Mainframes 360
The one stop destination for System Z professionals

Saturday, November 6, 2010

Creating a new IMS Database

Q. How do COBOL Programs access Data using IMS/DB Software?
COBOL-Programs use READ and WRITE Instructions to access Data from Files. This invokes or calls a helper-program called Access-Method. The Access-Method Software actually knows the details of how the data is organized, and the location(place) – where the record is stored physically on the big DASD-Disk. The Access-Method actually gets the Data from the File, in units of raw Blocks like 0001HARRYPOTTER1000MUMBAIINDIA. But, the access-method has no knowledge about the Record's format or structure – what are the fields in the Record. The Data fetched would be useless, or of little value if you don’t know its structure or Format. In an H2O water-Molecule, it is the Atomic-Structure that is important. On the same lines, Data is meaningful and can be processed, if you know its structure like (EMPID,FNAME,LNAME,SALARY,CITY,COUNTRY). 

In simple COBOL-File IO Programs, this format, structure or File-Layout, that I am stressing on, is hard-coded or embedded in the COBOL-Program. The COBOL-Program sees the same record-format, as that of the actual-record in the File on the Disk.

By contrast, when data is stored and managed by the IMS/DB Software(one more layer added to the Onion on the right), the COBOL-Program is now unaware of the Structure or record-format. The COBOL-Program talks with the IMS/DB Software which stores structure-details. The complicated details of the record-format and Structure are now taken care of by IMS/DB Software, and the COBOL-Program is spared and relieved from this botheration. The IMS DB/Software in turn, calls the Access-Method Software to actually GET the Data from the Disk-Dataset. The IMS/DB-Software Interface in return presents this Data to the COBOL-Program in the form of Segments. The IMS/DB Software does provides an Abstraction.

Q. How do you create a fresh New Database-File to store Data? Do I go to ISPF Menu Option 3.2?
Say that, you wanna store the data about your Shopping-List – the list of items that you want to buy from the Super-Market, in a Mainframe-File, and you want IMS/DB Software to help you manage your Shopping List. This means, if you want to add an item to the Shopping-List, remove an item from the Shopping-List, or take a Print of all the Items in the Shopping-List, you are gonna ask IMS/DB Software to do it for you.

The sad part is, IMS/DB Software can't read Sequential-Files. IMS/DB Software has the ability to read and write data to VSAM-ESDS Files. Hence, if you plan to use IMS/DB Software to manage your data, better create blank(empty) VSAM-ESDS Files to hold your valuable-Data. I have created an Empty New VSAM ESDS File IMS810.INVENDB by running the free IBM-Software Tool IDCAMS.

I'd use this Empty VSAM Database-File created newly, load my data into it, and then ask IMS/DB Software to manage this data in the future.
Q. What are Control-Blocks?
Whenever a COBOL Program, sends requests to the IMS-DB Software, to access data from the VSAM Database-File, IMS-DB Software cannot directly service it. To support the request, the IMS-DB Software needs (i) The Blue-print of the Database and (ii)the database privileges, the program has. These details are stored in specialized Load-Modules called Control-Blocks.

IMS-DB Software uses the Control-Blocks as a ready-reckoner, and constantly refers to them, for any requests that come along.
Q. What is DBD Control-Block?
The DataBase Descriptor or DBD Control-Block, contains the Database-Structure details – what are the different segments in this data, what are the fields in this segment etc. The DBD Control-Block contains the design of the database, it's a blue-print.

Every Database must have a DBD Control-Block. Say if, there are two hierarchical databases X and Y, there’s got to be two DBDs.

Q. What is PSB Control-Block?
The Program Specification Block or PSB Control-Block contains details about, the Database Privileges granted to a COBOL-Program. The PSB will specify, what database-segments the program is allowed to access, the type of access(Get, Insert, Update, Delete).

The IMS-DB Software uses the PSB Control-Block, to prevent unauthorized access and enforce security. If the Program attempts to access a segment in the database, which is not allowed in the PSB Control-Block, it is a security violation and the IMS-DB Software restricts it.

Every Program must have a PSB Control-Block. Say, if there are two Programs, there's got to be two PSBs. Moreover, a Program's PSB internally  contains a PCB(Program Control Block). For each database accessed by the Program, there is one PCB in the PSB Control-Block.

