IEFUJI — Job Initiation 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
- Parameter Descriptions
Return Specifications
- Registers at Exit
Coded Example of the Exit Routine

IEFUJI receives control before the system selects a job on the input queue for initiation. A return code from IEFUJI indicates whether job processing is to continue or be cancelled.

You can use IEFUJI to:

Validate job accounting information.
Determine how long a job was on the input job queue before it was selected.
Write particular information to an installation data set.

Defining the Exit in SMFPRMxx

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

To define IEFUJI 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 IEFUJI in SMFPRMxx.

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

If you associate exit routines with IEFUJI 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 does not disable the exit routine.

Exit Routine Environment

IEFUJI 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 job that is being started.
With no locks or ENQs held.

Exit Recovery

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

An ESTAE-type recovery routine is set up by the module that calls IEFUJI; 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

IEFUJI receives control from the system whenever a job on the input queue is selected for initiation. If the system availability manager (SAM) function is active and operational, the SAM job/step initialization exit routine executes before IEFUJI is called.

IEFUJI has information from the JOB statement available as parameters. The accounting information is in a formatted list, so that, for account number processing, IEFUJI is easier to use than exit IEFUJV. Table 2 shows the format of the JOB statement accounting information.

At the end of its processing, IEFUJI sets a return code to indicate whether job processing is to continue or not.

Programming Considerations

SMF automatically provides a replaceable module for IEFUJI. If an installation includes IEFUJI, it must follow certain programming standards:

The exit routine must follow standard linkage conventions.
Code the exit routine reenterable and refreshable.
IEFUJI can perform dynamic allocations and write to installation-defined data sets. In foreground jobs, data sets are allocated dynamically. However, for background jobs, you can either allocate data sets dynamically or you can pre-define (pre-allocate) a data set with a DD statement in the initiator cataloged procedure.
IEFUJI cannot access ISAM data sets.
Do not use a WTO with a routing code of 11 to send a message to the JESYSMSG data set for started tasks or TSO users.
Do not use subpool 240 or 250 when obtaining storage for this exit. Using these subpools may result in errors when the exit receives control for address spaces that are created with the KEEPRGN attribute.
To provide a consistent environment for accessing and allocating data sets across calls to SMF exits for the duration of a job or task, IEFUJI receives control with the initiator's JSCB active.

At job or job step termination, use the termination indicators in SMF record types 4, 5, 30, 34, and 35 to indicate that IEFUJI cancelled the job.

Macro Instructions and Restrictions: When issuing a WTOR macro, specify LONG=YES on the WAIT macro. Do not use a WTO with a routing code of 11 to send a message to the JESYSMSG data set for started tasks or TSO users.

Entry Specifications

The system provides a list of parameter addresses that IEFUJI can use.

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 IEFUJI

Parameter Descriptions: Register 1 points to the following list of addresses:

Word 1

Address of the common exit parameter area. For details on the parameter area, see Table 1.

Word 2

Address of a 20-byte area containing the programmer's name (in EBCDIC) from the JOB statement. This area is aligned left and padded with blanks if necessary.

Word 3

Address of a one-byte area indicating (in binary) the requested job selection priority. The value of this field equals the user-assigned priority of 0 to 14 (taken from the PRTY parameter on the JOB statement).

Word 4

Address of an area containing the accounting information from the JOB statement. (See Accounting Information.)

Word 5

Address of a 4-character area that contains the name of the subsystem for the job being processed. Examples:

ASCH, JES2, or JES3 — indicates the name of the subsystem that selected the job
OMVS — indicates a forked or spawned address space
STC — indicates a started task
TSO — indicates a time sharing option task
The jobname — used if it is four or fewer characters and none of the others apply

Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.

Figure 1. IEFUJI Input Parameter Structure

Return Specifications

A return code from IEFUJI indicates whether job processing is to continue.

If you associate multiple exit routines with IEFUJI, 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 IEFUJI, and any of those exit routines return with a value of 4, job processing will not continue.

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

Register

Contents

0-14

Not applicable

15

One of the following return codes:

Return Code: Explanation
Value of 4: Job processing is to be cancelled.
Value other than 4: Job processing is to continue.

Coded Example of the Exit Routine

A sample IEFUJI exit routine is provided in SYS1.SAMPLIB (in member SMFEXITS). This routine determines how long a job has been on the input job queue before it is initiated. It then writes this value and the job priority to the SMF data set as a user record.