Virtual Storage Access Method (VSAM)

VSAM Data Formats

Control Intervals

Control Information Fields

Control Interval 1

Control Interval 2

Control Interval 3

Spanned Records

VSAM Data Set Structure

VSAM Data Set Access

VSAM Data Set Access

Control Interval Size

Note: The valid control interval sizes and block sizes are from 512 to 8192 bytes in increments of 512 bytes, and from 8 KB to 32 KB in increments of 2 KB

Control Area

Control Interval Freespace

Control Area Freespace

Control Area Freespace

Control Interval Split

Index Control Interval Size

Note: The valid control interval and block sizes for index components are 512, 1024, 2048, and 4096 bytes.

Index Too Big

Index Too Big

In this example, the index CI size was defined as too large. A larger than necessary index CI size will waste space in each index record, as shown.Generally speaking, the index record need not be larger than the KEYLENGTH times the number of CIs within a CA. Actually, VSAM uses key compression techniques which usually allow a smaller index CI to be used efficiently. A compression factor of 50-60% is generally accepted for most user application files. The following formula can be used to approximate the optimum index CI size:

INDEX CISIZE = KEYLENGTH * (Num of CIs per CA) / 2

Index Too Small

Index Too Small

If the index CI size is defined as too small, there may not be enough room to hold a pointer for each CI within the CA. This causes wasted space in each CA and results in an inefficient file in respect to DASD space.

Intermediate index levels may be created if the high level index record is too small to contain all of the pointers to the Sequence Set records.

A good rule of thumb is to make the index large, since the cost of an index that is too large is only wasted space in the index records. An index that is too small, not only wastes space in the CAs but can create a need for multiple levels of indexing which will effect performance by potentially increasing the number of physical I/Os.

Selecting a VSAM Data Set Type

• Entry-sequenced data set (ESDS)• Key-sequenced data set (KSDS)• Relative record data set (RRDS)• Linear data set (LDS)

Selecting a VSAM Data Set Type

•Will you need to access the records in sequence, randomly, or both ways?

•Are all the records the same length?

•Will the record length change?

•How often will you need to move records?

•How often will you need to delete records?

•Do you want spanned records?

•Do you want to keep the data in order by the contents of the record?

•Do you want to access the data by an alternate index?

•Do you want to use access method services utilities with an IBM DB2 cluster?

Applications best suited to entry-sequenced data sets.

•Applications that require sequential access only. It is better to use entry-sequenced data sets or variable-length RRDSs for sequential access, because they support variable-length records and can be expanded as records are added.

•If you wish to use an entry-sequenced data set in an online application, load the data set sequentially by a batch program and access the data set directly by the relative byte address (RBA).

Applications best suited to key-sequenced data sets.

•Applications that require that each record have a key field.•Applications that require both direct and sequential access.•Applications that use high-level languages which do not support RBA use.•Online applications usually use key-sequenced data sets.•You want to access the data by an alternate index.•The advantage of key-sequenced data sets over fixed-length RRDS using direct access is ease of programming.•You want to have compressed data.

Applications best suited to linear data sets.

Linear data sets are rarely used by application programs. They are the most effective for specialized applications. For example, data-in-virtual (DIV) stores data in linear data sets.

Applications best suited to relative record data sets.

•Applications that require direct access only.•Applications which there is a one-to-one correspondence between records and relative record numbers. For example, you could assign numeric keys to records sequentially, starting with the value 1. Then, you could access a RRDS both sequentially and directly by key.•Fixed-length RRDSs use less storage and are usually faster at retrieving records than key-sequenced data sets or variable-length RRDSs.•If the records vary in length, use a variable-length RRDS.•Variable-length RRDSs can be used for COBOL applications.

Entry sequenced data set (ESDS)

Entry sequenced data set (ESDS)

Typical ESDS processing

Key sequenced data set (KSDS)

Key sequenced data set (KSDS)

Key sequenced data set (KSDS)

Data/Index relationship

Relative record data set (RRDS)

Relative record data set (RRDS)

Relative record data set (RRDS)

