IEFU86 — SMF record exit
Topics for this exit appear as follows:
The IEFU86 exit receives control for SMF records with either standard or extended headers. See the Standard and Extended SMF record headers section in z/OS MVS System Management Facilities (SMF) for details.
IEFU86 receives control when the caller invokes the SMFWTM or SMFEWRM macros. Unlike the IEFU83, IEFU84, and IEFU85 exits, IEFU86 receives control regardless of the mode of the caller or the SMFWTM or SMFEWTM invocation parameters.
After exit routine processing, IEFU86 returns a code that specifies whether SMF is to write the SMF record to the SMF data set. IEFU86 does not receive control for records whose writing has been suppressed either because of a system failure or because of SMFPRMxx options selected at IPL time or through the SET SMF command.
- Select or suppress those records to be written to the SMF data set or log stream. For example, an installation with a large TSO/E account might want to suppress the SMF dynamic DD records (type 40).
- Check resource use during a specific interval. For example, select records during the peak workload period.
Defining the exit in SMFPRMxx
In the SMF parmlib member (SMFPRMxx), specify IEFU86 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 IEFU86 routine only for work running under the subsystems you specify on SUBSYS. If you use the SYS option, the system invokes the IEFU86 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 IEFU86 installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFU86 or SYSyyy.IEFU86. 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 IEFU86 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 IEFU86 in SMFPRMxx.
The exit should reside in LPA, the LNKLST concatenation, or the nucleus. Do not use the DSNAME keyword when defining the exit in PROGxx, as the system will not be able to load the exit when restarting SMF.
If you do not associate any exit routines with exit IEFU86 in PROGxx, the system defaults to using the exit routine name that matches the exit name (IEFU86).
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.
Exit recovery
If IEFU86 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.
A functional recovery routine (FRR) is set up by IEEMB830 (the SVC 83 routine) because the caller is in cross memory mode.
Exit routine environment
IEFU86 receives control in the address space of the program that called the
SMFWTM or SMFEWTM service. Following is a description of the environment:
- Enabled for interrupts.
- In supervisor state with PSW key 0.
- In AMODE 31.
- Task or SRB mode.
- Can be invoked in cross memory mode.
- Can be holding the local lock.
See the IFAEXITP parameter list map for more information about how the exit was called.
Exit routine processing
Each SMF record is passed to IEFU86 before it is written to the SMF data set or log stream. The exit receives control for SMF records with either standard or extended headers The exit receives control regardless of whether SMFWTM or SMFEWTM was used to write the record, and regardless of the parameters used on the calls.
IEFU86 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 or log stream.
Programming considerations
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 the z/OS MVS Data Areas under z/OS Internet library.
Entry specifications
SMF passes to IEFU86 the address of a fullword that points to the parameter list that is mapped by the IFAEXITP mapping macro.
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. See Parameter Descriptions for more details.
- 2-12
- Not applicable.
- 13
- Register save area
- 14
- Return address.
- 15
- Entry point address of IEFU86.
Parameter descriptions
| Offset | Length | Type | Description |
|---|---|---|---|
| 0 | 4 | Character | Eye catcher - 'SMXP' |
| 4 | 2 | Binary | Length of this structure |
| 6 | 1 | Binary | Version - 1 |
| 7 | 1 | Binary |
|
| 8 | 4 | Binary | Pointer to the SMF record |
| C | 2 | Binary | Offset to the work area |
| E | 2 | Binary | Length of the work area |
- Work area described in IFAEXITP
-
Table 2. IEFU86 work area Offset Length Type Description 0 See Description in this table. Character Work area that is located past the parameter list at an offset value at + 'C'x into the parameter list. The length value of the work area is at + 'E'x into the parameter list.
Return specifications
A return code from IEFU86 indicates whether the current SMF record is to be suppressed.
If you associate multiple exit routines with IEFU86, 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 is returned.
If you associate multiple exit routines with exit IEFU86, and any of those exit routines return with a value of 4, the current SMF record is suppressed.
Registers at exit: Upon return from the exit processing, the register contents must be as follows:
- Register
- Contents
- 0 - 1
- Not applicable.
- 2
- Deleted by exit call processing.
- 3 -14
- Not applicable.
- 15
- Note: If multiple IEFU86 exits are called, or if any of the IEFU83, IEFU84, or IEFU85 exits are called, SMF accepts any of the exits that set a return code of 4.One of the following return codes:
- Return code
- Explanation
- Value of 0
- SMF is to write the record.
- Value of 4
- SMF is to not write the record.
- Other Value
- SMF is to write the record.
Recovery considerations
If IEFU86 abnormally terminates, SMF, in most cases, does not terminate. SMF deactivates the exit and then issues message CSV430I 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 ESTAEX recovery routine to handle errors that might occur during the execution of your exit routine.
An ESTAE-type recovery routine is set up by the module that calls IEFU86; the recovery routine, and if it gets control, prevents 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 corrected the program, or if you know that the error conditions are transient.
Whether the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.