Previous topic |
Next topic |
Contact z/OS |
IEFUTL — Time Limit Exit
z/OS MVS Installation Exits
Topics for This Exit Appear as Follows:
IEFUTL receives control from the system when one of the following time limits expires:
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:
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.
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:
Exit Routine Environment
IEFUTL receives control in the following environment:
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.
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:
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:
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.
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.
Parameter Descriptions: Register 1 points to the following list of addresses:
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
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.
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.
Copyright IBM Corporation 1990, 2014