HCL Perot Systems

VSAM Training

VSAM CONCEPTS
The VSAM means Virtual Storage Access Method is most commonly used access method on MVS
Systems. VSAM does more than just replace non-VSAM access methods with VSAM access methods. It
also provides efficiency improvements and a comprehensive catalog facility that centralises information
about all VSAM datasets. In addition, the multi-functional utility program AMS has a variety of file
related functions for VSAM as well as non-VSAM files.
DASD Labels and Space Management
Direct Access Storage Devices, or DASDs allow direct access to large quantities of data. They are used not
only to store user programs and data but also to store operating system programs and data.
The various models of DASD units can be divided into two basic categories, depending on the format in
which they store data CKD devices and FBA devices. On Count-Key-Data (CKD) devices data is stored
in variable length blocks, while in Fixed-Block Architecture (FBA) devices data is stored in 512 byte
blocks, CKD devices are more common.
An important function of the operating system and access methods in managing how spaces on a DASD
volume is allocated to the files that reside on it. The system must
1.
2.
3.
4.

Keep track of the location of existing files

Be able to add new files to the volume
Allocate additional space to existing file
Remove files from a volume

The information necessary to manage all this is stored in special DASD records called labels.
There are two types of labels
1.

Volume labels the VOL1 label

All DASD volumes must contain a volume label, called the VOL1 label. This label is always in the same
place on a disk volume. It identifies the volume with a volume serial number, vol-ser, which is a unique
six character number. It also contains the disk address of the VTOC.
2.

File Labels

The VTOC (Volume Table Of Contents) is a special file that contains the labels for the files on the volume.
These file labels also called Data set Control Blocks (DSCB) have several formats called Format-1,
Format-2 and so on.
Space Management
An important function of any operating system is managing space. On OS systems a special OS component
called Direct Access Device Space Management DADSM does the space management function. It
automates the process of allocating space to the file.
The drawbacks of DADSM are
1.

Limitation of sixteen free extents. If a file grows beyond this the program will abend, and the file will
have to be reorganised to used fewer extents.

VSAM Concepts

Page 1 of 16

HCL Perot Systems

2.

VSAM Training

When DADSM searches the VTOC for free space it uses a technique called first-fit. This means that
the first free extent that is large enough will be used for the file and not the one that is close to the right
size i.e. best fit. This often leads free extents are broken into smaller pieces rather than searching the
all the DSCB for a free extent closer to the size required.

VSAM Fundamentals
IBM announced VSAM in 1973, but it did not gain wide popularity till almost a decade later. Before
VSAM, IBM mainframe computers used other data management facilities and access methods. Which are
now grouped as non-VSAM dataset organisations to distinguish them from VSAM dataset organisations.
These older methods are also often referred to as Native Access Methods.
Because of the large number of files that existed at that time native access methods, the older access
methods could not be discarded immediately. So, as a strategic step, VSAM and NON-VSAM dataset
organisations had to coexist on the same platform. IBM has a long range plan now to replace all the nonVSAM dataset organisations with VSAM on their mainframes. This means that anyone who has to work on
an IBM mainframe system will certainly need to have knowledge about VSAM.
There are four major processing environments under which VSAM is used.
1.
2.
3.
4.

It can be used as a stand-alone product, VSAM datasets can be created and processed by a powerful
software product called IDCAMS.
Batch application programs in COBOL,PL/1,Assembler etc can access VSAM datasets.
In dataset management, PDS directories, catalogs and generating data groups can be manipulated
through specific IDCAMS commands. GDGs and catalogs are themselves VSAM datasets. Also, the
IDCAMS utility can be used to process older, non-VSAM dataset organisations.
Many major IBM software products, such as CICS, IMS, DB2 and TSO use VSAM datasets in a
majority of applications. In some of them, VSAM datasets are the only ones that are compatible.

