XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  Unitman  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

       A flexible unit manager for the HP49G  -  integrates and removes 
         units and their directories in the builtin UNITS menu system  
----------------------------------------------------------------------
Unitman is a one-page library whose most important first four commands will be
explained in examples. Thanks to a powerful machinery, each user-defined unit
can appear in a builtin UDir and is treated like a builtin unit. The menu can
completely be reorganized by the command roUM, i.e., units can be reordered,
some dispensable units removed or perhaps renamed. roUD reorganzes the whole
UNITS directory system. It expands itself by a UDir for converting currencies.
New Unit Dirs may be added ad libitum. The famous 3-fold functionality of unit
keys known from the 48 (Remark 1 below) works for user-defined units as well.
Most Unitman commands set the 49 to RPN. There is no smart unit management in
algebraic mode. Unitman commands also set the USR and the soft-menu mode, to
operate properly. Assign << 359 MENU >> to the rightshift-hold UNITS key. We
need the Unitman commands permanently in the examples below. 
DelUK deletes the
automatically generated assignment at the UNITS key 84.3 and puts it in the
stack, for compression or later reassignment. 
---------------------------------------------------------------------
NEW IN VERSION 1.2003
A html-document has been added which is a revised version of this
text-file. There is also a German html-version on the author's site. 

NEW IN VERSION 1.2002 
Since Unitman becomes more important in the EURO-age this text has thoroughly
been revised. 

NEW IN VERSION 9.2001 
minor change in ROMPTR 167 D (the only one occurring now in the assignment).
No change in functionality.

NEW IN VERSION 8.2001
Command Upgrd replaced by DelUK (deletes any UNITS-key assignment). It should 
be deleted if made by previous versions. Previously defined units need not be
redefined. It suffices to put them back into their categories with AddU in a
list. A UNITS-key assignment made by version 8.2001 doesn't contain unstable
pointers anymore and should work for all ROM versions from 1.19-3 on. 
---------------------------------------------------------------------
1. Let's first define the currency EURO in the new MONEY dir which contains
only the (US)$ after a first run of AddU or by pressing ExpU (Expand Units
system). ExpU is imported by AddU and other commands. Simply press AddU and
fill in the AddU dialog box after scrolling in the name MONEY with CHOOSE in
the dialog menu:
                 
                    XXXXXXXXXX Add a Unit XXXXXXXXXX
                    UnitDir       MONEY             
                    UnitName      "EUR"             
                    Define        1.02_$             
                    
EUR may be printed as it stands, but better you choose the EURO-symbol which
is on ALPHA Rigthshift 4. A unit name *must* be entered as a string because it
may be a illegal global name, kg/mm^2 say. Define must be answered here since
EUR is not known to the HP49 as a unit name. The Define field accepts units
only. These generally have a real before the "_". Finally, press OK and EUR
will appear in MONEY! Any amount of Dollars is now easily converted to EUR and
conversely. EXAMPLE: Print 100, press EUR and then leftshift $. This results
in 102_$. Both $ and EUR now appear as names in HOME (provided the example is
executed in HOME). One may hide these small unit-files lateron.

2. Next, we want the important unit ms (millisecond) to appear in TIME. In 
this example the dialog box is already filled in and should look as follows: 

                    XXXXXXXXXX Add a Unit XXXXXXXXXX
                    UnitDir       TIME
                    UnitName      "ms" 
                    Define        (can be skipped, need not be filled in!)       

The Define-option may safely be skipped because the system knows the prefix m
and the unit s and hence ms, although a unit name ms does not show up in the 
builtin TIME menu. With AddU, we just forced it to appear! Generally, units 
deriving from existing unit names by prefixing with D (Deco), h (hecto), ...
or d (deci) m (milli), ... as listed in the manual, are known to CONVERT and 
other commands, even if not occurring in the builtin menus. Nothing is written
in the HOME directory in such a case. Unitname also accept a list of strings,
all of which should be defined unitnames (either builtin or user-defined in a
previous version of Unitman, say). E.g., after creating the extra page for 
frequency units in the next example, one may add { "KHz" "rpm" } to the page 
of frequencies. Both units are known to the 49 but don't show up in a builtin 
menu. We have the equation 100_Hz = 6000_rpm (revolutions per minute).

3. The order of the present TIME menu is somewhat unpleasant. It seems better  
to open an extra page for frequency units like Hz, MHz etc. This can be done
with roUM. Press roUM, set the UDir TIME and press OK. That creates a special
stack (similar to the interactive stack) which looks as follows:

7:      yr
6:      d                   
5:      h                   This is a copy of the current 
4:      min                 TIME menu with "ms" already added. 
3:      s                   String quoters are here omitted.
2:      Hz                  
1:      ms                  (the initial cursor position).

