IMS/DB PROGRAMMING I MODULE I : IMS DATABASE STRUCTURES .....................................................

5
General Database Objectives ........................................................................................ 5 Introduction ............................................................................................................................... 5 Database Goals ........................................................................................................................ 5 IMS Hierarchical Structure Components ..................................................................... 6 Common Database Structures ................................................................................................. 6 Relational Databases ............................................................................................................... 6 Network Databases .................................................................................................................. 6 Hierarchical Databases ............................................................................................................ 7 IMS/VS ..................................................................................................................................... 7 IMS Hierarchical Components .................................................................................................. 7 Segments ................................................................................................................................. 7 Fields ........................................................................................................................................ 8 Field Types ............................................................................................................................... 8 Concepts of Root, Parent, and Child .......................................................................... 10 Parent and Child Segments.................................................................................................... 10 Parent Segments .................................................................................................................... 10 Child Segments ...................................................................................................................... 10 Root Segments ....................................................................................................................... 10 Dependent Segments ............................................................................................................. 10 IMS Limitations ....................................................................................................................... 10 Segment Occurrences ............................................................................................................ 10 Review .................................................................................................................................... 11 Summary ................................................................................................................................ 11

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

Components of an IMS Environment ......................................................................... 12 Introduction ............................................................................................................................. 12 Data Language I ..................................................................................................................... 12 IMS DB/DC System ................................................................................................................ 12 Components of the IMS Environment .................................................................................... 12 Modes of Processing ................................................................................................... 14 Modes of Processing .............................................................................................................. 14 Batch DL/I Processing ............................................................................................................ 14 TP/MPP .................................................................................................................................. 14 Batch Message Processing (BMP) ......................................................................................... 14 Hierarchical Data Structure .................................................................................................... 14 The Physical Database ........................................................................................................... 14 The Logical Database............................................................................................................. 15 Physical Database Definition ...................................................................................... 16 Defining the Physical Database .............................................................................................. 16 DBDGEN ................................................................................................................................ 16 DBDGEN Control Statements ................................................................................................ 16 DBD Statement....................................................................................................................... 16 DATASET Statement ............................................................................................................. 16 SEGM Statement.................................................................................................................... 16 FIELD Statements .................................................................................................................. 17 ENDING the DBDGEN Process ............................................................................................. 17 Logical Database Definition ........................................................................................ 18 Defining the Logical Database................................................................................................ 18 Program Specification Block (PSB) ........................................................................................ 18 Program Communication Block (PCB) ................................................................................... 18

IMS/DB - 1

PROCOPTs ............................................................................................................................ 18 Example of PSB with One PCB .............................................................................................. 19 Summary ................................................................................................................................ 19

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

Function Codes ............................................................................................................ 20 The Working-Storage Section ................................................................................................ 20 Function Codes ...................................................................................................................... 20 GET-HOLD Function .............................................................................................................. 20 Segment Search Arguments (SSAs) ........................................................................... 21 SSA Overview......................................................................................................................... 21 I/O Area .......................................................................................................................... 21 The Input/Output Area ............................................................................................................ 21 PCB Mask ...................................................................................................................... 23 The Program Communication Block ...................................................................................... 23 Procedure Divisions ..................................................................................................... 24 Procedure Divisions ................................................................................................................ 24 The Entry Statement............................................................................................................... 24 DL/I Retrieval Calls ................................................................................................................. 24 The Exit Statement ................................................................................................................. 24 IMS Components .................................................................................................................... 24 Summary ................................................................................................................................ 25

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

Unqualified SSAs .......................................................................................................... 26 Segment Search Argument .................................................................................................... 26 Unqualified SSAs .................................................................................................................... 26 Unqualified SSA Example ...................................................................................................... 26 Qualified and Unqualified SSAs ............................................................................................. 27 Qualified SSAs .............................................................................................................. 28 Qualified SSAs ....................................................................................................................... 28 Qualified SSA Example .......................................................................................................... 28 OPERATOR Field .......................................................................................................... 29 OPERATOR Field................................................................................................................... 29 Command Codes .......................................................................................................... 30 COMMAND-CODE Field ........................................................................................................ 30 F Command Example............................................................................................................. 30 Other Uses of COMMAND CODES ....................................................................................... 31 Summary ................................................................................................................................ 31

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

DL/I CALL Statement .................................................................................................... 32 DLI CALL Statement............................................................................................................... 32 Parameters/Arguments .......................................................................................................... 32 Accessing an IMS Database .................................................................................................. 33 Segment Sequence ...................................................................................................... 33 Segment Sequence Review ................................................................................................... 33 Function Codes ............................................................................................................ 34 Function Codes ...................................................................................................................... 34 GET UNIQUE (GU) ................................................................................................................ 34 Building a GU Call .................................................................................................................. 34 Verifying the GU call ............................................................................................................... 35

2 IMS/DB

