VSAM General Tips and Status Codes


What is VSAM?

VSAM, for Virtual Storage Access Method, is an IBM access method intended to provide, in one coherent system, most of the file organization needs for application programmers.

An access method such as VSAM is not a database management system. The two are easily confused. An access method stores and retrieves data. It does to provide for a relationship among the data, aside from data. It does not provide for a relationship among the data, aside from the fact that sequential datasets are in sequential order. A database system such as DB2 or IMS is often implemented using VSAM.  They differ in that the database also carries information that shows the relationship among the data. To use the book example, a book becomes a database when it references information in other books.

As such, it provides sequential, indexed, relative record and linear datasets. In VSAM terminology, these four types of data organization are named as follows:

O      ESDS.  Entry-Sequenced Datasets. These are the familiar sequential datasets, and they can be read or written only in sequential order – that is, the order of entry.

O      KSDS.  Key-Sequenced Datasets. These are datasets stored in order of a key field in the record. Individual records can be accessed randomly by the record key. The keys are stored in a separate index so that record access is a two-stage process: first locating the key in the index and then using the information in the index for the key to locate the record.
O      RSDS.  Relative record Datasets. These are datasets stored in some sequential order. The records have no internal keys, but individual records can be accessed randomly by giving the relative position of the record in the dataset, such as 1,2, and so on.
O      LDS.  Linear Datasets.  These are datasets that consist of a long stream of bytes. They aren’t considered to have records.

For an MVS dataset like PS or a PDS, the attribute information is contained in the VTOC (Volume Table of Contents) for the volume on which the dataset is stored. However, for a VSAM dataset, this same attribute information is stored in its catalog entry and is easily accessible with a single LISTCAT command, which can be entered online of in batch mode. The generic structure of VSAM consists of one master and at least one (usually multiple) user catalog. Master and user catalogs are each defined separately and are considered separate VSAM objects. The master catalog has pointers to the various user catalogs, which contain application datasets and are typically allocated by function within an environment, say one for programmers, one for accounting – whatever is appropriate for the enterprise. A large installation may support hundreds of user catalogs.
The catalog structure contains entries for both VSAM and non-VSAM datasets and other objects. While a VSAM dataset must be cataloged in either the master or a user catalog, a non-VSAM dataset can be cataloged in either the master or a user catalog, or in a OS catalog (CVOL, for Control Volume). You cannot catalog a VSAM dataset in a CVOL.

Master Catalog
User Catalog
User Catalog


VSAM uses two types of catalogs, an older one aptly named VSAM and a newer one that supports the XA and ESA environments and is called the Integrated Catalog Facility (ICF). Each VSAM dataset cataloged in an ICF catalog has its own VTOC entry.

A major strength of VSAM is that a single set of data management facilities called Access Method Services (AMS) manages both VSAM and non-VSAM datasets. AMS user a command processor called IDCAMS (Integrated data and catalog access method services) to handle a variety of functions such as creating, reproducing, and printing datasets, and listing catalog contents. IDCAMS is a program, and as an application programmer, much of your VSAM work will involve IDCAMS processing.

Control Interval, Control Area and Free Space:
VSAM stores records in the data component in units called control intervals (CI).  The control interval is VSAM’s equivalent of a block, and it is the unit of data that is actually transmitted when records are read or written. You specify control interval size with a CISZ parameter of the IDCAMS DEFINE CLUSTER command when you create the VSAM dataset. This also specifies the buffer size. The following figure illustrates the records stored in a control interval.
                                                                                                                                                                                                                                                               The proper selection of the CISZ is important, both to minimize unused space and to provide an efficient unit for transmitting records. This gets tricky because the control field (CF) is not a fixed length. The control field actually consists of two sub-fields: one Control Information Definition Field (CIDF) and one or more Record Definition Fields (RDF). The length of the control field can affect the CISZ selected.
When there is no room to add more records in a control interval, VSAM performs what is termed a control interval split. When you create a VSAM dataset, in addition to specifying a percentage of free space within each control interval, the FREESPACE parameter can also specify a percentage of control intervals to leave free. The control interval split moves records off to one of the free control intervals. When a control split occurs, the inserted records may no longer be in sequential order. The control intervals may also not be in sequence, depending on where the next empty control interval is located. This is not a problem with KSDS because it accesses the records through an index. However, from a performance point of view, control interval splits for a KSDS can cause big problems. It is not a problem for the other VSAM dataset types, because they can not have CI splits.
A Control Area comes to picture when there are no more free control intervals to perform a control interval split.  The control area is a fixed-length unit of contiguous DASD storage containing a number of control intervals. The control area is VSAM’s internal unit for allocating space within a cluster. That is, the primary and the secondary allocations consist of some number of control areas. If you don’t specify the CISZ, VSAM computes it for you. It ranges from one track to one cylinder. For instance, If you allocate storage in units of cylinders, a control area becomes a cylinder. Control areas are used internally by VSAM for storing the control intervals. When you first load a dataset, VSAM stores the Control intervals sequentially into the control areas, and the control areas filled sequentially.
The concept of FREESPACE applies to the KSDS and variable-length RRDS only. The free space when mentioned while defining a cluster, allocates some percentage of both the control interval and the control area for planned free space. This free space can be used for adding new records or for expanding existing variable records.

