IEFJFRQ — Subsystem Function Request Exit

Topics for This Exit Appear as Follows:

You can use the IEFJFRQ exit to tailor the subsystem interface (SSI) processing of subsystem function requests. See z/OS MVS Using the Subsystem Interface for more information on subsystem function requests.

IEFJFRQ receives control at two different points in SSI function request processing:
  • Prerequest — before the SSI routes either a directed or broadcast subsystem function request to the target subsystem(s). For broadcast requests, IEFJFRQ is called once for each subsystem defined to the SSI.
  • Postrequest — after the SSI has routed either a directed or broadcast subsystem function request to all appropriate subsystems.
At the prerequest point, you can use IEFJFRQ to modify or suppress processing for any subsystem, or for any subsystem function request. (See z/OS MVS Using the Subsystem Interface for a list of subsystem function requests.) For example, you can:
  • Suppress commands or WTOs.
  • Prevent calls to a specific subsystem, for example, a subsystem that is failing repeatedly.
  • Route directed requests to a different subsystem.
  • Interrupt a broadcast request, that is, cause the SSI to discontinue routing the broadcast request to the subsystems that have not yet processed the request.
  • Maintain records of subsystem invocation.
  • Enforce installation policies for subsystem invocation.
  • Modify the return code that the caller of the SSI receives.
At the postrequest point, you can use IEFJFRQ to:
  • Update records to reflect the results of function requests acted on by multiple exit routines during the prerequest processing.
  • Modify the return code that the caller of the SSI receives.

Applications using the IEFJFRQ installation exit can determine whether it is available by testing the JESFRQEX flag in the JESFLG field of the JESCT data area.

Controlling the Exit Routine through the Dynamic Exits Facility

IBM® has defined the IEFJFRQ exit to the dynamic exits facility. You can refer to the exit by the name IEFJFRQ. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and its exit routines.

You may install more than one exit routine at the IEFJFRQ exit point. Each exit routine can examine and modify the control blocks that represent the subsystem function request. The control blocks passed to the target subsystem reflect the modifications made by all installed exit routines.

You can control the order that exit routines receive control by using the FIRST or LAST parameter on one of the following services:
  • The CSVYDYNEX REQUEST=ADD macro
  • The SETPROG EXIT,ADD command
  • The EXIT ADD statement of the PROGxx parmlib member.
You can use the ADDABENDNUM parameter on the CSVDYNEX REQUEST=ADD macro or the ABENDNUM parameter of the SETPROG EXIT operator command to limit the number of times the exit routine abnormally ends before it becomes inactive. See z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN for more information on the CSVDYNEX macro, and z/OS MVS System Commands for more information on the SETPROG EXIT operator command. An abend is counted when both of the following conditions exist:
  • The exit routine does not provide recovery, or the exit routine provides recovery but percolates the error
  • The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.
By default, the system does not disable the exit routine. Note that IEFJFRQ cannot take advantage of consecutive abend processing, since IEFJFRQ supports fastpath calls in any PSW key,

You can use the DELETE parameter on the CSVDYNEX macro, or the SETPROG EXIT,DELETE command to delete exit routines from IEFJFRQ. If the delete request does not specify FORCE=YES, the system will not free the exit routine's storage, since the IEFJFRQ exit supports callers in any PSW key. See z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN for more information on the FORCE parameter on the CSVDYNEX macro, and z/OS MVS System Commands for more information on the FORCE parameter on the SETPROG command.

Exit Routine Environment

IEFJFRQ receives control in the following environment:
  • Enabled for interrupts
  • In the state and key of the caller of the SSI (issuer of the IEFSSREQ service that produced the subsystem function request that drives this exit)
  • In AMODE 31
  • With any locks held by the caller of the SSI
  • In primary ASC mode
  • In the dispatch mode (task or SRB) of the caller of the SSI
  • In the cross-memory mode of the caller of the SSI.

Exit Recovery

You should consider the resources accessed by your exit routine and the impact on system performance, when evaluating whether your exit routine should provide its own recovery. IBM recommends that you establish your own recovery only if you access system resources, and only for subsystem function requests that concern your exit routine.

