IDCAMS - DEFINE CLUSTER Command

• DEFINE CLUSTER command is used to create VSAM or non-VSAM objects like KSDS, ESDS, RRDS, LDS, GDG, VSAMSPACE etc.
• The most general syntax of DEFINE CLUSTER command is:-
  DEFINE CLUSTER (parameters) - [DATA(parameters)] - [INDEX(parameters)] - [CATALOG(subparameters)]
• Let’s have look at the complete Syntax (with most important parameters only)
  
  Note: - In below syntax, text written inside box bracket [] indicates the optional parameters/sub-parameters, text written in Italic represents the value which user has to code, pipe character ‘|’ is used to indicate either left or right parameter/sub parameter can be used(but not both).
  
  
  DEFINE CLUSTER - (NAME(vsam-file-name) - ( CYLINDERS ( primary[ secondary] ) | - RECORDS ( primary[ secondary] ) | - TRACKS ( primary[ secondary] ) | - KILOBYTES ( primary[ secondary] ) | - MEGABYTES ( primary[ secondary] ) ) - VOLUMES ( volser1 [volser2...] ) - [BUFFERSPACE ( size ) ] - [CONTROLINTERVALSIZE ( size ) ] - [ERASE | NOERASE] - [FREESPACE ( CI-percent [CA-percent] | 0 0 ) ] - [INDEXED | NONINDEXED | NUMBERED | LINEAR] - [KEYS ( length offset | 64 0 ) ] - [RECORDSIZE ( average maximum ) ] - [REUSE | NOREUSE] - [SHAREOPTIONS(cross-region[ cross-system] | 1 3) ] - [SPANNED|NONSPANNED] - [SPEED | RECOVERY] - [TO (date) | FOR (days) ] ) - [ DATA - ([NAME(vsam-file-name.data)]) ] - [ INDEX - ([NAME(vsam-file-name.index)]) ] - [CATALOG(catname[/password])]
• Parameters coded at CLUSTER level apply to the whole CLUSTER
• Parameters coded at DATA level apply only to DATA component and parameters coded at INDEX level apply only to INDEX component.
• Let’s discuss the meaning of each parameters mentioned in above Code snippet
• DEFINE CLUSTER
  • This command is used to create and name a VSAM cluster. Parameters can be coded along with this command to specify attributes of VSAM cluster
• NAME
  • NAME parameter is used to specify the name of VSAM cluster
  • When the DATA and INDEX parameter are coded to create the DATA and INDEX component the NAME parameter is coded for them too. If these parameters are omitted then VSAM tries to append .DATA and .INDEX as appropriate making sure dataset name is still staying within the 44 characters limit
• Space Allocation
  • It is used to specify the size of cluster.
  • Space may be requested in terms of Cylinders, Tracks, Records, Kilo Bytes or Mega Bytes.
  • Both a primary and secondary quantity can be specified.
  • The primary quantity is the amount of space initially allocated to the cluster.
  • The secondary quantity is the amount of additional space allocated when the available space is fully used and an additional record is added to the cluster. The number of times the cluster can be expanded (using secondary amount of space allocated) depends on several factors, but can be maximum of 123 times.
  • The RECORD method of allocation space is suggested, as in this case, AMS calculates the appropriate amount of space for the type of DASD on which the cluster is allocated.
• VOLUMES
  • VOLUMES parameter is used to specify one or more direct access storage volumes on which space will be allocated for the cluster.
• BUFFERSPACE or BUFSP
  • By default, VSAM allocates One Index buffer and Two Data buffers(one for data processing and another one for potential Split activity)
  • Using BUFFERSPACE parameter we can override these default values i.e. using BUFFERSPACE parameter we can specify the amount of storage (in bytes) required to process the one CI worth of data
  • Syntax: BUFFERSPACE (size-in-bytes)
  • For sequential processing, more number of Data buffers should be allocated.
  • For random processing, more number of Index buffer should be allocated.
  • For dynamic processing, more number data buffer and index buffer should be specified considering the ratio of sequential and random access planned
• CONTROLINTERVALSIZE or CISZ
  • It is used to specify the size of Control Interval (CI)
  • Syntax:- CONTROLINTERVALSIZE ( size )
  • The size is specified in terms of bytes
  • Should be multiple of 512 or 2048 bytes, depending on length of the record. Size can range from 512 to 32,768 bytes
  • If records are of 8192 bytes or less, the CISZ must be multiple of 512 bytes, but if records size is more than 8192 bytes, the CISZ must be multiple of 2048 BYTES
  • If the size is not a multiple of the appropriate value, AMS rounds the size up to the next appropriate multiple.
• ERASE | NOERASE
  • They are mutually exclusive i.e. either ERASE or NOERASE can be coded
  • ERASE parameter is used to specify that VSAM should overwrite sensitive data with binary zeroes when the cluster is deleted
  • NOERASE is default and it means that on cluster deletion data will not be overwritten with binary zeroes
  • We can code ERASE parameter at both CLUSTER and DATA level. When specified at Cluster level it only applies to the data component of cluster as index component contains only keys and not sensitive data.
