IEFU84 — SMF Record Exit

Topics for This Exit Appear as Follows:

Defining the Exit in SMFPRMxx
Controlling the Exit Routine Through the Dynamic Exits Facility
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Programming Considerations
- Macro Instructions and Restrictions
Entry Specifications
- Registers at Entry
Return Specifications
- Registers at Exit

The SMF record exit IEFU84 receives control when the caller invokes the SMFEWTM macro, specifying BRANCH=YES. After exit routine processing, IEFU84 returns a code that specifies whether the SMF record should be written to the SMF data set. The SMFEWTM macro allows the issuer to branch directly to the SVC routine without issuing the SVC. IEFU84 does not receive control for records suppressed because of options selected at IPL time or via the SET SMF command.

You can use IEFU84 to:

Select or suppress those records to be written to the SMF data set. For example, an installation with a large TSO/E account might want to suppress SMF records for all but a few selected TSO/E users.
Check resource use during a specific interval. For example, select records during the peak workload period.
Suppress some of the record type 30 subtypes.

Defining the Exit in SMFPRMxx

In the SMF parmlib member (SMFPRMxx), specify IEFU84 on the EXITS option of either the SYS or SUBSYS parameters, depending on the scope of work (system-wide or subsystem-wide) the exit is to affect.

If you use the SUBSYS option, the system invokes the IEFU84 routine only for work running under the subsystems you specify on SUBSYS. If you use the SYS option, the system invokes the IEFU84 routine for work running under any SMF-defined subsystem, such as JES2, JES3, STC, ASCH, OMVS, or TSO.

For more information about coding the EXITS option, see the description of SMFPRMxx in z/OS MVS Initialization and Tuning Reference.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM® has defined the IEFU84 installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFU84 or SYSyyy.IEFU84. See the description of the SMFPRMxx parmlib member in z/OS MVS Initialization and Tuning Reference for an explanation of the naming conventions for SMF exit routines. 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.

To define IEFU84 to the dynamic exits facility, you must specify the exit in both PROGxx and SMFPRMxx. The system does not call the exit if it is defined in PROGxx only. If you do not plan to use the dynamic exits facility for this exit, you need only define IEFU84 in SMFPRMxx.

If you do not associate any exit routines with exit IEFU84 in PROGxx, the system defaults to using the exit routine name that matches the exit name (IEFU84).

If you associate exit routines with this exit in PROGxx, the system does not use the default exit routine. If you need the default exit routine, you should explicitly add it to PROGxx.

You can use the ADDABENDNUM and ABENDCONSEC parameters 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. An abend is counted when both of the following conditions exist:

The exit routine does not provide recovery, or the exit routine does provide 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 disables the exit routine after two consecutive abends.

Exit Routine Environment

IEFU84 receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In AMODE 31.
In the address space of the task that issues the SMFEWTM BRANCH=YES macro.
Can be locked or in SRB mode.

Exit Recovery

If IEFU84 abnormally terminates, SMF, in most cases, does not terminate. SMF marks the exit as not valid and issues message IEE952I to the operator. If the exit performs a critical function, the operator can issue a SET SMF or SETSMF command to terminate recording. Otherwise, SMF recording continues but bypasses the installation exit routine.

IBM strongly recommends that you set up an FRR recovery routine to handle errors that might occur during the execution of your exit routine. The FRR should use the EUT=YES option to handle errors that occur when the exit is called in unlocked task mode.

An FRR is set up by the module that calls IEFU84; the recovery routine, if it gets control, will prevent SMF from ending if the exit routine abnormally ends. If this recovery routine gets control on two consecutive invocations of the exit, SMF requests that the exit routine be marked inactive, preventing any further invocations of that exit routine. The system issues message CSV430I, naming the exit and the exit routine.

If the exit performs a critical function, the operator can issue a SET PROG or SETPROG MODIFY command to change the status of the exit to active. This should be done only if you have corrected the program, or if you know the error conditions are transient.

Whether or not the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.

Exit Routine Processing

