IEF_ALLC_OFFLN — Allocated or Offline Device Installation Exit

Topics for This Exit Appear as Follows:

“Controlling the Exit Routine”
Replacing the Exit Routine
Exit Routine Environment
Exit Recovery
Exit Routine Processing
- Bringing a Device Online
- The Offline Device Table
- Letting the Job Wait for the Device
- Using the Exit with Your Installation's Default Policy
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 must wait because a device it requested is offline or allocated to another job, MVS™ issues WTORs that instruct the system operator to take one of the following actions:

Cancel the waiting job
Bring the device online
Allow the job to wait for the device to become available.

You can automate your installation's responses to allocation requests for offline, pending offline, or allocated devices, and reduce the need for operator intervention by:

Defining an installation default policy for handling the majority of potential allocation requests for offline, pending offline, or allocated devices. Specify the default policy in the ALLOCxx member of SYS1.PARMLIB.
Coding the Allocated or Offline Device exit routine to make exceptions, if any, to the installation default policy for certain jobs and/or devices. You can specify the exit in the EXITxx or PROGxx member of SYS1.PARMLIB; however, IBM® recommends that you use PROGxx.

For a list of the allocation messages you can automate or suppress, see Message Processing.

Using the information it receives about the job and the required device(s), the exit routine can:

Cancel the job
Cause offline devices to be brought online to satisfy the job's request
Cause a pending offline device to be considered for allocation
Allow the job to wait while:
- holding resources
- not holding resources
Allow the installation's default policy to determine which action to take.
Allow the WTOR to be issued so that the system operator can decide how to handle the job. If the WTOR is to be issued, the exit routine can determine which device numbers will be displayed on the WTOR.
Note: The exit routine can only exclude device numbers from the WTOR. It cannot exclude the actual list of devices eligible for allocation.

For more information about 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 Allocated or Offline installation exit to the dynamic exits facility. You can refer to the exit by the name IEF_ALLC_OFFLN. 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 routine 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.)

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 and 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

MVS invokes the allocated or offline device exit routine or routines, if any are specified to the dynamic exits facility, every time a job must wait for a device because all devices that could satisfy the job's request are either offline, pending offline, or allocated to other jobs. This exit is only invoked for tape requests and non-SMS-managed DASD requests. It is not invoked for SMS-managed DASD requests.

MVS invokes the exit routine before issuing WTORs that:

Identify the job that is waiting
List the devices that are unavailable
Request operator action.

These messages are listed in Message Processing.

Using the Information in the Parameter List: MVS passes the address of a list of parameters to the exit routine. The parameters contain the following information:

Job name
Step name
Name of the DD statement that requires the resource
Name of the data set that requires the resource
If specific volumes are needed, the serial numbers of the volumes
The number of nonspecific scratch volumes
The number of nonspecific private volumes
A list of the eligible devices that can be brought online
Note: The list may include pending offline devices. You can use this exit to indicate whether these devices are eligible for allocation. If a pending offline device is permanently resident DASD or has a reserved volume mounted, its entry in the list contains the mounted volume serial number.
An indication of whether the job can wait
An indication of whether the job can bring devices online
An indication of whether this is a repeated call to the exit
Action to be taken in response to WTOR (this field, ACTION, is filled in by the exit routine).
The number of 'wait without holding resources' decisions that the system will allow to be made for a particular device request (in the WAITNOHC field). This number includes decisions made by both the exit routine and the installation default. This number does not restrict the number of 'wait without holding resources' decisions that can be made by the system operator.
An indication of whether the system-managed tape library is online.
An indication of whether the system-managed tape library is offline.
An indication of whether the system-managed tape library is pending offline.
For a system-managed tape library request, the name of the library.
The relative concatenation number of the DD.
An indication of the device class of the DD; one of the following:
- Tape device
- Communications device
- Direct access device
- Graphics display device
- Unit record device
- Character reader device
If the request is for an esoteric group name that includes both tape and direct access devices, both the tape and direct access indicators will be set.

Using the information in the parameter list, the exit routine determines how the system should respond to the allocation request. The exit routine indicates its decision to the system by placing a value in the ACTION field of the parameter list.

See Return Specifications for the specific values the exit routine can return.

Bringing a Device Online

The system indicates to the exit routine that the job can bring devices online by setting the OKONLINE bit to 1 (in the exit parameter list).

If the exit routine attempts to bring a device online when the OKONLINE bit is not set to 1, the system will ignore the exit routine's decision and use the installation default policy (specified in the ALLOCxx parmlib member) to determine how to respond to the allocation request. If your installation does not define a default policy for handling allocated or offline device requests, or if no ALLOCxx parmlib member is defined, the system will issue WTORs so that the system operator must respond to the job's allocation request.

The exit routine brings device(s) online by:

Setting the ACTION field to X'08'.
Selecting the device(s) from the offline device table (as described in The Offline Device Table).

