Mainframes 360
The one stop destination for System Z professionals

Sunday, December 26, 2010

Inserting data into an IMS Database

Q. Give me a rough sketch of this COBOL-IMS Program.
I have coded a COBOL-Program to initially load(insert) data into an IMS Database. Broadly speaking, this COBOL-Program reads a Transaction from a Line-Sequential File, and loads it into the Inventory IMS Database. This process is repeated over and over again, until all the transactions from the Line-Sequential File have been read, and you've reached the End-Of-File.

Here's the Structure-Chart for this COBOL Program. A short overview of the modules of this COBOL-Program is given below.

I have broken down this COBOL-Program into 3 Modules – 300-HOUSEKEEPING(Yellow), 500-MAINLINE-PROCESSING(Pink) and 700-CLEANUP(Blue). The Housekeeping Module essentially performs any preparatory tasks such as, Opening the File etc. The Cleanup Module on the other hand, performs termination tasks such as, closing the file, displaying Program-Statistics, just before the program is about to end. 

The heart of the Program is 500-MAINLINE-PROCESSING Module. Read a Transaction, insert into the Database, read the next transaction, put in the database and this cycle of reading-and-inserting continues, till all the transactions have been processed.
Q. Could you show me the Program-Header?
The Name of this COBOL-IMS Program is IMSPGM01. The Program-Header has Comments which describe the Program-Name, the functionality of the program. This COBOL Program gets the data-input from the
Line-Sequential INPUT-FILE (Symbolic Name is INDD). Line 28 in the Program-Listing, is the SELECT Statement, which assigns the COBOL File INPUT-FILE to the Symbolic File-Name INDD.

Q. What is the Record-Layout of the Input-File? What's the data in the Input File?
The Input-File contains the Data, to be Inserted into the IMS Database. The COBOL-format or Record-Layout of the Data Input-File, is stored in a separate Copybook INVINPUT. I have shown the various fields of the Input-File Record below.


The Line-Sequential Input File has 132-Byte records. Let me show you a rough sketch(though not the exact representation) of the data-contents of the Input-File, so you would be in a position to compare the File-Record vis-à-vis its Record Layout.

I have used the symbol '|' as a Separator between fields, for the sake of understanding. Every record has a 1-Byte Transaction code, which tells if its Vendor Data(V), Item-Data(I) or Stock-Location Data(S). Then follows the actual Data-Area which is 131-Bytes large.

Let's take a look at Vendor records in Blue. 001 is the Vendor-Code, 'INDUS CHEMICALS' is the name of the vendor. Peter’s Road Royapettah, Chennai, TN and 600001 make up the address, city, state and zip-code. 4464004332 and 8097415095 make up the Contact Field.

There are four Items in this file in Red. 0011 is the item number, 'Sodium Palmitate' is the item description, 15500.00 and 4600.00 make up the item-price and unit-cost fields.

There are six Stock-Location records in this file in Green. DEL is the location, 1500 is the quantity-on-hand, 300 is re-order point and 450 is the quantity on order. 16-02-04 is the re-order date.

For those of you, who'd be setting up the Mainframe File at Home, here’s a Hex-dump of the Mainframe File – the actual data contents of the Mainframe Input File.

Let me now bring things into perspective. I have created a new blank Inventory-Database with the following Segments – Vendor Segment, Item Segment and Stock-Location Segment. A Vendor may supply many Items. An Item may be stocked at many locations.

When you load Data into an IMS Database, you must load the records in Sequential(Hierarchical) Order. Basically, my COBOL-Program will read the data from the Inventory-File and LOAD it Sequentially into the IMS-Database, shown above. After Loading, the resulting IMS-Database will have records like this -

Q. What is there in the FILE Section of the COBOL-IMS Program?
The FILE SECTION of my COBOL Program, describes the Record-Layout of the Input-File. The Record-Layout(COBOL Structure) of my Input-File is maintained in a separate Mainframe Copybook INVINPUT under the Library SYSADM.DEMO.COPYLIB. I just COPY INVINPUT, in my COBOL Program, it'll be expanded(substituted) at compile-time.

Q. What does the Working-Storage Area of a COBOL-IMS Program look like?
I am going to follow a standard Working-Storage Layout for all of my COBOL-IMS Programs. The picture below explains, how I have organised my Working Storage Layout. 

Q. What are the Flag and switches in this COBOL Program?
Flags and Switches : I use the END-OF-FILE Switch to raise an alarm, when all the transactions in the Input-File have been read. Its initial value is set to 'N' – the label NOT-AT-END. After the last record is read, the switch is turned ON, its value is set to 'Y'. 

Q. What about the DLI Function Codes?
The DLI Function is the operation to be performed on the IMS Database. Since, I am going to Insert New Data in the Inventory Database, I shall use the ISRT Function.

Q. What about the Segment Input-Output Area?
The Segment IO-Area is a COBOL Storage Area, a buffer for sending and receiving data from IMS DB Software. In this COBOL Program, I shall first store the data in the Segment IO-Area, and then issue an ISRT Call. Consequently, the data from the Segment IO-Area gets inserted into the Inventory Database.


The IO-Area should be big enough to accommodate Vendor Data, or Item Data or Stock Data. Out of the tree, the data of 1 vendor takes largest space  - 131 Bytes, so I have declared my IO-Area to be a PIC X(131).
Q. What about the Application Database SSA's?
SSA(Segment Search Arguments) is used to specify the Segment-Type. For example, if I had to insert Vendor Data, the SSA would be set to 'VENDRSEG '. Likewise, if I want to insert Items Data, I'd have to set the SSA to 'ITEMSSEG ', and to insert Stock Data, the SSA would have to be 'STLOCSEG '. I have declared the SSA as a 9-Bytes COBOL Field.

