version 5 release 5 cics transaction server for z/os · 2020. 8. 13. · • release

CICS Transaction Server for z/OSVersion 5 Release 5

API Reference

IBM

Note

Before using this information and the product it supports, read the information in “Notices” on page821.

This edition applies to the IBM® CICS® Transaction Server for z/OS® Version 5 Release 5 (product number 5655-Y04) andto all subsequent releases and modifications until otherwise indicated in new editions.© Copyright International Business Machines Corporation 1974, 2020.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

About this PDF......................................................................................................xi

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

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

Chapter 2. CICS command summary.................................................................... 15ABEND........................................................................................................................................................25ACQUIRE.................................................................................................................................................... 26ADD SUBEVENT......................................................................................................................................... 29ADDRESS....................................................................................................................................................30ADDRESS SET.............................................................................................................................................31ALLOCATE (APPC)...................................................................................................................................... 32ALLOCATE (LUTYPE6.1)............................................................................................................................. 35ALLOCATE (MRO)....................................................................................................................................... 36ASKTIME.................................................................................................................................................... 38ASSIGN.......................................................................................................................................................39

Codes returned by ASSIGN.................................................................................................................. 53BIF DEEDIT................................................................................................................................................ 55BIF DIGEST................................................................................................................................................ 57BUILD ATTACH (LUTYPE6.1)..................................................................................................................... 58BUILD ATTACH (MRO)................................................................................................................................60CANCEL...................................................................................................................................................... 62CANCEL (BTS)............................................................................................................................................ 64CHANGE PHRASE.......................................................................................................................................66CHANGE PASSWORD................................................................................................................................. 68CHANGE TASK............................................................................................................................................69CHECK ACQPROCESS................................................................................................................................ 70CHECK ACTIVITY....................................................................................................................................... 72CHECK TIMER............................................................................................................................................ 74CONNECT PROCESS...................................................................................................................................75CONVERSE (default).................................................................................................................................. 78CONVERSE (APPC)..................................................................................................................................... 78CONVERSE (LUTYPE2/LUTYPE3).............................................................................................................. 79CONVERSE (LUTYPE4)............................................................................................................................... 79CONVERSE (LUTYPE6.1)............................................................................................................................80CONVERSE (SCS)....................................................................................................................................... 80CONVERSE (3270 logical)..........................................................................................................................81CONVERSE (3600-3601)........................................................................................................................... 81CONVERSE (3600-3614)........................................................................................................................... 82CONVERSE (3650 interpreter)...................................................................................................................83

iii

CONVERSE (3650-3270)........................................................................................................................... 83CONVERSE (3650-3653)........................................................................................................................... 84CONVERSE (3650-3680)........................................................................................................................... 85CONVERSE (3767)..................................................................................................................................... 85CONVERSE (3770)..................................................................................................................................... 85CONVERSE (3790 full-function or inquiry)................................................................................................86CONVERSE (3790 3270-display).............................................................................................................. 86CONVERSE: z/OS Communications Server options.................................................................................. 87CONVERSE (non-z/OS Communications Server default)..........................................................................91CONVERSE (MRO)...................................................................................................................................... 92CONVERSE (2260)..................................................................................................................................... 92CONVERSE: non-z/OS Communications Server options...........................................................................93CONVERTTIME...........................................................................................................................................96DEFINE ACTIVITY...................................................................................................................................... 98DEFINE COMPOSITE EVENT................................................................................................................... 100DEFINE COUNTER and DEFINE DCOUNTER...........................................................................................102DEFINE INPUT EVENT............................................................................................................................. 105DEFINE PROCESS.................................................................................................................................... 105DEFINE TIMER.........................................................................................................................................108DELAY.......................................................................................................................................................111DELETE.....................................................................................................................................................114DELETE ACTIVITY....................................................................................................................................120DELETE CHANNEL................................................................................................................................... 121DELETE CONTAINER (BTS)......................................................................................................................122DELETE CONTAINER (CHANNEL)............................................................................................................ 124DELETE COUNTER and DELETE DCOUNTER...........................................................................................125DELETE EVENT.........................................................................................................................................127DELETE TIMER.........................................................................................................................................128DELETEQ TD.............................................................................................................................................129DELETEQ TS............................................................................................................................................. 130DEQ.......................................................................................................................................................... 132DOCUMENT CREATE................................................................................................................................ 133DOCUMENT DELETE................................................................................................................................ 136DOCUMENT INSERT................................................................................................................................ 137DOCUMENT RETRIEVE............................................................................................................................ 140DOCUMENT SET.......................................................................................................................................142DUMP TRANSACTION..............................................................................................................................144ENDBR......................................................................................................................................................148ENDBROWSE ACTIVITY...........................................................................................................................150ENDBROWSE CONTAINER (BTS).............................................................................................................151ENDBROWSE CONTAINER (CHANNEL)...................................................................................................151ENDBROWSE EVENT............................................................................................................................... 152ENDBROWSE PROCESS...........................................................................................................................152ENDBROWSE TIMER................................................................................................................................153ENQ.......................................................................................................................................................... 154ENTER TRACENUM.................................................................................................................................. 156EXTRACT ATTACH (LUTYPE6.1).............................................................................................................. 158EXTRACT ATTACH (MRO).........................................................................................................................161EXTRACT ATTRIBUTES (APPC)............................................................................................................... 163EXTRACT ATTRIBUTES (MRO)................................................................................................................ 164EXTRACT CERTIFICATE...........................................................................................................................165EXTRACT LOGONMSG............................................................................................................................. 168EXTRACT PROCESS................................................................................................................................. 169EXTRACT TCPIP....................................................................................................................................... 171EXTRACT TCT...........................................................................................................................................174EXTRACT WEB......................................................................................................................................... 175FETCH ANY...............................................................................................................................................180FETCH CHILD........................................................................................................................................... 181

