IMS DL/I ISRT, DLET, REPL: Modifying IMS Data

Reading data is only half the picture. Production IMS programs must also insert new records, update existing ones, and delete obsolete data. The three DL/I update calls — ISRT (Insert), DLET (Delete), and REPL (Replace) — each have specific rules about positioning and PCB requirements.

Prerequisites for Update Calls

Before issuing any update call, the program's PSB must have the appropriate processing options:

ISRT: PCB must have PROCOPT=I or PROCOPT=A
DLET: PCB must have PROCOPT=D or PROCOPT=A
REPL: PCB must have PROCOPT=R or PROCOPT=A

Attempting an update operation without the correct PROCOPT returns status code AD.

ISRT — Insert Segment

ISRT adds a new segment occurrence to the database. The position for insertion is determined by the sequence field value in the new segment and the SSAs provided.

Inserting a new root segment (CUSTOMER):

cobol

* Populate the new customer data
MOVE '2001000001' TO CUST-KEY.
MOVE 'JOHN SMITH ' TO CUST-NAME.
MOVE '123 MAIN ST' TO CUST-ADDRESS.

* ISRT the root — no parent SSA needed
CALL 'CBLTDLI' USING ISRT-FUNC
                     CUSTOMER-PCB
                     CUSTOMER-IO-AREA
                     CUSTOMER-UNQUAL-SSA.

IF PCB-STATUS-CODE NOT = '  '
   PERFORM ISRT-ERROR-ROUTINE.

Inserting a dependent segment (ACCOUNT under a CUSTOMER):

cobol

* Position at the parent customer
MOVE '2001000001' TO SSA-CUST-KEY.
CALL 'CBLTDLI' USING GU-FUNC
                     CUSTOMER-PCB
                     CUSTOMER-IO-AREA
                     CUSTOMER-QUAL-SSA.

* Populate the new account
MOVE 'CHK0000001' TO ACCT-KEY.
MOVE 'CHK'        TO ACCT-TYPE.
MOVE +00000000    TO ACCT-BALANCE.

* ISRT under the positioned customer
CALL 'CBLTDLI' USING ISRT-FUNC
                     CUSTOMER-PCB
                     ACCOUNT-IO-AREA
                     CUSTOMER-QUAL-SSA
                     ACCOUNT-UNQUAL-SSA.

The SSAs in the ISRT call tell IMS where to insert — under the qualified CUSTOMER, as an ACCOUNT. IMS places the new ACCOUNT in sequence-field order among the existing ACCOUNT twins.

ISRT status codes:

Blank: Success
II: Segment already exists (duplicate unique key)
GE: Parent not found (the parent SSA did not match)
AD: Not authorised (PROCOPT missing insert)

DLET — Delete Segment

DLET deletes the segment at the current position in the database. You must first retrieve the segment with a GU or GN call (with the FOR UPDATE intent — actually via hold calls discussed below), then issue DLET.

IMS automatically deletes all dependent segments under the deleted segment — deleting a CUSTOMER deletes all their ACCOUNTs and TRANSACTIONs.

Deleting a specific ACCOUNT:

cobol

* Use GHU (Get Hold Unique) to retrieve with hold
CALL 'CBLTDLI' USING GHU-FUNC
                     CUSTOMER-PCB
                     ACCOUNT-IO-AREA
                     CUSTOMER-QUAL-SSA
                     ACCOUNT-QUAL-SSA.

IF PCB-STATUS-CODE = '  '
    CALL 'CBLTDLI' USING DLET-FUNC
                         CUSTOMER-PCB
                         ACCOUNT-IO-AREA.

Note the use of GHU (Get Hold Unique) instead of GU. The hold variants (GHU, GHN, GHNP) are required before DLET or REPL — they signal to IMS that you intend to update the retrieved segment and prevent other programs from modifying it before your update.

REPL — Replace Segment

REPL replaces the data in the segment at the current hold position with new data from the I/O area. REPL cannot change the sequence field value (that would require delete and re-insert). REPL updates all other fields.

Updating an account balance:

cobol

* Retrieve with hold
CALL 'CBLTDLI' USING GHU-FUNC
                     CUSTOMER-PCB
                     ACCOUNT-IO-AREA
                     CUSTOMER-QUAL-SSA
                     ACCOUNT-QUAL-SSA.

IF PCB-STATUS-CODE = '  '
    ADD TRANSACTION-AMOUNT TO ACCT-BALANCE
    CALL 'CBLTDLI' USING REPL-FUNC
                         CUSTOMER-PCB
                         ACCOUNT-IO-AREA.

The REPL call uses the data currently in ACCOUNT-IO-AREA as the replacement. Modify the I/O area fields you want to change, then issue REPL.

The Hold Calls: GHU, GHN, GHNP

The hold variants of the retrieval calls are required before DLET and REPL:

Retrieval	Hold Variant	Use Before
GU	GHU	DLET or REPL of a specific segment
GN	GHN	DLET or REPL during sequential scan
GNP	GHNP	DLET or REPL of child during GNP loop

Issuing DLET or REPL without a preceding hold call returns status code DJ (not held).

Frequently Asked Questions

Q: Can REPL change the sequence field value? No. The sequence field (the key field used for segment ordering) cannot be changed with REPL. To change a sequence field value, you must DLET the old segment and ISRT a new one with the new key value. This is one reason sequence fields should be stable identifiers that do not change (like account numbers, not timestamps).

Q: What happens if another program modifies a segment between my GHU and DLET? IMS hold calls do not lock the segment in the traditional database sense — other programs can still read it. However, IMS ensures that your program's DLET or REPL will not produce inconsistent results. If the segment was deleted by another program between your GHU and DLET, you receive status code DA.

Q: Do I need to re-execute GHU every time I want to update the same segment in a loop? Yes. If you need to update a segment multiple times (unusual but possible), each update cycle requires a fresh GHU call. A hold is consumed by DLET or REPL — after the update, you must re-retrieve with a hold call for any subsequent update.

Part of the IMS Mastery Course — Module 11 of 22.