IMS V7 Appl Programming CICS and IMS

IMS Version 7
Application Programming: EXEC DLI

Commands for CICS and IMS
SC26-9424-02
IMS Version 7
Application Programming: EXEC DLI

Commands for CICS and IMS
SC26-9424-02
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on
page xiii.
Third Edition (March 2003) (Softcopy Only)

This edition replaces and makes obsolete the previous edition, SC26-9424-01. This edition is available in softcopy
format only. The technical changes for this version are summarized under “Summary of Changes” on page xxi. The
technical changes for this edition are indicated by a number to the left of a change.
© Copyright International Business Machines Corporation 2000, 2003. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Programming Interface Information. . . . . . . . . . . . . . . . . . xv
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Product Names. . . . . . . . . . . . . . . . . . . . . . . . . xvi
Preface . . . . . . . . . . . . . . . . .xvii. . . . . . . . . .
Summary of Contents . . . . . . . . . . . .
xvii . . . . . . . . . .
Prerequisite Knowledge . . . . . . . . . . .
xvii . . . . . . . . . .
Syntax Diagrams. . . . . . . . . . . . . . .
xviii . . . . . . . . .
How to Send Your Comments . . . . . . . . . . . . . . . . . . . xx
Summary of Changes . . . . . . . . . . . . . . . . . . . . . xxi

1 Changes to The Current Version of This Book for IMS Version 7 . . . . . . xxi
Changes to This Book for IMS Version 7 . . . . . . . . . . . . . . . xxi
Library Changes for IMS Version 7 . . . . . . . . . . . . . . . . . xxi
Part 1. Writing Application Programs. . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7
Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7
A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 2. Writing EXEC DLI Commands for Your Application Program 11

Using the I/O PCB, PSB, and PCB . . . . . . . . . . . . . . . . . 11
I/O PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Alternate PCB . . . . . . . . . . . . . . . . . . . . . . . . 11
DB PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11
GSAM PCB . . . . . . . . . . . . . . . . . . . . . . . . . 11
Format of a PSB . . . . . . . . . . . . . . . . . . . . . . . 12
PCB Summary . . . . . . . . . . . . . . . . . . . . . . . . 12
Specifying an EXEC DLI Command . . . . . . . . . . . . . . . . . 13
Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . 13
EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . 14
DLET Command . . . . . . . . . . . . . . . . . . . . . . . . 15
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 16
GN Command . . . . . . . . . . . . . . . . . . . . . . . . . 17
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 22
GNP Command . . . . . . . . . . . . . . . . . . . . . . . . 22
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
© Copyright IBM Corp. 2000, 2003 iii

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 27
GU Command . . . . . . . . . . . . . . . . . . . . . . . . . 27
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 33
ISRT Command . . . . . . . . . . . . . . . . . . . . . . . . 33
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 38
POS Command. . . . . . . . . . . . . . . . . . . . . . . . . 39
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 40
REPL Command . . . . . . . . . . . . . . . . . . . . . . . . 40
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 44
RETRIEVE Command . . . . . . . . . . . . . . . . . . . . . . 44
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 46
SCHD Command . . . . . . . . . . . . . . . . . . . . . . . . 46
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47
TERM Command . . . . . . . . . . . . . . . . . . . . . . . . 47
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 48
System Service Commands . . . . . . . . . . . . . . . . . . . . 48
ACCEPT Command . . . . . . . . . . . . . . . . . . . . . . . 49
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 49
CHKP Command . . . . . . . . . . . . . . . . . . . . . . . . 49
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 50
DEQ Command . . . . . . . . . . . . . . . . . . . . . . . . 50
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
iv Application Programming: EXEC DLI Commands for CICS and IMS

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 51
LOAD Command . . . . . . . . . . . . . . . . . . . . . . . . 51
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 52
LOG Command. . . . . . . . . . . . . . . . . . . . . . . . . 52
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 53
QUERY Command . . . . . . . . . . . . . . . . . . . . . . . 53
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 54
REFRESH Command . . . . . . . . . . . . . . . . . . . . . . 54
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55
ROLB Command . . . . . . . . . . . . . . . . . . . . . . . . 55
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55
ROLL Command . . . . . . . . . . . . . . . . . . . . . . . . 56
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 56
ROLS Command . . . . . . . . . . . . . . . . . . . . . . . . 57
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 58
SETS Command . . . . . . . . . . . . . . . . . . . . . . . . 58
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 59
SETU Command . . . . . . . . . . . . . . . . . . . . . . . . 59
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 60
Contents v
STAT Command . . . . . . . . . . . . . . . . . . . . . . . . 60
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 61
SYMCHKP Command . . . . . . . . . . . . . . . . . . . . . . 61
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63
XRST Command . . . . . . . . . . . . . . . . . . . . . . . . 63
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67

Specifying an Application Interface Block (AIB) . . . . . . . . . . . . . 67
AIB Mask . . . . . . . . . . . . . . . . . . . . . . . . . . 67
CICS Restrictions with AIB support . . . . . . . . . . . . . . . . 68
Specifying the DL/I Interface Block (DIB) . . . . . . . . . . . . . . . 68
Defining a Key Feedback Area . . . . . . . . . . . . . . . . . . . 71
Defining I/O Areas. . . . . . . . . . . . . . . . . . . . . . . . 71
COBOL I/O Area . . . . . . . . . . . . . . . . . . . . . . . 72
PL/I I/O Area. . . . . . . . . . . . . . . . . . . . . . . . . 72
Assembler Language I/O Area . . . . . . . . . . . . . . . . . . 72
Chapter 4. More about Writing Your Application Program . . . . . . . . 73

Programming Guidelines . . . . . . . . . . . . . . . . . . . . . 73
Coding a Program in Assembler Language . . . . . . . . . . . . . 74
Coding a Program in COBOL . . . . . . . . . . . . . . . . . . 78
Coding a Program in PL/I . . . . . . . . . . . . . . . . . . . . 81
Coding a Program in C . . . . . . . . . . . . . . . . . . . . . 85
Preparing Your EXEC DLI Program for Execution . . . . . . . . . . . . 91
Translator Options Required for EXEC DLI . . . . . . . . . . . . . 91
Compiler Options Required for EXEC DLI . . . . . . . . . . . . . . 91
Linkage Editor Options Required for EXEC DLI . . . . . . . . . . . . 92
Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93

Processing DEDBs with Subset Pointers . . . . . . . . . . . . . . . 93
Before You Use Subset Pointers . . . . . . . . . . . . . . . . . 95
Designating Subset Pointers You Want to Use . . . . . . . . . . . . 95
Using Subset Pointers . . . . . . . . . . . . . . . . . . . . . 95
Subset Pointer Status Codes . . . . . . . . . . . . . . . . . . 101
The POS Command . . . . . . . . . . . . . . . . . . . . . . 101
Locating a Specific Sequential Dependent . . . . . . . . . . . . . 101
Locating the Last Inserted Sequential Dependent Segment . . . . . . . 102
Identifying Free Space . . . . . . . . . . . . . . . . . . . . 102
The P Processing Option. . . . . . . . . . . . . . . . . . . . 103
Chapter 6. Recovering Databases and Maintaining Database Integrity 105

Issuing Checkpoints in a Batch or BMP Program . . . . . . . . . . . . 105
Issuing the CHKP Command . . . . . . . . . . . . . . . . . . 105
Issuing the SYMCHKP Command . . . . . . . . . . . . . . . . 106
vi Application Programming: EXEC DLI Commands for CICS and IMS

Restarting Your Program and Checking for Position . . . . . . . . . . . 106
Backing Out Database Updates Dynamically: The ROLL and ROLB
Commands . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using Intermediate Backout Points: The SETS and ROLS Commands . . . . 106
SETS Command . . . . . . . . . . . . . . . . . . . . . . . 107
ROLS Command. . . . . . . . . . . . . . . . . . . . . . . 107
Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109

Accepting Database Availability Status Codes . . . . . . . . . . . . . 109
Obtaining Information about Database Availability. . . . . . . . . . . . 109
Part 2. For Your Reference . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 8. Comparing Command-Level and Call-Level Programs . . . . 113
Chapter 9. DL/I Status Codes . . . . . . . . . . . . . . . . . . 117

Status Code Tables . . . . . . . . . . . . . . . . . . . . . . . 117
Categories of DL/I Status Codes . . . . . . . . . . . . . . . . . 117
Status Code Explanations . . . . . . . . . . . . . . . . . . . . 127
Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 153
IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 153
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Contents vii
viii Application Programming: EXEC DLI Commands for CICS and IMS
Figures
1. The Structure of a Command-Level Batch or BMP Program . . . . . . . . . . . . . . . 7
2. Medical Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. PATIENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. ILLNESS Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. TREATMNT Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. BILLING Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. PAYMENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. HOUSHOLD Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
9. General Format of a PSB. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
10. Processing a Long Chain of Segment Occurrences with Subset Pointers . . . . . . . . . . 93
11. Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . . . 94
12. More Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . 94
13. How Subset Pointers Divide a Chain into Subsets . . . . . . . . . . . . . . . . . . 94
14. Processing Performed for the Sample Passbook Example. . . . . . . . . . . . . . . . 96
15. Retrieving the First Segment in a Chain of Segments . . . . . . . . . . . . . . . . . 97
16. Moving the Subset Pointer to the Next Segment after Your Current Position . . . . . . . . . 98
17. Unconditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . . . . 99
18. Conditionally Setting the Subset Pointer to Your Current Position. . . . . . . . . . . . . 100
© Copyright IBM Corp. 2000, 2003 ix

x Application Programming: EXEC DLI Commands for CICS and IMS
Tables
1. Summary of PCB Information . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2. Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . . . 13
3. DL/I Calls Available to IMS and CICS Command-Level Application Programs . . . . . . . . 113
4. Comparing Call-Level and Command-Level Programs: Commands and Calls . . . . . . . . 113
5. Comparing Call-Level and Command-Level Programs: Command Codes and Options . . . . . 114
6. Database Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
7. Message Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
8. System Service Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
© Copyright IBM Corp. 2000, 2003 xi

xii Application Programming: EXEC DLI Commands for CICS and IMS
Notices
This information was developed for products and services offered in the U.S.A. IBM
may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and
services currently available in your area. Any reference to an IBM product, program,
or service is not intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However,
it is the user’s responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to
you.
This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
© Copyright IBM Corp. 2000, 2003 xiii

and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurement may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which

illustrates programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to IBM,
for the purposes of developing, using, marketing or distributing application programs
conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly
tested under all conditions. IBM, therefore, cannot guarantee or imply reliability,
serviceability, or function of these programs. You may copy, modify, and distribute
these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to
IBM’s application programming interfaces.
xiv Application Programming: EXEC DLI Commands for CICS and IMS
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Programming Interface Information

This book is intended to help the application programmer write IMS application
programs. This book primarily documents General-use Programming Interface and
Associated Guidance Information provided by IMS.
General-use programming interfaces allow the customer to write programs that

obtain the services of IMS.
However, this book also documents Product-sensitive Programming Interface and

Associated Guidance Information provided by IMS.
Product-sensitive programming interfaces allow the customer installation to perform

tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or tuning of
IMS. Use of such interfaces creates dependencies on the detailed design or
implementation of the IBM software product. Product-sensitive programming
interfaces should be used only for these specialized purposes. Because of their
dependencies on detailed design and implementation, it is to be expected that
programs written to such interfaces may need to be changed to run with new
product releases or versions, or as a result of service.
Product-sensitive Programming Interface and Associated Guidance Information is

identified where it occurs, either by an introductory statement to a chapter or
section or by the following marking:
Product-sensitive programming interface
Product-sensitive Programming Interface and Associated Guidance Information.

End of Product-sensitive programming interface
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or
other countries or both:
C/370 IMS
CICS IMS/ESA
CICS/ESA MVS
CICS/MVS MVS/ESA
DATABASE 2 OS/2
DB2 OS/390
BookManager RACF
IBM z/OS
Notices xv
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
Product Names
In this book, the licensed programs have shortened names:
v “COBOL for MVS & VM” is referred to as “COBOL”.
v “DB2 for MVS” is referred to as “DB2”.
v “CICS for MVS” is referred to as “CICS”.
v “CICS Transaction Server for OS/390” is referred to as “CICS”.
xvi Application Programming: EXEC DLI Commands for CICS and IMS
Preface
This book is for CICS application programmers whose programs use EXEC DLI
commands in an IMS environment. This book lists and describes the EXEC DLI
commands, and explains the procedures for writing application programs. For
information on using databases (such as, position in the database, using multiple
positioning, and using secondary indexing and logical relationships), see IMS
Version 7 Application Programming: Database Manager.
1 This edition is available only in PDF and BookManager formats. You can get the
1 most current versions of the PDF and BookManager formats by going to the IMS
1 Web site at www.ibm.com/ims and linking to the Library page.
Summary of Contents
This book has two parts:
Part 1 (Chapter 1, “How Your EXEC DLI Application Program Works with IMS”, on
page 7through Chapter 7, “Using Data Availability Enhancements”, on page 109)
explains the basics of writing the DL/I part of your application program with EXEC
DLI commands.
Part 2, “For Your Reference”, on page 111 contains reference information about the
parts of an IMS command-level application program such as EXEC DLI commands,
system service calls, qualification statements, EXEC DLI options, the DIB (DL/I
Interface Block), I/O areas, and status codes. These chapters are for experienced
programmers who understand IMS application programming and need only to look
up a fact such as the meaning of a particular status code. If you are one of those
programmers, you may also want to have on hand IMS/ESA Application
Programming: EXEC DLI Commands for CICS and IMS Summary.
“Bibliography” on page 153 lists all the non-IMS publications referred to in this book.
Prerequisite Knowledge
1 IBM offers a wide variety of classroom and self-study courses to help you learn
1 IMS. For a complete list, see the IMS home page on the World Wide Web at:
1 www.ibm.com/ims
1 This book assumes you are a CICS programmer familiar with the functions,
1 facilities, hardware, and software described in CICS/ESA CICS Family General
1 Information and from the Library page of the IMS home page on the Web:
1 www.ibm.com/ims.
This book also assumes that, if you plan to write a CICS program, you are familiar
with the principles covered in CICS/ESA Application Programming Guide and in
other CICS documentation.
Before using this book, you should understand the concepts of application design
presented in IMS Version 7 Application Programming: Design Guide.
This book is a follow-on to IMS Version 7 Application Programming: Design Guide

and also refers to IMS Version 7 Application Programming: Database Manager for
database information common to both EXEC DLI and DL/I application programs.
© Copyright IBM Corp. 2000, 2003 xvii

For definitions of IMS terms used in this book and references to related information
in other publications, see IMS Version 7 Master Index and Glossary.
Syntax Diagrams
The following rules apply to the syntax diagrams used in this book:
Arrow symbols
Read the syntax diagrams from left to right, from top to bottom, following
the path of the line.
򐂰򐂰─── Indicates the beginning of a statement.
───򐂰 Indicates that the statement syntax is continued on the next line.
򐂰─── Indicates that a statement is continued from the previous line.
───򐂰򙳰 Indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the
─── symbol and end with the ─── symbol.
Conventions
v Keywords, their allowable synonyms, and reserved parameters, appear in
uppercase for MVS and OS/2® operating systems, and lowercase for
UNIX® operating systems. These items must be entered exactly as
shown.
v Variables appear in lowercase italics (for example, column-name). They
represent user-defined parameters or suboptions.
v When entering commands, separate parameters and keywords by at
least one blank if there is no intervening punctuation.
v Enter punctuation marks (slashes, commas, periods, parentheses,
quotation marks, equal signs) and numbers exactly as given.
v Footnotes are shown by a number in parentheses, for example, (1).
v A symbol indicates one blank position.
Required items
Required items appear on the horizontal line (the main path).
REQUIRED_ITEM
Optional Items
Optional items appear below the main path.
REQUIRED_ITEM
optional_item
If an optional item appears above the main path, that item has no effect on
the execution of the statement and is used only for readability.
optional_item
REQUIRED_ITEM
Multiple required or optional items

If you can choose from two or more items, they appear vertically in a stack.
If you must choose one of the items, one item of the stack appears on the
main path.
xviii Application Programming: EXEC DLI Commands for CICS and IMS
REQUIRED_ITEM required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the
main path.
REQUIRED_ITEM
optional_choice1
optional_choice2
Repeatable items
An arrow returning to the left above the main line indicates that an item can
be repeated.
REQUIRED_ITEM repeatable_item
If the repeat arrow contains a comma, you must separate repeated items
with a comma.
REQUIRED_ITEM repeatable_item
A repeat arrow above a stack indicates that you can specify more than one
of the choices in the stack.
Default keywords
IBM-supplied default keywords appear above the main path, and the
remaining choices are shown below the main path. In the parameter list
following the syntax diagram, the default choices are underlined.
default_choice
REQUIRED_ITEM
optional_choice
optional_choice
IMS-specific syntax information

Fragments
Sometimes a diagram must be split into fragments. The fragments
are represented by a letter or fragment name, set off like this: | A |.
The fragment follows the end of the main diagram. The following
example shows the use of a fragment.
STATEMENT item 1 item 2 A
A:
item 3 KEYWORD
item 4 item 5
item 6
Preface xix
Substitution-block
Sometimes a set of several parameters is represented by a
substitution-block such as <A>. For example, in the imaginary
/VERB command you could enter /VERB LINE 1, /VERB EITHER
LINE 1, or /VERB OR LINE 1.
/VERB LINE line#

<A>
where <A> is:
EITHER
OR
Parameter endings
Parameters with number values end with the symbol '#', parameters
that are names end with 'name', and parameters that can be
generic end with '*'.
/MSVERIFY MSNAME msname

SYSID sysid#
The MSNAME keyword in the example supports a name value and

the SYSID keyword supports a number value.
How to Send Your Comments

Your feedback is important in helping us provide the most accurate information and
highest quality information. If you have any comments about this book or any other
IMS documentation, you can do one of the following:
1 v Go to the IMS home page at: http://www.ibm.com/ims. There you will find an
1 online feedback page where you can enter and submit comments.
v Send your comments by e-mail to imspubs@us.ibm.com. Be sure to include the
name of the book the part number of the book the version of IMS, and, if
applicable, the specific location of the text you are commenting on (for example,
a page number or table number).
v Fill out one of the forms at the back of this book and return it by mail, by fax, or
by giving it to an IBM representative.
xx Application Programming: EXEC DLI Commands for CICS and IMS

Summary of Changes
1 Changes to The Current Version of This Book for IMS Version 7
1 This edition, which is available in softcopy format only, includes technical and
1 editorial changes.
Changes to This Book for IMS Version 7

This edition, which is available in softcopy format only, includes technical and
editorial changes. This book contains new technical information for Version 7, and
editorial changes.
Library Changes for IMS Version 7

The major change to the IMS Version 7 library is that it is available not only in
hardcopy and in softcopy on BookManager, but also in softcopy Portable Document
Format (PDF). The complete library is available in BookManager and PDF on the
IMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7
softcopy library is available on the Transaction Processing and Data CD-ROM
(SK2T-0730) and the OS/390 Collection CD-ROM (SK2T-6700) in BookManager.
The unlicensed IMS Version 7 softcopy library is available in BookManager and
PDF on the Web at http://www.ibm.com/ims
Other changes include changes to these following books:

v IMS Version 7 Common Queue Server and Base Primitive Environment Guide
and Reference
The book formerly titled IMS/ESA Common Queue Server Guide and Reference
in the Version 6 library is called IMS Version 7 Common Queue Server and Base
Primitive Environment Guide and Reference.
The IMS Version 7 Common Queue Server and Base Primitive Environment
Guide and Reference is divided into two parts: ″Part 1: Common Queue Server,″
and ″Part 2: Base Primitive Environment.″
The IMS Version 7 Common Queue Server and Base Primitive Environment
Guide and Reference is now an unlicensed book.
v IMS Version 7 Command Reference
The book formerly titled IMS/ESA Operator’s Reference in the Version 6 library is
called IMS Version 7 Command Reference.
v IMS Version 7 Utilities Reference: Database and Transaction Manager
The books formerly titled IMS/ESA Utilities Reference: Database Manager and
IMS/ESA Utilities Reference: Transaction Manager in the Version 6 library have
been combined into one book called IMS Version 7 Utilities Reference: Database
and Transaction Manager.
v IMS Version 7 Application Programming: Database Manager and IMS Version 7
Customization Guide
The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved from
the IMS Version 7 Application Programming: Database Manager to the IMS
Version 7 Customization Guide.
v IMS Version 7 Sample Operating Procedures
For IMS Version 7, this book is available only in BookManager and PDF softcopy
on the product kit (LK3T-3526), the OS/390 Collection CD-ROM (SK2T-6700),
and on the Web at: http://www.ibm.com/ims
© Copyright IBM Corp. 2000, 2003 xxi

The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). As
a new book, the IJUG is available only in PDF and BookManager softcopy on the
product kit (LK3T-3526) and on the Web at: http://www.ibm.com/ims
xxii Application Programming: EXEC DLI Commands for CICS and IMS
Part 1. Writing Application Programs
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7
Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7
A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8

Using the I/O PCB, PSB, and PCB . . . . . . . . . . . . . . . . . 11
I/O PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Alternate PCB . . . . . . . . . . . . . . . . . . . . . . . . 11
DB PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11
GSAM PCB . . . . . . . . . . . . . . . . . . . . . . . . . 11
Format of a PSB . . . . . . . . . . . . . . . . . . . . . . . 12
PCB Summary . . . . . . . . . . . . . . . . . . . . . . . . 12
DB Batch Programs . . . . . . . . . . . . . . . . . . . . . 12
BMPs, MPPs, and IFPs. . . . . . . . . . . . . . . . . . . . 12
CICS Programs with DBCTL . . . . . . . . . . . . . . . . . . 12
Specifying an EXEC DLI Command . . . . . . . . . . . . . . . . . 13
Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . 13
EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . 14
DLET Command . . . . . . . . . . . . . . . . . . . . . . . . 15
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 16
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 16
GN Command . . . . . . . . . . . . . . . . . . . . . . . . . 17
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 21
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 21
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 21
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 22
GNP Command . . . . . . . . . . . . . . . . . . . . . . . . 22
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 26
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 27
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 27
GU Command . . . . . . . . . . . . . . . . . . . . . . . . . 27
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 32
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 32
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 33
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 33
ISRT Command . . . . . . . . . . . . . . . . . . . . . . . . 33
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
© Copyright IBM Corp. 2000, 2003 1

Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 38
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 38
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 38
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 38
POS Command. . . . . . . . . . . . . . . . . . . . . . . . . 39
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 40
REPL Command . . . . . . . . . . . . . . . . . . . . . . . . 40
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 43
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 43
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 44
Example 4 . . . . . . . . . . . . . . . . . . . . . . . . 44
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 44
RETRIEVE Command . . . . . . . . . . . . . . . . . . . . . . 44
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 46
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 46
SCHD Command . . . . . . . . . . . . . . . . . . . . . . . . 46
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 47
TERM Command . . . . . . . . . . . . . . . . . . . . . . . . 47
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 48
System Service Commands . . . . . . . . . . . . . . . . . . . . 48
ACCEPT Command . . . . . . . . . . . . . . . . . . . . . . . 49
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 49
CHKP Command . . . . . . . . . . . . . . . . . . . . . . . . 49
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 50
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 50
DEQ Command . . . . . . . . . . . . . . . . . . . . . . . . 50
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2 Application Programming: EXEC DLI Commands for CICS and IMS

Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 51
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 51
LOAD Command . . . . . . . . . . . . . . . . . . . . . . . . 51
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 52
LOG Command. . . . . . . . . . . . . . . . . . . . . . . . . 52
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 53
QUERY Command . . . . . . . . . . . . . . . . . . . . . . . 53
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 54
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 54
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 54
REFRESH Command . . . . . . . . . . . . . . . . . . . . . . 54
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 54
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55
ROLB Command . . . . . . . . . . . . . . . . . . . . . . . . 55
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 55
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55
ROLL Command . . . . . . . . . . . . . . . . . . . . . . . . 56
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 56
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 56
ROLS Command . . . . . . . . . . . . . . . . . . . . . . . . 57
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 57
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 58
Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 58
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 58
SETS Command . . . . . . . . . . . . . . . . . . . . . . . . 58
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Part 1. Writing Application Programs 3

Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 59
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 59
SETU Command . . . . . . . . . . . . . . . . . . . . . . . . 59
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 60
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 60
STAT Command . . . . . . . . . . . . . . . . . . . . . . . . 60
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 61
SYMCHKP Command . . . . . . . . . . . . . . . . . . . . . . 61
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 63
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63
XRST Command . . . . . . . . . . . . . . . . . . . . . . . . 63
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Example . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Explanation . . . . . . . . . . . . . . . . . . . . . . . . 65
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67

Specifying an Application Interface Block (AIB) . . . . . . . . . . . . . 67
AIB Mask . . . . . . . . . . . . . . . . . . . . . . . . . . 67
CICS Restrictions with AIB support . . . . . . . . . . . . . . . . 68
Specifying the DL/I Interface Block (DIB) . . . . . . . . . . . . . . . 68
Defining a Key Feedback Area . . . . . . . . . . . . . . . . . . . 71
Defining I/O Areas. . . . . . . . . . . . . . . . . . . . . . . . 71
COBOL I/O Area . . . . . . . . . . . . . . . . . . . . . . . 72
PL/I I/O Area. . . . . . . . . . . . . . . . . . . . . . . . . 72
Assembler Language I/O Area . . . . . . . . . . . . . . . . . . 72
Chapter 4. More about Writing Your Application Program . . . . . . . . 73

Programming Guidelines . . . . . . . . . . . . . . . . . . . . . 73
Coding a Program in Assembler Language . . . . . . . . . . . . . 74
Coding a Program in COBOL . . . . . . . . . . . . . . . . . . 78
Coding a Program in PL/I . . . . . . . . . . . . . . . . . . . . 81
Coding a Program in C . . . . . . . . . . . . . . . . . . . . . 85
Preparing Your EXEC DLI Program for Execution . . . . . . . . . . . . 91
Translator Options Required for EXEC DLI . . . . . . . . . . . . . 91
Compiler Options Required for EXEC DLI . . . . . . . . . . . . . . 91
Linkage Editor Options Required for EXEC DLI . . . . . . . . . . . . 92
Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93

Processing DEDBs with Subset Pointers . . . . . . . . . . . . . . . 93

Before You Use Subset Pointers . . . . . . . . . . . . . . . . . 95
Designating Subset Pointers You Want to Use . . . . . . . . . . . . 95
Using Subset Pointers . . . . . . . . . . . . . . . . . . . . . 95
Our Sample Application. . . . . . . . . . . . . . . . . . . . 95
Retrieving the First Segment in the Subset with the GETFIRST Option 96
Setting the Subset Pointers with the SETZERO, MOVENEXT, SET, and
SETCOND Options . . . . . . . . . . . . . . . . . . . . 97
Inserting Segments in a Subset . . . . . . . . . . . . . . . . 100
Deleting the Segment Pointed to By a Subset Pointer . . . . . . . . 100
Combining Options . . . . . . . . . . . . . . . . . . . . . 100
Subset Pointer Status Codes . . . . . . . . . . . . . . . . . . 101
The POS Command . . . . . . . . . . . . . . . . . . . . . . 101
Locating a Specific Sequential Dependent . . . . . . . . . . . . . 101
Locating the Last Inserted Sequential Dependent Segment . . . . . . . 102
Identifying Free Space . . . . . . . . . . . . . . . . . . . . 102
The P Processing Option. . . . . . . . . . . . . . . . . . . . 103

Issuing Checkpoints in a Batch or BMP Program . . . . . . . . . . . . 105
Issuing the CHKP Command . . . . . . . . . . . . . . . . . . 105
Issuing the SYMCHKP Command . . . . . . . . . . . . . . . . 106
Restarting Your Program and Checking for Position . . . . . . . . . . . 106
Commands . . . . . . . . . . . . . . . . . . . . . . . . . 106
Using Intermediate Backout Points: The SETS and ROLS Commands . . . . 106
SETS Command . . . . . . . . . . . . . . . . . . . . . . . 107
ROLS Command. . . . . . . . . . . . . . . . . . . . . . . 107
Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109

Accepting Database Availability Status Codes . . . . . . . . . . . . . 109
Obtaining Information about Database Availability. . . . . . . . . . . . 109
Part 1. Writing Application Programs 5

Chapter 1. How Your EXEC DLI Application Program Works
with IMS
This chapter describes the components of your CICS program. It also describes the
sample hierarchy used in this book’s examples.
Your EXEC DLI application uses EXEC DLI commands to read and update DL/I
databases. These applications can execute as pure batch, as a BMP running with
DBCTL or DB/DC, or as an online CICS program using DBCTL. Your EXEC DLI
program can also issue system service commands when using DBCTL.
IMS DB/DC can provide the same services as DBCTL.
Getting Started with EXEC DLI

Figure 1 shows the main elements of programs that use EXEC DLI commands to
access DL/I databases. The main differences between a CICS program and a
command-level batch or BMP program (represented by Figure 1) are that you do
not schedule a PSB for a batch program, and that you do not issue checkpoints for
a CICS program. The numbers on the left of the figure correspond to the notes that
follow.
Figure 1. The Structure of a Command-Level Batch or BMP Program
Notes to Figure 1:
1I/O areas. DL/I passes segments to and from the program in the I/O areas.
You may use a separate I/O area for each segment.
2Key feedback area. DL/I passes, on request, the concatenated key of the
lowest-level segment retrieved to the key feedback area.

Getting Started with EXEC DLI
3DL/I Interface Block (DIB). DL/I and CICS place the results of each
command in the DIB. The DIB contains most of the same information returned in
the DB PCB for programs using the call-level interface.
4Program entry. Control is passed to your program during program entry.
5Issue EXEC DLI commands. Commands read and update information in the
database.
6Check the status code. To find out the results of each command you issue,
you should check the status code in the DIB after issuing an EXEC DLI
command for database processing and after issuing a checkpoint command.
7Issue checkpoint. Issue checkpoints as needed to establish places from
which to restart. Issuing a checkpoint commits database changes and releases
resources.
8Terminate. This returns control to the operating system, commits database
changes, and releases resources.
Requirement: CICS/ESA Version 4, or later, and CICS Transaction Server run with
this version of IMS. Unless a distinction needs to made, all supported versions are
referred to as CICS.
A Sample Hierarchy
Many of the examples in this book use the medical hierarchy shown in the following
graphic. The database contains information that a medical clinic might keep about
its patients. To understand the examples, you should be familiar with the hierarchy
and the segments it contains.
Figure 2. Medical Hierarchy
The figures that follow show the layouts of the segments in the hierarchy. The
number below each field is the length in bytes that has been defined for that field.
v PATIENT Segment
The following graphic shows the PATIENT segment. It has three fields: patient
number (PATNO), patient name (NAME), and the patient’s address (ADDR).
PATIENT has a unique key field: PATNO. PATIENT segments are stored in
ascending order of their patient numbers. The lowest patient number in the
database is 00001 and the highest is 10500.
Figure 3. PATIENT Segment
v ILLNESS Segment

A Sample Hierarchy
The following graphic shows the ILLNESS segment. It has two fields: the date
when the patient came to the clinic with the illness (ILLDATE) and the name of
the illness (ILLNAME). The key field is ILLDATE. Because it is possible for a
patient to come to the clinic with more than one illness on the same date, this
key field is non-unique, that is, there may be more than one ILLNESS segment
with the same (an equal) key field value.
Usually someone in the installation, such as the database administrator (DBA),
decides the order in which segments in the database having equal keys or no
keys will be placed. The DBA can use the RULES keyword of the SEGM
statement of the DBD to specify this.
For segments with equal keys or no keys, RULES determines where the
segment is inserted. Where RULES=LAST, ILLNESS segments that have equal
keys are stored on a first-in first-out basis among those with equal keys.
ILLNESS segments with unique keys are stored in ascending order on the date
field, regardless of RULES. ILLDATE is specified in the format YYYYMMDD.
Figure 4. ILLNESS Segment
v TREATMNT Segment
The following graphic shows the TREATMNT segment.
It contains four fields:
– The date of the treatment (DATE)
– The medicine that was given to the patient (MEDICINE)
– The quantity of the medicine that the patient was given (QUANTITY)
– The name of the doctor who prescribed the treatment (DOCTOR)
The key field of the TREATMNT segment is DATE. Because a patient may
receive more than one treatment on the same date, DATE is a non-unique key
field. TREATMNT, like ILLNESS, has been specified as having RULES=LAST.
TREATMNT segments are also stored on a first-in-first-out basis. DATE is
specified in the same format as ILLDATE—YYYYMMDD.
Figure 5. TREATMNT Segment
v BILLING Segment
The following graphic shows the BILLING segment. It has only one field—the
amount of the current bill. BILLING has no key field.
Figure 6. BILLING Segment
v PAYMENT Segment
Chapter 1. How Your EXEC DLI Application Program Works with IMS 9
A Sample Hierarchy
The following graphic shows the PAYMENT segment. It also has only one
field—the amount of each payment remitted. The PAYMENT segment has no key
field.
Figure 7. PAYMENT Segment
v HOUSHOLD Segment
The following graphic shows the HOUSHOLD segment. It contains the names of
the members of the patient’s household, and how each is related to the patient.
RELNAME is the key field.
Figure 8. HOUSHOLD Segment

Chapter 2. Writing EXEC DLI Commands for Your Application
Program
This chapter explains the I/O PCB, PSB, and PCB. It also lists and describes the
EXEC DLI commands. For each command, a syntax diagram is provided, along
with information on options, restrictions, usage, and examples illustrating that
usage.
Using the I/O PCB, PSB, and PCB

A PSB used in a DBCTL environment can contain any of the following PCB types:
v I/O PCB
v Alternate PCBs
v DB PCBs
v GSAM PCBs
I/O PCB
In a DBCTL environment, an I/O PCB is needed to issue DBCTL service requests.
Unlike the other types of PCB, it is not defined with PSB generation, but if the
application program is using an I/O PCB, this has to be indicated in the PSB
scheduling request.
Alternate PCB
An alternate PCB defines a logical terminal and can be used instead of the I/O PCB
when it is necessary to direct a response to a terminal. Alternate PCBs appear in
PSBs used in a CICS-DBCTL environment, but are used only in an IMS DC
environment. CICS applications using DBCTL cannot successfully issue commands
that specify an alternate PCB, an MSDB PCB, or a GSAM PCB. However, a PSB
that contains PCBs of these types can be scheduled successfully in a CICS-DBCTL
environment.
Alternate PCBs are included in the PCB address list returned to a call level
application program. In an EXEC DLI application program, the existence of alternate
PCBs in the PSB affects the PCB number used in the PCB keyword.
DB PCB
A database PCB (DB PCB) is the PCB that defines an application program’s
interface to a database. One DB PCB is needed for each database view used by
the application program. It can be a full-function PCB, a DEDB PCB, or an MSDB
PCB.
GSAM PCB
A GSAM PCB defines an application program’s interface for GSAM operations.
When using DBCTL, a CICS program receives, by default, a DB PCB as the first
PCB in the parameter list passed to it after scheduling. However, when your
application program can handle an I/O PCB, you indicate this using the SYSSERVE
keyword on the SCHD command. The I/O PCB is then the first PCB in the parameter
address list passed back to your application program.

I/O PCB, PSB, and PCB
Format of a PSB
The format of a PSB is shown in Figure 9.
[IOPCB]
[Alternate PCB ... Alternate PCB]
[DBPCB ... DBPCB]
[GSAMPCB ... GSAMPCB]
Figure 9. General Format of a PSB
Each PSB must contain at least one PCB. The I/O PCB must be addressable in
order to issue a system service command. An alternate PCB is used only for IMS
online programs, which can run only with the Transaction Manager. Alternate PCBs
can be present even though your program does not run under the Transaction
Manager. A DB PCB can be a full-function PCB, a DEDB PCB, or an MSDB PCB.
PCB Summary
The following section summarizes the information concerning I/O PCBs and
alternate PCBs in various types of application programs.
Recommendation: You should read the following section if you intend to issue
system service requests.
DB Batch Programs
Alternate PCBs are always included in the list of PCBs supplied to the program by
DL/I irrespective of whether you have specified CMPAT=Y. The I/O PCB is returned
depending on the CMPAT option.
If you specify CMPAT=Y, the PCB list contains the address of the I/O PCB, followed
by the addresses of any alternate PCBs, followed by the addresses of any DB
PCBs.
If you do not specify CMPAT=Y, the PCB list contains the addresses of any
alternate PCBs followed by the addresses of the DB PCBs.
BMPs, MPPs, and IFPs

I/O PCBs and alternate PCBs are always passed to BMP programs. I/O PCBs and
alternate PCBs are also always passed to MPPs and to IFP application programs,
which are described in IMS Version 7 Application Programming: Design Guide.
The PCB list contains the address of the I/O PCB, followed by the addresses of any
alternate PCBs, followed by the addresses of the DB PCBs.
CICS Programs with DBCTL

The first PCB always refers to the first DB PCB whether you specify the
SYSSERVE keyword.
Table 1 summarizes the I/O PCB and alternate PCB information.

