DL/I calls from COBOL
A COBOL program talks to IMS by calling CBLTDLI with a function code, a PCB, an I/O area and optional segment search arguments (SSAs). After every call it checks the two-character status code in the PCB.
The call
CALL 'CBLTDLI' USING DLI-GU
CUSTDB-PCB
CUSTOMER-SEG
CUSTOMER-SSA
EVALUATE CUSTDB-STATUS
WHEN SPACES PERFORM PROCESS-CUSTOMER
WHEN 'GE' PERFORM CUSTOMER-NOT-FOUND
WHEN OTHER PERFORM DLI-ERROR
END-EVALUATEThe program receives its PCBs as parameters. In a batch DL/I or BMP program the entry point is typically ENTRY 'DLITCBL' USING IO-PCB CUSTDB-PCB, or the PROCEDURE DIVISION USING clause; the PCBs map onto LINKAGE SECTION structures that include the status code field.
Function codes
| Code | Meaning |
|---|---|
| GU | Get unique: go straight to a specific segment |
| GN | Get next: the next segment in hierarchical sequence |
| GNP | Get next within parent: the next child under the current parent |
| GHU / GHN / GHNP | The same, but hold the segment so it can be replaced or deleted |
| ISRT | Insert a new segment (or send a message on the I/O PCB) |
| REPL | Replace the held segment |
| DLET | Delete the held segment and its dependents |
Segment search arguments
An SSA tells IMS which segment you want. An unqualified SSA is just the 8-character segment name. A qualified SSA adds a condition in brackets: field name, operator and value.
CUSTOMER(CUSTNO =0000012345)Status codes you must know
| Status | Meaning |
|---|---|
| spaces | Call succeeded |
| GE | Segment not found |
| GB | End of database reached on a GN |
| GA / GK | GN moved to a different level (GA) or segment type at the same level (GK); informational |
| II | Insert failed: a segment with that key already exists |
| DJ | REPL or DLET without a preceding successful get-hold |
| AD | Invalid function code |
| QC | No more input messages (online programs reading the I/O PCB) |
An online program's shape
- GU on the I/O PCB to get the input message.
- Read and update databases with DL/I calls on the database PCBs.
- ISRT on the I/O PCB to send the reply.
- Loop back for the next message until GU returns QC.
Long-running BMPs take checkpoints (CHKP) at intervals to commit their work and release locks, and can be restarted from the last checkpoint with XRST.
A program issues GU for customer 12345 and gets status GE. What does that mean? Answer in two or three words.
Show a hint
It is the IMS equivalent of SQLCODE +100.
Show the solution
Segment not found: no CUSTOMER segment matched the SSA. It is a normal business result to handle, not an abend.
Common mistakes
Replace and delete need a GHU, GHN or GHNP first. Without it you get status DJ.
Not found and end of database are normal results. Handle them in the program's logic.
Segment and field names are 8 characters and the value must match the field length. A one-byte error quietly changes the search.
What you will see at work
- Production abends in IMS programs are often traced back to an unchecked status code; reviewers look for that first.
- Long BMPs without regular checkpoints hold locks and cause online timeouts; adding CHKP is a classic fix.
- Developers read DL/I traces and IMS log records with DBAs when diagnosing data problems.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.