IMS/DB Overview

CONTENTS
Introduction

2 Hrs

2 Hrs

Hierarchical Database & Terms

IMS DB components
IMS DB program coding
IMS DB Functions
IMS Status codes
IMS Processing Modes

4 Hrs
4 Hrs
2 Hrs

2 Hrs
2 Hrs
2

Introduction
IMS DB
Information Management System - DataBase Used for

creating and managing the physical storage and retrieval of

data which is organized using the hierarchical data structure.

IMS DB is the part of the IBMs software product IMS/VS

(Information Management System/ Virtual Storage).

IMS/VS is having two components :

IMS/DB : Used to create and manage the databases.

IMS/DC : Used to handle the online transaction
processing.

Hierarchical Database & Terms

The data relationship in IMS/DB is Hierarchical.
Hierarchical Database : Its a Tree structure.
Relationship of data is predefined by its structure.
Program Traverses the structure to access the data.
So all the access is through the predefined paths.
Its major advantage is speed of access as path is
predefined.
Disadvantage is the reduced flexibility inherent in a predefined structure and its complexity of design.

Hierarchical Database
ACCOUNT
BILLING

ADVANCE

FEES

RATE

CASH

PAYMENT
PAYCASH

PAYCHEQ

CHEQUE

 Terminology :
Segment : Smallest unit of data an application can
retrieve from a database, contains one or more
fields of data.

Root
: The entry point to the database. No parent.
Parent
: Segment with dependent segments.
Child
: Dependent segment of parent
Twin
: Multiple occurrences of a dependent segment
Key
: Unique identifier of a segment
Concatenated Key
: The concatenation of all the keys
of the parents with the key of the
segment.

Database Record
Search Field

: One root with all of its children.

: Any field defined in the database
definition.

 Sequential processing sequence of an IMS database is Topto-Bottom, Front-to-Back and Left-to-Right.

An IMS database consists of some number of database
records. The Size of the database is limited only by the
constraints of VSAM and DASD.
A maximum of 15 levels are allowed.
IMS allows up to 255 different segment types in a single
database.
IMS keeps track of its place in the database after every call.
So it is important to keep database position in mind.
IMS always moves forward, never backward.

IMS DB Components
Components of an IMS System
APPLICATION Program : The user modules written in
Assembler, Cobol, PL/1
DATABASE : The data accessed by one or more application.
DL/I Modules : The modules which interface between the MVS
access modules and the application program. All access to
IMS databases is through this module. So every time a
database is read or updated the DL/I interface must be called.
DL/I Control Blocks : The executable modules which define the
databases and the application programs view.

MVS

DATA
BASES

MVS
ACCESS
MODULES

PCB
MASK

DL/I
MODULES

DBD
PCB

APPLICATION
PROGRAM

(In

DBDLIB
PSBLIB

PSB)
APPL.
CONTROL
BLOCKS

 IMS Database Terminology :

DBD( Database Definition)
Defines the physical structure of the database.
PCB(Program Communication Block)
Defines the application view of the database.
PSB( Program Specification Block)
Contains all the PCBs for a specific program.
ACB( Application Control Block)
An Internal Control Block containing DBD and PSB
information.

10

DATABASE DEFINITION (DBD)

The DBD contains the database name and defines the actual
tree structure.
The Information given in the DBD includes :

Database name
Segment name
Key field names, lengths and locations
Search field names, lengths and locations
IMS and MVS access methods
DD names (Logical name for datasets)

DBDs are assembled and resides in DBDLIBs. The process

of assembling is called DBDGEN.

11

Example of DBD source:

TITLE
*
*
PRINT
DBD

'ASSEMBLE OF DBDNAME=OUTABLDB '

