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 350) indicates whether the language processorenvironment is integrated with TSO/E services.
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 spaceto 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 section 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.
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.
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.
- 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).
Replaceable Routines
The following topics describe each of the TSO/E REXX replaceable routines. The documentation describes how the system-supplied routines work, the input they receive, and the output they return. If you provide your own routine that replaces the system-supplied routine, your routine must handle all of the functions that the system-supplied routine handles.
The replaceable routines that TSO/E provides are programming routines that you can call from a program in any address space. The only requirement for invoking one of the system-supplied routines is that a language processor environment must exist in which the routine runs. The language processor environment can either be integrated or not integrated into TSO/E. For example, an application program can call the system-supplied data stack routine to perform data stack operations or call the I/O routine to perform I/O.
You can also write your own routines to handle different system services. For example, if you write your own exec load routine, a program can call your routine to load an exec before calling IRXEXEC to invoke the REXX exec. Similar to the system-supplied routines, if you write your own routine, an application program can call your routine in any address space as long as a language processor environment exists in which the routine can run. The environment can either be integrated or not integrated into TSO/E.
You could also write your own routine that application programs can call to perform a system service, and have your routine call the system- supplied routine. Your routine could act as a filter between the call to your routine and your routine calling the system-supplied routine.For example, you could write your own exec load routine that verifies a request, allocates a system load file, and then invokes the system-supplied exec load routine to actually load the exec.
General Considerations
This topic provides general information about the replaceable routines.
- If you provide your own replaceable routine, your routine is called in 31 bit addressing mode. Your routine may perform the requested service itself and not call the system-supplied routine. Your routine can perform pre-processing, such as checking or changing the request or parameters, and then call thecorresponding system-supplied routine. If your routine calls the system routine to actually perform the request, your routine must call the system routine in 31 bit addressing mode also.
- When the system calls your replaceable routine, your routine can use any of the system-supplied replaceable routines to request system services.
- The addresses of the system-supplied and any user-supplied replaceable routines are stored in the REXX vector of external entry points . This allows a caller external to REXX to call any of the replaceable routines, either the system-supplied or user-supplied routines. For example, if you want to preload a REXX exec in storage before using the IRXEXEC routine to invoke the exec, you can call the IRXLOAD routine to load the exec. IRXLOAD is the system-supplied exec load routine. If you provide your own exec load routine, you can also use your routine to preload the exec.
- When a replaceable routine is invoked by the system or by an application program, the contents of register 0 may or may not contain the address of the environmet block.
Using the Environment Block Address
If you provide a user-supplied replaceable routine that replaces a system-supplied replaceable routine, when the system calls your routine, it passes the address of the environment block for the current environment in register 0. If your user-supplied routine then invokes the system-supplied routine, it is suggested that you pass the environment block address you received to the system-supplied routine. When you invoke the system-supplied routine, you can pass the environment block address in register 0. Some replaceable routines also have an optional environment block address parameter that you can use.
If your user-supplied routine passes the environment block address in the parameter list,the system-supplied routine uses the address you specify and ignores register 0.
Additionally, the system-supplied routine does not validate the address you pass. Therefore,you must ensure that your user-supplied routine passes the same address it received in register 0 when it got control.
If your user-supplied routine does not specify an address in the environment block address parameter or the replaceable routine does not support the parameter,the system-supplied routine checks register 0 for the environment block address.If register 0 contains the address of a valid environment block,the system-supplied routine runs in that environment. If the address in register 0 is not valid, the system-supplied routine locates and runs in the current non-reentrant environment.
If your user-supplied routine does not pass the environment block address it received to the system-supplied routine, the system-supplied routine locates the current non-reentrant environment and runs in that environment. This may or may not be the environment in which you want the routine to run. Therefore, it is suggested that you pass the environment block address when your user-supplied routine invokes the system-supplied routine.
An application program running in any address space can call a system-supplied or user-supplied replaceable routine to perform a specific service. On the call, the application program can optionally pass the address of an environment block that represents the environment in which the routine runs. The application program can pass the environment block address in register 0 or in the environment block address parameter if the replaceable routine supports the parameter. Note the following for application programs that invoke replaceable routines:
- If an application program invokes a system-supplied replaceable routine and does not pass an environment block address, the system-supplied routine locates the current non-reentrant environment and runs in that environment.
- If an application program invokes a user-supplied routine, either the application program must provide the environment block address or the user-supplied routine must locate the current environment in which to run.
Installing Replaceable Routines
If you write your own replaceable routine, you must link-edit the routine as a separate load module. You can link-edit all your replaceable routines in a separate load library or in an existing library that contains other routines. The routines can reside in:
- The link pack area (LPA)
- Linklist (LNKLIST)
- A logon STEPLIB
The replaceable routines must be reentrant, refreshable, and reusable. The characteristics for the routines are:
- State: Problem program
- Not APF-authorized
- AMODE(31), RMODE(ANY)
|
List Of Topics 
IBM-REXX
Related Jobs