iv

FORCE TIMER.......................................................................................................................................... 183FORMATTIME...........................................................................................................................................184FREE......................................................................................................................................................... 188FREE (APPC).............................................................................................................................................188FREE (LUTYPE6.1)................................................................................................................................... 190FREE (MRO)..............................................................................................................................................190FREE CHILD............................................................................................................................................. 192FREEMAIN................................................................................................................................................192FREEMAIN64........................................................................................................................................... 195GDS ALLOCATE........................................................................................................................................ 196GDS ASSIGN............................................................................................................................................ 198GDS CONNECT PROCESS........................................................................................................................ 199GDS EXTRACT ATTRIBUTES....................................................................................................................201GDS EXTRACT PROCESS......................................................................................................................... 202GDS FREE.................................................................................................................................................204GDS ISSUE ABEND.................................................................................................................................. 205GDS ISSUE CONFIRMATION................................................................................................................... 206GDS ISSUE ERROR...................................................................................................................................207GDS ISSUE PREPARE...............................................................................................................................209GDS ISSUE SIGNAL................................................................................................................................. 210GDS RECEIVE...........................................................................................................................................211GDS SEND................................................................................................................................................ 213GDS WAIT................................................................................................................................................ 215GET CONTAINER (BTS)............................................................................................................................216GET CONTAINER (CHANNEL).................................................................................................................. 219GET COUNTER and GET DCOUNTER.......................................................................................................223GETMAIN................................................................................................................................................. 227GETMAIN64............................................................................................................................................. 231GETNEXT ACTIVITY.................................................................................................................................234GETNEXT CONTAINER (BTS)...................................................................................................................235GETNEXT CONTAINER (CHANNEL).........................................................................................................236GETNEXT EVENT......................................................................................................................................237GETNEXT PROCESS................................................................................................................................. 238GETNEXT TIMER......................................................................................................................................239GET64 CONTAINER................................................................................................................................. 241HANDLE ABEND.......................................................................................................................................245HANDLE AID............................................................................................................................................ 247HANDLE CONDITION...............................................................................................................................248IGNORE CONDITION............................................................................................................................... 250INQUIRE ACTIVITYID..............................................................................................................................250INQUIRE CONTAINER............................................................................................................................. 253INQUIRE EVENT...................................................................................................................................... 255INQUIRE PROCESS..................................................................................................................................256INQUIRE TIMER.......................................................................................................................................257INVOKE APPLICATION............................................................................................................................ 259INVOKE SERVICE.....................................................................................................................................262INVOKE WEBSERVICE.............................................................................................................................267ISSUE ABEND.......................................................................................................................................... 267ISSUE ABORT...........................................................................................................................................268ISSUE ADD............................................................................................................................................... 270ISSUE CONFIRMATION........................................................................................................................... 272ISSUE COPY (3270 logical)..................................................................................................................... 273ISSUE DISCONNECT (default).................................................................................................................274ISSUE DISCONNECT (LUTYPE6.1).......................................................................................................... 275ISSUE END............................................................................................................................................... 276ISSUE ENDFILE........................................................................................................................................278ISSUE ENDOUTPUT................................................................................................................................. 278ISSUE EODS............................................................................................................................................. 279

v

