%
%  The Regina Rexx Interpreter
%  Copyright (C) 1992-1994  Anders Christensen <anders@pvv.unit.no>
%


\chapter{Interfacing Rexx to other programs}
\label{ch:saaapi}


\begin{it} 
   This chapter describes an interface between a {\rexx} interpreter and
   another program, typically written in C or another high level, compiled
   language. It is intended for application programmers who are
   implementing {\rexx} support in their programs. It describes the
   interface known as the {\rexx} SAA API. 
\end{it}


\section{Overview of functions in SAA}

The functionality of the interface is devided into some main areas:
\begin{description}
\item[Subcommand handlers] 
   (section \ref{sect:subcom}) which trap and handle a command to an
   external environment.

\item[Interpreting]
   {\rexx} scripts (section \ref{sect:execute}), either from a disk
   file, or from memory.

\item[Variable interface]
   (section \ref{sect:varpool}), which makes it possible to access the
   variables in the interpreter, and allows operations like setting,
   fetching and dropping variables.

\item[System exits]
   (sections \ref{struct:sysexit} and \ref{sect:sysexit}), which are
   used to hook into certain key points in the interpreter while it
   executes a script.
\end{description}

In the following sections each of these areas are described in detail,
and a number of brief but complete examples are given at the end of
the chapter.

The description is of a highly technical nature, since it is assumed
that the reader will be an application programmer seeking information
about the interface. Therefore, much of the content is given as
prototypes and C style datatype definitions. Although this format is
cryptic for non-C programmers, it will convay exact, compact, and
complete information to the intended readers. Also, the problems with
ambiguity and incompleteness that often accompany a descriptive prose
text are avoided.

\subsection{Include Files and Libraries}

All the C code that uses the {\rexx} application interface, must
include a special header file that contains the necessary definitions.
This file is called {\tt rexxsaa.h}. Where you will find this file,
will depend on you system and which compiler you use. 

Also, the interface part between the application and the {\rexx}
interpreter may be implemented as a library, which you link with the
application using the functions described in this chapter. The name of
this library, and its location might differ from system to system.
With Regina, it is called {\tt libregina.a}, and is produced when you
compile Regina. 


\subsection{Preprocessor Symbols}

Including a header file ought to be enough; unfortunately, that is not
so. Each of the domains of functionality listed above are defined in
separate ``sections'' in the {\tt rexxsaa.h} header file. In order for
these to be made available, certain proprocessor symbols have to be
set. For instance, you have to include the following definition:
\begin{verbatim}
   #define INCL_RXSHV
\end{verbatim}
in order to make available the definitions and datatypes concerning
the variable pool interface. The various definitions that can be set
are: 
\begin{description}
\item[{\tt INCL\_RXSUBCOM}]
   Must be defined in order to get the prototypes, datatypes and
   symbols needed for the subcommand interface of the API.

\item[{\tt INCL\_RXSYSEXIT}]
   Must be defined in order to get the prototypes, datatypes, and
   symbols needed for the system exit functions

\item[{\tt INCL\_RXSHV}]
   Must be set in order to get the prototypes, symbols and datatype
   definitions necessary to use the {\rexx} variable pool. 
\end{description}


\subsection{Allocating and Deallocating Space}

For several of the functions described in this chapter, the
application calling them must allocate or deallocate dynamic memory.
Depending on the operating system, compiler and {\rexx} interpreter,
the method for these allocations and deallocations might vary. Regina
uses {\tt malloc()} and {\tt free()} in all these situations. 



\section{Datastructures}

In this section, some datastructures relevant to the
application interface to {\rexx} are defined and described. These are:
\begin{description}
\item[{\tt RXSTRING}] 
   Holds a {\rexx} string.

\item[{\tt RXSYSEXIT}]
   Holds a definition of a system exit handler. Used when starting a
   {\rexx} script with {\tt RexxStart}, and when defining the system
   exit handlers. 
\end{description}


\subsection{The {\tt RXSTRING} structure}

The SAA API interface uses ``Rexx strings'' which are stored in
the structure {\tt RXSTRING}. There is also a datatype {\tt
PRXSTRING}, which is a pointer to {\tt RXSTRING}. Their definitions
are: 
\begin{verbatim}
   typedef struct {
      unsigned char *strptr ;    /* Pointer to string contents */
      unsigned long strlength ;  /* Length of string */
   } RXSTRING ;

   typedef RXSTRING *PRXSTRING ;
\end{verbatim}
The {\tt strptr} field is a pointer to an array of
characters making up the contents of the ``Rexx string'', while {\tt
strlength} holds the number of characters in that array. 

Unfortunately, there are some inconsistencies in naming of various
special kinds of strings. In {\rexx} (TRL), a ``null string'' is a
string that has zero length. On the other hand, the SAA API operates
with two kinds of special strings: ``null strings'' and ``zero length
strings''. The latter is a string with zero length (equals null
strings in {\rexx}), while the former is a sort of ``undefined'' or
``empty'' string, which denotes a string without a value. The ``null
strings'' of SAA API are used to denote unspecified values (e.g.~a
parameter left out in a subroutine call). In this chapter, when the
terms ``null strings'' and ``zero length strings'' are quoted, they
refer to the SAA API style meaning.

A number of macros are defined, which simplifies operations on
{\tt RXSTRING}s for the programmer. In the list below, all parameters
called {\tt x} are of type {\tt RXSTRING}.
\begin{description}
\item[{\tt MAKERXSTRING(x,content,length)~}]
   The parameter {\tt contents} must be a pointer to {\tt char}, while
   {\tt length} is integer. The {\tt x} parameter will be set to the
   contents and length supplied. The only operations are assignments;
   no new space is allocated and the contents of the string is not
   copied. 

\item[{\tt RXNULLSTRING(x)~}] 
   Returns true only if {\tt x} is a ``null string''.
   I.e.~{\tt x.strptr} is {\tt NULL}.

\item[{\tt RXSTRLEN(x)~}]
   Returns the length of the string {\tt x} as an unsigned long. Zero
   is returned both when {\tt x} is a ``null string'' or a ``zero
   length string''.

\item[{\tt RXSTRPTR(x)~}]
   Returns a pointer to the first character in the string {\tt x}, or
   {\tt NULL} if {\tt x} is a ``null string''. If {\tt x} is a ``zero
   length string'', and non-{\tt NULL} pointer is returned.

\item[{\tt RXVALIDSTRING(x)~}]
   Returns true only if {\tt x} is neither a ``null string'' nor a
   ``zero length string'', i.e.~{\tt x} must have non-empty
   contents.

\item[{\tt RXZEROLENSTRING(x)~}]
   Returns true only if {\tt x} is a ``zero length string''.
   I.e.~{\tt x.strptr} is non-{\tt NULL}, and {\tt x.strlength} is
   zero.
\end{description}

These definitions are most likely to be defined as preprocessor
macros, so you should never ``call'' them with ``parameters'' having
any side effects. Also note that at least {\tt MAKERXSTRING()} is
likely to be implemented as two statements, and might not work
properly if following e.g.~an {\tt if} statement. Check the actual
definitions in the {\tt rexxsaa.h} header file before using them in a
fancy context. 

