TXSeries for Multiplatforms Application Programming Reference Version 6.2

TXSeries for Multiplatforms

Application Programming Reference Version 6.2

SC34-6640-02

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

Third Edition (January 2008) Order publications through your IBM representative or through the IBM branch office serving your locality. Copyright International Business Machines Corporation 1999, 2008. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

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

About this book . . . . . . . . . . . . . . . . . . . . . . . . xiii Who should read this book . . . . . . . . . . . . . . . . . . . . xiii Document organization . . . . . . . . . . . . . . . . . . . . . . xiii Conventions used in this book . . . . . . . . . . . . . . . . . . . xiv How to send your comments . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Using the CICS API commands . . . . . . . . . . . . . . 1 Command format . . . . . . . . . . . . . . . . . . . . . . . . 1 Conventions used in EXEC CICS commands . . . . . . . . . . . . . . 2 API command argument values . . . . . . . . . . . . . . . . . . . 3

Replacing arguments when programming with COBOL . . . . . . . . . . 3 Replacing arguments when programming with C or C++ . . . . . . . . . 4 Replacing arguments when programming with PL/I . . . . . . . . . . . 5 Data types used in C or C++ . . . . . . . . . . . . . . . . . . . 6 Restrictions on the use of MBCS data . . . . . . . . . . . . . . . . 7

CICS-value data areas (CVDA) . . . . . . . . . . . . . . . . . . . 7 Command options . . . . . . . . . . . . . . . . . . . . . . . . 8

INTO and SET . . . . . . . . . . . . . . . . . . . . . . . . 8 KEYLENGTH and RIDFLD . . . . . . . . . . . . . . . . . . . . 9 LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . 9 NOHANDLE . . . . . . . . . . . . . . . . . . . . . . . . . 9 RESP and RESP2 . . . . . . . . . . . . . . . . . . . . . . 10 SYSID . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 NOEDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 STATE . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Processing the IOERR condition . . . . . . . . . . . . . . . . . . 12 INQUIRE and SET commands . . . . . . . . . . . . . . . . . . . 13

Browsing resource definitions . . . . . . . . . . . . . . . . . . 15 Null values . . . . . . . . . . . . . . . . . . . . . . . . . 16

PERFORM SHUTDOWN SPI Command . . . . . . . . . . . . . . . 17 The CICS API commands by function . . . . . . . . . . . . . . . . 18

Error handling and abnormal termination support commands . . . . . . . 18 APPC Mapped conversation commands . . . . . . . . . . . . . . 18 Authentication commands . . . . . . . . . . . . . . . . . . . . 19 Basic Mapping Support (BMS) commands . . . . . . . . . . . . . . 19 Debugging services commands . . . . . . . . . . . . . . . . . . 19 Configuration services commands . . . . . . . . . . . . . . . . . 19 File services commands . . . . . . . . . . . . . . . . . . . . 21 Timer services commands . . . . . . . . . . . . . . . . . . . . 21 Journal services commands . . . . . . . . . . . . . . . . . . . 21 Program execution services commands . . . . . . . . . . . . . . . 21 Storage services commands . . . . . . . . . . . . . . . . . . . 22 Logical unit of work (LUW) services commands . . . . . . . . . . . . 22 Serialization services commands . . . . . . . . . . . . . . . . . 22 Temporary storage queue services commands . . . . . . . . . . . . 22 Terminal services commands . . . . . . . . . . . . . . . . . . . 22 Transient data queue services commands . . . . . . . . . . . . . . 22

Copyright IBM Corp. 1999, 2008 iii

Chapter 2. CICS API command reference . . . . . . . . . . . . . . 23 CICS API command information layout . . . . . . . . . . . . . . . . 23 ABEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . 24 ALLOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . 26 ASKTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 ASSIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 CHANGE PASSWORD . . . . . . . . . . . . . . . . . . . . . . 38 CHANGE TASK . . . . . . . . . . . . . . . . . . . . . . . . 40 COLLECT STATISTICS . . . . . . . . . . . . . . . . . . . . . . 41 CONNECT PROCESS . . . . . . . . . . . . . . . . . . . . . . 43 CONVERSE (APPC) . . . . . . . . . . . . . . . . . . . . . . . 46 CONVERSE (terminal) . . . . . . . . . . . . . . . . . . . . . . 49 DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DELETEQ TD . . . . . . . . . . . . . . . . . . . . . . . . . 59 DELETEQ TS . . . . . . . . . . . . . . . . . . . . . . . . . 60 DEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 DUMP TRANSACTION . . . . . . . . . . . . . . . . . . . . . . 67 ENDBR . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ENQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 EXTRACT ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . 77 EXTRACT PROCESS . . . . . . . . . . . . . . . . . . . . . . 79 EXTRACT TCPIP . . . . . . . . . . . . . . . . . . . . . . . . 80 FORMATTIME . . . . . . . . . . . . . . . . . . . . . . . . . 83 FREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FREEMAIN . . . . . . . . . . . . . . . . . . . . . . . . . . 87 GETMAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 HANDLE ABEND . . . . . . . . . . . . . . . . . . . . . . . . 91 HANDLE AID . . . . . . . . . . . . . . . . . . . . . . . . . 93 HANDLE CONDITION . . . . . . . . . . . . . . . . . . . . . . 96 IGNORE CONDITION . . . . . . . . . . . . . . . . . . . . . . 98 INQUIRE CONNECTION . . . . . . . . . . . . . . . . . . . . . 99 INQUIRE CONNECTION (browse) . . . . . . . . . . . . . . . . . 104 INQUIRE DSNAME . . . . . . . . . . . . . . . . . . . . . . . 106 INQUIRE FILE . . . . . . . . . . . . . . . . . . . . . . . . 109 INQUIRE FILE (browse) . . . . . . . . . . . . . . . . . . . . . 116 INQUIRE JOURNALNUM . . . . . . . . . . . . . . . . . . . . 118 INQUIRE JOURNALNUM (browse) . . . . . . . . . . . . . . . . . 119 INQUIRE MODENAME . . . . . . . . . . . . . . . . . . . . . 121 INQUIRE PROGRAM . . . . . . . . . . . . . . . . . . . . . . 123 INQUIRE PROGRAM (browse) . . . . . . . . . . . . . . . . . . 129 INQUIRE REQID . . . . . . . . . . . . . . . . . . . . . . . . 130 INQUIRE STATISTICS . . . . . . . . . . . . . . . . . . . . . 135 INQUIRE SYSTEM . . . . . . . . . . . . . . . . . . . . . . . 138 INQUIRE TASK . . . . . . . . . . . . . . . . . . . . . . . . 147 INQUIRE TASK LIST . . . . . . . . . . . . . . . . . . . . . . 155 INQUIRE TCLASS . . . . . . . . . . . . . . . . . . . . . . . 157 INQUIRE TDQUEUE . . . . . . . . . . . . . . . . . . . . . . 158 INQUIRE TDQUEUE (browse) . . . . . . . . . . . . . . . . . . . 163 INQUIRE TERMINAL or NETNAME . . . . . . . . . . . . . . . . . 165 INQUIRE TERMINAL (browse) . . . . . . . . . . . . . . . . . . 184 INQUIRE TRACEDEST . . . . . . . . . . . . . . . . . . . . . 186

iv TXSeries for Multiplatforms: Application Programming Reference

||

||

||

INQUIRE TRANSACTION . . . . . . . . . . . . . . . . . . . . 188 INQUIRE TRANSACTION (browse) . . . . . . . . . . . . . . . . . 193 INQUIRE TSQUEUE . . . . . . . . . . . . . . . . . . . . . . 195 ISSUE ABEND . . . . . . . . . . . . . . . . . . . . . . . . 197 ISSUE CONFIRMATION . . . . . . . . . . . . . . . . . . . . . 198 ISSUE ERROR . . . . . . . . . . . . . . . . . . . . . . . . 200 ISSUE PREPARE . . . . . . . . . . . . . . . . . . . . . . . 202 ISSUE SIGNAL . . . . . . . . . . . . . . . . . . . . . . . . 203 JOURNAL . . . . . . . . . . . . . . . . . . . . . . . . . . 205 LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 PERFORM SNAP API . . . . . . . . . . . . . . . . . . . . . . 213 PERFORM SHUTDOWN . . . . . . . . . . . . . . . . . . . . . 214 PERFORM STATISTICS RECORD . . . . . . . . . . . . . . . . . 215 POP HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . 216 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 PUSH HANDLE . . . . . . . . . . . . . . . . . . . . . . . . 220 READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 READNEXT . . . . . . . . . . . . . . . . . . . . . . . . . 227 READPREV . . . . . . . . . . . . . . . . . . . . . . . . . 233 READQ TD . . . . . . . . . . . . . . . . . . . . . . . . . . 239 READQ TS . . . . . . . . . . . . . . . . . . . . . . . . . . 243 RECEIVE (APPC) . . . . . . . . . . . . . . . . . . . . . . . 246 RECEIVE (terminal) . . . . . . . . . . . . . . . . . . . . . . 249 RECEIVE MAP . . . . . . . . . . . . . . . . . . . . . . . . 252 RELEASE . . . . . . . . . . . . . . . . . . . . . . . . . . 254 RESETBR . . . . . . . . . . . . . . . . . . . . . . . . . . 256 RETRIEVE . . . . . . . . . . . . . . . . . . . . . . . . . . 260 RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . 263 REWRITE . . . . . . . . . . . . . . . . . . . . . . . . . . 266 SEND (APPC) . . . . . . . . . . . . . . . . . . . . . . . . . 270 SEND (terminal) . . . . . . . . . . . . . . . . . . . . . . . . 272 SEND CONTROL . . . . . . . . . . . . . . . . . . . . . . . 274 SEND MAP . . . . . . . . . . . . . . . . . . . . . . . . . . 276 SEND TEXT . . . . . . . . . . . . . . . . . . . . . . . . . 279 SET CONNECTION . . . . . . . . . . . . . . . . . . . . . . 282 SET FILE . . . . . . . . . . . . . . . . . . . . . . . . . . 284 SET FILE CLOSED . . . . . . . . . . . . . . . . . . . . . . . 290 SET FILE DISABLED . . . . . . . . . . . . . . . . . . . . . . 292 SET FILE ENABLED . . . . . . . . . . . . . . . . . . . . . . 294 SET FILE OPEN . . . . . . . . . . . . . . . . . . . . . . . . 295 SET JOURNALNUM . . . . . . . . . . . . . . . . . . . . . . 296 SET PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . 298 SET STATISTICS . . . . . . . . . . . . . . . . . . . . . . . 303 SET SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . 308 SET TASK . . . . . . . . . . . . . . . . . . . . . . . . . . 312 SET TCLASS . . . . . . . . . . . . . . . . . . . . . . . . . 314 SET TDQUEUE . . . . . . . . . . . . . . . . . . . . . . . . 315 SET TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . 318 SET TRACEDEST . . . . . . . . . . . . . . . . . . . . . . . 326 SET TRANSACTION . . . . . . . . . . . . . . . . . . . . . . 328 SIGNOFF . . . . . . . . . . . . . . . . . . . . . . . . . . 331 SIGNON . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 START . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 STARTBR . . . . . . . . . . . . . . . . . . . . . . . . . . 340 SUSPEND . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Contents v

