application programming exec dli commands for cics and ims

IMS Version 7

Application Programming: EXEC DLICommands for CICS and IMS

SC26-9424-01

��

NoteBefore using this information and the product it supports, be sure to read the general information under “Notices” onpage xiii.

Second Edition (June 2001) (Softcopy Only)

This edition replaces and makes obsolete the previous edition, SC26-9424-00. This edition is available in softcopyformat only. The technical changes for this version are summarized under “Summary of Changes” on page xxi. Thetechnical changes for this edition are indicated by a vertical bar to the left of a change.

© Copyright International Business Machines Corporation 2000, 2001. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiProgramming Interface Information. . . . . . . . . . . . . . . . . . xvTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xvProduct Names. . . . . . . . . . . . . . . . . . . . . . . . . xvi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiSummary of Contents . . . . . . . . . . . . . . . . . . . . . . xviiPrerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . xviiSyntax Diagrams. . . . . . . . . . . . . . . . . . . . . . . . xviiiHow to Send Your Comments . . . . . . . . . . . . . . . . . . . xx

Summary of Changes . . . . . . . . . . . . . . . . . . . . . xxiChanges to The Current Version of This Book for IMS Version 7 . . . . . . xxiChanges to This Book for IMS Version 7 . . . . . . . . . . . . . . . xxiLibrary Changes for IMS Version 7 . . . . . . . . . . . . . . . . . xxi

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

Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2. Writing EXEC DLI Commands for Your Application Program 11Using the I/O PCB, PSB, and PCB . . . . . . . . . . . . . . . . . 11

I/O PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11Alternate PCB . . . . . . . . . . . . . . . . . . . . . . . . 11DB PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11GSAM PCB . . . . . . . . . . . . . . . . . . . . . . . . . 11Format of a PSB . . . . . . . . . . . . . . . . . . . . . . . 12PCB Summary . . . . . . . . . . . . . . . . . . . . . . . . 12

Specifying an EXEC DLI Command . . . . . . . . . . . . . . . . . 13Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . 13EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . 14DLET Command . . . . . . . . . . . . . . . . . . . . . . . . 15

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 15Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Example . . . . . . . . . . . . . . . . . . . . . . . . . . 16Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 16

GN Command . . . . . . . . . . . . . . . . . . . . . . . . . 17Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 18Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 22

GNP Command . . . . . . . . . . . . . . . . . . . . . . . . 22Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 23Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

© Copyright IBM Corp. 2000, 2001 iii

||

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 27Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 27

GU Command . . . . . . . . . . . . . . . . . . . . . . . . . 28Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 29Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 33

ISRT Command . . . . . . . . . . . . . . . . . . . . . . . . 33Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 34Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 38

POS Command. . . . . . . . . . . . . . . . . . . . . . . . . 39Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 39Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 40

REPL Command . . . . . . . . . . . . . . . . . . . . . . . . 40Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 41Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 43Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 44

RETRIEVE Command . . . . . . . . . . . . . . . . . . . . . . 44Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 45Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 46Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 46

SCHD Command . . . . . . . . . . . . . . . . . . . . . . . . 46Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 46Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47

TERM Command . . . . . . . . . . . . . . . . . . . . . . . . 47Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 47Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Example . . . . . . . . . . . . . . . . . . . . . . . . . . 48

System Service Commands . . . . . . . . . . . . . . . . . . . . 48ACCEPT Command . . . . . . . . . . . . . . . . . . . . . . . 49

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Example . . . . . . . . . . . . . . . . . . . . . . . . . . 49

CHKP Command . . . . . . . . . . . . . . . . . . . . . . . . 49Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 50Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 50

DEQ Command . . . . . . . . . . . . . . . . . . . . . . . . 50Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

iv Application Programming: EXEC DLI Commands for CICS and IMS

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Example . . . . . . . . . . . . . . . . . . . . . . . . . . 51Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 51

LOAD Command . . . . . . . . . . . . . . . . . . . . . . . . 51Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 52Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Example . . . . . . . . . . . . . . . . . . . . . . . . . . 52

LOG Command. . . . . . . . . . . . . . . . . . . . . . . . . 52Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Example . . . . . . . . . . . . . . . . . . . . . . . . . . 53Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 53

QUERY Command . . . . . . . . . . . . . . . . . . . . . . . 53Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 54Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 54

REFRESH Command . . . . . . . . . . . . . . . . . . . . . . 54Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 54Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Example . . . . . . . . . . . . . . . . . . . . . . . . . . 54Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55

ROLB Command . . . . . . . . . . . . . . . . . . . . . . . . 55Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 55Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Example . . . . . . . . . . . . . . . . . . . . . . . . . . 55Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 55

ROLL Command . . . . . . . . . . . . . . . . . . . . . . . . 56Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 56Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Example . . . . . . . . . . . . . . . . . . . . . . . . . . 56Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 56

ROLS Command . . . . . . . . . . . . . . . . . . . . . . . . 57Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 57Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 57Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 58

SETS Command . . . . . . . . . . . . . . . . . . . . . . . . 58Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 58Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Example . . . . . . . . . . . . . . . . . . . . . . . . . . 59Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 59

SETU Command . . . . . . . . . . . . . . . . . . . . . . . . 59Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 60Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Example . . . . . . . . . . . . . . . . . . . . . . . . . . 60Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 60

Contents v

STAT Command . . . . . . . . . . . . . . . . . . . . . . . . 60Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 61Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 61

SYMCHKP Command . . . . . . . . . . . . . . . . . . . . . . 61Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 62Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Example . . . . . . . . . . . . . . . . . . . . . . . . . . 63Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63

XRST Command . . . . . . . . . . . . . . . . . . . . . . . . 63Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 63Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Example . . . . . . . . . . . . . . . . . . . . . . . . . . 65Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 65

Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67Specifying an Application Interface Block (AIB) . . . . . . . . . . . . . 67

AIB Mask . . . . . . . . . . . . . . . . . . . . . . . . . . 67CICS Restrictions with AIB support . . . . . . . . . . . . . . . . 68

Specifying the DL/I Interface Block (DIB) . . . . . . . . . . . . . . . 68Defining a Key Feedback Area . . . . . . . . . . . . . . . . . . . 71Defining I/O Areas. . . . . . . . . . . . . . . . . . . . . . . . 71

COBOL I/O Area . . . . . . . . . . . . . . . . . . . . . . . 72PL/I I/O Area. . . . . . . . . . . . . . . . . . . . . . . . . 72Assembler Language I/O Area . . . . . . . . . . . . . . . . . . 72

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

Coding a Program in Assembler Language . . . . . . . . . . . . . 74Coding a Program in COBOL . . . . . . . . . . . . . . . . . . 78Coding a Program in PL/I . . . . . . . . . . . . . . . . . . . . 81Coding a Program in C . . . . . . . . . . . . . . . . . . . . . 85

Preparing Your EXEC DLI Program for Execution . . . . . . . . . . . . 91Translator Options Required for EXEC DLI . . . . . . . . . . . . . 91Compiler Options Required for EXEC DLI . . . . . . . . . . . . . . 91Linkage Editor Options Required for EXEC DLI . . . . . . . . . . . . 92

Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93Processing DEDBs with Subset Pointers . . . . . . . . . . . . . . . 93

Before You Use Subset Pointers . . . . . . . . . . . . . . . . . 94Designating Subset Pointers You Want to Use . . . . . . . . . . . . 95Using Subset Pointers . . . . . . . . . . . . . . . . . . . . . 95Subset Pointer Status Codes . . . . . . . . . . . . . . . . . . 101

The POS Command . . . . . . . . . . . . . . . . . . . . . . 102Locating a Specific Sequential Dependent . . . . . . . . . . . . . 102Locating the Last Inserted Sequential Dependent Segment . . . . . . . 102Identifying Free Space . . . . . . . . . . . . . . . . . . . . 103The P Processing Option. . . . . . . . . . . . . . . . . . . . 103

Chapter 6. Recovering Databases and Maintaining Database Integrity 105Issuing Checkpoints in a Batch or BMP Program . . . . . . . . . . . . 105

Issuing the CHKP Command . . . . . . . . . . . . . . . . . . 105Issuing the SYMCHKP Command . . . . . . . . . . . . . . . . 106

vi Application Programming: EXEC DLI Commands for CICS and IMS

Restarting Your Program and Checking for Position . . . . . . . . . . . 106Backing Out Database Updates Dynamically: The ROLL and ROLB

Commands . . . . . . . . . . . . . . . . . . . . . . . . . 106Using Intermediate Backout Points: The SETS and ROLS Commands . . . . 106

SETS Command . . . . . . . . . . . . . . . . . . . . . . . 107ROLS Command. . . . . . . . . . . . . . . . . . . . . . . 107

Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109Accepting Database Availability Status Codes . . . . . . . . . . . . . 109Obtaining 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 . . . . . . . . . . . . . . . . . . 117Status Code Tables . . . . . . . . . . . . . . . . . . . . . . . 117

Categories of DL/I Status Codes . . . . . . . . . . . . . . . . . 117Status Code Explanations . . . . . . . . . . . . . . . . . . . . 127

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

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 153IMS 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 . . . . . . . . . . . . . . . 72. Medical Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83. PATIENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84. ILLNESS Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95. TREATMNT Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96. BILLING Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97. PAYMENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108. HOUSHOLD Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109. General Format of a PSB. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

10. Processing a Long Chain of Segment Occurrences with Subset Pointers . . . . . . . . . . 9311. Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . . . 9412. More Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . 9413. How Subset Pointers Divide a Chain into Subsets . . . . . . . . . . . . . . . . . . 9414. Processing Performed for the Sample Passbook Example. . . . . . . . . . . . . . . . 9615. Retrieving the First Segment in a Chain of Segments . . . . . . . . . . . . . . . . . 9716. Moving the Subset Pointer to the Next Segment after Your Current Position . . . . . . . . . 9817. Unconditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . . . . 9918. Conditionally Setting the Subset Pointer to Your Current Position. . . . . . . . . . . . . 100

© Copyright IBM Corp. 2000, 2001 ix

x Application Programming: EXEC DLI Commands for CICS and IMS

Tables

1. Summary of PCB Information . . . . . . . . . . . . . . . . . . . . . . . . . . 122. Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . . . 133. DL/I Calls Available to IMS and CICS Command-Level Application Programs . . . . . . . . 1134. Comparing Call-Level and Command-Level Programs: Commands and Calls . . . . . . . . 1135. Comparing Call-Level and Command-Level Programs: Command Codes and Options . . . . . 1146. Database Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177. Message Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228. System Service Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

© Copyright IBM Corp. 2000, 2001 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. IBMmay not offer the products, services, or features discussed in this document in othercountries. Consult your local IBM representative for information on the products andservices 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, orservice may be used. Any functionally equivalent product, program, or service thatdoes 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-IBMproduct, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give you anylicense to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR APARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not apply toyou.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvements and/orchanges in the product(s) and/or the program(s) described in this publication at anytime without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not part of the materials for thisIBM 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 believesappropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose ofenabling: (i) the exchange of information between independently created programs

© Copyright IBM Corp. 2000, 2001 xiii

and other programs (including this one) and (ii) the mutual use of the informationwhich has been exchanged, should contact:

IBM CorporationJ74/G4555 Bailey AvenueP.O. Box 49023San Jose, CA 95161-9023U.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 materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of thoseproducts, their published announcements or other publicly available sources. IBMhas not tested those products and cannot confirm the accuracy of performance,compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of thoseproducts.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates 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 programsconforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughlytested under all conditions. IBM, therefore, cannot guarantee or imply reliability,serviceability, or function of these programs. You may copy, modify, and distribute

xiv Application Programming: EXEC DLI Commands for CICS and IMS

these sample programs in any form without payment to IBM for the purposes ofdeveloping, using, marketing, or distributing application programs conforming toIBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude 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 rightsreserved.

If you are viewing this information softcopy, the photographs and color illustrationsmay not appear.

Programming Interface InformationThis book is intended to help the application programmer write IMS applicationprograms. This book primarily documents General-use Programming Interface andAssociated Guidance Information provided by IMS.

General-use programming interfaces allow the customer to write programs thatobtain the services of IMS.

However, this book also documents Product-sensitive Programming Interface andAssociated Guidance Information provided by IMS.

Product-sensitive programming interfaces allow the customer installation to performtasks such as diagnosing, modifying, monitoring, repairing, tailoring, or tuning ofIMS. Use of such interfaces creates dependencies on the detailed design orimplementation of the IBM software product. Product-sensitive programminginterfaces should be used only for these specialized purposes. Because of theirdependencies on detailed design and implementation, it is to be expected thatprograms written to such interfaces may need to be changed to run with newproduct releases or versions, or as a result of service.

Product-sensitive Programming Interface and Associated Guidance Information isidentified where it occurs, either by an introductory statement to a chapter orsection or by the following marking:

Product-sensitive programming interface

Product-sensitive Programming Interface and Associated Guidance Information.

End of Product-sensitive programming interface

TrademarksThe following terms are trademarks of the IBM Corporation in the United States orother countries or both:

C/370 IBMCICS IMSCICS/ESA IMS/ESACICS/MVS MVSDATABASE 2 MVS/ESADB2 RACF

Notices xv

BookManager

Other company, product, and service names, which may be denoted by a doubleasterisk (**), may be trademarks or service marks of others.

Product NamesIn 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 DLIcommands in an IMS environment. This book lists and describes the EXEC DLIcommands, and explains the procedures for writing application programs. Forinformation on using databases (such as, position in the database, using multiplepositioning, and using secondary indexing and logical relationships), see IMSVersion 7 Application Programming: Database Manager.

This edition is available only in PDF and BookManager formats. This book isavailable on the IMS Version 7 Licensed Product Kit (LK3T-2326). You can also getthe most current versions of the PDF and BookManager formats by going to theIMS Web site at www.ibm.com/ims and linking to the Library page.

Summary of ContentsThis book has two parts:

Part 1 (“Chapter 1. How Your EXEC DLI Application Program Works with IMS” onpage 7through “Chapter 7. Using Data Availability Enhancements” on page 109)explains the basics of writing the DL/I part of your application program with EXECDLI commands.

“Part 2. For Your Reference” on page 111 contains reference information about theparts of an IMS command-level application program such as EXEC DLI commands,system service calls, qualification statements, EXEC DLI options, the DIB (DL/IInterface Block), I/O areas, and status codes. These chapters are for experiencedprogrammers who understand IMS application programming and need only to lookup a fact such as the meaning of a particular status code. If you are one of thoseprogrammers, you may also want to have on hand IMS/ESA ApplicationProgramming: EXEC DLI Commands for CICS and IMS Summary.

“Bibliography” on page 153 lists all the non-IMS publications referred to in this book.

Prerequisite KnowledgeIBM offers a wide variety of classroom and self-study courses to help you learnIMS. For a complete list, see the IMS home page on the World Wide Web at:www.ibm.com/ims

This book assumes you are a CICS programmer familiar with the functions,facilities, hardware, and software described in CICS/ESA CICS Family GeneralInformation and from the Library page of the IMS home page on the Web:www.ibm.com/ims.

This book also assumes that, if you plan to write a CICS program, you are familiarwith the principles covered in CICS/ESA Application Programming Guide and inother CICS documentation.

Before using this book, you should understand the concepts of application designpresented in IMS Version 7 Application Programming: Design Guide.

This book is a follow-on to IMS Version 7 Application Programming: Design Guideand also refers to IMS Version 7 Application Programming: Database Manager for

© Copyright IBM Corp. 2000, 2001 xvii

||||

|||

||||

database information common to both EXEC DLI and DL/I application programs.For definitions of IMS terms used in this book and references to related informationin other publications, see IMS Version 7 Master Index and Glossary.

Syntax DiagramsThe following rules apply to the syntax diagrams used in this book:

Arrow symbolsRead the syntax diagrams from left to right, from top to bottom, followingthe 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 inuppercase for MVS and OS/2 operating systems, and lowercase forUNIX operating systems. These items must be entered exactly as shown.

v Variables appear in lowercase italics (for example, column-name). Theyrepresent user-defined parameters or suboptions.

v When entering commands, separate parameters and keywords by atleast 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 itemsRequired items appear on the horizontal line (the main path).

�� REQUIRED_ITEM ��

Optional ItemsOptional items appear below the main path.

�� REQUIRED_ITEMoptional_item

��

If an optional item appears above the main path, that item has no effect onthe execution of the statement and is used only for readability.

��optional_item

REQUIRED_ITEM ��

xviii Application Programming: EXEC DLI Commands for CICS and IMS

Multiple required or optional itemsIf 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 themain path.

�� REQUIRED_ITEM required_choice1required_choice2

��

If choosing one of the items is optional, the entire stack appears below themain path.

�� REQUIRED_ITEMoptional_choice1optional_choice2

��

Repeatable itemsAn arrow returning to the left above the main line indicates that an item canbe repeated.

�� REQUIRED_ITEM repeatable_item ��

If the repeat arrow contains a comma, you must separate repeated itemswith a comma.

�� REQUIRED_ITEM

,

repeatable_item ��

A repeat arrow above a stack indicates that you can specify more than oneof the choices in the stack.

Default keywordsIBM-supplied default keywords appear above the main path, and theremaining choices are shown below the main path. In the parameter listfollowing the syntax diagram, the default choices are underlined.

�� REQUIRED_ITEMdefault_choice

optional_choiceoptional_choice

��

IMS-specific syntax information

FragmentsSometimes a diagram must be split into fragments. The fragmentsare represented by a letter or fragment name, set off like this: | A |.The fragment follows the end of the main diagram. The followingexample shows the use of a fragment.

Preface xix

�� STATEMENT item 1 item 2 A ��

A:

item 3item 4

KEYWORDitem 5

item 6

Substitution-blockSometimes a set of several parameters is represented by asubstitution-block such as <A>. For example, in the imaginary/VERB command you could enter /VERB LINE 1, /VERB EITHERLINE 1, or /VERB OR LINE 1.

�� /VERB<A>

LINE line# ��

where <A> is:

�� EITHEROR

��

Parameter endingsParameters with number values end with the symbol '#', parametersthat are names end with 'name', and parameters that can begeneric end with '*'.

�� /MSVERIFY MSNAME msnameSYSID sysid#

��

The MSNAME keyword in the example supports a name value andthe SYSID keyword supports a number value.

How to Send Your CommentsYour feedback is important in helping us provide the most accurate information andhighest quality information. If you have any comments about this book or any otherIMS documentation, you can do one of the following:

v Go to the IMS home page at: http://www.ibm.com/ims. There you will find anonline feedback page where you can enter and submit comments.

v Send your comments by e-mail to [email protected]. Be sure to include thename of the book the part number of the book the version of IMS, and, ifapplicable, 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, orby giving it to an IBM representative.

xx Application Programming: EXEC DLI Commands for CICS and IMS

||

Summary of Changes

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

Changes to This Book for IMS Version 7This edition, which is available in softcopy format only, includes technical andeditorial changes. This book contains new technical information for Version 7, aswell as editorial changes.

Library Changes for IMS Version 7The major change to the IMS Version 7 library is that it is available not only inhardcopy and in softcopy on BookManager, but also in softcopy Portable DocumentFormat (PDF). The complete library is available in BookManager and PDF on theIMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7softcopy 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 andPDF 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 Guideand Reference

The book formerly titled IMS/ESA Common Queue Server Guide and Referencein the Version 6 library is called IMS Version 7 Common Queue Server and BasePrimitive Environment Guide and Reference.

The IMS Version 7 Common Queue Server and Base Primitive EnvironmentGuide 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 EnvironmentGuide 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 iscalled 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 andIMS/ESA Utilities Reference: Transaction Manager in the Version 6 library havebeen combined into one book called IMS Version 7 Utilities Reference: Databaseand Transaction Manager.

v IMS Version 7 Application Programming: Database Manager and IMS Version 7Customization Guide

The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved fromthe IMS Version 7 Application Programming: Database Manager to the IMSVersion 7 Customization Guide.

v IMS Version 7 Sample Operating Procedures

For IMS Version 7, this book is available only in BookManager and PDF softcopyon 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, 2001 xxi

|

||

||||||||

The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). Asa new book, the IJUG is available only in PDF 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 . . . 7Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2. Writing EXEC DLI Commands for Your Application Program 11Using the I/O PCB, PSB, and PCB . . . . . . . . . . . . . . . . . 11

I/O PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11Alternate PCB . . . . . . . . . . . . . . . . . . . . . . . . 11DB PCB . . . . . . . . . . . . . . . . . . . . . . . . . . 11GSAM PCB . . . . . . . . . . . . . . . . . . . . . . . . . 11Format of a PSB . . . . . . . . . . . . . . . . . . . . . . . 12PCB Summary . . . . . . . . . . . . . . . . . . . . . . . . 12

DB Batch Programs . . . . . . . . . . . . . . . . . . . . . 12BMPs, MPPs, and IFPs. . . . . . . . . . . . . . . . . . . . 12CICS Programs with DBCTL . . . . . . . . . . . . . . . . . . 12

Specifying an EXEC DLI Command . . . . . . . . . . . . . . . . . 13Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . 13EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . . . 14DLET Command . . . . . . . . . . . . . . . . . . . . . . . . 15


Explanation . . . . . . . . . . . . . . . . . . . . . . . . 16Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 16

GN Command . . . . . . . . . . . . . . . . . . . . . . . . . 17Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 18Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 21Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 21Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 21

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 22GNP Command . . . . . . . . . . . . . . . . . . . . . . . . 22

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 23Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 27Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 27

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 27GU Command . . . . . . . . . . . . . . . . . . . . . . . . . 28



Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 33ISRT Command . . . . . . . . . . . . . . . . . . . . . . . . 33

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

© Copyright IBM Corp. 2000, 2001 1

Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 34Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 38


Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 38POS Command. . . . . . . . . . . . . . . . . . . . . . . . . 39

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 39Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 40

REPL Command . . . . . . . . . . . . . . . . . . . . . . . . 40Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 41Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 43Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 43Example 3 . . . . . . . . . . . . . . . . . . . . . . . . 44Example 4 . . . . . . . . . . . . . . . . . . . . . . . . 44

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 44RETRIEVE Command . . . . . . . . . . . . . . . . . . . . . . 44



SCHD Command . . . . . . . . . . . . . . . . . . . . . . . . 46Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 46Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Explanation . . . . . . . . . . . . . . . . . . . . . . . . 47TERM Command . . . . . . . . . . . . . . . . . . . . . . . . 47


Explanation . . . . . . . . . . . . . . . . . . . . . . . . 48System Service Commands . . . . . . . . . . . . . . . . . . . . 48ACCEPT Command . . . . . . . . . . . . . . . . . . . . . . . 49


CHKP Command . . . . . . . . . . . . . . . . . . . . . . . . 49Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 49Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 50


DEQ Command . . . . . . . . . . . . . . . . . . . . . . . . 50Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

2 Application Programming: EXEC DLI Commands for CICS and IMS

Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Example . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Explanation . . . . . . . . . . . . . . . . . . . . . . . . 51Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 51

LOAD Command . . . . . . . . . . . . . . . . . . . . . . . . 51Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 52Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Example . . . . . . . . . . . . . . . . . . . . . . . . . . 52

LOG Command. . . . . . . . . . . . . . . . . . . . . . . . . 52Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Example . . . . . . . . . . . . . . . . . . . . . . . . . . 53Restriction . . . . . . . . . . . . . . . . . . . . . . . . . 53

QUERY Command . . . . . . . . . . . . . . . . . . . . . . . 53Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 53Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 54Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 54

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 54REFRESH Command . . . . . . . . . . . . . . . . . . . . . . 54



ROLB Command . . . . . . . . . . . . . . . . . . . . . . . . 55Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 55Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Example . . . . . . . . . . . . . . . . . . . . . . . . . . 55


ROLL Command . . . . . . . . . . . . . . . . . . . . . . . . 56Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 56Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Example . . . . . . . . . . . . . . . . . . . . . . . . . . 56


ROLS Command . . . . . . . . . . . . . . . . . . . . . . . . 57Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 57Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 57


Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 58SETS Command . . . . . . . . . . . . . . . . . . . . . . . . 58

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Part 1. Writing Application Programs 3

Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 58Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Example . . . . . . . . . . . . . . . . . . . . . . . . . . 59


SETU Command . . . . . . . . . . . . . . . . . . . . . . . . 59Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 60Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Example . . . . . . . . . . . . . . . . . . . . . . . . . . 60


STAT Command . . . . . . . . . . . . . . . . . . . . . . . . 60Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 61Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 61

SYMCHKP Command . . . . . . . . . . . . . . . . . . . . . . 61Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 62Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Example . . . . . . . . . . . . . . . . . . . . . . . . . . 63


XRST Command . . . . . . . . . . . . . . . . . . . . . . . . 63Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 63Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Example . . . . . . . . . . . . . . . . . . . . . . . . . . 65


Chapter 3. Defining Application Program Elements to IMS . . . . . . . 67Specifying an Application Interface Block (AIB) . . . . . . . . . . . . . 67

AIB Mask . . . . . . . . . . . . . . . . . . . . . . . . . . 67CICS Restrictions with AIB support . . . . . . . . . . . . . . . . 68

Specifying the DL/I Interface Block (DIB) . . . . . . . . . . . . . . . 68Defining a Key Feedback Area . . . . . . . . . . . . . . . . . . . 71Defining I/O Areas. . . . . . . . . . . . . . . . . . . . . . . . 71

COBOL I/O Area . . . . . . . . . . . . . . . . . . . . . . . 72PL/I I/O Area. . . . . . . . . . . . . . . . . . . . . . . . . 72Assembler Language I/O Area . . . . . . . . . . . . . . . . . . 72

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

Coding a Program in Assembler Language . . . . . . . . . . . . . 74Coding a Program in COBOL . . . . . . . . . . . . . . . . . . 78Coding a Program in PL/I . . . . . . . . . . . . . . . . . . . . 81Coding a Program in C . . . . . . . . . . . . . . . . . . . . . 85

Preparing Your EXEC DLI Program for Execution . . . . . . . . . . . . 91Translator Options Required for EXEC DLI . . . . . . . . . . . . . 91Compiler Options Required for EXEC DLI . . . . . . . . . . . . . . 91Linkage Editor Options Required for EXEC DLI . . . . . . . . . . . . 92

Chapter 5. Processing Fast Path Databases . . . . . . . . . . . . . 93Processing DEDBs with Subset Pointers . . . . . . . . . . . . . . . 93


Before You Use Subset Pointers . . . . . . . . . . . . . . . . . 94Designating Subset Pointers You Want to Use . . . . . . . . . . . . 95Using Subset Pointers . . . . . . . . . . . . . . . . . . . . . 95

Our Sample Application. . . . . . . . . . . . . . . . . . . . 95Retrieving the First Segment in the Subset with the GETFIRST Option 96Setting the Subset Pointers with the SETZERO, MOVENEXT, SET, and

SETCOND Options . . . . . . . . . . . . . . . . . . . . 97Inserting Segments in a Subset . . . . . . . . . . . . . . . . 101Deleting the Segment Pointed to By a Subset Pointer . . . . . . . . 101Combining Options . . . . . . . . . . . . . . . . . . . . . 101

Subset Pointer Status Codes . . . . . . . . . . . . . . . . . . 101The POS Command . . . . . . . . . . . . . . . . . . . . . . 102

Locating a Specific Sequential Dependent . . . . . . . . . . . . . 102Locating the Last Inserted Sequential Dependent Segment . . . . . . . 102Identifying Free Space . . . . . . . . . . . . . . . . . . . . 103The P Processing Option. . . . . . . . . . . . . . . . . . . . 103

Chapter 6. Recovering Databases and Maintaining Database Integrity 105Issuing Checkpoints in a Batch or BMP Program . . . . . . . . . . . . 105

Issuing the CHKP Command . . . . . . . . . . . . . . . . . . 105Issuing the SYMCHKP Command . . . . . . . . . . . . . . . . 106

Restarting Your Program and Checking for Position . . . . . . . . . . . 106Backing Out Database Updates Dynamically: The ROLL and ROLB

Commands . . . . . . . . . . . . . . . . . . . . . . . . . 106Using Intermediate Backout Points: The SETS and ROLS Commands . . . . 106

SETS Command . . . . . . . . . . . . . . . . . . . . . . . 107ROLS Command. . . . . . . . . . . . . . . . . . . . . . . 107

Chapter 7. Using Data Availability Enhancements . . . . . . . . . . 109Accepting Database Availability Status Codes . . . . . . . . . . . . . 109Obtaining Information about Database Availability. . . . . . . . . . . . 109

Part 1. Writing Application Programs 5

Chapter 1. How Your EXEC DLI Application Program Workswith IMS

This chapter describes the components of your CICS program. It also describes thesample hierarchy used in this book’s examples.

Your EXEC DLI application uses EXEC DLI commands to read and update DL/Idatabases. These applications can execute as pure batch, as a BMP running withDBCTL or DB/DC, or as an online CICS program using DBCTL. Your EXEC DLIprogram can also issue system service commands when using DBCTL.

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

Getting Started with EXEC DLIFigure 1 shows the main elements of programs that use EXEC DLI commands toaccess DL/I databases. The main differences between a CICS program and acommand-level batch or BMP program (represented by Figure 1) are that you donot schedule a PSB for a batch program, and that you do not issue checkpoints fora CICS program. The numbers on the left of the figure correspond to the notes thatfollow.

Notes to Figure 1:

�1�I/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.

�2�Key feedback area. DL/I passes, on request, the concatenated key of thelowest-level segment retrieved to the key feedback area.

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


�3�DL/I Interface Block (DIB). DL/I and CICS place the results of eachcommand in the DIB. The DIB contains most of the same information returned inthe DB PCB for programs using the call-level interface.

�4�Program entry. Control is passed to your program during program entry.

�5�Issue EXEC DLI commands. Commands read and update information in thedatabase.

�6�Check 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 DLIcommand for database processing and after issuing a checkpoint command.

�7�Issue checkpoint. Issue checkpoints as needed to establish places fromwhich to restart. Issuing a checkpoint commits database changes and releasesresources.

�8�Terminate. This returns control to the operating system, commits databasechanges, and releases resources.

Requirement: CICS/ESA Version 4, or later, and CICS Transaction Server run withthis version of IMS. Unless a distinction needs to made, all supported versions arereferred to as CICS.

A Sample HierarchyMany of the examples in this book use the medical hierarchy shown in the followinggraphic. The database contains information that a medical clinic might keep aboutits patients. To understand the examples, you should be familiar with the hierarchyand the segments it contains.