One definition of these might be (don't expect this to be the case
with your implementation):
\begin{verbatim}
   #define MAKERXSTRING(x,c,l) ((x).strptr=(c),(x).strlength=(l))
   #define RXNULLSTRING(x)     (!(x).strptr)
   #define RXSTRLEN(x)         ((x).strptr ? (x).strlength : 0UL)
   #define RXSTRPTR(x)         ((x).strptr)
   #define RXVALIDSTRING(x)    ((x).strptr && (x).strlength)
   #define RXZEROLENSTRING(x)  ((x).strptr && !(x).strlength)
\end{verbatim}

Note that these definitions of strings differ from the normal
definition in C programs; where a string is an array of characters,
and its length is implicitly given by a terminating ASCII NUL character.
In the {\tt RXSTRING} definition, a string can contain any character,
including an ASCII NUL, and the length is explicitly given. 



\subsection{The {\tt RXSYSEXIT} structure}
\label{struct:sysexit}

This structure is used for defining which system exit handlers are to
handle which system exits. The two relevant datatypes are defined as:
\begin{verbatim}
   typedef struct {
      unsigned char *sysexit_name ;
      short sysexit_code ;
   } RXSYSEXIT ;

   typedef RXSYSEXIT *PRXSYSEXIT ;
\end{verbatim}

In this structure, {\tt sysexit\_name} is a pointer to the ASCII NUL
terminated string containing the name of a prevously registered (and
currently active) system exit handler. The {\tt sysexit\_code} field
is main function code of a system exit.

The system exits are divided into main functions and subfunctions. An
exit is defined to handle a main function, and must thus handle all
the subfunctions for that main function. All the functions and
subfunctions are listed in the description of the {\tt EXIT}
structure.




\section{The Subcommand Handler Interface}
\label{sect:subcom}

This sections describes the subcommand handler interface, which
enables the application to trap commands in a {\rexx} script being
executed and handle this commands itself. 


\subsection{What is a Subcommand Handler}

A subcommand handler is a piece of code, that is called to handle a
command to an external environment in {\rexx}. It must be either a
subroutine in the application that started the interpreter, or a
subroutine in a dynamic link library. In any case, when the
interpreter needs to execute a command to an external environment, it
will call the subcommand handler, passing the command as a parameter. 
Typically, an application will set up a subcommand handler before
starting a {\rexx} script. That way, it can trap and handle any
command being executed during the course of the script. 

Each subcommand handler handles one environment, which is refered to
by a name. It seems to be undefined whether upper and lower case
letters differ in the environment name, so you should assume they
differ. Also, there might be an upper limit for the length of an
environment name, and some letters may be illegal as part of an
environment name.

Regina allows any letter in the environment name, except 
ASCII NUL; and sets no upper limit for the length of an environment
name. However, for compatibility reasons, you should avoid
``uncommon'' letters and keep the length of the name fairly short.

The prototype of a subcommand handler function is:
\begin{verbatim}
   unsigned long handler(
      RXSTRING *command,
      unsigned short *flags,
      RXSTRING *returnstring
   ) ;
\end{verbatim}
After registration, this function is called whenever the
application is to handle a subcommand for a given environment. The
value of the paramaters are:
\begin{description}
\item[{\tt command~}]
   The command string that is to be executed. This is the resulting
   string after the command expression has been evaluated in the
   {\rexx} interpreter. It can not be empty, although it can be a
   ``zero-length-string''. 

\item[{\tt flags~}]
   Points to a {\tt unsigned short} which is to receive 
   the status of the completion of the handler. This can be one of the
   three following: {\tt RXSUBCOM\_OK}, {\tt RXSUBCOM\_ERROR}, or {\tt
   RXSUBCOM\_FAILURE}. The contents will be used to determine whether
   to raise any condition at return of the subcommand. Do not confuse
   it with the return value. 

\item[{\tt returnstring~}]
   Points to a {\tt RXSTRING} which is to receive the return value
   from the subcommand. Passing the return value as a string makes it
   possible to return non-numeric return codes. As a special case, you
   might set {\tt returnstring.strptr} to {\tt NULL}, instead of
   specifying a return string of the ASCII representation of zero.
\end{description}

Note that it is not possible to return ``nothing'' in a subcommand,
since this is interpreted as zero. Nor is is possible to return a
numeric return code as such; you must convert it to ASCII
representation before you return.

The {\tt returnstring} string will provide a 256 byte array which the
programmer might use if the return data is not longer that that. If
that space is not sufficient, the handler can provide another area
itself. In that case, the handler should not deallocate the default
area, and the new area should be allocated in a standard fashion. 



\subsection{The {\tt RexxRegisterSubcomExe()} function}

This function is used to register a subcommand handler with the
interface. The subcommand handler must be a procedure located within the code of
the application. After registration, the {\rexx} interpreter can execute
subcommands by calling the subcommand handler with parameters
describing the subcommand.

The prototype for {\tt RexxRegisterSubcom()} is:
\begin{verbatim}
   unsigned long RexxRegisterSubcomExe( 
      signed char* EnvName,
      unsigned long (*EntryPoint)(),
      unsigned char* UserArea 
   ) ;
\end{verbatim}

All the parameters are input, and their significance are:
\begin{description}
\item[{\tt EnvName~}]
   Points to an ASCII NUL terminated character string which defines
   the name of the environment to be registered. This is the same name
   as the {\rexx} interpreter uses with the {\tt ADDRESS} clause in
   order to select an external environment. 

\item[{\tt EntryPoint~}]
   Points to the entrypoint of the subcommand handler routine for the
   environment to be registered. See the section on Subcommand
   Handlers for more information. There is an upper limit for the
   length of this name.

\item[{\tt UserArea~}]
   Pointer to an 8 byte area of information that is to be associated
   with this environment. This pointer can be {\tt NULL} if no such
   area is necessary.
\end{description}

The areas pointed to by {\tt EnvName} and {\tt UserArea} are copied to
a private area in the interface, so the programmer may deallocate or
reuse the area used for these parameters after the call has returned. 

The {\tt RexxRegisterSubcom} returns an {\tt unsigned long}, which
carries status information describing the outcome of the operation.
The status will be one of the {\tt RXSUBCOM} values:
\begin{description}
\item[{\tt RXSUBCOM\_OK~}]
   The subcommand handler was sucessfully registered.

\item[{\tt RXSUBCOM\_DUP~}]
   The subcommand handler was sucessfully registered. There
   already existed another subcommand handler which was registed with
   {\tt RexxRegisterSubcomDll()}, but this will be shadowed by the
   newly registered handler.

\item[{\tt RXSUBCOM\_NOTREG~}]
   Due to some error, the handler was not registered. Probably
   because a handler for {\tt EnvName} was already defined at a
   previous call to {\tt RexxRegisterSubcomExe()}.

\item[{\tt RXSUBCOM\_NOEMEM~}]
   The handler was not registed, due to lack of memory. 
   