SYNCPOINT . . . . . . . . . . . . . . . . . . . . . . . . . 346 TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 UNLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . 349 VERIFY PASSWORD . . . . . . . . . . . . . . . . . . . . . . 352 WAIT CONVID . . . . . . . . . . . . . . . . . . . . . . . . 354 WAIT EVENT . . . . . . . . . . . . . . . . . . . . . . . . . 355 WAIT JOURNAL . . . . . . . . . . . . . . . . . . . . . . . . 357 WAIT TERMINAL . . . . . . . . . . . . . . . . . . . . . . . 359 WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 WRITE OPERATOR . . . . . . . . . . . . . . . . . . . . . . 365 WRITEQ TD . . . . . . . . . . . . . . . . . . . . . . . . . 367 WRITEQ TS . . . . . . . . . . . . . . . . . . . . . . . . . 369 XCTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

Chapter 3. Java API command reference . . . . . . . . . . . . . . 375 Support for Java beans . . . . . . . . . . . . . . . . . . . . . 375 Resource identification . . . . . . . . . . . . . . . . . . . . . 375 Method arguments . . . . . . . . . . . . . . . . . . . . . . . 376

Endianess . . . . . . . . . . . . . . . . . . . . . . . . . 376 Memory management . . . . . . . . . . . . . . . . . . . . . . 376 Length restrictions . . . . . . . . . . . . . . . . . . . . . . . 376 Exception handling . . . . . . . . . . . . . . . . . . . . . . . 376 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 The Java Security Manager . . . . . . . . . . . . . . . . . . . . 380 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . 380 Description of the CICS Java API . . . . . . . . . . . . . . . . . 381

Error handling and abnormal termination support . . . . . . . . . . . 381 APPC mapped conversations . . . . . . . . . . . . . . . . . . 381 Authentication . . . . . . . . . . . . . . . . . . . . . . . . 382 Basic Mapping Support . . . . . . . . . . . . . . . . . . . . 383

Building a CICS Java application . . . . . . . . . . . . . . . . . . 389 CICS Java API examples . . . . . . . . . . . . . . . . . . . . 391

Chapter 4. FEPI application programming reference . . . . . . . . . 393 Command format . . . . . . . . . . . . . . . . . . . . . . . 393 Arguments and data types . . . . . . . . . . . . . . . . . . . . 394 Errors and exception conditions . . . . . . . . . . . . . . . . . . 394 Syntax notation . . . . . . . . . . . . . . . . . . . . . . . . 394 FEPI INQUIRE and SET commands . . . . . . . . . . . . . . . . 395

Other points . . . . . . . . . . . . . . . . . . . . . . . . 395 FEPI ADD POOL . . . . . . . . . . . . . . . . . . . . . . . 395 FEPI ALLOCATE PASSCONVID . . . . . . . . . . . . . . . . . . 397 FEPI ALLOCATE POOL . . . . . . . . . . . . . . . . . . . . . 397 FEPI AP NOOP . . . . . . . . . . . . . . . . . . . . . . . . 399 FEPI CONVERSE DATASTREAM . . . . . . . . . . . . . . . . . 399 FEPI CONVERSE FORMATTED . . . . . . . . . . . . . . . . . . 403 FEPI DELETE POOL . . . . . . . . . . . . . . . . . . . . . . 408 FEPI DISCARD NODELIST . . . . . . . . . . . . . . . . . . . . 409 FEPI DISCARD POOL . . . . . . . . . . . . . . . . . . . . . 409 FEPI DISCARD PROPERTYSET . . . . . . . . . . . . . . . . . . 410 FEPI DISCARD TARGETLIST . . . . . . . . . . . . . . . . . . . 410 FEPI EXTRACT CONV . . . . . . . . . . . . . . . . . . . . . 411 FEPI EXTRACT FIELD . . . . . . . . . . . . . . . . . . . . . 413 FEPI EXTRACT STSN . . . . . . . . . . . . . . . . . . . . . 415 FEPI FREE . . . . . . . . . . . . . . . . . . . . . . . . . . 416 FEPI INQUIRE CONNECTION . . . . . . . . . . . . . . . . . . 417

vi TXSeries for Multiplatforms: Application Programming Reference

||||||||||||||||||||||||||||||||||||

FEPI INQUIRE NODE . . . . . . . . . . . . . . . . . . . . . . 421 FEPI INQUIRE POOL . . . . . . . . . . . . . . . . . . . . . . 422 FEPI INQUIRE PROPERTYSET . . . . . . . . . . . . . . . . . . 426 FEPI INQUIRE TARGET . . . . . . . . . . . . . . . . . . . . . 429 FEPI INSTALL NODELIST . . . . . . . . . . . . . . . . . . . . 430 FEPI INSTALL POOL . . . . . . . . . . . . . . . . . . . . . . 432 FEPI INSTALL PROPERTYSET . . . . . . . . . . . . . . . . . . 434 FEPI INSTALL TARGETLIST . . . . . . . . . . . . . . . . . . . 437 FEPI ISSUE . . . . . . . . . . . . . . . . . . . . . . . . . 439 FEPI RECEIVE DATASTREAM . . . . . . . . . . . . . . . . . . 441 FEPI RECEIVE FORMATTED . . . . . . . . . . . . . . . . . . . 444 FEPI REQUEST PASSTICKET . . . . . . . . . . . . . . . . . . 446 FEPI SEND DATASTREAM . . . . . . . . . . . . . . . . . . . . 447 FEPI SEND FORMATTED . . . . . . . . . . . . . . . . . . . . 449 FEPI SET CONNECTION . . . . . . . . . . . . . . . . . . . . 451 FEPI SET NODE . . . . . . . . . . . . . . . . . . . . . . . 452 FEPI SET POOL . . . . . . . . . . . . . . . . . . . . . . . . 454 FEPI SET TARGET . . . . . . . . . . . . . . . . . . . . . . . 455 FEPI SP NOOP . . . . . . . . . . . . . . . . . . . . . . . . 456 FEPI START . . . . . . . . . . . . . . . . . . . . . . . . . 456 Start data . . . . . . . . . . . . . . . . . . . . . . . . . . 458

Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Data formats . . . . . . . . . . . . . . . . . . . . . . . . . 460

Outbound data . . . . . . . . . . . . . . . . . . . . . . . 460 Inbound data . . . . . . . . . . . . . . . . . . . . . . . . 461

Ending status . . . . . . . . . . . . . . . . . . . . . . . . . 461 Transient data queue records . . . . . . . . . . . . . . . . . . . 463

Appendix A. EXEC interface block (EIB) fields . . . . . . . . . . . . 467

Appendix B. BMS-related constants . . . . . . . . . . . . . . . . 487 Field attributes and printer control characters . . . . . . . . . . . . . 487

Bit map of attributes . . . . . . . . . . . . . . . . . . . . . 489 Attention identifier constants list (DFHAID) . . . . . . . . . . . . . . 491

Appendix C. Translated code for CICS API commands . . . . . . . . 493

Appendix D. CICS terminal control . . . . . . . . . . . . . . . . 495 Commands and options for terminals and logical units . . . . . . . . . . 495

32-bit lengths . . . . . . . . . . . . . . . . . . . . . . . . 495 Read from terminal or logical unit (RECEIVE) . . . . . . . . . . . . 495 Write to terminal or logical unit (SEND) . . . . . . . . . . . . . . 496 Synchronize terminal I/O for a transaction (WAIT TERMINAL) . . . . . . 496 Converse with terminal or logical unit (CONVERSE) . . . . . . . . . . 496 Send an asynchronous interrupt (ISSUE SIGNAL) . . . . . . . . . . 496

