
The REXX/imc Technical Reference

This reference contains information for programmers of functions,
subcommand interfaces and other utilities to be called by or to call
the Rexx interpreter.

Information for Rexx programmers can be found in rexx.summary, rexx.info and
rexx.ref.
______________________________________________________________________________

1. The Application Programming Interface

REXX/imc has an implementation of the "SAA API" based on that of OS/2.  This
API is at present partially implemented and "mostly" compatible with OS/2,
but it will be standardised and completed in a future release.

Programs using the API are typically written in C. The supplied header file
and the descriptions below use C declarations to describe the available
functions and their parameters.

The API allows an application to start the REXX interpreter under program
control, to add subcommand environments and external functions, to access
the REXX variable pool, and to install system exits to process certain
interpreter activities.

A C program using the API should include the header file "rexxsaa.h".
Before including this file, the program should define appropriate
preprocessor symbols to indicate which parts of the API are required.
By default, the header file includes only enough information for the
application to start the interpreter.  The symbols which may be defined
are:

   INCL_RXSUBCOM     include definitions for the subcommand interface
   INCL_RXSHV        include definitions for the variable pool interface
   INCL_RXFUNC       include definitions for the external function interface
   INCL_RXSYSEXIT    include definitions for the system exit interface.

If all of the above are required, the program may just define:

   INCL_REXXSAA      include definitions for the whole API.

When an application is compiled, it should be linked with the REXX/imc
library using the compiler flag "-lrexx".  The compiler may need to be
told the location of the library file using the "-L/path/" flag.  Either
a statically linked library or a dynamically linked library may be used.
Details of how to make the libraries are contained in the installation
instructions for REXX/imc.

1(a). RXSTRINGs

The rexxsaa.h header file defines the RXSTRING datatype as follows to
hold a REXX string:

   typedef struct {
           ULONG strlength;     /* length of the string */
           char *strptr;        /* pointer to the string */
   } RXSTRING;

   typedef RXSTRING *PRXSTRING; /* a pointer to an RXSTRING */

All the API functions which deal with REXX strings use this structure.
Any RXSTRING which has a value will have the strptr field set to a valid
character pointer and the strlength field set to a length value.  The
empty string is represented by having the strlength field set to zero.
An RXSTRING may be NULL, in which case the strptr field will be set to
a NULL pointer.  This represents an undefined string, for example the
second parameter in the function call foo(1,,2), and is not the same
as an empty string, for example the second parameter in the function
call foo(1,'',2).

Associated with the RXSTRING structure are the following helper macros:

   MAKERXSTRING(rxstring,ptr,len)
                       - sets the strptr field of the string to the given
                         a pointer and the strlength field to the given
                         length.
   RXNULLSTRING(x)     - returns true if x is a NULL string.
   RXSTRLEN(x)         - returns the length of the string x.  This function
                         returns zero if x is a NULL string.
   RXSTRPTR(x)         - returns the strptr field of the string x.
   RXVALIDSTRING(x)    - returns true if x is neither NULL nor of length zero.
   RXZEROLENSTRING(x)  - returns true if x is not NULL but is of length zero.

Note that since these are macros they should not be trusted with arguments
that have side-effects.

1(b). Starting the REXX interpreter

The function RexxStart invokes the interpreter to execute a REXX program.

   long RexxStart(long argc,
                  PRXSTRING argv, 
                  PSZ *name,
                  PRXSTRING instore,
                  PSZ envname,
                  long calltype,
                  PRXSYSEXIT exits,
                  PSHORT rc,
                  PRXSTRING result);

The parameters are:

   argc:    the number of arguments passed to the program
   argv:    an array of argc RXSTRINGs containing the arguments passed to
            the program.  Any omitted arguments should be passed as NULL
            strings.
   name:    a name for the program.  This will usually be the file name of
            the program on disk (which will be searched for in the usual
            way as described in the REXX programming reference, but will
            not have any file extension added to it).  However, if the
            instore parameter contains the source of the program, then the
            name parameter is used only for the PARSE SOURCE instruction.
   instore: either NULL or a pointer to the first of two RXSTRINGs which
            define an in-storage REXX program.  If instore is NULL, then the
            program is loaded from a disk file named by the name parameter.
            Otherwise, instore[0] must be a valid RXSTRING which contains
            the source to be executed and instore[1] must be a NULL string.
            The source contained in instore[0] should be in the same format
            as it would be if it had just been loaded from disk.  Note that
            REXX/imc will not, at present, return a tokenised image of the
            program in instore[1].
   envname: either NULL or a null-terminated string which contains the name
            of the initial subcommand environment for the REXX program.  The
            environment name must be at most 30 characters in length.  If
            envname is NULL then a default will be chosen.  This will be
            the uppercased file extension, if this is present and suitable,
            otherwise the string "UNIX".
   calltype:one of the three integer values RXCOMMAND, RXSUBROUTINE
            or RXFUNCTION as defined in rexxsaa.h.  This determines
            the invocation method as given by the instruction
            "PARSE SOURCE . method .".  In addition, if the calltype
            is RXFUNCTION then any RETURN instruction which causes the
            program to end will be required to return a result.
   exits:   either NULL or a pointer to the first in an array of RXSYSEXIT
            structures defining the exits which will be used (see the
            section on system exits for more information).  The last item
            in the array must have an exit code of RXENDLST.  Exits will
            not be used if the exits parameter is NULL.
   rc:      a pointer to a short which will receive the numeric form of the
            result string.  If the result string is a whole number in the
            range -32767 to +32767 then it will be converted to an integer
            and stored in rc.  Otherwise, rc will be set to (short)(1<<15),
            but note that this is an extension which is present in REXX/imc
            only.  This parameter is documented as PLONG, but it seems to be
            PSHORT in most versions so for the time being it is a PSHORT in
            REXX/imc.
   result:  a pointer to an RXSTRING which will receive the result string
            returned by a RETURN or EXIT instruction from the REXX program,
            or NULL to indicate that the return value should be discarded.
            If the program did not return a result, then this parameter
            will be set to a NULL string.  If result points to an RXSTRING
            then the caller of RexxStart may set it to either a NULL string
            or a valid string.  If result is a valid string which is long
            enough to hold the result, then the result will be copied into
            that string and result->strlength will be set to indicate its
            length.  Otherwise, REXX will allocate (using malloc) a string
            to hold the result and the caller of RexxStart is responsible
            for freeing this storage.

The possible return values from RexxStart are:

   negative:  a syntax error (or other REXX error) occurred.  The absolute
              value of the return value will be the same as the REXX error
              number.
   zero:      the program ended normally.
   positive:  some error occurred which made it impossible to execute the
              program.  A return value of 3 means that the program could not
              be read in (although this number may change in the future).  A
              return value of 1 means that the parameters were incorrect or
              that the interpreter could not initialise properly.

Note that the interpreter will never return a result string to the caller
if an error occurred, and in this case the value of rc is undefined when
RexxStart returns.

RexxStart is recursive - that is, the application may call it from within
a subcommand handler, external function call or system exit even though a
previous call to RexxStart has still not finished.  It is not, however,
re-entrant, so if the operating system supports threads or lightweight
processes (LWPs), the SAA API should only be called from within a single
thread.

1(c). The Subcommand Interface

A subcommand handler is a function supplied by the application which
processes commands (that is, REXX instructions which consist only of
expressions, or occurrences of "command" in instructions of the form
"ADDRESS environment command").  Each subcommand handler must be registered
under an environment name, and these names are selected by the ADDRESS
instruction in REXX.

A subcommand handler must be declared as a function with the following
prototype:

   ULONG command_handler(
      PRXSTRING command,
      PUSHORT flags,
      PRXSTRING result);