The figures that follow show the layouts of the segments in the hierarchy. Thenumber 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: patientnumber (PATNO), patient name (NAME), and the patient’s address (ADDR).PATIENT has a unique key field: PATNO. PATIENT segments are stored inascending order of their patient numbers. The lowest patient number in thedatabase is 00001 and the highest is 10500.

v ILLNESS Segment

Figure 2. Medical Hierarchy

Figure 3. PATIENT Segment

Getting Started with EXEC DLI


The following graphic shows the ILLNESS segment. It has two fields: the datewhen the patient came to the clinic with the illness (ILLDATE) and the name ofthe illness (ILLNAME). The key field is ILLDATE. Because it is possible for apatient to come to the clinic with more than one illness on the same date, thiskey field is nonunique, that is, there may be more than one ILLNESS segmentwith 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 nokeys will be placed. The DBA can use the RULES keyword of the SEGMstatement of the DBD to specify this.

For segments with equal keys or no keys, RULES determines where thesegment is inserted. Where RULES=LAST, ILLNESS segments that have equalkeys 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 datefield, regardless of RULES. ILLDATE is specified in the format YYYYMMDD.

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 mayreceive more than one treatment on the same date, DATE is a nonunique keyfield. TREATMNT, like ILLNESS, has been specified as having RULES=LAST.TREATMNT segments are also stored on a first-in-first-out basis. DATE isspecified in the same format as ILLDATE—YYYYMMDD.

v BILLING Segment

The following graphic shows the BILLING segment. It has only one field—theamount of the current bill. BILLING has no key field.

v PAYMENT Segment

Figure 4. ILLNESS Segment

Figure 5. TREATMNT Segment

Figure 6. BILLING Segment

A Sample Hierarchy

Chapter 1. How Your EXEC DLI Application Program Works with IMS 9

The following graphic shows the PAYMENT segment. It also has only onefield—the amount of each payment remitted. The PAYMENT segment has no keyfield.

v HOUSHOLD Segment

The following graphic shows the HOUSHOLD segment. It contains the names ofthe members of the patient’s household, and how each is related to the patient.RELNAME is the key field.

Figure 7. PAYMENT Segment

Figure 8. HOUSHOLD Segment

A Sample Hierarchy


Chapter 2. Writing EXEC DLI Commands for Your ApplicationProgram

This chapter explains the I/O PCB, PSB, and PCB. It also lists and describes theEXEC DLI commands. For each command, a syntax diagram is provided, alongwith information on options, restrictions, usage, and examples illustrating thatusage.

Using the I/O PCB, PSB, and PCBA 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 PCBIn 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 theapplication program is using an I/O PCB, this has to be indicated in the PSBscheduling request.

Alternate PCBAn alternate PCB defines a logical terminal and can be used instead of the I/O PCBwhen it is necessary to direct a response to a terminal. Alternate PCBs appear inPSBs used in a CICS-DBCTL environment, but are used only in an IMS DCenvironment. CICS applications using DBCTL cannot successfully issue commandsthat specify an alternate PCB, an MSDB PCB, or a GSAM PCB. However, a PSBthat contains PCBs of these types can be scheduled successfully in a CICS-DBCTLenvironment.

Alternate PCBs are included in the PCB address list returned to a call levelapplication program. In an EXEC DLI application program, the existence of alternatePCBs in the PSB affects the PCB number used in the PCB keyword.

DB PCBA database PCB (DB PCB) is the PCB that defines an application program’sinterface to a database. One DB PCB is needed for each database view used bythe application program. It can be a full-function PCB, a DEDB PCB, or an MSDBPCB.

GSAM PCBA 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 firstPCB in the parameter list passed to it after scheduling. However, when yourapplication program can handle an I/O PCB, you indicate this using the SYSSERVEkeyword on the SCHD command. The I/O PCB is then the first PCB in the parameteraddress list passed back to your application program.


Format of a PSBThe format of a PSB is shown in Figure 9.

Each PSB must contain at least one PCB. The I/O PCB must be addressable inorder to issue a system service command. An alternate PCB is used only for IMSonline programs, which can run only with the Transaction Manager. Alternate PCBscan be present even though your program does not run under the TransactionManager. A DB PCB can be a full-function PCB, a DEDB PCB, or an MSDB PCB.

PCB SummaryThe following section summarizes the information concerning I/O PCBs andalternate PCBs in various types of application programs.

Recommendation: You should read the following section if you intend to issuesystem service requests.

DB Batch ProgramsAlternate PCBs are always included in the list of PCBs supplied to the program byDL/I irrespective of whether you have specified CMPAT=Y. The I/O PCB is returneddepending on the CMPAT option.

If you specify CMPAT=Y, the PCB list contains the address of the I/O PCB, followedby the addresses of any alternate PCBs, followed by the addresses of any DBPCBs.

If you do not specify CMPAT=Y, the PCB list contains the addresses of anyalternate PCBs followed by the addresses of the DB PCBs.

BMPs, MPPs, and IFPsI/O PCBs and alternate PCBs are always passed to BMP programs. I/O PCBs andalternate PCBs are also always passed to MPPs and to MDPs (message-drivenprograms), which are described in IMS Version 7 Application Programming: DesignGuide.

The PCB list contains the address of the I/O PCB, followed by the addresses of anyalternate PCBs, followed by the addresses of the DB PCBs.

CICS Programs with DBCTLThe first PCB always refers to the first DB PCB whether you specify theSYSSERVE keyword.

Table 1 summarizes the I/O PCB and alternate PCB information.

Table 1. Summary of PCB Information

Environment

EXEC DLI

I/O PCB count included inPCB(n)

Alternate PCB countincluded in PCB(n)

CICS DBCTL1 No No

[IOPCB][Alternate PCB ... Alternate PCB][DBPCB ... DBPCB][GSAMPCB ... GSAMPCB]

Figure 9. General Format of a PSB

I/O PCB, PSB, and PCB


Table 1. Summary of PCB Information (continued)

Environment

EXEC DLI

I/O PCB count included inPCB(n)

Alternate PCB countincluded in PCB(n)

CICS DBCTL2 No No

BMP Yes Yes

Batch3 No Yes

Batch4 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 fora 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 CommandThe following descriptions illustrates the general syntax of the EXEC DLIcommands and the information supplied by each parameter and variable. Table 2provides a summary of the commands available to batch, BMP, and onlineprograms.

The examples in this chapter use the PL/I delimiter.

Code the commands in free form: Where keywords, operands, and parameters areshown separated by commas, no blanks can appear immediately before or after thecomma. Where keywords, operands, and parameters are shown separated byblanks, you can include as many blanks as you wish.

The format of the commands is the same for users of COBOL, PL/I, assemblerlanguage, C/370 and C++/370.

Summary of EXEC DLI CommandsA summary of all the EXEC DLI commands is provided in Table 2.

Table 2. Summary of EXEC DLI Commands

Request Type

Program Characteristics

BatchBatch-

Oriented BMPCICS withDBCTL1

ACCEPT command4 Yes Yes Yes

CHKP command4 Yes Yes No

DEQ command4 Yes Yes Yes

DLET command Yes Yes Yes

Get commands (GU, GHU, GN, GHN, GNP, GHNP)4 Yes Yes Yes

GMSG command5 No Yes Yes

ICMD command5 No Yes Yes

ISRT command4 Yes Yes Yes

I/O PCB, PSB, and PCB

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

Table 2. Summary of EXEC DLI Commands (continued)

Request Type


BatchBatch-


LOAD command Yes No No

LOG command4 Yes Yes Yes

POS command4 No Yes Yes

QUERY command4 Yes Yes Yes

RCMD command5 No Yes Yes

REFRESH command4 Yes Yes Yes

REPL command4 Yes Yes Yes

RETRIEVE command Yes Yes No

ROLB command Yes Yes No

ROLL command Yes Yes No

ROLS command2,4 Yes Yes Yes

SCHD command No No Yes

SETS command2,4 Yes Yes Yes

SETU command Yes Yes No

STAT command3,4 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 shippinga 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 CommandsThe following commands are the only ones allowed for EXEC DLI. They can beused to read and update DL/I databases with a batch program, a BMP (runningDBCTL 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 28

v “ISRT Command” on page 33

v “POS Command” on page 39

v “REPL Command” on page 40

v “RETRIEVE Command” on page 44

Summary of EXEC DLI Commands


v “SCHD Command” on page 46

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” onpage 8.

DLET CommandThe Delete (DLET) command is used to remove a segment and its dependents fromthe database.

Format

OptionsUSING PCB(expression)

Specifies the DB PCB you want to use for the command. Its argument can beany expression that converts to the integer data type; you can specify either anumber or a reference to a halfword in your program containing a number.

VARIABLEIndicates that a segment is variable-length.

SEGMENT(name)Qualifies the command, specifying the name of the segment type you want toretrieve, insert, delete, or replace.

�� EXEC DLI DLETUSING PCB(expression) VARIABLE

�

� SEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

FROM(area) �

�SETZERO(data_value)

��

EXEC DLI Commands


SEGMENT((area))Is a reference to an area in your program containing the name of the segmenttype. You can specify an area instead of specifying the name of the segment inthe command.

SEGLENGTH(expression)Specifies the length of the I/O area into which the segment is retrieved. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (It is required in COBOL programs for any SEGMENT level thatspecifies the INTO or FROM option.)

Requirement: The value specified for SEGLENGTH must be greater than orequal 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.

UsageYou use the DLET command to delete a segment and its dependents from thedatabase. You must first retrieve segments you want to delete, just as if you werereplacing segments, The DLET command deletes the retrieved segment and itsdependents, 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.”

ExplanationYou want to delete all the information about Evelyn Parker from the database. To dothis, you must delete the PATIENT segment. When you do this, DL/I deletes all thedependents of that segment. This is exactly what you want DL/I to do—there is noreason to keep such segments as ILLNESS and TREATMNT for Evelyn Parker ifshe 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 theFROM option to give the name of the I/O area that contains the segment you wantdeleted:EXEC DLI DLET SEGMENT(PATIENT) FROM(PATAREA);

When you issue this command, the PATIENT segment, and its dependents—theILLNESS, TREATMNT, BILLING, PAYMENT, and HOUSHOLD segments—aredeleted.

RestrictionsYou cannot issue any commands using the same PCB between the retrievalcommand and the DLET command, and you can issue only one DLET command foreach GET command.

DLET Command


GN Command

The GN command is used to retrieve segments sequentially.

Format

�� EXEC DLI GET NEXTGN USING PCB(expression)

�

�KEYFEEDBACK(area)

FEEDBACKLEN(expression)

(1)INTO(area) �

�<A> 

��

<A> For each parent segment (optional):

VARIABLE FIRSTLASTCURRENT

SEGMENT(name)SEGMENT((area))

SEGLENGTH(expression)�

�OFFSET(expression) (2)

INTO(area)LOCKEDLOCKCLASS(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):

VARIABLE FIRSTLAST



GN Command

�OFFSET(expression) INTO(area) LOCKED

LOCKCLASS(class)

�


�

�SETCOND(data_value) SETZERO(data_value)

�



�

�KEYS(area)


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, usingFIELDLENGTH. For example: FIELDLENGTH(24,8)

4 You can use either the KEYS option or the WHERE option, but not both onone segment level.



KEYFEEDBACK(area)Specifies an area into which the concatenated key for the segment is placed. Ifthe area is not long enough, the key is truncated.

FEEDBACKLEN(expression)Specifies the length of the key feedback area into which you want theconcatenated key retrieved. Its argument can be any expression that convertsto the integer data type; you can specify either a number or a reference to ahalfword in your program containing a number. (It is required in COBOLprograms and optional in PL/I and assembler language programs.)

INTO(area)Specifies an area into which the segment is read.


GN Command


FIRSTSpecifies that you want to retrieve the first segment occurrence of a segmenttype, or that you want to insert a segment as the first occurrence.

LASTSpecifies that you want to retrieve the last segment occurrence of a segmenttype, or that you want to insert a segment as the last segment occurrence.

CURRENTQualifies the command, and specifies that you want to use your current positionat 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 ofyour program containing the name of the segment type that you want toretrieve.

You can have as many levels of qualification for a GN command as there arelevels in the database’s hierarchy. Using fully qualified commands with theWHERE or KEYS option clearly identifies the hierarchic path and the segmentyou want, and is useful in documenting the command. However, you do notneed to qualify a GN command, because you can specify a GN command withoutthe SEGMENT option.

Once you have established position in the database record, issuing a GNcommand without a SEGMENT option retrieves the next segment occurrence insequential order.

If you specify a SEGMENT option without a KEYS or WHERE option, IMS DBretrieves the first occurrence of that segment type it encounters by searchingforward from current position. With an unqualified GN command, the segmenttype you retrieve might not be the one you expected, so you should specify anI/O area large enough to contain the largest segment your program has accessto. (After successfully issuing a retrieval command, you can find out from theDIB the segment type retrieved.)

If you fully qualify your command with a WHERE or KEYS option, you wouldretrieve the next segment in sequential order, as described by the options.

Including the WHERE or KEYS options for parent segments defines thesegment occurrences that are to be part of the path to the segment you wantretrieved. Omitting the SEGMENT option for a level, or including only theSEGMENT option without a WHERE option, indicates that any path to theoption satisfies the command. DL/I uses only the qualified parent segments andthe lowest-level SEGMENT option to satisfy the command. DL/I does notassume a qualification for the missing level.

SEGLENGTH(expression)Specifies the length of the I/O area into which the segment is retrieved. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (It is required in COBOL programs for any SEGMENT level thatspecifies the INTO or FROM option.)


OFFSET(expression)Specifies the offset to the destination parent. It can be any expression thatconverts to the integer data type; you can specify either a number or areference to a halfword in your program containing a number. Use OFFSET

GN Command


when you process concatenated segments in logical relationships. OFFSET isrequired whenever the destination parent is a variable-length segment.

LOCKEDSpecifies that you want to retrieve a segment for the exclusive use of yourprogram, until a checkpoint or sync point is reached. This option performs thesame function as the Q command code, and it applies to both Fast Path andfull function. A 1-byte alphabetic character of ’A’ is automatically appended asthe class for the Q command code.

LOCKCLASS(class)Specifies that you want to retrieve a segment for the exclusive use of yourprogram until a DEQ command is issued or until a checkpoint or sync point isreached. (DEQ commands are not supported for Fast Path.) Class is a 1-bytealphabetic 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 isLOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, thenEXECDLI sets a status code of GL and initiates an ABENDU1041.

Fast Path does not support LOCKCLASS but, for consistency between full functionand Fast Path, you must specify LOCKCLASS('x')), where x is a letter in therange B to J. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by aletter in the range B to J, then EXECDLI sets a status code of GL and initiatesan ABENDU1041.

MOVENEXT(data_value)Specifies a subset pointer to be moved to the next segment occurrence afteryour current segment.

GETFIRST(data_value)Specifies that you want the search to start with the first segment occurrence ina 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.


SETPARENTSets parentage at the level you want.

FIELDLENGTH(expression)Specifies the length of the field value in a WHERE option.

KEYLENGTH(expression)Specifies the length of the concatenated key when you use the KEYS option. Itcan be any expression in the host language that converts to the integer datatype; if it is a variable, it must be declared as a binary halfword value. For IBMCOBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language,KEYLENGTH is optional. For COBOL programs that are not compiled with theIBM COBOL for MVS & VM (or the VS COBOL II) compiler, you must specifyKEYLENGTH with the KEYS option.

KEYS(area)Qualifies the command with the segment’s concatenated key. You can useeither KEYS or WHERE for a segment level, but not both.

GN Command


“Area” specifies an area in your program containing the segment’sconcatenated key.

WHERE(qualification statement)Qualifies the command, specifying the segment occurrence. Its argument is oneor more qualification statements, each of which compares the value of a field ina 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 valuescompared

v The name of a data area in your program containing the value that iscompared against the value of the field

UsageUse the GN command to sequentially retrieve segments from the database. Eachtime you issue a GN command, IMS DB retrieves the next segment, as described bythe options you include in the command. Before issuing a GN command, you shouldestablish 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 shouldqualify your GN commands as much as possible with the KEYS or WHERE optionsafter 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 commandqualified with the segment name PATIENT until DL/I returned a GB status code tothe program. (GB means that DL/I reached the end of the database before beingable 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 forwardto the next database record.

Example 2“What are the names of the patients we have seen since the beginning of thismonth?”

Explanation: A GN command that includes one or more WHERE or KEYS optionsretrieves the next occurrence of the specified segment type that satisfies thecommand. To answer this request, the program issues the GN command below untilDL/I returned a GB status code. The example shows the command you use at theend of April, 1988 (assuming ILLDATE1 contains 198804010):EXEC DLI GN

SEGMENT(PATIENT) INTO(PATAREA)SEGMENT(ILLNESS) INTO(ILLAREA) WHERE(ILLDATE>=ILLDATE1);

Example 3EXEC DLI GN INTO(PATAREA);

GN Command


Explanation: If you just retrieved the PATIENT segment for patient 04124 andthen issued the above command, you retrieve the first ILLNESS segment for patient04124.

RestrictionsWith an unqualified GN command, the retrieved segment type might not be the oneexpected. Therefore, specify an I/O area large enough to contain the largestsegment accessible to your program.

Use either the KEYS option or the WHERE option, but not both on one segmentlevel.

GNP CommandThe Get Next in Parent (GNP) command is used to retrieve dependent segmentssequentially.

Format

�� EXEC DLI GET NEXT IN PARENTGNP USING PCB(expression)

�



(1)INTO(area) �

�<A> 

��







�


�


�

GN Command

�

�KEYS(area)


 For the object segment (optional):

VARIABLE FIRSTLAST




LOCKCLASS(class)

�


�


�



�

�KEYS(area)


Notes:

1 If you leave out the SEGMENT option, specify the INTO option as shown.




OptionsYou can qualify your GNP command by using SEGMENT and WHERE options.

GNP Command

If you do not qualify your command, IMS DB retrieves the next sequential segmentunder the established parent. If you include a SEGMENT option, IMS DB retrievesthe first occurrence of that segment type that it finds by searching forward under theestablished parent.

You can have as many levels of qualification for a GNP command as there are levelsin the database’s hierarchy. However, you should not qualify your command in away that causes DL/I to move off of the segment type you have established as aparent for the command.

USING PCB(expression)Specifies the DB PCB you want to use for the command. Its argument can beany expression that converts to the integer data type; you can specify either anumber or a reference to a halfword in your program containing a number.

KEYFEEDBACK(area)Specifies an area into which the concatenated key for the segment is placed. Ifthe area is not long enough, the key is truncated. Use this to retrieve asegment’s concatenated key.


INTO(area)Specifies an area into which the segment is read. Use this to retrieve one ormore segments with one command.


FIRSTSpecifies that you want to retrieve the first segment occurrence of a segmenttype, or that you want to insert a segment as the first occurrence. Use this toretrieve the first segment occurrence of a segment type.

LASTSpecifies that you want to retrieve the last segment occurrence of a segmenttype, or that you want to insert a segment as the last segment occurrence. Usethis to retrieve the last segment occurrence of a segment type.

CURRENTQualifies the command, and specifies that you want to use your current positionat this level and above as qualification for this segment. Use this to retrieve asegment based on your current position.

SEGLENGTH(expression)Specifies the length of the I/O area into which the segment is retrieved. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (SEGLENGTH is required in COBOL programs for any SEGMENTlevel that specifies the INTO or FROM option.)


OFFSET(expression)Specifies the offset to the destination parent. The argument can be any

GNP Command


expression that converts to the integer data type; you can specify either anumber or a reference to a halfword in your program containing a number. UseOFFSET when you process concatenated segments in logical relationships.OFFSET is required whenever the destination parent is a variable-lengthsegment.

LOCKEDSpecifies that you want to retrieve a segment for the exclusive use of yourprogram, until a checkpoint or sync point is reached. Use this to reserve asegment for the exclusive use of your program. This option performs the samefunction as the Q command code, and it applies to both Fast Path and fullfunction. A 1-byte alphabetic character of ’A’ is automatically appended as theclass for the Q command code.














GNP Command





KEYLENGTH(expression)Specifies the length of the concatenated key when you use the KEYS option. Itcan be any expression in the host language that converts to the integer datatype; if it is a variable, it must be declared as a binary halfword value. For IBMCOBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language,KEYLENGTH is optional. For COBOL programs that are not compiled with theIBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specifyKEYLENGTH with the KEYS option.

SEGMENT(name), SEGMENT((area))Qualifies the command, specifying the name of the segment type or the area inyour program containing the name of the segment type that you want toretrieve, insert, delete, or replace.

You can have as many levels of qualification for a GNP command as there arelevels in the database’s hierarchy. Using fully qualified commands with theWHERE or KEYS option clearly identifies the hierarchic path and the segmentyou want, and is useful in documenting the command. However, you do notneed to qualify a GNP command at all, because you can specify a GNP commandwithout the SEGMENT option.

Once you have established position in the database record, issuing a GNPcommand without a SEGMENT option retrieves the next segment occurrence insequential order.

If you specify a SEGMENT option without a KEYS or WHERE option, IMS DBretrieves the first occurrence of that segment type it encounters by searchingforward from current position. With an unqualified GNP command, the segmenttype you retrieve might not be the one you expected, so you should specify anI/O area large enough to contain the largest segment your program has accessto. (After successfully issuing a retrieval command, you can find out from DIBthe segment type retrieved.)


Including the WHERE or KEYS options for parent segments defines thesegment occurrences that are to be part of the path to the segment you wantretrieved. Omitting the SEGMENT option for a level, or including only theSEGMENT option without a WHERE option, indicates that any path to theoption satisfies the command. DL/I uses only the qualified parent segments andthe lowest-level SEGMENT option to satisfy the command. DL/I does notassume a qualification for the missing level.

UsageThe Get Next in Parent (GNP) command makes it possible to limit the search for asegment; you can retrieve only the dependents of a particular parent. You musthave established parentage before issuing a GNP command. IMS Version 7Application Programming: Database Manager explains how to establish parentage.

GNP Command


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 dependentsegments of the patient whose patient number is 09080; you do not want to retrieveall the dependents of each patient. To do this, use the GU command to establishyour position and parentage on the PATIENT segment for Kate Bailey. Thencontinue to issue a GNP without SEGMENT or WHERE options until DL/I returns allthe dependents of that PATIENT segment. (A GE status code indicates that youhave retrieved all the dependent segments.) To answer the request above, yourprogram could issue these commands:EXEC DLI GU

SEGMENT(PATIENT) INTO(PATAREA)WHERE (PATNO=PATNO1);

EXEC DLI GNPINTO(ILLAREA);

A GNP command without SEGMENT or WHERE options retrieves the first dependentsegment occurrence under the current parent. If your current position is already ona dependent of the current parent, the above command retrieves the next segmentoccurrence under the parent.

With an unqualified GNP command, the segment type you retrieve might not be theone you expected, so you should specify an I/O area large enough to contain thelargest segment your program has access to. (After successfully issuing a GNPcommand, 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 retrievesthe dependent segments of the segment type you have specified under theestablished parent. Suppose that for this example, the key of ILLNESS is ILLNAME,and the key of TREATMNT is MEDICINE. You want to retrieve each TREATMNTsegment where the treatment was acetaminophen. The name of the doctor whoprescribed the treatment is part of the TREATMNT segment. (Assume that dataarea ILLNAME1 contains HEADACHE, and MEDIC1 contains ACETAMINOP.) Toanswer 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/Ireturned a GE (not found) status code, then your program retrieves the nextheadache segment and retrieves the TREATMNT segments for it. Your programdoes this until there were no more ILLNESS segments where the ILLNAME washeadache.

RestrictionsThe 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 ofthe segment type you have established as the parent for the command.

GNP Command


v You can retrieve only the dependents of a particular parent.

GU CommandThe Get Unique (GU) command is used to directly retrieve specific segments, and toestablish a starting position in the database for sequential processing.

Format

�� EXEC DLI GET UNIQUEGU USING PCB(expression)

�



INTO(area) �

�<A> 

��

<A>:

VARIABLE LASTSEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

�



�


�


�



�

�KEYS(area)


:

VARIABLE LASTSEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

�

GNP Command


LOCKCLASS(class)

�


�


�



�

�KEYS(area)


Notes:








INTO(area)Specifies an area into which the segment is read.


LASTSpecifies that you want to retrieve the last segment occurrence of a segmenttype, or that you want to insert a segment as the last segment occurrence.

GU Command


SEGMENT(name), SEGMENT((area))Qualifies the command, specifying the name of the segment type or the area inyour program containing the name of the segment type that you want toretrieve, insert, delete, or replace.

To retrieve the first occurrence of a segment type, you need only specify theSEGMENT option. You can specify as many levels of qualification as there arehierarchic levels defined by the PCB you are using.

To establish position at the beginning of the database, issue a GU command witha SEGMENT option that names the root segment type.

If you leave out SEGMENT options for one or more hierarchic levels, DL/Iassumes a segment qualification for that level. The qualification that DL/Iassumes depends on your current position.

v If DL/I has a position established at the missing level, DL/I uses the segmenton which position is established.

v If DL/I does not have a position established at the missing level, DL/I usesthe first occurrence at that level.

v If DL/I moves forward from a position established at a higher level, DL/I usesthe 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 positionestablished on a root, DL/I does not move from that root when trying tosatisfy the command.

You can have as many levels of qualification for a GU command as there arelevels in the database’s hierarchy. Using fully qualified commands with theWHERE or KEYS option clearly identifies the hierarchic path and thesegment 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 aGU command without the SEGMENT option.

Once you have established position in the database record, issuing a GUcommand without a SEGMENT option retrieves the next segment occurrencein sequential order.

If you specify a SEGMENT option without a KEYS or WHERE option, IMSDB retrieves the first occurrence of that segment type it encounters bysearching forward from current position. With an unqualified GU command, thesegment type you retrieve might not be the one you expected, so you shouldspecify an I/O area large enough to contain the largest segment yourprogram has access to. (After successfully issuing a retrieval command, youcan find out from DIB the segment type retrieved.)


Including the WHERE or KEYS options for parent segments defines thesegment occurrences that are to be part of the path to the segment you wantretrieved. Omitting the SEGMENT option for a level, or including only theSEGMENT option without a WHERE option, indicates that any path to theoption satisfies the command. DL/I uses only the qualified parent segmentsand the lowest-level SEGMENT option to satisfy the command. DL/I does notassume a qualification for the missing level.

SEGLENGTH(expression)Specifies the length of the I/O area into which the segment is retrieved. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (SEGLENGTH is required in COBOL programs for any SEGMENTlevel that specifies the INTO or FROM option.)

GU Command



OFFSET(expression)Specifies the offset to the destination parent. The argument can be anyexpression that converts to the integer data type; you can specify either anumber or a reference to a halfword in your program containing a number. UseOFFSET when you process concatenated segments in logical relationships.OFFSET is required whenever the destination parent is a variable-lengthsegment.

LOCKEDSpecifies that you want to retrieve a segment for the exclusive use of yourprogram, until a checkpoint or sync point is reached. This option performs thesame function as the Q command code. It applies to both Fast Path and fullfunction. A 1-byte alphabetic character of ’A’ is automatically appended as theclass for the Q command code.











KEYLENGTH(expression)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 theinteger data type; a variable must be declared as a binary halfword value. For

GU Command


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 theIBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specifyKEYLENGTH with the KEYS option.

WHERE(qualification statement)Use WHERE to further qualify your GU commands after using SEGMENT. If youfully qualify a GU command, you can retrieve a segment regardless of yourposition in the database record.

KEYS(area)Use KEYS to further qualify your GU commands and specify the segmentoccurrence by using its concatenated key.

If you specify a SEGMENT option without a KEYS or WHERE option, IMS DBretrieves the first occurrence of that segment type it encounters by searchingforward from current position. With an unqualified GU command, the segmenttype you retrieve might not be the one you expected, so you should specify anI/O area large enough to contain the largest segment your program has accessto. (After successfully issuing a retrieval command, you can find out from DIBthe segment type retrieved.)


Including the WHERE or KEYS options for parent segments defines thesegment occurrences that are to be part of the path to the segment you wantretrieved. Leaving the SEGMENT option out for a level, or including only theSEGMENT option without a WHERE option, indicates that any path to theoption satisfies the command. DL/I uses only the qualified parent segments andthe lowest level SEGMENT option to satisfy the command. DL/I does notassume a qualification for the missing level.

UsageUse the GU command to retrieve specific segments from the database, or toestablish a position in the database for sequential processing.

You must at least specify the SEGMENT option with a GU command to indicate thesegment type you want to retrieve. (IMS DB retrieves the first occurrence of thesegment you named in the SEGMENT argument.)

When you need to retrieve a specific occurrence of a segment type, you can furtherqualify the command by using the WHERE or KEYS option after the SEGMENToption.

You probably want to further qualify your GU commands with the WHERE or KEYSoption, and specify a specific occurrence of a segment type. If you fully qualify a GUcommand, you can retrieve a segment regardless of your position in the databaserecord.

Examples

Example 1“What illness was Robert James here for most recently? Was he given anymedication on that day for that illness? His patient number is 05136.”

GU Command


Explanation: This example requests two pieces of information. To answer the firstpart of the request and retrieve the most recent ILLNESS segment, issue this GUcommand (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 mostrecent visit to the clinic, you could issue another command to find out whether hewas 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 wastreated on that day for that illness (assuming PATNO1 contains 05163, and DATE1contains 19880105):EXEC DLI GU

SEGMENT(PATIENT) WHERE(PATNO=PATNO1)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(PATIENT) WHERE(PATNO=PATNO1)SEGMENT(ILLNESS) INTO(ILLAREA);

Explanation: In this example you want the ILLNESS segment for the patientwhose patient number is 10320.

Example 3EXEC DLI GU

SEGMENT(PATIENT)SEGMENT(ILLNESS)SEGMENT(TREATMNT) INTO(AREA);

Explanation: This example retrieves the first TREATMNT segment and specifiesthe three levels of qualification.

RestrictionYou must at least specify the SEGMENT option to indicate the segment type youwant to retrieve.

ISRT CommandThe Insert (ISRT) command is used to add one or more segments to the database.

GU Command


Format


Specifies the DB PCB you want to use for the command. Its argument can be

�� EXEC DLI INSERTISRT USING PCB(expression)

<A>

��



SEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

�

�(1)

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

�

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

�



�

�KEYS(area)


 For the object segment (required):

VARIABLE FIRSTLAST

SEGLENGTH(expression) OFFSET(expression)�


�



�

�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 onesegment level.

ISRT Command

any expression that converts to the integer data type; you can specify either anumber or a reference to a halfword in your program containing a number.


FIRSTSpecifies that you want to retrieve the first segment occurrence of a segmenttype, or that you want to insert a segment as the first occurrence. Use FIRST toinsert a segment as a first occurrence of a segment type.

LASTSpecifies that you want to retrieve the last segment occurrence of a segmenttype, or that you want to insert a segment as the last segment occurrence. UseLAST to insert a segment as the last occurrence of a segment type.

CURRENTQualifies the command, and specifies that you want to use your current positionat this level and above as qualification for this segment. Use CURRENT toinsert a segment based on your current position.

SEGMENT(name), SEGMENT((area))Qualifies the command, specifying the name of the segment type or the area inthe 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 toadd to the database. Unless ISRT is a path command, the lowest levelSEGMENT option specifies the segment being inserted. You cannot use aWHERE or KEYS option for this level.

If a segment has a unique key, DL/I inserts the segment in its key sequence. (Ifthe segment does not have a key, or has a nonunique key, DL/I inserts itaccording to the value specified for the RULES parameter during DBDGEN.

Related Reading: See IMS Version 7 Application Programming: DatabaseManager for information about inserting segments with the ISRT call.

If you specify a SEGMENT option for only the lowest level segment, and do notqualify the parent segments with SEGMENT, WHERE, or KEYS options, youmust make sure that the current position is at the correct place in the databaseto insert the segment. The SEGMENT option that DL/I assumes depends onyour current position in the database record:

v If DL/I has a position established at the missing level, DL/I uses the segmenton which position is established.

v If DL/I does not have a position established at the missing level, DL/I usesthe first occurrence at that level.

v If DL/I moves forward from a position established at a higher level, DL/I usesthe 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 positionestablished on a root, DL/I does not move from that root when trying tosatisfy the command.

It is good practice to always provide qualifications for higher levels to establishthe 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 keytaken 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 assoon as it is built in the I/O area just by using a SEGMENT option for it in theISRT command. You need not code the parent level segments to establish yourposition.

When you specify multiple parent segments, you can mix segments with andwithout the WHERE option. If you include only SEGMENT options on parentsegments, DL/I uses the first occurrence of each segment type to satisfy thecommand.

SEGLENGTH(expression)Specifies the length of the I/O area from which the segment is obtained. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (It is required in COBOL programs for any SEGMENT level thatspecifies the INTO or FROM option.)


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.










WHERE establishes position on the parents of a segment when you areinserting that segment. You can do this by specifying a qualification of WHEREor KEYS for the higher level SEGMENT options.

When you specify multiple parent segments, you can mix segments with andwithout the WHERE option. If you include only SEGMENT options on parentsegments, DL/I uses the first occurrence of each segment type to satisfy thecommand.

ISRT Command




KEYs can be used to qualify a parent segment. Instead of using WHERE, youcan specify KEYS and use the concatenated key of the segment asqualification. You can use the KEYS option once for each command,immediately after the highest level SEGMENT option.


KEYLENGTH(expression)Specifies the length of the concatenated key when you use the KEYS option. Itcan be any expression in the host language that converts to the integer datatype; if it is a variable, it must be declared as a binary halfword value. For IBMCOBOL for MBS & VM (or VS COBOL II), PL/I, or assembler language,KEYLENGTH is optional. For COBOL programs that are not compiled with theIBM COBOL for MBS & VM (or VS COBOL II) compiler, you must specifyKEYLENGTH with the KEYS option.

UsageTo add new segments to an existing database, use the ISRT command. When youissue the ISRT command, DL/I takes the data from the I/O area you have named inthe FROM option and adds the segment to the database. (The initial loading of adatabase requires using the LOAD command, instead of the ISRT command.)

Related Reading:The IMS Version 7 Administration Guide: Database Managerdescribes 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 segmentsonly by reprocessing the whole database or by adding the new segments to the endof the database.

Before you can issue the ISRT command to add a segment to the database, yourprogram must build the segment to be inserted in an I/O area. If the segment has akey, you must place the correct key in the correct location in the I/O area. If fieldsensitivity is used, the fields must be in the order defined by the PSB for theapplication’s view of the segment.

If you are adding a root segment occurrence, DL/I places it in the correct sequencein the database by using the key you supply in the I/O area. If the segment you areinserting is not a root, but you have just inserted its parent, you can insert the childsegment by issuing an insert request qualified with only the segment name. Youmust 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 rootsegment occurrence. When you are adding new segment occurrences to anexisting database, the segment type must have been defined in the DBD. You canadd new segment occurrences directly or sequentially after you have built them inthe program’s I/O area.

If the segment type you are inserting has a unique key field, the location where DL/Iadds 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 controlwhere 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 SEGMstatement for the database.

Related Reading: For information on performing a DBDGEN, see IMS Version 7Utilities Reference: Database and Transaction Manager.

Examples

Example 1“Add information to the record for Chris Edwards about his visit to the clinic onFebruary 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. YourI/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 addinformation about the illness.”

Explanation: You build the TREATMNT segment in a segment I/O area. TheTREATMNT segment includes the date, the medication, amount of medication, andthe doctor’s name:19930201MYOCINb�b�b�0001TRIEBb�b�b�b�b�&b�

The following command adds both the ILLNESS segment and the TREATMNTsegment to the database:EXEC DLI ISRT

SEGMENT(PATIENT) WHERE (PATNO=PATNO1)SEGMENT(ILLNESS) FROM(ILLAREA)SEGMENT(TREATMNT) FROM(TRETAREA);

Example 3EXEC DLI ISRT

SEGMENT(ILLNESS) KEYS(CONKEY)SEGMENT(TREATMNT) FROM(TRETAREA);

Explanation: Using this command is the same as having a WHERE optionqualified on the key field for the ILLNESS and PATIENT segments.

RestrictionsThe following restrictions apply to the ISRT command:

v You cannot issue the ISRT command until you have built a new segment in theI/O area.

v You must specify at least one SEGMENT option for each segment being addedto the database.

v When inserting a segment, you must have position established on the parents ofthe segment.

ISRT Command


v If you specify a SEGMENT option for only the lowest level segment, and do notqualify the parent segments with SEGMENT, WHERE, or KEYS options, be surethat 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 byusing the WHERE or KEYS option; DL/I uses the key field value specified in theI/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 youuse a FROM option for a parent segment, you must use a FROM option for eachdependent segment. (You can begin the path at any level, but you must not leaveout any levels.)

v You can only use the FIRST option with segments that have either no keys orhave a nonunique key with HERE specified on the RULES operand of the SEGMstatement in the DBD.

v You can only use the LAST option when the segment has no key or a nonuniquekey, and the INSERT rule for the segment is either FIRST or HERE.

POS CommandThe Position (POS) command retrieves the location of either a dependent or the lastinserted sequential dependent segment.

Format

OptionsUSING PCB(n)


INTO(data_area)Specifies an area into which the segment is read.


FEEDBACKLEN(expression)Specifies the length of the key feedback area into which you want theconcatenated key retrieved. Its argument can be any expression that convertsto the integer data type; you can specify either a number or a reference to ahalfword in your program containing a number. (FEEDBACKLEN is required inCOBOL programs and optional in PL/I and assembler language programs.)

�� EXEC DLI POSITIONPOS

USING PCB(n) INTO(data_area) �


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

�

�WHERE(qualification_statement)FIELDLENGTH(expression)

��

ISRT Command




WHERE(qualification statement)Qualifies the command, specifying the segment occurrence. Its argument is oneor more qualification statements, each of which compares the value of a field ina segment to a value you supply.


UsageUse the POS command to:

v Retrieve the location of a specific sequential dependent segment, including thelast 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 unchangedand an FH status code is returned.

RestrictionThe POS command is for DEDBs only.

REPL CommandThe Replace (REPL) command is used to replace a segment, usually to change thevalues of one or more of its fields.

POS Command


Format






SEGLENGTH(expression)Specifies the length of the I/O area from which the segment is obtained. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. (It is required in COBOL programs for any SEGMENT level thatspecifies the INTO or FROM option.)


�� EXEC DLI REPLACEREPL USING PCB(expression)

<A>

��


VARIABLESEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

�

�OFFSET(expression)

FROM(area)MOVENEXT(data_value)

�


 For the object segment (required):

VARIABLESEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

�

�OFFSET(expression)

FROM(area)MOVENEXT(data_value)

�


REPL Command

OFFSET(expression)Specifies the offset to the destination parent. It can be any expression thatconverts to the integer data type; you can specify either a number or areference to a halfword in your program containing a number. You use OFFSETwhen you process concatenated segments in logical relationships. It is requiredwhenever 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 thecorresponding SEGMENT option for each segment you want to replace.Including FROM options for one or more parent segments is called a pathcommand.

The argument following FROM identifies an I/O area that you have defined inyour program. You must use a separate I/O area for each segment type youwant to replace.





UsageYou 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, andyou do not want to replace all of the retrieved segments or the PSB does not havereplace sensitivity for all of the retrieved segments, you can indicate which of thesegments 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 havereplace sensitivity, the data for the segment in the I/O area for the REPL commandmust be the same as the segment returned on the preceding GET command. If thedata changes in this situation, the transaction is abended and no data is changedas a result of the Replace command.

Notice that the rules for a REPL path command differ from the rules for an ISRT pathcommand. 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 REPLcommand replaces data in a segment with data you supply in your applicationprogram. First, you must retrieve the segment into an I/O area. You then modify theinformation in the I/O area and replace the segment with the REPL command. Foryour program to successfully replace a segment, that segment must already havebeen defined as replace-sensitive in the PCB by specifying PROCOPT=A orPROCOPT=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 commandand the REPL command, and you can issue only one REPL command for each Getcommand.

Examples

Example 1EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA);EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA);

Explanation: This example shows that you cannot issue any commands using thesame PCB between the Get command and the REPL command, and you can issueonly one REPL command for each Get command. If you issue the above commandsand wanted to modify information in the segment again, you must first reissue theGU command, before reissuing the REPL command.

Example 2“We have received a payment for $65.00 from a patient whose ID is 08642. Updatethe patient’s billing record and payment record with this information, and print acurrent 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 thevalue in the BILLING segment, and adding $65.00 to the value in the PAYMENTsegment.

3. Replace the values in the BILLING and PAYMENT segments with the newvalues.

4. Print a bill for the patient, showing the patient’s name, number, address, thecurrent amount of the bill, and the amount of the payments to date.

To retrieve the BILLING and PAYMENT segments, issue a GU command. Becauseyou also need the PATIENT segment when you print the bill, you can include INTOfollowing the SEGMENT options for the PATIENT segment and for the BILLINGsegment: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, thenreplace the billing and payment segments in the database. Before issuing the REPLcommand, you must change the segments in the I/O area.

Because you have not changed the PATIENT segment, you do not need to replaceit when you replace the BILLING and PAYMENT segments. To indicate to DL/I thatyou do not want to replace the PATIENT segment, you do not specify theSEGMENT 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 notto replace the PATIENT segment.

These two examples are called path commands. You use a path REPL command toreplace more than one segment with one command.

Example 3“Steve Arons, patient number 10250, has moved to a new address in this town. Hisnew address is 4638 Brooks Drive, Lakeside, California. Update the database withhis new address.”

Explanation: You need to retrieve the PATIENT segment for Steve Arons andreplace the address portion of the segment. To retrieve the PATIENT segment, youcan 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 (PATNOand NAME), you do not have to change them in the I/O area. Place the newaddress in the I/O area following the PATNO and NAME fields. Then you issue thefollowing REPL command:EXEC DLI REPL

SEGMENT(PATIENT) FROM(PATAREA);

Example 4EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA)

WHERE (PATNO=PATNO1)SEGMENT(ILLNESS) INTO(ILLAREA)SEGMENT(TREATMNT) INTO(TRETAREA);

EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA)SEGMENT(TREATMNT) FROM(TRETAREA);

