IMS DB Get Unique (GU)

The 'GU' (Get Unique) call is used to retrieve a specific segment from the IMS database based on the criteria provided. It is commonly used to establish a position in the database for subsequent sequential processing or to directly access a particular segment. The 'GU' call can be unqualified (retrieving the first occurrence of a segment type) or qualified (retrieving a segment that matches specific criteria). The syntax of a GU call is as follows −

CALL 'CBLTDLI' USING
    DLI-GU
    DB-PCB
    IO-AREA
    [SSA1]
    [SSA2]
    ...

DLI-GU: A 4-character field with the value 'GU ', indicating the 'Get Unique' function.
DB-PCB: The Program Communication Block for the database, defined in the LINKAGE SECTION. It specifies the database to be accessed and contains status codes and other information after the call.
IO-AREA: The area in the WORKING-STORAGE SECTION where the retrieved segment data will be placed.
SSA1, SSA2, ...: Optional. Defines the segment type and optional qualification criteria for the retrieval.

Return Codes

After executing a 'GU' call, IMS sets a status code in the DB-PCB to indicate the outcome:

Blank (' '): Call was successful; segment retrieved.
GE: Segment not found that satisfies the SSA; no segment retrieved.

Example

Scenario - This program will retrieve a specific employee record based on a unique key by navigating through the Company → Project → Employee hierarchy.

Hierarchical Structure -

COMPANY       ← root segment  
 └─ PROJECT    ← child of COMPANY  
      └─ EMPLOYEE   ← child of PROJECT

Program -

IDENTIFICATION DIVISION.
PROGRAM-ID. GET-UNIQUE-EMPLOYEE.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.

DATA DIVISION.
WORKING-STORAGE SECTION.

* DL/I FUNCTION CODE
01 DL-I-FUNCTIONS.
   05 DLI-GU        PIC X(4) VALUE 'GU  '.

* I/O AREA TO RECEIVE SEGMENT DATA
01 IO-AREA.
   05 COMPANY-ID             PIC X(5).
   05 COMPANY-NAME           PIC X(30).
   05 PROJECT-ID             PIC X(5).
   05 PROJECT-NAME           PIC X(30).
   05 EMPLOYEE-ID            PIC X(5).
   05 EMPLOYEE-NAME          PIC X(25).

* SSA STRINGS (SEGMENT SEARCH ARGUMENTS)
01 SSA-STRINGS.
   05 SSA-COMPANY            PIC X(30) VALUE SPACES.
   05 SSA-PROJECT            PIC X(30) VALUE SPACES.
   05 SSA-EMPLOYEE           PIC X(30) VALUE SPACES.

LINKAGE SECTION.
* PCB MASK PROVIDED BY IMS
01 EMPLOYEE-PCB.
   05 DBD-NAME               PIC X(8).
   05 SEG-LEVEL              PIC XX.
   05 STATUS-CODE            PIC XX.
   05 PROC-OPTIONS           PIC X(4).
   05 FILLER                 PIC X(4).
   05 SEGMENT-NAME-FB        PIC X(8).
   05 LENGTH-KEY-FB          PIC S9(5) COMP.
   05 NUM-SENS-SEGS          PIC S9(5) COMP.
   05 KEY-FEEDBACK-AREA      PIC X(50).


PROCEDURE DIVISION.

    DISPLAY "=== START IMS DB GU CALL ===".

    * Prepare Qualified SSA strings
    MOVE 'COMPANY(COMPANY-ID =C001)' TO SSA-COMPANY.
    MOVE 'PROJECT(PROJECT-ID =P001)' TO SSA-PROJECT.
    MOVE 'EMPLOYEE(EMPLOYEE-ID=E001)' TO SSA-EMPLOYEE.

    * Issue GU (Get Unique) DL/I call
    CALL 'CBLTDLI' USING DLI-GU,
                         EMPLOYEE-PCB,
                         IO-AREA,
                         SSA-COMPANY,
                         SSA-PROJECT,
                         SSA-EMPLOYEE.

    * Check STATUS-CODE returned in PCB mask
    IF STATUS-CODE = '  '
        DISPLAY "=== EMPLOYEE RECORD FOUND ==="
        DISPLAY "COMPANY ID    : " COMPANY-ID
        DISPLAY "COMPANY NAME  : " COMPANY-NAME
        DISPLAY "PROJECT ID    : " PROJECT-ID
        DISPLAY "PROJECT NAME  : " PROJECT-NAME
        DISPLAY "EMPLOYEE ID   : " EMPLOYEE-ID
        DISPLAY "EMPLOYEE NAME : " EMPLOYEE-NAME
    ELSE
        DISPLAY "!!! FAILED TO RETRIEVE RECORD"
        DISPLAY "STATUS CODE: " STATUS-CODE
    END-IF.

    DISPLAY "=== END OF PROGRAM ===".
    GOBACK.

Sample Output

=== START IMS DB GU CALL ===
=== EMPLOYEE RECORD FOUND ===
COMPANY ID    : C001
COMPANY NAME  : TECHCORP
PROJECT ID    : P001
PROJECT NAME  : AI SYSTEMS
EMPLOYEE ID   : E001
EMPLOYEE NAME : JOHN DOE
=== END OF PROGRAM ===