Download doc - Basic VSAM

Transcript
Page 1: Basic VSAM

VSAM:

The Course guide

By Dan O'DeaUpdated for zOS April 28, 2003

Page 2: Basic VSAM

VSAM: Virtual Storage Access MethodWhat Is It and What Do I Need to Know About It?

The Basic Structure of VSAM

VSAM has four types of files:

ESDS, Entry Sequenced DataSets, replace sequential files; RRDS, Relative Record DataSets, replace direct access files; KSDS, Key Sequence DataSets, replace ISAM indexed files; LDS, Linear DataSets, designed to be a replacement for partitioned files

(PDSes) and are the file types used for DB2 databases.

We'll talk about each of these in turn. The LDS is covered first because the DB2 organization takes precedence.

The LDS

The LDS is similar to an ESDS processed at the CI level. VSAM treats an LDS as unformatted blocks in 4K CIs. A cluster component is defined over the single data component to provide a common structure for file access. VSAM does not support record-level access for an LDS. If record-level processing is attempted, an error results.

COBOL does not support LDSes. These access modes apply to LDSes:

CI access is the only access allowed. The CI can be addressed by RBA or sequentially. VSAM treats all bytes in the CI as data bytes. The application is solely responsible for managing the data;

Sequential processing can be forward or backward; Direct processing can be used if the relative byte address (RBA) for a

specific CI is known. VSAM can return the RBA of a CI when the record is initially written to the file.

Alternate indexes cannot be built over an LDS.

All bytes of a CI are considered data. When the CI is retrieved, the application is free to handle the data as it sees fit. From VSAM's point of view, the CI is simply rewritten back where it was in the file.

An LDS can be used as a reusable work file.

2

Page 3: Basic VSAM

The ESDS

The ESDS is almost the same as a sequential access file, with the addition of alternate index support providing keyed access to sequential data records.

A VSAM ESDS requires more overhead than a QSAM file, but requires less time to perform an I/O. If I/O time is not an issue, there is no need to pay for the extra CPU overhead.

An ESDS is a single data component containing data records. A cluster component is defined over the data component to provide a common structure for file access. These are the capabilities and limitations of an ESDS:

Sequential processing, either forward or backward; Direct processing via a relative byte address (RBA). VSAM can be asked to

return the RBA of a record when it is first written; Direct processing by key using an alternate index. The records can be

retrieved either directly with the key, or sequentially in alternate key order.

Alternate indexes (AIXes) can be built over the VSAM ESDS, allowing all the expected capabilities of using keyed access. Up to 255 AIXes can be built over a single ESDS. These indexes can be either unique or non-unique.

COBOL does not formally support the alternate index. However, if you force access to the ESDS using its AIX, COBOL treats the file as if it were a KSDS. The file cannot then be read in its normal sequential order by the program.

The following update capabilities and limitations are features of the ESDS:

Existing records can be updated and rewritten back to their original position as long as the record length has not changed;

New records are written at the end of the file. New records cannot be inserted among existing records;

Records cannot be physically deleted. To reclaim space from logically deleted records, the file must be reloaded.

Free space in an ESDS has no meaning, because records cannot be deleted or change in length. It is ignored by AMS when defining the file.

ESDS files can be defined as reusable work files. For more information on reusability, see The Complete Source Book for VSAM File Structures cited in the bibliography.

3

Page 4: Basic VSAM

The RRDS

The RRDS is almost the same as a BDAM file. Like the ESDS, the RRDS is not in common use for several reasons. In addition to the lack of familiarity with RRDSes, there is the question of resource use. While a VSAM RRDS requires more overhead than a BDAM file, it requires less time to perform an I/O. If I/O time is not a consideration, there is no need to pay for the extra CPU overhead. In addition, a BDAM file takes less disk space than an RRDS.

An RRDS with a fixed record length has a single data component containing the data records. A cluster component is defined over the data component to provide a common structure for file access. Records are referenced using a logical numbering scheme.

An RRDS with a variable record length looks just like a KSDS, with a data and index component. In a variable-length RRDS, records are prefixed by a VSAM-created record number. When you look at a catalog listing, the record length is four bytes greater than you expect. The number field is not accessible by a programmer, but a record may be referenced by its record number.

An RRDS is usually accessed directly, using the record number. It can also be read in relative record number sequence. VSAM returns the record number with any access if requested.

Alternate indexes cannot be built over an RRDS.

The following update capabilities and limitations are features of the RRDS:

Existing records can be updated and rewritten back to their original position. The record length can be changed if the file was defined with a variable record size;

New records can be written to any record slot not currently holding a record;

Records can be deleted. For a fixed-length RRDS, VSAM rewrites the slot with binary 0s. For a variable-length RRDS, VSAM deletes the record as if the file were a KSDS.

Free space in a fixed-length RRDS has no meaning. In a variable-length RRDS, free space functions as it does in a KSDS.

RRDS files can be used as reusable work files.

4

Page 5: Basic VSAM

The KSDS

A KSDS has two components: a data component containing the data records, and an index component. The index component is built and maintained by VSAM to provide random access to the data component. A cluster component is defined over the data and index components to provide a common structure for file access.

Below are the capabilities and limitations of a KSDS:

Direct processing by key, using the normal index or an alternate index; Sequential processing, either forward or backward, in key order; Direct processing via an RBA. VSAM can return the RBA of a record when

the record is first written.

Alternate indexes (AIXes) can be built over the KSDS, allowing all the normal capabilities of using keyed access. Up to 255 AIXes can be built over a single KSDS. These indexes can be either unique or non-unique.

The following types of update processing can occur with a KSDS:

Existing records can be updated and replaced in their original position. The length of the existing record can be changed as long as it's not larger than the file’s maximum record length. When a record is made shorter, records to the right are shifted left to reclaim the free space created by the changed record length. When a record is made longer, records to the right are shifted right. If there's not enough free space to the right a CI split, and possibly a CA (control area) split, occurs. CI and CA splits are discussed later;

New records can be written anywhere in the file, with the key determining where the record goes. When records are inserted between existing records and there's not enough free space, CI and maybe CA splits occur to fit the new record. If records are being inserted at the end of a file, free space is reserved as records are added (a "resume load");

Records can be physically deleted, causing free space to be reclaimed by shifting records to fill the gap(s) in the CI. If a CI is totally emptied by delete requests, VSAM marks the CI as "free." It can then be used as a candidate for future CI splits.

KSDS files can be used as reusable work files.

5

Page 6: Basic VSAM

VSAM Record Blocking Concepts

VSAM uses a double blocking system. First, user data records are collected into appropriately sized logical blocks called Control Intervals (CI). The CIs are then broken down to physical blocks. These physical blocks are always a multiple of 512 bytes.

For example, a file with 200-byte records could be put into a VSAM file with a CI size of 2,048 bytes, using about 97% of the data space. The data is then written as a single block of 2,048 bytes. The process works in reverse during a read. VSAM handles all blocking and deblocking of records, totally hidden from the user program.

In the appendices, I have included a list of allowable CI sizes, their physical record sizes, and other information on how VSAM stores data on 3390 DASD.

The user should pick a CI size matching the data record size and application processing needs. VSAM selects the correct physical record size to maximize the use of DASD space for that CI size.

When a CI is read, VSAM uses an I/O chaining process to make sure the entire CI is read in one I/O. VSAM may thus read more than one CI of data as if it were in the same I/O.

Loading and Maintaining an ESDS

During initial loading of an ESDS, CIs are loaded as full as possible, from left to right through the CI, in the physical order they are received in. At the end of each CI are two fields, the RDF and CIDF; we’ll discuss them later. Any unused bytes, from the right end of the last record to the left-most RDF, are filled with binary zeroes. There is no free space in the file except after the last record.

Records may be added. VSAM places these records at the end of the file in physical sequence. Once in the file, a record may be updated as long as its length doesn't change. The changed record is replaced at the RBA it came from. If records are deleted, the user program is responsible to mark the records and process them as deleted. VSAM does not delete records from an ESDS.

6

Page 7: Basic VSAM

Loading and Maintaining a KSDS: Free Space

During initial load of a KSDS, CIs are loaded from left to right in ascending key sequence. For this reason you must sort the records into ascending key order prior to loading them.

If the DEFINE command had a free space argument, or the FREESPACE parameter was changed with ALTER, records are loaded up to, but not beyond, the free space "high water mark" in each CI. If the FSPC parameter includes control area (CA) free space, empty CIs are left at the bottom of the CA.

You might ask how VSAM determines the high water mark for free space. Let's assume you have a CI size of 4096 bytes and your records are all 200 bytes long. If you had no free space, the 4K CI could hold 4096/200, or 20, records (since you can't store part of a record, always truncate the decimals).

Let's give the file 20% free space for future growth. During the initial load (or later resume load), VSAM guarantees each CI has at least 20% of its space left empty.

To find out how many bytes are left free, multiply the CI size by the FREESPACE percentage. Then subtract that number from the CI size to get the number of bytes VSAM lets you use.

The final step is to divide the usable bytes by the record length to find out how many records actually fit into the CI. Don't forget to truncate.

So, given: CISZ 4096, RECSZ (200 200), FSPC(20 10):

4096 bytes * 20% = 819.2, or 819 bytes free per CI; 4096 bytes - 819 bytes = 3,277 bytes usable; 3277 bytes / 200 bytes = 16.385, so 16 records of 200 bytes fit into a CI; 16 records * 200 bytes = 3,200 bytes; 4096 bytes - 3,200 bytes = 896 total bytes of free space.

See how VSAM reserved more bytes than you might expect? We'll discuss this in more detail later. For now, there are two important points you need to know about free space:

1. Free space gives you room to add records to the file after its initial load;2. Free space is observed only during initial load or resume load.

7

Page 8: Basic VSAM

Free Space Usage During Normal File Activity

After the initial load, all the following options are possible within the reserved free space. COBOL verbs are used in the descriptions.

Updating existing records. When a program wants to update an existing record, it must issue a keyed READ. VSAM searches the index to locate the data CI containing the record, and then searches the records in the CI from left to right for an equal key match. When the record is located, it is returned to the user program to be updated. To put the record back into the file, a REWRITE is issued.

If the key is changed as part of the update, and the changed key is new to the file, a WRITE rather than a REWRITE is needed. A REWRITE will fail. If the new key already exists, a REWRITE works only if the file was opened as RANDOM or DYNAMIC (as specified in the SELECT clause).

Existing records made longer. If the updated record is longer than it was before it can still be rewritten back to the file, as long as the new length is not greater than the maximum record length of the file. When the REWRITE is issued, VSAM compares the change in length to the amount of free space remaining in the CI.

If there is enough free space to put the record back where it was, any records to the right of the one being updated are moved to the right by enough places to make room for the longer record. The CI is then written back to the file.

If there is not enough room for the longer record, VSAM does a CI split. We'll discuss the CI split later.

Shortening existing records. If the program makes the record shorter, a REWRITE is issued without restrictions. VSAM determines the amount of change in the record's length, and then rewrites the record. All records to the right of the updated record are shifted left to reclaim the bytes no longer used by the updated record. That combines all free space at the end of the CI.

Deleting an existing record. If a program needs to delete a record, the key must be known and specified in a DELETE call. COBOL issues a READ to find the record. VSAM moves all records to the right of the deleted record to the left by a number of bytes equal in the record to be deleted. That combines all free space at the end of the CI.

If the record being deleted is the last record in the CI, the CI is reclaimed as a free CI. It can then be used as a candidate for a CI split.

8

Page 9: Basic VSAM