Explanation: This example assumes that you want to replace the PATIENT andTREATMNT segments for patient number 10401, but you do not want to change theILLNESS segment. To do this issue the above command (assuming PATNO1contains 10401).

RestrictionsThe following restrictions apply to the REPL command:

v You cannot issue any commands using the same PCB between the Getcommand 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 commandbefore reissuing the REPL command.

v You must qualify the REPL command with at least one SEGMENT option and oneFROM option.

v If you use a FROM option for a segment, you cannot qualify the segment byusing the WHERE or KEYS option; DL/I uses the key field value specified in theI/O area as qualification.

RETRIEVE CommandUse the RETRIEVE command to determine current position in the database in batchand BMP programs.

REPL Command


Format



expression specifies the PCB for which you want to retrieve the concatenatedkey. It can be any expression in the host language that converts to the integerdata type. You can specify either a number or a reference to a halfwordcontaining a number. The value must be a positive integer not greater than thenumber 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.



expression is the length of the key feedback I/O area. It can be any expressionin the host language that converts to integer data type; you can specify either anumber or a reference to a halfword containing a number. For IBM COBOL forMVS & VM (or VS COBOL II), PL/I, or assembler language, FEEDBACKLEN isoptional. For COBOL programs that are not compiled with the IBM COBOL forMVS & VM (or VS COBOL II) compiler, you must specify FEEDBACKLEN withthe KEYFEEDBACK option.

UsageIf your program issues symbolic checkpoint commands it must also issue theextended RESTART (XRST) command or the RETRIEVE command. The RETRIEVEcommand is issued once, at the start of your program. You can use the RETRIEVEcommand to start your program normally, or to restart it in case of an abnormaltermination.

You can use the RETRIEVE command from a specific checkpoint id or a time/datestamp. Because the RETRIEVE command attempts to reposition the database, yourprogram also needs to check for correct position.

After issuing the RETRIEVE command, the segment type and level on which theposition is established is returned to the DIBSEGM and DIBSEGLV fields in theDIB. The value in DIBKFBL is set to the actual length of the concatenated key. TheDIBSTAT field contains the value returned from the GU repositioning, not the XRSTcommand.

�� EXEC DLI RETRIEVE USING PCB(expression) KEYFEEDBACK(area) �

� FEEDBACKLEN(expression) ��

RETRIEVE Command


The RESTART command attempts to reposition DL/I databases by issuing aninternal GU qualified with the concatenated key. It is your responsibility to verify thatyour position in the database from the GU repositioning is the correct position for thecheckpoint ID used in the XRST command. You can use the RETRIEVE command toretrieve the concatenated key used with the GU repositioning, and determine yourcurrent position in all the PCBs your program accesses.

ExamplesEXEC DLI RETRIEVE USING PCB(2) KEYFEEDBACK(KEYAREA);

EXEC DLI RETRIEVE USING PCB(5) KEYFEEDBACK(KEYAREA);

ExplanationThese RETRIEVE commands retrieve the concatenated key for the first and fourth DBPCBs. (The first PCB in the list is the I/O PCB, so the first DB PCB is the secondone in the list.) After issuing the first RETRIEVE command, you can determine yourposition in the first DB PCB by examining the concatenated key in KEYAREA, andthe values returned in the DIBSEGM and DIBSEGLV fields in the DIB. After issuingthe second RETRIEVE command, you can determine your position in the fourth DBPCB by examining the same fields.

RestrictionsThe 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 nonunique keys or nonkeyedsegments.

v You cannot use this command unless the system log is stored on direct accessstorage and dynamic backout has been specified. You must also specify BKO=Yin the parm field of your JCL when you execute the program.

SCHD CommandThe Schedule (SCHD) command is used to schedule a PSB in a CICS onlineprogram. For information on the I/O PCB, see “Using the I/O PCB, PSB, and PCB”on page 11.

Format

OptionsPSB(name)

Specifies the name of the PSB available to your application program that youwant to schedule with the SCHD command.

PSB((area))Specifies an 8-byte data area in your program that contains the name of thePSB available to your program that you want to schedule with the SCHDcommand.

�� EXEC DLI SCHEDULESCHD

PSB(name)PSB((area)) SYSSERVE NODHABEND

��

RETRIEVE Command


SYSSERVESpecifies that the application program can handle an I/O PCB and might issuea system service request in the logical unit of work (LUW).

NODHABENDSpecifies 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 theDIB, causing a CICS transaction to fail with a DHxx abend. This option preventsthis. Following an unsuccessful SCHD command, the control, as well as thestatus code in the DIB are passed back to the application program, which canthen take the appropriate action.

UsageBefore you can access DL/I databases from a CICS program, you must notify DL/Ithat your program will be accessing a database by scheduling a PSB. Do this byissuing the SCHD command. When you no longer plan to use a PSB, or you want toschedule a subsequent PSB (one or more), you must terminate the previous PSBwith 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).

ExamplesEXEC DLI SCHD PSB(psbname)SYSSERVE;

EXEC DLI SCHD PSB((AREA));

ExplanationThese examples show two ways to schedule a PSB in a CICS program.

TERM CommandThe Terminate (TERM) command is used to terminate a PSB, in a CICS onlineprogram.

Format

OptionsNo options are allowed with the TERM command.

UsageIf you want to use a PSB other than the one already scheduled, use the TERMcommand to release the PSB.

When you issue the TERM command, all database changes are committed andcannot be backed out. Because returning to CICS also terminates the PSB andcommits changes, you need not use the TERM command unless you want toschedule another PSB, or commit database changes before returning to CICS.

�� EXEC DLI TERMINATETERM

��

SCHD Command


No options are allowed with the TERM command. If your program subsequentlyneeds a PSB that has terminated, it must reschedule that PSB by issuing anotherSCHD command.

In most applications, you do not need to use the TERM command.

ExampleEXEC DLI TERM

ExplanationThis example shows how to terminate a PSB with the TERM command.

System Service CommandsThe following system service commands require that you first issue the SCHDcommand 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 firstissuing 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 usingDBCTL:

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. Fordetailed information on the I/O PCB, as well as the PSB, and PCB, see “Using theI/O PCB, PSB, and PCB” on page 11.

TERM Command


ACCEPT CommandThe Accept (ACCEPT) command is used to tell IMS to return a status code to yourprogram, rather than abend the transaction.

Format

OptionsSTATUSGROUP('A')

Informs IMS that the application is prepared to accept status codes regardingunavailability. IMS then returns a status code instead of pseudoabending if acall issued later requires access to unavailable data.

This is a required option.

UsageUse the ACCEPT command to tell IMS to return a status code instead of abendingthe program. These status codes result because PSB scheduling completed withoutall of the referenced databases being available.

ExampleEXEC DLI ACCEPT STATUSGROUP('A');

This example shows how to specify the ACCEPT command.

CHKP CommandThe Checkpoint (CHKP) command is used to issue a basic checkpoint and to end alogical unit of work. You cannot use this command in a CICS program.

Format

OptionsID(area)

Contains the checkpoint ID. Specifies the name of an area in your programcontaining the checkpoint ID. The area pointed to is eight bytes. If you areusing PL/I, specify this option as a pointer to a major structure, an array, or acharacter string.

ID('literal')'literal' is an 8-byte checkpoint ID, enclosed in quotation marks. In CHKPcommands the area pointed to is 8 bytes long.

UsageThe two kinds of commands that allow you to make checkpoints are: the CHKP, orbasic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.

�� EXEC DLI ACCEPT STATUSGROUP('A') ��

�� EXEC DLI CHECKPOINTCHKP

ID(area)ID(’literal’)

��

ACCEPT Command


Batch programs can use either the symbolic or the basic command.

Both checkpoint commands make it possible for you to commit your program’schanges to the database and to establish places from which the program can berestarted, should it terminate abnormally.

You must not use the CHKPT=EOV parameter on any DD statement to take an IMScheckpoint.

See IMS Version 7 Application Programming: Design Guide for an explanation ofwhen and why you should issue checkpoints in your program. Both commandscause a loss of database position at the time the command is issued. Position mustbe reestablished by a GU command or other method of establishing position.

It is not possible to re-establish position in the midst of nonunique keys or nonkeyedsegments.

You can issue the basic CHKP command to commit your program’s changes to thedatabase and establish places from which your program can be restarted. Whenyou issue a basic CHKP command, you must provide the code for restarting yourprogram.

When you issue a CHKP command, you specify the ID for the checkpoint. You cansupply either the name of a data area in your program that contains the ID, or youcan supply the actual ID, enclosed in single quotes. See the examples below.

ExamplesEXEC DLI CHKP ID(chkpid);

EXEC DLI CHKP ID('CHKP0007');

ExplanationThese examples show how to specify the CHKP command.

RestrictionsThe 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 CHKPcommand.


DEQ CommandThe Dequeue (DEQ) command is used to release a segment that is retrieved withthe LOCKCLASS option.

Format

�� EXEC DLI DEQ LOCKCLASS(data_value) ��

CHKP Command


OptionLOCKCLASS(data_value)

Specifies that you want to release the lock that is being held as the result of anearlier GU, GN, or GNP command that had a LOCKCLASS option with the samedata_value. Data_value must be a 1-byte alphabetic character in the range of Bto J.

For full function, specify the LOCKCLASS option followed by the lock class ofthat segment (for example, LOCKCLASS('B')). If the option is not followed by aletter (B-J), EXECDLI sets a status code of GL and initiates an ABENDU1041.

DEQ commands are not supported for Fast Path.

UsageUse the DEQ command to release locks on segments that were retrieved using theLOCKCLASS option. Using LOCKCLASS on Get commands allows you to reservesegments for exclusive use by your transaction. No other transaction is allowed toupdate these reserved segments until either your transaction reaches a sync pointor the DEQ command has been issued, thereby releasing the locks on thesereserved segments. The LOCKCLASS option lets your application program leavethese segments and retrieve them later without any changes having been added.

ExampleYour 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');

ExplanationThis example shows the format of the DEQ command, where data_value is a 1-bytealphabetic character in the range B to J. The DEQ command releases the lock thatwas gotten and held with a LOCKCLASS of ’B’ for the PARTX segment as a resultof the first GU. The lock that was gotten with a LOCKCLASS of ’C’ on the PARTXsegment 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 thedatabase.

DEQ Command


Format


Specifies the DB PCB you want to use. Its argument can be any expressionthat converts to the integer data type; you can specify either a number or areference to a halfword in your program containing a number.


SEGMENT(name)Specifies the name of the segment type you want to retrieve, insert, delete, orreplace.

SEGMENT((area))A reference to an area in your program containing the name of the segmenttype. You can specify an area instead of the name of the segment in thecommand.

SEGLENGTH(expression)Specifies the length of the I/O area from which the segment is obtained. Itsargument can be any expression that converts to the integer data type; you canspecify either a number or a reference to a halfword in your program containinga number. ( SEGLENGTH is required in COBOL programs for any SEGMENTlevel that specifies the INTO or FROM option.)


FROM(area)Specifies an area containing the segment to be added, replaced, or deleted.

UsageThe LOAD command is used for database load programs, which are described inIMS Version 7 Administration Guide: Database Manager.

ExampleEXEC DLI LOAD

SEGMENT(ILLNESS) FROM(ILLAREA);

LOG Command

The Log (LOG) command is used to write information to the system log.

�� EXEC DLI LOADUSING PCB(expression) VARIABLE

�

� SEGMENT(name)SEGMENT((area)) SEGLENGTH(expression)

FROM(area) ��

LOAD Command


Format

OptionsFROM(area)

Specifies an area containing the segment to be added, replaced, or deleted.

LENGTH(expression)Specifies the length of an area.

UsageYou use the LOG command to write information to the system log. For detailedinformation on this command, see IMS Version 7 Application Programming: DesignGuide.

ExampleEXEC 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/Iinterface block (DIB), which is a subset of the IMS PCB.

Format

OptionsUSING PCB(expression) is required. No other options are allowed with the QUERYcommand.

UsageFor full-function databases, the DIB should contain NA, NU, TH or blanks. For anexplanation of the codes, see “Status Code Explanations” on page 127.

Use the QUERY command after scheduling the PSB but before making the databasecall. If the program has already issued a call using the DB PCB, you then use theREFRESH command to update the information in the DIB.

�� EXEC DLI LOG FROM(area) LENGTH(expression) ��

�� EXEC DLI QUERY USING PCB(expression) ��

LOG Command


Examples

Example 1EXEC DLI QUERY USING PCB(expression);

Explanation: This example shows how to specify the QUERY command. In thisexample, (n) specifies the PCB.

Example 2EXEC 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 REFRESHcommand updates all DB PCBs. You can issue it only one time.

Restrictions

The following restrictions apply to the QUERY command:



REFRESH Command

The Refresh (REFRESH) command is used to obtain the most recent information fromthe DIB for the most recently issued command.

Format

OptionsDBQUERY is required. Other options are not allowed with the REFRESH command.

UsageThe REFRESH command is used with the QUERY command.

The QUERY command is used after scheduling the PSB but before making the firstdatabase call. If the program has already issued a call using the DB PCB, use theREFRESH command to update the information in the DIB.

The REFRESH command updates all DB PCBs. It can be issued only once.

ExampleEXEC DLI REFRESH DBQUERY;

ExplanationThis example shows how to specify the REFRESH command.

�� EXEC DLI REFRESH DBQUERY ��

QUERY 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.


v You can issue this command only one time.

ROLB Command

The Roll Back (ROLB) command is used to dynamically back out changes and returncontrol to your program. You cannot use this command in a CICS program.

Format

OptionsNo options are allowed with the ROLB command.

UsageWhen 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 itsinaccurate processing. These are the rollback commands, ROLL (see “ROLLCommand” on page 56) and ROLB.

The ROLB command is valid in batch programs when the system log is stored ondirect access storage and dynamic backout has been specified through the use ofthe BKO execution parameter.

Issuing the ROLB causes IMS DB to back out any changes your program has madeto the database since its last checkpoint, or since the beginning of the program ifyour program has not issued a checkpoint. When you issue a ROLB command, IMSDB returns control to your program after backing out the changes, so that yourprogram can continue processing with the next statement after the ROLB command.

ExampleEXEC DLI ROLB;

ExplanationThis example shows how to dynamically back out changes and return control toyour 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 thiscommand.

�� EXEC DLI ROLB ��

REFRESH Command



v You cannot use this command when the system log is stored on direct accessstorage and dynamic backout has not been specified.

ROLL Command

The Roll (ROLL) command is used to dynamically back out changes. You cannot usethis command in a CICS program

Format

OptionsNo options are allowed with the ROLL command.

