Create VSAM or DEFINE CLUSTER

DEFINE CLUSTER Command DEFINE CLUSTER     (NAME(entryname)     {CYLINDERS(primary] secondary])  |      RECORDS(primary[ secondary])      ...

DEFINE CLUSTER Command

DEFINE CLUSTER
    (NAME(entryname)
    {CYLINDERS(primary] secondary])  |
     RECORDS(primary[ secondary])    |
     TRACKS(primary[ secondary])}
    VOLUMES(volser[ volser...])
    [BUFFERSPACE(size)]
    [CONTROLINTERVALSIZE(size)]
    [ERASE  |  NOERASE]
    [FILE(ddname)]
    [FREESPACE(CI-percent[ CA-percent]|0 0)]
    [IMBED  |  NOIMBED] 

    [REPLICATE  |  NOREPLICATE]
    [INDEXED  |  NONINDEXED  |  NUMBERED]
    [KEYS(length offset|64 0)]
    [MODEL(entryname[/password][ catname[/password]])]
    [RECORDSIZE(average maximum)]    

    [REUSE  |  NOREUSE]
    [SPEED  |  RECOVERY]
    [TO(date)  |  FOR(days)]
    [UNIQUE  |  SUBALLOCATION]
  
    [DATA
    ([NAME(entryname)])

    [INDEX
    ([NAME(entryname)])

Parameters that describe file’s characteristics(NKFIRST)

NAME – Specifies the name of the cluster or component


KEYS - The KEYS parameter specifies the length and position (relative to the beginning of the record, with 0 indicating the first character) of the primary key in the records written to the cluster.


FILE – If the name is specified in a DD statement, specify the DD name in this parameter.
INDEXED/NONINDEXED/NUMBERED – To define a KSDS/ESDS/RRDS


RECORDSIZE – Specifies the length of the logical records in your file. Two subparameters average record length and maximum record length are coded. If the integer values of both average and maximum are identical, the records which can be written to the cluster will be fixed length and of the size specified by the value.  If the values specified differ, the records written to the cluster may be in varying length, up to the value specified for maximum.
SPANNED – If your file will contain records that are longer than one CI, you need to code the SPANNED parameter.


TO(date) / FOR(days) – Specifies the retention period of cluster or component.
CATALOG – Specifies the name of the catalog that will own the cluster. If you omit the CATALOG parameter, the STEPCAT, JOBCAT, HLQ or MCAT identifies the catalog.

Parameters that specify file’s space allocation(CURVE/CRTVUSER)

CYLINDERS/RECORDS/TRACKS - One of the three space allocation subparameters must be coded to specify the size of the cluster.  Space may be requested in terms of cylinders, tracks, or records.  Both a primary and secondary quantity may be specified for either of the three specification units.  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 completely used and an additional record is added to the cluster.  The number of times that a cluster can be expanded (secondary quantities of space allocated) varies based on several factors, but may be as high as 123 times. 


UNIQUE/SUBALLOCATION - Where the space is obtained for allocation is determined by the UNIQUE / SUBALLOCATION parameter.  If UNIQUE is specified, free space must exist on the VOLUMES specified; an independent data space is created on the volume and is allocated entirely to the cluster being defined.  From a data management viewpoint, this is usually not a good idea.  A better method is to allow AMS to suballocate the required space from an already defined VSAM data space.
If the file will be owned by an ICF catatlog, you can omit this parameter. ICF catalogs do not have the concept of VSAM space.


REUSE- The REUSE parameter allows clusters to be defined that may be reset to empty status without deleting and re-defining them.  This is most often used for clusters used as work datasets.


VOLUMES - The VOLUMES parameter specifies one or more direct access storage volumes on which space may be allocated for the cluster.


ERASE- The ERASE parameter specifies that when the cluster is deleted, the space occupied by the cluster should be physically erased by overwriting the space with binary zeros prior to freeing the space for reuse.

Parameters that affect performance(FRISSBC/CFRISSB)

REPLICATE - REPLICATE specifies that VSAM should write each index record on a track as many times as it will fit. REPLICATE is obsolete nowadays.


IMBED - IMBED specifies that sequence set records are to be imbedded with the data in the data component of the cluster.  When the sequence set is imbedded in the data component, VSAM writes each sequence set record on the first track of its associated control area.  IMBED automatically implies REPLICATE. IMBED is obsolete nowadays.


FREESPACE- The FREESPACE parameter specifies a percentage of space to leave unallocated for future expansion.  The percentage applies when records are initially loaded into the cluster and when control interval and control area splits occur as records are inserted between existing records.  If FREESPACE is not specified, control intervals are filled as completely as possible and no space is left for addition of records in the future.

We know that FREESPACE(100,100) specification causes one record to be written for each

Control interval, and one Control Interval would be written for each control area. This is because VSAM will always load the first record before taking FREESPACE option into consideration!!!

Inserts at end of file FREESPACE(0 0)
Inserts clustered at points in the file FREESPACE(0 50)
data inserted at random, all over the file FREESPACE(20 25)

CISZ- In most cases, the CONTROLINTERVALSIZE parameter should be omitted.  


This allows AMS to choose the most efficient value for the dataset.  A control interval can range from 512 to 32,768 bytes in size.  If the size is between 512 and 8,192 bytes, a multiple of 512 should be specified.  If it is between 8,192 and 32,768 bytes, a multiple of 2,048 should be specified.  If the size is not a multiple of the appropriate value, AMS rounds the size up to the next appropriate multiple.  If CONTROLINTERVALSIZE is specified for the INDEX component of a KSDS, the specified size must be 512, 1,024, 2,048, or 4,096.
Although you can code CISZ parameter at the cluster level, that’s not a good idea. When you do, VSAM assigns the same CI size to both the data and index components. Instead you should specify CISZ at the DATA level and let VSAM calculate the CISZ for INDEX component. VSAM usually does a good job at that.


SPEED/RECOVERY -  The SPEED / RECOVERY parameters are used to specify whether or not VSAM should preformat the space allocated to the cluster as part of the DEFINE process.  Specifying RECOVERY (the default) causes the allocated space to be filled with end-of-file markers.  If the initial load of the cluster with data should fail before completion, the end-of-file markers can be used to resume the load from the point of failure.  For large datasets, this can save recovery time, however there is a trade-off in time to write the end-of-file markers during the definition of the cluster.


BUFFERSPACE - Specifies the minimum space for buffers. If you do not specify a value, VSAM attempts to get enough space to contain two data component control intervals and, if the data is key-sequenced, one index component control interval

SHAREOPTIONS -  Tells VSAM whether you want to let two or more jobs process a file at the same time. VSAM provides 2 options in this parameter, cross region and cross system, but you should need only the cross region option.

• Cross Region: Specifies the amount of sharing allowed among regions within the same system.
• Cross System: Specifies the amount of sharing allowed among systems. Job steps of two or more operating systems can gain access to the same VSAM data set regardless of the disposition indicated in the DD statement for the data set in each step.

Cross Region	Cross System
1 – Lets any number of jobs read privilege only or one job having write privilege only.	1 – Reserved, cannot be used
2 – Lets one job write privilege and all other jobs read privilege.	2 – Reserved, cannot be used
3 – Lets any number of jobs for both read and write access. No integrity. If you define a file with AIX that will be processed by a COBOL program, you should code 3 even if the file isn’t going to be shared. Because a COBOL program tries to open the base cluster more than once when AIXs are used, the open statement will fail unless sharing is specified.	3 – Lets any number of jobs for both read and write access. No integrity. If you define a file with AIX that will be processed by a COBOL program, you should code 3 even if the file isn’t going to be shared. Because a COBOL program tries to open the base cluster more than once when AIXs are used, the open statement will fail unless sharing is specified.

If you are using an MVS system, you should realize that the cross region share options are similar to those of the DISP parameter in a DD statement. Share options 1 and 2 are similar to DISP=OLD and Share option 3 is similar to DISP=SHR. You should also realize that the share options have no meaning unless DISP=SHR is coded for a file. If DISP=OLD is specified, the file is locked out to other jobs no matter what share options are specified.

SHAREOPTION (2,3) is defined in order that it can be accessed both in CICS and in BATCH environment.