VSAM Status Keys

Status keys indicate, by code, the status of any execution request on a file. They are only effective when the FILE STATUS clause has been included in the FILE-CONTROL entry of the ENVIRONMENT Division in COBOL. When the FILE STATUS clause is specified, the value of the status key is placed in the appropriate data item. This data item can then be displayed and evaluated.

Status keys are composed of two characters:
Status key 1 and status key 2. Information on what each status key indicates is as follows:                 

  | VSAM Status Key  | Definition                                           |  
  |       00         | Successful completion; no further information.       |  
  |       02         | Successful completion; duplicate keys exists but the |  
  |                  | WITH DUPLICATES option is specified.                 |  
  |       04         | Successful completion of READ statement; however,    |  
  |                  | processed record length does not agree with the fixed|  
  |                  | file attributes for said file.                       |  

  |       05         | Successful completion of OPEN statement; however, the|  
  |                  | optional file is absent at the time of execution. The|  
  |                  | file is created if the open mode is extend or I-O.   |  
  |       07         | Successful completion; however, a reel/unit is       |  
  |                  | required for: NO REWIND, REEL/UNIT, FOR REMOVAL      |  
  |                  | phrase, or the OPEN statement with the NO REWIND     |
  |                  | phrase.                                              |
  |       10         | At End; next logical record or file unavailable;     |  
  |                  | no further information.                              |  
  |       14         | At End; the record number's digits are greater than  |  
  |                  | the relative key data size item for the file.        |  
  |       21         | Invalid key condition; sequence error occurred.      |  
  |       22         | Invalid key condition; duplicate keys exist and are  |  
  |                  | not allowed for this file.                           |  
  |       23         | Invalid key condition; no record found, or file not  |  
  |                  | available.                                           |  
  |       24         | Invalid key condition; out of space (only occurs for |  
  |                  | VSAM relative and indexed files).                    |  
  |       30         | Permanent error; probably a data check, parity check,|  
  |                  | or transmission error; no further information.       |  
  |       34         | Permanent error; out of space (sequential files only)|  
  |       35         | Permanent error; a required file was absent when an  |  
  |                  | OPEN with the INPUT, I-O or extend phrase was used.  |  
  |       37         | Permanent error; a file was used that could not      |  
  |                  | support the open mode specified in the OPEN statement|  
  |       38         | Permanent error; an OPEN was issued on a file closed |  
  |                  | with lock.                                           |  
  |       39         | Permanent error; conflict between the fixed file     |  
  |                  | attributes and the ones used for that program's file.|  
  |       41         | Logic error; OPEN was used with an opened file.      |  
  |       42         | Logic error; CLOSE was used on a CLOSE file.         |  
  |       43         | Logic error; a DELETE or REWRITE was tried without   |  
  |                  | the last input-output statement being a successful   |  
  |                  | read.                                                |  
  |       44         | Logic error; a rewrite was attempted on a record that|  
  |                  | was not the same size as record being replaced.      |  
  |       46         | Logic error; A sequential READ statement failed with |  
  |                  | a file in the input or I-O mode because the previous |  
  |                  | READ statement failed, or caused an at end condition.|  
  |       47         | Logic error; an attempt to execute a READ statement  |  
  |                  | on a file not open in the input or I-O mode failed.  |  

  |       48         | Logic error; an attempt to execute a WRITE statement |  
  |                  | on a file not open in the output, I-O , or extend    |  
  |                  | mode.                                                |  
  |       49         | Logic error; an attempt to execute a DELETE or WRITE |   
  |                  | statement on a file not open in the I-O mode failed. |  
  |       90         | Other error; no further information.                 |  
  |       91         | Other error; password failure. (VSAM ONLY.)          |  
  ¦       92         | Other error; error in logic.                         |  
  |       93         | Other error; resource not available. (VSAM ONLY.)    |  
  |       94         | Other error; no current record pointer for sequential|  
  |                  | file request. (CMPR2 option with VSAM ONLY.)         |  
  |       95         | Other error; invalid or incomplete file information. |  
  |                  | (VSAM ONLY.)                                         |  
  |       96         | Other error; no DD statement exists for the file.    |  
  |                  | (VSAM ONLY.)                                         |  
  |       97         | Other error; OPEN statement successful and file      |  
  |                  | integrity verified. (VSAM ONLY.)                     |  


Computers TopOfBlogs Technology Blogs Mainframe interview question and answers,mainframe jobs,cobol,vsam,jcl,cics,db2,rdbms,mvs,tso,ispf,ibm,hcl,tcs,cts,wibro Blog Directory