VSAM Functions

VSAM Basics	Programming for VSAM
Allocating VSAM Files	Opening and Closing VSAM Files
Reading, Writing, and Updating VSAM Files	Sharing VSAM Data Sets
VSAM Return Codes	Service Descriptions

Additional background information on VSAM can be found in the Using Data Sets publication for your system's level of DFP or DFSMS. Using Data Sets contains descriptions of VSAM data sets and VSAM utilities, and VSAM programming guidance.

VSAM Basics

KSDS

Key-sequenced data sets. The records of this type of data set are maintained in key-sequence order. The records of the KSDS may be of variable length, but the key field is always in the same location and is always the same length.

KSDSs are made up of two components. The first is the data component; it contains the actual data records of the data set. The second component is the index. The index contains compressed key values and pointers into the data component, and permits high-speed random access of records. There may be only one index entry per data record (i.e., duplicate keys are not allowed). In addition to the primary index, alternate indexes may be defined for and associated with the data component. These alternate indexes permit random access to the data component using fields other than the primary key field. Alternate indexes, by default, permit duplicate keys.

KSDS records may be accessed both sequentially and directly (randomly). Records may be inserted, both in between existing records and onto the end. Records may also be deleted (erased) from the data set.

ESDS

Entry-sequenced data sets. The records of the ESDS are maintained in the order they are entered. As new records are added, they are always placed at the end of the data set. They are never inserted into the middle. Moreover, once a record has been added to an ESDS, it can never be deleted6. Like the KSDS, the ESDS permits variable length records. But, the ESDS will not permit a record to grow or shrink once it has been added. A replacement record must fit exactly over the old record's space.

An ESDS may be accessed both sequentially and randomly. For random access, a number called the Relative Byte Address (RBA) is used to specify the record to retrieve. The RBA of a record can be obtained at the time it is inserted, or can be determined by sequentially reading the data set.

RRDS

Relative record data set. The RRDS holds data that is accessed by the number of the record. The RRDS supports only fixed length records. Records can be inserted into the middle, or added onto the end of an RRDS. Records can also be deleted.

The RRDS permits both sequential and random access. Random access is by Relative Record Number (RRN), which is the sequence number of a record.

VRDS

Variable-length relative record data set. The VRDS, like the RRDS, holds data that is accessed by the number of the record. In addition, the VRDS also supports variable length records. Records can be inserted into the middle, or added onto the end of a VRDS. Records may also be deleted.

The VRDS permits both sequential and random access. Random access is by Relative Record Number (RRN).

LDS

Linear data set. This type of VSAM data set is used for the MVS Data-In-Virtual (DIV) service. It is also used by DB2 to contain table-related data. Linear data sets do not contain records in the same sense that KSDS, ESDS, and RRDS data sets do. Because of this, the record- oriented services of VSAM cannot read from or write to linear data sets. REXXTOOLS can, however, access linear data sets by control interval (refer to the definition of control interval that follows).

VSAM data sets are organized first by records, then by control intervals (CIs) which are collections of records; and then by control areas, which are collections of control intervals. Using the processing options described in the sections that follow, you can directly read from and write to VSAM data sets at the record and control interval levels. You cannot read or write control areas.

Programming For VSAM

1. Allocate the file. A Data Definition Name (DDNAME) is associated with the data set you wish to process.
2. Open the file for processing using the OPEN function. The access method makes a logical connection between your program and the data set to be accessed. Depending on the options you specify, your program can read, write, or update records. You can also select direct or sequential processing.
3. Read a record from the file using the GET function, or write a record to the file using the PUT function. If reading, the access method places the record's contents into a variable or variables for the program to use. Using VSAM, an individual record can be accessed directly without having to read through the records that precede it.

   If you are writing records, the access method takes the record from an argument to PUT.

4. Determine what processing applies to the record (if any) and perform the processing. The program can replace the record's data with new information or request that the access method remove the record from the data set. New records also may be added to the data set. For information regarding the processing of record fields, please see "Working with Record Fields"
5. If appropriate, return to step 3 to process other records.
6. Close the file using the CLOSE function. The logical connection between the program and the data set is terminated.
7. Free the file. The DDNAME is disassociated with the data set.

