C I C S T r a n s a cti o n S e rv e r f o r z/O S IBM€¦ · CONVERSE (MRO) ..... . 97 CONVERSE (2260) ..... . 98 CONVERSE: non-z/OS Communications Server options ... TEST EVENT

CICS Transaction Server for z/OS

API ReferenceVersion 5 Release 4

IBM

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

This edition applies to the IBM CICS Transaction Server for z/OS Version 5 Release 4 (product number 5655-Y04)and to all subsequent releases and modifications until otherwise indicated in new editions.

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

Contents

About this PDF . . . . . . . . . . . vii

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

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

Chapter 2. CICS command summary 17ABEND . . . . . . . . . . . . . . . 26ACQUIRE . . . . . . . . . . . . . . . 27ADD SUBEVENT . . . . . . . . . . . . 30ADDRESS . . . . . . . . . . . . . . . 31ADDRESS SET . . . . . . . . . . . . . 33ALLOCATE (APPC) . . . . . . . . . . . 33ALLOCATE (LUTYPE6.1). . . . . . . . . . 37ALLOCATE (MRO). . . . . . . . . . . . 38ASKTIME . . . . . . . . . . . . . . . 40ASSIGN . . . . . . . . . . . . . . . 41

Codes returned by ASSIGN . . . . . . . . 56BIF DEEDIT . . . . . . . . . . . . . . 58BIF DIGEST . . . . . . . . . . . . . . 59BUILD ATTACH (LUTYPE6.1) . . . . . . . . 61BUILD ATTACH (MRO) . . . . . . . . . . 64CANCEL . . . . . . . . . . . . . . . 66CANCEL (BTS) . . . . . . . . . . . . . 68CHANGE PHRASE. . . . . . . . . . . . 70CHANGE PASSWORD . . . . . . . . . . 72CHANGE TASK . . . . . . . . . . . . . 74CHECK ACQPROCESS . . . . . . . . . . 75CHECK ACTIVITY . . . . . . . . . . . . 77CHECK TIMER . . . . . . . . . . . . . 79CONNECT PROCESS . . . . . . . . . . . 80CONVERSE (default) . . . . . . . . . . . 83CONVERSE (APPC) . . . . . . . . . . . 83CONVERSE (LUTYPE2/LUTYPE3) . . . . . . 84CONVERSE (LUTYPE4) . . . . . . . . . . 85CONVERSE (LUTYPE6.1) . . . . . . . . . 85CONVERSE (SCS) . . . . . . . . . . . . 86CONVERSE (3270 logical) . . . . . . . . . 86CONVERSE (3600-3601) . . . . . . . . . . 87CONVERSE (3600-3614) . . . . . . . . . . 88CONVERSE (3650 interpreter) . . . . . . . . 88CONVERSE (3650-3270) . . . . . . . . . . 89CONVERSE (3650-3653) . . . . . . . . . . 89CONVERSE (3650-3680) . . . . . . . . . . 90CONVERSE (3767) . . . . . . . . . . . . 90CONVERSE (3770) . . . . . . . . . . . . 91

CONVERSE (3790 full-function or inquiry) . . . . 91CONVERSE (3790 3270-display) . . . . . . . 92CONVERSE: z/OS Communications Server options 92CONVERSE (non-z/OS Communications Serverdefault) . . . . . . . . . . . . . . . . 97CONVERSE (MRO). . . . . . . . . . . . 97CONVERSE (2260) . . . . . . . . . . . . 98CONVERSE: non-z/OS Communications Serveroptions . . . . . . . . . . . . . . . . 98CONVERTTIME . . . . . . . . . . . . 102DEFINE ACTIVITY . . . . . . . . . . . 104DEFINE COMPOSITE EVENT. . . . . . . . 106DEFINE COUNTER and DEFINE DCOUNTER . . 108DEFINE INPUT EVENT . . . . . . . . . . 112DEFINE PROCESS . . . . . . . . . . . 113DEFINE TIMER . . . . . . . . . . . . 115DELAY . . . . . . . . . . . . . . . 118DELETE . . . . . . . . . . . . . . . 121DELETE ACTIVITY . . . . . . . . . . . 129DELETE CHANNEL . . . . . . . . . . . 130DELETE CONTAINER (BTS) . . . . . . . . 131DELETE CONTAINER (CHANNEL) . . . . . 133DELETE COUNTER and DELETE DCOUNTER 134DELETE EVENT . . . . . . . . . . . . 136DELETE TIMER . . . . . . . . . . . . 137DELETEQ TD . . . . . . . . . . . . . 137DELETEQ TS . . . . . . . . . . . . . 139DEQ . . . . . . . . . . . . . . . . 141DOCUMENT CREATE . . . . . . . . . . 142DOCUMENT DELETE . . . . . . . . . . 146DOCUMENT INSERT . . . . . . . . . . 147DOCUMENT RETRIEVE . . . . . . . . . 150DOCUMENT SET . . . . . . . . . . . . 152DUMP TRANSACTION . . . . . . . . . . 154ENDBR . . . . . . . . . . . . . . . 159ENDBROWSE ACTIVITY . . . . . . . . . 161ENDBROWSE CONTAINER (BTS) . . . . . . 162ENDBROWSE CONTAINER (CHANNEL). . . . 162ENDBROWSE EVENT . . . . . . . . . . 163ENDBROWSE PROCESS . . . . . . . . . 164ENDBROWSE TIMER . . . . . . . . . . 164ENQ . . . . . . . . . . . . . . . . 165ENTER TRACENUM . . . . . . . . . . . 168EXTRACT ATTACH (LUTYPE6.1) . . . . . . 170EXTRACT ATTACH (MRO) . . . . . . . . 173EXTRACT ATTRIBUTES (APPC) . . . . . . . 176EXTRACT ATTRIBUTES (MRO) . . . . . . . 177EXTRACT CERTIFICATE . . . . . . . . . 179EXTRACT LOGONMSG. . . . . . . . . . 181EXTRACT PROCESS . . . . . . . . . . . 182EXTRACT TCPIP . . . . . . . . . . . . 184EXTRACT TCT . . . . . . . . . . . . . 187EXTRACT WEB . . . . . . . . . . . . 188FETCH ANY . . . . . . . . . . . . . 193FETCH CHILD . . . . . . . . . . . . . 194FORCE TIMER . . . . . . . . . . . . . 196

Copyright IBM Corp. 1989, 2017 iii

||||

FORMATTIME . . . . . . . . . . . . . 197FREE . . . . . . . . . . . . . . . . 202FREE (APPC) . . . . . . . . . . . . . 203FREE (LUTYPE6.1) . . . . . . . . . . . 204FREE (MRO) . . . . . . . . . . . . . 205FREE CHILD . . . . . . . . . . . . . 206FREEMAIN . . . . . . . . . . . . . . 207FREEMAIN64 . . . . . . . . . . . . . 210GDS ALLOCATE . . . . . . . . . . . . 212GDS ASSIGN . . . . . . . . . . . . . 214GDS CONNECT PROCESS . . . . . . . . . 215GDS EXTRACT ATTRIBUTES . . . . . . . . 217GDS EXTRACT PROCESS . . . . . . . . . 218GDS FREE . . . . . . . . . . . . . . 220GDS ISSUE ABEND . . . . . . . . . . . 221GDS ISSUE CONFIRMATION . . . . . . . . 223GDS ISSUE ERROR . . . . . . . . . . . 224GDS ISSUE PREPARE . . . . . . . . . . 225GDS ISSUE SIGNAL . . . . . . . . . . . 227GDS RECEIVE . . . . . . . . . . . . . 228GDS SEND . . . . . . . . . . . . . . 230GDS WAIT . . . . . . . . . . . . . . 232GET CONTAINER (BTS) . . . . . . . . . 234GET CONTAINER (CHANNEL) . . . . . . . 236GET COUNTER and GET DCOUNTER . . . . 241GETMAIN . . . . . . . . . . . . . . 246GETMAIN64 . . . . . . . . . . . . . 250GETNEXT ACTIVITY . . . . . . . . . . 254GETNEXT CONTAINER (BTS) . . . . . . . 255GETNEXT CONTAINER (CHANNEL) . . . . . 256GETNEXT EVENT . . . . . . . . . . . 257GETNEXT PROCESS . . . . . . . . . . . 259GETNEXT TIMER . . . . . . . . . . . . 260GET64 CONTAINER . . . . . . . . . . . 261HANDLE ABEND. . . . . . . . . . . . 266HANDLE AID . . . . . . . . . . . . . 268HANDLE CONDITION . . . . . . . . . . 270IGNORE CONDITION . . . . . . . . . . 271INQUIRE ACTIVITYID . . . . . . . . . . 272INQUIRE CONTAINER . . . . . . . . . . 275INQUIRE EVENT . . . . . . . . . . . . 277INQUIRE PROCESS . . . . . . . . . . . 278INQUIRE TIMER . . . . . . . . . . . . 279INVOKE APPLICATION . . . . . . . . . 281INVOKE SERVICE . . . . . . . . . . . 284INVOKE WEBSERVICE . . . . . . . . . . 289ISSUE ABEND . . . . . . . . . . . . . 290ISSUE ABORT . . . . . . . . . . . . . 291ISSUE ADD . . . . . . . . . . . . . . 293ISSUE CONFIRMATION . . . . . . . . . 295ISSUE COPY (3270 logical) . . . . . . . . . 296ISSUE DISCONNECT (default) . . . . . . . 297ISSUE DISCONNECT (LUTYPE6.1) . . . . . . 299ISSUE END . . . . . . . . . . . . . . 300ISSUE ENDFILE . . . . . . . . . . . . 301ISSUE ENDOUTPUT . . . . . . . . . . . 302ISSUE EODS . . . . . . . . . . . . . 303ISSUE ERASE . . . . . . . . . . . . . 304ISSUE ERASEAUP . . . . . . . . . . . 306ISSUE ERROR . . . . . . . . . . . . . 307ISSUE LOAD . . . . . . . . . . . . . 308

