Accessing IMS Databases

Unit 2

Copyright IBM Corporation 2008 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.

5.1

Objectives
Identify the context for and the major parts of an IMS database application program Learn the elements of an IMS database call Learn how SSAs and command codes are used in database calls to determine which segments are acted upon Demonstrate or simulate the four IMS database call functions Review the capability of the IMS Test Program (DFSDDLT0)

Copyright IBM Corporation 2008

DL/I Processing
z/OS

APPLICATION PROGRAM

INPUT / OUTPUT

CALL

DATA

DL/I

DATA BASE

LOG

Copyright IBM Corporation 2008

Application Program Structure (1 of 2)

I/O AREA SEGMENT (S) TO/FROM DATA BASE PCB AREA RETURN INFO FROM DL/I PROGRAM-AREA PROGRAM ENTRY CALLS TO DL/I
(GET INSERT REPLACE DELETE)

PROCESSING TERMINATION

DL/I MODULES
Copyright IBM Corporation 2008

DL/I AREA

Application Program Structure (2 of 2)

Application Program Entry Function (Get, Insert, Replace, Delete) Segment Search Arguments (SSAs):
Segment Name Key for Search Boolean Operators and/or Logic Command Codes
For example, "Path" Calls

Input/Output Area in Application Program Program Communication Block (PCB) contains:

Database Name Area to Return Information to Application Program

Termination

Copyright IBM Corporation 2008

Application Program Entry Point

COBOL
PROCEDURE DIVISION USING DB-PCB1, DB-PCB2. OR:

ENTRY 'DLITCBL 'USING DB-PCB1, DB-PCB2,

PL/I
OR:

DLITPLI: PROC (DB_PCB1, DB_PCB2) OPTIONS (MAIN); DCL DLITPLI ENTRY, DB_PCB1 POINTER, DB_PCB2 POINTER;

ASSEMBLER
Standard convention: Upon entry, register 1 points to a parameter list of PCB pointers Example
CSECT L USING L USING 9,0 (1) PCB1, 9 7, 4 (1) PCB2, 7 LOAD PCB1 ADDRESS LOAD PCB2 ADDRESS

Copyright IBM Corporation 2008

Program Communication Block (PCB)

Generated by PSB Utility Mask Written in COBOL

SIZE

FUNCTION
01 DB-PCB1. 02 DBD-NAME 02 SEG-LEVEL 02 STATUS-CODE 02 PROC-OPTIONS 02 RESERVE-DLI 02 SEG-NAME-FB 02 LENGTH-FB-KEY 02 NUM-SENS-SEGS 02 KEY-FB-AREA. 03 SKILL-KEY 03 NAME-KEY 03 EXPR-KEY

8 2 2 4 4 8 4 4

NAME OF DATABASE SEGMENT HIERARCHY LEVEL DL/I STATUS CODE DL/I PROCESSING OPTIONS RESERVED FOR DL/I SEGMENT NAME FEEDBACK LENGTH OF FEEDBACK KEY NUMBER OF SENSEGS

PIC PIC PIC PIC PIC PIC PIC PIC

X(8). XX. XX. XXXX. S9(5) COMP. X(8). S9(5) COMP. S9(5) COMP.

KEY FEEDBACK AREA

PIC X(4). PIC X(5). PIC X(3).

Copyright IBM Corporation 2008

DL/I Call Parameters

CALL 'CBLTDLI' (COBOL) 'PLITDLI' (PL/I) 'ASMTDLI' (Assembler) 'PASTDLI' (PASCAL) 'CTDLI' ("C"/370)

COUNT

NUMBER OF PARAMETERS GET INSERT DELETE REPLACE FEEDBACK CONTROL BLOCK

(REQUIRED for PL/I)

FUNCTION

PCB

DATABASE NAME
I/O-AREA SSA (s) (OPTIONAL, 0-15) SEGMENT SEGMENT SEARCH ARGUMENTS
Copyright IBM Corporation 2008

QUALIFIES SEGMENT (s) REQUESTED

DL/I Function Codes

FUNCTION GET SEGMENTS: GET UNIQUE GET NEXT GET NEXT WITHIN PARENT
GET SEGMENT for DELETE or UPDATE: GET HOLD UNIQUE GET HOLD NEXT GET HOLD NEXT WITHIN PARENT DELETING: DELETE UPDATING: REPLACE ADDING: INSERT
Copyright IBM Corporation 2008

CODE
GUbb GNbb GNPb

GHUb GHNb GHNP

DLET

REPL

ISRT

DL/I Interface
CALL 'CBLTDLI' USING GN, EDPCB, COURSE-SEG. FUNCTION CODE "WHAT"?

ADDRESS OF PCB "WHICH"?

PROGRAM WORKING-STORAGE "WHERE"? CALL PLITDLI (THREE, GU, EDPCB, COURSE_SEG);

