Get Next (GN)
The 'GN' (Get Next) call is used to retrieve the next segment in the database hierarchy, moving sequentially from the current position. It's commonly used after a 'GU' (Get Unique) call to process multiple segments in order. The 'GN' call can be unqualified (retrieving the next segment regardless of type) or qualified (retrieving the next segment of a specific type). The syntax of a GN call is as follows −
CALL 'CBLTDLI' USING
DLI-GN
DB-PCB
IO-AREA
[SSA1]
[SSA2]
...- DLI-GN: A 4-character field with the value 'GN ', indicating the 'Get Next' 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 'GN' 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.
- GB: End of database reached; no more segments to retrieve.
- GA: Call completed successfully, but a higher-level segment was retrieved.
- GK: Call completed successfully, but a different segment type at the same level was retrieved.
Example
Scenario - This program sequentially retrieves all employee segments from a hierarchical IMS database that includes Company → Project → Employee segments.
Hierarchical Structure -
COMPANY ← root segment
└─ PROJECT ← child of COMPANY
└─ EMPLOYEE ← child of PROJECT
Program -
IDENTIFICATION DIVISION.
PROGRAM-ID. GETNEXTE.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
* DL/I FUNCTION CODE
01 DL-I-FUNCTIONS.
05 DLI-GN PIC X(4) VALUE 'GN '.
* I/O AREA to hold retrieved 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).
LINKAGE SECTION.
* PCB MASK FOR EMPLOYEE SEGMENT (used by IMS)
01 EMPLOYEE-PCB.
05 FILLER PIC X(8). *> DBD Name
05 SEG-LEVEL PIC XX.
05 STATUS-CODE PIC XX.
05 PROC-OPTIONS PIC X(4).
05 RESERVED PIC X(4).
05 SEGMENT-NAME-FB PIC X(8).
05 KEY-LENGTH PIC S9(5) COMP.
05 NUM-SENSITIVES PIC S9(5) COMP.
05 KEY-FEEDBACK PIC X(50).
PROCEDURE DIVISION.
DISPLAY "==== EMPLOYEE LISTING USING GN ====".
PERFORM UNTIL STATUS-CODE NOT = SPACES
CALL 'CBLTDLI' USING DLI-GN,
EMPLOYEE-PCB,
IO-AREA
IF STATUS-CODE = ' '
DISPLAY "---------------------------------"
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 IF STATUS-CODE = 'GB'
DISPLAY "** END OF DATABASE REACHED **"
ELSE
DISPLAY "** ERROR: STATUS CODE = " STATUS-CODE
EXIT PERFORM
END-IF
END-PERFORM.
DISPLAY "==== PROGRAM END ====".
GOBACK.Sample Output
==== EMPLOYEE LISTING USING GN ==== --------------------------------- COMPANY ID : C001 COMPANY NAME : TECHCORP PROJECT ID : P001 PROJECT NAME : AI DEV EMPLOYEE ID : E001 EMPLOYEE NAME : JOHN DOE --------------------------------- COMPANY ID : C001 COMPANY NAME : TECHCORP PROJECT ID : P001 PROJECT NAME : AI DEV EMPLOYEE ID : E002 EMPLOYEE NAME : JANE SMITH ... ** END OF DATABASE REACHED ** ==== PROGRAM END ====