DEFINE CLUSTER creates and catalogs a VSAM data set. The operands specify its organization, record size, space, key, sharing, and component attributes. For example, INDEXED KEYS(10 0) defines a KSDS with a 10-byte key beginning at the first byte of each record.
VSAM DEFINE CLUSTER JCL
Run Access Method Services through PGM=IDCAMS. Put the DEFINE command in SYSIN and send command output to SYSPRINT.
//DEFVSAM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE CLUSTER (NAME(APP.CUSTOMER.KSDS) -
INDEXED -
KEYS(10 0) -
RECORDSIZE(100 200) -
CYLINDERS(5 2) -
FREESPACE(10 10) -
SHAREOPTIONS(2 3)) -
DATA (NAME(APP.CUSTOMER.KSDS.DATA) -
CONTROLINTERVALSIZE(4096)) -
INDEX (NAME(APP.CUSTOMER.KSDS.INDEX))
/*This job defines the catalog entries and allocates the cluster. It does not load application records. Load data in a later step, commonly with REPRO, after the DEFINE step succeeds.
How the command is structured
IBM documents three scopes in the command: cluster parameters, optional DATA parameters, and optional INDEX parameters. A cluster-level value normally applies to the components when the same attribute is not specified at component level. A component-level value can override the corresponding cluster attribute.
DEFINE CLUSTER (cluster-parameters) -
DATA (data-component-parameters) -
INDEX (index-component-parameters)A KSDS has both data and index components. ESDS and RRDS definitions have a data component but do not need a KSDS index component. Explicit component names are useful for catalog inspection, but follow the naming rules used at your site.
Important DEFINE CLUSTER parameters
| Parameter | Purpose | What to check |
|---|---|---|
NAME | Names the cluster or a component. | Use a valid high-level qualifier and confirm the target catalog. |
INDEXED | Defines a key-sequenced data set (KSDS). | Supply the correct key length and offset. |
NONINDEXED | Defines an entry-sequenced data set (ESDS). | Do not add a KSDS KEYS operand. |
NUMBERED | Defines a relative record data set (RRDS). | Match fixed or variable record requirements to the program. |
RECORDSIZE(avg max) | Sets average and maximum logical record lengths. | Equal values describe fixed-length records; different values describe variable-length records where supported. |
KEYS(length offset) | Sets the KSDS key length and its zero-based displacement. | Reconcile the offset with a copybook that may show positions starting at 1. |
CYLINDERS(primary secondary) | Allocates primary space and an extension amount. | Use measured record counts and growth, not copied sample numbers. |
FREESPACE(ci ca) | Reserves free space percentages in control intervals and control areas. | Balance expected inserts against unused space. |
CONTROLINTERVALSIZE | Requests a control interval size. | Use storage and performance guidance approved for the workload. |
SHAREOPTIONS(xregion xsystem) | Declares permitted sharing across regions and systems. | Match application serialization and site policy; it is not a substitute for integrity controls. |
REUSE or NOREUSE | Controls whether the cluster can be reset and reused as an empty data set. | Use the option expected by the load and retention process. |
KSDS DEFINE CLUSTER example
A KSDS uses INDEXED and a key definition. In KEYS(10 0), 10 is the key length and 0 is the displacement from the beginning of the record. A COBOL field described in positions 1 through 10 therefore maps to offset 0.
DEFINE CLUSTER (NAME(TEST.ORDER.KSDS) -
INDEXED -
KEYS(10 0) -
RECORDSIZE(120 240) -
CYLINDERS(3 1) -
FREESPACE(10 10)) -
DATA (NAME(TEST.ORDER.KSDS.DATA)) -
INDEX (NAME(TEST.ORDER.KSDS.INDEX))The program's key field, file definition, and record layout must agree with these attributes. Review the related COBOL indexed file organization guide when the cluster is used by COBOL.
ESDS DEFINE CLUSTER example
An ESDS stores records in entry sequence. Define it with NONINDEXED; omit KEYS and the KSDS index component.
DEFINE CLUSTER (NAME(TEST.EVENT.ESDS) -
NONINDEXED -
RECORDSIZE(80 200) -
CYLINDERS(2 1)) -
DATA (NAME(TEST.EVENT.ESDS.DATA))Choose an ESDS when arrival order and sequential processing fit the application. For a broader comparison, see when to use KSDS, ESDS, RRDS, and LDS.
RRDS DEFINE CLUSTER example
An RRDS addresses a record by relative record number. This fixed-length example uses NUMBERED and equal average and maximum record sizes:
DEFINE CLUSTER (NAME(TEST.TABLE.RRDS) -
NUMBERED -
RECORDSIZE(200 200) -
RECORDS(5000 500)) -
DATA (NAME(TEST.TABLE.RRDS.DATA))IBM also documents variable-length RRDS definitions, where NUMBERED is paired with different average and maximum record lengths. Confirm that the chosen organization and record format match the application before allocating the data set.
SMS-managed and non-SMS-managed allocation
An SMS-managed definition can use STORAGECLASS, DATACLASS, and MANAGEMENTCLASS, with ACS routines and class definitions supplying or overriding attributes. A non-SMS example may name one or more volumes directly with VOLUMES. Do not mix assumptions from one environment into the other.
When to specify DATA and INDEX
Specify DATA(...) or INDEX(...) when a component needs its own name or an attribute that differs from the cluster-level value. For a KSDS, this can separate data and index allocation choices. If an attribute is stated at both levels, verify which value takes precedence before relying on the result.
Use VSAM control interval concepts before selecting a control interval size or free-space percentage. These values affect storage and update behavior and should be chosen for the record and access pattern.
Verify the cluster after definition
A zero return code is only the first check. Read all IDCAMS messages in SYSPRINT, then inspect the catalog entry with LISTCAT.
//CHKVSAM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
LISTCAT ENTRIES(TEST.ORDER.KSDS) ALL
/*Confirm the cluster name, organization, component names, record size, key information, allocation, and catalog. The broader VSAM IDCAMS commands guide covers REPRO, LISTCAT, DELETE, and return-code handling without duplicating the definition detail on this page.
Common DEFINE CLUSTER errors
| Symptom | Likely check |
|---|---|
| The data set is already cataloged | Run LISTCAT against the exact cluster name and confirm whether the job should define a new object. |
| KSDS key does not match the program | Check key length, zero-based offset, copybook position, and uniqueness. |
| Records fail after the cluster is loaded | Compare actual logical record lengths with RECORDSIZE. |
| Allocation fails | Review SMS classes, volume availability, catalog alias, space units, security, and site rules. |
| Unexpected data or index attributes | Check whether a component-level value overrides the cluster value or a data class supplies an attribute. |
| Concurrent access behaves incorrectly | Review SHAREOPTIONS with the application owner and storage administrator. |
DEFINE CLUSTER checklist
- Choose one organization:
INDEXED,NONINDEXED, orNUMBEREDfor these KSDS, ESDS, and RRDS examples. - Match
RECORDSIZEto the real input and program definition. - For KSDS, verify key length, zero-based offset, and duplicate-key rules.
- Calculate space from expected records and growth.
- Use the SMS classes, volumes, and share options approved by the installation.
- Review
SYSPRINTand runLISTCAT ... ALLbefore loading data.
Related VSAM guides
Continue with VSAM concepts, the VSAM data set characteristics comparison, or the VSAM interview questions. Use the JCL utilities guide for the surrounding batch-job structure.
Official IBM references
- IBM: DEFINE CLUSTER syntax and parameters
- IBM: descriptive parameters for VSAM definitions
- IBM: KSDS and ESDS definition example
- IBM: z/OS DFSMS Using Data Sets
VSAM DEFINE CLUSTER FAQ
Which IDCAMS command creates a VSAM data set?
DEFINE CLUSTER creates and catalogs a VSAM cluster. Run IDCAMS with the command in SYSIN and review the result in SYSPRINT.
What does KEYS(10 0) mean in a VSAM definition?
It defines a 10-byte key beginning at offset zero, which is the first byte of each record. KEYS applies to a KSDS definition.
What is the difference between INDEXED, NONINDEXED, and NUMBERED?
INDEXED defines a KSDS, NONINDEXED defines an ESDS, and NUMBERED defines an RRDS. Each organization supports a different access pattern.
How do you verify a VSAM cluster after DEFINE CLUSTER?
Check the DEFINE return code and messages in SYSPRINT, then run LISTCAT ENTRIES(cluster-name) ALL to inspect the cataloged attributes and components.
A dependable definition starts with the program's real record and access requirements, not a copied allocation sample. Define, read every message, inspect the catalog entry, and only then load or open the cluster.
No comments:
Post a Comment