Selecting an Offline Device to Bring Online: If you plan to use the exit routine to cause devices to be brought online, code the routine to check the input bits in the UXSTATUS field of the offline device table. Before selecting the device(s), check:

The UXOFFLNE bit indicates whether the device has been varied offline (for maintenance, for example). If a device has been varied offline, the system sets the UXOFFLNE bit to 1.
The UXNOTACC bit indicates whether the device is accessible to the exit routine. If the device is not accessible (not physically defined in the system), the system sets the UXNOTACC bit to 1.
The exit routine can cause only accessible devices to be brought online.
The UXPENDNG bit indicates whether the device is pending offline. If a device is pending offline it cannot be brought online by the exit. However, it can be selected for allocation consideration. See Selecting a Pending-Offline Device for Allocation Consideration.
The UXVCOFFL bit indicates whether the device was varied offline by a configuration manager (for example, ESCON® Manager). If the exit routine attempts to bring the device online, the device will be brought online.
The UXVLOFFL bit indicates whether the device is offline because it resides in an offline system-managed tape library. If the system-managed tape library is offline, the system sets the UXVLOFFL bit to 1.

The exit routine brings the device online by setting the UXONLINE bit in the UXSTATUS field to 1.

Be aware that if the chosen devices cannot be successfully brought online, Allocation will retry the allocation request anyway. If the allocation request still cannot be satisfied, the exit routine might be driven again. The parameter list does not indicate that the device was not able to be brought online previously. The exit routine should consider this when choosing devices, and should be aware that it could cause a loop if it repeatedly chooses devices that cannot be brought online.

Selecting an Eligible System-Managed Tape Library Device

The system indicates whether a request is a system-managed tape library request by setting the LBREQIND bit to one in the exit parameter list. For system-managed tape library requests, the exit or installation default policy determines whether:

The exit is to select an eligible system-managed tape library device. The exit varies the device online only when the named library is already online.
The operator is to select an eligible system-managed tape library device. To vary the device online, the operator must first ensure that the named library is online by issuing the DISPLAY SMS,LIBRARY command (described in z/OS MVS System Commands). If the library is offline or pending offline, the operator must vary the library online before varying the device online by issuing the VARY SMS,LIBRARY command (described in z/OS MVS System Commands).

An eligible device in a system-managed tape library might be offline for one of the following reasons:

The device resides in a system-managed tape library that is offline or pending offline
There are no paths to the device
A reason other than a VARY LIBRARY offline command; for example, because the operator varied the tape device offline

Selecting a Pending-Offline Device for Allocation Consideration

The exit can be used to indicate whether a specific pending-offline device will be considered for allocation. A pending-offline device will be allocated only if no other online device becomes available. The device will remain in pending offline status.

The Offline Device Table

The offline device table (pointed to in the exit parameter list) contains the device numbers of all offline or pending offline devices that match the device type that the job specified in the allocation request.

The system sets the first 4 bytes of the offline device table to the number of entries (devices) in the table. The 4-byte field is followed by one 12-byte entry for each offline device:

Bytes: Contents
1-4: contain the device number (in EBCDIC).
5: the UXSTATUS field contains information about the offline status of the device.
6: reserved.
7-12: contain the VOLSER of the pending offline permanently resident DASD or reserved device is a volume is mounted.

The format of the offline device table follows:

Letting the Job Wait for the Device

The system indicates to the exit routine (in the OKTOWAIT bit of the exit parameter list) whether the job is allowed to wait. If OKTOWAIT is set to 1, the exit routine can cause the job to wait by setting the ACTION field to indicate one of the following:

The job will wait holding any resources it may have obtained
The job will wait without holding any resources it may have obtained.

If the exit routine attempts to cause the job to wait when OKTOWAIT is set to 0, the system will ignore the exit routine's decision and use the installation default policy (specified in the ALLOCxx parmlib member) to determine how to respond to the allocation request. If your installation does not define a default policy for handling allocated or offline device requests, or if no ALLOCxx parmlib member is defined, the system will issue messages (listed in Message Processing) so that the system operator must respond to the job's allocation request.

If the exit routine allows the job to wait, the system will issue an eventual action message (IEF289E) to inform the operator that the job is waiting for a device.

Using the Exit with Your Installation's Default Policy

If you code the exit, use it in conjunction with your installation default policy for jobs that must wait for allocated or offline devices. Define your installation's default policy by specifying one of the following parameters on the POLICY keyword of the ALLC_OFFLN statement:

Parameter: Action
WTOR: Allow the messages to be issued so that the system operator must decide whether to cancel the job or let the job wait.
Note: In a sysplex environment, you will want to reduce the number of WTORs; this exit might be a candidate for that consideration.
WAITHOLD: Allow jobs to wait for devices while holding obtained resources.
WAITNOH: Allow jobs to wait for devices without holding obtained resources.
CANCEL: Cancel jobs that must wait for allocated or offline devices.