where:

   command  is the command string created by REXX.  The character just
            after the end of the string is guaranteed to be a null, but
            the command may also contain other null characters.
   flags    is a pointer to a short integer to receive the completion status
            of the command.  The subcommand handler should set this to one
            of RXSUBCOM_OK, RXSUBCOM_ERROR or RXSUBCOM_FAILURE in order to
            indicate that the command completed successfully, completed with
            ERROR status, or completed with FAILURE status respectively.
   result   is a pointer to an RXSTRING which will receive the return
            code from the command in the form of a string (note that any
            numeric return code must be converted to a string before it
            can be passed to REXX).  This string will be assigned to the
            variable RC when the subcommand handler returns.  If result
            is a NULL string, then REXX will assign the string "0" to RC.

            REXX will set result to a 256-byte string before calling the
            subcommand handler.  The handler may store the result in this
            string (and set result->strlength to the length of the string),
            or (if the result is longer than that) it may allocate another
            using malloc.  If the handler allocates a new string to hold
            the result, then REXX will call free to release the storage
            after the handler returns.

The only valid return value from a subcommand handler seems to be 0.

The following functions are available to register, deregister and query
subcommand handlers:

ULONG RexxRegisterSubcomExe(
   PSZ envname,
   RexxSubcomHandler *handler,
   PUCHAR userarea);

   The RexxRegisterSubcomExe function registers the subcommand handler
   whose address is given by the parameter handler under the environment
   name given by the parameter envname.

   The userarea parameter may be NULL or it may point to a user-defined
   eight byte area of memory which will be associated with the subcommand
   handler.  The user area information may be retrieved with the
   RexxQuerySubcom function.

   The possible return values from RexxRegisterSubcomExe are:

   RXSUBCOM_OK        The handler was registered.
   RXSUBCOM_NOTREG    The handler was not registered because there was
                      another already registered under the same name.
   RXSUBCOM_NOEMEM    The handler was not registered due to lack of
                      memory.
   RXSUBCOM_BADTYPE   The handler was not registered due to a parameter
                      error.

ULONG RexxDeregisterSubcom(PSZ envname, PSZ module);

   The RexxDeregisterSubcom function deregisters the subcommand handler
   which was registered under the name given by the parameter envname.
   The module parameter is not used by REXX/imc.

   The possible return values from RexxDeregisterSubcom are:

   RXSUBCOM_OK        The handler was deregistered.
   RXSUBCOM_NOTREG    The handler was not found.
   RXSUBCOM_BADTYPE   The handler was not deregistered due to a parameter
                      error.

ULONG RexxQuerySubcom(PSZ envname, PSZ module, PUSHORT flag, PUCHAR userarea);

   The RexxQuerySubcom function queries any subcommand handler which might
   have been registered under the name given by the parameter envname.  The
   module parameter is not used by REXX/imc.  The result is both stored in
   the short integer pointed to by the flag parameter and returned as the
   result of the function.  If the userarea parameter is supplied, it must
   point to an eight-byte area which will receive the user area which was
   given when the subcommand handler was registered.

   The possible return values from RexxQuerySubcom are:

   RXSUBCOM_OK        The handler is registered.
   RXSUBCOM_NOTREG    The handler is not registered.
   RXSUBCOM_BADTYPE   The parameters were in error.

1(d). External Functions

An external function may be registered with REXX/imc using the SAA API.
After it has been registered, it may be called by a Rexx program as usual,
but only using the name under which it was registered.  The names of
functions are case-sensitive and unquoted function names are always
translated into upper case, so that a function to be called with the REXX
function call foo() must be registered under the name FOO.  This is a
difference from OS/2.  Functions registered using the SAA interface of
REXX/imc are searched just after the built-in functions, and at the same
time as functions loaded from ".rxfn" files (see section 2).  Function names
registered under the SAA interface of REXX/imc must not contain the slash
character (/).  Note that function names in REXX function calls have all
characters up to and including the last slash character removed before they
are matched against function names which have been loaded from ".rxfn" files
or registered under the SAA interface, so that "/tmp/FOO" matches a
function registered under the name "FOO".  [This was done so that the path
name of an auto-registering function may be specified, but will not
prevent the function from being found on subsequent calls when it has
already been registered.  This behaviour might be removed in a future
release.]

An external function to be registered using the SAA interface must be a
function with the following prototype:

   LONG function_handler(
      PSZ name,
      long argc,
      PRXSTRING argv,
      PSZ queuename,
      PRXSTRING result);

where:

   name      is a null-terminated string giving the name by which REXX
             called the function.
   argc      is the number of arguments passed to the function.
   argv      is an array of argc RXSTRINGs giving the arguments passed to
             the function.  Any omitted arguments will be passed as NULL
             strings.  The character just after the end of each argument
             which is present is guaranteed to be a null, but the arguments
             may also contain other null characters.
   queuename is the null-terminated name of the current queue, which is
             currently meaningless in REXX/imc and will equal the string
             "SESSION".
   result    is a pointer to an RXSTRING which will receive the result from
             the function.  If the function does not return a result, then
             it should set this RXSTRING to a NULL string.  If the function
             handler was called as a function, then the result will be used
             directly (and an error will be raised if the function did not
             return a result).  If it was called as a subroutine, the result
             (if any) will be assigned to the REXX variable RESULT.

             REXX will set result to a 256-byte string before calling the
             function.  The function may copy the result into this string
             (and set result->strlength to the length of the result), or
             (if the result is longer than 256 bytes) it may allocate a new
             string using malloc and set the result string to that.  If the
             function handler allocates a new string, REXX will use free to
             release it when the function returns.

The valid return values from a function handler are:

     0    The function completed successfully.
    40    An error occurred.  The REXX interpreter will raise error 40
          (incorrect call to routine) when the function returns.  Note
          that if the function returns this value, it must not return a
          result.

The following functions are available to register, deregister and query
external functions:

ULONG RexxRegisterFunctionExe(PSZ funcname, RexxFunctionHandler *handler);

   The RexxRegisterFunctionExe function registers the function given by
   the handler parameter under the name given by the funcname parameter,
   which is a null-terminated string.

   The possible return values from RexxRegisterFunctionExe are:

   RXFUNC_OK       The function was registered.
   RXFUNC_DEFINED  The function was not registered because it has already
                   been registered or loaded from a ".rxfn" file.
   RXFUNC_NOMEM    The function was not registered due to lack of memory.

ULONG RexxRegisterFunctionDll(PSZ funcname, PSZ dllname, PSZ entryname);

   The RexxRegisterFunctionDll call registers a function stored in a shared
   object file (or DLL).  The name of the shared object is given in the
   dllname parameter (see below).  The name of the function handler within
   the shared object is given in the entryname parameter, and the name by
   which Rexx will call the function is given by the funcname parameter.

   The dllname parameter may be either the exact path name of a file or a
   relative file name which will be searched for along a path given by one
   of the following: the REXXLIB environment variable; if that is not set
   the REXXFUNC environment variable; or if neither is set the compile-time
   default.  If the name of the shared object ends with ".rxfn" then this
   may be omitted from the dllname parameter.

   This version of the RexxRegisterFunctionDll function differs from the
   OS/2 version in that it attempts to load the function before returning
   control to the caller, and it returns an indication of whether this
   succeeded.  The possible return values are:

   RXFUNC_OK       The function was registered.
   RXFUNC_NOTREG   The function was not registered because the shared object
                   could not be loaded or did not contain the required entry
                   point.
   RXFUNC_DEFINED  The function was not registered because it has already
                   been registered or loaded from a ".rxfn" file.
   RXFUNC_NOMEM    The function was not registered due to lack of memory.