ISSUE ERASE........................................................................................................................................... 280ISSUE ERASEAUP.................................................................................................................................... 281ISSUE ERROR...........................................................................................................................................282ISSUE LOAD............................................................................................................................................. 284ISSUE NOTE............................................................................................................................................. 285ISSUE PASS..............................................................................................................................................286ISSUE PREPARE.......................................................................................................................................287ISSUE PRINT............................................................................................................................................289ISSUE QUERY...........................................................................................................................................290ISSUE RECEIVE........................................................................................................................................291ISSUE REPLACE....................................................................................................................................... 292ISSUE RESET............................................................................................................................................294ISSUE SEND............................................................................................................................................. 295ISSUE SIGNAL (APPC)............................................................................................................................. 297ISSUE SIGNAL (LUTYPE6.1)....................................................................................................................298ISSUE WAIT............................................................................................................................................. 299JOURNAL..................................................................................................................................................300LINK......................................................................................................................................................... 301LINK ACQPROCESS..................................................................................................................................308LINK ACTIVITY........................................................................................................................................ 311LOAD.........................................................................................................................................................314MONITOR................................................................................................................................................. 317MOVE CONTAINER (BTS).........................................................................................................................319MOVE CONTAINER (CHANNEL)...............................................................................................................321POINT.......................................................................................................................................................323POP HANDLE............................................................................................................................................324POST.........................................................................................................................................................325PURGE MESSAGE.....................................................................................................................................328PUSH HANDLE......................................................................................................................................... 328PUT CONTAINER (BTS)............................................................................................................................329PUT CONTAINER (CHANNEL).................................................................................................................. 331PUT64 CONTAINER................................................................................................................................. 335QUERY CHANNEL.....................................................................................................................................338QUERY COUNTER and QUERY DCOUNTER............................................................................................. 339QUERY SECURITY.................................................................................................................................... 342READ........................................................................................................................................................ 346READNEXT............................................................................................................................................... 357READPREV............................................................................................................................................... 367READQ TD................................................................................................................................................ 375READQ TS.................................................................................................................................................379RECEIVE (z/OS Communications Server default)................................................................................... 382RECEIVE (APPC)...................................................................................................................................... 382RECEIVE (LUTYPE2/LUTYPE3)................................................................................................................383RECEIVE (LUTYPE4)................................................................................................................................ 383RECEIVE (LUTYPE6.1)............................................................................................................................. 384RECEIVE (3270 logical)........................................................................................................................... 384RECEIVE (3600 pipeline).........................................................................................................................385RECEIVE (3600-3601)............................................................................................................................ 385RECEIVE (3600-3614)............................................................................................................................ 385RECEIVE (3650).......................................................................................................................................386RECEIVE (3767).......................................................................................................................................387RECEIVE (3770).......................................................................................................................................387RECEIVE (3790 full-function or inquiry)................................................................................................. 388RECEIVE: z/OS Communications Server options....................................................................................388RECEIVE (non-z/OS Communications Server default)........................................................................... 391RECEIVE (MRO)........................................................................................................................................392RECEIVE (2260).......................................................................................................................................392RECEIVE (2980).......................................................................................................................................392

vi

RECEIVE (3790 3270-display)................................................................................................................395RECEIVE: non-z/OSCommunications Server options.............................................................................395RECEIVE MAP.......................................................................................................................................... 398RECEIVE MAP MAPPINGDEV.................................................................................................................. 401RECEIVE PARTN.......................................................................................................................................403RELEASE...................................................................................................................................................405REMOVE SUBEVENT................................................................................................................................ 406REQUEST ENCRYPTPTKT........................................................................................................................ 408REQUEST PASSTICKET............................................................................................................................410RESET ACQPROCESS............................................................................................................................... 411RESET ACTIVITY......................................................................................................................................413RESETBR.................................................................................................................................................. 414RESUME................................................................................................................................................... 418RETRIEVE.................................................................................................................................................420RETRIEVE REATTACH EVENT.................................................................................................................. 422RETRIEVE SUBEVENT..............................................................................................................................424RETURN....................................................................................................................................................425REWIND COUNTER and REWIND DCOUNTER........................................................................................428REWRITE..................................................................................................................................................431ROUTE...................................................................................................................................................... 435RUN.......................................................................................................................................................... 439RUN TRANSID..........................................................................................................................................443SEND (z/OS Communications Server default)........................................................................................ 445SEND (APPC)............................................................................................................................................445SEND (LUTYPE2/LUTYPE3)..................................................................................................................... 446SEND (LUTYPE4)......................................................................................................................................446SEND (LUTYPE6.1)...................................................................................................................................446SEND (SCS).............................................................................................................................................. 447SEND (3270 logical).................................................................................................................................447SEND (3600 pipeline).............................................................................................................................. 448SEND (3600-3601)..................................................................................................................................448SEND (3600-3614)..................................................................................................................................449SEND (3650 interpreter)......................................................................................................................... 450SEND (3650-3270)..................................................................................................................................450SEND (3650-3653)..................................................................................................................................451SEND (3650-3680)..................................................................................................................................451SEND (3767)............................................................................................................................................ 451SEND (3770)............................................................................................................................................ 452SEND (3790 full-function or inquiry)...................................................................................................... 452SEND (3790 SCS).....................................................................................................................................453SEND (3790 3270-display)..................................................................................................................... 453SEND (3790 3270-printer)......................................................................................................................454SEND: z/OS Communications Server options......................................................................................... 454SEND (non-z/OS Communications Server default).................................................................................458SEND (MRO)............................................................................................................................................. 458SEND (2260)............................................................................................................................................ 458SEND (2980)............................................................................................................................................ 459SEND: non-z/OS Communications Server options................................................................................. 459SEND CONTROL....................................................................................................................................... 462SEND MAP................................................................................................................................................466SEND MAP MAPPINGDEV........................................................................................................................472SEND PAGE.............................................................................................................................................. 475SEND PARTNSET......................................................................................................................................478SEND TEXT...............................................................................................................................................479SEND TEXT MAPPED................................................................................................................................484SEND TEXT NOEDIT.................................................................................................................................486SIGNAL EVENT.........................................................................................................................................489SIGNOFF.................................................................................................................................................. 490