\item[{\tt RXSUBCOM\_BADTYPE~}]
   Indicates that the handler was not registered, due to one or more
   of the parameters having invalid values. 
\end{description}



\subsection{The {\tt RexxRegisterSubcomDll} function}

This function is used to set up a routine that is located in a module
in a dynamic link library, as a subcommand handler. Some operating
systems don't have dynamic linking, and thus cannot make use of this
facility. The prototype of this function is:
\begin{verbatim}
   unsigned int RexxRegisterSubcomDll(
      unsigned char *EnvName,
      unsigned char *ModuleName,
      unsigned char *EntryPoint,
      unsigned char *UserArea,
      unsigned long DropAuth
   ) ;
\end{verbatim}
This function is not yet supported by Regina.



\subsection{The {\tt RexxDeregisterSubcom} function}

This function is used to remove a particular environment from the list
of registered environments. The prototype of the function is:
\begin{verbatim}
   unsigned int RexxDeregisterSubcom( 
      signed char* EnvName,
      signed char* ModuleName 
   ) ;
\end{verbatim}

Both parameters are input values:
\begin{description}
\item[{\tt EnvName~}]
   Pointer to ASCII NUL terminated string, which represents the name
   of the environment to be removed.

\item[{\tt ModuleName~}]
   Also an ASCII NUL terminated string, which points to the name of
   the module containing the subcommand handler of the environment to
   be deleted. Not currently in use by Regina.
\end{description}

The list of defined environments is searched, and if an environment
matching the one named by the first parameter are found, it is
deleted. The returnvalue will be a {\tt RXSUBCOM\_} macro, which is
{\tt OK} if the environment was successfully deleted, {\tt NOTREG} if
the environment was not found, and {\tt BADTYPE} if illegal parameters
are found.

Most systems that do have dynamic linking have no method for reclaiming
the space used by dynamically linked routines. So, even if you were
able to load a ``dll'', there are no guarantees that you will be able
to unload it. 


\subsection{The {\tt RexxQuerySubcom()} function}

This function retrieves information about a previously registered
subcommand handler. The prototype of the function is:
\begin{verbatim}
   unsigned int RexxQuerySubcom(
      signed char *EnvName,
      signed char *ModuleName,
      unsgined short *Flag,
      unsigned char *UserWord 
   ) ;
\end{verbatim}

Note that some of the documentation I've seen skips the {\tt Flag}
parameter. I don't know why, and I don't know what is correct, but I
guess it should be there. The significance of the parameters are:
\begin{description}
\item[{\tt EnvName}]
   Pointer to an ASCII NUL terminated character string, which names
   the subcommand handler about which information is to be returned. 

\item[{\tt ModuleName}]
   Pointer to an ASCII NUL terminated character string, which names a
   dynamic link library. Only the named library will be searched for
   the subcommand handler named by {\tt EnvName}. This parameter must
   be {\tt NULL} if all subcommand handlers are to be searched. 

\item[{\tt Flag}] 
   Pointer to a short which is to receive the value {\tt RXSUBCOM\_OK}
   or {\tt RXSUBCOM\_NOTREG}. In fact, this is the same as the return
   value from the function. 

\item[{\tt UserWord}]
   Pointer to an area of 8 bytes. The ``userarea'' of the subcommand
   handler is copied to the area pointed to by {\tt UserWord}. This
   parameter might be {\tt NULL} if the data of the ``userarea'' is
   not needed. 
\end{description}

Note that the datatype of the {\tt UserWord} may differ. All seem to
agree that its size is 8 byte, but the datatype might differ between
{\tt unsigned long} or {\tt unsigned char}. You would do best in
allocating it as 8 byte with good alignment

The returned value from {\tt RexxQuerySubcom()} can be one of:
\begin{description}
\item[{\tt SUBCOM\_OK~}]
   The subcommand handler was found, and the required information has
   been returned in the {\tt Flag} and {\tt UserWord} variables. 

\item[{\tt SUBCOM\_NOTREG~}]
   The subcommand handler was not found. The {\tt Flag} variable will
   also be set to this value, and the {\tt UserWord} variable is not
   changed. 

\item[{\tt SUBCOM\_BADTYPE~}]
   One or more of the parameters had illegal values, and the operation
   was not carried through. 
\end{description}




\section{Executing {\rexx} Code}
\label{sect:execute}

This sections describes the {\tt RexxStart()} function, which allows
the application to startup the interpreter and make it interpret
pieces of {\rexx} code. 


\subsection{The {\tt RexxStart()} function}

This function is used to invoke the {\rexx} interpreter in order to
execute a piece of {\rexx} code, which may be located on disk, as a
pretokenized macro, or as ASCII source code in memory.
\begin{verbatim}
   long RexxStart( 
      long ArgCount,
      struct rxstring *ArgList,
      char *ProgramName,
      struct rxstring *Instore,
      char *EnvName,
      long CallType,
      struct rxsysexit Exits,
      long *ReturnCode,
      strcut rxstring *Result 
   ) ;
\end{verbatim}

Of these parameters, {\tt ReturnCode} and {\tt Result} are
output-only, while {\tt Instore} is both input and output. The rest of
the parameters are input-only. The significance of the parameters are:
\begin{description}
\item[{\tt ArgCount}]
   The number of parameter strings given to the procedure. This is
   the number of defined {\rexx}-strings pointed to by the
   {\tt ArgList} parameter. 

\item[{\tt ArgList~}]
   Pointer to an array of {\rexx}-strings, constituting the
   parameters to this call to {\rexx}. The size of this array is give
   by the parameter {\tt ArgCount}. If ArgCount is greater than one,
   the first and last parameters are {\tt ArgList[0]} and 
   {\tt ArgList[ArgCount-1]}. If {\tt ArgCount} is 0, the value of
   ArgList is irrelevant. 

   If the {\tt strptr} of one of the elements in the array pointed to
   by {\tt ArgList} is NULL, that means that this parameter is
   empty (i.e.~unspecified, as opposed to a string of zero size).

\item[{\tt ProgName~}]
   An ASCII NUL terminated string, specifying the name of the {\rexx}
   script to be executed. The value of {\tt Instore} will determine
   whether this value is interpreted as the name of a (on-disk)
   script, or a pretokenized macro. If it refers to a filename, the
   syntax of the contents of this parameter depends on the operating
   system.

\item[{\tt Instore~}]
   Parameter used for storing tokenized {\rexx} scripts. This
   parameter might either be {\tt NULL}, else it will be a pointer to
   two {\tt RXSTRING} structures, the first holding the ASCII version
   of a {\rexx} program, the other holding the tokenized version of
   that program. See below for more information about how to use {\tt
   Instore}. 

\item[{\tt EnvName~}]
   Pointer to ASCII NUL terminated string naming the environment which
   is to be the initial current environment when the script is
   started. If this parameter is set to {\tt NULL}, the filetype is
   used as the initial environment name. What the filetype is, may
   depend on your operating system, but in general it is everything
   after the last ``{\tt .}'' in the filename.

