RexxStart - Parameters

ArgCount (LONG) - input

The number of elements in the ArgList array. This is the value that the ARG() built-in function in the REXX program returns. ArgCount includes RXSTRINGs that represent omitted arguments. Omitted arguments are empty RXSTRINGs (strptr is NULL).
ArgList (PRXSTRING) - input
An array of RXSTRING structures that are the REXX program arguments.
ProgramName (PSZ) - input
Address of the ASCIIZ name of the REXX procedure. If Instore is NULL, ProgramName must contain at least the file name of the REXX procedure. You can also provide an extension, drive, and path specification. If you do not specify a file extension, the default is ".CMD". A REXX program can use any extension. If you do not provide the path and drive, the REXX interpreter uses the usual file search (current directory, then environment path).

If Instore is not NULL, ProgramName is the name used in the PARSE SOURCE instruction. If Instore requests a REXX procedure from the macrospace, ProgramName is the macrospace function name (see Macrospace Interface).

Instore (PRXSTRING) - input
An array of two RXSTRING descriptors for in-storage REXX procedures. If the strptr fields of both RXSTRINGs are NULL, the interpreter searches for REXX procedure ProgramName in the REXX macrospace (see Macrospace Interface). If the procedure is not in the macrospace, the call to RexxStart terminates with an error return code.

If either Instore strptr field is not NULL, Instore is used to run a REXX procedure directly from storage.

Instore[0]

An RXSTRING describing a memory buffer containing the REXX procedure source. The source must be an exact image of a REXX procedure disk file (complete with carriage returns, line feeds, and end-of-file characters).
Instore[1]
An RXSTRING containing the translated image of the REXX procedure. If Instore[1] is empty, the REXX interpreter returns the translated image in Instore[1] when the REXX procedure finishes running. The translated image may be used in Instore[1] on subsequent RexxStart calls.

If Instore[1] is not empty, the interpreter runs the translated image directly. The program source provided in Instore[0] is used only if the REXX procedure uses the SOURCELINE built-in function. Instore[0] can be empty if SOURCELINE is not used. If Instore[0] is empty and the procedure uses the SOURCELINE built-in function, SOURCELINE() returns 0 lines and any attempt to access the source returns Error 40.

If Instore[1] is not empty, but does not contain a valid REXX translated image, unpredictable results can occur. The REXX interpreter may be able to determine that the translated image is incorrect and retranslate the source.

Instore[1] is both an input and an output parameter.

If the procedure is executed from disk, the Instore pointer must be NULL. If the first argument string in Arglist contains the string "//T" and the CallType is RXCOMMAND, the interpreter translates the procedure source and writes the translated image to disk. Since the Instore pointer is NULL, the translated image is not returned in an Instore parameter.

The program calling RexxStart must release Instore[1] using DosFreeMem when the translated image is no longer needed.

The format of the translated image of a REXX program is not a programming interface. Only the interpreter version that created the image can run the translated image. Therefore, do not move a translated image to other systems or save it for later use. You can, however, use the translated image multiple times during a single application instance.

EnvName (PSZ) - input
Address of the ASCIIZ initial ADDRESS environment name. The ADDRESS environment is a subcommand handler registered using RexxRegisterSubcomExe or RexxRegisterSubcomDll. EnvName is used as the initial setting for the REXX ADDRESS instruction.

If EnvName is NULL, the file extension is used as the initial ADDRESS environment. The environment name cannot be longer than 250 characters.

CallType (LONG) - input
The type of REXX procedure execution. Allowed execution types are:

RXCOMMAND

The REXX procedure is a system or application command. REXX commands usually have a single argument string. The REXX PARSE SOURCE instruction returns COMMAND as the second token.
RXSUBROUTINE
The REXX procedure is a subroutine of another program. The subroutine can have multiple arguments and does not need to return a result. The REXX PARSE SOURCE instruction returns SUBROUTINE as the second token.
RXFUNCTION
The REXX procedure is a function called from another program. The subroutine may have multiple arguments and must return a result. The REXX PARSE SOURCE instruction returns FUNCTION as the second token.
Exits (PRXSYSEXIT) - input
An array of RXSYSEXIT structures defining exits for the REXX interpreter to use. The RXSYSEXIT structures have the following form:

typedef struct {
   PSZ             sysexit_name;  /* name of exit handler        */
   LONG            sysexit_code;  /* system exit function code   */
} RXSYSEXIT;

The sysexit_name is the address of an ASCIIZ exit handler name registered with RexxRegisterExitExe or RexxRegisterExitDll. Sysexit_code is a code identifying the handler exit type. System Exits provides exit code definitions. An RXENDLST entry identifies the system exit list end. Exits must be NULL if exits are not used.

ReturnCode (PSHORT) - output
The integer form of the Result string. If the Result string is a whole number in the range -(2**15) to 2**15-1, it is converted to an integer and also returned in ReturnCode.
Result (PRXSTRING) - output
The string returned from the REXX procedure with the REXX RETURN or EXIT instruction. A default RXSTRING can be provided for the returned result. If a default RXSTRING is not provided or the default is too small for the returned result, the REXX interpreter allocates an RXSTRING using DosAllocMem. The caller of RexxStart is responsible for releasing the RXSTRING storage with DosFreeMem.

The REXX interpreter does not add a terminating null to Result.

---

[Back: RexxStart - Syntax]
[Next: RexxStart - Returns]