GxTools v5.1 written in 100% SysRPL by Jack Levy Overview -------- GxTools is in effect a "Toolbar" for your G/Gx. It will assign it's customizable program bar to a key, and you may include any of the programs in the library on this bar. I wrote some of the programs from scratch; some programs were written by others, but I improved upon their code; and some programs were completely written by others. I don't take credit for all the utilities in this library; I am just interested in providing a useful utilities package for the GX. In addition to these utilities, I have developed many mathematical tools for the GX. These can be found in the MathTools library, via anonymous FTP from FTP.CIS.COM. Included in this library are such programs as a plotter replacement, quick solver, table of values, matrixwriter, and more! Disclaimer ---------- These programs have no guarentees. They have been tested on a HP48G revision R and a HP48GX revision R with no problems. Most of the programs in this library will *NOT* work on an S/SX series calculator. The others may or may not work, but I did not write these for SX's and there are no guarentees. I take no responsibility for any loss of memory or damage these programs cause to your calculator. Use at your own risk. As always, BACKUP YOUR CALCULATOR BEFORE LOADING THIS LIBRARY!! There is no way of telling if a new ROM revision may cause this library to crash. Registration ------------ This library is "Email-ware". What does this mean? If you like this program and use it regularly, you must send me an email message. (Not too steep, huh?) The idea is simple; If I know people are using this library, I will be more inclined to update it and write new programs. My internet address is jacklevy@aol.com and my compuserve ID is 73267,235. Installation ------------ 1. Transfer the library to your HP48G/GX using Kermit/Xmodem/etc. 2. Press the soft-key associated with the library file (GXT51.LIB). "Library 1081: GxT..." should now be displayed on level1 of the stack. 3. Purge the GXT51.LIB variable, leaving the library on the stack. 4. Enter the port number you want to store the library into. Note: For G users, this number must be 0. For GX users, the library can safely be stored in any port, but it is recommended that you store it in either port 0 or 1, as execution from a covered port is slower. 5. Press STO. 6. Turn the calculator off and then on again. To access the library, press right-shift-library (2), press NXT until you see "GxT", and press the corresponding key. To install and setup the library, press [NXT] twice and then "GXTCFG". For those who want to make sure that the library transferred correctly, place the library on the stack and run "BYTES". The following number should appear: Checksum: #A8A5h [43173d] Size: 4470.5 Note to users upgrading ----------------------- This vesion of GxTools contains different XLIBs. If you are upgrading from any previous version of GxTools or QTools, you must rerun INST (in GXTCFG) to correct your key assignments. With many new releases of the library, XLIB addresses are changed, and your key assignments may be incorrect. You must also re-compile your toolbar by running GXTCFG and pressing "SAVE". Finally, you should double check that any programs you created which access GxTools programs use the correct command. Because of the XLIB changes, they may now call a different command. Command Reference ----------------- GXTOOLS This is the menuline interface to the programs in this library. This menu is completely customizable through GXTCFG, and can include any of the utilities in the library in any order! In addition, you may add utilities in the MathTools library to this bar (this is discussed later). Select a program to run by pressing it's softkey; press NXT for more. For more information on customizing GXTOOLS, see the section on GXTCFG. GXTOOLS will not run until GXTCFG has been executed; If you run GXTOOLS and GxTpar does not exist, it will run GXTCFG and then continue. See the section on GXTCFG for more information. I assign this program to the left-shift-PRG button. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { GXTOOLS } HEAD 22.2 ASN This key is automatically assigned when GXTCFG/INST is run. LOCKER This is a password protection program for your calculator. It is not as tight as such programs as CodeLock and Gateway, but they are 2k+ and this is only 150 bytes! You can break through it using hardware resets, so it is not meant to keep out HP-Hackers; but I have made it as tight as SysRPL allows without creating a POL. As far as I know, there is no way to break past it by just hitting random keys, etc. Before LOCKER will run, you must configure it in GXTCFG. See GXTCFG for more information on these settings. When creating your display file, use right-shift-DOT to go to the next line. An example might be: "This calculator belongs to John Q. Public." The only thing important is that it is 3 lines or less and does not run off the screen. When you press INST button in GXTCFG, Locker will assign itself to the OFF key. Then, to turn off the calculator, make sure you are in USER mode, and turn it OFF like normal. When you turn it on again, LOCKER will run. You can change your password or message whenever you want inside GXTCFG. To those of you who did not reconfigure the password in GXTCFG: The default password is blank, so just hit ENTER to unlock it. Locker will not be accidently "unlocked" if you set alarms; If you set a message alarm ("") then the alarm will act like usual, and after locker loads the message will be displayed at the top of the screen. (You are then left in locker and still need to enter a password) Seting a program alarm (<< >>) will no longer work; When the program is run, it passes the commands to the stack without parsing, leaving Locker confused. As a result, each command in your program is fed to Locker as a attempted password. Setting a program alarm with Locker enabled will therefore cause it to turn itself off a few times when you turn it on (as it responds to the "invalid" passwords). So if you wish to use program alarms, you must disable Locker. I keep this assigned to my OFF key. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { LOCKER } HEAD 53.2 ASN This key is automatically assigned when GXTCFG/INST is run. PPURGE This is a "protective purge" front end for XPURGE. Put any object, list of objects, library identification, or other acceptable argument on level1 and execute. PPURGE will ask for confirmation by pressing ENTER, and then run XPURGE on the object. I keep this assigned to my PURGE key. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { PPURGE } HEAD 53.2 ASN This key is automatically assigned when GXTCFG/INST is run. XPURGE This is a purge replacement program by Bill Wickes. XPURGE will purge variables, libraries, directories, lists of combinations, or anything you place on the command line much faster than internal PURGE and PGDIR. Users who do not want to use Protective Purge may wish to assign this to their PURGE key. ORD The internal ORDER command, which re-orders directories, is very slow. ORD, by Mika Heiskanen, reorders a directory about twice as fast as the internal ORDER. The program is included in GxTools mainly because HIDEV uses it's sorting routines. Usage is identical to that of ORDER: Just place a list of the variables you want in the proper order on level1 and execute. FVAR FastVAR is an ML replacement by Mika for the VARS command. Much faster than internal VARS, but same function. Run to produce a list of all variables in the current directory. FVARA Another VARS replacement by Mika, but this one will include hidden variables in the list. HIDEV HIDEV will hide any variables in any directory from view, but you may still use them, recall them to the stack, and store information into them like usual. Any hidden variables will not show up in the memory browser, VAR key, or VARS list. Execution of HIDEV is simple; Create a list of the variables you want to KEEP (not hide) and place it on level 1. The easiest way of doing this is starting a list (with the {} key), pressing VAR, and then pressing each soft-key associated with the variable you want to keep. HIDEV will them reorder the variables you selected, in the order you entered them, and hide all remaining variables. To "awaken" the hidden variables, put 0 on level 1 of your stack and press HIDEV again. This program can be handy to hide your GxTpar file, as well as all the cluttering IOPAR, PPAR, ZPAR, EQ, EXPR, etc files in your directories. HIDEV uses ORD instead of ORDER to sort the directory. See the section on ORD for more information. HIDDEN This is another simple program to enter the HIDDEN directory on the HP. For anyone who does not know about this directory, the HIDDEN directory is a null-character directory off of HOME which is used by the 48G to store User keys and Alarm information. (And possibly other misc data) You can store anything you want in this directory, but you must NEVER reorder the variables, as this will result in a loss of memory. To use, simply press HIDDEN. To return to the home dir, just like any other dir, press the HOME key. FAST Displaying the display consumes 11% of the CPU processing time. This routine, written by Detlef Muellor, turns off the display, executes the command or program on level 1 of the stack, and then restores the display. It can be used with any program that does not require a visual display. If a command interferes with the screen display, it may require you to blindly turn the calculator OFF and then ON again. If this still does not work, pressing ON-C will always restore it. TEVAL TimeEval is a type of stopwatch for your programs; Put a program or command on level 1 of the stack, and instead of pressing EVAL, run TEVAL. After the program runs, a number in seconds will be left on level 1 of the stack. This is how long actual program execution took (excluding the time TEVAL was doing it's own operations). NOTE: The TEval program in many other utilities libraries is written for an SX and does not account for GX garbage collection times. This version is accurate on a G/Gx, thanks to Mika Heiskanen. I keep this assigned to my left-shift-TIME key. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { TEVAL } HEAD 72.2 ASN This key is automatically assigned when GXTCFG/INST is run. LNM LongName converts strings to global names (IDs) and vice versa. This allows for long filenames with spaces in them. For example, to store an equation as 'EQ TWO': Put the EQN on level2 of the stack, put "EQ TWO" on level1, run LNM, and press STO. To purge or modify 'EQ TWO', convert the string to an ID and continue. NOTE: There are three ways to put an invalid variable name on the stack once you have created it. First, you can type the name in by hand with quotes and convert it to an ID (as you did originally). Second, you type ""'s, change the entry mode to programming, and press the softkey associated with your variable. You can then convert it to an ID using LNM. Finally, you can trick the HP into placing a long variable name on the stack by pressing left-shift-[varkey]. An error will be returned, and the long filename will be dumped onto the stack. REN Renames a variable without re-ordering the directory (another by Mika). Requires two arguments: Enter the new name of the variable you want, then enter the current name of the variable on level1. NOTE: Do not attempt to rename a variable to a name which is already being used in the current directory. If you do, the other variable will be over-written with the contents of the variable you want to rename. TBYTES While the BYTES command is useful for reporting the size of an object, it lacks the ability to report the total size of all objects in a list. TBYTES makes up for this absence. Put either a list of objects or the ID of an object on Level1 and press TBYTES; The total size (in bytes) is left on the stack. SPRG Creates or breaks apart a program. Given a UserRPL or SysRPL program on level1, SPRG will break the program into it's pieces and leave the number of commands on level1. To create a program, enter the arguments in the order you want them to be assembled, then enter the number of arguments and run SPRG. Therefore, the output of a broken program is suitable input to rebuild the program. Keep in mind that the programs created by SPRG are SysRPL programs; They are not enclosed by << >> delimiters, but :: ; delimiters which you can not see. Therefore, if you run SPRG on the program << TEST >>, it will break it into <<, TEST, and >>. (Also leaving a 3 on the stack to indicate 3 commands) Example: << "Hello" 5 2 SPRG >> returns this: 1: "Hello" 5 Running SPRG again will return this: 3: "Hello" 2: 5 1: 2 SysRPL programs evaluate just as << >> programs, except you cannot edit them, and they are slightly smaller. CODE CODE (version 3) converts any object to a "Code" level object, or it will convert a Code object back to it's original. The purpose of converting a program to a Code object is because a parser can skip over it much quicker than something with << >> delimiters. It is highly recommended to convert any << >> key assignments to Code objects, as this will greatly speed up user keyboard recognition. Do not convert single ID key assignments to Code objects, as this will have a negative effect. (Loading time will increase by 0.001 seconds) XLRP XLibRomPointer converts to numbers to ROMPTRs (XLIBs) and back. The architecture of a ROMPTR is XLIB #Libnum #Cmdnum. So to compile the XLIB pointer to library 1094, command 6, put 1094 and 6 (or optionally #446h and #6h) on the stack and run XLRP. What results will be either XLIB 1094 6 (if the library does not exist) or the command (if it does). XLRP also decompiles ROMPTRs, giving you their address. For example, running << { MSOLVR } HEAD >> will place the pure "MSOLVR" command on the stack. When you execute XLRP, it will return the two hex pointers of it (ROMPTR 0AB 24). You can then use these ROMPTRs in programming. ADDR A hackers tool found in many libraries: Given a raw command XLIB, it will return the SYSEVAL address in HEX notation. For example, executing << { EVAL } HEAD ADDR >> places the EVAL XLIB (displayed as plain EVAL with no delimiters) on the stack and returns a #1A3BEh address (in hex). You can therefore call EVAL via SYSEVAL by executing << #1A3BEh SYSEVAL >>. HMEM When programming in SysRPL, crashes by bad programs can sometimes leave "memory corruption", which consists of unresolved environments, such as NULLLAM's which were not ABND'd. Pressing HMEM shows you visually how much "hidden" memory you have by displaying garbage on the screen; The more garbage you have, the more hidden memory there is. A normal G/GX will have enough garbage to fill the status display area (DA1), which takes up about the top quarter of a screen. The best way to measure how much garbage you have is by running [ON]-C (with no SOL or stack replacements loaded) and then immediately run HMEM. When you are done viewing the screen, press any key to exit. BZM This is v1.2 of the front end I made for BZ/UBZ compression utiltities (by Mika Heiskanen, available via FTP at HPCVBBS.EXTERNAL.HP.COM). For those of you that have used BZ and wanted to create string or program compressions, here is a menuline that will allow you to do so. In addition, it supports storage of BZ/UBZ in any library or directory, or simply just BZ. The detection is automatic and performed at runtime. If BZM can not locate BZ it will exit with a Syntax Error. If UBZ is found, it will use it; otherwise BZ is also used for decompression. BZM requires one argument: the object you want to compile. When you run BZM, the following menu will appear: BZ - Execute BZ compressor on the level1 argument. UBZ - Execute UBZ decompressor on the level1 argument. If the argument is a STR/PRG created argument, it will extract the compressed string and execute UBZ as normal. If UBZ does not exist, it will use BZ for decompression instead. [NOTE: If UBZ does not exist, the functionality of the BZ/UBZ keys are identical, except for program extraction.] STR - Intended for compression of strings, grobs, lists, or other viewables. First executes BZ on the level1 argument, then attaches a UBZ (or BZ if UBZ does not exist) to the end of the compression string. Thus, when the result is stored in a variable and executed, the string will come up without the need for manual decompression. PRG - Intended for compression of programs. Executes BZ on the level1 argument, then attaches a UBZ (or BZ, if UBZ doesn't exist) EVAL at the end of the string. When the result is stored in a variable, executing this variable will result in your program being run with no need for manual decompression. NOTE: If you are using BZ v1.2, you must rename the version of BZ you are using (BZ1 or BZ4) to 'BZ' or BZM will not load. If your copy of BZ is already coded into a library as BZ1/4, then you will need to disassemble the library and change it yourself. Note that the names must also be in uppercase (they are case sensitive). I keep this assigned to my left-shift-UNITS key. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { BZM } HEAD 74.2 ASN This key is automatically assigned when GXTCFG/INST is run. TDD Having the 48's internal clock on display can cause a slight drain on the batteries. It also often gives the display a "cluttered" feel. I find that I only really need a quick key to check the time/date, so that is what TDD (Time/Date Display) does. Pressing it will throw a string with the day of the week, date, and time (using the HP's european/american and military/normal settings) into DA1. Pressing any key clears it from the screen. I keep this assigned to my right-shift-TIME key. To do so, change to user mode if you aren't already in it (left-shift-alpha) and enter: { TDD } HEAD 72.3 ASN This key is automatically assigned when GXTCFG/INST is run. CONTRST New contrast adjustment by Dan Kirkland. Execute CONTRST and press the right or left arrow keys to adjust the contrast on the screen. Press [ENTER] when you are done. Press [ON] to abort and return to old settings. GXTCFG This is the configuration program for GXTOOLS and *must* be run before certain programs will function. There are four options you can change: [Locker Password] - This is the password for LOCKER. The default is "", which will set the password as nothing. To enter a password, simply insert any combination of letters, numbers, spaces, etc inside the given ""'s and press ENTER. NOTE: The password *MUST* be enclosed in quotes. If you enter a password enclosed in any other delimiters, LOCKER may crash. [Locker Alpha?] - If checked, alpha will come on automatically at startup in Locker. [Locker Display] - This is the "opening screen" for LOCKER. Whatever is in this field will show up in the first three lines of the screen when you start locker. The only restriction is that it must be less than three lines. Use [right-shift-.] to create a new line. If you are upgrading from a version previous to v4.0 and want to keep your old display screen, you can press the [CALC] button on the field, put LOCKDS on level1, and press [OK] to transfer it into GxTpar. LOCKDS and LOCKPW may then be deleted. [GxTools Menuline] - Used to customize the GXTOOLS menu. The list of menu items is given in the form of a normal list {} with commands from the library in any order. To enter them, either EDIT or create a new entry in this field. To place programs in the list, press right- shift-library and go into the "GxT" library menu; Now press any of the keys on the menu in any order. (The menu will be created in the order you press them) To put a null key, just enter "" as a name. While editing, if you wish to use the EDIT menu, you can just press NXT while editing the list and it will appear. The menu for GXTOOLS will be built when you exit GXTCFG by pressing "SAVE". By default, the GXTOOLS menu is a list of all utilities without key assignments. If you ever want to restore this default menu list, go to the menuline field and press [NXT] [RESET] [Reset Value]. Then press "SAVE" to rebuild the menuline. NOTE: The GxTools menu will also support commands from the MathTools library. To add them, simply type or select (from the 1091/MT library menu) the commands as usual into the list. You can get to the mathtools command listing by pressing RS-Library and going into the MT dir. There is a button labeled "INST" on the menuline; Pressing this will install key definitions for GxTools. The program will ask for confirmation and then install all six user key assignments [ GXTOOLS, PPURGE, TEVAL, TDD, BZM, and LOCKER ] to the keys described in their respective documentation. When key assignments have been made, you are returned to GXTCFG. Note that all key assignments are made in UserRPL and editable by any plain text editor. When you have finished modifying the configuration, press ENTER or OK. Options are stored in the file named GxTpar in the hidden directory. DO NOT ATTEMPT TO MODIFY GXTPAR! If any there is any corruption to GxTpar, you may "reset all options" from GXTCFG. If GxTpar prevents GXTCFG from loading, you must delete it and rerun GXTCFG to create a new one. ABOUTGXT A full screen message box with my name and internet email address. Removing the library -------------------- To remove the library from your HP48G/GX, do the following: 1. Enter the port ID in the form :PORT:1081 and press ENTER *TWICE* Example: If GxTools is stored in port 0, enter :0:1081 DUP The port ID should now be on levels 1 and 2 of your stack. 2. Press the DETACH button (either by typing in by hand, or pressing left-shift-library, DETACH) 3. Press the PURGE key (make sure USER mode is OFF) GxTools should now be removed from your calculator. If you still get an "Object in use" error, try turning off USER mode and switching to the HOME directory. Occasionally, if you have used GxTools extensively, you may have to do a warmboot (ON-C) before it will allow you to PURGE the library. Credits ------- While all of the code was written by myself (except where noted), there is much credit due to others. Thanks go out to: Mika Heiskanen : Inverse label menubuilders, ORD, REN, et all Detlef Mueller : FAST program routines Bill Wickes : XPURGE program routines Dan Kirkland : CONTRST program routines Animesh Sabnis : Beta testing of pre-releases Joe Horn : Code objects [code -> ob] Richard Stevenson : Beta testing of pre-releases, safe CODE If you use this program and have comments and/or suggestions, you can contact me at jacklevy@aol.com. I can also be found on IRC (#HP48) occasionally as "jacklevy". This library is actively supported and any reported bugs will be fixed immediately. Any suggestions will be considered! What's with the names? ---------------------- I know a lot of people are confused as to what I've done with these libraries. Just to clear up what is being continued and what is abandoned, here is the complete story: The original library was QuickTools, and consisted of small, fast tools. As it got larger, I made some major modifications, and created a new library called GxTools. GxTools had a popular plotter in it (MPLOT), so by demand I released this individually, resulting in the MPLOT library. This was as of version 4.0--when version 5.0 hit, the library got so large that I saw it neccessary to split it. From v5.0 on, the GxTools library will contain just that--utilities for your GX. All mathematical tools have been moved into the MathTools library, and the MPLOT library has been discontinued. All new versions of MPLOT will be updated in the MTools library from now on. Version History --------------- [ v5.1 09/25/95 ] - Menuline creation/reading routines rewritten. There is no more "building menus..." subroutine, and GxTpar is now smaller in size. Key labels are slightly different; they now just list as many characters in the key name as will fit in the labels. New routine are smaller and faster. - BZM completely rewritten. Will now use BZ/UBZ stored in any library or as a variable. Uses BZ if UBZ does not exist. - CODE replaced with a covered-port safe version. In rare low-memory circumstances, when CODE was stored in a covered port and executed it could cause a memory crash. Part of ML code replaced with SysRPL code which now makes it completely safe. - BZM is now assigned as the user key left-shift-UNITS under GXTCFG. - XLRP now accepts two hex digits as input. - Added TDD, quick time/date display. Assigned to right-shift-TIME. - Added SPRG, program builder/breaker. - Added REN, variable renamer. - Added FVAR, fast VARS replacement. - Added FVARA, fast VARS replacement with hidden variables. - Added CONTRST, graphical contrast adjustment program. - Renamed ORDR to ORD and ADDRS to ADDR to match mika's HackLib; programs are unaffected (identical XLIB addresses). - Renamed HIDEVS to HIDEV and LNAME to LNM to ease alpha entry; programs are unaffected (identical XLIB addresses). - HIDEV updated. Code compacted, made safer. - ABOUTGXT replaced with full screen message box. - Protection and error claiming added to many of the programs. - LOCKER code size reduced. Slight modifications. - GXTCFG now loads GXTOOLS upon completion. - GXTCFG key assignment converted from UserRPL pointer to SysRPL format. - HMEM now runs a garbage collection before executing. This will help prevent misconceptions when a lot of orphans are left in TEMPOB. - Over 350 bytes *smaller* than version 5.0!! Version history previous to and including v5.0 has been removed. gxt51.lib [1081] code by jack levy [jacklevy@aol.com] dated 09/25/95, 7:49pm