IEF_ALLC_OFFLN — Allocated or Offline Device Installation Exit

Topics for This Exit Appear as Follows:

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 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 that 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 are 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 defines 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 disabled. 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 might 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 ends, its recovery routine gets control.

If the exit routine abnormally ends, and the exit routine does not provide its own recovery, or the error percolates beyond the exit's recovery routine, a system recovery routine gets control and fail the allocation request.

Whether the exit routine continues to be started depends on the abend processing of the dynamic exits facility.

Exit Routine Processing

MVS starts 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. This is because all devices that can satisfy the job's request are either offline, pending offline, or allocated to other jobs. This exit is only started for tape requests and non-SMS-managed DASD requests. It is not started for SMS-managed DASD requests.

MVS starts the exit routine before it issues 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 might 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 it is a repeated call to the exit
  • Action to be taken in response to WTOR (this field, ACTION, is completed by the exit routine).
  • The number of 'wait without holding resources' decisions that the system allows to be made for a particular device request (in the WAITNOHC field). This number includes decisions that are 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 are 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 ignores 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 issues WTORs. That way, 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 is brought online.
  • The UXVLOFFL bit indicates whether the device is offline because it exists 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 retries 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 it chooses devices, and should be aware that it can 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 it varies 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 exists 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 an eligible tape library device based on device priority

The device priority value (UXDEVPRI) is available at z/OS 2.3 and above. It is also available for prior releases when the fix for APAR OA49373 is installed. UXDEVPRI is used in a system-managed tape environment to reflect device preference information:
  • The priority value is a number from 0-255, where 255 is the best or preferred value, and 0 is the worst value.
  • The priority value isn't unique, which means that multiple devices might have the same value.
  • Not all of the priority values are necessarily used. So for a given request, the best device the exit sees might have a priority value of 250 (instead of 255), or the best device might be 255 and the next best device might be 245, for example.
  • Some allocation requests might not be prioritized - for those requests, the priority value is 0.

Bit flag UXPRVALD indicates whether the devices in the offline device list have been assigned priority values.

Priority values are returned in the following cases:
  • The Device Allocation Assist (DAA) function is being used in the TS7700 Virtualization Engine to prioritize which clusters (or distributed libraries) are preferred on a specific mount request.
  • When multiple libraries are eligible for a scratch request, some libraries might be above or below scratch threshold. Devices in libraries above scratch threshold receive a priority value of 255 and devices in libraries below scratch threshold receive a priority value of 254.

Selecting a Pending-Offline Device for Allocation Consideration

The exit can be used to indicate whether a specific pending-offline device is considered for allocation. A pending-offline device is allocated only if no other online device becomes available. The device remains 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 waits holding any resources that it might have obtained
  • The job waits without holding any resources that it might have obtained.

If the exit routine attempts to cause the job to wait when OKTOWAIT is set to 0, the system ignores 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 issues 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 issues 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 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 want to reduce the number of WTORs; this exit might be a candidate for that consideration.
WAITHOLD
Allow jobs to wait for devices while it holds 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 most 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 devices. The exit routine's decisions override the installation's default policy.

If you do not code the exit routine, MVS uses 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 always issues the WTORs.

Programming Considerations

Observe the following conventions when you code 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 is always 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 that a job requires a device that is either offline, pending offline or allocated to another job. Therefore, when you code the exit routine, you should be aware that an increased path length increases processor usage and might 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 are 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 you use 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 occurs up to the number of times specified by the MAXNWAIT parameter of the ALLOCxx parmlib member. Then, the system uses the installation-defined default action.
  • Before you use the UXOFLPTR pointer field in the input parameters, check the field's value to see whether 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, with the installation default policy, to automate your installation's responses to the following WTORs:
    • 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 attempts to bring the requested device(s) online, and then retry the allocation. The system retries the allocation regardless of whether the devices can be brought online, and it might result in calling the exit routine again for the same allocation request. If the exit routine chooses the same devices to bring online, a loop results where Allocation repeatedly calls the exit routine to attempt to satisfy the request, and the exit routine takes an action that is unsuccessful and so the request can never be satisfied.

Message Processing

Use the exit routine, 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 require job-level support; for these devices, code the exit to mark the REPLY with the device number. For all other devices (most), 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> unit(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 might 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 the z/OS Internet library.

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