UsageWhen a batch program determines that some of its processing is invalid, twocommands make it possible for the program to remove the effects of its inaccurateprocessing. These are the rollback commands, ROLL and ROLB (see “ROLBCommand” 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 hasmade to the database since its last checkpoint, or since the beginning of theprogram provided your program has not issued a checkpoint. When you issue aROLL command, DL/I terminates your program after backing out the updates.

ExampleEXEC DLI ROLL;

ExplanationThis 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 codeU0778. 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 thiscommand.


v You cannot use this command when the system log is stored on direct accessstorage and dynamic backout has been specified. You must also specify BKO=Yin the parm field of your JCL when you execute the program.

�� EXEC DLI ROLL ��

ROLB Command


ROLS Command

The Roll Back to SETS or SETU (ROLS) command is used to back out to aprocessing point set by an earlier SETS command.

Format



TOKEN(token)A 4-byte token associated with the current processing point. If you specify bothTOKEN and AREA, the ROLS command backs out to the SETS or SETU youspecified.

AREA(data_area)The name of the area to be restored to the program when a ROLS command isissued. The first 2 bytes of the data-area field contain the length of thedata-area, including the length itself. The second 2 bytes must be set toX'0000'. If you specify both TOKEN and AREA, the ROLS command backs out tothe SETS you specified.

The ROLS call has two formats: with TOKEN and AREA (for IOPCB only) and withoutTOKEN and AREA (for IOPCB or DBPCB).

UsageUse the SETS and ROLS commands to define multiple points at which to preserve thestate of DL/I full-function databases and to return to these points later. (Forexample, you can use them so your program can handle situations that can occurwhen PSB scheduling completes without all of the referenced DL/I databases beingavailable.)

Use of the SETS and ROLS commands apply only to DL/I full-function databases. Thismeans that if a logical unit of work (LUW) is updating types of recoverableresources other than full-function databases, for example, VSAM files, the SETS andROLS requests have no effect on the non-DL/I resources. The backout points are notCICS commit points; they are intermediate backout points that apply only to DBCTLresources. 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 databaseswere in before either a specific SETS or SETU request or the most recent commitpoint.

Examples

Example 1EXEC DLI ROLS TOKEN(token1) AREA(data_area)

�� EXEC DLI ROLS USING PCB(expression)TOKEN(token) AREA(data_area)

��

ROLS Command


Explanation: In this example (for IOPCB only), backout takes place to thecorresponding TOKEN, as specified by a prior SETS call, and control returns to theapplication.

Example 2EXEC DLI ROLS USING PCB(PCB5)

Explanation: In this example, for IOPCB or DBPCB, backout takes place to theprior 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 'dataunavailable' status code. This command results in the same action that would haveoccurred had the program not issued an ACCEPT STATUSGROUPA command.(See “Chapter 7. Using Data Availability Enhancements” on page 109.)

Example 3EXEC DLI ROLS

Explanation: In this example, for IOPCB or DBPCB, backout takes place to theprior sync point and the application is pseudo-abended with a U3033, provided theprevious reference to that PCB gave an unavailable status code. Control does notreturn to the application.

Restrictions

The following restrictions apply to the ROLS command:




SETS Command

The Set a Backout Point (SETS) command is used to define points in yourapplication at which to preserve the state of the DL/I databases before initiating aset of DL/I requests to perform a function. Your application can issue a ROLScommand later if it cannot complete the function.

Format

OptionsTOKEN(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

�� EXEC DLI SETSTOKEN(mytoken) AREA(data_area)

��

ROLS Command


issued. The first 2 bytes of the data-area field contain the length of thedata-area, including the length itself. The second 2 bytes must be set toX'0000'.

UsageYou can use the SETS command to define multiple points at which to preserve thestate of the DL/I databases and to return to these points later. For example, youcan use the SETS command to allow your program to handle situations that canoccur when PSB scheduling completed without all of the referenced DL/I databasesbeing available.

The SETS command applies only to DL/I full-function databases. If a logical unit ofwork (LUW) is updating types of recoverable resources other than full-functiondatabases, for example VSAM files, the SETS command has no effect on thenon-DL/I resources. The backout points are not CICS commit points; they areintermediate backout points that apply only to DBCTL resources. It is up to you toensure the consistency of all the resources involved.

ExampleEXEC DLI SETS TOKEN(mytoken) AREA(data_area)

ExplanationThis example shows how to specify the SETS command.

Restrictions

The following restrictions apply to the SETS command:



v In batch, you can only use this command when the system log is stored on directaccess storage and dynamic backout has been specified. You must also specifyBKO=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 ismade to a DB2 database.

v It is valid, but not functional, if unsupported PCBs exist in the PSB or if theprogram uses an external subsystem.

SETU CommandThe Set a Backout Point Unconditionally (SETU) command is identical to the SETScommand except that it does not get rejected if unsupported PCBs are in the PSBor if the program uses an external subsystem.

Format

�� EXEC DLI SETUTOKEN(mytoken) AREA(data_area)

��

SETS Command


OptionsTOKEN(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 isissued. The first 2 bytes of the data-area field contain the length of thedata-area, including the length itself. The second 2 bytes must be set toX'0000'.

UsageYou can use the SETU command to define multiple points at which to preserve thestate of the DL/I databases and to return to these points later. For example, youcan use the SETU command to allow your program to handle situations that canoccur when PSB scheduling completed without all of the referenced DL/I databasesbeing available.

The SETU command applies only to DL/I full-function data bases. If a logical unit ofwork (LUW) is updating types of recoverable resources other than full-functiondatabases, such as VSAM files, the SETU command has no effect on the non-DL/Iresources. The backout points are not CICS commit points; they are intermediatebackout points that apply only to DBCTL resources. It is up to you to ensure theconsistency of all the resources involved.

ExampleEXEC DLI SETU TOKEN(mytoken) AREA(data_area)

ExplanationThis example shows how to specify the SETU command.

Restrictions

The following restrictions apply to the SETU command:





STAT CommandThis section contains programming interface information.

The Statistics (STAT) command is used to obtain IMS database statistics that youcan use in debugging your program.

SETU Command


Format



INTO(area)Specifies an area into which the data is read.

LENGTH(expression)Specifies the length of an area.

VSAM/NONVSAMSpecifies database type.

FORMATTED/UNFORMATTED/SUMMARYSpecifies type of output.

UsageThe STAT command is described in IMS Version 7 Application Programming: DesignGuide.

ExamplesFor 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 symboliccheckpoint and to end a logical unit of work.

Format

�� EXEC DLI STATISTICSSTAT USING PCB(expression)

INTO(area) �

�LENGTH(expression)

VSAM

NONVSAM

FORMATTED

UNFORMATTEDSUMMARY

��

�� EXEC DLI SYMCHKP ID(chkpid)ID('literal')

�

�

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

STAT Command


OptionsID(chkpid)

Is the name of an 8-byte area in your program containing the checkpoint ID. Ifyou are using PL/I, specify this parameter as a pointer to a major structure, anarray, 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 notneed to specify any area to checkpoint; however, you cannot specify more thanseven areas. If you specify more than one area, you must include allintervening areas. For example, if you specify AREA3, you must also specifyAREA1 and AREA2. The areas you specify using the SYMCHKP command mustbe 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 datatype; you can specify either a number or a reference to a halfword containing anumber. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assemblerlanguage programs, LENGTH1 to LENGTH7 are optional. For COBOLprograms that are not compiled with the IBM COBOL for MVS & VM (or VSCOBOL II) compiler, LENGTHx (where x is 1 to 7) is required for each AREAx(where x is 1 to 7) that you specify.

UsageThe two kinds of commands that allow you to make checkpoints are: the CHKP, orbasic 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’schanges to the database and to establish places from which the program can berestarted, should it terminate abnormally. You must not use the CHKPT=EOVparameter on any DD statement to take an IMS checkpoint.

Refer to IMS Version 7 Application Programming: Design Guide for an explanationof when and why you should issue checkpoints in your program. Both commandscause a loss of database position at the time the command is issued. Position mustbe reestablished by a GU command or other method of establishing position.

In addition to committing your program’s changes to the database and establishingplaces from which your program can be restarted, the Symbolic Checkpointcommand:

v Works with the Extended Restart ( XRST) command to restart your program if itterminates abnormally.

v Can save as many as seven data areas in your program, which are restoredwhen your program is restarted. You can save variables, counters, and statusinformation.

SYMCHKP Command


ExampleEXEC DLI SYMCHKP

ID(chkpid)AREA1(area1) LENGTH1(expression1)...AREA7(area7) LENGTH7(expression7)

ExplanationThis example shows how to issue a symbolic checkpoint and to end a logical unit ofwork 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.


v The areas you specify using the SYMCHKP command must be the same, and in thesame order, as the areas specified in the XRST command.

v If you specify more than one area, you must specify all intervening areas. Forexample, if you specify AREA3, you must also specify AREA1 and AREA2.

v When specifying expression1 with a COBOL program that is not compiled withthe 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 youspecify.

XRST Command

The Extended Restart (XRST) command is used to issue an extended restart, and toperform a normal start or an extended restart from a checkpoint ID or time/datestamp. If you use Symbolic Checkpoint commands in your program, you must usethe XRST command.

Format

OptionsMAXLENGTH(expression)

Specifies the length of an area from which a program is restarted. Thisparameter is the longest segment in the PSB, or of all the segments in a path, ifyou use path commands in your program. It can be any expression in the host

�� EXEC DLI XRSTMAXLENGTH(expression) ID(chkpid)

ID('literal')

�

�

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

SYMCHKP Command


language that converts to the integer data type. You can specify either anumber or a reference to a halfword containing a number. MAXLENGTH is notrequired, and defaults to 512 bytes.

ID(chkpid) ID('literal')This parameter is either the name of a 30-byte area in your program or a30-byte checkpoint ID, enclosed in quotes. This parameter is optional; you canspecify a checkpoint ID or a time/date stamp in the parm field of your JCLinstead. If you specify both, IMS uses the value in the parm field of the EXECstatement. If you are starting your program normally, do not specify acheckpoint 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 theEXEC statement is not used, then the rightmost bytes beyond the checkpoint IDbeing used in the I/O area must be set to blanks.

You can issue a XRST command after supplying a time/date stamp ofIIIIDDDHHMMSST, or from a specific checkpoint in your program by supplying acheckpoint ID. IIIIDDD is the region ID and day; HHMMSST is the actual time inhours, minutes, seconds, and tenths of seconds. The system messageDFS0540I 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 canspecify 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. Forexample, if you specify AREA3, you must also specify AREA1, and AREA2. Theareas you specify on the XRST command must be the same—and in the sameorder—as the areas you specify on the SYMCHKP command. When you restartthe program, only the areas you specified in the SYMCHKP command arerestored.

LENGTH#(expression#)Specifies the length of an area from which a program is restarted. Its argumentcan be any expression in the host language that converts to the integer datatype; you can specify either a number or a reference to a halfword containing anumber. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assemblerlanguage programs LENGTH1 to LENGTH7 are optional. For COBOL programsthat 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 is1 to 7) that you specify. Each qualification statement consists of:




UsageIf your programs issues Symbolic Checkpoint commands it must also issue theExtended Restart (XRST) command. The XRST is issued once, at the start of yourprogram. You can use the XRST command to start your program normally, or toextend restart it in case of an abnormal termination.

XRST Command


You can extend restart your program from a specific checkpoint ID, or a time/datestamp. Because the XRST attempts to reposition the database, your program alsoneeds 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 ofan 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 the8-byte ID consists of all blanks, then XRST will return the 14-byte timestamp ID. Theonly successful status code for an XRST command is a blank status code. If DL/Idetects any error while processing the XRST command, your program abends.

ExampleEXEC DLI XRST MAXLENGTH(expression)

ID(chkpid)AREA1(area1) LENGTH1(expression1)...AREA7(area7) LENGTH7(expression7)

ExplanationThis example shows how to specify the XRST command.

Restrictions

The following restrictions apply to the XRST command:




v You cannot use this command unless the system log is stored on direct accessstorage and dynamic backout has been specified. You must also specify BKO=Yin the parm field of your JCL when you execute the program.

XRST Command


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 AIBinterface, the format for the GU command would be EXEC DLI GU AIB(aib), insteadof EXEC DLI GU USING PCB(n) using the PCB format.

With CICS Transaction Server 1.1 or later, the following EXEC DLI commands aresupported 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 followingAIB-only commands are supported via the EXEC DLI interface: ICMD, RCMD andGMSG.

The CICS EDF debugging transaction supports AIB EXEC DLI requests, just as ithandles PCB type requests.

AIB MaskThe AIB mask must be supplied by the application and referenced in the EXEC callinstead 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 othervalues and respond accordingly.


CICS Restrictions with AIB supportRestrictions 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 andother information to your program through the DL/I interface block (DIB), which is asubset of IMS PCB. Your program should check the status code to make sure thecommand executed successfully.

Each program’s working storage contains its own DIB. The contents of the DIBreflect the status of the last DL/I command executed in that program. If theinformation in your program’s DIB is required by another program used by yourtransaction, you must pass the information to that program.

To access fields in the DIB, use labels that are automatically generated in yourprogram 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 aremandatory.

For a COBOL program:DIBVERPICTURE X(2)DIBSTATPICTURE X(2)DIBSEGMPICTURE X(8)DIBSEGLVPICTURE X(2)DIBKFBLPICTURE S9(4) COMPUTATIONALDIBDBDNMPICTURE 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:DIBVERCL2DIBSTATCL2DIBSEGMCL8DIBSEGLVCL2DIBKFBLHDIBDBDNMCL8DIBDBORGCL8

For a C program:unsigned char dibver {2} ;unsigned char dibstat {2} ;unsigned char dibsegm {8} ;unsigned char dibfic01 ;unsigned char dibfic02 ;

Specifying an Application Interface Block (AIB)


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 inparenthesis 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 fordocumentation and problem determination.)

2. Status Code (DIBSTAT)

DL/I places a 2-character status code in this field after executing each DL/Icommand. This code describes the results of the command.

After processing a DL/I command, DL/I returns control to your program at thenext sequential instruction following the command. The first thing your programshould do after each command is to test the status code field and takeappropriate action. If the command was completely successful, this fieldcontains blanks.

Following are the status codes that could be returned to this field (they are theonly status codes returned to your program):

b�b� (Blanks) The command was completely successful.

BA For GU, GN, GNP, DLET, REPL, and ISRT commands. Data was unavailable.

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 spaceis required than normally allowed.

GA For unqualified GN and GNP commands. DL/I returned a segment, but thesegment is at a higher level in the hierarchy than the last segment thatwas returned.

GB For GN commands. DL/I reached the end of the database trying tosatisfy your GN command and did not return a segment to yourprogram’s I/O area.

GD For ISRT commands. The program issued an ISRT command that didnot have SEGMENT options for all levels above that of the segmentbeing inserted.

GE For GU, GN, GNP, ISRT, and STAT commands. DL/I was unable to find thesegment you requested, or one or more of the parents of the segmentyou are trying to insert.

GG For Get commands. DL/I returns a GG status code to a program with aprocessing option of GOT or GON when the segment that the programis trying to retrieve contains an invalid pointer.

GK For unqualified GN and GNP commands. DL/I returned a segment thatsatisfies an unqualified GN or GNP request, but the segment is of adifferent segment type (but at the same level) than the last segmentreturned.

II For ISRT commands. The segment you are trying to insert already existsin the database. This code can also be returned if you have notestablished a path for the segment before trying to insert it. The

Specifying the DL/I Interface Block (DIB)

Chapter 3. Defining Application Program Elements to IMS 69

segment you are trying to insert might match a segment with the samekey in another hierarchy or database record.

LB For load programs only after issuing a LOAD command. The segmentyou are trying to load already exists in the database. DL/I returns thisstatus code only for segments with key fields.

NI For ISRT and REPL commands. The segment you are trying to insert orreplace requires a duplicate entry to be inserted in a secondary indexthat does not allow duplicate entries. This status code is returned forbatch programs that write log records to direct access storage. If aCICS program that does not log to disk encounters this condition, theprogram (transaction) is abnormally terminated.

TG For TERM commands. The program tried to terminate a PSB when onewas not scheduled.

The status codes listed above indicate exceptional conditions, and are the onlystatus codes returned to your program. All other status codes indicate errorconditions and cause your transaction or batch program to abnormallyterminate. If you want to pass control to an error routine from your CICSprogram, you can use the CICS HANDLE ABEND command; the last 2 bytes of theabend code are the IMS status code that caused the abnormal termination. Formore information on the HANDLE ABEND command, see the applicationprogramming reference manual for your version of CICS. Batch BMP programsabend with abend 1041.

3. Segment Name (DIBSEGM)

This is the name of the lowest-level segment successfully accessed. When aretrieval is successful, this field contains the name of the retrieved segment. Ifthe retrieval is unsuccessful, this field contains the last segment, along the pathto the requested segment, that satisfies the command.

After issuing an XRST command, this field is either set to blanks (indicating asuccessful normal start), or a checkpoint ID (indicating the checkpoint ID fromwhich 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 DBretrieves 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 pathcommand, IMS DB places the number of the lowest-level segment retrieved. IfIMS DB is unable to find the segment you have requested, it gives the levelnumber of the last segment it encountered that satisfied your command. This isthe lowest segment on the last path that IMS DB encountered while searchingfor 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 whenyou use the KEYFEEDBACK option with get commands. If your key feedbackarea 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 theDL/I control block that contains all information used to describe a database. TheDIBDBDNM 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 rightwith blanks. The DIBDBORG field is returned only on a QUERY command.

Defining a Key Feedback AreaTo retrieve the concatenated key of a segment, you must define an area into whichthe key is placed. The concatenated key returned is that of the lowest-levelsegment retrieved. (The segment retrieved is indicated in the DIB by the DIBSEGMand DIBSEGLV fields.)

Specify the name of the area using the KEYFEEDBACK option on a GETcommand.

A concatenated key is made up of the key of a segment, plus the keys for all of itsparents. For example, say you requested the concatenated key of the ILLNESSsegment for January 2, 1988, for patient number 05142. The following would bereturned 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 AreasYou use I/O areas to pass segments back and forth between your program and thedatabase. What an I/O area contains depends on the kind of command you areissuing:

v When you retrieve a segment, DL/I places the segment you requested in the I/Oarea.

v When you add a new segment, you build the new segment in the I/O area beforeissuing 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

The I/O area must be long enough to contain the longest segment you retrieve fromor add to the database. (Otherwise, you might experience storage overlap.) If youare retrieving, adding, or replacing multiple segments in one command, you mustdefine an I/O area for each segment.

As an example of what a segment looks like in your I/O area, say that you retrievedthe 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 likethis:19880303STREPTHROA

The language coding formats follow:

COBOL I/O AreaThe I/O area in a COBOL program should be defined as a 01 level working storageentry. 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 afixed-length character string, a major structure, a connected array, or an adjustablecharacter string. It cannot be the name of a minor structure or a character stringwith the attribute VARYING. If you want to define it as a minor structure, you canuse a pointer to the minor structure as the parameter.

Your program should define the I/O area as a fixed-length character string and passthe name of that string, or define it in one of the other ways mentioned above andthen pass the pointer variable that points to that definition. If you want to usesubstructures 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 0CL90KEY DS CL6FIELD DS CL84

Defining I/O Areas


Chapter 4. More about Writing Your Application Program

This chapter provides programming guidelines and information on preparingprograms for execution using EXEC DLI commands. It also contains skeletonprograms in assembler language, COBOL, PL/I, C, and C++.

Programming GuidelinesThis description provides some guidelines for writing efficient and error-freeprograms

The number, type, and sequence of the DL/I requests your program issues affectthe efficiency of your program. A program that is poorly designed runs if it is codedcorrectly. The suggestions that follow can help you develop the most efficient designpossible for your application program. Inefficiently designed programs can adverselyaffect performance and are hard to change. Being aware of how certaincombinations of commands or calls affects performance helps you to avoid theseproblems and design a more efficient program.

Once you have a general sequence of calls mapped out for your program, look overthe guidelines on sequence below to see if you can improve the sequence. Usuallyan 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 donot use more qualification than required.

v Use the request or sequence of requests that gives DL/I the shortest path to thesegment you want.

v Use the fewest number of requests possible in your program. Each DL/I requestyour program issues uses system time and resources. You may be able toeliminate unnecessary calls by:

– Using path requests if you are replacing, retrieving, or inserting more than onesegment 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 aseparate I/O area, and then gets it from that I/O area the second time it needsthe segment. If your program retrieves the same segment more than onceduring program execution, you are issuing an unnecessary request.

– Anticipating and eliminating needless and nonproductive requests, such asrequests that result in GB, GE, and II status codes. For example, if you areissuing GNs for a particular segment type and you know how manyoccurrences of that segment type exist, do not issue the GN that results in aGE status code. You can keep track of the number of occurrences yourprogram retrieves, and then continue with other processing when you knowyou have retrieved all the occurrences of that segment type.

– Issuing an insert request with a qualification for each parent instead of issuingGet requests for the parents to make sure that they exist. When you areinserting segments, you cannot insert dependents unless the parents exist. IfDL/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 toconditional routines, such as error and print routines, in other parts of theprogram, instead of having to branch around them to continue normalprocessing.


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 movingbackward in the hierarchy.

v Process database records in order of the key field of the root segments. (ForHDAM 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 commandsor calls in a way that depends heavily on the database structure. Depending onthe current structure of the hierarchy reduces the program’s flexibility.

Coding a Program in Assembler LanguageThe following is a sample CICS online program written in assembler language. Itshows you how the different parts of a command-level program fit together, andhow the EXEC DLI commands are coded.

Except for a few commands, the program shown below applies to batch, BMP, andCICS programs. Differences are highlighted in the notes that follow. The numbers tothe right of the sample code refer to those notes.

See the following assembler language sample code.*ASM XOPTS(CICS,DLI)* �1�R2 EQU 2R3 EQU 3R4 EQU 4R11 EQU 11R12 EQU 12R13 EQU 13DFHEISTG DSECTSEGKEYA DS CL4SEGKEYB DS CL4 �2�SEGKEYC DS CL4SEGKEY1 DS CL4SEGKEY2 DS CL4CONKEYB DS CL8SEGNAME DS CL8SEGLEN DS HPCBNUM DS HAREAA DS CL80AREAB DS CL80 �3�AREAC DS CL80AREAG DS CL250AREASTAT 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********************************************************************

Programming Guidelines


* 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)BAL R4,TESTDIB CHECK STATUS

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'BAL R4,TESTDIB CHECK STATUSB 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)BAL R4,TESTDIB CHECK STATUS

********************************************************************* 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) X�10�FIELDLENGTH(4) XINTO(AREAA) XSEGLENGTH(80) XSEGMENT(SEGB) WHERE(KEYB=SEGKEYB) FIELDLENGTH(4) XINTO(AREAB) XSEGLENGTH(80) XSEGMENT(SEGC) WHERE(KEYC=SEGKEYC) FIELDLENGTH(4) XINTO(AREAC) XSEGLENGTH(80)

BAL R4,TESTDIB* UPDATE FIELDS IN THE 3 SEGMENTS

EXEC DLI REPL USING PCB(1) XSEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80) XSEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80) XSEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80)

BAL R4,TESTDIB CHECK STATUS********************************************************************* 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) XSEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80)

BAL R4,TESTDIB CHECK STATUS

Coding a Program in Assembler Language

Chapter 4. More about Writing Your Application Program 75

********************************************************************* RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY* AND THEN DELETE IT AND ITS DEPENDENTS********************************************************************

MVC CONKEYB,=C'A200B230'EXEC DLI GU USING PCB(1) X

SEGMENT(SEGB) XKEYS(CONKEYB) KEYLENGTH(8) XINTO(AREAB) SEGLENGTH(80)

BAL R4,TESTDIB CHECK STATUSEXEC DLI DLET USING PCB(1) X

SEGMENT(SEGB) SEGLENGTH(80) FROM(AREAB)BAL R4,TESTDIB CHECK STATUS

********************************************************************* 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 CONKEYB,=C'A200B230'MVC SEGNAME,=CL8'SEGA'MVC SEGLEN,=H'80'MVC PCBNUM,=H'1'EXEC DLI GU USING PCB(PCBNUM) X

SEGMENT((SEGNAME)) XKEYS(CONKEYB) KEYLENGTH(8) SETPARENT XSEGMENT(SEGC) INTO(AREAC) SEGLENGTH(SEGLEN) XWHERE(KEYC='C520')

BAL R4,TESTDIB CHECK STATUS********************************************************************* RETRIEVE DATABASE STATISTICS********************************************************************

EXEC DLI STAT USING PCB(1) INTO(AREASTAT) XVSAM FORMATTED LENGTH(360)

BAL R4,TESTDIB CHECK STATUS********************************************************************* 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) XWHERE(KEYA > SEGKEY1 AND KEYA < SEGKEY2KEYA > 'A275' AND KEYA < 'A350')

BAL R4,TESTDIB CHECK STATUS********************************************************************* 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 RETURNERRORS EQU ** HANDLE ERROR CONDITIONS*ABENDS EQU ** HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES*

END

Notes to the sample Assembler code:

�1�For a CICS online program containing EXEC DLI commands, you mustspecify the DLI and CICS options. For a batch or BMP program containingEXEC DLI, you must specify only the DLI option.

�2�For reentrancy, define each of the areas the program uses—I/O areas, keyfeedback areas, and segment name areas in DFHEISTG.

�3�Define an I/O area for each segment you retrieve, add, or replace (in asingle command).

�4�For a batch or BMP program containing EXEC DLI, you must save registerson entry and restore registers on exit according to MVS register-savingconventions.

�5�In a batch or BMP program, a DFHEIENT saves the registers on entry. Donot specify the EIBREG parameter in a batch program.

�6�Do not code EXEC CICS commands in a batch or BMP program.

�7�In a CICS online program, use the SCHD PSB command to obtain a PSB forthe use of your program. Do not schedule a PSB in a batch or BMP program.

�8�This 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 anassembler language program.

�9�This GNP command retrieves all dependents under segment SEGA. The GEstatus code indicates that no more dependents exist.

�10�This GU command is an example of a path command. Use a separate I/Oarea for each segment you retrieve.

�11�In a CICS online program, the TERM command terminates the PSBscheduled earlier. You do not terminate the PSB in a batch or BMP program.

�12�For a batch or BMP program, code DFHEIRET with an optional RCREGparameter instead of EXEC CICS RETURN. The RCREG parameter identifies aregister containing the return code.

�13�After issuing each command, you should check the status code in the DIB.



Coding a Program in COBOLThe following is a sample program written for COBOL. It shows you how thedifferent parts of a command-level program fit together, and how the EXEC DLIcommands 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).

Except for a few commands, the program shown below applies to batch, BMP, andCICS programs. Differences are highlighted in the notes that follow. The numbers tothe 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 SEGKEY2 PIC X(4).77 SEGKEY3 PIC X(4).77 SEGKEY4 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 AREA01 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* ***************************************************************

Coding a Program in COBOL


*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.PERFORM TEST-DIB THRU OK.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.PERFORM TEST-DIB THRU OK.

** **************************************************************** 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)


* UPDATE FIELDS IN THE 3 SEGMENTSEXEC DLI REPL USING PCB(1)

SEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80)SEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80)SEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80)


** **************************************************************** 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)SEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80)


** **************************************************************** RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY* AND THEN DELETE IT AND ITS DEPENDENTS* ***************************************************************



*MOVE 'A200B230' TO CONKEYB.EXEC DLI GU USING PCB(1)

SEGMENT(SEGB)KEYS(CONKEYB) KEYLENGTH(8)INTO(AREAB) SEGLENGTH(80)

END-EXEC.PERFORM TEST-DIB THRU OK.EXEC DLI DLET USING PCB(1)

SEGMENT(SEGB) SEGLENGTH(80) FROM(AREAB) END-EXEC.PERFORM TEST-DIB THRU OK.

** ***************************************************************

* 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 'A200B230' TO CONKEYB.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.

PERFORM TEST-DIB THRU OK.** **************************************************************** RETRIEVE DATABASE STATISTICS* ****************************************************************

EXEC DLI STAT USING PCB(1) INTO(AREASTAT)VSAM FORMATTED LENGTH(360) END-EXEC.

PERFORM TEST-DIB THRU OK.** **************************************************************** RETRIEVE ROOT SEGMENT USING BOOLEAN OPERATORS* ****************************************************************

MOVE 'A050' TO SEGKEY1.MOVE 'A150' TO SEGKEY2.MOVE 'A275' TO SEGKEY3.MOVE 'A350' TO SEGKEY4.EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA)

SEGLENGTH(80) FIELDLENGTH(4,4,4,4)WHERE(KEYA > SEGKEY1 AND KEYA < SEGKEY2 OR

KEYA > SEGKEY3 AND KEYA < SEGKEY4)END-EXEC.PERFORM TEST-DIB THRU OK.

** ***************************************************************

* 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 CONDITIONSABENDS.* HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES

Notes to the sample COBOL code:

�1�For a CICS online program containing EXEC DLI commands, you mustspecify the DLI and CICS options. Fora batch or BMP program containing EXECDLI, you must specify only the DLI option.

�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.

�3�Define an I/O area for each segment you retrieve, add, or replace (in asingle command).


�5�For 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.

�6�This GU command retrieves the first occurrence of SEGA with a key of A300.KEYLENGTH and SEGLENGTH are optional for IBM COBOL for MVS & VM(and VS COBOL II). For COBOL V4 and OS/VS COBOL, KEYLENGTH andSEGLENGTH are required.

�7�This GU command is an example of a path command. You must use aseparate I/O area for each segment you retrieve.

�8�For a CICS online program, the TERM command terminates the PSBscheduled earlier. You do not terminate the PSB in a batch or BMP program.


Coding a Program in PL/IThe following is a sample program written in PL/I. It shows you how the differentparts of a command-level program fit together, and how the EXEC DLI commandsare coded.

Except for a few commands, the program shown below applies to batch, BMP, andCICS programs. Differences are highlighted in the notes that follow. The numbers tothe 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 SEGKEY2 CHAR (4);DCL SEGKEY3 CHAR (4);DCL SEGKEY4 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';EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA)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';EXEC DLI GU USING PCB(1)

Coding a Program in PL/I


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';EXEC DLI ISRT USING PCB(1)

SEGMENT(SEGB) KEYS(CONKEYB)SEGMENT(SEGC) FROM(AREAC);

CALL TEST_DIB;/* *//* ************************************************************ *//* RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY *//* AND THEN DELETE IT AND ITS DEPENDENTS *//* ************************************************************ *//* */CONKEYB = 'A200B230';EXEC DLI GU USING PCB(1)

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 *//* ************************************************************* *//* */CONKEYB = 'A200B230';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';SEGKEY2 = 'A150';SEGKEY3 = 'A275';SEGKEY4 = 'A350';EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA)

