Make your own free website on Tripod.com
8.4.1 The 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
pre-tokenized macro, or as ASCII source code in memory.

     APIRET APIENTRY RexxStart(
           LONG ArgCount,
           PRXSTRING ArgList,
           PSZ ProgramName,
           PRXSTRING Instore,
           PSZ EnvName,
           LONG CallType,
           PRXSYSEXIT Exits,
           PUSHORT ReturnCode,
           PRXSTRING Result
     ) ;

Of these parameters, ReturnCode and Result are output-only, while
Instore is both input and output. The rest of the parameters are
input-only. The significance of the parameters are:

     [ArgCount]
          The number of parameter strings given to the procedure.
          This is the number of defined REXX-strings pointed to by
          the ArgList parameter.
     [ArgList]
          Pointer to an array of REXX-strings, constituting the
          parameters to this call to REXX. The size of this array
          is given by the parameter ArgCount. If ArgCount is
          greater than one, the first and last parameters are
          ArgList[0] and ArgList[ArgCount-1].  If ArgCount is 0,
          the value of  ArgList is irrelevant.
     
          If the strptr of one of the elements in the array
          pointed to by ArgList is NULL, that means that this
          parameter is empty (i.e. unspecified, as opposed to a
          string of zero size).
     [ProgName]
          An ASCII NUL terminated string, specifying the name of
          the REXX script to be executed. The value of Instore
          will determine whether this value is interpreted as the
          name of a (on-disk) script, or a pre-tokenized macro. If
          it refers to a filename, the syntax of the contents of
          this parameter depends on the operating system.
     [Instore]
          Parameter used for storing tokenized REXX scripts. This
          parameter might either be NULL, else it will be a
          pointer to two 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 Instore.
     [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 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 period . in the filename.
     [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 parameter
          string can be passed, and in function mode, a value
          must be returned. In addition, the mode chosen will
          affect the output of the PARSE SOURCE instruction in
          REXX.
          
          Three symbolic values of integral type are defined,
          which can be used for this parameter: RXCOMMAND,
          RXFUNCTION and RXSUBROUTINE.
     [SysExists]
          A pointer to an array of exit handlers to be used. If no
          exit  handlers are to be defined, NULL may be specified.
          Each element in the array defines one exit handler, and
          the element  immediately following the last definition
          must have a sysexit_code set to RXENDLST.
     [ReturnCode]
          Pointer to a SHORT integer where the return code 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 ReturnCode is valid.
     [Result]
          Points to a REXX string into which the result string is
          written.  The caller may or may not let the 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 strlength field. If the size if not
          sufficient, a new area will be allocated, by some system
          dependent channel (i.e. malloc()), and the caller must
          see to that it is properly de-allocated (using  free()).

Note that the ArgCount parameter need not be the same as the ARG()
built-in function would return. Differences will occur if the last
entries in ArgList are null strings.

The 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:

     If  Instore is NULL, then ProgName names the filename of an
     on-disk REXX script which it to be read and executed.
     
     Else, if Instore is not NULL, the script is somewhere in
     memory, and no reading from disk is performed.  If both
     Instore[0].strptr and Instore[1].strptr are NULL, then the
     script to execute is a pre-loaded macro which must have been
     loaded with a call to either RexxAddMacro() or
     RexxLoadMacroSpace(); and ProgName is the name of the macro
     to execute.
     
     Else, if Instore[1].strptr is non-NULL, then Instore[1]
     contains the pre-tokenized image of a REXX script, and it is
     used for the execution.
     
     Else, if  Instore[0].strptr is non-NULL, then 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
     Instore[1] string, and then proceeds to execute that script.
     Upon return, the Instore[1] will be set, and can later be
     used to re-execute the script within the same process,
     without the overhead of tokenizing.
     
     The user is responsible for de-allocating any storage used by
     Instore[1]. Note that after tokenizing, the source code in
     Instore[0] is strictly speaking not needed anymore. It will
     only be consulted if the user calls the SOURCELINE() built-in
     function. It is not an error to use SOURCELINE() if the
     source is not present, but nullstrings and zero will be
     returned.
     
     Regina does not currently return any tokenized data in
     Instore[1] that can be used in a later call to RexxStart,
     outside of the current process.  What Regina returns in
     Instore[1], is an index into an in-memory tokenized version
     of the source code.  Once the process that parsed the source
     has stopped, the tokenized code is lost.

The valid return values from RexxStart() are:

     [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).
     [Zero]
          indicates that the interpreter finished executing the
          script without errors.
     [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.

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

Often, the application programmer is interested in providing
support simplifying the specification of filenames, like an
environment variable search path or a default file type. The REXX
interface does support a default file type:  .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 .CMD is OK).

If the initial environment name (EvnName) is 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.



PREV NEXT