IMS DB Insert (ISRT)
ISRT (Insert) is a DL/I function used to add a new segment to the IMS hierarchical database. To insert a dependent segment, you must first position on its parent segment using GU or GHU. In a COBOL program, the 'ISRT' call is made using the following syntax:
CALL 'CBLTDLI' USING
DLI-ISRT
DB-PCB
IO-AREA
[SSA1]
[SSA2]
...- DLI-ISRT: A 4-character field with the value 'ISRT', indicating the Insert 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 an 'ISRT' call, IMS sets a status code in the DB-PCB to indicate the outcome:
- Blank (' '): Call was successful; segment inserted.
- GE: Segment not found that satisfies the SSA; no segment inserted.
- II: Attempted to insert a segment that already exists.
- AH: Invalid SSA encountered on insert call.
- AI: Error opening database.
- AJ: SSA specified for the call is invalid.
- AK: Field name specified for qualified SSA is incorrectly coded or the field name isn't defined in the DBD.
Example
Scenario - Below is a simplified example of a COBOL program that uses the 'ISRT' call to insert a new 'EMPLOYEE' segment into an IMS database:
Hierarchical Structure -
COMPANY ← root segment
└─ PROJECT ← child of COMPANY
└─ EMPLOYEE ← child of PROJECT
Program -
IDENTIFICATION DIVISION.
PROGRAM-ID. INSERTE.
DATA DIVISION.
WORKING-STORAGE SECTION.
* DL/I FUNCTION CODES
01 DL-I-FUNCTIONS.
05 DLI-GU PIC X(4) VALUE 'GU '.
05 DLI-ISRT PIC X(4) VALUE 'ISRT'.
* I/O AREA to hold new EMPLOYEE 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 for positioning
01 SSA-STRINGS.
05 SSA-COMPANY PIC X(30)
VALUE 'COMPANY(COMPANY-ID=C001)'.
05 SSA-PROJECT PIC X(30)
VALUE 'PROJECT(PROJECT-ID=P999)'.
05 SSA-EMPLOYEE PIC X(20)
VALUE 'EMPLOYEE'.
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 "=== IMS INSERT EMPLOYEE PROGRAM ===".
* Step 1: Position on the PROJECT segment using GU
CALL 'CBLTDLI' USING DLI-GU,
EMP-PCB,
IO-AREA,
SSA-COMPANY,
SSA-PROJECT
IF STATUS-CODE = ' '
DISPLAY "POSITIONED ON PROJECT: " PROJECT-ID
* Step 2: Populate IO-AREA with new EMPLOYEE data
MOVE 'E999' TO EMPLOYEE-ID
MOVE 'ALAN RICKMAN' TO EMPLOYEE-NAME
* Step 3: Use ISRT to insert EMPLOYEE segment
* under current PROJECT
CALL 'CBLTDLI' USING DLI-ISRT,
EMP-PCB,
IO-AREA,
SSA-EMPLOYEE
IF STATUS-CODE = ' '
DISPLAY "EMPLOYEE INSERTED SUCCESSFULLY"
DISPLAY "EMPLOYEE ID : " EMPLOYEE-ID
DISPLAY "EMPLOYEE NAME : " EMPLOYEE-NAME
ELSE
DISPLAY "** INSERT FAILED. STATUS = " STATUS-CODE
END-IF
ELSE
DISPLAY "** PROJECT NOT FOUND. STATUS = " STATUS-CODE
END-IF.
DISPLAY "=== END OF PROGRAM ===".
GOBACK.Sample Output
=== IMS INSERT EMPLOYEE PROGRAM === POSITIONED ON PROJECT: P999 EMPLOYEE INSERTED SUCCESSFULLY EMPLOYEE ID : E999 EMPLOYEE NAME : ALAN RICKMAN === END OF PROGRAM ===