PIMS

MODULE 1: IMS DATABASE STRUCTURES Learning Objectives By the end of this module you will be able to Define the database Identify major data-related goals Identify the components in the IMS hierarchy Navigate through the segments in a database

A database is not really anything new. It is just 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 the exact file structure. People looking at files to which they should not have access. Programs needing to be changed when the data is organized differently.

Databases are used to meet 4 main data-related goals. 1. 2. 3. 4. Increase data independence Reduce data redundancy Increase data security Maintain data integrity

1.

Increase data independence in traditional processing environments, the data and the programs are dependent on each other. PROGRAM A DATA FILE PROGRAM B
If the format of the data is changed or re-organized, the programs dependent on that data must also be changed. For example, suppose you need three lines for an address instead of two, the data would have to be changed as well as all the programs.

In traditional processing environments, the data and the programs are dependent on each other.
In database processing, the data and the programs are INDEPENDENT A change in the data organization will NOT USUALLY affect the user programs.

INDEPENDENT DATA FILES

PROGRAM A PROGRAM B PROGRAM C

2. Reduce data redundancy in a conventional file systems, the same data may be stored in many different files to meet the requirements of the different applications. Thus some of the data is unnecessarily repeated (redundant). With traditional file processing, it is possible to find a customers address in my files: Customers record system. Purchase order system. Account 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 error. In a database system, different application systems share the same centralized data.
PURCHASE ORDER SYSTEM ACCOUNTS RECEIVABLE SYSTEM

DATABASE
CUSTOMER RECIRDS SYSTEM

3. Increase data security you are already familiar with 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 the data itself. Example 1: a programmer can read, but not update certain data. Example 1: only certain people may be allowed to access salary data. So, most databases have security features which authorize access to the data and place restrictions on the operations that may be performed on the data. Such features and restrictions enable the database to meet another of its goals to increase data security. 4. Maintain data integrity everyone who uses the database, from the database administrator to the programmer to the end user, is responsible for the integrity of the data. Maintaining 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 end up to be invalid or unreliable. Centralized control of the database insures that data integrity is maintained. Why is data integrity so important? the data could become meaningless

There are three common types of database structures. 1. Relational fields in one record type are used to point to other record types.

2. Network data is organized so that the PERSON segment is directly dependent on both COPANY 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 structures from hierarchical structure. A network database structure can be considered an expansion of the hierarchical structure.

3. Hierarchical IMS/VS is an example of a hierarchical database.

In hierarchical database There is always a basic or root segment. A segment may relate downward 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 is an acronym which stands for INFORMAION MANAGEMENT SYSTEM / VIRTUAL STORAGE. It is IBMs software product for creating and managing the physical storage and retrieval of data which 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 languageDL/I Throughout the remainder of the course, we will be using an example database. Part of our PERSONNEL database looks like this:

If you want to work effectively with IMS, you should know what components of its hierarchical structures are and how they are related. Well be discussing these components by defining terms such as: FIELDS. SEGMENTS, PARENT, CHILD. Youll be seeing a lot of these terms in upcoming modules. SEGMENT is the smallest block of information that DL/I can access in the database. Each segment has a unique name. In our PERSONNEL database, the segments are called:

Depending on your application program, DL/I read segments that point to other segments in a specified sequence. Heres one way DL/I could read the segment to get all the employee information. EMPLOYEE>>>WORK HISTORY EMPLOYEE>>>DEPENDENTS EMPLOYEE>>>BENEFIT DATA 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 (FD). Common practice is to redefine the input/output area (more details on this later). As an illustration, part of our EMPLOYEE database might be defined like this:
01 IO-AREA PIC X(100). 01 EMPLOYEE REDEFINED IO-AREA. 05 EMP-ID PIC X(11). 05 EMP-LASTNAME PIC X(15). 05 EMP-FIRSTNAME PIC X(15). 05 EMP-PHONENUM PIC X(10). *** 01 WORK-HISTORY REDEFINES IO-AREA. 05 DEPT-ID PIC X(10).

05 POSITION 05 BEGIN-DATE 05 REVIEW-DATE

PIC X(12). PIC X(8). PIC X(8).

