VSAM Cluster: Definition, Attributes, and Lifecycle

In VSAM, the cluster is the single logical dataset you define, catalog, and use. It has one name, one catalog entry, and one or two physical components (data and, for Key Sequenced Data Sets, index). Understanding the cluster as an object—how it is defined, what attributes it has, and how it moves through its lifecycle—helps you design, create, and maintain VSAM datasets correctly. This page focuses on the cluster as a catalog object: its definition, a reference of cluster-level attributes (what each does and how it affects behavior), and the four phases of its lifecycle (define, use, alter, delete).

What Is the Cluster in the Catalog?

When you run IDCAMS DEFINE CLUSTER, the utility creates a catalog entry for the cluster. That entry is the "cluster object." It stores the cluster name, the organization type (INDEXED, NONINDEXED, NUMBERED, or LINEAR), record and key attributes, space allocation, and pointers to the data component—and for KSDS, the index component. The cluster entry does not hold the actual data; it holds metadata and the links to the components where the data and index live. So when you run LISTCAT on the cluster, you see the cluster entry and, under it, the data component (and index component for KSDS). When a program opens the cluster by name, the system looks up this catalog entry and uses it to find the components and their locations on disk.

The cluster is therefore the single handle that applications and JCL use. You never open the data component or the index component by name. You open the cluster. The access method and the catalog do the rest. This keeps your code and JCL simple and ensures that the correct components are always used together.

Cluster Definition: What Gets Created

Defining a cluster means creating the catalog object and the underlying components in one step. DEFINE CLUSTER allocates space on the volumes you specify (or let SMS choose), builds the data component structure (control intervals and control areas), and for KSDS builds the index component. After a successful DEFINE, the cluster is ready to use: you can open it in a program, load it with REPRO or application writes, and read or update records. The definition is where you set most of the attributes that cannot be changed later, such as record size, key definition, and control interval size. Getting the definition right up front avoids having to define a new cluster and migrate data later.

Example: Defining a Cluster

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//DEFCLU   EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  DEFINE CLUSTER ( -
    NAME(USERID.INVENTORY.KSDS) -
    INDEXED -
    RECORDSIZE(80 120) -
    KEYS(12 0) -
    FREESPACE(15 10) -
    SHAREOPTIONS(2 3) -
    CISZ(4096) -
    CYLINDERS(5 2) -
    VOLUMES(SYSVOL)) -
  DATA (NAME(USERID.INVENTORY.KSDS.DATA)) -
  INDEX (NAME(USERID.INVENTORY.KSDS.INDEX))