Copyright IBM Corporation 2008

AIB Application Interface Block

Most DL/I (DB and DC) calls can be issued in two ways:
Call 'CBLTDLI' using GU, PCB, IO-AREA... or Call 'AIBTDLI' using GU, AIB, IO-AREA...

With the AIB call,

PSBGEN may optionally assign a name to a PCB
Application can reference by name rather than address

Can be used to access more system-related information

The Inquiry (INQY) call is used to request information regarding execution environment, destination type and status, and session status.
Copyright IBM Corporation 2008

Identifying Required Segments

COURSE segment layout -- the DB view
Course Code Course Description Course Length Course Price

COURSCDE

COURSDES

COURSLEN

COURSPRC

A COURSE segment occurrence -- the application view

U3700 IMS Fundamentals 003 750.00

Copyright IBM Corporation 2008

Segment Search Arguments (SSAs)

SSAs may be used to "qualify" a call in two ways
Unqualified SSA to identify only the segment type
Segment Name 8 b 1

Example: get all course segments within a database

GN COURSEbb

Qualified SSA identifies specific occurrences of segments

Segment Name ( Field Name Rel Operator Comparative Value 2 1-255 )

Example: get the course segment with key U3700

GU COURSEbb(COURSCDEb=U3700)
Copyright IBM Corporation 2008

DL/I Control-Block Relationships

// EXEC // IMS // PGM=DFSRRC00,PARM='DLI, ANYPROG,EDUCPSB,...' DD DSNAME=IMS.DBDLIB,DISP=SHR DD DSNAME=IMS.PSBLIB,DISP=SHR

PSBGEN DBDGEN DBD L I B

PSBLIB

EDUCPSB PCB DBDNAME= . . . EDUCDBD ...

EDUCDBD DATASET DD1=EDDATA ...

... //EDDATA ...

DD

DSN=HDAM.EDUCDATA,DISP=SHR

HDAM. EDUCDATA

// EXEC PGM=IDCAMS DELETE CLUSTER (NAME (HDAM.EDUCDATA) ... DEFINE CLUSTER (NAME (HDAM.EDUCDATA) -

Copyright IBM Corporation 2008

z/OS Access Methods

z/OS
VSAM OSAM

Transferring data to a program

z/OS Address-space:
DATABASE DATA SET

DL/I Action Modules

DL/I BUFFER

COURSE

CLASS ... CLASS ... ...

CLASS

I/O-AREA

CLASS

INSTRUCT

CLASS
STUDENT

DL/I Program

Copyright IBM Corporation 2008

Retrieving Data
z/OS Address-space
Application Program: ... ...
GU COURSE U3700 C LASS SF980814 . . . . . . . . . . . . . . . . . . INPUT/OUTPUT AREA: CLASS SF980814 COURSE U3700 CLASS SF980814 COURSE U3702 CLASS SF980814 WY980905

INSTRUCT MBA

INSTRUCT MBA EXPR

STUDENT SEQ01

STUDENT SEQ01

CLASS SF980814 WS981215 INSTRUCT

STUDENT

Copyright IBM Corporation 2008

GU and GHU
Used to retrieve a specific segment occurrence independent of the current position within the database Qualified SSAs identifying each hierarchic level are normally provided

A GET-UNIQUE Call with missing levels of qualification uses current control block information for missing levels. If none exist, unqualified SSAs are assumed for the missing levels.
A GET-UNIQUE call always returns the first segment in the data base that satisfies the qualification

STATUS-CODES
GE bb Segment not found Successful CALL
Copyright IBM Corporation 2008

Database Record (DBR)

COURSE
1 COURSE U3700 2 NAME ADAMS 3

Hierarchic Format
1

U3700

EXPR CB3

Indented Format
4

NAME

NAME JONES 5 EXPR AL5

ADAMS
6

JONES 8 SMITH
7

EXPR CB4

EDUC MBA 8

EXPR

EDUC

NAME SMITH 9

3 5

CB3 AL5 6 9 CB4 PL3

Copyright IBM Corporation 2008

EXPR PL3

MBA
10

10

BBA

EDUC BBA

GET UNIQUE Examples

Call 1 2 Cur SSA(s) in Call Pos COURSEbb(CODE=U3700) COURSEbb(CODE=U3700) NAMEbbbb(LASTNM=JONE S) COURSEbb(CODE=U3700) NAMEbbbb(LASTNM=JONE S) EDUCbbbb(DEGREE=MBA) COURSE(U3700 ) NAME(JONES) COURSE(U3700 ) COURSE(U3700 ) COURSE(U3700 ) NAME(JONES) Implied SSAs Segm Retr 1 4 Stat Code bb
4 NAME JONES

1
COURSE U3700

2 NAME ADAMS 3
EXPR CB3

