Mainframes 360
The one stop destination for System Z professionals

Monday, March 22, 2010

Inserting Records in VSAM File

Q. Adding records to a file, sequentially or randomly, what’s the difference?
KSDS Files can be updated sequentially as well as Randomly. How does
Random addition of records to a file, score over sequential addition of records?

In Sequential Addition(ACCESS MODE IS SEQUENTIAL), new records get added to the tail-end of the KSDS File. A file contains 3 employees – 10,20,30. You add a new employee record 40, the file becomes 10,20,30,40. You want to add employee-id 35. Not possible as you’ve been working in Sequential mode.

Ever played a game of Playing Cards? There are Spades, Hearts, Diamonds, and Clubs. When you pick a queen of Diamonds, you first find the suit – in this case Diamonds, to which the card should be added, and then insert it into the right slot. Like putting cards into the right suit, in random access(ACCESS MODE IS RANDOM), new records can be inserted, interspersed into the file. Random mode finds right-slot for each record.
Q. What are the COBOL instructions for adding records to KSDS Files?
The Employee-records stored in a KSDS File, have the following record layout -


COBOL Program can add(insert) new logical records to a KSDS File.

(i) You MOVE the key of the record that you want to add, to the RECORD KEY field(employee-id) in the 01-level record-descriptor. For example, if you want to add the employee (45,’RAHUL’,35,4000,’23-12-2005’), you place the key 45 in the key-field EMP-ID

(ii) Next, fill in the rest of the fields in the record. So, put ‘RAHUL’ in EMP-NAME, 35 in EMP-AGE, 4000 goes into EMP-SALARY and ‘23-12-2005’ goes into EMP-JDATE.

(iii) The COBOL WRITE verb is used to add the record to the file.

In response to the  COBOL WRITE instruction, VSAM performs a full-index search - to find the target Control Interval(CI) where the record should go. Once the Control Interval(CI) is located, the record is placed in the free-space available, while re-arranging the other records as necessary. Recollect, that the records in a Control-Interval are always sorted in key-sequence.

The format of the COBOL WRITE statement is -

WRITE record-name
KEY IS name-of-key-field

The WRITE statement includes the record-name(Record to be added). The INVALID KEY clause serves as red-signal, an indicator that things went wrong while adding the record. Generally, the INVALID KEY condition occurs, when you try to WRITE a duplicate record into a file. Like you try to add an Employee 100, who’s already there in the file. VSAM won’t allow you to over-write it, and throws back an error. You can trap(catch) this exceptional condition, error by INVALID KEY. NOT INVALID KEY represents the condition, if the record is successfully added to the file. You would use NOT INVALID KEY condition for record-keeping(printing messages) in the logs, it’ll run only if the record is successfully inserted into the file.
Q. Could you show me a simple COBOL Program to add records to a VSAM File?
I have a KSDS File, containing a list of Employees. The contents of the KSDS File AGY0157.EMPLOYEE.KSDS are shown below -


I want to add the following records to the Employees KSDS File -

The flag-variables to detect end-of-file condition, and error-condition are shown below.


All I/O operations(OPEN,READ,WRITE,CLOSE) on the Employees KSDS File, leave behind a 2-digit Status Code(a trail), indicating the results of the Operation(Success/failed). FILE-STATUS-CODES variable stores the I/O Status Code.

VSAM-FILE-OPERATION-SUCCESS condition represents '00' status code - indicating I/O Operation is Successful. VSAM-FILE-OPERATION-FAILED condition represent non-zero I/O status code – indicating I/O Error.

For record-keeping purposes

The starting point of the Program with the PROCEDURE DIVISION. We shall break up the task of adding records to Employee KSDS File into 3 paragraphs – OPEN-FILE, PROCESS and CLOSE-FILE.


Line 69 opens the Employee KSDS File for adding records. The VSAM-FILE-OPERATION-SUCESS 88-level condition checks status of the OPEN operation. If the file was OPENed successfully, the VSAM-FILE-OPERATION-SUCCESS switch is turned on(TRUE).

Lines 70-71 transfer the control to C100-PROCESS and D100-CLOSE-FILE para, to process the files and close them.

If the OPEN operation fails, you DISPLAY a message 'ERROR OPENING VSAM FILE', and file-status-code is printed.

Let’s go to B100-OPEN-FILE paragraph.


I shall read records from the EMPLOYEE-TRANSACTION-FILE and add them randomly to the EMPLOYEE-KSDS-MASTER file. As I am reading the records from
EMPLOYEE-TRANSACTION-FILE, I open it for INPUT. For making changes, I OPEN the EMPLOYEE-KSDS-MASTER file for I-O.

Immediately following the B100-OPEN-FILE, the MAIN-PARA performs
C100-PROCESS. This paragraph is reads 1 record from the Input transactions file and writes it to the Output Employee KSDS File. If there are 5 transactions to be added, this C100-PROCESS must be repeated 5 times. In other words, we iterate through C100-PROCESS for all the transactions one-by-one, in a cyclic way, till we reach the end of the transactions.

The C100-PROCESS paragraph looks like this -


Lines 86-90 READ a record from the EMPLOYEE-TRANSACTION-FILE. The READ block contains an AT END indicator. This condition becomes true when the all transactions from Input Transaction file have been read. At this point, you turn the AT-END switch on, so that the cyclic process of
PERFORM’ing C100-PROCESS comes to a halt.

Every-time you read a record, you increment the counter WS-INPUT-REC-CNT by 1. This kinda keeps track of, how many records you read off the input-file. This is shown in Line 91. Having done this for logging purposes, Line 92 copies the Input-file’s record EMPLOYEE-TRANSACTION-RECORD to the output-file’s record area EMPLOYEE-KSDS-RECORD.

Lines 93-99 write the EMPLOYEE-KSDS-RECORD to the Ouput Employee KSDS File. The INVALID KEY condition represents a duplicate record found error. The NOT INVALID KEY condition is true, when the employee-record is successfully written to the Output Employee KSDS file. Line 97 increments the counter
WS-INSERT-RECS-CNT by 1. This counter on the other hand, keeps track of the no. of records inserted successfully. All the records should get inserted.

The D100-CLOSE-FILE closes the files, and releases them. We also print the counts of the records read WS-INPUT-RECS-CNT and the records inserted into the Employee KSDS File WS-INSERT-RECS-CNT to the log, for error-tracking or bug-fixing purposes.


To many people who are thrown to work at a mainframe computer on their first job, they feel lost. Mainframe people seem to speak a completely different language and that doesn't make life easy. What's more, the books and manuals are incredibly hard to comprehend.

"What on earth is a Mainframe?" is an absolute beginner's guide to mainframe computers. We'll introduce you to the hardware and peripherals. We'll talk about the operating system, the software installed on a mainframe. We'll also talk about the different people who work on a mainframe. In a nutshell, we'll de-mystify the mainframe.

Readers based in India, can buy the e-book for Rs. 50 only or the print book. International readers based in the US and other countries can click here to purchase the e-book.