ISSUE NOTE . . . . . . . . . . . . . 309ISSUE PASS . . . . . . . . . . . . . . 311ISSUE PREPARE . . . . . . . . . . . . 312ISSUE PRINT . . . . . . . . . . . . . 314ISSUE QUERY . . . . . . . . . . . . . 315ISSUE RECEIVE . . . . . . . . . . . . 316ISSUE REPLACE . . . . . . . . . . . . 318ISSUE RESET . . . . . . . . . . . . . 320ISSUE SEND . . . . . . . . . . . . . 320ISSUE SIGNAL (APPC) . . . . . . . . . . 322ISSUE SIGNAL (LUTYPE6.1) . . . . . . . . 324ISSUE WAIT. . . . . . . . . . . . . . 325JOURNAL . . . . . . . . . . . . . . 326LINK . . . . . . . . . . . . . . . . 326LINK ACQPROCESS . . . . . . . . . . . 335LINK ACTIVITY . . . . . . . . . . . . 338LOAD . . . . . . . . . . . . . . . . 341MONITOR . . . . . . . . . . . . . . 344MOVE CONTAINER (BTS) . . . . . . . . . 346MOVE CONTAINER (CHANNEL) . . . . . . 349POINT . . . . . . . . . . . . . . . 351POP HANDLE . . . . . . . . . . . . . 352POST . . . . . . . . . . . . . . . . 353PURGE MESSAGE . . . . . . . . . . . 356PUSH HANDLE . . . . . . . . . . . . 357PUT CONTAINER (BTS) . . . . . . . . . 358PUT CONTAINER (CHANNEL) . . . . . . . 360PUT64 CONTAINER . . . . . . . . . . . 364QUERY CHANNEL . . . . . . . . . . . 368QUERY COUNTER and QUERY DCOUNTER . . 369QUERY SECURITY . . . . . . . . . . . 372READ . . . . . . . . . . . . . . . . 375READNEXT . . . . . . . . . . . . . . 387READPREV . . . . . . . . . . . . . . 398READQ TD . . . . . . . . . . . . . . 408READQ TS . . . . . . . . . . . . . . 412RECEIVE (z/OS Communications Server default) 416RECEIVE (APPC) . . . . . . . . . . . . 416RECEIVE (LUTYPE2/LUTYPE3) . . . . . . . 417RECEIVE (LUTYPE4). . . . . . . . . . . 417RECEIVE (LUTYPE6.1) . . . . . . . . . . 418RECEIVE (3270 logical) . . . . . . . . . . 418RECEIVE (3600 pipeline) . . . . . . . . . 419RECEIVE (3600-3601) . . . . . . . . . . . 419RECEIVE (3600-3614) . . . . . . . . . . . 420RECEIVE (3650) . . . . . . . . . . . . 420RECEIVE (3767) . . . . . . . . . . . . 421RECEIVE (3770) . . . . . . . . . . . . 421RECEIVE (3790 full-function or inquiry) . . . . 422RECEIVE: z/OS Communications Server options 422RECEIVE (non-z/OS Communications Serverdefault) . . . . . . . . . . . . . . . 426RECEIVE (MRO) . . . . . . . . . . . . 426RECEIVE (2260) . . . . . . . . . . . . 427RECEIVE (2980) . . . . . . . . . . . . 427RECEIVE (3790 3270-display) . . . . . . . . 429RECEIVE: non-z/OSCommunications Serveroptions . . . . . . . . . . . . . . . 430RECEIVE MAP . . . . . . . . . . . . . 434RECEIVE MAP MAPPINGDEV . . . . . . . 437RECEIVE PARTN . . . . . . . . . . . . 439

iv CICS TS for z/OS: API Reference

||

RELEASE. . . . . . . . . . . . . . . 441REMOVE SUBEVENT . . . . . . . . . . 443REQUEST ENCRYPTPTKT . . . . . . . . . 444REQUEST PASSTICKET . . . . . . . . . . 446RESET ACQPROCESS . . . . . . . . . . 448RESET ACTIVITY . . . . . . . . . . . . 449RESETBR. . . . . . . . . . . . . . . 450RESUME . . . . . . . . . . . . . . . 455RETRIEVE . . . . . . . . . . . . . . 456RETRIEVE REATTACH EVENT . . . . . . . 460RETRIEVE SUBEVENT . . . . . . . . . . 461RETURN . . . . . . . . . . . . . . . 463REWIND COUNTER and REWIND DCOUNTER 466REWRITE . . . . . . . . . . . . . . 469ROUTE . . . . . . . . . . . . . . . 474RUN . . . . . . . . . . . . . . . . 478RUN TRANSID . . . . . . . . . . . . 482SEND (z/OS Communications Server default) . . 484SEND (APPC) . . . . . . . . . . . . . 485SEND (LUTYPE2/LUTYPE3) . . . . . . . . 485SEND (LUTYPE4) . . . . . . . . . . . . 485SEND (LUTYPE6.1) . . . . . . . . . . . 486SEND (SCS) . . . . . . . . . . . . . . 486SEND (3270 logical) . . . . . . . . . . . 487SEND (3600 pipeline). . . . . . . . . . . 487SEND (3600-3601) . . . . . . . . . . . . 488SEND (3600-3614) . . . . . . . . . . . . 489SEND (3650 interpreter) . . . . . . . . . . 489SEND (3650-3270) . . . . . . . . . . . . 490SEND (3650-3653) . . . . . . . . . . . . 490SEND (3650-3680) . . . . . . . . . . . . 491SEND (3767). . . . . . . . . . . . . . 491SEND (3770). . . . . . . . . . . . . . 491SEND (3790 full-function or inquiry) . . . . . 492SEND (3790 SCS) . . . . . . . . . . . . 492SEND (3790 3270-display) . . . . . . . . . 493SEND (3790 3270-printer) . . . . . . . . . 493SEND: z/OS Communications Server options . . 493SEND (non-z/OS Communications Server default) 497SEND (MRO) . . . . . . . . . . . . . 498SEND (2260). . . . . . . . . . . . . . 498SEND (2980). . . . . . . . . . . . . . 498SEND: non-z/OS Communications Server options 499SEND CONTROL . . . . . . . . . . . . 502SEND MAP . . . . . . . . . . . . . . 507SEND MAP MAPPINGDEV . . . . . . . . 514SEND PAGE. . . . . . . . . . . . . . 517SEND PARTNSET . . . . . . . . . . . . 520SEND TEXT . . . . . . . . . . . . . . 521SEND TEXT MAPPED . . . . . . . . . . 528SEND TEXT NOEDIT . . . . . . . . . . 530SIGNAL EVENT . . . . . . . . . . . . 533SIGNOFF. . . . . . . . . . . . . . . 535SIGNON . . . . . . . . . . . . . . . 536SIGNON TOKEN . . . . . . . . . . . . 540SOAPFAULT ADD . . . . . . . . . . . 544SOAPFAULT CREATE . . . . . . . . . . 546SOAPFAULT DELETE . . . . . . . . . . 550SPOOLCLOSE . . . . . . . . . . . . . 551SPOOLOPEN INPUT. . . . . . . . . . . 553SPOOLOPEN OUTPUT . . . . . . . . . . 556

SPOOLREAD . . . . . . . . . . . . . 560SPOOLWRITE . . . . . . . . . . . . . 563START . . . . . . . . . . . . . . . 565START ATTACH . . . . . . . . . . . . 576START BREXIT . . . . . . . . . . . . . 577START CHANNEL . . . . . . . . . . . 580STARTBR. . . . . . . . . . . . . . . 584STARTBROWSE ACTIVITY. . . . . . . . . 591STARTBROWSE CONTAINER (BTS) . . . . . 592STARTBROWSE CONTAINER (CHANNEL) . . . 594STARTBROWSE EVENT. . . . . . . . . . 595STARTBROWSE PROCESS . . . . . . . . . 596STARTBROWSE TIMER . . . . . . . . . . 597SUSPEND . . . . . . . . . . . . . . 598SUSPEND (BTS) . . . . . . . . . . . . 598SYNCPOINT . . . . . . . . . . . . . 600SYNCPOINT ROLLBACK . . . . . . . . . 601TEST EVENT . . . . . . . . . . . . . 602TRANSFORM DATATOJSON . . . . . . . . 602TRANSFORM DATATOXML . . . . . . . . 604TRANSFORM JSONTODATA . . . . . . . . 607TRANSFORM XMLTODATA . . . . . . . . 608UNLOCK. . . . . . . . . . . . . . . 611UPDATE COUNTER and UPDATE DCOUNTER 615VERIFY PASSWORD . . . . . . . . . . . 618VERIFY PHRASE . . . . . . . . . . . . 621VERIFY TOKEN . . . . . . . . . . . . 624WAIT CONVID (APPC) . . . . . . . . . . 627WAIT EVENT . . . . . . . . . . . . . 628WAIT EXTERNAL. . . . . . . . . . . . 630WAIT JOURNALNAME . . . . . . . . . . 633WAIT JOURNALNUM . . . . . . . . . . 635WAIT SIGNAL . . . . . . . . . . . . . 636WAIT TERMINAL. . . . . . . . . . . . 637WAITCICS . . . . . . . . . . . . . . 638WEB CLOSE . . . . . . . . . . . . . 640WEB CONVERSE . . . . . . . . . . . . 642WEB ENDBROWSE FORMFIELD . . . . . . 656WEB ENDBROWSE HTTPHEADER . . . . . . 656WEB ENDBROWSE QUERYPARM . . . . . . 657WEB EXTRACT . . . . . . . . . . . . 658WEB OPEN . . . . . . . . . . . . . . 662WEB PARSE URL . . . . . . . . . . . . 668WEB READ FORMFIELD . . . . . . . . . 670WEB READ HTTPHEADER . . . . . . . . 672WEB READ QUERYPARM . . . . . . . . . 674WEB READNEXT FORMFIELD . . . . . . . 676WEB READNEXT HTTPHEADER . . . . . . 677WEB READNEXT QUERYPARM . . . . . . . 679WEB RECEIVE (Server) . . . . . . . . . . 680WEB RECEIVE (Client) . . . . . . . . . . 687WEB RETRIEVE . . . . . . . . . . . . 694WEB SEND (Server) . . . . . . . . . . . 695WEB SEND (Client) . . . . . . . . . . . 704WEB STARTBROWSE FORMFIELD . . . . . . 714WEB STARTBROWSE HTTPHEADER . . . . . 716WEB STARTBROWSE QUERYPARM . . . . . 717WEB WRITE HTTPHEADER . . . . . . . . 718WRITE . . . . . . . . . . . . . . . 721WRITE JOURNALNAME . . . . . . . . . 728WRITE JOURNALNUM . . . . . . . . . . 731

Contents v

||

||

||

