Defining the Exit in SMFPRMxx

In the SMF parmlib member (SMFPRMxx), specify IEFACTRT on the EXITS option of 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 IEFACTRT routine only for work running under the subsystems you specify on SUBSYS. If you use the SYS option, the system invokes the IEFACTRT 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 IEFACTRT installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFACTRT or SYSyyy.IEFACTRT. 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 IEFACTRT 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 IEFACTRT, you need only define this exit in SMFPRMxx.

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

If you associate exit routines with IEFACTRT 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 Routine Environment

Exit Recovery

IBM strongly recommends that you set up an ESTAEX recovery routine to handle errors that might occur during the execution of IEFACTRT.

An ESTAE-type recovery routine is set up by the module that calls IEFACTRT; the recovery routine, if it gets control, will allow the job to continue processing if the exit routine abnormally ends.

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

Exit Routine Processing

At job or job step termination, use the termination indicators in record types 4, 5 and 30 to determine whether or not IEFACTRT cancelled the job.

Your exit routine should be aware of these added type 30 continuation records, because they are passed to IEFACTRT. See the CAUTION bullet in the next topic, "Programming Considerations," if the exit routine suppresses some of these records. See z/OS MVS System Management Facilities (SMF) for more information concerning type 30 records.

IEFACTRT is the only SMF exit routine that can write to a job log, but only by passing the message to module IEFYS. When IEFYS receives control, register 13 must contain the address of an 18-word save area and register 12 must be used to pass message information. Figure 1 shows the procedure for writing JOBLOG messages from IEFACTRT. The maximum number of characters that can appear in a message is 132.

         MVC   36(4,12),MSGADDR  MOVE MESSAGE ADDRESS AND
         MVC   42(2,12),MSGLEN   LENGTH TO SYSTEM TABLE
         L     REG15,VIEFYS      BRANCH AND LINK TO MESSAGE
         BALR  REG14,REG15       ROUTINE

MSGADDR  DC    A(MSG)
MSG      DC    C'message text'
MSGLEN   DC    H'xx'             MESSAGE LENGTH
VIEFYS   DC    V(IEFYS)

