IMS DB Get Hold Next (GHN)

The 'GHN' (Get Hold Next) call is a DL/I function used to retrieve the next segment in the database sequence (just like GN) and place a hold (lock) on it for future 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 'GHN' call is made using the following syntax:

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

DLI-GHN: 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 'GHN' 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.
GB: End of database reached; no more segments to retrieve.

Example

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

Hierarchical Structure -

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

Program -

IDENTIFICATION DIVISION.
PROGRAM-ID. GHNEXAMP.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.

DATA DIVISION.
WORKING-STORAGE SECTION.

* DL/I FUNCTION CODES
01 DL-I-CODES.
   05 DLI-GHN     PIC X(4) VALUE 'GHN '.
   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).

* WORK FIELD TO UPDATE NAME
01 UPDATED-NAME           PIC X(25).

LINKAGE SECTION.
* PCB MASK
01 EMP-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: GHN EMPLOYEE UPDATE ===".

    PERFORM UNTIL STATUS-CODE NOT = '  '
        * Step 1: Use GHN to get and lock next EMPLOYEE
        CALL 'CBLTDLI' USING DLI-GHN,
                             EMP-PCB,
                             IO-AREA

        IF STATUS-CODE = '  '
            DISPLAY "FOUND EMPLOYEE: " EMPLOYEE-ID " - " EMPLOYEE-NAME

            * Step 2: Simulate name update (e.g., add '*')
            STRING EMPLOYEE-NAME DELIMITED BY SPACE
                   ' *' DELIMITED BY SIZE
                   INTO UPDATED-NAME

            MOVE UPDATED-NAME TO EMPLOYEE-NAME

            * Step 3: Update the segment using REPL
            CALL 'CBLTDLI' USING DLI-REPL,
                                 EMP-PCB,
                                 IO-AREA

            IF STATUS-CODE = '  '
                DISPLAY "-- NAME UPDATED TO: " EMPLOYEE-NAME
            ELSE
                DISPLAY "** REPL FAILED. STATUS = " STATUS-CODE
            END-IF
        ELSE IF STATUS-CODE = 'GB'
            DISPLAY "** END OF DATABASE **"
        ELSE
            DISPLAY "** ERROR: STATUS = " STATUS-CODE
        END-IF
    END-PERFORM.

    DISPLAY "=== PROGRAM COMPLETE ===".
    GOBACK.

Sample Output

=== BEGIN: GHN EMPLOYEE UPDATE ===
FOUND EMPLOYEE: E001 - JOHN DOE
-- NAME UPDATED TO: JOHN DOE *
FOUND EMPLOYEE: E002 - JANE SMITH
-- NAME UPDATED TO: JANE SMITH *
FOUND EMPLOYEE: E003 - ROBIN KING
-- NAME UPDATED TO: ROBIN KING *
** END OF DATABASE **
=== PROGRAM COMPLETE ===