Now move the cursor to Hz and press ROLL which rolls Hz to position 1. The new
TIME menu will have yr, d, h, min, s, ms on page 1, and Hz on page 2. Finally,
press ENTER or ON to leave the stack and convince yourself by visiting TIME. 
In the special stack one may use ROLL and ROLLD to reorder, the backspace key
for deleting (e.g, "st" in VOL, 1_st equals 1_m^3) and EDIT to rename an item
(e.g., kW to KW which means the same). ATTENTION: The special stack cannot be
aborted! Program execution continues whether ENTER or CANCEL is pressed. Hence
take care when making changes. You may also create a new frequency directory,
FREQ, say. Very useful if more frequency or time units are needed, e.g., the
internal clock tic (1_s = 8192_tic).

4. We want to add another UDir, named InfU (Informatic Units), say. Simply 
press AddUD, write InfU (as a string) into the black field and press OK. That
appends InfU to the unit dirs, first without any unit. These may be defined
with AddU as follows:  1_bit = 1_$, 1_byte = 8_bit, 1_Kbyte = 1024_byte, etc.
One should not jump over the Define-field for Kbyte after the byte-unit has
been created, because the HP49 would then think 1_Kbyte equals 1000 bytes!

5. Some people may want to have the UDir MONEY at the first place. No problem. 
Simply press roUDs (reorganize UDirs). This immediately creates a stack with 
all current UDirs. Now you may reorder with ROLL and ROLLD as in Example 3, in
our example by just pressing ROLLD on LEN, and we are done. You may remove a 
UDir with backspace, e.g. RAD, if you never deal with radiation. Only renaming
is a bit more involved. Let's consider an example. A German may want to rename
the UDir TIME into ZEIT. We press the EDIT option, with the cursor on "TIME".
That edits the string "TIME". Now we add the new name ZEIT as follows:
                                 "TIME
                                  ZEIT"
It is important here to have the old name and the new name in just one string, 
but on different lines, with no blanks before or after the names. Leave the 
editor with ENTER and return to the special stack environement. Then ENTER and
TIME has indeed been renamed into ZEIT. Also an US-user may try this example
without risking anything. Just rename ZEIT once again back to TIME.  
----------------------------------------------------------------------
You may purge all units you're not pleased with, e.g, miUS^2. The operating 
system still remembers them. One should not hesitate to remove any unwanted 
unit. It is not lost. If you want temporarily the builtin units, leave the
USR mode. However, if you purge a whole unit directory and you want it back
you have to recreate it step by step. This holds for the MONEY directory as
well which, for speed reason, is created by ExpU only at the very beginning.
UNITS customization is active in USR mode only. DelUK completely purges the
the customization and everything is lost if you don't save the assignment at
the UNITS key before, best in Port2. Unitman may also be combined with the
library UTOOL which supports Unitman.
---------------------------------------------------------------------
REMARK 1. User-defined units integrated in UNITS operate in the same manner 
as builtin units. A unit key acts in RPN mode as follows - for details see 
Chapter 10 of the HP48 (!) manual. It is not explained in the HP49 docs:

Nonshift:  Appends (or multiplies) the unit to the object in Level 1. E.g., 
           if 10 is on the stack then the $-key in MONEY yields 10_$.
Leftshift: Converts. E.g., if EUR appears in MONEY (see above) then pressing 
           leftshift EUR applied to 10_$ in the stack yields 9.80..._EUR.
Righshift: Divides. Rightshift $ applied to 100_Hz leaves 100 in the stack.
           Rightshift s "converts" 100 from the stack into 100_1/s = 100_Hz.

REMARK 2. While a dialog-box is active one may quietly page through the unit
menus to see what they contain or to get name fragments. Be careful in chosing
a unit-name. E.g., the unitname PS (PegaSiemens) cannot be redefined although
it was never in use. Unit names starting with operation signs or the empty
string may cause a crash after using them as explained in Remark 1. Using 'e'
as unit for an electron's charge may cause problems. The HP49 evaluates '2*e'
as a real or a charge unit, depending on how '2*e' was created. 

REMARK 3. The assignment on the rightshift UNITS key may become very large but
can be compressed to about 1 KB with BZ: recall the assignment with S?UA from
OT49, compress it with OT49's BZ-toggler ~, press UBZi and then +EVL from the 
menu. Finally, assign the result to the rightshift UNITS key. Clearly, do this
only after a UNITS customization has become sufficiently stable. Each change
in the UNITS structure automatically reassigns key 84.3 uncompressed.
-----------------------------------------------------------------------------
 Wolfgang Rautenberg  raut@math.fu-berlin.de  www.math.fu-berlin.de/usr/raut 