A system recovery routine will get control if:
  • The exit routine abnormally ends and the exit routine does not provide its own recovery
  • The error percolates beyond the exit routine's recovery routine
The system does not route the function request to any other exit routines associated with the exit, or to the target subsystem. If the error occurs while the SSI is processing a broadcast request, the SSI continues routing the request to any remaining subsystems. The abend processing of the dynamic exits facility determines whether the exit routine continues to be invoked.

Exit Routine Processing

When IEFJFRQ receives control, the SSI has:
  • Validated the SSOB and SSIB control blocks to ensure that these control blocks are addressable and have the correct eyecatchers and lengths. Note that an SSOB may have more than one acceptable length.
  • Set the SSOBSSIB field in the SSOB control block to point to the life-of-job SSIB, if the original subsystem function request did not specify an SSIB control block. See z/OS MVS Using the Subsystem Interface for more information on the life-of-job SSIB.
IEFJFRQ may be called multiple times for each subsystem function request. The process for calling IEFJRFQ differs depending on whether the request is directed or broadcast as follows:
  • For directed requests, IEFJFRQ is called:
    • Once before the target subsystem receives control
    • Once after the target subsystem receives control

    Note that the postrequest instance is called even if the prerequest instance caused the SSI to bypass the call to the target subsystem.

  • For broadcast requests, IEFJFRQ is called:
    • Once when the MSTR subsystem is invoked to initiate the broadcast processing
    • Once for each target subsystem
    • Once after broadcast processing is complete and the request has been routed to all appropriate subsystems.

    Note that the postrequest instance is called even if the prerequest instance caused the SSI to bypass all broadcast processing.

Prerequest processing:

IEFJFRQ receives control at the prerequest processing exit point before the SSI routes either a directed or broadcast subsystem function request to the target subsystem(s). Note that IEFJFRQ is invoked once for each subsystem receiving the request.

Postrequest processing:

IEFJFRQ receives control at the postrequest processing point after the SSI has routed either a directed or broadcast subsystem function request to all appropriate subsystems. Its primary purpose is to inform exit routines of the actions the SSI has taken with respect to the current subsystem function request.

Programming Considerations

IEFJFRQ exit routines must be reentrant.

Exit routines receive a pointer to the control blocks that represent the subsystem function request, which include the SSOB, SSIB, SSOB extension, and any areas pointed to from these control blocks. Exit routines should be careful when modifying any of these control blocks.

IEFJFRQ exit routines should not take actions that result in a call to the SSI, such as issuing a system command or dynamic allocation request. Actions that result in a call to the SSI could result in infinitely recursive calls to the IEFJFRQ exit. For example, an exit routine cannot issue an SVC WTO when processing a WTO/WTOR function request (SSI function code 9).

The SSI provides a 12-byte correlation token, named FRQP_CORRELATION_TOKEN, in the IEFJFRQP parameter mapping to assist exit routines in correlating calls resulting from a single subsystem function request. The correlation token has the following characteristics:
  • The token is not valid if the system clock is not operating
  • The first 8 bytes of the token are unique over the life of an IPL on a single system
  • The 8-byte single system token concatenated with the 4-byte system ID in the parameter mapping form a 12-byte token that is unique across a sysplex.

Performance Considerations:

SSI processing, specifically the routing of subsystem function requests, may impact performance; therefore, consider the following recommendations so that system performance is not degraded:
  • Exit routines installed at the IEFJFRQ exit point should not perform operations that may degrade system performance, such as; issuing WAIT requests, issuing requests for large amounts of dynamic storage, or issuing I/O requests. To reduce the need for storage requests, the system provides an area that your exit routine can use for dynamic storage. The FRQP_DYNSIZE constant in the IEFJFRQP parameter mapping defines the size of the dynamic storage area. The exit routine must clear the dynamic storage area before using it, because all exit routines installed at the IEFJFRQ exit point use the same work area.
  • Exit routines should quickly determine whether the current subsystem function request is of interest, and return to the system immediately if not. Time consuming operations, such as obtaining storage, should be deferred until after this check. You can delay the establishment of recovery to perform this check, as long as the check references only information identified by the input control blocks, that is, the IEFJFRQP parameter area, the SSOB, and the SSIB.