Typical RRDS processing

Linear data set (LDS)

Linear data set (LDS)

Data-in-virtual

Data-in-virtual objects

Mapping a linear data set

DIV IDENTIFY

DIV ACCESS

DIV MAP

DIV SAVE

DIV RESET

Defining a VSAM Data Set

•VSAM data sets must be cataloged.

•Define a VSAM data set in the catalog using the TSO ALLOCATE command, or access method services ALLOCATE or DEFINE CLUSTER command, dynamic allocation, or JCL. To define a VSAM data set with JCL, dynamic allocation SMS must be active on your system. Most of the DEFINE options available with access method services are not supported by dynamic allocation or JCL.

•Load the data set with data either by using the access method services REPRO command, or by writing your own program to load the data set.

•Optionally, define any alternate indexes and relate them to the base cluster. Use the access method services DEFINE ALTERNATEINDEX, DEFINE PATH, and BLDINDEX commands to do this.

Cluster Concept

For a key-sequenced data set, a cluster is the combination of the data component and the index component. The cluster provides a way to treat the index and data components as a single component with its own name. You can also give each component a name. Fixed-length RRDSs, entry-sequenced data sets, and linear data sets are considered to be clusters without index components. To be consistent, they are given cluster names that are normally used when processing the data set.

!

Naming a Cluster

Cluster name: SALES.REGION2.CLUSTERGenerated data name = SALES.REGION2.DATAGenerated index name = SALES.REGION2.INDEX

Cluster name: DEPT64.ASSET.INFOGenerated data name = DEPT64.ASSET.INFO.DATAGenerated index name = DEPT64.ASSET.INFO.INDEX

Cluster name: DEPTABCD.RESOURCE.REGION66.DATA1234.STUFFGenerated data name = DEPTABCD.RESOURCE.REGION66.DATA1234.STUFF.DGenerated index name = DEPTABCD.RESOURCE.REGION66.DATA1234.STUFF.I

Cluster name: DIV012.GROUP16.DEPT98.DAILYLOG.DEC1988.BACKGenerated data name = DIV012.GROUP16.DEPT98.DAILYLOG.TY7RESNOGenerated index name = DIV012.GROUP16.DEPT98.DAILYLOG.YIIQHNTR

Access method services

Functional commands DEFINE CLUSTER – creates/catalog data sets.DEFINE GDG – catalog GDG data sets.DEFINE ALTERNATEINDEX - defines an alternate indexDEFINE PATH - defines a path directly over an alternate index and its related base clusterBLDINDEX - builds alternate indexes for existing data setsALTER - modifies the attributes of defined data sets and catalogs.EXPORT – export VSAM data sets.IMPORT – import VSAM data sets.DELETE - deletes catalogs, VSAM data sets, non-VSAM data sets.LISTCAT – list catalog entries.PRINT - prints VSAM, non-VSAM data sets, and catalogs.REPRO – copy VSAM non-VSAM and catalogs.

AMS modal commands

IDCAMS. DEFINE CLUSTER

DEFINE CLUSTER (parameters) - [DATA(parameters)] - [INDEX(parameters)] - [CATALOG(subparameters)]

If you do not use the SMS classes to specify the necessary: •descriptive,•performance, •security, and integrity information,

Descriptive Information Includes:

INDEXED|NONINDEXED|NUMBERED|LINEAR parameter - Specifies the type of data organization used (key-sequenced, entry-sequenced, relative record, or linear).

RECORDSIZE parameter - Specifies the average and maximum lengths of data records. The RECORDSIZE parameter is not used for a linear data set.

KEYS parameter - Specifies the length and position of the key field in the records of a key-sequenced data set.

CATALOG parameter - Specifies the name and password of the catalog in which the cluster is to be defined.

Descriptive Information Includes:

VOLUMES parameter - Specifies the volume serial numbers of the volumes on which space is allocated for the cluster. For DASD data sets you can specify up to 59 volumes. For magnetic tape data sets you can specify up to 255 volumes.