Display device operations . . . . . . . . . . . . . . . . . . . . 497 Erase all unprotected fields (SEND CONTROL ERASEAUP) . . . . . . 497 Input operation without data (RECEIVE) . . . . . . . . . . . . . . 497

Appendix E. Defining BMS mapsets, maps, and fields . . . . . . . . . 499 Processing BMS maps . . . . . . . . . . . . . . . . . . . . . 499 Defining field groups . . . . . . . . . . . . . . . . . . . . . . 499 Coding the BMS definition macros . . . . . . . . . . . . . . . . . 500 DFHMDF . . . . . . . . . . . . . . . . . . . . . . . . . . 501 DFHMDI . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 DFHMSD . . . . . . . . . . . . . . . . . . . . . . . . . . 516

Contents vii

Appendix F. CVDAs recognized by the translator . . . . . . . . . . . 525 CVDAs sorted by symbolic name . . . . . . . . . . . . . . . . . . 525 CVDAs sorted by numeric value . . . . . . . . . . . . . . . . . . 539

Appendix G. CICS conditions . . . . . . . . . . . . . . . . . . 553

Appendix H. The Query Transaction Class interface . . . . . . . . . 557 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . 557 CICS_AdmCloseHandle . . . . . . . . . . . . . . . . . . . . . 558 CICS_AdmFreeStorage . . . . . . . . . . . . . . . . . . . . . 558 CICS_AdmOpenRegion . . . . . . . . . . . . . . . . . . . . . 559 CICS_AdmQueryTClass . . . . . . . . . . . . . . . . . . . . . 560

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Trademarks and service marks . . . . . . . . . . . . . . . . . . 564

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

viii TXSeries for Multiplatforms: Application Programming Reference

Figures 1. Browsing the Program Definitions (PD) with COBOL . . . . . . . . . . . . . . . . . . 16

Copyright IBM Corp. 1999, 2008 ix

x TXSeries for Multiplatforms: Application Programming Reference

Tables 1. Road map for the Application Programming Reference book . . . . . . . . . . . . . . . xiii 2. Conventions that are used in this book . . . . . . . . . . . . . . . . . . . . . . . xiv 3. Arguments used in COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Argument values used in C or C++ . . . . . . . . . . . . . . . . . . . . . . . . 4 5. Data types contained in cicstype.h . . . . . . . . . . . . . . . . . . . . . . . . . 7 6. Error handling and abnormal termination support . . . . . . . . . . . . . . . . . . . 18 7. Advanced program-to-program communications (APPC) mapped conversation . . . . . . . . 18 8. Authentication Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 9. Basic Mapping Support (BMS) . . . . . . . . . . . . . . . . . . . . . . . . . . 19 10. Debugging services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 11. Configuration services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 12. File services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 13. Timer services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 14. Journal services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 15. Program execution services . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 16. Storage services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 17. Logical unit of work (LUW) services . . . . . . . . . . . . . . . . . . . . . . . . 22 18. Serialization services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 19. Temporary storage queue services . . . . . . . . . . . . . . . . . . . . . . . . 22 20. Terminal services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 21. Transient data queue services . . . . . . . . . . . . . . . . . . . . . . . . . . 22 22. Correspondence between IBM mainframe-based CICS tables and TXSeries for Multiplatforms

resource definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 23. Correspondence between IBM mainframe-based CICS tables and TXSeries for Multiplatforms

resource definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 24. Mapping between CICS conditions and Java exceptions . . . . . . . . . . . . . . . . 378 25. APPC mapped conversations and Java classes . . . . . . . . . . . . . . . . . . . 382 26. Classes and methods for keyed files . . . . . . . . . . . . . . . . . . . . . . . 385 27. Classes and methods for nonkeyed files . . . . . . . . . . . . . . . . . . . . . . 386 28. ENDSTATUS values and associated meanings . . . . . . . . . . . . . . . . . . . 462 29. Hex values returned with EIBERRCD and their meanings . . . . . . . . . . . . . . . 469 30. EIBFN code that contains the last CICS command to be used . . . . . . . . . . . . . . 470 31. EIBRCODE values and corresponding conditions . . . . . . . . . . . . . . . . . . 474 32. RESP values in decimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 33. RESP2 values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 34. EIBRSRCE that specifies resource being accessed . . . . . . . . . . . . . . . . . . 483 35. Standard Attribute and Printer Control Character List, DFHBMSCA . . . . . . . . . . . . 487 36. Bit map of attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 37. Standard DFHAID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 38. Suffix used for terminal types . . . . . . . . . . . . . . . . . . . . . . . . . . 523 39. CVDAs sorted by symbolic name . . . . . . . . . . . . . . . . . . . . . . . . 525 40. CVDAs sorted by numeric value . . . . . . . . . . . . . . . . . . . . . . . . . 539

Copyright IBM Corp. 1999, 2008 xi

|||||||||||

xii TXSeries for Multiplatforms: Application Programming Reference

About this book This book describes the TXSeries for Multiplatforms application programming interface (API). It contains reference information that you need when you use CICS API commands to prepare application programs on the following platforms: AIX, HP-UX, Solaris, and Windows. Supported programming languages include COBOL, PL/I, C, and C++. (HP-UX does not support C++; HP-UX and Solaris do not support PL/I.)

Guidance information is in the TXSeries for Multiplatforms Application Programming Guide and the TXSeries for Multiplatforms Problem Determination Guide. For information about debugging CICS applications, see the TXSeries for Multiplatforms Problem Determination Guide.

Who should read this book The book is intended primarily for use by application programmers, but will also be useful to system programmers and systems analysts. Because CICS resource definitions are referred to throughout this book, you should be familiar with how they are defined and used in CICS. Resource definitions are described in the TXSeries for Multiplatforms Administration Reference. Programming for intercommunications requires a working knowledge of TCP/IP, SNA, or both, and might require a working knowledge of the PPC Gateway server.

Document organization Table 1. Road map for the Application Programming Reference book

If you want to... Refer to... Look up syntax and parameters of an API command

Chapter 1, Using the CICS API commands, on page 1.

Read about individual commands Chapter 2, CICS API command reference, on page 23.

Look up FEPI application programming commands

Chapter 4, FEPI application programming reference, on page 393

Look up EXEC interface block (EIB) fields Appendix A, EXEC interface block (EIB) fields, on page 467.

Look up BMS-related constants Appendix B, BMS-related constants, on page 487.

Look up translated code for CICS API commands

Appendix C, Translated code for CICS API commands, on page 493.

Look up CICS terminal control Appendix D, CICS terminal control, on page 495.

Define BMS mapsets, maps, and fields Appendix E, Defining BMS mapsets, maps, and fields, on page 499.

Look up CVDAs recognized by the translator Appendix F, CVDAs recognized by the translator, on page 525.

Look up CICS conditions Appendix G, CICS conditions, on page 553. Read about the conventions used in this book.

xiv.

Copyright IBM Corp. 1999, 2008 xiii

This book is for reference. The commands that are described in Chapter 2, CICS API command reference, on page 23 are listed in alphabetical order and use a standard format, as follows: v The syntax of the command v A description of what the command does v An alphabetical list of the options and their functions v An alphabetical list of conditions, and their causes, that can occur during the

execution of a command (as required) v Examples (as required)

Review Chapter 1, Using the CICS API commands, on page 1 before using the command reference, because that chapter provides general information about the commands. You will be referred to the appendixes as required.

This book contains information for all TXSeries for Multiplatforms products. Where the information is different for a specific TXSeries for Multiplatforms product, the words on product are used in line with the text, usually in a list or enclosed in parenthesis. Refer to the following example: v /usr/lpp/cics on CICS for AIX v /opt/cics on CICS for HP-UX v /opt/cics on CICS for Solaris.

Conventions used in this book TXSeries for Multiplatforms documentation uses the following typographical and keying conventions.

Table 2. Conventions that are used in this book Convention Meaning Bold Indicates values that you must use literally, such as commands,

functions, and resource definition attributes and their values. When referring to graphical user interfaces (GUIs), bold also indicates menus, menu items, labels, buttons, icons, and folders.

Monospace Indicates text that you must enter at a command prompt. Monospace also indicates screen text and code examples.

Italics Indicates variable values that you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books.

< > Encloses the names of keys on the keyboard. Where x is the name of a key, indicates a control-character

sequence. For example, means hold down the Ctrl key while you press the c key.

Refers to the key labeled with the word Return, the word Enter, or the left arrow.

% Represents the UNIX command-shell prompt for a command that does not require root privileges.

# Represents the UNIX command-shell prompt for a command that requires root privileges.

C:\> Represents the Windows command prompt. > When used to describe a menu, shows a series of menu selections.

For example, Select File > New means From the File menu, select the New command.

xiv TXSeries for Multiplatforms: Application Programming Reference

Table 2. Conventions that are used in this book (continued) Convention Meaning Entering commands When instructed to enter or issue a command, type the command

and then press . For example, the instruction Enter the ls command means type ls at a command prompt and then press .

[ ] Encloses optional items in syntax descriptions. { } Encloses lists from which you must choose an item in syntax

descriptions. | Separates items in a list of choices enclosed in { } (braces) in syntax

