The requirements for the caller are:

If in AR mode, specify SYSSTATE ASCENV=AR before invoking the macro.

None.

Before issuing the UCBLOOK 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.

None.

The standard form of the UCBLOOK macro is written as follows:

The parameters are explained as follows:

DEVN=devn addr

DEVNCHAR=devnchar addr

VOLSER=volser addr

LDEVNCHAR=xldevnchar

Specifies the address of an input field that identifies the device whose UCB address is to be obtained.

DEVN specifies the address of a halfword that contains, in binary form, the device number of the device whose UCB address is to be obtained.

DEVNCHAR specifies the address of a 4-character field that contains, in EBCDIC, the device number of the device whose UCB address is to be obtained.

VOLSER specifies the address of a 6-character field that contains, in EBCDIC, the volume serial number of the device whose UCB address is to be obtained.

LDEVNCHAR specifies the name (RS-type), or address in register (2)-(12), of a 5 character input that specifies the logical device number, in EBCDIC, of the device whose UCB address is to be obtained.

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

,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 the device whose UCB address is to be obtained. DEFAULT: 0.

,UCBPTR=ucbptr addr

Specifies the address of a fullword field in which the address of the UCB common segment associated with the requested device (DEVN, DEVNCHAR, or VOLSER) will be returned.

Use the UCBOB structure in the IEFUCBOB mapping macro to map the UCB common segment.

,UCBCXPTR=ucbcxptr addr

Specifies the address of a fullword field in which the system returns the address of the UCB common extension segment associated with the specified device (DEVN, DEVNCHAR, LDEVNCHAR, or VOLSER). Use the IEFUCBOB mapping macro to map the UCB common extension segment.

,UCBPXPTR=ucbpxptr addr

Specifies the address of a fullword field in which the system returns the address of the UCB prefix extension segment associated with the specified device (DEVN, DEVNCHAR, LDEVNCHAR, or VOLSER). Use the IOSDUPFX mapping macro to map the UCB prefix extension segment.

,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. The copy of the UCB prefix extension segment is mapped by the IOSDUPI mapping macro.

,LOC=BELOW

,LOC=ANY

Specifies whether the search should be restricted to below 16 megabyte UCB (LOC=BELOW) or should also include above 16 megabyte UCBs (LOC=ANY).

SPECIAL=NO

SPECIAL=YES

Specifies whether the UCB is findable (SPECIAL=YES) or not (SPECIAL=NO). 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.

,PIN

,NOPIN

Specifies whether the UCB is to be pinned to make it ineligible for deletion through dynamic I/O configuration changes. Pinning the UCB ensures that it cannot be deleted while the look-up process is taking place. The PIN parameter specifies that the UCB should be pinned, and NOPIN specifies that it should not. Programs that pin a UCB are also responsible for unpinning it once the UCB is no longer subject to processing. Use the UCBPIN macro with the UNPIN option to unpin the UCB.

,TEXT=text addr

Specifies the address of a 58-character input field containing text that documents the reason for the PIN request. If the pin request remains outstanding during a request for a configuration change that would delete this UCB, the text specified by the TEXT parameter will be displayed in a message identifying the reason for a configuration change failure.

,PTOKEN=ptoken addr

Specifies the address of an 8-character area that is to receive the pin token for the UCB. The caller must use the pin token when unpinning the UCB through the UCBPIN service.

,LASTING

Specifies that the UCB will not be unpinned automatically by the system at the time of termination of the task or address space with which the pin is associated.

When you code LASTING, the system cannot dynamically delete the UCB until your program issues UCBPIN with the UNPIN parameter.

,UNBOUND_ALIAS=NO

,UNBOUND_ALIAS=YES

Specifies whether the scan should include unbound alias UCBs.

YES

Include unbound alias UCBs

NO

Do not include unbound alias UCBs

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

,DEVCLASS=DASD

,DEVCLASS=DASDTAPE

,DEVCLASS=TAPE

Specifies the device class that is to be searched for the VOLSER look-up.

DASD

Searches UCBs for direct access device class

DASDTAPE

Searches UCBs for DASD and tape classes

TAPE

Searches UCBs for tape class

,DYNAMIC=NO

,DYNAMIC=YES

Specifies if static or dynamic UCBs are to be looked at:

NO

Only static and installation-static UCBs

YES

Static, installation-static, and dynamic UCBs

,RANGE=3DIGIT

,RANGE=ALL

Specifies whether the look-up should be restricted to UCBs with 3-digit device numbers (3DIGIT) or should include all UCBs (ALL).

,IOCTOKEN=ioctoken addr

,IOCTOKEN=NONE

Specifies the address of a 48-character area that contains the MVS™ I/O configuration token that the caller supplies to UCBLOOK. 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 UCBLOOK 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, UCBLOOK will set IOCTOKEN to the current I/O configuration token.

,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.

• 2, 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 2

,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.

None.

When control returns from UCBLOOK, GPR 15 (and retcode addr, if you coded RETCODE) contains a return code and, for return code X'08', GPR 0 (and rsncode addr, if you coded RSNCODE) contains a reason code.