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.