descriptions. ... Ellipses in syntax descriptions indicate that you can repeat the

preceding item one or more times. Ellipses in examples indicate that information was omitted from the example for the sake of brevity.

IN In function descriptions, indicates parameters whose values are used to pass data to the function. These parameters are not used to return modified data to the calling routine. (Do not include the IN declaration in your code.)

OUT In function descriptions, indicates parameters whose values are used to return modified data to the calling routine. These parameters are not used to pass data to the function. (Do not include the OUT declaration in your code.)

INOUT In function descriptions, indicates parameters whose values are passed to the function, modified by the function, and returned to the calling routine. These parameters serve as both IN and OUT parameters. (Do not include the INOUT declaration in your code.)

$CICS Indicates the full path name of the location in which the CICS product is installed; for example, /usr/lpp/cics on AIX. If the CICS environment variable is set to the product path name, you can use the examples exactly as shown in this book; otherwise, you must replace all instances of $CICS with the CICS product path name.

CICS on Open Systems

Refers collectively to the CICS product for all supported UNIX platforms.

TXSeries for Multiplatforms

Refers collectively to the CICS for AIX, CICS for HP-UX (HP-UX PA-RISC and HP-UX IPF), CICS for Solaris, and CICS for Windows products.

CICS Refers generically to the CICS for AIX, CICS for HP-UX, CICS for Solaris, and CICS for Windows products. Other CICS products in the CICS Family are distinguished by their operating system (for example, IBM mainframe-based CICS for the z/OS platform).

How to send your comments Your feedback is important in helping to provide the most accurate and highest quality information. If you have any comments about this book or any other TXSeries for Multiplatforms documentation, send your comments by e-mail to [email protected]. Be sure to include the name of the book, the document number of the book, the version of TXSeries for Multiplatforms, and, if applicable, the specific location of the information you are commenting on (for example, a page number or table number).

About this book xv

xvi TXSeries for Multiplatforms: Application Programming Reference

Chapter 1. Using the CICS API commands This chapter provides general information about the use of the CICS API commands.

Chapter 2, CICS API command reference, on page 23 shows the syntax of each command, describes the purpose and format of each command and its options, and lists the conditions that can arise during the running of each command.

For information about translating the commands, refer to the cicstran and cicstcl command descriptions in the TXSeries for Multiplatforms Application Programming Guide.

Command format The general format of a CICS command is EXECUTE CICS (or EXEC CICS) followed by the name of the required command, and possibly by one or more options, as follows:

EXEC CICS command [ option [ (arg) ] ]....

where:

command Describes the operation required (for example, READ).

option Describes any of the many optional facilities that are available with each function. Some options are followed by an argument in parentheses. You can write options (including those that require arguments) in any sequence.

arg (Short for argument) are values such as data-value, name, or data-area. Depending on the type that is given in the argument value, these can supply data to, or receive data from, CICS. For example, an argument value of data-value can be a constant, which would mean that the argument provides data to CICS. Examples of argument values that receive data from CICS are a data-area or a ptr-ref. For further information, see API command argument values on page 3.

The EXEC CICS commands are not case-sensitive.

An example of a CICS command: EXEC CICS READ FILE(FILEA) INTO(FILEA) RIDFLD(KEYNUM) UPDATE

You must add the appropriate end-of-command delimiter. This is described in Conventions used in EXEC CICS commands on page 2.

Copyright IBM Corp. 1999, 2008 1

Conventions used in EXEC CICS commands In the CICS documentation, the syntax of application programming commands is as follows:

Symbol Action

A B

C

A set of alternatives, one of which you must code.

A

B

C

A set of alternatives, one of which you can code.

A

B

C

A set of alternatives, of which you can code as many as you choose.

A

B

Alternatives where A is the default.

Name

Name:

A

B

Use with the named section in place of its name.

Punctuation and uppercase characters

Code exactly as shown.

Lowercase characters

Code your own text, as appropriate (for example, name).

The following symbols are used to show how to code the commands. These symbols are not part of the command and must not be included in the code. v Brackets [ ] show that the enclosed is optional; you can, but need not, code the

enclosed options. v Braces { } enclose a set of alternatives, one of which you must code. v A logical OR symbol | separates alternatives. If the alternatives are between {

and }, you must code one of them. If they are between [ and ], you can code one of them.

2 TXSeries for Multiplatforms: Application Programming Reference

v Underlining shows a default option that is assumed unless you specify otherwise (for example, the NEXT option of READQ TS).

v An ellipsis (...) shows that you can code the immediately preceding options more than once. Therefore, to show that either GTEQ or EQUAL, or neither, can be coded, and that EQUAL is the default, the syntax is: [GTEQ|EQUAL]

v Options that are not enclosed in either braces { } or square brackets [ ] are mandatory.

v The words EXEC CICS that precede the command are not always shown in the examples or descriptions; nor is the terminator that you must code at the end of each CICS command. For COBOL programs, the terminator is END-EXEC. For C or C++ programs, the terminator is a semicolon (;).

v Punctuation symbols must be coded exactly as shown. v Lowercase characters show argument values. For example, the FILE option of

the READ command is shown as: FILE(name)

In this case, name is replaced with the name of the file. You must code READ FILE and ( ) as shown. Commands can be entered in lowercase and you are free to code any valid text string for the name of the file.

API command argument values The parenthesized arguments that follow options in an API command are specified as follows: v data-value v data-area v CICS-value data area (or cvda) v pointer-value (or ptr-value) v pointer-ref (or ptr-ref) v name v label v hhmmss

Replacing arguments when programming with COBOL You can replace the arguments as follows:

Table 3. Arguments used in COBOL This argument: Can be replaced by: data-value Any COBOL data name of the correct data type for the argument, or by

a constant that can be converted to the correct type for the argument. You can specify the data type as one of the following: v 16-bit binary: PIC S9(4) COMP v 32-bit binary: PIC S9(8) COMP v Character string: PIC X(n), where n is the number of bytes

data-area Any COBOL data name of the correct data type for the argument. You can specify the data type as one of the following: v 16-bit binary: PIC S9(4) COMP v 32-bit binary: PIC S9(8) COMP v Character string: PIC X(n), where n is the number of bytesIf the data type is unspecified, the data area can refer to an elementary or group item.

Chapter 1. Using the CICS API commands 3

Table 3. Arguments used in COBOL (continued) This argument: Can be replaced by: cvda A CICS-value data area (CVDA). For more information, see CICS-value

data areas (CVDA) on page 7. pointer-ref or ptr-ref

A pointer variable or a COBOL data name preceded by ADDRESS OF.

name Either of the following: v A character string in single quotation marks (that is, a nonnumeric

literal). If this is shorter than the required length, CICS pads the string with blanks to the right of the string.

v A COBOL data area with a length equal to the length that is required for the name. If the data area is shorter than the required length, the excess characters are undefined.

label Any COBOL paragraph name or a section name. hhmmss Any COBOL data name of the data type PIC S9(7) COMP-3 or, for input

arguments only, by a decimal constant that COBOL can convert to the same data type. The value, whether input or output, is of the form 0HHMMSS+, where: v hh represents hours 00 through 99 v mm represents minutes 00 through 59 v ss represents seconds 00 through 59

In COBOL, you need not code the LENGTH option unless you want the program to read or write data of a length that is different from that of the referenced variable. To avoid truncation of data, compile COBOL programs with the NOTRUNC option.

Note: BLL cells and SERVICE RELOAD statements are not supported in the COBOL products that are used with TXSeries for Multiplatforms and IBM CICS for Windows. Therefore, you must modify any COBOL programs that use BLL cells or SERVICE RELOAD statements before migrating. For further information about migrating, see the TXSeries for Multiplatforms Application Programming Guide.

Replacing arguments when programming with C or C++ You can replace the arguments as follows:

Table 4. Argument values used in C or C++ This argument: Can be replaced by: data-value Any C or C++ expression that C or C++ can convert to the correct data

type for the argument. You can specify the data type as one of the following: v 16-bit binary: cics_sshort_t v 32-bit binary: cics_slong_t v Character string: char[n], where n is the number of bytesData-value includes data-area as a subset.

All data-value variables are passed as call-by-value.


Table 4. Argument values used in C or C++ (continued) This argument: Can be replaced by: data-area Any C or C++ data reference that has the correct data type for the

argument. You can specify the data type as one of the following: v 16-bit binary: cics_sshort_t v 32-bit binary: cics_slong_t v Character string: char[n], where n is the number of bytesIf the data type is unspecified, the data area can refer to a scalar data type, array, or structure. The reference must be to contiguous storage.

All data-area variables are passed as call-by-reference. cvda A CICS-value data area (CVDA). For more information, see CICS-value

data areas (CVDA) on page 7. pointer-ref or ptr-ref

Any C pointer type reference.

name Either of the following: v A character string in double quotation marks (that is, a literal

constant). v Any C or C++ expression or data reference whose value C or C++

can convert to a character array with a length that is equal to the maximum length that is allowed for the name. The value of the character array is the name that is to be used by the argument.

label label is not supported for the C or C++ language. hhmmss hhmmss is not supported for the C or C++ language.

Many commands involve the transfer of data between the application program and CICS. In most cases, the LENGTH option must be specified if SET is used; the syntax of each command and its associated options show whether this rule applies.

Replacing arguments when programming with PL/I You can replace the arguments as follows: v data-value can be replaced by any PL/I expression that can be converted to the