Table 1. Summary of PCB Information
EXEC DLI
I/O PCB count included in Alternate PCB count
Environment PCB(n) included in PCB(n)
CICS DBCTL1 No No
2
CICS DBCTL No No

I/O PCB, PSB, and PCB
Table 1. Summary of PCB Information (continued)
EXEC DLI
I/O PCB count included in Alternate PCB count
Environment PCB(n) included in PCB(n)
BMP Yes Yes
3
Batch No Yes
4
Batch Yes Yes
Notes:
1. SCHD command issued without the SYSSERVE option.
2. SCHD command issued with the SYSSERVE option for a CICS DBCTL command or for
a function-shipped command which is satisfied by a remote CICS system using DBCTL.
3. CMPAT=N specified on the PSBGEN statement.
4. CMPAT=Y specified on the PSBGEN statement.
Specifying an EXEC DLI Command

The following descriptions illustrates the general syntax of the EXEC DLI
commands and the information supplied by each parameter and variable. Table 2
provides a summary of the commands available to batch, BMP, and online
programs.
The examples in this chapter use the PL/I delimiter.
Code the commands in free form: Where keywords, operands, and parameters are
shown separated by commas, no blanks can appear immediately before or after the
comma. Where keywords, operands, and parameters are shown separated by
blanks, you can include as many blanks as you wish.
The format of the commands is the same for users of COBOL, PL/I, assembler
language, C/370 and C++/370.
Summary of EXEC DLI Commands

A summary of all the EXEC DLI commands is provided in Table 2.
Table 2. Summary of EXEC DLI Commands
Program Characteristics
Batch- CICS with
Request Type Batch Oriented BMP DBCTL1
ACCEPT command4 Yes Yes Yes
4
CHKP command Yes Yes No
4
DEQ command Yes Yes Yes
DLET command Yes Yes Yes
4
Get commands (GU, GHU, GN, GHN, GNP, GHNP) Yes Yes Yes
5
GMSG command No Yes Yes
ICMD command5 No Yes Yes
ISRT command4 Yes Yes Yes
LOAD command Yes No No

Summary of EXEC DLI Commands
Table 2. Summary of EXEC DLI Commands (continued)
Batch- CICS with
LOG command4 Yes Yes Yes
4
POS command No Yes Yes
4
QUERY command Yes Yes Yes
5
RCMD command No Yes Yes
4
REFRESH command Yes Yes Yes
4
REPL command Yes Yes Yes
RETRIEVE command Yes Yes No
ROLB command Yes Yes No
ROLL command Yes Yes No
2 4
ROLS command , Yes Yes Yes
SCHD command No No Yes
2 4
SETS command , Yes Yes Yes
SETU command Yes Yes No
3 4
STAT command , Yes Yes Yes
SYMCHKP command Yes Yes No
TERM command No No Yes
XRST command Yes Yes No
Notes:
1. In a CICS remote DL/I environment, commands in the CICS with DBCTL column are supported if you are shipping
a function to a remote CICS that uses DBCTL.
2. ROLS and SETS commands are not valid when the PSB contains a DEDB.
3. STAT is a Product-sensitive programming interface.
4. Are supported in the AIB format.
5. Are described in the AOI documentation within the IMS/ESA Operations Guide.
EXEC DLI Commands

The following commands are the only ones allowed for EXEC DLI. They can be
used to read and update DL/I databases with a batch program, a BMP (running
DBCTL or DB/DC), or a CICS program using DBCTL.
The EXEC DLI commands and the pages they are found on are as follows:
v “DLET Command” on page 15
v “GN Command” on page 17
v “GNP Command” on page 22
v “GU Command” on page 27
v “ISRT Command” on page 33
v “POS Command” on page 39
v “REPL Command” on page 40
v “RETRIEVE Command” on page 44
v “SCHD Command” on page 46

EXEC DLI Commands
v “TERM Command” on page 47
v “ACCEPT Command” on page 49
v “CHKP Command” on page 49
v “DEQ Command” on page 50
v “LOAD Command” on page 51
v “LOG Command” on page 52
v “QUERY Command” on page 53
v “REFRESH Command” on page 54
v “ROLB Command” on page 55
v “ROLL Command” on page 56
v “ROLS Command” on page 57
v “SETS Command” on page 58
v “SETU Command” on page 59
v “STAT Command” on page 60
v “SYMCHKP Command” on page 61
v “XRST Command” on page 63
The examples included with each command refer to the “A Sample Hierarchy” on
page 8.
DLET Command
The Delete (DLET) command is used to remove a segment and its dependents from
the database.
Format
EXEC DLI DLET
USING PCB(expression) VARIABLE
SEGMENT(name) FROM(area)
SEGMENT((area)) SEGLENGTH(expression)

SETZERO(data_value)
Options
USING PCB(expression)
Specifies the DB PCB you want to use for the command. Its argument can be
any expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number.
VARIABLE
Indicates that a segment is variable-length.
SEGMENT(name)
Qualifies the command, specifying the name of the segment type you want to
retrieve, insert, delete, or replace.

DLET Command
SEGMENT((area))
Is a reference to an area in your program containing the name of the segment
type. You can specify an area instead of specifying the name of the segment in
the command.
SEGLENGTH(expression)
Specifies the length of the I/O area into which the segment is retrieved. Its
argument can be any expression that converts to the integer data type; you can
specify either a number or a reference to a halfword in your program containing
a number. (It is required in COBOL programs for any SEGMENT level that
specifies the INTO or FROM option.)
Requirement: The value specified for SEGLENGTH must be greater than or
equal to the length of the longest segment that can be processed by this call.
FROM(area)
Specifies an area containing the segment to be added, replaced, or deleted.
Use FROM to insert one or more segments with one command.
SETZERO(data_value)
Specifies setting a subset pointer to zero.
Usage
You use the DLET command to delete a segment and its dependents from the
database. You must first retrieve segments you want to delete, just as if you were
replacing segments, The DLET command deletes the retrieved segment and its
dependents, if any, from the database.
Example
“Evelyn Parker has moved away from this area. Her patient number is 10450.
Delete her record from the database.”
Explanation
You want to delete all the information about Evelyn Parker from the database. To do
this, you must delete the PATIENT segment. When you do this, DL/I deletes all the
dependents of that segment. This is exactly what you want DL/I to do—there is no
reason to keep such segments as ILLNESS and TREATMNT for Evelyn Parker if
she is no longer one of the clinic’s patients.
Before you can delete the patient segment, you have to retrieve it:
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);
To delete this patient’s database record, you issue a DLET command and use the
FROM option to give the name of the I/O area that contains the segment you want
deleted:
EXEC DLI DLET SEGMENT(PATIENT) FROM(PATAREA);
When you issue this command, the PATIENT segment, and its dependents—the
ILLNESS, TREATMNT, BILLING, PAYMENT, and HOUSHOLD segments—are
deleted.
Restrictions
You cannot issue any commands using the same PCB between the retrieval
command and the DLET command, and you can issue only one DLET command for
each GET command.

GN Command
GN Command
The GN command is used to retrieve segments sequentially.
Format
EXEC DLI GET NEXT
GN USING PCB(expression)
(1)
INTO(area)
KEYFEEDBACK(area)
FEEDBACKLEN(expression)

<A> 
<A> For each parent segment (optional):

VARIABLE FIRST SEGMENT(name) SEGLENGTH(expression)
LAST SEGMENT((area))
CURRENT

OFFSET(expression) (2) LOCKED
INTO(area) LOCKCLASS(class)

MOVENEXT(data_value) GETFIRST(data_value) SET(data_value)

SETCOND(data_value) SETZERO(data_value) SETPARENT

WHERE(qualification statement)
(3)
FIELDLENGTH(expression)

KEYS(area)
(4)
KEYLENGTH(expression)
 For the object segment (optional):


GN Command

OFFSET(expression) INTO(area) LOCKED
LOCKCLASS(class)


SETCOND(data_value) SETZERO(data_value)

(3)

KEYS(area)
(4)
Notes:
1 If you leave out the SEGMENT option, specify the INTO option as shown.
2 Specify INTO on parent segments for a path command.
3 If you use multiple qualification statements, specify a length for each, using
FIELDLENGTH. For example: FIELDLENGTH(24,8)
4 You can use either the KEYS option or the WHERE option, but not both on
one segment level.
Options
KEYFEEDBACK(area)
Specifies an area into which the concatenated key for the segment is placed. If
the area is not long enough, the key is truncated.
Specifies the length of the key feedback area into which you want the
concatenated key retrieved. Its argument can be any expression that converts
to the integer data type; you can specify either a number or a reference to a
halfword in your program containing a number. (It is required in COBOL
programs and optional in PL/I and assembler language programs.)
INTO(area)
Specifies an area into which the segment is read.
VARIABLE
FIRST
Specifies that you want to retrieve the first segment occurrence of a segment
type, or that you want to insert a segment as the first occurrence.

GN Command
LAST
Specifies that you want to retrieve the last segment occurrence of a segment
type, or that you want to insert a segment as the last segment occurrence.
CURRENT
Qualifies the command, and specifies that you want to use your current position
at this level and above as qualification for this segment.
SEGMENT(name), SEGMENT((area))
Qualifies the command, specifying the name of the segment type or the area of
your program containing the name of the segment type that you want to
retrieve.
You can have as many levels of qualification for a GN command as there are
levels in the database’s hierarchy. Using fully qualified commands with the
WHERE or KEYS option clearly identifies the hierarchic path and the segment
you want, and is useful in documenting the command. However, you do not
need to qualify a GN command, because you can specify a GN command without
the SEGMENT option.
Once you have established position in the database record, issuing a GN
command without a SEGMENT option retrieves the next segment occurrence in
sequential order.
If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB
retrieves the first occurrence of that segment type it encounters by searching
forward from current position. With an unqualified GN command, the segment
type you retrieve might not be the one you expected, so you should specify an
I/O area large enough to contain the largest segment your program has access
to. (After successfully issuing a retrieval command, you can find out from the
DIB the segment type retrieved.)
If you fully qualify your command with a WHERE or KEYS option, you would
retrieve the next segment in sequential order, as described by the options.
Including the WHERE or KEYS options for parent segments defines the
segment occurrences that are to be part of the path to the segment you want
retrieved. Omitting the SEGMENT option for a level, or including only the
SEGMENT option without a WHERE option, indicates that any path to the
option satisfies the command. DL/I uses only the qualified parent segments and
the lowest-level SEGMENT option to satisfy the command. DL/I does not
assume a qualification for the missing level.
OFFSET(expression)
Specifies the offset to the destination parent. It can be any expression that
converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number. Use OFFSET
when you process concatenated segments in logical relationships. OFFSET is
required whenever the destination parent is a variable-length segment.

GN Command
LOCKED
Specifies that you want to retrieve a segment for the exclusive use of your
program, until a checkpoint or sync point is reached. This option performs the
same function as the Q command code, and it applies to both Fast Path and
full function. A 1-byte alphabetic character of ’A’ is automatically appended as
the class for the Q command code.
LOCKCLASS(class)
program until a DEQ command is issued or until a checkpoint or sync point is
reached. (DEQ commands are not supported for Fast Path.) Class is a 1-byte
alphabetic character (B-J), representing the lock class of the retrieved segment.
For full function code, the LOCKCLASS option followed by a letter (B-J)
designates the class of the lock for the segment. An example is
LOCKCLASS(’B’). If LOCKCLASS is not followed by a letter in the range B to J, then
EXECDLI sets a status code of GL and initiates an ABENDU1041.
Fast Path does not support LOCKCLASS but, for consistency between full function
and Fast Path, you must specify LOCKCLASS(’x’)), where x is a letter in the
range B to J. An example is LOCKCLASS(’B’). If LOCKCLASS is not followed by a
letter in the range B to J, then EXECDLI sets a status code of GL and initiates
an ABENDU1041.
MOVENEXT(data_value)
Specifies a subset pointer to be moved to the next segment occurrence after
your current segment.
GETFIRST(data_value)
Specifies that you want the search to start with the first segment occurrence in
a subset.
SET(data_value)
Specifies unconditionally setting a subset pointer to the current segment.
SETCOND(data_value)
Specifies conditionally setting a subset pointer to the current segment.
SETZERO(data_value)
SETPARENT
Sets parentage at the level you want.
Specifies the length of the field value in a WHERE option.
Specifies the length of the concatenated key when you use the KEYS option. It
can be any expression in the host language that converts to the integer data
type; if it is a variable, it must be declared as a binary halfword value. For IBM
COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language,
KEYLENGTH is optional. For COBOL programs that are not compiled with the
IBM COBOL for MVS & VM (or the VS COBOL II) compiler, you must specify
KEYLENGTH with the KEYS option.
KEYS(area)
Qualifies the command with the segment’s concatenated key. You can use
either KEYS or WHERE for a segment level, but not both.
“Area” specifies an area in your program containing the segment’s
concatenated key.

GN Command
Qualifies the command, specifying the segment occurrence. Its argument is one
or more qualification statements, each of which compares the value of a field in
a segment to a value you supply. Each qualification statement consists of:
v The name of a field in a segment
v The relational operator, which indicates how you want the two values
compared
v The name of a data area in your program containing the value that is
compared against the value of the field
Usage
Use the GN command to sequentially retrieve segments from the database. Each
time you issue a GN command, IMS DB retrieves the next segment, as described by
the options you include in the command. Before issuing a GN command, you should
establish position in the database record by issuing a GU command.
You do not have to use a segment option with a GN command. However, you should
qualify your GN commands as much as possible with the KEYS or WHERE options
after the SEGMENT option.
Examples
Example 1
“We need a list of all patients who have been to this clinic.”
Explanation: To answer this request, your program would issue a command

qualified with the segment name PATIENT until DL/I returned a GB status code to
the program. (GB means that DL/I reached the end of the database before being
able to satisfy your command.). This command looks like this:
EXEC DLI GN
SEGMENT(PATIENT) INTO(PATAREA);
Each time your program issued this command, the current position moves forward
to the next database record.
Example 2
“What are the names of the patients we have seen since the beginning of this
month?”
Explanation: A GN command that includes one or more WHERE or KEYS options

retrieves the next occurrence of the specified segment type that satisfies the
command. To answer this request, the program issues the GN command below until
DL/I returned a GB status code. The example shows the command you use at the
end of April, 1988 (assuming ILLDATE1 contains 198804010):
EXEC DLI GN
SEGMENT(PATIENT) INTO(PATAREA)
SEGMENT(ILLNESS) INTO(ILLAREA) WHERE(ILLDATE>=ILLDATE1);
Example 3
EXEC DLI GN INTO(PATAREA);
Explanation: If you just retrieved the PATIENT segment for patient 04124 and
then issued the above command, you retrieve the first ILLNESS segment for patient
04124.

GN Command
Restrictions
With an unqualified GN command, the retrieved segment type might not be the one
expected. Therefore, specify an I/O area large enough to contain the largest
segment accessible to your program.
Use either the KEYS option or the WHERE option, but not both on one segment
level.
GNP Command
The Get Next in Parent (GNP) command is used to retrieve dependent segments
sequentially.
Format
EXEC DLI GET NEXT IN PARENT
GNP USING PCB(expression)
(1)
INTO(area)
KEYFEEDBACK(area)

<A> 
SEGMENT(name)
VARIABLE FIRST SEGMENT((area)) SEGLENGTH(expression)
LAST
CURRENT




(3)

KEYS(area)
(4)

GNP Command
 For the object segment (optional):


LOCKCLASS(class)



(3)

KEYS(area)
(4)
Notes:
1 If you leave out the SEGMENT option, specify the INTO option as shown.
one segment level.
Options
You can qualify your GNP command by using SEGMENT and WHERE options.
If you do not qualify your command, IMS DB retrieves the next sequential segment
under the established parent. If you include a SEGMENT option, IMS DB retrieves
the first occurrence of that segment type that it finds by searching forward under the
established parent.
You can have as many levels of qualification for a GNP command as there are levels
in the database’s hierarchy. However, you should not qualify your command in a
way that causes DL/I to move off of the segment type you have established as a
parent for the command.
KEYFEEDBACK(area)
the area is not long enough, the key is truncated. Use this to retrieve a
segment’s concatenated key.

GNP Command
INTO(area)
Specifies an area into which the segment is read. Use this to retrieve one or
more segments with one command.
VARIABLE
FIRST
type, or that you want to insert a segment as the first occurrence. Use this to
retrieve the first segment occurrence of a segment type.
LAST
type, or that you want to insert a segment as the last segment occurrence. Use
this to retrieve the last segment occurrence of a segment type.
CURRENT
at this level and above as qualification for this segment. Use this to retrieve a
segment based on your current position.
a number. (SEGLENGTH is required in COBOL programs for any SEGMENT
level that specifies the INTO or FROM option.)
OFFSET(expression)
Specifies the offset to the destination parent. The argument can be any
expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number. Use
OFFSET when you process concatenated segments in logical relationships.
OFFSET is required whenever the destination parent is a variable-length
segment.
LOCKED
program, until a checkpoint or sync point is reached. Use this to reserve a
segment for the exclusive use of your program. This option performs the same
function as the Q command code, and it applies to both Fast Path and full
function. A 1-byte alphabetic character of ’A’ is automatically appended as the
class for the Q command code.
LOCKCLASS(class)

GNP Command
an ABENDU1041.
a subset.
SET(data_value)
SETCOND(data_value)
SETZERO(data_value)
SETPARENT
compared
KEYS(area)
concatenated key.
COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language,
IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify

GNP Command
Qualifies the command, specifying the name of the segment type or the area in
You can have as many levels of qualification for a GNP command as there are
WHERE or KEYS option clearly identifies the hierarchic path and the segment
you want, and is useful in documenting the command. However, you do not
need to qualify a GNP command at all, because you can specify a GNP command
without the SEGMENT option.
Once you have established position in the database record, issuing a GNP
command without a SEGMENT option retrieves the next segment occurrence in
sequential order.
forward from current position. With an unqualified GNP command, the segment
to. (After successfully issuing a retrieval command, you can find out from DIB
the segment type retrieved.)
the lowest-level SEGMENT option to satisfy the command. DL/I does not
Usage
The Get Next in Parent (GNP) command makes it possible to limit the search for a
segment; you can retrieve only the dependents of a particular parent. You must
have established parentage before issuing a GNP command. IMS Version 7
Application Programming: Database Manager explains how to establish parentage.
Examples
Example 1
“We need the complete record for Kate Bailey. Her patient number is 09080.”
Explanation: To satisfy this request, you want only to retrieve the dependent
segments of the patient whose patient number is 09080; you do not want to retrieve
all the dependents of each patient. To do this, use the GU command to establish
your position and parentage on the PATIENT segment for Kate Bailey. Then
continue to issue a GNP without SEGMENT or WHERE options until DL/I returns all
the dependents of that PATIENT segment. (A GE status code indicates that you
have retrieved all the dependent segments.) To answer the request above, your
program could issue these commands:

GNP Command
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA)
WHERE (PATNO=PATNO1);
EXEC DLI GNP
INTO(ILLAREA);
A GNP command without SEGMENT or WHERE options retrieves the first dependent
segment occurrence under the current parent. If your current position is already on
a dependent of the current parent, the above command retrieves the next segment
occurrence under the parent.
With an unqualified GNP command, the segment type you retrieve might not be the
one you expected, so you should specify an I/O area large enough to contain the
largest segment your program has access to. (After successfully issuing a GNP
command, you can find out from the DIB the segment type retrieved.)
Example 2
“Which doctors have been prescribing acetaminophen for headaches?”
Explanation: A GNP command with only a SEGMENT option sequentially retrieves

the dependent segments of the segment type you have specified under the
established parent. Suppose that for this example, the key of ILLNESS is ILLNAME,
and the key of TREATMNT is MEDICINE. You want to retrieve each TREATMNT
segment where the treatment was acetaminophen. The name of the doctor who
prescribed the treatment is part of the TREATMNT segment. (Assume that data
area ILLNAME1 contains HEADACHE, and MEDIC1 contains ACETAMINOP.) To
answer this request, you could issue these commands:
EXEC DLI GN
SEGMENT(ILLNESS) WHERE (ILLNAME=ILLNAME1);
EXEC DLI GNP
SEGMENT(TREATMNT) WHERE (MEDICINE=MEDIC1);
To process this, your program continues issuing the GNP command until DL/I
returned a GE (not found) status code, then your program retrieves the next
headache segment and retrieves the TREATMNT segments for it. Your program
does this until there were no more ILLNESS segments where the ILLNAME was
headache.
Restrictions
The GNP command has the following restrictions:
v You must have established parentage before issuing this command.
v You cannot qualify your GNP command in a way that causes DL/I to move off of
the segment type you have established as the parent for the command.
v You can retrieve only the dependents of a particular parent.
GU Command
The Get Unique (GU) command is used to directly retrieve specific segments, and to
establish a starting position in the database for sequential processing.
Format
EXEC DLI GET UNIQUE
GU USING PCB(expression)

GU Command
INTO(area)
KEYFEEDBACK(area) <A>


<A>:
SEGMENT(name)
VARIABLE LAST SEGMENT((area)) SEGLENGTH(expression)




(2)

KEYS(area)
(3)
:
SEGMENT(name)
VARIABLE LAST SEGMENT((area)) SEGLENGTH(expression)

LOCKCLASS(class)



(2)

KEYS(area)
(3)

GU Command
Notes:
one segment level.
Options
KEYFEEDBACK(area)
INTO(area)
VARIABLE
LAST
type, or that you want to insert a segment as the last segment occurrence.
To retrieve the first occurrence of a segment type, you need only specify the
SEGMENT option. You can specify as many levels of qualification as there are
hierarchic levels defined by the PCB you are using.
To establish position at the beginning of the database, issue a GU command with
a SEGMENT option that names the root segment type.
If you leave out SEGMENT options for one or more hierarchic levels, DL/I
assumes a segment qualification for that level. The qualification that DL/I
assumes depends on your current position.
v If DL/I has a position established at the missing level, DL/I uses the segment
on which position is established.
v If DL/I does not have a position established at the missing level, DL/I uses
the first occurrence at that level.
v If DL/I moves forward from a position established at a higher level, DL/I uses
the first occurrence at the missing level that falls within the new path.

GU Command
v If you leave out a SEGMENT option for the root level, and DL/I has position
established on a root, DL/I does not move from that root when trying to
satisfy the command.
You can have as many levels of qualification for a GU command as there are
WHERE or KEYS option clearly identifies the hierarchic path and the
segment you want, and is useful in documenting the command. However,
you do not need to qualify a GU command at all, because you can specify a
GU command without the SEGMENT option.
Once you have established position in the database record, issuing a GU
command without a SEGMENT option retrieves the next segment occurrence
in sequential order.
If you specify a SEGMENT option without a KEYS or WHERE option, IMS
DB retrieves the first occurrence of that segment type it encounters by
searching forward from current position. With an unqualified GU command, the
segment type you retrieve might not be the one you expected, so you should
specify an I/O area large enough to contain the largest segment your
program has access to. (After successfully issuing a retrieval command, you
can find out from DIB the segment type retrieved.)
option satisfies the command. DL/I uses only the qualified parent segments
and the lowest-level SEGMENT option to satisfy the command. DL/I does not
OFFSET(expression)
Specifies the offset to the destination parent. The argument can be any
expression that converts to the integer data type; you can specify either a
number or a reference to a halfword in your program containing a number. Use
OFFSET when you process concatenated segments in logical relationships.
OFFSET is required whenever the destination parent is a variable-length
segment.
LOCKED
program, until a checkpoint or sync point is reached. This option performs the
same function as the Q command code. It applies to both Fast Path and full
function. A 1-byte alphabetic character of ’A’ is automatically appended as the
class for the Q command code.
LOCKCLASS(class)

GU Command
an ABENDU1041.
a subset.
SET(data_value)
SETCOND(data_value)
SETZERO(data_value)
SETPARENT
Specifies the length of the concatenated key when you use the KEYS option.
The argument can be any expression in the host language that converts to the
integer data type; a variable must be declared as a binary halfword value. For
IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language,
IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify
Use WHERE to further qualify your GU commands after using SEGMENT. If you
fully qualify a GU command, you can retrieve a segment regardless of your
position in the database record.
KEYS(area)
Use KEYS to further qualify your GU commands and specify the segment
occurrence by using its concatenated key.
forward from current position. With an unqualified GU command, the segment
to. (After successfully issuing a retrieval command, you can find out from DIB
the segment type retrieved.)

GU Command
retrieved. Leaving the SEGMENT option out for a level, or including only the
the lowest level SEGMENT option to satisfy the command. DL/I does not
Usage
Use the GU command to retrieve specific segments from the database, or to
establish a position in the database for sequential processing.
You must at least specify the SEGMENT option with a GU command to indicate the
segment type you want to retrieve. (IMS DB retrieves the first occurrence of the
segment you named in the SEGMENT argument.)
When you need to retrieve a specific occurrence of a segment type, you can further
qualify the command by using the WHERE or KEYS option after the SEGMENT
option.
You probably want to further qualify your GU commands with the WHERE or KEYS
option, and specify a specific occurrence of a segment type. If you fully qualify a GU
command, you can retrieve a segment regardless of your position in the database
record.
Examples
Example 1
“What illness was Robert James here for most recently? Was he given any
medication on that day for that illness? His patient number is 05136.”
Explanation: This example requests two pieces of information. To answer the first
part of the request and retrieve the most recent ILLNESS segment, issue this GU
command (assuming that PATNO1 contains 05163):
EXEC DLI GU
SEGMENT(PATIENT) WHERE(PATNO=PATNO1)
SEGMENT(ILLNESS) INTO(AREA);
Once you had retrieved the ILLNESS segment with the date of the patient’s most
recent visit to the clinic, you could issue another command to find out whether he
was treated during that visit. If the date of his most recent visit was January 5,
1988, you could issue the command below to find out whether or not he was
treated on that day for that illness (assuming PATNO1 contains 05163, and DATE1
contains 19880105):
EXEC DLI GU
SEGMENT(ILLNESS) WHERE(ILLDATE=DATE1)
SEGMENT(TREATMNT) INTO(TRTAREA) WHERE(DATE=DATE1);
Example 2
“What is Joan Carter currently being treated for? Her patient number is 10320.”
EXEC DLI GU
SEGMENT(ILLNESS) INTO(ILLAREA);

GU Command
Explanation: In this example you want the ILLNESS segment for the patient
whose patient number is 10320.
Example 3
EXEC DLI GU
SEGMENT(PATIENT)
SEGMENT(ILLNESS)
SEGMENT(TREATMNT) INTO(AREA);
Explanation: This example retrieves the first TREATMNT segment and specifies
the three levels of qualification.
Restriction
You must at least specify the SEGMENT option to indicate the segment type you
want to retrieve.
ISRT Command
The Insert (ISRT) command is used to add one or more segments to the database.

ISRT Command
Format
EXEC DLI INSERT 
ISRT USING PCB(expression) <A>
SEGMENT(name)
VARIABLE FIRST SEGMENT((area)) SEGLENGTH(expression)
LAST
CURRENT

(1) MOVENEXT(data_value) GETFIRST(data_value)
FROM(area)

SET(data_value) SETCOND(data_value) SETZERO(data_value)

(2)

KEYS(area)
(3)
 For the object segment (required):

VARIABLE FIRST SEGLENGTH(expression) OFFSET(expression)
LAST

SEGMENT(name)
SETCOND(data_value) SETZERO(data_value) SEGMENT((area))

FROM(area)
Notes:
1 Specify FROM on parent segments for a path command.
3 You can use either the Keys option or the Where option, but not both on one
segment level.
Options

ISRT Command
VARIABLE
FIRST
type, or that you want to insert a segment as the first occurrence. Use FIRST to
insert a segment as a first occurrence of a segment type.
LAST
type, or that you want to insert a segment as the last segment occurrence. Use
LAST to insert a segment as the last occurrence of a segment type.
CURRENT
at this level and above as qualification for this segment. Use CURRENT to
insert a segment based on your current position.
the program containing the name of the segment type that you want to retrieve,
insert, delete, or replace.
You must include at least a SEGMENT option for each segment you want to
add to the database. Unless ISRT is a path command, the lowest level
SEGMENT option specifies the segment being inserted. You cannot use a
WHERE or KEYS option for this level.
If a segment has a unique key, DL/I inserts the segment in its key sequence. (If
the segment does not have a key, or has a non unique key, DL/I inserts it
according to the value specified for the RULES parameter during DBDGEN.
Related Reading: See IMS Version 7 Application Programming: Database
Manager for information about inserting segments with the ISRT call.
If you specify a SEGMENT option for only the lowest level segment, and do not
qualify the parent segments with SEGMENT, WHERE, or KEYS options, you
must make sure that the current position is at the correct place in the database
to insert the segment. The SEGMENT option that DL/I assumes depends on
your current position in the database record:
v If DL/I has a position established at the missing level, DL/I uses the segment
on which position is established.
v If DL/I does not have a position established at the missing level, DL/I uses
the first occurrence at that level.
v If DL/I moves forward from a position established at a higher level, DL/I uses
the first occurrence at the missing level that falls within the new path.
v If you leave out a SEGMENT option for the root level, and DL/I has position
established on a root, DL/I does not move from that root when trying to
satisfy the command.
It is good practice to always provide qualifications for higher levels to establish

the position of the segment being inserted.
If you are inserting a root segment, you need only specify a SEGMENT option.
DL/I determines the correct place for its insertion in the database by the key
taken from the I/O area. If the segment you are inserting is not a root segment,

ISRT Command
but you have just inserted its immediate parent, the segment can be inserted as
soon as it is built in the I/O area just by using a SEGMENT option for it in the
ISRT command. You need not code the parent level segments to establish your
position.
When you specify multiple parent segments, you can mix segments with and
without the WHERE option. If you include only SEGMENT options on parent
segments, DL/I uses the first occurrence of each segment type to satisfy the
command.
Specifies the length of the I/O area from which the segment is obtained. Its
FROM(area)
Use FROM to insert one or more segments with one command.
a subset.
SET(data_value)
SETCOND(data_value)
SETZERO(data_value)
compared
WHERE establishes position on the parents of a segment when you are

inserting that segment. You can do this by specifying a qualification of WHERE
or KEYS for the higher level SEGMENT options.
When you specify multiple parent segments, you can mix segments with and
without the WHERE option. If you include only SEGMENT options on parent
segments, DL/I uses the first occurrence of each segment type to satisfy the
command.

ISRT Command
KEYS(area)
KEYs can be used to qualify a parent segment. Instead of using WHERE, you
can specify KEYS and use the concatenated key of the segment as
qualification. You can use the KEYS option once for each command,
immediately after the highest level SEGMENT option.
concatenated key.
COBOL for MBS & VM (or VS COBOL II), PL/I, or assembler language,
IBM COBOL for MBS & VM (or VS COBOL II) compiler, you must specify
Usage
To add new segments to an existing database, use the ISRT command. When you
issue the ISRT command, DL/I takes the data from the I/O area you have named in
the FROM option and adds the segment to the database. (The initial loading of a
database requires using the LOAD command, instead of the ISRT command.)
Related Reading: The IMS Version 7 Administration Guide: Database Manager

describes the database load programs.
You can use ISRT to add new occurrences of an existing segment type to a HIDAM,
HISAM, or HDAM database. For an HSAM database, you can add new segments
only by reprocessing the whole database or by adding the new segments to the end
of the database.
Before you can issue the ISRT command to add a segment to the database, your
program must build the segment to be inserted in an I/O area. If the segment has a
key, you must place the correct key in the correct location in the I/O area. If field
sensitivity is used, the fields must be in the order defined by the PSB for the
application’s view of the segment.
If you are adding a root segment occurrence, DL/I places it in the correct sequence
in the database by using the key you supply in the I/O area. If the segment you are
inserting is not a root, but you have just inserted its parent, you can insert the child
segment by issuing an insert request qualified with only the segment name. You
must build the new segment in your I/O area before you issue the ISRT request.
You also qualify insert requests with the segment name when you add a new root
segment occurrence. When you are adding new segment occurrences to an
existing database, the segment type must have been defined in the DBD. You can
add new segment occurrences directly or sequentially after you have built them in
the program’s I/O area.
If the segment type you are inserting has a unique key field, the location where DL/I
adds the new segment occurrence depends on the value of its key field. If the

ISRT Command
segment does not have a key field, or if the key is not unique, you can control
where the new segment occurrence is added by specifying either the FIRST, LAST,
or HERE insert rule. Specify the rules on the RULES parameter of the SEGM
statement for the database.
Related Reading: For information on performing a DBDGEN, see IMS Version 7

Utilities Reference: Database and Transaction Manager.
Examples
Example 1
“Add information to the record for Chris Edwards about his visit to the clinic on
February 1, 1993. His patient number is 02345. He had a sore throat.”
Explanation: First, build the ILLNESS segment in your program’s I/O area. Your
I/O area for the ILLNESS segment looks like this:
19930201SORETHROAT
Use the command to add this new segment occurrence to the database is:
EXEC DLI ISRT
SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) FROM(ILLAREA);
Example 2
“Add information about the treatment to the record for Chris Edwards, and add
information about the illness.”
Explanation: You build the TREATMNT segment in a segment I/O area. The
TREATMNT segment includes the date, the medication, amount of medication, and
the doctor’s name:
19930201MYOCINbbb0001TRIEBbbbbb&b
The following command adds both the ILLNESS segment and the TREATMNT
segment to the database:
EXEC DLI ISRT
SEGMENT(PATIENT) WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) FROM(ILLAREA)
SEGMENT(TREATMNT) FROM(TRETAREA);
Example 3
EXEC DLI ISRT
SEGMENT(ILLNESS) KEYS(CONKEY)
Explanation: Using this command is the same as having a WHERE option

qualified on the key field for the ILLNESS and PATIENT segments.
Restrictions
The following restrictions apply to the ISRT command:
v You cannot issue the ISRT command until you have built a new segment in the
I/O area.
v You must specify at least one SEGMENT option for each segment being added
to the database.
v When inserting a segment, you must have position established on the parents of
the segment.

ISRT Command
v If you specify a SEGMENT option for only the lowest level segment, and do not
qualify the parent segments with SEGMENT, WHERE, or KEYS options, be sure
that current position is at the correct place in the database to insert the segment.
v If you use a FROM option for a segment, you cannot qualify the segment by
using the WHERE or KEYS option; DL/I uses the key field value specified in the
I/O area as qualification.
v You must use a separate I/O area for each segment type you want to add.
v You cannot mix SEGMENT options with and without the FROM option. When you
use a FROM option for a parent segment, you must use a FROM option for each
dependent segment. (You can begin the path at any level, but you must not leave
out any levels.)
v You can only use the FIRST option with segments that have either no keys or
have a non unique key with HERE specified on the RULES operand of the
SEGM statement in the DBD.
v You can only use the LAST option when the segment has no key or a non
unique key, and the INSERT rule for the segment is either FIRST or HERE.
POS Command
The Position (POS) command retrieves the location of either a dependent or the last
inserted sequential dependent segment.
Format
EXEC DLI POSITION USING PCB(n) INTO(data_area)
POS

KEYFEEDBACK(area) SEGMENT(name)
FEEDBACKLEN(expression) SEGMENT((area))

WHERE(qualification_statement)
Options
USING PCB(n)
INTO(data_area)
KEYFEEDBACK(area)
halfword in your program containing a number. (FEEDBACKLEN is required in
COBOL programs and optional in PL/I and assembler language programs.)

POS Command
SEGMENT(name)
SEGMENT((area))
the command.
a segment to a value you supply.
Usage
Use the POS command to:
v Retrieve the location of a specific sequential dependent segment, including the
last one inserted
v Determine the amount of unused space within each DEDB area
If the area specified by the POS command is unavailable, the I/O area is unchanged
and an FH status code is returned.
Restriction
The POS command is for DEDBs only.
REPL Command
The Replace (REPL) command is used to replace a segment, usually to change the
values of one or more of its fields.

REPL Command
Format
EXEC DLI REPLACE 
REPL USING PCB(expression) <A>
SEGMENT(name)
VARIABLE SEGMENT((area)) SEGLENGTH(expression)
FROM(area)
OFFSET(expression) MOVENEXT(data_value)

 For the object segment (required):
SEGMENT(name)
VARIABLE SEGMENT((area)) SEGLENGTH(expression)
FROM(area)
OFFSET(expression) MOVENEXT(data_value)

Options
VARIABLE
SEGMENT(name)
SEGMENT((area))
the command.