Entry Specifications

The IEFJFRQP macro maps the input to the IEFJFRQ exit, and contains the following information:
  • The address of the SSOB control block representing the subsystem function request
  • Flags that indicate:
    • Which instance (prerequest or postrequest) of the exit is being called
    • Whether the subsystem function request is a broadcast request
    • Whether the SSIB is a copy of the life-of-job SSIB or was provided by the SSI's caller.
  • The current value of the return code that is passed back to the caller of the SSI, if IEFJFRQ does not change this value.
  • A token that you can use to correlate exit calls resulting from a single subsystem function request.

For directed requests, the current return code value is always zero for the prerequest instance of the exit.

Every broadcast request begins as a subsystem function request directed to the MSTR subsystem. The SSI cannot determine if the request represents a broadcast request until the MSTR subsystem processes this request. Therefore, the broadcast indicator is not set when the SSI calls the prerequest instance of IEFJFRQ for a request directed to the MSTR subsystem, even if the request will eventually be a broadcast request.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register
Contents
0
Does not contain any information for use by the exit routine
1
Address of a list of pointers
2-12
Does not contain any information for use by the exit routine
13
Register save area
14
Return address
15
Entry point address of IEFJFRQ exit routine
Parameter List Contents: Register 1 points to the following list of addresses, which are mapped by the FRQP_PLIST_AREA field of the IEFJFRQP macro:
  • The address of the IEFJFRQP parameter area
  • The address of the working storage that the system provides for use by the exit routine.
Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.

Return Specifications

The exit routine must specify the following return codes:
  • A return code passed in register 15 that controls the system's processing of the subsystem function request
  • A return code in register 0 that is passed to the caller of the SSI.

For the prerequest instance of the IEFJFRQ exit, the return code passed in register 0 for the caller of the SSI is used only if the return code passed in register 15 indicates that the SSI should not pass the subsystem function request to the target subsystem.

For the postrequest instance of IEFJFRQ, the return code passed in register 0 is passed back to the caller of the SSI. You can preserve the return code that would be returned by the SSI by copying FRQP CURRENT SSI RETCODE in register 0. Register 0 must contain one of the return code values defined in the IEFSSOBH mapping macro.

If you associate multiple exit routines with IEFJFRQ, you can specify how the return information is handled by using the ATTRIB KEEPRC function on one of the following:
  • The SETPROG EXIT command
  • The EXIT statement of the PROGxx parmlib member
  • The CSVDYNEX macro services.

If multiple exit routines match the ATTRIB KEEPRC criteria, the system returns information from the exit routine that finished first.

Note that the KEEPRC function specifies tests to be performed on the return code set in register 15 on exit from the IEFJFRQ exit routine. The results of the tests control the information that is returned to the SSI, that is, both the exit's return code in register 15 and the SSI caller's return code in register 0.

If you do not specify the ATTRIB KEEPRC function, the system returns the information from the exit routine with the largest return code value. If multiple exit routines return with the same value, the value in the exit routine that finished first will be returned.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register
Contents
0
Return code to be provided to the caller of the SSI
1
The exit routine does not have to place any information in this register, and does not have to restore its contents to what they were when the exit routine received control.
2-14
Restored to contents on entry
15
One of the following return codes:
Return Code
Explanation
0
Route the subsystem function request to the target subsystem
4
Do not route the subsystem function request to the target subsystem
8
Do not route the subsystem function request to the target subsystem, or for broadcast requests, do not route the subsystem function request to any remaining subsystem that has not yet processed the request.
24
Do not route the subsystem function request to the target subsystem, or for broadcast requests, do not route the subsystem function request to any remaining subsystem that has not yet processed the request. Do not call any remaining IEFJFRQ exit routines.

The IEFJFRQP macro provides mnemonic names for the return code values.

Coded Example of the Exit Routine

A sample IEFJFRQ exit routine is provided in SYS1.SAMPLIB (in member IEFJSXIT).