home *** CD-ROM | disk | FTP | other *** search
/ Boot Disc 8 / boot-disc-1997-04.iso / PDA_Soft / Psion / misc / Jaicnv / JAICNVEN.TXT < prev    next >
Text File  |  1994-08-14  |  27KB  |  663 lines
  1.  
  2. General purpose conversion calculator for the Psion Series 3a
  3.                    Version 1.0
  4.  
  5.           Copyright (c) 1994 M.D. Nijdam
  6.  
  7. Email: marco@west.nl
  8. Address: Kerklaan 7c
  9.          NL-2283 CM  Rijswijk
  10.          the Netherlands
  11.  
  12. ======================================================================
  13. Table of contents
  14. ----------------------------------------------------------------------
  15.  
  16. Disclaimer
  17. The program and the name
  18. Introduction
  19.     Advantages over other conversion tools
  20.     Disadvantages to other conversion tools
  21. Running the program
  22.     Getting started
  23.     In the program
  24. Other features
  25.     Changing the database
  26.     Doing arithmetics
  27.     Changing the precision
  28.     Changing the number notation
  29.     Saving preferences as defaults
  30.     Using number in Calc memory
  31.     Storing result number in Calc memory
  32.     Hints
  33.     Exotics
  34. Changing the database
  35.     Database specification
  36.     Entering Categories
  37.     Setting defaults
  38.     Restrictions
  39. Translations
  40.     Internationalization
  41.     Translating helpfile
  42.     Hints
  43. OPL code
  44.     Compiling
  45.     Reusing
  46. And Finally: Keep me informed
  47.  
  48.  
  49. ======================================================================
  50. Disclaimer
  51. ----------------------------------------------------------------------
  52.  
  53. This program is free software; you can redistribute it and/or modify
  54. it under the terms of the GNU General Public License as published by
  55. the Free Software Foundation; either version 1, or (at your option)
  56. any later version.
  57.  
  58. This program is distributed in the hope that it will be useful,
  59. but WITHOUT ANY WARRANTY; without even the implied warranty of
  60. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  61. GNU General Public License for more details.
  62.  
  63. You should have received a copy of the GNU General Public License
  64. along with this program; if not, write to the Free Software
  65. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  66.  
  67. ======================================================================
  68. The program and the name
  69. ----------------------------------------------------------------------
  70.  
  71. JAICNV is short for "JAI Convert". It is a general purpose conversion
  72. utility for the Psion 3a, that computes for you the conversion of a
  73. number from one unit to another. It is general purpose because the
  74. conversion rules are stored in a database that can be modified with
  75. the Data tool on the Psion 3a. You can simply add more conversions.
  76. More details on this lateron.
  77.  
  78. JAI is short for "Just An Idea". In French (written as J'ai) it also
  79. means "I have", which might remind you of the famous speech by
  80. Martin Luther King: "I have a dream". I my case it also means
  81. "I have an idea".
  82.  
  83. ======================================================================
  84. Introduction
  85. ----------------------------------------------------------------------
  86.  
  87. Oh no, yet another conversion utility. Is it better than the other
  88. hundred I've seen?
  89.  
  90. Of course my opinion is yes. Although the interface is simple, the
  91. possibilities of this tool are almost endless. JAICNV can convert
  92. any number into any other, given that there is a formula to do it.
  93.  
  94.     To name just a few possibilities:
  95.     - length conversion from any unit to any other: inches, meters,
  96.       kilometers, yards, miles, parsecs, etc. etc.
  97.     - Similar for surface, volume, mass and speed units.
  98.     - Temperature conversion, even degrees Celcius to Fahrenheit,
  99.       which must be done with a formula and not with a factor.
  100.     - Currency conversions for any currency
  101.     - You can put your favourite formulas with one, or with some tricks
  102.       even several, variables in this tool.
  103.  
  104. I've included a database with many units in the above areas and more.
  105. And it is easy to add your own, or change existing ones. The latter
  106. is important for currencies, because the rates can changes almost
  107. dayly.
  108.  
  109. And that is not all. There is a two way interface with the Psion
  110. calculator through its memories, which also allows you to copy
  111. numbers to other applications, like Word, Data and Sheet.
  112.  
  113. Advantages over other conversion tools
  114. =====================================================================
  115.  
  116.      - This is free software.
  117.      - It is provided with source code.
  118.      - Everything can be changed.
  119.      - The program interface can be translated to different
  120.        languages, without changing the source code.
  121.      - It can accomodate for many conversion specifications in one
  122.        database, which can be entered easily by the user.
  123.        But it can also handle several databases.
  124.      - Conversions are split by category, for easier selection.
  125.      - Unneeded conversions can easily be deleted to save memory.
  126.      - Two way interface with calculator
  127.      - It is a calculator in itself; it can evaluate expressions
  128.        with formulas.
  129.  
  130. Disadvantages to other conversion tools
  131. =====================================================================
  132.  
  133.      - This is free software.
  134.      - No warranty, no support.
  135.      - Everything can be changed.
  136.  
  137.  
  138. ======================================================================
  139. Running the program
  140. ----------------------------------------------------------------------
  141.  
  142. Getting started
  143. ======================================================================
  144.  
  145. Copy the following files:
  146.  
  147.      jaicnv.opa     to \app directory
  148.      jaicnven.dbf   to \dat directory
  149.      jaicnven.hlp   to \dat directory
  150.  
  151. Install the application with the Install option in the Apps menu on
  152. the system screen.
  153.  
  154. Start the program by selecting the icon for the program and pressing
  155. Enter.
  156.  
  157. Alternatively you could modify the OPL program to compile into an OPO,
  158. by removing the APP definition section.
  159.  
  160.  
  161. In the program
  162. ======================================================================
  163.  
  164. After starting the program you will see the disclaimer. Press Enter
  165. and you will be on the opening screen. Here you can get help,
  166. do some actions via the menu, or go to the main screen by
  167. pressing Enter.
  168.  
  169. From the main screen you can return to the opening screen by
  170. pressing Esc.
  171.  
  172. On the main screen you can select the conversion category, the
  173. units and enter the values to be converted. To effectuate any
  174. change you make you must press the Enter key. It is important in
  175. which field you press Enter. E.g. if you are in the field for the
  176. "From" value and press Enter, the "To" value is computed. If you
  177. are in the "To" value field and press Enter, the From value is
  178. computed.
  179.  
  180.      The names "From" and "To" are thus somewhat misleading
  181.      because you can convert in both ways in most cases.
  182.      The reason to keep it is that with an incomplete database
  183.      not all conversions may be two way.
  184.  
  185. Initially some fields are protected. When you select a category
  186. and press Enter in the category field, the unit fields are unprotected,
  187. and when you select the units and press Enter in one of the unit
  188. fields, the value fields are unprotected. When you later change the
  189. category, it may happen that some fields are protected again.
  190.  
  191. Summary: Press Enter, again, and again and again.
  192.  
  193.  
  194. ======================================================================
  195. Other features
  196. ----------------------------------------------------------------------
  197.  
  198. Changing the database
  199. ======================================================================
  200.  
  201. The default database used is the first database that matches the
  202. filename "\dat\jaicnv*.dbf". However, you can select an other
  203. database. How to create such a database is described lateron.
  204.  
  205. To change the database, go to the main screen (Press Enter on
  206. the opening screen). The bottom item lets you select a (database)
  207. file. Press Enter in the filename field when you have selected one
  208. to open it.
  209.  
  210. The field works like other file selection field on the Psion.
  211. So you can press Tab to get more control over the file selection.
  212.  
  213. See also section on "internationalization" elsewhere in this
  214. document.
  215.  
  216.  
  217. Doing arithmetics
  218. ======================================================================
  219.  
  220. On the value lines you can not only fill in values, you can enter
  221. whole expressions. Of course you are limited to the length of the
  222. line. If you press enter in the field with the expression, its
  223. value is computed, and from it the other value using the
  224. conversion formula. To get the value of the expression itself,
  225. you must either select the same from and to unit, or
  226. you must first compute the other value as described above, than
  227. go to the other value field and press Enter.
  228.  
  229. If the expression is invalid an error will be given.
  230.  
  231. Expressions can be any valid OPL expression. This means they may
  232. include +, -, *, /, **, %, (, ), OPL functions (like sin(), cos(),
  233. tan(), pi, ln(), exp(), yes even rnd), Memories (M0 to M9), hexadecimal
  234. numbers (e.g. $0D), etc.
  235.  
  236.  
  237. Changing the precision
  238. ======================================================================
  239.  
  240. By default JAICNV shows values with 20 digits.
  241. You can change the number of decimals and the width of the computed
  242. number. On the opening screen press Menu and select the "Preferences"
  243. option from the "Special" menu. Change the "Value width" to your taste
  244. and press Enter to store it.
  245.  
  246. See also next section on number notation.
  247.  
  248.  
  249. Changing the number notation
  250. ======================================================================
  251.  
  252. Also on the preferences (see Changing the precision) screen you
  253. can change the notation used for numbers. Choose either
  254.  
  255. - scientific   : Scientific notation, with mantisse and exponent.
  256.                  In this case you can also specify the number
  257.                  of decimal digits.
  258. - Fixed        : Fixed point notation. In this case you can also
  259.                  specify the number of decimal digits
  260. - Optimal      : Fixed when possible, otherwise scientific.
  261.                  This is also the default at startup.
  262.                  The number of decimal digits is ignored in this case.
  263.  
  264.  
  265. Saving preferences as defaults
  266. ======================================================================
  267.  
  268. You can save the current preferences in the current database as
  269. defaults. The next time you open the database, these settings
  270. will be used.
  271.  
  272. To save the preferences, go to the opening screen, press Menu and
  273. select the "Save preferences" item from the "Special" menu.
  274.  
  275. This also saves the current Calc memory in the database.
  276.  
  277.  
  278. Using number in Calc memory
  279. ======================================================================
  280.  
  281. On the main screen, in one of the value fields, enter the name of
  282. the memory in Calc. The name consists of the letter M and a
  283. number from 0 to 9, like "m1".
  284.  
  285.  
  286. Storing result number in Calc memory
  287. ======================================================================
  288.  
  289. On the opening screen select from the "Memory" menu the option
  290. "Mx=From value" or "Mx=To value" to store the current From or To
  291. value in the current memory (x is the memory number). If From
  292. (or To) is actually an expression, it is first evaluated.
  293.  
  294. You can change the current Calc memory with the option "Change
  295. memory" from the "Memory" menu.
  296.  
  297. NOTE: Be warned that this is a dangerous operation. Other
  298.       programs (like Calc) might change the memory as well.
  299.       Whichever value is stored last is kept.
  300.  
  301.  
  302. Hints
  303. ======================================================================
  304.  
  305. - In each of the list fields (category, from unit and to unit)
  306.   you can type in the first letter of a unit to quickly jump to
  307.   it. If you press the letter again, it jumps to the next unit
  308.   with the same starting letter, etc.
  309. - If you want to do a conversion from (say) cubic nautical mile
  310.   to cubic meter (which is not in the database), you could first
  311.   go from nautical mile to meter, change From unit to meter,
  312.   To unit to nautical mile, goto To value field (which is still
  313.   reading "meter", and press Enter. The From value field (now
  314.   reading "meter" contains the value.
  315. - To convert from degrees to radian (not in the database yet),
  316.   you can use the OPL function rad(): Choose the sam From and To
  317.   units, enter in From value field "rad(123)" and press Enter.
  318.   The To field contains the answer.
  319.  
  320.  
  321. Exotics
  322. ======================================================================
  323.  
  324. You could make an entry in the database (see lateron on how to do
  325. that) that has a conversion factor equal to or formula that uses
  326. a Calc memory (or in formulas more than one memory).
  327.  
  328.    - This could be useful for conversions that change very
  329.      quickly, like currencies. You just store the current value
  330.      in the Calc memory and do your conversions.
  331.    - It can also be used for "What if" conversions, like
  332.      "What happens to the yield if the interest changes between
  333.      a couple of values", where the interest can be stored in a
  334.      memory, the input in one value field and the yield computed
  335.      in another.
  336.    - It is also possible to use this for formulas that require
  337.      more than one variable.
  338.  
  339. In a formula you can use the filled in value several times.
  340. See section on changing the database.
  341.  
  342. Bij using OPL functions you can do very complicated and
  343. strange conversions. For example you can convert a difference
  344. in time to a number of seconds using the following formule
  345. (sic):
  346.  
  347.     datetosecs(1994,01,01,val(left$("xx",2)),val(mid$("xx",3,2)),
  348.     val(mid$("xx",5,2)))-datetosecs(1994,01,01,val(mid$("xx",8,2)),
  349.     val(mid$("xx",10,2)),val(mid$("xx",12,2)))
  350.  
  351. This assumes that the "value" you enter has the following
  352. syntax: hhmmss-hhmmss. Here hh is hours, mm is minutes and
  353. ss is seconds. For example, 120101-120002 would result
  354. in 59 seconds.
  355.  
  356.  
  357. ======================================================================
  358. Changing the database
  359. ----------------------------------------------------------------------
  360.  
  361. As indicated earlier, all conversion specifications are stored in
  362. a database. This is a normal database that can be edited with the
  363. standard Data program on the Psion 3a. All fields stored in it
  364. are text fields, although some should represent values or
  365. formulas.
  366.  
  367. The conversion specifications are split over categories. Each
  368. category has a central unit. All conversions in a category must
  369. convert either to or from the unit of the category. In this way
  370. JAICNV is able to convert from any unit in a category to any
  371. other, via the central unit. Still you only have to specify the
  372. conversions only to one unit (the central), instead of to all
  373. possible other units.
  374.  
  375.  
  376. Database specification
  377. ======================================================================
  378.  
  379. The database consists of six fields:
  380.  
  381. - From unit
  382. - To unit
  383.                     These two specify the unit names that appear
  384.                     in the unit selection lists on the main
  385.                     screen.
  386.                     One of them must always be the unit of the
  387.                     category.
  388. - Factor
  389.                     The factor is a number (or a Calc memory
  390.                     name) that specifies the factor to be applied
  391.                     to go from the "From" to the "To" unit.
  392.                     Because the conversion is a factor, JAICNV
  393.                     will automatically be able to do the
  394.                     conversion from "To" to "From" as well.
  395.                     The factor must be empty if you want to
  396.                     use a formula.
  397. - Formula
  398.                     If the conversion is different from a factor
  399.                     (e.g. degrees Celcius to Fahrenheit) you
  400.                     must enter the formula to go from "From" unit
  401.                     to "To" unit. In this case if you want to go
  402.                     from "To" to "From" you must make a separate
  403.                     card in the database for this, with the
  404.                     proper formula.
  405.                     In the formula you can use the letters "xx"
  406.                     to indicate the place where the "From" value
  407.                     must be inserted (one "x" is not enough,
  408.                     since you can use the OPL function "exp()"
  409.                     in a formula). A formula can be a constant
  410.                     (i.e. have no xx), but may also contain xx
  411.                     several times (each one is replaced by the
  412.                     filled in value).
  413.                     A formula may contain OPL functions. Note
  414.                     that the separator for function arguments
  415.                     is also determined by the setting of default
  416.                     "DecimalSign" (see further on).
  417. - From description
  418. - To description
  419.                     These are more elaborate descriptions of the
  420.                     units. In many cases it is the full name of
  421.                     the unit, but it can be any text.
  422.                     It is displayed before the value fields on
  423.                     the main screen.
  424.                     The description for the central unit can be
  425.                     left empty, as it is ignored. The description
  426.                     for the central unit is taken from the
  427.                     category card (see below).
  428.  
  429. Entering Categories
  430. ======================================================================
  431.  
  432. A category is specified on a separate card, as follows:
  433.  
  434. - The "From unit" field must have the value "category:"
  435. - The "To unit" field must have the unit name of the central
  436.   unit.
  437. - The Factor and Formula fields are ignored.
  438. - The "From Description" field must contain the category name.
  439.   This is used in the list of categories on the main screen.
  440. - The "To description" field must contain the description for
  441.   the central unit. This description is always used when you
  442.   convert from or to the central unit.
  443.  
  444. Setting defaults
  445. ======================================================================
  446.  
  447. The database also contains some default values that you can
  448. change. Each default is on a separate card, as follows:
  449.  
  450. - The "From unit" field must have the value "default:"
  451. - The "To unit" field must have one of the special default
  452.   keywords (see below)
  453. - The factor and formula fields are ignored.
  454. - The "From Description" field must contain the value for
  455.   the default.
  456. - The "To Description" field is ignored. It may contain some
  457.   remarks on the values you can enter.
  458.  
  459. The following default keywords can be used:
  460. - HelpFile               Path and filename of help file to use
  461. * MemoryNr               Number of Calc memory (0-9)
  462. * ValWidth               Total maximum output width of value
  463. * ValPrecision           number of decimal digits to show/use
  464. * Notation               1 (scientific), 2 (fixed), 3 (optimal)
  465. - DecimalSign            One character: , or .
  466.                          This also determines the separator for
  467.                          function arguments: ";" resp. ",".
  468.  
  469. Some of these defaults can be changed inside Jaicnv, and saved
  470. again to the database. These are indicated with a *.
  471.  
  472. Restrictions
  473. ======================================================================
  474.  
  475. Because of the way JAICNV is implemented, there are some
  476. restrictions to the number of categories you can have, and the
  477. number of units you can have in a category:
  478.  
  479. - The total length of all category names (in the "From
  480.   Description" fields on the category cards) can not be larger
  481.   than 255 minus the number of categories.
  482. - The total length of all unit names for a category, that will
  483.   appear in the From or To unit lists on the main screen can
  484.   not be larger than 255 minus the number of units in the list.
  485.   (Note that for conversions with a factor the unit will appear
  486.   in both the From and To list).
  487.  
  488. JAICNV will warn you if these limits are exceeded.
  489. From this perspective it is wise to keep unit names short, and
  490. specify the full unit name in the description.
  491.  
  492. Also the following restrictions apply:
  493.  
  494. - Unit names can not be larger than 100 characters.
  495. - Descriptions can not be larger than 100 characters.
  496.      These two are not really important because such long names
  497.      or descriptions would not fit on the screen anyway.
  498. - Formulas can not be larger than 255 characters minus length of
  499.   value
  500. - Category and unit names may not contain kommas.
  501.  
  502.  
  503. ======================================================================
  504. Translations
  505. ----------------------------------------------------------------------
  506.  
  507. Internationalization
  508. ======================================================================
  509.  
  510. Different countries may have different national units, and
  511. possibly different names for the same unit.
  512.  
  513.      For example a "Nautical mile" in english has a Dutch
  514.      translation as "zeemijl".
  515.  
  516. Because JAICNV uses a database for its units, and allows you to
  517. select another database at runtime, it is possible to create
  518. separate databases in different languages.
  519.  
  520. In the distribution I've included a database in Dutch (maybe
  521. just a small niche market, but it is my native language).
  522. The name in "jaicnvnl.dbf".
  523.  
  524. For complete language conversion you also have to translate
  525. field names, menu options and help texts, as well as this manual.
  526. The code is written in such a way that all texts are located
  527. in the help database. Since this is also a normal Data database,
  528. you can use Data to change it as well (see below).
  529.  
  530. One point of attention when dealing with different languages is
  531. the sign for the decimal separator. In many languages it is a
  532. dot ".", in some a comma ",", like in Dutch. Jaicnv works with
  533. the one set for your Psion 3a.
  534. In a database you can use either of the two, but whichever you
  535. choose, you must use it consistently within the database. By default
  536. Jaicnv assumes numbers in the database contain a dot as decimal
  537. separator. You must set the default "DecimalSign" in the database
  538. to "," if you are using a "," as decimal separator (see section
  539. on setting defaults).
  540. It is recommended to also set this default explicitly to "."
  541. in the database if you are using that (instead of trusting the
  542. hardcoded default).
  543. The DecimalSign default also determines how function arguments
  544. in a formula have to be separated: using ";" or ",".
  545.  
  546. Translating helpfile
  547. ======================================================================
  548.  
  549. The help file is a normal database, that can be edited with the
  550. Data application on your Psion 3a. It contains several items:
  551.  
  552. - Texts for help (and for the disclaimer screen).
  553.   Each help item is on one card. A maximum of 8 help items
  554.   (cards) is allowed. Each card can have at most 8 lines of
  555.   text.
  556. - Texts for the menus.
  557.   Each menu is on one card. It has a fixed name to identify it.
  558.   The items in the menu are on the card as well, one per line,
  559.   in a fixed order. Look at an existing help database for this
  560.   order.
  561. - Texts for the panels.
  562.   For each panel there is one card. Like menus it has a fixed
  563.   name for identification, and the items on the lines are in a
  564.   fixed order.
  565.   For some fields on a panel, there is also a list of allowed
  566.   values (whose order is also fixed). An example is the list
  567.   of notations on the preferences panel.
  568. - Error messages
  569.   Each error message is on one card. It has a fixed name to
  570.   identify it (so do not translate that). An error message
  571.   can be one or two lines long.
  572.   Some error messages expect variable text to be filled in at
  573.   runtime. The message must contain the placeholders for this.
  574.   With one variable the placeholder is "%s1", with two they
  575.   are "%s1" and "%s2". You must include the correct number
  576.   of placeholders in the message. They can be on either of the
  577.   two lines, and in any order (if there are two).
  578. - Strings
  579.   One string per card, fixed names, string value in field "Msg".
  580.  
  581. The help database contains the following fields in a record:
  582. - Type:   must contain one of the strings "help:", "menu:",
  583.           "panel: fatal", "error:", "string:"
  584.           "help: disclaimer" is used for the disclaimer.
  585. - Name:   Item string (for help) or one of a set of fixed names
  586.           (for others)
  587. - Msg:    First line (for help or error), menu name, panel title,
  588.           string value
  589. - Line1:  Second line (for help or error), menu item, panel item
  590. - Line2..Line8: Following lines (for help), menu item, panel item
  591.  
  592. Hints
  593. ======================================================================
  594.  
  595. To do a full translation, I find it easier to save the database
  596. in ascii format, with new line as field separator, edit the
  597. resulting file on the PC, and joining it with an empty database.
  598.  
  599. Be careful about the editor you use on the PC however. Empty
  600. fields are specified with a line containing one space. Records
  601. are separated by an empty line. If your editor strips spaces at
  602. the end of the line you will be in BIG problems.
  603.  
  604. You can use any available international and scientific characters
  605. in the database. It seems that these characters are the same on
  606. the PC and the Psion.
  607.  
  608.  
  609. ======================================================================
  610. OPL code
  611. ----------------------------------------------------------------------
  612.  
  613. Compiling
  614. ======================================================================
  615.  
  616. If you want to compile the OPL code into an OPA, you must put the
  617. file
  618.      jaicnv.pic
  619. in directory
  620.      \pic
  621. (or change the source code).
  622.  
  623. Reusing
  624. ======================================================================
  625.  
  626. You may find the concepts of internationalization, help and
  627. others interesting. Since the source code is provided in the
  628. package you can reuse the code for those concepts.
  629.  
  630. HOWEVER, THE PROGRAM AND THE CODE FALL UNDER THE TERMS OF THE GNU
  631. GENERAL PUBLIC LICENSE. READ IT BEFORE YOU REUSE ANY CODE. IT IS
  632. CONTAINED IN THE FILE COPYING.GPL.
  633.  
  634. One of the rules imply that the software you create with this
  635. software must be free again, under the same GNU GPL terms.
  636. I also ask you to acknowledge me as the author of the reused
  637. code.
  638.  
  639. If you want to reuse code in a program that is distributed under
  640. other terms, write me.
  641.  
  642.  
  643. ======================================================================
  644. And Finally: Keep me informed
  645. ----------------------------------------------------------------------
  646.  
  647. As this is free software, and I provide both source code and
  648. customization via a database, you can freely make any changes
  649. (but observe the rules described in the GNU public licence
  650. agreement, which I have also included in this distribution).
  651.  
  652. Whenever you make a database with useful conversions, or
  653. translate a database to a different language, when you make
  654. useful changes or additions to the program please let me know
  655. about it.
  656.  
  657. Also when you have remarks, find bugs, have ideas on further
  658. enhancement let me know.
  659.  
  660. My email and surface mail addresses are at the top of this
  661. document.
  662.  
  663.