# VSAM Functions

Shadow REXXTOOLS provides a collection of REXX functions for working with VSAM data sets. The functions are closely modeled after the macro interface to VSAM. If you are already familiar with programming for VSAM in assembler, you will have no trouble using the Shadow REXXTOOLS VSAM functions. If you have never used the VSAM macros, you will want to read the sections that follow before you start programming.

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

VSAM, which stands for Virtual Storage Access Method, provides facilities for defining, managing, and accessing 5 different types of data sets. These are:

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

The basic flow of a program that processes VSAM files is essentially the same as the flow of a program that processes sequential files. In general, such a program will contain the following steps:

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.

## Allocating VSAM Files

VSAM file allocation works just like sequential file allocation. The JCL Data Definition (DD) statement may be used, or if dynamic allocation is required, the REXXTOOLS ALLOCATE and FREE commands can be used.

## Opening and Closing VSAM Files

To associate your program with the VSAM data set you want to process, you use the OPEN function. The CLOSE function performs the opposite action by disassociating your program with the VSAM data set. Using the OPEN function you can connect your program to an unlimited number of VSAM data sets.

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

### OPEN (ACB) Options

When opening a VSAM data set, you may specify several types of options which control how a data set can be processed. For example, you can determine whether the data set will be processed in a "read only" mode, and whether it will be processed by record or by control interval. The options argument of the OPEN function is where you code the data set options.

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)

Option | Description
--- | ---
ADR | Specifies that you want to use Relative Byte Addresses (RBAs) to access a data set. Note that addressed access is not permitted for RRDSs.
CNV | Specifies that you want to access the data set by control interval rather than by records. Note that CNV access also implies addressed (ADR) access (i.e., RBAs are used).
KEY | Specifies that you want to use keys (for KSDSs) or Relative Record Numbers (RRNs - for RRDSs) to access a data set. Keyed access is not permitted for ESDSs.

#### Group 2: Type of Access (additive)

Option | Description
--- | ---
DIR | Specifies that direct access will be used in processing this data set. That is, individual records will be randomly requested.
SEQ | Specifies that sequential access will be used in processing this data set. That is, contiguous records will be requested in either ascending or descending sequence.
SKP | Specifies that skip sequential access will be used in processing this data set. Records will be processed in sequence but some records may be skipped.

#### Group 3: Direction of Access (additive)

Option | Description
--- | ---
IN | Specifies that the data set is being opened for reading (GETting) records.
OUT | Specifies that the data set is being opened for writing (PUTting) records.

#### Group 4: Write Deferment (alternative)

Option | Description
--- | ---
DFR | Specifies that buffers are not to be immediately written following direct PUT requests.
NDF | Specifies that buffers are immediately to be written following direct PUT requests.

#### Group 5: Insertion Strategy (alternative)

Option | Description
--- | ---
NIS | Specifies that the normal insertion strategy is to be used. Control intervals are split at the midpoint.
SIS | Specifies that the sequential insertion strategy is to be used. Control intervals are split at the insertion point. This method is faster if several contiguously located records are being inserted.

#### Group 6: Object of Access (alternative)

Option | Description
--- | ---
NRM | Specifies that the ddname gives the object to be processed.
AIX | Specifies that the alternate index of the object specified by the ddname is to be processed. You do not use this option to process the base cluster with an alternate index. This option lets you read the records of the alternate index itself (something you will not usually want to do).

#### Group 7: Reusability of Data set (alternative)

Option | Description
--- | ---
NRS | Specifies that the data set is not reusable. That is, you cannot open it for reuse and overwrite the existing data with load mode processing.
RST | Specifies that the data set is reusable. Upon opening a data set with this option, it is as if all the existing data in the file is erased.

#### Group 8: VSAM buffer sharing (alternative)

Option | Description
--- | ---
DDN | Specifies that VSAM is to share control blocks and buffers by ddname. This option only applies to sibling tasks in the same address space, and is only available when the subtasks share subpool zero.
DSN | Specifies that VSAM is to share control block and buffers by data set name. This option only applies to sibling tasks in the same address space, and is only available when the subtasks share subpool zero.

#### 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'