bb

5 EXPR AL5

3A

bb
7

EXPR CB4

EDUC MBA
8 NAME SMITH

3B

EXPRbbbb(CLASSIF=AL5)

bb

9 EXPR PL3

3C 4A 4B

NAMEbbbb EXPRbbbb(CLASSIF=CB3) None

10

3 1 6

bb bb bb
COURSE U3700

EDUC BBA

EXPRbbbb(CLASSIF=CB4)

NAME

ADAMS 4 JONES 8 SMITH

4C

EXPRbbbb(CLASSIF=PL3)

GE

EXPR

EDUC

CB3 5 AL5 6 9 CB4 PL3 MBA 10 BBA

4D

COURSEbb(CODE=U3700) NAME(JONES) EDUCbbbb(DEGREE=MBA)

bb

Copyright IBM Corporation 2008

GN and GHN
Used to sequentially process segments in a database, or start sequential processing on a portion of it Always proceeds forward from current position within the database A GN Call with no SSAs returns the next segment in the database A GN Call with an unqualified SSA returns the next occurrence of that segment type A GN Call with a qualified SSA returns the next occurrence of the specified segment type which meets the search criteria Unqualified SSAs are supplied for missing levels STATUS-CODES
Unqualified Calls Only
'GA' - Crossed hierarchic boundary to higher level 'GK' - Different segment type at the same level

'GB' - End of Database reached 'GE' - Segment not found 'bb' - Successful call

Copyright IBM Corporation 2008

GNP or GHNP?
Works just like GN except only under established parent. Parent set by successful GN or GU call. Status codes
same as GN

Copyright IBM Corporation 2008

GET NEXT Examples

Call Current Position SSA(s) in call Segm Status Retr Code 1 2 3 4 5 6 7 8 9 10 1 bb bb bb GA bb bb GK GA bb GK GB bb bb bb bb GB bb GB
1
COURSE U3700

2 NAME ADAMS 3
EXPR CB3

1A B C D E F G H I J K L 2A B C D 3A B

4 NAME JONES

1 2 3 4 5 6 7 8 9 10 (WRAP)

5 EXPR AL5

6 EXPR CB4

7 EDUC MBA
8 NAME SMITH

9 EXPR PL3

10

2 4 8 1 8

NAME NAME NAME NAME

NAMEbbbb(LASTNM=SMITH) NAMEbbbb(LASTNM=JONES) COURSEbb(CODE=3700) NAMEbbbb(LASTNM=JONES) EXPRbbbb(CLASSIF=PL5)

2 4 8 8 -

EDUC BBA

COURSE U3700

NAME

ADAMS 4 JONES 8 SMITH

EXPR

EDUC

GE

3 5

CB3 AL5 6 9 CB4 PL3 MBA 10 BBA

Copyright IBM Corporation 2008

Replacing Data (REPL)

z/OS Address-space: Application Program: . . . . . .
GHU COURSE U3700 CLASS WS911215 . . . MOVE 'NEW DATA' TO IO-AREA . . . REPL . . . INPUT/OUTPUT AREA: WS911215 COURSE (U3700)

CLASS WS911215 CLASS SF910814 INSTRUCT AAS INSTRUCT MBA STUDENT SEQ01 STUDENT SEQ05

1. 2. 3.

Class WS911215 segment moved to i/o-area Changes are made to data in i/o-area Updated segment replaced in database
Copyright IBM Corporation 2008

Deleting Data (DLET)

z/OS Address-space:
COURSE (U3702)

Application Program: . . . . . .
GHU COURSE U3702 . . . . . . . . . . . . DLET . . . . . . . . . INPUT/OUTPUT AREA: COURSE (U3700)

CLASS NY980905

CLASS WS981215 CLASS SF980814

INSTRUCT BBA

STUDENT SEQ05

INSTRUCT AAS

STUDENT SEQ05

U3702
INSTRUCT MBA STUDENT SEQ01

1. 2. 3.

Course (U3702) segment moved to i/o-area Segment and its dependents are eliminated What is in database after deletion?
Copyright IBM Corporation 2008

Inserting Data (ISRT)

New segment data built in i/o-area Class (SL981015) segment added to database
z/OS Address-space: Application Program: . . .
MOVE 'NEW DATA' TO I/0-AREA . . . . . . ISRT COURSE U3700 CLASS . . . . . . . . . INPUT/OUTPUT AREA:

COURSE (U3700) CLASS WS981215 CLASS SL981015 CLASS SF980814 INSTRUCT AAS STUDENT SEQ05

SL981015

INSTRUCT MBA

STUDENT SEQ01

Copyright IBM Corporation 2008

CHKP Checkpoint and XRST Extended Restart

CHKP - CHECKPOINT
Commit updates Free database locks Save working storage (optional) CALL 'CBLTDLI' using CHKP, IOPCB,...

