IEFU29L — SMF Log Stream Dump 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 dump exit IEFU29L allows you to initiate the archiving of SMF data from a log stream. IEFU29L is invoked using the SWITCH SMF command.

Note that you can use the system logger to manage how long you retain the SMF log stream data and to automatically offload the log stream data to VSAM linear DASD data sets, so you might not need to use IEFU29L to drive the archiving of the SMF log stream data. See "Managing Log Data: How Much? For How Long?"in z/OS MVS Setting Up a Sysplex.

Use IEFU29L to perform the following tasks:

Issue the WTO macro to request that the operator start the SMF log stream dump program, IFASMFDL.
Initiate the dump program by submitting a job request to an internal reader.

Defining the Exit in SMFPRMxx

To allow the system to invoke IEFU29L, define the exit in the SMF parmlib member (SMFPRMxx). Specify IEFU29L on the EXITS option of the SUBSYS parameter for the STC subsystem. If your installation chooses not to define a SUBSYS parameter for STC, you can specify IEFU29L on the EXITS option of the SYS parameter.

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 IEFU29L installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFU29L or SYSyyy.IEFU29L. 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 IEFU29L 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 only need to define IEFU29L in SMFPRMxx.

If you do not associate any exit routines with exit IEFU29L in PROGxx, by default, the system uses the exit routine name that matches the exit name (IEFU29L).

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 that 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 the bit SDWACLUP off.

By default, the system does not disable the exit routine.

Exit Routine Environment

IEFU29L receives control in the following environment:

Enabled for interruptions.
In supervisor state with PSW key 0.
In AMODE 24 or 31.
In the SMF address space.

Exit Recovery

IBM suggests that you set up an ESTAEX recovery routine to handle errors that might occur during the execution of IEFU29L.

An ESTAE-type recovery routine is set up by the module that calls IEFU29L; if the recovery routine gets control, it will prevent SMF from ending when the exit routine ends abnormally.

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

Exit Routine Processing

The SMF dump exit receives control from the SMF writer when the SWITCH SMF command is issued to dump data from an SMF log stream.

Programming Considerations

IEFU29L 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.

Note: IEFU29L runs in the SMF address space that runs under the MSTR subsystem rather than JES. Therefore, jobs submitted to the internal reader from IEFU29L will run under MSTR rather than JES. To have a job run under JES, you must request that the job run on JES rather than the MSTR subsystem. For more information about submitting a job request to an internal reader, see z/OS MVS Using the Subsystem Interface.

Macro Instructions and Restrictions: IEFU29L can issue the WTOR macro (for example, to request the operator to start the dump program). When you issue the WTOR macro, specify LONG=YES on the WAIT macro.

IEFU29L cannot use the SMFWTM or SMFEWTM macro to write records to the SMF log stream.

Entry Specifications

SMF passes to IEFU29L a parameter list mapped by IEFU29LM, which contains the name of the log stream.

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

Register: Contents
0: Not applicable
1: Address of a pointer to a parameter list of IEFU29L, mapped by the IFAU29LM control block
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of IEFU29L

Parameter Descriptions: When IEFU29L is driven, control block IEFU29LM will receive Register 1, which points to the following address. Figure 1 shows an example of input parameter structure.

Word 1: An array of pointers, each of which point to U29L_PARM mapped in IFAU29LM. The high order bit of the pointer signifies that it is the last one.

Figure 1. IEFU29L Input Parameter Structure

Return Specifications

No return information is expected.

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

Register: Contents
0-15: Not applicable

Coded Example of the Exit Routine

A sample IEFU29L exit is provided in SYS1.SAMPLIB in member IEEU29. The sample exit consists of an Assembler stub that calls a REXX program, passing the names of the log streams as parameters. The sample REXX program returns the log stream names to the console and can be modified as necessary.