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.