Although the segment is the smallest block of information that DL/I can handle. It is not the smallest unit in the database. the FIELD is the smallest unit of information in the database. Each segment contains one or more fields of information. Tow type 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 defined to IMS. Difference: The KEY field is used to sequence the segments. Because of this, the value in KEY FIELD may not be changed In contrast, the SEARCH FIELDS may be changed at your will, depending on your application program.

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. A PARENT segment is a segment that has one or more segments depending on it. These dependent segments must be on the level directly below the parent.

Example 1: 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 are all the segments under a particular segment of a database. 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. Above example have 9 SEGMENT TYPES and 3 LEVELS.

Example 2: You will notice that there are 3 occurrences of segment 8. You can have as many segment occurrences as you want, as long as your storage medium can handle them.

TWIN is when a parent segment has multiple occurrences of a particular child segment, we call those children TWINS. In the diagram above, the three occurrences of segment 8 are called TWINS (even though there are three them). Segments 8 and 9 are not twins; they are known as SIBLINGS under segment 7. Similarly segments 2, 6 and 7 are siblings, as are segments 3, 4 and 5. In a DATABASE RECORD we have only one occurrence of the root segment and all its dependent segments. You application program calls DL/I to access information from one database record at the time. Each DL/I call works with one segment or a path of segments from this database record.

MODULE 2: THE IMS ENVIRONMENT Learning Objectives By the end of this module you will be able to List and describe the components of an IMS environment Discuss the three IMS processing modes: batch, BMP and MPP. Define PCBs in the PSB to create a logical database. Understand the purpose and recognize the components of a Database Description (DBD).

What is IMS? IBMs IMS (information management system) is one of the oldest databases 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

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

IMS supports user-written batch processing and telecommunication applications. It provides: - Database management services that support multiple applications using a common database. Database or DB system. - Data communication management services that supports 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. The components of the IMS software environment:

Application programs you can write these in COBOL, PL/I and assembler. The programs use standard calls to DL/I modules rather than read and write through FDs. DB PCB this is a program communication block 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 which performs operations on the data base when the called by application programs. IMS database the database could be called the center id the IMS systems. It normally resides on direct access storage. I/O PCB this is a program communication block which 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 which 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. Here is the processing flow when you are in DL/I batch processing: Application Program DB PCB DL/I IMS Database

Now heres the processing flow for on-line processing: Application Program

DB PCB

I/O PCB

DL/I

IMS Data
Communication

IMS Database

Terminal

Within IMS there are 3 modes of processing: Batch Data Language I (Batch DL/I) True batch processing BMP (Batch message processing) Combination of on-line and batch processing TP/MPP Teleprocessing (Message processing program) (True on-line processing)

Batch DL/I: No data communication services or terminal are used. Transactions are batch-generated and saved in standard files. Runs are initiated using JCL. Processing output is in a hard copy format. Database accessed are off-line.

BMP: There are 2 kinds of BMP 1. 2. Transaction-oriented Access the online message queues Can process input from and output to OS/VS files and databases. Batch-oriented Access online database in batch mode Can send messages to the message queue Are scheduled by the operator using JCL

TP (also called MPP for message processing program) Transactions are entered at the terminal. Transactions are put in message queue file. IMS scheduler immediately invokes the appropriate program to process the transactions. Processing output may be in hard copy format. Or, it may be sent back as a screen m Message to the originating terminal or an alternate terminal. Databases accessed are on-line.

THE PHYSICAL DATABASE represents how the data is actually recorded or stored on the storage medium (usually disk). Database records, composed of the root segments and all of its dependent segments are stored in hierarchical sequence: TOP to BOTTOM, LEFT to RIGHT LOGICAL DATABASE represents the sequence of segments from one or more physical databases required by an application program. These segments are combined to create a new hierarchical structure. The physical database is defined in the DataBase Decription (DBD) whereas logical data structure is defined in the program specification block (PSB) Defining the physical database is often the responsibility of the DBA (database administrator). The DBA ask the database design team for the following information: The hierarchical structure The key fields The search fields

The DBA initiated 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.

DSGROUP0

DBD DATASET SEGM FIELD SEGM FIELD