Status Codes .......................................................................................................................... 35 GET NEXT (GN) ..................................................................................................................... 35 No SSA ................................................................................................................................... 36 Unqualified SSA ..................................................................................................................... 36 Qualified SSA ......................................................................................................................... 36 GET NEXT PARENT (GNP)................................................................................................... 36 Establishing Parentage ........................................................................................................... 37 Additional Example ................................................................................................................. 37 Function Codes ...................................................................................................................... 37 Specifying a Path of Segments .............................................................................................. 38 PATH Calls .................................................................................................................... 38 PATH Calls ............................................................................................................................. 38 Coding a Segment .................................................................................................................. 38 One Final Word About PATH Calls ........................................................................................ 39 Summary ................................................................................................................................ 39

IMS/DB PROGRAMMING II MODULE I : UPDATING SEGMENTS ............................................................... 39

GET HOLD Calls ........................................................................................................... 39 GET Functions........................................................................................................................ 39 GET HOLD Calls .................................................................................................................... 39 Maintaining Data Integrity ....................................................................................................... 39 REPLACE Call ............................................................................................................... 41 The REPL Call ........................................................................................................................ 41 Example of the REPL Call ...................................................................................................... 41 REPL Status-Codes ............................................................................................................... 42 REPLACE with Command Codes ............................................................................... 42 The REPL Call ........................................................................................................................ 42 Example of an REPL Function ............................................................................................... 42 Relationships Between Functions .......................................................................................... 43 Summary ................................................................................................................................ 43

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

INSERT Calls to Load a Database .............................................................................. 43 Insert Function Code .............................................................................................................. 43 Program Specification Block .................................................................................................. 43 Load Mode .............................................................................................................................. 43 HSAM ..................................................................................................................................... 44 HISAM .................................................................................................................................... 44 HDAM ..................................................................................................................................... 44 HIDAM .................................................................................................................................... 44 Insert Mode............................................................................................................................. 44 ISRT Function Code ............................................................................................................... 44 INSERT RULE Options .......................................................................................................... 44 INSERT Calls to Add a New Segment ......................................................................... 46 INSERTing New Segments .................................................................................................... 46 Check STATUS CODE........................................................................................................... 46 INSERTing New Segments .................................................................................................... 47 DELETE Calls ................................................................................................................ 48 DELETE Segments ................................................................................................................ 48 GET HOLD and DELETE Functions ...................................................................................... 48 GET HOLD Precedes DELETE .............................................................................................. 49 DLET Call Status Codes......................................................................................................... 49 Using SSAs with DLET .......................................................................................................... 50

IMS/DB - 3

COMMAND CODE in a DLET Call ......................................................................................... 50 Summary ................................................................................................................................ 50

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

Status Code Checking ................................................................................................. 51 Introduction ............................................................................................................................. 51 Status Codes .......................................................................................................................... 51 Checking GET Calls ............................................................................................................... 51 Unexpected Status Codes ...................................................................................................... 51 Standard Abend/Error Routines ................................................................................. 52 The DL/I Standard Error Routine ............................................................................................ 52 Abending the Program ............................................................................................................ 52 Efficient Segment Access Strategy ............................................................................ 53 Segment Access .................................................................................................................... 53 ISRT Calls .............................................................................................................................. 53 Hierarchical Access ................................................................................................................ 53 Segment Search Arguments .................................................................................................. 53 Search Fields .......................................................................................................................... 53 Secondary Indices .................................................................................................................. 54 Multiple PCBs ......................................................................................................................... 54 Review of BMPs ..................................................................................................................... 54 Advantages and Disadvantages ............................................................................................. 54 Checkpoints .................................................................................................................. 55 Checkpoint Calls..................................................................................................................... 55 Two Kinds of Checkpoint Calls ............................................................................................... 55 Frequency of Checkpoint Calls ............................................................................................... 55 Standards and Guidelines ...................................................................................................... 55 Summary ................................................................................................................................ 55

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

Compiling and EXECUTION JCL ................................................................................ 56 Compiling................................................................................................................................ 56 Application Components......................................................................................................... 56 IMS Subroutine ....................................................................................................................... 56 Subroutines ............................................................................................................................ 56 Debugging with DL/I Test Program DLT0 .................................................................. 57 The EXECUTE JCL ................................................................................................................ 57 Testing Tools .......................................................................................................................... 57 Control Statements ................................................................................................................. 57 DLT0 JCL and Control Statements ........................................................................................ 58 Coding Errors ......................................................................................................................... 58 The Linkage Section ............................................................................................................... 58 Linkage Example .................................................................................................................... 59 Debugging a Program ............................................................................................................ 59 Summary ................................................................................................................................ 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

Introduction A 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 Goals Databases 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 customers address repeated in many files w/in: a customers records system a purchase order system an accounts receivable system This redundancy in the conventional file processing system could cause problems when a customers 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

IMS/DB PROGRAMMING I
Module I : IMS Database Structures General Database Objectives IMS Hierarchical Structure Components Concepts of Root, Parent, and Child

