ims documentation

IMS/DB PROGRAMMING I

MODULE I : IMS DATABASE STRUCTURES.....................................................5

General Database Objectives ....................................................................................5Introduction......................................................................................................................... 5Database Goals...................................................................................................................5

IMS Hierarchical Structure Components ..................................................................6Common Database Structures.............................................................................................6Relational Databases...........................................................................................................6Network Databases.............................................................................................................6Hierarchical Databases........................................................................................................7IMS/VS................................................................................................................................ 7IMS Hierarchical Components..............................................................................................7Segments............................................................................................................................ 7Fields.................................................................................................................................. 8Field Types.......................................................................................................................... 8

Concepts of Root, Parent, and Child ......................................................................10Parent and Child Segments...............................................................................................10Parent Segments...............................................................................................................10Child Segments................................................................................................................. 10Root Segments..................................................................................................................10Dependent Segments........................................................................................................10IMS Limitations.................................................................................................................. 10Segment Occurrences.......................................................................................................10Review.............................................................................................................................. 11Summary........................................................................................................................... 11

MODULE II : THE IMS ENVIRONMENT.............................................................12

Components of an IMS Environment ......................................................................12Introduction........................................................................................................................ 12Data Language I................................................................................................................12IMS DB/DC System...........................................................................................................12Components of the IMS Environment.................................................................................12

Modes of Processing ...............................................................................................14Modes of Processing.........................................................................................................14Batch DL/I Processing.......................................................................................................14TP/MPP............................................................................................................................. 14Batch Message Processing (BMP).....................................................................................14Hierarchical Data Structure................................................................................................14The Physical Database......................................................................................................14The Logical Database........................................................................................................15

Physical Database Definition ...................................................................................16Defining the Physical Database..........................................................................................16DBDGEN........................................................................................................................... 16DBDGEN Control Statements............................................................................................16DBD Statement.................................................................................................................. 16DATASET Statement.........................................................................................................16SEGM Statement...............................................................................................................16FIELD Statements.............................................................................................................17ENDING the DBDGEN Process.........................................................................................17

Logical Database Definition ....................................................................................18Defining the Logical Database............................................................................................18Program Specification Block (PSB)....................................................................................18

IMS/DB - 1

Program Communication Block (PCB)................................................................................18PROCOPTs....................................................................................................................... 18Example of PSB with One PCB..........................................................................................19Summary........................................................................................................................... 19

MODULE III : IMS APPLICATION PROGRAMMING.........................................20

Function Codes ........................................................................................................20The Working-Storage Section............................................................................................20Function Codes.................................................................................................................20GET-HOLD Function.........................................................................................................20

Segment Search Arguments (SSAs) .......................................................................21SSA Overview...................................................................................................................21

I/O Area ..................................................................................................................... 21The Input/Output Area.......................................................................................................21

PCB Mask ................................................................................................................. 23The Program Communication Block...................................................................................23

Procedure Divisions .................................................................................................24Procedure Divisions...........................................................................................................24The Entry Statement..........................................................................................................24DL/I Retrieval Calls............................................................................................................24The Exit Statement............................................................................................................24IMS Components...............................................................................................................24Summary........................................................................................................................... 25

MODULE IV : SEGMENT SEARCH ARGUMENTS...........................................26

Unqualified SSAs .....................................................................................................26Segment Search Argument................................................................................................26Unqualified SSAs...............................................................................................................26Unqualified SSA Example..................................................................................................26Qualified and Unqualified SSAs..........................................................................................27

Qualified SSAs .........................................................................................................28Qualified SSAs.................................................................................................................. 28Qualified SSA Example......................................................................................................28

OPERATOR Field .....................................................................................................29OPERATOR Field..............................................................................................................29

Command Codes ......................................................................................................30COMMAND-CODE Field....................................................................................................30F Command Example........................................................................................................30Other Uses of COMMAND CODES....................................................................................31Summary........................................................................................................................... 31

MODULE V : DL/I RETRIEVAL CALLS.............................................................32

DL/I CALL Statement ................................................................................................32DLI CALL Statement..........................................................................................................32Parameters/Arguments......................................................................................................32Accessing an IMS Database..............................................................................................33

Segment Sequence ..................................................................................................33Segment Sequence Review...............................................................................................33

Function Codes ........................................................................................................34Function Codes.................................................................................................................34GET UNIQUE (GU)...........................................................................................................34Building a GU Call.............................................................................................................34

2 – IMS/DB

Verifying the GU call..........................................................................................................35Status Codes..................................................................................................................... 35GET NEXT (GN)................................................................................................................35No SSA............................................................................................................................. 36Unqualified SSA.................................................................................................................36Qualified SSA....................................................................................................................36GET NEXT PARENT (GNP)..............................................................................................36Establishing Parentage......................................................................................................37Additional Example............................................................................................................37Function Codes.................................................................................................................37Specifying a Path of Segments..........................................................................................38

PATH Calls ...............................................................................................................38PATH Calls........................................................................................................................ 38Coding a Segment.............................................................................................................38One Final Word About PATH Calls....................................................................................39Summary........................................................................................................................... 39

IMS/DB PROGRAMMING II

MODULE I : UPDATING SEGMENTS................................................................39

GET HOLD Calls .......................................................................................................39GET Functions..................................................................................................................39GET HOLD Calls...............................................................................................................39Maintaining Data Integrity..................................................................................................39

REPLACE Call ..........................................................................................................41The REPL Call................................................................................................................... 41Example of the REPL Call..................................................................................................41REPL Status-Codes...........................................................................................................42

REPLACE with Command Codes ............................................................................42The REPL Call................................................................................................................... 42Example of an REPL Function...........................................................................................42Relationships Between Functions.......................................................................................43Summary........................................................................................................................... 43

MODULE II : INSERTING AND DELETING SEGMENTS..................................43

INSERT Calls to Load a Database ...........................................................................43Insert Function Code.........................................................................................................43Program Specification Block..............................................................................................43Load Mode........................................................................................................................ 43HSAM................................................................................................................................ 44HISAM............................................................................................................................... 44HDAM............................................................................................................................... 44HIDAM.............................................................................................................................. 44Insert Mode....................................................................................................................... 44ISRT Function Code..........................................................................................................44INSERT RULE Options......................................................................................................44

INSERT Calls to Add a New Segment .....................................................................46INSERTing New Segments................................................................................................46Check STATUS CODE......................................................................................................46INSERTing New Segments................................................................................................47

DELETE Calls ...........................................................................................................48DELETE Segments............................................................................................................48GET HOLD and DELETE Functions...................................................................................48GET HOLD Precedes DELETE..........................................................................................49

IMS/DB - 3

DLET Call Status Codes....................................................................................................49Using SSA’s with DLET.....................................................................................................50COMMAND CODE in a DLET Call.....................................................................................50Summary........................................................................................................................... 50

MODULE III : PROGRAMMING TECHNIQUES.................................................51

Status Code Checking .............................................................................................51Introduction........................................................................................................................ 51Status Codes..................................................................................................................... 51Checking GET Calls..........................................................................................................51Unexpected Status Codes.................................................................................................51

Standard Abend/Error Routines ..............................................................................52The DL/I Standard Error Routine........................................................................................52Abending the Program.......................................................................................................52

Efficient Segment Access Strategy .........................................................................53Segment Access................................................................................................................53ISRT Calls......................................................................................................................... 53Hierarchical Access...........................................................................................................53Segment Search Arguments..............................................................................................53Search Fields....................................................................................................................53Secondary Indices.............................................................................................................54Multiple PCBs....................................................................................................................54Review of BMPs................................................................................................................54Advantages and Disadvantages.........................................................................................54

Checkpoints .............................................................................................................55Checkpoint Calls................................................................................................................55Two Kinds of Checkpoint Calls...........................................................................................55Frequency of Checkpoint Calls...........................................................................................55Standards and Guidelines..................................................................................................55Summary........................................................................................................................... 55

MODULE IV : COMPILING, EXECUTING, AND DEBUGGING.........................56

Compiling and EXECUTION JCL .............................................................................56Compiling.......................................................................................................................... 56Application Components....................................................................................................56IMS Subroutine..................................................................................................................56Subroutines....................................................................................................................... 56

Debugging with DL/I Test Program DLT0 ...............................................................57The EXECUTE JCL...........................................................................................................57Testing Tools..................................................................................................................... 57Control Statements............................................................................................................57DLT0 JCL and Control Statements.....................................................................................58Coding Errors....................................................................................................................58The Linkage Section..........................................................................................................58Linkage Example...............................................................................................................59Debugging a Program........................................................................................................59Summary........................................................................................................................... 59

4 – IMS/DB

IMS/DB PROGRAMMING I Module I : IMS Database Structures

General Database Objectives IMS Hierarchical Structure Components

Concepts of Root, Parent, and Child

IntroductionA database is a concept, or a way of organizing data and software, to solve some of the problems found in conventional file processing. The database concept solves the problems of:

Duplication of data and effort. Programmers needing to know exact file structure. People looking at files to which they should not have access. Programs needing to be changed when the method of organizing data is altered.

Database GoalsDatabases are used to meet four main data-related goals:

1. Increasing data independence. In traditional processing environments, the data and the programs are

dependent on each other. If the format of the data is changed or reorganized, the programs dependent on that data must also be changed.

In database processing, the data and the programs are independent.2. Maintain data integrity.

Everyone who uses the database is responsible for the integrity of the data. Maintaining the accuracy (integrity) of the data is very important in a

database system, because the database is shared by many users. Without integrity, the data could be invalid or unreliable. Centralized control

of the database ensures the data integrity is maintained.3. Reducing data redundancy.

In a conventional file system, the same data may be stored in many different files to meet the requirements of different applications. Thus, some of the data is unnecessarily repeated (redundant). With traditional file processing, it is possible to find a customer’s address repeated in many files w/in:

a customer’s records system a purchase order system an accounts receivable system

This redundancy in the conventional file processing system could cause problems when a customer’s address changes. The address must be changed in each of the files, causing duplication of effort and more opportunities for errors. In a database system, different application systems share the same centralized data.

4. Increase Data Security. You are already familiar w/ some forms of data security. For example, you

have to supply a password to access remote computers. Databases often use passwords for protection. Once you gain access, there

are further restrictions on how you can access data itself.Example: A programmer can read, but not update certain data.Example: Only certain people may be allowed to access salary data.

IMS/DB - 5


General Database Objectives IMS Hierarchical Structure Components


Common Database StructuresHow databases are organized: There are three common types of database structures:

1. Relational2. Network3. Hierarchical

Relational DatabasesA relational database looks something like this:

Key field

(An employee record)

Key field

(A department record)

Fields in one record type are used to point to other record types.

Network DatabasesA network database might look like this:

Here, data is organized so that the PERSON segment is directly dependent on both COMPANY and CLUB. Segments are equivalent to records in flat file structures.

In a network database structure: Segments are related to one another as superiors and subordinates. A segment may relate downwards to one or more subordinates. A segment may relate upwards to one or more superiors. This is what distinguishes a

network structure from a hierarchical structure, which we will see next.

A network database structure can be considered an expansion of a hierarchical structure.

6 – IMS/DB

Soc. Security #Soc. Security # DataData

Datad

Datad

CompanyCompany ClubClub

BuildingBuilding VehicleVehicle PersonPerson

Hierarchical DatabasesIMS/VS is a hierarchical database. A diagram representing a hierarchical database would look like this:

Note that each segment is directly dependent on one segment only. This structure is often referred to as the inverted tree structure.

In a hierarchical database: There is always a basic or ‘root’ segment. A segment may be related downwards to one or more subordinate segments; these

subordinates are referred to as ‘child’ segments. A subordinate (child) segment may relate upward to only one superior or ‘parent’

segment.

IMS/VSSince this course will be dealing w/ IMS/VS, let’s begin by defining IMS.

Definition: IMS/VS is an acronym that stands for Informational Management System/Virtual Storage. It is IBM’s software product for creating and managing the physical storage and retrieval of data that is organized using the hierarchical data structure.

Note: Our definition does not mention access. In order to access IMS databases, you need a user interface language; DL/I.

Sample DatabaseThroughout the remainder of the course, we will be using an example database. Part of our PERSONNEL database looks like this:

IMS Hierarchical ComponentsIf you want to work effectively with IMS, you should know what the components of its hierarchical structure are and how they are related. We’ll be discussing these components by defining terms such as: SEGMENT, FIELD, PARENT, and CHILD. You will be seeing a lot of these terms in upcoming modules. SegmentsEach box in the database hierarchy chart represents a segment.

IMS/DB - 7

StudentStudent

ClubClub

DegreesDegrees High SchoolHigh School

CommentsComments

RegistrationRegistration

ReportsReports

EmployeeEmployee

DependentsDependents Benefit DataBenefit DataWork HistoryWork History

Definition: In most situations, a segment is the smallest block of information that the DL/I can access in the database.

Each segment has a unique name.In our PERSONNEL database, the segments are called:

Depending on your application program, DL/I reads segments that point to other segments in a specified sequence.

Here’s one way DL/I could read segments to get all the employee information. The hierarchical path through the database starts at the root segment, proceeds through intermediate segments, and ends at the last segments at the bottom of the structure.

In a COBOL program, we define segments in the working-storage area. This is similar to the way we define records in a standard File Definition (COBOL FD).

Common practice is to redefinethe Input/Output area. As anillustration, part of your EMPLOYEEdatabase might be defined like this:

FieldsAlthough the segment is the smallest unit of information that DL/I can handle, it is not the smallest unit in the database. The field is the smallest unit of information. Each segment contains one or more fields of information.

Field TypesTwo types of fields deserve special mention. They are SEARCH fields and KEY fields. Both fields supply search criteria (at the field level) to aid DL/I in selecting a desired segment. Both

8 – IMS/DB

EmployeeEmployee

DependentsDependents Benefit DataBenefit DataWork HistoryWork History

01 IO-AREA PIC X(100). 01 EMPLOYEE REDEFINES IO-AREA.

05 EMP-ID PIC X(11).05 EMP-LASTNAME PIC X(15).05 EMP-FIRSTNAME PIC X(15).05 EMP-PHONENUM PIC X(10).. . .

01 WORK-HISTORY REDEFINES IO-AREA.05 DEPT-ID PIC X(10).05 POSITION PIC X(12).05 BEGIN-DATE PIC X(8).05 REVIEW-DATE PIC X(8).. . .

KEY and SEARCH fields must be defined to IMS. You will see how when we look at the database description.

The difference between KEY and SEARCH fields is that: The KEY field is used to sequence the segments. Because of this, the value in a

KEY field may not be changed. In contrast, you can change the SEARCH fields depending on your application

program.

IMS/DB - 9


General Database ObjectivesIMS Hierarchical Structure Components


Parent and Child SegmentsIn previous frames it has been implied that segments of an IMS database are related to each other. How are the segments related? Segments are related in much the same way as parents and children. In fact, ‘parent’ and ‘child’ are actual terms used to describe the relationship between segments.

Parent SegmentsA parent segment is a segment that has one or more segments dependent on it. These dependent segments must be on the level directly below the parent. Segment 1 is the parent of segments 2, 3, and 4.

Child SegmentsA child segment is a segment that is directly dependenton another segment. Segments 5 and 6 are both child segments of segment 4, since they are directly dependent on segment 4.

Root SegmentsSegment 1 is a root segment because it has no parent. All hierarchical database structures have a single root segment at the top.

Dependent SegmentsDependent segments are all the segments under a particular segment of a database. In our chart, segments 2, 3, 4, 5, and 6 are dependents of segment 1. Dependents of a segment do not have to be children of that segment. Here only 2, 3, and 4 are the children of 1.

Here’s a tip to tell the difference between dependents and children. The children of a segment will always be on the same level directly below the segment, but dependents of a segment can extend downwards. Since 2, 3, and 4 are on the same level below 1, they are the children of segment 1. Segments 5 and 6 are only dependents of segment 1.

IMS LimitationsIMS lets you define up to 255 different segment types and up to 15 different levels in the hierarchy, but these limits are seldom reached. You will note that the example database (above) has 6 segment types and 3 levels.

Segment OccurrencesYou have a ‘twin’ when a parent segment has multiple occurrences of a particular child segment. We call those children twins. You will notice that there are 3 occurrences of segment 5. The three occurrences of segment 5 are called twins (even though there are three of them). You can have as many segment occurrences as you want, as long as your storage medium can handle them.

10 – IMS/DB

66

1. Parent1. Parent

33 4422

55

Jackie Herrera, 01/03/-1,

Segments 5 and 6 are not twins, they are known as siblings under segment 4. Similarly, segments 2, 3, and 4 are siblings.

ReviewWith all these terms behind us, we could say that a database consists of all occurrences of the root segment and all their dependent segments as shown below. In a database record we have only one occurrence of the root segment and all its dependent segments. Your application program calls DL/I to access information from one database record at a time. Each DL/I call works one segment or a path of segments from this database record.

There are 3 database records here:

SummaryBy now you should be familiar with:

what a database is four key phrases that describe data-related goals the components of the IMS hierarchy the relationships between hierarchical components

IMS/DB - 11

IMS/DB PROGRAMMING I Module II : The IMS Environment

Components of an IMS Environment Modes of Processing

Physical Database DefinitionLogical Database Definition

IntroductionIBM’s IMS (Information Management System) is one of the oldest database management systems in use, and one of the most sophisticated in terms of options and features. At the heart of IMS are its ‘hierarchical’ databases and its database manager, DL/I.

Data Language IData Language I, referred to as DL/I, is not a programming language like COBOL, PL/I or ASSEMBLER. DL/I are a set of IMS program modules that exist external to the application program. DL/I allow an application program to retrieve segments of the data from the database sequentially or directly.

IMS DB/DC SystemIMS supports user-written batch processing and telecommunication applications. It provides:

Database management services that support multiple applications using a common database.

The database services are called the database or ‘DB’ system. Data communications management services that support multiple terminal-oriented

applications using a common database. The data communications services are called the Data Communication or

‘DC’ system.

When the DB system and DC system are combined, they form the IMS DB/DC system.

Components of the IMS EnvironmentThe components of the IMS software environment are:

Application programs: You can write these in COBOL, PL/I and ASSEMBLER. The programs use standard calls to the DL/I modules rather than read and write through FD’s.

DB PCB: This is a Program Communication Block (PCB) which enables the program to communicate with DL/I to get information from the database.

DL/I: Data Language I is a set of program modules that performs operations on the database when called by application programs.

IMS Database: The database could be called the center of the IMS system. It normally resides in direct access storage.

I/O PCB: This is a Program Communication Block (PCB) that enables the program to communicate with IMS Data Communication to read or write information to/from a terminal.

IMS Data Communication: A set of programs that permit application programs to communicate with other programs and/or remote terminals through the standard calls.

Terminal: An interactive terminal used for on-line applications.

12 – IMS/DB

Here is the processing flow when you are in DL/I batch processing mode:

Here is the processing flow for on-line processing:

IMS/DB - 13

ApplicationProgram

DBPCB

I/OPCB

DL/IIMS Data

Communication

Terminal

ApplicationProgram

DBPCB

I/OPCB

DL/IIMS Data

Communication

Terminal

start

IMS Database

IMS Database

start


Components of an IMS Environment Modes of Processing Physical Database DefinitionLogical Database Definition

Modes of ProcessingWithin IMS there are three modes of processing:

1. BATCH DL/I - Batch Data Language I (true batch processing)2. TP/MPP Teleprocessing/Message Processing Program (true on-line processing)3. BMP - Batch Message Processing (combination of on-line and batch processing)

Batch DL/I Processing No data communication services or terminals are used. Transactions are batch-generated and saved in standard files. Runs are initiated using JCL (Job Control Language). Databases accessed are off-line.

TP/MPP Transactions are entered at the terminal. Transactions are put in a message queue file. (A message queue is a stored

collection of messages related to a specific transaction code.) IMS Scheduler immediately invokes the appropriate program to process the

transactions. Processing output may be sent back as a screen message to the originating terminal,

or an alternate terminal. Databases accessed are on-line.

Batch Message Processing (BMP)There are two types of Batch Message Processing:

1. Transaction-oriented can read and write to the on-line message queues. can process input from and output to OS/VS files and databases

2. Batch-oriented accesses on-line databases in batch mode. can only read message queues.

Both BMP types are scheduled by the operator using JCL.

Hierarchical Data StructureIn Module 1, we discussed the hierarchical data structure. It is important to understand:

How these structures are defined and created in IMS. How the access to some portion or the whole structure is tailored for each application

program.

The Physical DatabaseThe physical database represents how the data is actually recorded or stored on the storage medium (usually disk). IMS database storage is divided into two basic organizations:

1. Hierarchical Direct (HD)In HD storage, database records consist of two components: a segment occurrence,

and direct access pointers. The records are stored in the order in which segments are created.

2. Hierarchical Sequential (HS)

14 – IMS/DB

In HS storage, database records composed of the root segment and all of its dependent segments are stored in hierarchical sequence:

from top to bottomfrom left to right

The Logical DatabaseThe logical database represents the sequence of segments from one to more physical databases required by an application program. These segments are combined to create a new logical data structure.

The physical database is defined in the Database Description (DBD). Whereas… The logical data structure is defined in the Program Specification Block (PSB).

IMS/DB - 15


Components of an IMS EnvironmentModes of Processing

Physical Database Definition Logical Database Definition