REPL Command
OFFSET(expression)
Specifies the offset to the destination parent. It can be any expression that
converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number. You use OFFSET
when you process concatenated segments in logical relationships. It is required
whenever the destination parent is a variable length segment.
FROM(area)
Specifies an I/O area containing the segment to be added, replaced or deleted.
You can replace more than the segment by including the FROM option after the
corresponding SEGMENT option for each segment you want to replace.
Including FROM options for one or more parent segments is called a path
command.
The argument following FROM identifies an I/O area that you have defined in
your program. You must use a separate I/O area for each segment type you
want to replace.
SET(data_value)
SETCOND(data_value)
SETZERO(data_value)
Usage
You must qualify the REPL command with at least one SEGMENT and FROM option,
which together indicate the retrieved segments you want replaced.
If the Get command that preceded the REPL command was a path command, and
you do not want to replace all of the retrieved segments or the PSB does not have
replace sensitivity for all of the retrieved segments, you can indicate which of the
segments are not to be replaced by omitting the SEGMENT option.
If your program attempts to do a path replace of a segment where it does not have
replace sensitivity, the data for the segment in the I/O area for the REPL command
must be the same as the segment returned on the preceding GET command. If the
data changes in this situation, the transaction is abended and no data is changed
as a result of the Replace command.
Notice that the rules for a REPL path command differ from the rules for an ISRT path
command. You cannot skip segment levels to be inserted with an ISRT command,
as you can with a REPL command.
To update information in a segment, you can use the REPL command. The REPL
command replaces data in a segment with data you supply in your application
program. First, you must retrieve the segment into an I/O area. You then modify the
information in the I/O area and replace the segment with the REPL command. For
your program to successfully replace a segment, that segment must already have
been defined as replace-sensitive in the PCB by specifying PROCOPT=A or
PROCOPT=R on the SENSEG statement in the PCB.

REPL Command
Related Reading: For more information, see IMS Version 7 Utilities Reference:
System.
You cannot issue any commands using the same PCB between a Get command
and the REPL command, and you can issue only one REPL command for each Get
command.
Examples
Example 1
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA);
Explanation: This example shows that you cannot issue any commands using the
same PCB between the Get command and the REPL command, and you can issue
only one REPL command for each Get command. If you issue the above commands
and wanted to modify information in the segment again, you must first reissue the
GU command, before reissuing the REPL command.
Example 2
“We have received a payment for $65.00 from a patient whose ID is 08642. Update
the patient’s billing record and payment record with this information, and print a
current bill for the patient.”
Explanation: The four parts to satisfying this processing request are:

1. Retrieve the BILLING and PAYMENT segments for the patient.
2. Calculate the new values for these segments by subtracting $65.00 from the
value in the BILLING segment, and adding $65.00 to the value in the PAYMENT
segment.
3. Replace the values in the BILLING and PAYMENT segments with the new
values.
4. Print a bill for the patient, showing the patient’s name, number, address, the
current amount of the bill, and the amount of the payments to date.
To retrieve the BILLING and PAYMENT segments, issue a GU command. Because

you also need the PATIENT segment when you print the bill, you can include INTO
following the SEGMENT options for the PATIENT segment and for the BILLING
segment:
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1)
SEGMENT(BILLING) INTO(BILLAREA)
SEGMENT(PAYMENT) INTO(PAYAREA);
After you have calculated the current bill and payment, you can print the bill, then
replace the billing and payment segments in the database. Before issuing the REPL
command, you must change the segments in the I/O area.
Because you have not changed the PATIENT segment, you do not need to replace
it when you replace the BILLING and PAYMENT segments. To indicate to DL/I that
you do not want to replace the PATIENT segment, you do not specify the
SEGMENT option for the PATIENT segment in the REPL command.
EXEC DLI REPL
SEGMENT(BILLING) FROM(BILLAREA)
SEGMENT(PAYMENT) FROM(PAYAREA);

REPL Command
This command tells DL/I to replace the BILLING and PAYMENT segments, but not
to replace the PATIENT segment.
These two examples are called path commands. You use a path REPL command to
replace more than one segment with one command.
Example 3
“Steve Arons, patient number 10250, has moved to a new address in this town. His
new address is 4638 Brooks Drive, Lakeside, California. Update the database with
his new address.”
Explanation: You need to retrieve the PATIENT segment for Steve Arons and
replace the address portion of the segment. To retrieve the PATIENT segment, you
can use this GU command (assuming PATNO1 contains 10250):
EXEC DLI GU
SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);
Since you are not replacing the first two fields of the PATIENT segment (PATNO
and NAME), you do not have to change them in the I/O area. Place the new
address in the I/O area following the PATNO and NAME fields. Then you issue the
following REPL command:
EXEC DLI REPL
SEGMENT(PATIENT) FROM(PATAREA);
Example 4
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA)
WHERE (PATNO=PATNO1)
SEGMENT(ILLNESS) INTO(ILLAREA)
SEGMENT(TREATMNT) INTO(TRETAREA);
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA)
Explanation: This example assumes that you want to replace the PATIENT and
TREATMNT segments for patient number 10401, but you do not want to change the
ILLNESS segment. To do this issue the above command (assuming PATNO1
contains 10401).
Restrictions
The following restrictions apply to the REPL command:
v You cannot issue any commands using the same PCB between the Get
command and the REPL command.
v You can issue only one REPL command for each Get command.
v To modify information in a segment, you must first reissue the GU command
before reissuing the REPL command.
v You must qualify the REPL command with at least one SEGMENT option and one
FROM option.
v If you use a FROM option for a segment, you cannot qualify the segment by
using the WHERE or KEYS option; DL/I uses the key field value specified in the
I/O area as qualification.
RETRIEVE Command
Use the RETRIEVE command to determine current position in the database in batch
and BMP programs.

RETRIEVE Command
Format
EXEC DLI RETRIEVE USING PCB(expression) KEYFEEDBACK(area)
Options
expression specifies the PCB for which you want to retrieve the concatenated
key. It can be any expression in the host language that converts to the integer
data type. You can specify either a number or a reference to a halfword
containing a number. The value must be a positive integer not greater than the
number of PCBs generated for the PSB. The first PCB in the list, the I/O PCB,
is 1. The first DB PCB in the list is 2, the second is 3, and so forth.
KEYFEEDBACK(area)
expression is the length of the key feedback I/O area. It can be any expression
in the host language that converts to integer data type; you can specify either a
number or a reference to a halfword containing a number. For IBM COBOL for
MVS & VM (or VS COBOL II), PL/I, or assembler language, FEEDBACKLEN is
optional. For COBOL programs that are not compiled with the IBM COBOL for
MVS & VM (or VS COBOL II) compiler, you must specify FEEDBACKLEN with
the KEYFEEDBACK option.
Usage
If your program issues symbolic checkpoint commands it must also issue the
extended RESTART (XRST) command or the RETRIEVE command. The RETRIEVE
command is issued once, at the start of your program. You can use the RETRIEVE
command to start your program normally, or to restart it in case of an abnormal
termination.
You can use the RETRIEVE command from a specific checkpoint id or a time/date
stamp. Because the RETRIEVE command attempts to reposition the database, your
program also needs to check for correct position.
After issuing the RETRIEVE command, the segment type and level on which the
position is established is returned to the DIBSEGM and DIBSEGLV fields in the
DIB. The value in DIBKFBL is set to the actual length of the concatenated key. The
DIBSTAT field contains the value returned from the GU repositioning, not the XRST
command.

RETRIEVE Command
The RESTART command attempts to reposition DL/I databases by issuing an
internal GU qualified with the concatenated key. It is your responsibility to verify that
your position in the database from the GU repositioning is the correct position for the
checkpoint ID used in the XRST command. You can use the RETRIEVE command to
retrieve the concatenated key used with the GU repositioning, and determine your
current position in all the PCBs your program accesses.
Examples
EXEC DLI RETRIEVE USING PCB(2) KEYFEEDBACK(KEYAREA);
EXEC DLI RETRIEVE USING PCB(5) KEYFEEDBACK(KEYAREA);
Explanation
These RETRIEVE commands retrieve the concatenated key for the first and fourth DB
PCBs. (The first PCB in the list is the I/O PCB, so the first DB PCB is the second
one in the list.) After issuing the first RETRIEVE command, you can determine your
position in the first DB PCB by examining the concatenated key in KEYAREA, and
the values returned in the DIBSEGM and DIBSEGLV fields in the DIB. After issuing
the second RETRIEVE command, you can determine your position in the fourth DB
PCB by examining the same fields.
Restrictions
The following restrictions apply to the RETRIEVE command:
v You cannot use this command in a CICS program.
v To use this command, you must first define an I/O PCB for your program.
v You cannot reestablish position in the midst of non unique keys or non keyed
segments.
v You cannot use this command unless the system log is stored on direct access
storage and dynamic backout has been specified. You must also specify BKO=Y
in the parm field of your JCL when you execute the program.
SCHD Command
The Schedule (SCHD) command is used to schedule a PSB in a CICS online
program. For information on the I/O PCB, see “Using the I/O PCB, PSB, and PCB”
on page 11.
Format
EXEC DLI SCHEDULE PSB(name)
SCHD PSB((area)) SYSSERVE NODHABEND
Options
PSB(name)
Specifies the name of the PSB available to your application program that you
want to schedule with the SCHD command.
PSB((area))
Specifies an 8-byte data area in your program that contains the name of the
PSB available to your program that you want to schedule with the SCHD
command.

SCHD Command
SYSSERVE
Specifies that the application program can handle an I/O PCB and might issue
a system service request in the logical unit of work (LUW).
NODHABEND
Specifies that a CICS transaction does not fail with a DHxx abend.
Should a schedule fail under EXEC DLI, a status code might be returned in the
DIB, causing a CICS transaction to fail with a DHxx abend. This option prevents
this. Following an unsuccessful SCHD command, the control, as well as the
status code in the DIB are passed back to the application program, which can
then take the appropriate action.
Usage
Before you can access DL/I databases from a CICS program, you must notify DL/I
that your program will be accessing a database by scheduling a PSB. Do this by
issuing the SCHD command. When you no longer plan to use a PSB, or you want to
schedule a subsequent PSB (one or more), you must terminate the previous PSB
with the TERM command. (For more information on the I/O PCB and PSB, see
“Using the I/O PCB, PSB, and PCB” on page 11)
The SCHD command can be specified two ways (see the examples below).
Examples
EXEC DLI SCHD PSB(psbname)SYSSERVE;
EXEC DLI SCHD PSB((AREA));
Explanation
These examples show two ways to schedule a PSB in a CICS program.
TERM Command
The Terminate (TERM) command is used to terminate a PSB, in a CICS online
program.
Format
EXEC DLI TERMINATE
TERM
Options
No options are allowed with the TERM command.
Usage
If you want to use a PSB other than the one already scheduled, use the TERM
command to release the PSB.
When you issue the TERM command, all database changes are committed and
cannot be backed out. Because returning to CICS also terminates the PSB and
commits changes, you need not use the TERM command unless you want to
schedule another PSB, or commit database changes before returning to CICS.

TERM Command
No options are allowed with the TERM command. If your program subsequently
needs a PSB that has terminated, it must reschedule that PSB by issuing another
SCHD command.
In most applications, you do not need to use the TERM command.
Example
EXEC DLI TERM
Explanation
This example shows how to terminate a PSB with the TERM command.
System Service Commands

The following system service commands require that you first issue the SCHD
command with the SYSSERVE keyword:
v “ACCEPT Command” on page 49
v “DEQ Command” on page 50
v “LOG Command” on page 52
v “QUERY Command” on page 53
v “REFRESH Command” on page 54
v “ROLS Command” on page 57
v “SETS Command” on page 58
v “SETU Command” on page 59
v “STAT Command” on page 60
The following system service commands are valid in batch or BMP without first
issuing the SCHD command with the SYSSERVE keyword:
v “CHKP Command” on page 49
v “ROLB Command” on page 55
v “ROLL Command” on page 56
v “SYMCHKP Command” on page 61
v “XRST Command” on page 63
The following system service commands are valid in an online CICS program using
DBCTL:
v ACCEPT
v DEQ
v LOG
v QUERY
v REFRESH
v ROLS
v SETS
v STAT
To issue system service commands, the input/output PCB (I/O PCB) is required. For
detailed information on the I/O PCB, as well as the PSB, and PCB, see “Using the
I/O PCB, PSB, and PCB” on page 11.

ACCEPT Command
ACCEPT Command
The Accept (ACCEPT) command is used to tell IMS to return a status code to your
program, rather than abend the transaction.
Format
EXEC DLI ACCEPT STATUSGROUP('A')
ACCEPT STATUSGROUP('B')
Options
STATUSGROUP('A')
Informs IMS that the application is prepared to accept status codes regarding
unavailability. IMS then returns a status code instead of pseudoabending if a
call issued later requires access to unavailable data.
2 STATUSGROUP('B')
2 Informs IMS that the application is prepared to accept status codes regarding
2 unavailability and deadlock occurrence. IMS returns a status code instead of
2 pseudoabending if a call issued later requires access to unavailable data or
2 deadlock occurrence.
Usage
Use the ACCEPT command to tell IMS to return a status code instead of abending
the program. These status codes result because PSB scheduling completed without
all of the referenced databases being available.
Example
EXEC DLI ACCEPT STATUSGROUP('A');
This example shows how to specify the ACCEPT command.
CHKP Command
The Checkpoint (CHKP) command is used to issue a basic checkpoint and to end a
logical unit of work. You cannot use this command in a CICS program.
Format
EXEC DLI CHECKPOINT ID(area)
CHKP ID(’literal’)
Options
ID(area)
Contains the checkpoint ID. Specifies the name of an area in your program
containing the checkpoint ID. The area pointed to is eight bytes. If you are
using PL/I, specify this option as a pointer to a major structure, an array, or a
character string.

CHKP Command
ID('literal')
'literal' is an 8-byte checkpoint ID, enclosed in quotation marks. In CHKP
commands the area pointed to is 8 bytes long.
Usage
The two kinds of commands that allow you to make checkpoints are: the CHKP, or
basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Batch programs can use either the symbolic or the basic command.
Both checkpoint commands make it possible for you to commit your program’s
changes to the database and to establish places from which the program can be
restarted, should it terminate abnormally.
You must not use the CHKPT=EOV parameter on any DD statement to take an IMS
checkpoint.
See IMS Version 7 Application Programming: Design Guide for an explanation of

when and why you should issue checkpoints in your program. Both commands
cause a loss of database position at the time the command is issued. Position must
be reestablished by a GU command or other method of establishing position.
It is not possible to re-establish position in the midst of non unique keys or non
keyed segments.
You can issue the basic CHKP command to commit your program’s changes to the
database and establish places from which your program can be restarted. When
you issue a basic CHKP command, you must provide the code for restarting your
program.
When you issue a CHKP command, you specify the ID for the checkpoint. You can
supply either the name of a data area in your program that contains the ID, or you
can supply the actual ID, enclosed in single quotes. See the examples below.
Examples
EXEC DLI CHKP ID(chkpid);
EXEC DLI CHKP ID('CHKP0007');
Explanation
These examples show how to specify the CHKP command.
Restrictions
The following restrictions apply to the CHKP command:
v You cannot use this command in a CICS program, as was stated above.
v You must first define an I/O PCB for your program before you can use the CHKP
command.
v You cannot reestablish position in the midst of non unique keys or non keyed
segments.
DEQ Command
The Dequeue (DEQ) command is used to release a segment that is retrieved with
the LOCKCLASS option.

DEQ Command
Format
EXEC DLI DEQ LOCKCLASS(data_value)
Option
LOCKCLASS(data_value)
Specifies that you want to release the lock that is being held as the result of an
earlier GU, GN, or GNP command that had a LOCKCLASS option with the same
data_value. Data_value must be a 1-byte alphabetic character in the range of B
to J.
For full function, specify the LOCKCLASS option followed by the lock class of
that segment (for example, LOCKCLASS(’B’)). If the option is not followed by a
letter (B-J), EXECDLI sets a status code of GL and initiates an ABENDU1041.
DEQ commands are not supported for Fast Path.
Usage
Use the DEQ command to release locks on segments that were retrieved using the
LOCKCLASS option. Using LOCKCLASS on Get commands allows you to reserve
segments for exclusive use by your transaction. No other transaction is allowed to
update these reserved segments until either your transaction reaches a sync point
or the DEQ command has been issued, thereby releasing the locks on these
reserved segments. The LOCKCLASS option lets your application program leave
these segments and retrieve them later without any changes having been added.
Example
Your program can use the LOCKCLASS option as follows:
EXEC DLI DEQ LOCKCLASS(data_value)
EXEC DLI GU SEGMENT(PARTX)
SEGMENT(ITEM1) LOCKCLASS('B') INTO(PTAREA1);
EXEC DLI GU SEGMENT(PARTX)
SEGMENT(ITEM2) LOCKCLASS('C') INTO(PTAREA2);
EXEC DLI DEQ LOCKCLASS('B');
Explanation
This example shows the format of the DEQ command, where data_value is a 1-byte
alphabetic character in the range B to J. The DEQ command releases the lock that
was gotten and held with a LOCKCLASS of ’B’ for the PARTX segment as a result
of the first GU. The lock that was gotten with a LOCKCLASS of ’C’ on the PARTX
segment during the second GU remains held.
Restriction
The following restriction applies to the DEQ command:
v To use this command you must first define an I/O PCB for your program.
LOAD Command
The Load (LOAD) command is used to add a segment sequentially while loading the
database.

LOAD Command
Format
EXEC DLI LOAD
USING PCB(expression) VARIABLE
SEGMENT(name) FROM(area)
SEGMENT((area)) SEGLENGTH(expression)
Options
Specifies the DB PCB you want to use. Its argument can be any expression
that converts to the integer data type; you can specify either a number or a
reference to a halfword in your program containing a number.
VARIABLE
SEGMENT(name)
Specifies the name of the segment type you want to retrieve, insert, delete, or
replace.
SEGMENT((area))
A reference to an area in your program containing the name of the segment
type. You can specify an area instead of the name of the segment in the
command.
FROM(area)
Usage
The LOAD command is used for database load programs, which are described in
IMS Version 7 Administration Guide: Database Manager.
Example
EXEC DLI LOAD
SEGMENT(ILLNESS) FROM(ILLAREA);
LOG Command
The Log (LOG) command is used to write information to the system log.

LOG Command
Format
EXEC DLI LOG FROM(area) LENGTH(expression)
Options
FROM(area)
LENGTH(expression)
Specifies the length of an area.
Usage
You use the LOG command to write information to the system log. For detailed
information on this command, see IMS Version 7 Application Programming: Design
Guide.
Example
EXEC DLI LOG
FROM(ILLAREA) LENGTH(18);
Restriction
The following restriction applies to the LOG command:
QUERY Command
The Query (QUERY) command obtains status code and other information in the DL/I
interface block (DIB), which is a subset of the IMS PCB.
Format
EXEC DLI QUERY USING PCB(expression)
Options
USING PCB(expression) is required. No other options are allowed with the QUERY
command.
Usage
For full-function databases, the DIB should contain NA, NU, TH or blanks. For an
explanation of the codes, see “Status Code Explanations” on page 127.
Use the QUERY command after scheduling the PSB but before making the database
call. If the program has already issued a call using the DB PCB, you then use the
REFRESH command to update the information in the DIB.

QUERY Command
Examples
Example 1
EXEC DLI QUERY USING PCB(expression);
Explanation: This example shows how to specify the QUERY command. In this
example, (n) specifies the PCB.
Example 2
EXEC DLI REFRESH DBQUERY;
Explanation: If your program has already issued a call using the DB PCB name,
use the REFRESH command to update the information in the DIB. The REFRESH
command updates all DB PCBs. You can issue it only one time.
Restrictions
The following restrictions apply to the QUERY command:
v You cannot reestablish position in the midst of non-unique keys or non keyed
segments.
REFRESH Command
The Refresh (REFRESH) command is used to obtain the most recent information from
the DIB for the most recently issued command.
Format
EXEC DLI REFRESH DBQUERY
Options
DBQUERY is required. Other options are not allowed with the REFRESH command.
Usage
The REFRESH command is used with the QUERY command.
The QUERY command is used after scheduling the PSB but before making the first
database call. If the program has already issued a call using the DB PCB, use the
REFRESH command to update the information in the DIB.
The REFRESH command updates all DB PCBs. It can be issued only once.
Example
EXEC DLI REFRESH DBQUERY;
Explanation
This example shows how to specify the REFRESH command.

REFRESH Command
Restrictions
The following restrictions apply to the REFRESH command:
v To use this command, you must first define an I/O PCB for your program.
segments.
v You can issue this command only one time.
ROLB Command
The Roll Back (ROLB) command is used to dynamically back out changes and return
control to your program. You cannot use this command in a CICS program.
Format
EXEC DLI ROLB
Options
No options are allowed with the ROLB command.
Usage
When a batch or BMP program determines that some of its processing is invalid,
two commands make it possible for the program to remove the effects of its
inaccurate processing. These are the rollback commands, ROLL (see “ROLL
Command” on page 56) and ROLB.
The ROLB command is valid in batch programs when the system log is stored on
direct access storage and dynamic backout has been specified through the use of
the BKO execution parameter.
Issuing the ROLB causes IMS DB to back out any changes your program has made
to the database since its last checkpoint, or since the beginning of the program if
your program has not issued a checkpoint. When you issue a ROLB command, IMS
DB returns control to your program after backing out the changes, so that your
program can continue processing with the next statement after the ROLB command.
Example
EXEC DLI ROLB;
Explanation
This example shows how to dynamically back out changes and return control to
your program with the ROLB command.
Restrictions
The following restrictions apply to the ROLB command:
v You must first define an I/O PCB for your program before you can use this
command.

ROLB Command
segments.
v You cannot use this command when the system log is stored on direct access
storage and dynamic backout has not been specified.
ROLL Command
The Roll (ROLL) command is used to dynamically back out changes. You cannot use
this command in a CICS program
Format
EXEC DLI ROLL
Options
No options are allowed with the ROLL command.
Usage
When a batch program determines that some of its processing is invalid, two
commands make it possible for the program to remove the effects of its inaccurate
processing. These are the rollback commands, ROLL and ROLB (see “ROLB
Command” on page 55).
You can use ROLL in batch programs.
Issuing the ROLL causes CICS and DL/I to back out any changes your program has
made to the database since its last checkpoint, or since the beginning of the
program provided your program has not issued a checkpoint. When you issue a
ROLL command, DL/I terminates your program after backing out the updates.
Example
EXEC DLI ROLL;
Explanation
This example shows how to dynamically back out changes with the ROLL command.
If you use the ROLL command, IMS terminates the program with user abend code
U0778. This type of abnormal termination does not produce a storage dump.
Restrictions
The following restrictions apply to the ROLL command:
v You must first define an I/O PCB for your program before you can use this
command.
segments.

ROLS Command
ROLS Command
The Roll Back to SETS or SETU (ROLS) command is used to back out to a
processing point set by an earlier SETS command.
Format
EXEC DLI ROLS USING PCB(expression)
TOKEN(token) AREA(data_area)
Options
TOKEN(token)
A 4-byte token associated with the current processing point. If you specify both
TOKEN and AREA, the ROLS command backs out to the SETS or SETU you
specified.
AREA(data_area)
The name of the area to be restored to the program when a ROLS command is
issued. The first 2 bytes of the data-area field contain the length of the
data-area, including the length itself. The second 2 bytes must be set to
X'0000'. If you specify both TOKEN and AREA, the ROLS command backs out to
the SETS you specified.
The ROLS call has two formats: with TOKEN and AREA (for IOPCB only) and without
TOKEN and AREA (for IOPCB or DBPCB).
Usage
Use the SETS and ROLS commands to define multiple points at which to preserve the
state of DL/I full-function databases and to return to these points later. (For
example, you can use them so your program can handle situations that can occur
when PSB scheduling completes without all of the referenced DL/I databases being
available.)
Use of the SETS and ROLS commands apply only to DL/I full-function databases. This
means that if a logical unit of work (LUW) is updating types of recoverable
resources other than full-function databases, for example, VSAM files, the SETS and
ROLS requests have no effect on the non-DL/I resources. The backout points are not
CICS commit points; they are intermediate backout points that apply only to DBCTL
resources. It is up to you to ensure the consistency of all the resources involved.
You can use the ROLS command to backout to the state all full-function databases
were in before either a specific SETS or SETU request or the most recent commit
point.
Examples
Example 1
EXEC DLI ROLS TOKEN(token1) AREA(data_area)

ROLS Command
Explanation: In this example (for IOPCB only), backout takes place to the
corresponding TOKEN, as specified by a prior SETS call, and control returns to the
application.
Example 2
EXEC DLI ROLS USING PCB(PCB5)
Explanation: In this example, for IOPCB or DBPCB, backout takes place to the
prior sync point and the application is pseudo-abended with a U3033, status code.
Control does not return to the application.
In this example, PCB5 is the number of a DB PCB that has received a 'data
unavailable' status code. This command results in the same action that would have
occurred had the program not issued an ACCEPT STATUSGROUPA command.
(See Chapter 7, “Using Data Availability Enhancements”, on page 109.)
Example 3
EXEC DLI ROLS
Explanation: In this example, for IOPCB or DBPCB, backout takes place to the
prior sync point and the application is pseudo-abended with a U3033, provided the
previous reference to that PCB gave an unavailable status code. Control does not
return to the application.
Restrictions
The following restrictions apply to the ROLS command:
segments.
SETS Command
The Set a Backout Point (SETS) command is used to define points in your
application at which to preserve the state of the DL/I databases before initiating a
set of DL/I requests to perform a function. Your application can issue a ROLS
command later if it cannot complete the function.
Format
EXEC DLI SETS
TOKEN(mytoken) AREA(data_area)
Options
TOKEN(mytoken)
A 4-byte token associated with the current processing point.
AREA(data_area)
The name of the area to be restored to the program when a SETS command is

SETS Command
X'0000'.
Usage
You can use the SETS command to define multiple points at which to preserve the
state of the DL/I databases and to return to these points later. For example, you
can use the SETS command to allow your program to handle situations that can
occur when PSB scheduling completed without all of the referenced DL/I databases
being available.
The SETS command applies only to DL/I full-function databases. If a logical unit of
work (LUW) is updating types of recoverable resources other than full-function
databases, for example VSAM files, the SETS command has no effect on the
non-DL/I resources. The backout points are not CICS commit points; they are
intermediate backout points that apply only to DBCTL resources. It is up to you to
ensure the consistency of all the resources involved.
Example
EXEC DLI SETS TOKEN(mytoken) AREA(data_area)
Explanation
This example shows how to specify the SETS command.
Restrictions
The following restrictions apply to the SETS command:
segments.
v In batch, you can only use this command when the system log is stored on direct
access storage and dynamic backout has been specified. You must also specify
BKO=Y in the parm field of your JCL when you execute the program.
v It is rejected when the PSB contains a DEDB or MSDB PCB, or when the call is
made to a DB2 database.
v It is valid, but not functional, if unsupported PCBs exist in the PSB or if the
program uses an external subsystem.
SETU Command
The Set a Backout Point Unconditionally (SETU) command is identical to the SETS
command except that it does not get rejected if unsupported PCBs are in the PSB
or if the program uses an external subsystem.
Format
EXEC DLI SETU
TOKEN(mytoken) AREA(data_area)

SETU Command
Options
TOKEN(mytoken)
A 4-byte token associated with the current processing point.
AREA(data_area)
The name of the area to be restored to the program when a SETU command is
X'0000'.
Usage
You can use the SETU command to define multiple points at which to preserve the
state of the DL/I databases and to return to these points later. For example, you
can use the SETU command to allow your program to handle situations that can
occur when PSB scheduling completed without all of the referenced DL/I databases
being available.
The SETU command applies only to DL/I full-function data bases. If a logical unit of
work (LUW) is updating types of recoverable resources other than full-function
databases, such as VSAM files, the SETU command has no effect on the non-DL/I
resources. The backout points are not CICS commit points; they are intermediate
backout points that apply only to DBCTL resources. It is up to you to ensure the
consistency of all the resources involved.
Example
EXEC DLI SETU TOKEN(mytoken) AREA(data_area)
Explanation
This example shows how to specify the SETU command.
Restrictions
The following restrictions apply to the SETU command:
v You cannot reestablish position in the midst of non-unique keys or non-keyed
segments.
STAT Command
This section contains programming interface information.
The Statistics (STAT) command is used to obtain IMS database statistics that you
can use in debugging your program.

STAT Command
Format
EXEC DLI STATISTICS INTO(area)
STAT USING PCB(expression)
VSAM FORMATTED

LENGTH(expression) NONVSAM UNFORMATTED
SUMMARY
Options
INTO(area)
Specifies an area into which the data is read.
LENGTH(expression)
Specifies the length of an area.
VSAM/NONVSAM
Specifies database type.
FORMATTED/UNFORMATTED/SUMMARY
Specifies type of output.
Usage
The STAT command is described in IMS Version 7 Application Programming: Design
Guide.
Examples
For examples of the STAT command, see IMS Version 7 Application Programming:
Database Manager.
SYMCHKP Command
The Symbolic Checkpoint (SYMCHKP) command is used to issue a symbolic
checkpoint and to end a logical unit of work.
Format
EXEC DLI SYMCHKP ID(chkpid)
ID('literal')

AREA#(area#)LENGTH#(expression#)

SYMCHKP Command
Options
ID(chkpid)
Is the name of an 8-byte area in your program containing the checkpoint ID. If
you are using PL/I, specify this parameter as a pointer to a major structure, an
array, or a character string.
ID('literal')
Is the 8-byte checkpoint ID, enclosed in quotation marks.
AREA#(area#)
Specifies the areas in your program you want IMS to checkpoint. You do not
need to specify any area to checkpoint; however, you cannot specify more than
seven areas. If you specify more than one area, you must include all
intervening areas. For example, if you specify AREA3, you must also specify
AREA1 and AREA2. The areas you specify using the SYMCHKP command must
be the same and in the areas specified in the XRST command.
LENGTH#(expression#)
Can be any expression in the host language that converts to the integer data
type; you can specify either a number or a reference to a halfword containing a
number. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler
language programs, LENGTH1 to LENGTH7 are optional. For COBOL
programs that are not compiled with the IBM COBOL for MVS & VM (or VS
COBOL II) compiler, LENGTHx (where x is 1 to 7) is required for each AREAx
(where x is 1 to 7) that you specify.
Usage
basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Batch programs can use either the symbolic or the basic command.
changes to the database and to establish places from which the program can be
restarted, should it terminate abnormally. You must not use the CHKPT=EOV
parameter on any DD statement to take an IMS checkpoint.
Refer to IMS Version 7 Application Programming: Design Guide for an explanation

of when and why you should issue checkpoints in your program. Both commands
cause a loss of database position at the time the command is issued. Position must
be reestablished by a GU command or other method of establishing position.
In addition to committing your program’s changes to the database and establishing

places from which your program can be restarted, the Symbolic Checkpoint
command:
v Works with the Extended Restart (XRST) command to restart your program if it
terminates abnormally.
v Can save as many as seven data areas in your program, which are restored
when your program is restarted. You can save variables, counters, and status
information.

SYMCHKP Command
Example
EXEC DLI SYMCHKP
ID(chkpid)
AREA1(area1) LENGTH1(expression1)
...
Explanation
This example shows how to issue a symbolic checkpoint and to end a logical unit of
work with a SYMPCHKP command.
Restrictions
The following restrictions apply to the SYMCHKP command:
v If you issue this command, you must also issue the XRST command.
v To use the SYMCHKP command you must first define an I/O PCB for your program.
segments.
v The areas you specify using the SYMCHKP command must be the same, and in the
same order, as the areas specified in the XRST command.
v If you specify more than one area, you must specify all intervening areas. For
example, if you specify AREA3, you must also specify AREA1 and AREA2.
v When specifying expression1 with a COBOL program that is not compiled with
the IBM COBOL for MVS & VM (or the VS COBOL II) compiler, LENGTHx
(where x is 1 to 7) is required for each AREAx (where x is 1 to 7) that you
specify.
XRST Command
The Extended Restart (XRST) command is used to issue an extended restart, and to
perform a normal start or an extended restart from a checkpoint ID or time/date
stamp. If you use Symbolic Checkpoint commands in your program, you must use
the XRST command.
Format
EXEC DLI XRST
MAXLENGTH(expression) ID(chkpid)
ID('literal')

AREA#(area#)LENGTH#(expression#)
Options
MAXLENGTH(expression)
Specifies the length of an area from which a program is restarted. This
parameter is the longest segment in the PSB, or of all the segments in a path, if

XRST Command
you use path commands in your program. It can be any expression in the host
language that converts to the integer data type. You can specify either a
number or a reference to a halfword containing a number. MAXLENGTH is not
required, and defaults to 512 bytes.
ID(chkpid) ID('literal')
This parameter is either the name of a 30-byte area in your program or a
30-byte checkpoint ID, enclosed in quotes. This parameter is optional; you can
specify a checkpoint ID or a time/date stamp in the parm field of your JCL
instead. If you specify both, IMS uses the value in the parm field of the EXEC
statement. If you are starting your program normally, do not specify a
checkpoint ID, or ensure that the field pointed to by the chkpid contains blanks.
If your program is restarted and the CKPTID= value in the PARM field of the
EXEC statement is not used, then the right most bytes beyond the checkpoint
ID being used in the I/O area must be set to blanks.
You can issue a XRST command after supplying a time/date stamp of
IIIIDDDHHMMSST, or from a specific checkpoint in your program by supplying a
checkpoint ID. IIIIDDD is the region ID and day; HHMMSST is the actual time in
hours, minutes, seconds, and tenths of seconds. The system message
DFS0540I supplies the checkpoint ID and time/date stamp.
If you are using PL/I, specify chkpid as a pointer to a major structure, an array,
or a character string.
AREA#(area#)
Area# specifies the first area in your program you want to restore. You can
specify up to seven areas. You are not required to specify any areas; however,
if you specify more than one area, you must include all intervening areas. For
example, if you specify AREA3, you must also specify AREA1, and AREA2. The
areas you specify on the XRST command must be the same—and in the same
order—as the areas you specify on the SYMCHKP command. When you restart
the program, only the areas you specified in the SYMCHKP command are
restored.
LENGTH#(expression#)
Specifies the length of an area from which a program is restarted. Its argument
type; you can specify either a number or a reference to a halfword containing a
number. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler
language programs LENGTH1 to LENGTH7 are optional. For COBOL programs
that are not complied with the IBM COBOL for MVS & VM (or VS COBOL II)
compiler, LENGTHx (where x is 1 to 7) is required for each AREAx (where x is
1 to 7) that you specify. Each qualification statement consists of:
compared
Usage
If your programs issues Symbolic Checkpoint commands it must also issue the
Extended Restart (XRST) command. The XRST is issued once, at the start of your
program. You can use the XRST command to start your program normally, or to
extend restart it in case of an abnormal termination.

XRST Command
You can extend restart your program from a specific checkpoint ID, or a time/date
stamp. Because the XRST attempts to reposition the database, your program also
needs to check for correct position.
After issuing the XRST command, you should test the DIBSEGM field in the DIB.
After a normal start, the DIBSEGM field should contain blanks. At the completion of
an Extended Restart, the DIBSEGM field will contain a checkpoint ID. Normally,
XRST will return the 8-byte symbolic checkpoint ID, followed by 4 blanks. If the
8-byte ID consists of all blanks, then XRST will return the 14-byte timestamp ID. The
only successful status code for an XRST command is a blank status code. If DL/I
detects any error while processing the XRST command, your program abends.
Example
EXEC DLI XRST MAXLENGTH(expression)
ID(chkpid)
...
Explanation
This example shows how to specify the XRST command.
Restrictions
The following restrictions apply to the XRST command:
segments.
v You cannot use this command unless the system log is stored on direct access

XRST Command

Chapter 3. Defining Application Program Elements to IMS
This chapter provides information on the following:
v “Specifying an Application Interface Block (AIB)”
v “Specifying the DL/I Interface Block (DIB)” on page 68
v “Defining a Key Feedback Area” on page 71
v “Defining I/O Areas” on page 71
Specifying an Application Interface Block (AIB)

EXEC DLI commands can use the AIB interface. For example, using the AIB
interface, the format for the GU command would be EXEC DLI GU AIB(aib), instead
of EXEC DLI GU USING PCB(n) using the PCB format.
With CICS Transaction Server 1.1 or later, the following EXEC DLI commands are
supported in the AIB format (as well as the PCB format):
v GU
v GN
v GNP
v ISRT
v DLET
v REPL
v STAT
v POS
v QUERY
v REFRESH
v ACCEPT
v LOG
v DEQ
v SETS
v ROLS
With CICS Transaction Server 1.1 or later, and IMS/ESA Version 5, the following
AIB-only commands are supported via the EXEC DLI interface: ICMD, RCMD and
GMSG.
The CICS EDF debugging transaction supports AIB EXEC DLI requests, just as it
handles PCB type requests.
AIB Mask
The AIB mask must be supplied by the application and referenced in the EXEC call
instead of the PCB number (for example, EXEC DLI GU AIB(aib)).
The DIBSTAT field is set with a valid STATUS code when AIBRETRN =
X’00000000’ or x’00000900’. Applications should test AIBRETRN for any other
values and respond accordingly.

Specifying an Application Interface Block (AIB)
CICS Restrictions with AIB support
Restrictions due to function shipping include:
v The AIBLEN field must be between 128 and 256 bytes. 128 is recommended.
v LIST=NO must not be specified on any PCBs in the PSB.
Specifying the DL/I Interface Block (DIB)

