exec by John M O'Donnell (ODONNELL@LAMPF.LANL.GOV)          2-Oct-1994

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
============

Install EXEC in the HOME directory,
Make a list of directories to be searched by EXEC and store in TRAIL in the
HOME directory.

Hardware
========

Runs on 48S(X) and 48G(X)