WHERE(KEYA &Ar; SEGKEY1 AND KEYA &Al; SEGKEY2 ORKEYA &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:

�1�For a CICS online program containing EXEC DLI commands, you mustspecify the DLI and CICS options. For a batch or BMP program containingEXEC DLI, you must specify only the DLI option.

�2�Define, in automatic storage, each of the areas; I/O areas, key feedbackareas, and segment name areas.

�3�Define an I/O area for each segment you retrieve, add, or replace in a singlecommand.


�5�For 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.



�6�This GU command retrieves the first occurrence of SEGA with a key of A300.Notice that you do not need to include the KEYLENGTH and SEGLENGTHoptions.

�7�This GNP command retrieves all dependents under segment SEGA. The GEstatus code indicates that no more dependents exist.

�8�This GU command is an example of a path command. You must use aseparate I/O area for each segment you retrieve.

�9�For a CICS online program, the TERM command terminates the PSBscheduled earlier. You do not terminate the PSB in a batch or BMP program.


Coding a Program in CThe following is a sample program written in C. It shows you how the different partsof a command-level program fit together, and how the EXEC DLI commands arecoded.

Except for a few commands, the program shown below applies to batch, BMP, andCICS programs. Differences are highlighted in the notes that follow. The numbers tothe 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();

Coding a Program in C


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�INTO(&GNIOA) SEGLENGTH(60);

strcpy(OUTLIN2.OUTLINA,"SE2ORDER=");strcpy(OUTLIN2.OUTLINB,GNIOA);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();EXEC DLI ISRT USING PCB(2)

SEGMENT(SE2ORDER)FROM(&ISRTIOA) SEGLENGTH(60);

SENDSTAT();if (strncmp(dibptr->dibstat,"II",2) == 0)

strncpy(dibptr->dibstat," ",2);TESTDIB();


strcpy(OUTLINE,GN1);SENDLINE();EXEC DLI GET NEXT USING PCB(2) �12�

SEGMENT(SE2ORDER)INTO(&GNIOA) SEGLENGTH(60);


/* *//* GET INSERTED SEGMENT TO BE REPLACED *//* */


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();


strcpy(OUTLINE,GN1);SENDLINE();EXEC DLI GET NEXT USING PCB(2) �15�

SEGMENT(SE2ORDER)INTO(&GNIOA) SEGLENGTH(60);


/* *//* GET REPLACED SEGMENT *//* */


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 FORMATTEDINTO(&STATAREA);

SENDSTT2();TESTDIB();

/* *//* ISSUE TERM REQUEST *//* */

strcpy(OUTLINE,TERM);SENDLINE();EXEC DLI TERM; �19�SENDSTAT();TESTDIB();strcpy(OUTLINE,DIVIDER);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 SEND FROM(OUTLIN3) LENGTH(120);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 SEND FROM(OUTLIN2) LENGTH(11);EXEC CICS WRITEQ TD QUEUE("PRIM") FROM(OUTLIN2) LENGTH(L11);strcpy(OUTLINE,DIVIDER);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:

�1�You must include a standard header file string.h to gain access to stringmanipulation facilities.

�2�You must include standard header file stdio.h to gain access to standard I/Olibrary routings.

�3�Define DL/I messages.

�4�Define the I/O areas.

�5�Program start.

�6�Define PSB PC3COCHD.

�7�Issue the first command. Retrieves the first occurrence of segmentSE2ORDER and puts it into array OUTLIN2.

�8�Issue the GNP command to get the next segment and put it into arrayOUTLIN2.

�9�GE status codes indicate no more segments to get.

�10�Get next segment SE2ORDER and put it into the array OUTLIN2.

�11�Insert segment into array OUTLIN3.

�12�Issue GN to retrieve next segment and put it into array OUTLIN2.

�13�Get next segment that will be replaced and put it into OUTLIN3.

�14�Replace the segment and put it into array OUTLIN3.

�15�Get next segment and put it into array OUTLIN2.

�16�Get the replaced segment and put it into array OUTLIN3.



�17�Issue DELETE command after putting content of segment into arrayOUTLIN3.

�18�Issue STAT REQUEST command.

�19�Issue TERM command.

�20�Output processing.

�21�Check return code.


Preparing Your EXEC DLI Program for ExecutionThe steps for preparing your program for execution are as follows:

1. Run the CICS command language translator to translate the EXEC DLI andEXEC CICS commands. COBOL, PL/I, and assembler language programs haveseparate 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 yourprogram. The procedure you use depends on the type of program (batch, BMP, orCICS online) and the language it is written in (COBOL, PL/I, or assemblerlanguage).

Translator Options Required for EXEC DLI

Even when you use the CICS-supplied procedures for preparing your program, youmust supply certain translator options.

For a CICS online program containing EXEC DLI commands, you must specify theDLI and CICS options. For a batch or BMP program containing EXEC DLIcommands, you must specify the DLI option.

You can also specify the options on the EXEC job control statement that invokesthe translator; if you use both methods, the CBL and *PROCESS statementoverrides those in the EXEC statement. For more information on the translatoroptions, see CICS/ESA Application Programming Guide.

You must ensure that the translator options you use in a COBOL program do notconflict with the COBOL compiler options. When you translate an IBM COBOL forMVS & 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 IItranslator option.

Compiler Options Required for EXEC DLIIf you want to compile your batch COBOL program with COBOL for MVS & VM andthen execute it AMODE(31) on MVS, you must use the compiler option RENT. Ifyou want to compile your batch COBOL program with VS COBOL II and thenexecute 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, seeCICS Application Programming Reference.



Linkage Editor Options Required for EXEC DLI

If the compiler being used supports it, you can link a program written with EXECcommands as AMODE(31) RMODE(ANY).

Preparing your Program for Execution


Chapter 5. Processing Fast Path Databases

Using EXEC DLI commands under DBCTL, a CICS program or a batch-orientedBMP can access DEDBs. Parameters allow your program to use facilities of theDEDBs such as subset pointers, described below.

A DEDB contains a root segment and as many as 127 types of dependentsegment. One of these types can be a sequential dependent; the other 126 aredirect dependents. Sequential dependent segments are stored in chronologicalorder. Direct dependent segments are stored hierarchically.

DEDBs provide high data availability. Each DEDB can be partitioned, or divided intomultiple “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 onecopy of an area, application programs can access the data by using another copyof that area. This is transparent to the application program. When an error occurs todata in a DEDB, IMS does not stop the database. It makes the data in errorunavailable, but continues to schedule and process application programs. Programsthat 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 ofthe same rules apply. IMS systems can share DEDBs at the area level (instead ofat the database level as with full-function databases), or at the block level.

Related Reading: For more information on DEDB data sharing, see the descriptionof administering IMS systems that share data in IMS Version 7 AdministrationGuide: System.

Processing DEDBs with Subset PointersSubset pointers and the options you use with them are optimization tools thatsignificantly improve the efficiency of your program when you need to process longsegment chains. Subset pointers divide a chain of segment occurrences under thesame parent into two or more groups, or subsets. You can define as many as eightsubset pointers for any segment type. You then define the subset pointers fromwithin an application program (see “Using Subset Pointers” on page 95). Eachsubset 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 segmentoccurrences from the first four. Your program could then refer to that subset pointerthrough 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 theroot level. Subset pointers used for the root level are ignored.

Figure 11 and Figure 12 show some of the ways you can set subset pointers.Subset pointers are independent of one another, which means that you can set oneor more pointers to any segment in the chain. For example, you could set morethan one subset pointer to a segment, as shown in Figure 11.

Alternatively, you could define a one-to-one relationship between the pointers andthe segments, as shown in Figure 12.

Figure 13 on page 94 shows how the use of subset pointers divides a chain ofsegment occurrences under the same parent into subsets. Each subset ends withthe last segment in the entire chain. For example, the last segment in the subsetdefined by subset pointer 1 is B7.

Before You Use Subset PointersFor your program to use subset pointers, the pointers must be defined in the DBDfor the DEDB, and in your program’s PSB:

Figure 11. Examples of Setting Subset Pointers

Figure 12. More Examples of Setting Subset Pointers

Figure 13. How Subset Pointers Divide a Chain into Subsets

Processing DEDBs with Subset Pointers


v In the DBD, you specify the number of pointers for a segment chain. You canspecify as many as eight pointers for any segment chain.

v In the PSB, you specify which pointers your program uses; you define this on theSENSEG statement. (Each pointer is defined as an integer from 1 to 8.) You alsospecify on the SENSEG statement whether your program can set the pointers ituses. If your program has read-only sensitivity, it cannot set pointers, but canonly retrieve segments using subset pointers already set. If your program hasupdate 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 canset the pointers to segments in a chain. When an application program finishesexecuting, the subset pointers used by that program remain as they were set by theprogram and are not reset.

Designating Subset Pointers You Want to UseTo use subset pointers in your program, you must know the numbers for thepointers as they were defined in the PSB. Then, when you use the subset pointeroptions, you specify the number for each subset pointer you want to useimmediately after the option; for example, you would use P3 to indicate that youwant to retrieve the first segment occurrence in the subset defined by subsetpointer 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 toyour 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. Currentposition is at the current segment.

Our Sample ApplicationThe examples in this section are based on a sample application, the recording ofbanking transactions for a passbook account. The transactions are written to adatabase as either posted or unposted, depending on whether they were posted tothe customer’s passbook. For example, when Bob Emery does business with thebank, but forgets to bring in his passbook, an application program writes thetransactions to the database as unposted. The application program sets a subsetpointer to the first unposted transaction, so it can be easily accessed later. The nexttime Bob remembers to bring in his passbook, a program posts the transactions.The program can directly retrieve the first unposted transaction using the subsetpointer that was previously set. After the program has posted the transactions, itsets the subset pointer to zero; an application program that subsequently updatesthe database can determine that no unposted transactions exist. Figure 14 onpage 96 summarizes the processing performed when the passbook is unavailableand when it is available.


Chapter 5. Processing Fast Path Databases 95

Retrieving the First Segment in the Subset with the GETFIRSTOption

To retrieve the first segment occurrence in the subset, your program issues a Getcommand with the GETFIRST option. The GETFIRST option does not set or movethe pointer, but indicates to IMS that you want to establish position on the firstsegment 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 entiresegment chain.

Using the passbook account example described earlier, say that Bob Emery visitsthe bank, bringing his passbook, and you want to post all the unpostedtransactions. Because subset pointer 1 was previously set to the first unpostedtransaction, your program could use the following command to retrieve thattransaction:EXEC DLI GU SEGMENT(A) WHERE(AKEY = 'A1')

SEGMENT(B) INTO(BAREA) GETFIRST('1');

As shown by Figure 15 on page 97, this command retrieves segment B5. Tocontinue processing segments in the chain, you can issue Get Next commands, asyou would if you were not using subset pointers.

Figure 14. Processing Performed for the Sample Passbook Example



If the subset does not exist (subset pointer 1 has been set to zero), IMS returns aGE status code, and your position in the database immediately follows the lastsegment in the chain. Using the passbook example, the GE status code indicatesthat no unposted transactions exist.

You can specify only one GETFIRST option per qualification statement; if you usemore than one GETFIRST in a qualification statement, IMS returns an AJ statuscode 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 beenestablished on the first segment in the subset.

3. If you use GETFIRST with LAST, the last segment in the segment chain isretrieved.

4. If the subset pointer specified with GETFIRST is not set, IMS returns a GEstatus code, not the last segment in the segment chain. See “Setting the SubsetPointers with the SETZERO, MOVENEXT, SET, and SETCOND Options”

5. Do not use GETFIRST with FIRST. This causes you to receive an AJ statuscode.

6. GETFIRST overrides all insert rules, including LAST.

Setting the Subset Pointers with the SETZERO, MOVENEXT, SET,and SETCOND OptionsThe SETZERO, MOVENEXT, SET, and SETCOND options allow you to redefinesubsets by modifying the subset pointers. Before your program can set a subsetpointer, it must establish a position in the database. A command must be fullysatisfied before a subset pointer is set. The segment a pointer is set to depends onyour current position at the completion of the command. If a command to retrieve asegment is not completely satisfied, and a position is not established, the subsetpointers 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 yourprogram issues a command with the SETZERO option, the pointer is no longerset to a segment; the subset defined by that pointer no longer exists. (IMSreturns a status code of GE to your program if you try to use a subset pointerhaving a value of zero.)

Using the passbook example described earlier, say that you used the GETFIRSToption to retrieve the first unposted transaction. You would then process thechain of segments, posting the transactions. After posting the transactions and

Figure 15. Retrieving the First Segment in a Chain of Segments



inserting any new ones into the chain, you would use the SETZERO option to setthe 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 aprogram updating the database later on that no unposted transactions exist.

v Moving the subset pointer forward to the next segment after your currentposition: MOVENEXT

To move the subset pointer forward to the next segment after your currentposition, your program issues a command with the MOVENEXT option. Using thepassbook account example described earlier, say that you wanted to post someof the transactions, but not all, and that you wanted the subset pointer to be setto the first unposted transaction. The following command sets subset pointer 1 tosegment B6, as shown in Figure 16.EXEC DLI GU SEGMENT(A) WHERE(AKEY = 'A1')

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.

v Setting the subset pointer unconditionally: SET

You use the SET option to set a subset pointer. The SET option sets a subsetpointer unconditionally, regardless of whether or not it is already set. When yourprogram issues a command that includes the SET option, IMS sets the pointer toyour current position.

For example, to retrieve the first B segment occurrence in the subset defined bysubset pointer 1, and to reset pointer 1 at the next B segment occurrence, youwould issue the following commands:EXEC DLI GU SEGMENT(A) WHERE(AKEY = 'A1')

SEGMENT(B) INTO(BAREA) GETFIRST('1');EXEC DLI GN SEGMENT(B) INTO(BAREA) SET('1');

Figure 16. Moving the Subset Pointer to the Next Segment after Your Current Position



After you have issued these commands, instead of pointing to segment B5,subset pointer 1 points to segment B6, as shown in Figure 17.

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 subsetpointer is not already set to a segment.

Using the passbook example, say that Bob Emery visits the bank and forgets tobring his passbook; you add the unposted transactions to the database. You wantto set the pointer to the first unposted transaction, so later, when you post thetransactions, you can immediately access the first one. The following commandsets the subset pointer to the transaction you are inserting, if it is the firstunposted one:EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1')

SEGMENT(B) FROM(BAREA) SETCOND('1');

As shown by Figure 18 on page 100, this command sets subset pointer 1 tosegment B5. If unposted transactions already existed, the subset pointer is notchanged.

Figure 17. Unconditionally Setting the Subset Pointer to Your Current Position



Figure 18. Conditionally Setting the Subset Pointer to Your Current Position



Inserting Segments in a SubsetWhen you use the GETFIRST option to insert an unkeyed segment in a subset, thenew segment is inserted before the first segment occurrence in the subset.However, the subset pointer is not automatically set to the new segmentoccurrence. For example, the following command inserts a new B segmentoccurrence in front of segment B5, but does not set subset pointer 1 to point to thenew B segment occurrence:EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1')

SEGMENT(B) FROM(BAREA) GETFIRST('1');

To set subset pointer 1 to the new segment, you use the SET option along with theGETFIRST option, as shown in the following example:EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1')

SEGMENT(B) FROM(BAREA) GETFIRST('1') SET ('1');

If the subset does not exist (subset pointer 1 has been set to zero), the segment isadded to the end of the segment chain.

Deleting the Segment Pointed to By a Subset PointerIf you delete the segment pointed to by a subset pointer, the subset pointer pointsto the next segment occurrence in the chain. If the segment you delete is the last inthe chain, the subset pointer is set to zero.

Combining OptionsYou can use the SET, MOVENEXT, and SETCOND options with other options, andyou can combine subset pointer options with each other, provided they do notconflict. For example, you can use GETFIRST and SET together, but you cannotuse SET and SETZERO together because their functions conflict. If you combineoptions that conflict, IMS returns an AJ status code to your program.

You can use one GETFIRST option per qualification statement, and one updateoption (SETZERO, MOVENEXT, SET, or SETCOND) for each subset pointer.

Subset Pointer Status CodesIf you make an error in a qualification statement that contains subset pointeroptions, 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 pointersdefined in the DBD.

The subset options included in the qualification statement are in conflict; forexample, if one qualification statement contained a SET option and aSETZERO option for the same subset pointer, IMS would return an AJstatus code. S means to set the pointer to current position; Z means to setthe pointer to zero. You cannot use these options together in onequalification statement.

The qualification statement included more than one GETFIRST option.

The pointer number following a subset pointer option is invalid. You eitherdid not include a number, or included an invalid character. The numberfollowing the option must be between 1 and 8, inclusive.

AM The subset pointer referenced in the qualification statement was notspecified in the program’s PSB. For example, if your program’s PSB



specifies that your program can use subset pointers 1 and 4, and yourqualification statement referenced subset pointer 5, IMS would return an AMstatus 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 pointerupdate sensitivity.

The POS CommandYou can use the POS command (only with DEDBs) to do the following:

v Retrieve the location of a specific sequential dependent segment, or retrieves thelocation of the last inserted sequential dependent segment.

v Tell you the amount of unused space within each DEDB area. For example, youcan use the position information that IMS returns for a POS command to scan ordelete 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 unchangedand the status code FH is returned.

Locating a Specific Sequential Dependent

When you have position on a particular root segment, you can retrieve the positioninformation and the area name of a specific sequential dependent of that root. Ifyou have a position established on a sequential dependent segment, the searchstarts from that position. IMS returns the position information for the first sequentialdependent segment that satisfies the command.

To retrieve this information, you issue a POS command with a qualification statementcontaining the segment name of the sequential dependent. The current positionafter 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:

LL A 2-byte field giving the total length of the data in the I/O area, inbinary.

Area Name An 8-byte field giving the ddname from the AREA statement.

Position An 8-byte field containing the position information for the requestedsegment.

If the sequential dependent segment that is the target of the POScommand is inserted in the same synchronization interval, noposition information is returned. Bytes 11-18 contain X'FF'; otherfields contain normal data.

Unused CIs A 4-byte field containing the number of unused CIs in the sequentialdependent part.

Unused CIs A 4-byte field containing the number of unused CIs in theindependent overflow part.

Locating the Last Inserted Sequential Dependent Segment

You can also retrieve the position information for the most recently insertedsequential dependent segment of a given root segment. To do this, you issue a POS



command with a qualification statement containing the root segment as thesegment name. The current position after this type of command follows the samerules 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 mostrecently inserted sequential dependent segment. This field containszeros provided no sequential dependent for this root exist.



Identifying Free SpaceTo retrieve the area name and the next available position within the sequentialdependent part from all online areas, you can issue an unqualified POS command.This type of command also retrieves the unused space in the independent overflowand 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 entrycontains 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 24bytes for each entry.


Position An 8-byte field giving the next available position within thesequential dependent part.



The P Processing OptionIf the P processing option has been specified (with the PROCOPT parameter) in thePCB for your program, a GC status code is returned to your program whenever acommand to retrieve or insert a segment causes a Unit of Work (UOW) boundary tobe crossed. For more information on the UOW for DEDBs, see IMS Version 7Administration Guide: Database Manager. Although crossing the UOW boundaryprobably has no particular significance for your program, the GC status codeindicates that this is a good time to issue a CHKP command. The advantages ofdoing this are:

v Your position in the database is kept. Issuing a CHKP normally causes position inthe database to be lost, and the application program has to reestablish positionbefore it can resume processing.

v Commit points occur at regular intervals.

The POS Command


When a GC status code is returned, no data is retrieved or inserted. In yourprogram, you can either:

v Issue a CHKP command, and resume database processing by reissuing thecommand that caused the GC status code.

v Ignore the GC status code and resume database processing by reissuing thecommand that caused the status code.

The POS Command


Chapter 6. Recovering Databases and Maintaining DatabaseIntegrity

This chapter describes the commands you can use to help recover data accessedby your program and maintain data integrity:

v The Basic Checkpoint command, CHKP, which you can use to issue checkpointsfrom a batch or BMP program

v The Symbolic Checkpoint command, SYMCHKP, which you can use to issuecheckpoints from a batch or BMP program and to specify data areas that can berestored when you restart your program

v The Extended Restart command, XRST, which you can use along with symboliccheckpoints to start or restart your batch or BMP program

v The rollback commands, ROLL and ROLB, which you can use to dynamically backout database changes from a batch or BMP program

v The managing-backout-points commands, SETS and ROLS, which you can use toset 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, seethe description “Using the I/O PCB, PSB, and PCB” on page 11, and the manualsIMS Version 7 Utilities Reference: System and IMS Version 7 ApplicationProgramming: Design Guide.

Issuing Checkpoints in a Batch or BMP ProgramThe two kinds of commands that allow you to make checkpoints are: the CHKP, orBasic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.

Batch programs can use either the Symbolic Checkpoint or the Basic Checkpointcommand.

Both checkpoint commands make it possible for you to commit your program’schanges to the database and to establish places from which the batch or BMPprogram can be restarted, in cases of abnormal termination.

Requirement: You must not use the CHKPT=EOV parameter on any DD statementto take an IMS checkpoint.

See IMS Version 7 Application Programming: Design Guide for an explanation ofwhen and why you should issue checkpoints in your program. Because bothcheckpoint commands cause a loss of database position at the time the commandis issued, you must reestablish position with a GU command or other methods.

You cannot reestablish position in the midst of nonunique keys or nonkeyedsegments.

Issuing the CHKP CommandWhen you issue a CHKP command, you must provide the code for restarting yourprogram and you must 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 theactual ID, enclosed in single quotes. For example, either of the following commandsis valid:EXEC DLI CHKP ID(chkpid);

EXEC DLI CHKP ID('CHKP0007');

Issuing the SYMCHKP CommandThe SYMCHKP command in batch and BMP programs:

v Works with the Extended Restart (XRST) command to restart your program if itterminates abnormally. which are restored when your program is restarted. Youcan 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 PositionPrograms that issue Symbolic Checkpoint commands must also issue the ExtendedRestart (XRST) command. You must issue XRST once, as the first command in theprogram. You can use the XRST command to start your program normally, or torestart it in case of an abnormal termination. You can restart your program from oneof the following:

v A specific checkpoint ID

v A time/date stamp

Because the XRST command attempts to reposition the database, your program alsoneeds to check for correct position.

Backing Out Database Updates Dynamically: The ROLL and ROLBCommands

When a batch program determines that some of its processing is invalid, the ROLLand ROLB commands make it possible for the program to remove the effects of itsinaccurate processing.

You can use both ROLL and ROLB in batch programs. You can only use the ROLBcommand in batch programs if the system log is stored on direct access storageand 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 yourprogram has made to the database since its last checkpoint, or since the beginningof the program if your program has not issued a checkpoint.

Using Intermediate Backout Points: The SETS and ROLS CommandsUse the SETS and ROLS commands to define multiple points at which to preserve thestate of DL/I full-function databases and to return to these points later. (Forexample, you can use them to allow your program to handle situations that canoccur when PSB scheduling complete without all of the referenced DL/I databasesbeing 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 thanfull-function databases (VSAM files, for example), the SETS and ROLS requests have

Issuing Checkpoints


no effect on the non-DL/I resources. The backout points are not CICS commitpoints; they are intermediate backout points that apply only to DBCTL resources.Your program must ensure the consistency of all the resources involved.

SETS CommandBefore initiating a set of DL/I requests to perform a function, you can use a SETScommand to define points in your application at which to preserve the state of DL/Idatabases. Your application can issue a ROLS command later if it cannot completethe function.

ROLS CommandYou can use the ROLS command to back out to the state all full-function databaseswere in before either a specific SETS request or the most recent commit point.

Intermediate Backout Points

Chapter 6. Recovering Databases and Maintaining Database Integrity 107

Intermediate Backout Points


Chapter 7. Using Data Availability Enhancements

Your program might fail when it receives a status code indicating that a DL/Ifull-function database is unavailable. To avoid this, you can use data availabilityenhancements. After a PSB has been scheduled in DBCTL, your applicationprogram can issue requests to indicate to IMS that the program can handle dataavailability status codes and to obtain information about the availability of eachdatabase.

Accepting Database Availability Status CodesThese status codes occur because PSB scheduling was completed without all ofthe referenced databases being available. Use ACCEPT to tell DBCTL to return astatus 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 thefollowing 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 firstdatabase call. If the program has already issued a call using a DB PCB, then theQUERY command must follow the REFRESH command:EXEC DLI REFRESH DBQUERY

The REFRESH command updates the information in the DIB. You can only issue thiscommand one time.

For full-function databases, the DIBSTAT should contain NA, NU, TH, or blanks. ForMSDBs and DEDBs, the DIBSTAT always contains blanks.

If a CICS command language translator has been used to translate the EXEC DLIcommands, then, in addition to data availability status, the DBDNAME will bereturned in the DIB field DIBDBDNM. Also, the name of the database organizationwill 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-LevelPrograms

This chapter summarizes some of the differences between command- and call-levelprograms. If you are already familiar with DL/I calls, but not with EXEC DLIcommands, this section will help you understand the commands and options youcan 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 acommand-level program, you use the LOAD command instead of the ISRT call toinitially load a database.

v Table 5 on page 114 compares the options you use with EXEC DLI commandswith the command codes you use with DL/I calls. For example, the LOCKEDoption performs the same function as a Q command code.

Table 3. DL/I Calls Available to IMS and CICS Command-Level Application Programs

Request Type


BatchBatch-


CHKP call (symbolic) Yes Yes No

CHKP call (basic) Yes Yes No

GSCD call2 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

ROLS call (Roll Back to SETS)3 Yes Yes Yes

ROLS call (Roll Back to Commit) Yes Yes Yes

SETS call3 Yes Yes Yes

STAT call4 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 afunction 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.


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 Qcommand code.

DLET call DLET command Delete segments from a database.

GU, GN, and GNPcalls

GU, GN, and GNPcommands1

Retrieve segments from a database.

GHU, GHN, andGHNP calls1

GU, GN, and GNPcommands1

Retrieve segments from a database for updating.

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 ROLBcommand

Dynamically back out changes.

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 orMSDBs) 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 programminginterface.


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 onsegment level to beretrieved or inserted.

Retrieve or insert a sequence of segments in a hierarchic path usingonly one request, instead of having to use a separate request for eachsegment. (Path call or command).

Comparing Command-Level and Call-Level Programs


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 whensearching for a particular segment occurrence. Disregarded for a rootsegment.

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 SEGMENToption for segments you donot want replaced.

Designate segments you do not want replaced, when replacingsegments after a get hold request. Usually used when replacing a pathof segments.

P SETPARENT Set parentage at a higher level than what it usually is (the lowesthierarchic level of the request).

Q LOCKCLASS, LOCKED Reserve a segment so that other programs are not able to update ituntil 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 commandlevel programs.

Limit the search for a segment to the dependents of the segmentoccurrence on which position is established.

V CURRENT option Use the current position at this hierarchic level and above asqualification 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-levelequivalent.

Null. Use an SSA in command code format without specifying thecommand code. Can be replaced during execution with the commandcodes 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 informationis divided into two parts:

v Status code tables

– Database Calls

– Message Calls

– System Service Calls

v Status code explanations

Status Code TablesThe status code tables briefly explain each status code and list the calls for whichyou can receive each status code. The tables also include a column of numbersrepresenting the category of each status code; the numbers and the correspondingexplanations 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 onpage 124, they do not receive status codes.

Categories of DL/I Status CodesThe numbers in the category column of the status codes tables refer to thefollowing 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 tothe I/O area. The call is completed.

3. Those indicating warning status codes on successful calls when data is notreturned to the I/O area. The call is completed.

4. Those indicating improper user specifications. Most status codes are in thiscategory. The call is not completed.

5. Those indicating system, I/O, or security errors encountered during theexecution of I/O requests. The call is not completed.

6. Those indicating unavailable data.

Table 6. Database Calls

PCBStatusCode C

LS

E(G

SA

M)

DE

QG

U,

GH

UG

N,

GH

NG

NP,

GH

NP

DL

ET,

RE

PL

ISR

T(L

OA

D)

ISR

T(A

DD

)

FL

D

PO

S

OP

EN

(GS

AM

)

QU

ER

Y

RE

FR

ES

H

TE

RM

Cat

ego

ry

Description

AB X X X X X X X X X X 4 Segment I/O area required;none specified in call. Onlyapplies to full-function DEQcalls.

AC X X X X X X 4 Hierarchic error in SSAs.


Table 6. Database Calls (continued)

PCBStatusCode C

LS

E(G

SA

M)

DE

QG

U,

GH

UG

N,

GH

NG

NP,

GH

NP

DL

ET,

RE

PL

ISR

T(L

OA

D)

ISR

T(A

DD

)

FL

D

PO

S

OP

EN

(GS

AM

)

QU

ER

Y

RE

FR

ES

H

TE

RM

Cat

ego

ry

Description

AD X X X X X X X X X X 4 Function parameterincorrect. Only applies tofull-function DEQ calls.

AF X X 4 GSAM detected invalidvariable-length record.

AH X X 4 Required SSA missing.Options list not specified inSETO call.

AI X X X X X X 5 Data management OPENerror.

AJ X X X X X X X X 4 Incorrect parameter format inI/O area; incorrect SSAformat; incorrect commandused to insert a logical childsegment. I/O area length inAIB is invalid; incorrect classparameter specified in FastPath 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 compatiblewith processing option,segment sensitivity,transaction code, definition,or program type.

AO X X X X X X X 5 I/O error: OSAM, BSAM, orVSAM.

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 completedbecause data wasunavailable.

BB X X X X X 6 Call could not be completedbecause data wasunavailable and updates arebacked out only since thelast commit point.

BC X 6 Call could not be completedbecause of a deadlockoccurrence; updates arebacked out only since thelast commit point.

DA X X 4 Segment key field ornonreplaceable field hasbeen changed.

DJ X 4 No preceding successfulGHU or GHN call or an SSAsupplied at a level notretrieved.

Status Code Tables



PCBStatusCode C

LS

E(G

SA

M)

DE

QG

U,

GH

UG

N,

GH

NG

NP,

GH

NP

DL

ET,

RE

PL

ISR

T(L

OA

D)

ISR

T(A

DD

)

FL

D

PO

S

OP

EN

(GS

AM

)

QU

ER

Y

RE

FR

ES

H

TE

RM

Cat

ego

ry

Description

DX X 4 Violated delete rule.

EM X Normally for a utility.

FA X X 4 MSDB arithmetic overflowerror occurred.

FC X 4 POS call for directdependent 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 FWcodes.

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’sdependent region.

FM X X X X X X 4 Randomizing routine returncode = 4.

FN X 4 FSA error, field name.

FP X X X 4 Invalid hexadecimal ordecimal data.

FR X X X X X X X X 5 Total buffer allocationexceeded.

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 thannormally allowed. For theDEQ call, Fast Path was notable to release any buffers.

FY X X X X X X X X 4 Attempt to read sequentialdata preceding the currentposition.

GA X X 2 Crossing hierarchicalboundary.

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 forall levels above insert andhas lost segment position.

GE X X X X 1 Segment not found.

GG X X X 5 Segment contains invalidpointer.

Status Code Tables

Chapter 9. DL/I Status Codes 119


PCBStatusCode C

LS

E(G

SA

M)

DE

QG

U,

GH

UG

N,

GH

NG

NP,

GH

NP

DL

ET,

RE

PL

ISR

T(L

OA

D)

ISR

T(A

DD

)

FL

D

PO

S

OP

EN

(GS

AM

)

QU

ER

Y

RE

FR

ES

H

TE

RM

Cat

ego

ry

Description

GK X X 2 Crossing segmentboundaries on same level.

GL X 4 Invalid user log code. Onlyapplies to full-function DEQcalls.

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.

L2 X 1 The area lock failed.

LB X 1 Segment being loadedalready exists in database.

LC X 4 Key field of segments out ofsequence.

LD X 4 No parent for this segmenthas been loaded.

LE X 4 Sequence of siblingsegments not the same asDBD sequence.

LF X 4 An attempt was made toload a logical child segmentin either a HALDB PHDAMor PHIDAM database.

LS X 1 Work may be backed outbecause sufficient CI spacewas not preallocated for thearea, or the SDEP CI lockfailed.

NA X X 6 A database was unavailable.

NE X 3 DL/I call issued by indexmaintenance cannot findsegment.

NI X X X 1 Index maintenance foundduplicate segment in index.

NO X X X 5 I/O error: OSAM, BSAM, orVSAM.

NU X X 6 A database was unavailablefor update.

OS X Normally for a utility.

RX X 4 Violated replace rule.

TH X 4 No PSB was scheduled(command-level only).

TI X 4 Invalid path to segment(command-level only).

Status Code Tables


|||||||||||||||||||||


PCBStatusCode C

LS

E(G

SA

M)

DE

QG

U,

GH

UG

N,

GH

NG

NP,

GH

NP

DL

ET,

RE

PL

ISR

T(L

OA

D)

ISR

T(A

DD

)

FL

D

PO

S

OP

EN

(GS

AM

)

QU

ER

Y

RE

FR

ES

H

TE

RM

Cat

ego

ry

Description

X X X X X X 5 DL/I not active(command-level only).

X X X X X X 5 Invalid system DIB(command-level only).

TO X 4 Path replace error(command-level only).

TP X X X X X X 4 Invalid number for PCB orinvalid processing option(command-level only).

TR X X X X X X X X 4 CICS XDLIPRE user exitdetermined the precedingrequest should not beexecuted.

TY X X X X X X 5 Database not open(command-level only).

TZ X X X X X X 5 Length of segment greaterthan 64 KB.

UC X 1 Checkpoint taken (UtilityControl Facility (UCF) statuscode).

US X 1 Stop (UCF status code).

UX X 1 Checkpoint and stop (UCFstatus code).

V1 X X X 4 Segment length not withinlimits of DBDGEN.

V2 X X X X X X X X 4 Segment length invalid(command-level only).

V3 X X X X 4 Field length missing orinvalid (command-level only).

V4 X X X X X X 4 Length of variable-lengthsegment invalid(command-level only).

V5 X X X X X 4 Offset if invalid(command-level only).

V6 X X X X X 4 Concatenated key lengthinvalid (command-level only).

XX X X X X 5 Internal GSAM error.

bb1 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

PCBStatusCode A

UT

H

GU

GN

ISR

T

CH

NG

CM

D

GC

MD

PU

RG

SE

TO

Cat

ego

ry

Description

AA X X 4 CHNG call for alternate response PCB can specify onlylogical terminal destination; transaction code destinationspecified.

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 SETOcall.

AJ X 4 Invalid parameter format in I/O area; invalid SSA format;invalid command used to insert a logical child segment. I/Oarea 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 PCBis 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 processingoptions.

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 morethan one physical terminal assigned for input purposes. Notifymaster terminal operator.

AZ X 4 The conversational program has issued a PURG call to PCBthat cannot be purged.

A1 X X X 4 AUTH call attempted with invalid generic class name or erroroccurred during attempt to set destination name specified inthe CHNG or ISRT call.

A2 X 4 Call attempted with invalid PCB (PCB not modifiable or ISRToperation already done).

A3 X X 4 Call attempted to a modifiable TP PCB with no destinationset.

A4 X X X 4 Security violation detected during processing of either anAUTH call, a CHNG call, or an ISRT on a conversationalresponse.

A5 X X 4 Format name specified on second or subsequent messageISRT or PURG.

A6 X 4 Output segment size limit exceeded on call.

A7 X 4 Number of output segments inserted exceeded the limit byone. Any further queue manager calls are prohibited toprevent message queue overflow.

A8 X 4 ISRT to alternate response PCB followed ISRT to I/O PCB orvice versa.

A9 X 4 Alternate response PCB referenced by call requires that thesource physical terminal receive the output response.

CA X 4 No such command. No command responses produced.

Status Code Tables


Table 7. Message Calls (continued)

PCBStatusCode A

UT

H

GU

GN

ISR

T

CH

NG

CM

D

GC

MD

PU

RG

SE

TO

Cat

ego

ry

Description

CB X 4 Command, as entered, not allowed for AOI. No commandresponses produced.

CC X 2 Command executed. One or more command responsesproduced.

CD X 4 Entered command violates security. No command responsesproduced.

CE X 2 Transaction rescheduled after CMD call. Commit point hadnot 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. Transactionrescheduled. 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 beforeIMS last started.

CL X 2 Transaction from AOI exit routine. Message on queue beforeIMS last started. Message rescheduled. Commit point had notbeen reached.

CM X 3 Command executed. No command response produced.

CN X 4 IOASIZE= parameter on PSBGEN macro does not meetminimum requirement for CMD call.

E1 X X 4 The DFSMSCE0 user routing exit rejected the CHNG or ISRTcall.




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.

MR X – Reserved

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 ismessage text length plus four control characters).

