IEF_VOLUME_MNT — Volume Mount 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

When a job's allocation request requires a volume to be mounted, MVS™ issues a WTOR that requests the system operator to mount the volume or cancel the job. You can automate your installation's responses to volume mount WTORs, and reduce the need for operator intervention, by defining an installation default policy for volume mount allocation requests in the ALLOCxx member of SYS1.PARMLIB. The policy you specify will handle the majority of volume mount allocation requests that can occur.

Code a volume mount exit routine when you want to make exceptions to your installation default policy for certain jobs and/or volumes. Using the information it receives about the job, the exit routine determines whether to:

Cancel the job and suppress the WTOR
Allow the WTOR to be issued so that the system operator must decide whether to cancel the job or mount the volume
Allow your installation's default policy to determine whether to cancel the job or issue the WTOR.

For a list of the allocation messages you can automate or suppress, see Programming Considerations.

For more information on the ALLOCxx and EXITxx members of SYS1.PARMLIB, see z/OS MVS Initialization and Tuning Reference.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM® has defined the volume mount exit to the dynamic exits facility. You can refer to the exit by the name IEF_VOLUME_MNT. 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.

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.

Replacing the Exit Routine

For information about replacing a dynamic exit routine, see Replacing a Dynamic Exit Routine.

Exit Routine Environment

The exit receives control in the following 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.)
Can reside in (E)PLPA, (E)MLPA, or (E)FLPA.

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. However, the exit routine will continue to be invoked for all other volume mount allocation requests.

Exit Routine Processing

MVS invokes the volume mount exit routine or routines every time a job must wait for a volume to be mounted. Before issuing WTORs that identify the volume(s) to be mounted and request operator action, MVS invokes the volume mount exit routine or routines, if any are specified to the dynamic exits facility, and passes a set of parameters that contains the following information about the allocation request:

Job name
Step name
DD name of the data set that requires the volume to be mounted
Data set name
Volume serial number
Device number of the device on which the volume is to be mounted
Flags indicating the type of label on the volume, if any
Action to be taken in response to WTOR (this field is filled in by the exit routine).

Using the information in the parameter list, the exit routine indicates to the system (by placing a value in the ACTION field of the parameter list) whether the system should:

Cancel the job
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.

Using the Exit with Your Installation's Default Policy: If you code the exit, use it in conjunction with your installation's default policy for jobs that require volumes to be mounted. Determine your installation's default policy by specifying one of the following parameters on the POLICY parameter of the VOLUME_MNT statement:

Parameter: Action
CANCEL: Cancel jobs that must wait for a volume to be mounted.
WTOR: Allow the volume mount messages to be issued so that the system operator must decide whether to cancel the job or mount the volume.

When you have chosen a default policy to handle the majority of volume mount WTORs that can occur, use the volume mount 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 mount exit routine, MVS will use your installation's default policy (specified on the ALLOCxx parmlib member) to determine how to respond to all allocation volume mount requests (either cancelling all jobs that must wait for a volume to be mounted, or always allowing the WTOR to be issued). If your installation does not define a default policy, the system will always issue the volume mount WTOR.

Programming Considerations

Observe the following conventions when coding the volume mount exit routine:

Code the exit routine to be 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 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 mounted. Therefore, when coding the exit routine, you should be aware that an increased path length will increase processor utilization and may degrade performance.

Message Processing: Use the exit routine, in conjunction with the installation default policy, to suppress and automate your installation's responses to the following messages:

IEF233A - Mount volume <ser>
IEF233D - Mount volume <ser> or respond to IEF455D message
IEF455D - Mount <ser> on <device> for <jobname> or reply no.

In addition, you might avoid getting message IEF369D (invalid reply), which the system issues in response to an invalid reply to IEF455D.

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

Parameter Descriptions: Register 1 contains the address of a pointer to the exit parameter list, the UXPARMB, which is mapped by macro IEFZB479 (data area UXPARMB). For a mapping of the UXPARMB data area, see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Return Specifications

The volume mount exit indicates its decision to the system by placing one of the following values in the 1-byte ACTION field of the exit parameter list:

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'00': Let the installation default policy make the decision

If the exit routine does not return a valid value, the system will ignore the exit and use the installation default policy to make the decision.

If you associate multiple exit routines with IEF_VOLUME_MNT, 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.

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