Common Database Structures How databases are organized: There are three common types of database structures: 1. Relational 2. Network 3. Hierarchical Relational Databases A relational database looks something like this: Key field Soc. Security # (An employee record) Key field Data d (A department record) Fields in one record type are used to point to other record types. Network Databases A network database might look like this: Company Club Data

Building

Vehicle

Person

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

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

Registration

Degrees

High School

Club

Comments

Reports

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/VS Since this course will be dealing w/ IMS/VS, lets begin by defining IMS. Definition: IMS/VS is an acronym that stands for Informational Management System/Virtual Storage. It is IBMs 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 Database Throughout the remainder of the course, we will be using an example database. Part of our PERSONNEL database looks like this:

Employee

Work History

Dependents

Benefit Data

IMS Hierarchical Components If you want to work effectively with IMS, you should know what the components of its hierarchical structure are and how they are related. Well 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. Segments Each box in the database hierarchy chart represents a segment.

IMS/DB - 7

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: Employee

Work History

Dependents

Benefit Data

Depending on your application program, DL/I reads segments that point to other segments in a specified sequence. Heres 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 redefine the Input/Output area. As an illustration, part of your EMPLOYEE database might be defined like this:

01 IO-AREA PIC 01 EMPLOYEE REDEFINES IO-AREA. 05 EMP-ID PIC 05 EMP-LASTNAME PIC 05 EMP-FIRSTNAME PIC 05 EMP-PHONENUM PIC . . .

X(100). X(11). X(15). X(15). 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). . . .

Fields Although 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 Types Two 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 KEY and SEARCH fields must be defined to IMS. You will see how when we look at the database description.

8 IMS/DB

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

IMS/DB PROGRAMMING I
Module I : IMS Database Structures General Database Objectives IMS Hierarchical Structure Components Concepts of Root, Parent, and Child

Parent and Child Segments In 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 Segments A 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. 1. Parent

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

Root Segments Segment 1 is a root segment because it has no parent. All hierarchical database structures have a single root segment at the top. Dependent Segments Dependent 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. Heres 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 Limitations IMS 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 Occurrences You 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

Segments 5 and 6 are not twins, they are known as siblings under segment 4. Similarly, segments 2, 3, and 4 are siblings. Review With 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:

Summary By 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 Definition Logical Database Definition

Introduction IBMs 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 I Data 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 System IMS 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 Environment The 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 FDs. 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:

start

Application Program DB PCB I/O PCB

DL/I

IMS Data Communication

IMS Database

Terminal

Here is the processing flow for on-line processing: Application Program DB PCB I/O PCB

DL/I

IMS Data Communication

start IMS Database Terminal

IMS/DB - 13

IMS/DB PROGRAMMING I
Module II : The IMS Environment Components of an IMS Environment Modes of Processing Physical Database Definition Logical Database Definition

Modes of Processing Within 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 Structure In 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 Database The 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 bottom from left to right

The Logical Database The 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

IMS/DB PROGRAMMING I
Module II : The IMS Environment Components of an IMS Environment Modes of Processing Physical Database Definition Logical Database Definition

Defining the Physical Database Defining 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. DBDGEN The 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 Statements Here is an example of how to code a DBD using DBDGEN control statements. We will use our EMPLOYEE database. DBD NAME=EMPLOYEE,ACCESS=(HIDAM,OSAM) DATASET DD1=DDEMP,DEVICE=3380,SIZE=(4096),FRSPC=(10,10) SEGM NAME=EMPDATA,PARENT=0,BYTES=100 FIELD NAME=(EMPID,SEQ,U),BYTES=11,START=1,TYPE=C SEGM NAME=WORKDATA,PARENT=EMPDATA,BYTES=200 FIELD NAME=(DEPTID,SEQ,U),BYTES=5,START=1,TYPE=C DBDGEN FINISH END

DSGROUP0

. . .

DBD Statement The 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 Statement The 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 Statement There is one SEGM statement for each segment in the database. The SEGM statement: names the segment (max 8 characters)

16 IMS/DB

identifies the PARENT segment establishes the length of the segment Note: PARENT=0 signifies that EMPDATA is the root segment.

FIELD Statements Field 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 Process The 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 DBDs to find out, for example, what the key fields or search fields are in a particular segment.

IMS/DB - 17

IMS/DB PROGRAMMING I
Module II : The IMS Environment Components of an IMS Environment Modes of Processing Physical Database Definition Logical Database Definition

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

WORK-HISTORY

DEPENDENTS

