You are on page 1of 189

IMS Version 7

Application Programming: EXEC DLI Commands for CICS and IMS

SC26-9424-01

IMS Version 7

Application Programming: EXEC DLI Commands for CICS and IMS

SC26-9424-01

Note Before using this information and the product it supports, be sure to read the general information under “Notices” on page xiii.

Second Edition (June 2001) (Softcopy Only) This edition replaces and makes obsolete the previous edition, SC26-9424-00. This edition is available in softcopy format only. The technical changes for this version are summarized under “Summary of Changes” on page xxi. The technical changes for this edition are indicated by a 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 Contract with IBM Corp.

Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Notices . . . . . . . . . . Programming Interface Information. Trademarks . . . . . . . . . Product Names. . . . . . . . Preface . . . . . . . . Summary of Contents . . . Prerequisite Knowledge . . Syntax Diagrams. . . . . How to Send Your Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii . xv . xv . xvi . . . .

xvii xvii xvii xviii . . . . . . . . . . . . . . . . . . . xx . for . . . . IMS . . . . . . . Version . . . . . . . 7 . . . . . . . . . . . . . . . . . . . . . . . . . . xxi xxi xxi xxi

|

Summary of Changes . . . . . . . . Changes to The Current Version of This Book Changes to This Book for IMS Version 7 . . Library Changes for IMS Version 7 . . . .

Part 1. Writing Application Programs. . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7 Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7 A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8 Chapter 2. Writing EXEC DLI Commands Using the I/O PCB, PSB, and PCB . . . I/O PCB . . . . . . . . . . . . Alternate PCB . . . . . . . . . . DB PCB . . . . . . . . . . . . GSAM PCB . . . . . . . . . . . Format of a PSB . . . . . . . . . PCB Summary . . . . . . . . . . Specifying an EXEC DLI Command . . . Summary of EXEC DLI Commands . . . EXEC DLI Commands . . . . . . . . DLET Command . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Example . . . . . . . . . . . . Restrictions . . . . . . . . . . . GN Command . . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Examples . . . . . . . . . . . . Restrictions . . . . . . . . . . . GNP Command . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . .
© Copyright IBM Corp. 2000, 2001

for . . . . . . . . . . . . . . . . . . . . . . . . . .

Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

11 11 11 11 11 11 12 12 13 13 14 15 15 15 16 16 16 17 17 18 21 21 22 22 22 23 26

iii

Examples . . . . . . Restrictions . . . . . GU Command . . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Restriction . . . . . ISRT Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Restrictions . . . . . POS Command. . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Restriction . . . . . REPL Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Restrictions . . . . . RETRIEVE Command . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Restrictions . . . . . SCHD Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . TERM Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Example . . . . . . System Service Commands ACCEPT Command . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Example . . . . . . CHKP Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Restrictions . . . . . DEQ Command . . . . Format . . . . . . . Option . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27 27 28 28 29 32 32 33 33 34 34 37 38 38 39 39 39 40 40 40 41 41 42 43 44 44 45 45 45 46 46 46 46 46 47 47 47 47 47 47 48 48 49 49 49 49 49 49 49 49 49 50 50 50 50 51

iv

Application Programming: EXEC DLI Commands for CICS and IMS

Usage . . . . . Example . . . . Restriction . . . LOAD Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . LOG Command. . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restriction . . . QUERY Command . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . Restrictions . . . REFRESH Command Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . . ROLB Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . . ROLL Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . . ROLS Command . . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . Restrictions . . . SETS Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . . SETU Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

51 51 51 51 52 52 52 52 52 53 53 53 53 53 53 53 53 53 54 54 54 54 54 54 54 55 55 55 55 55 55 55 56 56 56 56 56 56 57 57 57 57 57 58 58 58 58 59 59 59 59 59 60 60 60 60

Contents

v

STAT Command . . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . SYMCHKP Command Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . . XRST Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restrictions . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . to . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

60 61 61 61 61 61 61 62 62 63 63 63 63 63 64 65 65 67 67 67 68 68 71 71 72 72 72 73 73 74 78 81 85 91 91 91 92

Chapter 3. Defining Application Program Elements Specifying an Application Interface Block (AIB) . . . AIB Mask . . . . . . . . . . . . . . . . CICS Restrictions with AIB support . . . . . . Specifying the DL/I Interface Block (DIB) . . . . . Defining a Key Feedback Area . . . . . . . . . Defining I/O Areas. . . . . . . . . . . . . . COBOL I/O Area . . . . . . . . . . . . . PL/I I/O Area. . . . . . . . . . . . . . . Assembler Language I/O Area . . . . . . . .

IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4. More about Writing Your Application Program Programming Guidelines . . . . . . . . . . . . . Coding a Program in Assembler Language . . . . . Coding a Program in COBOL . . . . . . . . . . Coding a Program in PL/I . . . . . . . . . . . . Coding a Program in C . . . . . . . . . . . . . Preparing Your EXEC DLI Program for Execution . . . . Translator Options Required for EXEC DLI . . . . . Compiler Options Required for EXEC DLI . . . . . . Linkage Editor Options Required for EXEC DLI . . . .

Chapter 5. Processing Fast Path Databases . . . . . . Processing DEDBs with Subset Pointers . . . . . . . . Before You Use Subset Pointers . . . . . . . . . . Designating Subset Pointers You Want to Use . . . . . Using Subset Pointers . . . . . . . . . . . . . . Subset Pointer Status Codes . . . . . . . . . . . The POS Command . . . . . . . . . . . . . . . Locating a Specific Sequential Dependent . . . . . . Locating the Last Inserted Sequential Dependent Segment Identifying Free Space . . . . . . . . . . . . . The P Processing Option. . . . . . . . . . . . . Chapter 6. Recovering Databases and Maintaining Issuing Checkpoints in a Batch or BMP Program . . Issuing the CHKP Command . . . . . . . . Issuing the SYMCHKP Command . . . . . .

. 93 . 93 . 94 . 95 . 95 . 101 . 102 . 102 . 102 . 103 . 103

Database . . . . . . . . . . . .

Integrity 105 . . . . . . 105 . . . . . . 105 . . . . . . 106

vi

Application Programming: EXEC DLI Commands for CICS and IMS

Restarting Your Program and Checking for Position . . . . . . . Backing Out Database Updates Dynamically: The ROLL and ROLB Commands . . . . . . . . . . . . . . . . . . . . . Using Intermediate Backout Points: The SETS and ROLS Commands SETS Command . . . . . . . . . . . . . . . . . . . ROLS Command. . . . . . . . . . . . . . . . . . .

. . . . 106 . . . . . . . . . . . . . . . . 106 106 107 107

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

Part 2. For Your Reference . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 8. Comparing Command-Level and Call-Level Programs . . . . 113 Chapter 9. DL/I Status Codes . Status Code Tables . . . . . . Categories of DL/I Status Codes Status Code Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 117 117 127

Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 153 IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 153 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Contents

vii

viii

Application Programming: EXEC DLI Commands for CICS and IMS

Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. The Structure of a Command-Level Batch or BMP Program . . . . . . . . . . . . . . . 7 Medical Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 PATIENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 ILLNESS Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 TREATMNT Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 BILLING Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 PAYMENT Segment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 HOUSHOLD Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 General Format of a PSB. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Processing a Long Chain of Segment Occurrences with Subset Pointers . . . . . . . . . . 93 Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . . . 94 More Examples of Setting Subset Pointers . . . . . . . . . . . . . . . . . . . . . 94 How Subset Pointers Divide a Chain into Subsets . . . . . . . . . . . . . . . . . . 94 Processing Performed for the Sample Passbook Example. . . . . . . . . . . . . . . . 96 Retrieving the First Segment in a Chain of Segments . . . . . . . . . . . . . . . . . 97 Moving the Subset Pointer to the Next Segment after Your Current Position . . . . . . . . . 98 Unconditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . . . . 99 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. 2. 3. 4. 5. 6. 7. 8. Summary of PCB Information . . . . . . . . . . . . . . . . . . . . . . Summary of EXEC DLI Commands . . . . . . . . . . . . . . . . . . . . DL/I Calls Available to IMS and CICS Command-Level Application Programs . . . . Comparing Call-Level and Command-Level Programs: Commands and Calls . . . . Comparing Call-Level and Command-Level Programs: Command Codes and Options . Database Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . System Service Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 . 13 . 113 . 113 . 114 . 117 . 122 . 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. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs
© Copyright IBM Corp. 2000, 2001

xiii

and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J74/G4 555 Bailey Avenue P.O. Box 49023 San Jose, CA 95161-9023 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute

xiv

Application Programming: EXEC DLI Commands for CICS and IMS

these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM’s application programming interfaces. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: © (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming Interface Information
This book is intended to help the application programmer write IMS application programs. This book primarily documents General-use Programming Interface and Associated Guidance Information provided by IMS. General-use programming interfaces allow the customer to write programs that obtain the services of IMS. However, this book also documents Product-sensitive Programming Interface and Associated Guidance Information provided by IMS. Product-sensitive programming interfaces allow the customer installation to perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or tuning of IMS. Use of such interfaces creates dependencies on the detailed design or implementation of the IBM software product. Product-sensitive programming interfaces should be used only for these specialized purposes. Because of their dependencies on detailed design and implementation, it is to be expected that programs written to such interfaces may need to be changed to run with new product releases or versions, or as a result of service. Product-sensitive Programming Interface and Associated Guidance Information is identified where it occurs, either by an introductory statement to a chapter or section or by the following marking: Product-sensitive programming interface Product-sensitive Programming Interface and Associated Guidance Information. End of Product-sensitive programming interface

Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
C/370 CICS CICS/ESA CICS/MVS DATABASE 2 DB2 IBM IMS IMS/ESA MVS MVS/ESA RACF
Notices

xv

BookManager

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

Product Names
In v v v v this book, the licensed programs have shortened names: “COBOL for MVS & VM” is referred to as “COBOL”. “DB2 for MVS” is referred to as “DB2”. “CICS for MVS” is referred to as “CICS”. “CICS Transaction Server for OS/390” is referred to as “CICS”.

xvi

Application Programming: EXEC DLI Commands for CICS and IMS

Preface
This book is for CICS application programmers whose programs use EXEC DLI commands in an IMS environment. This book lists and describes the EXEC DLI commands, and explains the procedures for writing application programs. For information on using databases (such as, position in the database, using multiple positioning, and using secondary indexing and logical relationships), see IMS Version 7 Application Programming: Database Manager. | | | | This edition is available only in PDF and BookManager formats. This book is available on the IMS Version 7 Licensed Product Kit (LK3T-2326). You can also get the most current versions of the PDF and BookManager formats by going to the IMS Web site at www.ibm.com/ims and linking to the Library page.

Summary of Contents
This book has two parts: Part 1 (“Chapter 1. How Your EXEC DLI Application Program Works with IMS” on page 7through “Chapter 7. Using Data Availability Enhancements” on page 109) explains the basics of writing the DL/I part of your application program with EXEC DLI commands. “Part 2. For Your Reference” on page 111 contains reference information about the parts of an IMS command-level application program such as EXEC DLI commands, system service calls, qualification statements, EXEC DLI options, the DIB (DL/I Interface Block), I/O areas, and status codes. These chapters are for experienced programmers who understand IMS application programming and need only to look up a fact such as the meaning of a particular status code. If you are one of those programmers, you may also want to have on hand IMS/ESA Application Programming: EXEC DLI Commands for CICS and IMS Summary. “Bibliography” on page 153 lists all the non-IMS publications referred to in this book.

Prerequisite Knowledge
| | | | | | | IBM offers a wide variety of classroom and self-study courses to help you learn IMS. 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 General Information 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 familiar with the principles covered in CICS/ESA Application Programming Guide and in other CICS documentation. Before using this book, you should understand the concepts of application design presented in IMS Version 7 Application Programming: Design Guide. This book is a follow-on to IMS Version 7 Application Programming: Design Guide and also refers to IMS Version 7 Application Programming: Database Manager for
© 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 information in other publications, see IMS Version 7 Master Index and Glossary.

Syntax Diagrams
The following rules apply to the syntax diagrams used in this book: Arrow symbols Read the syntax diagrams from left to right, from top to bottom, following the path of the line. ─── ─── ─── ─── Indicates the beginning of a statement. Indicates that the statement syntax is continued on the next line. Indicates that a statement is continued from the previous line. Indicates the end of a statement.

Diagrams of syntactical units other than complete statements start with the ─── symbol and end with the ─── symbol. Conventions v Keywords, their allowable synonyms, and reserved parameters, appear in uppercase for MVS and OS/2 operating systems, and lowercase for UNIX operating systems. These items must be entered exactly as shown. v Variables appear in lowercase italics (for example, column-name). They represent user-defined parameters or suboptions. v When entering commands, separate parameters and keywords by at least one blank if there is no intervening punctuation. v Enter punctuation marks (slashes, commas, periods, parentheses, quotation marks, equal signs) and numbers exactly as given. v Footnotes are shown by a number in parentheses, for example, (1). v A symbol indicates one blank position. Required items Required items appear on the horizontal line (the main path).
REQUIRED_ITEM

Optional Items Optional items appear below the main path.
REQUIRED_ITEM optional_item

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

xviii

Application Programming: EXEC DLI Commands for CICS and IMS

Multiple required or optional items If you can choose from two or more items, they appear vertically in a stack. If you must choose one of the items, one item of the stack appears on the main path.
REQUIRED_ITEM required_choice1 required_choice2

If choosing one of the items is optional, the entire stack appears below the main path.
REQUIRED_ITEM optional_choice1 optional_choice2

Repeatable items An arrow returning to the left above the main line indicates that an item can be repeated.

REQUIRED_ITEM

repeatable_item

If the repeat arrow contains a comma, you must separate repeated items with a comma.
, REQUIRED_ITEM repeatable_item

A repeat arrow above a stack indicates that you can specify more than one of the choices in the stack. Default keywords IBM-supplied default keywords appear above the main path, and the remaining choices are shown below the main path. In the parameter list following the syntax diagram, the default choices are underlined.
default_choice REQUIRED_ITEM optional_choice optional_choice

IMS-specific syntax information Fragments Sometimes a diagram must be split into fragments. The fragments are represented by a letter or fragment name, set off like this: | A |. The fragment follows the end of the main diagram. The following example shows the use of a fragment.

Preface

xix

STATEMENT

item 1

item 2

A

A:
item 3 item 4 KEYWORD item 5 item 6

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

where <A> is:
EITHER OR

Parameter endings Parameters with number values end with the symbol '#', parameters that are names end with 'name', and parameters that can be generic end with '*'.
/MSVERIFY MSNAME msname SYSID sysid#

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

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

| |

xx

Application Programming: EXEC DLI Commands for CICS and IMS

Summary of Changes
| | |

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

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

Library Changes for IMS Version 7
| | | | | | | | The major change to the IMS Version 7 library is that it is available not only in hardcopy and in softcopy on BookManager, but also in softcopy Portable Document Format (PDF). The complete library is available in BookManager and PDF on the IMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7 softcopy library is available on the Transaction Processing and Data CD-ROM (SK2T-0730) and the OS/390 Collection CD-ROM (SK2T-6700) in BookManager. The unlicensed IMS Version 7 softcopy library is available in BookManager and PDF on the Web at http://www.ibm.com/ims Other changes include changes to these following books: v IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference The book formerly titled IMS/ESA Common Queue Server Guide and Reference in the Version 6 library is called IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference. The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is divided into two parts: ″Part 1: Common Queue Server,″ and ″Part 2: Base Primitive Environment.″ The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is now an unlicensed book. v IMS Version 7 Command Reference The book formerly titled IMS/ESA Operator’s Reference in the Version 6 library is called IMS Version 7 Command Reference. v IMS Version 7 Utilities Reference: Database and Transaction Manager The books formerly titled IMS/ESA Utilities Reference: Database Manager and IMS/ESA Utilities Reference: Transaction Manager in the Version 6 library have been combined into one book called IMS Version 7 Utilities Reference: Database and Transaction Manager. v IMS Version 7 Application Programming: Database Manager and IMS Version 7 Customization Guide The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved from the IMS Version 7 Application Programming: Database Manager to the IMS Version 7 Customization Guide. v IMS Version 7 Sample Operating Procedures For IMS Version 7, this book is available only in BookManager and PDF softcopy on the product kit (LK3T-3526), the OS/390 Collection CD-ROM (SK2T-6700), and on the Web at: http://www.ibm.com/ims
© Copyright IBM Corp. 2000, 2001

xxi

| | |

The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). As a new book, the IJUG is available only in PDF softcopy on the product kit (LK3T-3526) and on the Web at: http://www.ibm.com/ims

xxii

Application Programming: EXEC DLI Commands for CICS and IMS

Part 1. Writing Application Programs
Chapter 1. How Your EXEC DLI Application Program Works with IMS . . . 7 Getting Started with EXEC DLI . . . . . . . . . . . . . . . . . . . 7 A Sample Hierarchy . . . . . . . . . . . . . . . . . . . . . . . 8 Chapter 2. Writing EXEC DLI Commands Using the I/O PCB, PSB, and PCB . . . I/O PCB . . . . . . . . . . . . Alternate PCB . . . . . . . . . . DB PCB . . . . . . . . . . . . GSAM PCB . . . . . . . . . . . Format of a PSB . . . . . . . . . PCB Summary . . . . . . . . . . DB Batch Programs . . . . . . . BMPs, MPPs, and IFPs. . . . . . CICS Programs with DBCTL . . . . Specifying an EXEC DLI Command . . . Summary of EXEC DLI Commands . . . EXEC DLI Commands . . . . . . . . DLET Command . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Example . . . . . . . . . . . . Explanation . . . . . . . . . . Restrictions . . . . . . . . . . . GN Command . . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Examples . . . . . . . . . . . . Example 1 . . . . . . . . . . Example 2 . . . . . . . . . . Example 3 . . . . . . . . . . Restrictions . . . . . . . . . . . GNP Command . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Examples . . . . . . . . . . . . Example 1 . . . . . . . . . . Example 2 . . . . . . . . . . Restrictions . . . . . . . . . . . GU Command . . . . . . . . . . . Format . . . . . . . . . . . . . Options. . . . . . . . . . . . . Usage . . . . . . . . . . . . . Examples . . . . . . . . . . . . Example 1 . . . . . . . . . . Example 2 . . . . . . . . . . Example 3 . . . . . . . . . . Restriction . . . . . . . . . . . ISRT Command . . . . . . . . . . Format . . . . . . . . . . . . .
© Copyright IBM Corp. 2000, 2001

for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 11 11 11 11 11 12 12 12 12 12 13 13 14 15 15 15 16 16 16 16 17 17 18 21 21 21 21 21 22 22 22 23 26 27 27 27 27 28 28 29 32 32 32 33 33 33 33 34

1

Options. . . . . . . Usage . . . . . . . Examples . . . . . . Example 1 . . . . Example 2 . . . . Example 3 . . . . Restrictions . . . . . POS Command. . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Restriction . . . . . REPL Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Example 1 . . . . Example 2 . . . . Example 3 . . . . Example 4 . . . . Restrictions . . . . . RETRIEVE Command . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Explanation . . . . Restrictions . . . . . SCHD Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Explanation . . . . TERM Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Example . . . . . . Explanation . . . . System Service Commands ACCEPT Command . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Example . . . . . . CHKP Command . . . . Format . . . . . . . Options. . . . . . . Usage . . . . . . . Examples . . . . . . Explanation . . . . Restrictions . . . . . DEQ Command . . . . Format . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

34 37 38 38 38 38 38 39 39 39 40 40 40 41 41 42 43 43 43 44 44 44 44 45 45 45 46 46 46 46 46 46 47 47 47 47 47 47 47 48 48 48 49 49 49 49 49 49 49 49 49 50 50 50 50 50

2

Application Programming: EXEC DLI Commands for CICS and IMS

Option . . . . . Usage . . . . . Example . . . . Explanation . . Restriction . . . LOAD Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . LOG Command. . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Restriction . . . QUERY Command . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . Example 1 . . Example 2 . . Restrictions . . . REFRESH Command Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . ROLB Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . ROLL Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . ROLS Command . . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . Example 1 . . Example 2 . . Example 3 . . Restrictions . . . SETS Command . . Format . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

51 51 51 51 51 51 52 52 52 52 52 53 53 53 53 53 53 53 53 53 54 54 54 54 54 54 54 54 54 54 55 55 55 55 55 55 55 55 56 56 56 56 56 56 56 57 57 57 57 57 57 58 58 58 58 58

Part 1. Writing Application Programs

3

Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . SETU Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . STAT Command . . Format . . . . . Options. . . . . Usage . . . . . Examples . . . . SYMCHKP Command Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . . XRST Command . . Format . . . . . Options. . . . . Usage . . . . . Example . . . . Explanation . . Restrictions . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . to . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

58 59 59 59 59 59 59 60 60 60 60 60 60 61 61 61 61 61 61 62 62 63 63 63 63 63 63 64 65 65 65 67 67 67 68 68 71 71 72 72 72 73 73 74 78 81 85 91 91 91 92

Chapter 3. Defining Application Program Elements Specifying an Application Interface Block (AIB) . . . AIB Mask . . . . . . . . . . . . . . . . CICS Restrictions with AIB support . . . . . . Specifying the DL/I Interface Block (DIB) . . . . . Defining a Key Feedback Area . . . . . . . . . Defining I/O Areas. . . . . . . . . . . . . . COBOL I/O Area . . . . . . . . . . . . . PL/I I/O Area. . . . . . . . . . . . . . . Assembler Language I/O Area . . . . . . . .

IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4. More about Writing Your Application Program Programming Guidelines . . . . . . . . . . . . . Coding a Program in Assembler Language . . . . . Coding a Program in COBOL . . . . . . . . . . Coding a Program in PL/I . . . . . . . . . . . . Coding a Program in C . . . . . . . . . . . . . Preparing Your EXEC DLI Program for Execution . . . . Translator Options Required for EXEC DLI . . . . . Compiler Options Required for EXEC DLI . . . . . . Linkage Editor Options Required for EXEC DLI . . . .

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

4

Application Programming: EXEC DLI Commands for CICS and IMS

Before You Use Subset Pointers . . . . . . . . . . . . . . . . Designating Subset Pointers You Want to Use . . . . . . . . . . . Using Subset Pointers . . . . . . . . . . . . . . . . . . . . Our Sample Application. . . . . . . . . . . . . . . . . . . Retrieving the First Segment in the Subset with the GETFIRST Option Setting the Subset Pointers with the SETZERO, MOVENEXT, SET, and SETCOND Options . . . . . . . . . . . . . . . . . . . Inserting Segments in a Subset . . . . . . . . . . . . . . . Deleting the Segment Pointed to By a Subset Pointer . . . . . . . Combining Options . . . . . . . . . . . . . . . . . . . . Subset Pointer Status Codes . . . . . . . . . . . . . . . . . The POS Command . . . . . . . . . . . . . . . . . . . . . Locating a Specific Sequential Dependent . . . . . . . . . . . . Locating the Last Inserted Sequential Dependent Segment . . . . . . Identifying Free Space . . . . . . . . . . . . . . . . . . . The P Processing Option. . . . . . . . . . . . . . . . . . . Chapter 6. Recovering Databases and Maintaining Database Integrity Issuing Checkpoints in a Batch or BMP Program . . . . . . . . . . Issuing the CHKP Command . . . . . . . . . . . . . . . . Issuing the SYMCHKP Command . . . . . . . . . . . . . . Restarting Your Program and Checking for Position . . . . . . . . . Backing Out Database Updates Dynamically: The ROLL and ROLB Commands . . . . . . . . . . . . . . . . . . . . . . . Using Intermediate Backout Points: The SETS and ROLS Commands . . SETS Command . . . . . . . . . . . . . . . . . . . . . ROLS Command. . . . . . . . . . . . . . . . . . . . .

. . . .

94 95 95 95 96

. . . . . . . . .

. 97 101 101 101 101 102 102 102 103 103 105 105 105 106 106 106 106 107 107

. . . . . . . .

. . . . . . . .

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

Part 1. Writing Application Programs

5

6

Application Programming: EXEC DLI Commands for CICS and IMS

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

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

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

Notes to Figure 1: 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 the lowest-level segment retrieved to the key feedback area.

© Copyright IBM Corp. 2000, 2001

7

Getting Started with EXEC DLI
3 DL/I Interface Block (DIB). DL/I and CICS place the results of each command in the DIB. The DIB contains most of the same information returned in the DB PCB for programs using the call-level interface. 4 Program entry. Control is passed to your program during program entry. 5 Issue EXEC DLI commands. Commands read and update information in the database. 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 DLI command for database processing and after issuing a checkpoint command. 7 Issue checkpoint. Issue checkpoints as needed to establish places from which to restart. Issuing a checkpoint commits database changes and releases resources. 8 Terminate. This returns control to the operating system, commits database changes, and releases resources. Requirement: CICS/ESA Version 4, or later, and CICS Transaction Server run with this version of IMS. Unless a distinction needs to made, all supported versions are referred to as CICS.

A Sample Hierarchy
Many of the examples in this book use the medical hierarchy shown in the following graphic. The database contains information that a medical clinic might keep about its patients. To understand the examples, you should be familiar with the hierarchy and the segments it contains.

Figure 2. Medical Hierarchy

The figures that follow show the layouts of the segments in the hierarchy. The number below each field is the length in bytes that has been defined for that field. v PATIENT Segment The following graphic shows the PATIENT segment. It has three fields: patient number (PATNO), patient name (NAME), and the patient’s address (ADDR). PATIENT has a unique key field: PATNO. PATIENT segments are stored in ascending order of their patient numbers. The lowest patient number in the database is 00001 and the highest is 10500.

Figure 3. PATIENT Segment

v ILLNESS Segment

8

Application Programming: EXEC DLI Commands for CICS and IMS

A Sample Hierarchy
The following graphic shows the ILLNESS segment. It has two fields: the date when the patient came to the clinic with the illness (ILLDATE) and the name of the illness (ILLNAME). The key field is ILLDATE. Because it is possible for a patient to come to the clinic with more than one illness on the same date, this key field is nonunique, that is, there may be more than one ILLNESS segment with the same (an equal) key field value. Usually someone in the installation, such as the database administrator (DBA), decides the order in which segments in the database having equal keys or no keys will be placed. The DBA can use the RULES keyword of the SEGM statement of the DBD to specify this. For segments with equal keys or no keys, RULES determines where the segment is inserted. Where RULES=LAST, ILLNESS segments that have equal keys are stored on a first-in first-out basis among those with equal keys. ILLNESS segments with unique keys are stored in ascending order on the date field, regardless of RULES. ILLDATE is specified in the format YYYYMMDD.

Figure 4. ILLNESS Segment

v TREATMNT Segment The following graphic shows the TREATMNT segment. It – – – contains four fields: The date of the treatment (DATE) The medicine that was given to the patient (MEDICINE) The quantity of the medicine that the patient was given (QUANTITY)

– The name of the doctor who prescribed the treatment (DOCTOR) The key field of the TREATMNT segment is DATE. Because a patient may receive more than one treatment on the same date, DATE is a nonunique key field. TREATMNT, like ILLNESS, has been specified as having RULES=LAST. TREATMNT segments are also stored on a first-in-first-out basis. DATE is specified in the same format as ILLDATE—YYYYMMDD.

Figure 5. TREATMNT Segment

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

Figure 6. BILLING Segment

v PAYMENT Segment

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

9

A Sample Hierarchy
The following graphic shows the PAYMENT segment. It also has only one field—the amount of each payment remitted. The PAYMENT segment has no key field.

Figure 7. PAYMENT Segment

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

Figure 8. HOUSHOLD Segment

10

Application Programming: EXEC DLI Commands for CICS and IMS

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

Using the I/O PCB, PSB, and PCB
A PSB used in a DBCTL environment can contain any of the following PCB types: v I/O PCB v Alternate PCBs v DB PCBs v GSAM PCBs

I/O PCB
In a DBCTL environment, an I/O PCB is needed to issue DBCTL service requests. Unlike the other types of PCB, it is not defined with PSB generation, but if the application program is using an I/O PCB, this has to be indicated in the PSB scheduling request.

Alternate PCB
An alternate PCB defines a logical terminal and can be used instead of the I/O PCB when it is necessary to direct a response to a terminal. Alternate PCBs appear in PSBs used in a CICS-DBCTL environment, but are used only in an IMS DC environment. CICS applications using DBCTL cannot successfully issue commands that specify an alternate PCB, an MSDB PCB, or a GSAM PCB. However, a PSB that contains PCBs of these types can be scheduled successfully in a CICS-DBCTL environment. Alternate PCBs are included in the PCB address list returned to a call level application program. In an EXEC DLI application program, the existence of alternate PCBs in the PSB affects the PCB number used in the PCB keyword.

DB PCB
A database PCB (DB PCB) is the PCB that defines an application program’s interface to a database. One DB PCB is needed for each database view used by the application program. It can be a full-function PCB, a DEDB PCB, or an MSDB PCB.

GSAM PCB
A GSAM PCB defines an application program’s interface for GSAM operations. When using DBCTL, a CICS program receives, by default, a DB PCB as the first PCB in the parameter list passed to it after scheduling. However, when your application program can handle an I/O PCB, you indicate this using the SYSSERVE keyword on the SCHD command. The I/O PCB is then the first PCB in the parameter address list passed back to your application program.

© Copyright IBM Corp. 2000, 2001

11

I/O PCB, PSB, and PCB

Format of a PSB
The format of a PSB is shown in Figure 9.
[IOPCB] [Alternate PCB ... Alternate PCB] [DBPCB ... DBPCB] [GSAMPCB ... GSAMPCB]

