Description

Description

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

Use the UCBSCAN macro to scan unit control blocks (UCBs) and return a copy of a UCB or a UCB address on each invocation.

Two types of scans are available with UCBSCAN: A scan of all UCBs, and a scan of all UCBs within a particular device class. For each type of scan, the caller may optionally:

Restrict the scan to UCBs defined as static or installation-static.
Restrict the scan to UCBs with 3-digit device numbers.
Restrict the scan to addresses of below 16 megabyte UCBs
Request alias UCBs for a parallel access volume.
Specify the device number with which the scan should begin.

UCBSCAN presents the UCBs in ascending device number order. UCBSCAN provides two options as follows:

COPY

On each invocation, UCBSCAN returns a copy of requested UCB segments and data in caller-supplied areas.

Address

On each invocation, UCBSCAN returns the address of the UCB, the address of requested UCB segments, and, optionally, a copy of the UCB prefix extension segment. The caller can specify whether the scan includes above 16 megabyte UCBs or only below 16 megabyte UCBs. The caller must pin and unpin the UCB unless one of the following is true:

The caller is running in an environment where dynamic configuration changes cannot occur
The caller can otherwise guarantee that the UCB will not be deleted.

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

LINKAGE=BRANCH is intended for performance-sensitive programs.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	For the COPY parameter: Problem state with any PSW key For the ADDRESS parameter: Supervisor state or PKM allowing key 0-7 For the LINKAGE=BRANCH parameter, 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:	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

If in AR mode, issue SYSSTATE ASCENV=AR before issuing UCBSCAN.

Restrictions

None.

Input register information

Before issuing the UCBSCAN 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 general purpose registers (GPRs) contain:

Register: Contents
0: Reason code if GPR 15 contains a return code of 04 or 08; 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: Return code