BENEFIT-DATA

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 its 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 PCBs (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 PSBs. 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 PCBs. 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. PROCOPTs Valid PROCOPTs include: G for GET (READ) I for INSERT R for REPLACE D for DELETE

18 IMS/DB

A for all options (G,I,R,D) L for LOAD (initial load of data) K for access to only the KEY of the segment O for ONLY - used with G to indicate that Get Hold calls are not allowed P for PATH calls Example of PSB with One PCB Heres an example of a PSB w/ only one PCB. It defines a logical data structure: PCB SENSEG SENSEG PSBGEN END TYPE=DB,DBDNAME=EMPDBD,KEYLEN=16 NAME=EMPDATA,PARENT=0,PROCOPT=K NAME=WORKDATA,PARENT=EMPDATA,PROCOPT=G LANG=COBOL,PSBNAME=EMPPSB1

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.

Summary By now you should be familiar with: 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

IMS/DB PROGRAMMING I
Module III : IMS Application Programming Function Codes Segment Search Arguments (SSAs) I/O Area PCB Mask Procedure Divisions

The Working-Storage Section The first section containing any IMS-related components is the WORKING-STORAGE SECTION. Lets begin by looking at the three highlighted components: 1. FUNCTION CODES 2. INPUT/OUTPUT AREA 3. SEGMENT SEARCH ARGUMENT(SSA) Function Codes A 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 Function The 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 database 2. 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 I
Module III : IMS Application Programming Function Codes Segment Search Arguments (SSAs) I/O Area PCB Mask Procedure Divisions

SSA Overview Your 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. Name Description 3. One or more command codes to qualify your DL/I call even more Name Description Command 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.

IMS/DB PROGRAMMING I
Module III : IMS Application Programming Function Codes Segment Search Arguments (SSAs) I/O Area PCB Mask Procedure Divisions

The Input/Output Area The 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 01 IO-AREA-GENERIC PIC X(500) VALUE SPACES.

IMS/DB - 21

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

01 IO-AREA

PIC X(100).

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

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

22 IMS/DB

IMS/DB PROGRAMMING I
Module III : IMS Application Programming Function Codes Segment Search Arguments (SSAs) I/O Area PCB Mask Procedure Divisions

The Program Communication Block The 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 program 01 DB-PCB-1. will access. The 01 level name should be unique for each 03 . . . 03 . . . . . . database:

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

01 DB-PCB-1. 03 . . . 03 . . . . . . 01 DB-PCB-2. 03 . . . 03 . . . . 03 . . . . .

Lets take a look at an 03 level This is a sample of how you would code each PCB mask. WORKING-STORAGE SECTION. LINKAGE SECTION 01 DB-PCB-1. 03 DBD-NAME 03 SEG-LEVEL 03 STATUS-CODE 03 PROC-OPTIONS 03 IMS-ADDRESS 03 SEGMENT-NAME 03 KEY-LENGTH 03 NUM-SENS-SEGS 03 KEY-FEEDBACK. 05 SEG-KEYS PIC PIC PIC PIC PIC PIC PIC PIC X(8). X(2). X(12). X(4). X(4). X(8). S9(5) COMP. S9(5) COMP.

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.

IMS/DB - 23

IMS/DB PROGRAMMING I
Module III : IMS Application Programming Function Codes Segment Search Arguments (SSAs) I/O Area PCB Mask Procedure Divisions Procedure Divisions We will now talk about the components that must be coded in the procedure division. ENTRY and EXIT statements DL/I CALL statements The Entry Statement Code the ENTRY statement as the first executable statement in your application program. It must follow immediately after the title PROCEDURE DIVISION. For example:

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

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 Calls DL/I retrieval calls are covered in detail in MODULE 5. Text RETRIEVAL: GU Get Unique GN Get Next GNP 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 Statement The 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 Components Heres 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.

24 IMS/DB

Working-Storage

FUNCTION CODES SEGMENT SEARCH AREA (SSA) INPUT/OUTPUT AREA PROGRAM COMMUNICATION BLOCK (PCB) ENTRY/EXIT STATEMENTS DL/I CALL STATEMENT

Linkage Section

Procedure Division

Summary By now you should be familiar with: 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.

IMS/DB - 25

IMS/DB PROGRAMMING I
Module IV : Segment Search Arguments Unqualified SSAs Qualified SSAs OPERATOR Field Command Codes

Segment Search Argument In 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 QUALIFIED

searches for a specific segment type searches for a specific occurrence of a specific segment type

Unqualified SSAs An 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. WORKING STORAGE. . 01 HISTORY-SSA. 05 SEGMENT-NAME PIC X(9) VALUE HISTORY . NOTE: The 9 position in the literal must be blank. th This blank in the 9 byte indicates an unqualified SSA.
th

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: SENSEG NAME=HISTORY,PARENT=xxxxxxxx,PROCOPT=x. Unqualified SSA Example Assume that your program needs to find out how many employees have worked for the company for more than 10 years.

26 IMS/DB

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

EMPLOYEE

WORK-HISTORY

DEPENDENTS

BENFIT-DATA

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. WORKING STORAGE. . 01 SSA-WORK-HISTORY PIC X(9) VALUE WORKHIST .

Qualified and Unqualified SSAs Some 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 leftmost parenthesis, by moving spaces to BEGIN-QUALIFY. 01 SSA-EMPLOYEE. 03 SEGMENT-NAME PIC X(8) VALUE 03 COMMAND-CODE PIC X(2) VALUE 03 BEGIN-QUALIFY PIC X(1) VALUE 03 KEYNAME PIC X(9) VALUE 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. *-. (. EMPKEY . =. ).

IMS/DB - 27

IMS/DB PROGRAMMING I
Module IV : Segment Search Arguments Unqualified SSAs Qualified SSAs OPERATOR Field Command Codes

Qualified SSAs Now 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. WORKING STORAGE. .. 01 SSA-EMPLOYEE. 03 SEGMENT-NAME PIC X(8) VALUE 03 COMMAND-CODE PIC X(2) VALUE 03 BEGIN-QUALIFY PIC X(1) VALUE 03 KEYNAME PIC X(8) VALUE 03 OPERATOR PIC X(2) VALUE 03 KEY-VALUE PIC X(11). 03 END-QUALIFY PIC X(1) VALUE

EMPLOYEE. *-. (. EMPKEY . =. ).

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: FIELD NAME=(EMPKEY,SEQ,U),BYTES=11,START=. . . 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 Example Assume 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. PROCEDURE DIVISION. . . . . MOVE 2345678912 TO KEY-VALUE. CALL CBLTDLI USING FUNC-CODE,PCB-MASK1,IO-AREA,SSA-EMPLOYEE. You can also move a variable into KEY-VALUE that had been previously assigned the employee number.

28 IMS/DB

IMS/DB PROGRAMMING I
Module IV : Segment Search Arguments Unqualified SSAs Qualified SSAs OPERATOR Field Command Codes

OPERATOR Field So far we have talked about each of the highlighted fields. 01 SSA-EMPLOYEE. 03 SEGMENT-NAME 03 COMMAND-CODE 03 BEGIN-QUALIFY 03 KEYNAME 03 OPERATOR 03 KEY-VALUE 03 END-QUALIFY

PIC PIC PIC PIC PIC PIC PIC

X(8) VALUE X(2) VALUE X(1) VALUE X(8) VALUE X(2) VALUE X(11). X(1) VALUE

EMPLOYEE. *-. (. EMPKEY . =. ).

There are only two fields left to discuss. Lets 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 = EQ Not equal to ~= =~ NE Less than < LT Less than or equal to <= =< LE Greater than > GT Greater than or equal to >= => GE

IMS/DB - 29

IMS/DB PROGRAMMING I
Module IV : Segment Search Arguments Unqualified SSAs Qualified SSAs OPERATOR Field Command Codes

COMMAND-CODE Field The 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. 01 SSA-EMPLOYEE. 03 SEGMENT-NAME 03 COMMAND-CODE 03 BEGIN-QUALIFY 03 KEYNAME 03 OPERATOR 03 KEY-VALUE 03 END-QUALIFY

PIC PIC PIC PIC PIC PIC PIC

X(8) VALUE X(2) VALUE X(1) VALUE X(8) VALUE X(2) VALUE X(11). X(1) VALUE

EMPLOYEE. *-. (. EMPKEY . =. ).

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 path F Access first segment occurrence L Access last segment occurrence U Maintain current position at this level V Maintain current position at this and higher levels N Do NOT replace this segment C Use a concatenated key P 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 Example Lets 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.

30 IMS/DB

2 B 1 C 1

Here is an SSA using F command code that obtains the first occurrence of the DEPENDENTS segment (called DEPENDENT). 01 SSA-DEPENDENTS. 03 SEGMENT-NAME 03 COMMAND-CODE . . .

PIC X(8) VALUE DEPENDENT. PIC X(2) VALUE *F.

EMPLOYEE

WORK-HISTORY

DEPENDENTS

BENFIT-DATA

Other Uses of COMMAND CODES Here 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 organizations standards and conventions for using these and other command codes.

Summary By now you should be familiar with: SSAs The difference between qualified and unqualified SSAs. Relational operators. The use of command codes.

IMS/DB - 31

IMS/DB PROGRAMMING I
Module V : DL/I Retrieval Calls DL/I CALL Statement Segment Sequence Function Codes PATH Calls

DLI CALL Statement In 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. Lets find out what those parameters/arguments are Parameters/Arguments This is a CALL to DL/I with all the parameters. Well look at each of these parameters in a little more detail shortly, but for now heres a brief overview of each parameters role. 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.

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

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.

32 IMS/DB

Accessing an IMS Database When you access an IMS database with a DL/I call, you will be using one of these FUNCTION CODES: RETRIEVAL: Get Unique Get Next Get Next Within Parent RETRIEVAL WITH INTENT TO UPDATE Get Hold Unique Get Hold Next Get Hold Next Within Parent UPDATE INSERT DELETE Replace Insert Delete GU GN GNP GHU GHN GHNP REPL ISRT DLET

IMS/DB PROGRAMMING I
Module V : DL/I Retrieval Calls DL/I CALL Statement Segment Sequence Function Codes PATH Calls

Segment Sequence Review REMEMBER: 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/VS would traverse the keys of this hierarchical database.

12 1 AKEY 7 11 EKEY

BKEY 4 CKEY 6 DKEY

10 FKEY

IMS/DB - 33

IMS/DB PROGRAMMING I
Module V : DL/I Retrieval Calls DL/I CALL Statement Segment Sequence Function Codes PATH Calls

Function Codes During 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 Call The Segment Search Argument (SSA-1)

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.

is used to build the following GU call GU SEGMENTA *-(AKEY=12). The GU function that is defined by SSA-1 as shown, will get the segment with AKEY=12.

34 IMS/DB

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

12 AKEY

11 EKEY

BKEY 4 CKEY 6 DKEY GU

10 FKEY

You accomplish this using the following code:

SEGMENTA *-(AKEY=1) SEGMENTB *-(BKEY=2) SEGMENTD *-(DKEY=6)

Verifying the GU call You 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 Codes When 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.

IMS/DB - 35

No SSA If 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 SSA With an UNQUALIFIED SSA, DL/I will retrieve the next occurrence of the segment type specified in the SSA. 01 SSA-1. 03 SEGMENT-NAME PIC X(8) VALUE SEGMENTA. 03 BEGIN-QUALIFY PIC X(1) VALUE SPACE. 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 SSA Using fully qualified SSAs with GN calls clearly identifies the hierarchical path and segment that you require. Using this GN call GN SEGMENTA *-(AKEY SEGMENTB *-(BKEY =1) =2) you will get segment

Note the GN with a qualified SSA starts at the current database position and performs an implied GU. 2

12 AKEY

BKEY 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. Lets take a look at an example.

36 IMS/DB

Establishing Parentage This GU will establish the parent segment #2 since this was the last successful retrieval. GU SEGMENTA *-(AKEY =1) SEGMENTB *-(BKEY =2) 1 12 AKEY 7 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 3 4 CKEY 5 6 DKEY then segment 5 and then segment 6

BKEY

Additional Example Lets take a look at one more The GU function establishes the parent segment as segment #11.

12 AKEY 11 EKEY

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

10 FKEY

The first GNP function will be unsuccessful, as segment #11 has no dependents. Function Codes You 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:

IMS/DB - 37

Specifying a Path of Segments Assume 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 of segments, and have all segments retrieved into the IO-AREA. You use the D command code, known as the PATH command, to create PATH calls. 4 CKEY 7 1 12 AKEY 11 EKEY

BKEY 6 DKEY

10 FKEY

Lets write the function that will retrieve these segments for us.

IMS/DB PROGRAMMING I
Module V : DL/I Retrieval Calls DL/I CALL Statement Segment Sequence Function Codes PATH Calls

PATH Calls The 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:

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

The IO-AREA needs to be as large as the sum of all the segments being retrieved in the call. 2ND NOTE: The D command is not required for the last segment in the path. 3 4 CKEY 2 7

1ST

12 AKEY 11 EKEY

BKEY 6

3RD DKEY

10 FKEY

Coding a Segment Since 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.

GN SEGMENTA *D(AKEY =1) SEGMENTE *SEGMENTF *-(FKEY =10) 38 IMS/DB

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

One Final Word About PATH Calls The 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. Summary By now you should be familiar with: 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 Functions Earlier 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 Calls There are three GET HOLD calls corresponding to each of the GET calls we learned about earlier in this series. 1. GHU GET HOLD UNIQUE 2. GHN GET HOLD NEXT 3. 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 Integrity The GET HOLD calls maintain data integrity by signifying to IMS that your application program intends to update a particular segment

Updates

Application

IMS Database

IMS/DB - 39

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

Application

IMS Database

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 TIP The 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.

40 IMS/DB

IMS/DB PROGRAMMING II
Module I : Updating Segments GET HOLD Calls REPLACE Call REPLACE with Command Codes

The REPL Call Assume that we want to change an employees 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 Call One 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. Lets take a look at the code that will accomplish this: . . . . . . . . . . . . . . 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. This segment of code: Retrieves Jennys record into the IO-AREA.

Insures that the GET-HOLD call was successful.

Moves the new last name into the EMP-IO AREA. We are now ready to issue the REPL call. Heres the REPL call to replace Jennys record.

CALL CBLTDLI USING

FUNTION-REPL, EMPLOYEE-PCB, EMP-IOAREA.

IF PCB-STATUS-CODE = THEN GO TO REPL-EXIT________________ ELSE :

This code checks that the REPL call was successful.

Lets find out what STATUS-CODES the REPL call may return.

IMS/DB - 41

REPL Status-Codes Two 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.

IMS/DB PROGRAMMING II
Module I : Updating Segments GET HOLD Calls REPLACE Call REPLACE with Command Codes

The REPL Call Here 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. CALL CBLTDLI USING FUNCTION-REPL, EMPLOYEE-PCB, EMP-IOAREA.

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 Function Heres 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. 12 1 GHU SEGMENTA *D(AKEY =1) AKEY SEGMENTB *D(BKEY =2) SEGMENTC 7 2 REPL SEGMENTA *N SEGMENTB *N BKEY This will retrieve #1, #2, #3 segments in the IO-AREA, but only replace segment #3. 4

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

42 IMS/DB

Relationships Between Functions You 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. Summary By now you should be familiar with: 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 Code To 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. LOAD Mode INSERT Mode

Lets look at the difference between the LOAD mode and the INSERT mode. Program Specification Block You 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 Mode In LOAD mode, only two processing options are allowed: LOAD Mode LOAD LOAD Sequential

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. LS is usually preferred as it specifies that segments must be loaded in ascending sequence.

IMS/DB - 43

A brief discussion of access methods follows HSAM HSAM: 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). HISAM HISAM: 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). HDAM HDAM: 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). HIDAM HIDAM: 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 Mode In INSERT mode, processing options can be: INSERT Mode INSERT INSERT in Sequence

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 Code Here 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 nonunique KEY will be inserted according to insert rules specified in the DBD. INSERT RULE Options Lets see the INSERT RULE options in the DBD.