In the above picture, the first–program can access both Database-X and
Database-Y, but the the second-program is only allowed to access the Database-X.
Q. Who creates the Control-Blocks?
How do you write or code a new Control-Block? You first write the Source-Code of the Control-Block in Assembler Language. But, the Mainframe-Computer doesn't understand Assembler. It knows only Binary Machine Language 0's and 1's. So, after writing the Source-Code, you Assemble-Link it to produce a Binary Load-Module for the Control-Block. IMS/DB Software shall always refer to these Control-Block Load Modules(containing Database structure-details), while storing or retrieving Data from the Database-File.

You go about creating two control-blocks - (i) DBD Control Block and (ii) PSB Control-Block.
Q. How do you write the Source-Code of the DBD Control-Block?
The secret to writing Source-code for DBD-Control Block, is you’ve got to think, "What's the Structure of the Data, that you are going to store in the VSAM-ESDS Database-File?" Say for example, I want to generate DBD Control-Block for the Inventory-Database. A pictorial representation of the Inventory-Database Structure is given below.

Here's a brief description of the Inventory-Database. The Inventory-Database has three segmentsVendor, Item and Stock-Location. When you begin to write Assembly Language Source-Code for the DBD Control-Block, ask yourself, "What are the segments in this Database"? For each segment, you code a SEGM Macro. This is how the skeleton of the Source-Code looks like. Code 3 SEGM Macros, one for VENDRSEG, one for ITEMSSEG and the last for STLOCSEG. The PARENT Attribute on the SEGM Macro tells, "who's the Parent of this Segment"? Since, Vendor Segment is the root, I coded PARENT=0 on it. On ITEMSSEG, I coded PARENT=VENDRSEG and likewise on STLOCSEG, I coded PARENT=ITEMSSEG. For each Segment, the BYTES Attribute indicates the total Sum-Length of all the Fields in that Segment. I’ll revisit this attribute a little later.


Now, every Segment VENDRSEG, ITEMSSEG and STLOCSEG can have many fields. Code the FIELD Macro once, for each Field. FIELD Macros go under the appropriate SEGM Macros. I am gonna explode each segment one-by-one, and show you how to code its Fields. 

Vendor Segment is the list of the Vendors, which supply Raw-Materials. Every Vendor has a 3-Character Alphanumeric Code-Number, a name, an address, city, state and Zip-Code where the Vendor is located and Telephone-Number and Contact-No. The BYTES Attribute indicates the length of the Field. The START Attribute indicates the Starting-Position or Offset(Displacement) of the Field. Let me elaborate it : VENDRNAM is 30 Bytes in Length, and starts from Position 34. It implies VENDRNAM spans from Position 34 to Position 63(30 Bytes). Consequently, the next successive Field VENDRADR will start from Position 64 and so on. An easy formula to remember this is –
Starting Position = (Previous Field's Start + Previous Field's Length).

Moreover, the TYPE Attribute indicate the type of data. Alphanumeric or PIC X Fields have TYPE=C. Numeric Fields(PIC 99) have TYPE=Z. Packed Decimal(
PIC S9(05)V99 COMP-3) have TYPE=P.

If you sum-up the field-lengths of VENDRCOD, VENDRNAM, VENDRADR, VENDRCIT , VENDRSTA, VENDRZIP, VENDRTEL and VENDRCON = (3+30+30+17+02+09+10+30) = 131 Bytes. It means the One Vendor's data will be 131 Bytes in size. So, you code BYTES=131 on the Vendor Segment's SEGM Macro.


When you write a COBOL-Program to fetch the Vendor-Data from the
IMS-Database, the Vendor-Data received from the IMS/DB Software into the
COBOL-Program needs to be stored or kept somewhere. You need COBOL-Variables corresponding to each of these VENDRSEG Fields that will store or hold the data in the COBOL-Program, when it received from the IMS Vendor Segment. Here, is the COBOL Copy-Book(a separate Mainframe File) containing the COBOL Variables corresponding these VENDRSEG FIELDs.


One Vendor may supply several Items. Item Segment represents the list of the Items, which a Vendor supplies. Every Item has an Item-Name, a short description, unit-price or cost of the Item and the average cost of the Items. Here’s the DBD Source-code for the ITEMSSEG Segment.