WRITE OPERATOR . . . . . . . . . . . 732WRITEQ TD. . . . . . . . . . . . . . 735WRITEQ TS . . . . . . . . . . . . . . 737WSACONTEXT BUILD . . . . . . . . . . 741WSACONTEXT DELETE . . . . . . . . . 745WSACONTEXT GET . . . . . . . . . . . 746WSAEPR CREATE . . . . . . . . . . . 750XCTL . . . . . . . . . . . . . . . . 753

Chapter 3. Threadsafe commands . . 757

Chapter 4. CICS-value data areas usedby all commands . . . . . . . . . . 761CVDAs and numeric values in alphabetic sequence 761CVDA values for the DEVICE option . . . . . 785CVDAs and numeric values in numeric sequence 788

Chapter 5. National language codes 813

Chapter 6. Terminal control . . . . . 815Commands and options for terminals and logicalunits . . . . . . . . . . . . . . . . 815Teletypewriter programming . . . . . . . . 817Display device operations . . . . . . . . . 818

Print displayed information (ISSUE PRINT) . . 818Copy displayed information (ISSUE COPY) . . 819Erase all unprotected fields (ISSUE ERASEAUP) 819

Handle input without data (RECEIVE) . . . . 820

Chapter 7. Common ProgrammingInterface Communications (CPICommunications) . . . . . . . . . 821SAA Resource Recovery . . . . . . . . . . 821

Chapter 8. BMS-related constants . . 823Magnetic slot reader (MSR) control value constants,DFHMSRCA . . . . . . . . . . . . . 826MSR control byte values. . . . . . . . . . 826Attention identifier constants, DFHAID . . . . 827

Chapter 9. BMS macros . . . . . . . 829Map set, map, and field definition . . . . . . 829Partition set definition . . . . . . . . . . 830

Field groups. . . . . . . . . . . . . 830DFHMDF . . . . . . . . . . . . . . 831DFHMDI . . . . . . . . . . . . . . . 842DFHMSD. . . . . . . . . . . . . . . 851DFHPDI . . . . . . . . . . . . . . . 862DFHPSD . . . . . . . . . . . . . . . 863

Notices . . . . . . . . . . . . . . 865

Index . . . . . . . . . . . . . . . 871

vi CICS TS for z/OS: API Reference

About this PDF

This PDF is a reference of the commands of the CICS application programminginterface. This documentation is intended for application programmers who arewriting applications to interact with CICS. Before CICS TS V5.4, this PDF wascalled the Application Programming Reference.

For information about how to write applications for CICS, using this API, seeDeveloping CICS Applications.

For details of the terms and notation used in this book, see Conventions andterminology used in the CICS documentation in IBM Knowledge Center.

Date of this PDF

This PDF was created on August 24th 2018.

Copyright IBM Corp. 1989, 2017 vii

http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/documentation/conventions.htmlhttp://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/documentation/conventions.html

viii CICS TS for z/OS: API Reference

Chapter 1. CICS API 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 moreoptions.

The command format is as follows:

where:

commanddescribes the operation required (for example, READ).

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

arg (short for argument) is a value such as data-value or name. Adata-value can be a constant, this means that an argument that sendsdata to CICS is generally a data-value. An argument that receives datafrom CICS must be a data-area.

Some arguments described as data-area can both send and receive data.In these cases, you must ensure that the data-area is not in protectedstorage.

An example of a CICS command is as follows:

You must add the appropriate end-of-command delimiter; see CICS commandsyntax notation on page 2.

Note: If you want to add comments against CICS commands, you can do this, inassembler only, by using a period or a comma as a delimiter after the lastargument. For example:EXEC CICS ADDRESS EIB(MYUEIB), @F1A

If a period or a comma is used with an EXEC CICS command, the following linemust begin between column 2 and column 16, with the continuation character incolumn 72. The following line cannot start after column 17. If there is no comma orperiod added, the following line must begin at or after column 2 and end bycolumn 71, with the continuation character in column 72.

EXEC CICS command option(arg)....

EXEC CICS READFILE(FILEA)INTO(FILEA)RIDFLD(KEYNUM)UPDATE

Copyright IBM Corp. 1989, 2017 1

CICS command syntax notationIn CICS documentation, CICS commands are presented in a standard way. Youinterpret the syntax by following the arrows from left to right.

The EXEC CICS that always precedes each command's keyword is not included;nor is the END-EXEC statement used in COBOL or the semicolon (;) used inPL/I and C that you must code at the end of each CICS command. In the Clanguage, a null character can be used as an end-of-string marker, but CICS doesnot recognize this; you must therefore never have a comma or period followed bya space (X'40') in the middle of a coding line.

The conventions are:

Symbol Action

ABC

A set of alternativesone of which you must code.

ABC

A set of alternativesone of which you must code. Youmay code more than one of them, in any sequence.

ABC

A set of alternativesone of which you may code.

ABC

A set of alternatives any number (including none) ofwhich you may code once, in any sequence.

A

B

Alternatives where A is the default.

Name

Name:

AB

Use with the named section in place of its name.

Punctuation and uppercasecharacters

Code exactly as shown.

2 CICS TS for z/OS: API Reference

Symbol Action

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

CICS command argument valuesThe data associated with a command option is called its argument. Each type ofargument can contain different data types; some arguments return informationfrom CICS to the program and others are set by the program.

Options in a CICS command can take the following argument values:v data-valuev data-areav cvda (CICS-value data area)v ptr-valuev ptr-refv namev filenamev systemnamev labelv hhmmss

For AMODE(64) programs only, options in a CICS command can also take thefollowing argument values:v data-area64v ptr-value64v ptr-ref64

Data areas and data values

Data areas and data values are the basic argument types. The difference betweenthem is the direction in which information flows when a task executes a command.A data-value is always, can only be, a sender; it conveys data to CICS that CICSuses to process the command. A data-area is a receiver; CICS uses it to returninformation to the caller. A data-area can also be a sender, for example when thedata to convey to CICS is variable length (as in FROM), or where a field is usedboth for input and output.

COBOL argument values

The argument values can be replaced as follows:v data-value can be replaced by 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 theargument. The following table shows how to define the correct data type:

Data type COBOL definition

Halfword binary PIC S9(4) COMP

Fullword binary PIC S9(8) COMP

Doubleword unsigned binary PIC 9(18) COMP

Character string PIC X(n) where n is the number of bytes

Chapter 1. CICS API command format 3


UTF-8 character string PIC X(n) where n is the number of bytes

v data-area can be replaced by any COBOL data name of the correct data type forthe argument. The following table shows how to define the correct data type:


Halfword binary PIC S9(4) COMP

Fullword binary PIC S9(8) COMP

Doubleword unsigned binary PIC 9(18) COMP

Character string PIC X(n) where n is the number of bytes

UTF-8 character string PIC X(n) where n is the number of bytes

Where the data type is unspecified, data-area can refer to an elementary or groupitem.

v cvda is described in CICS-value data areas (CVDAs).v ptr-value can be replaced by a pointer variable or ADDRESS special register.v ptr-ref can be replaced by a pointer variable or ADDRESS special register.v name can be replaced by either of the following values:

A character string specified as an alphanumeric literal. If this string is shorterthan the required length, it is padded with blanks.

A COBOL data area with a length equal to the required length for the name.The value in data-area is the name to be used by the argument. If data-area isshorter than the required length, the excess characters are undefined, whichmight cause unpredictable results.

filename, as used in FILE(filename), specifies the name of the file. The name mustcontain 18 characters from the range AZ, 09, $, @, and #.systemname, as used in SYSID(systemname), specifies the name of the system towhich the request is directed. The name must contain 14 characters from therange AZ, 09, $, @, and #.

v label can be replaced by any COBOL paragraph name or a section name.v hhmmss can be replaced by a decimal constant or by a data name of the form

PIC S9(7) COMP-3. The value must be of the form 0HHMMSS+ where:

HH Represents hours from 00 through 99.

MM Represents minutes from 00 through 59.

SS Represents seconds from 00 through 59.

In COBOL, you do not need to code the LENGTH option unless you want theprogram to read or write data of a length that is different from that of thereferenced variable.

C argument values

The argument values can be replaced as follows:v data-value can be replaced by any C expression that can be converted to the

correct data type for the argument. The following table shows how to define thecorrect data type:


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/system-programming/intro/dfha80x.html

Data type C definition

Halfword binary short int

Fullword binary long int

Doubleword binary char[8]

Character string char[n] where n is the number of bytes

UTF-8 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 C data reference that has the correct data type

for the argument. The following table shows how to define the correct data type:

Data type C definition

Halfword binary short int

Fullword binary long int

Doubleword binary char[8]

Character string char[n] where n is the number of bytes

UTF-8 character string char[n] where n is the number of bytes

If the data type is unspecified, data-area can refer to a scalar data type, array, orstructure. The reference must be to contiguous storage.

v cvda is described in CICS-value data areas (CVDAs).v ptr-value (which includes ptr-ref as a subset) can be replaced by any C expression

that can be converted to an address.v ptr-ref can be replaced by any C pointer type reference.v name can be replaced by either of the following values:

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

array with a length equal to the maximum length allowed for the name. Thevalue of the character array is the name to be used by the argument.

filename, as used in FILE(filename), specifies the name of the file. The name musthave 18 characters from the range AZ, 09, $, @, and #.systemname, as used in SYSID(systemname), specifies the name of the system towhich the request is directed. The name must have 14 characters from therange AZ, 09, $, @, and #.

v label is not supported in the C language.v hhmmss can be replaced by an integer constant; otherwise the application is

responsible for ensuring that the value passed to CICS is in packed decimalformat. The language does not provide a packed decimal type.




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



PL/I argument values

The argument values can be replaced 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 following table shows how to define thecorrect data type:

Data type PL/I definition

Halfword binary FIXED BIN(15)

Fullword binary FIXED BIN(31)

Doubleword binary CHAR (8)

Character string CHAR(n) where n is the number of bytes

UTF-8 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 following table shows how to define the correct datatype:

Data type PL/I definition

Halfword binary FIXED BIN(15)

Fullword binary FIXED BIN(31)

Doubleword binary CHAR (8)

Character string CHAR(n) where n is the number of bytes

UTF-8 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, orstructure; for example, FROM(P>STRUCTURE) LENGTH(LNG). The referencemust be to connected storage.The data area must also have the correct PL/I alignment attribute: ALIGNED forbinary items, and UNALIGNED for strings.If you use a varying data string without an explicit length, the data passedbegins with a two-byte length field, and its length is the maximum lengthdeclared for the string. If you explicitly specify a length in the command, thedata passed has this length; that is, the two-byte length field followed by dataup to the length you specified.