vii

SIGNON....................................................................................................................................................491SIGNON TOKEN....................................................................................................................................... 495SOAPFAULT ADD......................................................................................................................................500SOAPFAULT CREATE................................................................................................................................ 502SOAPFAULT DELETE................................................................................................................................ 505SPOOLCLOSE........................................................................................................................................... 506SPOOLOPEN INPUT................................................................................................................................. 508SPOOLOPEN OUTPUT..............................................................................................................................511SPOOLREAD.............................................................................................................................................515SPOOLWRITE........................................................................................................................................... 518START....................................................................................................................................................... 520START ATTACH.........................................................................................................................................529START BREXIT......................................................................................................................................... 531START CHANNEL......................................................................................................................................533STARTBR.................................................................................................................................................. 538STARTBROWSE ACTIVITY....................................................................................................................... 543STARTBROWSE CONTAINER (BTS)......................................................................................................... 545STARTBROWSE CONTAINER (CHANNEL)............................................................................................... 546STARTBROWSE EVENT............................................................................................................................ 547STARTBROWSE PROCESS....................................................................................................................... 548STARTBROWSE TIMER............................................................................................................................ 549SUSPEND................................................................................................................................................. 550SUSPEND (BTS)....................................................................................................................................... 550SYNCPOINT............................................................................................................................................. 552SYNCPOINT ROLLBACK...........................................................................................................................553TEST EVENT............................................................................................................................................. 554TRANSFORM DATATOJSON..................................................................................................................... 555TRANSFORM DATATOXML....................................................................................................................... 556TRANSFORM JSONTODATA.....................................................................................................................559TRANSFORM XMLTODATA....................................................................................................................... 561UNLOCK....................................................................................................................................................564UPDATE COUNTER and UPDATE DCOUNTER......................................................................................... 567VERIFY PASSWORD................................................................................................................................. 570VERIFY PHRASE.......................................................................................................................................573VERIFY TOKEN.........................................................................................................................................576WAIT CONVID (APPC)..............................................................................................................................579WAIT EVENT............................................................................................................................................ 580WAIT EXTERNAL......................................................................................................................................581WAIT JOURNALNAME............................................................................................................................. 584WAIT JOURNALNUM............................................................................................................................... 586WAIT SIGNAL...........................................................................................................................................586WAIT TERMINAL......................................................................................................................................587WAITCICS................................................................................................................................................ 588WEB CLOSE.............................................................................................................................................. 591WEB CONVERSE...................................................................................................................................... 593WEB ENDBROWSE FORMFIELD.............................................................................................................. 605WEB ENDBROWSE HTTPHEADER...........................................................................................................606WEB ENDBROWSE QUERYPARM.............................................................................................................607WEB EXTRACT......................................................................................................................................... 608WEB OPEN............................................................................................................................................... 613WEB PARSE URL...................................................................................................................................... 618WEB READ FORMFIELD...........................................................................................................................620WEB READ HTTPHEADER........................................................................................................................622WEB READ QUERYPARM......................................................................................................................... 624WEB READNEXT FORMFIELD..................................................................................................................626WEB READNEXT HTTPHEADER.............................................................................................................. 627WEB READNEXT QUERYPARM................................................................................................................ 629WEB RECEIVE (Server)............................................................................................................................ 630

viii