correct data type for the argument. The data type can be specified as one of the following: Halfword binary: FIXED BIN(15) Fullword binary: FIXED BIN(31) Character string: CHAR(n) where n is the number of bytes. data-value includes data-area as a subset.

v data-area can be replaced by any PL/I data reference that has the correct data type for the argument. The data type can be specified as one of the following: Halfword binary: FIXED BIN(15) Fullword binary: FIXED BIN(31) Character string: CHAR(n) where n is the number of bytes. If the data type is unspecified, data-area can refer to an element, array, or structure; for example, FROM(P>STRUCTURE) LENGTH(LNG). The reference must be to connected storage. The data area must also have the correct PL/I alignment attribute: ALIGNED for binary items, and UNALIGNED for strings. If you use a varying data string without an explicit length, the data that is passed begins with two length bytes, and its length is the maximum length that is


declared for the string. If you explicitly specify a length in the command, the data that is passed has this length; that is, the two length bytes followed by data up to the length that you specified.

v ptr-value (which includes ptr-ref as a subset) can be replaced by any PL/I expression that can be converted to POINTER.

v ptr-ref can be replaced by any PL/I reference of type POINTER ALIGNED. v name can be replaced by either of the following:

A character string in single quotation marks (that is, a literal constant). A PL/I expression or reference whose value can be converted to a character

string with a length that is equal to the maximum length that is allowed for the name. The value of the character string is the name that is to be used by the argument.

filename, as used in FILE(filename), specifies the name of the file. It has 1 through 8 characters, which can be from A through Z, 0 through 9, $, @, and #, (lowercase characters are converted to uppercase). systemname, as used in SYSID(systemname), specifies the name of the system to which the request is directed. It has 1 through 4 characters, which an be from A through Z, 0 through 9, $, @, and #, (lowercase characters are converted to uppercase).

v label can be replaced by any PL/I expression whose value is a label. v hhmmss can be replaced by a decimal constant or an expression that can be

converted to a FIXED DECIMAL(7,0). The value must be of the form 0HHMMSS+ where: HH represents hours 00 through 99. MM represents minutes 00 through 59. SS represents seconds 00 through 59.

If a DEFAULT DESCRIPTORS statement adds the UNALIGNED attribute to the ENTRY declarations that were generated by the CICS translator, data-area or pointer-reference arguments to CICS commands must also be UNALIGNED. Similarly for the ALIGNED attribute, data-area or pointer-reference arguments must be ALIGNED.

Many commands involve the transfer of data between the application program and CICS.

In most cases, the length of the data that is to be transferred must be provided by the application program. However, if a data area is specified as the source or target, it is not necessary to provide the length explicitly, because the command-language translator generates a default length value of either STG(data-area) or CSTG(data-area), as appropriate.

Data types used in C or C++ To assist in writing portable C transactions, CICS supplies a C or C++ header file that contains data type definitions for variables that are to be used in EXEC CICS API calls. This header file is named cicstype.h and on Open Systems is in: $CICS/include (see note)

and on Windows is in: prodDir\include (see note)

Note: Refer to Conventions used in this book on page xiv for a description of the product path name.


The data types that are contained in cicstype.h are as follows: Table 5. Data types contained in cicstype.h

cics_char_t A character cics_ubyte_t An 8-bit unsigned binary value cics_ushort_t A 16-bit unsigned binary value cics_sshort_t A 16-bit signed binary value cics_ulong_t A 32-bit unsigned binary value cics_slong_t A 32-bit signed binary value cics_bool_t A boolean data type cics_uxlong_t A 64-bit unsigned binary value cics_sxlong_t A 64-bit signed binary value

Restrictions on the use of MBCS data Some languages require characters to be represented by multiple bytes in what is called a multibyte character set (MBCS). CICS supports application programs that use MBCS code pages. This support is implemented with the cicstran -g option when the source code is translated. See the TXSeries for Multiplatforms Application Programming Guide for information about cicstran.

Particular command options, however, accept only values that are received from the ASCII (single byte) character set. In general, these are the options that correspond to the names of resources that CICS manages, such as files and transient data queues.

Where the application programming information documents the length as a number of bytes, such as 16-bit binary or 32-bit binary, that option is capable of accepting MBCS data. Where the length is documented as a number of characters, the option accepts only ASCII.

Note: CICS for AIX and CICS for HP-UX are the only systems that support MBCS data.

CICS-value data areas (CVDA) Some API commands have options that give the status or definition of a resource. For example, the STATE option on the CONNECT PROCESS command returns the state of the current conversation. Also, the INQUIRE and SET commands have many options that refer to resource status or definition. These options all have values that are CICS-supplied and are known as CICS-value data areas. They are shown in the syntax of commands with cvda in parentheses after the option name. In other contexts, uppercase letters (CVDA) are used.

You pass a CVDA value to CICS in one of two ways, depending on the conditions: In flexible form

You can use the DFHVALUE translator built-in function to assign a CVDA value to the 32-bit binary data area that is specified on the command, as in the following COBOL example: MOVE DFHVALUE(EMPTYREQ) TO AREA-A. EXEC CICS SET FILE(filename) EMPTYSTATUS(AREA-A) END-EXEC.


In short form If the required CVDA value is always the same for a particular command, you can specify this value directly as an option on the command, as in the following COBOL example: EXEC CICS SET FILE(filename) EMPTYREQ END-EXEC.

When an API command returns a CVDA value, define a 32-bit binary data area and pass this data area onto the appropriate command option. You can then use the DFHVALUE translator built-in function to test the returned value, as in the following COBOL example: EXEC CICS CONNECT PROCESS .... STATE(AREA-A) END-EXEC. IF AREA-A = DFHVALUE(ALLOCATED) THEN ...

Note: When using the Command-Level Interpreter (CECI) or the Execution Diagnostic Facility (EDF), CICS displays CVDAs on the screen as numeric values rather than as their corresponding symbolic names.

For a complete list of the CVDA symbolic names that are recognized by CICS and their associated numeric values, see Appendix F, CVDAs recognized by the translator, on page 525.

For more information about the STATE option, refer to STATE on page 11.

Command options This section provides information about using the following options that appear on several commands: v INTO and SET v KEYLENGTH and RIDFLD v LENGTH v NOHANDLE v RESP and RESP2 v SYSID v NOEDF v STATE v FILE

For more information about attention identifiers (AIDs), see HANDLE AID on page 93.

For information about the CICS Execution Diagnostic Facility (CEDF), see TXSeries for Multiplatforms Administration Reference.

INTO and SET If an application is to receive data by issuing a RECEIVE command, you must specify either the INTO or the SET option. These options specify the address of data that is received. The guidelines for using either INTO or SET are as follows: v Use INTO if your application program provides a suitable buffer to which CICS

should return data.


v Use SET if you want CICS to obtain a suitably sized buffer. Note that CICS might, at a later time, reuse buffers that were generated with the SET option. The minimum life of a SET buffer varies from command to command and is documented with each command.

If an application issues a RECEIVE command simply to test whether a terminal user has pressed an attention identifier (AID) key, you can leave out both the INTO and the SET option. If an application uses a RECEIVE to accept an AID, ensure that the application issues a HANDLE AID command before the RECEIVE. See HANDLE AID on page 93 for more information about the attention identifier keys.

KEYLENGTH and RIDFLD Unless a GENERIC key is used, the KEYLENGTH must always be equal to the full key length of the file. Also, the KEYLENGTH indicates the size of the RIDFLD data area.

LENGTH In COBOL and PL/I, the translator can set the value of particular lengths. This means that they are optional in programs that specify data areas.

In C, C++ , you must specify all LENGTH options, except on the SEND MAP, RECEIVE MAP, READ, READNEXT, READPREV, REWRITE, WRITE, DEQ, and ENQ commands.

If you use the ENQ command without a LENGTH option, CICS assumes that the command is applied to an address (for example the CWA). If you use the ENQ command with a LENGTH option, CICS assumes that the command is applied to a name (which can be 1 through 255 bytes long).

When a CICS command includes the LENGTH option, you generally express this option as a signed 16-bit binary value (the command description tells you what the value should be). This places a theoretical upper limit of 32767 bytes on LENGTH. In practice (depending on conventions of recoverability, function shipping, and so on) the achievable upper limit varies from command to command, but is somewhat less than this theoretical maximum.

The FLENGTH option, where available, allows you to specify any length value up to 2048 MB, but for application portability, it is recommended that you do not use more than 24 MB. Some commands have limits that are significantly below this. For example, RECEIVE and SEND have a limited FLENGTH of 32767 bytes.

NOHANDLE You can use the NOHANDLE option with any command to specify that you want CICS to take no action for any condition or attention identifier (AID) that results from the running of the command.

The NOHANDLE option covers all conditions that can occur for the commands on which you have specified NOHANDLE; the IGNORE CONDITION command covers specified conditions for all commands (until you change its effect by specifying a HANDLE CONDITION command that names one or more of these conditions).


You must be careful when using NOHANDLE with the RECEIVE command, because NOHANDLE overrides the HANDLE AID command in addition to the HANDLE CONDITION command, with the result that CICS ignores PF key responses.

Note that when using the C or C++ languages, every EXEC CICS command is handled as if it has the NOHANDLE option specified. For more information, see the TXSeries for Multiplatforms Application Programming Guide.