NAME=EMPLOYEE,ACCESS=(HIDAM,OSAM) DD1=DDEMP,DEVICE=3380,SIZE=(4096),FRSPC=(10,10) NAME=EMPDATA,PARENT=0,BYTES=100 NAME=(EMPID,SEQ,U),BYTES=11,START=1,TYPE=C NAME=WORKDATA,PARENT=EMPDATA,BYTES=200 NAME=(DEPIT,SEQ,U),BYTES=5,START=1,TYPE=C

. . . DBDGEN FINISH END to indicate the end of DBDGEN process.

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)

The dataset statement specifies: The DD name used in the JCL Disk DEVICE type (e.g. 3380) Blocksize (e.g. 4096) Freespace % (FRSPC)

There is one SEGM statement for each segment in the database. SEGM: Names the segment (max 8 characters) Identifies the PARENT segment Establishes the length of the segment Note: PARENT=0 signifies that EMPDTA is the root segment.

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 e.g. C = character - To define a SEARCH field, only specify the NAME operand

THE LOGOCAL DATABASE: Lets say that your program needs to access WORK-HISTORY data for all employees in the EMPLOYEE database:

Heres the logical view of the access path your program will take:

PSB (program specification block) The PSB is made up of one or more PCBs, 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 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 programs. A PSB contains one or more PCBs.

PCB (program communication block) Defines which of the segments in the database the program sensitive to (can access). It is also defines how the application program is allowed to process the segments. This is done via the processing options or PROCOPT.

Valid PROCOPTs include: G for GET (READ) I for INSERT R for REPLACE 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 D for DELETE A for all options (G,I,R,D) L for LOAD (initial load of data) Heres an example of a PSB with only one PCB. It defines a logical data structure the view one program has for the database:
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

DBDNAME tells IMS what DATABASE the program needs access to. The KEYLEN parameter of the PSB is the length in bytes of the longest concatenated key for the segments requested in the PSB. (segment key length may found in the DBD refer to the Module 1 or ask the DBA). SENSEG statements define the name of the segments in the database your program needs access to. PROCOPT defines how the segments may be accessed (G,I,R,D,A,K,L etc.) This PSB will allow your program access to the key only in the root segment EMPDATA. (PROCOPT=K) And READ access to the WORKDATA segment. (PROCOPT=G) The LANG parameter on the PSB statement tells MS what programming language will use the PSB (COBOL, PL/I, Assembler). No other segment in the database may be accessed with the PSB, EMPPSB1

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.

MODULE 3: IMS APPLICATION PRORAMMING Learning Objectives By the end of this module you will be able to List the IMS components required in a COBOL application program. Describe the function of each IMS component. Place each IMS component in the appropriate section of a COBOL application program. Enter and exit IMS.

