VSAM File Handling in CICS

In CICS, VSAM file operations are peformed using READ, WRITE, REWRITE, DELETE, UNLOCK, STARTBR, ENDBR, READPREV and READNEXT commands. These commands are explained in detail below.

The READ Command

READ
 DATASET (file name)
INTO (data area)
RIDFLD (record key area)
[UPDATE]
[EQUAL / GTEQ]
[LENGTH (record length area)]
[GENERIC]
[KEYLENGTH (data value)]
[SYSID (system name)]

The DATASET, INTO and RIDFLD options are required in every READ command. DATASET gives the name, in quotes, of the file that you wish to read. INTO names the data area within your program into which the record should be copied from the file. RIDFLD stands for Record IDentification FieLD. This option names the data area that contains the key value of the record you wish to read from the file.
The UPDATE option is used to establish exclusive control over a record. This is necessary to prepare CICS to update or delete a record later in your program.
EQUAL and GTEQ refer to the collating sequence in which record keys occur in the file. By default, the READ command will only read a record whose key is equal to the key specified in RIDFLD. If GTEQ is specified, the first record whose key is greater than or equal to the RIDFLD is read.
The LENGTH option is mandatory for reading variable length records. It specifies a data area that contains the maximum length input record that the program is expecting. When Cics executes the READ it stores the actual length of the record it reads into the data area specified in the LENGTH option. If this length exceeds the maximum length that the program had specified, the LENGERR exception condition is raised.
GENERIC tells CICS that the RIDFLD specifies only a partial key. KEYLENGTH, which is mandatory with the GENERIC option, tells CICS how many bytes of the RIDFLD key should be used to retrieve the record. The data value associated with the KEYLENGTH option may be a constant number, or it may be a variable data area defined in working storage.
The SYSID option is needed only if your installation uses the Intersystem Communication (ISC) facility to communicate with other systems. The four character system ID that you specify tells Cics on which system the file to be read is located. Whenever you specify the SYSID option, the LENGTH and KEYLENGTH options must be specified.

The WRITE command

WRITE
 DATASET (file name)
FROM (data area)
RIDFLD (record key area)
[LENGTH (data value)]
[KEYLENGTH (data value)]
[SYSID (system name)]

With the exception of FROM and LENGTH, all of these options are coded in the same way that they are coded for the READ command.
The FROM option indicates the name of the data area in working storage from which the record will be written.
The LENGTH option specifies the exact length of the record to be written. There is no need for CICS to return a length value to the program after the record has been written. Therefore, in the WRITE command, the LENGTH option can be specified by a constant number instead of by the name of the data area, as in the READ command. As with the READ command, the LENGTH option is required for variable length records.

The REWRITE Command

REWRITE
 DATASET (file name)
FROM (data area)
[LENGTH (data value)]
[SYSID (system name)]

After a record has been READ from a file with the UPDATE option, and the program has updated fields within the record, the REWRITE command can be issued to rewrite the record to the file and complete the update option.
Notice that the options that affect the WRITE command also affect the REWRITE command with the exception of the RIDFLD and KEYLENGTH options. These options are unnecessary because, if used at all they must be specified in the READ UPDATE command which must precede a REWRITE.
 
The DELETE Command

DELETE
 DATASET (file name)
[RIDFLD (record key area)]
[LEYLENGTH (data value)
[SYSID (system name)]

The DELETE command can be used in two ways to delete records. One way is to issue a DELETE command using the DATASET and RIDFLD options.
The other, safer, method is to issue a READ UPDATE command prior to deleting the record. The program can the inspect fields within the record to help determine whether the record should be deleted. If a record is deleted after being retrieved with a READ UPDATE command, the DELETE command may be issued without the RIDFLD option. RIDFLD is unnecessary in this instance because it was already specified on the READ UPDATE command.
The KEY LENGTH and SYSID options need to be issued only when the record to be deleted resides in a file on another system.

The UNLOCK Command

UNLOCK
 DATASET (file name)
[SYSID (system name)]

When a record is read with the UPDATE option, exclusive control for that record remains in effect until the record is either rewritten or deleted or until the transaction is terminated.
If once the record has been read, it is determined that an update is not necessary, exclusive control should be released from the record so that it can be accessed by other transactions.
The UNLOCK command releases the program's exclusive control over a record.
 
Writing a Browse Program
A browse transaction reads and displays multiple records from a file in a single transaction. Browse programs are usually coded to allow the user to continue browsing the file by pressing enter.
All browse programs contain the following Cics commands:
* STARTBR - Initiates the browse by establishing the key of the first record to be read.
* READNEXT - Reads the first and all subsequent records in a browse
* ENDBR - Terminates the Browse.

The STARTBR Command

STARTBR
 DATASET (file name)
RIDFLD (data area)
[GTEQ / EQUAL]
[GENERIC]
[KEYLENGTH (data value)]
[SYSID (system name)]

Most of these options are the same as for the READ command, except that STARTBR does not have INTO or LENGTH options. These options are unnecessary because STARTBR does not actually read a record into the program. It merely sets up a starting record key from which the READNEXT command works. Also note that, unlike the READ command, STARTBR takes GTEQ as a default option.
When a STARTBR command is issued with the GENERIC option the transaction is known as a generic browse.

The READNEXT command

READNEXT
 DATASET (file name)
INTO (data area)
RIDFLD (data area)
[LENGTH (data area)]
[KEYLENGTH (data value)]
[SYSID (system name)]

The READNEXT command reads just one record each time it is executed, therefore a browse program must include a loop that issues the READNEXT command multiple times. The loop should terminate after enough records have been read to fill up the screen, or until some earlier end point (such as end of file) has been reached.
The READNEXT command looks a lot like the READ command. Unlike STARTBR it does include the INTO and LENGTH options, records are actually being read into the program. Unlike READ, READNEXT does not have the GTEQ and GENERIC options, because these options establish the starting browse key, which is taken care of by STARTBR. The KEYLENGTH and SYSID options are required if the file to be read resides on another system.
 
The ENDBR Command

ENDBR
 DATASET (file name)
[SYSID (system name)]

The ENDBR command has two options, DATASET and SYSID. They perform the same functions in ENDBR as they do in all the other file handling commands.
Using the COMMAREA
After issuing the ENDBR command, you must issue a RETURN command to return control of the program to CICS. Use the COMMAREA option of the RETURN command in case the user wishes to continue the browse. It is common practice to store the last record key returned by the READNEXT command into a COMMAREA field. When the user resumes execution of the program, the key stored in DFHCOMMAREA may be moved to the data area referenced by the RIDFLD option of the STARTBR command.
 
The READPREV Command

A browse that reads a file in descending key sequence is called a reverse browse. A reverse browse program is coded using the READPREV command instead of the READNEXT command. The options of the READPREV command are identical to those of the READNEXT command. A reverse browse program is coded just like a normal browse, except that, after an initial mandatory READNEXT command is issued, the program loop executed the READPREV command instead of the READNEXT command.
The RESETBR Command
The RESETBR combines the effects of an ENDBR and a STARTBR. It's options are identical to those of the STARTBR. The RESETBR command can be used for a skip-sequential browse. During this type of application, the starting key of the browse is reset one or more times during the same transaction.

 Exceptional Conditions
Like any CICS commands, a file handling command may raise an exceptional condition when executed. Your programs should include either a HANDLE CONDITION or RESP options and some corresponding routines to handle the more common conditions that may occur.