Figure 9. General Format of a PSB

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

PCB Summary
The following section summarizes the information concerning I/O PCBs and alternate PCBs in various types of application programs. Recommendation: You should read the following section if you intend to issue system service requests.

DB Batch Programs
Alternate PCBs are always included in the list of PCBs supplied to the program by DL/I irrespective of whether you have specified CMPAT=Y. The I/O PCB is returned depending on the CMPAT option. If you specify CMPAT=Y, the PCB list contains the address of the I/O PCB, followed by the addresses of any alternate PCBs, followed by the addresses of any DB PCBs. If you do not specify CMPAT=Y, the PCB list contains the addresses of any alternate PCBs followed by the addresses of the DB PCBs.

BMPs, MPPs, and IFPs
I/O PCBs and alternate PCBs are always passed to BMP programs. I/O PCBs and alternate PCBs are also always passed to MPPs and to MDPs (message-driven programs), which are described in IMS Version 7 Application Programming: Design Guide. The PCB list contains the address of the I/O PCB, followed by the addresses of any alternate PCBs, followed by the addresses of the DB PCBs.

CICS Programs with DBCTL
The first PCB always refers to the first DB PCB whether you specify the SYSSERVE keyword. Table 1 summarizes the I/O PCB and alternate PCB information.
Table 1. Summary of PCB Information EXEC DLI Environment CICS DBCTL1 I/O PCB count included in PCB(n) No Alternate PCB count included in PCB(n) No

12

Application Programming: EXEC DLI Commands for CICS and IMS

I/O PCB, PSB, and PCB
Table 1. Summary of PCB Information (continued) EXEC DLI Environment CICS DBCTL2 BMP Batch Batch
3 4

I/O PCB count included in PCB(n) No Yes No Yes

Alternate PCB count included in PCB(n) No Yes Yes Yes

Notes: 1. SCHD command issued without the SYSSERVE option. 2. SCHD command issued with the SYSSERVE option for a CICS DBCTL command or for a function-shipped command which is satisfied by a remote CICS system using DBCTL. 3. CMPAT=N specified on the PSBGEN statement. 4. CMPAT=Y specified on the PSBGEN statement.

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

Summary of EXEC DLI Commands
A summary of all the EXEC DLI commands is provided in Table 2.
Table 2. Summary of EXEC DLI Commands Program Characteristics Request Type ACCEPT command4 CHKP command DEQ command
4 4

Batch Yes Yes Yes Yes
4

BatchOriented BMP Yes Yes Yes Yes Yes Yes Yes Yes

CICS with DBCTL1 Yes No Yes Yes Yes Yes Yes Yes

DLET command Get commands (GU, GHU, GN, GHN, GNP, GHNP) GMSG command5 ICMD command5 ISRT command4

Yes No No Yes

Chapter 2. Writing EXEC DLI Commands for Your Application Program

13

Summary of EXEC DLI Commands
Table 2. Summary of EXEC DLI Commands (continued) Program Characteristics Request Type LOAD command LOG command POS command
4 4 4

Batch Yes Yes No Yes No
4 5

BatchOriented BMP No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes No Yes

CICS with DBCTL1 No Yes Yes Yes Yes Yes Yes No No No Yes Yes Yes No Yes No Yes No

QUERY command RCMD command

REFRESH command REPL command
4

Yes Yes Yes Yes Yes

RETRIEVE command ROLB command ROLL command ROLS command , SCHD command SETS command , SETU command STAT command ,
3 4 2 4 2 4

Yes No Yes Yes Yes Yes No Yes

SYMCHKP command TERM command XRST command Notes:

1. In a CICS remote DL/I environment, commands in the CICS with DBCTL column are supported if you are shipping a function to a remote CICS that uses DBCTL. 2. ROLS and SETS commands are not valid when the PSB contains a DEDB. 3. STAT is a Product-sensitive programming interface. 4. Are supported in the AIB format. 5. Are described in the AOI documentation within the IMS/ESA Operations Guide.

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

14

Application Programming: EXEC DLI Commands for CICS and IMS

EXEC DLI Commands
v v v v v v v v v v v v v v v v v “SCHD Command” on page 46 “TERM Command” on page 47 “ACCEPT Command” on page 49 “CHKP Command” on page 49 “DEQ Command” on page 50 “LOAD Command” on page 51 “LOG Command” on page 52 “QUERY Command” on page 53 “REFRESH Command” on page 54 “ROLB Command” on page 55 “ROLL Command” on page 56 “ROLS Command” on page 57 “SETS Command” on page 58 “SETU Command” on page 59 “STAT Command” on page 60 “SYMCHKP Command” on page 61 “XRST Command” on page 63

The examples included with each command refer to the “A Sample Hierarchy” on page 8.

DLET Command
The Delete (DLET) command is used to remove a segment and its dependents from the database.

Format
EXEC DLI DLET USING PCB(expression) SEGMENT(name) SEGMENT((area)) VARIABLE FROM(area) SEGLENGTH(expression)

SETZERO(data_value)

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

Chapter 2. Writing EXEC DLI Commands for Your Application Program

15

DLET Command
SEGMENT((area)) Is a reference to an area in your program containing the name of the segment type. You can specify an area instead of specifying the name of the segment in the command. SEGLENGTH(expression) Specifies the length of the I/O area into which the segment is retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.) Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call. FROM(area) Specifies an area containing the segment to be added, replaced, or deleted. Use FROM to insert one or more segments with one command. SETZERO(data_value) Specifies setting a subset pointer to zero.

Usage
You use the DLET command to delete a segment and its dependents from the database. You must first retrieve segments you want to delete, just as if you were replacing segments, The DLET command deletes the retrieved segment and its dependents, if any, from the database.

Example
“Evelyn Parker has moved away from this area. Her patient number is 10450. Delete her record from the database.”

Explanation
You want to delete all the information about Evelyn Parker from the database. To do this, you must delete the PATIENT segment. When you do this, DL/I deletes all the dependents of that segment. This is exactly what you want DL/I to do—there is no reason to keep such segments as ILLNESS and TREATMNT for Evelyn Parker if she is no longer one of the clinic’s patients. Before you can delete the patient segment, you have to retrieve it:
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);

To delete this patient’s database record, you issue a DLET command and use the FROM option to give the name of the I/O area that contains the segment you want deleted:
EXEC DLI DLET SEGMENT(PATIENT) FROM(PATAREA);

When you issue this command, the PATIENT segment, and its dependents—the ILLNESS, TREATMNT, BILLING, PAYMENT, and HOUSHOLD segments—are deleted.

Restrictions
You cannot issue any commands using the same PCB between the retrieval command and the DLET command, and you can issue only one DLET command for each GET command.

16

Application Programming: EXEC DLI Commands for CICS and IMS

GN Command

GN Command
The GN command is used to retrieve segments sequentially.

Format
EXEC DLI GET NEXT GN USING PCB(expression)

(1) INTO(area) KEYFEEDBACK(area) FEEDBACKLEN(expression)

<A>

<B>

<A> For each parent segment (optional):
VARIABLE FIRST LAST CURRENT SEGMENT(name) SEGMENT((area)) SEGLENGTH(expression)

OFFSET(expression) INTO(area)

(2)

LOCKED LOCKCLASS(class)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

SETPARENT

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

KEYS(area) (4) KEYLENGTH(expression)

<B> For the object segment (optional):
VARIABLE FIRST LAST SEGMENT(name) SEGMENT((area)) SEGLENGTH(expression)

Chapter 2. Writing EXEC DLI Commands for Your Application Program

17

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

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

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

KEYS(area) (4) KEYLENGTH(expression)

Notes: 1 2 3 4 If you leave out the SEGMENT option, specify the INTO option as shown. Specify INTO on parent segments for a path command. If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8) You can use either the KEYS option or the WHERE option, but not both on one segment level.

Options
USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. KEYFEEDBACK(area) Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated. FEEDBACKLEN(expression) Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs and optional in PL/I and assembler language programs.) INTO(area) Specifies an area into which the segment is read. VARIABLE Indicates that a segment is variable-length.

18

Application Programming: EXEC DLI Commands for CICS and IMS

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

19

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

20

Application Programming: EXEC DLI Commands for CICS and IMS

GN Command
“Area” specifies an area in your program containing the segment’s concatenated key. WHERE(qualification statement) Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. Each qualification statement consists of: v The name of a field in a segment v The relational operator, which indicates how you want the two values compared v The name of a data area in your program containing the value that is compared against the value of the field

Usage
Use the GN command to sequentially retrieve segments from the database. Each time you issue a GN command, IMS DB retrieves the next segment, as described by the options you include in the command. Before issuing a GN command, you should establish position in the database record by issuing a GU command. You do not have to use a segment option with a GN command. However, you should qualify your GN commands as much as possible with the KEYS or WHERE options after the SEGMENT option.

Examples
Example 1
“We need a list of all patients who have been to this clinic.” Explanation: To answer this request, your program would issue a command qualified with the segment name PATIENT until DL/I returned a GB status code to the program. (GB means that DL/I reached the end of the database before being able to satisfy your command.). This command looks like this:
EXEC DLI GN SEGMENT(PATIENT) INTO(PATAREA);

Each time your program issued this command, the current position moves forward to the next database record.

Example 2
“What are the names of the patients we have seen since the beginning of this month?” Explanation: A GN command that includes one or more WHERE or KEYS options retrieves the next occurrence of the specified segment type that satisfies the command. To answer this request, the program issues the GN command below until DL/I returned a GB status code. The example shows the command you use at the end of April, 1988 (assuming ILLDATE1 contains 198804010):
EXEC DLI GN SEGMENT(PATIENT) INTO(PATAREA) SEGMENT(ILLNESS) INTO(ILLAREA) WHERE(ILLDATE>=ILLDATE1);

Example 3
EXEC DLI GN INTO(PATAREA);

Chapter 2. Writing EXEC DLI Commands for Your Application Program

21

GN Command
Explanation: If you just retrieved the PATIENT segment for patient 04124 and then issued the above command, you retrieve the first ILLNESS segment for patient 04124.

Restrictions
With an unqualified GN command, the retrieved segment type might not be the one expected. Therefore, specify an I/O area large enough to contain the largest segment accessible to your program. Use either the KEYS option or the WHERE option, but not both on one segment level.

GNP Command
The Get Next in Parent (GNP) command is used to retrieve dependent segments sequentially.

Format
EXEC DLI GET NEXT IN PARENT GNP USING PCB(expression)

(1) INTO(area) KEYFEEDBACK(area) FEEDBACKLEN(expression)

<A>

<B>

<A> For each parent segment (optional):
VARIABLE FIRST LAST CURRENT SEGMENT(name) SEGMENT((area)) SEGLENGTH(expression)

OFFSET(expression) INTO(area)

(2)

LOCKED LOCKCLASS(class)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

SETPARENT

22

Application Programming: EXEC DLI Commands for CICS and IMS

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

KEYS(area) (4) KEYLENGTH(expression)

<B> For the object segment (optional):
VARIABLE FIRST LAST SEGMENT(name) SEGMENT((area)) SEGLENGTH(expression)

OFFSET(expression)

INTO(area)

LOCKED LOCKCLASS(class)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

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

KEYS(area) (4) KEYLENGTH(expression)

Notes: 1 2 3 4 If you leave out the SEGMENT option, specify the INTO option as shown. Specify INTO on parent segments for a path command. If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8) You can use either the KEYS option or the WHERE option, but not both on one segment level.

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

Chapter 2. Writing EXEC DLI Commands for Your Application Program

23

GNP Command
If you do not qualify your command, IMS DB retrieves the next sequential segment under the established parent. If you include a SEGMENT option, IMS DB retrieves the first occurrence of that segment type that it finds by searching forward under the established parent. You can have as many levels of qualification for a GNP command as there are levels in the database’s hierarchy. However, you should not qualify your command in a way that causes DL/I to move off of the segment type you have established as a parent for the command. USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. KEYFEEDBACK(area) Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated. Use this to retrieve a segment’s concatenated key. FEEDBACKLEN(expression) Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs and optional in PL/I and assembler language programs.) INTO(area) Specifies an area into which the segment is read. Use this to retrieve one or more segments with one command. VARIABLE Indicates that a segment is variable-length. FIRST Specifies that you want to retrieve the first segment occurrence of a segment type, or that you want to insert a segment as the first occurrence. Use this to retrieve the first segment occurrence of a segment type. LAST Specifies that you want to retrieve the last segment occurrence of a segment type, or that you want to insert a segment as the last segment occurrence. Use this to retrieve the last segment occurrence of a segment type. CURRENT Qualifies the command, and specifies that you want to use your current position at this level and above as qualification for this segment. Use this to retrieve a segment based on your current position. SEGLENGTH(expression) Specifies the length of the I/O area into which the segment is retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (SEGLENGTH is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.) Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call. OFFSET(expression) Specifies the offset to the destination parent. The argument can be any

24

Application Programming: EXEC DLI Commands for CICS and IMS

GNP Command
expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. Use OFFSET when you process concatenated segments in logical relationships. OFFSET is required whenever the destination parent is a variable-length segment. LOCKED Specifies that you want to retrieve a segment for the exclusive use of your program, until a checkpoint or sync point is reached. Use this to reserve a segment for the exclusive use of your program. This option performs the same function as the Q command code, and it applies to both Fast Path and full function. A 1-byte alphabetic character of ’A’ is automatically appended as the class for the Q command code. LOCKCLASS(class) Specifies that you want to retrieve a segment for the exclusive use of your program until a DEQ command is issued or until a checkpoint or sync point is reached. (DEQ commands are not supported for Fast Path.) Class is a 1-byte alphabetic character (B-J), representing the lock class of the retrieved segment. For full function code, the LOCKCLASS option followed by a letter (B-J) designates the class of the lock for the segment. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041. Fast Path does not support LOCKCLASS but, for consistency between full function and Fast Path, you must specify LOCKCLASS('x')), where x is a letter in the range B to J. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041. MOVENEXT(data_value) Specifies a subset pointer to be moved to the next segment occurrence after your current segment. GETFIRST(data_value) Specifies that you want the search to start with the first segment occurrence in a subset. SET(data_value) Specifies unconditionally setting a subset pointer to the current segment. SETCOND(data_value) Specifies conditionally setting a subset pointer to the current segment. SETZERO(data_value) Specifies setting a subset pointer to zero. SETPARENT Sets parentage at the level you want. WHERE(qualification statement) Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. Each qualification statement consists of: v The name of a field in a segment v The relational operator, which indicates how you want the two values compared v The name of a data area in your program containing the value that is compared against the value of the field

Chapter 2. Writing EXEC DLI Commands for Your Application Program

25

GNP Command
FIELDLENGTH(expression) Specifies the length of the field value in a WHERE option. KEYS(area) Qualifies the command with the segment’s concatenated key. You can use either KEYS or WHERE for a segment level, but not both. “Area” specifies an area in your program containing the segment’s concatenated key. KEYLENGTH(expression) Specifies the length of the concatenated key when you use the KEYS option. It can be any expression in the host language that converts to the integer data type; if it is a variable, it must be declared as a binary halfword value. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language, KEYLENGTH is optional. For COBOL programs that are not compiled with the IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify KEYLENGTH with the KEYS option. SEGMENT(name), SEGMENT((area)) Qualifies the command, specifying the name of the segment type or the area in your program containing the name of the segment type that you want to retrieve, insert, delete, or replace. You can have as many levels of qualification for a GNP command as there are levels in the database’s hierarchy. Using fully qualified commands with the WHERE or KEYS option clearly identifies the hierarchic path and the segment you want, and is useful in documenting the command. However, you do not need to qualify a GNP command at all, because you can specify a GNP command without the SEGMENT option. Once you have established position in the database record, issuing a GNP command without a SEGMENT option retrieves the next segment occurrence in sequential order. If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB retrieves the first occurrence of that segment type it encounters by searching forward from current position. With an unqualified GNP command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a retrieval command, you can find out from DIB the segment type retrieved.) If you fully qualify your command with a WHERE or KEYS option, you would retrieve the next segment in sequential order, as described by the options. Including the WHERE or KEYS options for parent segments defines the segment occurrences that are to be part of the path to the segment you want retrieved. Omitting the SEGMENT option for a level, or including only the SEGMENT option without a WHERE option, indicates that any path to the option satisfies the command. DL/I uses only the qualified parent segments and the lowest-level SEGMENT option to satisfy the command. DL/I does not assume a qualification for the missing level.

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

26

Application Programming: EXEC DLI Commands for CICS and IMS

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 dependent segments of the patient whose patient number is 09080; you do not want to retrieve all the dependents of each patient. To do this, use the GU command to establish your position and parentage on the PATIENT segment for Kate Bailey. Then continue to issue a GNP without SEGMENT or WHERE options until DL/I returns all the dependents of that PATIENT segment. (A GE status code indicates that you have retrieved all the dependent segments.) To answer the request above, your program could issue these commands:
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1); EXEC DLI GNP INTO(ILLAREA);

A GNP command without SEGMENT or WHERE options retrieves the first dependent segment occurrence under the current parent. If your current position is already on a dependent of the current parent, the above command retrieves the next segment occurrence under the parent. With an unqualified GNP command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a GNP command, you can find out from the DIB the segment type retrieved.)

Example 2
“Which doctors have been prescribing acetaminophen for headaches?” Explanation: A GNP command with only a SEGMENT option sequentially retrieves the dependent segments of the segment type you have specified under the established parent. Suppose that for this example, the key of ILLNESS is ILLNAME, and the key of TREATMNT is MEDICINE. You want to retrieve each TREATMNT segment where the treatment was acetaminophen. The name of the doctor who prescribed the treatment is part of the TREATMNT segment. (Assume that data area ILLNAME1 contains HEADACHE, and MEDIC1 contains ACETAMINOP.) To answer this request, you could issue these commands:
EXEC DLI GN SEGMENT(ILLNESS) WHERE (ILLNAME=ILLNAME1); EXEC DLI GNP SEGMENT(TREATMNT) WHERE (MEDICINE=MEDIC1);

To process this, your program continues issuing the GNP command until DL/I returned a GE (not found) status code, then your program retrieves the next headache segment and retrieves the TREATMNT segments for it. Your program does this until there were no more ILLNESS segments where the ILLNAME was headache.

Restrictions
The GNP command has the following restrictions: v You must have established parentage before issuing this command. v You cannot qualify your GNP command in a way that causes DL/I to move off of the segment type you have established as the parent for the command.
Chapter 2. Writing EXEC DLI Commands for Your Application Program

27

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

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

Format
EXEC DLI GET UNIQUE GU USING PCB(expression)

INTO(area) KEYFEEDBACK(area) FEEDBACKLEN(expression)

<A>

<B>

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

OFFSET(expression) INTO(area)

(1)

LOCKED LOCKCLASS(class)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

SETPARENT

WHERE(qualification statement) (2) FIELDLENGTH(expression)

KEYS(area) (3) KEYLENGTH(expression)

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

28

Application Programming: EXEC DLI Commands for CICS and IMS

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

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

WHERE(qualification statement) (2) FIELDLENGTH(expression)

KEYS(area) (3) KEYLENGTH(expression)

Notes: 1 2 3 Specify INTO on parent segments for a path command. If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8) You can use either the KEYS option or the WHERE option, but not both on one segment level.

Options
USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. KEYFEEDBACK(area) Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated. FEEDBACKLEN(expression) Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs and optional in PL/I and assembler language programs.) INTO(area) Specifies an area into which the segment is read. VARIABLE Indicates that a segment is variable-length. LAST Specifies that you want to retrieve the last segment occurrence of a segment type, or that you want to insert a segment as the last segment occurrence.
Chapter 2. Writing EXEC DLI Commands for Your Application Program

29

GU Command
SEGMENT(name), SEGMENT((area)) Qualifies the command, specifying the name of the segment type or the area in your program containing the name of the segment type that you want to retrieve, insert, delete, or replace. To retrieve the first occurrence of a segment type, you need only specify the SEGMENT option. You can specify as many levels of qualification as there are hierarchic levels defined by the PCB you are using. To establish position at the beginning of the database, issue a GU command with a SEGMENT option that names the root segment type. If you leave out SEGMENT options for one or more hierarchic levels, DL/I assumes a segment qualification for that level. The qualification that DL/I assumes depends on your current position. v If DL/I has a position established at the missing level, DL/I uses the segment on which position is established. v If DL/I does not have a position established at the missing level, DL/I uses the first occurrence at that level. v If DL/I moves forward from a position established at a higher level, DL/I uses the first occurrence at the missing level that falls within the new path. v If you leave out a SEGMENT option for the root level, and DL/I has position established on a root, DL/I does not move from that root when trying to satisfy the command. You can have as many levels of qualification for a GU command as there are levels in the database’s hierarchy. Using fully qualified commands with the WHERE or KEYS option clearly identifies the hierarchic path and the segment you want, and is useful in documenting the command. However, you do not need to qualify a GU command at all, because you can specify a GU command without the SEGMENT option. Once you have established position in the database record, issuing a GU command without a SEGMENT option retrieves the next segment occurrence in sequential order. If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB retrieves the first occurrence of that segment type it encounters by searching forward from current position. With an unqualified GU command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a retrieval command, you can find out from DIB the segment type retrieved.) If you fully qualify your command with a WHERE or KEYS option, you would retrieve the next segment in sequential order, as described by the options. Including the WHERE or KEYS options for parent segments defines the segment occurrences that are to be part of the path to the segment you want retrieved. Omitting the SEGMENT option for a level, or including only the SEGMENT option without a WHERE option, indicates that any path to the option satisfies the command. DL/I uses only the qualified parent segments and the lowest-level SEGMENT option to satisfy the command. DL/I does not assume a qualification for the missing level. SEGLENGTH(expression) Specifies the length of the I/O area into which the segment is retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (SEGLENGTH is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.)

30

Application Programming: EXEC DLI Commands for CICS and IMS

GU Command
Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call. OFFSET(expression) Specifies the offset to the destination parent. The argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. Use OFFSET when you process concatenated segments in logical relationships. OFFSET is required whenever the destination parent is a variable-length segment. LOCKED Specifies that you want to retrieve a segment for the exclusive use of your program, until a checkpoint or sync point is reached. This option performs the same function as the Q command code. It applies to both Fast Path and full function. A 1-byte alphabetic character of ’A’ is automatically appended as the class for the Q command code. LOCKCLASS(class) Specifies that you want to retrieve a segment for the exclusive use of your program until a DEQ command is issued or until a checkpoint or sync point is reached. (DEQ commands are not supported for Fast Path.) Class is a 1-byte alphabetic character (B-J), representing the lock class of the retrieved segment. For full function code, the LOCKCLASS option followed by a letter (B-J) designates the class of the lock for the segment. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041. Fast Path does not support LOCKCLASS but, for consistency between full function and Fast Path, you must specify LOCKCLASS('x')), where x is a letter in the range B to J. An example is LOCKCLASS('B'). If LOCKCLASS is not followed by a letter in the range B to J, then EXECDLI sets a status code of GL and initiates an ABENDU1041. MOVENEXT(data_value) Specifies a subset pointer to be moved to the next segment occurrence after your current segment. GETFIRST(data_value) Specifies that you want the search to start with the first segment occurrence in a subset. SET(data_value) Specifies unconditionally setting a subset pointer to the current segment. SETCOND(data_value) Specifies conditionally setting a subset pointer to the current segment. SETZERO(data_value) Specifies setting a subset pointer to zero. SETPARENT Sets 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. The argument can be any expression in the host language that converts to the integer data type; a variable must be declared as a binary halfword value. For
Chapter 2. Writing EXEC DLI Commands for Your Application Program

31

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 the IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify KEYLENGTH with the KEYS option. WHERE(qualification statement) Use WHERE to further qualify your GU commands after using SEGMENT. If you fully qualify a GU command, you can retrieve a segment regardless of your position in the database record. KEYS(area) Use KEYS to further qualify your GU commands and specify the segment occurrence by using its concatenated key. If you specify a SEGMENT option without a KEYS or WHERE option, IMS DB retrieves the first occurrence of that segment type it encounters by searching forward from current position. With an unqualified GU command, the segment type you retrieve might not be the one you expected, so you should specify an I/O area large enough to contain the largest segment your program has access to. (After successfully issuing a retrieval command, you can find out from DIB the segment type retrieved.) If you fully qualify your command with a WHERE or KEYS option, you would retrieve the next segment in sequential order, as described by the options. Including the WHERE or KEYS options for parent segments defines the segment occurrences that are to be part of the path to the segment you want retrieved. Leaving the SEGMENT option out for a level, or including only the SEGMENT option without a WHERE option, indicates that any path to the option satisfies the command. DL/I uses only the qualified parent segments and the lowest level SEGMENT option to satisfy the command. DL/I does not assume a qualification for the missing level.

Usage
Use the GU command to retrieve specific segments from the database, or to establish a position in the database for sequential processing. You must at least specify the SEGMENT option with a GU command to indicate the segment type you want to retrieve. (IMS DB retrieves the first occurrence of the segment you named in the SEGMENT argument.) When you need to retrieve a specific occurrence of a segment type, you can further qualify the command by using the WHERE or KEYS option after the SEGMENT option. You probably want to further qualify your GU commands with the WHERE or KEYS option, and specify a specific occurrence of a segment type. If you fully qualify a GU command, you can retrieve a segment regardless of your position in the database record.

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

32

Application Programming: EXEC DLI Commands for CICS and IMS

GU Command
Explanation: This example requests two pieces of information. To answer the first part of the request and retrieve the most recent ILLNESS segment, issue this GU command (assuming that PATNO1 contains 05163):
EXEC DLI GU SEGMENT(PATIENT) WHERE(PATNO=PATNO1) SEGMENT(ILLNESS) INTO(AREA);

