IEF_ALLC_UNLOAD — Allocation Event 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
Entry Specifications
Return Specifications
Coded Example of the Exit Routine

The IEF_ALLC_UNLOAD exit is driven when a device is unloaded by Device Allocation outside of normal end-of-job or end-of-step device unload processing. It is invoked during processing such as VARY OFFLINE or UNLOAD commands.

This exit is called before the unload event starts and after the unload is complete. It is intended for programs that need to perform pre-processing or post-processing for an unload event. If your program only needs to be notified of an unload occurring and does not need to perform pre- or post-processing, then ENF function code 25 should be used instead.

Parameters describing the function are passed to the exit. These parameters are mapped by the IEFUNLXT mapping macro.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM® has defined the Allocation Event installation exit to the dynamic exits facility. You can refer to the exit by the name IEF_ALLC_UNLOAD. You can use 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 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.
May be invoked with any of the following ENQs held:
- SYSIEFSD.Q4
- SYSIEFSD.VARYDEV
- SYSIEFSD.CHNGDEVS

The parameter list contains information indicating which of the ENQs are obtained by another task on behalf of the unload process.

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 Unload Event exit routine or routines, if any are specified to the dynamic exits facility, whenever an unload event takes place.

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:

Eye-catcher (UNLXT)
Version ID
Length of the parameter list
One of the following functions indicating the nature of the event:
- Beginning of Unload event - 01
- End of Unload event - 02
- ABEND occurred during unload - 03
Flags indicating which of the following ENQs are held by the caller:
- SYSIEFSD.CHNGDEVS
- SYSIEFSD.VARYDEV
- SYSIEFSD.Q4
Address of the UCB of the device being unloaded. The system does not pin the UCB before calling the exit.

The exit routine can use the information in the parameter list. Because there is no action to be taken, the exit routine does not need to provide any response from the Unload Event exit.

Programming Considerations

Observe the following conventions when coding the IEF_ALLC_UNLOAD 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 you do not need to be notified of an Unload event.
The exit is called whenever an unload event begins or ends. Therefore, when coding the exit routine, you should be aware that an increased path length will increase processor utilization and may degrade performance. This includes issuing WAITs or invoking routines that may issue WAITs. Also, because of the serialization environment, other system processes may be delayed until the exit routine completes if the exit was invoked with any ENQs held.
Make sure that the exit routine does not get affected when new function code support is added.

Macro Instructions and Restrictions: Do not code the exit routine to invoke dynamic allocation.

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 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 the exit parameter list, which is mapped by macro IEFUNLXT

Return Specifications

MVS does not provide any field for a response; the exit does not return a valid value.

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

There is no coded example of this exit routine in SYS1.SAMPLIB.