When you have chosen a default policy to handle the majority of possible requests for allocation of pending offline, offline, or already-allocated devices use the exit routine to make exceptions, if any, for certain jobs and/or devices. The exit routine's decisions will override the installation's default policy.

If you do not code the exit routine, MVS will use your installation's default policy (specified in the ALLOCxx parmlib member) to determine how to respond to all allocation requests for allocated pending offline, or offline devices. If your installation does not define a default policy, the system will always issue the WTORs.

Programming Considerations

Observe the following conventions when coding the Allocated or Offline Device Exit routine:

Code the exit routine to be reentrant.
Do not code the exit routine to issue dynamic allocation calls.
Do not code an allocated or offline device exit routine if the decision of the exit routine will always be the same regardless of which devices are needed. Instead, allow your installation's default policy to determine how to handle the allocation request.
The exit is called every time a job requires a device that is either offline, pending offline or allocated to another job. Therefore, when coding the exit routine, you should be aware that an increased path length will increase processor utilization and may degrade performance.
When the exit routine determines that the system should issue WTORs (by setting the ACTION field to X'40'), the routine can modify the list of device numbers that will be displayed, via WTOR, to the system operator. The exit routine can exclude certain device numbers from the WTOR by setting the UXEXCLUD bit of the UXSTATUS field for the device (in the offline device table) to 1.
When using system-managed tape libraries, it is possible to loop between offline recovery and the exit. In this situation, offline recovery calls the exit, which selects a tape device that is offline because it is in an offline system-managed tape library. However, offline recovery cannot bring the selected device online until the operator brings the library online. Therefore, the device is not removed from the table of offline eligible devices, and offline recovery again calls the exit. This looping will occur up to the number of times specified by the MAXNWAIT parameter of the ALLOCxx parmlib member. Then the system will use the installation-defined default action.
Before using the UXOFLPTR pointer field in the input parameters, check the field's value to see if there are offline devices eligible to be allocated. A UXOFLPTR value of zero indicates that no offline devices are eligible for this request, and only already allocated devices are eligible.
Use the exit routine, in conjunction with the installation default policy, to automate your installation's responses to WTORs such as the following:
- IEF157E
- IEF238D
- IEF244I
- IEF433D
- IEF434D
- IEF490I.
When the exit routine requests to bring one or more devices online by setting the ACTION field to X'08' the system will attempt to bring the requested device(s) online, and then retry the allocation. The system will retry the allocation regardless of whether the devices can be brought online, and this might result in the exit routine being called again for the same allocation request. If the exit routine chooses the same devices to bring online, a loop will result where Allocation repeatedly calls the exit routine to attempt to satisfy the request, and the exit routine takes an action that will be unsuccessful and so the request can never be satisfied.

Message Processing

Use the exit routine, in conjunction with the installation default policy, to suppress or automate your installation's responses to the following message:

IEF238D - Reply [device name] [,] ['wait'] or 'cancel'
Note: In a sysplex environment, determine which, if any, devices will require job-level support; for these devices, code the exit to mark the REPLY with the device number. For all other devices (the majority), determine whether this message should set UXONLINE to 1 to allow offline devices to be brought online and to allow a pending offline device to be considered for allocation.
IEF244I - Unable to allocate <nnn> units(s). At least <nnn> allocated or offline units are needed
IEF433D - Wait requested — reply hold or nohold.

In addition, you might also avoid getting one or more of the following messages, which the system issues in response to invalid replies to the preceding messages:

IEF434D - Invalid reply (to message IEF433D). Reply hold or nohold.
IEF490I - Invalid reply (to message IEF238D) for one of the following reasons:
- Device is not accessible
- Required system managed volume is not available
- Required volume is not available
- Replied device is not eligible
- Device could not be found in the configuration.
- Device found in an offline library.
IEF877E - jjobname NEEDS xxx UNIT(S) FOR stepname ddname FOR VOLUME(S): ser, ...,ser SCRTCH nn PRIVAT nn | LIBRARY: LIBNAME LIBRARY STATUS: STATUS state1 dev ...dev state2
IEF878I - END OF IEF877E FOR stepname ddname

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:

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 UXPARMD, which is mapped by macro IEFZB481 (data area UXPARMD). For a mapping of the UXPARMD 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 exit routine indicates its decision to the system by setting the ACTION field (in the UXPARMD) to one of the following values:

Value: Meaning
X'80': Cancel the job
X'40': Issue the WTOR so that the operator can determine what to do
X'20': Let the job wait without holding resources
X'10': Let the job wait while holding resources
X'08': Bring the device online or, if pending offline, allow the device to be considered for allocation
X'00': Let the installation default policy determine what to do

If the exit routine does not return a valid value in the ACTION field, the system will ignore the exit, issue a message, 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 member is named IEFOFLNE.