SHOWCAT—Standard form

The format of the SHOWCAT macro is:

[label]

SHOWCAT

[ACB=address]
[AREA=address]
[FWLEN={NO|YES}]
[{CI=address|NAME=address}][RETURN={CI|NAME}]

label

specifies 1 to 8 characters that provide a symbolic address for the SHOWCAT macro.

ACB=address

specifies the address of the access method control block that defines the catalog containing the entry from which to display information. You issue the first SHOWCAT without ACB specified and VSAM supplies it to you for the next SHOWCAT (see the description of the work area under the AREA operand). Specifying ACB enables VSAM to go directly to the correct catalog without searching other catalogs first. You should always specify ACB when specifying CI instead of NAME.

AREA=address

specifies the address of the work area in which to display the catalog information. The first 2 bytes of the area must give the length of the area, including the 2 bytes. The minimum is 64. If the area is too small, VSAM returns as much information as possible.

FWLEN={NO|YES}

indicates whether the mappings for a workarea returned at the beginning supports a length of a halfword or fullword. The default is NO.

NO: indicates that the workarea returned supports only a length of a halfword. This is the default.
YES: indicates that the workarea returned supports only a length of a fullword.

You can use the IGGSHWPL macro to generate a DSECT statement and labels for the fields in the work area.

The format of the work area for RETURN=CI and FWLEN=NO is:

Offset	Length	Symbolic Name	Description
0(X'00')	2	SHWLEN1	Length of the area, including the length of this field (provided by you).
2(X'02')	2	SHWLEN2	Length of the area used by VSAM, including the length of this field and the preceding field.
4(X'04')	4	SHWACBP	The address of the ACB that defines the catalog that contains the entry from which information is displayed.
8(X'08')	1	SHWTYPE	Type of object about which information is returned: C Cluster D Data component G Alternate index I Index R Path Y Upgrade set

Note: For information on the RETURN=NAME and FWLEN=YES workarea mappings see the IGGSHWPL macro.

The following fields contain one set of information for C, G, R, and Y types and another set for D and I types:

The format of the work area for C, G, R, and Y types is:

Offset	Length or Bit Pattern	Symbolic Name	Description
9(X'09')	1	SHWATTR	For C and Y types: reserved.
			For G type:
	x... ....	SHWUP	The alternate index may (1) or may not (0) be a member of an upgrade set. One way of verifying this is to display information for the upgrade set of the base cluster and check whether it contains control interval numbers of entries that describe the components of the alternate index. Figure 1 shows how to get from the alternate index's catalog entry to the entries that describe its components (G to C to D to Y to D and I).
	.xxx xxxx		Reserved.
			For R type:
	x... ....	SHWUP	The path is (1) or is not (0) defined for upgrading alternate indexes.
	.xxx xxxx		Reserved.
10(X'0A')	2	SHWASS0	The number of association pointers that follow.
		SHWACT	Each association pointer identifies another catalog entry that describes an object associated with this C, G, R, or Y object. The possible types of associated objects are: With C: D, G, I, R. With G: C, D, G, I. With R: C, D, G, I. With Y: D, I. Figure 1 shows how the catalog entries for all these objects are interrelated.
12(X'0C')	1	SHWATYPE	Type of object the entry describes.
13(X'0D')	3	SHWAC1	The control interval number of its first record.
16(X'10')			Next association pointer, and so on. For type Y, if the area is too small to display an association pointer for each associated object, VSAM displays as many pointers as possible and returns a code of 4 in register 15. For types C and G, if the area is too small, VSAM displays as many pointers as possible, but returns as a code of 0 in register 15 because fields for the main associated objects can always be displayed (in the smallest allowed work area). For type R, fields for all associated objects (five possible) can always be displayed. (An associated pointer occupies 4 bytes (1 byte for the associated entry type and 3 bytes for its control interval number). However, for all types except Y, 4 additional bytes are required as work space for the SHOWCAT processor. For example, if you provide 80 bytes for associated objects, as many as 10 association pointers can be displayed for type C or G and 20 for type Y.)

The format of the work area for D and I types is:

Offset	Length	Symbolic Name	Description
9(X'09')	1		Reserved.
10(X'0A')	2	SHWDSB	Relative position of the prime key in records in the data component.
		SHWRKP	For the data component of an ESDS, there is no prime key and this field is 0.
12(X'0C')	2	SHWKEYLN	Length of the prime key.
14(X'0E')	4	SHWCISZ	Control interval size of the data or index component.
18(X'12')	4	SHWMREC	Maximum record size of the data or index component.
22(X'16')	2	SHWASS	The number of association pointers that follow.
		SHWACT	Each association pointer identifies another catalog entry that describes an object associated with this D or I object. The possible types of associated objects are: With D: C, G, Y. With I: C, G. Figure 1 shows how the catalog entries for all these objects are interrelated.
24(X'18')	1	SHWATYPE	Type of object the entry describes.
25(X'19')	3	SHWACI	The control interval number of its first record.
28(X'1C')			Next association pointer, and so on. Fields for all associated objects can always be displayed.

{CI=address|NAME=address}

specifies the address of an area that identifies the catalog entry containing the desired information.

Note: Users of the SHOWCAT macro are strongly urged to convert any uses of the CI keyword the RETURN=NAME format. The CI implementation exists to be compatible with VSAM catalogs which were no longer usable after 01/01/2000. The CI values returned are not sharable across address spaces and there is a finite table size allowed for mapping component names to pseudo-CI numbers. When this table is exceeded, which can be done by applications that issue the SHOWCAT macro many times, no further information can be returned by the SHOWCAT service. Because of these limitations the CI interface will be removed in the future.

CI=address: specifies the area is 3 bytes long and contains the control interval number (RBA divided by 512) of the first record in the catalog entry. You can issue the first SHOWCAT with NAME specified, and then VSAM supplies control interval numbers to you for other SHOWCATs (see the description of the work area under the AREA operand). The type of object named must be C, D, G, I, R, or Y. The 3-byte area must be separate from the work area, even though VSAM returns a control interval number in the work area.
NAME=address: specifies the area is 44 bytes long and contains the name of the object described by the entry. The name is left-justified and padded with blanks. The type of object named must be C, D, G, I, or R.

RETURN={CI|NAME}

indicates whether mappings will be generated for returning CI numbers or component names. The default is CI.

CI: indicates that mappings for CI numbers will be generated and CI numbers will be returned. This is the default.
NAME: indicates that mappings for component names will be generated and component names will be returned.