44 IMS/DB

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.

IMS/DB - 45

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 INSERTing New Segments Now lets 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: CALL CBLTDLI USING FUNCTION-ISRT, EMPLOYEE-PCB, EMP-IOAREA, EMP-SSA. This must be an UNqualified SSA.

The new segment to be inserted must have only one unqualified SSA. However, in order to insert a new 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:

CALL CBLTDLI USING

FUNCTION-ISRT, EMPLOYEE-PCB, EMP-IOAREA, A-SSA, B-SSA, C-SSA.

Where the SSAs look like:

SEGMENTA *-(AKEY SEGMENTB *-(BKEY SEGMENTC

=1) =2)

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

12 AKEY 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.

BKEY 4 CKEY

5 DKEY

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 CODE Remember always check the STATUS CODE after making a DL/I call.

46 IMS/DB

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 Segments Notice 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. CALL CBLTDLI USING FUNCTION-ISRT, EMPLOYEE-PCB, EMP-IOAREA, A-SSA, B-SSA, C-SSA.

SEGMENTA *-(AKEY SEGMENTB *-(BKEY SEGMENTC

=1) =2)

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

IMS/DB - 47

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 DELETE Segments Just 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 Functions To illustrate the use of GET HOLD and DELETE functions, lets 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 Jennys database record. GU EMPLOYEE HISTORY Segment 1 Segment 2 Segment 3 GU GHU

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