VSAM is available under all of IBMs mainframe operating systems MVS,VM, VSE and OS/390. The
MVS implementation of VSAM is the most comprehensive. Also, VSAM datasets can be stored on almost
all standard disk devices, such as 3390, 3380, 3350, 3370 etc. Present and future mainframe software
released by IBM will be designed to process records stored in VSAM datasets.
VSAM provides four types of the organisations along with their respective access methods and utilities.
Access methods are system software that provide technical details to system developers.
Linear Dataset (LDS)
Relative Record Dataset (RRDS) is like a direct file
Entry Sequenced Dataset (ESDS) is like standard sequential file
Key Sequenced Dataset (KSDS) is like an indexed sequential access method file
There four dataset organisations were developed to replace existing non-VSAM datasets, such QSAM,
ISAM, BDAM, QISAM and BSAM, but this could not obviously be done overnight. So VSAM datasets
had to force co-exist with non-VSAM datasets. The VSAM dataset organisations are superior to the native
access methods. VSAM provides for alternate indexes a feature not available in native access methods. It
has an admirable catalog facility that stores more information about VSAM and other datasets. The
powerful AMS utility in VSAM provides a variety of services dealing with catalogs, files, security, file
management etc. It provides comprehensive support for application development in many environments
such as COBOL,PL/1,FORTRAN, ASSEMBLER AND CICS.

VSAM Concepts

Page 2 of 16

HCL Perot Systems

VSAM Training

An overview of the major advantages of using VSAM is as follows :

1.

Very little JCL coding is needed for processing a VSAM file. The DD statement is one-line statement
needing only the DSNAME and DISP parameters.

2.

Records can be accessed through one or more secondary keys using alternative indexes built and
maintained by VSAM.

3.

In KSDS and ESDS, any field can be used to sequentially or randomly process the records

4.

Byte addressing can be used as an alternative method to randomly access and process records in a
KSDS and ESDS are using their relative byte addressing (RBA). This imparts to a disk dataset a
Concept generally associated with main memory and amply increases the processing capabilities of a
VSAM dataset.

5.

Status codes are returned following every I/O operation. Each IDCAMS command returns a condition
Codes.

VSAM Clusters
In VSAM terms, a file is often called a cluster. A cluster is a set of catalog entries that represent a file
catalog.
It consists of two components :
A DATA COMPONENT - which represents the actual records of a file.
An INDEX COMPONENT - which represents the indexes for KSDS.
VSAM Catalog Concepts
VSAM provides a comprehensive catalog facility that stores information about VSAM datasets and other
files.
There are two types of catalogs
MASTER CATALOG
USER CATALOG
Each OS system has just one master catalog but can have an unlimited number of user catalogs.
All user catalogs must be cataloged in the master catalog and all VSAM datasets must be in the master
catalog.
Some MVS installations use a facility called the Integrated Catalog Facility(ICF) instead of VSAM
catalogs. ICF catalogs are similar to VSAM catalogs in operation, the only difference is in the internal
structure and in how they are defined. All of the basic catalog manipulation functions apply to both VSAM
and ICF catalogs.
Under MVS, the high-level qualifier of a dataset name normally indicates the user catalog that owns the
file. For example, a file named DATA.CUSTOMER.MASTER.FILE is cataloged in a user catalog indicated
by DATA. Since the file name indicates the user catalog, no special coding is required to identify it.

VSAM Concepts

Page 3 of 16

HCL Perot Systems

VSAM Training