ULONG RexxDeregisterFunction(PSZ funcname);

   The RexxDeregisterFunction function deregisters the function which was
   previously registered under the name given by the funcname parameter,
   which is a null-terminated string.  Note that this function is also
   able to deregister functions which were loaded from ".rxfn" files.

   The possible return values from RexxDeregisterFunction are:

   RXFUNC_OK       The function was deregistered.
   RXFUNC_NOTREG   The function was not found.

ULONG RexxQueryFunction(PSZ funcname);

   The RexxQueryFunction function queries whether or not a function has
   been registered or loaded from a ".rxfn" file under the name given by
   the funcname parameter, which is a null-terminated string.

   The possible return values from RexxQueryFunction are:

   RXFUNC_OK       The function is registered.
   RXFUNC_NOTREG   The function is not registered.

1(e). System Exits

The application may define functions which REXX will call instead of using
its own system interface in certain circumstances, such as whenever it needs
to write out a line as a result of the SAY instruction.  The application
registers its system exit functions under names (which are similar to
environment names, although they occupy a separate name space) before
executing a REXX program.  When the application starts REXX, it specifies
the system exits which it wishes to handle and associates each with a named
exit handler.  Each system exit has a major function code and a subfunction
code; these are listed later in this section.

A system exit handler must be a function with the following prototype:

   LONG exit_handler(long exitcode, long subcode, PEXIT parmblock);

where:

   exitcode  is the major function code of the exit which the handler has
             been called to handle.
   subcode   is the subfunction code of the exit which the handler has been
             called to handle.
   parmblock is a pointer to a parameter block whose contents depend on
             the exit being handled.  The exit descriptions below give
             details on the parameter block required for each exit.  Some
             exits may not require a parameter block at all, in which case
             the parmblock parameter will be a NULL pointer.

             Since each exit requires a different kind of parameter block,
             the PEXIT data type has been declared as a union data type.  It
             is probably most convenient for each exit handler to convert
             the parameter block pointer into a pointer of the required type
             for the exit (which is allowed in C (I think!)).

The valid return values from a system exit handler are:

   RXEXIT_HANDLED      The exit handler processed the system exit as required.
   RXEXIT_NOT_HANDLED  The exit handler did not process the system exit, and
                       therefore REXX should behave as if the exit handler
                       had not been called.
   RXEXIT_RAISE_ERROR  An error occurred.  REXX will raise error 48 (failure
                       in system service) when the handler returns this
                       value.

A system exit handler should begin by checking the function and subfunction
codes, and return immediately with RXEXIT_NOT_HANDLED if they correspond to
an exit which the handler was not supposed to handle.

The following functions are available to register, deregister and query
system exit handlers.

ULONG RexxRegisterExitExe(PSZ name, RexxExitHandler *handler, UCHAR *userarea);

   The RexxRegisterExitExe function registers the system exit handler given
   by the handler parameter under the name given by the name parameter,
   which is a null-terminated string.

   The userarea parameter may be NULL or it may point to a user-defined
   eight byte area of memory which will be associated with the system
   exit handler.  The user area information may be retrieved with the
   RexxQueryExit function.

   The possible return values from RexxRegisterExitExe are:

   RXEXIT_OK       The handler was registered.
   RXEXIT_NOTREG   The handler was not registered because there is already a
                   system exit handler registered under the given name.
   RXEXIT_NOEMEM   The handler was not registered due to lack of memory.
   RXEXIT_BADTYPE  The handler was not registered due to a parameter error.

ULONG RexxDeregisterExit(PSZ name, PSZ module);

   The RexxDeregisterExit function deregisters the system exit handler which
   was registered under the name given by the name parameter, which is a
   null-terminated string.  The module parameter is not used by REXX/imc.

   The possible return values from RexxDeregisterExit are:

   RXEXIT_OK       The handler was deregistered.
   RXEXIT_NOTREG   The handler was not found.
   RXEXIT_BADTYPE  The parameters were in error.

ULONG RexxQueryExit(PSZ name, PSZ module, PUSHORT flag, PUCHAR userarea);

   The RexxQueryExit function queries any system exit handler which may have
   been registered under the name given by the name parameter, which is a
   null-terminated string.  The module parameter is not used by REXX/imc.
   The flag parameter is a pointer to a short integer which will be set to
   the return value from RexxQueryExit.  If the userarea parameter is not
   NULL, it must point to an eight-byte area of memory which will receive
   the user area which was given when the exit handler was registered.

   The possible return values from RexxQueryExit are:

   RXEXIT_OK       The handler is registered.
   RXEXIT_NOTREG   The handler is not registered.
   RXEXIT_BADTYPE  The parameters were in error.

Once the required system exit handlers have been registered, they may
be used by passing them to RexxStart in the "exits" parameter.  This
parameter is an array of structures of the form:

   typedef struct {
      char *sysexit_name;   /* name of exit handler */
      short sysexit_code;   /* major function code of system exit */
   } RXSYSEXIT;

Each of these structures associates a system exit handler which was
previously registered under the name given by the sysexit_name field
of the structure with the system exits whose major function codes agree
with the sysexit_code field of the structure.  Note that an exit handler
must handle all the subfunctions of any particular system exit; it may do
this by immediately returning RXEXIT_NOT_HANDLED as described earlier.

The last element of the array of RXSYSEXIT structures must have sysexit_code
set to RXENDLST.

The possible system exits are as follows.  Each major exit code is given
by a name of the form RXxxx, and each subfunction code is given by a name
of the form RXxxxyyy, where the RXxxx is the same as the major exit code.

RXCMD: Call a subcommand handler

   RXCMDHST: This exit is called when REXX is about to carry out a command.
             By default, REXX will call the appropriate subcommand handler
             to execute the command, but the exit may instead choose to
             process the command.  The parameter block for this exit is:

             typedef struct {
                struct {
                   unsigned int rxfcfail:1;   /* completed with FAILURE */
                   unsigned int rxfcerr:1;    /* completed with ERROR */
                } rxcmd_flags;
                char *rxcmd_address;          /* environment name */
                unsigned short rxcmd_addressl;/* environment length */
                char *rxcmd_dll;              /* not used by REXX/imc */
                unsigned short rxcmd_dll_len; /* not used by REXX/imc */
                RXSTRING rxcmd_command;       /* the command to be executed */
                RXSTRING rxcmd_retc;          /* the return string */
             } RXCMDHST_PARM;

             The handler may set either rxfcfail or rxfcerr to raise a
             FAILURE or ERROR condition, respectively.  The rxcmd_address
             parameter is the null-terminated name of the environment to
             which the command is being sent.  The rxcmd_command is an
             RXSTRING containing the command to be executed.  The character
             just after the end of the string is guaranteed to be a null,
             but the command may also contain other null characters.  The
             rxcmd_retc is an RXSTRING which is to receive the return code
             from the command as a string.  Any numeric return code must be
             translated into a string before it is returned.  REXX will
             provide a 256-byte buffer into which the return string may
             be copied.  The handler may allocate another using malloc, in
             which case REXX will use free to release it after the handler
             returns.
             