DSNAME=CAPSMISC.TAMRA.DBDLIB
VOL=DMAS82
NOGEN
NAME=OUTABLDB,
ACCESS=(HDAM,VSAM),
RMNAME=(OUTB80RM,1,750),
PASSWD=NO,
*************************************************************
DATASET GROUP NUMBER 1
************************************************************ DSG001
DATASET DD1=OUTABLD0,DEVICE=3380
SIZE=(4096),SCAN=3
*****************************************************
*
SEGMENT NUMBER 1
*****************************************************

12

SEGM NAME=OWTB58RT,
PARENT=0,
BYTES=5,
PTR=(TWIN,,,,)
FIELD NAME=(OWTBROOT,SEQ,U),
START=1,
BYTES=5,
TYPE=C
*******************************************
*
SEGMENT NUMBER 10
*
*******************************************
SEGM NAME=OWTMRSEG,
PARENT=((OWTB58RT,SNGL)),
BYTES=1250,
PTR=(NOTWIN,,,,)
DBDGEN
FINISH
END

13

PROGRAM COMMUNICATION BLOCK (PCB)

The PCB is the programs view of a database. It defines the
databases to be accessed and the scope of the programs
access.
It defines the segments which are available to the program.
So if a PCB does not contain one or more of the segments
in a database, it means the program is not sensitive to
these segments.
So only the segments defined in PCB will be accessed and
these are called as sensitive segments.
The PCB also states what type of activities are allowed on
respective segments : add, update, delete or read.

14

 The processing options allowed in a PCB are :

I
R
D
G
A
L
LS

:
:
:
:
:
:
:

To add/insert a segment.
To change/replace a segment.
To remove/delete a segment.
To read/get a segment.
All functions except load
To initialize(Load) database
Load the database but database must be in key
seq..
GO : Read only. So to read a segment, even if another
program is updating it.
Multiple of the options can be defined as in GI, meaning that
the program can get and/or insert segments.

15

 The processing option can be coded at the database level so

will be applicable for all the sensitive segments or it can be
defined at the segment level.
IO-PCB
It is also called as TP-PCB. It is used in online transactions
to process messages to/from the terminal and in batch
programs to take checkpoints.

16

PROGRAM SPECIFICATION BLOCK (PSB)

A PSB is the set of all PCBs that a program is going to use.

The program can access only databases which are defined

in the PSBs and can perform only those operations which
are defined under Procopt.

PSBs are assembled and resides in PSBLIBs. The process of

assembling is called PSBGEN.

17

Example of PSB source:

TITLE 'ASSEMBLE OF PSBNAME=#FNT15 '
*
DSNAME=CAPSMISC.TAMRA.PSBLIB
*
VOL=DMAS51
************************************************************
*
PCB NUMBER 1
TP NUMBER 1
************************************************************
PCB
TYPE=TP,
LTERM=,
ALTRESP=NO,
SAMETRM=NO,
MODIFY=YES,
EXPRESS=NO

18

***********************************************************
*
PCB NUMBER 2
DB NUMBER 1
***********************************************************
TYPE=DB,
DBDNAME=FKTSTMDB,
PROCOPT=AP,
KEYLEN=12,
PCBNAME=PCB2,
LIST=YES
SENSEG NAME=FKSGROOT,
PARENT=0
SENSEG NAME=FKSG02ND,
PARENT=FKSGROOT
SENSEG NAME=FKSG03RD,
PARENT=FKSG02ND

PCB

19

***************************************************************
*
PCB NUMBER 3
DB NUMBER 2
***************************************************************
PCB
TYPE=DB,
DBDNAME=FKTSTPDB,
PROCOPT=AP,
KEYLEN=12,
PCBNAME=PCB3,
LIST=YES
SENSEG NAME=FKSGROOT,
PARENT=0
SENSEG NAME=FKSG02ND,
PARENT=FKSGROOT
SENSEG NAME=FKSG14TH,
PARENT=FKSG13TH,
PROCOPT=A

20