IMS WORKING STORAGE SECTION FUNCTION CODES is a 4-byte code used to tell DL/I what kind of a call to make. E.g. the function code GN - tells DL/I to get the next segment from its current position in the database You will see how FUNCTION CODEs interact with the other parameters of the DL/I CALL statement in MODULE 5 DL/I RETRIEVAL CALLS. When you access an IMS database with a DL/I call, you will be using these function code: CODE MEANING DESCRIPTION GU Get-unique To obtain a unique occurrence of a segment within a database GN Get-next To obtain the next occurrence of a segment within a database GNP Get-next-within-parent To obtain the next occurrence of a segment under a parent; retrieves child segments under a parent sequentially GHU Get-hold-unique The GET_HOLD function codes are identical to the GET codes GHN Get-hold-next except that they must be used GHNP Get-hold-next-within-parent for retrieval if you intent to ALTER the data are 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, otherwise the replace or delete action will not be successful. After a GET-HOLD call you may issue REPL (to replace an occurrence of a segment in the database and DLET (to delete 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 exist, but this is not necessary. SEGMENT SEARCH ARGUMENT (SSA) your COBOL IMS application program issues DL/I calls to retrieve, insert, delete, or replace (update) database segments. In SSA you can provide: The name of the segment type you want. A description of a specific segment. One or more command codes to qualify your DL/I call even more. INPUT/OUPUT AREA Is a standard record description in the WORKING STORAGE SECTION which holds database segments for manipulation.

It 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. In these cases, the I/O AREA must be large enough to hold the largest concatenation of these segments. To record description for the I/O AREA can be generic and look like this: 01 IO-AREA-GENERIC PIC X(500) VALU SPACES In our EMPLOYEE database, the longest segment is 100 bytes. So the I/O AREA would be redefined. 01 IO-AREA PIC X(100). Sometimes the segment structure definitions are stored in COPYLIB or other source code library membersand look something 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).

IMS LINKAGE SECTION PROGRAM COMMUNICATION BLOCK (PCB MASK) The PCB 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 will access. The 01 level name should be unique for each database. e.g. if your program uses two databases you would code the following: 01 DB-PCB-1 03 03 01 DB-PCB-2 03 03 03

IMS PROCEDURE DIVISION: ENTRY STATEMENT Code the ENTRY statement as the FIRST executable statement in your application program. It must follow immediately after the title PROCEDURE DIVISION. E.g. PROCEDURE DIVIDION. 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 CALL STATEMENT AND STATUS CODE CHECKS: DL/I retrieval calls are covered in detail in MODULE 5. DL/I replace calls are covered in detail in MODULE 6. DL/I insert and delete calls are covered in MODULE 7. 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. And never use STOP RUN

MODULE 4: SEGMENT SEARCH ARGUMENTS Learning Objectives By the end of this module you will be able to Define an SSA Distinguish between a qualified and unqualified SSA. Describe relational operators. Demonstrate the use of command codes.

Segment Search Argument or SSA is an area in WORKING STORAGE used to identify the segment which you require access to. Is 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.

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 fields

Two types of SSA 1. UNQUALIFIED searches for a specific segment type. 2. QUALIFIED searches for a specific occurrence of a specific segment type.

UNQUALIFIED WORKING STORAGE. 01 HISTORY-SSA. 05 SEGMENT-NAME PIC X(9) VALE HISTORY

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. NOTE: the 9th position in the literal must be blank. This blank in the 9th byte indicates 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 EXAMPLE: Assume that your program needs to find out how many employees have worked for the company for more than 10 years. To accomplish this, your program would need to access the WORK-HISTORY data from the EMPLOYEE database. This would require that the data is accessed sequentially using an unqualified SSA. NAME =HISTORY,PARENT=XXXXXXXX,PROCOPT=X

QUALIFIED Now suppose that you wanted to find out some BENEFIT-DATA information for one specific employee. You obviously 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.

Remember that the key and search fields must have been defined in the DBD in the FIELD statement. For this example, it would look something like this: FIELD NAME=(EMPKEY,SEQ,U),BYTES=11,START-

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

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 -

What are some other reasons or using COMMAND CODES? They can save processing time by going directly to the last segment, rather than reading each segment occurrence, and checking in your program if it is the segment occurrence you want. They can reduce the amount of coding necessary in your application program.

MODULE 5: DL/I RETRIEVAL CALLS Learning Objectives By the end of this module you will be able to Write a DL/I call command using the function codes, GU, GN, GNP, to retrieve data segments. Access multiple data segments using PATH calls.

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.

CALL CBLTDLI USING FUNTION-CODE, PCB, IO-AREA, SSA-1, SSA-2 This is a CALL to DL/I with all of the parameters.

FUNTION-CODE - a 4 byte code that tells DL/I what kind of call to make. Ie. Whether the segment is retrieved, replaced, inserted or deleted. Eg. GN is a function code that tells 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 some other source library member. PCB argument tells DL/I which PCB to use for the CALL. Each call may only specify ONE PCB. IO-AREA tells DL/I where to put the segment once it has been retrieved, or where to take it from 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. SSA-1, SSA-2 gives DL/I additional criteria to use in finding a particular segments, 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

FUNCTION CODES: GET UNIQUE <GU> - used to retrieve segments directly. Using the GU function code you can specify the exact segment you wish to retrieve. You may also use GU to establish your position in the database. NOTEE: you should ALWAYS use a QUALIFIED SSA for GU calls. If GU is used without 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.

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. The value of STATUS-CODE will also tell you what, if any, the problem was. So, what values can STATUS-OCDE have? When the DL/I call is successful, STATUS-CODE is set to be blank. If it is unsuccessful, there are number of different codes that is may be set to. One of the most common will be STATUS-CODE = GE, indicating that the segment could not be found. It could also be GB, meaning end-of-database.

GET NEXT <GN> - 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 request. You may use the GN function code with: No SSA A QUALIFIED SSA An UNQUALIFIED SSA

GET NEXT PARENT <GNP> - get next within parent 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. There are two ways: 1. By issuing a successful GU or GN call. 2. By using the P command code <establish parentage> with a GU, GN, or GNP call.

Example:

Using a PATH CALL

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

The D command code indicates to DL/I that we want to retrieve a path of segments into the IO-AREA. The I/O area needs to be as large as the sum of all segments being retrieved in the call. NOTE: The D command code is not required for the last segment in the path.

Ex.

One final point should be made 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.

MODULE 6: UPDATING SEGMENTS Learning Objectives By the end of this module you will be able to Code GET HOLD calls in a COBOL IMS program. Code REPLACE calls. Code COMMAND CODES or REPLACE calls to update a path of segments

In Module 5 we saw how to use three GET functions: GET-UNIQUE GET-NEXT GET-NEXT-WITHIN-PARENT GU GN GNP

These functions can only be used to retrieve for viewing purposes: you can not alter, in any way, the retrieved segments. There are three GET HOLD calls corresponding to each of the GET calls we learned about in Module 5: GHU GET HOLD UNIQUE GHN GET HOLD NEXT GHNP GET HOLD NEXT IN PARENT Once your application program successfully retrieves a segment with a GET-HOLD call, it can replace the segment. QUESTION: can your program successfully issue a replace call if the STATUS-CODE returned to your program by DL/I for the GET-HOLD call is GE <NO> - A STATUS-CODE of GE indicates that the segment was not found in the database. You cannot replace a segment until it has been successfully retrieved.

NOTE: do you remember in Module 1 where we talked about maintaining data integrity as one of the four goals of a database system? The purpose of the GET HOLD calls is to maintain integrity. Do you know how? The GET HOLD calls maintain data integrity by signifying to IMS that your application program intends to update a particular segment. By putting a HOLD on the segment, IMS locks out any other update-intent access by other programs until you have completed our update. 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 CODING 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 or DLET call is done using the same database PCB mask. The order of the call should look like this: GHU REPL GN CALL CBLTDLI USING GHU, EMPLOYEE-PCB, EMP-IOAREA, EMP-SSA - The GET-HOLD call must be followed immediately by the replace call, if it isnt, the HOLD status is lost and another GET-HOLD must be issued before the segment can be replaced. Consider the following: Assume that we want to change an employees ID number because it was added incorrectly by your temporary help. If the ID-NUMBER is the key to the segment any attempt to REPL that segment will be unsuccessful because THE KEY FIELD FOR A SEGMENT CAN NOT BE CHANGED. To correct this error we would need to add a new, correct segment and delete the old incorrect segment.

THE REPL CALL One of your employees, a Jenny Smith, just got married to Albert Jones. You will need to change her last name to SMITH-JONES on the EMPLOYEE segment of your database.

REPL STATUS-CODES: DA- means you tried to change the Key field of the segment. RX means you violated some REPLACE rule. Once 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. Ex.

You 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 gend 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.

Example:

MODULE 7: INSERTING AND DELETING SEGMENT Learning Objectives By the end of this module you will be able to Code INSERT calls to initially load a database Code INSERT calls to add new segments to an existing database. Code DELETE calls to delete one or more segments from a database.

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 vs. INSERT mode You will recall that the PSB defines which segments may be accessed by your program. The PSB also 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: Only two processing options are allowed: L (LOAD) and LS (LOAD SEQUENTIAL). LS is usually preferred as it specifies that segments must be loaded in ascending sequence. L processing option mans 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 database must be loaded sequentially. Access methods will not be discussed in this course.

INSERT mode: Processing options can be: I or IS I mean insert new segments in sequential or random order. IS means 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 FUCTION CODE: The segment to be inserted must first be built in the program IO-AREA. Use SSAs to define the path to DL/I. Using the D COMMAND CODE to insert a path of segments Use an unqualified SSA at segment level(s) where the insertion will occur. New segments added to an existing database are inserted based n the segment KEY field: 1. Segments with a KEY field can be inserted in KEY sequence. 2. Segments with no KEY or non-unique KEY will be inserted according to INSERT rules specified in the DBD.

INSERT RULE options in the DBD FIRST tells DL/I to place the segments FIRST, that is, the first occurrence of this segment type. LAST tells DL/I to place this segment LAST in the twin chain, the last occurrence of this segment type. HERE tells DL/I to place this segment before the current segment occurrence; if current position has not been established, the segment is placed first on the twin chain of segments.

To insert 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)

