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 -

Image170[1] 

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
INVALID KEY
   what-to-do-if-duplicate-field
NOT INVALID KEY
   what-to-do-if-insert-is-successful

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 -

Image164[1] 

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

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

Image173[1] 

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.

Image172[1] 

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.

Image174[1] 

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 -

Image176[1]

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.

Image177[1] 

Tuesday, March 16, 2010

Random Processing of VSAM Files

Q. What are the Environment Division considerations for random processing of KSDS File?
When you want to do random processing of the records in a KSDS File, the COBOL SELECT statement has the following syntax :

SELECT filename
   ASSIGN TO ddname
   ORGANIZATION IS INDEXED
   ACCESS MODE IS RANDOM
   RECORD KEY IS name-of-key-field-in-record
   FILE STATUS IS file-status-area

Image163[1] 

The Key field that is used to uniquely identify each employee is the Employee Identification no. – EMP-ID field.
Q. How Random retrieval of KSDS Files works? 
For the sake of example, let’s assume that we have a KSDS File containing Employee records. The contents of the KSDS file are -

Image164[1]

The record-layout for the Employees KSDS file is as shown below -

Image165[1]

For random retrieval of records, you just spell out the key-value(Employee identification no.) of the employee you wanna find, to VSAM and in a jiffy, VSAM fetches the Employee details for you. Now, let’s look at what happens in the background.

The key value(employee-id) of the Employee record, you want to fetch is first placed in the key-field area(EMP-ID). Let’s assume you want to retrieve the details – name, age, salary and joining date of the Employee No. 70.

VSAM compares the RECORD KEY value(Employee-id) specified in the program, to the entries in the root index set record. The first entry in the root index record >= RECORD KEY value, is used to point to the next lower level index set record. The entries in this index record is then compared to the RECORD KEY. Again the first entry >= RECORD KEY value is found, and points to a next lower level index set record.

This search process continues downward through the index levels, until an index entry points to a sequence set record. The first sequence set entry which is greater than or equal to the (RECORD KEY)Employee No. 70, points to the Control Interval(CI) in the KSDS Data file. This Control Interval(CI) must hold the record(if it is in the file). The CI is now retrieved and searched for the desired logical record.
Q. What are the PROCEDURE DIVISION statements for random retrieval of records in KSDS file.
You are going to write a COBOL Program to search the details of Employee No. 70 in the Employee KSDS File. The COBOL Program can be broken down into three paragraphs – open, fetch, close.

The 1000-MAIN-PARA performs 3 steps -

Image166[1]

Line 51 performs 2000-OPEN-FILE-PARA, which would open the KSDS File for reading the records.

Lines 52-55 are executed, only if the Open operation on the KSDS File is successful. If the Open operation fails, a message stating ERROR OPENING VSAM FILE is displayed, and the error code is printed to the log.

If the OPEN operation is successful, you go ahead and fetch the logical-record you want, and then close the files, once you are done.

The 2000-OPEN-FILE paragraph OPENs the EMPLOYEE-KSDS-FILE containing Employee records in INPUT mode. The INPUT mode is used to read the records from a file. It also OPENs the OUTPUT-FILE in OUTPUT mode. The OUTPUT-FILE points to the log(print output) of the job, and we shall print the details of the Employee we want, to the OUTPUT-FILE.

Image167[1]

The 3000-FETCH-RECORD paragraph will retrieve(search) the details of Employee-ID 70.

We begin by placing the key value(employee-id) of the employee, we would like to search in the RECORD KEY field – EMP-ID. Lines 68 places the value '070' in the Key-field EMP-ID

Image168[1]

On Line 69, the COBOL READ Statement, causes VSAM to perform a random search on the EMPLOYEE-KSDS-FILE for the record with EMP-ID 70. If the search returns positive results - Employee record with EMP-ID=70 is found, the
NOT INVALID KEY clause is executed, and a message ‘RECORD FOUND’ is printed to the log. If the search is a failure – there is no Employee record in the KSDS File with EMP-ID=70, the INVALID KEY clause is executed, and a message ‘RECORD NOT FOUND’ is printed to the log.

We then store the data present in the EMPLOYEE-KSDS-RECORD area into
OUTPUT-RECORD area. Line 77 write the OUTPUT-RECORD, details of the Employee no. 70 to the OUTPUT-FILE.

The 4000-CLOSE-PARA closes the files, and releases them.

Image169[1]

Sunday, March 7, 2010

Sequential Processing of VSAM Files

Q. What are the ENVIRONMENT DIVISION considerations for sequential processing of KSDS File?
The SELECT statement in COBOL assigns a Symbolic-name(second name), to the actual TSO-file. So, I could use the symbolic file-name OUTPUT-FILE in COBOL, to refer to my file AGY0157.EMPLOYEE.KSDS.

SELECT Statement describes the file - (i) what’s the file-layout, the organization (ii) and the mode of processing(how are you going to process it).