/*
 

Here, NAME gives the cluster name. INDEXED makes it a KSDS, so both data and index components are created. RECORDSIZE(80 120) sets average and maximum record length. KEYS(12 0) defines a 12-byte key at offset 0. FREESPACE(15 10) reserves 15% of each CI and 10% of each CA for inserts. SHAREOPTIONS(2 3) allows cross-region and cross-system sharing. CISZ(4096) sets the control interval size to 4KB. CYLINDERS(5 2) allocates 5 primary and 2 secondary cylinders. The DATA and INDEX clauses give explicit names to the components; if omitted, IDCAMS would generate names from the cluster name. After this job runs, the cluster USERID.INVENTORY.KSDS exists in the catalog and can be used in JCL as DSN=USERID.INVENTORY.KSDS.

Cluster-Level Attributes Reference

The following table lists the main cluster-level attributes you can specify in DEFINE CLUSTER. Each attribute affects how the cluster is stored, shared, or protected. Some are fixed for the life of the cluster; others can be changed later with ALTER.

Organization Type: INDEXED, NONINDEXED, NUMBERED, LINEAR

The organization type determines the kind of VSAM dataset. INDEXED means a Key Sequenced Data Set (KSDS): records are in key order, and an index component provides key-based access. NONINDEXED means an Entry Sequenced Data Set (ESDS): records are in the order they were written, and access is by relative byte address (RBA). NUMBERED means a Relative Record Data Set (RRDS): fixed-length records in numbered slots (relative record number). LINEAR means a Linear Data Set (LDS): a byte stream with no record structure, used by products like DB2 or VSAM RLS. You cannot change the organization type after define; to switch types you must define a new cluster and copy the data.

RECORDSIZE and KEYS

RECORDSIZE(avg max) sets the average and maximum record length in bytes. For variable-length records, the maximum must be at least as large as the longest record you will store. For fixed-length records, average and maximum are often the same. KEYS(length offset) applies only to KSDS: length is the key length in bytes, and offset is the position of the key within each record (often 0). Both RECORDSIZE and KEYS are fixed at define time. If your record layout or key changes, you must define a new cluster with the new values and reload the data (for example with REPRO).

FREESPACE and Splits

FREESPACE(ci-percent ca-percent) reserves a percentage of each control interval and each control area for new records. For KSDS and RRDS, when you insert records, VSAM uses this free space. When the free space in a CI is used up, VSAM performs a CI split (and possibly a CA split), which can be expensive. Allocating enough free space (for example 15–20% CI and 10% CA for growing KSDS files) reduces how often splits occur. For ESDS, records are appended and free space is used differently; for LDS there is no record structure. FREESPACE is sometimes alterable, depending on the system.

SHAREOPTIONS

SHAREOPTIONS(cross-region cross-system) controls whether multiple address spaces (jobs or regions) can open the cluster at the same time and whether they can update it. The first number applies to cross-region sharing (e.g. multiple batch jobs or CICS regions); the second applies to cross-system sharing (e.g. multiple LPARs). Values typically range from 1 (minimum sharing) to 4 (maximum sharing). For example, (2 3) might allow multiple readers and one updater across regions, and broader sharing across systems. SHAREOPTIONS is often alterable, so you can change sharing behavior without redefining the cluster.

What You Can and Cannot Alter

After a cluster is defined, some attributes can be changed with IDCAMS ALTER; others cannot. The following table summarizes.

If you need to change a fixed attribute (for example record size or key definition), you must define a new cluster with the desired attributes, copy the data (e.g. with REPRO from the old cluster to the new one), and then switch applications to the new cluster name (or rename the new cluster if your shop allows). There is no in-place change for those attributes.

Lifecycle of a VSAM Cluster

The cluster moves through four phases from creation to removal. Understanding each phase helps you choose the right commands and avoid mistakes (for example trying to alter something that cannot be changed, or forgetting PURGE when deleting a retained dataset).

Define

Define is the creation step. You run IDCAMS with DEFINE CLUSTER in SYSIN. The utility allocates space on the volumes (or lets SMS manage it), creates the data component (and for KSDS the index component), and adds the cluster and component entries to the catalog. The cluster is then available for use. You typically define a cluster once when setting up a new file, or again when you need a new cluster with different fixed attributes (after which you copy data from the old cluster).

Use

Use is the normal operational phase. Batch jobs and online programs open the cluster by name. JCL specifies DSN=cluster-name on the DD statement. The access method uses the catalog to resolve the cluster to its components and performs reads and writes. The cluster remains in this phase for most of its life: it is opened, used, and closed many times. Attributes set at define time (and any changed by ALTER) apply throughout.

Alter

Alter is optional. When you need to change an attribute that is alterable (such as SHAREOPTIONS or FREESPACE), you run IDCAMS ALTER. The ALTER command identifies the cluster by name and specifies the new attribute values. The catalog entry is updated. The cluster does not need to be empty or closed in all environments; check your IDCAMS documentation for whether the cluster can be in use during ALTER. Alter does not change fixed attributes; for those, you must define a new cluster and migrate data.

Delete

Delete removes the cluster and its components from the catalog and frees the space on the volumes. The command is DELETE cluster-name CLUSTER. If the cluster has a retention period (FOR or TO) and has not yet expired, the delete fails unless you add the PURGE option, which overrides retention. Other options (e.g. ERASE to overwrite data before freeing, FORCE for special cases) depend on your IDCAMS implementation. After a successful DELETE, the cluster name no longer exists in the catalog; any job that tries to allocate it will get a "dataset not found" type condition.

Deleting a Cluster: Syntax and Options

A typical delete command looks like this:

1
2
  DELETE USERID.INVENTORY.KSDS CLUSTER
 

This removes the cluster and its components. If the cluster is retained (FOR/TO) and not yet expired, use:

1
2
  DELETE USERID.INVENTORY.KSDS CLUSTER PURGE
 

PURGE tells the system to delete the cluster even though the retention period has not been reached. Without PURGE, the delete would fail with a retention-related message. After deletion, the cluster name is gone; to use the same name again you would have to run DEFINE CLUSTER for that name (and optionally load data with REPRO).

Why the Cluster Name Is What You Use

Applications and JCL use the cluster name because the cluster is the only logical dataset. The data and index components are internal. The catalog stores the cluster entry and the links to the components; when you open the cluster, the access method follows those links. Using the cluster name everywhere keeps allocation simple (one DSN=), avoids mistakes (you cannot accidentally point to the data component only and lose key-based access for a KSDS), and lets the system manage component names and locations. When you design or document a VSAM file, you document the cluster name and its attributes; the component names are for LISTCAT and administration, not for everyday use.

Key Takeaways

• The cluster is the catalog object that represents the logical VSAM dataset; it has one name and points to one or two components.
• You always reference the cluster name in JCL and in programs; you never open the data or index component by name.
• Cluster-level attributes include NAME, organization type, RECORDSIZE, KEYS (KSDS), FREESPACE, SHAREOPTIONS, space allocation, CISZ, REUSE, passwords, retention, and CATALOG.
• RECORDSIZE, KEYS, organization type, and CISZ are fixed at define time; SHAREOPTIONS, FREESPACE, REUSE, and passwords are often alterable.
• Lifecycle: Define (create and catalog), Use (open by cluster name), Alter (change alterable attributes), Delete (remove from catalog and free space; use PURGE if retained).

Explain Like I'm Five

The cluster is like the name on a box that holds your toys. When you want to play, you say the name of the box. You don't say "open the bottom drawer" or "open the little index drawer"—you just say the box's name, and the grown-up (the system) knows which parts to open. The box is created once (define), you use it lots of times (use), sometimes the grown-up changes a rule about who can use it (alter), and when you don't need it anymore the box is thrown away (delete). The cluster is that box name: one name, one place to go.

Test Your Knowledge