When you define a VSAM cluster with IDCAMS, the cluster and its data (and index) components are recorded in a catalog. The catalog is the place where the system stores the cluster name, its attributes, and the locations of the components on DASD. When you open a VSAM file by name in JCL or in a program, the system uses the catalog to find that cluster and its components. On z/OS, the catalog system is the Integrated Catalog Facility (ICF). Understanding the catalog component helps you see why you do not need to specify VOLUME for cataloged VSAM, how JOBCAT and STEPCAT work when using user catalogs, and how to use LISTCAT to inspect VSAM objects. This page covers what the VSAM catalog is, how it fits with ICF, and how the catalog is used when defining and accessing VSAM datasets.
The catalog is a repository of metadata about datasets. For VSAM, it holds the definition of each cluster: the cluster name, the type (INDEXED, NONINDEXED, NUMBERED, LINEAR), record size, key information, free space, share options, and the names and locations of the data and index components. When you run DEFINE CLUSTER, IDCAMS creates or updates catalog entries for the cluster and for each component. Each component has its own entry that points to the volumes and extents where that component's data is stored. So the catalog does not hold the actual records; it holds the "directory" that tells the system where to find the cluster and its parts.
When your job allocates a VSAM dataset with DSN=USERID.MY.VSAM.CLUSTER, the system searches the catalog for that name. It finds the cluster entry, and from that entry it gets the data component name and location (and for KSDS, the index component name and location). The access method then uses that information to open the components and satisfy your program's I/O requests. So without the catalog, the system would not know which volumes to use or how the cluster is structured. That is why VSAM datasets are said to be cataloged: their definitions live in the catalog.
On z/OS, the catalog system used for VSAM (and for other dataset types) is the Integrated Catalog Facility, or ICF. ICF replaced the older VSAM catalog structure. An ICF catalog is itself made up of catalog datasets: typically a BCS (Basic Catalog Structure) and one or more VVDS (VSAM Volume Data Set) entries that hold volume and extent information. The details of BCS and VVDS are mainly of interest to system programmers; as an application developer you need to know that when you define a VSAM cluster, it is recorded in an ICF catalog, and when you allocate by name, the system uses that catalog to resolve the name to locations. The catalog you use is determined by the job's catalog search order: usually the master catalog and then any user catalogs pointed to by JOBCAT or STEPCAT.
For each VSAM cluster, the catalog stores at least the following. The cluster entry has the cluster name, the dataset type (KSDS, ESDS, RRDS, LDS), and the attributes you specified (or defaults): RECORDSIZE, KEYS, FREESPACE, SHAREOPTIONS, REUSE, passwords, retention, and so on. It also has pointers to the data component and, for KSDS, the index component. Each component has its own catalog entry with its name, type (data or index), volume serial(s), and extent information. So one cluster might correspond to three catalog entries: one for the cluster and one for each of the data and index components.
| Item | What is stored |
|---|---|
| Cluster name | Logical name used in JCL and programs |
| Dataset type | KSDS, ESDS, RRDS, LDS |
| Attributes | RECORDSIZE, KEYS, FREESPACE, SHAREOPTIONS, etc. |
| Data component | Name, volume(s), extent information |
| Index component (KSDS) | Name, volume(s), extent information |
For non-VSAM datasets you often specify VOLUME=SER=volser (or let SMS assign a volume). For VSAM, the usual practice is to omit VOLUME and UNIT from the DD statement. The cluster is cataloged; the catalog already has the volume and extent information for the data and index components. When the job runs, the system looks up the cluster name in the catalog and gets the volume from there. So the DD only needs DSN=cluster.name and DISP=SHR or OLD (or whatever disposition). The catalog does the rest. You only need to specify the catalog itself (e.g. JOBCAT or STEPCAT) when the cluster is in a user catalog that is not in the default search order.
There is typically one master catalog per z/OS system (or sysplex). It contains critical system datasets and often pointers to user catalogs. User catalogs are additional ICF catalogs that can hold application VSAM datasets. When you define a cluster, you can specify CATALOG(catalog-name[/password]) to put the cluster in a particular user catalog. When you run a job that uses that cluster, the job must have access to that catalog—usually by having a JOBCAT or STEPCAT DD that points to the user catalog. So the "catalog component" in the big picture is: the master catalog plus any user catalogs that hold your VSAM definitions, and the BCS/VVDS structures that store the actual entries.
To see what is in the catalog for a VSAM dataset, you use the IDCAMS LISTCAT command. LISTCAT can list a specific cluster by name, or list all entries under a prefix. The output includes the cluster name, type, attributes (record size, key, free space, etc.), and the names and allocation details of the data and index components. LISTCAT is useful for verifying that a cluster was defined correctly, for finding component names and volumes, and for debugging allocation or open failures. You run it in an IDCAMS job with SYSIN containing the LISTCAT command.
123456//LISTCAT EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * LISTCAT ENTRIES(USERID.MY.VSAM.CLUSTER) ALL /*
ENTRIES specifies the cluster name (or a prefix); ALL requests full attribute and allocation information. The report is written to SYSPRINT. From it you can confirm the cluster type, RECORDSIZE, KEYS, and the data and index component names and volumes.
When you run DEFINE CLUSTER, IDCAMS uses the job's catalog environment (master catalog plus any JOBCAT/STEPCAT) to decide where to create the new cluster entry. If you omit the CATALOG parameter, the cluster is cataloged in the first catalog in the search order that accepts new entries (often a user catalog pointed to by JOBCAT). If you specify CATALOG(user.catalog.name), the cluster is created in that catalog. The catalog must exist and the job must have access to it. After a successful DEFINE, the cluster and its components are in the catalog and can be used by any job that can find that catalog.
When you run IDCAMS DELETE cluster-name CLUSTER, IDCAMS removes the cluster entry and the component entries from the catalog and frees the space on the volumes. So the catalog is updated to show that the cluster no longer exists. If the cluster had a retention date and has not expired, you need the PURGE option on the DELETE to force removal. After a successful DELETE, a subsequent attempt to allocate that cluster name will fail because the name is no longer in the catalog.
The catalog is like the phone book for VSAM files. When you want to use a file, you give its name. The system looks up the name in the phone book (the catalog) and finds where that file lives (which volumes and which components). The catalog doesn't hold the actual data—just the name and address. ICF is the kind of phone book the system uses on z/OS.
1. Where does the system find the volume for a VSAM cluster when you use DSN=cluster.name?
2. What is ICF?
3. Which IDCAMS command lists catalog information for a VSAM dataset?