When control returns to the caller, the access registers (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.

Parameters

The parameters are explained as follows:

COPY

Specifies that a copy of the UCB is to be obtained. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy.

Note: When you issue UCBSCAN to obtain a UCB copy, the UCBID field in the copy is set to x‘CC’.

,WORKAREA=workarea addr

Specifies the address of a 100-character work area used by the UCBSCAN service. The caller must initialize this work area to binary zeros before starting a UCB scan. On subsequent invocations of UCBSCAN within the same scan, the caller must leave the contents of this work area unchanged.

,UCBAREA=ucbarea addr

Specifies the address of a 48-character storage area that will receive a copy of the UCB common segment and the UCB device-dependent segment. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy.

The caller does not need to initialize this area. Use the IEFUCBOB mapping macro to map the area. The contents of certain fields in the copy are:

The UCBEXTP field contains either:
- The address of the CMXTAREA, if CMXTAREA is below 16 MB
- 0, if CMXTAREA is above 16 MB or if the CMXTAREA parameter is not specified
The UCBNXUCB field is 0, because this field is not valid in the UCB copy.
Address fields in the copy might not contain valid addresses, so do not use these addresses to reference the data areas they point to.

,CMXTAREA=cmxtarea addr

,CMXTAREA=NONE

Specifies the address of a 32-character storage area that will receive a copy of the UCB common extension segment. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy and require this segment as part of a UCB copy.

Use the UCBCMEXT DSECT in the IEFUCBOB mapping macro to map the area. If the CMXTAREA area is below 16 MB, the UCBEXTP field in the UCBAREA area contains the address of the CMXTAREA area, If the CMXTAREA area is above 16 MB, the caller must explicitly supply the address of the CMXTAREA area because the UCBEXTP field will contain 0.

The UCBIEXT field contains 0 because this field is not valid in the UCB copy.

The UCBCLEXT field contains the address of the DCEAREA if the UCB has a device class extension and the caller specified the DCEAREA parameter. Otherwise, the field contains 0.

,UCBPAREA=ucbparea addr

,UCBPAREA=NONE

Specifies the address of a 48-character storage area that will receive a copy of the UCB prefix extension segment. This keyword is required if SUBCHANNELSET=ALL is specified. The area can be mapped by the IOSDUPI mapping macro.

,DCEAREA=dcearea addr

,DCEAREA=NONE

Specifies the address of a storage area that will receive a copy of the UCB device class extension segment. See z/OS HCD Planning for a list of the MVS services that accept a UCB copy and require this segment as part of a UCB copy.

Note: If DCEAREA=NONE is coded, then DCELEN=0 must be coded. If DCEAREA=NONE is defaulted, then DCELEN does not have to be coded.

,DCELEN=length addr

Specifies the address of a 2-byte field that contains the length of the area specified by DCEAREA. The length specified must be 1 through 256 bytes. DCELEN is required with DCEAREA.

,VOLSER=volser addr

,VOLSER=NONE

Specifies the address of a 6-character field that indicates, in EBCDIC, the volume serial number of the device for which a UCB copy is to be obtained.

,DEVNCHAR=devnchar addr

Specifies the address of a 4-character field that is to receive the EBCDIC device number associated with the UCB copy.

,DEVN=devn addr

,DEVN=0

Specifies (DEVN=devn addr) an input halfword that contains, in binary form, the device number with which the scan is to begin. The default, DEVN=0, starts the scan with the first UCB.

,SUBCHANNELSET=ID

,SUBCHANNELSET=ALL

,SUBCHANNELSET=ID: Indicates the UCB scan is based on one subchannel set. DEFAULT: ID
,SCHSET=xschset
SCHSET=0: Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the UCB scan is to be performed. DEFAULT: 0.
,SUBCHANNELSET=ALL: Indicates the UCB scan is based on all subchannel sets. DEFAULT: ID

,LDEVNCHAR=xldevnchar

Indicates the name (RS-type), or address in register (2)-(12), of an optional 5 character output which is to contain the EBCDIC logical device number associated with the UCB copy.

Note: A logical device number is represented by the 1-digit subchannel set id followed by a 4-digit device number, sdddd.

,DYNAMIC=NO

,DYNAMIC=YES

Specifies whether the scan should be restricted to static and installation-static UCBs (DYNAMIC=NO) or should also include dynamic UCBs (DYNAMIC=YES).

,RANGE=3DIGIT

,RANGE=ALL

Specifies whether the scan should be restricted to UCBs with 3-digit device numbers (3DIGIT) or should also include UCBs with 4-digit device numbers (ALL).

,UNBOUND_ALIAS=NO

,UNBOUND_ALIAS=YES

,UNBOUND_ALIAS=ONLY

Specifies whether the scan should include unbound alias UCBs.

YES: Include unbound alias UCBs
NO: Do not include unbound alias UCBs
ONLY: Include only unbound alias UCBs

Note: The UNBOUND_ALIAS function is intended for IOS use only.

SPECIAL=NO

SPECIAL=YES

SPECIAL=ONLY

Specifies whether the UCB is findable (SPECIAL=YES) or not (SPECIAL=NO). SPECIAL=ONLY should be used to scan for only special devices. Special devices are those UCBs that represent devices that are not PAV-alias devices in the alternate subchannel set. The 3390S and 3390D device types are special devices.

,DEVCLASS=ALL

,DEVCLASS=CHAR

,DEVCLASS=COMM

,DEVCLASS=CTC

,DEVCLASS=DASD

,DEVCLASS=DISP

,DEVCLASS=TAPE

,DEVCLASS=UREC

Specifies the device class that is to be scanned:

ALL: Scans UCBs for all device classes
CHAR: Scans UCBs for character reader device class
COMM: Scans UCBs for communications device class
CTC: Scans UCBs for channel to channel device class
DASD: Scans UCBs for direct access device class
DISP: Scans UCBs for display device class
TAPE: Scans UCBs for tape device class
UREC: Scans UCBs for unit record device class

,DEVCID=devcid addr

Specifies the address of an 8-bit input field that contains the device class ID of the device class to be scanned. The value in this byte represents the third byte in the UCBTYP field of each device in the class.

If you specify DEVCID, only UCBs of the particular device class specified will be presented, and the DEVCLASS parameter is ignored.

,IOCTOKEN=ioctoken addr

,IOCTOKEN=NONE

Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro, which is described in z/OS MVS Programming: Assembler Services Reference ABE-HSP. If the I/O configuration token that is current when UCBSCAN is invoked does not match the token whose address is supplied as input by ioctoken addr, the caller will be notified through a return code.

If the input IOCTOKEN (specified by ioctoken addr) is set to binary zeros, UCBSCAN will set IOCTOKEN to the current I/O configuration token at the start of the scan.

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

Specifies the type of call that should be generated:

SYSTEM: Specifies a Program Call (PC)
BRANCH: Specifies a Branch entry

LINKAGE=BRANCH is intended for performance-sensitive programs.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=plistver

Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
1, if you use the currently available parameters.

To code, specify in this input parameter one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1

,RETCODE=retcode addr

Specifies the fullword location where the system is to store the return code. The return code is also in GPR 15.

,RSNCODE=rsncode addr

Specifies the fullword location where the system is to store the reason code. The reason code is also in GPR 0.

Return and reason codes

When control returns from USBSCAN, GPR 15 (and retcode addr, if you coded RETCODE) contains a return code and, for some return codes, GPR 0 (or rsncode addr, if you coded RSNCODE) contains a reason code.

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	None	Meaning: UCBSCAN completed successfully. Action: None.
04	01	Meaning: UCBSCAN processing ended. All UCBs that met the search criteria have been presented to the caller. The contents of UCBAREA are unchanged, and WORKAREA has been reset to binary zeros. Action: None.
08	01	Meaning: Program error. A caller in AR mode specified an ALET that was not valid. Action: Correct the ALET and reissue the macro. Possibly the caller wrote over an area in the parameter list; look for this error.
08	02	Meaning: Program error. An error occurred when the system tried to access the caller's parameter list. Action: Ensure that you have met the environmental requirements for the macro, and reissue the macro.
08	03	Meaning: Program error. An error occurred in referencing the caller-supplied area for the UCB copy; the area was specified in the UCBAREA parameter. Action: Correct the UCBAREA parameter.
08	04	Meaning: Program error. An error occurred in referencing the caller-supplied area for the UCB prefix extension segment data. This reason code is valid only for callers using the UCBPAREA parameter. Action: Correct the UCBPAREA parameter.
08	05	Meaning: Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the IOCTOKEN parameter. Action: Correct the IOCTOKEN parameter.
08	08	Meaning: Program error. An error occurred in referencing the caller-supplied work area specified in the WORKAREA parameter. Action: Correct the WORKAREA parameter.
08	09	Meaning: Program error. An error occurred in referencing the caller-supplied CMXTAREA area. This reason code is valid only for callers using the CMXTAREA parameter. Action: Correct the CMXTAREA parameter.
08	0B	Meaning: Program error. An error occurred in referencing the caller-supplied DCEAREA area. This reason code is valid only for callers using the DCEAREA parameter. Action: Correct the DCEAREA parameter.
08	0C	Meaning: Program error. The caller specified a volume serial number that is not valid. (Note that binary zeros are not considered valid.) This reason code is valid only for callers using the VOLSER parameter. Action: Correct the VOLSER parameter.
08	0D	Meaning: Program error. For the DCEAREA token, the caller specified a length that is negative, is zero, or exceeds 256 bytes. This reason code is valid only for callers using the DCELEN parameter. Action: Correct the DCELEN parameter.
08	0E	Meaning: The value specified on the SCHSET keyword is not valid. Action: Correct the SCHSET value.
0C	None	Meaning: Environmental error. The I/O configuration has changed, so that the I/O configuration token supplied through the IOCTOKEN parameter is not current. This return code is valid only for callers using the IOCTOKEN parameter. Action: Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the UCBINFO macro to zero. Start the scan from the beginning.
20	None	Meaning: System error. An unexpected error occurred. Action: Supply the return code to the appropriate IBM support personnel.