What does II mean? we tried to insert a segment that already existed in the database. Segment C #3 already was in our database. What other ISRT call status code could we get? GE would tell us that DL/I could not find the path specified by the SSAs in our ISRT call. Remember, always check the STATUS CODE after making DL/I call. When making an ISRT call, check for: - II tried to insert a segment that already exists. - GE could not find the path of segment specified in our SSAs.

Did you notice that we did not make a GET HOLD call before INSERTING a new segment? Instead of issuing GET calls, we define QUALIFIED SSAs for all the parents of the path to the new segment.

DELETING SEGMENTS (DLET) Just like the REPL call, DLET (DELETE CALL) must be preceded by one of the three GET HOLD calls. DL/I will reject the DLET call if the call that preceded it was not a GET HOLD call. Example: 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 1. GU calls to active EMPLOYEE database to retrieve the appropriate data from the various segments in Jennys database record. 2. 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. 3. An ISRT call to the employee HISTORY database inserts a history segment. 4. A DLET call to the active EMPLOYEE database removes Jennys record.

STATUS CODES FOR DLET successful delete of segment or segments specified DA unsuccessful the segment key was changed before DLET was issued. DJ unsuccessful the program did not issue a GET HOLD call before the DLET was issued. DX unsuccessful the program issued a DLET call which violated the delete rule defined for the segment in the DBD.

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

