SHOWCAT

Format

Notes:

¹ When issuing SHOWCAT for the first time, use the NAME and AREA parameters to receive the CI addresses for associated objects and the catalog ACB address which are in the return area. From then on use the CI address, ACB address, and the AREA address to retrieve more information about the associated objects.

Purpose

Use the SHOWCAT macro to allow an application to retrieve information from the VSAM catalog. The information retrieved can be used to calculate parameters for building the resource pool for Local Shared Resources.

To use the SHOWCAT macro you must enter SHOWCAT on:

The name of the object.
The information returned to you includes the control interval numbers of catalog records in entries that describe associated objects.
A control interval number to retrieve information from one of these other entries.

Parameters

NAME

Specifies the address of a 44-byte area containing the data set name of the VSAM object for which you are retrieving information. The name is left justified, padded with blanks on the right, and must be an object other than upgrade set (Y).

CI

Specifies the address of a 3-byte area that contains the control interval number of the catalog entry for the object you want displayed. All object entries are valid. The area you specify with this parameter must be distinct from the area you specify with the AREA parameter.

Note: When you enter the first SHOWCAT for an object using the NAME parameter, you receive the CI numbers for associated objects and the catalog ACB address in the return area. You then use these pointers to retrieve more information about the associated objects.

ACB

Specifies the address of the ACB that defines the catalog containing the entry you want displayed.

Note:

The first time you enter SHOWCAT, do not specify an ACB. VSAM indicates the address of the ACB in the return area. Use this address and the entry CI numbers to retrieve information for the associated objects.
You must specify the ACB address in register notation.

AREA

Specifies the address of a work area where the catalog information is to be displayed.

Note:

The first 2 bytes of this area must contain the length of the work area, which includes the 2-byte length indicator.
The minimum size of the area is 64 bytes.

Usage

When using this macro you must make sure that register 13 contains the address of a 72-byte save area.
If you enter the macro from within one of your exit routines (LERAD or SYNAD) you must provide a second 72-byte save area because the original one is still in use by the external VSAM routine.

Completion Codes

When VSAM returns to the application after a SHOWCAT request, register 15 contains one of the following completion codes:

Completion Code	Meaning
0	VSAM completed the request successfully.
4	The area specified in the AREA parameter is less than the minimum required (64 bytes) or the area is too small to display all associated objects.
8	An error was detected while VSAM routines were being loaded.
12	Either the ACB address is invalid or the VSAM master catalog does not exist or cannot be opened.
20	The named object or control interval does not exist.
24	There was an I/O error in accessing the catalog.
28	The CI number specified is invalid.
32	The catalog record does not describe an acceptable type of object (C, D, G, I, R, or Y).
36	The information in the catalog is at a different level than that in the catalog recovery area.
40	There was an unexpected error code returned from catalog management to the SHOWCAT processor.

Information and Format in the Catalog Display

If the completion code returned was zero, the requested catalog information is returned in the work area that you specified with the AREA operand. The format of the returned information is as follows:

Offset	Length (bytes)	Meaning
0(0)	2	Length of the work area, including the length of this length field (provided by requester).
2(2)	2	Length of the work area actually used by VSAM, including the length of this field and the preceding field.
4(4)	4	The address of the ACB that defines the catalog that contains the entry which will be displayed.
8(8)	1	Type of object about which information is returned: Cluster (C) Data Component (D) Index Component (I) Alternate Index (G) Path (R) Upgrade Set (Y).

For C, G, R, and Y types:

Offset	Length (bytes)	Meaning
9(9)	1	For C and Y types: Reserved. For G type: x... .... The alternate index can be (1) or cannot be (0) a member of an upgrade set. The way to find out for sure 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 an alternate index. .xxx xxxx Reserved. For R type: x... .... The path is (1) or is not (0) defined with the UPDATE attribute (for upgrading alternate indexes). .xxx xxxx Reserved.
10(A)	2	The number of pairs of fields that follow. Each pair of fields 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, I, R With R: C, D, G, I With Y: D, I.
12(C)	1	Type of associated object the entry describes.
13(D)	3	The control interval number of its first record.
16(10)		Next pair of fields, and so on. Note: VSAM displays as many pairs as possible and returns a code of 4 in register 15 if the area is too small. Each pair of fields occupies 4 bytes, except Y-type (8 bytes).

For D and I types:

Offset	Length (bytes)	Meaning
9(9)	1	Reserved.
10(A)	2	Relative position of the prime key in records in the data component. For the data component of an entry-sequenced or a relative record file there is no prime key and this field is 0.
12(C)	2	Length of the prime key.
14(E)	4	Control interval size of the data or index component.
18(12)	4	Maximum record size of the data or index component.
22(16)	2	The number of pairs of fields that follow. Each pair of fields 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.
24(18)	1	Type of associated object the entry describes.
25(19)	1	The control interval number of its first record.
28(1C)		Next pair of fields, and so on. If the minimum AREA size is specified, fields for all associated objects can always be displayed.

ABEND Code	Meaning
03B	An invalid address was found in a VSAM control block or a VSAM parameter list. This means that your program tried to use an address to which it has no access.