Each SMF record is passed to an installation exit (either IEFU83, IEFU84 or IEFU85) before it is written to the SMF data set. If you use the SMFEWTM macro and specify BRANCH=YES, SMF invokes installation exit IEFU84. If you use the SMFWTM macro or if you specify BRANCH=NO on the SMFEWTM macro, SMF invokes installation exit IEFU83.

The SMFEWTM macro verifies that SMF recording is active and allows the issuer to branch directly to the SVC routine without issuing the SVC. BRANCH=YES causes the macro to generate a call to the subroutine that moves the data to the SMF buffer.

IEFU84 places a return code in register 15 before returning control; the code indicates whether the record is to be written to the SMF data set.

Programming Considerations

IEFU84 must be reenterable and refreshable, because PLPA pages are stolen. That is, they can be paged in but not paged out, and subsequent page-ins overlay any code changes.

IEFU84 cannot access installation-defined data sets.

The addresses of the user communication and user identification fields of the common exit parameter area (a copy of the first 36 bytes of the JMR) are not passed to the IEFU84 exit routine. To obtain these addresses, the exit routine can follow pointers from the ASXB to the TCB to the JMR. In the ASXB, the ASXBLTCB points to a chain of TCBs. The ASXB can be found from the field ASCBASXB in the ASCB which in turn can be found from the PSAAOLD in the PSA.

In the TCB, the TCBTCT field points to the TCT. In the TCT, the TCTJMR field points to the JMR. The JMR and the PSA are mapped by macros IEFJMR and IHAPSA, respectively. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping of the JMR, and z/OS MVS Data Areas, Vol 5 (SSAG-XTLST) for the mappings of the TCB and the TCT.

Note: If you use the ASXBLTCB, this would only be the LAST TCB that was attached in the address space, and would not necessarily be running, or even dispatchable. You would have determine that by looking at the dispatchability bits in the TCB. Or you could start with the ASXBFTCB, which will point to the Region Control Task's TCB, and chain down from that using the TCBTCB field.

APPC/MVS Consideration: You might want your exit routine to perform specific processing for work initiated by the APPC/MVS transaction scheduler. To enable your exit routine to determine when it has been invoked during this type of processing, have the routine check the OUCBSUBN field in the OUCB control block. For APPC/MVS TPs, this field is set to 'ASCH' (EBCDIC).

The exit routine can access OUCBSUBN by chaining through pointers from the PSA to the ASCB to the OUCB. In the PSA, the PSAAOLD points to the ASCB. In the ASCB, the ASCBOUCB field points to the OUCB.

The ASCB, OUCB, and the PSA are mapped by macros IHAASCB, IRAOUCB, and IHAPSA, respectively. The mappings are described in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Macro Instructions and Restrictions: When issuing a WTOR macro, specify LONG=YES on the WAIT macro.

IEFU84 cannot use the SMFWTM or SMFEWTM macro to write to the SMF data set.

Because IEFU84 might be locked or in SRB mode, the exit routine cannot issue any SVCs. IEFU83 may be given the alias name IEFU84, if IEFU83 can run locked or SRB mode.

Entry Specifications

SMF passes to IEFU84 the address of a fullword that points to the SMF record.

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

Register: Contents
0: Not applicable
1: Address of the parameter list
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of IEFU84

Parameter Descriptions: Register 1 points to the following address:

Word 1: The address of the record that SMF is to write. The first four bytes of this record are the record descriptor word (RDW). See z/OS MVS System Management Facilities (SMF) for a description of the RDW.

Figure 1. IEFU84 Input Parameter Structure

Return Specifications

A return code from IEFU84 indicates whether the current SMF record is to be suppressed.

If you associate multiple exit routines with IEFU84, you can specify how the return information is to be handled using the ATTRIB KEEPRC function of the SETPROG EXIT command, the EXIT statement of PROGxx, or CSVDYNEX services. If multiple exit routines match the ATTRIB KEEPRC criteria, the system returns information from the exit routine that finished first.

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

If you associate multiple exit routines with exit IEFU84, and any of those exit routines return with a value of 4, the system does not write the record to the SMF data set.

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

Register

Contents

0-14

Same as at entry

15

One of the following return codes:

Return Code: Explanation
Value of 4: SMF is not to write the record to the SMF data set.
Other than 4: SMF is to write the record to the SMF data set.