HOLD
EMPLOYEE HISTORY

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

HOLD
EMPLOYEE HISTORY History Segment

A DLET call to the active EMPLOYEE database remove Jennys record.

GU GHU ISRT DLET

HOLD
EMPLOYEE HISTORY

48 IMS/DB

We have already completed our GU calls to retrieve the data from Jennys active employee record, and used that information to build the history segment in the history IO-AREA. Lets retrieve Jennys record with a GET HOLD UNIQUE. MOVE 356-74-5555 TO EMP-ID. CALL CBLTDLI USING FUNC-GHU, EMPLOYEE-PCB, EMP-IOAREA, EMP-SSA. Next, well insert this segment into the HISTORY database: CALL CBLTDLI USING FUNC-ISRT, HISTORY-PCB, EMP-IOAREA, HISTORY-SSA.

Dont 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 Jennys record on the EMPLOYEE database. No SSAs are needed. All segments under the root segment will also be deleted by the one DLET call. CALL CBLTDLI USING FUNC-DLET, HISTORY-PCB, EMP-IOAREA.

GET HOLD Precedes DELETE We 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 HISTORYPCB. EMPLOYEE-PCB DLET Call GHU Call Dont forget we also checked the status codes after each call. DLET Call Status Codes Now lets look at some status codes that we might see with the DLET call: DA DJ DX - 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. HISTORY-PCB ISRT Call