Usage of Free Space during Normal File Activity (cont'd)

Inserting a new record. The program must issue a WRITE statement. Internally, VSAM performs a READ to locate the proper CI to contain the new record. When the CI is located, it's read into a data buffer, where VSAM searches it for record keys to determine the "point of insertion" for the new record. Keep in mind, all records must be in ascending key sequence.

Once VSAM determines the point of insertion, it compares the number of free space bytes in the CI to the length of the record. If there is enough space to contain the record, VSAM moves all the existing records to the right of the point of insertion toward the end of the CI. That provides enough room to insert the new record. If there is not enough space, VSAM schedules a CI split.

If the record to be inserted has a key greater than that of the record at the end of a given CI but less than that of the record at the beginning of the next CI, VSAM sometimes inserts the new record at the end of one CI but other times at the beginning of the next CI because of key compression in the index.

9

Page 10: Basic VSAM

Index Structure of a KSDS

A VSAM KSDS consists of two components: one containing data and one being an index used to locate data records in the data component. Here is a graphic showing the structure of an index. This is not the actual physical model, but rather a logical point of view. In other words, the figure shows how VSAM searches for a data record.

Within the data component CIs are grouped into a "block" called a control area (CA). The CA provides a handy logical unit to index. Above each CA (logically speaking), the index begins with a group of records called the sequence set. Each sequence set record points to a CI within the CA below it. The sequence set is also called "index level 1". There are an equal number of CIs and sequence set records in the CA. For example, if the CA contains 90 Cis, the sequence set contains 90 sequence set records. Each index entry consists of the high key in the rightmost record of the indexed CI and a pointer (CI number) to that CI. On the next page is a conceptual diagram of how that works.

10

Page 11: Basic VSAM

KDSD Indexing (cont'd)

If the data component has more than one CA (thus more than one sequence set record), there must be another level above the sequence set. This higher level contains key/pointer entries just like Level 1, but references the sequence set below it rather than the data component. In other words, on level 2 the index records contain the highest key in the corresponding sequence set record below it, and a CI pointer to the index CI containing that sequence set record.

If there are large numbers of sequence set records, one level 2 record is not large enough to hold all necessary entries. In this case, there must be more than one Level 2 record and at least one index set record pointing to each Level 2 record. This new level is, of course, Level 3. All index levels above the first (the sequence set) are collectively called the index set.

This structure pyramids upward until there is only one index record at the top level.

11

Page 12: Basic VSAM

Retrieving Records from a KSDS

When your program makes a READ call to a KSDS, VSAM first reads the highest-level index record into an index component buffer. The location of the highest-level index record is found using the HI-LEVEL-RBA field in the index's catalog entry. The search key is compared against the entry keys within the sequence set record from left to right, looking for the first key higher than the search key. When that key is found, the RBA pointer associated with it is used to get the appropriate record from the next lowest index level. That continues through the index set until a sequence set record is reached.

The search through the sequence set works the same way as the index set search. When a hit occurs, the RBA of the data component CI is returned to VSAM, which uses that to get the CI where the record should reside. When the CI is read into the data component buffers, VSAM deblocks the CI and return the requested record to the program.

VSAM CI/CA Split Processing

For a long time IBM had the arrogant philosophy "My way or the highway," resulting in abends when your job violated arbitrary standards. For example, you can only have 16 extents on a non-VSAM file, with a resulting B-37 abend when you try to use more.

In VSAM, the new philosophy seems to be "The user is always right" and extra effort is spent to accomplish the I/O request. A KSDS's distributed free space allows for additions of new records or changes to existing records. When the room runs out, some method of adding more room must be used to prevent interruptions to the user program.

In the old ISAM overflow method, inserts of records happened immediately, but that caused reads to slow down drastically after just a few inserts. That's backward, considering you need to read a record far more often than you need to insert it.

In VSAM, a new concept called "cellular splitting" was introduced. VSAM tries to split a CI to make room for a new record. If that fails, a CA split is done followed by a CI split.

There are two types of splitting strategies, Normal Insert Strategy (NIS) and Sequential Insert Strategy (SIS). As you might expect, NIS is used by default. SIS must be specifically coded for, and is beneficial when mass sequential inserts are requested.

12

Page 13: Basic VSAM

KSDS CI and CA Splitting Concepts: The CI split

When a record insert cannot be completed due to lack of free space, VSAM tries to split the CI to make room. In NIS CI splits, VSAM:

Turns on the "busy bit" in the CI and writes it back to the file. That prevents another program modifying the CI while the split is happening;

Checks the entries in the sequence set record for this CA to locate a free CI; If there is a free CI in this CA:

A new CI is created in the buffer. There is no need to read the free CI because it contains only binary 0s;

VSAM finds the mid-point of the CI to be split at the nearest record boundary. All records to the right of this point are moved to the new CI. Both CIs now have approximately 50% free space;

The insert is performed as a normal insert into the old CI. This includes turning off the "busy bit" on the CI being updated;

The CA's sequence set record is updated to show the old CI's new highest key and the new CI now having data in it;

The new CI is written into its old location; The old CI is written into its old location.

If there is not a free CI in the same CA, a CA split must occur. VSAM performs a CA split, and then returns to perform the CI split.

An example of this would be helpful.

13

Page 14: Basic VSAM

KSDS CI and CA Splitting Concepts: The CI split (cont'd)

Figure 2.10 shows the original content of the file. Say an update program is run containing a record insertion with the key 10776. Using a key search VSAM finds the destination for the record is CI #02. The point of insertion is between keys 10775 and 10777.

VSAM checks the free space at the end of the CI. Since there is none, a CI split is required. A sequence set search is done, and VSAM determines CI#08 is free and can accept a split.

14

Page 15: Basic VSAM

KSDS CI and CA Splitting Concepts: The CI split (cont'd)

The midpoint of the CI is found to be between records 10762 and 10764. All records to the right of record key 10762 are moved to the new version of CI #08 in the buffer. Since there is room in the new CI for the record key 10776 between 10775 and 10777, the insert takes place at the time CI #08 is filled. Figure 2.11 shows the file after the CI has been split but before the sequence set record has been updated.

15

Page 16: Basic VSAM

KSDS CI and CA Splitting Concepts: The CI split

Finally, the sequence set record is updated to show the new high keys for each CI and to show the logical sequence of keys. Note how CI #08's sequence set record now resides between records for CIs #02 and #03. That shows the logical key sequence should the file be read sequentially.

16

Page 17: Basic VSAM

KSDS CI and CA Splitting Concepts: the CA split

In NIS mode, a CA split only occurs during a CI split if VSAM finds the CA does not have any free CIs. NIS CA splits work like this:

A free CA must be found. VSAM checks the catalog's HURBA and HARBA. If the HURBA is less than the HARBA, VSAM knows there is at least one free CA between the end of the data (HURBA) and the end of the file's present allocation extent (HARBA). The first CA beyond the HURBA is selected as the destination for a CA split;

The CIs in the bottom half of the old CA must be located for movement into the new CA. Because it is necessary to keep the data in logical sequence, the bottom logical half of the CI, not the bottom physical half, is moved. VSAM locates the midpoint of the CA's sequence set and moves all CIs beyond that point into the new CA;

VSAM then begins moving the CIs from the old CA to the new one. This is a long process. First, a read I/O is required each time an old CI is moved if it is not already in a data buffer. Second, a write I/O is required each time the set of data buffers is full. Third, since (more than likely) the target CI is quite far away in the DASD from the source CI, there is a large time spent on disk head seek time. For example, on a 4K CI size there are 180 CIs per CA, half of which need to move. Assuming the IBM defaults of two data buffers, this means 180 I/O (1 read/write pair per CI) plus 90 disk seeks in each direction between source and target CAs. At a seek time of 9.5ms and an I/O time of (about) 3.9ms for a 4K CI, that adds up to over 1.5 seconds to perform a CA split's data moves. Ouch!

Once the data has been moved, the sequence set of the source CI is updated to show the CIs moved are now free. A sequence set record is built above the new CI to describe it as well;

Each sequence set record has a horizontal chain pointer to identify the next CA in ascending key sequence. The source sequence set record is given a new chain pointer to the new target sequence set record. That new record's chain pointer now points to the source's original "next CA". The sequence set records are now written back to the index;

Since a new sequence set record has been created on index level 1, level 2 must be updated to reflect its addition. An entry is built showing the highest key in the new CI. That entry is then inserted between the entries for the original CI and the one following it. The sequence set records are moved to the right to make room for the insert. Often there is room enough for this to happen. If there is not, an index CI split occurs to create a new level 2 index set record. It should be noted, this process occurs repeatedly all the way up to the highest level of the index and must be considered as part of the cost of a CA split.

17

Page 18: Basic VSAM

KSDS CI and CA Splitting Concepts: SIS Mode

A CI split occurs every time a record is inserted into a CI without enough free space. If you have a large number of sequential records to insert into a KSDS, you can expect a large number of CI splits to occur. There is a way to block out a set of empty CIs in a file for sequential insert processing: SIS mode, or Sequential Insert Strategy.

SIS mode provides for potential CI splitting up front; each subsequent insert won't require splitting. For more information on SIS processing refer to the VSAM book cited in the bibliography.

VSAM Control Information

In a non-VSAM environment, a file is either fixed blocked (FB) or variably blocked (VB). For an FB file, the OS needs only the record length to block or deblock the data. On a VBA file, however, there must be some way for the OS to determine how to block and deblock the file, because each record could have a different length. Therefore, in a VB file, each record and block is preceded by a length field of four bytes.

For example, consider a fixed record length of 251 bytes. To contain 10 records the BLKSIZE of the file would be 10*251, or 2510. For a file with variable record lengths, the maximum of which is 251, each record must be described to the OS as 255 (251 plus the 4-byte record length prefix). To contain the same 10 records the BLKSIZE would be 10*255+4, or 2554.

A VSAM file has a double blocking structure. Each VSAM file has a "block" of data records of fixed length called a control interval (CI). Inside the CI, records can be variable in length. How does VSAM know how long each record is?

VSAM uses two fields in each CI to describe record lengths: the Control Interval Definition Field (CIDF) and the Record Descriptor Field (RDF). In each CI there is one CIDF of four bytes and at least two RDFs of three bytes each.

How the CIDF and RDFs are used is detailed in the cited VSAM reference. It is useful to know the CIDF is used as the "software end-of-file" mark, also called the "end-of-data" mark. The first CI at the top of the first unused CA is filled with binary zeroes and is considered end-of-data.

The key thing to remember here is the length of these fields. If your file has fixed length records you must subtract 10 from each potential CI size when dividing by the record size. For variable length records it is necessary to know how the records vary.

18

Page 19: Basic VSAM

VSAM Control Information: Spanned Records

If the SPANNED attribute has been specified in the VSAM file's definition, records longer than the CI size may cross CI boundaries. Each portion of a record residing in a spanned CI is called a segment. Several rules need to be understood:

For a record to span, its record size must be specified in the define with a maximum record size larger than the CI size;

Records spanning CIs cannot share CIs with non-spanning records; The first byte of the segment starts in byte 1 of the CI and uses all the

bytes in the CI, minus the control fields. The only exception is the last segment if it is shorter than the CI size;

FOR A KSDS: The key must be in the first segment; Free space is not reserved in a spanned CI; CI splits do not occur in spanned CIs.

A spanned record cannot span across a CA boundary; To ensure integrity, segments each contain an update field in the RDF of

their CI. Upon an update request, VSAM checks these fields to make sure the entire record is valid. If the update field is not the same in all segments, VSAM cancels the update;

Each CI with a spanned record contains a CIDF and two RDFs. The first (i. e. rightmost) RDF contains the length and number of the segment. The second RDF contains the update number.

In general, it's not a good idea to use spanned records. This topic is discussed in more detail shortly.

19

Page 20: Basic VSAM

VSAM Data Structure Concepts: the Cluster

Before we get into the cluster concept of VSAM, let's review the basics of non-VSAM file storage.

A new, non-VSAM file is physically allocated at job step initiation using the JCL DD statement. DISP=NEW causes the JCL to pass the space and unit parameters to DADSM. A volume is located and DADSM reads through the format 5 DSCB records in the VTOC (or the Space Map record if the VTOC is indexed) to find the first contiguous span of unallocated tracks able to satisfy the allocate request. If there is not enough contiguous space, DADSM tries to find enough total space within five extents.

If the space exists, DADSM writes a format 1 DSCB to mark the tracks selected as allocated. This DSCB contains such items as the DSN, creation date, available DCB information, etc. That allows the OS to locate and use the file later.

Since VSAM was intended to replace all other access methods, and the VTOC is a non-VSAM file accessed through keys, it was necessary to replace the VTOC with a new structure, processed and managed using VSAM. That structure is called the VSAM catalog. Since it also must be a VSAM file and be accessed by keys (DSN), the VSAM catalog is a VSAM KSDS.

In 1983 the VSAM catalog structure was replaced by the ICFCAT structure. ICF catalogs are discussed later in this document. However, since the purpose of this discussion is to show how VSAM file structure works and why it's designed the way it is, we’ll continue to refer to the VSAM catalog for now.

When a VSAM file is allocated using AMS' DEFINE command, the VSAM catalog is requested to act as a VTOC. Therefore it must somehow mark tracks as allocated for each of the physical file components. A name is assigned to each component, either given in the DEFINE command or generated by AMS. A record (like the VTOC DSCBs) is written for each component to the catalog. These records contain all the information the OS needs to access the file.

For normal access, component information is not enough. In all programs there is file definition language to access one file at a time using one DD statement. Specifying the DSN of either the index or data component would allow access to that component, but without any connection to the other component. The allocated component could be read as an ESDS, but in the case of a KSDS that's probably not what you'd want. To be completely specific, the VTOC does not contain association records to link individual components.

20

Page 21: Basic VSAM

VSAM Data Structure Concepts: the Cluster (cont'd)

All VSAM files have an additional catalog entry to describe associations between related components. This entry is called the cluster. Granted the cluster is only required for a KSDS or a variable-length RRDS file, but consistency needs force the cluster define to be necessary for all VSAM files. By this convention, a program can access an entire logical file with all its structures by allocating only one DSN.

Let's look at a typical VSAM define. Note the convention of allocating the data component as ‘cluster.DATA’ and the index component as ‘cluster.INDEX’. This is a convention only and is not required.

DEFINE - CLUSTER - (NAME(B5926VSM.G5925.VXVRELGA.KSDS) - STORAGECLASS(SCVSAMDB) MANAGEMENTCLASS(MCDBASE) - INDEXED SPEED SHAREOPTIONS(2 3) - RECORDSIZE(146 146) - KEYS(21 0) - FREESPACE(0 0)) - DATA - (NAME(B5926VSM.G5925.VXVRELGA.KSDS.DATA) - VOLUMES(* * * * * * *) - CISZ(4096) - CYLINDERS(275 20)) - INDEX - (NAME(B5926VSM.G5925.VXVRELGA.KSDS.INDEX) - VOLUMES(* *) - CISZ(2048) - TRACKS(1 1))

Because the cluster record is the association between components, values given in the cluster definition are assigned to all components of the file unless specifically given in a particular component section. For example, if the CISZ (CI size) arguments were left off the data and index component definitions and a CISZ (2048) argument were given in the cluster define, both components would be given a CI size of 2048.

If space is provided under the cluster section and not included with the other components, VSAM reserves the minimum space it needs for the index and allocate the rest of the space to the data component.

21

Page 22: Basic VSAM

VSAM Data Structure Concepts: The Cluster (cont'd)

Let's take a quick look at some of the define parameters.

1. DEFINE -2. CLUSTER - 3. (NAME(B5926VSM.G5925.VXVRELGA.KSDS) -4. STORAGECLASS(SCVSAMDB) MANAGEMENTCLASS(MCDBASE) -5. INDEXED SPEED SHAREOPTIONS(2 3) -6. RECORDSIZE(146 146) -7. KEYS(21 0) - 8. FREESPACE(0 0)) - 9. DATA -10. (NAME(B5926VSM.G5925.VXVRELGA.KSDS.DATA) –11.VOLUMES(* * * * * * *) -12.CISZ(4096) - 13.CYLINDERS(275 20)) -14. INDEX -15. (NAME(B5926VSM.G5925.VXVRELGA.KSDS.INDEX) –16.VOLUMES(* *) -17.CISZ(2048) -18.TRACKS(1 1))

1. DEFINE - start the define2. CLUSTER - start the cluster record define3. (NAME(...) - the cluster name. This is the DSN to access the file4. Storage/Management Class - tells SMS where to put the file5. File options is discussed later6. RECORDSIZE - the average followed by the maximum allowed record size.

If the two values are the same, the record format is fixed7. KEYS - describes the key length and offset. In this case, the key is 21 bytes

long and starts in byte 1 of the record (offset 0)8. FREESPACE - given as % of CI free bytes, then % of CIs free in a CA9. DATA - start the data component record definition10.(NAME(...) - the data component name11.VOLUMES - DASD names (one or more, up to 255) for the file's location.

Asterisks are placeholders in an SMS environment12.CISZ(4096) - the CI size of the data component13.CYLINDERS(275 20) - the amount of disk space for the data component14. INDEX - start the index component record definition15.(NAME(...) - the name of the index component17.CISZ(2048) - the CI size of the index component18.TRACKS(1 1) - the amount of disk space for the index component

There are a large number of options you can assign VSAM files. We'll be discussing VSAM file definitions very shortly.

22

Page 23: Basic VSAM

VSAM Alternate Index Structure

A KSDS can be accessed in three "normal" modes: sequentially by primary key, randomly by primary key, and directly by RBA (PL/I and Assembler only).The KSDS components (data and index) can also be read as ESDS files by opening each separately. Often, though, the application may need to access the records using something other than the primary key. The obvious example is, say, a file keyed on employee number but also containing the last name or social security number of each person. VSAM allows this through use of the Alternate Index (AIX). A file can have up to 255 AIXes, but for practical purposes four is the maximum number.

The AIX is not just another index component built over a base KSDS. It is not possible to have two primary keys (two indexes) over the same data, because the data needs to be in key order. An AIX is a complete KSDS in itself, with data and index components and a connecting cluster component.

That raises the objection, "Why duplicate the data sorted a different way? Isn't that wasteful?" The AIX is not like that at all. The data component of the AIX contains (usually) very small subset records with a control information field, the alternate key, and one or more base keys. The control information has several binary values describing the contents of the record and is used to locate the other fields during record processing. The alternate key field is used to control sequencing of AIX records; in other words, the AIX's primary key. The base key field is a pointer value used to locate the associated record(s) in the base cluster. For an ESDS this field is an RBA, because records in an ESDS cannot move around within the file. For a KSDS, because records move around frequently, the base key field is the actual key of the record(s) to be retrieved.

When a user program reads an AIX for a KSDS, VSAM gets the alternate key record from the AIX and uses the base key field to access the index of the base cluster. A base record is then located and passed to the user program.

Connecting AIXes to Base Clusters

In many respects, VSAM considers an AIX to be a KSDS. An AIX cannot be defined until its base cluster is defined. AMS provides a special command, the BLDINDEX, to load a defined AIX. However, even when an AIX is defined, it cannot access the base cluster unless an association is defined between the base and AIX. This is a sort of "super cluster" record and is called a PATH. When a program needs to read a base cluster through its AIX, it must allocate the AIX using its PATH name. A reference to the PATH causes VSAM to interpret the read request on the alternate key as a request to read the associated base cluster record.

23

Page 24: Basic VSAM

Alternate Index Attributes

VSAM design forces the key of a KSDS to be unique within its file. For example, in a file keyed by Employee Number no record can have the same Employee Number. For the same reason, all alternate indexes are built with a key unique within the alternate index file.

Each alternate index, however, can be given an attribute of UNIQUEKEY or NONUNIQUEKEY. That attribute defines whether the alternate key is unique in the base cluster records. It must be decided when an AIX is created whether the alternate keys is unique. NONUNIQUEKEY is the default, so you must code UNIQUEKEY if the base records' alternate keys are to be unique.

If the alternate key is not unique, you'll need to be able to locate all the records having that key. The AIX record contains multiple base key fields if the AIX is defined as NONUNIQUEKEY, and the record length in the AIX is variable. If the AIX is defined with UNIQUEKEY, the AIX record length is fixed.

Keeping the Index in Sync with the Base Cluster

When a new record is inserted into a file with an alternate index, the new record is not accessible through the AIX until the AIX is updated with the record's alternate key information. Conversely, should a base record be deleted, the AIX may still have a record pointing to the deleted base record.

There are two ways to keep an AIX in sync with its base cluster. The obvious method is to rebuild the AIX after each change to the base cluster. That may be impractical. Fortunately VSAM can do the synchronization for you.

A default attribute for an AIX is UPGRADE. That tells VSAM to update the AIX every time the base cluster is updated. Here's what UPGRADE provides:

Each record inserted into the base cluster causes an insertion (new record or base key field) in the associated AIX(es). A base key field insert results in the AIX record getting longer. If there is a duplicate alternate key and the AIX is defined with UNIQUEKEY, the entire insert fails.

Each record deletion in the base cluster causes a deletion (either a record delete or a base key field delete) in the AIX. If the AIX was defined with NONUNIQUEKEY, the AIX record gets shorter.

Each update to an alternate key field in the base cluster results in a record or field deletion and a record or field insertion in the AIX.

See Appendix B for examples of AIX access using COBOL and Assembler.

24

Page 25: Basic VSAM

DASD Volume Space Management for VSAM

When VSAM was first planned, the VSAM catalog was to replace the VTOC in the role of DASD management. That is incompatible with having VTOCs manage the DASD. Volumes with VSAM files could not have non-VSAM files on them, while volumes using a VTOC and non-VSAM files could not have VSAM files on them. Since eliminating non-VSAM proved impossible, IBM worked out a method to allow both VSAM and non-VSAM files to be on the same volumes.

DASD volume management has always relied on the track allocation information kept in the VTOC to be accurate. For VSAM files that information was kept not only in the VTOC but in the VSAM catalog as well. The two need to be kept in sync, but how?

Obviously the solution is to make either the VTOC or the VSAM catalog the owner of the information, and the other subordinate to it. All the old software remained; it would have been ugly to add non-VSAM space management into the VSAM access method code. IBM put the VTOC in charge of DASD space management.

There are problems with that. VTOC DSCB records do not keep historical information. Remember, VSAM files are actually multiple datasets accessed using a single DSN; the VTOC doesn't allow that. Nor does the VTOC allow logical connection of an AIX with its base cluster.

Finally, there is a need to allow multiple volumes to be easily associated with a particular DSN because VSAM has multiple components associated with a single DSN. The VTOC can control files only on its own volume.

The VSAM catalog was created to address those problems. The result was, in effect, a multi-volume VTOC. The catalog, a VSAM file itself, can contain all the information the OS needs to access any file in that catalog.

Unfortunately there were still problems. Those of you who worked with VSAM in the 1970s on into the early 1980s remember having to define VSAM user catalogs and separate, suballocated or unique data spaces before defining any VSAM files. To eliminate these problems, the VSAM catalog was replaced with the Integrated Catalog Facility (ICF). Under the ICF catalog, all that extra work went away.

25

Page 26: Basic VSAM

Finding a VSAM File: The ICF Catalog

VSAM follows a definite order of search to locate a catalog entry for a file when access is requested. When creating a new file, the first catalog found in the search is used. When locating an existing file, many catalogs may be searched until an entry is found. The search order is:

The catalog whose ALIAS matches the high level qualifier of the file being accessed. Beginning with DFP 3.1 up to four levels of the DSN may be used;

The system's master VSAM catalog. This may fail with a RACF error.

DFP and the ICF Catalog

DFP solves the VSAM catalog problems by using the ICF catalog. This new catalog is a two-part file. A Base Catalog Structure (BCS) contains pointer records to locate a file's descriptor records. Those are kept in a VSAM Volume Data Set (VVDS) file. The VVDS contains the file's attributes and volume allocation information. All DASD space management functions are removed from VSAM, allowing elimination of data space and volume ownership concepts.

An ICF catalog consists of only one BCS and one or more (one per DASD volume) VVDS files. The BCS is a VSAM KSDS and contains history, protection, and association information on a given file. It also holds volume location information such as the VOLSER(s) where the file resides.

A VSAM file can be in only one BCS, but a single BCS can access any number of VVDSes.

The VVDS

Each DASD volume containing VSAM objects has a VVDS. Physically, this is an ESDS and is always called SYS1.VVDS.V<volser>. The VVDS cannot be changed by most of the AMS functions. Each data record of the VVDS contains one file's attributes, statistics, allocation, and volume information. This record is called a VSAM Volume Record (VVR).

All VSAM files on a given volume have an associated VVR. Although the VVR can point back to only one BCS, any number of BCSes can point to a given VVDS.

26

Page 27: Basic VSAM

Finding Any File using the ICF Catalog

When locating a file, the high-level qualifier (HLQ) is used as a search argument. The master VSAM catalog is read to see if a BCS has an entry for a matching alias. If an alias match is found, the BCS is located and searched for a record whose key is the complete file name requested. File permissions are checked next. If the user can access the file, VSAM uses the association information to determine which VVDS (VSAM) or VTOC (non-VSAM) to go to next. The file descriptor record is then read to locate the actual file and make its records available.

Of course, the VVDS/BCS connections aren't perfect. Say a file on a volume is pointed to by the VVDS but has no BCS entry (an uncataloged file). If the user needs the file, an AMS DEFINE subcommand RECATALOG can be used. If the user doesn't want the file, the VVR record in the VVDS can be deleted.

Or, say a file is cataloged, but the VVDS pointed to by the BCS does not have a descriptor record for the file. If the user wants the file, the only recourse is to delete the BCS entry (DELETE NOSCRATCH) and restore the file. If not, the NOSCRATCH delete cleans up the catalog.

Defining a VSAM file

Access Method Services (AMS) was designed as a replacement to JCL file allocation. AMS commands have a similar structure to the CLIST language, including the ability to set condition codes, testing values, GOTOs, etc. AMS is executed using the program IDCAMS. The DEFINE command is only one of the commands AMS has, but it is the only one you can use to create VSAM (and certain non-VSAM) files and other catalog objects. The following items can be defined:

CLUSTER - a VSAM KSDS, ESDS, RRDS, or LDS; AIX - a VSAM alternate index; PATH - an association record between an AIX and its base cluster; ALIAS - a VSAM HLQ or another name for a non-VSAM file; NONVSAM - Catalog a non-VSAM file in an ICF catalog. GENERATION DATAGROUP - also called a GDG.

For a complete list of parameters for the DEFINE CLUSTER command please see Appendix C. This document covers those you may need to use.

27

Page 28: Basic VSAM

Define Cluster Basic Parameters

NAME( ... ) is required at the cluster level, optional on data and index levels. It provides a DSN by which the file is accessed. If the data and / or index name parameter is left off, VSAM assigns a name using the cluster name with a DATA or INDEX appended to it.

OWNER( ... ) is optional at all levels. If the define is run interactively in TSO, the TSOID is used as the owner. In all other cases the owner is NULL.

INDEXED / NONINDEXED / LINEAR / NUMBERED specifies the file is (respectively) a KSDS, ESDS, LDS, or RRDS. This can only be specified at the cluster level. Abbreviations for these are (respectively) IXD, NIDX, LIN, NUMD.

KEYS(n n) specifies the length and location of the primary key for indexed clusters only. It is valid at the data or cluster level only. The first number is the length of the key; the second number is the offset relative to the first byte (i. e. 0 indicates the key starts in the first byte). For example, if the key is in bytes 27 - 44, the parameter is KEYS(18 26). The default is KEYS(64 0). You cannot specify non-contiguous keys.

Define Cluster Space Allocation Parameters

RECORDSIZE(n n) - abbreviated RECSZ, this specifies the "average" and "maximum" record length to be loaded to the data component. If the two values are the same, VSAM expects all records being loaded is that length, but accepts records of any size up to the maximum specified. If the two values differ, VSAM assumes the records may be any size up to the maximum length. In this case, the "average" size can be anything and does not affect the cluster definition unless the RECORDS parameter is used. The default RECORDSIZE is (4089 4089) if the CI size is 4096 or greater. If the CI size is smaller the default is the CI size minus seven bytes. If the file is SPANNED the default is (4086 32600).

Note: REPRO and EXPORT cannot handle record sizes larger than 32760. Be aware of that when designing your file.

If RECORDSIZE specifies variable length records, you should look into how often the record varies from record to record and fit the CI size to that. VSAM is a fixed block access method and variable records do not necessarily fit well into fixed block sizes. If you like statistics, two standard deviations of all record sizes in the file gives the 95th percentile of the average record lengths.

28

Page 29: Basic VSAM

Define Cluster Space Allocation Parameters (cont'd)

CONTROLINTERVALSIZE( ... ) specifies the control interval size. This is optional and can be coded at the cluster, data, or index level. Its abbreviation is CISZ or CNVSZ. This parameter cannot be specified for an LDS. For a list of allowable CI sizes, see Appendix A.

Keep the following in mind when choosing a CI size:

If specified at the cluster level, all components have the same CI size unless it is overridden;

For a KSDS, if the CI size is specified at the data level but not the cluster or index level, AMS calculates one for the index.

It is recommended to code the CI size at the data and index level.

When selecting a CI size, try to get the best fit for your records. First, determine if you are using SPANNED records. Generally spanning is a bad idea unless the record size is very large or if variable records vary by large amounts.

If your record size is fixed, simply make a list of CI sizes giving a reasonably good percentage used (say, 95%). Keep in mind, a fit of 100% is not good because VSAM needs room to write its CIDF and RDFs.

For example, a record size of 200 fits quite well in CI sizes of 1024, 2048, 3072, ... but not so well into 512, 1536, 2560, .... Note they also don't fit as well as expected in a CI size of 4608 since 10 bytes are needed for the CIDF and the two RDFs.

For a KSDS or RRDS you should pick a (relatively) small CI size. This allows both faster data transfer rates and a lower lockout ratio, since getting one record in a giant CI may cause closely spaced records to become temporarily inaccessible (and take longer to access). To speed sequential processing, use buffers.

29

Page 30: Basic VSAM

Define Cluster Space Allocation Parameters: CI size (cont'd)

In a KSDS you should make sure the CI has enough room for free space to allow for growth. This can be tricky if you aren't careful. Here are two examples with opposite effects:

Assumptions: RECSZ(1000 1000), CISZ(2048). With no free space, two records fit in a CI (2,000 bytes in a CI of 2048 bytes). With 3% free space:

2048 * .03 = 61 bytes to be left free; 2048 - 61 = 1987 bytes "loadable"; 1987 / 1000 = 1 record loaded per CI.

In this case the requested 3% free space turned out to be 50% because only one record is loaded per CI rather than two.

Assumptions: RECSZ(600 600), CISZ(4096). With no free space, six records fit in a CI (3,600 bytes in a CI of 4096 bytes). With 10% free space:

4096 * .10 = 409 bytes to be left free; 4096 - 409 = 3687 bytes "loadable"; 3687 / 600 = 6 records loaded per CI.

In this case, the requested 10% free space turned out to be no free space as all six records are loaded in each CI.

Finally, you should try to select a CI size fitting the DASD type. The smallest CI sizes use only about 50% to 75% of the available track space. A CI size of 4096 (or any 2K increment above that) uses about 87% or more of the track space and would be a better pick.

A Word about the Index CI size

The index CI size is just as important as the data CI size. The index CI size must be large enough to index all data component CIs within each CA. When the index CI size is not large enough, VSAM leaves data CIs empty within each CA. Two problems indicating the index CI size is too small:

The file takes more space than you'd expect based on its space calculations; CA splits occur sooner than expected based on the free space percentage.

Steps to calculate the index CI size can be found beginning on Page 39.

30

Page 31: Basic VSAM

Define Cluster Space Allocation Parameters: Free Space

FREESPACE(n n) specifies the free space percentages for each CI and CA respectively. The abbreviation for this parameter is FSPC. The percentages can be any number from 0 to 100. Regardless of the percentages, VSAM always tries to load at least one record per CI and one CI per CA.

How to Calculate Free Space: the CI

The amount of free space is dependent on the file’s activity and over what amount of time. Here are the things to consider:

The data format of the keys (single or multiple fields, data type (alphabetic, numeric, or alphanumeric)) and how tightly spaced the keys are;

Where record inserts occur within existing keys. If inserts occur randomly free space distributed evenly is helpful. If inserts occur only at the end of existing records or in clustered groups, free space won't be reserved properly;

In general, you should pay for inserts up front. It's not feasible to plan for free space for the life of the file, so know how many inserts is made in the reorganization and update lifecycle;

How many deletes are made during the same lifecycle. Remember, in a KSDS a delete frees up space to be possibly used for a later insert.

If the above conditions are understood, it's fairly easy to calculate free space. You would simply divide the net insertions by the record count, resulting in the overall percentage increase to the file over time. Let's look at an example.

Assumptions: 100,000 initial records, a CI size of 4096, and a fixed record size of 200 bytes.

Based on the frequency of reorganization, it's decided the file needs room for 25,000 records to be inserted. During the same period an estimate of 5,000 deletes is performed. Further, the keys to be added or deleted occur randomly among the key ranges, and the timing of delete actions allows us to use a "net insertion" value of 20,000. Thus:

Net insertions * 100 = CI freespace percent 20,000 * 100 = 17% Total records + net insertions 100,000 + 20,000

From this calculation we see the total amount of CI free space should be at least 17%. For general purposes you could round the free space percentage to 20% because it's easily workable.

31

Page 32: Basic VSAM

How to Calculate Free Space: the CI (cont'd)

In a previous example, we showed the need to be careful in applying free space percentage. VSAM may give you substantially more or less than the coded percentage free. This calculation is the one to use:

Records loaded = CI size - (CI size * CI freespace%) Record size

Plugging in the values from our existing example:

Records loaded = 4096 - (4096 * .20) or 4096 - 819 = 16200 200

You may have noticed the CIDF and RDF lengths were ignored in the calculations. For a fixed-length record this value is 10 bytes. For a variable length record, the total length of the CI information fields is the number of expected records in the CI times 3, plus four bytes.

You also should have noticed the calculated free space percentage, 20%, is what we actually achieved. That was not an accident. That's why the ratio of record size to CI size is so important.

How to Calculate Free Space: the CA

The second number in the FREESPACE parameter is the percentage of CIs to be left free in each CA. For example, a 4K CI size has 180 CIs per CA, so with a parameter of FSPC(0 10), 18 CIs is left free in each CA.

If the file is defined with any CI free space there should be at least some CA free space as well. Because a CA split is so resource intensive and time consuming, it's well worth it to make your file slightly larger to avoid CA splits. But how much is enough?

Assuming you have the optimum CI free space calculated, CA free space would be used only for those situations you couldn’t plan for. Because that's so hard to predict, a small amount of CA free space should be sufficient. One guide could be to use 1/2 the amount of CI free space as your CA free space percentage. 10 percent should be plenty. Note, however, CA free space percentage needs to be accounted for in any space calculations. These calculations are covered shortly.

32

Page 33: Basic VSAM

Other Free Space Concerns

So far we've discussed only evenly distributed update activity. Of course, inserts can be clustered. What can you do about it?

If the inserts are somewhat clustered, try using no CI free space but a moderate CA free space percentage. That puts all free space at the end of each CA, allowing CI splits to happen if necessary. However, that could backfire.If most of your activity happens in a few CAs, all the free space in the other CAs is wasted.

For heavy clustering, consider no free space of any kind and let VSAM split as needed. During an initial break-in phase performance is poor, then improve to a point after the splits have provided enough free space to accommodate more inserts. If this strategy is taken, you should cut back on reorg frequency. Many people think they need to reorganize when the number of splits has gotten high, and that's just wrong. It is true taking a CI or CA split causes a performance loss during the split, but the performance after a split is no worse than as if the split had never occurred. In some cases, the file may actually perform better after several splits due to an increase in distributed free space.

Consider this: free space can be altered at any time using the AMS command ALTER. Assume we have these ranges of keys in an employee database:

Keys 00001 - 19999 with turnover at 5% Keys 20000 - 49999 with turnover at 10% Keys 50000 - 99999 with turnover at 30%

You can load the file to accommodate the different free spaces needed for these keys:

DEFINE CLUSTER ( ... FREESPACE(5 5) ...) REPRO ... FROMKEY(00001) TOKEY(19999) ALTER ... FREESPACE(10 5) REPRO ... FROMKEY(20000) TOKEY(49999) ALTER ... FREESPACE(30 15) REPRO ... FROMKEY(50000) TOKEY(99999)

Of course, this method has its problems. The biggest one is the fact the file used as input must also be keyed (e. g. a KSDS). However, it does work.

33

Page 34: Basic VSAM

Define Cluster Space Allocation Parameters: Space

Space can be allocated as any of the following: CYLINDERS (CYL), TRACKS (TRK), RECORDS (REC), KILOBYTES (KB), or MEGABYTES (MB). If the DATACLASS or MODEL parameters are used, this argument is not needed. It is not relevant when RECATALOG is specified. The argument is supplied as a primary and secondary amount. It can be specified at the cluster, data, or index levels. Let's discuss the types of allocations you can specify.

When allocating in records, you specify the number of records you think the file can hold. AMS then calculates the file size for you. Allocating in records is not recommended because of these three drawbacks:

AMS uses the average record length to calculate the space. This is fine for fixed length records but may be way off for variable records;

None of the factors affecting space are considered when AMS calculates the space (e. g. FREESPACE is ignored). To account for them, the user must "make up" a record number to accommodate the extra space needed;

AMS determines what the CA size is. CA sizes other than one cylinder are very inefficient, but nobody told AMS that.

Allocating in tracks should only be done in special circumstances, e. g. there are very few records in the file. Here are a few examples:

TRACKS(10 2) is very bad. The CA size is set to 2 tracks, giving a 2-level index and requiring three I/O for each random access.

TRACKS(2 2) is good as long as the data doesn't go into extents. The index consists of a single sequence set record and thus only one level. If the file takes an extent, however, each random access requires two I/O. This extra I/O cannot be saved by extra buffering, either.

TRACKS(10) is good as long as the file never needs an extent (if it does an abend occurs). Again, this allocation needs only a single CA and thus only one I/O to get any record.

Unless the installation is extremely tight on DASD, you should just go ahead and allocate a small file as CYL(1 1). When allocating in megabytes or kilobytes, AMS rounds up to the minimum number of cylinders to contain that much space.

34

Page 35: Basic VSAM

Define Cluster Space Allocation Parameters (Cont'd)

If the space argument is specified at the cluster level for a file with only one component (e. g. an ESDS), that space is allocated to the data component. Space allocations cannot be specified at both the cluster and data levels. In a multiple component file (e. g. a KSDS), the location of the space argument can be important.

When specified at the cluster level the amount is divided between the data and index components. The division is based on the other file attributes. After the division, if the amount determined for the data is not an even multiple of the CA size it is rounded up to the next higher CA multiple. This can result in a larger file than was specified. If a value is specified at the cluster level and another level, an error results.

When specified at the data level the entire amount is given to the data component. AMS determines a proper amount to the index component based on the file's attributes.

When specified at both the data and index levels AMS gives the coded amount to each component.

For a KSDS, you should specify the space at the data level or both data and index levels.

Multiple Volume Allocation

If the file extends to a new volume, VSAM takes the primary number of cylinders, not the secondary number. For that reason it's a good idea on a large file to code space for a 2,000 cylinder file as, for example, CYL(250 200) rather than CYL(2000 50).

A VSAM file can take up to between 119 and 123 extents, with up to five being used for the primary allocation.

Define Cluster Space Allocation Parameters: Volumes

The VOLUMES parameter tells VSAM what device(s) to allocate to the file. If more than one volume is specified, all volumes can be used. An "*" is used in an SMS environment and tells VSAM to use whatever volume SMS tells it to use. A maximum of 59 volumes can be specified. The abbreviation for VOLUMES is VOL.

35

Page 36: Basic VSAM

Define Cluster Space Allocation Parameters (cont'd)

SPANNED / NONSPANNED specifies whether records can be allowed to span across multiple control intervals. Abbreviated by SPND and NSPND, the default is NONSPANNED. The exception is the AIX, which is always SPANNED.

With SPANNED, records larger than the CI size (if the maximum record size is larger than the CI size) are stored in pieces across continuous CIs until the entire record is stored. A CI can contain either a segment for a spanned record or no spanning records, but not both. If a spanned record does not use a full CI for its final segment, no other records can use that space. Free space arguments are ignored for spanned records.

Specify SPANNED only in these situations:

The file has variable length records and only a very few are large; The file has variable length records and there is a large variation in record

length, with the most common length in between the largest and smallest.

36

Page 37: Basic VSAM

Calculating Space for a VSAM file

A fairly precise set of calculations is available to get an accurate allocation amount for your VSAM file. You need to gather the following information:

The total number of records the file initially contains; Record sizes for the file. A fixed record length is easy to calculate for.

Variable record sizes are far harder to work with unless you have very accurate information on how the records vary over time and between records;

For an ESDS, determine how many records are added after initial load; For a KSDS, establish the reorganization cycle time; For a KSDS, determine how many inserts and deletions will occur as well as

when and approximately where in the file they occur.

Where insertions occur determines where free space should be reserved and how much the file needs. This topic was discussed in the free space description above. Appendix D has a pair of work sheets you can use to determine the amount of space your VSAM file needs.

Calculating an Index CI size

We talked about calculating a data CI size in the DEFINE CLUSTER section. Because the index CI size is an optional parameter, we've pretty much ignored it until now. However, it is an important consideration to VSAM file design.

Beginning in zOS v1.4, AMS calculates the minimum index size this way:

ASSUMPTION: key length 11 bytes, 4096 data CI size.

Divide the key length by three, always rounding up. For example, dividing 11 by 3 results in 2.75, and rounding up to 3;

Add 3 bytes (the index record’s overhead) to the result. In our example, this makes 6;

Multiply the result by the number of CIs in a CA. In our example, 6 * 180 = 1080;

Take the smallest CI size large enough to contain a record that size. The smallest CI size large enough to hold a 1080-byte record is 1536.

The index CI size picked by AMS may be a reasonable estimate; however, it is highly recommended the designer calculate and explicitly assign an index CI size.

37

Page 38: Basic VSAM

Calculating an Index CI size (cont'd)

Index set records should be as small as possible to decrease search time. At the same time, the sequence set records must be large enough to address all the CIs in one CA. During the initial load, if the sequence set record runs out of space before the CI is full, VSAM moves on to the next CI, leaving the previous CI partially empty. That can increase the space needed by the file tremendously.

To determine the necessary index CI size, the file's key length and the data CI size must be known. Appendix A lists the number of CIs per CA, and the table just below shows the average compressed key length. These two numbers are multiplied together to find the required index CI size.

To summarize:

Make an effort to determine a compressed key length and add 3; Find the number of CIs per CA; Multiply the two and round up to the next allowable CI size value.

If your keys don't compress well, the calculated CI size will be too small. As a general rule of thumb, large keys with multiple fields where a middle field is EBCDIC and packed with blanks will not compress well. If you think you may have a poorly compressed key, it's usually safe to add 512 to the calculated index CI size.

As a general rule, a 4K (4,096 bytes) data CI size and a 2K (2,048 bytes) index CI size are "best".

Here is a real-world example. In a given file the key length was 47 bytes, the average compressed key length was 24, and the data CI size was 3072. With an index CI size of 2560, the file needed 4,050 cylinders to hold all its data. With an index CI size of 3072 (the next CI size up), the same data was contained in 2,800 cylinders. That's a storage gain of nearly 30%, but we can get still more. If the data CI size is taken as correct this file really needs an index CI size of 6144:

24-byte compressed key + 3 bytes = 27 bytes; 27 bytes * 225 CIs per CA (3072 data CI size) = 6075; next valid CI size up from 6075 is 6144.

Using the index CI size calculated, the file shrunk down to 1,600 cylinders.

Perhaps it's obvious, but the larger the data CI size is, the smaller its index CI size is.

38

Page 39: Basic VSAM

Define Cluster: Performance Tuning Parameters

The BUFFERSPACE parameter specifies the number of bytes used for buffered processing of the file's data and index records. It can be abbreviated as BUFSP or BUFSPC. There's no real need to code this parameter. The default buffer space is calculated at define time by AMS as enough space to read two data CIs and (if a KSDS) one index CI. If the parameter is coded in the define, it overrides the default only if the specified value is larger. Here is an example:

Assume a 4K (4,096 byte) data CI size and a 2K (2,048 byte) index CI size. The default space is 2*4K or 8K, plus 1*2k, for a total of 10K. The result is BUFSP(10240).

Buffer space is divided at open time as follows:

If the file is opened sequentially, one buffer is reserved for index processing and the remaining space is allocated to data buffers;

If the file is opened for random processing, two buffers are allocated to process data records and the remaining bytes are dedicated to index processing.

Even IBM documentation considers this a performance problem.

While the BUFFERSPACE parameter can be used to determine buffer amounts it is frequently better to explicitly state buffer needs in one of the following methods:

AMP JCL parameter in the DD statement; Assigning LSR buffers; ACB parameters in an Assembler program; DECLARE parameters in a PL/I program.

We'll discuss AMP and LSR buffers in turn.

39

Page 40: Basic VSAM

Dynamic Buffer Specification

The AMP JCL parameter allows the user to specify the number of buffers to use for a VSAM file. The AMP subparameters are:

BUFSP - the number of bytes for all components of the file. Providing this argument is exactly like supplying the BUFSP argument in the define;

BUFND - specifies the number of buffers to be used by the data component; BUFNI - specifies the number of buffers to be used by the index component.

In almost all cases, paired BUFND/BUFNI parameters are preferred because they're more easily understood at a glance. It is not required to specify them in together; use one or the other or both. This is the syntax for the AMP parameter:

AMP=('BUFND=xx,BUFNI=xx')

The parentheses are not required. Data buffers (BUFND) are used for sequential processing and index buffers (BUFNI) are used for random processing. Most people know the default buffering is not enough. The question is, "How much buffering do I need?" The answer is not simple, partly because different processing modes can be affected by buffering amounts.

There are many variables affecting VSAM's use of buffers, most of which are too complicated for this document. The picture is much simpler if we consider only batch applications using COBOL.

40

Page 41: Basic VSAM

Buffers for Random Processing

Random processing means the program issues a keyed I/O request looking for a single record. A keyed search always starts at the top of the index structure, following it all the way through to the sequence set before reading the actual record. VSAM looks first in its index buffers to see if the required index set record is already in memory. With the IBM default of only one buffer, an I/O is needed whenever a new index record is needed.

VSAM does not allow the entire index to be read into memory. While any number of index set records in memory is searched, VSAM recognizes only one sequence set record per I/O request no matter how many are sitting in buffers. Because most index records are sequence set records, for most applications VSAM can keep the entire index set in memory using very few buffers.

It's not always necessary to do so. If the transactions to be run against the file are presorted, the number of index buffers should be equal to the number of the highest level of the index. For example, if your index has four levels, the proper parameter is AMP=('BUFNI=4').

If the transactions are unsorted, you must know how many index set records there are. This information is not in the LISTC, but can be calculated. Locate the total number of index records in the LISTC and subtract the number of sequence set records. The remainder is the number of index set records.

Since there is one sequence set record per CA, the number of CAs in the file is the number of sequence set records. Note: the number of cylinders does not give a completely accurate account of the number of CAs, because some of them are not being used and have no sequence set record. The formula is:

BUFNI = total index records - Data HURBA + 1 CA size

The "+1" accounts for the required sequence set record. In most random access situations, the default number of data buffers is sufficient. By definition, "random" means "anywhere in the file," so the likelihood of finding the next record in the same CI is minimal.

The only time more data buffers might be useful during random processing is in a case where the user expects a large number of CA splits during the update. In this case, processing would be speeded considerably during a split. On the other hand, you're not supposed to get CA splits.

41

Page 42: Basic VSAM

Buffers for Sequential Processing

Sequential processing means the program asks for records using sequentially higher key values (KSDS) or in physical sequence (ESDS), one record after another, such as READ ... NEXT. Buffering for this predictable request is easy.

There are two types of buffer processing VSAM can do. One is called "alternating buffer support," in which one buffer is acted on asynchronously by VSAM while another is used by the application program. The other is called "read ahead" (or "prefetch"). In this process VSAM reads ahead, filling buffers in advance while the program is processing older buffers.

When enough buffers exist, VSAM builds channel programs to read or write CIs based on half- or full track multiples, saving rotational delay. VSAM can chain schedule up to a full CA in a single I/O request if there are enough buffers available. In an extreme case, when the application program needs to read the entire file sequentially, it is worthwhile to code enough data buffers to read all the CIs in a single CA. This logic also applies to REPRO backups, alternate index builds, and reorgs.

For most application programs, the need to read the data sequentially does not span the entire file but only portions at a time. In that case, buffering one track at a time is the optimum balance between speed and using too much storage for data buffers. The calculation is:

BUFND = 2 * (Number of data CIs per track) + 3.

The "+3" accounts for the "work CI" VSAM reserves and spares two for those circumstances when CIs span tracks.

In sequential processing there is never a need for more than one index buffer.

Direct Access Buffering with LSR

Assembler programs (and, of course, CICS regions) have access to another buffer pool called the Local Shared Resource pool, or LSR. LSR can also be used in batch (BLSR). A complete discussion of LSR and BLSR is too detailed for this document. Fortunately there is an IBM publication on BLSR; it’s listed in the bibliography.

42

Page 43: Basic VSAM

More Performance Options

SPEED / RECOVERY specifies whether the data component is pre-initialized at load time. RECOVERY can be abbreviated as RCVY; there is no abbreviation for SPEED. Using RECOVERY causes VSAM to do triple I/O during the load because of the pre-initialization of CIs and sequence set records.

For an ESDS, RECOVERY lets you restart the load "in the middle." In other words, even if the load fails VSAM considers what was loaded to be good.Sometimes, however, VSAM cannot restart a load of a KSDS. RECOVERY is the default; always code SPEED for a KSDS.

WRITECHECK / NOWRITECHECK specifies whether VSAM double-checks each WRITE. Abbreviated as WCK or NWCK, the default is NOWRITECHECK.Because of the considerable reliability of I/O channels and the excess overhead involved in rechecking each WRITE, use the default.

ERASE / NOERASE specifies whether the data component is to be rewritten with binary zeroes at delete time. Abbreviated as ERAS/NERAS, the default is NOERASE. RACF has built-in erase functions, so if the file is protected by RACF the ERASE parameter is not needed.

REUSE / NOREUSE specifies whether the file can be opened over and over with a new set of records (REUSE) or must be deleted and redefined before it can be reloaded (NOREUSE). Abbreviated as RUS/NRUS, the default is NOREUSE.

In JCL temporary files are processed by non-VSAM access methods. With the REUSE parameter, a permanent VSAM file is treated as a temporary one (at least regarding content).

One advantage a REUSEable file has over a JCL temporary file is the ability of the user to decide whether to keep the records. Temporary JCL files go away at the end of the job, along with their contents. In a VSAM file defined with REUSE, however, records are deleted only if the user program opens the file as OUTPUT. Normally records remain in the file unless specifically deleted by another user process.

Technically, REUSE sets the HURBA to 0 if the file is to be overwritten. This causes all secondary volumes (and their extents, of course) to be marked as candidates. It does not, however, free up existing extents on the primary volume. All statistics in the catalog are set to NULL.

A REUSEable file cannot have alternate indexes. In most cases the SAM temporary files are sufficient. However, a VSAM REUSEable file is the only way to go if a random-access temporary file is needed.

43

Page 44: Basic VSAM

Define Cluster: More Performance Options

SHAREOPTIONS(n n) specifies how the cluster or its components are shared among its users within the system ("cross-region") or across multiple systems ("cross-system"). The abbreviation is SHR, and the default is SHR(1 3).

The cross-region parameter can have these values:

1. Any number of users can have read access (OPEN INPUT) or one user can have update access (OPEN I/O). VSAM ensures complete integrity.

2. Any number of users can have concurrent read access, and one user can have update access. If the user requires read integrity you must use the ENQ and DEQ macros to obtain exclusive control of the file. The file's records are safe due to the restriction of one update access at a time, but a record can be updated after a program has read it.

3. Any number of users can have read access, and any number of users can have update access. VSAM provides no integrity checking, so the program must provide all of it (including the use of ENQ and DEQ).

4. The same as 3. but also flushes the buffers for each I/O request.

The cross-system parameter can have these values:

3. Any number of users can have read access and any number of users can have update access. VSAM provides no integrity checking; the program must provide all of it. In this case, RESERVE and RELEASE macros are more useful than DEQ/ENQ because they work on the DASD rather than the file.

4. The same as 3. but also flushes the buffers for each I/O request.

In addition, under option 3 VSAM takes these three special actions:

A change in the file's HiUsedRBA is not allowed (the file cannot grow larger); For a KSDS, a change in the high-key RBA is prevented. In other words, the

highest key in the file does not move; Data and sequence set buffers are refreshed for keyed searches. Note this

applies only to direct (random) requests; sequential requests can still use copies of the CI or sequence set records from the buffer.

You'll note the cross-system options do not provide much security. Before IBM's SYSPLEX architecture, most installations used either IBM's Global Resource Serialization (GRS) product, or Multi-Image Management (MIM) from Legent, to handle file sharing. SYSPLEX handles all that now.

Unless you need to update a file in batch while it's active in real-time, and read integrity is not necessary, you should code SHR(2 3).

44

Page 45: Basic VSAM

Define Cluster: Installation Defaults

MODEL( ... ) specifies an existing cluster, data, or index component is to be used for assigning attributes to a new file. If desired, all attributes of a file can be assigned through modeling. The only required parameter is the cluster name (and, of course, MODEL).

If the MODEL parameter is specified, any attributes of a file not explicitly given in the define are taken from the catalog entry of the file in the MODEL statement. If a parameter is specified, its value in the define takes precedence over the same attribute in the file being modeled.

Take note of the parameters supplied in the define to make sure they don't conflict with the file being modeled. For example, if a RECORDSIZE parameter is coded in a define but the CISZ is not, make sure the CISZ in the existing file can handle that record size.

It is not possible to define a dummy VSAM file with no size to be modeled. It is possible to set up a dummy file of minimal size to be modeled.

Define Cluster: Security Authorization Parameters

MASTERPW / CONTROLPW / UPDATEPW / READPW ( ... ) specifies passwords for (respectively) full, component, update, and read access. Today with RACF these are no longer needed (as are the next three parameters) and therefore no descriptions are given.

ATTEMPTS: the number of tries a user has to enter the correct file password.

CODE ( ... ) specifies a message to be sent to the operator when an access failed all its ATTEMPTS.

AUTHORIZATION ( ... ) specifies the program name of the User Security Violation Routine (USVR) to be given control during OPEN processing. This is given control only if a valid password is given. It is ignored if a MASTERPW is given successfully.

TO ( ... ) / FOR ( ... ) specifies a time during which the file cannot be deleted except using the PURGE parameter. The TO argument is a "Julian" date of YYYYDDD; the FOR argument is a number of days.

45

Page 46: Basic VSAM

Define Cluster using SMS

The following three parameters are effective only under SMS. If SMS is not active the define fails.

DATACLASS ( ... ) specifies a 1 - 8 character name of a Data Class list. This is used to assign allocation attributes to the cluster such as number and type of size parameters. Generally, DATACLAS is not used.

MANAGEMENTCLASS ( ... ) specifies a 1 - 8 character name of a Management Class to assign retention, backup, and migration attributes to the file. Abbreviated as MGMTCLAS. STORAGECLASS ( ... ) specifies a 1 - 8 character name of a Storage Class to assign devices and volumes for file allocation. Abbreviated as STORCLAS.

One final Define Cluster Parameter

RECATALOG / NORECATALOG parameters cause VSAM to recreate the Cluster Sphere record for the file without actually redefining it. Of course, NORECATALOG is the default. Abbreviations are respectively RCTLG and NRCTLG.

If possible, the original define should be run with this parameter added. While not necessary, it's simply easier to do so.

OPTIONAL: Defining a VSAM File with JCL

A user can create a VSAM file in their JCL. The DSN= field is the cluster name. The following parameters help you:

RECORG=(KS, ES, RS, LS) for (respectively) KSDS, ESDS, RRDS, LDS; KEYLEN=n - used with the next parameter, provides key information; KEYOFF=n - used with KEYLEN, this is the offset of the key; LIKE=dsn - works like MODEL.

The following differences exist:

LRECL=n - the maximum (not average) record length; AVGREC=(U, K, M) - scale modification of units, thousands, or millions of

records when determining space in SPACE=({avg. rec. len.} ({pu}, {su})). For example, SPACE=(80,(10,1)) with AVGREC=K actually provides for a space argument of (80,(10000,1000)).

46

Page 47: Basic VSAM

Defining an Alternate Index (AIX)

In many ways, defining an alternate index is similar to defining a base cluster. Only those parameters different from the base cluster parameters are listed here, unless the parameter has a different application in a base cluster versus an AIX.

RELATE ( ... ) specifies the base cluster to be accessed using the AIX. The base cluster cannot have the REUSE attribute and must be a KSDS or an ESDS.

KEYS (n n) basically the same as in the base cluster define, except the AIX key cannot start in the same byte as the primary key. However, the key can be a subset of the primary key if desired.

RECORDSIZE (n n) - the same as in the base cluster define, with additional considerations.

If the file is defined as UNIQUEKEY, "average" should equal "maximum." If the file is defined as NONUNIQUEKEY, the value of "average" must be less than the value given for "maximum."

Alternate indexes are automatically defined with the SPANNED attribute (although it can't be explicitly coded) to accommodate non-unique keys.

In a NONUNIQUEKEY file each record has a 5-byte control field:

Byte 1: x'00' if the base is a ESDS, x'01' if the base is a KSDS; Byte 2: length of the base cluster pointers in an AIX record. Values are x'04' if the base is an ESDS, x'length' if the base is a KSDS; Bytes 3 and 4: the number of occurrences of the base pointers within the record. For a UNIQUEKEY AIX this number is always x'0001'. Since a 2-byte field allows positive numbers up to x'7FFF', you can see the maximum number of occurrences of base cluster pointers is 32,767. Two examples follow.

SSN / Employee number AIX: a unique relationship. The record has five bytes of control information, a 9-byte SSN, and a single employee number field of, say, five bytes for a total AIX record length of 19 bytes.

Employee Number / Department AIX: a non-unique relationship. Further, say each department can have at most 50 employees. The record has its five bytes of control information, the department field (say 3 bytes), and (assuming the same 5 bytes of employee number bytes), up to 50 * 5, or 250, bytes of employee number information. The maximum record length would thus be 258 bytes.

47

Page 48: Basic VSAM

Defining and AIX: Records and Keys (cont'd)

Obviously, it is possible with a non-unique key to "run out of room" when adding base cluster records. Suppose, as in the previous example, you have defined a maximum record size of 258 bytes to your AIX. Tomorrow your boss may decide to expand a department to more than 50 people. What happens to your AIX?

"Extra" Keys During a Load

Normally a base cluster is loaded, followed by a build of an alternate index. During the first build of the AIX, if a given alternate key should generate more "entries" than fit in the AIX, VSAM flags it with an error message. VSAM then saves the existing AIX record moves on to the next alternate key. The result is a valid AIX with some base cluster record pointers missing. The fix is to drop the AIX, fix the define, and then rerun the build. It is unnecessary to rerun the load of the base cluster.

"Extra" Keys During an Update

In an established base cluster / AIX set, if an update would result in the AIX record "running out of room," the entire update is cancelled. In other words, not only does the AIX update fail, so does the base cluster's update. That only happens when the UPGRADE option is specified. If the AIX is defined with NOUPGRADE, the update continues.

Defining an AIX: the Upgrade Parameter

UPGRADE / NOUPGRADE specifies whether the alternate index is updated whenever the base cluster is updated. Abbreviations are respectively UPG and NUPG. The default is UPGRADE.

If UPGRADE is in use, VSAM automatically opens the AIX when the base cluster is opened. If a change made to the base cluster would affect the AIX, the AIX update takes effect before the base cluster update is completed.

With UPGRADE the user can be assured the AIX and base cluster are accurate and in sync with each other. There is no other way to do so except though the BLDINDEX AMS command. Further, the UPGRADE does not take effect until the AIX has been built.

AIXes are very expensive. Any access to the base cluster through its AIX requires twice as many I/O to access a given record. This should not discourage you from using AIXes, but be aware of the costs.

48

Page 49: Basic VSAM

Defining an AIX: DEFINE PATH

Although there are several parameters on the DEFINE PATH statement, only these are useful to you in our current environment:

NAME ( ... ) is the name by which you access the alternate index.

PATHENTRY ( ... ) specifies the name of the AIX to be accessed. If this argument is supplied for a base cluster without an AIX it functions as a "create alias" command. The abbreviation is PENT.

UPDATE / NOUPDATE - specifies whether the AIX is to be maintained using UPGRADE. Note this overrides the UPGRADE parameter. In other words, if the path is defined as NOUPDATE the AIX is not maintained even if it was defined with UPGRADE. The default is UPDATE. The parameters can be abbreviated respectively as UPD / NUPD.

RECATALOG / NORECATALOG specifies whether the define path is being done to re-synchronize the catalog entries.

Building an AIX: the BLDINDEX Command

The BLDINDEX command creates and loads an AIX from an existing base cluster. Several parameters of BLDINDEX are not in common use and are not discussed here. During a build of an AIX the following operations occur:

The base cluster is read sequentially; The key and alternate key are extracted from each base cluster record; At EOF in the base cluster, the AIX has a set of records which are not in

alternate key order. These records must be sorted before they are loaded; VSAM performs this sort;

Once the records are sorted, they are written to the AIX. As each record is written, the control field is added at the front of the record.

BLDINDEX parameters

INFILE ( ... ) or INDATASET ( ... ) specify the base cluster DDname or DSN used to build the AIX. One or the other must be given. Abbreviations are IFILE or IDS. When INDATASET is used it needs exclusive access to the base cluster. Unless a BLDINDEX is run against an initialized base cluster (i. e. one "seed" record), it is highly recommended INFILE be used so you can code AMP buffers in the JCL.

The base cluster named in the statement must have been specified in the RELATE parameter in the AIX's define. The base cluster and the AIX must be in the same catalog.

49

Page 50: Basic VSAM

BLDINDEX Parameters (cont'd)

OUTFILE ( ... ) / OUTDATASET ( ... ) specify the AIX being built. OUTFILE requires a DDname, OUTDATASET requires the file's DSN. Abbreviations are OFILE and ODS respectively. In general, the same restrictions for INFILE / INDATASET apply to OUTFILE / OUTDATASET. OUTFILE is recommended so you can code AMP buffers.

EXTERNALSORT / INTERNALSORT - specify whether VSAM uses an internal sort (virtual storage) or external sort (disk work space) to sort the AIX records. Abbreviations are ESORT and ISORT. The default is ISORT.

With small files ISORT isn't a problem. To calculate the amount of storage needed:

Calculate the AIX key length plus base key length. When the base cluster is an ESDS the base key length is 4. When the base cluster is a KSDS the base key length is the KSDS key length;

Multiply that number by the number of base cluster records; Add 25% for internal sort work space; Round the answer up to the nearest 32K multiple.

The answer, plus about 170K for IDCAMS processing, plus any BUFND and BUFNI parameters, tells what is needed for an internal sort. This number can be surprisingly large. Consider a 5-byte base key, a 9-byte alternate key, 42,000 records, and UNIQUEKEY. The space needed is 14 bytes (9+5) times 42,000 records = 588,000, times 1.25 (additional 25%) = 735,000. Round that to the nearest 32K and you get 736K. Add the 170K bytes BLDINDEX uses, plus buffers you have allocated (assume 1 cylinder's worth of data buffers on a 4K CI size for both base cluster and AIX, or 2880K), and the working storage you need (the REGION parameter) would be 3786K, or 3.7 megabytes. If you had 100,000 records, this number jumps to over 4.66 megabytes.

Fortunately, in today's environment most jobs get 10 megabytes for virtual storage, so unless the AIX is huge the build uses an internal sort (and run much quicker for it).

Just in case, you should note the BLDINDX command creates its own sort work files. The JCL statements IDCUT1 and IDCUT2 are needed to provide DASD allocations to do so. If the BLDINDX works successfully VSAM deletes them for you. A word of warning: if the BLDINDX fails, these work files remain cataloged and you must manually delete them. Because of that it's a good idea to name them explicitly in their DD statements.

50

Page 51: Basic VSAM

Maintaining VSAM files: the ALTER Command

Many characteristics of VSAM files can be changed "on the fly" with the AMS ALTER command. There are three main considerations:

The correct object must be specified in an entryname argument. Many attributes are valid at only index or only data levels, or both separately. For example, if you're renaming a VSAM KSDS you must rename the cluster, data, and index components separately;

Some characteristics can only be changed at specific times in a VSAM file's lifetime. For example, KEYS can be altered only when the data component of a file is empty;

Multiple components and files can be selected using generic names. An asterisk (*) can be substituted for a single qualifier. The high-level qualifier must be specified, and only one level can be substituted with the "*".

Most of the parameters ALTER can change have the same meaning as they do in the define. In some cases the parameters have a slightly different meaning in the ALTER, and there are a few new ones. Only those parameters which are differ in function from those in the DEFINE is discussed here. In addition, ALTER parameters applicable only to catalogs are left out. For a complete list, see Appendix F.

ADDVOLUMES( ... ) - abbreviated as AVOL, this adds candidate volumes to the list of possible locations for extents. Under SMS, a "*" stands for one unspecified volume. This ALTER can be run at any time.

FREESPACE - can be run at any time.

KEYS - can be altered only if:

The file is empty (HURBA is 0); The current value for KEYS is (64 0); The key description must fit within the record.

Additionally, if the KEYS parameter is for an AIX, it is the AIX key and not the base cluster key definition that is changed.

LIMIT( ... ) - for GDGs, the maximum number of generations to keep.

MANAGEMENTCLASS - results in migration of the file through normal SMS processing.

51

Page 52: Basic VSAM

Maintaining VSAM files: the ALTER Command Parameters (cont'd)

NEWNAME ( ... ) - specifies a new name to be attached to a component. As mentioned above, if a VSAM file is to be renamed a separate ALTER is needed for each component. Note: a file cannot be renamed to an alias in a different catalog than the one it's already in.

NULLIFY ( ... ) - removes a protection attribute. Attributes you can nullify are AUTHORIZATION, CODE, CONTROLPW, EXCEPTIONEXIT, MASTERPW, OWNER, READPW, RETENTION, and UPDATEPW.

RECORDSIZE (n n) - may be altered only if: The file is empty (HURBA is 0); The current value for RECSZ is (4089 32600); The new maximum record size must be at least 7 bytes less than the current

CI size and large enough to contain the entire key; If the object being altered is an AIX, the maximum size must be large enough

to contain all base key pointers to be built.

REMOVEVOLUMES ( ... ) - abbreviated RVOL, removes candidate volumes from the named object. This can also be used in such a way as to remove all VSAM files (including the VVDS) from a given volume by specifying the master catalog as the object named. Since that second function is extremely dangerous, don't do it!

TYPE(LINEAR) - specified for an ESDS with a 4096 CI size, changes that object to an LDS. This change is irreversible. The parameter is ignored for any other type of object.

UNIQUEKEY / NONUNIQUEKEY - has the same meaning as in a define with the following restrictions:

UNIQUEKEY can be specified only for an empty AIX (before BLDINDEX); NONUNIQUEKEY can be specified at any time. Be sure the maximum record

size is large enough to handle the multiple keys.

52

Page 53: Basic VSAM

Some Examples of ALTER Commands

Free space alteration. Note the following:

The ALTER command must specify the component being altered. An error message is issued for an ALTER FSPC on the cluster component, even if the original define had FSPC in the cluster define.

The new free space does not take effect until the next load or resume load, as:

REPRO INFILE(INFILE) OUTFILE(OUTFILE) COUNT(5000) ALTER HLQ.2LQ.VSAM.DATA FSPC(10 5) REPRO INFILE(INFILE) OUTFILE(OUTFILE) SKIP(5000) COUNT(5000) ALTER HLQ.2LQ.VSAM.DATA FSPC(20 10) REPRO INFILE(INFILE) OUTFILE(OUTFILE) SKIP(10000)

Adding a candidate volume:

ALTER HLQ.2LQ.VSAM.DATA AVOL(* *)

Renaming a cluster and its components. This can be done to non-VSAM as well as VSAM files. When renaming a VSAM file, you should rename not only the cluster but also the individual components:

ALTER HLQ.2LQ.VSAM NEWNAME(HLQ.2LQ.NEWLQ.VSAM) ALTER HLQ.2LQ.VSAM.DATA NEWNAME(HLQ.2LQ.NEWLQ.VSAM.DATA) ALTER HLQ.2LQ.VSAM.INDEX - NEWNAME(HLQ.2LQ.NEWLQ.VSAM.INDEX) ALTER HLQ.2LQ.NONVSAM NEWNAME(HLQ.2LQ.NEWLQ.NONVSAM)

53

Page 54: Basic VSAM

Deleting VSAM Files

There is more to deleting VSAM files than simply typing "delete <file>". For example, many VSAM files have more than one component and thus more than one catalog entry. It is therefore possible (but not desirable!) to delete only part of a VSAM file. We'll look at all the parameters of the delete command, but will go into detail on only a few.

These are the objects you can delete with AMS: ALIAS, AIX, CLUSTER, GDG, NONVSAM, NVR, PAGESPACE, PATH, TRUENAME, USERCATALOG, and VVR. Those objects you may not recognize are:

NVR: in a VVDS, the pointer to a non-VSAM file; VVR: in a VVDS, the pointer to a VSAM file; TRUENAME: an entry in a BCS for a data or index component. Used only if

the original cluster's catalog entry is inaccessible.

The following options can be specified:

ERASE / NOERASE - optionally overwrites the file's data space with binary zeroes. Erase should be used only for files protected by something other than RACF, as the erase-on-delete function of RACF is faster.

FILE ( ... ) - names the JCL DDname providing allocation of the volume where the file is located. If this is not specified, AMS attempts to dynamically allocate the file. Access to the volume is required when deleting:

a VVR with no cluster sphere record; with the ERASE parameter; objects from a recoverable catalog; a volume owned by a catalog being deleted with FORCE; volumes containing non-VSAM files with SCRATCH; a member in a PDS.

FILE is not needed if the file is actually cataloged to the named volume. If FILE is specified, the DD statement should have only DDname, UNIT=, DISP=, and VOL=SER= parameters.

If multiple volumes are needed and they're the same device type, they should be specified on the same DD statement. If they are of different types, a concatenated DD statement is needed.

54

Page 55: Basic VSAM

Deleting VSAM Files (cont'd)

FORCE / NOFORCE - deletes GDGs without checking to verify they are empty.

For example, if you try to delete a GDG base with cataloged generations the delete fails. To delete a GDG base with cataloged generations you must specify FORCE, which deletes the generations first, then the base.

PURGE / NOPURGE - specifies whether to delete the file regardless of any expiration date. PURGE always deletes the file; NOPURGE returns a high condition code if the expiration date has not been exceeded.

RECOVERY / NORECOVERY - used for deleting a BCS catalog.

SCRATCH / NOSCRATCH - specifies whether the file is physically removed from any volume it reside(s) on. This has three distinct uses:

When deleting a cluster or AIX, NOSCRATCH specifies the entry is to be removed from the catalog only, without physically deleting the object from the volume. This would be used if the file does not actually exist, but the catalog records pointing to it do exist;

When deleting non-VSAM files, NOSCRATCH specifies only the catalog entry would be removed, not the VTOC entry;

After a volume recovery, NOSCRATCH would be used to delete catalog entries having no corresponding VVDS entries on that volume.

In most cases, a delete should be coded like this:

DELETE <filename>

If you have a need of deleting one or more AIXes without also deleting the associated base clusters you can code your delete like this example:

DELETE <filename> ALTERNATEINDEX

Frequently, in a define you would want to delete the file first. This delete is often coded as:

DELETE <filename> PURGE CLUSTER

The CLUSTER in this case is optional if <filename> is a cluster name.

55

Page 56: Basic VSAM

Verifying VSAM objects

The VERIFY function synchronizes a VSAM file's allocation data with its catalog entry. The two can become out of sync if a CLOSE of the file fails.

VSAM maintains information in the catalog describing each file's end-of-file information, including the High-Used-RBA (HURBA), High-Allocated-RBA (HARBA), end-of-key range (EOKR), and High-Key-RBA fields. During file processing these fields are updated in the in-storage copy of the catalog records. These fields are not written back to the catalog until the file is properly closed. If anything happens to the file before the user issues a CLOSE, the correct information is not written back to the catalog.

VSAM catalog management ensures the failure to properly close a file won't go unnoticed. When a file is opened for output or update, VSAM flips a bit in the VVDS to signal the file is being updated. The bit remains on until a CLOSE is issued and completed. If a failure occurs and this bit is left on, when another attempt is made to access the file as output or update the OPEN needs to ensure the file is in satisfactory condition before it proceeds. This insurance is the VERIFY.

There are three uses of the term VERIFY, each with small differences in operations logic and whether they actually update the catalog or just the in-storage control blocks. The user should take note of the proper conditions for each VERIFY and to use the same VERIFY logic each time for a given file.

Verify from an Assembler Program

An Assembler program can invoke the VSAM VERIFY macro to ensure the program knows the correct end-of-file location in the file. This VERIFY does not update the open-for-update bit, and does not write this information to the catalog unless the file has been opened for output / update AND the file is being closed.

Verify as an IDCAMS Command (Explicit Verify)

The second way to VERIFY a file is by an explicit IDCAMS command. The VERIFY command first issues an open for update. If the open-for-update bit is on, a VERIFY macro is issued. Finally, a CLOSE is issued. This process verifies the HURBA and, if the file is a KSDS, the High-Key RBA and the number of index levels. If there is a discrepancy between the file and the catalog, VERIFY assumes the file is correct and update the catalog accordingly. At CLOSE time the open-for-update bit is turned off.

If the open-for-update bit was on at the start of the VERIFY, AMS returns a non-zero return code. If the bit was off VERIFY returns a 0, meaning the VERIFY was not needed.

56

Page 57: Basic VSAM

The Implicit VERIFY

VSAM OPEN processing automatically invokes an implicit VERIFY if, during OPEN processing, the open-for-update bit is found unaccountably turned on. VSAM considers the bit on unaccountably if it finds no ENQs on the file. An ENQ means the file is open for update elsewhere, which would be the case if the bit is on.

This works the same as for a call from an Assembler program, i. e. the VERIFY does not update the open-for-update bit and does not write the information to the catalog unless the file has been opened for output / update AND the file is being closed. For practical purposes, if a file is left in a VERIFY-able state, it may remain in that state for a string of jobs, each performing their own implicit VERIFY until the file is actually opened for update and is then successfully closed.

VERIFY Function and Syntax

VERIFY can be used to resynchronize clusters, alternate indexes, and catalogs. Paths for AIXes cannot be verified. While it is possible to verify data and index components separately, it results in timestamps being different, thus causing problems at OPEN time. VERIFY cannot work on an LDS. Finally, VERIFY fails on an empty KSDS (i. e. its HURBA is 0). VERIFY has two calls:

VERIFY FILE ( ... ) - specifies the DD name of the file to be verified;

VERIFY DATASET ( ... ) - specifies the DSN to be verified. No JCL statement is needed for this call. During this type of VERIFY, the file is allocated as DISP=OLD. If SHR is required you must use FILE. DATASET can be abbreviated as DS.

During OPEN processing, VSAM checks both the DISP field and the file’s SHAREOPTIONS. The file is allocated only if the DISP allows it. If allocation fails the file is not opened, a message is issued, and the job terminates.

Once the DISP is satisfied, SHAREOPTIONS determine if the file can be open as requested:

SHR(1 3): if the file is open elsewhere as read, no update is allowed. If the program is allowed to open the file as update, no other reads is allowed.

SHR(2 3): Only one job may open the file as UPDATE but allows other opens for READ. During initial load this SHR is treated as SHR(1 3).

SHR(3 3): allows all opens. As above, during initial load this SHR is treated as SHR(1 3). SHR(3 4) is treated the same as SHR(3 3).

57

Page 58: Basic VSAM

A Last Word on VERIFY

Many people (and even many VSAM documents) suggest you VERIFY each time an update is to take place. That could be dangerous, as could ignoring a non-zero condition code issued by an implicit VERIFY. Remember, a VERIFY means the file had its open-for-update bit on. Generally that happens because of an ABEND or system crash. From that it follows the file may well be "broken" from an application perspective, perhaps missing records or data fields in certain records. It's a good practice to check the preceding batch to determine if the last job updating the file really updated correctly.

Printing VSAM Files

The AMS command PRINT creates an output listing of the contents of a VSAM file, catalog, or non-VSAM file. The parameters of PRINT are:

INFILE / INDATASET - abbreviated IFILE and IDS. Specifies either the DDname or the DSN of the file to be printed. For a KSDS, naming the base cluster prints the records in key order. Specifying the PATH name for an AIX prints the records in alternate key order. If a KSDS data component is specified it is printed as if it were an ESDS (i. e. physical order); if the index component is specified only index records is printed (again, in physical order).

OUTFILE ( ... ) - specifies the DDname to send the output to. The DCB is "RECFM=VBA,LRECL=125".

CHARACTER / DUMP / HEX - specifies the output format. CHAR is the abbreviation for CHARACTER. CHAR tries to print each record in EBCDIC format, with non-printable characters appearing as dots (.). HEX prints the file byte-by-byte, in hexadecimal. No attempt is made to translate the print into readable characters. DUMP prints the output in "dump" format, i. e. a hexadecimal representation on the left and a character representation on the right.

FROMKEY ( ... ) / FROMADDRESS ( ... ) / FROMNUMBER ( ... ) / SKIP ( ... ) indicate a starting position in the file. If none of these are specified, processing starts with the first logical record. FROMKEY cannot be used on non-keyed files, while FROMNUMBER is for RRDSes only. SKIP should not be used when printing through a PATH, since the results are unpredictable.

TOKEY ( ... ) / TOADDRESS ( ... ) / TONUMBER ( ... ) / COUNT ( ... ) work in conjunction with the "FROM" parameters. These specify where to stop printing. As such, the restrictions are the same. Do not use COUNT when printing through a PATH, since the results are unpredictable.

58

Page 59: Basic VSAM

Backing Up and Recovering VSAM Files

One of the most important considerations for any access method is the approach used to back up the file's records, and to restore those records if the file breaks. There are many programs for performing backup and restore functions. Prior to DFP, IBM-supplied programs such as IEHDASDR or IEHMOVE were available to back up or restore full volumes or individual files. These were slow and had obtuse control statement formats, so for many years the program of choice for backup and recovery was FDR. With the advent of DFP, the IBM product DFDSS has replaced FDR in most installations.

Additionally, there are AMS commands similar in function to the old IEH* programs. These commands are REPRO, EXPORT, and IMPORT.

REPRO is the primary AMS command for copying data sets. It can copy both VSAM and non-VSAM. Since it's easier to use than IMPORT and EXPORT it is the command of choice to handle backing up VSAM files (if you're not using DFDSS, of course). REPRO's process is easy to understand:

Open the input file and determine the access method to use; Open the output file and determine its access method. In addition, REPRO

determines if there are records present. If there are, the "incoming" records are merged with them. During the copy the records are deblocked from the input file and reblocked for the output file.

REPRO cannot read or write records larger than 32,760 bytes.

The following types of copies can be done with REPRO:

ESDS to ESDS, KSDS, RRDS, non-VSAM sequential; KSDS to ESDS, KSDS, RRDS, non-VSAM sequential; RRDS to ESDS, KSDS, RRDS, non-VSAM sequential; LDS to LDS, non-VSAM sequential; non-VSAM sequential to ESDS, KSDS, RRDS, non-VSAM sequential.

In addition, REPRO can copy, merge, or split ICF catalogs.

If the output is a KSDS, reorganization takes place automatically. That means the output KSDS is initially loaded, with consideration given to free space, and all records is written in ascending key order. The input records must be sorted in key order with no duplicates.

59

Page 60: Basic VSAM

REPRO Function and Syntax

INFILE ( ... ) / INDATASET ( ... ) - abbreviated by IFILE and IDS. The INFILE argument is the JCL DDname of the input file. INDATASET names the DSN and does not require a JCL statement. The input file can be either a VSAM file, a non-VSAM file, a PATH over an AIX or cluster, or an ICF catalog.

For performance purposes, unless the file is very small INFILE should be used, as INDATASET does not allow you to use buffers.

OUTFILE ( ... ) / OUTDATASET ( ... ) - abbreviated by OFILE and ODS respectively. The OUTFILE argument is the JCL DDname of the output file. OUTDATASET names the DSN and does not require a JCL statement. This file can be either a VSAM file, a non-VSAM file, a PATH over an AIX or cluster, an ICF catalog (if the input is an ICF catalog), or SYSOUT (INFILE only).

For performance purposes, unless the file is very small OUTFILE should be used, as OUTDATASET does not allow you to use buffers.

ENTRIES ( ... ) / LEVEL ( ... ) - used for merging or copying an ICF catalog.

FILE ( ... ) - specified when merging ICF catalogs. FROMKEY ( ... ) / FROMADDRESS ( ... ) / FROMNUMBER ( ... ) / SKIP ( ... ) indicate a starting position in the file. If none of these are given processing starts with the first logical record. FROMKEY cannot be used on non-keyed files, while FROMNUMBER is for RRDSes only. SKIP is the only parameter usable with non-VSAM files. SKIP should not be used when using a PATH, since the results are unpredictable, and cannot be used with an LDS.

MERGECAT / NOMERGECAT - used only for ICF catalogs.

REPLACE / NOREPLACE - indicates whether a record in the input is to replace the corresponding record in the output. These parameters work when the repro is a merge, i. e. the target file has records in it. They are ignored if the target file has no records (HURBA is 0). In a MERGE a KSDS is not reorged.

In a KSDS merge the record is replaced if its keys are the same. In an RRDS the record replaces the target record slot, whatever its prior contents.

If NOREPLACE is specified and a source record has the same key as a target record, a message is issued. If four such messages occur, REPRO terminates. REPLACE cannot be used if the target file is a PATH over an AIX, or is a base KSDS with a UNIQUEKEY AIX defined to it and using UPGRADE.

60

Page 61: Basic VSAM

REPRO Function and Syntax (cont'd)

REUSE / NOREUSE - REUSE specifies the VSAM target file is opened as a reusable file, provided it was defined as REUSE. If the target file was not defined as REUSE this parameter works only if the target is empty (i. e. HURBA = 0). Otherwise the REPRO fails with an error message.

If a KSDS file is opened as REUSE it is treated as an initial load.

With NOREUSE the file is opened as not reusable, regardless of the way the target file was defined. If the target has records in it, the REPRO acts as a merge, allowing REPLACE / NOREPLACE to take over. This is the default condition.

TOKEY ( ... ) / TOADDRESS ( ... ) / TONUMBER ( ... ) / COUNT ( ... ) work in conjunction with the "FROM" parameters. These specify where to stop printing. As such, the restrictions are the same. Do not use COUNT when printing through a PATH, since the results are unpredictable. The COUNT parameter is the only one in this group usable with non-VSAM files.

The EXPORT Command

The primary function of EXPORT is to create a transportable copy of a VSAM file, including clusters and alternate indexes, to be later recreated with IMPORT. EXPORT is also used to back up catalogs. EXPORT works like this:

After command syntax checking, EXPORT dumps the catalog records for all objects (cluster, data, index, and all extension records) to the backup file. EXPORT cannot process records larger than 32,760 bytes;

After the catalog records, the VSAM file(s)'s data are copied to the backup media. EXPORT accesses the file sequentially. For a KSDS, EXPORT uses the sequence set records. CIs are read and deblocked into logical records, then reblocked into the user-given block size for the output file;

Finally, after all data records have been dumped, the EXPORT command is checked for the keyword TEMPORARY or PERMANENT. If PERMANENT is used, AMS assumes the file is being moved to another installation and deletes the source file. If TEMPORARY is used, AMS marks the resulting file with a timestamp and leaves the source file alone.

Since the output file contains catalog, header, and data records, the format of the output from an EXPORT is unique to itself. If necessary, the file can be read by REPRO, but the catalog and header records must be skipped.

61

Page 62: Basic VSAM

The EXPORT Command Function and Syntax

The first parameter for an EXPORT of a catalog must be the name of the catalog. The only other parameter for that function is DISCONNECT. For all other EXPORTS the first parameter is the entry name of the file being exported. Other parameters are:

OUTFILE ( ... ) / OUTDATASET ( ... ) - abbreviated by OFILE and ODS respectively. The OUTFILE argument is the JCL DDname of the output file. OUTDATASET names the DSN and does not require a JCL statement. Since the output file is usually a tape, FILE should be used. The output file is physical sequential with "RECFM=VBS" and an LRECL depending on the input file. Generally the LRECL is the input file's maximum LRECL plus four bytes. If the MAXLRECL is less than 324, EXPORT sets the output LRECL to 328. The output BLKSIZE is 2048 unless you change it to something larger.

CIMODE / RECORDMODE - specifies whether CI processing or logical record processing is used to export ESDS base cluster records. RECORDMODE is the default.

CIMODE processes ESDS base cluster records as a single CI. As the file is read, an entire CI is retrieved and written to the output file. In effect, each CI is treated as a logical record. This is not usable for an ESDS with an AIX over it.

CIMODE is the only way to EXPORT an LDS.

INFILE ( ... ) - abbreviated by IFILE, this provides the JCL DDname of the input file. The default is to dynamically allocate the file. For performance purposes, unless the file is very small INFILE should be used.

ERASE / NOERASE - specifies whether VSAM is to overwrite the data with binary zeros when the file is deleted. This overrides the DEFINE parameter. ERASE can only be specified when PERMANENT is used.

PURGE / NOPURGE - PURGE specifies to delete the file regardless of any expiration date.

TEMPORARY / PERMANENT - PERMANENT causes the file being exported to be deleted at the end of the EXPORT. Since PERMANENT is the default, using EXPORT can be dangerous.

62

Page 63: Basic VSAM

The IMPORT Command

The primary function of IMPORT is to recreate a transportable copy of a VSAM file, including clusters and alternate indexes, from a file produced by an EXPORT. IMPORT is also used to restore catalogs. IMPORT works like this:

After command syntax checking, IMPORT determines the catalog to be used for the restore. IMPORT then attempts to locate the file being restored;

If the file is found, the "TEMP-EXP" bit in the catalog is checked. If the bit is on, IMPORT continues. If the bit is off, IMPORT ends with an error because the object has not had a transportable copy made with EXPORT;

If the file is not cataloged, processing continues. If the file was cataloged, it is deleted;

Next, the catalog records from the EXPORT are read in from the copy and used to create defines for all exported objects. IMPORT then issues the define command for each object to be created.

If the file being imported was defined with an allocation amount less than one cylinder, its allocation is bumped up by one until, after a succession of IMPORT commands, the file reaches a control area size of one cylinder.

Finally, the logical data records are read from the transportable volume into the new file.

Since IMPORT and EXPORT are the only way of backing up a catalog, IMPORT has a few commands exclusively relating to ICF catalogs. This document covers only those IMPORT parameters pertaining to "regular files."

The following parameters are used for catalogs only: ALIAS, CONNECT, LOCK/UNLOCK. Other parameters of IMPORT are discussed on the following pages.

63

Page 64: Basic VSAM

The IMPORT Command Function and Syntax

INFILE ( ... ) / INDATASET ( ... ) - abbreviated by IFILE and IDS. The INFILE argument is the JCL DDname of the input file. INDATASET names the DSN and does not require a JCL statement. The file must have been produced by an EXPORT. For performance purposes, unless the file is very small INFILE should be used, as INDATASET does not allow you to use buffers.

OUTFILE ( ... ) / OUTDATASET ( ... ) - abbreviated by OFILE and ODS respectively. The OUTFILE argument is the JCL DDname of the output file. OUTDATASET names the DSN and does not require a JCL statement.

If the file is being restored on a different volume from its prior location, the DD statement must contain "DSN=<cluster>,DISP=OLD,AMP=AMORG" as well as a unit and "VOL=SER" parameter.

If the file's data and index components existed on different volumes at EXPORT time, the DD statement must be concatenated. The first DD names the cluster component and its VOLSER, while the second DD names the index component and its VOLSER.

If the NEWNAME option is used the DSN must specify the new name.

ERASE / NOERASE - specifies whether VSAM is to overwrite the data with binary zeros before the file is imported. This overrides the DEFINE parameter. ERASE can only be specified when PERMANENT is used.

INTOEMPTY - specifies the data is being imported to an empty cluster, i. e. one with an HURBA of 0. If the cluster is empty and this parameter is not given, IMPORT fails.

This parameter is useful when you need to change parameters that cannot be modified on the OBJECTS parameter, e. g. CI SIZE or CYLINDERS.

PURGE / NOPURGE - PURGE deletes the file regardless of any expiration date.

SAVRAC / NOSAVRAC - specifies whether the existing RACF profiles are to be used or new profiles created. SAVRAC uses the existing profiles. NOSAVRAC removes, then recreates, RACF profiles protecting all objects being imported. NOSAVRAC is the default.

64

Page 65: Basic VSAM

The IMPORT Command Function and Syntax (cont'd)

OBJECTS ( ... ) - has several operands:

entryname - specifies the object being modified. A separate OBJECTS statement is needed for each object being imported. Each "entryname" group is enclosed in parentheses, with all groups being enclosed in OBJECTS' parenthesis.

FILE ( ... ) - gives the JCL DD statement naming the volume(s) for the object.

MANAGEMENTCLASS ( ... ) - specifies the management class for the object.

NEWNAME ( ... ) - the new name being assigned to the object.

STORAGECLASS ( ... ) - specifies the storage class for the object named.

VOLUMES ( ... ) - specifies the volume(s) to receive the cluster. If this parameter is not supplied, IMPORT attempts to put the object back to its original volumes. If specified, all volumes must be of the same device type.

If VOLUMES is specified at the cluster or AIX level it is propagated to all components. If it is specified at the DATA or INDEX level it applies to that component only.

Problems with IMPORT and EXPORT

As designed, these commands work well. However, since they were designed to move data from one complex to another, they have some drawbacks relative to REPRO, namely it's difficult to change file attributes. In addition, with proper buffering, REPRO is faster than IMPORT and EXPORT. In short, if you need to back up and recover your data with AMS commands, you should use REPRO in combination with stored delete / defines.

65

Page 66: Basic VSAM

Examples of REPRO, EXPORT, and IMPORT

Assuming valid JCL, here are examples of REPRO and EXPORT commands being used to back up a VSAM file.

REPRO INFILE(INFILE) OUTFILE(TAPE) EXPORT <filename> OUTFILE(TAPE) TEMPORARY

Here are examples of REPRO and EXPORT commands being used to recover a VSAM file.

DELETE <filename> DEFINE CLUSTER( <filename> ... ) then REPRO INFILE(TAPE) OUTFILE(OUTFILE)

IMPORT INFILE(TAPE) OUTFILE( <DDname> )

In the REPRO example changing the define would also change any file parameters needing to be changed. To do this with IMPORT:

DELETE <filename> DEFINE CLUSTER( <filename> ... ) IMPORT INFILE(TAPE) OUTFILE( <DDname> ) INTOEMPTY

VSAM Catalog Maintenance

At this point, a full VSAM class would discuss catalog backup, recovery, and problem investigation. Since none of us have the authority to operate with catalogs this information is skipped. If you want to know more feel free to borrow The Complete Source Book for VSAM File Structures cited in the appendix.

A Final Word in this Document

A companion to this document is discussion of the AMS LISTCAT command, including a description of its output and how to interpret it. The LISTCAT command can help you tune your VSAM files once they've been used for a while. There is no possible way to predict accurately how a file looks after several months of use. The LISTC is the only way of verifying you've done your design work properly. It's also the only way to solve certain problems.

Use these documents wisely and your VSAM files will remain happy and healthy... as will your customers!

66

Page 67: Basic VSAM

Bibliography

The Complete Source Book for VSAM File Structures, Ronald K. Ferguson,SIS publications, Seventh Printing, 1992

67


Recommended