WEB RECEIVE (Client)............................................................................................................................. 637WEB RETRIEVE........................................................................................................................................ 642WEB SEND (Server)..................................................................................................................................644WEB SEND (Client)...................................................................................................................................652WEB STARTBROWSE FORMFIELD...........................................................................................................662WEB STARTBROWSE HTTPHEADER....................................................................................................... 664WEB STARTBROWSE QUERYPARM......................................................................................................... 665WEB WRITE HTTPHEADER......................................................................................................................666WRITE...................................................................................................................................................... 669WRITE JOURNALNAME........................................................................................................................... 675WRITE JOURNALNUM............................................................................................................................. 678WRITE OPERATOR................................................................................................................................... 679WRITEQ TD.............................................................................................................................................. 681WRITEQ TS...............................................................................................................................................684WSACONTEXT BUILD.............................................................................................................................. 688WSACONTEXT DELETE............................................................................................................................ 692WSACONTEXT GET.................................................................................................................................. 692WSAEPR CREATE..................................................................................................................................... 696XCTL......................................................................................................................................................... 699

Chapter 3. Threadsafe commands...................................................................... 703

Chapter 4. CICS-value data areas used by all commands.................................... 707CVDAs and numeric values in alphabetic sequence...............................................................................707CVDA values for the DEVICE option........................................................................................................ 735CVDAs and numeric values in numeric sequence.................................................................................. 739

Chapter 5. National language codes for application development........................ 769

Chapter 6. Terminal control................................................................................771Commands and options for terminals and logical units......................................................................... 771Teletypewriter programming...................................................................................................................772Display device operations....................................................................................................................... 773

Print displayed information (ISSUE PRINT)...................................................................................... 774Copy displayed information (ISSUE COPY)....................................................................................... 774Erase all unprotected fields (ISSUE ERASEAUP).............................................................................. 774Handle input without data (RECEIVE)............................................................................................... 775

Chapter 7. Common Programming Interface Communications (CPICommunications)...........................................................................................777SAA Resource Recovery.......................................................................................................................... 777

Chapter 8. BMS-related constants......................................................................779Magnetic slot reader (MSR) control value constants, DFHMSRCA.........................................................783MSR control byte values.......................................................................................................................... 783Attention identifier constants, DFHAID.................................................................................................. 784

Chapter 9. BMS macros......................................................................................787Map set, map, and field definition...........................................................................................................787Partition set definition............................................................................................................................. 788

Field groups........................................................................................................................................788DFHMDF................................................................................................................................................... 790DFHMDI....................................................................................................................................................799DFHMSD...................................................................................................................................................808DFHPDI.................................................................................................................................................... 817DFHPSD....................................................................................................................................................819

ix

Notices..............................................................................................................821

Index................................................................................................................ 827

x

About this PDF

This PDF is a reference of the commands of the CICS application programming interface. Thisdocumentation is intended for application programmers who are writing applications to interact withCICS. Before CICS TS V5.4, this PDF was called the Application Programming Reference.

For information about how to write applications for CICS, using this API, see Developing CICSApplications.

For details of the terms and notation used in this book, see Conventions and terminology used in the CICSdocumentation in IBM Knowledge Center.

Date of this PDFThis PDF was created on October 19th 2020.

© Copyright IBM Corp. 1974, 2020 xi

https://www.ibm.com/support/knowledgecenter/SSGMCP_latest/documentation/conventions.htmlhttps://www.ibm.com/support/knowledgecenter/SSGMCP_latest/documentation/conventions.html

xii CICS TS for z/OS: API Reference

Chapter 1. CICS API command formatThe general format of a CICS command is EXECUTE CICS (or EXEC CICS) followed by the name of therequired command, and possibly by one or more options.

The command format is as follows:

EXEC CICS command option(arg)....

where:command

describes the operation required (for example, READ).option

describes any of the many optional facilities available with each function. Some options are followedby an argument in parentheses. You can write options (including those that require arguments) in anyorder.

arg(short for argument) is a value such as “data-value” or “name”. A “data-value” can be a constant, thismeans that an argument that sends data to CICS is generally a “data-value”. An argument thatreceives data from CICS must be a “data-area”.

Some arguments described as “data-area” can both send and receive data. In these cases, you mustensure that the “data-area” is not in protected storage.

An example of a CICS command is as follows:

EXEC CICS READ FILE('FILEA') INTO(FILEA) RIDFLD(KEYNUM) UPDATE

You must add the appropriate end-of-command delimiter; see “CICS command syntax notation ” on page1.

Note: If you want to add comments against CICS commands, you can do this, in assembler only, by usinga period or a comma as a delimiter after the last argument. For example:

EXEC CICS ADDRESS EIB(MYUEIB), @F1A

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

CICS command syntax notationIn CICS documentation, CICS commands are presented in a standard way. You interpret the syntax byfollowing 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 in PL/I and C that you must code at the end of eachCICS command. In the C language, a null character can be used as an end-of-string marker, but CICS does

© Copyright IBM Corp. 1974, 2020 1

not recognize this; you must therefore never have a comma or period followed by a space (X'40') in themiddle of a coding line.

The conventions are:

Symbol Action

A

B

C

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

A

B

C

A set of alternatives—one of which you must code. You may codemore than one of them, in any sequence.

