VSAM Reviewer

VSAM (Virtual Access Storage Method)

1) What are VSAM datasets?
•    VSAM data sets are held on direct access storage devices (DASD) auxiliary storage. VSAM divides its data set storage into control areas (CA), which are further divided into control intervals (CI). Control intervals are the unit of data transmission between virtual and auxiliary storage. Each one is of fixed size and, in general, contains a number of records. A KSDS or ESDS can have records that extend over more than one control interval. These are called spanned records.

•    There are some special coding considerations for VSAM files under z/OS for access method services (IDCAMS) commands, environment variables, and JCL.
A VSAM file is available if all of the following conditions are true:
o    You define it using access method services.
o    You define it for your program by providing a DD statement, an environment variable, or an ALLOCATE command.
o    It has previously contained a record.
A VSAM file is unavailable if it has never contained a record, even if you have defined it.
You always get a return code of zero on completion of the OPEN statement for a VSAM sequential file.
Use the access method services REPRO command to empty a file. Deleting records in this manner resets the high-use relative byte address (RBA) of the file to zero. The file is effectively empty and appears to COBOL as if it never contained a record.

2) What are the different type of VSAM datasets and define each?
•    The different types of VSAM datasets are as follows:
o    Key-sequenced data set (KSDS)
o    Entry-sequenced data set (ESDS)
o    Relative record data set (RRDS) (both fixed and variable record lengths)

•    Key-sequenced data set (KSDS)
o    A key-sequenced data set has each of its records identified by a key. (The key of each record is simply a field in a predefined position within the record.)
o    Each key must be unique in the data set.
o    When the data set is initially loaded with data, or when new records are added, the logical order of the records depends on the collating sequence of the key field. This also fixes the order in which you retrieve records when you browse through the data set.
o    To find the physical location of a record in a KSDS, VSAM creates and maintains an index. This relates the key of each record to the record's relative location in the data set. When you add or delete records, this index is updated accordingly.
o    KSDS records can be retrieved directly with a key.
o    The key is specified when you define the dataset and can be up to 255 bytes at any offset into the record.
o    A KSDS is made up of two components, the data and an index. The data component contains, the, er, data. The index contains the keys and pointers into the data component.
o    Note that a KSDS uses a sparse index which assumes the records are in order within the data blocks which is why you can't load a KSDS with records that are out of order.
o    The data and index components are linked together in a logical entity known as a cluster. Usually processes refer to the cluster name to use a KSDS. Unlike an ESDS or RRDS, deleted KSDS records are physically removed and the space is reclaimed.

•    Entry-sequenced data set (ESDS)
o    An entry-sequenced data set is one in which each record is identified by its relative byte address (RBA).
o    Records are held in an ESDS in the order in which they were first loaded into the data set. New records added to an ESDS always go after the last record in the data set. You may not delete records or alter their lengths. After a record has been stored in an ESDS, its RBA remains constant. When browsing, records are retrieved in the order in which they were added to the data set.
o    An ESDS is essentially a sequential dataset where new records are always inserted at the end.
o    You cannot access records directly with a key. However, you may access specific records with a relative byte address (RBA), if you have or can calculate it. In fact, it's fairly common to see CICS application use an ESDS as a log file to write records in sequential order while retrieving the new record's RBA from the RIDFLD operand of the EXEC CICS WRITE command. If the application squirrels away the RBA it can later retrieve the log record directly. Also note that you cannot physically delete a record from an ESDS. Instead, most applications utilize a "logical delete" scheme where a field in the ESDS record is set to a value indicating the record is no longer valid.

•    Relative record data set (RRDS)
o    A relative record data set has records that are identified by their relative record number (RRN). The first record in the data set is RRN 1; the second is RRN 2, and so on. Records in an RRDS can be fixed or variable length records, and
o    the way in which VSAM handles the data depends on whether the data set is a fixed or variable RRDS. A fixed RRDS has fixed-length slots predefined to VSAM, into which records are stored. The length of a record on a fixed RRDS is always equal to the size of the slot. VSAM locates records in a fixed RRDS by multiplying the slot size by the RRN (which you supply on the file control request), to calculate the byte offset from the start of the data set.
o    A variable RRDS, on the other hand, can accept records of any length up to the maximum for the data set. In a variable RRDS VSAM locates the records by means of an index.
o    A fixed RRDS generally offers better performance. A variable RRDS offers greater function.
o    An RRDS consists of preformatted, fixed length slots that may or may not have records in them. RRDS's can be processed sequentially or directly through a relative record number (RRN). Note that when a record is erased the slot still holds its place in the dataset, unlike a KSDS where VSAM reclaims the empty space.

3) How are VSAM files defined?
•    You can process VSAM entry-sequenced, key-sequenced, and relative-record data sets in Enterprise COBOL only after you define them through access method services (IDCAMS).

