Scanning UCBs

Use the UCBSCAN macro to scan UCBs, returning UCB information on each invocation. The scan can include all UCBs in the system, or be restricted to a specific device class. For example, you can use UCBSCAN to find all DASD devices currently defined in the I/O configuration.

There are two kinds of information that UCBSCAN can return on each invocation. If you specify the COPY keyword, UCBSCAN returns a copy of a UCB in a user-supplied work area. If you specify the ADDRESS keyword, UCBSCAN returns a UCB common segment address. With the ADDRESS keyword, you can also request a UCB common extension or prefix extension address. Unauthorized programs must specify the COPY keyword when invoking the UCBSCAN macro.

When you use UCBSCAN to obtain UCB addresses for devices, it is necessary to ensure that these devices will not be dynamically deleted while the scan is taking place. The PIN parameter on the UCBSCAN macro allows the caller to pin each UCB whose address is to be obtained. As with UCBLOOK, specifying the PIN parameter ensures that the returned address for the UCB is valid as of the moment the UCB is pinned, and that the address remains valid as long as the pin is in effect. As in any other case where a program pins a UCB, the program is responsible for unpinning the UCB once the UCB is no longer subject to processing.

IBM® recommends the use of the UCBSCAN macro for UCB scans. The limited method UCB scan service (described under Obtaining UCB information (limited method)) is restricted to below 16 megabyte UCBs for static and installation-static devices with 3-digit device numbers. However, the UCBSCAN macro can perform the same functions as the UCB scan service, and also provides these additional advantages:

You can use UCBSCAN for dynamic devices, as well as for static and installation-static devices. It is also possible to limit the scan to static and installation-static devices, or to also include dynamic devices.
You can use UCBSCAN for devices with 4-digit numbers as well as for devices with 3-digit numbers.
You can use UCBSCAN COPY for copies of below and above 16 megabyte UCBs.
You can use UCBSCAN ADDRESS for addresses of below and above 16 megabyte UCBs.
You can use UCBSCAN ADDRESS to obtain the address of the UCB common extension and UCB prefix extension.
UCBSCAN supports AR-mode callers.
UCBSCAN allows you to start the scan at a specific device number.
UCBSCAN returns UCBs in ascending order by device number.