IMSDB

Overview
The term database means a collection of related data organized in a way that can be
processed by application programs. A database management system (DBMS) consists of
a set of licensed programs that define and maintain the structure of the database and
provide support for certain types of application programs. The types of database
structures are network, relational, and hierarchical. This manual presents information on
IMS, a hierarchical database management system from IBM*.

The IMS software environment can be divided into five main parts:

 database
 Data Language I (DL/I)
 DL/I control blocks
 data communications component (IMS TM)
 application programs

Figure 1-1 shows the relationships of the IMS components. We discuss each of these
components in greater detail in this and subsequent chapters.

1
 Figure 1-1: IMS environment components.

IMS Database
Before the development of DBMSs, data was stored in individual files, or as flat files.
With this system, each file was stored in a separate data set in sequential or indexed
format. To retrieve data from the file, an application had to open the file and read through
it to the location of the desired data. If the data was scattered through a large number of
files, data access required a lot of opening and closing of files, creating additional I/O and
processing overhead. To reduce the number of files accessed by an application,
programmers often stored the same data in many files. This practice created redundant
data and the related problems of ensuring update consistency across multiple files. To
ensure data consistency, special cross-file update programs had to be scheduled following
the original file update.

The concept of a database system resolved many data integrity and data duplication
issues encountered in a file system. A database stores the data only once in one place and
makes it available to all application programs and users. At the same time, databases
provide security by limiting access to data. The user's ability to read, write, update, insert,

2
or delete data can be restricted. Data can also be backed up and recovered more easily in
a single database than in a collection of flat files.

Database structures offer multiple strategies for data retrieval. Application programs can
retrieve data sequentially or (with certain access methods) go directly to the desired data,
reducing I/O and speeding data retrieval. Finally, an update performed on part of the
database is immediately available to other applications. Because the data exists in only
one place, data integrity is more easily ensured.

The IMS database management system as it exists today represents the evolution of the
hierarchical database over many years of development and improvement. IMS is in use at
a large number of business and government installations throughout the world. IMS is
recognized for providing excellent performance for a wide variety of applications and for
performing well with databases of moderate to very large volumes of data and
transactions.

DL/I
Because they are implemented and accessed through use of the Data Language I (DL/I),
IMS databases are sometimes referred to as DL/I databases. DL/I is a command-level
language, not a database management system. DL/I is used in batch and online programs
to access data stored in databases. Application programs use DL/I calls to request data.
DL/I then uses system access methods, such as Virtual Storage Access Method (VSAM),
to handle the physical transfer of data to and from the database.

IMS databases are often referred to by the access method they are designed for, such as
HDAM, PHDAM, HISAM, HIDAM, and PHIDAM. IMS makes provisions for nine
types of access methods, and you can design a database for any one of them. We discuss
each of them in greater detail in Chapter 2, "IMS Structures and Functions." The point to
remember is that they are all IMS databases, even though they are referred to by access
type.

Control Blocks
When you create an IMS database, you must define the database structure and how the
data can be accessed and used by application programs. These specifications are defined
within the parameters provided in two control blocks, also called DL/I control blocks:

 database description (DBD)

 program specification block (PSB)

In general, the DBD describes the physical structure of the database, and the PSB
describes the database as it will be seen by a particular application program. The PSB
tells the application which parts of the database it can access and the functions it can
perform on the data.

3
Information from the DBD and PSB is merged into a third control block, the application
control block (ACB). The ACB is required for online processing but is optional for batch
processing.

Data Communications
The IMS Transaction Manager (IMS TM) is a separate set of licensed programs that
provide access to the database in an online, real-time environment. Without the TM
component, you would be able to process data in the IMS database in a batch mode only.
With the IMS TM component, you can access the data and can perform update, delete,
and insert functions online. As Figure 1-1 shows, the IMS TM component provides the
online communication between the user and DL/I, which, in turn, communicates with the
application programs and the operating system to access and process data stored in the
database.

Application Programs
The data in a database is of no practical use to you if it sits in the database untouched. Its
value comes in its use by application programs in the performance of business or
organizational functions. With IMS databases, application programs use DL/I calls
embedded in the host language to access the database. IMS supports batch and online
application programs. IMS supports programs written in ADA, assembler, C, COBOL,
PL/I, VS PASCAL, and REXX.

Hierarchical versus Relational Databases

There are several types of database management systems, categorized generally by how
they logically store and retrieve data. The two most common types in use today are
relational and hierarchical. Each type has its advantages and disadvantages, and in many
organizations both types are used. Whether you choose a relational or hierarchical
database management system depends largely on how you intend to use the data being
stored.

Relational Database
In a relational database, data is stored in a table made up of rows and columns. A separate
table is created for logically related data, and a relational database may consist of
hundreds or thousands of tables.

Within a table, each row is a unique entity (or record) and each column is an attribute
common to the entities being stored. In the example database described in Table 1-1 on
page 1-9, Course No. has been selected as the key for each row. It was chosen because
each course number is unique and will be listed only once in the table. Because it is
unique for each row, it is chosen as the key field for that row. For each row, a series of

4
columns describe the attributes of each course. The columns include data on title,
description, instructor, and department, some of which may not be unique to the course.
An instructor, for instance, might teach more than one course, and a department may
have any number of courses. It is important early in design of a database to determine
what will be the unique, or key, data element.

Hierarchical Databases
Now let's look at the same data stored in a hierarchical format. This time the data is
arranged logically in a top-down format. In a hierarchical database, data is grouped in
records, which are subdivided into a series of segments. In the example Department
database on Figure 1-2 on page 1-8, a record consists of the segments Dept, Course, and
Enroll.

In a hierarchical database, the structure of the database is designed to reflect logical

dependencies-certain data is dependent on the existence of certain other data. Enrollment
is dependent on the existence of a course, and, in this case, a course is dependent on the
existence of a department. In a hierarchical database, the data relationships are defined.
The rules for queries are highly structured. It is these fixed relationships that give IMS
extremely fast access to data when compared to a relational database. Speed of access
and query flexibility are factors to consider when selecting a DBMS.

Strengths and Weaknesses

Hierarchical and relational systems have their strengths and weaknesses. The relational
structure makes it relatively easy to code requests for data. For that reason, relational
databases are frequently used for data searches that may be run only once or a few times
and then changed. But the query-like nature of the data request often makes the relational
database search through an entire table or series of tables and perform logical
comparisons before retrieving the data. This makes searches slower and more processing-
intensive. In addition, because the row and column structure must be maintained
throughout the database, an entry must be made under each column for every row in
every table, even if the entry is only a place holder-a null entry. This requirement places
additional storage and processing burdens on the relational system.

With the hierarchical structure, data requests or segment search arguments (SSAs) may
be more complex to construct. Once written, however, they can be very efficient,
allowing direct retrieval of the data requested. The result is an extremely fast database
system that can handle huge volumes of data transactions and large numbers of
simultaneous users. Likewise, there is no need to enter place holders where data is not
being stored. If a segment occurrence isn't needed, it isn't inserted.

The choice of which type of DBMS to use often revolves around how the data will be
used and how quickly it should be processed. In large databases containing millions of
rows or segments and high rates of access by users, the difference becomes important. A

5
very active database, for example, may experience 50 million updates in a single day. For
this reason, many organizations use relational and hierarchical DBMSs to support their
data management goals.

Sample Hierarchical Database

To illustrate how the hierarchical structure looks, we'll design two very simple databases
to store information for the courses and students in a college. One database will store
information on each department in the college, and the second will contain information
on each college student.

In a hierarchical database, an attempt is made to group data in a one-to-many

relationship. An attempt is also made to design the database so that data that is logically
dependent on other data is stored in segments that are hierarchically dependent on the
data. For that reason, we have designated Dept as the key, or root, segment for our
record, because the other data would not exist without the existence of a department. We
list each department only once. We provide data on each course in each department. We
have a segment type Course, with an occurrence of that type of segment for each course
in the department. Data on the course title, description, and instructor is stored as fields
within the Course segment. Finally, we have added another segment type, Enroll, which
will include the student IDs of the students enrolled in each course.

In Figure 1-2, we also created a second database called Student. This database contains
information on all the students enrolled in the college. This database duplicates some of
the data stored in the Enroll segment of the Department database. Later, we will construct
a larger database that eliminates the duplicated data. The design we choose for our
database depends on a number of factors; in this case, we will focus on which data we
will need to access most frequently,

The two sample databases, Department and Student, are shown in Figure 1-2. The two
databases are shown as they might be structured in relational form in Table 1-1, Table 1-
2, and Table 1-3 on page 1-9.

6
 Figure 1-2: Sample hierarchical databases for department and student.

Department Database
The segments in the Department database are as follows:

Dept Information on each department. This segment includes fields for the department
ID (the key field), department name, chairman's name, number of faculty, and
number of students registered in departmental courses.
Course This segment includes fields for the course number (a unique identifier), course
title, course description, and instructor's name.
Enroll The students enrolled in the course. This segment includes fields for student ID
(the key field), student name, and grade.
Student Database
The segments in the Student database are as follows:

Student Student information. It includes fields for student ID (key field), student name,
address, major, and courses completed.
Billing Billing information for courses taken. It includes fields for semester, tuition
due, tuition paid, and scholarship funds applied.

The dotted line between the root (Student) segment of the Student database and the Enroll
segment of the Department database represents a logical relationship based on data
residing in one segment and needed in the other. Logical relationships are explained in
detail in "The Role of Logical Relationships" on page 2-55.

7
Example Relational Structure
Tables 1-1, 1-2 and 1-3 show how the two hierarchical Department and Student databases
might be structured in a relational database management system. We have broken them
down into three tables-Course, Student, and Department. Notice that we have had to
change the way some data is stored to accommodate the relational format.

Course No. Course Title Description Instructor Dept ID

HI-445566 History 321 Survey course J. R. Jenkins HIST
MH-778899 Algebra 301 Freshman-level A.L. Watson MATH
BI-112233 Biology 340 Advanced course B.R. Sinclair BIOL

Table 1-1: Course database in relational table format.

Student ID Student Name Address Major

123456777 Jones, Bill 1212 N. Main History
123456888 Smith, Jill 225B Baker St Physics
123456999 Brown, Joe 77 Sunset St Zoology

Table 1-2: Student database in relational table format.

Dept ID Dept. Name Chairman Budget Code

HIST History J. B. Hunt L72
MATH Mathematics R. K. Turner A54
BIOL Biology E. M. Kale A25

Table 1-3: Department database in relational table format.

Design Considerations
Before implementing a hierarchical structure for your database, you should analyze the
end user's processing requirements, because they will determine how you structure the
database. To help you understand the business processing needs of the user, you can
construct a local view consisting of the following:

 list of required data elements

 controlling keys of the data elements
 data groupings for each process, reflecting how the data is used in
business practice
 mapping of the data groups that shows their relationships

8
In particular, you must consider how the data elements are related and how they will be
accessed. The topics that follow should help you in that process.

Normalization of Data
Even though you have a collection of data that you want to store in a database, you may
have a hard time deciding how the data should be organized. Normalization of data refers
to the process of breaking data into affinity groups and defining the most logical, or
normal, relationships between them. There are accepted rules for the process of data
normalization. Normalization usually is discussed in terms of form. Although there are
five levels of normalization form, it is usually considered sufficient to take data to the
third normalization form. For most uses, you can think of levels of normalization as the
following:

 First normal form. The data in this form is grouped under a

primary key-a unique identifier. In other words, the data occurs
only once for each key value.
 Second normal form. In this form, you remove any data that was
only dependent on part of the key. For example, in Table 1-1 on
page 1-9, Dept ID could be part of the key, but the data is really
only dependent on the Course No.
 Third normal form. In this form, you remove anything from the
table that is not dependent on the primary key. In Table 1-3, the
Department table, if we included the name of the University
President, it would occur only once for each Dept ID, but it is in no
way dependent on Dept ID. So that information is not stored here.
The other columns, Dept. Name, Chairman, and Budget Code, are
totally dependent on the Dept ID.

Example Database Expanded

At this point we have learned enough about database design to expand our original
example database. We decide that we can make better use of our college data by
combining the Department and Student databases. Our new College database is shown in
Figure 1-3.

9
 Figure 1-3: College database (combining department and student databases).

The following segments are in the expanded College database:

College The root segment. One record will exist for each college in the university.
The key field is the College ID, such as ARTS, ENGR, BUSADM, and
FINEARTS.
Dept Information on each department within the college. It includes fields for the
department ID (the key field), department name, chairman's name, number
of faculty, and number of students registered in departmental courses.
Course Includes fields for the course number (the key field), course title, course
description, and instructor's name.
Enroll A list of students enrolled in the course. There are fields for student ID (key
field), student name, current grade, and number of absences.
Staff A list of staff members, including professors, instructors, teaching
assistants, and clerical personnel. The key field is employee number. There
are fields for name, address, phone number, office number, and work
schedule.
Student Student information. It includes fields for student ID (key field), student
name, address, major, and courses being taken currently.

10
Billing Billing and payment information. It includes fields for billing date (key
field), semester, amount billed, amount paid, scholarship funds applied, and
scholarship funds available.
Academic The key field is a combination of the year and the semester. Fields include
grade point average per semester, cumulative GPA, and enough fields to list
courses completed and grades per semester.
Data Relationships
The process of data normalization helps you break data into naturally associated
groupings that can be stored collectively in segments in a hierarchical database. In
designing your database, break the individual data elements into groups based on the
processing functions they will serve. At the same time, group data based on inherent
relationships between data elements.

For example, the College database (Figure 1-3) contains a segment called Student.
Certain data is naturally associated with a student, such as student ID number, student
name, address, and courses taken, Other data that we will want in our College database-
such as a list of courses taught or administrative information on faculty members-would
not work well in the Student segment.

Two important data relationship concepts are one-to-many and many-to-many. In the
College database, there are many departments for each college (Figure 1-3 shows only
one example), but only one college for each department. Likewise, many courses are
taught by each department, but a specific course (in this case) can be offered by only one
department. The relationship between courses and students is one of many-to-many, as
there are many students in any course and each student will take a number of courses. A
one-to-many relationship is structured as a dependent relationship in a hierarchical
database: the many are dependent upon the one. Without a department, there would be no
courses taught: without a college, there would be no departments.

Parent and child relationships are based solely on the relative positions of the segments
in the hierarchy, and a segment can be a parent of other segments while serving as the
child of a segment above it. In Figure 1-3, Enroll is a child of Course, and Course,
although the parent of Enroll, is also the child of Dept. Billing and Academic are both
children of Student, which is a child of College. (Technically, all of the segments except
College are dependents.)

When you have analyzed the data elements, grouped them into segments, selected a key
field for each segment, and designed a database structure, you have completed most of
your database design. You may find, however, that the design you have chosen does not
work well for every application program. Some programs may need to access a segment
by a field other than the one you have chosen as the key. Or another application may need
to associate segments that are located in two different databases or hierarchies. IMS has
provided two very useful tools that you can use to resolve these data requirements:
secondary indexes and logical relationships.

11
Secondary indexes let you create an index based on a field other than the root segment
key field. That field can be used as if it were the key to access segments based on a data
element other than the root key. Logical relationships let you relate segments in separate
hierarchies and, in effect, create a hierarchic structure that does not actually exist in
storage. The logical structure can be processed as if it physically exists, allowing you to
create logical hierarchies without creating physical ones. We discuss both of these
concepts in greater detail in Chapter 2, "IMS Structures and Functions."

Hierarchical Sequence
Because segments are accessed according to their sequence in the hierarchy, it is
important to understand how the hierarchy is arranged. In IMS, segments are stored in a
top-down, left-to-right sequence (see Figure 1-4). The sequence flows from the top to the
bottom of the leftmost path or leg. When the bottom of that path is reached, the sequence
continues at the top of the next leg to the right.

Understanding the sequence of segments within a record is important to understanding

movement and position within the hierarchy. Movement can be forward or backward and
always follows the hierarchical sequence. Forward means from top to bottom, and
backward means bottom to top. Position within the database means the current location at
a specific segment.

Hierarchical Data Paths

In Figure 1-4, the numbers inside the segments show the hierarchy as a search path would
follow it. The numbers to the left of each segment show the segment types as they would
be numbered by type, not occurrence. That is, there may be any number of occurrences of
segment type 04, but there will be only one type of segment 04. The segment type is
referred to as the segment code.

To retrieve a segment, count every occurrence of every segment type in the path and
proceed through the hierarchy according to the rules of navigation:

 top to bottom
 front to back (counting twins)
 left to right

For example, if an application program issues a GET-UNIQUE (GU) call for segment 6
in Figure 1-4, the current position in the hierarchy is immediately following segment 6
(not 06). If the program then issued a GET-NEXT (GN) call, IMS would return segment
7.

As shown in Figure 1-4, the College database can be separated into four search paths:

 The first path includes segment types 01, 02, 03, and 04.