The COBOL Copy-Book Layout(a Separate Mainframe File) corresponding to the Above ITEMSSEG, is shown below. 


One Item may be stocked or stored at multiple-locations or warehouses.
Stock-Location segment represents the list of the locations, where an item is stored or stocked. Each Location is identified by a 3-character alphanumeric code. At every location, important-details about the inventory such as what is the quantity-on-hand, what is reorder-point, what is the quantity-on-order, and the last re-order date is recorded.

This picture shows, how I wrote the DBD Source-Code for the Stock-Location Segment.


The COBOL Copy-Book Layout(A Separate Mainframe File) corresponding to the above Stock-Location Fields, is in the snap below.

Q. How do I assemble and Link the above DBD Macros?
I have the following setup at my shop. I have created a Library(PDS) for storing the DBD Macro Source-Codes called IMS810.DBDSRC. I have keyed in my DBD Source-code in a Member INVDBD, under the Source Library. I have another Library(PDS), which will contain the corresponding DBD Control-Blocks Load Modules, which are produced after assembling the source-code. My DBD Load-Library is IMS810.DBDLIB. Before you run the assemble-link job, you should have your own personal DBD-Source and Load-Libraries setup.

To Assemble and Link your DBD-Code, you run the Assembler-Software
(EXEC PGM=ASMA90) first and followed by the Linker-Software(EXEC PGM=IEWL). So, you write a simple two-step Assemble-Link job. You can download this JCL by clicking here. This is how it looks.


There are four-variables that you need to set. The DBDNAME Parameter is the name of the DBD. The SRCLIB Variable is the DBD Source-Library. The MACLIB Variable is the IMS Macro-Library. You should ask the System Programmers at your shop and find out, the name of the IMS Macro Library. Last, the DBDLIB is the name of the DBD Load-Library.
Q. How do you write the PSB Macro Source Code?
A PSB Control-Block is like a Entry Pass(Ticket). The PSB helps prevent any unauthorized Access to the Data. IMS/DB Software checks PSB Control-Block to enforce Access-Control.

Every COBOL Program that accesses IMS/DB Database, has its own PSB(Entry Pass). In fact, it is customary to have the PSB-Name same as the Program-Name. Inside each PSB, there are several PCBs. Suppose there are two Databases –Employee Database EMPDBD and Inventory Database INVDBD, that the program needs access to. You code a PCB-Macro for each Database, that the program accesses.

The PCB Macro, essentially tells the Processing Options PROCOPT=G. PROCOPT Parameter is damn important and indicates the Access-Privilege. For example, to authorize the program to only read the data from the Database, code PROCOPT=G. On the other hand, for a Program to initially load data into the the Database, coding a PROCOPT=LS is necessary, and so on..

Look, how I have written the Source-Code for the a simple PSB which has one-PCB for the Inventory-Database. If a Program uses this PSB, the program will only be able to access Inventory Database(and not Customer Database). You may also download this Source-Code by clicking here.


Following the PCB-Macro, you may code the SENSEG or Segment Sensitivity Macros. You code one SENSEG Macro for each Segment. The NAME Parameter indicates the name of the Segment. I have coded three SENSEG Macros for VENDRSEG, ITEMSSEG and STLOCSEG.
Q. How do I assemble and link the above PSB Macros?
I have the following setup at my end. I have created a Library(PDS) for storing my PSB Macro Source-Codes IMS810.PSBSRC. I have keyed in my
PSB Source-Code in a Member INVPSB under the Source-Library. I have another Load Library or PDS IMS810.PSBLIB, which will contain the PSB Control-Blocks Load-Modules, produced on assembling the Source-Code. My advise to you is, go ahead and first setup your Own personal PSB Source-Library and Load-Library before you run the Assemble-Link Job.

Just like the DBDGEN Job, I have written a PSBGEN Job to Assemble-and-Link the PSB Code. See below how the PSBGEN Job looks. You may also download this JCL Code by clicking here.


There are four variables, that you need to set. PSBNAME is the name of the PSB. SRCLIB is the Source-Library containing the PSB Macros Source-Code. MACLIB is the IMS Macro Library. PSBLIB is the Load-Library where the PSB Control-Blocks reside.

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.