IDCAMS LISTCAT

The IDCAMS LISTCAT command lists catalog entries from a VSAM or ICF catalog. You can list clusters, data and index components, paths, alternate indexes, and other objects. LISTCAT shows attributes such as name, type, space allocation, volumes, creation and expiration dates, record size, key information, and more. You control how much detail you get with NAME, VOLUME, ALLOCATION, or ALL. You limit which entries are listed with ENTRIES(entry-name) or a generic prefix. This page explains the LISTCAT syntax, the difference between NAME, VOLUME, ALLOCATION, and ALL, how to list a specific cluster or path, and how to send the output to a dataset.

What LISTCAT Does

LISTCAT reads the catalog and prints information about the entries you request. It does not change the catalog or the datasets; it only reports what is in the catalog. You use it to verify that a cluster exists, to see its attributes (e.g. RECORDSIZE, KEYS, FREESPACE), to check space allocation and volumes, to find the names of data and index components, and to see creation and expiration dates. So LISTCAT is the main way to inspect VSAM catalog entries from a batch job or from a tool that runs IDCAMS.

General Syntax

LISTCAT can list by object type (CLUSTER, PATH, etc.) and by entry name. You specify how much detail with NAME, VOLUME, ALLOCATION, or ALL. Basic form:

1
2
3
4
5
6
7
8
  LISTCAT -
    [ CLUSTER | DATA | INDEX | PATH | ALTERNATEINDEX | ... ] -
    [ ENTRIES(entry-name [ entry-name ... ]) ] -
    [ NAME | VOLUME | ALLOCATION | ALL ] -
    [ OUTFILE(ddname) ] -
    [ PREFIX | NOPREFIX ] -
  [ CATALOG(catname) ]
 

If you omit ENTRIES, LISTCAT may list all entries in the catalog (or under a default); that can be a lot of output. Usually you specify ENTRIES with a cluster name, path name, or generic prefix (e.g. MY.FILE.*). NAME is the minimum detail; ALL is the maximum. OUTFILE sends the listing to a DD name (e.g. a dataset) instead of SYSPRINT.

Detail Levels: NAME, VOLUME, ALLOCATION, ALL

The amount of information LISTCAT prints depends on which level you choose. Each level adds more fields to the previous one. The default is often NAME or a system-dependent level.

Object Types

You can restrict the listing to a specific type of catalog entry. If you specify CLUSTER and ENTRIES(my.cluster), you list that cluster (and optionally its components). If you specify PATH, you list path entries. Omitting the type may list all entry types that match ENTRIES.

ENTRIES: Which Entries to List

ENTRIES(entry-name) limits the listing to the named entry or entries. You can list one cluster: ENTRIES(MY.FILE.KSDS). You can list several: ENTRIES(MY.FILE1 MY.FILE2). You can use a generic name with an asterisk: ENTRIES(MY.FILE.*) lists all entries whose name starts with MY.FILE. (e.g. MY.FILE.KSDS, MY.FILE.KSDS.DATA, MY.FILE.KSDS.INDEX). So ENTRIES is the main way to focus LISTCAT on the objects you care about. Without ENTRIES, the scope depends on your system (e.g. all entries in the catalog or under a default prefix).

OUTFILE: Sending Output to a Dataset

By default, LISTCAT writes to SYSPRINT (the IDCAMS output DD), which is usually the job log. To capture the listing in a dataset, use OUTFILE(ddname). In JCL, allocate that DD to a sequential dataset (or SYSOUT). The listing will be written there. Use this when you need to parse the output (e.g. to check allocation or find component names) or to keep a record of the catalog state.

CATALOG and PREFIX

CATALOG(catname) specifies which catalog to list. If you omit it, the step or job default catalog is used. When your cluster is in a user catalog, specify that catalog or ensure JOBCAT/STEPCAT points to it. PREFIX and NOPREFIX control whether a user ID (or high-level qualifier) is automatically added to entry names in the listing; behavior is implementation-dependent. Use the option that matches your site's naming convention.

Example: List One Cluster with Full Detail

1
2
3
4
5
6
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  LISTCAT ENTRIES(MY.FILE.KSDS) CLUSTER ALL
/*
 

Lists the cluster MY.FILE.KSDS and its components with full detail (ALL). The output includes name, type, space allocation, volumes, record size, key definition, free space, share options, creation and expiration, and other attributes. The listing goes to SYSPRINT.

Example: List All Entries Under a Prefix

1
2
  LISTCAT ENTRIES(MY.APPL.*) NAME
 

Lists all catalog entries whose name starts with MY.APPL. (e.g. MY.APPL.FILE1, MY.APPL.FILE1.DATA, MY.APPL.PATH). NAME keeps the output short (name and type only). Use this to see what datasets exist under a high-level qualifier.

Example: List Paths and Send to a Dataset

1
2
3
4
5
6
7
8
9
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//LISTOUT  DD   DSN=MY.LISTCAT.OUTPUT,DISP=(NEW,CATLG,DELETE),
//             SPACE=(TRK,(1,1)),UNIT=SYSDA,
//             DCB=(RECFM=FB,LRECL=133,BLKSIZE=13300)
//SYSIN    DD   *
  LISTCAT ENTRIES(MY.APPL.*) PATH ALL OUTFILE(LISTOUT)
/*
 

Lists all path entries under MY.APPL.* with full detail and writes the output to MY.LISTCAT.OUTPUT. The LISTOUT DD is allocated to that dataset. SYSPRINT will still receive the usual IDCAMS messages; the catalog listing goes to LISTOUT.

What You See for a Cluster

For a cluster entry, LISTCAT ALL typically shows: the cluster name and type (CLUSTER), the names of the DATA and INDEX components (for KSDS), space allocation (primary and secondary in cylinders or tracks), RECORDSIZE, KEYS (length and offset for KSDS), FREESPACE, SHAREOPTIONS, volume serial numbers, creation and expiration date, high-used RBA (how much of the dataset is used), and other attributes. For a path, you see the path name and PATHENTRY (the AIX name). For an AIX, you see the AIX cluster name, RELATE (base cluster), and AIX-specific attributes. So LISTCAT is the main way to verify define-time attributes and to troubleshoot "dataset not found" or space issues.

Key Takeaways

• LISTCAT lists catalog entries. Use it to see cluster, path, and AIX attributes, space, and history.
• ENTRIES(entry-name) limits the listing to the named entry or entries. Use a generic (e.g. MY.FILE.*) to list multiple.
• NAME shows minimal detail; VOLUME adds volumes; ALLOCATION adds space; ALL shows full detail.
• OUTFILE(ddname) sends the listing to a dataset. Allocate the DD to a sequential file or SYSOUT.
• Specify CLUSTER, PATH, or ALTERNATEINDEX to list only that type of entry.

Explain Like I'm Five

The catalog is like a phone book that remembers where every file lives and what it looks like. LISTCAT is like looking up a name in the phone book and reading the entry. You can ask for just the name (NAME), or the name and address (VOLUME), or the name, address, and how big the house is (ALLOCATION), or everything in the entry (ALL). You tell the system which name to look up with ENTRIES. So LISTCAT is "show me what the catalog knows about this file."

Test Your Knowledge