IEF_VOLUME_ENQ — Volume ENQ Installation Exit
Topics for This Exit Appear as Follows:
- Controlling the Exit Routine Through the Dynamic Exits Facility
- Replacing the Exit Routine
- 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
- Defining an installation default policy for handling a majority of the volume ENQ allocation requests that are likely to occur. Specify the default policy on the VOL_ENQ statement in the ALLOCxx member of SYS1.PARMLIB.
- Coding the volume ENQ exit routine to make exceptions, if any, to the installation default policy for certain jobs and/or volumes. You can specify the exit in the EXITxx or PROGxx member of SYS1.PARMLIB; however, IBM® recommends that you use PROGxx.
- Cancel the job and suppress the WTOR
- Allow the job to wait
- Allow the WTOR to be issued so that the system operator must decide whether to cancel the job or let the job wait
- Allow the installation default policy to determine whether to cancel the job or issue the WTOR.
For more information on the ALLOCxx, EXITxx, and PROGxx parmlib members, see z/OS MVS Initialization and Tuning Reference.
Controlling the Exit Routine Through the Dynamic Exits Facility
IBM has defined the volume ENQ installation exit to the dynamic exits facility. 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.
- 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.
Replacing the Exit Routine
For information about replacing a dynamic exit routine, see Replacing a Dynamic Exit Routine.
Exit Routine Environment
- Enabled for interrupts.
- In supervisor state with PSW key 1.
- In AMODE 31 and RMODE ANY.
- With no locks held. (However, it may hold an exclusive ENQ on major name SYSZTIOT for the address space in which the allocation occurs.)
Exit Recovery
The exit routine should provide its own recovery. If the exit routine abnormally terminates, its recovery routine will get control.
If the exit routine abnormally terminates, and the exit routine does not provide its own recovery, or the error percolates beyond the exit's recovery routine, a system recovery routine will get control. The system will fail the allocation request.
Whether or not the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.
Exit Routine Processing
- Job name
- Step name
- A table containing the serial numbers of the volumes that the job requires
- Action to be taken in response to WTOR (this field, ACTION, is filled in by the exit routine).
- Cancel the job and suppress the WTORs
- Allow the job to wait for the volume(s)
- Allow the WTORs to be issued so that the system operator must make the decision
- Allow the installation's default policy to make the decision.
See Return Specifications for the specific values the exit routine can return.
- Parameter
- Action
- CANCEL
- Cancel jobs that must wait for a volume to be released
- WTOR
- Allow the volume ENQ messages to be issued so that the system operator must decide whether to cancel the job or let the job wait.
- WAIT
- Allow jobs to wait for volumes to be released.
When you have chosen a default policy to handle the majority of volume ENQ WTORs that can occur, use the volume ENQ exit routine to make exceptions, if any, for certain jobs and/or volumes. The exit routine's decisions will override the installation's default policy.
If you do not code the volume ENQ exit routine, MVS will use your installation's default policy (specified in the ALLOCxx member) to determine how to respond to all volume ENQ allocation requests. If your installation does not define a default policy, the system will always issue the volume ENQ WTORs.
Programming Considerations
- Code the exit routine so that it is reentrant.
- Do not code the exit routine to issue dynamic allocation calls.
- Do not code the exit routine if its decision will always be the same regardless of which jobs are waiting or which volumes are needed. Instead, allow your installation's default policy to make the decision.
- The exit is called every time a job requires a volume to be released. Therefore, when coding the exit routine, you should be aware that an increased path length will increase processor utilization and may degrade performance.
- IEF690I - The following volumes are unavailable to <jobname>...
- IEF235D - <jobname> is waiting for volumes. To cancel wait, reply no.
Macro Instructions and Restrictions: Do not code the exit routine to issue the WAIT macro or call a service that issues a WAIT, such as WTOR.
Entry Specifications
The system passes the address of the exit parameter list to the exit routine.
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 the exit parameter list
- 2-12
- Not applicable
- 13
- Register save area
- 14
- Return address
- 15
- Entry point address of the exit routine
Parameter Descriptions: Register 1 contains the address of a pointer to the exit parameter list, the UXPARMA, which is mapped by macro IEFZB478 (data area UXPARMA). For a mapping of the UXPARMA data area, see z/OS MVS Data Areas in the z/OS Internet library.
Return Specifications
- Value
- Explanation
- X'80'
- Cancel the job and suppress the WTOR
- X'40'
- Issue the WTOR so that the system operator can make the decision
- X'08'
- Let the job wait for the volume(s)
- X'00'
- Let the installation default policy make the decision
If the exit routine does not return a valid value in the ACTION field, the system will ignore the exit and use the installation default policy to make the decision.
Registers at Exit: Upon return from the exit processing, the register contents must be as follows.
- Register
- Contents
- 0-14
- Restored to contents at entry
- 15
- 0
Coded Example of the Exit Routine
For your reference, IBM provides a coded example of this exit routine in SYS1.SAMPLIB. The routine is named IEFVENQS.