CICS Transaction Server for z/OSVersion 4 Release 2

Application Programming Reference

SC34-7159-02

IBM

CICS Transaction Server for z/OSVersion 4 Release 2

Application Programming Reference

SC34-7159-02

IBM

NoteBefore using this information and the product it supports, read the information in Notices on page 925.

This edition applies to Version 4 Release 2 of CICS Transaction Server for z/OS (product number 5655-S97) and toall subsequent releases and modifications until otherwise indicated in new editions.

Copyright IBM Corporation 1989, 2014.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

What this manual is about . . . . . . viiWho should read this manual . . . . . . . . viiWhat you need to know to understand this manual viiHow to use this manual . . . . . . . . . . viiWhat this manual does not cover . . . . . . . vii

Notes on terminology . . . . . . . . ix

Changes in CICS Transaction Server forz/OS, Version 4 Release 2 . . . . . . . xi

About the CICS API commands . . . . 1CICS API command format . . . . . . . . . 1CICS command syntax notation . . . . . . . . 2CICS command argument values . . . . . . . 4CICS command restrictions . . . . . . . . . 9LENGTH options in CICS commands . . . . . 10NOHANDLE option . . . . . . . . . . . 10RESP and RESP2 options . . . . . . . . . . 10Translated code for CICS commands . . . . . . 11

COBOL translation output . . . . . . . . 11C translation output . . . . . . . . . . 12PL/I translation output . . . . . . . . . 12Assembler translation output . . . . . . . 13

CICS-value data areas (cvdas) . . . . . . . . 17CICS threadsafe commands in the API . . . . . 17Threadsafe commands . . . . . . . . . . . 18

CICS API commands. . . . . . . . . 23CICS command summary . . . . . . . . . 24ABEND . . . . . . . . . . . . . . . 32ACQUIRE . . . . . . . . . . . . . . . 34ADD SUBEVENT . . . . . . . . . . . . 37ADDRESS . . . . . . . . . . . . . . . 39ADDRESS SET . . . . . . . . . . . . . 41ALLOCATE (APPC) . . . . . . . . . . . 42ALLOCATE (LUTYPE6.1). . . . . . . . . . 46ALLOCATE (MRO). . . . . . . . . . . . 48ASKTIME . . . . . . . . . . . . . . . 50ASSIGN . . . . . . . . . . . . . . . 51BIF DEEDIT . . . . . . . . . . . . . . 66BIF DIGEST . . . . . . . . . . . . . . 68BUILD ATTACH (LUTYPE6.1) . . . . . . . . 70BUILD ATTACH (MRO) . . . . . . . . . . 73CANCEL . . . . . . . . . . . . . . . 76CANCEL (BTS) . . . . . . . . . . . . . 78CHANGE PHRASE. . . . . . . . . . . . 81CHANGE PASSWORD . . . . . . . . . . 83CHANGE TASK . . . . . . . . . . . . . 85CHECK ACQPROCESS . . . . . . . . . . 86CHECK ACTIVITY . . . . . . . . . . . . 88CHECK TIMER . . . . . . . . . . . . . 91CONNECT PROCESS . . . . . . . . . . . 93CONVERSE (default) . . . . . . . . . . . 96