MODULE 8: EFFECTIVE PROGRAMMING TECHNIQUES Learning Objectives By the end of this module you will be able to Know how to handle unexpected IMS status codes. Understand the benefits of using standard error routines. Develop techniques to increase the effectiveness and efficiency of an IMS application program 1. Efficient segment access strategies. 2. Taking checkpoints.

When programming in any language, it is important that you are aware of things 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 1. STATUS CODES: Recall that DL/I give you information about the result of your DL/I CALL in the STATUS CODE field of the DB PCB. You know that your program should check the STATUS CODE after every DL/I call. There are over 100 status codes! But 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, so this is the first thing you should check for after a call. Besides checking each call for SPACES, if you are making a GET call, you may also test for: GA which means DL/I has returned a segment, but that the segment is at a higher level in the hierarchy than the last returned segment. DL/I will only return GA for UNQUALIFIED GET NEXT calls. GB which means that DL/I reached the end of the database and therefore could not return a segment to your program. GE which means DL/I could not find the segment you asked for. This could happen after a GU, GN, or GNP call. GK which means 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).

The DL/I standard error routine should list: The call that was being executed when the error occurred. The SSAs, if any, included in the call. Contents of the PCB, particularly the STATUS CODE and key feedback information. Anything else that would give an audit trail, such as flags and counters.

2. SEGMENT ACCESS: When designing and writing an application, one of your concerns is the efficiency of your code. With a hierarchical database structure, one of the things that can effect efficiently in a significant fashion is how you access segments. Four key area to consider in accessing segments efficiently: 1. ISRT CALLS if you recall the GU <GET-UNIQUE> call, it can be used to check whether a segment you want to INSERT already exist, 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 above the target SSA and does an invisible GU. So, just use ISRT call with appropriate SSAs without a GET call. 2. HIERARCHICAL ACCESS code your DL/I calls in a manner consistent with record and segment relationships. - Know the CURRENT POSITION - Know which segment is the PARENT - Access segments in the database structure (TOP to BOTTOM, LEFT to RIGHT) 3. SEGMENT SEARCH ARGUMENTS 4. SERACH FIELDS

SEGMENT SEARCH ARGUMENTS: Qualified SSAs should be used whenever possible! This cannot be emphasized enough. Qualified SSAs give DL/I more precise information about the segment you want to access. Besides being more efficient, qualifies 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 handled like Unqualified SSAs and, 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 retrieve a segment based on some 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 SEARCH FIELDS 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 defines in the DBD and increase the size of the DBD.