Once you had retrieved the ILLNESS segment with the date of the patient’s most recent visit to the clinic, you could issue another command to find out whether he was treated during that visit. If the date of his most recent visit was January 5, 1988, you could issue the command below to find out whether or not he was treated on that day for that illness (assuming PATNO1 contains 05163, and DATE1 contains 19880105):
EXEC DLI GU SEGMENT(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 patient whose patient number is 10320.

Example 3
EXEC DLI GU SEGMENT(PATIENT) SEGMENT(ILLNESS) SEGMENT(TREATMNT) INTO(AREA);

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

Restriction
You must at least specify the SEGMENT option to indicate the segment type you want to retrieve.

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

Chapter 2. Writing EXEC DLI Commands for Your Application Program

33

ISRT Command

Format
EXEC DLI INSERT ISRT <B> USING PCB(expression) <A>

<A> For each parent segment (optional):
VARIABLE FIRST LAST CURRENT SEGMENT(name) SEGMENT((area)) SEGLENGTH(expression)

(1) FROM(area)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

WHERE(qualification statement) (2) FIELDLENGTH(expression)

KEYS(area) (3) KEYLENGTH(expression)

<B> For the object segment (required):
VARIABLE FIRST LAST SEGLENGTH(expression) OFFSET(expression)

MOVENEXT(data_value)

GETFIRST(data_value)

SET(data_value) SEGMENT(name) SEGMENT((area))

SETCOND(data_value)

SETZERO(data_value)

FROM(area)

Notes: 1 2 3 Specify FROM on parent segments for a path command. If you use multiple qualification statements, specify a length for each, using FIELDLENGTH. For example: FIELDLENGTH(24,8) You can use either the Keys option or the Where option, but not both on one segment level.

Options
USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be

34

Application Programming: EXEC DLI Commands for CICS and IMS

ISRT Command
any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. VARIABLE Indicates that a segment is variable-length. FIRST Specifies that you want to retrieve the first segment occurrence of a segment type, or that you want to insert a segment as the first occurrence. Use FIRST to insert a segment as a first occurrence of a segment type. LAST Specifies that you want to retrieve the last segment occurrence of a segment type, or that you want to insert a segment as the last segment occurrence. Use LAST to insert a segment as the last occurrence of a segment type. CURRENT Qualifies the command, and specifies that you want to use your current position at this level and above as qualification for this segment. Use CURRENT to insert a segment based on your current position. SEGMENT(name), SEGMENT((area)) Qualifies the command, specifying the name of the segment type or the area in the program containing the name of the segment type that you want to retrieve, insert, delete, or replace. You must include at least a SEGMENT option for each segment you want to add to the database. Unless ISRT is a path command, the lowest level SEGMENT option specifies the segment being inserted. You cannot use a WHERE or KEYS option for this level. If a segment has a unique key, DL/I inserts the segment in its key sequence. (If the segment does not have a key, or has a nonunique key, DL/I inserts it according to the value specified for the RULES parameter during DBDGEN. Related Reading: See IMS Version 7 Application Programming: Database Manager for information about inserting segments with the ISRT call. If you specify a SEGMENT option for only the lowest level segment, and do not qualify the parent segments with SEGMENT, WHERE, or KEYS options, you must make sure that the current position is at the correct place in the database to insert the segment. The SEGMENT option that DL/I assumes depends on your current position in the database record: v If DL/I has a position established at the missing level, DL/I uses the segment on which position is established. v If DL/I does not have a position established at the missing level, DL/I uses the first occurrence at that level. v If DL/I moves forward from a position established at a higher level, DL/I uses the first occurrence at the missing level that falls within the new path. v If you leave out a SEGMENT option for the root level, and DL/I has position established on a root, DL/I does not move from that root when trying to satisfy the command. It is good practice to always provide qualifications for higher levels to establish the position of the segment being inserted. If you are inserting a root segment, you need only specify a SEGMENT option. DL/I determines the correct place for its insertion in the database by the key taken from the I/O area. If the segment you are inserting is not a root segment,
Chapter 2. Writing EXEC DLI Commands for Your Application Program

35

ISRT Command
but you have just inserted its immediate parent, the segment can be inserted as soon as it is built in the I/O area just by using a SEGMENT option for it in the ISRT command. You need not code the parent level segments to establish your position. When you specify multiple parent segments, you can mix segments with and without the WHERE option. If you include only SEGMENT options on parent segments, DL/I uses the first occurrence of each segment type to satisfy the command. SEGLENGTH(expression) Specifies the length of the I/O area from which the segment is obtained. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.) Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call. FROM(area) Specifies an area containing the segment to be added, replaced, or deleted. Use FROM to insert one or more segments with one command. MOVENEXT(data_value) Specifies a subset pointer to be moved to the next segment occurrence after your current segment. GETFIRST(data_value) Specifies that you want the search to start with the first segment occurrence in a subset. SET(data_value) Specifies unconditionally setting a subset pointer to the current segment. SETCOND(data_value) Specifies conditionally setting a subset pointer to the current segment. SETZERO(data_value) Specifies setting a subset pointer to zero. WHERE(qualification statement) Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. Each qualification statement consists of: v The name of a field in a segment v The relational operator, which indicates how you want the two values compared v The name of a data area in your program containing the value that is compared against the value of the field WHERE establishes position on the parents of a segment when you are inserting that segment. You can do this by specifying a qualification of WHERE or KEYS for the higher level SEGMENT options. When you specify multiple parent segments, you can mix segments with and without the WHERE option. If you include only SEGMENT options on parent segments, DL/I uses the first occurrence of each segment type to satisfy the command.

36

Application Programming: EXEC DLI Commands for CICS and IMS

ISRT Command
FIELDLENGTH(expression) Specifies the length of the field value in a WHERE option. KEYS(area) Qualifies the command with the segment’s concatenated key. You can use either KEYS or WHERE for a segment level, but not both. KEYs can be used to qualify a parent segment. Instead of using WHERE, you can specify KEYS and use the concatenated key of the segment as qualification. You can use the KEYS option once for each command, immediately after the highest level SEGMENT option. “Area” specifies an area in your program containing the segment’s concatenated key. KEYLENGTH(expression) Specifies the length of the concatenated key when you use the KEYS option. It can be any expression in the host language that converts to the integer data type; if it is a variable, it must be declared as a binary halfword value. For IBM COBOL for MBS & VM (or VS COBOL II), PL/I, or assembler language, KEYLENGTH is optional. For COBOL programs that are not compiled with the IBM COBOL for MBS & VM (or VS COBOL II) compiler, you must specify KEYLENGTH with the KEYS option.

Usage
To add new segments to an existing database, use the ISRT command. When you issue the ISRT command, DL/I takes the data from the I/O area you have named in the FROM option and adds the segment to the database. (The initial loading of a database requires using the LOAD command, instead of the ISRT command.) Related Reading:The IMS Version 7 Administration Guide: Database Manager describes the database load programs. You can use ISRT to add new occurrences of an existing segment type to a HIDAM, HISAM, or HDAM database. For an HSAM database, you can add new segments only by reprocessing the whole database or by adding the new segments to the end of the database. Before you can issue the ISRT command to add a segment to the database, your program must build the segment to be inserted in an I/O area. If the segment has a key, you must place the correct key in the correct location in the I/O area. If field sensitivity is used, the fields must be in the order defined by the PSB for the application’s view of the segment. If you are adding a root segment occurrence, DL/I places it in the correct sequence in the database by using the key you supply in the I/O area. If the segment you are inserting is not a root, but you have just inserted its parent, you can insert the child segment by issuing an insert request qualified with only the segment name. You must build the new segment in your I/O area before you issue the ISRT request. You also qualify insert requests with the segment name when you add a new root segment occurrence. When you are adding new segment occurrences to an existing database, the segment type must have been defined in the DBD. You can add new segment occurrences directly or sequentially after you have built them in the program’s I/O area. If the segment type you are inserting has a unique key field, the location where DL/I adds the new segment occurrence depends on the value of its key field. If the
Chapter 2. Writing EXEC DLI Commands for Your Application Program

37

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

Examples
Example 1
“Add information to the record for Chris Edwards about his visit to the clinic on February 1, 1993. His patient number is 02345. He had a sore throat.” Explanation: First, build the ILLNESS segment in your program’s I/O area. Your I/O area for the ILLNESS segment looks like this:
19930201SORETHROAT

Use the command to add this new segment occurrence to the database is:
EXEC DLI ISRT SEGMENT(PATIENT) WHERE (PATNO=PATNO1) SEGMENT(ILLNESS) FROM(ILLAREA);

Example 2
“Add information about the treatment to the record for Chris Edwards, and add information about the illness.” Explanation: You build the TREATMNT segment in a segment I/O area. The TREATMNT segment includes the date, the medication, amount of medication, and the doctor’s name:
19930201MYOCINb b b 0001TRIEBb b b b b &b

The following command adds both the ILLNESS segment and the TREATMNT segment to the database:
EXEC DLI ISRT SEGMENT(PATIENT) WHERE (PATNO=PATNO1) SEGMENT(ILLNESS) FROM(ILLAREA) SEGMENT(TREATMNT) FROM(TRETAREA);

Example 3
EXEC DLI ISRT SEGMENT(ILLNESS) KEYS(CONKEY) SEGMENT(TREATMNT) FROM(TRETAREA);

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

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

38

Application Programming: EXEC DLI Commands for CICS and IMS

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

POS Command
The Position (POS) command retrieves the location of either a dependent or the last inserted sequential dependent segment.

Format
EXEC DLI POSITION POS USING PCB(n) INTO(data_area)

KEYFEEDBACK(area) FEEDBACKLEN(expression)

SEGMENT(name) SEGMENT((area))

WHERE(qualification_statement) FIELDLENGTH(expression)

Options
USING PCB(n) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. INTO(data_area) Specifies an area into which the segment is read. KEYFEEDBACK(area) Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated. FEEDBACKLEN(expression) Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (FEEDBACKLEN is required in COBOL programs and optional in PL/I and assembler language programs.)

Chapter 2. Writing EXEC DLI Commands for Your Application Program

39

POS Command
SEGMENT(name) Qualifies the command, specifying the name of the segment type you want to retrieve, insert, delete, or replace. SEGMENT((area)) Is a reference to an area in your program containing the name of the segment type. You can specify an area instead of specifying the name of the segment in the command. WHERE(qualification statement) Qualifies the command, specifying the segment occurrence. Its argument is one or more qualification statements, each of which compares the value of a field in a segment to a value you supply. FIELDLENGTH(expression) Specifies the length of the field value in a WHERE option.

Usage
Use the POS command to: v Retrieve the location of a specific sequential dependent segment, including the last one inserted v Determine the amount of unused space within each DEDB area If the area specified by the POS command is unavailable, the I/O area is unchanged and an FH status code is returned.

Restriction
The POS command is for DEDBs only.

REPL Command
The Replace (REPL) command is used to replace a segment, usually to change the values of one or more of its fields.

40

Application Programming: EXEC DLI Commands for CICS and IMS

REPL Command

Format
EXEC DLI REPLACE REPL <B> USING PCB(expression) <A>

<A> For each parent segment (optional):
VARIABLE SEGMENT(name) SEGMENT((area)) FROM(area) OFFSET(expression) MOVENEXT(data_value) SEGLENGTH(expression)

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

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

SET(data_value)

SETCOND(data_value)

SETZERO(data_value)

Options
USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. VARIABLE Indicates that a segment is variable-length. SEGMENT(name) Qualifies the command, specifying the name of the segment type you want to retrieve, insert, delete, or replace. SEGMENT((area)) Is a reference to an area in your program containing the name of the segment type. You can specify an area instead of specifying the name of the segment in the command. SEGLENGTH(expression) Specifies the length of the I/O area from which the segment is obtained. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.) Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

41

REPL Command
OFFSET(expression) Specifies the offset to the destination parent. It can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. You use OFFSET when you process concatenated segments in logical relationships. It is required whenever the destination parent is a variable length segment. FROM(area) Specifies an I/O area containing the segment to be added, replaced or deleted. You can replace more than the segment by including the FROM option after the corresponding SEGMENT option for each segment you want to replace. Including FROM options for one or more parent segments is called a path command. The argument following FROM identifies an I/O area that you have defined in your program. You must use a separate I/O area for each segment type you want to replace. MOVENEXT(data_value) Specifies a subset pointer to be moved to the next segment occurrence after your current segment. SET(data_value) Specifies unconditionally setting a subset pointer to the current segment. SETCOND(data_value) Specifies conditionally setting a subset pointer to the current segment. SETZERO(data_value) Specifies setting a subset pointer to zero.

Usage
You must qualify the REPL command with at least one SEGMENT and FROM option, which together indicate the retrieved segments you want replaced. If the Get command that preceded the REPL command was a path command, and you do not want to replace all of the retrieved segments or the PSB does not have replace sensitivity for all of the retrieved segments, you can indicate which of the segments are not to be replaced by omitting the SEGMENT option. If your program attempts to do a path replace of a segment where it does not have replace sensitivity, the data for the segment in the I/O area for the REPL command must be the same as the segment returned on the preceding GET command. If the data changes in this situation, the transaction is abended and no data is changed as a result of the Replace command. Notice that the rules for a REPL path command differ from the rules for an ISRT path command. You cannot skip segment levels to be inserted with an ISRT command, as you can with a REPL command. To update information in a segment, you can use the REPL command. The REPL command replaces data in a segment with data you supply in your application program. First, you must retrieve the segment into an I/O area. You then modify the information in the I/O area and replace the segment with the REPL command. For your program to successfully replace a segment, that segment must already have been defined as replace-sensitive in the PCB by specifying PROCOPT=A or PROCOPT=R on the SENSEG statement in the PCB.

42

Application Programming: EXEC DLI Commands for CICS and IMS

REPL Command
Related Reading: For more information, see IMS Version 7 Utilities Reference: System. You cannot issue any commands using the same PCB between a Get command and the REPL command, and you can issue only one REPL command for each Get command.

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

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

Example 2
“We have received a payment for $65.00 from a patient whose ID is 08642. Update the patient’s billing record and payment record with this information, and print a current bill for the patient.” Explanation: The four parts to satisfying this processing request are: 1. Retrieve the BILLING and PAYMENT segments for the patient. 2. Calculate the new values for these segments by subtracting $65.00 from the value in the BILLING segment, and adding $65.00 to the value in the PAYMENT segment. 3. Replace the values in the BILLING and PAYMENT segments with the new values. 4. Print a bill for the patient, showing the patient’s name, number, address, the current amount of the bill, and the amount of the payments to date. To retrieve the BILLING and PAYMENT segments, issue a GU command. Because you also need the PATIENT segment when you print the bill, you can include INTO following the SEGMENT options for the PATIENT segment and for the BILLING segment:
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1) SEGMENT(BILLING) INTO(BILLAREA) SEGMENT(PAYMENT) INTO(PAYAREA);

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

Chapter 2. Writing EXEC DLI Commands for Your Application Program

43

REPL Command
This command tells DL/I to replace the BILLING and PAYMENT segments, but not to replace the PATIENT segment. These two examples are called path commands. You use a path REPL command to replace more than one segment with one command.

Example 3
“Steve Arons, patient number 10250, has moved to a new address in this town. His new address is 4638 Brooks Drive, Lakeside, California. Update the database with his new address.” Explanation: You need to retrieve the PATIENT segment for Steve Arons and replace the address portion of the segment. To retrieve the PATIENT segment, you can use this GU command (assuming PATNO1 contains 10250):
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1);

Since you are not replacing the first two fields of the PATIENT segment (PATNO and NAME), you do not have to change them in the I/O area. Place the new address in the I/O area following the PATNO and NAME fields. Then you issue the following REPL command:
EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA);

Example 4
EXEC DLI GU SEGMENT(PATIENT) INTO(PATAREA) WHERE (PATNO=PATNO1) SEGMENT(ILLNESS) INTO(ILLAREA) SEGMENT(TREATMNT) INTO(TRETAREA); EXEC DLI REPL SEGMENT(PATIENT) FROM(PATAREA) SEGMENT(TREATMNT) FROM(TRETAREA);

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

Restrictions
The following restrictions apply to the REPL command: v You cannot issue any commands using the same PCB between the Get command and the REPL command. v You can issue only one REPL command for each Get command. v To modify information in a segment, you must first reissue the GU command before reissuing the REPL command. v You must qualify the REPL command with at least one SEGMENT option and one FROM option. v If you use a FROM option for a segment, you cannot qualify the segment by using the WHERE or KEYS option; DL/I uses the key field value specified in the I/O area as qualification.

RETRIEVE Command
Use the RETRIEVE command to determine current position in the database in batch and BMP programs.

44

Application Programming: EXEC DLI Commands for CICS and IMS

RETRIEVE Command

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

FEEDBACKLEN(expression)

Options
USING PCB(expression) Specifies the DB PCB you want to use for the command. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. expression specifies the PCB for which you want to retrieve the concatenated key. It can be any expression in the host language that converts to the integer data type. You can specify either a number or a reference to a halfword containing a number. The value must be a positive integer not greater than the number of PCBs generated for the PSB. The first PCB in the list, the I/O PCB, is 1. The first DB PCB in the list is 2, the second is 3, and so forth. KEYFEEDBACK(area) Specifies an area into which the concatenated key for the segment is placed. If the area is not long enough, the key is truncated. FEEDBACKLEN(expression) Specifies the length of the key feedback area into which you want the concatenated key retrieved. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. (It is required in COBOL programs and optional in PL/I and assembler language programs.) expression is the length of the key feedback I/O area. It can be any expression in the host language that converts to integer data type; you can specify either a number or a reference to a halfword containing a number. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language, FEEDBACKLEN is optional. For COBOL programs that are not compiled with the IBM COBOL for MVS & VM (or VS COBOL II) compiler, you must specify FEEDBACKLEN with the KEYFEEDBACK option.

Usage
If your program issues symbolic checkpoint commands it must also issue the extended RESTART (XRST) command or the RETRIEVE command. The RETRIEVE command is issued once, at the start of your program. You can use the RETRIEVE command to start your program normally, or to restart it in case of an abnormal termination. You can use the RETRIEVE command from a specific checkpoint id or a time/date stamp. Because the RETRIEVE command attempts to reposition the database, your program also needs to check for correct position. After issuing the RETRIEVE command, the segment type and level on which the position is established is returned to the DIBSEGM and DIBSEGLV fields in the DIB. The value in DIBKFBL is set to the actual length of the concatenated key. The DIBSTAT field contains the value returned from the GU repositioning, not the XRST command.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

45

RETRIEVE Command
The RESTART command attempts to reposition DL/I databases by issuing an internal GU qualified with the concatenated key. It is your responsibility to verify that your position in the database from the GU repositioning is the correct position for the checkpoint ID used in the XRST command. You can use the RETRIEVE command to retrieve the concatenated key used with the GU repositioning, and determine your current position in all the PCBs your program accesses.

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

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

Explanation

Restrictions
The following restrictions apply to the RETRIEVE command: v You cannot use this command in a CICS program. v To use this command, you must first define an I/O PCB for your program. v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments. v You cannot use this command unless the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.

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

Format
EXEC DLI SCHEDULE SCHD PSB(name) PSB((area)) SYSSERVE NODHABEND

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

46

Application Programming: EXEC DLI Commands for CICS and IMS

SCHD Command
SYSSERVE Specifies that the application program can handle an I/O PCB and might issue a system service request in the logical unit of work (LUW). NODHABEND Specifies that a CICS transaction does not fail with a DHxx abend. Should a schedule fail under EXEC DLI, a status code might be returned in the DIB, causing a CICS transaction to fail with a DHxx abend. This option prevents this. Following an unsuccessful SCHD command, the control, as well as the status code in the DIB are passed back to the application program, which can then take the appropriate action.

Usage
Before you can access DL/I databases from a CICS program, you must notify DL/I that your program will be accessing a database by scheduling a PSB. Do this by issuing the SCHD command. When you no longer plan to use a PSB, or you want to schedule a subsequent PSB (one or more), you must terminate the previous PSB with the TERM command. (For more information on the I/O PCB and PSB, see “Using the I/O PCB, PSB, and PCB” on page 11) The SCHD command can be specified two ways (see the examples below).

Examples
EXEC DLI SCHD PSB(psbname)SYSSERVE; EXEC DLI SCHD PSB((AREA));

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

TERM Command
The Terminate (TERM) command is used to terminate a PSB, in a CICS online program.

Format
EXEC DLI TERMINATE TERM

Options
No options are allowed with the TERM command.

Usage
If you want to use a PSB other than the one already scheduled, use the TERM command to release the PSB. When you issue the TERM command, all database changes are committed and cannot be backed out. Because returning to CICS also terminates the PSB and commits changes, you need not use the TERM command unless you want to schedule another PSB, or commit database changes before returning to CICS.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

47

TERM Command
No options are allowed with the TERM command. If your program subsequently needs a PSB that has terminated, it must reschedule that PSB by issuing another SCHD command. In most applications, you do not need to use the TERM command.

Example
EXEC DLI TERM

Explanation

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

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

48

Application Programming: EXEC DLI Commands for CICS and IMS

ACCEPT Command

ACCEPT Command
The Accept (ACCEPT) command is used to tell IMS to return a status code to your program, rather than abend the transaction.

Format
EXEC DLI ACCEPT STATUSGROUP('A')

Options
STATUSGROUP('A') Informs IMS that the application is prepared to accept status codes regarding unavailability. IMS then returns a status code instead of pseudoabending if a call issued later requires access to unavailable data. This is a required option.

Usage
Use the ACCEPT command to tell IMS to return a status code instead of abending the program. These status codes result because PSB scheduling completed without all of the referenced databases being available.

Example
EXEC DLI ACCEPT STATUSGROUP('A');

This example shows how to specify the ACCEPT command.

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

Format
EXEC DLI CHECKPOINT CHKP ID(area) ID(’literal’)

Options
ID(area) Contains the checkpoint ID. Specifies the name of an area in your program containing the checkpoint ID. The area pointed to is eight bytes. If you are using PL/I, specify this option as a pointer to a major structure, an array, or a character string. ID('literal') 'literal' is an 8-byte checkpoint ID, enclosed in quotation marks. In CHKP commands the area pointed to is 8 bytes long.

Usage
The two kinds of commands that allow you to make checkpoints are: the CHKP, or basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command.
Chapter 2. Writing EXEC DLI Commands for Your Application Program

49

CHKP Command
Batch programs can use either the symbolic or the basic command. Both checkpoint commands make it possible for you to commit your program’s changes to the database and to establish places from which the program can be restarted, should it terminate abnormally. You must not use the CHKPT=EOV parameter on any DD statement to take an IMS checkpoint. See IMS Version 7 Application Programming: Design Guide for an explanation of when and why you should issue checkpoints in your program. Both commands cause a loss of database position at the time the command is issued. Position must be reestablished by a GU command or other method of establishing position. It is not possible to re-establish position in the midst of nonunique keys or nonkeyed segments. You can issue the basic CHKP command to commit your program’s changes to the database and establish places from which your program can be restarted. When you issue a basic CHKP command, you must provide the code for restarting your program. When you issue a CHKP command, you specify the ID for the checkpoint. You can supply either the name of a data area in your program that contains the ID, or you can supply the actual ID, enclosed in single quotes. See the examples below.

Examples
EXEC DLI CHKP ID(chkpid); EXEC DLI CHKP ID('CHKP0007');

Explanation

These examples show how to specify the CHKP command.

Restrictions
The following restrictions apply to the CHKP command: v You cannot use this command in a CICS program, as was stated above. v You must first define an I/O PCB for your program before you can use the CHKP command. v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments.

DEQ Command
The Dequeue (DEQ) command is used to release a segment that is retrieved with the LOCKCLASS option.

Format
EXEC DLI DEQ LOCKCLASS(data_value)

50

Application Programming: EXEC DLI Commands for CICS and IMS

DEQ Command

Option
LOCKCLASS(data_value) Specifies that you want to release the lock that is being held as the result of an earlier GU, GN, or GNP command that had a LOCKCLASS option with the same data_value. Data_value must be a 1-byte alphabetic character in the range of B to J. For full function, specify the LOCKCLASS option followed by the lock class of that segment (for example, LOCKCLASS('B')). If the option is not followed by a letter (B-J), EXECDLI sets a status code of GL and initiates an ABENDU1041. DEQ commands are not supported for Fast Path.

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

Example
Your program can use the LOCKCLASS option as follows:
EXEC DLI DEQ LOCKCLASS(data_value) EXEC DLI GU SEGMENT(PARTX) SEGMENT(ITEM1) LOCKCLASS('B') INTO(PTAREA1); EXEC DLI GU SEGMENT(PARTX) SEGMENT(ITEM2) LOCKCLASS('C') INTO(PTAREA2); EXEC DLI DEQ LOCKCLASS('B');

This example shows the format of the DEQ command, where data_value is a 1-byte alphabetic character in the range B to J. The DEQ command releases the lock that was gotten and held with a LOCKCLASS of ’B’ for the PARTX segment as a result of the first GU. The lock that was gotten with a LOCKCLASS of ’C’ on the PARTX segment during the second GU remains held.

Explanation

Restriction
The following restriction applies to the DEQ command: v To use this command you must first define an I/O PCB for your program.

LOAD Command
The Load (LOAD) command is used to add a segment sequentially while loading the database.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

51

LOAD Command

Format
EXEC DLI LOAD USING PCB(expression) SEGMENT(name) SEGMENT((area)) VARIABLE FROM(area) SEGLENGTH(expression)

Options
USING PCB(expression) Specifies the DB PCB you want to use. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. VARIABLE Indicates that a segment is variable-length. SEGMENT(name) Specifies the name of the segment type you want to retrieve, insert, delete, or replace. SEGMENT((area)) A reference to an area in your program containing the name of the segment type. You can specify an area instead of the name of the segment in the command. SEGLENGTH(expression) Specifies the length of the I/O area from which the segment is obtained. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. ( SEGLENGTH is required in COBOL programs for any SEGMENT level that specifies the INTO or FROM option.) Requirement: The value specified for SEGLENGTH must be greater than or equal to the length of the longest segment that can be processed by this call. FROM(area) Specifies an area containing the segment to be added, replaced, or deleted.

Usage
The LOAD command is used for database load programs, which are described in IMS Version 7 Administration Guide: Database Manager.

Example
EXEC DLI LOAD SEGMENT(ILLNESS) FROM(ILLAREA);

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

52

Application Programming: EXEC DLI Commands for CICS and IMS

LOG Command

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

Options
FROM(area) Specifies an area containing the segment to be added, replaced, or deleted. LENGTH(expression) Specifies the length of an area.

Usage
You use the LOG command to write information to the system log. For detailed information on this command, see IMS Version 7 Application Programming: Design Guide.

Example
EXEC DLI LOG FROM(ILLAREA) LENGTH(18);

Restriction
The following restriction applies to the LOG command: v To use this command you must first define an I/O PCB for your program.

QUERY Command
The Query (QUERY) command obtains status code and other information in the DL/I interface block (DIB), which is a subset of the IMS PCB.

Format
EXEC DLI QUERY USING PCB(expression)

Options
USING PCB(expression) is required. No other options are allowed with the QUERY command.

Usage
For full-function databases, the DIB should contain NA, NU, TH or blanks. For an explanation of the codes, see “Status Code Explanations” on page 127. Use the QUERY command after scheduling the PSB but before making the database call. If the program has already issued a call using the DB PCB, you then use the REFRESH command to update the information in the DIB.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

53

QUERY Command

Examples
Example 1
EXEC DLI QUERY USING PCB(expression);

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

Example 2
EXEC DLI REFRESH DBQUERY;

Explanation: If your program has already issued a call using the DB PCB name, use the REFRESH command to update the information in the DIB. The REFRESH command updates all DB PCBs. You can issue it only one time.

Restrictions
The following restrictions apply to the QUERY command: v 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 nonkeyed segments.

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

Format
EXEC DLI REFRESH DBQUERY

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

Usage
The REFRESH command is used with the QUERY command. The QUERY command is used after scheduling the PSB but before making the first database call. If the program has already issued a call using the DB PCB, use the REFRESH command to update the information in the DIB. The REFRESH command updates all DB PCBs. It can be issued only once.

Example
EXEC DLI REFRESH DBQUERY;

Explanation

This example shows how to specify the REFRESH command.

54

Application Programming: EXEC DLI Commands for CICS and IMS

REFRESH Command

Restrictions
The following restrictions apply to the REFRESH command: v To use this command, you must first define an I/O PCB for your program. v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments. v You can issue this command only one time.

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

Format
EXEC DLI ROLB

Options
No options are allowed with the ROLB command.

Usage
When a batch or BMP program determines that some of its processing is invalid, two commands make it possible for the program to remove the effects of its inaccurate processing. These are the rollback commands, ROLL (see “ROLL Command” on page 56) and ROLB. The ROLB command is valid in batch programs when the system log is stored on direct access storage and dynamic backout has been specified through the use of the BKO execution parameter. Issuing the ROLB causes IMS DB to back out any changes your program has made to the database since its last checkpoint, or since the beginning of the program if your program has not issued a checkpoint. When you issue a ROLB command, IMS DB returns control to your program after backing out the changes, so that your program can continue processing with the next statement after the ROLB command.

Example
EXEC DLI ROLB;

Explanation
This example shows how to dynamically back out changes and return control to your program with the ROLB command.

Restrictions
The following restrictions apply to the ROLB command: v You 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 this command.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

55

ROLB Command
v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments. v You cannot use this command when the system log is stored on direct access storage and dynamic backout has not been specified.

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

Format
EXEC DLI ROLL

Options
No options are allowed with the ROLL command.

Usage
When a batch program determines that some of its processing is invalid, two commands make it possible for the program to remove the effects of its inaccurate processing. These are the rollback commands, ROLL and ROLB (see “ROLB Command” on page 55). You can use ROLL in batch programs. Issuing the ROLL causes CICS and DL/I to back out any changes your program has made to the database since its last checkpoint, or since the beginning of the program provided your program has not issued a checkpoint. When you issue a ROLL command, DL/I terminates your program after backing out the updates.

Example
EXEC DLI ROLL;

Explanation

This example shows how to dynamically back out changes with the ROLL command. If you use the ROLL command, IMS terminates the program with user abend code U0778. This type of abnormal termination does not produce a storage dump.

Restrictions
The following restrictions apply to the ROLL command: v You 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 this command. v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments. v You cannot use this command when the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.

56

Application Programming: EXEC DLI Commands for CICS and IMS

ROLS Command

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

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

Options
USING PCB(expression) Specifies the DB PCB you want to use. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. TOKEN(token) A 4-byte token associated with the current processing point. If you specify both TOKEN and AREA, the ROLS command backs out to the SETS or SETU you specified. AREA(data_area) The name of the area to be restored to the program when a ROLS command is issued. The first 2 bytes of the data-area field contain the length of the data-area, including the length itself. The second 2 bytes must be set to X'0000'. If you specify both TOKEN and AREA, the ROLS command backs out to the SETS you specified. The ROLS call has two formats: with TOKEN and AREA (for IOPCB only) and without TOKEN and AREA (for IOPCB or DBPCB).

Usage
Use the SETS and ROLS commands to define multiple points at which to preserve the state of DL/I full-function databases and to return to these points later. (For example, you can use them so your program can handle situations that can occur when PSB scheduling completes without all of the referenced DL/I databases being available.) Use of the SETS and ROLS commands apply only to DL/I full-function databases. This means that if a logical unit of work (LUW) is updating types of recoverable resources other than full-function databases, for example, VSAM files, the SETS and ROLS requests have no effect on the non-DL/I resources. The backout points are not CICS commit points; they are intermediate backout points that apply only to DBCTL resources. It is up to you to ensure the consistency of all the resources involved. You can use the ROLS command to backout to the state all full-function databases were in before either a specific SETS or SETU request or the most recent commit point.

Examples
Example 1
EXEC DLI ROLS TOKEN(token1) AREA(data_area)
Chapter 2. Writing EXEC DLI Commands for Your Application Program

57

ROLS Command
Explanation: In this example (for IOPCB only), backout takes place to the corresponding TOKEN, as specified by a prior SETS call, and control returns to the application.

Example 2
EXEC DLI ROLS USING PCB(PCB5)

Explanation: In this example, for IOPCB or DBPCB, backout takes place to the prior sync point and the application is pseudo-abended with a U3033, status code. Control does not return to the application. In this example, PCB5 is the number of a DB PCB that has received a 'data unavailable' status code. This command results in the same action that would have occurred had the program not issued an ACCEPT STATUSGROUPA command. (See “Chapter 7. Using Data Availability Enhancements” on page 109.)

Example 3
EXEC DLI ROLS

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

Restrictions
The following restrictions apply to the ROLS command: 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 nonkeyed segments. v You cannot use this command when the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.

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

Format
EXEC DLI SETS TOKEN(mytoken) AREA(data_area)

Options
TOKEN(mytoken) A 4-byte token associated with the current processing point. AREA(data_area) The name of the area to be restored to the program when a SETS command is

58

Application Programming: EXEC DLI Commands for CICS and IMS

SETS Command
issued. The first 2 bytes of the data-area field contain the length of the data-area, including the length itself. The second 2 bytes must be set to X'0000'.