Each time your program executes a DL/I command, DL/I returns a status code and
other information to your program through the DL/I interface block (DIB), which is a
subset of IMS PCB. Your program should check the status code to make sure the
command executed successfully.
Each program’s working storage contains its own DIB. The contents of the DIB
reflect the status of the last DL/I command executed in that program. If the
information in your program’s DIB is required by another program used by your
transaction, you must pass the information to that program.
To access fields in the DIB, use labels that are automatically generated in your
program by the translator.
Requirement: These labels are reserved; you must not redefine them.
In your COBOL, PL/I, assembler, and C programs, some variable names are
mandatory.
For a COBOL program:

DIBVERPICTURE X(2)
DIBSTATPICTURE X(2)
DIBSEGMPICTURE X(8)
DIBSEGLVPICTURE X(2)
DIBKFBLPICTURE S9(4) COMPUTATIONAL
DIBDBDNMPICTURE X(8)
DIBDBORGPICTURE X(8)
For a PL/I program:

DIBVERCHAR(2)
DIBSTATCHAR(2)
DIBSEGMCHAR(8)
DIBSEGLVCHAR(2)
DIBKFBLFIXED BINARY (15,0)
DIBDBDNMCHAR(8)
DIBDBORGCHAR(8)
For an assembler language program:

DIBVERCL2
DIBSTATCL2
DIBSEGMCL8
DIBSEGLVCL2
DIBKFBLH
DIBDBDNMCL8
DIBDBORGCL8
For a C program:
unsigned char dibver {2} ;
unsigned char dibstat {2} ;
unsigned char dibsegm {8} ;
unsigned char dibfic01 ;
unsigned char dibfic02 ;

unsigned char dibseglv {2} ;
signed short int dibkfbl ;
unsigned char dibdbdnm {8} ;
unsigned char dibdborg {8} ;
unsigned char dibfic03 {6} ;
The following notes explain the contents of each variable name. The name in
parenthesis is the label used to access the contents.
1. Translator Version (DIBVER)
This is the version of the DIB format your program is using. (DIBVER is used for
documentation and problem determination.)
2. Status Code (DIBSTAT)
DL/I places a 2-character status code in this field after executing each DL/I
command. This code describes the results of the command.
After processing a DL/I command, DL/I returns control to your program at the
next sequential instruction following the command. The first thing your program
should do after each command is to test the status code field and take
appropriate action. If the command was completely successful, this field
contains blanks.
Following are the status codes that could be returned to this field (they are the
only status codes returned to your program):
bb (Blanks) The command was completely successful.
BA For GU, GN, GNP, DLET, REPL, and ISRT commands. Data was unavailable.
2 BC For DLET, REPL, and ISRT commands. A deadlock was detected.
FH For GU, GN, GNP, DLET, REPL, ISRT, POS, CHKP, and SYMCHKP commands.
The DEDB was inaccessible.
FW For GU, GN, GNP, DLET, REPL, ISRT, and POS commands. More buffer space
is required than normally allowed.
GA For unqualified GN and GNP commands. DL/I returned a segment, but the
segment is at a higher level in the hierarchy than the last segment that
was returned.
GB For GN commands. DL/I reached the end of the database trying to
satisfy your GN command and did not return a segment to your
program’s I/O area.
GD For ISRT commands. The program issued an ISRT command that did
not have SEGMENT options for all levels above that of the segment
being inserted.
GE For GU, GN, GNP, ISRT, and STAT commands. DL/I was unable to find the
segment you requested, or one or more of the parents of the segment
you are trying to insert.
GG For Get commands. DL/I returns a GG status code to a program with a
processing option of GOT or GON when the segment that the program
is trying to retrieve contains an invalid pointer.
GK For unqualified GN and GNP commands. DL/I returned a segment that
satisfies an unqualified GN or GNP request, but the segment is of a
different segment type (but at the same level) than the last segment
returned.
II For ISRT commands. The segment you are trying to insert already exists
in the database. This code can also be returned if you have not
Chapter 3. Defining Application Program Elements to IMS 69

established a path for the segment before trying to insert it. The
segment you are trying to insert might match a segment with the same
key in another hierarchy or database record.
LB For load programs only after issuing a LOAD command. The segment
you are trying to load already exists in the database. DL/I returns this
status code only for segments with key fields.
NI For ISRT and REPL commands. The segment you are trying to insert or
replace requires a duplicate entry to be inserted in a secondary index
that does not allow duplicate entries. This status code is returned for
batch programs that write log records to direct access storage. If a
CICS program that does not log to disk encounters this condition, the
program (transaction) is abnormally terminated.
TG For TERM commands. The program tried to terminate a PSB when one
was not scheduled.
The status codes listed above indicate exceptional conditions, and are the only
status codes returned to your program. All other status codes indicate error
conditions and cause your transaction or batch program to abnormally
terminate. If you want to pass control to an error routine from your CICS
program, you can use the CICS HANDLE ABEND command; the last 2 bytes of the
abend code are the IMS status code that caused the abnormal termination. For
more information on the HANDLE ABEND command, see the application
programming reference manual for your version of CICS. Batch BMP programs
abend with abend 1041.
3. Segment Name (DIBSEGM)
This is the name of the lowest-level segment successfully accessed. When a
retrieval is successful, this field contains the name of the retrieved segment. If
the retrieval is unsuccessful, this field contains the last segment, along the path
to the requested segment, that satisfies the command.
After issuing an XRST command, this field is either set to blanks (indicating a
successful normal start), or a checkpoint ID (indicating the checkpoint ID from
which the program was restarted).
You should test this field after issuing any of the following commands:
v GN
v GNP
v GU
v ISRT
v LOAD
v RETRIEVE
v XRST
4. Segment Level Number (DIBSEGLV)
This is the hierarchic level of the lowest-level segment retrieved. When IMS DB
retrieves the segment you have requested, IMS DB places, in character format,
the level number of that segment in this field. If you are issuing a path
command, IMS DB places the number of the lowest-level segment retrieved. If
IMS DB is unable to find the segment you have requested, it gives the level
number of the last segment it encountered that satisfied your command. This is
the lowest segment on the last path that IMS DB encountered while searching
for the segment you requested.
You should test this field after issuing any of the following commands:
v GN

v GNP
v GU
v ISRT
v LOAD
v RETRIEVE
5. Key Feedback Length (DIBKFBL)
This is a halfword field that contains the length of the concatenated key when
you use the KEYFEEDBACK option with get commands. If your key feedback
area is not long enough to contain the concatenated key, the key is truncated,
and this area indicates the actual length of the full concatenated key.
6. Database Description Name (DIBDBDNM)
This is the fullword field that contains the name of the DBD. The DBD is the
DL/I control block that contains all information used to describe a database. The
DIBDBDNM field is returned only on a QUERY command.
7. Database Organization (DIBDBORG)
This is the fullword field that names the type of database organization (HDAM,
HIDAM, HISAM, HSAM, GSAM, SHSAM, INDEX, or DEDB) padded to the right
with blanks. The DIBDBORG field is returned only on a QUERY command.
Defining a Key Feedback Area

To retrieve the concatenated key of a segment, you must define an area into which
the key is placed. The concatenated key returned is that of the lowest-level
segment retrieved. (The segment retrieved is indicated in the DIB by the DIBSEGM
and DIBSEGLV fields.)
Specify the name of the area using the KEYFEEDBACK option on a GET
command.
A concatenated key is made up of the key of a segment, plus the keys for all of its
parents. For example, say you requested the concatenated key of the ILLNESS
segment for January 2, 1988, for patient number 05142. The following would be
returned to your key feedback field:
0514219880102
This number includes the key field of the ILLNESS segment, ILLDATE,
concatenated to the key field of the PATIENT segment, PATNO.
If you define an area that is not long enough to contain the entire concatenated key,
the key is truncated.
Defining I/O Areas

You use I/O areas to pass segments back and forth between your program and the
database. What an I/O area contains depends on the kind of command you are
issuing:
v When you retrieve a segment, DL/I places the segment you requested in the I/O
area.
v When you add a new segment, you build the new segment in the I/O area before
issuing an ISRT command.
v Before you modify a segment, you first retrieve the segment into the I/O area,
then issue the DLET or REPL command.
Chapter 3. Defining Application Program Elements to IMS 71

Defining I/O Areas
The I/O area must be long enough to contain the longest segment you retrieve from
or add to the database. (Otherwise, you might experience storage overlap.) If you
are retrieving, adding, or replacing multiple segments in one command, you must
define an I/O area for each segment.
As an example of what a segment looks like in your I/O area, say that you retrieved
the ILLNESS segment for Robert James, who came to the clinic on March 3, 1988.
He was treated for strep throat. The data returned to your I/O area would look like
this:
19880303STREPTHROA
The language coding formats follow:
COBOL I/O Area

The I/O area in a COBOL program should be defined as a 01 level working storage
entry. You can further define the area with 02 entries.
IDENTIFICATION
. DIVISION.
.
.
DATA DIVISION.
WORKING-STORAGE SECTION.
01INPUT-AREA.
02 KEY PICTURE X(6).
02 FIELD PICTURE X(84).
PL/I I/O Area

In PL/I, the name for the I/O area used in the DL/I call can be the name of a
fixed-length character string, a major structure, a connected array, or an adjustable
character string. It cannot be the name of a minor structure or a character string
with the attribute VARYING. If you want to define it as a minor structure, you can
use a pointer to the minor structure as the parameter.
Your program should define the I/O area as a fixed-length character string and pass
the name of that string, or define it in one of the other ways mentioned above and
then pass the pointer variable that points to that definition. If you want to use
substructures or elements of an array, use the DEFINED or BASED attribute.
DECLARE 1 INPUT_AREA,
2 KEY CHAR(6),
2 FIELD CHAR(84);
Assembler Language I/O Area

The I/O area in an assembler language program is formatted as follows:
IOAREA DS 0CL90
KEY DS CL6
FIELD DS CL84

Chapter 4. More about Writing Your Application Program
This chapter provides programming guidelines and information on preparing
programs for execution using EXEC DLI commands. It also contains skeleton
programs in assembler language, COBOL, PL/I, C, and C++.
Programming Guidelines
This description provides some guidelines for writing efficient and error-free
programs
The number, type, and sequence of the DL/I requests your program issues affect
the efficiency of your program. A program that is poorly designed runs if it is coded
correctly. The suggestions that follow can help you develop the most efficient design
possible for your application program. Inefficiently designed programs can adversely
affect performance and are hard to change. Being aware of how certain
combinations of commands or calls affects performance helps you to avoid these
problems and design a more efficient program.
Once you have a general sequence of calls mapped out for your program, look over
the guidelines on sequence below to see if you can improve the sequence. Usually
an efficient sequence of requests causes efficient internal DL/I processing.
v Use the simplest call. Qualify your requests to narrow the search for DL/I, but do
not use more qualification than required.
v Use the request or sequence of requests that gives DL/I the shortest path to the
segment you want.
v Use the fewest number of requests possible in your program. Each DL/I request
your program issues uses system time and resources. You may be able to
eliminate unnecessary calls by:
– Using path requests if you are replacing, retrieving, or inserting more than one
segment in the same path. If you are using more than one request to do this,
you are issuing unnecessary requests.
– Changing the sequence so that your program saves the segment in a
separate I/O area, and then gets it from that I/O area the second time it needs
the segment. If your program retrieves the same segment more than once
during program execution, you are issuing an unnecessary request.
– Anticipating and eliminating needless and nonproductive requests, such as
requests that result in GB, GE, and II status codes. For example, if you are
issuing GNs for a particular segment type and you know how many
occurrences of that segment type exist, do not issue the GN that results in a
GE status code. You can keep track of the number of occurrences your
program retrieves, and then continue with other processing when you know
you have retrieved all the occurrences of that segment type.
– Issuing an insert request with a qualification for each parent instead of issuing
Get requests for the parents to make sure that they exist. When you are
inserting segments, you cannot insert dependents unless the parents exist. If
DL/I returns a GE status code, at least one of the parents does not exist.
v Keep the main section of the program logic together. For example, branch to
conditional routines, such as error and print routines, in other parts of the
program, instead of having to branch around them to continue normal
processing.

Programming Guidelines
v Use call sequences that make good use of the physical placement of the data.
Access segments in hierarchic sequence as much as possible. Avoid moving
backward in the hierarchy.
v Process database records in order of the key field of the root segments. (For
HDAM databases, this order depends on the randomizing routine that is used.
Check with your DBA for this information.)
v Try to avoid constructing the logic of the program and the structure of commands
or calls in a way that depends heavily on the database structure. Depending on
the current structure of the hierarchy reduces the program’s flexibility.
Coding a Program in Assembler Language

The following is a sample CICS online program written in assembler language. It
shows you how the different parts of a command-level program fit together, and
how the EXEC DLI commands are coded.
Except for a few commands, the program shown below applies to batch, BMP, and
CICS programs. Differences are highlighted in the notes that follow. The numbers to
the right of the sample code refer to those notes.
See the following assembler language sample code.

*ASM XOPTS(CICS,DLI)
* 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R11 EQU 11
R12 EQU 12
R13 EQU 13
DFHEISTG DSECT
SEGKEYA DS CL4
SEGKEYB DS CL4 2
SEGKEYC DS CL4
SEGKEY1 DS CL4
SEGKEY2 DS CL4
CONKEYB DS CL8
SEGNAME DS CL8
SEGLEN DS H
PCBNUM DS H
AREAA DS CL80
AREAB DS CL80 3
AREAC DS CL80
AREAG DS CL250
AREASTAT DS CL360
* COPY MAPSET
*
*******************************************************************
* INITIALIZATION
* HANDLE ERROR CONDITIONS IN ERROR ROUTINE 4
* HANDLE ABENDS (DLI ERROR STATUS CODES) IN ABEND ROUTINE
* RECEIVE INPUT MESSAGE
*******************************************************************
*
SAMPLE DFHEIENT CODEREG=(R2,R3),DATAREG=(R13,R12),EIBREG=R11 5
*
EXEC CICS HANDLE CONDITION ERROR(ERRORS) 6
*
EXEC CICS HANDLE ABEND LABEL(ABENDS) 6
*
EXEC CICS RECEIVE MAP (’SAMPMAP’) MAPSET(’MAPSET’) 6
* ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING
*
*******************************************************************

* SCHEDULE PSB NAMED ’SAMPLE1’
*******************************************************************
*
EXEC DLI SCHD PSB(SAMPLE1) 7
BAL R4,TESTDIB CHECK STATUS
*
*******************************************************************
* RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS
*******************************************************************
*
MVC SEGKEYA,=C’A300’ 8
EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA) X
SEGLENGTH(80) WHERE(KEYA=SEGKEYA) FIELDLENGTH(4)
GNPLOOP EQU *
EXEC DLI GNP USING PCB(1) INTO(AREAG) SEGLENGTH(250)
CLC DIBSTAT,=C’GE’ LOOK FOR END 9
BE LOOPDONE DONE AT ’GE’
B GNPLOOP
LOOPDONE EQU *
*
*******************************************************************
* INSERT NEW ROOT SEGMENT
*******************************************************************
*
MVC AREAA,=CL80’DATA FOR NEW SEGMENT INCLUDING KEY’
EXEC DLI ISRT USING PCB(1) SEGMENT(SEGA) FROM(AREAA) X
SEGLENGTH(80)
*
*******************************************************************
* RETRIEVE 3 SEGMENTS IN PATH AND REPLACE THEM
*******************************************************************
*
MVC SEGKEYA,=C’A200’
MVC SEGKEYB,=C’B240’
MVC SEGKEYC,=C’C241’
EXEC DLI GU USING PCB(1) X
SEGMENT(SEGA) WHERE(KEYA=SEGKEYA) X10
FIELDLENGTH(4) X
INTO(AREAA) X
SEGLENGTH(80) X
SEGMENT(SEGB) WHERE(KEYB=SEGKEYB) FIELDLENGTH(4) X
INTO(AREAB) X
SEGLENGTH(80) X
SEGMENT(SEGC) WHERE(KEYC=SEGKEYC) FIELDLENGTH(4) X
INTO(AREAC) X
SEGLENGTH(80)
BAL R4,TESTDIB
* UPDATE FIELDS IN THE 3 SEGMENTS
EXEC DLI REPL USING PCB(1) X
SEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80) X
SEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80) X
SEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80)
*
*******************************************************************
* INSERT NEW SEGMENT USING CONCATENATED KEY TO QUALIFY PARENT
*******************************************************************
*
MVC AREAC,=CL80’DATA FOR NEW SEGMENT INCLUDING KEY’
MVC CONKEYB,=C’A200B240’
EXEC DLI ISRT USING PCB(1) X
SEGMENT(SEGB) KEYS(CONKEYB) KEYLENGTH(8) X
Chapter 4. More about Writing Your Application Program 75

*
*******************************************************************
* RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY
* AND THEN DELETE IT AND ITS DEPENDENTS
*******************************************************************
*
EXEC DLI GU USING PCB(1) X
SEGMENT(SEGB) X
KEYS(CONKEYB) KEYLENGTH(8) X
INTO(AREAB) SEGLENGTH(80)
EXEC DLI DLET USING PCB(1) X
SEGMENT(SEGB) SEGLENGTH(80) FROM(AREAB)
*
*******************************************************************
* RETRIEVE SEGMENT BY QUALIFYING PARENT WITH CONCATENATED KEY,
* OBJECT SEGMENT WITH WHERE OPTION USING A LITERAL,
* AND THEN SET PARENTAGE
*
* USE VARIABLES FOR PCB INDEX, SEGMENT NAME, AND SEGMENT LENGTH
*******************************************************************
*
MVC SEGNAME,=CL8’SEGA’
MVC SEGLEN,=H’80’
MVC PCBNUM,=H’1’
EXEC DLI GU USING PCB(PCBNUM) X
SEGMENT((SEGNAME)) X
KEYS(CONKEYB) KEYLENGTH(8) SETPARENT X
SEGMENT(SEGC) INTO(AREAC) SEGLENGTH(SEGLEN) X
WHERE(KEYC=’C520’)
*
*******************************************************************
* RETRIEVE DATABASE STATISTICS
*******************************************************************
*
EXEC DLI STAT USING PCB(1) INTO(AREASTAT) X
VSAM FORMATTED LENGTH(360)
*
*******************************************************************
* RETRIEVE ROOT SEGMENT USING BOOLEAN OPERATORS
*******************************************************************
*
MVC SEGKEY1,=C’A050’
MVC SEGKEY2,=C’A150’
EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA) X
SEGLENGTH(80) FIELDLENGTH(4,4,4,4) X
WHERE(KEYA > SEGKEY1 AND KEYA < SEGKEY2
KEYA > ’A275’ AND KEYA < ’A350’)
*
*******************************************************************
* TERMINATE PSB WHEN DLI PROCESSING IS COMPLETED
*******************************************************************
*
EXEC DLI TERM 11
*
*******************************************************************
* SEND OUTPUT MESSAGE
*******************************************************************
*
EXEC CICS SEND MAP(’SAMPMAP’) MAPSET(’MAPSET’) 6
EXEC CICS WAIT TERMINAL

*
*******************************************************************
* COMPLETE TRANSACTION AND RETURN TO CICS
*******************************************************************
*
EXEC CICS RETURN 12
*
*******************************************************************
* CHECK STATUS IN DIB
*******************************************************************
*
TESTDIB EQU *
CLC DIBSTAT,=C’ ’ IS STATUS BLANK 13
BER R4 YES - RETURN
* HANDLE DLI STATUS CODES REPRESENTING EXCEPTIONAL CONDITIONS
*
BR R4 RETURN
ERRORS EQU *
* HANDLE ERROR CONDITIONS
*
ABENDS EQU *
* HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES
*
END
Notes to the sample Assembler code:

1For a CICS online program containing EXEC DLI commands, you must
specify the DLI and CICS options. For a batch or BMP program containing
EXEC DLI, you must specify only the DLI option.
2For reentrance, define each of the areas the program uses—I/O areas, key
feedback areas, and segment name areas in DFHEISTG.
3Define an I/O area for each segment you retrieve, add, or replace (in a
single command).
4For a batch or BMP program containing EXEC DLI, you must save registers
on entry and restore registers on exit according to MVS register-saving
conventions.
5In a batch or BMP program, a DFHEIENT saves the registers on entry. Do
not specify the EIBREG parameter in a batch program.
6Do not code EXEC CICS commands in a batch or BMP program.
7In a CICS online program, use the SCHD PSB command to obtain a PSB for
the use of your program. Do not schedule a PSB in a batch or BMP program.
8This GU command retrieves the first occurrence of SEGA with a key of A300.
You do not have to provide the KEYLENGTH or SEGLENGTH options in an
assembler language program.
9This GNP command retrieves all dependents under segment SEGA. The GE
status code indicates that no more dependents exist.
10This GU command is an example of a path command. Use a separate I/O
area for each segment you retrieve.
11In a CICS online program, the TERM command terminates the PSB
scheduled earlier. You do not terminate the PSB in a batch or BMP program.
12For a batch or BMP program, code DFHEIRET with an optional RCREG
parameter instead of EXEC CICS RETURN. The RCREG parameter identifies a
register containing the return code.
13After issuing each command, you should check the status code in the DIB.

Coding a Program in COBOL
The following is a sample program written for COBOL. It shows you how the
different parts of a command-level program fit together, and how the EXEC DLI
commands are coded. The sample program applies to the COBOL V4 compiler
(5734-CB2), the OS/VS COBOL compiler (5740-CB1), IBM COBOL for MVS & VM
(5688-197), and the VS COBOL II compiler (5668-958 and 5668-940).
the right of the sample code refer to those notes.
See the following COBOL sample code.

CBL LIB,APOST,XOPTS(CICS,DLI) IDENTIFICATION DIVISION.
PROGRAM-ID. SAMPLE. 1
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
.* SOURCE-COMPUTER. IBM-370.
.* OBJECT-COMPUTER. IBM-370.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 SEGKEYA PIC X(4).
77 SEGKEYB PIC X(4). 2
77 SEGKEYC PIC X(4).
77 SEGKEY1 PIC X(4).
77 CONKEYB PIC X(8).
77 SEGNAME PIC X(8).
77 SEGLEN COMP PIC S9(4).
77 PCBNUM COMP PIC S9(4).
01 AREAA PIC X(80).
* DEFINE SEGMENT I/O AREA
01 AREAB PIC X(80).
01 AREAC PIC X(80). 3
01 AREAG PIC X(250).
01 AREASTAT PIC X(360).
* COPY MAPSET.
PROCEDURE DIVISION.
*
* ***************************************************************
* INITIALIZATION
* HANDLE ERROR CONDITIONS IN ERROR ROUTINE
* HANDLE ABENDS (DLI ERROR STATUS CODES) IN ABEND ROUTINE
* RECEIVE INPUT MESSAGE
* ***************************************************************
*
EXEC CICS HANDLE CONDITION ERROR(ERRORS) END-EXEC. 4
*
EXEC CICS HANDLE ABEND LABEL(ABENDS) END-EXEC. 4
*
EXEC CICS RECEIVE MAP (’SAMPMAP’) MAPSET(’MAPSET’) END-EXEC. 4
* ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING
*
* ***************************************************************
* SCHEDULE PSB NAMED ’SAMPLE1’
* ***************************************************************
*
EXEC DLI SCHD PSB(SAMPLE1) END-EXEC.
PERFORM TEST-DIB THRU OK. 5
*
* ***************************************************************
* RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS
* ***************************************************************

*
MOVE ’A300’ TO SEGKEYA.
EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA)
SEGLENGTH(80) WHERE(KEYA=SEGKEYA) 6
FIELDLENGTH(4)
END-EXEC.
PERFORM TEST-DIB THRU OK.
GNPLOOP.
EXEC DLI GNP USING PCB(1) INTO(AREAG) SEGLENGTH(250)
END-EXEC.
IF DIBSTAT EQUAL TO ’GE’ THEN GO TO LOOPDONE.
GO TO GNPLOOP.
LOOPDONE.
*
* ***************************************************************
* INSERT NEW ROOT SEGMENT
* ***************************************************************
*
MOVE ’DATA FOR NEW SEGMENT INCLUDING KEY’ TO AREAA.
EXEC DLI ISRT USING PCB(1) SEGMENT(SEGA) FROM(AREAA)
SEGLENGTH(80) END-EXEC.
*
* ***************************************************************
* RETRIEVE 3 SEGMENTS IN PATH AND REPLACE THEM
* ***************************************************************
*
MOVE ’A200’ TO SEGKEYA.
MOVE ’B240’ TO SEGKEYB.
MOVE ’C241’ TO SEGKEYC.
EXEC DLI GU USING PCB(1)
SEGMENT(SEGA) WHERE(KEYA=SEGKEYA) FIELDLENGTH(4) 7
INTO(AREAA)
SEGLENGTH(80)
SEGMENT(SEGB) WHERE(KEYB=SEGKEYB) FIELDLENGTH(4)
INTO(AREAB)
SEGLENGTH(80)
SEGMENT(SEGC) WHERE(KEYC=SEGKEYC) FIELDLENGTH(4)
INTO(AREAC)
SEGLENGTH(80)
END-EXEC.
* UPDATE FIELDS IN THE 3 SEGMENTS
EXEC DLI REPL USING PCB(1)
SEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80)
SEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80)
END-EXEC.
*
* ***************************************************************
* INSERT NEW SEGMENT USING CONCATENATED KEY TO QUALIFY PARENT
* ***************************************************************
*
MOVE ’DATA FOR NEW SEGMENT INCLUDING KEY’ TO AREAC.
MOVE ’A200B240’ TO CONKEYB.
EXEC DLI ISRT USING PCB(1)
SEGMENT(SEGB) KEYS(CONKEYB) KEYLENGTH(8)
END-EXEC.
*
* ***************************************************************
* RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY
* AND THEN DELETE IT AND ITS DEPENDENTS
* ***************************************************************

*
SEGMENT(SEGB)
KEYS(CONKEYB) KEYLENGTH(8)
INTO(AREAB) SEGLENGTH(80)
END-EXEC.
EXEC DLI DLET USING PCB(1)
SEGMENT(SEGB) SEGLENGTH(80) FROM(AREAB) END-EXEC.
*
* ***************************************************************
* RETRIEVE SEGMENT BY QUALIFYING PARENT WITH CONCATENATED KEY,
* OBJECT SEGMENT WITH WHERE OPTION,
* AND THEN SET PARENTAGE
*
* USE VARIABLES FOR PCB INDEX, SEGMENT NAME, AND SEGMENT LENGTH
* ***************************************************************
*
MOVE ’C520’ TO SEGKEYC.
MOVE ’SEGA’ TO SEGNAME.
MOVE 80 TO SEGLEN.
MOVE 1 TO PCBNUM.
EXEC DLI GU USING PCB(PCBNUM)
SEGMENT((SEGNAME))
KEYS(CONKEYB) KEYLENGTH(8) SETPARENT
SEGMENT(SEGC) INTO(AREAC) SEGLENGTH(SEGLEN)
WHERE(KEYC=SEGKEYC) FIELDLENGTH(4) END-EXEC.
*
* ***************************************************************
* RETRIEVE DATABASE STATISTICS
* ***************************************************************
*
EXEC DLI STAT USING PCB(1) INTO(AREASTAT)
VSAM FORMATTED LENGTH(360) END-EXEC.
*
* ***************************************************************
* RETRIEVE ROOT SEGMENT USING BOOLEAN OPERATORS
* ***************************************************************
*
MOVE ’A050’ TO SEGKEY1.
SEGLENGTH(80) FIELDLENGTH(4,4,4,4)
WHERE(KEYA > SEGKEY1 AND KEYA < SEGKEY2 OR
KEYA > SEGKEY3 AND KEYA < SEGKEY4)
END-EXEC.
*
* ***************************************************************
* TERMINATE PSB WHEN DLI PROCESSING IS COMPLETED
* ***************************************************************
*
EXEC DLI TERM END-EXEC. 8
*
* ***************************************************************
* ***************************************************************
* SEND OUTPUT MESSAGE
* ***************************************************************
*
EXEC CICS SEND MAP(’SAMPMAP’) MAPSET(’MAPSET’) END-EXEC.

EXEC CICS WAIT TERMINAL END-EXEC.
*
* ***************************************************************
* COMPLETE TRANSACTION AND RETURN TO CICS
* ***************************************************************
*
EXEC CICS RETURN END-EXEC.
*
* ***************************************************************
* CHECK STATUS IN DIB
* ***************************************************************
*
TEST-DIB.
IF DIBSTAT EQUAL TO ’ ’ THEN GO TO OK.
OK. 9
ERRORS.
* HANDLE ERROR CONDITIONS
ABENDS.
* HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES
Notes to the sample COBOL code:

2 Define each of the areas the program uses—I/O areas, key feedback areas,
and segment name areas—as 77- or 01-level working storage entries.
3Define an I/O area for each segment you retrieve, add, or replace (in a
single command).
5For CICS online programs, you use a SCHD PSB command to obtain a PSB.
You do not schedule a PSB in a batch or BMP program.
KEYLENGTH and SEGLENGTH are optional for IBM COBOL for MVS & VM
(and VS COBOL II). For COBOL V4 and OS/VS COBOL, KEYLENGTH and
SEGLENGTH are required.
7This GU command is an example of a path command. You must use a
separate I/O area for each segment you retrieve.
8For a CICS online program, the TERM command terminates the PSB
Coding a Program in PL/I

The following is a sample program written in PL/I. It shows you how the different
parts of a command-level program fit together, and how the EXEC DLI commands
are coded.
the right of the program refer to those notes.
See the following PL/I sample code.

*PROCESS INCLUDE,GN,XOPTS(CICS,DLI); 1
SAMPLE: PROCEDURE OPTIONS(MAIN);
DCL SEGKEYA CHAR (4);
DCL SEGKEYB CHAR (4); 2
DCL SEGKEYC CHAR (4);
DCL SEGKEY1 CHAR (4);

DCL CONKEYB CHAR (8);
DCL SEGNAME CHAR (8);
DCL PCBNUM FIXED BIN (15);
DCL AREAA CHAR (80);
/* DEFINE SEGMENT I/O AREA */
DCL AREAB CHAR (80);
DCL AREAC CHAR (80); 3
DCL AREAG CHAR (250);
DCL AREASTAT CHAR (360);
%INCLUDE MAPSET
/* */
/* */
/* ************************************************************ */
/* INITIALIZATION */
/* HANDLE ERROR CONDITIONS IN ERROR ROUTINE */
/* HANDLE ABENDS (DLI ERROR STATUS CODES) IN ABEND PROGRAM */
/* RECEIVE INPUT MESSAGE */
/* ************************************************************ */
/* */
EXEC CICS HANDLE CONDITION ERROR(ERRORS); 4
/* */
EXEC CICS HANDLE ABEND PROGRAM(’ABENDS’); 4
/* */
EXEC CICS RECEIVE MAP (’SAMPMAP’) MAPSET(’MAPSET’); 4
/* ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING */
/* */
/* ************************************************************ */
/* SCHEDULE PSB NAMED ’SAMPLE1’ */
/* ************************************************************ */
/* */
EXEC DLI SCHD PSB(SAMPLE1);
CALL TEST_DIB; 5
/* ************************************************************* */
/* RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS */
/* ************************************************************* */
/* */
SEGKEYA = ’A300’;
WHERE(KEYA=SEGKEYA); 6
CALL TEST_DIB;
GNPLOOP:
EXEC DLI GNP USING PCB(1) INTO(AREAG); 7
IF DIBSTAT = ’GE’ THEN GO TO LOOPDONE;
CALL TEST_DIB;
GO TO GNPLOOP;
LOOPDONE:
/* */
/* ************************************************************ */
/* INSERT NEW ROOT SEGMENT */
/* ************************************************************ */
/* */
AREAA = ’DATA FOR NEW SEGMENT INCLUDING KEY’;
EXEC DLI ISRT USING PCB(1) SEGMENT(SEGA) FROM(AREAA);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* RETRIEVE 3 SEGMENTS IN PATH AND REPLACE THEM */
/* ************************************************************* */
/* */
SEGKEYA = ’A200’;
SEGKEYB = ’B240’;
SEGKEYC = ’C241’;

SEGMENT(SEGA) WHERE(KEYA=SEGKEYA) 8
INTO(AREAA)
SEGMENT(SEGB) WHERE(KEYB=SEGKEYB)
INTO(AREAB)
SEGMENT(SEGC) WHERE(KEYC=SEGKEYC)
INTO(AREAC);
CALL TEST_DIB;
/* UPDATE FIELDS IN THE 3 SEGMENTS */
EXEC DLI REPL USING PCB(1)
SEGMENT(SEGA) FROM(AREAA)
SEGMENT(SEGB) FROM(AREAB)
SEGMENT(SEGC) FROM(AREAC);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* INSERT NEW SEGMENT USING CONCATENATED KEY TO QUALIFY PARENT */
/* ************************************************************* */
/* */
AREAC = ’DATA FOR NEW SEGMENT INCLUDING KEY’;
CONKEYB = ’A200B240’;
SEGMENT(SEGB) KEYS(CONKEYB)
SEGMENT(SEGC) FROM(AREAC);
CALL TEST_DIB;
/* */
/* ************************************************************ */
/* RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY */
/* AND THEN DELETE IT AND ITS DEPENDENTS */
/* ************************************************************ */
/* */
SEGMENT(SEGB)
KEYS(CONKEYB)
INTO(AREAB);
CALL TEST_DIB;
EXEC DLI DLET USING PCB(1)
SEGMENT(SEGB) FROM(AREAB);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* RETRIEVE SEGMENT BY QUALIFYING PARENT WITH CONCATENATED KEY, */
/* OBJECT SEGMENT WITH WHERE OPTION */
/* AND THEN SET PARENTAGE */
/* */
/* USE VARIABLES FOR PCB INDEX, SEGMENT NAME */
/* ************************************************************* */
/* */
SEGNAME = ’SEGA’;
SEGKEYC = ’C520’;
PCBNUM = 1;
EXEC DLI GU USING PCB(PCBNUM)
SEGMENT((SEGNAME))
KEYS(CONKEYB) SETPARENT
SEGMENT(SEGC) INTO(AREAC)
WHERE(KEYC=SEGKEYC);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* RETRIEVE DATABASE STATISTICS */
/* ************************************************************* */
/* */
EXEC DLI STAT USING PCB(1) INTO(AREASTAT) VSAM FORMATTED;
CALL TEST_DIB;
/* */
/* ************************************************************ */

/* RETRIEVE ROOT SEGMENT USING BOOLEAN OPERATORS */
/* ************************************************************ */
/* */
SEGKEY1 = ’A050’;
WHERE(KEYA &Ar; SEGKEY1 AND KEYA &Al; SEGKEY2 OR
KEYA &Ar; SEGKEY3 AND KEYA &Al; SEGKEY4);
CALL TEST_DIB;
/* */
/* ************************************************************* */
/* TERMINATE PSB WHEN DLI PROCESSING IS COMPLETED */
/* ************************************************************* */
/* */
EXEC DLI TERM;

9
/* */
/* ************************************************************* */
/* SEND OUTPUT MESSAGE */
/* ************************************************************* */
/* */
EXEC CICS SEND MAP(’SAMPMAP’) MAPSET(’MAPSET’); 4
EXEC CICS WAIT TERMINAL;
/* */
/* ************************************************************* */
/* COMPLETE TRANSACTION AND RETURN TO CICS */
/* ************************************************************* */
/* */
EXEC CICS RETURN; 4
/* */
/* ************************************************************ */
/* CHECK STATUS IN DIB */
/* ************************************************************ */
/* */
TEST_DIB: PROCEDURE;
IF DIBSTAT = ’ ’ RETURN; 10
/* HANDLE DLI STATUS CODES REPRESENTING EXCEPTIONAL CONDITIONS */

/* */
OK:
END TEST_DB;
ERRORS:
/* HANDLE ERROR CONDITIONS */
/* */
END SAMPLE;
Notes to the sample PL/I code:

2Define, in automatic storage, each of the areas; I/O areas, key feedback
areas, and segment name areas.
3Define an I/O area for each segment you retrieve, add, or replace in a single
command.
5For CICS online programs, you use a SCHD PSB command to obtain a PSB.
You do not schedule a PSB in a batch or BMP program.

Notice that you do not need to include the KEYLENGTH and SEGLENGTH
options.
7This GNP command retrieves all dependents under segment SEGA. The GE
status code indicates that no more dependents exist.
8This GU command is an example of a path command. You must use a
separate I/O area for each segment you retrieve.
9For a CICS online program, the TERM command terminates the PSB
Coding a Program in C
The following is a sample program written in C. It shows you how the different parts
of a command-level program fit together, and how the EXEC DLI commands are
coded.
the right of the program refer to those notes.
See the following C sample code.

#include < string.h> 1
#include < stdio.h > 2
char DIVIDER[120] = "-----------------------------------------\