***********************************************************
*
PCB NUMBER 4
GSAM NUMBER 1
***********************************************************
TYPE=GSAM,
NAME=CSIBCHIN,
PROCOPT=G
***********************************************************
*
PCB NUMBER 5
GSAM NUMBER 2
***********************************************************
PCB TYPE=GSAM,
NAME=CSIQLOAD,
PROCOPT=L

PCB

PSBGEN PSBNAME=#FNT15,
LANG=ASSEM,
IOASIZE=512,
CMPAT=YES
END

21

APPLICATION CONTROL BLOCK (ACB)

When IMS executes an application program, it uses an ACB.
An ACB is the run-time control block that is a consolidation
of the PSB and DBDs.
For batch programs, IMS dynamically creates the ACB from
the PSB and DBD.
For online programs, an ACB gen is run which merges the
DBD and PSB and creates the ACB.

22

IMS DB Program Coding

This section brief how to actually code application programs
which access IMS databases. The following topics will be
covered to have a better understanding of an IMS program:

Program Entry Statement

Communication with IMS
PCB MASK
IO-AREA
SSA
Segment & SSA Copybooks

23

Program Entry Statement

This is the starting point of your program. It should be the
first executable statement in your IMS program. So in Cobol
it follows the Procedure Division statement.
IMS passes control to the application program at the ENTRY
statement in the program; the application program returns
control to IMS when finished by issuing a GOBACK.
ENTRY DLITPLI USING

IO-PCB
LOAN-PCB
PAY-PCB.

24

 PCBs are passed by IMS to the application program in the

same order they are listed in the PSB. The IO-PCB must be
listed first.
For IMS programs that also uses DB2, the entry statement is
not specified. Instead the PCBs are coded in the Procedure
Division statement.
PROCEDURE DIVISION USING

IO-PCB
LOAN-PCB
PAY-PCB.

25

Communication with IMS

Access to an IMS database is gained through the Data
Language Interface, commonly known as DLI.
The DLI interface may be invoked in one of two ways :
By making a call to the IBM supplied program CBLTDLI &
passing an PCB
By invoking the EXEC-DLI CICS interface & passing a
PCB

26

PLITDLI call :

CALL PLITDLI USING

PARM-COUNT
FUNCTION
PCB
IO-AREA
SSA.

Parm-count tells how many parameter follow. This is a 4-byte

binary field defined as S9(8) COMP.
Function Tells DLI what type of call to make.
Contd..

27

 PCB tells IMS what database to process and has return

information from IMS.
IO-AREA tells IMS where to place the data (for retrievals) and
where to find the data (for updates).
SSA (Segment Search Argument) steer IMS to correct segment
by supplying details such as segment name and key values.

28

PCB & PCB-MASK

The PCB describes the results of each call made to IMS.
There should be a one to one relationship between the PCBs
defined in the PSB and the PCBs defined in the program.
The PCBs are listed on the ENTRY statement and then
defined in the LINKAGE SECTION in the form of PCB-MASK.
One PCB-MASK for each PCB.
Each PCB-MASK is an 01 level record in the linkage section.
While the order of the PCBs is critical on the ENTRY
statement, the order of the PCBs in the linkage section is of
no consequence.

29

 Thru PCB IMS communicates with the program. The

application program must interrogate the PCB to determine
the success or failure of the call.
So the structure of IMS application program will be as
follows:
:
:
01 PCB-MASK.
:
PROCEDURE DIVISION.
ENTRY DLITCBL USING PCB-MASK
:
DL/I CALLS

30

 PCB MASK structure:

POS

DESCRIPTION

1-8
9-10
11-12
13-16
17-20
21-28
29-32
33-36
37-XX

DATABASE NAME
SEGMENT LEVEL
STATUS CODE
PROCESSING OPTIONS
RESERVED FOR DL/I
SEGMENT NAME
KEY FEEDBACK LENGTH
NO. OF SENSITIVE SEGMENT
KEY FEEDBACK AREA

31

 PCB MASK EXAMPLE:

01 LOAN-PCB.
03 DBD-NAME
PIC
03 SEG-LEVEL
PIC
03 STATUS-CODE PIC
03 PROC-OPT
PIC
03 FILLER
PIC
03 SEG-NAME
PIC
03 KEY-FEED-LEN PIC
03 SEN-SEG PIC S9(8)
03 KEY-FEED
PIC

X(8).
99.
XX.
X(4).
X(4).
X(8).
S9(8) COMP.
COMP.
X(100).

32

 The status-code is most important and must be checked

after every call made to the IMS.
The segment-level and the segment-name contain the level
and name of the last segment IMS processed.
The key-feedback area contains the full key of the last
segment processed.
The IMS itself fills in the PCB with information;the
application program never moves anything to it.

33

IO-AREAS
The IO-AREA passed to the IMS is the storage location for
the segment to be processed. Its a two-way communication.
For retrieval calls, the IMS places the segment retrieved in
the IO-AREA.
For update calls, the program must place the update
segment in the IO-AREA and IMS will use it to update the
database.
The IO-AREA length should be more enough to hold the
longest segment used in the program, otherwise IMS will
overlay the subsequent storage after the IO-AREA.

34

SEGMENT SEARCH ARGUMENT (SSA)

SSA allow the application program to define to IMS the type of
database access required.
There are two-types of calls to IMS :
QUALIFIED CALL

: The application pgm provides an

SSA telling IMS what segment
to access

UNQUALIFIED CALL : The application pgm does not

provide an SSA. IMS will determine
what segment to process.

35

 For Qualified calls, there are two types of SSAs :

UNQUALIFIED SSA : Only the segment name is

provided

QUALIFIED SSA

: The segment name, key value and

other information is provided by
the application.

36

 UNQUALIFIED SSA
POS

DESCRIPTION

1-8
9

SEGMENT NAME
BLANK

Example
01 UNQUAL-SSA.
03 segment-name pic x(9) value ACCOUNT.

37

 QUALIFIED SSA
POS

DESCRIPTION

1-8
9
10-17
18-19
20-XX
XX+1

SEGMENT NAME
LEFT PARENTHESIS
KEY NAME FROM DBD
RELATIONAL OPERATOR
VALUE OF KEY-FIELD
RIGHT PARENTHESIS

38

Example
01 ACCOUNT-SSA.
03 seg-name

pic x(8) value ACCOUNT.

03 left-paren pic x value (.

03 key-field

pic x(8) value ACCOUNT#.

03 filler

pic x(2) value EQ.

03 key-value

pic x(6) value 123456.

03 filler

pic x value ).

39

So now we are ready to see a full fledged DLI call. The

example below will retrieve exactly one segment with a
specific key value supplied by the call.
CALL PLITDLI USING

GU
LOAN-PCB
BILLING-IO-AREA
ACCOUNT-SSA
BILLING-SSA.

40

Segment & SSA Copybooks

The structure of segments are generally kept in copybook
members and these copybook members are used in the IMS
program by using COPY statement.
Similarly its a good practice to code the SSAs in a separate
copybook member (one for each segment) so there is no
need to code them again and again inside the programs.
In this case then you need to copy the SSA member by
COPY statement and then just pass the values in key-valuefield and use it in call..

41

IMS DB Functions
IMS Databases can be processed one of two ways :

Sequential Processing : The database is processed in sequence

from some starting point. The order of the retrieval of the
segments is determined by their physical order on the
database.

Random Processing : The database is not retrieved in any order.

The application program asks for a specific segment identified
by some field in the segment.

42

These two processing methods can be used to retrieve, delete, add

or to change the segments. Several Call functions are available in
IMS to process the segments.

GN : get next
GHN : get hold next

GNP : get next within parent

GHNP : get hold next within parent

GU : get unique
GHU : get hold unique

ISRT : insert a segment

DLET : delete a segment
REPL : replace a segment

