DEFINE CLUSTER (for Beginners)

DEFINE CLUSTER command creates new VSAM datasets (i.e., ESDS, KSDS, RRDS and LDS). The parameters can specify with the Cluster, DATA, and INDEX components.

Detailed Syntax -

//JOBNAME  JOB job-card-parameters
//SYSIN    DD *
 	  {CYLINDERS(primary[ secondary])|
 	   KILOBYTES(primary[ secondary])|
 	   MEGABYTES(primary[ secondary])|
 	   RECORDS(primary[ secondary])|
 	   TRACKS(primary[ secondary])}
 	  VOLUMES(volser[ volser...])
 	  [FREESPACE(CI-percent[ CA-percent]|0 0)]
 	  [KEYS(length offset| 64 0]
 	  [MODEL(entryname[ catname])]
 	  [RECORDSIZE(average maximum)]
 	  [SHAREOPTIONS(crossregion[ crosssystem]|1 3)]
 	[DATA (
 	[INDEX (
  • The parameters enclosed with [ ] are optional. The remaining parameters (without [ ]) are mandatory.
  • The parameters are enclosed in parentheses ( ) and are followed by other parameters separated by space for all (Cluster, DATA and INDEX) components.


The DEFINE CLUSTER command uses to create the VSAM datasets, and below are the mandatory and optional parameters.

Mandatory Parameters

Parameters Description
CLUSTER CLUSTER parameter is used to define the cluster or re-catalog cluster or cluster entry. The parameters specified with the CLUSTER keyword are applied to the whole cluster that is going to create.
Short Description: CL
NAME (entryname) NAME parameter specifies/used to define the cluster's entry name or the name of each of its components.
entrynames are different for the cluster, its data component, and its index component.
CYLINDERS (primary[ secondary])
KILOBYTES (primary[ secondary])
MEGABYTES (primary[ secondary])
RECORDS (primary[ secondary])
TRACKS (primary[ secondary])
These parameters are used to specify the amount of space allocated to the cluster in CYLINDERS (CYL), KILOBYTES (KB), MEGABYTES (MB), RECORDS (REC), or TRACKS (TRK) from the volume's available space.

primary Specifies the amount of space that should allocate initially to the cluster.
secondary Specifies an amount of space required each time when the cluster extends.

Short Description: CYL, KB, MB, REC, TRK
VOLUMES (volser[ volser...]) VOLUMES parameter specifies the volume name on which VSAM needs to be created.
Short Description: VOL

Optional Parameters

Parameters Description
CONTROLINTERVALSIZE (size) CONTROLINTERVALSIZE parameter specifies the size of the control interval for the cluster or component.
Short Description: CISZ or CNVSZ
ERASE | NOERASE These options specify whether the cluster components memory is to be erased or not erased when cluster entry in the catalog is deleted.
Default: NOERASE
Short Description: ERAS
Short Description: NERAS
FREESPACE (CI-percent[ CA-percent]|0 0) FREESPACE specifies the percentage of free space that is to be left empty in each control interval and control area when the cluster is initially loaded or after the mass insert.
Short Description: FSPC
Default: FREESPACE (0 0)
INDEXED | LINEAR | NONINDEXED | NUMBERED These parameters are used to specify the type of data organization for the cluster.
The valid file organizations are INDEXED (KSDS), NONINDEXED (ESDS), NUMBERED (RRDS), or LINEAR (LDS).
Short Description: IXD
Short Description: LIN
Short Description: NIXD
Short Description: NUMD
KEYS (length offset | 64 0) KEYS parameter specifies the information about the primary key field in the data record.
Default: KEYS (64 0)
OWNER (ownerid) Specifies the cluster's owner.
RECORDSIZE (average maximum|default) RECORDSIZE specifies the average and maximum lengths in bytes of the records in the DATA component.
Short Description: RECSZ
REUSE | NOREUSE These parameters specify whether the cluster can open again and again for reuse.
Short Description: RUS
Short Description: NRUS
SPEED | RECOVERY These parameters specify whether the data component control areas are to be preformatted duwing the loading.
Short Description: RCVY
TO (date) | FOR (days) These parameter specifies the retention period for the cluster being defined.
Short Description: RCVY
WRITECHECK | NOWRITECHECK These parameters indicate the write check whether the cluster or component is to be reviewed when a record is written into it.
Short Description: WCK
Short Description: NWCK

Examples -

Requirement - Create ESDS with fixed-length records of size 47 bytes.

Code -

***************************** Top of Data ******************************
//MATEPKE JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//* DEFINE VSAM FIXED-LENGTH ESDS CLUSTER                               
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD SYSOUT=*                                                  
//SYSIN    DD  *                                                        
  DEFINE CLUSTER(NAME(MATEPK.TEST.ESDS)  -                              
     RECORDSIZE(47,47)    -                                             
     CYLINDERS(2,1)       -                                             
     CISZ(4096)           -                                             
     VOLUMES(DEVHD4)      -                                             
     NONINDEXED           -                                             
     REUSE     )          -                                             
**************************** Bottom of Data ****************************

In the above JCL, MATEPK is the userid and changes all as required.

Output -

Once the above JCL is submitted, check the MAXCC of the job for any errors. If the MAXCC is 00 or 04, ESDS successfully created.

********************************* TOP OF DATA **********************************
IDCAMS  SYSTEM SERVICES                                           TIME: 03:12:51
  DEFINE CLUSTER(NAME(MATEPK.TEST.ESDS)  -                                      
     RECORDSIZE(47,47)    -                                                     
     CYLINDERS(2,1)       -                                                     
     CISZ(4096)           -                                                     
     VOLUMES(DEVHD4)      -                                                     
     NONINDEXED           -                                                     
     REUSE     )          -                                                     
IDC0508I DATA ALLOCATION STATUS FOR VOLUME DEVHD4 IS 0                          
******************************** BOTTOM OF DATA ********************************

Verify the ESDS in 3.4 (Dataset List utility) or any File management tools.

Command ===> _____________________________________________   Scroll ===> CSR  
Command - Enter "/" to select action                  Message           Volume 
         MATEPK.TEST.ESDS                                               *VSAM* 
         MATEPK.TEST.ESDS.DATA                                          DEVHD4 
***************************** End of Data Set list ****************************

Explaining Example -

In the above example,

  • RECORDSIZE(47,47) specifies the record average length is 47, and the maximum size is 47. So the ESDS file we are creating is fixed-length.
  • CYLINDERS(2,1) specifies the primary memory allocation is 2 CYLINDERS, and secondary memory allocation is 1 CYLINDER.
  • CISZ(4096) specifies the control interval size is 4096.
  • VOLUMES(DEVHD4) specifies that allocate the ESDS on volume DEVHD4.
  • NONINDEXED parameter specifies the file is to create ESDS.
  • REUSE specifies the memory can reuse immediately once the file gets deleted.