12
  The second path includes segment types 01, 02, and 05.
 The third path includes segment types 01, 06, and 07.
 The fourth path includes segment types 01, 06, and 08.

The search path always starts at 01, the root segment.

Figure 1-4: Sequence and data paths in a hierarchy.

Database Records
Whereas a database consists of one or more database records, a database record consists
of one or more segments. In the College database, a record consists of the root segment
College and its dependent segments. It is possible to define a database record as only a
root segment. A database can contain only the record structure defined for it, and a
database record can contain only the types of segments defined for it.

The term record can also be used to refer to a data set record (or block), which is not the
same thing as a database record. IMS uses standard data system management methods to
store its databases in data sets. The smallest entity of a data set is also referred to as a
record (or block). Two distinctions are important:

 A database record may be stored in several data set blocks.

13
  A block may contain several whole records or pieces of several
records.

In this article, we try to distinguish between database record and data set record where
the meaning may be ambiguous.

Segment Format
A segment is the smallest structure of the database in the sense that IMS cannot retrieve
data in an amount less than a segment. Segments can be broken down into smaller
increments called fields, which can be addressed individually by application programs.

A database record can contain a maximum of 255 types of segments. The number of
segment occurrences of any type is limited only by the amount of space you allocate for
the database. Segment types can be of fixed length or variable length. You must define
the size of each segment type.

It is important to distinguish the difference between segment types and segment

occurrences. Course is a type of segment defined in the DBD for the College database.
There can be any number of occurrences for the Course segment type. Each occurrence
of the Course segment type will be exactly as defined in the DBD. The only differences
in occurrences of segment types is the data contained in them (and the length, if the
segment is defined as variable length).

Segments consist of two major parts, a prefix and the data being stored. (SHSAM and
SHISAM database segments consist only of the data, and GSAM databases have no
segments.) The prefix portion of a segment is used to store information that IMS uses in
managing the database.

Prefix Data
segment delete counters size seq. data
code byte and field (key)
pointers field length varies,
1 byte 1 byte 2 based
4 bytes per bytes on a minimum and
element maximum size

Figure 1-5: Format of a variable-length segment.

Figure 1-6 shows the format of a fixed length segment. In the fixed-length segment, there
is no size field.

Prefix Data

14
segment delete counters size seq. data
code byte and field (key)
pointers field length is
1 byte 1 byte 2 bytes whatever
4 bytes per is specified for
element the segment

Figure 1-6: Format of a fixed-length segment.

The fields contained in an IMS database segment are described below. In the data
portion, you can define the following types of fields: a sequence field, data fields.

Segment IMS uses the segment code field to identify each segment type stored in a
Code database. A unique identifier consisting of a number from 1 to 255 is assigned
to each segment type when IMS loads the database. Segment types are
numbered in ascending sequence, beginning with the root segment as 1 and
continuing through all dependent segment types in hierarchic order.
Delete IMS uses this byte to track the status of a deleted segment. The space it
Byte occupied may (or may not) be available for use.
Counters and Pointers

This area exists in hierarchic direct access method (HDAM) and hierarchic indexed direct
access method (HIDAM) databases and, in some cases, hierarchic indexed sequential
access method (HISAM) databases. It can contain information on the following elements:

 Counters - Counter information is used when logical relationships

are defined. Logical relationships are discussed in detail in "The
Role of Logical Relationships" on page 2-55.
 Pointers - Pointers consist of one or more addresses of segments
pointed to by this segment. Pointers are discussed in detail in
"Pointer Types" on page 2-37.

Size Field

For variable-length segments, this field states the size of the segment, including the size
field (2 bytes).

Sequence (Key) Field

15
The sequence field is often referred to as the key field. It can be used to keep occurrences
of a segment type in sequence under a common parent, based on the data or value entered
in this field. A key field can be defined in the root segment of a HISAM, HDAM, or
HIDAM database to give an application program direct access to a specific root segment.
A key field can be used in HISAM and HIDAM databases to allow database records to be
retrieved sequentially. Key fields are used for logical relationships and secondary
indexes.

The key field not only can contain data but also can be used in special ways that help you
organize your database. With the key field, you can keep occurrences of a segment type
in some kind of key sequence, which you design. For instance, in our example database
you might want to store the student records in ascending sequence, based on student ID
number. To do this, you define the student ID field as a unique key field. IMS will store
the records in ascending numerical order. You could also store them in alphabetical order
by defining the name field as a unique key field.

Three factors of key fields are important to remember:

 The data or value in the key field is called the key of the segment.
 The key field can be defined as unique or non-unique.
 You do not have to define a key field in every segment type

Data

You define data fields to contain the actual data being stored in the database. (Remember
that the sequence field is a data field.) Data fields, including sequence fields, can be
defined to IMS for use by applications programs. Field names are used in SSAs to qualify
calls. See "Segment Search Argument" on page 3-22 for more information.

Segment Definitions

16
In IMS, segments are defined by the order in which they occur and by their relationship
with other segments:

Root segment The first, or highest segment in the record. There can be only one root
segment for each record. There can be many records in a database.
Dependent All segments in a database record except the root segment.
segment
Parent segment A segment that has one or more dependent segments beneath it in the
hierarchy.
Child segment A segment that is a dependent of another segment above it in the
hierarchy.
Twin segment A segment occurrence that exists with one or more segments of the same
type under a single parent.
Segment Edit/Compression
IMS provides a Segment Edit/Compression Facility that lets you encode, edit, or
compress the data portion of a segment in full-function or Fast Path DEDB databases.
You can use the Edit/Compression Facility to perform the following tasks:

 encode data-make data unreadable to programs that do not have the

edit routine to see it in decoded form
 edit data-allow an application program to receive data in a format
or sequence other than that in which it is stored
 compress data-use various compression routines, such as removing
blanks or repeating characters, to reduce the amount of DASD
required to store the data

The Segment Edit/Compression Facility allows two types of data compression:

 data compression-compression that does not change the content or

relative position of the key field. For variable-length segments, the
size field must be updated to show the length of the compressed
segment. For segments defined to the application as fixed-length, a
2-byte field must be added at the beginning of the data portion by
the compression routine to allow IMS to determine storage
requirements.
 key compression-compression of data within a segment that can
change the relative position, value, or length of the key field and
any other fields except the size field. In the case of a variable-
length segment, the segment size field must be updated by the
compression routine to indicate the length of the compressed
segment.

Pointers

17
IMS uses pointers to locate related segments in a database. Pointers are physically stored
in the prefix portion of a segment. Each pointer contains the relative byte address (RBA)
of another segment. When the database is loaded, IMS creates pointers according to the
DBD you specified. During subsequent processing, IMS uses pointers to traverse the
database (navigate from segment to segment). IMS automatically maintains the contents
of pointers when segments are added, deleted, and updated.

Control Blocks
When you create an IMS database, you tell IMS what the physical structure of the
database will be-the segment names, segment lengths, the fields that each segment will
contain, the segment's position in the hierarchy, and so on. You also tell IMS what
segments can be accessed, whether they can be updated, deleted, or new ones inserted,
and other access control specifications. You do this through a series of specifications that
will be contained in control blocks, also called DL/I control blocks, because the DL/I
command language is used perform the data manipulation functions. Control blocks do
just what the name implies-they control the way in which IMS will structure and access
the data stored in the database.

The data structure and control specifications you write will be contained in three major
control blocks:

 DBD, which describes the database organization and access

methods
 PSB, which describes an application program's view and use of the
database
 ACB, which combines information from the DBD and PSB

Database Description

18
A database description (DBD) is a series of macro statements that define the type of
database, all segments and fields, and any logical relationships or indexing. DBD macro
statements are submitted to the DBDGEN utility, which generates a DBD control block
and stores it in the IMS.DBDLIB library for use when an application program accesses
the database.

Figure 2-1 shows a sample DBD for an HDAM database. When the DBD is assembled
and link-edited, a load module is created and stored in an IMS DBDLIB library. In the
DBDGEN process, each segment is assigned a segment code, a one-byte value in
ascending sequence, that is used to identify the segment in physical storage.

In the DBD statement, an IMS access method and a system access method are specified
(HDAM, OSAM in this example). The roles of the two access methods are discussed in
greater detail in "Access Methods."

Fields within each segment can be defined as key fields or non-key search fields for use
by application programs in retrieving segments. A key field is used for searching and
sequencing. Each segment occurrence will be placed in a database record according to the
sequence of the key fields. In Figure 2-1, the statement for field COLLID (college ID) is
defined as a sequence field (SEQ) and as unique (U). Only fields that will be used in
SSAs or that are key fields must be defined in the DBD.

Figure 2-1: DBD for an HDAM database with secondary index.

The DBD contains the following statements:

19
DATASET Defines the DDname and block size of a data set. One DATASET
statement is required for each data set group.
SEGM Defines a segment type, its position in the hierarchy, its physical
characteristics, and its relationship to other segments. Up to 15 hierarchic
levels can be defined. The maximum number of segment types for a
single database is 255.
FIELD Defines a field within a segment. The maximum number of fields per
segment is 255. The maximum number of fields per database is 1,000.
LCHILD Defines a secondary index or logical relationship between two segments.
It also is used to define the relationship between a HIDAM index and the
root segment of the database.
XDFLD Used only when a secondary index exists. It is associated with the target
segment and specifies the name of the indexed field, the name of the
source segment, and the field to be used to create the secondary index.
See "The Role of Secondary Indexes" for more information.
DBDGEN Indicates the end of statements defining the DBD.
END Indicates to the assembler that there are no more statements.

DBD Names the database being described and specifies its organization.

Program Specification Block

The program specification block (PSB) is a series of macro statements that describe the
data access characteristics of an application program. Among other things, the PSB
specifies:

 all databases that the application program will access

 which segments in the database that the application program is
sensitive to
 how the application program can use the segments (inquiry or
update)

A PSB consists of one or more program communication blocks (PCBs). The PCB
specifies the segments to which the application program can have access and the
processing authorization for each segment. You define a PCB for each database (or each
view of the database) accessed by the application program. In the application program
host code, you specify the PSB for that application.

For each PCB, you must code a corresponding block in the application program's linkage
section. These data communication I/O areas are used for communication between IMS
and the application. (There are actually two types of PCBs, a database PCB and a data
communications PCB.)

PCBs contain SENSEG (sensitive segment) and SENFLD (sensitive field) statements.
These statements allow you to specify which segments and fields the application program

20
will "see." If you define a segment as sensitive, it will be accessible to the application. If
you do not, it will be ignored by the application program. This gives you great flexibility
in creating the views that application programs will have of your database.

The PSB macros are used as input to the PSBGEN utility, a macro assembler that
generates a PSB control block. The PSB control block is stored in the IMS.PSBLIB
library for use during database processing. There can be many PSBs for one DBD.

Figure 2-2 shows the structure of PSB generation input.

Figure 2-2: Sample PSBGEN generation input.

The PSB statements include the following:

21
PCB Defines the database to be accessed by the application program. The
statement also defines the type of operations allowed by the application
program. Each database requires a separate PCB statement. PSB
generation allows for up to 255 database PCBs (less the number of
alternate PCBs defined).
SENSEG Defines the segment types to which the application program will be
sensitive. A separate SENSEG statement is required for each segment
type. If a segment is defined as sensitive, all the segments in the path from
the root to that segment must also be defined as sensitive. Specific
segments in the path can be exempted from sensitivity by coding
PROCOPT=K in the SENSEG statement.
SENFLD Defines the fields in a segment type to which the application program is
sensitive. Can be used only in association with field-level sensitivity. The
SENFLD statement must follow the SENSEG statement to which it is
related.
PROCOPT Defines the type of access to a database or segment. PROCOPTs can be
used on the PCB or SENSEG statements. Primary PROCOPT codes are as
follows:
G read only
R replace, includes G
I insert
D delete, includes G
A get and update, includes G, R, I, D
K used on SENSEG statement; program will have key-only sensitivity
to this segment
L load database
Secondary PROCOPT codes are as follows:
E exclusive use of hierarchy or segments
O get only, does not lock data when in use
P must be used if program will issue path call using the D command
code
S sequential (LS is required to load HISAM and HIDAM databases; GS
gets in ascending sequence)
Application Control Block
Application control blocks (ACBs) are created by merging information from PSBs and
DBDs. For online applications, ACBs must be prebuilt using the ACB maintenance
utility. For batch applications, ACBs can be built dynamically using DBDLIB and
PSBLIB as input (PARM=DL/I) or the prebuilt ACB from ACBLIB can be used
(PARM=DBB). The ACBGEN process is shown in Figure 2-3.

22
 Figure 2-3: ACB generation.

Prebuilt ACBs require less time to schedule an application program and use less storage.
The ACB maintenance utility also provides some error-checking capability.

ACBs can be built for all PSBs, for particular PSBs, or for all PSBs that reference a
particular DBD. Prebuilt ACBs are stored in the IMS.ACBLIB library. During ACB
generation, the ACB maintenance utility must have exclusive control of the
IMS.ACBLIB. Because of this, the utility must be executed using an IMS.ACBLIB that
is not currently allocated to an active IMS system. You can execute the ACB
maintenance utility against an inactive copy of ACBLIB, then use the IMS Online
Change function to make the new members available to an active IMS online system.

Access Methods
IMS accesses data after it has been retrieved from DASD and places it in a buffer pool in
memory. The task of retrieving the data from DASD is performed by one of several
system access methods. These should not be confused with IMS access methods such as
HSAM, HISAM, HDAM, HIDAM, and so on. IMS access methods are actually types of
database organizations. In IMS terminology, however, databases often are referred to by
their IMS access method. An IMS database definition must always specify an IMS access
method and a system access method. In some cases, you can choose the type of system
access method you want to use. In other cases, the system access method is dictated by
the IMS access method. HISAM, for instance, uses only VSAM.

23
Both the system and IMS access methods are used for IMS database retrieval and update.
Application programs specify the data to retrieve and make a DL/I call to the system
access method. The system access method returns a block of data to IMS. The IMS
access method then locates the data within the block and passes it to the application
program. The IMS database types and their access methods are shown in Table 2-1.

Table 2-1: IMS database and system access types.

VSAM
In the discussion on HISAM and HIDAM databases later in this chapter, you will find
reference to VSAM, particularly in association with VSAM key-sequenced data sets
(KSDSs) and entry-sequenced data sets (ESDSs), because of the way in which certain
databases use these data sets. Before discussing the various IMS access methods, it is
helpful to have an understanding of VSAM's role in the storage and retrieval of data.
VSAM performs the physical I/O of data for IMS. It retrieves the data from DASD and
places it in the main storage buffer pool for use by IMS. When processing has been
completed, VSAM returns the data to DASD, where it is stored until needed again. To
perform these functions, VSAM uses its own set of data storage and retrieval structures.

A VSAM data set consists of a set of records. The records are grouped into control
intervals (CIs), which in turn are grouped into larger groupings called control areas
(CAs). The layout of a control interval is shown in Figure 2-4.

Figure 2-4: VSAM control interval layout.

A VSAM CI consists of records, free space, and control information. You can determine
the size of a CI or let VSAM do it for you. When you define the size of a CI for a data
set, all CIs in the data set will be the same size. When you define the CI, you also
determine the percentage of free space to be designated. You will attempt to create
enough free space to avoid CI splits while not using so much free space that you waste
DASD. CI splits occur when there is no room to insert another record; consequently,
VSAM moves half of the records from the CI where the record was to be inserted to a
new CI. CI splits are a costly overhead, especially in high-activity systems. (You can
correct CI splits by reorganizing the database.)

24
CIs are grouped inside a control area (CA). The goal is to have enough unused CIs to
allow new data to be added without causing a CA split. CA splits are more processing-
intensive than CI splits. On the other hand, you don't want to waste DASD by defining
too many unused CIs. For information on calculating space requirements, refer to the
IBM manuals IMS/ESA Administration Guide: Database Manager and IMS/ESA
Administration Guide: System.

The control information portion of the CI contains two types of fields:

 The record definition field (RDF) contains information on the

records stored in the CI, their length, and whether they are fixed or
variable length.
 The control interval definition field (CIDF) contains information
on the CI itself. It keeps track of the amount of free space available
and where the free space is located relative to the beginning of the
CI. CIs have only one CIDF but may have a variable number of
RDFs, depending on whether the CI contains fixed-length or
variable-length records or a combination of the two.

Sequence Sets and Indexes

For KSDSs, VSAM keeps track of all CAs and CIs through the use of two levels of
indexing-the sequence set and the index set.

VSAM maintains a sequence set record for each CA in the data set. The sequence set
record contains an entry for each CI in the CA. Each entry contains the key of the highest
record in the CI and a pointer to the CI. The index contains an entry for each sequence set
record. This gives the index an entry for each CA, since there is a sequence set for every
CA. Each index entry contains the key of the highest record in its CA and a pointer to the
sequence set record for that CA.