43

 Hold means to hold the segment in exclusive mode for a

possible update.
Within parent means to retrieve the next dependent segment
of this parent.
Unique asks IMS to retrieve a specific ( Unique) segment in
the database.
An unqualified get next retrieves the next sensitive segment
in the hierarchy.
An qualified get next retrieves the next sensitive segment
matching the search criterian.

44

 When inserting, or adding, a root segment, IMS puts the

segment in the proper position in the database, based on the
value in the key field of the io-area.
When inserting a child, or dependent the key of the parent
may or may not be provided.
If the parent is not qualified, the segment will be inserted at
the current database position, as a child of the last parent
processed.
If the parent is qualified, the segment will be inserted as a
child of the specified parent, regardless of the database
position.
The type of segment to be inserted must always be specified.
MS takes the key-info fron io-area.

45

 When replacing a segemnt the application must have first

read and held the segment for update (GHU, GHN, GHNP).
So no qualification is allowed on replace.
The key-field on a segment can never be changed.
When deleting a segemnt again the application must have
first read and held the segment for update (GHU, GHN,
GHNP).
When a parent segment is deleted all dependent segments
are always deleted automatically.This is true even if the
application pgm is not sensitive to the dependent segments
in the PCB of the PSB.

46

PARANTAGE :
Parantage is set by the GNP or GHNP functions.
These commands sequentially process the database but limit
the segments to dependent segments of the established
parent.
The Seq. Search starts at the current position and stops at
the last dependent segment of the parent.
Parentage must have been set prior to issuing GNP/GHNP
request. This can be done by two ways :
By retrieving a parent segment with the help of GN, GU
etc. Command. Parentage will be set at the last segment
read.
By using Command codes.

47

IMS Status Codes

After every call IMS returns a status code in the PCB. The status
code describes the success or failure of the call.

The status code should be checked after every call to IMS.

If an unexpected status code is encountered, the program

should abend.

IMS Status code can be divided into three categories :

Informational, Program error, IO Error.

For calls using XXXTDLI all status codes are returned to the
application program.

48

The most common Status Codes are as follows:

BLANK

- The call was successful.

GB - End of database reached.

GE - Segment not found.
GK - During unqualified call IMS crossed to a next
segment type at the same level.
GA - During unqualified call IMS crossed to higher
level of hierarchy.
AD - Function code is invalid .
AK - Field name does not match the name in DBD.

Cont..

49

 AI

- Open error; probably a missing DD statement.

DA

- Pgm tried to change the key value on a replace or

delete call.

DJ
not

- Pgm tried to replace/delete a segment that had

been held.

II

- Pgm tried to insert a segment that is

already exist.

AJ

- The SSA is coded incorrectly.

50

IMS Processing Modes

IMS Processing can be done thru three different modes :
DL/I - Its a pure batch processing and database will be
mentioned in the form of DD statement. i.e. The databases will
be used in when they are not up.
BMP- Batch Message Processing. In BMP mode the application
run in conjunction with an IMS control region. An MVS started
task controls all online and BMP programs. Although these jobs
are run thru batch mode but they use to run on database
directly. i.e. BMP jobs uses online databases. BMP jobs can be
hourly, daily, weekly, monthly etc.

51

 MPP - Message Processing Program

In MPP mode the application run is a online
application which updates/enquire database in pure
online mode. All the transactions made by various
terminals accumulated in the form of messages in a
message queue and then the IMS schedular process
all those messages against online databases thru
online programs. All MPP request are handled thru
the IMS online region.

52

SUMMARY
The course is starting with the introduction of IMS
terminology and covering all areas essential to start writing a
IMS DB program.
The topics covered in the course are Intro to IMS DB
components, Programming techniques, Various functions and
status codes in IMS and finally a brief about the processing
mode available in the IMS world.
This course is definitely a good start to sail through
the IMS ocean and to explore its power and complexities.

53