•    A VSAM cluster is a logical definition for a VSAM data set and has one or two components:
o    The data component of a VSAM cluster contains the data records.
o    The index component of a VSAM key-sequenced cluster consists of the index records.

•    Use the DEFINE CLUSTER access-method services command to define VSAM data sets (clusters). This process includes creating an entry in an integrated catalog without any data transfer. Define the following information about the cluster:
o    Name of the entry
o    Name of the catalog to contain this definition and its password (can use default name)
o    Organization (sequential, indexed, or relative)
o    Device and volumes that the data set will occupy
o    Space required for the data set
o    Record size and control interval sizes (CISIZE)
o    Passwords (if any) required for future access

•    Depending on what kind of data set is in the cluster, also define the following information for each cluster:
o    For VSAM indexed data sets (KSDS), specify length and position of the prime key in the records.
o    For VSAM fixed-length relative-record data sets (RRDS), specify the record size as greater than or equal to the maximum size COBOL record:
DEFINE CLUSTER NUMBERED
RECORDSIZE(n,n)
When you define a data set in this way, all records are padded to the fixed slot size n. If you use the RECORD IS VARYING ON data-name form of the RECORD clause, a WRITE or REWRITE uses the length specified in DEPENDING ON data-name as the length of the record to be transferred by VSAM. This data is then padded to the fixed slot size. READ statements always return the fixed slot size in the DEPENDING ON data-name.
o    For VSAM variable-length relative-record data sets (RRDS), specify the average size COBOL record expected and the maximum size COBOL record expected:
DEFINE CLUSTER NUMBERED
RECORDSIZE(avg,m)
The average size COBOL record expected must be less than the maximum size COBOL record expected.
o    For COBOL simulated variable-length relative-record data sets, specify the average size of the COBOL records and a size that is greater than or equal to the maximum size COBOL record plus 4:
DEFINE CLUSTER INDEXED
KEYS(4,0)
RECORDSIZE(avg,m)
The average size COBOL record expected must be less than the maximum size COBOL record expected.

4) How do you define VSAM file organizations and records in a COBOL program?
•    For all files that you process in your COBOL program, you need to define the files to the operating system with an appropriate system data definition.
Depending on the operating system, this system data definition can take any of the following forms:
o    DD statement for MVS JCL.
o    ALLOCATE command under TSO.
The following examples show the relationship of a FILE-CONTROL entry to the system data definition and to the FD entry in the FILE SECTION:

JCL DD statement:
    (1)