Usage
You can use the SETS command to define multiple points at which to preserve the state of the DL/I databases and to return to these points later. For example, you can use the SETS command to allow your program to handle situations that can occur when PSB scheduling completed without all of the referenced DL/I databases being available. The SETS command applies only to DL/I full-function databases. If a logical unit of work (LUW) is updating types of recoverable resources other than full-function databases, for example VSAM files, the SETS command has no effect on the non-DL/I resources. The backout points are not CICS commit points; they are intermediate backout points that apply only to DBCTL resources. It is up to you to ensure the consistency of all the resources involved.

Example
EXEC DLI SETS TOKEN(mytoken) AREA(data_area)

Explanation

This example shows how to specify the SETS command.

Restrictions
The following restrictions apply to the SETS command: 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 nonkeyed segments. v In batch, you can only use this command when the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program. v It is rejected when the PSB contains a DEDB or MSDB PCB, or when the call is made to a DB2 database. v It is valid, but not functional, if unsupported PCBs exist in the PSB or if the program uses an external subsystem.

SETU Command
The Set a Backout Point Unconditionally (SETU) command is identical to the SETS command except that it does not get rejected if unsupported PCBs are in the PSB or if the program uses an external subsystem.

Format
EXEC DLI SETU TOKEN(mytoken) AREA(data_area)

Chapter 2. Writing EXEC DLI Commands for Your Application Program

59

SETU Command

Options
TOKEN(mytoken) A 4-byte token associated with the current processing point. AREA(data_area) The name of the area to be restored to the program when a SETU command is issued. The first 2 bytes of the data-area field contain the length of the data-area, including the length itself. The second 2 bytes must be set to X'0000'.

Usage
You can use the SETU command to define multiple points at which to preserve the state of the DL/I databases and to return to these points later. For example, you can use the SETU command to allow your program to handle situations that can occur when PSB scheduling completed without all of the referenced DL/I databases being available. The SETU command applies only to DL/I full-function data bases. If a logical unit of work (LUW) is updating types of recoverable resources other than full-function databases, such as VSAM files, the SETU command has no effect on the non-DL/I resources. The backout points are not CICS commit points; they are intermediate backout points that apply only to DBCTL resources. It is up to you to ensure the consistency of all the resources involved.

Example
EXEC DLI SETU TOKEN(mytoken) AREA(data_area)

Explanation

This example shows how to specify the SETU command.

Restrictions
The following restrictions apply to the SETU command: v You cannot 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 nonkeyed segments. v You cannot use this command when the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.

STAT Command
This section contains programming interface information. The Statistics (STAT) command is used to obtain IMS database statistics that you can use in debugging your program.

60

Application Programming: EXEC DLI Commands for CICS and IMS

STAT Command

Format
EXEC DLI STATISTICS STAT VSAM LENGTH(expression) NONVSAM INTO(area) USING PCB(expression) FORMATTED UNFORMATTED SUMMARY

Options
USING PCB(expression) Specifies the DB PCB you want to use. Its argument can be any expression that converts to the integer data type; you can specify either a number or a reference to a halfword in your program containing a number. INTO(area) Specifies an area into which the data is read. LENGTH(expression) Specifies the length of an area. VSAM/NONVSAM Specifies database type. FORMATTED/UNFORMATTED/SUMMARY Specifies type of output.

Usage
The STAT command is described in IMS Version 7 Application Programming: Design Guide.

Examples
For examples of the STAT command, see IMS Version 7 Application Programming: Database Manager.

SYMCHKP Command
The Symbolic Checkpoint (SYMCHKP) command is used to issue a symbolic checkpoint and to end a logical unit of work.

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

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

Chapter 2. Writing EXEC DLI Commands for Your Application Program

61

SYMCHKP Command

Options
ID(chkpid) Is the name of an 8-byte area in your program containing the checkpoint ID. If you are using PL/I, specify this parameter as a pointer to a major structure, an array, or a character string. ID('literal') Is the 8-byte checkpoint ID, enclosed in quotation marks. AREA#(area#) Specifies the areas in your program you want IMS to checkpoint. You do not need to specify any area to checkpoint; however, you cannot specify more than seven areas. If you specify more than one area, you must include all intervening areas. For example, if you specify AREA3, you must also specify AREA1 and AREA2. The areas you specify using the SYMCHKP command must be the same and in the areas specified in the XRST command. LENGTH#(expression#) Can be any expression in the host language that converts to the integer data type; you can specify either a number or a reference to a halfword containing a number. For IBM COBOL for MVS & VM (or VS COBOL II), PL/I, or assembler language programs, LENGTH1 to LENGTH7 are optional. For COBOL programs that are not compiled with the IBM COBOL for MVS & VM (or VS COBOL II) compiler, LENGTHx (where x is 1 to 7) is required for each AREAx (where x is 1 to 7) that you specify.

Usage
The two kinds of commands that allow you to make checkpoints are: the CHKP, or basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command. Batch programs can use either the symbolic or the basic command. Both checkpoint commands make it possible for you to commit your program’s changes to the database and to establish places from which the program can be restarted, should it terminate abnormally. You must not use the CHKPT=EOV parameter on any DD statement to take an IMS checkpoint. Refer to IMS Version 7 Application Programming: Design Guide for an explanation of when and why you should issue checkpoints in your program. Both commands cause a loss of database position at the time the command is issued. Position must be reestablished by a GU command or other method of establishing position. In addition to committing your program’s changes to the database and establishing places from which your program can be restarted, the Symbolic Checkpoint command: v Works with the Extended Restart ( XRST) command to restart your program if it terminates abnormally. v Can save as many as seven data areas in your program, which are restored when your program is restarted. You can save variables, counters, and status information.

62

Application Programming: EXEC DLI Commands for CICS and IMS

SYMCHKP Command

Example
EXEC DLI SYMCHKP ID(chkpid) AREA1(area1) LENGTH1(expression1) ... AREA7(area7) LENGTH7(expression7)

Explanation
This example shows how to issue a symbolic checkpoint and to end a logical unit of work with a SYMPCHKP command.

Restrictions
The following restrictions apply to the SYMCHKP command: v If you issue this command, you must also issue the XRST command. v You cannot use this command in a CICS program. v To use the SYMCHKP command you must first define an I/O PCB for your program. v You cannot reestablish position in the midst of nonunique keys or nonkeyed segments. v The areas you specify using the SYMCHKP command must be the same, and in the same order, as the areas specified in the XRST command. v If you specify more than one area, you must specify all intervening areas. For example, if you specify AREA3, you must also specify AREA1 and AREA2. v When specifying expression1 with a COBOL program that is not compiled with the IBM COBOL for MVS & VM (or the VS COBOL II) compiler, LENGTHx (where x is 1 to 7) is required for each AREAx (where x is 1 to 7) that you specify.

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

Format
EXEC DLI XRST MAXLENGTH(expression) ID(chkpid) ID('literal')

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

Options
MAXLENGTH(expression) Specifies the length of an area from which a program is restarted. This parameter is the longest segment in the PSB, or of all the segments in a path, if you use path commands in your program. It can be any expression in the host

Chapter 2. Writing EXEC DLI Commands for Your Application Program

63

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

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

64

Application Programming: EXEC DLI Commands for CICS and IMS

XRST Command
You can extend restart your program from a specific checkpoint ID, or a time/date stamp. Because the XRST attempts to reposition the database, your program also needs to check for correct position. After issuing the XRST command, you should test the DIBSEGM field in the DIB. After a normal start, the DIBSEGM field should contain blanks. At the completion of an Extended Restart, the DIBSEGM field will contain a checkpoint ID. Normally, XRST will return the 8-byte symbolic checkpoint ID, followed by 4 blanks. If the 8-byte ID consists of all blanks, then XRST will return the 14-byte timestamp ID. The only successful status code for an XRST command is a blank status code. If DL/I detects any error while processing the XRST command, your program abends.

Example
EXEC DLI XRST MAXLENGTH(expression) ID(chkpid) AREA1(area1) LENGTH1(expression1) ... AREA7(area7) LENGTH7(expression7)

Explanation

This example shows how to specify the XRST command.

Restrictions
The following restrictions apply to the XRST 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 nonkeyed segments. v You cannot use this command unless the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.

Chapter 2. Writing EXEC DLI Commands for Your Application Program

65

XRST Command

66

Application Programming: EXEC DLI Commands for CICS and IMS

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

Specifying an Application Interface Block (AIB)
EXEC DLI commands can use the AIB interface. For example, using the AIB interface, the format for the GU command would be EXEC DLI GU AIB(aib), instead of EXEC DLI GU USING PCB(n) using the PCB format. With CICS Transaction Server 1.1 or later, the following EXEC DLI commands are supported in the AIB format (as well as the PCB format): v GU v v v v v GN GNP ISRT DLET REPL

v STAT v POS v v v v v QUERY REFRESH ACCEPT LOG DEQ

v SETS v ROLS With CICS Transaction Server 1.1 or later, and IMS/ESA Version 5, the following AIB-only commands are supported via the EXEC DLI interface: ICMD, RCMD and GMSG. The CICS EDF debugging transaction supports AIB EXEC DLI requests, just as it handles PCB type requests.

AIB Mask
The AIB mask must be supplied by the application and referenced in the EXEC call instead of the PCB number (for example, EXEC DLI GU AIB(aib)). The DIBSTAT field is set with a valid STATUS code when AIBRETRN = X’00000000’ or x’00000900’. Applications should test AIBRETRN for any other values and respond accordingly.

© Copyright IBM Corp. 2000, 2001

67

Specifying an Application Interface Block (AIB)

CICS Restrictions with AIB support
Restrictions due to function shipping include: v The AIBLEN field must be between 128 and 256 bytes. 128 is recommended. v LIST=NO must not be specified on any PCBs in the PSB.

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

For a PL/I program:
DIBVERCHAR(2) DIBSTATCHAR(2) DIBSEGMCHAR(8) DIBSEGLVCHAR(2) DIBKFBLFIXED BINARY (15,0) DIBDBDNMCHAR(8) DIBDBORGCHAR(8)

For an assembler language program:
DIBVERCL2 DIBSTATCL2 DIBSEGMCL8 DIBSEGLVCL2 DIBKFBLH DIBDBDNMCL8 DIBDBORGCL8

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

68

Application Programming: EXEC DLI Commands for CICS and IMS

Specifying the DL/I Interface Block (DIB)
unsigned char signed short int unsigned char unsigned char unsigned char dibseglv dibkfbl dibdbdnm dibdborg dibfic03 {2} ; {8} {8} {6} ; ; ; ;

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

GB

GD

GE

GG

GK

II

Chapter 3. Defining Application Program Elements to IMS

69

Specifying the DL/I Interface Block (DIB)
segment you are trying to insert might match a segment with the same key in another hierarchy or database record. LB For load programs only after issuing a LOAD command. The segment you are trying to load already exists in the database. DL/I returns this status code only for segments with key fields. For ISRT and REPL commands. The segment you are trying to insert or replace requires a duplicate entry to be inserted in a secondary index that does not allow duplicate entries. This status code is returned for batch programs that write log records to direct access storage. If a CICS program that does not log to disk encounters this condition, the program (transaction) is abnormally terminated. For TERM commands. The program tried to terminate a PSB when one was not scheduled.

NI

TG

The status codes listed above indicate exceptional conditions, and are the only status codes returned to your program. All other status codes indicate error conditions and cause your transaction or batch program to abnormally terminate. If you want to pass control to an error routine from your CICS program, you can use the CICS HANDLE ABEND command; the last 2 bytes of the abend code are the IMS status code that caused the abnormal termination. For more information on the HANDLE ABEND command, see the application programming reference manual for your version of CICS. Batch BMP programs abend with abend 1041. 3. Segment Name (DIBSEGM) This is the name of the lowest-level segment successfully accessed. When a retrieval is successful, this field contains the name of the retrieved segment. If the retrieval is unsuccessful, this field contains the last segment, along the path to the requested segment, that satisfies the command. After issuing an XRST command, this field is either set to blanks (indicating a successful normal start), or a checkpoint ID (indicating the checkpoint ID from which the program was restarted). You should test this field after issuing any of the following commands: v GN v GNP v GU v ISRT v LOAD v RETRIEVE v XRST 4. Segment Level Number (DIBSEGLV) This is the hierarchic level of the lowest-level segment retrieved. When IMS DB retrieves the segment you have requested, IMS DB places, in character format, the level number of that segment in this field. If you are issuing a path command, IMS DB places the number of the lowest-level segment retrieved. If IMS DB is unable to find the segment you have requested, it gives the level number of the last segment it encountered that satisfied your command. This is the lowest segment on the last path that IMS DB encountered while searching for the segment you requested. You should test this field after issuing any of the following commands: v GN

70

Application Programming: EXEC DLI Commands for CICS and IMS

Specifying the DL/I Interface Block (DIB)
v v v v v GNP GU ISRT LOAD RETRIEVE

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

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

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

71

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

The language coding formats follow:

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

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

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

72

Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 4. More about Writing Your Application Program
This chapter provides programming guidelines and information on preparing programs for execution using EXEC DLI commands. It also contains skeleton programs in assembler language, COBOL, PL/I, C, and C++.

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

© Copyright IBM Corp. 2000, 2001

73

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

Coding a Program in Assembler Language
The following is a sample CICS online program written in assembler language. It shows you how the different parts of a command-level program fit together, and how the EXEC DLI commands are coded. Except for a few commands, the program shown below applies to batch, BMP, and CICS programs. Differences are highlighted in the notes that follow. The numbers to the right of the sample code refer to those notes. See the following assembler language sample code.
*ASM XOPTS(CICS,DLI) * R2 EQU 2 R3 EQU 3 R4 EQU 4 R11 EQU 11 R12 EQU 12 R13 EQU 13 DFHEISTG DSECT SEGKEYA DS CL4 SEGKEYB DS CL4 SEGKEYC DS CL4 SEGKEY1 DS CL4 SEGKEY2 DS CL4 CONKEYB DS CL8 SEGNAME DS CL8 SEGLEN DS H PCBNUM DS H AREAA DS CL80 AREAB DS CL80 AREAC DS CL80 AREAG DS CL250 AREASTAT DS CL360 * COPY MAPSET * ******************************************************************* * INITIALIZATION * HANDLE ERROR CONDITIONS IN ERROR ROUTINE * HANDLE ABENDS (DLI ERROR STATUS CODES) IN ABEND ROUTINE * RECEIVE INPUT MESSAGE ******************************************************************* * SAMPLE DFHEIENT CODEREG=(R2,R3),DATAREG=(R13,R12),EIBREG=R11 * EXEC CICS HANDLE CONDITION ERROR(ERRORS) * EXEC CICS HANDLE ABEND LABEL(ABENDS) * EXEC CICS RECEIVE MAP ('SAMPMAP') MAPSET('MAPSET') * ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING * ******************************************************************* 1

2

3

4

5 6 6 6

74

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in Assembler Language
* SCHEDULE PSB NAMED 'SAMPLE1' ******************************************************************* * EXEC DLI SCHD PSB(SAMPLE1) BAL R4,TESTDIB CHECK STATUS * ******************************************************************* * RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS ******************************************************************* * MVC SEGKEYA,=C'A300' EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA) 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 BE LOOPDONE DONE AT 'GE' BAL R4,TESTDIB CHECK STATUS B GNPLOOP LOOPDONE EQU * * ******************************************************************* * INSERT NEW ROOT SEGMENT ******************************************************************* * MVC AREAA,=CL80'DATA FOR NEW SEGMENT INCLUDING KEY' EXEC DLI ISRT USING PCB(1) SEGMENT(SEGA) FROM(AREAA) 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) SEGMENT(SEGA) WHERE(KEYA=SEGKEYA) FIELDLENGTH(4) 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) BAL R4,TESTDIB * UPDATE FIELDS IN THE 3 SEGMENTS EXEC DLI REPL USING PCB(1) SEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80) SEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80) SEGMENT(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) SEGMENT(SEGB) KEYS(CONKEYB) KEYLENGTH(8) SEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80) BAL R4,TESTDIB CHECK STATUS

7

X

8

9

X

X X 10 X X X X X X X X

X X X

X X

Chapter 4. More about Writing Your Application Program

75

Coding a Program in Assembler Language
* ******************************************************************* * RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY * AND THEN DELETE IT AND ITS DEPENDENTS ******************************************************************* * MVC CONKEYB,=C'A200B230' EXEC DLI GU USING PCB(1) SEGMENT(SEGB) KEYS(CONKEYB) KEYLENGTH(8) INTO(AREAB) SEGLENGTH(80) BAL R4,TESTDIB CHECK STATUS EXEC DLI DLET USING PCB(1) 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) SEGMENT((SEGNAME)) KEYS(CONKEYB) KEYLENGTH(8) SETPARENT SEGMENT(SEGC) INTO(AREAC) SEGLENGTH(SEGLEN) WHERE(KEYC='C520') BAL R4,TESTDIB CHECK STATUS * ******************************************************************* * RETRIEVE DATABASE STATISTICS ******************************************************************* * EXEC DLI STAT USING PCB(1) INTO(AREASTAT) VSAM 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) SEGLENGTH(80) FIELDLENGTH(4,4,4,4) WHERE(KEYA > SEGKEY1 AND KEYA < SEGKEY2 KEYA > 'A275' AND KEYA < 'A350') BAL R4,TESTDIB CHECK STATUS * ******************************************************************* * TERMINATE PSB WHEN DLI PROCESSING IS COMPLETED ******************************************************************* * EXEC DLI TERM * ******************************************************************* * SEND OUTPUT MESSAGE ******************************************************************* * EXEC CICS SEND MAP('SAMPMAP') MAPSET('MAPSET') EXEC CICS WAIT TERMINAL

X X X X

X X X X

X

X X

11

6

76

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in Assembler Language
* ******************************************************************* * COMPLETE TRANSACTION AND RETURN TO CICS ******************************************************************* * EXEC CICS RETURN * ******************************************************************* * CHECK STATUS IN DIB ******************************************************************* * TESTDIB EQU * CLC DIBSTAT,=C' ' IS STATUS BLANK BER R4 YES - RETURN * HANDLE DLI STATUS CODES REPRESENTING EXCEPTIONAL CONDITIONS * BR R4 RETURN ERRORS EQU * * HANDLE ERROR CONDITIONS * ABENDS EQU * * HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES * END

12

13

Notes to the sample Assembler code: 1 For a CICS online program containing EXEC DLI commands, you must specify the DLI and CICS options. For a batch or BMP program containing EXEC DLI, you must specify only the DLI option. 2 For reentrancy, define each of the areas the program uses—I/O areas, key feedback areas, and segment name areas in DFHEISTG. 3 Define an I/O area for each segment you retrieve, add, or replace (in a single command). 4 For a batch or BMP program containing EXEC DLI, you must save registers on entry and restore registers on exit according to MVS register-saving conventions. 5 In a batch or BMP program, a DFHEIENT saves the registers on entry. Do not 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 for the 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 an assembler language program. 9 This GNP command retrieves all dependents under segment SEGA. The GE status code indicates that no more dependents exist. 10 This GU command is an example of a path command. Use a separate I/O area for each segment you retrieve. 11 In a CICS online program, the TERM command terminates the PSB scheduled 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 RCREG parameter instead of EXEC CICS RETURN. The RCREG parameter identifies a register containing the return code. 13 After issuing each command, you should check the status code in the DIB.

Chapter 4. More about Writing Your Application Program

77

Coding a Program in COBOL

Coding a Program in COBOL
The following is a sample program written for COBOL. It shows you how the different parts of a command-level program fit together, and how the EXEC DLI commands are coded. The sample program applies to the COBOL V4 compiler (5734-CB2), the OS/VS COBOL compiler (5740-CB1), IBM COBOL for MVS & VM (5688-197), and the VS COBOL II compiler (5668-958 and 5668-940). Except for a few commands, the program shown below applies to batch, BMP, and CICS programs. Differences are highlighted in the notes that follow. The numbers to the right of the sample code refer to those notes. See the following COBOL sample code.
CBL LIB,APOST,XOPTS(CICS,DLI) IDENTIFICATION DIVISION. PROGRAM-ID. SAMPLE. 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). 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 AREA 01 AREAB PIC X(80). 01 AREAC PIC X(80). 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. * EXEC CICS HANDLE ABEND LABEL(ABENDS) END-EXEC. * EXEC CICS RECEIVE MAP ('SAMPMAP') MAPSET('MAPSET') END-EXEC. * ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING * * *************************************************************** * SCHEDULE PSB NAMED 'SAMPLE1' * *************************************************************** * EXEC DLI SCHD PSB(SAMPLE1) END-EXEC. PERFORM TEST-DIB THRU OK. * * *************************************************************** * RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS * *************************************************************** 1

2

3

4 4 4

5

78

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in COBOL
* MOVE 'A300' TO SEGKEYA. EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA) SEGLENGTH(80) WHERE(KEYA=SEGKEYA) 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.

6

*

* *************************************************************** * 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) END-EXEC. PERFORM TEST-DIB THRU OK. * UPDATE FIELDS IN THE 3 SEGMENTS EXEC DLI REPL USING PCB(1) SEGMENT(SEGA) FROM(AREAA) SEGLENGTH(80) SEGMENT(SEGB) FROM(AREAB) SEGLENGTH(80) SEGMENT(SEGC) FROM(AREAC) SEGLENGTH(80) END-EXEC. PERFORM TEST-DIB THRU OK. * * *************************************************************** * 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) END-EXEC. PERFORM TEST-DIB THRU OK. * * *************************************************************** * RETRIEVE SEGMENT DIRECTLY USING CONCATENATED KEY * AND THEN DELETE IT AND ITS DEPENDENTS * ***************************************************************
Chapter 4. More about Writing Your Application Program

79

Coding a Program in COBOL
* 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.

80

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in COBOL
EXEC CICS WAIT TERMINAL END-EXEC. * * *************************************************************** * COMPLETE TRANSACTION AND RETURN TO CICS * *************************************************************** * EXEC CICS RETURN END-EXEC. * * *************************************************************** * CHECK STATUS IN DIB * *************************************************************** * TEST-DIB. IF DIBSTAT EQUAL TO ' ' THEN GO TO OK. OK. 9 ERRORS. * HANDLE ERROR CONDITIONS ABENDS. * HANDLE ABENDS INCLUDING DLI ERROR STATUS CODES

Notes to the sample COBOL code: 1 For a CICS online program containing EXEC DLI commands, you must specify the DLI and CICS options. Fora batch or BMP program containing EXEC DLI, 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 a single command). 4 Do not code EXEC CICS commands in a batch or BMP program. 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 and SEGLENGTH are required. 7 This GU command is an example of a path command. You must use a separate I/O area for each segment you retrieve. 8 For a CICS online program, the TERM command terminates the PSB scheduled earlier. You do not terminate the PSB in a batch or BMP program. 9 After issuing each command, you should check the status code in the DIB.

Coding a Program in PL/I
The following is a sample program written in PL/I. It shows you how the different parts of a command-level program fit together, and how the EXEC DLI commands are coded. Except for a few commands, the program shown below applies to batch, BMP, and CICS programs. Differences are highlighted in the notes that follow. The numbers to the right of the program refer to those notes. See the following PL/I sample code.
*PROCESS SAMPLE: DCL DCL DCL DCL INCLUDE,GN,XOPTS(CICS,DLI); PROCEDURE OPTIONS(MAIN); SEGKEYA CHAR SEGKEYB CHAR SEGKEYC CHAR SEGKEY1 CHAR 1 (4); (4); (4); (4); 2

Chapter 4. More about Writing Your Application Program

81

Coding a Program in PL/I
DCL DCL DCL DCL DCL DCL DCL DCL DCL DCL DCL SEGKEY2 CHAR (4); SEGKEY3 CHAR (4); SEGKEY4 CHAR (4); CONKEYB CHAR (8); SEGNAME CHAR (8); PCBNUM FIXED BIN (15); AREAA CHAR (80); /* DEFINE SEGMENT I/O AREA AREAB CHAR (80); AREAC CHAR (80); AREAG CHAR (250); 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); /* EXEC CICS HANDLE ABEND PROGRAM('ABENDS'); /* EXEC CICS RECEIVE MAP ('SAMPMAP') MAPSET('MAPSET'); /* ANALYZE INPUT MESSAGE AND PERFORM NON-DLI PROCESSING /* /* ************************************************************ /* SCHEDULE PSB NAMED 'SAMPLE1' /* ************************************************************ /* EXEC DLI SCHD PSB(SAMPLE1); CALL TEST_DIB;

*/ 3

*/ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */

4 4 4

5 */ */ */ */ 6 7

/* ************************************************************* /* RETRIEVE ROOT SEGMENT AND ALL ITS DEPENDENTS /* ************************************************************* /* SEGKEYA = 'A300'; EXEC DLI GU USING PCB(1) SEGMENT(SEGA) INTO(AREAA) WHERE(KEYA=SEGKEYA); CALL TEST_DIB; GNPLOOP: EXEC DLI GNP USING PCB(1) INTO(AREAG); 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)

*/ */ */ */ */

*/ */ */ */ */

82

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in PL/I
SEGMENT(SEGA) WHERE(KEYA=SEGKEYA) 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; /* /* ************************************************************ 8

*/

*/ */ */ */ */

*/ */ */ */ */ */

*/ */ */ */ */ */ */ */

*/ */ */ */ */ */ */

Chapter 4. More about Writing Your Application Program

83

Coding a Program in PL/I
/* 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 OR KEYA &Ar; SEGKEY3 AND KEYA &Al; SEGKEY4); CALL TEST_DIB; /* /* ************************************************************* /* TERMINATE PSB WHEN DLI PROCESSING IS COMPLETED /* ************************************************************* /* EXEC DLI TERM; /* /* ************************************************************* /* SEND OUTPUT MESSAGE /* ************************************************************* /* EXEC CICS SEND MAP('SAMPMAP') MAPSET('MAPSET'); EXEC CICS WAIT TERMINAL; /* /* ************************************************************* /* COMPLETE TRANSACTION AND RETURN TO CICS /* ************************************************************* /* EXEC CICS RETURN; /* /* ************************************************************ /* CHECK STATUS IN DIB /* ************************************************************ /* TEST_DIB: PROCEDURE; IF DIBSTAT = ' ' RETURN; /* HANDLE DLI STATUS CODES REPRESENTING EXCEPTIONAL CONDITIONS /* */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */

*/ */ */ */ */ 9

4

4

10 */ */

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 must specify the DLI and CICS options. For a batch or BMP program containing EXEC DLI, you must specify only the DLI option. 2 Define, in automatic storage, each of the areas; I/O areas, key feedback areas, and segment name areas. 3 Define an I/O area for each segment you retrieve, add, or replace in a single command. 4 Do not code EXEC CICS commands in a batch or BMP program. 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.

84

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in PL/I
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 SEGLENGTH options. 7 This GNP command retrieves all dependents under segment SEGA. The GE status code indicates that no more dependents exist. 8 This GU command is an example of a path command. You must use a separate I/O area for each segment you retrieve. 9 For a CICS online program, the TERM command terminates the PSB scheduled earlier. You do not terminate the PSB in a batch or BMP program. 10 After issuing each command, you should check the status code in the DIB.

Coding a Program in C
The following is a sample program written in C. It shows you how the different parts of a command-level program fit together, and how the EXEC DLI commands are coded. Except for a few commands, the program shown below applies to batch, BMP, and CICS programs. Differences are highlighted in the notes that follow. The numbers to the right of the program refer to those notes. See the following C sample code.
#include < string.h> #include < stdio.h > 1 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]; struct {

4

Chapter 4. More about Writing Your Application Program

85

Coding a Program in C
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() {

/* /* SCHEDULE PSB /* strcpy(OUTLINE,SCHED); SENDLINE(); EXEC DLI SCHEDULE PSB(PC3COCHD); SENDSTAT(); TESTDIB(); /* /* ISSUE GU REQUEST /* strcpy(OUTLINE,GU1); SENDLINE(); EXEC DLI GET UNIQUE USING PCB(2) SEGMENT(SE2ORDER) WHERE(FE2OGREF>="000000") INTO(&GUIOA) SEGLENGTH(60); strcpy(OUTLIN2.OUTLINA,"SE2ORDER="); strcpy(OUTLIN2.OUTLINB,GUIOA); SENDLIN2(); SENDSTAT(); TESTDIB(); /* /* ISSUE GNP REQUEST /* do { strcpy(OUTLINE,GNP1); SENDLINE();

EXEC CICS ADDRESS EIB(dfheiptr); strcpy(OUTLINE,DIVIDER); SENDLINE(); strcpy(OUTLINE,START); SENDLINE();

5

*/ */ */ 6 */ */ */ 7

*/ */ */

86

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in C
EXEC DLI GET NEXT IN PARENT USING PCB(2) INTO(&GNIOA) SEGLENGTH(60); strcpy(OUTLIN2.OUTLINA,"SEGMENT="); strcpy(OUTLIN2.OUTLINB,GNIOA); SENDLIN2(); SENDSTAT(); if (strncmp(dibptr->dibstat,"GE",2) != 0) TESTDIB(); } while (strncmp(dibptr->dibstat,"GE",2) != 0); /* /* ISSUE GN REQUEST /* strcpy(OUTLINE,GN1); SENDLINE(); EXEC DLI GET NEXT USING PCB(2) SEGMENT(SE2ORDER) 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); 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(); /* /* ISSUE GN REQUEST /* strcpy(OUTLINE,GN1); SENDLINE(); EXEC DLI GET NEXT USING PCB(2) SEGMENT(SE2ORDER) INTO(&GNIOA) SEGLENGTH(60); strcpy(OUTLIN2.OUTLINA,"SE2ORDER="); strcpy(OUTLIN2.OUTLINB,GNIOA); SENDLIN2(); SENDSTAT(); TESTDIB(); /* */ /* GET INSERTED SEGMENT TO BE REPLACED */ /* */ strcpy(OUTLINE,GU2); SENDLINE(); EXEC DLI GET UNIQUE USING PCB(2) SEGMENT(SE2ORDER) WHERE(FE2OGREF="000999") INTO(&ISRTIOA) SEGLENGTH(60); strcpy(OUTLIN3.OUTLINX,"ISRT SEG="); strcpy(OUTLIN3.OUTLINY,ISRTIOA.ISRT1); strcpy(OUTLIN3.OUTLINZ,ISRTIOA.ISRT2); 8

