DEFINE CLUSTER: Full Syntax Reference

This page is a full syntax reference for the IDCAMS DEFINE CLUSTER command. It lists every major parameter you can use when defining a VSAM cluster (KSDS, ESDS, RRDS, or LDS), what each parameter does, how it affects the cluster, and where it can be specified. Use it alongside the DEFINE CLUSTER overview page when you need the complete picture—required vs optional parameters, space allocation options, record and key attributes, sharing and catalog options, and the DATA and INDEX subparameters.

Why a Full Syntax Reference?

DEFINE CLUSTER has many parameters. Some are required (NAME, organization, RECORDSIZE, space; KEYS for KSDS). Others control space (CYLINDERS, TRACKS, RECORDS, FREESPACE), sharing (SHAREOPTIONS), placement (VOLUMES), security (READPW, UPDATEPW), retention (FOR, TO), and component names (DATA, INDEX). A full reference helps you choose the right combination and avoid mistakes. For example, RECORDSIZE and KEYS cannot be changed after the cluster is defined; getting them right the first time matters. Similarly, FREESPACE affects how often VSAM splits control intervals and control areas when you insert records, so understanding the syntax helps you set it correctly.

Complete Command Form

The command has this general shape. Cluster-level parameters come first, then optionally the DATA(...) clause, and for KSDS the INDEX(...) clause. Continuation is with a hyphen at end of line. Parameters can be in any order within their section.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
  DEFINE CLUSTER ( -
    NAME(cluster-name) -
    INDEXED | NONINDEXED | NUMBERED | LINEAR -
    RECORDSIZE(min max) -
    [ KEYS(length offset) ]           /* required for INDEXED */ -
    [ FREESPACE(ci-percent ca-percent) ] -
    CYLINDERS(primary [secondary]) | TRACKS(primary [secondary]) | RECORDS(primary [secondary]) -
    [ SHAREOPTIONS(cross-region cross-system) ] -
    [ VOLUMES(volser [...]) ] -
    [ BUFFERSPACE(n) ] -
    [ REUSE | NOREUSE ] -
    [ UNIQUEKEY | NONUNIQUEKEY ]      /* KSDS only */ -
    [ CATALOG(catname[/password]) ] -
    [ READPW(pwd) ] [ UPDATEPW(pwd) ] -
    [ FOR(days) | TO(date) ] -
    [ other... ] ) -
  [ DATA ( [ NAME(...) ] [ CISZ(...) ] [ space ] [ VOLUMES(...) ] ... ) ] -
  [ INDEX ( [ NAME(...) ] [ CISZ(...) ] [ space ] [ VOLUMES(...) ] ... ) ]   /* KSDS only */
 

Required Parameters

You must specify the cluster name, the organization type, record size, and space. For a KSDS you must also specify the key. Everything else has defaults or is optional.

Space Allocation Parameters

Space can be specified at the cluster level (applies to the whole cluster; for a KSDS the system divides it between data and index) or inside DATA(...) and INDEX(...) for separate control. You use one of CYLINDERS, TRACKS, or RECORDS. Primary is the initial allocation; secondary is the amount added each time the dataset is extended. If you omit secondary, behavior is system-dependent (some systems allow no extension).

CYLINDERS is typical for large production files. TRACKS is useful for smaller files or when you need finer granularity than a full cylinder. RECORDS is useful when you want to express allocation in terms of how many records you expect; the system converts to tracks/cylinders using RECORDSIZE and control interval size. You can specify different space in DATA and INDEX for a KSDS—for example DATA CYLINDERS(100 50) and INDEX CYLINDERS(2 1)—so the index does not take space from the data component.

FREESPACE

FREESPACE(ci-percent ca-percent) reserves a percentage of each control interval and each control area for inserts. It applies to KSDS and RRDS. The first value is the percentage of each CI left free; the second is the percentage of each CA left as free CIs. For example FREESPACE(20 10) reserves 20% of each CI and 10% of each CA. Higher values reduce how often VSAM must split CIs and CAs when you insert records, but they also mean less data per CI (more I/O for full sequential scans). ESDS does not use FREESPACE in the same way because it only appends; LDS has no record structure. If you omit FREESPACE, the default is often (0 0), which can lead to many splits in a growing KSDS.

Record and Key Parameters

RECORDSIZE and KEYS define the record layout. These cannot be changed after the cluster is defined. UNIQUEKEY/NONUNIQUEKEY and REUSE/NOREUSE control key behavior and whether the cluster can be reused without delete/redefine.

For RECORDSIZE, fixed-length records are the norm for KSDS and RRDS (e.g. RECORDSIZE(80 80)). Variable-length records use a range (e.g. RECORDSIZE(100 500)); the actual length is stored in a prefix. For KEYS, the offset is 0-based: KEYS(10 0) means the key starts at the first byte of the record. The key must lie entirely within the record (offset + length ≤ record length). UNIQUEKEY means no two records can have the same key; NONUNIQUEKEY allows duplicates, and retrieval by key returns records in RBA order.

Sharing, Volumes, and Buffers

SHAREOPTIONS(cross-region cross-system) controls whether multiple address spaces or systems can open the cluster and whether they can update it. (1 3) allows read-only sharing; (2 3) allows read/write sharing and is common for batch; (3 3) means no sharing (exclusive). VOLUMES is used when you need the cluster on specific DASD volumes; omit it when SMS or the system chooses the volume. BUFFERSPACE is a hint for buffer allocation; many installations leave it omitted.