RECORDS|KILOBYTES|MEGABYTES|TRACKS|CYLINDERS parameter - Specifies the amount of space to allocate for the cluster. The CYLINDERS, TRACKS, MEGABYTES, KILOBYTES and RECORDS parameters are permitted for a linear data set.If RECORDS is specified for a linear data set, space is allocated with the number of control intervals equal to the number of records.

Descriptive Information Includes:

RECATALOG parameter - Specifies if an entry is recreated from information in the VSAM volume data set (VVDS), or defined for the first time.

REUSE|NOREUSE parameter - Specifies if the cluster is reusable for temporary storage of data.

BUFFERSPACE parameter - Specifies the minimum amount of I/O buffer space that must be allocated to process the data set.

Performance Information Includes:

CONTROLINTERVALSIZE parameter - Specifies the control interval size for VSAM to use (instead of letting VSAM calculate the size).The size of the control interval must be large enough to hold a data record of the maximum size specified in the RECORDSIZE parameter unless the data set was defined with the SPANNED parameter. SPANNED parameter - Specifies whether records can span control intervals. The SPANNED parameter is not permitted for fixed-length and variable-length RRDSs, and linear data sets. 

Performance Information Includes:

SPEED|RECOVERY parameter - Specifies whether to preformat control areas during initial loading of a data set.  VOLUMES parameter for the index component - Specifies whether to place the cluster’s index on a separate volume from data. FREESPACE parameter - Specifies the amount of free space to remain in the data component of a key-sequenced data set or variable-length RRDS’s control intervals and control areas when the data records are loaded. KEYRANGES parameter - Specifies how data should be spread over multiple volumes.

Security and Integrity Information Includes:

Passwords - Because passwords are not supported for system-managed data sets, this information pertains to non-system-managed data sets only.  AUTHORIZATION parameter - Specifies your own authorization routine to verify that a requester has the right to gain access to data. EXCEPTIONEXIT parameter - Specifies an I/O error-handling routine (the exception exit routine) that is entered if the program does not specify a SYNAD exit.

Security and Integrity Information Includes:

WRITECHECK parameter - Specifies whether to verify that write operations have completed and that the data can be read. SHAREOPTIONS parameter - Specifies whether and to what extent data is to be shared among systems, and jobs. ERASE parameter - Specifies whether to erase the information a data set contains when you delete the data set.

DEFINE CLUSTER Examples

//DEFINE JOB ...//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DEFINE CLUSTER -(NAME (SMS04.KSDS02) -STORAGECLASS (FINCE02) -MANAGEMENTCLASS (MC1985) -DATACLASS (VSAMDB05)) -DATA -(MEGABYTES (10 2)) -INDEX -(KILOBYTES (25 5))/*

Define an SMS-Managed Key-Sequenced Cluster Specifying Data and Index Parameters:

//DEFCLU5 JOB ...//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD *DEFINE CLUSTER -(NAME(EXAMPLE.ESDS2) -RECORDSIZE(2500 3000) -SPANNED -VOLUMES(VSER03) -CYLINDERS(2 1) -NONINDEXED -CATALOG(RSTUCAT2)/*

Define Entry-Sequenced Cluster in a Catalog:

IDCAMS. ALLOCATE

//STEP1 EXEC PGM=IDCAMS,DYNAMNBR=1//SYSPRINT DD SYSOUT=*//SYSIN DD *ALLOC - DSNAME(M166575.ALLOC.EXAMPLE) - NEW CATALOG - SPACE(10,2) - AVBLOCK(80) - AVGREC(K) - LRECL(80) - RECORG(ES) - STORCLAS(FAST) - MGMTCLAS(VSAM)/*

IDCAMS. ALTER

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD * DEFINE CLUSTER - (NAME(EXAMPLE.KSDS) - TRK(1 1) - VOL (338001)) - DATA - (NAME(EXAMPLE.KSDS.DATA)) - INDEX - (NAME(EXAMPLE.KSDS.INDEX)) ALTER - EXAMPLE.KSDS - NEWNAME(EXAMPLE.TEST) ALTER - EXAMPLE.KSDS.* - NEWNAME(EXAMPLE.TEST.*)