Status Code Tables


Table 7. Message Calls (continued)

PCBStatusCode A

UT

H

GU

GN

ISR

T

CH

NG

CM

D

GC

MD

PU

RG

SE

TO

Cat

ego

ry

Description

QH X X X X 4 Terminal symbolic error; output designation unknown to IMS(logical terminals or transaction code). Either the messagesegment LL is not at least 5 bytes or the destination name inI/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(command-level only).

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 passingSPA by a program-to-program switch after answeringterminal.

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 bitsare 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 destinationset to a logical terminal, but was not defined asALTRESP=YES. MSC direct routing does not supportprogram-to-program switch between conversationaltransactions.

XG X 4 Current conversation requires fixed-length SPAs. Attempt wasmade 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 isnot a SPA.

X3 X 4 Invalid SPA.

X4 X 4 Insert to a transaction code PCB that is not conversationaland 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).

bb1 X X X X X X X X X 1 No status code returned. Proceed.

Note:


Table 8. System Service Calls

PCBStatusCode C

HK

P

INIT

INQ

YJA

VAS

YN

CL

OG

PC

B

RO

LB

RO

LL

RO

LS

SE

TS

SE

TU

SN

AP

1 STA

T2 S

YN

C

XR

ST

Cat

ego

ry

Description

AB X X X X X 4 Segment I/O area required; nonespecified in call.

Status Code Tables


Table 8. System Service Calls (continued)

PCBStatusCode C

HK

P

INIT

INQ

YJA

VAS

YN

CL

OG

PC

B

RO

LB

RO

LL

RO

LS

SE

TS

SE

TU

SN

AP

1 STA

T2 S

YN

C

XR

ST

Cat

ego

ry

Description

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 commandused 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 aTP 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 thePSB are unavailable or no databasePCBs are in the PSB.

BK X 6 At least one of the databases includedin the PSB is unavailable or haslimited availability, or at least one PCBreceived an NA or NU status code.

FA X X 4 MSDB arithmetic overflow erroroccurred.

FD X X 3 Deadlock occurred.


FH X X 3 DEDB inaccessible.

FI X X 4 I/O area not in user’s dependentregion.

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. Pleasesupply one.

NU X 6 A database was unavailable forupdate.

QC X 3 No more input messages exist.

QE X X 4 GN request before GU. GCMD requestbefore CMD.

QF X 4 Segment less than five characters(segment length is message textlength plus four control characters).

Status Code Tables



PCBStatusCode C

HK

P

INIT

INQ

YJA

VAS

YN

CL

OG

PC

B

RO

LB

RO

LL

RO

LS

SE

TS

SE

TU

SN

AP

1 STA

T2 S

YN

C

XR

ST

Cat

ego

ry

Description

RA X 4 Token does not match one for a SETS,or the PCB did not get BA or BB onlast call.

RC X 4 ROLS call issued with unsupportedPCBs in the PSB, or the program isusing an attached subsystem.

SA X 5 Insufficient space.

SB X 4 Would exceed maximum number oflevels allowed.

SC X X 5 A SETS/SETU call was issued withunsupported PCBs in the PSB, or theprogram is using an attachedsubsystem.

SY X 5 Internal error during sync-pointprocessing for an IMS/Javaapplication.

TA X 5 PSB not in PSB directory(command-level only).

TC X 4 PSB already scheduled(command-level only).

TE X 5 PSB initialization failed(command-level only).

TJ X 5 DL/I not active (command-level only).

TL X 4 Conflict in scheduling intent(command-level only).

TN X X X X X X X 5 Invalid system DIB (command-levelonly).

TP X X 4 Invalid number for PCB or invalidprocessing option (command-levelonly).

TR X X X X 4 CICS XDLIPRE user exit determinedthe preceding request should not beexecuted.

TY X X 5 Database not open (command-levelonly).

TZ X X 5 Length of segment greater than 64 KB.

V2 X 4 Segment length invalid(command-level only).

V7 X 4 Statistics area length invalid(command-level only).

XD X X 1 IMS terminating. Further DL/I callsmust not be issued. No messagereturned.

bb3 X X X X X X X X X X X X X 1 Good. No status code returned.Proceed.

Status Code Tables



PCBStatusCode C

HK

P

INIT

INQ

YJA

VAS

YN

CL

OG

PC

B

RO

LB

RO

LL

RO

LS

SE

TS

SE

TU

SN

AP

1 STA

T2 S

YN

C

XR

ST

Cat

ego

ry

Description

Notes:

1. SNAP is a Product-sensitive programming interface.



Status Code ExplanationsThis information appears in the three application programming guides. For EXECDL/I commands, all status codes, except those identified as being returned to theapplication 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.

AA

Explanation: IMS ignored a CHNG or ISRT call becausethe alternate response PCB that is referenced in the callspecified a transaction code as a destination. Analternate response PCB must have a logical terminalspecified as its destination.

Programmer Response: Correct the CHNG or ISRT call.

AB

Explanation: An I/O area is required as one of theparameters on this call, and the call did not specify one.After this status code is returned, your position in thedatabase is unchanged. AB only applies to full-functionDEQ calls.

Programmer Response: Correct the call by includingthe address of an I/O area as one of the callparameters.

AC

Explanation:

For call-level programs:

An error is in an SSA for a DLET, Get, ISRT, or REPL callfor one of these reasons:

v DL/I could not find a segment in the DB PCBspecified in the call that has the segment name givenin the SSA.

v The segment name is in the DB PCB, but the SSAspecifying that segment name is not in its correcthierarchic sequence.

v The call specifies two SSAs for the same hierarchiclevel.

IMS also returns this status code when a STAT 1 callhas an invalid statistics function. After this status code isreturned, your position in the database is unchanged.

For command-level programs:

An error is in one of the WHERE or SEGMENT optionson a Get or ISRT command for one of these reasons:

v DL/I could not find a segment in the DB PCBspecified in the segment name given in theSEGMENT option.

v The segment name is in the DB PCB, but thequalification for the command does not specify it in itscorrect hierarchic sequence.

v The command specifies two SEGMENT options forthe same hierarchic level.

Programmer Response: Correct the segment namein the SSA or SEGMENT option or in the statisticsfunction of the STAT1 call.

AD

Explanation:


Either the function parameter on the call is invalid or thefunction is not supported for the type of PCB specifiedin the call. Only applies to full-function DEQ calls. Somepossible reasons are:

v The function parameter is invalid.

v A system service call used a PCB that is not the I/OPCB.


AA • AD


v A call issued in a DCCTL environment referred to anunsupported PCB or database.

v A message GU or GN call used an alternate PCBinstead of the I/O PCB.

v A database call used a PCB that is not a DB PCB.

v A message GU used the I/O PCB without specifyingIN=trancode in the BMP JCL.

v A SETS or ROLS call included the I/O area but omittedthe token.

v A CPI Communications driven program issued theSETO call on the I/O PCB.

v A call was issued from an IFP region on an I/O PCB.

v Invalid subsystem level for spool API processing.


A command was issued that is not supported in theenvironment. An example is a system service commandin an online program. If the command is correct, someother possible causes are:

v Referencing a DB PCB on a system servicecommand. System service commands must referencethe I/O PCB.

v Referencing an I/O PCB for a database command, ornot defining an I/O PCB before issuing systemservice commands.

v A command issued in a DCCTL environment referredto an unsupported database or DB PCB.

Programmer Response: Be sure that the specifiedfunction is valid for the PCB specified by the request.

AF

Explanation: GSAM detected a variable-length recordwhose length is invalid on a GU, GHU, GN, or GHN call.

Programmer Response: Correct the program.

AG

Explanation: During INQY call processing, the I/O areawas not large enough to contain all the output data. TheI/O area was filled with partial data, as much as wouldfit in the area provided. AIBOALEN contains the actuallength of the data returned to the application andAIBOAUSE contains the output area length that isrequired for the application program to receive all thedata.

Programmer Response: Correct the applicationprogram by using a larger I/O area. The minimum sizeof the I/O area is the value contained in the AIBOAUSEfield.

AH

Explanation: You get this status code if you:

1. Specify an options list parameter that was notspecified in the call list.

2. The program issued an ISRT call that did not includeany SSAs. The ISRT call requires an SSA.

3. If the program was issuing a GU call to a GSAMdatabase, the GU did not specify an RSA. RSAs arerequired on GU calls to GSAM databases. After thisstatus code is returned, your position in thedatabase is unchanged.

Programmer Response: For cause 2, correct theISRT call by including a qualification; or for cause 3,correct the GU call by adding an RSA to the call.

AI

Explanation: A data management open erroroccurred. Some possible reasons are:

v An error is in the DD statements.

v Neither DD statements nor DFSMDA dynamicallocation members were provided for this database.

v The data set OPEN request did not specify loadmode, but the data set was empty. An empty data setrequires the load option in the PCB.

v The buffer is too small to hold a record that was readat open time.

v No DD statements or DFSMDA members weresupplied for logically related databases.

v For an OSAM data set, the DSORG field of theOSAM DCB, DSCB, or JFCB does not specify PS orDA.

v For an old OSAM data set, the BUFL or BLKSIZEfield in the DSCB is 0.

v The data set is being opened for load, and theprocessing option for one or more segments is otherthan L or LS.

v The allocation of the OSAM data set is invalid. Theallocation is probably (1,1), rather than (1,1) and thiscauses the DSORG to be P0.

v The processing option is L, the OSAM data set is old,and the DSCB LRECL, BLKSIZE, or both, does notmatch the DBD LRECL, BLKSIZE, or both.

v Incorrect or missing information prevented IMS fromdetermining the block size or the logical recordlength.

v A catalog was not available for accessing a VSAMdatabase that was requested.

v OS could not perform an OPEN, but the I/O requestis valid. Either the data definition information isincorrect, or information is missing.

v RACF was used to protect the OSAM data set, andthe control region has no update authorization.

AF • AI


If IMS returns message DFS0730I, you can determinethe cause of the OPEN failure from this message in thejob log. For more information, see the description of thismessage in IMS Version 7 Messages and Codes,Volume 2.

Programmer Response: These kinds of problemsoften require the help of a system programmer orsystem administrator. But before you go to one of thesespecialists, some things you can do are:

v Check the DD statements. Make sure that theddname is the same as the name specified on theDATASET statement of the DBD. The segment namearea in the DB PCB (call level), or in the DIB(command level) has the ddname of the data set thatcould not be opened.

v Check the PSB and make sure that the appropriateprocessing options have been specified for each ofthe DB PCBs that your program uses.

AJ

Explanation: For call-level programs:

For calls that provide parameters in the I/O area, suchas SETS, ROLS, and INIT, the format of the parametersin the I/O area is invalid.

For database calls that include SSAs, such as Get,DLET, REPL, and ISRT, the format of one of the SSAs isinvalid. The number in the segment level number field ofthe DB PCB is the level number of the SSA that isinvalid. Some possible reasons for the invalid SSAformat are:

v The SSA contains a command code that is invalid forthat call.

v The relational operator in the qualification statementis invalid.

v A qualification statement is missing a rightparenthesis or a Boolean connector.

v A DLET call has multiple or qualified SSAs.

v A REPL call has qualified SSAs.

v An ISRT call has the last qualified SSA.

v An ISRT call that inserts a logical child segment intoan existing database includes the D command code.ISRT calls for logical child segments cannot be pathcalls.

v The RSA parameter on a GSAM call is invalid.

v The SSA used an R, S, Z, W, or M command codefor a segment for which no subset pointers aredefined in the DBD.

v The subset command codes included in the SSA arein conflict; for example, if one SSA contained an Sstatus code and a Z status code, Fast Path wouldreturn an AJ status code. S means to set the pointerto current position; Z means to set the pointer to 0.You could not use these status codes in one SSA.

v The pointer number following a subset pointercommand code is invalid. Either you did not include a

number, or you included an invalid character. Thenumber following the command code must bebetween 1 and 8, inclusive.

v The SSA included more than one R command code.An SSA can include only one R command code.

v The specified size for the SSA is too small. After thisstatus code is returned, your position in the databaseis unchanged.

v In response to a SETS or ROLS call, the length of theI/O area is 0, the LL field is less than 4, or the ZZfield is not 0.

v In response to an INIT call, the format of the I/O areais incorrect.

v For calls that provide the length of the I/O area in theAIB, such as INQY, the I/O area length is invalid.

v For SETO, I/O area length is less than 4096 or lessthan the minimum.

v For the Q command code, the specified lock class isnot a letter (A-J).


An ISRT command attempted to insert a logical childsegment using a path command. ISRT commands forlogical child segments cannot be path commands.

Programmer Response:

If you receive this status code on a SETS, ROLS, or INITrequest, correct the parameters provided in the I/Oarea.

If you receive this status code on a Get, DLET, REPL, orISRT request, correct the invalid portion of the SSA. Ifyou receive this status code on a GSAM call, correctthe RSA.

AK


An SSA contains an invalid field name, or the fieldname is not defined in the DBD. The number in thesegment level number field of the DB PCB is the levelnumber of the SSA that contains the invalid name.

You can also receive this status code if the program isaccessing a logical child through the logical parent. DL/Ireturns AK if the field specified in the qualification hasbeen defined for the logical child segment, and itincludes (at least partially) the portion of the logical childthat contains the concatenated key of the logical parent.

When you are using field-level sensitivity, a field youspecified in the SSA has not been defined in the PSB.After this status code is returned, your position in thedatabase is unchanged.


A WHERE option contains an invalid field name. (Thefield name is not defined in the DBD.) The number inthe DIBSEGLV field of the DIB is the level number of

AJ • AK


the WHERE option that contains the invalid name.

Programmer Response: Correct the SSA or WHEREoption.

AL

Explanation: You get this status code if you:

1. Issue a message call in a batch program.

2. Issue a ROLB, ROLS, or SETS call from a batchprogram under one of the following conditions:

v The system log is not on DASD.

v The system log is on DASD, but dynamic backouthas not been specified using the BKO executionparameter.

Programmer Response: For cause 1, correct theprogram so that message calls in a batch program arenot issued. For cause 2, either change the program orput the log on DASD with BKO specified on theexecution parameter.

AM


The call function is not compatible with the processingoption in the PCB, the segment sensitivity, thetransaction-code definition, or the program type. Thelevel number in the PCB is the level number of the SSAthat is invalid. Some of the reasons you might get thisstatus code are:

v If you issue a retrieval call with the D command codein a program that does not have the P processingoption specified in the DB PCB that was used for thecall.

v If you issue a DLET or ISRT call to a terminal-relateddynamic MSDB from a program with no input LTERMpresent. An example is a batch-oriented BMP.

v If the subset pointer referenced in the SSA was notdefined in the program’s PSB. For example, if yourprogram’s PSB specifies that your program can usesubset pointers 1 and 4, and your SSA referencessubset pointer 5, Fast Path returns an AM statuscode to your program.

v If your program tried to use an S, Z, W, or Mcommand code for a subset pointer to which it wasnot pointer update-sensitive, as defined in theprogram’s PSB.

v If a BMP, a CICS online program, or an MPP issuesan ISRT call with the D command code when theprogram does not have the P processing optionspecified in the DB PCB that was referenced in thecall. Batch programs do not need the P processingoption to issue an ISRT call with the D commandcode, unless the program uses field-level sensitivity.

v If the processing option is L and the program issueda call other than an ISRT call. Load programs canissue only ISRT calls.

v If a DLET, REPL, or ISRT call that references a DBPCB does not have the necessary processing optionfor that call. The minimum processing options forthese calls are D for DLET, R for REPL, and I for ISRT.

v If you issue a DLET, REPL, or ISRT call for a segmentto which the program is not sensitive.

v If you issue a CHKP call on a GSAM or VSAM data setopened for output. This code is returned in the GSAMPCB.

v If you issue a GSAM call with an invalid call functioncode.

v If you issue an ISRT or DLET call for the index targetsegment or a segment on which the index target isdependent in the physical database while using analternate processing sequence.

v If you issue a path replace where the program doesnot have replace sensitivity, command code N is notspecified, and the data for the segment is changed inthe I/O area.

v If GSAM could not obtain buffer space because theregion size is too small. This is shown by the valueX'1C' in the field GBCRTNCD.

v If you issue a DLET, ISRT, or REPL call from aprogram where the TRANSACT macro that was usedat IMS system definition specified INQUIRY=YES forthe input message.

v If you issue a call from an ETO terminal to aterminal-related MSDB or a non-terminal-relatedMSDB with terminal-related keys. See IMS Version 7Administration Guide: Transaction Manager for moreinformation on ETO.

v If you issue any type of call with update intent to aMSDB from a dynamically defined device such as aLU 6.2, ETO, or OTMA device.

After this status code is returned, your position in thedatabase is unchanged.


The command is not compatible with the processingoption in the PCB or segment sensitivity. The levelnumber in the DIB is the level number of thequalification that is invalid. Some of the reasons youmight get this status code are:

v If you issue a path retrieval command in a programthat does not have the P processing option specifiedin the DB PCB that was used for the call.

v If the processing option is L and the program issueda command other than a LOAD command. Loadprograms can issue only LOAD commands.

v If you issue a DLET, REPL, or ISRT command thatreferences a DB PCB that does not have thenecessary processing option for that command. Theminimum processing options for these calls are D forDLET, R for REPL, and I for ISRT.

AL • AM


v If you issue a DLET, REPL, or ISRT command for asegment to which the program is not sensitive.

v If you issue a CHKP command if a GSAM or VSAMdata set is open for output.

v If you issue a GSAM call with an invalid call functioncode.

v If you issue an ISRT or DLET command for the indextarget segment, or a segment in the physicaldatabase on which the index target is dependent,while using an alternate processing sequence.

v If you issue a path replace where the program doesnot have replace sensitivity, command code N is notspecified, and the data for the segment is changed inthe I/O area.

v If you issue a call to a GSAM dummy data set. Anycall to a GSAM dummy data set is invalid.

Programmer Response: Correct the request, or makethe necessary changes in the PCB.

AO

Explanation: A BSAM, GSAM, VSAM, or OSAMphysical I/O error occurred. When issued from GSAM,this status code means that the error occurred when:

v A data set was accessed.

v The CLOSE SYNAD routine was entered. The erroroccurred when the last block of records was writtenprior to the closing of the data set.

IMS does not return an AO status code for write errorswith BSAM, VSAM, and OSAM.

If your program receives this status code after issuing acall, this call does not cause the database to bestopped.

Programmer Response: Determine whether the erroroccurred during input or output, and correct theproblem. These problems usually require the help of asystem programmer or system administrator.

AP

Explanation: A message or CHKP call is invalidbecause more than four parameters (or five if aparameter count is specified) are in a message call or aCHKP call issued in a transaction-oriented BMP. Thefollowing exceptions apply:

v A batch-oriented BMP can issue a CHKP call withmore than 4 (or 5) parameters.

v One parameter after the I/O area parameter isallowed in order for the application program to specifya MOD name in an ISRT call. It is counted towardsthe maximum of four (or five) parameters.

Programmer Response: Correct the call.

AQ

Explanation: The AIB contains an invalid subfunction,or the INQY call specifies an invalid function.

Programmer Response: Specify a valid subfunction.Valid INQY call subfunctions are null, DBQUERY,ENVIRON, FIND, or PROGRAM.

AR

Explanation: The options list contains an error that isrelated to a keyword. The feedback area, if one isprovided, will contain additional error information.

Programmer Response: Correct the request.

AS

Explanation: An IAFP specific processing error hasoccurred. The PRTO= option contained invalid data setprocessing options. The feedback area, if provided, willcontain additional error information.


AT

Explanation: The length of the data in the program’sI/O area is greater than the area reserved for it in thecontrol region. The length of the area reserved isdefined by the ACB utility program, DFSUACB0, and isprinted as part of its output.

Programmer Response: If the program is in error,correct the program. If the program is correct, reserve alarger control region by specifying parameters on thePSBGEN statement of PSBGEN.

AU

Explanation: The total length of the SSAs in thedatabase call is greater than the area reserved for themin the control region. The length of the area reserved isdefined by the ACB utility program, DFSUACB0, andprinted as part of its output. After this status code isreturned, your position in the database is unchanged.

Programmer Response: If the program is in error,correct the program. If the program is correct, increasethe PSB SSA space defined in the PSBGEN.

AX

Explanation: A failure to get CSA storage, a failure ofthe DFSLUMIF call, or a processing error with the IAFPSpool API occurred. When this code is returned,diagnostic information is written to the log in a '67D0'log record. Spool API processing errors return aDFS0013E message.

A RACROUTE REQUEST=VERIFY,EVIRON=CREATE

AO • AX


(RACF RACINIT) made during an AUTH call for LU 6.2was unsuccessful.

An OTMA user exit returned invalid routing information.See OTMA return codes in the IMS Version 7 OpenTransaction Manager Access Guide.

Programmer Response: These problems usuallyrequire the help of a system programmer or systemadministrator.

AY

Explanation: IMS ignored a message ISRT callbecause the logical terminal referenced by the alternateresponse PCB currently has more than one physicalterminal assigned to it for input purposes.

Programmer Response: Ask the master terminaloperator to determine (using /DISPLAY ASSIGNMENTLTERM x) which physical terminals (two or more) referto this logical terminal. Use the /ASSIGN command tocorrect the problem.

AZ

Explanation: IMS ignored a PURG or ISRT call in aconversational program. Some possible reasons are:

v Issuing a PURG call referencing the I/O PCB or analternate response PCB. Conversational programscan issue PURG calls only when the PURG callreferences an alternate PCB that is not an alternateresponse PCB.

v Issuing a PURG call to send the SPA.

v Issuing an ISRT or a PURG call referencing analternate PCB that is set for an invalid destination orfor a destination that IMS cannot determine.

v Issuing an ISRT call referencing an alternate PCBwhose destination is a conversational transactioncode when the first segment inserted is not the SPA;or when IMS cannot determine whether or not theSPA was the first segment inserted.

Programmer Response: Correct the PURG or ISRT call.

A1

Explanation: IMS returns the A1 status code for oneof the following reasons:

v AUTH call for LU 6.2 input did not find a PST LU 6.2extension block or did not find a UTOKEN.

v CHNG call against alternate response PCB when theapplication program has not yet issued a GU.

v The MSC program routing exit routine (DFSCMPR0)was called while processing a CHNG call and one ofthe following occurred:

– The exit routine rejected the call by returning withreturn code 8 (A1 status code).

– The exit routine returned with a RC=4 to route themessage back to the originating system; however,

the originating system has not been determinedbecause the application program has not issued aGU.

– The SYSID returned in R0 by the exit routine isnot a valid remote SYSID.

– The MSNAME pointed to by the address in R1,set by the exit routine, is not a valid remoteMSNAME.

v The MSC program routing routine exit (DFSMSCE0)was called while processing an ISRT or CHNG calland one of the following occurred:

– The exit routine rejected the call by settingMSPRFL3=MSPR3REJ in the DFSMSCEP userparameter list that is passed to the exit.

– IMS detected an error while processing thereroute request from the exit. It issued a message″DFS070 Unable to route message RSN=xxyy″and wrote a 6701-MSCE log record to the IMSlog. For more information about this error, see thesection on diagnosing message routing problemsin IMS Version 7 Diagnosis Guide and Reference.

v The destination name supplied in the I/O area of aCHNG call is invalid.

v The destination name supplied in the I/O area of aCHNG call is valid (the destination is a program andthe PCB is not an alternate response PCB), but thetransaction is Fast Path exclusive.

v AUTH call parameter list contained an invalid genericCLASS name. No access checking was done.

v The routing exit routine (DFSCMPR0 or DFSMSCE0)attempted an invalid request to override a directrouting request.

Programmer Response: Correct the CHNG or AUTHcall, MSC program routing exit (DFSCMPR0 orDFSMSCE0), or ensure that the specified destination isvalid.

A2

Explanation: The program issued a CHNG callagainst an invalid PCB. The PCB was invalid for one ofthese reasons:

v It was not an alternate PCB.

v It was an alternate PCB, but it was not modifiable.

v It was being used to process a message and had notcompleted processing it.

Programmer Response: Check the PCB that wasused by the CHNG call and determine which PCB shouldhave been used for the call.

A3

Explanation: The program issued an ISRT or PURG callthat referenced a modifiable alternate PCB that did nothave its destination set. IMS returns this status code toPURG calls only when the PURG call specified an I/O areaas one of the parameters.

AY • A3


Programmer Response: Issue a CHNG call to set thedestination of the modifiable alternate PCB, and thenreissue the ISRT or PURG call.

A4

Explanation: A security violation was detected duringprocessing of an AUTH, CHNG, or ISRT call of a SPA on aconversational response. Some of the reasons for thisstatus code are:

v Transaction authorization is active and either RACFor a transaction authorization exit routine returned anonzero return code.

v The user is not authorized for access to theRESOURCE name in the class requested in theAUTH call. No installation data is returned.

v No source CNT is available, which might be causedby the application program not having issued a GU.

v A program-to-program message switch is being done.In this case, the applicable authorization LTERM isbased on the original message, and this authorizationdoes not allow this function to be performed.

Programmer Response: Check the transaction codeto make sure it was entered correctly. If it was, checkwith the person who handles security at yourinstallation.

A5

Explanation: An ISRT or PURG call supplied an invalidparameter list. The call supplied the fourth parameter(the MOD name), but the ISRT or PURG being issued wasnot for the first segment of an output message.

Programmer Response: Correct the ISRT or PURG call.

A6

Explanation: For a message processing program(MPP or BMP), IMS ignored a message ISRT callbecause the length of the message segment beinginserted exceeds the size specified in the SEGSIZEkeyword of the TRANSACT macro. For a Fast Pathprogram (IFP), the length of the output message to aFast Path terminal exceeds the size specified in theFPBUF parm of the TERMINAL macro.

Programmer Response: Correct the output messagesegment.

A7

Explanation: IMS ignored a message ISRT call for oneof the following reasons:

v The number of message segments inserted exceedsthe number specified in the SEGNO keyword of theTRANSACT macro.

v The IMS queue manager or user Queue ManagerSpace Notification exit routine (DFSQSPC0)

prohibited the insert to prevent the message queuedata sets from overflowing. However, the ISRT is notignored for the message in progress when theDFSQSPC0 threshold is exceeded. The in-progressmessage will be processed. Any subsequent ISRTsare ignored.

v The IMS queue manager or user Queue ManagerSpace Notification exit routine (DFSQSPC0)prohibited the insert because the destinationTRANSACTION or LTERM was stopped.

Programmer Response: Check the output messagesand correct them. Use ROLB or another method to freebuffer space.