RESP and RESP2 You can use the RESP option with any command to test whether CICS raised a condition when running the command. For SET commands only, where the INVREQ condition might occur for more than one reason, you can use the RESP2 option to find out why the condition occurred. RESP(xxx)

In this example, xxx is a user-defined 32-bit binary data area. On return from the command, xxx contains a value that corresponds to a condition that CICS might have raised, or to a normal response; that is: xxx=DFHRESP(NORMAL).

You can use the DFHRESP translator built-in function to test the returned status.

In COBOL you can test the returned RESP value as follows: EXEC CICS WRITEQ TS FROM(abc) QUEUE(qname) RESP(xxx) END-EXEC. IF xxx = DFHRESP(NOSPACE) THEN ...

In PL/I you can test the returned RESP value as follows: EXEC CICS WRITEQ TS FROM(abc) QUEUE(qname) RESP(xxx); IF xxx = DFHRESP(NOSPACE) THEN ...

In C or C++ a similar test is: EXEC CICS WRITEQ TS FROM("abc") LENGTH(3) QUEUE(qname) RESP(xxx); switch(xxx) { case DFHRESP(NORMAL) : break; case DFHRESP(INVREQ) : Invreq_Cond(); break; default : Errors(); }

Because the use of RESP implies NOHANDLE, you must be careful when using RESP with the RECEIVE command, because NOHANDLE overrides the HANDLE AID command in addition to the HANDLE CONDITION command. The result is that CICS ignores PF key responses.

RESP2(yyy) In this example, yyy is a user-defined 32-bit binary data area. On return from the command, yyy contains a value that further qualifies the response to particular commands. RESP2 values are unique within a command. For CICS, this applies to INQUIRE and SET commands only.


SYSID The SYSID option appears on the ALLOCATE command and most file services, timer services, program execution, temporary storage, and transient data commands. It is a four-character name. Each CICS region has a local SYSID. On CICS, it is configured in the LocalSysId attribute of the Region Definition (RD) entry. In addition, a CICS region can have entries in the Communications Definitions (CD), each of which defines a connection to a remote system. The name of a CD entry is referred to as a remote SYSID or a connection name. These remote SYSIDs are known only to the local region and do not have to match the name of the remote system at the other end of the connection.

The SYSID option on the ALLOCATE command allows an application to specify a remote SYSID only. This is because ALLOCATE is starting a Distributed Transaction Processing (DTP) conversation with a program that is running on a remote system.

The SYSID option on other commands can be a local or a remote SYSID. It is used to specify where the resource resides. v If the local SYSID is specified, the resource resides on the local CICS region.

The resource must be defined in the local resource definition. In addition, the local definition for the resource must not have the RemoteSysId attribute set to a remote SYSID, otherwise CICS generates an AEY9 abnormal termination.

v If a remote SYSID is specified, CICS uses an intersystem request to send the command on the connection that is defined for the SYSID. The system that receives the request must be a CICS region.

If the SYSID option is not specified on a file services, timer services, program execution, temporary storage, or transient data command, it defaults to the value that is in the RemoteSysId attribute of the resources local definition. If RemoteSysId=, or it is set to the local SYSID, the command runs locally. If RemoteSysId is set to a remote SYSID, CICS uses an intersystem request to send the command on the connection that is defined for the SYSID. Again, the receiving system must be CICS.

Any application that is using the SYSID option on file services, timer services, program execution, temporary storage, or transient data commands to request a remote SYSID, must have RSLCheck=none set in Transaction Definitions (TD) entry of the invoking transaction. Otherwise, CICS raises the NOTAUTH condition. This is because the SYSID option causes local security checking to be bypassed, so CICS allows its use only by transactions that do not require RSL checking.

See the TXSeries for Multiplatforms Intercommunication Guide for more information about DTP conversations and the use of intersystem requests to access resources on other CICS regions.

NOEDF The NOEDF option enables you to prevent a command from being visible to Execution Diagnostic Facility (CEDF). You can code this option on any command.

STATE The STATE option is available on advanced program-to-program communications (APPC) commands such as ALLOCATE and CONNECT PROCESS. APPC commands allow a CICS program to send data to, and receive data from, another program that is running in a remote system. The programs are linked together by using a conversation. Only one program can send data at a time, although each


program can have a chance to send while the conversation is active. The rules that control when each program can send data are expressed in terms of a conversation state.

The conversation state is a local attribute of the conversation. It changes its value depending on the APPC commands that the local program issues, and as a result of data and other status information that is received from the remote program.

A local program can query the conversation state by using either the STATE option on an APPC command, or the EXTRACT ATTRIBUTES command. The conversation state is returned as one of the following CVDA values: v ALLOCATED v CONFFREE v CONFRECEIVE v CONFSEND v FREE v PENDFREE v PENDRECEIVE v RECEIVE v ROLLBACK v SEND v SYNCFREE v SYNCRECEIVE v SYNCSEND

The TXSeries for Multiplatforms Intercommunication Guide defines the conversation states and when they occur in the conversation. It also defines which APPC commands are permitted in each conversation state.

CICS-value data areas (CVDA) on page 7 describes how to use CVDA values.

Programming that uses APPC conversations is called Distributed Transaction Processing (DTP). See the TXSeries for Multiplatforms Intercommunication Guide for guidance on using APPC conversations.

FILE The FILE option appears on all file service commands. The value of filename is an eight-character name by which a file is known to CICS.

Processing the IOERR condition Any program that attempts to process an IOERR condition for a recoverable resource must not issue a RETURN or a SYNCPOINT command, but must terminate by issuing an ABEND command. A RETURN or SYNCPOINT command causes CICS to commit changes to other recoverable resources, and might cause the overall state of the transaction to be incorrect.

For related information, see Appendix G, CICS conditions, on page 553.


INQUIRE and SET commands The INQUIRE and SET commands allow user-written system programs to look at the information that defines a named CICS resource (the installed definitions runtime values) and to change some of the values.

The INQUIRE and SET commands give access to the following CICS resources: v Connections v Definition stanza entries v Files v Journals v Mode names v Programs v Queued requests v Regions v Statistics v Tasks v Temporary storage queues v Terminals v Trace activities v Transactions v Transient data queues

The facilities that are provided are similar to those of the CEMT transaction. Changes to the resource attributes apply only for the duration of the current CICS session and are supported only within the local region. They are therefore lost when CICS is autostarted.

Although the INQUIRE and SET commands have functions that you can use in application programs, these commands are intended primarily for user-written system programs and not for general application programs. For example, you can use these commands to provide a customized version of CEMT.

Some INQUIRE and SET System Programming Interface (SPI) commands and some SPI options to existing INQUIRE and SET commands support the CICSPlex(R) System Manager (CICSPlex SM), which is the IBM System-390 management product for CICS networks. CICSPlex SM provides a single system image of the CICS regions in an enterprise, with the ability to manage those regions from a single point of control. The following commands enable support of this product: v INQUIRE DSNAME v INQUIRE MODENAME v INQUIRE REQID v INQUIRE TRACEDEST v INQUIRE TSQUEUE v SET TRACEDEST

The following commands have options to encompass the SPI functions. CICS returns a null value when the functions do not apply to its platform: v INQUIRE SYSTEM v INQUIRE TASK v INQUIRE TDQUEUE v INQUIRE TERMINAL OR NETNAME


v TRANSACTION v SET FILE v SET FILE CLOSED v SET FILE DISABLED v SET SYSTEM v SET TASK v SET TDQUEUE v SET TERMINAL v SET TRANSACTION

The INQUIRE command also has special forms that enable you to browse all the runtime definitions that you are authorized to access for a particular resource. For more information, see Browsing resource definitions on page 15.

The INQUIRE and SET commands have all the advantages of other EXEC CICS commands. In particular, they are supported by CECI, the Command Level Interpreter transaction, and by the Execution Diagnostic Facility (EDF).

Note the following general points: v You do not have to issue an INQUIRE command before issuing a SET command. v In most cases, the items that you can change with a SET command are a subset

of those that you can retrieve with an INQUIRE command. v In general, the effect of a particular operation that is specified on an EXEC CICS

SET command is the same as the effect when it is specified through CEMT. v An INQUIRE or SET command that is issued against an individual resource

results in a resource security check if the RSLCheck attribute in the Transaction Definitions (TD) entry for the transaction that is issuing the command specifies that resource security checking is in use. This applies only to files, programs, transactions, transient data queues, and journals. The NOTAUTH condition occurs on all INQUIRE and SET commands where the application is not authorized to view or change the resource.

v The INQUIRE and SET commands are not supported across intersystem communication (ISC). However, you can use the INQUIRE command to retrieve information about some of the attributes of a remote resource (from its local definition).

v CICS does not maintain exclusive control of the information that is returned on an INQUIRE command. This means that you can change the information at any time; for example, by issuing a SET command.

v Like all other EXEC CICS commands, these commands have NOHANDLE, NOEDF, and RESP options, which are not shown in the command syntax.

v Besides the RESP option, the INQUIRE and SET commands also have a RESP2 option. (See RESP and RESP2 on page 10.)

v If a condition occurs on an INQUIRE command, the command did not run correctly, and CICS cannot guarantee the validity of the returned values.

v If a condition occurs on a SET command, CICS has made as few as possible of the requested changes on return. To establish which, if any, of the changes CICS has made, you can issue an INQUIRE command.