Catalog, Passwords, and Retention

CATALOG is needed only when the cluster is to be cataloged in a user catalog that is not the default. READPW and UPDATEPW provide simple password protection; without the correct password, open fails. FOR and TO set retention; DELETE without PURGE will not remove the object until the retention period has passed.

DATA and INDEX Subparameters

The DATA(...) clause applies to the data component; the INDEX(...) clause applies to the index component (KSDS only). Inside them you can override or supply component-specific attributes. Common subparameters are NAME (component name), space (CYLINDERS, TRACKS, RECORDS), CISZ (control interval size), and VOLUMES.

If you omit the DATA and INDEX clauses, IDCAMS generates default component names (cluster-name.DATA and cluster-name.INDEX). Specifying NAME(...) inside DATA and INDEX lets you control those names. Specifying space inside DATA and INDEX lets you allocate different amounts to data and index, which is recommended for KSDS so the index does not consume more space than it needs.

Example: Full KSDS Definition

This example uses many of the parameters discussed above: NAME, INDEXED, RECORDSIZE, KEYS, FREESPACE, space at DATA and INDEX, SHAREOPTIONS, REUSE, and explicit DATA and INDEX names.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
  DEFINE CLUSTER ( -
    NAME(MY.APPL.PROD.KSDS) -
    INDEXED -
    RECORDSIZE(200 200) -
    KEYS(20 0) -
    UNIQUEKEY -
    FREESPACE(20 10) -
    SHAREOPTIONS(2 3) -
    REUSE -
    VOLUMES(MYVOL1) -
    FOR(30)) -
  DATA ( -
    NAME(MY.APPL.PROD.KSDS.DATA) -
    CYLINDERS(50 25) -
    CISZ(4096)) -
  INDEX ( -
    NAME(MY.APPL.PROD.KSDS.INDEX) -
    CYLINDERS(2 1))
 

The cluster is a KSDS with 200-byte fixed records and a 20-byte unique key at offset 0. FREESPACE(20 10) reserves 20% of each CI and 10% of each CA. SHAREOPTIONS(2 3) allows read/write sharing. REUSE allows the file to be reloaded without delete/redefine. The data component gets 50 cylinders primary and 25 secondary with 4 KB CIs; the index gets 2 cylinders primary and 1 secondary. Retention is 30 days.

Parameter Order and Defaults

Parameters can appear in any order within the DEFINE CLUSTER parentheses and within the DATA and INDEX clauses. IDCAMS parses by keyword, not position. Some parameters have defaults: NOREUSE, UNIQUEKEY, SHAREOPTIONS often defaults to (2 3) or (1 3) depending on the environment, and FREESPACE defaults to (0 0) if omitted. If you omit the DATA and INDEX clauses entirely, the cluster is still created with default component names and space is taken from the cluster-level allocation. For a KSDS, that space is divided between data and index; the split is system-determined and may not match what you want, so specifying DATA and INDEX with explicit space is recommended for production.

What You Cannot Change Later

RECORDSIZE, KEYS (length and offset), and the organization type (INDEXED, NONINDEXED, NUMBERED, LINEAR) are fixed at define time. The ALTER command can change many attributes—FREESPACE, SHAREOPTIONS, some space and buffer settings—but it cannot change record size, key definition, or organization. To change those you must define a new cluster with the desired attributes and copy the data (e.g. with REPRO) from the old cluster to the new one, then switch applications to the new name and optionally delete the old cluster.

Organization Types: Quick Comparison

• INDEXED: KSDS. Requires KEYS. Has data and index components. Use for keyed access and sequential in key order.
• NONINDEXED: ESDS. No KEYS. Data component only. Use for append-only, RBA or sequential access.
• NUMBERED: RRDS. Data component only. Fixed-length records in slots; access by RRN. FREESPACE optional.
• LINEAR: LDS. Byte-addressable; no record structure. Used by products like Db2; not for normal record I/O.

Step-by-Step: Defining a New KSDS

1. Choose the cluster name (1–44 characters, valid TSO naming).
2. Decide organization: INDEXED for KSDS.
3. Set RECORDSIZE(min max)—same value twice for fixed-length.
4. Set KEYS(length offset) for the primary key.
5. Choose space: CYLINDERS, TRACKS, or RECORDS with primary (and usually secondary). Prefer specifying in DATA and INDEX separately for KSDS.
6. Set FREESPACE(ci-percent ca-percent) if the file will grow after load (e.g. 20 10).
7. Set SHAREOPTIONS (e.g. 2 3 for batch read/write sharing).
8. Add VOLUMES, REUSE, passwords, or retention if required by your shop.
9. Run IDCAMS with the DEFINE CLUSTER command; fix any syntax or catalog errors.
10. Load data (e.g. REPRO) and verify with LISTCAT or a test program.

Explain Like I'm Five

DEFINE CLUSTER is like filling out an order form for a new filing system. You have to say what it's called (NAME), what kind it is (with keys, or in order, or numbered drawers, or just a big box), how big each folder is (RECORDSIZE), and how much space you want (CYLINDERS or TRACKS). If it's the kind with keys, you have to say how long the key is and where it is (KEYS). Then you can add extra options: how much empty space to leave for new folders (FREESPACE), who can use it at the same time (SHAREOPTIONS), and whether you can wipe it and reuse it without throwing it away (REUSE). The full syntax reference is the complete list of every box you can fill on that form.

Test Your Knowledge