A

B

C

A set of alternatives—one of which you may code.

A

B

C

A set of alternatives — any number (including none) of which youmay code once, in any sequence.

A

B

Alternatives where A is the default.

Name

NameA

B

Use with the named section in place of its name.

Punctuation and uppercasecharacters

Code exactly as shown.

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 of argument can containdifferent data types; some arguments return information from CICS to the program and others are set bythe program.

Options in a CICS command can take the following argument values:

2 CICS TS for z/OS: API Reference

• data-value• data-area• cvda (CICS-value data area)• ptr-value• ptr-ref• name• filename• systemname• label• hhmmss

For AMODE(64) programs only, options in a CICS command can also take the following argument values:

• data-area64• ptr-value64• ptr-ref64

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

COBOL argument valuesThe argument values can be replaced as follows:

• data-value can be replaced by any COBOL data name of the correct data type for the argument, or by aconstant that can be converted to the correct type for the argument. The following table shows how todefine 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

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

• data-area can be replaced by any COBOL data name of the correct data type for the argument. Thefollowing 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

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

Chapter 1. CICS API command format 3

Where the data type is unspecified, data-area can refer to an elementary or group item.• cvda is described in CICS-value data areas (CVDAs).• ptr-value can be replaced by a pointer variable or ADDRESS special register.• ptr-ref can be replaced by a pointer variable or ADDRESS special register.• name can be replaced by either of the following values:

– A character string specified as an alphanumeric literal. If this string is shorter than the requiredlength, 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 isthe name to be used by the argument. If data-area is shorter than the required length, the excesscharacters are undefined, which might cause unpredictable results.

filename, as used in FILE(filename), specifies the name of the file. The name must contain 1–8characters from the range A–Z, 0–9, $, @, and #.

systemname, as used in SYSID(systemname), specifies the name of the system to which the request isdirected. The name must contain 1–4 characters from the range A–Z, 0–9, $, @, and #.

• label can be replaced by any COBOL paragraph name or a section name.• 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 the program to read or write dataof a length that is different from that of the referenced variable.

C argument valuesThe argument values can be replaced as follows:

• data-value can be replaced by any C expression that can be converted to the correct data type for theargument. 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

data-value includes data-area as a subset.• 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:


Halfword binary short int

Fullword binary long int

Doubleword binary char[8]


https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/system-programming/intro/dfha80x.html


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, or structure. Thereference must be to contiguous storage.

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

to an address.• ptr-ref can be replaced by any C pointer type reference.• 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. The value of the character array is the name to be used bythe argument.

filename, as used in FILE(filename), specifies the name of the file. The name must have 1–8 charactersfrom the range A–Z, 0–9, $, @, and #.

systemname, as used in SYSID(systemname), specifies the name of the system to which the request isdirected. The name must have 1–4 characters from the range A–Z, 0–9, $, @, and #.

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

that the value passed to CICS is in packed decimal format. The language does not provide a packeddecimal type.HH




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

PL/I argument valuesThe argument values can be replaced as follows:

• data-value can be replaced by any PL/I expression that can be converted to the correct data type for theargument. The following table shows how to define the correct 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.• 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 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

If the data type is unspecified, data-area can refer to an element, array, or structure; for example,FROM(P–>STRUCTURE) LENGTH(LNG). The reference must be to connected storage.

The data area must also have the correct PL/I alignment attribute: ALIGNED for binary items, andUNALIGNED for strings.

If you use a varying data string without an explicit length, the data passed begins with a two-byte lengthfield, and its length is the maximum length declared for the string. If you explicitly specify a length in thecommand, the data passed has this length; that is, the two-byte length field followed by data up to thelength you specified.

• cvda is described in CICS-value data areas (CVDAs).• ptr-value (which includes ptr-refas a subset) can be replaced by any PL/I expression that can be

converted to POINTER.• ptr-ref can be replaced by any PL/I reference of type POINTER ALIGNED.• 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. The value of the character string is the name to be usedby the argument.

filename, as used in FILE(filename), specifies the name of the file. The name must have 1-8 charactersfrom the range A–Z, 0–9, $, @, and #.

systemname, as used in SYSID(systemname), specifies the name of the system to which the request isdirected. The name must have 1-4 characters from the range A–Z, 0–9, $, @, and #.

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

DECIMAL(7,0). The value must be of the form 0HHMMSS+ where:HH




If the UNALIGNED attribute is added to the ENTRY declarations generated by the CICS translator by aDEFAULT DESCRIPTORS statement, data-area or pointer-reference arguments to CICS commands mustalso be UNALIGNED. Similarly for the ALIGNED attribute, data-area or pointer-reference arguments mustbe ALIGNED.