Defining the Physical DatabaseDefining the physical database is often the responsibility of the DBA. The DBA asks the database design team for the following information:

1. The hierarchical structure.2. The key fields.3. The search fields.

DBDGENThe DBA initiates a process called DBDGEN (Database Description Generator) to describe the physical structure of the database and to create a DBD (Database Description). In theory, this process needs to be performed only once for each database. However, in practice, as the database evolves, new segments are added, existing segments are expanded, and key fields or search fields are added or changed. All of these events require a new DBDGEN.

DBDGEN Control StatementsHere is an example of how to code a DBD using DBDGEN control statements. We will use our EMPLOYEE database.

DBD StatementThe DBD statement:

names the database identifies the access method as HIDAM (Hierarchical Indexed Direct Access

Method).The other most popular IMS access method is HDAM (Hierarchical Direct Access Method).

DATASET StatementThe DATASET statement specifies:

the DD name used in the JCL the Disk DEVICE type (e.g. 3380) the Blocksize (e.g. 4096) the percentage of Freespace (FRSPC)

SEGM StatementThere is one SEGM statement for each segment in the database. The SEGM statement:

16 – IMS/DB

DBD NAME=EMPLOYEE,ACCESS=(HIDAM,OSAM) DSGROUP0 DATASET DD1=DDEMP,DEVICE=3380,SIZE=(4096),FRSPC=(10,10)

SEGM NAME=EMPDATA,PARENT=0,BYTES=100FIELD NAME=(EMPID,SEQ,U),BYTES=11,START=1,TYPE=CSEGM NAME=WORKDATA,PARENT=EMPDATA,BYTES=200FIELD NAME=(DEPTID,SEQ,U),BYTES=5,START=1,TYPE=C

. . .DBDGENFINISHEND

names the segment (max 8 characters) identifies the PARENT segment establishes the length of the segment

Note: PARENT=0 signifies that EMPDATA is the root segment.

FIELD StatementsField statements are used to define KEY fields and SEARCH fields.

SEQ defines EMPID to be a KEY field U defines EMPID to be a UNIQUE key BYTES defines the field size START defines starting position in the segment for this field TYPE defines field type, for example, C = character field.

To define a SEARCH field, only specify the NAME subparameter in the NAME operand.

ENDING the DBDGEN ProcessThe last 3 lines of code indicate the end of the DBDGEN process. You may not have to use the DBDGEN process very often in your work environment. But you may need to look at DBD’s to find out, for example, what the key fields or search fields are in a particular segment.

IMS/DB - 17


Components of an IMS EnvironmentModes of Processing

Physical Database Definition Logical Database Definition

Defining the Logical DatabaseNow that we have seen the process for creating a physical database, let’s turn our attention to the logical data structure and it definition. Let’s say that your program needs to access WORK-HISTORY data for all employees in the EMPLOYEE database:

The ‘logical’ view of the access path you program will take is EMPLOYEE WORK-HISTORY

Program Specification Block (PSB)You have seen how a logical database is represented. In an IMS database, this logical data structure is referred to as a PSB (Program Specification Block). Now it’s time to learn how the logical database is created. First, the design team (analysts and programmers) decides what logical data structure is required of each program. The PSB is made up of one or more PCB’s (Program Communication Block), and this defines the logical structure a program will use.

The PSBGEN process produces a load module stored in the PSBLIB library. These load modules are called PSB’s.

The PSB is a control block that defines the logical data structure a program will use.

While many application programs can share the same PSB (but usually do not), programs can only use one PSB in a given application.

The PSB supplies IMS with a description of what database information (which database segments) may be accessed by the application program.

Program Communication Block (PCB)You have seen that a PSB is made up of one or more PCB’s.

The Program Communication Block (PCB) defines which of the segments in the database the program is ‘sensitive’ to (can access).

The PCB also defines how the application program is allowed to process the segments. This is done via the ‘processing options’ or PROCOPT.

PROCOPTsValid PROCOPTs include:

G for GET (READ)I for INSERTR for REPLACED for DELETE

18 – IMS/DB

EMPLOYEEEMPLOYEE

DEPENDENTSDEPENDENTS BENEFIT-DATABENEFIT-DATAWORK-HISTORYWORK-HISTORY

A for all options (G,I,R,D)L for LOAD (initial load of data)K for access to only the KEY of the segmentO for ONLY - used with G to indicate that Get Hold calls are not allowedP for PATH calls

Example of PSB with One PCBHere’s an example of a PSB w/ only one PCB. It defines a logical data structure:

This PSB will allow your program access the key only in the root segment EMPDATA (PROCOPT=K)…and READ access to the WORKDATA segment (PROCOPT=G). No other segment in the database may be accessed with the PSB, EMPPSB1.

DBDNAME tells IMS what database the program needs access to. The KEYLEN parameter of the PSB is the length in bytes of longest concatenated key for the segments requested in the PSB. A concatenated key contains the key of the root segment, followed by the key of each dependent segment, down to the lowest segment of interest. It defines the path from the root segment to the segment being referenced. Segment key length may be found in the DBD - refer to MODULE 1 or ask the DBA.

SENSEG statements define the name of the segments in the database that your program needs access to. PROCOPT defines how the segment may be accessed (G,I,R,D,A,K,L, etc.)