Shadow REXXTOOLS maintains information about open VSAM files in a data structure associated with the task under which the OPEN function was executed. The information is maintained by ddname. Files remain registered with REXXTOOLS and open until they are explicitly closed, or until the task that opened them terminates.

All REXX programs under a MVS task share the same REXXTOOLS VSAM data structures. Thus if program A calls program B (REXX CALL or function call), any ddname that is opened by either program A or program B is known to the other. File sharing also extends to directly subtasked REXX programs. As a consequence, if Program A attaches program B, the files opened by program A are known by program B. However, files opened by program B will not be known to A when control is returned. This is because task termination will close all files opened by program B.

Notes:

1. In address spaces where subtasks in a vertical chain (e.g., A attaches B; B attaches C; etc.) are run asynchronously (i.e., the attaching task does not wait on the subtask), it is the responsibility of the REXX programmer to ensure that requests to the same ddname are serialized. The REXXTOOLS ENQ and DEQ functions may be used for this purpose. For example, if A opens a file and attaches subtask B asynchronously, A and B can share the file, but they must explicitly serialize their requests. Between sibling subtasks there is more programming assistance. That is, if A attaches B and C asynchronously, and if B and C each open the same ddname separately, VSAM will provide implicit serialization (There are restrictions on sibling subtask sharing. See "Sharing VSAM Data sets" for more information).

The OPEN options are organized into groups. Some of the groups are additive. That is, you may select one, some, or all of the options in that group. Other groups are alternative. From these groups you may select just one option. All of the groups contain one option that is the default value. If you do not select an option from a group, VSAM will use the default value (the default values are underscored).

Group 1: Type of Key (additive)

Group 2: Type of Access (additive)

Group 3: Direction of Access (additive)

Group 4: Write Deferment (alternative)

Group 5: Insertion Strategy (alternative)

Group 6: Object of Access (alternative)

Group 7: Reusability of Data set (alternative)

Examples

1. Open a new and empty KSDS for loading:

   call open 'vsam', 'outdd', '(key,seq,out)'
   

2. Open an RRDS for random access (both input and output):

   call open 'vsam', 'iodd', '(key,dir,in,out)'
   

3. Close a VSAM data set of any type after any type of processing:

   call close 'vsam', 'mydd'
   

GET

The GET function is used to retrieve records or control intervals.

PUT

The PUT function is used to write records or control intervals. If the PUT follows a GET with the UPD (update) option, the record that was retrieved by the GET will be replaced. In all other cases, PUT is interpreted as a request to insert new records into the data set.

POINT

The POINT function is used to position VSAM on a record in a VSAM file. For example, you can position VSAM on the last record in a file when you plan to read the file with the BWD (backward) option.

ERASE

The ERASE function is used to remove records from a KSDS or RRDS. Before you can ERASE a record you must GET it. VSAM does not permit ERASE to be used on ESDS data sets.

The groups of RPL options are given in the tables below. All of the RPL options are alternative options. From alternative option tables you may select only one option. If you do not select an option from a table, VSAM will use a default value (the default values are underscored).

Notes:

1. The options argument, like other arguments, is processed and communicated to VSAM before the actual VSAM macros which execute the request are issued.
2. Some of the RPL options are identical to the OPEN function's options. However, for the most part, the OPEN options merely describe the types of processing that might take place, whereas the RPL options are specific requests for services. So, for example, even though you may have specified ADR processing in the OPEN, you must also specify ADR processing when you perform a GET, a PUT, or a POINT.

Group 1: Type of Key (alternative)

Group 2: Type of Access (alternative)

Group 3: Use of Keyin (alternative)

Group 4: Read/Write Direction (alternative)

Group 5: Positioning and Control (alternative)

Group 6: Keyin Test Options (alternative)

Note: The Keyin Test Options apply to both full and generic keys.

Group 7: Generic Search Options (alternative)

