VSAM Concepts

What is VSAM?

VSAM (Virtual Storage Access Method) is a high-performance access method for datasets on z/OS systems. Developed by IBM, VSAM provides efficient, flexible methods for organizing and accessing records in direct-access storage devices (DASD).

VSAM offers several key advantages over non-VSAM access methods:

• Improved performance through optimized access paths
• Support for multiple organization types to suit different application needs
• Built-in indexing capabilities for rapid record retrieval
• Advanced space management features
• Enhanced security and data integrity features
• Support for very large datasets

VSAM Dataset Organization Types

VSAM supports four primary types of dataset organization, each designed for specific access patterns and requirements:

1. Key Sequenced Data Set (KSDS)

The most widely used VSAM organization type, KSDS organizes records by a key field within each record. Records are stored in ascending key sequence.

Key characteristics:

• Records are retrieved directly using key values
• Supports sequential access in key sequence
• Records can be added and deleted dynamically
• Record lengths can be fixed or variable
• Contains both an index component and a data component

Ideal for: Applications that require both random and sequential access, such as customer databases, inventory systems, and most business applications.

2. Entry Sequenced Data Set (ESDS)

ESDS organizes records in the order they are loaded or added to the dataset, similar to a physical sequential file but with VSAM's enhanced capabilities.

Key characteristics:

• Records are stored in physical (entry) sequence
• New records can only be added at the end of the dataset
• Direct access is by Relative Byte Address (RBA)
• Records cannot be deleted (only marked as deleted)
• Record lengths can be fixed or variable

Ideal for: Log files, audit trails, and applications where records are primarily accessed sequentially or by their physical position.

3. Relative Record Data Set (RRDS)

RRDS organizes records by their relative record number, offering a hybrid of direct access and sequential processing capabilities.

Key characteristics:

• Records are accessed by their relative position (slot) in the dataset
• All records must be the same length
• Slots can be left empty, allowing for sparse population
• Records can be added, updated, and deleted directly
• Supports both sequential and direct access

Ideal for: Applications where the record's position has meaning, such as day-of-year reports, or when using application-assigned record numbers.

4. Linear Data Set (LDS)

LDS provides a simple byte-addressable storage space with minimal VSAM overhead, primarily used for specialized system functions.

Key characteristics:

• Treated as a continuous string of bytes
• No record structure imposed by VSAM
• Accessed as "pages" of data (usually 4K blocks)
• No built-in access methods like other VSAM types
• Application is responsible for organizing data

Ideal for: System-level functions, Db2 tablespaces, data-in-virtual applications, and Java Virtual Machine storage.

VSAM Dataset Components

VSAM datasets consist of several components that work together to provide efficient data storage and retrieval:

Data Component

The data component contains the actual user data stored in the VSAM dataset. Depending on the organization type, this data is arranged differently:

• In KSDS: Records stored in logical order based on the key field
• In ESDS: Records stored in physical entry sequence
• In RRDS: Fixed-length slots containing records or empty spaces
• In LDS: Continuous string of bytes with no record structure

Index Component

For KSDS, the index component provides the mapping between key values and the physical location of records. The index consists of multiple levels:

• Sequence Set: The lowest level of the index, pointing directly to data records
• Index Set: Higher-level indices that point to sequence set entries

ESDS, RRDS, and LDS datasets do not have an index component.

Control Areas (CAs) and Control Intervals (CIs)

VSAM organizes data into physical units of storage:

• Control Interval (CI): The basic unit of VSAM I/O, typically 4K to 32K bytes
• Control Area (CA): A group of CIs, usually one or more cylinders on DASD

This organization helps optimize space usage and performance.

Catalog Entries

VSAM datasets must be cataloged in an ICF (Integrated Catalog Facility) catalog. The catalog contains:

• Dataset attributes (organization, record size, key details)
• Location information (volume, extent details)
• Security and usage statistics

Defining VSAM Datasets

VSAM datasets are typically defined using IDCAMS (Access Method Services), a utility that provides commands for creating and managing VSAM datasets. The primary command used is DEFINE CLUSTER.

Basic DEFINE CLUSTER Syntax

1
2
3
4
5
6
7
8
9
10
11
12
13
//DEFVSAM  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER ( -
         NAME(dataset.name) -
         VOLUMES(volser) -
         organization-type -
         RECORDSIZE(average maximum) -
         KEYS(length offset) -
         SPACE(primary secondary) -
         additional-parameters -
       )
/*

Example: Defining a KSDS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//DEFKSDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER ( -
         NAME(USER.CUSTOMER.VSAM.KSDS) -
         INDEXED -
         VOLUMES(SYSVOL) -
         RECORDSIZE(200 300) -
         KEYS(10 0) -
         FREESPACE(20 10) -
         SHAREOPTIONS(2 3) -
         SPACE(10 5) CYLINDERS -
       )
/*

In this example:

• INDEXED: Specifies a KSDS organization
• RECORDSIZE(200 300): Average record size is 200 bytes, maximum is 300 bytes
• KEYS(10 0): Key field is 10 bytes long, starting at position 0
• FREESPACE(20 10): Reserve 20% of each CI and 10% of each CA for future insertions
• SHAREOPTIONS(2 3): Sharing options for cross-region and cross-system access
• SPACE(10 5) CYLINDERS: Allocate 10 primary and 5 secondary cylinders

Example: Defining an ESDS

1
2
3
4
5
6
7
8
9
10
11
//DEFESDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER ( -
         NAME(USER.LOGFILE.VSAM.ESDS) -
         NONINDEXED -
         VOLUMES(SYSVOL) -
         RECORDSIZE(100 100) -
         SPACE(5 2) CYLINDERS -
       )
/*

Key differences for an ESDS:

• NONINDEXED: Specifies an ESDS organization
• No KEYS parameter is used (entry-sequenced)
• No FREESPACE parameter (records are only added at the end)

Example: Defining an RRDS

1
2
3
4
5
6
7
8
9
10
11
//DEFRRDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER ( -
         NAME(USER.POSITION.VSAM.RRDS) -
         NUMBERED -
         VOLUMES(SYSVOL) -
         RECORDSIZE(150 150) -
         SPACE(2 1) CYLINDERS -
       )
/*

Key differences for an RRDS:

• NUMBERED: Specifies an RRDS organization
• Fixed RECORDSIZE (average must equal maximum)
• No KEYS parameter (accessed by relative record number)

Accessing VSAM Datasets in JCL

When accessing VSAM datasets through JCL, the DD statement syntax differs from non-VSAM datasets:

Basic DD Statement for VSAM

1
2
//ddname DD DSN=dataset.name,
//           DISP=SHR

Key points about VSAM datasets in JCL:

• JCL does not require or support UNIT or VOL parameters for VSAM datasets - this information is obtained from the catalog.
• DISP parameters are limited - NEW is not valid (use IDCAMS DEFINE instead), and CATLG/UNCATLG are ignored (VSAM datasets are always cataloged).
• Valid DISP parameters are OLD, SHR, and MOD (though MOD has a different meaning than for non-VSAM datasets).
• AMP parameter is used for special VSAM processing options.

Example: Accessing a VSAM Dataset

1
2
3
//STEP01   EXEC PGM=CUSTPROG
//CUSTFILE DD DSN=USER.CUSTOMER.VSAM.KSDS,
//            DISP=SHR

Using the AMP Parameter

The AMP parameter allows you to specify special processing options for VSAM datasets:

1
2
3
//CUSTFILE DD DSN=USER.CUSTOMER.VSAM.KSDS,
//            DISP=SHR,
//            AMP=('BUFND=10','BUFNI=5','STRNO=3')

Common AMP subparameters include:

• BUFND: Number of data buffers
• BUFNI: Number of index buffers
• STRNO: Number of concurrent strings (access paths)
• OPTCD: Processing options (e.g., 'OPTCD=L' for VSAM shared resources)
• RECFM: Forces a specific record format interpretation

Common VSAM Operations with IDCAMS

IDCAMS provides a comprehensive set of commands for managing VSAM datasets:

Listing Dataset Information

1
2
3
4
5
//LISTCAT  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(dataset.name) ALL
/*

Deleting a VSAM Dataset

1
2
3
4
5
//DELVSAM  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE dataset.name CLUSTER
/*

Printing VSAM Dataset Contents

1
2
3
4
5
6
//PRINTDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  PRINT INFILE(VSAMIN) CHAR
//VSAMIN   DD DSN=dataset.name,DISP=SHR
/*

Copying Data to/from a VSAM Dataset

1
2
3
4
5
6
7
//COPYVSAM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=input.dataset,DISP=SHR
//OUTFILE  DD DSN=output.dataset,DISP=SHR
//SYSIN    DD *
  REPRO INFILE(INFILE) OUTFILE(OUTFILE)
/*

Altering VSAM Dataset Parameters

1
2
3
4
5
6
7
//ALTERVSM EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  ALTER dataset.name -
        BUFFERSPACE(100000) -
        SHAREOPTIONS(2 3)
/*

VSAM Performance Considerations

Optimizing VSAM performance involves several key considerations:

Control Interval and Control Area Sizing

Proper sizing of CIs and CAs can significantly impact performance:

• Larger CIs can improve sequential processing but may waste space for random access
• Smaller CIs reduce space waste but increase index complexity
• CA size affects reorganization time and the frequency of CA splits

Buffer Allocation

Appropriate buffer allocation improves I/O efficiency:

• Increase BUFND for sequential processing
• Increase BUFNI for random processing of a KSDS
• Use the AMP parameter to override defaults

Free Space Allocation

For KSDS, proper free space allocation can reduce the frequency of CI and CA splits:

• Higher free space percentages improve insert performance but use more disk space
• Lower free space is appropriate for less volatile datasets
• Consider the frequency and distribution of record insertions

Reorganization

Regular reorganization helps maintain optimal performance:

• Use EXPORT/IMPORT or REPRO to reorganize datasets with excessive splits
• Schedule reorganizations based on access patterns and growth rates
• Monitor for signs of performance degradation

VSAM Limitations and Considerations

While VSAM offers many advantages, there are some limitations to be aware of:

• VSAM datasets cannot be concatenated in JCL
• Certain parameters (like DCB information) cannot be specified in JCL for VSAM datasets
• VSAM does not support traditional sequential access methods like QSAM
• Some utilities that work with sequential datasets do not support VSAM
• VSAM datasets are typically more complex to define and manage than sequential or partitioned datasets
• Recovery may be more challenging, especially after CI or CA splits