In some cases, the high-level qualifier and the user catalog name are the same. More often, the high-level
qualifier is an alias of the actual name. For example if DATA is an alias for user catalog named
TRNG.MPS800, any file whose high level qualifier is DATA is cataloged in TRNG.MPS800. And, if
AREA is an alias of TRNG.MPS800, any file whose high-level qualifier is AREA is also cataloged in that
user catalog user. By using aliases, files with different aliases can be cataloged in the same user catalog.
VSAM Space Management
VSAM maintains detailed information about DASD space allocated to VSAM files. This information more
comprehensive and flexible than the equivalent information stored for a non-VSAM file in a VTOC.
Concept of Data Space
VSAM was designed to co-exist with the space management functions provided by the VTOC and
DADSM. For this a concept of data space was introduced. This is an area of a disk volume that is under the
control of the VSAM. To indicate that control, VSAM invokes DADSM to make an entry in the VTOC for
the space. DADSM must be used to allocate or extend a space. Thus, to operating system, the space is just
another file. However, once allocated, VSAM has complete control over subsequent allocations within that
space.
Unique Files
Within a space, VSAM can create sub allocated files. VSAM uses its own space management files to
create, extend, or delete sub allocated files. Alternatively, an entire space can be allocated to a single
VSAM file. This file is called a unique file. It is managed by DADSM rather than by VSAM.
Allocation information is maintained at two places: the VSAM catalog entry for the file and the VTOC
entry for the space that contains the file.
Unique files allow a certain degree of flexibility not available with sub allocated files. VSAM and DADSM
jointly manage all unique files. All I/O operations with the file are done by VSAM. Every unique file has
an entry in the VTOC of the file for the data component and for the index component for a KSDS.
RECORD management under MVS
Record management a major component under MVS is responsible for maintaining the logical records of a
VSAM file. It is used to store records for all four types of VSAM datasets and for alternate indexes and
catalogs.
Record management groups logical records into blocks called control intervals. Control intervals, in turn,
are grouped into control areas.
Control Intervals
The fundamental building block of every component of a VSAM dataset is the control interval (CI). It is
the unit of data VSAM transfers between virtual and disk storage. Its concept is similar to that of blocking
for non-VSAM files. The size of the control interval affects the performance of a VSAM file.
The size of a CI must be between 512 and 32,768 bytes, i.e. 32K. Up to 8K, the CI size must be a multiple
of 512 bytes; beyond that is a multiple of 2K.
When a file is defined, VSAM automatically determines a CI size based on the average size of record
specified and the characteristics of the device on which the file will reside. There could be design
considerations which may need the CI size to be different from what VSAM would have calculated. This
can be done through the AMS utility.

VSAM Concepts

Page 4 of 16

HCL Perot Systems

VSAM Training

Structure of a Control Interval

A CI consists of three parts: one or more logical records, control information and (optionally) unused space.
Logical
Record 1

Record 2

Record 3

Unused Space

Control
Information

The logical records are grouped together at the beginning of the control interval. The control information
occupies the right most part of the CI. If any record in the CI is to be expanded through addition of fields or
increase in filed lengths (ESDS or KSDS) or if another record is to be inserted (KSDS only), this unused
space is adjusted as needed.
Control information consists of two fields:
1.

Control Interval Descriptor Field (CIDF)

It is contained in the rightmost four bytes of each control interval. It consists of two binary fields each two
bytes in length. The right-most two bytes contain the amount of unused space in the CI. The left most two
bytes identify the size of the data area, i.e. the area occupied by the logical records. The CIDF contains a
flag that is set when the control interval is in the process of being updated.
2.

Record Descriptor Fields (RDF)

These are located to the left of the CIDF. Each RDF is 3 bytes long. It consists of two values a leading
control byte and a two-byte numeric value. These fields describe the logical records in the control interval.
In the simplest case, there is one RDF for each record in the Control interval. A RDF can also identify
spanned record segments. The RDF are stored from right to left.
Control Areas
A group of adjacent control intervals is called a control area. A control area can be as small as one track or
as large as one cylinder; usually, an entire cylinder is used. The control area size is determined based on the
amount space that is allocated to the file and the characteristics of the device on which the file will be
stored.
Relative Byte Address
Although uncommon, the records of an ESDS can be processed directly rather than sequentially. Thats
because the record can be identified by a Relative Byte Address RBA. The RBA is an indication of how
far, in bytes, each record is displaced from the beginning of the file. For example, if all the records are 256
bytes in length, the RBA of the first record is 0, of the second is 256, of the third is 512 and so on to the end
of the control interval. Beyond the first control interval, however, records do not have RBAs that are
multiples of 256 because the control information at the end of each record interval is part of the RBA value.
Spanned Records
A record that is larger than a single control interval is called a spanned record, i.e. a spanned record
occupies two or more control intervals. If there is unused space in the second control interval, the extra
space is not available for the other records. Because of this, it is generally preferable to initially specify a
control interval that is larger enough to accommodate the biggest record in the file. A spanned record must
be entirely contained within a control area, which means that a record cannot span across two control areas.
Also spanned records are not allowed in a dataset in which VSAM constructs an alternate index. Spanned
records are possible only in ESDS and KSDS. They are not available in an RRDS.
Characteristics of VSAM datasets

VSAM Concepts

Page 5 of 16

HCL Perot Systems

VSAM Training

Linear Dataset (LDS)

