DEFINE CLUSTER (for Experienced)


DEFINE CLUSTER command creates new VSAM datasets (i.e., ESDS, KSDS, RRDS and LDS).

DEFINE CLUSTER to define attributes for the cluster as a whole and the DATA and INDEX components of the cluster. The parameters can specify with the Cluster, DATA, and INDEX components.

High-level Syntax -


//JOBNAME  JOB job-card-parameters
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (parameters) 
	 [DATA(parameters)]
	 [INDEX(parameters)]
	 [CATALOG(subparameters)]
/*

Low-level (Detail) Syntax -


//JOBNAME  JOB job-card-parameters
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER
 	  (NAME(entryname)
 	  {CYLINDERS(primary[ secondary])|
 	   KILOBYTES(primary[ secondary])|
 	   MEGABYTES(primary[ secondary])|
 	   RECORDS(primary[ secondary])|
 	   TRACKS(primary[ secondary])}
 	  VOLUMES(volser[ volser...])
 	  [BUFFERSPACE(size)]
 	  [CONTROLINTERVALSIZE(size)]
 	  [DATACLASS(class)]
 	  [ERASE|NOERASE]
 	  [FILE(ddname)]
 	  [FREESPACE(CI-percent[ CA-percent]|0 0)]
 	  [INDEXED|LINEAR|NONINDEXED|NUMBERED]
 	  [KEYS(length offset| 64 0]
 	  [MODEL(entryname[ catname])]
 	  [OWNER(ownerid)]
 	  [RECORDSIZE(average maximum)]
 	  [REUSE|NOREUSE]
 	  [SHAREOPTIONS(crossregion[ crosssystem]|1 3)]
 	  [SPANNED|NONSPANNED]
 	  [SPEED|RECOVERY]
 	  [TO(date)|FOR(days)]
 	  [WRITECHECK|NOWRITECHECK])
 	[DATA (
 	  [NAME(entryname)]
 	  {CYLINDERS(primary[ secondary])|
 	   KILOBYTES(primary[ secondary])|
 	   MEGABYTES(primary[ secondary])|
 	   RECORDS(primary[ secondary])|
 	   TRACKS(primary[ secondary])}
 	  [VOLUMES(volser[ volser...])]
 	  [BUFFERSPACE(size)]
 	  [CONTROLINTERVALSIZE(size)]
 	  [ERASE|NOERASE]
 	  [FILE(ddname)]
 	  [FREESPACE(CI-percent[ CA-percent])]
 	  [KEYS(length  offset)]
 	  [MODEL(entryname[ catname])]
 	  [OWNER(ownerid)]
 	  [RECORDSIZE(average  maximum)]
 	  [REUSE|NOREUSE]
 	  [SHAREOPTIONS(crossregion[ crosssystem])]
 	  [SPANNED|NONSPANNED]
 	  [SPEED|RECOVERY]
 	  [WRITECHECK|NOWRITECHECK])]
 	[INDEX (
 	  [NAME(entryname)]
 	  {CYLINDERS(primary[ secondary])|
 	   KILOBYTES(primary[ secondary])|
 	   MEGABYTES(primary[ secondary])|
 	   RECORDS(primary[ secondary])|
 	   TRACKS(primary[ secondary])}
 	  [VOLUMES(volser[ volser...])]
 	  [CONTROLINTERVALSIZE(size)]
 	  [FILE(ddname)]
 	  [MODEL(entryname [ catname])]
 	  [OWNER(ownerid)]
 	  [REUSE|NOREUSE]
 	  [SHAREOPTIONS(crossregion[ crosssystem])]
 	  [WRITECHECK|NOWRITECHECK])]
 	[CATALOG(catname)]
/*
Note!
  • 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.

Parameters


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

Mandatory Parameters


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.
  • The set of sub-parameters for the CLUSTER parameter is enclosed with parenthesis ().

Short Description: CL

NAME (entryname)


  • NAME parameter specifies/used to define the cluster's entry name or the name of each of its components.
  • The entryname is unique to the cluster and is not shared with the cluster's (DATA and INDEX) components.
  • NAME (entryname) is mandatory and should be specified for the Cluster component.
  • entrynames are different for the cluster, its data component, and its index component.
  • The DATA and INDEX components should be named individually to set the separate names for each component.
  • The name is automatically generated if no name is specified for the DATA or INDEX component.
  • The name for a VSAM dataset can be up to 44 alphanumeric characters.

CYLINDERS (primary[ secondary])
KILOBYTES (primary[ secondary])
MEGABYTES (primary[ secondary])
RECORDS (primary[ secondary])
TRACKS (primary[ secondary])


  • The above 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.
  • A MEAGBYTES (MB) parameter specifies that the memory allocation is always done in cylinders.
  • A KILOBYTES (KB) and RECORDS (REC) parameters specifies that the memory allocation is always done in tracks.
  • If the KILOBYTES keyword is coded, the memory allocated in tracks that is equal to the number of KILOBYTES specified. Similarly, for MEGABYTES.
  • If the RECORDS keyword is coded, the memory allocated in tracks that is equal to containing the given number of records.
  • Regardless of the allocation type, The CA (control area) size is calculated based on the smaller of the two allocation quantities (primary or secondary) but not based on the allocation type.
  • A CA is never greater than a single-cylinder; it might be smaller than a cylinder, depending on the quantity and type of allocation.

When multiple volumes are used for a dataset -

  • The first volume is defined as the primary volume. The initial allocation of a dataset is on the primary volume.
  • A dataset's secondary space allocation (if defined) is the space allocated when the primary space is filled, and the dataset needs additional space on the same volume.
  • The space is divided between the DATA and INDEX components. The calculations are based on the control interval size, record size, device type, and other data set attributes.
  • The total space specified is allocated to the DATA component. An additional amount of space is allocated to the INDEX component, depending on control interval size, record size, device type, and other data set attributes.

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.
  • VOLUMES must be specified either as a CLUSTER parameter or as a parameter of both DATA and INDEX.
  • Volumes are allocated to the dataset or used by the dataset in the same order they specify.
  • If there is not enough space on the volume as specified, the allocation is unsuccessful.

Short Description: VOL

Optional Parameters


BUFFERSPACE (size)


  • BUFFERSPACE parameter is used to specify the minimum space for buffers.
  • The VSAM uses the buffer size to calculate the DATA and INDEX component's control interval sizes.
  • Suppose BUFFERSPACE is not provided and the data is key sequenced. In that case, VSAM attempts to get enough space to contain two DATA component CIs and one INDEX component CI.

size

The size should be enough (equal or greater than) to contain two DATA component CIs and one INDEX CI if the data is key sequenced.

Short Description: BUFSP or BUFSPC

CONTROLINTERVALSIZE (size)


  • CONTROLINTERVALSIZE parameter specifies the size of the control interval for the cluster or component.
  • If CONTROLINTERVALSIZE is specified at the cluster level, it applies to the component where no CONTROLINTERVALSIZE has been specified.
  • The size of the control interval depends on the maximum size of the data records and the amount of buffer space provided in the cluster definition.
  • If CONTROLINTERVALSIZE is not coded, VSAM determines the size of control intervals.

size

Specifies cluster DATA and INDEX components CI size.

Short Description: CISZ or CNVSZ

DATACLASS(class)


  • Specifies allocation attributes for the new datasets. The storage administrator provides the data class name (1-8 characters).

Short Description: DATACLAS

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

ERASE

ERASE parameter specifies the cluster each component memory erased (overwritten with binary zeros) when its catalog entry is deleted.

Short Description: ERAS

NOERASE

NOERASE parameter specifies that each cluster component memory is not to erased and left as it is.

Short Description: NERAS

FILE (ddname)


  • FILE parameter names the DD statement that identifies and allocates the volumes specified by the VOLUMES keyword.
  • If more than one volume is specified, all volumes must be the same device type.
  • If the FILE parameter is not specified, an attempt is made to allocate the required volumes dynamically.
  • FILE parameter should specify only when the UNIQUE parameter is specified.
  • A FILE parameter should be specified for every unique component individually or on the cluster level.
  • If both components (DATA and INDEX) are unique and reside on the same volume, the FILE parameter should be specified for both DATA and INDEX.

Restriction -

When FILE refers to multi-volume of the same device type, the volumes that are represented by the DD statement cannot be concatenated.

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.
  • CI-percent is a percentage of the space to be kept aside for adding new records and updating existing records with a length change.
  • CI-percent and CA-percent should be equal to, or less than, 100 and can be expressed in decimal (n), hexadecimal (X'n'), or binary (B‘n’) form.
  • If FREESPACE(100 100) is specified, the CIs and CAs are not left empty.
  • FREESPACE is applicable for KSDS and VRDS datasets and ignored for all other types of clusters.

Short Description: FSPC

Default: FREESPACE (0 0)

INDEXED | LINEAR | NONINDEXED | NUMBERED


  • The above parameter is used to specify the type of data organization for the cluster.
  • If the parameter is not specified, the default value is INDEXED.
  • The file organization should be specified while defining a cluster.
  • The valid file organizations are INDEXED (KSDS), NONINDEXED (ESDS), NUMBERED (RRDS), or LINEAR (LDS).
  • Linear dataset clusters are treated as ESDS clusters that should be processed using control interval access.

Default: INDEXED

INDEXED

  • The INDEXED parameter specifies that the cluster is defined for the key-sequenced dataset (KSDS).
  • If the INDEXED keyword is specified, an index component is automatically defined and cataloged.
  • The data records are accessed using a key or relative-byte address (RBA).

Short Description: IXD

LINEAR

  • The LINEAR parameter specifies that the cluster is defined for the linear dataset (LDS).

Short Description: LIN

NONINDEXED

  • The NONINDEXED parameter specifies that the cluster is defined for the entry-sequenced dataset (ESDS).

Short Description: NIXD

NUMBERED

  • The NUMBERED parameter specifies that the cluster is defined for the relative record dataset (RRDS).

Short Description: NUMD

KEYS (length offset | 64 0)


  • KEYS parameter specifies the information about the primary key field in the data record.

length offset

  • Specifies key length and its displacement (in bytes) positions from the offset of the record.
  • The sum of length plus offset cannot exceed the length of the shortest record.

Default: KEYS (64 0)

MODEL (entryname[ catname])


  • The MODEL parameter is used to specify an already-defined cluster entry is to be used as a model for the entry being built.
  • The entry using as a model should be of the same entry type as the new entry being built.

entryname

  • Specifies the name of the cluster or component entry to be used as a model.

catname

  • Names the model entry's catalog.

OWNER (ownerid)


  • specifies the cluster's owner.
  • If the dataset is created in TSO/E, the TSO/E user's userid becomes the ownerid.

RECORDSIZE (average maximum|default)


  • RECORDSIZE specifies the average and maximum lengths in bytes of the records in the DATA component.
  • The minimum record size is 1 byte.
  • RECORDSIZE can be given as a parameter of either CLUSTER or DATA.
  • This parameter overrides the LRECL specification on the DATACLASS parameter. MAXLRECL = CI/CA * (CISZ - 10).

Short Description: RECSZ

REUSE | NOREUSE


  • These parameters specify whether the cluster can open again and again for reuse.

REUSE

  • Specifies that the cluster can open again and again for usage.

Short Description: RUS

NOREUSE

  • Specifies that the cluster cannot be opened again as a new cluster.

Short Description: NRUS

SHAREOPTIONS (crossregion[ crosssystem]|1 3)


  • SHAREOPTIONS parameter specifies the sharing options of how a component or cluster can share among users.
  • The value of SHAREOPTIONS is assumed to be (3,3) when the dataset is accessed in VSAM.
crossregion

crossregion specifies the amount of sharing allowed among regions within the same system or multiple systems.

OPT 1

  • Any number of users can access the dataset for reading, or one user can access it for writing.

OPT 2

  • Any number of users can access the dataset for reading, and one user can access it for writing.

OPT 3

  • Any number of users can fully share the dataset. Each user is responsible for maintaining both read and write integrity for the data the program is accessing.

OPT 4

  • Any number of users can fully share the dataset. VSAM refreshes the buffers for each request that is used for direct processing.
crosssystem

crosssystem option specifies the amount of sharing allowed among systems.

OPT 1

Reserved

OPT 2

Reserved

OPT 3

  • OPT 3 specifies the dataset is fully shared. With this option, each user is responsible for maintaining both read and write integrity for the data that the user's program is accessing.

OPT 4

  • OPT 4 specifies that the dataset is fully shared. VSAM refreshes the buffers for each request that is used for direct processing.

Short Description: SHR

Default: SHR (1 3)

SPANNED | NONSPANNED


  • Specifies whether a data record is allowed to save beyond the CI boundaries.

SPANNED

  • Specifies that the maximum record length is larger than a CI size and the record is stored on more than one control interval.

Short Description: SPND

NONSPANNED

  • Indicates that the record is stored in one CI. VSAM selects a CI size that accommodates the largest record.

Short Description: NSPND

SPEED | RECOVERY


  • These parameters specify whether the data component control areas are to be preformatted duwing the loading.
  • This parameter is only considered during the actual loading (creation) of a dataset.

SPEED

  • The SPEED parameter does not preformat the DATA component's space.

Default: RECOVERY

RECOVERY

  • The RECOVERY parameter specifies that does preformat the data component's space prior to writing the data records.
  • RECOVERY is a way to verify used storage for each CA on the device before the data is written.

Short Description: RCVY

TO (date) | FOR (days)


  • This parameter specifies the retention period for the cluster being defined.
  • If neither TO nor FOR is used, the cluster can be deleted at any time.

TO (date)

  • TO parameter specify the date up to which to keep the cluster before it is allowed to be deleted.
  • The date is given in the form [yy]yyddd, in which yyyy is a four-digit year, yy is a two-digit year, and ddd is a three-digit day of the year (001 through 366).

FOR (days)

  • FOR parameter shows the number of days to keep the cluster being defined.
  • The maximum number is 9999.
  • If the number is 0 through 9998, the cluster is retained for the number of days.
  • If the number is 9999, the cluster is retained indefinitely.

WRITECHECK | NOWRITECHECK


These parameters indicate the write check whether the cluster or component is to be reviewed when a record is written into it.

WRITECHECK

  • WRITECHECK parameter shows that a record is written and then read without data transfer to test for the written data condition.

Short Description: WCK

NOWRITECHECK

  • NOWRITECHECK parameter specifies that the cluster or component is not to be checked by a write check.

Short Description: NWCK

CATALOG (catname)


  • Specifies the catalog name in which the cluster is to be defined.

Short Description: CAT

Examples -


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

Code -

----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
***************************** 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     )          -                                             
  DATA(NAME(MATEPK.TEST.ESDS.DATA))                                     
/*                                                                      
**************************** 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     )          -                                                     
  DATA(NAME(MATEPK.TEST.ESDS.DATA))                                             
IDC0508I DATA ALLOCATION STATUS FOR VOLUME DEVHD4 IS 0                          
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0                       
                                                                                
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 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.