Argument and variable processing

The AXREXX macro allows the invoker to specify up to 20 arguments and 256 variables by specifying the REXXARGS or REXXVARS parameter respectively. To use the REXXARGS and REXXVARS parameters, the AXREXX invoker must create a header section mapped by AXRARGLST followed in contiguous storage by one or more AXRARGENTRY sections. For the REXXARGS parameter, the entries mapped by AXRARGENTRY must appear in the same order as the arguments specified on the ARG statement in the REXX program. The mapping for AXRARGLST and AXRARGENTRY can be found in AXRZARG.

AXRARGLST contains the following:

AxrArgLstId - Set this to either AxrArgLstAcro or AxrVarLstAcro depending on whether this is for the RexxArgs parameter or the RexxVars parameter
AxrArgLstVer - Set to 0 (the current version)
AXRARGLstNumber - Set to the number of Arguments or variables (for example, the number of AXRARGLstEntry's that follow)
Other fields must be cleared to 0.

AXRARGEntry contains the following:

AXRARGAddr - Set this to the 64 bit address of the buffer containing the argument or variable. If the argument or variable resides below 2 gig, use AXRARGAddrLow and make sure AXRARGAddrHigh is 0.
AxrNameAddr - Set this to the 64 bit address of the buffer containing the name of the argument or variable. This field can be set to 0 if this is for an input only argument. If this name resides below 2 gig, use AXRNameAddrLow and set AXRNameAddrHigh to 0.
AXRARGLength - Set this to the length of the buffer containing the argument or variable. Note that different argument/variable types have specific requirements regarding lengths.
AXRARGAlet - Set this to the alet of the argument/variable. It must be a public entry on the DUAL of the task that invokes AXREXX. If the argument/vairable resides in the invoker's primary address space, set this to 0.
AXRARGNameAlet - Set this to the alet of the buffer containing the name of the argument/vairable. It must be a public entry on the DUAL of the task that invokes AXREXX. If the name resides in the invoker's primary address space, set this to 0.
AXRArgOutLength - System REXX sets this to the length of data returned to the invoker. Note that this value is in units of bytes for types Signed, Unsigned and Char, in units of hex digits (half bytes) for type HexString and in units of bits for type BitString.
AxrArgNameLength - Set this to the length of the name of the argument. This must contain the actual length of the name and not include any trailing blanks.
AxrArgType - Set this to the type of the argument/variable.
AXRARGInput - Set this if the argument/variable in the REXX exec is to be initialized to a value on entry to the exec.
AXRArgOutput - Set this if you want to retrieve the final value of the argument/variable on exit from the exec for a SYNC=YES request. If the variable is not set by the exec, System REXX will fail the request.
Other fields must be cleared to zero.

Since the only data type in REXX is the character string, System REXX must first convert input arguments or variables into this format. The invoker must specify the data type of the argument or variable in AXRARGTYPE. The following data types are supported:

AXRARGTYPEUNSIGNED - The input is treated as an unsigned integer value. The length must be 4 or 8 bytes.
AXRARGTYPESIGNED - The input is treated as 2s complement signed integer value. The length must be 4 or 8 bytes.
AXRARGYTPECHAR - The input is treated as a character string. The length can be from 0 to 512 bytes.
AXRARGTYPEHEXSTRING - The input is treated as a hexadecimal string. The length is specified in hexadecimal digits (2 per byte) and can be from 0 to 512 hexadecimal digits in length. When processing an output argument/variable with an odd number of hex digits the half byte after the last hex digit is cleared. For example, if an output variable is 5 hex digits, then when processing of the exec is completed, 5 hex digits corresponding to the vairable will be stored into the AXREXX invoker's storage followed by 4 bits set to zero.
AXRARGTYPEBITSTRING - The input is treated as a bit string. The length is specified in bits (8 per byte) and can be from 0 to 32. When processing an output argument/variable whose length is not a multiple of 8 bits, the bits following the bit string up to the next byte will be cleared to zeros. For example, if an output variable is 9 bits then when processing of the exec is completed, 9 bits of the AXREXX invoker's storage will be set to the variable followed by 7 bits of zeros.

If AXREXX encounters an error while attempting to marshal the invoker's input into a REXX argument or variable, System REXX will indicate in AXRARGLstEntryInError the number of the argument or variable that caused the error. AXREXX will return a specific reason code indicating the problem with the argument or variable and abort the request.

In addition to any input argument or variables that the AXREXX invoker may provide, System REXX sets the following variables:

AXREQTOKEN - Contains a 16 byte value which uniquely identifies the AXREXX invocation.
AXRINDD - If the REXXINDSN keyword is specified, this variable will contain the name of the DD used for allocating the input data set; otherwise it is not set.
AXROUTDD - If the REXXOUTDSN keyword is specified, this variable will contain the name of the DD used for allocating the output data set; otherwise it is not set.

If the exec successfully completes (no run time errors) and the AXREXX invocation specifies SYNC=YES, System REXX will attempt to obtain the final values of any output arguments or variables (those that have indicated AXRARGOUTPUT), convert them into the specified data type and insert their converted values into the AXREXX invoker's buffers specified by AXRARGADDR/AXRARGALET. The lengths of output arguments and variables are inserted into AXRARGOUTLENGTH. If there is any failure with attempting to process a single output argument or variable, System REXX will abort and not attempt to retrieve subsequent arguments or variables. Since output arguments are retrieved prior to output variables, if System REXX fails to process an output argument, no subsequent output arguments are processed and no output variables are processed.

In addition to output arguments and variables, System REXX also returns the return code from the exec in the AXRDIAGEXECRETCODE area in the REXXDIAG parameter (see AXRZARG for the mapping macro). The return code is returned as a 31 bit signed binary value. If it cannot be converted into such a value, or if the exec does not return a return code, then AXRDIAGNOEXECRETCODE will be set on.