System REXX

System REXX is a z/OS® component that allows REXX execs to be executed outside of conventional TSO/E and Batch environments. REXX has long been considered one of the fastest development languages for system exit and utilities work on z/OS. The possibilities for exploiting REXX code through the use of System REXX are vast, whether to provide operator assists or to provide an easy way to process files and strings. The System REXX environment provides a function package that allows a REXX exec to invoke system commands and to return results back to the invoker in a variety of ways. System REXX execs may be initiated through an assembler macro interface called AXREXX or through an operator command.

There are two different System REXX environments supported:
  • TSO=NO
In both environments, the exec runs in problem state, key 8, in an APF authorized address space. Any modules that are loaded, linked or attached from the exec, must reside in an APF authorized library; otherwise, a X'306' abend occurs. In both cases, the REXX exec runs under the enclave of the AXREXX invoker when the invoker can be classified; otherwise, the exec runs under the enclave of AXR.

There can be up to 64 REXX worker tasks running TSO=NO execs and up to 8 TSO server address spaces running TSO=YES execs. If a worker task is not available for an inbound TSO=NO request, or if a TSO server address space is not available for a TSO=YES request, the request is queued and the requestor is suspended if SYNC=YES is specified. The order in which System REXX processes queued requests may not be in the same order that the requests have been submitted. AXREXX invokers that use SYNC=YES should consider the potentially long wait time.

At most 5000 active and waiting requests are allowed to exist at any time. When this threshold is reached, subsequent AXREXX requests are rejected until the number of active and waiting requests drops to 4000. ENF signals (65) are issued when the threshold is exceeded, when the total number of requests is getting close to the threshold, and when acceptance of inbound requests is resumed.

TSO=NO environment: When TSO=NO is specified on the AXREXX invocation, the exec is executed in an MVS™ host command environment, sharing the address space where it is executing with up to 63 other concurrently running TSO=NO execs. In addition to MVS, the following host command environments are supported:
  • BCPii
  • LINK
  • LU62
Data set allocation other than provided by the AXREXX macro is not supported in this environment. Applications that perform input/output to data sets other than those specified on the REXXINDSN and REXXOUTDSN AXREXX keywords must use TSO=YES.

TSO=YES environment: The TSO=YES environment supports all of the host commands listed under the TSO=NO environment, along with some additional host commands supported by TSO. If you specify TSO=YES on the AXREXX invocation, the exec will run isolated in a single address space, and can safely allocate data sets without concern of a DDNAME conflict with a concurrently running exec. If the exec exits with data sets allocated, System REXX will free the allocations. The TSO=YES environment is established with the Terminal Monitor Program (TMP) when AXRRXWKD is specified as an authorized command in IKTJTSOxx, otherwise the TSO/E Environment Service is used. When established using the TMP, the TSO=YES environment supports CONSOLE host commands, the SUBMIT command, and several other foreground initiated background commands that are unavailable with the TSO/E Environment Service. If the exec is initiated when the primary subsystem is not active, the exec runs under the MASTER subsystem which restricts available TSO commands, regardless of whether the TMP is used. Only the TSO=YES environment supports SYSCALL (z/OS UNIX) host commands that are only available to requests associated with RACF® user ID's that have OMVS segments defined to them, which establishes the level of z/OS UNIX authorization. In particular, if execs are initiated from the operator console, the operator must be logged on for many SYSCALL host commands to work.

The following list shows additional TSO host commands that are supported in a TSO=YES environment:
  • ALLOCATE (except for the SYSOUT operand)
  • CALL
  • EXEC
  • FREE
  • HELP
  • RMM
  • SEND
  • TIME
Note: See z/OS DFSMSrmm Managing and Using Removable Media for details of the considerations for use of the RMM TSO subcommands.
No other TSO Services and facilities are supported. In particular, when non-supported host commands are invoked, the following errors might be encountered:
  • Some authorized host commands may not work under the TSO Environment Service. Starting System REXX under the TMP should resolve this.
  • The PSCBUSER field in the PSCB can be * for a TSO=YES environment when the security environment specified on the AXREXX invocation is not associated with a valid userid. When this occurs, the value is returned by the userid() function in REXX, and can cause problems for TSO/E commands or services that require a valid user ID.
  • JES facilities are available when the primary subsystem is active. When the primary subsystem is not active, the exec is run under the MASTER subsystem.
When a TSO=YES exec is dispatched, it receives control with the following TSO/E profile attributes set:
Other restrictions that users should be aware of include:
  • System REXX does not support the establishment of additional Language Processor Environments using any of the TSO/E REXX Customizing Services (IRXINIT or IRXTERM for example). In addition, when a REXX exec invokes an assembler program (by LINKMVS or other means), the contents of field ENVBLOCK_USERFIELD in the IRXENVB data area should not be altered in any way. If the program needs to maintain a storage area across calls, it must use the name/token services. See 'Sharing Application Data (Name/Token Callable Services)' in z/OS MVS Programming: Assembler Services Guide.
  • The STORAGE external function can only be used to read storage.
  • The BCPii host command environment does not support being invoked in an exec via the MODIFY AXR command.