
                               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
