· Contents. About this...

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 page817.

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................................................................................................................ 3CICS command restrictions.........................................................................................................................9LENGTH options in CICS commands.........................................................................................................10NOHANDLE option..................................................................................................................................... 10RESP and RESP2 options...........................................................................................................................10Translated code for CICS commands........................................................................................................11

COBOL translation output.................................................................................................................... 11C translation output..............................................................................................................................12PL/I translation output.........................................................................................................................12Assembler translation output.............................................................................................................. 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)...........................................................................................................................84CONVERSE (3767)..................................................................................................................................... 84CONVERSE (3770)..................................................................................................................................... 85CONVERSE (3790 full-function or inquiry)................................................................................................85CONVERSE (3790 3270-display).............................................................................................................. 85CONVERSE: z/OS Communications Server options.................................................................................. 86CONVERSE (non-z/OS Communications Server default)..........................................................................90CONVERSE (MRO)...................................................................................................................................... 91CONVERSE (2260)..................................................................................................................................... 91CONVERSE: non-z/OS Communications Server options.......................................................................... 92CONVERTTIME...........................................................................................................................................95DEFINE ACTIVITY......................................................................................................................................97DEFINE COMPOSITE EVENT..................................................................................................................... 99DEFINE COUNTER and DEFINE DCOUNTER...........................................................................................101DEFINE INPUT EVENT.............................................................................................................................104DEFINE PROCESS.................................................................................................................................... 104DEFINE TIMER.........................................................................................................................................107DELAY.......................................................................................................................................................110DELETE.....................................................................................................................................................113DELETE ACTIVITY....................................................................................................................................119DELETE CHANNEL................................................................................................................................... 120DELETE CONTAINER (BTS)..................................................................................................................... 121DELETE CONTAINER (CHANNEL)............................................................................................................123DELETE COUNTER and DELETE DCOUNTER...........................................................................................124DELETE EVENT.........................................................................................................................................126DELETE TIMER.........................................................................................................................................127DELETEQ TD.............................................................................................................................................128DELETEQ TS............................................................................................................................................. 129DEQ.......................................................................................................................................................... 131DOCUMENT CREATE................................................................................................................................132DOCUMENT DELETE................................................................................................................................ 135DOCUMENT INSERT................................................................................................................................ 136DOCUMENT RETRIEVE............................................................................................................................ 139DOCUMENT SET.......................................................................................................................................141DUMP TRANSACTION..............................................................................................................................143ENDBR......................................................................................................................................................147ENDBROWSE ACTIVITY.......................................................................................................................... 149ENDBROWSE CONTAINER (BTS)............................................................................................................ 150ENDBROWSE CONTAINER (CHANNEL).................................................................................................. 150ENDBROWSE EVENT............................................................................................................................... 151ENDBROWSE PROCESS...........................................................................................................................152ENDBROWSE TIMER................................................................................................................................152ENQ.......................................................................................................................................................... 153ENTER TRACENUM.................................................................................................................................. 156EXTRACT ATTACH (LUTYPE6.1)..............................................................................................................157EXTRACT ATTACH (MRO)........................................................................................................................ 160EXTRACT 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.......................................................................................................................................288ISSUE PRINT............................................................................................................................................289ISSUE QUERY...........................................................................................................................................290ISSUE RECEIVE........................................................................................................................................291ISSUE REPLACE....................................................................................................................................... 293ISSUE RESET............................................................................................................................................295ISSUE SEND............................................................................................................................................. 295ISSUE SIGNAL (APPC)............................................................................................................................. 297ISSUE SIGNAL (LUTYPE6.1)....................................................................................................................298ISSUE WAIT............................................................................................................................................. 299JOURNAL..................................................................................................................................................301LINK......................................................................................................................................................... 301LINK ACQPROCESS................................................................................................................................. 309LINK ACTIVITY........................................................................................................................................ 311LOAD........................................................................................................................................................ 314MONITOR.................................................................................................................................................317MOVE CONTAINER (BTS)........................................................................................................................ 319MOVE CONTAINER (CHANNEL)...............................................................................................................321POINT.......................................................................................................................................................323POP HANDLE............................................................................................................................................324POST.........................................................................................................................................................325PURGE MESSAGE.....................................................................................................................................328PUSH HANDLE......................................................................................................................................... 329PUT CONTAINER (BTS)........................................................................................................................... 329PUT CONTAINER (CHANNEL)..................................................................................................................332PUT64 CONTAINER................................................................................................................................. 335QUERY CHANNEL.....................................................................................................................................339QUERY 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)............................................................................................................................ 386RECEIVE (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................................................................................................................................ 407REQUEST ENCRYPTPTKT........................................................................................................................ 408REQUEST PASSTICKET............................................................................................................................410RESET ACQPROCESS...............................................................................................................................411RESET ACTIVITY......................................................................................................................................413RESETBR.................................................................................................................................................. 414RESUME................................................................................................................................................... 418RETRIEVE.................................................................................................................................................420RETRIEVE REATTACH EVENT................................................................................................................. 422RETRIEVE SUBEVENT..............................................................................................................................424RETURN....................................................................................................................................................425REWIND COUNTER and REWIND DCOUNTER........................................................................................428REWRITE..................................................................................................................................................431ROUTE...................................................................................................................................................... 436RUN.......................................................................................................................................................... 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........................................................................................................................473SEND PAGE.............................................................................................................................................. 476SEND PARTNSET......................................................................................................................................479SEND TEXT...............................................................................................................................................479SEND TEXT MAPPED................................................................................................................................485SEND TEXT NOEDIT.................................................................................................................................487SIGNAL EVENT.........................................................................................................................................490SIGNOFF.................................................................................................................................................. 491

vii

SIGNON....................................................................................................................................................492SIGNON TOKEN....................................................................................................................................... 496SOAPFAULT ADD..................................................................................................................................... 501SOAPFAULT CREATE............................................................................................................................... 503SOAPFAULT DELETE................................................................................................................................506SPOOLCLOSE........................................................................................................................................... 507SPOOLOPEN INPUT.................................................................................................................................509SPOOLOPEN OUTPUT..............................................................................................................................512SPOOLREAD.............................................................................................................................................516SPOOLWRITE...........................................................................................................................................519START.......................................................................................................................................................521START ATTACH........................................................................................................................................530START 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............................................................................................................ 606WEB EXTRACT......................................................................................................................................... 607WEB OPEN............................................................................................................................................... 612WEB PARSE URL...................................................................................................................................... 617WEB READ FORMFIELD...........................................................................................................................619WEB READ HTTPHEADER........................................................................................................................621WEB READ QUERYPARM......................................................................................................................... 623WEB READNEXT FORMFIELD..................................................................................................................625WEB READNEXT HTTPHEADER...............................................................................................................626WEB READNEXT QUERYPARM................................................................................................................ 628WEB RECEIVE (Server)............................................................................................................................ 629

viii

WEB RECEIVE (Client)............................................................................................................................. 635WEB RETRIEVE........................................................................................................................................ 641WEB SEND (Server)..................................................................................................................................642WEB SEND (Client)...................................................................................................................................650WEB STARTBROWSE FORMFIELD.......................................................................................................... 660WEB STARTBROWSE HTTPHEADER....................................................................................................... 662WEB STARTBROWSE QUERYPARM.........................................................................................................663WEB WRITE HTTPHEADER......................................................................................................................664WRITE...................................................................................................................................................... 667WRITE JOURNALNAME........................................................................................................................... 673WRITE JOURNALNUM............................................................................................................................. 676WRITE OPERATOR...................................................................................................................................677WRITEQ TD.............................................................................................................................................. 679WRITEQ TS...............................................................................................................................................682WSACONTEXT BUILD.............................................................................................................................. 686WSACONTEXT DELETE............................................................................................................................ 690WSACONTEXT GET.................................................................................................................................. 690WSAEPR CREATE.....................................................................................................................................694XCTL......................................................................................................................................................... 697

Chapter 3. Threadsafe commands...................................................................... 701

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

Chapter 5. National language codes................................................................... 765

Chapter 6. Terminal control............................................................................... 767Commands and options for terminals and logical units......................................................................... 767Teletypewriter programming.................................................................................................................. 768Display device operations....................................................................................................................... 769

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

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

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

Chapter 9. BMS macros......................................................................................783Map set, map, and field definition...........................................................................................................783Partition set definition............................................................................................................................. 784

Field groups........................................................................................................................................784DFHMDF................................................................................................................................................... 786DFHMDI....................................................................................................................................................795DFHMSD...................................................................................................................................................804DFHPDI.................................................................................................................................................... 813DFHPSD....................................................................................................................................................815

ix

Notices..............................................................................................................817

Index................................................................................................................ 823

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 April 13th 2020.

© Copyright IBM Corp. 1974, 2020 xi

https://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/documentation/conventions.htmlhttps://www.ibm.com/support/knowledgecenter/SSGMCP_5.4.0/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 CICS

© Copyright IBM Corp. 1974, 2020 1

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

2 CICS TS for z/OS: API Reference

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


Halfword binary PIC S9(4) COMP

Chapter 1. CICS API command format 3


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


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

• data-area can be replaced by any C data reference that has the correct data type for the argument. Thefollowing 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


Represents minutes from 00 through 59.SS

Represents seconds from 00 through 59.

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:


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


Represents minutes from 00 through 59.



SSRepresents seconds from 00 through 59.

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 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) 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 referenceto 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.

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:


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

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 ob

· Contents. About this...

Documents

Transcript of · Contents. About this...