DEFINE CLUSTER

DEFINE CLUSTER is the IDCAMS command that creates a new VSAM cluster. When you run it, IDCAMS allocates space on DASD, creates the catalog entry (or entries) for the cluster and its components, and sets the attributes you specify: organization type (KSDS, ESDS, RRDS, or LDS), record size, key (for KSDS), free space, and allocation. You cannot create a VSAM dataset with JCL DISP=NEW the way you do for sequential files; DEFINE CLUSTER is the standard way. This page explains the DEFINE CLUSTER syntax, the main parameters, and how to define each type of VSAM dataset.

What DEFINE CLUSTER Does

When IDCAMS processes a DEFINE CLUSTER command, it creates one logical object—the cluster—and one or two component objects. For a KSDS (INDEXED), it creates the data component and the index component. For ESDS, RRDS, or LDS, it creates only the data component. The cluster name is what you use in JCL (DSN=) and in application programs. The components are internal; you do not open them directly. DEFINE CLUSTER also allocates space: you specify how much (in cylinders, tracks, or records) and optionally which volume(s). After a successful DEFINE, the cluster is cataloged and ready to be opened, loaded (e.g. with REPRO), and used by programs.

General Syntax

The command starts with DEFINE CLUSTER and is followed by cluster-level parameters, then optionally DATA(...) and for KSDS INDEX(...). Parameters are keyword(value) or keyword. Continuation across lines uses a hyphen at the end of the line. A minimal form is:

1
2
3
4
5
6
7
8
  DEFINE CLUSTER ( -
    NAME(cluster-name) -
    organization -
    RECORDSIZE(min max) -
    space-allocation) -
  [ DATA (...) ] -
  [ INDEX (...) ]    /* KSDS only */
 

Organization is one of INDEXED, NONINDEXED, NUMBERED, or LINEAR. Space allocation is CYLINDERS(primary secondary), TRACKS(primary secondary), or RECORDS(primary secondary). For KSDS you also specify KEYS(length offset). The following sections describe the main parameters in more detail.

Organization Type: INDEXED, NONINDEXED, NUMBERED, LINEAR

You must specify exactly one organization type. It determines the dataset type and what components are created.

INDEXED is used for keyed files where you need direct access by key and sequential access in key order. NONINDEXED is for entry-sequenced files (logs, history) where records are appended and accessed by position (RBA) or sequentially. NUMBERED is for fixed-length records accessed by relative record number. LINEAR is for special uses (e.g. LDS for Db2) and is not used for normal record I/O.

Essential Parameters

These parameters appear on almost every DEFINE CLUSTER. NAME identifies the cluster. RECORDSIZE defines the record layout. KEYS is required for KSDS. FREESPACE and space allocation control how much space is reserved and how much is allocated.

RECORDSIZE and KEYS

RECORDSIZE(min max) gives the minimum and maximum record length in bytes. For fixed-length records (common for KSDS and RRDS), code the same value twice, e.g. RECORDSIZE(80 80) or RECORDSIZE(200 200). For variable-length records, min and max define the allowed range; for example RECORDSIZE(50 500) allows records from 50 to 500 bytes. These values cannot be changed after the cluster is defined.

KEYS(length offset) applies only to INDEXED (KSDS). Length is the key length in bytes; offset is the position of the first byte of the key within the record (0-based). For example KEYS(10 0) means a 10-byte key starting at byte 0; KEYS(8 20) means an 8-byte key starting at byte 20. The key must lie entirely within the record (offset + length ≤ record length). Key length and offset are fixed at define time.

Space Allocation

You specify space with CYLINDERS(primary secondary), TRACKS(primary secondary), or RECORDS(primary secondary). Primary is the amount allocated when the cluster is created. When the cluster fills, VSAM extends it by the secondary amount (up to a limit, often 123 extensions). CYLINDERS is common for larger files; TRACKS for smaller; RECORDS for very small or when you want to allocate by record count. Example: CYLINDERS(10 5) allocates 10 cylinders initially and 5 cylinders per extension.

FREESPACE

