System Programming APIs

567 Pages·2017·3.68 MB·English

IMS
Version 15.1.0
System Programming APIs
(September 27, 2018 edition)
IBM
SC27-6797-00

IMS
Version 15.1.0
System Programming APIs
(September 27, 2018 edition)
IBM
SC27-6797-00
Note
Before you use this information and the product it supports, read the information in “Notices” on page 541.
September 27, 2018 edition.
This edition applies to IMS 15 (program number 5635-A06), IMS Database Value Unit Edition, V15.01.00 (program
number 5655-DS5), IMS Transaction Manager Value Unit Edition, V15.01.00 (program number 5655-TM4), and to all
subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1974, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this information . . . . . . . . vii Sequence for coding CSL requests . . . . . 114
Prerequisite knowledge . . . . . . . . . . vii Requests common to all CSL components . . . . 114
How new and changed information is identified. . vii CSLZQRY: query request . . . . . . . . 114
How to read syntax diagrams . . . . . . . . vii CSLZSHUT: shutdown request . . . . . . 116
Accessibility features for IMS 15 . . . . . . . ix
How to send your comments. . . . . . . . . x Chapter 4. CSL automated operator
program requests . . . . . . . . . 119
Part 1. Common Queue Server (CQS) 1 CSLOMCMD: command request . . . . . . . 119
CSLOMI: API request . . . . . . . . . . 129
Chapter 1. Writing a CQS client . . . . 3 CSLOMQRY: query request. . . . . . . . . 138
CSL OM automated operator program clients . . 143
Summary of CQS client requests. . . . . . . . 3
How AOP clients that run on the host
Sequence of CQS requests issued by a client for
communicate with the CSL OM . . . . . . 144
queue structure . . . . . . . . . . . . . 4
How AOP clients that run on a workstation
Considerations for coding CQS requests . . . . . 5
communicate with the CSL OM . . . . . . 144
Environmental requirements for CQS . . . . . 8
Processing AOP commands with a command
Return codes and reason codes for CQS requests . 9
processing client . . . . . . . . . . . 145
CQS clients and handling special events. . . . . 12
Interpreting CSL OM XML output . . . . . 146
Chapter 2. CQS client requests . . . . 15
Chapter 5. Writing a CSL ODBM client 147
CQSBRWSE request . . . . . . . . . . . 17
Sequence of ODBM client requests . . . . . . 147
CQSCHKPT request . . . . . . . . . . . 25
CSL ODBM client requests . . . . . . . . . 148
CQSCONN request. . . . . . . . . . . . 28
CSLDMDRG: ODBM client deregistration
CQSDEL request. . . . . . . . . . . . . 35
request . . . . . . . . . . . . . . 148
CQSDEREG request . . . . . . . . . . . 41
CSLDMI: ODBM application program interface 150
CQSDISC request . . . . . . . . . . . . 42
CSLDMREG: ODBM client registration request 161
CQSINFRM request . . . . . . . . . . . 47
CQSMOVE request. . . . . . . . . . . . 51
Chapter 6. Writing a CSL OM client 165
CQSPUT request . . . . . . . . . . . . 55
CSL OM command processing client requests . . 165
CQSQUERY request . . . . . . . . . . . 64
CSLOMBLD: command registration build . . . 165
CQSREAD request . . . . . . . . . . . . 73
CSLOMDRG: command deregistration request 167
CQSRECVR request . . . . . . . . . . . 79
CSLOMOUT: unsolicited output request . . . 169
CQSREG request . . . . . . . . . . . . 83
CSLOMRDY: ready request. . . . . . . . 170
CQSRSYNC request . . . . . . . . . . . 86
CSLOMREG: command registration request . . 172
CQSSHUT request . . . . . . . . . . . . 92
CSLOMRSP: command response request . . . 175
CQSUNLCK request . . . . . . . . . . . 94
CSLOMSUB: Subscribe to unsolicited messages . . 178
CQSUPD request . . . . . . . . . . . . 99
CSLOMUSB: Unsubscribe to unsolicited messages 181
CSL OM directives . . . . . . . . . . . 182
Part 2. Common Service Layer
(CSL) . . . . . . . . . . . . . . 105
Chapter 7. Writing a CSL RM client 187
Sequence of RM client requests . . . . . . . 187
Chapter 3. Writing a CSL client. . . . 107 Issue CSL RM requests to manage global resources 188
Event Control Blocks with CSL requests . . . . 107 Issue CSL RM requests to coordinate IMSplex-wide
Environmental requirements for SCI requests. . . 107 processes. . . . . . . . . . . . . . . 188
How to interpret CSL request return and reason CSLRMDEL: delete resources . . . . . . . . 189
codes . . . . . . . . . . . . . . . . 109 CSLRMDRG: deregister clients . . . . . . . 194
Planning considerations for writing clients for the CSLRMPRI: process initiate. . . . . . . . . 195
CSL . . . . . . . . . . . . . . . . 109 CSLRMPRR: process respond . . . . . . . . 197
Registration of CSL managers with SCI. . . . . 111 CSLRMPRS: process step . . . . . . . . . 199
SCI registration. . . . . . . . . . . . 111 CSLRMPRT: process terminate. . . . . . . . 205
Registering an ODBM client . . . . . . . 111 CSLRMQRY: query resources . . . . . . . . 207
Registering an OM command processing client 112 CSLRMREG: register clients . . . . . . . . 212
Registering an RM client . . . . . . . . 113 CSLRMUPD: update resources . . . . . . . 216
How to enable SCI ready state. . . . . . . 113 CSL RM directives. . . . . . . . . . . . 221
© Copyright IBM Corp. 1974, 2017 iii
CSL RM repopulate structure directive . . . . 222 Example of logged data elements. . . . . . . 297
CSL RM structure failed directive . . . . . 222
CSL RM process step directive. . . . . . . 223 Chapter 12. End of Job (EOJ) call log
CSL RM process step response directive . . . 224 record . . . . . . . . . . . . . . 299
Chapter 8. Writing a CSL SCI client 227
Chapter 13. SETS and ROLS call log
Sequence of CSL SCI requests . . . . . . . . 227
records . . . . . . . . . . . . . . 301
Advanced CSL SCI requests . . . . . . . . 228
CSL SCI requests . . . . . . . . . . . . 228
Chapter 14. Format of the data
CSLSCBFR: buffer return request. . . . . . 228
CSLSCDRG: deregistration request . . . . . 230 capture log records. . . . . . . . . 303
CSLSCMSG: send message request . . . . . 232 Data capture log record prefix. . . . . . . . 303
CSLSCQRY: query request . . . . . . . . 239 Changed data log record format . . . . . . . 303
CSLSCQSC: quiesce request . . . . . . . 242 Format for data element header . . . . . . . 304
CSLSCRDY: ready request . . . . . . . . 243 CAPD block format (LOGID=X'00') . . . . . . 305
CSLSCREG: registration request . . . . . . 244 CAPD_DATA format (LOGID=X'0C') . . . . . 307
CSLSCRQR request return request . . . . . 252 End of Job call log record format. . . . . . . 309
CSLSCRQS: send request . . . . . . . . 255 SETS and ROLS call log record format . . . . . 309
Chapter 9. CSL Operations Manager Part 4. Database resource adapter
XML output . . . . . . . . . . . . 261
(DRA) . . . . . . . . . . . . . . 311
CSLOMI XML output examples . . . . . . . 261
CSLOMCMD output . . . . . . . . . . . 264
Chapter 15. Thread concepts. . . . . 313
CSLOMQRY output . . . . . . . . . . . 265
Processing threads. . . . . . . . . . . . 313
CSLOMOUT output . . . . . . . . . . . 267
Processing multiple threads . . . . . . . . 314
XML tags returned as CSL OM responses . . . . 267
CCTL multithread example. . . . . . . . . 315
Chapter 10. REXX SPOC API and the
Chapter 16. Sync points. . . . . . . 321
CSL . . . . . . . . . . . . . . . 275
The two-phase commit protocol . . . . . . . 322
REXX SPOC API environment with the CSL OM 275
In-doubt state during two-phase sync processing 324
Setting up the REXX environment in a CSL . . 275
Setting up the IMSplex environment. . . . . 275
Chapter 17. DRA startup table . . . . 325
Issuing type-2 IMS commands. . . . . . . 277
CSLULGTS: retrieving command responses in
XML . . . . . . . . . . . . . . . 277 Chapter 18. Enable the DRA for a
CSLULOPT: including format identifiers in CCTL . . . . . . . . . . . . . . . 329
command responses . . . . . . . . . . 277
CSLULGTP: retrieving command responses Chapter 19. Enabling the DRA for the
directly to a REXX stem variable . . . . . . 278
ODBA interface . . . . . . . . . . 331
REXX SPOC API within a transaction . . . . 284
Ending the IMS SPOC environment . . . . . 285
Chapter 20. Processing CCTL DRA
Retrieving unsolicited messages . . . . . . . 285
CSLULSUB request . . . . . . . . . . 285 requests . . . . . . . . . . . . . 333
CSLULUSB request . . . . . . . . . . 286
CSLULGUM request . . . . . . . . . . 286 Chapter 21. Processing ODBA calls 335
Sample program for subscribing to OM . . . 286
REXX samples and examples . . . . . . . . 287
Chapter 22. CCTL-initiated DRA
Sample REXX SPOC program . . . . . . . 287
function requests . . . . . . . . . 337
REXX SPOC batch job example . . . . . . 288
/DISPLAY command examples and format INIT request. . . . . . . . . . . . . . 337
identifiers . . . . . . . . . . . . . 290 RESYNC request . . . . . . . . . . . . 340
Autonomic computing examples . . . . . . 290 TERM request . . . . . . . . . . . . . 341
SCHED request. . . . . . . . . . . . . 342
IMS request . . . . . . . . . . . . . . 345
Part 3. Asynchronous data
SYNTERM request . . . . . . . . . . . 346
propagation . . . . . . . . . . . 293
PREP request . . . . . . . . . . . . . 347
COMTERM request . . . . . . . . . . . 348
Chapter 11. Changed data log record 295 ABTTERM request . . . . . . . . . . . 349
Elements of captured data . . . . . . . . . 295 TERMTHRD request . . . . . . . . . . . 350
Reducing the amount of captured data. . . . . 296
iv System Programming APIs
Chapter 23. Terminating the DRA . . . 351 Return and reason codes for the COMMAND
request . . . . . . . . . . . . . . . 385
Chapter 24. Designing the CCTL COMMAND output block mapping. . . . . . 386
recovery process. . . . . . . . . . 353
Chapter 30. DBRC query request
(QUERY) . . . . . . . . . . . . . 389
Chapter 25. CCTL performance:
Output from query requests . . . . . . . . 390
monitoring DRA thread TCBs . . . . 355
Backout query request (TYPE=BACKOUT) . . 390
DRA thread statistics. . . . . . . . . . . 355
Database query request (TYPE=DB) . . . . . 394
DRA statistics . . . . . . . . . . . . . 357
DBDS query request (TYPE=DBDS) . . . . . 416
DRA tracing. . . . . . . . . . . . . . 358
Group query request (TYPE=*GROUP). . . . 422
Sending commands to IMS DB . . . . . . . 358
Log query request (TYPE=LOG) . . . . . . 429
Problem diagnosis. . . . . . . . . . . . 358
OLDS query request (TYPE=OLDS) . . . . . 437
HALDB partition query request (TYPE=PART) 441
Part 5. Database Recovery Control RECON status query request (TYPE=RECON) 447
(DBRC) . . . . . . . . . . . . . 361 Subsystem query request (TYPE=SUBSYS). . . 451
Chapter 31. DBRC release buffer
Chapter 26. DBRC API . . . . . . . 363
request (RELBUF) . . . . . . . . . 457
Structure of applications that access the DBRC API 363
How an application program establishes the
DBRC API environment. . . . . . . . . 364 Chapter 32. DBRC start request
How an application program ends the DBRC (STARTDBRC) . . . . . . . . . . . 461
API environment . . . . . . . . . . . 364
Addressing and residency mode . . . . . . 364 Chapter 33. DBRC stop request
Address space control (ASC) mode and state 364
(STOPDBRC) . . . . . . . . . . . 465
How the DBRC API uses registers . . . . . 364
How to include equate (EQU) statements in
Chapter 34. DBRC unauthorization
your DBRC API application . . . . . . . 364
API application. . . . . . . . . . . . 365 request (UNAUTH) . . . . . . . . . 467
Versions of the DBRC API macro. . . . . . 366 Return and reason codes for UNAUTH. . . . . 470
The DBRC API token. . . . . . . . . . 366 APAUB_RsnCode for UNAUTH output block 471
Macro forms of the DSPAPI macro . . . . . 366 UNAUTH output block mapping. . . . . . . 472
Query output block header. . . . . . . . 368 UNAUTH output block . . . . . . . . . . 472
Runtime considerations for the DBRC API. . . . 369
DSPAPI macro access. . . . . . . . . . 369 Part 6. IMS catalog API
RECON data set access . . . . . . . . . 369
(DFS3CATQ) . . . . . . . . . . . 473
RECON access authority . . . . . . . . 370
Time stamp format for DBRC requests . . . . 370
How DBRC uses the output data set . . . . 371 Chapter 35. IMS catalog API
Wildcard support for name parameters for (DFS3CATQ macro). . . . . . . . . 475
Query requests. . . . . . . . . . . . 371
Chapter 36. Structure of applications
Chapter 27. DBRC API security
that access the IMS catalog API . . . 477
features. . . . . . . . . . . . . . 373
Chapter 37. DSECT mapping request
Chapter 28. DBRC authorization
(DSECT) for the IMS catalog API . . . 479
request (AUTH) . . . . . . . . . . 375
Syntax for the AUTH request . . . . . . . . 375
| Chapter 38. HLQ request (HLQ) for the
Parameters for the AUTH request . . . . . . 376
|| IMS catalog API . . . . . . . . . . 481
Return and reason codes for AUTH . . . . . . 377
APAUB_RsnCode for AUTH output block. . . . 379
AUTH output block mapping . . . . . . . . 380 Chapter 39. Open request (OPEN) for
AUTH output block . . . . . . . . . . . 381 the IMS catalog API. . . . . . . . . 485
Chapter 29. DBRC command request Chapter 40. Get request (GET) for the
(COMMAND). . . . . . . . . . . . 383 IMS catalog API . . . . . . . . . . 489
Syntax for the COMMAND request . . . . . . 383
Parameters for the COMMAND request . . . . 383
Contents v
Chapter 41. List request (LIST) for the IMS as secondary half session. . . . . . . . 524
IMS catalog API . . . . . . . . . . 495
Chapter 45. Bind parameters for SLU
Chapter 42. Close request (CLOSE) 1 and SLU 2 . . . . . . . . . . . . 529
for the IMS catalog API . . . . . . . 499 SLU 1 bind parameters . . . . . . . . . . 529
SLU 2 bind parameters . . . . . . . . . . 531
Part 7. Repository Server batch
Chapter 46. Format for CINIT user
interface (FRPBATCH) . . . . . . 501
data parameters . . . . . . . . . . 535
Chapter 43. Commands for Chapter 47. SNA character string
FRPBATCH . . . . . . . . . . . . 503 controls. . . . . . . . . . . . . . 537
ADD command for FRPBATCH . . . . . . . 505 Format controls. . . . . . . . . . . . . 537
DELETE command for FRPBATCH . . . . . . 507 Control function code assignments . . . . . . 538
DSCHANGE command for FRPBATCH . . . . 507
LIST command for FRPBATCH . . . . . . . 508
Part 9. Appendixes . . . . . . . . 539
RENAME command for FRPBATCH . . . . . 509
START command for FRPBATCH . . . . . . 510
STOP command for FRPBATCH . . . . . . . 511 Notices . . . . . . . . . . . . . . 541
UPDATE command for FRPBATCH. . . . . . 512 Programming interface information . . . . . . 543
Trademarks . . . . . . . . . . . . . . 543
Part 8. VTAM and SNA reference Terms and conditions for product documentation 543
IBM Online Privacy Statement. . . . . . . . 544
information . . . . . . . . . . . 515
Bibliography. . . . . . . . . . . . 547
Chapter 44. Bind parameters for SLU
P and LU 6.1. . . . . . . . . . . . 517
Index . . . . . . . . . . . . . . . X.-1
Finance communication system bind parameters 517
IMS as primary half session . . . . . . . . 519
vi System Programming APIs
About this information
These topics provide reference information for IMS system application
programming interface (API) calls for IMS Common Queue Server (CQS); IMS
Common Service Layer (CSL); IMS data propagation with IMS DataPropagator for
z/OS®; IMS Database Resource Adapter (DRA); IMS Database Recovery Control
(DBRC) API; IMS catalog API; IMS Repository Server (FRPBATCH); and VTAM®
and SNA.
This information is available in IBM® Knowledge Center.
Prerequisite knowledge
Before using this information, you should have knowledge of either IMS Database
Manager (DB) or IMS Transaction Manager (TM). You should also understand
basic z/OS and IMS concepts, your installation's IMS system, and have general
knowledge of the tasks involved in project planning.
You can learn more about z/OS by visiting the “z/OS basic skills” topics in IBM
Knowledge Center.
You can gain an understanding of basic IMS concepts by reading An Introduction to
IMS, an IBM Press publication.
IBM offers a wide variety of classroom and self-study courses to help you learn
IMS. For a complete list of courses available, go to the IBM Skills Gateway and
search for IMS.
How new and changed information is identified
New and changed information in most IMS library PDF publications is denoted by
a character (revision marker) in the left margin. The first edition (-00) of Release
Planning, as well as the Program Directory and Licensed Program Specifications, do not
include revision markers.
Revision markers follow these general conventions:
v Only technical changes are marked; style and grammatical changes are not
marked.
v If part of an element, such as a paragraph, syntax diagram, list item, task step,
or figure is changed, the entire element is marked with revision markers, even
though only part of the element might have changed.
v If a topic is changed by more than 50%, the entire topic is marked with revision
markers (so it might seem to be a new topic, even though it is not).
Revision markers do not necessarily indicate all the changes made to the
information because deleted text and graphics cannot be marked with revision
markers.
How to read syntax diagrams
The following rules apply to the syntax diagrams that are used in this information:
© Copyright IBM Corp. 1974, 2017 vii
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 ►◄
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 ►◄
viii System Programming APIs