Replaceable routines and exits

When a REXX exec runs, different system services are used for obtaining and freeing storage, handling data stack requests, loading and freeing the exec, and I/O. TSO/E provides routines for these system services. The routines are called replaceable routines because you can provide your own routines that replace the system-supplied routines. You can provide your own routines for non-TSO/E address spaces. In the TSO/E address space, you can provide your own routines only if the language processor environment is initialized with the TSOFL flag off. The TSOFL flag (see Flags and corresponding masks) indicates whether the language processor environment is integrated with TSO/E services. Types of environments - integrated and not integrated into TSO/E describes the two types of environments.

In addition to defining your own replaceable routines to replace the routines that TSO/E provides, you can use the interfaces as described in this chapter to call any of the TSO/E-supplied routines to perform system services. You can call the routines in any address space, that is, in any type of language processor environment. You can also write your own routine to perform a system service using the interfaces described for the routine. A program can then call your own routine in any address space to perform that particular service.

In addition to replaceable routines, TSO/E also provides several exits you can use to customize REXX processing. The exits let you customize the initialization and termination of language processor environments, exec processing itself, and attention interrupts. Unlike the replaceable routines that you can replace only in language processor environments that are not integrated into TSO/E, you can provide REXX exits in any type of environment (integrated and not integrated into TSO/E). One exception is the attention handling exit for attention interrupts. The exit applies only to TSO/E, so you can specify the exit only in an environment that is integrated into TSO/E.

This chapter describes each of the replaceable routines and the exits that TSO/E provides for REXX processing.

Replaceable Routines: If you provide a replaceable routine that will replace the system- supplied routine, your routine can perform some pre-processing and then call the system-supplied routine to actually perform the service request. If the replaceable routine you provide calls the system-supplied routine, your replaceable routine must act as a filter between the call to your routine and your routine calling the system-provided routine. Pre-processing can include checking the request for the specific service, changing the request, or terminating the request. Your routine can also perform the requested service itself and not call the system-supplied routine.

The routines that you can replace and the functions your routine must perform, if you replace the system-supplied routine, are summarized below. Replaceable routines describes each routine in more detail.

Exec Load: Called to load an exec into storage and free an exec when the exec completes processing. The exec load routine is also called to determine whether an exec is currently loaded and to close a specified data set.
I/O: Called to read a record from or write a record to a specified ddname. The I/O routine is also called to open a specified DD. For example, the routine is called for the SAY and PULL instructions (if the environment is not integrated into TSO/E) and for the EXECIO command.
Host Command Environment: Called to process all host commands for a specific host command environment.
Data Stack: Called to handle any requests for data stack services.
Storage Management: Called to obtain and free storage.
User ID: Called to obtain the user ID. The USERID built-in function returns the result that the user ID routine obtains.
Message Identifier: Called to determine whether the message identifier (message ID) is displayed with a REXX error message.

Replaceable routines are defined on a language processor environment basis. You define the names of the routines in the module name table. To define your own replaceable routine to replace the system-supplied routine, you must do the following:

Write the code for the routine. The individual topics in this chapter describe the interfaces to each replaceable routine.
Define the routine name to a language processor environment. For environments that are initialized in non-TSO/E address spaces, you can provide your own IRXPARMS parameters module that IRXINIT uses instead of the default IRXPARMS module. In your module, specify the names of your replaceable routines. You can also call IRXINIT to initialize an environment and pass the name of your module name table that includes the names of your replaceable routines.
In the TSO/E address space, you can call IRXINIT to initialize an environment and pass the name of your module name table that includes the names of the replaceable routines. When you call IRXINIT, the TSOFL flag in the parameters module must be off, so the environment is not integrated into TSO/E.

Changing the default values for initializing an environment describes how to provide your own parameters module. Initialization routine - IRXINIT describes IRXINIT.

You can also call any of the system-supplied replaceable routines from a program to perform a system service. You can also write your own routine that user-written programs can call to perform a service. This chapter describes the interfaces to the system routines.

Exit Routines: In addition to the replaceable routines, there are several exits you can use to customize REXX processing. Some of the exits have fixed names. Other exits do not have a fixed name. You name the exit yourself and then specify the name in the module name table. The exits are briefly described below. REXX exit routines describes each exit in more detail.

Pre-environment initialization – use to customize processing before the IRXINIT initialization routine initializes a language processor environment.
Post-environment initialization – use to customize processing after the IRXINIT initialization routine has initialized an environment, but before IRXINIT completes processing.
Environment termination – use to customize processing when a language processor environment is terminated.
Exec initialization – use to customize processing after the variable pool has been created and before the exec begins processing.
Exec termination – use to customize processing after an exec completes processing and before the variable pool is deleted.
Exec processing – use to customize exec processing before an exec is loaded and runs.
Attention handling – use to customize attention interrupt processing in TSO/E.

Unlike the replaceable routines, which you can define only in language processor environments that are not integrated into TSO/E, you can provide the exits in any type of environment. One exception is the attention handling routine, which is only applicable to the TSO/E address space (in an environment that is integrated into TSO/E). See REXX exit routines for more information about the exits.