------------------------------------------------------------------";
char BLANK[120] = " \
\0";
char BLAN2[110] = " \
\0";
char SCHED[120] = "Schedule PSB(PC3COCHD) " 3
char GN1[120] = "GN using PCB(2) Segment(SE2ORDER) check dibstat \
is blank";
char GNP1[120] = "GNP using PCB(2) check dibstat = GK or blank \
(or GE for last GNP)";
char GU1[120] = "GU using PCB(2) Segment(SE2ORDER) where(\
FE2OGREF=000000’’) check dibstat blank";
char GU2[120] = "GU using PCB(2) Segment(SE2ORDER) where(\
FE2OGREF=000999’’) check dibstat blank";
char REP1[120] = "REPLACE using PCB(2) Segment(SE2ORDER) check \
dibstat is blank";
char DEL1[120] = "DELETE using PCB(2) Segment(SE2ORDER) check \
dibstat is blank";
char INS1[120] = "INSERT using PCB(2) Segment(SE2ORDER) where\
(FE2OGREF=’’000999’’) check dibstat is blank";
char TERM[120] = "TERM - check dibstat is blank";
char STAT[120] = "STAT USING PCB(2) VSAM FORMATTED";
char DATAB[6] = "000999";
char DATAC[114] = " REGRUN TEST INSERT NO1.";
char START[120] = "PROGXIV STARTING";
char OKMSG[120] = "PROGXIV COMPLETE";
int TLINE = 120;
int L11 = 11;
int L360 = 11;
struct {
char NEWSEGB[6];
char NEWSEGC[54];
} NEWSEG;
char OUTLINE[120]; 4
struct {

char OUTLINA[9];
char OUTLINB[111];
} OUTLIN2;
struct {
char OUTLINX[9];
char OUTLINY[6];
char OUTLINZ[105];
} OUTLIN3;
char GUIOA[60];
char GNIOA[60];
struct {
char ISRT1[6];
char ISRT2[54];
} ISRTIOA;
struct {
char REPLIO1[6];
char REPLIO2[54];
} REPLIOA;
struct {
char DLET1[6];
char DLET2[54];
} DLETIOA;
struct {
char STATA1[120];
char STATA2[120];
char STATA3[120];
} STATAREA;
struct {
char DHPART[2];
char RETCODE[2]
} DHABCODE;
main()
{
EXEC CICS ADDRESS EIB(dfheiptr); 5
strcpy(OUTLINE,DIVIDER);
SENDLINE();
strcpy(OUTLINE,START);
SENDLINE();
/* */
/* SCHEDULE PSB */
/* */
strcpy(OUTLINE,SCHED);
SENDLINE();
EXEC DLI SCHEDULE PSB(PC3COCHD); 6
SENDSTAT();
TESTDIB();
/* */
/* ISSUE GU REQUEST */
/* */
strcpy(OUTLINE,GU1);
SENDLINE();
EXEC DLI GET UNIQUE USING PCB(2) 7
SEGMENT(SE2ORDER)
WHERE(FE2OGREF>="000000")
INTO(&GUIOA) SEGLENGTH(60);
strcpy(OUTLIN2.OUTLINA,"SE2ORDER=");
strcpy(OUTLIN2.OUTLINB,GUIOA);
SENDLIN2();
SENDSTAT();
TESTDIB();
/* */
/* ISSUE GNP REQUEST */
/* */
do {
strcpy(OUTLINE,GNP1);
SENDLINE();

EXEC DLI GET NEXT IN PARENT USING PCB(2) 8
INTO(&GNIOA) SEGLENGTH(60);
strcpy(OUTLIN2.OUTLINA,"SEGMENT=");
strcpy(OUTLIN2.OUTLINB,GNIOA);
SENDLIN2();
SENDSTAT();
if (strncmp(dibptr->dibstat,"GE",2) != 0) 9
TESTDIB();
} while (strncmp(dibptr->dibstat,"GE",2) != 0);
/* */
/* ISSUE GN REQUEST */
/* */
strcpy(OUTLINE,GN1);
SENDLINE();
EXEC DLI GET NEXT USING PCB(2)
SEGMENT(SE2ORDER) 10
SENDLIN2();
SENDSTAT();
TESTDIB();
/* */
/* INSERT SEGMENT */
/* */
strcpy(OUTLINE,INS1);
SENDLINE();
strcpy(NEWSEG.NEWSEGB,DATAB); 11
strcpy(NEWSEG.NEWSEGC,DATAC);
strcpy(ISRTIOA.ISRT1,NEWSEG.NEWSEGB);
strcpy(ISRTIOA.ISRT2,NEWSEG.NEWSEGC);
strcpy(OUTLIN3.OUTLINX,"ISRT SEG=");
strcpy(OUTLIN3.OUTLINY,ISRTIOA.ISRT1);
strcpy(OUTLIN3.OUTLINZ,ISRTIOA.ISRT2);
SENDLIN3();
SEGMENT(SE2ORDER)
FROM(&ISRTIOA) SEGLENGTH(60);
SENDSTAT();
if (strncmp(dibptr->dibstat,"II",2) == 0)
strncpy(dibptr->dibstat," ",2);
TESTDIB();
/* */
/* */
SENDLINE();
EXEC DLI GET NEXT USING PCB(2) 12
SEGMENT(SE2ORDER)
SENDLIN2();
SENDSTAT();
TESTDIB();
/* */
/* GET INSERTED SEGMENT TO BE REPLACED */
/* */
SENDLINE();
SEGMENT(SE2ORDER)
WHERE(FE2OGREF="000999")
INTO(&ISRTIOA) SEGLENGTH(60);
strcpy(OUTLIN3.OUTLINX,"ISRT SEG=");
strcpy(OUTLIN3.OUTLINY,ISRTIOA.ISRT1);
strcpy(OUTLIN3.OUTLINZ,ISRTIOA.ISRT2);

SENDLIN3();
SENDSTAT();
TESTDIB();
/* */
/* REPLACE SEGMENT */
/* */
strcpy(OUTLINE,REP1);
SENDLINE();
strcpy(REPLIOA.REPLIO1,DATAB); 14
strcpy(REPLIOA.REPLIO2,"REGRUN REPLACED SEGMENT NO1.");
strcpy(OUTLIN3.OUTLINX,"REPL SEG=");
strcpy(OUTLIN3.OUTLINY,REPLIOA.REPLIO1);
strcpy(OUTLIN3.OUTLINZ,REPLIOA.REPLIO2);
SENDLIN3();
EXEC DLI REPLACE USING PCB(2)
SEGMENT(SE2ORDER)
FROM(&REPLIOA) SEGLENGTH(60);
SENDSTAT();
TESTDIB();
/* */
/* */
SENDLINE();
EXEC DLI GET NEXT USING PCB(2) 15
SEGMENT(SE2ORDER)
SENDLIN2();
SENDSTAT();
TESTDIB();
/* */
/* GET REPLACED SEGMENT */
/* */
SENDLINE();
SEGMENT(SE2ORDER)
WHERE(FE2OGREF="000999")
INTO(&REPLIOA) SEGLENGTH(60);
strcpy(OUTLIN3.OUTLINX,"REPL SEG=");
strcpy(OUTLIN3.OUTLINY,REPLIOA.REPLIO1);
strcpy(OUTLIN3.OUTLINZ,REPLIOA.REPLIO2);
SENDLIN3();
SENDSTAT();
TESTDIB();
/* */
/* ISSUE DELETE REQUEST */
/* */
strcpy(OUTLINE,DEL1);
SENDLINE();
strcpy(DLETIOA.DLET1,REPLIOA.REPLIO1); 17
strcpy(DLETIOA.DLET2,REPLIOA.REPLIO2);
strcpy(OUTLIN3.OUTLINX,"DLET SEG=");
strcpy(OUTLIN3.OUTLINY,DLETIOA.DLET1);
strcpy(OUTLIN3.OUTLINZ,DLETIOA.DLET2);
SENDLIN3();
EXEC DLI DELETE USING PCB(2)
SEGMENT(SE2ORDER)
FROM(&DLETIOA) SEGLENGTH(60);
SENDSTAT();
TESTDIB();
/* */
/* ISSUE STAT REQUEST */
/* */
strcpy(OUTLINE,STAT);

SENDLINE();
EXEC DLI STAT USING PCB(2) 18
VSAM FORMATTED
INTO(&STATAREA);
SENDSTT2();
TESTDIB();
/* */
/* ISSUE TERM REQUEST */
/* */
strcpy(OUTLINE,TERM);
SENDLINE();
EXEC DLI TERM; 19
SENDSTAT();
TESTDIB();
SENDLINE();
SENDOK();
/* */
/* RETURN TO CICS */
/* */
EXEC CICS RETURN;
}
/* */
/* */
/* */
SENDLINE()
{
EXEC CICS SEND FROM(OUTLINE) LENGTH(120); 20
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLINE) LENGTH(TLINE);
strcpy(OUTLINE,BLANK);
return;
}
SENDLIN2()
{
EXEC CICS SEND FROM(OUTLIN2) LENGTH(120);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN2) LENGTH(TLINE);
strcpy(OUTLIN2.OUTLINA,BLANK,9);
strcpy(OUTLIN2.OUTLINB,BLANK,111);
return;
}
SENDLIN3()
{
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN3) LENGTH(TLINE);
strcpy(OUTLIN3.OUTLINX,BLANK,9);
strcpy(OUTLIN3.OUTLINY,BLANK,6);
strcpy(OUTLIN3.OUTLINZ,BLANK,105);
return;
}
SENDSTAT()
{
strncpy(OUTLIN2.OUTLINA,BLANK,9);
strncpy(OUTLIN2.OUTLINB,BLAN2,110);
strcpy(OUTLIN2.OUTLINA," DIBSTAT=");
strcpy(OUTLIN2.OUTLINB,dibptr->dibstat);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN2) LENGTH(L11);
SENDLINE();
return;
}
SENDSTT2()
{

strncpy(OUTLIN2.OUTLINA,BLANK,9);
strncpy(OUTLIN2.OUTLINB,BLAN2,110);
strcpy(OUTLIN2.OUTLINA," DIBSTAT=");
strcpy(OUTLIN2.OUTLINB,dibptr->dibstat);
EXEC CICS SEND FROM(STATAREA) LENGTH(360);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(STATAREA)
LENGTH(L360);
return;
}
SENDOK()
{
EXEC CICS SEND FROM(OKMSG) LENGTH(120);
EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OKMSG) LENGTH(TLINE);
return;
}
TESTDIB() 21
{
if (strncmp(dibptr->dibstat," ",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GK",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GB",2) == 0)
return;
else if (strncmp(dibptr->dibstat,"GE",2) == 0)
return;
else
{
EXEC CICS ABEND ABCODE("PETE"); 22
EXEC CICS RETURN;
}
return;
}
Notes to the sample C code:

1You must include a standard header file string.h to gain access to string
manipulation facilities.
2You must include standard header file stdio.h to gain access to standard I/O
library routings.
3Define DL/I messages.
4Define the I/O areas.
5Program start.
6Define PSB PC3COCHD.
7Issue the first command. Retrieves the first occurrence of segment
SE2ORDER and puts it into array OUTLIN2.
8Issue the GNP command to get the next segment and put it into array
OUTLIN2.
9GE status codes indicate no more segments to get.
10Get next segment SE2ORDER and put it into the array OUTLIN2.
11Insert segment into array OUTLIN3.
12Issue GN to retrieve next segment and put it into array OUTLIN2.
13Get next segment that will be replaced and put it into OUTLIN3.
14Replace the segment and put it into array OUTLIN3.
15Get next segment and put it into array OUTLIN2.
16Get the replaced segment and put it into array OUTLIN3.

17Issue DELETE command after putting content of segment into array
OUTLIN3.
18Issue STAT REQUEST command.
19Issue TERM command.
20Output processing.
21Check return code.
Preparing Your EXEC DLI Program for Execution

The steps for preparing your program for execution are as follows:
1. Run the CICS command language translator to translate the EXEC DLI and
EXEC CICS commands. COBOL, PL/I, and assembler language programs have
separate translators.
2. Compile your program.
3. Link-edit:
v An online program with the appropriate CICS interface module
v A batch or BMP program with the IMS interface module.
You can use CICS-supplied procedures to translate, compile, and link-edit your
program. The procedure you use depends on the type of program (batch, BMP, or
CICS online) and the language it is written in (COBOL, PL/I, or assembler
language).
Translator Options Required for EXEC DLI

Even when you use the CICS-supplied procedures for preparing your program, you
must supply certain translator options.
For a CICS online program containing EXEC DLI commands, you must specify the
DLI and CICS options. For a batch or BMP program containing EXEC DLI
commands, you must specify the DLI option.
You can also specify the options on the EXEC job control statement that invokes
the translator; if you use both methods, the CBL and *PROCESS statement
overrides those in the EXEC statement. For more information on the translator
options, see CICS/ESA Application Programming Guide.
You must ensure that the translator options you use in a COBOL program do not
conflict with the COBOL compiler options. When you translate an IBM COBOL for
MVS & VM program, you must use the COBOL for MVS & VM translator option.
Similarly, when you translate a VS COBOL II program, you must use the COBOL II
translator option.
Compiler Options Required for EXEC DLI

If you want to compile your batch COBOL program with COBOL for MVS & VM and
then execute it AMODE(31) on MVS, you must use the compiler option RENT. If
you want to compile your batch COBOL program with VS COBOL II and then
execute it AMODE(31) on MVS, you must use the compiler options RES and RENT.
For information on which compiler options should be used for a CICS program, see
CICS Application Programming Reference.

Preparing your Program for Execution
Linkage Editor Options Required for EXEC DLI
If the compiler being used supports it, you can link a program written with EXEC
commands as AMODE(31) RMODE(ANY).

Chapter 5. Processing Fast Path Databases
Using EXEC DLI commands under DBCTL, a CICS program or a batch-oriented
BMP can access DEDBs. Parameters allow your program to use facilities of the
DEDBs such as subset pointers, described below.
A DEDB contains a root segment and as many as 127 types of dependent

segment. One of these types can be a sequential dependent; the other 126 are
direct dependents. Sequential dependent segments are stored in chronological
order. Direct dependent segments are stored hierarchically.
DEDBs provide high data availability. Each DEDB can be partitioned, or divided into
multiple “areas.” Each area contains a different set of database records. In addition,
you can make up to seven copies of each area data set. If an error exists in one
copy of an area, application programs can access the data by using another copy
of that area. This is transparent to the application program. When an error occurs to
data in a DEDB, IMS does not stop the database. It makes the data in error
unavailable, but continues to schedule and process application programs. Programs
that do not need the data in error are unaffected.
DEDBs can be shared among application programs in separate IMS systems.

Sharing DEDBs is virtually the same as sharing full-function databases, and most of
the same rules apply. IMS systems can share DEDBs at the area level (instead of
at the database level as with full-function databases), or at the block level.
Related Reading: For more information on DEDB data sharing, see the description
of administering IMS systems that share data in IMS Version 7 Administration
Guide: System.
Processing DEDBs with Subset Pointers

Subset pointers and the options you use with them are optimization tools that
significantly improve the efficiency of your program when you need to process long
segment chains. Subset pointers divide a chain of segment occurrences under the
same parent into two or more groups, or subsets. You can define as many as eight
subset pointers for any segment type. You then define the subset pointers from
within an application program (see “Using Subset Pointers” on page 95). Each
subset pointer points to the start of a new subset. For example, in Figure 10,
suppose you defined one subset pointer that divided the last three segment
occurrences from the first four. Your program could then refer to that subset pointer
through options, and directly retrieve the last three segment occurrences.
Figure 10. Processing a Long Chain of Segment Occurrences with Subset Pointers

You can use subset pointers at any level of the database hierarchy, except at the
root level. Subset pointers used for the root level are ignored.
2 Figure 11 and Figure 12 show some of the ways you can set subset pointers.
2 Subset pointers are independent of one another, which means that you can set one
2 or more pointers to any segment in the chain. For example, you could set more
2 than one subset pointer to a segment, as shown in Figure 11.
Figure 11. Examples of Setting Subset Pointers
2 Alternatively, you could define a one-to-one relationship between the pointers and
2 the segments, as shown in Figure 12.
Figure 12. More Examples of Setting Subset Pointers
Figure 13 on page 94 shows how the use of subset pointers divides a chain of
segment occurrences under the same parent into subsets. Each subset ends with
the last segment in the entire chain. For example, the last segment in the subset
defined by subset pointer 1 is B7.
Figure 13. How Subset Pointers Divide a Chain into Subsets

Before You Use Subset Pointers
For your program to use subset pointers, the pointers must be defined in the DBD
for the DEDB, and in your program’s PSB:
v In the DBD, you specify the number of pointers for a segment chain. You can
specify as many as eight pointers for any segment chain.
v In the PSB, you specify which pointers your program uses; you define this on the
SENSEG statement. (Each pointer is defined as an integer from 1 to 8.) You also
specify on the SENSEG statement whether your program can set the pointers it
uses. If your program has read-only sensitivity, it cannot set pointers, but can
only retrieve segments using subset pointers already set. If your program has
update sensitivity, it can update subset pointers by using the SET, SETCOND,
MOVENEXT, and SETZERO options.
After the pointers are defined in the DBD and the PSB, an application program can
set the pointers to segments in a chain. When an application program finishes
executing, the subset pointers used by that program remain as they were set by the
program and are not reset.
Designating Subset Pointers You Want to Use

To use subset pointers in your program, you must know the numbers for the
pointers as they were defined in the PSB. Then, when you use the subset pointer
options, you specify the number for each subset pointer you want to use
immediately after the option; for example, you would use P3 to indicate that you
want to retrieve the first segment occurrence in the subset defined by subset
pointer 3. No default exists, so if you do not include a number between 1 and 8,
IMS considers your qualification statement invalid and returns an AJ status code to
your program.
Using Subset Pointers

To take advantage of subsets, application programs use five options.
GETFIRST Allows you to retrieve the first segment in a subset.
SETZERO Sets a subset pointer to zero.
MOVENEXT Sets a subset pointer to the segment following the current segment.
Current position is at the current segment.
SET Unconditionally sets a subset pointer to the current segment.
Current position is at the current segment.
SETCOND Conditionally sets a subset pointer to the current segment. Current
position is at the current segment.
Our Sample Application

The examples in this section are based on a sample application, the recording of
banking transactions for a passbook account. The transactions are written to a
database as either posted or unposted, depending on whether they were posted to
the customer’s passbook. For example, when Bob Emery does business with the
bank, but forgets to bring in his passbook, an application program writes the
transactions to the database as unposted. The application program sets a subset
pointer to the first unposted transaction, so it can be easily accessed later. The next
time Bob remembers to bring in his passbook, a program posts the transactions.
The program can directly retrieve the first unposted transaction using the subset
pointer that was previously set. After the program has posted the transactions, it
sets the subset pointer to zero; an application program that subsequently updates
Chapter 5. Processing Fast Path Databases 95

the database can determine that no unposted transactions exist. Figure 14
summarizes the processing performed when the passbook is unavailable and when
it is available.
Figure 14. Processing Performed for the Sample Passbook Example
Retrieving the First Segment in the Subset with the GETFIRST

Option
To retrieve the first segment occurrence in the subset, your program issues a Get
command with the GETFIRST option. The GETFIRST option does not set or move
the pointer, but indicates to IMS that you want to establish position on the first
segment occurrence in the subset. The GETFIRST option is like the FIRST option,
except that the GETFIRST option applies to the subset instead of to the entire
segment chain.
Using the passbook account example described earlier, say that Bob Emery visits
the bank, bringing his passbook, and you want to post all the unposted
transactions. Because subset pointer 1 was previously set to the first unposted
transaction, your program could use the following command to retrieve that
transaction:
EXEC DLI GU SEGMENT(A) WHERE(AKEY = ’A1’)
SEGMENT(B) INTO(BAREA) GETFIRST(’1’);

As shown by Figure 15, this command retrieves segment B5. To continue
processing segments in the chain, you can issue Get Next commands, as you
would if you were not using subset pointers.
Figure 15. Retrieving the First Segment in a Chain of Segments
If the subset does not exist (subset pointer 1 has been set to zero), IMS returns a
GE status code, and your position in the database immediately follows the last
segment in the chain. Using the passbook example, the GE status code indicates
that no unposted transactions exist.
You can specify only one GETFIRST option per qualification statement; if you use
more than one GETFIRST in a qualification statement, IMS returns an AJ status
code to your program. The rules for using the GETFIRST option are:
1. You can use GETFIRST with all options except:
v FIRST
v LOCKCLASS
v LOCKED
2. Other options take effect after the GETFIRST option has, and position has been
established on the first segment in the subset.
3. If you use GETFIRST with LAST, the last segment in the segment chain is
retrieved.
4. If the subset pointer specified with GETFIRST is not set, IMS returns a GE
status code, not the last segment in the segment chain. See “Setting the Subset
Pointers with the SETZERO, MOVENEXT, SET, and SETCOND Options”
5. Do not use GETFIRST with FIRST. This causes you to receive an AJ status
code.
6. GETFIRST overrides all insert rules, including LAST.
Setting the Subset Pointers with the SETZERO, MOVENEXT, SET,

and SETCOND Options
The SETZERO, MOVENEXT, SET, and SETCOND options allow you to redefine
subsets by modifying the subset pointers. Before your program can set a subset
pointer, it must establish a position in the database. A command must be fully
satisfied before a subset pointer is set. The segment a pointer is set to depends on
your current position at the completion of the command. If a command to retrieve a
segment is not completely satisfied, and a position is not established, the subset
pointers remain as they were before the command was issued.
v Setting the subset pointer to zero: SETZERO
The SETZERO option sets the value of the subset pointer to zero. After your
program issues a command with the SETZERO option, the pointer is no longer
set to a segment; the subset defined by that pointer no longer exists. (IMS
returns a status code of GE to your program if you try to use a subset pointer
having a value of zero.)

Using the passbook example described earlier, say that you used the GETFIRST
option to retrieve the first unposted transaction. You would then process the
chain of segments, posting the transactions. After posting the transactions and
inserting any new ones into the chain, you would use the SETZERO option to set
the subset pointer to zero as shown in the following command:
EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = ’A1’)
SEGMENT(B) FROM(BAREA) SETZERO(’1’);
After this command, subset pointer 1 would be set to zero, indicating to a

program updating the database later on that no unposted transactions exist.
v Moving the subset pointer forward to the next segment after your current
position: MOVENEXT
To move the subset pointer forward to the next segment after your current
position, your program issues a command with the MOVENEXT option. Using the
passbook account example described earlier, say that you wanted to post some
of the transactions, but not all, and that you wanted the subset pointer to be set
to the first unposted transaction. The following command sets subset pointer 1 to
segment B6, as shown in Figure 16.
SEGMENT(B) INTO(BAREA) GETFIRST(’1’) MOVENEXT(’1’);
If the current segment is the last in the chain, and you use a MOVENEXT option,
IMS sets the pointer to zero.
Figure 16. Moving the Subset Pointer to the Next Segment after Your Current Position
v Setting the subset pointer unconditionally: SET

You use the SET option to set a subset pointer. The SET option sets a subset
pointer unconditionally, regardless of whether or not it is already set. When your
program issues a command that includes the SET option, IMS sets the pointer to
your current position.
For example, to retrieve the first B segment occurrence in the subset defined by
subset pointer 1, and to reset pointer 1 at the next B segment occurrence, you
would issue the following commands:

SEGMENT(B) INTO(BAREA) GETFIRST(’1’);
EXEC DLI GN SEGMENT(B) INTO(BAREA) SET(’1’);
After you have issued these commands, instead of pointing to segment B5,
subset pointer 1 points to segment B6, as shown in Figure 17.
Figure 17. Unconditionally Setting the Subset Pointer to Your Current Position
v Setting the subset pointer conditionally: SETCOND

Your program uses the SETCOND option to conditionally set the subset pointer.
The SETCOND option is similar to the SET option; the only difference is that,
with the SETCOND option, IMS updates the subset pointer only if the subset
pointer is not already set to a segment.
Using the passbook example, say that Bob Emery visits the bank and forgets to
bring his passbook; you add the unposted transactions to the database. You want
to set the pointer to the first unposted transaction, so later, when you post the
transactions, you can immediately access the first one. The following command
sets the subset pointer to the transaction you are inserting, if it is the first
unposted one:
SEGMENT(B) FROM(BAREA) SETCOND(’1’);
As shown by Figure 18 on page 100, this command sets subset pointer 1 to

segment B5. If unposted transactions already existed, the subset pointer is not
changed.

Figure 18. Conditionally Setting the Subset Pointer to Your Current Position
Inserting Segments in a Subset

When you use the GETFIRST option to insert a non-keyed segment in a subset,
the new segment is inserted before the first segment occurrence in the subset.
However, the subset pointer is not automatically set to the new segment
occurrence. For example, the following command inserts a new B segment
occurrence in front of segment B5, but does not set subset pointer 1 to point to the
new B segment occurrence:
SEGMENT(B) FROM(BAREA) GETFIRST(’1’);
To set subset pointer 1 to the new segment, you use the SET option along with the
GETFIRST option, as shown in the following example:
SEGMENT(B) FROM(BAREA) GETFIRST(’1’) SET (’1’);
If the subset does not exist (subset pointer 1 has been set to zero), the segment is
added to the end of the segment chain.
Deleting the Segment Pointed to By a Subset Pointer

If you delete the segment pointed to by a subset pointer, the subset pointer points
to the next segment occurrence in the chain. If the segment you delete is the last in
the chain, the subset pointer is set to zero.
Combining Options
You can use the SET, MOVENEXT, and SETCOND options with other options, and
you can combine subset pointer options with each other, provided they do not
conflict. For example, you can use GETFIRST and SET together, but you cannot
use SET and SETZERO together because their functions conflict. If you combine
options that conflict, IMS returns an AJ status code to your program.
You can use one GETFIRST option per qualification statement, and one update
option (SETZERO, MOVENEXT, SET, or SETCOND) for each subset pointer.
Subset Pointer Status Codes
If you make an error in a qualification statement that contains subset pointer
options, IMS can return these status codes to your program:
AJ The qualification statement used a GETFIRST, SET, SETZERO, SETCOND,
or MOVENEXT option for a segment for which there are no subset pointers
defined in the DBD.
The subset options included in the qualification statement are in conflict; for
example, if one qualification statement contained a SET option and a
SETZERO option for the same subset pointer, IMS would return an AJ
status code. S means to set the pointer to current position; Z means to set
the pointer to zero. You cannot use these options together in one
qualification statement.
The qualification statement included more than one GETFIRST option.
The pointer number following a subset pointer option is invalid. You either
did not include a number, or included an invalid character. The number
following the option must be between 1 and 8, inclusive.
AM The subset pointer referenced in the qualification statement was not
specified in the program’s PSB. For example, if your program’s PSB
specifies that your program can use subset pointers 1 and 4, and your
qualification statement referenced subset pointer 5, IMS would return an AM
status code to your program.
Your program tried to use an option that updates the pointer (SET,
SETCOND, or MOVENEXT) but the program’s PSB did not specify pointer
update sensitivity.
The POS Command

You can use the POS command (only with DEDBs) to do the following:
v Retrieve the location of a specific sequential dependent segment, or retrieves the
location of the last inserted sequential dependent segment.
v Tell you the amount of unused space within each DEDB area. For example, you
can use the position information that IMS returns for a POS command to scan or
delete the sequential dependent segments for a particular time period.
For the syntax of the POS command, see “POS Command” on page 39.
If the area the POS command specifies is unavailable, the I/O area is unchanged
and the status code FH is returned.
Locating a Specific Sequential Dependent

When you have position on a particular root segment, you can retrieve the position
information and the area name of a specific sequential dependent of that root. If
you have a position established on a sequential dependent segment, the search
starts from that position. IMS returns the position information for the first sequential
dependent segment that satisfies the command.
To retrieve this information, you issue a POS command with a qualification statement
containing the segment name of the sequential dependent. The current position
after this kind of POS command is in the same place that it is after a GNP command.
After a successful POS command, the I/O area contains:

The POS Command
LL A 2-byte field giving the total length of the data in the I/O area, in
binary.
Area Name An 8-byte field giving the ddname from the AREA statement.
Position An 8-byte field containing the position information for the requested
segment.
If the sequential dependent segment that is the target of the POS
command is inserted in the same synchronization interval, no
position information is returned. Bytes 11-18 contain X'FF'; other
fields contain normal data.
Unused CIs A 4-byte field containing the number of unused CIs in the sequential
dependent part.
Unused CIs A 4-byte field containing the number of unused CIs in the
independent overflow part.
Locating the Last Inserted Sequential Dependent Segment

You can also retrieve the position information for the most recently inserted
sequential dependent segment of a given root segment. To do this, you issue a POS
command with a qualification statement containing the root segment as the
segment name. The current position after this type of command follows the same
rules as position after a GU.
After a successful command, the I/O area contains:

LL A 2-byte field containing the total length of the data in the I/O area,
in binary.
Position An 8-byte field containing the position information for the most
recently inserted sequential dependent segment. This field contains
zeros provided no sequential dependent for this root exist.
dependent part.
Identifying Free Space

To retrieve the area name and the next available position within the sequential
dependent part from all online areas, you can issue an unqualified POS command.
This type of command also retrieves the unused space in the independent overflow
and sequential dependent parts.
After a successful unqualified POS command, the I/O area contains the length (LL),
followed by as many entries as there are areas within the database. Each entry
contains the second through the fifth fields shown below:
LL A 2-byte field containing the total length of the data in the I/O area,
in binary. The length includes the 2 bytes for the LL field, plus 24
bytes for each entry.
Position An 8-byte field giving the next available position within the
sequential dependent part.
The POS Command
dependent part.
The P Processing Option

If the P processing option has been specified (with the PROCOPT parameter) in the
PCB for your program, a GC status code is returned to your program whenever a
command to retrieve or insert a segment causes a Unit of Work (UOW) boundary to
be crossed. For more information on the UOW for DEDBs, see IMS Version 7
Administration Guide: Database Manager. Although crossing the UOW boundary
probably has no particular significance for your program, the GC status code
indicates that this is a good time to issue a CHKP command. The advantages of
doing this are:
v Your position in the database is kept. Issuing a CHKP normally causes position in
the database to be lost, and the application program has to reestablish position
before it can resume processing.
v Commit points occur at regular intervals.
When a GC status code is returned, no data is retrieved or inserted. In your

program, you can either:
v Issue a CHKP command, and resume database processing by reissuing the
command that caused the GC status code.
v Ignore the GC status code and resume database processing by reissuing the
command that caused the status code.

The POS Command
Chapter 6. Recovering Databases and Maintaining Database
Integrity
This chapter describes the commands you can use to help recover data accessed
by your program and maintain data integrity:
v The Basic Checkpoint command, CHKP, which you can use to issue checkpoints
from a batch or BMP program
v The Symbolic Checkpoint command, SYMCHKP, which you can use to issue
checkpoints from a batch or BMP program and to specify data areas that can be
restored when you restart your program
v The Extended Restart command, XRST, which you can use along with symbolic
checkpoints to start or restart your batch or BMP program
v The rollback commands, ROLL and ROLB, which you can use to dynamically back
out database changes from a batch or BMP program
v The managing-backout-points commands, SETS and ROLS, which you can use to
set multiple backout points and then return to these points later
v The Dequeue command, DEQ, which releases previously reserved segments
To use any of the commands, you must have defined an I/O PCB for your program,
except for the DEDB DEQ calls, which are issued against a DEDB PCB.
Related Reading: For more information on checkpoint and rollback commands, see
the description “Using the I/O PCB, PSB, and PCB” on page 11, and the manuals
IMS Version 7 Utilities Reference: System and IMS Version 7 Application
Programming: Design Guide.
Issuing Checkpoints in a Batch or BMP Program

Basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Batch programs can use either the Symbolic Checkpoint or the Basic Checkpoint
command.
changes to the database and to establish places from which the batch or BMP
program can be restarted, in cases of abnormal termination.
Requirement: You must not use the CHKPT=EOV parameter on any DD statement
to take an IMS checkpoint.
See IMS Version 7 Application Programming: Design Guide for an explanation of

when and why you should issue checkpoints in your program. Because both
checkpoint commands cause a loss of database position at the time the command
is issued, you must reestablish position with a GU command or other methods.
You cannot reestablish position in the midst of non-unique keys or non-keyed

segments.
Issuing the CHKP Command

When you issue a CHKP command, you must provide the code for restarting your
program and you must specify the ID for the checkpoint. You can supply either the

Issuing Checkpoints
name of a data area in your program that contains the ID, or you can supply the
actual ID, enclosed in single quotes. For example, either of the following commands
is valid:
EXEC DLI CHKP ID(chkpid);
EXEC DLI CHKP ID('CHKP0007');
Issuing the SYMCHKP Command

The SYMCHKP command in batch and BMP programs:
v Works with the Extended Restart (XRST) command to restart your program if it
terminates abnormally. which are restored when your program is restarted. You
can save variables, counters, and status information.
For examples of how to specify the SYMCHKP command, see “SYMCHKP Command”
on page 61.
Restarting Your Program and Checking for Position

Programs that issue Symbolic Checkpoint commands must also issue the Extended
Restart (XRST) command. You must issue XRST once, as the first command in the
program. You can use the XRST command to start your program normally, or to
restart it in case of an abnormal termination. You can restart your program from one
of the following:
v A specific checkpoint ID
v A time/date stamp
Because the XRST command attempts to reposition the database, your program also
needs to check for correct position.

Commands
When a batch program determines that some of its processing is invalid, the ROLL
and ROLB commands make it possible for the program to remove the effects of its
inaccurate processing.
You can use both ROLL and ROLB in batch programs. You can only use the ROLB
command in batch programs if the system log is stored on direct access storage
and if you have specified BKO=Y in the parm field of your JCL.
Issuing either of these commands causes DL/I to back out any changes your
program has made to the database since its last checkpoint, or since the beginning
of the program if your program has not issued a checkpoint.
Using Intermediate Backout Points: The SETS and ROLS Commands

Use the SETS and ROLS commands to define multiple points at which to preserve the
state of DL/I full-function databases and to return to these points later. (For
example, you can use them to allow your program to handle situations that can
occur when PSB scheduling complete without all of the referenced DL/I databases
being available.)
The SETS and ROLS commands apply only to DL/I full-function databases. Therefore,
if a logical unit of work (LUW) is updating recoverable resources other than
full-function databases (VSAM files, for example), the SETS and ROLS requests have
Intermediate Backout Points
no effect on the non-DL/I resources. The backout points are not CICS commit
points; they are intermediate backout points that apply only to DBCTL resources.
Your program must ensure the consistency of all the resources involved.
SETS Command
Before initiating a set of DL/I requests to perform a function, you can use a SETS
command to define points in your application at which to preserve the state of DL/I
databases. Your application can issue a ROLS command later if it cannot complete
the function.
ROLS Command
You can use the ROLS command to back out to the state all full-function databases
were in before either a specific SETS request or the most recent commit point.

Intermediate Backout Points
Chapter 7. Using Data Availability Enhancements
Your program might fail when it receives a status code indicating that a DL/I
full-function database is unavailable. To avoid this, you can use data availability
enhancements. After a PSB has been scheduled in DBCTL, your application
program can issue requests to indicate to IMS that the program can handle data
availability status codes and to obtain information about the availability of each
database.
Accepting Database Availability Status Codes

These status codes occur because PSB scheduling was completed without all of
the referenced databases being available. Use ACCEPT to tell DBCTL to return a
status code instead of abending the program:
EXEC DLI ACCEPT STATUSGROUP('A');
Obtaining Information about Database Availability

You can put data availability status codes into each of the DB PCBs under the
following conditions:
v In a CICS DBCTL environment, by using the PSB scheduling request command,
SCHD.
v In a Batch or BMP environment, at initialization time.
You can obtain the data availability status codes within the DL/I interface block
(DIB) by using the following QUERY command:
EXEC DLI QUERY USING PCB(n);
n specifies the PCB.
The QUERY command is used after scheduling the PSB but before making the first
database call. If the program has already issued a call using a DB PCB, then the
QUERY command must follow the REFRESH command:
EXEC DLI REFRESH DBQUERY
The REFRESH command updates the information in the DIB. You can only issue this
command one time.
For full-function databases, the DIBSTAT should contain NA, NU, TH, or blanks. For
MSDBs and DEDBs, the DIBSTAT always contains blanks.
If a CICS command language translator has been used to translate the EXEC DLI
commands, then, in addition to data availability status, the DBDNAME will be
returned in the DIB field DIBDBDNM. Also, the name of the database organization
will be returned in the DIB field DIBDBORG.
For an explanation of the codes, see “Status Code Explanations” on page 127.

Part 2. For Your Reference

