Application Programming APIs

715 Pages·2014·3.6 MB·English

IMS
Version 13
Application Programming APIs
(cid:1)(cid:2)(cid:3)
SC19-3647-01

IMS
Version 13
Application Programming APIs
(cid:1)(cid:2)(cid:3)
SC19-3647-01
Note
Beforeusingthisinformationandtheproductthatitsupports,besuretoreadthegeneralinformationunder“Notices”on
page669.
ThiseditionappliestoIMSVersion13(programnumber5635-A04),IMSDatabaseValueUnitEdition,V13.1
(programnumber5655-DSM),IMSTransactionManagerValueUnitEdition,V13.1(programnumber5655-TM2),
andtoallsubsequentreleasesandmodificationsuntilotherwiseindicatedinneweditions.
©CopyrightIBMCorporation1974,2014.
USGovernmentUsersRestrictedRights–Use,duplicationordisclosurerestrictedbyGSAADPScheduleContract
withIBMCorp.
Contents
About this information . . . . . . . . vii NULLcommandcode . . . . . . . . . 227
Prerequisiteknowledge . . . . . . . . . . vii DEDBcommandcodesforDL/I . . . . . . 228
IMSfunctionnamesusedinthisinformation. . . viii Relationshipbetweencalls,AIBs,andPCBs . . . 235
Hownewandchangedinformationisidentified viii DL/Itestprogram(DFSDDLT0)reference. . . . 236
Howtoreadsyntaxdiagrams . . . . . . . . viii Controlstatements . . . . . . . . . . 237
AccessibilityfeaturesforIMSVersion13 . . . . . x ABENDstatement. . . . . . . . . . . 237
Howtosendyourcomments . . . . . . . . xi CALLstatement . . . . . . . . . . . 238
COMMENTstatement . . . . . . . . . 259
Chapter 1. DL/I calls reference . . . . . 1 COMPAREstatement. . . . . . . . . . 260
IGNOREstatement . . . . . . . . . . 266
Databasemanagement . . . . . . . . . . . 1
OPTIONstatement . . . . . . . . . . 266
DL/Icallsfordatabasemanagement . . . . . 1
PUNCHCTLstatement . . . . . . . . . 268
DL/IcallsforIMSDBsystemservices . . . . 35
STATUSstatement. . . . . . . . . . . 270
Transactionmanagement . . . . . . . . . . 81
WTOstatement. . . . . . . . . . . . 273
DL/Icallsfortransactionmanagement . . . . 81
WTORstatement . . . . . . . . . . . 273
DL/IcallsforIMSTMsystemservices. . . . 123
JCLrequirementsfortheDL/Itestprogram
EXECDLIcommands . . . . . . . . . . 163
(DFSDDLT0). . . . . . . . . . . . . 274
SummaryofEXECDLIcommands . . . . . 164
ExecutionofDFSDDLT0inIMSregions . . . 277
ACCEPTcommand . . . . . . . . . . 165
ExplanationofDFSDDLT0returncodes . . . 278
CHKPcommand . . . . . . . . . . . 165
DFSDDLT0operations . . . . . . . . . 278
DEQcommand. . . . . . . . . . . . 167
DLETcommand . . . . . . . . . . . 168
Chapter 2. DRDA DDM command
GNcommand . . . . . . . . . . . . 169
GNPcommand. . . . . . . . . . . . 174 architecture reference. . . . . . . . 281
GUcommand . . . . . . . . . . . . 180 OverviewofthesyntaxforDDMtermssupported
ISRTcommand. . . . . . . . . . . . 186 byIMS . . . . . . . . . . . . . . . 281
LOADcommand . . . . . . . . . . . 191 DSSHDRsyntax . . . . . . . . . . . 282
LOGcommand. . . . . . . . . . . . 192 DDMcommitandrollbackprocessing . . . . . 282
POScommand . . . . . . . . . . . . 192 DDMcommandsandcommandobjects . . . . 283
QUERYcommand. . . . . . . . . . . 194 ACCRDBcommand(X'2001') . . . . . . . 283
REFRESHcommand . . . . . . . . . . 194 ACCSECcommand(X'106D') . . . . . . . 285
REPLcommand . . . . . . . . . . . 195 CLSQRYcommand(X'2005') . . . . . . . 286
RETRIEVEcommand. . . . . . . . . . 199 CNTQRYcommand(X'2006') . . . . . . . 287
ROLBcommand . . . . . . . . . . . 201 DEALLOCDBcommand(X'C801') . . . . . 289
ROLLcommand . . . . . . . . . . . 202 DLIFUNCcommandobject(X'CC05') . . . . 290
ROLScommand . . . . . . . . . . . 203 DLIFUNCFLGcommandobject(X'CC09') . . . 291
SCHDcommand . . . . . . . . . . . 205 EXCSATcommand(X'1041') . . . . . . . 292
SETScommand. . . . . . . . . . . . 206 EXCSQLIMMcommand(X'200A') . . . . . 294
SETUcommand . . . . . . . . . . . 207 || EXCSQLSETcommand(X'2014') . . . . . . 298
STATcommand . . . . . . . . . . . 208 FLDENTRYcommandobject(X'CC03'). . . . 300
SYMCHKPcommand . . . . . . . . . 208 FLDENTRYRELcommandobject(X'CC0C') . . 301
TERMcommand . . . . . . . . . . . 210 IMSCALLcommand(X'C803'). . . . . . . 301
XRSTcommand . . . . . . . . . . . 211 INAIBcommandobject(X'CC01') . . . . . 302
Commandcodereference . . . . . . . . . 213 || MONITORRDcommand(X'1C00') . . . . . 303
Acommandcode . . . . . . . . . . . 215 OPNQRYcommand(X'200C') . . . . . . . 304
Ccommandcode . . . . . . . . . . . 215 || PRPSQLSTTcommand(X'200D') . . . . . . 308
Dcommandcode . . . . . . . . . . . 216 RLSEcommand(X'C802') . . . . . . . . 310
Fcommandcode . . . . . . . . . . . 218 RTRVFLDcommandobject(X'CC04') . . . . 312
Gcommandcode . . . . . . . . . . . 219 RTRVFLDRELcommandobject(X'CC0B') . . . 312
Lcommandcode . . . . . . . . . . . 219 SECCHKcommand(X'106E') . . . . . . . 313
Ncommandcode . . . . . . . . . . . 220 SEGMLISTcommandobject(X'CC0A') . . . . 314
|| Ocommandcode . . . . . . . . . . . 221 || SQLATTRcommand(X'2450') . . . . . . . 315
Pcommandcode . . . . . . . . . . . 222 || SQLCARDcommand(X'2408'). . . . . . . 316
Qcommandcode . . . . . . . . . . . 223 || SQLDARDcommand(X'2411'). . . . . . . 318
Ucommandcode . . . . . . . . . . . 225 || SQLDTAcommand(X'2412') . . . . . . . 322
Vcommandcode . . . . . . . . . . . 226 || SQLSTTcommand(X'2414') . . . . . . . 324
©CopyrightIBMCorp.1974,2014 iii
SSALISTcommandobject(X'CC06'). . . . . 325 SampleexecsusingREXXTDLI . . . . . . . 381
DDMreplymessagesandreplyobjects. . . . . 326 SAYexec:forexpressionevaluation . . . . . 382
ABNUOWRMreplymessage(X'220D'). . . . 326 PCBINFOexec:displayavailablePCBsin
ACCRDBRMreplymessage(X'2201') . . . . 327 currentPSB . . . . . . . . . . . . . 383
ACCSECRDreplyobject(X'14AC') . . . . . 328 PARTexecs:databaseaccessexamples . . . . 384
AGNPRMRMreplymessage(X'1232') . . . . 329 DOCMD:IMScommandsfrontend . . . . . 387
CMDVLTRMreplymessage(X'221D') . . . . 330 IVPREXXsampleapplication . . . . . . . 391
DEALLOCDBRMreplymessage(X'CA01') . . 330
ENDQRYRMreplymessage(X'220B') . . . . 331 Chapter 4. Java programming
ENDUOWRMreplymessage(X'220C') . . . . 333 reference . . . . . . . . . . . . . 395
EXCSATRDreplyobject(X'1443'). . . . . . 334
IMSUniversaldriverssupportforJDBC . . . . 395
IMSCALLRMreplymessage(X'CA04') . . . . 335
javax.sql.Clobmethodssupported . . . . . 395
OPNQFLRMreplymessage(X'2212') . . . . 336
java.sql.Connectionmethodssupported . . . 395
OPNQRYRMreplymessage(X'2205') . . . . 337
java.sql.DatabaseMetaDatamethodssupported 397
QRYDSCreplyobject(X'241A') . . . . . . 339
javax.sql.DataSourcemethodssupported . . . 401
QRYDTAreplyobject(X'241B') . . . . . . 339
java.sql.Drivermethodssupported . . . . . 401
QRYPOPRMreplymessage(X'220F') . . . . 340
java.sql.ParameterMetaDatamethodssupported 402
RDBAFLRMreplymessage(X'221A') . . . . 341
java.sql.PreparedStatementmethodssupported 402
RDBATHRMreplymessage(X'2203') . . . . 342
java.sql.Statementmethodssupported . . . . 404
RDBNACRMreplymessage(X'2204') . . . . 343
java.sql.ResultSetmethodssupported . . . . 405
RDBNFNRMreplymessage(X'2211') . . . . 344
java.sql.ResultSetMetaDatamethodssupported 410
RDBUPDRMreplymessage(X'2218') . . . . 345
IMSUniversaldriverssupportfortheCommon
RLSERMreplymessage(X'CA03') . . . . . 346
ClientInterface. . . . . . . . . . . . . 411
RSCLMTRMreplymessage(X'1233') . . . . 347
javax.resource.cci.Connectionmethods
SECCHKRMreplymessage(X'1219') . . . . 348
supported . . . . . . . . . . . . . 411
SQLERRRMreplymessage(X'2213'). . . . . 349
javax.resource.cci.ConnectionFactorymethods
DDMparametersusedbyIMS . . . . . . . 350
supported . . . . . . . . . . . . . 412
AIBOALENparameter(X'C904') . . . . . . 350
javax.resource.cci.ConnectionMetaDatamethods
AIBRSNM1parameter(X'C901') . . . . . . 350
supported . . . . . . . . . . . . . 412
AIBRSNM2parameter(X'C902') . . . . . . 351
javax.resource.cci.Interactionmethodssupported 412
AIBSFUNCparameter(X'C903') . . . . . . 351
javax.resource.cci.LocalTransactionmethods
aibStreamdatastructure. . . . . . . . . 351
supported . . . . . . . . . . . . . 413
dbpcbStreamdatastructure . . . . . . . 352
javax.resource.cci.ResultSetInfomethods
iopcbStreamdatastructure. . . . . . . . 353
supported . . . . . . . . . . . . . 413
OUTAIBDBPCBparameter(X'CC02') . . . . 354
javax.resource.cci.ResourceAdapterMetaData
OUTAIBIOPCBparameter(X'CC08'). . . . . 355
methodssupported . . . . . . . . . . 414
RDBNAMparameter(X'2110'). . . . . . . 356
javax.resource.cci.RecordFactorymethods
SSAparameter(X'C906'). . . . . . . . . 357
supported . . . . . . . . . . . . . 414
SSACOUNTparameter(X'C905') . . . . . . 357
JavaAPIdocumentation(Javadoc) . . . . . . 415
UPDCNTparameter(X'C90A') . . . . . . 357
Chapter 5. Message Format Service
Chapter 3. IMS Adapter for REXX
(MFS) reference . . . . . . . . . . 417
reference . . . . . . . . . . . . . 359
MFSapplicationprogramdesign. . . . . . . 417
IMSAdapterforREXXoverview. . . . . . . 360
RelationshipsbetweenMFScontrolblocks. . . 417
Sampleexitroutine(DFSREXXU). . . . . . . 361
Formatlibrarymemberselection . . . . . . 424
Addressingotherenvironments . . . . . . . 361
3270orSLU2screenformatting . . . . . . 427
REXXtransactionprograms . . . . . . . . 361
Devicecompatibilitywithpreviousversionsof
REXXTDLIcommands . . . . . . . . . . 363
MFS . . . . . . . . . . . . . . . 431
REXXTDLIcalls . . . . . . . . . . . . 364
EnhancingsystemperformanceofMFSmessage
REXXIMSextendedcommands . . . . . . . 369
anddeviceformats . . . . . . . . . . 437
DLIINFO. . . . . . . . . . . . . . 369
MFSdefinitionsforintersystemcommunication 442
IMSRXTRC . . . . . . . . . . . . . 370
MFSmessageformats . . . . . . . . . . 444
MAPDEF. . . . . . . . . . . . . . 371
Inputmessageformats . . . . . . . . . 444
MAPGET. . . . . . . . . . . . . . 373
Outputmessageformats. . . . . . . . . 446
MAPPUT. . . . . . . . . . . . . . 374
MFSmessageformattingfunctions . . . . . 480
SET. . . . . . . . . . . . . . . . 375
SRRBACKandSRRCMIT . . . . . . . . 376
Chapter 6. OTMA Callable Interface
STORAGE . . . . . . . . . . . . . 377
API reference . . . . . . . . . . . 551
WTO,WTP,andWTL . . . . . . . . . 378
WTOR. . . . . . . . . . . . . . . 379 OTMACallableInterfaceAPIcalls . . . . . . 551
IMSQUERYextendedfunctions . . . . . . 379 OTMAC/Ihintsandtips . . . . . . . . 551
iv ApplicationProgrammingAPIs
otma_createAPI . . . . . . . . . . . 553 || DESCRIBEOUTPUT . . . . . . . . . . 621
otma_openAPI. . . . . . . . . . . . 554 || EXECUTE . . . . . . . . . . . . . 623
otma_openxAPI . . . . . . . . . . . 556 || FETCH . . . . . . . . . . . . . . 624
otma_allocAPI. . . . . . . . . . . . 557 || INCLUDE . . . . . . . . . . . . . 625
otma_send_receiveAPI . . . . . . . . . 558 || INSERT . . . . . . . . . . . . . . 626
otma_send_receivexAPI. . . . . . . . . 561 || OPEN. . . . . . . . . . . . . . . 629
otma_send_asyncAPI . . . . . . . . . 562 || PREPARE . . . . . . . . . . . . . 631
otma_receive_asyncAPI. . . . . . . . . 564 || SELECT . . . . . . . . . . . . . . 633
otma_freeAPI . . . . . . . . . . . . 566 || UPDATE. . . . . . . . . . . . . . 643
otma_closeAPI. . . . . . . . . . . . 566 || WHENEVER . . . . . . . . . . . . 646
OTMAC/Isampleprograms . . . . . . . . 567 || SQLcommunicationarea(SQLIMSCA). . . . . 647
WarrantyanddistributionforOTMAC/I || DescriptionofSQLIMSCAfields . . . . . . 647
sampleprograms . . . . . . . . . . . 567 || TheincludedSQLIMSCA . . . . . . . . 649
OTMAC/Isampleprogramforsynchronous || SQLdescriptorarea(SQLIMSDA) . . . . . . 649
processing . . . . . . . . . . . . . 567 || DescriptionofSQLIMSDAfields . . . . . . 650
OTMAC/Isampleprogramforasynchronous || TheincludedSQLIMSDA . . . . . . . . 652
processing . . . . . . . . . . . . . 579
Chapter 8. XML support reference . . 655
| Chapter 7. SQL programming SQLextensionsforXMLstorageandretrieval . . 655
|| reference . . . . . . . . . . . . . 593 retrieveXMLUDF . . . . . . . . . . . 655
|| SQLconceptsforIMS . . . . . . . . . . 593 storeXMLUDF. . . . . . . . . . . . 657
|| Structuredquerylanguage . . . . . . . . 593 XQuerysupportintheIMSclassicJDBCdriver 658
|| IMSdatastructuresforSQL . . . . . . . 594 XQueryfunctionandoperationextensionsfor
|| Languageelements . . . . . . . . . . . 598 IMS . . . . . . . . . . . . . . . 658
|| Characters . . . . . . . . . . . . . 598 ExampleofanexpressionusingXQuerysupport
|| Tokens . . . . . . . . . . . . . . 598 intheIMSclassicJDBCdriver. . . . . . . 663
|| Identifiers . . . . . . . . . . . . . 599 StandardXQueryfeaturesinIMS. . . . . . 663
|| Namingconventions . . . . . . . . . . 599 XQueryfunctionsandoperatorssupportedby
|| Datatypes . . . . . . . . . . . . . 600 IMS . . . . . . . . . . . . . . . 665
|| Assignmentandcomparison . . . . . . . 604 RestrictionsforusingtheXQuerysupportinthe
|| Constants . . . . . . . . . . . . . 606 IMSclassicJDBCdriver. . . . . . . . . 667
|| Fieldnames. . . . . . . . . . . . . 607
|| Referencestovariables . . . . . . . . . 608 Notices . . . . . . . . . . . . . . 669
|| HoststructuresinCOBOL . . . . . . . . 610 Programminginterfaceinformation . . . . . . 671
|| Predicates . . . . . . . . . . . . . 610 Trademarks . . . . . . . . . . . . . . 671
|| Searchconditions . . . . . . . . . . . 614 || Privacypolicyconsiderations . . . . . . . . 672
|| Statements . . . . . . . . . . . . . . 615
|| HowSQLstatementsareinvoked . . . . . 615 Bibliography. . . . . . . . . . . . 673
|| CLOSE . . . . . . . . . . . . . . 618
|| DECLARECURSOR . . . . . . . . . . 619
Index . . . . . . . . . . . . . . . 675
|| DECLARESTATEMENT . . . . . . . . 620
|| DELETE . . . . . . . . . . . . . . 621
Contents v
vi ApplicationProgrammingAPIs
About this information
These topics provide reference information for the IMS™ application programming
interfaces (APIs), including DL/I, EXEC DL/I, the classic Java™APIs for IMS, the
IMS Universal drivers, and the Java dependent region resource adapter. The topics
also provide reference information for SQLprogramming for IMS, the IMSAdapter
for REXX, the DL/I test program (DFSDDLT0), and the IMS Message Format
Service (MFS). Guidance information for writing IMS application programs is in
IMS Version 13 Application Programming.
This information is available in IBM® Knowledge Center at www.ibm.com/
support/knowledgecenter.
Prerequisite knowledge
This book is anAPI (application programming interface) reference for IMS
application programming in any of the following environments:
v IMS Database Manager (IMS DB), including IMS Database Control (DBCTL)
v IMS Transaction Manager (IMS TM)
v CICS® EXEC DLI
v WebSphere®Application Server for z/OS®
v WebSphereApplication Server for distributed platforms
v Java dependent regions (JMP and JBP)
v Any environment for stand-alone Java application development
This book provides reference information for the IMS application programming
interfaces (APIs), including DL/I, EXEC DLI, the IMS Universal drivers, and the
Java class libraries for IMS. It also provides reference information for the IMS
Adapter for REXX, the DL/I test program (DFSDDLT0), and the IMS Message
Format Service (MFS). Guidance information for writing IMS application programs
is in IMS Version 13 Application Programming.
Before using this book, you should understand the concepts of application design
described in IMS Version 13 Application Programming, which assumes that you
understand basic z/OS and IMS concepts and the IMS environments. 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++.
To write Java applications, you must thoroughly understand the Java language and
JDBC. This book assumes that you know Java and JDBC. It does not explain any
Java or JDBC concepts.
To create the Java database metadata class, which is a required step in writing Java
applications for IMS using the IMS Universal drivers or the Java class libraries, you
must understand IMS databases. IMS database concepts are described in IMS
Version 13 Database Administration.
To write applications that store or retrieve XML, you must understand XMLand its
related technologies, such as XMLschemas.
©CopyrightIBMCorp.1974,2014 vii
You can learn more about z/OS by visiting the “z/OS basic skills education” topics
in IBM Knowledge Center.
You can gain an understanding of basic IMS concepts by reading An Introduction to
IMS, an IBM Press publication.An excerpt from this publication is available in the
IBM Knowledge Center.
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 IMS home page at
ibm.com/ims and link to the Training and Certification page.
IMS function names used in this information
In this information, the term HALDB Online Reorganization refers to the
integrated HALDB Online Reorganization function that is part of IMS Version 13,
unless otherwise indicated.
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:
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).
(cid:1)(cid:1) required_item (cid:1)(cid:2)
v Optional items appear below the main path.
viii ApplicationProgrammingAPIs