IEFUTL — Time Limit Exit

Topics for This Exit Appear as Follows:

IEFUTL receives control from the system when one of the following time limits expires:
  • Job processor time limit (from the JOB statement)
  • Step processor time limit (from the EXEC statement or the default from the job entry subsystem)
  • Continuous wait time limit for the job (from the SMFPRMxx JWT parameter). "Continuous wait time" is defined as time spent waiting while the application program is in control. For example, the time required to recall a data set from HSM Migration Levels 1 or 2 and/or the time required to mount a tape is counted towards the job's continuous wait time if the allocation of the data set is dynamic (that is, issued while the application program is running) while the time required for those activities is not counted toward the job's continuous wait time if the allocation is static (that is, for a DD statement). This is because static allocations occur under the initiator rather than under the application program.

If one of the above time limits is exceeded and your installation does not supply an IEFUTL exit routine, the system cancels the job. A return code from this exit indicates whether the job step is to be terminated or processing should continue with a new time limit.

You can use IEFUTL to:
  • Allow the job step to abend.
  • Inform the operator that a job has exceeded its continuous-wait-time limits.
  • Extend processor time limits for selected jobs.
  • Extend the wait time limit within a job.
  • Keep a record of time limit expirations.
  • Vary the handling of time limit expirations for different types of jobs, such as teleprocessing, test, or production jobs.

Defining the Exit in SMFPRMxx

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

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 does not disable the exit routine.

Exit Routine Environment

IEFUTL receives control in the following environment:

Exit Recovery

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

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

Because the purpose of IEFUTL is to decide whether a step that has exceeded its allotted processor time or wait time should be abnormally terminated (the system default) or allowed to continue, be aware that the job WILL abend with the S322 or S522 it would have received if the exit routine had never gotten control.

Exit Routine Processing

Processor time is collected in two categories: execution under TCBs and execution under SRBs. The limiting function of IEFUTL applies only to such time under TCBs.

IEFUTL receives control when a time limit has expired. While IEFUTL is running, the application program continues to execute. (Note that this represents a change from MVS/XA and MVS/ESA up through release 4, wherein the system would suspend execution of an application program while IEFUTL was running.) This means, for example, that if IEFUTL issues a WTOR asking the operator whether to allow a job to continue executing or to cancel it, the job will, in fact, continue to execute while IEFUTL is waiting for the answer to the WTOR.

Depending on whether the expired time limit is a job, step, or continuous wait time limit, you can use the information in the SMF common exit parameter area to determine if processing should continue. The value of the time limit extension is either in seconds or in timer units, where 1 second = 38400 timer units. The smallest time extension granted is 220 microseconds or 1.048576 seconds.

The time limit for the execution of a job step is specified by the job entry subsystem or by parameters on job control statements.
  • If a job time limit is not specified on the JOB statement, the time limit for each job step is the value specified for the TIME=parameter on the EXEC statement, or the default value from the job entry subsystem.
  • If a job time limit is specified on the JOB statement, the time limit for each job step is the remaining job time or the job step time limit (from the TIME=parameter or the job entry subsystem default), whichever is smaller.

You can extend execution time and wait time only within a step. Each extension resets the limit for the entire step to the extension value you specify.

The step execution and the wait time limits are re-initialized to the system default values at the beginning of each job step. Thus, unused extended execution time from one job step is not carried over for the next step.

An installation-written IEFUTL exit routine should control the number of extensions for a given step to prevent looping. It can record the expiration in the SMF data set or write a message to the console; however, in doing so, a system interlock could occur. (See Programming Considerations.)