File organization - Is the file sequential or does it also have an index, is it indexed. You also want to tell, how the records should be processed in a file – do you traverse the records one-by-one sequentially, and process the file from start-to-end, till you find the desired record – that’s sequential processing. On the other hand, you can directly jump(hop) or fly over-to the desired record(that’s a lot quicker) and process it – that’s random processing. For sequential processing of records, you must set the ACCESS MODE to Sequential.

The SELECT statement highlights the RECORD KEY. The value in record key field provides a unique identification for each record in the file. Every record will have a unique value in record key field. For example, in the Employees KSDS File, the record key is EMP-ID. This is because, every employee has a unique EMP-ID. No two employees have same EMP-ID.

First up, in the picture below, see what the SELECT statement for KSDS file has - 

Image158[1]  

Now, the File descriptor and record-layout(the various fields in Employee record) for the Employees KSDS file is shown in the picture :

Image157[1] 
Q. How do you perform initial loading of records in KSDS file?
When you create an empty KSDS file, you want to store some meaningful data in the file. Storing records, or populating an empty KSDS file with records is called Initial Load. You write records out one-by-one sequentially to the KSDS file. Thus, for the Initial load, the access mode is set to Sequential. During Initial Load, the records must be loaded in increasing(ascending) sequence of the RECORD KEY.

We are going to load records sequentially in the Employee KSDS File. To begin with, here are the Working storage section variables -

Image159[1]

Lines 42-44 define the END-OF-INPUT-FILE flag variable. This variable behaves like a switch, initially it is in NOT-AT-END state. When you have read all the records in the file, it flips over to AT-END state.

Lines 46-48 define the STATUS CODE area for the KSDS File. Whenever you perform a VSAM operation, like opening the file, writing to the file, or closing the file, it leaves behind a 2-digit code number. 00 indicates a successful operation and non-zero code indicates failure.

Make it a habit to use File Status codes because, trapping errors, and nipping them in the bud, helps your program to recover from the dangerous run-time errors, which could crash your program and leave your files or database in an inconsistent state.

Lines 50-51 define the counter variable which keeps track of the number of input records processed.

The procedure for sequentially loading a KSDS file, is as follows
1. OPEN OUTPUT filename
2. WRITE record-name
   FROM data-area
   INVALID KEY what to do
3. CLOSE filename

The WRITE statement in COBOL is used to write a record to a KSDS file. When you initially load a KSDS file, the RECORD KEY must be increasing(ascending) order. What happens when this condition is not met? The WRITE is aborted, and a STATUS CODE is set. The INVALID KEY clause is executed, when the WRITE operation fails. Thus, key-violation is automatically detected by the INVALID KEY clause. Thus, INVALID KEY Routine can be used to trap duplicate key, or out-of-sequence record errors. 

The picture below shows the PROCEDURE DIVISION statements -

Image160[1]

Line 55 performs the OPEN-FILE routine, which opens the KSDS file.

The conditional IF block(Lines 56-63) tests the value of FILE-STATUS-CODES variable. If the Open operation leaves behind a STATUS CODE 00(VSAM-FILE-OPERATION-OK), a loop is generated to load the records in the KSDS file and then close it. If a non-zero status code is left behind(ELSE block), you print a message to the log which says 'Unable to open indexed file'.

Lines 66-69 is the OPEN-FILE routine. EMPLOYEE-KSDS-FILE is opened for output on line 68.

Image161[1]

Lines 71-81 is the load a record into the Employees file. Line 72 reads a record from the input data. The record is placed in the INPUT-RECORD area. Once the record has been read, the counter WS-EMLOYEE-CNT is incremented. The WRITE statement in line 77 attempts to add this record to the file. WRITE automatically sequence checks the records on the RECORD KEY field. If WRITE operation fails, it is because of duplicate key, or out-of-sequence error. A message is DISPLAYed on line 80.

Here, I have just assumed that the WRITE operation fails because of key-violation. However, this may not always be the case(e.g. if the file fills up and no more space is available, or hardware I/O error). Ideally speaking, the STATUS CODE must be tested to differentiate between possible errors.

Image162[1]
Lines 83-92 CLOSE the KSDS file, after the loading is complete. The CLOSE operation leaves behind a STATUS CODE. If the CLOSE is successful, a message is DISPLAYed 'VSAM FILE CREATION COMPLETED'. The number of records processed are also displayed. If the CLOSE fails, the message 'VSAM FILE NOT PROPERLY CLOSED'.

Monday, March 1, 2010

CICS Tutorials

Tutorial Description
Introduction to CICS Learn about the CICS Transaction Server for the zOS. The CICS application programming interface(API) allows developers to create online transactions.
Pseudo-conversational style of programming CICS tasks are pseudo-conversational. Learn the difference between conversational and pseudo-conversational tasks.
CICS Maps and BMS Learn how to construct CICS maps using BMS Macros DFHMSD, DFHMDI and DFHMDF. Read about the Attribute byte and the MDT.

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.