Group 8: Variable Control Options (alternative)

Sequential Processing

Examples

1. Sequentially load a KSDS. This example assumes that a REXX pseudo-array named REC. contains the records to load (in key sequence):

   /* Allocate and open the outdd file */
   do i = 1 to 20
     call put 'outdd', rec.i,,'(key,seq)'
   end
   /* Close and free the outdd file */
   

2. Sequentially read a KSDS:

   /* Allocate and open the indd file */
   recin = get( 'indd',,'(key,seq)')
   do while rc = 0
     parse var recin 'Address:' aline 'Date:' date,
           145 custinfo
     recin = get( 'indd',,'(key,seq)')
   end
   /* Close and free the indd file */
   

3. Sequentially read an ESDS:

   /* Allocate and open the indd file */
   GetCustRec = "parse value get( 'indd',,'(adr,seq)')",
                    "with fname +10 lname +15 ssn +9 ."
    
   interpret GetCustRec
   do while rc = 0
     say 'Name:' lname','fname 'SSN:' ssn
     interpret GetCustRec
   end
   /* Close and free the indd file */
   

Direct Processing

KSDSs offer the most flexibility with respect to direct access. A KSDS may be accessed using either keyed (KEY) or addressed (ADR) access. If keyed access is used, the keyin argument for the function must contain a partial or complete key.8 If addressed access is used, the argument must be a relative byte address (RBA).

ESDSs may be accessed directly using the ADR (addressed) option. For a direct request against an ESDS you must supply an RBA for the keyin argument.

A direct access request against an RRDS must use a relative record number (RRN) for the keyin argument. You may not use addressed access for a relative record data set even though it is possible to obtain the RBAs for an RRDS's records.

Note: The Batch Local Shared Resources (BLSR) subsystem can be used to improve the performance of long running, direct processing jobs. The Shadow REXXTOOLS VSAM interface supports the use of BLSR. For more information on this facility, refer to Application Development Guide: Batch Local Shared Resource Subsystem, GC28-1672 . Do not use BLSR with programs that process data sequentially since this will lead to increased run times.

Examples

1. Directly add a new record to a KSDS. The new record's key is 'ABC001':

   /* Allocate and open the outdd file */
   call put 'outdd', 'ABC001 new data',,'(key,dir)'
   /* Close and free the outdd file */
   

2. Directly read the first record from an ESDS. The first record always has an RBA of zero:

   /* Allocate and open the indd file */
   call get 'indd', 0, '(adr,dir)'
   /* Close and free the indd file */
   

3. Directly retrieve then delete a record from a KSDS:

   /* Allocate and open the iodd file */
   call get 'iodd', 'ABC001', '(key,dir)'
   if rc = 0 then
     call erase 'iodd'
   /* Close and free the iodd file */
   

How VSAM I/O Works

Depending on the file sharing method (which is discussed below), other users in other address spaces may also read and write the same records. The other users will have their own private buffers. Thus, if there are two users reading the first control interval of a KSDS, there are really 3 copies of the data in the system: the DASD copy, the first user's copy, and the second user's copy.

Because of VSAM buffering, two exposures to data corruption must be considered:

Read Integrity

is compromised if one user is allowed to write to a control interval while another user has a copy in memory. When this happens the second user's memory copy is said to be "down level".

Write Integrity

is compromised if two users update the same control interval at the same time. The last user to write the control interval is the one whose changes take effect.

At first glance, this might not appear to be a problem. Even the most scrupulous of protocols must permit serial access to a record. However, when you consider the case where one user updates the first record of a control interval while another user updates the fourth, you begin see where the difficulty lies. The last user to write to the file will completely nullify the first user's changes.

VSAM Serialization Methods

The scope of a lock is the amount of data that is reserved. The status portion of the disposition parameter in JCL has a data set-wide scope, for example. Using DISP=OLD, an accessor has exclusive control of the whole data set. The duration of a lock is the amount of time a lock is held. Using the disposition parameter example again, DISP=OLD locks a data set for the amount of time it takes the job step to run. Because of these factors, the perceived concurrency for DISP=OLD serialization is very low. Other serialization methods permit greater perceived concurrency.

