PDA Software Library

home *** CD-ROM | disk | FTP | other *** search

/ PDA Software Library / pdasoftwarelib.iso / PSION / MISC / JAICNV / JAICNVEN.TXT < prev next >

Wrap

Text File | 1994-08-14 | 26.4 KB | 663 lines

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.