\item[{\tt CallType~}]
   A value describing whether the {\rexx} interpreter is to be invoked
   in command, function or subroutine mode. Actually, this has little
   significance. The main difference is that in command mode, only
   one parameterstring can be passed, and in function mode, a value
   must be returned. In addition, the mode chosen will affect the
   output of the {\tt PARSE SOURCE} instruction in {\rexx}.

   Three symbolic values of integral type are defined, which can be
   used for this parameter: {\tt RXCOMMAND}, {\tt RXFUNCTION} and {\tt
   RXSUBROUTINE}. 

\item[{\tt SysExists~}]
   A pointer to an array of exit handlers to be used. If no exit
   handlers are to be defined, {\tt NULL} may be specified.
   Each element in the array defines one exit handler, and the element
   immediately following the last definition must have a {\tt
   sysexit\_code} set to {\tt RXENDLST}.
   
\item[{\tt ReturnCode~}]
   Pointer to an {\tt long} where the returncode is stored, provided
   that the returned value is numeric, and within the range
   -(2**15) to 2**15-1. I don't know what happens to ReturnCode
   if either of these conditions is not satisfied. It probably becomes
   undefined, which means that it is totally useless since the program
   has to inspect the return string in order to determine whether
   {\tt ReturnCode} is valid. Nor do I know why only 16 bits are used,
   when a long is 32 bits. 