## Reading, Writing, and Updating Records

The Shadow REXXTOOLS functions which permit record and control interval level access to VSAM data sets are:

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.

### Request Parameter List (RPL) Options

Request Parameter List (RPL) options are used in the options arguments of the GET, PUT, and POINT functions. The RPL is a REXXTOOLS-managed data structure that is shared for all requests to the same ddname (Thus, by implication, different ddnames have different RPLs). For example, if you specify the options '(KEY,SEQ,UPD)' on the first GET, PUT, or POINT for a ddname, subsequent invocations of the GET, PUT, or POINT functions for the same ddname -- if they do not change these options -- will also use '(KEY,SEQ,UPD)'.

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)

Option | Description
--- | ---
ADR | Specifies that you want to use Relative Byte Addresses (RBAs) to access a record. Note that addressed access is not permitted for RRDSs.
CNV | Specifies that you want to process a control interval rather than a record. Note that CNV access also implies addressed (ADR) access (i.e., RBAs are used).
KEY | Specifies that you want to use keys (for KSDSs) or Relative Record Numbers (RRNs - for RRDSs) to process a record. Keyed access is not permitted for ESDSs.

#### Group 2: Type of Access (alternative)

Option | Description
--- | ---
DIR | Specifies that you want to process a record directly. (i.e., you want to specify a key, RBA, or RRN to process a record).
SEQ | Specifies that you want to process the next record in the data set (either forward or backward).
SKP | Specifies that you want to process a record by key but that the key of the record will be higher than that of the previous record processed.

#### Group 3: Use of Keyin (alternative)

Option | Description
--- | ---
ARD | Specifies that the keyin argument is to be used (if a form of direct access processing has been requested) to find the record to be located, retrieved, or stored.
LRD | Specifies that the last record in the data set is to be processed. The BWD (backward processing option) must also be specified.

#### Group 4: Read/Write Direction (alternative)

Option | Description
--- | ---
FWD | Specifies that if the file is being processed sequentially, processing will proceed from the first record to the last (i.e., forward).
BWD | Specifies that if the file is being processed sequentially, processing will proceed from the last record to the first (i.e., backward).

#### Group 5: Positioning and Control (alternative)

Option | Description
--- | ---
NSP | Specifies that for direct processing requests VSAM is to remember the position of the record being processed. The position will not be "forgotten" by VSAM until a sequential request or an ENDREQ function call is performed.
NUP | Specifies that the record being processed will not be updated, or deleted and that positioning is not to be remembered.
UPD | Specifies that the record being processed is to be updated or deleted (ERASEd). For a GET, VSAM will remember its position and (for certain share options) obtain exclusive control of the control interval containing the record. When a subsequent ERASE, PUT, or ENDREQ function is executed, positioning and control are relinquished.

#### Group 6: Keyin Test Options (alternative)

Option | Description
--- | ---
KEQ | Specifies for keyed, direct searches that the key you provide in the keyin argument must match, exactly, the key of a record in the data set or else the search fails.
KGE | Specifies for keyed, direct searches that the key you provide in the keyin argument must be greater than or equal to the key of a record in the data set.

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

#### Group 7: Generic Search Options (alternative)

Option | Description
--- | ---
FKS | Specifies that the key supplied in the keyin argument is to be treated as a full length key.
GEN | Specifies that the key supplied in the keyin argument is to be treated as a generic key (i.e., only the leading characters of a key are specified). Generic keys potentially will match more than one record.

#### Group 8: Variable Control Options (alternative)

Option | Description
--- | ---
VAR | Specifies that $RXT variables are to be created.
NOV | Specifies that $RXT variables are not to be created. This option can improve performance.

### Sequential Processing

Using the SEQ option, you can process all VSAM data set types sequentially (i.e., one record after another). Sequential access can be used in conjunction with either the KEY (for keyed access) or ADR (for addressed access) options. Note, however, that ESDSs may be processed using addressed access only. You cannot specify '(KEY,SEQ)' options for processing an ESDS.

#### 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

Records in VSAM files can also be accessed directly. That is, you can extract one record for processing without having to read past the records that precede it. To specify direct processing use the DIR RPL option.

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 */