Chapter 8. Comparing Command-Level and Call-Level
Programs
This chapter summarizes some of the differences between command- and call-level
programs. If you are already familiar with DL/I calls, but not with EXEC DLI
commands, this section will help you understand the commands and options you
can use to perform the tasks you performed using calls.
v Table 3 provides a quick reference for using DL/I calls.
v Table 4 compares EXEC DLI commands with DL/I calls. For example, in a
command-level program, you use the LOAD command instead of the ISRT call to
initially load a database.
v Table 5 on page 114 compares the options you use with EXEC DLI commands
with the command codes you use with DL/I calls. For example, the LOCKED
option performs the same function as a Q command code.
Table 3. DL/I Calls Available to IMS and CICS Command-Level Application Programs
Batch- CICS with
CHKP call (symbolic) Yes Yes No
CHKP call (basic) Yes Yes No
2
GSCD call Yes No No
INIT call Yes Yes Yes
ISRT call (initial load) Yes No No
ISRT call Yes Yes Yes
LOG call Yes Yes Yes
SCHD call No No Yes
ROLB call Yes Yes No
ROLL call Yes Yes No
3
ROLS call (Roll Back to SETS) Yes Yes Yes
ROLS call (Roll Back to Commit) Yes Yes Yes
3
SETS call Yes Yes Yes
4
STAT call Yes Yes Yes
TERM call No No Yes
XRST call Yes Yes No
Notes:
1. In a CICS remote DL/I environment, CALLs in the CICS-DBCTL column are supported if you are shipping a
function to a remote CICS that uses DBCTL.
2. GSCD is a Product-sensitive programming interface.
3. SETS and ROLS calls are not valid when the PSB contains a DEDB.
Table 4. Comparing Call-Level and Command-Level Programs: Commands and Calls

Call-Level Command-Level Allows you to...
INIT call ACCEPT command Initialize for data availability status codes.

Comparing Command-Level and Call-Level Programs
Table 4. Comparing Call-Level and Command-Level Programs: Commands and Calls (continued)
Call-Level Command-Level Allows you to...
CHKP call (basic) CHKP command Issue a basic checkpoint.
DEQ call DEQ command Release segments retrieved using LOCKCLASS option or Q
command code.
DLET call DLET command Delete segments from a database.
GU, GN, and GNP GU, GN, and GNP Retrieve segments from a database.
calls commands1
GHU, GHN, and GU, GN, and GNP Retrieve segments from a database for updating.
GHNP calls1 commands1
GSCD call GSCD call2 Retrieve system addresses.
ISRT call ISRT command Add segments to a database.
ISRT call LOAD command Initially load a database.
LOG call LOG command Write a message to the system log.
POS call POS command Retrieve positioning and/or space usage in a DEDB area.
INIT call ACCEPT command Initialize for data availability status.
INIT call QUERY command Obtain information of initial data availability.
INIT call REFRESH command Availability information after using a PCB.
REPL call REPL command Replace segments in a database.
XRST call RETRIEVE command Issue an extended restart.
ROLL or ROLB call ROLL or ROLB Dynamically back out changes.
command
ROLS call ROLS command Back out to a previously set backout point.
PCB call SCHD command Schedule a PSB.
SETS call SETS command Set a backout point.
SETU call SETU command Set a backout point even if unsupported PCBs (like DEDBs or
MSDBs) are present.
STAT call3 STAT command Obtain system and buffer pool statistics.
CHKP call (extended) SYMCHKP command Issue a symbolic checkpoint.
TERM call TERM command Terminate a PSB.
XRST call XRST command Issue an extended restart.
Notes:
1. Get commands are just like Get Hold calls, and the performance of Get commands and Get calls is the same.
2. You can use the GSCD call in a batch command-level program. GSCD is a Product-sensitive programming
interface.
Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options
Call- Level Command-Level Allows You to...
C KEYS option Use the concatenated key of a segment to identify the segment.
D INTO or FROM specified on Retrieve or insert a sequence of segments in a hierarchic path using
segment level to be only one request, instead of having to use a separate request for each
retrieved or inserted. segment. (Path call or command).
Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options (continued)
Call- Level Command-Level Allows You to...
F FIRST option Back up to the first occurrence of a segment under its parent when
searching for a particular segment occurrence. Disregarded for a root
segment.
L LAST option Retrieve the last occurrence of a segment under its parent.
M MOVENEXT option Set a subset pointer to the segment following the current segment.
N Leave out the SEGMENT Designate segments you do not want replaced, when replacing
option for segments you do segments after a get hold request. Usually used when replacing a path
not want replaced. of segments.
P SETPARENT Set parentage at a higher level than what it usually is (the lowest
hierarchic level of the request).
Q LOCKCLASS, LOCKED Reserve a segment so that other programs are not able to update it
until you have finished processing it.
R GETFIRST option Retrieve the first segment in a subset.
S SET option Unconditionally set a subset pointer to the current segment.
U No equivalent for command Limit the search for a segment to the dependents of the segment
level programs. occurrence on which position is established.
V CURRENT option Use the current position at this hierarchic level and above as
qualification for the segment.
W SETCOND option Conditionally set a subset pointer to the current segment.
Z SETZERO option Set a subset pointer to zero.
– No command-level Null. Use an SSA in command code format without specifying the
equivalent. command code. Can be replaced during execution with the command
codes you want.
Chapter 8. Comparing Command-Level and Call-Level Programs 115

Chapter 9. DL/I Status Codes
This section contains reference information on all IMS status codes. The information
is divided into two parts:
v Status code tables
– Database Calls
– Message Calls
– System Service Calls
v Status code explanations
Status Code Tables

The status code tables briefly explain each status code and list the calls for which
you can receive each status code. The tables also include a column of numbers
representing the category of each status code; the numbers and the corresponding
explanations are below.
For information about each of the status codes, see Table 6, Table 7 on page 122,
and Table 8 on page 124.
Exception: Although the calls APSB, DPSB, and ROLL are included in Table 8 on
page 124, they do not receive status codes.
Categories of DL/I Status Codes

The numbers in the category column of the status codes tables refer to the
following categories of status codes:
1. Those indicating exceptional but valid conditions. The call is completed.
2. Those indicating warning or information-only status codes on successful calls
(for example, GA and GK). If the call requested data, IMS returns the data to
the I/O area. The call is completed.
3. Those indicating warning status codes on successful calls when data is not
returned to the I/O area. The call is completed.
4. Those indicating improper user specifications. Most status codes are in this
category. The call is not completed.
5. Those indicating system, I/O, or security errors encountered during the
execution of I/O requests. The call is not completed.
6. Those indicating unavailable data.
Table 6. Database Calls
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
TERM
(ADD)
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
AB X X X X X X X X X X 4 Segment I/O area required;
none specified in call. Only
applies to full-function DEQ
calls.
AC X X X X X X 4 Hierarchic error in SSAs.

Status Code Tables
Table 6. Database Calls (continued)
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
AD X X X X X X X X X X 4 Function parameter
incorrect. Only applies to
full-function DEQ calls.
AF X X 4 GSAM detected invalid
variable-length record.
AH X X 4 Required SSA missing.
Options list not specified in
SETO call.
AI X X X X X X 5 Data management OPEN
error.
AJ X X X X X X X X 4 Incorrect parameter format in
I/O area; incorrect SSA
format; incorrect command
used to insert a logical child
segment. I/O area length in
AIB is invalid; incorrect class
parameter specified in Fast
Path Q command code.
AK X X X X X X X 4 Invalid SSA field name.
AM X X X X X X X X 4 Call function not compatible
with processing option,
segment sensitivity,
transaction code, definition,
or program type.
AO X X X X X X X 5 I/O error: OSAM, BSAM, or
VSAM.
AT X X X 4 User I/O area too long.
AU X X X X X X 4 SSAs too long.
BA X X X X X 6 Call could not be completed
because data was
unavailable.
BB X X X X X 6 Call could not be completed
because data was
unavailable and updates are
backed out only since the
last commit point.
BC X 6 Call could not be completed
because of a deadlock
occurrence; updates are
backed out only since the
last commit point.
DA X X 4 Segment key field or
non-replaceable field has
been changed.
DJ X 4 No preceding successful
GHU or GHN call or an SSA
supplied at a level not
retrieved.
Status Code Tables
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
DX X 4 Violated delete rule.
EM X Normally for a utility.
FA X X 4 MSDB arithmetic overflow
error occurred.
FC X 4 POS call for direct
dependent segments only.
FD X X X X X X X 2 Deadlock occurred.
FE X 4 FSA error, not field name.
FF X 3 No space in MSDB.
FG X 4 Combination of FE and FW
codes.
FH X X X X X X X 3 DEDB inaccessible.
FI X X X X X X X 4 I/O area not in user’s
dependent region.
FM X X X X X X 4 Randomizing routine return
code = 4.
FN X 4 FSA error, field name.
FP X X X 4 Invalid hexadecimal or
decimal data.
FR X X X X X X X X 5 Total buffer allocation
exceeded.
FS X 3 DEDB areas are full.
FT X X X X X X 4 Too many SSAs on call.
FV X 3 MSDB verify condition failed.
FW X X X X X X X X X 2 More resources needed than
normally allowed. For the
DEQ call, Fast Path was not
able to release any buffers.
FY X X X X X X X X 4 Attempt to read sequential
data preceding the current
position.
GA X X 2 Crossing hierarchical
boundary.
GB X 1 End of database.
GC X X X X 3 Crossing unit of work (UOW)
boundary.
GD X 1 Call did not have SSAs for
all levels above insert and
has lost segment position.
GE X X X X 1 Segment not found.
GG X X X 5 Segment contains invalid
pointer.
Chapter 9. DL/I Status Codes 119

Status Code Tables
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
GK X X 2 Crossing segment
boundaries on same level.
GL X 4 Invalid user log code. Only
applies to full-function DEQ
calls.
GP X X X 4 No parentage established.
HT X Normally for a utility.
II X 3 Segment already exists.
IX X 4 Violated insert rule.
1 L2 X 1 The area lock failed.
LB X 1 Segment being loaded
already exists in database.
LC X 4 Key field of segments out of
sequence.
LD X 4 No parent for this segment
has been loaded.
LE X 4 Sequence of sibling
segments not the same as
DBD sequence.
LF X 4 An attempt was made to
load a logical child segment
in either a HALDB PHDAM
or PHIDAM database.
1 LS X 1 Work may be backed out
1 because sufficient CI space
1 was not preallocated for the
1 area, or the SDEP CI lock
1 failed.
NA X X 6 A database was unavailable.
NE X 3 DL/I call issued by index
maintenance cannot find
segment.
2 NI X X X 1 Index maintenance found
2 duplicate segments in the
2 index or it detected an index
2 maintenance open error.
NO X X X 5 I/O error: OSAM, BSAM, or
VSAM.
NU X X 6 A database was unavailable
for update.
OS X Normally for a utility.
RX X 4 Violated replace rule.
TH X 4 No PSB was scheduled
(command-level only).
Status Code Tables
REFRESH
Category
(GSAM)
(GSAM)
QUERY
(LOAD)
PCB
GHNP
OPEN
(ADD)
TERM
DLET,
CLSE
REPL
GNP,
ISRT
ISRT
GHU
GHN
DEQ
POS
FLD
Status
GU,
GN,
Code Description
TI X 4 Invalid path to segment
X X X X X X 5 DL/I not active
X X X X X X 5 Invalid system DIB
TO X 4 Path replace error
TP X X X X X X 4 Invalid number for PCB or
invalid processing option
TR X X X X X X X X 4 CICS XDLIPRE user exit
determined the preceding
request should not be
executed.
TY X X X X X X 5 Database not open
TZ X X X X X X 5 Length of segment greater
than 64 KB.
UC X 1 Checkpoint taken (Utility
Control Facility (UCF) status
code).
US X 1 Stop (UCF status code).
UX X 1 Checkpoint and stop (UCF
status code).
V1 X X X 4 Segment length not within
limits of DBDGEN.
V2 X X X X X X X X 4 Segment length invalid
V3 X X X X 4 Field length missing or
invalid (command-level only).
V4 X X X X X X 4 Length of variable-length
segment invalid
V5 X X X X X 4 Offset if invalid
V6 X X X X X 4 Concatenated key length
invalid (command-level only).
XX X X X X 5 Internal GSAM error.
1
bb X X X X X X X X X X X X X X 1 No status code returned.
Proceed.
Note:
1. bb indicates blank.

Status Code Tables
Table 7. Message Calls
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
AA X X 4 CHNG call for alternate response PCB can specify only
logical terminal destination; transaction code destination
specified.
AB X X X X X X X 4 Segment I/O area required; none specified in call.
AD X X X X X X X X 4 Function parameter invalid.
AH X 4 Required SSA missing. Options list not specified in SETO
call.
AJ X 4 Invalid parameter format in I/O area; invalid SSA format;
invalid command used to insert a logical child segment. I/O
area length in AIB is invalid.
AL X X X X X X X X 4 Call using I/O PCB in batch program.
AP X X X X X X X X 4 Specifying more than four user call parameters for a TP PCB
is not valid.
AR X X 4 Error in option list related to IMS option keyword.
AS X X 4 The PRTO= option contained invalid data set processing
options.
AT X X X 4 User I/O area too long.
AX X X X X 5 System error. Call not completed successfully.
AY X 4 Alternate response PCB referenced by ISRT call has more
than one physical terminal assigned for input purposes. Notify
master terminal operator.
AZ X 4 The conversational program has issued a PURG call to PCB
that cannot be purged.
A1 X X X 4 AUTH call attempted with invalid generic class name or error
occurred during attempt to set destination name specified in
the CHNG or ISRT call.
A2 X 4 Call attempted with invalid PCB (PCB not modifiable or ISRT
operation already done).
A3 X X 4 Call attempted to a modifiable TP PCB with no destination
set.
A4 X X X 4 Security violation detected during processing of either an
AUTH call, a CHNG call, or an ISRT on a conversational
response.
A5 X X 4 Format name specified on second or subsequent message
ISRT or PURG.
A6 X 4 Output segment size limit exceeded on call.
A7 X 4 Number of output segments inserted exceeded the limit by
one. Any further queue manager calls are prohibited to
prevent message queue overflow.
A8 X 4 ISRT to alternate response PCB followed ISRT to I/O PCB or
vice versa.
A9 X 4 Alternate response PCB referenced by call requires that the
source physical terminal receive the output response.
CA X 4 No such command. No command responses produced.
Status Code Tables
Table 7. Message Calls (continued)
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
CB X 4 Command, as entered, not allowed for AOI. No command
responses produced.
CC X 2 Command executed. One or more command responses
produced.
CD X 4 Entered command violates security. No command responses
produced.
CE X 2 Transaction rescheduled after CMD call. Commit point had
not been reached.
CF X 2 Message on queue before IMS was last started.
CG X 2 Transaction originated from AOI exit routine.
CH X 5 AOI detected system error; CMD request not processed.
Reissue CMD call.
CI X 2 Transaction on queue before IMS last started. Transaction
rescheduled. Commit point not reached.
CJ X 2 Transaction from AOI exit routine. Message rescheduled.
Commit point not reached.
CK X 2 Transaction from AOI exit routine. Message on queue before
IMS last started.
CL X 2 Transaction from AOI exit routine. Message on queue before
IMS last started. Message rescheduled. Commit point had not
been reached.
CM X 3 Command executed. No command response produced.
CN X 4 IOASIZE= parameter on PSBGEN macro does not meet
minimum requirement for CMD call.
E1 X X 4 The DFSMSCE0 user routing exit rejected the CHNG or ISRT
call.
call.
call.
FH X 3 DEDB inaccessible.
FI X X X 4 I/O area not in user’s dependent region.
FS X 3 DEDB areas are full.
FV X 3 MSDB verify condition failed.
2 MR X X X X X X 4 Error detected by the Queue Control Facility (QCF) routines.
QC X 3 No more input messages exist.
QD X X 3 No more segments exist for this message.
QE X X 4 GN request before GU. GCMD request before CMD.
QF X X X X 4 Segment less than five characters (segment length is
message text length plus four control characters).

Status Code Tables
Table 7. Message Calls (continued)
Category
PCB
GCMD
CHNG
PURG
AUTH
SETO
ISRT
CMD
Status
GU
GN
Code Description
QH X X X X 4 Terminal symbolic error; output designation unknown to IMS
(logical terminals or transaction code). Either the message
segment LL is not at least 5 bytes or the destination name in
I/O area is blank or invalid.
TG X 4 No PSB was scheduled (command-level only).
X 5 Invalid system DIB (command-level only).
TP X 4 Invalid number for PCB or invalid processing option
TY X 5 Database not open (command-level only).
TZ X 5 Length of segment greater than 64 KB.
XA X 4 Attempt to continue processing the conversation by passing
SPA by a program-to-program switch after answering
terminal.
XB X 4 Program passed SPA to other program, but trying to respond.
XC X 4 Program inserted message with Z1 field bits set. These bits
are reserved for system use.
XE X 4 Tried to ISRT SPA to express PCB.
XF X X 4 Alternate PCB specified in ISRT call for SPA had destination
set to a logical terminal, but was not defined as
ALTRESP=YES. MSC direct routing does not support
program-to-program switch between conversational
transactions.
XG X 4 Current conversation requires fixed-length SPAs. Attempt was
made to insert SPA to transaction with a different or nonfixed-
length SPA.
X2 X X 4 First insert to transaction code PCB that is conversational is
not a SPA.
X3 X 4 Invalid SPA.
X4 X 4 Insert to a transaction code PCB that is not conversational
and the segment is a SPA.
X5 X 4 Insert of multiple SPAs to transaction code PCB.
X6 X 4 Invalid transaction code name inserted into SPA.
X7 X 4 Length of SPA is incorrect (user modified first 6 bytes).
1
bb X X X X X X X X X 1 No status code returned. Proceed.
Note:
Table 8. System Service Calls

Category
SNAP1
PCB
CHKP
ROLB
SYNC
ROLS
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
AB X X X X X 4 Segment I/O area required; none

specified in call.
Status Code Tables
Table 8. System Service Calls (continued)
Category
SNAP1
PCB
CHKP
ROLB
SYNC
ROLS
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
AC X 4 Hierarchic error in SSAs.
AD X X X X X X X X X X X 4 Function parameter invalid.
AG X 4 Partial data return. I/O area too small.
AJ X X X 4 Invalid parameter format in I/O area;
invalid SSA format; invalid command
used to insert a logical child segment.
I/O area length in AIB is invalid.
AL X X X 4 Call using I/O PCB in batch program.
AP X 4 More than 4 user call parameters for a
TP PCB are invalid.
AQ X 4 Invalid subfunction code.
AT X 4 User I/O area too long.
BJ X 6 All of the databases included in the
PSB are unavailable or no database
PCBs are in the PSB.
BK X 6 At least one of the databases included
in the PSB is unavailable or has
limited availability, or at least one PCB
received an NA or NU status code.
FA X X 4 MSDB arithmetic overflow error
occurred.
FD X X 3 Deadlock occurred.
FH X X 3 DEDB inaccessible.
FI X X 4 I/O area not in user’s dependent
region.
FS X X 3 DEDB areas are full.
FV X X 3 MSDB verify condition failed.
GA X 2 Crossing hierarchic boundary.
GE X X X 1 Segment not found.
GL X 4 Invalid user log code.
NA X 6 A database was unavailable.
NL X 4 XEFRDER card not provided. Please
supply one.
NU X 6 A database was unavailable for
update.
QC X 3 No more input messages exist.
QE X X 4 GN request before GU. GCMD request
before CMD.
QF X 4 Segment less than five characters
(segment length is message text
length plus four control characters).

Status Code Tables
Category
SNAP1
PCB
CHKP
ROLB
SYNC
ROLS
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
RA X 4 Token does not match one for a SETS,
or the PCB did not get BA or BB on
last call.
RC X 4 ROLS call issued with unsupported
PCBs in the PSB, or the program is
using an attached subsystem.
SA X 5 Insufficient space.
SB X 4 Would exceed maximum number of
levels allowed.
SC X X 5 A SETS/SETU call was issued with
unsupported PCBs in the PSB, or the
program is using an attached
subsystem.
SY X 5 Internal error during sync-point
processing for an IMS/Java
application.
TA X 5 PSB not in PSB directory
TC X 4 PSB already scheduled
TE X 5 PSB initialization failed
TJ X 5 DL/I not active (command-level only).
TL X 4 Conflict in scheduling intent
TN X X X X X X X 5 Invalid system DIB (command-level
only).
TP X X 4 Invalid number for PCB or invalid
processing option (command-level
only).
TR X X X X 4 CICS XDLIPRE user exit determined
the preceding request should not be
executed.
TY X X 5 Database not open (command-level
only).
TZ X X 5 Length of segment greater than 64 KB.
V2 X 4 Segment length invalid
V7 X 4 Statistics area length invalid
XD X X 1 IMS terminating. Further DL/I calls
must not be issued. No message
returned.
bb3 X X X X X X X X X X X X X 1 Good. No status code returned.
Proceed.
AA • AD
Category
SNAP1
PCB
CHKP
ROLB
SYNC
ROLS
SYNC
ROLL
SETU
XRST
SETS
JAVA
STAT
INQY
LOG
PCB
Status
INIT
Code Description
2
Notes:
1. SNAP is a Product-sensitive programming interface.
Status Code Explanations

This information appears in the three application programming guides. For EXEC
DL/I commands, all status codes, except those identified as being returned to the
application program, cause an abnormal termination of the application program.
All explanations apply to both DL/I call (call-level) programs and EXEC DLI
(command-level) programs except where split. The term “request” means call,
command, or both.
IMS also returns this status code when a STAT 1 call

AA
has an invalid statistics function. After this status code is
Explanation: IMS ignored a CHNG or ISRT call because returned, your position in the database is unchanged.
the alternate response PCB that is referenced in the call
specified a transaction code as a destination. An For command-level programs:
alternate response PCB must have a logical terminal
specified as its destination. An error is in one of the WHERE or SEGMENT options
Programmer Response: Correct the CHNG or ISRT call. on a Get or ISRT command for one of these reasons:
v DL/I could not find a segment in the DB PCB
specified in the segment name given in the
AB SEGMENT option.
Explanation: An I/O area is required as one of the v The segment name is in the DB PCB, but the
parameters on this call, and the call did not specify one. qualification for the command does not specify it in its
After this status code is returned, your position in the correct hierarchic sequence.
database is unchanged. AB only applies to full-function v The command specifies two SEGMENT options for
DEQ calls. the same hierarchic level.
Programmer Response: Correct the call by including Programmer Response: Correct the segment name
the address of an I/O area as one of the call in the SSA or SEGMENT option or in the statistics
parameters. function of the STAT1 call.
AC AD
Explanation: Explanation:
For call-level programs: For call-level programs:
An error is in an SSA for a DLET, Get, ISRT, or REPL call Either the function parameter on the call is invalid or the
for one of these reasons: function is not supported for the type of PCB specified
v DL/I could not find a segment in the DB PCB in the call. Only applies to full-function DEQ calls. Some
specified in the call that has the segment name given possible reasons are:
in the SSA. v The function parameter is invalid.
v The segment name is in the DB PCB, but the SSA v A system service call used a PCB that is not the I/O
specifying that segment name is not in its correct PCB.
hierarchic sequence.
v The call specifies two SSAs for the same hierarchic
level. 1. STAT is a Product-sensitive programming interface.

AF • AI
v A call issued in a DCCTL environment referred to an
AH
unsupported PCB or database.
v A message GU or GN call used an alternate PCB Explanation: You get this status code if you:
instead of the I/O PCB. 1. Specify an options list parameter that was not
v A database call used a PCB that is not a DB PCB. specified in the call list.
v A message GU used the I/O PCB without specifying 2. The program issued an ISRT call that did not include
IN=trancode in the BMP JCL. any SSAs. The ISRT call requires an SSA.
v A SETS or ROLS call included the I/O area but omitted 3. If the program was issuing a GU call to a GSAM
the token. database, the GU did not specify an RSA. RSAs are
required on GU calls to GSAM databases. After this
v A CPI Communications driven program issued the
status code is returned, your position in the
SETO call on the I/O PCB.
database is unchanged.
v A call was issued from an IFP region on an I/O PCB.
Programmer Response: For cause 2, correct the
v Invalid subsystem level for spool API processing.
ISRT call by including a qualification; or for cause 3,
correct the GU call by adding an RSA to the call.
For command-level programs:
A command was issued that is not supported in the AI

environment. An example is a system service command Explanation: A data management open error
in an online program. If the command is correct, some occurred. Some possible reasons are:
other possible causes are:
v An error is in the DD statements.
v Referencing a DB PCB on a system service
command. System service commands must reference v Neither DD statements nor DFSMDA dynamic
the I/O PCB. allocation members were provided for this database.
v Referencing an I/O PCB for a database command, or v The data set OPEN request did not specify load
not defining an I/O PCB before issuing system mode, but the data set was empty. An empty data set
service commands. requires the load option in the PCB.
v A command issued in a DCCTL environment referred v The buffer is too small to hold a record that was read
to an unsupported database or DB PCB. at open time.
v No DD statements or DFSMDA members were
Programmer Response: Be sure that the specified supplied for logically related databases.
function is valid for the PCB specified by the request.
v For an OSAM data set, the DSORG field of the
OSAM DCB, DSCB, or JFCB does not specify PS or
AF DA.
Explanation: GSAM detected a variable-length record v For an old OSAM data set, the BUFL or BLKSIZE
whose length is invalid on a GU, GHU, GN, or GHN call. field in the DSCB is 0.
v The data set is being opened for load, and the
Programmer Response: Correct the program.
processing option for one or more segments is other
than L or LS.
AG v The allocation of the OSAM data set is invalid. The
Explanation: During INQY call processing, the I/O area allocation is probably (1,1), rather than (1,1) and this
was not large enough to contain all the output data. The causes the DSORG to be P0.
I/O area was filled with partial data, as much as would v The processing option is L, the OSAM data set is old,
fit in the area provided. AIBOALEN contains the actual and the DSCB LRECL, BLKSIZE, or both, does not
length of the data returned to the application and match the DBD LRECL, BLKSIZE, or both.
AIBOAUSE contains the output area length that is v Incorrect or missing information prevented IMS from
required for the application program to receive all the determining the block size or the logical record
data. length.
Programmer Response: Correct the application v A catalog was not available for accessing a VSAM
program by using a larger I/O area. The minimum size database that was requested.
of the I/O area is the value contained in the AIBOAUSE v OS could not perform an OPEN, but the I/O request
field. is valid. Either the data definition information is
incorrect, or information is missing.
v RACF was used to protect the OSAM data set, and
the control region has no update authorization.
AJ • AK
If IMS returns message DFS0730I, you can determine number, or you included an invalid character. The
the cause of the OPEN failure from this message in the number following the command code must be
job log. For more information, see the description of this between 1 and 8, inclusive.
message in IMS Version 7 Messages and Codes, v The SSA included more than one R command code.
Volume 2. An SSA can include only one R command code.
Programmer Response: These kinds of problems v The specified size for the SSA is too small. After this
often require the help of a system programmer or status code is returned, your position in the database
system administrator. But before you go to one of these is unchanged.
specialists, some things you can do are: v In response to a SETS or ROLS call, the length of the
v Check the DD statements. Make sure that the I/O area is 0, the LL field is less than 4, or the ZZ
ddname is the same as the name specified on the field is not 0.
DATASET statement of the DBD. The segment name v In response to an INIT call, the format of the I/O area
area in the DB PCB (call level), or in the DIB is incorrect.
(command level) has the ddname of the data set that
v For calls that provide the length of the I/O area in the
could not be opened.
AIB, such as INQY, the I/O area length is invalid.
v Check the PSB and make sure that the appropriate
v For SETO, I/O area length is less than 4096 or less
processing options have been specified for each of
than the minimum.
the DB PCBs that your program uses.
v For the Q command code, the specified lock class is
not a letter (A-J).
AJ
Explanation: For call-level programs: For command-level programs:
For calls that provide parameters in the I/O area, such An ISRT command attempted to insert a logical child
as SETS, ROLS, and INIT, the format of the parameters segment using a path command. ISRT commands for
in the I/O area is invalid. logical child segments cannot be path commands.
For database calls that include SSAs, such as Get, Programmer Response:
DLET, REPL, and ISRT, the format of one of the SSAs is
invalid. The number in the segment level number field of If you receive this status code on a SETS, ROLS, or INIT
the DB PCB is the level number of the SSA that is request, correct the parameters provided in the I/O
invalid. Some possible reasons for the invalid SSA area.
format are:
If you receive this status code on a Get, DLET, REPL, or
v The SSA contains a command code that is invalid for ISRT request, correct the invalid portion of the SSA. If
that call. you receive this status code on a GSAM call, correct
v The relational operator in the qualification statement the RSA.
is invalid.
v A qualification statement is missing a right AK
parenthesis or a Boolean connector.
Explanation: For call-level programs:
v A DLET call has multiple or qualified SSAs.
v A REPL call has qualified SSAs. An SSA contains an invalid field name, or the field
name is not defined in the DBD. The number in the
v An ISRT call has the last qualified SSA.
segment level number field of the DB PCB is the level
v An ISRT call that inserts a logical child segment into number of the SSA that contains the invalid name.
an existing database includes the D command code.
ISRT calls for logical child segments cannot be path You can also receive this status code if the program is
calls. accessing a logical child through the logical parent. DL/I
returns AK if the field specified in the qualification has
v The RSA parameter on a GSAM call is invalid.
been defined for the logical child segment, and it
v The SSA used an R, S, Z, W, or M command code includes (at least partially) the portion of the logical child
for a segment for which no subset pointers are that contains the concatenated key of the logical parent.
defined in the DBD.
When you are using field-level sensitivity, a field you
v The subset command codes included in the SSA are
specified in the SSA has not been defined in the PSB.
in conflict; for example, if one SSA contained an S
After this status code is returned, your position in the
status code and a Z status code, Fast Path would
database is unchanged.
return an AJ status code. S means to set the pointer
to current position; Z means to set the pointer to 0. For command-level programs:
You could not use these status codes in one SSA.
A WHERE option contains an invalid field name. (The
v The pointer number following a subset pointer field name is not defined in the DBD.) The number in
command code is invalid. Either you did not include a the DIBSEGLV field of the DIB is the level number of

AL • AM
the WHERE option that contains the invalid name. v If a DLET, REPL, or ISRT call that references a DB
PCB does not have the necessary processing option
Programmer Response: Correct the SSA or WHERE
for that call. The minimum processing options for
option.
these calls are D for DLET, R for REPL, and I for ISRT.
v If you issue a DLET, REPL, or ISRT call for a segment
AL to which the program is not sensitive.
Explanation: You get this status code if you: v If you issue a CHKP call on a GSAM or VSAM data set
1. Issue a message call in a batch program. opened for output. This code is returned in the GSAM
PCB.
2. Issue a ROLB, ROLS, or SETS call from a batch
program under one of the following conditions: v If you issue a GSAM call with an invalid call function
code.
v The system log is not on DASD.
v If you issue an ISRT or DLET call for the index target
v The system log is on DASD, but dynamic backout segment or a segment on which the index target is
has not been specified using the BKO execution dependent in the physical database while using an
parameter. alternate processing sequence.
Programmer Response: For cause 1, correct the v If you issue a path replace where the program does
program so that message calls in a batch program are not have replace sensitivity, command code N is not
not issued. For cause 2, either change the program or specified, and the data for the segment is changed in
put the log on DASD with BKO specified on the the I/O area.
execution parameter. v If GSAM could not obtain buffer space because the
region size is too small. This is shown by the value
AM X'1C' in the field GBCRTNCD.
v If you issue a DLET, ISRT, or REPL call from a
Explanation: For call-level programs:
program where the TRANSACT macro that was used
The call function is not compatible with the processing at IMS system definition specified INQUIRY=YES for
option in the PCB, the segment sensitivity, the the input message.
transaction-code definition, or the program type. The v If you issue a call from an ETO terminal to a
level number in the PCB is the level number of the SSA terminal-related MSDB or a non-terminal-related
that is invalid. Some of the reasons you might get this MSDB with terminal-related keys. See IMS Version 7
status code are: Administration Guide: Transaction Manager for more
v If you issue a retrieval call with the D command code information on ETO.
in a program that does not have the P processing v If you issue any type of call with update intent to a
option specified in the DB PCB that was used for the MSDB from a dynamically defined device such as a
call. LU 6.2, ETO, or OTMA device.
v If you issue a DLET or ISRT call to a terminal-related
dynamic MSDB from a program with no input LTERM After this status code is returned, your position in the
present. An example is a batch-oriented BMP. database is unchanged.
v If the subset pointer referenced in the SSA was not
defined in the program’s PSB. For example, if your For command-level programs:
program’s PSB specifies that your program can use
subset pointers 1 and 4, and your SSA references The command is not compatible with the processing
subset pointer 5, Fast Path returns an AM status option in the PCB or segment sensitivity. The level
code to your program. number in the DIB is the level number of the
v If your program tried to use an S, Z, W, or M qualification that is invalid. Some of the reasons you
command code for a subset pointer to which it was might get this status code are:
not pointer update-sensitive, as defined in the v If you issue a path retrieval command in a program
program’s PSB. that does not have the P processing option specified
v If a BMP, a CICS online program, or an MPP issues in the DB PCB that was used for the call.
an ISRT call with the D command code when the v If the processing option is L and the program issued
program does not have the P processing option a command other than a LOAD command. Load
specified in the DB PCB that was referenced in the programs can issue only LOAD commands.
call. Batch programs do not need the P processing v If you issue a DLET, REPL, or ISRT command that
option to issue an ISRT call with the D command references a DB PCB that does not have the
code, unless the program uses field-level sensitivity. necessary processing option for that command. The
v If the processing option is L and the program issued minimum processing options for these calls are D for
a call other than an ISRT call. Load programs can DLET, R for REPL, and I for ISRT.
issue only ISRT calls.
AO • AX
v If you issue a DLET, REPL, or ISRT command for a
AQ
segment to which the program is not sensitive.
v If you issue a CHKP command if a GSAM or VSAM Explanation: The AIB contains an invalid subfunction,
data set is open for output. or the INQY call specifies an invalid function.
v If you issue a GSAM call with an invalid call function Programmer Response: Specify a valid subfunction.
code. Valid INQY call subfunctions are null, DBQUERY,
v If you issue an ISRT or DLET command for the index ENVIRON, FIND, or PROGRAM.
target segment, or a segment in the physical
database on which the index target is dependent, AR
while using an alternate processing sequence.
Explanation: The options list contains an error that is
v If you issue a path replace where the program does
related to a keyword. The feedback area, if one is
not have replace sensitivity, command code N is not
provided, will contain additional error information.
specified, and the data for the segment is changed in
the I/O area. Programmer Response: Correct the request.
v If you issue a call to a GSAM dummy data set. Any
call to a GSAM dummy data set is invalid. AS
Programmer Response: Correct the request, or make Explanation: An IAFP specific processing error has
the necessary changes in the PCB. occurred. The PRTO= option contained invalid data set
processing options. The feedback area, if provided, will
AO contain additional error information.
Explanation: A BSAM, GSAM, VSAM, or OSAM Programmer Response: Correct the request.
physical I/O error occurred. When issued from GSAM,
this status code means that the error occurred when: AT
v A data set was accessed.
Explanation: The length of the data in the program’s
v The CLOSE SYNAD routine was entered. The error I/O area is greater than the area reserved for it in the
occurred when the last block of records was written control region. The length of the area reserved is
prior to the closing of the data set. defined by the ACB utility program, DFSUACB0, and is
printed as part of its output.
IMS does not return an AO status code for write errors
with BSAM, VSAM, and OSAM. Programmer Response: If the program is in error,
correct the program. If the program is correct, reserve a
If your program receives this status code after issuing a larger control region by specifying parameters on the
call, this call does not cause the database to be PSBGEN statement of PSBGEN.
stopped.
Programmer Response: Determine whether the error AU
occurred during input or output, and correct the Explanation: The total length of the SSAs in the
problem. These problems usually require the help of a database call is greater than the area reserved for them
system programmer or system administrator. in the control region. The length of the area reserved is
defined by the ACB utility program, DFSUACB0, and
AP printed as part of its output. After this status code is
returned, your position in the database is unchanged.
Explanation: A message or CHKP call is invalid
because more than four parameters (or five if a Programmer Response: If the program is in error,
parameter count is specified) are in a message call or a correct the program. If the program is correct, increase
CHKP call issued in a transaction-oriented BMP. The the PSB SSA space defined in the PSBGEN.
following exceptions apply:
v A batch-oriented BMP can issue a CHKP call with AX
more than 4 (or 5) parameters.
Explanation: A failure to get CSA storage, a failure of
v One parameter after the I/O area parameter is the DFSLUMIF call, or a processing error with the IAFP
allowed in order for the application program to specify Spool API occurred. When this code is returned,
a MOD name in an ISRT call. It is counted towards diagnostic information is written to the log in a '67D0'
the maximum of four (or five) parameters. log record. Spool API processing errors return a
Programmer Response: Correct the call. DFS0013E message.
A RACROUTE REQUEST=VERIFY,EVIRON=CREATE

