SYSUTILS v2.1 by John M O'Donnell (ODONNELL@LAMPF.LANL.GOV) 21-Sep-1993 --> S/SX/G/GX Summary ======= SYSUTILS is a collection of unix like directory utilities for the HP48. The library is written in SYS-RPL and USER-RPL. SYSUTILS v2.1 was created using the RPL48 package by Detlef Mueller and Raymond Hellstern (and Rick Grevelle). It was written on an SX, but is expected to also run on a GX. Command Description =================== (1) Command: EXEC Short Description: EXEC adds path like functionality to the HP48. This routine is similar to ones written by Scott Burke and Darryl Okahata. EXEC searches a list of directories (given in the variables 'TRAIL' and 'TRAIL.SYS') for the first occurrence of an object named in stack level 1. At the end of the search, the object is evaluated in the initial directory. Stack arguments: levels, N+1,...,2 - arguments required to evaluate requested object. level 1 - object to be found in another directory and then evaluated. Other arguments: TRAIL.SYS - an ordered list of directories to search for the object named in level 2. TRAIL.SYS is in HOME. TRAIL - an ordered list of directories to search for the object named in level 1. This list is prepended to TRAIL.SYS. It is used to make modifications to TRAIL.SYS local to a given directory tree. A default TRAIL with no paths should be included in HOME. In the interest of size and speed, little checking is done - make sure TRAIL refers only to existing directories. Return Stack: levels M,...,1 - results of evaluating the object. Error Messages: Bad Control Variable - TRAIL, or TRAIL.SYS is not a list. Other messages are described in the HP48 manual. Discussion: When searching a directory for the requested object, only the specified directories (and not their parents) are searched. Thus, using the directory tree from Scott Burke's example: HOME /\ WORK PLAY / / \ \ W1 W2 W3 GAMES and with TRAIL.SYS set to { { W2 } { WORK } }, the HOME directory would not be searched, and WORK would be searched only once. This version evaluates the requested object in the current directory, not the directory in which the object came from. (This can be easily changed.) I have considered points raised by the previous authors: (1) I do not require TRAIL or TRAIL.SYS to be in the HOME directory. It comes from the HP48 PATH, and a local copy is then maintained in the program. This allows software packages to have their own path. (2) the name is short. (3) Using SYSRPL considerably speeded up the code. Other speed improvements include searching only the requested directories (not their parents as well) and terminating the search loop as soon as the first occurrence of the requested object is found. (4) Searching the current directory can easily be achieved by including {} in TRAIL.SYS. (5) No extra code is required to handle {} occurring in TRAIL.SYS. (6) HOME is only searched if included in TRAIL.SYS (either as HOME or as { HOME }. (7) The code is independent of flag -55 (LAST ARGS). (8) The requested object is evaluated in the original directory, not the directory in which the requested object came from. This is a personal preference. I can provide a version which evaluates the object in it's own directory. Which option is preferred? Should it be selectable via a flag? (2) Command: DIRS Short description: Displays a list of the directory stack used by the PUSHD and POPD commands. Stack arguments: None. Other arguments: DIRS.DAT - contains a list of the directory stack. (see PUSHD for details.) Return Stack: None. Error Messages: Bad Control Variable - DIRS.DAT does not contain a list with at least one element. Other messages are described in the HP48 manual. Discussion: Displays the list of directories used by the PUSHD and POPD commands. Each entry is numbered with a binary integer and base, as set in the modes menu. If DIRS.DAT must contain a list with at least one object, otherwise an error is returned. (3) Command: PUSHD Short description: Changes the current directory. Puts the new directory at the end of a stack of directories. The new directory may be selected by name (it is added to the stack), or selected from a directory already on the stack (the stack will be re-ordered.) Stack arguments: level 1 - name of a directory to add to stack (either a global or a list). or - number of directory stack entry which will be brought to the head of the stack (similar to ROLL command). Other arguments: DIRS.DAT - contains a list of the directory stack. (see below for details.) Return Stack: None. Error Messages: Bad Control Variable - DIRS.DAT does not contain a list with one or more elements. Bad Argument Value - selected item is not a directory. or numeric selection is not in the range of items in DIRS.DAT. or selected item in DIRS.DAT is not a list pointing to a directory. Other messages as in the HP48 manual. Discussion: Provides functionality similar to the Unix C-shell command PUSHD. Changes the current directory. The new directory is selected by name (as a global or a list), or by number from a list of directories already entered using the PUSHD command. If selection is by number, the list is reordered in a manner similar to the ROLL command. The current list of directories (with their number) may be displayed with the DIRS command. DIRS displays the entry number is a 'binary' whereas, PUSHD only accepts reals in stack level 1. The list of directories is kept in the variable DIRS.DAT. Confusion is likely to occur if this is not in HOME. A default DIRS.DAT is created when the library is installed. The DIRS, PUSHD and POPD commands check for valid arguments, and also for a valid DIRS.DAT. DIRS.DAT can become corrupted by modifying it with routines other than those provided in SYSUTILS. DIRS.DAT may also become corrupted by purging a directory which it refers to. Corrupt entries in DIRS.DAT may be removed with the standard editor, or by using the POPD command. (4) Command: POPD Short description: Removes entries from the list of directories used by PUSHD. If entry 0 is removed, also changes the directory. Stack arguments: level 1 - number of the entry in the directory stack to be removed. Other arguments: DIRS.DAT - contains a list of the directory stack. (see PUSHD for details.) Return Stack: None. Error Messages: Bad Control Variable - DIRS.DAT does not contain a list with one or more elements. Bad Argument Value - new entry 0 in DIRS.DAT is not a list pointing to a directory. or numeric selection is not in the range of items in DIRS.DAT. or Only one entry left in DIRS.DAT. Other messages as in the HP48 manual. Discussion: POPD is used to delete entries from the list of directories used by PUSHD. The entry to remove is selected by the number shown by the DIRS command. Removal is similar to ROLL followed by DROP. If entry 0 is removed, then the current directory is changed to the new entry 0 value. DIRS displays the entry number is a 'binary' whereas, POPD only accepts reals in stack level 1. (5) Command: NAMKEY Short Description: Provides the rc.p name for a key. Runs interactively. Return Stack: Name of the key pressed. (5) Command: SHOKEY Short Description: Shows the definition of a user defined key. Runs interactively. Discussion: When prompted, hit the key to be shown. Do not enter user mode. The definition of the key is displayed as a comment at the top of the screen. Installation ============ SYSUTILS is provided as a self attaching library (number 1721). To install, save it in a port, and power the calculator off then on. Defaults are provided for DIRS.DAT and TRAIL, if they do not exist. You may want to edit TRAIL to include PATHS to your own directories.