Creating a z/OS UNIX REXX environment from an application

To create a z/OS UNIX REXX environment, fetch and call the module BPXWRBLD from a key 8 problem state program. z/OS linkage for C (that is, standard OS linkage) is required.

The BPXWRBLD module requires the following parameters:

16K area

A 16,000-byte environment area. This must persist for the life of the REXX environment.

arg count

The count of the number of REXX initialization arguments.

arg pointer array

An array of pointers to null-terminated strings, one for each REXX initialization argument. The array and the null-terminated strings must persist for the life of the REXX environment.

env count

The count of the number of environment variables to be exported to the REXX program.

env length pointer array

An array of pointers to fullwords, one for each environment variable. The fullword contains the length of the string that defines the environment variable, including the terminating null. The last element of the array must point to a fullword of 0.

The array and the fullwords must persist for the life of the REXX environment.

env pointer array

An array of pointers to null-terminated strings, one for each environment variable. Each string defines one environment variable. The array and the null-terminated strings must persist for the life of the REXX environment.

The format of the string is

NAME=value

where NAME is the environment variable name, and value is the value for the environment variable followed by a null character.

REXX env addr

The address of a fullword where the address of the newly created REXX environment is returned.

If BPXWRBLD fails to create the environment, it returns the return code it received from the IRXINIT service. BPXWRBLD does not return any other codes.

The parameter list is a standard MVS™ variable-length parameter list. On entry, the following registers must be set:

Register 1: Address of the parameter list
Register 13: Address of a register save area
Register 14: Return address
Register 15: Entry point address

              --------+
              |     --+----> 16K area
              --------+
              |     --+----> arg count
              --------+
              |     --+----> arg pointer array
              --------+
              |     --+----> env count
              --------+
              |     --+----> env length pointer array
              --------+
              |     --+----> env pointer array
              --------+
              |1    --+----> Rexx env addr
              --------+

When constructing arguments to the REXX program that are also passed to BPXWRBLD, keep in mind that:

The only use of the argument count and argument array is to populate the __argv. REXX variables. You can set the argument count to 0 if the REXX programs will always get their arguments using PARSE ARG or the arg(1) REXX function call. In this case, __argv.0 is set to 0 when the REXX program is run.
After the call to BPXWRBLD, do not alter the data that is pointed to by the environment pointer arrays or the arg pointer array.

Signals are not supported in this environment.