RXSIO: Perform input or output

   RXSIOSAY: This exit is called when REXX is about to write a line as a
             result of a SAY instruction.  The exit may choose to deal with
             the line as it requires; otherwise the interpreter will write
             the line to the standard output stream.  The parameter block
             for this exit is:

             typedef struct {
                RXSTRING rxsio_string;
             } RXSIOSAY_PARM;

             The rxsio_string is the string to be written out.  The
             character just after the end of the string is guaranteed
             to be a null, but the string may also contain other null
             characters.  The string will not contain an end-of-line
             character unless one was present in the SAY instruction.

   RXSIOTRC: This exit is called when REXX is about to write a line during
             tracing.  The exit may choose to deal with the line as it
             requires; otherwise the interpreter will write the line to
             the trace output stream (usually the standard error).  The
             parameter block for this exit is:

             typedef struct {
                RXSTRING rxsio_string;
             } RXSIOTRC_PARM;

             The rxsio_string is the string to be written out.  The
             character just after the end of the string is guaranteed
             to be a null.  The string will not contain an end-of-line
             character.

   RXSIOTRD: This exit is called when REXX is about to read a line of input
             as a result of the PARSE PULL instruction when the REXX stack
             is empty.  The exit may choose to supply a line of its own;
             otherwise the interpreter will read the line from the standard
             input stream.  The parameter block for this exit is:

             typedef struct {
                RXSTRING rxsiotrd_retc;
             } RXSIOTRD_PARM;

             The input line should be returned in the rxsiotrd_retc string.
             It should not contain any end-of-line character which might
             have been used to terminate the line of input (but it may
             contain other end-of-line characters).  REXX will provide a
             256-byte string in which the handler may place the input line.
             The handler may allocate its own using malloc, in which case
             REXX will use free to release it when the handler returns.

   RXSIODTR: This exit is called when REXX is about to read a line of input
             at a pause during interactive tracing.  The exit may choose to
             supply a line of its own; otherwise the interpreter will read
             the line from the standard input stream.  The parameter block
             for this exit is:

             typedef struct {
                RXSTRING rxsiodtr_retc;
             } RXSIODTR_PARM;

             The input line should be returned in the rxsiotrd_retc string.
             It should not contain any end-of-line character which might
             have been used to terminate the line of input.  REXX will
             provide a 256-byte string in which the handler may place the
             input line.  The handler may allocate its own using malloc, in
             which case REXX will use free to release it when the handler
             returns.

   Note: the PARSE LINEIN instruction and the built-in functions LINEIN,
   LINEOUT, CHARIN and CHARS do not call the RXSIO exit handler.

RXINI: Initialisation processing

   RXINIEXT: This exit is called when initialisation is complete, just
             before execution of the REXX program starts.  The exit handler
             may use this exit to perform initialisation functions such as
             setting REXX variables.  There is no parameter block for this
             exit.

RXTER: Termination processing

   RXTEREXT: This exit is called just after the REXX program has finished,
             and just before termination processing.  The exit handler
             may use this exit to perform terminatino functions such as
             retrieving REXX variables.  There is no parameter block for
             this exit.

1(f). The Variable Pool Interface

Variables in the REXX program may be accessed using the RexxVariablePool
function, which processes one or more request blocks arranged in a linked
list.  Each request is a structure of the form:

   typedef struct shvnode
   {
      struct shvnode *shvnext;
      RXSTRING shvname;
      RXSTRING shvvalue;
      ULONG shvnamelen;
      ULONG shvvaluelen;
      UCHAR shvcode;
      UCHAR shvret;
   } SHVBLOCK;

where:

   shvnext     is the address of the next request block, or NULL if this is
               the last request block.
   shvcode     is the request code.  Valid request codes are listed below.
   shvname     is an RXSTRING containing a REXX variable name.  It may be
               an input or an output parameter according to the request
               code.
   shvnamelen  is the length of the buffer which the shvname RXSTRING points
               to.
   shvvalue    is an RXSTRING containing the value of a REXX variable.
               It may be an input or an output parameter according to the
               request code.
   shvvaluelen is the length of the buffer which the shvvalue RXSTRING points
               to.
   shvret      is a return code which will be set when the request has been
               processed.  It will be set to the OR of zero or more of the
               following flags:

               RXSHV_NEWV   the named variable was uninitialised before the
                            request was processed
               RXSHV_LVAR   no more variables are available for an
                            RXSHV_NEXTV request.
               RXSHV_TRUNC  A returned variable name or value was truncated
                            because the supplied RXSTRING was too short to
                            hold the name or value.
               RXSHV_BADN   An invalid variable name was given.
               RXSHV_MEMFL  The request was not processed due to lack of
                            memory.
               RXSHV_BADF   An invalid function code was given.

The valid request codes and their meanings are:

   RXSHV_SYSET: Symbolic set.  The name given in the shvname field is
                interpreted as a variable as if it were present in a REXX
                program.  It is set to the value given in the shvvalue
                field.
   RXSHV_SET:   Direct set.  The variable whose name matches that given in
                the shvname field is set to the value given in the shvvalue
                field.
   RXSHV_SYFET: Symbolic fetch.  The name given in the shvname field is
                interpreted as a variable as if it were present in a REXX
                program.  Its value is fetched and stored in the shvvalue
                RXSTRING.  If the application has set this to a NULL string,
                then REXX allocates one using malloc.  The application
                is responsible for freeing this storage.  Otherwise,
                shvvaluelen gives the maximum length of a string which REXX
                can store in the shvvalue RXSTRING.  If the value is longer
                than this then it is truncated.  The RXSHV_TRUNC flag will
                then be set in shvret.
   RXSHV_FETCH: Direct fetch.  The value of the variable whose name matches
                that given in the shvname field is fetched and stored in the
                shvvalue RXSTRING, as in the RXSHV_SYFET request.
   RXSHV_SYDRO: Symbolic drop.  The name given in the shvname field is
                interpreted as a variable as if it were present in a REXX
                program.  It is dropped (that is, it becomes undefined).
   RXSHV_DROPV: Direct drop.  The variable whose name matches that given
                in the shvname field is dropped (that is, it becomes
                undefined).
   RXSHV_NEXTV: Fetch next variable.  Each time this request is processed
                the interpreter returns the name and value of a variable
                which is currently accessible by the executing REXX program.
                The interpreter keeps track of which variables have been
                returned, and successive RXSHV_NEXTV requests will return
                different variables (in no particular order) until all the
                accessible variables have been returned.  When there is no
                variable left to return, the RXSHV_NEXTV request will set
                the RXSHV_LVAR flag in shvret and will leave the returned
                variable and value undefined.  The information about which
                variables have been returned is reset every time the REXX
                program resumes execution, and also at every set, fetch or
                drop request from the variable pool.

                The name of each returned variable will be stored in the
                shvname field of the request block.  If the application
                has set this to a NULL string then REXX allocates one using
                malloc.  The application is responsible for freeing this
                storage.  Otherwise, shvnamelen gives the maximum length
                of a string which REXX can store in the shvname RXSTRING.
                If the name is longer than this then it is truncated.  The
                RXSHV_TRUNC flag will then be set in shvret.

                The value of each variable is returned in an analogous
                manner in the shvvalue field (in exactly the same way as
                for the RXSHV_SYFET and RXSHV_FETCH requests).

                In the current release of REXX/imc, simple symbols and
                stems are returned in (approximately) the order in which
                they became defined.  The compound symbols of any one stem
                are returned consecutively in a similar order, just after
                the stem (if any) is returned.  Note that it is in general
                not possible to tell the difference between a stem being
                returned (for example, after the instruction foo.=3) and a
                compound variable whose tail has length zero (for example,
                after the instructions bar=''; foo.bar=3).  However, if
                "foo."  is returned after any other variable with that
                stem (including "foo."  itself), it is always the case
                that this occurrence of "foo."  is a compound variable.
                The converse is unfortunately not true.  That is, if
                "foo."  is the first variable with that stem, it is not
                necessarily a stem variable unless another copy of "foo."
                appears, in which case the first one is a stem and the
                second is a compound variable.

A symbolic variable name is one which is interpreted according to REXX
rules.  That is, it must contain only letters, digits, dots, and a small
number of other characters that are valid in symbols and must not start
with a digit or dot; it is uppercased before use, and each simple symbol
component of a compound symbol (except the stem) is replaced by its value
before use.

A direct variable name is the exact name of a variable which appears in
the variable pool (and it is the kind of variable name that RXSHV_NEXTV
returns).  It is the kind of name that a symbolic variable name turns into
after it has been processed as described in the above paragraph.  That part
of the name up to the first dot must satisfy the conditions for a symbolic
name and must be in upper case.  After the first dot, the name is allowed
to contain any character.

