Pinning and unpinning UCBs

You can pin a UCB in either of the following ways:

When issuing the UCBLOOK and UCBSCAN macros, specify the PIN parameter on these macros.
Specifying the PIN parameter when obtaining UCB information with UCBLOOK and UCBSCAN ensures that the UCB cannot be deleted through a dynamic configuration change.
Issue the UCBPIN macro, specifying the PIN parameter.
Specifying the PIN parameter with UCBPIN ensures that the UCB whose address is supplied as input cannot be deleted through dynamic configuration changes. For example, assume that your program has allocated a device and must save the UCB address for later use after the device is unallocated. You could issue UCBPIN with the PIN parameter, providing the address of the UCB for the device as input. Pinning the UCB ensures that the UCB (and therefore the device itself) cannot be deleted once the device is unallocated.

You can unpin UCBs by issuing the UCBPIN macro with the UNPIN option; you must provide the pin token that the system returned when the UCB was pinned.

Programs that pin UCBs must provide information documenting the reason for the pin request. If a configuration change involving a pinned UCB is attempted, this information is displayed as part of a message that explains why the configuration change was rejected. Use the TEXT parameter to provide the text for the message. Potential text might record what is using the device, for example:

THE XYZ SERVICE IS USING THE ABC DEVICE.

The system will reject any requested I/O configuration changes involving a device whose UCB is pinned. Therefore, you might want a program to receive notification of configuration change requests that involve a device whose UCB has been pinned by the program. The program could then unpin the UCB, allowing the configuration change to occur. See Requesting notification of I/O configuration changes for further information.

Each program that needs to obtain UCB information must ensure that the UCB will not be deleted. Thus, any UCB might be pinned by several different programs at one time. Each program must subsequently unpin the UCB before the device can be deleted. For example, if a UCB has been pinned by three different programs and is later unpinned by two of those programs, the UCB is still pinned because of the one outstanding pin request.

If a program fails to unpin a UCB that it had previously pinned, the system will automatically free the pin at the time of termination of the task or address space with which the pin is associated, unless the LASTING parameter was specified when the UCB was pinned. The following list identifies four environments in which the system will automatically free an outstanding pin:

A program that is in task mode and not in cross memory mode has pinned a UCB. The pin request is associated with the current job step task. If the pin is still in force when the job step task terminates, the system automatically frees the pin.
A program that is in SRB mode and not in cross memory mode has pinned a UCB. The pin request is associated with the currently-executing address space. If the pin is still in force when the address space terminates, the system automatically frees the pin.
A program that is in task mode and cross memory mode has pinned a UCB. The pin request is associated with the current job step task of the current home address space. If the pin is still in force when the job step task terminates, the system automatically frees the pin.
A program that is in SRB mode and cross memory mode has pinned a UCB. The pin request is associated with the home address space. If the pin is still in force when the address space terminates, the system automatically frees the pin.

If LASTING is specified on the pin request, the system will not automatically free the pin.