IMS DB Get Hold Unique (GHU)

The 'GHU' (Get Hold Unique) call is a DL/I function used to retrieve a specific segment (like GU) from the database and place a hold (lock) on it for update (REPL) or delete (DLET). This hold ensures that the segment remains locked, preventing other processes from modifying it until the hold is released. In a COBOL program, the 'GHU' call is made using the following syntax:

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

DLI-GHU: A 4-character field with the value 'GHU ', indicating the 'Get Hold 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 'GHU' call, IMS sets a status code in the DB-PCB to indicate the outcome:

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

Example

Scenario - Below is a simplified example of a COBOL program that uses the 'GHU' call to retrieve and update a specific 'EMPLOYEE' segment from an IMS database:

Hierarchical Structure -

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

Program -

IDENTIFICATION DIVISION.
PROGRAM-ID. GHUEXAMP.

DATA DIVISION.
WORKING-STORAGE SECTION.

* DL/I FUNCTION CODES
01 DL-I-CODES.
   05 DLI-GHU     PIC X(4) VALUE 'GHU '.
   05 DLI-REPL    PIC X(4) VALUE 'REPL'.

* I/O AREA FOR 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
01 SSA-AREA.
   05 SSA-COMPANY         PIC X(30) VALUE 'COMPANY(COMPANY-ID =C001)'.
   05 SSA-PROJECT         PIC X(30) VALUE 'PROJECT(PROJECT-ID =P001)'.
   05 SSA-EMPLOYEE        PIC X(35) VALUE 'EMPLOYEE(EMPLOYEE-ID=E001)'.
   
LINKAGE SECTION.
* PCB MASK
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-SENSITIVES      PIC S9(5) COMP.
   05 KEY-FEEDBACK        PIC X(50).

PROCEDURE DIVISION.

    DISPLAY "=== BEGIN: GHU EMPLOYEE ===".

    * STEP 1: Use GHU to lock a specific EMPLOYEE
    CALL 'CBLTDLI' USING DLI-GHU,
                         EMPLOYEE-PCB,
                         IO-AREA,
                         SSA-COMPANY,
                         SSA-PROJECT,
                         SSA-EMPLOYEE.

    IF STATUS-CODE = '  '
        DISPLAY "EMPLOYEE LOCKED FOR UPDATE:"
        DISPLAY "EMPLOYEE ID   : " EMPLOYEE-ID
        DISPLAY "EMPLOYEE NAME : " EMPLOYEE-NAME

        * STEP 2: MODIFY the employee name in the I/O AREA
        MOVE "JOHN M" TO EMPLOYEE-NAME

        * STEP 3: Use REPL to update the locked record
        CALL 'CBLTDLI' USING DLI-REPL,
                             EMPLOYEE-PCB,
                             IO-AREA

        IF STATUS-CODE = '  '
            DISPLAY "EMPLOYEE NAME UPDATED SUCCESSFULLY"
        ELSE
            DISPLAY "** UPDATE FAILED. STATUS = " STATUS-CODE
        END-IF
    ELSE
        DISPLAY "** EMPLOYEE NOT FOUND. STATUS = " STATUS-CODE
    END-IF.

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

Sample Output

=== BEGIN: GHU EMPLOYEE ===
EMPLOYEE LOCKED FOR UPDATE:
EMPLOYEE ID   : E001
EMPLOYEE NAME : JOHN DOE
EMPLOYEE NAME UPDATED SUCCESSFULLY
=== END OF PROGRAM ===