Output from the Catalog Information Routine

The catalog information routine returns the requested information to the caller in a user work area that is based on CIRWA. The data that is returned for each entry code value is described in Table 1.

Table 1. The data returned for each entry code
Entry code	Meaning	Data returned
X'01'	Retrieve the data set names having one more level of qualifier above what the caller specified.	Nine bytes of data per data set name. Each entry in the list contains a 1-byte prefix, which can be ignored, followed by an 8-byte qualifier.
X'02'	Retrieve all data set names.	45-byte data set names are moved into the user work area.
X'04'	Retrieve the volume information associated with a given data set name.	Volume information is moved into the user work area. See Table 4 for volume information format.
X'05'	Retrieve the next level data set name and volume information. (Excludes data set names with no volume information, for example, cluster, and GDG base.)	A list of variable-length entries, one entry per data set name. Each entry in the list contains a 1-byte prefix, which can be ignored, followed by the 8-byte qualifiers making up the data set name (including periods if they occur), and then volume information. See Table 4 for the format of the volume data.
X'06'	Retrieve all data set names and volume information. (Excludes data set names with no volume information, for example, cluster, and GDG base.)	45-byte data set name followed by volume information is moved to the user work area for all levels.

Note: For codes X'02' and X'06', a 1-byte field precedes a 44-byte name field. The type field has one of the following values:

V for volume
C for cluster
G for alternate index
R for path
F for FREE
Y for upgrade
B for GDG base
X for alias name
P for page space
M for master catalog
U for user catalog
A for non-VSAM data set
D for data component
I for index component

A format 1 user work area that is based on CIRWA is shown in Table 2.

Table 2. Format 1 user work area for CIRPARM
Number of bytes	Field name	Contents or meaning
2	AREALN	Length of work area (an unsigned, 16-bit number).
2	DATALIN	Length of data returned +4 (an unsigned, 16-bit number).
Variable	DATA	An array of entries where data is stored. Each entry consists of a 1-byte type field followed by a 44-byte name field. The array has an end indicator of X'FF'.

A format 2 user work area that is based on CIRWA is shown in Table 3.

Table 3. Format 2 user work area for CIRPARM
Number of bytes	Field name	Contents or meaning
4	AREALN2	Length of work area (a signed, 32-bit number).
4	DATALIN2	Length of data returned +8 (a signed, 32-bit number).
Variable	DATA	An array of entries where data is stored. Each entry consists of a 1-byte type field followed by a 44-byte name field. The array has an end indicator of X'FF'.

When you specify a data set name, a volume list is built in your work area. A volume list consists of an entry for each volume on which part of the data set resides; it is preceded by a 1-byte field that contains a count of the number of volumes in the list. The count field is followed by a variable number of 12-byte entries, with one entry for each volume. Each 12-byte entry consists of a four-byte device code, a six-byte volume serial number, and a two-byte sequence number. As many as 255 of these 12-byte entries can be built in your work area. The volume list has an end indicator of X'FF'. Table 4 shows the format of the volume list.

Table 4. Volume information format
Number of bytes	Field name	Contents or meaning
1		Number of volumes on which part of the data set resides.
4	DEVTYP	Device type.
6	VOLSER	Volume serial number.
2	FILESEQ	File sequence number. (This field is provided for compatibility with the OS/VS catalog, and is used for non-VSAM data sets that reside on tape volumes.)