To resolve the VCON for IEFYS correctly, be sure to follow the example in Figure 2 which shows how to make an IEFACTRT installation exit routine available to the system by link editing it into a system library.

 //LKUSRPGM     JOB     MSGLEVEL=(1,1)
 //             EXEC    PGM=IEWL,PARM='XREF,LET,LIST'
 //SYSPRINT     DD      SYSOUT=A
 //SYSUT1       DD      UNIT=SYSDA,SPACE=(TRK,10)
 //SYSLMOD      DD      DSNAME=SYS1.LINKLIB,DISP=OLD
 //SYSLIB       DD      DSNAME=SYS1.AOSB3,DISP=SHR
 //SYSLIN       DD      *
     object deck
          INCLUDE    SYSLIB(IEFTB724)
          NAME       EXITNAME(R)
 /*

Programming Considerations

For information on how to use these macros, see z/OS MVS System Management Facilities (SMF).

Entry Specifications

SMF passes to IEFACTRT a code to define the reason for calling the exit routine and a list of parameter addresses that the routine can use.

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

Register

Contents

0

One of the following hexadecimal codes that indicate why SMF has invoked the exit:

Code

Explanation

X'0C'

Indicates job step termination. Word 10 in the parameter list is the address of the record descriptor word (RDW) for a type 4 or type 34 record.

X'10'

Indicates job termination. Word 10 in the parameter list is the address of the RDW for a type 5 or type 35 record.

X'14'

Indicates job or step termination. Word 10 in the parameter list is the address of the RDW for a type 30 record. The subtype field in the type 30 record determines if it is a job or a step termination record.

X'18'

Indicates TSO/E session or accounting interval termination. Word 10 in the parameter list is the address of the RDW for a type 32 record.

1

Address of the parameter list

2-11

Not applicable

12

Address of a message information area, which can be used to interface to IEFYS.

13

Register save area

14

Return address

15

Entry point address of IEFACTRT

Figure 3. IEFACTRT Input Parameter Structure

Common Exit Parameter Area

The common exit parameter area is a 56-byte area that contains information an SMF installation exit routine might need. It is a copy of the first 56 bytes of the job management record (JMR), of which the first 36 bytes are usable by the exit. In addition, byte 56 is a version indicator, which indicates whether additional information is available. When byte 56 is '01'x, an additional area is provided at offset 76, mapped by the JMRE DSECT within the JMR and contains an 8 character jobclass and a 64-byte job correlator, if provided by the primary JES subsystem.

The address of the common exit parameter area is passed to all SMF installation exits except IEFU29, IEFU83, IEFU84, and IEFU85. The common exit parameter area is mapped by macro IEFJMR, as part of the JMR, except for the indicator of the SMF option selected by the user field. This field is mapped by the SMCAOPT field in the SMCA data area. See Table 1 for a description of the area, and Accounting Information for a description of the accounting information. See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the complete mapping of the JMR and the complete mapping of the SMCA.

Accounting Information

The accounting information is presented to IEFACTRT differently than to IEFUAV, IEFUJI, and IEFUSI. IEFACTRT receives both the number of accounting fields and a pointer to the accounting fields in the input parameter list. See the parameter descriptions in Entry Specifications for more details. For the other exits, the input parameter list contains a pointer to all the accounting information as described in Table 2.

Figure 4 provides examples of accounting information. Note that these fields are contiguous and are only spaced in Figure 4 for clarity. These examples show different forms of accounting information you can specify in JCL, and the resulting representation (hexadecimal) that will be passed to the SMF exits list.

                                 .........Accounting Information.........
   JCL                                   .......Accounting Fields........
                                 #FIELDS LEN1 DATA1 LEN2 DATA2 LEN3 DATA3
-------------------------------------------------------------------------
//MYJOB JOB ,PROGNAM          -> 01      00
//MYJOB JOB 9,PROGNAM         -> 01      01   F9
//MYJOB JOB (9,8),PROGNAM     -> 02      01   F9    01   F8
//MYJOB JOB (9,8,77),PROGNAM  -> 03      01   F9    01   F8    02   F7F7
//MYJOB JOB '9',PROGNAM       -> 01      01   F9
//MYJOB JOB '9,8',PROGNAM     -> 01      03   F96BE8
//MYJOB JOB ('9','8'),PROGNAM -> 02      01   F9    01   F8
//MYJOB JOB ('9,8'),PROGNAM   -> 01      03   F96BF8
//MYJOB JOB (9,,8),PROGNAM    -> 03      01   F9    00         01   F8
//MYJOB JOB (9,',8),PROGNAM   -> 03      01   F9    00         01   F8
//MYJOB JOB ((9)),PROGNAM     -> 01      01   F9

Return Specifications

A return code from IEFACTRT (in register 15) indicates whether the job is to continue or terminate. Another return code (in register 1) indicates whether or not SMF is to write the termination records to the SMF data set.

The criterion is based on the contents of register 15. If multiple exit routines match the defined criterion, the system returns information from the exit routine called first.

The defined criterion is EXIT ATTRIB KEEPRC(GE,4).

If  Exit A returns with  R1 = 4  and  R15 = 0,
and Exit B returns with  R1 = 0  and  R15 = 8,
and Exit C returns with  R1 = 0  and  R15 = 4,
and Exit D returns with  R1 = 4  and  R15 = 4,

the final results are    R1 = 0  and  R15 = 8.

The system derives the return information from the first exit called that
matches the defined criteria. Here, R15 is greater or equal to 4, which
is Exit B.

The job continues (because R15 is not 4) and the system writes the
termination records to the SMF data set (because R1 for Exit B is not 4).

If you do not specify a criteria method, the system returns the information from the first exit routine that returns a value of four in register 15, and cancels the remaining job steps. If that exit routine also returns a value of four in register 1, the system does not write the termination records to the SMF data set. For any other value in register 1 the system does write the termination records.

There are no defined criteria.

If  Exit A returns with  R1 = 4  and  R15 = 0,
and Exit B returns with  R1 = 0  and  R15 = 8,
and Exit C returns with  R1 = 0  and  R15 = 4,
and Exit D returns with  R1 = 4  and  R15 = 4,

the final results are    R1 = 0  and  R15 = 4.

The system derives the return information from the first exit called that
returns a value of 4 in R15, which is Exit C.

The job terminates (because R15 is 4) and the system writes the
termination records to the SMF data set (because R1 for Exit C is not 4).

If no exit routine returns a value of four in register 15, the system returns the information from the exit routine that is called first, and the job continues. Again, if that exit routine returns a value of four in register 1, the system does not write the termination records to the SMF data set, while for any other value in register 1 from that exit routine, the system does write the termination records to the SMF data set.

There are no defined criteria.

If  Exit A returns with  R1 = 4  and  R15 = 0,
and Exit B returns with  R1 = 0  and  R15 = 8,
and Exit C returns with  R1 = 0  and  R15 = 0,

the final results are    R1 = 4  and  R15 = 0.

Because no exit set R15 to 4, the system derives the return information
from the first exit called, which is Exit A.

The job continues (because R15 is not 4) and the system does not write
the termination records to the SMF data set (because R1 for Exit A is 4).

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

Register

Contents

0

Restored to contents at entry

1

One of the following return codes:

Return Code

Explanation

Value of 4

SMF is not to write the termination record to the SMF data set.

Other than 4

SMF is to write the termination record to the SMF data set.

2-14

Restored to contents at entry

15

One of the following return codes:

Return Code

Explanation

Value of 4

The remaining job steps are to be cancelled.

Other than 4

Job processing is to continue.

Note: The system may fail a step or job even if the return code is zero. This could happen, for example, as a result of specifying CATLG_ERR FAILJOB(YES) and incurring that type of post execution error. (A return code is generated by the application program and is never changed by the operating system.) A user can deduce that a step failed due to a "post execution error" if bit SMF30SYE in the two-byte SMF30STI field in the SMF30 subtype 4 record is on.

Coded Example of the Exit Routine

Sample IEFACTRT exit routines are provided in SYS1.SAMPLIB in members SMFEXITS and IEEACTRT. The sample in SMFEXITS changes the SMF job termination (types 5 and 35) and job step termination (types 4 and 34) records to user records, and attempts to write them to an SMF data set. If the data set is full, the routine writes a message to the console indicating that SMF records are being lost. At job termination, the routine writes a record containing the job name, programmer's name, and account number to the JOBLOG data set.

The IEEACTRT exit routine puts a summary of the step on each JES2 job log using WTO with ROUTCODE=14. The summary includes both step and job information.