A8

Explanation: IMS ignored an ISRT call because:

v An ISRT call to an alternate response PCB must notfollow an ISRT call to the I/O PCB.

v An ISRT call to the I/O PCB must not follow an ISRTcall to an alternate response PCB.

Programmer Response: Correct the ISRT call.

A9

Explanation: IMS ignored the ISRT call because:

v The ISRT call referenced an alternate response PCBdefined as SAMETRM=YES, but the PCBrepresented a logical terminal that is not part of theoriginating physical terminal. An alternate responsePCB defined as SAMETRM=YES must represent thesame physical terminal as the physical terminalassociated with the originating logical terminal.

v The originating terminal is in response mode, and thealternate response PCB is not associated with thatlogical terminal.

IMS does not return this status code if the programmakes either of these errors while communicating with aterminal in a remote IMS system through MSC.

Programmer Response: Determine whether theapplication program is in error, the output logicalterminal has been incorrectly reassigned (using the/ASSIGN command), or if SAMETRM=YES should nothave been specified for the alternate response PCB.

BA

Explanation: The request was not completed becauseit required access to unavailable data.

A status of BA is returned on a DL/I call that attempts toaccess an unavailable partition. If the very next DL/I callis a GN that is either completely unqualified or qualifiedonly by root name, then the next partition is selected.The next-partition selection continues until either anavailable partition is found or there are no morepartitions in the database. If an available partition is

A4 • BA


||

||||||

returned, the call returns the first root in that partition. AGN call that is qualified only on a dependent segmentname results in a BA status if the prior call had a BAstatus returned for the root level.

Only the updates done for the current request, prior tothe time it encountered the unavailable data, arebacked out. The state of the database is as it wasbefore the failing request was issued. If the request wasREPL or DLET, the PCB position was unchanged. If therequest was a Get or ISRT request, the PCB position isunpredictable.

For a DEDB, this status code might be returned if noupdates have been made by the current call. If updateshave been made by the current call since the lastcommit point, a BB status code is returned instead. Ifchanges have been made by a previous call, theapplication program must decide whether to committhese changes.

Rather than having an abnormal termination occur, thisstatus code is returned to the application program thatissued the EXEC DLI command.

Programmer Response: This is an information-onlystatus code.

BB

Explanation: The BB status code is the same as BAexcept that all database updates that the program madesince the last commit point are backed out, and allnonexpress messages sent since the last commit pointare canceled. The PCB position for all PCBs is at thestart of the database.

For a DEDB, this status code might be returned ifupdates have been made by the current call.



BC

Explanation: The response from an INIT STATUSGROUPB call was not completed because it requiredaccess to unavailable data.

All database resources that were allotted up to the lastcommit point are backed out, with the exception ofGSAM and DB2. All output messages are backed out tothe last commit point. Input messages are requeued.


BJ

Explanation: All of the databases in the PSB areunavailable, or there are no database PCBs in the PSB.

Each PCB (excluding GSAM) received an NA statuscode as the result of the INQY DBQUERY call.


BK

Explanation: At least one of the databases included inthe PSB is unavailable or has limited availability.

At least one PCB received an NA or NU status code asthe result of processing the INQY DBQUERY call.


CA

Explanation: The program issued a CMD call with aninvalid command verb, or the command verb does notapply to the IMS system that the program is running in.IMS does not return any command responses.

Programmer Response: Correct the command in theCMD call.

CB

Explanation: The command entered in the CMD call isnot allowed from an AOI program. IMS does not returnany command responses.

Programmer Response: Correct the command. For alist of the commands that an AOI program can issue,see IMS Version 7 Customization Guide.

CC

Explanation: IMS has executed the command andreturned one or more command responses.

Programmer Response: Your program should issueGCMD calls as necessary to retrieve the responses.

CD

Explanation: The command that was entered on theCMD call violates security, or the application program isnot authorized to issue CMD calls. IMS does not executethe command or return any command responses.

Programmer Response: Correct the command. Ifnecessary, check with the person in charge of securityat your installation to find out why your program isrestricted from using that command.

BB • CD


CE

Explanation: IMS rescheduled the message that thisGU call retrieved since the last CMD call. The programhad not reached a commit point when the message wasrescheduled.


CF

Explanation: The message being returned on the GUcall was received by IMS before the start of this IMSexecution. CF can be received on a CHKP call when anI/O area is specified for an MPP or message-orientedBMP. This occurs when a CHKP call issues an internal GUcall.


CG

Explanation: The message retrieved by this GUoriginated from an AOI exit routine.


CH

Explanation: IMS ignored the CMD call just issuedbecause the AOI command interface detected a systemerror and was unable to process the command. IMSprocessing continues.

Programmer Response: Reissue the command.

CI

Explanation: CI is a combination of CE and CF. Themessage retrieved by this GU was scheduled fortransmission before IMS was last started. The messagewas rescheduled, but the program had not reached acommit point.


CJ

Explanation: CJ is a combination of CE and CG. Themessage retrieved by this GU was scheduled fortransmission before IMS was last started. The messageoriginated from an AOI exit routine.


CK

Explanation: CK is a combination of CF and CG. Themessage retrieved with this GU originated from an AOIuser exit. The message was scheduled for transmissionbefore IMS was last started.


CL

Explanation: CL is a combination of CE, CF, and CG.Please see the explanations of those codes.


CM

Explanation: The command that was entered on theCMD call has been executed and completed, but itresulted in an exception response that could not be builtbecause of an insufficient amount of general work area(WKAP).

Programmer Response: Increase WKAP if you wantretrieval of the response.

CN

Explanation: The IOASIZE= parameter that wasspecified on the PSBGEN macro is defined for less thanthe required minimum for CMD calls (132 bytes).

Programmer Response: Redefine IOASIZE=parameter on the PSBGEN for a minimum of 132 bytes.

DA

Explanation: The program issued a DLET or REPL thattried to modify the key field in the segment or, whenusing field-level sensitivity, a REPL call tried to modify afield that had REPL=NO specified on the SENFLDSTMT in the PSB. You cannot change a segment’s keyfield.


DJ

Explanation: The program issued a DLET or REPL callthat was rejected because the segment was notcurrently in hold status. Some possible reasons for thisstatus code are:

v The segment had not been previously retrieved witha Get Hold call.

v The segment was already deleted using this PCB.After one Get Hold call, multiple REPL calls or a DLETcall following a REPL call are valid, but multiple DLETcalls are not.

CE • DJ


v The segment was obtained using a secondary indexas the processing sequence. A subsequent DLET orREPL call using either this PCB or another PCB withinthe PSB caused the current secondary index entry forthis PCB to be deleted.

v A checkpoint call was issued following the Get Holdcall and preceding the REPL or DLET call.

v A rollback call was issued following the get hold calland preceding the REPL or DLET call.

Programmer Response: Correct the program so thatthe segment is in hold status when a DLET or REPL isissued.

DX

Explanation: The program issued a DLET that violatesthe delete rule for that segment.

Programmer Response: Check the program to seewhether or not the program should delete that segment;if it should, check with your DBA (or the equivalentspecialist at your installation) to find out what delete rulehas been specified for that segment.

EM

Explanation: The EM status (empty area) indicatesthat there are no valid sequential dependent segmentsin the area.

Programmer Response: Check to see that the correctarea is being processed by the utility and thatsequential dependent segments have been inserted.

E1

Explanation: The DFSMSCE0 user routing exitrejected the ISRT or CHNG call by settingMSPRFL3=MSPR3REJ and MSPRSTAT=E1 in theDFSMSCEP user parameter list that is passed to theexit.

Programmer Response: Refer to the user installationcopy of the DFSMSCE0 exit for information on theMSPR3REJ and MSPRSTAT settings. Contact yoursystem programmer.

E2



E3



FA

Explanation: IMS returns this status code when theprogram reaches a commit point and an arithmeticoverflow occurs in an MSDB, DEDB, or VSO DEDBduring that commit interval since the last commit point(or, if the program had not reached a commit point,since the program began processing). You can receivethis status code on a SYNC call, a CHKP call, or a GU callto the message queue, depending on your program.The overflow occurred after the program issued aFLD/CHANGE call, or a REPL call for the MSDB, DEDB, orVSO DEDB. When this happens, IMS issues an internalROLB call to eliminate the changes that the program hasmade since the last commit point. All databasepositioning is lost.

Programmer Response: Reprocess the transaction.

FC

Explanation: The program issued a request that is notvalid for the segment type.


FD

Explanation: A nonmessage driven BMP reached adeadlock when IMS tried to get DEDB or MSDBresources (either DEDB UOWs or overflow latches) forthe program. Or, a mixed-mode BMP reached adeadlock on any resource, either Fast Path or fullfunction. IMS eliminates all database updates that theprogram has made since the last SYNC call, CHKPrequest, or SYMCHKP command (or since the programstarted processing, if the program has not issued a SYNCcall or CHKP request). All database positioning is lost,unless you specified the P processing option in thePCB. Messages to a non-express alternate TP PCB arediscarded.


Programmer Response: Start processing from thelast commit point. If you reach a deadlock again,terminate the program.

DX • FD


FE

Explanation: IMS returns this status code any time aprogram issues a FLD call that receives a nonblankstatus code in the FSA.

Programmer Response: See “Fast Path Databases”in IMS Version 7 Application Programming: DatabaseManager for an explanation of FSA status codes andcorrect the FLD call.

FF

Explanation: A program issued an ISRT call againstan MSDB that has no free space. If IMS determines thatthere is no free space when the program issues theISRT call, the program receives the FF status code forthat call. IMS might not determine this until the programreaches the next commit point. In this case, IMS returnsFF when the program issues a GU call to the messagequeue, a SYNC call, or a CHKP call, depending on whichcall caused the commit point.

Programmer Response: To avoid this situation,specify more space for the MSDB at the next systemstart (cold start or normal restart).

FG

Explanation: FG is a combination of FE and FW. Abatch-oriented BMP issued a FLD call that received anonblank status code in the FSA, and the program hasdepleted its normal buffer allocation.

Programmer Response: Check the FSA status codeand correct the FLD call, and then issue SYNC or CHKPcalls in the program more frequently. One way to handlethis status code is to branch to an error routine thatcauses the program to issue SYNC or CHKP calls morefrequently when it receives this status code.

FH

Explanation: A DEDB area was inaccessible to therequested service when the program issued a databaserequest or when the program reached a commit point.The AREA was stopped or the DEDB randomizingroutine was not loaded into storage. A /STARTDATABASE dedbname command will cause the DEDBrandomizing routine to be reloaded.

If IMS returns this status code on a call that caused acommit point to occur (a SYNC call, a message GU, aCHKP request, or a SYMCHKP command), IMS issuesan internal ROLB call to eliminate the program’s databaseupdates and message output created since the lastcommit point.

If your program is accessing a DEDB in a data-sharingenvironment, and if the authorization fails when yourprogram issues its first DL/I call to the DEDB, Fast Pathreturned this status code. Fast Path also notified themaster terminal operator of the authorization failure.

Your position in the database is before the first root inthe next area. A GN will get the next available record(unless that one is also inaccessible).

If a program has access to an area through a PCB withPROCOPT=H and another PCB without PROCOPT=H,it is possible that only calls to the PCB withPROCOPT=H will receive the FH status code. This isbecause the area is accessible to IMS, but the requiredHSSP (high-speed sequential processing) setup couldnot be established. Message DFS0533A explains thereason for this occurrence and is sent to the job log.This status code is also returned if the PROCOPT forone PCB is more restrictive than the PROCOPT of adifferent PCB in the same PSB. Position is set to thebeginning of the next accessible area.


Programmer Response: If the data in the area isimportant, contact the DBA. If the data in the area isunimportant, the program should roll back the changes.Your program can continue processing with the nextavailable area.

If the status code is related to an HSSP setup problem,fix the error as described in the message DFS0533A inthe job log.

FI

Explanation: The program’s I/O area is not at astorage address that the program can access.


FM

Explanation: The application program issued arequest for which the randomizing routine returned areturn code of 4.

The key supplied on a DL/I call to a HALDB was greaterthan the high key value for the last partition. Or theuser’s partition selection exit returned with RC=04 afterhaving been passed a key value with which to select apartition.


Programmer Response: The database position hasnot changed. The application program must determinesubsequent processing.

FN

Explanation: The program issued a FLD call thatcontains a field name in the FSA that is not defined inthe DBD. IMS does not continue processing the FLD callor any of the FSAs in the FLD call. IMS returns an FN

FE • FN


|||||

status code in this situation even if an earlier FSA in thesame FLD call received an FE status code.

Programmer Response: Issue a ROLB call to removethe effects of the incorrect FLD call and then correct theFLD call.

FP

Explanation: The I/O area referenced by a REPL,ISRT, or FLD/CHANGE call to an MSDB contains aninvalid packed-decimal or hexadecimal field.

Programmer Response: Correct the data in the I/Oarea.

FR

Explanation: One of the following situations exists:

v A batch-oriented BMP issued a database request thatforced the system to go beyond the buffer limitspecified for the region.

v A batch-oriented BMP received a GC status code in aPCB with PROCOPT=H. Another commit processwas required before using the PCB again.

IMS eliminates all database changes made by theprogram since the last SYNC call, CHKP request, orSYMCHKP command the program issued (or since theprogram started processing if the program has notissued any SYNC calls, CHKP requests, or SYMCHKPcommands). All database positions for PCBs notreferring to a DEDB with PROCOPT=P or H active arelost. If the PCB referred to a DEDB with PROCOPT=Por H active, the position is set to the valid position afterthe last commit process, or the start of the valid range ifthere was no commit process.


Programmer Response: Either terminate the programand restart it with a larger buffer allocation, or provide aroutine that causes frequent commit points. IfPROCOPT=H is used, make sure that a commit point isrequested after a GC code has been returned.

FS

Explanation: For a root segment or direct dependentsegment, this status code is returned only to BMPs. Fora sequential dependent segment, this status code canbe returned to either a BMP or a message-drivenprogram:

v A BMP issued an ISRT request for a root segment, adirect dependent segment, or a sequential dependentsegment, but IMS could not get enough space ineither the root-addressable or sequential dependentpart of the DEDB area to insert the new segment:

– If IMS returns this status code on an ISRT requestfor a root segment, a direct dependent segment,or a sequential dependent segment, the problemis with the root-addressable portion of the area,the independent overflow area, or the sequentialdependent area.

– If IMS returns this status code when the programissues a SYNC call, CHKP request, or SYMCHKPcommand, the problem is with the sequentialdependent part of the area.

In either case, IMS eliminates all of the databasechanges the program has made since the last commitpoint (or since the program started processing, if theprogram has not reached a commit point).

v A message-driven program issued an ISRT requestfor a sequential dependent segment, and thesequential dependent part is full.


Programmer Response: Continue with otherprocessing, and report the problem to the systemprogrammer.

FT

Explanation: The Fast Path program issued a call to aFast Path database that included too many SSAs. A callto a DEDB can include up to 15 SSAs. A call to anMSDB can include only one SSA.

Programmer Response: Correct the call.

FV

Explanation: At least one of the verify operations in aFLD call issued in a batch-oriented BMP failed when theprogram reached a commit point. IMS eliminates thedatabase updates the program has made since it issuedthe last SYNC or CHKP call (or if the program has notissued a SYNC or CHKP call, since the program startedprocessing). All database positioning is lost.

Programmer Response: Reprocess the transaction orterminate the program.

FW

Explanation: A BMP has used all buffers that areallocated for normal use, or all buffers have beenmodified. IMS returns this status code to warn you thatyou might be running out of buffer space. An FR statuscode might be imminent.

If you have been processing a DEDB, you get FW forrequests that change data.

If you have been processing an MSDB, you get FW forall calls that change data and for GH calls.

FP • FW


With a DEQ call, you receive this code if no buffers canbe released.


Programmer Response: You can supply anerror-handling routine, triggered by the FW status code,that will cause your program to issue SYNC calls, CHKPrequests, or SYMCHKP commands as soon as an FWstatus code is returned to your program. This reducesthe total buffer requirement. To avoid receiving the FWstatus code, issue SYNC or CHKP calls more frequently.

FY

Explanation: PROCOPT=H PCBs process segmentssequentially in the forward direction. Position isestablished on a UOW and is moved forward only.Attempts to retrieve segments prior to the current UOWposition are not allowed for HSSP application programsand will not be processed; they receive this status code.

Programmer Response: Change the applicationprogram to retrieve segments in a forward directiononly; use a PCB with a PROCOPT value other than Hto access the segments in the backward direction.

GA

Explanation: In trying to satisfy an unqualified GN orGNP call, IMS crossed a hierarchic boundary into ahigher level.

If IMS returns GA after a STAT2 request, it means thatthe request that was just issued retrieved the totalstatistics for all the VSAM buffer subpools.

Rather than having an abnormal termination occur, thisstatus code is returned to the application program thatissued the EXEC DLI command. This call results in areturn code of 0.

Programmer Response: This status code is aninformation-only status code.

GB

Explanation: In trying to satisfy a GN call, DL/I reachedthe end of the database or, if you used a SETRstatement, the end of the current range. In this situation,the SSA for the call or qualification for the commandspecified data beyond the last occurrence, and thesearch was not limited to the presence of a known orexpected segment occurrence.

For example, a GN call was specified for a key greaterthan a particular value, rather than a GU call specifying akey value beyond the highest value.

A GB status code can be returned for:

v An unqualified GN call

v A qualified GN call without a maximum key (if no datais returned to the I/O area)

In contrast, a GE status code, instead of a GB statuscode, can be returned for:

v A GU call

v A qualified GN call without a maximum key (if data isreturned to the I/O area)

v A qualified GN call with a maximum key

IMS also returns this status code when it has closed aGSAM data set. The assumed position for a subsequentrequest for a GSAM or full-function database is thebeginning of the database, or if a SETR statement wasused for a DEDB database, the beginning of the currentrange.


Programmer Response: User determined.

GC

Explanation: An attempt was made to cross aunit-of-work (UOW) boundary, or an area boundary inthe case of PROCOPT=H. For a batch-oriented BMPPCB with PROCOPT=H or PROCOPT=P, at least onecall on the referenced PCB changed position in thedatabase since the last commit process or after theprogram began executing. IMS did not retrieve or inserta segment. Position is before the first segment of thefollowing UOW.


Programmer Response: User determined. However, ifthe GC status code results from a call that referred to aPCB with PROCOPT=H, the program must cause acommit process before any other call can be issued forthat PCB. Failure to do so results in an FR status code.

GD

Explanation: The program issued an ISRT call thatwas not qualified for all levels above the level of thesegment being inserted. For at least one of the levelsfor which no qualification was specified, a prior requestusing this PCB established valid position on a segment.That position is no longer valid for one of thesereasons:

v The segment has been deleted by a DLET call using adifferent DB PCB.


FY • GD


v The segment was retrieved using an alternateprocessing sequence, and a REPL or DLET call for thisDB PCB caused the index for the existing position tobe deleted.



GE

Explanation:


IMS returns this status code when:

v DL/I is unable to find a segment that satisfies thesegment search argument described in a Get call.

v For an ISRT call, DL/I cannot find one of the parentsof the segment being inserted.

v For an ISRT call, DL/I was requested to insert a rootsegment outside of the accessible range determinedby a SETR statement.

v The program issued a STAT3 call for OSAM bufferpool statistics, but the buffer pool does not exist.

v The program issued a STAT3 call for VSAM buffersubpool statistics, but the subpools do not exist.

v A nonmessage driven BMP issued a FLD call to anMSDB segment. After the FLD call but before acommit point, the MSDB segment was deleted. GEcan be returned for this reason after either a SYNC ora CHKP call.


v DL/I is unable to find a segment that satisfies thesegment described in a Get command.

v For an ISRT command, DL/I cannot find one of theparents of the segment you’re inserting.

v The program issued a STAT3 command for ISAM orOSAM buffer pool statistics, but the buffer pool doesnot exist.

v The program issued a STAT call for 3 VSAM buffersubpool statistics, but the subpools do not exist.


Programmer Response: The action you takedepends on your program.

Note: When a GNP call for a DEDB sequentialdependent segment results in a GE status code,the I/O area contains a length indication of 10

bytes and the original position of the deletedportion of the sequential dependent part. Positionis at the end of the sequential dependent chain.

GG

Explanation: DL/I returns this status code if thesegment being retrieved contains an invalid pointer andthe application program has a processing option of GOTor GON. (Processing options are explained underPROCOPT in the discussion of program specificationblock generation in IMS Version 7 Utilities Reference:System.) This can occur when update activity in thedatabase is going on concurrently with your program’sprocessing.


The PCB key feedback length and area will be basedon the last segment that satisfied the call. Your positionis at the beginning of the database.


If your request specified KEYFEEDBACK, the DIBKFBLwill contain the length of the key of the last segmentthat satisfied the command. Your position is at thebeginning of the database.


Programmer Response: Continue processing withanother segment or terminate the program. The requestthat resulted in the GG status code might be successfulif you issue it again.

GK

Explanation: DL/I has returned a different segmenttype at the same hierarchic level for an unqualified GN orGNP call.

Rather than having an abnormal termination occur, thisstatus code is returned to the application program thatissued the EXEC DLI command. This call results in areturn and reason code of 0.


GL

Explanation: For either call-level or command-levelprograms:

The program issued a LOG request that contained aninvalid log code for user log records. The log code in aLOG request must be equal to or greater than X'A0'.


DL/I returns GL on a DEQ request when the first byte ofthe I/O area referenced in the request did not contain avalid DEQ class (B-J).3. STAT is a Product-sensitive programming interface.

GE • GL



EXECDLI returns a GL status for either a GN, GNP, GU, orDEQ command when the alphabetic character coded onthe LOCKCLASS option is not within the range of B toJ. An ABENDU1041 is then issued.

Programmer Response: Correct the log code, whichis the first byte of the log message.


If the program received this status code for a DEQrequest, check the DEQ class code in the I/O area.


Check the alphabetic character coded for class on theLOCKCLASS option to ensure that it is in the rangefrom B to J.

GP

Explanation: The program issued a GNP when there isno parentage established, or the segment levelspecified in the GNP is not lower than the level of theestablished parent.

Programmer Response: Make sure you haveestablished parentage before issuing GNP, and checkthe segment level specified by the GNP.

HT

Explanation: The HT status indicates that theHigh-Water-Mark time stamp (HWM TS) is less than theLogical Begin time stamp (LB TS).

Programmer Response: The time stamp in theHigh-Water-Mark segment was not updated on the areadata set during utility setup and partner notification.Check whether the data-sharing partner is still running.The RLM may have a lock for the sequential dependentCI.

II

Explanation: The program issued an ISRT call thattried to insert a segment that already exists in thedatabase. Current position after an II status code is justbefore the duplicate of the segment you tried to insert.Some of the reasons for receiving this status code are:

v A segment with an equal physical twin sequence fieldalready exists for the parent.

v A segment with an equal logical twin sequencealready exists for the parent.

v The logical parent has a logical child pointer, thelogical child does not have a logical twin pointer, andthe segment being inserted is the second logical childfor that logical parent.

v The segment type does not have physical twinforward pointers and the segment being inserted is

the second segment of this type for that parent, or itis the second HDAM or PHDAM root for one anchorpoint.

v The segment being inserted is in an invertedstructure. (The immediate parent of this segment inthe logical structure is actually its physical child in thephysical structure.)

v A physically paired logical child segment alreadyexists with a sequence field equal to that of thesegment you’re inserting. For example, the segmentcould have been inserted with no duplication, butwhen an attempt was made to position for the insertof its physical pair, the segment had a duplicate keyto an existing twin segment.

v An application program inserted a key of X'X’FF...FF’'into a HISAM, HIDAM, or PHIDAM database.



IX

Explanation: The program issued an ISRT call thatviolated the insert rule for that segment. Some of thereasons that IMS returns this status code are:

v The program tried to insert the logical child andlogical parent, and the insert rule for the logicalparent is physical and the logical parent does notexist.

v The program tried to insert the logical child and thelogical parent, and the insert rule is logical or virtualand the logical parent does not exist. In the I/O area,the key of the logical parent does not match thecorresponding key in the concatenated key in thelogical child.

v The program tried to insert a logical child, and theinsert rule of the logical parent is virtual and thelogical parent exists. In the I/O area, the key in thelogical parent segment does not match thecorresponding key in the concatenated key in thelogical child.

v The program tried to insert a physically pairedsegment, where both sides of the physical pair arethe same segment type and the physical and logicalparent are the same occurrence.

v The program issued an ISRT call to a GSAMdatabase after receiving an AI or AO status code.

Programmer Response: Correct the ISRT or theprogram.

L2

Explanation: The application program needed toallocate SDEP CI RBAs to contain the applicationprograms’ insert activity for a particular AREA in theDEDB, but the request to acquire the AREA lock failed.

GP • L2


|

||||

Programmer Response: Contact the IMS DBA or theIMS Systems Programmer.

LB

Explanation: The segment that the program tried toload already exists in the database. Other possiblecauses are:

v A segment with an equal physical twin sequence fieldalready exists for the parent.

v A segment type does not have a physical twinforward pointer, and the segment being inserted iseither the second segment of this segment type forthe parent or the second HDAM or PHDAM root forone anchor point.

v An application program inserted a key of X'FF...FF'into a HISAM, HIDAM, or PHIDAM database.


Programmer Response: Correct the ISRT call orLOAD command, or find out if the load sequence isincorrect. Check with the DBA or the equivalentspecialist at your installation.

LC

Explanation: The key field of the segment beingloaded is out of sequence.

Programmer Response: Check the segment anddetermine where it should be loaded.

LD

Explanation: No parent has been loaded for thesegment being loaded.

Programmer Response: Check the sequence ofsegments that have been loaded and determine wherethe parent should have been loaded.

LE

Explanation: The sequence of sibling segments beingloaded is not the same as the sequence that is definedin the DBD.

Programmer Response: Check and correct thesequence of the segments that are being loaded.

LF

Explanation: The source data for a logical childsegment was found in the input stream of a load job fora High Availability Large Database (HALDB). Logicalchild segments cannot be loaded into a HALDB PHDAMor PHIDAM database. Instead, the segments must beadded later in an update run.

Programmer Response: Remove all source data forlogical child segments from the load job and insert themlater with an update job.

LS

Explanation: The LS status means that an applicationprogram needed to allocate SDEP CI RBAs to containthe application programs’ insert activity for a particulararea in a Data Entry Database and the CIs could not belocked by the RLM. The application work may becommitted, but some other application work may nothave enough CI space, depending on how much SDEPinsert work was done and the first committedapplication.

Programmer Response: Do a commit and be carefulnot to insert too many more SDEP segments.

MR

Explanation: Reserved.

NA

Explanation: The INIT call with DBQUERY in the I/Oarea or the QUERY command was issued, and at leastone of the databases that could be accessed using thisPCB was not available.

A request made using this PCB will probably result in aBA status code if the INIT STATUS GROUPA has beenissued or in a DFS3303I message and 3303 pseudoabend if it has not. An exception is when the databaseis not available because dynamic allocation failed. Inthis case, a request results in an AI (unable to open)status code.


NE

Explanation: Indexing maintenance issued a DL/I call,and the segment has not been found. This status codeis included in message DFS0840I. The system consolereceives message DFS0840I INDEX ERROR (dbdname) NE(first 45 bytes of key). The application program receivesa blank status code.

An application program could have processed asecondary index as a database and thus deleted someof the secondary index entries. Subsequently, when asource segment is deleted, the secondary index for thesource statement might not be present. For this reason,when the application program deletes a source segmentand the index entry is not present, the DFS0840Imessage is sent to the system console, but a blankstatus code is returned to the application program.

Programmer Response: Determine whether thesecondary index has been processed as a databaseand, as a result, the key included in the DFS0840I

LB • NE


||

message was deleted. If this is not the case, check thecause for the index inconsistency with the database andcorrect it.

NI

Explanation: There is a duplicate segment in a uniquesecondary index. While IMS was inserting or replacing asource segment for a secondary index defined with aunique sequence field, the insertion of the secondaryindex segment was attempted but was unsuccessfulbecause an index segment with the same key wasfound. One possible cause for a duplicate segment inthe index is that the index DBD incorrectly specified aunique key value—secondary index only.

In an online application program, the call is backed outand the program receives an NI status code.

For a batch program that does not log to the IMS DASDlog, IMS abnormally terminates the program with aU0828 abend. You should run batch backout.

Programmer Response: The response is determinedby the user. If duplicate secondary index entries occur,specify the index as non unique, and provide anoverflow entry-sequenced data set.

NL

Explanation: The application program issued anextended checkpoint call. Checkpoint information iswritten to the log data set, but there is no DD statementin the batch step for the log, so no checkpoint waswritten. The DD name for the log data set is IEFRDER.Although no checkpoint information was written, normalcommit processing was performed.

Programmer Response: Provide an IEFRDER DDstatement. No status is returned for a DD DUMMYstatement.

NO

Explanation: A BSAM or VSAM physical I/O erroroccurred during a database request that is issued bythe index maintenance function.

For an online program, all updates made for the call arebacked out and the application program receives theNO status code. For a batch program that does not logto the IMS DASD log, IMS abnormally terminates theprogram with an 826 abend.

Programmer Response: See accompanyingmessages giving details of the error. In a batchenvironment, run batch backout.

NU

Explanation: An ISRT, DLET, or REPL request usingthis PCB might result in a BA status code if the INITSTATUS GROUPA call or QUERY command has been

issued or in a DFS3303I message or 3303 pseudoabend if it has not. If the unavailable database is onlyrequired for delete processing, it is possible that theISRT and REPL requests can be processed.


OS

Explanation: The OS status indicates that theSTOPRBA parameter value given for the DEDBSequential Dependent Scan Utility is too large for thecurrent sequential dependent CI set.

Programmer Response: Check the parameter valuefor validity and use a correct value or use the utilitiesdefault value for the scan end.

QC

Explanation: There are no more messages in thequeue for the program. The reasons that IMS returnsthis status code are:

v An application program issued a successful CHKP call,but the message GU call issued internally by the CHKPcall was unsuccessful (that is, it did not return amessage).