Variable pool requests are processed by the function:

ULONG RexxVariablePool(PSHVBLOCK RequestBlockList);

The parameter is a pointer to the first request block in the linked list.
The return value may be RXSHV_NOAVL, meaning that the variable pool API is
not available.  In this case, none of the requests will have been processed.
The API is made available just before execution of a program begins (just
before the RXINIEXT exit is called) and may be used until just after the
execution finishes (just after the RXTEREXT exit is called).

If the return value is not RXSHV_NOAVL, then it will be the OR of all the
return codes which have been returned individually in the shvret fields of
the request blocks.
______________________________________________________________________________

2. Writing external functions for REXX/imc

There are four ways to write external functions for REXX/imc:

  (a) in REXX
  (b) using the SAA application programming interface
  (c) as a ".rxfn" file, and
  (d) as a Unix program.

External functions in REXX are covered in the REXX programming reference.
The SAA application programming interface for external functions is covered
in section 1(d).  The remaining methods are described in this section.

2(c). Writing a ".rxfn" file

A function written as a ".rxfn" file will be searched for and linked in
with the interpreter at the time when it is first requested.  This gives an
advantage over using the SAA API in that SAA functions must be registered by
the application before they may be used by a REXX program - though this
is made easier by the inclusion of the RxFuncAdd REXX function in the
interpreter.  In general, the function(s) in a ".rxfn" file may either be
SAA function handlers as described above or specially written functions
for REXX/imc.  However, the latter type is the only one supported for
stand-alone functions; files containing only SAA functions must be supplied
as a library with a ".rxlib" file (see section 3).  This is because it is
the ".rxlib" file which tells the interpreter that the functions must be
called using the SAA calling sequence (either that, or a REXX/imc-style
function must use the SAA interface to register all the SAA functions).

A ".rxfn" file should be compiled and then linked in the normal way for
shared objects.  This differs between operating systems, but if the "Make"
program knows how to compile shared objects on your system then try making
rxmathfn.rxfn to see what flags it uses.  For a stand-alone function the
name of the output file should be the name by which the function is to
be called with ".rxfn" appended, all in lower case.  If this file is in
the rexx function search order (see the section on function or subroutine
invocation in the REXX/imc programming reference) then the file will be
loaded and linked in with the interprter automatically the first time that
the function is called.  Future calls to the same function will not have to
load the function from a file.

The REXX/imc-style function is described in the remainder of this section.
It is not really recommended for new functions because of portability
issues, so skip to the next section if this is not of interest.

A REXX/imc function will need access to several of the interpreter's
functions, so its source must include "functions.h".  It may also need
access to certain global variables, in which case it should include
"globals.h".  Useful functions and global variables are listed below.
In addition, the function may call any routine from the API, in which
case it should include "rexxsaa.h" as described in section 1.

A REXX/imc function should be declared as:

    int rxfunction(char *name, int argc);

(including the name rxfunction).  The name parameter gives the name by which
the function was called, excluding any path name.  That is, any part of the
name up to and including the last slash (/) will have been removed.  This
may be used to distinguish between several function calls that have all
been implemented by the same routine (this is more common in a function
library; see the section on function libraries).  The argc parameter gives
the number of arguments which were passed to the function.  These will be
placed on the calculator stack in LIFO order.  Any missing parameters will
have been stacked as strings of length -1.

The function will be expected to remove all its parameters from the
calculator stack and either

  (i) place a result on the calculator stack and return 1, or
 (ii) return 0 without placing anything on the calculator stack.  This means
      that the function has not returned a result.

However, the function may choose to return an error.  In this case, it
need not remove all arguments from the calculator stack.  A valid error
code is a negative number whose absolute value is the number of a REXX
error.  When the function returns, that error will be reported.

REXX/imc contains a function declared as follows:

   int funccall(RexxFunctionHandler *func,char *name,int argc);

This function enables a function that has a REXX/imc-style calling sequence
to call a function that has an SAA-style calling sequence.  For example,
if function_handler is an external function designed for use with the SAA
API, then it can be saved as a REXX/imc-style ".rxfn" file by appending the
following function:

   int rxfunction(char *name, int argc)
   {
      return funccall(function_handler,name,argc);
   }

This gives the SAA function the advantage of being able to be loaded on
demand instead of having to be registered.

A single function stored in a REXX/imc file should not contain a public
symbol called rxdictionary; this is reserved for function libraries.

Useful functions, including functions to retrieve arguments and stack the
answer, are the following:

char *delete(len)  int *len;

Deletes a string from the calculator stack, and returns an address where it
can be found.  On return, len will be set to the length of the argument.
The string is guaranteed to be followed by two bytes of available memory,
so that the application may teminate it with a null character if necessary,
and the string may be written to.  The string is not guaranteed to be
null-terminated when it is unstacked.  The string is not actually moved in
memory, so it will be invalidated whenever the calculator stack is changed
(that means that it may not be used as an argument to stack()).  However,
further calls to delete() will not corrupt the string.

int getint(flag)  int *flag;

Deletes a string from the calculator stack, interprets it as an integer, and
returns the result.  If the string is not a number which can be held in an
int variable, the function will die.  If the string is not an integer and
the flag is non-zero, the function will die, otherwise the number will be
converted into the nearest integer.

void stack(string,len)  char *string; int len;

Copies the given string of the given length on to the calculator stack.

void stackint(i)  int i;

Stacks a string representing the integer i on the calculator stack.

int isnull()

Returns 1 if the next value to be unstacked is null (that is, it has
length -1 indicating an omitted parameter), and zero otherwise.

void die(rc)  int rc;

Raise the error whose code is rc.  The interpreter will then either halt
with diagnostics or signal to an appropriate label, according to the current
settings of "SIGNAL ON".  This function never returns to its caller.

int num(minus,exp,zero,len)  int *minus,*exp,*zero,*len;

Attempts to extract a number from the top value on the calculator stack,
returning it as a sequence of digits.  The value is always left stacked.  If
unsuccessful, num returns a negative number (except when the top value is
null, in which case num dies).  Otherwise, num stores a sequence of digits
in the workspace (see below), and returns the offset from the start of the
workspace to the start of the sequence of digits (which always equals the
old value of eworkptr).  The value eworkptr is updated to point past the end
of the sequence of digits.  The length of the sequence is returned in len.
If the number is zero, then zero is set to 1, and otherwise it is set to 0.
If it is negative, then minus is set to 1, and otherwise 0.  The exponent
stored in exp is such that if a decimal point were placed between the first
two digits of the sequence and the result were multiplied by ten to the
power exp, then the original number would be recovered.

void stacknum(num,len,exp,minus) char *num; int exp,len,minus;

A sequence of digits starting at address num and of length len is formatted
according to the Rexx rules for numerics and stacked.  The exponent "exp" and
sign "minus" are interpreted according to the rules in "num" above.

The following functions from the variable interface should probably not
be used.  Use the SAA API instead.

char *varget(name,namelen,len) char *name; int varlen; int *len;

The variable whose name is "name" and contains "namelen" characters is
searched for in the current symbol table.  If the name is a compound symbol
or a stem, then the first character of the name must have bit 7 set.  The
name is used as-is, that is, it is not translated to upper case, and if it
is a compound variable then no substitution occurs in the tail.  A pointer
to the variable's value is returned, and "len" is set to its length.  If the
variable has not been assigned a value then "len" and the result are zero
and the null pointer, respectively.  The copy of the value which is returned
must not be changed in any way.  It may be invalidated whenever the symbol
table is changed (and may not be used as a parameter to varset()).

void varset(name,namelen,value,len) char *name,*value; int namelen,len;