Linear datasets contains Data Component only. The CI sizes of the LDS datasets are always 4K bytes. For
this datasets there is no Control Information. Each Control Interval contains the data of the record.
Relative Record Dataset (RRDS)
The RRDS used for fixed length records. It contains the data component only. Records are stored in
preformatted i.e. numbered as Slots. Each slot contains one RDF. RDF indicates whether the record is
empty or full. It can be access by randomly using relative record number and also possible to access
sequentially.
Entry-Sequenced Datasets (ESDS)
An ESDS is a sequential file in which records are typically retrieved in the order in which they were written
to the dataset and additions are always made at the end of the file.
Although uncommon, records can also be processed directly using a relative byte address (RBA). The RBA
is an indication of how far, in bytes, each record is displaced from the beginning of a file. This type of
processing however is applicable only to non-spanned ESDS records, Since RBA for the spanned CI will
again begin from zero in the new CI.
If there is any space left over in the control interval because the records of that control interval dont
completely fill it, that would not be usable.
Key-Sequenced Datasets (KSDS)
A KSDS is in many ways similar to an ISAM file. Because VSAM has a better index structure and
improved overflow handling most users have converted their applications to VSAM and today it is the
widely used file organisation on IBM mainframes.
A KSDS can be processed sequentially or randomly when used for sequentially processing the records are
processed in the order of the key values in the files index.
A KSDS consists of two components: a data component and an index component. The data component
contains the records and the index component contains the indexes necessary to access the records.
The index component of a KSDS has two parts: a sequence set and an index set. The sequence set is the
lowest level of the index. There is one sequence set for each control area. Each sequence set record contains
an index entry for each CI in the corresponding control area. This index entry contains the highest key
value in the respective CI. Within the sequence set records, index entries are stored in sequence from right
to left. The sequence set is searched to determine which CI in the data component contains a particular
record.
The index set is used to locate sequence set records. Index set records are arranged in one or more levels.
The highest level of an index set always has just one record. Many KSDS files use just one index set
record. Assuming an index-CI size of 512 bytes, that is just enough for 58 sequence set records. That relates
to 58 control areas since each sequence set record corresponds to one control area. Since typically control
areas are one cylinder in size, we can have 58 cylinders of data which is about 32 million bytes on a typical
3350 DASD. If the file is larger than that, additional index set records are created by VSAM as needed, and
these are arranged in levels as required.
The search sequence is as follows :

VSAM Concepts

Page 6 of 16

HCL Perot Systems

1.

The index set is searched to determine which sequence set record to use.

2.

The sequence set record is then searched to locate which control level to use.

3.

Finally, the control interval is searched to locate the needed record

VSAM Training

The pointers used for locating a record in this way are called vertical pointers. VSAM also uses horizontal
pointers in the sequence set of a KSDS to process the file sequentially without using the index set.
In its index entries, VSAM uses a key-compression algorithm to compress the index keys to just about
three or four bytes. This results in considerable saving of space.
Concept of Control Interval Split
The concept is applicable in the case of control intervals containing KSDS files. Free space can be reserved
to accommodate new records within the data component of a KSDS. This can be done in two ways: leave
space within each control interval or leave entire control intervals empty. The free space is defined when
defining a KSDS cluster using AMS.
In a KSDS records are stored in key sequence. When a record is added to a KSDS, it is inserted in its
correct sequential location in the proper control interval, and the records that follow it in the control
interval are shifted
If an insertion is made into a control interval that is already full, some of the records in it are moved into a
free control interval. This is called a Control Interval Split.
Control Area Split
When a record in a KSDS is to be inserted and all the control intervals within a control area are full, a
control area split takes place before a control interval split. To do this, a new control area is allocated,
about half the control intervals from the original control area are moved to the new one, and a new
sequence set record is created for the new control area. Then, the control interval split is performed.
A Control Area split involves a lot of disk I/O, and so it is more prudent to allocate enough free control
intervals to accommodate expected control interval splits.
Since control interval and control area splits affect the performance of the application system using VSAM
datasets, the design of space requirements must take these into consideration while designing the system.
Relative Record Datasets
An RRDS consists of fixed length slots which are sequentially numbered beginning with 1. These numbers
called relative record numbers (RRNs) are used to access the records of an RRDS directly. Each slot either
contains a record or is empty.
The RRN is processed sequentially or directly. In sequential processing, VSAM automatically skips over
empty slots.
Random Processing is based on each records relative position in the file. To access slot in an RRDS in an
application program in COBOL, the RRN must be identified or specified by moving the value to a
designated 4 byte key field in WORKING-STORAGE before attempting an I-O operation.
Because an RRDS doesnt have an index component to search, it can be processed more efficiently than a
KSDS. In RRDS, any individual record can be randomly read or written in exactly one I-O operation
whereas in an KSDS it takes a minimum of two I-O operations.

