
General purpose conversion calculator for the Psion Series 3a
                   Version 1.0

          Copyright (c) 1994 M.D. Nijdam

Email: marco@west.nl
Address: Kerklaan 7c
         NL-2283 CM  Rijswijk
         the Netherlands

======================================================================
Table of contents
----------------------------------------------------------------------

Disclaimer
The program and the name
Introduction
    Advantages over other conversion tools
    Disadvantages to other conversion tools
Running the program
    Getting started
    In the program
Other features
    Changing the database
    Doing arithmetics
    Changing the precision
    Changing the number notation
    Saving preferences as defaults
    Using number in Calc memory
    Storing result number in Calc memory
    Hints
    Exotics
Changing the database
    Database specification
    Entering Categories
    Setting defaults
    Restrictions
Translations
    Internationalization
    Translating helpfile
    Hints
OPL code
    Compiling
    Reusing
And Finally: Keep me informed


======================================================================
Disclaimer
----------------------------------------------------------------------

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

======================================================================
The program and the name
----------------------------------------------------------------------

JAICNV is short for "JAI Convert". It is a general purpose conversion
utility for the Psion 3a, that computes for you the conversion of a
number from one unit to another. It is general purpose because the
conversion rules are stored in a database that can be modified with
the Data tool on the Psion 3a. You can simply add more conversions.
More details on this lateron.