Q. What about the Counters in this COBOL Program?
I would like take counts of the number of input transactions read, no. of records inserted into database, and the no. of records that error-ed out.

Q. What is there in the LINKAGE Section of this Program?
After issuing an IMS Call, the IMS DB Software stores a 2-Digit Status Code, indicating the success or failure of the Database Operation in the PCB Control-Blocks in Memory. The corresponding COBOL Definition(Fields) for these PCB Control-Blocks is called the PCB Mask. The PCB Mask COBOL Fields are declared under the Linkage Section of a COBOL-IMS Program.

Here's the PCB Mask COBOL Fields. I have stored them in a separate Mainframe Copy-Book INVENPCB, under the Library SYSADM.DEMO.COPYLIB.

What I did is, I just coded COPY INVENPCB, in my COBOL Program, so the above PCB Mask COBOL Fields get copied to my COBOL Program at Compile-Time.

Q. Roughly, what does the PROCEDURE DIVISION of this COBOL Program look like?
The PROCEDURE DIVISION is broadly broken down into three activities – Initialization, Processing and Cleanup. The Lines 76 through 77 of the COBOL Source-Code PERFORM the 300-HOUSEKEEPING Para, that does startup things like, Opening Files, and prepares for the processing ahead. The lines 79 through 80, PERFORM the 500-MAINLINE-PROCESSING Paragraph. The function of the MAINLINE-PROCESSING Paragraph is, to read the data from the Input-File, and Insert this data into the Database. After all the data has been inserted, the Lines 83 through 84 PERFORM the 700-CLEANUP Routine, that does termination tasks, like closing any files.

Q. What does the Housekeeping Routine do?
The 300-HOUSEKEEPING Routine essentially OPENs the COBOL File INPUT-FILE. Once the file is OPEN, you can read the data-records from the File. 

Q. What does the Mainline Processing Routine do?
The 500-MAINLINE-PROCESSING Routine is broken down into three steps : (A) Read a Data-Record from the Input-File (B) Preparing the Data to be Loaded into the IMS Database(C) Insert the Data Record into the IMS Database.

Q. What does the 530-READ-DATA Routine do?
The 530-READ-DATA executes the COBOL READ instruction. The READ...END-READ Block reads one record from the INPUT-FILE. The AT END special condition holds TRUE, when all the transactions from the INPUT-FILE have been processed, and the End of the Sequential File has been detected. No further processing is needed. The Line 115 in the COBOL Source Code SETs my AT-END flag to TRUE, thereby turning ON the END-OF-FILE-SWITCH = 'Y'. The GO TO Statement in COBOL causes the control to jump to 500-MAINLINE-PROCESSING-EXIT Point, and exit out.

Q. What does the 550-PREPARE-LOAD-DATA Routine do?
When one Record is Read from the INPUT-FILE, it gets stored in the 01-Level Group Data-Item INPUT-RECORD. Essentially, the INPUT-RECORD in the file has a 1-Byte TRANSACTION-CODE Prefix , followed by a 131-Bytes DATA-AREA, which consists of the actual data to be inserted.

The below schematic gives you a Split-View of any data-record, when it fetched from the INPUT-FILE into the INPUT-RECORD Cobol Area, in the COBOL Program. Like when the first record is read, 'V' is stored in the TRANSACTION-CODE Field, and '001 INDUS CHEMICALS ...' is stored in the DATA-AREA.

Essentially, we are interested to Load, whatever contents are present in the DATA-AREA into the IMS Database. Thus, I have coded a MOVE from DATA-AREA to the SEGMENT-IO-AREA, in the COBOL Program.


Moreover, you also need to supply an Unqualified-SSA on the ISRT Call. This will tell IMS, what's the data you are trying to Insert? Is it Vendor-Data, Item-Data or Stock-location Data? Observe that, in the INPUT-RECORD, the TRANSACTION-CODE field contains either V, I or S. In the COBOL Code, I'll check this field. A transaction-code 'V' implies Vendor-Data, 'I' implies Item-Data and 'S' implies Stock Location Data. I have coded a MOVE statement, to store the appropriate Segment-Type to the Unqualified-SSA.

Now, we are all set to Insert the Data in the IMS Database.
Q. How does the 560-ISRT-INVDB Routine look like?
The 560-ISRT-INVDB Routine issues an ISRT Call on the Inventory Database. The data stored in SEGMENT-IO-AREA will be inserted into the Database. The Segment-Type is indicated by the Unqualified SSA.


After execution, IMS DB Software communicates back important information, such as a two-digit Status code representing the Success or Failure of the Operation, the Key-Value of Data last inserted, the Key-Length etc in the PCB Control Blocks in Memory. You can see these details in the COBOL Program through the INVENTORY-PCB-MASK. By examining the contents of the INVENTORY-PCB-MASK in the COBOL Program, you can decide what messages to print, if an error occurs.

The IF-ELSE Block tests Success or Failure of the ISRT Call. When the ISRT Call is successful, the IMS DB Software sets SPACES, in hexadecimal format X'4040', as the Status Code. If the ISRT Call fails, IMS DB Software sets a Non-Blank Status Code.
Q. What does the 700-CLEANUP Routine do?
The 700-CLEANUP Routine is called, during termination of the COBOL Program, to close the INPUT-FILE after all the transactions have been processed.


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.