IMS/DB - 49

Using SSAs with DLET Normally 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 GHU Axxxxxx Bxxxxxx Cxxxxxx *D(AKEY *D(BKEY =1) =2)

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

REPL Axxxxxx Bxxxxxx Cxxxxxx

*N *N will only replace #1.

DLET Bxxxxxx

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

COMMAND CODE in a DLET Call No command codes apply to DLET. If you issue a COMMAND CODE in a DLET call, DL/I disregards the COMMAND CODE. Summary By now you should be familiar with: 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.

50 IMS/DB

IMS/DB PROGRAMMING II
Module III : Programming Techniques Status Code Checking Standard Abend/Error Routines Efficient Segment Access Strategy Checkpoints

Introduction When 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 CODES 2. SEGMENT ACCESS 3. CHECKPOINTS Status Codes Recall 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. Lets 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 Calls Besides checking each call for SPACES, if you are making GET calls, you may also test for: GA GB GE GK DL/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. DL/I reached the end of the database and therefore could not return a segment to your program. DL/I could not find the segment you asked for. This could happen after a GU, GN, or GNP call. DL/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 Codes When 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.

IMS/DB - 51

IMS/DB PROGRAMMING II
Module III : Programming Techniques Status Code Checking Standard Abend/Error Routines Efficient Segment Access Strategy Checkpoints