FREESPACE(ci-percent ca-percent) reserves a percentage of each control interval and each control area for new records. This is used by KSDS and RRDS to reduce how often VSAM has to split control intervals or control areas when inserting. For example FREESPACE(20 10) reserves 20% of each CI and 10% of each CA. Higher values mean more room for inserts but less data per CI (more I/O for sequential reads). ESDS does not use FREESPACE in the same way because it only appends; LDS has no record structure.

DATA and INDEX Clauses

The DATA clause lets you specify the data component name and optionally other data-component attributes. The INDEX clause (KSDS only) lets you specify the index component name and attributes. If you omit them, IDCAMS generates default names (usually cluster-name.DATA and cluster-name.INDEX). Explicit names are useful when you want to recognize components in LISTCAT or when following naming standards. Example:

1
2
3
4
5
6
7
8
9
10
11
  DEFINE CLUSTER ( -
    NAME(MY.APPL.KSDS) -
    INDEXED -
    RECORDSIZE(100 100) -
    KEYS(12 0) -
    FREESPACE(15 10) -
    CYLINDERS(20 5) -
    SHAREOPTIONS(2 3)) -
  DATA (NAME(MY.APPL.KSDS.DATA)) -
  INDEX (NAME(MY.APPL.KSDS.INDEX))
 

This defines a KSDS named MY.APPL.KSDS with 100-byte fixed records, a 12-byte key at offset 0, 15% CI and 10% CA free space, 20 cylinders primary and 5 secondary, and share options (2 3). The data and index components are explicitly named.

Defining an ESDS

For an Entry Sequenced Data Set use NONINDEXED. There is no KEYS parameter. You still specify RECORDSIZE and space. There is no INDEX clause.

1
2
3
4
5
6
7
  DEFINE CLUSTER ( -
    NAME(MY.LOG.ESDS) -
    NONINDEXED -
    RECORDSIZE(256 256) -
    CYLINDERS(5 2)) -
  DATA (NAME(MY.LOG.ESDS.DATA))
 

ESDS records are fixed or variable within RECORDSIZE; they are stored in the order they are written and cannot be physically deleted. Access is by RBA or sequential.

Defining an RRDS

For a Relative Record Data Set use NUMBERED. Records are fixed-length; each slot has a relative record number (RRN). You specify RECORDSIZE (same min and max for fixed length) and space. FREESPACE can be used to leave empty slots for later inserts.

1
2
3
4
5
6
7
8
  DEFINE CLUSTER ( -
    NAME(MY.RRDS.FILE) -
    NUMBERED -
    RECORDSIZE(80 80) -
    FREESPACE(10 5) -
    TRACKS(10 5)) -
  DATA (NAME(MY.RRDS.FILE.DATA))
 

Other Useful Parameters

VOLUMES(volser) specifies the DASD volume serial(s) when you need to place the cluster on particular volumes. SHAREOPTIONS(cross-region cross-system) controls how the file can be shared (e.g. (2 3) for typical batch). REUSE allows the cluster to be opened for output and rewritten without deleting it first. READPW and UPDATEPW add password protection. FOR(days) or TO(date) set retention. CATALOG(catalog-name[/password]) specifies which catalog to use. Your installation may have standards for these.

Key Takeaways

• DEFINE CLUSTER creates a VSAM cluster; you must use it—you cannot create VSAM with JCL DISP=NEW.
• Specify one organization: INDEXED (KSDS), NONINDEXED (ESDS), NUMBERED (RRDS), or LINEAR (LDS).
• NAME, RECORDSIZE, and space allocation (CYLINDERS, TRACKS, or RECORDS) are required in practice; KEYS is required for KSDS.
• FREESPACE(ci-percent ca-percent) reserves space for inserts in KSDS and RRDS.
• DATA and INDEX clauses are optional; use them to name the data and index components explicitly.
• RECORDSIZE and KEYS cannot be changed after define; use a new cluster and REPRO to change them.

Explain Like I'm Five

DEFINE CLUSTER is like ordering a new filing cabinet. You tell the system what kind of cabinet (with keys, or just in order, or with numbered drawers), how big the folders (records) are, how much space you want, and what to call it. The system finds space on the disks, writes down the name in the catalog, and from then on you can open that cabinet and put in or read data. You cannot change the folder size or the key type later—you would have to get a new cabinet and move the data.

Test Your Knowledge