The LANG parameter on the PSB statement tells IMS what programming language will use the PSB (COBOL, PL/I, ASSEMBLER). PSBNAME gives the PSB a name (usually the same name as the application program name that will use the PSB. Note: Other parameters may be specified in the PSB. Ask your DBA or IMS Systems Support person for details.


components in the IMS environment the three IMS processing modes physical database as defined in DBD logical database as defined in PSB

IMS/DB - 19

PCB TYPE=DB,DBDNAME=EMPDBD,KEYLEN=16 SENSEG NAME=EMPDATA,PARENT=0,PROCOPT=K SENSEG NAME=WORKDATA,PARENT=EMPDATA,PROCOPT=G PSBGEN LANG=COBOL,PSBNAME=EMPPSB1 END

IMS/DB PROGRAMMING I Module III : IMS Application Programming

Function Codes Segment Search Arguments (SSAs)

I/O AreaPCB Mask

Procedure Divisions

The Working-Storage SectionThe first section containing any IMS-related components is the WORKING-STORAGE SECTION. Let’s begin by looking at the three highlighted components:

1. FUNCTION CODES2. INPUT/OUTPUT AREA3. SEGMENT SEARCH ARGUMENT(SSA)

Function CodesA function code is a 4-byte code used to tell DL/I what kind of a ‘call’ to make. For example, the function code ‘GN’ tells DL/I to get the next segment from its current position in the database. Most installations define all possible function codes in working-storage in a COPYLIB or other Source Library member (ask your DBA or IMS support person). Later you will see how function codes interact with the other function codes and the three update function codes listed on the next page.

When you access an IMS database with a DL/I call, you will be using these function codes: Get-Unique - to obtain a unique occurrence of a segment in the database Get-Next - to obtain the next occurrence of a segment within a database Get-Next-Within-Parent - to obtain the next occurrence of a segment under a parent;

retrieves child segments under a parent sequentially

GET-HOLD FunctionThe GET-HOLD function codes are identical to GET codes, except that they must be used for retrieval if you intend to ALTER the data being retrieved. Note: These codes imply exclusive use of the segment; no one else can access the segment until you are finished with it.

Remember: in order to replace and delete a segment you must first issue one of the GET-HOLD function codes (GHU, GHN, GHNP); otherwise, the replace or delete action will not be successful.

After a GET-HOLD call you may issue:1. DLET - to DELETE an occurrence of a segment in the database2. REPL - to REPLACE an occurrence of a segment in the database

If you want to add a new occurrence of a segment to your database, you would use ISRT - to INSERT an occurrence of a segment to your database. Note: Sometimes a GET-HOLD call is issued before the ISRT, to see if the segment already exists, but this is not necessary.

20 – IMS/DB

IMS/DB PROGRAMMING IModule III : IMS Application Programming

Function Codes Segment Search Arguments (SSAs)

I/O AreaPCB Mask

Procedure Divisions

SSA OverviewYour COBOL application program issues DL/I calls to retrieve, insert, delete, or replace (update) database segments. In SSA you can provide:

1. The name of the segment type you want.Name

2. A description of a specific segment.NameDescription

3. One or more ‘command codes’ to qualify your DL/I call even moreNameDescriptionCommand Code

Since the SSA is such an important part of your IMS application program, we will be discussing it in more detail in Module 4.


Function CodesSegment Search Arguments (SSAs)

I/O Area PCB Mask

Procedure Divisions

The Input/Output AreaThe Input/Output Area (I/O Area):

Is a standard record description in the WORKING-STORAGE SECTION which holds database segments for manipulation

Is used by DL/I to pass segments to your program Can be used by the programmer to add segments, or change (replace) segment

data. Must be equal to, or greater than, the length of the longest segment to be used by

the program.

In some cases, multiple segments in a parent/child relationship can be retrieved or inserted together. Note: In these cases, the I/O AREA must be large enough to hold the largest concatenation of these segments.

The record description for the I/O AREA can be ‘generic’ and look like this

IMS/DB - 21

01 IO-AREA-GENERIC PIC X(500) VALUE SPACES.

In our EMPLOYEE database, the longest segment is 100 bytes. So the I/O AREA would be defined as

Sometimes the segment structure definitions are stored in COPYLIB (or other source code librarymembers) and can look like this

22 – IMS/DB

01 IO-AREA PIC X(100).

03 EMPLOYEE-SEGMENT-IO-AREA.05 EMP-ID PIC X(11).05 EMP-LASTNAME PIC X(15).05 EMP-FIRSTNAME PIC X(15).



I/O Area PCB Mask

Procedure Divisions

The Program Communication BlockThe Program Communication Block (PCB MASK) is an area common to your COBOL IMS application program and DL/I. It is used to transfer information about each call made to DL/I back to the program. You must code one Database PCB mask for each database your programwill access. The 01 level name should be unique for each database:

For example, if your program uses two databases you would code the following:

Let’s take a look at an 03 level…This is a sample of how you would code each PCB mask.

IMS/DB - 23

01 DB-PCB-1.03 . . .03 . . . . . .

01 DB-PCB-1.03 . . .03 . . . . . .

01 DB-PCB-2.03 . . .03 . . . .03 . . . . .

WORKING-STORAGE SECTION.

LINKAGE SECTION

01 DB-PCB-1.03 DBD-NAME PIC X(8).03 SEG-LEVEL PIC X(2).03 STATUS-CODE PIC X(12).03 PROC-OPTIONS PIC X(4).03 IMS-ADDRESS PIC X(4).03 SEGMENT-NAME PIC X(8).03 KEY-LENGTH PIC S9(5) COMP.03 NUM-SENS-SEGS PIC S9(5) COMP.03 KEY-FEEDBACK.

05 SEG-KEYS PIC X(#).

The most important field in the PCB mask is the STATUS-CODE. This field informs you if your DL/I call was successful or not. Specific values of the STATUS-CODE will be discussed later in this series. PIC X(#): You must specify the length of the longest possible concatenated key. The remainder of the PCB mask fields will be discussed later in this series.

24 – IMS/DB



I/O AreaPCB Mask

Procedure Divisions

Procedure DivisionsWe will now talk about the components that must be coded in the procedure division.

ENTRY and EXIT statements DL/I CALL statements

The Entry StatementCode the ENTRY statement as the first executable statement in your application program. It must follow immediately after the title PROCEDURE DIVISION. For example:

Note: List the names of the DB-PCB mask in the same order as they are defined in the PSB for your program.

DL/I Retrieval CallsDL/I retrieval calls are covered in detail in MODULE 5.

Text RETRIEVAL:GU Get UniqueGN Get NextGNP Get Next Within Parent

DL/I replace calls are covered in detail later in this series.UPDATE:REPL Replace

DL/I insert and delete calls are covered in detail later in this series.Text INSERT:ISRT Insert

Text DELETE:DLET Delete

The Exit StatementThe application program must return control to IMS when it has finished processing. When control is returned to IMS, you must be sure to:

1. Close all open non-IMS files.2. Use the GOBACK statement

Important: Always use the GOBACK statement, never use STOP RUN!IMS ComponentsHere’s a quick review of the IMS components that we have looked at. Take a few minutes to review the chart and ensure you understand what we have been talking about.

IMS/DB - 25

PROCEDURE DIVISION.ENTRY ‘DLITCBL’ USING DB-PCB-1,DB-PCB-2.

Working-Storage FUNCTION CODESSEGMENT SEARCH AREA (SSA)INPUT/OUTPUT AREA

Linkage Section PROGRAM COMMUNICATION BLOCK (PCB)

Procedure Division ENTRY/EXIT STATEMENTSDL/I CALL STATEMENT


The IMS components required in a COBOL application program The function of each IMS component. The placement of each IMS component in a COBOL application program. Entering and exiting IMS.

26 – IMS/DB

IMS/DB PROGRAMMING I Module IV : Segment Search Arguments

Unqualified SSAs Qualified SSAs

OPERATOR FieldCommand Codes

Segment Search ArgumentIn this module, we will discuss the SSA in detail. A Segment Search Argument, or SSA, is an area in working-storage used to identify the segment to which you require access. It is also an optional DL/I CALL parameter that qualifies a call by specifying a particular segment type or segment occurrence.

When specified in a DL/I CALL: The SSA always follows the I/O AREA parameter. There may be one to fifteen SSAs specified in a call statement. The SSAs must appear in hierarchical order by segment type. Each parent segment in the hierarchy of a dependent segment can have an SSA in

the call.

The SSA contains the information necessary to obtain the segment you require. This information could be:

The segment name. The segment name and segment key. The segment name and search field.

There are two types of SSAs:UNQUALIFIED searches for a specific segment typeQUALIFIED searches for a specific occurrence of a specific segment type

Unqualified SSAsAn unqualified SSA is a segment search argument which specifies a segment name only.

As you may have guessed, since only the SEGMENT-NAME is specified in an unqualified SSA, calls made using these SSAs will access the database sequentially from the current position.

NOTE: The 9th position in the literal must be blank. This blank in the 9th byte indicates an unqualified SSA.

An SSA with a * in position 9, a - in position 10, and a blank in position 11 is also an unqualified SSA.

In addition, the literal must be a segment name within the logical database. In other words, the PSB for this program should have a statement that looks like this:

Unqualified SSA ExampleAssume that your program needs to find out how many employees have worked for the company for more than 10 years.

IMS/DB - 27

WORKING STORAGE. ………………………………………………………………. 01 HISTORY-SSA.

05 SEGMENT-NAME PIC X(9) VALUE ‘HISTORY ’.

SENSEG NAME=HISTORY,PARENT=xxxxxxxx,PROCOPT=x.

To accomplish this, your program would need to access the WORK-HISTORY data from the EMPLOYEE database.

The program must access the data sequentially using an unqualified SSA.Segment names are 8 bytes or less. This SSA is a 9 bytes with a blank in position 9, indicating an unqualified SSA.

Qualified and Unqualified SSAsSome installations use the same SSA working-storage definition for both qualified and unqualified SSAs.

This is a qualified SSA as it stands. In order to make it unqualified, we need to blank out the left-most parenthesis, by moving spaces to BEGIN-QUALIFY.

28 – IMS/DB

WORKING STORAGE. ………………………………………………………………. 01 SSA-WORK-HISTORY PIC X(9) VALUE ‘WORKHIST ’.

01 SSA-EMPLOYEE.03 SEGMENT-NAME PIC X(8) VALUE ‘EMPLOYEE’.03 COMMAND-CODE PIC X(2) VALUE ‘*-’.03 BEGIN-QUALIFY PIC X(1) VALUE ‘(’.03 KEYNAME PIC X(9) VALUE ‘EMPKEY ’.03 OPERATOR PIC X(2) VALUE ‘ =’.03 KEY-VALUE PIC X(11).03 END-QUALIFY PIC X(1) VALUE ‘)’.. . . . . . .. . . . . . .

PROCEDURE DIVISION. . . . . . . . . . . . MOVE SPACES TO BEGIN-QUALIFY.

EMPLOYEE

WORK-HISTORYWORK-HISTORY BENFIT-DATABENFIT-DATADEPENDENTSDEPENDENTS


Unqualified SSAs Qualified SSAs

OPERATOR FieldCommand Codes

Qualified SSAsNow suppose that you want to find some BENEFIT-DATA information for one specific employee.Obviously, you no longer want to read sequentially through all the segments. It would be much more efficient to use a direct access method. In order to accomplish this we will need to define a qualified SSA.

A segment search argument which supplies the DL/I call with either a KEY or SEARCH FIELD value, in addition to the SEGMENT-NAME, is a QUALIFIED SSA.

Remember that the key and search fields must be defined in the DBD in the FIELD statements. For this example, it would look something like this:

The open left parenthesis ‘(‘ in position 9, or after a variable number of command codes, signifies the beginning of a qualification statement.

The right ‘)’ closing parenthesis signifies the end of the qualified SSA.

Qualified SSA ExampleAssume that we want to obtain benefit information on one specific employee, whose employee number is 23456789012.

Your COBOL program would have to move the employee number into the KEY-VALUE field of SSA-EMPLOYEE and then issue the DL/I call.

You can also move a variable into KEY-VALUE that had been previously assigned the employee number.

IMS/DB - 29

WORKING STORAGE. ……………………………………………………………………………………….. 01 SSA-EMPLOYEE.

03 SEGMENT-NAME PIC X(8) VALUE ‘EMPLOYEE’.03 COMMAND-CODE PIC X(2) VALUE ‘*-‘.03 BEGIN-QUALIFY PIC X(1) VALUE ‘(‘.03 KEYNAME PIC X(8) VALUE ‘EMPKEY ‘.03 OPERATOR PIC X(2) VALUE ‘=‘.03 KEY-VALUE PIC X(11).03 END-QUALIFY PIC X(1) VALUE ‘)’.

FIELD NAME=(EMPKEY,SEQ,U),BYTES=11,START=. . .

PROCEDURE DIVISION. . . . . MOVE ‘2345678912’ TO KEY-VALUE. CALL ‘CBLTDLI’ USING FUNC-CODE,PCB-MASK1,IO-AREA,SSA-EMPLOYEE.


Unqualified SSAsQualified SSAs

OPERATOR Field Command Codes

OPERATOR FieldSo far we have talked about each of the highlighted fields.

There are only two fields left to discuss. Let’s now look at the OPERATOR field. So far we have only seen one relational operator, that is the EQUAL TO operator = .

You might correctly assume that we are not limited to this one operator. You may also use the following:

RELATIONAL OPERATOR SYMBOLS/CODE Equal to = EQNot equal to ~= =~ NELess than < LTLess than or equal to <= =< LEGreater than > GTGreater than or equal to >= => GE

30 – IMS/DB

01 SSA-EMPLOYEE.03 SEGMENT-NAME PIC X(8) VALUE ‘EMPLOYEE’.03 COMMAND-CODE PIC X(2) VALUE ‘*-‘.03 BEGIN-QUALIFY PIC X(1) VALUE ‘(‘.03 KEYNAME PIC X(8) VALUE ‘EMPKEY ‘.03 OPERATOR PIC X(2) VALUE ‘=‘.03 KEY-VALUE PIC X(11).03 END-QUALIFY PIC X(1) VALUE ‘)’.


Unqualified SSAsQualified SSAs

OPERATOR Field Command Codes

COMMAND-CODE FieldThe last field we need to look at is the COMMAND-CODE field.

So far we have told the DL/I which segments to access. Now it needs to know how to access them - that is, what command codes do.

Command codes are designated by an asterisk *, immediately followed by one or more COMMAND CODES.

The initial value of COMMAND CODE here is ‘*-‘. The ‘-‘ is a NULL COMMAND and serves only as a placeholder until one of the COMMAND CODES is inserted.

The following are examples of COMMAND CODES:CODE FUNCTION

D Retrieve a pathF Access first segment occurrenceL Access last segment occurrenceU Maintain current position at this levelV Maintain current position at this and higher levelsN Do NOT replace this segmentC Use a concatenated keyP Establish parentage at this level- Null/ignore

Once you begin to work with IMS/VS, you will want to look up a detailed description of each command in the manuals, but for now we will just look at a few simple examples.For simplicity, the examples in this course use SSAs which have been defined to allow for a single command code. In order to use multiple command codes, simply expand the size or number of fields used to contain them, and give them an initial VALUE of ‘-‘.

F Command ExampleLet’s see how an F command code works. Remember, ‘F; means First segment occurrence.For example, you need to go from segment C2 to B1 (the first occurrence of segment B). You can accomplish this w/ the F command.

IMS/DB - 31

01 SSA-EMPLOYEE.03 SEGMENT-NAME PIC X(8) VALUE ‘EMPLOYEE’.03 COMMAND-CODE PIC X(2) VALUE ‘*-‘.03 BEGIN-QUALIFY PIC X(1) VALUE ‘(‘.03 KEYNAME PIC X(8) VALUE ‘EMPKEY ‘.03 OPERATOR PIC X(2) VALUE ‘=‘.03 KEY-VALUE PIC X(11).03 END-QUALIFY PIC X(1) VALUE ‘)’.

Here is an SSA using F command code that obtains the first occurrence of the DEPENDENTS segment (called DEPENDENT).

Other Uses of COMMAND CODESHere are some other reasons for using command codes:

They can save processing time by going directly to the last segment. To avoid reading each segment occurrence, they can check in your program if it is

the segment occurrence you want. They can reduce the amount of coding your application program requires.

We have just scratched the surface here regarding command codes. As you can see, command codes can add a level of power (and complexity) to your application program.

We will learn more about command codes in Module 5 when we cover the retrieval of “paths” of dependent segments.

If you would like more information about command codes, talk to your DBA to find out your organization’s standards and conventions for using these and other command codes.


SSAs The difference between qualified and unqualified SSAs. Relational operators. The use of command codes.

32 – IMS/DB

2 2

A A

C 1 C 1 2 2

B 1 B 1

01 SSA-DEPENDENTS.

03 SEGMENT-NAME PIC X(8) VALUE ‘DEPENDENT’.03 COMMAND-CODE PIC X(2) VALUE ‘*F’.. . .

EMPLOYEE

WORK-HISTORYWORK-HISTORY BENFIT-DATABENFIT-DATADEPENDENTSDEPENDENTS

IMS/DB PROGRAMMING I Module V : DL/I Retrieval Calls

DL/I CALL Statement Segment Sequence

Function CodesPATH Calls

DLI CALL StatementIn the IMS environment, application programs written in COBOL access segments in the database by using the CALL to DL/I. When the application program executes, DL/I interprets the requirements that are specified in the parameters/arguments of the DL/I CALL.

Let’s find out what those parameters/arguments are…

Parameters/ArgumentsThis is a CALL to DL/I with all the parameters. We’ll look at each of these parameters in a little more detail shortly, but for now here’s a brief overview of each parameter’s role.

IMS/DB - 33

CALL ‘CBLTDLI’ USING FUNCTION-CODE,PCB,IO-AREA,SSA-1,SSA-2 …

Gives DL/I additional criteria to used in finding a particular segment, or enables a path of multiple segments to be retrieved, replaced, inserted, or deleted in a single call to DL/I.

Each CALL statement may have up to 15 SSAs.

A 4-Byte code that tells DL/I what kind of “call” to make, i.e. whether the segment is retrieved, replaced, inserted, or deleted.

For example: GN is a function code that tell DL/I to get the next segment from its current position in the database.

Most installations define all the possible function codes in WORKING STORAGE via COPYLIB or another source library member.

An argument which tells DL/I which PCB to use for the CALL. Each call may only specify ONE PCB.

Tells DL/I where to put the segment once it has been retrieved, or where to retrieve it when it is to be inserted into a database.

The CALL may only specify ONE IO-AREA. Note that the IO-AREA may contain data from multiple segments if a technique called “path call” is used.

Accessing an IMS DatabaseWhen you access an IMS database with a DL/I call, you will be using one of these FUNCTION CODES:

RETRIEVAL: Get Unique GU

Get Next GN

Get Next Within Parent GNP

RETRIEVAL WITH INTENT TO UPDATE Get Hold Unique GHU

Get Hold Next GHN

Get Hold Next Within Parent GHNP

UPDATE Replace REPL

INSERT Insert ISRT

DELETE Delete DLET



Function CodesPATH Calls

Segment Sequence ReviewREMEMBER: When processing the database sequentially, IMS/VS traverses the hierarchical structure with the following priority:

TOP to BOTTOM LEFT to RIGHT FRONT to BACK

Here is an example of how IMS/VSwould traverse the keys of this hierarchical database.

34 – IMS/DB

FKEY

12 12

11 11 7 7 2 2

4 4 3 3 66

8 8

5 5 10 10 9 9

AKEY

BKEY

CKEY DKEY

EKEY

1 1


DL/I CALL StatementSegment Sequence

Function Codes PATH Calls

Function CodesDuring the course of this module, we will be discussing these three function codes:

1. GET UNIQUE (GU)2. GET NEXT (GN)3. GET NEXT PARENT (GNP)

GET UNIQUE (GU)GET UNIQUE (GU) is used to:

Retrieve segments directly Specify the exact segment you wish to retrieve. Establish your position in the database

If GU is used w/o an SSA, DL/I automatically repositions itself at the first root segment and returns its contents to the IO-AREA. This may cause some unexpected results during testing.

Building a GU CallThe Segment Search Argument (SSA-1)…

…is used to build the following GU call…

The GU function that is defined by SSA-1 as shown, will get the segment with AKEY=12.

IMS/DB - 35

01 SSA-1.03 SEGMENT-NAME PIC X(8) VALUE ‘SEGMENTA’.03 COMMAND-CODE PIC X(2) VALUE ‘*-’.03 BEGIN-QUALIFY PIC X(1) VALUE ‘(’.03 KEYNAME PIC X(9) VALUE ‘AKEY ’.03 OPERATOR PIC X(2) VALUE ‘ =’.03 KEY-VALUE PIC X(11)VALUE ‘12’.03 END-QUALIFY PIC X(1) VALUE ‘)’.. . . . . . .. . . . . . .

CALL ‘CBLTDLI’ USING ‘GU’,PCB,IO-AREA,SSA-1.

GU SEGMENTA *-(AKEY=12).

Retrieving a SegmentAssume you want to retrieve SEGMENT #6 of the DKEY.

You accomplish this using the following code:

Verifying the GU callYou now know how to CALL DL/I using the GU function code.

The important thing to remember is that you should always use qualified SSAs when retrieving specific segments. Once the CALL has been executed, you will want to know whether it executed successfully.

In Module 3, you were given a brief introduction to the PCB mask. One of the fields in the PCB mask is the STATUS-CODE. It is this field that you want to check after a DL/I CALL.

Status CodesWhen a DL/I CALL statement is executed, the value of the STATUS-CODE field in the PCB Mask:

Is changed to reflect whether or not the CALL was successful. Tells you what, if any, problems were encountered.

So what values can STATUS CODE have? When the DL/I Call is successful, STATUS-CODE is set to be blank. If it is unsuccessful, there are a number of different codes that it may be set to:

STATUS-CODE = “GE”, indicating that the segment could not be found. This is the most common occurrence.STATUS-CODE = “GB”, meaning end-of-database.

GET NEXT (GN)GET NEXT (GN) is used to sequentially access segments in the database. DL/I uses the current position set by the previous Call as the starting point of the search for the segment you requested.

You may use the GN function code with: No SSA. An unqualified SSA. A qualified SSA.

36 – IMS/DB

12 12

11 11

1 1

7 7 2 2

4 4 3 3 66

8 8

5 5 10 10 9 9

AKEY

BKEY

CKEY DKEY

EKEY

FKEY

GU SEGMENTA *-(AKEY=1)

SEGMENTB *-(BKEY=2)SEGMENTD *-(DKEY=6)

No SSAIf you do not specify an SSA, then the first GN call will retrieve segment #1. The second GN call will retrieve segment #2 and so on…

Unqualified SSAWith an UNQUALIFIED SSA, DL/I will retrieve the next occurrence of the segment type specified in the SSA.

If SSA-1 is defined as above, the first GN call would retrieve segment #1. The second would retrieve segment #12. The third would set PCB Mask STATUS_CODE field to end-of-file or ‘GB’.

Qualified SSAUsing fully qualified SSAs with GN calls clearly identifies the hierarchical path and segment that you require.

Using this GN call… …you will get segment

Note the GN with a qualified SSAstarts at the current databaseposition and performs an impliedGU.

GET NEXT PARENT (GNP)GET NEXT PARENT (GNP) is used to sequentially access dependent segments of an established parent segment.

The first thing you must do before using GNP is to establish parentage.

You can establish parentage by: Issuing a successful GU or GN call. Using the P Command Code (Establish Parentage) with a GU, GN, or GNP call.

Let’s take a look at an example.

IMS/DB - 37

01 SSA-1.

03 SEGMENT-NAME PIC X(8) VALUE ‘SEGMENTA’.03 BEGIN-QUALIFY PIC X(1) VALUE SPACE.

GN SEGMENTA *-(AKEY =1) SEGMENTB *-(BKEY =2)

12 12 1 1

7 7 2 2

AKEY

BKEY

Establishing ParentageThis GU will establish the parent segment #2 since this was the last successful retrieval.

Additional ExampleLet’s take a look at one more…

The GU function establishesthe parent segment as segment #11.

The first GNP function will be unsuccessful, as segment #11 has no dependents.

Function CodesYou have now seen how these three command function.

GET UNIQUE (GU) GET NEXT (GN GET NEXT PARENT (GNP)

With these three command functions you may retrieve: One segment A series of segments in hierarchical sequence A group of segments with a common parent segment

But what if you wanted a segment and all of its higher level segments w/o having to issue a call for each one? You could do this by issuing what is known as a PATH CALL. For example:

38 – IMS/DB

12 12 1 1

7 7 2 2

4 4 3 3 66

5 5

AKEY

BKEY

CKEY DKEY

GU SEGMENTA *-(AKEY =1) SEGMENTB *-(BKEY =2)

GNP GNP GNP GNP

The first GNP call without an SSA will retrieve the first child segment #3 of parent segment #2.

The next GNP call will retrieve segment #4…

… then segment 5…

…and then segment 6…

12 12

11 11

1 1

8 8

10 10 9 9

AKEY

EKEY

FKEY

GU SEGMENTA *-(AKEY =1) SEGMENTE *-(EKEY =11)

GNP

Specifying a Path of SegmentsAssume for some reason you knew that you required segments #1, #2, and #5 in that order.

We want to be able to specify a path ofsegments, and have all segmentsretrieved into the IO-AREA.

You use the ‘D’ command code,known as the PATH command, tocreate PATH calls.

Let’s write the function that will retrieve these segments for us.



Function Codes PATH Calls

PATH CallsThe ‘D’ command code indicates to DL/I that we want to retrieve a path of segments into the IO-AREA.

The path for the code is as follows:

The IO-AREA needs to be aslarge as the sum of all thesegments being retrievedin the call.

NOTE: The ‘D’ commandis not required for the last segment in the path.

Coding a SegmentSince a child segment can have only one parent, you may have only one path to get to this FKEY segment. You could code a DL/I call, leaving out some levels of SSAs.

With GN and GNP calls, DL/I will build unqualified SSAs for the missing levels.

IMS/DB - 39

12 12

11 11

1 1

7 7 2 2

4 4 3 3 66

8 8

5 5 10 10 9 9

AKEY

BKEY

CKEY DKEY

EKEY

FKEY

GN SEGMENTA *D(AKEY =1) SEGMENTB *D(BKEY =2) SEGMENTD *-(DKEY =5)

GN SEGMENTA *D(AKEY =1) SEGMENTE *- SEGMENTF *-(FKEY =10)

12 12

11 11

1 1

7 7 2 2

4 4 3 3 66

8 8

5 5 10 10 9 9

AKEY

BKEY

CKEY DKEY

EKEY

FKEY

1ST

2ND

3RD

In this case, it returns the same segments asif you had specified the SSA for the EKEY segment.

One Final Word About PATH CallsThe Program Specification Block (PSB) for your program must specify an additional PROCOPT value in order to make PATH calls.

So, if you intend to make PATH calls in your program, be sure to coordinate this with your DBA when the PSB is created.


DL/I calls using GU, GN, and GNP function codes to retrieve data segments. The use of PATH calls to access a path of segments.

IMS/DB PROGRAMMING II Module I : Updating Segments

GET HOLD Calls REPLACE Call

REPLACE with Command Codes

GET FunctionsEarlier in this series you learned how to use three GET function:

GET-UNIQUE GU GET-NEXT GN GET-NEXT-WITHIN-PARENT GNP

These functions can only be used to retrieve for viewing purposes. You cannot alter, in any way, the retrieved segments.

In this module, you will see how you can retrieve and replace segments.

GET HOLD CallsThere are three GET HOLD calls corresponding to each of the GET calls we learned about earlier in this series.

1. GHU GET HOLD UNIQUE2. GHN GET HOLD NEXT3. GHNP GET HOLD NEXT IN PARENT

Once your application program successfully retrieves a segment with a GET HOLD call, it can replace the segment.

Maintaining Data IntegrityThe GET HOLD calls maintain data integrity by signifying to IMS that your application program intends to update a particular segment

40 – IMS/DB

ApplicationIMS Database

Updates

By putting a “hold” on the segment, IMS locks out all other programs.

The “hold” is released the next time a call is made to the database using the same PCB mask.

That is why, in order to complete the update process, the next call after a successful GET HOLD call should be a replace (REPL) or delete (DLET).

IMPORTANT TIPThe ‘HOLD’ status on a particular segment that was created as a result of a successful DL/I GET HOLD (GHU, GHN, or GHNP) call will be canceled if any intervening call other than a REPL (replace) or DLET (delete) call is done using the same database PCB Mask.

Using a GET HOLD without the logical possibility of a REPL (replace) or DLET (delete) results in inefficient processing.

IMS/DB - 41

Application IMS Database


GET HOLD Calls REPLACE Call


The REPL CallAssume that we want to change an employee’s ID number because it was added incorrectly by another programmer. If the ID-NUMBER is the key to the segment, any attempt to REPL (replace) the segment will be unsuccessful because…

The KEY field for a segment cannot be changed.

To correct this error, we would need to add a new, correct segment and delete the old, incorrect segment.

We will discuss ISRT and DLET in the next module.

Example of the REPL CallOne of your employees, Jenny Smith, has just married Albert Jones. You will need to change her last name to SMITH-JONES on the EMPLOYEE segment of your database. Let’s take a look at the code that will accomplish this:

This segment of code:

Retrieves Jenny’s record intothe IO-AREA.

Insures that the GET-HOLD callwas successful.

Moves the new last name intothe EMP-IO AREA. We arenow ready to issue the REPLcall.

Here’s the REPL call to replace Jenny’s record.

This code checks that the REPL call was successful.

Let’s find out what STATUS-CODES the REPL call may return.

42 – IMS/DB

. . . . . . . . . . . . . . MOVE ‘356-74-5555’ TO EMP-ID. CALL ‘CBLTDLI’ USING FUNTION-GHU,

EMPLOYEE-PCB,EMP-IOAREA,EMP-SSA.

IF PCB-STATUS-CODE = ‘ ‘ THEN GO TO REPL-EXIT________________

ELSE:

REPL-PAR MOVE ‘SMITH-JONES’ TO EMP-LASTNAME.

CALL ‘CBLTDLI’ USING FUNTION-REPL,EMPLOYEE-PCB,EMP-IOAREA.

IF PCB-STATUS-CODE = ‘ ‘ THEN GO TO REPL-EXIT________________

ELSE:

REPL Status-CodesTwo REPL Status Codes are DA and RX:

DA means you tried to change the KEY field of the segment. RX means you violated a REPLACE rule.

One case would be if you issued a GET call rather than a GET HOLD call before issuing the REPL call. Or you may have tried to improperly use a COMMAND CODE in a REPL call.


GET HOLD CallsREPLACE Call


The REPL CallHere is the REPL call from our previous example. Note that the call does not specify any SSAs. SSAs are not normally used in the REPL function call. DL/I gets the information about the segments we want to replace from the IO-AREA.

The IO-AREA gets it information from the GET-HOLD call that we make before issuing the REPL call. However, there is an exception; when the ‘N’ COMMAND CODE must be used with the REPL call.

Example of an REPL FunctionHere’s an example of how to use a path GHU call using the ‘D’ COMMAND CODE, followed by a REPL call where only the lowest segment is to be replaced.

This will retrieve #1, #2, #3 segments in theIO-AREA, but only replace segment #3.

The replacements of the higher level segments are to be ignored. This is signaled by the ‘N’ command code.

IMS/DB - 43

CALL ‘CBLTDLI’ USING FUNCTION-REPL,EMPLOYEE-PCB,EMP-IOAREA.

GHU SEGMENTA *D(AKEY =1)SEGMENTB *D(BKEY =2)SEGMENTC

REPL SEGMENTA *NSEGMENTB *N

12 12 1 1

7 7 2 2

4 4 3 3 5 5

AKEY

BKEY

CKEY DKEY

Relationships Between FunctionsYou have just seen how to update segments in a database using the GET HOLD and REPLACE functions. It is important to remember that there is a relationship between the functions allowed in a program and the PSB that was generated for the program. As you recall, the PSB is made up of one or more PCBs, identifying which segment(s) the program “is sensitive to” or can access.

Also, the PROCOPT statement specifically defines how the segment can be accessed.


How to code GET HOLD calls. How to issue REPLace calls. How to REPLace using the ‘N’ COMMAND CODE.

IMS/DB PROGRAMMING II Module II : Inserting and Deleting Segments

INSERT Calls to Load a Database INSERT Calls to Add a New Segment

DELETE Calls

Insert Function CodeTo initially ‘load’ records to an IMS database, you use the insert function code (ISRT) in a DL/I call. To add new records or segments to an existing IMS database you use the same insert function code (ISRT) in a DL/I call.

So, the ISRT call is used in two modes: LOAD and INSERT.

Let’s look at the difference between the LOAD mode and the INSERT mode.

Program Specification BlockYou will recall that the PSB (Program Specification Block):

Defines which segments may be accessed by your program. Defines the ‘processing options’ – this tells DL/I what operations may be performed

on the segments.

The basic difference between adding records/segments in LOAD mode and INSERT mode is what processing options are specified in the PSB for the program.

Load ModeIn LOAD mode, only two processing options are allowed:

L (LOAD) and LS (LOAD SEQUENTIAL).

The L processing option means load the database, but not necessarily in sequential order. There are a variety of different access methods available. Some will permit random loading and others require that databases must be loaded sequentially.

44 – IMS/DB

LOAD Mode INSERT Mode

LOAD Mode

LOAD SequentialLOAD

LS is usually preferred as it specifies that segments must be loaded in ascending sequence.

A brief discussion of access methods follows…

HSAMHSAM: The segments that make up a database record are stored sequentially in hierarchical order, like a sequential file. HSAM is very efficient for sequential processing, but very inefficient for random processing.

HSAM is not commonly used. Segments cannot be inserted in an existing HSAM database (the database must be unloaded and then reloaded).

HISAMHISAM: The segments are stored in the same way as for an HSAM database, but an index is added, so that random access to any database record is allowed. HISAM is very efficient for sequential processing and fairly efficient for random processing. Segments can be inserted in an existing HISAM database, but existing segments may be move around to make room for the new segment(s).

HDAMHDAM: Segment occurrences are stored, preceded by direct address pointers to related (in a hierarchical sense) segments. Root segments are stored using a randomizing scheme. HDAM is efficient for random processing, but is not generally appropriate, for sequential processing.

Segments can be inserted and are never moved to make room for new segments (the pointers for the segments are modified as new segments are added).

HIDAMHIDAM: The segments are stored similar to that of an HDAM database, with an index added to store the root segments (so that root segments are not stored using a randomizing scheme). HIDAM is relatively efficient for both random and sequential processing.

Insert ModeIn INSERT mode, processing options can be:

I – Insert new segments in sequential or random order. IS – Add new segments only in ascending sequence.

Segments can be added to all database types except HSAM. New segments are added to an HSAM database by unloading it and then reloading it.

ISRT Function CodeHere are some things you should know about ISRT function code:

The segment to be inserted must first be built in the program IO-AREA. Use the ‘D’ COMMAND CODE to insert a path of segments. Use SSAs to define the path to DL/I. Use an unqualified SSA at segment level(s) where the insertion will occur. New segments added to an existing database are inserted based on the segment

KEY fields in the IO-AREA.

Segments with a KEY field can be inserted in KEY sequence. Segments with no KEY or non-unique KEY will be inserted according to insert rules specified in the DBD.

IMS/DB - 45

INSERT Mode

INSERT in SequenceINSERT

INSERT RULE OptionsLet’s see the INSERT RULE options in the DBD.

FIRST – tells DL/I to place the segment FIRST; that is, the first occurrence of this segment type. FIRST can be used in the unqualified SSA to override the insert rules in the DBD.

LAST – tells DL/I to place this segment LAST in the twin chain, the last occurrence of this segment type. LAST can be used in the unqualified SSA to override the insert rules in the DBD.

HERE – tells DL/I to place this segment before the current segment occurrence; if the current position has not been established, the segment is placed first on the twin chain of segments. A twin chain is all twin segments dependent on a particular parent segment.

46 – IMS/DB


INSERT Calls to Load a Database INSERT Calls to Add a New Segment

DELETE Calls

INSERTing New SegmentsNow let’s look at some examples of INSERTing new segments…

To insert a new root-level EMPLOYEE segment, we build the contents of the IO-AREA to be inserted, and then issue this call to DL/I:

This must be an UNqualified SSA.

The new segment to be insertedmust have only one unqualifiedSSA. However, in order to insert anew segment in its proper location,(e.g., a new segment type C, #99)we should QUALIFY the path to this new segment with QUALIFIED SSAs:

Where the SSAs look like:

Given that Segment C #3 is in the IO-AREA, what will happen when this ISRT call is made?

When we check the STATUS CODE after making the ISRT call, we will not get SPACES – the status code will be ‘||’.

What does ‘||’ mean?

We tried to insert a segment that already existed in the database. Segment C #3 already was in our database.

What other ISRT call status code could we get?

GE – would tell us that the DL/I could not find the path specified by the SSAs in our ISRT call.

Check STATUS CODERemember always check the STATUS CODE after making a DL/I call.

IMS/DB - 47

CALL ‘CBLTDLI’ USING FUNCTION-ISRT,EMPLOYEE-PCB,EMP-IOAREA,EMP-SSA.

CALL ‘CBLTDLI’ USING FUNCTION-ISRT,EMPLOYEE-PCB,EMP-IOAREA,A-SSA,B-SSA,C-SSA.

SEGMENTA *-(AKEY =1) SEGMENTB *-(BKEY =2) SEGMENTC

12 12 1 1

7 7 2 2

4 4 3 3 5 5

AKEY

BKEY

CKEY DKEY

When making an ISRT call check for: ‘||’ – tried to insert a segment that already exists ‘GE’ – could not find the path of segments specified in our SSAs.

INSERTing New SegmentsNotice that we do not make a GET-HOLD call before INSERTing (ISRT) a new segment. Instead of issuing GET calls, we define QUALIFIED SSAs for all the parents of the path to the new segment.

Now that we know how to INSERT new segments, let’s look at how we tell DL/I to DELETE a segment.

48 – IMS/DB

CALL ‘CBLTDLI’ USING FUNCTION-ISRT,EMPLOYEE-PCB,EMP-IOAREA,A-SSA,B-SSA,C-SSA.

SEGMENTA *-(AKEY =1) SEGMENTB *-(BKEY =2) SEGMENTC


INSERT Calls to Load a DatabaseINSERT Calls to Add a New Segment

DELETE Calls

DELETE SegmentsJust like the REPL call, DLET (DELETE call) must be preceded by one of the three GET HOLD calls. DL/I rejects the DLET call if the call that preceded it was not a GET HOLD call.

GET HOLD and DELETE FunctionsTo illustrate the use of GET HOLD and DELETE functions, let’s consider the EMPLOYEE database. An employee named Jenny Smith-Jones has resigned. We are going to delete her record from the active EMPLOYEE database, and add her information to the employee HISTORY database. Our calling pattern will look something like this:

GU calls to the active EMPLOYEE database to retrieve the appropriate data from the various segments in Jenny’s database record.

GHU calls to the root segment of the active EMPLOYEE database to retrieve Jenny’s record with a ‘hold’. This will lock others out from the database until we are done.

An ISRT call to the employee HISTORY database inserts a history segment.

A DLET call to the active EMPLOYEE database remove Jenny’s record.

IMS/DB - 49

HISTORY

EMPLOYEE

GUGU

Segment 1Segment 1

Segment 2Segment 2

Segment 3Segment 3

HISTORY

EMPLOYEE

GUGU

GHUGHU

HOLD

HISTORY

EMPLOYEE

GUGU

GHUGHU

HOLD

ISRTISRT

History SegmentHistory Segment

HISTORY

EMPLOYEE

GUGU

GHUGHU

HOLD

ISRTISRT

DLETDLET

We have already completed our GU calls to retrieve the data from Jenny’s active employee record, and used that information to build the history segment in the history IO-AREA. Let’s retrieve Jenny’s record with a GET HOLD UNIQUE.

Next, we’ll insert this segment into the HISTORY database:

Don’t forget to check the status code after each database call. Now that we have inserted what we needed on the HISTORY database, we can issue the DELETE call (DLET) for Jenny’s record on the EMPLOYEE database. No SSAs are needed. All segments under the root segment will also be deleted by the one DLET call.

GET HOLD Precedes DELETEWe said the DL/I will reject the DLET call if the call that preceded it was not a GET HOLD call. In this example, we performed GHU, followed by an ISRT, and then we performed the DLET. We said that the DLET call must immediately follow the GET HOLD call. To be more precise, the DLET call must immediately follow the GET HOLD using the same PCB. In our example, the GHU and DLET call used the EMPLOYEE-PCB, while the intervening ISRT call used the HISTORY-PCB.

Don’t forget we also checked the status codes after each call.

DLET Call Status CodesNow let’s look at some status codes that we might see with the DLET call:

- successful delete of segment or segments specified.

- unsuccessful; the segment key was changed before DLET was issued.

- unsuccessful; the program did not issue a GET HOLD call before the DLET was issued.

- unsuccessful; the program issued a DLET call, which violated the delete rule defined for the segment in the DBD.

50 – IMS/DB

MOVE ‘356-74-5555’ TO EMP-ID. CALL ‘CBLTDLI’ USING FUNC-GHU,

EMPLOYEE-PCB,EMP-IOAREA,EMP-SSA.

CALL ‘CBLTDLI’ USING FUNC-ISRT,HISTORY-PCB,EMP-IOAREA,HISTORY-SSA.

CALL ‘CBLTDLI’ USING FUNC-DLET,HISTORY-PCB,EMP-IOAREA.

EMPLOYEE-PCB HISTORY-PCB

DLET Call

GHU Call

ISRT Call

‘ ’

‘DA’

‘DJ’

‘DX’

Using SSA’s with DLETNormally an SSA is not used with the DLET function. However, you may encounter the situation where you have issued a path call with a GET HOLD function code. If you do not want to delete all of the segments in that path, you could issue a DLET call with an UNQUALIFIED SSA for the segment (and all its dependents) you want to delete. In this instance, only one SSA is allowed with the DLET function. For example…

…will retrieve segments #1, #2, and #3 and put them in the IO-AREA.

…will only replace #1.

…will delete segment B and also delete dependents of segment B.

COMMAND CODE in a DLET CallNo command codes apply to DLET. If you issue a COMMAND CODE in a DLET call, DL/I disregards the COMMAND CODE.


How to code INSERT calls both to initially LOAD a database, and to add new records to an existing database.

How to issue DELETE calls to delete one or more segments.

IMS/DB - 51

GHU Axxxxxx *D(AKEY =1)Bxxxxxx *D(BKEY =2)Cxxxxxx

REPL AxxxxxxBxxxxxx *NCxxxxxx *N

DLET Bxxxxxx

IMS/DB PROGRAMMING II Module III : Programming Techniques

Status Code Checking Standard Abend/Error Routines

Efficient Segment Access StrategyCheckpoints

IntroductionWhen programming in any language, it is important that you are aware of factors that may help you develop effective and efficient applications. In this module, we will look at three areas that will assist you to achieve this goal in your IMS/DLI applications.

1. STATUS CODES2. SEGMENT ACCESS3. CHECKPOINTS

Status CodesRecall that DL/I gives you information about the result of your DL/I call in the STATUS CODE field for the DB PCB. You know that your program should check the STATUS CODE after every DL/I call. Let’s take a closer look at the STATUS CODE check, and how your program should handle it…

You should always be sure that your program verifies the STATUS CODE after every DL/I call. You want to be certain that the call has been successful, and that your program has achieved the results it was expecting. There are over 100 status codes! However, in most cases only a few will apply to any one call. If a DL/I call is successful, the STATUS CODE will be set to SPACES. This is the first thing you should verify after a call.

Checking GET CallsBesides checking each call for SPACES, if you are making GET calls, you may also test for:

GADL/I has returned a segment, but the segment is at a higher level in the hierarchy than the returned segment. DL/I will only return ‘GA’ for UNQUALIFIED GET NEXT calls.

GBDL/I reached the end of the database and therefore could not return a segment to your program.

GEDL/I could not find the segment you asked for. This could happen after a ‘GU’, ‘GN’, or ‘GNP’ call.

GKDL/I returned a segment that satisfies an UNQUALIFIED ‘GN’ or ‘GNP’ call, but the segment is a different segment type than the last segment that was returned (but at the same level).

Unexpected Status CodesWhen unexpected status codes are received, your program should branch to an error routine. Most data processing shops using IMS have set up a standard error routine which ensures that important information is printed to aid in determining the problem.

52 – IMS/DB


Status Code Checking Standard Abend/Error Routines

Efficient Segment Access StrategyCheckpoints

The DL/I Standard Error RoutineThe DL/I standard error routine should list:

The SSAs , if any, included in the call. The call that was being executed when the error occurred. Contents of the PCB, particularly the STATUS CODE and key feedback information. Anything else that would provide an audit trail, such as flags and counters.

Abending the ProgramNow that any unexpected STATUS CODES have been handled, you must decide: Should the program be ABENDED? This will depend on a number of things:

1. Your shop policy. Check with your DBA or Supervisor2. Whether the program can continue without the segment that was requested.3. Whether the problem is serious enough that any further processing cannot continue.

REMEMBER, if the program UPDATES the database, and you prematurely terminate it by ABENDing, the database will need to be recovered before another program accesses it.

That completes our discussion of STATUS CODES. Let’s move on to look at SEGMENT ACCESS…

IMS/DB - 53


Status Code CheckingStandard Abend/Error Routines

Efficient Segment Access Strategy Checkpoints

Segment AccessWhen designing and writing an application, one of your concerns should be the efficiency of your code. With a hierarchical database structure, one of the things that can significantly affect efficiency is how you access segments.

We will look at six key areas to consider in accessing segments efficiently:1. ISRT Calls2. Hierarchical Access3. Segment Search Arguments4. Search Fields5. Secondary Indices6. Multiple PCBs

ISRT CallsIf you recall our discussing of the GU (GET UNIQUE) call, you may remember that it can be used to verify whether a segment you want to INSERT already exists, or to position IMS for the insert. Including the GET call before ISRT results in two DL/I calls for every successful INSERT. This is neither efficient nor necessary because the ISRT call uses all the SSAs without a GET call.

Hierarchical AccessWhen you code your CALL statements you should take advantage of the hierarchical structure of the IMS database. Code your DL/I calls in a manner consistent with record and segment relationships.

You should:o Know your current position.o Know which segment is the parent.

You should access segments in the database structure from:o Top to bottomo Left to right

Segment Search ArgumentsQualified SSAs give DL/I more precise information about the segment you want to access. Besides being more efficient, qualified SSAs are a good way to document what your program is doing. Implied SSAs should be avoided in GU and ISRT calls even though DL/I will construct internal SSAs. Missing SSAs are often handled like unqualified SSAs; therefore, qualified SSAs should be used if possible.

Search FieldsThe fewer DL/I calls your program makes, the more efficient your program will be. So, if you need to retrieved a segment based on a field’s data value besides the KEY, define and use SEARCH fields. If your database has a field besides the KEY field that needs to be tested in many programs, use the SEARCH field in your DL/I CALL rather than coding a procedural IF statement in your program.

NOTE: Some shops do not use SEARCH fields. They must be defined in the DBD and increase the size of the DBD.

54 – IMS/DB

Secondary IndicesA secondary index is a self-contained database that stores pointers to segments in the database being indexed. The secondary index allows the program to access segments in a sequence other than the key sequence.

Secondary index databases are connected to the main database in the DBDGEN.

Multiple PCBsA program that is working with a single database may require more than one logical view of the database. The PSB for the program can be defined with multiple PCBs that reflect different logical views of the same database. This technique can be used when recording the organizational structure of a company where employees report to managers who in turn report to the project manager.

One PCB can point to the managers to whom the employees report.

A second PCB can point to the reporting employees.

Review of BMPsThe last area we will look at is checkpoints, however, before we talk about checkpoints let’s review some of the material about batch programs and BMPs…

You will recall that IMS application programs can be run as on-line applications or as batch applications. A BMP is a batch program running under the control of the IMS On-Line Control Region. BMPs access and update IMS databases just as IMS batch programs. Databases must be off-line for access by batch programs. Databases must be on-line (On-Line IMS up) for access by BMP programs. Each mode of processing has its own set of advantages and disadvantages. A good strategy is to design a program that could run either as a batch program or as a BMP.

Advantages and DisadvantagesThe primary advantage of BMPs over batch is data availability. Databases accessed by a BMP are also available to other BMPs or on-line transactions. However, RESTART procedures for BMPs can be more involved than those for batch programs. This is where ‘checkpointing’ comes into the picture.

IMS/DB - 55

SecondaryIndex

Main Database

Project ManagerProject Manager

ManagerManager ManagerManager

EmployeeEmployee EmployeeEmployee EmployeeEmployeeEmployeeEmployee


Status Code CheckingStandard Abend/Error Routines

Efficient Segment Access Strategy Checkpoints

Checkpoint CallsCheckpoint calls are the means by which programs indicate to IMS that a synchronization point has been reached. This is a point where the application program commits the data it has modified or created, ensuring that it is consistent and complete. Here are some things that happen as a result of making a checkpoint call:

IMS commits database updates and sends messages which had previously been stored in buffers.

Database positioning is reset at the beginning of the database. A new synchronization point is set for backing out database changes and sending

messages.

Two Kinds of Checkpoint CallsThere are two kinds of Checkpoint calls:

1. BASIC2. SYMBOLIC

The parameters you need for either Checkpoint call include: The DL/I call function code ‘CHKP’. The name of the I/O PCB. The name of the I/O AREA containing the Checkpoint ID.

In addition to these, the Symbolic call allows you to save as many as seven data areas in your program which will be restored when your program is restarted. The length and name of each data area you want saved are passes to DL/I as additional parameters on the Checkpoint call.

Frequency of Checkpoint CallsIn batch, checkpointing is used mostly for long-running jobs. The frequency at which you ‘checkpoint’ depends on a number of factors. Here are a few possibilities:

Every 15 minutes. Although this would have potential benefits in the event of an ABEND, the disadvantages are that each checkpoint will chew up machine time/wall time and add to an already long running job.

Every hour. This will use less machine time and perhaps maximize time in the event of an ABEND.

Every ‘so-many’ segments. This would need to be discussed with your DBA to determine the optimum number of records.

Standards and GuidelinesMost Information Systems department have their own standards for coding Checkpoint (CHKP) and Restart (XRST) calls. Talk to our course administrator or DBA to find out what standards and guidelines exist in your organization for these calls.


Checking STATUS CODES after DL/I calls and what to do with unexpected STATUS CODES.

The benefits of Standard Error Routines. Efficient segment access strategies. Reasons for using Checkpoint calls.

56 – IMS/DB

IMS/DB PROGRAMMING II Module IV : Compiling, Executing, and Debugging

Compiling and EXECUTION JCL Debugging with DL/I Test Program DLT0

CompilingIMS supplies an interface module (DFSLI000) that must be link-edited to your batch program after your program has been completed. If you use the IBM-supplied procedure called IMSCOBOL, IMS link edits the language interface with your program. Most installations have TSO panels and CLISTs set up to make these additional items transparent to the application programmer. Ask your DBA or technical support person about your shop standards.

Application ComponentsSo now that you know all about CODING and COMPILING your IMS application program, let’s see how to execute it. Your IMS application program is actually a ‘subroutine’ . To illustrate, remember the format of the DL/I Call statement?

IMS SubroutineYour program CALLs DL/I to access the IMS database. There are two ways to tell the operating system that you are creating a subroutine:

1. A PROCEDURE DIVISION USING ????2. An ENTRY ‘ ‘ USING statement. Most installations use the ENTRY statement.

SubroutinesRemember, we coded: ENTRY ‘DLITCBL’ USING PCB_1, and when we are finished, we use the GOBACK statement. GOBACK returns control to the calling program. A good way to remember these two statements is:

You tell the operating system that your program is a subroutine by coding:

Your application program calls DL/I subroutines with the:

IMS/DB - 57

CALL ‘CBLTDLI’ USING FUNCTION_CODE,PCB_1,IO_AREA,SSA_1.

“DL/I TO COBOL” ====> ENTRY ‘DLITCBL’ USING PCB_1

“COBOL TO DL/I” ====> CALL ‘CBLTDLI’

IMS/DB PROGRAMMING II Module IV : Compiling, Executing, and Debugging

Compiling and EXECUTION JCL Debugging with DL/I Test Program DLT0

The EXECUTE JCLWhat does the EXECUTE JCL look like?

DFSRRCCOO is the name for the batch IMS module from IBM.Pgmname is the name of your application program.Psbname is the name of the Program Specification Block (PSB) for your program; this is usually the same name as your application program.

NOTE: Your installation may have mode IMS EXECUTION JCL which contains standard IMS libraries. Ask your DBA or technical support person what you should use.

Testing ToolsYour installation may have special IMS testing software tools. IBM supplies a testing tool for IMS called DFSDDLT0. DFSDDKT0 (or DLT0, as it’s called for short) is an IMS DL/I test program that executes the DL/I calls you specify for a given database. DLT0 can be used to:

Test DL/I calls w/o executing your application program. INSERT, REPLACE, DELETE records on a database, or RETRIEVE (DUMP) records from a database. Debug an application program.

Before you use DLT0, you will need a PSB. For more information, see your DBA.

Control StatementsThere are four control statements that inform the DLT0 which DL/I CALL to execute:

1. STATUS: establishes print options for DLT0’s output, and selects the DB PCB.2. COMMENTS: allows comments for documentation purposes.3. CALL: indicates the CALL you want to execute, any SSAs you want to use with the

CALL, and how many times you want the call executed.4. COMPARE: tells DLT0 to compare results of the CALL with the results you supply

here.

In addition to the four control statements, there is a DATA statement. The DATA statement provides IMS with segment information for INSERT and REPLACE calls.

58 – IMS/DB

//STEP1 EXEC PGM=DFSRRC00,PARM=(DLI,pgmname,psbname

DLT0 JCL and Control StatementsThis is an example of DLT0 JCL and control statements that replace a segment on the EMPLOYEE database.

For more information on DLT0, see the IMS Applications Program Manual.

Coding ErrorsYou may have coding errors in your IMS application program, just like you would in a non-IMS program. Some of the errors that may have been caused by something you coded (or failed to code) in DL/I, such as:

An unexpected status code. A program ABEND. An incorrect or wrong segment.

We discussed the value of a standard IMS error routine. The information displayed will be helpful in debugging.

Let’s take a look at some information that IMS provides for that purpose…

The Linkage SectionRemember the sample PCB Mask?

We have already covered status code field.

If the retrieve is unsuccessful, the level number and segment name are supplied for the last segment in the hierarchy which DID satisfy the search criteria.

IMS/DB - 59

//DLT0 EXEC PGM=DFSRRC00,PARM=’DLI,DFSDDLT0,EMPLPSB’ //STEPLIB DD DSN=IMSVS.RESLIB,DISP=SHR //IMS DD DSN=IMSVS.PSBLIB,DISP=SHR // DD DSN=IMSVS.DBDLIB,DISP=SHR //EMPLDB DD DSN=EMPLOYEE.MASTERDB,DISP=OLD //IEFRDER DD DSN=(supply IMS log dataset here…) //PRINTDD DD SYSOUT=A // (other dd statements per your installation) //SYSIN DD * S 1 1 1 1 1 EMPLDB L U GHU EMPLOYEE (EMPLID =79845231001) L U REPL L DATA (place your data to be replaced here…)

LINKAGE SECTION. 01 DB-PCB-1.

03 DBD-NAME PIC X(08).03 SEG-LEVEL PIC X(02).03 STATUS-CODE PIC X(02).03 PROC-OPTIONS PIC X(04).03 IMS-RESERVED PIC S9(5) COMP.03 SEGMENT-NAME PIC X(08).03 KEY-LENGTH PIC S9(5) COMP.03 NUM-SENS-SEGS PIC S9(8) COMP.03 KEY-FEEDBACK.

05 SEG-KEYS PIC X(##).

In this example, we willallow up to 50 bytes to hold the value of concatenated keys

At entry time,this field contains the name of the database that IMS tried to access

These fields contain the level number and segment name of the segment that was successfully retrieved in the call.

While trying to retrieve the BENEFIT segment for an employee, you find the EMPLOYEE segment but not the BENEFIT segment. If none of the search criteria were satisfied, the level would be ‘00’ and the segment would contain spaces.

The Proc-Options line contains the values specified in the PROCOPT = parameter of the PSB for the PCB referenced in the call statement. This is a 4-byte field used internally by IMS. This field contains the number of segment types that the application program ‘is sensitive to’ or has access to.

In this case, the STATUS-CODE contains ‘GE’, the SEG-LEVEL contains ‘01’, and the SEGMENT-NAME contains ‘EMPLOYEE’.

This field contains the value of concatenated key for the last segment found. This value will be left justified.

Linkage ExampleIn the EMPLOYEE database, the EMPID field (11 bytes long) is the key to the EMPLOYEE segment.

The DEPTID field (length 5) is the key to the WORKDATA segment.

An attempt to retrieve the WORKDATA segment with DEPTID = 54321 for EMPID = 60050040011, will result in the value 6005004001154321 being placed in the first 16 bytes of the SEG-KEYS field in the PCB Mask.

Debugging a ProgramHere are two more ideas that may help in debugging your program:

1. The STAT (statistics request) CALL gives you statistics about the number of reads and writes done by your program. If the number is not what you expected, something is wrong with how your calls are being executed.

2. DLITRACE is a control card that executes the IMS TRACE program called DFSDLTR0. This program traces and records DL/I call issued by IMS application programs. It is useful debugging tool as it shows you which calls your application program made. Errors are easy to spot, as the last call displayed is the call that is in error. DLITRACE requires a statement in the DFSVSAMP dataset in your execution JCL. Ask your DBA for help in setting up a DLITRACE or refer to the IMS Application Programming Manual for more information.


EXECUTING your IMS application program. COMPILING your IMS application program. TESTING your IMS application program. DEBUGGING your IMS application program using a STANDARD ERROR

ROUTINE, the STAT call, and DLITRACE.

60 – IMS/DB

EMPLOYEEkey EMPID

WORKDATAkey DEPTID

ims documentation

Documents

source library

technical

standard error

program specification

program communication

maintain current

ims data communication

batch message