The parameters "name" and "namelen" name a variable and satisfy the same
conditions as in varget above.  The parameters "value" and "len" describe
the position and length respectively of a string which is to be assigned to
the variable.  The assignment always succeeds unless there is insufficient
memory available, in which case the routine dies.

Note: the variable name and the string may contain arbitrary characters, and
neither is validated.  If you assign a value to a simple symbol called, e.g.
"blah" (in lower case) or "XYZ.123" (containing a dot), etc.  then the
symbol will not be accessible to the Rexx program, but it may be recovered
using varget(), provided it has not been hidden or destroyed by a PROCEDURE
instruction.

Any other function from the Rexx source may be used, but they are [or
perhaps are not!] described elsewhere.  Try in the source itself...

A function may use global data from Rexx.  It may either include the
header file "globals.h" (which defines all the global variables of the Rexx
interpreter) or simply include declarations for the particular variables it
uses.  Some useful variables are:

char *workptr; unsigned eworkptr,worklen;

The workspace, which may be used freely by a function.  The space starts at
workptr, and is of maximum length worklen.  The variable eworkptr may be
used to hold the length of the data currently stored in the workspace.

int precision,fuzz;

The setting of "NUMERIC DIGITS", and precision minus the setting of "NUMERIC
FUZZ", respectively.  That is, "precision" holds the precision of ordinary
calculations, and "fuzz" holds the precision of comparison operations.

char numform;

Zero if "NUMERIC FORM SCIENTIFIC" is in effect, and one if "NUMERIC FORM
ENGINEERING".

int ppc;

The number of the instruction being interpreted.

int rxstacksock;

A file descriptor which is connected to the Rexx stack process via a socket.

FILE *ttyin,*ttyout;

Streams which may be used to communicate with the terminal.


A Rexx memory structure (for example the workspace) may be extended using
the macros mtest or dtest.  These are called like functions, but note that
some arguments may be evaluated more than once or not at all.

mtest(memptr,alloc,length,extend)

Check that the desired length for the area, "length", is not greater than
the actual length, "alloc".  If it is, then attempt to reallocate the area,
pointed to by "memptr", with "extend" more bytes than its previous length.
The parameters memptr and alloc will be updated to reflect the new position
and length of the area.  The macro will die if not enough memory is
available.

dtest(memptr,alloc,length,extend)

Perform mtest on the four arguments, but return 0 if the area did not move,
and non-zero otherwise.  In order to use this macro, the current function
must contain variables:

char *mtest_old;
long mtest_diff;

If the memory pointer has moved, then mtest_diff contains the difference
(the new pointer minus the old).

2(d). Writing an external function as a Unix program

If a REXX program calls a function which is not internal or built-in and
cannot be found in any of the other categories of external function, then
REXX/imc searches for a file having the same name as the function in lower
case without a file extension, and this is assumed to be a Unix program.
The program may be written in any language supported by Unix such as C or
perl (even REXX, but note that although the programs will share the same
stack, a fresh copy of the interpreter will be loaded and some of the
parameter information will be lost as usual for a REXX program called
as a command).  If the program is interpreted then it must start with a
"#!" comment that names its interpreter, and the Unix kernel must be able
to recognise this form of comment. 

REXX/imc will execute the Unix program with argv[0] containing the name
by which the function was called, excluding any path name (that part of
the name up to and including the last slash character), and the rest of
argv[] containing the function's arguments.  The program will thus have
argc equal to one more than the number of arguments passed by REXX.  The
arguments will be null-terminated, which means that the arguments must not
contain null characters.

The program will be expected to print its result on its standard output,
followed by a newline character.  The program returns an empty string by
printing a single newline character.  The program returns no result by
printing nothing.

If the program finishes with an exit code of 255 (or -1), then REXX/imc will
raise error 50 (error in called routine).
______________________________________________________________________________

3. Writing Function Libraries for REXX/imc

Any of the four methods used in section 2 may be used to write a function
library, with some minor changes in certain circumstances.  A function
library is a single file which implements several functions (although there
is nothing to say that a library must contain more than one function).  Each
function library is accompanied by a ".rxlib" file, described below, which
lists the functions contained in the library.

If the file is a REXX program or a Unix program, then the same entry
point (the start of the program) is used for all the functions in the
library, and the program must examine the name by which it was called
in order to determine which function to carry out.  In a Unix program,
this is argv[0] as described in section 2(d).  In a REXX program, the
name may be found from PARSE SOURCE (in the fourth word).

If the file is a ".rxfn" file, then the functions have separate entry points
and must be listed in a dictionary within the file.  [The only time when
a ".rxfn" file would not have a dictionary is when it contains a single
function whose entry point is called rxfunction; in that case the only
difference between a stand-alone function and a library is the presence of a
".rxlib" file, described below.  The name by which Rexx calls the function
will be the name listed in the ".rxlib" file.]  A ".rxfn" dictionary is a
public symbol whose name is rxdictionary and whose type is an array of
dictionary elements, thus:

   typedef struct _dictionary {
      char *name;
      int (*function)();
   } dictionary;

   dictionary rxdictionary[];

Each name field must be initialised to the null-terminated name of a
function, as called by a REXX program.  The names are case-sensitive and
should usually be in upper case.  Each function field must be initialised
to the entry point of the function, which will have either the calling
sequence described in section 2(c) or the SAA calling sequence (whichever
choice is made, all functions should have the same calling sequence).  The
last element of the dictionary array must have both fields set to NULL.
When a ".rxfn" file is opened, all the functions in the dictionary are
registered automatically and will not need to be loaded again from the file
on subsequent references.

Once the functions have been collected together in one file as described
above, the library should be placed in a directory which REXX/imc will
search for function libraries (see the section on function or subroutine
invocation in the REXX/imc programming reference).  REXX/imc also needs
to be made aware of the library's contents.  This is done by writing a
text file whose name is the same as that of the library (but without the
file extension such as ".rxfn" or ".rexx") with ".rxlib" appended.  The
text file contains the names of the functions which may be found in the
library, separated by blanks, newlines or tab characters.  The names are
case-sensitive.  REXX/imc will only load a function library if the required
function name is found within this text file.  The name of the function
library itself is irrelevant; REXX/imc will read all ".rxlib" files found in
the appropriate directories and store the names found inside.

If the function library is a set of functions using the SAA interface
then the first token in the ".rxlib" file must be "rxsaa:".  If this is
missing then the functions will be called using the wrong protocol and the
interpreter will crash.

The set of mathematical functions, rxmathfn.*, is an example of a function
library.  It is supplied in two forms: a REXX program and a ".rxfn" file.
Either will work.

The rxmathfn.rexx function library demonstrates a kludge in the library
interface: if the ".rxlib" file contains the token "rxmathfn:" then the REXX
interpreter will skip the usual procedure of resetting NUMERIC DIGITS to 9
whenever it starts an external function.  The setting is still preserved,
and restored when the function returns, but if the ".rxlib" file contains
the token "rxmathfn:" then the function library can inherit the value.  This
token is only meaningful when the function library is a REXX program.  It is
ignored for the other forms of library.
______________________________________________________________________________

