version 5 release 4 cics transaction server for z/os€¦ · force timer.....183

CICS Transaction Server for z/OSVersion 5 Release 4

API Reference

IBM

Note

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

This edition applies to the IBM CICS® Transaction Server for z/OS® Version 5 Release 4 (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....................................................................................................................................... 9RESP 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......................................................................................................................................... 28ADDRESS....................................................................................................................................................30ADDRESS SET.............................................................................................................................................31ALLOCATE (APPC)......................................................................................................................................32ALLOCATE (LUTYPE6.1).............................................................................................................................34ALLOCATE (MRO)....................................................................................................................................... 36ASKTIME.................................................................................................................................................... 37ASSIGN.......................................................................................................................................................39

Codes returned by ASSIGN..................................................................................................................52BIF DEEDIT................................................................................................................................................ 54BIF DIGEST................................................................................................................................................ 56BUILD ATTACH (LUTYPE6.1).....................................................................................................................57BUILD ATTACH (MRO)............................................................................................................................... 59CANCEL...................................................................................................................................................... 61CANCEL (BTS)............................................................................................................................................ 63CHANGE PHRASE.......................................................................................................................................65CHANGE PASSWORD................................................................................................................................. 67CHANGE TASK............................................................................................................................................68CHECK ACQPROCESS................................................................................................................................ 69CHECK ACTIVITY....................................................................................................................................... 70CHECK TIMER............................................................................................................................................ 73CONNECT PROCESS.................................................................................................................................. 74CONVERSE (default).................................................................................................................................. 77CONVERSE (APPC).....................................................................................................................................77CONVERSE (LUTYPE2/LUTYPE3).............................................................................................................. 78CONVERSE (LUTYPE4)...............................................................................................................................78CONVERSE (LUTYPE6.1)............................................................................................................................79CONVERSE (SCS)....................................................................................................................................... 79CONVERSE (3270 logical)..........................................................................................................................80CONVERSE (3600-3601)...........................................................................................................................80CONVERSE (3600-3614)...........................................................................................................................81CONVERSE (3650 interpreter).................................................................................................................. 82

iii

CONVERSE (3650-3270)...........................................................................................................................82CONVERSE (3650-3653)...........................................................................................................................83CONVERSE (3650-3680)...........................................................................................................................83CONVERSE (3767)..................................................................................................................................... 83CONVERSE (3770)..................................................................................................................................... 84CONVERSE (3790 full-function or inquiry)................................................................................................84CONVERSE (3790 3270-display).............................................................................................................. 85CONVERSE: z/OS Communications Server options.................................................................................. 86CONVERSE (non-z/OS Communications Server default)..........................................................................90CONVERSE (MRO)...................................................................................................................................... 90CONVERSE (2260)..................................................................................................................................... 91CONVERSE: non-z/OS Communications Server options.......................................................................... 91CONVERTTIME...........................................................................................................................................95DEFINE ACTIVITY......................................................................................................................................96DEFINE COMPOSITE EVENT..................................................................................................................... 98DEFINE COUNTER and DEFINE DCOUNTER...........................................................................................100DEFINE INPUT EVENT.............................................................................................................................103DEFINE PROCESS.................................................................................................................................... 104DEFINE TIMER.........................................................................................................................................106DELAY.......................................................................................................................................................109DELETE.....................................................................................................................................................112DELETE ACTIVITY....................................................................................................................................118DELETE CHANNEL................................................................................................................................... 119DELETE CONTAINER (BTS)..................................................................................................................... 120DELETE CONTAINER (CHANNEL)............................................................................................................122DELETE COUNTER and DELETE DCOUNTER...........................................................................................123DELETE EVENT.........................................................................................................................................125DELETE TIMER.........................................................................................................................................126DELETEQ TD.............................................................................................................................................127DELETEQ TS............................................................................................................................................. 128DEQ.......................................................................................................................................................... 129DOCUMENT CREATE................................................................................................................................131DOCUMENT DELETE................................................................................................................................ 134DOCUMENT INSERT................................................................................................................................ 134DOCUMENT RETRIEVE............................................................................................................................ 138DOCUMENT SET.......................................................................................................................................140DUMP TRANSACTION..............................................................................................................................142ENDBR......................................................................................................................................................146ENDBROWSE ACTIVITY.......................................................................................................................... 148ENDBROWSE CONTAINER (BTS)............................................................................................................ 149ENDBROWSE CONTAINER (CHANNEL).................................................................................................. 149ENDBROWSE EVENT............................................................................................................................... 150ENDBROWSE PROCESS...........................................................................................................................151ENDBROWSE TIMER................................................................................................................................151ENQ.......................................................................................................................................................... 152ENTER TRACENUM.................................................................................................................................. 155EXTRACT ATTACH (LUTYPE6.1)..............................................................................................................156EXTRACT ATTACH (MRO)........................................................................................................................ 159EXTRACT ATTRIBUTES (APPC)............................................................................................................... 162EXTRACT ATTRIBUTES (MRO)................................................................................................................ 163EXTRACT CERTIFICATE.......................................................................................................................... 164EXTRACT LOGONMSG............................................................................................................................. 167EXTRACT PROCESS................................................................................................................................. 168EXTRACT TCPIP.......................................................................................................................................170EXTRACT TCT...........................................................................................................................................173EXTRACT WEB......................................................................................................................................... 174FETCH ANY.............................................................................................................................................. 179FETCH CHILD...........................................................................................................................................180

iv

FORCE TIMER.......................................................................................................................................... 182FORMATTIME...........................................................................................................................................183FREE......................................................................................................................................................... 187FREE (APPC).............................................................................................................................................187FREE (LUTYPE6.1)................................................................................................................................... 189FREE (MRO)..............................................................................................................................................189FREE CHILD............................................................................................................................................. 191FREEMAIN................................................................................................................................................191FREEMAIN64........................................................................................................................................... 194GDS ALLOCATE........................................................................................................................................ 195GDS ASSIGN............................................................................................................................................ 197GDS CONNECT PROCESS........................................................................................................................ 198GDS EXTRACT ATTRIBUTES................................................................................................................... 200GDS EXTRACT PROCESS......................................................................................................................... 201GDS FREE.................................................................................................................................................203GDS ISSUE ABEND.................................................................................................................................. 204GDS ISSUE CONFIRMATION...................................................................................................................205GDS ISSUE ERROR...................................................................................................................................206GDS ISSUE PREPARE...............................................................................................................................207GDS ISSUE SIGNAL................................................................................................................................. 209GDS RECEIVE...........................................................................................................................................210GDS SEND................................................................................................................................................ 212GDS WAIT................................................................................................................................................ 214GET CONTAINER (BTS)........................................................................................................................... 215GET CONTAINER (CHANNEL)..................................................................................................................218GET COUNTER and GET DCOUNTER.......................................................................................................222GETMAIN................................................................................................................................................. 226GETMAIN64............................................................................................................................................. 230GETNEXT ACTIVITY.................................................................................................................................233GETNEXT CONTAINER (BTS).................................................................................................................. 234GETNEXT CONTAINER (CHANNEL).........................................................................................................235GETNEXT EVENT......................................................................................................................................236GETNEXT PROCESS................................................................................................................................. 237GETNEXT TIMER......................................................................................................................................238GET64 CONTAINER................................................................................................................................. 240HANDLE ABEND.......................................................................................................................................244HANDLE AID............................................................................................................................................ 246HANDLE CONDITION...............................................................................................................................247IGNORE CONDITION...............................................................................................................................249INQUIRE ACTIVITYID............................................................................................................................. 249INQUIRE CONTAINER............................................................................................................................. 252INQUIRE EVENT...................................................................................................................................... 254INQUIRE PROCESS..................................................................................................................................255INQUIRE TIMER.......................................................................................................................................256INVOKE APPLICATION............................................................................................................................258INVOKE SERVICE.....................................................................................................................................261INVOKE WEBSERVICE.............................................................................................................................266ISSUE ABEND.......................................................................................................................................... 266ISSUE ABORT...........................................................................................................................................267ISSUE ADD............................................................................................................................................... 269ISSUE CONFIRMATION...........................................................................................................................271ISSUE COPY (3270 logical)..................................................................................................................... 272ISSUE DISCONNECT (default).................................................................................................................273ISSUE DISCONNECT (LUTYPE6.1).......................................................................................................... 274ISSUE END............................................................................................................................................... 275ISSUE ENDFILE........................................................................................................................................277ISSUE ENDOUTPUT................................................................................................................................. 277ISSUE EODS............................................................................................................................................. 278

v

ISSUE ERASE........................................................................................................................................... 278ISSUE ERASEAUP.................................................................................................................................... 280ISSUE ERROR...........................................................................................................................................281ISSUE LOAD............................................................................................................................................. 283ISSUE NOTE............................................................................................................................................. 284ISSUE PASS..............................................................................................................................................285ISSUE PREPARE.......................................................................................................................................286ISSUE PRINT............................................................................................................................................287ISSUE QUERY...........................................................................................................................................288ISSUE RECEIVE........................................................................................................................................290ISSUE REPLACE....................................................................................................................................... 291ISSUE RESET............................................................................................................................................293ISSUE SEND............................................................................................................................................. 293ISSUE SIGNAL (APPC)............................................................................................................................. 295ISSUE SIGNAL (LUTYPE6.1)....................................................................................................................297ISSUE WAIT............................................................................................................................................. 298JOURNAL..................................................................................................................................................299LINK......................................................................................................................................................... 300LINK ACQPROCESS................................................................................................................................. 307LINK ACTIVITY........................................................................................................................................ 310LOAD........................................................................................................................................................ 313MONITOR.................................................................................................................................................316MOVE CONTAINER (BTS)........................................................................................................................ 318MOVE CONTAINER (CHANNEL)...............................................................................................................320POINT.......................................................................................................................................................322POP HANDLE............................................................................................................................................323POST.........................................................................................................................................................324PURGE MESSAGE.....................................................................................................................................327PUSH HANDLE......................................................................................................................................... 327PUT CONTAINER (BTS)........................................................................................................................... 328PUT CONTAINER (CHANNEL)..................................................................................................................330PUT64 CONTAINER................................................................................................................................. 334QUERY CHANNEL.....................................................................................................................................337QUERY COUNTER and QUERY DCOUNTER.............................................................................................338QUERY SECURITY....................................................................................................................................341READ........................................................................................................................................................ 345READNEXT............................................................................................................................................... 356READPREV............................................................................................................................................... 366READQ TD................................................................................................................................................ 374READQ TS.................................................................................................................................................378RECEIVE (z/OS Communications Server default)................................................................................... 381RECEIVE (APPC)...................................................................................................................................... 381RECEIVE (LUTYPE2/LUTYPE3)................................................................................................................382RECEIVE (LUTYPE4)................................................................................................................................ 382RECEIVE (LUTYPE6.1)............................................................................................................................. 383RECEIVE (3270 logical)........................................................................................................................... 383RECEIVE (3600 pipeline).........................................................................................................................383RECEIVE (3600-3601)............................................................................................................................ 384RECEIVE (3600-3614)............................................................................................................................ 384RECEIVE (3650).......................................................................................................................................385RECEIVE (3767).......................................................................................................................................386RECEIVE (3770).......................................................................................................................................386RECEIVE (3790 full-function or inquiry)................................................................................................. 387RECEIVE: z/OS Communications Server options....................................................................................387RECEIVE (non-z/OS Communications Server default)........................................................................... 390RECEIVE (MRO)........................................................................................................................................391RECEIVE (2260).......................................................................................................................................391RECEIVE (2980).......................................................................................................................................391

vi

RECEIVE (3790 3270-display)................................................................................................................394RECEIVE: non-z/OSCommunications Server options.............................................................................394RECEIVE MAP.......................................................................................................................................... 397RECEIVE MAP MAPPINGDEV.................................................................................................................. 400RECEIVE PARTN.......................................................................................................................................402RELEASE...................................................................................................................................................404REMOVE SUBEVENT................................................................................................................................ 405REQUEST ENCRYPTPTKT........................................................................................................................ 406REQUEST PASSTICKET............................................................................................................................409RESET ACQPROCESS...............................................................................................................................410RESET ACTIVITY......................................................................................................................................411RESETBR.................................................................................................................................................. 413RESUME................................................................................................................................................... 417RETRIEVE.................................................................................................................................................419RETRIEVE REATTACH EVENT................................................................................................................. 421RETRIEVE SUBEVENT..............................................................................................................................423RETURN....................................................................................................................................................424REWIND COUNTER and REWIND DCOUNTER........................................................................................427REWRITE..................................................................................................................................................430ROUTE...................................................................................................................................................... 434RUN.......................................................................................................................................................... 438RUN TRANSID..........................................................................................................................................442SEND (z/OS Communications Server default)........................................................................................ 444SEND (APPC)............................................................................................................................................444SEND (LUTYPE2/LUTYPE3)..................................................................................................................... 445SEND (LUTYPE4)......................................................................................................................................445SEND (LUTYPE6.1)...................................................................................................................................445SEND (SCS).............................................................................................................................................. 446SEND (3270 logical).................................................................................................................................446SEND (3600 pipeline).............................................................................................................................. 447SEND (3600-3601)..................................................................................................................................447SEND (3600-3614)..................................................................................................................................448SEND (3650 interpreter)......................................................................................................................... 449SEND (3650-3270)..................................................................................................................................449SEND (3650-3653)..................................................................................................................................450SEND (3650-3680)..................................................................................................................................450SEND (3767)............................................................................................................................................ 450SEND (3770)............................................................................................................................................ 451SEND (3790 full-function or inquiry)...................................................................................................... 451SEND (3790 SCS).....................................................................................................................................452SEND (3790 3270-display)..................................................................................................................... 452SEND (3790 3270-printer)......................................................................................................................453SEND: z/OS Communications Server options......................................................................................... 453SEND (non-z/OS Communications Server default).................................................................................456SEND (MRO)............................................................................................................................................. 456SEND (2260)............................................................................................................................................ 457SEND (2980)............................................................................................................................................ 457SEND: non-z/OS Communications Server options................................................................................. 458SEND CONTROL....................................................................................................................................... 460SEND MAP................................................................................................................................................465SEND MAP MAPPINGDEV........................................................................................................................471SEND PAGE.............................................................................................................................................. 474SEND PARTNSET......................................................................................................................................477SEND TEXT...............................................................................................................................................478SEND TEXT MAPPED................................................................................................................................483SEND TEXT NOEDIT.................................................................................................................................485SIGNAL EVENT.........................................................................................................................................488SIGNOFF.................................................................................................................................................. 489

vii

SIGNON....................................................................................................................................................490SIGNON TOKEN....................................................................................................................................... 494SOAPFAULT ADD..................................................................................................................................... 499SOAPFAULT CREATE............................................................................................................................... 501SOAPFAULT DELETE................................................................................................................................504SPOOLCLOSE........................................................................................................................................... 505SPOOLOPEN INPUT.................................................................................................................................507SPOOLOPEN OUTPUT..............................................................................................................................510SPOOLREAD.............................................................................................................................................514SPOOLWRITE...........................................................................................................................................517START.......................................................................................................................................................519START ATTACH........................................................................................................................................527START BREXIT......................................................................................................................................... 529START CHANNEL..................................................................................................................................... 531STARTBR..................................................................................................................................................536STARTBROWSE ACTIVITY.......................................................................................................................541STARTBROWSE CONTAINER (BTS)........................................................................................................ 543STARTBROWSE CONTAINER (CHANNEL)...............................................................................................544STARTBROWSE EVENT............................................................................................................................545STARTBROWSE PROCESS.......................................................................................................................546STARTBROWSE TIMER............................................................................................................................547SUSPEND................................................................................................................................................. 548SUSPEND (BTS)....................................................................................................................................... 548SYNCPOINT............................................................................................................................................. 550SYNCPOINT ROLLBACK...........................................................................................................................550TEST EVENT............................................................................................................................................. 551TRANSFORM DATATOJSON.................................................................................................................... 552TRANSFORM DATATOXML...................................................................................................................... 554TRANSFORM JSONTODATA.................................................................................................................... 557TRANSFORM XMLTODATA...................................................................................................................... 558UNLOCK................................................................................................................................................... 562UPDATE COUNTER and UPDATE DCOUNTER.........................................................................................565VERIFY PASSWORD.................................................................................................................................568VERIFY PHRASE.......................................................................................................................................570VERIFY TOKEN.........................................................................................................................................573WAIT CONVID (APPC)............................................................................................................................. 576WAIT EVENT............................................................................................................................................ 577WAIT EXTERNAL......................................................................................................................................578WAIT JOURNALNAME............................................................................................................................. 581WAIT JOURNALNUM............................................................................................................................... 583WAIT SIGNAL...........................................................................................................................................583WAIT TERMINAL......................................................................................................................................584WAITCICS................................................................................................................................................ 585WEB CLOSE.............................................................................................................................................. 587WEB CONVERSE...................................................................................................................................... 590WEB ENDBROWSE FORMFIELD.............................................................................................................. 602WEB ENDBROWSE HTTPHEADER...........................................................................................................603WEB ENDBROWSE QUERYPARM............................................................................................................ 603WEB EXTRACT......................................................................................................................................... 604WEB OPEN............................................................................................................................................... 609WEB PARSE URL...................................................................................................................................... 614WEB READ FORMFIELD...........................................................................................................................616WEB READ HTTPHEADER........................................................................................................................618WEB READ QUERYPARM......................................................................................................................... 620WEB READNEXT FORMFIELD..................................................................................................................622WEB READNEXT HTTPHEADER...............................................................................................................623WEB READNEXT QUERYPARM................................................................................................................ 625WEB RECEIVE (Server)............................................................................................................................ 626

viii

WEB RECEIVE (Client)............................................................................................................................. 632WEB RETRIEVE........................................................................................................................................ 638WEB SEND (Server)..................................................................................................................................639WEB SEND (Client)...................................................................................................................................647WEB STARTBROWSE FORMFIELD.......................................................................................................... 657WEB STARTBROWSE HTTPHEADER....................................................................................................... 658WEB STARTBROWSE QUERYPARM.........................................................................................................659WEB WRITE HTTPHEADER......................................................................................................................661WRITE...................................................................................................................................................... 664WRITE JOURNALNAME........................................................................................................................... 670WRITE JOURNALNUM............................................................................................................................. 673WRITE OPERATOR...................................................................................................................................674WRITEQ TD.............................................................................................................................................. 676WRITEQ TS...............................................................................................................................................678WSACONTEXT BUILD.............................................................................................................................. 682WSACONTEXT DELETE............................................................................................................................ 686WSACONTEXT GET.................................................................................................................................. 687WSAEPR CREATE.....................................................................................................................................691XCTL......................................................................................................................................................... 693

Chapter 3. Threadsafe commands...................................................................... 697

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

Chapter 5. National language codes................................................................... 761

Chapter 6. Terminal control............................................................................... 763Commands and options for terminals and logical units......................................................................... 763Teletypewriter programming.................................................................................................................. 764Display device operations....................................................................................................................... 765

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

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

Chapter 8. BMS-related constants......................................................................771Magnetic slot reader (MSR) control value constants, DFHMSRCA.........................................................775MSR control byte values.......................................................................................................................... 775Attention identifier constants, DFHAID.................................................................................................. 776

Chapter 9. BMS macros......................................................................................779Map set, map, and field definition...........................................................................................................779Partition set definition............................................................................................................................. 780

Field groups........................................................................................................................................780DFHMDF................................................................................................................................................... 782DFHMDI....................................................................................................................................................791DFHMSD...................................................................................................................................................800DFHPDI.................................................................................................................................................... 809DFHPSD....................................................................................................................................................811

ix

Notices..............................................................................................................813

Index................................................................................................................ 819

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 PDF

This 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,this means 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 CICSdoes not recognize this; you must therefore never have a comma or period followed by a space (X'40') inthe middle of a coding line.

© Copyright IBM Corp. 1974, 2020 1

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:

• data-value• data-area

2 CICS TS for z/OS: API Reference

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

Data 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 values

The 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

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.

Chapter 1. CICS API command format 3

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

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


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

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, 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 values


• data-value can be replaced by any PL/I expression that can be converted to the correct data type forthe 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

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 inthe command, the data passed has this length; that is, the two-byte length field followed by data up tothe length 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 beused by 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 thecommand-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 99



MMRepresents minutes from 00 through 59

SSRepresents 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) 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 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 themaximum 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.


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

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.


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.

For AMODE(64) applications, although the application and the initial comm

version 5 release 4 cics transaction server for z/os€¦ · force timer.....183

Documents