3. CHECKPOINTS 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. Things that happen as a result f 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.

2 Kinds of CHECKPOINT CALLS: 1. BASIC 2. SYMBOLIC The parameters you need for either CHECKPOINT call includes: 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 are you want saved are passed to DL/I as additional parameters on the CHECKPOINT call. 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: 1. Every 15 minutes although this would have potential benefit 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. 2. Every hour this will use less machine time and perhaps maximize time in the event of the ABEND. 3. Every so-many segments - this would need to be discussed with your DBA to determine the optimum number of records. Most Information Systems departments have their own standards for coding checkpoints <CHKP> and restart <XRST> calls.

MODULE 9: COMPILING, EXECUTION, DEBUGGING Learning Objectives By the end of this module you will be able to Compile Execute Test Debug

An IMS application program

COMPILE IMS supplies an interface module (DFSLI000) which must be link-edited to your batch program after your program has been compiled. If you use the IBM-supplied procedure called IMSCOBOL, IMS link edits the language interface with your program. Most installations have TSO panels and CLIST set up to make these additional items transparent to the application programmer. EXECUTE your IMS application program is actually a subroutine which is called by IMS which calls other subroutines in turn. To illustrate: CALL CBLTDLI USING FUNCTION-CODE, PCB-1, OI-AREA, SSA-1. But how is your program a subroutine? there are 2 ways to tell the operating system that you are creating a subroutine: 1. a PROCEDURE DIVISION USING statement 2. An ENTRY USING statement Most installations use the ENTRY statement and when are finished, we use the GOBACK statement. Ex. ENTRY DLITCBL USING PCB-1 ::::::::::::::::::::::::::: ::::::::::::::::::::::::::: ::::::::::::::::::::::::::: ::::::::::::::::::::::::::: GOBACK (returns control to the calling program)

DL/I to COBOL ENTRY DLITCBL USING PCB-1 COBOL to DL/I CALL CBLTDLI

What does the EXECUTE JCL look like? //STEP1 EXEC PGM=DFSRRC00,PARM=(DLI,pgmname,psbname) Where: DFSRRC00 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 name. TEST IBM supplies a testing tool for IMS called DFSDDLT0 DFSDDLT0 DLT0 <as its called for short> is an IMS DL/I test program which executes the DL/I CALLS you specify for a given database. And it can be used to: - Test DL/I calls without executing your application program - INSERT, REPLACE, and DELETE records on a database. - RETRIEVE <DUMP> records from a database - DEBUG an application program. DLT0 the IMS DL/I program that test calls, changes databases and debugs an application program. NOTE: before you use DLT0, you will need a PSB HOW TO USE DLT0: To tell DLT0 the DL/I CALL you want to execute you can use 4 types of control statements: 1. STATUS establishes print options for DLT0s output, and selects the DB PCB. 2. COMMENT 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 4 control statements, there is a DATA statement. The DATA statement provides IMS with segment information for INSERT and REPLACE calls.

Example of DLT0 JCL and control statements:

DEBUG: What kind of errors could you have that may have been caused by something you coded <or failed to code> in DL/I? - An unexpected status code - A program abend - An incorrect segment 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.

For example: If you attempt to retrieve the BENEFIT segment for a specific employee in our employee database, and the BENEFIT segment is not found, but the employee segment id found - The STATUS-CODE will contain GE - The SEG-LEVEL will contain 01 and - The SEGMENT-NAME will contain EMPLOYEE If none of the search criteria were satisfied, the level would be set o 00 and the segment would contain spaces.

Here are 2 more ideas that may help in debugging your program: - The STAT <statistics request> CALL gives you statistics about the number of reads and writes done by your program. If the number is more or less than you expected, you know something is wrong with how your calls are being executed. - DLITRACE is a control card that executes the IMS TRACE program called DFSDLTR0. This program traces and records DL/I calls issued by all types of IMS application programs. It is useful debugging tool because it shows you exactly what DL/I calls your IMS application program made. Errors are easy to spot, because the last call displayed is normally the call that is in error. NOTE: DLITRACE requires a control statement in the DFSVAMP dataset in your execution JCL.