• FREESPACE or FSPC
  • FREESPACE parameter is used to specify the percentage of free space to be reserved for the Control Interval (CI) and Control Area (CA) of the data component. This reserved free space can be used for adding new records or expanding existing variable length records.
  • Can be coded only for KSDS or variable-length RRDS
  • Syntax: FREESPACE (CI-percent CA-percent)
  • FREESPACE (0 0) is default
• INDEXED | NONINDEXED | NUMBERED | LINEAR
  • It is used to indicate type of cluster and it is mutually exclusive parameter i.e. only one of them can be used to define cluster.
  • INDEXED specifies KSDS cluster
  • NONINDEXED specifies ESDS cluster
  • NUMBERED specifies RRDS cluster
  • LINEAR specifies LDS dataset
  • Default is INDEXED
• KEYS
  • Used to specify the information about primary key of KSDS
  • Can be coded only for KSDS
  • Syntax:- KEYS (length offset)
  • Where, length specifies the length of primary key and offset specifies the primary key’s displacement in bytes from the beginning of record
  • Default is KEYS (64 0)
• RECORDSIZE or RECSZ
  • RECORDSIZE parameter is used to specify the record size.
  • Syntax: RECORDSIZE (average maximum)
  • Where, average is used to specify the average value for length of all records and maximum is used to specify the maximum value of variable length record
  • Default is RECORDSIZE (4086 4086)
  • Value for average and maximum will be same in case of fixed length records
  • Different value for average and maximum indicates that cluster contains variable length records
• REUSE | NOREUSE
  • When coded REUSE, cluster is used as a reusable cluster i.e. whenever you open the dataset in OUTPUT mode, all the records that are already exist in the dataset are deleted logically.
  • NOREUSE is the default and specifies that the cluster is not reusable.
  • This is most often used for clusters used as work datasets
• SHAREOPTIONS
  • SHAREOPTIONS parameter is used to specify how the VSAM dataset will be shared across the region and across the system
  • Syntax:- SHAREOPTIONS(cross-region cross-system)
  • Where,
    cross-region is used to indicate how dataset can be shared and accessed on a standalone system. Its value can range from 1 to 3. Description of each number will be explained below
    cross-system is used to indicate how dataset can be shared and accessed between different systems. Its value can be either 3 or 4. Description of each number is as explained in below table
  • Default value is SHAREOPTIONS(1 3)
    

    Sub_Parameter	Value	Description
    cross-region	1	Multiple Jobs can read the dataset OR only one Job can write to the dataset
    cross-region	2	Multiple Jobs can read the dataset AND one Job can write to the dataset
    cross-region cross-system	3	Multiple Jobs can read the dataset and Multiple jobs can write to dataset.
    cross-system	4	Same as Value 3. But it also forces a buffer refresh for each random access

• SPANNED | NOSPANNED
  • When coded SPANNED, it allows large records to span across more than one CI. However records cannot span across control areas.
  • When coded NOSPANNED, records will not be allowed to span out of one CI and job will fail if maximum record length is more than CI size specified
  • NOSPANNED is default
  • SPANNED can be specified only for ESDS or KSDS
• SPEED | RECOVERY
  • When coded RECOVERY (the default), it pre-formats VSAM dataset during initial load or resuming load. Specifying RECOVERY causes the space allocated to be filled with end-of-file markers. If the initial load of the cluster fails before completion, the end-of-file markers can be used to restart the load from the point of failure. For large datasets, this can save recovery time, but there is a trade-off in time to write the end-of-file markers during the definition of the cluster.
  • When coded SPEED, it will not pre-format the dataset. If SPPED is specified load will have to be restarted from beginning. SPEED is highly preferred because it speed up the initial load and will be much faster than RECOVERY
• TO(date)| FROM (days)
  • TO and FROM are mutually exclusive commands and used to specify the retention period of the cluster being defined.
  • The default value for this parameter is zero days
  • Syntax:- TO (date)    or    FROM (days)
  • Where,
    • date is in format YYDDD and it is Julian date
    • days can range from 1 – 9999
• DATA component
  • The DATA part of DEFINE CLUSTER is used to instruct IDCAMS that a separate data component is to be created.
  • It is optional to specify DATA part, but if coded must follow all the parameters that apply to the cluster.
• INDEX component
  • The INDEX parameter creates a separate index component.
  • It is optional to specify INDEX part, but if coded must follow all the parameters that apply to the data component.
  • It can be coded only with KSDS cluster
• CATALOG
  • CATALOG parameter is used to specify the catalog under which the cluster is defined.
  • While accessing the dataset, it is first searched in the catalog specified in CATALOG parameter.
  • In case, if CATALOG parameter is not coded, then the dataset will be searched in below manner till it is not found:-
    • STEPCAT or JOBCAT catalog ==> User catalog ==> System catalog
    • If not found in System catalog too, then error message will be displayed
• Example for DEFINE CLUSTER command can be referred in section ‘Defining KSDS’. ‘DEFINING ESDS’ or ‘DEFINING RRDS’ ==LINK==