9 */ */ */

10

*/ */ */ 11

*/ */ */ 12

13

Chapter 4. More about Writing Your Application Program

87

Coding a Program in C
SENDLIN3(); SENDSTAT(); TESTDIB();

/* /* REPLACE SEGMENT /* strcpy(OUTLINE,REP1); SENDLINE(); strcpy(REPLIOA.REPLIO1,DATAB); strcpy(REPLIOA.REPLIO2,"REGRUN REPLACED SEGMENT 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(); /* /* ISSUE GN REQUEST /* strcpy(OUTLINE,GN1); SENDLINE(); EXEC DLI GET NEXT USING PCB(2) SEGMENT(SE2ORDER) INTO(&GNIOA) SEGLENGTH(60); strcpy(OUTLIN2.OUTLINA,"SE2ORDER="); strcpy(OUTLIN2.OUTLINB,GNIOA); SENDLIN2(); SENDSTAT(); TESTDIB(); /* */ /* GET REPLACED SEGMENT */ /* */ strcpy(OUTLINE,GU2); SENDLINE(); EXEC DLI GET UNIQUE USING PCB(2) 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); 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);

*/ */ */ 14

NO1.");

*/ */ */ 15

16

*/ */ */ 17

*/ */ */

88

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in C
SENDLINE(); EXEC DLI STAT USING PCB(2) VSAM FORMATTED INTO(&STATAREA); SENDSTT2(); TESTDIB(); 18

}

/* /* ISSUE TERM REQUEST /* strcpy(OUTLINE,TERM); SENDLINE(); EXEC DLI TERM; SENDSTAT(); TESTDIB(); strcpy(OUTLINE,DIVIDER); SENDLINE(); SENDOK(); /* /* RETURN TO CICS /* EXEC CICS RETURN;

*/ */ */ 19

*/ */ */