VSAM Concepts

Page 7 of 16

HCL Perot Systems

VSAM Training

The limitations of RRDS are

1.
2.
3.
4.

Only fixed-length records are allowed

RBA processing is not supported
Standard IDCAMS alternate key processing, like DEFINE AIX is not supported
The slot number to associate with a record is very difficult to determine.

Additions to an RRDS can be done in two ways

1.
2.

New records can be inserted in empty slots in the file. To do so the application program must be able to
identify the empty slots. Thats not always easy to do.
Add them to the end of the file. For example, suppose an RRDS contains 1000 slots. If a record is
written to slot 1001, VSAM allocates an additional control area, preformats the slots in it, then writes
the record. If a record is written to slot 5000 then VSAM will allocate and preformat four more control
areas before it writes the record.
Alternate Indexes

Alternate indexes can be used to access the records of a VSAM KSDS in an order than that of the files
primary key. The dataset over which an alternate index exists is called a base cluster.
Although an ESDS can be used as a base cluster, most alternate indexes are built over key sequenced
datasets.
When an alternate index is associated with one primary key, the alternate key is called a unique key. It can
be associated with duplicate or non-unique keys also.
When an alternate index file is processed with duplicate keys directly. Only the first base cluster record for
each alternate key value is available. For example consider a case in which there is an alternate key for a
department number. In a department there can be more than one employee. When this alternate index file is
processed directly then the first base cluster record is available.
An alternate index is itself a KSDS. If the base cluster is a KSDS, each record in the alternate indexs data
component contains an alternate key value and one or more primary keys for the corresponding in the base
cluster. If the base cluster is an ESDS, each record in the data component contains an alternate key value
and one or more RBAs for the corresponding records in the base cluster.
The index component of an alternate index contains the alternate keys that index the records in the data
component, just as in a standard KSDS.
It is not necessary to upgrade an alternative index each time its base cluster is changed. Upgradable indexes
add considerable overhead to alternate index processing and so alternate indexes are generally rebuilt
rightly to return the alternate indexes to prime-key sequence. In such cases, users must know that changes
to their files will not be reflected in the alternate indexes until the next day. If an automatic upgrade is
required whenever changes are made to the base cluster, then this will have to be clearly specified in the
AMS command.
Access Method Services
Access Method Services or AMS (also known as IDCAMS) is a powerful general purpose utility program
providing a variety of services for VSAM files. AMS is used to
Define VSAM objects such as catalogs, spaces and datasets
List information about VSAM objects.

VSAM Concepts

Page 8 of 16

HCL Perot Systems

VSAM Training

Perform basic file maintenance functions such as copying, printing, renaming or deleting datasets.

AMS is an essential part of VSAM.

Categories of AMS commands
AMS commands come under two categories
Functional Commands
Modal Commands
Functional commands instruct AMS to actually do something, while modal commands control the
execution of functional commands.
AMS Command
-------------------DEFINE MASTERCATALOG
DEFINE USERCATALOG
DEFINE CLUSTER
DEFINE ALTERNATEINDEX

Function
----------Defines a master catalog
Defines a user catalog
Defines a VSAM file
Defines an alternate index

DEFINE PATH

Defines the path to relate an alternate index to its base cluster

BLDINDEX
ALTER

Builds an alternate index

Changes information specified for a catalog, cluster, alternate
index or path

DELETE

Removes a catalog entry for a catalog, cluster, alternate index

or path

EXPORT
IMPORT
LISTCAT

Produces a transportable file

Copies a previously exported file
Lists information about datasets

PRINT

Prints the contents of a VSAM or non-VSAM file

REPRO

Copies records from one file to another

Functional Commands
IF

Controls the flow of command execution by testing condition

Codes returned by functional commands

SET

Controls the flow of command execution by altering condition

codes returned by functional commands

PARM

Sets option values that affects the way AMS executes

Coding AMS Commands

The general format for AMS commands is
Verb parameters..............