4. Accessing the REXX stack

 (a) Initialising

     When the application which requires access to the stack initialises, or
     when it first wants to use the stack, it should do the following:

     i.  If the environment variable RXSTACK is set, then a stack already
	 exists and uses a socket whose name is the value of RXSTACK.  This
	 should always happen if the application is called from within
	 REXX.  The application may choose to use this stack, or create
	 another.
     ii. In order to create a new stack, the application should run "rxque"
	 and store the output.  If the application prefers a particular
	 filename for the stack socket, it should give that as a parameter
	 to "rxque" and also set the environment variable RXSTACK to that
	 name.  The output from "rxque filename" will be the stack's process
	 number in the format "%d\n".  The output from "rxque" will be in
	 the form "RXSTACK=%s RXSTACKPROC=%d".  The "%s" in this format is
	 the stack's socket name, and the "%d" is the stack's process number.
	 The RXSTACK variable must be exported to the environment.  The
	 process number must be remembered, so that the stack can be
	 terminated later.
     iii.When a socket name has been obtained, the application should
         connect to it a socket of type SOCK_STREAM.  This socket will be
	 used in all further communication with the stack.

     The stack obtained by the application in this way can be accessed by
     any other process, providing it knows the socket name and has
     permission to access it.  This will usually be limited to descendants
     of the application.  In particular, if the application executes the
     REXX interpreter, the interpreter will use the same stack.

 (b) Terminating

     If the application did not create the stack, it has nothing further to
     do.  Otherwise it must kill the stack process (using the pid which was
     remembered earlier) with signal 15 (SIGTERM).

     In case the application crashes, the stack process will terminate after
     five minutes of inactivity if it finds that its parent no longer
     exists (that means that when the stack server is executed it should be
     executed as a child of the application, and not a grandchild or other
     descendant).

 (c) Communications

     There are three data types which may be communicated: commands, lengths
     and data.  A command is a single character.  A length is a sequence of
     six hex digits followed by a newline character: seven bytes in all.
     Data is an arbitrary sequence of characters of a pre-determined
     length.  All communications are written unbuffered.

     Each communication with the stack Each is initiated by the application
     writing a command character down the socket.  The possible command
     characters are as follows:

     N (for Number):  The stack responds by writing a length down the
       socket, representing the number of items on the stack.
     S (for Stack):  The stack expects the application to write a length
       value followed by a data item of that length.  It stacks that data
       item in lifo order.
     Q (for Queue):  The stack expects the application to write a length
       value followed by a data item of that length.  It queues that data
       item in fifo order.
     G (for Get):  The stack responds by writing the length of the top stack
       entry followed by its data, and removes the entry from the stack.
     P (for Peek):  The stack responds by writing the length of the top stack
       entry followed by its data, but leaves the stack unchanged.
     D (for Drop):  No further communication occurs, but the stack deletes
       its top entry.
     K (for Kill me): The stack expects the application to write a length
       value followed by one more byte.  The length value is interpreted as
       the pid of a process, and the byte as a signal number.  On receipt of
       this information, the stack server will (attempt to) kill the given
       process with the given signal.  This command may be used to make an
       application allow the stack to catch up, in case some of the
       communications are still en route to the server (the Num command could
       also be used for this purpose).

     If the stack process receives an incorrect command value or encounters
     an error while reading from the socket, then the connection to the
     offending application will be broken immediately.
______________________________________________________________________________

5. The REXX/imc internal data structures

REXX/imc has several data structures including the program, the label
table, the symbol table, and the program stack.  Each is kept as a block of
"malloc"ed memory which is grown dynamically as necessary (the "growing" is
usually performed by the mtest and dtest macros, mentioned above).

(a) The Source

    The source code is stored in memory as it appears in the REXX program
    on disk, except that newline characters are translated into zero bytes.
    The address of each line (numbered from 1 to the number of lines in the
    program) is stored in an array (which is another block of "malloc"ed
    memory), and accessed using the construction "source[num]".  The
    zeroth element of source stores the file name of the source, which is
    stored in a separately allocated block of memory.  The block allocated
    for the source itself is guaranteed to start at source[1].

(b) The Program

    The "program", or preprocessed source, is stored as a list of
    instructions, and prog[num] is a structure containing details about the
    "num"th instruction.  There are "stmts" instructions in this list.  Note
    that "THEN", "ELSE" and "OTHERWISE" are counted as individual
    instructions, and that null clauses do not appear in the list of
    instructions.  prog[0] contains some pointers to the starts of things
    (namely the block allocated for the tokenised program itself, the block
    allocated for the source, and the beginning of the first comment in the
    source).  prog[stmts] is a null instruction which points to the end of
    the source.
    
    Each instruction is obtained from the source by removing all comments
    and labels; stripping all unnecessary blanks and collapsing multiple
    spaces into one; concatenating lines together whenever the continuation
    character "," appears; tokenising keywords into special characters, and
    translating "^" (the variant NOT operator) into "\" (the real NOT
    operator).  The source is also checked for mismatched quotes, invalid
    labels and invalid characters during preprocessing.

    Whereas "source" always contains the source of the program being
    interpreted, "prog" can sometimes contain the list of instructions
    obtained from an "interpret" instruction.  In this case, the source
    pointer in prog[0] is used instead of source[1] when freeing the source.
    Also, certain instructions (such as "call") are required to save the
    current program temporarily and go back to the original program, by
    searching for it on the program stack.

    The current instruction number within the program is stored in the global
    variable ppc.  The current character position within the program line is
    stored in a local variable, often called lineptr.

    Each prog[num] consists of the following structure, called "program":

       int num;         The line number in the source where the instruction
                        originates - used when tracing source instructions.
       char *source;    The start of this instruction in the source
       char *sourcend;  The end of this instruction in the source
       int related;     Reserved for future use
       char *line;      The address of the tokenised instruction

    The source between "source" and "sourcend" is the current instruction
    including any comments on the same line but not including labels.
    Comments on separate lines and labels will appear after "sourcend" or
    before "source".

(c) The Labels    

    Labels within a program are separated off and stored in a table while
    the program is being preprocessed.  The table is stored in a block of
    memory at address labptr and of length lablen.  While the table is being
    built up the length of data so far is elapbtr.  The table consists of
    the concatenation of elements in the following format:

       int    total length of this element
       int    instruction number of label
       char[] name of label, terminated with a zero character and padded [*]

    The last element in the table is followed by the integer zero.

    [*] In all the data structures used by REXX/imc, variable-length string
    entries are padded (with random bytes) to a multiple of 4 bytes, in
    order that later data is aligned to the Sun SPARCstation's requirements.
    The alignment is done by macros in const.h and may be changed.

(d) The Calculator Stack

    The calculator stack is simply a list of values in temporary storage
    during the evaluation of an expression.  Expressions are in effect
    translated to reverse polish notation (e.g. 1+2 becomes 1 2 +), with
    each operation stacking and removing values as appropriate.  The stack
    is stored in a block of memory addressed by cstackptr and of cstacklen
    bytes.  The total size of the data on the stack is ecstackptr.  Each
    element on the stack consists of a string (padded as necessary [*])
    followed by its integer length.

(e) The Workspace

    The workspace is a block of memory which is used by various parts of the
    interpreter to store transient data.  It is addressed by workptr and is
    of length worklen.  Some routines (especially num()) maintain the length
    of the currently stored data in eworkptr.

(f) The Symbol Table

    The symbol table is a multiple-level associative array containing the
    definitions of all the REXX symbols which have been assigned values.  It
    is stored in a block of memory addressed by vartab and of length varlen.

    Each level of the table is a separate entity, referring to the active
    variables of a program fragment which used the PROCEDURE instruction to
    hide the earlier levels, except that each level may contain pointers to
    earlier levels as a result of the PROCEDURE EXPOSE instruction.

    The start of each level is stored in the array varstk[] as an integer
    offset from the start of the entire table.  The number of levels is
    varstkptr, and the number of elements in the array is varstklen.  The
    total length of all current levels of the symbol table is
    varstk[varstkptr+1].

    Each level of the symbol table contains all currently active simple
    symbols and stems as a binary search tree.  The elements of the tree are
    in the following format (as described by the varent data type):

       int    total length of this element
       int    position of the left child (as offset from start of level)
       int    position of the right child (as offset from start of level)
       int    length of the symbol's name
       int    amount of memory allocated to hold the symbol's value
       int    actual length of the symbol's value
       char[] the symbol's name, padded [*]
       char[] space for the symbol's value

    If the symbol is a stem, the terminating dot of the name is not stored,
    but the most significant bit of the first character of the name is set.

    If the length of the value is negative, then the symbol is considered
    to be undefined; it has been deleted by DROP or some other process.

    If the "amount of memory" element of the structure is negative, then
    this symbol is actually located in an earlier level; the negative value
    gives the level number, starting at -1 which means the earliest level
    (i.e. the first in the memory block).

    Each stem entry in the symbol table has a value containing a default
    value and a mini-symbol table.  The default value is stored first, in
    the format:

       int    the amount of space allocated to the default value
       int    the actual length of the default value
       char[] space for the default value

    Immediately following that are entries for all the tails, in exactly the
    same format as for the main symbol table.

