Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

Use the UCBINFO macro to obtain information from a unit control block (UCB) for a specified device. The UCBINFO macro provides the following options:

DEVCOUNT: Returns a count of the UCBs for a device class or device group.
DEVINFO: Returns information about a device, particularly, why the device is offline. For the base UCB of a Parallel Access Volume (PAV), DEVINFO returns the number of alias UCBs that are defined, and the number that are usable. Also, the DEVINFO can return an indicator in the IOSDDEVI mapping macro reflecting whether the device is a Hyper Parallel Access Volume (HyperPAV) device.
HYPERPAVALIASES: Returns information for HyperPAV aliases that are configured in the same logical subsystem as the input device. The HYPERPAVALIASES function allows you to obtain selected information for each alias exposure of a Parallel Access Volume (PAV) device in HyperPAV mode. All alias exposures contained in the logical subsystem are returned in the output PAVAREA. The data returned by this function is mapped by the mapping macro IOSDPAVA and consists of a header and one or more entries.
PATHINFO: Returns information about the device path and type of channel path associated with the device.
PATHMAP: Returns information about the device path.
PRFXDATA: Obtains a copy of the UCB prefix extension segment.
PAVINFO: Returns information about the alias UCBs for a Parallel Access Volume (PAV) or a Hyper Parallel Access Volume (HyperPAV).

The options of the UCBINFO macro have the same environmental specifications, programming requirements, restrictions, register information, and performance implications described below, except where noted in the explanations of each option.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key. For LINKAGE=BRANCH, all of the following: Supervisor state with key 0 31-bit addressing mode Primary ASC mode Parameter list and any data areas it points to must be in fixed storage or, if the caller is disabled, in disabled reference (DREF) storage.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any
Control parameters:	Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

Before issuing the UCBINFO macro, you can issue the UCBSCAN macro to obtain either the UCBPTR or the device number, which you must provide as input to UCBINFO. z/OS MVS Programming: Assembler Services Guide Authorized callers must serialize (such as through pinning) the device against dynamic deletions when specifying any of the following:

DEVINFO with the UCBPTR parameter
HYPERPAVALIASES with the UCBPTR parameter
PATHINFO with the UCBPTR parameter
PATHMAP with the UCB pointer in the MAPAREA field.
PRFXDATA with the UCBPTR parameter
PAVINFO with the UCBPTR parameter

See z/OS MVS Programming: Authorized Assembler Services Guide for information about accessing and pinning UCBs.

The caller must include the appropriate mapping macro for the UCBINFO option being used:

Option: Mapping Macro
DEVCOUNT: None
DEVINFO: IOSDDEVI mapping macro
HYPERPAVALIASES: IOSDPAVA mapping macro
PATHINFO: IOSDPATH mapping macro
PATHMAP: IOSDMAP mapping macro
PAVINFO: IOSDPAVA mapping macro
PRFXDATA: IOSDUPI mapping macro

Restrictions

None.

Input register information

Before issuing the UCBINFO macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: A reason code; otherwise, used as a work register by the system
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: A return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.