XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX OT49 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Operating Tools for the HP49 Aims at making the life on the HP49 as easy as possible. OT49 serves both, the normal user and the expert. It offers library-, menu-, programming- and compression-tools and allows to recall menus, standard or user key assignments and to toggle fonts, flags and other items. Some options should be assigned to keys, e.g., DType, 3tog, S?UK and the togglers from page 2. Store OT49 in any port. A warmstart (ON+F3) attaches OT49 *and* the builtin libs 256 and 257 some commands of which are used in OT49. For getting OT49's full power, load also extable in port 2. The lib manager D<->L is the primary tool for customizing the 49-HELP engine for self-made library commands in UsrRPL. Note also that your ROM version should not be older than 19-6. -------------------------------------- NEW in VERSION 5.2003 (final version if future ROMs make no basic changes) Togglers on page 2 and BZDIR improved. A html-document added. NEW in VERSION 4.2003 Small bug in Flg~ fixed. Header update correct also if toggling flag -67. NEW in VERSION 3.2003 In future one can hide files also with the filer (Filer1 or Filer2, version 3.2003). Therefore, the OT49 hiding tools are replaced by system parameter togglers, see below. Those who like slighly more comfortable hiding tools may use the HIDE lib 273. Purge command has moved to the last page now. Those who used the Purge command in programs and key-assignments must reprogram these. NEW in VERSION 9.2002 BZ-toggler ~ decodes now compressed self-evaluating code, see below. NEW in VERSION 8.2002 InL slightly different input line, BZDIR now compatible with Filer1. Existing compressed directories are not affected. NEW in VERSION 7.2002. D<->L made still more user-friendly, see below. DType shows also Dispatch Type of Level 1 object. S?UK now displays both, Usr a n d Sys key numbering. Can also be used in Edit mode. NEW in VERSION 2.2002 A new option $HELP is added to the dialog box in D<->L for creating a library. You may add HELPs for library commands while browsing the catalog with CAT. NEW in VERSION 1.2002 LMN yields the list of visible rompointer also for internal lib numbers for which MENU errors. E.g, 221 LMN yields the list { ->LANGUAGE ... }. Command SFD is replaced by BZDir since ROM 19-6 introduces a new slightly more general command DISPXY. Thus, programs containing SFD have to be revised. Already in earlier versions the BZ-toggler has become a very powerful additional feature: Self-decompression and self-evalution can be done inside a short code object, see below. We mention that the following unnamed rompointers are stable, hence may confidentially be used as long as OT49 is present on your calculator: XLIB 360 25 - the set of a l l variables of a directory, hiddens included. XLIB 360 26 - a very small and fast BZ-decompressor, no argument checking! XLIB 360 27 - BZstring filter. Errors, except for a BZ-string input. ------------------------------------------------------------------------------ Below, Lst, Prg, Str, Zint, Meta denote any list, program, string, integer, or metaobject, resp. A metaobject is a collection of arbitrary stack-objects with a count in level 1. All explanations refer to RPN-mode. Library commands: Page 1 - Menu and Library Tools CrM "Create Menu" Stack: Lst -> MLst Expands the menu-building facilities. Creates a menu-list MLst (a list accepted by MENU or TMENU) from a n y list. MLst always ends up with EXIT on key F6. If Lst is empty then EXIT will be the only menu option. If executed in a suspended (HALT) state, it also continues the program. If Lst is a standard argument for MENU or TMENU, nothing changes. The interesting case is that Lst contains a member, L say, which is itself a list of size > 2. In this case, the head of L will be the menu-name of a program automatically made from L's tail. CrM allows a very economic writing of complex menus. That a name cannot be quoted inside a list is no problem for OT49: names and other objects inside lists can be quoted with a special quoter symbol which is replaced by the SysRPL-quoter x' after processing the list or program with ->XU, see below. EXAMPLE. The argument { {"TIME" << DO TSTR 1 DISP UNTIL KEY END >> } } for TMENU which displays the running time can shorter be written as { { TIME DO TSTR 1 DISP UNTIL KEY END } }, without program delimiters. And the displayed menu has an EXIT at the end, in addition. LMN "ListMenuNames". Stack: zint/real -> list (or errors) Recalls the list of menu names of a menu with the input number (this is impossible in UsrRPL, in general; assign RCLMENU to a key if you want to know the number of the current menu). list contains unnamed rompointers at places where subdirectories occur in the menu. Press leftshift-hold NXT (sets the last menu) to see what they mean. Also the three ports are included into the scheme, numbered by 0,-1,-2 (e.g., -2 LMN returns the list of files in Port 2). 1 LMN recalls the CST-list, 2 LMN does VARS. 3 LMN returns the directory listing under MTH, 34 LMN one the two menus with list-related commands, 81 LMN a list of PLOT commands, 104 LMN the list of Transfer-commands, 110 LMN a list of port commands, 111 LMN the list of all lib-titles, 360 LMN the list of OT49-commands, 2270 LMN a large list of commands added in the HP49, 788 LMN the huge list of the 141 CAS commands, etc. Also for numbers not accepted by MENU, LMN yields the command list (e.g., those from lib 222). For reals < 256 LMN errors if a corresponding internal library doesn't exist and also for the value 30 (30 MENU need not exist). The output of LMN may contain rompointers which can be evaled and analysed with DType from OT49. E.g., 3 LMN has only rompointers in it which form the MATH menu. These rompointers may freely be used to form your own MATH menu. With LMN, one may form one's own application menus as in the following EXAMPLE1. We want the HP48 port menu 110 with its useful items ATTACH etc. Its first position entry (PORTS) has been removed on the HP49; it now has a gap at the end. We just fill it with the PURGE command: << 110 LMN OBJ-> DROP2 { PURGE } HEAD 6 ->LIST TMENU >> For a better programming see under . It is recommended to assign this to leftshift-hold 2 (key 93.21). This is very similar to the HP48. EXAMPLE2. Suppose we want collect *all* commands related to lists in a single menu. This is realized by the following simple UsrRPL-program: << 34 LMN 1 6 SUB @ Recall the LIST-commands from the PRG-menu with 11 LMN @ SubDirs ELEM, PROC included! Recall LIST-commands + @ from the MTH-menu. Concatenate and set the common TMENU >> @ list as a single 3-page menu. It's convenient to attach this program to a key, for instance leftshift- hold PRG. Thus, OT49 provides enormous freedom in manipulating menus. NOTE FOR EXPERTS: LMN supports an extended use of CST: 1 LMN yields the TMENU list also if CST stores a program or name of it which evaluates to a valid menu list and if the CST key is correspondingly assigned. - "List difference". Stack: Lst2 Lst1 -> Lst Yields the relative complement Lst2 - Lst1 of arbitary lists, i.e. the list of all members of Lst2 not in Lst1. With -, other set operations are readily defined. E.g., << OVER SWAP - - >>, applied to Lst2 List1 computes Lst2-(Lst1-Lst2) which is the intersection of Lst2 and Lst1. DoL "DoList". Stack: Lst Obj -> Lst* A very fast list processor. Obj is usually a program or function but can actually be any object, evaluated for each member of Lst. In particular, if Obj is a list, it is evaluated as if it were a program. The output is collected in a list Lst* which may be empty (e.g., if all members of Lst are displayed, or if Lst itself is empty). EXAMPLE: The number of binary digits of an integer n > 0 is given by IP((log n)/(log 2))+1. To compute these for n=1,...,16, put {1 ... 16} and << LOG 2 LOG / IP 1 + >> on the stack and press DoL. Instead of the program, { LOG 2 LOG / IP 1 + } does the same, and also 'IP((log n)/(log 2))+1'. You get the above program or list also by applying 3tog to this algebraics. HINT FOR EXPERTS: DoL can be used in *any* temporary environement with its own nulllams in the arguments (impossible with DOLIST or DOSUB). D<->L Toggles library creation and splitting. If Level 1 contains a real or a zint n and an external library with number n exist in a port, its source directory is restored in 's' (s for source) and one drives into this directory. Otherwise a dialog box is invoked to aid in library creation - provided D<->L isn't executed in HOME but in an intended source dir as long as this does not yet contain the variable $ROMID. The dialog box is asking for the library name ($TITLE), lib-num ($ROMID), the list of visible names in the lib ($VISIBLE), its hiddens ($HIDDEN) and a field $HELP for adding HELP options in the Catalog for some of your commands. This is the only supported capability of $EXTPRG which can be managed only from inside a library; all other ones can be realized by the user not familiar with SysRPL with the aid of APPSman. $HELP may be scipped and *must* be skipped with a ROM version older than 19-6. To get HELP on the CAT key or in LIBman or Emacs for the commands Cmd1,...,Cmdk (names from the directory), fill in the $HELP field with a list as follows: { {Cmd1 "Tex1"} ... {Cmdk "Textk"} } where "Text1" is displayed if Cmd1 is selected in CAT, etc. Whenever $HELP is not of the indicated shape, D<->L errors. Please do not misuse the 49 by providing HELP for each command (OT49 yields HELP only for -D (DispOff), found at the very end of CAT command listing). A HELP-text may be scrolled in the Catalog if the text is too large for one screen. Make the $VISIBLE entry as follows: Press leftshift + to edit {}. Then press VAR and put into the list the names from your dir in the order you want to see them lateron in the library. Similarly, fill in $HIDDEN - to contain the unvisible files used by your library. Hit leftshift + twice to start an entry into $HELP. A list field entry may be the empty list. After pressing OK, D<->L creates additional $-variables: $CONFIG (to attach the library at warmstarts), $HELP, $$ and $EXTPRG. Of all these $-variables, $CONFIG, $HIDDEN, $VISIBLE, $Romid, $TITLE and $HELP are modifyable for a second run by the normal user. In particular, the help texts in $HELP can be improved as often as you want. Modifying $$ is not allowed unless you are an experienced SysRPL programmer! Note that $$ appends itself to the list in $HIDDEN. If removed, D<->L will error as long as $EXTPRG exists. IMPORTANT: Whenever $ROMID is present in the source directory, the dialog box is skipped. Useful for modifying the $-variables or for adding new ones, $MESSAGE say, in a second run of D<->L; just delete the lib from the stack after a first run. A second run of D<->L is very fast since the dialog box is skipped. Command order in the library is fixed by the order in $VISIBLE and $HIDDEN. Only files occurring in these two lists will belong to the library. EXAMPLE. Assume we want HELP for the command ->TO? of Keyman. Split it by doing 1200 D<->L. We are now in the dir s1200. Purge all $-variables at the end of the dir and archive your HOME in port 2. Run D<->L again, still being in s1200. Next fill in the dialog box with the obvious (see the screen-shot of OT49). Don't forget to put {x008...x00E} in $HIDDEN. HELP on ->TO should describe the stack diagram of ->TO. E.g., fill in $HELP as follows: { { ->TO? "Short pressed puts TakeOver on Top" } }. Press OK and store the new Keyman in Port 0 with the old Keyman still in port 1 or 2. The OS will prefer the modified Keyman in Port 0. Now press CAT and choose IfE?P - and you'll see its HELP option. InL "Input List". Displays a message from Level 1 and waits for input into a list (mostly global variables) which will be the output. InL is very useful for an elegant treatment of ORDER, Purge and other list-accepting commands. NOTE: Pressing CANCEL in InL aborts without error messages. EXAMPLEs: << "ORDER" InL ORDER >> assigned to a key is a nice ordering tool. The message need not be a string; the program may be shortened to ' ORDER InL ORDER (use ->XU to create such a program). This reduces the above program from 28 to 18 bytes). Similarly, << "Purge" InL Purge >> is a fast and general PURGE tool which purges from ports as well. Both commands are power-devouring. Hence, put the Display-Off command -D in front of the command to save your batteries. Faster than the Filer is also this renaming tool: << ' RENAME InL OBJ-> DROP SWAP RENAME >>. -------------- Page 2 - Toggling system parameter ~ANG Toggles RAD/DEG which is noticed in the Header. This and other togglers should be assigned to suitable keys to use it also in programming mode. ~COOR Toggles the three builtin coordinate system. ~FONT If normally pressed toggles toggles current font and minifont. You best see the effect by having something in the stack. If double-clicked like a PC-mouse, toggles the 3 standard fonts (which probably rarely happens). ~FONT shows its full power only if assigned to a key, with a TakeOver on top (see Keyman.txt). A good key is the unused rightshift-hold NXT which reminds on "Paste the screen appropriately". ~BASE Toggles HEX/DEC/OCT/BIN, noticed in the Header. ~LANG Toggles the 3 languages, displayed in the Header. ------------------------------------ Page 3 - Information and Programming Tools. DType Displays type number, type name and Dispatch number of a Level 1 object. If this is a rompointer (aka lib-name) or a flashpointer, its content is recalled. The content's type is displayed in this case and an asterix is appended to the type, to remind you that type information refers to the content. Flash- and rompointers cannot be recalled at the user level. A main reason for using DType is that the stack appearance of an object does not always yield reliable type information. The Dispatch number is important only for SysRPL programmers. Flashpointers are not extracted if its extension in flash-rom is undefined at the begin of its asm code. In this case you'll see the message "Ext undefined". EXAMPLE. The standard assignment of SIN (recalled with S?UK) appears as SIN. Applying DType seemingly duplicates SIN. But the display says "Function*". We hence may infer that SIN in Level 2 is only the lib-name of the Level 1 function (the latter has 2.5, the other 5.5 bytes). As a matter of fact, most operation and function keys are rompointers. With DType, arbitrary rompointers are recalled, without splitting a library. E.g., the key sequence [S?UK][DType][DType] yields the DType-program. S?UK Recalls a key's actual functionality (either its standard assignment or user assignment whenever the key is assigned and USR is on). Choose the key after S?UK. The main use of S?UK for a beginner is that it displays the location of a pressed key; it informs on the key code rc.p (row, column, plane). E.g., it displays 42.31 if pressed on rightshift-hold CAT. Also the system key code { #key #plane } is shown, { 18 9 } in the example. The system key code is basic in advanced programming. 3tog Toggles three representations of a program: its program, its metaobject and its list form. A test with some program on the stack will tell you more than lengthy explanation. The list form is convenient to modify a UsrRPL program with stripped program delimiters, the metaobject form to modify a SysRPL-program whenever MASD fails to recompile a decompiled program to its original. Applied to an algebraic object, 3tog toggles its list, program and metaobject RPN-equivalents. Try with '1+2=3', say. Stack-diagram: Alg -> Prg -> Meta -> Lst -> Prg -> ... Flg~ Comfortable Flag-toggler for System and User flags. Needs a positive or negative real or zint < 129. Zints should be prefered since small zints need less memory than reals. Toggles a flag and displays what has just been done in the Header. The 10 flags listed below directly affect the (2-lines) Header look. In these cases no extra information is displayed (watch the header). The same for the corresponding user flags, hence you have got 10 particularly fast user-flag togglers. . flag -11 : toggles HEX and OCT (flag -12 clear) flag -12 : toggles DEC and BIN (flag -11 clear) flag -16 : toggles XYZ and RXU (to "Xtended" UsrRPL). Strips the user program delimiters of a UsrRPL program (also inside a program or a list). Local environement delimiters are respected. In PRG-mode, ->XU writes a quoter ï (symbol 180) which, after a program is run with ->XU, replaces ï by the SysRPL-quoter ' (symbol 39, also seen as x' if flag -85 is set). ->XU is very powerful. It expands, in a sense, the built-in compiler. The resulting program is mostly much smaller and faster. But it cannot be edited and recompiled anymore with ENTER. Use 3tog or Sys~ instead. Only programs, lists and the name 'ï' can be affected by ->XU. To get ï conveniently, assign ->XU after processing it with ->TO from Keyman to rightshift-hold EQW, say. EXAMPLE. Reprogramming <<"Purge" InL Purge>> as << ' Purge InL Purge>> and processing this with ->XU saves 7.5 bytes and is much faster. Thus, ->XU enables you directly to quote rompointers like Purge, impossible in UsrRPL. The main advantage of ->XU in programming is that names etc can also be quoted in lists which makes UsrRPL much stronger. -------------------------------------- Page 4 - Compression tools and Miscellaneous. ~ Toggles BZ-compressing and decompressing. ~ is executed also by pressing alpha-rightshift 1 (92.5) and then ENTER on the symbol ~. Hence, ~ need not be searched in the library menu. Compression ends always up with setting a powerful menu for further processing the obtained BZ-string: [UBZi] appends the BZ-decompressor XLIB 360 26, for internal use only. XLIB 360 26 is slightly faster in decompressing than ~. [UBZe] appends the decompessor's content for external use, e.g., if a compressed object is sent to hpcalc.org. [+EVL] appends EVAL to a program. For instance, <<"BZ..." XLIB 360 26>> results in the self-evaluating <<"BZ..." XLIB 360 26 EVAL>>. [BZC] makes a code object from a BZ-string. Its execution decompresses whithout evaluating the decompressed object. [BZCE] is like [BZC], but evals the decompressed object. These codes are readable by any HP49. The code objects thus obtained are decoded by ~. Other code objects are compressed (if having at least 27 nibbles). [EXIT] toggles the menu with the OT49 menu. REMARK for EXPERTS: Menu options after compressing with ~ can be used in programs. ::CK1 x~ 5 GETPROC EVAL %0 InitMenu% ?DispStatus; yields an object's BZCE-code and cleans the header from BZ-messages, etc. BZDir Compresses a directory with all its subdirectories (except HOME). Go to that directory and run BZDir. This leaves a single file in the directory whose name coincides with the directory name. Its execution immediately restores the original directory. Thus, a directory with a single equally named file in it means with high probability that it is compressed. -D D deshed = "DisplayOff". Put on top of a program, the program executes with turned-off display. This is faster and saves the batteries. If put somewhere in the middle of a program, the screen will turn off from that moment on until the end of the current runstream (the next semicolon not preceded by a ::). You see the symbols :: and ; when setting flag -85. -D is recommended for longer-lasting power consuming applications. ObFx If loading something from the HP48 or with XMODEM from hpcalc.org one sometimes gets a corrupted string: the received object was not fully "understood" by the HP49. Put it on the stack and run ObFx. This leaves the right object on the stack provided the object isn't corrupt itself. Purge Purges everything very fast, including directories (except the internal Hidden directory). The fast purging of directories has to be paid with some care: No stack object should reference to objects from a directory intended to be purged. Best to have only a name or list of such on the stack when applying Purge, and nothing should be suspended. EXIT Leaves the current menu and resets the previous one. EXIT appends itself to any temporary menu created with CrM, but may also be appended to any other menu. Used in a program suspended with HALT, EXIT automatically continues its execution without first pressing CONT. -------------------------------------------------- Wolfgang Rautenberg - raut@math.fu-berlin.de - www.math.fu-berlin.de/~raut CREDITS. Thanks to joint work with Peter Geelhoed the library extractor in D<->L could be made faster and more comprehensive. DoL uses an idea of Werner Huysegoms. S?Ukey uses a code of Jonathan Busby and a hint of Carsten Dominik. Embedding decompression and self-evaluation in asm code is due to Jurjen Bos. Particular thanks to Heiko Arnemann who created the html-document and the pictures.