z/OS® UNIX MVS™ Address Space Processing: The following applies to address spaces that are z/OS UNIX MVS processes:

  • If the time expiration is for a job or step time limit and IEFUTL exit processing indicates that the job step should be terminated, the system takes the following action:
    1. The system sends a SIGXCPU signal to the z/OS UNIX MVS process, and grants a small time extension to allow for SIGXCPU processing to occur. Applications can catch SIGXCPU signals and perform an orderly cleanup of the job or reset the CPU limit to a larger value.
      Note: Processes can use the z/OS UNIX MVS setrlimit callable service to control CPU resource consumption. For information about z/OS UNIX MVS signals and the setrlimit callable service, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.
    2. If the time extension for SIGXCPU processing expires, the system sends a SIGKILL signal to the z/OS UNIX MVS process and grants a small time extension to allow SIGKILL processing to occur. Applications cannot catch or ignore SIGKILL signals. SIGKILL signals provide for a more orderly shutdown of the application than an abend of the job step.
    3. If the time extension for SIGKILL processing expires, the system abends the job step.
  • If the time expiration is for a job or step time limit and IEFUTL exit processing indicates that a time extension should be granted, the system grants the time extension.
  • If the time expiration is for a continuous wait time limit and IEFUTL exit processing indicates that the job step should be terminated, the system abends the job step.
  • If the time expiration is for a continuous wait time limit and IEFUTL exit processing indicates that a time extension should be granted, the system grants the time extension.

Programming Considerations

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

IEFUTL can perform dynamic allocations and write to installation-defined data sets. In foreground jobs, data sets are allocated dynamically. 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.

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. To provide a consistent environment for accessing and allocating data sets across calls to SMF exits for the duration of a job or task, IEFUTL receives control with the initiator's JSCB active.

If IEFUTL enqueues on any resource that the job task or any of its subtasks is enqueued on, the initiator ends abnormally. IEFUTL can, however, determine if a particular resource is held before issuing an ENQ (or invoking an SVC that issues an ENQ) by issuing an ENQ macro with RET=TEST. The macro must also specify the major and minor resource names in the QNAME and RNAME parameters. For example: 
ENQ(QNAME,RNAME,E,3,SYSTEM),RET=TEST

Because SMF exits must be reentrant, be sure to use the execute form of the macro.

For more information on the ENQ macro, see z/OS MVS Programming: Assembler Services Guide and z/OS MVS Programming: Assembler Services Reference ABE-HSP.

Entry Specifications

IEFUTL is passed the address of the SMF common exit parameter area and the type of time limit that expired to determine whether processing should continue.

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

Register
Contents
0
A binary code to indicate why the exit is taking control:
Binary Code
Explanation
0
The processor time limit for the job expired
4
The processor time limit for the step expired
8
The continuous wait time limit for the job expired
1
Address of the parameter list
2-12
Not applicable
13
Register save area
14
Return address
15
Entry point address of IEFUTL
Parameter Descriptions: Register 1 points to the following list of addresses:
Word 1
The address of the common exit parameter area (see Common Exit Parameter Area).
Word 2
The 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 othersapply
Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.
Figure 1. IEFUTL Input Parameter Structure
ieae4009

Return Specifications

If IEFUTL returns a code that indicates that processing should continue, then the time extension to be applied is returned in register 1.

If you associate multiple exit routines with IEFUTL, 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 IEFUTL, and any of those exit routines return with a value other than 4 or 8, job processing is cancelled.

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

Register
Contents
0
Not applicable
1
Contains one of the following time extensions:
  • If R15=4, R1 contains a time extension in timer units.
  • If R15=8, R1 contains a time extension in seconds.
2-14
Not applicable
15
One of the following return codes:
Return Code
Explanation
4
Job processing should be continued with a time extension in timer units.
8
Job processing should be continued with a time extension in seconds.
Other value
Job processing should be cancelled.

Coded Example of the Exit Routine

Sample IEFUTL exit routines are provided in SYS1.SAMPLIB in members SMFEXITS and IEEUTL. This routine terminates a job if either the job processor time limit or the job step processor time limit has been exceeded. If the continuous wait time limit for the job has been exceeded, the routine extends the limit twice; on the third entry for exceeding the continuous wait time limit, the routine cancels the job.

The continuous wait time limit is not an accumulation of all the time the task spends waiting, but rather a single continuous wait period that exceeds the specified limit.

Each time the routine is invoked for exceeding the continuous wait time limit, the routine writes a record to the SMF data set describing the action taken.

The IEEUTL exit routine is the SMF time limit exit. Since TSO sessions are handled like batch jobs, the SMF job wait limit and CPU time limits are enforced. This routine checks to see if the address space is a TSO session, and, if the CPU time is exceeded, issues a warning message to the terminal and grants a one-minute extension before the session is cancelled.