v cvda is described in CICS-value data areas (CVDAs).v ptr-value (which includes ptr-refas 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 values:

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 equal to the maximum length allowed for the name. Thevalue of the character string is the name to be used by the argument.

filename, as used in FILE(filename), specifies the name of the file. The name musthave 1-8 characters from the range AZ, 09, $, @, and #.systemname, as used in SYSID(systemname), specifies the name of the system towhich the request is directed. The name must have 1-4 characters from the rangeAZ, 09, $, @, and #.



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 form0HHMMSS+ where:




If the UNALIGNED attribute is added to the ENTRY declarations generated by theCICS translator by a DEFAULT DESCRIPTORS statement, data-area orpointer-reference arguments to CICS commands must also be UNALIGNED.Similarly for the ALIGNED attribute, data-area or pointer-reference argumentsmust be ALIGNED.

Many commands involve the transfer of data between the application program andCICS. In most cases, the length of the data to be transferred must be provided bythe application program. However, if a data area is specified as the source ortarget, it is not necessary to provide the length explicitly, because thecommand-language translator generates a default length value of eitherSTG(data-area) or CSTG(data-area), as appropriate.

Assembler-language argument values for AMODE(24) andAMODE(31) programs

In general, an argument can be either the address of the data or the data itself (inassembler language terms, either a relocatable expression or an absoluteexpression).

A relocatable expression must not contain unmatched brackets (outside quotationmarks) or unmatched quotation marks (apart from length-attribute references). Ifthis rule is obeyed, any expression can be used, including literal constants, such as=AL2(100), forms such as 20(0,R11), and forms that use the macro-replacementfacilities.

An absolute expression must be a single term that is either a length-attributereference, or a self-defining constant.

Use care with equated symbols, which should be used only when referring toregisters (pointer references). For example, if an equated symbol is used for alength, it is treated as the address of the length and an unpredictable error occurs.

For AMODE(24) and AMODE(31) assembler language programs, the argumentvalues can be replaced as follows:v data-value can be replaced by a relocatable expression that is an

assembler-language reference to data of the correct type for the argument, or bya constant of the correct type for the argument.

v data-area can be replaced by a relocatable expression that is anassembler-language reference to data of the correct type for the argument.

v cvda is described in CICS-value data areas (CVDAs).v ptr-value can be replaced by an absolute expression that is an assembler-language

reference to a register.v ptr-ref can be replaced by an absolute expression that is an assembler-language

reference to a register.



v name can be replaced either by a character string in single quotation marks, orby an assembler-language language relocatable expression reference to acharacter string. The length is equal to the maximum length allowed for thename. The value of the character string is the name to be used by the argument.filename, as used in FILE(filename), specifies the name of the file. The name musthave 18 characters from the range AZ, 09, $, @, and #.systemname, as used in SYSID(systemname), specifies the name of the system towhich the request is directed. The name must have 14 characters from therange AZ, 09, $, @, and #.

v label refers to a destination address to which control is transferred. It can bereplaced by the label of the destination instruction or by the label of an addressconstant for the destination. This constant must not specify a length.You can also use the expression =A(dest) where dest is a relocatable expressiondenoting the destination.For example, the following commands are equivalent:

v hhmmss can be replaced by a self-defining decimal constant, or anassembler-language reference to a field defined as PL4. The value must be of theform 0HHMMSS+ where:

HH Represents hours from 00 through 99

MM Represents minutes from 00 through 59

SS Represents seconds from 00 through 59

Many commands involve the transfer of data between the application program andCICS. In most cases, the application program must provide the length of the datato be transferred. However, if a data area is specified as the source or target, it isnot necessary to provide the length explicitly, because the command-languagetranslator generates a default length. For example:

Assembler-language argument values for AMODE(64) programs

In general, an argument can be either the address of the data or the data itself (inassembler language terms, either a relocatable expression or an absoluteexpression).

A relocatable expression must not contain unmatched brackets (outside quotationmarks) or unmatched quotation marks (apart from length-attribute references). If

HANDLE CONDITION ERROR(DEST)HANDLE CONDITION ERROR(ADCON)HANDLE CONDITION ERROR(=A(DEST))...DEST BR 14ADCON DC A(DEST)

xxx DC CL8..EXEC CICS ... LENGTH(Lxxx)


this rule is obeyed, any expression can be used, including literal constants, such as=AL2(100), forms such as 20(0,R11), and forms that use the macro-replacementfacilities.

An absolute expression must be a single term that is either a length-attributereference, or a self-defining constant.

Use care with equated symbols, which should be used only when referring toregisters (pointer references). For example, if an equated symbol is used for alength, it is treated as the address of the length and an unpredictable error occurs.

For non-Language Environment (LE) AMODE(64) assembler language programs,argument values can be replaced as follows:v data-value can be replaced by a relocatable expression that is an

assembler-language reference to data of the correct type for the argument, or bya constant of the correct type for the argument.

v data-area can be replaced by a relocatable expression that is anassembler-language reference to data of the correct type for the argument.

v data-area64 can be replaced by a relocatable expression that is anassembler-language 64-bit reference to data of the correct type for the argument.

v cvda is described in CICS-value data areas (CVDAs).v ptr-value can be replaced by an absolute expression that is an assembler-language

reference to a register.v ptr-value64 can be replaced by an absolute expression that is an

assembler-language 64-bit reference to a register.v ptr-ref can be replaced by an absolute expression that is an assembler-language

reference to a register.v ptr-ref64 can be replaced by an absolute expression that is an assembler-language

64-bit reference to a register.v name can be replaced either by a character string in single quotation marks, or

by an assembler-language language relocatable expression reference to acharacter string. The length is equal to the maximum length allowed for thename. The value of the character string is the name to be used by the argument.filename, as used in FILE(filename), specifies the name of the file. The name musthave 18 characters from the range AZ, 09, $, @, and #.systemname, as used in SYSID(systemname), specifies the name of the system towhich the request is directed. The name must have 14 characters from therange AZ, 09, $, @, and #.

v hhmmss can be replaced by a self-defining decimal constant, or anassembler-language reference to a field defined as PL4. The value must be of theform 0HHMMSS+ where:

HH Represents hours from 00 through 99

MM Represents minutes from 00 through 59

SS Represents seconds from 00 through 59

label is not supported for AMODE(64) programs.

Many commands involve the transfer of data between the application program andCICS. In most cases, the application program must provide the length of the datato be transferred. However, if a data area is specified as the source or target, it isnot necessary to provide the length explicitly, because the command-language



translator generates a default length. For example:

CICS command restrictionsSome general restrictions apply to all CICS commands that access user data.v The program must be in primary addressing mode when invoking any CICS

service. The primary address space must be the home address space. Allparameters passed to CICS must reside in the primary address space.

v If your program uses access registers, CICS preserves only access registers 2through 13, because CICS code can use access registers 0, 1, 14 and 15 for z/OS

macro calls.

LENGTH options in CICS commandsIn COBOL, PL/I, and Assembler language, the translator defaults certain lengths, ifthe NOLENGTH translator option is not specified. This means they are optional inprograms that specify data areas. In C, all LENGTH options must be specified.

When a CICS command offers the LENGTH option, it is expressed as a signedhalfword binary value. This puts a theoretical upper limit of 32 763 bytes onLENGTH. In practice, depending on issues of recoverability, function shipping, andother factors, assume a 24 KB limit.

This advisory 24 KB limit does not apply to the FLENGTH option on CICScommands (except for terminal-related SEND and RECEIVE commands, because ofarchitectural limitations). The FLENGTH option is used on commands that relate tocontainers and journals, among others.

For temporary storage, transient data, and file control commands, the data setdefinitions themselves might impose further restrictions.

NOHANDLE optionUse the NOHANDLE option with any command to specify that you want noaction to be taken for any condition or AID resulting from the execution of thatcommand.

For further information about the NOHANDLE option, see RESP andNOHANDLE options .

Using the C or C++ language implies NOHANDLE on all commands.

RESP and RESP2 optionsYou can use the RESP option with any command to test whether a condition wasraised during its execution. With some commands, when a condition can be raisedfor more than one reason, if you have already specified RESP, you can use theRESP2 option to determine exactly why a condition occurred.

xxx DC CL8..EXEC CICS ... LENGTH(Lxxx)


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/applications/designing/dfhp3_exc_resp_nohandle.htmlhttp://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/applications/designing/dfhp3_exc_resp_nohandle.html

RESP(xxx)xxx is a user-defined fullword binary data area. On return from the command,it contains a value that corresponds to the condition that might be raised, or toa normal return, that is, xxx=DFHRESP(NORMAL). You can test this value bymeans of DFHRESP, as follows:

This form of DFHRESP applies to both COBOL and PL/I.

The following example is a similar test in C:

The following example is a similar test in assembler language:

The translator changes this code to:

Because the use of RESP implies NOHANDLE, use care when you use RESPwith the RECEIVE command. NOHANDLE overrides both the HANDLE AIDand the HANDLE CONDITION command, with the result that PF keyresponses are ignored.

RESP2(yyy)yyy is a user-defined fullword binary data area. On return from the command,it contains a value that further qualifies the response to certain commands.Unlike the RESP values, RESP2 values have no associated symbolic names andthere is no translator built-in function that corresponds to DFHRESP, so youmust test the fullword binary value itself.

Translated code for CICS commandsApplication programs can be written in COBOL, C, PL/I, or assembler language,and contain CICS commands. CICS translates these programs and creates anequivalent source program where each command is now translated into a callmacro or statement in the language of the original source program.

EXEC CICS WRITEQ TS FROM(abc)QUEUE(qname)NOSUSPENDRESP(xxx)RESP2(yyy)

.

.IF xxx=DFHRESP(NOSPACE) THEN ...

switch (xxx) {case DFHRESP(NORMAL) : break;case DFHRESP(INVREQ) : Invreq_Cond();

break;default : Errors();

}

CLC xxx,DFHRESP(NOSPACE)

CLC xxx,=F18


COBOL translation outputEXEC CICS commands are converted to calls to the CICS interface DFHEI1.

The following example shows how the EXEC statement:is translated to:

Copybook DFHEIBLCThis new copybook is a lower case version of the existing DFHEIBLK copybook.

A difference is that in DFHEIBLK the top level name is

whereas in DFHEIBLC the top level name is

This is consistent with the name generated by the translator today, and alsoconforms to the rule that CICS reserved words should start with DFH.

C translation outputFor a C application program, each command is replaced by reassignmentstatements followed by a dfhexec statement that passes the parameters.

PL/I translation outputFor a PL/I application program, each command is always replaced by a DOstatement, a declaration of a generated entry name, a CALL statement, and anEND statement. The ENTRY declaration ensures that the appropriate conversionsfor argument values take place.

If a PL/I on-unit consists of a single EXEC CICS command, the command shouldbe inside a BEGIN block, for example:

EXEC CICS RETURN TRANSID(fred)COMMAREA(mycommarea) END-EXEC.

Move length of mycommarea to dfhb0020Call DFHEI1 using by content

x0e08e0000700001000f0f0f0f2f7404040by content fred by reference mycommareaby reference dfhb0020 end-call.

01 EIBLK.

01 dfheiblk.

ON ERROR BEGIN;EXEC CICS RETURN;END;


In a similar way, if an EXEC CICS command is associated with a PL/I conditionprefix, the command should be inside a BEGIN block, for example:

If OPTIONS(MAIN) is specified, the translator modifies the parameter list byinserting the EIB structure pointer as the first parameter. If OPTIONS(MAIN) is notspecified (that is, if the program is to be link-edited to the main module), theparameter list is not modified, and it is the application programmer's responsibilityto address the EIB structure in the link-edited program if access to it is required. Ineither case, where a program commences with a valid PL/I PROCEDUREstatement, the translator inserts the declaration of the EIB structure.

Assembler translation outputThe invocation of a CICS assembler language application program obeys systemstandards.

On entry to the application program, registers 1, 15, 14, and 13 contain thefollowing addresses:v Register 1 contains the address of the parameter list. This list has at least two

entries: Address of the EIB (EXEC interface block) Address of the COMMAREA; if no COMMAREA, entry is X'00000000'

v Register 15 contains the address of the entry point.v Register 14 contains the address of the return point.v Register 13 contains the address of the save area.

All other registers are undefined.

DFHECALL macroFor an assembler language application program, when the CICS translator detectsa CICS command, each command is replaced by an invocation of the DFHECALLmacro. The DFHECALL macro sets up the command parameters and calls theinitial CICS command processor to handle the command.

This macro expands to a system-standard call sequence that uses registers 15, 14, 0,and 1. The contents of these registers are as follows:v Register 15 contains the address of the entry point in the EXEC interface

program.v Register 14 contains the address of the return point in your application program.v Register 0 is undefined.v Register 1 contains the address of the parameter list.

The entry point held in register 15 is resolved in the EXEC interface processor thatmust be link-edited with your application program. For AMODE(24) andAMODE(31) applications, this EXEC interface processor is DFHEAI; forAMODE(64) applications, it is DFHEAG.

(NOZERODIVIDE): BEGIN;EXEC CICS GETMAINSET(ptr-ref)LENGTH(data-value);END;


You can specify the exit from the application program by an EXEC CICS RETURNcommand in your source program. Alternatively, you can use the DFHEIRETmacro, which restores the registers and returns control to the address in register 14.The translator inserts the DFHEIRET macro, with no parameters specified,immediately before the END statement, unless you specify the NOEPILOGtranslator option. You can use this macro to return from a top-level program, but isnot advisable from a lower-level program.

During assembly, the DFHECALL macro builds an argument list in dynamicstorage, so that the application program is reentrant. Then the macro invokes theEXEC interface program DFHEIP for AMODE(24) or AMODE(31) applications, orDFHEIG for AMODE(64) applications. These programs also obey system standards,as previously described.

For AMODE(64) applications, although the application and the initial commandprocessor run in 64-bit addressing mode, the parameters that the DFHECALLmacro sets up and passes to the initial command processor contain 31-bitaddresses. Therefore, the storage in which the call parameters are built, theDFHEISTG storage, must be 31-bit storage (above 16 MB but below 2 GB).

In addition to the invocation of the DFHECALL macro, the translator also insertsthe following macros into your source program:

DFHEIGBL

This macro sets globals if you are using EXEC DLI in either a batch or anonline CICS application program. Within DFHEIGBL, if DFHEIDL is set to1, this means that the program contains EXEC DLI commands. If DFHEIDBis set to 1, this means that the program is batch DL/I. If you are not usingDL/I, it is commented and set to 0.

DFHEIENT

This macro is inserted after the first CSECT or START instruction. Itperforms prolog code to allocate working storage to hold any uservariables and for CICS use:v It saves registersv It gets an initial allocation of the storage that is defined by DFHEISTGv It sets up a base register (default register 3)v It sets up a dynamic storage register (default register 13)v It sets up a register to address the EIB (default register 11)

DFHEIRET

This macro performs epilog code to release the working storage of theapplication program:v It restores registers.

DFHEIRET RCREG=nn, where nn (any register number other than 13)contains the return code to be placed in register 15 after the registers arerestored.

v It returns control to the address in register 14.

DFHEISTG and DFHEIEND

These macros define dynamic storage:v They define the storage required for the parameter listv They define a save area.


For further details about these macros with AMODE(64) applications, see Codingthe EXEC CICS(r) assembler interface.

A copybook, DFHEIBLK, that contains a DSECT that describes the EIB, is alsoincluded automatically.

The program must have an END statement because the translator does nototherwise insert the default macros. Also CSECT or START and END must be inuppercase for the translator to recognize them.

The example in Figure 1 shows a simple assembler language application programthat uses the BMS command SEND MAP to send a map to a terminal, followed bythe output after program INSTRUCT is translated.

Source program

INSTRUCT CSECTEXEC CICS SEND MAP(DFH$AGA) MAPONLY ERASEEND

This source program is translated to:

DFHEIGBL , INSERTED BY TRANSLATORINSTRUCT CSECT

DFHEIENT INSERTED BY TRANSLATOR* EXEC CICS SEND MAP(DFH$AGA) MAPONLY ERASE

DFHECALL =X1804C0000800000000046204000020,(CHA7,=CL7DFH$AGA*),(______RF,DFHEIV00)

DFHEIRET INSERTED BY TRANSLATORDFHEISTG INSERTED BY TRANSLATORDFHEIEND INSERTED BY TRANSLATOREND

Figure 1. Source program and translated code for a CICS command


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/applications/developing/assembler/dfhp4b00139.htmlhttp://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/applications/developing/assembler/dfhp4b00139.html

Chapter 2. CICS command summary

The EXEC CICS commands categorized according to the function they perform.

For EIB response codes, see Response codes of EXEC CICS commands.

For EIB function codes, see Function codes of EXEC CICS commands.

Abend supportv ABENDv HANDLE ABEND

APPC basic conversationv GDS ALLOCATEv GDS ASSIGNv GDS CONNECT PROCESSv GDS EXTRACT ATTRIBUTESv GDS EXTRACT PROCESSv GDS FREEv GDS ISSUE ABENDv GDS ISSUE CONFIRMATIONv GDS ISSUE ERRORv GDS ISSUE PREPAREv GDS ISSUE SIGNALv GDS RECEIVEv GDS SENDv GDS WAIT

APPC mapped conversationv ALLOCATE (APPC)v CONNECT PROCESSv CONVERSE (APPC)v EXTRACT ATTRIBUTES (APPC)v EXTRACT PROCESSv FREE (APPC)v ISSUE ABENDv ISSUE CONFIRMATIONv ISSUE ERRORv ISSUE PREPAREv ISSUE SIGNAL (APPC)v RECEIVE (APPC)v SEND (APPC)v WAIT CONVID (APPC)

Copyright IBM Corp. 1989, 2017 17

http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/reference/commands-api/dfha8me.htmlhttp://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/reference/commands-api/dfha8mf.html

Asynchronous Servicesv FETCH ANYv FETCH CHILDv FREE CHILDv RUN TRANSID

Authenticationv CHANGE PASSWORDv CHANGE PHRASE on page 70v SIGNOFFv SIGNONv SIGNON TOKENv VERIFY PASSWORDv VERIFY PHRASEv VERIFY TOKEN

Batch data interchangev ISSUE ABORTv ISSUE ADDv ISSUE ENDv ISSUE ERASEv ISSUE NOTEv ISSUE QUERYv ISSUE RECEIVEv ISSUE REPLACEv ISSUE SENDv ISSUE WAIT

BMSv PURGE MESSAGEv RECEIVE MAPv RECEIVE MAP MAPPINGDEVv RECEIVE PARTNv ROUTEv SEND CONTROLv SEND MAPv SEND MAP MAPPINGDEVv SEND PAGEv SEND PARTNSETv SEND TEXTv SEND TEXT MAPPEDv SEND TEXTNOEDIT

Built-in functionsv BIF DEEDITv BIF DIGEST


|

|

|

|

|

CICS business transaction services (BTS)v ACQUIREv ADD SUBEVENTv CANCELv CANCEL (BTS) on page 68v CHECK ACQPROCESSv CHECK ACTIVITYv CHECK TIMERv DEFINE ACTIVITYv DEFINE COMPOSITE EVENTv DEFINE INPUT EVENTv DEFINE PROCESSv DEFINE TIMERv DELETE ACTIVITYv DELETE CONTAINER (BTS)v DELETE EVENTv DELETE TIMERv ENDBROWSE ACTIVITYv ENDBROWSE CONTAINER (BTS) on page 162v ENDBROWSE EVENTv ENDBROWSE PROCESSv FORCE TIMERv GET CONTAINER (BTS)v GETNEXT ACTIVITYv GETNEXT CONTAINER (BTS) on page 255v GETNEXT EVENTv GETNEXT PROCESSv INQUIRE ACTIVITYIDv INQUIRE CONTAINERv INQUIRE EVENTv INQUIRE PROCESSv INQUIRE TIMERv LINK ACQPROCESSv LINK ACTIVITYv MOVE CONTAINER(BTS)v PUT CONTAINER (BTS)v REMOVE SUBEVENTv RESET ACQPROCESSv RESET ACTIVITYv RESUMEv RETRIEVE REATTACH EVENTv RETRIEVE SUBEVENTv RUNv STARTBROWSE ACTIVITYv STARTBROWSE CONTAINER (BTS) on page 592

Chapter 2. CICS command summary 19

v STARTBROWSE EVENTv STARTBROWSE PROCESSv SUSPEND (BTS)v TEST EVENT

Channel commandsv DELETE CHANNELv DELETE CONTAINER (CHANNEL)v ENDBROWSE CONTAINER (CHANNEL) on page 162v GET CONTAINER (CHANNEL)v GET64 CONTAINERv GETNEXT CONTAINER (CHANNEL) on page 256v MOVE CONTAINER (CHANNEL)v PUT CONTAINER (CHANNEL)v PUT64 CONTAINERv QUERY CHANNELv STARTBROWSE CONTAINER (CHANNEL) on page 594v START CHANNEL

Console supportv WRITE OPERATOR

Diagnostic servicesv DUMP TRANSACTIONv ENTER TRACENUM

Document servicesv DOCUMENT CREATEv DOCUMENT DELETEv DOCUMENT INSERTv DOCUMENT RETRIEVEv DOCUMENT SET

Environment servicesv ADDRESSv ADDRESS SETv ASSIGN

Event processingv SIGNAL EVENT

Exception supportv HANDLE CONDITIONv IGNORE CONDITIONv POP HANDLEv PUSH HANDLE


File control servicesv DELETEv ENDBRv READv READNEXTv READPREVv RESETBRv REWRITEv STARTBRv UNLOCKv WRITE

Interval control servicesv ASKTIMEv CANCELv DELAYv FORMATTIMEv POSTv RETRIEVEv STARTv WAIT EVENT

Journalingv WAIT JOURNALNAMEv WAIT JOURNALNUMv WRITE JOURNALNAMEv WRITE JOURNALNUM

Monitoringv MONITOR

Named counter serverv DEFINE COUNTER and DEFINE DCOUNTERv DELETE COUNTER and DELETE DCOUNTERv GET COUNTER and GET DCOUNTERv QUERY COUNTER and QUERY DCOUNTERv REWIND COUNTER and REWIND DCOUNTERv UPDATE COUNTER and UPDATE DCOUNTER

Program controlv INVOKE APPLICATION on page 281v LINKv LOADv RELEASEv RETURNv XCTL


Scheduling servicesv START ATTACHv START BREXIT

Security servicesv REQUEST PASSTICKETv QUERY SECURITY

Spool Interface (JES)v SPOOLCLOSEv SPOOLOPEN INPUTv SPOOLOPEN OUTPUTv SPOOLREADv SPOOLWRITE

Storage controlv FREEMAINv FREEMAIN64v GETMAINv GETMAIN64

Syncpointv SYNCPOINTv SYNCPOINT ROLLBACK

Task controlv CHANGE TASKv DEQv ENQv SUSPENDv WAIT EXTERNALv WAITCICS

TCP/IP servicesv EXTRACT CERTIFICATEv EXTRACT TCPIP

Temporary storage controlv DELETEQ TSv READQ TSv WRITEQ TS

Terminal controlv ALLOCATE (LUTYPE6.1)v ALLOCATE (MRO)v BUILD ATTACH (LUTYPE6.1)v BUILD ATTACH (MRO)v CONVERSE (APPC)


v CONVERSE (default) on page 83v CONVERSE (LUTYPE2/LUTYPE3)v CONVERSE (LUTYPE4)v CONVERSE (LUTYPE6.1)v CONVERSE (MRO)v CONVERSE (non-z/OS Communications Server default) on page 97v CONVERSE: non-z/OS Communications Server options on page 98v CONVERSE (SCS)v CONVERSE: z/OS Communications Server options on page 92v CONVERSE (2260)v CONVERSE (3270 logical)v CONVERSE (3600-3601)v CONVERSE (3600-3614)v CONVERSE (3650 interpreter)v CONVERSE (3650-3270)v CONVERSE (3650-3653)v CONVERSE (3650-3680)v CONVERSE (3767)v CONVERSE (3770)v CONVERSE (3790 full-function or inquiry)v CONVERSE (3790 3270-display)v EXTRACT ATTACH (LUTYPE6.1)v EXTRACT ATTACH (MRO)v EXTRACT ATTRIBUTES (MRO)v EXTRACT LOGONMSGv EXTRACT TCTv FREE (LUTYPE6.1)v FREEv FREE (MRO)v HANDLE AIDv ISSUE COPY (3270 logical)v ISSUE DISCONNECT (LUTYPE6.1) on page 299v ISSUE DISCONNECTv ISSUE ENDFILEv ISSUE ENDOUTPUTv ISSUE EODSv ISSUE ERASEAUPv ISSUE LOADv ISSUE PASSv ISSUE PRINTv ISSUE RESETv ISSUE SIGNAL (LUTYPE6.1)v POINTv RECEIVE (APPC)v RECEIVE (LUTYPE2/LUTYPE3)


v RECEIVE (LUTYPE4)v RECEIVE (LUTYPE6.1)v RECEIVE (MRO)v RECEIVE (non-z/OS Communications Server default) on page 426v RECEIVE: non-z/OSCommunications Server options on page 430v RECEIVE (z/OS Communications Server default) on page 416v RECEIVE (z/OS Communications Server default) on page 416v RECEIVE (2260)v RECEIVE (2980)v RECEIVE (3270 logical)v RECEIVE (3600 pipeline) on page 419v RECEIVE (3600-3601)v RECEIVE (3600-3614)v RECEIVE (3650)v RECEIVE (3767)v RECEIVE (3770)v RECEIVE (3790 full-function or inquiry)v RECEIVE (3790 3270-display)v SEND (APPC)v SEND (LUTYPE2/LUTYPE3)v SEND (LUTYPE4)v SEND (LUTYPE6.1)v SEND (MRO)v SEND (non-z/OS Communications Server default) on page 497v SEND: non-z/OS Communications Server options on page 499v SEND (SCS)v SEND (z/OS Communications Server default) on page 484v SEND: z/OS Communications Server options on page 493v SEND (2260)v SEND (2980)v SEND (3270 logical)v SEND (3600 pipeline)v SEND (3600-3601)v SEND (3600-3614)v SEND (3650 interpreter)v SEND (3650-3270)v SEND (3650-3653)v SEND (3650-3680)v SEND (3767)v SEND (3770)v SEND (3790 full-function or inquiry)v SEND (3790 SCS)v SEND (3790 3270-display)v SEND (3790 3270-printer)v WAIT SIGNAL


v WAIT TERMINAL

Transient datav DELETEQ TDv READQ TDv WRITEQ TD

Web supportv CONVERTTIMEv EXTRACT WEBv WEB CLOSEv WEB CONVERSEv WEB ENDBROWSE FORMFIELDv WEB ENDBROWSE HTTPHEADERv WEB ENDBROWSE QUERYPARM on page 657v WEB EXTRACTv WEB OPENv WEB PARSE URLv WEB READ FORMFIELDv WEB READ HTTPHEADERv WEB READ QUERYPARM on page 674v WEB READNEXT FORMFIELDv WEB READNEXT HTTPHEADERv WEB READNEXT QUERYPARM on page 679v WEB RECEIVE (Server)v WEB RECEIVE (Client)v WEB RETRIEVEv WEB SEND (Server)v WEB SEND (Client)v WEB STARTBROWSE FORMFIELDv WEB STARTBROWSE HTTPHEADERv WEB STARTBROWSE QUERYPARM on page 717v WEB WRITE HTTPHEADER

Web servicesv INVOKE SERVICEv INVOKE WEBSERVICEv SOAPFAULT ADDv SOAPFAULT CREATEv SOAPFAULT DELETEv TRANSFORM DATATOJSON on page 602v TRANSFORM DATATOXMLv TRANSFORM JSONTODATA on page 607v TRANSFORM XMLTODATAv WSACONTEXT BUILDv WSACONTEXT DELETEv WSACONTEXT GETv WSAEPR CREATE


|

|

ABENDTerminate a task abnormally.

Description

The ABEND command terminates a task abnormally.

CICS releases the main storage associated with the terminated task; optionally, youcan obtain a transaction dump of this storage.

Invoking the ABEND command causes the current transaction to abend. TheLanguage Environment is informed that an abend has occurred and the followingmessage is written out to CEEMSG followed by a dump report:CEE3250C The system or user abend XXXX was issued

XXXX is the transaction dump code specified on the ABCODE option. The LanguageEnvironment attempts to access register addresses to dump out the referencedstorage as part of the dump report written to CEEMSG. If the LanguageEnvironment does not have access to the storage addressed by these registers, an0C4 abend can occur. You can eliminate 0C4 abends by setting the LanguageEnvironment runtime option TERMTHDACT to QUIET, MSG, or UAONLY. For moreinformation, see TERMTHDACT in z/OS Language Environment ProgrammingReference.

Options

ABCODE(name) Specifies that main storage related to the terminating task is dumped. TheABCODE is used as a transaction dump code to identify the dump. ABCODEfollows the format rules for DUMPCODE. The DUMP TRANSACTION onpage 154 command gives the format rules that apply to DUMPCODE, if theserules are not followed, ABEND does not produce a dump.

Do not start the name with the letter A, because this is reserved for CICS itself.

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

CANCEL Specifies that exits established by HANDLE ABEND commands are ignored.An ABEND CANCEL command cancels all exits at any level in the task andterminates the task abnormally. If the PL/I STAE execution-time option isspecified, an abnormal termination exit is established by PL/I. This exit isrevoked by the CANCEL option.

NODUMP Specifies that an abend occurs without causing a dump to be taken. Forprograms link-edited using the Language Environment SCEELKED library,when NODUMP is specified, a dump is never taken, regardless of any setting

ABEND

ABENDABCODE(name) CANCEL NODUMP

This command is threadsafe.


http://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ceea500/cltherm.htmhttp://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ceea500/cltherm.htm

in the transaction dump table. For programs not link-edited with LanguageEnvironment, if the transaction dump table already has an entry for the abendcode, or if the abend is in Language Environment run-unit initialization ortermination, the NODUMP option is ignored.

Examples

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

ACQUIREAcquire access to a BTS activity from outside the process that contains it.

Description

ACQUIRE enables a program that is executing outside a particular BTS process toaccess an activity within the process. It allows the program to:v Read and write to the activity's data-containersv Issue various commands, such as RUN and LINK, against the activity.1

An activity that a program gains access to by means of an ACQUIRE command isknown as an acquired activity. A program can acquire only one activity per unit ofwork. The activity remains acquired until the next syncpoint.

ACQUIRE ACTIVITYID acquires the specified descendant (non-root) activity.

ACQUIRE PROCESS acquires the root activity of the specified process.

Note: When a program defines a process, it is automatically given access to theprocess's root activity. (This enables the defining program to access the processcontainers and root activity containers before running the process.) When aprogram gains access to a root activity by means of either a DEFINE PROCESS oran ACQUIRE PROCESS command, the process is known as the acquired process.

Rules1. A program can acquire only one activity within the same unit of work. The

activity remains acquired until the next syncpoint. This means, for example,that a program:v Cannot issue both a DEFINE PROCESS and an ACQUIRE PROCESS

command within the same unit of work.

1. If the acquired activity is a root activity, against the process.

ACQUIRE PROCESS

ACQUIRE PROCESS(data-value) PROCESSTYPE(data-value)ACTIVITYID(data-value)

Conditions: ACTIVITYBUSY, ACTIVITYERR, INVREQ, IOERR, LOCKED, NOTAUTH, PROCESSBUSY,PROCESSERR


v Cannot issue both an ACQUIRE PROCESS and an ACQUIRE ACTIVITYIDcommand within the same unit of work. That is, it can acquire either adescendant activity or a root activity, not one of each.

2. If a program is executing as an activation of an activity, it cannot:v Acquire an activity in the same process as itself. It cannot, for example, issue

ACQUIRE PROCESS for the current process.v Use a LINK command to activate the activity that it has acquired.

3. An acquired activity's process is accessible in the same way as the activity itselfcan access it. Thus, if the acquired activity is a descendant activity:v Its process's containers may be read but not updated.v The process may not be the subject of any commandsuch as RUN, LINK,

SUSPEND, RESUME, or RESETthat directly manipulates the process or itsroot activity.

Conversely, if the acquired activity is a root activity:v Its process's containers may be both read and updated.v The process may be the subject of commands such as RUN, LINK,

SUSPEND, RESUME, or RESET. The ACQPROCESS keyword on thecommand identifies the subject process as the one the program that issuesthe command has acquired in the current unit of work.

Options

ACTIVITYID(data-value)specifies the identifier (152 characters) of the descendant activity to beacquired.

PROCESS(data-value)specifies the name (136 characters) of the process whose root activity is to beacquired.

PROCESSTYPE(data-value)specifies the process-type (18 characters) of the process whose root activity isto be acquired.

Conditions

107 ACTIVITYBUSYRESP2 values:

19 The request timed out. It may be that another task using thisactivity-record has been prevented from ending.

109 ACTIVITYERRRESP2 values:

8 The activity referred to by the ACTIVITYID option could not be found.

16 INVREQRESP2 values:

22 The unit of work that issued the ACQUIRE command has alreadyacquired an activity; a unit of work can acquire only one activity.

17 IOERRRESP2 values:

29 The repository file is unavailable.

30 An input/output error has occurred on the repository file.


100 LOCKEDThe request cannot be performed because a retained lock exists against therelevant record on the repository file.

70 NOTAUTHRESP2 values:

101 The user associated with the issuing task is not authorized to accessthe file associated with the BTS repository data set on which details ofthe process are stored.

106 PROCESSBUSYRESP2 values:

13 The request timed out. It may be that another task using thisprocess-record has been prevented from ending.

108 PROCESSERRRESP2 values:

5 The process named in the PROCESS option could not be found.

9 The process-type named in the PROCESSTYPE option could not befound.

Usage examples

ACQUIRE ACTIVITYID can be used to implement user-related activities. Forexample, on its first activation an activity might:1. Define an input event to represent a particular user-interaction2. Issue an ASSIGN command to obtain the identifier of its own activity-instance3. Save the input event and activity identifier on a data base4. Return without completing.

Later, when a user is ready to process the work represented by the activity, he orshe starts a transaction. This transaction, which executes outside the BTS process:1. Retrieves the input event and activity identifier from the data base2. Uses the ACQUIRE ACTIVITYID command to acquire access to the activity3. Places the information required to complete the activity in an input

data-container, and runs the activity. The INPUTEVENT option of the RUNcommand tells the activity why it is being activated.

ACQUIRE PROCESS can be used to implement client/server processing. Forexample, a client program might use the DEFINE PROCESS and RUN commandsto create and run a server process, which carries out some work, defines one ormore input events, and returns without completing. The client issues a syncpointor returns. To run the same server process again, the client uses the ACQUIREPROCESS and RUN commands.


ADD SUBEVENTAdd a sub-event to a BTS composite event.

Description

ADD SUBEVENT adds a sub-event to a BTS composite event. The sub-event:v Must be an atomic (not a composite) eventv Cannot be a system eventv Must not currently be part of a composite eventv Cannot, if the predicate of the composite event uses the AND Boolean operator,

be an input event.

Adding a sub-event causes the composite's predicate to be re-evaluated.

Options

EVENT(data-value)specifies the name (116 characters) of the composite event. This mustpreviously have been defined to the current activity, using the DEFINECOMPOSITE EVENT command.

SUBEVENT(data-value)specifies the name (116 characters) of the atomic event to be added to thecomposite event as a sub-event. The sub-event must previously have beendefined to the current activity, using one of the following commands:v DEFINE ACTIVITYv DEFINE INPUT EVENTv DEFINE TIMER

It:v Must not currently be part of a composite eventv Cannot, if the predicate of the composite event uses the AND Boolean

operator, be an input event.

Conditions

111 EVENTERRRESP2 values:

4 The event specified on the EVENT option is not recognized by BTS.

5 The sub-event specified on the SUBEVENT option is not recognized by. BTS.

16 INVREQRESP2 values:

1 The command was issued outside the scope of an activity.

ADD SUBEVENT

ADD SUBEVENT(data-value) EVENT(data-value)

Conditions: EVENTERR, INVREQ


2 The event specified on the EVENT option is invalidit is not acomposite event.

3 The sub-event specified on the SUBEVENT option is invalid.Specifying any of the following as a sub-event produces this error:v A composite eventv A system eventv A sub-event of another composite eventv A sub-event of this composite eventthat is, an atomic event that

has already been added to this composite eventv An input event, if the composite uses the AND Boolean operator.

ADDRESSObtain access to CICS storage areas.

Note for dynamic transaction routing: Using ADDRESS with CWA could createinter-transaction affinities that adversely affect the use of dynamic transactionrouting. See Affinity for more information about transaction affinities.

Description

ADDRESS accesses the following areas:v The access control environment element (ACEE)v The communication area available to the invoked program (COMMAREA)v The common work area (CWA)v The EXEC interface block (EIB)v The terminal control table user area (TCTUA)v The transaction work area (TWA)

In assembler language, no more than four options may be specified in oneADDRESS command.

Options

ACEE(ptr-ref) returns a pointer to the access control environment element, the control blockthat is generated by an external security manager (ESM) when the user signson. If the user is not signed on, the address of the CICS DFLTUSER's ACEE isreturned. If an ACEE does not exist, CICS sets the pointer reference to the nullvalue, X'FF000000'.

ADDRESS

ADDRESSACEE(ptr-ref) COMMAREA(ptr-ref) CWA(ptr-ref) EIB(ptr-ref)

TCTUA(ptr-ref) TWA(ptr-ref)

This command is threadsafe.


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/applications/designing/dfhp3ak.html

For information on how to map the ACEE data area, see the mapping macroIHAACEE supplied in SYS1.MACLIB.

Note: Take care when addressing an ACEE in a server program invoked by adistributed program link. The ACEE address returned depends on the linksecurity and may not be the same as the address of the user signed on at thelocal system.

COMMAREA(ptr-ref) returns a pointer reference, set to the address of the communication area(COMMAREA) available to the currently executing program. COMMAREA isused to pass information between application programs. If the COMMAREAdoes not exist, the pointer reference is set to the null value, X'FF000000'.

In C, you must use ADDRESS COMMAREA to get the address of thecommunication area, because this is not passed as an argument to a C mainfunction.

CWA(ptr-ref) returns a pointer reference, set to the address of the common work area(CWA). This area makes information available to applications running in asingle CICS system. If a CWA does not exist, CICS sets the pointer reference tothe null value, X'FF000000'.

EIB(ptr-ref) returns a pointer reference set to the address of the EXEC interface block (EIB).You must use this option to get addressability to the EIB in applicationroutines other than the first invoked by CICS (where addressability to the EIBis provided automatically). If the application program is translated withSYSEIB in the XOPTS parameter list, this option returns the address of thesystem EIB.

If TASKDATALOC(ANY) is defined on the transaction definition, the addressof the data may be above or below the 16MB line.

If TASKDATALOC(BELOW) is defined on the transaction definition, and thedata resides above the 16MB line, the data is copied below the 16MB line, andthe address of this copy is returned.

C functions must use ADDRESS EIB to get the address of the EXEC interfaceblock, because this address is not passed as an argument to a C main function.You must code an ADDRESS EIB statement at the beginning of eachapplication if you want access to the EIB, or if you are using a command thatincludes the RESP or RESP2 option.

TCTUA(ptr-ref) returns a pointer reference, set to the address of the terminal control table userarea (TCTUA) for the principal facility, not that for any alternate facility thatmay have been allocated. This area is used for passing information betweenapplication programs, but only if the same terminal is associated with theapplication programs involved. If a TCTUA does not exist, the pointerreference is set to the null value, X'FF000000'.

TWA(ptr-ref) returns a pointer reference, set to the address of the transaction work area(TWA). This area is used for passing information between applicationprograms, but only if they are in the same task. If a TWA does not exist, thepointer reference is set to the null value, X'FF000000'.

If TASKDATALOC(ANY) is defined on the transaction definition, the addressof the data may be above or below the 16MB line.


If TASKDATALOC(BELOW) is defined on the transaction definition, and thedata resides above the 16MB line, the data is copied below the 16MB line, andthe address of this copy is returned.

ADDRESS SETSet the address of a structure or pointer.

Description

The value from the USING option is used to set the reference in the SET option.

Options

SET(data-area/ptr-ref) sets a pointer reference.

USING(ptr-ref/data-area) supplies a pointer value.

COBOL example of ADDRESS SET

To set the address of a structure to a known pointer value:

To set a pointer variable to the address of a structure:

ALLOCATE (APPC)Allocate a session to a remote APPC logical unit for use by an APPC mappedconversation.

ADDRESS SET

ADDRESS SET(data-area) USING(ptr-ref)SET(ptr-ref) USING(data-area)

EXEC CICS ADDRESS SET(address of struc)USING(ptr)

EXEC CICS ADDRESS SET(ptr)USING(address of struc01)

ALLOCATE (APPC)

ALLOCATE SYSID(systemname)PROFILE(name)

PARTNER(name)NOQUEUE STATE(cvda)

Conditions: CBIDERR, INVREQ, NETNAMEIDERR, PARTNERIDERR, SYSBUSY, SYSIDERR


Description

ALLOCATE makes one of the sessions associated with the named system availableto the application program, and optionally selects a set of session-processingoptions.

CICS returns, in EIBRSRCE in the EIB, the 4-byte CONVID (conversation identifier)that the application program uses in all subsequent commands that relate to theconversation.

If a session to the requested APPC LU is not available, the application issuspended until a session does become available. In such a case, the suspension ofthe application can be prevented by specifying either the NOQUEUE or theNOSUSPEND option. NOSUSPEND is still supported as an equivalent forNOQUEUE, but NOQUEUE is the preferred keyword.

A session is immediately available for allocation only if it is all of the following:v A contention winnerv Already boundv Not already allocated

CICS attempts to satisfy a request for a session by choosing among sessions in thefollowing order of preference:1. Contention winner that is bound and not already allocated (CICS allocates it).

This is a session that is immediately available.2. Contention winner that is unbound (CICS binds it and allocates it).3. Contention loser that is bound and not already allocated (CICS bids for it).4. Contention loser that is unbound (CICS binds it and bids for it).

The action taken by CICS if no session is immediately available depends onwhether you specify NOQUEUE (or the equivalent NOSUSPEND option), and alsoon whether your application has executed a HANDLE command for the SYSBUSYcondition. In these situations, CICS does not bid for sessions or bind additionalsessions. It looks for a session that is immediately available (that is, a contentionwinner that is bound and not already allocated), and if one is not available, theSYSBUSY condition is returned. The possible combinations are shown below:

HANDLE for SYSBUSY condition issued The command is not queued and control is returned immediately to the labelspecified in the HANDLE command, whether or not you have specifiedNOQUEUE.

No HANDLE issued for SYSBUSY condition If you have specified NOQUEUE (or NOSUSPEND), the request is not queuedand control is returned immediately to your application program. TheSYSBUSY code (X'D3') is set in the EIBRCODE field of the EXEC interfaceblock. You should test this field immediately after issuing the ALLOCATEcommand.

The HANDLE for SYSBUSY condition therefore has the same effect as theNOQUEUE option, except for where control is returned in the application. If theHANDLE command is used, control is returned to the label, and if it is not used,control is returned to the instruction following the ALLOCATE command.


If you have omitted the NOQUEUE option, and you have not issued a HANDLEcommand for the SYSBUSY option, then if no session is immediately available,CICS queues the request (and your application waits) until a session is available.The request is allocated a session either when a winner session has becomeavailable, or when CICS has successfully bid for a loser session. Omit theNOQUEUE option when you want all winner or loser sessions to be considered forallocation to the request. You can use the QUEUELIMIT and MAXQTIMEattributes of the CONNECTION resource definitions to limit the length of thequeue of requests, and the time that requests spend on the queue. Managingallocate queues has more information about allocate queues. The DTIMOUT valuespecified on the transaction definition can be used to limit the wait time forindividual requests.

Options

NOQUEUE overrides the default action when a SYSBUSY condition arises. This indicatesthat a session is not immediately available. The default action is to suspendapplication execution until a session is available. NOQUEUE inhibits thiswaiting; control returns immediately to the application program instructionfollowing the command.

Note, however, that if a HANDLE CONDITION for SYSBUSY is active whenthe command is executed, this also overrides the default action, and control ispassed to the user label supplied in the HANDLE CONDITION. This takesprecedence over the NOQUEUE option but is, of course, negated by eitherNOHANDLE or RESP.

If an APPC ALLOCATE request is issued against a single session connectionfrom the contention loser end, the NOQUEUE option always causes SYSBUSYto be returned rather than allowing the request to bid for the session. If theNOQUEUE option is absent, the request is able to bid for the session.

If an APPC ALLOCATE request is issued against a parallel session connection,and the NOQUEUE option is specified, only sessions that are immediatelyavailable (that is, a contention winner that is bound and not already allocated)can be allocated to the request. If no such session is available, then SYSBUSY isreturned. If the NOQUEUE option is absent, the request is able to bid for aloser session, or bind unbound winner sessions.

PARTNER(name) specifies the name (8 characters) of a set of definitions that include the namesof a remote LU (NETNAME) and a communication profile to be used on theallocated session. You can use this option as an alternative to specifying SYSIDand PROFILE explicitly.

PROFILE(name) specifies the name (1-8 characters) of a set of session-processing options thatare to be used during the execution of mapped commands for the sessionspecified in the SYSID option. If you specify SYSID and omit PROFILE, adefault profile (DFHCICSA) is selected.

STATE(cvda) gets the state of the current conversation. The cvda value returned by CICS isALLOCATED.

SYSID(systemname) specifies the name (1-4 characters) by which the remote APPC LU is known tothis CICS. This option requests that one of the sessions to the named system isto be allocated.


http://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/tuning/connections/dfht139.htmlhttp://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/tuning/connections/dfht139.html

Conditions

62 CBIDERR occurs if the requested PROFILE cannot be found.

Default action: terminate the task abnormally.

16 INVREQ occurs if the ALLOCATE command is not valid for the device to which it isdirected.


99 NETNAMEIDERR occurs if the name specified in the NETNAME parameter of the RDOdefinition for the PARTNER specified on the allocate command is invalid.


97 PARTNERIDERR occurs if the name specified in the PARTNER option is not recognized byCICS.


59 SYSBUSY occurs for one of the following reasons:v The request for a session cannot be serviced immediately. This is only

possible if the NOQUEUE option is set, or a HANDLE CONDITION forSYSBUSY is active.

v The ALLOCATE command is issued when persistent session recovery is stillin process and the sessions needed to satisfy the command are not yetrecovered.

Default action: ignore the condition.

53 SYSIDERR occurs if CICS is unable to provide the application program with a suitablesession, for one of the following reasons:v The name specified in the SYSID option is not recognized by CICS.v The mode name derived from the PROFILE option is not one of the mode

names defined for the APPC system entry.v All the sessions in the group specified by SYSID and mode name are out of

service, or all sessions are out of service.v The AID (automatic initiate descriptor) representing your ALLOCATE has

been canceled.v All the sessions are busy and the (queued) allocates have been purged or

rejected.



ALLOCATE (LUTYPE6.1)Acquire a session to a remote LUTYPE6.1 logical unit.

Description

ALLOCATE acquires an alternate facility and optionally selects a set ofsession-processing options. If SYSID is specified, CICS makes available to theapplication program one of the sessions associated with the named system. Thename of this session can be obtained from EIBRSRCE in the EIB. If SESSION isspecified, CICS makes the named session available.

If the session requested is not available, the application is suspended until thesession does become available. In such a case, the suspension of the applicationcan be prevented by specifying either the NOQUEUE or the NOSUSPEND option.NOSUSPEND is still supported as an equivalent for NOQUEUE, but NOQUEUE isthe preferred keyword.

Options

NOQUEUE overrides the default action when a SESSBUSY or SYSBUSY condition arises.These conditions indicate that the session requested is not immediatelyavailable. The default action is to suspend application execution until thesession is available. NOQUEUE inhibits this waiting; control returnsimmediately to the application program instruction following the command.

Note, however, that if a HANDLE CONDITION for SESSBUSY or SYSBUSY isactive when the command is executed, this also overrides the default action,and control is passed to the user label supplied in the HANDLE CONDITION.This takes precedence over the NOQUEUE option but is, of course, negated byeither NOHANDLE or RESP.

PROFILE(name) specifies the name (18 characters) of a set of session-processing options thatare to be used during execution of terminal control commands for the sessionspecified in the SYSID or SESSION options. If the PROFILE option is omitted,a default profile (DFHCICSA) is selected.

SESSION(name) specifies the symbolic identifier (14 characters) of a session TCTTE. Thisoption specifies the alternate facility to be used.

SYSID(systemname) specifies the name (14 characters) of a system TCTSE. This option specifiesthat one of the sessions to the named system is to be allocated.

ALLOCATE (LUTYPE6.1)

ALLOCATE SESSION(name)SYSID(systemname) PROFILE(name) NOQUEUE

Conditions: CBIDERR, EOC, INVREQ, SESSBUSY, SESSIONERR, SYSBUSY, SYSIDERR


Conditions

62 CBIDERR occurs if the requested PROFILE cannot be found.


06 EOC occurs when a request/response unit (RU) is received with the end-of-chainindicator set. Field EIBEOC also contains this indicator.


16 INVREQ occurs when the specified session is already allocated to this task, or thesession is an APPC session.


60 SESSBUSY occurs if the request for the specified session cannot be serviced immediately.This is only possible if the NOQUEUE option is set, or a HANDLECONDITION for SESSBUSY is active.


58 SESSIONERR occurs if the name specified in the SESSION option is not that of anLUTYPE6.1 session TCTTE, or if the session cannot be allocated because it isout of service.


59 SYSBUSY occurs for one of the following reasons:v The request for a session cannot be serviced immediately. This is only

possible if the NOQUEUE option is set, or a HANDLE CONDITION forSYSBUSY is active.

v The ALLOCATE command is issued when persistent session recovery is stillin process and the sessions needed to satisfy the command are not yetrecovered.


53 SYSIDERR occurs if CICS is unable to provide the application program with a suitablesession, for one of the following reasons:v The name specified in the SYSID option is not recognized by CICS.v All sessions are out of service.v The AID (automatic initiate descriptor) representing your ALLOCATE has

been canceled.v All the sessions are busy and the (queued) allocates have been purged or

rejected.


ALLOCATE (MRO)Acquire an MRO session.


Description

ALLOCATE acquires an alternate facility. CICS makes available to the applicationprogram one of the sessions associated with the system named in the SYSIDoption. The name of this session can be obtained from EIBRSRCE in the EIB.

If the session requested is not available, the application is suspended until thesession does become available. In such a case, the suspension of the applicationcan be prevented by specifying the NOQUEUE option.

Options

NOQUEUE overrides the default action when a SYSBUSY condition arises. This conditionindicates that the session requested is not immediately available. The defaultaction is to suspend application execution until the session is available.NOQUEUE inhibits this waiting; control returns immediately to the applicationprogram instruction following the command.

Note, however, that if a HANDLE CONDITION for SYSBU

Documents

C I C S T r a n s a cti o n S e rv e r f o r z/O S IBM€¦ · CONVERSE (MRO) ..... . 97 CONVERSE (2260) ..... . 98 CONVERSE: non-z/OS Communications Server options ... TEST EVENT