Browsing resource definitions The INQUIRE command allows you to retrieve information about a single named resource. The command also has special forms that allow you to browse all the runtime definitions that you are authorized to access for a particular resource.

You can browse the definitions for the following resources: v Connections v Files v Journals v Programs v Terminals v Transactions v Transient data queues

CICS does not attempt to retrieve definitions that you are not authorized to access. No locking of the retrieved information occurs, which means that a definition can change at any time during the browse. No facility is available for selective browsing; that is, for returning entries only if they meet particular conditions.

The general command format of a browse operation has the following standard pattern: INQUIRE resource START INQUIRE resource(data-area) NEXT [other options same as for INQUIRE resource] INQUIRE resource END

where resource represents the resource type (for example, PROGRAM).

Descriptions follow of each of the command forms. The information that is given applies to all browse operations. INQUIRE resource START

This command positions an internal pointer at the first definition that you are authorized to access in the relevant CICS resource definitions. The command does not retrieve any information, nor does it allow you to specify a start point.

CICS allows only a one-browse of a particular resource type at any one time in a given task. The ILLOGIC condition occurs if a browse is already in progress when an application issues an INQUIRE START command.

INQUIRE resource (data-area) NEXT The first time this command is issued, it retrieves the name and any requested attributes of the first resource definition. On each subsequent occasion, the command retrieves the name and attributes of the next resource definition.

The END condition occurs when you have already retrieved all the definitions that you are authorized to access in the relevant CICS resource definitions. CICS does not change any data areas that are specified on the command. Note that the default action for the END condition is to terminate the task abnormally, so you need to detect its occurrence. You cannot request a selective browse of the resource definitions, and you can browse only forward. All optional attributes that you specify are output fields only, and CICS ignores them on input.


CICS maintains a pointer to the current browse position at the transaction level. CICS does not reset this when an application issues LINK or XCTL commands. The ILLOGIC condition occurs if an application issues an INQUIRE NEXT command for a resource type that has had no previous INQUIRE START command successfully issued.

INQUIRE resource END This command ends the browse and frees any held resources. You can end a browse at any time after issuing the INQUIRE START command. If you do not issue an INQUIRE END command, the browse terminates at the end of the transaction. The browse is not terminated if the application issues an EXEC CICS SYNCPOINT command.

The ILLOGIC condition occurs if an application issues an INQUIRE END command for a resource type that has had no previous INQUIRE START command successfully issued. The following COBOL example shows a browse of the Program Definitions (PD) that retrieves the name and language of each program that is defined in the PD. CICS browses the complete set of PD entries, so the application issues the INQUIRE PROGRAM NEXT command until the END condition arises, then issues the INQUIRE PROGRAM END command.

Null values If you issue an INQUIRE command to find out the value of an attribute that is not applicable to the named resource, CICS returns a null value in the data area that you have defined. CICS also returns a null value if the information that you have requested is not available at the time of the inquiry.

Null values depend on the format of the user-defined data area, and are defined as follows: v Character fields are blanks. v Binary fields are -1. v Pointer fields are XFF000000. v C programs return zero as the null value.

Figure 1. Browsing the Program Definitions (PD) with COBOL


v CICS-Value Data Area (CVDA) fields are DFHVALUE(NOTAPPLIC). For more information, see CICS-value data areas (CVDA) on page 7.

If you issue a SET command that includes one or more null argument values, CICS ignores the corresponding attributes. This allows the possibility of coding general SET commands in which some attributes can be left as they are, without having to issue an INQUIRE command first to establish what the current values are. You are most likely to want to do this when the field is defined as a CVDA. However, in all cases, if you simply leave out an optional attribute from a SET command, CICS does not change its value.

For CVDAs on SET commands, you can code the null value as DFHVALUE(IGNORE), where IGNORE is equivalent to (and has the same value as) NOTAPPLIC on INQUIRE commands. You code the SET command as in the following COBOL example: WS-SYMBOLNAME = DFHVALUE(IGNORE) EXEC CICS SET FILE(WS-FILENAME) READABLE ADDABLE DELETE(WS-SYMBOLNAME) END-EXEC.

You can then read from, and add to, the file. The delete status remains the same as it was before the SET FILE command was issued. Simply leaving out the DELETE option from the command gives the same effect, but this approach lacks flexibility for some coding conditions.

For more information about the use of CVDAs, see Appendix F, CVDAs recognized by the translator, on page 525.

For other related information, see TXSeries for Multiplatforms Administration Reference.

PERFORM SHUTDOWN SPI Command The PERFORM SHUTDOWN SPI command allows user-written system programs to shutdown the CICS region.

EXEC CICS PERFORM SHUTDOWN provides two types of Shutdown from which the system programmer can choose the one that is most suitable for current requirements: v Normal (EXEC CICS PERFORM SHUTDOWN) v Immediate (EXEC CICS PERFORM SHUTDOWN IMMEDIATE SPI)

EXEC CICS PERFORM SHUTDOWN starts a normal shutdown of the CICS region. It waits for all the tasks to complete before it performs shutdown.

EXEC CICS PERFORM SHUTDOWN IMMEDIATE SPI starts an immediate shutdown of the region. It does not wait for the tasks to complete.

Note: 1. Do not use PERFORM SHUTDOWN SPI in normal business

applications. It is intended for use in user-written system programs.


2. When EXEC CICS PERFORM SHUTDOWN [IMMEDIATE] SPI completes successfully, it does not return the control back to the application program, unless an exception condition occurs.

The CICS API commands by function The following tables categorize commands according to the functions that they perform:

Error handling and abnormal termination support commands Table 6. Error handling and abnormal termination support

ABEND Terminates a task abnormally. HANDLE ABEND Handles an abnormal termination exit. HANDLE CONDITION Handles conditions. IGNORE CONDITION Ignores conditions. POP HANDLE Restores the original HANDLE commands. PUSH HANDLE Suspends existing HANDLE commands.

APPC Mapped conversation commands Advanced program-to-program communications (APPC) mapped conversation commands allow a CICS program to send data to, and receive data from, a program that is running in a remote system. Programming that uses APPC conversations is called Distributed Transaction Processing (DTP). Guidance information is given in the TXSeries for Multiplatforms Intercommunication Guide .

Table 7. Advanced program-to-program communications (APPC) mapped conversation ALLOCATE Creates an APPC mapped conversation. CONNECT PROCESS Initiates an APPC mapped conversation to a program that is

running in a remote system. CONVERSE (APPC) Communicates on an APPC mapped conversation. EXTRACT ATTRIBUTES Obtains the state of an APPC conversation. EXTRACT PROCESS Retrieves information about an APPC conversation. FREE Finishes with an APPC conversation. ISSUE ABEND Abnormally terminates an APPC conversation. ISSUE CONFIRMATION Issues a positive response to a SEND CONFIRM request

on an APPC mapped conversation. ISSUE ERROR Sends an error indicator on an APPC mapped conversation. ISSUE PREPARE Issues the first flow of a syncpoint request on an APPC

mapped conversation. ISSUE SIGNAL Requests change of direction from a remote program on an

APPC mapped conversation. RECEIVE (APPC) Receives data from an APPC mapped conversation. SEND (APPC) Sends data on an APPC mapped conversation. WAIT CONVID Requests that buffered data is transmitted on an APPC

mapped conversation.


Authentication commands Table 8. Authentication Support

CHANGE PASSWORD Changes the password for a specified user ID. SIGNOFF Signs off from a terminal. SIGNON Signs on to a terminal. VERIFY PASSWORD Verifies the password for a specified user ID.

Basic Mapping Support (BMS) commands Table 9. Basic Mapping Support (BMS)

RECEIVE MAP Receives screen input into an application data area. SEND CONTROL Sends device controls to a terminal. SEND MAP Sends mapped output data to a terminal. SEND TEXT Sends data without mapping.

Debugging services commands Table 10. Debugging services

DUMP Requests a transaction dump. ENTER Writes a trace entry. TRACE Controls the CICS trace facility.

Configuration services commands Table 11. Configuration services

ADDRESS Obtains access to CICS storage areas. ASSIGN Obtains values from outside the application programs local

environment. COLLECT STATISTICS Obtains either the current statistics for a single named

resource, or the global statistics for a named resource type. INQUIRE CONNECTION Retrieves information about a system connection. INQUIRE CONNECTION (browse)

Browses information about the system connections.

INQUIRE DSNAME Retrieves information about an object that is associated with a File Definitions (FD) stanza entry.

INQUIRE FILE Retrieves information about a file. INQUIRE FILE (browse) Browses information about the files that you are authorized

to access.

INQUIRE JOURNALNUM Retrieves information about a user journal. INQUIRE JOURNALNUM (browse)

Browses information about the user journals that you are authorized to access.

INQUIRE MODENAME Retrieves information about a session group within a connection.

INQUIRE PROGRAM Retrieves information about a program, map set, or table.


Table 11. Configuration services (continued) INQUIRE PROGRAM (browse)

Browses information about the programs, map sets, and tables that you are authorized to access.

INQUIRE REQID Retrieves information about a queued request. INQUIRE STATISTICS Retrieves information about the accumulation and recording

of CICS. INQUIRE SYSTEM Retrieves information about the local CICS region. INQUIRE TASK Retrieves information about a user task. INQUIRE TASK LIST Retrieves a list of user tasks. INQUIRE TCLASS Retrieves information about a transaction class. INQUIRE TDQUEUE Retrieves information about a transient data queue. INQUIRE TDQUEUE (browse) Browses information about the transient data queues that