The DL/I Standard Error Routine The 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 Program Now 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 Supervisor 2. 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. Lets move on to look at SEGMENT ACCESS

52 IMS/DB

IMS/DB PROGRAMMING II
Module III : Programming Techniques Status Code Checking Standard Abend/Error Routines Efficient Segment Access Strategy Checkpoints Segment Access When 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 Calls 2. Hierarchical Access 3. Segment Search Arguments 4. Search Fields 5. Secondary Indices 6. Multiple PCBs ISRT Calls If 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 Access When 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 bottom o Left to right Segment Search Arguments Qualified 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 Fields The 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 fields 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.

IMS/DB - 53

Secondary Indices A 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

Main Database

Secondary index databases are connected to the main database in the DBDGEN. Multiple PCBs A 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. Project Manager Manager Employee Employee Manager Employee One PCB can point to the managers to whom the employees report. Employee A second PCB can point to the reporting employees.

Review of BMPs The last area we will look at is checkpoints, however, before we talk about checkpoints lets 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 Disadvantages The 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.

54 IMS/DB

IMS/DB PROGRAMMING II
Module III : Programming Techniques Status Code Checking Standard Abend/Error Routines Efficient Segment Access Strategy Checkpoints

Checkpoint Calls Checkpoint 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 Calls There are two kinds of Checkpoint calls: 1. BASIC 2. 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 Calls In 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 Guidelines Most 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. Summary By now you should be familiar with: 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.

IMS/DB - 55

Reasons for using Checkpoint calls.

IMS/DB PROGRAMMING II
Module IV : Compiling, Executing, and Debugging Compiling and EXECUTION JCL Debugging with DL/I Test Program DLT0

Compiling IMS 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 Components So now that you know all about CODING and COMPILING your IMS application program, lets see how to execute it. Your IMS application program is actually a subroutine . To illustrate, remember the format of the DL/I Call statement? CALL CBLTDLI USING FUNCTION_CODE, PCB_1, IO_AREA, SSA_1.

IMS Subroutine Your 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. Subroutines Remember, 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: DL/I TO COBOL ====> ENTRY DLITCBL USING PCB_1

Your application program calls DL/I subroutines with the:

COBOL TO DL/I ====> CALL CBLTDLI

56 IMS/DB

IMS/DB PROGRAMMING II
Module IV : Compiling, Executing, and Debugging Compiling and EXECUTION JCL Debugging with DL/I Test Program DLT0

The EXECUTE JCL What does the EXECUTE JCL look like? //STEP1 EXEC PGM=DFSRRC00,PARM=(DLI,pgmname,psbname

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 Tools Your installation may have special IMS testing software tools. IBM supplies a testing tool for IMS called DFSDDLT0. DFSDDKT0 (or DLT0, as its 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 Statements There are four control statements that inform the DLT0 which DL/I CALL to execute: 1. STATUS: establishes print options for DLT0s 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.

IMS/DB - 57

DLT0 JCL and Control Statements This is an example of DLT0 JCL and control statements that replace a segment on the EMPLOYEE database. //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)

For more information on DLT0, see the IMS Applications Program Manual. Coding Errors You 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. Lets take a look at some information that IMS provides for that purpose The Linkage Section Remember the sample PCB Mask? We have already covered status code field. These fields contain the level number and segment name of the segment that was successfully retrieved in the call. LINKAGE SECTION. 01 DB-PCB-1. 03 DBD-NAME 03 SEG-LEVEL 03 STATUS-CODE 03 PROC-OPTIONS 03 IMS-RESERVED 03 SEGMENT-NAME 03 KEY-LENGTH 03 NUM-SENS-SEGS 03 KEY-FEEDBACK. 05 SEG-KEYS PIC PIC PIC PIC PIC PIC PIC PIC X(08). X(02). X(02). X(04). S9(5) COMP. X(08). S9(5) COMP. S9(8) COMP. At entry time, this field contains the name of the database that IMS tried to access

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

PIC X(##).

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.

58 IMS/DB

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 Example In the EMPLOYEE database, the EMPID field (11 bytes long) is the key to the EMPLOYEE segment. EMPLOYEE key EMPID The DEPTID field (length 5) is the key to the WORKDATA segment. WORKDATA key DEPTID 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 Program Here 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. Summary By now you should be familiar with: 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.

IMS/DB - 59