IMS- DL/I Calls

DL/I calls are the only way an application program reads or updates IMS data. Every call is a COBOL CALL 'CBLTDLI' with a 4-character function code, a PCB mask, an I/O area, and optional Segment Search Arguments (SSAs). This module shows each major call with real, runnable COBOL.

The DL/I call format

• CALL 'CBLTDLI' USING function-code, pcb-mask, io-area, ssa-1, ... ssa-n. CBLTDLI is the IMS language interface module for COBOL (assembler uses DFSLI000/ASMTDLI).
• The function code is PIC X(4): 'GU ', 'GN ', 'ISRT', 'REPL', 'DLET', and so on. Pad to 4 characters.
• The PCB mask is a LINKAGE SECTION structure describing the PCB; IMS fills in the status code after every call.
• SSAs are the search criteria, one per hierarchy level, top-down. A call can have from 0 to 15 SSAs.

DL/I function codes

• GU (Get Unique): fetch one segment directly, using a qualified SSA with a key.
• GN (Get Next): fetch the next segment in hierarchical sequence; the workhorse of sequential processing.
• GNP (Get Next in Parent): like GN but stays inside the currently established parent.
• GHU / GHN / GHNP (Get Hold Unique / Next / Next in Parent): like GU/GN/GNP but lock the segment so REPL or DLET can follow.
• ISRT (Insert): insert a new segment occurrence. SSA is unqualified at the level being inserted.
• REPL (Replace): update the segment retrieved by the last Get Hold call. The key field cannot be changed.
• DLET (Delete): delete the segment retrieved by the last Get Hold call, honoring delete rules.
• CHKP / XRST: checkpoint and restart for BMP programs (see Module 6).
• ROLL / ROLS: back out database changes to the last commit point (online/batch).

The PCB mask (LINKAGE SECTION)

• Every DL/I program declares the PCB mask in LINKAGE SECTION and names it in PROCEDURE DIVISION USING. IMS fills STATUS-CODE after each call - always check it.

SSA formats and command codes

• Unqualified SSA: just the segment name, e.g. 'COURSE'. Used for sequential reads and inserts.
• Qualified SSA: name plus a Boolean condition, e.g. 'STUDENT(STUDID = S1001)'. Operators: =, >=, <=, >, <, not =. (Shown here escaped; code them with the real symbols.)
• Command codes follow the segment name after an asterisk: F = first occurrence, L = last occurrence, D = path call, P = set parentage, U = hold position at this level, Q = enqueue the segment exclusively.
• Example with parentage: 'STUDENT(STUDID = S1001)*P' positions on the parent so following GNP calls stay inside it.

Example 1: GU - get one segment by key

Example 2: GN loop - read all COURSE twins of one student

• The *P command code sets parentage on STUDENT, so the GN calls walk only that student's COURSE twins.
• Two SSAs are passed on the GN: one per level, top-down. The loop ends when GN returns GB.

Example 3: ISRT, REPL and DLET

• REPL and DLET take no SSA; they act on the segment held by the preceding GHU/GHN/GHNP.
• REPL cannot change the sequence (key) field; to change a key, delete and re-insert the segment.
• DLET honors the segment's delete rule: with PHYSICAL, dependents are deleted as well.

Key status codes to memorize

• ' ' (two blanks): call succeeded. Always compare against blanks, not zeros.
• GE: GU did not find the segment described by the SSA.
• GB: end of database reached on GN/GNP.
• GA / GC: the call crossed a hierarchical boundary; the requested level was not found.
• II: ISRT violated an insert rule, usually a duplicate unique key.
• DA: REPL tried to change the key field - not allowed.
• DJ: REPL/DLET issued without a prior Get Hold call.
• DX: DLET blocked because dependents exist and delete rules forbid it.
• LB: segment is enqueued (locked) by another program.
• QC: no more input messages (GU to the IO-PCB in an MPP).
• AB / AD / AJ / AC: call rejected - processing options, bad function code, bad parameter list, bad SSA.