(g) The Program Stack

    The program stack holds information relating to currently active control
    structures, e.g. function calls and DO-END blocks.  It is stored in a
    block of memory addressed by pstackptr and of length pstacklen.  The
    length of all data currently on the program stack is epstackptr.  The
    stack holds a sequence of various entries in the following formats, and
    the number of entries in the current function is held in pstacklev:

    for a simple DO-END block (type 0), a SELECT block (type 2),
    a DO WHILE or DO FOREVER block or (type 8), a "struct minstack" entry:

       int stmt    the statement number where the block started
       char *pos   the character where the block started (used for finding the
                   WHILE or UNTIL part of a repetitive DO instruction)
       int len     the length of this structure (16)
       int type    the type value (as mentioned above)

    for a repetitive DO with a control variable, an extended "struct
    minstack" entry:

       int stmt    the statement number where the block started
       char *pos   the character where the block started
       char[]      the limit value, padded [*] (empty string for "no limit")
       int         the length of the limit value
       char[]      the step value, padded [*]
       int         the length of the step value
       char[]      the name of the control variable, padded [*]
       int         the length of the control variable name
       int         the value which appeared after FOR, or -1 for "no value"
       int len     the total length of this structure
       int type    the number 10.

    for a repetitive block introduced by "DO count", a "struct forstack" entry:

       int stmt    the statement number where the block started
       char *pos   the character where the block started
       int fornum  the value specified after "DO"
       int len     the length of this structure (20)
       int type    the number 15.

    for an internal function call, a "struct procstack2" entry:

       int stmt    the statement number where the function call ocurred
       char *csp   the caller's cstackptr
       int ecsp    the caller's ecstaclptr
       int csl     the caller's cstacklen
       char trc    the caller's trace flag
       char tim    the caller's timestamp flag
       char form   the caller's NUMERIC FORM (0 for SCIENTIFIC)
                   the compiler will probably insert one byte here
       int digits  the caller's NUMERIC DIGITS
       int fuzz    the caller's "NUMERIC DIGITS minus NUMERIC FUZZ"
       long mic    the caller's timestamp microseconds value
       long sec    the caller's timestamp seconds value
       int address1 the caller's environment number (for ADDRESS)
       int address2 the caller's alternate environment number
       program *prg the program which was being interpreted at the time
       int stmts   the number of statements in that program
       int len     the length of this structure (60)
       int type    the number 11, becoming 12 when the PROCEDURE instruction
                   has been executed
    Note: the program is stored in case it was generated by "interpret"; if
    that is so then the "real" program will be reinstated before the call.

    for an INTERPRET instruction, a "struct interpstack" entry:

       int stmt     the statement number where the INTERPRET occurred
       program *prg the program which was being interpreted at the time
       int stmts    the number of instructions in that program
       int len      the length of this structure (20)
       int type     the number 14.

    for a command typed during interactive trace mode, a "struct
    interactstack" entry (note that a "struct interpstack" entry also
    appears above this):

       int stmt    the statement number where the interruption occurred
       char *csp   the interrupted program's cstackptr
       int ecs     the interrupted program's ecstackptr
       int csl     the interrupted program's cstacklen
       int len     the length of this structure (16)
       int type    the number 16.

    Occasionally, the interpreter stacks a program line with the sole intent
    of having it appear in the traceback.  Such an entry would be in the
    format of a "struct errorstack":

       int stmt     the statement number where the error occurred
       program *prg the program where the error occurred
       int stmts    the number of statements in this program
       int len      the length of this structure (20)
       int type     the number 20

    Note that external calls are no longer stored on the program stack.  For
    most purposes, they can be seen to be executed by a separate incarnation
    of the interpreter.
       
(h) The "Hash" Tables

    There are three "hash" tables, each arranged in a similar way to one
    level of the symbol table; however the value of each symbol in the hash
    table is a single void* pointer rather than a string of characters.
    There are three hash tables, each occupying a separate block of memory
    addressed by hashptr[i] and of length hashlen[i] (for i=0,1,2).  They
    are used to store environment variables, details of open files, and
    details about loaded functions respectively.  Each element of a hash
    table is arranged as follows (and as indicated in the "hashent" data
    type):

       int    length of this element
       int    position of the left child
       int    position of the right child
       void*  value of the element
       char[] name of the element, terminated by a zero byte and padded [*]

    The value of each element may be one of the following:

    In hash table 0:  a pointer to the string "NAME=VALUE" which has been
    used in a putenv() call.

    In hash table 1:  either a null pointer, or a pointer to a block of
    memory which contains a "struct fileinfo" followed by a zero-terminated
    filename (which may be empty if the file name is unknown).  The "struct
    fileinfo" is described in const.h.

    In hash table 2:  a pointer to a "funcinfo" structure containing the
    address of a loaded function.  One of the functions loaded from each
    function package also contains the handle which was returned from
    dlopen().

(i) The Signal Stack

    REXX stores the context of each invocation of the interpreter()
    function, so that it can be restored whenever an EXIT or a caught signal
    is encountered.  The context is stored in the array sigstack[], which at
    any time has sigstacklen elements allocated to it.  The number of the
    highest used element of sigstack[] is interplev.  Each entry of the
    signal stack contains:

       short bits    The combined bits for all SIGNAL ON traps which are on
       short bitson  ...all SIGNAL ON traps which were executed at this level
       short callon  ...all CALL ON traps which are on
       short delay   ...all conditions which are delayed
       char type     1 if a "signal" trap just occurred, 2 if "call", 0 if none
       char which    The number for the condition which just occurred (if any)
       char *data    A description for for the condition which just occurred
       int ppc[6]    The statement numbers to jump to for all the conditions
                     or minus the statement number to flag with "label not
		     found" if a condition occurs
       jmp_buf jmp   The context of this level of the interpreter.

    Note: a negative number in ppc[i] means that the trap instruction for
    this condition named a non-existent label.  -ppc[i] will be the
    statement number of this trap instruction.  This means that we can
    delay the "label not found" error until it actually happens: moreover,
    we can include the condition trap instruction in the traceback.
    However, an interpreted condition trap instruction is not guaranteed to
    stay around, and therefore it is reported as an error immediately if it
    names a non-existent label.

(j) The Shell's Hash Table

    The builtin shell keeps a record of where it found each command in a
    hash table (yes, a real one ;-) ).  The variable "hashtable" points to
    an array of bucket pointers, and the variable "hashbuckets" holds the
    number of pointers in the table.  A bucket pointer is null if there are
    no entries in the bucket; otherwise it points to a hashitem structure,
    representing the first item in the bucket.  That item may in turn point
    to another item in the bucket.  The items in each bucket are kept in
    alphabetical order, to reduce the average time taken for an unsuccessful
    search (or an insertion).  Each item contains the following information:

       struct _hashitem *next  The next item in the bucket, or null
       int hits                Number of times this has been found
       int expense             Position within $PATH
       int dot                 Whether dot occurred in the path before this
       int data                Offset from end of header to data
       char[]                  The key; a string of characters ending with 0.
       char[]                  The data; another nul-terminated string.
