IMS DB Get Hold Next in Parent (GHNP)
GHNP (Get Hold Next in Parent) is similar to GNP, which gets the next dependent (child) segment under a current parent. But GHNP holds (locks) the retrieved segment so you can safely update (REPL) or delete (DLET) it. In a COBOL program, the 'GHNP' call is made using the following syntax:
CALL 'CBLTDLI' USING
DLI-GHNP
DB-PCB
IO-AREA
[SSA1]
[SSA2]
...- DLI-GHNP: A 4-character field with the value 'GHNP', indicating the 'Get Hold Next within Parent' 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 'GHNP' 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.
- GP: Parentage not established; no segment retrieved.
Example
Scenario - Below is a simplified example of a COBOL program that uses the 'GHNP' call to retrieve and update 'PROJECT' segments under a specific 'COMPANY' segment from an IMS database:
Hierarchical Structure -
COMPANY ← root segment
└─ PROJECT ← child of COMPANY
└─ EMPLOYEE ← child of PROJECT
Program -
IDENTIFICATION DIVISION.
PROGRAM-ID. GHNPEXMP.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
DATA DIVISION.
WORKING-STORAGE SECTION.
* DL/I FUNCTION CODES
01 DL-I-CODES.
05 DLI-GU PIC X(4) VALUE 'GU '.
05 DLI-GHNP PIC X(4) VALUE 'GHNP'.
05 DLI-REPL PIC X(4) VALUE 'REPL'.
* I/O AREA
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-STRINGS.
05 SSA-COMPANY PIC X(30) VALUE 'COMPANY(COMPANY-ID =C001)'.
05 SSA-PROJECT PIC X(30) VALUE 'PROJECT(PROJECT-ID =P101)'.
* WORK AREA FOR NAME UPDATE
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 "=== START: GHNP UPDATE EMPLOYEES ===".
* Step 1: Get the specific project using GU
CALL 'CBLTDLI' USING DLI-GU,
EMP-PCB,
IO-AREA,
SSA-COMPANY,
SSA-PROJECT
IF STATUS-CODE = ' '
DISPLAY "PROJECT FOUND: " PROJECT-ID " - " PROJECT-NAME
DISPLAY "READING EMPLOYEES UNDER PROJECT..."
* Step 2: Use GHNP to get & hold each EMPLOYEE under this project
PERFORM UNTIL STATUS-CODE NOT = ' '
CALL 'CBLTDLI' USING DLI-GHNP,
EMP-PCB,
IO-AREA
IF STATUS-CODE = ' '
DISPLAY "EMPLOYEE FOUND: " EMPLOYEE-ID " - " EMPLOYEE-NAME
* Simulate update
STRING EMPLOYEE-NAME DELIMITED BY SPACE
' +UPDATED' DELIMITED BY SIZE
INTO UPDATED-NAME
MOVE UPDATED-NAME TO EMPLOYEE-NAME
* Update segment using REPL
CALL 'CBLTDLI' USING DLI-REPL,
EMP-PCB,
IO-AREA
IF STATUS-CODE = ' '
DISPLAY "-- UPDATED TO: " EMPLOYEE-NAME
ELSE
DISPLAY "** REPL FAILED. STATUS = " STATUS-CODE
END-IF
ELSE IF STATUS-CODE = 'GE'
DISPLAY "** NO MORE EMPLOYEES UNDER PROJECT **"
ELSE
DISPLAY "** ERROR: STATUS = " STATUS-CODE
END-IF
END-PERFORM
ELSE
DISPLAY "** PROJECT NOT FOUND OR ERROR. STATUS = " STATUS-CODE
END-IF.
DISPLAY "=== PROGRAM COMPLETE ===".
GOBACK.Sample Output
=== START: GHNP UPDATE EMPLOYEES === PROJECT FOUND: P101 - CLOUD PROJECT READING EMPLOYEES UNDER PROJECT... EMPLOYEE FOUND: E001 - JOHN DOE -- UPDATED TO: JOHN DOE +UPDATED EMPLOYEE FOUND: E002 - SARA LEE -- UPDATED TO: SARA LEE +UPDATED ** NO MORE EMPLOYEES UNDER PROJECT ** === PROGRAM COMPLETE ===