Many commands involve the transfer of data between the application program and CICS. In most cases,the length of the data to be transferred must be provided by the application program. However, if a dataarea is specified as the source or target, it is not necessary to provide the length explicitly, because the



command-language translator generates a default length value of either STG(data-area) or CSTG(data-area), as appropriate.

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

In general, an argument can be either the address of the data or the data itself (in assembler languageterms, either a relocatable expression or an absolute expression).

A relocatable expression must not contain unmatched brackets (outside quotation marks) or unmatchedquotation marks (apart from length-attribute references). If this rule is obeyed, any expression can beused, including literal constants, such as =AL2(100), forms such as 20(0,R11), and forms that use themacro-replacement facilities.

An absolute expression must be a single term that is either a length-attribute reference, or a self-definingconstant.

Use care with equated symbols, which should be used only when referring to registers (pointerreferences). For example, if an equated symbol is used for a length, it is treated as the address of thelength and an unpredictable error occurs.

For AMODE(24) and AMODE(31) assembler language programs, the argument values can be replaced asfollows:

• data-value can be replaced by a relocatable expression that is an assembler-language reference to dataof the correct type for the argument, or by a constant of the correct type for the argument.

• data-area can be replaced by a relocatable expression that is an assembler-language reference to dataof the correct type for the argument.

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

register.• ptr-ref can be replaced by an absolute expression that is an assembler-language reference to a register.• name can be replaced either by a character string in single quotation marks, or by an assembler-

language language relocatable expression reference to a character string. The length is equal to themaximum length allowed for the name. The value of the character string is the name to be used by theargument.



• label refers to a destination address to which control is transferred. It can be replaced by the label ofthe destination instruction or by the label of an address constant for the destination. This constant mustnot specify a length.

You can also use the expression =A(dest) where dest is a relocatable expression denoting thedestination.

For example, the following commands are equivalent:

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



• hhmmss can be replaced by a self-defining decimal constant, or an assembler-language reference to afield defined as PL4. The value must be of the form 0HHMMSS+ where:HH

Represents hours from 00 through 99MM

Represents minutes from 00 through 59SS

Represents seconds from 00 through 59

Many commands involve the transfer of data between the application program and CICS. In most cases,the application program must provide the length of the data to be transferred. However, if a data area isspecified as the source or target, it is not necessary to provide the length explicitly, because thecommand-language translator generates a default length. For example:

xxx DC CL8 . .EXEC CICS ... LENGTH(L'xxx)

Assembler-language argument values for AMODE(64) programsIn general, an argument can be either the address of the data or the data itself (in assembler languageterms, either a relocatable expression or an absolute expression).

A relocatable expression must not contain unmatched brackets (outside quotation marks) or unmatchedquotation marks (apart from length-attribute references). If this rule is obeyed, any expression can beused, including literal constants, such as =AL2(100), forms such as 20(0,R11), and forms that use themacro-replacement facilities.

An absolute expression must be a single term that is either a length-attribute reference, or a self-definingconstant.

Use care with equated symbols, which should be used only when referring to registers (pointerreferences). For example, if an equated symbol is used for a length, it is treated as the address of thelength and an unpredictable error occurs.

For non-Language Environment® (LE) AMODE(64) assembler language programs, argument values can bereplaced as follows:

• data-value can be replaced by a relocatable expression that is an assembler-language reference to dataof the correct type for the argument, or by a constant of the correct type for the argument.

• data-area can be replaced by a relocatable expression that is an assembler-language reference to dataof the correct type for the argument.

• data-area64 can be replaced by a relocatable expression that is an assembler-language 64-bitreference to data of the correct type for the argument.

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

register.• ptr-value64 can be replaced by an absolute expression that is an assembler-language 64-bit reference

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

register.• name can be replaced either by a character string in single quotation marks, or by an assembler-

language language relocatable expression reference to a character string. The length is equal to the



maximum length allowed for the name. The value of the character string is the name to be used by theargument.



• hhmmss can be replaced by a self-defining decimal constant, or an assembler-language reference to afield defined as PL4. The value must be of the form 0HHMMSS+ where:HH

Represents hours from 00 through 99MM

Represents minutes from 00 through 59SS

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 and CICS. In most cases,the application program must provide the length of the data to be transferred. However, if a data area isspecified as the source or target, it is not necessary to provide the length explicitly, because thecommand-language translator generates a default length. For example:

xxx DC CL8 . .EXEC CICS ... LENGTH(L'xxx)

CICS command restrictionsSome general restrictions apply to all CICS commands that access user data.

• The program must be in primary addressing mode when invoking any CICS service. The primary addressspace must be the home address space. All parameters passed to CICS must reside in the primaryaddress space.

• If your program uses access registers, CICS preserves only access registers 2 through 13, because CICScode 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, if the NOLENGTHtranslator option is not specified. This means they are optional in programs 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 signed halfword binary value. Thisputs a theoretical upper limit of 32 763 bytes on LENGTH. In practice, depending on issues ofrecoverability, function shipping, and other factors, assume a 24 KB limit.

This advisory 24 KB limit does not apply to the FLENGTH option on CICS commands (except for terminal-related SEND and RECEIVE commands, because of architectural limitations). The FLENGTH option is usedon commands that relate to containers and journals, among others.

For temporary storage, transient data, and file control commands, the data set definitions themselvesmight impose further restrictions.


NOHANDLE optionUse the NOHANDLE option with any command to specify that you want no action to be taken for anycondition or AID resulting from the execution of that command.

For further information about the NOHANDLE option, see RESP and NOHANDLE 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 was raised during itsexecution. With some commands, when a condition can be raised for more than one reason, if you havealready specified RESP, you can use the RESP2 option to determine exactly why a condition occurred.RESP(xxx)

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

EXEC CICS WRITEQ TS FROM(abc) QUEUE(qname) NOSUSPEND RESP(xxx) RESP2(yyy) . .IF xxx=DFHRESP(NOSPACE) THEN ...

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

The following example is a similar test in C:

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

The following example is a similar test in assembler language:

CLC xxx,DFHRESP(NOSPACE)

The translator changes this code to:

CLC xxx,=F'18'

Because the use of RESP implies NOHANDLE, use care when you use RESP with the RECEIVEcommand. NOHANDLE overrides both the HANDLE AID and the HANDLE CONDITION command, withthe result that PF key responses are ignored.

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


https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/applications/designing/dfhp3_exc_resp_nohandle.html

Translated code for CICS commandsApplication programs can be written in COBOL, C, PL/I, or assembler language, and contain CICScommands. CICS translates these programs and creates an equivalent source program where eachcommand is now translated into a call macro or statement in the language of the original source program.

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

The following example shows how the EXEC statement:

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

is translated to:

Move length of mycommarea to dfhb0020Call 'DFHEI1' using by content x'0e08e0000700001000f0f0f0f2f7404040' by content 'fred' by reference mycommarea by reference dfhb0020 end-call.

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

01 EIBLK.

whereas in DFHEIBLC the top level name is

01 dfheiblk.

This is consistent with the name generated by the translator today, and also conforms to the rule thatCICS reserved words should start with DFH.

C translation outputFor a C application program, each command is replaced by reassignment statements followed by adfhexec statement that passes the parameters.

PL/I translation outputFor a PL/I application program, each command is always replaced by a DO statement, a declaration of agenerated entry name, a CALL statement, and an END statement. The ENTRY declaration ensures that theappropriate conversions for argument values take place.

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

ON ERROR BEGIN; EXEC CICS RETURN; END;


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

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

If OPTIONS(MAIN) is specified, the translator modifies the parameter list by inserting the EIB structurepointer as the first parameter. If OPTIONS(MAIN) is not specified (that is, if the program is to be link-edited to the main module), the parameter list is not modified, and it is the application programmer'sresponsibility to address the EIB structure in the link-edited program if access to it is required. In eithercase, where a program commences with a valid PL/I PROCEDURE statement, the translator inserts thedeclaration of the EIB structure.

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

On entry to the application program, registers 1, 15, 14, and 13 contain the following addresses:

• 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'

• Register 15 contains the address of the entry point.• Register 14 contains the address of the return point.• 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 detects a CICS command, eachcommand is replaced by an invocation of the DFHECALL macro. The DFHECALL macro sets up thecommand parameters and calls the initial 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 contentsof these registers are as follows:

• Register 15 contains the address of the entry point in the EXEC interface program.• Register 14 contains the address of the return point in your application program.• Register 0 is undefined.• Register 1 contains the address of the parameter list.

The entry point held in register 15 is resolved in the EXEC interface processor that must be link-editedwith your application program. For AMODE(24) and AMODE(31) applications, this EXEC interfaceprocessor is DFHEAI; for AMODE(64) applications, it is DFHEAG.

You can specify the exit from the application program by an EXEC CICS RETURN command in your sourceprogram. Alternatively, you can use the DFHEIRET macro, which restores the registers and returns controlto the address in register 14. The translator inserts the DFHEIRET macro, with no parameters specified,immediately before the END statement, unless you specify the NOEPILOG translator option. You can usethis macro to return from a top-level program, but is not advisable from a lower-level program.

During assembly, the DFHECALL macro builds an argument list in dynamic storage, so that the applicationprogram is reentrant. Then the macro invokes the EXEC interface program DFHEIP for AMODE(24) orAMODE(31) applications, or DFHEIG for AMODE(64) applications. These programs also obey systemstandards, as previously described.


version 5 release 5 cics transaction server for z/os · 2020. 8. 13. · • release

Documents