v An application program processing APPCsynchronous messages that does not set sync pointsfor each message GU call (that is, mode=MULT on theTRANSACT macro) is returned a QC status code toforce a sync point after each GU call.

For more information regarding the TRANSACTmacro, refer to IMS Version 7 Installation Volume 2:System Definition and Tailoring.

v An MPP or transaction-oriented BMP issued a GU callto retrieve another message, but either there are nomore messages or the processing limit (that is,PROCLIM=parm on the TRANSACT macro) hasbeen reached.

v IMS is shutting down or:

– A /PSTOP REGION command has been issued forthe dependent region in which the applicationprogram is processing.

– A database dump (/DBD) command has beenissued.

– A database recovery (/DBR) command is inoperation.

– A stop subsystem (/STOP SUBSYS) commandhas been issued.

For more information regarding these commands,refer to IMS Version 7 Command Reference.

v IMS wants to reschedule the region (quickreschedule). For more information regarding quickreschedule, refer to IMS Version 7 AdministrationGuide: System.

Programmer Response: This is an information-only

NI • QC


status code. The application program should terminate.

QD

Explanation: The program issued a message GN orGCMD call, but there are no more segments for thismessage.

Programmer Response: Process the message.

QE

Explanation: The program issued a message GN callbefore issuing a GU call to the message queue. Inmessage-driven Fast Path programs, this code appliesto message calls only. The program issued a messageGN call before issuing a GU call to the message queue. Inmessage-driven Fast Path programs, this code appliesto message calls only. This code is also returned whena program issues a ROLB call, specifying the I/O areaparameter, without having issued a successful messageGU call during that commit interval. A message-drivenFast Path program issued a CHKP call to establish aninternal GU call but the CHKP call failed with a status QCcode. A successful GU call was never issued during thecommit interval for the failing CHKP call. Information onlystatus code for calls encountering SDEP full or FLDverify failures which are reprocessed via ROLB.

Programmer Response: Correct the program by:

v Issuing a GU call before the GN call

v Issuing a CMD call before the GCMD call

v Issuing a GU call before the ROLB call

QF

Explanation: When using Shared Queues and theapplication ISRT(S) results in a message that spansmultiple queue buffers, the second and subsequentbuffers are PUT to the Shared Queues. If the SharedQueues are full and those CQS PUTs are rejected, thisresults in a STATUSQF being passed back to theapplication.

Programmer Response: Correct the segment. Issue aROLB to back out any incomplete data.

QH

Explanation: There has been a terminal symbolicerror. The output logical terminal name or transactioncode is unknown to IMS. Some reasons for receivingthis status code are:

v The program tried to insert an alternate responsePCB receiving a QC status code for a GU call.

v The program tried to insert to an I/O PCB that has alogical terminal name of blanks. This could occurafter the program issued a GU call for a message thatoriginated either from a batch-oriented BMP or a CPICommunications driven program.

v SMB or CNT could not be found.

v The program deallocated a conversation with a SETOcall with the DEALLOCATE_ABEND option. Anysubsequent ISRT calls are rejected with this statuscode.

v The program issued an ISRT call without first issuinga GU call.

v The logical terminal name or transaction codespecified is Fast Path exclusive and is not availableto this program.

v The program issued an ISRT call for a segmentshorter than 5 bytes.

v The program issued an ISRT call for a SPA shorterthan 6 bytes.

v The logical terminal name or transaction code hasleading blanks, instead of being left-justified.

Programmer Response: Check the logical terminalname or transaction code, and correct it.

RA

Explanation: The token does not match a token forany outstanding SETS requests or the request wasissued for a database PCB that did not get a BA statuson the previous request.

Programmer Response: The outstanding SETSrequest might have been canceled by a commitprocess, or an error exists in the use of the token.

RC

Explanation: The ROLS call was issued withunsupported PCBs in the PSB, or the program is usingan attached subsystem. If the ROLS call is in response toa SETS call, the call is rejected. If the ROLS call is inresponse to a SETU call, the call is processed, butupdates to unsupported PCBs or an attachedsubsystem are not backed out. This status is onlyreturned for a ROLS call in response to a SETU call if anattached subsystem is being used.


Explanation: The ROLS request was rejected becausethe PSB contains access to a DEDB, MSDB, or GSAMorganization or has access to an attached subsystem.

Programmer Response: The ROLS request is invalid inthis environment. The program must either remove theuse of the database organization that is preventing theuse of the ROLS call or not use the ROLS call.

RX

Explanation: The program issued a REPL that violatedthe replace rule for that segment.

Programmer Response: Correct the REPL call, orcheck with the DBA or the equivalent specialist at yourinstallation.

QD • RX


|||||||

||

SA

Explanation: On a SETS request, IMS was not able toobtain the storage space for the data in the I/O area.

Programmer Response: Use a larger region size forthe job step.

SB

Explanation: The maximum number of levels, nine, ofSETS requests were already specified, and this requestis attempting to set the tenth.


SC

Explanation: A SETS or SETU call was issued withunsupported PCBs (DEDB, MSDB, or GSAM) in thePSB, or the program is using an attached subsystem.

Programmer Response: For a SETS call, the requestis rejected. Remove the unsupported PCBs or use theSETU call. For a SETU call, the program can proceed withthe knowledge that a ROLS call will not back out changesfor the unsupported PCBs. The other option is to notuse the SETS or ROLS function.

SY

Explanation: IMS incurred an internal error duringSyncpoint processing for an IMS/JAVA SYNC requestcall.

Programmer Response: Contact your IMS systemprogrammer.

TA

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a scheduling request. The PSB named in therequest is not in the PSB directory.

Programmer Response: Correct the name of the PSBin the scheduling request, or add the PSB name to thePSB directory.

TC

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a scheduling request. It means that you havealready scheduled a PSB.

Programmer Response: Correct your program so thatyou terminate a PSB before scheduling another. If youwant to reschedule a PSB, you must have alreadyterminated the PSB.

TE

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a scheduling request. The PSB could not bescheduled because an initialization error occurred.

Programmer Response: See your systemprogrammer or DBA. For information on possiblecauses for the PSB initialization error, see IMS Version7 Application Programming: Database Manager.

TG

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a terminate request. The program issued aterminate request when there was no PSB scheduled.

Programmer Response: This is an information-onlystatus code. If you only wanted to terminate a PSB,continue with processing. If you also wanted to cause async point, issue a SYNCPOINT command. (No syncpoint was caused by the unsuccessful terminaterequest.)


TH

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a database request or a statistics request. Theprogram attempted to access the database beforescheduling a PSB.

Programmer Response: Correct your program, andschedule a PSB before accessing the database.

TI

Explanation: This status code applies tocommand-level programs only, and it is returned afteran ISRT command. The ISRT command defined aninvalid path to the segment. Data must be transferredfor all segments between the first named segment andthe last named segment.

Programmer Response: Correct the ISRT command,specifying a FROM option for each segment to betransferred.

TJ

Explanation: This status code applies to CICS onlinecommand-level programs only, and it can be returnedafter any command that a CICS online program uses.DL/I is not active.

Programmer Response: Contact your DBA. CICS

SA • TJ


must be reinitialized with DL/I defined as active in theSIT.

TL

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returned after ascheduling request. A conflict in scheduling intentoccurred. (This cannot occur if program isolation hasbeen specified.)

Programmer Response: Specify program isolation inthe SIT. If program isolation has not been specified, waituntil the PSB is no longer in use, and reschedule it.

TN

Explanation: This status code applies tocommand-level programs only, and it can be returnedafter any of the commands. An invalid SDIB exists. Aninitialization call was not made, or the system’s DIB (notthe application program’s DIB) was overlaid.

Programmer Response: Check your program tomake sure that you did not use an entry statement, asyou would in a call-level batch program. Also make surethat no addressing errors are in your program thatwould cause an overlay.

TO

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing a REPL command. A path-replace erroroccurred. The segments to be replaced are comparedto the previous Get command and one of the followingsituations occurred:

v A segment is named to be replaced that was notretrieved by the Get command.

v Data had not been transferred (no INTO option) forthis segment on the Get command.

v The attributes of the data to be transferred do notmatch the data in the database.


TP

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing any of the database commands, a LOADcommand, or a statistics request. The number of thePCB specified in the USING option is higher than thenumber of PCBs in the PSB being used, or an invalidprocessing option was specified. For example, theprogram tried to issue a LOAD command without havingthe L processing option specified in its PSB.

An EXEC DLI command is being attempted against aGSAM PCB. This is invalid.

Programmer Response: Check the PSB and correctyour program.

TR

Explanation: This status code means that the CICSXDLIPRE exit routine returned X'04' in register 15because the routine determined that the immediatelypreceding DL/I request should not be executed.

Programmer Response: Contact the CICS systemprogrammer.

TY

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a database or statistics request. The databasewas not open when the request was issued.

Programmer Response: Contact your DBA or systemprogrammer. The database can be checked and openedby using operator commands.

TZ

Explanation: This status code applies to CICS onlinecommand-level programs only, and it is returnedfollowing a database or statistics request. The length ofthe retrieved segment is greater than 64 KB.

Programmer Response: Contact your DBA or systemprogrammer; the database definition might requiremodification.

UB

Explanation: This status code is returned when IMS isunable to obtain private buffer pool.

Programmer Response: No DFS0535I message isissued if the High Speed Reorganized Utility (HSRE) isbeing used when this status code is received. See theDFS2712I messages issued at utility termination for thename of the module, abend subcode, Utility High SpeedWorkarea (UHSW) storage area dump, IOAR (DEDBI/O), and register contents.

If the DBFPAPB0 return code is 08, storage is notavailable for the private buffer pool.

If the DBFHUSS0 return code is 10, the request forprivate buffers is for the initial buffer set and the privatepool anchor address already exists.

UC

Explanation: This status code is returned for thefollowing reasons:

v For batch programs in which a checkpoint record waswritten to the UCF journal data set. For informationabout the Utility Control Facility (UCF), see IMS

TL • UC


Version 7 Administration Guide: Database Managerand IMS Version 7 Utilities Reference: Database andTransaction Manager.

During the processing of an HD reorganization, areload, or an initial load program under thesupervision of the Utility Control Facility (UCF), acheckpoint record was written to the UCF journaldata set. IMS returns this status code to indicate thatthe last ISRT call was correct and the initial loadprogram might continue or it might perform acheckpoint procedure before continuing.

v When a connect failed.

Programmer Response: This is an information-onlystatus code for the first status code reason above.

When this status code is issued for a connect failure,see message DFS0535I for more information on how tocorrect the error.

UP

Explanation: This status code is returned when theUOW requested is greater than the UOW range.

Programmer Response: Correct the error and run thejob again.

UR

Explanation: This status code is returned for batchprograms only. Your initial load program is beingrestarted under UCF. For information about the UtilityControl Facility (UCF), see IMS Version 7 AdministrationGuide: Database Manager and IMS Version 7 UtilitiesReference: Database and Transaction Manager. Theprogram terminated while executing under UCF. The jobwas resubmitted with a restart request.

Programmer Response: Ensure that the program isin proper sequence with database loading. The programuses the I/O area and the DB PCB key feedback areato do this.

US

Explanation: This status code is returned for batchprograms only. The initial load program is about to stopprocessing. While processing an HD reorganizationreload or user initial load program under the supervisionof UCF, the operator replied to the WTOR from UCBand requested the current function to terminate. Forinformation about the Utility Control Facility (UCF), seeIMS Version 7 Administration Guide: Database Managerand IMS Version 7 Utilities Reference: Database andTransaction Manager. The last ISRT call was processed.

Programmer Response: Ensure that the initial loadprogram performs a checkpoint procedure of its datasets and returns with a nonzero value in register 15.

UW

Explanation: This status code is returned when IMS isunable to obtain a work area.

Programmer Response: Increase the REGION sizeand run the job again.

UX

Explanation: This status code is returned for batchprograms only. A checkpoint record was written, andprocessing stopped. This is a combination of UC andUS status codes.

Programmer Response: See the descriptions of UCand US status codes.

U1

Explanation: This status code is returned when thearea name specified is not valid.

Programmer Response: Correct the error and run theutility job again.

U9

Explanation: This status code is returned when thearea access intent is read or read only. Access intentmust be UP or EX.

Programmer Response: Use the /STA DB ACCESScommand to set the access intent to UP or EX and runthe job again.

V1

Explanation: The program tried to insert or replace avariable-length segment that is too long. The length ofthe segment must be equal to or less than themaximum length specified in the DBD. IMS also returnsstatus code V1 when the specified minimum lengthcannot hold the complete sequence field of the segmenttype. In this situation, status code V1 results from oneof three instances: processing without anedit/compression routine; processing with anedit/compression routine, but not specifying the keycompression option; or coding a length field (LL) that isless than the specified minimum length. The lengthmust be long enough to include the entire referencefield; if the segment is a logical child, it must include theentire concatenated key of the logical parent and allsequence fields for the paired segment. The programtried to delete a variable-length segment. The copy ofthis segment in the user’s I/O area contains an invalidlength field.

IMS also returns this status code when an invalid recordlength is specified in a GSAM call.


UP • V1


V2

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing a database or LOAD command. The segmentlength is missing or invalid. The segment length mustbe a positive integer. For variable-length segments, it isthe maximum size acceptable to the program’s I/O area.

Programmer Response: Check that the programtranslated and compiled correctly. The value of anysegment length in a path command should not exceed32 KB, and the sum of the lengths should not exceed64 KB.

V3

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing a Get or ISRT command. The field length ismissing or invalid. The field length must be a positiveinteger, and it must be specified for each field in aWHERE option.


V4

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing any of the database commands or a LOADcommand. The length of a variable-length segment isinvalid. The LL field as provided by the program on anISRT or REPL command, or as received in the I/O areaon a Get command, exceeds the value ofSEGLENGTH.


V5

Explanation: This status code applies tocommand-level programs only, and is returned followinga Get, REPL, or ISRT command. The offset is invalid. Theoffset must be a positive integer and not greater thanthe segment length.


V6

Explanation: This status code applies tocommand-level programs only, and it is returnedfollowing a Get or ISRT command using the KEYSoption. The concatenated key length is missing orinvalid. The length of the concatenated key must be apositive integer.


V7

Explanation: This status code applies tocommand-level programs only, and is returned followinga STAT command. It means that the statistics arealength is either too small or invalid. The length must bea positive integer, and it must be at least 72 bytes forunformatted statistics, 120 bytes for summary statistics,and 360 bytes for formatted statistics.


XA

Explanation: The program tried to continueprocessing the conversation by passing the SPA toanother program through a program-to-programmessage switch after already responding to theterminal.

Programmer Response: If a response has been sent,the SPA should be returned to IMS. Correct theprogram.

XB

Explanation: The program has passed the SPA toanother program but is trying to respond to theoriginating terminal.

Programmer Response: No response is allowed by aprogram that is passed control of the program through aprogram-to-program message switch.

XC

Explanation: The program inserted a message thathas some bits in the Z1 field set. The Z1 field isreserved for IMS.

Programmer Response: Correct the program toprevent it from setting those bits.

XD

Explanation: IMS is terminating by a CHECKPOINTFREEZE or DUMPQ. IMS returns this code to a BMPthat has issued a CHKP or SYNC call. If it is atransaction-oriented BMP, IMS does not return amessage.

IMS also returns XD when a batch program issues aSYNC call.

Programmer Response: Terminate the programimmediately. IMS will terminate the program abnormallyif the program issues another call.

V2 • XD


XE

Explanation: A program tried to insert a SPA to analternate express PCB.

Programmer Response: Regenerate the PSB andremove the EXPRESS=YES option from the PCB, ordefine another non-express PCB to be used in the ISRTcall.

XF

Explanation: IMS is ignoring the ISRT call for the SPA,because the specified alternate PCB had its destinationset to a logical terminal but was not defined asALTRESP=YES during PSB generation.

MSC directed routing does not support aprogram-to-program switch between conversationaltransactions.

Programmer Response: Correct the applicationprogram or change the PSB generation for thatalternate PCB to specify ALTRESP=YES.

XG

Explanation: IMS ignored the ISRT call because thecurrent conversation requires a fixed-length SPA, andthe ISRT call was to a program with a different length orvariable-length SPA, while the source IMS system wasearlier than IMS 6.1. If the SPA ISRT on a remotesystem is not going back to the input terminal (IOPCB),the SPA size must be the same as the size of thecurrent one, if the source IMS system is earlier thanIMS 6.1.

Programmer Response: Correct the program or theSPA definitions.

XX

Explanation: An error occurred during GSAMinitialization or during GSAM call processing. If thisstatus code is in the GSAM PCB before the applicationprogram issued the first call, the error was detectedduring initialization. Possible causes are:

v Insufficient space

v Invalid DBD

v Invalid block size

v Invalid option

v Internal GSAM error

Programmer Response: A subsequent GSAM call willresult in an abnormal termination of the program. Theprogram should terminate.

X2

Explanation: The first ISRT call to an alternate PCBwhose destination is a conversational transaction codeis not for the SPA. The SPA must be inserted with thefirst ISRT call.

Programmer Response: Insert the SPA, and thenreinsert the message segment.

X3

Explanation: The program modified the first 6 bytes ofthe SPA; the SPA is now invalid.

Programmer Response: Correct the program andrestore the original bytes.

X4

Explanation: The program issued an ISRT call to passthe SPA to a nonconversational transaction code. It didthis by referencing a PCB whose destination was set forthe nonconversational transaction code. You can sendthe SPA only to transaction codes that are defined asconversational.

Programmer Response: Correct the ISRT call. Sendonly data segments.

X5

Explanation: The program issued more than one ISRTcall to send the SPA to a PCB whose destination is atransaction code. Only one SPA is allowed permessage.


X6

Explanation: An invalid transaction code name wasinserted into the SPA. This will occur if the input is fromLU 6.2 (APPC) or OTMA and if a dynamic control blockwas built for the transaction code.

Programmer Response: Correct the program to setthe proper transaction code name.

X7

Explanation: The length of the SPA is incorrect. Theprogram modified the first 6 bytes.

Programmer Response: Correct the SPA and theprogram.

XE • X7


blanks (bb)

Explanation: The call was completed.

Programmer Response: Proceed with processing.

blanks (bb)


Part 3. Appendixes


Bibliography

This bibliography includes all the publications citedin this book, including the publications in the IMSlibrary.

CICS/ESA Version 4.1 ApplicationProgramming Guide, SC33-1169

CICS/ESA Version 4.1 ApplicationProgramming Reference, SC33-1170

CICS Family: General Information, GC33-0155

CICS Transaction Server for OS/390 Release3 CICS Application Programming Guide,SC33-1687

CICS Transaction Server for OS/390 Release3 CICS Application Programming Reference,SC33-1688

IMS Version 7 Library

SC26-9419 ADB Administration Guide:Database Manager

SC26-9420 AS Administration Guide: SystemSC26-9421 ATM Administration Guide:

Transaction ManagerSC26-9422 APDB Application Programming:

Database ManagerSC26-9423 APDG Application Programming:

Design GuideSC26-9424 APCICS Application Programming:

EXEC DLI Commands forCICS and IMS

SC26-9425 APTM Application Programming:Transaction Manager

SC26-9427 CG Customization GuideSC26-9426 CQS Common Queue Server and

Base Primitive EnvironmentGuide and Reference

SC26-9436 CR Command ReferenceSC26-9428 DBRC DBRC Guide and ReferenceLY37-3738 DGR Diagnosis Guide and

ReferenceLY37-3739 FAST Failure Analysis Structure

Tables (FAST) for DumpAnalysis

SC27-0832 IJUG IMS Java User’s GuideGC26-9429 IIV Installation Volume 1:

Installation and VerificationGC26-9430 ISDT Installation Volume 2:

System Definition andTailoring

SC26-9432 MIG Master Index and GlossaryGC26-9433 MC1 Messages and Codes

GC26-1120 MC2 Messages and Codes,Volume 2

SC26-9434 OTMA Open Transaction ManagerAccess

SC26-9435 OG Operations GuideGC26-9437 RPG Release Planning GuideSC26-9438 SOP Sample Operating

ProceduresSC26-9440 URDBTM Utilities Reference: Database

and Transaction ManagerSC26-9441 URS Utilities Reference: System

Supplementary PublicationsGC26-9431 LPS Licensed Program

SpecificationsSC26-9439 SOC Summary of Operator

Commands

Online Softcopy PublicationsLK3T-3526 CDROM IMS Version 7 Softcopy LibrarySK2T-0730 CDROM IBM Online Library: Transaction

Processing and DataSK2T-6700 CDROM OS/390 Collection


Index

AACCEPT command

description 49examples 49format 49options 49usage 49

AIB (Application Interface Block)AIB mask 67restrictions 68supported commands 67

AJ status code 101Alternate PCB 11AM status code 101assembler language

DL/I command-level sample 74I/O area 72

Bbacking out database changes 106backout points, intermediate 106basic checkpoint 105batch program, issuing checkpoints 105batch programs, command-level samples

assembler 74C 85COBOL 78PL/I 81

BILLING segment 9BMP (batch message processing) program, issuing

checkpoints 105

CC program, DL/I command-level sample 85call-level programs

comparing with command-level programscommand codes and options 114commands and calls 113

DL/I calls available to IMS and CICScommand-level 113

categories, status codes 117checkpoint (CHKP)

EXEC DLI commandbasic 105current position 105

symbolic EXEC DLI command, description 106CHKP (Checkpoint) command

description 49, 105examples 50format 49options 49restrictions 50usage 49

COBOLDL/I command-level sample 78I/O area 72

codes, statusexplanations 127tables 117

command-level programscomparing with call-level programs

command codes and options 114commands and calls 113

DIB (DL/I interface block) 68DL/I calls available to IMS and CICS 113I/O area, defining 71key feedback area, defining 71preparing EXEC DL/I program for execution 91sample assembler language 74sample C 85sample COBOL 78sample PL/I 81status codes, checking 69syntax of EXEC DLI commands 13

commands, EXEC DLIACCEPT 49CHKP 49DEQ 50DLET 15GN 17GNP 22GU 28ISRT 33LOAD 51LOG 52POS 39QUERY 53REFRESH 54REPL 40RETRIEVE 44ROLB 55ROLL 56ROLS 57SCHD 46SETS 58SETU 59STAT 60SYMCHKP 61TERM 47XRST 63

comparing EXEC DLI commands with DL/I calls 113comparing EXEC DLI options with command

codes 114compiling, options with EXEC DLI 91crossing a unit of work (UOW) boundary when

processing DEDBs 103

Ddata availability enhancements 109data entry database 93database availability

obtaining information 109status codes, accepting 109


database description name field, DIB (DL/I interfaceblock) 71

database example, medical hierarchy 8database integrity, maintaining 105database organization field, DIB (DL/I interface

block) 71database processing, fast path 93database recovery, planning for

backing out database changes 106checkpoints, take with basic CHKP command 105checkpoints, taking 106restarting your program, XRST command 106

DB PCB 11DBCTL facilities

ACCEPT command 109data availability 109QUERY command 109REFRESH command 109ROLS command 107SETS command 107

DEDB (data entry database)processing

overview 93POS command 102subset pointers 93

defining application program elements to IMSAIB 67DIB 68I/O area 71key feedback area 71

DEQ (Dequeue) commanddescription 50examples 51format 50options 51restrictions 51usage 51

DIB (DL/I interface block)accessing information 68database description name field 71database organization field 71fields 68key feedback length field 71segment level field 70segment name field 70status code field 69structure 68translator version 69

direct dependent segments, in DEDBs 93DL/I interface block 68DLET (Delete) command

description 15example 16format 15options 15Restrict 16usage 16

dynamic backout 106

EEXEC DLI

allowable commands 14

EXEC DLI (continued)compiler options, required 91linkage editor options, required 92preparing program for execution 91program summary 13syntax of commands 13translator options, required 91

EXEC DLI commandsACCEPT 49CHKP 49DEQ 50DLET 15GN 17GNP 22GU 28ISRT 33LOAD 51LOG 52POS 39QUERY 53REFRESH 54REPL 40RETRIEVE 44ROLB 55ROLL 56ROLS 57SCHD 46SETS 58SETU 59STAT 60SYMCHKP 61TERM 47XRST 63

EXEC DLI options, use with subset pointers 95

FFast Path, subset pointers with DEDBs 93fast path database, processing 93fields in DIB 68FIRST insert rule 37free space, identifying 103

GGC status code 103general programming guidelines 73GETFIRST option

examples 96retrieving first segment in subset 96

GN (GET NEXT) commanddescription 17examples 21format 17options 18restrictions 22usage 21

GNP (GET NEXT in Parent) commanddescription 22examples 27format 22options 23


GNP (GET NEXT in Parent) command (continued)restrictions 27usage 26

GSAM PCB 11GU (GET UNIQUE) command

description 28examples 32format 28options 29restrictions 33usage 32

guidelines, general programming 73

HHERE insert rule 37hierarchical database example, medical 8HOUSHOLD segment 10

II/O area

assembler language 72COBOL 72coding 72command-level program 71PL/I 72symbolic CHKP 106XRST 106

I/O PCB (input/output PCB) 11ILLNESS segment 8intermediate backout points 106ISRT (insert) command

insert rules 37ISRT (Insert) command


issue checkpoints in batch or BMP programs 105

Kkey feedback area

command-level program 71length field in DIB 71

LLAST insert rule 37level number field in DIB 70link editing, EXEC DLI 92linkage editor options with EXEC DLI 92LOAD (Load) command


locatinga specific sequential dependent 102last inserted sequential dependent 102

LOG commanddescription 52examples 53format 53options 53restrictions 53usage 53

Mmedical database example

description 8segments 8

MOVENEXT optionexamples 98use when moving subset pointer forward 98

moving subset pointer forward 98

Oonline programs, command-level samples

assembler 74C 85COBOL 78PL/I 81

options for subset pointersGETFIRST 96MOVENEXT 98SET 98SETCOND 99SETZERO 97

PP processing option 103path command 44PATIENT segment 8PAYMENT segment 9PCB (program communication block)

in application programs, summary 12types 11

PL/IDL/I command-level sample 81I/O area 72

pointers, subsetDBD, defining 95description 93GETFIRST option 96MOVENEXT option 98preparation for using 94PSB, defining 95sample application 95SET option 98SETCOND option 99SETZERO option 97status codes 101

POS commanddescription 39

Index 157

POS command (continued)EXEC DLI command format 39format 39free space, identifying 103locating a specific sequential dependent 102locating the last inserted sequential dependent 102options 39usage 40using with DEDBs 102

processingDEDBs 93Fast Path, P (position) option 103

programming guidelines, general 73PSB (program specification block), format 12

QQUERY command

description 53example 53format 53options 53restrictions 54usage 53

Rrandomizing routine, FM status code 137recovering databases 105recovery EXEC DLI commands

basic CHKP 105SYMCHKP 106XRST 106

REFRESH command 109description 54example 54format 54options 54restrictions 55usage 54

REPL (Replace) commanddescription 40examples 43, 44format 41options 41restrictions 44usage 42

resetting a subset pointer 98restarting your program, with EXEC DLI XRST

command 106RETRIEVE command


ROLB (Rollback) commanddescription 55examples 55format 55options 55

ROLB (Rollback) command (continued)restrictions 55usage 55

ROLL commanddescription 56examples 56format 56options 56restrictions 56usage 56

ROLS command 107description 57examples 57format 57options 57restrictions 58usage 57

RULES=FIRST 37RULES=HERE 37RULES=LAST 37

Ssample programs

command-level assembler languagebatch 74online 74

command-level Cbatch 85online 85

command-level COBOLbatch 78online 78

command-level PL/Ibatch 81online 81

SCHD (Schedule) commanddescription 46examples 47format 46options 46usage 47

segment level number field 70segment name field, DIB (DL/I interface block) 70segments in medical database example 8sequential dependent segments

free space, identifying 103in DEDBs 93locating a specific dependent 102locating the last inserted dependent 102POS command 102

SET optionexamples 98resetting a subset pointer 98

SETCOND optionexamples 99setting a subset pointer conditionally 99

SETS commanddescription 58example 59format 58options 58


SETS command (continued)restrictions 59usage 59

setting a subset pointerconditionally 99to zero 97

SETU commanddescription 59example 60format 59options 60restrictions 60usage 60

SETZERO optionexamples 97setting a subset pointer to zero 97

STAT commanddescription 60examples 61format 61options 61usage 61

status code, field in DIB 69status codes

categories 117checking in a command-level program 69database calls 122database calls, table 117message calls, table 122, 124processing option P 103subset pointers 101

subset pointersDBD, defining 95description 93GETFIRST option 96MOVENEXT option 98preparation for using 94PSB, defining 95sample application 95SET option 98SETCOND option 99SETZERO option 97status codes 101

symbolic checkpointrestart 106XRST 106

SYMCHKP (Symbolic Checkpoint) commandcurrent position 62description 61, 106examples 63format 61options 62restrictions 63usage 62

System ServiceACCEPT 49CHKP 49DEQ 50LOAD 51LOG 52QUERY 53

System Service (continued)REFRESH 54ROLB 55ROLL 56ROLS 57SETS 58SETU 59STAT 60SYMCHKP 61XRST 63

TTERM (Terminate) command


translating, EXEC DLI program 91translator options required for EXEC DLI 91translator version, DIB (DL/I interface block) 69TREATMNT segment 9

UUtility Control Facility (UCF) 147

Vvariable names, mandatory 68

XXRST (Extended Restart) command


Index 159

Readers’ Comments — We’d Like to Hear from You

IMS Version 7Application Programming: EXEC DLI Commands for CICS and IMS

Publication No. SC26-9424-01

Overall, how satisfied are you with the information in this book?

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedOverall satisfaction h h h h h

How satisfied are you that the information in this book is:

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedAccurate 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 anyway it believes appropriate without incurring any obligation to you.

Name Address

Company or Organization

Phone No.

Readers’ Comments — We’d Like to Hear from YouSC26-9424-01

SC26-9424-01

��Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

International Business Machines CorporationDepartment BWE/H3P.O. Box 49023San Jose, CA95161-9945

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

Program Number: 5655-B01

Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

SC26-9424-01

Spine information:

�� IMS Version 7Application Programming: EXEC DLI Commands forCICS and IMS

application programming exec dli commands for cics and ims

Documents