## Sharing VSAM Data sets

VSAM data sets can be shared among many users. More importantly, VSAM data sets can be shared by many users all at the same time. In order to understand how VSAM file sharing is implemented, you need to understand how VSAM performs I/O and what sharing facilities are available.

### How VSAM I/O Works

First, let's examine how VSAM reads and writes records. It doesn't. While your programs appear to read or write only one record at a time, VSAM actually reads and writes, at a minimum, a control interval with each I/O operation. When reading, the records of the control interval are placed into a buffer that is unique for each user of the file. After the control interval has been loaded into the buffer, VSAM selects the desired record and presents it to the user. Subsequent GETs or PUTs, if they are for the same record or for other records already in the buffer, are satisfied with the copy in storage and not the copy on DASD.

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

Serialization is the technique which allows asynchronous processes to share, one-at-a-time, any resource. When used in the context of data set access, serialization is often called "locking". The basic idea is that each accessor must first obtain a lock on a data set (or some part thereof) prior to using it. When the access is completed, the current accessor must release the lock to allow others to access the data. Perceived concurrency, or the extent to which a resource appears to be simultaneously shared by many users, is a function of the lock's scope and duration.

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

Disposition is determined when the data set is allocated. If you are using JCL to allocate the data set, the DISP parameter is used. If you are allocating the data set using the REXXTOOLS ALLOCATE command, disposition is controlled by the status keywords (OLD, SHR, NEW, and MOD). SHR disposition allows many users to read a data set at the same time. User's who want to update the data set must use OLD to ensure read/write integrity.

#### VSAM Share Options

Share options determine how VSAM will handle multi-user access to a data set, and are determined by the SHAREOPTIONS keyword of the DEFINE CLUSTER command. Share options take effect only if the data set is allocated with DISP=SHR. In addition, share options do not apply when a VSAM file is opened and loaded for the first time.

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

For files shared between tasks running asynchronously in the same address space, VSAM provides serialization support based on shared buffers. This support is completely independent of cross-region SHAREOPTIONS, and is controlled, instead, by the DDN and DSN options of the OPEN function. If DDN (the default) is specified, VSAM will share buffers for files that are opened with the same ddname. If DSN is specified, VSAM will share buffers based on data set name.

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

The MVS ENQ/DEQ service (which can be accessed via the REXXTOOLS ENQ and DEQ functions) can be used to provide a protocol for serializing accesses to a VSAM file. In combination with cross-region SHAREOPTIONS 2, 3, or 4, ENQ/DEQ can be used to provide a high degree of perceived concurrency, while maintaining read/write integrity. Note, though, that such a protocol must be strictly adhered to by all accessors. There is no mechanism in the MVS ENQ/DEQ service to prevent "cheaters" from accessing a data set without first obtaining the appropriate locks.

### Serialization Precedence

The various serialization methods have an order of precedence. Allocation disposition takes precedence over all other methods. This is followed by SHAREOPTIONS serialization, which is followed by ENQ/DEQ serialization.

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

Because of the flexibility of ENQ/DEQ serialization, locks can be constructed for any part of a data set. You could, for example, use a record's key as the resource to be locked. Yet, because VSAM reads and writes several records at a time, the minimum unit for serialization usually must encompass a complete control interval. In this case, the relative byte address (RBA) of the control interval is used for the lock.

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

The "dirty read" technique can be used to provide a high degree of concurrent access to VSAM files while avoiding the complications associated with CI and CA splits. The dirty read protocol can be summarized as follows:

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.

## VSAM Return Codes

Upon completion, all Shadow REXXTOOLS VSAM functions provide a return code and a reason code. The return code is placed in the standard RC variable, while the reason code is placed in a special variable named REASON.

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

Unless otherwise noted, the values for RC and REASON are taken directly from the underlying VSAM macro return and reason codes. In all cases, a return code of zero indicates success.

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.

## Service Descriptions

The sections that follow describe the syntax and operation of the VSAM-related functions.

CLOSE

ENDREQ

ERASE

GET

OPEN

POINT

PUT

VERIFYV

© Copyright 1998 by Open Software Technologies, Inc.