CONVERSE (APPC) . . . . . . . . . . . 97CONVERSE (LUTYPE2/LUTYPE3) . . . . . . 98CONVERSE (LUTYPE4) . . . . . . . . . . 99CONVERSE (LUTYPE6.1) . . . . . . . . . 100CONVERSE (SCS) . . . . . . . . . . . . 101CONVERSE (3270 logical) . . . . . . . . . 102CONVERSE (3600-3601) . . . . . . . . . . 103CONVERSE (3600-3614) . . . . . . . . . . 104CONVERSE (3650 interpreter) . . . . . . . . 105CONVERSE (3650-3270) . . . . . . . . . . 106CONVERSE (3650-3653) . . . . . . . . . . 107CONVERSE (3650-3680) . . . . . . . . . . 108CONVERSE (3767) . . . . . . . . . . . 109CONVERSE (3770). . . . . . . . . . . . 110CONVERSE (3790 full-function or inquiry) . . . 111CONVERSE (3790 3270-display) . . . . . . . 112CONVERSE: z/OS Communications Server options 113CONVERSE (non-z/OS Communications Serverdefault) . . . . . . . . . . . . . . . 118CONVERSE (MRO) . . . . . . . . . . . 119CONVERSE (2260) . . . . . . . . . . . 120CONVERSE: non-z/OS Communications Serveroptions . . . . . . . . . . . . . . . 121CONVERTTIME . . . . . . . . . . . . 126DEFINE ACTIVITY . . . . . . . . . . . 128DEFINE COMPOSITE EVENT. . . . . . . . 131DEFINE COUNTER and DEFINE DCOUNTER . . 133DEFINE INPUT EVENT . . . . . . . . . . 137DEFINE PROCESS . . . . . . . . . . . 138DEFINE TIMER . . . . . . . . . . . . 141DELAY . . . . . . . . . . . . . . . 144DELETE . . . . . . . . . . . . . . . 147DELETE ACTIVITY . . . . . . . . . . . 155DELETE CONTAINER (BTS) . . . . . . . . 157DELETE CONTAINER (CHANNEL) . . . . . 159DELETE COUNTER and DELETE DCOUNTER 160DELETE EVENT . . . . . . . . . . . . 162DELETE TIMER . . . . . . . . . . . . 163DELETEQ TD . . . . . . . . . . . . . 164DELETEQ TS . . . . . . . . . . . . . 166DEQ . . . . . . . . . . . . . . . . 168DOCUMENT CREATE . . . . . . . . . . 170DOCUMENT DELETE . . . . . . . . . . 174DOCUMENT INSERT . . . . . . . . . . 175DOCUMENT RETRIEVE . . . . . . . . . 179DOCUMENT SET . . . . . . . . . . . . 181DUMP TRANSACTION . . . . . . . . . . 184ENDBR . . . . . . . . . . . . . . . 189ENDBROWSE ACTIVITY . . . . . . . . . 192ENDBROWSE CONTAINER . . . . . . . . 193ENDBROWSE EVENT . . . . . . . . . . 194ENDBROWSE PROCESS . . . . . . . . . 195ENQ . . . . . . . . . . . . . . . . 196ENTER TRACENUM . . . . . . . . . . . 199EXTRACT ATTACH (LUTYPE6.1) . . . . . . 201EXTRACT ATTACH (MRO) . . . . . . . . 205

Copyright IBM Corp. 1989, 2014 iii

||

EXTRACT ATTRIBUTES (APPC) . . . . . . . 209EXTRACT ATTRIBUTES (MRO) . . . . . . . 211EXTRACT CERTIFICATE . . . . . . . . . 213EXTRACT LOGONMSG. . . . . . . . . . 216EXTRACT PROCESS . . . . . . . . . . . 218EXTRACT TCPIP . . . . . . . . . . . . 220EXTRACT TCT . . . . . . . . . . . . . 224EXTRACT WEB . . . . . . . . . . . . 225FORCE TIMER . . . . . . . . . . . . . 230FORMATTIME . . . . . . . . . . . . . 231FREE . . . . . . . . . . . . . . . . 236FREE (APPC) . . . . . . . . . . . . . 237FREE (LUTYPE6.1) . . . . . . . . . . . 239FREE (MRO) . . . . . . . . . . . . . 240FREEMAIN . . . . . . . . . . . . . . 242GDS ALLOCATE . . . . . . . . . . . . 245GDS ASSIGN . . . . . . . . . . . . . 248GDS CONNECT PROCESS . . . . . . . . . 249GDS EXTRACT ATTRIBUTES . . . . . . . . 252GDS EXTRACT PROCESS . . . . . . . . . 254GDS FREE . . . . . . . . . . . . . . 256GDS ISSUE ABEND . . . . . . . . . . . 258GDS ISSUE CONFIRMATION . . . . . . . . 260GDS ISSUE ERROR . . . . . . . . . . . 262GDS ISSUE PREPARE . . . . . . . . . . 264GDS ISSUE SIGNAL . . . . . . . . . . . 266GDS RECEIVE . . . . . . . . . . . . . 268GDS SEND . . . . . . . . . . . . . . 271GDS WAIT . . . . . . . . . . . . . . 274GET CONTAINER (BTS) . . . . . . . . . 276GET CONTAINER (CHANNEL) . . . . . . . 279GET COUNTER and GET DCOUNTER . . . . 283GETMAIN . . . . . . . . . . . . . . 288GETNEXT ACTIVITY . . . . . . . . . . 292GETNEXT CONTAINER . . . . . . . . . 294GETNEXT EVENT . . . . . . . . . . . 295GETNEXT PROCESS . . . . . . . . . . . 297HANDLE ABEND. . . . . . . . . . . . 298HANDLE AID . . . . . . . . . . . . . 300HANDLE CONDITION . . . . . . . . . . 302IGNORE CONDITION . . . . . . . . . . 304INQUIRE ACTIVITYID . . . . . . . . . . 305INQUIRE CONTAINER . . . . . . . . . . 308INQUIRE EVENT . . . . . . . . . . . . 310INQUIRE PROCESS . . . . . . . . . . . 312INQUIRE TIMER . . . . . . . . . . . . 313INVOKE SERVICE . . . . . . . . . . . 315INVOKE WEBSERVICE . . . . . . . . . . 320ISSUE ABEND . . . . . . . . . . . . . 321ISSUE ABORT . . . . . . . . . . . . . 323ISSUE ADD . . . . . . . . . . . . . . 325ISSUE CONFIRMATION . . . . . . . . . 327ISSUE COPY (3270 logical) . . . . . . . . . 329ISSUE DISCONNECT (default) . . . . . . . 330ISSUE DISCONNECT (LUTYPE6.1) . . . . . . 332ISSUE END . . . . . . . . . . . . . . 333ISSUE ENDFILE . . . . . . . . . . . . 335ISSUE ENDOUTPUT . . . . . . . . . . . 336ISSUE EODS . . . . . . . . . . . . . 337ISSUE ERASE . . . . . . . . . . . . . 338ISSUE ERASEAUP . . . . . . . . . . . 340