VSAM Concepts

Page 9 of 16

HCL Perot Systems

VSAM Training

Where verb is a command (DEFINE CLUSTER, for example), and parameters supply additional
information that tells AMS what should be done.
AMS commands can be coded between columns 2 and 72.
To continue a command from one line to another, a hyphen has to be coded after the last parameter on that
line. There should be at least one blank between the end of the parameter and the hyphen.
Parameters can be abbreviated. Some abbreviations are
CONTROLINTEVALSIZE
ALTERNATEINDEX

as CNVSZ OR CISZ
as AIX

Many parameters need a value to be coded in parentheses like

RECORDS(300)
KEYS(5 0)
ENTRIES(file 1, file 2, file 3)
Condition Codes :
Each AMS functional command issues a condition code that tells you whether or not the command was
successfully executed. There are five standard IBM condition codes
0 Successful execution ; no errors
4 A minor problem was encountered but AMS was able to complete the command
8 A major problem was encountered, execution is not likely to be successful
12 A major problem was encountered, AMS could not complete the command
16
Disaster Processing terminated
As it executes, AMS maintains two conditional codes, LASTCC and MAXCC. LASTCC always
represents the condition code issued by the most recently executed AMS command, while MAXCC
represents the highest condition code returned by any command in the AMS job step. The IF command
provides conditional processing based on LASTCC or MAXCC and the SET command can be used to
modify either of these at any time.
Example : IF LASTCC > 0 THEN SET MAXCC = 16
IF MAXCC <= 4 THEN PRINT..
Invoking AMS
AMS can be invoked in MVS under two environments OS and TSO.
Example : Under OS
//LISTCAT JOB
//
EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT = a
//SYSIN DD *
DEFINE CLUSTER(NAME..
USER-ID=
.....)
/*
//

VSAM Concepts

Page 10 of 16

HCL Perot Systems

VSAM Training

Under TSO

READY
Define usercatalog
(The lower case text represents data entered by the terminal operator, while the upper case text is a
TSO message)
AMS Commands
| Commands for defining catalogs and space
1.

DEFINE USERCATALOG (NAME(entry-name) VOLUME (vol-ser)

[OWNER(Owner-id) ]
[FOR(days) | TO (days) ]
[(CYLINDERS)
{TRACKS } (Primary [secondary] ) ]
{BLOCKS}
{RECORDS}
| DATA ([{CYLINDERS}
{TRACKS}
{BLOCKS}(Primary [secondary])
(REOCRDS)
|CATALOG (name[/password])]

Explanations :
NAME : Required, Specifies the name of the catalog
VOLUME : Required, Identifies the Volume which will contain the catalog
OWNER : Optional, One to eight character owner-id for the catalog
FOR : Optional, Specifies a retention period (dddd) OR an expiry date (YYDDD)
TO: for the catalog
Primary : Specifies how much space to allocate initially to the catalog or component, expressed in
cylinders, tracks, records or blocks.
Secondary : Optional, Specifies the secondary space allocation
CATALOG : Optional, specifies the name and password of the master catalog, required to define a user
catalog if the master catalog is password protected.
Example :
DEFINE USERCATALOG (NAME(AR.USER.CATALOG)
VOLUME(VOL400)
CYLINDERS(200 15))
DATA (TRACKS(60 15))
CATALOG (VSAM.MASTER.CATALOG/xxxxxxxxxx)
The DEFINE ALIAS command
DEFINE ALIAS (NAME(entry-name)
RELATE(entry-name[/password]))
[CATALOG(name[/password])]

VSAM Concepts

Page 11 of 16

HCL Perot Systems

VSAM Training

Explanations :
NAME
RELATE
CATALOG

Required, Specifies the name of the alias to be specified)

Required, Specifies name and password of an existing catalog with which the alias name
is to be associated.
Optional. Name and Password of master catalog only if it is password protected.

Example :
DEFINE ALIAS (NAME(BILLING)
RELATE(AR.USER.CATALOG))
CATALOG(VSAM.MASTER.CATALOG/xxxxxxxx)
Example for defining space :
The DEFINE SPACE parameter :
DEFINE SPACE (VOLUMES(VOL400 VOL500)
CYLINDERS(200 20) )
CATALOG(AR.USER.CATALOG)
2.

COMMAND TO DEFINE CLUSTERS

Example :
DEFINE CLUSTER(NAME(MATL.PUR.MAST)
OWNER(PRS)
INDEXED
RECORDSIZE(200)
KEYS(6 0)
VOLUMES(MPS300)
UNIQUE)
DATA(NAME(MATL.PUR.MAST.INDEX))
Example for Some Commands
1. DEFINE AIX (NAME(MATL.PUR.MAST.SSN.AIX)
RELATE (MATL.PUR.MAST)
OWNER(PRS)
TO(99340)
KEYS(9 12)
UNIQUEKEY
NOUPGRADE
VOLUMES(MPS300)
UNIQUE)
DATA (NAME(MATL.PUR.MAST.AIX.DATA)
CYLINDERS(1))
INDEX(NAME(MATL.PUR.MAST.SSN.AIX)
UPDATE)

2. BLDINDEX INDATASET(MATL.PUR.MAST)
OUTDATASET(MATL.PMAST.SSN.AIX) CATALOG(MATL)

VSAM Concepts

Page 12 of 16

HCL Perot Systems

VSAM Training

3.

LISTCAT ENTRIES(MATL.PUR.MAST)
LISTCAT ENTRIES(MATL.*.MAST)
LISTCAT LEVEL(MATL)

4.

ALTER MATL.VENDOR.MAST
NEWNAME(MATL.VENDMAST)

5.

DELETE MATL.PUR.MAST
PURGE

6.

PRINT INDATASET (MATL.PUR.MAST)

CHARACTER
SKIP(23)
COUNT(6)

7.

REPRO INDATASET(MATL.PUR.MAST)
OUTDATASET(MATL.PURMAST.REPRO)

Application Programming in COBOL

The compiler version for COBOL, whether VS COBOL or VS COBOL II. It, does not directly affect the
way VSAM files are processed in COBOL.
Entries in the ENVIRONMENT and DATA divisions for VSAM files.
To identify a VSAM file in a COBOL program, entries in the Environment and Data divisions are coded
just as for a non-VSAM file. The SELECT statement is coded in the Input-Output section of the
Environment division. FD entries are made in the File Section of the Data division to describe the files
records.
The SELECT Statement
This statement has two functions for VSAM files. It relates the internal name the COBOL program uses to
an external name the system uses to identify the file at execution time. It specifies how the file is organized
and how the program will execute it.
The format for the SELECT statement is
SELECT file-name

ASSIGN TO assignment-name
ORGANIZATION IS (sequential/indexed name)
[ACCESS MODE is (sequential/random/dynamic)]
[RELATIVE KEY is data-name ]
[RECORD KEY is data-name]
[PASSWORD is data-name]
[ALTERNATE RECORD KEY is data-name]
[PASSWORD is data-name]
[WITH DUPLICATES]
[FILE STATUS is data-name]

The ASSIGN Clause

Specifies an assignment name for the file. This name is used in the JCL on a DD statement for OS/MVS to
allocate the file. The format of the assignment name depends on the operating system and the files
organisation. For OS/MVS it is as follows :

VSAM Concepts

Page 13 of 16

HCL Perot Systems

File Organisation
KSDS
RRDS
ESDS

VSAM Training
Syntax
[Comment-]name

Example
CUSTMAST

[Comment-]As-name

AS-INVTRAN

The ORGANISATION Clause

Coded to indicate a VSAM files organisation SEQUENTIAL, INDEXED or RELATIVE. The value
coded must agree with the organisation specified for the file when it was defined. The ACCESS MODE
clause.
Coded to specify how the program will process the file. For ESDS is must be SEQUENTIAL. For KSDS or
RRDS it can be SEQUENTIAL or RANDOM. If DYNAMIC is specified for KSDS or RRDS, the
program can alternate between sequential and random access.
The Key Clause
1.
2.

RELATIVE KEY only for RRDS; RECORD KEY and ALTERNATE KEY only for KSDS. None of
these clauses are applicable for ESDS.
For a RRDS, the RELATIVE KEY clause is coded for random or dynamic access; it is optional for
sequential access. In it, a working storage field is named that will contain a relative record number; for
example
05 RELATIVB KEY PIC 9(8) COMP.
It is recommended that the relative key be defined as an unsigned binary full word. This can be
defined as a packed decimal field also.

3.

For a KSDS, the RECORD KEY clause must be coded to name the files primary key field, regardless
of the files access mode. This field must be defined within one of the record descriptions coded in the
FD entry for the file.

4.

The field named in each ALTERNATE RECORD KEY clause must be within the files record
descriptions, and an alternate index that uses field must exist. If the alternate index allows non-unique
keys, WITH DUPLICATES must be specified

5.

If the ALTERNATE RECORD KEY clause is coded, a DD statement must be included in the JCL for
the path associated with each alternate index specified.

The PASSWORD Clause

1.

Used if the file is protected by VSAM password. Only one (the highest level) password needs to be
specified. Two or more will be required if alternate keys are specified for a KSDS.

2.

For a RRDS or an ESDS the clause may be coded anywhere in the SELECT statement. For a KSDS it
must be coded right after the RECORD KEY or ALTERNATE RECORD KEY clause. To supply a
password for a KSDS base cluster, it is coded after the RECORD KEY Clause. To supply a password
clause is coded right after the ALTERNATE RECORD KEY clause, but before the WITH
DUPLICATES clause, if it is included.

3.

In the PASSWORD clause, a field with eight bytes is named. This value is checked when an OPEN
statement is issued. The value must be at a high enough level to permit the COBOL operations on the
file.

VSAM Concepts

Page 14 of 16

HCL Perot Systems

VSAM Training

The FILE STATUS Clause

1.
2.

This clause specifies a field thats updated by VSAM after each I/O statement for the file is executed.
The field must be defined in the working-storage and PIC must be XX.
When an I/O statement executes successfully, VSAM puts 00 in the FILE STATUS field. But when an
error condition occurs, VSAM puts a non-zero two digit error code in FILE STATUS field. The
program written should examine the FILE STATUS field after each I/O statement to determine whether
an error occurred, and if so, what action to take.

File Section Entries for VSAM files

As for any other file, an FD entry has to be coded. The only entry required is LABEL RECORDS ARE
STANDARD. Following this entry, at least one record description for the file must be coded. If the file is a
KSDS, that record description must include the record key field and all alternate key fields specified in the
files SELECT statement.
SELECT EMPMAST ASSIGN TO EMPMAST
ORGANISATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS EM-EMPLOYEE-NUMBER
ALTERNATE RECORD KEY IS EM-LAST
NAME WITH DUPLICATES
ALTERNATE RECORD KEY IS
EM-PASSPORT-NUMBER
FILE STATUS IS EMPMAST-STATUS
FD EMPMAST
LABEL RECORDS ARE STANDARD.
01 EMPLOYEE MASTER RECORD.
05 EM-EMPLOYEE-NUMBER
05 EM-LAST-NAME
05 EM-PASSPORT-NUMBER

PIC 9(5).
PIC X(15).
PIC 9(10).

Procedure Division Statements for VSAM files.

1.
2.
3.

4.

The statements that are used are OPEN,CLOSE,READ, WRITE, REWRITE, DELETE and START.
For as reusable the OUTPUT can be specified. If EXTEND is specified, records that exist in the
reusable file will be retained.
For working with alternate indexes, we need to know two things
How to switch from the primary key to an alternate key changing the key of reference.
How the random and sequential versions of the READ statement differ when the alternate key is used.
The key of reference can be changed by using a START statement in the case of sequential or dynamic
access and by coding the KEY clause on a random READ statement for random or dynamic access.
Example: 1. START EMPMAST
KEY IS EQUAL TO EMP-PASSPORT NUMBER
READ EMPMAST
KEY IS EMP-PASSPORT NUMBER.

VSAM Concepts

Page 15 of 16

HCL Perot Systems

VSAM Training

In the first example the file is positioned to the record indicated by the employee passport number
alternate key. Then subsequent sequential READ statement will retrieve records in passport number
sequence. To switch back to the primary key, another START statement is issued, this time specifying the
RECORD KEY field or omitting the KEY clause altogether.
In the second example, the employee master is read based on the contents of the passport number. The
passport number alternate key becomes the key of reference for subsequent sequential READ statements.
The key of reference applies only to the sequential READ statements; a subsequent random READ
statement uses the primary key field unless the KEY clause is coded again.

E ND

VSAM Concepts

Page 16 of 16