JAI is short for "Just An Idea". In French (written as J'ai) it also
means "I have", which might remind you of the famous speech by
Martin Luther King: "I have a dream". I my case it also means
"I have an idea".

======================================================================
Introduction
----------------------------------------------------------------------

Oh no, yet another conversion utility. Is it better than the other
hundred I've seen?

Of course my opinion is yes. Although the interface is simple, the
possibilities of this tool are almost endless. JAICNV can convert
any number into any other, given that there is a formula to do it.

    To name just a few possibilities:
    - length conversion from any unit to any other: inches, meters,
      kilometers, yards, miles, parsecs, etc. etc.
    - Similar for surface, volume, mass and speed units.
    - Temperature conversion, even degrees Celcius to Fahrenheit,
      which must be done with a formula and not with a factor.
    - Currency conversions for any currency
    - You can put your favourite formulas with one, or with some tricks
      even several, variables in this tool.

I've included a database with many units in the above areas and more.
And it is easy to add your own, or change existing ones. The latter
is important for currencies, because the rates can changes almost
dayly.

And that is not all. There is a two way interface with the Psion
calculator through its memories, which also allows you to copy
numbers to other applications, like Word, Data and Sheet.

Advantages over other conversion tools
=====================================================================

     - This is free software.
     - It is provided with source code.
     - Everything can be changed.
     - The program interface can be translated to different
       languages, without changing the source code.
     - It can accomodate for many conversion specifications in one
       database, which can be entered easily by the user.
       But it can also handle several databases.
     - Conversions are split by category, for easier selection.
     - Unneeded conversions can easily be deleted to save memory.
     - Two way interface with calculator
     - It is a calculator in itself; it can evaluate expressions
       with formulas.

Disadvantages to other conversion tools
=====================================================================

     - This is free software.
     - No warranty, no support.
     - Everything can be changed.


======================================================================
Running the program
----------------------------------------------------------------------

Getting started
======================================================================

Copy the following files:

     jaicnv.opa     to \app directory
     jaicnven.dbf   to \dat directory
     jaicnven.hlp   to \dat directory

Install the application with the Install option in the Apps menu on
the system screen.

Start the program by selecting the icon for the program and pressing
Enter.

Alternatively you could modify the OPL program to compile into an OPO,
by removing the APP definition section.


In the program
======================================================================

After starting the program you will see the disclaimer. Press Enter
and you will be on the opening screen. Here you can get help,
do some actions via the menu, or go to the main screen by
pressing Enter.

From the main screen you can return to the opening screen by
pressing Esc.

On the main screen you can select the conversion category, the
units and enter the values to be converted. To effectuate any
change you make you must press the Enter key. It is important in
which field you press Enter. E.g. if you are in the field for the
"From" value and press Enter, the "To" value is computed. If you
are in the "To" value field and press Enter, the From value is
computed.

     The names "From" and "To" are thus somewhat misleading
     because you can convert in both ways in most cases.
     The reason to keep it is that with an incomplete database
     not all conversions may be two way.

Initially some fields are protected. When you select a category
and press Enter in the category field, the unit fields are unprotected,
and when you select the units and press Enter in one of the unit
fields, the value fields are unprotected. When you later change the
category, it may happen that some fields are protected again.

Summary: Press Enter, again, and again and again.


======================================================================
Other features
----------------------------------------------------------------------

Changing the database
======================================================================

The default database used is the first database that matches the
filename "\dat\jaicnv*.dbf". However, you can select an other
database. How to create such a database is described lateron.

To change the database, go to the main screen (Press Enter on
the opening screen). The bottom item lets you select a (database)
file. Press Enter in the filename field when you have selected one
to open it.

The field works like other file selection field on the Psion.
So you can press Tab to get more control over the file selection.

See also section on "internationalization" elsewhere in this
document.


Doing arithmetics
======================================================================

On the value lines you can not only fill in values, you can enter
whole expressions. Of course you are limited to the length of the
line. If you press enter in the field with the expression, its
value is computed, and from it the other value using the
conversion formula. To get the value of the expression itself,
you must either select the same from and to unit, or
you must first compute the other value as described above, than
go to the other value field and press Enter.

If the expression is invalid an error will be given.

Expressions can be any valid OPL expression. This means they may
include +, -, *, /, **, %, (, ), OPL functions (like sin(), cos(),
tan(), pi, ln(), exp(), yes even rnd), Memories (M0 to M9), hexadecimal
numbers (e.g. $0D), etc.


Changing the precision
======================================================================

By default JAICNV shows values with 20 digits.
You can change the number of decimals and the width of the computed
number. On the opening screen press Menu and select the "Preferences"
option from the "Special" menu. Change the "Value width" to your taste
and press Enter to store it.

See also next section on number notation.


Changing the number notation
======================================================================

Also on the preferences (see Changing the precision) screen you
can change the notation used for numbers. Choose either

- scientific   : Scientific notation, with mantisse and exponent.
                 In this case you can also specify the number
                 of decimal digits.
- Fixed        : Fixed point notation. In this case you can also
                 specify the number of decimal digits
- Optimal      : Fixed when possible, otherwise scientific.
                 This is also the default at startup.
                 The number of decimal digits is ignored in this case.


Saving preferences as defaults
======================================================================

You can save the current preferences in the current database as
defaults. The next time you open the database, these settings
will be used.

To save the preferences, go to the opening screen, press Menu and
select the "Save preferences" item from the "Special" menu.

This also saves the current Calc memory in the database.


Using number in Calc memory
======================================================================

On the main screen, in one of the value fields, enter the name of
the memory in Calc. The name consists of the letter M and a
number from 0 to 9, like "m1".


Storing result number in Calc memory
======================================================================

On the opening screen select from the "Memory" menu the option
"Mx=From value" or "Mx=To value" to store the current From or To
value in the current memory (x is the memory number). If From
(or To) is actually an expression, it is first evaluated.

You can change the current Calc memory with the option "Change
memory" from the "Memory" menu.

NOTE: Be warned that this is a dangerous operation. Other
      programs (like Calc) might change the memory as well.
      Whichever value is stored last is kept.


Hints
======================================================================

- In each of the list fields (category, from unit and to unit)
  you can type in the first letter of a unit to quickly jump to
  it. If you press the letter again, it jumps to the next unit
  with the same starting letter, etc.
- If you want to do a conversion from (say) cubic nautical mile
  to cubic meter (which is not in the database), you could first
  go from nautical mile to meter, change From unit to meter,
  To unit to nautical mile, goto To value field (which is still
  reading "meter", and press Enter. The From value field (now
  reading "meter" contains the value.
- To convert from degrees to radian (not in the database yet),
  you can use the OPL function rad(): Choose the sam From and To
  units, enter in From value field "rad(123)" and press Enter.
  The To field contains the answer.


Exotics
======================================================================

You could make an entry in the database (see lateron on how to do
that) that has a conversion factor equal to or formula that uses
a Calc memory (or in formulas more than one memory).

   - This could be useful for conversions that change very
     quickly, like currencies. You just store the current value
     in the Calc memory and do your conversions.
   - It can also be used for "What if" conversions, like
     "What happens to the yield if the interest changes between
     a couple of values", where the interest can be stored in a
     memory, the input in one value field and the yield computed
     in another.
   - It is also possible to use this for formulas that require
     more than one variable.

In a formula you can use the filled in value several times.
See section on changing the database.

Bij using OPL functions you can do very complicated and
strange conversions. For example you can convert a difference
in time to a number of seconds using the following formule
(sic):

    datetosecs(1994,01,01,val(left$("xx",2)),val(mid$("xx",3,2)),
    val(mid$("xx",5,2)))-datetosecs(1994,01,01,val(mid$("xx",8,2)),
    val(mid$("xx",10,2)),val(mid$("xx",12,2)))

This assumes that the "value" you enter has the following
syntax: hhmmss-hhmmss. Here hh is hours, mm is minutes and
ss is seconds. For example, 120101-120002 would result
in 59 seconds.


======================================================================
Changing the database
----------------------------------------------------------------------

As indicated earlier, all conversion specifications are stored in
a database. This is a normal database that can be edited with the
standard Data program on the Psion 3a. All fields stored in it
are text fields, although some should represent values or
formulas.

The conversion specifications are split over categories. Each
category has a central unit. All conversions in a category must
convert either to or from the unit of the category. In this way
JAICNV is able to convert from any unit in a category to any
other, via the central unit. Still you only have to specify the
conversions only to one unit (the central), instead of to all
possible other units.


Database specification
======================================================================

The database consists of six fields:

- From unit
- To unit
                    These two specify the unit names that appear
                    in the unit selection lists on the main
                    screen.
                    One of them must always be the unit of the
                    category.
- Factor
                    The factor is a number (or a Calc memory
                    name) that specifies the factor to be applied
                    to go from the "From" to the "To" unit.
                    Because the conversion is a factor, JAICNV
                    will automatically be able to do the
                    conversion from "To" to "From" as well.
                    The factor must be empty if you want to
                    use a formula.
- Formula
                    If the conversion is different from a factor
                    (e.g. degrees Celcius to Fahrenheit) you
                    must enter the formula to go from "From" unit
                    to "To" unit. In this case if you want to go
                    from "To" to "From" you must make a separate
                    card in the database for this, with the
                    proper formula.
                    In the formula you can use the letters "xx"
                    to indicate the place where the "From" value
                    must be inserted (one "x" is not enough,
                    since you can use the OPL function "exp()"
                    in a formula). A formula can be a constant
                    (i.e. have no xx), but may also contain xx
                    several times (each one is replaced by the
                    filled in value).
                    A formula may contain OPL functions. Note
                    that the separator for function arguments
                    is also determined by the setting of default
                    "DecimalSign" (see further on).
- From description
- To description
                    These are more elaborate descriptions of the
                    units. In many cases it is the full name of
                    the unit, but it can be any text.
                    It is displayed before the value fields on
                    the main screen.
                    The description for the central unit can be
                    left empty, as it is ignored. The description
                    for the central unit is taken from the
                    category card (see below).

Entering Categories
======================================================================

A category is specified on a separate card, as follows:

- The "From unit" field must have the value "category:"
- The "To unit" field must have the unit name of the central
  unit.
- The Factor and Formula fields are ignored.
- The "From Description" field must contain the category name.
  This is used in the list of categories on the main screen.
- The "To description" field must contain the description for
  the central unit. This description is always used when you
  convert from or to the central unit.

Setting defaults
======================================================================

The database also contains some default values that you can
change. Each default is on a separate card, as follows:

- The "From unit" field must have the value "default:"
- The "To unit" field must have one of the special default
  keywords (see below)
- The factor and formula fields are ignored.
- The "From Description" field must contain the value for
  the default.
- The "To Description" field is ignored. It may contain some
  remarks on the values you can enter.

The following default keywords can be used:
- HelpFile               Path and filename of help file to use
* MemoryNr               Number of Calc memory (0-9)
* ValWidth               Total maximum output width of value
* ValPrecision           number of decimal digits to show/use
* Notation               1 (scientific), 2 (fixed), 3 (optimal)
- DecimalSign            One character: , or .
                         This also determines the separator for
                         function arguments: ";" resp. ",".

Some of these defaults can be changed inside Jaicnv, and saved
again to the database. These are indicated with a *.

Restrictions
======================================================================

Because of the way JAICNV is implemented, there are some
restrictions to the number of categories you can have, and the
number of units you can have in a category:

- The total length of all category names (in the "From
  Description" fields on the category cards) can not be larger
  than 255 minus the number of categories.
- The total length of all unit names for a category, that will
  appear in the From or To unit lists on the main screen can
  not be larger than 255 minus the number of units in the list.
  (Note that for conversions with a factor the unit will appear
  in both the From and To list).

JAICNV will warn you if these limits are exceeded.
From this perspective it is wise to keep unit names short, and
specify the full unit name in the description.

Also the following restrictions apply:

- Unit names can not be larger than 100 characters.
- Descriptions can not be larger than 100 characters.
     These two are not really important because such long names
     or descriptions would not fit on the screen anyway.
- Formulas can not be larger than 255 characters minus length of
  value
- Category and unit names may not contain kommas.


======================================================================
Translations
----------------------------------------------------------------------

Internationalization
======================================================================

Different countries may have different national units, and
possibly different names for the same unit.

     For example a "Nautical mile" in english has a Dutch
     translation as "zeemijl".

Because JAICNV uses a database for its units, and allows you to
select another database at runtime, it is possible to create
separate databases in different languages.

In the distribution I've included a database in Dutch (maybe
just a small niche market, but it is my native language).
The name in "jaicnvnl.dbf".

For complete language conversion you also have to translate
field names, menu options and help texts, as well as this manual.
The code is written in such a way that all texts are located
in the help database. Since this is also a normal Data database,
you can use Data to change it as well (see below).

One point of attention when dealing with different languages is
the sign for the decimal separator. In many languages it is a
dot ".", in some a comma ",", like in Dutch. Jaicnv works with
the one set for your Psion 3a.
In a database you can use either of the two, but whichever you
choose, you must use it consistently within the database. By default
Jaicnv assumes numbers in the database contain a dot as decimal
separator. You must set the default "DecimalSign" in the database
to "," if you are using a "," as decimal separator (see section
on setting defaults).
It is recommended to also set this default explicitly to "."
in the database if you are using that (instead of trusting the
hardcoded default).
The DecimalSign default also determines how function arguments
in a formula have to be separated: using ";" or ",".

Translating helpfile
======================================================================

The help file is a normal database, that can be edited with the
Data application on your Psion 3a. It contains several items:

- Texts for help (and for the disclaimer screen).
  Each help item is on one card. A maximum of 8 help items
  (cards) is allowed. Each card can have at most 8 lines of
  text.
- Texts for the menus.
  Each menu is on one card. It has a fixed name to identify it.
  The items in the menu are on the card as well, one per line,
  in a fixed order. Look at an existing help database for this
  order.
- Texts for the panels.
  For each panel there is one card. Like menus it has a fixed
  name for identification, and the items on the lines are in a
  fixed order.
  For some fields on a panel, there is also a list of allowed
  values (whose order is also fixed). An example is the list
  of notations on the preferences panel.
- Error messages
  Each error message is on one card. It has a fixed name to
  identify it (so do not translate that). An error message
  can be one or two lines long.
  Some error messages expect variable text to be filled in at
  runtime. The message must contain the placeholders for this.
  With one variable the placeholder is "%s1", with two they
  are "%s1" and "%s2". You must include the correct number
  of placeholders in the message. They can be on either of the
  two lines, and in any order (if there are two).
- Strings
  One string per card, fixed names, string value in field "Msg".

The help database contains the following fields in a record:
- Type:   must contain one of the strings "help:", "menu:",
          "panel: fatal", "error:", "string:"
          "help: disclaimer" is used for the disclaimer.
- Name:   Item string (for help) or one of a set of fixed names
          (for others)
- Msg:    First line (for help or error), menu name, panel title,
          string value
- Line1:  Second line (for help or error), menu item, panel item
- Line2..Line8: Following lines (for help), menu item, panel item

Hints
======================================================================

To do a full translation, I find it easier to save the database
in ascii format, with new line as field separator, edit the
resulting file on the PC, and joining it with an empty database.

Be careful about the editor you use on the PC however. Empty
fields are specified with a line containing one space. Records
are separated by an empty line. If your editor strips spaces at
the end of the line you will be in BIG problems.

You can use any available international and scientific characters
in the database. It seems that these characters are the same on
the PC and the Psion.


======================================================================
OPL code
----------------------------------------------------------------------

Compiling
======================================================================

If you want to compile the OPL code into an OPA, you must put the
file
     jaicnv.pic
in directory
     \pic
(or change the source code).

Reusing
======================================================================

You may find the concepts of internationalization, help and
others interesting. Since the source code is provided in the
package you can reuse the code for those concepts.

HOWEVER, THE PROGRAM AND THE CODE FALL UNDER THE TERMS OF THE GNU
GENERAL PUBLIC LICENSE. READ IT BEFORE YOU REUSE ANY CODE. IT IS
CONTAINED IN THE FILE COPYING.GPL.

One of the rules imply that the software you create with this
software must be free again, under the same GNU GPL terms.
I also ask you to acknowledge me as the author of the reused
code.

If you want to reuse code in a program that is distributed under
other terms, write me.


======================================================================
And Finally: Keep me informed
----------------------------------------------------------------------

As this is free software, and I provide both source code and
customization via a database, you can freely make any changes
(but observe the rules described in the GNU public licence
agreement, which I have also included in this distribution).

Whenever you make a database with useful conversions, or
translate a database to a different language, when you make
useful changes or additions to the program please let me know
about it.

Also when you have remarks, find bugs, have ideas on further
enhancement let me know.

My email and surface mail addresses are at the top of this
document.