By following the values of record keys from index to sequence set to CA to CI, VSAM
can locate any record in the data set. When VSAM reaches the CI, it can obtain record
information from the CIDF and RDFs of the CI. The example in Figure 2-5 illustrates this
concept.

25
26
 Figure 2-5: Structure of VSAM index set and sequence set records.

Key-Sequenced Data Sets

The data sets we have described so far have been key-sequenced data sets (KSDSs). You
can see that the name derives from the way VSAM stores and retrieves records based on
the record key.

VSAM can retrieve the records in a KSDS in a number of ways. The simplest and most
obvious way is to read each record in the logical order (lowest key to highest key) in
which they are stored. This is called sequential retrieval. Obviously, this method has
limitations if you want only some of the records or if you want them in other than key
sequence order.

VSAM can use the key sequence retrieval method to return only a portion of the records.
This method is called keyed sequential retrieval or skip sequential retrieval. With this
method, you specify the keys of the records you want retrieved, but they must be in
ascending order. Another method, addressed sequential retrieval, locates the records to be
retrieved by their RBA (relative byte address-the number of bytes from the beginning of
the data set to the beginning of the record). You must supply the RBAs to VSAM.
Addressed sequential retrieval can be used with KSDSs but is primarily designed for
ESDSs.

VSAM can also retrieve KSDS records directly. You provide the record key, and VSAM
uses the index set and sequence set to navigate its way to the correct CI and to the record
you requested. With this method, you can retrieve records in any order.

VSAM can retrieve a record directly by its RBA. This method, addressed direct retrieval,
like addressed sequential retrieval, is designed primarily for ESDSs.

Entry-Sequenced Data Sets

Entry-sequenced data sets (ESDSs) are stored in the order in which they are loaded,
rather than by key sequence. With ESDSs, VSAM does not create an index and does not
reserve free space. No index is needed because there are no record keys to track.
Likewise, free space is not needed because the next record added to the data set is stored
at the end of the existing set of records. If a record is too large to fit in the CI being
loaded, VSAM creates a new CI and puts the record there. VSAM does not attempt to use
space that may be left at the end of each CI.

ESDSs are retrieved only by RBA using either addressed sequential retrieval or addressed
direct sequential retrieval. With addressed sequential retrieval, you give VSAM the RBA
of the first record. It retrieves the succeeding records by computing their RBA based on
the record length field of each record's RDF. With the addressed direct method, you must
supply VSAM with the RBA of each record you want.

27
Because of their storage and retrieval mechanisms, ESDSs have certain limitations that
make them less attractive for many applications. Although updating is relatively simple,
adding and deleting records proves more difficult. With updating, you read the record,
enter changes, and rewrite it, without changing the record length. To delete, you read the
record and mark it for deletion, but VSAM does not physically delete the record or
reclaim the unused space. To add a record, you must add it at the end of the data set.

QSAM
The queued sequential access method (QSAM) processes records sequentially from the
beginning of the data set. QSAM groups logical records into physical blocks before
writing them to storage and handles the blocking and deblocking of records for you.
QSAM is typically used by application programs that retrieve or create a single member
at a time within a partitioned data set (PDS). The characteristics of a member of a PDS-
which is a collection of sequentially organized members-are the same as those of a
sequential data set.

BSAM
The basic sequential access method (BSAM) allows you to read and write physical
records only. It does not perform blocking or deblocking of records. With BSAM, you
can begin processing a data set at any point

BDAM
The basic direct access method (BDAM) allows you to write or retrieve records directly
by address, using the physical track, relative track, or relative record number.

OSAM
The overflow sequential access method (OSAM) was developed for use with DL/I
databases. It combines many features of sequential access methods and of BDAM. To the
operating system, an OSAM data set appears the same as a sequential data set. An OSAM
data set can be read with BSAM or QSAM. OSAM allows direct access to records.

Database Organizations
The nine types of databases supported by IMS can be grouped by their IMS access
method. Hierarchic sequentially accessed databases include

 HSAM
 SHSAM
 HISAM
 SHISAM

28
  GSAM

Hierarchic direct databases include

 HDAM
 HIDAM

Fast Path databases provide fast access with limited functionality

 DEDB
 MSDB

Hierarchic Sequential Databases

The earliest IMS database organization types were based on sequential storage and access
of database segments. Hierarchic sequential databases share certain characteristics.
Compared to hierarchic direct databases, which we will discuss later, hierarchic
sequential databases are of simpler organization. The root and dependent segments of a
record are related by physical adjacency. Access to dependent segments is always
sequential. Deleted dependent segments are not physically removed but are marked as
deleted. Hierarchic sequential databases can be stored on tape or DASD.

HSAM
In a hierarchic sequential access method (HSAM) database, the segments in each record
are stored physically adjacent. Records are loaded sequentially with root segments in
ascending key sequence. Dependent segments are stored in hierarchic sequence. The
record format is fixed-length and unblocked. An HSAM database is updated by rewriting
the entire database. Although HSAM databases can be stored on DASD or tape, HSAM is
basically a tape-based format. Figure 2-6 shows an HSAM database record and segment
format.

Figure 2-6: HSAM database segment structure.

29
IMS identifies HSAM segments by creating a two-byte prefix consisting of a segment
code and a delete byte at the beginning of each segment. HSAM segments are accessed
through two operating system access methods:

 basic sequential access method (BSAM)

 queued sequential access method (QSAM)

QSAM is always used as the access method when the system is processing online, but
you can specify either method for batch processing through the PROCOPT parameter in
the PCB.

Entry to an HSAM database is through GET UNIQUE (GU) or GET NEXT (GN) calls.
The first call starts at the beginning of the database and searches sequentially through the
records until it locates the requested segment. Subsequent calls use that position as the
starting point for calls that process forward in the database.

HSAM databases are limited by the strictly sequential nature of the access method.
DELETE (DLET) and REPLACE (REPL) calls are not allowed, and INSERT (ISRT)
calls are allowed only during the database load. Field-level sensitivity is provided, but
HSAM databases are limited in the number of IMS options they can use.

Because of the numerous limitations, HSAM databases see limited use and are reserved
primarily for applications that require sequential processing only.

SHSAM
A simple HSAM (SHSAM) database contains only one type of segment-a fixed-length
root segment. Because there is no need for a segment code and deletes are not allowed,
there is no need for a prefix portion of a SHSAM database segment. Because they contain
only user data, SHSAM databases can be accessed by BSAM and QSAM. The only DL/I
calls used with SHSAM databases are the GET calls. Like HSAM, SHSAM database
segments can be deleted or inserted only during a reload.

HISAM
The hierarchic indexed sequential access method (HISAM) database organization adds
some badly needed capabilities not provided by HSAM. Like HSAM, HISAM databases
store segments within each record in physically adjacent sequential order. Unlike HSAM,
each HISAM record is indexed, allowing direct access to each record. This eliminates the
need to read sequentially through each record until the desired record is found. As a
result, random data access is considerably faster than with HSAM. HISAM databases
also provide a method for sequential access when that is needed.

A HISAM database is stored in a combination of two data sets. The database index and
all segments in a database record that fit into one logical record are stored in a primary

30
data set that is a VSAM KSDS. Remaining segments are stored in the overflow data set,
which is a VSAM ESDS. The index points to the CI containing the root segment, and the
logical record in the KSDS points to the logical record in the ESDS, if necessary.

If segments remain to be loaded after the KSDS record and the ESDS record have been
filled, IMS uses another ESDS record, stores the additional segments there, and links the
second ESDS record with a pointer in the first record. You determine the record length
for the KSDS and the ESDS when you create the DBD for the database.

If segments are deleted from the database, they are still physically present in the correct
position within the hierarchy, but a delete byte is set to show that the record has been
deleted. Although the segment is no longer visible to the application program, it remains
physically present and the space it occupies is unavailable until the database is
reorganized. The only exception to this is the deletion of a root segment where the logical
record in the VSAM KSDS is physically deleted and the index entry is removed; any
VSAM ESDS logical records in the overflow data set are not be deleted or updated in any
way.

Inserting segments into a HISAM database often entails a significant amount of I/O
activity. Because IMS must enforce the requirement for segments to be physically
adjacent and in hierarchic order, it will move existing segments within the record or
across records to make room for the insertion; however, any dependent segments are not
flagged as deleted. To facilitate indexing, HISAM databases must be defined with a
unique sequence field in each root segment. The sequence fields are used to construct the
index.

HISAM databases are stored on DASD, and data access can be much faster than with
HSAM databases. All DL/I calls can be used against a HISAM database. Additionally,
HISAM databases are supported by a greater number of IMS and MVS options.

HISAM databases work well for data that requires direct access to records and sequential
processing of segments within each record.

Figure 2-7 shows the database structure for HISAM. Notice that four ESDS records have
been used in loading one logical record. The arrows represent pointers.

31
Figure 2-7: HISAM database structure.

32
HISAM Segment Structure
Figure 2-8 shows the HISAM segment structure.

Figure 2-8: HISAM segment structure.

A HISAM segment contains the following fields:

Segment 1 byte. The segment code byte contains a one-byte unsigned binary number
Code that is unique to the segment type within the database. The segments are
numbered in hierarchic order, starting at 1 and ending with 255 (X'01' through
X'FF').
Delete 1 byte. The delete byte contains a set of flags.
Byte
Counters and Pointers
The appearance of this area depends on the logical relationship status of the segment:

o If the segment is not a logical child or logical parent, this area is omitted.
o If the segment is a logical child, and if a direct pointer (see "Pointer
Types") is specified (the logical parent must be in an HD database), the
four-byte RBA of the logical parent will be present.
o If the segment is a logical parent and has a logical relationship that is
unidirectional or bidirectional with physical pairing, a four-byte counter
will exist.

If the segment is a logical parent and has one or more logical relationships that are
bidirectional with virtual pairing, then for each relationship there is a four-byte RBA
pointer to the first logical child segment (a logical child first pointer) and, optionally, a
four-byte RBA pointer to the last logical child segment (a logical child last pointer),
depending on whether you specified LCHILD=SNGL or LCHILD=DBLE in the DBD.

33
There is only one counter in a segment, but there can be multiple logical child first (LCF)
and logical child last (LCL) pointers. The counter precedes the pointers. The pointers are
in the order that the logical relationships are defined in the DBD, with a logical child first
pointer before a logical child last pointer.

Figure 2-9 shows a segment with multiple logical child pointers.

Figure 2-9: Multiple logical child pointers in a segment.

Data

The length of the data area (which is specified in the DBD) can be a fixed length or a
variable length. For a logical child segment with symbolic keys (PARENT=PHYSICAL
on the SEGM statement), the concatenated key of the logical parent will be at the start of
the segment.

If the segment is variable length, the first two bytes of the data area are a hexadecimal
number that represents the length of the data area, including the two-byte length field.

SHISAM
As is the case with SHSAM, a simple HISAM (SHISAM) database contains only a root
segment, and its segment has no prefix portion. SHISAM databases can use only VSAM
as their access method. The data must be stored in a KSDS. All DL/I calls can be used
with SHISAM databases, and their segments can be accessed by DL/I calls and VSAM
macros.

GSAM
Generalized sequential access method (GSAM) databases are designed to be compatible
with MVS data sets. They are used primarily when converting from an existing MVS-
based application to IMS because they allow access to both during the conversion
process. To be compatible with MVS data sets, GSAM databases have no hierarchy,
database records, segments, or keys. GSAM databases can be based on the VSAM or
QSAM/BSAM MVS access methods. They can have fixed-length or variable-length
records when used with VSAM or fixed-length, variable-length, or undefined-length
records when used with QSAM/BSAM.

34
Hierarchic Direct Databases
Hierarchic direct access method (HDAM) and hierarchic indexed direct access method
(HIDAM) databases are referred to collectively as HD databases. The hierarchic direct
databases were developed to overcome some of the deficiencies of sequential access
databases. HD databases share these characteristics:

 Pointers are used to relate segments.

 Deleted segments are physically removed.
 VSAM ESDS or OSAM data sets are used for storage.
 HD databases are stored on DASD.
 HD databases are of a more complex organization than
sequentially organized databases.

The following sections discuss HDAM, PHDAM, HIDAM and PHIDAM database
organizations. Because pointers play such an integral role in direct access databases, they
are referenced frequently in the text. Pointers are four-byte address values that give the
offset from the beginning of the data set of the segment being addressed. They tie the
segments together without the need for segments to be physically adjacent. Segments can
be inserted or deleted without the need to move other segments. There are different types
of pointers. Pointers are discussed in greater detail in "Pointer Types" below.

HDAM
HDAM databases are typically used when you need fast access to the root segment of the
database record, usually by direct access. In a hierarchic direct access method (HDAM)
database, the root segments of records are randomized to a storage location by an
algorithm that converts a root's key into a storage location. No index or sequential
ordering of records or segments is involved. The randomizing module reads the root's key
and, through an arithmetic technique, determines the storage address of the root segment.
The storage location to which the roots are randomized are called anchor points or root
anchor points (RAPs). The randomizing algorithm usually attempts to achieve a random
distribution of records across the data set. Theoretically, randomizing the location of
records minimizes the number of accesses required to retrieve a root segment.

The randomizing technique results in extremely fast retrieval of data, but it usually does
not provide for sequential retrieval of records. This can be achieved in HDAM databases
through the use of secondary indexes or by using a physical-key-sequencing randomizer
module.

The advantage of HDAM is that it does not require reading an index to access the
database. The randomizing module provides fast access to root segments and to the paths
of dependent segments. It uses only the paths of the hierarchy needed to reach the
segment being accessed, further increasing access speed. The disadvantage is that you

35
cannot process HDAM databases in key sequence unless the randomizing module stores
root segments in physical key sequence.

An HDAM database consists of one data set split into two parts: the root addressable area
(RAA) and the overflow area. The data set can be a VSAM ESDS or an OSAM data set.
You specify which access method to use in the DBD ACCESS parameter.

In designing an HDAM database, you decide the size of the RAA and the number of CIs
(or blocks, if you are using OSAM) that it will be broken down into. Within a CI or
block, you define the number of Raps The randomizer uses these parameters in
establishing a storage location for the root segment of the record. The CI does not contain
just RAAs and Raps It also is used for storage of the record's dependent segments. Each
CI begins with a free space element anchor point (FSEAP) area. The FSEAP is used to
locate free or unused space in the block. When IMS inserts new segments in the block, it
updates the FSEAP.

Figure 2-10 shows how a record appears in an HDAM database.

36
Figure 2-10: HDAM database structure.

37
Three CIs are in the RAA, and four CIs are in the overflow area. Together, they make up
the data set. Each CI in the RAA contains two Raps In the example, the College record
randomized to the second RAP in the second CI in the data set. The RAP does not
contain the root segment. It contains a four-byte pointer that contains the address of the
root segment.

After an initial load, segments within a database record are very likely to be grouped
together in blocks/CIs in hierarchic order. After update activity, this may not be the case.

To insert a root segment, IMS invokes the HDAM randomizer that has been specified in
the DBD. This determines the RAP from which the root must be chained.

When a segment has been inserted in an HDAM database, the segment is never moved so
that all the direct address pointers are preserved. The example assumes physical child
first pointers and twin forward pointers are specified for all segment types. If, as in the
case under consideration, there are more segments in the database record at initial load
than the BYTES parameter in the DBD will allow to be inserted in the RAA, all other
segments will be inserted into overflow. This is also true for multiple inserts of segments
within the same database record during the same synchronization point. If the database
were to use multiple data set groups, each secondary data set group would have the
format of the overflow part of an HDAM database.

If segments are deleted from the database segment, they are physically deleted from the
data set and the space is designated as free space.

Bit Maps
In HD databases, bit maps are used to keep track of free space. A bit map is a string of
bits that indicate whether enough space is available in a CI or OSAM block to contain an
occurrence of the longest segment defined for the data set. In a VSAM ESDS, the bit map
is located in the second CI of the data set. (The first CI is reserved.) In OSAM, bit maps
are put in the first block of the first extent of the data set.

As you read the bits in a bit map from left to right, they reflect the status of the
corresponding CI or block following the bit map. The bits are set as follows:

 0 if not enough space exists in the CI or block

 1 if there is adequate space for the longest segment specified for
the data set.

For example, if the first bit is set to 1, the first CI or block following the block containing
the bit map will have space available. If the third bit in the bit map is set to 0, the third CI
or block following that containing the bit map will not have sufficient space available,
and so on. As data is added and new CIs are created, the number of CIs may reach the
size limit of the bit map. If so, another bit map is created and the process repeated for CIs
that are added subsequently.

38
Free Space Element Anchor Point
Another specialized field, the free space element anchor point (FSEAP), is used in
determining the availability of free space within a CI or block. As shown in Figure 2-10,
the FSEAP is located at the beginning of each CI or OSAM block in a data set. An
FSEAP is made up of two 2-byte fields. The first field contains the offset, in bytes, to the
first free space element (FSE) in the block. An FSE is associated with each area of free
space within the block or CI. The FSEs in a CI are chained together using pointers. The
second field in the FSEAP tells whether this block or CI contains a bit map.

Free Space Element

In addition to an FSEAP, each OSAM block or VSAM CI contains free space elements
(FSEs) that provide information about the free space available in the block. The FSE
makes up the first eight bytes of each area of free space. It consists of the following
fields:

 Free space chain pointer (CP). This 2-byte field gives the offset in
bytes to the beginning of the next FSE in the block or CI. If it is
the last FSE in the block, it is set to zero.
 Available length field (AL). This 2-byte field gives the length of
the free space area, including the length of the FSE.
 Task ID field (ID). This 4-byte field contains the task ID of the
program that freed the space. This field is used to allow a program
to reuse the same space during a specified period without
contending with other programs for the space.

PHDAM
PHDAM databases are partitioned HDAM databases. Each PHDAM database is divided
into a maximum of 1001 partitions which can be treated as separate databases. A
PHDAM database is also referred to as a High Availability Large Database (HALDB).

HIDAM
Unlike HDAM, HIDAM databases use an index to locate root segments. HIDAM
databases are typically used when you would like to access database records randomly
and sequentially and also access segments randomly within a record. The index and the
database are stored in separate data sets. The index is stored as a single VSAM KSDS.
The database is stored as a VSAM ESDS or OSAM data set. The index stores the value
of the key of each root segment, with a four-byte pointer that contains the address of the
root segment.

39
The root segment locations in the index are stored in sequential order, allowing HIDAM
databases to be processed directly or sequentially. A disadvantage of HIDAM databases
is that the additional step required to scan an index makes access slower than with
HDAM databases.

When you access a record by root key, IMS searches for the key in the index and uses the
pointer to go directly to the record. If the PTR =TB or PTR=HB (twin backward pointer
or hierarchic backward pointer) parameter is defined for the root, the root segments are
chained together in ascending order. Sequential processing is done by following this
pointer chain. In HIDAM, Raps are generated only if you specify the PTR=T or PTR=H
(twin pointer or hierarchic pointer) parameter for the root. When either of these pointer
parameters is defined, IMS puts one RAP at the beginning of the CI or block. Root
segments within the CI or block are chained by pointers from the most recently inserted
back to the first root on the RAP. The result is that the pointers from one root to the next
cannot be used to process roots sequentially. Sequential processing must be performed by
using key values, which requires the use of the index and increases access time. For this
reason, you should specify PTR=TB or PTR=HB for root segments in HIDAM databases.

Figure 2-11 shows how the database record exists in a HIDAM database.

40
Figure 2-11: HIDAM database structure.

41
After an initial load, segments within a database record are stored physically in
blocks/CIs in hierarchic order. After update activity, this may not be the case.

When a segment has been inserted in a HIDAM database, the segment is never moved to
preserve all the direct address pointers. The example assumes that physical child first
pointers and twin forward pointers are specified for all segment types.

If segments are deleted from the database segment, they are physically deleted from the
data set, and the space is designated as free space. If the database has multiple data set
groups, each secondary data set group has the format of the main part of the HIDAM
database.

PHIDAM
PHIDAM databases are partitioned HIDAM databases. Each PHIDAM database is
divided into a maximum of 1001 partitions which can be treated as separate databases. A
PHIDAM database is also referred to as a High Availability Large Database (HALDB).

HDAM/HIDAM Segment Structure

Figure 2-12 shows the HDAM/HIDAM segment structure.

Figure 2-12: HDAM/HIDAM segment structure.

An HDAM/HIDAM segment contains the following fields:

Segment 1 byte. The segment code byte contains a one-byte unsigned binary number
Code that is unique to the segment type within the database. The segments are
numbered in hierarchic order, starting at 1 and ending with 255 (X'01' through
X'FF').
Delete 1 byte. The delete byte contains a set of flags.
Byte

Counters and Pointers

42
The following four-byte fields can be in this area and, if present, will occur in the
following order:

Counter

If the segment has a logical relationship that is unidirectional or

bidirectional with physical pairing, a four-byte counter will exist.

Hierarchic or Physical Twin Pointers

A hierarchic forward pointer or a twin forward pointer must be present

in the segment prefix, unless PTR=NOTWIN was specified in the SEGM
statement. Hierarchic backward pointers or twin backward pointers can
also be present (PTR=HB or PTR=TB on SEGM statement).

Physical Parent Pointer

This pointer will be present if the segment is a logical child or has a

logical child below it in the hierarchy. It will also be generated if the
segment is a logical parent or has a logical parent below it in the
hierarchy.

It is also present in any segments that are target segments for a

secondary index or that lie on the hierarchical paths between the root
segment and any target segments.

Logical Twin Pointers

A logical twin forward pointer and a logical twin backward pointer exist
only in a logical child segment with a bidirectional logical relationship
that is virtually paired. A logical twin backward pointer will be present
if LTWINBWD is specified on the SEGM statement of the logical child
segment.

Logical Parent Pointer

A logical child segment can have a direct pointer to its logical parent
(PHYSICAL specified on SEGM statement) if the logical parent is in an
HD database.

Logical Child Pointers

43
If the segment is a logical parent and has one or more logical
relationships that are bidirectional with virtual pairing, for each
relationship there is a four-byte RBA pointer to the first logical child
segment (a logical child first pointer). There can also be a four-byte
RBA pointer to the last logical child segment (a logical child last
pointer), depending on whether you specified LCHILD=SNGL or
LCHILD=DBLE in the DBD. The pointers are in the order that the
logical relationships are defined in the DBD, with a logical child first
pointer before a logical child last pointer.

Physical Child Pointers

If physical pointers rather than hierarchical pointers have been chosen

for the segment, there is a four-byte RBA pointer to the first physical
child segment (a physical child first pointer). There can also be a four-
byte RBA pointer to the last physical child segment (a physical child
last pointer). The pointers are in the order that the physical children
are defined in the DBD, with a physical child first pointer before a
physical child last pointer.

Figure 2-13 shows a logical parent with unidirectional relationships, two bidirectional
virtually paired relationships (the second with backward pointers), and three physical
segments (the second with backward pointers).

Figure 2-13: Sample counter and pointers in a typical HD-type segment.

Data The data area can be a fixed length that is specified in the DBD or variable
length (described in "Variable-Length Segment Structure"). For a logical
child segment with symbolic keys (PARENT=PHYSICAL on the SEGM
statement), the concatenated key of the logical parent will be at the start of the
segment.
Data Pad If the segment length is an odd number of bytes, a one-byte pad will be
appended to the segment to ensure that all segments start on half-word
boundaries.
Variable-Length Segment Structure

44
Figure 2-14 depicts a variable-length segment (VLS) that can exist in HISAM, HDAM,
and HIDAM databases.

Figure 2-14: Variable length segment structure.

Variable-length segments contain the following fields:

Segment Code See the definition for the appropriate database organization.
Delete Byte See the definition for the appropriate database organization.
Counters and See the definition for the appropriate database organization.
Pointers
Length Field 2 bytes. Signed binary number that specifies the length of the data
portion of the segment, including the length field itself.
Data See the definition for the appropriate database organization. If a variable-
length segment in a HISAM database is replaced and is longer than it
was before, IMS moves the following segments to make room for the
new segment. IMS does not move HDAM and HIDAM database
segments once they have been inserted. Instead, it splits the segment,
leaving the prefix part in the original location and inserting the data part
in another location. The two parts are connected by a VLS pointer.

You can make a segment variable in length in one of two ways:

 by specifically defining it to be variable in length by using the

SIZE operand in the SEGM macro of the DBD
 by implicitly defining it to be variable length by using the
COMPRTN (compression routine) operand in the SEGM macro of
the DBD

Use of a compression routine always makes the segment variable length in the data, but
may be presented to the user through a DL/I call as fixed length. How the user sees the
segment data is determined by the SIZE parameter in the DBD.

45
 Figure 2-15: Split variable length segment structure.

Prefix Portion

The prefix portion contains the following fields:

Segment Code See the definition for the appropriate database organization.
Delete Byte See the definition for the appropriate database organization. BIT 4 is
on,
indicating that the prefix and data are separated. Typically this is
X'08'.
Counters and See the definition for the appropriate database organization.
Pointers
VLS Pointer 4 bytes. RBA of the data part of the variable length segment.
Free Space Normal IMS free space (see "Free Space Element").
Data Portion
The data portion contains the following fields:
Segment Code See the definition for the appropriate database organization.
Delete Byte This will always be X'FF'.
Length Field 2 bytes. Signed binary number that specifies the length of the data
portion of the segment, including the length field.
Data See the definition for the appropriate database organization.
Pointer Types

46
Pointers play an important role in accessing data stored in hierarchic direct access and
indexed databases. An understanding of the various types of pointers and how they are
used is important in understanding how database segments are accessed.

In HD databases, the records are kept in hierarchical sequence through the use of
pointers-four-byte fields that contain the address of another segment. The prefix in every
HD segment contains one or more pointers, and each pointer contains the relative byte
address (relative to the beginning of the database) of the segment to which it points.

There are a number of types of pointers, and they can be mixed within a database record
to meet specific data access requirements.

Hierarchic Forward Pointers

Hierarchic forward (HF) pointers point to the next segment in the hierarchy. Segments
are located by following the HF pointers to the desired segment. This is essentially the
same as using a sequentially accessed database. As with a sequential database, when HF
pointers are used, all the segments in the hierarchy must be searched until the requested
segment is located. HF pointers are most suitable for databases where segments are
typically processed in hierarchic sequence.

Figure 2-16 shows an example of hierarchic forward pointers.

Figure 2-16: Examples of Hierarchic Forward Pointers.

Hierarchic Forward and Hierarchic Backward Pointers

47
With hierarchic forward (HF) and hierarchic backward (HB) pointers, each segment
points to the next segment and the previous segment in the hierarchy. Because HF and
HB pointers are four bytes each, combining them requires eight bytes in each dependent
segment. Root segments require 12 bytes, because the root points forward to the next
root, backward to the previous root, and forward to the first dependent segment.

Physical Child First Pointers

With physical child first (PCF) pointers, each parent segment points to the first
occurrence of each of its immediate child segment types. No pointers exist to connect
occurrences of the same segment type under a parent, which means that the hierarchy is
not completely connected. Physical twin (PT) pointers can be used to connect twin
segments and complete the hierarchy.

Physical Child First and Physical Child Last Pointers

With physical child first (PCF) and physical child last (PCL) pointers, each parent
segment in a record points to the first and last occurrence of its immediately dependent
segment types. PCL pointers cannot be used alone; PCF pointers must be used with them.

PCL pointers are most often used with PCF pointers in two cases:

 when no sequence field is defined for the segment type

 when new segment occurrences of a type are inserted at the end of
existing occurrences

PCL pointers give fast access to the last occurrence of a segment type, a
feature that significantly speeds inserts applied at the end of existing
occurrences. PCL pointers also provide fast retrieval of the last occurrence of
a segment type.

Physical Twin Forward Pointers

With physical twin forward (PTF) pointers, each occurrence of a given segment type
under the same parent points forward to the next occurrence. PTF pointers can be
specified for root segments, but not in the same way as with other segments. If PTF
pointers are used alone, only part of the hierarchy is connected. Parent and child
segments are not connected. Physical child pointers can be used to complete the
hierarchy.

Physical Twin Forward and Backward Pointers

48
With physical child forward (PTF) and physical child backward (PTB) pointers, each
occurrence of a segment type under the same parent points forward and backward to
occurrences of the same type. As with other forward and backward pointers, PTBs can be
used only with PTFs. When PTF and PTB pointers are specified for root segments, they
point to the next root segment and the previous root segment in the database.

Symbolic Pointers

IMS also allows the use of symbolic pointers. A symbolic pointer uses the concatenated
key of the segment it points to, rather than the segment's direct address. A concatenated
key consists of the key fields of the root segment and successive child segments, to the
key field of the accessed segment. For more information on symbolic pointers, see "The
Role of Secondary Indexes" and "The Role of Logical Relationships."

Multiple Data Set Groups

This manual has discussed the use of two data sets that can be using for storing
databases-the primary data set and a secondary, or overflow, data set. IMS also allows
you to store HISAM and HD databases on up to 10 data set groups-the primary data set
group and a maximum of nine secondary data set groups.

The use of multiple data set groups has a number of advantages. Primarily, it allows you
to create data set groups designed for the specific needs of various application programs.
By defining data set groups in different ways, you can:

 separate frequently used segments from those that are seldom used
 separate segment types that are frequently added or deleted from
those that are seldom added or deleted
 separate segments that vary greatly is size from the other segments
in the database

As an example, you may have designed a database so that the most frequently accessed
segment types are highest in the hierarchy, so that they can be accessed more quickly.
Later, you write another application program that frequently accesses a number of
segments that are scattered randomly throughout the hierarchy. You know that these
segments will take more time and processing to access. To overcome this difficulty, you
can define a data set group to contain the segments accessed by the second application
program.

You define data set groups in the DBD for the database.

Fast Path Databases

49
The Fast Path feature of IMS is designed to give improved response times for database
inquiries and updates. It does so through the use of specialized databases and the
Expedited Message Handling (EMH) facility. EMH ensures that Fast Path transaction
messages bypass normal message queuing and the priority scheduling process.

Two types of databases can be used with the Fast Path feature of IMS. They are data
entry databases (DEDBs) and main storage databases (MSDBs).

DEDBs
DEDBs are similar in structure to an HDAM database, but with some important
differences. DEDBs are stored in special VSAM data sets called areas. The unique
storage attributes of areas are a key element of the effectiveness of DEDBs in improving
performance. While other database types allow records to span data sets, a DEDB always
stores all of the segments that make up a record in a single area. The result is that an area
can be treated as a self-contained unit. In the same manner, each area is independent of
other areas. An area can be taken offline, for example, while a reorganization is
performed on it. If an area fails, it can be taken offline without affecting the other areas.

Areas of the same DEDB can be allocated on different volumes or volume types. Each
area can have its own space management parameters. A randomizing routine chooses
each record location, avoiding buildup on one device. These capabilities allow greater I/O
efficiency and increase the speed of access to the data.

An important advantage of DEDB areas is the flexibility they provide in storing and
accessing self-contained portions of a databases. You might choose to store data that is
typically accessed during a specific period of the day in the same area or set of areas. You
can rotate the areas online or offline as needed to meet processing demands. For example,
you might keep all records of customers located in one time zone in one set of areas and
move the areas on and offline to coincide with the business hours of that time zone.
DEDBs also make it easier to implement very large databases. The storage limit for a
DEDB area is 4 gigabytes (GB). By using a large number of areas to store a database,
you can exceed the size limitation of 232 bytes for a VSAM data set.

A DEDB area is divided into three major parts:

 units of work (UOWs)

 independent overflow part
 sequential dependent part

Figure 2-17 illustrates the structure of a DEDB area.

50
 Figure 2-17: DEDB area structure.

A Unit of Work (UOW) is further divided into the root addressable part and the
dependent overflow parts. Record storage in the root-addressable and dependent overflow
parts of a UOW closely resembles record storage in an HDAM database. The root and as
many segments as possible are stored in the root addressable part, and additional segment
occurrences are stored in the dependent overflow part.

If the size of a record exceeds the space available in the root-addressable and dependent
overflow parts, segments will be added in the independent overflow part.

Because a UOW is totally independent of other UOWs, you can process a UOW
independently of the rest of the DEDB. The ability to continue processing the remainder
of an area while reorganizing a single UOW significantly increases the data availability
of a DEDB database.

Figure 2-18 shows the configuration of a VSAM CI within a UOW.

51
 Figure 2-18: Configuration of a control interval within a unit of work.

FSEAP This field gives the offset in bytes to the first free space element (FSE). If
the CI is in the sequential dependent part, these two bytes are not used.
CI TYP This describes the type of CI.

1 base section

2 overflow section

3 independent overflow part

4 sequential dependent part

RAP This contains the root anchor point if the CI is in the root addressable part
of the area. Only one RAP exists per CI. Other roots randomized to this CI
will be chained off of this RAP in ascending key sequence.
CUSN CI update sequence number. This number is increased by one with each
update of the CI.
RBA Relative byte address of this CI.
RDF Record definition field. This contains information on the records stored in
the CI, their length, and whether they are fixed length or variable length.
CIDF CI definition field. This field contains information on the control interval
itself. It keeps track of the amount of free space available and where the
free space is located, relative to the beginning of the CI. Control intervals
will have only one CIDF but may have a variable number of RDFs,
depending on whether the CI contains fixed-length or variable-length
records or a combination of the two.

52
Sequential Dependent (SDEP)

DEDBs employ a special segment type called sequential dependent (SDEP). Sequential
dependents are designed for very fast insertion of segments or to accommodate a very
high volume of inserts. They must be located in the hierarchy as the first child of the root
segment, and they occupy their own space in an area. Although SDEPs perform well for
insert operations, they are not as efficient at online retrieval. For this reason, SDEP
segments are often retrieved sequentially by using the SDEP Scan utility and are
processed further by offline jobs.

The sequential dependent part of the area is used solely for the storage of sequential
dependent segments. These segments are added in chronological order, regardless of
which root they belong to. They are chained back to the root in reverse order by pointers.

The purely sequential nature of SDEPs allows rapid insertion of new SDEP segment
occurrences. SDEPs can only be written and read sequentially, and REPLACE and
DELETE calls are not allowed. When the sequential dependent part is full, new segments
must be added at its beginning. For this reason, the SDEP area must be purged
periodically. The SDEP Scan utility can be used to extract SDEP segments from an area
while online processing continues. The Sequential Dependent Delete utility allows you to
delete some or all of the SDEPs while online processing continues.

SDEPs typically are used for temporary data. They are often used for recording
processing events that occur against a record during a particular time period. A bank, for
example, might record the activity of each customer account during the day in SDEPs
that are read and processed later offline.

Other DEDB segment types are direct dependent segments (DDEPs). They can be stored
and retrieved hierarchically and support ISRT, GET, DLET, and REPL calls. IMS
attempts to store DEDB DDEPs in the same CI as the root segment. If space is not
available in the root CI, IMS will search the dependent overflow and then the
independent overflow parts. You can define DDEP segments with or without a unique
sequence field. DDEPs are chained together by a PCF pointer in the parent for each
dependent segment type and a PTF pointer in each dependent segment. Figure 2-19
illustrates the format of a DEDB record.

53
 Figure 2-19: DEDB record format.

Root and direct dependent segments can be stored in the root addressable part of a UOW
or the dependent overflow part, if the root addressable part is full. The independent
overflow part consists of empty CIs that are not initially designated for use by a specific
UOW. Any UOW can use any CI in the independent overflow part. When a UOW begins
using a CI in the independent overflow part, however, the CI can be used only by that
UOW. The sequential dependent part of an area stores SDEPs in the order in which they
are loaded, without regard to the root segment or the UOW that contains the root.

Although a DEDB can be compared in structure to HDAM, there are a number of

important differences between the two. DEDBs have the following restrictions:

 do not support secondary indexes

 do not support logical relationships
 allow unique key field or no key field for a segment; do not
support non-unique key fields
 do not support batch processing

DEDBs are supported by DBRC and standard IMS logging, image copy, and recovery
procedures. DEDB areas are accessed by using VSAM improved control interval
processing (ICIP).

54
Randomizing Module
IMS uses a randomizing module to determine the location of root segments.

The randomizing module addresses records by:

 ascending area number

 ascending UOW
 ascending key in each anchor point chain

Multiple Area Data Sets

IMS allows a DEDB area to be replicated (copied) up to seven times, thus creating
multiple area data sets (MADS). You can do this using the DEDB Area Data Set Create
utility, which lets you make multiple copies of an area without stopping processing. The
copies you create must have the same CI sizes and spaces, but they can reside on separate
devices. Although IMS allows seven copies plus the original, for a total of eight iterations
of the same area, most IS shops use no more than two or sometimes three copies, to avoid
excessive use of DASD space.

As changes are made to data within one area of a MADS, IMS automatically updates all
copies to ensure the integrity of the data throughout the MADS. If one area of the MADS
fails, processing can continue with another copy of the area.

If an error occurs during processing of an area, IMS prevents application programs from
accessing the CI in error by creating an error queue element (EQE) for the error CI. IMS
uses the EQE to isolate the CI in error while allowing applications to access the
remainder of the area. When IMS detects errors on four different CIs within an area, or
when an area has experienced more than 10 write errors, IMS stops the area. Because
other copies of the area are available, IMS can continue processing by using the same CI
in one of the copies.

MSDBs
Main storage databases (MSDBs) are so named because the entire database is loaded into
main storage when processing begins. This makes them extremely fast, because database
segments do not have to be retrieved from DASD. Most IS shops reserve MSDBs for a
site's most frequently accessed data, particularly data that requires a high transaction rate.
The fact that MSDBs require memory storage limits their size.

In addition to being executed in main storage, MSDBs gain speed from a number of other
processing conventions. Update calls are not executed immediately; rather, updates are
held for simultaneous execution when a synchronization point is reached. Also, MSDBs
support field calls, a feature that allows MSDB segments to be updated at the field level
while permitting other programs access to other fields within the segment at the same

55
time. Finally, MSDBs are made up of fixed-length root segments only. Because there are
no dependent segments, segment searches are simplified. There are two general types of
MSDBs: terminal-related and nonterminal-related.

Terminal-Related MSDBs

With terminal-related MSDBs, each segment occurrence is associated with, or owned, by

a specific logical terminal. Only the logical terminal that owns a segment is allowed to
update the segment, but all logical terminals are allowed to retrieve all segments. The
name of the logical terminal that owns the segment is used as the key of the segment. The
key of a terminal-related segment does not actually reside in the segment. Terminal-
related MSDBs are used when segments contain data that can be associated with a
specific user or terminal.

Terminal-related MSDBs are divided into two types:

 terminal-related fixed
 terminal-related dynamic

Terminal-related fixed MSDBs do not allow segments to be inserted or deleted. They can
be retrieved and updated only. Terminal-related dynamic MSDBs allow segments to be
inserted or deleted.

Nonterminal-Related MSDBs

With nonterminal-related MSDBs, segments are not owned by any terminals. An

application program can read and update any segment; however, insert or delete calls are
not allowed.

There are two types of nonterminal-related MSDBs

 nonterminal-related with terminal keys

 nonterminal-related without terminal keys

With nonterminal-related with terminal keys, the name of a logical terminal or a field in
the segment is used as the key of the segment. As with terminal-related fixed segments, if
the terminal name is used as the key, it does not reside in the segment. For nonterminal-
related without terminal keys, terminal names are not used as keys; a data value is used as
key. The key can be any part or all of the field, but it must reside in the sequence field of
the segment.

Nonterminal-related MSDBs are typically used when a large number of users need to
update data frequently, such as users at point-of-purchase terminals.

56
Virtual Storage Option
The Fast Path Virtual Storage Option (VSO) for DEDBs allows you to achieve
performance improvements similar to those of MSDBs by loading one or more DEDB
areas into virtual storage. You do this by defining the DEDBs as VSO areas. VSO areas
must be registered with DBRC and do not allow block-level sharing while the area is in
virtual storage. Otherwise, they are the same as non-VSO DEDB areas.

The Role of Secondary Indexes

A secondary index lets you process a segment type in a sequence other than that defined
by the segment’s key. You can base a secondary index on any segment in the database,
including the root, and you can create more than one secondary index on any segment. In
fact, you can use up to 32 secondary indexes for a segment type and a total of 1,000
secondary indexes for a single database. A secondary index allows you to have an index
based on any field in the database. This section describes how secondary indexes can be
used to solve access needs in the sample College databases.

Secondary indexes can be used with HD databases and with HISAM. A secondary index
uses VSAM as its access method. A secondary index is a self-contained database, with its
own DBD, containing segments that point to a segment in the primary database. Each
secondary index’s DBD contains parameters that connect it to the primary database.

Let’s look again at the College database created in Chapter 1, “IMS Concepts.” It is
shown again in Figure 2-20.

57
 Figure 2-20: College database.

As part of our database, we decided to list the students enrolled in a specific course. We
handled this requirement by creating the Enroll segment as a dependent of Course.
Suppose that the Enroll segment has the data fields shown in Figure 2-21.

Figure 2-21: Data fields of the enroll segment.

58
If we retrieve the occurrences of the Enroll segment in key sequence order, we will have
a list based on student ID number. But suppose we want the information in this segment
in an alphabetical list based on the student’s names. To create this list using the StudeID
field would be difficult. If we create a secondary index based on the Name field, we can
generate our listing easily by processing sequentially on the new Name key field.

You can also use the secondary index to access segments individually. You do this by
referring to them specifically by the secondary index name (remember, the secondary
index is a database) in the segment search argument you write.

Finally, you can treat the secondary index as a database and use the information stored in
it. Using our StudeID secondary index, we can retrieve just the contents of the field to
which it points, giving us an alphabetical list of student names.

When you want an application to perform processing by using a secondary index, you
must code the PROCSEQ parameter in the application program PCB. This identifies the
index database to the application program. If you want the application program to use the
database’s regular processing sequence, do not include the PROCSEQ parameter. You
can have the application program use the regular processing sequence and the secondary
index by including two PCBs in the application program’s PSB. One PCB contains the
PROCSEQ parameter and one does not.

Secondary Index Segments

The segments used in setting up a secondary index are referred to as the source, target,
and pointer segments, depending on their function within the index structure. When you
set up a secondary index, you must define to IMS which segments will act in which
capacity.

Source Segment

The source segment in the primary database contains the field that is being used as the
pointer segment’s key field. The secondary index will be sequenced on this field. In
Figure 2-20, Enroll was the source segment.

Target Segment

The target segment in the primary database is the segment to which the index points. It is
the segment that is retrieved when the secondary index is used. In many cases, but not
always, the target segment is the same as the source segment. In Figure 2-20, the Enroll
segment is the target segment.

59
Pointer Segment

The pointer segment is the only type of segment that is stored in the secondary index
database. (Target and source segments are in the primary database.)

Index Pointer Segment Layout

Figure 2-22 shows the index segment’s configuration.

Figure 2-22: Index pointer segment layout.

The layout of the index pointer segment is as follows:

Non-Unique Optional. This 4-byte field is present only when the pointer segment
Pointer contains non-unique keys. It is used to chain together the KSDS and
ESDS logical records with the same key value. It is not part of the
segment prefix. It is not reflected in the prefix length of the generated
DBD.
Segment Code Optional. This 1-byte field appears only if DOS COMPAT was
specified in the index DBD. The prefix length in the generated DBD
always assumes this field is present, even though it may not be
present.
Delete Byte Required. This 1-byte field is always present. At load time it contains
X'00'.
Direct Pointer Optional. This 4-byte field is present if the secondary index is
pointing to an HD-type database and direct pointing was selected. It
contains the 4-byte RBA of the target segment.
CONST Optional. This 1-byte field contains a user-specified constant. It is
required for a shared secondary index. If present, it forms part of the
VSAM key. SRCH Required. It consists of one to five fields copied
from the index source segment. This field is the VSAM key. This is
the data used to qualify a call when accessing the target segment by
using the secondary index.
SUBSEQ Optional. It consists of one to five fields copied from the index source
segment. If present, it is concatenated with the search (SRCH) data to
produce a unique VSAM key.

60
DDATA Optional. It consists of one to five fields copied from the index source
segment. It is available only when processing the secondary index as
a separate database.
Symbolic Pointer Required if the primary database is HISAM. Optional for HD-type
primary databases. It is mutually exclusive with direct pointers. If
present, it contains the concatenated key of the target segment, which
must be unique. The symbolic pointer may be a separate field or may
be imbedded in the SUBSEQ or DDATA fields.
User Data Optional. It is inserted and maintained by the application program
after the secondary index has been created. There is no operand in the
XDFLD macro to define this area. It is the residual space left in the
logical record after space for all requested fields is satisfied.
Pad Optional. This 1-byte field is not part of the segment data and is
present only if it is necessary to make the logical record length an
even integer to satisfy the VSAM requirement.
Secondary Index Implementation
Secondary indexes can accommodate non-unique keys. You can create a secondary index
based on a field that will not always be unique. In our previous example, we discussed
creating a secondary index based on student name. It is quite possible for two students to
have the same name, particularly if you are indexing on the last name only. You would
certainly have non-unique keys if you created a secondary index based on the Major
field. When this occurs, IMS creates a SYNRBA field in the pointer segment of the
secondary index. The SYNRBA field contains a pointer that points to duplicate key
segments. Duplicated key segments are stored in a VSAM ESDS and are chained
together by pointers of this type. This section discusses secondary index implementation
using non-unique or unique keys.

Non-Unique Keys

To implement a secondary index with non-unique VSAM keys, two VSAM data sets are
required. The first (or only) occurrence of a non-unique key is placed in a KSDS.
Subsequent occurrences of that key are placed in an ESDS. Logical records containing
multiple occurrences of the same key are chained together. IMS implements this chain by
appending a 4-byte RBA pointer to the front of each record.

Figure 2-23 shows the implementation of a secondary index with non-unique

keys.

61
 Figure 2-23: SecondaryiIndex implementation with non-unique keys.

Unique Keys

When unique VSAM keys are present, no ESDS is required and no 4-byte pointer is
appended to the front of each logical record. Figure 2-24 shows the implementation of a
secondary index with unique keys.

Figure 2-24: Secondary index implementation with unique keys.

Manuals have been written on the use of secondary indexes, and a complete discussion of
the subject is beyond the scope of this book. They are an extremely powerful tool for use
with IMS databases, however, and should be a part of every IMS DBA's data
management strategy.

The Role of Logical Relationships

IMS provides the ability to create special types of segments that access data in other
segments through the use of pointers. You can create a segment type that contains no data
but points to a segment in the same or another database to access the data stored there.
Because the segment is not actually a physical child of the segment to which it points, it
is called a logical child. And because the path established between the logical child and
the segment to which it points is not a physical relationship, it is called a logical
relationship.

The ability to create logical relationships among database segments is a powerful feature
of IMS. It lets you avoid the need to store redundant data, and it lets you create new
database hierarchies without creating new databases. By establishing a logical
relationship, you can create a hierarchy that does not actually exist in storage but can be

62
processed as if it does. You can relate segments that exist in separate hierarchies within
the same database or in separate databases.

Note: Logical relationships cannot be used with Fast Path DEDB or MSDB databases.

To illustrate the concept of logical relationships, let's look again at the example College
database. Suppose we decide that, as part of the College database, we want a segment
under Dept that lists the classrooms being used for each course. We could create a new
segment, Rooms, as a dependent. But suppose we discover that the physical descriptions
we need are already contained in a segment of another database. The data we need is
included in the Units segment of the Buildings database. It would be redundant to repeat
the same data in our College database. By doing so, we would be vulnerable to the
problems associated with duplicate data:

 It requires additional maintenance to keep the duplicate sets of data

up to date and synchronized.
 It requires extra DASD to store the duplicate data. We can achieve
the effect of a new Rooms segment in the College database by
creating a logical data structure that ties the College and Building
databases together. To do this, we create a logical DBD that
defines the structure we want. In the College database, where we
want our Rooms segment, we create what is called a logical child
segment. It points to the Units segment in the Buildings database.
The Units segment, where the data is physically stored, is referred
to as the logical parent. In our logical child segment, Rooms, we
simply store pointers that point to the appropriate occurrences of
the Units segment, the logical parent.

The logical relationship we have just established gives us the logical structure shown in
Figure 2-25.

63
 Figure 2-25: Logical structure based on college and buildings databases.

Figure 2-25 is an example of a unidirectional logical relationship. It is called

unidirectional because we can go in only one direction, from the College database to the
Units segment. You can use the Rooms segment of the College database to find
information on classroom space available for courses, but you could not use any segment
of the Buildings database to find information on what courses are being taught in specific
rooms. You can, however, create logical relationships that will allow you to access data
in both directions. In addition to unidirectional relationships, you can create two types of
bidirectional relationships-physically paired and virtually paired.

Physical Pairing
Suppose that we want to be able to access data in the College database as if the data were
in a segment of the Buildings database. When we access the Units segment of the
Buildings database, we want to know which courses will be taught in each room. We can
do this by storing the Rooms logical child segment in the Buildings database and pointing
to the Course segment in the College database. As a room is assigned to a course, the
Rooms logical child will be updated in both databases. We will have a bidirectional path
that lets us determine what room a course will be taught in and what courses will be
taught in any room. The Rooms segment is physically stored in both databases and the
segments are said to be physically paired. IMS automatically updates both logical child
segments when a logical parent segment occurrence is added.

64
Virtual Pairing
In the discussion of physical pairing, we discovered how to link to databases
bidirectionally by using two logical child segments, one in each database. By using
virtual pairing, we can do the same thing without creating a logical child in the Buildings
database. Instead, we can add another pointer in the Rooms logical child in the College
database to give us a two-way path between the two databases. This gives us the effect of
two logical child segments, although we only have one. The logical child that is stored in
the College database is called the real logical child. The logical child that is created by
the second pointer in the real logical child is called the virtual logical child. The
relationship we have created between the two database segments is called bidirectional
virtual pairing.

Intersection Data
When two segments are logically related, it is possible to create data that is relevant only
to the relationship. For example, in our College database, the number of seats available in
the room where a course will be taught is a unique combination of the course and the
room assigned for it. This information could be useful in determining if the enrollment
for a course has exceeded the number of seats available. This type of data is called
intersection data. It is meaningful only in the context of the two logically related
segments. Intersection data is stored in the logical child segment. There are two types of
intersection data:

 fixed intersection data (FID)

 variable intersection data (VID)

Fixed Intersection Data

Fixed intersection data is any data stored in the logical child. When you are using direct
pointing, FID is the only data in the logical child segment. In symbolic pointing, the FID
is stored in the data portion of the segment after the LPCK.

Variable Intersection Data

Variable intersection data is used when you have several occurrences of intersection data
for the same logical relationship. It is stored as a dependent of the logical child, and there
can be as many occurrences per logical child as needed.

65
Use of Pointers in Logical Relationships
Pointers used in logical relationships fall into two categories-direct and symbolic. It is
possible to implement logical relationships using both types. The major differences are
that a direct pointer is a true pointer. With a direct pointer, the logical child segment
contains the address of the logical parent segment to which it points. With a symbolic
pointer, the logical child segment contains the key of the logical parent segment to which
it points. Four types of pointers can be specified in logical relationships:

 logical parent (LP)

 logical child (LC)
 logical twin (LT)
 physical parent (PP)

Logical Parent Pointers

LP pointers point from the logical child to the logical parent. When pointing into HDAM
and HIDAM databases, an LP pointer can be a direct pointer or a symbolic pointer. It
must be a symbolic pointer if pointing into a HISAM database; however, direct LP
pointers can exist in a HISAM database as long as they are not pointing into a HISAM
database. Because pointers are not required between segments in a HISAM database, the
only time direct pointers are used in them is to maintain a logical relationship with an HD
database.

A symbolic LP pointer consists of the logical parent's concatenated key (LPCK). A

symbolic LP pointer can point into a HISAM database or HD database. It is stored in the
first part of the logical child segment.

In HISAM or HIDAM databases, IMS uses symbolic pointers to access the database's
index and (from there) to locate the logical parent segment. In HDAM, the randomizing
module changes the symbolic pointer into a block and RAP address to find the logical
parent.

Logical Child Pointers

Logical child pointers are used only for logical relationships that use virtual pairing. With
virtual pairing, only one logical child exists on DASD, and it contains a pointer to a
logical parent. The logical parent points to the logical child segment. Two types of logical
child pointers can be used:

 logical child first (LCF)

 a combination of LCF and logical child last (LCL) pointers

Because LCF and LCL pointers are direct pointers, the segment they are pointing to must
be in an HD database. The logical parent (the segment pointing to the logical child) must

66
be in a HISAM or HD database. If the parent is in a HISAM database, the logical child
must use a symbolic pointer to point to the parent.

Logical Twin Pointer

Like logical child pointers, logical twin pointers are used only for logical relationships
that use virtual pairing. Logical twins are multiple occurrences of logical child segments
that point to the same occurrence of a logical parent segment. Two types of logical twin
pointers can be used:

 logical twin forward (LTF)

 a combination of LTF and logical twin backward (LTB) pointers
LTF pointers point from a logical twin to the logical twin stored
after it. LTB pointers, used only with LTF pointers, point from a
logical twin to the logical twin stored before it. Logical twin
pointers function similarly to the physical twin pointers described
in "Physical Twin Forward and Backward Pointers."

LTF and LTB pointers are direct pointers, containing the 4-byte address of the segment to
which they point, and can exist only in HD databases.

Physical Parent Pointer

Physical parent (PP) pointers point from a segment to its physical parent. IMS generates
PP pointers automatically for HD databases involved in logical relationships. They are
put in the prefix of all logical child and logical parent segments and in the prefix of all
segments on which a logical child or logical parent is dependent in its physical database.
Having a PP pointer in each segment in the chain from logical segment to physical parent
creates a path back to the root segment on which the segment is dependent. This allows
access to any of the segments in the chain in forward or backward order.

As with direct pointers, PP pointers contain the 4-byte address of the segment to which
they point.

Online Environment
The IMS/ESA product is made up of two major components-IMS DB and IMS TM. IMS
dB supports the creation and maintenance of the database and processes database calls.
IMS TM is a data communication system that supports online transaction processing for
IMS dB This section discusses the components of the IMS online environment, the
facilities available, and the types of programs that can be used.

There are major differences between batch processing and online processing. When you
initiate a program in batch mode, a region in memory, sometimes called an address space,
is assigned to it. The region will be loaded with the application program itself and the

67
IMS modules it needs for execution. The batch application program will process
independently of other jobs being run in the system. The batch application program
begins with the first JCL statement, executes serially through the job, and (assuming it is
coded properly and all systems are functioning correctly) completes successfully. It needs
no intervention from a user or another program.

In the online environment, an application program can be started and stopped

intermittently. It can be launched by a user or by another program. You don't have to
submit JCL to initiate it. Instead, you can enter a transaction code from a remote terminal.
When IMS receives the message with the correct transaction code, it will initiate the
application program for you. In fact, any user with the proper authorization can initiate an
online application program. Users can use the program in interactive mode from their
terminals. These capabilities, and others, make online programs indispensable for most
business computing environments.

Application Programming Environments

IMS supports five application processing environments that provide a wide range of
processing options:

 dB/DC (database/data communications)

 Database Control (DBCTL)
 Data Communications Control (DCCTL)
 dB batch
 TM batch

dB/DC
In previous chapters we have discussed IMS databases and use of the DL/I command
language in writing batch application programs. These application programs use the
services of DL/I only. The IMS dB/DC environment provides a full implementation of
DL/I and the data communications interface to allow online processing.

There are a number of differences between batch and online applications.

With online applications:

 Many users can access information in the databases

simultaneously.
 The application can communicate with users at terminals and with
other applications.
 Users can invoke the application from terminals.
 Users get the results of the application processing immediately.
 The database can be updated immediately.

68
Database Control
The DBCTL environment allows a transaction management subsystem other than IMS
TM to have online access to DL/I databases and data entry databases (DEDBs). This
means users of the Customer Information Control System (CICS) transaction manager,
for example, can use DBCTL to access DL/I databases.

DC Control
DCCTL lets you use IMS TM to access non-IMS databases, such as DATABASE 2
(DB2*). DCCTL uses the IMS External Subsystem (ESS) Attach Facility to access other
databases. When using DCCTL, you must define the subsystems that DCCTL can access
in an IMS.PROCLIB member. DCCTL provides access to the following subsystems:
online change

 MFS
 MSC
 DBRC
 device support
 IMS commands

Online Configuration
The IMS online processing environment consists of a central control region and a number
of designated address spaces within the MVS environment. Figure 3-1 shows the
configuration of the online processing environment.

69
 Figure 3-1: IMS Online Configuration.

Each box in Figure 3-1 represents an address space in an MVS environment. The online
operating environment is controlled through the following specialized processing regions:

 control region (CTL)

 message processing regions (MPRs)
 batch message processing regions (BMPs)
 DL/I separate address space (DL/I SAS)
 Database Recovery Control (DBRC)

These regions provide the following functions:

Control Region: The CTL region is the address space that holds the control program that
runs continuously in the dB/DC environment. It is responsible for a number of online
functions. It holds the IMS control program, which services all communications DL/I

70
calls. It is responsible for Fast Path databases that are accessed by an online program and
for Fast Path I/O. It performs all IMS command processing. The control region also:

 supervises processing for message queues

 supervises communication traffic for all connected terminals
 is responsible for restart and recovery information
 is responsible for the operation of the system log

DL/I Separate Address Space: The DL/I SAS controls full-function databases accessed
by an online program. It handles full-function database physical I/O for programs. It also
is responsible for full-function program isolation (PI) locking.

Database Recovery Control: DBRC extends the capabilities of utilities for database
recovery to allow easier recovery of full-function databases, Fast Path DEDBs, and
databases accessed through CICS. DBRC has three levels of control:

 log control
 recovery control
 share control

See "Database Recovery Control" for more information. Address spaces that contain
application programs are referred to as dependent regions. Each of the regions discussed
below is a dependent region.

Message Processing Region: The MPR loads the application program and holds it to
wait for messages. The control program controls scheduling of processing in the MPR.
Output can be to a terminal or to another program.

Batch Message Processing Region: The BMP region contains application programs for
processing against databases in a batch processing operation. The BMP has access to
non-IMS DL/I databases such as flat files, as well as to IMS databases and online IMS
message queues. Scheduling is done by OS/VS messaging.

Online Resource Allocation

Most examples of online programming discussed in this chapter deal with the dB/DC
environment. Because most dB/DC systems handle a number of application programs and
respond to messages originating from a variety of sources, IMS must have a broad-
ranging control of resources. When you define the IMS system for dB/DC, you must
provide IMS with certain information about the application programs and databases that
IMS will be processing and about the communications resources that IMS will use.

71
Defining Application Resources
To use the resources available to application programs, you must define those resources
to IMS for use with the application. This section discusses the resources available and
how to define them to IMS.

Databases

To access databases through MPPs or BMPs, you must first define each database to IMS
by entering a DATABASE macro that lists the DBD name of the database. The following
DATABASE macro accesses a database whose DBD name is COLLEGE:
DATABASE COLLEGE

APPLCTN Macro

The dB/DC environment processes two kinds of online application programs: MPPs (see
"Message Processing Programs" on page 3-18) and BMPs (see "Batch Message
Processing Programs" on page 3-18). The main difference between the two is that IMS
processes an MPP dynamically when it receives a message with an MPP as a destination.
IMS processes a BMP when it is scheduled by a system operator. BMPs are typically
used to process messages that are held in a message queue for that purpose. You must
define MPPs or BMPs to IMS in the APPLCTN system definition macros during system
definition. Here is an example of an APPLCTN system definition macro for an MPP:

APPLCTN PSB=PROGRAM1

Here is an example of an APPLCTN system definition macro for a BMP:

APPLCTN PSB=BMPPGM2,PGMTYPE=BATCH
Transaction Codes

Messages are associated with application programs through the use of transaction codes.
You can assign more than one transaction code to an application program, but you can
assign each application code to only one application. Transaction codes are defined
through a TRANSACT macro, which follows the APPLCTN macro for the program it is
assign to. You define a transaction code as a unique combination of one to eight
characters. IMS creates a message queue for each transaction code. As messages are
generated for the transaction code, messages are stored in the appropriate message queue
pending processing. Here is an example of a TRANSACT macro for transaction code
TRANS1:

TRANSACT CODE=TRANS1

72
Defining Communications Resources
In using the dB/DC environment, you must also define communications resources such as
communications lines and terminals to IMS. When you define these resources to IMS,
you are creating a communications network that IMS will use in routing messages to and
from terminals and the central processor. Control of the hardware is managed by a type of
subsystem called a teleprocessing access method. An example of a TP access method is
Virtual Telecommunications Access Method (VTAM). The three major types of
hardware defined to IMS are communications lines, physical terminals, and logical
terminals.

Communications Lines

There are two major types of communications lines: switched and non-switched. With
switched lines, users dial a number to gain access to the network. Switched lines allow
the attachment of only one remote terminal at a time. With non-switched lines, terminals
are connected directly to a dedicated line. Non-switched lines can be contention lines or
polled lines. Contention lines allow only one contention-type terminal on the line at a
time. Polled lines allow one or more terminals to use the line at a time. You must use a
LINE macro to assign one or more remote terminals to a communications line and the
LINEGRP macro to create line groups of lines that connect terminals of a similar type.
Use separate line groups to group terminals with the same communication mode, polling
technique, or transmission code.

Physical Terminals

Physical terminals are connected to a communications line and defined to IMS. Each
terminal device in a line group is assigned a numeric identifier or address called a
PTERM. A major distinction of terminal attachments is whether they are local or remote.
Local refers to attachments made through a channel; remote attachments are made
through a communications control unit. Because remote terminals are connected through
one or more levels of communications control units, you must use a CTLUNIT macro to
define the control unit to IMS when configuring the network.

Logical Terminals

Although the physical terminal is defined to the system, IMS uses logical terminal
(LTERM) names to communicate with the terminals connected to the system. An
LTERM name can be assigned to a physical terminal and later moved to a different
physical terminal. You can associate many LTERM names with a single physical
terminal to allow multiple users of the same terminal. When you define a TERMINAL
macro, you can follow it with one or more NAME macros that list the LTERM names
associated with that terminal.

73
In IMS online processing, LTERM names are used as message destinations in much the
same way that transaction codes are used. IMS creates a message queue for each LTERM
name. Messages addressed to that LTERM are held in the LTERM message queue.
LTERM messages can be sent by MPPs, BMPs, or another logical terminal. The use of
message queues allows the application program to be independent of the time of
transmission or arrival of messages.

An application program interacts with a logical terminal in much the same way it does
with a database. A GU call, for instance, retrieves a message segment from a queue, and
an ISRT call inserts a message segment into a queue.

Here is an example of IMS data communications macros defining the line groups, lines,
control units, physical terminals, and logical terminals on a network:

LINEGRP DDNAME=LINEDD,UNITTYPE=3270
LINE ADDR=L03
CTLUNIT ADDR=CT4,MODEL=1
TERMINAL ADDR=65
NAME LTERM5
TERMINAL ADDR=66
NAME LTERM11
NAME LTERM15
NAME LTERM22
Message Types
Units of communication that flow between terminals and the host computer in an online
environment are referred to as messages. Most of our discussion of online processing
revolves around the format and processing of messages. In IMS online processing there
are three message types, based on their destination:

 transaction code messages

 logical terminal messages
 IMS terminal commands

Transaction Code Messages

Transaction code messages are used to communicate with application programs.

Transaction code messages can originate from a terminal or from another program.
Transaction codes are used to link transactions to the program that will execute them. A
transaction can be assigned to only one program, but a single program can be assigned
many types of transactions. The code is recognized by the system and is used to route the
message to the transaction's message queue for processing by the application program.

74
Logical Terminal Messages

During IMS TM system definition, physical terminals are assigned logical names. A
physical terminal can have more than one logical name, and a logical name can be
changed, removed, or assigned to another physical terminal. The logical terminal name
plays a similar role to the transaction code. The logical terminal name is used by the
system to place the message in the right message queue for further processing. Logical
terminal name messages are those messages addressed to a logical terminal. They can be
sent by the host processing unit or by another terminal.

IMS Terminal Commands

Certain commands are reserved for specified IMS operating functions. They are used for
operations such as starting, stopping, restarting, controlling, or changing IMS online.
They are also used to run IMS utilities. Most of these commands are used by the master
terminal operator (MTO) only. Their format is a slash followed by the command. The
command /STOP, for example, prevents new IMS transactions from scheduling.

Message Segments
Although messages are transmitted as a single unit, they can be divided into one or more
message segments. MPP and BMP programs actually retrieve messages one segment at a
time, in much the same way that database records are retrieved one segment at a time.
Input and output messages have segments reserved for IMS control information. Figure
3-2 shows the structure of a message segment.

Figure 3-2: Sample Message Segment

A message segment includes the following fields:

Length: A binary number that expresses the total length of the segment, including LL
and ZZ bytes.

ZZ: Two bytes of control information used by IMS.

DEST-CODE: A 1- to 8-character destination code. For input messages, the destination

code is normally a transaction code, but it can be an IMS command or LTERM name. For
outgoing messages, the destination is normally the originating LTERM name as specified
in the I/O PCB or a different LTERM specified by an alternate PCB.

75
b: A trailing blank.

Text: The text of the message. Length may vary, but each text segment has a maximum
size of 132 bytes.

The message may consist of only one segment; the application program may require
more information for processing than can be contained in one segment. If so, a sequence
of several segments will be sent. When IMS receives an input message, it examines each
segment for the end-of-segment indicator. If the message is a single segment, the end-of-
segment is also interpreted as the end-of-message.

Message Processing
Application programs can use DL/I calls to retrieve and process messages. A GU
function accesses the first message segment and a GN accesses subsequent message
segments. The application program inserts the response to the input message into the I/O
PCB, where it is retrieved by IMS and returned to the entering terminal. The application
program can send output messages to a destination other than the originating terminal by
using an alternate I/O PCB. Use of the alternate I/O PCB has the effect of placing the
outgoing message in the message queue of a different LTERM name. When the message
has been received by a terminal or by another program, IMS dequeues (deletes) it. If the
message is not delivered successfully, IMS saves it in the appropriate message queue for
future delivery. If you are using the message formatting service (MFS), the outgoing
message is processed by MFS before being routed to the LTERM. MFS converts program
output format to device output format (DOF).

I/O PCB
IMS has two types of PCB areas, a database PCB and a data communications PCB. The
database PCB is defined as part of the PSB and describes the hierarchical structure of the
database, the sensitive segments, and the types of DL/I calls that can be used (see
"Program Specification Block" on page 2-5). The data communications PCB is used to
allow the application program to communicate with remote terminals. This function is
performed by a specific type of data communications PCB called an I/O PCB. You do not
have to define the I/O PCB in an application program's PSB; IMS automatically
generates it for you. You must, however, include an I/O PCB area in the application
program's linkage section. In a batch program, you do not have to be concerned with the
I/O PCB; only the database PCB is required.

The I/O PCB is generated by IMS and inserted automatically as the first PCB in the PSB
parameter list for a BMP or MPP. Application programs use the I/O PCB to receive
messages from the input message queue and to transmit messages back to the originating
terminal. An application program uses a GU or GN call to retrieve messages from the
message queue and an ISRT call to send messages to a terminal.

76
The I/O PCB generated by IMS resides outside your program. It is not added to the PSB
source code. To use the I/O PCB, you must define a mask of the I/O PCB in your
program to check the results of IMS calls. Your mask must contain the same number and
size of fields as the I/O PCB, and they must be in the same order.

To match the I/O PCB, the mask in your program should have the following fields:

Logical Terminal Name: An 8-byte field containing the name of the LTERM that sent
the message or that the output message should be sent to.

Reserved Field: A 2-byte field reserved for IMS.

Status Code: A 2-byte field that describes the results of a DL/I call.

Current Date: A 4-byte field that gives the Julian date the message was originated in a
packed, right-aligned YYDDD format.

Current Time: A 4-byte field that gives the time the message was originated in a packed
HHMMSST format.

Input Message: Sequence Number

A 4-byte field containing the message sequence number assigned to the message by IMS.

Message Output Desciptor (MOD) Name: An 8-byte field used only with MFS to
specify the MOD to be used.

User Identification: An 8-byte field usually associated with RACF sign-on authority to
contain the user's ID.

Group Name: An 8-byte field used by DB2 to provide security for SQL calls.

Figure 3-3 shows a sample I/O PCB mask as defined in the Linkage Section of a COBOL
application program.

77
 Figure 3-3: Sample I/O PCB Mask.

I/O PCB Status Codes

Here are the most common I/O PCB status codes:

Spaces: The call was completed successfully.

QC: There are no input messages in the application program message queue.

QD: The message contains no more segments.

AD: An invalid call function was used.

A5: This is the format name specified on a second or subsequent message ISRT or PURG
call.

QF: The message segment has a length of less than 5 bytes (it contains control characters
only, no message text).

Alternate PCBs
You may want to code a program that can send messages to a destination other than the
originating terminal. You may want to include logic that will let the program send a
message to a different terminal or to another program. You can do this through the use of
an alternate PCB that you define in the application program's PSB. You can also make
the alternate PCB modifiable, so that logic within the program can decide where to send
the message. Make the PCB modifiable by including a MODIFY=YES parameter in the
PCB statement.

You must also code an alternate PCB in the Linkage Section of your application program.
The alternate PCB follows the I/O PCB mask and precedes the database PCB. Figure 3-4
shows a sample alternate PCB and its position in the Linkage Section of a COBOL
program.

78
 Figure 3-4: Sample Alternate PCB.

Message Switching
It is possible for an application to send a message to another application program. To do
this, you must use an alternate PCB and use a transaction code rather than an LTERM
name as the destination. When your application program issues an ISRT call to the
alternate PCB and specifies a transaction code as the destination for the message, the
message is placed in the transaction code message queue rather than an LTERM queue.
The application program receiving the message will process it as with any other message.

Multiple Systems Coupling

You can communicate with terminals and programs in an IMS TM system other than
your own through the use of an IMS facility called Multiple Systems Coupling (MSC).
MSC establishes links between the two (or more) IMS TM systems and keeps track of the
terminals and transaction codes belonging to each one. You can refer to terminals and
transaction codes in your IMS TM system as local and to those in other IMS TM systems
as remote.

In most cases, you will not need to make program changes to communicate with
programs or terminals in a remote system. You perform an ISRT of the destination
against the I/O PCB. MSC handles the message routing. You can determine whether an
input message is from your system or a remote system, and you can set an alternate
destination in a remote system for the outgoing message. IMS uses bits in the message
reserved field to keep track of the origin and destination of messages to and from other
IMS TM systems.

Message Scheduling

79
Message scheduling refers to the process by which an input transaction is united with its
associate application program and is processed. All input and output messages are queued
in message queues in virtual storage by IMS. Messages that are identified by transaction
code or logical terminal can be queued in the order in which they are received. Distinct
serial queues are created for each transaction or LTERM.

When a message has been processed or received by its destination, it is removed from the
queue (dequeued) and the space in the queue is made available for another message.
Figure 3-5 shows the flow of a transaction message.

Figure 3-5: Flow of Transaction Messages.

The scheduling of messages for processing is influenced by a number of factors,

including parameters set in the PSB and others that can be grouped under the general
heading of workload control.

PSB Scheduling
Each MPR can have from one to four message classes. You can assign messages to these
classes by JCL when the PSB is created. Every transaction has a message class, which is
assigned at system definition. Within each message class, messages can be assigned a
priority that is defined at system definition. The control region uses all of these elements
in scheduling messages for processing.

Workload Control

Workload control is based on the combination of a number of parameters that establish

the processing schedule for messages:

Processing Limit

A processing limit can be set for each program. It establishes the maximum number of
messages for that program that can be processed in one scheduling. It is set at system
definition.

80
Limit Priority

If a transaction gets bumped by higher priorities for a certain length of time, its priority is
raised, so that it can be processed eventually. Limit priority is assigned at system
definition.

Parallel Processing

A program may be scheduled for serial or parallel message processing. If it is set for
parallel processing, a parallel limit count establishes when to schedule an additional
region for the program. The limit count is assigned at system definition.

Wait for Input

When an application program is loaded into an MPR, it is left there in a Wait for Input
(WFI) status until its PROCLIM (maximum processing time) is reached. This is true even
if no messages are in the queue.

Quick Reschedule

If no higher class or priority message is waiting and an application program reaches its
PROCLIM, IMS resets the counter to zero without terminating the transaction. This can
be disabled by setting the processing limit to 1.

Pseudo Wait for Input

Pseudo WFI (PWFI) allows the application to remain in the MPR until another input
message is received, even though its PROCLIM has expired. When the next message is
for the PWFI program, this eliminates the unnecessary overhead of terminating the
program and then reloading it for the message. If the message is not for the PWFI
program, the program is terminated.

Application Programs
The value of a database management system lies in its use by application programs to
execute business processes. You can use several types of application programs to access
the data stored in the database:

 MPPs
 BMPs
 interactive Fast Path programs (IFPs)
 batch programs

The types of application programs you can use allow you to use the database in batch
mode only, in online mode, or in a combination of the two. MPPs, BMPs, and IFPs are

81
online programs that execute in the IMS TM online environment. Batch programs are
executed in the IMS batch environment, as discussed in "Online Configuration" on page
3-5. Programs that execute in the IMS TM environment must be defined to IMS before
they can be used. This is done at system definition time in APPLCTN definition macros.
Application programs can be written in COBOL, PL/1, C, VS Pascal, Ada, REXX, or
Assembler language. The databases are accessed through DL/I statements, or calls,
embedded within the application program code.

Message Processing Programs

MPPs are online transaction-initiated programs. They run in real time and can be
interactive with the user. MPPs are loaded dynamically by IMS when a message for the
program is initiated by a user or by another program. Although they are executed
differently, they have the same basic structure as batch programs.

Batch Message Processing Programs

BMPs are initiated by JCL and can access operating system files and IMS databases.
Messages directed to BMPs are held in a message queue until the BMP is scheduled by
the operator. The BMP then reads the messages from its message queue and processes
them.

Interactive Fast Path Programs

IFPs are used for applications that are identified with DEDB databases. IFPs process and
reply quickly to messages from terminals. IFPs bypass IMS scheduling and are processed
by the Fast Path EMH facility. IFPs are used for large transaction volumes that require
rapid response.

DL/I Calls
The purpose of a DL/I call is to instruct DL/I to perform a certain action involving the
data stored in the IMS database. Although a complete description of how to code DL/I
calls is beyond the scope of this manual, you should understand certain concepts
regarding the calls and how they are used. A DL/I call includes four parts:

CALL FUNCTION: Tells DL/I what needs to be done (for example, retrieve, update,
insert, delete).

PCB: Gives the name of the PCB of the database that will be referenced by the call.

I/O AREA: Specifies the work area for the requested segment.

SSA: Specifies the segment and path of the data to be accessed.

82
Figure 3-6 shows the format of a DL/I call in a COBOL application program.

Figure 3-6: Sample DL/I Call Format.

Call Function Codes

Function codes specify the action to be taken by DL/I:

GU (get unique): Retrieves a specific segment. This call command does not depend on
the current position within the database. DL/I always returns the segment specified (if it
exists), regardless of position.

GN (get next): Retrieves the next segment in the hierarchy that satisfies the
qualifications specified. The segment to be retrieved is determined by a combination of
the current position in the database and the segment search argument (SSA). To establish
position, a GU call often precedes a GN.

GNP (get next within parent): Retrieves segments in the order they are physically
stored, just as GN, but limits the call to segments dependent on the established parent.
The SSA tells DL/I which dependent to retrieve. A GNP call without an SSA retrieves
the next dependent.

ISRT (insert): Inserts a new segment occurrence. Before issuing the call, you must code
an I/O area for the new segment. The I/O area must contain the same fields in the same
order, length, and data types that exist on the segment being inserted.

DLET (delete): Deletes the segment previously retrieved and all of its dependents, even
if the application is not defined as sensitive to them. It must be preceded by a GHU,
GHN, or GHNP call (see GET HOLD Calls). Deletes generally do not use SSAs.

REPL (replace): Replaces current data in a selected segment with new data from the I/O
area. Like DLET, it must be preceded by a GHU, GHN, or GHNP call and generally does
not use an SSA. The segment's key fields cannot be changed.

GET HOLD calls: GET HOLD calls have the same format as GET calls:

83
  GHU (get hold unique)
 GHN (get hold next)
 GHNP (get hold next within parent)

The calls hold the segment until it is replaced or deleted or until another segment is
retrieved using the same PCB. GET HOLD calls must be performed before a DLET or
REPL can be issued.

Database PCB Area

The database PCB specifies which database will be referenced by a DL/I call. The
database PCB tells IMS which database view to use and provides a place for IMS to
return results of the call to the application. Figure 3-7 shows an example of the database
PCB entry for a DL/I call in a COBOL application program. The KEY-FEEDBACK field
must be large enough to hold the longest possible concatenated key of the sensitive
segments involved in the SSA.

Figure 3-7: Sample PCB Statement.

84
Database I/O Area
You must establish a working storage area where the segment you request with the call
can be placed. It can also be used to insert or replace a segment. It is coded in much the
same format as that of the PCB example shown in Figure 3-7.

If you are coding an online program, you must include a message I/O area to allow the
program to communicate with terminals.

Transaction Codes
Transactions are messages that have a BMP or MPP (or IFP, in the case of Fast Path) as a
destination. Each type of transaction must be identified to IMS by a transaction code.
Transaction codes must be defined to IMS before they can be used; this is done at system
definition time through the use of TRANSACT macros. Transaction codes are associated
with a specific application program so that IMS can identify which application program
processes the transaction. A transaction can be associated with only one application
program, although an application program can process more than one type of transaction.

1. Transactions are processed in the following sequence:

2. The transaction code is entered at a terminal.
3. The application program associated with the transaction is
initiated.
4. The input message is retrieved from the message queue.
5. The input message is processed by the application program.
6. An output message is sent by the application program.
7. The last three steps are repeated until all messages on the
application program's message queue have been processed.

Segment Search Argument

The SSA is used to specify to DL/I the segment and path of the data you want to access
with the DL/I call. In most cases, a separate SSA is used for each hierarchical level on the
path to the required segment. The SSA may be unqualified or it may be qualified with the
key field name and value of the segment being accessed.

Figure 3-8 gives an example of a typical SSA entry in a COBOL application program.
The KEY-FIELD-VALUE depends on the length of the key field of the segment being
searched.

85
 Figure 3-8: Sample Segment Search Argument.

An SSA contains the following statements:

SEGMENT NAME: This value tells DL/I which segment to access.

COMMAND CODES: IMS command codes can be used here to modify the DL/I call.

LEFT PAREN (OR SPACE): If left blank, the SSA will be an unqualified SSA.

KEY FIELD NAME: The key field, search field, or index field that will be used in the
segment search.

OPERATOR: A relational operator (for example, EQ, GT, LT) can be used.

KEY FIELD VALUE: This is the value of the field that will be processed.

RIGHT PAREN: This statement is used to indicate the end of the SSA.

Conversational Programming
The technique of conversational programming was developed to overcome certain
inefficiencies in the conventional, or non-conversational, way of processing messages. In
many cases, an application program may need to process transactions made up of several
steps. Additionally, the program may need a way of referring to the results of the

86
previous iteration of the transaction. Finally, it is inefficient to allow an application to
reside in memory during the entire time that may be needed for a user to go through a
series of steps that result in a prolonged dialog with the program. Conversational
programming overcomes these problems. The way conversational programming is
implemented is through the use of a scratch pad area (SPA). The use of an SPA is the
major difference between conversational and non-conversational programming.

Scratch Pad Area

The SPA is an area designated in virtual storage to be used store the results of a series of
processing transactions. The SPA is similar in format to an input transaction. It includes a
transaction code field that identifies the transaction code of the program associated with
the conversation. Although the transaction code normally remains unchanged, the
application program can be set up to pass the SPA to another application program during
processing. To do this, the original application program inserts the transaction code of the
program to receive the SPA.

The SPA is read by a GU call to the I/O PCB and message segments are then read with
subsequent GN calls to the I/O PCB. You can write to the SPA by issuing an ISRT call to
the I/O PCB. After issuing the first ISRT call, subsequent ISRT calls to the I/O PCB send
message segments. You can terminate the conversation in two ways. The user can issue
the appropriate IMS command to terminate the transaction or the application program can
terminate the conversation by placing binary zeros in the transaction code field.

Figure 3-9 shows the format of a scratch pad area.

Figure 3-9: Scratch Pad Area Format.

Length: Two-byte field that gives the length of the SPA, including the variable-length
text area.

Reserved: Four-byte field reserved for IMS. This field should not be changed by the
application program.

Trancode: Eight-byte transaction code field. This field is necessary for both input and
output messages.

Text: Variable-length field for use by the application program. This field is also
called the user work area.

87
Expedited Message Handling
The expedited message handling (EMH) facility allows Fast Path transaction messages to
circumvent normal IMS message processing. Use of EMH comes with certain
restrictions. First, you must identify the transaction as a Fast Path type. Second, the
message being processed must meet the criteria of a Fast Path message:

 single segment
 not edited by the MFS
 not an IMS command
 from a VTAM terminal

When you have satisfied these conditions, IMS acquires an EMH buffer and allocates it
for use by the originating terminal for all Fast Path message processing until the session
ends. You can specify the size of the EMH buffer but, if the buffer proves too small,
EMH will return it to the EMH pool and obtain a larger one.

Message Format Service

The MFS facility can be used in formatting messages to and from terminals. MFS
removes device-specific characteristics in input and output messages and eliminates the
necessity of tying all screen panel formatting information to the application program.
This not only makes the program more device-independent but also makes design and
modification of panels easier.

MFS uses four control blocks to separate panel formatting information before a message
goes to the application program for processing and to return it to the message when it
goes to the terminal for display. The four control blocks are as follows:

Device Input Format: Device input formats (DIFs) describe the formats of messages
that MFS
receives from devices.

Message Input Descriptor: Message input descriptors (MIDs) describe how MFS
formats messages for the MPP application to process.

Message Output Descriptor: Message output descriptors (MODs) describe the layout of
the message as it is sent by the MPP application program.

Device Output Format: DOFs describe how MFS formats the message for the device.

Figure 3-10 illustrates the role of the four control blocks in the routing of messages from
terminal to program and back.

88
 Figure 3-10: Message Reformatting by MFS Control Blocks.

A specific DIF, DOF, MID, and MOD must be defined for each unique message used by
an application program. Creating the control blocks can be simplified through the use of
SDF II, an interactive tool for use in designing and generating MFS control blocks. SDF
II provides a panel editor for you to use in creating and testing panels.

Data Sharing
You can allow more than one IMS online system or batch system to have concurrent
access to data stored in a common database. This capability is referred to as data sharing.
If you use IMS to control access to the common data, you will be required to use the data
sharing support provided by DBRC. See "Share Control" on page 3-41.

The databases that can be accessed by an application program must be defined in the
program's PSB. To ensure data integrity, changes to a databases record segment must be
fully committed before the segment is released for access by another program. This data
integrity protection is provided by IMS lock management.

Lock Management
You can choose one of two methods for controlling access to database segments. A
program isolation lock manager can control lock requests for a single IMS system. This is
called local locking. An Internal Resources Lock Manager (IRLM) component can
control lock requests for multiple IMS systems or a single IMS system. This is called
global locking. If you want the dB/DC environment to take part in block-level sharing,
you will be required to use IRLM.

89
When you specify database locking, the entity protected is the database record and the
specific item locked is the root segment. (For HDAM databases, the item locked is the
anchor point, which means that all records chained from that anchor point are also
locked.) Locking occurs when IMS obtains position in the database, and it is held until
position is changed to another database record or until a commit occurs. Whether another
program can obtain concurrent access to the locked record is determined by the
processing option (PROCOPT) defined in the database PCB.

Backup and Recovery

Despite our best efforts and automated procedures, data can sometimes be lost or
corrupted because of a variety of causes, including hardware failure, procedural errors,
abnormal system termination, or faulty application logic. IMS provides processes that
allow data to be recovered to its original state:

 Logging allows IMS to reprocess data from a given point in time.

 Backup utilities create and store valid copies of the database for
use in recovery operations.
 Recovery utilities recreate the recovered database.
 DBRC manages the logs and can be used to manage backup,
recovery, and data sharing.

Backing up a database is like taking out an insurance policy. If you never need to recover
a database, you do not need a backup. However, because most databases are updated and
used regularly, they are subject to disasters. If disaster strikes, you need to be prepared to
recover from it. A copy of a database, referred to as an image copy, provides a complete
backup of the database. When you take an image copy, you create a duplicate of the
database as it exists at that moment in time.

After you discover a problem, you must begin the recovery process. The problem may be
that IMS or the database validation program found a pointer error. A hardware
malfunction may have physically damaged a data set or disabled a disk pack filled with
IMS database data sets. Or someone might have discovered a logic error in an IMS
application program that has improperly updated several databases.

Whatever the reason, the database must be recovered to its exact state before the failure
occurred. Because the database must be taken offline for recovery, it becomes
unavailable to IMS users.

You can recover a database to its exact state before the failure occurred, or you can
recover it to a particular point in time. In either scenario, you must complete the
following steps:

1. Apply the most recent image copy or the image copy taken at the
time to which you want to recover.

90
 2. Apply the changes made after the image copy was taken. These
changes may be in logs or change accumulation data sets or both.
3. Take an image copy of the recovered database, and verify the
pointers. You must have a backup in case you need to recover
again in the future, and you must ensure that the recovered
database is valid. The following sections describe each of these
processes in more detail. Remember that the IMS utilities require
you to take the database offline (making it unavailable to users)
during some or all of the process, depending on the utilities you
choose to use. This unavailability can be a key factor in
organizational operations when it affects business-critical
applications.

Image Copy
IMS provides two utilities to make copies of a database. The Database Image Copy
Utility (DFSUDMP0) creates an as-is image copy of a database. The Online Database
Image Copy Utility (DFSUICP0) can be used to create an image copy of a database while
it is being updated online. Both utilities operate at the data set level, so if the database
consists of multiple data sets or areas, they all must be supplied to the utility. It is
generally recommended that you copy all data sets (the entire database) at the same time.
The frequency you choose to take image copies depends on the recovery requirements of
your organization. You should always create an image copy by using your choice of
utilities after a database reorganization, reload, or initial load.

Logging
IMS automatically keeps a running record, a log, of all significant events that occur
during processing. The events written to the log include IMS startup and shutdown,
program starts and stops, changes to a database, transaction requests received, responses
generated and sent, application program checkpoints, and system checkpoints.

The contents of a log record are shown in Figure 3-11.

Figure 3-11: Log Record Contents.

The contents of the log record fields are as follows:

91
LENGTH: The length of the record, including data and sequence number.

LOGCODE: A hexadecimal log code.

DATA: A variable length field to contain the data being logged.

SEQNO: A consecutive sequence number that shows everything was captured as

intended by the log.

Log information is used for processes other than recovery. It is often used for
performance analysis. All log records are kept internal to IMS and can be
stored in one of five types of log data sets:

 online log data set (OLDS)

 write ahead data sets (WADS)
 system log data sets (SLDS)
 recovery log data sets (RLDS)
 restart data set (RDS)

Online Log Data Set

The OLDS collects data from the online environment only. It includes all the log records
needed for restart and recovery and for batch and dynamic backout. IMS allows you to
specify dual logging, which writes log information on two sets of logs. This provides
extra protection in case of damage to one log set. IMS automatically closes the current
OLDS and opens a new one when the current OLDS is filled. The filled OLDS is written
to the SLDS.

Write Ahead Data Set

WADS contain a copy of committed log records being held in the OLDS buffers before
being written to the OLDS. The WADS ensure that log records based on changes to the
buffer are logged before a database is changed. If an IMS or system failure occurs,
information written to the WADS can be used to complete the content of the OLDS.

System Log Data Set

Logs are archived from the OLDS to the SLDS by the IMS Log Archive utility when the
OLDS is full or inactive. Archiving can be automatic or manual. Automatic archiving is
usually preferred for large systems with a lot of activity because it eliminates the need to
monitor the logging process. You can specify that each OLDS be archived when it is full
or that a number of OLDS be filled before archiving. Manual archiving is usually chosen
when logging needs to be performed infrequently or at irregular intervals.

Recovery Log Data Set

92
The RLDS can be created during execution of the Log Archive utility. It contains change
records only, which makes it usually much smaller than the OLDS or SLDS. The value of
the RLDS in a recovery is that it will process much more quickly.

Restart Data Set

System checkpoint ID information is written to the RDS during logging. This

information, stored in the checkpoint ID table, is used during restart to determine a point
from which to begin the restart. This data is also stored on the log, but the RDS requires
less processing time.

Figure 3-12 shows the relationship of the log data sets.

Figure 3-12: Log data set environment.

Log Contents
Table 3-1 lists common log record types and their meanings.

93
 Log Code Meaning
X'07' application program terminated
X'08' application program scheduled
X'10' security violation
X'20' database opened
X'21' database closed
X'31' GU issued for message
X'41' basic Checkpoint call issued
X'50' database updated
X'52' ISRT about to be performed
X'59' Fast Path log record
X'5F' DL/I call completed

Table 3-1: Log Record Types

Change Accumulation
To recover a database by applying log records to an image copy, you must wait while
IMS reads and applies each change to every changed segment in the database. You can
shorten this procedure significantly if you could skip all the interim changes and read and
apply only the most recent change, because that is all you really need to make the
database current.

You can consolidate the records in the SLDS and RLDS by running the IMS Change
Accumulation utility (or the BMC Software CHANGE ACCUMULATION PLUS
product). The Change Accumulation utility reads the log records and summarizes the
segment changes. The utility produces a change accumulation data set that includes only
the most recent changes organized in sequential order by block number for each data set
summarized. Because the change accumulation data set will be much smaller than the log
data sets, a database recovery will require much less time.

You can update change accumulation data sets by applying new log records periodically.
This creates a new, current change accumulation data set that incorporates any changes
since the last change accumulation was done. To perform a recovery, apply the latest
change accumulation data set to the most recent image copy of the database, with any log
records written since the last change accumulation. Figure 3-13 shows the change
accumulation process.

94
 Figure 3-13: Change Accumulation

Commit Points
Although IMS allows multiple application programs to access a database at one time, it
allows only one program at a time to update individual segments. While your application
has access to a segment, other programs are prevented from accessing the segment until
your program has reached a commit point. A commit point is the point in the program
processing sequence at which the program has completed a unit of work. IMS issues
commit points under the following conditions:

 A program terminates normally. Normal termination always results

in a commit point, except that for Fast Path databases a commit
point must occur before normal termination.
 A Checkpoint call is issued. A Checkpoint call is a means by
which an application program can specifically tell IMS that it has
reached a commit point.
 A new input message is retrieved by an MPP processing in single
mode. At the commit point, IMS makes the changes to the
database permanent and releases the segment for access by other
application programs. For example, your program may receive a
message to update the data contained in a segment or number of
segments located in a database. While the program is retrieving
and updating a segment, IMS protects the segment from processing

95
 by other programs. When the program completes processing, IMS
issues a commit point. Several things happen when the commit
point is reached:
 IMS makes the changes to the database permanent.
 IMS releases the segment or segments it has locked
since the last commit point.
 The current position in the database (except GSAM)
is reset to the beginning of the database.

Checkpoints
Because some programs do not have built-in commit points, IMS provides a means
whereby an application program can request a commit point. This is done through a
Checkpoint call. A Checkpoint call tells IMS that the program has reached a commit
point. A checkpoint provides a point from which the program can be restarted.
Checkpoint calls are primarily used in the following programs:

 multiple-mode programs
 batch-oriented BMPs
 batch programs
 programs running in a data sharing environment

Checkpoint calls are not needed in the following programs:

 single-mode programs
 database load programs
 programs that access the database in read-only mode and with
PROCOPT=GO that are short enough to be restarted from the
beginning
 programs that have exclusive use of the database IMS provides for
two types of Checkpoint calls-basic Checkpoint calls and symbolic
Checkpoint calls.

Basic check point calls can be used by any type of program, but they are the only type of
Checkpoint call allowed for MPPs and IFPs. Basic Checkpoint calls do not support MVS
or GSAM files and do not support the Restart call. Symbolic Checkpoint calls can be
used by BMPs and batch programs. Symbolic checkpoints allow a program to specify as
many as seven data areas to be checkpointed. The Restart call restores these designated
areas to the condition they were in when the symbolic Checkpoint call was issued.

A Checkpoint call produces the following results:

 IMS makes the changes to the database permanent.

 IMS releases the segment or segments it has locked since the last
commit point.

96
  The current position in the database (except GSAM) is reset to the
beginning of the database.
 IMS writes a log record (containing the checkpoint identification)
to the system log.
 IMS sends a message (containing the checkpoint identification) to
the system console operator and to the IMS master terminal
operator.
 IMS returns the next input message to the program's I/O area.
 If your program also accesses DB2, IMS tells DB2 that the
changes your program has made can be made permanent. DB2
makes the changes to the DB2 database permanent.

Backout
IMS will back out changes to a database automatically if a MPP or BMP application
program terminates abnormally before reaching a commit point. IMS also performs a
backout if an application program issues a Roll backout call (ROLL), Roll Back backout
call (ROLB), or Roll Back to SETS (ROLS) call. So that IMS can perform the backout if
needed, and so users will not receive information that may prove to be inaccurate, IMS
holds output messages until a program reaches a commit point. In an abnormal
termination of the program, IMS discards any output messages generated since the last
commit point.

If an application program terminates abnormally while processing an input message, IMS

may discard the input message, depending on the type of termination. In all cases, IMS
backs out uncommitted changes and releases locks on any segments held since the last
commit point. You can use DL/I calls to manually back out database updates. The
backout calls include

 ROLB
 ROLL
 ROLS
 Set a Backout Point (SETS)
 SET Unconditional (SETU) ROLB, ROLL, and ROLS calls
produce three common results:
 All database changes since the last commit are backed out.
 All output messages (except EXPRESS PURG) since the last
commit point are discarded.
 All segment locks are released.

ROLB, ROLL, and ROLS calls differ in the following ways:

 ROLB returns control to your program and places the first segment
of the first message after the last commit point into the I/O PCB.
 ROLL abends with user code 0778. All messages retrieved since
the last commit point are discarded.

97
  ROLB abends with user code 3303. All messages retrieved since
the last commit point are returned to the message queue.

A SETS call can be used to set up to nine intermediate backout points to be used by the
ROLS call. It can also be used to cancel all existing backout points. SETS can be
combined with a ROLS call to back out pieces of work between the intermediate backout
points.

To set the intermediate backout point, issue the SETS call by using the I/O PCB and
including an I/O area and a 4-byte token. To back out database changes and message
activity that has occurred since a prior SETS call, issue a ROLS call that specifies the
token that marks the backout point you have selected. IMS then backs out the database
changes made since the SETS token specified. It also discards all non-express messages
since the token. A SETU call operates like a SETS call except that it ignores certain
conditions under which the SETS call is rejected. A SETS call is not accepted when
unsupported PCBs exist in the PSB (PCBs for DEDB, MSDB and GSAM organizations)
or an external subsystem is used.

Restart
A Restart call lets you restart a program after an abnormal termination. It must be coded
as the first call in the program. When you use the Restart call the following actions occur:

 The last message is returned.

 The database position is reestablished.
 Up to seven specified data areas are returned to their condition at
the last checkpoint.

Database Recovery Control

DBRC is a part of IMS that allows easier maintenance and recovery of IMS DL/I
databases, including Fast Path DEDBs and databases accessed through CICS. Although
originally written to keep track of logs, change accumulation, and other log and tracking
information, DBRC now performs a variety of tasks that fall under the general headings
of log control, recovery control, and share control. Although it is optional for batch
processing, DBRC is required for online transaction processing.

During online processing, DBRC occupies its own MVS address space. IMS
communicates with DBRC through the IMS TM control region to supply DBRC with the
information it will require to provide the log control, recovery control, or share control
services requested. When used in batch processing, or the execution of CICS or IMS
utilities, DBRC is loaded as part of the IMS dB code in the batch region.

98
RECON Data Sets
IMS communication with DBRC is performed through the use of three VSAM KSDS
data sets, called Recovery Control (RECON) data sets. The RECON data sets contain all
of the recovery information used in recovering registered databases. RECON data sets are
used by IMS to record system log and database status information that is used in
recovery, image copy, and reorganization operations. RECON data sets are also used in
DBRC's control of database sharing and are required for IMS online operation. Because
RECON data sets are critical to the functions performed by DBRC, three copies of the
data sets are maintained. The primary RECON data set is referred to as RECON1, or
Copy1. The second data set is called RECON2, or Copy2. The third is usually referred to
as RECON3, or SPARE. The ddnames associated with the RECON data sets are
RECON1, RECON2, and RECON3. The RECON data sets may be dynamically allocated
by generating MDA members in RESLIB.

RECON data sets contain several types of records, each of which is associated with a
particular function of DBRC. A RECON header record is created for each RECON data
set to provide information that DBRC uses in managing the system. Other records are
created to maintain log control, change accumulation, image copy, database data set,
reorganization, and recovery information.

Log Control
DBRC controls the use and availability of OLDS, SLDS, RLDS, and interim log data
sets. Information about the logs is stored in a set of RECON data set records called log
data set records. If you requested dual logging, they are referred to as PRILOG (the
primary log) and SECLOG, (the secondary log). DBRC also creates log allocation
(LOGALL) records to identify a database that was changed while its log data set was
open.

Figure 3-14 illustrates the relationship between DBRC and the log data sets.

99
 Figure 3-14: DBRC Log Control.

Recovery Control
DBRC controls the recovery of databases by supplying the necessary input for the IMS
Recovery utility. To use the recovery control portion of DBRC, you must register your
databases with DBRC. Recovery control does not choose the correct utility to be run at
the correct time. For example, you must select the correct utility to run in the following
circumstances:

 image copy after reorganization

 recovery after database I/O error
 backout after batch failure
 /ERE after online failure

DBRC performs two types of recovery-full recovery and time stamp recovery.

A full recovery means that you have restored all of the database updates that were
performed since the image copy was taken. It requires a valid image copy of the database,
all log data sets created since the image copy was taken, and any change accumulation
data sets.

100
A time stamp recovery recovers the database to a selected point in time. A time stamp
recovery can use any image copy of the database. Then updates (using logs and change
accumulation data sets) are applied up to a selected point in time. A time stamp recovery
results in an older version of the database. You may need an older version because of
application logic that corrupted the most current database. Or the point in time you have
selected to recover to may have been the last time the database was valid.

A time stamp recovery is usually used when the database has been corrupted through a
processing error such as faulty application logic. A full recovery is most often used when
the data has not been corrupted but the database has been lost through something like a
hardware or reorganization failure. The data was not corrupted; the database simply
crashed.

Share Control
IMS lets you determine the degree to which database records can be shared by
application programs or users. When using DBRC in the share control mode, DBRC
enforces the share level you have defined. To use DBRC share control, you must register
the database to DBRC and define the level of sharing you want. IMS allows four levels of
data sharing:

SHARELEVL 0 No sharing. The database can be accessed only by the subsystem to which
it has been authorized.
SHARELEVL 1 Database-level sharing. The owner subsystem can perform updates, but
other subsystems are read only.
SHARELEVL 2 Intra-host block-level sharing. Subsystems executing on the same MVS
have full update authority.
SHARELEVL 3 Inter-host block-level sharing. Subsystems operating on the same (or any
other) MVS have full update authority.

Levels 2 and 3 require use of the IRLM. You specify the share level when you register
the database with DBRC. Use of share control automatically invokes DBRC log control
and recovery control.

101