Note: Often the duration of lock is the most important factor in determining perceived concurrency. For example, if a data set-wide lock is held only briefly, perceived concurrency does not suffer.

In general, the number of users that can concurrently access a VSAM data set is a function of one or more of the following serialization mechanisms.

Data set disposition

VSAM Share Options

There are 4 levels of cross-region file sharing:

SHAREOPTION 1

One user may write to the file or many users may read the file. Using this option, VSAM ensures complete read and write integrity. However, because the writer's lock endures while the file is open, the perceived concurrency for other writers is usually about as low as DISP=OLD serialization.

SHAREOPTION 2

One user may write to the file and many users may read the file. VSAM ensures write integrity but read integrity is the responsibility of the user.

SHAREOPTION 3

Many users may read and write to the file, and complete responsibility for read and write integrity is with the user. Failure to maintain read/write integrity can result not only in program abends, but corrupted data as well.

SHAREOPTION 4

Many users may read and write to the file. However VSAM does provide some support for concurrent use by ensuring that all direct requests (read and write) result in accesses to the DASD copy of the data. That is, a GET will cause the buffer to be refreshed from DASD, and a PUT will cause the buffer to be written to DASD. Sequential processing programs must use the ENDREQ function to ensure that buffers are refreshed. Again, failure to maintain read/write integrity can result in catastrophe.

Intra-Region Serialization

When buffers are shared in this manner, VSAM maintains complete read and write integrity. However, only subtasks that share subpool zero storage can use intra-region file sharing. This is because VSAM allocates data buffers in subpool zero and needs these buffers to remain allocated even though the first task to open the data set may have terminated (when subpool zero is not shared, MVS automatically frees subpool zero storage when a task terminates).

ENQ/DEQ Serialization

Serialization Precedence

Sophisticated applications requiring a high degree of concurrent use, almost always require the use of SHAREOPTIONS 3 or 4 and ENQ/DEQ serialization. Even so, you can always use disposition serialization whenever you want to ensure that just one user has the file (third shift batch update and reporting applications often fit this profile).

Serialization Problems

Another complication that must be considered arises from insertions into KSDSes. Whenever a control interval is full but a new record needs to be inserted into its middle, VSAM "splits" the control interval into two parts, each containing some free space. The new record can then be inserted. A negative consequence of this splitting action is that it makes impossible the use of any protocol based on control interval locks -- you can't lock on a moving target.

Finally, the problem of splitting can cascade to higher levels: if a control area is full, it too must be split before a new control interval can be inserted.

The "Dirty Read" Technique

1. The VSAM file must be defined with cross-region SHAREOPTIONS 4.
2. The file must be allocated with DISP=SHR.
3. All operations on the file, including reads, must be preceded with an ENQ for the data set. The data set name is specified for the ENQ "rname", but any string can be used for the ENQ "qname" (though it must be the same string for all accessors).
4. After a lock is obtained, the user's buffer must be refreshed with a GET request. This step also applies to new record insertions.
5. At the end of all file operations, the enqueue is released with a DEQ function call.
6. No lock is held during a wait (such as terminal input wait).
7. Before updating a previously read record, a fresh copy of the record must be obtained and compared to the original to ensure that no other user has updated the record while it was being browsed and modified. As always, the second read, the record comparison, and the update must be shielded by a lock.

In addition, except for the GET function which returns a record, all VSAM functions return the return code as their value. For example, the following code will display the return code two times, once as OPEN's returned value, and once as the value of the RC variable

say "RC="open('vsam','indd') "RC="rc "REASON="reason

Notes:

1. The complete list of VSAM return and reason codes can be found in the IBM publication Macro Instructions for Data Sets for your system's level of DFP or DFSMS.
2. The return and reason codes (including ABEND codes) produced by the VSAM functions are all decimal (not hexadecimal) values.

CLOSE

ENDREQ

ERASE

GET

OPEN

POINT

PUT

VERIFYV