/* */ /* */ /* */ SENDLINE() { EXEC CICS SEND FROM(OUTLINE) LENGTH(120); 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;

20

{

} {

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() {
Chapter 4. More about Writing Your Application Program

89

Coding a Program in C
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; 21

TESTDIB() { 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"); EXEC CICS RETURN; } return; }

22

Notes to the sample C code: 1 You must include a standard header file string.h to gain access to string manipulation facilities. 2 You must include standard header file stdio.h to gain access to standard I/O library 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 segment SE2ORDER and puts it into array OUTLIN2. 8 Issue the GNP command to get the next segment and put it into array OUTLIN2. 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.

90

Application Programming: EXEC DLI Commands for CICS and IMS

Coding a Program in C
17 Issue DELETE command after putting content of segment into array OUTLIN3. 18 Issue STAT REQUEST command. 19 Issue TERM command. 20 Output processing. 21 Check return code. 22 Do not code EXEC CICS commands in a batch or BMP program.

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

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

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

Chapter 4. More about Writing Your Application Program

91

Preparing your Program for Execution

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

92

Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 5. Processing Fast Path Databases
Using EXEC DLI commands under DBCTL, a CICS program or a batch-oriented BMP can access DEDBs. Parameters allow your program to use facilities of the DEDBs such as subset pointers, described below. A DEDB contains a root segment and as many as 127 types of dependent segment. One of these types can be a sequential dependent; the other 126 are direct dependents. Sequential dependent segments are stored in chronological order. Direct dependent segments are stored hierarchically. DEDBs provide high data availability. Each DEDB can be partitioned, or divided into multiple “areas.” Each area contains a different set of database records. In addition, you can make up to seven copies of each area data set. If an error exists in one copy of an area, application programs can access the data by using another copy of that area. This is transparent to the application program. When an error occurs to data in a DEDB, IMS does not stop the database. It makes the data in error unavailable, but continues to schedule and process application programs. Programs that do not need the data in error are unaffected. DEDBs can be shared among application programs in separate IMS systems. Sharing DEDBs is virtually the same as sharing full-function databases, and most of the same rules apply. IMS systems can share DEDBs at the area level (instead of at the database level as with full-function databases), or at the block level. Related Reading: For more information on DEDB data sharing, see the description of administering IMS systems that share data in IMS Version 7 Administration Guide: System.

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

Figure 10. Processing a Long Chain of Segment Occurrences with Subset Pointers

© Copyright IBM Corp. 2000, 2001

93

Processing DEDBs with Subset Pointers
You can use subset pointers at any level of the database hierarchy, except at the root level. Subset pointers used for the root level are ignored. 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 one or more pointers to any segment in the chain. For example, you could set more than one subset pointer to a segment, as shown in Figure 11.

Figure 11. Examples of Setting Subset Pointers

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

Figure 12. More Examples of Setting Subset Pointers

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

Figure 13. How Subset Pointers Divide a Chain into Subsets

Before You Use Subset Pointers
For your program to use subset pointers, the pointers must be defined in the DBD for the DEDB, and in your program’s PSB:

94

Application Programming: EXEC DLI Commands for CICS and IMS

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

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

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

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

Chapter 5. Processing Fast Path Databases

95

Processing DEDBs with Subset Pointers

Figure 14. Processing Performed for the Sample Passbook Example

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

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

96

Application Programming: EXEC DLI Commands for CICS and IMS

Processing DEDBs with Subset Pointers

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

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

Setting the Subset Pointers with the SETZERO, MOVENEXT, SET, and SETCOND Options
The SETZERO, MOVENEXT, SET, and SETCOND options allow you to redefine subsets by modifying the subset pointers. Before your program can set a subset pointer, it must establish a position in the database. A command must be fully satisfied before a subset pointer is set. The segment a pointer is set to depends on your current position at the completion of the command. If a command to retrieve a segment is not completely satisfied, and a position is not established, the subset pointers remain as they were before the command was issued. v Setting the subset pointer to zero: SETZERO The SETZERO option sets the value of the subset pointer to zero. After your program issues a command with the SETZERO option, the pointer is no longer set to a segment; the subset defined by that pointer no longer exists. (IMS returns a status code of GE to your program if you try to use a subset pointer having a value of zero.) Using the passbook example described earlier, say that you used the GETFIRST option to retrieve the first unposted transaction. You would then process the chain of segments, posting the transactions. After posting the transactions and
Chapter 5. Processing Fast Path Databases

97

Processing DEDBs with Subset Pointers
inserting any new ones into the chain, you would use the SETZERO option to set the subset pointer to zero as shown in the following command:
EXEC DLI ISRT SEGMENT(A) WHERE(AKEY = 'A1') SEGMENT(B) FROM(BAREA) SETZERO('1');

After this command, subset pointer 1 would be set to zero, indicating to a program updating the database later on that no unposted transactions exist. v Moving the subset pointer forward to the next segment after your current position: MOVENEXT To move the subset pointer forward to the next segment after your current position, your program issues a command with the MOVENEXT option. Using the passbook account example described earlier, say that you wanted to post some of the transactions, but not all, and that you wanted the subset pointer to be set to the first unposted transaction. The following command sets subset pointer 1 to segment B6, as shown in Figure 16.
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.

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

v Setting the subset pointer unconditionally: SET You use the SET option to set a subset pointer. The SET option sets a subset pointer unconditionally, regardless of whether or not it is already set. When your program issues a command that includes the SET option, IMS sets the pointer to your current position. For example, to retrieve the first B segment occurrence in the subset defined by subset pointer 1, and to reset pointer 1 at the next B segment occurrence, you would issue the following commands:
EXEC DLI GU SEGMENT(A) WHERE(AKEY = 'A1') SEGMENT(B) INTO(BAREA) GETFIRST('1'); EXEC DLI GN SEGMENT(B) INTO(BAREA) SET('1');

98

Application Programming: EXEC DLI Commands for CICS and IMS

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

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

v Setting the subset pointer conditionally: SETCOND Your program uses the SETCOND option to conditionally set the subset pointer. The SETCOND option is similar to the SET option; the only difference is that, with the SETCOND option, IMS updates the subset pointer only if the subset pointer is not already set to a segment. Using the passbook example, say that Bob Emery visits the bank and forgets to bring his passbook; you add the unposted transactions to the database. You want to set the pointer to the first unposted transaction, so later, when you post the transactions, you can immediately access the first one. The following command sets the subset pointer to the transaction you are inserting, if it is the first unposted one:
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 to segment B5. If unposted transactions already existed, the subset pointer is not changed.

Chapter 5. Processing Fast Path Databases

99

Processing DEDBs with Subset Pointers

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

100

Application Programming: EXEC DLI Commands for CICS and IMS

Processing DEDBs with Subset Pointers

Inserting Segments in a Subset
When you use the GETFIRST option to insert an unkeyed segment in a subset, the new segment is inserted before the first segment occurrence in the subset. However, the subset pointer is not automatically set to the new segment occurrence. For example, the following command inserts a new B segment occurrence in front of segment B5, but does not set subset pointer 1 to point to the new B segment occurrence:
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 the GETFIRST 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 is added to the end of the segment chain.

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

Combining Options
You can use the SET, MOVENEXT, and SETCOND options with other options, and you can combine subset pointer options with each other, provided they do not conflict. For example, you can use GETFIRST and SET together, but you cannot use SET and SETZERO together because their functions conflict. If you combine options that conflict, IMS returns an AJ status code to your program. You can use one GETFIRST option per qualification statement, and one update option (SETZERO, MOVENEXT, SET, or SETCOND) for each subset pointer.

Subset Pointer Status Codes
If you make an error in a qualification statement that contains subset pointer options, IMS can return these status codes to your program: AJ The qualification statement used a GETFIRST, SET, SETZERO, SETCOND, or MOVENEXT option for a segment for which there are no subset pointers defined in the DBD. The subset options included in the qualification statement are in conflict; for example, if one qualification statement contained a SET option and a SETZERO option for the same subset pointer, IMS would return an AJ status code. S means to set the pointer to current position; Z means to set the pointer to zero. You cannot use these options together in one qualification statement. The qualification statement included more than one GETFIRST option. The pointer number following a subset pointer option is invalid. You either did not include a number, or included an invalid character. The number following the option must be between 1 and 8, inclusive. AM The subset pointer referenced in the qualification statement was not specified in the program’s PSB. For example, if your program’s PSB

Chapter 5. Processing Fast Path Databases

101

Processing DEDBs with Subset Pointers
specifies that your program can use subset pointers 1 and 4, and your qualification statement referenced subset pointer 5, IMS would return an AM status code to your program. Your program tried to use an option that updates the pointer (SET, SETCOND, or MOVENEXT) but the program’s PSB did not specify pointer update sensitivity.

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

Locating a Specific Sequential Dependent
When you have position on a particular root segment, you can retrieve the position information and the area name of a specific sequential dependent of that root. If you have a position established on a sequential dependent segment, the search starts from that position. IMS returns the position information for the first sequential dependent segment that satisfies the command. To retrieve this information, you issue a POS command with a qualification statement containing the segment name of the sequential dependent. The current position after this kind of POS command is in the same place that it is after a GNP command. After a successful POS command, the I/O area contains: LL Area Name Position A 2-byte field giving the total length of the data in the I/O area, in binary. An 8-byte field giving the ddname from the AREA statement. An 8-byte field containing the position information for the requested segment. If the sequential dependent segment that is the target of the POS command is inserted in the same synchronization interval, no position information is returned. Bytes 11-18 contain X'FF'; other fields contain normal data. Unused CIs Unused CIs A 4-byte field containing the number of unused CIs in the sequential dependent part. A 4-byte field containing the number of unused CIs in the independent overflow part.

Locating the Last Inserted Sequential Dependent Segment
You can also retrieve the position information for the most recently inserted sequential dependent segment of a given root segment. To do this, you issue a POS

102

Application Programming: EXEC DLI Commands for CICS and IMS

The POS Command
command with a qualification statement containing the root segment as the segment name. The current position after this type of command follows the same rules as position after a GU. After a successful command, the I/O area contains: LL Area Name Position A 2-byte field containing the total length of the data in the I/O area, in binary. An 8-byte field giving the ddname from the AREA statement. An 8-byte field containing the position information for the most recently inserted sequential dependent segment. This field contains zeros provided no sequential dependent for this root exist. A 4-byte field containing the number of unused CIs in the sequential dependent part. A 4-byte field containing the number of unused CIs in the independent overflow part.

Unused CIs Unused CIs

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

Area Name Position Unused CIs Unused CIs

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

103

The POS Command
When a GC status code is returned, no data is retrieved or inserted. In your program, you can either: v Issue a CHKP command, and resume database processing by reissuing the command that caused the GC status code. v Ignore the GC status code and resume database processing by reissuing the command that caused the status code.

104

Application Programming: EXEC DLI Commands for CICS and IMS

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

Issuing Checkpoints in a Batch or BMP Program
The two kinds of commands that allow you to make checkpoints are: the CHKP, or Basic Checkpoint command, and the SYMCHKP, or Symbolic Checkpoint command. Batch programs can use either the Symbolic Checkpoint or the Basic Checkpoint command. Both checkpoint commands make it possible for you to commit your program’s changes to the database and to establish places from which the batch or BMP program can be restarted, in cases of abnormal termination. Requirement: You must not use the CHKPT=EOV parameter on any DD statement to take an IMS checkpoint. See IMS Version 7 Application Programming: Design Guide for an explanation of when and why you should issue checkpoints in your program. Because both checkpoint commands cause a loss of database position at the time the command is issued, you must reestablish position with a GU command or other methods. You cannot reestablish position in the midst of nonunique keys or nonkeyed segments.

Issuing the CHKP Command
When you issue a CHKP command, you must provide the code for restarting your program and you must specify the ID for the checkpoint. You can supply either the
© Copyright IBM Corp. 2000, 2001

105

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

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

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

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

Using Intermediate Backout Points: The SETS and ROLS Commands
Use the SETS and ROLS commands to define multiple points at which to preserve the state of DL/I full-function databases and to return to these points later. (For example, you can use them to allow your program to handle situations that can occur when PSB scheduling complete without all of the referenced DL/I databases being available.) The SETS and ROLS commands apply only to DL/I full-function databases. Therefore, if a logical unit of work (LUW) is updating recoverable resources other than full-function databases (VSAM files, for example), the SETS and ROLS requests have

106

Application Programming: EXEC DLI Commands for CICS and IMS

Intermediate Backout Points
no effect on the non-DL/I resources. The backout points are not CICS commit points; they are intermediate backout points that apply only to DBCTL resources. Your program must ensure the consistency of all the resources involved.

SETS Command
Before initiating a set of DL/I requests to perform a function, you can use a SETS command to define points in your application at which to preserve the state of DL/I databases. Your application can issue a ROLS command later if it cannot complete the function.

ROLS Command
You can use the ROLS command to back out to the state all full-function databases were in before either a specific SETS request or the most recent commit point.

Chapter 6. Recovering Databases and Maintaining Database Integrity

107

Intermediate Backout Points

108

Application Programming: EXEC DLI Commands for CICS and IMS

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

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

Obtaining Information about Database Availability
You can put data availability status codes into each of the DB PCBs under the following conditions: v In a CICS DBCTL environment, by using the PSB scheduling request command, SCHD. v In a Batch or BMP environment, at initialization time. You can obtain the data availability status codes within the DL/I interface block (DIB) by using the following QUERY command:
EXEC DLI QUERY USING PCB(n);

n specifies the PCB. The QUERY command is used after scheduling the PSB but before making the first database call. If the program has already issued a call using a DB PCB, then the QUERY command must follow the REFRESH command:
EXEC DLI REFRESH DBQUERY

The REFRESH command updates the information in the DIB. You can only issue this command one time. For full-function databases, the DIBSTAT should contain NA, NU, TH, or blanks. For MSDBs and DEDBs, the DIBSTAT always contains blanks. If a CICS command language translator has been used to translate the EXEC DLI commands, then, in addition to data availability status, the DBDNAME will be returned in the DIB field DIBDBDNM. Also, the name of the database organization will be returned in the DIB field DIBDBORG. For an explanation of the codes, see “Status Code Explanations” on page 127.

© Copyright IBM Corp. 2000, 2001

109

110

Application Programming: EXEC DLI Commands for CICS and IMS

Part 2. For Your Reference

© Copyright IBM Corp. 2000, 2001

111

112

Application Programming: EXEC DLI Commands for CICS and IMS

Chapter 8. Comparing Command-Level and Call-Level Programs
This chapter summarizes some of the differences between command- and call-level programs. If you are already familiar with DL/I calls, but not with EXEC DLI commands, this section will help you understand the commands and options you can use to perform the tasks you performed using calls. v Table 3 provides a quick reference for using DL/I calls. v Table 4 compares EXEC DLI commands with DL/I calls. For example, in a command-level program, you use the LOAD command instead of the ISRT call to initially load a database. v Table 5 on page 114 compares the options you use with EXEC DLI commands with the command codes you use with DL/I calls. For example, the LOCKED option performs the same function as a Q command code.
Table 3. DL/I Calls Available to IMS and CICS Command-Level Application Programs Program Characteristics Request Type CHKP call (symbolic) CHKP call (basic) GSCD call INIT call ISRT call (initial load) ISRT call LOG call SCHD call ROLB call ROLL call ROLS call (Roll Back to SETS)
3 3 2

Batch Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes Yes No Yes

BatchOriented BMP Yes Yes No Yes No Yes Yes No Yes Yes Yes Yes Yes Yes No Yes

CICS with DBCTL1 No No No Yes No Yes Yes Yes No No Yes Yes Yes Yes Yes No

ROLS call (Roll Back to Commit) SETS call STAT call
4

TERM call XRST call Notes:

1. In a CICS remote DL/I environment, CALLs in the CICS-DBCTL column are supported if you are shipping a function to a remote CICS that uses DBCTL. 2. GSCD is a Product-sensitive programming interface. 3. SETS and ROLS calls are not valid when the PSB contains a DEDB. 4. STAT is a Product-sensitive programming interface. Table 4. Comparing Call-Level and Command-Level Programs: Commands and Calls Call-Level INIT call Command-Level ACCEPT command Allows you to... Initialize for data availability status codes.

© Copyright IBM Corp. 2000, 2001

113

Comparing Command-Level and Call-Level Programs
Table 4. Comparing Call-Level and Command-Level Programs: Commands and Calls (continued) Call-Level CHKP call (basic) DEQ call DLET call GU, GN, and GNP calls GHU, GHN, and GHNP calls1 GSCD call ISRT call ISRT call LOG call POS call INIT call INIT call INIT call REPL call XRST call ROLL or ROLB call ROLS call PCB call SETS call SETU call STAT call3 CHKP call (extended) TERM call XRST call Notes: 1. Get commands are just like Get Hold calls, and the performance of Get commands and Get calls is the same. 2. You can use the GSCD call in a batch command-level program. GSCD is a Product-sensitive programming interface. 3. STAT is a Product-sensitive programming interface. Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options Call- Level C D Command-Level KEYS option Allows You to... Use the concatenated key of a segment to identify the segment. Command-Level CHKP command DEQ command DLET command GU, GN, and GNP commands1 GU, GN, and GNP commands1 GSCD call2 ISRT command LOAD command LOG command POS command ACCEPT command QUERY command REFRESH command REPL command RETRIEVE command ROLL or ROLB command ROLS command SCHD command SETS command SETU command STAT command SYMCHKP command TERM command XRST command Allows you to... Issue a basic checkpoint. Release segments retrieved using LOCKCLASS option or Q command code. Delete segments from a database. Retrieve segments from a database. Retrieve segments from a database for updating. Retrieve system addresses. Add segments to a database. Initially load a database. Write a message to the system log. Retrieve positioning and/or space usage in a DEDB area. Initialize for data availability status. Obtain information of initial data availability. Availability information after using a PCB. Replace segments in a database. Issue an extended restart. Dynamically back out changes. Back out to a previously set backout point. Schedule a PSB. Set a backout point. Set a backout point even if unsupported PCBs (like DEDBs or MSDBs) are present. Obtain system and buffer pool statistics. Issue a symbolic checkpoint. Terminate a PSB. Issue an extended restart.

INTO or FROM specified on Retrieve or insert a sequence of segments in a hierarchic path using segment level to be only one request, instead of having to use a separate request for each retrieved or inserted. segment. (Path call or command).

114

Application Programming: EXEC DLI Commands for CICS and IMS

Comparing Command-Level and Call-Level Programs
Table 5. Comparing Call-Level and Command-Level Programs: Command Codes and Options (continued) Call- Level F Command-Level FIRST option Allows You to... Back up to the first occurrence of a segment under its parent when searching for a particular segment occurrence. Disregarded for a root segment. Retrieve the last occurrence of a segment under its parent. Set a subset pointer to the segment following the current segment. Designate segments you do not want replaced, when replacing segments after a get hold request. Usually used when replacing a path of segments. Set parentage at a higher level than what it usually is (the lowest hierarchic level of the request). Reserve a segment so that other programs are not able to update it until you have finished processing it. Retrieve the first segment in a subset. Unconditionally set a subset pointer to the current segment. Limit the search for a segment to the dependents of the segment occurrence on which position is established. Use the current position at this hierarchic level and above as qualification for the segment. Conditionally set a subset pointer to the current segment. Set a subset pointer to zero. Null. Use an SSA in command code format without specifying the command code. Can be replaced during execution with the command codes you want.

L M N

LAST option MOVENEXT option Leave out the SEGMENT option for segments you do not want replaced. SETPARENT LOCKCLASS, LOCKED GETFIRST option SET option No equivalent for command level programs. CURRENT option SETCOND option SETZERO option No command-level equivalent.

P Q R S U V W Z –

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

115

Comparing Command-Level and Call-Level Programs

116

Application Programming: EXEC DLI Commands for CICS and IMS

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

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

Categories of DL/I Status Codes
The numbers in the category column of the status codes tables refer to the following categories of status codes: 1. Those indicating exceptional but valid conditions. The call is completed. 2. Those indicating warning or information-only status codes on successful calls (for example, GA and GK). If the call requested data, IMS returns the data to the I/O area. The call is completed. 3. Those indicating warning status codes on successful calls when data is not returned to the I/O area. The call is completed. 4. Those indicating improper user specifications. Most status codes are in this category. The call is not completed. 5. Those indicating system, I/O, or security errors encountered during the execution of I/O requests. The call is not completed. 6. Those indicating unavailable data.
Table 6. Database Calls REFRESH Category CLSE (GSAM) OPEN (GSAM) QUERY DEQ GU, GHU GN, GHN GNP, GHNP DLET, REPL ISRT (LOAD) ISRT (ADD)

PCB Status Code AB

TERM

POS

FLD

Description Segment I/O area required; none specified in call. Only applies to full-function DEQ calls. Hierarchic error in SSAs.

X

X

X

X

X

X

X

X

X

X

4

AC

X

X

X

X

X

X

4

© Copyright IBM Corp. 2000, 2001

117

Status Code Tables
Table 6. Database Calls (continued) REFRESH Category CLSE (GSAM) OPEN (GSAM) QUERY DEQ GU, GHU GN, GHN GNP, GHNP DLET, REPL ISRT (LOAD) ISRT (ADD)

PCB Status Code AD

TERM

POS

FLD

Description Function parameter incorrect. Only applies to full-function DEQ calls. GSAM detected invalid variable-length record. Required SSA missing. Options list not specified in SETO call. Data management OPEN error. Incorrect parameter format in I/O area; incorrect SSA format; incorrect command used to insert a logical child segment. I/O area length in AIB is invalid; incorrect class parameter specified in Fast Path Q command code. Invalid SSA field name. Call function not compatible with processing option, segment sensitivity, transaction code, definition, or program type. I/O error: OSAM, BSAM, or VSAM. User I/O area too long. SSAs too long. Call could not be completed because data was unavailable. Call could not be completed because data was unavailable and updates are backed out only since the last commit point. Call could not be completed because of a deadlock occurrence; updates are backed out only since the last commit point. Segment key field or nonreplaceable field has been changed. No preceding successful GHU or GHN call or an SSA supplied at a level not retrieved.

X

X

X

X

X

X

X

X

X

X

4

AF AH

X

X X X

4 4

AI AJ X

X X

X X

X X

X X

X X

X X X

5 4

AK AM

X X

X X

X X X

X X

X X

X X

X X

4 4

AO AT AU BA

X

X

X

X X

X X X

X X X X

X

5 4 4 6

X X

X X

X X

X X

BB

X

X

X

X

X

6

BC

X

6

DA

X

X

4

DJ

X

4

118

Application Programming: EXEC DLI Commands for CICS and IMS

Status Code Tables
Table 6. Database Calls (continued) REFRESH Category CLSE (GSAM) OPEN (GSAM) QUERY DEQ GU, GHU GN, GHN GNP, GHNP DLET, REPL ISRT (LOAD) ISRT (ADD)

PCB Status Code DX EM FA FC FD FE FF FG FH FI FM FN FP FR FS FT FV FW

TERM

POS

FLD

Description Violated delete rule. Normally for a utility.

X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X

4

4 4 2 4 3 4 3 4 4 4 4 5 3 4 3 2

MSDB arithmetic overflow error occurred. POS call for direct dependent segments only. Deadlock occurred. FSA error, not field name. No space in MSDB. Combination of FE and FW codes. DEDB inaccessible. I/O area not in user’s dependent region. Randomizing routine return code = 4. FSA error, field name. Invalid hexadecimal or decimal data. Total buffer allocation exceeded. DEDB areas are full. Too many SSAs on call. MSDB verify condition failed. More resources needed than normally allowed. For the DEQ call, Fast Path was not able to release any buffers. Attempt to read sequential data preceding the current position. Crossing hierarchical boundary. End of database. Crossing unit of work (UOW) boundary. Call did not have SSAs for all levels above insert and has lost segment position. Segment not found. Segment contains invalid pointer.

FY

X

X

X

X

X

X

X

X

4

GA GB GC GD X

X X X

X

2 1 X X X 3 1

GE GG

X X

X X

X X

X

1 5

Chapter 9. DL/I Status Codes

119

Status Code Tables
Table 6. Database Calls (continued) REFRESH Category CLSE (GSAM) OPEN (GSAM) QUERY DEQ GU, GHU GN, GHN GNP, GHNP DLET, REPL ISRT (LOAD) ISRT (ADD)

PCB Status Code GK GL

TERM

POS

FLD

Description Crossing segment boundaries on same level. Invalid user log code. Only applies to full-function DEQ calls. No parentage established. Normally for a utility.

X X

X

2 4

GP HT II IX L2 LB LC LD LE

X

X

X X

4

X X X X X X X

3 4 1 1 4 4 4

Segment already exists. Violated insert rule. The area lock failed. Segment being loaded already exists in database. Key field of segments out of sequence. No parent for this segment has been loaded. Sequence of sibling segments not the same as DBD sequence. An attempt was made to load a logical child segment in either a HALDB PHDAM or PHIDAM database. Work may be backed out because sufficient CI space was not preallocated for the area, or the SDEP CI lock failed. A database was unavailable. DL/I call issued by index maintenance cannot find segment. Index maintenance found duplicate segment in index. I/O error: OSAM, BSAM, or VSAM. A database was unavailable for update. Normally for a utility.

LF

X

4

| | | | |

LS

X

1

NA NE X

X

X

6 3

NI NO NU OS RX TH TI

X X

X X

X X X X X

1 5 6

X X X

4 4 4

Violated replace rule. No PSB was scheduled (command-level only). Invalid path to segment (command-level only).

120

Application Programming: EXEC DLI Commands for CICS and IMS

Status Code Tables
Table 6. Database Calls (continued) REFRESH Category CLSE (GSAM) OPEN (GSAM) QUERY DEQ GU, GHU GN, GHN GNP, GHNP DLET, REPL ISRT (LOAD) ISRT (ADD)

PCB Status Code

TERM

POS

FLD

Description DL/I not active (command-level only). Invalid system DIB (command-level only). Path replace error (command-level only). Invalid number for PCB or invalid processing option (command-level only). CICS XDLIPRE user exit determined the preceding request should not be executed. Database not open (command-level only). Length of segment greater than 64 KB. Checkpoint taken (Utility Control Facility (UCF) status code). Stop (UCF status code). Checkpoint and stop (UCF status code). Segment length not within limits of DBDGEN. Segment length invalid (command-level only). Field length missing or invalid (command-level only). Length of variable-length segment invalid (command-level only). Offset if invalid (command-level only). Concatenated key length invalid (command-level only). Internal GSAM error. No status code returned. Proceed.

X X TO TP X

X X

X X

X X X X

X X

X

5 5 4

X

X

X

X

X

4

TR

X

X

X

X

X

X

X

X

4

TY TZ UC

X X

X X

X X

X X

X

X X X

5 5 1

X

US UX V1 V2 V3 V4 X X X X X X X X X X X X

X X X X X X X X X X X

1 1 4 4 4 4

V5 V6 XX bb
1

X X X X X X

X X X X

X X

X X X

X X X X X X X X X X

4 4 5 1

X

X

X

Note: 1. bb indicates blank.

Chapter 9. DL/I Status Codes

121

Status Code Tables
Table 7. Message Calls PCB Status Code AA Category GCMD CHNG PURG AUTH

SETO

ISRT

CMD

GU

GN

Description CHNG call for alternate response PCB can specify only logical terminal destination; transaction code destination specified. Segment I/O area required; none specified in call. Function parameter invalid. Required SSA missing. Options list not specified in SETO call. Invalid parameter format in I/O area; invalid SSA format; invalid command used to insert a logical child segment. I/O area length in AIB is invalid. Call using I/O PCB in batch program. Specifying more than four user call parameters for a TP PCB is not valid. Error in option list related to IMS option keyword. The PRTO= option contained invalid data set processing options. User I/O area too long. System error. Call not completed successfully. Alternate response PCB referenced by ISRT call has more than one physical terminal assigned for input purposes. Notify master terminal operator. The conversational program has issued a PURG call to PCB that cannot be purged. AUTH call attempted with invalid generic class name or error occurred during attempt to set destination name specified in the CHNG or ISRT call. Call attempted with invalid PCB (PCB not modifiable or ISRT operation already done). Call attempted to a modifiable TP PCB with no destination set. Security violation detected during processing of either an AUTH call, a CHNG call, or an ISRT on a conversational response. Format name specified on second or subsequent message ISRT or PURG. Output segment size limit exceeded on call. Number of output segments inserted exceeded the limit by one. Any further queue manager calls are prohibited to prevent message queue overflow. ISRT to alternate response PCB followed ISRT to I/O PCB or vice versa. Alternate response PCB referenced by call requires that the source physical terminal receive the output response. No such command. No command responses produced.

X

X

4

AB AD AH AJ

X

X X

X X

X X

X X

X X

X X X X X X

4 4 4 4

AL AP AR AS AT AX AY

X X

X X

X X

X X

X X X X

X X

X X

X X X X X

4 4 4 4 4 X 5 4

X X

X X X X

AZ A1 X X X

X

4 4

A2 A3 A4 X X X

X X X

4 4 4

A5 A6 A7

X X X

X

4 4 4

A8 A9 CA

X X X

4 4 4

122

Application Programming: EXEC DLI Commands for CICS and IMS

Status Code Tables
Table 7. Message Calls (continued) PCB Status Code CB CC CD CE CF CG CH CI CJ CK CL X X X X X X X X Category GCMD CHNG PURG AUTH

SETO

ISRT

CMD

GU

GN

Description Command, as entered, not allowed for AOI. No command responses produced. Command executed. One or more command responses produced. Entered command violates security. No command responses produced. Transaction rescheduled after CMD call. Commit point had not been reached. Message on queue before IMS was last started. Transaction originated from AOI exit routine. AOI detected system error; CMD request not processed. Reissue CMD call. Transaction on queue before IMS last started. Transaction rescheduled. Commit point not reached. Transaction from AOI exit routine. Message rescheduled. Commit point not reached. Transaction from AOI exit routine. Message on queue before IMS last started. Transaction from AOI exit routine. Message on queue before IMS last started. Message rescheduled. Commit point had not been reached. Command executed. No command response produced. IOASIZE= parameter on PSBGEN macro does not meet minimum requirement for CMD call. The DFSMSCE0 user routing exit rejected the CHNG or ISRT call. The DFSMSCE0 user routing exit rejected the CHNG or ISRT call. The DFSMSCE0 user routing exit rejected the CHNG or ISRT call. No space in MSDB. DEDB inaccessible. I/O area not in user’s dependent region. DEDB areas are full. MSDB verify condition failed. Reserved No more input messages exist. No more segments exist for this message. GN request before GU. GCMD request before CMD. Segment less than five characters (segment length is message text length plus four control characters).

X X X

4 2 4 2 2 2 5 2 2 2 2

CM CN E1 E2 E3 FF FH FI FS FV MR QC QD QE QF X X X X X X X X X X X X X X X X X X X

X X

3 4 4 4 4 3 3 4 3 3 – 3 X X X X 3 4 4

Chapter 9. DL/I Status Codes

123

Status Code Tables
Table 7. Message Calls (continued) PCB Status Code QH Category GCMD CHNG PURG AUTH

SETO

ISRT

CMD

GU

GN

Description Terminal symbolic error; output designation unknown to IMS (logical terminals or transaction code). Either the message segment LL is not at least 5 bytes or the destination name in I/O area is blank or invalid. No PSB was scheduled (command-level only). Invalid system DIB (command-level only). Invalid number for PCB or invalid processing option (command-level only). Database not open (command-level only). Length of segment greater than 64 KB. Attempt to continue processing the conversation by passing SPA by a program-to-program switch after answering terminal. Program passed SPA to other program, but trying to respond. Program inserted message with Z1 field bits set. These bits are reserved for system use. Tried to ISRT SPA to express PCB. Alternate PCB specified in ISRT call for SPA had destination set to a logical terminal, but was not defined as ALTRESP=YES. MSC direct routing does not support program-to-program switch between conversational transactions. Current conversation requires fixed-length SPAs. Attempt was made to insert SPA to transaction with a different or nonfixedlength SPA. First insert to transaction code PCB that is conversational is not a SPA. Invalid SPA. Insert to a transaction code PCB that is not conversational and the segment is a SPA. Insert of multiple SPAs to transaction code PCB. Invalid transaction code name inserted into SPA. Length of SPA is incorrect (user modified first 6 bytes). No status code returned. Proceed.

X

X

X

X

4

TG

X X

4 5 4 5 5 X 4

TP TY TZ XA

X X X

XB XC XE XF

X X X X X

4 4 4 4

XG

X

4

X2 X3 X4 X5 X6 X7 bb
1

X X X X X X X X X X X X X

X

4 4 4 4 4 4

X

X

1

Note: 1. bb indicates blank. Table 8. System Service Calls PCB Status Code AB Category CHKP ROLB ROLS SETU SNAP INQY JAVA SYNC LOG SYNC

ROLL

XRST

SETS

STAT

PCB

INIT

Description Segment I/O area required; none specified in call.

1

X

X

X

X

X

2

4

124

Application Programming: EXEC DLI Commands for CICS and IMS

Status Code Tables
Table 8. System Service Calls (continued) PCB Status Code AC AD AG AJ X X X X X X X X X X X X Category CHKP ROLB SETU SNAP INQY JAVA SYNC LOG SYNC ROLS

ROLL

XRST

SETS

STAT

PCB

INIT

Description Hierarchic error in SSAs. Function parameter invalid. Partial data return. I/O area too small. Invalid parameter format in I/O area; invalid SSA format; invalid command used to insert a logical child segment. I/O area length in AIB is invalid. Call using I/O PCB in batch program. More than 4 user call parameters for a TP PCB are invalid. Invalid subfunction code. User I/O area too long. All of the databases included in the PSB are unavailable or no database PCBs are in the PSB. At least one of the databases included in the PSB is unavailable or has limited availability, or at least one PCB received an NA or NU status code. MSDB arithmetic overflow error occurred. Deadlock occurred. No space in MSDB. DEDB inaccessible. I/O area not in user’s dependent region. DEDB areas are full. MSDB verify condition failed. Crossing hierarchic boundary. Segment not found. Invalid user log code. A database was unavailable. XEFRDER card not provided. Please supply one. A database was unavailable for update. No more input messages exist. GN request before GU. GCMD request before CMD. Segment less than five characters (segment length is message text length plus four control characters).

1

X X X X

2

4 4 4 4

AL AP AQ AT BJ X X X X

X

X

X

4 4 4 4 6

BK

X

6

FA FD FF FH FI FS FV GA GE GL NA NL NU QC QE QF

X X X X X X X X X X X X X X X X X X X

X X

4 3 3

X

3 4

X X

3 3 2

X

1 4 6 4 6 3 4 4

Chapter 9. DL/I Status Codes

125

Status Code Tables
Table 8. System Service Calls (continued) PCB Status Code RA Category CHKP ROLB SETU SNAP INQY JAVA SYNC LOG SYNC ROLS

ROLL

XRST

SETS

STAT

PCB

INIT

Description Token does not match one for a SETS, or the PCB did not get BA or BB on last call. ROLS call issued with unsupported PCBs in the PSB, or the program is using an attached subsystem. Insufficient space. Would exceed maximum number of levels allowed. A SETS/SETU call was issued with unsupported PCBs in the PSB, or the program is using an attached subsystem. Internal error during sync-point processing for an IMS/Java application. PSB not in PSB directory (command-level only). PSB already scheduled (command-level only). PSB initialization failed (command-level only). DL/I not active (command-level only). Conflict in scheduling intent (command-level only). Invalid system DIB (command-level only). Invalid number for PCB or invalid processing option (command-level only). CICS XDLIPRE user exit determined the preceding request should not be executed. Database not open (command-level only). Length of segment greater than 64 KB. Segment length invalid (command-level only). Statistics area length invalid (command-level only). IMS terminating. Further DL/I calls must not be issued. No message returned. Good. No status code returned. Proceed.

1

X

2

4

RC

X

4

SA SB SC

X X X X

5 4 5

SY

X

5

TA TC TE TJ TL TN TP X X

X X X X X X X X X X X X

5 4 5 5 4 5 4

TR

X

X

X

X

4

TY TZ V2 V7 XD X

X X X

X X

5 5 4

X X

4 1

bb3

X

X

X

X

X

X

X

X

X

X

X

X

X

1

126

Application Programming: EXEC DLI Commands for CICS and IMS

AA • AD
Table 8. System Service Calls (continued) PCB Status Code Notes: 1. SNAP is a Product-sensitive programming interface. 2. STAT is a Product-sensitive programming interface. 3. bb indicates blank. Category CHKP ROLB SETU SNAP INQY JAVA SYNC LOG SYNC ROLS

ROLL

XRST

SETS

STAT

PCB

INIT

Description

1

Status Code Explanations
This information appears in the three application programming guides. For EXEC DL/I commands, all status codes, except those identified as being returned to the application program, cause an abnormal termination of the application program. All explanations apply to both DL/I call (call-level) programs and EXEC DLI (command-level) programs except where split. The term “request” means call, command, or both.
AA Explanation: IMS ignored a CHNG or ISRT call because the alternate response PCB that is referenced in the call specified a transaction code as a destination. An alternate response PCB must have a logical terminal specified as its destination. Programmer Response: Correct the CHNG or ISRT call. AB Explanation: An I/O area is required as one of the parameters on this call, and the call did not specify one. After this status code is returned, your position in the database is unchanged. AB only applies to full-function DEQ calls. Programmer Response: Correct the call by including the address of an I/O area as one of the call parameters. AC Explanation: For call-level programs: An error is in an SSA for a DLET, Get, ISRT, or REPL call for one of these reasons: v DL/I could not find a segment in the DB PCB specified in the call that has the segment name given in the SSA. v The segment name is in the DB PCB, but the SSA specifying that segment name is not in its correct hierarchic sequence. v The call specifies two SSAs for the same hierarchic level. IMS also returns this status code when a STAT 1 call has an invalid statistics function. After this status code is returned, your position in the database is unchanged. For command-level programs: An error is in one of the WHERE or SEGMENT options on a Get or ISRT command for one of these reasons: v DL/I could not find a segment in the DB PCB specified in the segment name given in the SEGMENT option. v The segment name is in the DB PCB, but the qualification for the command does not specify it in its correct hierarchic sequence. v The command specifies two SEGMENT options for the same hierarchic level. Programmer Response: Correct the segment name in the SSA or SEGMENT option or in the statistics function of the STAT1 call. AD Explanation: For call-level programs: Either the function parameter on the call is invalid or the function is not supported for the type of PCB specified in the call. Only applies to full-function DEQ calls. Some possible reasons are: v The function parameter is invalid. v A system service call used a PCB that is not the I/O PCB.

1. STAT is a Product-sensitive programming interface. Chapter 9. DL/I Status Codes

2

127

AF • AI
v A call issued in a DCCTL environment referred to an unsupported PCB or database. v A message GU or GN call used an alternate PCB instead 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 specifying IN=trancode in the BMP JCL. v A SETS or ROLS call included the I/O area but omitted the token. v A CPI Communications driven program issued the SETO 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. For command-level programs: A command was issued that is not supported in the environment. An example is a system service command in an online program. If the command is correct, some other possible causes are: v Referencing a DB PCB on a system service command. System service commands must reference the I/O PCB. v Referencing an I/O PCB for a database command, or not defining an I/O PCB before issuing system service commands. v A command issued in a DCCTL environment referred to an unsupported database or DB PCB. Programmer Response: Be sure that the specified function is valid for the PCB specified by the request. AF Explanation: GSAM detected a variable-length record whose 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 area was not large enough to contain all the output data. The I/O area was filled with partial data, as much as would fit in the area provided. AIBOALEN contains the actual length of the data returned to the application and AIBOAUSE contains the output area length that is required for the application program to receive all the data. Programmer Response: Correct the application program by using a larger I/O area. The minimum size of the I/O area is the value contained in the AIBOAUSE field. AH Explanation: You get this status code if you: 1. Specify an options list parameter that was not specified in the call list. 2. The program issued an ISRT call that did not include any SSAs. The ISRT call requires an SSA. 3. If the program was issuing a GU call to a GSAM database, the GU did not specify an RSA. RSAs are required on GU calls to GSAM databases. After this status code is returned, your position in the database is unchanged. Programmer Response: For cause 2, correct the ISRT 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 error occurred. Some possible reasons are: v An error is in the DD statements. v Neither DD statements nor DFSMDA dynamic allocation members were provided for this database. v The data set OPEN request did not specify load mode, but the data set was empty. An empty data set requires the load option in the PCB. v The buffer is too small to hold a record that was read at open time. v No DD statements or DFSMDA members were supplied for logically related databases. v For an OSAM data set, the DSORG field of the OSAM DCB, DSCB, or JFCB does not specify PS or DA. v For an old OSAM data set, the BUFL or BLKSIZE field in the DSCB is 0. v The data set is being opened for load, and the processing option for one or more segments is other than L or LS. v The allocation of the OSAM data set is invalid. The allocation is probably (1,1), rather than (1,1) and this causes 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 not match the DBD LRECL, BLKSIZE, or both. v Incorrect or missing information prevented IMS from determining the block size or the logical record length. v A catalog was not available for accessing a VSAM database that was requested. v OS could not perform an OPEN, but the I/O request is valid. Either the data definition information is incorrect, or information is missing. v RACF was used to protect the OSAM data set, and the control region has no update authorization.

128

Application Programming: EXEC DLI Commands for CICS and IMS

AJ • AK
If IMS returns message DFS0730I, you can determine the cause of the OPEN failure from this message in the job log. For more information, see the description of this message in IMS Version 7 Messages and Codes, Volume 2. Programmer Response: These kinds of problems often require the help of a system programmer or system administrator. But before you go to one of these specialists, some things you can do are: v Check the DD statements. Make sure that the ddname is the same as the name specified on the DATASET statement of the DBD. The segment name area in the DB PCB (call level), or in the DIB (command level) has the ddname of the data set that could not be opened. v Check the PSB and make sure that the appropriate processing options have been specified for each of the DB PCBs that your program uses. AJ Explanation: For call-level programs: For calls that provide parameters in the I/O area, such as SETS, ROLS, and INIT, the format of the parameters in 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 is invalid. The number in the segment level number field of the DB PCB is the level number of the SSA that is invalid. Some possible reasons for the invalid SSA format are: v The SSA contains a command code that is invalid for that call. v The relational operator in the qualification statement is invalid. v A qualification statement is missing a right parenthesis 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 into an existing database includes the D command code. ISRT calls for logical child segments cannot be path calls. v The RSA parameter on a GSAM call is invalid. v The SSA used an R, S, Z, W, or M command code for a segment for which no subset pointers are defined in the DBD. v The subset command codes included in the SSA are in conflict; for example, if one SSA contained an S status code and a Z status code, Fast Path would return an AJ status code. S means to set the pointer to 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 pointer command code is invalid. Either you did not include a number, or you included an invalid character. The number following the command code must be between 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 this status code is returned, your position in the database is unchanged. v In response to a SETS or ROLS call, the length of the I/O area is 0, the LL field is less than 4, or the ZZ field is not 0. v In response to an INIT call, the format of the I/O area is incorrect. v For calls that provide the length of the I/O area in the AIB, such as INQY, the I/O area length is invalid. v For SETO, I/O area length is less than 4096 or less than the minimum. v For the Q command code, the specified lock class is not a letter (A-J). For command-level programs: An ISRT command attempted to insert a logical child segment using a path command. ISRT commands for logical child segments cannot be path commands. Programmer Response: If you receive this status code on a SETS, ROLS, or INIT request, correct the parameters provided in the I/O area. If you receive this status code on a Get, DLET, REPL, or ISRT request, correct the invalid portion of the SSA. If you receive this status code on a GSAM call, correct the RSA. AK Explanation: For call-level programs: An SSA contains an invalid field name, or the field name is not defined in the DBD. The number in the segment level number field of the DB PCB is the level number of the SSA that contains the invalid name. You can also receive this status code if the program is accessing a logical child through the logical parent. DL/I returns AK if the field specified in the qualification has been defined for the logical child segment, and it includes (at least partially) the portion of the logical child that contains the concatenated key of the logical parent. When you are using field-level sensitivity, a field you specified in the SSA has not been defined in the PSB. After this status code is returned, your position in the database is unchanged. For command-level programs: A WHERE option contains an invalid field name. (The field name is not defined in the DBD.) The number in the DIBSEGLV field of the DIB is the level number of
Chapter 9. DL/I Status Codes

129

AL • AM
the WHERE option that contains the invalid name. Programmer Response: Correct the SSA or WHERE option. 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 batch program under one of the following conditions: v The system log is not on DASD. v The system log is on DASD, but dynamic backout has not been specified using the BKO execution parameter. Programmer Response: For cause 1, correct the program so that message calls in a batch program are not issued. For cause 2, either change the program or put the log on DASD with BKO specified on the execution parameter. AM Explanation: For call-level programs: The call function is not compatible with the processing option in the PCB, the segment sensitivity, the transaction-code definition, or the program type. The level number in the PCB is the level number of the SSA that is invalid. Some of the reasons you might get this status code are: v If you issue a retrieval call with the D command code in a program that does not have the P processing option specified in the DB PCB that was used for the call. v If you issue a DLET or ISRT call to a terminal-related dynamic MSDB from a program with no input LTERM present. An example is a batch-oriented BMP. v If the subset pointer referenced in the SSA was not defined in the program’s PSB. For example, if your program’s PSB specifies that your program can use subset pointers 1 and 4, and your SSA references subset pointer 5, Fast Path returns an AM status code to your program. v If your program tried to use an S, Z, W, or M command code for a subset pointer to which it was not pointer update-sensitive, as defined in the program’s PSB. v If a BMP, a CICS online program, or an MPP issues an ISRT call with the D command code when the program does not have the P processing option specified in the DB PCB that was referenced in the call. Batch programs do not need the P processing option to issue an ISRT call with the D command code, unless the program uses field-level sensitivity. v If the processing option is L and the program issued a call other than an ISRT call. Load programs can issue only ISRT calls. v If a DLET, REPL, or ISRT call that references a DB PCB does not have the necessary processing option for that call. The minimum processing options for these calls are D for DLET, R for REPL, and I for ISRT. v If you issue a DLET, REPL, or ISRT call for a segment to which the program is not sensitive. v If you issue a CHKP call on a GSAM or VSAM data set opened for output. This code is returned in the GSAM PCB. v If you issue a GSAM call with an invalid call function code. v If you issue an ISRT or DLET call for the index target segment or a segment on which the index target is dependent in the physical database while using an alternate processing sequence. v If you issue a path replace where the program does not have replace sensitivity, command code N is not specified, and the data for the segment is changed in the I/O area. v If GSAM could not obtain buffer space because the region size is too small. This is shown by the value X'1C' in the field GBCRTNCD.

v If you issue a DLET, ISRT, or REPL call from a program where the TRANSACT macro that was used at IMS system definition specified INQUIRY=YES for the input message. v If you issue a call from an ETO terminal to a terminal-related MSDB or a non-terminal-related MSDB with terminal-related keys. See IMS Version 7 Administration Guide: Transaction Manager for more information on ETO. v If you issue any type of call with update intent to a MSDB from a dynamically defined device such as a LU 6.2, ETO, or OTMA device. After this status code is returned, your position in the database is unchanged. For command-level programs: The command is not compatible with the processing option in the PCB or segment sensitivity. The level number in the DIB is the level number of the qualification that is invalid. Some of the reasons you might get this status code are: v If you issue a path retrieval command in a program that does not have the P processing option specified in the DB PCB that was used for the call. v If the processing option is L and the program issued a command other than a LOAD command. Load programs can issue only LOAD commands. v If you issue a DLET, REPL, or ISRT command that references a DB PCB that does not have the necessary processing option for that command. The minimum processing options for these calls are D for DLET, R for REPL, and I for ISRT.

130

Application Programming: EXEC DLI Commands for CICS and IMS

AO • AX
v If you issue a DLET, REPL, or ISRT command for a segment to which the program is not sensitive. v If you issue a CHKP command if a GSAM or VSAM data set is open for output. v If you issue a GSAM call with an invalid call function code. v If you issue an ISRT or DLET command for the index target segment, or a segment in the physical database on which the index target is dependent, while using an alternate processing sequence. v If you issue a path replace where the program does not have replace sensitivity, command code N is not specified, and the data for the segment is changed in the I/O area. v If you issue a call to a GSAM dummy data set. Any call to a GSAM dummy data set is invalid. Programmer Response: Correct the request, or make the necessary changes in the PCB. AO Explanation: A BSAM, GSAM, VSAM, or OSAM physical 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 error occurred when the last block of records was written prior to the closing of the data set. IMS does not return an AO status code for write errors with BSAM, VSAM, and OSAM. If your program receives this status code after issuing a call, this call does not cause the database to be stopped. Programmer Response: Determine whether the error occurred during input or output, and correct the problem. These problems usually require the help of a system programmer or system administrator. AP Explanation: A message or CHKP call is invalid because more than four parameters (or five if a parameter count is specified) are in a message call or a CHKP call issued in a transaction-oriented BMP. The following exceptions apply: v A batch-oriented BMP can issue a CHKP call with more than 4 (or 5) parameters. v One parameter after the I/O area parameter is allowed in order for the application program to specify a MOD name in an ISRT call. It is counted towards the 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 is related to a keyword. The feedback area, if one is provided, will contain additional error information. Programmer Response: Correct the request. AS Explanation: An IAFP specific processing error has occurred. The PRTO= option contained invalid data set processing options. The feedback area, if provided, will contain additional error information. Programmer Response: Correct the request. AT Explanation: The length of the data in the program’s I/O area is greater than the area reserved for it in the control region. The length of the area reserved is defined by the ACB utility program, DFSUACB0, and is printed as part of its output. Programmer Response: If the program is in error, correct the program. If the program is correct, reserve a larger control region by specifying parameters on the PSBGEN statement of PSBGEN. AU Explanation: The total length of the SSAs in the database call is greater than the area reserved for them in the control region. The length of the area reserved is defined by the ACB utility program, DFSUACB0, and printed as part of its output. After this status code is returned, your position in the database is unchanged. Programmer Response: If the program is in error, correct the program. If the program is correct, increase the PSB SSA space defined in the PSBGEN. AX Explanation: A failure to get CSA storage, a failure of the DFSLUMIF call, or a processing error with the IAFP Spool API occurred. When this code is returned, diagnostic information is written to the log in a '67D0' log record. Spool API processing errors return a DFS0013E message. A RACROUTE REQUEST=VERIFY,EVIRON=CREATE

Chapter 9. DL/I Status Codes

131

AY • A3
(RACF RACINIT) made during an AUTH call for LU 6.2 was unsuccessful. An OTMA user exit returned invalid routing information. See OTMA return codes in the IMS Version 7 Open Transaction Manager Access Guide. Programmer Response: These problems usually require the help of a system programmer or system administrator. AY Explanation: IMS ignored a message ISRT call because the logical terminal referenced by the alternate response PCB currently has more than one physical terminal assigned to it for input purposes. Programmer Response: Ask the master terminal operator to determine (using /DISPLAY ASSIGNMENT LTERM x) which physical terminals (two or more) refer to this logical terminal. Use the /ASSIGN command to correct the problem. AZ Explanation: IMS ignored a PURG or ISRT call in a conversational program. Some possible reasons are: v Issuing a PURG call referencing the I/O PCB or an alternate response PCB. Conversational programs can issue PURG calls only when the PURG call references an alternate PCB that is not an alternate response PCB. v Issuing a PURG call to send the SPA. v Issuing an ISRT or a PURG call referencing an alternate PCB that is set for an invalid destination or for a destination that IMS cannot determine. v Issuing an ISRT call referencing an alternate PCB whose destination is a conversational transaction code when the first segment inserted is not the SPA; or when IMS cannot determine whether or not the SPA was the first segment inserted. Programmer Response: Correct the PURG or ISRT call. A1 Explanation: IMS returns the A1 status code for one of the following reasons: v AUTH call for LU 6.2 input did not find a PST LU 6.2 extension block or did not find a UTOKEN. v CHNG call against alternate response PCB when the application program has not yet issued a GU. v The MSC program routing exit routine (DFSCMPR0) was called while processing a CHNG call and one of the following occurred: – The exit routine rejected the call by returning with return code 8 (A1 status code). – The exit routine returned with a RC=4 to route the message back to the originating system; however, the originating system has not been determined because the application program has not issued a GU. – The SYSID returned in R0 by the exit routine is not a valid remote SYSID. – The MSNAME pointed to by the address in R1, set by the exit routine, is not a valid remote MSNAME. v The MSC program routing routine exit (DFSMSCE0) was called while processing an ISRT or CHNG call and one of the following occurred: – The exit routine rejected the call by setting MSPRFL3=MSPR3REJ in the DFSMSCEP user parameter list that is passed to the exit. – IMS detected an error while processing the reroute request from the exit. It issued a message ″DFS070 Unable to route message RSN=xxyy″ and wrote a 6701-MSCE log record to the IMS log. For more information about this error, see the section on diagnosing message routing problems in IMS Version 7 Diagnosis Guide and Reference. v The destination name supplied in the I/O area of a CHNG call is invalid. v The destination name supplied in the I/O area of a CHNG call is valid (the destination is a program and the PCB is not an alternate response PCB), but the transaction is Fast Path exclusive. v AUTH call parameter list contained an invalid generic CLASS name. No access checking was done. v The routing exit routine (DFSCMPR0 or DFSMSCE0) attempted an invalid request to override a direct routing request. Programmer Response: Correct the CHNG or AUTH call, MSC program routing exit (DFSCMPR0 or DFSMSCE0), or ensure that the specified destination is valid. A2 Explanation: The program issued a CHNG call against an invalid PCB. The PCB was invalid for one of these 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 not completed processing it. Programmer Response: Check the PCB that was used by the CHNG call and determine which PCB should have been used for the call. A3 Explanation: The program issued an ISRT or PURG call that referenced a modifiable alternate PCB that did not have its destination set. IMS returns this status code to PURG calls only when the PURG call specified an I/O area as one of the parameters.

132

Application Programming: EXEC DLI Commands for CICS and IMS

A4 • BA
Programmer Response: Issue a CHNG call to set the destination of the modifiable alternate PCB, and then reissue the ISRT or PURG call. A4 Explanation: A security violation was detected during processing of an AUTH, CHNG, or ISRT call of a SPA on a conversational response. Some of the reasons for this status code are: v Transaction authorization is active and either RACF or a transaction authorization exit routine returned a nonzero return code. v The user is not authorized for access to the RESOURCE name in the class requested in the AUTH call. No installation data is returned. v No source CNT is available, which might be caused by 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 is based on the original message, and this authorization does not allow this function to be performed. Programmer Response: Check the transaction code to make sure it was entered correctly. If it was, check with the person who handles security at your installation. A5 Explanation: An ISRT or PURG call supplied an invalid parameter list. The call supplied the fourth parameter (the MOD name), but the ISRT or PURG being issued was not 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 call because the length of the message segment being inserted exceeds the size specified in the SEGSIZE keyword of the TRANSACT macro. For a Fast Path program (IFP), the length of the output message to a Fast Path terminal exceeds the size specified in the FPBUF parm of the TERMINAL macro. Programmer Response: Correct the output message segment. A7 Explanation: IMS ignored a message ISRT call for one of the following reasons: v The number of message segments inserted exceeds the number specified in the SEGNO keyword of the TRANSACT macro.

| | | | | |

prohibited the insert to prevent the message queue data sets from overflowing. However, the ISRT is not ignored for the message in progress when the DFSQSPC0 threshold is exceeded. The in-progress message will be processed. Any subsequent ISRTs are ignored. v The IMS queue manager or user Queue Manager Space Notification exit routine (DFSQSPC0) prohibited the insert because the destination TRANSACTION or LTERM was stopped. Programmer Response: Check the output messages and correct them. Use ROLB or another method to free buffer space. A8 Explanation: IMS ignored an ISRT call because: v An ISRT call to an alternate response PCB must not follow an ISRT call to the I/O PCB. v An ISRT call to the I/O PCB must not follow an ISRT call 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 PCB defined as SAMETRM=YES, but the PCB represented a logical terminal that is not part of the originating physical terminal. An alternate response PCB defined as SAMETRM=YES must represent the same physical terminal as the physical terminal associated with the originating logical terminal. v The originating terminal is in response mode, and the alternate response PCB is not associated with that logical terminal. IMS does not return this status code if the program makes either of these errors while communicating with a terminal in a remote IMS system through MSC. Programmer Response: Determine whether the application program is in error, the output logical terminal has been incorrectly reassigned (using the /ASSIGN command), or if SAMETRM=YES should not have been specified for the alternate response PCB. BA Explanation: The request was not completed because it required access to unavailable data. A status of BA is returned on a DL/I call that attempts to access an unavailable partition. If the very next DL/I call is a GN that is either completely unqualified or qualified only by root name, then the next partition is selected. The next-partition selection continues until either an available partition is found or there are no more partitions in the database. If an available partition is
Chapter 9. DL/I Status Codes

| v The IMS queue manager or user Queue Manager | Space Notification exit routine (DFSQSPC0)

133

BB • CD
returned, the call returns the first root in that partition. A GN call that is qualified only on a dependent segment name results in a BA status if the prior call had a BA status returned for the root level. Only the updates done for the current request, prior to the time it encountered the unavailable data, are backed out. The state of the database is as it was before the failing request was issued. If the request was REPL or DLET, the PCB position was unchanged. If the request was a Get or ISRT request, the PCB position is unpredictable. For a DEDB, this status code might be returned if no updates have been made by the current call. If updates have been made by the current call since the last commit point, a BB status code is returned instead. If changes have been made by a previous call, the application program must decide whether to commit these changes. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: This is an information-only status code. BB Explanation: The BB status code is the same as BA except that all database updates that the program made since the last commit point are backed out, and all nonexpress messages sent since the last commit point are canceled. The PCB position for all PCBs is at the start of the database. For a DEDB, this status code might be returned if updates have been made by the current call. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: This is an information-only status code. BC Explanation: The response from an INIT STATUS GROUPB call was not completed because it required access to unavailable data. All database resources that were allotted up to the last commit point are backed out, with the exception of GSAM and DB2. All output messages are backed out to the last commit point. Input messages are requeued. Programmer Response: This is an information-only status code. BJ Explanation: All of the databases in the PSB are unavailable, or there are no database PCBs in the PSB. Each PCB (excluding GSAM) received an NA status code as the result of the INQY DBQUERY call. Programmer Response: This is an information-only status code. BK Explanation: At least one of the databases included in the PSB is unavailable or has limited availability. At least one PCB received an NA or NU status code as the result of processing the INQY DBQUERY call. Programmer Response: This is an information-only status code. CA Explanation: The program issued a CMD call with an invalid command verb, or the command verb does not apply to the IMS system that the program is running in. IMS does not return any command responses. Programmer Response: Correct the command in the CMD call. CB Explanation: The command entered in the CMD call is not allowed from an AOI program. IMS does not return any command responses. Programmer Response: Correct the command. For a list of the commands that an AOI program can issue, see IMS Version 7 Customization Guide. CC Explanation: IMS has executed the command and returned one or more command responses. Programmer Response: Your program should issue GCMD calls as necessary to retrieve the responses. CD Explanation: The command that was entered on the CMD call violates security, or the application program is not authorized to issue CMD calls. IMS does not execute the command or return any command responses. Programmer Response: Correct the command. If necessary, check with the person in charge of security at your installation to find out why your program is restricted from using that command.

134

Application Programming: EXEC DLI Commands for CICS and IMS

CE • DJ
CE Explanation: IMS rescheduled the message that this GU call retrieved since the last CMD call. The program had not reached a commit point when the message was rescheduled. Programmer Response: This is an information-only status code. CF Explanation: The message being returned on the GU call was received by IMS before the start of this IMS execution. CF can be received on a CHKP call when an I/O area is specified for an MPP or message-oriented BMP. This occurs when a CHKP call issues an internal GU call. Programmer Response: This is an information-only status code. CG Explanation: The message retrieved by this GU originated from an AOI exit routine. Programmer Response: This is an information-only status code. CH Explanation: IMS ignored the CMD call just issued because the AOI command interface detected a system error and was unable to process the command. IMS processing continues. Programmer Response: Reissue the command. DA CI Explanation: CI is a combination of CE and CF. The message retrieved by this GU was scheduled for transmission before IMS was last started. The message was rescheduled, but the program had not reached a commit point. Programmer Response: This is an information-only status code. CJ Explanation: CJ is a combination of CE and CG. The message retrieved by this GU was scheduled for transmission before IMS was last started. The message originated from an AOI exit routine. Programmer Response: This is an information-only status code. Explanation: The program issued a DLET or REPL that tried to modify the key field in the segment or, when using field-level sensitivity, a REPL call tried to modify a field that had REPL=NO specified on the SENFLD STMT in the PSB. You cannot change a segment’s key field. Programmer Response: Correct the request. DJ Explanation: The program issued a DLET or REPL call that was rejected because the segment was not currently in hold status. Some possible reasons for this status code are: v The segment had not been previously retrieved with a Get Hold call. v The segment was already deleted using this PCB. After one Get Hold call, multiple REPL calls or a DLET call following a REPL call are valid, but multiple DLET calls are not. CK Explanation: CK is a combination of CF and CG. The message retrieved with this GU originated from an AOI user exit. The message was scheduled for transmission before IMS was last started. Programmer Response: This is an information-only status code. CL Explanation: CL is a combination of CE, CF, and CG. Please see the explanations of those codes. Programmer Response: This is an information-only status code. CM Explanation: The command that was entered on the CMD call has been executed and completed, but it resulted in an exception response that could not be built because of an insufficient amount of general work area (WKAP). Programmer Response: Increase WKAP if you want retrieval of the response. CN Explanation: The IOASIZE= parameter that was specified on the PSBGEN macro is defined for less than the required minimum for CMD calls (132 bytes). Programmer Response: Redefine IOASIZE= parameter on the PSBGEN for a minimum of 132 bytes.

Chapter 9. DL/I Status Codes

135

DX • FD
v The segment was obtained using a secondary index as the processing sequence. A subsequent DLET or REPL call using either this PCB or another PCB within the PSB caused the current secondary index entry for this PCB to be deleted. v A checkpoint call was issued following the Get Hold call and preceding the REPL or DLET call. v A rollback call was issued following the get hold call and preceding the REPL or DLET call. Programmer Response: Correct the program so that the segment is in hold status when a DLET or REPL is issued. DX Explanation: The program issued a DLET that violates the delete rule for that segment. Programmer Response: Check the program to see whether or not the program should delete that segment; if it should, check with your DBA (or the equivalent specialist at your installation) to find out what delete rule has been specified for that segment. EM Explanation: The EM status (empty area) indicates that there are no valid sequential dependent segments in the area. Programmer Response: Check to see that the correct area is being processed by the utility and that sequential dependent segments have been inserted. E1 Explanation: The DFSMSCE0 user routing exit rejected the ISRT or CHNG call by setting MSPRFL3=MSPR3REJ and MSPRSTAT=E1 in the DFSMSCEP user parameter list that is passed to the exit. Programmer Response: Refer to the user installation copy of the DFSMSCE0 exit for information on the MSPR3REJ and MSPRSTAT settings. Contact your system programmer. E2 Explanation: The DFSMSCE0 user routing exit rejected the ISRT or CHNG call by setting MSPRFL3=MSPR3REJ and MSPRSTAT=E2 in the DFSMSCEP user parameter list that is passed to the exit. Programmer Response: Refer to the user installation copy of the DFSMSCE0 exit for information on the MSPR3REJ and MSPRSTAT settings. Contact your system programmer. E3 Explanation: The DFSMSCE0 user routing exit rejected the ISRT or CHNG call by setting MSPRFL3=MSPR3REJ and MSPRSTAT=E3 in the DFSMSCEP user parameter list that is passed to the exit. Programmer Response: Refer to the user installation copy of the DFSMSCE0 exit for information on the MSPR3REJ and MSPRSTAT settings. Contact your system programmer. FA Explanation: IMS returns this status code when the program reaches a commit point and an arithmetic overflow occurs in an MSDB, DEDB, or VSO DEDB during 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 receive this status code on a SYNC call, a CHKP call, or a GU call to the message queue, depending on your program. The overflow occurred after the program issued a FLD/CHANGE call, or a REPL call for the MSDB, DEDB, or VSO DEDB. When this happens, IMS issues an internal ROLB call to eliminate the changes that the program has made since the last commit point. All database positioning is lost. Programmer Response: Reprocess the transaction. FC Explanation: The program issued a request that is not valid for the segment type. Programmer Response: Correct the request. FD Explanation: A nonmessage driven BMP reached a deadlock when IMS tried to get DEDB or MSDB resources (either DEDB UOWs or overflow latches) for the program. Or, a mixed-mode BMP reached a deadlock on any resource, either Fast Path or full function. IMS eliminates all database updates that the program has made since the last SYNC call, CHKP request, or SYMCHKP command (or since the program started processing, if the program has not issued a SYNC call or CHKP request). All database positioning is lost, unless you specified the P processing option in the PCB. Messages to a non-express alternate TP PCB are discarded. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: Start processing from the last commit point. If you reach a deadlock again, terminate the program.

136

Application Programming: EXEC DLI Commands for CICS and IMS

FE • FN
FE Explanation: IMS returns this status code any time a program issues a FLD call that receives a nonblank status code in the FSA. Programmer Response: See “Fast Path Databases” in IMS Version 7 Application Programming: Database Manager for an explanation of FSA status codes and correct the FLD call. FF Explanation: A program issued an ISRT call against an MSDB that has no free space. If IMS determines that there is no free space when the program issues the ISRT call, the program receives the FF status code for that call. IMS might not determine this until the program reaches the next commit point. In this case, IMS returns FF when the program issues a GU call to the message queue, a SYNC call, or a CHKP call, depending on which call caused the commit point. Programmer Response: To avoid this situation, specify more space for the MSDB at the next system start (cold start or normal restart). FG Explanation: FG is a combination of FE and FW. A batch-oriented BMP issued a FLD call that received a nonblank status code in the FSA, and the program has depleted its normal buffer allocation. Programmer Response: Check the FSA status code and correct the FLD call, and then issue SYNC or CHKP calls in the program more frequently. One way to handle this status code is to branch to an error routine that causes the program to issue SYNC or CHKP calls more frequently when it receives this status code. FH Explanation: A DEDB area was inaccessible to the requested service when the program issued a database request or when the program reached a commit point. The AREA was stopped or the DEDB randomizing routine was not loaded into storage. A /START DATABASE dedbname command will cause the DEDB randomizing routine to be reloaded. If IMS returns this status code on a call that caused a commit point to occur (a SYNC call, a message GU, a CHKP request, or a SYMCHKP command), IMS issues an internal ROLB call to eliminate the program’s database updates and message output created since the last commit point. If your program is accessing a DEDB in a data-sharing environment, and if the authorization fails when your program issues its first DL/I call to the DEDB, Fast Path returned this status code. Fast Path also notified the master terminal operator of the authorization failure. Your position in the database is before the first root in the 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 with PROCOPT=H and another PCB without PROCOPT=H, it is possible that only calls to the PCB with PROCOPT=H will receive the FH status code. This is because the area is accessible to IMS, but the required HSSP (high-speed sequential processing) setup could not be established. Message DFS0533A explains the reason for this occurrence and is sent to the job log. This status code is also returned if the PROCOPT for one PCB is more restrictive than the PROCOPT of a different PCB in the same PSB. Position is set to the beginning of the next accessible area. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: If the data in the area is important, contact the DBA. If the data in the area is unimportant, the program should roll back the changes. Your program can continue processing with the next available area. If the status code is related to an HSSP setup problem, fix the error as described in the message DFS0533A in the job log. FI Explanation: The program’s I/O area is not at a storage address that the program can access. Programmer Response: Correct the program. FM Explanation: The application program issued a request for which the randomizing routine returned a return code of 4.

| The key supplied on a DL/I call to a HALDB was greater | than the high key value for the last partition. Or the | user’s partition selection exit returned with RC=04 after | having been passed a key value with which to select a | partition.
Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: The database position has not changed. The application program must determine subsequent processing. FN Explanation: The program issued a FLD call that contains a field name in the FSA that is not defined in the DBD. IMS does not continue processing the FLD call or any of the FSAs in the FLD call. IMS returns an FN
Chapter 9. DL/I Status Codes

137

FP • FW
status code in this situation even if an earlier FSA in the same FLD call received an FE status code. Programmer Response: Issue a ROLB call to remove the effects of the incorrect FLD call and then correct the FLD call. FP Explanation: The I/O area referenced by a REPL, ISRT, or FLD/CHANGE call to an MSDB contains an invalid packed-decimal or hexadecimal field. Programmer Response: Correct the data in the I/O area. FR Explanation: One of the following situations exists: v A batch-oriented BMP issued a database request that forced the system to go beyond the buffer limit specified for the region. v A batch-oriented BMP received a GC status code in a PCB with PROCOPT=H. Another commit process was required before using the PCB again. IMS eliminates all database changes made by the program since the last SYNC call, CHKP request, or SYMCHKP command the program issued (or since the program started processing if the program has not issued any SYNC calls, CHKP requests, or SYMCHKP commands). All database positions for PCBs not referring to a DEDB with PROCOPT=P or H active are lost. If the PCB referred to a DEDB with PROCOPT=P or H active, the position is set to the valid position after the last commit process, or the start of the valid range if there was no commit process. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: Either terminate the program and restart it with a larger buffer allocation, or provide a routine that causes frequent commit points. If PROCOPT=H is used, make sure that a commit point is requested after a GC code has been returned. FS Explanation: For a root segment or direct dependent segment, this status code is returned only to BMPs. For a sequential dependent segment, this status code can be returned to either a BMP or a message-driven program: v A BMP issued an ISRT request for a root segment, a direct dependent segment, or a sequential dependent segment, but IMS could not get enough space in either the root-addressable or sequential dependent part of the DEDB area to insert the new segment: – If IMS returns this status code on an ISRT request for a root segment, a direct dependent segment, or a sequential dependent segment, the problem is with the root-addressable portion of the area, the independent overflow area, or the sequential dependent area. – If IMS returns this status code when the program issues a SYNC call, CHKP request, or SYMCHKP command, the problem is with the sequential dependent part of the area. In either case, IMS eliminates all of the database changes the program has made since the last commit point (or since the program started processing, if the program has not reached a commit point). v A message-driven program issued an ISRT request for a sequential dependent segment, and the sequential dependent part is full. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: Continue with other processing, and report the problem to the system programmer. FT Explanation: The Fast Path program issued a call to a Fast Path database that included too many SSAs. A call to a DEDB can include up to 15 SSAs. A call to an MSDB can include only one SSA. Programmer Response: Correct the call. FV Explanation: At least one of the verify operations in a FLD call issued in a batch-oriented BMP failed when the program reached a commit point. IMS eliminates the database updates the program has made since it issued the last SYNC or CHKP call (or if the program has not issued a SYNC or CHKP call, since the program started processing). All database positioning is lost. Programmer Response: Reprocess the transaction or terminate the program. FW Explanation: A BMP has used all buffers that are allocated for normal use, or all buffers have been modified. IMS returns this status code to warn you that you might be running out of buffer space. An FR status code might be imminent. If you have been processing a DEDB, you get FW for requests that change data. If you have been processing an MSDB, you get FW for all calls that change data and for GH calls.

138

Application Programming: EXEC DLI Commands for CICS and IMS

FY • GD
With a DEQ call, you receive this code if no buffers can be released. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: You can supply an error-handling routine, triggered by the FW status code, that will cause your program to issue SYNC calls, CHKP requests, or SYMCHKP commands as soon as an FW status code is returned to your program. This reduces the total buffer requirement. To avoid receiving the FW status code, issue SYNC or CHKP calls more frequently. FY Explanation: PROCOPT=H PCBs process segments sequentially in the forward direction. Position is established on a UOW and is moved forward only. Attempts to retrieve segments prior to the current UOW position are not allowed for HSSP application programs and will not be processed; they receive this status code. Programmer Response: Change the application program to retrieve segments in a forward direction only; use a PCB with a PROCOPT value other than H to access the segments in the backward direction. GA Explanation: In trying to satisfy an unqualified GN or GNP call, IMS crossed a hierarchic boundary into a higher level. If IMS returns GA after a STAT2 request, it means that the request that was just issued retrieved the total statistics for all the VSAM buffer subpools. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. This call results in a return code of 0. Programmer Response: This status code is an information-only status code. GB Explanation: In trying to satisfy a GN call, DL/I reached the end of the database or, if you used a SETR statement, the end of the current range. In this situation, the SSA for the call or qualification for the command specified data beyond the last occurrence, and the search was not limited to the presence of a known or expected segment occurrence. For example, a GN call was specified for a key greater than a particular value, rather than a GU call specifying a key value beyond the highest value. A GB status code can be returned for: GD Explanation: The program issued an ISRT call that was not qualified for all levels above the level of the segment being inserted. For at least one of the levels for which no qualification was specified, a prior request using this PCB established valid position on a segment. That position is no longer valid for one of these reasons: v The segment has been deleted by a DLET call using a different DB PCB. v An unqualified GN call v A qualified GN call without a maximum key (if no data is returned to the I/O area) In contrast, a GE status code, instead of a GB status code, can be returned for: v A GU call v A qualified GN call without a maximum key (if data is returned to the I/O area) v A qualified GN call with a maximum key IMS also returns this status code when it has closed a GSAM data set. The assumed position for a subsequent request for a GSAM or full-function database is the beginning of the database, or if a SETR statement was used for a DEDB database, the beginning of the current range. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: User determined. GC Explanation: An attempt was made to cross a unit-of-work (UOW) boundary, or an area boundary in the case of PROCOPT=H. For a batch-oriented BMP PCB with PROCOPT=H or PROCOPT=P, at least one call on the referenced PCB changed position in the database since the last commit process or after the program began executing. IMS did not retrieve or insert a segment. Position is before the first segment of the following UOW. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: User determined. However, if the GC status code results from a call that referred to a PCB with PROCOPT=H, the program must cause a commit process before any other call can be issued for that PCB. Failure to do so results in an FR status code.

2. STAT is a Product-sensitive programming interface. Chapter 9. DL/I Status Codes

139

GE • GL
v The segment was retrieved using an alternate processing sequence, and a REPL or DLET call for this DB PCB caused the index for the existing position to be deleted. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: User determined. GE Explanation: For call-level programs: IMS returns this status code when: v DL/I is unable to find a segment that satisfies the segment search argument described in a Get call. v For an ISRT call, DL/I cannot find one of the parents of the segment being inserted. v For an ISRT call, DL/I was requested to insert a root segment outside of the accessible range determined by a SETR statement. v The program issued a STAT3 call for OSAM buffer pool statistics, but the buffer pool does not exist. v The program issued a STAT call for VSAM buffer subpool statistics, but the subpools do not exist.
3

bytes and the original position of the deleted portion of the sequential dependent part. Position is at the end of the sequential dependent chain. GG Explanation: DL/I returns this status code if the segment being retrieved contains an invalid pointer and the application program has a processing option of GOT or GON. (Processing options are explained under PROCOPT in the discussion of program specification block generation in IMS Version 7 Utilities Reference: System.) This can occur when update activity in the database is going on concurrently with your program’s processing. For call-level programs: The PCB key feedback length and area will be based on the last segment that satisfied the call. Your position is at the beginning of the database. For command-level programs: If your request specified KEYFEEDBACK, the DIBKFBL will contain the length of the key of the last segment that satisfied the command. Your position is at the beginning of the database. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: Continue processing with another segment or terminate the program. The request that resulted in the GG status code might be successful if you issue it again. GK Explanation: DL/I has returned a different segment type at the same hierarchic level for an unqualified GN or GNP call. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. This call results in a return and reason code of 0. Programmer Response: This is an information-only status code. GL Explanation: For either call-level or command-level programs: The program issued a LOG request that contained an invalid log code for user log records. The log code in a LOG request must be equal to or greater than X'A0'. For call-level programs: DL/I returns GL on a DEQ request when the first byte of the I/O area referenced in the request did not contain a valid DEQ class (B-J).

v A nonmessage driven BMP issued a FLD call to an MSDB segment. After the FLD call but before a commit point, the MSDB segment was deleted. GE can be returned for this reason after either a SYNC or a CHKP call. For command-level programs: v DL/I is unable to find a segment that satisfies the segment described in a Get command. v For an ISRT command, DL/I cannot find one of the parents of the segment you’re inserting. v The program issued a STAT command for ISAM or OSAM buffer pool statistics, but the buffer pool does not exist.
3

v The program issued a STAT call for 3 VSAM buffer subpool statistics, but the subpools do not exist. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: The action you take depends on your program. Note: When a GNP call for a DEDB sequential dependent segment results in a GE status code, the I/O area contains a length indication of 10

3. STAT is a Product-sensitive programming interface.

140

Application Programming: EXEC DLI Commands for CICS and IMS

GP • L2
For command-level programs: EXECDLI returns a GL status for either a GN, GNP, GU, or DEQ command when the alphabetic character coded on the LOCKCLASS option is not within the range of B to J. An ABENDU1041 is then issued. Programmer Response: Correct the log code, which is the first byte of the log message. For call-level programs: If the program received this status code for a DEQ request, check the DEQ class code in the I/O area. For command-level programs: Check the alphabetic character coded for class on the LOCKCLASS option to ensure that it is in the range from B to J. GP Explanation: The program issued a GNP when there is no parentage established, or the segment level specified in the GNP is not lower than the level of the established parent. Programmer Response: Make sure you have established parentage before issuing GNP, and check the segment level specified by the GNP. HT Explanation: The HT status indicates that the High-Water-Mark time stamp (HWM TS) is less than the Logical Begin time stamp (LB TS). Programmer Response: The time stamp in the High-Water-Mark segment was not updated on the area data 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 dependent CI. II Explanation: The program issued an ISRT call that tried to insert a segment that already exists in the database. Current position after an II status code is just before 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 field already exists for the parent. v A segment with an equal logical twin sequence already exists for the parent. v The logical parent has a logical child pointer, the logical child does not have a logical twin pointer, and the segment being inserted is the second logical child for that logical parent. v The segment type does not have physical twin forward pointers and the segment being inserted is the second segment of this type for that parent, or it is the second HDAM or PHDAM root for one anchor point. v The segment being inserted is in an inverted structure. (The immediate parent of this segment in the logical structure is actually its physical child in the physical structure.) v A physically paired logical child segment already exists with a sequence field equal to that of the segment you’re inserting. For example, the segment could have been inserted with no duplication, but when an attempt was made to position for the insert of its physical pair, the segment had a duplicate key to an existing twin segment. v An application program inserted a key of X'X’FF...FF’' into a HISAM, HIDAM, or PHIDAM database. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: User determined. IX Explanation: The program issued an ISRT call that violated the insert rule for that segment. Some of the reasons that IMS returns this status code are: v The program tried to insert the logical child and logical parent, and the insert rule for the logical parent is physical and the logical parent does not exist. v The program tried to insert the logical child and the logical parent, and the insert rule is logical or virtual and the logical parent does not exist. In the I/O area, the key of the logical parent does not match the corresponding key in the concatenated key in the logical child. v The program tried to insert a logical child, and the insert rule of the logical parent is virtual and the logical parent exists. In the I/O area, the key in the logical parent segment does not match the corresponding key in the concatenated key in the logical child. v The program tried to insert a physically paired segment, where both sides of the physical pair are the same segment type and the physical and logical parent are the same occurrence. v The program issued an ISRT call to a GSAM database after receiving an AI or AO status code. Programmer Response: Correct the ISRT or the program.

| L2 | | | |
Explanation: The application program needed to allocate SDEP CI RBAs to contain the application programs’ insert activity for a particular AREA in the DEDB, but the request to acquire the AREA lock failed.
Chapter 9. DL/I Status Codes

141

LB • NE
| Programmer Response: Contact the IMS DBA or the | IMS Systems Programmer.
LB Explanation: The segment that the program tried to load already exists in the database. Other possible causes are: v A segment with an equal physical twin sequence field already exists for the parent. v A segment type does not have a physical twin forward pointer, and the segment being inserted is either the second segment of this segment type for the parent or the second HDAM or PHDAM root for one anchor point. v An application program inserted a key of X'FF...FF' into a HISAM, HIDAM, or PHIDAM database. Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command. Programmer Response: Correct the ISRT call or LOAD command, or find out if the load sequence is incorrect. Check with the DBA or the equivalent specialist at your installation. LC Explanation: The key field of the segment being loaded is out of sequence. Programmer Response: Check the segment and determine where it should be loaded. LD Explanation: No parent has been loaded for the segment being loaded. Programmer Response: Check the sequence of segments that have been loaded and determine where the parent should have been loaded. LE Explanation: The sequence of sibling segments being loaded is not the same as the sequence that is defined in the DBD. Programmer Response: Check and correct the sequence of the segments that are being loaded. LF Explanation: The source data for a logical child segment was found in the input stream of a load job for a High Availability Large Database (HALDB). Logical child segments cannot be loaded into a HALDB PHDAM or PHIDAM database. Instead, the segments must be added later in an update run. LS Explanation: The LS status means that an application program needed to allocate SDEP CI RBAs to contain the application programs’ insert activity for a particular area in a Data Entry Database and the CIs could not be locked by the RLM. The application work may be committed, but some other application work may not have enough CI space, depending on how much SDEP insert work was done and the first committed application. Programmer Response: Do a commit and be careful not to insert too many more SDEP segments. MR Explanation: Reserved. NA Explanation: The INIT call with DBQUERY in the I/O area or the QUERY command was issued, and at least one of the databases that could be accessed using this PCB was not available. A request made using this PCB will probably result in a BA status code if the INIT STATUS GROUPA has been issued or in a DFS3303I message and 3303 pseudo abend if it has not. An exception is when the database is not available because dynamic allocation failed. In this case, a request results in an AI (unable to open) status code. Programmer Response: This is an information-only status code. NE Explanation: Indexing maintenance issued a DL/I call, and the segment has not been found. This status code is included in message DFS0840I. The system console receives message DFS0840I INDEX ERROR (dbdname) NE (first 45 bytes of key). The application program receives a blank status code. An application program could have processed a secondary index as a database and thus deleted some of the secondary index entries. Subsequently, when a source segment is deleted, the secondary index for the source statement might not be present. For this reason, when the application program deletes a source segment and the index entry is not present, the DFS0840I message is sent to the system console, but a blank status code is returned to the application program. Programmer Response: Determine whether the secondary index has been processed as a database and, as a result, the key included in the DFS0840I Programmer Response: Remove all source data for logical child segments from the load job and insert them later with an update job.

142

Application Programming: EXEC DLI Commands for CICS and IMS

NI • QC
message was deleted. If this is not the case, check the cause for the index inconsistency with the database and correct it. NI Explanation: There is a duplicate segment in a unique secondary index. While IMS was inserting or replacing a source segment for a secondary index defined with a unique sequence field, the insertion of the secondary index segment was attempted but was unsuccessful because an index segment with the same key was found. One possible cause for a duplicate segment in the index is that the index DBD incorrectly specified a unique key value—secondary index only. In an online application program, the call is backed out and the program receives an NI status code. For a batch program that does not log to the IMS DASD log, IMS abnormally terminates the program with a U0828 abend. You should run batch backout. Programmer Response: The response is determined by the user. If duplicate secondary index entries occur, specify the index as non unique, and provide an overflow entry-sequenced data set. NL Explanation: The application program issued an extended checkpoint call. Checkpoint information is written to the log data set, but there is no DD statement in the batch step for the log, so no checkpoint was written. The DD name for the log data set is IEFRDER. Although no checkpoint information was written, normal commit processing was performed. Programmer Response: Provide an IEFRDER DD statement. No status is returned for a DD DUMMY statement. NO Explanation: A BSAM or VSAM physical I/O error occurred during a database request that is issued by the index maintenance function. For an online program, all updates made for the call are backed out and the application program receives the NO status code. For a batch program that does not log to the IMS DASD log, IMS abnormally terminates the program with an 826 abend. Programmer Response: See accompanying messages giving details of the error. In a batch environment, run batch backout. NU Explanation: An ISRT, DLET, or REPL request using this PCB might result in a BA status code if the INIT STATUS GROUPA call or QUERY command has been issued or in a DFS3303I message or 3303 pseudo abend if it has not. If the unavailable database is only required for delete processing, it is possible that the ISRT and REPL requests can be processed. Programmer Response: This is an information-only status code. OS Explanation: The OS status indicates that the STOPRBA parameter value given for the DEDB Sequential Dependent Scan Utility is too large for the current sequential dependent CI set. Programmer Response: Check the parameter value for validity and use a correct value or use the utilities default value for the scan end. QC Explanation: There are no more messages in the queue for the program. The reasons that IMS returns this status code are: v An application program issued a successful CHKP call, but the message GU call issued internally by the CHKP call was unsuccessful (that is, it did not return a message). v An application program processing APPC synchronous messages that does not set sync points for each message GU call (that is, mode=MULT on the TRANSACT macro) is returned a QC status code to force a sync point after each GU call. For more information regarding the TRANSACT macro, refer to IMS Version 7 Installation Volume 2: System Definition and Tailoring. v An MPP or transaction-oriented BMP issued a GU call to retrieve another message, but either there are no more messages or the processing limit (that is, PROCLIM=parm on the TRANSACT macro) has been reached. v IMS is shutting down or: – A /PSTOP REGION command has been issued for the dependent region in which the application program is processing. – A database dump (/DBD) command has been issued. – A database recovery (/DBR) command is in operation. – A stop subsystem (/STOP SUBSYS) command has been issued. For more information regarding these commands, refer to IMS Version 7 Command Reference. v IMS wants to reschedule the region (quick reschedule). For more information regarding quick reschedule, refer to IMS Version 7 Administration Guide: System. Programmer Response: This is an information-only
Chapter 9. DL/I Status Codes

143

QD • RX
status code. The application program should terminate. QD Explanation: The program issued a message GN or GCMD call, but there are no more segments for this message. Programmer Response: Process the message. QE Explanation: The program issued a message GN call before issuing a GU call to the message queue. In message-driven Fast Path programs, this code applies to message calls only. The program issued a message GN call before issuing a GU call to the message queue. In message-driven Fast Path programs, this code applies to message calls only. This code is also returned when a program issues a ROLB call, specifying the I/O area parameter, without having issued a successful message GU call during that commit interval. A message-driven Fast Path program issued a CHKP call to establish an internal GU call but the CHKP call failed with a status QC code. A successful GU call was never issued during the commit interval for the failing CHKP call. Information only status code for calls encountering SDEP full or FLD verify 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 RC Explanation: The ROLS call was issued with unsupported PCBs in the PSB, or the program is using an attached subsystem. If the ROLS call is in response to a SETS call, the call is rejected. If the ROLS call is in response to a SETU call, the call is processed, but updates to unsupported PCBs or an attached subsystem are not backed out. This status is only returned for a ROLS call in response to a SETU call if an attached subsystem is being used. Programmer Response: User determined. Explanation: The ROLS request was rejected because the PSB contains access to a DEDB, MSDB, or GSAM organization or has access to an attached subsystem. Programmer Response: The ROLS request is invalid in this environment. The program must either remove the use of the database organization that is preventing the use of the ROLS call or not use the ROLS call. RX Explanation: The program issued a REPL that violated the replace rule for that segment. Programmer Response: Correct the REPL call, or check with the DBA or the equivalent specialist at your installation. v SMB or CNT could not be found. v The program deallocated a conversation with a SETO call with the DEALLOCATE_ABEND option. Any subsequent ISRT calls are rejected with this status code. v The program issued an ISRT call without first issuing a GU call. v The logical terminal name or transaction code specified is Fast Path exclusive and is not available to this program. v The program issued an ISRT call for a segment shorter than 5 bytes. v The program issued an ISRT call for a SPA shorter than 6 bytes. v The logical terminal name or transaction code has leading blanks, instead of being left-justified. Programmer Response: Check the logical terminal name or transaction code, and correct it. RA Explanation: The token does not match a token for any outstanding SETS requests or the request was issued for a database PCB that did not get a BA status on the previous request. Programmer Response: The outstanding SETS request might have been canceled by a commit process, or an error exists in the use of the token.

| | | | | | |

Explanation: When using Shared Queues and the application ISRT(S) results in a message that spans multiple queue buffers, the second and subsequent buffers are PUT to the Shared Queues. If the Shared Queues are full and those CQS PUTs are rejected, this results in a STATUSQF being passed back to the application.

| Programmer Response: Correct the segment. Issue a | ROLB to back out any incomplete data.
QH Explanation: There has been a terminal symbolic error. The output logical terminal name or transaction code is unknown to IMS. Some reasons for receiving this status code are: v The program tried to insert an alternate response PCB receiving a QC status code for a GU call. v The program tried to insert to an I/O PCB that has a logical terminal name of blanks. This could occur after the program issued a GU call for a message that originated either from a batch-oriented BMP or a CPI Communications driven program.

144

Application Programming: EXEC DLI Commands for CICS and IMS

SA • TJ
SA Explanation: On a SETS request, IMS was not able to obtain the storage space for the data in the I/O area. Programmer Response: Use a larger region size for the job step. SB Explanation: The maximum number of levels, nine, of SETS requests were already specified, and this request is attempting to set the tenth. Programmer Response: Correct the program. SC Explanation: A SETS or SETU call was issued with unsupported PCBs (DEDB, MSDB, or GSAM) in the PSB, or the program is using an attached subsystem. Programmer Response: For a SETS call, the request is rejected. Remove the unsupported PCBs or use the SETU call. For a SETU call, the program can proceed with the knowledge that a ROLS call will not back out changes for the unsupported PCBs. The other option is to not use the SETS or ROLS function. SY Explanation: IMS incurred an internal error during Syncpoint processing for an IMS/JAVA SYNC request call. Programmer Response: Contact your IMS system programmer. TA Explanation: This status code applies to CICS online command-level programs only, and it is returned following a scheduling request. The PSB named in the request is not in the PSB directory. Programmer Response: Correct the name of the PSB in the scheduling request, or add the PSB name to the PSB directory. TC Explanation: This status code applies to CICS online command-level programs only, and it is returned following a scheduling request. It means that you have already scheduled a PSB. Programmer Response: Correct your program so that you terminate a PSB before scheduling another. If you want to reschedule a PSB, you must have already terminated the PSB. TH Explanation: This status code applies to CICS online command-level programs only, and it is returned following a database request or a statistics request. The program attempted to access the database before scheduling a PSB. Programmer Response: Correct your program, and schedule a PSB before accessing the database. TI Explanation: This status code applies to command-level programs only, and it is returned after an ISRT command. The ISRT command defined an invalid path to the segment. Data must be transferred for all segments between the first named segment and the last named segment. Programmer Response: Correct the ISRT command, specifying a FROM option for each segment to be transferred. TJ Explanation: This status code applies to CICS online command-level programs only, and it can be returned after any command that a CICS online program uses. DL/I is not active. Programmer Response: Contact your DBA. CICS TE Explanation: This status code applies to CICS online command-level programs only, and it is returned following a scheduling request. The PSB could not be scheduled because an initialization error occurred. Programmer Response: See your system programmer or DBA. For information on possible causes for the PSB initialization error, see IMS Version 7 Application Programming: Database Manager. TG Explanation: This status code applies to CICS online command-level programs only, and it is returned following a terminate request. The program issued a terminate request when there was no PSB scheduled. Programmer Response: This is an information-only status code. If you only wanted to terminate a PSB, continue with processing. If you also wanted to cause a sync point, issue a SYNCPOINT command. (No sync point was caused by the unsuccessful terminate request.) Rather than having an abnormal termination occur, this status code is returned to the application program that issued the EXEC DLI command.

Chapter 9. DL/I Status Codes

145

TL • UC
must be reinitialized with DL/I defined as active in the SIT. TL Explanation: This status code applies to CICS online command-level programs only, and it is returned after a scheduling request. A conflict in scheduling intent occurred. (This cannot occur if program isolation has been specified.) Programmer Response: Specify program isolation in the SIT. If program isolation has not been specified, wait until the PSB is no longer in use, and reschedule it. TN Explanation: This status code applies to command-level programs only, and it can be returned after any of the commands. An invalid SDIB exists. An initialization call was not made, or the system’s DIB (not the application program’s DIB) was overlaid. Programmer Response: Check your program to make sure that you did not use an entry statement, as you would in a call-level batch program. Also make sure that no addressing errors are in your program that would cause an overlay. TO Explanation: This status code applies to command-level programs only, and it is returned following a REPL command. A path-replace error occurred. The segments to be replaced are compared to the previous Get command and one of the following situations occurred: v A segment is named to be replaced that was not retrieved by the Get command. v Data had not been transferred (no INTO option) for this segment on the Get command. v The attributes of the data to be transferred do not match the data in the database. Programmer Response: Correct the program. TP Explanation: This status code applies to command-level programs only, and it is returned following any of the database commands, a LOAD command, or a statistics request. The number of the PCB specified in the USING option is higher than the number of PCBs in the PSB being used, or an invalid processing option was specified. For example, the program tried to issue a LOAD command without having the L processing option specified in its PSB. An EXEC DLI command is being attempted against a GSAM PCB. This is invalid. Programmer Response: Check the PSB and correct your program. TR Explanation: This status code means that the CICS XDLIPRE exit routine returned X'04' in register 15 because the routine determined that the immediately preceding DL/I request should not be executed. Programmer Response: Contact the CICS system programmer. TY Explanation: This status code applies to CICS online command-level programs only, and it is returned following a database or statistics request. The database was not open when the request was issued. Programmer Response: Contact your DBA or system programmer. The database can be checked and opened by using operator commands. TZ Explanation: This status code applies to CICS online command-level programs only, and it is returned following a database or statistics request. The length of the retrieved segment is greater than 64 KB. Programmer Response: Contact your DBA or system programmer; the database definition might require modification. UB Explanation: This status code is returned when IMS is unable to obtain private buffer pool. Programmer Response: No DFS0535I message is issued if the High Speed Reorganized Utility (HSRE) is being used when this status code is received. See the DFS2712I messages issued at utility termination for the name of the module, abend subcode, Utility High Speed Workarea (UHSW) storage area dump, IOAR (DEDB I/O), and register contents. If the DBFPAPB0 return code is 08, storage is not available for the private buffer pool. If the DBFHUSS0 return code is 10, the request for private buffers is for the initial buffer set and the private pool anchor address already exists. UC Explanation: This status code is returned for the following reasons: v For batch programs in which a checkpoint record was written to the UCF journal data set. For information about the Utility Control Facility (UCF), see IMS

146

Application Programming: EXEC DLI Commands for CICS and IMS

UP • V1
Version 7 Administration Guide: Database Manager and IMS Version 7 Utilities Reference: Database and Transaction Manager. During the processing of an HD reorganization, a reload, or an initial load program under the supervision of the Utility Control Facility (UCF), a checkpoint record was written to the UCF journal data set. IMS returns this status code to indicate that the last ISRT call was correct and the initial load program might continue or it might perform a checkpoint procedure before continuing. v When a connect failed. Programmer Response: This is an information-only status 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 to correct the error. UP Explanation: This status code is returned when the UOW requested is greater than the UOW range. Programmer Response: Correct the error and run the job again. UR Explanation: This status code is returned for batch programs only. Your initial load program is being restarted under UCF. For information about the Utility Control Facility (UCF), see IMS Version 7 Administration Guide: Database Manager and IMS Version 7 Utilities Reference: Database and Transaction Manager. The program terminated while executing under UCF. The job was resubmitted with a restart request. Programmer Response: Ensure that the program is in proper sequence with database loading. The program uses the I/O area and the DB PCB key feedback area to do this. US Explanation: This status code is returned for batch programs only. The initial load program is about to stop processing. While processing an HD reorganization reload or user initial load program under the supervision of UCF, the operator replied to the WTOR from UCB and requested the current function to terminate. For information about the Utility Control Facility (UCF), see IMS Version 7 Administration Guide: Database Manager and IMS Version 7 Utilities Reference: Database and Transaction Manager. The last ISRT call was processed. Programmer Response: Ensure that the initial load program performs a checkpoint procedure of its data sets and returns with a nonzero value in register 15. UW Explanation: This status code is returned when IMS is unable to obtain a work area. Programmer Response: Increase the REGION size and run the job again. UX Explanation: This status code is returned for batch programs only. A checkpoint record was written, and processing stopped. This is a combination of UC and US status codes. Programmer Response: See the descriptions of UC and US status codes. U1 Explanation: This status code is returned when the area name specified is not valid. Programmer Response: Correct the error and run the utility job again. U9 Explanation: This status code is returned when the area access intent is read or read only. Access intent must be UP or EX. Programmer Response: Use the /STA DB ACCESS command to set the access intent to UP or EX and run the job again. V1 Explanation: The program tried to insert or replace a variable-length segment that is too long. The length of the segment must be equal to or less than the maximum length specified in the DBD. IMS also returns status code V1 when the specified minimum length cannot hold the complete sequence field of the segment type. In this situation, status code V1 results from one of three instances: processing without an edit/compression routine; processing with an edit/compression routine, but not specifying the key compression option; or coding a length field (LL) that is less than the specified minimum length. The length must be long enough to include the entire reference field; if the segment is a logical child, it must include the entire concatenated key of the logical parent and all sequence fields for the paired segment. The program tried to delete a variable-length segment. The copy of this segment in the user’s I/O area contains an invalid length field. IMS also returns this status code when an invalid record length is specified in a GSAM call. Programmer Response: Correct the program.

Chapter 9. DL/I Status Codes

147

V2 • XD
V2 Explanation: This status code applies to command-level programs only, and it is returned following a database or LOAD command. The segment length is missing or invalid. The segment length must be a positive integer. For variable-length segments, it is the maximum size acceptable to the program’s I/O area. Programmer Response: Check that the program translated and compiled correctly. The value of any segment length in a path command should not exceed 32 KB, and the sum of the lengths should not exceed 64 KB. V3 Explanation: This status code applies to command-level programs only, and it is returned following a Get or ISRT command. The field length is missing or invalid. The field length must be a positive integer, and it must be specified for each field in a WHERE option. Programmer Response: Correct the program. V4 Explanation: This status code applies to command-level programs only, and it is returned following any of the database commands or a LOAD command. The length of a variable-length segment is invalid. The LL field as provided by the program on an ISRT or REPL command, or as received in the I/O area on a Get command, exceeds the value of SEGLENGTH. Programmer Response: Correct the program. V5 Explanation: This status code applies to command-level programs only, and is returned following a Get, REPL, or ISRT command. The offset is invalid. The offset must be a positive integer and not greater than the segment length. Programmer Response: Correct the program. V6 Explanation: This status code applies to command-level programs only, and it is returned following a Get or ISRT command using the KEYS option. The concatenated key length is missing or invalid. The length of the concatenated key must be a positive integer. Programmer Response: Correct the program. V7 Explanation: This status code applies to command-level programs only, and is returned following a STAT command. It means that the statistics area length is either too small or invalid. The length must be a positive integer, and it must be at least 72 bytes for unformatted statistics, 120 bytes for summary statistics, and 360 bytes for formatted statistics. Programmer Response: Correct the program. XA Explanation: The program tried to continue processing the conversation by passing the SPA to another program through a program-to-program message switch after already responding to the terminal. Programmer Response: If a response has been sent, the SPA should be returned to IMS. Correct the program. XB Explanation: The program has passed the SPA to another program but is trying to respond to the originating terminal. Programmer Response: No response is allowed by a program that is passed control of the program through a program-to-program message switch. XC Explanation: The program inserted a message that has some bits in the Z1 field set. The Z1 field is reserved for IMS. Programmer Response: Correct the program to prevent it from setting those bits. XD Explanation: IMS is terminating by a CHECKPOINT FREEZE or DUMPQ. IMS returns this code to a BMP that has issued a CHKP or SYNC call. If it is a transaction-oriented BMP, IMS does not return a message. IMS also returns XD when a batch program issues a SYNC call. Programmer Response: Terminate the program immediately. IMS will terminate the program abnormally if the program issues another call.

148

Application Programming: EXEC DLI Commands for CICS and IMS

XE • X7
XE Explanation: A program tried to insert a SPA to an alternate express PCB. Programmer Response: Regenerate the PSB and remove the EXPRESS=YES option from the PCB, or define another non-express PCB to be used in the ISRT call. XF Explanation: IMS is ignoring the ISRT call for the SPA, because the specified alternate PCB had its destination set to a logical terminal but was not defined as ALTRESP=YES during PSB generation. MSC directed routing does not support a program-to-program switch between conversational transactions. Programmer Response: Correct the application program or change the PSB generation for that alternate PCB to specify ALTRESP=YES. XG Explanation: IMS ignored the ISRT call because the current conversation requires a fixed-length SPA, and the ISRT call was to a program with a different length or variable-length SPA, while the source IMS system was earlier than IMS 6.1. If the SPA ISRT on a remote system is not going back to the input terminal (IOPCB), the SPA size must be the same as the size of the current one, if the source IMS system is earlier than IMS 6.1. Programmer Response: Correct the program or the SPA definitions. XX Explanation: An error occurred during GSAM initialization or during GSAM call processing. If this status code is in the GSAM PCB before the application program issued the first call, the error was detected during 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 will result in an abnormal termination of the program. The program should terminate. X7 Explanation: The length of the SPA is incorrect. The program modified the first 6 bytes. Programmer Response: Correct the SPA and the program. X2 Explanation: The first ISRT call to an alternate PCB whose destination is a conversational transaction code is not for the SPA. The SPA must be inserted with the first ISRT call. Programmer Response: Insert the SPA, and then reinsert the message segment. X3 Explanation: The program modified the first 6 bytes of the SPA; the SPA is now invalid. Programmer Response: Correct the program and restore the original bytes. X4 Explanation: The program issued an ISRT call to pass the SPA to a nonconversational transaction code. It did this by referencing a PCB whose destination was set for the nonconversational transaction code. You can send the SPA only to transaction codes that are defined as conversational. Programmer Response: Correct the ISRT call. Send only data segments. X5 Explanation: The program issued more than one ISRT call to send the SPA to a PCB whose destination is a transaction code. Only one SPA is allowed per message. Programmer Response: Correct the program. X6 Explanation: An invalid transaction code name was inserted into the SPA. This will occur if the input is from LU 6.2 (APPC) or OTMA and if a dynamic control block was built for the transaction code. Programmer Response: Correct the program to set the proper transaction code name.

Chapter 9. DL/I Status Codes

149

blanks (bb)
blanks (bb) Explanation: The call was completed. Programmer Response: Proceed with processing.

150

Application Programming: EXEC DLI Commands for CICS and IMS

Part 3. Appendixes

© Copyright IBM Corp. 2000, 2001

151

152

Application Programming: EXEC DLI Commands for CICS and IMS

Bibliography
This bibliography includes all the publications cited in this book, including the publications in the IMS library. CICS/ESA Version 4.1 Application Programming Guide, SC33-1169 CICS/ESA Version 4.1 Application Programming Reference, SC33-1170 CICS Family: General Information, GC33-0155 CICS Transaction Server for OS/390 Release 3 CICS Application Programming Guide, SC33-1687 CICS Transaction Server for OS/390 Release 3 CICS Application Programming Reference, SC33-1688
GC26-1120 SC26-9434 SC26-9435 GC26-9437 SC26-9438 SC26-9440 SC26-9441 MC2 OTMA OG RPG SOP URDBTM URS Messages and Codes, Volume 2 Open Transaction Manager Access Operations Guide Release Planning Guide Sample Operating Procedures Utilities Reference: Database and Transaction Manager Utilities Reference: System

GC26-9431 SC26-9439

IMS Version 7 Library
SC26-9419 SC26-9420 SC26-9421 SC26-9422 SC26-9423 SC26-9424 ADB AS ATM APDB APDG APCICS Administration Guide: Database Manager Administration Guide: System Administration Guide: Transaction Manager Application Programming: Database Manager Application Programming: Design Guide Application Programming: EXEC DLI Commands for CICS and IMS Application Programming: Transaction Manager Customization Guide Common Queue Server and Base Primitive Environment Guide and Reference Command Reference DBRC Guide and Reference Diagnosis Guide and Reference Failure Analysis Structure Tables (FAST) for Dump Analysis IMS Java User’s Guide Installation Volume 1: Installation and Verification Installation Volume 2: System Definition and Tailoring Master Index and Glossary Messages and Codes LK3T-3526 SK2T-0730 SK2T-6700

Supplementary Publications LPS Licensed Program Specifications SOC Summary of Operator Commands

Online Softcopy Publications CDROM IMS Version 7 Softcopy Library CDROM IBM Online Library: Transaction Processing and Data CDROM OS/390 Collection

SC26-9425 SC26-9427 SC26-9426

APTM CG CQS

SC26-9436 SC26-9428 LY37-3738 LY37-3739

CR DBRC DGR FAST

SC27-0832 GC26-9429 GC26-9430

IJUG IIV ISDT

SC26-9432 GC26-9433

MIG MC1

© Copyright IBM Corp. 2000, 2001

153

154

Application Programming: EXEC DLI Commands for CICS and IMS

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

B
backing out database changes 106 backout points, intermediate 106 basic checkpoint 105 batch program, issuing checkpoints 105 batch programs, command-level samples assembler 74 C 85 COBOL 78 PL/I 81 BILLING segment 9 BMP (batch message processing) program, issuing checkpoints 105

C
C program, DL/I command-level sample 85 call-level programs comparing with command-level programs command codes and options 114 commands and calls 113 DL/I calls available to IMS and CICS command-level 113 categories, status codes 117 checkpoint (CHKP) EXEC DLI command basic 105 current position 105 symbolic EXEC DLI command, description CHKP (Checkpoint) command description 49, 105 examples 50 format 49 options 49 restrictions 50 usage 49 COBOL DL/I command-level sample 78 I/O area 72
© Copyright IBM Corp. 2000, 2001

106

D
data availability enhancements 109 data entry database 93 database availability obtaining information 109 status codes, accepting 109

155

database description name field, DIB (DL/I interface block) 71 database example, medical hierarchy 8 database integrity, maintaining 105 database organization field, DIB (DL/I interface block) 71 database processing, fast path 93 database recovery, planning for backing out database changes 106 checkpoints, take with basic CHKP command 105 checkpoints, taking 106 restarting your program, XRST command 106 DB PCB 11 DBCTL facilities ACCEPT command 109 data availability 109 QUERY command 109 REFRESH command 109 ROLS command 107 SETS command 107 DEDB (data entry database) processing overview 93 POS command 102 subset pointers 93 defining application program elements to IMS AIB 67 DIB 68 I/O area 71 key feedback area 71 DEQ (Dequeue) command description 50 examples 51 format 50 options 51 restrictions 51 usage 51 DIB (DL/I interface block) accessing information 68 database description name field 71 database organization field 71 fields 68 key feedback length field 71 segment level field 70 segment name field 70 status code field 69 structure 68 translator version 69 direct dependent segments, in DEDBs 93 DL/I interface block 68 DLET (Delete) command description 15 example 16 format 15 options 15 Restrict 16 usage 16 dynamic backout 106

EXEC DLI (continued) compiler options, required 91 linkage editor options, required 92 preparing program for execution 91 program summary 13 syntax of commands 13 translator options, required 91 EXEC DLI commands ACCEPT 49 CHKP 49 DEQ 50 DLET 15 GN 17 GNP 22 GU 28 ISRT 33 LOAD 51 LOG 52 POS 39 QUERY 53 REFRESH 54 REPL 40 RETRIEVE 44 ROLB 55 ROLL 56 ROLS 57 SCHD 46 SETS 58 SETU 59 STAT 60 SYMCHKP 61 TERM 47 XRST 63 EXEC DLI options, use with subset pointers

95

F
Fast Path, subset pointers with DEDBs fast path database, processing 93 fields in DIB 68 FIRST insert rule 37 free space, identifying 103 93

G
GC status code 103 general programming guidelines 73 GETFIRST option examples 96 retrieving first segment in subset 96 GN (GET NEXT) command description 17 examples 21 format 17 options 18 restrictions 22 usage 21 GNP (GET NEXT in Parent) command description 22 examples 27 format 22 options 23

E
EXEC DLI allowable commands 14

156

Application Programming: EXEC DLI Commands for CICS and IMS

GNP (GET NEXT in Parent) command (continued) restrictions 27 usage 26 GSAM PCB 11 GU (GET UNIQUE) command description 28 examples 32 format 28 options 29 restrictions 33 usage 32 guidelines, general programming 73

locating a specific sequential dependent 102 last inserted sequential dependent 102 LOG command description 52 examples 53 format 53 options 53 restrictions 53 usage 53

M
medical database example description 8 segments 8 MOVENEXT option examples 98 use when moving subset pointer forward moving subset pointer forward 98

H
HERE insert rule 37 hierarchical database example, medical HOUSHOLD segment 10 8

98

I
I/O area assembler language 72 COBOL 72 coding 72 command-level program 71 PL/I 72 symbolic CHKP 106 XRST 106 I/O PCB (input/output PCB) 11 ILLNESS segment 8 intermediate backout points 106 ISRT (insert) command insert rules 37 ISRT (Insert) command description 33 examples 38 format 34 options 34 restrictions 38 usage 37 issue checkpoints in batch or BMP programs

O
online programs, command-level samples assembler 74 C 85 COBOL 78 PL/I 81 options for subset pointers GETFIRST 96 MOVENEXT 98 SET 98 SETCOND 99 SETZERO 97

P
P processing option 103 path command 44 PATIENT segment 8 PAYMENT segment 9 PCB (program communication block) in application programs, summary types 11 PL/I DL/I command-level sample 81 I/O area 72 pointers, subset DBD, defining 95 description 93 GETFIRST option 96 MOVENEXT option 98 preparation for using 94 PSB, defining 95 sample application 95 SET option 98 SETCOND option 99 SETZERO option 97 status codes 101 POS command description 39

105

12

K
key feedback area command-level program 71 length field in DIB 71

L
LAST insert rule 37 level number field in DIB 70 link editing, EXEC DLI 92 linkage editor options with EXEC DLI LOAD (Load) command description 51 examples 52 format 52 options 52 usage 52 92

Index

157

POS command (continued) EXEC DLI command format 39 format 39 free space, identifying 103 locating a specific sequential dependent 102 locating the last inserted sequential dependent options 39 usage 40 using with DEDBs 102 processing DEDBs 93 Fast Path, P (position) option 103 programming guidelines, general 73 PSB (program specification block), format 12

102

Q
QUERY command description 53 example 53 format 53 options 53 restrictions 54 usage 53

ROLB (Rollback) command (continued) restrictions 55 usage 55 ROLL command description 56 examples 56 format 56 options 56 restrictions 56 usage 56 ROLS command 107 description 57 examples 57 format 57 options 57 restrictions 58 usage 57 RULES=FIRST 37 RULES=HERE 37 RULES=LAST 37

S
sample programs command-level assembler language batch 74 online 74 command-level C batch 85 online 85 command-level COBOL batch 78 online 78 command-level PL/I batch 81 online 81 SCHD (Schedule) command description 46 examples 47 format 46 options 46 usage 47 segment level number field 70 segment name field, DIB (DL/I interface block) segments in medical database example 8 sequential dependent segments free space, identifying 103 in DEDBs 93 locating a specific dependent 102 locating the last inserted dependent 102 POS command 102 SET option examples 98 resetting a subset pointer 98 SETCOND option examples 99 setting a subset pointer conditionally 99 SETS command description 58 example 59 format 58 options 58

R
randomizing routine, FM status code 137 recovering databases 105 recovery EXEC DLI commands basic CHKP 105 SYMCHKP 106 XRST 106 REFRESH command 109 description 54 example 54 format 54 options 54 restrictions 55 usage 54 REPL (Replace) command description 40 examples 43, 44 format 41 options 41 restrictions 44 usage 42 resetting a subset pointer 98 restarting your program, with EXEC DLI XRST command 106 RETRIEVE command description 44 examples 46 format 45 options 45 restrictions 46 usage 45 ROLB (Rollback) command description 55 examples 55 format 55 options 55

70

158

Application Programming: EXEC DLI Commands for CICS and IMS

SETS command (continued) restrictions 59 usage 59 setting a subset pointer conditionally 99 to zero 97 SETU command description 59 example 60 format 59 options 60 restrictions 60 usage 60 SETZERO option examples 97 setting a subset pointer to zero 97 STAT command description 60 examples 61 format 61 options 61 usage 61 status code, field in DIB 69 status codes categories 117 checking in a command-level program 69 database calls 122 database calls, table 117 message calls, table 122, 124 processing option P 103 subset pointers 101 subset pointers DBD, defining 95 description 93 GETFIRST option 96 MOVENEXT option 98 preparation for using 94 PSB, defining 95 sample application 95 SET option 98 SETCOND option 99 SETZERO option 97 status codes 101 symbolic checkpoint restart 106 XRST 106 SYMCHKP (Symbolic Checkpoint) command current position 62 description 61, 106 examples 63 format 61 options 62 restrictions 63 usage 62 System Service ACCEPT 49 CHKP 49 DEQ 50 LOAD 51 LOG 52 QUERY 53

System Service (continued) REFRESH 54 ROLB 55 ROLL 56 ROLS 57 SETS 58 SETU 59 STAT 60 SYMCHKP 61 XRST 63

T
TERM (Terminate) command description 47 examples 48 format 47 options 47 usage 47 translating, EXEC DLI program 91 translator options required for EXEC DLI 91 translator version, DIB (DL/I interface block) 69 TREATMNT segment 9

U
Utility Control Facility (UCF) 147

V
variable names, mandatory 68

X
XRST (Extended Restart) command description 63 examples 65 format 63 options 63 restrictions 65 usage 64

Index

159

160

Application Programming: EXEC DLI Commands for CICS and IMS

Readers’ Comments — We’d Like to Hear from You
IMS Version 7 Application Programming: EXEC DLI Commands for CICS and IMS Publication No. SC26-9424-01 Overall, how satisfied are you with the information in this book? Very Satisfied h Satisfied h Neutral h Dissatisfied h Very Dissatisfied h

Overall satisfaction

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

Accurate Complete Easy to find Easy to understand Well organized Applicable to your tasks

Please tell us how we can improve this book:

Thank you for your responses. May we contact you?

h Yes

h No

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.

Name Company or Organization Phone No.

Address

___________________________________________________________________________________________________

Readers’ Comments — We’d Like to Hear from You
SC26-9424-01

Cut or Fold Along Line

Fold and _ _ _ _ _ _ _ _ _ _Fold and_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _ _ _ _ _ staple _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Tape _ _ _ _ _ _ _ _ Tape _ _ _ _ do not _ _ _ _ NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES

BUSINESS REPLY MAIL
FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE

International Business Machines Corporation Department BWE/H3 P.O. Box 49023 San Jose, CA 95161-9945

_________________________________________________________________________________________ Fold and Tape Please do not staple Fold and Tape

SC26-9424-01

Cut or Fold Along Line

Program Number: 5655-B01

Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber.

SC26-9424-01

Spine information:

IMS Version 7

Application Programming: EXEC DLI Commands for CICS and IMS