IMS DL/I Calls: GU, GN, GNP Retrieval Commands

DL/I calls are the programming interface to IMS databases. Unlike SQL, which is declarative ("give me data matching these conditions"), DL/I is procedural — the programmer explicitly navigates the hierarchy one call at a time. The three retrieval calls — GU, GN, and GNP — are the foundation of every IMS program.

The CALL 'CBLTDLI' Syntax

Every DL/I call in COBOL uses the same basic structure:

cobol

CALL 'CBLTDLI' USING function-code
                     pcb-mask
                     io-area
                     [ssa-1]
                     [ssa-2]
                     ...

function-code: A PIC X(4) variable set to 'GU ', 'GN ', 'GNP ', 'ISRT', etc.
pcb-mask: The PCB structure defined in the LINKAGE SECTION
io-area: The working storage area where IMS places the retrieved segment
ssa-1...: Optional Segment Search Arguments that qualify the call

Always check the PCB status code after every call — blank means success, GE means not found, GB means end of database.

GU — Get Unique

GU retrieves a specific segment occurrence, using SSAs to identify exactly which segment you want. GU also re-establishes IMS position — it starts fresh, ignoring any previous position in the database.

GU to get a specific customer:

cobol

WORKING-STORAGE SECTION.
01 DLI-FUNCTIONS.
   05 GU-FUNC   PIC X(4) VALUE 'GU  '.
   05 GN-FUNC   PIC X(4) VALUE 'GN  '.
   05 GNP-FUNC  PIC X(4) VALUE 'GNP '.

01 CUSTOMER-SSA.
   05 FILLER    PIC X(9)  VALUE 'CUSTOMER('.
   05 FILLER    PIC X(8)  VALUE 'CUST-KEY'.
   05 FILLER    PIC X(2)  VALUE ' ='.
   05 SSA-CUST  PIC X(10).
   05 FILLER    PIC X(1)  VALUE ')'.

PROCEDURE DIVISION USING CUSTOMER-PCB.

    MOVE '1001000001' TO SSA-CUST.
    CALL 'CBLTDLI' USING GU-FUNC
                         CUSTOMER-PCB
                         CUSTOMER-IO-AREA
                         CUSTOMER-SSA.
    IF PCB-STATUS-CODE = '  '
       PERFORM PROCESS-CUSTOMER
    ELSE IF PCB-STATUS-CODE = 'GE'
       PERFORM CUSTOMER-NOT-FOUND
    ELSE
       PERFORM IMS-ERROR-ROUTINE.

GU positions the database at the retrieved segment. Subsequent GN calls will start from this position.

GN — Get Next

GN retrieves the next segment occurrence in hierarchical sequence, starting from the current position. GN moves forward through the database — it never goes backward.

GN to sequentially read all customers:

cobol

PERFORM UNTIL DONE
    CALL 'CBLTDLI' USING GN-FUNC
                         CUSTOMER-PCB
                         CUSTOMER-IO-AREA
                         CUSTOMER-UNQUAL-SSA
    EVALUATE PCB-STATUS-CODE
        WHEN '  '
            PERFORM PROCESS-CUSTOMER
        WHEN 'GB'
            MOVE 'Y' TO DONE-FLAG
        WHEN OTHER
            PERFORM IMS-ERROR-ROUTINE
    END-EVALUATE
END-PERFORM.

An unqualified SSA ('CUSTOMER ' with no parentheses) tells IMS to return any CUSTOMER segment — just the next one in sequence.

GN with a qualified SSA limits the next segment to those matching the qualification — GN stops (status code GE) when no more qualifying segments exist.

GNP — Get Next within Parent

GNP is like GN but restricted to segments under the current parent. Once all children under the current parent are exhausted, GNP returns GE — it does not cross to the next parent.

Pattern to read all accounts under a specific customer:

cobol

* First, position at the customer with GU
    MOVE '1001000001' TO SSA-CUST-KEY.
    CALL 'CBLTDLI' USING GU-FUNC
                         CUSTOMER-PCB
                         CUSTOMER-IO-AREA
                         CUSTOMER-QUAL-SSA.

* Now read all accounts under this customer
    PERFORM UNTIL NO-MORE-ACCOUNTS
        CALL 'CBLTDLI' USING GNP-FUNC
                             CUSTOMER-PCB
                             ACCOUNT-IO-AREA
                             ACCOUNT-UNQUAL-SSA
        EVALUATE PCB-STATUS-CODE
            WHEN '  '
                PERFORM PROCESS-ACCOUNT
            WHEN 'GE'
                MOVE 'Y' TO NO-MORE-ACCOUNTS
            WHEN OTHER
                PERFORM IMS-ERROR-ROUTINE
        END-EVALUATE
    END-PERFORM.

This is the canonical IMS pattern for processing all children of a parent — GU to position at the parent, then GNP loop for the children.

Key Status Codes for Retrieval

Status Code	Meaning	Action
(blank)	Successful retrieval	Process the data
`GE`	Segment not found (qualification not met)	End of search or not found
`GB`	End of database (GN hit the last segment)	Stop sequential processing
`GP`	Segment not found within parent (GNP)	All children processed
`AC`	Segment not sensitive to this PCB	Programming error — check PSB
`AJ`	Field not defined in SSA	Programming error — check SSA field name

Frequently Asked Questions

Q: What is the difference between GE and GB? GE (Get Error) means the specific qualified segment you searched for does not exist. GB (Get Blank/End) means you have reached the physical end of the database during a sequential GN scan. GE from a GNP means there are no more qualifying children under the current parent. GB only occurs with GN and only when the entire database is exhausted.

Q: Can GU retrieve a dependent segment directly without retrieving its parent first? Yes — a GU call can include SSAs for the full path from root to the target dependent segment. IMS uses the SSAs to navigate directly to the target. For example, to GU directly to a specific TRANSACTION, include qualified SSAs for CUSTOMER, ACCOUNT, and TRANSACT. IMS positions at the specified transaction without your program explicitly reading the parent segments.

Q: What does an unqualified SSA look like in COBOL? An unqualified SSA is simply the 9-character segment name padded with a space:

cobol

01 CUSTOMER-UNQUAL-SSA PIC X(9) VALUE 'CUSTOMER '.

No parentheses, no field qualification. It tells IMS to return the next occurrence of that segment type, regardless of content.

Part of the IMS Mastery Course — Module 10 of 22.