IMS Appl Prog

IMS
Application Programming: Database Manager

V ersion 9
SC18-7809-04
IMS

V ersion 9
SC18-7809-04
Note Before using this information and the product it supports, read the information in Notices on page 379.
| |
This edition applies to IMS Version 9 (program number 5655-J38) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC18-7809-03. Copyright IBM Corporation 1974, 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . v Tables . . . . . . . . . . . . . . . vii About This Book. . . . . . . . . . . ix
Summary of Contents . . . . . . . . . Prerequisite Knowledge . . . . . . . . IBM Product Names Used in This Information . How to Read Syntax Diagrams . . . . . . Accessibility Features for IMS Version 9 . . . How to Send Your Comments . . . . . . . . . . ix . ix . . x . . xi . xiii . xiii Specifying the AIB Mask for ODBA Applications . Specifying the UIB (CICS Online Programs Only). Specifying the I/O Areas . . . . . . . . . Formatting Segment Search Arguments (SSAs). . GSAM Databases . . . . . . . . . . . The AIBTDLI Interface. . . . . . . . . . Language Specific Entry Points . . . . . . . Program Communication Block (PCB) Lists. . . The AERTLDI interface . . . . . . . . . Language Environments . . . . . . . . . Special DL/I Situations . . . . . . . . . . . . . . . . . . . . 74 77 80 80 85 85 86 89 91 91 93
Summary of Changes . . . . . . . . xv
| |
Changes to the Current Edition of This Book IMS Version 9 . . . . . . . . . . Changes to This Book for IMS Version 9. . Library Changes for IMS Version 9 . . . for . . . . . . . xv . xv . xv
Chapter 4. Current Position in the Database After Each Call . . . . . . . 95

Current Position after Successful Calls . . . . . 95 Current Position after Unsuccessful Calls . . . . 100 Multiple Processing . . . . . . . . . . . 104
Part 1. Writing Application Programs 1

| |
Chapter 5. Recovering Databases and Maintaining Database Integrity . . . . 111

Issuing Checkpoints . . . . . . . . . . Restarting Your Program From the Latest Checkpoint . . . . . . . . . . . . . Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) . . . . . . . . Reserving Segments for the Exclusive Use of Your Program . . . . . . . . . . . . . . . 111 . 111 . 112 . 118
Chapter 1. How Application Programs Work with Database Manager . . . . . 5

IMS Environments . . . . . . . . . . . . 5 DL/I and Your Application Program . . . . . . 7 DL/I Calls . . . . . . . . . . . . . . . 7 DL/I Codes . . . . . . . . . . . . . . 8 Database Descriptions (DBDs) and Program Specification Blocks (PSBs). . . . . . . . . . 9 DL/I for CICS Online Users . . . . . . . . . 10 DL/I using the ODBA Interface . . . . . . . 12 Database Hierarchy Examples . . . . . . . . 13
Chapter 6. The Database Resource Adapter (DRA) . . . . . . . . . . . 121

Thread Concepts . . . . . . . . . . . . Sync Points . . . . . . . . . . . . . . DRA Startup Table . . . . . . . . . . . Enabling the DRA for a CCTL . . . . . . . . Enabling the DRA for the ODBA Interface . . . . Processing CCTL DRA Requests . . . . . . . Processing ODBA Calls . . . . . . . . . . CCTL-Initiated DRA Function Requests . . . . PAPL Mapping Format . . . . . . . . . . Terminating the DRA. . . . . . . . . . . Designing the CCTL Recovery Process . . . . . CCTL Performance: Monitoring DRA Thread TCBs 121 124 128 129 130 131 132 132 141 141 142 143
Chapter 2. Writing Your Application Programs . . . . . . . . . . . . . 19

Programming Guidelines . . . . . . . . Segment Search Arguments (SSAs) . . . . Considerations for Coding DL/I Calls and Data Areas . . . . . . . . . . . . . . Preparing to Run Your CICS DL/I Call Program Examples of How to Code DL/I Calls and Data Areas . . . . . . . . . . . . . . . . . . . . 19 . 20 . 28 . 29 . 29
Chapter 3. Defining Application Program Elements. . . . . . . . . . 53

Formatting DL/I Calls for Language Interfaces Assembler Language Application Programming C Language Application Programming . . . COBOL Application Programming. . . . . Pascal Application Programming . . . . . Application Programming for PL/I . . . . Specifying the I/O PCB Mask . . . . . . Specifying the DB PCB Mask . . . . . . Specifying the AIB Mask . . . . . . . .
Copyright IBM Corp. 1974, 2011
Chapter 7. Secondary Indexing and Logical Relationships . . . . . . . . 149

How Secondary Indexing Affects Your Program Processing Segments in Logical Relationships . 149 . 152
. . . . . . . . .
. . . . . . . . .
53 54 56 59 62 64 67 70 73
Chapter 8. Processing GSAM Databases . . . . . . . . . . . . . 157

Accessing GSAM Databases GSAM Record Formats . . GSAM I/O Areas . . . . . . . . . . . . . . . . . . . . . . . . . . 157 . 161 . 162
iii
GSAM Status Codes . . . . . . . Symbolic CHKP and XRST with GSAM GSAM Coding Considerations. . . . Origin of GSAM Data Set Characteristics
. . . .
. . . .
. . . .
. . . .
162 163 163 164
Chapter 9. Processing Fast Path Databases . . . . . . . . . . . . . 169

Main Storage Databases (MSDBs). . . . . . Data Entry Databases (DEDBs) . . . . . . Fast Path Database Calls . . . . . . . . Processing MSDBs and DEDBs . . . . . . Restrictions on Using Calls for MSDBs . . . . Processing DEDBs (IMS and CICS with DBCTL) Calls with Dependent Segments for DEDBs . . DEDB DL/I calls to extract DEDB information . Fast Path Coding Considerations . . . . . . . . . . . 169 170 170 171 178 178 . 187 . 188 . 195
ROLL Call . . ROLS Call . . SETS/SETU Call SNAP Call . . STAT Call . . SYNC Call . . TERM Call (CICS XRST Call . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online Programs . . . . . .
. . . . . . . . . . . . Only) . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
280 281 282 284 286 288 289 290
Chapter 13. Relationship Between Calls and AIB and PCBs. . . . . . . 295 Chapter 14. DL/I Test Program (DFSDDLT0) . . . . . . . . . . . . 297
Control Statements . . . . . . . Planning the Control Statement Order . ABEND Statement. . . . . . . . CALL Statement . . . . . . . . COMMENT Statement . . . . . . COMPARE Statement . . . . . . IGNORE Statement . . . . . . . OPTION Statement . . . . . . . PUNCH CTL Statement . . . . . . STATUS Statement . . . . . . . WTO Statement . . . . . . . . WTOR Statement . . . . . . . . JCL Requirements . . . . . . . . Execution of DFSDDLT0 in IMS Regions Explanation of DFSDDLT0 Return Codes DFSDDLT0 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 299 300 300 320 321 327 327 328 331 334 335 335 339 339 339
Part 2. Reference . . . . . . . . . 197

Chapter 10. Command Code Reference . . . . . . . . . . . . . 201
General Command Codes for DL/I Calls . DEDB Command Codes for DL/I . . . . . . . . 202 . 213
Chapter 11. DL/I Calls for Database Management . . . . . . . . . . . . 219

Database Management CIMS Call . . . . CLSE Call . . . . DEQ Call . . . . . DLET Call . . . . FLD Call . . . . . GN/GHN Call . . . GNP/GHNP Call . . GU/GHU Call . . . ISRT Call . . . . . OPEN Call . . . . POS Call . . . . . REPL Call . . . . RLSE Call . . . . Call Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 221 223 224 225 226 229 233 235 238 241 242 245 247
Chapter 15. Adapter for REXX . . . . 343

Sample Exit Routine (DFSREXXU) Addressing Other Environments . REXX Transaction Programs . . REXXTDLI Commands . . . . REXXTDLI Calls . . . . . . REXXIMS Extended Commands . Sample Execs Using REXXTDLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 344 345 349 349 352 364
Chapter 12. DL/I Calls for System Services . . . . . . . . . . . . . 249

System Service Call Summary . . . . APSB Call . . . . . . . . . . CHKP (Basic) Call . . . . . . . . CHKP (Symbolic) Call . . . . . . DPSB Call . . . . . . . . . . GMSG Call . . . . . . . . . . GSCD Call . . . . . . . . . . ICMD Call . . . . . . . . . . INIT Call . . . . . . . . . . . INQY Call . . . . . . . . . . LOG Call . . . . . . . . . . . PCB Call (CICS Online Programs Only) RCMD Call . . . . . . . . . . ROLB Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 252 253 254 255 256 258 259 261 266 276 277 278 280
Chapter 16. CICS-DL/I User Interface Block Return Codes . . . . . . . . 377

Not-Open Conditions. . . Invalid Request Conditions . . . . . . . . . . . . . . . . 378 . 378
Notices . . . . . . . . . . . . . . 379
Programming Interface Information . Trademarks . . . . . . . . . . . . . . . . . . 381 . 381
Bibliography . . . . . . . . . . . . 383
IMS Version 9 Library . . . Supplementary Publications . Publication Collections . . . Accessibility Titles Cited in This . . . . . . . . . Library . . . . . . . . . . . . . . . . 383 384 384 384
Index . . . . . . . . . . . . . . . 385
iv
Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. DL/I Program Elements. . . . . . . . . 6 Normal Relationship between Programs, PSBs, PCBs, DBDs, and Databases . . . . . . . 10 Relationship between Programs and Multiple PCBs (Concurrent Processing) . . . . . . 10 The Structure of a Call-Level CICS Online Program. . . . . . . . . . . . . . 11 Medical Hierarchy . . . . . . . . . . 13 Segment with a Noncontiguous Sequence Field 23 D Command Code Example . . . . . . . 27 Sample Assembler Language Program . . . 30 Sample Call-Level Assembler Language Program (CICS Online) . . . . . . . . 32 Sample C Language Program . . . . . . 34 Sample COBOL Program . . . . . . . . 37 Sample Call-Level OS/V COBOL program (CICS Online) . . . . . . . . . . . . 42 Sample Pascal Program . . . . . . . . 45 Sample PL/I Program . . . . . . . . . 47 Sample Call-Level PL/I Program (CICS Online) . . . . . . . . . . . . . . 51 Defining the UIB, PCB Address List, and the PCB Mask for VS COBOL II . . . . . . . 78 Defining the UIB, PCB Address List, and the PCB Mask for OS/VS COBOL . . . . . . 78 The COBOL COPY DLIUIB Copy Book 79 Defining the UIB, PCB Address List, and the PCB Mask for PL/I . . . . . . . . . . 80 Defining the UIB, PCB Address List, and the PCB Mask for Assembler Language . . . . 80 Example Code: * CONSTANT AREA . . . . 82 Qualified SSA without Command Codes 84 Current Position Hierarchy . . . . . . . 96 Example Code: Deleting Segment C11. . . . 97 Hierarchy after Deleting a Segment . . . . 98 Hierarchy after Deleting a Segment and Dependents . . . . . . . . . . . . 98 Hierarchy after Adding New Segments and Dependents . . . . . . . . . . . . 100 DL/I Positions . . . . . . . . . . . 101 Multiple Processing . . . . . . . . . 104 Multiple Positioning Hierarchy . . . . . 105 Single and Multiple Positioning Hierarchy 106 SETS and ROLS Calls Working Together 116 ODBA Two-Phase Sync Point Processing 127 DRA Component Structure with the ODBA Interface . . . . . . . . . . . . . 131 Example of Using the Dependent AND 151 Example of Using the Independent AND 151 Patient and Item Hierarchies . . . . . . 154 Concatenated Segment . . . . . . . . 154 //IMS DD Statement Example . . . . . . 168 Sample PCB Specifying View=MSDB 177 Processing a Long Chain of Segment Occurrences with Subset Pointers . . . . . 179 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. Examples of Setting Subset Pointers . . . . Additional Examples of Setting Subset Pointers . . . . . . . . . . . . . How Subset Pointers Divide a Chain into Subsets . . . . . . . . . . . . . U Command Code Example . . . . . . Processing for the Passbook Example Moving the Subset Pointer to the Next Segment after Your Current Position . . . . Retrieving the First Segment in a Chain of Segments . . . . . . . . . . . . . Unconditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . Conditionally Setting the Subset Pointer to Your Current Position . . . . . . . . . Hierarchic Sequence . . . . . . . . . Sample PL/I Program to retrieve database status values . . . . . . . . . . . . I/O Area for SNAP Operation Parameters Example JCL Code for DD Statement Definition . . . . . . . . . . . . . Example JCL Code for DFSDDLT0 in a BMP Using the Binder to Copy the Name IVPREXX . . . . . . . . . . . . . JCL Code Used to Run the IVPREXX Sample Exec . . . . . . . . . . . . . . IMS Adapter for REXX Logical Overview Diagram . . . . . . . . . . . . . Exec To Do Calculations . . . . . . . . PDF EDIT Session on the SAY Exec . . . . Example Output from the SAY Exec . . . . Example Output of PCBINFO Exec on a PSB without Database PCBs. . . . . . . . . Example Output of PCBINFO Exec on a PSB with a Database PCB. . . . . . . . . . PCBINFO Exec Listing . . . . . . . . Example Output of PARTNUM Exec Example Output of PARTNAME Exec PARTNUM Exec: Show Set of Parts Near a Specified Number . . . . . . . . . . PARTNAME Exec: Show Parts with Similar Names . . . . . . . . . . . . . . Output from = > DOCMD . . . . . . . Output from = > DOCMD /DIS NODE ALL;? Output from = > DOCMD /DIS NODE ALL;CID>0 . . . . . . . . . . . . Output from = > DOCMD /DIS NODE ALL;TYPE=SLU2 . . . . . . . . . . Output from = > DOCMD /DIS TRAN ALL;ENQCT>0 & RECTYPE='T02' . . . . Output from = > DOCMD /DIS LTERM ALL;ENQCT>0 . . . . . . . . . . . DOCMD Exec: Process an IMS Command 179 180 180 211 214 215 216 217 218 231 272 285 335 336 345 346 347 365 365 365 366 366 367 368 368 369 370 371 371 371 372 372 372 373
| |
| 75.
vi
Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. Licensed Program Full Names and Short Names x PATIENT Segment . . . . . . . . . . 14 ILLNESS Segment . . . . . . . . . . 14 TREATMNT Segment . . . . . . . . . 15 BILLING Segment . . . . . . . . . . 15 PAYMENT Segment . . . . . . . . . . 15 HOUSEHOLD Segment . . . . . . . . 15 Teller Segment in a Fixed Related MSDB 16 Branch Summary Segment in a Dynamic Related MSDB . . . . . . . . . . . 17 Account Segment in a Nonrelated MSDB 17 Qualified SSA Structure . . . . . . . . 21 Unqualified SSA with Command Code 27 Qualified SSA with Command Code . . . . 27 I/O PCB Mask . . . . . . . . . . . 67 DB PCB Mask. . . . . . . . . . . . 71 AIB Fields . . . . . . . . . . . . . 73 AIB Fields for Use of ODBA Applications 74 Relational Operators . . . . . . . . . 81 I/O PCB and Alternate PCB Information Summary . . . . . . . . . . . . . 90 Using LANG= Option in a Language Environment for PL/I Compatibility . . . . 92 Results of Single and Multiple Positioning with DL/I Calls. . . . . . . . . . . 106 Comparison of ROLB, ROLL, and ROLS 113 Example of Events in a Multithreading System . . . . . . . . . . . . . . 123 CCTL Single-Phase Sync Point Processing 126 CCTL Two-Phase Sync Point Processing 126 Information Provided for the Schedule Process: . . . . . . . . . . . . . 143 Information Provided at UOR Termination: 144 GSAM DB PCB Mask . . . . . . . . . 158 Format of the RSA . . . . . . . . . . 160 Summary of GSAM Calls . . . . . . . 163 Summary of Fast Path Database Calls 170 Subset Pointer Command Codes and Calls 171 FSA Structure . . . . . . . . . . . 172 Unqualified SSA with Subset Pointer Command Code . . . . . . . . . . 181 Qualified SSA with Subset Pointer Command Code . . . . . . . . . . . . . . 181 Qualified POS Call: Keywords and Map of I/O Area Returned. . . . . . . . . . 184 DEDB DL/I Calls . . . . . . . . . . 188 Field initialization for DEDB DL/I calls 189 Fields initialized for specific DEDB DL/I calls 190 Fields updated by IMS for all DL/I call types 190 Fields updated by specific DL/I calls 190 Status codes for specific DEDB DL/I calls 194 Summary of Command Codes . . . . . . 201 Command Codes and Related Calls . . . . 202 Command Codes for DL/I Calls . . . . . 202 Summary of DB Calls . . . . . . . . . 220 CIMS CONNECT parameter list format 221
| 48.
49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62.
63.
64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. 75. 76. 77. 78. 79. 80. 81. 82. 83. 84. 85. 86. 87. 88.
| | | | | |
37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47.
CIMS CONNECT table entry format . . . . Unqualified POS Call: Keywords and Map of the I/O Area Return Output . . . . . . Summary of System Service Calls . . . . . GMSG Support by Application Region Type ICMD Support by Application Region Type INIT DBQUERY: Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI . . . . . INIT DBQUERY: I/O Area Example for PLITDLI . . . . . . . . . . . . . INIT I/O Area Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI . . . . . INIT I/O Area Examples for PLITDLI INIT I/O Area Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI . . . . . INIT I/O Area Examples for PLITDLI INQY ENVIRON Data Output . . . . . . INQY MSGINFO data output . . . . . . Subfunction, PCB, and I/O Area Combinations for the INQY Call . . . . . Log Record Formats for COBOL, C, Assembler, Pascal, and PL/I Programs for the AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI Interfaces . . . . . Log Record Formats for COBOL, C, Assembler, Pascal, and PL/I Programs for the PLITDLI Interface . . . . . . . . . . RCMD Support by Application Region Type SNAP Operation Parameters . . . . . . Call Relationship to PCBs . . . . . . . Summary of DFSDDLT0 Control Statements ABEND Statement . . . . . . . . . . CALL FUNCTION Statement . . . . . . CALL DATA Statement . . . . . . . . OPTION DATA Statement . . . . . . . FEEDBACK DATA Statement . . . . . . DL/I Call Functions . . . . . . . . . CALL FUNCTION Statement (Column-Specific SSAs) . . . . . . . . CALL FUNCTION Statement with DFSDDLT0 Call Functions . . . . . . . COMMENT Statement . . . . . . . . COMPARE DATA Statement . . . . . . COMPARE AIB Statement . . . . . . . COMPARE PCB Statement . . . . . . . IGNORE Statement . . . . . . . . . OPTION Statement . . . . . . . . . PUNCH CTL Statement . . . . . . . . STATUS Statement . . . . . . . . . . WTO Statement . . . . . . . . . . . WTOR Statement . . . . . . . . . . IMS Adapter for REXX Parameter Types and Definitions . . . . . . . . . . . . REXXIMS Extended Commands . . . . . Return Codes in UIBFCTR . . . . . . .
222 243 250 258 260 262 262 263 263 264 264 268 270 275
276
276 279 285 295 298 300 300 303 305 305 306 318 319 321 322 323 324 327 328 329 331 334 335 351 353 377
vii
89.
Return Codes in UIBDLTR if UIBFCTR='0C' (NOTOPEN) . . . . . . . . . . . . 377
90.
Return Codes in UIBDLTR if UIBFCTR='08' (INVREQ). . . . . . . . . . . .
. 377
viii
About This Book

| | | This information is available as part of the Information Management Software for z/OS Solutions Information Center at http://publib.boulder.ibm.com/infocenter/ imzic. A PDF version of this information is available in the information center. This book is a guide to application programming in an IMS Database Manager (IMS DB) environment. It covers basic information on coding DL/I calls for DB programs. The book is designed to provide guidance for application programmers who use the IMS DB environment to create and run application programs. Portions of this book are for programmers who use IMS from a Customer Information Control System (CICS) environment. This book also contains information on the DBCTL environment. DBCTL is generated by IMS DB, contains no data communication components, and is designed to function as a database manager for non-IMS transaction management systems. With IMS Version 9, you can reorganize HALDB partitions online, either by using the integrated HALDB Online Reorganization function or by using an external product. In this information, the term HALDB Online Reorganization refers to the integrated HALDB Online Reorganization function that is part of IMS Version 9, unless otherwise indicated.
Summary of Contents
This book has two parts: v Part 1, Writing Application Programs, on page 1 provides basic information on coding DL/I calls for IMS DB programs, information that you can use to interactively develop REXX EXECs under TSO/E and execute them in IMS MPPs, BMPs, IFPs, or batch regions. v Part 2, Reference, on page 197 provides additional information that you need to write and test your application programs.
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. Before using this book, you should understand the concepts of application design presented in IMS Version 9: Application Programming: Design Guide, which assumes you understand basic IMS concepts and the various environments. This book is an extension to IMS Version 9: Application Programming: Design Guide. The IMS concepts explained in this manual are limited to those concepts that are pertinent to developing and coding application programs. You should also know how to use assembler language, C language, COBOL, Pascal, or PL/I. CICS programs can be written in assembler language, C language, COBOL, PL/I, and C++.
ix
IBM Product Names Used in This Information

In this information, the licensed programs shown in Table 1 are referred to by their short names.
Table 1. Licensed Program Full Names and Short Names Licensed program full name IBM Application Recovery Tool for IMS and DB2 IBM CICS Transaction Server for OS/390 IBM CICS Transaction Server for z/OS IBM DB2 Universal Database
Licensed program short name Application Recovery Tool CICS CICS DB2 Universal Database DB2 UDB for z/OS Enterprise COBOL Enterprise COBOL Enterprise PL/I High Level Assembler IMS Advanced ACB Generator IMS Batch Backout Manager IMS Batch Terminal Simulator IMS Buffer Pool Analyzer IMS Command Control Facility IMS Connect IMS Connector for Java IMS Database Control Suite IMS Database Recovery Facility IMS Database Repair Facility IMS DataPropagator IMS DEDB Fast Recovery IMS ETO Support IMS Fast Path Basic Tools IMS Fast Path Online Tools IMS Hardware Data Compression-Extended IBM IMS HALDB Conversion Aid IMS High Performance Change Accumulation Utility IMS HP Load IMS HP Pointer Checker
IBM DB2 Universal Database for z/OS IBM Enterprise COBOL for z/OS IBM Enterprise COBOL for z/OS and OS/390 IBM Enterprise PL/I for z/OS and OS/390 IBM High Level Assembler for MVS & VM & VSE IBM IMS Advanced ACB Generator IBM IMS Batch Backout Manager IBM IMS Batch Terminal Simulator IBM IMS Buffer Pool Analyzer IBM IMS Command Control Facility for z/OS IBM IMS Connect for z/OS IBM IMS Connector for Java IBM IMS Database Control Suite IBM IMS Database Recovery Facility for z/OS IBM IMS Database Repair Facility IBM IMS DataPropagator for z/OS IBM IMS DEDB Fast Recovery IBM IMS Extended Terminal Option Support IBM IMS Fast Path Basic Tools IBM IMS Fast Path Online Tools IBM IMS Hardware Data Compression-Extended IBM IMS High Availability Large Database (HALDB) Conversion Aid for z/OS IBM IMS High Performance Change Accumulation Utility for z/OS IBM IMS High Performance Load for z/OS IBM IMS High Performance Pointer Checker for OS/390
Table 1. Licensed Program Full Names and Short Names (continued) Licensed program full name Licensed program short name
IBM IMS High Performance Prefix Resolution IMS HP Prefix Resolution for z/OS IBM Tivoli NetView for z/OS IBM WebSphere Application Server for z/OS and OS/390 IBM WebSphere MQ for z/OS IBM WebSphere Studio Application Developer Integration Edition IBM z/OS
Tivoli NetView for z/OS WebSphere Application Server for z/OS WebSphere MQ WebSphere Studio z/OS
Additionally, this information might contain references to the following IBM product names: v "IBM C/C++ for MVS" or "IBM C/C++ for MVS/ESA" is referred to as either "C/MVS" or "C++/MVS." v "IBM CICS for MVS" is referred to as "CICS." v "IBM DataAtlas for OS/2" is referred to as "DataAtlas." v "IBM Language Environment for MVS & VM" or "IBM z/OS Language Environment" is referred to as "Language Environment." v "IBM PL/I for MVS & VM" or "IBM PL/I for OS/390 & VM" is referred to as "PL/I."
How to Read Syntax Diagrams

The following rules apply to the syntax diagrams that are used in this information: v Read the syntax diagrams from left to right, from top to bottom, following the path of the line. The following conventions are used: The >>--- symbol indicates the beginning of a syntax diagram. The ---> symbol indicates that the syntax diagram is continued on the next line. The >--- symbol indicates that a syntax diagram is continued from the previous line. The --->< symbol indicates the end of a syntax diagram. v Required items appear on the horizontal line (the main path).
required_item
v 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 syntax element and is used only for readability.
optional_item required_item
About This Book
xi
v 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
If one of the items is the default, it appears above the main path, and the remaining choices are shown below.
default_choice required_item optional_choice optional_choice
v An arrow returning to the left, above the main line, indicates an item that 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 repeat the items in the stack. v Sometimes a diagram must be split into fragments. The syntax fragment is shown separately from the main syntax diagram, but the contents of the fragment should be read as if they are on the main path of the diagram.
required_item fragment-name
fragment-name:
required_item optional_item
v In IMS, a b symbol indicates one blank position.
xii
v Keywords, and their minimum abbreviations if applicable, appear in uppercase. They must be spelled exactly as shown. Variables appear in all lowercase italic letters (for example, column-name). They represent user-supplied names or values. v Separate keywords and parameters by at least one space if no intervening punctuation is shown in the diagram. v Enter punctuation marks, parentheses, arithmetic operators, and other symbols, exactly as shown in the diagram. v Footnotes are shown by a number in parentheses, for example (1).
Accessibility Features for IMS Version 9

Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use information technology products successfully.
Accessibility Features
The following list includes the major accessibility features in z/OS products, including IMS Version 9. These features support: v Keyboard-only operation. v Interfaces that are commonly used by screen readers and screen magnifiers. v Customization of display attributes such as color, contrast, and font size. | | The information center is accessibility-enabled for the IBM Home Page Reader. You can operate all features by using the keyboard instead of the mouse.
Keyboard Navigation
You can access IMS Version 9 ISPF panel functions by using a keyboard or keyboard shortcut keys. For information about navigating the IMS Version 9 ISPF panels using TSO/E or ISPF, refer to the z/OS TSO/E Primer, the z/OS TSO/E Users Guide, and the z/OS ISPF Users Guide. These guides describe how to navigate each interface, including the use of keyboard shortcuts or function keys (PF keys). Each guide includes the default settings for the PF keys and explains how to modify their functions.
Related Accessibility Information

| Online documentation for IMS Version 9 is available in the information center.
IBM and Accessibility

See the IBM Accessibility Center at www.ibm.com/able for more information about the commitment that IBM has to accessibility.
How to Send Your Comments

| | | | Your feedback helps us provide the most accurate and highest quality information. The documentation for this version is provided as-is and is no longer being updated. However, we welcome your feedback and will review your comments to see if we can use them to improve versions of the product that are still in service. Send your comments by email to imspubs@us.ibm.com.
About This Book
xiii
xiv
Summary of Changes
| |
Changes to the Current Edition of This Book for IMS Version 9

This edition includes technical and editorial changes.
Changes to This Book for IMS Version 9

This book contains new technical information for IMS Version 9, as well as editorial changes.
Technical Changes
New information on the following enhancements is included: v The sample PL/I code in Coding a Batch Program in PL/I on page 46 has been modified. v The sample CICS PL/I code in Coding a CICS Online Program in PL/I on page 50 has been modified. v Coding a batch program in COBOL includes new information . For more information, see Coding a Batch Program in COBOL on page 36. v Issuing a POS call includes new information. For more information, see POS Call on page 242. v AIB has been added to Table 66 on page 295. For more information, see Chapter 13, Relationship Between Calls and AIB and PCBs, on page 295. v Issuing a INQY call includes new information. For more information, see INQY Call on page 266.
Editorial Changes
The following organizational changes have been made to this book: v Segment Search Arguments (SSAs) on page 20 has been moved from Chapter 1, How Application Programs Work with Database Manager, on page 5 to Chapter 2, Writing Your Application Programs, on page 19. v Multiple Qualification Statements on page 24 has been added to Segment Search Arguments (SSAs) on page 20. For detailed information about technical enhancements for IMS Version 9, see the IMS Version 9: Release Planning Guide.
Library Changes for IMS Version 9

Changes to the IMS Library for IMS Version 9 include the addition of one title, a change of one title, organizational changes, and a major terminology change. Changes are indicated by a vertical bar (|) to the left of the changed text. The IMS Version 9 information is now available in the Information Management Software for z/OS Solutions Information Center , which is available at http://publib.boulder.ibm.com/infocenter/imzic. The Information Management Software for z/OS Solutions Information Center provides a graphical user interface for centralized access to the product information for IMS, IMS Tools, DB2 Universal Database (UDB) for z/OS, DB2 Tools, and DB2 Query Management Facility (QMF).
xv
| | | |
There are known limitations with BookManager output. If you encounter problems in the BookManager information with Web addresses, syntax diagrams, wide examples, or tables, refer to the information in the information center or in a PDF book.
New and Revised Titles

The following list details the major changes to the IMS Version 9 library: v IMS Version 9: IMS Connect Guide and Reference The library includes new information: IMS Version 9: IMS Connect Guide and Reference. This information is available in softcopy format only, as part of the Information Management Software for z/OS Solutions Information Center , and in PDF and BookManager formats. IMS Version 9 provides an integrated IMS Connect function, which offers a functional replacement for the IMS Connect tool (program number 5655-K52). In this information, the term IMS Connect refers to the integrated IMS Connect function that is part of IMS Version 9, unless otherwise indicated. v The information formerly titled IMS Version 8: IMS Java Users Guide is now titled IMS Version 9: IMS Java Guide and Reference. This information is available in softcopy format only, as part of the Information Management Software for z/OS Solutions Information Center , and in PDF and BookManager formats. v To complement the IMS Version 9 library, a retail book, An Introduction to IMS by Dean H. Meltz, Rick Long, Mark Harrington, Robert Hain, and Geoff Nicholls (ISBN # 0-13-185671-5), is available from IBM Press. Go to the IMS Web site at www.ibm.com/ims for details.
Organizational Changes
Organization changes to the IMS Version 9 library include changes to: v IMS Version 9: Customization Guide v IMS Version 9: IMS Connect Guide and Reference v IMS Version 9: IMS Java Guide and Reference v IMS Version 9: Messages and Codes, Volume 1 v IMS Version 9: Utilities Reference: System | | | | | | A new appendix has been added to the IMS Version 9: Customization Guide that describes the contents of the ADFSSMPL (also known as SDFSSMPL) data set. The IMS Connect messages that were in IMS Version 9: IMS Connect Guide and Reference have moved to IMS Version 9: Messages and Codes, Volume 1. The IMS Connect commands that were in IMS Version 9: IMS Connect Guide and Reference have moved to IMS Version 9: Command Reference. The chapter titled "DLIModel Utility" has moved from IMS Version 9: IMS Java Guide and Reference to IMS Version 9: Utilities Reference: System. The DLIModel utility messages that were in IMS Version 9: IMS Java Guide and Reference have moved to IMS Version 9: Messages and Codes, Volume 1. | | | | To ease the transition of your security support from the Security Maintenance Utility (SMU) to RACF, new SMU to RACF conversion utilities have been introduced. These utilities are documented in a new part in the IMS Version 9: Utilities Reference: System.
xvi
Terminology Changes
IMS Version 9 introduces new terminology for IMS commands: type-1 command A command, generally preceded by a leading slash character, that can be entered from any valid IMS command source. In IMS Version 8, these commands were called classic commands. type-2 command A command that is entered only through the OM API. Type-2 commands are more flexible than type-2 commands and can have a broader scope. In IMS Version 8, these commands were called IMSplex commands or enhanced commands.
Summary of Changes
xvii
xviii
Part 1. Writing Application Programs

| |
Chapter 1. How Application Programs Work with Database Manager . . . . . . . . . . . IMS Environments . . . . . . . . . . . DL/I and Your Application Program . . . . . DL/I Calls . . . . . . . . . . . . . . DB Call Functions . . . . . . . . . . System Service Call Functions . . . . . . DL/I Codes . . . . . . . . . . . . . Status, Return, and Reason Codes . . . . . Exceptional Condition Status Codes . . . . High Availability Large Databases (HALDBs) . Error Routines . . . . . . . . . . . . Database Descriptions (DBDs) and Program Specification Blocks (PSBs). . . . . . . . . DL/I for CICS Online Users . . . . . . . . DL/I using the ODBA Interface . . . . . . Database Hierarchy Examples . . . . . . . Medical Hierarchy Example . . . . . . . Bank Account Hierarchy Example . . . . . . . . . . . . . . . . 5 5 7 7 7 7 8 8 9 9 9 Format . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Example of a DL/I Call Format. . . . . . Pascal Application Programming . . . . . . Format . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Example of a DL/I Call Format. . . . . . Application Programming for PL/I . . . . . Format . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . Example of a DL/I Call Format. . . . . . Specifying the I/O PCB Mask . . . . . . . Specifying the DB PCB Mask . . . . . . . Specifying the AIB Mask . . . . . . . . . Specifying the AIB Mask for ODBA Applications . Specifying the UIB (CICS Online Programs Only). Specifying the I/O Areas . . . . . . . . . Formatting Segment Search Arguments (SSAs). . SSA Coding Rules . . . . . . . . . . SSA Coding Formats . . . . . . . . . GSAM Databases . . . . . . . . . . . The AIBTDLI Interface. . . . . . . . . . Language Specific Entry Points . . . . . . . Assembler Language Entry Point . . . . . C Language Entry Point . . . . . . . . COBOL Entry Point . . . . . . . . . Pascal Entry Point . . . . . . . . . . PL/I Entry Point . . . . . . . . . . CEETDLI, AIBTDLI, and AERTDLI Interface Considerations . . . . . . . . . . . Program Communication Block (PCB) Lists. . . PCB List Format . . . . . . . . . . . Format of a GPSB PCB List . . . . . . . PCB Summary . . . . . . . . . . . The AERTLDI interface . . . . . . . . . Language Environments . . . . . . . . . The CEETDLI interface to IMS . . . . . . Specifying LANG= Option for PL/I Compatibility. . . . . . . . . . . . Special DL/I Situations . . . . . . . . . Application Program Scheduling against HALDBs . . . . . . . . . . . . . Mixed-Language Programming . . . . . . Language Environment Routine Retention . . Extended Addressing Capabilities of z/OS . . Preloaded Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 60 62 62 62 63 64 64 64 65 67 67 70 73 74 77 80 80 81 82 85 85 86 87 87 88 88 88 88 89 89 89 90 91 91 92
. . . . .
. 9 10 12 13 13 15 19 19 20 21 21 23 24 26 28 29 29 29 32 34 36 39 44 46 50
Chapter 2. Writing Your Application Programs . . Programming Guidelines . . . . . . . . . . Segment Search Arguments (SSAs) . . . . . . Unqualified SSAs . . . . . . . . . . . Qualified SSAs . . . . . . . . . . . . SSA Guidelines . . . . . . . . . . . . Multiple Qualification Statements . . . . . . SSAs and Command Codes . . . . . . . . Considerations for Coding DL/I Calls and Data Areas . . . . . . . . . . . . . . . . Preparing to Run Your CICS DL/I Call Program . . Examples of How to Code DL/I Calls and Data Areas . . . . . . . . . . . . . . . . Coding a Batch Program in Assembler Language Coding a CICS Online Program in Assembler Language . . . . . . . . . . . . . . Coding a Batch Program in C Language . . . . Coding a Batch Program in COBOL . . . . . Coding a CICS Online Program in COBOL . . . Coding a Batch Program in Pascal . . . . . . Coding a Batch Program in PL/I . . . . . . Coding a CICS Online Program in PL/I . . . . Chapter 3. Defining Application Program Elements . . . . . . . . . . . . . Formatting DL/I Calls for Language Interfaces Assembler Language Application Programming Format . . . . . . . . . . . . . Parameters . . . . . . . . . . . Example of a DL/I Call Format. . . . . C Language Application Programming . . . Format . . . . . . . . . . . . . Parameters . . . . . . . . . . . I/O Area . . . . . . . . . . . . Example of a DL/I Call Format. . . . . COBOL Application Programming. . . . .
. 92 . 93 . . . . . 93 93 94 94 94
. . 53 . . 53 . . 54 . . 54 . . 55 . . 56 . . 56 . . 56 . . 57 . . 59 . . 59 . . 59
Chapter 4. Current Position in the Database After Each Call . . . . . . . . . . . . . . . 95 Current Position after Successful Calls . . . . . 95 Position after Retrieval Calls. . . . . . . . 97 Position after DLET. . . . . . . . . . . 97 Position after REPL . . . . . . . . . . . 99 Position after ISRT . . . . . . . . . . . 99 Current Position after Unsuccessful Calls . . . . 100
Position after an Unsuccessful DLET or REPL Call . . . . . . . . . . . . . . . Position after an Unsuccessful Retrieval or ISRT Call . . . . . . . . . . . . . . . Multiple Processing . . . . . . . . . . . Multiple Positioning . . . . . . . . . . Advantages of Using Multiple Positioning. . . Multiple DB PCBs . . . . . . . . . . . Chapter 5. Recovering Databases and Maintaining Database Integrity . . . . . . Issuing Checkpoints . . . . . . . . . . Restarting Your Program From the Latest Checkpoint . . . . . . . . . . . . . Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) . . . . . . . . Backing Out to a Prior Commit Point: ROLL, ROLB, and ROLS . . . . . . . . . . Backing Out to an Intermediate Backout Point: SETS, SETU, and ROLS . . . . . . . . Reserving Segments for the Exclusive Use of Your Program . . . . . . . . . . . . . .
100 101 104 104 107 109
Status Codes for Secondary Indexes . . . Processing Segments in Logical Relationships How Logical Relationships Affect Your Programming . . . . . . . . . . Status Codes for Logical Relationships . .
. . . .
. 152 . 152 . 154 . 155 157 157 157 159 160 161 161 162 162 163 163 164 165 165 166 166 167 167 167 169 169 170 170 171 171 176 177 177 178 178 178 183 185 186 186 187 187 187 187 188 188 191 191 191 192 192 193
. 111 . 111 . 111 . 112 . 112 . 116 . 118
Chapter 6. The Database Resource Adapter (DRA). . . . . . . . . . . . . . . . Thread Concepts . . . . . . . . . . . . Processing Threads . . . . . . . . . . Processing Multiple Threads . . . . . . . CCTL Multithread Example . . . . . . . Sync Points . . . . . . . . . . . . . . The Two-Phase Commit Protocol . . . . . . In-Doubt State During Two-Phase Sync. . . . DRA Startup Table . . . . . . . . . . . Sample DFSPZP00 Source Code . . . . . . DFSPRP Macro Keywords . . . . . . . . Enabling the DRA for a CCTL . . . . . . . . Enabling the DRA for the ODBA Interface . . . . Processing CCTL DRA Requests . . . . . . . Processing ODBA Calls . . . . . . . . . . CCTL-Initiated DRA Function Requests . . . . INIT Request . . . . . . . . . . . . RESYNC Request . . . . . . . . . . . TERM Request . . . . . . . . . . . . Thread Function Requests . . . . . . . . PAPL Mapping Format . . . . . . . . . . Terminating the DRA. . . . . . . . . . . Designing the CCTL Recovery Process . . . . . CCTL Performance: Monitoring DRA Thread TCBs DRA Thread Statistics . . . . . . . . . DRA Statistics . . . . . . . . . . . . Tracing . . . . . . . . . . . . . . Sending Commands to IMS DB . . . . . . Problem Diagnosis . . . . . . . . . .
| | | | | |
121 121 121 122 122 124 125 127 128 128 128 129 130 131 132 132 132 134 135 135 141 141 142 143 143 145 146 146 146
Chapter 8. Processing GSAM Databases . . . Accessing GSAM Databases . . . . . . . . PCB Masks for GSAM Databases . . . . . . Retrieving and Inserting GSAM Records . . . Resetting the Position in a GSAM Database . . Explicit Open and Close Calls to GSAM . . . GSAM Record Formats . . . . . . . . . . GSAM I/O Areas . . . . . . . . . . . . GSAM Status Codes . . . . . . . . . . . Symbolic CHKP and XRST with GSAM . . . . GSAM Coding Considerations. . . . . . . . Origin of GSAM Data Set Characteristics . . . . DD Statement DISP Parameter for GSAM Data Sets . . . . . . . . . . . . . . . Extended Checkpoint Restart for GSAM Data Sets . . . . . . . . . . . . . . . Copying GSAM Data Sets Between Checkpoint and Restart . . . . . . . . . . . . . Converting Data Sets From Non-Striped Data Sets to Striped Data Sets. . . . . . . . . Concatenated Data Sets Used by GSAM . . . Suggested Method for Specifying GSAM Data Set Attributes . . . . . . . . . . . . DLI, DBB, and BMP Region Types and GSAM Chapter 9. Processing Fast Path Databases . . Main Storage Databases (MSDBs). . . . . . . Data Entry Databases (DEDBs) . . . . . . . Fast Path Database Calls . . . . . . . . . Processing MSDBs and DEDBs . . . . . . . Updating Segments: REPL, DLET, ISRT, and FLD . . . . . . . . . . . . . . . Commit-Point Processing in MSDBs and DEDBs VSO Considerations . . . . . . . . . . Data Locking for MSDBs and DEDBs . . . . Restrictions on Using Calls for MSDBs . . . . . Processing DEDBs (IMS and CICS with DBCTL) Processing DEDBs with Subset Pointers . . . Retrieving Location with the POS Call (for DEDB Only) . . . . . . . . . . . . . Commit-Point Processing in a DEDB . . . . P Processing Option . . . . . . . . . . H Processing Option . . . . . . . . . . Data Locking . . . . . . . . . . . . Calls with Dependent Segments for DEDBs . . . Direct Dependent Segments . . . . . . . Sequential Dependent Segments . . . . . . DEDB DL/I calls to extract DEDB information . . IOAI structure . . . . . . . . . . . . AL_LEN Call . . . . . . . . . . . . DI_LEN Call . . . . . . . . . . . . DS_LEN Call . . . . . . . . . . . . AREALIST Call. . . . . . . . . . . . DEDBINFO Call . . . . . . . . . . . DEDSTR Call . . . . . . . . . . . .
Chapter 7. Secondary Indexing and Logical Relationships . . . . . . . . . . . . . 149 How Secondary Indexing Affects Your Program 149 SSAs with Secondary Indexes . . . . . . . 149 Multiple Qualification Statements with Secondary Indexes. . . . . . . . . . . 150 DL/I Returns with Secondary Indexes . . . . 152
| | | | | | | |
Fast Path Coding Considerations .
. 195
Part 1. Writing Application Programs
Chapter 1. How Application Programs Work with Database Manager

Application programs use Data Language I (DL/I) to communicate with the IMS. This chapter gives an overview of the application programming techniques and the application programming interface for IMS Database Manager (IMS DB). The following topics provide additional information: v IMS Environments v DL/I and Your Application Program on page 7 v DL/I Calls on page 7 v DL/I Codes on page 8 v Database Descriptions (DBDs) and Program Specification Blocks (PSBs) on page 9 v DL/I for CICS Online Users on page 10 v DL/I using the ODBA Interface on page 12 v Database Hierarchy Examples on page 13 Related Reading: v If your installation uses the IMS Transaction Manager (IMS TM), see IMS Version 9: Application Programming: Transaction Manager for information on transaction management functions. v Information on DL/I EXEC commands is in the IMS Version 9: Application Programming: EXEC DLI Commands for CICS and IMS.
| | |
IMS Environments
| | | | Your application program can execute in different IMS environments. The three online environments are DB/DC, DBCTL, and DCCTL. The two batch environments are DB batch and TM batch. Related Reading: For information on these environments, see IMS Version 9: Administration Guide: System. The information in this section applies to all application programs that run in IMS. The main elements in an IMS application program are: v Program entry v Program communication block (PCB) or application interface block (AIB) definition v I/O (input/output) area definition v DL/I calls v Program termination Figure 1 on page 6 shows how these elements relate to each other. The numbers on the right in Figure 1 on page 6 refer to the notes that follow.
Figure 1. DL/I Program Elements
Notes for Figure 1: 1. Program entry. IMS passes control to the application program with a list of associated PCBs. 2. PCB or AIB. IMS describes the results of each DL/I call using the AIBTDLI interface in the application interface block (AIB) and, when applicable, the program communication block (PCB). To find the results of a DL/I call, your program must use the PCB that is referenced in the call. To find the results of the call using the AIBTDLI interface, your program must use the AIB. Your application program can use the PCB address that is returned in the AIB to find the results of the call. To use the PCB, the program defines a mask of the PCB and can then reference the PCB after each call to determine the success or failure of the call. An application program cannot change the fields in a PCB; it can only check the PCB to determine what happened when the call was completed. 3. I/O area. IMS passes segments to and from the program in the program's I/O area. 4. DL/I calls. The program issues DL/I calls to perform the requested function. 5. Program termination. The program returns control to IMS DB when it has finished processing. In a batch program, your program can set the return code and pass it to the next step in the job. | | | | | Recommendation: If your program does not use the return code in this way, set the return code to 0 as a programming convention. Your program can use the return code for this same purpose in Batch Message Processing (BMP) regions. Message Processing Programs (MPPs) cannot pass return codes.
DL/I and Your Application Program

When an application program call is issued to IMS, control passes to IMS from the application program. Standard subroutine linkage and parameter lists link IMS to your application program. After control is passed, IMS examines the input parameters, which perform the request functions.
DL/I Calls
A DL/I call consists of a call statement and a list of parameters. The parameters provide information that IMS needs to execute the call. This information consists of the call function, the name of the data structure that IMS uses for the call, the data area in the program into which IMS returns data, and any condition that the retrieved data must meet. You can issue calls to perform database management calls (DB calls) and to obtain IMS DB system service (system service calls).
DB Call Functions
The DL/I calls for database management are: CLSE DEQ DLET FLD GHN GHNP GHU GN GNP GU ISRT OPEN POS REPL GSAM Close Dequeue Delete Field Get Hold Next Get Hold Next in Parent Get Hold Unique Get Next Get Next in Parent Get Unique Insert GSAM Open Position Replace
Related Reading: The DL/I calls are described in detail in Chapter 11, DL/I Calls for Database Management, on page 219.
System Service Call Functions

The DL/I calls for system services are: APSB CHKP CHKP CIMS DPSB Allocate PSB Basic Checkpoint Symbolic Checkpoint ODBA Function Deallocate PSB
DL/I Calls
GMSG GSCD ICMD INIT INQY LOG PCB RCMD ROLB ROLL ROLS SETS SETU SNAP STAT SYNC TERM XRST Get Message Get Address of System Contents Directory Issue Command Initialize Inquiry Log Specify and Schedule a PCB Retrieve Command Roll Back Roll Roll Back to SETS Set a Backout Point SET Unconditional Collects diagnostic information Statistics Synchronization Terminate Extended Restart
Related Reading: The DL/I calls for system services are described in detail in Chapter 12, DL/I Calls for System Services, on page 249. |
DL/I Codes
This section contains information about the different DL/I codes that you will encounter when working with IMS Database Manager Application Programs.
Status, Return, and Reason Codes

To give information about the results of each call, IMS places a two-character status code in the PCB after each IMS call your program issues. Your program should check the status code after every IMS call. If it does not check the status code, the program might continue processing even though the previous call caused an error. The status codes your program should test for are those that indicate exceptional but valid conditions. IMS Version 9: Messages and Codes, Volume 1 lists the status codes that may be returned by each call type and indicates the level of success for each call. Your program should check for status codes which indicate the call was successful, such as blanks. If IMS returns a status code that you did not expect, your program should branch to an error routine. Information for your calls is supplied in status codes that are returned in the PCB, return and reason codes that are returned in the AIB, or both.
DL/I Codes
Exceptional Condition Status Codes

Some status codes do not mean that your call was successful or unsuccessful; they just give information about the results of the call. Your program uses this information to determine what to do next. The meaning of these status codes depend on the call. In a typical program, status codes that you should test for apply to the get calls. Some status codes indicate exceptional conditions for other calls, and you should provide routines other than error routines for these situations. For example, AH means that a required segment search argument (SSA) is missing, and AT means that the user I/O area is too long.
High Availability Large Databases (HALDBs)

You need to be aware that the feedback on data availability at PSB schedule time shows the availability of only the High Availability Large Database (HALDB) master, not of the HALDB partitions. However, the error settings for data unavailability of a HALDB partition are the same as those of a non-HALDB database, namely status code 'BA' or pseudo abend U3303. Also note that logical child segments cannot be loaded into a HALDB PHDAM or PHIDAM database. Logical child segments must be inserted later in an update run. Any attempt to load a logical child segment in either a PHDAM or PHIDAM database results in status code LF.
Error Routines
If your program detects an error after checking for blanks and exceptional conditions in the status code, it should branch to an error routine and print as much information as possible about the error before terminating. Determining which call was being executed when the error occurred, what parameters were on the IMS call, and the contents of the PCB will be helpful in understanding the error. Print the status code to help with problem determination. Two kinds of errors can occur in your program: programming errors and system or I/O errors. Programming errors, are usually your responsibility to find and fix. These errors are caused by things like an invalid parameter, an invalid call, or an I/O area that is too long. System or I/O errors are usually resolved by the system programmer or the equivalent specialist at your installation. Because every application program should have an error routine, and because each installation has its own ways of finding and debugging program errors, you probably have your own standard error routines.
Database Descriptions (DBDs) and Program Specification Blocks (PSBs)

Application programs can communicate with databases without being aware of the physical location of the data they possess. To do this, database descriptors (DBDs) and program specification blocks (PSBs) are used. A DBD describes the content and hierarchic structure of the physical or logical database. DBDs also supply information to IMS to help in locating segments. A PSB specifies the database segments an application program can access and the functions it can perform on the data, such as read only, update, or delete. Because
High Availability Large Database

an application program can access multiple databases, PSBs are composed of one or more program control blocks (PCBs). The PSB describes the way a database is viewed by your application program. Figure 2 shows the normal relationship between application programs, PSBs, PCBs, DBDs, and databases.
Figure 2. Normal Relationship between Programs, PSBs, PCBs, DBDs, and Databases
Figure 3 shows concurrent processing, which uses multiple PCBs for the same database.
Figure 3. Relationship between Programs and Multiple PCBs (Concurrent Processing)
DL/I for CICS Online Users

This topic applies to call-level CICS programs that use Database Control (DBCTL). DBCTL provides a database subsystem that runs in its own address space and gives one or more CICS systems access to IMS DL/I full-function databases and data entry databases (DEDBs). Figure 4 on page 11 shows the structure of a call-level CICS online program. See Figure 4 on page 11 notes for a description of each program element depicted in the figure.
10
Figure 4. The Structure of a Call-Level CICS Online Program
Notes to Figure 4: 1. I/O area. IMS passes segments to and from the program in the program's I/O area. 2. PCB. IMS describes the results of each DL/I call in the database PCB mask. | | | | | | | | | | 3. One of the following: v Application interface block (AIB). If you chose to use the AIB, the AIB provides the program with addresses of the PCBs and return codes from the CICS-DL/I interface. v User interface block (UIB). If you chose not to use AIB, the UIB provides the program with addresses of the PCBs and return codes from the CICS-DL/I interface. The horizontal line between number 3 (UIB) and number 4 (Program entry) in Figure 4, represents the end of the declarations section and the start of the executable code section of the program.
11

4. Program entry. CICS passes control to the application program during program entry. Do not use an ENTRY statement as you would in a batch program. | | | | | | | | | | 5. Schedule the PSB. This identifies the PSB your program is to use and passes the address of the AIB or UIB to your program. 6. Issue DL/I calls. Issue DL/I calls to read and update the database. 7. One of the following: v Check the status code in the AIB. If you chose to use the AIB, you should check the return code after issuing any DL/I call for database processing. Do this before checking the status code in the PCB. v Check the return code in the UIB. If you chose not to use the AIB, you should check the return code after issuing any DL/I call for database processing, including the PCB or TERM call. Do this before checking the status code in the PCB. 8. Check the status code in the PCB. You should check the status code after issuing any DL/I call for database processing. The code gives you the results of your DL/I call. 9. Terminate the PSB. This terminates the PSB and commits database changes. PSB termination is optional, and if it is not done, the PSB is released when your program returns control to CICS. 10. Return to CICS. This returns control to either CICS or the linking program. If control is returned to CICS, database changes are committed, and the PSB is terminated.
DL/I using the ODBA Interface

This section applies to z/OS application programs that use database resources that are managed by IMS DB. Open Database Access (ODBA) is an interface that enables the z/OS application programs to access IMS DL/I full-function databases and data entry databases (DEDBs). The three parts to access IMS DL/I using the ODBA interface are Common Logic Flow for SRMS and MRMS, SRMS, and MRMS. The common logic flow for single resource manage scenarios (SRMS) and multiple resource manager scenarios (MRMS) is described in steps one through nine. The logic flow differences for SRMS and MRMS are described below. 1. I/O area. IMS passes segments to and from the application program in the its I/O area. 2. PCB. IMS describes the results of each DL/I call in the database PCB mask. 3. Application interface block (AIB). The AIB provides the program with addresses of the PCBs and return codes from the ODBA-DL/I interface. 4. Program entry. Obtain and initialize the AIB. 5. Initialize the Open Database Access (ODBA) interface. 6. Schedule the PSB. This step identifies the PSB that your program is to use and also provides a place for IMS to keep internal tokens. 7. Issue DL/I calls. Issue DL/I calls to read and update the database. The following calls are available: v Retrieve v Replace v Delete
12
DL/I using the ODBA Interface

v Insert 8. Check the return code in the AIB. You should check the return code after issuing any DL/I call for database processing. Do this before checking the status code in the PCB. 9. Check the status code in the PCB. If the AIB return code indicates (Return Code X'900'), then you should check the status code after issuing any DL/I call for database processing. The code gives you the results of your DL/I call. The logic flow for how the programmer commits changes for SRMS follows. The programmer: 1. Commits database changes. No DL/I calls, including system service calls such as LOG or STAT, can be made between the commit and the termination of the DPSB. 2. Terminates the PSB. 3. Terminates the ODBA interface. 4. Returns to environment that initialized the application program. The logic flow for how the programmer commits changes for MRMS follows. The programmer: 1. Terminates the PSB. 2. Terminates the ODBA interface. 3. Commits changes. 4. Returns to environment that initialized the application program.
Database Hierarchy Examples

The examples in this information use the medical hierarchy shown in Figure 5 and the bank hierarchies shown in Table 8 on page 16, Table 9 on page 17, and Table 10 on page 17. The medical hierarchy is used with full-function databases and Fast Path data entry databases (DEDBs). The bank hierarchies are an example of an application program used with main storage databases (MSDBs). To understand these examples, familiarize yourself with the hierarchies and segments that each hierarchy contains.
Medical Hierarchy Example

The medical database shown in Figure 5 contains information that a medical clinic keeps about its patients.
Figure 5. Medical Hierarchy
The tables that follow show the layouts of each segment in the hierarchy. The segments field names are in the first row of each table. The number below each field name is the length in bytes that has been defined for that field.
13

v PATIENT Segment Table 2 shows the PATIENT segment. It has three fields: The patients number (PATNO) The patients name (NAME) The patient's address (ADDR) PATIENT has a unique key field: PATNO. PATIENT segments are stored in ascending order based on the patient number. The lowest patient number in the database is 00001 and the highest is 10500.
Table 2. PATIENT Segment Field Name PATNO NAME ADDR Field Length 10 5 30
v ILLNESS Segment Table 3 shows the ILLNESS segment. It has two fields: The date when the patient came to the clinic with the illness (ILLDATE) The name of the illness (ILLNAME) The key field is ILLDATE. Because it is possible for a patient to come to the clinic with more than one illness on the same date, this key field is non unique, that is, there may be more than one ILLNESS segment with the same (an equal) key field value. Usually during installation, the database administrator (DBA) decides the order in which to place the database segments with equal or no keys. The DBA can use the RULES keyword of the SEGM statement of the DBD to specify the order of the segments. 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.
Table 3. ILLNESS Segment Field Name ILLDATE ILLNAME Field Length 8 10
v TREATMNT Segment Table 4 on page 15 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 received (QUANTITY) The name of the doctor who prescribed the treatment (DOCTOR) The TREATMNT segments key field is DATE. Because a patient may receive more than one treatment on the same date, DATE is a non unique key field.
14

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 ILLDATEYYYYMMDD.
Table 4. TREATMNT Segment Field Name DATE MEDICINE QUANTITY DOCTOR Field Length 8 10 4 10
v BILLING Segment Table 5 shows the BILLING segment. It has only one field: the amount of the current bill. BILLING has no key field.
Table 5. BILLING Segment Field Name BILLING Field Length 6
v PAYMENT Segment Table 6 shows the PAYMENT segment. It has only one field: the amount of payments for the month. The PAYMENT segment has no key field.
Table 6. PAYMENT Segment Field Name PAYMENT Field Length 6
v HOUSHOLD Segment Table 7 shows the HOUSHOLD segment. It contains two fields: The names of the members of the patient's household (RELNAME) How each member of the household is related to the patient (RELATN) The HOUSEHOLD segments key field is RELNAME.
Table 7. HOUSEHOLD Segment Field Name RELNAME RELATN Field Length 10 8
Bank Account Hierarchy Example

The bank account hierarchy is an example of an application program that is used with main storage databases (MSDBs). In the medical hierarchy example, the database record for a particular patient comprises the PATIENT segment and all of the segments underneath the PATIENT segment. In an MSDB, such as the one in the bank account example, the segment is the whole database record. The database record contains only the fields that the segment contains. The two types of MSDBs are related and nonrelated. In related MSDBs, each segment is owned by one logical terminal. The "owned" segment can only be updated by the terminal that owns it. In nonrelated MSDBs, the segments are not owned by
15

logical terminals. Related MSDBs and Nonrelated MSDBs on page 17 illustrate the differences between these types of databases. Additional information on how related and nonrelated MSDBs differ is provided under Processing MSDBs and DEDBs on page 171.
Related MSDBs
Related MSDBs can be fixed or dynamic. In a fixed related MSDB, you can store summary data about a particular teller at a bank. For example, you can have an identification code for the teller's terminal. Then you can keep a count of that teller's transactions and balance for the day. This type of application requires a segment with three fields: TELLERID TRANCNT TELLBAL A two-character code that identifies the teller The number of transactions the teller has processed The balance for the teller
Table 8 shows what the segment for this type of application program looks like.
Table 8. Teller Segment in a Fixed Related MSDB TELLERID TRANCNT TELLBAL
Some of the characteristics of fixed related MSDBs include: v You can only read and replace segments. You cannot delete or insert segments. In the bank teller example, the teller can change the number of transactions processed, but you cannot add or delete any segments. You never need to add or delete segments. v Each segment is assigned to one logical terminal. Only the owning terminal can change a segment, but other terminals can read the segment. In the bank teller example, you do not want tellers to update the information about other tellers, but you allow the tellers to view each others information. Tellers are responsible for their own transactions. v The name of the logical terminal that owns the segment is the segment's key. Unlike non-MSDB segments, the MSDB key is not a field of the segment. It is used as a means of storing and accessing segments. v A logical terminal can only own one segment in any one MSDB. In a dynamic related MSDB, you can store data summarizing the activity of all bank tellers at a single branch. For example, this segment contains: BRANCHNO The identification number for the branch TOTAL TRANCNT DEPBAL WTHBAL The bank branch's current balance The number of transactions for the branch on that day The deposit balance, giving the total dollar amount of deposits for the branch The withdrawal balance, giving the dollar amount of the withdrawals for the branch
Table 9 on page 17 shows what the branch summary segment looks like in a dynamic related MSDB.
16

Table 9. Branch Summary Segment in a Dynamic Related MSDB BRANCHNO TOTAL TRANCNT DEPBAL WTHBAL
How dynamic related MSDBs differ from fixed related MSDBs: v The owning logical terminal can delete and insert segments in a dynamic related MSDB. v The MSDB can have a pool of unassigned segments. This kind of segment is assigned to a logical terminal when the logical terminal inserts it, and is returned to the pool when the logical terminal deletes it.
Nonrelated MSDBs
A nonrelated MSDB is used to store data that is updated by several terminals during the same time period. For example, you might store data about an individuals' bank accounts in a nonrelated MSDB segment, so that the information can be updated by a teller at any terminal. Your program might need to access the data in the following segment fields: ACCNTNO BRANCH TRANCNT BALANCE The account number The name of the branch where the account is The number of transactions for this account this month The current balance
Table 10 shows what the account segment in a nonrelated MSDB application program looks like.
Table 10. Account Segment in a Nonrelated MSDB ACCNTNO BRANCH TRANCNT BALANCE
The characteristics of nonrelated MSDBs include: v Segments are not owned by terminals as they are in related MSDBs. Therefore, IMS programs and Fast Path programs can update these segments. Updating segments is not restricted to the owning logical terminal. v Your program cannot delete or insert segments. v Segment keys can be the name of a logical terminal. A nonrelated MSDB exists with terminal-related keys. The segments are not owned by the logical terminals, and the logical terminal name is used to identify the segment. v If the key is not the name of a logical terminal, it can be any value, and it is in the first field of the segment. Segments are loaded in key sequence.
17
18
Chapter 2. Writing Your Application Programs

| | | | | | | | | | | This chapter contains information that will help you write application programs. It contains guidelines for writing efficient application programs and using segment search arguments (SSAs) and command codes. A checklist of coding considerations and skeleton programs in High Level Assembler language, C language, COBOL, Pascal, and PL/I are also available to help you. The following topics provide additional information: v Programming Guidelines v v v v Segment Search Arguments (SSAs) on page 20 Considerations for Coding DL/I Calls and Data Areas on page 28 Preparing to Run Your CICS DL/I Call Program on page 29 Examples of How to Code DL/I Calls and Data Areas on page 29
Programming Guidelines
The number, type, and sequence of the IMS requests your program issues affects the efficiency of your program. A program that is poorly designed can still run if it is coded correctly. IMS will not find design errors for you. The suggestions that follow will help you develop the most efficient design possible for your application program. When you have a general sequence of calls mapped out for your program, look over the guidelines on sequence to see if you can improve it. An efficient sequence of requests results in efficient internal IMS processing. As you write your program, keep in mind the guidelines explained in this section. The following list offers programming guidelines that will help you write efficient and error-free programs. v Use the most simple call. Qualify your requests to narrow the search for IMS. v Use the request or sequence of requests that will give IMS the shortest path to the segment you want. v Use as few requests as possible. Each DL/I call your program issues uses system time and resources. You may be able to eliminate unnecessary calls by: Using path requests when 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 subsequent times it needs the segment. If your program retrieves the same segment more than once during program execution, you are issuing unnecessary requests. 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 GN calls 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. 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, rather than issuing Get requests for the parents to make sure that they exist. If IMS
19
Programming Guidelines
returns a GE status code, at least one of the parents does not exist. When you are inserting segments, you cannot insert dependent segments unless the parent segments exist. | | | | | | | | | v Commit your updates regularly. IMS limits full-function databases so that only 300 databases at a time can have uncommitted updates. Logically related databases, secondary indexes, and HALDB partitions are counted towards this limit. The number of partitions in HALDB databases is the most common reason for approaching the 300 database limit for uncommitted updates. If the PROCOPT values allow a BMP application to insert, replace, or delete segments in the databases, ensure that the BMP application does not update a combined total of more than 300 databases and HALDB partitions without committing the changes. 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 branching around them to continue normal processing. v Use call sequences that make good use of the physical placement of the data. Access segments in hierarchic sequence as often as possible, and avoid moving backward in the hierarchy. v Process database records in order of the key field of the root segments. (For HDAM and PHDAM databases, this order depends on the randomizing routine that is used. Check with your DBA for this information.) v 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. v Minimize the number of segments your program locks. You may need to take checkpoints to release the locks on updated segments and the lock on the current database record for each PCB your program uses. Each PCB used by your program has the current database record locked at share or update level. If this lock is no longer required, issuing the GU call, qualified at the root level with a greater-than operator for a key of X'FF' (high values), releases the current lock without acquiring a new lock. | | | | | | Do not use the minimization technique if you use a randomizer that puts high values at the end of the database and you use secondary indexes. If there is another root beyond the supposed high value key, IMS returns a GE to allow the application to determine the next step. A secondary index might not work because the hierarchical structure is inverted, and although the key is past the last root in the index, it might not be past the last root in the database. Using PCBs with a processing option of get (G) results in locks for the PCB at share level. This allows other programs that use the get processing option to concurrently access the same database record. Using a PCB with a processing option that allows updates (I, R, or D) results in locks for the PCB at update level. This does not allow any other program to concurrently access the same database record. Related Reading: For more information about segment locking, see Reserving Segments for the Exclusive Use of Your Program on page 118.
| |
Segment Search Arguments (SSAs)

Segment search arguments (SSAs) specify information for IMS to use in processing a DL/I call. A DL/I call with one or more SSAs is a qualified call, and a DL/I call without SSAs is an unqualified call. Definitions:
20
Segment Search Arguments (SSA)

Unqualified SSAs Qualified SSAs Contains only a segment name. Includes one or more qualification statements that name a segment occurrence. The C command and a segment occurrence's concatenated key can be substituted for a qualification statement.
You can use SSA to select segments by name and to specify search criteria for specific segments. Specific segments are described by adding qualification statements to the DL/I call. You can further qualify your calls by using command codes. Table 11 shows the structure of a qualified SSA. Table 12 on page 27 shows the structure of an unqualified SSA using command codes. Finally, Table 13 on page 27 shows the structure of a qualified SSA that uses command codes.
Unqualified SSAs
An unqualified SSA gives the name of the segment type that you want to access. In an unqualified SSA, the segment name field is 8 bytes and must be followed by a 1-byte blank. If the actual segment name is fewer than 8 bytes long, it must be padded to the right with blanks. An example of an unqualified SSA follows:
PATIENT
Qualified SSAs
To qualify an SSA, you can use either a field or the sequence field of a virtual child. A qualified SSA describes the segment occurrence that you want to access. This description is called a qualification statement and has three parts. Table 11 shows the structure of a qualified SSA.
Table 11. Qualified SSA Structure SSA Component Seg Name ( Fld Name R.O. Fld Value ) Field Length 8 1 8 2 Variable 1
Using a qualification statement enables you to give IMS information about the particular segment occurrence that you are looking for. You do this by giving IMS the name of a field within the segment and the value of the field you are looking for. The field and the value are connected by a relational operator (R.O. in Table 11) which tells IMS how you want the two compared. For example, to access the PATIENT segment with the value 10460 in the PATNO field, you could use this SSA:
PATIENT (PATNO = 10460)
The qualification statement is enclosed in parentheses. The first field contains the name of the field (Fld Name in Table 11) that you want IMS to use in searching for the segment. The second field contains a relational operator. The relational operator can be any one of the following: v Equal, represented as
21

= = EQ v Greater than, represented as > > GT v Less than, represented as < < LT v Greater than or equal to, represented as >= => GE v Less than or equal to, represented as <= =< LE v Not equal to, represented as = = NE The third field (Fld Value in Table 11 on page 21) contains the value that you want IMS to use as the comparative value. The length of Fld Value must be the same length as the field specified by Fld Name. You can use more than one qualification statement in an SSA. Special cases exist, such as in a virtual logical child segment when the sequence field consists of multiple fields. Related Reading: For more information on multiple qualification statements, see Multiple Qualification Statements on page 24.
Sequence Fields of a Virtual Logical Child

As a general rule, a segment can have only one sequence field. However, in the case of the virtual logical-child segment type, multiple FIELD statements can be used to define a noncontiguous sequence field. When specifying the sequence field for a virtual logical child segment, if the field is not contiguous, the length of the field named in the SSA is the concatenated length of the specified field plus all succeeding sequence fields. Figure 6 on page 23 shows a segment with a noncontiguous sequence field.
22
Figure 6. Segment with a Noncontiguous Sequence Field
If the first sequence field is not included in a scattered sequence field in an SSA, IMS treats the argument as a data field specification, rather than as a sequence field. Related Reading: For more information on the virtual logical child segment, refer to IMS Version 9: Administration Guide: Database Manager.
SSA Guidelines
Using SSAs can simplify your programming, because the more information you can give IMS to do the searching for you, the less program logic you need to analyze and compare segments in your program. Using SSAs does not necessarily reduce system overhead, such as internal logic and I/Os, required to obtain a specific segment. To locate a particular segment without using SSAs, you can issue DL/I calls and include program logic to examine key fields until you find the segment you want. By using SSAs in your DL/I calls, you can reduce the number of DL/I calls that are issued and the program logic needed to examine key fields. When you use SSAs, IMS does this work for you. Recommendations: v Use qualified calls with qualified SSAs whenever possible. SSAs act as filters, returning only the segments your program requires. This reduces the number of calls your program makes, which provides better performance. It also provides better documentation of your program. Qualified SSAs are particularly useful when adding segments with insert calls. They ensure that the segments are inserted where you want them to go. v For the root segment, specify the key field and an equal relational operator, if possible. Using a key field with an equal-to, equal-to-or-greater-than, or greater-than operator lets IMS go directly to the root segment. v For dependent segments, it is desirable to use the key field in the SSA, although it is not as important as at the root level. Using the key field and an equal-to operator lets IMS stop the search at that level when a higher key value is encountered. Otherwise IMS must search through all occurrences of the segment type under its established parent in order to determine whether a particular segment exists. v If you often must search for a segment using a field other than the key field, consider putting a secondary index on the field. For more information on secondary indexing, see Chapter 7, Secondary Indexing and Logical Relationships, on page 149. Example: Suppose you want to find the record for a patient by the name of Ellen Carter. As a reminder, the patient segment in the examples contains three fields: the patient number, which is the key field; the patient name; and the patient address. The fact that patient number is the key field means that IMS stores the
23
Segment Search Argument (SSA) Guidelines

patient segments in order of their patient numbers. The best way to get the record for Ellen Carter is to supply her patient number in the SSA. If her number is 09000, your program uses this call and SSA:
GU&$tab;PATIENT (PATNO = 09000)
If your program supplies an invalid number, or if someone has deleted Ellen Carter's record from the database, IMS does not need to search through all the PATIENT occurrences to determine that the segment does not exist. However, if your program does not have the number and must give the name instead, IMS must search through all the patient segments and read each patient name field until it finds Ellen Carter or until it reaches the end of the patient segments.
Multiple Qualification Statements

When you use a qualification statement, you can do more than give IMS a field value with which to compare the fields of segments in the database. You can give several field values to establish limits for the fields you want IMS to compare. You can use a maximum of 1024 qualification statements on a call. Connect the qualification statements with one of the Boolean operators. You can indicate to IMS that you are looking for a value that, for example, is greater than A and less than B, or you can indicate that you are looking for a value that is equal to A or greater than B. The Boolean operators are: Logical AND For a segment to satisfy this request, the segment must satisfy both qualification statements that are connected with the logical AND (coded * or &). For a segment to satisfy this request, the segment can satisfy either of the qualification statements that are connected with the logical OR (coded + or |).
Logical OR
One more Boolean operator exists and is called the independent AND. Use it only with secondary indexes. Multiple Qualification Statements with Secondary Indexes on page 150 describes its use. For a segment to satisfy multiple qualification statements, the segment must satisfy a set of qualification statements. A set is a number of qualification statements that are joined by an AND. To satisfy a set, a segment must satisfy each of the qualification statements within that set. Each OR starts a new set of qualification statements. When processing multiple qualification statements, IMS reads them left to right and processes them in that order. When you include multiple qualification statements for a root segment, the fields you name in the qualification statements affect the range of roots that IMS examines to satisfy the call. DL/I examines the qualification statements to determine the minimum acceptable key value. If one or more of the sets do not include at least one statement that is qualified on the key field with an operator of equal-to, greater-than, or equal-to-or-greater-than, IMS starts at the first root of the database and searches for a root that meets the qualification.
24

If each set contains at least one statement that is qualified on the key field with an equal-to, greater-than, or equal-to-or-greater-than operator, IMS uses the lowest of these keys as the starting place for its search. After establishing the starting position for the search, IMS processes the call by searching forward sequentially in the database, similar to the way it processes GN calls. IMS examines each root it encounters to determine whether the root satisfies a set of qualification statements. IMS also examines the qualification statements to determine the maximum acceptable key value. If one or more of the sets do not include at least one statement that is qualified on the key field with an operator of equal-to, less-than-or-equal-to, or less-than, IMS determines that no maximum key value exists. If each set contains at least one statement that is qualified on the key field with an equal-to, less-than, or equal-to-or-less-than operator, IMS uses the maximum of these keys to determine when the search stops. IMS continues the search until it satisfies the call, encounters the end of the database, or finds a key value that exceeds the maximum. If no maximum key value is found, the search continues until IMS satisfies the call or encounters the end of the database. Examples: Shown below are cases of SSAs used at the root level:
ROOTKEY = 10&FIELDB =XYZ+ROOTKEY =10&FIELDB =ABC
In this case, the minimum and maximum key is 10. This means that IMS starts searching with key 10 and stops when it encounters the first key greater than 10. To satisfy the SSA, the ROOTKEY field must be equal to 10, and FIELDB must be equal to either ABC or XYZ.
ROOTKEY =>10&ROOTKEY =<20
In this case, the minimum key is 10 and the maximum key is 20. Keys in the range of 10 to 20 satisfy the SSA. IMS stops the search when it encounters the first key greater than 20.
ROOTKEY =>10&ROOTKEY =<20+ROOTKEY =>110&ROOTKEY =<120
In this case, the minimum key is 10 and the maximum key is 120. Keys in the range of 10 to 20 and 110 to 120 satisfy the call. IMS stops the search when it encounters the first key greater than 120. IMS does not scan from 20 to 110 but skips forward (using the index for HIDAM or PHIDAM) from 20 to 110. Because of this, you can use ranges for more efficient program operation. When you use multiple qualification statement segments that are part of logical relationships, additional considerations exist. See How Logical Relationships Affect Your Programming on page 154 for more information about these considerations.
Example of How to Use Multiple Qualification Statements

The easiest way to understand multiple qualification statements is to look at an example: Did we see patient number 04120 during 1992? To find the answer to this question, you need to give IMS more than the patients name; you want IMS to search through the ILLNESS segments for that patient, read each one, and return any that have a date in 1992. The call you would issue to do this is:
25

GU PATIENT (PATNO EQ04120) ILLNESS (ILLDATE >=19920101&ILLDATE <=19921231)
In other words, you want IMS to return any ILLNESS segment occurrences under patient number 04120 that have a date on or after January 1, 1992, and on or before December 31, 1992, joined with an AND connector. Suppose you wanted to answer the following request: Did we see Judy Jennison during January of 1992 or during July of 1992? Her patient number is 05682. You could issue a GU call with the following SSAs:
GU PATIENT (PATNO EQ05682) ILLNESS (ILLDATE >=19920101&ILLDATE <=19920131| ILLDATE >=19920701&ILLDATE <=19920731)
To satisfy this request, the value for ILLDATE must satisfy either of the two sets. IMS returns any ILLNESS segment occurrences for the month of January 1992, or for the month of July 1992.
Multiple Qualification Statements for HDAM, PHDAM, or DEDB

For HDAM (Hierarchical Direct Access Method ), PHDAM (partioned HDAM), or data entry database (DEDB) organizations, a randomizing exit routine usually does not store the root keys in ascending key sequence. For these organizations, IMS determines the minimum and maximum key values. The minimum key value is passed to the randomizing exit routine, which determines the starting anchor point. The first root off this anchor is the starting point for the search. When IMS encounters a key that exceeds the maximum key value, IMS terminates the search with a GE status code. If the randomizing routine randomized so that the keys are stored in ascending key sequence, a call for a range of keys will return all of the keys in the range. However, if the randomizing routine did not randomize into key sequence, the call does not return all keys in the requested range. Therefore, use calls for a range of key values only when the keys are in ascending sequence (when the organization is HDAM, PHDAM, or DEDB). Recommendation: When the organization is HDAM or DEDB, do not use calls that allow a range of values at the root level. For more details about HDAM or PHDAM databases, see IMS Version 9: Administration Guide: Database Manager.
SSAs and Command Codes

SSAs can also include one or more command codes, which can change and extend the functions of DL/I calls. For information on command codes, see General Command Codes for DL/I Calls on page 202. IMS always returns the lowest segment in the path to your I/O area. If your program codes a D command code in an SSA, IMS also returns the segment described by that SSA. A call that uses the D command code is called a path call. Example: Suppose your program codes a D command code on a GU call that retrieves segment F and all segments in the path to F in the hierarchy shown in Figure 7.
26
Figure 7. D Command Code Example
The call function and the SSAs for the call look like this:
GU A C E F *D *D *D
A command code consists of one letter. Code the command codes in the SSA after the segment name field. Separate the segment name field and the command code with an asterisk, as shown in Table 12.
Table 12. Unqualified SSA with Command Code SSA Component Seg Name * Cmd Code b Field Length 8 1 Variable 1
Your program can use command codes in both qualified and unqualified SSAs. However, command codes cannot be used by MSDB calls. If the command codes are not followed by qualification statements, they must each be followed by a 1-byte blank. If the command codes are followed by qualification statements, do not use the blank. The left parenthesis of the qualification statement follows the command code instead, as indicated in Table 13.
Table 13. Qualified SSA with Command Code SSA Component Seg Name * Cmd Code ( Fld Name R.O. Fld Value ) Field Length 8 1 Variable 1 8 2 Variable 1
If your program uses command codes to manage subset pointers in a DEDB, enter the number of the subset pointer immediately after the command code. Subset pointers are a means of dividing a chain of segment occurrences under the same
27

parent into two or more groups or subsets. Your program can define as many as eight subset pointers for any segment type. Using an application program, your program can then manage these subset pointers. This process is described in detail in Processing DEDBs with Subset Pointers on page 178.
Considerations for Coding DL/I Calls and Data Areas

If you have made all the design decisions about your program, coding the program is a matter of implementing the decisions that you have made. Before you start coding, make sure you have the information described in this section. In addition to knowing the design and processing logic for your program, you need to know about the data that your program is processing, the PCBs it references, and the segment formats in the hierarchies your program processes. You can use the following list as a checklist to make sure you are not missing any information. If you are missing information about data, IMS options being used in the application program, or segment layouts and the application program's data structures, obtain this information from the DBA or the equivalent specialist at your installation. Be aware of the programming standards and conventions that have been established at your installation. Program design considerations: v The sequence of calls for your program. v The format of each call: Does the call include any SSAs? If so, are they qualified or unqualified? Does the call contain any command codes? v The processing logic for the program. v The routine the program uses to check the status code after each call. v The error routine the program uses. Checkpoint considerations: v The type of checkpoint call to use (basic or symbolic). v The identification to assign to each checkpoint call, regardless of whether the Checkpoint call is basic or symbolic. v If you are going to use the symbolic checkpoint call, which areas of your program to checkpoint. Segment considerations: v Whether the segment is fixed length or variable length. v The length of the segment (the maximum length, if the segment is variable length). v The names of the fields that each segment contains. v Whether the segment has a key field. If it does, is the key field unique or non unique? If it does not, what sequencing rule has been defined for it? (A segment's key field is defined in the SEQ keyword of the FIELD statement in the DBD. The sequencing rule is defined in the RULES keyword of the SEGM statement in the DBD.) v The segment's field layouts: The byte location of each field. The length of each field.
28
Considerations for Coding DL/I Calls and Data Areas

The format of each field. Data structure considerations: v Each data structure your program processes has been defined in a DB PCB. All of the PCBs your program references are part of a PSB for your application program. You need to know the order in which the PCBs are defined in the PSB. v The layout of each of the data structures your program processes. v Whether multiple or single positioning has been specified for each data structure. This is specified in the POS keyword of the PCB statement during PSB generation. v Whether any data structures use multiple DB PCBs.
Preparing to Run Your CICS DL/I Call Program

You must perform several steps before you run your CICS DL/I call program. Refer to the appropriate CICS reference information. v For information on translating, compiling, and binding your CICS online program, see the description of installing application programs in CICS/ESA System Definition Guide. v For information on which compiler options should be used for a CICS online program, as well as for CICS considerations when converting a CICS online COBOL program with DL/I calls to Enterprise COBOL, see CICS/ESA Application Programming Guide.
| | | | | | |
Examples of How to Code DL/I Calls and Data Areas

This section contains sample programs written in assembler language, C language, COBOL, Pascal, and PL/I. The programs are examples of how to code DL/I calls and data areas. They are not complete programs. Before running them, you must modify them to suit the requirements of your installation. The following topics provide additional: v Coding a Batch Program in Assembler Language v v v v v Coding Coding Coding Coding Coding a a a a a CICS Online Program in Assembler Language on page 32 Batch Program in C Language on page 34 Batch Program in COBOL on page 36 CICS Online Program in COBOL on page 39 Batch Program in Pascal on page 44
v Coding a Batch Program in PL/I on page 46 v Coding a CICS Online Program in PL/I on page 50
Coding a Batch Program in Assembler Language

Figure 8 on page 30 is a skeleton program that shows how the parts of an IMS program written in assembler language fit together. The numbers to the right of the program refer to the notes that follow the program. This kind of program can run as a batch program or as a batch-oriented BMP.
29
Coding Programs in Assembler Language

PGMSTART CSECT * EQUATE REGISTERS * USEAGE OF REGISTERS R1 EQU 1 ORIGINAL PCBLIST ADDRESS R2 EQU 2 PCBLIST ADDRESS1 R5 EQU 5 PCB ADDRESSS R12 EQU 12 BASE ADDRESS R13 EQU 13 SAVE AREA ADDRESS R14 EQU 14 R15 EQU 15 * USING PGMSTART,R12 BASE REGISTER ESTABLISHED SAVE (14,12) SAVE REGISTERS LR 12,15 LOAD REGISTERS ST R13,SAVEAREA+4 SAVE AREA CHAINING LA R13,SAVEAREA NEW SAVE AREA USING PCBLIST,R2 MAP INPUT PARAMETER LIST USING PCBNAME,R5 MAP DB PCB LR R2,R1 SAVE INPUT PCB LIST IN REG 2 L R5,PCBDETA LOAD DETAIL PCB ADDRESS LA R5,0(R5) REMOVE HIGH ORDER END OF LIST FLAG CALL ASMTDLI,(GU,(R5),DETSEGIO,SSANAME),VL * * L R5,PCBMSTA LOAD MASTER PCB ADDRESS CALL ASMTDLI,(GHU,(R5),MSTSEGIO,SSAU),VL * * CALL ASMTDLI,(GHN,(R5),MSTSEGIO),VL * * CALL ASMTDLI,(REPL,(R5),MSTSEGIO),VL * * L R13,4(R13) RESTORE SAVE AREA RETURN (14,12) RETURN BACK * * FUNCTION CODES USED * GU DC CL4GU GHU DC CL4GHU GHN DC CL4GHN REPL DC CL4REPL * * SSAS * SSANAME DS 0C DC CL8ROOTDET DC CL1( DC CL8KEYDET DC CL2 = NAME DC CL5 DC C) * Figure 8. Sample Assembler Language Program (Part 1 of 2) NOTES 1
3 4
5 6
30

SSAU MSTSEGIO DETSEGIO SAVEAREA * PCBLIST PCBIO PCBMSTA PCBDETA * PCBNAME DBPCBDBD DBPCBLEV DBPCBSTC DBPCBPRO DBPCBRSV DBPCBSFD DBPCBMKL DBPCBNSS DBPCBKFD DC DC DC DC CL9ROOTMST* CL100 CL100 18F0 10 DSECT DS A DS A DS A DSECT DS DS DS DS DS DS DS DS DS END CL8 CL2 CL2 CL4 F CL8 F F C PGMSTART ADDRESS OF I/O PCB ADDRESS OF MASTER PCB ADDRESS OF DETAIL PCB DBD NAME LEVEL FEEDBACK STATUS CODES PROC OPTIONS RESERVED SEGMENT NAME FEEDBACK LENGTH OF KEY FEEDBACK NUMBER OF SENSITIVE SEGMENTS IN PCB KEY FEEDBACK AREA
11
Figure 8. Sample Assembler Language Program (Part 2 of 2)
Notes to Figure 8 on page 30: 1. The entry point to an assembler language program can have any name. Also, you can substitute CBLTDLI for ASMTDLI in any of the calls. 2. When IMS passes control to the application program, register 1 contains the address of a variable-length fullword parameter list. Each word in this list contains the address of a PCB that the application program must save. The high-order byte of the last word in the parameter list has the 0 bit set to a value of 1 which indicates the end of the list. The application program subsequently uses these addresses when it executes DL/I calls. 3. The program loads the address of the DETAIL DB PCB. 4. The program issues a GU call to the DETAIL database using a qualified SSA (SSANAME). 5. The program loads the address of the HALDB master PCB. 6. The next three calls that the program issues are to the HALDB master. The first is a GHU call that uses an unqualified SSA. The second is an unqualified GHN call. The REPL call replaces the segment retrieved using the GHN call with the segment in the MSTSEGIO area. You can use the parmcount parameter in DL/I calls in assembler language instead of the VL parameter, except for in the call to the sample status-code error routine. 7. The RETURN statement loads IMS registers and returns control to IMS. 8. The call functions are defined as four-character constants. 9. The program defines each part of the SSA separately so that it can modify the SSA's fields. 10. The program must define an I/O area that is large enough to contain the largest segment it is to retrieve or insert (or the largest path of segments if the program uses the D command code). This program's I/O areas are 100 bytes each. 11. A fullword must be defined for each PCB. The assembler language program can access status codes after a DL/I call by using the DB PCB base addresses. This example assumes that an I/O PCB was passed to the application program. If the program is a batch program, CMPAT=YES must be specified on the PSBGEN statement of PSBGEN so that the I/O PCB is included.
31

Because the I/O PCB is required for a batch program to make system service calls, CMPAT=YES should always be specified.
Binding Assembler Code to the IMS Language Interface Module

The IMS language interface module (DFSLI000) must be bound to the compiled assembler language program.
Coding a CICS Online Program in Assembler Language

Figure 9 is a skeleton program in assembler language. It shows how you define and establish addressability to the UIB. The numbers to the right of the program refer to the notes that follow the program. This program can run in a CICS environment using DBCTL.
PGMSTART UIBPTR IOAREA AREA1 AREA2 PCBPTRS * PCB1PTR PCB1 DBPC1DBD DBPC1LEV DBPC1STC DBPC1PRO DBPC1RSV DBPC1SFD DBPC1MKL DBPC1NSS DBPC1KFD DBPC1NM DBPC1NMA DBPC1NMP ASMUIB PSBNAME PCBFUN REPLFUN TERMFUN GHUFUN SSA1 GOODRC GOODSC SKIP * DSECT DS F DS 0CL40 DS CL3 DS CL37 DLIUIB USING UIB,8 DSECT PSB ADDRESS LIST DS F DSECT USING PCB1,6 DS CL8 DS CL2 DS CL2 DS CL4 DS F DS CL8 DS F DS F DS 0CL256 DS 0CL12 DS 0CL14 DS CL17 CSECT B SKIP DC CL8ASMPSB DC CL4PCB DC CL4REPL DC CL4TERM DC CL4GHU DC CL9AAAA4444 DC XL100 DC CL2 DS 0H SCHEDULE PSB AND OBTAIN PCB ADDRESSES NOTES 1
Figure 9. Sample Call-Level Assembler Language Program (CICS Online) (Part 1 of 2)
32

CALLDLI ASMTDLI,(PCBFUN,PSBNAME,UIBPTR) L 8,UIBPTR CLC UIBFCTR,X00 BNE ERROR1 GET PSB ADDRESS LIST L 4,UIBPCBAL USING PCBPTRS,4 GET ADDRESS OF FIRST PCB IN LIST L 6,PCB1PTR ISSUE DL/I CALL: GET A UNIQUE SEGMENT CALLDLI ASMTDLI,(GHUFUN,PCB1,IOAREA,SSA1) CLC UIBFCTR,GOODRC BNE ERROR2 CLC DBPC1STC,GOODSC BNE ERROR3 PERFORM SEGMENT UPDATE ACTIVITY MVC AREA1,....... MVC AREA2,....... ISSUE DL/I CALL: REPLACE SEGMENT AT CURRENT POSITION CALLDLI ASMTDLI,(REPLFUN,PCB1,IOAREA,SSA1) CLC UIBFCTR,GOODRC BNE ERROR4 CLC DBPC1STC,GOODSC B TERM DS 0H INSERT ERROR DIAGNOSTIC CODE B TERM DS 0H INSERT ERROR DIAGNOSTIC CODE B TERM DS 0H INSERT ERROR DIAGNOSTIC CODE B TERM DS 0H INSERT ERROR DIAGNOSTIC CODE DS 0H INSERT ERROR DIAGNOSTIC CODE B TERM DS 0H RELEASE THE PSB CALLDLI ASMDLI, (TERMFUN) EXEC CICS RETURN END ASMUIB
* * *
* *
ERROR1 * ERROR2 * ERROR3 * ERROR4 * ERROR5 * TERM *
9,10
Figure 9. Sample Call-Level Assembler Language Program (CICS Online) (Part 2 of 2)
Notes to the example: 1. The program must define an I/O area that is large enough to contain the largest segment it is to retrieve or insert (or the largest path of segments if the program uses the D command code). 2. The DLIUIB statement copies the UIB DSECT, which is expanded as shown under Specifying the UIB (CICS Online Programs Only) on page 77. 3. A fullword must be defined for each DB PCB. The assembler language program can access status codes after a DL/I call by using the DB PCB base addresses. 4. This is an unqualified SSA. For qualified SSA, define each part of the SSA separately so that the program can modify the fields of the SSA. 5. This call schedules the PSB and obtains the PSB address. 6. This call retrieves a segment from the database. CICS online assembler language programs use the CALLDLI macro, instead of the call statement, to access DL/I databases. This macro is similar to the call statement. It looks like this:
33

CALLDLI ASMTDLI,(function,PCB-name,ioarea, SSA1,...SSAn),VL
7. CICS online programs must check the return code in the UIB before checking the status code in the DB PCB. 8. The REPL call replaces the data in the segment that was retrieved by the most recent Get Hold call. The data is replaced by the contents of the I/O area referenced in the call. 9. This call releases the PSB. 10. The RETURN statement loads IMS registers and returns control to IMS. | Related Reading: For more information on installing CICS application programs, see CICS/MVS Installation Guide.
Coding a Batch Program in C Language

Figure 10 is a skeleton batch program that shows you how the parts of an IMS program that is written in C fit together. The numbers to the right of the program refer to the notes that follow the program.
#pragma runopts(env(IMS),plist(IMS)) #include <ims.h> #include <stdio.h> main() { /* */ /* descriptive statements */ /* */ IO_PCB_TYPE *IO_PCB = (IO_PCB_TYPE*)PCBLIST[0]; struct {PCB_STRUCT(10)} *mast_PCB = __pcblist[1]; struct {PCB_STRUCT(20)} *detail_PCB = __pcblist[2]; const static char func_GU[4] = "GU "; const static char func_GN[4] = "GN "; const static char func_GHU[4] = "GHU "; const static char func_GHN[4] = "GHN "; const static char func_GNP[4] = "GNP "; const static char func_GHNP[4] = "GHNP"; const static char func_ISRT[4] = "ISRT"; const static char func_REPL[4] = "REPL"; const static char func_DLET[4] = "DLET"; char qual_ssa[8+1+8+2+6+1+1]; /* initialized by sprintf /*below. See the */ /*explanation for */ /*sprintf in note 7 for the */ /*meanings of 8,1,8,2,6,1 */ /*the final 1 is for the */ /*trailing \0 of string */ static const char unqual_ssa[]= "NAME "); /* 12345678_ */ struct { } mast_seg_io_area; struct { } det_seg_io_area; Figure 10. Sample C Language Program (Part 1 of 2) 6 NOTES 1 2
34
Coding Programs in C Language

/* /* /* */ */ */
Initialize the qualifier sprintf(qual_ssa, "%8.8s(%8.8s%2.2s%6.6s)", "ROOT", "KEY", "=", "vvvvv");
7 */ */ */ 8 9 10 11 12
/* /* /*
Main part of C batch program ctdli(func_GU, detail_PCB, &det_seg_io_area,qual_ssa); ctdli(func_GHU, mast_PCB, &mast_seg_io_area,qual_ssa); ctdli(func_GHN, mast_PCB, &mast_seg_io_area); ctdli(func_REPL, mast_PCB, &mast_seg_io_area;
} Figure 10. Sample C Language Program (Part 2 of 2)
Notes to Figure 10: 1. The env(IMS) establishes the correct operating environment and the plist(IMS) establishes the correct parameter list when invoked under IMS. The ims.h header file contains declarations for PCB layouts, __pcblist, and the ctdli routine. The PCB layouts define masks for the PCBs that the program uses as structures. These definitions make it possible for the program to check fields in the PCBs. The stdio.h header file contains declarations for sprintf (used to build up the SSA). 2. After IMS has loaded the application program's PSB, IMS gives control to the application program through this entry point. 3. The C run-time sets up the __pcblist values. The order in which you refer to the PCBs must be the same order in which they have been defined in the PSB. (Values other than 10 and 20 can be used, according to the actual key lengths needed.) These declarations can be done using macros, such as:
#define IO_PCB (IO_PCB_TYPE *) (__pcblist[0]) #define mast_PCB (__pcblist[1]) #define detail_PCB (__pcblist[2])
This example assumes that an I/O PCB was passed to the application program. When the program is a batch program, CMPAT=YES must be specified on the PSBGEN statement of PSBGEN so that the I/O PCB is included. Because the I/O PCB is required for a batch program to make system service calls, CMPAT=YES should always be specified for batch programs. 4. Each of these areas defines one of the call functions used by the batch program. Each character string is defined as four alphanumeric characters, with a value assigned for each function. (If the [4]s had been left out, 5 bytes would have been reserved for each constant.) You can define other constants in the same way. Also, you can store standard definitions in a source library and include them by using a #include directive. Instead, you can define these by macros, although each string would have a trailing null ('\0').
35
Coding Programs in C Language

5. The SSA is put into a string (see note 7). You can define a structure, as in COBOL, PL/I, or Pascal, but using sprintf is more convenient. (Remember that C strings have trailing nulls that cannot be passed to IMS.) Note that the string is 1 byte longer than required by IMS to contain the trailing null, which is ignored by IMS. Note also that the numbers in brackets assume that six fields in the SSA are equal to these lengths. 6. The I/O areas that will be used to pass segments to and from the database are defined as structures. 7. The sprintf function is used to fill in the SSA. The %-8.8s format means a left-justified string of exactly eight positions. The %2.2s format means a right-justified string of exactly two positions. Because the ROOT and KEY parts do not change, this can also be coded:
sprintf(qual_ssa, "ROOT (KEY =%-6.6s)", "vvvvv"); /* 12345678 12345678 */
8. This call retrieves data from the database. It contains a qualified SSA. Before you can issue a call that uses a qualified SSA, initialize the data field of the SSA. Before you can issue a call that uses an unqualified SSA, initialize the segment name field. Unlike the COBOL, PL/I, and Pascal interface routines, ctdli also returns the status code as its result. (Blank is translated to 0.) So, you can code:
switch (ctdli(....)) { case 0: ... /* everything ok */ break; case AB: .... break; case IX: ... break; default: }
You can pass only the PCB pointer for DL/I calls in a C program. 9. This is another call with a qualified SSA. 10. This call is an unqualified call that retrieves data from the database. Because it is a Get Hold call, it can be followed by REPL or DLET. 11. The REPL call replaces the data in the segment that was retrieved by the most recent Get Hold call. The data is replaced by the contents of the I/O area that is referenced in the call. 12. The end of the main routine (which can be done by a return statement or exit call) returns control to IMS. | | | |
Binding C Code to the Language Interface Module

IMS provides a language interface module (DFSLI000) that is an interface between IMS and the C language. This module must be made available to the application program at bind time.
Coding a Batch Program in COBOL

The program in Figure 11 is a skeleton batch program that shows you how the parts of an IMS program, written in COBOL, fit together. The numbers to the right of the program refer to the notes that follow the program. This kind of program can run as a batch program or as a batch-oriented BMP.
36
Coding Programs in COBOL

ENVIRONMENT DIVISION . . DATA DIVISION. WORKINGSTORAGE SECTION. 77 FUNCGU 77 FUNCGHU 77 FUNCGN 77 FUNCGHN 77 FUNCGNP 77 FUNCGHNP 77 FUNCREPL 77 FUNCISRT 77 FUNCDLET 77 COUNT 01 UNQUALSSA. 02 SEGNAME 02 FILLER 01 QUALSSAMAST. 02 SEGNAMEM 02 BEGINPARENM 02 KEYNAMEM 02 RELOPERM 02 KEYVALUEM 02 ENDPARENM 01 QUALSSADET. 02 SEGNAMED 02 BEGINPAREND 02 KEYNAMED 02 RELOPERD 02 KEYVALUED 02 ENDPAREND 01 DETSEGIN. 02 02 01 MASTSEGIN. 02 02 LINKAGE SECTION. 01 IOPCB. 02 FILLER 02 IOSTATCODE 02 FILLER 01 DBPCBMAST. 02 MASTDBDNAME 02 MASTSEGLEVEL 02 MASTSTATCODE 02 MASTPROCOPT 02 FILLER 02 MASTSEGNAME 02 MASTLENKFB 02 MASTNUSENSEG 02 MASTKEYFB 01 DBPCBDETAIL. 02 DETDBDNAME 02 DETSEGLEVEL 02 DETSTATCODE 02 DETPROCOPT 02 FILLER 02 DETSEGNAME 02 DETLENKFB 02 DETNUSENSEG 02 DETKEYFB Note 1
PICTURE XXXX VALUE GU . PICTURE XXXX VALUE GHU . PICTURE XXXX VALUE GHN . PICTURE XXXX VALUE GHN . PICTURE XXXX VALUE GNP . PICTURE XXXX VALUE GHNP. PICTURE XXXX VALUE REPL. PICTURE XXXX VALUE ISRT. PICTURE XXXX VALUE DLET. PICTURE S9(5)VALUE +4 COMPUTATIONAL. PICTURE X(08) VALUE PICTURE X VALUE . PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE X(08) X X(08) X(02) X(06) X X(08) X X(08) X(02) X(06) X VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE . 2
ROOTMAST. (. KEYMAST . =. vvvvvv. ). ROOTDET . (. KEYDET . =. vvvvvv. ).
PICTURE X(10). PICTURE XX. PICTURE X(20). PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE PICTURE X(8). XX. XX. XXXX. S9(5) COMPUTATIONAL. X(8). S9(5) COMPUTATIONAL. S9(5) COMPUTATIONAL. XX. X(8). XX. XX. XXXX. S9(5) COMPUTATIONAL. X(8). S9(5) COMPUTATIONAL. S9(5) COMPUTATIONAL. XX. 5
Figure 11. Sample COBOL Program (Part 1 of 2)
37

| PROCEDURE DIVISION USING IOPCB, DBPCBMAST, DBPCBDETAIL | . | . | . | . | CALL CBLTDLI USING FUNCGU, DBPCBDETAIL, | DETSEGIN, QUALSSADET. | . | . | CALL CBLTDLI USING COUNT, FUNCGHU, DBPCBMAST, | MASTSEGIN, QUALSSAMAST. | . | . | CALL CBLTDLI USING FUNCGHN, DBPCBMAST, | MASTSEGIN. | . | . | CALL CBLTDLI USING FUNCREPL, DBPCBMAST, | MASTSEGIN. | . | . | GOBACK. |
Figure 11. Sample COBOL Program (Part 2 of 2)
10 11
Notes to Figure 11: 1. You define each of the DL/I call functions the program uses with a 77-level or 01-level working storage entry. Each picture clause is defined as four alphanumeric characters and has a value assigned for each function. If you want to include the optional parmcount field, you can initialize count values for each type of call. You can also use a COBOL COPY statement to include these standard descriptions in the program. 2. A 9-byte area is set up for an unqualified SSA. Before the program issues a call that requires an unqualified SSA, it moves the segment name to this area. If a call requires two or more SSAs, you may need to define additional areas. 3. A 01-level working storage entry defines each qualified SSA that the application program uses. Qualified SSAs must be defined separately, because the values of the fields are different. 4. A 01-level working storage entry defines I/O areas that are used for passing segments to and from the database. You can further define I/O areas with 02-level entries. You can use separate I/O areas for each segment type, or you can define one I/O area that you use for all segments. 5. A 01-level linkage section entry defines a mask for each of the PCBs that the program requires. The DB PCBs represent both input and output databases. After issuing each DL/I call, the program checks the status code through this linkage. You define each field in the DB PCB so that you can reference it in the program. 6. This is the standard procedure division statement of a batch program. After IMS has loaded the PSB for the program, IMS passes control to the application program. The PSB contains all the PCBs that are defined in the PSB. The coding of USING on the procedure division statement references each of the PCBs by the names that the program has used to define the PCB masks in the linkage section. The PCBs must be listed in the order in which they are defined in the PSB. The example in Figure 11 assumes that an I/O PCB was passed to the application program. When the program is a batch program, CMPAT=YES must be specified on the PSBGEN statement of PSBGEN so that the I/O PCB
38

is included. Because the I/O PCB is required for a batch program to make system service calls, CMPAT=YES should always be specified for batch programs. The entry DLITCBL statement is only used in the main program. Do not use it in called programs. 7. This call retrieves data from the database by using a qualified SSA. Before issuing the call, the program must initialize the key or data value of the SSA so that it specifies the particular segment to be retrieved. The program should test the status code in the DB PCB that was referenced in the call immediately after issuing the call. You can include the parmcount parameter in DL/I calls in COBOL programs, except in the call to the sample status-code error routine. It is never required in COBOL. 8. This is another retrieval call that contains a qualified SSA. 9. This is an unqualified retrieval call. 10. The REPL call replaces the segment that was retrieved in the most recent Get Hold call. The segment is replaced with the contents of the I/O area that is referenced in the call (MAST-SEG-IN). 11. The program issues the GOBACK statement when it has finished processing. | | | | | | | | | | |
Binding COBOL Code to the IMS Language Interface Module

IMS supplies a language interface module (DFSLI000). This module must be bound to the batch program after the program has been compiled. It gives a common interface to IMS. If you use the IMS-supplied procedures (IMSCOBOL or IMSCOBGO), IMS binds the language interface with the application program. IMSCOBOL is a two-step procedure that compiles and binds your program. IMSCOBGO is a three-step procedure that compiles, binds, and executes your program in an IMS batch region. Related Reading: For information on how to use these procedures, see IMS Version 9: Installation Volume 2: System Definition and Tailoring.
Coding a CICS Online Program in COBOL

The programs in this section are skeleton online programs in Enterprise COBOL. They show examples of how to define and set up addressability to the UIB. The numbers to the right of the programs refer to the notes that follow them. This kind of program can run in a CICS environment using DBCTL.
CBL APOST IDENTIFICATION DIVISION. PROGRAMID. CBLUIB. ENVIRONMENT DIVISION. DATA DIVISION. WORKINGSTORAGE SECTION. 77 PSBNAME PIC X(8) VALUE CBLPSB . 77 PCBFUNCTION PIC X(4) VALUE PCB . 77 TERMFUNCTION PIC X(4) VALUE TERM. 77 GHUFUNCTION PIC X(4) VALUE GHU . 77 REPLFUNCTION PIC X(4) VALUE REPL. 77 SSA1 PIC X(9) VALUE AAAA4444 . 77 SUCCESSMESSAGE PIC X(40). 77 GOODSTATUSCODE PIC XX VALUE . 77 GOODRETURNCODE PIC X VALUE LOWVALUE. 01 MESSAGE0. 02 MESSAGE1 PIC X(38). 02 MESSAGE2 PIC XX. 01 DLIIOAREA. NOTES
2 3
39

02 AREA1 PIC X(3). 02 AREA2 PIC X(37). LINKAGE SECTION. COPY DLIUIB. 4,5 01 OVERLAYDLIUIB REDEFINES DLIUIB. 02 PCBADDR USAGE IS POINTER. 02 FILLER PIC XX. 01 PCBADDRESSES. 02 PCBADDRESSLIST USAGE IS POINTER OCCURS 10 TIMES. 01 PCB1. 02 PCB1DBDNAME PIC X(8). 02 PCB1SEGLEVEL PIC XX. 02 PCB1STATUSCODE PIC XX. 02 PCB1PROCOPT PIC XXXX. 6 02 FILLER PIC S9(5) COMP. 02 PCB1SEGNAME PIC X(8). 02 PCB1LENKFB PIC S9(5) COMP. 02 PCB1NUSENSEG PIC S9(5) COMP. 02 PCB1KEYFB PIC X(256). PROCEDURE DIVISION. * SCHEDULE THE PSB AND ADDRESS THE UIB. CALL CBLTDLI USING PCBFUNCTION, PSBNAME, ADDRESS OF DLIUIB. IF UIBFCTR IS NOT EQUAL LOWVALUES THEN * INSERT ERROR DIAGNOSTIC CODE. EXEC CICS RETURN ENDEXEC. SET ADDRESS OF PCBADDRESSES TO PCBADDR. ISSUE DL/I CALL: GET A UNIQUE SEGMENT SET ADDRESS OF PCB1 TO PCBADDRESSLIST(1). CALL CBLTDLI USING GHUFUNCTION, PCB1, DLIIOAREA, SSA1. IF UIBFCTR IS NOT EQUAL GOODRETURNCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. IF PCB1STATUSCODE IS NOT EQUAL GOODSTATUSCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. PERFORM SEGMENT UPDATE ACTIVITY MOVE ...... TO AREA1. MOVE ...... TO AREA2. ISSUE DL/I CALL: REPLACE SEGMENT AT CURRENT POSITION CALL CBLTDLI USING REPLFUNCTION, PCB1, DLIIOAREA, SSA1. IF UIBFCTR IS NOT EQUAL GOODRETURNCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. IF PCB1STATUSCODE IS NOT EQUAL GOODSTATUSCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. RELEASE THE PSB CALL CBLTDLI USING TERMFUNCTION. OTHER APPLICATION FUNCTION EXEC CICS RETURN ENDEXEC. GOBACK.
* * * *
10
* * * *
11,12
Notes to example: 1. You define each of the DL/I call functions the program uses with a 77-level or 01-level working storage entry. Each picture clause is defined as four alphanumeric characters and has a value assigned for each function. If you want to include the optional parmcount field, initialize count values for each type of call. You can also use the COBOL COPY statement to include these standard descriptions in the program. 2. A 9-byte area is set up for an unqualified SSA. Before the program issues a call that requires an unqualified SSA, it can either initialize this area with the
40

segment name or move the segment name to this area. If a call requires two or more SSAs, you may need to define additional areas. An 01-level working storage entry defines I/O areas that are used for passing segments to and from the database. You can further define I/O areas with 02-level entries. You can use separate I/O areas for each segment type, or you can define one I/O area that you use for all segments. The linkage section does not contain BLLCELLS with Enterprise COBOL. The COPY DLIUIB statement will be expanded as shown in Figure 18 on page 79. The field UIBPCBAL is redefined as a pointer variable in order to address the special register of Enterprise COBOL. This field contains the address of an area containing the PCB addresses. Do not alter the addresses in the area.
3.
4. 5. 6.
| | |
7. One PCB layout is defined in the linkage section. The PCB-ADDRESS-LIST occurs n times, where n is greater than or equal to the number of PCBs in the PSB. 8. The PCB call schedules a PSB for your program to use. The address of the DLIUIB parameter returns the address of DLIUIB. 9. This unqualified GHU call retrieves a segment from the database and places it in the I/O area that is referenced by the call. Before issuing the call, the program must initialize the key or data value of the SSA so that it specifies the particular segment to be retrieved. 10. CICS online programs should test the return code in the UIB before testing the status code in the DB PCB. 11. The REPL call replaces the segment that was retrieved in the most recent Get Hold call with the data that the program has placed in the I/O area. 12. The TERM call terminates the PSB the program scheduled earlier. This call is optional and is only issued if a sync point is desired prior to continued processing. The program issues the EXEC CICS RETURN statement when it has finished its processing. If this is a RETURN from the highest-level CICS program, a TERM call and sync point are internally generated by CICS.
41

IDENTIFICATION DIVISION. PROGRAMID. CBLUIB. ENVIRONMENT DIVISION. DATA DIVISION. WORKINGSTORAGE SECTION. 77 PSBNAME PIC X(8) VALUE CBLPSB . 77 PCBFUNCTION PIC X(4) VALUE PCB . 77 TERMFUNCTION PIC X(4) VALUE TERM. 77 GHUFUNCTION PIC X(4) VALUE GHU . 77 REPLFUNCTION PIC X(4) VALUE REPL. 77 SSA1 PIC X(9) VALUE AAAA4444 . 77 SUCCESSMESSAGE PIC X(40). 77 GOODSTATUSCODE PIC XX VALUE . 77 GOODRETURNCODE PIC X VALUE LOWVALUE. 01 MESSAGE. 02 MESSAGE1 PIC X(38). 02 MESSAGE2 PIC XX. 01 DLIIOAREA. 02 AREA1 PIC X(3). 02 AREA2 PIC X(37). LINKAGE SECTION. 01 BLLCELLS. 02 FILLER PIC S9(8) COMP. 02 UIBPTR PIC S9(8) COMP. 02 BPCBPTRS PIC S9(8) COMP. 02 PCB1PTR PIC S9(8) COMP. COPY DLIUIB. 01 PCBPTRS. 02 BPCB1PTR PIC 9(8) COMP. 01 PCB1. 02 PCB1DBDNAME PIC X(8). 02 PCB1SEGLEVEL PIC XX. 02 PCB1STATUSCODE PIC XX. 02 PCB1PROCOPT PIC XXXX. 02 FILLER PIC S9(5) COMP. 02 PCB1SEGNAME PIC X(8). 02 PCB1LENKFB PIC S9(5) COMP. 02 PCB1NUENSEG PIC S9(5) COMP. 02 PCB1KEYFB PIC X(256). PROCEDURE DIVISION. CALL CBLTDLI USING PCBFUNCTION, PSBNAME, UIBPTR IF UIBFCTR IS NOT EQUAL LOWVALUES THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. MOVE UIBPCBAL TO BPCBPTRS. MOVE BPCB1PTR TO PCB1PTR. * ISSUE DL/I CALL: GET A UNIQUE SEGMENT CALL CBLTDLI USING GHUFUNCTION, PCB1, DLIIOAREA, SSA1. SERVICE RELOAD UIBPTR IF UIBFCTR IS NOT EQUAL GOODRETURNCODE THEN * INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. Figure 12. Sample Call-Level OS/V COBOL program (CICS Online) (Part 1 of 2) NOTES
3 4
5,6 7
10
42

IF PCB1STATUSCODE IS NOT EQUAL GOODSTATUSCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. PERFORM SEGMENT UPDATE ACTIVITY MOVE ....... TO AREA1. MOVE ....... TO AREA2. ISSUE DL/I CALL: REPLACE SEGMENT AT CURRENT POSITION CALL CBLTDLI USING REPLFUNCTION, PCB1, DLIIOAREA, SSA1. IF UIBFCTR IS NOT EQUAL GOODRETURNCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. IF PCB1STATUSCODE IS NOT EQUAL GOODSTATUSCODE THEN INSERT ERROR DIAGNOSTIC CODE EXEC CICS RETURN ENDEXEC. RELEASE THE PSB CALL CBLTDLI USING TERMFUNCTION. EXEC CICS RETURN ENDEXEC.
* * *
11
* *
12,13
Figure 12. Sample Call-Level OS/V COBOL program (CICS Online) (Part 2 of 2)
Notes to Figure 12: 1. You define each of the DL/I call functions the program uses with a 77-level or 01-level working storage entry. Each picture clause is defined as four alphanumeric characters and has a value assigned for each function. If you want to include the optional parmcount field, you can initialize count values for each type of call. You can also use the COBOL COPY statement to include these standard descriptions in the program. 2. A 9-byte area is set up for an unqualified SSA. Before the program issues a call that requires an unqualified SSA, it can either initialize this area with the segment name or move the segment name to this area. If a call requires two or more SSAs, you may need to define additional areas. 3. An 01-level working storage entry defines I/O areas that are used for passing segments to and from the database. You can further define I/O areas with 02-level entries. You can use separate I/O areas for each segment type, or you can define one I/O area to use for all segments. 4. The linkage section must start with a definition of this type to provide addressability to a parameter list that will contain the addresses of storage that is outside the working storage of the application program. The first 02-level definition is used by CICS to provide addressability to the other fields in the list. A one-to-one correspondence exists between the other 02-level names and the 01-level data definitions in the linkage section. 5. The COPY DLIUIB statement will be expanded as shown in Figure 18 on page 79. 6. The UIB returns the address of an area that contains the PCB addresses. The definition of PCB pointers is necessary to obtain the actual PCB addresses. Do not alter the addresses in the area. 7. The PCBs are defined in the linkage section. 8. The PCB call schedules a PSB for your program to use. 9. This unqualified GHU call retrieves a segment from the database and places it in the I/O area that is referenced by the call. Before issuing the call, the program must initialize the key or data value of the SSA so that it specifies the particular segment to be retrieved. 10. CICS online programs should test the return code in the UIB before testing the status code in the DB PCB. 11. The REPL call replaces the segment that was retrieved in the most recent Get Hold call with the data that the program has placed in the I/O area.
43

12. The TERM call terminates the PSB that the program scheduled earlier. This call is optional and is only issued if a sync point is desired prior to continued processing. 13. The program issues the EXEC CICS RETURN statement when it has finished its processing. If this is a return from the highest-level CICS program, a TERM call and sync point are internally generated by CICS. | | Related Reading: For more information about installing application programs, see CICS/MVS Installation Guide.
Ensuring Addressability Using the COBOL Optimization Feature (CICS Online Only)
| | | | | If you use the OS/VS COBOL compiler (5740-CB1) with the OPTIMIZE feature, you must use the SERVICE RELOAD compiler control statement in your program to ensure addressability to areas that are defined in the LINKAGE SECTION. If you use the Enterprise COBOL compiler, the SERVICE RELOAD statement is not required. The format of the SERVICE RELOAD statement is:
SERVICE RELOAD fieldname
fieldname is the name of a storage area defined in a 01-level statement in the LINKAGE SECTION. Use the SERVICE RELOAD statement after each statement that modifies addressability to an area in the LINKAGE SECTION. Include the SERVICE RELOAD statement after the label if the statement might cause a branch to another label. If you specify NOOPTIMIZE when compiling your program, you do not need to use the SERVICE RELOAD statement. However, use this statement to ensure that the program will execute correctly if it is compiled using the OPTIMIZE option. For more information on using the SERVICE RELOAD statement, see CICS/ESA Application Programmer's Reference.
Coding a Batch Program in Pascal

Figure 13 on page 45 is a skeleton batch program in Pascal. It shows you how the parts of an IMS program that is written in Pascal fit together. The numbers to the right of the program refer to the notes that follow the program. Restriction: Pascal is not supported by CICS.
44
Coding Programs in Pascal

segment PASCIMS; type CHAR2 CHAR4 CHAR6 CHARn packed array [1..2] of CHAR; packed array [1..4] of CHAR; packed array [1..6] of CHAR; packed array [1..n] of CHAR; DB_PCB_TYPE = record DB_NAME : ALFA; DB_SEG_LEVEL : CHAR2; DB_STAT_CODE : CHAR2; DB_PROC_OPT : CHAR4; FILLER : INTEGER; DB_SEG_NAME : ALFA; DB_LEN_KFB : INTEGER; DB_NO_SENSEG : INTEGER; DB_KEY_FB : CHARn; end; procedure PASCIMS (var SAVE: INTEGER; var DB_PCB_MAST: DB_PCB_TYPE; var DB_PCB_DETAIL : DB_PCB_TYPE); REENTRANT; procedure PASCIMS; type QUAL_SSA_TYPE = record SEG_NAME : ALFA; SEQ_QUAL : CHAR; SEG_KEY_NAME : ALFA; SEG_OPR : CHAR2; SEG_KEY_VALUE: CHAR6; SEG_END_CHAR : CHAR; end; MAST_SEG_IO_AREA_TYPE = record (* Field declarations *) end; DET_SEG_IO_AREA_TYPE = record (* Field declarations *) end; var MAST_SEG_IO_AREA : MAST_SEG_IO_AREA_TYPE; DET_SEG_IO_AREA : DET_SEG_IO_AREA_TYPE; const GU = GU ; GN = GN ; GHU = GHU ; GHN = GHN ; GHNP = GHNP; ISRT = ISRT; REPL = REPL; DLET = DLET; QUAL_SSA = QUAL_SSA_TYPE(ROOT,(,KEY, =, vvvvv,)); UNQUAL_SSA = NAME ; procedure PASTDLI; GENERIC; begin Figure 13. Sample Pascal Program (Part 1 of 2) = = = = NOTES 1 2
6 7
45
Coding Programs in Pascal

PASTDLI(const var var const PASTDLI(const var var const PASTDLI(const var var PASTDLI(const var var end; GU, DB_PCB_DETAIL; DET_SEG_IO_AREA; QUAL_SSA); GHU, DB_PCB_MAST, MAST_SEG_IO_AREA, QUAL_SSA); GHN, DB_PCB_MAST, MAST_SEG_IO_AREA); REPL, DB_PCB_MAST, MAST_SEG_IO_AREA); 9
10
11 12 13
Figure 13. Sample Pascal Program (Part 2 of 2)
Notes to Figure 13: 1. Define the name of the Pascal compile unit. 2. Define the data types that are needed for the PCBs used in your program. 3. Define the PCB data type that is used in your program. 4. Declare the procedure heading for the REENTRANT procedure that is called by IMS. The first word in the parameter list should be an INTEGER, which is reserved for VS Pascal's usage. The rest of the parameters are the addresses of the PCBs that are received from IMS. 5. Define the data types that are needed for the SSAs and I/O areas. 6. Declare the variables used for the I/O areas. 7. Define the constants, such as function codes and SSAs that are used in the PASTDLI DL/I calls. 8. Declare the IMS interface routine by using the GENERIC directive. GENERIC identifies external routines that allow multiple parameter list formats. A GENERIC routine's parameters are declared only when the routine is called. 9. This call retrieves data from the database. It contains a qualified SSA. Before you can issue a call that uses a qualified SSA, you must initialize the data field of the SSA. Before you can issue a call that uses an unqualified SSA, you must initialize the segment name field. 10. This is another call that has a qualified SSA. 11. This call is an unqualified call that retrieves data from the database. Because it is a Get Hold call, it can be followed by a REPL or DLET call. 12. The REPL call replaces the data in the segment that was retrieved by the most recent Get Hold call; the data is replaced by the contents of the I/O area that is referenced in the call. 13. You return control to IMS by exiting from the PASCIMS procedure. You can also code a RETURN statement to exit at another point. | | |
Binding Pascal Code to the IMS Language Interface Module

You must bind your program to the IMS language interface module (DFSLI000) after compiling your program.
Coding a Batch Program in PL/I

Figure 14 is a skeleton batch program in PL/I. It shows you how the parts of an IMS program that is written in PL/I fit together. The numbers to the right of the program refer to the notes that follow. This kind of program can run as a batch program or as a batch-oriented BMP.
46
Coding Programs in PL/I

Restriction: IMS application programs cannot use PL/I multitasking. This is because all tasks operate as subtasks of a PL/I control task when you use multitasking. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
/* */ /* ENTRY POINT */ /* */ DLITPLI: PROCEDURE (IO_PTR_PCB,DB_PTR_MAST,DB_PTR_DETAIL) OPTIONS (MAIN); /* */ /* DESCRIPTIVE STATEMENTS */ /* */ DCL IO_PTR_PCB POINTER; DCL DB_PTR_MAST POINTER; DCL DB_PTR_DETAIL POINTER; DCL FUNC_GU CHAR(4) INIT(GU ); DCL FUNC_GN CHAR(4) INIT(GN ); DCL FUNC_GHU CHAR(4) INIT(GHU ); DCL FUNC_GHN CHAR(4) INIT(GHN ); DCL FUNC_GNP CHAR(4) INIT(GNP ); DCL FUNC_GHNP CHAR(4) INIT(GHNP); DCL FUNC_ISRT CHAR(4) INIT(ISRT); DCL FUNC_REPL CHAR(4) INIT(REPL); DCL FUNC_DLET CHAR(4) INIT(DLET); DCL 1 QUAL_SSA STATIC UNALIGNED, 2 SEG_NAME CHAR(8) INIT(ROOT ), 2 SEG_QUAL CHAR(1) INIT((), 2 SEG_KEY_NAME CHAR(8) INIT(KEY ), 2 SEG_OPR CHAR(2) INIT( =), 2 SEG_KEY_VALUE CHAR(6) INIT(vvvvv), 2 SEG_END_CHAR CHAR(1) INIT()); DCL 1 UNQUAL SSA STATIC UNALIGNED, 2 SEG_NAME_U CHAR(8) INIT(NAME ), 2 BLANK CHAR(1) INIT( ); DCL 1 MAST_SEG_IO_AREA, 2 2 2 DCL 1 DET_SEG_IO_AREA, 2 2 2 DCL 1 IO_PCB BASED (IO_PTR_PCB), 2 FILLER CHAR(10), 2 STAT CHAR(2); Figure 14. Sample PL/I Program (Part 1 of 2) NOTES 1
47

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DCL 1 DB_PCB_MAST BASED (DB_PTR_MAST), 2 MAST_DB_NAME CHAR(8), 2 MAST_SEG_LEVEL CHAR(2), 2 MAST_STAT_CODE CHAR(2), 2 MAST_PROC_OPT CHAR(4), 2 FILLER FIXED BINARY (31,0), 2 MAST_SEG_NAME CHAR(8), 2 MAST_LEN_KFB FIXED BINARY (31,0), 2 MAST_NO_SENSEG FIXED BINARY (31,0), 2 MAST_KEY_FB CHAR(*); DB_PCB_DETAIL BASE (DB_PTR_DETAIL), 2 DET_DB_NAME CHAR(8), 2 DET_SEG_LEVEL CHAR(2), 2 DET_STAT_CODE CHAR(2), 2 DET_PROC_OPT CHAR(4), 2 FILLER FIXED BINARY (31,0), 2 DET_SEG_NAME CHAR(8), 2 DET_LEN_KFB FIXED BINARY (31,0), 2 DET_NO_SENSEG FIXED BINARY (31,0), 2 DET_KEY_FB CHAR(*); THREE FIXED BINARY (31,0) INITIAL(3); FOUR FIXED BINARY (31,0) INITIAL(4); FIVE FIXED BINARY (31,0) INITIAL(5); SIX FIXED BINARY (31,0) INITIAL(6);
DCL 1
DCL DCL DCL DCL /* */ /* MAIN PART OF PL/I BATCH PROGRAM */ /* */ CALL PLITDLI (FOUR,FUNC_GU,DB_PCB_DETAIL,DET_SEG_IO_AREA, QUAL_SSA); IF DET_STAT_CODE = GOOD_STATUS_CODE THEN DO; CALL PLITDLI (FOUR,FUNC_GHU,DB_PCB_MAST,MAST_SEG_IO_AREA,QUAL_SSA); IF MAST_STAT_CODE = GOOD_STATUS_CODE THEN DO; CALL PLITDLI (THREE,FUNC_GHN,DB_PCB_MAST,MAST_SEG_IO_AREA); IF MAST_STAT_CODE = GOOD_STATUS_CODE THEN DO; CALL PLITDLI (THREE,FUNC_REPL,DB_PCB_MAST,MAST_SEG_IO_AREA); IF MAST_STAT_CODE ^= GOOD_STATUS_CODE THEN DO; /* INSERT REPLACE DIAGNOSTIC MESSAGE */ END; ELSE DO; /* INSERT GHN DIAGNOSTIC MESSAGE */ END; ELSE DO; /* INSERT GHU DIAGNOSTIC MESSAGE */ END; ELSE DO; /* INSERT GU DIAGNOSTIC MESSAGE */ END; RETURN; END DLITPLI;
7 8 9 10
11
| | Figure 14. Sample PL/I Program (Part 2 of 2) | Notes to Figure 14: | | | | | | | | | | 1. After IMS has loaded the PSB of the application program, IMS gives control to the application program through this entry point. PL/I programs must pass the pointers to the PCBs, not the names, in the entry statement. The entry statement lists the PCBs that the program uses by the names that it has assigned to the definitions for the PCB masks. The order in which you refer to the PCBs in the entry statement must be the same order in which they have been defined in the PSB. The example in Figure 14 on page 47 assumes that an I/O PCB was passed to the application program. When the program is a batch program, CMPAT=YES must be specified on the PSBGEN statement of PSBGEN so that the I/O PCB
48

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | is included. Because the I/O PCB is required for a batch program to make system service calls, CMPAT=YES should always be specified for batch programs. 2. Each of these areas defines one of the call functions used by the batch program. Each character string is defined as four alphanumeric characters, with a value assigned for each function. You can define other constants in the same way. Also, you can store standard definitions in a source library and include them by using a %INCLUDE statement. 3. A structure definition defines each SSA the program uses. The unaligned attribute is required for SSAs. The SSA character string must reside contiguously in storage. You should define a separate structure for each qualified SSA, because the value of the data field for each SSA is different. 4. The I/O areas that are used to pass segments to and from the database are defined as structures. 5. Level-01 declaratives define masks for the PCBs that the program uses as structures. These definitions make it possible for the program to check fields in the PCBs. 6. This statement defines the parmcount that is required in DL/I calls that are issued from PL/I programs (except for the call to the sample status-code error routine, where it is not allowed). The parmcount is the address of a 4-byte field that contains the number of subsequent parameters in the call. The parmcount is required only in PL/I programs. It is optional in the other languages. The value in parmcount is binary. This example shows how you can code the parmcount parameter when three parameters follow in the call:
DCL THREE FIXED BINARY (31,0) INITIAL(3);
7. This call retrieves data from the database. It contains a qualified SSA. Before you can issue a call that uses a qualified SSA, initialize the data field of the SSA. Before you can issue a call that uses an unqualified SSA, initialize the segment name field. Check the status code after each DL/I call that you issue. Although you must declare the PCB parameters that are listed in the entry statement to a PL/I program as POINTER data types, you can pass either the PCB name or the PCB pointer in DL/I calls in a PL/I program. 8. This is another call that has a qualified SSA. 9. This is an unqualified call that retrieves data from the database. Because it is a Get Hold call, it can be followed by REPL or DLET. 10. The REPL call replaces the data in the segment that was retrieved by the most recent Get Hold call; the data is replaced by the contents of the I/O area referenced in the call. 11. The RETURN statement returns control to IMS.
Binding PL/I Code to the IMS Language Interface Module

IMS provides a language interface module (DFSLI000) which gives a common interface to IMS. This module must be bound to the program. If you use the IMS-supplied procedures (IMSPLI or IMSPLIGO), IMS binds the language interface module to the application program. IMSPLI is a two-step procedure that compiles and binds your program. IMSPLIGO is a three-step procedure that compiles, binds, and executes your program in a DL/I batch region. For information on how to use these procedures, see IMS Version 9: Installation Volume 2: System Definition and Tailoring.
49
Coding a CICS Online Program in PL/I

The program in Figure 15 is a skeleton CICS online program in PL/I. It shows you how to define and establish addressability to the UIB. The numbers to the right of the program refer to the notes that follow. This kind of program can run in a CICS environment using DBCTL.
50

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
PLIUIB: PROC OPTIONS(MAIN); DCL PSB_NAME CHAR(8) STATIC INIT(PLIPSB ); DCL PCB_FUNCTION CHAR(4) STATIC INIT(PCB ); DCL TERM_FUNCTION CHAR(4) STATIC INIT(TERM); DCL GHU_FUNCTION CHAR(4) STATIC INIT(GHU ); DCL REPL_FUNCTION CHAR(4) STATIC INIT(REPL); DCL SSA1 CHAR(9) STATIC INIT(AAAA4444 ); DCL PARM_CT_1 FIXED BIN(31) STATIC INIT(1); DCL PARM_CT_3 FIXED BIN(31) STATIC INIT(3); DCL PARM_CT_4 FIXED BIN(31) STATIC INIT(4); DCL GOOD_RETURN_CODE BIT(8) STATIC INIT(0B); DCL GOOD_STATUS_CODE CHAR(2) STATIC INIT( ); %INCLUDE DLIUIB; DCL 1 PCB_POINTERS BASED(UIBPCBAL), 2 PCB1_PTR POINTER; DCL 1 DLI_IO_AREA, 2 AREA1 CHAR(3), 2 AREA2 CHAR(37); DCL 1 PCB1 BASED(PCB1_PTR), 2 PCB1_DBD_NAME CHAR(8), 2 PCB1_SEG_LEVEL CHAR(2), 2 PCB1_STATUS_CODE CHAR(2), 2 PCB1_PROC_OPTIONS CHAR(4), 2 PCB1_RESERVE_DLI FIXED BIN (31,0), 2 PCB1_SEGNAME_FB CHAR(8), 2 PCB1_LENGTH_FB_KEY FIXED BIN(31,0), 2 PCB1_NUMB_SENS_SEGS FIXED BIN(31,0), 2 PCB1_KEY_FB_AREA CHAR(17); /* SCHEDULE PSB AND OBTAIN PCB ADDRESSES */ CALL PLITDLI (PARM_CT_3,PCB_FUNCTION,PSB_NAME,UIBPTR); IF UIBFCTR = GOOD RETURN CODE THEN DO; /* ISSUE DL/I CALL: GET A UNIQUE SEGMENT */ CALL PLITDLI (PARM_CT_4,GHU_FUNCTION,PCB1,DLI_IO_AREA,SSA1); IF UIBFCTR = GOOD_RETURN_CODE& PCB1_STATUS_CODE = GOOD_STATUS_CODE THEN DO; /* PERFORM SEGMENT UPDATE ACTIVITY */ AREA1 = ......; AREA2 = ......; /* ISSUE DL/I: REPLACE SEGMENT AT CURRENT POSITION */ PLITDLI (PARM_CT_3,REPL_FUNCTION,PCB1,DLI_IO_AREA); IF UIBFCTR ^= GOOD_RETURN_CODE PCB1_STATUS_CODE ^= GOOD_STATUS_CODE THEN DO; /* INSERT REPL ERROR DIAGNOSTIC CODE */ END; END; ELSE DO; /* INSERT GHU ERROR DIAGNOSTIC CODE */ END; END; ELSE DO; /* ANALYZE UIB PROBLEM */ /* ISSUE UIB DIAGNOSTIC MESSAGE */ END; /* RELEASE THE PSB */ CALL PLITDLI(PARM_CT_1,TERM_FUNCTION); EXEC CICS RETURN; END PLIUIB; Figure 15. Sample Call-Level PL/I Program (CICS Online) NOTES 1
3 4 5 6
7 8 9
10
11 12
Notes to Figure 15: 1. Each of these areas defines the DL/I call functions the program uses. Each character string is defined as four alphanumeric characters and has a value assigned for each function. You can define other constants in the same way. You can store standard definitions in a source library and include them by using a %INCLUDE statement.
51

2. A structure definition defines each SSA the program uses. The unaligned attribute is required for SSA. The SSA character string must reside contiguously in storage. If a call requires two or more SSA, you may need to define additional areas. 3. The %INCLUDE DLIUIB statement will be expanded as shown in Figure 19 on page 80. 4. The UIB returns the address of an area containing the PCB addresses. The definition of PCB pointers is necessary to obtain the actual PCB addresses. Do not alter the addresses in the area. 5. The I/O areas that are used to pass segments to and from the database are defined as structures. 6. The PCBs are defined based on the addresses that are passed in the UIB. 7. The PCB call schedules a PSB for your program to use. 8. This unqualified GHU call retrieves a segment from the database. The segment is placed in the I/O area that is referenced in the call. Before issuing the call, the program must initialize the key or data value of the SSA so that it specifies the particular segment to be retrieved. 9. CICS online programs must test the return code in the UIB before testing the status code in the DB PCB. 10. The REPL call replaces the segment that was retrieved in the most recent Get Hold call. The I/O area that is referenced in the call contains the segment to be replaced. 11. The TERM call terminates the PSB that the program scheduled earlier. 12. The program issues the EXEC CICS RETURN statement when it has finished processing. | | Related Reading: For more information about installing application programs, see CICS/MVS Installation Guide.
| |
52
Chapter 3. Defining Application Program Elements

This chapter describes the elements of your application program that are used with IMS. Your application program must define these elements. This section describes formatting DL/I calls for language interfaces and provides language calls information for assembler language, C language, COBOL, Pascal, and PL/I. | The following topics provide additional information: v Formatting DL/I Calls for Language Interfaces v Assembler Language Application Programming on page 54 v C Language Application Programming on page 56 v COBOL Application Programming on page 59 v Pascal Application Programming on page 62 v Application Programming for PL/I on page 64 v Specifying the I/O PCB Mask on page 67 v Specifying the DB PCB Mask on page 70 v v v v v Specifying the AIB Mask on page 73 Specifying the AIB Mask for ODBA Applications on page 74 Specifying the UIB (CICS Online Programs Only) on page 77 Specifying the I/O Areas on page 80 Formatting Segment Search Arguments (SSAs) on page 80
v GSAM Databases on page 85 v The AIBTDLI Interface on page 85 v Language Specific Entry Points on page 86 v v v v Program Communication Block (PCB) Lists on page 89 The AERTLDI interface on page 91 Language Environments on page 91 Special DL/I Situations on page 93
Related Reading: For detailed information on specific parameters for the DL/I calls, see Chapter 11, DL/I Calls for Database Management, on page 219 and Chapter 12, DL/I Calls for System Services, on page 249.
Formatting DL/I Calls for Language Interfaces

When you use DL/I calls in a programming language supported by IMS (High Level Assembler, C language, COBOL, Pascal, and PL/I), you must call the DL/I language interface to initiate the functions specified with the DL/I calls. IMS offers several interfaces for DL/I calls: v A language-independent interface for any programs that are Language Environment conforming (CEETDLI) v A nonspecific language interface for all supported languages (AIBTDLI) v Language-specific interfaces for all supported languages (xxxTDLI)
53
Formatting DL/I Calls for Language Interfaces

Related Reading: Not every DL/I call uses all the parameters shown. For descriptions of the call functions and the parameters they use, see Chapter 11, DL/I Calls for Database Management, on page 219 or Chapter 12, DL/I Calls for System Services, on page 249. Because each programming language uses a different syntax, the format for calling the language interfaces varies.
Assembler Language Application Programming

This section contains the format, parameters, and DL/I call sample formats for IMS application programs in assembler language. In such programs, all DL/I call parameters that are passed as addresses can be passed in a register which, if used, must be enclosed in parentheses.
Format
CALL (2) ASMTDLI,( (1) parmcount, function ,db pcb ,tp pcb C (2) AIBTDLI,( (1) parmcount, (1) ) ,VL function, aib A B A A B
A:
,i/o area , ,ssa ,token ,stat function ,rsa ,rootssa
B:
,i/o area length, i/o area , ,area length,area
54

C:
,psb name, uibptr ,sysserve
Notes: 1 2 Assembler language must use either parmcount or VL. See Chapter 11, DL/I Calls for Database Management, on page 219 and Chapter 12, DL/I Calls for System Services, on page 249 for descriptions of call functions and parameters.
Parameters
parmcount Specifies the address of a 4-byte field in user-defined storage that contains the number of parameters in the parameter list that follows parmcount. Assembler language application programs must use either parmcount or VL. function Specifies the address of a 4-byte field in user-defined storage that contains the call function. The call function must be left-justified and padded with blanks (such as GU ). db pcb Specifies the address of the database PCB to be used for the call. The PCB address must be one of the PCB addresses passed on entry to the application program in the PCB list. tp pcb Specifies the address of the I/O PCB or alternate PCB to be used for the call. The PCB address must be one of the PCB addresses passed on entry to the application program in the PCB list. aib Specifies the address of the application interface block (AIB) in user-defined storage. For more information on AIB, see The AIBTDLI Interface on page 85. i/o area Specifies the address of the I/O area in user-defined storage that is used for the call. The I/O area must be large enough to contain the returned data. i/o area length Specifies the address of a 4-byte field in user-defined storage that contains the I/O area length (specified in binary). area length Specifies the address of a 4-byte field in user-defined storage that contains the length (specified in binary) of the area immediately following it in the parameter list. Up to seven area lengths or area pairs can be specified. area Specifies the address of the area in user-defined storage to be checkpointed. Up to seven area lengths or area pairs can be specified. token Specifies the address of a 4-byte field in user-defined storage that contains a user token.
55

stat function Specifies the address of a 9-byte field in user-defined storage that contains the stat function to be performed. ssa Specifies the address in user-defined storage that contains the SSAs to be used for the call. Up to 15 SSAs can be specified, one of which is rootssa. rootssa Specifies the address of a root segment search argument in user-defined storage. rsa Specifies the address of the area in user-defined storage that contains the record search argument. psb name Specifies the address in user-defined storage of an 8-byte PSB name to be used for the call. uibptr Specifies the address in user-defined storage of the user interface block (UIB). sysserve Specifies the address of an 8-byte field in user-defined storage to be used for the call. VL Signifies the end of the parameter list. Assembler language programs must use either parmcount or VL.
Example of a DL/I Call Format

Using the DL/I AIBTDLI interface:
CALL AIBTDLI,(function,aib,i/o area,ssa1),VL
Using the DL/I language-specific interface:

CALL ASMTDLI,(function,db pcb,i/o area,ssa1),VL
C Language Application Programming

This section contains the format, parameters, and DL/I sample call formats for IMS application programs in C language.
Format
56

(1) rc=CTDLI( parmcount, function ,db pcb ,tp pcb A A B C (2) rc=AIBTDLI( parmcount , function, (1) aib A B (1) CEETDLI( parmcount, function ,db pcb ,i/o pcb A A B ,aib A B );
A:
B:
C:
Notes: 1 See Chapter 11, DL/I Calls for Database Management, on page 219 and Chapter 12, DL/I Calls for System Services, on page 249 for descriptions of call functions and parameters. For AIBTDLI, parmcount is required for C applications.
Parameters
rc This parameter receives the DL/I status or return code. It is a two-character field shifted into the 2 low-order bytes of an integer variable (int). If the status code is two blanks, 0 is placed in the field. You can test the rc parameter with
57

an if statement. For example, if (rc == 'IX'). You can also use rc in a switch statement. You can choose to ignore the value placed in rc and use the status code returned in the PCB instead. parmcount Specifies the name of a fixed binary (31) variable in user-defined storage that contains the number of parameters in the parameter list that follows parmcount. function Specifies the name of a character (4) variable, left justified in user-defined storage, that contains the call function to be used. The call function must be left-justified and padded with blanks (such as GU ). db pcb Specifies the name of a pointer variable that contains the address of the database to be used for the call. The PCB address must be one of the PCB addresses passed on entry to the application program in the PCB list. tp pcb Specifies the name of a pointer variable that contains the address of the I/O PCB or alternate PCB to be used for the call. The PCB address must be one of the PCB addressed passed on entry to the application program in the PCB list. aib Specifies the name of the pointer variable that contains the address of the structure that defines the application interface block (AIB) in user-defined storage. For more information on the AIB, see The AIBTDLI Interface on page 85. i/o area Specifies the name of a pointer variable to a major structure, array, or character string that defines the I/O area in user-defined storage used for the call. The I/O area must be large enough to contain all of the returned data. i/o area length Specifies the name of a fixed binary (31) variable in user-defined storage that contains the I/O area length. area length Specifies the name of a fixed binary (31) variable in user-defined storage that contains the length of the area immediately following it in the parameter list. Up to seven area lengths or area pairs can be specified. area Specifies the name of the pointer variable that contains the address of the structure that defines the user-defined storage to be checkpointed. Up to seven area lengths or area pairs can be specified. token Specifies the name of a character (4) variable in user-defined storage that contains a user token. stat function Specifies the name of a character (9) variable in user-defined storage that contains the stat function to be performed. ssa Specifies the name of a character variable in user-defined storage that contains the SSAs to be used for the call. Up to 15 SSAs can be specified, one of which is rootssa.
58

rootssa Specifies the name of a character variable that defines the root segment search argument in user-defined storage. rsa Specifies the name of a character variable that contains the record search argument for a GU call or where IMS should return the rsa for an ISRT or GN call. psb name Specifies the name of a character (8) variable containing the PSB name to be used for the call. uibptr Specifies the name of a pointer variable that contains the address of the structure that defines the user interface block (UIB) that is used in user-defined storage. sysserve Specifies the name of a character (8) variable string in user-defined storage to be used for the call.
I/O Area
In C, the I/O area can be of any type, including structures or arrays. The ctdli declarations in ims.h do not have any prototype information, so no type checking of the parameters is done. The area may be auto, static, or allocated (with malloc or calloc). You need to give special consideration to C-strings because DL/I does not recognize the C convention of terminating strings with nulls ('\0') Instead of the usual strcpy and strcmp functions, you may want to use memcpy and memcmp.

Using the DL/I CEETDLI interface:
#include <leawi.h> . . . CEETDLI (function,db pcb,i/o area,ssa1);

int rc; . . . rc=AIBTDLI (parmcount,function,aib,i/o area,ssa1);

#include <ims.h> int rc; . . . rc=CTDLI (function,db pcb,i/o area,ssa1);
COBOL Application Programming

This section contains the format, parameters, and DL/I sample call formats for IMS application programs in COBOL.
Format
CALL
59

(1) 'CBLTDLI' USING parmcount, function ,db pcb ,tp pcb A A B C (1) 'AIBTDLI' USING parmcount, (1) 'CEETDLI' USING parmcount, function ,db pcb ,tp pcb A A B ,aib A B function, aib A B .
A:
B:
C:
Notes: 1 See Chapter 11, DL/I Calls for Database Management, on page 219 and Chapter 12, DL/I Calls for System Services, on page 249 for descriptions of call functions and parameters.
Parameters
parmcount Specifies the identifier of a usage binary (4) byte data item in user-defined storage that contains the number of parameters in the parameter list that follows parmcount. function Specifies the identifier of a usage display (4) byte data item, left justified in
60

user-defined storage that contains the call function to be used. The call function must be left-justified and padded with blanks (such as GU ). db pcb Specifies the identifier of the database PCB group item from the PCB list that is passed to the application program on entry. This identifier will be used for the call. tp pcb Specifies the identifier of the I/O PCB or alternate PCB group item from the PCB list that is passed to the application program on entry. This identifier will be used for the call. aib Specifies the identifier of the group item that defines the application interface block (AIB) in user-defined storage. For more information on the AIB, see The AIBTDLI Interface on page 85. i/o area Specifies the identifier of a major group item, table, or usage display data item that defines the I/O area length in user-defined storage used for the call. The I/O area must be large enough to contain all of the returned data. i/o area length Specifies the identifier of a usage binary (4) byte data item in user-defined storage that contains the I/O area length (specified in binary). area length Specifies the identifier of a usage binary (4) byte data item in user-defined storage that contains the length (specified in binary) of the area immediately following it in the parameter list. Up to seven area lengths or area pairs can be specified. area Specifies the identifier of the group item that defines the user-defined storage to be checkpointed. Up to seven area lengths or area pairs can be specified. token Specifies the identifier of a usage display (4) byte data item in user-defined storage that contains a user token. stat function Specifies the identifier of a usage display (9) byte data item in user-defined storage that contains the stat function to be performed. ssa Specifies the identifier of a usage display data item in user-defined storage that contains the SSAs to be used for the call. Up to 15 SSAs can be specified, one of which is rootssa. rootssa Specifies the identifier of a usage display data item that defines the root segment search argument in user-defined storage. rsa Specifies the identifier of a usage display data item that contains the record search argument. psb name Specifies the identifier of a usage display (8) byte data item containing the PSB name to be used for the call. uibptr Specifies the identifier of the group item that defines the user interface block (UIB) that is used in user-defined storage.
61

sysserve Specifies the identifier of a usage display (8) byte data item in user-defined storage to be used for the call.

CALL 'CEETDLI' USING function,db pcb,i/o area,ssa1.

CALL 'AIBTDLI' USING function,aib,i/o area,ssa1.

CALL 'CBLTDLI' USING function,db pcb,i/o area,ssa1.
Pascal Application Programming

Thissection contains the format, parameters, and DL/I sample call formats for IMS application programs in Pascal.
Format
PASTDLI ( A ,VAR ,VAR db pcb tp pcb B B C AIBTDLI ( A , D VAR aib, B C );
A:
(1) CONST CONST parmcount , function
B:
,VAR i/o area , ,VAR ssa ,CONST token ,CONST stat function ,VAR rsa ,VAR rootssa
62

C:
,VAR i/o area length, VAR i/o area , ,VAR area length,VAR area
D:
,VAR psb name, VAR uibptr ,VAR sysserve
Parameters
parmcount Specifies the name of a fixed binary (31) variable in user-defined storage that contains the number of parameters in the parameter list that follows parmcount. function Specifies the name of a character (4) variable, left justified in user-defined storage, that contains the call function to be used. The call function must be left-justified and padded with blanks (such as GU ). db pcb Specifies the name of a pointer variable that contains the address of the database PCB defined in the call procedure statement. tp pcb Specifies the name of a pointer variable that contains the address of the I/O PCB or alternate PCB defined in the call procedure statement. aib Specifies the name of the pointer variable that contains the address of the structure that defines the application interface block (AIB) in user-defined storage. For more information on the AIB, see The AIBTDLI Interface on page 85. i/o area Specifies the name of a pointer variable to a major structure, array, or character string that defines the I/O area in user-defined storage used for the call. The I/O area must be large enough to contain all of the returned data. i/o area length Specifies the name of a fixed binary (31) variable in user-defined storage that contains the I/O area length. area length Specifies the name of a fixed binary (31) variable in user-defined storage that contains the length of the area immediately following it in the parameter list. Up to seven area lengths or area pairs can be specified. area Specifies the name of the pointer variable that contains the address of the
63

structure that defines the user-defined storage to be checkpointed. Up to seven area lengths or area pairs can be specified. token Specifies the name of a character (4) variable in user-defined storage that contains a user token. stat function Specifies the name of a character (9) variable in user-defined storage that contains the stat function to be performed. ssa Specifies the name of a character variable in user-defined storage that contains the SSAs to be used for the call. Up to 15 SSAs can be specified, one of which is rootssa. rootssa Specifies the name of a character variable that defines the root segment search argument in user-defined storage. rsa Specifies the name of a character variable that contains the record search argument. psb name Specifies the name of a character (8) variable containing the PSB name to be used for the call. uibptr Specifies the name of a pointer variable that contains the address of the structure that defines the user interface block (UIB) that is used in user-defined storage. sysserve Specifies the name of a character (8) variable string in user-defined storage to be used for the call.

AIBTDLI(CONST function, VAR aib, VAR i/o area, VAR ssa1);

PASTDLI(CONST function, VAR db pcb, VAR i/o area, VAR ssa1);
Application Programming for PL/I

This section contains the format, parameters, and DL/I sample call formats for IMS application programs in PL/I. Exception: For the PLITDLI interface, all parameters except parmcount are indirect pointers; for the AIBTDLI interface, all parameters are direct pointers.
Format
64

CALL PLITDLI ( parmcount, function ,db pcb ,tp pcb A A B C AIBTDLI ( parmcount, function, aib A B (1) CEETDLI ( parmcount, function ,db pcb ,tp pcb A A B ,aib A B );
A:
B:
C:
Parameters
parmcount Specifies the name of a fixed binary (31-byte) variable that contains the number of arguments that follow parmcount.
65

function Specifies the name of a fixed-character (4-byte) variable left-justified, blank padded character string containing the call function to be used (such as GU
).
db pcb Specifies the structure associated with the database PCB to be used for the call. This structure is based on a PCB address that must be one of the PCB addresses passed on entry to the application program. tp pcb Specifies the structure associated with the I/O PCB or alternate PCB to be used for the call. aib Specifies the name of the structure that defines the AIB in your application program. For more information on the AIB, see The AIBTDLI Interface on page 85. i/o area Specifies the name of the I/O area used for the call. The I/O area must be large enough to contain all the returned data. i/o area length Specifies the name of a fixed binary (31) variable that contains the I/O area length. area length Specifies the name of a fixed binary (31) variable that contains the length of the area immediately following it in the parameter list. Up to seven area lengths or area pairs can be specified. area Specifies the name of the area to be checkpointed. Up to seven area lengths or area pairs can be specified. token Specifies the name of a character (4) variable that contains a user token. stat function Specifies the name of a character (9) variable string containing the stat function to be performed. ssa Specifies the name of a character variable that contains the SSAs to be used for the call. Up to 15 SSAs can be specified, one of which is rootssa. rootssa Specifies the name of a character variable that contains a root segment search argument. rsa Specifies the name of a character variable that contains the record search argument. psb name Specifies the name of a character (8) containing the PSB name to be used for the call. uibptr Specifies the name of the user interface block (UIB). sysserve Specifies the name of a character (8) variable character string to be used for the call.
66

CALL CEETDLI (parmcount,function,db pcb,i/o area,ssa1);

CALL AIBTDLI (parmcount,function,aib,i/o area,ssa1);

%INCLUDE CEEIBMAW; CALL PLITDLI (parmcount,function,db pcb,i/o area,ssa1);
Specifying the I/O PCB Mask

After your program issues a call with the I/O Program Communications Block (I/O PCB), IMS returns information about the results of the call to the I/O PCB. To determine the results of the call, your program must check the information that IMS returns. Issuing a system service call requires an I/O PCB. Because the I/O PCB resides outside your program, you must define a mask of the PCB in your program to check the results of IMS calls. The mask must contain the same fields, in the same order, as the I/O PCB. Your program can then refer to the fields in the PCB through the PCB mask. Table 14 shows the fields that the I/O PCB contains, their lengths, and the applicable environment for each field.
Table 14. I/O PCB Mask Descriptor Logical terminal name Reserved for IMS Status code
3 2 1
Byte Length 8 2 2 Date

4
DB/DC X X X X X X X X X X X X X
DBCTL
DCCTL X X
DB Batch
TM Batch
X X X X X X X X X X X
4-Byte Local date and time
2 2 4 8
Time
Input message sequence number 5 Message output descriptor name Userid

7 8 6
8 8 Date Time UTC Offset 4 6 2 1 3
Group name 12-Byte Time Stamp9
Userid Indicator10 Reserved for IMS

2
Notes: 1. Logical Terminal Name

67
I/O PCB Mask

This field contains the name of the terminal that sent the message. When your program retrieves an input message, IMS places the name of the logical terminal that sent the message in this field. When you want to send a message back to this terminal, you refer to the I/O PCB when you issue the ISRT call, and IMS takes the name of the logical terminal from the I/O PCB as the destination. 2. Reserved for IMS These fields are reserved. 3. Status Code IMS places the status code describing the result of the DL/I call in this field. IMS updates the status code after each DL/I call that the program issues. Your program should always test the status code after issuing a DL/I call. The three status code categories are: v Successful status codes or status codes with exceptional but valid conditions. This category does not contain errors. If the call was completely successful, this field contains blanks. Many of the codes in this category are for information only. For example, a QC status code means that no more messages exist in the message queue for the program. When your program receives this status code, it should terminate. v Programming errors. The errors in this category are usually ones that you can correct. For example, an AD status code indicates an invalid function code. v I/O or system errors. For the second and third categories, your program should have an error routine that prints information about the last call that was issued before program termination. Most installations have a standard error routine that all application programs at the installation use. 4. Local Date and Time The current local date and time are in the prefix of all input messages except those originating from non-message-driven BMPs. The local date is a packed-decimal, right-aligned date, in the format yyddd. The local time is a packed-decimal time in the format hhmmsst. The current local date and time indicate when IMS received the entire message and enqueued it as input for the program, rather than the time that the application program received the message. To obtain the application processing time, you must use the time facility of the programming language you are using. For a conversation, for an input message originating from a program, or for a message received using Multiple System Coupling (MSC), the time and date indicate when the original message was received from the terminal. 5. Input Message Sequence Number The input message sequence number is in the prefix of all input messages except those originating from non-message-driven BMPs. This field contains the sequence number IMS assigned to the input message. The number is binary. IMS assigns sequence numbers by physical terminal, which are continuous since the time of the most recent IMS startup. 6. Message Output Descriptor Name You only use this field when you use MFS. When you issue a GU call with a message output descriptor (MOD), IMS places its name in this area. If your program encounters an error, it can change the format of the screen and send an error message to the terminal by using this field. To do this, the program must change the MOD name by including the MOD name parameter on an ISRT or PURG call.
68
I/O PCB Mask

Although MFS does not support APPC, LU 6.2 programs can use an interface to emulate MFS. For example, the application program can use the MOD name to communicate with IMS to specify how an error message is to be formatted. Related Reading: For more information on the MOD name and the LTERM interface, see IMS Version 9: Administration Guide: Transaction Manager. 7. Userid The use of this field is connected with RACF signon security. If signon is not active in the system, this field contains blanks. If signon is active in the system, the field contains one of the following: v The user's identification from the source terminal. v The LTERM name of the source terminal if signon is not active for that terminal. v The authorization ID. For batch-oriented BMPs, the authorization ID is dependent on the value specified for the BMPUSID= keyword in the DFSDCxxx PROCLIB member: If BMPUSID=USERID is specified, the value from the USER= keyword on the JOB statement is used. If USER= is not specified on the JOB statement, the program's PSB name is used. If BMPUSID=PSBNAME is specified, or if BMPUSID= is not specified at all, the program's PSB name is used. 8. Group Name The group name, which is used by DB2 to provide security for SQL calls, is created through IMS transactions. Three instances that apply to the group name are: v If you use RACF and SIGNON on your IMS system, the RACROUTE SAF (extract) call returns an eight-character group name. v If you use your own security package on your IMS system, the RACROUTE SAF call returns any eight-character name from the package and treats it as a group name. If the RACROUTE SAF call returns a return code of 4 or 8, a group name was not returned, and IMS blanks out the group name field. v If you use LU 6.2, the transaction header can contain a group name. Related Reading: For more information about LU 6.2, see IMS Version 9: Administration Guide: Transaction Manager. 9. 12-Byte Time Stamp This field contains the current date and time fields, but in the IMS internal packed-decimal format. The time stamp has the following parts: Date yyyydddf This packed-decimal date contains the year (yyyy), day of the year (ddd), and a valid packed-decimal + sign such as (f). Time hhmmssthmiju This packed-decimal time consists of hours, minutes, and seconds (hhmmss) and fractions of the second to the microsecond (thmiju). No packed-decimal sign is affixed to this part of the time stamp. UTC Offset aqq$
69
I/O PCB Mask

The packed-decimal UTC offset is prefixed by 4 bits of attributes (a). If the 4th bit of (a) is 0, the time stamp is UTC; otherwise, the time stamp is local time. The control region parameter, TSR=(U/L), specified in the DFSPBxxx PROCLIB member, controls the representation of the time stamp with respect to local time versus UTC time. The offset value (qq$) is the number of quarter hours of offset to be added to UTC or local time to convert to local or UTC time respectively. The offset sign ($) follows the convention for a packed-decimal plus or minus sign. Field 4 on page 68 always contains the local date and time. Related Reading: For a more detailed description of the internal packed-decimal time-format, see IMS Version 9: Database Recovery Control (DBRC) Guide and Reference. 10. Userid Indicator The Userid Indicator is provided in the I/O PCB and in the response to the INQY call. The Userid Indicator contains one of the following: v U - The user's identification from the source terminal during signon v L - The LTERM name of the source terminal if signon is not active v P - The PSBNAME of the source BMP or transaction v O - Other name The value contained in the Userid Indicator field indicates the contents of the userid field.
Specifying the DB PCB Mask

IMS describes the results of the calls your program issues in the DB PCB that is referenced in the call. To determine the success or failure of the DL/I call, the application program includes a mask of the DB PCB and then references the fields of the DB PCB through the mask. A DB PCB mask must contain the fields shown in Table 15. (Your program can look at, but not change, the fields in the DB PCB.) The fields in your DB PCB mask must be defined in the same order and with the same length as the fields shown here. When you code the DB PCB mask, you also give it a name, but the name is not part of the mask. You use the name (or the pointer, for PL/I) when you reference each of the PCBs your program processes. A GSAM DB PCB mask is slightly different from other DB PCB masks. Related Reading: For more information about GSAM DB PCB Masks, see GSAM Databases on page 85. Of the nine fields, only five are important to you as you construct the program. These are the fields that give information about the results of the call. They are the segment level number, status code, segment name, length of the key feedback area, and key feedback area. The status code is the field your program uses most often to find out whether the call was successful. The key feedback area contains the data from the segments you have specified; the level number and segment name help you determine the segment type you retrieved after an unqualified GN or GNP call, or they help you determine your position in the database after an error or unsuccessful call.
70

Table 15. DB PCB Mask Descriptor Database name
3 4 1 2
Byte Length 8 2 2 4 4 8 4 4 var length

5
DB/DC X X X X X X X X X
DBCTL X X X X X X X X X
DCCTL
DB Batch X X X X X X X X X
TM Batch
Segment level number Status code
Processing options Reserved for IMS Segment name

6
Length of key feedback area 7 Number of sensitive segments 8 Key feedback area
9
Notes: 1. Database Name This contains the name of the database. This field is 8 bytes long and contains character data. 2. Segment Level Number This field contains numeric character data. It is 2 bytes long and right-justified. When IMS retrieves the segment you have requested, IMS places the level number of that segment in this field. If you are retrieving several segments in a hierarchic path with one call, IMS places the number of the lowest-level segment retrieved. If IMS is unable to find the segment that you request, it gives you the level number of the last segment it encounters that satisfied your call. 3. Status Code After each DL/I call, this field contains the two-character status code that describes the results of the DL/I call. IMS updates this field after each call and does not clear it between calls. The application program should test this field after each call to find out whether the call was successful. When the program is initially scheduled, this field contains a data-availability status code, which indicates any possible access constraint based on segment sensitivity and processing options. Related Reading: For more information on these status codes, seeINIT Call on page 261. During normal processing, four categories of status codes exist: v Successful or exceptional but valid conditions. If the call was completely successful, this field contains blanks. Many of the codes in this category are for information only. For example, GB means that IMS has reached the end of the database without satisfying the call. This situation is expected in sequential processing and is not usually the result of an error. v Errors in the program. For example, AK means that you have included an invalid field name in a segment search argument (SSA). Your program should have error routines available for these status codes. If IMS returns an error status code to your program, your program should terminate. You can then find the problem, correct it, and restart your program.
71

v I/O or system error. For example, an AO status code means that there has been an I/O error concerning OSAM, BSAM, or VSAM. If your program encounters a status code in this category, it should terminate immediately. This type of error cannot normally be fixed without a system programmer, database administrator, or system administrator. v Data-availability status codes. These are returned only if your program has issued the INIT call indicating that it is prepared to handle such status codes. Status Code Explanations in IMS Version 9: Messages and Codes, Volume 1 describes possible causes and corrections in more detail. 4. Processing Options This is a 4-byte field containing a code that tells IMS what type of calls this program can issue. It is a security mechanism in that it can prevent a particular program from updating the database, even though the program can read the database. This value is coded in the PROCOPT parameter of the PCB statement when the PSB for the application program is generated. The value does not change. 5. Reserved for IMS This 4-byte field is used by IMS for internal linkage. It is not used by the application program. 6. Segment Name After each successful call, IMS places in this field the name of the last segment that satisfied the call. When a retrieval is successful, this field contains the name of the retrieved segment. When a retrieval is unsuccessful, this field contains the last segment along the path to the requested segment that would satisfy the call. The segment name field is 8 bytes long. When a program is initially scheduled, the name of the database type is put in the SEGNAME field. For example, the field contains DEDB when the database type is DEDB; GSAM when the database type is GSAM; HDAM, or PHDAM when the database type is HDAM or PHDAM. 7. Length of Key Feedback Area This is a 4-byte binary field that gives the current length of the key feedback area. Because the key feedback area is not usually cleared between calls, the program needs to use this length to determine the length of the relevant current concatenated key in the key feedback area. 8. Number of Sensitive Segments This is a 4-byte binary field that contains the number of segment types in the database to which the application program is sensitive. 9. Key Feedback Area At the completion of a retrieval or ISRT call, IMS places the concatenated key of the retrieved segment in this field. The length of the key for this request is given in the 4-byte 7 field. If IMS is unable to satisfy the call, the key feedback area contains the key of the segment at the last level that was satisfied. A segment's concatenated key is made up of the keys of each of its parents and its own key. Keys are positioned left to right, starting with the key of the root segment and following the hierarchic path. IMS does not normally clear the key feedback area. IMS sets this length of the key feedback area to indicate the portion of the area that is valid at the completion of each call. Your program should not use the content of the key feedback area that is not included in the key feedback area length.
72
Specifying the AIB Mask

The application interface block (AIB) is used by your program to communicate with IMS, when your application does not have a PCB address or the call function does not use a PCB. The AIB mask enables your program to interpret the control block defined. The AIB structure must be defined in working storage, on a fullword boundary, and initialized according to the order and byte length of the fields as shown in Table 16. The tables notes describe the contents of each field.
Table 16. AIB Fields Descriptor AIB identifier
1
Byte Length 8 4
3
DB/DC X X X X
DBCTL DCCTL X X X X X X X X
DB Batch X X X X
TM Batch X X X X
DFSAIB allocated length 2 Subfunction code Resource name Reserved

5 4
8 8 16 4 4 12
Maximum output area length 6 Output area length used 7 Reserved

8 9 10 11
X X
X X
X X
X X
X X
Return code Reason code
4 4 4 4 48
12
X X X X
X X
X X X
X X
X X
Error code extension Resource address Reserved

13
Notes: 1. AIB Identifier (AIBID) This 8-byte field contains the AIB identifier. You must initialize AIBID in your application program to the value DFSAIB before you issue DL/I calls. This field is required. When the call is completed, the information returned in this field is unchanged. 2. DFSAIB Allocated Length (AIBLEN) This field contains the actual 4-byte length of the AIB as defined by your program. You must initialize AIBLEN in your application program before you issue DL/I calls. The minimum length required is 128 bytes. When the call is completed, the information returned in this field is unchanged. This field is required. 3. Subfunction Code (AIBSFUNC) This 8-byte field contains the subfunction code for those calls that use a subfunction. You must initialize AIBSFUNC in your application program before you issue DL/I calls. When the call is completed, the information returned in this field is unchanged. 4. Resource Name (AIBRSNM1) This 8-byte field contains the name of a resource. The resource varies depending on the call. You must initialize AIBRSNM1 in your application
73

program before you issue DL/I calls. When the call is complete, the information returned in this field is unchanged. This field is required. For PCB related calls where the AIB is used to pass the PCB name instead of passing the PCB address in the call list, this field contains the PCB name. The PCB name for the I/O PCB is IOPCB . The PCB name for other types of PCBs is defined in the PCBNAME= parameter in PSBGEN. 5. Reserved This 16-byte field is reserved. 6. Maximum Output Area Length (AIBOALEN) This 4-byte field contains the length of the output area in bytes that was specified in the call list. You must initialize AIBOALEN in your application program for all calls that return data to the output area. When the call is completed, the information returned in this area is unchanged. 7. Used Output Area Length (AIBOAUSE) This 4-byte field contains the length of the data returned by IMS for all calls that return data to the output area. When the call is completed this field contains the length of the I/O area used for this call. 8. Reserved This 12-byte field is reserved. 9. Return code (AIBRETRN) When the call is completed, this 4-byte field contains the return code. 10. Reason Code (AIBREASN) When the call is completed, this 4-byte field contains the reason code. 11. Error Code Extension (AIBERRXT) This 4-byte field contains additional error information depending on the return code in AIBRETRN and the reason code in AIBREASN. 12. Resource Address (AIBRSA1) When the call is completed, this 4-byte field contains call-specific information. For PCB related calls where the AIB is used to pass the PCB name instead of passing the PCB address in the call list, this field returns the PCB address. 13. Reserved This 48-byte field is reserved. The application program can use the returned PCB address, when available, to inspect the status code in the PCB and to obtain any other information needed by the application program. Related Reading: For more information about the return and reason codes, see IMS Version 9: Messages and Codes, Volume 1.
Specifying the AIB Mask for ODBA Applications

Table 17 describes the fields for specifying the application interface block (AIB) mask for ODBA applications. describe the contents of each field. The notes that follow describe the contents of each field.
Table 17. AIB Fields for Use of ODBA Applications AIB Fields AIB identifier Byte Length 8 DB/DC X IMS DB X DCCTL X DB Batch X TM Batch X
74

Table 17. AIB Fields for Use of ODBA Applications (continued) AIB Fields DFSAIB allocated length Subfunction code Resource name #1 Resource name #2 Reserved Maximum output area length Output area length used Reserved Return code Reason code Error code extension Resource address #1 Resource address #2 Resource address #3 Reserved Reserved for ODBA Byte Length 4 8 8 8 8 4 4 12 4 4 4 4 4 4 40 136 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 DB/DC X X X IMS DB X X X DCCTL X X X DB Batch X X X TM Batch X X X
Notes for AIB Fields for Use of ODBA Applications: 1. AIB Identifier (AIBID) This 8-byte field contains the AIB identifier. You must initialize AIBID in your application program to the value DFSAIB before you issue DL/I calls. This field is required. When the call is completed, the information returned in this field is unchanged. 2. DFSAIB Allocated Length (AIBLEN) This field contains the actual 4-byte length of the AIB as defined by your program. You must initialize AIBLEN in your application program before you issue DL/I calls. The minimum length required is 264 bytes for ODBA. When the call is completed, the information returned in this field is unchanged. This field is required. 3. Subfunction Code (AIBSFUNC) This 8-byte field contains the subfunction code for those calls that use a subfunction. You must initialize AIBSFUNC in your application program before you issue DL/I calls. When the call is completed, the information returned in this field is unchanged. 4. Resource Name (AIBRSNM1) #1 This 8-byte field contains the name of a resource. The resource varies depending on the call. You must initialize AIBRSNM1 in your application program before you issue DL/I calls. When the call is complete, the information returned in this field is unchanged. This field is required. For PCB related calls where the AIB is used to pass the PCB name instead of passing the PCB address in the call list, this field contains the PCB name. The PCB name for the I/O PCB is IOPCB . The PCB name for other types of PCBs is defined in the PCBNAME= parameter in PSBGEN.
75

5. Resource Name (AIBRSNM2) #2 Specify a 4-character ID of ODBA startup table DFSxxxx0, where xxxx is a four-character ID. 6. Reserved This 8-byte field is reserved. 7. Maximum Output Area Length (AIBOALEN) This 4-byte field contains the length of the output area in bytes that was specified in the call list. You must initialize AIBOALEN in your application program for all calls that return data to the output area. When the call is completed, the information returned in this area is unchanged. 8. Used Output Area Length (AIBOAUSE) This 4-byte field contains the length of the data returned by IMS for all calls that return data to the output area. When the call is completed this field contains the length of the I/O area used for this call. 9. Reserved This 12-byte field is reserved. 10. Return code (AIBRETRN) When the call is completed, this 4-byte field contains the return code. 11. Reason Code (AIBREASN) When the call is completed, this 4-byte field contains the reason code. 12. Error Code Extension (AIBERRXT) This 4-byte field contains additional error information depending on the return code in AIBRETRN and the reason code in AIBREASN. 13. Resource Address (AIBRSA1) #1 When the call is completed, this 4-byte field contains call-specific information. For PCB related calls where the AIB is used to pass the PCB name instead of passing the PCB address in the call list, this field returns the PCB address. 14. Resource Address (AIBRSA2) #2 This 4-byte field is reserved for ODBA. 15. Resource Address (AIBRSA3) #3 This 4-byte token, returned on the APSB call, is required for subsequent DLI calls and the DPSB call related to this thread. 16. Reserved This 40-byte field is reserved. 17. Reserved for ODBA This 136-byte field is reserved for ODBA The application program can use the returned PCB address, when available, to inspect the status code in the PCB and to obtain any other information needed by the application program. COBOL AIB Mask Example
01 AIB 02 AIBRID 02 AIBRLEN 02 AIBRSFUNC 02 AIBRSNM1 02 AIBRSNM2 02 AIBRESV1 02 AIBOALEN 02 AIBOAUSE PIC PIC PIC PIC PIC PIC PIC PIC x(8). 9(9) USAGE BINARY. x(8). x(8). x(8). x(8). 9(9) USAGE BINARY. 9(9) USAGE BINARY.
76

02 02 02 02 02 02 02 02 02 02 02 02 02 AIBRESV2 AIBRETRN AIBREASN AIBERRXT AIBRESA1 AIBRESA2 AIBRESA3 AIBRESV4 AIBRSAVE AIBRTOKN AIBRTOKC AIBRTOKV AIBRTOKA PIC x(12). PIC 9(9) USAGE BINARY. PIC 9(9) USAGE BINARY. PIC 9(9) USAGE BINARY. USAGE POINTER. USAGE POINTER. USAGE POINTER. PIC x(40). OCCURS 18 TIMES USAGE POINTER. OCCURS 6 TIMES USAGE POINTER. PIC x(16). PIC x(16). OCCURS 2 TIMES PIC 9(9) USAGE BINARY.
Assembler AIB Mask Example

DFSAIB AIBID AIBLEN AIBSFUNC AIBRSNM1 AIBRSVM2 AIBOALEN AIBOAUSE DSECT DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS EQU DS DS DS DS DS EQU CL8DFSAIB F CL8 CL8 CL8 2F F F 2F H H F F F A A A 10F *-DFSAIB 18F 6F CL16 XL16 2F *-DFSAIB
AIBRETRN AIBREASN AIBRRXT AIBRSA1 AIBRSA2 AIBRSA3 AIBLL AIBSAVE AIBTOKN AIBTOKC AIBTOKV AIBTOKA AIBAERL
Specifying the UIB (CICS Online Programs Only)

The interface between your CICS online program and DL/I passes additional information to your program in a user interface block (UIB). The UIB contains the address of the PCB list and any return codes your program must examine before checking the status code in the DB PCB. When you issue the PCB call to obtain a PSB for your program, a UIB is created for your program. As with any area outside your program, you must include a definition of the UIB and establish addressability to it. CICS provides a definition of the UIB for all programming languages: v In COBOL programs, use the COPY DLIUIB statement (Figure 16 on page 78 for VS COBOL II, or Figure 17 for OS/VS COBOL). Coding a CICS Online Program in COBOL on page 39 shows how to establish addressability to the UIB. Figure 18 on page 79 shows the fields defined when you use the COBOL COPY DLIUIB statement. v In PL/I programs, use a %INCLUDE DLIUIB statement (Figure 19 on page 80). Coding a CICS Online Program in PL/I on page 50 shows how to establish addressability to the UIB.
77

v In assembler language programs, use the DLIUIB macro (Figure 20 on page 80). Coding a CICS Online Program in Assembler Language on page 32 shows how to establish addressability to the UIB. Three fields in the UIB are important to your program: UIBPCBAL, UIBFCTR, and UIBDLTR. UIBPCBAL contains the address of the PCB address list. Through it you can obtain the address of the PCB you want to use. Your program must check the return code in UIBFCTR (and possibly UIBDLTR) before checking the status code in the DB PCB. If the contents of UIBFCTR and UIBDLTR are not null, the content of the status code field in the DB PCB is not meaningful. The return codes are described in Chapter 16, CICS-DL/I User Interface Block Return Codes, on page 377. Immediately after the statement that defines the UIB in your program, you must define the PCB address list and the PCB mask. Figure 16 provides an example of using the COPY DLIUIB statement in a VS COBOL II program:
LINKAGE SECTION. 01 COPY DLIUIB. OVERLAY-DLIUIB REDEFINES DLIUIB. 02 PCBADDR USAGE IS POINTER. 02 FILLER PIC XX.
01
PCB-ADDRESSES. 02 PCB-ADDRESS-LIST USAGE IS POINTER OCCURS 10 TIMES. 01 PCB1. 02 PCB1-DBD-NAME PIC X(8). 02 PCB1-SEG-LEVEL PIC XX. . . . Figure 16. Defining the UIB, PCB Address List, and the PCB Mask for VS COBOL II
Figure 17 provides an example of using the COPY DLIUIB statement in an OS/VS COBOL program.
LINKAGE SECTION. 01 BLL CELLS. 02 FILLER 02 UIB-PTR 02 PCB-LIST-PTR 02 PCB1-PTR COPY DLIUIB. 01 PCB-ADDRESS-LIST. 02 PCB1-LIST-PTR PIC S9(8) COMP. 01 PCB1. 02 PCB1-DBD-NAME PIC X(8). 02 PCB1-SEG-LEVEL PIC XX. . . . Figure 17. Defining the UIB, PCB Address List, and the PCB Mask for OS/VS COBOL
PIC PIC PIC PIC
S9(8) S9(8) S9(8) S9(8)
COMP. COMP. COMP. COMP.
78

Figure 18 provides an example of using the COBOL COPY DLIUIB statement.
01 * * 02 * 03 UIBFCTR PIC X. 88 FCNORESP 88 FCNOTOPEN 88 FCINVREQ 88 FCINVPCB UIBDLTR PIC X. 88 DLPSBNF 88 DLTASKNA 88 DLPSBSCH 88 DLLANGCON 88 DLPSBFAIL 88 DLPSBNA 88 DLTERMNS 88 DLFUNCNS 88 DLINA VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE UIBRCODE. Return codes . . . . Additional information . . . . . . . . . DLIUIB. Address of the PCB addr list 02 UIBPCBAL PIC S9(8) COMP. DL/I return codes
* 03
Figure 18. The COBOL COPY DLIUIB Copy Book
The values placed in level 88 entries are not printable. They are described in Chapter 16, CICS-DL/I User Interface Block Return Codes, on page 377. The meanings of the field names and their hexadecimal values are shown below: FCNORESP Normal response X'00' FCNOTOPEN Not open X'0C' FCINVREQ Invalid request X'08' FCINVPCB Invalid PCB X'10' DLPSBNF PSB not found X'01' DLTASKNA Task not authorized X'02' DLPSBSCH PSB already scheduled X'03' DLLANGCON Language conflict X'04' DLPSBFAIL PSB initialization failed X'05' DLPSBNA PSB not authorized X'06' DLTERMNS Termination not successful X'07'
79

DLFUNCNS Function unscheduled X'08' DLINA DL/I not active X'FF' Figure 19 shows you how to define the UIB, PCB address list, and PCB mask for PL/I.
DCL UIBPTR PTR; /* DCL 1 DLIUIB UNALIGNED BASED(UIBPTR), /* 2 UIBPCBAL PTR, /* 2 UIBRCODE, /* 3 UIBFCTR BIT(8) ALIGNED, /* 3 UIBDLTR BIT(8) ALIGNED; /* POINTER TO UIB */
EXTENDED CALL USER INTFC BLK*/ PCB ADDRESS LIST */ DL/I RETURN CODES */ RETURN CODES */ ADDITIONAL INFORMATION */
Figure 19. Defining the UIB, PCB Address List, and the PCB Mask for PL/I
Figure 20 shows you how to define the UIB, PCB address list, and PCB mask for assembler language.
DLIUIB UIB UIBPCBAL UIBRCODE UIBFCTR UIBDLTR UIBLEN DSECT DS DS DS DS DS DS DS EQU 0F A 0XL2 X X 2X 0F *-UIB EXTENDED CALL USER INTFC BLK PCB ADDRESS LIST DL/I RETURN CODES RETURN CODE ADDITIONAL INFORMATION RESERVED LENGTH IS FULLWORD MULTIPLE LENGTH OF UIB
Figure 20. Defining the UIB, PCB Address List, and the PCB Mask for Assembler Language
Specifying the I/O Areas

Use an I/O area to pass segments between your program and IMS. What the I/O area contains depends on the type of call you are issuing: v When you retrieve a segment, IMS DB places the segment you requested in the I/O area. v When you add a new segment, you first build the new segment in the I/O area. v Before modifying a segment, your program must first retrieve it. When you retrieve the segment, IMS DB places the segment in an I/O area. The format of the record segments you pass between your program and IMS can be fixed length or variable length. Only one difference is important to the application program: a message segment containing a 2-byte length field (or 4 bytes for the PLITDLI interface) at the beginning of the data area of the segment. The I/O area for IMS calls must be large enough to hold the largest segment your program retrieves from or adds to the database. If your program issues any Get or ISRT calls that use the D command code, the I/O area must be large enough to hold the largest path of segments that the program retrieves or inserts.
Formatting Segment Search Arguments (SSAs)

This section describes the coding rules and provides coding formats and examples for defining SSAs in assembler language, C language, COBOL, Pascal, and PL/I.
80
SSA Coding Rules

The rules for coding an SSA are as follows: v Define the SSA in the data area of your program. v The segment name field must: Be 8 bytes long. If the name of the segment you are specifying is less than 8 bytes long, it should be left justified and padded on the right with blanks. Contain a segment name that has been defined in the DBD that your application program uses. In other words, make sure you use the exact segment name, or your SSA will be invalid. v If the SSA contains only the segment name, byte 9 must contain a blank. v If the SSA contains one or more command codes: Byte 9 must contain an asterisk (*). The last command code must be followed by a blank unless the SSA contains a qualification statement. If the SSA contains a qualification statement, the command code must be followed by the left parenthesis of the qualification statement. v If the SSA contains a qualification statement: The qualification statement must begin with a left parenthesis and end with a right parenthesis. There must not be any blanks between the segment name or command codes, if used, and the left parenthesis. The field name must be 8 bytes long. If the field name is less than 8 bytes, it must be left justified and padded on the right with blanks. The field name must have been defined for the specified segment type in the DBD the application program is using. The relational operator follows the field name. It must be 2 bytes long and can be represented alphabetically or symbolically. Table 18 lists the relational operators.
Table 18. Relational Operators Symbolic = = >= or => <= or =< > > < < = or = Alphabetic EQ GE LE GT LT NE Meaning Equal to Greater than or equal to Less than or equal to Greater than Less than Not equal to
The comparative value follows the relational operator. The length of this value must be equal to the length of the field that you specified in the field name. This length is defined in the DBD. The comparative value must include leading zeros for numeric values or trailing blanks for alphabetic values as necessary. v If you are using multiple qualification statements within one SSA (Boolean qualification statements), the qualification statements must be separated by one of these symbols: * or & Dependent AND + or | Logical OR
81

# Independent AND One of these symbols must appear between the qualification statements that the symbol connects. v The last qualification statement must be followed by a right parenthesis. Restriction: An SSA created by the application program must not exceed the space allocated for the SSA in the PSB. Related Reading: For additional information about defining the PSB SSA size, see the explanation of the PSBGEN statement in IMS Version 9: Utilities Reference: Database and Transaction Manager.
SSA Coding Formats

This section shows examples of coding formats for assembler language, C language, COBOL, Pascal, and PL/I.
Assembler Language SSA Definition Examples

Figure 21 shows how you would define a qualified SSA without command codes. If you want to use command codes with this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.
* CONSTANT AREA . . . SSANAME DS 0CL26 ROOT DC CL8'ROOT ' DC CL1'(' DC CL8'KEY ' DC CL2' =' NAME DC CLn'vv...v' DC CL1')' Figure 21. Example Code: * CONSTANT AREA
This SSA looks like this:

ROOT (KEY =vv...v)
C Language SSA Definition Examples

An unqualified SSA that does not use command codes looks like this in C:
const struct { char seg_name_u[8]; char blank[1]; } unqual_ssa = {"NAME
", " "};
You can use an SSA that is coded like this for each DL/I call that needs an unqualified SSA by supplying the name of the segment type you want during program execution. Note that the string size declarations are such that the C null terminators do not appear within the structure. You can, of course, declare this as a single string:
const char unqual_ssa[] = "NAME "; /* 8 chars + 1 blank */
DL/I ignores the trailing null characters. You can define SSAs in any of the ways explained for the I/O area.
82

The easiest way to create a qualified SSA is using the sprintf function. However, you can also define it using a method similar to that used by COBOL or PL/I. The following is an example of a qualified SSA without command codes. To use command codes with this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.
struct { seg_name char[8]; seg_qual char[1]; seg_key_name char[8]; seg_opr char[2]; seg_key_value char[n]; seg_end_char char[1]; } qual_ssa = {"ROOT ", "(", "KEY
", " =", "vv...vv", ")"};
Another way is to define the SSA as a string, using sprintf. Remember to use the preprocessor directive #include <stdio.h>.
char qual_ssa[8+1+8+2+6+1+1]; /* the final 1 is for the */ /* trailing \0 of string */ sprintf(qual_ssa, "%-8.8s(%-8.8s%2.2s%-6.6s)", "ROOT", "KEY", "=", "vvvvv");
Alternatively, if only the value were changing, the sprintf call can be:
sprintf(qual_ssa, "ROOT (KEY =%-6.6s)", "vvvvv"); /* 12345678 12345678 */
In both cases, the SSA looks like this:

ROOT (KEY =vv...v)
These SSAs are both taken from the C skeleton program shown in Figure 10 on page 34. To see how SSAs are used in DL/I calls, refer to that program.
COBOL SSA Definition Examples

An unqualified SSA without command codes looks like this in COBOL:
DATA DIVISION. WORKING-STORAGE SECTION. . . . 01 UNQUAL-SSA. 02 SEG-NAME PICTURE X(08) 02 FILLER PICTURE X
VALUE '........'. VALUE ' '.
By supplying the name of the segment type you want during program execution, you can use an SSA coded like the one in this example for each DL/I call that needs an unqualified SSA. Use a 01 level working storage entry to define each SSA that the program is to use. Then use the name you have given the SSA as the parameter in the DL/I call, in this case:
UNQUAL-SSA,
The following SSA is an example of a qualified SSA that does not use command codes. If you use command codes in this SSA, code the asterisk (*) and the command code between the 8-byte segment name field and the left parenthesis that begins the qualification statement.
83

DATA DIVISION. WORKING-STORAGE SECTION. . . . 01 QUAL-SSA-MAST. 02 SEG-NAME-M PICTURE 02 BEGIN-PAREN-M PICTURE 02 KEY-NAME-M PICTURE 02 REL-OPER-M PICTURE 02 KEY-VALUE-M PICTURE 02 END-PAREN-M PICTURE
X(08) X X(08) X(02) X(n) X
VALUE VALUE VALUE VALUE VALUE VALUE
'ROOT '. '('. 'KEY '. ' ='. 'vv...v'. ')'.
The SSA looks like this:

ROOT (KEY =vv...v)
These SSAs are both taken from the COBOL skeleton program in Figure 11 on page 37. To see how they are used in a DL/I call, refer to that program.
Pascal SSA Definition Examples

An unqualified SSA without command codes looks like this in Pascal:
type STRUCT = record SEG_NAME : ALFA; BLANK : CHAR; end; const UNQUAL_SSA = STRUCT('NAME',' ');
You can, of course, declare this as a single string:

const UNQUAL_SSA = 'NAME ';
The SSA shown in Figure 22 is an example of a qualified SSA that does not use command codes. If you use command codes in this SSA, code the asterisk (*) and the command code between the 8-byte segment name field and the left parenthesis that begins the qualification statement. This SSA looks like this:
type STRUCT = record SEG_NAME : ALFA; SEG_QUAL : CHAR; SEG_KEY_NAME : ALFA; SEG_OPR : CHAR; SEG_KEY_VALUE : packed array[1..n] of CHAR; SEG_END_CHAR : CHAR; end; const QUAL_SSA = STRUCT('ROOT','(','KEY',' =','vv...v',')'); Figure 22. Qualified SSA without Command Codes ROOT (KEY =vv...v)
PL/I SSA Definition Examples

An unqualified SSA that does not use command codes looks like this in PL/I:
DCL 1 2 2 UNQUAL_SSA STATIC UNALIGNED, SEG_NAME_U CHAR(8) INIT('NAME BLANK CHAR(1) INIT(' '); '),
You can use a SSA that is coded like this for each DL/I call that needs an unqualified SSA by supplying the name of the segment type you want during program execution.
84

In PL/I you define SSAs in structure declarations. The unaligned attribute is required for SSA data interchange with IMS. The SSA character string must reside contiguously in storage. For example, assignment of variable key values might cause IMS to construct an invalid SSA if the key value has changed the aligned attribute. A separate SSA structure is required for each segment type that the program accesses because the value of the key fields differs among segment types. After you have initialized the fields (other than the key values), the SSA should not need to be changed again. You can define SSAs in any of the ways explained for the I/O area. The following is an example of a qualified SSA without command codes. If you use command codes in this SSA, code the asterisk (*) and command codes between the 8-byte segment name field and the left parenthesis that begins the qualification statement.
DCL 1 QUAL_SSA STATIC UNALIGNED, 2 SEG_NAME CHAR(8) 2 SEG_QUAL CHAR(1) 2 SEG_KEY_NAME CHAR(8) 2 SEG_OPR CHAR(2) 2 SEG_KEY_VALUE CHAR(n) 2 SEG_END_CHAR CHAR(1) INIT('ROOT '), INIT('('), INIT('KEY '), INIT(' ='), INIT('vv...v'), INIT(')');
This SSA looks like this:

ROOT (KEY =vv...v)
Both of these SSAs are taken from the PL/I skeleton program shown in Figure 14 on page 47. To see how they are used in DL/I calls, refer to that program.
GSAM Databases
This section shows how to code GSAM databases. GSAM databases are only available to application programs that can run as batch programs, batch-oriented BMPs or transaction-oriented BMPs. The PCB mask and the RSA that you use in a GSAM call have special formats. Generalized Sequential Access Method (GSAM) DB PCB masks are slightly different from other DB PCB masks. The fields that are different are the length of the key feedback area and the key feedback area. Also, an additional field exists that gives the length of the record being retrieved or inserted when using undefined-length records. The RSA (record search argument) is an 8-byte token that can be returned on GN and ISRT calls. The application program can save the RSA for use in a subsequent GU call. Related Reading: For more information on RSAs for GSAM, see Chapter 8, Processing GSAM Databases, on page 157.
The AIBTDLI Interface

This section explains how to use the application interface block (AIB), an interface between your application program and IMS.
85
AIBTDLI Interface
When you use the AIBTDLI interface, you specify the PCB that is requested for the call by placing the PCB name (as defined by PSBGEN) in the resource name field of the AIB. You do not specify the PCB address. Because the AIB contains the PCB name, your application can refer to the PCB name rather than to the PCB address. The AIBTDLI call allows you to select PCBs directly by name rather than by a pointer to the PCB. At completion of the call, the AIB returns the PCB address that corresponds to the PCB name that is passed by the application program. For PCBs to be used in a AIBTDLI call, you must assign a name in PSBGEN, either with PCBNAME= or with the name as a label on the PCB statement. PCBs that have assigned names are also included in the positional pointer list, unless you specify LIST=NO. During PSBGEN, you define the names of the DB PCBs and alternate PCBs. All I/O PCBs are generated with the PCB name IOPCB . For a generated program specification block (GPSB), the I/O PCB is generated with the PCB name IOPCB , and the modifiable alternate PCB is generated with the PCB name TPPCB1 . Because you can pass the PCB name, you do not need to know the relative PCB number in the PCB list. In addition, the AIBTDLI interface enables your application program to make calls on PCBs that do not reside in the PCB list. The LIST= keyword, which is defined in the PCB macro during PSBGEN, controls whether the PCB is included in the PCB list. The AIB resides in user-defined storage that is passed to IMS for DL/I calls that use the AIBTDLI interface. When the call is completed, the AIB is updated by IMS. Recommendation: Allocate at least 128 bytes of storage for the AIB. Restriction: No fields in the AIB can be used by the application program except as defined by IMS. Related Reading: For more information about PSBGEN, see IMS Version 9: Utilities Reference: System.
Language Specific Entry Points

IMS gives control to an application program through an entry point. The formats for coding entry statements in assembler language, C language, COBOL, Pascal, and PL/I are shown in these sections: Assembler Language Entry Point on page 87, C Language Entry Point on page 87, COBOL Entry Point on page 88, Pascal Entry Point on page 88, and PL/I Entry Point on page 88. Your entry point must refer to the PCBs in the order in which they have been defined in the PSB. IMS passes the PCB pointers to a PL/I program differently than it passes them to assembler language, C language, COBOL, or Pascal programs. In addition, Pascal requires that IMS pass an integer before passing the PCB pointers. IMS uses the LANG keyword or the PSBGEN statement of PSBGEN to determine the type of program to which it is passing control. Therefore, you must be sure that the language that is specified during PSBGEN is consistent with the language of the program. When you code each DL/I call, you must provide the PCB you want to use for that call. In all cases except CICS online, the list of PCBs that the program can access is passed to the program at its entry point. For CICS online, you must first schedule a PSB as described in PCB Call (CICS Online Programs Only) on page 277.
86

Application interfaces that use the AIB structure (AIBTDLI or CEETDLI) use the PCB name rather than the PCB structure, and they do not require the PCB list to be passed at entry to the application. In a CICS online program, you do not obtain the address of the PCBs through an entry statement, but through the user interface block (UIB). For more information, see Specifying the UIB (CICS Online Programs Only) on page 77.
Assembler Language Entry Point

You can use any name for the entry statement to an assembler language DL/I program. When IMS passes control to the application program, register 1 contains the address of a variable-length fullword parameter list. Each word in the list contains the address of a PCB. Save the content of register 1 before you overwrite it. IMS sets the high-order byte of the last fullword in the list to X'80' to indicate the end of the list. Use standard z/OS linkage conventions with forward and backward chaining.
C Language Entry Point

When IMS passes control to your program, it passes the addresses, in the form of pointers, for each of the PCBs that your program uses. The usual argc and argv arguments are not available to a program that is invoked by IMS. The IMS parameter list is made accessible by using the __pcblist macro. You can directly reference the PCBs by __pcblist[0], __pcblist[1], or you can define macros to give these more meaningful names. Note that I/O PCBs must be cast to get the proper type:
(IO_PCB_TYPE *)(__pcblist[0])
The entry statement for a C language program is the main statement.

#pragma runopts(env(IMS),plist(IMS)) #include <ims.h> main() { . . . }
The env option specifies the operating environment in which your C language program is to run. For example, if your C language program is invoked under IMS and uses IMS facilities, specify env(IMS). The plist option specifies the format of the invocation parameters that is received by your C language program when it is invoked. When your program is invoked by a system support services program, the format of the parameters passed to your main program must be converted into the C language format: argv, argc, and envp. To do this conversion, you must specify the format of the parameter list that is received by your C language program. The ims.h include file contains declarations for PCB masks. You can finish in three ways: v End the main procedure without an explicit return statement. v Execute a return statement from main. v Execute an exit or an abort call from anywhere, or alternatively issue a longjmp back to main, and then do a normal return.
87

One C language program can pass control to another by using the system function. The normal rules for passing parameters apply; in this case, the argc and argv arguments can be used to pass information. The initial __pcblist is made available to the invoked program.
COBOL Entry Point

The procedure statement must refer to the I/O PCB first, then to any alternate PCB it uses, and finally to the DB PCBs it uses. The alternate PCBs and DB PCBs must be listed in the order in which they are defined in the PSB.
PROCEDURE DIVISION USING PCB-NAME-1 [,...,PCB-NAME-N]
In previous versions of IMS, USING might be coded on the entry statement to reference PCBs. However, IMS continues to accept such coding on the entry statement. Recommendation: Use the procedure statement rather than the entry statement to reference the PCBs.
Pascal Entry Point

The entry point must be declared as a REENTRANT procedure. When IMS passes control to a Pascal procedure, the first address in the parameter list is reserved for Pascal's use, and the other addresses are the PCBs the program uses. The PCB types must be defined before this entry statement. The IMS interface routine PASTDLI must be declared with the GENERIC directive.
procedure ANYNAME(var SAVE: INTEGER; var pcb1-name: pcb1-name-type[; ... var pcbn-name: pcbn-name-type]); REENTRANT; procedure ANYNAME; (* Any local declarations *) procedure PASTDLI; GENERIC; begin (* Code for ANYNAME *) end;
PL/I Entry Point

The entry statement must appear as the first executable statement in the program. When IMS passes control to your program, it passes the addresses of each of the PCBs your program uses in the form of pointers. When you code the entry statement, make sure you code the parameters of this statement as pointers to the PCBs, and not the PCB names.
anyname: PROCEDURE (pcb1_ptr [,..., pcbn_ptr]) OPTIONS (MAIN); . . . RETURN;
The entry statement can be any valid PL/I name.
CEETDLI, AIBTDLI, and AERTDLI Interface Considerations

This section explains the interfaces: CEETDLI, AIBTDLI, and AERTDLI. The considerations for CEETDLI are:
88

v For PL/I programs, the CEETDLI entry point is defined in the CEEIBMAW include file. Alternatively, you can declare it yourself, but it must be declared as an assembler language entry (DCL CEETDLI OPTIONS(ASM);). v For C language application programs, you must specify env(IMS) and plist(IMS); these specifications enable the application program to accept the PCB list of arguments. The CEETDLI function is defined in <leawi.h>; the CTDLI function is defined in <ims.h>. The considerations for AIBTDLI are: v When using the AIBTDLI interface for C/MVS, Enterprise COBOL, or PL/I language application programs, the language run-time options for suppressing abend interception (that is, NOSPIE and NOSTAE) must be specified. However, for Language Environment-conforming application programs, the NOSPIE and NOSTAE restriction is removed. v The AIBTDLI entry point for PL/I programs must be declared as an assembler language entry (DCL AIBTDLI OPTIONS(ASM);). v For C language applications, you must specify env(IMS) and plist(IMS); these specifications enable the application program to accept the PCB list of arguments. The considerations for AERTDLI are: v When using the AERTDLI interface for C/MVS, COBOL, or PL/I language application programs, the language run-time options for suppressing abend interception (that is, NOSPIE and NOSTAE) must be specified. However, for Language Environment-conforming application programs, the NOSPIE and NOSTAE restriction is removed. v The AERTDLI entry point for PL/I programs must be declared as an assembler language entry (DCL AERTDLI OPTIONS(ASM);). v For C language applications, you must specify env(IMS) and plis(IMS). These specifications enable the application program to accept the PCB list of arguments. v AERTDLI must receive control with 31 bit addressability.
Program Communication Block (PCB) Lists

This section describes the formats of PCB lists and GPSB PCB lists, and provides a description of PCBs in various types of application programs.
PCB List Format

The following example shows the general format of a PCB list.
[IOPCB] [Alternate PCB ... Alternate PCB] [DB PCB ... DB PCB] [GSAM PCB ... GSAM PCB]
| | | | |
Each PSB must contain at least one PCB. An I/O PCB is required for most system service calls. An I/O PCB or alternate PCB is required for transaction management calls. (Alternate PCBs can exist in IMS TM.) DB PCBs for DL/I databases are used only with the IMS Database Manager under DBCTL. GSAM PCBs can be used with DCCTL.
Format of a GPSB PCB List

A generated program specification block (GPSB) takes this format:
89
PCB Lists
[IOPCB] [Alternate PCB]
A GPSB contains only an I/O PCB and one modifiable alternate PCB. (A modifiable alternate PCB enables you to change the destination of the alternate PCB while the program is running.)A GPSB can be used by all transaction management application programs, and permits access to the specified PCBs without the need for a specific PSB for the application program. | | | The names of PCBs in a GPSB are predefined. The name of the I/O PCB is IOPCB. The name of the alternate PCB is TPPCB1 . The minimum size of the I/O work area that IMS generates for GPSBs in a DBCTL environment is 600 bytes.
PCB Summary
This section summarizes the information concerning I/O PCBs and alternate PCBs in various types of application programs. You should read this section if you intend to issue system service requests. DB Batch Programs If CMPAT=Y is specified in PSBGEN, the I/O PCB is present in the PCB list; otherwise, the I/O PCB is not present, and the program cannot issue system service calls. Alternate PCBs are always included in the list of PCBs that IMS supplies to the program. The I/O PCB and alternate PCBs are always passed to BMPs, MPPs, and IFPs. The PCB list always 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 Online Programs with DBCTL If you specify the IOPCB option on the PCB call, the first PCB address in your PCB list is the I/O PCB, followed by any alternate PCBs, followed by the addresses of the DB PCBs. If you do not specify the I/O PCB option, the first PCB address in your PCB list points to the first DB PCB. Table 19 summarizes the I/O PCB and alternate PCB information.
Table 19. I/O PCB and Alternate PCB Information Summary CALL DL/I Environment MPP IFP BMP DB Batch DB Batch
1 2 3 4
BMPs, MPPs, and IFPs
I/O PCB address in PCB list Yes Yes Yes No Yes Yes No
Alternate PCB address in PCB list Yes Yes Yes Yes Yes Yes No
TM Batch
CICS DBCTL
90
PCB Lists
Table 19. I/O PCB and Alternate PCB Information Summary (continued) CALL DL/I Environment CICS DBCTL5 Notes: 1. CMPAT = N specified. 2. CMPAT = Y specified. 3. CMPAT = Option. Default is always to Y, even when CMPAT = N is specified. 4. SCHD request issued without the IOPCB or SYSSERVE option. 5. SCHD request issued with the IOPCB or SYSSERVE for a CICS DBCTL request or for a function-shipped request which is satisfied by a CICS system using DBCTL. I/O PCB address in PCB list Yes Alternate PCB address in PCB list Yes
The AERTLDI interface

This section explains how to use the AIB with ODBA applications. When you use the AERTDLI interface, the AIB used for database calls must be the same AIB as used for the APSB call. Specify the PCB that is requested for the call by placing the PCB name (as defined by PSBGEN) in the resource name field of the AIB. You do not specify the PCB address. Because the AIB contains the PCB name, your application can refer to the PCB name rather than to the PCB address. The AERTDLI call allows you to select PCBs directly by name rather than by a pointer to the PCB. At completion of the call, the AIB returns the PCB address that corresponds to the PCB name that is passed by the application program. For PCBs to be used in a AERTDLI call, you must assign a name in PSBGEN, either with PCBNAME= or with the name as a label on the PCB statement. PCBs that have assigned names are also included in the positional pointer list, unless you specify LIST=NO. During PSBGEN, you define the names of the DB PCBs and alternate PCBs. All I/O PCBs are generated with the PCB name IOPCB . Because you pass the PCB name, you do not need to know the relative PCB number in the PCB list. In addition, the AERTDLI interface enables your application program to make calls on PCBs that do not reside in the PCB list. The LIST= keyword, which is defined in the PCB macro during PSBGEN, controls whether the PCB is included in the PCB list. The AIB resides in user-defined storage that is passed to IMS for DL/I calls that use the AERTDLI interface. When the call is completed, the AIB is updated by IMS. Because some of the fields in the AIB are used internally by IMS, the same APSB AIB must be used for all subsequent calls for that PSB. Requirement: Allocate 264 bytes of storage for the AIB.
Language Environments
IBM z/OS Language Environment provides the strategic execution environment for running your application programs written in one or more high-level languages. It provides not only language-specific run-time support, but also cross-language run-time services for your application programs, such as support for initialization, termination, message handling, condition handling, storage management, and National Language Support. Many of Language Environment services are
91
accessible explicitly through a set of Language Environment interfaces that are common across programming languages; these services are accessible from any Language Environment-conforming program. Language Environment-conforming programs can be compiled with: v IBM z/OS C/C++ Compilers v Enterprise COBOL v Enterprise PL/I These programs can be produced by programs coded in assembler. All these programs can use CEETDLI, the Language Environment-provided language-independent interface to IMS, as well as older language-dependent interfaces to IMS, such as CTDLI, CBLTDLI, and PLITDLI. Although they do not conform to Language Environment, programs compiled with the following older compilers can run under Language Environment: v IBM C/370 v IBM VS COBOL II v IBM OS PL/I These programs cannot use CEETDLI, but they can use the older language-dependent interfaces to IMS. Related Reading: For more information about Language Environment, see IBM Language Environment for MVS and VM Programming Guide.
The CEETDLI interface to IMS

The language-independent CEETDLI interface to IMS is provided by Language Environment. It is the only IMS interface that supports the advanced error handling capabilities that Language Environment provides. The CEETDLI interface supports the same functionality as the other IMS application interfaces. The characteristics are: v The parmcount variable is optional. v Length fields are 2 bytes long. v Direct pointers are used. Related Reading: For more information about Language Environment, see IBM Language Environment for MVS and VM Programming Guide and Language Environment for MVS & VM Installation and Customization.
Specifying LANG= Option for PL/I Compatibility

For IMS PL/I applications running in a compatibility mode that uses the PLICALLA entry point, you must specify LANG=PLI on the PSBGEN, or you can change the entry point and add SYSTEM(IMS) to the EXEC PARM of the compile step so that you can specify LANG=blank or LANG=PLI on the PSBGEN. Table 20 summarizes when you can use LANG= and LANG=PLI.
Table 20. Using LANG= Option in a Language Environment for PL/I Compatibility Compile EXEC statement is PARM=(...,SYSTEM(IMS)... Yes Yes and entry point name is PLICALLA Yes No Then LANG= is LANG=PLI LANG= or LANG=PLI
92
Table 20. Using LANG= Option in a Language Environment for PL/I Compatibility (continued) Compile EXEC statement is PARM=(...,SYSTEM(IMS)... No No and entry point name is PLICALLA No Yes Then LANG= is Not valid for IMS PL/I applications LANG=PLI
| | | | | | | |
Restriction: PLICALLA is only valid for PL/I compatibility with Language Environment. If a PL/I application program that uses the PLICALLA entry at bind time is bound using Language Environment with the PLICALLA entry, the bind will work; however, you must use LANG=PLI in the PSB. If you recompile the application program (without the PLICALLA entry) by using Enterprise PL/I, and then attempt to bind using Language Environment Version 1 Release 2 or later, the bind will fail. To bind successfully, you first must remove the PLICALLA entry statement from the bind.
Special DL/I Situations Application Program Scheduling against HALDBs

Application programs are scheduled against HALDBs the same way they are against non-HALDBs. Scheduling is based on the availability status of the HALDB master and is not affected by individual partition access and status. The application programmer needs to be aware of changes to the handling of unavailable data for HALDBs. The feedback on data availability at PSB schedule time shows the availability of the HALDB master, not of the partitions. However, the error settings for data unavailability of a partition at the first reference to the partition during the processing of a DL/I call are the same as those of a non-HALDB, namely status code BA or pseudo ABENDU3303. Example: If you issue the IMS /DBR command to half of the partitions to take them offline, the remaining partitions are available to the programs. If you load a new HALDB that contains logical relationships, the logical child segments are not loaded as part of the load step. Add logical children through normal update processing after the database is loaded. When a program accesses a partition for the first time, an indicator records that the PSB accessed the partition. Commands can operate against a partition currently not in use. A DFS05651 message results if a BMP uses a partition and the command was against that partition. If an application attempts to access data from a stopped partition, a pseudo abend results or the application receives a BA status code. If the partition starts before the application attempts to access data in that partition again, the DL/I call succeeds.
Mixed-Language Programming
When an application program uses the Language Environment language-independent interface, CEETDLI, IMS does not need to know the language of the calling program. When the application program calls IMS in a language-dependent interface, IMS determines the language of the calling program according to the entry name that is specified in the CALL statement. That is, IMS assumes that the program is:
93
Special DL/I Situations

v v v v v Assembler language when the application program uses CALL ASMTDLI C language when the application program uses rc=CTDLI COBOL when the application program uses CALL CBLTDLI Pascal when the application program uses CALL PASTDLI PL/I when the application program uses CALL PLITDLI
For example, if a PL/I program calls an assembler language subroutine and the assembler language subroutine makes DL/I calls by using CALL ASMTDLI, the assembler language subroutine should use the assembler language calling convention, not the PL/I convention. In this situation, where the I/O area uses the LLZZ format, LL is a halfword, not the fullword that is used for PL/I.
Language Environment Routine Retention

If you run programs in an IMS TM dependent region that requires Language Environment (such as an IMS message processing region), you can improve performance if you use Language Environment library routine retention along with the existing PREINIT feature of IMS TM. Related Reading: For more information about Language Environment routine retention, see IBM Language Environment for MVS & VM Programming Guide and IBM Language Environment for MVS & VM Installation and Customization.
Extended Addressing Capabilities of z/OS

The two modes in z/OS with extended addressing capabilities are: the addressing mode (AMODE) and the residency mode (RMODE). IMS places no constraints on the RMODE and AMODE of an application program. The program can reside in the extended virtual storage area. The parameters that are referenced in the call can also be in the extended virtual storage area.
Preloaded Programs
| | If you compile your COBOL program with the Enterprise COBOL compiler and preload it, you must use the COBOL compiler option RENT. If you compile your COBOL program with the VS COBOL II compiler and preload it, you must use the COBOL compiler options RES and RENT.
94
Chapter 4. Current Position in the Database After Each Call

Positioning means that DL/I tracks your place in the database after each call that you issue. By tracking your position in the database, DL/I enables you to process the database sequentially. | The following topics provide additional information: v Current Position after Successful Calls v Current Position after Unsuccessful Calls on page 100 v Multiple Processing on page 104
Current Position after Successful Calls

Position is important when you process the database sequentially by issuing GN, GNP, GHN, and GHNP calls. Current position is where IMS starts its search for the segments that you specify in the calls. This section explains current position for successful calls. Current position is also affected by an unsuccessful retrieval or ISRT call. Current Position after Unsuccessful Calls on page 100 explains current position in the database after an unsuccessful call. Before you issue the first call to the database, the current position is the place immediately before the first root segment occurrence in the database. This means that if you issue an unqualified GN call, IMS retrieves the first root segment occurrence. It is the next segment occurrence in the hierarchy that is defined by the DB PCB that you referenced. Certain calls cancel your position in the database. You can reestablish this position with the GU call. Because the CHKP and SYNC (commit point) calls cancel position, follow either of these calls with a GU call. The ROLS and ROLB calls also cancel your position in the database. When you issue a GU call, your current position in the database does not affect the way that you code the GU call or the SSA you use. If you issue the same GU call at different points during program execution (when you have different positions established), you will receive the same results each time you issue the call. If you have coded the call correctly, IMS returns the segment occurrence you requested regardless of whether the segment is before or after the current position. Exception: If a GU call does not have SSAs for each level in the call, it is possible for IMS to return a different segment at different points in your program. This is based on the position at each level. Example: Suppose you issue the following call against the data structure shown in Figure 23 on page 96.
GU A (AKEY B D = A1) (BKEY (DKEY
= B11) D111)
95

The structure in the figure contains six segment types: A, B, C, D, E, and F. Figure 23 shows one database record, the root of which is A1.
Figure 23. Current Position Hierarchy
When you issue this call, IMS returns the D segment with the key D111, regardless of where your position is when you issue the call. If this is the first call your program issues (and if this is the first database record in the database), current position before you issue the call is immediately before the first segment occurrence in the databasejust before the A segment with the key of A1. Even if current position is past segment D111 when you issue the call (for example, just before segment F111), IMS still returns the segment D111 to your program. This is also true if the current position is in a different database record. When you issue GN and GNP calls, current position in the database affects the way that you code the call and the SSA. That is because when IMS searches for a segment described in a GN or GNP call, it starts the search from current position and can only search forward in the database. IMS cannot look behind that segment occurrence to satisfy a GN or GNP. These calls can only move forward in the database when trying to satisfy your call, unless you use the F command code, the use of which is described in F Command Code on page 205. If you issue a GN call for a segment occurrence that you have already passed, IMS starts searching at the current position and stops searching when it reaches the end of the database (resulting in a GB status code), or when it determines from your SSA that it cannot find the segment you have requested (GE status code). Current Position after Unsuccessful Calls on page 100 explains where your position is when you receive a GE status code. Current position affects ISRT calls when you do not supply qualified SSAs for the parents of the segment occurrence that you are inserting. If you supply only the unqualified SSA for the segment occurrence, you must be sure that your position in the database is where you want the segment occurrence to be inserted.
96
Position after Retrieval Calls

| | | | | After you issue any kind of successful retrieval call, position immediately follows the segment occurrence you just retrievedor the lowest segment occurrence in the path if you retrieved several segment occurrences using the D command code. When you use the D command code in a retrieval call, a successful call is one that IMS completely satisfies. Example: If you issue the following call against the database shown in Figure 23 on page 96, IMS returns the C segment occurrence with the key of C111. Current position is immediately after C111. If you then issue an unqualified GN call, IMS returns the C112 segment to your program.
GU A( B C (AKEY (BKEY (CKEY = A1) = B11) = C111)
Your current position is the same after retrieving segment C111, whether you retrieve it with GU, GN, GNP, or any of the Get Hold calls. If you retrieve several segment occurrences by issuing a Get call with the D command code, current position is immediately after the lowest segment occurrence that you retrieved. If you issue the GU call as shown in the example above, but include the D command code in the SSA for segments A and B, the current position is still immediately after segment C111. C111 is the last segment that IMS retrieves for this call. With the D command code, the call looks like this: | | |
GU A B C D(AKEY D(BKEY (CKEY = A1) = B11) = C111)
You do not need the D command code on the SSA for the C segment because IMS always returns to your I/O area the segment occurrence that is described in the last SSA.
Position after DLET

After a successful DLET call, position immediately follows the segment occurrence you deleted. This is true when you delete a segment occurrence with or without dependents. Example: If you issue the call shown Figure 24 to delete segment C111, current position is immediately after segment C111. Then, if you issue an unqualified GN call, IMS returns segment C112.
GHU DLET Figure 24. Example Code: Deleting Segment C11 A B C (AKEY (BKEY (CKEY = A1) = B11) = C111)
Figure 25 on page 98 shows what the hierarchy looks like after this call. The successful DLETcall has deleted segment C111.
97
Figure 25. Hierarchy after Deleting a Segment
When you issue a successful DLET call for a segment occurrence that has dependents, IMS deletes the dependents, and the segment occurrence. Current position still immediately follows the segment occurrence you deleted. An unqualified GN call returns the segment occurrence that followed the segment you deleted. Example: If you delete segment B11 in the hierarchy shown in Figure 25, IMS deletes its dependent segments, C112 and D111, as well. Current position immediately follows segment B11, just before segment B12. If you then issue an unqualified GN call, IMS returns segment B12. Figure 26 shows what the hierarchy looks like after you issued this call.
Figure 26. Hierarchy after Deleting a Segment and Dependents
Because IMS deletes the segment's dependents, you can think of current position immediately following the last (lowest, right-most) dependent. In the example in Figure 25, this immediately follows segment D111. But if you then issue an unqualified GN call, IMS still returns segment B12. You can think of position in
98

either placethe results are the same either way. An exception to this can occur for a DLET that follows a GU path call, which returned a GE status code. See Current Position after Unsuccessful Calls on page 100 regarding position after unsuccessful calls.
Position after REPL

A successful REPL call does not change your position in the database. Current position is just where it was before you issued the REPL call. It immediately follows the lowest segment that is retrieved by the Get Hold call that you issued before the REPL call. Example: If you retrieve segment B13 in Figure 26 on page 98 using a GHU instead of a GU call, change the segment in the I/O area, and then issue a REPL call, current position immediately follows segment B13.
Position after ISRT

After you add a new segment occurrence to the database, current position immediately follows the new segment occurrence. Example: In Figure 27 on page 100, if you issue the following call to add segment C113 to the database, current position immediately follows segment C113. An unqualified GN call would retrieve segment D111.
ISRT A (AKEY =
If you are inserting a segment that has a unique key, IMS places the new segment in key sequence. If you are inserting a segment that has either a non unique key or no key at all, IMS places the segment according to the rules parameter of the SEGM statement of the DBD for the database. ISRT Call on page 238 explains these rules. If you insert several segment occurrences using the D command code, current position immediately follows the lowest segment occurrence that is inserted. Example: Suppose you insert a new segment B (this would be B14), and a new C segment occurrence (C141), which is a dependent of B14. Figure 27 on page 100 shows what the hierarchy looks like after these segment occurrences are inserted. The call to do this looks like this:
ISRT A (AKEY =
You do not need the D command code in the SSA for the C segment. On ISRT calls, you must include the D command code in the SSA for the only first segment you are inserting. After you issue this call, position immediately follows the C segment occurrence with the key of C141. Then, if you issue an unqualified GN call, IMS returns segment E11. If your program receives an II status code as a result of an ISRT call (which means that the segment you tried to insert already exists in the database), current position is just before the duplicate of the segment that you tried to insert.
99
Current Position after Unsuccessful Calls
Figure 27. Hierarchy after Adding New Segments and Dependents

IMS establishes another kind of position when you issue retrieval and ISRT calls. This is position on one segment occurrence at each hierarchic level in the path to the segment that you are retrieving or inserting. You need to know how IMS establishes this position to understand the U and V command codes described in General Command Codes for DL/I Calls on page 202. Also, you need to understand where your position in the database is when IMS returns a not-found status code to a retrieval or ISRT call. In Current Position after Successful Calls on page 95 you saw what current position is, why and when it is important, and how successful DL/I calls affect it. But chances are that not every DL/I call that your program issues will be completely successful. When a call is unsuccessful, you should understand how to determine your position in the database after that call.
Position after an Unsuccessful DLET or REPL Call

DLET and REPL calls do not affect current position. Your position in the database is the same as it was before you issued the call. However, an unsuccessful Get call or ISRT call does affect your current position. To understand where your position is in the database when IMS cannot find the segment you have requested, you need to understand how DL/I determines that it cannot find your segment. In addition to establishing current position after the lowest segment that is retrieved or inserted, IMS maintains a second type of position on one segment occurrence at each hierarchic level in the path to the segment you are retrieving or inserting. Example: In Figure 28 on page 101, if you had just successfully issued the GU call with the SSA shown below, IMS has a position established at each hierarchic level.
100

GU A B C (AKEY (BKEY (CKEY =b A1) B11) = C111)
Now DL/I has three positions, one on each hierarchic level in the call: v One on the A segment with the key A1 v One on the B segment with the key B11 v One on the C segment with the key C111
Figure 28. DL/I Positions
When IMS searches for a segment occurrence, it accepts the first segment occurrence it encounters that satisfies the call. As it does so, IMS stores the key of that segment occurrence in the key feedback area.
Position after an Unsuccessful Retrieval or ISRT Call

Current position after a retrieval or ISRT call that receives a GE status code depends on how far IMS got in trying to satisfy the SSA in the call. When IMS processes an ISRT call, it checks for each of the parents of the segment occurrence you are inserting. An ISRT call is similar to a retrieval call, because IMS processes the call level by level, trying to find segment occurrences to satisfy each level of the call. When IMS returns a GE status code on a retrieval call, it means that IMS was unable to find a segment occurrence to satisfy one of the levels in the call. When IMS returns a GE status code on an ISRT call, it means that IMS was unable to find one of the parents of the segment occurrence you are inserting. These are called not-found calls. When IMS processes retrieval and ISRT calls, it tries to satisfy your call until it determines that it cannot. When IMS first tries to find a segment matching the description you have given in the SSA and none exists under the first parent, IMS tries to search for your segment under another parent. How you code the SSA in the call determines whether IMS can move forward and try again under another parent.
101

Example: Suppose you issue the following GN call to retrieve the C segment with the key of C113 in the hierarchy shown in Figure 28 on page 101.
GN A B C (AKEY (BKEY (CKEY = A1) = B11) = C113)
When IMS processes this call, it searches for a C segment with the key equal to C113. IMS can only look at C segments whose parents meet the qualifications for the A and B segments. The B segment that is part of the path must have a key equal to B11, and the A segment that is part of the path must have a key equal to A1. IMS then looks at the first C segment. Its key is C111. The next C segment has a key of C112. IMS looks for a third C segment occurrence under the B11 segment occurrence. No more C segment occurrences exist under B11. Because you have specified in the SSA that the A and B segment occurrences in C's path must be equal to certain values, IMS cannot look for a C segment occurrence with a key of C113 under any other A or B segment occurrence. No more C segment occurrences exist under the parent B11; the parent of C must be B11, and the parent of B11 must be A1. IMS determines that the segment you have specified does not exist and returns a not-found (GE) status code. When you receive the GE status code on this call, you can determine where your position is from the key feedback area, which reflects the positions that IMS has at the levels it was able to satisfyin this case, A1 and B11. After this call, current position immediately follows the last segment occurrence that IMS examined in trying to satisfy your callin this case, C112. Then, if you issue an unqualified GN call, IMS returns D111. The current position after this call is different if A and B have non unique keys. Suppose A's key is unique and B's is non unique. After IMS searches for a C113 segment under B11 and is unable to find one, IMS moves forward from B11 to look for another B segment with a key of B11. When IMS does not find one, DL/I returns a GE status code. Current position is further in the database than it was when both keys were unique. Current position immediately follows segment B11. An unqualified GN call would return B12. If A and B both have non unique keys, current position after the previous call immediately follows segment A1. Assuming no more segment A1s exist, an unqualified GN call would return segment A2. If other A1s exist, IMS tries to find a segment C113 under the other A1s. But suppose you issue the same call with a greater-than-or-equal-to relational operator in the SSA for segment B:
GU A B C (AKEY (BKEY (CKEY = A1) =>B11) = C113)
IMS establishes position on segment A1 and segment B11. Because A1 and B11 satisfy the first two SSAs in the call, IMS stores their keys in the key feedback area. IMS searches for a segment C113 under segment B11. None is found. But this time, IMS can continue searching, because the key of the B parent can be greater than or equal to B11. The next segment is B12. Because B12 satisfies the qualification for segment B, IMS places B12's key in the key feedback area. IMS then looks for a C113 under B12 and does not find one. The same thing happens for B13: IMS places the key of B13 in the key feedback area and looks for a C113 under B13.
102

When IMS finds no more B segments under A1, it again tries to move forward to look for B and C segments that satisfy the call under another A parent. But this time it cannot; the SSA for the A segment specifies that the A segment must be equal to A1. (If the keys were non unique, IMS could look for another A1 segment.) IMS then knows that it cannot find a C113 under the parents you have specified and returns a GE status code to your program. In this example, you have not limited IMS's search for segment C113 to only one B segment, because you have used the greater-than-or-equal-to operator. IMS's position is further than you might have expected, but you can tell what the position is from the key feedback area. The last key in the key feedback area is the key of segment B13; The current position of IMS immediately follows segment B13. If you then issue an unqualified GN call, IMS returns segment E11. Each of the B segments that IMS examines for this call satisfies the SSA for the B segment, so IMS places the key of each in the key feedback area. But if one or more of the segments IMS examines does not satisfy the call, IMS does not place the key of that segment in the key feedback area. This means that IMS's position in the database might be further than the position reflected by the key feedback area. For example, suppose you issue the same call, but you qualify segment B on a data field in addition to the key field. To do this, you use multiple qualification statements for segment B. Assume the data field you are qualifying the call on is called BDATA. Assume the value you want is 14, but that only one of the segments, B11, contains a value in BDATA of 14:
GN A B C (AKEY (BKEY (CKEY = A1) >=B11*BDATA = C113) = 14)
After you issue this call, the key feedback area contains the key for segment B11. If you continue issuing this call until you receive a GE status code, IMS's current position immediately follows segment B13, but the key feedback area still contains only the key for segment B11. Of the B segments IMS examines, only one of them (B11) satisfies the SSA in the call. When you use a greater-than or greater-than-or-equal-to relational operator, you do not limit IMS's search. If you get a GE status code on this kind of call, and if one or more of the segments IMS examines does not satisfy an SSA, IMS's position in the database may be further than the position reflected in the key feedback area. If, when you issue the next GN or GNP call, you want IMS to start searching from the position reflected in the key feedback area instead of from its real position, you can either: v Issue a fully qualified GU call to reestablish position to where you want it. v Issue a GN or GNP call with the U command code. Including a U command code on an SSA tells IMS to use the first position it established at that level as qualification for the call. This is like supplying an equal-to relational operator for the segment occurrence that IMS has positioned on at that level. Example: Suppose that you first issue the GU call with the greater-than-or-equal-to relational operator in the SSA for segment B, and then you issue this GN call:
GN A B C *U *U
103

The U command code tells IMS to use segment A1 as the A parent, and segment B11 as the B parent. IMS returns segment C111. But if you issue the same call without the U command code, IMS starts searching from segment B13 and moves forward to the next database record until it encounters a B segment. IMS returns the first B segment it encounters.
Multiple Processing
The order in which an application program accesses segments in a hierarchy depends on the purpose of the application program. Some programs access segments directly, others sequentially. Some application programs require that the program process segments in different hierarchic paths, or in different database records, in parallel. If your program must process segments from different hierarchic paths or from different database records in parallel, using multiple positioning or multiple PCBs can simplify the program's processing. For example: v Suppose your program must retrieve segments from different hierarchic paths alternately: for example, in Figure 29, it might retrieve B11, then C11, then B12, then C12, and so on. If your program uses multiple positioning, IMS maintains positions in both hierarchic paths. Then the program is not required to issue GU calls to reset position each time it needs to retrieve a segment from a different path. v Suppose your program must retrieve segments from different database records alternately: for example, it might retrieve a B segment under A1, and then a B segment under another A root segment. If your program uses multiple PCBs, IMS maintains positions in both database records. Then the program does not have to issue GU calls to reset position each time it needs to access a different database record.
Figure 29. Multiple Processing
Multiple Positioning
When you define the PSB for your application program, you have a choice about the kind of positioning you want to use: single or multiple. All of the examples used so far, and the explanations about current position, have used single positioning. This section explains what multiple positioning is, why it is useful, and how it affects your programming. Specify the kind of position you want to use for each PCB on the PCB statement when you define the PSB. The POS operand for a DEDB is disregarded. DEDBs support multiple positioning only. Definitions:
104
v Single positioning means that IMS maintains position in one hierarchic path for the hierarchy that is defined by that PCB. When you retrieve a segment, IMS clears position for all dependents and all segments on the same level. v Multiple positioning means that IMS maintains position in each hierarchic path in the database record that is being accessed. When you retrieve a segment, IMS clears position for all dependents but keeps position for segments at the same level. Example: Suppose you issue these two calls using the hierarchy shown in Figure 30:
GU A B C E (AKEY (BKEYY (CKEYY (EKEYY = A1) = B11) = C111) = E11)
GN
Figure 30. Multiple Positioning Hierarchy
After issuing the first call with single positioning, IMS has three positions established: one on A1, one on B11, and one on C111. After issuing the second call, the positions on B11 and C111 are canceled. Then IMS establishes positions on A1 and E11. After issuing the first call with single and multiple positioning, IMS has three positions established: one on A1, one on B11, and one on C111. However, after issuing the second call, single positioning cancels positions on B11 and C111 while multiple positioning retains positions on B11 and C111. IMS then establishes positions on segments A1 and E11 for both single and multiple positioning. After issuing the first call with multiple positioning, IMS has three positions established (just as with single positioning): one on A1, one on B11, and one on C111. But after issuing the second call, the positions on B11 and C111 are retained. In addition to these positions, IMS establishes position on segments A1 and E11.
105
Figure 31. Single and Multiple Positioning Hierarchy
The examples that follow compare the results of single and multiple positioning using the hierarchy in Figure 31.
Table 21. Results of Single and Multiple Positioning with DL/I Calls Sequence Example 1 GU (where AKEY equals A1) GNP B GNP C GNP B GNP C GNP B GNP C GNP B GNP C Example 2 GU A (where AKEY equals A1) GN B GN C GN B GN C Example 3 GU A (where AKEY equals A1) GN C GN B GN B GN C Example 4 GU A (where AKEY equals A1) GN B GN C GN D GN E GN B GN D GN C GN E Result of Single Positioning A1 B11 C11 Not C12 Not C13 Not Not A1 B11 C11 B21 C21 A1 C11 B21 B22 C21 A1 B11 C11 D111 E111 B21 D221 C under next A E under next A Result of Multiple Positioning A1 B11 C11 B12 C12 B13 C13 Not found Not found A1 B11 C11 B12 C12 A1 C11 B11 B12 C12 A1 B11 C11 D111 E111 B12 D112 C12 E121
found found found found
106
Multiple positioning is useful when you want to examine or compare segments in two hierarchic paths. It lets you process different segment types under the same parent in parallel. Without multiple positioning, you would have to issue GU calls to reestablish position in each path.
Advantages of Using Multiple Positioning

The advantages of using multiple positioning are: v You might be able to design your program with greater data independence than you would using single positioning. You can write application programs that use GN and GNP calls, and GU and ISRT calls with missing levels in their SSAs, independent of the relative order of the segment types being processed. If you improve your program's performance by changing the relative order of segment types and all of the application programs that access those segment types use multiple positioning, you could make the change without affecting existing application programs. To do this without multiple positioning, the program would have to use GN and GNP calls, and GU and ISRT calls with incompletely specified SSAs. v Your program can process dependent segment types in parallel (it can switch back and forth between hierarchic paths without reissuing GU calls to reset position) more efficiently than is possible with single positioning. You indicate to IMS the hierarchic path that contains the segments you want in your SSAs in the call. IMS uses the position established in that hierarchic path to satisfy your call. The control blocks that IMS builds for each kind of positioning are the same. Multiple positioning does not require more storage, nor does it have a big impact on performance. Keep in mind that multiple positioning might use more processor time than single positioning, and that multiple positioning cannot be used with HSAM databases.
How Multiple Positioning Affects Your Program

Multiple positioning affects the order and structure of your DL/I calls. GU and ISRT: The only time multiple positioning affects GU and ISRT calls is when you issue these calls with missing SSAs in the hierarchic path. When you issue a GU or ISRT call that does not contain an SSA for each level in the hierarchic path, IMS builds the SSA for the missing levels according to the current position: v If IMS has a position established at the missing level, the qualification IMS uses is derived from that position, as reflected in the DB PCB. v If no position is established at the missing level, IMS assumes a segment type for that level. v If IMS moves forward from a position that is established at a higher level, it assumes a segment type for that level. Because IMS builds the missing qualification based on current position, multiple positioning makes it possible for IMS to complete the qualification independent of current positions that are established for other segment types under the same parent occurrence. DLET and REPL with Multiple Positioning: Multiple positioning does not affect DLET or REPL calls; it only affects the Get Hold calls that precede them. Qualified GN and GNP Calls: When your program issues a GN or GNP call, IMS tries to satisfy the call by moving forward from current position. When you use multiple positioning, more than one current position exist: IMS maintains a
107
position at each level in all hierarchic paths, instead of at each level in one hierarchic path. To satisfy GN and GNP calls with multiple positioning, IMS moves forward from the current position in the path that is referred to in the SSA. Mixing Qualified and Unqualified GN and GNP Calls: Although multiple positioning is intended to be used with qualified calls for parallel processing and data independence, you may occasionally want to use unqualified calls with multiple positioning. For example, you may want to sequentially retrieve all of the segment occurrences in a hierarchy, regardless of segment type. Recommendation: Limit unqualified calls to GNP calls in order to avoid inconsistent results. Mixing qualified and unqualified SSAs may be valid for parallel processing, but doing so might also decrease the program's data independence. There are three rules that apply to mixing qualified and unqualified GN and GNP calls: 1. When you issue an unqualified GN or GNP, IMS uses the position that is established by the preceding call to satisfy the GN or GNP call. For example:
Your program issues these calls: GU A (where AKEY = A1) GN B GN E GN DL/I returns these segments: A1 B11 E11 F111
| | |
When your program issues the unqualified GN call, IMS uses the position that is established by the last call, the call for the E segment, to satisfy the unqualified call. 2. After you successfully retrieve a segment with an unqualified GN or GNP, IMS establishes position in only one hierarchic path: the path containing the segment just retrieved. IMS cancels positions in other hierarchic paths. IMS establishes current position on the segment that is retrieved and sets parentage on the parent of the segment that is retrieved. If you issue a qualified call for a segment in a different hierarchic path after issuing an unqualified call, the results are unpredictable. For example:
Your program issues these calls: GU A (where AKEY = A1) GN B GN E GN GN B DL/I returns these segments: A1 B11 E11 F111 unpredictable
When you issue the unqualified GN call, IMS no longer maintains a position in the other hierarchic path, so the results of the GN call for the B segment are unpredictable. 3. If you issue an unqualified GN or GNP call and IMS has a position established on a segment that the unqualified call might encounter, the results of the call are unpredictable. Also, when you issue an unqualified call and you have established position on the segment that the call should retrieve, the results are unpredictable. For example:
108
Your program issues these calls: GU A (where AKEY = A1) GN E GN D GN B GN B GN DL/I returns these segments: A1 E11 D111 B12 B13 E11 (The only position IMS has is the one established by the GN call.)
In this example, IMS has a position established on E11. An unqualified GN call moves forward from the position that is established by the previous call. Multiple positions are lost; the only position IMS has is the position that is established by the GN call. To summarize these rules: 1. To satisfy an unqualified GN or GNP call, IMS uses the position established in the last call for that PCB. 2. If an unqualified GN or GNP call is successful, IMS cancels positions in all other hierarchic paths. Position is maintained only within the path of the segment retrieved.
Resetting Position with Multiple Positioning

To reset position, your program issues a GU call for a root segment. If you want to reset position in the database record you are currently processing, you can issue a GU call for that root segment, but the GU call cannot be a path call. Example: Suppose you have positions established on segments B11 and E11. Your program can issue one of the calls below to reset position on the next database record. Issuing this call causes IMS to cancel all positions in database record A1:
GU A (AKEY = A2)
Or, if you wanted to continue processing segments in record A1, you issue this call to cancel all positions in record A1:
GU A (AKEY = A1)
Issuing this call as a path call does not cancel position.
Multiple DB PCBs
When a program has multiple PCBs, it usually means that you are defining views of several databases, but this also can mean that you need several positions in one database record. Defining multiple PCBs for the same hierarchic view of a database is another way to maintain more than one position in a database record. Using multiple PCBs also extends what multiple positioning does, because with multiple PCBs you can maintain positions in two or more database records and within two or more hierarchic paths in the same record. Example: Suppose you were processing the database record for Patient A. Then you wanted to look at the record for Patient B and also be able to come back to your position for Patient A. If your program uses multiple PCBs for the medical hierarchy, you issue the first call for Patient A using PCB1 and then issue the next
109
Multiple DB PCBs
call, for Patient B, using PCB2. To return to Patient A's record, you issue the next call using PCB1, and you are back where you left off in that database record. Using multiple PCBs can decrease the number of Get calls required to maintain position and can sometimes improve performance. Multiple PCBs are particularly useful when you want to compare information from segments in two or more database records. On the other hand, the internal control block requirements increase with each PCB that you define. You can use the AIBTDLI interface with multiple PCBs by assigning different PCBNAMEs to the PCBs during PSB generation. Just as multiple PCBs must have different addresses in the PSB PCBLIST, multiple PCBs must have different PCBNAMEs when using the AIBTDLI interface. For example, if your application program issues DL/I calls against two different PCBs in a list that identifies the same database, you achieve the same effect with the AIBTDLI interface by using different PCBNAMEs on the two PCBs at PSB generation time.
110
Chapter 5. Recovering Databases and Maintaining Database Integrity

This chapter describes the programming tasks of issuing checkpoints, restarting programs, and maintaining database integrity. | The following topics provide additional information: v Issuing Checkpoints v Restarting Your Program From the Latest Checkpoint v Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) on page 112 v Reserving Segments for the Exclusive Use of Your Program on page 118
Issuing Checkpoints
Two kinds of checkpoint (CHKP) calls exist: the basic CHKP and the symbolic CHKP. All IMS programs and CICS shared database programs can issue the basic CHKP call; only BMPs and batch programs can use either call. IMS Version 9: Application Programming: Design Guide explains when and why you should issue checkpoints in your program. Both checkpoint calls cause a loss of database position when the call is issued, so you must reestablish position with a GU call or some other method. You cannot reestablish position in the middle of non unique keys or nonkeyed segments. Restriction: You must not specify CHKPT=EOV on any DD statement to take an IMS checkpoint. Some differences exist if you issue the same call sequence against a full-function database or a DEDB, and an MSDB. For more information about the differences, see Commit-Point Processing in MSDBs and DEDBs on page 176. Depending on the database organization, a CHKP call can result in the database position for the PCB being reset. When the CHKP call is issued, the locks held by the program are released. Therefore, if locks are necessary for maintaining your database position, the position is reset by the CHKP call. Position is reset in all cases except those in which the organization is either GSAM (locks are not used) or DEDB, and the CHKP call is issued after a GC status code. For a DEDB, the position is maintained at the unit-of-work boundary. Issuing a CHKP resets the destination of the modifiable alternate PCB. Related Reading: For more information on CHKP calls, see CHKP (Basic) Call on page 253 and CHKP (Symbolic) Call on page 254.
Restarting Your Program From the Latest Checkpoint

If you use basic checkpoints instead of symbolic checkpoints, provide the necessary code to restart the program from the latest checkpoint if the program terminates abnormally.
111
Restarting Your Program and Checking for Position

One way to restart the program from the latest checkpoint is to store repositioning information in a HDAM or PHDAM database. With this method, your program writes a database record containing repositioning information to the database each time a checkpoint is issued. Before your program terminates, it should delete the database record. For more information on the XRST call, see XRST Call on page 290.
Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions)
IMS uses these DL/I calls to back out database updates: ROLB, ROLL, ROLS, SETS, and SETU. The ROLB and ROLS calls can back out the database updates or cancel the output messages that the program has created since the program's most recent commit point. A ROLL call backs out the database updates and cancels any non-express output messages the program has created since the last commit point. It also deletes the current input message. SETS allows multiple intermediate backout points to be noted during application program processing. SETU operates like SETS except that it is not rejected by unsupported PCBs in the PSB. If your program issues a subsequent ROLS call specifying one of these points, database updates and message activity performed since that point are backed out. CICS online programs with DBCTL can use the ROLS and SETS or SETU DL/I calls to back out database changes to a previous commit point or to an intermediate backout point.
Backing Out to a Prior Commit Point: ROLL, ROLB, and ROLS

When a program determines that some of its processing is invalid, some calls enable the program to remove the effects of its incorrect processing. These are the Roll Back calls: ROLL, ROLS using a DB PCB (or ROLS without an I/O area or token), and ROLB. When you issue one of these calls, IMS: v Backs out the database updates that the program has made since the program's most recent commit point. v Cancels the non-express output messages that the program has created since the program's most recent commit point. The main difference between these calls is that ROLB returns control to the application program after backing out updates and canceling output messages, ROLS does not return control to the application program, and ROLL terminates the program with an abend code of U0778. ROLB can return the first message segment to the program since the most recent commit point, but ROLL and ROLS cannot. The ROLL and ROLB calls, and the ROLS call without a specified token, are valid when the PSB contains PCBs for GSAM data sets. However, segments inserted in the GSAM data sets since the last commit point are not backed out by these calls. An extended checkpoint-restart can be used to reposition the GSAM data sets when restarting. You can use a ROLS call either to back out to the prior commit point or to back out to an intermediate backout point that was established by a prior SETS call. This section refers only to the form of the ROLS call that backs out to the prior commit point. For information about the other form of ROLS, see Backing Out to an Intermediate Backout Point: SETS, SETU, and ROLS on page 116.
112
Maintaining Database Integrity

Table 22 summarizes the similarities and the differences between the ROLB, ROLL, and ROLS calls.
Table 22. Comparison of ROLB, ROLL, and ROLS Actions Taken: Back out database updates since the last commit point. Cancel output messages created since the last commit point. Delete from the queue the message in process. Previous messages (if any) processed since the last commit point are returned to the queue to be reprocessed. Return the first segment of the first input message issued since the most recent commit point. U3303 abnormal termination. Returns the processed input messages to the message queue. U0778 abnormal termination. No dump. No abend. Program continues processing. Notes: 1. ROLB, ROLL, or ROLS calls cancel output messages that are sent with an express PCB unless the program issued a PURG. For example, if the program issues the call sequence that follows, MSG1 would be sent to its destination because PURG tells IMS that MSG1 is complete and the I/O area now contains the first segment of the next message (which in this example is MSG2). MSG2, however, would be canceled. ISRT PURG ROLB EXPRESS PCB, MSG1 EXPRESS PCB, MSG2 I/O PCB X X X2 X3 ROLB X X
1
ROLL X X
1
ROLS X X1
Because IMS has the complete message (MSG1) and because an express PCB is being used, the message can be sent before a commit point. 2. Returned only if you supply the address of an I/O area as one of the call parameters. 3. The transaction is suspended and requeued for subsequent processing.
ROLL
A ROLL call backs out the database updates and cancels any non-express output messages the program has created since the last commit point. It also deletes the current input message. Any other input messages that were processed since the last commit point are returned to the queue to be reprocessed. IMS then terminates the program with an abend code U0778. This type of abnormal termination terminates the program without a storage dump. When you issue a ROLL call, the only parameter you supply is the call function, ROLL. You can use the ROLL call in a batch program. If your system log is on DASD, and if dynamic backout has been specified through the use of the BKO execution parameter, database changes made since the last commit point will be backed out; otherwise they will not. One reason for issuing ROLL in a batch program is for compatibility. After backout is complete, the original transaction is discarded if it can be, and it is not re-executed. IMS issues the APPC/MVS verb, ATBCMTP TYPE(ABEND), specifying the TPI to notify remote transaction programs. Issuing the APPC/MVS verb causes all active conversations (including any that are spawned by the application program) to be DEALLOCATED TYP(ABEND_SVC).
113
ROLB
The advantage of using a ROLB call is that IMS returns control to the program after executing a ROLB call, so the program can continue processing. The parameters for the ROLB call are: v The call function, ROLB v The name of the I/O PCB or AIB The total effect of the ROLB call depends on the type of IMS application program that issued it. v For current IMS application programs: After IMS backout is complete, the original transaction is represented to the IMS application program. Any resources that cannot be rolled back by IMS are ignored; for example, output that is sent to an express alternate PCB and a PURG call that is issued before the ROLB call. v For modified IMS application programs: The same consideration for the current IMS application program applies. The application program must notify any spawned conversations that a ROLB was issued. v For CPI-C driven IMS application programs: Only IMS resources are affected. All database changes are backed out. Any messages that are inserted to non-express alternate PCBs are discarded. Also, any messages that are inserted to express PCBs that have not had a PURG call are discarded. The application program must notify the originating remote program and any spawned conversations that a ROLB call was issued. MPPs and Transaction-Oriented BMPs: If the program supplies the address of an I/O area as one of the ROLB parameters, the ROLB call acts as a message retrieval call and returns the first segment of the first input message issued since the most recent commit point. This is true only if the program has issued a GU call to the message queue since the last commit point; it if has not, it was not processing a message when it issued the ROLB call. If the program issues GN call to the message queue after issuing a ROLB call, IMS returns the next segment of the message that was being processed when the ROLB call was issued. If no more segments exist for that message, IMS returns a QD status code. If the program issues a GU call to the message queue after the ROLB call, IMS returns the first segment of the next message to the application program. If no more messages exist on the message queue for the program to process, IMS returns a QC status code. If you include the I/O area parameter, but you have not issued a successful GU call to the message queue since the last commit point, IMS returns a QE status code to your program. If you do not include the address of an I/O area in the ROLB call, IMS does the same thing for you. If the program has issued a successful GU call in the commit interval and then issues a GN call, IMS returns a QD status code. If the program issues a GU call after the ROLB call, IMS returns the first segment of the next message or a QC status code, if no more messages exist for the program.
114

If you have not issued a successful GU call since the last commit point, and you do not include an I/O area parameter on the ROLB call, IMS backs out the database updates and cancels the output messages that were created since the last commit point. Batch Programs: If your system log is on DASD, and if dynamic backout has been specified through the use of the BKO execution parameter, you can use the ROLB call in a batch program. The ROLB call does not process messages as it does for MPPs; it backs out the database updates made since the last commit point and returns control to your program. You cannot specify the address of an I/O area as one of the parameters on the call; if you do, an AD status code is returned to your program. You must, however, have an I/O PCB for your program. Specify CMPAT=YES on the CMPAT keyword in the PSBGEN statement for your program's PSB. Related Reading: For more information on using the CMPAT keyword, see IMS Version 9: Utilities Reference: System. For information on coding the ROLB call, see ROLB Call on page 280.
ROLS
You can use the ROLS call in two ways to back out to the prior commit point and return the processed input messages to IMS for later reprocessing: v Have your program issue the ROLS call using the I/O PCB but without an I/O area or token in the call. The parameters for this form of the ROLS call are: The call function, ROLS The name of the I/O PCB or AIB v Have your program issue the ROLS call using a database PCB that has received one of the data-unavailable status codes. This has the same result as if unavailable data were encountered and the INIT call was not issued. A ROLS call must be the next call for that PCB. Intervening calls using other PCBs are permitted. On a ROLS call with a TOKEN, message queue repositioning can occur for all non-express messages, including all messages processed by IMS. The processing uses APPC/MVS calls, and includes the initial message segments. The original input transaction can be represented to the IMS application program. Input and output positioning is determined by the SETS call. This positioning applies to current and modified IMS application programs but does not apply to CPI-C driven IMS programs. The IMS application program must notify all remote transaction programs of the ROLS. On a ROLS call without a TOKEN, IMS issues the APPC/MVS verb, ATBCMTP TYPE(ABEND), specifying the TPI. Issuing this verb causes all conversations associated with the application program to be DEALLOCATED TYPE(ABEND_SVC). If the original transaction is entered from an LU 6.2 device and IMS receives the message from APPC/MVS, a discardable transaction is discarded rather than being placed on the suspend queue like a non-discardable transaction. See IMS Version 9: Administration Guide: Transaction Manager for more information on LU 6.2. The parameters for this form of the ROLS call are: v The call function, ROLS v The name of the DB PCB that received the BA or BB status code
115

In both of the these parameters, the ROLS call causes a U3303 abnormal termination and does not return control to the application program. IMS keeps the input message for future processing.
Backing Out to an Intermediate Backout Point: SETS, SETU, and ROLS

You can use a ROLS call either to back out to an intermediate backout point that was established by a prior SETS or SETU call, or to back out to the prior commit point. This section refers only to the form of ROLS that backs out to the intermediate backout point. For information about the other form of ROLS, see Backing Out to a Prior Commit Point: ROLL, ROLB, and ROLS on page 112. The ROLS call that backs out to an intermediate point backs out only DL/I changes. This version of the ROLS call does not affect CICS changes that use CICS file control or CICS transient data. The SETS and ROLS calls set intermediate backout points within the call processing of the application program and then backout database changes to any of these points. Up to nine intermediate backout points can be set. The SETS call specifies a token for each point. IMS then associates this token with the current processing point. A subsequent ROLS call using the same token backs out all database changes and discards all non-express messages that were performed after the SETS call with the same token. Figure 32 shows how the SETS and ROLS calls work together. In addition, to assist the application program in managing other variables that it may wish to reestablish after a ROLS call, user data can be included in the I/O area of the SETS call. This data is then returned when the ROLS call is issued with the same token.
Figure 32. SETS and ROLS Calls Working Together
SETS and SETU Calls

The SETS call sets up to nine intermediate backout points or cancels all existing backout points. With the SETS call, you can back out pieces of work. If the
116

necessary data to complete one piece of work is unavailable, you can complete a different piece of work and then return to the former piece. To set an intermediate backout point, issue the call using the I/O PCB, and include an I/O area and a token. The I/O area has the format LLZZuser-data, where LL is the length of the data in the I/O area including the length of the LLZZ portion. The ZZ field must contain binary zeros. The data in the I/O area is returned to the application program on the related ROLS call. If you do not want to save some of the data that is to be returned on the ROLS call, set the LL that defines the length of the I/O area to 4. For PLITDLI, you must define the LL field as a fullword rather than a halfword, as it is for the other languages. The content of the LL field for PLITDLI is consistent with the I/O area for other calls using the LLZZ format. The content is the total length of the area, including the length of the 4-byte LL field, minus 2. A 4-byte token associated with the current processing point is also required. This token can be a new token for this program execution, or it can match a token that was issued by a preceding SETS call. If the token is new, no preceding SETS calls are canceled. If the token matches the token of a preceding SETS call, the current SETS call assumes that position. In this case, all SETS calls that were issued subsequent to the SETS call with the matching token are canceled. The parameters for this form of the SETS call are: v The call function, SETS v The name of the I/O PCB or AIB v The name of the I/O area containing the user data v The name of an area containing the token For the SETS call format, see SETS/SETU Call on page 282. To cancel all previous backout points, the call is issued using the I/O PCB but does not include an I/O area or a token. When an I/O area is not included in the call, all intermediate backout points that were set by prior SETS calls are canceled. The parameters for this form of the SETS call are: v The call function, SETS v The name of the I/O PCB or AIB Because it is not possible to back out committed data, commit-point processing causes all outstanding SETS to be canceled. If PCBs for DEDB, MSDB, and GSAM organizations are in the PSB, or if the program accesses an attached subsystem, a partial backout is not possible. In that case, the SETS call is rejected with an SC status code. If the SETU call is used instead, it is not rejected because of unsupported PCBs, but will return an SC status code as a warning that the PSB contains unsupported PCBs and that the function is not applicable to these unsupported PCBs. Related Reading: For status codes that are returned after the SETS call, see IMS Version 9: Messages and Codes, Volume 1. For explanations of those status codes and the response required, see IMS Version 9: Messages and Codes, Volume 1.
117
ROLS
The ROLS call backs out database changes to a processing point set by a previous SETS or SETU call, or to the prior commit point. The ROLS call then returns the processed input messages to the message queue. To back out database changes and message activity that have occurred since a prior SETS call, issue the ROLS call using the I/O PCB, and specify an I/O area and token in the call. If the token does not match a token that was set by a preceding SETS call, an error status is returned. If the token matches the token of a preceding SETS call, the database updates made since this corresponding SETS call are backed out, and all non-express messages that were inserted since the corresponding SETS are discarded. SETS that are issued as part of processing that was backed out are canceled. The existing database positions for all supported PCBs are reset. If a ROLS call is in response to a SETU call, and if there are unsupported PCBs (DEDB, MSDB, or GSAM) in the PSB, the position of the PCBs is not affected. The token specified by the ROLS call can be set by either a SETS or SETU call. If no unsupported PCBs exist in the PSB, and if the program has not used an attached subsystem, the function of the ROLS call is the same regardless of whether the token was set by a SETS or SETU call. If the ROLS call is in response to a SETS call, and if unsupported PCBs exist in the PSB or the program used an attached subsystem when the preceding SETS call was issued, the SETS call is rejected with an SC status code. The subsequent ROLS call is either rejected with an RC status code, indicating unsupported options, or it is rejected with an RA status code, indicating that a matching token that was set by a preceding successful SETS call does not exist. If the ROLS call is in response to a SETU call, the call is not rejected because of unsupported options. If unsupported PCBs exist in the PSB, this is not reflected with a status code on the ROLS call. If the program is using an attached subsystem, the ROLS call is processed, but an RC status is returned as a warning indicating that if changes were made using the attached subsystem, those changes were not backed out. The parameters for this form of the ROLS call are: v The call function, ROLS v The name of the I/O PCB or AIB v The name of the I/O area to receive the user data v The name of an area containing the 4-byte token Related Reading: For status codes that are returned after the ROLS call, see IMS Version 9: Messages and Codes, Volume 1. For explanations of those status codes and the response required, see IMS Version 9: Messages and Codes, Volume 1.
Reserving Segments for the Exclusive Use of Your Program

You may want to reserve a segment and prohibit other programs from updating the segment while you are using it. To some extent, IMS does this for you through resource lock management. The Q command code lets you reserve segments in a different way. Restriction: The Q command code is not supported for MSDB organizations or for a secondary index that is processed as a database.
118
Reserving Segments
Resource lock management and the Q command code both reserve segments for your program's use, but they work differently and are independent of each other. To understand how and when to use the Q command code and the DEQ call, you must understand resource lock management. The function of resource lock management is to prevent one program from accessing data that another program has altered until the altering program reaches a commit point. Therefore, you know that if you have altered a segment, no other program (except those using the GO processing option) can access that segment until your program reaches a commit point. For database organizations that support the Q command code, if the PCB processing option allows updates and the PCB holds position in a database record, no other program can access the database record. The Q command code allows you to prevent other programs from updating a segment that you have accessed, even when the PCB that accessed the segment moves to another database record. Related Reading: For more information on the Q command code, see Q Command Code on page 208.
119
Reserving Segments
120
Chapter 6. The Database Resource Adapter (DRA)

The DRA is an interface to IMS DB full-function databases and data entry databases (DEDBs). The DRA can be used by a coordinator controller (CCTL) or a z/OS application program that uses the Open Database Access (ODBA) interface. This chapter is intended for the designer of a CCTL or an z/OS application program. If you want more information about a specific CCTL's interaction with IMS DB or DB/DC, see the documentation for that CCTL. Related Reading: v For additional information on defining the ODBA interface, see IMS Version 9: Installation Volume 2: System Definition and Tailoring v For information on designing application programs that use ODBA, see IMS Version 9: Application Programming: Design Guide The following topics provide additional information: v Thread Concepts v Sync Points on page 124 v DRA Startup Table on page 128 v Enabling the DRA for a CCTL on page 129 v v v v v v Enabling the DRA for the ODBA Interface on page 130 Processing CCTL DRA Requests on page 131 Processing ODBA Calls on page 132 CCTL-Initiated DRA Function Requests on page 132 PAPL Mapping Format on page 141 Terminating the DRA on page 141
v Designing the CCTL Recovery Process on page 142 v CCTL Performance: Monitoring DRA Thread TCBs on page 143
Thread Concepts
A DRA thread is a DRA structure that connects: v A CCTL task (which makes database calls to IMS DB) with an IMS DB task that can process those calls. A CCTL thread is a CCTL task that issues IMS DB requests using the DRA. v A z/OS application program task (which makes database calls to IMS DB) with an IMS DB task that can process those calls. An ODBA thread is a z/OS task that issues IMS DB calls using the DRA. A single DRA thread is associated with every CCTL or ODBA thread. CCTL or ODBA threads cannot establish a connection with more than one DRA thread at a time.
Processing Threads
The way that the DRA processes a CCTL thread is different from how it processes an ODBA thread.
121
Thread Concepts
Processing a CCTL Thread

When a CCTL application program needs data from an IMS DB database, a CCTL task must issue a SCHED request for a PSB. To process the SCHED request, the DRA must create a DRA thread. To do this, the DRA chooses an available DRA thread TCB and assigns to it the CCTL thread token (a unique token that CCTL puts in the SCHED PAPL PAPLTTOK) and its own IMS DB task, which schedules the PSB. If the scheduling is successful, the DRA thread is considered complete because it now connects a CCTL thread to a IMS DB task using a specific DRA thread TCB. Subsequent DRA requests from this CCTL thread must use the same CCTL thread token in order to ensure that the request goes to the correct DRA thread. When the application program finishes and the CCTL thread no longer needs the services of the DRA thread, the CCTL issues a TERMTHRD (Terminate Thread) request to remove the CCTL thread token from the DRA thread TCB and terminates the DRA thread. The thread TCB can then become part of a new DRA thread.
Processing an ODBA Thread

When an z/OS application program needs data from an IMS DB database, an ODBA task must issue an APSB call to initialize the ODBA environment. To process the APSB call, the DRA creates a DRA thread. The DRA chooses an available DRA thread TCB and assigns to it the ODBA thread and its own IMS DB task, which schedules the PSB. If the scheduling is successful, the DRA thread is considered complete because it now connects an ODBA thread to a IMS DB task using a specific DRA thread block. When the application program finishes and the ODBA thread no longer needs the services of the DRA thread, the z/OS application issues a DPSB call to terminate the DRA thread. The thread block can then become part of a new DRA thread.
Processing Multiple Threads

The DRA is capable of processing more than one thread at the same time. This is known as multithreading. Multithreading means that multiple CCTL or ODBA threads can be using the DRA at the same time. Multithreading applies to all DRA requests and ODBA calls.
Processing Multiple CCTL Threads

To use the multithreading capability: v The DRA must be initialized with more that one thread TCB. To initialize the DRA with more that one thread TCB, specify the MINTHRD and MAXTHRD parameters (in the DRA Startup Table) as greater than one. v The CCTL must be capable of processing its CCTL threads concurrently. v The CCTL must have Suspend and Resume exit routines. The DRA uses these routines to notify the CCTL of the status of thread processing.
Processing Multiple ODBA Threads

To use the multithreading capability, the DRA must be initialized with more than one DRA thread. To do this, specify the MINTHRD and MAXTHRD parameters (in the DRA Startup Table) as greater than one.
CCTL Multithread Example

Events in a multithreading system are shown in chronological order from top to bottom in Table 23 on page 123. To illustrate the concept of concurrent processing, the figure is split into two columns.
122
Thread Concepts
There are two CCTL threads and two DRA threads in the example. xxxRTNA is the module name (for this example) of the CCTL routine that builds PAPLs and calls DFSPRRC0 to process DRA requests.
Table 23. Example of Events in a Multithreading System CCTL TCB Events Application program1 needs a PSB, so CCTL thread1 is created. CCTL thread1 events: v DFSRTNA builds the SCHED PAPL and calls DFSPRRC0. v DFSPRRC0 creates a DRA thread, and the thread token (PAPLTTOK) is assigned to DRA thread TCB1. v DFSPRRC0 activates thread TCB1. v DFSPRRC0 calls the Suspend exit routine. v The Suspend exit routine suspends CCTL thread1. v The DRA processes the SCHED request and asks IMS DB to perform a schedule process. v Scheduling is in progress. CCTL can now dispatch other CCTL threads for the CCTL TCB. Application program2 needs a PSB, so CCTL thread2 is created. CCTL thread2 events: v DFSRTNA builds the SCHED PAPL and calls DFSPRRC0. v DFSPRRC0 creates a DRA thread, and a new thread token (PAPLTTOK) is assigned to DRA thread TCB2. v DFSPRRC0 activates thread TCB2. v DFSPRRC0 calls the Suspend exit routine. The Suspend exit routine suspends CCTL thread2. DRA thread TCB2 events: DRA thread TCB1 events: DRA TCB Events
v The DRA processes the SCHED request and asks IMS DB to perform a schedule process. v Scheduling is in progress. Both threads are now suspended. The CCTL TCB is inactive until one of the threads resumes execution. TCB2 scheduling finishes first. DRA thread TCB2 events: v Scheduling completes in IMS DB, and the PAPL is filled in with the results. v The DRA calls the Resume exit routine and passes the PAPL back to the CCTL.
123
Thread Concepts
Table 23. Example of Events in a Multithreading System (continued) CCTL TCB Events DRA TCB Events
Thread2 can resume immediately because the v The Resume exit routine sees the thread CCTL TCB is idle. It resumes execution token (PAPLTTOK) and flags CCTL directly after the point at which it was thread2 as 'ready to resume'. suspended by the Suspend exit routine. v The Resume exit routine returns to the DRA, and TCB2 becomes inactive. TCB1 scheduling completes. DRA thread TCB1 events: v Scheduling completes in IMS DB and the PAPL is filled in with the results. v The DRA calls the Resume exit routine and passes the PAPL back to the CCTL. Thread1 must wait until the Resume exit routine is available because thread2 has just resumed. v The Resume exit routine sees the thread token (PAPLTTOK) and flags CCTL thread1 as 'ready to resume'. v The Resume exit routine returns control to the DRA and TCB1 becomes inactive. CCTL thread2 events: v The Suspend exit routine returns to its caller, DFSPRRC0. v DFSPRRC0 returns to DFSRTNA. v DFSRTNA gets the results from the SCHED PAPL and gives them to the application program2. v DFSRTNA finishes the thread2 SCHED request. After thread2 completes in CCTL TCB, the CCTL can dispatch thread1, which is currently waiting. CCTL thread1 events: v The Suspend exit routine returns to its caller, DFSPRRC0. v DFSPRRC0 returns to DFSRTNA. v DFSRTNA gets the results from the SCHED PAPL and gives them to the application program1. v DFSRTNA finishes the thread1 SCHED request.
Sync Points
Sync point processing finalizes changes to resources. Sync point requests specify actions to take place for the resource changed (for example, commit or abort). A sync point is when IMS DB actually processes the request. Each sync point is based on a unit of recovery (UOR). A UOR covers the time during which database resources are allocated and can be updated until a request is received to commit or abort any changes. Normally, the UOR starts with a CCTL SCHED (schedule a PSB) request or an ODBA APSB call and ends with a sync point request. Other DRA thread requests can also define the start and end of a UOR.
124
Sync Points
A CCTL UOR is identified by a recovery token (PAPLRTOK) that is received as part of a thread request that creates a new UOR. It is 16 bytes in length. The first 8 bytes contain the CCTL identification. This identification is the same as the CCTL ID that was a final DRA startup parameter determined from USERID or PAPLUSID in INIT request. The second 8 bytes must be a unique identifier specified by the CCTL for each UOR. Related Reading: See the request descriptions under CCTL-Initiated DRA Function Requests on page 132 for more information on the DRA thread requests. IMS DB expects the CCTL or the z/OS application to make the sync point decision and the resulting request. In the case of a CCTL, the CCTL is the sync point manager and coordinates the sync point process with all of the database resource managers (including those other than IMS DB) that are associated with a UOR. In the case of an z/OS application, RRS/MVS is the sync point manager and coordinates all the resource managers (including those other than IMS) that are associated with the UOR. A CCTL working with a single resource manager may request a sync point in a single request or can use the two-phase sync point protocol which is required for a CCTL working with multiple resource managers. The single-phase sync point request can be issued when the CCTL has decided to commit the UOR, and when IMS DB owns all of the resources modified by the UOR. An z/OS application must use the two-phase sync point protocol for committing changes to the IMS database.
The Two-Phase Commit Protocol

The two-phase sync point protocol consists of two requests issued by the sync point manager to each of the resource managers involved in the UOR: Phase 1 Phase 2 The sync point manager asks all participants if they are ready to commit a UOR. The sync point manager tells each participant to commit or abort based on the response to the request issued in phase 1.
A UOR has two states: in-flight and in-doubt. The UOR is in an in-flight state from its creation time until the time IMS DB logs the phase 1 end (point C in Table 24 on page 126 and Table 25 on page 126). The UOR is in an in-doubt state from (point C) until IMS DB logs phase 2 (point D inTable 24 on page 126 and point H in Table 25 on page 126). The in-doubt state for a single-phase sync point request is a momentary state between points C and D in Table 24 on page 126. The in-flight and in-doubt states are important because they define what happens to the UOR in the event of a thread failure. If a thread fails while its IMS DB UOR is in-flight the UOR database changes are backed out. If a thread fails when its IMS DB UOR is in-doubt, during single-phase commit, the UOR database changes are kept for an individual thread abend, but are not kept for a system abend. If a thread fails when its IMS DB UOR is in-doubt during two-phase commit, the database changes are kept. Thread failure refers to either of these cases: v Individual thread abends.
125
Sync Points
v System abends: IMS DB failure, CCTL failure, z/OS application failure, or z/OS failure (which abends all threads). The following shows the system events that occur when CCTL is used for single-phase sync point processing.
Time ABCDE Table 24. CCTL Single-Phase Sync Point Processing Points In Time A B C D E System Events CCTL phase 1 send IMS DB phase 1 receive IMS DB log phase 1 end IMS DB log phase 2 CCTL phase 2 receive
Table 25 shows the system events that occur when CCTL is used for two-phase sync point processing.
Time ABCDEFGHJK Table 25. CCTL Two-Phase Sync Point Processing Points In Time A B C D E F G H J K System Events CCTL phase 1 send IMS DB phase 1 receive IMS DB log phase 1 end IMS DB phase 1 respond CCTL phase 1 receive CCTL phase 2 send IMS DB phase 2 receive IMS DB log phase 2 IMS DB phase 2 respond CCTL phase 2 receive
Figure 33 on page 127 shows the system events that occur when two-phase sync point processing is done using ODBA.
126
Sync Points
Figure 33. ODBA Two-Phase Sync Point Processing
Notes: 1. The z/OS application and IMS DB make a connection using the ODBA interface. 2. IMS expresses protected interest in the work started by the z/OS application. This informs RRS/MVS that IMS will participate in the two-phase commit process. 3. The z/OS application makes a read request to an IMS resource. 4. The z/OS application updates a protected resource. 5. Control is returned to the z/OS application following its update request. 6. The z/OS application requests that the update be made permanent by issuing the SRRCMIT call. 7. RRS/MVS calls IMS to do the prepare (phase 1) process. 8. IMS returns to RRS/MVS with its vote to commit. 9. RRS/MVS calls IMS to do the commit (phase 2) process. 10. IMS informs RRS/MVS that it has completed phase 2. 11. Control is returned to the z/OS application following its commit request.
In-Doubt State During Two-Phase Sync

A IMS DB UOR remains in the in-doubt state until a phase 2 request is received. This process is called resolving the in-doubt. While a UOR is in-doubt, the database resources owned by that UOR are inaccessible to other requests. It is vital that in-doubts are resolved immediately. CCTL Example: If in-doubt UORs are created because IMS DB failed, the following sequence must occur to resolve the in-doubt UORs. 1. After restarting IMS DB, the CCTL should identify itself to IMS DB using an INIT request.
127
Sync Points
2. If identification is successful, the DRA notifies the CCTL control exit, passing to it a list of IMS DB UORs that are in-doubt. 3. The CCTL must resolve each in-doubt by making a RESYNC call, which causes a phase 2 action, commit or abort. For CCTL to resolve a IMS DB in-doubt UOR, the CCTL must have a record of this UOR and the appropriate phase 2 action it must take. In this example, the CCTL record of a possible IMS DB in-doubt UOR is called a transition UOR. 4. The CCTL must define a transition UOR for the interval A-K (refer to Table 25 on page 126). Because this interval encompasses the IMS DB in-doubt period C-H, CCTL can resolve any in-doubts. If a CCTL defines a transition UOR as interval E-K and if IMS DB fails while a thread is between C and D, IMS DB has an in-doubt UOR for which CCTL has no corresponding transition UOR, even though the phase 1 call failed. CCTL cannot resolve this UOR during the identify process. The only way to resolve this in-doubt is by using the IMS DB command, CHANGE INDOUBT. ODBA Example: For ODBA, all in-doubts are resolved through z/OS using the Recoverable Resource Service (RRS).
DRA Startup Table

The database resource adapter (DRA) Startup Table contains values used to define the characteristics of the DRA. The DRA Startup Table is created by assembling: v The DFSPZPxx module for a CCTL's use. v The DFSxxxx0 module for ODBA's use. The CCTL or ODBA system programmer must make the required changes to these modules to correctly specify the DRA parameters desired. The DRA parameters are specified as keywords on the DFSPRP macro invocation. These keywords and their definitions are found in DFSPRP Macro Keywords.
Sample DFSPZP00 Source Code

DFSPZP00 CSECT DFSPRP DSECT=NO END
DFSPRP Macro Keywords

Keyword AGN= Description A one-to-eight character application group name. This is used as part of the IMS DB and DB/DC security function (see IMS Version 9: Administration Guide: System for more information on IMS DB and DB/DC security). Total Fast Path NBA buffers for the CCTL's or ODBA's use. For a description of Fast Path DEDB buffer usage, see IMS Version 9: Administration Guide: System. The four-character name of the IMS DB or DB/DC region. This is the same as the IMSID parameter in the DBC procedure. For more information on the DBC procedure, see IMS Version 9: Installation Volume 2: System Definition and Tailoring. The default name is SYS1. A one-to-eight character ddname used with the dynamic allocation of the IMS DB execution library. The default ddname is CCTLDD.
CNBA=
DBCTLID=
DDNAME=
128
DRA Startup Table

DSNAME= A 1-to-44 character data set name of the IMS DB execution library, which must contain the DRA modules and must be z/OS authorized. The default DSNAME is IMS.SDFSRESL. This library must contain the DRA modules. The number of Fast Path DEDB overflow buffers allocated per thread. For a description of Fast Path DEDB buffer usage, see IMS Version 9: Administration Guide: System. The default is 00. The number of Fast Path DEDB buffers allocated and fixed per thread. For a description of Fast Path DEDB buffer usage, see IMS Version 9: Administration Guide: System. The default is 00. Specifies the DRA level that the CCTL or ODBA supports. The default is 1. The number of times a z/OS application region is to attempt to IDENTIFY (or attach) to IMS after the first IDENTIFY attempt fails. The maximum number 255. The default is 0. The maximum number of DRA thread TCBs available at one time. The maximum number is 999. The default is number 1. The minimum number of DRA thread TCBs to be available at one time. The maximum number is 999. The default is number 1. The output class used for a SNAP DUMP of abnormal thread terminations. The default is A. (CCTL only). The amount of time (in seconds) a CCTL waits for the successful completion of a DRA TERM request. Specify this value only if the CCTL application is coded to use it. This value is returned to the CCTL upon completion of an INIT request. The time (in seconds) between attempts of the DRA to identify itself to IMS DB or DB/DC during an INIT request. The default is 60 seconds. An eight-character name of the CCTL or ODBA region. This keyword is ignored for an ODBA Region.
FPBOF=
FPBUF=
FUNCLV= IDRETRY=
MAXTHRD= MINTHRD= SOD= TIMEOUT=
TIMER=
USERID=
Enabling the DRA for a CCTL

This section describes the two steps required to enable the DRA. 1. The coordinator controller (CCTL) system programmer must copy the DRA Startup/Router routine (DFSPRRC0) into a CCTL load library, because the CCTL must load DFSPRRC0. Although the DRA is shipped with the IMS product, it runs in the CCTL address space. The system programmer can copy the routine from the IMS.SDFSRESL library (built by the IMS definition process), or can concatenate the IMS.SDFSRESL library to the ODBA step library. 2. The system programmer must put the DFSPZPxx load module (DRA Startup Table) in a load library. The DRA is now ready to be initialized. The CCTL starts the initialization process as a result of the CCTL application program issuing an initialization (INIT) request. The CCTL loads DFSPRRC0 and then calls the DRA to process the INIT request.
129
DRA Startup Table

As part of the initialization request, the CCTL application program specifies the startup table name suffix (xx). The default load module, DFSPZP00, is in the IMS.SDFSRESL library. After processing the INIT request, the DRA identifies itself to IMS DB. The DRA is then capable of handling other requests. Related Reading: For an example of DFSPZP00, see IMS Version 9: Installation Volume 2: System Definition and Tailoring. DFSPZP00 contains default values for the DRA initialization parameters. If you want to specify values other than the defaults, write your own module (naming it DFSPZPxx), assemble it, and load it in the CCTL load library. Use the supplied module, DFSPZP00, as an example. The remainder of the DRA modules reside in a load library that is dynamically allocated by DFSPRRC0. The DDNAME and DSNAME of this load library are specified in the startup table. The default DSNAME (IMS.SDFSRESL) contains all the DRA code and is specified in the default startup table, DFSPZP00.
Enabling the DRA for the ODBA Interface

There are four steps required to enable the DRA before an ODBA interface can use it: 1. Create the ODBA DRA Startup Table. 2. Verify that the ODBA and DRA modules reside in the STEPLIB or JOBLIB in the z/OS application region. 3. Link the z/OS application programs with DFSCDLI0. 4. Set up security. These steps are described in detail in the IMS Version 9: Installation Volume 2: System Definition and Tailoring. | | | | | The ODBA interface starts the initialization process as a result of the z/OS application program issuing an initialization (CIMS INIT) request or an APSB call. The ODBA interface calls the DRA to process the CIMS INIT request or APSB call. Optionally, the z/OS application program can specify the DRA startup table name (xxxx) in the AIBRSNM2 field of the AIB. After processing the CIMS INIT request, the DRA identifies itself to one IMS DB. The DRA is then capable of handling other requests. The DRA's structure at this time is shown in Figure 34 on page 131.
130
Enabling the DRA for the ODBA Interface
Figure 34. DRA Component Structure with the ODBA Interface
The remainder of the DRA modules reside in a load library that is dynamically allocated by DFSAERA0. The DDNAME and DSNAME of this load library are specified in the startup table. The default DSNAME (IMS.SDFSRESL) contains all the DRA code.
Processing CCTL DRA Requests

The CCTL communicates with IMS DB through DRA requests. These requests are passed from the CCTL to the DRA using a participant adapter parameter list (PAPL). See Chapter 6, The Database Resource Adapter (DRA), on page 121 for a sample PAPL listing. There are different types of DRA requests shown in the sample PAPL listing. To make a DRA request the CCTL must pass control to the DRA Startup/Router Routine DFSPRRC0, and have register 1 point to a PAPL. Before passing control to DFSPRRC0, the CCTL must fill in the PAPL according to the desired request. These requests are specified by a function code in the PAPLFUNC field. To specify a thread function request, put the PAPLTFUN value into the PAPLFUNC field. The function requests are further broken down into many subfunctions. A thread function request is referred to by its subfunction name (for example, a thread request with a schedule subfunction is referred to as a SCHED request). Non-thread function requests are referred to by function name (for example, an initialization request is called an INIT request). The term DRA request applies to both thread and non-thread function requests. Once the PAPL is built and the DRA Startup/Router routine is loaded, the CCTL passes control to DFSPRRC0. The contents of the registers upon entry to DFSPRRC0 are: Register 1 13 14 Contents Address of the PAPL Address of a standard 18-word save area Return address of the calling routine
131
Processionally DRA Requests

The DRA Startup/Router routine puts itself into 31-bit addressing mode and will return to the calling routine in the caller's original addressing mode with all its registers restored. Register 15 is always returned with a zero in it. The return code for the request is in the PAPLRETC field of the PAPL.
Processing ODBA Calls

Unlike a CCTL's use of the PAPL, an z/OS application program communicates with IMS DB using the AERTDLI interface. The AERTDLI call interface processes DL/I calls from the z/OS application and also returns the results of those calls back to the z/OS application using an AIB. Related Reading: For information on using the AIB mask for configuring ODBA calls, see Specifying the AIB Mask for ODBA Applications on page 74.
CCTL-Initiated DRA Function Requests

This section documents General-Use Programming Interface and Associated Guidance Information. This section discusses the requests available to the CCTL that allow it to communicate with DBCTL. These requests are passed to the DRA through the PAPL. For all DRA requests, there are PAPL fields that the CCTL must fill in. When the DRA completes the request, there are some output PAPL fields that the DRA fills in. Some fields in the returned PAPL might contain the original input value. (The PAPLTTOK and PAPLUSER fields will retain the original input values.) The PAPLUSER field is a field to be used at the CCTL's discretion. One possible use for it is to pass data to exit routines. The DRA returns a code (in the PAPLRETC field) to the CCTL after processing a DRA request. The code indicates the status of the request and can be either an IMS code, a DRA code, or a z/OS code. Failed DRA requests return a nonzero value in the PAPLRETC field. Related Reading: v See Problem Diagnosis on page 146 for more information on the codes returned when a DRA request fails. v For a complete list and description of all DRA return codes, see IMS Version 9: Messages and Codes, Volume 1.
INIT Request
| | | | The INIT request initializes the DRA. The DRA startup parameter table contains all of the required parameters that you need to define the DRA. You can use the parameters given in the default module, DFSPZP00, or you can write your own module and bind it into the IMS.SDFSRESL. Related Reading: For more information, see Enabling the DRA for a CCTL on page 129.
132

The INIT PAPL also contains some parameters needed to initialize the DRA. If the same parameter appears in both the INIT PAPL and in the DRA startup parameter table, the specification in the INIT PAPL will override that in the startup table. In addition to the required parameters of INIT PAPL, the optional parameters include: Field PAPLFUNC PAPLSUSP PAPLRESM PAPLCNTL PAPLTSTX Contents PAPLINIT The address of the Suspend exit routine The address of the Resume exit routine The address of the Control exit routine The address of the Status exit routine
After the INIT request and the startup table have been processed, the DRA returns the following data to the CCTL in the INIT PAPL: Field PAPLDBCT PAPLCTOK PAPLTIMO PAPLRETC PAPLDLEV Contents The IMS DB identifier (this is the IMSID parameter from system definition) The request token that identifies the CCTL to the DRA DRA TERM request timeout value (in seconds) A code returned to the CCTL specifying the status of the request A flag indicating to CCTL which functions the DRA supports. (For the latest version of PAPL mapping format see the IMS. library; member name is DFSPAPL.)
INIT Request, Identify to DBCTL

To make the DRA functional, the DRA must identify itself to IMS DB, thus establishing a link between IMS DB and the CCTL. The identify process occurs in two cases: v As a direct result of an INIT request. v As part of a terminate/reidentify request from a Control exit routine invocation. The DRA identifies itself to the IMS DB subsystem specified in the final DRA startup parameters. The identify process executes asynchronously to the INIT process. Therefore, it is possible for the INIT request to complete successfully while the identify process fails. In this case, the Control exit routine notifies the CCTL that the connection to IMS DB failed. If IMS DB is not active, the console operator will receive a DFS690 message (a code of 0 was returned in the PAPLRETC field). You must reply with either a CANCEL or WAIT response. If you reply with WAIT, the DRA waits for a specified time interval before attempting to identify again. The waiting period is necessary because the identify process won't succeed until the DBCTL restart process is complete. You specify the length of the waiting period on the TIMER DRA startup parameter. If subsequent attempts to identify fail, the console operator will receive message DFS691, WAITING FOR IMS DB. If the DRA cannot identify to IMS DB because the subsystem does not reach a restart complete state, there are two ways to terminate the identify process:
133

v The Control exit routine is called with each identify failure. This sets a PAPL return code of 4 or 8, which terminates the identify process. v The CCTL can issue a TERM request. If you reply with CANCEL to message DFS690, control is passed to the Control exit routine, and the DRA acts upon the routine's decision. After the identify process successfully completes, the DRA makes the CCTL address space non-swappable and calls the Control exit routine with a list of in-doubt UORs. If no in-doubt UORs exist, a null list is passed. The CCTL can use the RESYNC request to resolve any in-doubt UORs that do exist. The INIT request will attempt to create the MINTHRD number of thread TCBs. The actual number of TCBs created might be less than this value due to storage constraints.
INIT Request after a Previous DRA Session Termination

If a prior DRA session ended with a TERM request that received a PAPL return code=0, this INIT request must specify PAPLCTOK=0. If PAPLCTOK other than 0 is sent, the INIT request will fail. The INIT request must pass the PAPLCTOK value of the prior session in the current PAPLCTOK field if a DRA session ended because of: v A nonzero return code from a TERM request. v An internal TERM request from a Control exit routine request. v A DRA failure.
RESYNC Request
The RESYNC request tells IMS DB what to do with in-doubt UORs. The 4 following subfunction values indicate possible actions: PAPLRCOM PAPLRABT PAPLSCLD PAPLSUNK Commit the in-doubt UOR. Abort the in-doubt UOR. Changes made to any recoverable resource are backed out. The UOR was lost to the transaction manager due to a coldstart. The in-doubt UOR is unknown to the CCTL. This can occur when the CCTL's in-doubt period does not include the start of phase 1. (See Table 25 on page 126 for an illustration of in-doubt periods.)
You must fill in the following input fields of the PAPL: Field PAPLCTOK Contents Request token This token identifies the CCTL to the DRA. The DRA establishes the token and returns it to the CCTL in the parameter list on the startup INIT request. The request token must be passed on to the DRA for all RESYNC requests. PAPLRTOK Recovery token This 16-byte token is associated with a UOR. The first 8 bytes must be the transaction manager subsystem ID. The second 8 bytes must be unique for one CCTL thread. This is one of the in-doubt recovery tokens passed to the Control exit routine.
134

PAPLFUNC | | PAPLSNC PAPLRSYN This field must contain PAPLRCOM, PAPLRABT, PAPLSCLD, or PAPLSUNK.
TERM Request
The TERM request results in a termination of the IMS DB/CCTL connection and a removal of the DRA from the CCTL environment. The DRA terminates after all threads have been resolved. No new DRA or thread requests are allowed, and current requests in progress must complete. You must fill in the following input fields in the PAPL: Field PAPLFUNC PAPLCTOK Contents PAPLTERM, DRA terminate function code The DRA request token (output from an INIT request)
After receiving the TERM request results, the CCTL may remove DFSPPRC0. The fields returned in the PAPL to the CCTL are: Field PAPLRETC PAPLMXNB PAPLMTNB PAPLHITH PAPLTIMX Contents The return code The number of times the maximum thread count was encountered during this DRA session The number of times the minimum thread count was encountered during this DRA session The largest number of thread TCBs that were scheduled during this DRA session The elapsed time at maximum thread for this DRA session
Thread Function Requests

The Thread Function requests consist of the SCHED, IMS, SYNTERM, PREP, COMTERM, ABTTERM, and TERMTHRD requests and are described in the following topics: v SCHED Request v IMS Request on page 137 v SYNTERM Request on page 138 v PREP Request on page 139 v COMTERM Request on page 139 v ABTTERM Request on page 140 v TERMTHRD Request on page 140
SCHED Request
The SCHED request schedules a PSB in IMS DB. The first SCHED request made by a CCTL thread requires a new DRA thread. If any existing DRA thread TCBs are not currently processing a DRA thread, one of these is used. If no TCBs are available, the DRA either creates a new thread TCB (until the maximum number of threads as specified by the MAXTHRD parameter in the INIT request is reached), or makes the SCHED request wait until a thread becomes available.
135

The value in the PAPLWCMD field indicates whether the thread to which the SCHED request applies is a short or long thread. The type of thread determines the action that IMS takes when a database command is entered for a database scheduled to the thread. The /STOP DATABASE, /DBDUMP DATABASE, or /DBRECOVERY DATABASE command issued against a database scheduled on a short thread will wait for the database to be unscheduled. IMS rejects these commands if they are entered for a database scheduled on a long thread. You must fill in the following input fields in the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLTTOK PAPLRTOK PAPLPSB PAPLWRTH Contents PAPLTFUN, thread function code PAPLSCHE, schedule request subfunction code The DRA request token (output from an INIT request) The thread token set up by the CCTL The 16-byte UOR token (RTOKEN). For more information about UORs, see Sync Points on page 124. The PSB name Deadlock Worth Value If this thread hits a deadlock condition with any other DRA thread or with any IMS region, DBCTL collapses the thread with the lower deadlock worth value. PAPLWCMD This bit defines the thread as either a short or long thread which determines what action IMS takes on a /STOP DATABASE, /DBDUMP DATABASE, or /DBRECOVERY DATABASE command for a database scheduled to the thread. If the bit is set on (X'80'), the database is scheduled on a short thread; if the bit is set off, the database is scheduled for a long thread. Fast Path Trace Option If this bit is on (X'40'), Fast Path tracing in IMS DB is activated. (For more information, see Tracing on page 146 in CCTL Performance: Monitoring DRA Thread TCBs on page 143.) PAPLKEYP Public Key Option If this bit is set (X'10'), DBCTL will build UPSTOR area in a special subpool so that applications running in public key can fetch the UPSTOR area. PAPLLKGV Lockmax Option If this bit is set (X'08'), DBCTL uses the value in PAPLLKMX as the maximum number of locks that this UOR can hold. Exceeding the maximum results in a U3301 abend. PAPLLKMX Lockmax Value, 0 to 255 This value overrides any LOCKMAX parameter specified on the PSBGEN for the PSB referenced in the SCHED request. PAPLALAN Application language type
PAPLFTRD
Specifying the following input field is optional: Field Contents
136

PAPLSTAT PAPLPBTK Address of an area where scheduled statistical data is returned to the CCTL. Address of the token for the z/OS Workload Manager performance block obtained by the CCTL. You must specify this field for z/OS Workload Manager support for DRA threads. The output fields returned in the PAPL to the CCTL are: Field PAPLRETC PAPLCTK2 PAPLPCBL Contents The return code The thread request token number 2. This is another DRA token required on future DRA requests originating from this thread. The address of the PCB list. There is one entry in the list for each PCB in the PSB that was scheduled, even if the PCB cannot be used with IMS DB. The address of the PCBLIST entry pointing to the first database PCB The size of the maximum I/O area The language type of the PSB The maximum key length The address of the schedule statistical data area. This address must be specified on the input field.
PAPL1PCB PAPLIOSZ PAPLPLAN PAPLMKEY PAPLSTAT
CCTLs currently using the IMS Database Manager and migrating to DBCTL will experience a change in the PCBLIST and user PCB area on a schedule request. The first PCB pointer in the PCBLIST contains the address of an I/O PCB. The I/O PCB is internally allocated during the schedule process in a DBCTL environment. The I/O PCB is normally used for output messages or to request control type functions to be processed. The PCBLIST and the PCBs reside in a contiguous storage area known as UPSTOR. If the PSB was generated with LANG=PLI, the PCBLIST points to pointers for the PCBs. If LANG= was not PLI, the PCBLIST points to the PCBs directly.
IMS Request
This request makes an IMS or Fast Path database request against the currently scheduled PSB. You must fill in the following input fields in the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK PAPLRTOK Contents PAPLTFUN PAPLDLI, DL1 request subfunction code DRA request token (output from an INIT request) Thread Token number 2. This is the DRA request token that is part of the output from a SCHED request. Thread token set up by the CCTL RTOKEN
137

A 16-byte UOR token. See Sync Points on page 124 for more information about UORs. PAPLCLST PAPLALAN The address of an IMS call list. See Chapter 3, Defining Application Program Elements, on page 53 for call list formats. Application language type. This must reflect how the call list is set up. If PAPLALAN=PLI, the DRA expects the call list to contain pointers to the PCB's pointers. For any other programming language, the DRA expects direct pointers. PAPLALAN does not have to match PAPLPLAN which schedules request returns. For example, if PAPLPLAN=PLI, the PCBLIST in UPSTOR points to an indirect list. If desired, the CCTL can use this to create a PCBLIST that application programs use. If the application programs are written in COBOL, the CCTL may create a new PCBLIST without pointers as long as the new list actually points to PCBs in UPSTOR. The application program IMS call lists can specify PAPLALAN=COBOL, and the DRA will not expect pointers in the call list. The output fields returned in the PAPL to the CCTL are: Field PAPLRETC PAPLSEGL Contents Code returned Length of data returned
SYNTERM Request
This is a single-phase sync point request to commit the UOR. It also releases the PSB. You must fill in the following input fields in the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK PAPLRTOK Contents PAPLTFUN PAPLSTRM, sync point commit/terminate subfunction code DRA request token (output from INIT request) The thread request token number 2. This DRA token is the output from the SCHED request. The thread token set up by the CCTL A 16-byte UOR token (RTOKEN). For information on UORs see Sync Points on page 124.
You can specify the following, optional input fields: Field PAPLSTAT Contents Address of an area where transaction statistical data is returned to the CCTL.
The output fields returned in the PAPL to the CCTL are: Field PAPLRETC Contents Code returned
138

PAPLSSCC PAPLSTAT State of the single-phase sync point request at the time of the thread failure. This field is set if PAPLRETC is not equal to zero. The address of the transaction statistical data area. The address must be specified on the input field.
PREP Request
This is a phase 1 sync-point request that asks IMS DB if it is ready to commit this UOR. You must fill in the following input fields of the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK PAPLRTOK Contents PAPLTFUN PAPLPREP, sync-point prepare subfunction code DRA request token (output from an INIT request) Thread Token number 2. This is the DRA request token which is output from a SCHED request. The thread token set up by the CCTL A 16-byte UOR token (RTOKEN). See Sync Points on page 124 for more information about UORs.
The output fields returned in the PAPL to the CCTL are: Field PAPLRETC PAPLSTCD Contents Code returned Fast Path status code If the value in the PAPLRETC field is decimal 35, the PAPLSTCD field contains a status code that further describes the error.
COMTERM Request
This is a phase 2 sync-point request to commit the UOR. It also releases the PSB. You must issue a PREP request prior to issuing a COMTERM request. You must fill in the following input fields in the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK PAPLRTOK Contents PAPLTFUN PAPLCTRM, sync-point commit/terminate subfunction code DRA request token (output from an INIT request) Thread Token number 2. This is the DRA request token, which is output from a SCHED request. The thread token set up by the CCTL A 16-byte UOR token (RTOKEN). See Sync Points on page 124 for more information about UORs.
Specifying the following input field is optional: Field PAPLSTAT Contents Address of an area where transaction statistical data is returned to the CCTL
139

The output fields returned in the PAPL to the CCTL are: Field PAPLRETC PAPLSTAT Contents Code returned The address of the transaction statistical data area. This address must be specified on the input field.
ABTTERM Request
This is a phase 2 sync-point request for abort processing. It also releases the PSB. It does not require a preceding PREP request. You must fill in the following input fields of the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK PAPLRTOK Contents PAPLTFUN PAPLATRM, sync-point abort/terminate subfunction code DRA request token (output from an INIT request) Thread Token number 2. This is the DRA request token, which is output from a SCHED request. The thread token set up by the CCTL A 16-byte UOR token (RTOKEN). See Sync Points on page 124 for more information about UORs.
Specifying the following input field is optional: Field PAPLSTAT Contents Address of an area where transaction statistical data is returned to the CCTL.
TERMTHRD Request
This request terminates the DRA thread. You must fill in the following input fields of the PAPL: Field PAPLFUNC PAPLSFNC PAPLCTOK PAPLCTK2 PAPLTTOK Contents PAPLTFUN PAPLTTHD, thread terminate subfunction code DRA request token (output from an INIT request) Thread Token number 2. This is the DRA request token which is output from a SCHED request. The thread token set up by the CCTL
Specifying the following input field is optional:
140

Field PAPLSTAT Contents Address of an area where transaction statistical data is returned to the CCTL
PAPL Mapping Format

The PAPL is the parameter list used by the DRA interface in a CCTL environment. For the latest version of PAPL mapping format, see the IMS.ADFSMAC library; the member name is DFSPAPL.
Terminating the DRA

Termination isolation should be one of your primary considerations when you design a CCTL subsystem or an z/OS application. Definition:Termination isolation means that a failure of the IMS DB subsystem does not cause a direct failure of any attached CCTL subsystem or z/OS application and vice versa. Although IMS DB was designed to prevent failure between connecting subsystems, a termination of a CCTL subsystem can cause IMS DB failure. If a DRA thread TCB terminates while IMS DB is processing a thread DL/I call on the CCTL's behalf, IMS DB fails with a U0113 abend. To promote termination isolation, see the Designing the CCTL Recovery Process on page 142. The conditions that cause a thread TCB to terminate while IMS DB processes a DL/I call are: v A DRA thread abend due to code failure. This can be corrected by fixing the failing code. v The CCTL TCB collapses while a thread TCB still exists. The thread TCB collapses with an S13E or S33E abend and can result from three situations: a CCTL abend, a cancel command, or a shutdown. The number of U0113 abends caused by a CCTL cancel command can be reduced by following the design recommendations listed in the Designing the CCTL Recovery Process on page 142. v A DRA thread abend due to a IMS DB /STOP REGION CANCEL command initiated by CCTL. An IMS DB U0113 abend can be prevented by designing the CCTL recovery process so that it issues a TERM request and waits for the request to complete. This allows the DRA and thread TCBs to terminate before the CCTL TCB terminates.
141
Designing the CCTL Recovery
Designing the CCTL Recovery Process

Under the conditions of a nonrecoverable z/OS abend, a DRA TERM request lets all threads collapse and U0113 is possible. To reduce the number of nonrecoverable abends of the CCTL, IMS DB intercepts any operator CANCEL of a CCTL that is connected to IMS DB, and converts it to a S08E recoverable abend of the CCTL. You can also as a last resort, force a CCTL to shut down. If an operator enters a FORCE command after CANCEL has been entered (and converted to S08E), IMS DB converts FORCE into a z/OS cancel command. Subsequent FORCE attempts are not intercepted by IMS DB. In these cases of nonrecoverable abends, a U0113 is possible. A CCTL might have a means of allowing its own shutdown. The CCTL shutdown logic should issue a DRA TERM request and wait for the request completion to prevent a U0113 abend in IMS DB. The DRA TERM request waits for current thread requests to complete. One thing that can prevent a current thread DL/I call from completing normally is if the call has to wait in IMS DB for a database segment to become available. The reason the segment might not be available is that it is held by another UOR, either in a thread belonging to another CCTL or in an IMS dependent region (for example, a BMP). The solution is to not have CCTL threads or BMPs that have long-running UORs. Recommendation: BMPs should take frequent checkpoints. No matter how you choose to prevent or discourage long-running CCTL threads, you must decide how long to wait for the DRA TERM request to complete (TIMEOUT). In most cases, it is undesirable to get a U113 abend in IMS DB during a CCTL termination, so the timeout value should be greater than the longest possible UOR. If the CCTL has a means of limiting the UOR time or allowing the installation to specify this time limit, the DRA TERM timeout value can be determined. This timeout value can be specified in the DRA startup table and is returned to the CCTL in the INIT PAPL. Recommendation: CCTL should use this DRA TERM timeout value when waiting for the DRA TERM request to complete. At the very least, by using the DRA TERM timeout value, you can control whether CCTL terminations cause IMS DB failures with respect to the UOR time length of the applications that run in a given IMS DB/CCTL session. CCTL Operations Recommendation: v Avoid using CANCEL or FORCE commands against CCTL regions that are connected to IMS DB. CCTL Design Recommendations: v The CCTL should issue a DRA TERM request during recoverable abend processing. v CCTL shutdown functions should issue a DRA TERM request. v Whenever a DRA TERM request is issued, wait for it to complete. If this time must have an upper limit, use the TIMEOUT value specified in the DRA startup table. v The CCTL should prevent long-running UORs in its threads using IMS DB. User Installation Recommendations:
142
Designing the CCTL Recovery

v Have BMPs take frequent checkpoints. v Limit long-running UOR applications. v Set the TIMEOUT startup parameter as high as possible, preferably longer than longest running UOR.
CCTL Performance: Monitoring DRA Thread TCBs

Requirement: The DRA initialization process requires a minimum and maximum value (MINTHRD and MAXTHRD) for DRA thread TCBs. The value of MINTHRD and MAXTHRD determine the number of multithreading executions that can occur concurrently. These values also define the range of thread TCBs that the DRA will maintain under normal conditions with no thread failures. The number of TCBs can go below the MINTHRD value when the following thread failures occur: v An abend. v A nonzero DRA thread request return code that causes the thread TCB to be collapsed. v Termination using a IMS DB /STOP REGION command. Failed thread TCBs are not automatically recreated. The thread TCB number increases again if a new thread is created to process a SCHED request. If the number of thread TCBs is greater than the MINTHRD value and all thread activity ceases normally, the number of thread TCBs left in the DRA will be the MINTHRDD value. During CCTL processing, the number of active DRA threads occupying thread TCBs varies from 0 to the MAXTHRD number. Active DRA threads indicate that at least one SCHED request has been made but not any TERMTHRD requests. If the number of non-active thread TCBs becomes too large, the DRA automatically collapses some thread TCBs to release IMS DB resources. The status of DRA thread TCBs can be evaluated from the output of the /DISPLAY CCTL ALL command, except for one case. Related Reading: See IMS Version 9: Command Reference for examples of this command. If there were no thread failures, the output might show fewer thread TCBs than the MINTHRD value because of internal short lived conditions. In fact, the actual number of thread TCBs does equal the MINTHRD.
DRA Thread Statistics

DRA thread statistics are returned for a SCHED request and for any DRA requests that terminate a UOR. The statistics are in a CCTL area that is pointed to by the PAPLSTAT field. The PAPL listing maps this area, as shown in Table 26. The statistics also appear in the IMS DB log records X'08' (SCHED) and X'07' (UOR terminate).
Table 26. Information Provided for the Schedule Process: PAPL Field PAPLNPSB PAPLPOOL Field Length (Hexadecimal) 8 8 Contents PSB name Elapsed wait time for pool space (packed: microseconds)
143
Monitoring DRA Thread TCBs

Table 26. Information Provided for the Schedule Process: (continued) PAPL Field PAPLINTC PAPLSCHT PAPLTIMO PAPLTLOC PAPLDBIO Field Length (Hexadecimal) 8 8 8 8 4 Contents Elapsed wait time - intent conflict (packed: microseconds) Elapsed time for schedule process (packed: microseconds) Elapsed time for DB I/O (packed: microseconds) Elapsed time for DI locking (packed: microseconds) Number of DB I/Os
Table 27. Information Provided at UOR Termination: PAPL Field PAPLGU1 PAPLGN PAPLGNP PAPLGHU PAPLGHN PAPLGHNP PAPLISRT PAPLDLET PAPLREPL PAPLTOTC PAPLTENQ PAPLWTEQ PAPLTSDQ PAPLUENQ PAPLWUEQ PAPLUPDQ PAPLEXEQ PAPLWEXQ PAPLEXDQ PAPLDATS PAPLDATN PAPLDECL PAPLDERD PAPLMSCL PAPLOVFN PAPLUOWC PAPLBFWT PAPLUSSN Field Length (Hexadecimal) 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 8 8 2 2 2 2 2 2 4 Contents Number of database GU calls issued Number of database GN calls issued Number of database GNP calls issued Number of database GHU calls issued Number of database GHN calls issued Number of database GHNP calls issued Number of database ISRT calls issued Number of database DLET calls issued Number of database REPL calls issued Total number of DL/I database calls Number of test enqueues Number of WAITS on test enqueues Number of test dequeues Number of update enqueues Number of WAITs on updates and enqueues Number of update dequeues Number of exclusive enqueues Number of WAITs on exclusive enqueues Number of exclusive dequeues STCK time schedule started STCK time schedule completed Number of DEDB calls Number of DEDB read operations Reserved for Fast Path Number of overflow buffers used Number of UOW contentions Number of WAITs for DEDB buffers Unique schedule sequence number
144

Table 27. Information Provided at UOR Termination: (continued) PAPL Field PAPLCTM1 Field Length (Hexadecimal) 4 Contents Elapsed UOR CPU time (for thread TCB) (For timer units, see z/OS STIMER macro)
DRA Statistics
DRA statistics are contained in the returned PAPL as a result of a DRA TERM request, or in the Control exit routine's PAPL when it is called for DRA termination. This routine is called when the DRA fails or when a previous Control exit routine invocation resulted in return code 4. The statistics in the returned PAPL are: 1. The number of times the MAXTHRD value was reached. 2. The number of times the MINTHRD value was reached (only includes the times the value is reached when the thread TCB number is decreasing.) 3. The largest number of thread TCBs ever reached during this DRA session. (This is the number of TCBs, not the number of DRA threads, so it is at least the minimum thread value.) 4. The time (in seconds) during which the DRA thread TCB count was at the MAXTHRD value. You can find the field names for the previous statistics in the PAPL extensions for the TERM PAPL and control exit routine PAPL. Before attempting to evaluate the statistics DRA performance, remember: v If the DRA is using the maximum number of threads (MAXTHRD), when the DRA receives any new SCHED requests it will make these requests wait until a thread is available. v As active threads become available (for example, as a result of TERMTHRD call), some of the available threads might be collapsed. | | | These factors can adversely affect performance, but both improve IMS DB resource availability because fewer DRA threads require fewer IMS DB resources. The IMS DB resources (PSTs) are then available for other BMPs or other CCTLs to use. Statistics 1, 2, and 4 can serve as a measurement of the two factors, and will help you decide how to balance performance and resource usage. For the sake of this discussion, these statistics are presented solely from a performance point of view (for example, assume only 1 CCTL connected to a IMS DB).
Evaluating the DRA Statistics

If statistics 1 and 4 are high, a SCHED request had to wait for an available thread many times. To improve performance, raise the MAXTHRD value. The impact of statistic 2 on performance can only be estimated if thread activity history is known (the DRA does not provide this history but the CCTL can). If activity is steady, little thread collapsing occurs and statistic 2 is meaningless. If activity fluctuates a lot, statistic 2 can be useful. v If statistic 2 is 0, much thread collapsing might occurring, but the MINTHRD value was never reached.
145

v If statistic 2 is not zero, the MINTHRD value was reached and at those points, thread collapsing was stopped, thus enhancing performance. Therefore, if you have highly fluctuating thread activity, you can improve performance by raising MINTHRD until statistic 2 has a nonzero value. Finally, statistic 3 can be useful for adjusting your MAXTHRD value. Note: These statistics are useful in determining MINTHRD and MAXTHRD definitions. When MINTHRD=MAXTHRD, these statistics will be of no value.
Tracing
There is no tracing (logging) of activity in the DRA, but there is tracing in IMS DB of DL/I and Fast Path activity. The setup and invocation of DL/I tracing for IMS DB is the same as for IMS. The output trace records for CCTL threads contain the recovery token. Fast Path tracing in IMS DB is different from IMS. Fast Path tracing in IMS DB is activated when a SCHED request to the DRA has the PAPLFTRD equal to ON (Fast Path trace desired for this UOR). When this UOR completes, a trace output file is closed and sent to SYSOUT Class A. If a thread request fails during Fast Path processing, the DRA might return the PAPL with the PAPLFTRR field equal to ON. This recommends to the CCTL that it request the PAPLFTRD field be equal to ON (Fast Path trace desired) in the SCHED PAPL if this failing transaction is run again by the CCTL.
Sending Commands to IMS DB

In an IMS DB warm standby or IMS/ESA XRF environment, a CCTL might desire to have the IMS alternate system become the primary IMS system. To do this without operator intervention, a CCTL can use a z/OS SVC 34 to broadcast an emergency restart command to a IMS DB alternate, or a SWITCH command to an IMS XRF alternate. These are the only IMS commands that can be done using this interface. The command verb can be preceded by either the command recognition character or the 4-character IMS identification that is in the PAPLDBCT field of the INIT PAPL.
Problem Diagnosis
Failed DRA requests have a nonzero value in the PAPLRETC field of the PAPL returned to the CCTL. The format of PAPLRETC is:
HHSSSUUU
Where: HH= X'00'- No output UUU IMS DB return codes
X'88'- No output SSS UUU All z/OS non-retryable abend codes (for example, 222, 13E) or, IMS abend codes (775, 777, 844, 849, 2478, 2479, 3303)
X'84'- SNAP only
146

UUU IMS abend codes (260, 261, 263)
X'80'- SDUMP/SNAP provided SSS UUU All the z/OS retryable abend codes All IMS abend codes besides those listed for the format of PAPLRETC
Diagnostic information is provided by the DRA in the form of an SDUMP, or a SNAP data set output. For X'80', the SDUMP is attempted first. If it fails, SNAP is done. For X'84', no SDUMP is attempted, but a SNAP is attempted. A z/OS or IMS abend code failure results in DRA thread termination and thread TCB collapse. A IMS DB return code has no affect on the DRA itself or the thread TCB. DRA thread TCB failures that occur when not processing a thread request result in a SDUMP/SNAP process. DRA control TCB failures that occur when not processing a DRA request result in a SDUMP/SNAP process and the Control exit routine is called. For a SCHED type of thread request, a failure with X'80' or X'84' can result in either SNAP or SDUMP.
SDUMP
SDUMP output contains: v The IMS control region. v DLISAS address space. v Key 0 and key 7 CSA. v Selected parts of DRA private storage, including the ASCB, TCB, and RBs. You can format the IMS control blocks by using the Offline Dump Formatter (ODF). Related Reading: The ODF is described in IMS Version 9: Diagnosis Guide and Reference. The ODF will not format DRA storage. You can use IPCS to format the z/OS blocks in the CCTL's private storage. DRA SDUMPS have their own SDUMP options. As a result of this, any CHNGDUMP specifications cannot cause sections of DRA SDUMPs to be omitted. If these specifications aren't in the DRA's list of options, they can have an additive effect on DRA SDUMPS.
SNAP
The SNAP dump data sets are dynamically allocated whenever a SNAP dump is needed. A parameter in the DRA Startup Table defines the SYSOUT class. The SNAP output contains: v Selected parts of DRA private storage, including the ASCB, TCB, and RBs. v IMS DB's control blocks.
147
148
Chapter 7. Secondary Indexing and Logical Relationships

This chapter describes two ways in which IMS can provide flexibility in how your program views the data. Secondary indexing and logical relationships are techniques that can change your application program's view of the data. The DBA makes the decision about whether to use these options. Examples of when you use these techniques are: v If an application program must access a segment type in a sequence other than the sequence specified by the key field, secondary indexing can be used. Secondary indexing also can change the application program's access to or view of the data based on a condition in a dependent segment. v If an application program requires a logical structure that contains segments from different databases, logical relationships are used. | The following topics provide additional information: v How Secondary Indexing Affects Your Program v Processing Segments in Logical Relationships on page 152
How Secondary Indexing Affects Your Program

One instance of using a secondary index occurs when an application program needs to select database records in a sequence other than that defined by the root key. IMS stores root segments in the sequence of their key fields. A program that accesses root segments out of the order of their key fields cannot operate efficiently. You can index any field in a segment by defining an XDFLD statement for the field in the DBD for the database. If the Get call is not qualified on the key but uses some other field, IMS must search all the database records to find the correct record. With secondary indexing, IMS can go directly to a record based on a field value that is not in the key field. This section explains how secondary indexing affects your programming. For more information about secondary indexes and examples, see IMS Version 9: Application Programming: Design Guide.
SSAs with Secondary Indexes

If your program uses a secondary index, you can use the name of an indexed field in your SSAs. When you do this, IMS goes directly to the secondary index and finds the pointer segment with the value you specify. Then IMS locates the segment that the index segment points to in the database and returns the segment to your program. To use an indexed field name in the SSA, follow these guidelines: v Define the indexed field, using the XDFLD statement, in the DBD for the primary database during DBD generation. v Use the name that was given on the XDFLD statement as the field name in the qualification statement.
149
Secondary Indexing Affects Your Program

v Specify the secondary index as the processing sequence during PSB generation. Do this by specifying the name of the secondary index database on the PROCSEQ parameter on the PCB during PSB generation. Related Reading: For more detailed information about generating a DBD and a PSB, refer to the IMS Version 9: Utilities Reference: System. If you modify the XDFLD of the indexed segment (using the REPL call), you lose any parentage that you had established before issuing the REPL call. The key feedback area is no longer valid after a successful REPL call. Example: For you to index the PATIENT segment on the NAME field, the segment must have been defined on the XDFLD statement in the DBD for the medical database. If the name of the secondary index database is INDEX, you specify PROCSEQ=INDEX in the PCB. To issue a qualification that identifies a PATIENT by the NAME field instead of by PATNO, use the name that you specified on the XDFLD statement. If the name of the XDFLD is XNAME, use XNAME in the SSA, as follows: In the DBD: In the PSB: XDFLD NAME=XNAME PROCSEQ=INDEX = JBBROKE )
In the program: GU PATIENT (XNAME
Multiple Qualification Statements with Secondary Indexes

When you qualify a call using the name of an indexed field, you can include multiple qualification statements. You can use two AND operators to connect the qualification statements: * or & When used with secondary indexing, this AND is called the dependent AND. To satisfy the call, IMS scans the index once and searches for one pointer segment in the index that satisfies both qualification statements. This is called the independent AND. You use it only with secondary indexing. When you use the independent AND to satisfy the call, IMS scans the index twice and searches for two or more different pointer segments in the index that point to the same target segment.
The distinction between the two ANDs applies only when the indexed field (the one defined as XDFLD in the DBD) is used in all qualifications. If one of the qualification statements uses another field, both ANDs work like the dependent AND. The next two sections give examples of the dependent and independent AND. Although the examples show only two qualification statements in the SSA, you can use more than two. No set limit exists for the number of qualification statements you can include in an SSA, but a limit on the maximum size of the SSA does exist. You specify this size on the SSASIZE parameter of the PSBGEN statement. For information on this parameter, see IMS Version 9: Utilities Reference: System.
The Dependent AND

When you use the dependent AND, IMS scans the index only once. To satisfy the call, it must find one pointer segment that satisfies both qualification statements.
150

Example: Suppose you want to list patients whose bills are between $500 and $1000. To do this, you index the PATIENT segment on the BILLING segment, and specify that you want IMS to use the secondary index as the processing sequence. Figure 35 shows the three secondary indexing segments.
Figure 35. Example of Using the Dependent AND
You then use this call:

GU PATIENT (XBILLING>=00500*XBILLING<=01000)
To satisfy this call, IMS searches for one pointer segment with a value between 500 and 1000. IMS returns the PATIENT segment that is pointed to by that segment.
The Independent AND

Example: Suppose you want a list of the patients who have had both tonsillitis and strep throat. To get this information, you index the PATIENT segment on the ILLNAME field in the ILLNESS segment, and specify that you want IMS to use the secondary index as the processing sequence. In this example, you retrieve the PARENT segments based on a dependent's (the ILLNESS segment's) qualification. Figure 36 shows the four secondary indexing segments.
Figure 36. Example of Using the Independent AND
You want IMS to find two pointer segments in the index that point to the same PATIENT segment, one with ILLNAME equal to TONSILLITIS and one with ILLNAME equal to STREPTHRT. Use this call:
GU PATIENT (XILLNAME=TONSILITIS#XILLNAME= STREPTHRT)
151

This call retrieves the first PATIENT segment with ILLNESS segments of strep throat and tonsillitis. When you issue the call, IMS searches for an index entry for tonsillitis. Then it searches for an index entry for strep throat that points to the same PATIENT segment. When you use the independent AND with GN and GNP calls, a special situation can occur. If you repeat a GN or a GNP call using the same qualification, it is possible for IMS to return the same segment to your program more than once. You can check to find out whether IMS has already returned a segment to you by checking the key feedback area. If you continue issuing a GN call until you receive a not-found (GE) status code, IMS returns a segment occurrence once for each independent AND group. When IMS returns a segment that is identical to one that was already returned, the PCB key feedback area is different.
DL/I Returns with Secondary Indexes

The PATIENT segment that IMS returns to the application program's I/O area looks just as it would if you had not used secondary indexing. The key feedback area, however, contains something different. The concatenated key that IMS returns is the same, except that, instead of giving you the key for the segment you requested (the key for the PATIENT segment), IMS gives you the search portion of the key of the secondary index (the key for the segment in the INDEX database). The term key of the pointer segment refers to the key as perceived by the application program. That is, the key does not include subsequent fields. IMS places this key in the position where the root key would be located if you had not used a secondary indexin the left-most bytes of the key feedback area. The IMS Version 9: Application Programming: Design Guide gives some examples of this. If you try to insert or replace a segment that contains a secondary index source field that is a duplicate of one that is already reflected in the secondary index, IMS returns an NI status code. An NI status code is returned only for batch programs that log to direct-access storage. Otherwise, the application program is abnormally terminated. You can avoid having your program terminated by making sure a duplicate index source field does not exist. Before inserting a segment, try to retrieve the segment using the secondary index source field as qualification.
Status Codes for Secondary Indexes

If a secondary index is defined for a segment and if the definition specifies a unique key for the secondary index (most secondary indexes allow duplicate keys), your application program might receive the NI status code in addition to regular status codes. This status code can be received for a PCB that either uses or does not use the secondary index as a processing sequence. See IMS Version 9: Messages and Codes, Volume 1 for additional information about the NI status code.
Processing Segments in Logical Relationships

Sometimes an application program needs to process a hierarchy that is made up of segments that already exist in two or more separate database hierarchies. Logical relationships make it possible to establish hierarchic relationships between these segments. When you use logical relationships, the result is a new hierarchyone that does not exist in physical storage but that can be processed by application programs as though it does exist. This type of hierarchy is called a logical structure.
152

One advantage of using logical relationships is that programs can access the data as though it exists in more than one hierarchy, even though it is only stored in one place. When two application programs need to access the same segment through different paths, an alternative to using logical relationships is to store the segment in both hierarchies. The problem with this approach is that you must update the data in two places to keep it current. Processing segments in logical relationships is not very different from processing other segments. This section uses the example about an inventory application program that processes data in a purchasing database, but which also needs access to a segment in a patient database. Related Reading: v For more information about application programming requirements that logical relationships can satisfy, see IMS Version 9: Application Programming: Design Guide. v For a full description of the inventory application program example, see IMS Version 9: Application Programming: Design Guide. Example: The hierarchy that an inventory application program needs to process contains four segment types: v An ITEM segment containing the name and an identification number of a medication that is used at a medical clinic v A VENDOR segment that contains the name and address of the vendor who supplies the item v A SHIPMENT segment that contains information such as quantity and date for each shipment of the item that the clinic receives v A DISBURSE segment that contains information about the disbursement of the item at the clinic, such as the quantity, the date, and the doctor who prescribed it The TREATMNT segment in the medical database used throughout this section contains the same information that the inventory application program needs to process in the DISBURSE segment. Rather than store this information in both hierarchies, you can store the information in the TREATMNT segment, and define a logical relationship between the DISBURSE segment in the item hierarchy and the TREATMNT segment in the patient hierarchy. Doing this makes it possible to process the TREATMNT segment through the item hierarchy as though it is a child of SHIPMENT. DISBURSE then has two parents: SHIPMENT is DISBURSE's physical parent, and TREATMNT is DISBURSE's logical parent. Three segments are involved in this logical relationship: DISBURSE, SHIPMENT, and TREATMNT. Figure 37 on page 154 shows the item hierarchy on the right. The DISBURSE segment points to the TREATMNT segment in the patient hierarchy shown on the left. (The patient hierarchy is part of the medical database.)
153
Figure 37. Patient and Item Hierarchies
Three types of segments are found in a logical relationship: v TREATMNT is called the logical parent segment. It is a physical dependent of ILLNESS, but it can be processed through the item hierarchy because a path is established by the logical child segment DISBURSE. The logical parent segment can be accessed through both hierarchies, but it is stored in only one place. v SHIPMENT is called a physical parent segment. The physical parent is the parent of the logical child in the physical database hierarchy. v DISBURSE is called a logical child segment. It establishes a path to the TREATMNT segment in the PATIENT hierarchy from the SHIPMENT segment in the ITEM hierarchy. Because a logical child segment points to its logical parent, two paths exist through which a program can access the logical parent segment: v When a program accesses the logical parent segment through the physical path, it reaches this logical parent segment through the segment's physical parent. Accessing the TREATMNT segment through ILLNESS is accessing the logical parent segment through its physical path. v When a program accesses the logical parent segment through the logical path, it reaches this logical parent segment through the segment's logical child. Accessing the TREATMNT segment through SHIPMENT is accessing the logical parent segment through its logical path. When a logical parent segment is accessed through the logical child, the logical child is concatenated with both the data from its logical parent segment and any data the user has chosen to associate with this pairing (intersection data) in a single segment I/O area, like this:
Figure 38. Concatenated Segment
LL is the length field of the logical parent if this segment is a variable-length segment.
How Logical Relationships Affect Your Programming

The calls you issue to process segments in logical relationships are the same calls that you use to process other segments. However, the processing is different depending on how the logical segment looks in your I/O area, what the DB PCB
154

mask contains after a retrieve call, and how you can replace, delete, and insert physical and logical parent segments. Because it is possible to access segments in logical relationships through the logical path or the physical path, the segments must be protected from being updated by unauthorized programs. When DBAs define logical relationships, they define a set of rules that determine how the segments can be deleted, replaced, and inserted. Defining these rules is a database design decision. If your program processes segments in logical relationships, the DBA (or the person at your installation responsible for database design) should tell you: v What segments look like in your I/O area when you retrieve them v Whether your program is allowed to update and insert segments v What to do if you receive a DX, IX, or RX status code | The requirements for inserting a logical child segment are: v In load mode, the logical child can be inserted only under its physical parent. You do not supply the logical parent in the I/O area. v In update mode, the format of the logical child is different, depending on whether it is accessed from its physical parent or from its logical parent. If accessed from its physical parent, the logical child's format is the concatenated key of the logical parent followed by intersection data. If accessed from its logical parent, the logical child's format is the concatenated key of the physical parent, followed by intersection data. v The logical child can be inserted or replaced, depending on the insert rule for the logical or physical parent. Unless the insert rule of the logical or physical parent is PHYSICAL, the logical or physical parent must be supplied in the I/O area following the logical child, as illustrated in Figure 38 on page 154.
Status Codes for Logical Relationships

These status codes apply specifically to segments that are involved in logical relationships. These are not all of the status codes that you can receive when processing a logical child segment or a physical or logical parent. If you receive one of these status codes, it means that you are trying to update the database in a way that you are not allowed to. Check with the DBA or person responsible for implementing logical relationships at your installation to find out what the problem is. DX IMS did not delete the segment because the physical delete rule was violated. If the segment is a logical parent, it still has active logical children. If the segment is a logical child, it has not been deleted through its logical path. You tried to insert either a logical child segment or a concatenated segment. If it was a logical child segment, the corresponding logical or physical parent segment does not exist. If it was a concatenated segment, either the insert rule was physical and the logical or physical parent does not exist, or the insert rule is virtual and the key of the logical or physical parent in the I/O area does not match the concatenated key of the logical or physical parent. The physical replace rule has been violated. The physical replace rule was specified for the destination parent, and an attempt was made to change its data. When a destination parent has the physical replace rule, it can be replaced only through the physical path.
IX
RX
155
156
Chapter 8. Processing GSAM Databases

GSAM databases are available to application programs that can run as batch programs, batch-oriented BMPs, or transaction-oriented BMPs. If your application program accesses GSAM databases, as you design your program consider that: v An IMS program can retrieve records and add records to the end of the GSAM database, but the program cannot delete or replace records in the database. v You use separate calls to access GSAM databases. (Additional checkpoint and restart considerations are involved in using GSAM.) v Your program must use symbolic CHKP and XRST calls if it uses GSAM. Basic CHKP calls cannot checkpoint GSAM databases. v When an IMS program uses a GSAM data set, the program treats a GSAM data set like a sequential nonhierarchic database. The z/OS access methods that GSAM can use are BSAM on direct access, unit record, and tape devices; and VSAM on direct-access storage. VSAM data sets must be nonkeyed, non indexed, entry-sequenced data sets (ESDS) and must reside on DASD. VSAM does not support temporary, SYSIN, SYSOUT, and unit-record files. v Because GSAM is a sequential nonhierarchic database, it has no segments, keys, or parentage. | The following topics provide additional information: v Accessing GSAM Databases v GSAM Record Formats on page 161 v GSAM I/O Areas on page 162 v GSAM Status Codes on page 162 v Symbolic CHKP and XRST with GSAM on page 163 v GSAM Coding Considerations on page 163 v Origin of GSAM Data Set Characteristics on page 164
Accessing GSAM Databases

The calls you use to access Generalized Sequential Access Method (GSAM) databases are different from those you use to access other IMS databases, and you can use GSAM databases for input and output. For example, your program can read input from a GSAM database sequentially and then load another GSAM database with the output data. Programs that retrieve input from a GSAM database usually retrieve GSAM records sequentially and then process them. Applications that send output to a GSAM database must add output records to the end of the database as the program processes the records. You cannot delete or replace records in a GSAM database, and any records that you add must go at the end of the database.
PCB Masks for GSAM Databases

For the most part, you process GSAM databases in the same way that you process other IMS databases. You use calls that are very similar to DL/I calls to communicate your requests. GSAM describes the results of those calls in a GSAM DB PCB.
157

Calls to GSAM databases can use either the AIBTDLI or the PCB interface. For information on the AIBTDLI interface, see The AIBTDLI Interface on page 85. The DB PCB mask for a GSAM database serves the same purpose as it does for other IMS databases. The program references the fields of the DB PCB through the GSAM DB PCB mask. The GSAM DB PCB mask must contain the same fields as the GSAM DB PCB and must be of the same length. Some differences exist between a DB PCB for a GSAM database and one for other IMS databases. Some of the fields are different, and the GSAM DB PCB has one field that the other PCBs do not. Table 28 on page 158 shows the order and lengths of these fields. Because GSAM is not a hierarchical database, some fields in a PCB mask for other IMS databases do not have meanings in a GSAM PCB mask. The fields that are not used when you access GSAM databases are: v The second field: segment level number v The sixth field: segment name v The eighth field: number of sensitive segments Even though GSAM does not use these fields, you must define them in the order and length shown in Table 28 in the GSAM DB PCB mask. When you code the fields in a DB PCB mask, name the area that contains all the fields as you do for a DB PCB. The entry statement associates each DB PCB mask in your program with a DB PCB in your program's PSB based on the order of the PCBs in the PSB. The entry statement refers to the DB PCB mask in your program by the name of the mask or by a pointer. When you code consider that the entry statement in: v COBOL, Pascal, C, and assembler language programs, it must list the names of the DB PCB masks in your program. v PL/I programs, it must list the pointers to the DB PCB masks in your program. The first PCB name or pointer in the entry statement corresponds to the first PCB. The second name or pointer in the entry statement corresponds to the second PCB, and so on.
Table 28. GSAM DB PCB Mask Descriptor Database name1 Segment level number2 Status code3 Processing options Reserved for IMS Segment name
6 5 4
Byte Length 8 2 2 4 4 8 4
DB/DC X N/A X X X N/A X
DBCTL X N/A X X X N/A X
DCCTL X N/A X X X N/A X
DB Batch X N/A X X X N/A X
TM Batch X N/A X X X N/A X
Length of key feedback area and undefined-length records area7 Number of sensitive segments8 Key feedback area9
4 8
N/A X
N/A X
N/A X
N/A X
N/A X
158

Table 28. GSAM DB PCB Mask (continued) Descriptor Length of undefined-length records10 Byte Length 4 DB/DC X DBCTL X DCCTL X DB Batch X TM Batch X
Notes: 1. Database Name. The name of the GSAM DBD. This field is 8 bytes and contains character data. 2. Segment Level Number. Not used by GSAM, but you must code it. It is 2 bytes. 3. Status Code. IMS places a two-character status code in this field after each call to a GSAM database. This code describes the results of the call. IMS updates this field after each call and does not clear it between calls. The application program should test this field after each call to find out whether the call was successful. If the call was completed successfully, this field contains blanks. 4. Processing Options. This is a 4-byte field containing a code that tells IMS the types of calls this program can issue. It is a security mechanism in that it can prevent a particular program from updating the database, even though the program can read the database. This value is coded in the PROCOPT parameter of the PCB statement when generating the PSB for the application program. The value does not change. For GSAM, the values are G, GS, L, or LS. 5. Reserved for IMS. This 4-byte field is used by IMS for internal linkage. It is not used by the application program. 6. Segment Name. This field is not used by GSAM, but it must be coded as part of the GSAM DB PCB mask. It is 8 bytes. 7. Length of Key Feedback Area and Undefined-Length Records Area. This is a 4-byte field that contains the decimal value of 12. This is the sum of the lengths of the 9 and 10. 8. Number of Sensitive Segments. This field is not used by GSAM, but it should be coded as part of the GSAM DB PCB mask. This field is 4 bytes. 9. Key Feedback Area. After a successful retrieval call, GSAM places the address of the record that is returned to your program in this field. This is called a record search argument (RSA). You can use it later if you want to retrieve that record directly by including it as one of the parameters on a GU call. This field is 8 bytes. 10. Undefined-Length Records Area. If you use undefined-length records (RECFM=U), the length in binary of the record you are processing is passed between your program and GSAM in this field. This field is 4 bytes long. When you issue a GU or GN call, GSAM places the binary length of the retrieved record in this field. When you issue an ISRT call, put the binary length of the record you are inserting in this field before issuing the ISRT call.
Retrieving and Inserting GSAM Records

To retrieve GSAM records sequentially, use the GN call. The only required parameters are the GSAM PCB and the I/O area for the segment. To process the whole database, issue the GN call until you get a GB status code in the GSAM PCB. This means that you have reached the end of the database. GSAM automatically closes the database when you reach the end of it. To add records to a
159

new data set or to add new records to the end of an existing data set in the database, use the ISRT call. GSAM adds the records sequentially in the order in which you supply them. | | | | | | | | | | | | | | | | | | | | | | You can retrieve records directly from a GSAM database by supplying a record search argument (RSA) to the GSAM database. An RSA is similar to a segment search argument (SSA), but it contains the exact address of the record that you want to retrieve. The specific contents and format of the RSA depend on the access method that GSAM is using. For BSAM tape data sets and VSAM data sets, the RSA contains the relative byte address (RBA). For BSAM disk data sets, the RSA contains the disk address and uses the relative track and record format. The following table provides more details about the format of the RSA:
Table 29. Format of the RSA Position Positions 1-4 Address v BSAM (DASD) relative track and record (TTRZ) for the block in the buffer. v BSAM RBA. v VSAM RBA. Position 5 Position 6 Positions 7 and 8 Relative data set of the concatenated data set. The first data set number is 1. Relative volume of the data set. The first volume of data set is 1. Current displacement.
Before you can supply an RSA in a GU call to a GSAM database, that RSA must have previously been returned to you as a result of a GN or ISRT call. For GSAM to return an RSA, the GN or ISRT call must be issued with a fourth parameter that points to an eight-byte RSA save area in your program, as shown in Table 30 on page 163. Save this RSA until you want to retrieve that particular record. To retrieve that particular record, issue a GU call for the record and specify the address of its RSA as a fourth parameter of the GU call. GSAM returns the record to the I/O area that you named as one of the call parameters. GSAM Coding Considerations on page 163 provides a list of parameters you can use with GSAM database calls.
| | |
| | | | | | | | |
Restriction: Retrieve records directly from a GSAM database on DASD only. When using buffered I/O, buffer definitions for the output PCB may affect performance.
Resetting the Position in a GSAM Database

You can use the GU call to reset the position in the GSAM database. You can reset the position to the start of the GSAM database or to a specific segment in the GSAM database by completing one of the following tasks: v To reset the position to the start of the GSAM database, issue a GU call with an RSA that consists of a fullword with a binary value of 1, followed by a fullword with a binary value of 0.
160

| | | | | v To reset the position to a specific segment in the GSAM database, issue a GU call with an RSA that contains the saved RSA value from a prior ISRT or GN call for that segment. For more information about issuing a GU call with an RSA, see Retrieving and Inserting GSAM Records on page 159.
Explicit Open and Close Calls to GSAM

IMS opens the GSAM data set when the first call is made and closes the data set when the application program terminates. Therefore, the application program does not usually need to make explicit open or close calls to GSAM. However, explicit OPEN and CLSE calls are useful if: v the application program loads a GSAM data set, and then in the same step reads the data set using GSAM (for example, to sort the data set). The application program should issue the GSAM CLSE call after the load is complete. v the GSAM data set is an output data set, and it is possible that when the program executes it does not make GSAM ISRT calls. A data set is not created. Subsequent attempts to read the nonexistent data set (using GSAM or not) will likely result in an error. To avoid this situation, explicitly open the data set. DL/I closes the data set when the step terminates. Closing the data set prevents the possibility of attempting to read an empty data set. The explicit OPEN or CLSE call need not include an I/O area parameter. Depending on the processing option of the PCB, the data set is opened for input or output. You can specify that an output data set contain either ASA or machine control characters. Including an I/O area parameter in the call and specifying OUTA in the I/O area indicates ASA control characters. Specifying OUTM specifies machine control characters.
GSAM Record Formats

GSAM records are nonkeyed. For variable-length records you must include the record length as the first 2 bytes of the record. Undefined-length records, like fixed-length records, contain only data (and control characters, if needed). If you use undefined-length records, record length is passed between your program and GSAM in the 4-byte field that follows the key feedback area of the GSAM DB PCB. This is the tenth field in Table 28 on page 158. It is called the undefined-length records area. When you issue an ISRT call, supply the length. When you issue a GN or GU call, GSAM places the length of the returned record in this field. The advantage of using undefined-length records is that you do not need to include the record length at the beginning of the record, and records do not need to be of fixed length. The length of any record must be less than or equal to the block size (BLKSIZE) and greater than 11 bytes (an z/OS convention). If you are using VSAM, you can use blocked or unblocked fixed-length or variable-length records. If you are using BSAM, you can use blocked or unblocked fixed-length, variable-length, or undefined-length records. Whichever you use, be sure to specify this on the RECFM keyword in the DATASET statement of the GSAM DBD. You can override this in the RECFM statement of the DCB parameter in the JCL. You can also include carriage control characters in the JCL for all formats. Origin of GSAM Data Set Characteristics on page 164 explains what you can use to override each type of record format.
161
GSAM I/O Areas
GSAM I/O Areas

If v v v you provide an optional I/O area, it must contain one of these values: INP for an input data set OUT for an output data set OUTA for an output data set with ASA control characters
v OUTM for an output data set with machine control characters For GN, ISRT, and GU calls, the format of the I/O area depends on whether the record is fixed-length, undefined-length (valid only for BSAM), or variable-length. For each kind of record, you have the option of using control characters. The formats of an I/O area for fixed-length or undefined-length records are: v With no control characters, the I/O area contains only data. The data begins in byte 0. v With control characters, the control characters are in byte 0 and the data begins in byte 1. If you are using undefined-length records, the record length is passed between your program and GSAM in the PCB field that follows the key feedback area. When you are issuing an ISRT call, supply the length. When you are issuing a GN or GU call, GSAM places the length of the returned record in this field. This length field is 4 bytes long. The formats for variable-length records differ because variable-length records include a length field, which other records do not have. The length field is 2 bytes. Variable-length I/O areas, like fixed-length and undefined-length I/O areas, can have control characters. v Without control characters, bytes 0 and 1 contain the 2-byte length field, and the data begins in byte 2. v With control characters, bytes 0 and 1 still contain the length field, but byte 2 contains the control characters, and the data starts in byte 3.
GSAM Status Codes

Your program should test for status codes after each GSAM call, just as it does after each DL/I or system service call. | | | | | If, you find that you have an error and terminate your program after checking the status codes, be sure to note the PCB in error before you terminate. The GSAM PCB address is helpful in determining problems. When a program that uses GSAM terminates abnormally, GSAM issues PURGE and CLSE calls internally, which changes the PCB information. Status codes that have specific meanings for GSAM are: AF AH AI AJ AM GSAM detected a BSAM variable-length record with an invalid format. Terminate your program. You have not supplied an RSA for a GU call. There has been a data management OPEN error. One of the parameters on the RSA that you supplied is invalid. You have issued an invalid request against a GSAM database.
162
GSAM Status Codes

AO GB IX An I/O error occurred when the data set was accessed or closed. You reached the end of the database, and GSAM has closed the database. The next position is the beginning of the database. You issued an ISRT call after receiving an AI or AO status code. Terminate your program.
Symbolic CHKP and XRST with GSAM

To checkpoint GSAM databases, use symbolic CHKP and XRST calls. By using GSAM to read or write the data set, symbolic CHKP and XRST calls can be used to reposition the data set at the time of restart, enabling you to make your program restartable. When you use an XRST call, IMS repositions GSAM databases for processing. CHKP and XRST calls are available to application programs that can run as batch programs, batch-oriented BMPs, or transaction-oriented BMPs. Restriction: When restarting GSAM databases: v You cannot use temporary data sets with a symbolic CHKP or XRST call. v A SYSOUT data set at restart time may give duplicate output data. v You cannot restart a program that is loading a GSAM or VSAM database. When IMS restores the data areas specified in the XRST call, it also repositions any GSAM databases that your program was using when it issued the symbolic CHKP call. If your program was loading GSAM databases when the symbolic CHKP call was issued, IMS repositions them (if they are accessed by BSAM). If you make a copy of the GSAM data set for use as input to the restart process, ensure that the short blocks are written to the new data set as short blocks, for example, using IEBGENER with RECFM=U for SYSUT1. You can also do the restart using the original GSAM data set.
GSAM Coding Considerations

| | | The calls your program uses to access GSAM databases are not the same as the DL/I calls. This section tells you how to code GSAM calls and GSAM databases. The system service calls that you use with GSAM are symbolic CHKP and XRST. Table 30 summarizes GSAM database calls. The five calls you can use to process GSAM databases are: v CLSE v GN v GU v ISRT v OPEN The COBOL, PL/I, Pascal, C, and assembler language call formats and parameters for these calls are the same and are described in Table 30. GSAM calls do not differ significantly from DL/I calls, but GSAM calls must reference the GSAM PCB, and they do not use SSAs.
Table 30. Summary of GSAM Calls Call Formats CLSE Meaning Close Use Explicitly closes GSAM database Options None Parameters function, gsam pcb
163
GSAM Coding Considerations

Table 30. Summary of GSAM Calls (continued) Call Formats GN Meaning Get Next Use Retrieves next sequential record Establishes position in database or retrieves a unique record Adds new record at end of database Explicitly opens GSAM database Options Parameters
Can supply function, gsam pcb, i/o address for RSA to area [,rsa name] be returned None function, gsam pcb, i/o area, rsa name
GU
Get Unique
ISRT
Insert
Can supply function, gsam pcb, i/o address for RSA to area [,rsa name] be returned Can specify printer or punch control characters function, gsam pcb [, open option]
OPEN
Open
Origin of GSAM Data Set Characteristics

For an input data set, the record format (RECFM), logical record length (LRECL), and block size (BLKSIZE) are based on the input data set label. If this information is not provided by a data set label, the DD statement or the DBD specifications are used. The DD statement has priority. An output data set can have the following characteristics: v Record format v Logical record length v Block size v Other JCL DCB parameters Specify the record format on the DATASET statement of the GSAM DBD. The options are: v V for variable v VB for variable blocked v F for fixed v FB for fixed blocked v U for undefined The V, F, or U definition applies and is not overridden by the DCB=RECFM= specification on the DD statement. However, if the DD RECFM indicates blocked and the DBD does not, RECFM is set to blocked. If the DD RECFM of A or M control character is specified, it applies as well. Unless an undefined record format is used, specify the logical record using the RECORD= parameter of the DATASET statement of DBDGEN, or use DCB=LRECL=xxx on the DD statement. If the logical record is specified on both, the DD statement has priority. Specify block size using the BLOCK= or SIZE= parameter of the DATASET statement of DBDGEN, or use DCB=BLKSIZE=xxx on the DD statement. If block size is specified on both, the DD statement has priority. If the block size is not specified by the DBD or the DD statement, the system determines the size based on the device type, unless the undefined record format is used.
164
GSAM Data Set Characteristics

The other JCL DCB parameters that can be used, include: v CODE v DEN v TRTCH v MODE v STACK v PRTSP, which can be used if RECFM does not include A or M v DCB=BUFNO=X, which, when used, causes GSAM to use X number of buffers Restriction: Do not use BFALN, BUFL, BUFOFF, FUNC, NCP, and KEYLEN. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DD Statement DISP Parameter for GSAM Data Sets

The DD statement DISP parameter can be configured based on whether you are creating input or output data sets and how you plan to use the data sets: v For input data sets, set DISP=OLD. v For output data sets, consider the following options: To create an output data set allocated by the DD statement, set DISP=NEW. To add new records to an empty data set when performing normal start or a restart after failure, set DISP=MOD, DISP=SHR, or DISP=OLD. When restarting the step, set DISP=OLD for existing data sets and DISP=MOD for empty data sets. To add new records to an existing non-empty data set when performing a restart after failure, set DISP=MOD, DISP=SHR, or DISP=OLD. These parameters add new records from the restart point on the existing data set. To add new records to the end of an existing non-empty data set when performing normal start, set DISP=MOD. Warning: Specifying the DISP=OLD or DISP=SHR parameter for a normal start with non-empty data sets will overwrite the existing records from the beginning of the data set.
Extended Checkpoint Restart for GSAM Data Sets

If you are using extended checkpoint restart for GSAM data sets: v Do not use passed data sets. v Do not use backward references to data sets in previous steps. v Do not use the DISP=MOD parameter to add records to an existing tape data set. v Do not use the DISP=DELETE or DISP=UNCATLG parameter. v Use DFSMS striped data sets under the following conditions: When the data sets will be managed by SMS. When the data sets are likely to exceed the system extent limit for volumes. Additionally, keep in mind that: v No attempt is made to reposition a SYSIN, SYSOUT, or temporary data set. v No attempt is made to reposition any of the concatenated data sets for a concatenated DD statement if any of the concatenated data sets are SYSIN or SYSOUT data sets. v If you are using concatenated data sets, specify the same number and sequence of data sets at restart time and checkpoint time.
165

| | | | | | | | | | | | | | | | | | | | | | v GSAM/VSAM load mode restrictions apply to both non-striped and striped data sets. v If the PSB contains an open GSAM/VSAM output data set when the symbolic checkpoint call is issued, the system returns an AM status code in the database PCB as a warning. This code means that the data set is not repositioned at restart, and the checkpoint has completed normally.
Copying GSAM Data Sets Between Checkpoint and Restart

To position GSAM data sets when restarting, non-striped GSAM DASD data sets use the relative track and record format (TTRZ). GSAM uses TTRZ on the volume to position non-striped GSAM DASD data sets when restarting. For a tape data set, the relative record on the volume is used. The relative record on the tape volume cannot be changed. To copy non-striped DASD data sets between checkpoint and restart: v Copy the data set to the same device type. v Avoid any reblocking by using the undefined record format (RECFM=U) for both the input and the output data set. Each copied volume contains the same number of records as the original volumes. Note: GSAM uses the relative block number (RBN) to reposition striped DASD data sets. When data sets that are managed by SMS are used with GSAM databases, you cannot control how each volume is copied. After the data set is copied, unlike with non-striped DASD data sets, you do not need to ensure that the restart record's TTRZ is unchanged.
Converting Data Sets From Non-Striped Data Sets to Striped Data Sets
| | | | | | | | | | | | | | | | | | | | Convert GSAM/BSAM non-striped data sets to striped data sets before you need to perform an extended restart when a system allocation limit is exceeded or a system X'37' error condition occurs. Non-striped data sets that are not managed by SMS extend beyond their initial primary or secondary allocation only by volume, but with non-striped GSAM/BSAM multiple volume data sets that are managed by SMS, the resulting new space allocation takes effect for all of the volumes in the data set. If you copy non-striped data sets that are managed by SMS after you change the space allocation values, the number of records in the new volumes will be different from the number of records in the old volume. The new primary and secondary allocation values are used with non-striped data sets. As the data is copied, all of the space that is allocated on the new volume is used before the data is copied to the next volume. If an error condition (System x37 or system allocation limit exceeded) occurs during the processing of a GSAM/BSAM non-striped data set, and the data set is converted to a striped data set after the error occurs, a restart after failure will not complete successfully. Because the issued checkpoint saved a TTRZ value in the log record for repositioning, the log record for striped data sets will be used by GSAM restart after failure, which requires a relative block number (RBN) to perform the repositioning.
166
Concatenated Data Sets Used by GSAM

GSAM can use concatenated data sets, which may be on unlike device types, such as DASD and tape, or on different DASD devices. Logical record lengths and block sizes can differ, and it is not required that the data set with the largest block size be concatenated first. The maximum number of concatenated data sets for a single DD statement is 255. The number of buffers determined for the first of the concatenated data sets is used for all succeeding data sets. Generation data groups can result in concatenated data sets.
Suggested Method for Specifying GSAM Data Set Attributes

Recommendation: When specifying GSAM data set attributes: v On the DBD, specify RECFM. (It is required.) v On the DATASET statement, specify the logical record length using RECORD=. v On the DD statement, do not specify LRECL, RECFM, or BLKSIZE. The system determines block size, with the exception of RECFM=U. The system determines logical record length from the DBD. v For the PSB, specify PROCOPT=LS for output and GS for input. If you include S, GSAM uses multiple buffers instead of a single buffer for improved performance. IMS will add 2 bytes to the record length value specified in the DBD in order to accommodate the ZZ field that is needed to make up the BSAM RDW. Whenever the database is GSAM or BSAM and the records are variable (V or VB), IMS adds 2 bytes. The record size of the GSAM database is 2 bytes greater than the longest segment that is passed to IMS by the application program. | | | | | | | | | | | | | | | | | | |
DLI, DBB, and BMP Region Types and GSAM

To access GSAM databases, IMS builds its DLI control blocks using PSB and DBD information from PSBLIB, DBDLIB and ACBLIB. The source of the PSB and DBD information depends on the region type. For DLI offline batch regions, IMS obtains PSB and DBD information from PSBLIB and DBDLIB. For DBB offline batch regions, IMS database management obtains PSB and DBD information from ACBLIB. For online batch regions (BMPs), IMS builds its DLI control blocks with information from ACBLIB. If an application is scheduled in a BMP region and the PSB associated with the application contains one or more GSAM PCBs, IMS scheduling obtains PSB information from ACBLIB and PSBLIB. In this case, the PSB in ACBLIB and PSBLIB must be the same. GSAM database management does not obtain PSB and DBD information from ACBLIB. Instead, GSAM database management obtains PSB and DBD information from PSBLIB and DBDLIB. When you initialize a DLI, DBB or BMP region using GSAM, you must include an //IMS DD and GSAM DD statements. When DBB or BMP regions are not using GSAM, //IMS DD statements do not need to be included. To load PSBs and DBDs and build GSAM control blocks, you must include an //IMS DD statement. In Figure 39 on page 168, an example of the //IMS DD statement is shown.
167
//STEP //STEPLIB // //IMS // //IMSACB //SYSPRINT //SYSUDUMP //ddnamex //ddnamex
EXEC DD DD DD DD DD DD DD DD DD . . .
PGM=DFSRRC00,PARM=[BMP|DBB|DLI],... DSN=executionlibrary-name,DISP=SHR DSN=pgmlib-name,DISP=SHR DSN=psblib-name,DISP=SHR DSN=dbdlib-name,DISP=SHR DSN=acblib-name,disp=shr (required for DBB) SYSOUT=A SYSOUT=A (add DD statements for required GSAM databases) (add DD statements for non-GSAM IMS databases for DLI/DBB)
/* Figure 39. //IMS DD Statement Example
168
Chapter 9. Processing Fast Path Databases

This chapter contains information on Fast Path database calls and MSDB and DEDB information that is required by Fast Path calls. Fast Path message calls appear in IMS Version 9: Application Programming: Transaction Manager manual. Restriction: This DEDB information applies to CICS users with DBCTL. MSDBs and cannot be accessed through CICS and DBCTL. The two kinds of Fast Path databases are: v Main storage databases (MSDBs) are available in a DB/DC environment, and contain only root segments in which you store data that you access most frequently. v Data entry databases (DEDBs) are hierarchic databases that can have as many as 15 hierarchic levels and as many as 127 segment types. DEDBs are available to both IMS users and CICS users with DBCTL. | The following topics provide additional information: v Main Storage Databases (MSDBs) v Data Entry Databases (DEDBs) on page 170 v Fast Path Database Calls on page 170 v Processing MSDBs and DEDBs on page 171 v v v v v Restrictions on Using Calls for MSDBs on page 178 Processing DEDBs (IMS and CICS with DBCTL) on page 178 Calls with Dependent Segments for DEDBs on page 187 DEDB DL/I calls to extract DEDB information on page 188 Fast Path Coding Considerations on page 195
Related Reading: For more information on the types of processing requirements the two types of Fast Path databases satisfy, see IMS Version 9: Administration Guide: Database Manager. This section contains information on how to write programs to access data in MSDBs and DEDBs.
Main Storage Databases (MSDBs)

MSDBs contain only root segments. Each segment is like a database record, because the segment contains all of the information about a particular subject. In a DL/I hierarchy, a database record is made up of a root segment and all its dependents. For example, in the medical hierarchy, a particular PATIENT segment and all the segments underneath that PATIENT segment comprise the database record for that patient. In an MSDB, the segment is the whole database record. The database record contains only the fields that the segment contains. MSDB segments are fixed length. The two kinds of MSDBs are terminal related and non-terminal related. In terminal-related MSDBs, each segment is owned by one logical terminal. The segment that is owned can be updated only by that terminal. Related MSDBs can be fixed or dynamic. You can add segments to and delete segments from dynamic related MSDBs. You cannot add segments to or delete segments from fixed related MSDBs.
169
Main Storage Databases (MSDBs)

In the second kind of MSDB, called non-terminal related (or nonrelated) MSDBs, the segments are not owned by logical terminals. One way to understand the differences between these types of databases and why you would use each one, is to look at the examples of each in Bank Account Hierarchy Example on page 15.
Data Entry Databases (DEDBs)

A DEDB contains a root segment and as many as 127 dependent segment types. One of these 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 can provide high data availability. Each DEDB can be partitioned, or divided into multiple areas. Each area contains a different collection of database records. In addition, you can make as many as seven copies of each area data set. If an error exists in one copy of an area, application programs continue to access the data by using another copy of that area. Use of the copy of an area is transparent to the application program. When an error occurs to data in a DEDB, IMS does not stop the database. IMS 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 explanation of administering IMS systems that share data in IMS Version 9: Administration Guide: System.
Fast Path Database Calls

Table 31 summarizes the database calls you can use with Fast Path databases.
Table 31. Summary of Fast Path Database Calls Types of MSDBs: NonterminalRelated TerminalRelated Fixed TerminalRelated Dynamic
Function Code DEQ FLD GU, GHU GN, GHN GNP, GHNP DLET ISRT POS REPL
DEDBs X
X X X
X X X
X X X X X
X X X X X X
170
Fast Path Database Calls

DL/I calls to DEDBs can include the same number of SSAs as existing levels in the hierarchy (a maximum of 15). They can also include command codes and multiple qualification statements. Restriction: v Fast Path ignores command codes that are used with sequential dependent segments. v If you use a command code that does not apply to the call you are using, Fast Path ignores the command code. v If you use F or L in an SSA for a level greater than the established parent, Fast Path ignores the F or L command code. v DL/I calls to DEDBs cannot include the independent AND, which is used only with secondary indexing. Calls to DEDBs can use all command codes. Only calls to DEDBs that use subset pointers can use the R, S, Z, W, and M command codes. Table 32 shows which calls you can use with these command codes.
Table 32. Subset Pointer Command Codes and Calls Command Code M R S W X X DLET GU GHU X X X X X GN GHN X X X X X GNP GHNP X X X X X ISRT X X X X X X X X REPL X
Processing MSDBs and DEDBs Updating Segments: REPL, DLET, ISRT, and FLD
Three of the calls that you can use to update an MSDB or DEDB are the same ones that you use to update other IMS databases: REPL, DLET, and ISRT. You can issue a REPL call to a related MSDB or nonrelated MSDB, and you can issue any of the three calls for non-terminal-related MSDBs (without terminal-related keys) or DEDBs. When you issue REPL or DLET calls against an MSDB or DEDB, you must first issue a Get Hold call for the segment you want to update, just as you do when you replace or delete segments in other IMS databases. One call that you can use against MSDBs and DEDBs that you cannot use against other types of IMS databases is the Field (FLD) call, which enables you to access and change the contents of a field within a segment. The FLD call has two types: v FLD/VERIFY This type of call compares the value of the field in the target segment to the value you supply in the FSA. v FLD/CHANGE This type of call changes the value of the field in the target segment in the way that you specify in the FSA. A FLD/CHANGE call is only successful if the previous FLD/VERIFY call is successful.
171
Processing MSDBs and DEDBs

The FLD call does in one call what a Get Hold call and a REPL call do in two calls. For example, using the ACCOUNT segment shown in Table 10 on page 17 a bank would need to perform the following processing to find out whether a customer could withdraw a certain amount of money from a bank account: 1. Retrieve the segment for the customer's account. 2. Verify that the balance in the account is more than the amount that the customer wants to withdraw. 3. Update the balance to reflect the withdrawal if the amount of the balance is more than the amount of the withdrawal. Without using the FLD call, a program would issue a GU call to retrieve the segment, then verify its contents with program logic, and finally issue a REPL call to update the balance to reflect the withdrawal. If you use the FLD call with a root SSA, you can retrieve the desired segment. The FLD call has the same format as SSAs for other calls. If no SSA exists, the first segment in the MSDB or DEDB is retrieved. You use the FLD/VERIFY to compare the BALANCE field to the amount of the withdrawal. A FLD/CHANGE call can update the BALANCE field if the comparison is satisfactory. The segment retrieved by a FLD call is the same as can be retrieved by a GHU call. After the FLD call, the position is lost. An unqualified GN call after a FLD call returns the next segment in the current area.
Checking the Contents of a Field: FLD/VERIFY

A FLD/VERIFY call compares the contents of a specified field in a segment to the value that you supply. The way that a FLD/VERIFY call compares the two depends on the operator you supply. When you supply the name of a field and a value for comparison, you can determine if the value in the field is: v Equal to the value you have supplied v Greater than the value you have supplied v Greater than or equal to the value you have supplied v Less than the value you have supplied v Less than or equal to the value you have supplied v Not equal to the value you have supplied After IMS performs the comparison that you have asked for, it returns a status code (in addition to the status code in the PCB) to tell you the results of the comparison. You specify the name of the field and the value that you want its value compared to in a field search argument, or FSA. The FSA is also where IMS returns the status code. You place the FSA in an I/O area before you issue a FLD call, and then you reference that I/O area in the calljust as you do for an SSA in a DL/I call. An FSA is similar to an SSA in that you use it to give information to IMS about the information you want to retrieve from the database. An FSA, however, contains more information than an SSA. Table 33 shows the structure and format of an FSA.
Table 33. FSA Structure FSA Component FLD NAME SC Field Length 8 1
172

Table 33. FSA Structure (continued) FSA Component OP FLD VALUE CON Field Length 1 Variable 1
The five fields in an FSA are: Field Name (FLD Name) This is the name of the field that you want to update. The field must be defined in the DBD. Status Code (SC) This is where IMS returns the status code for this FSA. If IMS successfully processes the FSA, it returns a blank status code. If IMS fails to process the FSA, it returns a FE status code to the PCB to indicate a nonblank status code in the FSA and returns a nonblank FSA status code. The FSA status codes that IMS might return to you on a FLD/VERIFY call are: | | | B The length of the data supplied in the field value is invalid, or the segment length of the data in the database is smaller than required to contain the fields as specified in the DBD. The verify check is unsuccessful. In other words, the answer to your query is no. The field value contains invalid data. The data you supplied in this field is not the same type of data that is defined for this field in the DBD. The requested field is not found in the segment.
D E
Operator (OP) This tells IMS how you want the two values compared. For a FLD/VERIFY call, you can specify: E G H L M N Verify that the value in the field is equal to the value you have supplied in the FSA. Verify that the value in the field is greater than the value you have supplied in the FSA. Verify that the value in the field is greater than or equal to the value you have supplied in the FSA. Verify that the value in the field is less than the value you have supplied in the FSA. Verify that the value in the field is less than or equal to the value you have supplied in the FSA. Verify that the value in the field is not equal to the value you have supplied in the FSA.
Field Value (FLD Value) This area contains the value that you want IMS to compare to the value in the segment field. The data that you supply in this area must be the same type of data in the field you have named in the first field of the FSA. The five types of data are: hexadecimal, packed decimal, alphanumeric (or a combination of data types), binary fullword, and binary halfword. The length of the data in this area must be the same as the length that is defined for this field in the DBD.
173

Exceptions: v If you are processing hexadecimal data, the data in the FSA must be in hexadecimal. This means that the length of the data in the FSA is twice the length of the data in the field in the database. IMS checks the characters in hexadecimal fields for validity before that data is translated to database format. (Only 0 to 9 and A to F are valid characters.) v For packed-decimal data, you do not need to supply the leading zeros in the field value. This means that the number of digits in the FSA might be less than the number of digits in the corresponding database field. The data that you supply in this field must be in a valid packed-decimal format and must end in a sign digit. When IMS processes the FSA, it does logical comparisons for alphanumeric and hexadecimal fields; it does arithmetic comparisons for packed decimal and binary fields. Connector (CON) If this is the only or last FSA in this call, this area contains a blank. If another FSA follows this one, this area contains an asterisk (*). You can include several FSAs in one FLD call, if all the fields that the FSAs reference are in the same segment. If you get an error status code for a FLD call, check the status codes for each of the FSAs in the FLD call to determine where the error is. When you have verified the contents of a field in the database, you can change the contents of that field in the same call. To do this, supply an FSA that specifies a change operation for that field.
Changing the Contents of a Field: FLD/CHANGE

To indicate to IMS that you want to change the contents of a particular field, use an FSA, just as you do in a FLD/VERIFY call. The difference is in the operators that you can specify and the FSA status codes that IMS can return to you after the call. Using Table 33 on page 172 FLD/CHANGE works like this: v You specify the name of the field that you want to change in the first field of the FSA (Field Name). v You specify an operator in the third field of the FSA (Operator), which indicates to IMS how you want to change that field. v You specify the value that IMS must use to change the field in the last area of the FSA (Field Value). By specifying different operators in a FLD/CHANGE call, you change the field in the database in these ways: v Add the value supplied in the FSA to the value in the field. v Subtract the value supplied in the FSA from the value in the field. v Set the value in the database field to the value supplied in the FSA. You code these operators in the FSA with these symbols: v To add: + v To subtract: v To set the field equal to the new value: = You can add and subtract values only when the field in the database contains arithmetic (packed-decimal, binary-fullword, or binary-halfword) data. The status codes you can receive in a FLD/CHANGE FSA are:
174

A B C E F G H Invalid operation; for example, you specified the + operator for a field that contains character data. Invalid data length. The data you supplied in the FSA is not the length that is defined for that field in the DBD. You attempted to change the key field in the segment. Changing the key field is not allowed. Invalid data in the FSA. The data that you supplied in the FSA is not the type of data that is defined for this field in the DBD. You tried to change an unowned segment. This status code applies only to related MSDBs. An arithmetic overflow occurred when you changed the data field. The requested field was not found in the segment.
Example of Using FLD/VERIFY and FLD/CHANGE

The example in this section uses the bank account segment shown in Table 10 on page 17. Assume that a customer wants to withdraw $100 from a checking account. The checking account number is 24056772. To find out whether the customer can withdraw this amount, you must check the current balance. If the current balance is greater than $100, you want to subtract $100 from the balance, and add 1 to the transaction count in the segment. You can do all of this processing by using one FLD call and three FSAs. The three FSAs are described: 1. Verify that the value in the BALANCE field is greater than or equal to $100. For this verification, you specify the BALANCE field, the H operator for greater than or equal to, and the amount. The amount is specified without a decimal point. Field names less than eight characters long must be padded with trailing blanks to equal eight characters. You also have to leave a blank between the field name and the operator for the FSA status code. This FSA looks like this:
BALANCE H10000*
The last character in the FSA is an asterisk, because this FSA will be followed by other FSAs. 2. Subtract $100 from the value in the BALANCE field if the first FSA is successful. If the first FSA is unsuccessful, IMS does not continue processing. To subtract the amount of the withdrawal from the amount of the balance, you use this FSA:
BALANCE -10000*
Again, the last character in the FSA is an asterisk, because this FSA is followed by a third FSA. 3. Add 1 to the transaction count for the account. To do this, use this FSA:
TRANCNT +001
In this FSA, the last character is a blank ( ), because this is the last FSA for this call. When you issue the FLD call, you do not reference each FSA individually; you reference the I/O area that contains all of them.
175
Commit-Point Processing in MSDBs and DEDBs

This section describes the MSDB commit view and DEDBs with an MSDB commit view. (The following information assumes that you are already familiar with the concepts of commit point processing, as described in IMS Version 9: Application Programming: Design Guide.)
MSDB Commit View

When you update a segment in an MSDB, IMS does not apply your updates immediately. Updates do not go into effect until your program reaches a commit point. As a result of the way updates are handled, you can receive different results if you issue the same call sequence against a full-function database or a DEDB and an MSDB. For example, if you issue GHU and REPL calls for a segment in an MSDB, and then issue another Get call for the same segment in the same commit interval, the segment that IMS returns to you is the old value, not the updated one. If, on the other hand, you issue the same call sequence for a segment in a full-function database or DEDB, the second Get call returns the updated segment. When the program reaches a commit point, IMS also reprocesses the FLD VERIFY/CHANGE call. If the VERIFY test passes, the change is applied to the database. If the VERIFY test fails, the changes made since the previous commit point are undone, and the transaction is reprocessed.
DEDBs with MSDB Commit View

Your existing application programs can use either the MSDB commit view or the default DEDB commit view. To use the MSDB commit view for DEDBs, specify VIEW=MSDB on the PCB statement; if you do not specify VIEW=MSDB, the DEDB uses the default DEDB commit view. So no changes to any existing application programs are required in order to migrate your MSDBs to DEDBs. Assume that you specify VIEW=MSDB in the PCB and an application program issues GHU and REPL calls to a DEDB followed by another GHU call for the segment in the same commit interval. Then the application program receives the old value of the data and not the new value from the REPL call. If you do not specify VIEW=MSDB, your application program receives the new updated values of the data, just as you expect for a DEDB or other DL/I database. You can specify VIEW=MSDB for any DEDB PCB. If it is specified for a non-DEDB database, you receive message DFS0904 during ACBGEN. If you issue a REPL call with a PCB that specifies VIEW=MSDB, the segment must have a key. This requirement applies to any segment in a path if command code 'D' is specified. Otherwise, the AM status code is returned. See IMS Version 9: Messages and Codes, Volume 1 for information about that status code. Figure 40 on page 177 shows an example of a PCB that specifies the VIEW option.
176

PCB , TYPE=DB, NAME=DEDBJN21, PROCOPT=A, KEYLEN=30, VIEW=MSDB, POS=M *00000100 *00000200 *00000300 *00000400 *00000500 *00000600 00000700
Figure 40. Sample PCB Specifying View=MSDB
VSO Considerations
VSO is transparent to the processing of an application. Where the data resides is immaterial to the application.
Data Locking for MSDBs and DEDBs

All MSDB calls, including the FLD call, can lock the data at the segment level. The lock is acquired at the time the call is processed and is released at the end of the call. All DEDB calls, with the exception of HSSP calls, are locked at the VSAM CI level. For single-segment, root-only, fixed-length VSO areas, if you specify PROCOPT R or G, the application program can obtain segment-level locks for all calls. If you specify any other PROCOPT, the application program obtains VSAM CI locks. Related Reading: For more information on HSSP, see IMS Version 9: Administration Guide: Database Manager. Segment-level locking (SLL) provides a two-tier locking scheme. First, a share (SHR) lock is obtained for the entire CI. Then, an exclusive (EXCL) segment lock is obtained for the requested segment. This scheme allows for contention detection between SLL users of the CI and EXCL requestors of the CI. When contention occurs between an existing EXCL CI lock user and a SHR CI lock requestor, the SHR CI lock is upgraded to an EXCL CI lock. During the time that this EXCL CI lock is held, subsequent SHR CI lock requests must wait until the EXCL CI is released at the next commit point. DEDB FLD calls are not locked at call time. Instead, the lock is acquired at a commit point. During sync-point processing, the lock is re-acquired (if not already held), and the changes are verified. Verification failure results in the message being reprocessed (for message-driven applications) or an FE status code (for non-message-driven applications). Verification can fail if the segment used by the FLD call has been deleted or replaced before a sync-point. Segment retrieval for a FLD call is the same as for a GU call. An unqualified FLD call returns the first segment in the current area, just as an unqualified GU call does. After the FLD call is processed, all locks for the current CI are released if the current CI is unmodified by any previous call. When a compression routine is defined on the root segment of a DEDB with a root-only structure, and when that root segment is a fixed-length segment, its length becomes variable after being compressed. To replace a compressed segment, you must perform a delete and an insert. In this case, segment level control and locking will not be available.
177
Restrictions on Using Calls for MSDBs
Restrictions on Using Calls for MSDBs

To retrieve segments from an MSDB 1, you can issue Get calls just as you do to retrieve segments from other IMS databases. Because MSDBs contain only root segments, you only use GU and GN calls (and GHU and GHN calls when you plan to update a segment). If the segment name field in the SSA contains *MYLTERM, the GU, GHU, and FLD calls return the LTERM-owned segment, and the remainder of the SSA is ignored. When you are processing MSDBs, you should consider the following differences between calls to MSDBs and to other IMS databases: v You can use only one SSA in a call to an MSDB. v MSDB calls cannot use command codes. v MSDB calls cannot use multiple qualification statements (Boolean operators). v The maximum length for an MSDB segment key is 240 bytes (not 255 bytes, as in other IMS databases). v If the SSA names an arithmetic field (types P, H, or F) as specified in the database description (DBD), the database search is performed using arithmetic comparisons (rather than the logical comparisons that are used for DL/I calls). v If a hexadecimal field is specified, each byte in the database field is represented in the SSA by its two-character hexadecimal representation. This representation makes the search argument twice as long as the database field. Characters in hexadecimal-type SSA qualification statements are tested for validity before translation to the database format. Only numerals 0 through 9 and letters A through F are accepted. v Terminal-related and non-terminal-related LTERM-keyed MSDBs are not supported for ETO or LU 6.2 terminals. Attempted access results in no data being retrieved and an AM status code. See IMS Version 9: Administration Guide: Transaction Manager for more information on ETO and LU 6.2. v MSDBs cannot be shared among IMS subsystems in a sysplex group. When using the Fast Path Expedited Message Handler (EMH), terminal related and non-terminal related with terminal key MSDBs can only be accessed by static terminals. These static terminals run transactions with Sysplex Processing Code (SPC) of Locals Only as specified in DBFHAGU0 (Input Edit Router exit routine).
Processing DEDBs (IMS and CICS with DBCTL)

This section explains subset pointers, the POS call, data locking, and the P and H processing options.
Processing DEDBs with Subset Pointers

Subset pointers and the command codes 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 are a means of dividing 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. (This is further described in Using Subset Pointers on page 181.) Each subset pointer points to the start of a new subset. For example, in Figure 41 on page 179, suppose you
1. This section does not apply to CICS users.
178
Processing DEDBs (IMS, CICS with DBCTL)

define one subset pointer that divides the last three segment occurrences from the first four. Your program can then refer to that subset pointer through command codes and directly retrieve the last three segment occurrences.
Figure 41. Processing a Long Chain of Segment Occurrences with Subset Pointers
You can use subset pointers at any level of the database hierarchy, except at the root level. If you try to use subset pointers at the root level, they are ignored. Figure 42 and Figure 43 on page 180show 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 can set more than one subset pointer to a segment, as shown in Figure 42.
Figure 42. Examples of Setting Subset Pointers
You can also define a one-to-one relationship between the pointers and the segments, as shown inFigure 43 on page 180.
179
Figure 43. Additional Examples of Setting Subset Pointers
Figure 44 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 that is defined by subset pointer 1 is B7.
Figure 44. How Subset Pointers Divide a Chain into Subsets
Before You Use Subset Pointers

For your program to use subset pointers, the pointers must be defined in the DBD for the DEDB and in your program's PSB: v In the DBD, you specify the number of pointers for a segment chain. You can specify as many as eight pointers for any segment chain. v In the PSB, you specify which pointers your program is to use. Define this on the SENSEG statement. (Each pointer is defined as an integer from 1 to 8.) Also, indicate on the SENSEG statement whether your program can set the pointers it uses. If your program has read sensitivity, it cannot set pointers but can only retrieve segments using subset pointers that are already set. If your program has update sensitivity, it can also update subset pointers by using the S, W, M, and Z command codes.
180

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; they are not reset.
Designating Subset Pointers

To use subset pointers in your program, you must know the numbers for the pointers as they were defined in the PSB. When you use the subset pointer command codes, specify the number of each subset pointer you want to use followed by the command code. For example, you use R3 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 SSA invalid and returns an AJ status code.
Using Subset Pointers

To take advantage of subsets, application programs use five command codes. The R command code retrieves the first segment in a subset. The following 4 command codes, which are explained in General Command Codes for DL/I Calls on page 202, redefine subsets by modifying the subset pointers: Z M S W Sets a subset pointer to 0. Sets a subset pointer to the segment following the current segment. Unconditionally sets a subset pointer to the current segment. Conditionally sets a subset pointer to the current segment.
Before your program can set a subset pointer, it must establish a position in the database. A call 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 call. If a call to retrieve a segment is not completely satisfied and a position is not established, the subset pointers remain as they were before the call was made. You can use subset pointer command codes in either an unqualified SSA or a qualified SSA. To use a command code in a call with an unqualified SSA, use the command code along with the number of the subset pointer you want, after the segment name. This is shown in Table 34.
Table 34. Unqualified SSA with Subset Pointer Command Code Seg Name 8 * 1 Cmd Code Variable Ssptr. Variable 1
To use a subset pointer command code with a qualified SSA, use the command code and subset pointer number immediately before the left parenthesis of the qualification statement, as shown in Table 35.
Table 35. Qualified SSA with Subset Pointer Command Code Seg Name 8 * 1 Cmd Code Variable Ssptr. Variable ( 1 Fld Name 8 R.O. 2 Fld Value Variable ) 1
The examples in this section use calls with unqualified SSA. The examples are based on Sample Application Program, which is described in Fast Path Coding Considerations on page 195.
181

Inserting Segments in a Subset: When you use the R command code 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. Example: The following call 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:
ISRT A B (Akey *R1 = A1)
To set subset pointer 1 to the new segment, you use the S command code along with the R command code, as shown in the following example:
ISRT A B (Akey *R1S1 = A1)
If the subset does not exist (subset pointer 1 is set to 0), 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 segment in the chain, the subset pointer is set to 0. Combining Command Codes: You can use the S, M, and W command codes with other command codes, and you can combine subset pointer command codes with each other, as long as they do not conflict. For example, you can use R and S together, but you cannot use S and Z together because their functions conflict. If you combine command codes that conflict, IMS returns an AJ status code to your program. You can use one R command code for each SSA and one update command code (Z, M, S, or W) for each subset pointer.
Subset Pointer Status Codes

If you make an error in an SSA that contains subset pointer command codes, IMS can return either of these status codes to your program: AJ The SSA used an R, S, Z, W, or M command code for a segment that does not have subset pointers defined in the DBD. The subset command codes included in the SSA are in conflict. For example, if one SSA contains an S command code and a Z command code for the same subset pointer, IMS returns an AJ status code. S indicates that you want to set the pointer to current position; Z indicates that you want to set the pointer to 0. You cannot use these command codes in one SSA. The SSA includes more than one R command code. The pointer number following a subset pointer command code is invalid. You either did not include a number, or you included an invalid character. The number following the command code must be between 1 and 8. AM The subset pointer referenced in the SSA is not specified in the program's PSB. For example, if your program's PSB specifies that your program can use subset pointers 1 and 4, and your SSA references subset pointer 5, IMS returns an AM status code.
182

Your program tried to use a command code that updates the pointer (S, W, or M), but the program's PSB did not specify pointer-update sensitivity. | | Your program attempted to open a GSAM database without specifying an IOAREA.
Retrieving Location with the POS Call (for DEDB Only)

With the POS (Position) call, you can: v Retrieve the location of a specific sequential dependent segment. v Retrieve the location of the last-inserted sequential dependent segment, its time stamp, and the IMS ID. v Retrieve the time stamp of a sequential dependent or Logical Begin. v Tell the amount of unused space within each DEDB area. For example, you can use the information that IMS returns for a POS call to scan or delete the sequential dependent segments for a particular time period. POS Call on page 242 explains how you code the POS call and what the I/O area for the POS call looks like. If the area that the POS call specifies is unavailable, the I/O area is unchanged, and the FH status code 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 call. To retrieve this information, issue a POS call with a qualified or unqualified SSA containing the segment name of the sequential dependent. Current position after this kind of POS call is the same place that it would be after a GNP call. After a successful POS call, 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. Exception: If the sequential dependent segment that is the target of the POS call 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 call with an unqualified or qualified SSA containing the root segment as the segment name. Current position after this type of call follows the same rules as position after a GU call.
183

You can also retrieve the position of the SDEP, its time stamp, and the ID of the IMS that owns the segment. To do this, you issue a POS call with a qualified SSA and provide the keyword PCSEGTSP in position one of the I/O area as input to the POS call. The keyword requests the POS call to return the position of the SDEP, its time stamp, and the ID of the IMS that owns the segment. Requirement: The I/O area must be increased in size to 42 bytes to allow for the added data being returned. The I/O area includes a 2-byte LL field that is not shown in Table 36. This LL field is described after Table 36.
Table 36. Qualified POS Call: Keywords and Map of I/O Area Returned Keyword <null> PCSEGTSP Field 1 Area name Field 2 Sequential dependent location from qualified SSA Field 3 Unused CIs in sequential dependent part Field 4 Unused CIs in independent overflow part Field 5 Committed sequential dependent segment time stamp Field 6 IMS ID Field 7 Pad word 0 word 1 word 2 word 3 word 4 Field 3 word 5 Field 4 word 6 word 7 N/A Field 6 word 8 word 9 N/A Field 7
Field 1 Field 1
Field 2 Field 2
Field 5
After a successful POS call, the I/O area contains: LL (Field 1) Area Name An 8-byte field giving the ddname from the AREA statement. (Field 2) Position An 8-byte field containing the position information for the most recently inserted sequential dependent segment. This field contains zeros if no sequential dependent exists for this root. Sequential dependent location from qualified SSA IMS places two pieces of data in this 8-byte field after a successful POS call. The first 4 bytes contain the cycle count, and the second 4 bytes contain the VSAM RBA. If the sequential dependent segment that is the target of the POS call is inserted in the same synchronization interval, no position information is returned. Bytes 11-18 contain X'FF'. Other fields contain normal data. (Field 3) (Not shown in table) A 2-byte field, in binary, containing the total length of the data in the I/O area.
184

Unused CIs in sequential dependent part A 4-byte field containing the number of unused control intervals in the sequential dependent part. (Field 4) Unused CIs in independent overflow part A 4-byte field containing the number of unused control intervals in the independent overflow part. (Field 5) Committed Sequential Dependent Segment Time Stamp An 8-byte field containing the time stamp that corresponds to the SDEP segment located by the qualified POS call. (Field 6) IMS ID Identifies the IMS that owns the CI where the SDEP segment was located. (Field 7) Pad An 8-byte pad area to align the I/O area on a double word boundary. No data is returned to this field.
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 call. This type of call also retrieves the unused space in the independent overflow and sequential dependent parts. After a unsuccessful unqualified POS call, the I/O area contains the length (LL), followed by the same number of entries as existing areas within the database. Each entry contains the fields shown below: Area Name Position Unused SDEP CIs Unused IOV CIs An 8-byte field giving the ddname from the AREA. An 8-byte field with binary zeros. A 4-byte field with binary zeros. A 4-byte field with two binary zeros followed by a bad status code.
Commit-Point Processing in a DEDB

IMS retains database updates in processor storage until the program reaches a commit point. IMS saves updates to a DEDB in Fast Path buffers. The database updates are not applied to the DEDB until after the program has successfully completed commit-point processing. Unlike Get calls to an MSDB, however, a Get call to an updated segment in a DEDB returns the updated value, even if a commit point has not occurred. When a BMP is processing DEDBs, it must issue a CHKP or SYNC call to do commit-point processing before it terminates. Otherwise, the BMP abnormally terminates with abend U1008. If you want a DEDB to have an MSDB commit view, refer to Commit-Point Processing in MSDBs and DEDBs on page 176.
185
P Processing Option
If the P processing option is specified in the PCB for your program, a GC status code is returned to your program whenever a call to retrieve or insert a segment causes a unit of work (UOW) boundary to be crossed. Related Reading: For more information on the UOW for DEDBs, see IMS Version 9: 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 either a SYNC or CHKP call. The advantages of issuing a SYNC or CHKP call after your program receives a GC status code are: v Your position in the database is retained. Issuing a SYNC or CHKP call normally causes position in the database to be lost, and the application program must reestablish position before it can resume processing. v Commit points occur at regular intervals. When a GC status code is returned, no data is retrieved or inserted. In your program, you can either: v Issue a SYNC or CHKP call, and resume database processing by reissuing the call that caused the GC status code. v Ignore the GC status code, and resume database processing by reissuing the call that caused the status code.
H Processing Option
If the H processing option has been specified in the PCB for your call program, a GC status code is returned whenever a call to retrieve or insert a segment causes a unit of work (UOW) or an area boundary to be crossed. The program must cause a commit process before any other calls can be issued to that PCB. If a commit process is not caused, an FR status code results (total buffer allocation exceeded), and all database changes for this synchronization interval are washed (sync-point failure). A GC status code is returned when crossing the area boundary so that the application program can issue a SYNC or CHKP call to force cleanup of resources (such as buffers) that were obtained in processing the previous area. This cleanup might cause successive returns of a GC status code for a GN or GHN call, even if a SYNC or CHKP call is issued appropriately for the previous GC status code. When an application is running HSSP and proceeding through the DEDB AREA sequentially, a buffer shortage condition may occur due to large IOV chains. In this case, a FW status code is returned to the application. Usually, the application issues a commit request and position is set to the next UOW. However, this does not allow the previous UOW to finish processing. In order to finish processing the previous UOW, you can issue a commit request after the FW status code is received and set the position to remain in the same UOW. You must also reposition the application to the position that gave the FW status code. The following shows an example of the command sequence and corresponding application responses.
GN GN GN root1 root2 root3
186

GN CHKP GN SSA=(root4) GN root4 root4 root5 /*FW status code received*/ /*User reposition prior to CHKP*/
Data Locking
For information on how data locking is handled for DEDBs, see Data Locking for MSDBs and DEDBs on page 177.
Calls with Dependent Segments for DEDBs

This section provides information on which calls you can use with direct and sequential dependent segments for DEDBs. The DL/I calls that you can issue against a root segment are: GU, GN (GNP has no meaning for a root segment), DLET, ISRT, and REPL. You can issue all DL/I calls against a direct dependent segment, and you can issue Get and ISRT calls against sequential dependents segments.
Direct Dependent Segments

DL/I calls to direct dependents include the same number of SSAs as existing levels in the hierarchy (a maximum of 15). They can also include command codes and multiple qualification statements. The same rules apply to using command codes on DL/I calls to DEDBs as to full-function databases. Exception: v If you use the D command code in a call to a DEDB, the P processing option need not be specified in the PCB for the program. The P processing option has a different meaning for DEDBs than for full-function databases. (See P Processing Option on page 186.) Some special command codes can be used only with DEDBs that use subset pointers. Your program uses these command codes to read and update the subset pointers. Subset pointers are explained in Processing DEDBs with Subset Pointers on page 178.
Sequential Dependent Segments

Because sequential dependents are stored in chronological order, they are useful in journaling, data collection, and auditing application programs. You can access sequential dependents directly. However, sequential dependents are normally retrieved sequentially using the Database Scan utility. Restriction: When processing sequential dependent segments: v You can only use the F command code with sequential dependents; IMS ignores all other command codes. v You cannot use Boolean operators in calls to sequential dependents. Related Reading: For more information about the utility, see IMS Version 9: Utilities Reference: Database and Transaction Manager.
187

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DEDB DL/I calls to extract DEDB information

DL/I calls can be issued to obtain structural information about Data Entry Databases (DEDBs). Any application that can issue DL/I calls can take advantage of these DL/I calls. There are two basic call types: v The first type returns the minimum I/O area length required for a specific type-2 DL/I call. v The second type returns specific information about the specified DEDB. Each of these DL/I calls uses a call interface block called the Input Output Area Input (IOAI), a Telecommunication-Program Program Specification Block (TP PCB), and specific calls that require an I/O area. Some required initialization of the IOAI is common for all calls and some initialization is specific to an individual call. The IOAI and the I/O area must be obtained in key 8 storage. The following table describes the DL/I calls to extract DEDB information.
Table 37. DEDB DL/I Calls DL/I Call AL_LEN DI_LEN DS_LEN AREALIST Description Returns the minimum length of the I/O area that is required for an AREALIST call. Returns the minimum length of the I/O area that is required for an DEDBINFO call. Returns the minimum length of the I/O area required for a DEDBSTR call. Returns a list of areas that are part of the specified DEDB, with each area mapped by DBFCDAL1. Returns DEDB information from the DMCB, mapped by DBFCDDI1. Returns a list of segments and a segment data for DEDB with each segment mapped by DBFCDDS1.
DEDBINFO DEDBSTR
The DL/I call that uses the standard interface with register 1 must point to IOAI_CA.
IOAI structure
The following figure shows the IOAI structure.
starting offset IOAI_START IOAI_NAME IOAI_#FPU IOAI_#FPI IOAI_SUBC * IOAI_BLEN IOAI_ILEN IOAI_IOAREA * IOAI_CALL IOAI_PCBI DS DC DC DC DC DC DC DC DC DC 0F CL4IOAI 0 CL4#FPU 4 CL8#FPUCDPI 8 CL8 10 A(0) A(0) A(0) A(0) A(0) 18 1C 20 24 28 note *1 *1 *1 *1 *1 *1 *1 *1 *1
188

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
IOAI_IOAI * IOAI_DLEN IOAI_STATUS IOAI_B_LEVEL IOAI_STATUS_RC IOAI_USERVER IOAI_IMSVER * IOAI_IMSLEVEL * IOAI_APPL_NAME IOAI_USERDATA IOAI_TIMESTAMP * IOAI_IN0 IOAI_IN1 IOAI_IN2 IOAI_IN3 IOAI_IN4 * IOAI_FDBK0 IOAI_FDBK1 IOAI_FDBK2 IOAI_FDBK3 IOAI_FDBK4 * IOAI_WA0 IOAI_WA1 IOAI_WA2 IOAI_WA3 IOAI_WA4 * DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC DC A(0) A(0) CL2 XL20 A(0) A(0) A(0) A(0) 2C 30 34 36 38 3C 40 44 *1 *2 *2 *2 *2 *1 *2 *2 *1 *1 *2 *3 *3 *3 *3 *3 *2 *2 *2 *2 *2 *4 *4 *4 *4 *4
CL8 48 CL8 50 CL8 58 input words. A(0) 60 A(0) 64 A(0) 68 A(0) 6C A(0) 70 feedback words A(0) 74 A(0) 78 A(0) 7C A(0) 80 A(0) 84 workareas. A(0) 88 A(0) 8C A(0) 90 A(0) 94 A(0) 98
DS 20F0 9C for future expansion IOAI_END_CHAR DC CL4IEND EC *1 IOAI_LEN len(DBFIOAI) = xF0 bytes
Notes: 1. The user is responsible for initializing these fields. 2. IMS uses these fields to return data to the caller. Fields types are dependent on the DL/I call type and are documented in the DL/I call types descriptions below. 3. Can be used to pass additional data on the DL/I call, as documented in the specific DL/I call types descriptions below. 4. These fields are unchanged and can be used as work areas by the application. The fields in table Table 38 must be initialized for all DEDB DL/I calls.
Table 38. Field initialization for DEDB DL/I calls Field IOAI_NAME IOAI_#FPU IOAI_#FPI IOAI_SUBC IOAI_BLEN Description The characters IOAI identifying this block. The characters #FPU indicating this is a #FPU call. The characters #FPUCDPI indicating this is a subset call. The DL/I call: AL_LEN, AREALIST, DS_LEN, DEDBSTR, DI_LEN or DEDBINFO. The total length of the IOAI (X'F0').
189

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 38. Field initialization for DEDB DL/I calls (continued) Field IOAI_CALL IOAI_PCBI IOAI_IOAI Description Address of IOAI_#FPU. Address of the TPCB. Address of this block. The user must set the high order bit on to indicate the end of the DL/I list. Call version number. Defaults to one. This is the version number of a specific call. This field will be updated in the future if a specific call is altered such that the application must be sensitive to the changes. The chars 'IEND' identifying the end of block.
IOAI_USERVER
IOAI_END_CHAR
The fields in Table 39 are initialized for specific DL/I calls. If a specific call does not need an I/O area, these fields are ignored.
Table 39. Fields initialized for specific DEDB DL/I calls Field IOAI_ILEN IOAI_IOAREA I/O Area Description The total length of the I/O area, including prefix and suffix. Address of the I/O area. First word: The I/O area length (same as IOAI_ILEN). Last word: X'FFFFFFFF', which is an 'end of I/O area' marker. Five input words that might be required.
IOAI_IN0 through IOAI_IN4
The fields in Table 40 are updated by IMS for all the DEDB DL/I call types.
Table 40. Fields updated by IMS for all DL/I call types Field IOAI_DLEN Description The length of the output data that is returned by IMS. This field is informational only. A 2-byte status code. A return code if needed. The maximum version of this call. The IMS level.
IOAI_STATUS IOAI_STATUS_RC IOAI_IMSVER IOAI_IMSLEVEL
The fields in Table 41 might be updated by specific DL/I calls.

Table 41. Fields updated by specific DL/I calls Field I/O Area IOAI_FDBK0 through IOAI_FDBK4 Description First word: unchanged. Data: see specific call types. Last word: potentially changed. Five output words which may return data as documented by specific calls.
190

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
AL_LEN Call
The AL_LEN call returns the minimum length of the I/O area required for an AREALIST call.
Input
IOAI See IOAI structure on page 188. IOAI_IN0 Points to storage containing the DEB name.
Output
IOAI_STATUS Call status, ' ' means successful. IOAI_FDBK0 The minimum length of the I/O area. IOAI_FDBK1 The number of AREAS in this DEDB.
DI_LEN Call
Return the minimum length of the I/O area required for an DEDBINFO call.
Input
Output
IOAI_STATUS Call status, ' ' means successful. IOAI_FDBK0 The minimum length of the I/O area.
DS_LEN Call
Return the minimum length of the I/O area required for a DEDBSTR call.
Input
Output
IOAI_STATUS Call status, ' ' means successful. IOAI_FDBK0 The minimum length of the I/O area.
191

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | IOAI_FDBK1 The number of SEGMENTS in this DEDB.
AREALIST Call
Return a list of areas which are part of the specified DEDB, with each area mapped by DBFCDAL1.
Input
IOAI See IOAI structure on page 188. IOAI_IN0 Points to storage containing the DEB name. I/O Area Formatted as documented above.
Output
IOAI_STATUS Call status, ' ' means successful. IOAI_FDBK0 The minimum length of the I/O area. IOAI_FDBK1 The number of AREAS in this DEDB. The I/O Area
0 4 8 C 14 len-4 ______________________________________//_____________________ | I/O | offset| data | DEDB | area list | end of data | | area | to |length | name | using DBFCDAL1 | marker | | len | data | | | control blocks | xEEEEEEEE | ______________________________________//_____________________ len:4 4 4 8 variable 4
DEDBINFO Call
Return DEDB information from the DMCB, mapped by DBFCDDI1.
Input
IOAI See IOAI structure on page 188. IOAI_IN0 Points to storage containing the DEB name. I/O Area Formatted with length in the first word, and 'FFFFFFFF' as an end of I/O area marker.
Output
IOAI_FDBK0 The minimum length of the I/O area. IOAI_FDBK1 The minimum I/O area for the DEDBSTR call.
192

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | IOAI_FDBK2 The minimum I/O area for the AREALIST call. The I/O Area
0 4 8 C 14 len-4 _____________________________________________________________ | I/O | offset| data | DEDB | the DEDB info | end of data | | area | to |length | name | using DBFCDDI1 | marker | | len | data | | | control block | xEEEEEEEE | _____________________________________________________________ len:4 4 4 8 len(DBFCDDI1) 4
DEDSTR Call
Return a list of segments and segment data for a DEDB with each segment mapped by DBFCDDS1.
Input
IOAI See IOAI structure on page 188. IOAI_IN0 Points to storage containing the DEB name. I/O Area Formatted with length in the first word, and 'FFFFFFFF' as an end of I/O area marker.
Output
IOAI_STATUS The minimum length of the I/O area. IOAI_FDBK0 The minimum I/O area for the DEDBSTR call. IOAI_FDBK1 The minimum I/O area for the SEGMENTS call. The I/O Area
0 4 8 C 14 len-4 ______________________________________//_____________________ | I/O | offset| data | DEDB | segments | end of data | | area | to |length | name | in DBFCDDS1 | marker | | len | data | | | control blocks | xEEEEEEEE | ______________________________________//_____________________ len:4 4 4 offset 0F CL8 0XL4 XL1 X01 X02 X04 X08 X80 X40 X20 X10 XL1 XL1 00 08 08 Area name Flag Bytes Flags for area status: - Area is opened - Temporary bit for backout - Utility active on this area - Error recovery needed - Sequential dep. part full - I/O error - Area stop request - Area restart request Reserved for Flag Byte #2 Reserved for Flag Byte #3
variable
DBFCDAL1 mapping: CDAL_START DS CDAL_ARNM DS CDAL_FLGS DS CDAL_FLG1 DS CDAL_F1OP EQU CDAL_F1BK EQU CDAL_F1UT EQU CDAL_F1ER EQU CDAL_F1AF EQU CDAL_F1EP EQU CDAL_F1ST EQU CDAL_F1RE EQU CDAL_FLG2 DS CDAL_FLG3 DS
09 0A
193

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
CDAL_FLG4 CDAL_LEND CDAL_LEN DS DS DS EQU XL1 0B 1F 0C 0F *-&AA._START; offset 0D CL8 00 H 08 H 0A H 0C H 0E F 10 CL8 14 F 1C 8F 20 0D *-&AA._START; Reserved for Flag Byte #4 for growth End of area list entry Len of area list entry
DBFCDDI0 mapping: CDDI_START DS CDDI_DBNM DS CDDI_ANR DS CDDI_HSLV DS CDDI_SGNR DS CDDI_SEGL DS CDDI_HBLK DS CDDI_RMNM DS CDDI_RMEP DS DS DS CDDI_LEN EQU DBFCDDS1 mapping: CDDS_START DS CDDS_GNAM DS CDDS_GDOF DS CDDS_MAX DS CDDS_MIN DS CDDS_DBOF DS CDDS_NRFLD DS CDDS_SC DS CDDS_PREF DS CDDS_FLG1 DS CDDS_FL1K EQU CDDS_FL1S EQU CDDS_FL1P EQU CDDS_FISRT DS CDDS_PARA DS CDDS_SBLP DS CDDS_LEVL DS CDDS_KEYL DS CDDS_KDOF DS CDDS_RSRVE DS CDDS_CMPC DS CDDS_FLG2 DS DS DS CDDS_END DS CDDS_LEN EQU
Database name Number of areas defined Max SEGM level in the DB Highest valid SEGM code Maximum IOA length Number of anchor blocks Randomizing module name Randomizing module entry point Reserved Align on double word boundary Length of this area (x40)
offset 0F CL8 00 SEGMENT NAME H 08 OFFSET FROM START SEQ TO DATA H 0A MAX SEG LEN H 0C MIN SEG LEN H 0E OFFSET TO SEG ENTRIES FL1 10 NUMBER OF FIELDS IN SEG FL1 11 SEGMENT CODE H 12 POINTER OFFSET IN PARENT PREF X 14 FLAG BYTE X80 KEY SEGMENT X40 SEQUENTIAL DEP SEGMENT X20 PCL POINTER TO PARENT X 15 INSERT RULES H 16 OFFSET TO PARENT SEGMENT F 18 SIBLING POINTER XL1 1C SEGMENT LEVEL XL1 1D KEY LENGTH - 1 H 1E OFFSET TO KEY FIELD IN SEGMENT XL4 20 FOR USE IN UMDR0 | RESERVED A 24 A(CMPC) XL1 28 FLAG BYTE 2 (fixed length) XL3 29 FOR GROWTH 5F 2C for growth 0F END *-&AA._START; len of SDB entry
The following status codes are specific to these new DL/I calls.
Table 42. Status codes for specific DEDB DL/I calls Status Code AA AB AC AD AE AF AG Description Invalid #FPU/#FPUCDPI call. Getmain error. DEDB name not found. The I/O area was not long enough to contain the data. IOAI_LEN was zeros. It must be filled by the caller. The I/O area address was not passed in by IOAI_IOAREA. The IOAI does not point to itself, IOAI_IOAI.
194

| | | | | | | | | | | | | |
Table 42. Status codes for specific DEDB DL/I calls (continued) Status Code AH AI AJ AK AL AM Description The IOAI did not contain 'IOAI'. The I/O area length in the I/O area does not match IOAI. The I/O area did not contain the end-of-list marker. The IOAI did not have end-of-block marker 'IEND'. IOAI_BLEN is not correct. DEDB not passed in via the IOAI on the #FPUCDPI call.
Fast Path Coding Considerations

You can use DL/I calls to access Fast Path databases. You can also use two additional calls: FLD and POS. The type of Fast Path database that you are processing determines when you can use each of these calls. To process MSDBs, you can use these calls: v For nonterminal-related MSDBs: FLD GU and GHU GN and GHN REPL v For terminal-related, fixed MSDBs: FLD GU and GHU GN and GHN REPL v For terminal-related, dynamic MSDBs: DLET FLD GU and GHU GN and GHN ISRT REPL You can use these calls to process a DEDB: v DEQ v DLET v FLD v GU and GHU v GN and GHN v GNP and GHNP v ISRT v POS
195
Fast Path Coding Considerations

v REPL
196
Part 2. Reference
Chapter 10. Command Code Reference . . . . 201 General Command Codes for DL/I Calls . . . . 202 C Command Code . . . . . . . . . . 203 D Command Code . . . . . . . . . . 204 F Command Code . . . . . . . . . . . 205 L Command Code . . . . . . . . . . . 206 N Command Code . . . . . . . . . . 207 P Command Code . . . . . . . . . . . 208 Q Command Code . . . . . . . . . . 208 U Command Code . . . . . . . . . . 211 V Command Code . . . . . . . . . . 212 NULL Command Code . . . . . . . . . 213 DEDB Command Codes for DL/I . . . . . . 213 Sample Application Program . . . . . . . 213 M Command Code . . . . . . . . . . 214 R Command Code. . . . . . . . . . . 215 S Command Code . . . . . . . . . . . 216 W Command Code . . . . . . . . . . 217 Z Command Code. . . . . . . . . . . 218 Chapter 11. DL/I Calls for Database Management . . . . . . . . Database Management Call Summary CIMS Call . . . . . . . . . Format . . . . . . . . . Parameters . . . . . . . . Usage . . . . . . . . . . CLSE Call . . . . . . . . . Format . . . . . . . . . Parameters . . . . . . . . Usage . . . . . . . . . . DEQ Call . . . . . . . . . . Format (Full Function) . . . . Format (Fast Path DEDB) . . . Parameters . . . . . . . . Usage . . . . . . . . . . Restrictions . . . . . . . . DLET Call . . . . . . . . . Format . . . . . . . . . Parameters . . . . . . . . Usage . . . . . . . . . . FLD Call . . . . . . . . . . Format . . . . . . . . . Parameters . . . . . . . . Usage . . . . . . . . . . FSAs . . . . . . . . . . GN/GHN Call . . . . . . . . Format . . . . . . . . . Parameters . . . . . . . . Usage: Get Next (GN) . . . . Usage: Get Hold Next (GHN) . . Usage: HDAM, PHDAM, or DEDB with GN . . . . . . . . . Restrictions . . . . . . . . GNP/GHNP Call . . . . . . . Format . . . . . . . . .
. . . . . 219 . . . . . 219 . . . . . 221 . . . . . 221 . . . . . 221 . . . . . 222 . . . . . 223 . . . . . 223 . . . . . 223 . . . . . 223 . . . . . 224 . . . . . 224 . . . . . 224 . . . . . 224 . . . . . 224 . . . . . 225 . . . . . 225 . . . . . 225 . . . . . 225 . . . . . 226 . . . . . 226 . . . . . 226 . . . . . 227 . . . . . 227 . . . . . 227 . . . . . 229 . . . . . 229 . . . . . 229 . . . . . 230 . . . . . 232 Database . . . . . 232 . . . . . 233 . . . . . 233 . . . . . 233
| | | | |
Parameters . . . . . . . . . . Usage: Get Next in Parent (GNP) . . . Usage: Get Hold Next in Parent (GHNP) GU/GHU Call . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage: Get Unique (GU). . . . . . Usage: Get Hold Unique (GHU) . . . Restrictions . . . . . . . . . . ISRT Call . . . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage . . . . . . . . . . . . OPEN Call . . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage . . . . . . . . . . . . POS Call . . . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage . . . . . . . . . . . . Restrictions . . . . . . . . . . REPL Call . . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage . . . . . . . . . . . . RLSE Call . . . . . . . . . . . Format . . . . . . . . . . . Parameters . . . . . . . . . . Usage . . . . . . . . . . . . Restrictions . . . . . . . . . . Chapter 12. DL/I Calls for System System Service Call Summary . . APSB Call . . . . . . . . Format . . . . . . . . Parameters . . . . . . . Usage . . . . . . . . . CHKP (Basic) Call . . . . . . Format . . . . . . . . Parameters . . . . . . . Usage . . . . . . . . . CHKP (Symbolic) Call . . . . Format . . . . . . . . Parameters . . . . . . . Usage . . . . . . . . . Restrictions . . . . . . . DPSB Call . . . . . . . . Format . . . . . . . . Parameters . . . . . . . Usage . . . . . . . . . GMSG Call . . . . . . . . Format . . . . . . . . Parameters . . . . . . . Usage . . . . . . . . . Restrictions . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
233 234 235 235 236 236 237 237 238 238 238 238 239 241 241 242 242 242 242 243 245 245 245 245 245 246 247 247 247 247 247
Services . . 249 . . . . . . 250 . . . . . . 252 . . . . . . 252 . . . . . . 252 . . . . . . 252 . . . . . . 253 . . . . . . 253 . . . . . . 253 . . . . . . 253 . . . . . . 254 . . . . . . 254 . . . . . . 254 . . . . . . 255 . . . . . . 255 . . . . . . 255 . . . . . . 255 . . . . . . 255 . . . . . . 256 . . . . . . 256 . . . . . . 256 . . . . . . 256 . . . . . . 257 . . . . . . 258
197
GSCD Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . ICMD Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . INIT Call . . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . INQY Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . LOG Call . . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . PCB Call (CICS Online Format . . . . Parameters . . . Usage . . . . . Restrictions . . . RCMD Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . ROLB Call . . . . Format . . . . Parameters . . . Restrictions . . . ROLL Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . ROLS Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . SETS/SETU Call . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . SNAP Call . . . . Format . . . . Parameters . . . Usage . . . . . Restrictions . . . STAT Call . . . . Format . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programs Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
258 258 258 259 259 259 259 259 260 261 261 261 261 261 265 266 266 266 266 275 276 276 276 277 277 277 277 278 278 278 278 278 278 279 279 280 280 280 280 280 281 281 281 281 281 281 281 282 282 282 282 283 283 283 284 284 284 286 286 286 287
Parameters . Usage . . . Restrictions . SYNC Call . . Format . . Parameters . Usage . . . Restrictions . TERM Call (CICS Format . . Usage . . . Restrictions . XRST Call . . Format . . Parameters . Usage . . . Restrictions .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . Only) . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
287 288 288 288 289 289 289 289 289 289 290 290 290 290 290 291 293
Chapter 13. Relationship Between Calls and AIB and PCBs . . . . . . . . . . . . . . 295 Chapter 14. DL/I Test Program (DFSDDLT0) . . Control Statements . . . . . . . . . . . Planning the Control Statement Order . . . . . ABEND Statement. . . . . . . . . . . . Examples of ABEND Statement . . . . . . CALL Statement . . . . . . . . . . . . CALL FUNCTION Statement . . . . . . . CALL DATA Statement . . . . . . . . . OPTION DATA Statement . . . . . . . . FEEDBACK DATA Statement . . . . . . . DL/I Call Functions . . . . . . . . . . Examples of DL/I Call Functions . . . . . . CALL FUNCTION Statement with Column-Specific SSAs . . . . . . . . . DFSDDLT0 Call Functions . . . . . . . . Examples of DFSDDLT0 Call Functions. . . . COMMENT Statement . . . . . . . . . . Conditional COMMENT Statement . . . . . Unconditional COMMENT Statement . . . . Example of COMMENT Statement . . . . . COMPARE Statement . . . . . . . . . . COMPARE DATA Statement . . . . . . . COMPARE AIB Statement . . . . . . . . COMPARE PCB Statement . . . . . . . . Examples of COMPARE DATA and COMPARE PCB Statements . . . . . . . . . . . IGNORE Statement . . . . . . . . . . . Example of IGNORE Statement Using N or . OPTION Statement . . . . . . . . . . . Example of OPTION Control Statement . . . PUNCH CTL Statement . . . . . . . . . . Example of PUNCH CTL Statement . . . . . Example of PUNCH CTL Statement for All Parameters . . . . . . . . . . . . . STATUS Statement . . . . . . . . . . . Examples of STATUS Statement . . . . . . WTO Statement . . . . . . . . . . . . Example of WTO Statement . . . . . . . WTOR Statement . . . . . . . . . . . . Example of WTOR Statement . . . . . . . 297 298 299 300 300 300 300 303 305 305 306 309 317 319 319 320 320 321 321 321 322 323 324 325 327 327 327 328 328 331 331 331 333 334 334 335 335
198
JCL Requirements . . . . . . . . . . . SYSIN DD Statement . . . . . . . . . SYSIN2 DD Statement . . . . . . . . PRINTDD DD Statement . . . . . . . PUNCHDD DD Statement . . . . . . . Using the PREINIT Parameter for DFSDDLT0 Input Restart . . . . . . . . . . . Execution of DFSDDLT0 in IMS Regions . . . Explanation of DFSDDLT0 Return Codes . . . DFSDDLT0 Hints . . . . . . . . . . . Load a Database . . . . . . . . . . Print the Segments in a Database . . . . . Retrieve and Replace a Segment . . . . . Delete a Segment . . . . . . . . . . Do Regression Testing . . . . . . . . Use as a Debugging Aid. . . . . . . . Verify How a Call Is Executed. . . . . .
. . . . . . . . . . . . . . . .
335 336 336 337 337 337 339 339 339 340 340 340 341 341 341 341 343 344 344 345 347 347 349 349 349 350 351 352 353 354 355 357 358 359 360 360 362 362 363 364 365 366 368 370 375
Chapter 15. Adapter for REXX . . . . . . . Sample Exit Routine (DFSREXXU) . . . . . . Addressing Other Environments . . . . . . . REXX Transaction Programs . . . . . . . . IMS Adapter for REXX Overview Diagram . . IVPREXX Sample Application . . . . . . . REXXTDLI Commands . . . . . . . . . . REXXTDLI Calls . . . . . . . . . . . . Return Codes . . . . . . . . . . . . Parameter Handling . . . . . . . . . . Example DL/I Calls . . . . . . . . . . REXXIMS Extended Commands . . . . . . . DLIINFO . . . . . . . . . . . . . . IMSRXTRC . . . . . . . . . . . . . MAPDEF . . . . . . . . . . . . . . MAPGET . . . . . . . . . . . . . . MAPPUT. . . . . . . . . . . . . . SET. . . . . . . . . . . . . . . . SRRBACK and SRRCMIT . . . . . . . . STORAGE . . . . . . . . . . . . . WTO, WTP, and WTL . . . . . . . . . WTOR. . . . . . . . . . . . . . . IMSQUERY Extended Functions . . . . . . Sample Execs Using REXXTDLI . . . . . . . SAY Exec: For Expression Evaluation . . . . PCBINFO Exec: Display Available PCBs in Current PSB . . . . . . . . . . . . . PART Execs: Database Access Examples . . . DOCMD: IMS Commands Front End . . . . IVPREXX: MPP/IFP Front End for General Exec Execution. . . . . . . . . . . . . . Chapter 16. CICS-DL/I User Return Codes . . . . . Not-Open Conditions. . . Invalid Request Conditions .
Interface Block . . . . . . . . 377 . . . . . . . . 378 . . . . . . . . 378
Part 2. Reference
199
200
Chapter 10. Command Code Reference

| | | | This chapter contains reference information on all of the command codes. The following topics provide additional information: v General Command Codes for DL/I Calls on page 202 v DEDB Command Codes for DL/I on page 213 See Table 43, Table 44 on page 202, and Table 45 for all the command codes and their usage. Restriction: Command codes cannot be used by MSDB calls.
Table 43. Summary of Command Codes Command Code C D F Allows You to... Use the concatenated key of a segment to identify the segment. Retrieve or insert a sequence of segments in a hierarchic path using only one call, instead of having to use a separate (path) call for each segment. 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. Move a subset pointer to the next segment occurrence after your current position. (Used with DEDBs only.) Designate segments that you do not want replaced when replacing segments after a Get Hold call. Usually used when replacing a path of segments. Set parentage at a higher level than what it usually is (the lowest-level SSA of the call). Reserve a segment so that other programs will not be able to update it until you have finished processing and updating it. Retrieve the first segment occurrence in a subset. (Used with DEDBs only.) Unconditionally set a subset pointer to the current position. (Used with DEDBs only.) Limit the search for a segment to the dependents of the segment occurrence on which position is established. Use the hierarchic level at the current position and higher as qualification for the segment. Set a subset pointer to your current position, if the subset pointer is not already set. (Used with DEDBs only.) Set a subset pointer to 0, so it can be reused. (Used with DEDBs only.) Null. Use an SSA in command code format without specifying the command code. Can be replaced during execution with the command codes that you want.
L M N P Q R S U
| |
V W Z -
Table 44 on page 202 shows the list of command codes with applicable calls.
201
Command Code Reference

Table 44. Command Codes and Related Calls Command Code C D F L M N P Q R S U V W Z 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 GU GHU X X X X X GN GHN X X X X X GNP GHNP X X X X X X X X X X X X X X X X X X REPL ISRT X X X X X DLET
Table 45. Command Codes for DL/I Calls Command Code C D F L M N P Q R S

1 1 1
Usage Supplies concatenated key in SSA Retrieves or inserts a sequence of segments Starts search with first occurrence Locates last occurrence Moves subset pointer forward to the next segment Prevents replacement of a segment on a path call Establishes parentage of present level Enqueues segment Retrieves first segment in the subset Sets subset pointer unconditionally Maintains current position Maintains current position at present level and higher
U V W Z
1 1
Sets subset pointer conditionally Sets subset pointer to 0 Reserves storage positions for program command codes in SSA
- (null) Note:
1. This command code is used only with DEDBs.
General Command Codes for DL/I Calls

This section has descriptions and examples for general command codes DL/I calls.
202
C Command Code
You can use the C command code to indicate to IMS that (instead of supplying a qualification statement) you are supplying the segments concatenated key as a means of identifying it. You can use either the C command code or a qualification statement, but not both. You can use the C command code for all Get calls and for the ISRT call. When you code the concatenated key, enclose it in parentheses following the *C, and place it in the same position that would otherwise contain the qualification statement. Example: Suppose you wanted to satisfy this request: Did Joan Carter visit the clinic on March 3, 1993? Her patient number is 07755. The PATIENT segments key field is the patient number, and the ILLNESS segments key field is the date field, so the concatenated key is 0775519930303. This number is comprised of four digits for the year, followed by two digits for both the month and the day. You issue a GU call with the following SSA to satisfy the request:
GU ILLNESS *C(0775519930303)
Using the C command code is sometimes more convenient than a qualification statement because it is easier to use the concatenated key than to move each part of the qualification statement to the SSA area during program execution. Using the segment's concatenated key is the equivalent of giving all the SSA in the path to the segment qualified on their keys. Example: Suppose that you wanted to answer this request: What treatment did Joan Carter, patient number 07755, receive on March 3, 1993? Using qualification statements, you would specify the following SSA with a GU call:
GU PATIENT (PATNO EQ07755) ILLNESS (ILLDATE EQ19930303) TREATMNT
Using a C command code, you can satisfy the previous request by specifying the following SSA on a GU call:
GU ILLNESS *C(0775519930303) TREATMNT
If you need to qualify a segment by using a field other than the key field, use a qualification statement instead of the C command code. Only one SSA with a concatenated key is allowed for each call. To return segments to your program in the path to the segment specified by the concatenated key, you can use unqualified SSA containing the D command code. Example: If you want to return the PATIENT segment for Joan Carter to your I/O area, in addition to the ILLNESS segment, use the call:
GU PATIENT *D ILLNESS *C(0775519930303)
203

You can use the C command code with the object segment for a Get call, but not for an ISRT call. The object segment for an ISRT call must be unqualified.
D Command Code
You can use the D command code to retrieve or insert a sequence of segments in a hierarchic path with one call rather than retrieving or inserting each segment with a separate call. A call that uses the D command code is called a path call. For your program to use the D command code, the P processing option must be specified in the PCB, unless your program uses command code D when processing DEDBs. Related Reading: For more information on using the P processing option, see the description of PSB generation in IMS Version 9: Utilities Reference: System.
Retrieving a Sequence of Segments

When you use the D command code with retrieval calls, IMS places the segments in your I/O area. The segments in the I/O area are placed one after the other, left to right, starting with the first SSA you supplied. To have IMS return each segment in the path, you must include the D command code in each SSA. You can, however, include an intervening SSA without the D command code. You do not need to include the D command code on the last segment in the path, because IMS always returns the last segment in the path to your I/O area. The D command code has no effect on IMS's retrieval logic. The only thing it does is cause each segment to be moved to your I/O area. The segment name in the PCB is the lowest-level segment that is retrieved or the last level that is satisfied in the call in the case of a GE (not-found) status code. Higher-level segments with the D command code are placed in the I/O area. If IMS is unable to find the lowest segment your program has requested, it returns a GE (not-found) status code, just as it does if your program does not use the D command code and IMS is unable to find the segment your program has requested. This is true even if IMS reaches the end of the database before finding the lowest segment your program requested. If IMS reaches the end of the database without satisfying any levels of a path call, it returns a GB (end of database) status code. However, if IMS returns one or more segments to your I/O area (new segments for which there was no current position at the start of the current call), and if IMS is unable to find the lowest requested segment, IMS returns a GE status code, even if it has reached the end of the database. The advantages of using the D command code are significant even if your program is not sure that it will need the dependent segment returned by D. For example, suppose that after examining the dependent segment, your program still needs to use it. Using the D command, your program has the segment if you need it, and your program is not required to issue another call for the segment. Example: As an example of the D command code, suppose your program has this request: Compute the balance due for each of the clinic's patients by subtracting the payments received from the amount billed; print bills to be mailed to each patient. To process this request for each patient, your program needs to know the patient's name and address, what the charges are for the patient, and the amount of
204

payment the patient has made. Issue this call until your program receives a GE status code indicating that no more patient segments exist:
GN PATIENT *D BILLING *D PAYMENT
Each time you issue this call, your I/O area contains the patient segment, the billing segment, and the payment segment for a particular person.
Inserting a Sequence of Segments

With ISRT calls, your program can use the D command code to insert a path of segments simultaneously. Your program need not include D for each SSA in the path. Your program just specifies D on the first segment that you want IMS to insert. IMS inserts the segments in the path that follow. Example: Suppose your program has this request: Judy Jennison visited the clinic for the first time. Add a record that includes PATIENT, ILLNESS, and TREATMNT segments. After building the segments in your I/O area, issue an ISRT call with the following SSA:
ISRT PATIENT *D ILLNESS TREATMNT
Not only is the PATIENT segment added, but the segments following the PATIENT segment, ILLNESS and TREATMNT, are also added to the database. You cannot use the D command code to insert segments if a logical child segment in the path exists.
F Command Code
You can use the F command code to start the search with the first occurrence of a certain segment type or to insert a new segment as the first occurrence in a chain of segments.
Retrieving a Segment as the First Occurrence

You can use the F command code for GN and GNP calls. Using it with GU calls is redundant (and is disregarded) because GU calls can already back up in the database. When you use F, you indicate that you want the search to start with the first occurrence of the segment type you indicate under its parent in attempting to satisfy this level of the call. You can use the F command code for GN and GNP calls to back up in the database. You can back up to the first occurrence of the segment type that has current position, or you can back up to a segment type that is before the current position in the hierarchy. Restriction: The parent of the segment that you are backing up from must be in the same hierarchic path as the segment you are backing up to. IMS disregards F when you supply it at the root level or with a GU or GHU. The search must start with the first occurrence of the segment type that you indicate under the parent. When the search at that level is satisfied, that level is treated as though a new occurrence of a segment has satisfied the search. This is
205

true even when the segment that satisfies an SSA where F command code is specified as the same segment occurrence on which DL/I was positioned before the call was processed. When a new segment occurrence satisfies an SSA, the position of all dependent segments is reset. New searches for dependent segments then start with the first occurrence of that segment type under its parent.
Inserting a Segment as the First Occurrence

When you use F with an ISRT call, you are indicating that you want IMS to insert the segment you have supplied as the first segment occurrence of its segment type. Use F with segments that have either no key at all or a non unique key, and that have HERE specified on the RULES operand of the SEGM statement in the DBD. If you specify HERE in the DBD, the F command code overrides this, and IMS inserts the new segment occurrence as the first occurrence of that segment type. Using the F command code to override the RULES specification on the DBD applies only to the path (either logical or physical) that you are using to access the segment for the ISRT call. For example, if you are using the physical path to access the segment, the command code applies to the physical path but not to the logical path. For clarification of using command codes with the RULES specification, ask the database administrator at your installation. Example: Suppose that you specified RULES=HERE in the DBD for the TREATMNT segment. You want to satisfy this request: Mary Martin visited the clinic today and visited a number of different doctors. Add the TREATMNT segment for Dr. Smith as the first TREATMNT segment for the most recent illness. First you build a TREATMNT segment in your I/O area:
19930302ESEDRIX 0040SMITH
Then you issue an ISRT call with the following SSA. This adds a new occurrence of the TREATMNT segment as the first occurrence of the TREATMNT segment type among those with equal keys.
ISRT PATIENT (PATNO ILLNESS *L TREATMNT*F = 06439)
This example applies to HDAM or PHDAM root segments and to dependent segments for any type of database.
L Command Code
You can use the L command code to retrieve the last occurrence of a particular segment type or to insert a segment as the last occurrence of a segment type. The following topics provide additional information: v Retrieving a Segment as the Last Occurrence v Inserting a Segment as the Last Occurrence on page 207
Retrieving a Segment as the Last Occurrence

The L command code indicates that you want to retrieve the last segment occurrence that satisfies the SSA, or that you want to insert the segment occurrence you are supplying as the last occurrence of that segment type. Like F, L simplifies
206

your programming because you can go directly to the last occurrence of a segment type without having to examine the previous occurrences with program logic, if you know that it is the last segment occurrence that you want. L can be used with GU or GHU, because IMS normally returns the first occurrence when you use a GU call. IMS disregards L at the root level. Using L with GU, GN, and GNP indicates to IMS that you want the last occurrence of the segment type that satisfies the qualification you have provided. The qualification is the segment type or the qualification statement of the SSA. If you have supplied just the segment type (an unqualified SSA), IMS retrieves the last occurrence of this segment type under its parent. Example: Suppose you have this request using the medical hierarchy: What was the illness that brought Jennifer Thompson, patient number 10345, to the clinic most recently? In this example, assume that RULES=LAST is specified in the DBD for the database on ILLNESS. Issue this call to retrieve this information:
GU PATIENT (PATNO ILLNESS *L = 10345)
The first SSA gives IMS the number of the particular patient. The second SSA asks for the last occurrence (in this case, the first occurrence chronologically) of the ILLNESS segment for this patient.
Inserting a Segment as the Last Occurrence

Use L with ISRT only when the segment has no key or a non unique key, and the insert rule for the segment is either FIRST or HERE. Using the L command code overrides both FIRST and HERE for HDAM or PHDAM root segments and dependent segments in any type of database. Using the L command code to override the RULES specification on the DBD applies only to the path (either logical or physical) that you are using to access the segment for the ISRT call. For example, if you are using the physical path to access the segment, the command code applies to the physical path but not to the logical path. For clarification of using command codes with the RULES specification, ask your database administrator.
N Command Code
The N command code prevents you from replacing a segment on a path call. In conjunction with the D command code, it lets the application program to process multiple segments using one call. Alone, the D command code retrieves a path of segments in your I/O area. With the N command code, the D command code lets you distinguish which segments you want to replace. Example: The following code only replaces the TREATMNT segment.
GHU PATIENT*D(PATNO = 06439) ILLNESS *D(ILLDATE =19930301) TREATMNT PATIENT*N(PATNO = 06439) ILLNESS *N(ILLDATE =19930301) TREATMNT
REPL
Restriction: If you use D and N command codes together, IMS retrieves the segment but does not replace it.
207

The N command code applies only to REPL calls, and IMS ignores it if you include the code in any other call.
P Command Code
Ordinarily, IMS sets parentage at the level of the lowest segment that is accessed during a call. To set parentage at a higher level, you can use the P command code in a GU, GN, or GNP call. The parentage that you set with P works just like the parentage that IMS sets: it remains in effect for subsequent GNP calls, and is not affected by ISRT, DLET, or REPL calls. It is only affected by GNP if you use the P command code in the GNP call. Parentage is canceled by a subsequent GU, GHU, GN, or GHN. Use the P command code at only one level of the call. If you mistakenly use P in multiple levels of a call, IMS sets parentage at the lowest level of the call that includes P. If IMS cannot fully satisfy the call that uses P (for example, IMS returns a GE status code), but the level that includes P is satisfied, P is still valid. If IMS cannot fully satisfy the call including the level that contains P, IMS does not set any parentage. You would receive a GP (no parentage established) if you then issued a GNP. If you use P with a GNP call, IMS processes the GNP call with the parentage that was already set by preceding calls. IMS then resets parentage with the parentage you specified using P after processing the GNP call. Example: If you want to send a current bill to all of the patients seen during the month, the determining value is in the ILLNESS segment. You want to look at only patients whose ILLNESS segments have dates after the first of the month. For patients who have been to the clinic during the month, you need to look at their addresses and the amount of charges in the BILLING segment so that you can print a bill. For this example, assume the date is March 31, 1993. Issue these two calls to process this information:
GN GNP PATIENT *PD ILLNESS (ILLDATE >=19930301) BILLING
After you locate a patient who has been to the clinic during the month, you issue the GNP call to retrieve that patient's BILLING segment. Then you repeat the GN call to find each patient who has been to the clinic during the month, until IMS returns a GB status code.
Q Command Code
Use the Q command code if you want to prevent another program from updating a segment until your program reaches a commit point. The Q command code tells IMS that your application program needs to work with a segment and that no other tasks can be allowed to modify the segment until the program has finished. This means that you can retrieve segments using the Q command code, then retrieve them again later, knowing that they have not been altered by another program. (You should be aware, however, that reserving segments for the exclusive use of your program can affect system performance.)
208

You can use the Q command code in batch programs in a data-sharing environment and in CICS and IMS online programs. IMS ignores Q in non-data-sharing batch programs.
Limiting the Number of Database Calls

For full function, before you use the Q command code in your program, you must specify a MAXQ value during PSBGEN. This establishes the maximum number of database calls (with Q command codes) that you can make between sync points. Related Reading: For information on PSBGEN, see IMS Version 9: Utilities Reference: System. Fast Path does not support the MAXQ parameter. Consequently in Fast Path, you can issue as many database calls with Q command codes as you want.
Using Segment Lock Class

For full function, when you use the Q command code to retrieve a segment, you specify the letter Q followed by a letter (A-J), designating the lock class of that segment (for example, QA). If the lock class is not a letter (A-J), IMS returns the status code GL. Fast Path supports the Q command code alone, without a letter designating the lock class. However, for consistency between Fast Path and full function, Fast Path treats the Q command code as a 2-byte string, where the second byte must be a letter (A-J). If the second byte is not a letter (A-J), IMS returns the status code AJ. Example: Suppose a customer wants to place an order for items 1, 2, and 3, but only if 50 item 1's, 75 item 2's, and 100 item 3's are available. Before placing this order, the program must examine all three item segments to determine whether an adequate number of each item is available. You do not want other application programs to change any of the segments until your program has determined this and, if possible, placed the order. To process this request for full function, your program uses the Q command code when it issues the Get calls for the item segments. When you use the Q command code in the SSA, you assign a lock class immediately following the command code in the SSA.
GU GU GU PART ITEM PART ITEM PART ITEM X 1 X 2 X 3 *QA *QA *QA
Exception: For Fast Path, the second byte of the lock class is not interpreted as lock class 'A'. After retrieving the item segments, your program can examine them to determine whether an adequate number of each item are on hand to place the order. Assume 100 of each item are on hand. Your program then places the order and updates the database accordingly. To update the segment, your program issues a GHU call for each segment and follows it immediately with a REPL call:
209

GHU REPL GHU REPL GHU REPL ITEM ITEM ITEM ITEM ITEM ITEM 1 1 with the value 50 2 2 with the value 25 3 3 with the value 0
Using the DEQ Call with the Q Command Code

When you use the Q command code and the DEQ call, you reserve and release segments. For full function, to issue a DEQ call against an I/O PCB to release a segment, you place the letter designating the segment's lock class in the first byte of an I/O area. Then, you issue the DEQ call with the name of the I/O area that contains the letter. A DEDB DEQ call is issued against a DEDB PCB. Because Fast Path does not support lock class, a DEDBDEQ call does not require that a lock class be specified in the I/O area. Restriction: The EXEC DL/I interface does not support DEDB DEQ calls, because EXEC DL/I disallows a PCB for DEQ calls.
Retrieving Segments with Full-Function DEQ Calls

The DEQ call releases all segments that are retrieved using the Q command code, except: v Segments modified by your program, until your program reaches a commit point v Segments required to keep your position in the hierarchy, until your program moves to another database record v A class of segments that has been locked again as another class If your program only reads segments, it can release them by issuing a DEQ call. If your program does not issue a DEQ call, IMS releases the reserved segments when your program reaches a commit point. By releasing them with a DEQ call before your program reaches a commit point, you make them available to other programs more quickly.
Retrieving Buffers with Fast Path DEQ Calls

DEQ calls cause Fast Path to release a buffer that satisfies one of the conditions: v The buffer has not been modified, or the buffer does not protect a valid root position. v The buffer has been protected by a Q command code. Fast Path returns an FW status code when no buffers can be released for a DEQ call. Any CI locking or segment-level locking performed with a Q command code is protected from other application programs until a DEQ call is issued or a commit point is reached.
Considerations for Root and Dependent Segments (Full Function Only)

| | The following considerations may apply to your application programs based on the type of data-sharing environment and locking used.
210

| | | | | | | | | | | | | | In a non-data-sharing environment using program isolation (PI) locking: If you use the Q command code on a root segment, other programs in which the PCB does not have update capability can access the database record. Programs in which the PCB has update capability cannot access any of the segments in that database record. If you use the Q command code on a dependent segment, other programs can read the segment using one of the Get calls without the hold. The Q command code does not hold segments from one step of a conversation to another. In a data-sharing environment using internal resource lock manager (IRLM) locking: If you use the Q command code on either a root or dependent segment, other programs in which the PCB does not have update capability can access the database record. Programs in which the PCB has update capability cannot access any of the segments in that database record. Related Reading: For more information on the relationship between the Q command code and the DEQ call, see Reserving Segments for the Exclusive Use of Your Program on page 118.
U Command Code
As IMS satisfies each level in a retrieval or ISRT call, a position on the segment occurrence that satisfies that level is established. The U command code prevents position from being moved from a segment during a search of its hierarchic dependents. If the segment has a unique sequence field, using this code is equivalent to qualifying the SSA so that it is equal to the current value of the key field. When a call is being satisfied, if the position is moved above the level that the U code was issued at, the code has no effect for the segment type whose parent changed position. U is especially useful when unkeyed dependents or non unique keyed segments are being processed. The position on a specific occurrence of an unkeyed or non unique keyed segment can be held by using this code. Example: Suppose you want to find out about the illness that brought a patient named Mary Warren to the clinic most recently, and about the treatments she received for that illness. Figure 45 shows the PATIENT, ILLNESS, and TREATMNT segments for Mary Warren.
Figure 45. U Command Code Example
To retrieve this information, retrieve the first ILLNESS segment and the TREATMNT segments associated with that ILLNESS segment. To retrieve the most recent ILLNESS segment, you can issue the following GU call:
211

GU PATIENT (PATNO ILLNESS *L = 05810
After this call, IMS establishes a position at the root level on the PATIENT segment with the key 05810 and on the last ILLNESS segment. Because other ILLNESS segments with the key 19860412 may exist, you can think of this one as the most recent ILLNESS segment. You might want to retrieve the TREATMNT segment occurrences that are associated with that ILLNESS segment. You can do this by issuing the GN call below with the U command code:
GN PATIENT *U ILLNESS *U TREATMNT
In this example, the U command code indicates to IMS that you want only TREATMNT segments that are dependents of the ILLNESS and PATIENT segments on which IMS has established position. Issuing the above GN call the first time retrieves the TREATMNT segment with the key of 19860412. Issuing the GN call the second time retrieves the TREATMNT segment with the key 19860418. If you issue the call a third time, IMS returns a not-found status code. The U command code tells IMS that, if it does not find a segment that satisfies the lower qualification under this parent, it cannot continue looking under other parents. If the U command code was not in the PATIENT SSA, the third GN call causes IMS to move forward at the root level in an attempt to satisfy the call. If you supply a U command code for a qualified SSA, IMS ignores the U. If used in conjunction with command code F or L, the U command code is disregarded at the level and all lower levels of SSA for that call.
V Command Code
Using the V command code on an SSA is similar to using a U command code in that SSA and all preceding SSA. Specifying the V command code for a segment level tells IMS that you want to use the position that is established at that level and above as a qualification for the call. Using the V command code is analogous to qualifying your request with a qualified SSA that specifies the current IMS position. Example: Suppose that you wanted to answer this request: Did Joan Carter, patient number 07755, receive any treatment on March 3, 1993? Using a qualified SSA, specify the following call:
GU PATIENT (PATNO = 07755) ILLNESS (ILLDATE =19930303) TREATMNT
If you have position established on the PATIENT segment for patient number 07755 and on the ILLNESS segment for March 3, 1993, you can use your position to retrieve the TREATMNT segments in which you are interested. You do this by specifying the V command code as follows:
GN PATIENT ILLNESS *V TREATMNT
212

Using the V command code for a call is like establishing parentage and issuing a subsequent GNP call, except that the V command code sets the parentage for the call it is used with, not for subsequent calls. For example, to satisfy the previous request, you could have set parentage at the ILLNESS segment level and issued a GNP to retrieve any TREATMNT segments under that parent. With the V command code, you specify that you want the ILLNESS segment to be used as parentage for that call. You can specify the V command code for any parent segment. If you use the V command code with a qualified SSA, it is ignored for that level and for any higher level that contains a qualified SSA.
NULL Command Code

The null command code (-) enables you to reserve one or more positions in a SSA in which a program can store command codes, if they are needed during program execution. Example: Reserve position for two command codes as follows:
GU PATIENT *--(PATNO = 07755) ILLNESS (ILLDATE =19930303) TREATMNT
Using the null command code lets you use the same set of SSAs for more than one purpose. However, dynamically modifying the SSA makes debugging more difficult.
DEDB Command Codes for DL/I

The M, R, S, W, and Z command codes are only used with a DEDB. The examples in this topic are based on the scenario given in Sample Application Program.
Sample Application Program

The examples in this section are based on one sample application programthe recording of banking transactions for a passbook (savings account) 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 0. An application program that updates the database later will be able to tell that no unposted transactions exist. Figure 46 summarizes the processing that is performed when the passbook is unavailable and when it is available.
213
Figure 46. Processing for the Passbook Example
M Command Code
To move the subset pointer forward to the next segment after your current position, your program issues a call with the M command code. Using the passbook account example, suppose that you want to post some, but not all, of the transactions, and that you want 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 47.
GU B A *R1M1 (AKEY
If the current segment is the last in the chain, and you use an M command code, IMS sets the pointer to 0.
214
Figure 47. Moving the Subset Pointer to the Next Segment after Your Current Position
R Command Code
To retrieve the first segment occurrence in the subset, your program issues a Get call with the R command code. The R command code does not set or move the pointer. It indicates to IMS that you want to establish position on the first segment occurrence in the subset. The R command code is like the F command code, except that the R command code applies to the subset instead of to the entire segment chain. Using the passbook account example, suppose that Bob Emery visits the bank and brings his passbook; you want to post all of the unposted transactions. Because subset pointer 1 was previously set to the first unposted transaction, your program uses the following call to retrieve that transaction:
GU A B (AKEY *R1 = A1)
As shown by Figure 48 on page 216, this call retrieves segment B5. To continue processing segments in the chain, you can issue GN calls as you would if you were not using subset pointers. If the subset does not exist (subset pointer 1 has been set to 0), IMS returns a GE status code, and your position in the database will be immediately following the last segment in the chain. Using the passbook example, the GE status code tells
215

you that no unposted transactions exist.
Figure 48. Retrieving the First Segment in a Chain of Segments
You can specify only one R command code for each SSA. If you use more than one R in a SSA, IMS returns an AJ status code to your program. You can use R with other command codes, except F and Q. Other command codes in a SSA take effect after the R command code has been processed, and after position has been successfully established on the first segment in the subset. If you use the L and R command codes together, the last segment in the segment chain is retrieved. (If the subset pointer that was specified with the R command code, IMS returns a GE status code instead of the last segment in the segment chain.) Do not use the R and F command codes together. If you do, you will receive an AJ status code. The R command code overrides all insert rules, including LAST.
S Command Code
To set a subset pointer unconditionally, regardless of whether it is already set, your program issues a call with the S command code. W Command Code on page 217 describes how to set a subset pointer only if it is not already set. When your program issues a call that includes the S command code, IMS sets the pointer to your current position. 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:
GU GN A B B (AKEY *R1 *S1 = B1)
After you issue this call, instead of pointing to segment B5, subset pointer 1 points to segment B6, as shown in Figure 49 on page 217.
216
Figure 49. Unconditionally Setting the Subset Pointer to Your Current Position
W Command Code
Like the S command code, the W command code sets the subset pointer conditionally. Unlike the S command code, the W command code updates the subset pointer only if the subset pointer is not already set to a segment. Example: Using the passbook example, suppose 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 that later, when you post the transactions, you can immediately access the first one. The following call sets the subset pointer to the transaction you are inserting if it is the first unposted one.
ISRT A B (AKEY *W1 = A1)
217

As shown by Figure 50, this call sets subset pointer 1 to segment B5. If unposted transactions already exist, the subset pointer is not changed.
Figure 50. Conditionally Setting the Subset Pointer to Your Current Position
Z Command Code
The Z command code sets the value of the subset pointer to 0. After your program issues a call with the Z command code, the pointer is no longer set to a segment, and 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 0.) Example: Using the passbook example, suppose that you used the R command code to retrieve the first unposted transaction. You then process the chain of segments, posting the transactions. After posting the transactions and inserting any new ones into the chain, use the Z command code to set the subset pointer to 0 as shown in the following call:
ISRT A B (AKEY *Z1 = A1)
After this call, subset pointer 1 is set to 0, which indicates to a program that subsequently updates the database that no unposted transactions exist.
218
Chapter 11. DL/I Calls for Database Management

This chapter describes the calls you can use with IMS DB to perform database management functions in your application program. The calls are listed in alphabetical order. Each call description contains: v A syntax diagram v Definitions for parameters that are available to the call v Details on how to use the call in your application program v Restrictions on call usage, where applicable Each parameter is described as an input parameter or output parameter. Input refers to input to IMS from the application program. Output refers to output from IMS to the application program. Database management calls must use either db pcb or aib parameters. The syntax diagrams for these calls begin with the function parameter. The call, call interface (xxxTDLI), and parmcount (if it is required) are not included in the syntax diagrams. | The following topics provide additional information: v Database Management Call Summary v CIMS Call on page 221 v CLSE Call on page 223 v DEQ Call on page 224 v DLET Call on page 225 v FLD Call on page 226 v GN/GHN Call on page 229 v GNP/GHNP Call on page 233 v GU/GHU Call on page 235 v ISRT Call on page 238 v OPEN Call on page 241 v POS Call on page 242 v REPL Call on page 245 v RLSE Call on page 247 Related Reading: For specific information about coding your program in assembler language, C language, COBOL, Pascal, and PL/I, see Chapter 3, Defining Application Program Elements, on page 53. For information on the DL/I calls used for transaction management and EXEC DLI commands used in CICS, see IMS Version 9: Application Programming: Transaction Manager and IMS Version 9: Application Programming: EXEC DLI Commands for CICS and IMS.
Database Management Call Summary

Table 46 on page 220 shows the parameters that are valid for each database management call. Optional parameters are enclosed in brackets ([ ]).
219

Restriction: Language-dependent parameters are not shown here. The variable parmcount is required for all PLITDLI calls. Either parmcount or VL is required for assembler language calls. Parmcount is optional in COBOL, C, and Pascal programs. Related Reading: For more information on language-dependent application elements, see Chapter 3, Defining Application Program Elements, on page 53.
Table 46. Summary of DB Calls Function Code CIMS Meaning and Use Options Initializes and terminates the ODBA interface in a z/OS application region. Close Dequeue Closes a GSAM database explicitly Releases segments reserved by Q command code Removes a segment and its dependents from the database Accesses a field within a segment Retrieves subsequent message segments Retrieves dependents sequentially Retrieves segments and establishes a starting position in the database Retrieves subsequent message segments Retrieves dependents sequentially Retrieves segments and establishes a starting position in the database Loads and adds one or more segments to the database Opens a GSAM database explicitly Retrieves the location of a specific dependent or last-inserted sequential dependent segment Parameters aib Valid for DB/DC, IMS DB
CLSE DEQ
function, gsam pcb or DB/DC, DBCTL, DB aib batch, ODBA function, i/o pcb (full DB batch, BMP, MPP, function only), or aib, IFP, DBCTL, ODBA i/o area (full function only) function, db pcb or aib, i/o area, [ssa] function, db pcb or aib, i/o area, rootssa function, db pcb or aib, i/o area, [ssa] function, db pcb or aib, i/o area, [ssa] function, db pcb or aib, i/o area, [ssa] DB/DC, DBCTL, DB batch, ODBA DB/DC, ODBA DB/DC, DBCTL, DB batch, ODBA DB/DC, DBCTL, DB batch, ODBA DB/DC, DBCTL, DB batch, ODBA
DLET
Delete
FLD GHN GHNP GHU
Field Get Hold Next Get Hold Next in Parent Get Hold Unique
GN
Get Next
function, db pcb or aib, i/o area, [ssa or rsa] function, db pcb or aib, i/o area, [ssa] function, db pcb or aib, i/o area, [ssa or rsa] function, db pcb or aib, i/o area, [ssa or rsa]
DB/DC, DBCTL, DB batch, ODBA DB/DC, DBCTL, DB batch, ODBA DB/DC, DBCTL, DB batch, ODBA
GNP GU
Get Hold Next in Parent Get Unique
ISRT
Insert
DB/DC, DCCTL, DB batch, ODBA
OPEN POS
Open Position
function, gsam pcb or DB/DC, DBCTL, DB aib, [i/o area] batch, ODBA function, db pcb or aib, i/o area, [ssa] DB/DC, DBCTL, DB batch, ODBA
220

Table 46. Summary of DB Calls (continued) Function Code REPL Meaning and Use Replace Options Changes values of one or more fields in a segment Parameters function, db pcb or aib, i/o area, [ssa] Valid for DB/DC, DBCTL, DB batch, ODBA DB/DC, DBCTL, DB batch, ODBA
RLSE
Release
Releases all locks held function, db pcb or for unmodified data. aib, i/o area, [ssa]
CIMS Call
The CIMS call is used to initialize and terminate the ODBA interface in a z/OS application region.
Format
CIMS aib
Call Name CIMS
DB/DC X
IMS DB X
DCCTL
DB Batch
TM Batch
Parameters
aib Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye-catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB length. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Character value. This field is optional. AIBSFUNC Subfunction code. This field must contain one of the 8-byte subfunction codes as follows: | | | | | | | | | CONNECT AIBRSA1. Address of the CONNECT parameter list.
Table 47. CIMS CONNECT parameter list format Offset X'00' X'04' Length X'04' X'04' Field Input Input Usage description Count of connect request table entries. Address of the connect request table.
221
DB Call: CIMS
| | | | | | | | | | | | | | | | | | | | | | | |
X'08' X'0C' X'10' X'04' X'04' X'04' Output Output Output Table 48. CIMS CONNECT table entry format Offset X'00' X'04' Length X'04' X'04' Field Input Input Usage description 1- to 4-character IMS alias name (cccc) from the startup properties table DFScccc0, where cccc is the alias name. 0 or the 4-byte address of the connection properties table (DFSPRP). A value of 0 indicates that ODBA loads a startup properties table named DFScccc0, where cccc is the alias name. This member is constructed by specifying the DFSPRP macro in DFScccc0, then assembling and linking the member. This member must be in the STEPLIB or JOBLIB of the ODBA application job. A non-zero value indicates that the caller supplies the address of the connection properties parameter table. The table is mapped by the DFSPRP macro. Connect request return code for this entry. Return codes are those documented for AIBRETRN. Connect request return code for this entry. Return codes are those documented for AIBREASN Connect request error extension code for this entry. The error extension might contain additional diagnostic information specific to the return and reason codes.
INIT AIBRSNM2. A 4-character ID of the ODBA startup table (optional). TERM AIBRSNM2. A 4-character ID of the ODBA startup table representing the IMS connection that is to be terminated. TALL Terminate all IMS connections.
Usage
The CIMS call is used by an application program that is running in an application address space to establish or terminate the ODBA environment. | | | | | | | | | | CONNECTb Use the CIMS CONNECT call to initialize the ODBA environment within the ODBA address space and to subsequently connect to one or more IMS DBCTL or IMS DB or TM subsystems. The CIMS CONNECT can be issued instead of, or in addition to, the CIMS INIT call. The CIMS CONNECT call performs ODBA initialization if it has not already been done. The call can be issued with AIBRSA1 set to -1 (X'FFFFFFFF') to perform initialization only. The connect request table contains one or more connect request entries in contiguous storage. The format of the connect request table entries is described in Table 48. INITbbbb The CIMS subfunction INIT must be issued by the application to establish the ODBA environment in the z/OS application address space. Optionally, AIBRSNM2 can specify the 4-character ID of the ODBA Startup table member. This is the member named DFSxxxx0 where xxxx is equal to the 4-character ID. If AIBRSNM2 is specified, ODBA will attempt to establish a
222
DB Call: CIMS
connection to the IMS specified in the DFSxxxx0 member after the ODBA environment has been initialized in the z/OS application address space. TERMbbbb The CIMS subfunction TERM can be issued to terminate one and only one IMS connection. AIBRSNM2 specifies the 4-character ID of the startup table member representing the IMS connection to be terminated. Upon completion of the TERM subfunction the ODBA environment will remain intact in the z/OS application address space. Note: If the application that issued CIMS INIT chooses to return to the operating system following completion of the CIMS TERM, the address space will experience a system abend A03. This can be avoided by issuing the CIMS TALL prior to returning to the operating system TALLbbbb The CIMS subfunction TALL must be issued to terminate all IMS connections and terminate the ODBA environment in the application address space.
CLSE Call
The close (CLSE) call is used to explicitly close a GSAM database. For more information on GSAM, see Chapter 8, Processing GSAM Databases, on page 157.
Format
CLSE gsam pcb aib
Call Name For GSAM: CLSE
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
gsam pcb Specifies the GSAM PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB length. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a GSAM PCB.
Usage
For information on using CLSE, see Explicit Open and Close Calls to GSAM on page 161.
223
DB Call: DEQ
DEQ Call
The Dequeue (DEQ) call is used to release a segment that is retrieved using the Q command code.
Format (Full Function)

DEQ i/o pcb aib i/o area
Format (Fast Path DEDB)

DEQ DEDB pcb aib
Call Name For Full-Function and DEDB: DEQ
DB/DC X
DBCTL X
DCCTL
DB Batch X
TM Batch
Parameters
DEDB pcb (Fast Path only) Specifies any DEDB PCB for the call. i/o pcb (full function only) Specifies the I/O PCB for the DEQ call. This is an input and output parameter. aib Specifies the AIB for the call. This is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area (full function only) Specifies the 1-byte area containing a letter (A-J), which represents the lock class of the locks to be released. This is a mandatory input parameter.
Usage
The DEQ call releases all segments that are retrieved using the Q command code, except: v Segments modified by your program, until your program reaches a commit point
224
DB Call: DEQ
v Segments required to keep your position in the hierarchy, until your program moves to another database record v A class of segments that has been locked using a different lock class If your program only reads segments, it can release them by issuing a DEQ call. If your program does not issue a DEQ call, IMS releases the reserved segments when your program reaches a commit point. By releasing the segments with a DEQ call before your program reaches a commit point, you make them available to other programs more quickly. For more information on the relationship between the DEQ call and the Q command code, see Reserving Segments for the Exclusive Use of Your Program on page 118.
Restrictions
In a CICS DL/I environment, calls made from one CICS (DBCTL) system are supported in a remote CICS DL/I environment, if the remote environment is also CICS (DBCTL).
DLET Call
The Delete (DLET) call is used to remove a segment and its dependents from the database.
Format
DLET db pcb aib i/o area
ssa
Call Name For Full-Function: For DEDB: For MSDB: DLET DLET DLET
DB/DC X X X
DBCTL X X
DCCTL
DB Batch X
TM Batch
Parameters
db pcb Specifies the DB PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
225
DB Call: DLET
AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area in your program that communicates with IMS. This parameter is an input parameter. Before deleting a segment, you must first issue a Get Hold call to place the segment in the I/O area. You can then issue the DLET call to delete the segment and its dependents in the database. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA that you supply in the call point to data areas in your program where the SSAs have been defined for the call. You can use only one SSA in the parameter. This parameter is optional for the DLET call.
Usage
The DLET call must be preceded by one of the three Get Hold calls. When you issue the DLET call, IMS deletes the held segment, along with all its physical dependents from the database, regardless of whether your program is sensitive to all of these segments. IMS rejects the DLET call if the preceding call for the PCB was not a Get Hold, REPL, or DLET call. If the DLET call is successful, the previously retrieved segment and all of its dependents are removed from the database and cannot be retrieved again. If the Get Hold call that precedes the DLET call is a path call, and you do not want to delete all the retrieved segments, you must indicate to IMS which of the retrieved segments (and its dependents, if any) you want deleted; to do this, specify an unqualified SSA for that segment. Deleting a segment this way automatically deletes all dependents of the segment. Only one SSA is allowed in the DLET call, and this is the only time a SSA is applicable in a DLET call. No command codes apply to the DLET call. If you use a command code in a DLET call, IMS disregards the command code.
FLD Call
The Field (FLD) call is used to access a field within a segment for MSDBs or DEDBs.
Format
FLD db pcb aib i/o area
ssa
Call Name For MSDB: For DEDB: FLD FLD
DB/DC X X
DBCTL
DCCTL
DB Batch
TM Batch
226
DB Call: FLD
Parameters
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies your program's I/O area, which contains the field search argument (FSA) for this call. This parameter is an input parameter. ssa Specifies the SSA, if any, that you want to use in this call. You can use up to 15 SSAs in this input parameter. The SSA that you supply will point to those data areas that you have defined for the call. This parameter is optional for the FLD call.
Usage
Use the FLD call to access and change the contents of a field within a segment. The FLD call does two things for you: it compares the value of a field to the value you supply (FLD/VERIFY), and it changes the value of the field in the way that you specify (FLD/CHANGE). All DL/I command codes are available to DEDBs, using the FLD call. The FLD call formats for DEDBs are the same as for other DL/I calls. So, if your MSDBs have been converted to DEDBs, you do not need to change application programs that use the FLD call. For more information on the FLD call, see Updating Segments: REPL, DLET, ISRT, and FLD on page 171. You can also use the FLD call in application programs for DEDBs, instead of the combination of GHU, REPL, and DL/I calls.
FSAs
The field search argument (FSA) is equivalent to the I/O area that is used by other DL/I database calls. For a FLD call, data is not moved into the I/O area; rather, the FSAs are moved into the I/O area. Multiple FSAs are allowed on one FLD call. This is specified in the FSA's connector field. Each FSA can operate on either the same or different fields within the target segment.
227
DB Call: FLD
The FSA that you reference in a FLD call contains five fields. The rules for coding these fields are as follows: Field name This field must be 8 bytes long. If the field name you are using is less than 8 bytes, the name must be left-justified and padded on the right with blanks. FSA status code This field is 1 byte. After a FLD call, IMS returns one of these status codes to this area: Successful A B C D E F G H Invalid operation Operand length invalid Invalid callprogram tried to change key field Verify check was unsuccessful Packed decimal or hexadecimal field is invalid Program tried to change an unowned segment Arithmetic overflow Field not found in segment
Op code This 1-byte field contains one of these operators for a change operation: + = To add the operand to the field value To subtract the operand from the field value To set the field value to the value of the operand
For a verify operation, this field must contain one of the following: E G H L M N Verify that the field value and the operand are equal. Verify that the field value is greater than the operand. Verify that the field value is greater than or equal to the operand. Verify that the field value is less than the operand. Verify that the field value is less than or equal to the operand. Verify that the field value is not equal to the operand.
Operand This variable length field contains the value that you want to test the field value against. The data in this field must be the same type as the data in the segment field. (You define this in the DBD.) If the data is hexadecimal, the value in the operand is twice as long as the field in the database. If the data is packed decimal, the operand does not contain leading zeros, so the operand length might be shorter than the actual field. For other types of data, the lengths must be equal. Connector This 1-byte field must contain a blank if this is the last or only FSA, or an asterisk (*) if another FSA follows this one. The format of SSA in FLD calls is the same as the format of SSA in DL/I calls. If no SSA exists, the first segment in the MSDB or DEDB is retrieved.
228
DB Call: FLD
For more information on the FLD call and some examples, see Processing MSDBs and DEDBs on page 171.
GN/GHN Call
The Get Next (GN) call is used to retrieve segments sequentially from the database. The Get Hold Next (GHN) is the hold form for a GN call.
Format
GN db pcb aib i/o area
ssa rsa GHN db pcb aib i/o area
ssa
Call Name For Full-Function: For GSAM: For DEDB: For MSDB: GN/GHN GN GN GN
DB/DC X X X X
DBCTL X X X
DCCTL
DB Batch X
TM Batch
X X
Parameters
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area. This parameter is an output parameter. When you issue one of the Get calls successfully, IMS returns the requested segment to this area. If your program issues any path calls, the I/O area must be long enough
229
DB Call: GN/GHN
to hold the longest path of concatenated segments following a path call. This area always contains left-justified segment data. The I/O area points to the first byte of this area. When you use the GN call with GSAM, the area named by the i/o area parameter contains the record you are retrieving. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA that you supply in the call point to data areas in your program where the SSA have been defined for the call. You can use up to 15 SSAs in the parameter. This parameter is optional for the GN call. rsa Specifies the area in your program where the RSA for the record should be returned. This output parameter is used for GSAM only and is optional. See GSAM Databases on page 85 for more information on RSAs.
Usage: Get Next (GN)

A Get Next (GN) call is a request for a segment, as described by the SSA you supply, that is linked to the call that was issued prior to the GN call. IMS starts its search at the current position. When you use theGN call: v Processing moves forward from current position (unless the call includes the F command code). v IMS uses the current position (that was set by the previous call) as the search starting point. v The segment retrieved is determined by a combination of the next sequential position in the hierarchy and the SSA included in the call. v Be careful when you use GN, because it is possible to use SSAs that force IMS to search to the end of the database without retrieving a segment. This is particularly true with the not equal or greater than relational operators. A GN call retrieves the next segment in the hierarchy that satisfies the SSA that you supplied. Because the segment retrieved by a GN call depends on the current position in the hierarchy, GN is often issued after a GU call. If no position has been established in the hierarchy, GN retrieves the first segment in the database. A GN call retrieves a segment or path of segments by moving forward from the current position in the database. As processing continues, IMS looks for segments at each level to satisfy the call. Example:Sequential retrieval in a hierarchy is always top to bottom and left to right. For example, if you repeatedly issue unqualified GN calls against the hierarchy in Figure 51 on page 231, IMS returns the segment occurrences in the database record in this order: 1. A1 (the root segment) 2. B1 and its dependents (C1,D1,F1,D2,D3,E1,E2, and G1) 3. H1 and its dependents (I1,I2,J1, and K1). If you issue an unqualified GN again after IMS has returned K1, IMS returns the root segment occurrence whose key follows segment A1 in the database. A GN call that is qualified with the segment type can retrieve all the occurrences of a particular segment type in the database.
230
DB Call: GN/GHN
Figure 51. Hierarchic Sequence
Example: If you issue a GN call with qualified SSAs for segments A1 and B1, and an unqualified SSA for segment type D, IMS returns segment D1 the first time you issue the call, segment D2 the second time you issue the call, and segment D3 the third time you issue the call. If you issue the call a fourth time, IMS returns a status code of GE, which means that IMS could not find the segment you requested. You can use unqualified GN calls to retrieve all of the occurrences of a segment in a hierarchy, in their hierarchic sequence, starting at the current position. Each unqualified GN call retrieves the next sequential segment forward from the current position. For example, to answer the processing request: Print out the entire medical database. You would issue an unqualified GN call repeatedly until IMS returned a GB status code, indicating that it had reached the end of the database without being able to satisfy your call. If you issued the GN again after the GB status code, IMS would return the first segment occurrence in the database. Like GU, a GN call can have as many SSAs as the hierarchy has levels. Using fully qualified SSAs with GN calls clearly identifies the hierarchic path and the segment you want, thus making it useful in documenting the call. A GN call with an unqualified SSA retrieves the next occurrence of that segment type by going forward from the current position. GN with a qualified SSA retrieves the next occurrence of the specified segment type that satisfies the SSAs. When you specify a GN that has multiple SSAs, the presence or absence of unqualified SSAs in the call has no effect on the operation unless you use command codes on the unqualified SSA. IMS uses only qualified SSAs plus the last SSA to determine the path and retrieve the segment. Unspecified or unqualified SSAs for higher-level segments in the hierarchy mean that any high-level segment that is the parent of the correct lower-level, specified or qualified segment will satisfy the call. A GN call with a SSA that is qualified on the key of the root can produce different results from a GU with the same SSA, depending on the position in the database and the sequence of keys in the database. If the current position in the database is
231
DB Call: GN/GHN
beyond a segment that would satisfy the SSA, the segment is not retrieved by the GN. GN returns the GE status code if both of these conditions are met: v The value of the key in the SSA has an upper limit that is set, for example, to less-than-or-equal-to the value. v A segment with a key greater than the value in the SSA is found in a sequential search before the specified segment is found. GN returns the GE status code, even though the specified segment exists and would be retrieved by a GU call.
Usage: Get Hold Next (GHN)

Before your program can delete or replace a segment, it must retrieve the segment and indicate to IMS that it is going to change the segment in some way. The program does this by issuing a Get call with a hold before deleting or replacing the segment. When the program has successfully retrieved the segment with a Get Hold call, it can delete the segment or change one or more fields (except the key field) in the segment. The only difference between Get calls with a hold and Get calls without a hold is that the hold calls can be followed by REPL or DLET. The hold status on the retrieved segment is canceled and must be reestablished before you reissue the DLET or REPL call. After issuing a Get Hold call, you can issue more than one REPL or DLET call to the segment if you do not issue intervening calls to the same PCB. If you find out that you do not need to update it after issuing a Get Hold call, you can continue with other processing without releasing the segment. The segment is freed as soon as the current position changeswhen you issue another call to the same PCB that you used for the Get Hold call. In other words, a Get Hold call must precede a REPL or DLET call. However, issuing a Get Hold call does not require you to replace or delete the segment.
Usage: HDAM, PHDAM, or DEDB Database with GN

For database organizations other than HDAM, PHDAM, and DEDB, processing the database sequentially using GN calls returns the root segments in ascending key sequence. However, the order of the root segments for a HDAM, PHDAM, or DEDB database depends on the randomizing routine that is specified for that database. Unless a sequential randomizing routine was specified, the order of the root segments in the database is not in ascending key sequence. For a hierarchic direct access method (HDAM, PHDAM) or a DEDB database, a series of unqualified GN calls or GN calls that are qualified only on the root segment: 1. Returns all the roots from one anchor point 2. Moves to the next anchor point 3. Returns the roots from the anchor point Unless a sequential randomizing routine was specified, the roots on successive anchor points are not in ascending key sequence. One situation to consider for HDAM, PHDAM, and DEDB organizations is when a GN call is qualified on the key field of the root segment with an equal-to operator or an equal-to-or-greaterthan operator. If IMS has an existing position in the database, it checks to ensure that the requested key is equal to or greater than the key of the current root. If it is
232
DB Call: GN/GHN
not, a GE status code is returned. If it is equal to or greater than the current key and is not satisfied using the current position, IMS calls the randomizing routine to determine the anchor point for that key. IMS tries to satisfy the call starting with the first root of the selected anchor.
Restrictions
You can use GN to retrieve the next record of a GSAM database, but GHN is not valid for GSAM.
GNP/GHNP Call
The Get Next in Parent (GNP) call is used to retrieve dependents sequentially. The Get Hold Next in Parent (GHNP) call is the hold form for the GNP call.
Format
GNP GHNP db pcb aib i/o area
ssa
Call Name For Full-Function: For DEDB: For MSDB: GNP/GHNP GNP/GHNP GNP/GHNP
DB/DC X X X
DBCTL X X
DCCTL
DB Batch X
TM Batch
Parameters
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area. This parameter is an output parameter. When you issue the Get call successfully, IMS returns the requested segment to this area. If your program issues any path calls, the I/O area must be long enough to hold
233
DB Call: GNP/GHNP
the longest path of concatenated segments following a path call. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program in which you have defined the SSAs for the call. You can use up to 15 SSAs for this parameter. This parameter is optional for the GNP call.
Usage: Get Next in Parent (GNP)

A GNP call retrieves segments sequentially. The difference between a GN and a GNP is that GNP limits the segments that can satisfy the call to the dependent segments of the established parent. An unqualified GNP retrieves the first dependent segment occurrence under the current parent. If your current position is already on a dependent of the current parent, an unqualified GNP retrieves the next segment occurrence. If you are moving forward in the database, even if you are not retrieving every segment in the database, you can use GNP to restrict the returned segments to only those children of a specific segment.
Linking with Previous DL/I Calls

A GNP call is linked to the previous DL/I calls that were issued by your program in two ways: v Current position: The search for the requested segment starts at the current position established by the preceding GU, GN, or GNP call. v Parentage: The search for the requested segment is limited to the dependents of the lowest-level segment most recently accessed by a GU or GN call. Parentage determines the end of the search and is in effect only following a successful GU or GN call.
Processing with Parentage

You can set parentage in two ways: v By issuing a successful GU or GN call. When you issue a successful GU or GN call, IMS sets parentage at the lowest-level segment returned by the call. Issuing another GU or GN call (but against a different PCB) does not affect the parentage that you set using the first PCB in the previous call. An unsuccessful GU or GN call cancels parentage. v By using the P command code with a GU, GN, or GNP call, you can set parentage at any level.
How DL/I Calls Affect Parentage

A GNP call does not affect parentage unless it includes the P command code. Unless you are using a secondary index, REPL does not affect parentage. If you are using a secondary index, and you replace the indexed segment, parentage is lost. For more information, see How Secondary Indexing Affects Your Program on page 149. A DLET call does not affect parentage unless you delete the established parent. If you do delete the established parent, you must reset parentage before issuing a GNP call.
234
DB Call: GNP/GHNP
ISRT affects parentage only when you insert a segment that is not a dependent of the established parent. In this case, ISRT cancels parentage. If the segment you are inserting is a dependent at some level of the established parent, parentage is unaffected. For example, in Figure 27 on page 100, assume segment B11 is the established parent. Neither of these two ISRT calls would affect parentage:
ISRT A B C A B C D (AKEY (BKEY (AKEY (BKEY (CKEY = A1) = B11) = A1) = B11) = C111)
ISRT
The following ISRT call would cancel parentage, because the F segment is not a direct dependent of B, the established parent:
ISRT A F (AKEY = A1)
You can include one or more SSAs in a GNP call. The SSA can be qualified or unqualified. Without SSAs, a GNP call retrieves the next sequential dependent of the established parent. The advantage of using SSAs with GNP is that they allow you to point IMS to a specific dependent or dependent type of the established parent. A GNP with an unqualified SSA sequentially retrieves the dependent segment occurrences of the segment type you have specified under the established parent. A GNP with a qualified SSA describes to IMS the segment you want retrieved or the segment that is to become part of the hierarchic path to the segment you want retrieved. A qualified GNP describes a unique segment only if it is qualified on a unique key field and not a data field or a non unique key field. A GNP with multiple SSAs defines the hierarchic path to the segment you want. If you specify SSAs for segments at levels above the established parent level, those SSAs must be satisfied by the current position at that level. If they cannot be satisfied using the current position, a GE status code is returned and the existing position remains unchanged. The last SSA must be for a segment that is below the established parent level. If it is not, a GP status code is returned. Multiple unqualified SSAs establish the first occurrence of the specified segment type as part of the path you want. If some SSAs between the parent and the requested segment in a GNP call are missing, they are generated internally as unqualified SSAs. This means that IMS includes the first occurrence of the segment from the missing SSAs as part of the hierarchic path to the segment you have requested.
Usage: Get Hold Next in Parent (GHNP)

Retrieval for the GHNP call is the same as for the GHN call. For more information, see Usage: Get Hold Next (GHN) on page 232.
GU/GHU Call
The Get Unique (GU) call is used to directly retrieve segments and to establish a starting position in the database for sequential processing. The Get Hold Unique (GHU) is the hold form for a GU call.
235
DB Call: GU/GHU
Format
GU db pcb aib i/o area
ssa rsa GHU db pcb aib i/o area
ssa
Call Name For Full-Function: For GSAM: For DEDB: For MSDB: GU/GHU GU GU GU
DB/DC X X X X
DBCTL X X X
DCCTL
DB Batch X
TM Batch
X X
Parameters
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area. This parameter is an output parameter. When you issue one of the Get calls successfully, IMS returns the requested segment to this area. If your program issues any path calls, the I/O area must be long enough to hold the longest path of concatenated segments following a path call. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area. When you use the GU call with GSAM, the area named by the i/o area parameter contains the record you are retrieving. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program where you have defined the SSAs for the call. You can use up to 15 SSAs for the parameter. This parameter is optional for the GU call.
236
DB Call: GU/GHU
rsa Specifies the area in your program that contains the record search argument. This required input parameter is only used for GSAM. See GSAM Databases on page 85 for more information on RSAs.
Usage: Get Unique (GU)

GU is a request for a segment, as described by the SSAs you supply. You use it when you want a specific segment. You can also use it to establish your position in the database. The GU call is the only call that can establish position backward in the database. (The GN and GNP calls, when used with the F command code, can back up in the database, but with limitations. F Command Code on page 205 explains this.) Unlike GN and GNP, a GU call does not move forward in the database automatically. If you issue the same GU call repeatedly, IMS retrieves the same segment each time you issue the call. If you want to retrieve only particular segments, use fully qualified GUs for these segments instead of GNs. If you want to retrieve a specific segment occurrence or obtain a specific position within the database, use GU. If you want to retrieve a specific segment or to set your position in the database to a specific place, you generally use qualified GU calls. A GU call can have the same number of SSAs as the hierarchy has levels, as defined by the DB PCB. If the segment you want is on the fourth level of the hierarchy, you can use four SSAs to retrieve the segment. (No reason would ever exist to use more SSAs than levels in the hierarchy. If your hierarchy has only three levels, you would never need to locate a segment lower than the third level.) The following is additional information for using the GU call with SSAs: v A GU call with an unqualified SSA at the root level attempts to satisfy the call by starting at the beginning of the database. If the SSA at the root level is the only SSA, IMS retrieves the first segment in the database. v A GU call with a qualified SSA can retrieve the segment described in the SSA, regardless of that segment's location relative to current position. v When you issue a GU that mixes qualified and unqualified SSAs at each level, IMS retrieves the first occurrence of the segment type that satisfies the call. v If you leave out an SSA for one of the levels in a GU call that has multiple SSAs, IMS assumes an SSA for that level. The SSA that IMS assumes depends on current position: If IMS has a position established at the missing level, the SSA that IMS uses is derived from that position, as reflected in the DB PCB. If IMS does not have a position established at the missing level, IMS assumes an unqualified SSA for that level. If IMS moves forward from a position established at a higher level, IMS assumes an unqualified SSA for that level. If the SSA for the root level is missing, and IMS has position established on a root, IMS does not move from that root when trying to satisfy the call.
Usage: Get Hold Unique (GHU)

Before your program can delete or replace a segment, it must retrieve the segment and indicate to IMS that it is going to change the segment in some way. The program does this by issuing a Get call with a hold before deleting or replacing
237
DB Call: GU/GHU
the segment. Once the program has successfully retrieved the segment with a Get Hold call, it can delete the segment or change one or more fields (except the key field) in the segment. The only difference between Get calls with a hold and without a hold is that the hold calls can be followed by a REPL or DLET call. The hold status on the retrieved segment is canceled and must be reestablished before you reissue the DLET or REPL call. After issuing a Get Hold call, you can issue more than one REPL or DLET call to the segment if you do not issue intervening calls to the same PCB. If you find out that you do not need to update it after issuing a Get Hold call, you can continue with other processing without releasing the segment. The segment is freed as soon as the current position changeswhen you issue another call to the same PCB you used for the Get Hold call. In other words, a Get Hold call must precede a REPL or DLET call. However, issuing a Get Hold call does not require you to replace or delete the segment.
Restrictions
You can use GU to retrieve the record with the RSA you provide with a GSAM database, but GHU is not valid for GSAM.
ISRT Call
The Insert (ISRT) call is used to load a database and to add one or more segments to the database. You can use ISRT to add a record to the end of a GSAM database or for an alternate PCB that is set up for IAFP processing.
Format
|
ISRT db pcb aib i/o area ssa rsa
|
Call Name For Full-Function: For GSAM: For DEDB: For MSDB: ISRT ISRT ISRT ISRT DB/DC X X X X DBCTL X X X X X DCCTL DB Batch X X X TM Batch
Parameters
238
DB Calls: ISRT
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area. This parameter is an input parameter. When you want to add a new segment to the database, you place the new segment in this area before issuing the ISRT call. This area must be long enough to hold the longest segment that IMS returns to this area. For example, if none of the segments your program retrieves or updates is longer than 48 bytes, your I/O area should be 48 bytes. If your program issues any path calls, the I/O area must be long enough to hold the longest concatenated segment following a path call. The segment data that this area contains is always left-justified. The I/O area points to the first byte of this area. When you use the ISRT call with GSAM, the area named by the i/o area parameter contains the record you want to add. The area must be long enough to hold these records. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program where you have defined the SSAs for the call. You can use up to 15 SSAs on the call. This parameter is required. rsa Specifies the area in your program where the RSA should be returned by DL/I. This output parameter is used for GSAM only and is optional. See GSAM Databases on page 85 for more information on RSAs.
Usage
Your program uses the ISRT call to initially load a database and to add information to an existing one. The call looks the same in either case. However, the way it is used is determined by the processing option in the PCB. This section explains how you use ISRT to add segments to an existing database. ISRT can add new occurrences of an existing segment type to a HIDAM, PHIDAM, HISAM, HDAM, PHDAM, DEDB, or MSDB database. Restriction: New segments cannot be added to a HSAM database unless you reprocess the whole database or add the new segments to the end of the database. Before you issue the ISRT call, build the new segment in the I/O area. The new segment fields must be in the same order and of the same length as defined for the segment. (If field sensitivity is used, they must be in the order defined for the application program's view of the segment.) The DBD defines the fields that a segment contains and the order in which they appear in the segment.
Root Segment Occurrence

If you are adding a root segment occurrence, IMS places it in the correct sequence in the database by using the key you supply in the I/O area. If the segment you
239
DB Calls: ISRT
are inserting is not a root, but you have just inserted its parent, you can insert the child segment by issuing an ISRT call with an unqualified SSA. You must build the new segment in your I/O area before you issue the ISRT call. Also, you use an unqualified SSA when you insert a root. 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. At least one SSA is required in an ISRT call; the last (or only) SSA specifies the segment being inserted. To insert a path of segments, you can set the D command code for the highest-level segment in the path.
Insert Rules
If the segment type you are inserting has a unique key field, the place where IMS adds the new segment occurrence depends on the value of its key field. If the 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 of DBDGEN for this database. Related Reading: For information on performing a DBDGEN, see IMS Version 9: Utilities Reference: Database and Transaction Manager. The rules on the RULES parameter are as follows: FIRST IMS inserts the new segment occurrence before the first existing occurrence of this segment type. If this segment has a nonunique key, IMS inserts the new occurrence before all existing occurrences of that segment that have the same key field. IMS inserts the new occurrence after the last existing occurrence of the segment type. If the segment occurrence has a nonunique key, IMS inserts the new occurrence after all existing occurrences of that segment type that have the same key. IMS assumes you have a position on the segment type from a previous IMS call. IMS places the new occurrence before the segment occurrence that was retrieved or deleted by the last call, which is immediately before current position. If current position is not within the occurrences of the segment type being inserted, IMS adds the new occurrence before all existing occurrences of that segment type. If the segment has a nonunique key and the current position is not within the occurrences of the segment type with equal key value, IMS adds the new occurrence before all existing occurrences that have equal key fields.
LAST
HERE
You can override the insert rule of FIRST with the L command code. You can override the insert rule of HERE with either the F or L command code. This is true for HDAM and PHDAM root segments and for dependent segments in any type of database that have either nonunique keys or no keys at all. An ISRT call must have at least one unqualified SSA for each segment that is added to the database. Unless the ISRT is a path call, the lowest-level SSA specifies the segment being inserted. This SSA must be unqualified. If you use the D command code, all the SSAs below and including the SSA containing the D command code must be unqualified.
240
DB Calls: ISRT
Provide qualified SSAs for higher levels to establish the position of the segment being inserted. Qualified and unqualified SSAs can be used to specify the path to the segment, but the last SSA must be unqualified. This final SSA names the segment type to be inserted. If you supply only one unqualified SSA for the new segment occurrence, you must be sure that current position is at the correct place in the database to insert that segment.
Mix Qualified and Unqualified SSA

You can mix qualified and unqualified SSAs, but the last SSA must be unqualified. If the SSAs are unqualified, IMS satisfies each unqualified SSA with the first occurrence of the segment type, assuming that the path is correct. If you leave out a SSA for one of the levels in an ISRT with multiple SSAs, IMS assumes an SSA for that level. The SSA that IMS assumes depends on current position: v If IMS has a position established at the missing level, the SSA that IMS uses is derived from that position, as reflected in the DB PCB. v If IMS does not have a position established at the missing level, IMS assumes an unqualified SSA for that level. v If IMS moves forward from a position established at a higher level, IMS assumes an unqualified SSA for that level. v If the SSA for the root level is missing, and IMS has position established on a root, IMS does not move from that root when trying to satisfy the call.
Using SSA with the ISRT Call

Using SSA with ISRT is a good way to check for the parent segments of the segment you want to insert. You cannot add a segment unless its parent segments exist in the database. Instead of issuing Get calls for the parents, you can define a fully qualified set of SSAs for all the parents and issue the ISRT call for the new segment. If IMS returns a GE status code, at least one of the parents does not exist. You can then check the segment level number in the DB PCB to find out which parent is missing. If the level number in the DB PCB is 00, IMS did not find any of the segments you specified. A 01 means that IMS found only the root segment; a 02 means that the lowest-level segment that IMS found was at the second level; and so on.
OPEN Call
The OPEN call is used to explicitly open a GSAM database.
Format
OPEN gsam pcb aib i/o area
Call Name For GSAM: OPEN
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
241
DB Call: OPEN
Parameters
gsam pcb Specifies the GSAM PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name of a GSAM PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the kind of data set you are opening. This parameter is an input parameter.
Usage
For more information, see Explicit Open and Close Calls to GSAM on page 161.
POS Call
A qualified Position (POS) call is used to retrieve the location of a specific sequential dependent segment. In addition to location, a qualified POS call using an SSA for a committed segment will return the sequential dependent segment (SDEP) time stamp and the ID of the IMS owner that inserted it. For more information about the qualified POS call, refer to tableLocating the Last Inserted Sequential Dependent Segment on page 183. An unqualified POS points to the logical end of the sequential dependent segment (SDEP) data. By default, an unqualified POS call returns the DMACNXTS value, which is the next SDEP CI to be allocated. Because this CI has not been allocated, its specification without the EXCLUDE keyword will often result in a DFS2664A message from the SDEP utilities.
Format
|
POS db pcb aib keyword i/o area ssa
Call Name For DEDB: POS
DB/DC X
DBCTL X
DCCTL
DB Batch
TM Batch
242
DB Call: POS
Parameters
db pcb Specifies the DB PCB for the DEDB that you are using for this call. This parameter is an input and output parameter. aib Specifies the AIB for the DEDB that you are using for this call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. | | | | keyword Specifies the Keyword for the DEDB that you are using for this call. Returns six words containing field codes to I/O area. Table 49 lists the five keywords and the corresponding output. i/o area Specifies the I/O area in your program that you want to contain the positioning information that is returned by a successful POS call. This parameter is an output parameter. The I/O area should be long enough to contain all the returned entries. IMS returns an entry for each area in the DEDB. | | | | | | | | | | The I/O area returned on POS call contained six words with nine potential fields of data for each return output. Each field is four or eight bytes. When the successful POS is an unqualified call, the I/O area consists of a 2 byte field that contains the length of the data area (LL), followed by 24 bytes of positioning information. The I/O data area will have 24 bytes of positioning information for every area in the DEDB. By selecting one of the five keywords in position zero of the input I/O area, the user specifies the kind of data in the return I/O area. Table 49 lists the five keywords and the data that an unqualified POS call returns based on the keyword you choose for position zero of the input I/O area.
Table 49. Unqualified POS Call: Keywords and Map of the I/O Area Return Output Keyword <null> V5SEGRBA PCSEGRTS PCSEGHWM PCHSEGTS PCLBSGTS byte 2 LL LL LL LL LL LL word 0 word 1 Field 1 Field 1 Field 1 Field 1 Field 1 Field 1 word 2 word 3 Field 2 Field 3 Field 3 Field 3 Field 8 Field 9 word 4 Field 4 word 5 Field 5 <null> Field 6 Field 7 Field 6 Field 6
243
DB Call: POS
| | | Field 1 Area name This 8-byte field contains the ddname from the AREA statement. Field 2 | | | | Sequential dependent next to allocate CI This field is the default if no keyword is specified in position zero of the I/O area. The data returned is the 8-byte cycle count and RBA (CC+RBA) acquired from the global DMACNXTS field. This data represents the next pre-allocated CI as a CI boundary. Field 3 | | | Local sequential dependent next segment The data returned is the 8-byte CC+RBA segment boundary of the most recently committed SDEP segment. This data is specific to only the IMS that executes the POS call. Its scope is for local IMS use only. Field 4 Unused CIs in sequential dependent part This 4-byte field contains the number of unused control intervals in the sequential dependent part. Field 5 Unused CIs in independent overflow part This 4-byte field contains the number of unused control intervals in the independent overflow part. Field 6 | | | | | | | Sequential dependent segment time stamp The data returned is the 8-byte time stamp of the most recently committed SDEP segment across all IMS partners, or for a local SDEP, the time stamp of the first pre-allocated SDEP CI dummy segment of the local IMS. If the area (either local or shared) has not been opened, or a /DBR was performed without any subsequent SDEP segment inserts, the current time is returned. Field 7 | | | Sequential dependent High Water Mark (HWM) This 8-byte field contains the cycle count plus RBA (CC+RBA) of the last pre-allocated SDEP CI which is the High Water Mark (HWM) CI. Field 8 | | | | | | Highest committed SDEP segment The data returned is the 8-byte cycle count plus RBA (CC+RBA) for the most recently committed SDEP segment across all IMS partners, or for a local SDEP, the CC+RBA of the most recently committed SDEP segment of the local IMS. If the area (either local or shared) has not been opened, or a /DBR was performed without any subsequent SDEP segment inserts, the HWM CI is returned. Field 9 | | Logical begin time stamp This 8-byte field contains the logical begin time stamp from the DMACSDEP_LOGICALBEGIN_TS field. ssa Specifies the SSA that you want to use in this call. This parameter is an input
244
DB Call: POS
parameter. The format of SSA in POS calls is the same as the format of SSA in DL/I calls. You can use only one SSA in this parameter. This parameter is optional for the POS call.
Usage
The POS call: v Retrieves the location of a specific sequential dependent segment. v Retrieves the location of last-inserted sequential dependent segment, its time stamp, and the IMS ID. v Retrieves the time stamp of a sequential dependent segment or Logical Begin. v Tells you the amount of unused space within each DEDB area. For example, you can use the information that IMS returns for a POS call to scan or delete the sequential dependent segments for a particular time period. If the area which the POS call specifies is unavailable, the I/O area is unchanged, and the status code FH is returned.
Restrictions
You can only use the POS call with a DEDB.
REPL Call
The Replace (REPL) call is used to change the values of one or more fields in a segment.
Format
REPL db pcb aib i/o area
ssa
Call Name For Full-Function: For DEDB: For MSDB: REPL REPL REPL
DB/DC X X X
DBCTL X X
DCCTL
DB Batch X
TM Batch
Parameters
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
245
DB Call: REPL
AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the area in your program that communicates with IMS. This parameter is an input parameter. When you want to replace an existing segment in the database with a new segment, you first issue a Get Hold call to place the new segment in the I/O area. You can modify the data in the I/O area, and then issue the REPL call to replace the segment in the database. ssa Specifies the SSA, if any, to be used in the call. This parameter is an input parameter. The SSA you supply in the call point to data areas in your program in which you have defined the SSA for the call. You can use up to 15 SSAs in this parameter. This parameter is optional for the REPL call.
Usage
A REPL call must be preceded by one of the three Get Hold calls. After you retrieve the segment, you modify it in the I/O area, and then issue a REPL call to replace it in the database. IMS replaces the segment in the database with the segment you modify in the I/O area. You cannot change the field lengths of the segments in the I/O area before you issue the REPL call. For example, if you do not change one or more segments that are returned on a Get Hold call, or if you change the segment in the I/O area but do not want the change reflected in the database, you can inform IMS not to replace the segment. Specify an unqualified SSA with an N command code for that segment, which tells IMS not to replace the segment. The N command enables you to tell IMS not to replace one or more of the multiple segments that were returned using the D command code. However, you can specify an N command code even if there were no D command codes on the preceding Get Hold call. You should not include a qualified SSA on a REPL call. If you do, you receive an AJ status code. For your program to successfully replace a segment, the segment must have been previously defined as replace-sensitive by PROCOPT=A or PROCOPT=R on the SENSEG statement in the PCB. | | | | | If no fields in the segment were changed by the REPL call, the lock is released when the application moves to another database record. Use the Q command code if you need to preserve the segment for the exclusive use of your program. Related Reading: For more information on the PROCOPT option, see IMS Version 9: Utilities Reference: System. If your program attempts to do a path replace of a segment where it does not have replace sensitivity, and command code N is not specified, the data for the segment in the I/O area for the REPL call must be the same as the segment returned on the preceding Get Hold call. If the data changes in this situation, your program receives the status code, AM, and data does not change as a result of the REPL call.
246
DB Call: RLSE
| | | | | | | | For Full-Function: | For DEDB: | | | | | | | | | | | | | | | | | | | | | | | |
Call Name RLSE RLSE DB/DC X X DBCTL X X DCCTL DB Batch X X TM Batch
RLSE Call
The Release (RLSE) call is used to release all locks held for unmodified data.
Format
RLSE db pcb aib
Parameters
db pcb Specifies the DB PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. The following fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a DB PCB.
Usage
You use the RLSE call in Fast Path (FP) database applications to release all of the unmodified locks that are owned by the application. For Full-Function (FF) database applications, these are the locks held by the DB PCB referenced in the call. If the lock is protecting a resource that has been updated, the lock will not be released. After the RLSE call position in the database is lost.
Restrictions
The RLSE call has to be issued using a DB PCB. The PCB cannot be an I/O PCB or an MSDB PCB.
247
248
Chapter 12. DL/I Calls for System Services

| | This chapter describes the calls you can use to obtain IMS DB system services for use in each type of application program and the parameters of each call. Each call description contains: v A syntax diagram v Definitions for parameters that are available to the call v Details on how to use the call in your application program v Restrictions on call usage, where applicable Each parameter is described as an input parameter or output parameter. Input refers to input to IMS from the application program. Output refers to output from IMS to the application program. Syntax diagrams for these calls begin with the function parameter. The call interface (xxxTDLI) and parmcount (if it is required) are not included in the syntax diagrams. | The following topics provide additional information: v v v v v v v v v v v v v v v System Service Call Summary on page 250 APSB Call on page 252 CHKP (Basic) Call on page 253 CHKP (Symbolic) Call on page 254 DPSB Call on page 255 GMSG Call on page 256 GSCD Call on page 258 ICMD Call on page 259 INIT Call on page 261 INQY Call on page 266 LOG Call on page 276 PCB Call (CICS Online Programs Only) on page 277 RCMD Call on page 278 ROLB Call on page 280 ROLL Call on page 280
v ROLS Call on page 281 v SETS/SETU Call on page 282 v v v v v SNAP Call on page 284 STAT Call on page 286 SYNC Call on page 288 TERM Call (CICS Online Programs Only) on page 289 XRST Call on page 290
Related Reading: For specific information about coding your program in assembler language, C language, COBOL, Pascal, and PL/I, see Chapter 3, Defining Application Program Elements, on page 53 for the complete structure. For information on calls that apply to TM, see IMS Version 9: Application
249
DL/I Calls for System Services

Programming: Transaction Manager. Calls within the section are in alphabetic order. For information on DL/I calls used for transaction management and EXEC DLI commands used in CICS, see IMS Version 9: Application Programming: Transaction Manager and IMS Version 9: Application Programming: EXEC DLI Commands for CICS and IMS.
System Service Call Summary

Table 50 summarizes which system service calls you can use in each type of IMS DB application program and the parameters for each call. Optional parameters are enclosed in brackets ([ ]). Exception: Language-dependent parameters are not shown here. For more information on language-dependent application elements, see Chapter 3, Defining Application Program Elements, on page 53.
Table 50. Summary of System Service Calls Function Code APSB Meaning Allocate PSB Use/Options Allocates a PSB for an ODBA application Prepares for recovery Prepares for recovery. Specifies up to seven program areas to be saved Parameters aib Valid for DB/DC, IMS DB
CHKP (Basic) CHKP (Symbolic)
Basic checkpoint Symbolic checkpoint
function, i/o pcb or aib, i/o area function, i/o pcb or aib, i/o area len, i/o area[, area len, area]
DB batch, TM batch, BMP, MPP, IFP DB batch, TM batch, BMP
GMSG
Get Message
Retrieves a message function, aib, i/o area from the AO exit routine. Waits for an AOI message when none is available Gets address of system contents directory Issues an IMS command and retrieves the first command response segment function, db pcb, i/o pcb or aib, i/o area function, aib, i/o area
DB/DC and DCCTL (BMP, MPP, IFP), DB/DC and DBCTL (DRA thread), DBCTL (BMP non-message driven), ODBA DB Batch, TM Batch
GSCD1
Get System Contents Directory Issue Command
ICMD
DB/DC and DCCTL (BMP, MPP, IFP), DB/DC and DBCTL (DRA thread), DBCTL (BMP non-message driven), ODBA DB batch, TM batch, BMP, MPP, IFP, DBCTL, ODBA
INIT
Initialize application
Receives data function, i/o pcb or aib, i/o area availability and deadlock occurrence status codes and checks each PCB database for data availability
250

Table 50. Summary of System Service Calls (continued) Function Code INQY Meaning Inquiry Use/Options Returns information and status codes about I/O or alternate PCB destination type, location, and session status Writes a message to the system log Specifies and schedules another PSB Parameters function, aib, i/o area, AIBFUNC=FIND| DBQUERY| ENVIRON Valid for DB batch, TM batch, BMP, MPP, IFP, ODBA
LOG
Log
function, i/o pcb or aib, i/o area function, psb name, uibptr, [,sysserve]
DB batch, TM batch, BMP, MPP, IFP, DBCTL, ODBA CICS (DBCTL or DB/DC) DB/DC and DCCTL (BMP, MPP, IFP), DB/DC and DBCTL (DRA thread), DBCTL (BMP non-message driven), ODBA DB batch, TM batch, BMP, MPP, IFP
PCB
Program Communication Block Retrieve Command
RCMD
Retrieves the second function, aib, i/o area and subsequent command response segments resulting from an ICMD call Eliminates database function, i/o pcb or updates and returns aib, i/o area last message to i/o area Eliminates database updates Issues call using name of DB PCB or i/o PCB and backs out database changes to SETS points function function, db pcb, i/o pcb or aib, i/o area, token
ROLB
Roll back
ROLL ROLS
Roll Roll back to SETS
DB batch, TM batch, BMP, MPP, IFP DB batch, TM batch, BMP, MPP, IFP, DBCTL, ODBA
SETS/SETU
Set a backout point
Cancels all existing function, i/o pcb or backout points and aib, i/o area, token establishes as many as nine intermediate backout points Collects diagnostic information; choose SNAP options function, db pcb or aib, i/o area function, db pcb or aib, i/o area, stat function function, i/o pcb or aib
DB batch, TM batch, BMP, MPP, IFP, DBCTL, ODBA
SNAP2
DB batch, BMP, MPP, IFP, CICS (DBCTL or DB/DC), ODBA DB batch, BMP, MPP, IFP, DBCTL, ODBA
STAT3
Statistics
Retrieves IMS system statistics; choose type and format Releases locked resources and requests commit-point processing Releases a PSB so another can be scheduled to commit database changes
SYNC
Synchronization
BMP
TERM
Terminate
function
CICS (DBCTL or DB/DC)
251

Table 50. Summary of System Service Calls (continued) Function Code XRST Meaning Extended restart Use/Options Parameters Valid for DB batch, TM batch, BMP
Specifies up to function, i/o pcb or seven areas to be aib, i/o area len, i/o saved. Works with area[, area len, area] symbolic checkpoint to restart application program
Note: 1. GSCD is a Product-sensitive programming interface. 2. SNAP is a Product-sensitive programming interface. 3. STAT is a Product-sensitive programming interface.
APSB Call
The Allocate PSB (APSB) calls are used to allocate a PSB for an ODBA application.
Format
APSB aib
Call Name APSB
DB/DC X
IMS DB X
DCCTL
DB Batch
TM Batch
Parameters
aib Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PSB name. AIBRSNM2 This is the 4-character ID of ODBA startup table representing the target IMS of the APSB.
Usage
The ODBA application must load or be link edited with the ODBA application interface AERTDLI. The APSB call must be issued prior to any DLI calls. The APSB call uses the AIB to allocate a PSB for ODBA application programs.
252
System Service Call: APSB

RRS/MVS must be active at the time of the APSB call. If RRS/MVS is not active, the APSB call will fail and the application will receive:
AIBRETRN = X'00000108' AIBREASN = X'00000548'
CHKP (Basic) Call

A basic Checkpoint (CHKP) call is used for recovery purposes. The ODBA interface does not support this call.
Format
CHKP i/o pcb aib i/o area
Call Name CHKP
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. A basic CHKP call must refer to the I/O PCB. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies your program's I/O area that contains the 8-byte checkpoint ID. This parameter is an input parameter. If the program is an MPP or a message-driven BMP, the CHKP call implicitly returns the next input message to this I/O area. Therefore, the area must be large enough to hold the longest returned message.
Usage
Basic CHKP commits the changes your program has made to the database and establishes places in your program from which you can restart your program, if it terminates abnormally.
253
System Service Call: CHKP (Symbolic) Call
CHKP (Symbolic) Call

A symbolic Checkpoint (CHKP) call is used for recovery purposes. If you use the symbolic Checkpoint call in your program, you also must use the XRST call. The ODBA interface does not support this call.
Format
CHKP i/o pcb aib i/o area length i/o area
area length area
Call Name CHKP
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. This parameter is an input and output parameter. A symbolic CHKP call must refer to the I/O PCB. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area length This parameter is no longer used by IMS. For compatibility reasons, this parameter must be included in the call, and it must contain a valid address. You can get a valid address by specifying the name of any area in your program. i/o area Specifies the I/O area in your program that contains the 8-byte ID for this checkpoint. This parameter is an input parameter. If the program is a message-driven BMP, the CHKP call implicitly returns the next input message into this I/O area. Therefore, the area must be large enough to hold the longest returned message. area length Specifies a 4-byte field in your program that contains the length (in binary) of the area to checkpoint. This parameter is an input parameter. You can specify up to seven area lengths. For each area length, you must also specify the area
254

parameter. All seven area parameters (and corresponding length parameters) are optional. When you restart the program, IMS restores only the areas you specified in the CHKP call. area Specifies the area in your program that you want IMS to checkpoint. This parameter is an input parameter. You can specify up to seven areas. Each area specified must be preceded by an area length parameter.
Usage
The symbolic CHKP call commits the changes your program has made to the database and establishes places in your program from which you can restart your program, if it terminates abnormally. In addition, the CHKP call: v Works with the Extended Restart (XRST) call to restart your program if it terminates abnormally v Enables you to save as many as seven data areas in your program, which are restored when your program is restarted An XRST call is required before a CHKP call to indicate to IMS that symbolic check points are being taken. The XRST call must specify a checkpoint ID of blanks. For more information, see XRST Call on page 290.
Restrictions
The Symbolic CHKP call is allowed only from batch and BMP applications.
DPSB Call
The DPSB call is used to deallocate IMS DB resources.
Format
DPSB aib
Call Name DPSB
DB/DC X
IMS DB X
DCCTL
DB Batch
TM Batch
Parameters
aib Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PSB name.
255

AIBSFUNC Subfunction code. This field must contain one of the 8-byte subfunction codes as follows:
bbbbbbbb (Null) PREPbbbb
Usage
The DPSB call is used by an application running in a z/OS application region to deallocate a PSB. If the PREP subfunction is not used, the application must activate sync-point processing prior to issuing the DPSB. Use the RRS/MVS SRRCMIT/ATRCMIT calls to activate the sync-point process. Refer to MVS Programming: Resource Recovery for more information on these calls. If the DPSB is issued before changes are committed, and, or locks released, the application will receive:
AIBRETRN = X'00000104' AIBREASN = X'00000490'
The thread will not be terminated. The application should issue a SRRCMIT or SRRBACK call, and retry the DPSB. The PREP sub-function allows the application to issue the DPSB prior to activating the sync-point process. The sync-point activation can occur at a later time, but still must be issued.
GMSG Call
A Get Message (GMSG) call is used in an automated operator (AO) application program to retrieve a message from the AO exit routine DFSAOE00.
Format
GMSG aib i/o area
Parameters
aib Specifies the application interface block (AIB) to be used for this call. This parameter is an input and output parameter. You must initialize the following fields in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the length of the AIB the application actually obtained. AIBSFUNC Subfunction code. This field must contain one of these 8-byte subfunction codes: 8-blanks (null) When coded with an AOI token in the AIBRSNM1 field, indicates IMS is to return when no AOI message is available for the application program.
256
System Service Call: GMSG

WAITAOI When coded with an AOI token in the AIBRSNM1 field, WAITAOI indicates IMS is to wait for an AOI message when none is currently available for the application program. This subfunction value is invalid if an AOI token is not coded in AIBRSNM1. In this case, error return and reason codes are returned in the AIB. The value WAITAOI must be left justified and padded on the right with a blank character. AIBRSNM1 Resource name. This field must contain the AOI token or blanks. The AOI token identifies the message the AO application is to retrieve. The token is supplied for the first segment of a message. If the message is a multisegment message, set this field to blanks to retrieve the second through the last segment. AIBRSNM1 is an 8-byte alphanumeric left-justified field that is padded on the right with blanks. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. This field is not changed by IMS. AIBOAUSE Length of the data returned in the I/O area. This parameter is an output parameter. When partial data is returned because the I/O area is not large enough, AIBOAUSE contains the length required to receive all of the data, and AIBOALEN contains the actual length of the data. i/o area Specifies the I/O area to use for this call. This parameter is an output parameter. The I/O area should be large enough to hold the largest segment that is passed from IMS to the AO application program. If the I/O area is not large enough to contain all the data, IMS returns partial data.
Usage
GMSG is used in an AO application program to retrieve a message associated with an AOI token. The AO application program must pass an 8-byte AOI token to IMS in order to retrieve the first segment of the message. IMS uses the AOI token to associate messages from AO exit routine DFSAOE00 with the GMSG call from an AO application program. IMS returns to the application program only those messages associated with the AOI token. By using different AOI tokens, DFSAOE00 can direct messages to different AO application programs. Note that your installation defines the AOI token. Related Reading: For more information on the AOI exits, see IMS Version 9: Customization Guide. To retrieve the second through the last segments of a multisegment message, issue GMSG calls with no token specified (set the token to blanks). If you want to retrieve all segments of a message, you must issue GMSG calls until all segments are retrieved. IMS discards all nonretrieved segments of a multisegment message when a new GMSG call that specifies an AOI token is issued. Your AO application program can specify a wait on the GMSG call. If no messages are currently available for the associated AOI token, your AO application program waits until a message is available. The decision to wait is specified by the AO
257
System Service Call: GMSG

application program, unlike a WFI transaction where the wait is specified in the transaction definition. The wait is done on a call basis; that is, within a single application program some GMSG calls can specify waits, while others do not. Table 51 shows, by IMS environment, the types of AO application programs that can issue GMSG. GMSG is also supported from a CPI-C driven program.
Table 51. GMSG Support by Application Region Type IMS Environment Application Region Type DRA thread BMP (nonmessage-driven) BMP (message-driven) MPP IFP DBCTL Yes Yes N/A N/A N/A DB/DC Yes Yes Yes Yes Yes DCCTL N/A Yes Yes Yes Yes
Restrictions
A CPI-C driven program must issue an allocate PSB (APSB) call before issuing GMSG.
GSCD Call
This section contains product-sensitive programming interface information. A Get System Contents Directory (GSCD) call retrieves the address of the IMS system contents directory for batch programs. The ODBA interface does not support this call.
Format
GSCD db pcb i/o pcb aib i/o area
Call Name GSCD
DB/DC
DBCTL
DCCTL
DB Batch X
TM Batch X
Parameters
db pcb Specifies the DB PCB for the call. This parameter is an input and output parameter. i/o pcb Specifies the I/O PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. The these fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
258
System Service Call: GSCD

AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB (if the I/O PCB is used), or the name of a DB PCB (if a DB PCB is used). AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area, which must be 8 bytes long. IMS places the address of the system contents directory (SCD) in the first 4 bytes and the address of the program specification table (PST) in the second 4 bytes. This parameter is an output parameter.
Usage
IMS does not return a status code to a program after it issues a successful GSCD call. The status code from the previous call that used the same PCB remains unchanged in the PCB. For more information on GSCD, see IMS Version 9: Application Programming: Design Guide.
Restrictions
The GSCD call can be issued only from batch application programs.
ICMD Call
An Issue Command (ICMD) call enables an automated operator (AO) application program to issue an IMS command and retrieve the first command response segment.
Format
ICMD aib i/o area
Parameters
aib Specifies the application interface block (AIB) for this call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. This field is not changed by IMS.
259
System Service Call: ICMD

AIBOAUSE Length of data returned in the I/O area. This parameter is an output parameter. Your program must check this field to determine whether the ICMD call returned data to the I/O area. When the only response to the command is a DFS058 message indicating that the command is either in progress or complete, the response is not returned. When partial data is returned because the I/O area is not large enough, AIBOAUSE contains the length required to receive all of the data, and AIBOALEN contains the actual length of the data. i/o area Specifies the I/O area to use for this call. This parameter is an input and output parameter. The I/O area should be large enough to hold the largest command that is passed from the AO application program to IMS, or the largest command response segment that is passed from IMS to the AO application program. If the I/O area is not large enough to contain all the data, IMS returns partial data.
Usage
ICMD enables an AO application to issue an IMS command and retrieve the first command response segment. When using ICMD, put the IMS command that is to be issued in your application program's I/O area. After IMS has processed the command, it returns the first segment of the response message to your AO application program's I/O area. To retrieve subsequent segments (one segment at a time) use the RCMD call. Some IMS commands that complete successfully result in a DFS058 message indicating that the command is complete. Some IMS commands that are processed asynchronously result in a DFS058 message indicating that the command is in progress. For a command entered on an ICMD call, neither DFS058 message is returned to the AO application program. In this case, the AIBOAUSE field is set to 0 to indicate that no segment was returned. So, your AO application program must check the AIBOAUSE field along with the return and reason codes to determine if a response was returned. Related Reading: For more information on the AOI exits, see IMS Version 9: Customization Guide. Table 52 shows, by IMS environment, the types of AO application programs that can issue ICMD. ICMD is also supported from a CPI-C driven program.
Table 52. ICMD Support by Application Region Type IMS Environment Application Region Type DRA thread BMP (nonmessage-driven) BMP (message-driven) MPP IFP DBCTL Yes Yes N/A N/A N/A DB/DC Yes Yes Yes Yes Yes DCCTL N/A Yes Yes Yes Yes
260
System Service Call: ICMD

See IMS Version 9: Command Reference for a list of commands that can be issued using the ICMD call.
Restrictions
Before issuing ICMD, a CPI-C driven program must issue an allocate PSB (APSB) call.
INIT Call
The Initialize (INIT) call allows an application to receive status codes regarding deadlock occurrences and data availability (by checking each DB PCB).
Format
INIT i/o pcb aib i/o area
Call Name INIT
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. INIT must refer to the I/O PCB. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area in your program that contains the character string or strings indicating which INIT functions are requested. This parameter is an input parameter. INIT function character strings include DB QUERY, STATUS GROUPA, and STATUS GROUPB.
Usage
You can use the call in any application program, including IMS batch in a sharing environment. Specify the function in your application program with a character string in the I/O area.
261
System Service Call: INIT

Example: Use the format LLZZ Character-String, where LL is the length of the character string including the length of the LLZZ portion; ZZ must be binary 0. For PL/I, you must define the LL field as a fullword; the value is the length of the character string including the length of the LLZZ portion, minus 2. If the I/O area is invalid, an AJ status code is returned. Table 55 on page 263 and Table 56 on page 263 contain sample I/O areas for INIT when it is used with assembler language, COBOL, C language, Pascal, and PL/I.
Determining Database Availability: INIT DBQUERY

When the INIT call is issued with the DBQUERY character string in the I/O area, the application program can obtain information regarding the availability of data for each PCB. Table 53 contains a sample I/O area for the INIT call with DBQUERY for assembler language, COBOL, C language, and Pascal.
Table 53. INIT DBQUERY: Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI L 00 L 0B Z 00 Z 00 Character String DBQUERY
Note: The LL value of X'0B' is a hexadecimal representation of decimal 11. ZZ fields are binary.
Table 54 contains a sample I/O area for the INIT call with DBQUERY for PL/I.
Table 54. INIT DBQUERY: I/O Area Example for PLITDLI L 00 L 00 L 00 L 0B Z 00 Z 00 Character String DBQUERY
Note: The LL value of X'0B' is a hexadecimal representation of decimal 11. ZZ fields are binary.
LL or LLLL
A 2-byte field that contains the length of the character string, plus two bytes for LL. For the PLITDLI interface, use the 4-byte field LLLL. When you use the AIB interface (AIBTDLI), PL/I programs require only a 2-byte field. A 2-byte field of binary zeros.
ZZ
One of the following status codes is returned for each database PCB: NA At least one of the databases that can be accessed using this PCB is not available. A call made using this PCB probably results in a BA or BB status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not. An exception is when the database is not available because dynamic allocation failed. In this case, a call results in an AI (unable to open) status code. In a DCCTL environment, the status code is always NA. NU At least one of the databases that can be updated using this PCB is unavailable for update. An ISRT, DLET, or REPL call using this PCB might result in a BA status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not. The database that caused the NU status code might be required only for delete processing. In that case, DLET calls fail, but ISRT and REPL calls succeed.
262

The data that can be accessed with this PCB can be used for all functions that the PCB allows. DEDBs and MSDBs always have the status code. In addition to data availability status, the name of the database organization of the root segment is returned in the segment name field of the PCB. The segment name field contains one of the following database organizations: DEDB, MSDB, GSAM, HDAM, PHDAM, HIDAM, PHIDAM, HISAM, HSAM, INDEX, SHSAM, or SHISAM. For a DCCTL environment, the database organization is UNKNOWN. Important: If you are working with a High Availability Large Database (HALDB), you need to be aware that the feedback on data availability at PSB schedule time only shows the availability of the HALDB master, not of the HALDB partitions. However, the error settings for data unavailability of a HALDB partition are the same as those of a non-HALDB database, namely status code 'BA' or pseudo abend U3303. Related Reading: For more information on HALDB, see High Availability Large Databases (HALDBs) on page 9.
Automatic INIT DBQUERY

When the program is initially scheduled, the status code in the database PCBs is initialized as if the INIT DBQUERY call were issued. The application program can therefore determine database availability without issuing the INIT call. For a DCCTL environment, the status code is NA.
Performance Considerations for the INIT Call (IMS Online Only)

For performance reasons, the INIT call should not be issued before the first GU call to the I/O PCB. If the INIT call is issued first, the GU call is not processed as efficiently.
Enabling Data Availability Status Codes: INIT STATUS GROUPA

Table 55 contains a sample I/O area for the INIT call for assembler language, COBOL, C language, and Pascal.
Table 55. INIT I/O Area Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI L 00 L 11 Z 00 Z 00 Character String STATUS GROUPA
Note: The LL value of X'11' is a hexadecimal representation of decimal 17. ZZ fields are binary.
Table 56 contains a sample I/O area for the INIT call for PL/I.
Table 56. INIT I/O Area Examples for PLITDLI L 00 L 00 L 00 L 11 Z 00 Z 00 Character String STATUS GROUPA
263

LL or LLLL ZZ LL is a halfword-length field. For non-PLITDLI calls, LLLL is a fullword-length field for PLITDLI. A 2-byte field of binary zeros.
The value for LLZZ data or LLLLZZ data is always 4 bytes (for LLZZ or LLLLZZ), plus data length. Recommendation: You should be familiar with data availability. Related Reading: For more information about data availability, see IMS Version 9: Application Programming: Design Guide. When the INIT call is issued with the character string STATUS GROUPA in the I/O area, the application program informs IMS that it is prepared to accept status codes regarding data unavailability. IMS then returns a status code rather than a resultant pseudoabend if a subsequent call requires access to unavailable data. The status codes that are returned when IMS encounters unavailable data are BA and BB. Status codes BA and BB both indicate that the call could not be completed because it required access to data that was not available. DEDBs can receive the BA or BB status code. In response to status code BA, the system backs out only the updates that were done for the current call before it encountered the unavailable data. If changes have been made by a previous call, the application must decide to commit or not commit to these changes. The state of the database is left as it was before the failing call was issued. If the call was a REPL or DLET call, the PCB position is unchanged. If the call is a Get type or ISRT call, the PCB position is unpredictable. In response to status code BB, the system backs out all database updates that the program made since the last commit point and cancels all nonexpress messages that were sent since the last commit point. The PCB position for all PCBs is at the start of the database.
Enabling Deadlock Occurrence Status Codes: INIT STATUS GROUPB

Table 57 contains a sample I/O area for the INIT call for assembler language, COBOL, C language, and Pascal.
Table 57. INIT I/O Area Examples for ASMTDLI, CBLTDLI, CTDLI, and PASTDLI L 00 L 11 Z 00 Z 00 Character String STATUS GROUPB
Table 58 contains a sample I/O area for the INIT call for PL/I.
Table 58. INIT I/O Area Examples for PLITDLI L 00 L 00 L 00 L 11 Z 00 Z 00 Character String STATUS GROUPB
264

LL or LLLL ZZ LL is a halfword-length field. For non-PLITDLI calls, LLLL is a fullword-length field for PLITDLI. A 2-byte field of binary zeros.
The value for LLZZ data or LLLLZZ data is always four bytes (for LLZZ or LLLLZZ), plus data length. When the INIT call is issued with the character string STATUS GROUPB in the I/O area, the application program informs IMS that it is prepared to accept status codes regarding data unavailability and deadlock occurrences. The status codes for data unavailability are BA and BB, as described under Enabling Data Availability Status Codes: INIT STATUS GROUPA on page 263. When a deadlock occurs in batch and the INITSTATUS GROUPB call has been issued, the following occurs: v If no changes were made to the database, the BC status code is returned. v If updates were made to the database, and if a datalog exists and BKO=YES is specified, the BC status code is returned. v If changes were made to the database, and a disklog does not exist or BKO=YES is not specified, a 777 pseudoabend occurs. When the application program encounters a deadlock occurrence, IMS: v Backs out all database resources (with the exception of GSAM and DB2) to the last commit point. Although GSAM PCBs can be defined for pure batch or BMP environments, GSAM changes are not backed out. Database resources are backed out for DB2 only when IMS is the sync-point coordinator. When you use INIT STATUS GROUPB in a pure batch environment, you must specify the DISKLOG and BACKOUT options. v Backs out all output messages to the last commit point. v Requeues all input messages as follows: Environment MPP and BMP Action All input messages are returned to the message queue. The application program no longer controls its input messages. All input messages are returned to IMS Fast Path (IFP) balancing group queues (BALGRP), making them available to any other IFP region on the BALGRP. The IFP that is involved in the deadlock receives the next transaction or message that is available on the BALGRP.
IFP
Action is limited to resources that are managed by DBCTL, for example, database updates. v Returns a BC status code to the program in the database PCB. DBCTL
Restrictions
For function shipping in the CICS environment, the local and remote CICS must both be DBCTL. You should be familiar with deadlock occurrences as described in IMS Version 9: Administration Guide: System.
265
System Service Call: INQY
INQY Call
The Inquiry (INQY) call is used to request information regarding execution environment, destination type and status, and session status. INQY is valid only when using the AIB interface.
Format
INQY aib i/o area
Call Name INQY
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
aib Specifies the address of the application interface block (DFSAIB) for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBSFUNC Subfunction code. This field must contain one of the 8-byte subfunction codes as follows: v v v v v DBQUERY ENVIRON FIND LERUNOPT PROGRAM Not supported with the ODBA interface.
AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of any named PCB in the PSB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. This field is not changed by IMS. i/o area Specifies the data output area to use with the call. This parameter is an output parameter. An I/O area is required for INQY subfunctions ENVIRON and PROGRAM . It is not required for subfunctions DBQUERY and FIND .
Usage
The INQY call operates in both batch and online IMS environments. IMS application programs can use the INQY call to request information regarding the output destination, the session status, the current execution environment, the availability of databases, and the PCB address, which is based on the PCB name. You must use
266

the AIB when issuing an INQY call. Before you can issue an INQY call, initialize the fields of the AIB. For more information on initializing AIBs, see The AIBTDLI Interface on page 85. When you use the INQY call, specify an 8-byte subfunction code, which is passed in the AIB. The INQY subfunction determines the information that the application program receives. For a summary of PCB type and I/O area use for each subfunction, see Table 61 on page 275. The INQY call returns information to the caller's I/O area. The length of the data that is returned from the INQY call is passed back to the application program in the AIB field, AIBOAUSE. You specify the size of the I/O area in the AIB field, AIBOALEN. The INQY call returns only as much data as the area can hold in one call. If the area is not large enough for all the information, an AG status code is returned, and partial data is returned in the I/O area. In this case, the AIB field AIBOALEN contains the actual length of the data returned to the I/O area, and the AIBOAUSE field contains the output area length that would be required to receive all the data.
Querying Data Availability: INQY DBQUERY

| | | | | | | | | When the INQY call is issued with the DBQUERY subfunction, the application program obtains information regarding the data for each PCB. The only valid PCB name that can be passed in AIBRSNM1 is IOPCB . The INQY DBQUERY call is similar to the INITDBQUERY call. The INQY DBQUERY call does not return information in the I/O area, but like the INIT DBQUERY call, it updates status codes in the database PCBs. The application program is not made aware of the status of each PCB until an INQY FIND call is issued. To retrieve the status for a database, you must pass the DB PCB for that database in the INQY FIND call. In addition to the INIT DBQUERY status codes, the INQY DBQUERY call returns these status codes in the I/O PCB: The call is successful and all databases are available. BJ None of the databases in the PSB are available, or no PCBs exist in the PSB. All database PCBs (excluding GSAM) contain an NA status code as the result of processing the INQY DBQUERY call. At least one of the databases in the PSB is not available or availability is limited. At least one database PCB contains an NA or NU status code as the result of processing the INQY DBQUERY call.
BK
| | | | | | | | | | |
The INQY FIND call returns the following status for each PCB: NA At least one of the databases that can be accessed using this PCB is not available. A call that is made using this PCB probably results in a BA or BB status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if the call has not been issued. An exception is when the database is not available because dynamic allocation failed. In this case, a call results in an AI (unable to open) status code. In a DCCTL environment, the status code is always NA. NU At least one of the databases that can be updated using this PCB is unavailable for update. An ISRT, DLET, or REPL call using this PCB might
267

| | | | | | | result in a BA status code if the INIT STATUS GROUPA call has been issued, or in a DFS3303I message and 3303 pseudoabend if it has not been issued. The database that caused the NU status code might be required only for delete processing. In that case, DLET calls fail, but ISRT and REPL calls succeed. The data that can be accessed with this PCB can be used for all functions the PCB allows. DEDBs and MSDBs always have the status code.
Querying the Environment: INQY ENVIRON

When the INQY call is issued with the ENVIRON subfunction, the application program obtains information regarding the current execution environment. The only valid PCB name that can be passed in AIBRSNM1 is IOPCB . This includes the IMS identifier, release, region, and region type. The INQY ENVIRON call returns character-string data. The output is left justified and padded with blanks on the right. Recommendation: To receive the following data and to account for expansion, define the I/O area length to be larger than 152 bytes. If you define the I/O area length to be exactly 152 bytes and the I/O area is expanded in future releases, you will receive an AG status code. 100 bytes INQY ENVIRON data 2 bytes Length field for Recovery Token section (18 bytes) 16 bytes Recovery Token 2 bytes Length field for APARM section (maximum of 34 bytes) 32 bytes APARM data ___________________________________________ 152 bytes Total I/O area length Table 59 lists the output that is returned from the INQY ENVIRON call. Included with the information returned is the outputs byte length, the actual value, and an explanation.
Table 59. INQY ENVIRON Data Output Information Returned IMS Identifier IMS Release Level IMS Control Region Type Length in Bytes 8 4 8 BATCH DB TM DB/DC IMS Application Region Type 8 BATCH BMP DRA IFP MPP Actual Value Explanation Provides the identifier from the execution parameters. Provides the release level for IMS. For example, X'00000410'. Indicates that an IMS batch region is active. Indicates that only the IMS Database Manager is active. (DBCTL system) Indicates that only the IMS Transaction Manager is active. (DCCTL system) Indicates that both the IMS Database and Transaction managers are active. (DBDC system) Indicates that the IMS Batch region is active. Indicates that the Batch Message Processing region is active. Indicates that the Database Resource Adapter Thread region is active. Indicates that the IMS Fast Path region is active. Indicates that the Message Processing region is active.
268

Table 59. INQY ENVIRON Data Output (continued) Information Returned Region Identifier Application Program Name PSB Name (currently allocated) Transaction Name
1
Length in Bytes 4 8 8 8
Actual Value
Explanation Provides the region identifier. For example, X'00000001'. Provides the name of the application program being run. Provides the name of the PSB currently allocated. Provides the name of the transaction. Indicates that no associated transaction exists.
User Identifier
Provides the user ID. Indicates that the user ID is unavailable.
Group Name
Provides the group name. Indicates that the group name is unavailable.
Status Group Indicator
A B
Indicates an INIT STATUS GROUPA call is issued. Indicates an INIT STATUS GROUPB call is issued. Indicates that a status group is not initialized.
Address of Recovery Token Address of the Application Parameter String 2
4 4 0
Provides the address of the LL field, followed by the recovery token. Provides the address of the LL field, followed by the application program parameter string. Indicates that the APARM= parameter is not coded in the execution parameters of the dependent region JCL. Indicates IMS is not using Shared Queues. SHRQ Indicates IMS is using Shared Queues. Userid of dependent address space. The Userid Indicator field has one of four possible values. This value indicates the contents of the userid field. U L P O Indicates the users identification from the source terminal during sign-on. Indicates the LTERM name of the source terminal in sign-on is not active. Indicates the PSBNAME of the source BMP or transaction. Indicates some other name. Reserved for IMS. Indicates IMS has not expressed interest in the UR with RRS. Therefore, the application should refrain from performing any work that causes RRS to become the syncpoint manager for the UR because IMS will not be involved in the commit scope. For example, the application should not issue any outbound protected conversations. RRS Indicates IMS has expressed interest in the UR with RRS. Therefore, IMS will be involved in the commit scope if RRS is the syncpoint manager for the UR.
Shared Queues Indicator
Userid of Address Space Userid Indicator
8 1
1 RRS Indicator 1 1 1 1 1
269

Table 59. INQY ENVIRON Data Output (continued) Information Returned Notes: 1. The user ID is derived from the PSTUSID field of the PST that represents the region making the INQY ENVIRON call. The PSTUSID field is one of the following: v For message-driven BMP regions that have not completed successful GU calls to the IMS message queue and for non-message-driven BMP regions, the PSTUSID field is derived from the name of the PSB that is currently scheduled into the BMP region. v For message-driven BMP regions that have completed a successful GU call and for any MPP region, the PSTUSID field is derived which is usually the input terminal's RACF ID. If the terminal has not signed on to RACF, the ID is the input terminal's LTERM. Length in Bytes Actual Value Explanation
| 2. The pointer is an address that identifies a length field (LL) which contains the length of the recovery token or application program parameter string in binary, including the two bytes required for LL. Use this pointer to set | up addressability of the AIB between releases in a batch program. | | | | | | | | | |
Querying the input information: INQY MSGINFO

To obtain information regarding the current input message, use the INQY call with the MSGINFO subfunction. The only valid PCB name that can be passed in the AIBRSNM1 field is IOPCBbbb. The output returns the version number and the output fields for the message information. The INQY MSGINFO call returns the response in the I/O area. The following table lists the output that is returned from the INQY MSGINFO call. Included with the information returned is the byte length, the actual value, and an explanation of the output.
Length in bytes 4 8 Actual value 1 Explanation Output response version 1. The IMS identifier from which the input message originated. This field is reserved for future output expansion.
| Table 60. INQY MSGINFO data output | Information returned | Version number | Origin IMSID | | | Reserved for IMS | | | | | | | | | | | | | | | |
68
Querying the PCB: INQY FIND

The FIND subfunction is used to get a PCB address after issuing an INQY DBQUERY call. See Querying Data Availability: INQY DBQUERY on page 267 for more information about the INQY DBQUERY call. Issuing the FIND subfunction after issuing an INQY DBQUERY call allows the application program to analyze the current PCB status code to determine if either an NA or NU status code is set in the PCB. When the INQY call is issued with the FIND subfunction, the application program is returned with the PCB address of the requested PCB name that is passed in AIBRSNM1. The only valid PCB names that can be passed in AIBRSNM1 are IOPCB or the name of an alternate PCB or DB PCB, as defined in the PSB. The PCB address is returned in the AIBRSA1 field of the AIB mask. When the INQY call is completed, the AIBRSA1 field contains call-specific information. To retrieve the status for a database, you must pass the DB PCB for that database in the INQY FIND call. You must issue one call for each PCB required.
270

On a FIND subfunction, the requested PCB remains unmodified, and no information is returned in an I/O area. | | | | The FIND subfunction is used to get a PCB address following an INQY DBQUERY call. This process allows the application program to analyze the PCB status code to determine if either an NA or NU status code is set in the PCB. The following PL/I code sample shows how to retrieve the database status values.
271

| II00_INITSTAT: PROC; DCL DUMMY_LENGTH CHAR(4) INIT( ); /* TO PLEASE IMS */ | AIB.PCBNAME = IOPCB; | CALL AIBTDLI($3,INIT,AIB,STATUS_CALL2); | IF AIB.RETURN = 0 THEN | PUT SKIP LIST(INIT ISSUED); | ELSE | DO; | PUT SKIP LIST (AIB RETURN CODE ,AIB.RETURN); | PUT SKIP LIST (AIB REASON CODE ,AIB.REASON); | PUT SKIP LIST (IOPCB STATUS CODE ,IO_PCB.STATUS_CODE); | PUT SKIP LIST (INIT UNSUCCESSFULL); | END; | SELECT (IO_PCB.STATUS_CODE); | WHEN ( ) | GROUPA_STATUS = ; | WHEN (NA) | GROUPA_STATUS = NA; | WHEN (NU) | GROUPA_STATUS = NU; | OTHERWISE | DO; | PUT SKIP LIST | (INIT STATUS GROUPA FAILED ,IO_PCB.STATUS_CODE); | END; | END; | PUT SKIP LIST | (INIT STATUS GROUPA = ,IO_PCB.STATUS_CODE); | | END II00_INITSTAT; | JJ00_INQY: PROC; DCL DUMMY_LENGTH CHAR(4) INIT( ); /* TO PLEASE IMS */ | AIB.PCBNAME = IOPCB; | AIB.SUB_FUNC = DBQUERY ; | AIB.OUT_LEN_TOT = 2000; | CALL AIBTDLI($3,INQY,AIB,IO_AREA); | PUT SKIP LIST(INQY ISSUED ON IOPCB BEFORE CHECK OF AIB RETURN); | IF AIB.RETURN = 0 THEN | PUT SKIP LIST(INQY ISSUED - 0 RC ON AIB.RETURN); | ELSE | DO; | PUT SKIP LIST (AIB RETURN CODE ,AIB.RETURN); | PUT SKIP LIST (AIB REASON CODE ,AIB.REASON); | PUT SKIP LIST (IOPCB STATUS CODE ,IO_PCB.STATUS_CODE); | PUT SKIP LIST (INQY IOPCB DBQUERY UNSUCCESSFULL); | END; | SELECT (IO_PCB.STATUS_CODE); | WHEN ( ) | DO; | PUT SKIP DATA (IO_AREA); | PUT SKIP DATA (IO_PCB.STATUS_CODE); | END; | WHEN (NA) | PUT SKIP LIST (NA STATUS ON IO_PCB.STATUS_CODE); | WHEN (NU) | PUT SKIP LIST (NU STATUS ON IO_PCB.STATUS_CODE); | OTHERWISE | DO; | PUT SKIP LIST | (INQY FAILED ,IO_PCB.STATUS_CODE); | END; | END; | | | Figure 52. Sample PL/I Program to retrieve database status values (Part 1 of 3) |
272

PUT SKIP LIST (START B1CSTP FIND CALL); AIB.PCBNAME = B1CSTP; AIB.SUB_FUNC = FIND ; AIB.OUT_LEN_TOT = 2000; CALL AIBTDLI($3,INQY,AIB,IO_AREA); PUT SKIP LIST(INQY B1CSTP FIND READY TO BE CALLED); IF AIB.RETURN = 0 THEN PUT SKIP LIST(INQY B1CSTP FIND CALLED - 0 RC); ELSE DO; PUT SKIP LIST (AIB RETURN CODE ,AIB.RETURN); PUT SKIP LIST (AIB REASON CODE ,AIB.REASON); PUT SKIP LIST (CSTP_PCB STATUS CODE ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (INQY B1CSTP FIND UNSUCCESSFULL); END; PUT SKIP LIST (CSTP STATUS ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (IO PCB , IO_PCB.STATUS_CODE); SELECT (CSTP_PCB.STATUS_CODE); WHEN ( ) DO; PUT SKIP DATA (CSTP_PCB.STATUS_CODE); PUT SKIP DATA (IO_AREA); END; WHEN (NA) PUT SKIP LIST (NA STATUS ON B1CSTP CSTPPCB.STATUS_CODE); WHEN (NU) PUT SKIP LIST (NU STATUS ON B1CSTP CSTPPCB.STATUS_CODE); OTHERWISE DO; PUT SKIP LIST (INQY FAILED ,IO_PCB.STATUS_CODE); END; END; PUT SKIP LIST (START D1CSTP FIND CALL); AIB.PCBNAME = D1CSTP; AIB.SUB_FUNC = FIND ; AIB.OUT_LEN_TOT = 2000; CALL AIBTDLI($3,INQY,AIB,IO_AREA); PUT SKIP LIST(INQY D1CSTP FIND READY TO BE CALLED); IF AIB.RETURN = 0 THEN PUT SKIP LIST(INQY D1CSTP FIND CALLED - 0 RC); ELSE DO; PUT SKIP LIST (AIB RETURN CODE ,AIB.RETURN); PUT SKIP LIST (AIB REASON CODE ,AIB.REASON); PUT SKIP LIST (CSTP_PCB STATUS CODE ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (INQY D1CSTP FIND UNSUCCESSFULL); END; PUT SKIP LIST (CSTP STATUS ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (IO PCB , IO_PCB.STATUS_CODE); SELECT (CSTP_PCB.STATUS_CODE); WHEN ( ) DO; PUT SKIP DATA (CSTP_PCB.STATUS_CODE); PUT SKIP DATA (IO_AREA); END; WHEN (NA) PUT SKIP LIST (NA STATUS ON D1CSTP CSTPPCB.STATUS_CODE); WHEN (NU) PUT SKIP LIST (NU STATUS ON D1CSTP CSTPPCB.STATUS_CODE); OTHERWISE DO; PUT SKIP LIST (INQY FAILED ,IO_PCB.STATUS_CODE); END; Figure 52. Sample PL/I Program to retrieve database status values (Part 2 of 3)
273
END; PUT SKIP LIST (START S1CSTP FIND CALL); AIB.PCBNAME = XXCSTP; AIB.SUB_FUNC = FIND ; AIB.OUT_LEN_TOT = 2000; CALL AIBTDLI($3,INQY,AIB,IO_AREA); PUT SKIP LIST(INQY S1CSTP FIND READY TO BE CALLED); IF AIB.RETURN = 0 THEN PUT SKIP LIST(INQY S1CSTP FIND CALLED - 0 RC); ELSE DO; PUT SKIP LIST (AIB RETURN CODE ,AIB.RETURN); PUT SKIP LIST (AIB REASON CODE ,AIB.REASON); PUT SKIP LIST (CSTP_PCB STATUS CODE ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (INQY S1CSTP FIND UNSUCCESSFULL); END; PUT SKIP LIST (CSTP STATUS ,CSTP_PCB.STATUS_CODE); PUT SKIP LIST (IO PCB , IO_PCB.STATUS_CODE); SELECT (CSTP_PCB.STATUS_CODE); WHEN ( ) DO; PUT SKIP DATA (CSTP_PCB.STATUS_CODE); PUT SKIP DATA (IO_AREA); END; WHEN (NA) PUT SKIP LIST (NA STATUS ON S1CSTP CSTPPCB.STATUS_CODE); WHEN (NU) PUT SKIP LIST (NU STATUS ON S1CSTP CSTPPCB.STATUS_CODE); OTHERWISE DO; PUT SKIP LIST (INQY FAILED ,IO_PCB.STATUS_CODE); END; END;
| Figure 52. Sample PL/I Program to retrieve database status values (Part 3 of 3)
Querying for LE Overrides: INQY LERUNOPT

| | | | | | | | | When the LERUNOPT call is issued with the LERUNOPT subfunction, IMS determines if LE overrides are allowed based on the LEOPT system parameter. The LE override parameters are defined to IMS through the UPDATE LE command. IMS checks to see if there are any overrides applicable to the caller based on the specific combinations of transaction name, LTERM name, user ID, or program name in the callers environment. IMS will return the address of the string to the caller if an override parameter is found. The LE overrides are used by the IMS supplied CEEBXITA exit, DFSBXITA, to allow dynamic overrides for LE runtime parameters. DFSBXITA is delivered in the IMS.SDFSSMPL library. Related Reading: v For more information about the UPDATE LE command, see IMS Version 9: Command Reference. v For more information about the IMS supplied CEEBXITA, DFSBXITA, see IMS Version 9: Customization Guide. The call string must contain the function code and the AIB address. The I/O area is not a required parameter and will be ignored if specified. The only valid PCB name that can be passed in AIBRSNM1 is IOPCB. The AIBOALEN and AIBOAUSE fields are not used.
274

The rules for matching an entry that results in it being returned on a DL/I INQY LERUNOPT call are: v An MPP or JMP region uses transaction name, LTERM, userid, and program to match with each entry. v An IFB, JBP, or non-message driven BMP uses program name to match with each entry. If an entry has a defined filter for transaction name, LTERM, or userid, it does not match. Message driven BMPs also use transaction name. v The entries are scanned to find the entry with the most filter matches. The first entry in the list with the most exact filter matches is selected. The scan stops with an entry found with all of the filters matching the entry. Note: Searching table entries may cause user confusion because of the way entries are built and searched. For example, assume there are two entries in the table that match on the filters specified on the DL/I INQY call. The first transaction matches on transaction name and LTERM name. The second entry matches on transaction name and program name. IMS chooses the first entry because it was the first entry encountered with highest number of filter matches. If the second entry is now updated with a longer parameter string, which causes a new entry to be built, it will be added to the head of the queue. The next search would result in the entry with transaction name and program name being selected. This could result in a set of runtime options being selected that were not expected by the user.
Querying the Program Name: INQY PROGRAM

When you issue the INQY call with the PROGRAM subfunction, the application program name is returned in the first 8 bytes of the I/O area. The only valid PCB name that can be passed in AIBRSNM1 is IOPCB .
INQY Return Codes and Reason Codes

When you issue the INQY call, return and reason codes are returned to the AIB. Status codes can be returned to the PCB. If return and reason codes other than those that apply to INQY are returned, your application should examine the PCB to see what status codes are found.
Map of INQY Subfunction to PCB Type

Table 61. Subfunction, PCB, and I/O Area Combinations for the INQY Call Subfunction FIND ENVIRON DBQUERY LERUNOPT PROGRAM I/O PCB OK OK OK OK OK Alternate PCB DB PCB OK NO NO NO NO OK NO NO NO NO I/O Area Required NO YES NO NO YES
Restrictions
The INQY call is valid only when using the AIB. An INQY call issued through the PCB interface is rejected with an AD status code.
275
System Service Call: LOG
LOG Call
The Log (LOG) call is used to send and write information to the IMS system log.
Format
LOG io pcb aib i/o area
Call Name LOG
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the area in your program that contains the record that you want to write to the system log. This is an input parameter. This record must follow the format shown in Table 62and Table 63.
Table 62. Log Record Formats for COBOL, C, Assembler, Pascal, and PL/I Programs for the AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI Interfaces LL 2 ZZ 2 C 1 Text Variable
Table 63. Log Record Formats for COBOL, C, Assembler, Pascal, and PL/I Programs for the PLITDLI Interface LLLL 4 ZZ 2 C 1 Text Variable
The fields must be: LL or LLLL Specifies a 2-byte field (or, for PL/I, a 4-byte-long field) to contain the length of the record. The length of the record is
276
System Service Call: LOG

equal to LL + ZZ + C + text of the record. When you calculate the length of the log record, you must account for all fields. The total length you specify includes: v 2 bytes for LL or LLLL. (For PL/I, include the length as 2, even though LLLL is a 4-byte field.) v 2 bytes for the ZZ field. v 1 byte for the C field. v n bytes for the length of the record itself. If you are using the PLITDLI interface, your program must define the length field as a binary fullword. ZZ C Text Specifies a 2-byte field of binary zeros. Specifies a 1-byte field containing a log code, which must be equal to or greater than X'A0'. Specifies any data to be logged.
Usage
An application program can write a record to the system log by issuing the LOG call. When you issue the LOG call, specify the I/O area that contains the record you want written to the system log. You can write any information to the log, and you can use different log codes to distinguish between different types of information. You can issue the LOG call: v In a batch program, and the record is written to the IMS log v In an online program in the DBCTL environment, and the record is written to the DBCTL log v In the IMS DB/DC environment, and the record is written to the IMS log
Restrictions
The length of the I/O area (including all fields) cannot be larger than the logical record length (LRECL) for the system log data set, minus four bytes, or the I/O area specified in the IOASIZE keyword of the PSBGEN statement of the PSB. For function shipping in the CICS environment, the local and remote CICS must both be DBCTL.
PCB Call (CICS Online Programs Only)

The PCB call is used to schedule a PSB call. The ODBA interface does not support this call.
Format
PCB psb name uibptr sysserve
Call Name PCB
DB/DC X
DBCTL X
DCCTL
DB Batch
TM Batch
277
System Service Call: PCB
Parameters
The AIB is not valid for PCB calls. psb name Specifies the PSB. An asterisk can be used for the parameter to indicate the default. This parameter is an input parameter. uibptr Specifies a pointer, which is set to the address of the UIB after the call. This parameter is an output parameter. sysserve Specifies an optional 8-byte field that contains either IOPCB or NOIOPCB. This parameter is an input parameter.
Usage
Before a CICS online program can issue any DL/I calls, it must indicate to DL/I its intent to use a particular PSB. A PCB call accomplishes this and also obtains the address of the PCB list in the PSB. When you issue a PCB call, specify: v The call function: PCB v The PSB you want to use, or an asterisk to indicate that you want to use the default name. The default PSB name is not necessarily the name of the program issuing the PCB call, because that program could have been called by another program. v A pointer, which is set to the address of the UIB after the call. For more information on defining and establishing addressability to the UIB, see Specifying the UIB (CICS Online Programs Only) on page 77. v The system service call parameter that names an optional 8-byte field that contains either IOPCB or NOIOPCB.
Restrictions
For function shipping in the CICS environment, the local and remote CICS must both be DBCTL.
RCMD Call
A Retrieve Command (RCMD) call enables an automated operator (AO) application program retrieve the second and subsequent command response segments after an ICMD call.
Format
RCMD aib i/o area
Parameters
aib Specifies the application interface block (AIB) used for this call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
278
System Service Call: RCMD

AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. This field is not changed by IMS. AIBOAUSE Length of data returned in the I/O area. This parameter is an output parameter. When partial data is returned because the I/O area is not large enough, AIBOAUSE contains the length required to receive all of the data, and AIBOALEN contains the actual length of the data. i/o area Specifies the I/O area to use for this call. This parameter is an output parameter. The I/O area should be large enough to hold the largest command response segment that is passed from IMS to the AO application program. If the I/O area is not large enough for all of the information, partial data is returned in the I/O area.
Usage
RCMD lets an AO application program retrieve the second and subsequent command response segments resulting from an ICMD call. Related Reading For more information on the AOI exits, see IMS Version 9: Customization Guide. Table 64 shows, by IMS environment, the types of AO application programs that can issue RCMD. RCMD is also supported from a CPI-C driven program.
Table 64. RCMD Support by Application Region Type IMS Environment Application Region Type DRA thread BMP (nonmessage-driven) BMP (message-driven) MPP IFP DBCTL Yes Yes N/A N/A N/A DB/DC Yes Yes Yes Yes Yes DCCTL N/A Yes Yes Yes Yes
RCMD retrieves only one response segment at a time. If you need additional response segments, you must issue RCMD one time for each response segment that is issued by IMS.
Restrictions
An ICMD call must be issued before an RCMD call.
279
System Service Call: ROLB
ROLB Call
The Roll Back (ROLB) call is used to dynamically back out database changes and return control to your program. For more information on the ROLB call, see Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) on page 112. The ODBA interface does not support this call.
Format
ROLB i/o pcb aib i/o area
Call Name ROLB
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the area in your program where IMS returns the first message segment. This parameter is an output parameter.
Restrictions
The AIB must specify the I/O PCB for this call.
ROLL Call
The Roll (ROLL) call is used to abnormally terminate your program and to dynamically back out database changes. For more information on the ROLL call, see Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) on page 112.
280
System Service Call: ROLL

The ODBA interface does not support this call.
Format
ROLL
Call Name ROLL
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
The only parameter required for the ROLL call is the call function.
Usage
When you issue a ROLL call, IMS terminates the application program with a U0778 abend.
Restrictions
Unlike the ROLB call, the ROLL call does not return control to the program.
ROLS Call
The Roll Back to SETS (ROLS) call is used to back out to a processing point set by a prior SETS or SETU call. For more information on the ROLS call, see Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) on page 112.
Format
ROLS i/o pcb aib db pcb i/o area token
Call Name ROLS
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
db pcb Specifies the DB PCB for the call. This parameter is an input and output parameter. i/o pcb Specifies the I/O PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
281
System Service Call: ROLS

AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB , or the name of a DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the I/O area has the same format as the I/O area supplied on the SETS call. This parameter is an output parameter. token Specifies the area in your program that contains a 4-byte identifier. This parameter is an input parameter.
Usage
When you use the Roll Back to SETS (ROLS) call to back out to a processing point set by a prior SETS or SETU, the ROLS enables you to continue processing or to back out to the prior commit point and place the input message on the suspend queue for later processing. Issuing a ROLS call for a DB PCB can result in the user abend code 3303.
Restrictions
For function shipping in the CICS environment, the local and remote CICS must both be DBCTL. The ROLS call is not valid when the PSB contains a DEDB or MSDB PCB, or when the call is made to a DB2 database.
SETS/SETU Call
The Set a Backout Point (SETS) call is used to set an intermediate backout point or to cancel all existing backout points. The SET Unconditional (SETU) call operates like the SETS call, except that the SETU call is accepted even if unsupported PCBs exist or an external subsystem is used. For more information on the SETS and SETU calls, see Maintaining Database Integrity (IMS Batch, BMP, and IMS Online Regions) on page 112.
Format
SETS SETU i/o pcb aib i/o area token
Call Name SETS/SETU
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
282
System Service Call: SETS/SETU
Parameters
i/o pcb Specifies the I/O PCB for the call. SETS and SETU must refer to the I/O PCB. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the area in your program that contains the data to be returned on the corresponding ROLS call. This parameter is an input parameter. token Specifies the area in your program that contains a 4-byte identifier. This parameter is an input parameter.
Usage
The SETS and SETU format and parameters are the same, except for the call functions, SETS and SETU. The SETS and SETU calls provide the backout points that IMS uses in the ROLS call. The ROLS call operates with the SETS and SETU call backout points. The meaning of the SC status code for SETS and SETU is as follows: SETS The SETS call is rejected. The SC status code in the I/O PCB indicates that either the PSB contains unsupported options or the application program made calls to an external subsystem.
SETU The SETU call is not rejected. The SC status code indicates either that unsupported PCBs exist in the PSB or the application program made calls to an external subsystem.
Restrictions
For function shipping in the CICS environment, the local and remote CICS must both be DBCTL. The SETS call is not valid when the PSB contains a DEDB or MSDB PCB, or when the call is made to a DB2 database. The SETU call is valid, but not functional, if unsupported PCBs exist in the PSB or if the program uses an external subsystem. | | Before a ROLS call, you can specify a maximum of 255 SETS calls with the same token and still back out to the correct message level. After 255 SETS calls, the
283
System Service Call: SETS/SETU

| | messages continue to back out, but only to the same message level as at 255th SETS call. The SETS token count resets to zero during sync point processing.
SNAP Call
This section contains product-sensitive programming interface information. The SNAP call is used to collect diagnostic information.
Format
SNAP db pcb aib i/o area
Call Name SNAP
DB/DC X
DBCTL X
DCCTL
DB Batch X
TM Batch
Parameters
db pcb Specifies the address that refers to a full-function PCB that is defined in a calling program PSB. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a full-function DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies the area in your program that contains SNAP operation parameters. This parameter is an input parameter. Figure 53 on page 285 shows the SNAP operation parameters you specify, including: v Length for bytes 1 through 2 v Destination for bytes 3 through 10 v Identification for bytes 11 through 18 v SNAP options for bytes 19 through 22
284
System Service Call: SNAP
Figure 53. I/O Area for SNAP Operation Parameters
Table 65 explains the values that you can specify.

Table 65. SNAP Operation Parameters Byte 1-2 Value xx Meaning This 2-byte binary field specifies the length of the SNAP operation parameters. The length must include this 2-byte length field. When you do not specify operation parameters, IMS uses default values. This chart lists the lengths that result from your parameter specifications. If you supply values And IMS supplies for: default values for: Destination, Identification, SNAP options Destination, Identification Destination SNAP options Identification, SNAP options Destination, Identification, SNAP options Then the length (in hexadecimal) is: 16
12 10 2
If you specify another length, IMS uses default values for the destination, identification, and SNAP operation parameters. 3-10 This 8-byte field tells IMS where to send SNAP output. You can direct output to the IMS log by specifying LOG or Directs the output to the IMS log. This is the default destination. dcbaddr Directs the output to the data set defined by this DCB address. The application program must open the data set before the SNAP call refers to it. This option is valid only in a batch environment. The output data set must conform to the rules for a z/OS SNAP data set. ddname Directs the output to the data set defined by the corresponding DD statement. The DD statement must conform to the rules for a z/OS SNAP data set. The data set specified by ddname is opened and closed for this SNAP request. In a DB/DC environment, you must supply the DD statement in the JCL for the control region. If the destination is invalid, IMS directs output to the IMS log.
285
System Service Call: SNAP

Table 65. SNAP Operation Parameters (continued) Byte 11-18 Value cccccccc Meaning This is an eight-character name you can supply to identify the SNAP. If you do not supply a name, IMS uses the default value, NOTGIVEN. This four-character field identifies which data elements you want the SNAP output to include. YYYN is the default. Buffer Pool: Y N 20 Y N 21 Y Dump all buffer pools and sequential buffering control blocks with a SNAP call. Do not dump buffer pools or sequential buffering control blocks with a SNAP call. Control Blocks: Dump control blocks related to the current DB PCB with a SNAP call. Do not dump control blocks related to the current DB PCB with a SNAP call. Dump all control blocks for this PSB with a SNAP call. Specifying Y in byte 21 produces a snap dump for the current DB PCB request in byte 20 to Y, regardless of the current value. Do not dump all control blocks for this PSB with a SNAP call. In this case, the current DB PCB SNAP request in position 20 is used as specified. This is equivalent to specifying YYY in positions 19-21. Region: Y Dump the entire region on the DCB address or data set ddname that you supplied in bytes 3-10 with a SNAP call. IMS processes this request before it acts on any SNAP requests made in bytes 19-21. If the destination is the IMS log, IMS does not dump the entire region. Instead, it processes the request as if you had specified ALL. Do not dump the entire region with a SNAP call. Dump subpools 0-127 with a SNAP call.
19-22 19
cccc
19-21 22
ALL
N S
After the SNAP call, IMS can return the AB, AD, or (blank) status code. For a description of these codes and the response required, see IMS Version 9: Application Programming: EXEC DLI Commands for CICS and IMS.
Usage
Any application program can issue this call.
Restrictions
STAT Call
This sectioncontains product-sensitive programming interface information.
286
System Service Call: STAT

The Statistics (STAT) call is used in a CICS, IMS online, or batch program to obtain database statistics that might be useful for performance monitoring.
Format
STAT db pcb aib i/o area stat function
Call Name STAT
DB/DC X
DBCTL X
DCCTL
DB Batch X
TM Batch
Parameters
db pcb Specifies the DB PCB used to pass status information to the application program. The VSAM statistics used by the data sets associated with this PCB are not related to the type of statistics that is returned from the STAT call. This PCB must reference a full-function database. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the name of a full-function DB PCB. AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. i/o area Specifies an area in the application program that is large enough to hold the requested statistics. This parameter is an output parameter. In PL/I, this parameter should be specified as a pointer to a major structure, array, or character string. stat function Specifies a 9-byte area whose content describes the type and format of the statistics required. The first 4 bytes define the type of statistics requested and byte 5 defines the format to be provided. The remaining 4 bytes contain EBCDIC blanks. If the stat function that is provided is not one of the defined functions, an AC status code is returned. This parameter is an input parameter. The 9-byte field contains: v 4 bytes that define the type of statistics you want: DBAS OSAM database buffer pool statistics DBES OSAM database buffer pool statistics, enhanced or extended VBAS VSAM database subpool statistics
287
System Service Call: STAT

VBES VSAM database subpool statistics, enhanced or extended v 1 byte that gives the format of the statistics: F Full statistics to be formatted. If you specify F, your I/O area must be at least 360 bytes for DBAS or VBAS and 600 bytes for DBES or VBES. Full OSAM database subpool statistics in a formatted form. If you specify O, your I/O area must be at least 360 bytes. Summary of the statistics to be formatted. If you specify S, your I/O area must be at least 120 bytes for DBAS or VBAS and 360 bytes for DBES or VBES.
O S
Full statistics to be unformatted. If you specify U, your I/O area must be at least 72 bytes. v 4 bytes of EBCDIC blanks for normal or enhanced STAT call, or E1 , for extended STAT call. U Restriction: The extended format parameter is supported by the DBESO, DBESU, and DBESF functions only. Extended OSAM buffer pool statistics can be retrieved by including the parameter E1 following the enhanced call function. The extended STAT call returns all of the statistics returned with the enhanced call, plus the statistics on the coupling facility buffer invalidates, OSAM caching, and sequential buffering IMMED and SYNC read counts.
Usage
The STAT call can be helpful in debugging because it retrieves IMS database statistics. It is also helpful in monitoring and tuning for performance. The STAT call retrieves OSAM database buffer pool statistics and VSAM database buffer supports. When you request VSAM statistics, each issued STAT call retrieves the statistics for a subpool. Statistics are retrieved for all VSAM local shared resource pools in the order in which they are defined. For each local shared resource pool, statistics are retrieved in ascending order based on buffer size. Statistics for index subpools always follow those for data subpools if any index subpool exists in the shared resource pool. The index subpools are also retrieved in ascending order based on buffer size. For more information on the STAT call, see IMS Version 9: Application Programming: Design Guide.
Restrictions
SYNC Call
The Synchronization Point (SYNC) call is used to release resources that IMS has locked for the application program. The ODBA interface does not support this call.
288
System Service Call: SYNC
Format
SYNC i/o pcb aib
Call Name SYNC
DB/DC X
DBCTL X
DCCTL X
DB Batch
TM Batch
Parameters
i/o pcb Specifies the IO PCB for the call. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB .
Usage
SYNC commits the changes your program has made to the database, and establishes places in your program from which you can restart, if your program terminates abnormally.
Restrictions
The SYNC call is valid only in non-message driven BMPs; you cannot issue a SYNC call from an CPI-C driven application program. For important considerations about using the SYNC call, see IMS Version 9: Administration Guide: Database Manager.
TERM Call (CICS Online Programs Only)

The Terminate (TERM) call is used to terminate a PSB in a CICS online program. The ODBA interface does not support this call.
Format
TERM
Call Name TERM
DB/DC X
DBCTL X
DCCTL
DB Batch
TM Batch
289
System Service Call: TERM
Usage
If your program needs to use more than one PSB, you must issue a TERM call to release the first PSB it uses and then issue a second PCB call to schedule the second PSB. The TERM call also commits database changes. The only parameter in the TERM call is the call function: TERM or T . When your program issues the call, CICS terminates the scheduled PSB, causes a CICS sync point, commits changes, and frees resources for other tasks.
Restrictions
XRST Call
The Extended Restart (XRST) call is used to restart your program. If you use the symbolic Checkpoint call in your program, you must precede it with an XRST call that specifies checkpoint data of blanks. The ODBA interface does not support this call.
Format
XRST i/o pcb aib i/o area length i/o area
area length area
Call Name XRST
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Parameters
i/o pcb Specifies the I/O PCB for the call. XRST must refer to the I/O PCB. This parameter is an input and output parameter. aib Specifies the AIB for the call. This parameter is an input and output parameter. These fields must be initialized in the AIB: AIBID Eye catcher. This 8-byte field must contain DFSAIB .
AIBLEN AIB lengths. This field must contain the actual length of the AIB that the application program obtained. AIBRSNM1 Resource name. This 8-byte, left-justified field must contain the PCB name, IOPCB . AIBOALEN I/O area length. This field must contain the length of the I/O area specified in the call list. This parameter is not used during the XRST call. For compatibility reasons, this parameter must still be coded.
290
System Service Call: XRST

i/o area length This parameter is no longer used by IMS. For compatibility reasons, this parameter must still be included in the call, and it must contain a valid address. You can get a valid address by specifying the name of any area in your program. i/o area Specifies a 14-byte area in your program. This area must be either set to blanks if starting your program normally or, if performing an extended restart, have a checkpoint ID. area length Specifies a 4-byte field in your program that contains the length (in binary) of the area to restore. This parameter is an input parameter. You can specify up to seven area lengths. For each area length, you must specify the area parameter. All seven area parameters (and corresponding area length parameters) are optional. When you restart the program, IMS restores only the areas specified on the CHKP call. The number of areas you specify on an XRST call must be less than or equal to the number of areas you specify on a CHKP call. area Specifies the area in your program that you want IMS to restore. You can specify up to seven areas. Each area specified must be preceded by an area length. This is an input parameter.
Usage
Programs that wish to issue Symbolic Checkpoint calls (CHKP) must also issue the Extended Restart call (XRST). The XRST call must be issued only once and should be issued early in the execution of the program. It does not need to be the first call in the program. However, it must precede any CHKP call. Any Database calls issued before the XRST call are not within the scope of a restart. To determine whether to perform a normal start or a restart, IMS evaluates the I/O area provided by the XRST call or CKPTID= value in the PARM field on the EXEC statement in your program's JCL.
Starting Your Program Normally

When you are starting your program normally, the I/O area pointed to in the XRST call must contain blanks and the CKPTID= value in the PARM field must be nulls. This indicates to IMS that subsequent CHKP calls are symbolic checkpoints rather than basic checkpoints. Your program should test the I/O area after issuing the XRST call. IMS does not change the area when you are starting the program normally. However, an altered I/O area indicates that you are restarting your program. Consequently, your program must handle the specified data areas that were previously saved and that are now restored.
Restarting Your Program

You can restart the program from a symbolic checkpoint taken during a previous execution of the program. The checkpoint used to perform the restart can be identified by entering the checkpoint ID either in the I/O area pointed to by the XRST call (left-most justified, with the rest of the area containing blanks) or by specifying the ID in the CKPTID= field of the PARM= parameter on the EXEC statement in your program's JCL. (If you supply both, IMS uses the CKPTID= value specified in the parm field of the EXEC statement.) The ID specified can be:
291

v A 1 to 8-character extended checkpoint ID v A 14-character "time stamp" ID from message DFS0540I, where: IIII is the region ID DDD is the day of the year HHMMSST is the time in hours, minutes, seconds, and tenth of a second v The 4-character constant "LAST". (BMPs only: this indicates to IMS that the last completed checkpoint issued by the BMP will be used for restarting the program) The system message DFS0540I supplies the checkpoint ID and the time stamp. The system message DFS682I supplies the checkpoint ID of the last completed checkpoint which can be used to restart a batch program or batch message processing program (BMP) that was abnormally terminated. If the program being restarted is in either a batch region or a BMP region, and the checkpoint log records no longer reside on the Online Log Data Set (OLDS) or System Log Data Set (SLDS), the //IMSLOGR DD defining the log data set must be supplied in the JCL for the BATCH or BMP region. IMS reads these data sets and searches for the checkpoint records with the ID that was specified. Restriction: To issue a checkpoint restart from a batch job, you must use the original job name, or IMS cannot locate the checkpoint and the job fails with a U0102. At completion of the XRST call the I/O area always contains the 8-character checkpoint ID used for the restart. An exception exists when the checkpoint ID is equal to 8 blank characters; the I/O area then contains a 14-character time stamp (IIIIDDDHHMMSST). Also check the status code in the I/O PCB. The only successful status code for an XRST call are blanks.
Position in the Database after Issuing XRST

The XRST call attempts to reposition all databases to the position that was held when the last checkpoint was taken. This is done by including each PCB and PCB key feedback area in the checkpoint record. Issuing XRST causes the key feedback area from the PCB in the checkpoint record to be moved to the corresponding PCB in the PSB that is being restarted. Then IMS issues a GU call, qualified with the concatenated key (using the C command code), for each PCB that held a position when the checkpoint was taken. After the XRST call, the PCB reflects the results of the GU repositioning call, not the value that was present when the checkpoint was taken. The GU call is not made if the PCB did not hold a position on a root or lower-level segment when the checkpoint was taken. A GE status code in the PCB means that the GU for the concatenated key was not fully satisfied. The segment name, segment level, and key feedback length in the PCB reflect the last level that was satisfied on the GU call. A GE status code can occur because IMS is unable to find a segment that satisfies the segment search argument that is associated with a Get call for one of the following reasons: v The call preceding the checkpoint call was a DLET call issued against the same PCB. In this case, the position is correct because the not-found position is the same position that would exist following the DLET call.
292

Restriction: Avoid taking a checkpoint immediately after a DLET call. v The segment was deleted by another application program between the time your program terminated abnormally and the time you restarted your program. A GN call issued after the restart returns the first segment that follows the deleted segment or segments. This explanation assumes that position at the time of checkpoint was on a segment with a unique key. XRST cannot reposition to a segment if that segment or any of its parents have a non unique key. For a DEDB, the GC status code is received when position is not on a segment but at a unit-of-work (UOW) boundary. Because the XRST call attempts to reestablish position on the segment where the PCB was positioned when the symbolic checkpoint was taken, the XRST call does not reestablish position on a PCB if the symbolic checkpoint is taken when the PCB contains a GC status code. If your program accesses GSAM databases, the XRST call also repositions these databases. For more information on processing GSAM databases, see Chapter 8, Processing GSAM Databases, on page 157.
Restrictions
If your program is being started normally, the first 5 bytes of the I/O area must be set to blanks. If your program is restarted and the CKPTID= value in the PARM field of the EXEC statement is not used, then the right-most bytes beyond the checkpoint ID being used in the I/O area must be set to blanks. The XRST call is allowed only from Batch and BMP application programs.
293
294
Chapter 13. Relationship Between Calls and AIB and PCBs

Table 66 shows the relationship of calls to full function (FF), main storage database (MSDB), data entry database (DEDB), I/O, and general sequential access method (GSAM) PCBs.
Table 66. Call Relationship to PCBs CALL APSB CHKP CIMS CLSE DEQ DLET DPSB FLD GHN GHNP GHU GMSG GN GNP GSCD GU ICMD INIT INQY ISRT LOG OPEN PCB2 POS RCMD REPL ROLB ROLL
2 1
AIB X X X X X X X X X X X X X X X X X X X X X X
FF PCBs
MSDB PCBs
DEDB PCBs
I/O PCBs
GSAM PCBs
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
ROLS SETS/SETU SNAP STAT

3 3
X X X X X
X X
X X
SYNC
295
Relationship Between Calls and AIB and PCBs

Table 66. Call Relationship to PCBs (continued) CALL TERM XRST Notes: 1. GSCD is a Product-sensitive programming interface. 2. The PCB, ROLL, and TERM calls do not have an associated PCB. 3. SNAP is a Product-sensitive programming interface. 4. STAT is a Product-sensitive programming interface.
2
AIB
FF PCBs
MSDB PCBs
DEDB PCBs
I/O PCBs
GSAM PCBs
296
Chapter 14. DL/I Test Program (DFSDDLT0)

DFSDDLT0 is an IMS application program test tool that issues calls to IMS based on control statement information. You can use it to verify and debug DL/I calls independently of application programs. You can run DFSDDLT0 using any PSB, including those that use an IMS-supported language. You can also use DFSDDLT0 as a general-purpose database utility program. The functions that DFSDDLT0 provides include: v Issuing any valid DL/I call against any database using: Any segment search argument (SSA) or PCB, or both Any SSA or AIB, or both v Comparing the results of a call to expected results. This includes the contents of selected PCB fields, the data returned in the I/O area, or both. v Printing the control statements, the results of calls, and the results of comparisons only when the output is useful, such as after an unequal compare. v Dumping DL/I control blocks, the I/O buffer pool, or the entire batch region. v Punching selected control statements into an output file to create new test data sets. This simplifies the construction of new test cases. v Merging multiple input data sets into a single input data set using a SYSIN2 DD statement in the JCL. You can specify the final order of the merged statements in columns 73 to 80 of the DFSDDLT0 control statements. v Sending messages to the z/OS system console (with or without a reply). v Repeating each call up to 9,999 times. The following topics provide additional information: v Control Statements on page 298 v v v v v v v v Planning the Control Statement Order on page 299 ABEND Statement on page 300 CALL Statement on page 300 COMMENT Statement on page 320 COMPARE Statement on page 321 IGNORE Statement on page 327 OPTION Statement on page 327 PUNCH CTL Statement on page 328
v STATUS Statement on page 331 v WTO Statement on page 334 v WTOR Statement on page 335 v JCL Requirements on page 335 v Execution of DFSDDLT0 in IMS Regions on page 339 v Explanation of DFSDDLT0 Return Codes on page 339 v DFSDDLT0 Hints on page 339
297
Control Statements
Control Statements
DFSDDLT0 processes control statements to control the test environment. DFSDDLT0 can issue calls to IMS full-function databases and Fast Path databases, as well as DC calls. Table 67 gives an alphabetical summary of the types of control statements DFSDDLT0 uses. A detailed description of each type of statement follows.
Table 67. Summary of DFSDDLT0 Control Statements Control Statement ABEND CALL L
1
Code ABEND
Description Causes user abend 252. There are two types of CALL statements: CALL FUNCTION identifies the type of IMS call function to be made and supplies information to be used by the call. CALL DATA provides IMS with additional information.
COMMENT T
There are two types of COMMENT statements: Conditional allows a limited number of comments that are printed or not depending on how the STATUS statement is coded and the results of the PCB or DATA COMPARE. Unconditional allows an unlimited number of comments, all of which are printed. There are three types of COMPARE statements: E COMPARE DATA verifies that the correct segment was retrieved by comparing the segment returned by IMS with data in this statement. COMPARE AIB compares values that IMS returns to the AIB. COMPARE PCB checks fields in the PCB and calls for a snap dump of the DL/I blocks, the I/O buffer pool, or the batch region if the compare is unequal.
U1 COMPARE
IGNORE OPTION1
N or . O
The program ignores statements that contain an N or . (period) in column 1. Shows which control blocks are to be dumped, the number of unequal comparisons allowed, whether dumps are produced, number of lines printed per page, and the SPA size. PUNCH CTL produces an output data set consisting of the COMPARE PCB statements, the COMPARE AIB statements, the DATA statements, and all other control statements read. Establishes print options and selects the PCB or AIB against which subsequent calls are to be issued. Sends a message to the z/OS console without waiting for reply. Sends a message to the z/OS console and waits for a reply before proceeding.
PUNCH1
CTL
STATUS1 WTO1 WTOR Note:

1
S WTO WTOR
1. These control statements are acted on immediately when encountered in an input stream. Do not code them where they will interrupt call sequences. (See Planning the Control Statement Order on page 299.)
The control statements from Table 67 are described below: v The CALL statement is the central DFSDDLT0 statement. The CALL statement has two parts: CALL FUNCTION and CALL DATA. CALL FUNCTION identifies the type of IMS call function and supplies information about segment
298
Control Statements
search arguments (SSAs). CALL DATA provides more information required for the type of call identified by CALL FUNCTION. v The STATUS statement controls the PCB, AIB, and handling of output. v The three types of COMPARE statements, DATA, PCB, and AIB, compare different values: If you want specific data from a call, use COMPARE DATA to check the segment data for mismatches when the call is made. Use COMPARE PCB to check status codes, segment levels, and feedback keys. It also indicates mismatches when you specify output. Use COMPARE AIB to compare values that IMS returns to the AIB. v The two COMMENT statements, Conditional and Unconditional, allow you to set limits on the number of comments on the DFSDDLT0 job stream and to specify whether you want the comments printed. v The OPTION statement controls several overall functions such as the number of unequal comparisons allowed and the number of lines printed per page. v The remaining statements, ABEND, IGNORE, CTL, WTO and WTOR, are not as important as the others at first. Read the sections describing these statements so that you can become familiar with the functions they offer. When you are coding the DFSDDLT0 control statements, keep these items in mind: v If you need to temporarily override certain control statements in the DFSDDLT0 streams, go to the JCL requirements section and read about SYSIN/SYSIN2 processing under SYSIN2 DD Statement on page 336. v You must fill in column 1 of each control statement. If column 1 is blank, the statement type defaults to the prior statement type. DFSDDLT0 attempts to use any remaining characters as it would for the prior statement type. v Use of reserved fields can produce invalid output and unpredictable results. v Statement continuations are important, especially for the CALL statement. v Sequence numbers are not required, but they can be very useful for some DFSDDLT0 functions. To understand how to use sequence numbers, see PUNCH CTL Statement on page 328, SYSIN DD Statement on page 336 and SYSIN2 DD Statement on page 336. v All codes and fields in the DFSDDLT0 statements must be left justified followed by blanks, unless otherwise specified.
Planning the Control Statement Order

The order of control statements is critical in constructing a successful call. To avoid unpredictable results, follow these guidelines: 1. If you are using STATUS and OPTION statements, place them somewhere before the calls that are to use them. 2. Both types of COMMENT statements are optional but, if present, must appear before the call they document. 3. You must code CALL FUNCTION statements and any required SSAs consecutively without interruption. 4. CALL DATA statements must immediately follow the last continuation, if any, of the CALL FUNCTION statements. 5. COMPARE statements are optional but must follow the last CALL (FUNCTION or DATA) statement. 6. When CALL FUNCTION statements, CALL DATA statements, COMPARE DATA statements, COMPARE PCB statements, and COMPARE AIB statements
299
Planning the Control Statement Order

are coded together, they form a call sequence. Do not interrupt call sequences with other DFSDDLT0 control statements. Exception: IGNORE statements are the only exception to this rule. 7. Use IGNORE statements (N or .) to override any statement, regardless of its position in the input stream. You can use IGNORE statements in either SYSIN or SYSIN2 input streams.
ABEND Statement
The ABEND statement causes IMS to issue an abend and terminate DFSDDLT0. Table 68 shows the format of the ABEND statement.
Table 68. ABEND Statement Column 1-5 6-72 73-80 Function Identifies control statement Reserved Sequence indication nnnnnnnn For SYSIN2 statement override. Code ABEND Description Issues abend U252. (No dump is produced unless you code DUMP on the OPTION statement.)
Examples of ABEND Statement

If you use ABEND in the input stream and want a dump, you must specify DUMP on the OPTION statement. The default on the OPTION statement is NODUMP.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< ABEND 22100010
Dump will be produced; OPTION statement provided requests dump.

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O DUMP 22100010
No dump will be produced; OPTION statement provided requests NODUMP.

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O NODUMP 22100010
CALL Statement
The CALL control statement has two parts: CALL FUNCTION and CALL DATA. v The CALL FUNCTION statement supplies the DL/I call function, the segment search arguments (SSAs), and the number of times to repeat the call. SSAs are coded according to IMS standards. v With the CALL DATA statement you provide any data (database segments, z/OS commands, checkpoint IDs) required by the DL/I call specified in the CALL FUNCTION statement. See CALL DATA Statement on page 303.
CALL FUNCTION Statement

Table 69 gives the format for CALL FUNCTION statements, including the column number, function, code, and description. This is the preferred format when you are not working with column-specific SSAs.
Table 69. CALL FUNCTION Statement Column 1 Function Identifies control statement Code L Description Issues an IMS call
300
CALL Statement
Table 69. CALL FUNCTION Statement (continued) Column 2 3 Function Reserved SSA level n 4 5-8 Reserved Repeat count nnnn If blank, repeat count defaults to 1. 'nnnn' is the number of times to repeat this call. Range is 1 to 9999, right-justified, with or without leading zeros. SSA level (optional) Range of hexadecimal characters allowed is 1-F Code Description
9 10-13
Reserved Identifies DL/I call function xxxx Continue SSA CONT If blank, use function from previous CALL statement. 'xxxx' is a DL/I call function. Continuation indicator for SSAs too long for a single CALL FUNCTION statement. Column 72 of the preceding CALL FUNCTION statement must have an entry. The next CALL statement should have CONT in columns 10 - 13 and the SSA should continue in column 16.
14-15 16-23 or 16-23 or 16-23 or 16-23 or 16-19 and 20 or 1619 21-24
Reserved SSA name Token MOD name Subfunction Statistics type Statistics format SETO ID1 SETO IOAREA SIZE xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxx x SETx nnnn Must be left-justified. Token name (SETS/ROLS). Modname (PURG+ISRT). nulls, DBQUERY, FIND, ENVIRON, PROGRAM (INQY). DBAS/DBES-OSAM or VBAS/VBES-VSAM (STAT).2 F - Formatted U- Unformatted S - Summary. Where x is 1, 2, or 3. Specified on SETO and CHNG calls as defined in Note. Value of 0000 to 8192. If a value greater than 8192 is specified, it defaults to 8192. If no value is specified, the call is made with no SETO size specified.
2471
Remainder of SSA
Unqualified SSAs must be blank. Qualified search arguments should have either an '*' or a '(' in column 24 and follow IMS SSA coding conventions. No continuations for this statement. x Alone, it indicates multiple SSAs each beginning in column 16 of successive statements. With CONT in columns 10-13 of the next statement, indicates a single SSA that is continued beginning in column 16 of the following statement.
72
Continuation column
301
CALL Statement
Table 69. CALL FUNCTION Statement (continued) Column 73-80 Note: 1. SETO CALL: The SETO ID (SET1, SET2, or SET3) is required on the SETO call if DFSDDLT0 is to keep track of the text unit address returned on the SETO call that would be passed on the CHNG call for option parameter TXTU. If the SETO ID is omitted on the SETO call, DFSDDLT0 does not keep track of the data returned and is unable to reference it on a CHNG call. CHNG CALL: The SETO ID (SET1, SET2, or SET3) is required on the CHNG call if DFSDDLT0 is to place the address of the SETO ID I/O area returned on the SETO call. This is the SETO call of the text unit returned on the SETO call with a matching SETO ID for this CHNG call into the TXTU=ADDR field of the option parameter in the CHNG call. When the SETO ID is specified on the CHNG call, DFSDDLT0 moves the address of that text unit returned on the SETO call using the same SETO ID. Code the OPTION statement parameter TXTU as follows: TXTU=xxxx where xxxx is any valid non-blank character. It cannot be a single quote character. Suggested value for xxxx could be SET1, SET2, or SET3. This value is not used by DFSDDLT0. 2. STAT is a Product-sensitive programming interface. Function Sequence indication Code nnnnnnnn Description For SYSIN2 statement override.
This information applies to different types of continuations: v Column 3, the SSA level, is usually blank. If it is blank, the first CALL FUNCTION statement fills SSA 1, and each following CALL FUNCTION statement fills the next lower SSA. If column 3 is not blank, the statement fills the SSA at that level, and the following CALL FUNCTION statement fills the next lower one. v Columns 5 through 8 are usually blank, but if used, must be right justified. The same call is repeated as specified by the repeat call function. v Columns 10 through 13 contain the DL/I call function. The call function is required only for the first CALL FUNCTION statement when multiple SSAs are in a call. If left blank, the call function from the previous CALL FUNCTION statement is used. v Columns 16 through 23 contain the segment name if the call uses a SSA. v If the DL/I call contains multiple SSAs, the statement must have a nonblank character in column 72, and the next SSA must start in column 16 of the next statement. The data in columns 1 and 10 through 13 are blank for the second through last SSAs. Restriction: On ISRT calls, the last SSA can have only the segment name with no qualification or continuation. v If a field value extends past column 71, put a nonblank character in column 72. (This character is not read as part of the field value, only as a continuation character.) In the next statement insert the keyword CONT in columns 10 through 13 and continue the field value starting at column 16. v Maximum length for the field value is 256 bytes, maximum size for a SSA is 290 bytes, and the maximum number of SSAs for this program is 15, which is the same as the IMS limit. v If columns 5 through 8 in the CALL FUNCTION statement contain a repeat count for the call, the call will terminate when reaching that count, unless it first encounters a GB status code.
302
CALL Statement
Related Reading: See CALL FUNCTION Statement with Column-Specific SSAs on page 317 for another format supported by DFSDDLT0.
CALL DATA Statement

CALL DATA statements provide IMS with information normally supplied in the I/O area for that type of call function. CALL DATA statements must follow the last CALL FUNCTION statement. You must enter an L in column 1, the keyword DATA in columns 10 through 13, and code the necessary data in columns 16 through 71. You can continue data by entering a nonblank character in column 72. On the continuation statement, columns 1 through 15 are blank and the data resumes in column 16. Table 70 shows the format for a CALL DATA statement.
Table 70. CALL DATA Statement Column 1 2 3 Function Identifies control statement Code L Description CALL DATA statement. Adds 2500 bytes to the length of data defined in columns 5 through 8. Causes 50 bytes (columns 16 through 65) to be propagated through remaining I/O area. Note: This must be the last data statement and cannot be continued. Not a variable-length segment. V For the first statement describing the only variable-length segment or the first variable-length segment of multiple variable-length segments, LL field is added before the segment data. For statements describing the second through the last variable-length segments, LL field is added before the segment data. For the first statement describing a fixed-length segment in a path call. For message segment, LLZZ field is added before the data. Undefined record format for GSAM records. The length of segment for an ISRT is placed in the DB PCB key feedback area.
Increase segment length K Propagate remaining I/O indicator P
Format options
P Z U
5-8
Length of data in segment
nnnn
This value must be right justified but need not contain leading zeros. If you do not specify a length, DFSDDLT0 will use the number of DATA statements read multiplied by 56 to derive the length.
9 10-13 14-15
Reserved Identifies CALL DATA statement Reserved DATA Identifies this as a DATA statement.
303
CALL Statement
Table 70. CALL DATA Statement (continued) Column 16-71 or 16-23 or 16-23 or 16 72 DEQ option Continuation column x 73-80 Sequence indication nnnnnnnn DEQ options (A,B,C,D,E,F,G,H,I, or J). If no more continuations for this segment. If more data for this segment or more segments. For SYSIN2 statement override. Destination name Destination name (CHNG). Checkpoint ID Checkpoint ID (SYNC). Function Data area Code xxxx Description Data that goes in the I/O area.
When inserting variable-length segments or including variable-length data for a CHKP or LOG call: v You must use a V or M in column 4 of the CALL DATA statement. v Use V if only one variable-length segment is being processed. v You must enter the length of the data with leading zeros, right justified, in columns 5 through 8. The value is converted to binary and becomes the first 2 bytes of the segment data. v You can continue a CALL DATA statement into the next CALL DATA statement by entering a nonblank character in column 72. For subsequent statements, leave columns 1 through 15 blank, and start the data in column 16. If multiple variable-length segments are required (that is, concatenation of logical child and logical parent segments, both of which are variable-length) for the first segment: v You must enter a V in column 4. v You must enter the length of the first segment in columns 5 through 8. v If the first segment is longer than 56 bytes, continue the data as described for inserting variable-length segments. Exceptions: The last CALL DATA statement to contain data for this segment must have a nonblank character in column 72. The next CALL DATA statement applies to the next variable-length statement and must contain an M in column 4 and the length of the segment in columns 5 through 8. You can concatenate any number of variable-length segments in this manner. Enter M or V and the length (only in CALL DATA statements that begin data for a variable-length segment). When a program is inserting or replacing through path calls: v Enter a P in column 4 to specify that the length field is to be used as the length the segment will occupy in the user I/O area.
304
CALL Statement
v You only need to use P in the first statement of fixed-length-segment CALL DATA statements in path calls that contain both variable- and fixed-length segments. v You can use V, M, and P in successive CALL DATA statements. For INIT, SETS, ROLS, and LOG calls: v The format of the I/O area is
LLZZuser-data
where LL is the length of the data in the I/O area, including the length of the LLZZ portion. v If you want the program to use this format for the I/O area, enter a Z in column 4 and the length of the data in columns 5 through 8. The length in columns 5 through 8 is the length of the data, not including the 4-byte length of LLZZ.
OPTION DATA Statement

The OPTION DATA statement contains options as required for SETO and CHNG calls. Table 71 shows the format for an OPTION DATA statement, including the column number, function, code, and description.
Table 71. OPTION DATA Statement Column 1 2-9 10-13 Function Identifies control statement Reserved Identifies OPT CONT 14-15 16-71 72 Reserved Option area Continuation column x 73-80 Sequence number nnnnnnnn xxxx Options as defined for SETO and CHNG call. If no more continuations for options. If more option data exists in following statement. For SYSIN2 statement override. Identifies this as OPTION statement. Identifies this as a continuation of an option input. Code L Description OPTION statement.
FEEDBACK DATA Statement

The FEEDBACK DATA statement defines an area to contain feedback data. The FEEDBACK DATA statement is optional. However, if the FEEDBACK DATA statement is used, an OPTION DATA statement is required. Table 72 shows the format for a FEEDBACK DATA statement, including the column number, function, code, and description.
Table 72. FEEDBACK DATA Statement Column 1 2-3 Function Identifies control statement Reserved Code L Description FEEDBACK statement.
305
CALL Statement
Table 72. FEEDBACK DATA Statement (continued) Column 4 Function Format option Z 5-8 Length of feedback area nnnn Code Description Feedback area contains LLZZ. Length of feedback area will be computed and the LLZZ will be added to the feedback area. This value must be right justified but need not contain leading zeros. If you do not specify a length, DFSDDLT0 uses the number of FDBK inputs read multiplied by 56 to derive the length.
2-9 10-13 14-15 16-71 72
Reserved Identifies Reserved Feedback area Continuation column x xxxx Contains user pre-defined initialized area. If no more continuations for feedback. If more feedback data exists in following statement. For SYSIN2 statement override. FDBK Identifies this as feedback statement and continuation of feedback statement.
73-80
Sequence number
nnnnnnnn
DL/I Call Functions

Table 73 shows the DL/I call functions supported in DFSDDLT0 and which ones require data statements.
Table 73. DL/I Call Functions Call CHKP CHNG AIB Support yes yes PCB Support yes yes Data Stmt R R R CMD DEQ yes yes yes yes R R
1
Description Checkpoint. Change alternate PCB. Contains the alternate PCB name option statement and feedback statement optional. Issue IMS command. This call defaults to I/O PCB. Dequeue segments locked with the Q command code. For full function, this call defaults to the I/O PCB, provided a DATA statement containing the class to dequeue immediately follows the call. For Fast Path, the call is issued against a DEDB PCB. Do not include a DATA statement immediately following the DEQ call. Delete. If the data statement is present, it is used. If not, the call uses the data from the previous Get Hold Unique (GHU). Fieldfor Fast Path MSDB calls using FSAs. This call references MSDBs only. If there is more than one FSA, put a nonblank character in column 34, and put the next FSA in columns 16-34 of the next statement. A DATA statement containing FSA is required. Get command response. This call defaults to I/O PCB. Get Hold Next. Get Hold Next in Parent. Get Hold Unique.
DLET FLD
yes yes
yes yes
O R
GCMD GHN GHNP GHU
yes yes yes yes
yes yes yes yes
N O O O
2 2 2
306
CALL Statement
Table 73. DL/I Call Functions (continued) Call GMSG
3
AIB Support yes
PCB Support no
Data Stmt R
Description Get Message is used in an automated operator (AO) application program to retrieve a message from AO exit routine DFSAOE00. The DATA statement is required to allow for area in which to return data. The area must be large enough to hold this returned data. Get Next segment. Get Next in Parent. Get Unique segment. Issue Command enables an automated operator (AO) application program to issue an IMS command and retrieve the first command response segment. The DATA statement is required to contain the input command and to allow for area in which to return data. The area must be large enough to hold this returned data. Initialization This call defaults to I/O PCB. A DATA statement is required. Use the LLZZ format. Request environment information using the AIB and the ENVIRON subfunction. The DATA statement is required to allow for area in which to return data. The area must be large enough to hold this returned data. Request database information using the AIB and the DBQUERY subfunction, which is equivalent to the INIT DBQUERY call. The DATA statement is required to allow for area in which to return data. The area must be large enough to hold this returned data. Insert.
GN GNP GU ICMD
3
yes yes yes yes
yes yes yes no
O2 O O R
2 2
INIT INQY3
yes yes
yes no
R R
ISRT
yes
yes R O R
DB PCB, DATA statement required. I/O PCB using I/O area with MOD name, if any, in columns 16-23. Alt PCB. Log system request. This call defaults to I/O PCB. DATA statement is required and can be specified in one of two ways. Position - for DEDBs to determine a segment location. This call references DEDBs only. Purge.
LOG POS PURG
yes yes yes
yes yes yes
R N
This call defaults to use I/O PCB. If column 16 is not blank, MOD (message output descriptor) name is used and a DATA statement is required. If column 16 is blank, the DATA statement is optional. Retrieve Command enables an automated operator (AO) application program to retrieve the second and subsequent command response segments after an ICMD call. The DATA statement is required to allow for area in which to return data. The area must be large enough to hold this returned data. ReplaceThis call references DB PCBs only. The DATA statement is required. Roll Back call.
O RCMD
3
yes
no
REPL ROLB
yes yes
yes yes
R O
307
CALL Statement
Table 73. DL/I Call Functions (continued) Call ROLL ROLS AIB Support no yes PCB Support yes yes Data Stmt O O
1
Description Roll Back call and issue U778 abend. Back out updates and issue 3303 abend. Uses the I/O PCB. Can be used with the SETS call function. To issue a ROLS with an I/O area and token as the fourth parameter, specify the 4-byte token in column 16 of the CALL statement. Leaving columns 16-19 blank will cause the call to be made without the I/O area and the token. (To issue a ROLS using the current DB PCB, use ROLX.) Roll call against the DB PCB (DFSDDLT0 call function). This call is used to request a Roll Back call to DB PCB, and is changed to ROLS call when making the DL/I call. Set options. OPTION statement required. FEEDBACK statement optional. Create or cancel intermediate backout points. Uses I/O PCB. To issue a SETS with an I/O area and token as the fourth parameter, specify the four-byte token in column 16 of the CALL statement and include a DATA statement. Leaving columns 16-19 blank will cause the call to be made without the I/O area and the token. Sets the identification and destination for snap dumps. If a SNAP call is issued without a CALL DATA statement, a snap of the I/O buffer pools and control blocks will be taken and sent to LOG if online and to PRINTDD DCB if batch. The SNAP ID will default to SNAPxxxx where xxxx starts at 0000 and is incremented by 1 for every SNAP call without a DATA statement. The SNAP options default to YYYN. If a CALL DATA statement is used, columns 16-23 specify the SNAP destination, columns 24-31 specify the SNAP identification, and columns 32-35 specify the SNAP options. SNAP options are coded using Y to request a snap dump and N to prevent it. Column 32 snaps the I/O buffer pools, columns 33 and 34 snap the IMS control blocks and column 35 snaps the entire region. The SNAP call function is only supported for full-function database PCB. The STAT call retrieves statistics on the IMS system. This call must reference only full-function DB PCBs. See the examples on 317. Statistics type is coded in columns 16-19 of the CALL FUNCTION statement. DBAS For OSAM database buffer pool statistics.
ROLX
yes
yes
SETO SETS/SETU
yes yes
yes yes
N O
SNAP4
yes
yes
STAT5
yes
yes
VBAS For VSAM database subpool statistics. Statistics format is coded in column 20 of the CALL FUNCTION statement. F U S SYNC XRST yes yes yes yes R R For the full statistics to be formatted if F is specified, the I/O area must be at least 360 bytes. For the full statistics to be unformatted if U is specified, the I/O area must be at least 72 bytes. For a summary of the statistics to be formatted if S is specified, the I/O area must be at least 120 bytes.
Synchronization. Restart.
308
CALL Statement
Table 73. DL/I Call Functions (continued) Call Notes: 1. R = required; O = optional; N = none 2. The data statement is required on the AIB interface. 3. Valid only on the AIB interface. 4. SNAP is a Product-sensitive programming interface. 5. STAT is a Product-sensitive programming interface. AIB Support PCB Support Data Stmt
1
Description
Examples of DL/I Call Functions

Basic CHKP Call: Use a CALL FUNCTION statement to contain the CHKP function and a CALL DATA statement to contain the checkpoint ID.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L CHKP 10101400 L DATA TESTCKPT
Symbolic CHKP Call with Two Data Areas to Checkpoint: Use a CALL FUNCTION statement to contain the CHKP function, a CALL DATA statement to contain the checkpoint ID data, and two CALL DATA statements to contain the data that you want to checkpoint. You also need to use an XRST call when you use the symbolic CHKP call. Prior usage of an XRST call is required when using the symbolic CHKP call, as the CHKP call keys on the XRST call for symbolic CHKP. Recommendation: Issue an XRST call as the first call in the application program.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L XRST L . L . L . L CHKP L DATA TSTCHKP2 X L 8 DATA STRING2X L 16 DATA STRING2-STRING2U EIGHT BYTES OF DATA (STRING2-) IS CHECKPOINTED AND U SIXTEEN BYTES OF DATA (STRING2-STRING2-) IS CHECKPOINTED ALSO
CHNG Call: Use a CALL FUNCTION statement to contain the CHNG function and a CALL DATA statement to contain the new logical terminal name.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L CHNG SET1 L OPT IAFP=A1M,PRTO=LLOPTION1,OPTION2, L CONT OPTION4 L Z0023 DATA DESTNAME LL is the hex value of the length of LLOPTION,.........OPTION4.
The following is an example of a CHNG statement using SETO ID SET2, OPTION statement, DATA statement with MODNAME, and FDBK statement.
309
CALL Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L CHNG SET2 L OPT IAFP=A1M,TXTU=SET2 L Z0023 DATA DESTNAME L Z0095 FDBK FEEDBACK AREA
CMD Call: Use a CALL FUNCTION statement to contain the CMD function and a CALL DATA statement to contain the Command data.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L CMD L ZXXXX DATA COMMAND DATA WHERE XXXX = THE LENGTH OF THE COMMAND DATA
DEQ Call: For full function, use a CALL FUNCTION statement to contain the DEQ function and a CALL DATA statement to contain the DEQ value (A,B,C,D,E,F,G,H,I or J).
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L DEQ L DATA A
For Fast Path, use a CALL FUNCTION statement to contain the DEQ function.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L DEQ
DLET Call: Use a CALL FUNCTION statement to contain the DLET function. The data statement is optional. If there are intervening calls to other PCBs between the Get Hold call and the DLET call, you must use a data statement to refresh the I/O area with the segment to be deleted.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L DLET
FLD Call: Use a CALL FUNCTION statement to contain the FLD function and ROOTSSA, and a CALL DATA statement to contain the FSAs.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L FLD ROOTA (KEYA =ROOTA) L DATA ??????? X L DATA
GCMD Call: Use a CALL FUNCTION statement to contain the GCMD function; no CALL DATA statement is required.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GCMD
GHN Call: Use a CALL FUNCTION statement to contain the GHN function; no CALL DATA statement is required.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GHN 10103210
GHNP Call: Use a CALL FUNCTION statement to contain the GHNP function; no CALL DATA statement is required.
310
CALL Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GHNP 10103210
GHU Call with a Continued SSA: Use two CALL FUNCTION statements to contain the single SSA.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GHU SEGG (FILLRG = G131G131G131G131G131G131G131G131G131G* CONT 131G131G131G131G131G131G131 )
GMSG Call: Use a CALL FUNCTION statement to contain the GMSG function. Use a CALL DATA statement to retrieve messages from AO exit routine.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GMSG TOKEN111 WAITAOI L Z0132 DATA L GMSG L Z0132 DATA
GN Call: Use a CALL FUNCTION statement to contain the GN function; no CALL DATA statement is required.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GN 10103210
GNP Call: Use a CALL FUNCTION statement to contain the GNP function; no CALL DATA statement is required.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GNP 10103210
GU Call with a Single SSA and a Relational Operator: Use a CALL FUNCTION statement to contain the GU function; no CALL DATA statement is required. The qualified SSA begins in column 24 and is contained in parentheses.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU SEGF (KEYF > F131*KEYF < F400)
GU Call with a Single SSA and a Relational Operator Extended Across Multiple Inputs with Boolean Operators: Use a CALL FUNCTION statement to contain the GU function and three additional continuation of CALL FUNCTION input to continue with Boolean operators. No CALL DATA statement is required. The qualified SSA begins in column 24 and is contained in parentheses. This type of SSA can continue over several statements.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU SEGG (FILLRG > G131G131G131G131G131G131G131G131G131G* CONT 131G131G131G131G131G131G131 &FILLRG < G400G400G4* CONT 00G400G400G400G400G400G400G400G400G400G400G400G400G400 * CONT )
GU Path Call: Use a CALL FUNCTION statement to contain the GU function and three additional continuation of CALL function input to continue with two additional SSAs. No CALL DATA statement is required. The call uses command codes in columns 24 and 25 to construct the path call. This type of call cannot be made with the column-specific SSA format.
311
CALL Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU SEGA *D(KEYA = A200) * SEGF *D(KEYF = F250) * SEGG *D(KEYG = G251)
ICMD Call: Use a CALL FUNCTION statement to contain the ICMD function. Use a CALL DATA statement to contain the command.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ICMD L Z0132 DATA /DIS ACTIVE
INIT Call: Use a CALL FUNCTION statement to contain the INIT call and a CALL DATA statement to contain the INIT function DBQUERY, STATUS GROUPA, or STATUS GROUPB.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L INIT 10103210 L Z0011 DATA DBQUERY
INQY Call: Use a CALL FUNCTION statement to contain the INQY call and either the DBQUERY or ENVIRON subfunction. The subfunctions are in the call input rather than the data input as in the INIT call.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L INQY ENVIRON 10103210 L V0256 DATA 10103211 L 10103212 |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L INQY DBQUERY 10103210 L V0088 DATA 10103211 L 10103212
ISRT Call: Use two CALL FUNCTION statements to contain the multiple SSAs and a CALL DATA statement to contain the segment data.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT STOCKSEG(NUMFIELD =20011) X10103210 ITEMSSEG 10103211 L V0018 DATA 3002222222222222 10103212
ISRT Containing Only One Fixed-Length Segment: Use a CALL FUNCTION statement to contain the ISRT function and segment name, and two CALL DATA statements to contain the fixed-length segment. When inserting only one fixed-length segment, leave columns 4 through 8 blank and put data in columns 16 through 71. To continue data, put a nonblank character in column 72, and the continued data in columns 16 through 71 of the next statement.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT JOKESSEG 10103210 L DATA THEQUICKBLACKDOGJUMPEDONTOTHECRAZYFOXOOPSTHEQUICKBROWNFO*10103211 XJUMPEDOVERTHELAZYDOGSIR 10103212
ISRT Containing Only One Variable-Length Segment: Use a CALL FUNCTION statement to contain the ISRT function and segment name, and two CALL DATA statements to contain the variable-length segment. When only one segment of variable-length is being processed, you must enter a V in column 4, and columns 5 through 8 must contain the length of the segment data. The length in columns 5 through 8 is converted to binary and becomes the first two bytes of the segment
312
CALL Statement
data. To continue data, put a nonblank character in column 72, and the continued data in columns 16 through 71 of the next statement.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT JOKESSEG 10103210 L V0080 DATA THEQUICKBLACKDOGJUMPEDONTOTHECRAZYFOXOOPSTHEQUICKBROWNFO*10103211 XJUMPEDOVERTHELAZYDOGSIR 10103212
ISRT Containing Multiple Variable-Length Segments: Use a CALL FUNCTION statement to contain the ISRT function and segment name, and four CALL DATA statements to contain the variable-length segments. For the first segment, you must enter a V in column 4 and the length of the segment data in columns 5 through 8. If the segment is longer than 56 bytes, put a nonblank character in column 72, and continue data on the next statement. The last statement to contain data for this segment must have a nonblank character in column 72. The next DATA statement applies to the next variable-length segment and it must contain an M in column 4, the length of the new segment in columns 5 through 8, and data starting in column 16. Any number of variable-length segments can be concatenated in this manner. If column 72 is blank, the next statement must have the following: v An L in column 1 v An M in column 4 v The length of the new segment in columns 5 through 8 v The keyword DATA in columns 10 through 13 v Data starting in column 16
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT AAAAASEG 10103210 L V0080 DATA THEQUICKBLACKDOGJUMPEDONTOTHECRAZYFOXOOPSTHEQUICKBROWNFO*10103211 XJUMPEDOVERTHELAZYDOGSIR *10103212 M0107 DATA NOWISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRYNOW*10103213 ISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRY 10103214
ISRT Containing Multiple Segments in a PATH CALL: Use a CALL FUNCTION statement to contain the ISRT function and segment name, and seven CALL DATA statements to contain the multiple segments in the PATH CALL. When DFSDDLT0 is inserting or replacing segments through path calls, you can use V and P in successive statements. The same rules apply for coding multiple variable-length segments, but fixed-length segments must have a P in column 4 of the DATA statement. This causes the length field in columns 5 through 8 to be used as the length of the segment, and causes the data to be concatenated in the I/O area without including the LL field. Rules for continuing data in the same segment or starting a new segment in the next statement are the same as those applied to the variable-length segment.
313
CALL Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT LEV01SEG*D *10103210 LEV02SEG *10103211 LEV03SEG *10103212 LEV04SEG 10103213 L V0080 DATA THEQUICKBLACKDOGJUMPEDONTOTHECRAZYFOXOOPSTHEQUICKBROWNFO*10103214 XJUMPEDOVERTHELAZYDOGSIR *10103215 M0107 DATA NOWISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRYNOW*10103216 ISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRY *10103217 L P0039 DATA THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGSIR *10103218 L M0107 DATA NOWISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRYNOW*10103219 ISTHETIMEFORALLGOODMENTOCOMETOTHEAIDOFTHEIRCOUNTRY 10103220
LOG Call Using an LLZZ Format: Use a CALL FUNCTION statement to contain the LOG function and a CALL DATA statement to contain the LLZZ format of data to be logged. When you put a Z in column 4, the first word of the record is not coded in the DATA statement. The length specified in columns 5 through 8 must include the 4 bytes for the LLZZ field that is not in the DATA statement.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L LOG 10103210 L Z0016 DATA ASEGMENT ONE 10103211
The A in column 16 becomes the log record ID. POS Call: Use a CALL FUNCTION statement to contain the POS function and SSA; CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L POS SEGA (KEYA =A300)
PURG Call with MODNAME and Data: Use a CALL FUNCTION statement to contain the PURG function and MOD name. Use the CALL DATA statement to contain the message data. If MOD name is provided, a DATA statement is required.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L PURG MODNAME1 L DATA FIRST SEGMENT OF NEW MESSAGE
PURG Call with Data and no MODNAME: Use a CALL FUNCTION statement to contain the PURG function; a DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L PURG L DATA FIRST SEGMENT OF NEW MESSAGE
PURG Call without MODNAME or Data: Use a CALL FUNCTION statement to contain the PURG function; CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L PURG
RCMD Call: Use a CALL FUNCTION statement to contain the RCMD function. Use a CALL DATA statement to retrieve second and subsequent command response segments resulting from an ICMD call.
314
CALL Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L RCMD L Z0132 DATA
REPL Call: Use a CALL FUNCTION statement to contain the REPL function. Use a CALL DATA statement to contain the replacement data.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L REPL L V0028 DATA THIS IS THE REPLACEMENT DATA
ROLB Call Requesting Return of First Segment of Current Message: Use a CALL FUNCTION statement to contain the ROLB function. Use the CALL DATA statement to request first segment of current message.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLB L DATA THIS WILL BE OVERLAID WITH FIRST SEGMENT OF MESSAGE
ROLB Call Not Requesting Return of First Segment of Current Message: Use a CALL FUNCTION statement to contain the ROLB function. The CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLB
ROLL Call: Use a CALL FUNCTION statement to contain the ROLL function. The CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLL
ROLS Call with a Token: Use a CALL FUNCTION statement to contain the ROLS function and token, and the CALL DATA statement to provide the data area that will be overlaid by the data from the SETS call.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLS TOKEN1 L Z0046 DATA THIS WILL BE OVERLAID WITH DATA FROM SETS
ROLS Call without a Token: Use a CALL FUNCTION statement to contain the ROLS function. The CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLS
ROLX Call: Use a CALL FUNCTION statement to contain the ROLX function. The CALL DATA statement is optional. The ROLX function is treated as a ROLS call with no token.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ROLX
SETO Call: Use a CALL FUNCTION statement to contain the SETO function. The DATA statement is optional; however, if an OPTION statement is passed on the call, the DATA statement is required. Also, if a FEEDBACK statement is passed on the call, then both the DATA and OPTION statements are required. The following is an example of a SETO statement using the OPTION statement and SETO token
315
CALL Statement
of SET1.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SETO SET1 5000 L OPT PRTO=11OPTION1,OPTION2, L CONT OPTION3, L CONT OPTION4
11 is the hex value of the length of 11OPTION,.........OPTION4. The following is an example of a SETO statement using the OPTION statement and SETO token of SET1.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SETO SET1 7000 L OPT PRTO=11OPTION1,OPTION2,OPTION3,OPTION4
11 is the hex value of the length of 11OPTION,.........OPTION4. The following is an example of a SETO statement using the OPTION statement and SETO token of SET2 and FDBK statement.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SETO SET2 5500 L OPT PRTO=11OPTION1,OPTION2,OPTION3,OPTION4 L Z0099 FDBK OPTION ERROR FEEDBACK AREA
11 is the hex value of the length of 11OPTION,.........OPTION4. SETS Call with a Token: Use a CALL FUNCTION statement to contain the SETS function and token; use the CALL DATA statement to provide the data that is to be returned to ROLS call.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SETS TOKEN1 L Z0033 DATA RETURN THIS DATA ON THE ROLS CALL
SETS Call without a Token: Use a CALL FUNCTION statement to contain the SETS function; CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SETS
This section (SNAP call) contains product-sensitive programming interface information. SNAP Call: Use a CALL FUNCTION statement to contain the SNAP function and a CALL DATA statement to contain the SNAP data.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SNAP 10103210 L V0022 DATA PRINTDD 22222222 10103212
This section (STAT call) contains product-sensitive programming interface information.
316
CALL Statement
STAT Call: OSAM statistics require only one STAT call. STAT calls for VSAM statistics retrieve only one subpool at a time, starting with the smallest. See IMS Version 9: Application Programming: Design Guide for further information about the statistics returned by STAT.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L STAT DBASF L STAT VBASS L STAT VBASS L STAT VBASS L STAT VBASS
SYNC Call: Use a CALL FUNCTION statement to contain the SYNC function. The CALL DATA statement is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SYNC
Initial XRST Call: Use a CALL FUNCTION statement to contain the XRST FUNCTION and a CALL DATA statement that contains a checkpoint ID of blanks to indicate that you are normally starting a program that uses symbolic checkpoints.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L XRST 10101400 L DATA L CKPT L DATA YOURID01
Basic XRST Call: Use a CALL FUNCTION statement to contain the XRST function and a CALL DATA statement to contain the checkpoint ID.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L XRST 10101400 L DATA TESTCKPT
Symbolic XRST Call: Use a CALL FUNCTION statement to contain the XRST function, a CALL DATA statement to contain the checkpoint ID data, and one or more CALL DATA statements where the data is to be returned. The XRST call is used with the symbolic CHKP call.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L XRST L DATA TSTCHKP2 X L 8 DATA OVERLAY2 X L 16 DATA OVERLAY2OVERLAY2 U EIGHT BYTES OF DATA (OVERLAY2) SHOULD BE OVERLAID WITH CHECKPOINTED DATA U SIXTEEN BYTES OF DATA (OVERLAY2OVERLAY2) IS OVERLAID ALSO
CALL FUNCTION Statement with Column-Specific SSAs

In this format, the SSA has intervening blanks between fields. Columns 24, 34, and 37 must contain blanks. Command codes are not permitted. Table 74 on page 318 gives the format for the CALL FUNCTION statement with column-specific SSAs.
317
CALL Statement
Table 74. CALL FUNCTION Statement (Column-Specific SSAs) Column 1 2 3 4 5-8 Function Identifies control statement Reserved Reserved Reserved Repeat Count nnnn If blank, repeat count defaults to 1. 'nnnn' is the number of times to repeat this call. Range 1 to 9999, right-justified but need not contain leading zeros. If blank, use function from previous CALL statement. xxxx CONT 'xxxx' is a DL/I call function. Continuation indicator for SSAs too long for a single CALL FUNCTION statement. Column 72 of preceding CALL FUNCTION statement must contain a nonblank character. The next CALL statement should have CONT in columns 10 through 13 and the SSA should continue in column 16. Code L Description Call statement (see columns 10-13).
10-13
Identifies DL/I call function
14-15 16-23 24 25 26-33 34 35-36 37 38-nn nn+1 72
Reserved SSA name Reserved Start character for SSA SSA field name Reserved DL/I call operator(s) Reserved Field value End character for SSA Continuation column x nnnnn ) name ( f-name s-name Required if call contains SSA. Separator field. Required if segment is qualified. Required if segment is qualified. Separator field. Required if segment is qualified. Separator field. Required if segment is qualified. Note: Do not use '5D' or ')' in field value. Required if segment is qualified. No continuations for this statement. Alone, it indicates multiple SSAs each beginning in column 16 of successive statements. With CONT in columns 10-13 of the next statement, indicates a single SSA that is continued beginning in column 16 of the following statement For SYSIN2 statement override.
73-80
Sequence indication
nnnnnnnn
If a CALL FUNCTION statement contains multiple SSAs, the statement must have a nonblank character in column 72 and the next SSA must start in column 16 of the next statement. If a field value extends past column 71, put a nonblank character in column 72. In the next statement insert the keyword CONT in columns 10 through 13 and continue the field value starting at column 16. Maximum length for field value is 256 bytes, maximum size for a SSA is 290 bytes, and the maximum number of SSAs for this program is 15, which is the same as the IMS limit.
318
CALL Statement
DFSDDLT0 Call Functions

The DFSDDLT0 call functions were created for DFSDDLT0. They do not represent valid IMS calls and are not punched as output if DFSDDLT0 encounters them while a CTL (PUNCH) statement is active. Table 75 shows the special call functions of the CALL FUNCTION statement. Descriptions and examples of these special functions follow.
Table 75. CALL FUNCTION Statement with DFSDDLT0 Call Functions Column 1 2-4 5-8 Function Identifies control statement Reserved Repeat count nnnn If blank, repeat count defaults to 1. 'nnnn' is the number of times to repeat this call. Range is 1 to 9999, right-justified but need not contain leading zeros. Code L Description Call statement.
9 10-15
Reserved Special call function STAK END SKIP START Stack control statements for later execution. Stop stacking and begin execution. Skip statements until START function is encountered. Start processing statements again. For SYSIN2 statement override.
73-80
Sequence indication
nnnnnnnn
STAK/END (stacking) Control Statements

With the STAK statement, you repeat a series of statements that were read from SYSIN and held in memory. All control statements between the STAK statement and the END statement are read and saved. When DFSDDLT0 encounters the END statement, it executes the series of calls as many times as specified in columns 5 through 8 of the STAK statement. STAK calls imbedded within another STAK cause the outer STAK call to be abnormally terminated.
SKIP/START (skipping) Control Statements

With the SKIP and START statements, you identify groups of statements that you do not want DFSDDLT0 to process. These functions are normally read from SYSIN2 and provide a temporary override to an established SYSIN input stream. DFSDDLT0 reads all control statements occurring between the SKIP and START statements, but takes no action. When DFSDDLT0 encounters the START statement, it reads and processes the next statement normally.
Examples of DFSDDLT0 Call Functions

STAK/END Call: The following example shows the STAK and END call functions.
319
CALL Statement
//BATCH.SYSIN DD * 10000700 |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O SNAP= ,ABORT=0 10000800 S 1 1 1 1 1 10001000 L GU SEGA (KEYA =A300) 10001100 L 0003 STAK 10001150 WTO THIS IS PART OF THE STAK 10001200 T THIS COMMENT IS PART OF THE STAK 10001300 L GN 10001400 L END 10001450 U THIS COMMENT SHOULD GET PRINTED AFTER THE STAK IS DONE 3 TIMES 10001500 L 0020 GN 10001600 /*
SKIP/START Call: The following example demonstrates the use of the SKIP and START call functions in SYSIN2 to override and stop the processing of the STAK and END call functions in SYSIN. DFSDDLT0 executes the GU call function in SYSIN, skips the processing of STACK, WTO, T comment, GN, and END in SYSIN, and goes to the COMMENT.
//BATCH.SYSIN DD * 10000700 |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O SNAP= ,ABORT=0 10000800 S 1 1 1 1 1 10001000 L GU SEGA (KEYA =A300) 10001100 L 0003 STAK 10001150 WTO THIS IS PART OF THE STAK 10001200 T THIS COMMENT IS PART OF THE STAK 10001300 L GN 10001400 L END 10001450 U THIS COMMENT SHOULD GET PRINTED AFTER THE STAK IS DONE 3 TIMES 10001500 L 0020 GN 10001600 /* //BATCH.SYSIN2 DD * |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L SKIP 10001150 L START 10001450 U THIS COMMENT SHOULD REPLACE THE STAK COMMENT 10001500 U ********THIS COMMENT SHOULD GET PRINTED BECAUSE OF SYSIN2********* 10001650 /*
COMMENT Statement
Use the COMMENT statement to print comments in the output data. The two types of COMMENT statements, conditional and unconditional are described. Table 76 on page 321 shows the format of the COMMENT statement.
Conditional COMMENT Statement

You can use up to five conditional COMMENT statements per call; no continuation mark is required in column 72. Code the statements in the DFSDDLT0 stream before the call they are to document. Conditional COMMENTS are read and held until a CALL is read and executed. (If a COMPARE statement follows the CALL, conditional COMMENTS are held until after the comparison is completed.) You control whether the conditional comments are printed with column 3 of the STATUS statement. DFSDDLT0 prints the statements according to the STATUS statement in the following order: conditional COMMENTS, the CALL, and the COMPARE(s). The time and date are also printed with each conditional COMMENT statement.
320
COMMENT Statement
Unconditional COMMENT Statement

You can use any number of unconditional COMMENT statements. Code them in the DFSDDLT0 stream before the call they are to document. The time and date are printed with each unconditional COMMENT statement. Table 76 lists the column number, function, code, and description
Table 76. COMMENT Statement Column 1 Function Identifies control statement Code T U 2-72 73-80 Comment data Sequence indication nnnnnnnn Description Conditional comment statement. Unconditional comment statement. Any relevant comment. For SYSIN2 statement override.
Example of COMMENT Statement

T/U Comment Calls: The following example shows the T and U comment calls.
//BATCH.SYSIN DD * 10000700 |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O SNAP= ,ABORT=0 10000800 S 1 1 1 1 1 10001000 L GU SEGB (KEYA =A400) 10001100 T THIS COMMENT IS A CONDITIONAL COMMENT FOR THE FIRST GN 10001300 L GN 10001400 U THIS COMMENT IS AN UNCONDITIONAL COMMENT FOR THE SECOND GN 10001500 L 0020 GN 10001600 /*
COMPARE Statement
The COMPARE statement compares the actual results of a call with the expected results. The three types of COMPARE statements are the COMPARE PCB, COMPARE DATA, and COMPARE AIB. When you use the COMPARE PCB, COMPARE DATA, and COMPARE AIB statements you must: v Code COMPARE statements in the DFSDDLT0 stream immediately after either the last continuation, if any, of the CALL DATA statement or another COMPARE statement. v Specify the print option for the COMPARE statements in column 7 of the STATUS statement. For all three COMPARE statements: v The condition code returned for a COMPARE gives the total number of unequal comparisons. v For single fixed-length segments, DFSDDLT0 uses the comparison length to perform comparisons if you provide a length. The length comparison option (column 3) is not applicable. When you use the COMPARE PCB statement and you want a snap dump when there is an unequal comparison, request it on the COMPARE PCB statement. A snap dump to a log with SNAP ID COMPxxxx is issued along with the snap dump options specified in column 3 of the COMPARE PCB statement.
321
COMPARE Statement
The numeric part of the SNAP ID is initially set to 0000 and is incremented by 1 for each SNAP resulting from an unequal comparison.
COMPARE DATA Statement

The COMPARE DATA statement is optional. It compares the segment returned by IMS to the data in the statement to verify that the correct segment was retrieved. Table 77 gives the format of the COMPARE DATA statement.
Table 77. COMPARE DATA Statement Column 1 2 3 Function Identifies control statement Reserved Length comparison option For fixed-length segments or if the LL field of the segment is not included in the comparison; only the data is compared. L The length in columns 5-8 is converted to binary and compared against the LL field of the segment. Code E Description COMPARE statement.
Segment length option V For a variable-length segment only, or for the first variable-length segment of multiple variable-length segments in a path call, or for a concatenated logical-childlogical-parent segment. For the second or subsequent variable-length segment of a path call, or for a concatenated logical-childlogicalparent segment. For fixed-length segments in path calls. For message segment. Length to be used for comparison. (Required for length options V, M, and P if L is coded in column 3.)
| | | | | | | | |
P Z 5-8 Comparison length nnnn
9 10-13
Reserved Identifies type of statement DATA Required for the first I/O COMPARE statement and the first statement of a new segment if data from previous I/O COMPARE statement is not continued.
14-15 16-71 72
Reserved String of data Continuation column x Data against which the segment in the I/O area is to be compared. If blank, data is NOT continued. If not blank, data will be continued, starting in columns 16-71 of the subsequent statements for a maximum of 3840 bytes. For SYSIN2 statement override.
73-80
Sequence indication
nnnnnnnn
322
COMPARE Statement
Table 77. COMPARE DATA Statement (continued) Column Notes: v If you code an L in column 3, the value in columns 5 through 8 is converted to binary and compared against the LL field of the returned segment. If you leave column 3 blank and the segment is not in a path call, then the value in columns 5 through 8 is used as the length of the comparison. v If you code column 4 with a V, P, or M, you must enter a value in columns 5 through 8. v If this is a path call comparison, code a P in column 4. The value in columns 5 through 8 must be the exact length of the fixed segment used in the path call. v If you specify the length of the segment, this length is used in the COMPARE and in the display. If you do not specify a length, DFSDDLT0 uses the shorter value for the length of the comparison and display of: The length of data supplied in the I/O area by IMS The number of DATA statements read times 56 Function Code Description
COMPARE AIB Statement

The COMPARE AIB statement is optional. You can use it to compare values returned to the AIB by IMS. Table 78 shows the format of the COMPARE AIB statement.
Table 78. COMPARE AIB Statement Column 1 2 Function Identifies control statement Hold compare option Code E H Description COMPARE statement. Hold COMPARE statement. See note for COMPARE AIB Statement. Reset hold condition for a single COMPARE statement. 3 4-6 7 8-11 12 13-16 17-72 73-80 Reserved AIB compare Reserved Return code Reserved Reason code Reserved Sequence indication nnnnnnnn For SYSIN2 statement override. xxxx Allow specified reason code only. xxxx Allow specified return code only. AIB Identifies an AIB compare.
Note for COMPARE AIB Statement: To execute the same COMPARE AIB after a series of calls, put an H in column 2. When you specify an H, the COMPARE statement executes after each call. The H COMPARE statement is particularly useful when comparing with the same status code on repeated calls. The H COMPARE statement stays in effect until another COMPARE AIB statement is read.
323
COMPARE Statement
COMPARE PCB Statement

The COMPARE PCB statement is optional. You can use it to compare values returned to the PCB by IMS or to print blocks or buffer pool. Table 79 shows the format of the COMPARE PCB statement.
Table 79. COMPARE PCB Statement Column 1 2 Function Identifies control statement Hold compare option Code E H Description COMPARE statement. Hold compare statement. Reset hold condition for a single COMPARE statement. 3 Snap dump options (if compare was unequal) 1 2 4 8 S Use default value. (You can change the default value or turn off the option by coding the value in an OPTION statement.) The complete I/O buffer pool. The entire region (batch regions only). The DL/I blocks. Terminate the job step on miscompare of DATA or PCB. To SNAP subpools 0 through 127. Requests for multiple SNAP dump options can be obtained by summing their respective hexadecimal values. If anything other than a blank, 1-9, A-F, or S is coded in column 3, the SNAP dump option is ignored. Ignore extended option. P S SNAP the complete buffer pool (batch). SNAP subpools 0 through 127 (batch). An area is never snapped twice. The SNAP option is a combination of columns 3 (SNAP dump option) and 4 (extended SNAP option). 5-6 7 8-9 Segment level Reserved Status code xx XX OK 10 11-18 Reserved Segment name User Identification xxxxxxxx Segment name for DB PCB compare. Logical terminal for I/O. Destination for ALT PCB. 19 20-23 24-71 or 24-31 Reserved Length of key Concatenated key User ID
Extended SNAP1 options
nn
'nn' is the segment level for COMPARE PCB. A leading zero is required.
Allow blank status code only. Allow specified status code only. Do not check status code. blank, GA, GC, or GK allowed.
nnnn
'nnnn' is length of the feedback key. Concatenated key feedback for DB PCB compare. User identification for TP PCB.
324
COMPARE Statement
Table 79. COMPARE PCB Statement (continued) Column 72 Function Continuation column x 73-80 Note: 1. SNAP is a Product-sensitive programming interface. Sequence indication nnnnnnnn Code Description If blank, key feedback is not continued. If not blank, key feedback is continued, starting in columns 16-71 of subsequent statements. For SYSIN2 statement override.
Blank fields are not compared to the corresponding field in the PCB, except for the status code field. (Blanks represent a valid status code.) To accept the status codes blank, GA, GC, or GK as a group, put OK in columns 8 and 9. To stop comparisons of status codes, put XX in columns 8 and 9. To execute the same compare after a series of calls, put an H in column 2. This executes the COMPARE statement after each call. This is particularly useful to compare to a blank status code only when loading a database. The H COMPARE statement stays in effect until another COMPARE PCB statement is read.
Examples of COMPARE DATA and COMPARE PCB Statements

COMPARE PCB Statement for Blank Status Code: The COMPARE PCB statement is coded blank. It checks a blank status code for the GU.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU 10101100 E 10101200
COMPARE PCB Statement for SSA Level, Status Code, Segment Name, Concatenated Key Length, and Concatenated Key: The COMPARE PCB statement is a request to compare the SSA level, a status code of OK (which includes blank, GA, GC, and GK), segment name of SEGA, concatenated key length of 0004, and a concatenated key of A100.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU E 01 OK SEGA 0004A100
COMPARE PCB Statement for SSA Level, Status Code, Segment Name, Concatenated Key Length, and Concatenated Key: The COMPARE PCB statement causes the job step to terminate based on the 8 in column 3 when any of the fields in the COMPARE PCB statement are not equal to the corresponding field in the PCB.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU 10105100 E 8 01 OK SEGK 0004A100 10105200
COMPARE PCB Statement for Status Code with Hold Compare: The COMPARE PCB statement is a request to compare the status code of OK (which includes blank, GA, GC, and GK) and hold that compare until the next COMPARE PCB statement. The compare of OK is used on GN following GU and is also used on a GN that has a request to be repeated six times.
325
COMPARE Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU SEGA (KEYA = A300) 20201100 L GN 20201300 EH OK 20201400 L 0006 GN 20201500
COMPARE DATA Statement for Fixed-Length Segment: The COMPARE DATA statement is a request to compare the data returned. 72 bytes of data are compared.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU E DATA A100A100A100A100A100A100A100A100A100A100A100A100A100A100X10102200 E A100A100A100A100 10102300
COMPARE DATA Statement for Fixed-Length Data for 64 Bytes: The COMPARE DATA statement is a request to compare 64 bytes of the data against the data returned.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU 10101600 E 0064 DATA A100A100A100A100A100A100A100A100A100A100A100A100A100A100X10101700 E A100A100B111B111 10101800
COMPARE DATA Statement for Fixed-Length Data for 72 Bytes: The COMPARE DATA statement is a request to compare 72 bytes of the data against the data returned.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L GU 10103900 E LP0072 DATA A100A100A100A100A100A100A100A100A100A100A100A100A100A100X10104000 E A100A100A100A100 10104100
COMPARE DATA Statement for Variable-Length Data of Multiple-Segments Data and Length Fields: The COMPARE DATA statement is a request to compare 36 bytes of the data against the data returned for segment 1 and 16 bytes of data for segment 2. It compares the length fields of both segments.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT D (DSS = DSS01) X38005500 L DJ (DJSS = DJSS01) X38005600 L QAJAXQAJ 38005700 L V0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38005800 L M0016 DATA QAJSS01*IQAJ** 38005850 L GHU D (DSS = DSS01) X38006000 DJ (DJSS = DJSS01) X38006100 QAJAXQAJ (QAJASS = QAJASS97) 38006200 E LV0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38006300 E LM0016 DATA QAJSS01*2QAJ** 38006350
COMPARE DATA Statement for Variable-Length Data of Multiple Segments with no Length Field COMPARE: The COMPARE DATA statement is a request to compare 36 bytes of the data against the data returned for segment 1 and 16 bytes of data for segment 2 with no length field compares of either segment.
326
COMPARE Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT D (DSS = DSS01) X38005500 L DJ (DJSS = DJSS01) X38005600 L QAJAXQAJ 38005700 L V0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38005800 L M0016 DATA QAJSS01*IQAJ** 38005850 L GHU D (DSS = DSS01) X38006000 DJ (DJSS = DJSS01) X38006100 QAJAXQAJ (QAJASS = QAJASS97) 38006200 E V0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38006300 M0016 DATA QAJSS01*2QAJ** 38006350
COMPARE DATA Statement for Variable-Length Data of Multiple Segments and One Length Field COMPARE: The COMPARE DATA statement is a request to compare 36 bytes of the data against the data returned for segment 1 and 16 bytes of data for segment 2. It compares the length field of segment 1 only.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< L ISRT D (DSS = DSS01) X38005500 L DJ (DJSS = DJSS01) X38005600 L QAJAXQAJ 38005700 L V0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38005800 L M0016 DATA QAJSS01*IQAJ** 38005850 L GHU D (DSS = DSS01) X38006000 DJ (DJSS = DJSS01) X38006100 QAJAXQAJ (QAJASS = QAJASS97) 38006200 E LV0036 DATA QSS02QASS02QAJSS01QAJASS97*IQAJA** *38006300 M0016 DATA QAJSS01*2QAJ** 38006350
IGNORE Statement
DFSDDLT0 ignores any statement with an N or a period (.) in column 1. You can use the N or . (period) to comment out a statement in either the SYSIN or SYSIN2 input streams. Using N or . (period) in a SYSIN2 input stream causes the SYSIN input stream to be ignored as well. See SYSIN2 DD Statement on page 336 for information on how to override SYSIN input. Table 80 gives the format of the IGNORE statement. An example of the statement follows.
Table 80. IGNORE Statement Column 1 2-72 73-80 Function Identifies control statement Ignored Sequence indication nnnnnnnn For SYSIN2 statement override. Code N or . Description IGNORE statement.
Example of IGNORE Statement Using N or .

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< . NOTHING IN THIS AREA WILL BE PROCESSED. ONLY THE SEQUENCE NUMBER 67101010 N WILL BE USED IF READ FROM SYSIN2 OR SYSIN. 67101020
OPTION Statement
Use the OPTION statement to override various default options. Use multiple OPTION statements if you cannot fit all the options you want in one statement. No continuation character is necessary. Once you set an option, it remains in effect until you specify another OPTION statement to change the first parameter. Table 81 on page 328 shows the format of the OPTION statement. An example follows.
327
OPTION Statement
Table 81. OPTION Statement Column 1 2 3-72 Function Identifies control statement Reserved Keyword parameters: ABORT= v 0 v 1 to 9999 LINECNT= SNAP1 10 to 99 x v Turns the ABORT parameter off. v Number of unequal compares before aborting job. Initial default is 5. Number of lines printed per page. Must be filled with zeros. Initial default 54. SNAP option default, when results of compare are unequal. To turn the SNAP option off, code 'SNAP='. See COMPARE PCB Statement on page 324 for the appropriate values for this parameter. (Initial default is 5 if this option is not coded. This causes the I/O buffer pool and the DL/I blocks to be dumped with a SNAP call.) Produce/do not produce dump if job abends. Default is NODUMP. v H v C v Hexadecimal representation for lower case characters. This is the initial default. v Character representation for lower case characters. STATCD/NOSTATCD Issue/do not issue an error message for the internal, end-of-job stat call that does not receive a blank or GA status code. NOSTATCD is the default. Issue/do not issue a DFSDDLT0 ABENDU0249 when an invalid status code is returned for any of the internal end-of-job stat calls in a batch environment. NOABU249 is the default. nnnnnnnn For SYSIN2 statement override. Code O Description OPTION statement (free-form parameter fields).
DUMP/NODUMP LCASE=
ABU249/NOABU249
73 - 80 Note:
Sequence indication
1. SNAP is a Product-sensitive programming interface.
OPTION statement parameters can be separated by commas.
Example of OPTION Control Statement

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< O ABORT=5,DUMP,LINECNT=54,SPA=4096,SNAP=5 67101010
PUNCH CTL Statement

The PUNCH CTL statement allows you to produce an output data set consisting of COMPARE PCB statements, COMPARE DATA statements, COMPARE AIB statements, other control statements (with the exceptions noted in Table 82 on page 329), or combinations of these statements. Table 82 on page 329 shows the format and keyword parameters for the PUNCH CTL statement.
328
PUNCH Statement
Table 82. PUNCH CTL Statement Column 1-3 4-9 10-13 Function Identifies control statement Reserved Punch control PUNC NPUN 14-15 16-72 Reserved Keyword parameters: OTHER Reproduces all input control statements except: v CTL (PUNCH) statements. v N or . (IGNORE) statements. v COMPARE statements. v CALL statements with functions of SKIP and START. Any control statements that appear between SKIP and START CALLs are not punched. (See SKIP/START (skipping) Control Statements on page 319). v CALL statements with functions of STAK and END. Control statements that appear between STAK and END CALLS are saved and then punched the number of times indicated in the STAK CALL. (See STAK/END (stacking) Control Statements on page 319). DATAL Create a full data COMPARE using all of the data returned to the I/O area. Multiple COMPARE statements and continuations are produced as needed. Create a single data COMPARE statement using only the first 56 bytes of data returned to the I/O area. Create a full PCB COMPARE using the complete key feedback area returned in the PCB. Multiple COMPARE statements and continuations are produced as needed. Begin punching (no default values). Stop punching (default value). Code CTL Description PUNCH statement.
DATAS
PCBL
329
PUNCH Statement
Table 82. PUNCH CTL Statement (continued) Column Function PCBS Code Description Create a single PCB COMPARE statement using only the first 48 bytes of the key feedback area returned in the PCB. If a GB status code is returned on a Fast Path call while in STAK, but prior to exiting STAK, this function issues or does not issue SYNC. 00000001 to 99999999. This is the starting sequence number to be used for the punched statements. Eight numeric bytes must be coded. INCR= 1 to 9999. Increment the sequence number of each punched statement by this value. Leading zeros are not required. AIB 73-80 Sequence indication nnnnnnnn Create an AIB COMPARE statement. For SYSIN2 statement override.
SYNC/NOSYNC
START=
To change the punch control options while processing a single DFSDDLT0 input stream, always use PUNCH CTL statements in pairs of PUNC and NPUN. One way to use the PUNCH CTL statement is as follows: 1. Code only the CALL statements for a new test. Do not code the COMPARE statements. 2. Verify that each call was executed correctly. 3. Make another run using the PUNCH CTL statement to have DFSDDLT0 merge the proper COMPARE statements and produce a new output data set that can be used as input for subsequent regression tests. You can also use PUNCH CTL if segments in an existing database are changed. The control statement causes DFSDDLT0 to produce a new test data set that has the correct COMPARE statements rather than you having to manually change the COMPARE statements. Parameters in the CTL statement must be the same length as described in Table 82, and they must be separated by commas.
330
PUNCH Statement
Example of PUNCH CTL Statement

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< CTL PUNC PCBS,DATAS,OTHER,START=00000010,INCR=0010 33212010 CTL NPUN 33212020
The DD statement for the output data set is labeled PUNCHDD. The data sets are fixed block with LRECL=80. Block size as specified on the DD statement is used. If not specified, the block size is set to 80. If the program is unable to open PUNCHDD, DFSDDLT0 issues abend 251.
Example of PUNCH CTL Statement for All Parameters

|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< CTL PUNC OTHER,DATAL,PCBL,START=00000001,INCR=1000,AIB 33212010
STATUS Statement
With the STATUS statement, you establish print options and name the PCB that you want subsequent calls to be issued against. Table 83 shows the format of the STATUS statement.
Table 83. STATUS Statement Column 1 2 Function Identifies control statement Output device option 1 A 3 Print comment option 1 2 4 Print AIB option 1 2 5 Print call option 1 2 6 7 Reserved Print compare option 1 2 8 9 Reserved Print PCB option 1 2 Do not print. Print for each call. Print only if compare done and unequal. Do not print. Print for each call. Print only if compare done and unequal. Code S Description STATUS statement. Use PRINTDD when in a DL/I region; use I/O PCB in MPP region. Use PRINTDD in MPP region if DD statement is provided; otherwise, use I/O PCB. Same as if 1, and disregard all other fields in this STATUS statement. Do not print. Print for each call. Print only if compare done and unequal. Do not print. Print for each call. Print only if compare done and unequal. Do not print. Print for each call. Print only if compare done and unequal.
331
STATUS Statement
Table 83. STATUS Statement (continued) Column 10 11 Function Reserved Print segment option 1 2 12 Set task and real time 1 2 13-14 15 Reserved PCB selection option 1 2 3 4 5 PCB name passed in columns 16-23 (use option 1). DBD name passed in columns 16-23 (use option 2). Relative DB PCB passed in columns 16-23 (use option 3). Relative PCB passed in columns 16-23 (use option 4). $LISTALL passed in columns 16-23 (use option 5). If column 15 is blank, DFSDDLT0 selects options 2 through 5 based on content of columns 16-23. Opt. 1 16-23 PCB selection PCB name alpha These columns must contain the name of the label on the PCB at PSBGEN, or the name specified on the PCBNAME= operand for the PCB at PSBGEN time. The default PCB is the first database PCB in the PSB. If columns 16-23 are blank, current PCB is used. If DBD name is specified, this must be the name of a database DBD in the PSB. When columns 16 through 18 are blank, columns (19-23) of this field are interpreted as the relative number of the DB PCB in the PSB. This number must be right-justified to column 23, but need not contain leading zeros. When columns 16 through 18 = 'TP ', columns (19-23) of this field are interpreted as the relative number of the PCB from the start of the PCB list. This number must be right-justified to column 23, but need not contain leading zeros. I/O PCB is always the first PCB in the PCB list in this program. Prints out all PCBs in the PSB for test script. Use print options to print this STATUS statement. 1 Do not use print options in this statement; print this STATUS statement. Do not print. Print for each call. Print only if compare done and unequal. Do not time Time each call. Time each call if compare done and unequal. Code Description
Opt. 2 16-23
PCB selection DBD name
alpha
Opt. 3 16-18 19-23
PCB selection Relative position of PCB in PSB
numeric
Opt. 4 16-18 19-23
PCB selection I/O PCB Relative position of PCB in PSB
TP numeric
Opt. 5 16-23 24
List all PCBs in the PSB Print status option
$LISTALL
332
STATUS Statement
Table 83. STATUS Statement (continued) Column Function Code 2 3 25-28 PCB processing option xxxx Description Do not print this STATUS statement but use print options in this statement. Do not print this STATUS statement and do not use print options in this statement. This is optional and is only used when two PCBs have the same name but different processing options. If not blank, it is used in addition to the PCB name in columns 16 through 23 to select which PCB in the PSB to use.
29 30-32
Reserved AIB interface AIB Indicates that the AIB interface is used and the AIB is passed rather than passing the PCB. (Passing the PCB is the default.) Note: When the AIB interface is used, the PCB must be defined at PSBGEN with PCBNAME=name. IOPCB is the PCB name used for all I/O PCBs. DFSDDLT0 recognizes that name when column 15 contains a 1 and columns 16 through 23 contain IOPCB.
33 37-72 73-80
Reserved Reserved Sequence indication nnnnnnnn For SYSIN2 statement override.
If DFSDDLT0 does not encounter a STATUS statement, all default print options (columns 3 through 12) are 2 and the default output device option (column 2) is 1. You can code a STATUS statement before any call sequence in the input stream, changing either the PCB to be referenced or the print options. The referenced PCB stays in effect until a subsequent STATUS statement selects another PCB. However, a call that must be issued against an I/O PCB (such as LOG) uses the I/O PCB for that call. After the call, the PCB changes back to the original PCB.
Examples of STATUS Statement

To Print Each CALL Statement: The following STATUS statement tells DFSDDLT0 to print these options: COMMENTS, CALL, COMPARE, PCB, and SEGMENT DATA for all calls.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S 1 1 1 1 1
To Print Each CALL Statement, Select a PCB: The following STATUS statements tell DFSDDLT0 to print the COMMENTS, CALL, COMPARE, PCB, and SEGMENT DATA options for all calls, and select a PCB. The 1 in column 15 is required for PCBNAME. If omitted, the PCBNAME is treated as a DBDNAME.
333
STATUS Statement
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S 1 1 1 1 1 1PCBNAME |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S 1 1 1 1 1 1PCBNAME AIB
To print each CALL statement, select PCB based on a DBD name: The following STATUS statements tell DFSDDLT0 to print the COMMENTS, CALL, COMPARE, PCB, and SEGMENT DATA options for all calls, and select a PCB by a DBD name. The 2 in column 15 is optional.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S 1 1 1 1 1 2DBDNAME |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S 1 1 1 1 1 2DBDNAME AIB
If you do not use the AIB interface, you do not need to change STATUS statement input to existing streams; existing call functions will work just as they have in the past. However, if you want to use the AIB interface, you must change the STATUS statement input to existing streams to include AIB in columns 30 through 32. The existing DBD name, Relative DB PCB, and Relative PCB will work if columns 30 through 32 contain AIB and the PCB has been defined at PSBGEN with PCBNAME=name.
WTO Statement
The WTO (Write to Operator) statement sends a message to the z/OS console without waiting for a reply. Table 84 shows the format for the WTO statement.
Table 84. WTO Statement Column 1-3 4 5-72 73-80 Function Identifies control statement Reserved Message to send Sequence indication nnnnnnnn Message to be written to the system console. For SYSIN2 statement override. Code WTO Description WTO statement.
Example of WTO Statement

This WTO statement sends a message to the z/OS console and continues the test stream.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< WTO AT A WTO WITHIN TEST STREAM --WTO NUMBER 1-- TEST STARTED
334
WTOR Statement
WTOR Statement
The WTOR (Write to Operator with Reply) statement sends a message to the z/OS system console and waits for a reply. Table 85 shows the format of the WTOR statement.
Table 85. WTOR Statement Column 1-4 5 6-72 73-80 Function Identifies control statement Reserved Message to send Sequence indication nnnnnnnn Message to be written to the system console. For SYSIN2 statement override. Code WTOR Description WTOR statement.
Example of WTOR Statement

This WTOR statement causes the test stream to hole until DFSDDLT0 receives a response from the z/OS console operator. Any response is valid.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< WTOR AT A WTOR WITHIN TEST STREAM - ANY RESPONSE WILL CONTINUE
JCL Requirements
This section defines the DD statements that DFSDDLT0 uses. Execution JCL depends on the installation data set naming standards as well as the IMS environment (batch or online). See Figure 54.
//SAMPLE JOB ACCOUNTING,NAME,MSGLEVEL=(1,1),MSGCLASS=3,PRTY=8 33001100 //GET EXEC PGM=DFSRRC00,PARM=DLI,DFSDDLT0,PSBNAME 33001200 //STEPLIB DD DSN=IMS.SDFSRESL,DISP=SHR 33001300 //IMS DD DSN=IMS2.PSBLIB,DISP=(SHR,PASS) 33001400 // DD DSN=IMS2.DBDLIB,DISP=(SHR,PASS) 33001500 //DDCARD DD DSN=DATASET,DISP=(OLD,KEEP) 33001600 //IEFRDER DD DUMMY 33001700 //PRINTDD DD SYSOUT=A 33001800 //SYSUDUMP DD SYSOUT=A 33001900 //SYSIN DD * 33002000 |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< U THIS IS PART OF AN EXAMPLE 33002100 S 1 1 1 1 1 PCB-NAME 33002200 L GU 33002300 /* //SYSIN2 DD * |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< ABEND 33002300 /* Figure 54. Example JCL Code for DD Statement Definition
Figure 55 on page 336 is an example of coding JCL for DFSDDLT0 in a BMP. Use of a procedure is optional and is only shown here as an example.
335
JCL Requirements
//SAMPLE JOB ACCOUNTING,NAME,MSGLEVEL=(1,1),MSGCLASS=A 00010047 //************************************************************* //* BATCH DL/I JOB TO RUN FOR RSR TESTING * //************************************************************* //BMP EXEC IMSBATCH,MBR=DFSDDLT0,PSB=PSBNAME //BMP.PRINTDD DD SYSOUT=A //BMP.PUNCHDD DD SYSOUT=B //BMP.SYSIN DD * U ***THIS IS PART OF AN EXAMPLE OF SYSIN DATA 00010000 S 1 1 1 1 1 1 00030000 L GU 00040000 L 0099 GN 00050000 /* |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< //BMP.SYSIN2 DD * U ***THIS IS PART OF AN EXAMPLE OF SYSIN2 DATA ******************* 00020000 ABEND 00050000 /* Figure 55. Example JCL Code for DFSDDLT0 in a BMP
SYSIN DD Statement
The data set specified by the SYSIN DD statement is the normal input data set for DFSDDLT0. When processing input data that is on direct-access or tape, you may want to override certain control statements in the SYSIN input stream or to add other control statements to it. You do this with a SYSIN2 DD statement and the control statement sequence numbers. Sequence numbers in columns 73 to 80 for SYSIN data are optional unless a SYSIN2 override is used. If a SYSIN2 override is used, follow the directions for using sequence numbers as described in SYSIN2 DD Statement.
SYSIN2 DD Statement
DFSDDLT0 does not require the SYSIN2 DD statement, but if it is present in the JCL, DFSDDLT0 will read and process the specified data sets. When using SYSIN2: v The SYSIN DD data set is the primary input. DFSDDLT0 attempts to insert the SYSIN2 control statements into the SYSIN DD data set. v You must code the control groups and sequence numbers properly in columns 73 to 80 or the merging process will not work. v Columns 73 and 74 indicate the control group of the statement. v Columns 75 to 80 indicate the sequence number of the statement. v Sequence numbers must be in numeric order within their control group. v Control groups in SYSIN2 must match the SYSIN control groups, although SYSIN2 does not have to use all the control groups used in SYSIN. DFSDDLT0 does not require that control groups be in numerical order, but the control groups in SYSIN2 must be in the same order as those in SYSIN. v When DFSDDLT0 matches a control group in SYSIN and SYSIN2, it processes the statements by sequence number. SYSIN2 statements falling before or after a SYSIN statement are merged accordingly. v If the sequence number of a SYSIN2 statement matches the sequence number of a SYSIN statement in its control group, the SYSIN2 overrides the SYSIN. v If the program reaches the end of SYSIN before it reaches the end of SYSIN2, it processes the records of SYSIN2 as if they were an extension of SYSIN.
336
JCL Requirements
v Replacement or merging occurs only during the current run. The original SYSIN data is not changed. v During merge, if one of the control statements contains blanks in columns 73 through 80, DFSDDLT0 discards the statement containing blanks, sends a message to PRINTDD, and continues the merge until end-of-file is reached.
PRINTDD DD Statement
The PRINTDD DD statement defines output data set for DFSDDLT0, including displays of control blocks using the SNAP call. It must conform to the z/OS SNAP data set requirements.
PUNCHDD DD Statement
The DD statement for the output data set is labeled PUNCHDD. The data sets are fixed block with LRECL=80. Block size as specified on the DD statement is used; if not specified, the block size is set to 80. If the program is unable to open PUNCHDD, DFSDDLT0 issues abend 251. Here is an example of the PUNCHDD DD statement.
//PUNCHDD DD SYSOUT=B
Using the PREINIT Parameter for DFSDDLT0 Input Restart

You use the DFSDDLT0 restart function to restart a DFSDDLT0 input stream within the same dependent region. The PREINIT parameter in the EXEC statement invokes the restart function. Code the PREINIT parameter of DFSMPR as PREINIT=xx, where xx is the two-character suffix of the DFSINTxx PROCLIB member. (PREINIT=DL refers to the default PROCLIB member.) The PREINIT process establishes a checkpoint field for each active IMS region. This field is updated with the sequence number of each GU call to an I/O PCB as it is processed. For this reason, sequence numbers are required for all such GU calls that are used. On a restart, if the checkpoint field contains a sequence number, the DFSDDLT0 stream starts at the next GU call to an I/O PCB following the sequence number in the checkpoint field; otherwise the DFSDDLT0 stream starts from the beginning. The DFSDDLSI module and the default IMS.PROCLIB member, DFSINTDL, are shipped with IMS and are installed as part of normal IMS installation. The following code shows examples of SYSIN/SYSIN2 and PREINIT.
//TSTPGM JOB CARD //DDLTTST EXEC DFSMPR,PREINIT=DL //MPP.SYSIN DD * |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< S11 1 1 1 1 TP 1 01000000 OPTIONS SNAP= ,ABORT=9999 01000010 U********************************************************************** 01000040 S11 1 1 1 1 TP 1 01000050 L GU 01000060 E OK 01000070 S11 1 1 1 1 DBPCBXXX 01000080 L GU 01000090 E DATA A INIT-LOAD UOW 01000100 E 01 ROOTSEG1 0008A 0004D 01000110 S11 1 1 1 1 TP 1 01000120 L ISRT 01000130 L Z0080 DATA -SYNC INTERVAL 1 SEG 1 -MESSAGE 1 X01000140 L P DATA 11111111111111111111111111111111111111111111111 01000150
337
JCL Requirements
L ISRT 01000160 L Z0080 DATA -SYNC INTERVAL 1 SEG 2 -END EOM 1 X01000170 L P DATA 11111111111111111111111111111111111111111111111 01000180 U********************************************************************** 01000190 U* ENDING FIRST SYNC INTERVAL 01000200 U********************************************************************** 01000210 L GU 01000220 E QC 01000230 L GU 01000240 E OK 01000250 S11 1 1 1 1 DBPCBXXX 01000260 WTO GETTING DATA BASE SEGMENT 1 FROM DBPCBXXX 01000270 L U GHU 01000280 E DATA INIT-LOAD UOW. 1 A.P. 1 01000290 E OK 01000300 L U0003 GN 01000310 E OK 01000320 S11 1 1 1 1 TP 1 01000330 L ISRT 01000340 L Z0080 DATA -SYNC INTERVAL 2 SEG 1 -MESSAGE 1 X01000350 L P DATA 22222222222222222222222222222222222222222222211 01000360 L ISRT 01000370 L Z0080 DATA -SYNC INTERVAL 2 SEG 2 -END EOM 1 X01000380 L P DATA 22222222222222222222222222222222222222222222211 01000390 U********************************************************************** 01000400 U* ENDING SECOND SYNC INTERVAL 01000410 U********************************************************************** 01000420 L GU 01000430 E QC 01000440 L GU 01000450 E OK 01000460 S11 1 1 1 1 DBPCBXXX 01000470 S11 1 1 1 1 TP 1 01000480 L ISRT 01000490 L Z0080 DATA -SYNC INTERVAL 3 SEG 1 -MESSAGE 1 X01000500 L P DATA 33333333333333333333333333333333333333333333311 01000510 L ISRT 01000520 L Z0080 DATA -SYNC INTERVAL 3 SEG 2 -END EOM 1 X01000530 L P DATA 33333333333333333333333333333333333333333333311 01000580 U********************************************************************** 01000590 U* ENDING THIRD SYNC INTERVAL 01000600 U********************************************************************** 01000610 L GU 01000620 E QC 01000630 //MPP.SYSIN2 DD * |---+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----< ABEND 01000430 /*
Notes for the SYSIN/SYSIN2 and PREINIT examples: 1. The PREINIT= parameter coded in the EXEC statement invokes the restart process. 2. When DFSDDLT0 starts processing, it substitutes the SYSIN2 ABEND statement for the statement in SYSIN with the same sequence number. (It is the GU call with sequence number 01000430.) 3. DFSDDLT0 begins with statement 01000000 and processes until it encounters the ABEND statement (statement number 01000430). The GU calls to the I/O PCB have already been tracked in the checkpoint field (statements 01000060, 01000220, and 01000240). 4. When DFSDDLT0 is rescheduled, it examines the checkpoint field and finds 01000240. DFSDDLT0 begins processing at the next GU call to the I/O PCB, statement 01000450.
338
JCL Requirements
If the statement currently numbered 01000240 did not have a sequence number, DFSDDLT0 would restart from statement 01000000 when it was rescheduled.
Execution of DFSDDLT0 in IMS Regions

DFSDDLT0 is designed to operate in a DL/I or BMP region but can be executed in an IFP or MPP region. In a BMP or DL/I region, the EXEC statement allows the program name to be different from the PSB name. There is no problem executing calls against any database in a BMP or DL/I region. In an MPP region, the program name must be the same as the PSB name. To execute a DFSDDLT0 program in an MPP region, you must give DFSDDLT0 the PSB name or an alias of the PSB named in the IMS definition. You can use a temporary step library. In an MPP region or a BMP region with an input transaction code specified in the EXEC statement, DFSDDLT0 normally gets input by issuing a GU and GNs to the I/O PCB. DFSDDLT0 issues GU and GN calls until it receives the No More Messages status code, QC. If there is a SYSIN DD statement and a PRINTDD DD statement in the dependent region, DFSDDLT0 reads input from SYSIN and SYSIN2, if present, and sends output to the PRINTDD. If the dependent region is an MPP region and the input stream does not cause a GU to be issued to the I/O PCB before encountering end-of-file from SYSIN, the program will implicitly do a GU to the I/O PCB to get the message that caused the program to be scheduled. If the input stream causes a GU to the I/O PCB and a No More Messages status code is received, this is treated as the end of file. When input is from the I/O PCB, you can send output to PRINTDD by coding a 1 or an A in column 2 of the STATUS statement. Because the input is in fixed form, it is difficult to key it from a terminal. To use DFSDDLT0 to test DL/I in a message region, execute another message program that reads control statements stored as a member of a partitioned set. Insert these control statements to an input transaction queue. IMS then schedules the program to process the transactions. This method allows you to use the same control statements to execute in any region type.
Explanation of DFSDDLT0 Return Codes

A non-zero return code from DFSDDLT0 indicates the number of unequal comparisons that occurred during that time. A return code of 0 (zero) from DFSDDLT0 does not necessarily mean that DFSDDLT0 executed without errors. There are several messages issued by DFSDDLT0 that do not change the return code, but do indicate some sort of error condition. This preserves the return code field for the unequal comparison count. If an error message was issued during the run, a message ERRORS WERE DETECTED WITHIN THE INPUT STREAM. REVIEW OUTPUT TO DETERMINE ERRORS. appears at the end of the DFSDDLT0 output. You must examine the output to ensure DFSDDLT0 executed as expected.
DFSDDLT0 Hints
This section describes loading a database, printing, retrieving, replacing, and deleting segments, regression testing, using a debugging aid, and verifying how a call is executed.
339
DFSDDLT0 Hints
Load a Database
Use DFSDDLT0 for loading only very small databases because you must to provide all the calls and data rather than have them generated. The following example shows CALL FUNCTION and CALL DATA statements that are used to load a database.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7---+-----< O SNAP= ,ABORT=0 S 1 2 2 1 1 L ISRT COURSE L DATA FRENCH L ISRT COURSE L DATA COBOL L ISRT CLASS L DATA 12 L ISRT CLASS L DATA 27 L ISRT STUDENT L DATA SMITH THERESE L ISRT STUDENT L DATA GRABOWSKY MARION
Print the Segments in a Database

Use either of the following sequences of control statements to print the segments in a database.
|---+----1----+----2----+----3----+----4----+----5----+----6----+----7---+-----< .* Use PRINTDD, print call, compare, and PCB if compare unequal .* Do 1 Get Unique call .* Hold PCB compare, End step if status code is not blank, GA, GC, GK .* Do 9,999 Get Next calls S 2 2 2 1 DBDNAME L GU EH8 OK L 9999 GN |---+----1----+----2----+----3----+----4----+----5----+----6----+----7---+-----< .* Use PRINTDD, print call, compare, and PCB if compare unequal .* Do 1 Get Unique call .* Hold PCB compare, Halt GN calls when status code is GB. .* Do 9,999 Get Next calls S 2 2 2 1 DBDNAME L GU EH OK L 9999 GN
Both examples request the GN to be repeated 9999 times. Note that the first example uses a COMPARE PCB of EH8 while the second uses a COMPARE PCB of EH. The difference between these two examples is that the first halts the job step the first time the status code is not blank, GA, GC, or GK. The second example halts repeating the GN and goes on to process any remaining DFSDDLT0 control statements when a GB status code is returned or the GN has been repeated 9999 times.
Retrieve and Replace a Segment

Use the following sequence of control statements to retrieve and replace a segment.
340
DFSDDLT0 Hints
|----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8---S 1 1 1 1 1 COURSEDB L GHU COURSE (TYPE =FRENCH) X CLASS (WEEK =27) X STUDENT (NAME =SMITH) L REPL L DATA SMITH THERESE
Delete a Segment
Use the following sequence of control statements to delete a segment.
|----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8---S 1 1 1 1 1 4 L GHU COURSE (TYPE =FRENCH) X CLASS *L X INSTRUC (NUMBER =444) L DLET
Do Regression Testing
DFSDDLT0 is ideal for doing regression testing. By using a known database, DFSDDLT0 can issue calls and then compare the results of the call to expected results using COMPARE statements. The program then can determine if DL/I calls are executed correctly. If you code all the print options as 2's (print only if comparisons done and unequal), only the calls not properly satisfied are displayed.
Use as a Debugging Aid

When debugging a program, you usually need a print of the DL/I blocks. You can snap the blocks to a log data set at appropriate times by using a COMPARE statement that has an unequal compare in it. You can then print the blocks from the log. If you need the blocks even though the call executed correctly, such as for the call before the failing call, insert a SNAP function in the CALL statement in the input stream.
Verify How a Call Is Executed

Because it is very easy to execute a particular call, you can use DFSDDLT0 to verify how a particular call is handled. This can be of value if you suspect DL/I is not operating correctly in a specific situation. You can issue the calls suspected of not executing properly and examine the results.
341
DFSDDLT0 Hints
342
Chapter 15. Adapter for REXX

The IMS adapter for REXX (REXXTDLI) provides an environment in which IMS users can interactively develop REXX EXECs under TSO/E (time-sharing option extensions) and execute them in IMS MPPs, BMPs, IFPs, or Batch regions. This product does not compete with DFSDDLT0 but is used as an adjunct. The IMS adapter for REXX provides an application programming environment for prototyping or writing low-volume transaction programs. The REXX environment executing under IMS has the same abilities and restrictions as those documented in the IBM TSO Extensions for MVS/REXX Reference. These few restrictions pertain to the absence of the TSO, ISPEXEC, and ISREDIT environments, and to the absence of TSO-specific functions such as LISTDS. You can add your own external functions to the environment as documented in the IBM TSO Extensions for MVS/REXX Reference. IMS calls the REXX EXEC using IRXJCL. When this method is used, Return Code 20 (RC20) is a restricted return code. Return Code 20 is returned to the caller of IRXJCL when processing was not successful, and the EXEC was not processed. A REXX EXEC runs as an IMS application and has characteristics similar to other IMS-supported programming languages, such as COBOL. Programming language usage (REXX and other supported languages) can be mixed in MPP regions. For example, a COBOL transaction can be executed after a REXX transaction is completed, or vice versa. The advantages of REXX are: v REXX is an easy-to-use interpretive language. v REXX does not require a special PSB generation to add an EXEC and run it because EXECs can run under a standard PSB (IVPREXX or one that is established by the user). v The REXX interface supports DL/I calls and provides these functions: Call tracing of DL/I calls, status, and parameters Inquiry of last DL/I call Extensive data mapping PCB specification by name or offset Obtaining and releasing storage Messaging through WTO, WTP, WTL, and WTOR The following system environment conditions are necessary to run REXX EXECs: v DFSREXX0 and DFSREXX1 must be in a load library accessible to your IMS dependent or batch region; for example, STEPLIB. v DFSREXX0 is stand-alone and must have the RENT option specified. v DFSREXX1 must be bound with DFSLI000 and DFSCPIR0 (for SRRCMIT and SRRBACK) and optionally, DFSREXXU. The options must be REUS, not RENT. v IVPREXX (copy of DFSREXX0 program) must be installed as an IMS transaction program. IVP (Installation Verification Program) installs the program. For more information, see REXX Transaction Programs on page 345.
| |
343
IMS Adapter for REXX

v The PSB must be defined as assembler language or COBOL. v SYSEXEC DD points to a list of data sets containing the REXX EXECs that will be run in IMS. You must put this DD in your IMS dependent or batch region JCL. v SYSTSPRT DD is used for REXX output, for example tracing, errors, and SAY instructions. SYSTSPRT DD is usually allocated as SYSOUT=A or another class, depending on installation, and must be put in the IMS dependent or batch region JCL. v SYSTSIN DD is used for REXX input because no console exists in an IMS dependent region, as under TSO. The REXX PULL statement is the most common use of SYSTSIN. The following topics provide additional information: v Sample Exit Routine (DFSREXXU) v Addressing Other Environments v REXX Transaction Programs on page 345 v REXXTDLI Commands on page 349 v REXXTDLI Calls on page 349 v REXXIMS Extended Commands on page 352 v Sample Execs Using REXXTDLI on page 364 Related Reading: For more information on SYSTSPRT and SYSTSIN, see IBM TSO Extensions for MVS/REXX Reference.
Sample Exit Routine (DFSREXXU)

| | | | | | | IMS provides a sample user exit routine that is used with the IMS Adapter for REXX. For a description of how to write the user exit routine see IMS Version 9: Customization Guide. The sample user exit routine checks to see if it is being called on entry. If so, the user exit routine sets the parameter list to the transaction code with no arguments and sets the start-up IMSRXTRC level to 2. The return code is set to 0. For the latest version of the DFSREXXU source code, see the IMS.ADFSSMPL distribution library; the member name is DFSREXXU.
Addressing Other Environments

Use the REXX ADDRESS instruction to change the destination of commands. The IMS Adapter for REXX functions through two host command environments: REXXTDLI and REXXIMS. Other host command environments can be accessed with an IMS EXEC as well. The z/OS environment is provided by TSO in both TSO and non-TSO address spaces. It is used to run other programs such as EXECIO for file I/O. IMS does not manage the z/OS EXECIO resources. An IMS COMMIT or BACKOUT, therefore, has no effect on these resources. Because EXECIO is not an IMS-controlled resource, no integrity is maintained. If integrity is an issue for flat file I/O, use IMS GSAM, which ensures IMS-provided integrity. If APPC/MVS is available (MVS 4.2 or higher), other environments can be used. The environments are: APPCMVS CPICOMM Used for z/OS-specific APPC interfacing Used for CPI Communications
344
Addressing Other Environments

LU62 Used for z/OS-specific APPC interfacing
Related Reading: For more information on addressing environments, see IBM TSO Extensions for MVS/REXX Reference.
REXX Transaction Programs

A REXX transaction program can use any PSB definition. The definition set up by the IVP for testing is named IVPREXX. A section of the IMS stage 1 definition is shown in the following example:
********************************************************************** * IVP APPLICATIONS DEFINITION FOR DB/DC, DCCTL * ********************************************************************** APPLCTN GPSB=IVPREXX,PGMTYPE=TP,LANG=ASSEM REXXTDLI SAMPLE TRANSACT CODE=IVPREXX,MODE=SNGL, X MSGTYPE=(SNGLSEG,NONRESPONSE,1)
This example uses a GPSB, but you could use any PSB that you have defined. The GPSB provides a generic PSB that has an TP PCB and a modifiable alternate PCB. It does not have any database PCBs. The language type of ASSEM is specified because no specific language type exists for a REXX application. Recommendation: For a REXX application, specify either assembler language or COBOL. IMS schedules transactions using a load module name that is the same as the PSB name being used for MPP regions or the PGM name for other region types. You must use this load module even though your application program consists of the REXX EXEC. The IMS adapter for REXX provides a load module for you to use. This module is called DFSREXX0. You can: v Copy to a steplib data set with the same name as the application PSB name. Use either a standard utility intended for copying load modules (such as IEBCOPY or SAS), or the Linkage Editor. v Use the Linkage Editor to define an alias for DFSREXX0 that is the same as the application PGM name. | | Example: Figure 56 shows a section from the PGM setup job that uses the binder to perform the copy function to the name IVPREXX. The example uses the IVP.
//* REXXTDLI SAMPLE - GENERIC APPLICATION DRIVER //* //LINK EXEC PGM=IEWL, // PARM=XREF,LIST,LET,SIZE=(192K,64K) //SYSPRINT DD SYSOUT=* //SDFSRESL DD DISP=SHR,DSN=IMS.SDFSRESL //SYSLMOD DD DISP=SHR,DSN=IMS1.PGMLIB //SYSUT1 DD UNIT=(SYSALLDA,SEP=(SYSLMOD,SYSLIN)), // DISP=(,DELETE,DELETE),SPACE=(CYL,(1,1)) //SYSLIN DD * INCLUDE SDFSRESL(DFSREXX0) ENTRY DFSREXX0 NAME IVPREXX(R) /* Figure 56. Using the Binder to Copy the Name IVPREXX
345

When IMS schedules an application transaction, the load module is loaded and given control. The load module establishes the REXX EXEC name as the PGM name with an argument of the Transaction Code (if applicable). The module calls a user exit routine (DFSREXXU) if it is available. The user exit routine selects the REXX EXEC (or a different EXEC to run) and can change the EXEC arguments, or do any other desired processing. Related Reading: For more information on the IMS adapter for REXX exit routine, see IMS Version 9: Customization Guide. Upon return from the user exit routine, the action requested by the routine is performed. This action normally involves calling the REXX EXEC. The EXEC load occurs using the SYSEXEC DD allocation. This allocation must point to one or more partitioned data sets containing the IMS REXX application programs that will be run as well as any functions written in REXX that are used by the programs. Standard REXX output, such as SAY statements and tracing, is sent to SYSTSPRT. This DD is required and can be set to SYSOUT=A. When the stack is empty, the REXX PULL statement reads from the SYSTSIN DD. In this way, you can conveniently provide batch input data to a BMP or batch region. SYSTSIN is optional; however, you will receive an error message if you issue a PULL from an empty stack and SYSTSIN is not allocated. Figure 57 shows the JCL necessary for MPP region that runs the IVPREXX sample EXEC.
//IVP32M11 EXEC PROC=DFSMPR,TIME=(1440), // AGN=IVP, AGN NAME // NBA=6, // OBA=5, // SOUT=*, SYSOUT CLASS // CL1=001, TRANSACTION CLASS 1 // CL2=000, TRANSACTION CLASS 2 // CL3=000, TRANSACTION CLASS 3 // CL4=000, TRANSACTION CLASS 4 // TLIM=10, MPR TERMINATION LIMIT // SOD=, SPIN-OFF DUMP CLASS // IMSID=IVP1, IMSID OF IMS CONTROL REGION // PREINIT=DC, PROCLIB DFSINTXX MEMBER // PWFI=Y PSEUDO=WFI //* //* ADDITIONAL DD STATEMENTS //* //DFSCTL DD DISP=SHR, // DSN=IVPSYS32.PROCLIB(DFSSBPRM) //DFSSTAT DD SYSOUT=* //* REXX EXEC SOURCE LOCATION //SYSEXEC DD DISP=SHR, // DSN=IVPIVP32.INSTALIB // DD DISP=SHR, // DSN=IVPSYS32.SDFSEXEC //* REXX INPUT LOCATION WHEN STACK IS EMPTY //SYSTSIN DD * /* //* REXX OUTPUT LOCATION //SYSTSPRT DD SYSOUT=* //* COBOL OUTPUT LOCATION //SYSOUT DD SYSOUT=* Figure 57. JCL Code Used to Run the IVPREXX Sample Exec
346
IMS Adapter for REXX Overview Diagram

Figure 58 shows the IMS adapter for REXX environment at a high level. This figure shows how the environment is structured under the IMS program controller, and some of the paths of interaction between the components of the environment.
Figure 58. IMS Adapter for REXX Logical Overview Diagram
IVPREXX Sample Application

Figure 57 on page 346 shows the JCL needed to use IVPREXX from an MPP region. This EXEC can also be run from message-driven BMPs or IFP regions. To use the IVPREXX driver sample program in a message-driven BMP or IFP environment, specify IVPREXX as the program name and PSB name in the IMS region program's parameter list. Specifying IVPREXX loads the IVPREXX load module, which is a copy of the DFSREXX0 front-end program. The IVPREXX program loads and runs an EXEC named IVPREXX that uses message segments sent to the transaction as arguments to derive the EXEC to call or the function to perform. Interactions with IVPREXX from an IMS terminal are shown in the following examples: v IVPREXX Example 1 v IVPREXX Example 2 on page 348 v IVPREXX Example 3 on page 348 v IVPREXX Example 4 on page 348
IVPREXX Example 1
Entry:
IVPREXX execname
or
IVPREXX execname arguments
Response:
347

EXEC execname ended with RC= x
IVPREXX Example 2
Entry:
IVPREXX LEAVE
Response:
Transaction IVPREXX leaving dependent region.
IVPREXX Example 3
Entry:
IVPREXX HELLOHELLO
Response:
One-to-eight character EXEC name must be specified.
IVPREXX Example 4
Entry:
IVPREXX
or
IVPREXX ?
Response:
TRANCODE TRANCODE TRANCODE TRANCODE EXECNAME <Arguments> LEAVE TRACE level ROLL Run specified EXEC Leave Dependent Region 0=None,1=Some,2=More,3=Full Issue ROLL call
When an EXEC name is supplied, all of the segments it inserts to the I/O PCB are returned before the completion message is returned. REXX return codes (RC) in the range of 20000 to 20999 are usually syntax or other REXX errors, and you should check the z/OS system console or region output for more details. Related Reading: For more information on REXX errors and messages, see IBM TSO Extensions for MVS/REXX Reference. Stopping an Infinite Loop: To stop an EXEC that is in an infinite loop, you can enter either of the following IMS commands from the master terminal or system console:
/STO REGION p1 ABDUMP p2 /STO REGION p1 CANCEL
In these examples, p1 is the region number and p2 is the TRANCODE that the EXEC is running under. Use the /DISPLAY ACTIVE command to find the region number. This technique is not specific to REXX EXECs and can be used on any transaction that is caught in an infinite loop. Related Reading: For more information about these commands and others to help in this situation, see IMS Version 9: Command Reference.
348
REXXTDLI Commands
REXXTDLI Commands
| | | | | This section contains REXX commands and describes how they apply to DL/I calls. The terms command and call can be used interchangeably when explaining the REXXTDLI environment. However, the term command is used exclusively when explaining the REXXIMS environment. For consistency, call is used when explaining DL/I, and command is used when explaining REXX. To issue commands in the IMS adapter for REXX environment, you must first address the correct environment. Two addressable environments are provided with the IMS adapter for REXX. The environments are as follows: REXXTDLI Used for standard DL/I calls, for example GU and ISRT. The REXXTDLI interface environment is used for all standard DL/I calls and cannot be used with REXX-specific commands. All commands issued to this environment are considered to be standard DL/I calls and are processed appropriately. A GU call for this environment could look like this:
Address REXXTDLI "GU MYPCB DataSeg"
REXXIMS
Used to access REXX-specific commands (for example, WTO and MAPDEF) in the IMS adapter for REXX environment. The REXXIMS interface environment is used for both DL/I calls and REXX-specific commands. When a command is issued to this environment, IMS checks to see if it is REXX-specific. If the command is not REXX-specific, IMS checks to see if it is a standard DL/I call. The command is processed appropriately. The REXX-specific commands, also called extended commands, are REXX extensions added by the IMS adapter for the REXX interface. A WTO call for this environment could look like this:
Address REXXIMS "WTO Message"
On entry to the scheduled EXEC, the default environment is z/OS. Consequently, you must either use ADDRESS REXXTDLI or ADDRESS REXXIMS to issue the IMS adapter for REXX calls. Related Reading: For general information on addressing environments, see IBM TSO Extensions for MVS/REXX Reference.
REXXTDLI Calls
dlicall parm1 parm2 ...
The format of a DL/I call varies depending on call type. The parameter formats for supported DL/I calls can be found in Chapter 11, DL/I Calls for Database Management, on page 219 and Chapter 12, DL/I Calls for System Services, on page 249. The parameters for the calls are case-independent, separated by one or more blanks, and are generally REXX variables. See Parameter Handling on page 350 for detailed descriptions.
Return Codes
If you use the AIBTDLI interface, the REXX RC variable is set to the return code from the AIB on the DL/I call.
349
REXXTDLI Commands
If you do not use the AIBTDLI interface, a simulated return code is returned. This simulated return code is set to zero if the PCB status code was GA, GK, or bb . If the status code had any other value, the simulated return code is X'900' or decimal 2304.
Parameter Handling
The IMS adapter for REXX performs some parameter setup for application programs in a REXX environment. This setup occurs when the application program uses variables or maps as the parameters. When the application uses storage tokens, REXX does not perform this setup. The application program must provide the token and parse the results just as a non-REXX application would. For a list of parameter types and definitions, see Table 86 on page 351. The REXXTDLI interface performs the following setup: v The I/O area retrieval for the I/O PCB is parsed. The LL field is removed, and the ZZ field is removed and made available by means of the REXXIMS(ZZ) function call. The rest of the data is placed in the specified variable or map. Use the REXX LENGTH() function to find the length of the returned data. v The I/O area building for the TP PCB or alternate PCB is done as follows: The appropriate LL field. The ZZ field from a preceding SET ZZ command or X'0000' if the command was not used. The data specified in the passed variable or map. v The I/O area processing for the SPA is similar to the first two items, except that the ZZ field is 4 bytes long. v The feedback area on the CHNG and SETO calls is parsed. The LLZZLL fields are removed, and the remaining data is returned with the appropriate length. v The parameters that have the LLZZ as part of their format receive special treatment. These parameters occur on the AUTH, CHNG, INIT, ROLS, SETO, and SETS calls. The LLZZ fields are removed when IMS returns data to you and added (ZZ is always X'0000') when IMS retrieves data from you. In effect, your application ignores the LLZZ field and works only with the data following it. v The numeric parameters on XRST and symbolic CHKP are converted between decimal and a 32-bit number (fullword) as required.
350
REXXTDLI Commands
Table 86. IMS Adapter for REXX Parameter Types and Definitions Type1 PCB Parameter Definition PCB Identifier specified as a variable containing one of the following: v PCB name as defined in the PSB generation on the PCBNAME= parameter. See IMS Version 9: Utilities Reference: System for more information on defining PCB names. The name can be from 1 to 8 characters long and does not have to be padded with blanks. If this name is given, the AIBTDLI interface is used, and the return codes and reason codes are acquired from that interface. v An AIB block formatted to DFSAIB specifications. This variable is returned with an updated AIB. v A # followed by PCB offset number (#1=first PCB). Example settings are: IOPCB=:"#1" ALTPCB=:"#2" DBPCB=:"#3" The IOAREA length returned by a database DL/I call defaults to 4096 if this notation is used. The correct length is available only when the AIBTDLI interface is used. In SSA Input variable. It can be specified as a constant, variable, *mapname2, or !token3. Input variable with an SSA (segment search argument). It can be specified as a constant, variable, *mapname2, or !token3. Output variable to store a result after a successful command. It can be specified as a variable, *mapname2, or !token3. Variable that contains input on entry and contains a result after a successful command. It can be specified as a variable, *mapname2, or !token3. Input constant. This command argument must be the actual value, not a variable containing the value.
Out
In/Out
Const Note:
1. The parameter types listed in Table 86 correspond to the types shown in Table 46 on page 220 and Table 50 on page 250, as well as to those shown in Table 87 on page 353. All parameters specified on DL/I calls are case independent except for the values associated with the STEM portion of the compound variable (REXX terminology for an array-like structure). A period (.) can be used in place of any parameter and is read as a NULL (zero length string) and written as a void (place holder). Using a period in place of a parameter is useful when you want to skip optional parameters. 2. For more information on *mapname, see MAPGET on page 357 and MAPPUT on page 358. 3. For more information on !token, see STORAGE on page 360.
Example DL/I Calls

The following example shows an ISRT call issued against the I/O PCB. It writes the message Hello World.
351
REXXTDLI Commands
IO = "IOPCB" /* IMS Name for I/O PCB */ OutMsg="Hello World" Address REXXTDLI "ISRT IO OutMsg" If RC\=0 Then Exit 12
In this example, IO is a variable that contains the PCB name, which is the constant IOPCB for the I/O PCB. If a non-zero return code (RC) is received, the EXEC ends (Exit) with a return code of 12. You can do other processing here. The next example gets a part from the IMS sample parts database. The part number is "250239". The actual part keys have a "02" prefix and the key length defined in the DBD is 17 bytes. The following example puts the segment into the variable called Part_Segment.
PartNum DB SSA Address = "250239" = "DBPCB01" = PARTROOT(PARTKEY = ||Left(02||PartNum,17)||) REXXTDLI "GU DB Part_Segment SSA"
Notes: v In a real EXEC, you would probably find the value for PartNum from an argument and would have to check the return code after the call. v The LEFT function used here is a built-in REXX function. These built-in functions are available to any IMS REXX EXEC. For more information on functions, see IBM TSO Extensions for MVS/REXX Reference. v The single quote (') and double quote (") are interchangeable in REXX, as long as they are matched. The IMS.SDFSISRC library includes the DFSSUT04 EXEC. You can use this EXEC to process any unexpected return codes or status codes. To acquire the status code from the last DL/I call issued, you must execute the IMSQUERY('STATUS') function. It returns the two character status code. If you use an EXEC that runs in both IMS and non-IMS environments, check to see if the IMS environment is available. You can check to see if the IMS environment is available in two ways: v Use the z/OS SUBCOM command and specify either the REXXTDLI or REXXIMS environments. The code looks like this:
Address MVS SUBCOM REXXTDLI If RC=0 Then Say "IMS Environment is Available." Else Say "Sorry, no IMS Environment here."
v Use the PARSE SOURCE instruction of REXX to examine the address space name (the 8th word). If it is running in an IMS environment, the token will have the value IMS. The code looks like this:
Parse Source . . . . . . . Token . If Token=IMS Then Say "IMS Environment is Available." Else Say "Sorry, no IMS Environment here."
Environment Determination
REXXIMS Extended Commands

The IMS adapter for REXX gives access to the standard DL/I calls and it supplies a set of extended commands for the REXX environment. These commands are listed in Table 87 and are available when you ADDRESS REXXIMS. DL/I calls are also available when you address the REXXIMS environment.
352

The following topics include additional information about REXX commands: v DLIINFO v IMSRXTRC on page 354 v MAPDEF on page 355 v MAPGET on page 357 v v v v v v v MAPPUT on page 358 SET on page 359 SRRBACK and SRRCMIT on page 360 STORAGE on page 360 WTO, WTP, and WTL on page 362 WTOR on page 362 IMSQUERY Extended Functions on page 363
Parameter Types Out [PCB] In Const In [Const] Const In Const Out Const In Out Out Const Const [In [Const] ] In In In In Out
1
Table 87. REXXIMS Extended Commands Command DLIINFO IMSRXTRC MAPDEF MAPGET MAPPUT SET SRRBACK SRRCMIT STORAGE WTO WTP WTL WTOR Note: 1. The parameter types listed correspond to the types shown in Table 86 on page 351. All parameters specified on DL/I calls are case-independent except for the values associated with the STEM portion of the compound variable (REXX terminology for an array-like structure). A period (.) can be used in place of any parameter and has the effect of a NULL (zero length string) if read and a void (place holder) if written. Use a period in place of a parameter to skip optional parameters.
DLIINFO
The DLIINFO call requests information from the last DL/I call or on a specific PCB. The following topics contain additional information: v Format on page 354 v Usage on page 354 v Example on page 354
353
Format
DLIINFO infoout pcbid
Call Name DLIINFO
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The infoout variable name is a REXX variable that is assigned the DL/I information. The pcbid variable name, when specified as described in Parameter Handling on page 350, returns the addresses associated with the specified PCB and its last status code. The format of the returned information is as follows: Word 1 2 3 4 5 6 7 Description Last DL/I call ('.' if N/A) Last DL/I PCB name (name or #number, '.' if N/A) Last DL/I AIB address in hexadecimal (00000000 if N/A) Last DL/I PCB address in hexadecimal (00000000 if N/A) Last DL/I return code (0 if N/A) Last DL/I reason code (0 if N/A) Last DL/I call status ('.' if blank or N/A)
Example
Address REXXIMS DLIINFO MyInfo /* Get Info Parse Var MyInfo DLI_Cmd DLI_PCB DLI_AIB_Addr DLI_PCB_Addr, DLI_RC DLI_Reason DLI_Status . */
Always code a period after the status code (seventh word returned) when parsing to allow for transparent additions in the future if needed. Words 3, 4, and 7 can be used when a pcbid is specified on the DLIINFO call.
IMSRXTRC
The IMSRXTRC command is used primarily for debugging. It controls the tracing action taken (that is, how much trace output through SYSTSPRT is sent to the user) while running a REXX program. v Format v Usage on page 355 v Example on page 355
Format
IMSRXTRC level
Call Name IMSRXTRC
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
354
Usage
The level variable name can be a REXX variable or a digit, and valid values are from 0 to 9. The initial value at EXEC start-up is 1 unless it is overridden by the user Exit. Traced output is sent to the DDNAME SYSTSPRT. See IMS Version 9: Customization Guide for more information on the IMS adapter for REXX exit routine. The IMSRXTRC command can be used in conjunction with or as a replacement for normal REXX tracing (TRACE). Level 0 1 2 3 4-7 8 Description Trace errors only. The previous level and trace DL/I calls, their return codes, and environment status (useful for flow analysis). All the previous levels and variable sets. All the previous levels and variable fetches (useful when diagnosing problems). All previous levels. All previous levels and parameter list to/from standard IMS language interface. See message DFS3179 in IMS Version 9: Messages and Codes, Volume 1. All previous levels.
Example
Address REXXIMS IMSRXTRC 3
IMSRXTRC is independent of the REXX TRACE instruction.
MAPDEF
The MAPDEF command makes a request to define a data mapping.
Format
MAPDEF mapname A REPLACE
A:
: variable C V B P Z length * length .digit
startpos
length *
Call Name MAPDEF
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
355
Usage
Data mapping is an enhancement added to the REXXIMS interface. Because REXX does not offer variable structures, parsing the fields from your database segments or MFS output maps can be time consuming, especially when data conversion is necessary. The MAPDEF, MAPGET, and MAPPUT commands allow simple extraction of most formatted data. v mapname is a 1- to 16-character case-independent name. v definition (A) is a variable containing the map definition. v REPLACE, if specified, indicates that a replacement of an existing map name is allowed. If not specified and the map name is already defined, an error occurs and message DFS3171E is sent to the SYSTPRT. The map definition has a format similar to data declarations in other languages, with simplifications for REXX. In this definition, you must declare all variables that you want to be parsed with their appropriate data types. The formiat is shown in A in the syntax diagram. Variable name: The variable name variable is a REXX variable used to contain the parsed information. Variable names are case-independent. If you use a STEM (REXX terminology for an array-like structure) variable, it is resolved at the time of use (at the explicit or implicit MAPGET or MAPPUT call time), and this can be very powerful. If you use an index type variable as the STEM portion of a compound variable, you can load many records into an array simply by changing the index variable. Map names or tokens cannot be substituted for variable names inside a map definition. Repositioning the internal cursor: A period (.) can be used as a variable place holder for repositioning the internal cursor position. In this case, the data type must be C, and the length can be negative, positive, or zero. Use positive values to skip over fields of no interest. Use negative lengths to redefine fields in the middle of a map without using absolute positioning. The data type values are: C V B Z P Character Variable Binary (numeric) Zoned Decimal (numeric) Packed Decimal (numeric)
All numeric data types can have a period and a number next to them. The number indicates the number of digits to the right of a decimal point when converting the number. Length value: The length value can be a number or an asterisk (*), which indicates that the rest of the buffer will be used. You can only specify the length value for data types C and V. Data type V maps a 2-byte length field preceding the data string, such that a when the declared length is 2, it takes 4 bytes. Valid lengths for data types are: C V 1 to 32767 bytes or * 1 to 32765 bytes or *
356

B Z P 1 to 4 bytes 1 to 12 bytes 1 to 6 bytes
If a value other than asterisk (*) is given, the cursor position is moved by that value. The startpos value resets the parsing position to a fixed location. If startpos is omitted, the column to the right of the previous map variable definition (cursor position) is used. If it is the first variable definition, column 1 is used. Note: A length of asterisk (*) does not move the cursor position, so a variable declared after one with a length of asterisk (*) without specifying a start column overlays the same definition.
Example
This example defines a map named DBMAP, which is used implicitly on a GU call by placing an asterisk (*) in front of the map name.
DBMapDef = RECORD C * :, /* NAME C 10 :, /* PRICE Z.2 6 :, /* CODE C 2 :, /* . C 25 :, /* CATEGORY B 1 /* Address REXXIMS MAPDEF DBMAP DBMapDef Pick up entire record Cols 1-10 hold the name Cols 11-16 hold the price Cols 11-16 hold the code Skip 25 columns Col 42 holds category */ */ */ */ */ */
. . .
Address REXXTDLI GU DBPCB *DBMAP /* Read and decode a segment */ If RC\=0 Then Signal BadCall /* Check for failure */ Say CODE /* Can now access any Map Variable*/
The entire segment retrieved on the GU call is placed in RECORD. The first 10 characters are placed in NAME, and the next 6 are converted from zoned decimal to EBCDIC with two digits to the right of the decimal place and placed in PRICE. The next 2 characters are placed in CODE, the next 25 are skipped, and the next character is converted from binary to EBCDIC and placed in CATEGORY. The 25 characters that are skipped are present in the RECORD variable.
MAPGET
The MAPGET command is a request to parse or convert a buffer into a specified data mapping previously defined with the MAPDEF command.
Format
MAPGET mapname buffer
Call Name MAPGET
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The mapname variable name specifies the data mapping to use. It is a 1- to 16-character case-independent name. The buffer variable name is the REXX variable containing the data to parse.
357

Map names can also be specified in the REXXTDLI calls in place of variable names to be set or written. This step is called an implicit MAPGET. Thus, the explicit (or variable dependent) MAPGET call can be avoided. To indicate that a Map name is being passed in place of a variable in the DL/I call, precede the name with an asterisk (*), for example, GU IOPCB *INMAP.
Examples
This example uses explicit support.
Address REXXTDLI GU DBPCB SegVar If RC=0 Then Signal BadCall /* Check for failure */ Address REXXIMS MAPGET DBMAP SegVar/* Decode Segment */ Say VAR_CODE /*Can now access any Map Variable */
This example uses implicit support.

Address REXXTDLI GU DBPCB *DBMAP If RC=0 Then Signal BadCall Say VAR_CODE /* Read and decode segment if read*/ /* Check for failure */ /* Can now access any Map Variable*/
If an error occurs during a MAPGET, message DFS3172I is issued. An error could occur when a Map is defined that is larger than the input segment to be decoded or during a data conversion error from packed or zoned decimal format. The program continues, and an explicit MAPGET receives a return code 4. However, an implicit MAPGET (on a REXXTDLI call, for example) does not have its return code affected. Either way, the failing variable's value is dropped by REXX.
MAPPUT
This MAPPUT command makes a request to pack or concatenate variables from a specified Data Mapping, defined by the MAPDEF command, into a single variable.
Format
MAPPUT mapname buffer
Call Name MAPPUT
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The mapname variable name specifies the data mapping to use, a 1- to 16-character case-independent name. The buffer variable name is the REXX variable that will contain the resulting value. Map names can also be specified in the REXXTDLI call in place of variable names to be fetched or read. This step is called an implicit MAPPUT and lets you avoid the explicit MAPPUT call. To indicate that a Map name is being passed in the DL/I call, precede the name with an asterisk (*), for example, ISRT IOPCB *OUTMAP. Note: If the data mapping is only partial and some fields in the record are not mapped to REXX variables, then the first field in the mapping should be a character type of length asterisk (*), as shown in the Example on page 357. This step is the only way to ensure that non-mapped (skipped) fields are not lost between the MAPGET and MAPPUT calls, whether they be explicit or implicit.
358
Examples
This example uses explicit support.
Address REXXTDLI GHU DBPCB SegVar SSA1 If RC\=0 Then Signal BadCall Address REXXIMS MAPGET DBMAP SegVar DBM_Total = DBM_Total + Deposit_Amount Address REXXIMS MAPPUT DBMAP SegVar REPL DBPCB SegVar If RC\=0 Then Signal BadCall /* /* /* /* /* /* /* Read segment Check for failure Decode Segment Adjust Mapped Variable Encode Segment Update Database Check for failure */ */ */ */ */ */ */
This example uses implicit support.

Address REXXTDLI GHU DBPCB *DBMAP SSA1 If RC\=0 Then Signal BadCall DBM_Total = DBM_Total + Deposit_Amount REPL DBPCB *DBMAP If RC\=0 Then Signal BadCall /* /* /* /* /* Read and decode segment if read */ Check for failure */ Adjust Mapped Variable */ Update Database */ Check for failure */
If an error occurs during a MAPPUT, such as a Map field defined larger than the variable's contents, then the field is truncated. If the variable's contents are shorter than the field, the variable is padded: Character (C) Character (V) Numeric (B,Z,P) Padded on right with blanks Padded on right with zeros Padded on the left with zeros
If a MAP variable does not exist when a MAPPUT is processed, the variable and its position are skipped. All undefined and skipped fields default to binary zeros. A null parameter is parsed normally. Conversion of non-numeric or null fields to numeric field results in a value of 0 being used and no error.
SET
The SET command resets AIB subfunction values and ZZ values before you issue a DL/I call.
Format
SET SUBFUNC variable ZZ variable
Call Name SET
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The SET SUBFUNC command sets the AIB subfunction used on the next DL/I call. This value is used only if the next REXXTDLI call passes a PCB name. If the call does pass a PCB name, the IMS adapter for REXX places the subfunction name (1 to 8 characters or blank) in the AIB before the call is issued. This value initially defaults to blanks and is reset to blanks on completion of any REXXTDLI DL/I call. The SET ZZ command is used to set the ZZ value used on a subsequent DL/I call. This command is most commonly used in IMS conversational transactions and terminal dependent applications to set the ZZ field to something other than the
359

default of binary zeros. Use the SET command before an ISRT call that requires other than the default ZZ value. For more explanation on ZZ processing, see Parameter Handling on page 350.
Examples
This example shows the SET SUBFUNC command used with the INQY call to get environment information.
IO="IOPCB" Func = "ENVIRON" Address REXXIMS "SET SUBFUNC Func" Address REXXTDLI "INQY IO EnviData" IMS_Identifier = Substr(EnviData,1,8) /* /* /* /* Sub-Function Value */ Set the value */ Make the DL/I Call */ Get IMS System Name*/
This example shows the SET ZZ command used with a conversational transaction for SPA processing.
Address REXXTDLI GU IOPCB SPA Hold_ZZ = IMSQUERY(ZZ) /* Get first Segment /* Get ZZ Field (4 bytes) */ */
. . .
Address REXXIMS SET ZZ Hold_ZZ Address REXXTDLI ISRT IOPCB SPA /* Set ZZ for SPA ISRT /* ISRT the SPA */ */
This example shows the SET ZZ command used for setting 3270 Device Characteristics Flags.
Bell_ZZ = 0040X Address REXXIMS SET ZZ Bell_ZZ Address REXXTDLI ISRT IOPCB Msg /* ZZ to Ring Bell on Term /* Set ZZ for SPA ISRT /* ISRT the Message */ */ */
SRRBACK and SRRCMIT

The Common Programming Interface Resource Recovery (CPI-RR) commands allow an interface to use the SAA resource recovery interface facilities for back-out and commit processing.
Format
SRRBACK return_code SRRCMIT return_code
Call Name SRRBACK, SRRCMIT
DB/DC X
DBCTL
DCCTL X
DB Batch
TM Batch
Usage
The return code from the SRR command is returned and placed in the return_code variable name as well as the REXX variable RC. For more information on SRRBACK and SRRCMIT, see IMS Version 9: Administration Guide: Transaction Manager and System Application Architecture Common Programming Interface: Resource Recovery Reference.
STORAGE
The STORAGE command allows the acquisition of system storage that can be used in place of variables for parameters to REXXTDLI and REXXIMS calls.
360
Format
STORAGE OBTAIN !token length KEEP BELOW RELEASE !token
Call Name STORAGE
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
Although REXX allows variables to start with characters (!) and (#), these characters have special meanings on some commands. When using the REXXTDLI interface, you must not use these characters as the starting characters of variables. The !token variable name identifies the storage, and it consists of an exclamation mark followed by a 1- to 16-character case-independent token name. The length variable name is a number or variable containing size in decimal to OBTAIN in the range 4 to 16777216 bytes (16 MB). The storage class has two possible override values, BELOW and KEEP, of which only one can be specified for any particular token. The BELOW function acquires the private storage below the 16 MB line. The KEEP function marks the token to be kept after this EXEC is terminated. The default action gets the storage in any location and frees the token when the EXEC is terminated. Use the STORAGE command to get storage to use on DL/I calls when the I/O area must remain in a fixed location (for example, Spool API) or when it is not desirable to have the LLZZ processing. For more information on LLZZ processing, see Parameter Handling on page 350. Once a token is allocated, you can use it in REXXTDLI DL/I calls or on the STORAGE RELEASE command. When using STORAGE: v When used on DL/I calls, none of the setup for LLZZ fields takes place. You must fill the token in and parse the results from it just as required by a non-REXX application. v You cannot specify both KEEP and BELOW on a single STORAGE command. v The RELEASE function is only necessary for tokens marked KEEP. All tokens not marked KEEP and not explicitly released by the time the EXEC ends are released automatically by the IMS adapter for REXX. v When you use OBTAIN, the entire storage block is initialized to 0. v The starting address of the storage received is always on the boundary of a double word. v You cannot re-obtain a token until RELEASE is used or the EXEC that obtained it, non-KEEP, terminates. If you try, a return code of -9 is given and the error message DFS3169 is issued. v When KEEP is specified for the storage token, it can be accessed again when this EXEC or another EXEC knowing the token's name is started in the same IMS region. v Tokens marked KEEP are not retained when an ABEND occurs or some other incident occurs that causes region storage to be cleared. It is simple to check if the block exists on entry with the IMSQUERY(!token) function. For more information, see IMSQUERY Extended Functions on page 363.
361
Example
This example shows how to use the STORAGE command with Spool API.
/* Get 4K Buffer below the line for Spool API Usage */ Address REXXIMS STORAGE OBTAIN !MYTOKEN 4096 BELOW /* Get Address and length (if curious) */ Parse Value IMSQUERY(!MYTOKEN) With My_Token_Addr My_Token_Len. Address REXXIMS SETO ALTPCB !MYTOKEN SETOPARMS SETOFB
. . .
Address REXXIMS STORAGE RELEASE !MYTOKEN
WTO, WTP, and WTL

The WTO command is used to write a message to the operator. The WTP command is used to write a message to the program (WTO ROUTCDE=11). The WTL command is used to write a message to the console log.
Format
WTO message WTP message WTL message
Call Name WTO, WTP, WTL
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The message variable name is a REXX variable containing the text that is stored displayed in the appropriate place.
Example
This example shows how to write a simple message stored the REXX variable MSG.
Msg = Sample output Address REXXIMS WTO Address REXXIMS WTP Address REXXIMS WTL message. Msg Msg Msg /* /* /* /* Build Message Tell Operator Tell Programmer Log It */ */ */ */
WTOR
The WTOR command requests input or response from the z/OS system operator.
Format
WTOR message response
Call Name WTOR
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The message variable name is a REXX variable containing the text that will be displayed on the z/OS console. The operator's response is placed in the REXX variable signified by the response variable name.
362

Attention: This command hangs the IMS region in which it is running until the operator responds.
Example
This example prompts the operator to enter ROLL or CONT on the z/OS master or alternate console. Once the WTOR is answered, the response is placed in the REXX variable name response, and the EXEC will continue and process the IF statement appropriately.
Msg = Should I ROLL or Continue. Reply "ROLL" or "CONT" Address REXXIMS WTOR Msg Resp /* Ask Operator */ If Resp = ROLL Then /* Tell Programmer */ Address REXXTDLI ROLL /* Roll Out of this */
IMSQUERY Extended Functions

The IMSQUERY function is available to query certain IMS information either on the environment or on the prior DL/I call.
Format
IMSQUERY ( FEEDBACK IMSRXTRC REASON SEGLEVEL SEGNAME STATUS TRANCODE USERID ZZ !token )
Call Name IMSQUERY
DB/DC X
DBCTL X
DCCTL X
DB Batch X
TM Batch X
Usage
The format of the function call is: IMSQUERY(Argument) where Argument is one of the following values: Argument FEEDBACK IMSRXTRC REASON SEGLEVEL SEGNAME STATUS Description of Data Returned FEEDBACK area from current PCB. Current IMSRXTRC trace level #. Reason code from last call (from AIB if used on last REXXTDLI type call). Segment level from current PCB (Last REXXTDLI call must be against a DB PCB, or null is returned). Segment name from current PCB (Last REXXTDLI call must be against a DB PCB, or null is returned). IMS status code from last executed REXXTDLI call (DL/I call). This argument is the two character status code from the PCB. Current transaction code being processed, if available.
TRANCODE
363

USERID Input terminal's user ID, if available. If running in a non-message-driven region, the value is dependent on the specification of the BMPUSID= keyword in the DFSDCxxx PROCLIB member: v If BMPUSID=USERID is specified, the value from the USER= keyword on the JOB statement is used. v If USER= is not specified on the JOB statement, the program's PSB name is used. v If BMPUSID=PSBNAME is specified, or if BMPUSID= is not specified at all, the program's PSB name is used. ZZ ZZ (of LLZZ) from last REXXTDLI command. This argument can be used to save the ZZ value after you issue a GU call to the I/O PCB when the transaction is conversational. Address (in hexadecimal) and length of specified token (in decimal), separated by a blank.
!token
This value can be placed in a variable or resolved from an expression. In these cases, the quotation marks should be omitted as shown below:
Token_Name="!MY_TOKEN" AddrInfo=IMSQUERY(Token_Name) /* or */ AddrInfo=IMSQUERY("!MY_TOKEN")
Although the function argument is case-independent, no blanks are allowed within the function argument. You can use the REXX STRIP function on the argument, if necessary. IMSQUERY is the preferred syntax, however REXXIMS is supported and can be used, as well.
Example
If REXXIMS(STATUS)=GB Then Signal End_Of_DB . . . Hold_ZZ = IMSQUERY(ZZ) /* Get current ZZ field*/ . . . Parse Value IMSQUERY(!MYTOKEN) With My_Token_Addr My_Token_Len .
Related Reading: For information on the IMS adapter for REXX exit routine, see IMS Version 9: Customization Guide.
Sample Execs Using REXXTDLI

| | This chapter shows samples of REXX execs that use REXXTDLI to access IMS services. The example sets are designed to highlight various features of writing IMS applications in REXX. The samples are simplified and might not reflect actual usage (for example, they do not use databases). The PART exec database access example is a set of three execs that access the PART database, which is built by the IMS installation verification program (IVP). The first two execs in this example, PARTNUM and PARTNAME, are extensions of the PART transaction that runs the program DFSSAM02, which is supplied with IMS
364
Sample Execs Using REXXTDLI

as part of IVP. The third exec is the DFSSAM01 exec supplied with IMS and is an example of the use of EXECIO within an exec.
SAY Exec: For Expression Evaluation

Figure 59 is a listing of the SAY exec. SAY evaluates an expression supplied as an argument and displays the results. The REXX command INTERPRET is used to evaluate the supplied expression and assign it to a variable. Then that variable is used in a formatted reply message.
/* EXEC TO DO CALCULATIONS */ Address REXXTDLI Arg Args If Args= Then Msg=SUPPLY EXPRESSION AFTER EXEC NAME. Else Do Interpret X=Args /* Evaluate Expression */ Msg=EXPRESSION: Args = X End ISRT IOPCB MSG Exit RC Figure 59. Exec To Do Calculations
This exec shows an example of developing applications with IMS Adapter for REXX. It also shows the advantages of REXX, such as dynamic interpretation, which is the ability to evaluate a mathematical expression at run-time. A PDF EDIT session is shown in Figure 60. This figure shows how you can enter a new exec to be executed under IMS.
EDIT ---- USER.PRIVATE.PROCLIB(SAY) - 01.03 ------------------ COLUMNS 001 072 COMMAND ===> SCROLL ===> PAGE ****** ***************************** TOP OF DATA ****************************** 000001 /* EXEC TO DO CALCULATIONS */ 000002 Address REXXTDLI 000003 Arg Args 000004 If Args= Then 000005 Msg=SUPPLY EXPRESSION AFTER EXEC NAME. 000006 Else Do 000007 Interpret X=Args /* Evaluate Expression */ 000008 Msg=EXPRESSION: Args = X 000009 End 000010 000011 ISRT IOPCB MSG 000012 Exit RC ****** **************************** BOTTOM OF DATA ****************************
Figure 60. PDF EDIT Session on the SAY Exec
To execute the SAY exec, use IVPREXX and supply an expression such as:
IVPREXX SAY 5*5+7
This expression produces the output shown in Figure 61.

EXPRESSION: 5*5+7 = 32 EXEC SAY ended with RC= 0
Figure 61. Example Output from the SAY Exec
365
PCBINFO Exec
PCBINFO Exec: Display Available PCBs in Current PSB

The PCB exec maps the PCBs available to the exec, which are the PCBs for the executing PSB. The mapping consists of displaying the type of PCB (IO, TP, or DB), the LTERM or DBD name that is associated, and other useful information. Mapping displays this information by using the PCB function described in DLIINFO on page 353. Example output screens are shown in Figure 62 and Figure 63. The listing is shown in Figure 64 on page 367. PCB mappings are created by placing DFSREXX0 in an early concatenation library and renaming it to an existing application with a PSB/DBD generation.
IMS PCB System Information Exec: PCBINFO System Date: 09/26/92 Time: 15:52:15 PCB # 1: Type=IO, LTERM=T3270LC Date=91269 Time=1552155 PCB # 2: Type=TP, LTERM=* NONE * PCB # 3: Type=TP, LTERM=* NONE * PCB # 4: Type=TP, LTERM=CTRL PCB # 5: Type=TP, LTERM=T3275 EXEC PCBINFO ended with RC= 0 Status= Status=AD Status= Status= Status= UserID= OutDesc=DFSMO2
Figure 62. Example Output of PCBINFO Exec on a PSB without Database PCBs.
IMS PCB System Information Exec: PCBINFO System Date: 09/26/92 Time: 15:53:34 PCB # 1: Type=IO, LTERM=T3270LC Status= Date=89320 Time=1553243 PCB # 2: Type=DB, DBD =DI21PART Status= EXEC PCBINFO ended with RC= 0 UserID= Level=00 Opt=G OutDesc=DFSMO2
Figure 63. Example Output of PCBINFO Exec on a PSB with a Database PCB.
366
PCBINFO Exec
/* REXX EXEC TO SHOW SYSTEM LEVEL INFO */ Address REXXTDLI Arg Dest . WTO=(Dest=WTO) Call SayIt IMS PCB System Information Exec: PCBINFO Call SayIt System Date: Date(U) Time: Time() Call Sayit /* A DFS3162 message is given when this exec is run because it does */ /* not know how many PCBs are in the list and it runs until it gets */ /* an error return code. Note this does not show PCBs that are */ /* available to the PSB by name only, in other words, not in the PCB list. Msg=PCBINFO: Error message normal on DLIINFO. WTP MSG Do i=1 by 1 until Result=LAST Call SayPCB i End Exit 0 SayPCB: Procedure Expose WTO Arg PCB DLIINFO DLIINFO #PCB /* Get PCB Address */ If rc<0 Then Return LAST /* Invalid PCB Number */ Parse Var DLIInfo . . AIBAddr PCBAddr . PCBINFO=Storage(PCBAddr,255) /* Read PCB */ DCPCB=(Substr(PCBInfo,13,1)=00x) /* Date Field, must be DC PCB */ If DCPCB then Do Parse Value PCBInfo with, LTERM 9 . 11 StatCode 13 CurrDate 17 CurrTime 21, InputSeq 25 OutDesc 33 UserID 41 If LTERM= then LTERM=* NONE * CurrDate=Substr(c2x(CurrDate),3,5) CurrTime=Substr(c2x(CurrTime),1,7) If CurrDate\=000000 then Do Call SayIt PCB #Right(PCB,2): Type=IO, LTERM=LTERM, Status=StatCode UserID=UserID OutDesc=OutDesc Call SayIt Date=CurrDate Time=CurrTime End Else Call SayIt PCB #Right(PCB,2): Type=TP, LTERM=LTERM, Status=StatCode End Else Do Parse Value PCBInfo with, DBDName 9 SEGLev 11 StatCode 13 ProcOpt 17 . 21 Segname . 29, KeyLen 33 NumSens 37 KeyLen = c2d(KeyLen) NumSens= c2d(NumSens) Call SayIt PCB #Right(PCB,2): Type=DB, DBD =DBDName, Status=StatCode Level=SegLev Opt=ProcOpt End Return SayIt: Procedure Expose WTO Parse Arg Msg If WTO Then WTO MSG Else ISRT IOPCB MSG Return Figure 64. PCBINFO Exec Listing
*/
367
PART Execs
PART Execs: Database Access Examples

This set of execs accesses the PART database shipped with IMS. These execs demonstrate fixed-record database reading, SSAs, and many REXX functions. The PART database execs (PARTNUM, PARTNAME, and DFSSAM01) are described in this section. The PARTNUM exec is used to show part numbers that begin with a number equal to or greater than the number you specify. An example output screen is shown in Figure 65. To list part numbers beginning with the number 300 or greater, enter the command:
PARTNUM 300
All part numbers that begin with a 300 or larger numbers are listed. The listing is shown in Figure 67 on page 369.
IMS Parts DATABASE Transaction System Date: 02/16/92 Time: 23:28:41 Request: Display 5 Parts with Part_Number >= 300 1 Part=3003802 Desc=CHASSIS 2 Part=3003806 Desc=SWITCH 3 Part=3007228 Desc=HOUSING 4 Part=3008027 Desc=CARD FRONT 5 Part=3009228 Desc=CAPACITOR EXEC PARTNUM ended with RC= 0
Figure 65. Example Output of PARTNUM Exec
PARTNAME is used to show part names that begin with a specific string of characters. To list part names beginning with TRAN, enter the command:
PARTNAME TRAN
All part names that begin with TRAN are listed on the screen. The screen is shown in Figure 66. The listing is shown in Figure 68 on page 370.
IMS Parts DATABASE Transaction System Date: 02/16/92 Time: 23:30:09 Request: Display 5 Parts with Part Name like TRAN 1 Part=250239 Desc=TRANSISTOR 2 Part=7736847P001 Desc=TRANSFORMER 3 Part=975105-001 Desc=TRANSFORMER 4 Part=989036-001 Desc=TRANSFORMER End of DataBase reached before 5 records shown. EXEC PARTNAME ended with RC= 0
Figure 66. Example Output of PARTNAME Exec
The DFSSAM01 exec is used to load the parts database. This exec is executed in batch, is part of the IVP, and provides an example of EXECIO usage in an exec. Related Reading: For details, see IMS Version 9: Installation Volume 1: Installation Verification.
368
PART Execs
PARTNUM Exec: Show Set of Parts Near a Specified Number

Requirement: Figure 67is designed to be run by the IVPREXX exec with PSB=DFSSAM02.
/* REXX EXEC TO SHOW A SET OF PARTS NEAR A SPECIFIED NUMBER /* Designed to be run by the IVPREXX exec with PSB=DFSSAM02 /* Syntax: IVPREXX PARTNUM string <start#> Address REXXTDLI IOPCB=IOPCB /* PCB Name */ DataBase=#2 /* PCB # */ RootSeg_Map = PNUM C 15 3 : DESCRIPTION C 20 27 MAPDEF ROOTSEG ROOTSEG_MAP Call SayIt IMS Parts DATABASE Transaction Call SayIt System Date: Date(U) Time: Time() Call Sayit Arg PartNum Segs . If \DataType(Segs,W) then Segs=5 /* default view amount */ */ */ */
PartNum=Left(PartNum,15) /* Pad to 15 with Blanks */ If PartNum= then Call Sayit Request: Display first Segs Parts in the DataBase Else Call Sayit Request: Display Segs Parts with Part_Number >= PartNum SSA1=PARTROOT(PARTKEY >=02PartNum) GU DATABASE *ROOTSEG SSA1 Status=IMSQUERY(STATUS) If Status=GE then Do /* Segment Not Found */ Call Sayit No parts found with larger Part_Number Exit 0 End Do i=1 to Segs While Status= Call Sayit Right(i,2) Part=PNum Desc=Description GN DATABASE *ROOTSEG SSA1 Status=IMSQUERY(STATUS) End If Status=GB then Call SayIt End of DataBase reached before Segs records shown. Else If Status\= then Signal BadCall Call Sayit Exit 0 SayIt: Procedure Expose IOPCB Parse Arg Msg ISRT IOPCB MSG If RC\=0 then Signal BadCall Return BadCall: DLIINFO INFO Parse Var Info Call PCB . . . . Status . Msg = Unresolved Status Code Status, on Call on PCB PCB ISRT IOPCB MSG Exit 99 Figure 67. PARTNUM Exec: Show Set of Parts Near a Specified Number
PARTNAME Exec: Show a Set of Parts with a Similar Name

Requirement: The REXX exec shown in Figure 68 on page 370 is designed to be run by the IVPREXX exec with PSB=DFSSAM02.
369
PART Execs
/* REXX EXEC TO SHOW ALL PARTS WITH A NAME CONTAINING A STRING /* Designed to be run by the IVPREXX exec with PSB=DFSSAM02 /* Syntax: IVPREXX PARTNAME string <#parts> Arg PartName Segs . Address REXXIMS Term =IOPCB /* PCB Name */ DataBase=DBPCB01 /* PCB Name for Parts Database */ Call SayIt IMS Parts DATABASE Transaction Call SayIt System Date: Date(U) Time: Time() Call Sayit If \DataType(Segs,W) & Segs\=* then Segs=5 If PartName= then Do Call Sayit Please supply the first few characters of the part name Exit 0 End Call Sayit Request: Display Segs Parts with Part Name like PartName SSA1=PARTROOT GU DATABASE ROOT_SEG SSA1 Status=REXXIMS(STATUS) i=0 Do While RC=0 & (i<Segs | Segs=*) Parse Var Root_Seg 3 PNum 18 27 Description 47 GN DATABASE ROOT_SEG SSA1 Status=REXXIMS(STATUS) If RC\=0 & Status\=GB Then Leave If Index(Description,PartName)=0 then Iterate i=i+1 Call Sayit Right(i,2)) Part=PNum Desc=Description End If RC\=0 & Status\=GB Then Signal BadCall If i<Segs & Segs\=* then Call SayIt End of DataBase reached before Segs records shown. Call Sayit Exit 0 SayIt: Procedure Expose Term Parse Arg Msg ISRT Term MSG If RC\=0 then Signal BadCall Return BadCall: Call "DFSSUT04" Term Exit 99 Figure 68. PARTNAME Exec: Show Parts with Similar Names */ */ */
DFSSAM01 Exec: Load the Parts Database

For the latest version of the DFSSAM01 source code, see the IMS.ADFSEXEC distribution library; member name is DFSSAM01.
DOCMD: IMS Commands Front End

DOCMD is an automatic operator interface (AOI) transaction program that issues IMS commands and allows dynamic filtering of their output. The term dynamic means that you use the headers for the command as the selectors (variable names) in the filter expression (Boolean expression resulting in 1 if line is to be displayed and 0 if it is not). This listing is shown in Figure 75 on page 373.
370
DOCMD
Not all commands are allowed through transaction AOI, and some setup needs to be done to use this AOI. Related Reading: See Security Considerations for Automated Operator Commands in IMS Version 9: Administration Guide: System for more information. Some examples of DOCMD are given in Figure 69, Figure 70, Figure 71, Figure 72 on page 372, Figure 73 on page 372, and Figure 74 on page 372.
Please supply an IMS Command to execute. EXEC DOCMD ended with RC= 0
Figure 69. Output from = > DOCMD

Headers being shown for command: /DIS NODE ALL Variable (header) #1 = RECTYPE Variable (header) #2 = NODE_SUB Variable (header) #3 = TYPE Variable (header) #4 = CID Variable (header) #5 = RECD Variable (header) #6 = ENQCT Variable (header) #7 = DEQCT Variable (header) #8 = QCT Variable (header) #9 = SENT EXEC DOCMD ended with RC= 0
Figure 70. Output from = > DOCMD /DIS NODE ALL;?

Selection criteria =>CID>0<= Command: /DIS NODE ALL NODE_SUB TYPE CID RECD ENQCT DEQCT QCT SENT L3270A 3277 01000004 5 19 19 0 26 IDLE CON L3270C 3277 01000005 116 115 115 0 122 CON Selected 2 lines from 396 lines. DOCMD Executed 402 DL/I calls in 2.096787 seconds. EXEC DOCMD ended with RC= 0
Figure 71. Output from = > DOCMD /DIS NODE ALL;CID>0
371
DOCMD
Selection criteria =>TYPE=SLU2<= Command: /DIS NODE ALL NODE_SUB TYPE CID RECD ENQCT DEQCT QCT SENT WRIGHT SLU2 00000000 0 0 0 0 0 IDLE Q3290A SLU2 00000000 0 0 0 0 0 IDLE Q3290B SLU2 00000000 0 0 0 0 0 IDLE Q3290C SLU2 00000000 0 0 0 0 0 IDLE Q3290D SLU2 00000000 0 0 0 0 0 IDLE V3290A SLU2 00000000 0 0 0 0 0 IDLE V3290B SLU2 00000000 0 0 0 0 0 IDLE H3290A SLU2 00000000 0 0 0 0 0 IDLE H3290B SLU2 00000000 0 0 0 0 0 IDLE E32701 SLU2 00000000 0 0 0 0 0 IDLE E32702 SLU2 00000000 0 0 0 0 0 IDLE E32703 SLU2 00000000 0 0 0 0 0 IDLE E32704 SLU2 00000000 0 0 0 0 0 IDLE E32705 SLU2 00000000 0 0 0 0 0 IDLE ADLU2A SLU2 00000000 0 0 0 0 0 IDLE ADLU2B SLU2 00000000 0 0 0 0 0 IDLE ADLU2C SLU2 00000000 0 0 0 0 0 IDLE ADLU2D SLU2 00000000 0 0 0 0 0 IDLE ADLU2E SLU2 00000000 0 0 0 0 0 IDLE ADLU2F SLU2 00000000 0 0 0 0 0 IDLE ADLU2X SLU2 00000000 0 0 0 0 0 IDLE ENDS01 SLU2 00000000 0 0 0 0 0 IDLE ENDS02 SLU2 00000000 0 0 0 0 0 IDLE ENDS03 SLU2 00000000 0 0 0 0 0 IDLE ENDS04 SLU2 00000000 0 0 0 0 0 IDLE ENDS05 SLU2 00000000 0 0 0 0 0 IDLE ENDS06 SLU2 00000000 0 0 0 0 0 IDLE NDSLU2A1 SLU2 00000000 0 0 0 0 0 ASR IDLE NDSLU2A2 SLU2 00000000 0 0 0 0 0 ASR IDLE NDSLU2A3 SLU2 00000000 0 0 0 0 0 ASR IDLE NDSLU2A4 SLU2 00000000 0 0 0 0 0 ASR IDLE NDSLU2A5 SLU2 00000000 0 0 0 0 0 IDLE NDSLU2A6 SLU2 00000000 0 0 0 0 0 ASR IDLE OMSSLU2A SLU2 00000000 0 0 0 0 0 IDLE Selected 34 lines from 396 lines. DOCMD Executed 435 DL/I calls in 1.602206 seconds. EXEC DOCMD ended with RC= 0
Figure 72. Output from = > DOCMD /DIS NODE ALL;TYPE=SLU2
Selection criteria =>ENQCT>0 & RECTYPE=T02<= Command: /DIS TRAN ALL TRAN CLS ENQCT QCT LCT PLCT CP NP LP SEGSZ SEGNO PARLM RC TACP18 1 119 0 65535 65535 1 1 1 0 0 NONE 1 Selected 1 lines from 1104 lines. DOCMD Executed 1152 DL/I calls in 5.780977 seconds. EXEC DOCMD ended with RC= 0
Figure 73. Output from = > DOCMD /DIS TRAN ALL;ENQCT>0 & RECTYPE='T02'
Selection criteria =>ENQCT>0<= Command: /DIS LTERM ALL LTERM ENQCT DEQCT QCT CTRL 19 19 0 T3270LC 119 119 0 Selected 2 lines from 678 lines. DOCMD Executed 681 DL/I calls in 1.967670 seconds. EXEC DOCMD ended with RC= 0
Figure 74. Output from = > DOCMD /DIS LTERM ALL;ENQCT>0
The source code for the DOCMD exec is shown in Figure 75 on page 373.
372
DOCMD
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
/*********************************************************************/ /* A REXX EXEC that executes an IMS command and parses the */ /* output by a user supplied criteria. */ /* */ /* */ /*********************************************************************/ /* Format: tranname DOCMD IMS-Command;Expression */ /* Where: */ /* tranname is the tranname of a command capable transaction that */ /* will run the DFSREXX program. */ /* IMS-Command is any valid IMS command that generates a table of */ /* output like /DIS NODE ALL or /DIS TRAN ALL */ /* Expression is any valid REXX expression, using the header names*/ /* as the variables, like CID>0 or SEND=0 or more */ /* complex like CID>0 & TYPE=SLU2 */ /* Example: TACP18 DOCMD DIS A Display active */ /* TACP18 DOCMD DIS NODE ALL;? See headers of DIS NODE */ /* TACP18 DOCMD DIS NODE ALL;CID>0 Show active Nodes */ /* TACP18 DOCMD DIS NODE ALL;CID>0;SYSOUT Output to SYSOUT */ /* TACP18 DOCMD DIS NODE ALL;CID>0 & TYPE=SLU2 */ /*********************************************************************/ Address REXXTDLI Parse Upper Arg Cmd ; Expression ; SysOut Cmd=Strip(Cmd); Expression=Strip(Expression) SysOut=(SysOut\=) If Cmd= Then Do Call SayIt Please supply an IMS Command to execute. Exit 0 End AllOpt= (Expression=ALL) If AllOpt then Expression= If Left(Cmd,1)\=/ then Cmd=/Cmd /* Add a slash if necessary */ If Expression= Then Call SayIt No Expression supplied, all output shown, from: Cmd Else If Expression=? Then Call SayIt Headers being shown for command: Cmd Else Call SayIt Selection criteria =>Expression<=, Command: Cmd x=Time(R); Calls=0 ExitRC= ParseHeader(Cmd,Expression) If ExitRC\=0 then Exit ExitRC If Expression=? Then Do Do i=1 to Vars.0 Call SayIt Variable (header) #i = Vars.i Calls=Calls+1 End End Figure 75. DOCMD Exec: Process an IMS Command (Part 1 of 3)
373
DOCMD
Else Do Call ParseCmd Expression Do i=1 to Line.0 If AllOpt then Line=Line.i Else Line=Substr(Line.i,5) If SysOut then Do Push Line EXECIO 1 DISKW DOCMD End Else Do Call SayIt Line Calls=Calls+1 End End If SysOut then Do EXECIO 0 DISKW DOCMD ( FINIS End If Expression\= then Call SayIt Selected Line.0-1 lines from, LinesAvail lines. Else Call SayIt Total lines of output: Line.0-1 Call SayIt DOCMD Executed Calls DL/I calls in, Time(E) seconds. End Exit 0 ParseHeader: CurrCmd=Arg(1) CmdCnt=0 CMD IOPCB CURRCMD CmdS= IMSQUERY(STATUS) Calls=Calls+1 If CmdS= then Do Call SayIt Command Executed, No output available. Return 4 End Else If CmdS\=CC then Do Call SayIt Error Executing Command, Status=CmdS Return 16 End CurrCmd=Translate(CurrCmd, ,15x) /* Drop special characters CurrCmd=Translate(CurrCmd,__,-/) /* Drop special characters CmdCnt=CmdCnt+1 Interpret LINE.||CmdCnt = Strip(CurrCmd) Parse Var CurrCmd RecType Header If Expression= then Nop Else If Right(RecType,2)=70 then Do Vars.0=Words(Header)+1 Vars.1 = "RECTYPE" Do i= 2 to Vars.0 Interpret VARS.i = "Word(CurrCmd,i)" End End Else Do Call SayIt Command did not produce a header, record, first records type=RecType Return 12 End Return 0 Figure 75. DOCMD Exec: Process an IMS Command (Part 2 of 3)
*/ */
374
IVPREXX
ParseCmd: LinesAvail=0 CurrExp=Arg(1) Do Forever GCMD IOPCB CURRCMD CmdS= IMSQUERY(STATUS) Calls=Calls+1 If CmdS\= then Leave /* Skip Time Stamps */ If Word(CurrCmd,1)=X99 & Expression\= then Iterate LinesAvail=LinesAvail+1 CurrCmd=Translate(CurrCmd, ,15x)/* Drop special characters */ If Expression= then OK=1 Else Do Do i= 1 to Vars.0 Interpret Vars.i = "Word(CurrCmd,i)" End Interpret OK=Expression End If OK then Do CmdCnt=CmdCnt+1 Interpret LINE.||CmdCnt = Strip(CurrCmd) End End Line.0 = CmdCnt If CmdS\=QD Then Call SayIt Error Executing Command:, Arg(1) Stat=CmdS Return SayIt: Procedure Parse Arg Line ISRT IOPCB LINE Return RC
Figure 75. DOCMD Exec: Process an IMS Command (Part 3 of 3)
IVPREXX: MPP/IFP Front End for General Exec Execution

The IVPREXX exec is a front-end generic exec that is shipped with IMS as part of the IVP. It runs other execs by passing the exec name to execute after the TRANCODE (IVPREXX). For further details on IVPREXX, see IVPREXX Sample Application on page 347. For the latest version of the IVPREXX source code, see the IMS.ADFSEXEC distribution library; member name is IVPREXX.
375
376
Chapter 16. CICS-DL/I User Interface Block Return Codes

After issuing any kind of a DL/I call, CICS online programs must check the return code in the UIB before checking the DL/I status code. If the value in UIBRCODE is not null, the contents of the PCB status code are not meaningful. For more information on defining and addressing a UIB, see Specifying the UIB (CICS Online Programs Only) on page 77. The UIBRCODE contains two bytes, UIBFCTR and UIBDLTR. You should first check the contents of UIBFCTR; the contents of UIBDLTR are meaningful only if UIBFCTR indicates a NOTOPEN or INVREQ condition. Table 88, Table 89, and Table 90 show the return codes from the CICS-DL/I interface.
Table 88. Return Codes in UIBFCTR Condition NORESP (normal response) NOTOPEN (not open) INVREQ (invalid request) ASM X'00' X'0C' X'08' COBOL LOW-VALUES 12-4-8-9 12-8-9 PL/I 00000 000 00001 100 00001 000
Table 89. Return Codes in UIBDLTR if UIBFCTR='0C' (NOTOPEN) Condition Database not open Intent scheduling conflict ASM X'00' X'02' COBOL LOW-VALUES 12-2-9 PL/I 00000 000 00000 010
Table 90. Return Codes in UIBDLTR if UIBFCTR='08' (INVREQ) Condition Invalid argument passed to DL/I PSBNF (PSB not found) PSBSCH (PSB already scheduled) NOTDONE (request not executed) PSBFAIL (PSB initialization failed) TERMNS (termination not successful) FUNCNS (function unscheduled) INVPSB (invalid PSB) DLINA (DL/I not active) ASM X'00' X'01' X'03' X'04' X'05' X'07' X'08' X'10' X'FF' COBOL LOW-VALUES 12-1-9 12-3-9 12-4-9 12-5-9 12-7-9 12-8-9 12-10-9 12-11-0-7-8-9 PL/I 00000 000 00000 001 00000 011 00000 100 00000 101 00000 111 00001 000 00010 000 11111 111
377
CICS-DL/I User Interface Block Return Codes

If these codes do not appear to be due to programming errors, they may be caused by not-open or invalid-request conditions. The following topics provide additional information: v Not-Open Conditions v Invalid Request Conditions
Not-Open Conditions
A NOTOPEN condition is indicated if UIBFCTR contains X'0C'
UIBDLTR='00' Explanation: This is returned on a database call if the database was stopped after the PSB is scheduled. UIBDLTR='02' Explanation: This indicates that an intent-scheduling conflict exists. This condition does not occur if you are using IMS program isolation.
Invalid Request Conditions

An invalid request is indicated by UIBFCTR=X'08'
UIBDLTR='00' (INVARG) Explanation: An invalid argument was passed to DL/I indicating one of these problems: v Count argument exists, but count is too high. v I/O area is missing. v Received data length is greater than 65520. v Call type is invalid. UIBDLTR='01' (PSBNF) Explanation: This is returned after a scheduling call; it indicates that the PSB to be scheduled was not defined in the PSB directory (PDIR). UIBDLTR='03' (PSBSCH) Explanation: This PSB has already been scheduled. UIBDLTR='04' (NOTDONE) Explanation: The XDLIPRE exit routine indicates that a DL/I request should not be issued. UIBDLTR='05' (PSBFAIL) Explanation: The PSB could not be scheduled, possibly because: v The database has been stopped. v The master terminal operator has entered a DUMPDB command. This command sets the read-only flag in the DMB directory (DDIR). You will not be able to schedule any PSBs with update intent. v The master terminal operator has entered a RECOVERDB command. This command sets the do-not-schedule-flag in the DDIR. You will not be able to schedule any PSB that references the database. v The END statement in the PDIR generation stream did not specify the DFSIDIR0 operand. The trace entry, which contains the PCB status, gives you the reason for the scheduling failure. UIBDLTR='07' (TERMNS) Explanation: A terminate request was issued, but no PSB was currently scheduled. It could indicate that the PSB has already taken place because of a terminate request or CICS sync point. UIBDLTR='08' (FUNCNS) Explanation: A database call was issued when the PSB was not scheduled. UIBDLTR='10' (INVPSB) Explanation: SYSSERVE IOPCB specified for local DL/I. UIBDLTR='FF' (DLINA) Explanation: DLI=NO has been specified in the system initialization table (SIT).
378
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: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd. 1623-14, Shimotsuruma, Yamato-shi Kanagawa 242-8502 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.
379
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 and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA 95141-1003 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample
380
programs are provided "AS IS," without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. 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 and Associated Guidance Information.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web in the topic Copyright and trademark information at http://www.ibm.com/legal/copytrade.shtml. The following terms are trademarks or registered trademarks of other companies, and have been used at least once in the IMS library: v Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. v Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Notices
381
v Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. v Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. v UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and service names might be trademarks of IBM or other companies.
382
Bibliography
This bibliography lists all of the information in the IMS Version 9 library. v CICS/ESA Application Programming Guide, SC33-1169 v CICS/ESA Application Programming Reference, SC33-1170 v CICS/ESA CICS-IMS Database Control Guide, SC33-1184 v CICS/MVS Installation Guide, SC33-0506 v CICS/ESA System Definition Guide, SC33-1164 v IBM Language Environment Installation and Customization on MVS, SC26-4817 v IBM Language Environment for MVS & VM Programming Guide, SC26-4818 v MVS/ESA: JCL Reference MVS/ESA System Product: JES2 Version 5 , GC28-1479 v MVS/ESA System Programming Library: Application Development Guide, GC28-1852 v System Application Architecture Common Programming Interface: Resource Recovery Reference, SC31-6821 v IBM TSO Extensions for MVS/REXX Reference, SC28-1883
Title IMS Version 9: Command Reference IMS Version 9: Common Queue Server Guide and Reference IMS Version 9: Common Service Layer Guide and Reference IMS Version 9: Customization Guide IMS Version 9: Database Recovery Control (DBRC) Guide and Reference IMS Version 9: Diagnosis Guide and Reference IMS Version 9: Failure Analysis Structure Tables (FAST) for Dump Analysis IMS Version 9: IMS Connect Guide and Reference IMS Version 9: IMS Java Guide and Reference IMS Version 9: Installation Volume 1: Installation Verification IMS Version 9: Installation Volume 2: System Definition and Tailoring IMS Version 9: Master Index and Glossary IMS Version 9: Messages and Codes, Volume 1 IMS Version 9: Messages and Codes, Volume 2 IMS Version 9: Open Transaction Manager Access Guide and Reference IMS Version 9: Operations Guide IMS Version 9: Release Planning Guide IMS Version 9: Summary of Commands IMS Version 9: Utilities Reference: Database and Transaction Manager IMS Version 9: Utilities Reference: System Acronym CR CQS CSL Order number SC18-7814 SC18-7815 SC18-7816
CG DBRC
SC18-7817 SC18-7818
DGR FAST
LY37-3203 LY37-3204
CT JGR IIV
SC18-9287 SC18-7821 GC18-7822
ISDT
GC18-7823
IMS Version 9 Library

Title IMS Version 9: Administration Guide: Database Manager IMS Version 9: Administration Guide: System IMS Version 9: Administration Guide: Transaction Manager IMS Version 9: Application Programming: Database Manager IMS Version 9: Application Programming: Design Guide IMS Version 9: Application Programming: EXEC DLI Commands for CICS and IMS IMS Version 9: Application Programming: Transaction Manager IMS Version 9: Base Primitive Environment Guide and Reference Acronym ADB AS ATM APDB Order number SC18-7806 SC18-7807 SC18-7808 SC18-7809
MIG MC1 MC2 OTMA
SC18-7826 GC18-7827 GC18-7828 SC18-7829
OG RPG SOC URDBTM
SC18-7830 GC17-7831 SC18-7832 SC18-7833
APDG APCICS
SC18-7810 SC18-7811
APTM
SC18-7812
URS
SC18-7834
BPE
SC18-7813
383
Supplementary Publications
Title IMS TM Resource Adapter User's Guide and Reference IMS Version 9 Fact Sheet IMS Version 9: Licensed Program Specifications IRLM Messages and Codes Order number SC19-1211 GC18-7697 GC18-7825 GC19-2666
Publication Collections
Order number IMS Version 9 Softcopy Library CD LK3T-7213 Licensed Bill of Forms (LBOF): Hardcopy LBOF-7789 IMS Version 9 Hardcopy and and CD Softcopy Library Unlicensed Bill of Forms Hardcopy SBOF-7790 (SBOF): IMS Version 9 Unlicensed Hardcopy Library z/OS and Software Products DVD SK3T-4271 DVD Collection Title Format
Accessibility Titles Cited in This Library

Title z/OS V1R1.0 TSO Primer z/OS V1R5.0 TSO/E Users Guide z/OS V1R5.0 ISPF Users Guide, Volume 1 Order number SA22-7787 SA22-7794 SC34-4822
384
Index Special characters

!token IMSQUERY function 363 STORAGE command 360 . (period) usage null or void placeholder 353 parsing, transparent additions REXX 351 *mapname 357, 358 AIB (application interface block) (continued) AIBLEN (DFSAIB allocated length) (continued) in ROLB call 280 in ROLS call 282 in SETS/SETU call 283 in SNAP call 284 in STAT call 287 in SYNC call 289 in XRST call 290 AIBOALEN (maximum output area length) 74 in CHKP (symbolic) call 254 in GMSG call 257 in GSCD call 259 in ICMD call 259 in INIT call 261 in INQY call 266 in LOG call 276 in RCMD call 279 in ROLB call 280 in ROLS call 282 in SETS/SETU call 283 in SNAP call 284 in STAT call 287 in XRST call 290 AIBOAUSE (used output area length) description 74 in GMSG call 257 in ICMD call 260 in RCMD call 279 AIBREASN (reason code) 74 AIBRSA1 (resource address) 74 AIBRSNM1 (resource name) description 73 in APSB call 252 in CHKP (basic) call 253 in CHKP (symbolic) call 254 in DPSB call 255 in GMSG call 257 in GSCD call 259 in INIT call 261 in INQY call 266 in LOG call 276 in ROLB call 280 in ROLS call 282 in SETS/SETU call 283 in SNAP call 284 in STAT call 287 in SYNC call 289 in XRST call 290 AIBRSNM2 in APSB call 252 in CHKP (basic) call 253 AIBSFUNC (subfunction code) description 73 in DPSB call 256 in GMSG call 256 in INQY call 266 description 85 AIB (application interface block) (continued) DFSAIB allocated length (AIBLEN) 73 fields 73 interface, REXX 349 mask 73, 74 program entry statement 89 specifying 73 storage, defining 86 subfunction, setting 359 AIB mask, specifying 73 AIBERRXT (reason code) 74 AIBID (AIB identifier) field, AIB mask 73 AIBLEN (DFSAIB allocated length) field, AIB mask 73 AIBOALEN (maximum output area length) field, AIB mask 74 AIBOAUSE (used output area length) field, AIB mask 74 AIBREASN (reason code) AIB mask, field 74 AIBREASN (reason code) field, AIB mask 74 AIBRSA1 (resource address) field, AIB mask 74 AIBRSNM1 (resource name) field, AIB mask 73 AIBSFUNC (subfunction code) field, AIB mask 73 AIBTDLI interface See AIB (application interface block) Allocate PSB (APSB) call 252 format 252 parameters 252 usage 252 AMODE 94 AND operators dependent 150 independent 151 logical 24 AO (automated operator) application GMSG call 256 ICMD call 259 RCMD call 278 AOI token, usage 257 APPC environment 344 application interface block (AIB) See AIB (application interface block) application program DBDs (database descriptions), about 9 deadlock occurrence, in 265 environments 5 HALDB environment, scheduling 93 hierarchy examples 13, 15 PSBs (program specification blocks), about 9 APSB (Allocate PSB) call 252 format 252
354
Numerics
12-byte time stamp, field in I/O PCB 8-blanks (null) 256 69
A
AB0C1 internal call statement 298 abend statement 300 accessing GSAM databases 157 AD/Cycle C/370 91 addressability to UIB, establishing 78 addressing environments 344, 349 addressing mode (AMODE) 94 AIB (application interface block) address return 89 AIB identifier in RCMD call 278 AIB identifier (AIBID) description 73 in APSB call 252 in CHKP (basic) call 253 in CHKP (symbolic) call 254 in DPSB call 255 in GMSG call 256 in GSCD call 258 in ICMD call 259 in INIT call 261 in INQY call 266 in LOG call 276 in ROLB call 280 in ROLS call 281 in SETS/SETU call 283 in SNAP call 284 in STAT call 287 in SYNC call 289 in XRST call 290 AIBERRXT (reason code) 74 AIBLEN (DFSAIB allocated length) in APSB call 252 in CHKP (basic) call 253 in CHKP (symbolic) call 254 in DPSB call 255 in GMSG call 256 in GSCD call 259 in ICMD call 259 in INIT call 261 in INQY 266 in LOG call 276 in RCMD call 279 Copyright IBM Corp. 1974, 2011
385
APSB (Allocate PSB) call (continued) parameters 252 usage 252 area in CHKP (symbolic) call 255 in XRST call 291 area length in CHKP (symbolic) call 254 in XRST call 291 areas, I/O 80 assembler language DL/I call format, example 56 DL/I call-level sample 32 DL/I program structure 29 entry statement 86 parameters, DL/I call format 55 program entry 87 register 1, program entry 87 return statement 86 SSA definition examples 82 syntax diagram, DL/I call format 54 UIB, specifying 77
B
backout point, intermediate 116 bank account database example 15 Basic Checkpoint (CHKP Basic) description 253 format 253 parameters 253 usage 253 batch programs assembler language 29 C language 34 COBOL 36 deadlock occurrence, in 265 maintaining integrity 115 overview 5 Pascal 44 PL/I 46 structure 5 BILLING segment 15 binding, reference 32, 49 BMPs, transaction-oriented ROLB 114 Boolean operators dependent AND 150 independent AND 151 logical AND operator 24 logical OR 24 SSA, coding 81
C
C language 87 __pcblist 87 batch program, coding 34 DL/I call formats, example 59 DL/I program structure 34 entry statement 86, 87 exit 87 I/O area 59 parameters, DL/I call format 57 PCBs, passing 87 return statement 86
C language (continued) SSA definition examples 82 syntax diagram, DL/I call format 56 system function 88 C/C++ 91 call functions, DL/I 309 call results for status codes, exceptional 9 CALL statement 300 CALL DATA 303 CALL DATA statement internal field 303 CALL FUNCTION 300 call-level programs, CICS online 10 calls, DB CIMS 221 CLSE 223 DEQ 224 DLET 225 FLD 226 GHNP 233 GHU 235 GN 229 GNP 233 GU 235 ISRT 238 OPEN 241 POS 242 REPL 245 RLSE 247 calls, system service APSB (allocate PSB) 252 CHKP (basic) 253 CHKP (symbolic) 254 GMSG (get message) 256 ICMD (issue command) 259 INIT (initialize) 261 INQY (inquiry) 266 LOG (log) 276 PCB (schedule a PSB) 277 RCMD (retrieve command) 278 ROLB (roll back) 280 SETS/SETU (set a backout point) 282 backing out to an intermediate backout point 116 using 116 SNAP 284 STAT (statistics) 286 SYNC (synchronization point) 288 TERM (terminate) 289 XRST (extended restart) 290 CCTL (coordinator controller) design recommendation 142 performance considerations thread monitoring 143 CEETDLI 91 address return 88 interface to IMS 92 program entry statement 53, 88 checkpoint (CHKP) calls considerations 28 description 111 issuing 111 CHKP (basic checkpoint) call description 253 format 253
CHKP (basic checkpoint) call (continued) parameters 253 usage 253 CHKP (checkpoint) call, considerations 28 CHKP (symbolic checkpoint) call description 254 format 254 parameters 254 usage 255 with GSAM 163 CHKP call function 306 CHNG call function 306 CICS DL/I call program, compiling 29 CICS online programs 277 assembler language, sample 32 COBOL, establishing addressability 44 COBOL, optimization feature 44 COBOL, sample 39 PCB call 277 PL/I, sample 50 structure 10 TERM call 289 CIMS call description 221 format 221 parameters 221 usage 222 class, record segment 209 closing a GSAM database explicitly 161, 223 CLSE (Close) call description 223 format 223 parameters 223 usage 223 CMD call function 306 COBOL CICS online, establishing addressability 44 CICS online, optimization feature 44 DL/I call formats, example 62 DL/I call-level, sample 39 DL/I program structure 36 entry statement 86 Language Environment 91 parameters, DL/I call format 60 return statement 86 SSA definition examples 83 syntax diagram, DL/I call format 59 UIB, specifying 77 COBOL/370 and Language Environment 91 codes, status checking 8 logical relationships 155 coding rules, SSA 81 command codes 204 C description 203 SSAs (segment search arguments) 21 D examples 26, 203 Get calls 204 ISRT call 205
386
command codes (continued) D (continued) P processing option 204 DEDBs 27 DL/I calls 201 F Get calls 205 HERE insert rule 240 ISRT call 206 restrictions 187 L FIRST insert rule 207, 240 Get calls 206 M 214 N 207 Null 213 overview 26 P 208 Q 118, 208 qualified SSAs 27 R 215 reference 201 restrictions 81 S 216 SSAs (segment search arguments) 21 subset pointers 27, 181, 182 U 211 unqualified SSAs 27 V 212 Z 218 COMMENT statement conditional (T) 320 unconditional (U) 320 commit point processing DEDB 185 MSDB 176 COMPARE statement COMPARE AIB 323 COMPARE DATA 322 COMPARE PCB 324 introduction 321 concatenated data sets, GSAM 167 concatenated key and PCB mask 72, 159 concatenated segments, logical relationships 154 connector, field search argument (FSA) 228 CTL (PUNCH) statement 328 current position determining 95 multiple positioning 104 qualification 211 unsuccessful calls 100
D
data areas, coding 28 data availability, status codes 71 data entry database (DEDB) See DEDB (data entry database) data locking 177 data mapping, define with MAXDEF command 355 data redundancy, reducing 152 data structures 29 database administrator 14
database (continued) calls Fast Path 195 summary 219 DB PCB, name 71, 159 deallocating resources 255 position after XRST 292 determining 95 establishing using GU 237 multiple positioning 104 unsuccessful calls 100 recovery with ROLL call 114 recovery, back out changes 113 database descriptions (DBDs) 9 database management calls 7 database resource adapter (DRA) See DRA (database resource adapter) DB PCB status codes NU 262 DB PCB (database program communication block) database name 71, 159 entry statement, pointer 158 fields 70, 71 in GSCD 258 key feedback area 159 key feedback area length field 72, 159 mask 71 fields 159 fields, GSAM 158 general description 70 GSAM reference 85 name 158 relation 70 specifying 70 masks DB PCB 70 multiple DB PCBs 109 number of sensitive segments field 72 processing options field 72, 159 relation to DB PCB 70 secondary indexing, contents 152 segment level number field 71 segment name field 72 sensitive segments 72 status code field 71, 159 status codes NA 262 DBA 14 DBDs (database descriptions) description 9 DBQUERY using with INIT call 262 deadlock occurrence application programs 265 batch programs, in 265 debugging, IMSRXTRC 354 DEDB (data entry database) 170 call restrictions 187 command codes 213 data locking 177 DL/I calls 187 multiple qualification statements 26
DEDB (data entry database) (continued) PCBs and DL/I calls 295 processing commit point 185 data locking 177 fast path 169 H option 186 overview 171 P option 186 POS call 183 subset pointers 178 root segments, order 232 updating segments 171 updating with subset pointers 178 define a data mapping with MAXDEF command 355 Delete (DLET) call description 225 format 225 parameters 223, 225, 242 SSA 226 usage 226 with MSDB, DEDB or VSO DEDB 171 dependent AND operator 150 dependents, direct 170 DEQ (Dequeue) call description 224 format Fast Path 224 full function 224 function 306 parameters Fast Path 224 full function 224 Q command code 209, 224 restrictions 225 summary 220 usage 224 Dequeue (DEQ) call description 224 format Fast Path 224 full function 224 function 306 parameters Fast Path 224 full function 224 Q command code 209, 224 summary 220 usage 224 DFSDDLT0 (DL/I Test Program) See DL/I Test Program (DFSDDLT0) DFSDDLT0 internal control statements AB0C1 statement (INTERNAL CALL STATEMENT) 298 WTSR statement (INTERNAL CALL STATEMENT) 298 DFSPRP macro keywords 128 DFSPSP00 (DRA startup table) 128 DFSREXXU, example user exit routine 344 DFSSAM01 (Loads the Database) 370 DL/I call formats, examples assembler language 56 C language 59 COBOL 62 Index
387
DL/I call formats, examples (continued) Pascal 64 PL/I 67 DL/I call functions special DFSDDLT0 END 319 SKIP 319 STAK 319 START 319 supported CHKP 306 CHNG 306 CMD 306 DEQ 306 DLET 306 FLD 306 GCMD 306 GHN 306 GHNP 306 GHU 306 GMSG 307 GN 307 GNP 307 GU 307 ICMD 307 INIT 307 INQY 307 ISRT 307 LOG 307 POS 307 PURG 307 RCMD 307 REPL 307 ROLB 307 ROLL 308 ROLS 308 ROLX 308 SETO 308 SETS 308 SNAP 308 STAT 308 SYNC 308 XRST 308 DL/I call functions, examples 309 DL/I calls (general information) qualified calls 20 qualifying calls command codes 26 concatenated key 203 field 21 segment type 21 relationships to PCBs, FF PCBs 295 REXXTDLI 349 segment search arguments (SSAs) 20 types 21 unqualified calls 20 DL/I calls, database management CIMS 221 CLSE 223 DEQ 224 DLET 225, 226 FLD 226, 229 general description 7 GHNP call 235 GHU call 237 GN 229, 233 GNHP call 232
DL/I calls, database management (continued) GNP 233, 235 GU 235, 238 ISRT 238, 241 OPEN 241 POS 242, 245 REPL 245, 246 RLSE 247 summary 7, 219 DL/I calls, general information coding 28 getting started with 5 using 7 DL/I calls, system service APSB 252 CHKP 253, 254, 255 CHKP (basic) 253 description 249 DPSB 255 GMSG 256 GSCD 258, 259 INIT 261, 265 INQY 266 LOG 276, 277 PCB 277, 278 ROLB 114, 280 ROLL 113, 280, 281 ROLS 281, 282 SETS/SETU 282, 283 SNAP 284, 286 STAT 286, 288, 289, 290 summary 7, 250 SYNC 288, 289 XRST 290 DL/I language interfaces overview 53 supported interfaces 53 DL/I Open Database Access (ODBA) interface 12 DL/I options logical relationships 152 secondary indexing 149 DL/I program structure 5 DL/I return codes (REXX) 349 DL/I Test Program (DFSDDLT0) control statements 298, 335 execution in IMS regions 339 explanation of return codes 339 hints on usage 339, 341 JCL requirements 335, 339 overview 297 restarting input stream 337 DL/I, getting started with CICS online 10 DLET (Delete) call description 225 format 225 parameters 223, 225, 242 SSA 226 usage 226 with MSDB, DEDB or VSO DEDB 171 DLET call function 306 DLIINFO . (period) usage 354 REXX extended command 352, 353
DLITCBL 88 DLITPLI 88 DOCMD exec 370 DPSB call description 255 format 255 parameters 255 usage 256 DRA (database resource adapter) CCTL function requests description 132 INIT 132 RESYNC 134 TERM 135 CCTL recovery process 142 description 121 DRA statistics 145 enabling CCTL 129 ODBA 130 initializing CCTL 129 ODBA 130 macro keywords 128 multithreading 122 PAPL 141 problem determination 146 processing CCTL requests 131 ODBA calls 132 startup table description 128 DFSPZPxx 128 sync point processing description 124 sync-point processing in-doubt state 127 protocol 125 termination 141 thread ODBA 122 processing 121 structure 121 thread function requests 135 ABTTERM 140 COMTERM 139 IMS 137 PREP 139 SCHED 135 SYNTERM 138 TERMTHRD 140 thread statistics 143 tracing 146 dynamic MSDBs (main storage databases) 16
E
E (COMPARE) statement 321 enabling data availability status codes 71 END call function 319 entry and return conventions 86 environment (REXX) address 344, 349 determining 352 extended 349
388
equal-to relational operator 21 error routines 9 explanation 9 I/O errors 9 programming errors 9 system errors 9 types of errors 9 examples bank account database 15 Boolean operators 25 D command code 26, 204 DFSDDLT0 statements COMMENT 321 DATA/PCB COMPARE 325 DD 337 DL/I call functions 309 IGNORE 327 OPTION 328 PUNCH 331 STATUS 333 SYSIN, SYSIN2, and PREINIT 337 WTO 334 WTOR 335 DFSREXXU user exit routine 344 FLD/CHANGE 175 FLD/VERIFY 175 L command code 207 medical database 13 multiple qualification statements 25 N command code 207 Null command code 213 P command code 208 path call 26 SSA, secondary indexing 150 U Command Code 211 UIB, defining 78 V command code 212 EXECIO example 370 managing resources 344 explicitly opening and closing a GSAM database 161 extended commands See REXXIMS commands extended environment See environment (REXX) extended functions See IMSQUERY extended function Extended Restart (XRST) description 290 parameters 290 position in database 292 restarting your program 291 restrictions 293 starting your program normally 291 usage 291 with Symbolic Checkpoint (CHKP Symbolic) 255
Fast Path (continued) MSDB (main storage database) 169 processing MSDBs and VSO DEDBs 171 subset pointers, using with DEDBs 178 types of databases 169 field changing contents 174 checking contents: FLD/VERIFY 172 Field (FLD) call See FLD (Field) call field name FSA 173, 228 SSA, qualification statement 21 field search argument (FSA) connector 228 description 172 field name 228 Op code 228 operand 228 reference 227 status code 228 with DL/I calls 172 field value FSA 173 SSA, qualification statement 21, 22 fields in a DB PCB 159 fields in a DB PCB mask 71 file I/O See EXECIO FIRST insert rule, L command code 207 fixed-length records 161 fixed, MSDBs (main storage databases) 16 FLD (Field) call description 171, 226 FLD/CHANGE 174 FLD/VERIFY 172 format 226 FSAs 227 parameters 227 summary 220 usage 227 FLD call function 306 free space, identifying 185 FSA (field search argument) connector 228 description 172 field name 228 Op code 228 operand 228 reference 227 status code 228 with DL/I calls 172 full-function database PCBs and DL/I calls 295 segment release 210
F
F command code, restrictions 187 Fast Path database calls 169, 170 databases, processing 169 DEDB (data entry database) 169 FSA 227
G
GB (end of database), return status code 204 GCMD call function 306 GE (segment not found), return status code 204
generalized sequential access method (GSAM) See GSAM (generalized sequential access method) generated program specification block (GPSB), format 89 Get calls D command code 204 F command code 205 function 306 L command code 207 Null command code 213 P command code 208 Q command code 208 U Command Code 211 V command code 212 get hold next (GHN), usage 232 Get Hold Unique (GHU) description 237 Get Message (GMSG) call description 256 format 256 parameters 256 restrictions 258 usage 257 Get Next (GN) call description 229 format 229 hold form (GHN) 232 parameters 229 SSA 231 usage 230 Get Next in Parent (GNP) call description 233 effect in parentage 234 format 233 hold form (GHNP) 235 parameters 233 SSA 235 usage 234 linking with previous DL/I calls 234 processing with parentage 234 Get System Contents Directory (GSCD) call description 258 format 258 parameters 258 usage 259 Get Unique (GU) call description 235 format 236 hold form (GHU) 237 parameters 236 restrictions 238 usage 237 GHN (get hold next), usage 232 GHNP call 233 hold form 235 GHU (Get Hold Unique), description 237 GMSG call description 256 format 256 parameters 256 restrictions 258 usage 257 Index
389
GN (Get Next) call description 229 format 229 hold form (GHN) 232 parameters 229 SSA 231 usage 230 GNP (Get Next in Parent) call description 233 effect in parentage 234 format 233 hold form (GHNP) 235 parameters 233 SSA 235 usage 234 linking with previous DL/I calls 234 processing with parentage 234 GPSB (generated program specification block), format 89 greater-than relational operator 21 greater-than-or-equal-to relational operator 21 group name, field in I/O PCB 69 GSAM (generalized sequential access method) accessing databases 157 BMP region type 167 call summary 163 CHKP 163 coding considerations 163 data areas 85 data set attributes, specifying 167 characteristics, origin 164 concatenated 167 DD statement DISP parameter 165 extended checkpoint restart 165 database, explicitly opening and closing 161 DB PCB mask, fields 158 DB PCB masks 85 DBB region type 167 description 157 designing a program 157 DLI region types 167 fixed-length records 161 I/O areas 162 PCBs and DL/I calls 295 record formats 161 records, retrieving and inserting 159 restrictions on CHKP and XRST 163 RSA 85, 160 status codes 162 undefined-length records 161 variable-length records 161 XRST 163 GSCD (Get System Contents Directory) call description 258 format 258 parameters 258 usage 259 GU (Get Unique) call description 235 format 236
GU (Get Unique) call (continued) hold form (GHU) 237 parameters 236 restrictions 238 SSA 237 usage 237 guidelines, programming 19
H
H processing option 186 HALDB (High Availability Large Database) application programs, scheduling against 93 HALDB partitions data availability 9 error settings 9 handling 9 initial load of 93 restrictions for loading logical child segments 9 scheduling 9 status codes 9 HDAM multiple qualification statements 26 order of root segments 232 HERE insert rule F command code 206 L command code 207 hierarchic sequence 230 hierarchical database example, medical 13 hierarchy bank account database 15 data structures 29 medical database 13 hierarchy examples 13, 15 High Availability Large Database (HALDB) application programs, scheduling against 93 HALDB partitions data availability 9 error settings 9 handling 9 initial load of 93 restrictions for loading logical child segments 9 scheduling 9 status codes 9 HOUSHOLD segment 15
I
I/O area C language 59 coding 80 description 80 for XRST 291 in CHKP (symbolic) call 254 in GMSG call 257 in GSCD call 259 in INIT call 261 in INQY call 266 length in CHKP (symbolic) call
254
I/O area (continued) returned keywords 243 map of 243 specifying 80 I/O PCB in GSCD 258 in INIT call 261 mask 12-byte time stamp 69 general description 67 group name field 69 input message sequence number 68 logical terminal name field 67 message output descriptor name 68 specifying 67 status code field 68 userid field 69 userid indicator field 70 PCBs and DL/I calls 295 ICMD call commands that can be issued 261 description 259, 261 format 259 parameters 259 restrictions 261 use 260 IGNORE (N or .) statement 327 ILLNESS segment 14 IMSQUERY extended function arguments 363 usage 363 IMSRXTRC command 352, 354 independent AND operator 151 indexed field in SSA 150 indexing, secondary DL/I Returns 152 effect on program 149 multiple qualification statements 150 SSAs 149 status codes 152 infinite loop, stopping 348 INIT (Initialize) call automatic INIT DBQERY 263 call function 307 database availability, determining 262 description 261 enabling data availability, status codes 263 enabling deadlock occurrence, status codes 264 format 261 INIT STATUS GROUPA 263 INIT STATUS GROUPB 264 parameters 261 performance 263 restrictions 265 status codes 263 usage 261 using with DBQUERY 262 Initialize (INIT) call automatic INIT DBQERY 263 database availability, determining 262
390
Initialize (INIT) call (continued) description 261 enabling data availability, status codes 263 enabling deadlock occurrence, status codes 264 format 261 INIT STATUS GROUPA 263 INIT STATUS GROUPB 264 parameters 261 performance 263 restrictions 265 status codes 263 usage 261 using with DBQUERY 262 input for a DL/I program 28 input message sequence number, field in I/O PCB 68 INQY (Inquiry) call description 266 format 266 map of INQY subfunction to PCB type 275 parameters 266 querying data availability 267 environment 268 PCB 270 program name 275 restriction 275 return and reason codes 275 usage 266 INQY call querying input information 270 LERUNOPT, using LERUNOPT subfunction 274 INQY call function 307 INQY DBQUERY 267 INQY ENVIRON, data output 268 INQY FIND 270 INQY PROGRAM 275 inserting first occurrence of a segment 205 last occurrence 206 segments 239 inserting a segment as first occurrence 206 as last occurrence 206 GSAM records 159 in sequence 205 path of segments 205 root 239 rules to obey 239 specifying rules 240 integrity batch programs 115 maintaining, database 112 using ROLB 113 MPPs and transaction-oriented BMPs 114 using ROLL 113 using ROLS 115 interfaces, DL/I 91 See DL/I interfaces intermediate backout point backing out 116
internal call statements AB0C1 298 WTSR 298 internal control statements, DFSDDLT0 AB0C1 statement (INTERNAL CALL STATEMENT) 298 WTSR statement (INTERNAL CALL STATEMENT) 298 internal control statements, summary 298 ISRT (Insert) call D command code 205 description 238 F command code 206 format 238 L command code 207 loading a database 207 parameters 238 RULES parameter 206 SSA 240 with MSDB, DEDB or VSO DEDB 171 ISRT call function 307 Issue Command (ICMD) call See ICMD call 259 IVPREXX exec 375 IVPREXX sample application 347
LOG (Log) call description 276 format 276 parameters 276 restrictions 277 usage 277 LOG call function 307 logging DRA (database resource adapter) logical AND, Boolean operator 24 logical child 152 logical child segments HALDB (High Availability Large Database), restrictions 9 logical OR, Boolean operator 24 logical parent 152 logical relationships effect on programming 154 introduction 152 logical child 152 logical parent 152 physical parent 152 processing segments 152 programming, effect 152 status codes 155 logical structure 152 logical terminal name, field in I/O PCB 67
146
J
JCL (job control language), requirements 335, 339
M
M command code examples 214 subset pointers, moving forward 214 main storage database (MSDB) See MSDB (main storage database) main storage database (MSDBs) types nonrelated 17 main storage databases (MSDBs) dynamic 16 types related 16 managing subset pointers in DEDBs with command codes 171 MAP definition (MAPDEF) 352, 355 map name See *mapname MAP reading (MAPGET) 352, 357 MAP writing (MAPPUT) 352, 358 mapping MAPDEF 355 MAPGET 357 MAPPUT 358 mask AIB 73 DB PCB 70 MAXQ and Q command code 209 medical database example 13 description 13 segments 13 message output descriptor name, field in I/O PCB 68 mixed-language programming 93 modifiable alternate PCBs 111 MPPs ROLB 114 Index
K
key feedback area DB PCB, length field 72 length field in DB PCB 159 overview 72 keys concatenated 203
L
L (CALL) statement 300 Language Environment 91 LANG = option for PL/I compatibility 92 language interfaces, DL/I 91 See DL/I interfaces length of key feedback area 159 less-than relational operator 21 less-than-or-equal-to relational operator 21 level number, field in DB PCB 71 limiting number of full-function database calls 209 locating dependents in DEDBs last-inserted sequential dependent, POS call 183 POS call 183 specific sequential dependent, POS call 183 lock class and Q command code 209 lock management 119
391
MSDB (main storage database) call restrictions 178 commit point processing 176 data locking 177 PCBs and DL/I calls 295 processing 171 data locking 177 updating segments 171 MSDBs (main storage database) processing commit points 176 MSDBs (main storage databases) nonrelated 169 terminal related 169 types description 169 nonrelated 17 related 16 multiple DB PCBs 109 positioning 104 processing 104 qualification statements 24 qualification statements, DEDB 26 qualification statements, HDAM 26 qualification statements, PHDAM 26 multiple positioning advantages of 107 effecting your program 107 resetting position 109 MYLTERM 178
operators Boolean 24 relational 24 OPTION statement 327 options, processing; field in DB PCB 159 OR, logical 24 OS/VS COBOL and Language Environment 91 overriding FIRST insert rule 207 HERE insert rule 206, 207 insert rules 240
72,
P
P command code 208 P processing option 186, 204 parameters assembler language, DL/I call format 55 C language, DL/I call format 57 COBOL, DL/I call format 60 Pascal, DL/I call format 63 PL/I, DL/I call format 65 parentage, P command code 208 PART exec 368 PARTNAME exec 369 PARTNUM exec 369 parts of DL/I program 5 Pascal batch program, coding 44 DL/I call formats, example 64 DL/I program structure 44 entry statement 86, 88 parameters, DL/I call format 63 PCBs, passing 88 SSA definition examples 84 syntax diagram, DL/I call format 62 path call 204 D command code 204 definition 26 example 26 overview 26 PATIENT segment 14 PAYMENT segment 15 PCB (program communication block) address list, accessing 77 DL/I calls, relationship 295 DLIINFO call 353 masks description 6 GSAM databases 157 I/O PCB 67 modifiable alternate PCBs 111 types 90 PCB (schedule a PSB) call description 277 format 277 parameters 278 usage 278 PCBINFO exec 366 PCHSEGTS 243 PCLBSGTS 243 PCSEGHWM 243 PCSEGRTS 243
N
N command code 207 NA 262 name field, segments 21 nonrelated (non-terminal-related) MSDBs 169 not-equal-to relational operator 21 not-found status code description 100 position after 100 NU 262 Null command code 213
O
O (OPTION) Statement 327 ODBA (Open Database Access) interface, DLI/I getting started with 12 op code 228 OPEN (Open) call description 241 format 241 usage 242 Open Database Access (ODBA) interface, DL/I getting started with 12 operand FSA 228 operation parameter, SNAP external call 285 operator FSA 173 SSA 21
period usage See usage PHDAM multiple qualification statements 26 PHDAM database 232 physical parent 152 PL/I batch program, coding 46 DL/I call formats, example 67 DL/I call-level sample 50 DL/I program, multitasking restriction 46 entry statement 86 parameters, DL/I call format 65 PCBs, passing 88 pointers in entry statement 88 return statement 86 SSA definition examples 84 syntax diagram, DL/I call format 64 UIB, specifying 77 PL/I and Language Environment 91 PL/I Compatibility LANG= Option 92 PLITDLI 117 POS (Position) call description 183, 242 examples 245 format 242 I/O area 243 parameters 243 unqualified keywords 243 usage 245 POS call function 307 POS(positioning)=MULT(multiple) 104 position establishing in database 237 positioning after DLET 97 after ISRT 99 after REPL 99 after retrieval calls 97 after unsuccessful calls 100 after unsuccessful DLET or REPL call 100 after unsuccessful retrieval or ISRT call 101 CHKP, effect 111 current, after unsuccessful calls 100 determining 95 multiple 104 understanding current 95 PREINIT parameter, input restart 335 preloaded programs 94 processing commit-point in DEDB 185 commit-point in MSDB 176 database, several views 109 DEDBs 178 Fast Path databases 169 GSAM databases 157 MSDBs and VSO DEDBs 171 multiple 104 options field in DB PCB 72, 159 H (position), for Fast Path 186 P (path) 204
392
processing (continued) options (continued) P (position), for Fast Path 186 segments in logical relationships 152 program batch structure 5 design 28 restarting 111 program communication block See also DB (database program communication block) See PCB (program communication block) program deadlock 264 program specification blocks (PSBs) description 9 programming guidelines 19 mixed language 93 secondary indexing 149 PSB (program specification block) format 89 PSBGEN LANG= Option 92 PSBs (program specification blocks) description 9 PUNCH statement 328 PURG call function 307
R
R command code 215 RACF signon security 69 RACROUTE SAF 69 randomizing routine exit routine 26, 232 RCMD call description 278, 279 format 278 parameters 278 restrictions 279 use 279 reading segments in MSDBs 172, 178 record search argument See RSA (record search argument) related (terminal related) MSDBs 169 relational operators Boolean operators 24 independent AND 24 list 21 logical AND 24 logical OR 24 overview 21 SSA, coding 81 SSA, qualification statement 21 REPL (Replace) call description 245 format 245 N command code 207 parameters 245 SSAs 246 usage 246 with MSDB, DEDB or VSO DEDB 171 REPL call function 307 requesting a segment using GU 237 reserving place for command codes 187 segment command code 118 lock management 119 resetting a subpointer 216 residency mode (RMODE) 94 Restart, Extended parameters 290 position in database 292 restarting your program 291 restrictions 293 starting your program normally 291 usage 291 Restart, Extended (XRST) description 290 with Symbolic Checkpoint (CHKP Symbolic) 255 restarting your program XRST call 291 restarting your program, basic checkpoints 111 restrictions CHKP and XRST with GSAM 163 database calls to DEDBs 187 to MSDBs 178 F command code 205 number of database calls and Fast Path 209
Q
Q command code 118 and the DEQ call 210 example 209 full function and segment release 210 lock class 209 MAXQ 209 qualification statement coding 81 field name 21 field value 21, 22 multiple qualification statements 24 multiple qualification statements, DEDB 26 multiple qualification statements, HDAM 26 multiple qualification statements, PHDAM 26 relational operator 21 segment name 21 structure 21 qualification statements overview 21 qualified calls definition 21 overview 20 qualified SSA structure with command code 27 qualified SSAs (segment search arguments) qualification statement 21 structure 21 qualifying DL/I calls with command codes 26 SSAs 21
retrieval calls D command code 204 F command code 205 L command code 207 status codes, exceptional 9 Retrieve Command (RCMD) call See RCMD call 278 retrieving dependents sequentially 233 first occurrence of a segment 205 last occurrence 206 segments Q command code, Fast Path 209 Q command code, full function 209 sequentially 204 segments with D 204 return codes UIB 77, 377 REXX . (period) usage 351 calls return codes 349 summary 349 syntax 349 commands DL/I calls 349 summary 349 DL/I calls, example 351 execs DFSSAM01 370 DOCMD 370 IVPREXX 375 PART 368 PARTNAME 369 PARTNUM 369 PCBINFO 366 SAY 365 IMSRXTRC, trace output 354 REXX, IMS adapter . (period) usage 353 address environment 344 AIB, specifying 351 description 343 DFSREXX0 program 343, 347 DFSREXX1 343 DFSREXXU user exit 343 DFSRRC00 347 diagram 347 DL/I parameters 350 environment 352 example execs 364 feedback processing 350 I/O area 350 installation 343 IVPREXX exec 347 IVPREXX PSB 345 IVPREXX setup 345 LLZZ processing 350 LNKED requirements 343 non-TSO/E 343 PCB, specifying 351 programs 343 PSB requirements 343 sample generation 345 sample JCL 345 SPA processing 350 Index
393
REXX, IMS adapter (continued) SRRBACK 343 SRRCMIT 343 SSA, specifying 351 SYSEXEC DD 343, 345 system environment 343, 345 SYSTSIN DD 345 SYSTSPRT DD 343, 345 TSO environment 343 TSO/E restrictions 343 ZZ processing 350 REXXIMS commands 355, 357 See also IMSQUERY extended function DLIINFO 352, 353 IMSRXTRC 352, 354 MAPDEF 352 MAPGET 352 MAPPUT 352, 358 SET 352, 359 SRRBACK 352, 360 SRRCMIT 352, 360 STORAGE 352, 360 WTL 352, 362 WTO 352, 362 WTOR 352, 362 WTP 352, 362 REXXTDLI commands 349 RLSE format 247 RLSE (Release) call description 247 parameters 247 usage 247 RMODE 94 ROLB in MPPs and transaction-oriented BMPs 114 ROLB (Roll Back) call compared to ROLL call 113 description 114, 280 format 280 maintaining database integrity 112 parameters 280 usage 114 ROLB call function 307 ROLL (Roll) call compared to ROLB call 113 description 113, 280 format 281 maintaining database integrity 112 ROLL call function 308 ROLS backing out to an intermediate backout point 116 ROLS (Roll Back to SETS) call description 281 format 281 maintaining database integrity 112 parameters 281 TOKEN 115 ROLS call function 308 ROLX call function 308 routines, error 9 RSA (record search argument) description 160 GSAM, reference 85 overview 159
rules coding an SSA 81 RULES parameter FIRST, L command code 207 HERE F command code 206 L command code 207
S
S (STATUS) statement 331 S command code examples 216 subpointer, resetting 216 sample JCL 335 sample programs call-level assembler language, CICS online 32 call-level COBOL, CICS online 39 call-level PL/I, CICS online 50 SAY exec 365 scheduling HALDB (High Availability Large Database) 9 scheduling HALDBs application programs, against 93 secondary indexes multiple qualification statements 150 secondary indexing DB PCB contents 152 effect on programming 149 information returned by DL/I 152 SSAs 149 status codes 152 secondary processing sequence 150 segment requesting using GU 237 segment level number field 71 segment name DB PCB, field 72 SSA, qualification statement 21 segment search argument (SSA) coding rules 81 segment search arguments (SSAs) 20 segment, information needed 28 segments medical database example 13 sensitive segments in DB PCB 72 sequence hierarchy 230 sequence field virtual logical child, in 22 sequence, indication for statements 335 sequential dependent segments how stored 170 sequential dependents 170 overview 170 SET command (REXX) 352, 359 SET SUBFUNC command (REXX) 359 SET ZZ 359 SETO call function 308 SETO, DFSDDLT0 description 300 SETS backing out to an intermediate backout point 116 SETS (Set a Backout Point) call description 116, 282
SETS (Set a Backout Point) call (continued) format 282 parameters 283 SETS call function 308 setting parentage with the P command code 208 subset pointer to zero 218 SETU backing out to an intermediate backout point 116 SETU (Set a Backout Point Unconditional) call description 116, 282 format 282 parameters 283 SETU, call function 116 signon security, RACF 69 single positioning 104 skeleton programs assembler language 29 C language 34 COBOL 36 Pascal 44 PL/I 46 SKIP call function 319 SNAP call description 284 format 284 parameters 284 status codes 286 SNAP call function 308 specifying command codes for DEDBs 181 DB PCB mask 70 GSAM data set attributes 167 processing options for DEDBs 186 Spool API STORAGE command example 362 SRRBACK command (REXX) description 352 format, usage 360 SRRCMIT command (REXX) description 352 format, usage 360 SSA (segment search argument) coding formats 82 restrictions 82 rules 80 coding rules 81 command codes 26 qualification statement 81 reference 80 relational operators 21 restrictions 80 segment name field 81 structure with command code 27 usage command codes 27 guidelines 23 multiple qualification statements 24 virtual logical child, in 22 SSAs (segment search argument) overview 20
394
SSAs (segment search argument) (continued) segment name field 21 SSAs (segment search arguments) 20 definition 20 qualified 21 unqualified 21 usage 226 DLET 226 GN 231 GNP 235 ISRT 240 REPL 246 secondary indexing 149 STAK call function 319 START call function 319 STAT (Statistics) call description 286 format 287 parameters 287 usage 288 STAT call function 308 status code GE (segment not found) 204 status codes blank 8 checking 8 DB PCB, for 262 error routines 9 exceptional call results 9 field in DB PCB 71, 159 FSA 173 GB, end of database 204 GSAM 162 H processing option 186 HALDB (high availability large databases) partitions 9 logical relationships 155 P processing option 186 retrieval calls 9 subset pointers 182 status codes, field in I/O PCB 68 STATUS statement 331 storage !token 360 STORAGE command 360 STORAGE command (REXX) description 352 format, usage 360 subset pointer command codes restrictions 27 subset pointers DEDB, managed by command codes 27 defining, DBD 181 defining, PCB 181 description 178 M command 214 preparing to use 180 R command code 215 resetting 216 S command code 216 sample application 181, 213 status codes 182 using 178 Z command code 218
Summary database management call 219 system service calls 250 summary of changes for DFSDDLT0 internal control statements 298 summary of command codes 26 Symbolic Checkpoint (CHKP Symbolic) 254 format 254 parameters 254 restrictions 255 usage 255 SYNC (Synchronization Point) call description 288 format 289 parameters 289 usage 289 SYNC call function 308 syntax diagram assembler language, DL/I call format 54 C language, DL/I call format 56 COBOL, DL/I call format 59 how to read xi Pascal, DL/I call format 62 PL/I, DL/I call format 64 SYSIN input 335 SYSIN2 input processing 335 system service calls APSB (Allocate PSB) 252 CHKP (Basic) 253 CHKP (Symbolic) 254 DPSB (deallocate) 255 GMSG (Get Message) 256 ICMD (Issue Command) 259 INIT (Initialize) 261 INQY (Inquiry) 266 LOG (Log) 276 PCB (schedule a PSB) 277 RCMD (Retrieve Command) 278 ROLB (Roll Back) 280 SETS/SETU (Set a Backout Point) 282 SNAP 284 STAT (Statistics) 286 SYNC (Synchronization Point) 288 TERM (Terminate) 289 XRST (Extended Restart) 290
U
U (Comment) statement 321 U Command Code 211 UIB (user interface block) defining, in program 77 field names 79 PCB address list, accessing 77 return codes, accessing 77 return codes, list 377 UIBDLTR introduction 78 return codes, checking 377 UIBFCTR introduction 78 return codes, checking 377 UIBPCBAL introduction 78 return codes, checking 377 undefined-length records 159 unqualified calls definition 21 overview 20 unqualified POS call I/O returned area key words 243 map of 243 keywords 243 unqualified SSA structure with command code 27 usage with command codes 27 unqualified SSAs segment name field 21 UOW boundary, processing DEDB 186 updating segments in an MSDB, DEDB or VSO DEDB 171 user interface block See UIB (user interface block) userid indicator, field in I/O PCB 70 userid, field in I/O PCB 69
V
V command code 212 V5SEGRBA 243 variable-length records 159 virtual logical child 22 virtual storage option data entry database (VSO DEDB) See VSO DEDB (virtual storage option data entry database), processing VS COBOL II and Language Environment 91 VSAM, STAT call 288 VSO DEDB (virtual storage option data entry database), processing 171
T
T (Comment) statement 320 TERM (Terminate) call description 289 format 289 usage 290 test program See DL/I Test Program (DFSDDLT0) testing status codes 8 tracing DRA (database resource adapter) 146 transaction-oriented BMPs ROLB 114 TREATMNT segment 14 TSO/E REXX See REXX, IMS adapter
W
WAITAOI 257 WTL command (REXX) description 352 format, usage 362 WTO command (REXX) description 352 format, usage 362 Index
395
WTO statement 334 WTOR command (REXX) description 352 format, usage 362 WTOR statement 335 WTP command (REXX) description 352 format, usage 362 WTSR internal call statement
298
X
XRST (Extended Restart) 255 XRST (Extended Restart) call description 290 format 290 parameters 290 restrictions 293 usage 291 with GSAM 163 XRST call function 308
Z
Z command code examples 218 setting a subpointer to zero z/OS environment 344 218
396
Program Number: 5655-J38
Printed in USA
SC18-7809-04
Spine information:
IMS
Version 9

IMS Appl Prog

Uploaded by

IMS Appl Prog

Uploaded by

IMS

Application Programming: Database Manager

Application Programming: Database Manager

Chapter 4. Current Position in the Database After Each Call . . . . . . . 95

Part 1. Writing Application Programs 1

Chapter 5. Recovering Databases and Maintaining Database Integrity . . . . 111

Chapter 1. How Application Programs Work with Database Manager . . . . . 5

Chapter 6. The Database Resource Adapter (DRA) . . . . . . . . . . . 121

Chapter 2. Writing Your Application Programs . . . . . . . . . . . . . 19

Chapter 3. Defining Application Program Elements. . . . . . . . . . 53

Chapter 7. Secondary Indexing and Logical Relationships . . . . . . . . 149

Chapter 8. Processing GSAM Databases . . . . . . . . . . . . . 157

162 163 163 164

Chapter 9. Processing Fast Path Databases . . . . . . . . . . . . . 169

280 281 282 284 286 288 289 290

Part 2. Reference . . . . . . . . . 197

Chapter 11. DL/I Calls for Database Management . . . . . . . . . . . . 219

Chapter 15. Adapter for REXX . . . . 343

Chapter 12. DL/I Calls for System Services . . . . . . . . . . . . . 249

Chapter 16. CICS-DL/I User Interface Block Return Codes . . . . . . . . 377

Application Programming: Database Manager

Copyright IBM Corp. 1974, 2011

Application Programming: Database Manager

Copyright IBM Corp. 1974, 2011

Return Codes in UIBDLTR if UIBFCTR='0C' (NOTOPEN) . . . . . . . . . . . . 377

Return Codes in UIBDLTR if UIBFCTR='08' (INVREQ). . . . . . . . . . . .

Application Programming: Database Manager

About This Book

Copyright IBM Corp. 1974, 2011

IBM Product Names Used in This Information

Application Programming: Database Manager

How to Read Syntax Diagrams

v Optional items appear below the main path.

About This Book

v In IMS, a b symbol indicates one blank position.

Application Programming: Database Manager

Accessibility Features for IMS Version 9

Related Accessibility Information

IBM and Accessibility

How to Send Your Comments

About This Book

Application Programming: Database Manager

Changes to the Current Edition of This Book for IMS Version 9

Changes to This Book for IMS Version 9

Library Changes for IMS Version 9

New and Revised Titles

Application Programming: Database Manager

Application Programming: Database Manager

Part 1. Writing Application Programs

100 101 104 104 107 109

. 111 . 111 . 111 . 112 . 112 . 116 . 118

Application Programming: Database Manager

Fast Path Coding Considerations .

Part 1. Writing Application Programs

Application Programming: Database Manager

Chapter 1. How Application Programs Work with Database Manager

Copyright IBM Corp. 1974, 2011

Figure 1. DL/I Program Elements

Application Programming: Database Manager

DL/I and Your Application Program

System Service Call Functions

Status, Return, and Reason Codes

Application Programming: Database Manager

Exceptional Condition Status Codes

High Availability Large Databases (HALDBs)

Database Descriptions (DBDs) and Program Specification Blocks (PSBs)

High Availability Large Database

Figure 3. Relationship between Programs and Multiple PCBs (Concurrent Processing)

DL/I for CICS Online Users

Application Programming: Database Manager

DL/I for CICS Online Users

Figure 4. The Structure of a Call-Level CICS Online Program

DL/I for CICS Online Users

DL/I using the ODBA Interface

Application Programming: Database Manager

DL/I using the ODBA Interface