//OUTFILE  DD  DSNAME=MY.OUT171,UNIT=SYSDA,SPACE=(TRK,(50,5))
/*

COBOL code:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT CARPOOL
      ASSIGN TO OUTFILE (1)
      ORGANIZATION IS SEQUENTIAL.
. . .
DATA DIVISION.
FILE SECTION.
FD CARPOOL       (2)
    LABEL  RECORD STANDARD
    BLOCK  CONTAINS 0 CHARACTERS
    RECORD CONTAINS 80 CHARACTERS

(1)
The assignment-name in the ASSIGN clause points to the ddname OUTFILE in the DD statement or the environment variable OUTFILE in the export command:
•    //OUTFILE  DD DSNAME=OUT171 . . ., or
•    export OUTFILE= . . .

(2)
When you specify a file file-name in a FILE-CONTROL entry, you must describe the file in an FD entry:
SELECT CARPOOL
. . .
FD CARPOOL

•    Use an entry in the FILE-CONTROL paragraph in the ENVIRONMENT DIVISION to define the file organization and access modes for the VSAM files in your COBOL program.

•    In the FILE SECTION of the DATA DIVISION, code a file description (FD) entry for the file. In the associated record description entry or entries, define the record-name and record length. Code the logical size of the records with the RECORD clause.
Important: You can process VSAM data sets in Enterprise COBOL programs only after you define them with access method services.

VSAM file organization, access mode, and record format
File Org       Sequential access    Random access    Dynamic access    Fixed length    Variable length
ESDS          Yes                         No                       No                       Yes                 Yes
KSDS         Yes                         Yes                       Yes                      Yes                 Yes
RRDS         Yes                         Yes                       Yes                      Yes                 Yes


5) What is an Alternate Index (AIX)?   How is it defined and loaded?
•    An alternate index is a key-sequenced data set containing index entries organized by the alternate keys of its associated base data records. It provides another way of locating records in the data component of a cluster.

•    An alternate index can be defined over a key-sequenced or entry-sequenced cluster.

•    An alternate index cannot be defined for a reusable cluster, a fixed- or variable-length RRDS, an extended addressable ESDS, a catalog, a VVDS (data set name 'SYS1.VVDS.Vvolser'), another alternate index, a linear data set, or a non-VSAM data set.

•    The data class parameter can be specified for a system-managed alternate index. Access method services DEFINE will assign the same management class and storage class as the alternate index's base cluster. If a base cluster is defined as extended format, then the alternate index it relates to must be able to be defined as extended format. Alternate indexes cannot be compressed.

•    The sequence for building an alternate index is as follows:
1.    Define the base cluster, using either the ALLOCATE command, the DEFINE CLUSTER command, or JCL.
2.    Load the base cluster either by using the REPRO command or by writing your own program to load the data set.
3.    Define the alternate index, using the DEFINE ALTERNATEINDEX command.
4.    Relate the alternate index to the base cluster, using the DEFINE PATH command. The base cluster and alternate index are described by entries in the same catalog.
5.    Build the alternate index, using the BLDINDEX command.

•    BLDINDEX is used to build the alternate keys and load the alternate indexes.

6) What is the Use of the List and Verify command?
•    The LISTCAT command is provided to list the information from catalog entries. If you have been reading this page in sequence, you have already seen output from the LISTCAT command in the SYSOUT listings from my examples of many of the other AMS commands. It is almost always a good idea to list the catalog entries for objects immediately following their creation to visually verify that all of the options you intended to specify were entered correctly and had the desired effect on the entry created. It is also frequently necessary to list fields from the catalog entry for a VSAM object to diagnose problems.

•    The VERIFY command is used to verify VSAM Dataset. If a job terminates abnormally and a VSAM dataset is not closed, the catalog entry for the dataset is flagged to indicate that the dataset may be corrupt. Before the dataset can be opened again, the VERIFY command must be used to correctly identify the end of the dataset and reset the catalog entry.

7) How are empty VSAM files loaded?
•    There are 3 techniques to initially load a empty VSAM file.
o    Initially loading a file sequentially
o    Initially loading a file randomly or dynamically
o    Loading a VSAM data set with access method services

•    Initially loading a file sequentially:
o    Initially loading a file means writing records into the file for the first time. Doing so is not the same as writing records into a file from which all previous records have been deleted. To initially load a VSAM file:
1.    Open the file.
2.    Use sequential processing (ACCESS IS SEQUENTIAL). (Sequential processing is faster than random or dynamic processing.)
3.    Use WRITE to add a record to the file.
o    Using OPEN OUTPUT to load a VSAM file significantly improves the performance of your program. Using OPEN I-O or OPEN EXTEND has a negative effect on the performance of your program.
o    When you load VSAM indexed files sequentially, you optimize both loading performance and subsequent processing performance, because sequential processing maintains user-defined free space. Future insertions will be more efficient.
o    With ACCESS IS SEQUENTIAL, you must write the records in ascending RECORD KEY order.
o    When you load VSAM relative files sequentially, the records are placed in the file in the ascending order of relative record numbers.

•    Initially loading a file randomly or dynamically:
o    You can use random or dynamic processing to load a file, but they are not as efficient as sequential processing. Because VSAM does not support random or dynamic processing, COBOL has to perform some extra processing to enable you to use ACCESS IS RANDOM or ACCESS IS DYNAMIC with OPEN OUTPUT or OPEN I-O. These steps prepare the file for use and give it the status of a loaded file because it has been used at least once.
o    In addition to extra overhead for preparing files for use, random processing does not consider any user-defined free space. As a result, any future insertions might be inefficient. Sequential processing maintains user-defined free space.
o    When you are loading an extended-format VSAM data set, file status 30 will occur for the OPEN if z/OS DFSMS system-managed buffering sets the buffering to local shared resources (LSR). To successfully load the VSAM data set in this case, specify ACCBIAS=USER in the DD AMP parameter for the VSAM data set to bypass system-managed buffering.

•    Loading a VSAM data set with access method services
o    You can load or update a VSAM data set by using the access method services REPRO command. Use REPRO whenever possible.

8) How can records be added to a non empty VSAM file?
•    Use the COBOL WRITE statement to add a record to a file without replacing any existing records.

•    The record to be added must not be larger than the maximum record size that you set when you defined the file.

•    Your program should check the file status key after each WRITE statement.

•    There are 2 techniques programmatically to add records in a VSAM file.
o    Adding records sequentially
o    Adding records randomly or dynamically

•    Adding records sequentially
o    Use ACCESS IS SEQUENTIAL and code the WRITE statement to add records sequentially to the end of a VSAM file that has been opened with either OUTPUT or EXTEND.
o    Sequential files are always written sequentially.
o    For indexed files, you must write new records in ascending key sequence. If you open the file EXTEND, the record keys of the records to be added must be higher than the highest primary record key on the file when you opened the file.
o    For relative files, the records must be in sequence. If you include a RELATIVE KEY data item in the SELECT clause, the relative record number of the record to be written is placed in that data item.
o    Adding records randomly or dynamically

•    Adding records randomly or dynamically
o    When you write records to an indexed data set and ACCESS IS RANDOM or ACCESS IS DYNAMIC, you can write the records in any order.

9) How are records in a VSAM file updated/replaced?
•    To replace a record in a VSAM file, use REWRITE on a file that you opened as I-O.

•    If the file was not opened as I-O, the record is not rewritten and the status key is set to 49. Check the file status key after each REWRITE statement.

•    For sequential files, the length of the replacement record must be the same as the length of the original record.

•    For indexed files or variable-length relative files, you can change the length of the record you replace.

•    To replace a record randomly or dynamically, you do not have to first READ the record. Instead, locate the record you want to replace as follows:
o    For indexed files, move the record key to the RECORD KEY data item, and then issue the REWRITE.
o    For relative files, move the relative record number to the RELATIVE KEY data item, and then issue the REWRITE.

10) How do you delete records from a VSAM file?
•    To remove an existing record from an indexed or relative file, open the file I-O and use the DELETE statement.

•    You cannot use DELETE on a sequential file.

•    When you use ACCESS IS SEQUENTIAL or the file contains spanned records, your program must first read the record to be deleted. The DELETE then removes the record that was read. If the DELETE is not preceded by a successful READ, the deletion is not done and the status key value is set to 92.

•    When you use ACCESS IS RANDOM or ACCESS IS DYNAMIC, your program does not have to first read the record to be deleted. To delete a record, move the key of the record to be deleted to the RECORD KEY data item, and then issue the DELETE. Your program should check the file status key after each DELETE statement.

11) How do you handle errors when processing VSAM files?
•    When an input or output statement operation fails, COBOL does not perform corrective action for you.

•    All OPEN and CLOSE errors with a VSAM file, whether logical errors in your program or input/output errors on the external storage media, return control to your COBOL program even if you coded no DECLARATIVE and no FILE STATUS clause.

•    If any other input or output statement operation fails, you choose whether your program will continue running after a less-than-severe error.

•    COBOL provides these ways for you to intercept and handle certain VSAM input and output errors:
o    End-of-file phrase (AT END)
o    EXCEPTION/ERROR declarative
o    FILE STATUS clause (file status key and VSAM status code)
o    INVALID KEY phrase

•    You should define a status key for each VSAM file that you define in your program. Check the status key value after each input or output request, especially OPEN and CLOSE.

•    If you do not code a file status key or a declarative, serious VSAM processing errors will cause a message to be issued and a Language Environment condition to be signaled, which will cause an abend if you specify the runtime option ABTERMENC(ABEND).

12) What are the common COBOL statements to process VSAM files?
•    Use the COBOL statements shown below to process VSAM files.
    OPEN  - To connect the VSAM data set to your COBOL program for processing.

    WRITE - To add records to a file or load a file.

    START- To establish the current location in the cluster for a READ NEXT.
    START does not retrieve a record; it only sets the current record pointer.

    READ and READ NEXT- To retrieve records from a file.

    REWRITE- To update records.

    DELETE- To logically remove records from indexed and relative files only.

    CLOSE- To disconnect the VSAM data set from your program.

•    All of the following factors determine which I/O statements you can use for a given VSAM data set:
o    Access mode (sequential, random, or dynamic)
o    File organization (ESDS, KSDS, or RRDS)
o    Mode of OPEN statement (INPUT, OUTPUT, I-O, or EXTEND)

•    The fields that you code in the FILE STATUS clause are updated by VSAM after each input-output statement to indicate the success or failure of the operation.

13) What are the common VSAM status codes?
00  -  SUCCESSFUL COMPLETION                   
02  -  DUPLICATE KEY, NON UNIQ. ALT INDX       
04  -  READ, WRONG LENGTH RECORD               
05  -  OPEN, FILE NOT PRESENT                  
10  -  END OF FILE                             
20  -  INVALID KEY VSAM KSDS OR RRDS           
22  -  DUPLICATE KEY                           
23  -  RECORD OR FILE NOT FOUND                
35  -  OPEN, FILE NOT PRESENT                          
41  -  OPEN, FILE IS OPEN                              
42  -  CLOSE, FILE IS CLOSED                           
97  -  VSAM - OPEN OK, FILE INTEGRITY VERIFIED  

14) What is the file position indicator?
•    The file position indicator marks the next record to be accessed for sequential COBOL requests. You do not set the file position indicator in your program. It is set by successful OPEN, START, READ, and READ NEXT statements.

•    Subsequent READ or READ NEXT requests use the established file position indicator location and update it.

•    The file position indicator is not used or affected by the output statements WRITE, REWRITE, or DELETE. The file position indicator has no meaning for random processing.