Loading a VSAM Data Set Depending on the type of VSAM data set being loaded, the source data set records might or might not need to be in a particular order.

•Records being loaded into an entry-sequenced data set do not have to be submitted in any particular order. Entry-sequenced data set records are sequenced by their time of arrival rather than by any field in the logical record.•Fixed-length RRDS records are placed into slots specified either by a user-supplied or a VSAM-supplied relative record number. The relative record number is not part of the logical record, so it is not necessary that the records be submitted in any particular order.•Records being loaded into a key-sequenced data set must be in ascending order by key, with no duplicate keys in the input data set.•Records being loaded into a variable-length RRDS must be in ascending order by key, with no duplicate keys in the input data set. If they are loaded in sequential mode, VSAM assigns the relative record number.

Using REPRO to Copy a Data Set

You can use the REPRO command to do any of the following:•Copy or merge a VSAM data set into another VSAM data set.•Copy or merge a sequential data set into another sequential data set.•Copy an alternate index as a key-sequenced VSAM data set.•Copy a VSAM data set whose records are fixed length into an empty fixed-length RRDS.•Convert a sequential or indexed sequential data set into a VSAM data set.•Copy a VSAM data set into a sequential data set.Copy individual members of a PDS or PDSE. A PDS or PDSE cannot be copied, but individual members can be copied.

IDCAMS. REPRO

//SORT EXEC PGM=SORT //SYSOUT DD SYSOUT=* //SORTIN DD DSN=P390S.EXAM(SORTIN1),DISP=OLD //SORTOUT DD DSN=&&SORTOUT,DISP=(,PASS),SPACE=(TRK,(1,1)) //SYSIN DD * SORT FIELDS=(1,8,A),FORMAT=CH SUM FIELDS=NONE /* //STEP1 EXEC PGM=IDCAMS //INPUT DD DSN=&&SORTOUT,DISP=(OLD,PASS) //SYSPRINT DD SYSOUT=* //SYSIN DD * REPRO - INFILE(INPUT) - OUTDATASET(P390S.KSDS1)

Defining an Alternate Index

The sequence for building an alternate index is as follows:

1. Define the base cluster, using either the ALLOCATE command, the DEFINE CLUSTER command, or JCL.2. Load the base cluster either by using the REPRO command or by writing your own program to load the data set.3. Define the alternate index, using the DEFINE ALTERNATEINDEX command. 4. Relate the alternate index to the base cluster, using the DEFINE PATH command. The base cluster and alternate index are described by entries in the same catalog.5. Build the alternate index, using the BLDINDEX command.

Base cluster and AIX relationship

Alternate Index Structure for a Key-Sequenced Data Set

Alternate Index Structure for an Entry-Sequenced Data Set

Defining an Alternate Index

//STEP1 EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DEFINE ALTERNATEINDEX - (NAME(P390S.KSDS1.AIX) - RELATE(P390S.KSDS1) - KEYS(4 11) - RECORDSIZE(40 50) - VOLUMES(Stud01) - CYLINDERS(1 1) - NONUNIQUEKEY - UPGRADE) DEFINE PATH - (NAME(P390S.KSDS1.PATH) - PATHENTRY(P390S.KSDS1.AIX)

IDCAMS. BLDINDEX

//BASEDD DD DSNAME=P390S.KSDS1,DISP=OLD //AIXDD DD DSNAME=P390S.KSDS1.AIX,DISP=OLD //SYSPRINT DD SYSOUT=* //SYSIN DD * BLDINDEX INFILE(BASEDD) - OUTFILE(AIXDD) - SORTCALL /*

IDCAMS. LISTCAT

[ALIAS][CLUSTER] [DATA] [INDEX][GENERATIONDATAGROUP][NONVSAM][PAGESPACE][PATH][USERCATALOG][VOLUMEENTRIES( volent)][CREATION( days)][ENTRIES( entryname [ entryname...])|LEVEL( level)][EXPIRATION( days)][FILE( ddname)] [NAME|HISTORY|VOLUME| ALLOCATION|ALL][OUTFILE( ddname)][CATALOG( catname)]

