The standard form of the ADDRESS function of the UCBSCAN macro is written as follows:

The parameters are explained as follows:

ADDRESS

Specifies that a UCB address is to be obtained.

,WORKAREA=workarea addr

Specifies the address of a 100-character work area that will be 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.

,UCBPTR=ucbptr addr

Specifies the address of a pointer in which the address of the UCB common segment for the next UCB that meets the search criteria 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 will return the address of the UCB common extension. 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 will return the address of the UCB prefix extension. Use the IOSDUPFX mapping macro to map the UCB prefix extension segment.

,LOC=BELOW

,LOC=ANY

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

,PIN

,NOPIN

Specifies whether the UCB is to be pinned to make it ineligible for deletion through the dynamic UCB process. Pinning the UCB ensures that it will not be deleted while the scan 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.

,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 area can be mapped by the IOSDUPI mapping macro.

,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 includes all subchannel sets. DEFAULT: ID

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

,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 an 8-bit input field used to supply the hexadecimal device class ID of the device class to be scanned. devcid addr specifies the address of the field.

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 area that contains the MVS I/O configuration token that you supply to UCBSCAN. You 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 only the following parameters:
  • ADDRESS
  • DEVCID
  • DEVCLASS
  • DEVN
  • DYNAMIC
  • IOCTOKEN
  • LINKAGE
  • LOC
  • MF
  • NOPIN
  • PIN
  • PLISTVER
  • PTOKEN
  • RANGE
  • RETCODE
  • RSNCODE
  • TEXT
  • UCBPAREA
  • UCBPTR
  • WORKAREA
• 2, if you use any of the following parameters and parameters from plistver 1.
  • UCBCXPTR
  • UCBPXPTR

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

• IMPLIED_VERSION
• MAX
• A decimal value of 1 or 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.

When control returns from UCBSCAN, GPR 15 (and retcode addr, if you coded RETCODE) contains one of the following return codes: