Home  Page 1 Page 2 Page 3 VSAM ERROR CODE VSAM Questions


Virtual Storage Access Method - VSAM - is a data management system introduced by IBM in the 1970s as part of the OS/VS1 and OS/VS2 operating systems.  Although there are still datasets that are best managed with the several other (non-VSAM) data management methods, VSAM is a major component of modern IBM operating systems.  Since MVS 3.8 is one of those operating systems, I thought it might be useful to other Hercules' users to set down some basic information about VSAM.  

I have divided the material presented here into two main segments -

  • Concepts and Facilities
  • Access Method Services

In the first segment, I will try to provide a simple description of the components of VSAM, with the goal of introducing VSAM to those who have not had practical experience with it.  I don't want to write a textbook, as I have several of those in my own library and they can be quite dry and boring.  But, it is my perception that quite a few people are coming into the Hercules (and MVS) community who have not had any formal exposure to this type of material and I think there may be some positive benefit to my efforts.

In the second segment, I will try to cover most, if not all, of the functions provided by Access Method Services.  Access Method Services is the single, general-purpose utility that is used to manipulate VSAM components by both Systems and Applications Programmers.  If you are more interested in the "how to" rather than the "why", this second segment is probably where you will want to begin reading.

There is also an index at the bottom of the page to allow you to quickly locate the section describing a particular AMS function.

Concepts and Facilities

VSAM was, by several accounts, intended to replace all of the earlier data management systems in use by IBM's operating systems.  Conventional (non-VSAM) access methods generally provide only a single type of dataset organization.  VSAM provides three:

  • Key Sequenced Data Set (KSDS), where each record is identified for access by specifying its key value - a sequence of characters embedded in each data record which uniquely identify that record from all other records in the dataset.  KSDS datasets are similar to Indexed Sequential Access Method (ISAM) datasets, with many of the same characteristics, but also having distinct advantages over ISAM.
  • Entry Sequenced Data Set (ESDS), where each record is identified for access by specifying its physical location - the byte address of the first data byte of each record in relationship to the beginning of the dataset.  ESDS datasets are similar to Basic Sequential Access Methid (BSAM) or Queued Sequential Access Method (QSAM) datasets.
  • Relative Record Data Set (RRDS), where each record is identified for access by specifying its record number - the sequence number relative to the first record in the dataset.  RRDS datasets are similar to Basic Direct Access Method (BDAM) datasets.

VSAM datasets are frequently referred to as clusters.  A KSDS cluster consists of two physical parts, an index component, and a data component.  ESDS and RRDS clusters consist of only a single component, the data component.

KSDS Cluster Components

Each record in the data component of a KSDS cluster contains a key field, which must be the same number of characters and occur in the same relative position in each record.  The records are stored in the data component in logical sequence based upon their key field value.  The index component of the KSDS cluster contains the list of key values for the records in the cluster with pointers to the corresponding records in the data component.  The records in a KSDS may be accessed sequentially, in order by key value, or directly, by supplying the key value of the desired record.  The records of a KSDS cluster may be fixed length or variable length.  Records may be added or deleted at any point within a KSDS cluster, and the affected record is inserted or removed, and the surrounding records will be reorganized as required to maintain the correct logical sequence.

ESDS Cluster Components

The records in an ESDS cluster are stored in the order in which they are entered into the dataset.  Each record is referenced by its relative byte address (RBA).  In an ESDS dataset of 100 byte records, the RBA of the first record is 0, the RBA of the second record is 100, the RBA of the third record is 200, etc.  The records in an ESDS may be accessed sequentially, in order by RBA value, or directly, by supplying the RBA of the desired record.  The records of an ESDS cluster may be fixed length or variable length.  Records may not be deleted from an ESDS cluster, and they may only be added (appended) to the end of the dataset, following records previously written. 

RRDS Cluster Components

The records in an RRDS cluster are stored in fixed length slots.  Each record is referenced by the number of its slot, which is a number varying from 1 to the maximum number of records which may be contained in the dataset.  The records in an RRDS cluster may be accessed sequentially, in relative record number order, or directly, by supplying the relative record number of the desired record.  The records of an RRDS cluster must be of fixed length.  Records may be added to an RRDS cluster by writing a new record's data into an empty slot, and records may be deleted from an RRDS cluster, thereby leaving an empty slot where the record that was deleted was previously stored.

Control Intervals

In non-VSAM data management methods, the unit of data that is moved between memory and the storage device is defined by the block.  In VSAM, the unit of data that is transferred in each physical I/O operation is defined as a control interval.  A control interval contains records, control information, and (in the case of KSDS clusters) possibly free space which may later be used to contain inserted records.  

When a VSAM dataset is loaded, control intervals are created and records are written into them.  With KSDS clusters, the entire control interval is usually not filled.  Some percentage of free space is left available for expansion.  With ESDS clusters, each control interval is completely filled before records are written into the next control interval in sequence.  With RRDS clusters, control intervals are filled with fixed-length slots, each containing either an active record or a dummy record.  Slots containing dummy records are available for use when new records are added to the dataset.

Control Areas

Control intervals are grouped together into control areas.  The rules used for filling and writing control areas are similar to those which apply for control intervals.  For ESDS and RRDS clusters, control areas are filled with control intervals that contain records.  For KSDS clusters, some of the control intervals in each control area may consist entirely of free space that can be used for dataset expansion.

VSAM Catalogs

When a non-VSAM dataset is created, the user has the option, by means of the DISP=(,CATLG) JCL entry, of creating a catalog entry for the dataset.  The catalog keeps track of the unit and volume on which the dataset resides and can be used for later retrieval of the dataset.  With VSAM datasets, creation of a catalog entry to record the unit and volume, as well as many other characteristics of the dataset, is not optional.

Prior to VSAM, catalog entries for non-VSAM datasets were contained in OS CVOLS (operating system control volumes).  VSAM maintains its own catalog, which is itself a KSDS cluster, into which catalog entries describing VSAM clusters are recorded.  The same VSAM catalog may also be used to contain the catalog entries for non-VSAM datasets.

Later releases of OS/390, the operating system into which MVS evolved, and  z/OS, the current incarnation of MVS-OS/390, use yet another catalog system - the Integrated Catalog Facility.  On the latest versions of OS/390 and z/OS, ICF catalogs are the only type of catalogs supported.

For MVS 3.8j, the relevant catalog system is the VSAM catalog, which is where information for both VSAM and non-VSAM datasets is recorded.

Access Method Services

Pre-VSAM data management required many utility programs for housekeeping -

  • IEBGENER to copy the contents of sequential datasets
  • IEHMOVE and IEBCOPY to copy, move, reorganize, expand, backup and restore the contents of partitioned dataset
  • IEBISAM to load, backup, restore, and reorganize the contents of ISAM datasets

to name a few.  However, there is only a single utility for managing all of the housekeeping needs of VSAM -


which is also known by the functionality it provides - Access Method Services - or, simply, AMS.

The basic JCL to run the utility is:


Some of the functions require additional DD statements when they are referenced by the AMS command statements, but SYSPRINT and SYSIN are the only absolute requirements.

There are a number of ways to organize the many functions that AMS provides.  I will present functions as they might be required on a newly generated system.  For example, the first task would be to set up user catalogs and data space to accommodate the creation of VSAM clusters.  At the end of this page I will place an Index table with links to bookmarks so that anyone looking for a specific function can find it more easily.