\item[{\tt Result~}]
   Points to a {\rexx} string into which the result string is written.
   The caller may or may not let the {\tt strptr} field be
   supplied.  If supplied (i.e.~it is non-NULL), that area will be
   used, else a new area will be allocated. If the supplied area is
   used, its size is supposed to be given by the {\tt strlength}
   field. If the size if not sufficient, a new area will be allocated,
   by some systemdependent channel (i.e.~{\tt malloc()}), and the
   caller must see to that it is properly deallocated (using {\tt
   free()}. 
\end{description}

Note that the {\tt ArgCount} parameter need not be the same as the
{\tt ARG()} built-in function would return. Differences will occurr if
the last entries in {\tt ArgList} are ``null strings''.

The {\tt Instore} parameter needs some special attention. It is used to
directly or indirectly specify where to fetch the code to execute. The
following ``algorithm'' is used to determine what to execute: 
\begin{itemize}
\item
   If {\tt Instore} is {\tt NULL}, then {\tt ProgName} names the
   filename of an on-disk {\rexx} script which it to be read and
   executed.

\item
   Else, if {\tt Instore} is not {\tt NULL}, the script is somewhere
   in memory, and no reading from disk is performed.  If both {\tt
   Instore[0].strptr} and {\tt Instore[1].strptr} are {\tt NULL}, then
   the script to execute is a preloaded macro which must have been
   loaded with a call to either {\tt RexxAddMacro()} or {\tt
   RexxLoadMacroSpace()}; and {\tt ProgName} is the name of the
   macro to execute.

\item
   Else, if {\tt Instore[1].strptr} is non-{\tt NULL}, then {\tt
   Instore[1]} contains the pretokenized image of a {\rexx} script,
   and it is used for the execution.

\item
   Else, if {\tt Instore[0].strptr} is non-{\tt NULL}, then {\tt
   Instore[0]} contains the ASCII image of a {\rexx} script, just as
   if the script had been read directly from the disk (i.e.~including
   linefeeds and such). This image is passed to the interpreter, which
   tokenizes it, and stores the tokenized script in the {\tt
   Instore[1]} string, and then proceeds to execute that script. Upon
   return, the {\tt Instore[1]} will be set, and can later be used to
   reexecute the script without the overhead of tokenizing.
\end{itemize}

The user is responsible for deallocating any storage used by {\tt
Instore[1]}. Note that after tokenizing, the sourcecode in {\tt
Instore[0]} is strictly speaking not needed anymore. It will only be
consulted if the user calls the {\tt SOURCELINE()} built-in function.
It is not an error to use {\tt SOURCELINE()} if the source is not
present, but nullstrings and zero will be returned. 

The valid return values from {\tt RexxStart()} are:
\begin{description}
\item[Negative]
   indicates that a syntax error occurred during interpretation. In
   general, you can expect the error value to have the same absolute
   value as the {\rexx} syntax error (but opposite signs, of course).

\item[Zero]
   indicates that the interpreter finished executing the script
   without errors.

\item[Positive]
   indicates probably that some problem occurred, that made it
   impossible to execute the script, e.g.~a bad parameter value.
   However, I can't find any references in the documentation which
   states which values it is supposed to return. 
\end{description}

During the course of an execution of {\tt RexxStart()}, subcommand
handlers and exit handlers might be called. These may call any
function in the application interface, including another invocation of
{\tt RexxStart()}.

Often, the application programmer is interested in providing
support simplifing the specification of filenames, like an 
environment variable search path or a default file type. The {\rexx}
interface does support a default file type: {\tt .CMD}, but the user
may not set this to anything else. Therefore, it is generally up to the
application programmer to handle search paths, and also default file
types (unless {\tt .CMD} is ok).

If the initial environment name ({\tt EvnName}) is {\tt NULL}, then
the initial environment during interpretation will be set equal to the
file type of the script to execute. If the script does not have a file
type, it is probably set to some interpreter specific value. 



\section{Variable Pool Interface}
\label{sect:varpool}

This section describes the variable pool part of the application
interface, which allows the application programmer to set, retrieve and
drop variables in the {\rexx} interpreter from the application
program. It also allows access to other information. 

The C preprocessor symbol {\tt INCL\_RXSHV} must be defined if the
definitions for the variable pool interface are to be made available
when {\tt rexxsaa.h} is included. 



\subsection{Symbolic or Direct}

First, let us define two terms, ``symbolic'' variable name and
``direct'' variable name, which are used in connection with the
variable pool.

A symbolic variable name is the name of a variable, but it needs
normalization and tail substitution before it names the real variable.
The name {\tt foo.bar} is a symbolic variable name, and it is
transformed by normalization, to {\tt FOO.BAR}, and then by tail
substitution to {\tt FOO.42} (assuming that the current value of {\tt
BAR} is 42).

Normalization is the process of uppercasing all characters in the
symbolic name; and tail substitution is the process of substituting each
distinct simple symbol in the tail for its value.

On the other hand, a direct variable refers directly to the name of
the variable. In a sense, it is a symbolic variable that has already
been normalized and tail substituted. For instance, {\tt foo.bar} is
not a valid direct variable name, since lower case letters are not
allowed in the variable stem. The direct variable {\tt FOO.42} is the
same as the variable above. For simple variables, the only difference
between direct and symbolic variable names is that lower case letters
are allowed in symbolic names

Note that the two direct variable names {\tt FOO.bar}
and {\tt FOO.BAR} refer to different variables, since upper and lower
case letters differ in the tail. In fact, the tail of a compound
direct variable may contain any character, including ASCII NUL. The
stem part of a variable, and all simple variables can not contain any
lower case letters.

As a remark, what would the direct variable {\tt FOO.}~refer to: the
stem {\tt FOO.}~or the compound variable having stem {\tt FOO.}~and a
nullstring as tail? Well, I suppose the former, since it is the
more useful. Thus, the latter is inaccessable as a direct variable.



\subsection{The {\tt SHVBLOCK} structure}

All requests to manipulate the {\rexx} variable pool are controlled by
a structure which is called {\tt SHVBLOCK}, having the definition:
\begin{verbatim}
   typedef struct shvnode {
      struct shvnode *shvnext ;    /* ptr to next in blk in chain */
      RXSTRING shvname ;           /* name of variable */
      RXSTRING shvvalue ;          /* value of variable */
      unsigned long shvnamelen ;   /* length of shvname.strptr */
      unsigned long shvvaluelen ;  /* length of shvvalue.strptr */
      unsigned char shvcode ;      /* operation code */
      unsigned char shvret ;       /* return code */
   } SHVBLOCK ;

   typedef SHVBLOCK *PSHVBLOCK ;
\end{verbatim}

The fields {\tt shvnext} and {\tt shvcode} are purely input, while
{\tt shvret} is purely output. The rest of the fields might be input
or output, depending on the requested operation, and the value of the
fields. The significance of each field is:
\begin{description}
\item[{\tt shvnext~}] 
   One call to {\tt RexxVariablePool()} may sequentially process many
   requests. The {\tt shvnext} field links one request to the next in
   line. The last request must have set {\tt shvnext} to {\tt NULL}.
   The requests are handled individually and thus, calling {\tt
   RexxVariablePool()} with several requests is equivalent to making
   one call to {\tt RexxVariablePool()} for each request.

\item[{\tt shvname~}]
   Contains the name of the variable to operate on, as a {\tt
   RXSTRING}. This field is only relevant for some requests, and its
   use may differ.

\item[{\tt shvvalue~}]
   Contains the value of the variable to operate on as a {\tt
   RXSTRING}. Like {\tt shvname}, this might not be relevant for all
   types of requests.

\item[{\tt shvnamelen~}]
   The length of the array that {\tt shvname.strptr} points to.  This
   field holds the maximum possible number of characters in {\tt
   shvname.strptr}. While {\tt shvname.strlength} holds the number of
   characters that are actually in use (i.e.~defined).

\item[{\tt shvvaluelen~}]
   The length of the array that {\tt shvvalue.strptr} points to.
   Relates to {\tt shvvalue} like {\tt shvnamelen} relates to {\tt
   shvname}. 

\item[{\tt shvcode~}]
   The code of operation; decides what type of request to perform. A
   list of all the available requests is given below. 

\item[{\tt shvret~}]
   A return code describing the outcome of the request. This code is a
   bit special. The lower seven bits are flags which are set depending
   on whether some condition is met or not. Values above 127 are not
   used in this field. 
\end{description}

There is a difference between {\tt strnamelen} and {\tt
strname.strlength}. The former is the total length of the array of
characters pointed to by {\tt strname.strptr} (if set). While the
latter is the number of these characters that are actually in use.
When a {\tt SHVBLOCK} is used to return data from {\tt
RexxVariablePool()}, and a preallocated string space has been
supplied, both these will be used; {\tt strname.strptr} will be set to
the length of the data returned, while {\tt strnamelen} is never
changed, only read to find the maximum number of characters that {\tt
shvname} can hold.

Even though {\tt shvnamelen} is not really needed when {\tt shvname}
is used for input, it is wise to set it to its proper value (or
at least set it to the same as {\tt shvname.strlength}). The same
applies for {\tt shvvalue} and {\tt shvvaluelen}. 

The field {\tt shvcode} can take one of the following symbolic
values:
\begin{description}
\item[{\tt RXSHV\_DROP~}]
   The variable named by the direct variable name {\tt shvname} is
   dropped (i.e.~becomes undefined). The fields {\tt shvvalue} and
   {\tt shvvaluelen} do not matter.

\item[{\tt RXSHV\_EXIT~}]
   This is used to set the return value for an external function
   or exit handler. 

\item[{\tt RXSHV\_FETCH~}]
   The value of the variable named by the direct variable name {\tt
   shvname} is retrieved and stored in {\tt shvvalue}. If {\tt
   shvvalue.strptr} is {\tt NULL}, the interpreter will allocate
   sufficient space to store the value (but it is the responsibility
   of the application programmer to release that space). Else, the
   value will be stored in the area allocated for {\tt shvvalue}, and
   {\tt shvvaluelen} is taken to be the maximum size of that area.

\item[{\tt RXSHV\_NEXTV~}]
   This code is used to retrieve the names and values of all variables
   at the current procedure level; i.e.~excluding variables shadowed by
   {\tt PROCEDURE}.  The name and value of each variable are retrieved
   simultaneously into {\tt shvname} and {\tt shvvalue}, respectively.

   Successive requests for {\tt RXSHV\_NEXTV} will traverse the
   interpreter's internal data structure for storing variables, and
   return a new pair of variable name and value for each request. Each
   variable that is visible in the current scope, is returned once
   and only once, but the order is indeterministic.

   When all available variables in the {\rexx} interpreter have
   already been retrieved, subsequent {\tt RXSHV\_NEXTV} requests will
   set the flag RXSHV\_LVAR in the {\tt shvret} field.  There are a few
   restrictions. The traversal will be reset whenever the interpreter
   resumes execution, so an incomplete traversal can not be continued
   in a later external function, exit handler, or subcommand handler.
   Also, any set, fetch or drop operation will reset the traversal.
   These restrictions have been added to ensure that the variable pool
   is static throughout one traversal.

\item[{\tt RXSHV\_PRIV~}]
   Retrieves some piece of information from the interpreter, other than
   a variable value, based on the value of the {\tt shvname} field.
   The value is stored in {\tt shvvalue} as for a ``normal'' fetch. A
   list of possible names is shown below.

\item[{\tt RXSHV\_SET~}]
   The variable named by the direct variable name {\tt shvname} is set
   to the value given by {\tt shvvalue}.

\item[{\tt RXSHV\_SYFET~}]
   Like {\tt RXSHV\_FETCH}, except that {\tt shvname} is a symbolic
   variable name.

\item[{\tt RXSHV\_SYDRO~}]
   Like {\tt RXSHV\_DROP}, except that {\tt shvname} is a symbolic
   variable name. 

\item[{\tt RXSHV\_SYSET~}]
   Like {\tt RXSHV\_SET}, except that {\tt shvname} is a symbolic
   variable name. 
\end{description}

One type of request that needs some special attention is the {\tt
RXSHV\_PRIV}, which retrieves a kind of ``meta-variable''. Depending
on the value of {\tt shvname}, it returns a value in {\tt shvvalue}
describing some aspect of the interpreter. For {\tt RXSHV\_PRIV} the
possible values for {\tt shvname} are:
\begin{description}
\item[{\tt PARM~}]
   Returns the ASCII representation of the number of parameters to the
   currently active {\rexx} procedure. This must not the same value as
   the built-in function {\tt ARG()} returns, but the number {\tt
   ArgCount} in {\tt RexxStart}. The two might differ if a routine was
   called with trailing omitted parameters.

\item[{\tt PARM.{\it n}~}]
   The {\it n} must be a positive integer; and the value returned will
   be the {\it n}'th parameter at the current procedure level.  This
   is not completely equivalent to the information that the builtin
   function {\tt ARG()} returns. For parameters where {\tt ARG()} would
   return the state omitted, the returned value is a ``null string'',
   while for parameters where {\tt ARG()} would return the state
   ``existing'', the return value will be the parameter string (which may
   be a ``zero length string''.

\item[{\tt QUENAME~}]
   The name of the currently active external data queue. This feature
   has not yet been implemented in Regina, which always return
   ``default''. 

\item[{\tt SOURCE~}] 
   Returns the same string that is used in the {\tt PARSE SOURCE}
   clause in {\rexx}, at the current procedure level of interpretation.

\item[{\tt VERSION~}]
   Returns the same string that is used in the {\tt PARSE VERSION}
   clause in {\rexx}. 
\end{description}

The value returned by a variable pool request is a bit uncommon. A
return value is computed for each request, and stored in the {\tt shvret}
field.  This is a one-byte field, of which the most significant bit is
never set.  A symbolic value {\tt RXSHV\_OK} is defined as the value
zero, and the {\tt shvret} field will be equal to this name if none if
the flags listed below is set.  The symbolic value for these flags
are:
\begin{description}
\item[{\tt RXSHV\_BADF~}]
   The {\tt shvcode} of this request contained a bad function code.

\item[{\tt RXSHV\_BADN~}]
   The {\tt shvname} field contained a string that is not valid in
   this context. What exactly is a valid value depends on whether the
   operation is a private, a symbolic variable, or direct variable
   operation. 

\item[{\tt RXSHV\_LVAR~}]
   Set if and only if the request was {\tt RXSHV\_NETXV}, and all
   available variables have already been retrieved by earlier
   requests.

\item[{\tt RXSHV\_MEMFL~}]
   There was not enough memory to complete this request. 

\item[{\tt RXSHV\_NEWV~}]
   Set if and only if the referenced variable did not previously have
   a value. It can be returned for any set, fetch or drop operation. 

\item[{\tt RXSHV\_TRUNC~}]
   Set if the retrieved value was truncated when it was copied into
   either the {\tt shvname} or {\tt shvvalue} fields. See below.
\end{description}

These flags are directrly suitable for logical OR, without shifting,
e.g.~to check for truncation and no variables left, you can do
something like:
\begin{verbatim}
   if (req->shvret & (RXSHV_TRUNC | RXSHV_LVAR))
      printf("Truncation or no vars left\n") ;
\end{verbatim}

{\tt RXSHV\_TRUNC} can only occur when the interface is storing a
retrieved value in a {\tt SHVBLOCK}, and the preallocated space is
present, but not sufficiently large. As described for {\tt RXSHV\_FETCH}, the
interpreter will allocate enough space if {\tt shvvalue.strptr} is
{\tt NULL}, and then {\tt RXSHV\_TRUNC} will never be set.  Else the
space supplied by {\tt shvvalue.strptr} is used, and {\tt shvvaluelen}
is taken as the maximum length of {\tt shvvalue}, and truncation will
occur if the supplied space is too small.

Some implementations will consider {\tt SHV\_MEMFL} to be so severe as
to skip the rest of the operations in a chain of requests. In order to
write compatible software, you should never assume that requests
following in a chain after a request that returned {\tt SHV\_MEMFL}
have been performed.

The {\tt RXSHV\_BADN} is returned if the supplied {\tt shvname}
contains a value that is not legal in this context. For the symbolic
set, fetch and drop operations, that means a symbol that is a legal
variable name; both upper and lower case letters are allowed. For the
direct set, fetch and drop operations, that means a variable name
after normalization and tail substitution is not a legal variable
name. For the {\tt RXSHV\_PRIV}, it must be one of the values listed
above.

There is a small subtlety in the above description. TRL states that
when a {\rexx} assignment assignes a value to a stem variable, all
possible variables having that stem are assigned a new value
(independent of whether they had an explicit value before). So
strictly speaking, if a stem is set, then a {\tt RXSHV\_NETV} sequence
should return an (almost) infinite sequence of compound variables for
that stem. Of course, that is completely useless, so you can assume
that only compound variables of that stem given an explicit value
after the stem was assigned a value will be returned by {\tt
RXSHV\_NEXTV}. However, because of that subtlety, the variables
returned by {\tt RXSHV\_NEXTV} for compound variables might not be
representative for the state of the variables. 

E.g.~what would a sequence of {\tt RXSHV\_NEXT}
requests return after the following {\rexx} code:
\begin{verbatim}
   foo. = 'bar'
   drop foo.bar
\end{verbatim}
The second statement here, might not change the returned values!
After the first statement, only the stem {\tt foo.}~would probably
have been returned, and so also if all variables were fetched after the
second statement.



\subsection{Regina Notes for the Variable Pool}

Due to the subtleties described at the end of the previous subsection,
some notes on how Regina handles {\tt RXSHV\_NEXTV} requests for
compound variables are in order. The following rules applies:
\begin{itemize}
\item
   Both the stem variable {\tt FOO.} and the compound variable having
   {\tt FOO.} as stem and a nullstring as tail, are returned with the
   name of {\tt FOO.}. In this situation, a sequence of {\tt
   RXSHV\_NEXTV} requests may seem to return values for the same
   variable twice. This is unfortunate, but it seems to be the only
   way. In any case, you'll have to perform the {\tt RXSHV\_SYFET} in
   order to determine which is which.

\item
   If a stem variable has not been assigned a value, its compound
   variables are only returned if they have been assigned an explicit
   value. I.e.~compound variables for that stem that have either never
   been assigned a value, or have been dropped, will not be reported
   by {\tt RXSHV\_NEXTV}. There is nothing strange about this.

\item
   If a stem variable has been assigned a value, then its compound
   variables will be reported in two cases: Firstly, the compound
   variables having explicitly been assigned a value afterwards.
   Secondly, the compound variables which have been dropped
   afterwards, which are reported to have their initial value, and the
   flag {\tt RXSHV\_NEWV} is set in {\tt shvret}.
\end{itemize}

It may sound a bit stupid that unset variables are listed when the
request is to list all variables which have been set, but that is
about the best I can do, if I am to stay within the standard
definition and return a complete and exact status of the variable
pool. 

If the return code from {\tt RexxVariablePool()} is less than 128,
Regina is guaranteed to have tried to process all requests in the
chain. If the return code is  above 127, some requests may not have been
processed. Actually, the number 127 (or 128) is a bit inconvenient,
since it will be an problem for later expansion of the standard. A
much better approach would be to have a preprocessor symbol (say, {\tt
RXSHV\_FATAL}, and if the return code from the {\tt RexxVariablePool()}
function was larger than that, it would be a ``direct'' error code,
and not a ``composite'' error code built from the {\tt shvret}
fields of the requests. The {\tt RXSHV\_FATAL} would then have to be
the addition of all the atomic composite error codes.

(Warning: author mounting the soapbox.)  The ``right'' way to fix
this, is to let the function {\tt RexxVariablePool()} set another flag
in {\tt shvret} (e.g.\ named {\tt RXSHV\_STEM}) during {\tt
RXSHV\_NEXTV} if and only if the value returned is a stem variable.
That way, the application programmer would be able to differ between
stem variables and compound variable with a null string tail.

To handle the other problem with compound variables and {\tt RXSHV\_NEXTV},
I would have liked to return a ``null string'' in {\tt shvvalue} if
and only if the variable is a compound variable having its initial
value, and the stem of that compound variable has been assigned a
value. Then, the value of the compound variable is equal to
its name, and is available in the {\tt shvname} field.

I'd also like to see that the {\tt shvret} value contained other
information conserning the variables, e.g.\ whether the variable was
exposed at the current procedure level. Of course, Regina does not
contain any of these extra, unstandard features. (Author is
dismounting the soapbox.)

When Regina is returning variables with {\tt RXSHV\_NEXTV}, the
variables are returned in the order in which the occurr in the open
hashtable in the interpreter. I.e.~the order in which variables
belonging to different bins are returned is consistent, but the order
in which variables hashed to the same bin are returned, is
indeterministic. Note that all compound variables belonging to the
same stem are returned in one sequence.




\subsection{The {\tt RexxVariablePool()} function}
\label{fn:RexxVarPool}

This function is used to process a sequence of variable requests, and
process them sequentially. The prototype of this function is:
\begin{verbatim}
   ULONG RexxVariablePool(
      SHVBLOCK *Request
   ) ;
\end{verbatim}
Its only parameter is a pointer to a {\tt SHVBLOCK} structure, which
may be the first of the linked list. The function performs the
operation specified in each block. If an error should occur, the
current request is terminated, and the function moves on to the next
request in the chain. 

The result value is a bit peculiar. If the returned value is less than
128, it is calculated by logically OR'ing the returned {\tt shvret}
field of all the requests in the chain. That way, you can easily check
whether any of the requests was e.g.~skipped because of lack of
memory. To determine which request, you have to interate through the list.

If the result value is higher than 127, it signifies an error. If any of
these values are set, you can not assume that any of the requests have
been processed. The following symbolic name gives its meaning.
\begin{description}
\item[{\tt RXSHV\_NOAVL~}]
   Means that the interface is not available for this request.  This
   might occur if the interface was not able to start the interpreter,
   or if an operation requested a variable when the interpreter is not
   currently executing any script (i.e.~idle and waiting for a script
   to execute).
\end{description}




\section{The System Exit Handler Interface}
\label{sect:sysexit}


The exit handlers provide a mechanism for governing important aspects
of the {\rexx} interpreter from the application: It can trap
situations like the interpreter writing out text, and then handle them
itself, e.g.~by displaying the text in a special window. You can
regard system exits as a sort of ``hooks''. 



\subsection{The System Exit Handler}

Just like the subcommand handler, the system exit handler is a routine
supplied by the application, and is called by the interpreter when
certain situations occur. These situations are described in detail
later. For the examples below, we will use the output from {\tt SAY}
as an example. 

If a system exit handler is enabled for the {\tt SAY} instruction, it
will be called with a parameter describing the text that is to be
written out. The system exit handler can choose to handle the
situation (e.g.~by writing the text itself), or it can ignore it and
let the interpreter perform the output. The return code from the
system exit tells the interpreter whether a system exit handled the
situation or not. 

A system exit handler must be a routine defined according to the
prototype:
\begin{verbatim}
   signed long my_exit_handler(
      signed long ExitNumber,
      signed long Subfunction, 
      PEXIT ParmBlock
   ) ;
\end{verbatim}
In this prototype, the type {\tt PEXIT} is a pointer to a parameter
block containing all the parameters necessary to handle the situation.
The actual definition of this parameter block will vary, and is
described in detail in the list of each system exit.

The exits are defined in a two-level hierarchy. The {\tt ExitNumber}
defines the main function for a system exit, while the {\tt
Subfunction} defines the subfunction within that main function.
E.g.~for {\tt SAY}, the mainfunction will be {\tt RXSIO} (the system
exit for standard I/O) and the subfunction will be {\tt RXSIOSAY}. The
{\tt RXSIO} main function has other subfunctions for handling trace
output, interactive trace input, and {\tt PULL} input from standard
input.

The value returned from the system exit handler must be one of the
following symbolic values:
\begin{description}
\item[{\tt RXEXIT\_HANDLED~}]
   Signals that the system exit handler took care of the situation,
   and that the interpreter should not proceed to do the default
   action. For the {\tt SAY} instruction, this means that the
   interpreter will not print out anything. 

\item[{\tt RXEXIT\_NOT\_HANDLED~}]
   Signals that the system exit handler did not take care of the
   situation, and the interpreter will proceed to perform the default
   action. For the {\tt SAY} instruction, this means that it must
   print out the argument to {\tt SAY}.

\item[{\tt RXEXIT\_RAISE\_ERROR~}]
   Signals that the interpreter's default action for this situation
   should not be performed, but instead a {\tt SYNTAX} condition
   should be raised. Don't get confused by the name, it is not the
   {\tt ERROR} condition, but the {\tt SYNTAX} condition is raised,using
   the syntax error ``Failure in system service'' (normally numbered
   48).
\end{description}

In addition to returning information as the numeric return value,
information may also be returned by setting variables in the parameter
block. For instance, if the system exit is to handle interactive trace
input, that is how it will supply the interpreter with the input
string. 

It is a good and disiplined practice to let your exit handlers start
by verifying the {\tt ExitNumber} and {\tt Subfunction} codes, and
immediately return {\tt RXEXIT\_NOT\_HANDLED} if it does not recognize
both of them. That way, your application will be upwards compatible with
future interpreters which might have more subfunctions for any given
main function.




\subsection{List of System Exit Handlers}



\subsection{{\tt RXFUN} --- The External Function Exit Handler}

\subsection{{\tt RXCMD} --- the Subcommand Exit Handler}

The main function code for this exit handler is given by the symbolic
name {\tt RXCMD}. It is called whenever the interpreter is about to
call a subcommand, i.e.~a command to an external environment. It has
only one subfunction: {\tt RXCMDHST}. 

The {\tt ParmBlock} parameter for this subfunction has the following
definition: 
\begin{verbatim}
   typedef struct {
      typedef struct {
         unsigned int rxfcfail:1 ;
         unsigned int rxfcerr:1 ;
      } rxcmd_flags ;
      unsigned char *rxcmd_address ;
      unsigned short rxcmd_addressl ;
      unsigned char *rxcmd_dll ;
      unsigned short rxcmd_dll_len ;
      RXSTRING rxcmd_command ;
      RXSTRING rxcmd_retc ;
   } RXCMDHST_PARM ;
\end{verbatim}

The significance of each variable is:
\begin{description}
\item[{\tt rxcmd\_flags.rxfcfail~}] 
   If this flag is set, the interpreter will raise a {\tt FAILURE}
   condition at the return of the exit handler. 

\item[{\tt rxcmd\_flags.rxfcerr~}]
   Like the previous, but the {\tt ERROR} condition is raised instead.

\item[{\tt rxcmd\_address~}]
   Points to a character array containing the name of the environment
   to which the command normally would be sent. 

\item[{\tt rxcmd\_addressl~}]
   Holds the length of {\tt rxcmd\_address}. Note that the last
   character is the letter ``ell'', not the number one. 

\item[{\tt rxcmd\_dll~}]
   Defines the name for the DLL which is to handle the command. I'm
   not sure what this entry is used for. It is not currently in use
   for Regina. 

\item[{\tt rxcmd\_dll\_len~}]
   Holds the length of {\tt rxcmd\_dll}. If this length is set to
   zero, the subcommand handler for this environment is not a DLL, but
   an exe handler. 

\item[{\tt rxcmd\_command~}]
   Holds the command string to be executed, including command
   name and parameters. 

\item[{\tt rxcmd\_retc~}]
   Set by the exit handler to the string which is to be considered the
   return code from the command. It is assigned to the special
   variable {\tt RC} at return from the exit handler.  The user is
   responsible for allocating space for this variable. I have no clear
   idea what happens if {\tt rxcmd\_retc.strptr} is set to {\tt
   NULL}; it might set {\tt RC} to zero, to the null string, or even
   drop it.
\end{description}

It seems that this exit handler is capable of raising both the {\tt
ERROR} and the {\tt FAILURE} conditions simultaneously. I don't know
whether that is legal, or whether only the {\tt FAILURE} condition is
raised, since the {\tt ERROR} condition is a sort of ``subset'' of
{\tt FAILURE}.

Note that the return fields of the parameter block are only relevant
if the value {\tt RXEXIT\_HANDLED} was returned. This applies to the
{\tt rxcmd\_flags} and {\tt rxcmd\_retc} fields of the structure.
   


\subsection{{\tt RXMSQ} --- the External Data Queue Exit Handler}
\label{saa:rxmsq}


\subsection{{\tt RXSIO} --- the Standard I/O Exit Handler}

The main code for this exit handler has the symbolic value {\tt
RXSIO}. There are four subfunctions:
\begin{description}
\item[{\tt RXSIODTR~}]
   Called whenever the interpreter needs to read a line from the user
   during interactive tracing. Note the difference between this
   subfunction and {\tt RXSIOTRD}.

\item[{\tt RXSIOSAY~}]
   Called whenever the interpreter tries to write something to
   standard output in a {\tt SAY} instruction, even a {\tt SAY} instruction
   without a parameter.

\item[{\tt RXSIOTRC~}]
   Called whenever the interpreter tries to write out debugging
   information, e.g.~during tracing, as a trace back, or as a syntax
   error message.

\item[{\tt RXSIOTRD~}]
   Called whenever the interpreter need to read from the standard
   input stream during a {\tt PULL} or {\tt PARSE PULL} instruction. Note
   that it will not be called if there is sufficient data on the
   stack to satisfy the operation.
\end{description}

Note that these function are only called for the exact situations that
are listed above. E.g.~the {\tt RXSIOSAY} is not called during a call
to the {\rexx} built-in function {\tt LINEOUT()} that writes to the
default output stream. TRL says that {\tt SAY} is identical to calling
{\tt LINEOUT()} for the standard output stream, but SAA API still
manages to see the difference between stem variables and compound
variables with a ``zero-length-string'' tail. Please bear with
this inconsistency.

Depending on the subfunction, the {\tt ParmBlock} parameter will have
four only slightly different definitions. It is kind of frustrating
that the {\tt ParmBlock} takes so many different datatypes, but it can
be handled easily using {\tt unions}, see a later section. The
definitions are:
\begin{verbatim}
   typedef struct {             
      RXSTRING rxsiodtr_retc ;  /* the interactive trace input */
   } RXSIODTR_PARM ;

   typedef struct {
      RXSTRING rxsio_string ;   /* the SAY line to write out */
   } RXSIOSAY_PARM ;

   typedef struct {
      RXSTRING rxsio_string ;   /* the debug line to write out */
   } RXSIOTRC_PARM ;

   typedef struct {
      RXSTRING rxsiotrd_retc ;  /* the line to read in */
   } RXSIOTRD_PARM ;
\end{verbatim}
In all of these, the {\tt RXSTRING} structure either holds
the value to be written out (for {\tt RXSIOSAY} and {\tt RXSIOTRC}),
or the value to be used instead of reading standard input stream (for {\tt
RXSIOTRD} and {\tt RXSIODTR}). Note that the values set by {\tt
RXSIOTRD} and {\tt RXSIODTR} are ignored if the exit handler does
not return the value {\tt RXEXIT\_HANDLED}.
 
Any end-of-line marker are stripped off the strings in
this context. If the exit handler writes out the string during {\tt
RXSIOSAY} or {\tt RXSIOTRC}, it must supply any end-of-line action
itself. Similarily, the interpreter does not expect a end-of-line
marker in the data returned from {\tt RXSIODTR} and {\tt RXSIOTRD}.

The space used to store the return data for the {\tt RXSIODTR} and
{\tt RCSIOTRD} subfunctions, must be provided by the exit handler
itself, and the space is not deallocated by the interpreter. The space
can be reused by the application at any later time. The space
allocated to hold the data given by the {\tt RXSIOSAY} and {\tt
RXSIOTRC} subfunctions, will be allocated by the interpreter, and must
neither be deallocated by the exit handler, nor used after the exit
handler has terminated.


\subsection{{\tt RXHLT} --- the Halt Condition Exit Handler}

\subsection{{\tt RXTRC} --- the Trace Status Exit Handler}


\subsection{{\tt RXINI} --- the Initialization Exit Handler}

{\tt RXTER} and this exit handler are a bit different from
the others. {\tt RXINI} provides the application programmer with a method of
getting control before the execution of the script starts. Its main
purpose is to enable manipulation of the variable pool in order to set
up certain variables before the script starts, or set the trace mode. 

It has only one subfunction, {\tt RXINIEXT}, called once duing each
call to {\tt RexxStart()}: just before the first {\rexx} statement is
interpreted.  Variable manipulations performed during this exit will
have effect when the script starts.

As there is no information to be communicated during this exit, the
value of {\tt ParmBlock} is undefined. It makes no difference whether
you return {\tt RXEXIT\_HANDLED} or {\tt RXEXIT\_NOT\_HANDLED}, since
there is no situation to handle. 



\subsection{{\tt RXTER} --- the Termination Exit Handler}

This exit resembles {\tt RXINI}. Its sole subfunction is {\tt
RXTEREXT}, which is called once, just after the last statement of the
{\rexx} script has been interpreted. The state of all variables are
intact during this call; so it can be used to retrieve the values of
the variables at the exit of a script. (In fact, that is the whole
purpose of this exit handler.)

Like {\tt RXINI}, there is no information to be communicated during
the exit, so {\tt ParamBlock} is undefined in this call. And also like
{\tt RXINI}, it is more of a hook than an exit handler, so it does not
matter whether you return {\tt RXEXIT\_HANDLED} or {\tt
RXEXIT\_NOT\_HANDLED}.










