UCBLIST or INFOLIST Type of Call

The UCBLIST or INFOLIST type call requires you to specify either the UCBLIST or INFOLIST parameter or both.

The format of the UCBLIST or INFOLIST type call is:


>>-+-------+--DEVTYPE------------------------------------------->
   '-label-'            

>--+-ddloc------------------------------------+----------------->
   |                             .-,BELOW-.   |   
   '-UCBLIST=(ucbl_addr,ucbl_num-+--------+-)-'   
                                 '-,ANY---'       

>--,(area_addr,area_size)--+---------------------+-------------->
                           '-INFOLIST=codel_addr-'   

>--+--------------------+--------------------------------------><
   |            .-MAX-. |   
   '-,PLISTVER=-+-0---+-'   
                '-1---'

ddloc—A-type address or (1-12)

The name of an 8-byte field that contains the symbolic name of the DD statement to which the device is assigned. The name must be left justified in the 8-byte field, and must be followed by blanks if the name is fewer than eight characters. Each DEVTYPE macro executable invocation must have either ddloc to identify an allocated data set or UCBLIST= to identify one or more devices.

You can specify ddloc as (1) only if you omit all keywords.

area_addrx—Rx-type address or (0, 2-12)

area_addr—A-type address or (2-12)

The name of an area into which the device information is to be placed. If your program does not specify the UCBLIST or INFOLIST function, the area is two, five, or six words long, depending on whether you specify the DEVTAB and RPS operands. If your program specifies the UCBLIST parameter without INFOLIST the area must be 6 words long for each UCB. The area must be on a word boundary.

If your program specifies the INFOLIST parameter, then the length of the area depends on what you coded for INFO on the referenced DEVTYPE macro. The INFO description states how many bytes are returned for each value you specify in the INFO list. To calculate the area size needed, multiply the sum of those values by ucbl_num in UCBLIST. If you omit UCBLIST (and specify ddloc), do not multiply.

Note that if you specify UCBLIST (and not ddloc) then (area_addr,area_size) must still be the second positional parameter. If you code (area_addr,area_size) before all the keywords, then code it after one comma. If you code (area_addr,area_size) after a keyword, then code (area_addr,area_size) after two commas.

area_size—absolute expression or (2-12)

The size (in bytes) of the area into which the device information is to be placed. See Table 1.

Table 1. Minimum size of area
ddloc specified	UCBLIST specified	INFOLIST specified	Minimum size of area
Yes	No	Omitted or 0	8, 20, or 24 bytes depending on whether DEVTAB and RPS are coded.
Yes	No	Yes	Sum of the number of bytes returned for each code specified with INFO. See also the INFO keyword.
No	Yes	Omitted or 0	24 bytes per UCB
No	Yes	Yes	The product of the number of UCBs specified with UCBLIST and the sum of the number of bytes returned for each code specified with INFO. See also the INFO keyword.

DEVTAB[,RPS]

DEVTAB is only meaningful for direct access devices. If DEVTAB is specified, the following number of words of information is placed in your area:

For direct access devices: 5 words
For non-direct access devices: 2 words.

If you do not specify DEVTAB, INFOLIST, or UCBLIST, one word of information is placed in your area if the reference is to a graphics or teleprocessing device; for any other type of device, two words of information are placed in your area.

RPS: If RPS is specified, DEVTAB must also be specified. The RPS parameter causes one additional word of rotational position sensing information to be included with the DEVTAB information.

UCBLIST=(ucbl_addr,ucbl_num [,BELOW or ANY])

UCBLIST provides a list service in which the caller passes a list of 4-byte UCB addresses and specifies the number of UCB address entries that are in the list. You must specify the UCBLIST parameter or ddloc. The BELOW or ANY are optional keywords that indicate whether the address passed by the UCB parameter contains a 3-byte or 4-byte UCB address. This keyword only applies to callers running in AMODE 31. If the caller is running in AMODE 24, the keyword ANY is ignored and the high-order byte is treated as X'00'.

If you do not specify INFOLIST, then the information returned is always returned in 6-word entries (one entry per UCB address) regardless of the device type. The words that would contain information not applicable to the device for that entry are not altered.

The DEVTYPE macro will accept a captured UCB or an actual UCB address above or below the 16 MB line, via the UCBLIST = parameter. It will also accept 24- or 31-bit addresses of UCB copies. The UCB copy must be on a word boundary, but can be above or below the 16 MB line. Unauthorized programs can get a copy of the UCB by using the UCBSCAN macro and specifying the COPY and UCBAREA keywords. Refer to z/OS HCD Planning for details.

ucbl_addr—A-type address or (2-12): Name of an area containing a list of 4-byte UCB addresses.
ucbl_num—absolute expression or (2-12): Number of 4-byte UCB address entries in the list.
BELOW: The UCB parameter contains addresses of UCBs that reside in storage below 16 MB, or a captured UCB. This is the default. If BELOW is specified, the high-order byte of the UCB address is treated as X'00'.
ANY: The UCB parameter contains a 4-byte UCB address. If ANY is specified when invoking in 31-bit mode, DEVTYPE treats each word in the UCB address list as a 31-bit address.

INFOLIST=codel_addr

The name of an area that specifies the types of information DEVTYPE is to return. Coding INFOLIST=0 has the same effect as omitting it. If you specify INFOLIST, then you must also specify ddloc or UCBLIST and you must specify (area_addr,area_size). The format of the returned words is described under DEVTYPE, DASD, and SUFFIX (see page DEVTYPE).

codel_addr—A-type address or (2-12): Specifies an area which contains an instance of the DEVTYPE macro where you coded only the INFO keyword.

PLISTVER=0 or 1 or MAX

Specifies the version of the parameter list for the macro to generate.

0: The program cannot be assembled on a level of the system earlier than DFSMS/MVS Release 3, which was released in 1996. It can run on any system level that supports the coded parameters. You cannot code this with the INFOLIST or INFO parameter. The parameter list will be 20 bytes long.
1: The program can be assembled and run only on DFSMS/MVS Release 3 or later. The parameter list will not be acceptable for systems prior to DFSMS/MVS. This specification generates a 24-byte parameter list.
MAX: In the current release, this has the same effect as coding 1. In a future release, this value might allow a parameter list that is incompatible with an earlier release. This is the default and generates a 24-byte parameter list.