LISTACAT

LISTCAT Examples

//STEP1 EXEC PGM=IDCAMS,REGION=2048K //SYSPRINT DD SYSOUT=X //SYSIN DD * LISTCAT ALIAS CATALOG(CATALOG.VSOFT02) LISTCAT ENTRIES(SOFT.DFSMS.SCDS) ALL LISTCAT LEVEL(D.A07) NONVSAM ALL LISTCAT LEVEL(SYS1.VVDS)/*

IDCAMS. DELETE

( entryname[ entryname ...])[ALIAS| ALTERNATEINDEX| CLUSTER| GENERATIONDATAGROUP|LIBRARYENTRY| NONVSAM| NVR| PAGESPACE| PATH| TRUENAME| USERCATALOG| VOLUMEENTRY| VVR][ERASE|NOERASE][FILE( ddname)][FORCE|NOFORCE][PURGE|NOPURGE][SCRATCH|NOSCRATCH][CATALOG( catname)]

DELETE

Examples DELETE EXAM.KSDS CATALOG(CATALOG.VSOFTO2)

DELETE (P.SFN.SAS.D96P) NOSCRATCH NONVSAMDELETE EXAM.*

IDCAMS. PRINT

//STEP1 EXEC PGM=IDCAMS//SYSPRINT DD SYSOUT=A//SYSIN DD */* PRINT THE ENTIRE CATALOG */PRINT -INDATASET(USERCAT4)/*

IF-THEN-ELSE Command SequenceIF {LASTCC|MAXCC} operator number

THEN[ command|DO command setEND][ELSE[ command|DOcommand setEND]]

ExampleIF LASTCC > 4 -THEN IF MAXCC < 12 -THEN REPRO...ELSE DELETE...ELSE IF LASTCC = 4 -THENELSE PRINT...

SET Command

SET {MAXCC|LASTCC}= number

ExampleIF MAXCC=0THEN DOLISTCAT CATALOG (AMASTCAT) ENT (MN01.B005)PRINT INFILE (AJK006)ENDELSE ...SET MAXCC=8

CANCEL Command

ExampleIF MAXCC=0THEN DOLISTCAT CATALOG (AMASTCAT) ENT (MN01.B005)PRINT INFILE (AJK006)ENDELSE DOSET MAXCC=12CANCELEND

Using Job Control Language for VSAM

•SMS must be active, but the data set does not have to be system-managed.

•Any VSAM data set can be defined using JCL, except for a variable-length RRDS.

Creating a VSAM Data Set Using JCL

AVGREC - Specifies the scale value of an average record request on the SPACE keyword. The system applies the scale value to the primary and secondary quantities specified in the SPACE keyword. Possible values for the AVGREC keyword are: U - Use a scale of 1 K - Use a scale of 1024 M - Use a scale of 1 048 576

RECORG - Specifies the type of data set desired: KS, ES, RR, LS. KS = key-sequenced data set ES = entry-sequenced data set RR = fixed-length relative record data set LS = linear data set

Creating a VSAM Data Set Using JCL

KEYLEN - Specifies key length.

KEYOFF - Specifies offset to key.

LRECL - Specifies logical record length. Implies a system determined control interval size.

LIKE - Specifies that the properties of an existing cataloged data set should be used to allocate a new data set.

REFDD - Specifies that the properties on the JCL statement and from the data class of a previous DD statement should be used to allocate a new data set.

Allocate a VSAM Data Set

Allocate a Key-Sequenced Data Set //DDNAME DD DSNAME=KSDATA,DISP=(NEW,KEEP), // SPACE=(80,(20,2)),AVGREC=U,RECORG=KS, // KEYLEN=15,KEYOFF=0,LRECL=250

Allocate a Temporary VSAM Data Set

//VSAM1 DD DSN=&CLUSTER,DISP=(NEW,PASS), // RECORG=ES,SPACE=(1,(10)),AVGREC=M, // LRECL=256,STORCLAS=TEMP