AY • A2
(RACF RACINIT) made during an AUTH call for LU 6.2 the originating system has not been determined
was unsuccessful. because the application program has not issued a
GU.
An OTMA user exit returned invalid routing information.
See OTMA return codes in the IMS Version 7 Open – The SYSID returned in R0 by the exit routine is
Transaction Manager Access Guide. not a valid remote SYSID.
– The MSNAME pointed to by the address in R1,
Programmer Response: These problems usually
set by the exit routine, is not a valid remote
require the help of a system programmer or system
MSNAME.
administrator.
v The MSC program routing routine exit (DFSMSCE0)
was called while processing an ISRT or CHNG call
AY and one of the following occurred:
Explanation: IMS ignored a message ISRT call – The exit routine rejected the call by setting
because the logical terminal referenced by the alternate MSPRFL3=MSPR3REJ in the DFSMSCEP user
response PCB currently has more than one physical parameter list that is passed to the exit.
terminal assigned to it for input purposes. – IMS detected an error while processing the
Programmer Response: Ask the master terminal reroute request from the exit. It issued a message
operator to determine (using /DISPLAY ASSIGNMENT ″DFS070 Unable to route message RSN=xxyy″
LTERM x) which physical terminals (two or more) refer and wrote a 6701-MSCE log record to the IMS
to this logical terminal. Use the /ASSIGN command to log. For more information about this error, see the
correct the problem. section on diagnosing message routing problems
in IMS Version 7 Diagnosis Guide and Reference.
v The destination name supplied in the I/O area of a
AZ CHNG call is invalid.
Explanation: IMS ignored a PURG or ISRT call in a v The destination name supplied in the I/O area of a
conversational program. Some possible reasons are: CHNG call is valid (the destination is a program and
v Issuing a PURG call referencing the I/O PCB or an the PCB is not an alternate response PCB), but the
alternate response PCB. Conversational programs transaction is Fast Path exclusive.
can issue PURG calls only when the PURG call v AUTH call parameter list contained an invalid generic
references an alternate PCB that is not an alternate CLASS name. No access checking was done.
response PCB. v The routing exit routine (DFSCMPR0 or DFSMSCE0)
v Issuing a PURG call to send the SPA. attempted an invalid request to override a direct
v Issuing an ISRT or a PURG call referencing an routing request.
alternate PCB that is set for an invalid destination or 2 v The OTMA Prerouting Exit routine (DFSYPRX0)
for a destination that IMS cannot determine. 2 might have specified an incorrect 16-byte OTMA
v Issuing an ISRT call referencing an alternate PCB 2 client override name. The client name can not contain
whose destination is a conversational transaction 2 all blanks. If the client name is shorter than 16 bytes,
code when the first segment inserted is not the SPA; 2 it must be padded with blanks.
or when IMS cannot determine whether or not the Programmer Response: Correct the CHNG or AUTH
SPA was the first segment inserted. call, MSC program routing exit (DFSCMPR0 or
Programmer Response: Correct the PURG or ISRT call. DFSMSCE0), or ensure that the specified destination is
valid.
A1
A2
Explanation: IMS returns the A1 status code for one
of the following reasons: Explanation: The program issued a CHNG call
against an invalid PCB. The PCB was invalid for one of
v AUTH call for LU 6.2 input did not find a PST LU 6.2
these reasons:
extension block or did not find a UTOKEN.
v It was not an alternate PCB.
v CHNG call against alternate response PCB when the
application program has not yet issued a GU. v It was an alternate PCB, but it was not modifiable.
v The MSC program routing exit routine (DFSCMPR0) v It was being used to process a message and had not
was called while processing a CHNG call and one of completed processing it.
the following occurred: Programmer Response: Check the PCB that was
– The exit routine rejected the call by returning with used by the CHNG call and determine which PCB should
return code 8 (A1 status code). have been used for the call.
– The exit routine returned with a RC=4 to route the
message back to the originating system; however,
A3 • A9
A3 A7
Explanation: The program issued an ISRT or PURG call Explanation: IMS ignored a message ISRT call for one
that referenced a modifiable alternate PCB that did not of the following reasons:
have its destination set. IMS returns this status code to v The number of message segments inserted exceeds
PURG calls only when the PURG call specified an I/O area the number specified in the SEGNO keyword of the
as one of the parameters. TRANSACT macro.
Programmer Response: Issue a CHNG call to set the 1 v The IMS queue manager or user Queue Manager
destination of the modifiable alternate PCB, and then 1 Space Notification exit routine (DFSQSPC0)
reissue the ISRT or PURG call. 1 prohibited the insert to prevent the message queue
1 data sets from overflowing. However, the ISRT is not
1 ignored for the message in progress when the
A4
1 DFSQSPC0 threshold is exceeded. The in-progress
Explanation: A security violation was detected during 1 message will be processed. Any subsequent ISRTs
processing of an AUTH, CHNG, or ISRT call of a SPA on a 1 are ignored.
conversational response. Some of the reasons for this v The IMS queue manager or user Queue Manager
status code are: Space Notification exit routine (DFSQSPC0)
v Transaction authorization is active and either RACF prohibited the insert because the destination
or a transaction authorization exit routine returned a TRANSACTION or LTERM was stopped.
nonzero return code.
Programmer Response: Check the output messages
v The user is not authorized for access to the and correct them. Use ROLB or another method to free
RESOURCE name in the class requested in the buffer space.
AUTH call. No installation data is returned.
v No source CNT is available, which might be caused
A8
by the application program not having issued a GU.
v A program-to-program message switch is being done. Explanation: IMS ignored an ISRT call because:
In this case, the applicable authorization LTERM is v An ISRT call to an alternate response PCB must not
based on the original message, and this authorization follow an ISRT call to the I/O PCB.
does not allow this function to be performed. v An ISRT call to the I/O PCB must not follow an ISRT
Programmer Response: Check the transaction code call to an alternate response PCB.
to make sure it was entered correctly. If it was, check Programmer Response: Correct the ISRT call.
with the person who handles security at your
installation.
A9
A5 Explanation: IMS ignored the ISRT call because:

v The ISRT call referenced an alternate response PCB
Explanation: An ISRT or PURG call supplied an invalid
defined as SAMETRM=YES, but the PCB
parameter list. The call supplied the fourth parameter
represented a logical terminal that is not part of the
(the MOD name), but the ISRT or PURG being issued was
originating physical terminal. An alternate response
not for the first segment of an output message.
PCB defined as SAMETRM=YES must represent the
Programmer Response: Correct the ISRT or PURG call. same physical terminal as the physical terminal
associated with the originating logical terminal.
A6 v The originating terminal is in response mode, and the
alternate response PCB is not associated with that
Explanation: For a message processing program logical terminal.
(MPP or BMP), IMS ignored a message ISRT call
because the length of the message segment being IMS does not return this status code if the program
inserted exceeds the size specified in the SEGSIZE makes either of these errors while communicating with a
keyword of the TRANSACT macro. For a Fast Path terminal in a remote IMS system through MSC.
program (IFP), the length of the output message to a
Fast Path terminal exceeds the size specified in the Programmer Response: Determine whether the
FPBUF parm of the TERMINAL macro. application program is in error, the output logical
terminal has been incorrectly reassigned (using the
Programmer Response: Correct the output message /ASSIGN command), or if SAMETRM=YES should not
segment. have been specified for the alternate response PCB.

BA • CD
All database resources that were allotted up to the last
BA
commit point are backed out, with the exception of
Explanation: The request was not completed because GSAM and DB2. All output messages are backed out to
it required access to unavailable data. the last commit point. Input messages are requeued.
A status of BA is returned on a DL/I call that attempts to Programmer Response: This is an information-only
access an unavailable partition. If the very next DL/I call status code.
is a GN that is either completely unqualified or qualified
only by root name, then the next partition is selected.
BJ
The next-partition selection continues until either an
available partition is found or there are no more Explanation: All of the databases in the PSB are
partitions in the database. If an available partition is unavailable, or there are no database PCBs in the PSB.
returned, the call returns the first root in that partition. A
GN call that is qualified only on a dependent segment Each PCB (excluding GSAM) received an NA status
name results in a BA status if the prior call had a BA code as the result of the INQY DBQUERY call.
status returned for the root level. Programmer Response: This is an information-only
Only the updates done for the current request, prior to status code.
the time it encountered the unavailable data, are
backed out. The state of the database is as it was BK
before the failing request was issued. If the request was
REPL or DLET, the PCB position was unchanged. If the Explanation: At least one of the databases included in
request was a Get or ISRT request, the PCB position is the PSB is unavailable or has limited availability.
unpredictable. At least one PCB received an NA or NU status code as
For a DEDB, this status code might be returned if no the result of processing the INQY DBQUERY call.
updates have been made by the current call. If updates Programmer Response: This is an information-only
have been made by the current call since the last status code.
commit point, a BB status code is returned instead. If
changes have been made by a previous call, the
application program must decide whether to commit CA
these changes. Explanation: The program issued a CMD call with an
Rather than having an abnormal termination occur, this invalid command verb, or the command verb does not
status code is returned to the application program that apply to the IMS system that the program is running in.
issued the EXEC DLI command. IMS does not return any command responses.
Programmer Response: This is an information-only Programmer Response: Correct the command in the
status code. CMD call.
BB CB
Explanation: The BB status code is the same as BA Explanation: The command entered in the CMD call is
except that all database updates that the program made not allowed from an AOI program. IMS does not return
since the last commit point are backed out, and all any command responses.
nonexpress messages sent since the last commit point Programmer Response: Correct the command. For a
are canceled. The PCB position for all PCBs is at the list of the commands that an AOI program can issue,
start of the database. see IMS Version 7 Customization Guide.
For a DEDB, this status code might be returned if
updates have been made by the current call. CC
Rather than having an abnormal termination occur, this Explanation: IMS has executed the command and
status code is returned to the application program that returned one or more command responses.
issued the EXEC DLI command.
Programmer Response: Your program should issue
Programmer Response: This is an information-only GCMD calls as necessary to retrieve the responses.
status code.
CD
BC
Explanation: The command that was entered on the
Explanation: The response from an INIT STATUS CMD call violates security, or the application program is
GROUPB call was not completed because it required not authorized to issue CMD calls. IMS does not execute
access to unavailable data. the command or return any command responses.
CE • CR
Programmer Response: Correct the command. If Programmer Response: This is an information-only
necessary, check with the person in charge of security status code.
at your installation to find out why your program is
restricted from using that command.
CK
Explanation: CK is a combination of CF and CG. The
CE
message retrieved with this GU originated from an AOI
Explanation: IMS rescheduled the message that this user exit. The message was scheduled for transmission
GU call retrieved since the last CMD call. The program before IMS was last started.
had not reached a commit point when the message was
Programmer Response: This is an information-only
rescheduled.
status code.
status code.
CL
Explanation: CL is a combination of CE, CF, and CG.
CF
Please see the explanations of those codes.
Explanation: The message being returned on the GU
call was received by IMS before the start of this IMS
status code.
execution. CF can be received on a CHKP call when an
I/O area is specified for an MPP or message-oriented
BMP. This occurs when a CHKP call issues an internal GU CM
call.
Explanation: The command that was entered on the
Programmer Response: This is an information-only CMD call has been executed and completed, but it
status code. resulted in an exception response that could not be built
because of an insufficient amount of general work area
(WKAP).
CG
Programmer Response: Increase WKAP if you want
Explanation: The message retrieved by this GU
retrieval of the response.
originated from an AOI exit routine.
CN
status code.
Explanation: The IOASIZE= parameter that was
specified on the PSBGEN macro is defined for less than
CH
the required minimum for CMD calls (132 bytes).
Explanation: IMS ignored the CMD call just issued
Programmer Response: Redefine IOASIZE=
because the AOI command interface detected a system
parameter on the PSBGEN for a minimum of 132 bytes.
error and was unable to process the command. IMS
processing continues.
DA
Programmer Response: Reissue the command.
Explanation: The program issued a DLET or REPL that
tried to modify the key field in the segment or, when
CI
using field-level sensitivity, a REPL call tried to modify a
Explanation: CI is a combination of CE and CF. The field that had REPL=NO specified on the SENFLD
message retrieved by this GU was scheduled for STMT in the PSB. You cannot change a segment’s key
transmission before IMS was last started. The message field.
was rescheduled, but the program had not reached a
Programmer Response: Correct the request.
commit point.
CR
status code.
Explanation: The IMS Java application attempted to
issue a Java GU message call before issuing a Java
CJ
commit.
Explanation: CJ is a combination of CE and CG. The
Programmer Response: You must issue a Java
message retrieved by this GU was scheduled for
commit from your application prior to issuing another
transmission before IMS was last started. The message
Java GU message call.
originated from an AOI exit routine.

DJ • FD
DJ E2
Explanation: The program issued a DLET or REPL call Explanation: The DFSMSCE0 user routing exit
that was rejected because the segment was not rejected the ISRT or CHNG call by setting
currently in hold status. Some possible reasons for this MSPRFL3=MSPR3REJ and MSPRSTAT=E2 in the
status code are: DFSMSCEP user parameter list that is passed to the
v The segment had not been previously retrieved with exit.
a Get Hold call. Programmer Response: Refer to the user installation
v The segment was already deleted using this PCB. copy of the DFSMSCE0 exit for information on the
After one Get Hold call, multiple REPL calls or a DLET MSPR3REJ and MSPRSTAT settings. Contact your
call following a REPL call are valid, but multiple DLET system programmer.
calls are not.
v The segment was obtained using a secondary index E3
as the processing sequence. A subsequent DLET or
REPL call using either this PCB or another PCB within Explanation: The DFSMSCE0 user routing exit
the PSB caused the current secondary index entry for rejected the ISRT or CHNG call by setting
this PCB to be deleted. MSPRFL3=MSPR3REJ and MSPRSTAT=E3 in the
DFSMSCEP user parameter list that is passed to the
v A checkpoint call was issued following the Get Hold
exit.
call and preceding the REPL or DLET call.
v A rollback call was issued following the get hold call Programmer Response: Refer to the user installation
and preceding the REPL or DLET call. copy of the DFSMSCE0 exit for information on the
MSPR3REJ and MSPRSTAT settings. Contact your
Programmer Response: Correct the program so that system programmer.
the segment is in hold status when a DLET or REPL is
issued.
FA
DX Explanation: IMS returns this status code when the

program reaches a commit point and an arithmetic
Explanation: The program issued a DLET that violates overflow occurs in an MSDB, DEDB, or VSO DEDB
the delete rule for that segment. during that commit interval since the last commit point
Programmer Response: Check the program to see (or, if the program had not reached a commit point,
whether or not the program should delete that segment; since the program began processing). You can receive
if it should, check with your DBA (or the equivalent this status code on a SYNC call, a CHKP call, or a GU call
specialist at your installation) to find out what delete rule to the message queue, depending on your program.
has been specified for that segment. The overflow occurred after the program issued a
FLD/CHANGE call, or a REPL call for the MSDB, DEDB, or
VSO DEDB. When this happens, IMS issues an internal
EM ROLB call to eliminate the changes that the program has
Explanation: The EM status (empty area) indicates made since the last commit point. All database
that there are no valid sequential dependent segments positioning is lost.
in the area. Programmer Response: Reprocess the transaction.
Programmer Response: Check to see that the correct
area is being processed by the utility and that FC
sequential dependent segments have been inserted.
Explanation: The program issued a request that is not
valid for the segment type.
E1
Programmer Response: Correct the request.
Explanation: The DFSMSCE0 user routing exit
rejected the ISRT or CHNG call by setting
MSPRFL3=MSPR3REJ and MSPRSTAT=E1 in the FD
DFSMSCEP user parameter list that is passed to the Explanation: A nonmessage driven BMP reached a
exit. deadlock when IMS tried to get DEDB or MSDB
Programmer Response: Refer to the user installation resources (either DEDB UOWs or overflow latches) for
copy of the DFSMSCE0 exit for information on the the program. Or, a mixed-mode BMP reached a
MSPR3REJ and MSPRSTAT settings. Contact your deadlock on any resource, either Fast Path or full
system programmer. function. IMS eliminates all database updates that the
program has made since the last SYNC call, CHKP
request, or SYMCHKP command (or since the program
started processing, if the program has not issued a SYNC
FE • FI
call or CHKP request). All database positioning is lost, If IMS returns this status code on a call that caused a
unless you specified the P processing option in the commit point to occur (a SYNC call, a message GU, a
PCB. Messages to a non-express alternate TP PCB are CHKP request, or a SYMCHKP command), IMS issues
discarded. an internal ROLB call to eliminate the program’s database
updates and message output created since the last
Rather than having an abnormal termination occur, this
commit point.
status code is returned to the application program that
issued the EXEC DLI command. If your program is accessing a DEDB in a data-sharing
environment, and if the authorization fails when your
Programmer Response: Start processing from the
program issues its first DL/I call to the DEDB, Fast Path
last commit point. If you reach a deadlock again,
returned this status code. Fast Path also notified the
terminate the program.
master terminal operator of the authorization failure.
Your position in the database is before the first root in
FE the next area. A GN will get the next available record
(unless that one is also inaccessible).
Explanation: IMS returns this status code any time a
program issues a FLD call that receives a nonblank If a program has access to an area through a PCB with
status code in the FSA. PROCOPT=H and another PCB without PROCOPT=H,
it is possible that only calls to the PCB with
Programmer Response: See “Fast Path Databases” PROCOPT=H will receive the FH status code. This is
in IMS Version 7 Application Programming: Database because the area is accessible to IMS, but the required
Manager for an explanation of FSA status codes and HSSP (high-speed sequential processing) setup could
correct the FLD call. not be established. Message DFS0533A explains the
reason for this occurrence and is sent to the job log.
FF This status code is also returned if the PROCOPT for
one PCB is more restrictive than the PROCOPT of a
Explanation: A program issued an ISRT call against different PCB in the same PSB. Position is set to the
an MSDB that has no free space. If IMS determines that beginning of the next accessible area.
there is no free space when the program issues the
ISRT call, the program receives the FF status code for Rather than having an abnormal termination occur, this
that call. IMS might not determine this until the program status code is returned to the application program that
reaches the next commit point. In this case, IMS returns issued the EXEC DLI command.
FF when the program issues a GU call to the message Programmer Response: If the data in the area is
queue, a SYNC call, or a CHKP call, depending on which important, contact the DBA. If the data in the area is
call caused the commit point. unimportant, the program should roll back the changes.
Programmer Response: To avoid this situation, Your program can continue processing with the next
specify more space for the MSDB at the next system available area.
start (cold start or normal restart). If the status code is related to an HSSP setup problem,
fix the error as described in the message DFS0533A in
FG the job log.
Explanation: FG is a combination of FE and FW. A

batch-oriented BMP issued a FLD call that received a FI
nonblank status code in the FSA, and the program has 2 Explanation: The program’s I/O area is not at a
depleted its normal buffer allocation. 2 storage address that the program can access. IMS
Programmer Response: Check the FSA status code 2 determined that the storage address of the start of the
and correct the FLD call, and then issue SYNC or CHKP 2 I/O area supplied by the program could not be
calls in the program more frequently. One way to handle 2 referenced, or that the storage address computed as
this status code is to branch to an error routine that 2 the start of the I/O area plus the length of the segments
causes the program to issue SYNC or CHKP calls more 2 being returned could not be referenced. IMS sets this
frequently when it receives this status code. 2 status code only to avoid a potential program check
2 abend during data movement. The absence of an FI
2 status code does not imply that the supplied I/O area
FH 2 address is logically correct or that the area is large
Explanation: A DEDB area was inaccessible to the 2 enough.
requested service when the program issued a database 2 NOTE: If AIB interface is used, the supplied lengths in
request or when the program reached a commit point. 2 the AIB are first validated against returned segment
The AREA was stopped or the DEDB randomizing 2 lengths and the appropriate AIB return and reason
routine was not loaded into storage. A /START 2 codes are set if validation fails. If validation succeeds,
DATABASE dedbname command will cause the DEDB 2 IMS still checks the actual storage addresses involved
randomizing routine to be reloaded. 2 in the move, and an FI status code might still be

FM • FS
2 returned. If AIB interface is not used, only the storage referring to a DEDB with PROCOPT=P or H active are
2 address validation is performed. lost. If the PCB referred to a DEDB with PROCOPT=P
or H active, the position is set to the valid position after
the last commit process, or the start of the valid range if
there was no commit process.
FM
Explanation: The application program issued a
request for which the randomizing routine returned a
return code of 4.
Programmer Response: Either terminate the program
1 The key supplied on a DL/I call to a HALDB was greater
and restart it with a larger buffer allocation, or provide a
1 than the high key value for the last partition. Or the
routine that causes frequent commit points. If
1 user’s partition selection exit returned with RC=04 after
PROCOPT=H is used, make sure that a commit point is
1 having been passed a key value with which to select a
requested after a GC code has been returned.
1 partition.
FS
issued the EXEC DLI command. Explanation: For a root segment or direct dependent
segment, this status code is returned only to BMPs. For
Programmer Response: The database position has
a sequential dependent segment, this status code can
not changed. The application program must determine
be returned to either a BMP or a message-driven
subsequent processing.
program:
v A BMP issued an ISRT request for a root segment, a
FN direct dependent segment, or a sequential dependent
Explanation: The program issued a FLD call that segment, but IMS could not get enough space in
contains a field name in the FSA that is not defined in either the root-addressable or sequential dependent
the DBD. IMS does not continue processing the FLD call part of the DEDB area to insert the new segment:
or any of the FSAs in the FLD call. IMS returns an FN – If IMS returns this status code on an ISRT request
status code in this situation even if an earlier FSA in the for a root segment, a direct dependent segment,
same FLD call received an FE status code. or a sequential dependent segment, the problem
is with the root-addressable portion of the area,
Programmer Response: Issue a ROLB call to remove the independent overflow area, or the sequential
the effects of the incorrect FLD call and then correct the dependent area.
FLD call.
– If IMS returns this status code when the program
issues a SYNC call, CHKP request, or SYMCHKP
FP command, the problem is with the sequential
dependent part of the area.
Explanation: The I/O area referenced by a REPL,
ISRT, or FLD/CHANGE call to an MSDB contains an In either case, IMS eliminates all of the database
invalid packed-decimal or hexadecimal field. changes the program has made since the last commit
point (or since the program started processing, if the
Programmer Response: Correct the data in the I/O
program has not reached a commit point).
area.
v A message-driven program issued an ISRT request
for a sequential dependent segment, and the
FR sequential dependent part is full.
Explanation: One of the following situations exists: 2 Related Reading: For more information about
v A batch-oriented BMP issued a database request that 2 sequential dependent space management, see the
forced the system to go beyond the buffer limit 2 IMS Version 7 Administration Guide: Database
specified for the region. 2 Manager.
v A batch-oriented BMP received a GC status code in a
PCB with PROCOPT=H. Another commit process
was required before using the PCB again.
IMS eliminates all database changes made by the Programmer Response: Continue with other
program since the last SYNC call, CHKP request, or processing, and report the problem to the system
SYMCHKP command the program issued (or since the programmer.
program started processing if the program has not
issued any SYNC calls, CHKP requests, or SYMCHKP
commands). All database positions for PCBs not
FT • GB
FT GA
Explanation: The Fast Path program issued a call to a Explanation: In trying to satisfy an unqualified GN or
Fast Path database that included too many SSAs. A call GNP call, IMS crossed a hierarchic boundary into a
to a DEDB can include up to 15 SSAs. A call to an higher level.
MSDB can include only one SSA.
If IMS returns GA after a STAT2 request, it means that
Programmer Response: Correct the call. the request that was just issued retrieved the total
statistics for all the VSAM buffer subpools.
FV Rather than having an abnormal termination occur, this
Explanation: At least one of the verify operations in a
issued the EXEC DLI command. This call results in a
FLD call issued in a batch-oriented BMP failed when the
return code of 0.
program reached a commit point. IMS eliminates the
database updates the program has made since it issued Programmer Response: This status code is an
the last SYNC or CHKP call (or if the program has not information-only status code.
issued a SYNC or CHKP call, since the program started
processing). All database positioning is lost.
GB
Programmer Response: Reprocess the transaction or
Explanation: In trying to satisfy a GN call, DL/I reached
terminate the program.
the end of the database or, if you used a SETR
statement, the end of the current range. In this situation,
FW the SSA for the call or qualification for the command
specified data beyond the last occurrence, and the
Explanation: A BMP has used all buffers that are
search was not limited to the presence of a known or
allocated for normal use, or all buffers have been
expected segment occurrence.
modified. IMS returns this status code to warn you that
you might be running out of buffer space. An FR status For example, a GN call was specified for a key greater
code might be imminent. than a particular value, rather than a GU call specifying a
key value beyond the highest value.
If you have been processing a DEDB, you get FW for
requests that change data. A GB status code can be returned for:
If you have been processing an MSDB, you get FW for v An unqualified GN call
all calls that change data and for GH calls. v A qualified GN call without a maximum key (if no data
is returned to the I/O area)
With a DEQ call, you receive this code if no buffers can
be released.
In contrast, a GE status code, instead of a GB status
Rather than having an abnormal termination occur, this code, can be returned for:
status code is returned to the application program that v A GU call
v A qualified GN call without a maximum key (if data is
Programmer Response: You can supply an returned to the I/O area)
error-handling routine, triggered by the FW status code, v A qualified GN call with a maximum key
that will cause your program to issue SYNC calls, CHKP
requests, or SYMCHKP commands as soon as an FW IMS also returns this status code when it has closed a
status code is returned to your program. This reduces GSAM data set. The assumed position for a subsequent
the total buffer requirement. To avoid receiving the FW request for a GSAM or full-function database is the
status code, issue SYNC or CHKP calls more frequently. beginning of the database, or if a SETR statement was
used for a DEDB database, the beginning of the current
FY range.
Explanation: PROCOPT=H PCBs process segments Rather than having an abnormal termination occur, this
sequentially in the forward direction. Position is status code is returned to the application program that
established on a UOW and is moved forward only. issued the EXEC DLI command.
Attempts to retrieve segments prior to the current UOW
position are not allowed for HSSP application programs Programmer Response: User determined.
and will not be processed; they receive this status code.
Programmer Response: Change the application
program to retrieve segments in a forward direction
only; use a PCB with a PROCOPT value other than H
to access the segments in the backward direction.

GC • GG
v The program issued a STAT3 call for VSAM buffer
GC
subpool statistics, but the subpools do not exist.
Explanation: An attempt was made to cross a v A nonmessage driven BMP issued a FLD call to an
unit-of-work (UOW) boundary, or an area boundary in MSDB segment. After the FLD call but before a
the case of PROCOPT=H. For a batch-oriented BMP commit point, the MSDB segment was deleted. GE
PCB with PROCOPT=H or PROCOPT=P, at least one can be returned for this reason after either a SYNC or
call on the referenced PCB changed position in the a CHKP call.
database since the last commit process or after the
program began executing. IMS did not retrieve or insert For command-level programs:
a segment. Position is before the first segment of the
following UOW. v DL/I is unable to find a segment that satisfies the
segment described in a Get command.
Rather than having an abnormal termination occur, this v For an ISRT command, DL/I cannot find one of the
status code is returned to the application program that parents of the segment you’re inserting.
v The program issued a STAT3 command for ISAM or
Programmer Response: User determined. However, if OSAM buffer pool statistics, but the buffer pool does
the GC status code results from a call that referred to a not exist.
PCB with PROCOPT=H, the program must cause a v The program issued a STAT call for 3 VSAM buffer
commit process before any other call can be issued for subpool statistics, but the subpools do not exist.
that PCB. Failure to do so results in an FR status code.
GD status code is returned to the application program that
Explanation: The program issued an ISRT call that
was not qualified for all levels above the level of the Programmer Response: The action you take
segment being inserted. For at least one of the levels depends on your program.
for which no qualification was specified, a prior request
using this PCB established valid position on a segment. Note: When a GNP call for a DEDB sequential
That position is no longer valid for one of these dependent segment results in a GE status code,
reasons: the I/O area contains a length indication of 10
v The segment has been deleted by a DLET call using a bytes and the original position of the deleted
different DB PCB. portion of the sequential dependent part. Position
is at the end of the sequential dependent chain.
v The segment was retrieved using an alternate
processing sequence, and a REPL or DLET call for this
DB PCB caused the index for the existing position to GG
be deleted.
Explanation: DL/I returns this status code if the
segment being retrieved contains an invalid pointer and
the application program has a processing option of GOT
or GON. (Processing options are explained under
PROCOPT in the discussion of program specification
Programmer Response: User determined. block generation in IMS Version 7 Utilities Reference:
System.) This can occur when update activity in the
database is going on concurrently with your program’s
GE processing.
Explanation: For call-level programs: For call-level programs:
IMS returns this status code when: The PCB key feedback length and area will be based
v DL/I is unable to find a segment that satisfies the on the last segment that satisfied the call. Your position
segment search argument described in a Get call. is at the beginning of the database.
v For an ISRT call, DL/I cannot find one of the parents For command-level programs:
of the segment being inserted.
If your request specified KEYFEEDBACK, the DIBKFBL
v For an ISRT call, DL/I was requested to insert a root will contain the length of the key of the last segment
segment outside of the accessible range determined that satisfied the command. Your position is at the
by a SETR statement. beginning of the database.
v The program issued a STAT3 call for OSAM buffer
pool statistics, but the buffer pool does not exist.
3. STAT is a Product-sensitive programming interface. Programmer Response: Continue processing with
GK • IX
another segment or terminate the program. The request
HT
that resulted in the GG status code might be successful
if you issue it again. Explanation: The HT status indicates that the
High-Water-Mark time stamp (HWM TS) is less than the
Logical Begin time stamp (LB TS).
GK
Programmer Response: The time stamp in the
Explanation: DL/I has returned a different segment
High-Water-Mark segment was not updated on the area
type at the same hierarchic level for an unqualified GN or
data set during utility setup and partner notification.
GNP call.
Check whether the data-sharing partner is still running.
Rather than having an abnormal termination occur, this The RLM may have a lock for the sequential dependent
status code is returned to the application program that CI.
issued the EXEC DLI command. This call results in a
return and reason code of 0.
II
Explanation: The program issued an ISRT call that
status code.
tried to insert a segment that already exists in the
database. Current position after an II status code is just
GL before the duplicate of the segment you tried to insert.
Some of the reasons for receiving this status code are:
Explanation: For either call-level or command-level
programs: v A segment with an equal physical twin sequence field
already exists for the parent.
The program issued a LOG request that contained an v A segment with an equal logical twin sequence
invalid log code for user log records. The log code in a already exists for the parent.
LOG request must be equal to or greater than X'A0'.
v The logical parent has a logical child pointer, the
For call-level programs: logical child does not have a logical twin pointer, and
the segment being inserted is the second logical child
DL/I returns GL on a DEQ request when the first byte of
for that logical parent.
the I/O area referenced in the request did not contain a
valid DEQ class (B-J). v The segment type does not have physical twin
forward pointers and the segment being inserted is
For command-level programs: the second segment of this type for that parent, or it
EXECDLI returns a GL status for either a GN, GNP, GU, or is the second HDAM or PHDAM root for one anchor
DEQ command when the alphabetic character coded on point.
the LOCKCLASS option is not within the range of B to v The segment being inserted is in an inverted
J. An ABENDU1041 is then issued. structure. (The immediate parent of this segment in
the logical structure is actually its physical child in the
Programmer Response: Correct the log code, which
physical structure.)
is the first byte of the log message.
v A physically paired logical child segment already
For call-level programs: exists with a sequence field equal to that of the
If the program received this status code for a DEQ segment you’re inserting. For example, the segment
request, check the DEQ class code in the I/O area. could have been inserted with no duplication, but
when an attempt was made to position for the insert
For command-level programs: of its physical pair, the segment had a duplicate key
to an existing twin segment.
Check the alphabetic character coded for class on the
LOCKCLASS option to ensure that it is in the range v An application program inserted a key of X'X’FF...FF’'
from B to J. into a HISAM, HIDAM, or PHIDAM database.

GP status code is returned to the application program that
Explanation: The program issued a GNP when there is issued the EXEC DLI command.
no parentage established, or the segment level Programmer Response: User determined.
specified in the GNP is not lower than the level of the
established parent.
IX
Programmer Response: Make sure you have
established parentage before issuing GNP, and check Explanation: The program issued an ISRT call that
the segment level specified by the GNP. violated the insert rule for that segment. Some of the
reasons that IMS returns this status code are:

L2 • MR
v The program tried to insert the logical child and
LC
logical parent, and the insert rule for the logical
parent is physical and the logical parent does not Explanation: The key field of the segment being
exist. loaded is out of sequence.
v The program tried to insert the logical child and the Programmer Response: Check the segment and
logical parent, and the insert rule is logical or virtual determine where it should be loaded.
and the logical parent does not exist. In the I/O area,
the key of the logical parent does not match the
corresponding key in the concatenated key in the LD
logical child. Explanation: No parent has been loaded for the
v The program tried to insert a logical child, and the segment being loaded.
insert rule of the logical parent is virtual and the
logical parent exists. In the I/O area, the key in the Programmer Response: Check the sequence of
logical parent segment does not match the segments that have been loaded and determine where
corresponding key in the concatenated key in the the parent should have been loaded.
logical child.
v The program tried to insert a physically paired LE
segment, where both sides of the physical pair are
Explanation: The sequence of sibling segments being
the same segment type and the physical and logical
loaded is not the same as the sequence that is defined
parent are the same occurrence.
in the DBD.
v The program issued an ISRT call to a GSAM
database after receiving an AI or AO status code. Programmer Response: Check and correct the
sequence of the segments that are being loaded.
Programmer Response: Correct the ISRT or the
program.
LF
1 L2 Explanation: The source data for a logical child

segment was found in the input stream of a load job for
1 Explanation: The application program needed to a High Availability Large Database (HALDB). Logical
1 allocate SDEP CI RBAs to contain the application child segments cannot be loaded into a HALDB PHDAM
1 programs’ insert activity for a particular AREA in the or PHIDAM database. Instead, the segments must be
1 DEDB, but the request to acquire the AREA lock failed. added later in an update run.
1 Programmer Response: Contact the IMS DBA or the Programmer Response: Remove all source data for
1 IMS Systems Programmer. logical child segments from the load job and insert them
later with an update job.
LB
Explanation: The segment that the program tried to LS
load already exists in the database. Other possible Explanation: The LS status means that an application
causes are: program needed to allocate SDEP CI RBAs to contain
v A segment with an equal physical twin sequence field the application programs’ insert activity for a particular
already exists for the parent. area in a Data Entry Database and the CIs could not be
v A segment type does not have a physical twin locked by the RLM. The application work may be
forward pointer, and the segment being inserted is committed, but some other application work may not
either the second segment of this segment type for have enough CI space, depending on how much SDEP
the parent or the second HDAM or PHDAM root for insert work was done and the first committed
one anchor point. application.
v An application program inserted a key of X'FF...FF' Programmer Response: Do a commit and be careful
into a HISAM, HIDAM, or PHIDAM database. not to insert too many more SDEP segments.
Rather than having an abnormal termination occur, this MR

issued the EXEC DLI command. 2 Explanation: An error was detected by the Queue
2 Control Facility (QCF) routines on a GU, GN, ISRT,
Programmer Response: Correct the ISRT call or 2 CMD, or PURG call. If the application program issuing
LOAD command, or find out if the load sequence is 2 the call is not the QCF (product 5699-E97) licensed
incorrect. Check with the DBA or the equivalent 2 product, then the problem is an invalid usage of the
specialist at your installation. 2 MRQPSB block. The PSB block may only be used by
2 those products. Refer to the IMS Version 7 Installation
NA • NO
2 Volume 2: System Definition and Tailoring, MSGQUEU
NI
2 macro, MRQPSBN= parameter for instruction on
2 specification and use of the PSB. If the application Explanation:
2 program is the QCF program, then the AIBRETRN code v There is a duplicate segment in a unique secondary
2 should be 000000F0. Locate the AIBREASN code and index. While IMS was inserting or replacing a source
2 refer to the DFSMRAEQ IMS macro for information on segment for a secondary index defined with a unique
2 MQR/QCF AINREASN codes. sequence field, the insertion of the secondary index
Programmer Response: If the application program is segment was attempted but was unsuccessful
not QCF, then use a PSB other than MRQPSB. because an index segment with the same key was
found. One possible cause for a duplicate segment in
If the application is QCF, locate the AIBREASN code the index is that the index DBD incorrectly specified a
and refer to the DFSMRAEQ IMS macro for information unique key value—secondary index only.
on MQR/QCF AIBREASN codes. Refer to IMS Queue
v A data management open error occurred when
Control Facility for z/OS™ V1R2, Users Guide for
opening the index data set.
AIBREASON codes.
In an online application program, the call is backed out
NA and the program receives an NI status code.
Explanation: The INIT call with DBQUERY in the I/O
For a batch program that does not log to the IMS DASD
area or the QUERY command was issued, and at least
log, IMS abnormally terminates the program with a
one of the databases that could be accessed using this
U0828 abend. You should run batch backout.
PCB was not available.
Programmer Response: The response is determined
A request made using this PCB will probably result in a
by the user. If duplicate secondary index entries occur,
BA status code if the INIT STATUS GROUPA has been
specify the index as non unique, and provide an
issued or in a DFS3303I message and 3303 pseudo
overflow entry-sequenced data set. If an open error
abend if it has not. An exception is when the database
occurred examine message DFS0730I for the cause of
is not available because dynamic allocation failed. In
the open error.
this case, a request results in an AI (unable to open)
status code.
NL
status code. Explanation: The application program issued an
extended checkpoint call. Checkpoint information is
written to the log data set, but there is no DD statement
NE
in the batch step for the log, so no checkpoint was
Explanation: Indexing maintenance issued a DL/I call, written. The DD name for the log data set is IEFRDER.
and the segment has not been found. This status code Although no checkpoint information was written, normal
is included in message DFS0840I. The system console commit processing was performed.
receives message DFS0840I INDEX ERROR (dbdname) NE
Programmer Response: Provide an IEFRDER DD
(first 45 bytes of key). The application program receives
statement. No status is returned for a DD DUMMY
a blank status code.
statement.
An application program could have processed a
secondary index as a database and thus deleted some
NO
of the secondary index entries. Subsequently, when a
source segment is deleted, the secondary index for the Explanation: A BSAM or VSAM physical I/O error
source statement might not be present. For this reason, occurred during a database request that is issued by
when the application program deletes a source segment the index maintenance function.
and the index entry is not present, the DFS0840I
message is sent to the system console, but a blank For an online program, all updates made for the call are
status code is returned to the application program. backed out and the application program receives the
NO status code. For a batch program that does not log
Programmer Response: Determine whether the to the IMS DASD log, IMS abnormally terminates the
secondary index has been processed as a database program with an 826 abend.
and, as a result, the key included in the DFS0840I
message was deleted. If this is not the case, check the Programmer Response: See accompanying
cause for the index inconsistency with the database and messages giving details of the error. In a batch
correct it. environment, run batch backout.