ISSUE ERROR . . . . . . . . . . . . . 342ISSUE LOAD . . . . . . . . . . . . . 344ISSUE NOTE . . . . . . . . . . . . . 345ISSUE PASS . . . . . . . . . . . . . . 347ISSUE PREPARE . . . . . . . . . . . . 349ISSUE PRINT . . . . . . . . . . . . . 351ISSUE QUERY . . . . . . . . . . . . . 352ISSUE RECEIVE . . . . . . . . . . . . 354ISSUE REPLACE . . . . . . . . . . . . 356ISSUE RESET . . . . . . . . . . . . . 359ISSUE SEND . . . . . . . . . . . . . 360ISSUE SIGNAL (APPC) . . . . . . . . . . 363ISSUE SIGNAL (LUTYPE6.1) . . . . . . . . 365ISSUE WAIT. . . . . . . . . . . . . . 366JOURNAL . . . . . . . . . . . . . . 368LINK . . . . . . . . . . . . . . . . 369LINK ACQPROCESS . . . . . . . . . . . 377LINK ACTIVITY . . . . . . . . . . . . 380LOAD . . . . . . . . . . . . . . . . 384MONITOR . . . . . . . . . . . . . . 387MOVE CONTAINER (BTS) . . . . . . . . . 390MOVE CONTAINER (CHANNEL) . . . . . . 393POINT . . . . . . . . . . . . . . . 396POP HANDLE . . . . . . . . . . . . . 397POST . . . . . . . . . . . . . . . . 398PURGE MESSAGE . . . . . . . . . . . 402PUSH HANDLE . . . . . . . . . . . . 403PUT CONTAINER (BTS) . . . . . . . . . 404PUT CONTAINER (CHANNEL) . . . . . . . 407QUERY COUNTER and QUERY DCOUNTER . . 411QUERY SECURITY . . . . . . . . . . . 414READ . . . . . . . . . . . . . . . . 418READNEXT . . . . . . . . . . . . . . 430READPREV . . . . . . . . . . . . . . 441READQ TD . . . . . . . . . . . . . . 451READQ TS . . . . . . . . . . . . . . 455RECEIVE (z/OS Communications Server default) 459RECEIVE (APPC) . . . . . . . . . . . . 460RECEIVE (LUTYPE2/LUTYPE3) . . . . . . . 461RECEIVE (LUTYPE4). . . . . . . . . . . 462RECEIVE (LUTYPE6.1) . . . . . . . . . . 463RECEIVE (3270 logical) . . . . . . . . . . 464RECEIVE (3600 pipeline) . . . . . . . . . 465RECEIVE (3600-3601) . . . . . . . . . . . 466RECEIVE (3600-3614) . . . . . . . . . . . 467RECEIVE (3650) . . . . . . . . . . . . 468RECEIVE (3767) . . . . . . . . . . . . 469RECEIVE (3770) . . . . . . . . . . . . 470RECEIVE (3790 full-function or inquiry) . . . . 471RECEIVE: z/OS Communications Server options 472RECEIVE (non-z/OS Communications Serverdefault) . . . . . . . . . . . . . . . 476RECEIVE (MRO) . . . . .