VSAM Concepts

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. Keep track of the location of existing files2. Be able to add new files to the volume3. Allocate additional space to existing file4. 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


2. 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 non-VSAM 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. It can be used as a stand-alone product, VSAM datasets can be created and processed by a powerful software product called IDCAMS.

2. Batch application programs in COBOL,PL/1,Assembler etc can access VSAM datasets.3. 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.

4. 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 IBM’s 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 fileEntry Sequenced Dataset (ESDS) is like standard sequential fileKey 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.



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 CATALOGUSER 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.



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.



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. That’s 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 RBA’s 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

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 don’t 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 file’s 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 :

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

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 doesn’t 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.

The limitations of RRDS are

1. Only fixed-length records are allowed2. RBA processing is not supported3. Standard IDCAMS alternate key processing, like DEFINE AIX is not supported4. The slot number to associate with a record is very difficult to determine.

Additions to an RRDS can be done in two ways

1. 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. That’s not always easy to do.

2. 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 file’s 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 index’s 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.

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

AMS is an essential part of VSAM.Categories of AMS commandsAMS commands come under two categories

Functional CommandsModal Commands

Functional commands instruct AMS to actually do something, while modal commands control the execution of functional commands.

AMS Command Function-------------------- -----------

DEFINE MASTERCATALOG Defines a master catalogDEFINE USERCATALOG Defines a user catalogDEFINE CLUSTER Defines a VSAM fileDEFINE ALTERNATEINDEX Defines an alternate index

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

BLDINDEX Builds an alternate indexALTER 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 Produces a transportable fileIMPORT Copies a previously exported fileLISTCAT 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..............

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 as CNVSZ OR CISZALTERNATEINDEX 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 errors4 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 successful12 A major problem was encountered, AMS could not complete the command16 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=



.....)/*//

Under TSO

READYDefine 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 catalogVOLUME : Required, Identifies the Volume which will contain the catalogOWNER : Optional, One to eight character owner-id for the catalogFOR : Optional, Specifies a retention period (dddd) OR an expiry date (YYDDD)TO: for the catalogPrimary : 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 allocationCATALOG : 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])]

Explanations :

NAME Required, Specifies the name of the alias to be specified)RELATE Required, Specifies name and password of an existing catalog with which the alias name

is to be associated.CATALOG 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)INDEXEDRECORDSIZE(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)

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 file’s 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-nameORGANIZATION 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 file’s organisation. For OS/MVS it is as follows :

File Organisation Syntax ExampleKSDS [Comment-]name CUSTMASTRRDSESDS [Comment-]As-name AS-INVTRAN

The ORGANISATION Clause

Coded to indicate a VSAM file’s 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. RELATIVE KEY only for RRDS; RECORD KEY and ALTERNATE KEY only for KSDS. None of these clauses are applicable for ESDS.

2. 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 file’s primary key field, regardless of the file’s 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 file’s 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.

The FILE STATUS Clause

1. This clause specifies a field that’s 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.

2. 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 file’s SELECT statement.

SELECT EMPMAST ASSIGN TO EMPMASTORGANISATION IS INDEXEDACCESS MODE IS DYNAMICRECORD KEY IS EM-EMPLOYEE-NUMBER

ALTERNATE RECORD KEY IS EM-LASTNAME WITH DUPLICATES

ALTERNATE RECORD KEY IS EM-PASSPORT-NUMBER FILE STATUS IS EMPMAST-STATUS

FD EMPMASTLABEL RECORDS ARE STANDARD.

01 EMPLOYEE MASTER RECORD.

05 EM-EMPLOYEE-NUMBER PIC 9(5). 05 EM-LAST-NAME PIC X(15). 05 EM-PASSPORT-NUMBER PIC 9(10).

Procedure Division Statements for VSAM files.

1. The statements that are used are OPEN,CLOSE,READ, WRITE, REWRITE, DELETE and START.2. For as reusable the OUTPUT can be specified. If EXTEND is specified, records that exist in the

reusable file will be retained.3. 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.

4. 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 EMPMASTKEY IS EQUAL TO EMP-PASSPORT NUMBER

READ EMPMAST KEY IS EMP-PASSPORT NUMBER.

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


Documents

VSAM Concepts