you are authorized to access. INQUIRE TERMINAL or NETNAME

Retrieves information about a terminal.

INQUIRE TERMINAL (browse)

Browses information about the terminals.

INQUIRE TRACEDEST Retrieves information about the tracing destination. INQUIRE TRANSACTION Retrieves information about a transaction. INQUIRE TRANSACTION (browse)

Browses information about the transactions that you are authorized to access.

INQUIRE TSQUEUE Retrieves information about a temporary storage queue. PERFORM STATISTICS RECORD

Causes the statistics for a named resource type to be recorded.

SET CONNECTION Changes some of the attributes of a connection. SET FILE Changes some of the attributes of a file. SET FILE CLOSED Closes a file. SET FILE DISABLED Makes a file unavailable to application programs. SET FILE ENABLED Makes a file available to application programs. SET FILE OPEN Opens a file. SET JOURNALNUM Changes the open status of a user journal. SET PROGRAM Changes some of the attributes of a program map set or

table. SET STATISTICS Changes some of the values that control the accumulation

and recording of CICS statistics. SET SYSTEM Changes some of the attributes of a system. SET TASK Purges a user task. SET TCLASS Changes attributes of a transaction class. SET TDQUEUE Changes some of the attributes of a transient data queue. SET TERMINAL Changes some of the attributes of a terminal. SET TRACEDEST Changes tracing options. SET TRANSACTION Changes some of the attributes of a transaction.


File services commands Table 12. File services

DELETE Deletes a record from a file. ENDBR Ends a browse. READ Reads a record from a file. READNEXT Reads the next record during a browse. READPREV Reads the previous record during a browse. RESETBR Resets the start of a browse. REWRITE Updates a record in a file. STARTBR Starts browse. UNLOCK Releases exclusive control on a record. WRITE Writes a record to a file.

Timer services commands Table 13. Timer services

ASKTIME Requests the current date and time of day. CANCEL Cancels an interval control request. DELAY Delays the processing of a task. FORMATTIME Selects the format of date and time. POST Requests notification when the specified expiration time for

exclusive control on a record is reached. RETRIEVE Retrieves data that is stored for a task. START Schedules a task in a local or a remote system. WAIT EVENT Waits for an event to occur.

Journal services commands Table 14. Journal services

JOURNAL Creates a journal record. WAIT JOURNAL Synchronizes with journal output.

Program execution services commands Table 15. Program execution services

LINK Links to another program that is expecting return. RETURN Returns program control. XCTL Transfers program control. SUSPEND Suspends a task.


Storage services commands Table 16. Storage services

FREEMAIN Releases main storage. GETMAIN Gets main storage. LOAD Loads an application table or map set from a disk directory

into shared main storage. RELEASE Releases a loaded application table or map set.

Logical unit of work (LUW) services commands Table 17. Logical unit of work (LUW) services

SYNCPOINT Establishes a syncpoint.

Serialization services commands Table 18. Serialization services

DEQ Releases a currently enqueued resource for use by another task.

ENQ Schedules use of a resource by a task (enqueue).

Temporary storage queue services commands Table 19. Temporary storage queue services

DELETEQ TS Deletes a temporary storage queue. READQ TS Reads data from a temporary storage queue. WRITEQ TS Writes data to a temporary storage queue.

Terminal services commands Table 20. Terminal services

CONVERSE (terminal) Communicates with a terminal. HANDLE AID Handles attention identifiers. RECEIVE (terminal) Receives data from a terminal. SEND (terminal) Writes (or sends) data to a terminal. WAIT TERMINAL Ensures terminal operation has completed.

Transient data queue services commands Table 21. Transient data queue services

DELETEQ TD Deletes an intrapartition transient data queue. READQ TD Reads data from a transient data queue. WRITEQ TD Writes data to a transient data queue.


Chapter 2. CICS API command reference This chapter contains, in alphabetical sequence, descriptions of the CICS API commands.

CICS API command information layout Following the title and a brief description of the purpose of the command are the following information segments: Syntax

Shows the command options and the conditions that you can raise. For example, the syntax and conditions for the ALLOCATE command are

shown as:

Description Provides an expanded description of the command.

Options Describes the semantics of the command. Often, values that are defined by other CICS family products but not necessarily returned by CICS on Open Systems and CICS for Windows are included in this document. These values are included for portability purposes.

Conditions Some commands describe how and when conditions can be raised, and the default action that is taken if the condition is not handled by the program.

Note: Condition handling is dependent on the programming language. For example, the default action for COBOL is Terminate the task abnormally and the default action for C is No action. In most cases, only the default action for COBOL is listed.

Examples Some commands also include examples that are usually shown in COBOL format, ignoring the command terminator.

ABEND

Terminates a task abnormally.

Syntax

ALLOCATE

ALLOCATE

ALLOCATE SYSID(name) PROFILE(name)

NOQUEUE

STATE(cvda)

NOSUSPEND

Conditions: INVREQ, SYSIDERR

Copyright IBM Corp. 1999, 2008 23

Description

ABEND terminates a task abnormally.

CICS releases the main storage that is associated with the terminated task; optionally, you can obtain a dump of this storage first.

The following example shows how to terminate a task abnormally: EXEC CICS ABEND ABCODE(BCDE)

Options ABCODE(name)

Specifies that CICS is to dump main storage that is associated with the task that is being terminated, and provides a name to identify the dump file. However, CICS produces a dump only if the TransDump attribute in the Transaction Definitions (TD) is set to yes, and no active abnormal termination exit exists for the current logical level.

The specified name, which can consist of up to four bytes with no embedded blanks, also serves as the abnormal termination code. If you do not specify ABCODE, CICS uses a code of ???? (four question marks) instead.

Note: If ABCODE is not used, the effect is the same as NODUMP.CANCEL

Specifies that CICS is to cancel all exits (if any) that have been established by HANDLE ABEND commands at any logical level in the task before the task is terminated; in effect, CICS ignores these exits.

NODUMP Allows you to request an abend without causing a dump to be taken.

Related Information

HANDLE ABEND on page 91

TXSeries for Multiplatforms Administration Reference

ADDRESS Obtains access to CICS storage areas.

Syntax

ABEND

ABEND ABCODE(name)

CANCEL

NODUMP


||||||||||||||||||||||||||||||

|

||

Description

ADDRESS gets access to the following areas: v The communication area that is available to the invoked program (COMMAREA) v The common work area (CWA) v The EXEC interface block (EIB) v The terminal user area (TCTUA) v The transaction work area (TWA)

Options COMMAREA(ptr-ref)

Specifies a pointer reference that is to be set to the address of the communication area (COMMAREA) that is available to the currently-running program. CICS uses this area to pass information between application programs. If a COMMAREA does not exist, CICS sets the pointer reference to the null value. Refer to Null values on page 16.

C or C++ functions must use ADDRESS COMMAREA to get the address of the communication area because this address is not passed as an argument to a C or C++ main function. COBOL programs receive the COMMAREA as a parameter, and programs must contain a definition of a data area to allow access. For more information, see the TXSeries for Multiplatforms Application Programming Guide.

CWA(ptr-ref) Specifies a pointer referencethat is to be set to the address of the common work area (CWA). This area makes information available to applications that are running in a single region. If a CWA does not exist, CICS sets the pointer reference to the null value. Refer to Null values on page 16.

EIB(ptr-ref) Specifies a pointer reference that is to be set to the address of the EIB. You must use this option to get addressability to the EIB in application routines other than the first one that is started by CICS (where addressability to the EIB is provided automatically).

TCTUA(ptr-ref) Specifies a pointer reference that is to be set to the address of the terminal user area (TCTUA) for the principal facility, and not for any alternate facility that has possibly been allocated. Use this area to pass information between application programs, but only if the same terminal is associated with the

ADDRESS

ADDRESS COMMAREA(ptr-ref)

CWA(ptr-ref)

EIB(ptr-ref)

TCTUA(ptr-ref)

TWA(ptr-ref)

Condition: INVREQ

Note: COMMAREA is not supported for COBOL programs.

Chapter 2. CICS API command reference 25

application programs that are involved (which can be in different tasks). If a TCTUA does not exist, CICS sets the pointer reference to the null value. Refer to Null values on page 16.

TWA(ptr-ref) Specifies a pointer reference that is to be set to the address of the transaction work area (TWA). Use this area to pass information between application programs, but only if they are in the same task. If a TWA does not exist, CICS sets the pointer reference to the null value. Refer to Null values on page 16.

Conditions INVREQ

Occurs if ADDRESS TCTUA was executed on a server side of a DPL program. Default action: Terminates the task abnormally.

Related Information

TXSeries for Multiplatforms Application Programming Guide

ALLOCATE Initiates an advanced program-to-program communications (APPC) mapped conversation. (APPC conversations allow data to be sent and received between programs that are running in remote systems. This is called Distributed Transaction Programming (DTP). For guidance information about DTP, refer to the TXSeries for Multiplatforms Intercommunication Guide.)

Syntax

Description

ALLOCATE requests a conversation with a remote region. CICS returns the four-byte CONVID (conversation identifier) in the EIBRSRCE field of the EIB. The application program uses the CONVID in all subsequent commands that

Documents

TXSeries for Multiplatforms Application Programming Reference Version 6.2