NU • QH
v IMS wants to reschedule the region (quick
NU
reschedule). For more information regarding quick
Explanation: An ISRT, DLET, or REPL request using reschedule, refer to IMS Version 7 Administration
this PCB might result in a BA status code if the INIT Guide: System.
STATUS GROUPA call or QUERY command has been
issued or in a DFS3303I message or 3303 pseudo
status code. The application program should terminate.
abend if it has not. If the unavailable database is only
required for delete processing, it is possible that the
ISRT and REPL requests can be processed. QD
Programmer Response: This is an information-only Explanation: The program issued a message GN or
status code. GCMD call, but there are no more segments for this
message.
OS Programmer Response: Process the message.
Explanation: The OS status indicates that the
STOPRBA parameter value given for the DEDB QE
Sequential Dependent Scan Utility is too large for the
current sequential dependent CI set. Explanation: The program issued a message GN call
before issuing a GU call to the message queue. In
Programmer Response: Check the parameter value message-driven Fast Path programs, this code applies
for validity and use a correct value or use the utilities to message calls only. The program issued a message
default value for the scan end. GN call before issuing a GU call to the message queue. In
message-driven Fast Path programs, this code applies
to message calls only. This code is also returned when
QC
a program issues a ROLB call, specifying the I/O area
Explanation: There are no more messages in the parameter, without having issued a successful message
queue for the program. The reasons that IMS returns GU call during that commit interval. A message-driven
this status code are: Fast Path program issued a CHKP call to establish an
v An application program issued a successful CHKP call, internal GU call but the CHKP call failed with a status QC
but the message GU call issued internally by the CHKP code. A successful GU call was never issued during the
call was unsuccessful (that is, it did not return a commit interval for the failing CHKP call. Information only
message). status code for calls encountering SDEP full or FLD
verify failures which are reprocessed via ROLB.
v An application program processing APPC
synchronous messages that does not set sync points Programmer Response: Correct the program by:
for each message GU call (that is, mode=MULT on the v Issuing a GU call before the GN call
TRANSACT macro) is returned a QC status code to
v Issuing a CMD call before the GCMD call
force a sync point after each GU call.
v Issuing a GU call before the ROLB call
For more information regarding the TRANSACT
macro, refer to IMS Version 7 Installation Volume 2:
System Definition and Tailoring. QF
v An MPP or transaction-oriented BMP issued a GU call 1 Explanation: When using Shared Queues and the
to retrieve another message, but either there are no 1 application ISRT(S) results in a message that spans
more messages or the processing limit (that is, 1 multiple queue buffers, the second and subsequent
PROCLIM=parm on the TRANSACT macro) has 1 buffers are PUT to the Shared Queues. If the Shared
been reached. 1 Queues are full and those CQS PUTs are rejected, this
v IMS is shutting down or: 1 results in a STATUSQF being passed back to the
– A /PSTOP REGION command has been issued for 1 application.
the dependent region in which the application 1 Programmer Response: Correct the segment. Issue a
program is processing. 1 ROLB to back out any incomplete data.
– A database dump (/DBD) command has been
issued.
QH
– A database recovery (/DBR) command is in
operation. Explanation: There has been a terminal symbolic
– A stop subsystem (/STOP SUBSYS) command error. The output logical terminal name or transaction
has been issued. code is unknown to IMS. Some reasons for receiving
this status code are:
For more information regarding these commands,
refer to IMS Version 7 Command Reference. v The program tried to insert an alternate response
PCB receiving a QC status code for a GU call.
RA • TA
v The program tried to insert to an I/O PCB that has a
RX
logical terminal name of blanks. This could occur
after the program issued a GU call for a message that Explanation: The program issued a REPL that violated
originated either from a batch-oriented BMP or a CPI the replace rule for that segment.
Communications driven program.
Programmer Response: Correct the REPL call, or
v SMB or CNT could not be found. check with the DBA or the equivalent specialist at your
v The program deallocated a conversation with a SETO installation.
call with the DEALLOCATE_ABEND option. Any
subsequent ISRT calls are rejected with this status
SA
code.
v The program issued an ISRT call without first issuing Explanation: On a SETS request, IMS was not able to
a GU call. obtain the storage space for the data in the I/O area.
v The logical terminal name or transaction code Programmer Response: Use a larger region size for
specified is Fast Path exclusive and is not available the job step.
to this program.
v The program issued an ISRT call for a segment SB
shorter than 5 bytes.
v The program issued an ISRT call for a SPA shorter Explanation: The maximum number of levels, nine, of
than 6 bytes. SETS requests were already specified, and this request
is attempting to set the tenth.
v The logical terminal name or transaction code has
leading blanks, instead of being left-justified. Programmer Response: Correct the program.
Programmer Response: Check the logical terminal

name or transaction code, and correct it. SC
Explanation: A SETS or SETU call was issued with
RA unsupported PCBs (DEDB, MSDB, or GSAM) in the
PSB, or the program is using an attached subsystem.
Explanation: The token does not match a token for
any outstanding SETS requests or the request was Programmer Response: For a SETS call, the request
issued for a database PCB that did not get a BA status is rejected. Remove the unsupported PCBs or use the
on the previous request. SETU call. For a SETU call, the program can proceed with
the knowledge that a ROLS call will not back out changes
Programmer Response: The outstanding SETS for the unsupported PCBs. The other option is to not
request might have been canceled by a commit use the SETS or ROLS function.
process, or an error exists in the use of the token.
SY
RC
Explanation: IMS incurred an internal error during
Explanation: The ROLS call was issued with Syncpoint processing for an IMS/JAVA SYNC request
unsupported PCBs in the PSB, or the program is using call.
an attached subsystem. If the ROLS call is in response to
a SETS call, the call is rejected. If the ROLS call is in Programmer Response: Contact your IMS system
response to a SETU call, the call is processed, but programmer.
updates to unsupported PCBs or an attached
subsystem are not backed out. This status is only
TA
returned for a ROLS call in response to a SETU call if an
attached subsystem is being used. Explanation: This status code applies to CICS online
command-level programs only, and it is returned
Programmer Response: User determined.
following a scheduling request. The PSB named in the
Explanation: The ROLS request was rejected because request is not in the PSB directory.
the PSB contains access to a DEDB, MSDB, or GSAM
Programmer Response: Correct the name of the PSB
organization or has access to an attached subsystem.
in the scheduling request, or add the PSB name to the
Programmer Response: The ROLS request is invalid in PSB directory.
this environment. The program must either remove the
use of the database organization that is preventing the
use of the ROLS call or not use the ROLS call.

TC • TO
specifying a FROM option for each segment to be
TC
transferred.
Explanation: This status code applies to CICS online
TJ
following a scheduling request. It means that you have
already scheduled a PSB. Explanation: This status code applies to CICS online
command-level programs only, and it can be returned
Programmer Response: Correct your program so that
after any command that a CICS online program uses.
you terminate a PSB before scheduling another. If you
DL/I is not active.
want to reschedule a PSB, you must have already
terminated the PSB. Programmer Response: Contact your DBA. CICS
must be reinitialized with DL/I defined as active in the
SIT.
TE
TL
following a scheduling request. The PSB could not be Explanation: This status code applies to CICS online
scheduled because an initialization error occurred. command-level programs only, and it is returned after a
scheduling request. A conflict in scheduling intent
Programmer Response: See your system
occurred. (This cannot occur if program isolation has
programmer or DBA. For information on possible
been specified.)
causes for the PSB initialization error, see IMS Version
7 Application Programming: Database Manager. Programmer Response: Specify program isolation in
the SIT. If program isolation has not been specified, wait
until the PSB is no longer in use, and reschedule it.
TG
TN
following a terminate request. The program issued a Explanation: This status code applies to
terminate request when there was no PSB scheduled. command-level programs only, and it can be returned
after any of the commands. An invalid SDIB exists. An
initialization call was not made, or the system’s DIB (not
status code. If you only wanted to terminate a PSB,
the application program’s DIB) was overlaid.
continue with processing. If you also wanted to cause a
sync point, issue a SYNCPOINT command. (No sync Programmer Response: Check your program to
point was caused by the unsuccessful terminate make sure that you did not use an entry statement, as
request.) you would in a call-level batch program. Also make sure
that no addressing errors are in your program that
would cause an overlay.
TO
TH Explanation: This status code applies to
following a REPL command. A path-replace error
occurred. The segments to be replaced are compared
following a database request or a statistics request. The
to the previous Get command and one of the following
program attempted to access the database before
situations occurred:
scheduling a PSB.
v A segment is named to be replaced that was not
Programmer Response: Correct your program, and retrieved by the Get command.
schedule a PSB before accessing the database.
v Data had not been transferred (no INTO option) for
this segment on the Get command.
TI v The attributes of the data to be transferred do not
Explanation: This status code applies to match the data in the database.
command-level programs only, and it is returned after Programmer Response: Correct the program.
an ISRT command. The ISRT command defined an
invalid path to the segment. Data must be transferred
for all segments between the first named segment and
the last named segment.
Programmer Response: Correct the ISRT command,
TP • UR
available for the private buffer pool.
TP
If the DBFHUSS0 return code is 10, the request for
Explanation: This status code applies to
private buffers is for the initial buffer set and the private
pool anchor address already exists.
following any of the database commands, a LOAD
command, or a statistics request. The number of the
PCB specified in the USING option is higher than the UC
number of PCBs in the PSB being used, or an invalid
processing option was specified. For example, the Explanation: This status code is returned for the
program tried to issue a LOAD command without having following reasons:
the L processing option specified in its PSB. v For batch programs in which a checkpoint record was
written to the UCF journal data set. For information
An EXEC DLI command is being attempted against a about the Utility Control Facility (UCF), see IMS
GSAM PCB. This is invalid. Version 7 Administration Guide: Database Manager
Programmer Response: Check the PSB and correct and IMS Version 7 Utilities Reference: Database and
your program. Transaction Manager.
During the processing of an HD reorganization, a
reload, or an initial load program under the
TR
supervision of the Utility Control Facility (UCF), a
Explanation: This status code means that the CICS checkpoint record was written to the UCF journal
XDLIPRE exit routine returned X'04' in register 15 data set. IMS returns this status code to indicate that
because the routine determined that the immediately the last ISRT call was correct and the initial load
preceding DL/I request should not be executed. program might continue or it might perform a
checkpoint procedure before continuing.
Programmer Response: Contact the CICS system
programmer. v When a connect failed.
TY status code for the first status code reason above.
Explanation: This status code applies to CICS online When this status code is issued for a connect failure,
command-level programs only, and it is returned see message DFS0535I for more information on how to
following a database or statistics request. The database correct the error.
was not open when the request was issued.
Programmer Response: Contact your DBA or system UP
programmer. The database can be checked and opened Explanation: This status code is returned when the
by using operator commands. UOW requested is greater than the UOW range.
Programmer Response: Correct the error and run the
TZ job again.
command-level programs only, and it is returned UR
following a database or statistics request. The length of
the retrieved segment is greater than 64 KB. Explanation: This status code is returned for batch
programs only. Your initial load program is being
Programmer Response: Contact your DBA or system restarted under UCF. For information about the Utility
programmer; the database definition might require Control Facility (UCF), see IMS Version 7 Administration
modification. Guide: Database Manager and IMS Version 7 Utilities
Reference: Database and Transaction Manager. The
UB program terminated while executing under UCF. The job
was resubmitted with a restart request.
Explanation: This status code is returned when IMS is
unable to obtain private buffer pool. Programmer Response: Ensure that the program is
in proper sequence with database loading. The program
Programmer Response: No DFS0535I message is uses the I/O area and the DB PCB key feedback area
issued if the High Speed Reorganized Utility (HSRE) is to do this.
being used when this status code is received. See the
DFS2712I messages issued at utility termination for the
name of the module, abend subcode, Utility High Speed
Workarea (UHSW) storage area dump, IOAR (DEDB
I/O), and register contents.
If the DBFPAPB0 return code is 08, storage is not

US • V5
edit/compression routine; processing with an
US
edit/compression routine, but not specifying the key
Explanation: This status code is returned for batch compression option; or coding a length field (LL) that is
programs only. The initial load program is about to stop less than the specified minimum length. The length
processing. While processing an HD reorganization must be long enough to include the entire reference
reload or user initial load program under the supervision field; if the segment is a logical child, it must include the
of UCF, the operator replied to the WTOR from UCB entire concatenated key of the logical parent and all
and requested the current function to terminate. For sequence fields for the paired segment. The program
information about the Utility Control Facility (UCF), see tried to delete a variable-length segment. The copy of
IMS Version 7 Administration Guide: Database Manager this segment in the user’s I/O area contains an invalid
and IMS Version 7 Utilities Reference: Database and length field.
Transaction Manager. The last ISRT call was processed.
IMS also returns this status code when an invalid record
Programmer Response: Ensure that the initial load length is specified in a GSAM call.
program performs a checkpoint procedure of its data
sets and returns with a nonzero value in register 15.
V2
UW
Explanation: This status code is returned when IMS is
unable to obtain a work area.
following a database or LOAD command. The segment
Programmer Response: Increase the REGION size length is missing or invalid. The segment length must
and run the job again. be a positive integer. For variable-length segments, it is
the maximum size acceptable to the program’s I/O area.
UX Programmer Response: Check that the program
translated and compiled correctly. The value of any
Explanation: This status code is returned for batch
segment length in a path command should not exceed
programs only. A checkpoint record was written, and
32 KB, and the sum of the lengths should not exceed
processing stopped. This is a combination of UC and
64 KB.
US status codes.
Programmer Response: See the descriptions of UC
V3
and US status codes.
U1
following a Get or ISRT command. The field length is
Explanation: This status code is returned when the missing or invalid. The field length must be a positive
area name specified is not valid. integer, and it must be specified for each field in a
WHERE option.
Programmer Response: Correct the error and run the
utility job again. Programmer Response: Correct the program.
U9 V4
Explanation: This status code is returned when the Explanation: This status code applies to
area access intent is read or read only. Access intent command-level programs only, and it is returned
must be UP or EX. following any of the database commands or a LOAD
command. The length of a variable-length segment is
Programmer Response: Use the /STA DB ACCESS invalid. The LL field as provided by the program on an
command to set the access intent to UP or EX and run ISRT or REPL command, or as received in the I/O area
the job again. on a Get command, exceeds the value of
SEGLENGTH.
V1 Programmer Response: Correct the program.
Explanation: The program tried to insert or replace a
variable-length segment that is too long. The length of V5
the segment must be equal to or less than the
maximum length specified in the DBD. IMS also returns Explanation: This status code applies to
status code V1 when the specified minimum length command-level programs only, and is returned following
cannot hold the complete sequence field of the segment a Get, REPL, or ISRT command. The offset is invalid. The
type. In this situation, status code V1 results from one offset must be a positive integer and not greater than
of three instances: processing without an the segment length.
V6 • XX
Programmer Response: Correct the program. IMS also returns XD when a batch program issues a
SYNC call.
V6 Programmer Response: Terminate the program
immediately. IMS will terminate the program abnormally
if the program issues another call.
following a Get or ISRT command using the KEYS
option. The concatenated key length is missing or XE
invalid. The length of the concatenated key must be a
Explanation: A program tried to insert a SPA to an
positive integer.
alternate express PCB.
Programmer Response: Regenerate the PSB and
remove the EXPRESS=YES option from the PCB, or
V7 define another non-express PCB to be used in the ISRT
call.
command-level programs only, and is returned following
a STAT command. It means that the statistics area XF
length is either too small or invalid. The length must be
Explanation: IMS is ignoring the ISRT call for the SPA,
a positive integer, and it must be at least 72 bytes for
because the specified alternate PCB had its destination
unformatted statistics, 120 bytes for summary statistics,
set to a logical terminal but was not defined as
and 360 bytes for formatted statistics.
ALTRESP=YES during PSB generation.
MSC directed routing does not support a
program-to-program switch between conversational
XA transactions.
Explanation: The program tried to continue Programmer Response: Correct the application
processing the conversation by passing the SPA to program or change the PSB generation for that
another program through a program-to-program alternate PCB to specify ALTRESP=YES.
message switch after already responding to the
terminal.
XG
Programmer Response: If a response has been sent,
Explanation: IMS ignored the ISRT call because the
the SPA should be returned to IMS. Correct the
current conversation requires a fixed-length SPA, and
program.
the ISRT call was to a program with a different length or
variable-length SPA, while the source IMS system was
XB earlier than IMS 6.1. If the SPA ISRT on a remote
system is not going back to the input terminal (IOPCB),
Explanation: The program has passed the SPA to
the SPA size must be the same as the size of the
another program but is trying to respond to the
current one, if the source IMS system is earlier than
originating terminal.
IMS 6.1.
Programmer Response: No response is allowed by a
Programmer Response: Correct the program or the
program that is passed control of the program through a
SPA definitions.
program-to-program message switch.
XX
XC
Explanation: An error occurred during GSAM
Explanation: The program inserted a message that
initialization or during GSAM call processing. If this
has some bits in the Z1 field set. The Z1 field is
status code is in the GSAM PCB before the application
reserved for IMS.
program issued the first call, the error was detected
Programmer Response: Correct the program to during initialization. Possible causes are:
prevent it from setting those bits. v Insufficient space
v Invalid DBD
XD v Invalid block size
Explanation: IMS is terminating by a CHECKPOINT v Invalid option
FREEZE or DUMPQ. IMS returns this code to a BMP v Internal GSAM error
that has issued a CHKP or SYNC call. If it is a
transaction-oriented BMP, IMS does not return a Programmer Response: A subsequent GSAM call will
message.

X2 • blanks (bb)
result in an abnormal termination of the program. The
program should terminate.
X2 blanks (bb)
Explanation: The first ISRT call to an alternate PCB Explanation: The call was completed.
whose destination is a conversational transaction code
Programmer Response: Proceed with processing.
is not for the SPA. The SPA must be inserted with the
first ISRT call.
Programmer Response: Insert the SPA, and then
reinsert the message segment.
X3
Explanation: The program modified the first 6 bytes of
the SPA; the SPA is now invalid.
Programmer Response: Correct the program and
restore the original bytes.
X4
Explanation: The program issued an ISRT call to pass
the SPA to a nonconversational transaction code. It did
this by referencing a PCB whose destination was set for
the nonconversational transaction code. You can send
the SPA only to transaction codes that are defined as
conversational.
Programmer Response: Correct the ISRT call. Send
only data segments.
X5
Explanation: The program issued more than one ISRT
call to send the SPA to a PCB whose destination is a
transaction code. Only one SPA is allowed per
message.
X6
Explanation: An invalid transaction code name was
inserted into the SPA. This will occur if the input is from
LU 6.2 (APPC) or OTMA and if a dynamic control block
was built for the transaction code.
Programmer Response: Correct the program to set
the proper transaction code name.
X7
Explanation: The length of the SPA is incorrect. The
program modified the first 6 bytes.
Programmer Response: Correct the SPA and the
program.
Part 3. Appendixes

Bibliography
This bibliography includes all the publications cited GC26-9429 IIV IMS Version 7 Installation
in this book, including the publications in the IMS Volume 1: Installation and
library. Verification
CICS/ESA Version 4.1 Application GC26-9430 ISDT IMS Version 7 Installation
Programming Guide, SC33-1169 Volume 2: System Definition
and Tailoring
CICS/ESA Version 4.1 Application SC26-9432 MIG IMS Version 7 Master Index
Programming Reference, SC33-1170 and Glossary
CICS Family: General Information, GC33-0155 GC26-9433 MC1 IMS Version 7 Messages and
CICS Transaction Server for OS/390 Release Codes, Volume 1
3 CICS Application Programming Guide, GC26-1120 MC2 IMS Version 7 Messages and
Codes, Volume 2
SC33-1687
SC26-9434 OTMA IMS Version 7 Open
CICS Transaction Server for OS/390 Release Transaction Manager Access
3 CICS Application Programming Reference, Guide
SC33-1688 SC26-9435 OG IMS Version 7 Operations
Guide
GC26-9437 RPG IMS Version 7 Release
IMS Version 7 Library Planning Guide
SC26-9438 SOP IMS Version 7 Sample
Operating Procedures
SC26-9419 ADB IMS Version 7 Administration
Guide: Database Manager SC26-9440 URDBTM IMS Version 7 Utilities
Reference: Database and
SC26-9420 AS IMS Version 7 Administration
Transaction Manager
Guide: System
SC26-9441 URS IMS Version 7 Utilities
SC26-9421 ATM IMS Version 7 Administration
Reference: System
Guide: Transaction Manager
SC26-9422 APDB IMS Version 7 Application
Programming: Database Supplementary Publications
Manager
SC26-9423 APDG IMS Version 7 Application GC26-9431 LPS IMS Version 7 Licensed
Programming: Design Guide Program Specifications
SC26-9424 APCICS IMS Version 7 Application SC26-9439 SOC IMS Version 7 Summary of
Programming: EXEC DLI Operator Commands
Commands for CICS and
IMS
SC26-9425 APTM IMS Version 7 Application
1 Publication Collections
Programming: Transaction 1 LK3T-3526 CD IMS Version 7 Licensed
Manager 1 Product Kit: Online Library
SC26-9427 CG IMS Version 7 Customization LBOF5294 Hardcopy Licensed Bill of Forms (LBOF):
Guide and CD IMS Version 7 Hardcopy and
SC26-9426 CQS IMS Version 7 Common Online Library
Queue Server and Base SBOF5297 Hardcopy Unlicensed Bill of Forms
Primitive Environment Guide (SBOF): IMS Version 7
and Reference Unlicensed Hardcopy Library
SC26-9436 CR IMS Version 7 Command SK2T-0730 CD IBM Online Library: Transaction
Reference Processing and Data
SC26-9428 DBRC IMS Version 7 DBRC Guide 1 SK2T-6700 CD IBM Online Library OS/390
and Reference
LY37-3738 DGR IMS Version 7 Diagnosis
Guide and Reference
LY37-3739 FAST IMS Version 7 Failure
Analysis Structure Tables
(FAST) for Dump Analysis
SC27-0832 IJUG IMS Version 7 IMS Java
User’s Guide

Index
A COBOL (continued)
I/O area 72
ACCEPT command
codes, status
description 49
explanations 127
examples 49
tables 117
format 49
command-level programs
options 49
comparing with call-level programs
usage 49
command codes and options 114
AIB (Application Interface Block)
commands and calls 113
AIB mask 67
DIB (DL/I interface block) 68
restrictions 68
DL/I calls available to IMS and CICS 113
supported commands 67
I/O area, defining 71
AJ status code 101
key feedback area, defining 71
Alternate PCB 11
preparing EXEC DL/I program for execution 91
AM status code 101
sample assembler language 74
assembler language
sample C 85
DL/I command-level sample 74
sample COBOL 78
I/O area 72
sample PL/I 81
status codes, checking 69
syntax of EXEC DLI commands 13
B commands, EXEC DLI
backing out database changes 106 ACCEPT 49
backout points, intermediate 106 CHKP 49
basic checkpoint 105 DEQ 50
batch program, issuing checkpoints 105 DLET 15
batch programs, command-level samples GN 17
assembler 74 GNP 22
C 85 GU 27
COBOL 78 ISRT 33
PL/I 81 LOAD 51
BILLING segment 9 LOG 52
BMP (batch message processing) program, issuing POS 39
checkpoints 105 QUERY 53
REFRESH 54
REPL 40
C RETRIEVE 44
C program, DL/I command-level sample 85 ROLB 55
call-level programs ROLL 56
comparing with command-level programs ROLS 57
command codes and options 114 SCHD 46
commands and calls 113 SETS 58
DL/I calls available to IMS and CICS SETU 59
command-level 113 STAT 60
categories, status codes 117 SYMCHKP 61
checkpoint (CHKP) TERM 47
EXEC DLI command XRST 63
basic 105 comparing EXEC DLI commands with DL/I calls 113
current position 105 comparing EXEC DLI options with command
symbolic EXEC DLI command, description 106 codes 114
CHKP (Checkpoint) command compiling, options with EXEC DLI 91
description 49, 105 crossing a unit of work (UOW) boundary when
examples 50 processing DEDBs 103
format 49
options 49
restrictions 50 D
usage 50 data availability enhancements 109
COBOL

data entry database DLET (Delete) command (continued)
See DEDB (data entry database) Restrict 16
database availability usage 16
obtaining information 109 dynamic backout 106
status codes, accepting 109
database description name field, DIB (DL/I interface
block) 71 E
database example, medical hierarchy 8 EXEC DLI
database integrity, maintaining 105 allowable commands 14
database organization field, DIB (DL/I interface compiler options, required 91
block) 71 linkage editor options, required 92
database processing, fast path 93 preparing program for execution 91
database recovery, planning for program summary 13
backing out database changes 106 syntax of commands 13
checkpoints, take with basic CHKP command 105 translator options, required 91
checkpoints, taking 106 EXEC DLI commands
restarting your program, XRST command 106 ACCEPT 49
DB PCB 11 CHKP 49
DBCTL facilities DEQ 50
ACCEPT command 109 DLET 15
data availability 109 GN 17
QUERY command 109 GNP 22
REFRESH command 109 GU 27
ROLS command 107 ISRT 33
SETS command 107 LOAD 51
DEDB (data entry database) LOG 52
processing POS 39
overview 93 QUERY 53
POS command 101 REFRESH 54
subset pointers 93 REPL 40
defining application program elements to IMS RETRIEVE 44
AIB 67 ROLB 55
DIB 68 ROLL 56
I/O area 71 ROLS 57
key feedback area 71 SCHD 46
DEQ (Dequeue) command SETS 58
description 50 SETU 59
examples 51 STAT 60
format 51 SYMCHKP 61
options 51 TERM 47
restrictions 51 XRST 63
usage 51 EXEC DLI options, use with subset pointers 95
DIB (DL/I interface block)
accessing information 68
database description name field 71 F
database organization field 71 fast path database, processing 93
fields 68 Fast Path, subset pointers with DEDBs 93
key feedback length field 71 fields in DIB 68
segment level field 70 FIRST insert rule 37
segment name field 70 free space, identifying 102
status code field 69
structure 68
translator version 69
direct dependent segments, in DEDBs 93
G
GC status code 103
DL/I interface block
general programming guidelines 73
See DIB (DL/I interface block)
GETFIRST option
DLET (Delete) command
examples 96
description 15
retrieving first segment in subset 96
example 16
GN (GET NEXT) command
format 15
description 17
options 15
examples 21
GN (GET NEXT) command (continued)
format 17
L
LAST insert rule 37
options 18
level number field in DIB 70
restrictions 22
link editing, EXEC DLI 92
usage 21
linkage editor options with EXEC DLI 92
GNP (GET NEXT in Parent) command
LOAD (Load) command
description 22
description 51
examples 26
examples 52
format 22
format 52
options 23
options 52
restrictions 27
usage 52
usage 26
locating
GSAM PCB 11
a specific sequential dependent 101
GU (GET UNIQUE) command
last inserted sequential dependent 102
description 27
LOG command
examples 32
description 52
format 27
examples 53
options 29
format 53
restrictions 33
options 53
usage 32
restrictions 53
guidelines, general programming 73
usage 53
H M
HERE insert rule 37
medical database example
hierarchical database example, medical 8
description 8
HOUSHOLD segment 10
segments 8
MOVENEXT option
examples 98
I use when moving subset pointer forward 98
I/O area moving subset pointer forward 98
assembler language 72
COBOL 72
coding 72
command-level program 71
O
online programs, command-level samples
PL/I 72
assembler 74
symbolic CHKP 106
C 85
XRST 106
COBOL 78
I/O PCB (input/output PCB) 11
PL/I 81
ILLNESS segment 8
options for subset pointers
intermediate backout points 106
GETFIRST 96
ISRT (insert) command
MOVENEXT 98
insert rules 37
SET 98
ISRT (Insert) command
SETCOND 99
description 33
SETZERO 97
examples 38
format 34
options 34
restrictions 38 P
usage 37 P processing option 103
issue checkpoints in batch or BMP programs 105 path command 44
PATIENT segment 8
PAYMENT segment 9
K PCB (program communication block)
in application programs, summary 12
key feedback area
types 11
command-level program 71
PL/I
length field in DIB 71
I/O area 72
pointers, subset
DBD, defining 95
Index 157
pointers, subset (continued) restarting your program, with EXEC DLI XRST
description 93 command 106
GETFIRST option 96 RETRIEVE command
MOVENEXT option 98 description 44
preparation for using 95 examples 46
PSB, defining 95 format 45
sample application 95 options 45
SET option 98 restrictions 46
SETCOND option 99 usage 45
SETZERO option 97 ROLB (Rollback) command
status codes 101 description 55
POS command examples 55
description 39 format 55
EXEC DLI command format 39 options 55
format 39 restrictions 55
free space, identifying 102 usage 55
locating a specific sequential dependent 101 ROLL command
locating the last inserted sequential dependent 102 description 56
options 39 examples 56
usage 40 format 56
using with DEDBs 101 options 56
processing restrictions 56
DEDBs 93 usage 56
Fast Path, P (position) option 103 ROLS command 107
programming guidelines, general 73 description 57
PSB (program specification block), format 12 examples 57
format 57
options 57
Q restrictions 58
QUERY command usage 57
description 53 RULES=FIRST 37
example 53 RULES=HERE 37
format 53 RULES=LAST 37
options 53
restrictions 54
usage 53 S
sample programs
command-level assembler language
R batch 74
randomizing routine, FM status code 138 online 74
recovering databases 105 command-level C
recovery EXEC DLI commands batch 85
basic CHKP 105 online 85
SYMCHKP 106 command-level COBOL
XRST 106 batch 78
REFRESH command 109 online 78
description 54 command-level PL/I
example 54 batch 81
format 54 online 81
options 54 SCHD (Schedule) command
restrictions 55 description 46
usage 54 examples 47
REPL (Replace) command format 46
description 40 options 46
examples 43, 44 usage 47
format 41 segment level number field 70
options 41 segment name field, DIB (DL/I interface block) 70
restrictions 44 segments in medical database example 8
usage 42 sequential dependent segments
resetting a subset pointer 98 free space, identifying 102
in DEDBs 93
sequential dependent segments (continued) SYMCHKP (Symbolic Checkpoint) command
locating a specific dependent 101 current position 62
locating the last inserted dependent 102 description 61, 106
POS command 101 examples 63
SET option format 61
examples 98 options 62
resetting a subset pointer 98 restrictions 63
SETCOND option usage 62
examples 99 System Service
setting a subset pointer conditionally 99 ACCEPT 49
SETS command CHKP 49
description 58 DEQ 50
example 59 LOAD 51
format 58 LOG 52
options 58 QUERY 53
restrictions 59 REFRESH 54
usage 59 ROLB 55
setting a subset pointer ROLL 56
conditionally 99 ROLS 57
to zero 97 SETS 58
SETU command SETU 59
description 59 STAT 60
example 60 SYMCHKP 61
format 59 XRST 63
options 60
restrictions 60
usage 60 T
SETZERO option TERM (Terminate) command
examples 97 description 47
setting a subset pointer to zero 97 examples 48
STAT command format 47
description 60 options 47
examples 61 usage 47
format 61 translating, EXEC DLI program 91
options 61 translator options required for EXEC DLI 91
usage 61 translator version, DIB (DL/I interface block) 69
status code, field in DIB 69 TREATMNT segment 9
status codes
categories 117
checking in a command-level program 69 U
database calls 122 Utility Control Facility (UCF) 147
database calls, table 117
message calls, table 122, 124
processing option P 103
subset pointers 101
V
variable names, mandatory 68
subset pointers
DBD, defining 95
description 93
GETFIRST option 96 X
MOVENEXT option 98 XRST (Extended Restart) command
preparation for using 95 description 63
PSB, defining 95 examples 65
sample application 95 format 63
SET option 98 options 63
SETCOND option 99 restrictions 65
SETZERO option 97 usage 64
status codes 101
symbolic checkpoint
restart 106
XRST 106
Index 159
Readers’ Comments — We’d Like to Hear from You
IMS Version 7
Application Programming: EXEC DLI Commands for CICS and IMS
Publication No. SC26-9424-02
Overall, how satisfied are you with the information in this book?
Very Satisfied Satisfied Neutral Dissatisfied Very Dissatisfied

Overall satisfaction h h h h h
How satisfied are you that the information in this book is:
Very Satisfied Satisfied Neutral Dissatisfied Very Dissatisfied

Accurate h h h h h
Complete h h h h h
Easy to find h h h h h
Easy to understand h h h h h
Well organized h h h h h
Applicable to your tasks h h h h h
Please tell us how we can improve this book:
Thank you for your responses. May we contact you? h Yes h No
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you.
Name Address
Company or Organization
Phone No.
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
SC26-9424-02 Along Line
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation
H150/090
555 Bailey Avenue
San Jose, CA U.S.A.
95141-9989
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC26-9424-02 Along Line

Program Number: 5655-B01
Printed in U.S.A.
SC26-9424-02
Spine information:
Application Programming: EXEC DLI Commands for

IMS Version 7 CICS and IMS

IMS V7 Appl Programming CICS and IMS

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

IMS V7 Appl Programming CICS and IMS

Caricato da

Copyright:

Formati disponibili

IMS Version 7

Application Programming: EXEC DLI

Application Programming: EXEC DLI

Third Edition (March 2003) (Softcopy Only)

Summary of Changes . . . . . . . . . . . . . . . . . . . . . xxi

Part 1. Writing Application Programs. . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Writing EXEC DLI Commands for Your Application Program 11

© Copyright IBM Corp. 2000, 2003 iii

iv Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67

Chapter 4. More about Writing Your Application Program . . . . . . . . 73

Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93

Chapter 6. Recovering Databases and Maintaining Database Integrity 105

vi Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109

Part 2. For Your Reference . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 8. Comparing Command-Level and Call-Level Programs . . . . 113

Chapter 9. DL/I Status Codes . . . . . . . . . . . . . . . . . . 117

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

© Copyright IBM Corp. 2000, 2003 ix

© Copyright IBM Corp. 2000, 2003 xi

This information could include technical inaccuracies or typographical errors.

© Copyright IBM Corp. 2000, 2003 xiii

Such information may be available, subject to appropriate terms and conditions,

Any performance data contained herein was determined in a controlled

This information contains sample application programs in source language, which

Programming Interface Information

General-use programming interfaces allow the customer to write programs that

However, this book also documents Product-sensitive Programming Interface and

Product-sensitive programming interfaces allow the customer installation to perform

Product-sensitive Programming Interface and Associated Guidance Information is

Product-sensitive programming interface

Product-sensitive Programming Interface and Associated Guidance Information.

This book is a follow-on to IMS Version 7 Application Programming: Design Guide

© Copyright IBM Corp. 2000, 2003 xvii

Multiple required or optional items

IMS-specific syntax information

STATEMENT item 1 item 2 A

/VERB LINE line#

where <A> is:

/MSVERIFY MSNAME msname

The MSNAME keyword in the example supports a name value and

How to Send Your Comments

xx Application Programming: EXEC DLI Commands for CICS and IMS

Changes to This Book for IMS Version 7

Library Changes for IMS Version 7

Other changes include changes to these following books:

© Copyright IBM Corp. 2000, 2003 xxi

Chapter 2. Writing EXEC DLI Commands for Your Application Program 11

© Copyright IBM Corp. 2000, 2003 1

2 Application Programming: EXEC DLI Commands for CICS and IMS

Part 1. Writing Application Programs 3

Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67

Chapter 4. More about Writing Your Application Program . . . . . . . . 73

Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93

4 Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 6. Recovering Databases and Maintaining Database Integrity 105

Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109

Part 1. Writing Application Programs 5

IMS DB/DC can provide the same services as DBCTL.

Getting Started with EXEC DLI

Figure 1. The Structure of a Command-Level Batch or BMP Program

© Copyright IBM Corp. 2000, 2003 7