XRST - EXTENDED RESTART

Repositions Databases - including GSAM Recover working storage (optional)

Call 'CBLTDLI' using XRST, IOPCB,...

Copyright IBM Corporation 2008

Application Program Recovery/Restart

RESTART LOGIC DATA AREAS FUNCTION CODES I/O-AREAS WORK AREA LIST OF USER-DEFINED AREAS PROGRAM LOGIC ENTRY CALL 'XRST' // EXEC.....PARM='...
CHKPT-ID DATE/TIME

CHKPT-ID IN WORK AREA

NO

CHKPT-ID IN PARM FIELD

NO

YES
RESTART PROCESSING

YES

PROCESS

CALL 'CHKP' TERMINATION

CONTINUE NORMAL PROCESSING

Copyright IBM Corporation 2008

Multiple IMS Batch Address Spaces

z/OS
IMS/BATCH Address Space IMS/BATCH Address Space IMS/BATCH Address Space

Application

Application

Application

DL/I Modules

DL/I Modules

DL/I Modules

Data Buffers

Data Buffers

Data Buffers

Database (A)

System Log

Database (B)

System Log

Database (C)

System Log

Copyright IBM Corporation 2008

DL/I Test Program

z/OS Module 'DFSDDLT0' is provided

DL/I CONTROLLER (DFSRRC00)

BLOCK LOADING AND BUILDING

SYSTEM LIBRARY

DBD PSB DL/I TEST PROGRAM 'DFSDDLT0'

VSAM CLUSTER

Copyright IBM Corporation 2008

DL/I Test Program Input

//DLT0 EXEC PGM=DFSRRC00,PARM='DLI,DFSDDLT0,PSBCOBOL, , , , , , , , ,N,N,' //STEPLIB DD DSN=IMS820.SDFSRESL,DISP=SHR //IMS DD DSN=C25.U3700.PSBLIB,DISP=SHR // DD DSN=C25.U3700.DBDLIB,DISP=SHR //PRINTDD DD SYSOUT= //SYSPRINT DD SYSOUT= //SKILL DD DSN=C25.U3700T16.SKILL,DISP=SHR //SYSIN DD * S 1 1 1 1 1 SKILL 2 UXXXXXXXXXXXXX TEST STATEMENT 1 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX L GU SKILL (SKCLASS = BU115 ) NAME (FULNAM = AKERSON, LAWRENCE R. X CONT ) X

EH L /*

OK 0006 GNP

. . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IMS 10.1 TEST PROGRAM OUTPUT XX BEGIN TEST XX TIME= 10.57.08.93 DATE=04.081

Copyright IBM Corporation 2008

DL/I Test Program Output

0002 0F 0003 PCB SELECTED = DBD SELECTED = SKILL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALL=GU SEG=SKILL FIELD=SKClASS OPER== VALUE=BU115 ) SEG=NAME FlELD=FULNAM OPER== VALUE=AKERSON, LAWRENCE R.

) COMP RET CODE=OK DBPCB LEV=02 SEG=NAME RET CODE= KFDB LEN=05 KEY FDB=BU115 AKERSON, LAWRENCE R. COMMENTS TIME=10.57.09.49 DATE=04.081 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALL=GNP SEGMENT = (05A100-30436 1000) COMP RET CODE=OK DBPCB LEV=03 SEG=EXPR RET CODE= KFDB LEN=0054 KEY FDBK= (BU115 AKERSON, LAWRENCE R. 1000) CALL=GNP SEGMENT = (06A200-10242 2000) COMP RET CODE=OK DBPCB LEV=03 SEG=EXPR RET CODE= KFDB LEN=0054 KEY FDBK= (BU115 AKERSON, LAWRENCE R. 2000) . . . . . . STATISTICS FOR DATA BASE CALLS: GU GN GNP GHU GHN GHNP ISRT DLET REPL TOTAL DL/I COUNTS BY CALL1 0 6 0 0 0 0 0 0 7 TOTAL NUMBER OF CALLS = 7 TOTAL NUMBER EQUAL COMPARES = 0 TOTAL NUMBER UNEQUAL COMPARES = PSB= PSBCOBOL PCB= DBD= SKILL STOP TIME= 10.57.10.27 DATE= 04.081

SEGMENT

= (AKERSON, LAWRENCE R. (

Copyright IBM Corporation 2008

Unit Summary
I/O areas, PCB areas, entry points, calls and a process termination are the major parts of an IMS program executing in an IMS region IMS calls consist of an interface, functions, I/O areas, PCBs and optionally SSAs with command codes. SSAs with optional command codes are used to determine which segments are acted upon The Get, Insert, Update and Delete database functions were demonstrated IMS Test Program (DFSDDLT0) was introduced.

Copyright IBM Corporation 2008