0% found this document useful (0 votes)

245 views

CICS Application Programming Reference

This is the second edition of the Application Programming Reference for CICS / ESA 4.1. Changes from the first edition are marked by the '+' sign to the left of the changes. When you send information to IBM, you grant it a nonexclusive right to use or distribute it.

Uploaded by

Sasikanth Dumpa

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

245 views

CICS Application Programming Reference

Uploaded by

Sasikanth Dumpa

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 462

CICS for MVS/ESA.

IBM
Application Programming Reference
Version 4 Release 1

SC33-1170-03
CICS for MVS/ESA. IBM
Application Programming Reference
Version 4 Release 1

SC33-1170-03
Note!

Before using this information and the product it supports, be sure to read the general information under “Notices” on page vii.

Second edition (April 1997)

This edition applies to Version 4 Release 1 of the IBM licensed program Customer Information Control System/Enterprise Systems
Architecture (CICS/ESA), program number 5655-018, and to all subsequent versions, releases, and modifications until otherwise indicated in
new editions. Consult the latest edition of the applicable IBM system bibliography for current information on this product.

This is the second edition of the Application Programming Reference for CICS/ESA 4.1. It is based on the first edition, SC33-1170-00, which is
now obsolete. Changes from the first edition are marked by the ‘+’ sign to the left of the changes. The vertical lines in the left-hand margins
indicate changes made between the CICS/ESA 3.3 edition and the CICS/ESA 4.1 first edition.

The CICS/ESA 3.3 edition remains applicable and current for users of CICS/ESA 3.3.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address
given below.

At the back of this publication is a page entitled “Sending your comments to IBM”. If you want to make comments, but the methods described
are not available to you, please address them to:

IBM United Kingdom Laboratories Limited, Information Development,

Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate
without incurring any obligation to you.

 Copyright International Business Machines Corporation 1982, 1997. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . vii CONVERSE (3650-3680) . . . . . . . . . . . . . . . . 47
Programming interface information . . . . . . . . . . . . vii CONVERSE (3767) . . . . . . . . . . . . . . . . . . . 47
Trademarks and service marks . . . . . . . . . . . . . . vii CONVERSE (3770) . . . . . . . . . . . . . . . . . . . 48
CONVERSE (3790 full-function or inquiry) . . . . . . . 48
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . ix CONVERSE (3790 3270-display) . . . . . . . . . . . 49
Determining if a publication is current . . . . . . . . . ix CONVERSE (non-VTAM default) . . . . . . . . . . . . 53
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . x CONVERSE (MRO) . . . . . . . . . . . . . . . . . . 53
CICS/ESA 4.1 library . . . . . . . . . . . . . . . . . x CONVERSE (System/3) . . . . . . . . . . . . . . . . 54
Other CICS books . . . . . . . . . . . . . . . . . . . xi CONVERSE (System/7) . . . . . . . . . . . . . . . . 54
Books from related libraries . . . . . . . . . . . . . . . xi CONVERSE (2260) . . . . . . . . . . . . . . . . . . . 55
CONVERSE (2741) . . . . . . . . . . . . . . . . . . . 56
Summary of changes . . . . . . . . . . . . . . . . . xiii CONVERSE (2770) . . . . . . . . . . . . . . . . . . . 57
Changes for the first edition of the CICS/ESA 4.1 book xiii CONVERSE (2780) . . . . . . . . . . . . . . . . . . . 57
| Changes for the second edition of the CICS/ESA 4.1 CONVERSE (3270 display) . . . . . . . . . . . . . . 58
| book . . . . . . . . . . . . . . . . . . . . . . . . . . xiv CONVERSE (3600 BTAM) . . . . . . . . . . . . . . . 58
CONVERSE (3735) . . . . . . . . . . . . . . . . . . . 60
Chapter 1. Commands . . . . . . . . . . . . . . . . . 1 CONVERSE (3740) . . . . . . . . . . . . . . . . . . . 60
Command format . . . . . . . . . . . . . . . . . . . . . 1 DELAY . . . . . . . . . . . . . . . . . . . . . . . . . 65
| CICS syntax notation used in this book . . . . . . . . . 1 DELETE . . . . . . . . . . . . . . . . . . . . . . . . 67
# Possible ABEND AICA timeout . . . . . . . . . . . . . . 2 DELETEQ TD . . . . . . . . . . . . . . . . . . . . . . 70
Argument values . . . . . . . . . . . . . . . . . . . . . 2 DELETEQ TS . . . . . . . . . . . . . . . . . . . . . . 71
| MVS/ESA restrictions . . . . . . . . . . . . . . . . . . . 4 DEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
CICS-value data areas (cvdas) . . . . . . . . . . . . . . 5 DUMP TRANSACTION . . . . . . . . . . . . . . . . . 74
LENGTH options . . . . . . . . . . . . . . . . . . . . . 5 ENDBR . . . . . . . . . . . . . . . . . . . . . . . . . 77
NOHANDLE option . . . . . . . . . . . . . . . . . . . . 5 ENQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
RESP and RESP2 options . . . . . . . . . . . . . . . . 5 ENTER TRACENUM . . . . . . . . . . . . . . . . . . 80
| CICS/ESA interface to JES . . . . . . . . . . . . . . . . 6 EXTRACT ATTACH (LUTYPE6.1) . . . . . . . . . . . 82
| Using the CICS interface to JES . . . . . . . . . . . . . 8 EXTRACT ATTACH (MRO) . . . . . . . . . . . . . . 84
Commands by function . . . . . . . . . . . . . . . . . . 9 EXTRACT ATTRIBUTES (APPC) . . . . . . . . . . . 86
ABEND . . . . . . . . . . . . . . . . . . . . . . . . . 12 EXTRACT ATTRIBUTES (MRO) . . . . . . . . . . . . 87
ADDRESS . . . . . . . . . . . . . . . . . . . . . . . 13 EXTRACT LOGONMSG . . . . . . . . . . . . . . . . 88
ADDRESS SET . . . . . . . . . . . . . . . . . . . . . 15 EXTRACT PROCESS . . . . . . . . . . . . . . . . . 89
ALLOCATE (APPC) . . . . . . . . . . . . . . . . . . 16 EXTRACT TCT . . . . . . . . . . . . . . . . . . . . . 91
ALLOCATE (LUTYPE6.1) . . . . . . . . . . . . . . . 18 FORMATTIME . . . . . . . . . . . . . . . . . . . . . 92
ALLOCATE (MRO) . . . . . . . . . . . . . . . . . . . 20 | FREE . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ASKTIME . . . . . . . . . . . . . . . . . . . . . . . . 21 FREE (APPC) . . . . . . . . . . . . . . . . . . . . . 96
ASSIGN . . . . . . . . . . . . . . . . . . . . . . . . . 22 FREE (LUTYPE6.1) . . . . . . . . . . . . . . . . . . 97
BIF DEEDIT . . . . . . . . . . . . . . . . . . . . . . 30 FREE (MRO) . . . . . . . . . . . . . . . . . . . . . . 98
BUILD ATTACH (LUTYPE6.1) . . . . . . . . . . . . . 31 FREEMAIN . . . . . . . . . . . . . . . . . . . . . . . 99
BUILD ATTACH (MRO) . . . . . . . . . . . . . . . . 33 GDS ALLOCATE . . . . . . . . . . . . . . . . . . . . 102
CANCEL . . . . . . . . . . . . . . . . . . . . . . . . 35 GDS ASSIGN . . . . . . . . . . . . . . . . . . . . . . 104
| CHANGE PASSWORD . . . . . . . . . . . . . . . . . 37 GDS CONNECT PROCESS . . . . . . . . . . . . . . 105
CHANGE TASK . . . . . . . . . . . . . . . . . . . . 38 GDS EXTRACT ATTRIBUTES . . . . . . . . . . . . . 107
CONNECT PROCESS . . . . . . . . . . . . . . . . . 39 GDS EXTRACT PROCESS . . . . . . . . . . . . . . 108
CONVERSE (VTAM default) . . . . . . . . . . . . . . 41 GDS FREE . . . . . . . . . . . . . . . . . . . . . . . 109
CONVERSE (APPC) . . . . . . . . . . . . . . . . . . 41 GDS ISSUE ABEND . . . . . . . . . . . . . . . . . . 110
CONVERSE (LUTYPE2/LUTYPE3) . . . . . . . . . . 42 GDS ISSUE CONFIRMATION . . . . . . . . . . . . . 111
CONVERSE (LUTYPE4) . . . . . . . . . . . . . . . . 42 GDS ISSUE ERROR . . . . . . . . . . . . . . . . . . 112
CONVERSE (LUTYPE6.1) . . . . . . . . . . . . . . . 43 GDS ISSUE PREPARE . . . . . . . . . . . . . . . . 113
CONVERSE (SCS) . . . . . . . . . . . . . . . . . . . 43 GDS ISSUE SIGNAL . . . . . . . . . . . . . . . . . . 114
CONVERSE (3270 logical) . . . . . . . . . . . . . . . 44 GDS RECEIVE . . . . . . . . . . . . . . . . . . . . . 115
CONVERSE (3600-3601) . . . . . . . . . . . . . . . . 44 GDS SEND . . . . . . . . . . . . . . . . . . . . . . . 117
CONVERSE (3600-3614) . . . . . . . . . . . . . . . . 45 GDS WAIT . . . . . . . . . . . . . . . . . . . . . . . 119
CONVERSE (3650 interpreter) . . . . . . . . . . . . . 45 GETMAIN . . . . . . . . . . . . . . . . . . . . . . . . 120
CONVERSE (3650-3270) . . . . . . . . . . . . . . . . 46 HANDLE ABEND . . . . . . . . . . . . . . . . . . . . 123
CONVERSE (3650-3653) . . . . . . . . . . . . . . . . 46 HANDLE AID . . . . . . . . . . . . . . . . . . . . . . 125

 Copyright IBM Corp. 1982, 1997 iii

HANDLE CONDITION . . . . . . . . . . . . . . . . . 127
IGNORE CONDITION . . . . . . . . . . . . . . . . . 129
ISSUE ABEND . . . . . . . . . . . . . . . . . . . . . 130
ISSUE ABORT . . . . . . . . . . . . . . . . . . . . . 131
ISSUE ADD . . . . . . . . . . . . . . . . . . . . . . . 133
ISSUE CONFIRMATION . . . . . . . . . . . . . . . . 135
ISSUE COPY (3270 display) . . . . . . . . . . . . . . 137
ISSUE COPY (3270 logical) . . . . . . . . . . . . . . 138
ISSUE DISCONNECT (default) . . . . . . . . . . . . 139
ISSUE DISCONNECT (LUTYPE6.1) . . . . . . . . . . 140
ISSUE END . . . . . . . . . . . . . . . . . . . . . . . 141
ISSUE ENDFILE . . . . . . . . . . . . . . . . . . . . 143
ISSUE ENDOUTPUT . . . . . . . . . . . . . . . . . . 144
ISSUE EODS . . . . . . . . . . . . . . . . . . . . . . 145
ISSUE ERASE . . . . . . . . . . . . . . . . . . . . . 146
ISSUE ERASEAUP . . . . . . . . . . . . . . . . . . . 148
ISSUE ERROR . . . . . . . . . . . . . . . . . . . . . 149
ISSUE LOAD . . . . . . . . . . . . . . . . . . . . . . 150
ISSUE NOTE . . . . . . . . . . . . . . . . . . . . . . 151
ISSUE PASS . . . . . . . . . . . . . . . . . . . . . . 152
ISSUE PREPARE . . . . . . . . . . . . . . . . . . . 154
ISSUE PRINT . . . . . . . . . . . . . . . . . . . . . . 155
ISSUE QUERY . . . . . . . . . . . . . . . . . . . . . 156
ISSUE RECEIVE . . . . . . . . . . . . . . . . . . . . 157
ISSUE REPLACE . . . . . . . . . . . . . . . . . . . . 159
ISSUE RESET . . . . . . . . . . . . . . . . . . . . . 161
ISSUE SEND . . . . . . . . . . . . . . . . . . . . . . 162
ISSUE SIGNAL (APPC) . . . . . . . . . . . . . . . . 164
ISSUE SIGNAL (LUTYPE6.1) . . . . . . . . . . . . . 165
ISSUE WAIT . . . . . . . . . . . . . . . . . . . . . . 166
LINK . . . . . . . . . . . . . . . . . . . . . . . . . . 168
LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . 172
MONITOR . . . . . . . . . . . . . . . . . . . . . . . 174
POINT . . . . . . . . . . . . . . . . . . . . . . . . . 176
POP HANDL407.52 Tm0.6665 Tc0N8f18.524 Tm0.3885 Tw[( . . . . . . . . . . . . . . . . . . . . .)]TJ9 0 0 9 269.930N8f18.524 Tm0 Tw(774)Tj-25.9983 -1
.
SPOOLOPEN INPUT . . . . . . . . . . . . . . . . . . 294 Appendix J. BMS-related constants . . . . . . . . . 375
SPOOLOPEN OUTPUT . . . . . . . . . . . . . . . . 296 Magnetic slot reader (MSR) control value constants,
SPOOLREAD . . . . . . . . . . . . . . . . . . . . . . 299 DFHMSRCA . . . . . . . . . . . . . . . . . . . . . . 377
SPOOLWRITE . . . . . . . . . . . . . . . . . . . . . 301 MSR control byte values . . . . . . . . . . . . . . . . 377
START . . . . . . . . . . . . . . . . . . . . . . . . . 303 Attention identifier constants, DFHAID . . . . . . . . . 379
STARTBR . . . . . . . . . . . . . . . . . . . . . . . . 309
SUSPEND . . . . . . . . . . . . . . . . . . . . . . . 313 Appendix K. BMS macro summary . . . . . . . . . 381
SYNCPOINT . . . . . . . . . . . . . . . . . . . . . . 314 Mapset, map, and field definition . . . . . . . . . . . . 381
SYNCPOINT ROLLBACK . . . . . . . . . . . . . . . 315 Partition set definition . . . . . . . . . . . . . . . . . . 381
UNLOCK . . . . . . . . . . . . . . . . . . . . . . . . 316 DFHMDF . . . . . . . . . . . . . . . . . . . . . . . . 383
| VERIFY PASSWORD . . . . . . . . . . . . . . . . . 318 DFHMDI . . . . . . . . . . . . . . . . . . . . . . . . 390
WAIT CONVID (APPC) . . . . . . . . . . . . . . . . . 320 DFHMSD . . . . . . . . . . . . . . . . . . . . . . . . 396
WAIT EVENT . . . . . . . . . . . . . . . . . . . . . . 321 DFHPDI . . . . . . . . . . . . . . . . . . . . . . . . . 403
WAIT EXTERNAL . . . . . . . . . . . . . . . . . . . 322 DFHPSD . . . . . . . . . . . . . . . . . . . . . . . . 404
WAIT JOURNALNUM . . . . . . . . . . . . . . . . . 324
WAIT SIGNAL . . . . . . . . . . . . . . . . . . . . . 325 Index . . . . . . . . . . . . . . . . . . . . . . . . . . 405
WAIT TERMINAL . . . . . . . . . . . . . . . . . . . . 326
WAITCICS . . . . . . . . . . . . . . . . . . . . . . . 327
WRITE . . . . . . . . . . . . . . . . . . . . . . . . . 329
WRITE JOURNALNUM . . . . . . . . . . . . . . . . . 332
WRITE OPERATOR . . . . . . . . . . . . . . . . . . 334
WRITEQ TD . . . . . . . . . . . . . . . . . . . . . . 336
WRITEQ TS . . . . . . . . . . . . . . . . . . . . . . 338
XCTL . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Appendix A. EXEC interface block . . . . . . . . . 343

EIB fields . . . . . . . . . . . . . . . . . . . . . . . . 343

Appendix B. Codes returned by ASSIGN . . . . . . 351

ASSIGN TERMCODE . . . . . . . . . . . . . . . . . 351
ASSIGN FCI . . . . . . . . . . . . . . . . . . . . . . 351

Appendix C. Translated code for CICS commands 353

COBOL . . . . . . . . . . . . . . . . . . . . . . . . . 353
C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Assembler language . . . . . . . . . . . . . . . . . . 353

Appendix D. Terminal control . . . . . . . . . . . . 357

Commands and options for terminals and logical units 357
TCAM-supported terminals and logical units . . . . . . 358
BTAM programmable terminals . . . . . . . . . . . . 358
Teletypewriter programming . . . . . . . . . . . . . . 359
Display device operations . . . . . . . . . . . . . . . 360

Appendix E. SAA Resource Recovery . . . . . . . 363

SRRCMT . . . . . . . . . . . . . . . . . . . . . . . . 363
SRRBACK . . . . . . . . . . . . . . . . . . . . . . . 363

Appendix F. Common Programming Interface

Communications (CPI Communications) . . . . . 365

Appendix G. API restrictions for distributed

program link . . . . . . . . . . . . . . . . . . . . . 367
Summary of the restricted API commands . . . . . . . 367
List of API commands . . . . . . . . . . . . . . . . . 367

| Appendix H. CVDA numeric values . . . . . . . . . 371

| Appendix I. National language codes . . . . . . . . 373

Contents v
vi CICS/ESA Application Programming Reference
Notices
The following paragraph does not apply in any country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply to you.

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in
all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The
evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the
responsibility of the user.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information
between independently created programs and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact Laboratory Counsel, MP151, IBM United Kingdom Laboratories, Hursley Park,
Winchester, Hampshire, England SO21 2JN. Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this
document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594, U.S.A..

Programming interface information

This book is intended to help you write application programs using EXEC CICS commands. This book documents General-use
Programming Interface and Associated Guidance Information provided by CICS.

General-use programming interfaces allow the customer to write programs that obtain the services of CICS.

Trademarks and service marks

The following terms, used in this publication, are trademarks or service marks of IBM Corporation in the United States or other
countries:

ACF/VTAM AFP AT
BookManager C/370 CICS
CICS OS/2 CICS/ESA CICS/MVS
CICS/VSE DATABASE 2 DB2
ESA/370 IBM IBMLink
IMS/ESA MVS/ESA MVS/SP
RACF System/370 Systems Application Architecture
SAA SQL/DS VTAM

 Copyright IBM Corp. 1982, 1997 vii

viii CICS/ESA Application Programming Reference
Preface
What this book is about: This book describes the CICS/ESA application programming interface; it contains reference
information needed to prepare COBOL, C, PL/I, and assembler-language application programs, using CICS commands, to be
executed under CICS. Guidance information is in the &dfhpe00l.. For information about debugging CICS applications, see the
CICS/ESA Problem Determination Guide.

Who this book is for: The book is intended primarily for use by application programmers, but will also be useful to system
programmers and systems analysts.

What you need to know to understand this book: We assume that you have some experience in writing programs in
COBOL, C, PL/I, or assembler language. You should also have a knowledge of the CICS concepts and terminology introduced
in the CICS/ESA 3.3 Facilities and Planning Guide and you should have read the CICS Application Programming Primer (VS
COBOL II) and the CICS/ESA Application Programming Guide.

How to use this book: This book is for reference. Each of the commands has a standard format, as follows:
The syntax of the command
A description of what the command does
An alphabetical list of the options and their functions
An alphabetical list of conditions, and their causes, that can occur during execution of a command.

Notes on terminology
ASM is used sometimes as the abbreviation for assembler language.

| What this book does not cover: The EXEC CICS commands for system programming; that is COLLECT, DISABLE,
| ENABLE, INQUIRE, PERFORM, RESYNC, and SET are not covered in this book but you will find them in the CICS/ESA
| System Programming Reference.

The EXEC CICS FEPI commands available for use with the CICS/ESA Front End Programming Interface feature are not
discussed in this book, but in the CICS/ESA Front End Programming Interface Feature User’s Guide.

Determining if a publication is current

IBM regularly updates its publications with new and changed information. When first published, both hardcopy and
BookManager softcopy versions of a publication are in step, but subsequent updates will probably be available in softcopy
before they are available in hardcopy.

For CICS Transaction Server books, these softcopy updates appear regularly on the Transaction Processing and Data
Collection Kit CD-ROM, SK2T-0730-xx. Each reissue of the collection kit is indicated by an updated order number suffix (the
-xx part). For example, collection kit SK2T-0730-06 is more up-to-date than SK2T-0730-05. The collection kit is also clearly
dated on the cover.

Here’s how to determine if you are looking at the most current copy of a publication:
A publication with a higher suffix number is more recent than one with a lower suffix number. For example, the publication
with order number SC33-0667-02 is more recent than the publication with order number SC33-0667-01. (Note that suffix
numbers are updated as a product moves from release to release, as well as for hardcopy updates within a given release.)
When the softcopy version of a publication is updated for a new collection kit the order number it shares with the hardcopy
version does not change. Also, the date in the edition notice remains that of the original publication. To compare softcopy
with hardcopy, and softcopy with softcopy (on two editions of the collection kit, for example), check the last two characters
of the publication’s filename. The higher the number, the more recent the publication. For example, DFHPF104 is more
recent than DFHPF103. Next to the publication titles in the CD-ROM booklet and the readme files, asterisks indicate
publications that are new or changed.
Updates to the softcopy are clearly marked by revision codes (usually a “#” character) to the left of the changes.

 Copyright IBM Corp. 1982, 1997 ix

Bibliography

CICS/ESA 4.1 library

Evaluation and planning
Release Guide GC33-1161 April 1997
Migration Guide GC33-1162 April 1997

General
CICS Family: Library Guide GC33-1226 April 1995
Master Index SC33-1187 October 1994
User’s Handbook SX33-1188 April 1997
Glossary (softcopy only) GC33-1189 n/a

Administration
Installation Guide GC33-1163 April 1997
System Definition Guide SC33-1164 April 1997
Customization Guide SC33-1165 April 1997
Resource Definition Guide SC33-1166 April 1997
Operations and Utilities Guide SC33-1167 April 1997
CICS-Supplied Transactions SC33-1168 April 1997

Programming
Application Programming Guide SC33-1169 October 1994
Application Programming Reference SC33-1170 April 1997
System Programming Reference SC33-1171 April 1997
Sample Applications Guide SC33-1173 October 1994
Distributed Transaction Programming Guide SC33-1174 October 1994
Front End Programming Interface User’s Guide SC33-1175 October 1994

Diagnosis
Problem Determination Guide SC33-1176 October 1994
Messages and Codes GC33-1177 April 1997
Diagnosis Handbook LX33-6093 October 1994
Diagnosis Reference LY33-6082 April 1997
Data Areas LY33-6083 April 1997
Supplementary Data Areas LY33-6081 October 1994
Closely-Connected Program Interface LY33-6084 November 1996

Communication
Intercommunication Guide SC33-1181 April 1997
Server Support for CICS Clients SC33-1591 February 1996
CICS Family: Inter-product Communication SC33-0824 October 1996
CICS Family: Communicating from CICS on System/390 SC33-1697 October 1996

Special topics
Recovery and Restart Guide SC33-1182 October 1994
Performance Guide SC33-1183 October 1994
CICS-IMS Database Control Guide SC33-1184 October 1994
CICS-RACF Security Guide SC33-1185 October 1994
Shared Data Tables Guide SC33-1186 October 1994
External CICS Interface SC33-1390 April 1997
CICS ONC RPC Feature for MVS/ESA Guide SC33-1119 February 1996
CICS Web Interface Guide SC33-1892 November 1996

The book that you are reading was republished in hardcopy format in April 1997 to incorporate updated information previously
available only in softcopy. The right-hand column in the above table indicates the latest hardcopy editions of the CICS/ESA
books available in April 1997. A book with a date earlier than April 1997 remains the current edition for CICS/ESA 4.1. Note
that it is possible that other books in the library will be updated after April 1997.

When a new order is placed for the CICS/ESA 4.1 product, the books shipped with that order will be the latest hardcopy
editions.

The style of IBM covers changes periodically. Books in this library have more than one style of cover.

For information about the softcopy books, see “Determining if a publication is current” on page ix. The softcopy books are
regularly updated to include the latest information.

x CICS/ESA Application Programming Reference

Other CICS books
CICS Application Migration Aid Guide, SC33-0768
CICS Application Programming Primer (VS COBOL II), SC33-0674
CICS/ESA Facilities and Planning Guide for CICS/ESA Version 3 Release 3, SC33-0654
CICS/ESA XRF Guide for CICS/ESA Version 3 Release 3, SC33-0661
CICS Family: API Structure, SC33-1007
CICS Family: General Information, GC33-0155
IBM CICS Transaction Affinities Utility MVS/ESA, SC33-1159

CICS Clients
CICS Clients: Administration, SC33-1436
CICS Family: Client/Server Programming, SC33-1435
These books contain information about IMS application
Books from related libraries programming for CICS users, and tell you how to write
online, batch, or CICS shared database programs that use
MVS: see the following books:
the EXEC DLI interface or the DL/I CALL interface with the
MVS/ESA System Programming Library: Application DL/I interface block (DIB). If you use the DL/I CALL interface
Development 31-Bit Addressing, GC28-1820 with the TCA, you should see the CICS/OS/VS Version 1
MVS/ESA System Programming Library: Application Release 7 Application Programmer’s Reference Manual
Development Guide, GC28-1821 (Macro Level).
MVS/ESA System Programming Library: System
Note: The EXEC DLI interface is no longer documented in
Generation, GC28-1825
the CICS/ESA Application Programming Reference.
MVS/ESA System Programming Library: Initialization
and Tuning, GC28-1828 Systems Network Architecture: See the following
MVS/ESA System Programming Library: Application Systems Network Architecture (SNA) book for further
Development Guide, GC28-1852 information about SNA:
MVS/ESA System Programming Library: Application
Development Guide - Extended Addressability, Sessions between Logical Units, GC20-1868.
GC28-1854
MVS/ESA System Programming Library: Application Systems Application Architecture: See the following
Development Macro Reference, GC28-1857 Systems Application Architecture (SAA) for further
| MVS/ESA JCL User’s Guide, GC28-1473 information about SAA:
| MVS/ESA Operations: Systems Commands, GC28-1826 SAA Common Programming Interface Communications
ESA/370 Principles of Operation, SA22-7200. Reference, SC26-4399.

Data facility product: SQL: For information about executing SQL in a CICS
MVS/ESA Data Administration: Macro Instruction application program see the following books:
Reference, SC26-4506 IBM DATABASE 2 Application Programming Guide for
MVS/ESA VSAM Administration: Macro Instruction CICS Users, SC26-4080
Reference, SC26-4517 IBM DATABASE 2 Reference, SC26-4078.
MVS/ESA VSAM Administration Guide, SC26-4518.
Other related books: You may also want to refer to the
IMS: For information about IMS, see the following books. following IBM books:
If you use the CICS-DL/I interface, see one of the following
IMS books: Distributed Processing Programming Executive/Distributed
Presentation Services (DPPX/DPS):
IMS/VS Version 2 Application Programming for
CICS/OS/VS Users, SC26-4177 DPPX/Distributed Presentation Services Version 2
IMS Application Programming: Design Guide, System Programming Guide, SC33-0117
SC26-4279
IMS Application Programming: EXEC DLI Commands OS/VS COBOL Compiler and Library Programmer’s Guide,
manual, SC26-4280 SC28-6483
IMS Application Programming: DL/I Calls manual,
VS COBOL II Application Programming Guide, SC26-4045
SC26-4274.
OS PL/I Version 2 Programming Guide, SC26-4307

Preface xi
An Introduction to the IBM 3270 Information Display System,
GA27-2739

3274 Control Unit Reference Summary, GX20-1878.

Component Description: IBM 2721 Portable Audio Terminal,

GA27-3029.

IBM 2780 Data Transmission Terminal Component

Description, GA27-3035

CICS/OS/VS IBM 3270 Data Stream Device Guide,

SC33-0232

IBM 3270 Data Stream Programmer’s Reference, GA23-0059

CICS/OS/VS IBM 4700/3600/3630 Guide, SC33-0233

xii CICS/ESA Application Programming Reference

 Copyright IBM Corp. 1982, 1997 xiii

| Changes for the second edition of the

| CICS/ESA 4.1 book
| Changes that were made for the first edition are still indicated
| by vertical bars to the left of the changes.
| Changes made for this second edition are indicated by the ‘+’
| symbol to the left of the changes.
| Users of the first edition can therefore see what has changed since
| that first edition was published.
| Softcopy versions of this book use both these revision indicators and
| use the ‘#’ symbol to show further changes since this second
| hardcopy edition of the book was published.

xiv CICS/ESA Application Programming Reference

Chapter 1. Commands
This book shows the syntax of each command, describes the
purpose and format of each command and its options, and | CICS syntax notation used in this book
gives a list of the conditions that can arise during the
| In the CICS books, CICS commands are presented in a
execution of a command.
| standard way.
Note: The INQUIRE and SET commands of the application
programming interface (API) are primarily for the use of the | The “EXEC CICS” that always precedes each command’s
system programmer; they are not described in this book. For | keyword is not included; nor is the “END-EXEC” statement
details of the commands, refer to the CICS/ESA System | used in COBOL or the semicolon (;) used in PL/I and C that
Programming Reference. | you must code at the end of each CICS command. In the C
| language, a null character can be used as an end-of-string
For information about translating the commands, see the | marker, but CICS does not recognize this; you must
CICS/ESA Application Programming Guide for translator | therefore never have a comma or period followed by a space
options, and the CICS/ESA System Definition Guide for the | (X'40') in the middle of a coding line.
JCL.
| You interpret the syntax by following the arrows from left to
| right. The conventions are:
Command format
| Symbol Action
|
The general format of a CICS command is EXECUTE CICS || ──┬─A─┬─────" A set of alternatives—one of which you
(or EXEC CICS) followed by the name of the required | ├─B─┤ must code.
command, and possibly by one or more options, as follows: | └─C─┘
|
EXEC CICS command option(arg).... || ──┬───┬─────" A set of alternatives—one of which you
| ├─A─┤ may code.
where: | ├─B─┤
| └─C─┘
|
command describes the operation required (for example, || A set of alternatives—any number of
┌──
─────┐
READ). | ───*┬───┬┴───" which you may code once.
option describes any of the many optional facilities | ├─A─┤
| ├─B─┤
available with each function. Some options are | └─C─┘
|
followed by an argument in parentheses. You || Alternatives where A is the default.
┌─A─┐
can write options (including those that require | ──┼───┼─────"
arguments) in any order. | └─B─┘
|
arg (short for argument) is a value such as || ──┤ Name ├──" Use with the named section in place of its
“data-value” or “name”. A “data-value” can be a | name.
| Name:
constant, this means that an argument that | ├──A──┬───┬────┤
sends data to CICS is generally a “data-value”. | └─B─┘
An argument that receives data from CICS must | Punctuation and Code exactly as shown.
be a “data-area”. | uppercase
| Some arguments described as “data-area” can | characters
| both send and receive data (such as LENGTH). | Lowercase Code your own text, as appropriate (for
| In these cases, you must ensure that the | characters example, name).
| “data-area” is not in protected storage.
| For example, with READ FILE(filename) you must code READ
An example of a CICS command is as follows: | FILE and () unchanged, but are free to code any valid text
EXEC CICS READ | string to mean the name of the file.
FILE('FILEA')
INTO(FILEA) # Apar 80057
RIDFLD(KEYNUM)
# Documentation for Apar 80057 added 29 Feb 1996
UPDATE
# (TUCKER)
You must add the appropriate end-of-command delimiter; see
“CICS syntax notation used in this book.”

 Copyright IBM Corp. 1982, 1997 1

“ptr-ref” can be replaced by the name of any BLL cell.
# Possible ABEND AICA timeout In VS COBOL II, you can replace “ptr-ref” with a pointer
variable or an ADDRESS special register.
# A task can be abended by CICS if it has been running for
# longer than the runaway time, ICVR, specified in the system “name” can be replaced by either of the following:
# initialization table (SIT). This abend can be prevented by – A character string in single quotation marks (that is,
# coding an EXEC CICS SUSPEND command in the a nonnumeric literal). If this is shorter than the
# application. This causes the dispatcher to suspend the task required length, it is padded with blanks.
# that issued the request and allow any task of higher priority
# to run. If there is no task ready to run, the program that – A COBOL data area with a length equal to the
# issued the suspend is resumed. For further information length required for the name. The value in
# about abend AICA, see the Problem Determination Guide. “data-area” is the name to be used by the argument.
If “data-area” is shorter than the required length, the
excess characters are undefined.
Argument values “filename”, as used in FILE(filename), specifies the
name of the file. It has 1–8 characters from A–Z, 0–9,
The parenthesized argument values that follow options in a $, @, and #, (lowercase characters are converted to
CICS command are specified as follows: uppercase).
data-value “systemname”, as used in SYSID(systemname),
data-area specifies the name of the system the request is directed
cvda (CICS-value data area) to. It has 1–4 characters from A–Z, 0–9, $, @, and #,
ptr-value (lowercase characters are converted to uppercase).
ptr-ref “label” can be replaced by any COBOL paragraph name
name or a section name.
label
hhmmss “hhmmss” can be replaced by a decimal constant or by
| filename a data name of the form PIC S9(7) COMP-3. The value
| systemname must be of the form 0HHMMSS+ where:
HH represents hours from 00 through 99
MM represents minutes from 00 through 59
COBOL argument values
SS represents seconds from 00 through 59.
The argument values can be replaced as follows:
“data-value” can be replaced by any COBOL data name In OS/VS COBOL, you must code the LENGTH options. In
of the correct data type for the argument, or by a VS COBOL II there is no need to code the LENGTH option
constant that can be converted to the correct type for the unless you want the program to read or write data of a length
argument. The data type can be specified as one of the different from that of the referenced variable.
following:
– Halfword binary — PIC S9(4) COMP C argument values
– Fullword binary — PIC S9(8) COMP The argument values can be replaced as follows:
– Character string — PIC X(n) where “n” is the
“data-value” can be replaced by any C expression that
number of bytes.
can be converted to the correct data type for the
“data-area” can be replaced by any COBOL data name argument. The data type can be specified as one of the
of the correct data type for the argument. The data type following:
can be specified as one of the following:
– Halfword binary — short int
– Halfword binary — PIC S9(4) COMP – Fullword binary — long int
– Fullword binary — PIC S9(8) COMP – Character string — char[n] where “n” is the number
– Character string — PIC X(n) where “n” is the of bytes.
number of bytes.
“data-value” includes “data-area” as a subset.
Where the data type is unspecified, “data-area” can refer
“data-area” can be replaced by any C data reference
to an elementary or group item.
that has the correct data type for the argument. The
“cvda” is described in “CICS-value data areas (cvdas)” data type can be specified as one of the following:
on page 5.
– Halfword binary — short int
“ptr-value” can be replaced by the name of any base – Fullword binary — long int
locator for linkage (BLL) cell, or by any COBOL data – Character string — char[n] where “n” is the number
name that contains a copy of such a pointer in a BLL of bytes.
cell.

2 CICS/ESA Application Programming Reference

If the data type is unspecified, “data-area” can refer to a “data-value” includes “data-area” as a subset.
scalar data type, array, or structure. The reference must
“data-area” can be replaced by any PL/I data reference
be to contiguous storage.
that has the correct data type for the argument. The
“cvda” is described in “CICS-value data areas (cvdas)” data type can be specified as one of the following:
on page 5.
– Halfword binary — FIXED BIN(15)
“ptr-value” (which includes “ptr-ref” as a subset) can be – Fullword binary — FIXED BIN(31)
replaced by any C expression that can be converted to – Character string — CHAR(n) where “n” is the
an address. number of bytes.
“ptr-ref” can be replaced by any C pointer type If the data type is unspecified, “data-area” can refer to
reference. an element, array, or structure; for example,
FROM(P–>STRUCTURE) LENGTH(LNG). The
“name” can be replaced by either of the following:
reference must be to connected storage.
– A character string in double quotation marks (that is,
The data area must also have the correct PL/I alignment
a literal constant).
attribute: ALIGNED for binary items, and UNALIGNED
– A C expression or reference whose value can be for strings.
converted to a character array with a length equal to
If you use a varying data string without an explicit length,
the maximum length allowed for the name. The
the data passed begins with two length bytes, and its
value of the character array is the name to be used
length is the maximum length declared for the string. If
by the argument.
you explicitly specify a length in the command, the data
“filename”, as used in FILE(filename), specifies the passed has this length; that is, the two length bytes
name of the file. It has 1–8 characters from A–Z, 0–9, followed by data up to the length you specified.
$, @, and #, (lowercase characters are converted to
“cvda” is described in “CICS-value data areas (cvdas)”
uppercase).
on page 5.
“systemname”, as used in SYSID(systemname),
“ptr-value” (which includes “ptr-ref” as a subset) can be
specifies the name of the system the request is directed
replaced by any PL/I expression that can be converted
to. It has 1–4 characters from A–Z, 0–9, $, @, and #,
to POINTER.
(lowercase characters are converted to uppercase).
“ptr-ref” can be replaced by any PL/I reference of type
“hhmmss” is not supported in the C language.
POINTER ALIGNED.
“label” is not supported in the C language.
“name” can be replaced by either of the following:
| “hhmmss” can be replaced by an integer constant;
– A character string in single quotation marks (that is,
| otherwise the application is responsible for ensuring that
a literal constant).
| the value passed to CICS is in packed decimal format.
| The language does not provide a packed decimal type. – A PL/I expression or reference whose value can be
converted to a character string with a length equal
| HH represents hours from 00 through 99
to the maximum length allowed for the name. The
| MM represents minutes from 00 through 59
value of the character string is the name to be used
| SS represents seconds from 00 through 59.
by the argument.
Many commands involve the transfer of data between the “filename”, as used in FILE(filename), specifies the
application program and CICS. name of the file. It has 1–8 characters from A–Z, 0–9,
$, @, and #, (lowercase characters are converted to
In most cases, the LENGTH option must be specified if SET
uppercase).
is used; the syntax of each command and its associated
options show whether or not this rule applies. “systemname”, as used in SYSID(systemname),
specifies the name of the system the request is directed
to. characters from A–Z, 0–9, $, @, and #, (lowercase
PL/I argument values characters are converted to uppercase).
The argument values can be replaced as follows:
“label” can be replaced by any PL/I expression whose
“data-value” can be replaced by any PL/I expression that value is a label.
can be converted to the correct data type for the
“hhmmss” can be replaced by a decimal constant or an
argument. The data type can be specified as one of the
expression that can be converted to a FIXED
following:
DECIMAL(7,0). The value must be of the form
– Halfword binary — FIXED BIN(15) 0HHMMSS+ where:
– Fullword binary — FIXED BIN(31)
HH represents hours from 00 through 99
– Character string — CHAR(n) where “n” is the
MM represents minutes from 00 through 59
number of bytes.
SS represents seconds from 00 through 59.

Chapter 1. Commands 3
If the UNALIGNED attribute is added to the ENTRY string. The length is equal to the maximum length
declarations generated by the CICS translator by a allowed for the name. The value of the character string
DEFAULT DESCRIPTORS statement, data-area or is the name to be used by the argument.
pointer-reference arguments to CICS commands must also
“filename”, as used in FILE(filename), specifies the
be UNALIGNED. Similarly for the ALIGNED attribute,
name of the file. It has 1–8 characters from A–Z, 0–9,
data-area or pointer-reference arguments must be ALIGNED.
$, @, and #, (lowercase characters are converted to
uppercase).
Many commands involve the transfer of data between the
application program and CICS. “systemname”, as used in SYSID(systemname),
specifies the name of the system the request is directed
In most cases, the length of the data to be transferred must to. It has 1–4 characters from A–Z, 0–9, $, @, and #,
be provided by the application program. However, if a data (lowercase characters are converted to uppercase).
area is specified as the source or target, it is not necessary
“label” refers to a destination address to which control is
to provide the length explicitly, because the
transferred. It can be replaced by the label of the
command-language translator generates a default length
destination instruction or by the label of an address
value of either STG(data-area) or CSTG(data-area), as
constant for the destination. This constant must not
appropriate.
specify a length.
You can also use the expression =A(dest) where “dest”
Assembler-language argument values is a relocatable expression denoting the destination.
In general, an argument may be either the address of the For example, the following commands are equivalent:
data or the data itself (in assembler-language terms, either a HANDLE CONDITION ERROR(DEST)
relocatable expression or an absolute expression). HANDLE CONDITION ERROR(ADCON)
HANDLE CONDITION ERROR(=A(DEST))
A relocatable expression must not contain unmatched ..
.
brackets (outside quotation marks) or unmatched quotation DEST BR 14
marks (apart from length-attribute references). If this rule is ADCON DC A(DEST)
obeyed, any expression can be used, including literal
constants, such as =AL2(100), forms such as 20(0,R11), and “hhmmss” can be replaced by a self-defining decimal
forms that use the macro-replacement facilities. constant, or an assembler-language reference to a field
defined as PL4. The value must be of the form
An absolute expression must be a single term that is either a 0HHMMSS+ where:
length-attribute reference, or a self-defining constant. HH represents hours from 00 through 99
MM represents minutes from 00 through 59
Care must be taken with equated symbols, which should be
SS represents seconds from 00 through 59.
used only when referring to registers (pointer references). If
an equated symbol is used for a length, for example, it is Many commands involve the transfer of data between the
treated as the address of the length and an unpredictable application program and CICS.
error occurs.
In most cases, the length of the data to be transferred must
The argument values can be replaced as follows: be provided by the application program. However, if a data
“data-value” can be replaced by a relocatable expression area is specified as the source or target, it is not necessary
that is an assembler-language reference to data of the to provide the length explicitly, because the
correct type for the argument, or by a constant of the command-language translator generates a default length.
correct type for the argument.
For example:
“data-area” can be replaced by a relocatable expression
xxx DC CL8
that is an assembler-language reference to data of the
.
correct type for the argument.
.
“cvda” is described in “CICS-value data areas (cvdas)” EXEC CICS ... LENGTH(L'xxx)
on page 5.
“ptr-value” can be replaced by an absolute expression
that is an assembler-language reference to a register. | MVS/ESA restrictions
“ptr-ref” can be replaced by an absolute expression that | The following general restrictions apply to all CICS
is an assembler-language language reference to a | commands:
register.
| The restrictions that apply to CICS commands that access
“name” can be replaced either by a character string in | user
single quotation marks, or by an assembler-language
language relocatable expression reference to a character | The program must be in primary addressing mode when

4 CICS/ESA Application Programming Reference

| invoking any CICS service. The primary address space practice (depending on issues of recoverability, function
| must be the home address space. All parameters shipping, and so on), the achievable upper limit varies from
| passed to CICS must reside in the primary address command to command, but is somewhat less than this
| space. theoretical maximum.
| CICS does not always preserve access registers across
# To be safe, do not let the value assigned to the length option
| CICS commands or macro invocations. If your program
# for any CICS command exceed 24KB.
| uses access registers, it should save them before
| invoking a CICS service, and restore them before For journaled items, the length may be further restricted by
| reusing them. the buffer size of the journal.

For journal commands, the restrictions apply to the sum of

CICS-value data areas (cvdas) the LENGTH and PFXLENG values.

There are options on a number of commands that describe # For transient data, and file control commands, the data set
or define a resource. CICS supplies, in CICS-value data definitions may themselves impose further restrictions.
areas, the values associated with these options. The options
are shown in the syntax of the commands with the term
“cvda” in parentheses. NOHANDLE option
You pass a cvda value in two different ways: You can use the NOHANDLE option with any command to
specify that you want no action to be taken for any condition
You can assign a cvda value with the translator routine
| or AID resulting from the execution of that command. For
DFHVALUE. This allows you to change a cvda value in
| further information about the NOHANDLE option, see the
the program as the result of other run-time factors.
| CICS/ESA Application Programming Guide.
For example:
MOVE DFHVALUE(NOTPURGEABLE) TO AREA-A. | Note that using the C language implies NOHANDLE on all
EXEC CICS WAIT EXTERNAL ECBLIST() NUMEVENTS() | commands.
PURGEABILITY(AREA-A).
If the required action is always the same, you can
declare the value directly. RESP and RESP2 options
For example: You can use the RESP option with any command to test
EXEC CICS WAITCICS ECBLIST() NUMEVENTS() PURGEABLE. whether a condition was raised during its execution. With
some commands, when a condition can be raised for more
You receive a cvda value by defining a fullword binary data | than one reason, you can, if you have already specified
area and then testing the returned value with the translator | RESP, use the RESP2 option to determine exactly why a
routine DFHVALUE. For example: condition occurred.
EXEC CICS CONNECT PROCESS .... STATE(AREA-A) RESP(xxx)
IF AREA-A = DFHVALUE(ALLOCATED) .... “xxx” is a user-defined fullword binary data area. On
IF AREA-A = DFHVALUE(CONFFREE) ....
return from the command, it contains a value
corresponding to the condition that may have been
raised, or to a normal return, that is,
LENGTH options xxx=DFHRESP(NORMAL). You can test this value by
means of DFHRESP, as follows:
In VS COBOL II, PL/I, and assembler language, the
translator defaults certain lengths, # EXEC CICS WRITEQ TS FROM(abc)
# QUEUE(qname)
# Apar PQ06624 # NOSUSPEND
# RESP(xxx)
# Documentation for Apar PQ06624 added 20/08/97 # RESP2(yyy)
# .
# .
# if the NOLENGTH translator option is not specified. This # IF xxx=DFHRESP(NOSPACE) THEN ...
means they are optional in programs that specify data areas.
The above form of DFHRESP applies to both COBOL
In OS/VS COBOL and C, all LENGTH options must be and PL/I.
specified. An example of a similar test in C:
When a CICS command offers the LENGTH option, it is
generally expressed as a signed halfword binary value. This
puts a theoretical upper limit of 32 763 bytes on LENGTH. In

Chapter 1. Commands 5
switch (xxx) { | JES2
case DFHRESP(NORMAL) : break;
case DFHRESP(INVREQ) : Invreq_Cond(); | Number of SYSOUT data sets
break; | There is an upper limit to the number of data sets
default : Errors(); | that can be created by a single job. If this limit is
} | exceeded during a CICS run, subsequent
An example of a similar test in assembler language: | SPOOLOPEN OUTPUT requests return the
| ‘ALLOCERR’ condition.
CLC xxx,DFHRESP(NOSPACE)
| Output queue and job queue sizes
which the translator changes to:
CLC xxx,=F'18' | The number of Job Output Elements and Job Queue
| Elements may need to be increased to
As the use of RESP implies NOHANDLE, you must be | accommodate the additional output processing.
careful when using RESP with the RECEIVE command, | Timely processing of the data sets created using this
because NOHANDLE overrides the HANDLE AID | interface minimizes this requirement.
command as well as the HANDLE CONDITION
command, with the result that PF key responses are | Spool space
ignored. | Although the spool space for a data set created
| using this interface is reused after it has been
RESP2(yyy)
| processed, some control information is retained for
“yyy” is a user-defined fullword binary data area. On
| the life of the job. You may have to increase the
return from the command, it contains a value that further
| spool file allocation to allow for this.
qualifies the response to certain commands. Unlike the
RESP values, RESP2 values have no associated
symbolic names and there is no translator built-in | JES3
function corresponding to DFHRESP, so you must test
| Job queue size
the fullword binary value itself. RESP2 values are given
in the description of each command that returns them. | The number of Job Queue Elements may need to be
| increased to accommodate the additional output
| processing. Also, more JSAM buffers may be
| CICS/ESA interface to JES | required. Timely processing of the data sets created
| using this interface minimizes this requirement.
| The CICS interface to JES (the Job Entry Subsystem | Spool space
| component of MVS) provides specialist programmer EXEC
| commands for accessing the system spool files maintained | Although the spool space for a data set created
| by JES2 and JES3. You can support the requirements of | using this interface is reused after it has been
| other products to exchange files with other systems | processed, some control information is retained for
| connected through a JES remote spooling communications | the life of the job. You may have to increase the
| subsystem (RSCS) network. The term JES is used to refer | spool file allocation to allow for this.
| to both JES2 and JES3.

| The CICS interface to JES enables you to:

| Retrieve data for a specific user from the local JES
| spool. See Figure 1 on page 7.
| Create a file and write records directly to the local JES
| spool. See Figure 2 on page 7.
| Send a JES spool file to a specific remote destination.
| See Figure 3 on page 7.

| There are internal limits in JES2 and JES3 that you should
| consider when you are designing applications to use this
| interface. Some of these internal limits can depend on which
| release of JES you are using. You should therefore read the
| following in conjunction with the appropriate JES
| documentation.

6 CICS/ESA Application Programming Reference

MVS

SPOOLOPEN OUTPUT
USERID('*') NODE('*')
CICS JES
TOKEN JES SPOOL
SPOOLWRITE TOKEN

SPOOLWRITE TOKEN

SPOOLCLOSE TOKEN

| Figure 1. Retrieve data from the JES spool

MVS VM1

RSCS
CICS JES
JES SPOOL

SPOOLOPEN
OUTPUT
USERID ('USER1')
NODE ('VM1')

USER1

# Figure 2. Create a file and write directly to the JES spool

MVS
SPOOLOPEN INPUT
USERID('SYS1CICS')
VM1
CICS JES TOKEN
RSCS
SPOOLREAD TOKEN JES SPOOL

RECORD
CP TAG DEV PUN
Data Set NODE('MVS')
Name USERID('SYS1CICS')

SPOOLREAD TOKEN

ENDFILE RESP

SPOOLCLOSE TOKEN

# Figure 3. Send the written file to a remote destination

| For both JES2 and JES3, some performance degradation
| can be experienced if a backlog of CICS-created data sets is
| allowed to accumulate. You should ensure that procedures
| exist to detect and remedy such situations.

Chapter 1. Commands 7
| transaction using the interface, their files can be
| Using the CICS interface to JES | differentiated by using different writer names or different
| classes within a single writer name. Furthermore, you should
| To use the CICS interface to JES, you must code DFHSIT
| ensure that the transactions either terminate or wait for a
| SPOOL=YES.
| short period between SPOOLCLOSE and a subsequent
| You must specify RESP or NOHANDLE on the EXEC CICS | SPOOLOPEN. If you do not do this, one transaction can
| SPOOLCLOSE, SPOOLOPEN, SPOOLREAD, and | prevent others from using the interface.
| SPOOLWRITE commands. RESP bears a one-to-one
| correspondence with HANDLE CONDITION. If you do not | JES exits
| code RESP, your program abends. You can also code the
| Both JES2 and JES3 provide a way of screening incoming
| RESP2 option.
| files. For JES2, the TSO/E Interactive Data Transmission
| NOHANDLE, RESP, and RESP2 are not shown in the syntax | Facility Screening and Notification exit is used. The JES3
| boxes or in the option lists for the EXEC CICS SPOOL | equivalent is the Validate Incoming Netdata File exit.
| commands described in this manual. At the end of the
| You should review any use your installation makes of these
| description of each spool command, there is a list of RESP
| exits to ensure that files that are to be read using the CICS
| values and the RESP2 values that are specific to the
| interface to JES are correctly processed.
| CICS-JES interface.

| Transactions that process SYSOUT data sets larger than | Output

| 1000 records, either for INPUT or for OUTPUT, are likely to
| have a performance impact on the rest of CICS. When you | The transaction program issues SPOOLOPEN to allocate an
| cannot avoid such a transaction, you should carefully | output data set, specifying a remote NODE and USERID.
| evaluate general system performance. You should introduce | SPOOLOPEN returns a unique token to the transaction,
| a pacing mechanism if the effects on the rest of CICS are | which must be used in all subsequent SPOOLWRITE and
| unacceptable. | SPOOLCLOSE commands to identify the file being written to.
| Finally, the transaction issues SPOOLCLOSE to close and
| All access to a JES spool file must be completed within one | deallocate the report, and permit its immediate printing or
| logical unit of work. Issuing an EXEC CICS SYNCPOINT | onward routing by the system spooler. The normal response
| command implicitly issues a SPOOLCLOSE command for | received from the SPOOLOPEN OUTPUT command is:
| any open report.
| The file is allocated to you and identified by the
| token returned by CICS.
| Input | Data can now be written to it.
| A remote application must route any files intended for a
If the node is a remote MVS system, the data set is queued
| CICS transaction to a specific user name at the system
| on the JES spool against the destination userid. The ID of
| where CICS resides. See Figure 1 on page 7 for an
| this destination user was specified on the SPOOLOPEN
| example of a CP command used by a VM system to do this.
| OUTPUT USERID parameter. If the node is a remote VM
| The figure also shows the EXEC CICS SPOOL commands
system, the data is queued in the VM RDR queue for the ID
| you use to retrieve the data.
that was specified on the same USERID parameter.
| The CICS transaction issues the SPOOLOPEN command,
| specifying the writer name on the USERID parameter and
| optionally the class of output within the writer name. The
| normal response is:
| 1. No input for this external writer.
| 2. The single-thread is busy (see below).
| 3. The file is allocated to you for retrieval, and is identified
| by the “token” returned by CICS. The token must be
| included on every SPOOL command for retrieving the
| data set.

| In cases (1) and (2), the transaction should retry the

| SPOOLOPEN after a suitable interval, by restarting itself.

| In case (3), the transaction should then retrieve the file with
| SPOOLREAD commands, and proceed to SPOOLCLOSE as
| rapidly as possible to release the path for other users. This
| is especially important for input from JES because the input
| path is single-threaded. When there is more than one

8 CICS/ESA Application Programming Reference

Commands by function Batch data interchange
ISSUE ABORT
The following is a list of EXEC CICS commands categorized ISSUE ADD
according to the function they perform. ISSUE END
ISSUE ERASE
ISSUE NOTE
Abend support
ISSUE QUERY
ABEND ISSUE RECEIVE
HANDLE ABEND ISSUE REPLACE
ISSUE SEND
ISSUE WAIT
APPC basic conversation
GDS ALLOCATE
GDS ASSIGN BMS
GDS CONNECT PROCESS PURGE MESSAGE
GDS EXTRACT ATTRIBUTES RECEIVE MAP
GDS EXTRACT PROCESS RECEIVE PARTN
GDS FREE ROUTE
GDS ISSUE ABEND SEND CONTROL
GDS ISSUE CONFIRMATION SEND MAP
GDS ISSUE ERROR SEND PAGE
GDS ISSUE PREPARE SEND PARTNSET
GDS ISSUE SIGNAL SEND TEXT
GDS RECEIVE SEND TEXT MAPPED
GDS SEND SEND TEXT NOEDIT
GDS WAIT

Built-in functions
APPC mapped conversation
BIF DEEDIT
ALLOCATE (APPC)
CONNECT PROCESS
CONVERSE (APPC) Console support
EXTRACT ATTRIBUTES (APPC) WRITE OPERATOR
EXTRACT PROCESS
FREE (APPC)
ISSUE ABEND Diagnostic services
ISSUE CONFIRMATION DUMP TRANSACTION
ISSUE ERROR ENTER TRACENUM
ISSUE PREPARE
ISSUE SIGNAL (APPC)
RECEIVE (APPC) Environment services
SEND (APPC) ADDRESS
WAIT CONVID ADDRESS SET
ASSIGN
Authentication
| CHANGE PASSWORD Exception support
SIGNOFF HANDLE CONDITION
SIGNON IGNORE CONDITION
| VERIFY PASSWORD POP HANDLE
PUSH HANDLE

Chapter 1. Commands 9
File control Syncpoint
DELETE SYNCPOINT
ENDBR SYNCPOINT ROLLBACK
READ
READNEXT
READPREV
Task control
RESETBR CHANGE TASK
REWRITE DEQ
STARTBR ENQ
UNLOCK SUSPEND
WRITE WAIT EXTERNAL
WAITCICS

Interval control
ASKTIME
Temporary storage control
CANCEL DELETEQ TS
DELAY READQ TS
FORMATTIME WRITEQ TS
POST
RETRIEVE
START
Terminal control
WAIT EVENT ALLOCATE (LUTYPE6.1)
ALLOCATE (MRO)
BUILD ATTACH (LUTYPE6.1)
Journaling BUILD ATTACH (MRO)
WAIT JOURNALNUM CONVERSE (default)
WRITE JOURNALNUM CONVERSE (LUTYPE2/LUTYPE3)
CONVERSE (LUTYPE4)
CONVERSE (LUTYPE6.1)
Monitoring CONVERSE (MRO)
MONITOR CONVERSE (SCS)
CONVERSE (System/3)
CONVERSE (System/7)
Program control CONVERSE (2260)
LINK CONVERSE (2741)
LOAD CONVERSE (2770)
RELEASE CONVERSE (2780)
RETURN CONVERSE (3270 display)
XCTL CONVERSE (3270 logical)
CONVERSE (3600 BTAM)
CONVERSE (3600-3601)
Security CONVERSE (3600-3614)
QUERY SECURITY CONVERSE (3650 interpreter)
CONVERSE (3650-3270)
CONVERSE (3650-3653)
| Spool Interface (JES) CONVERSE (3650-3680)
| SPOOLCLOSE CONVERSE (3735)
| SPOOLOPEN INPUT CONVERSE (3740)
| SPOOLOPEN OUTPUT CONVERSE (3767)
| SPOOLREAD CONVERSE (3770)
| SPOOLWRITE CONVERSE (3790 full-function or inquiry)
CONVERSE (3790 3270-display)
EXTRACT ATTACH (LUTYPE6.1)
Storage control EXTRACT ATTACH (MRO)
FREEMAIN EXTRACT ATTRIBUTES (MRO)
GETMAIN EXTRACT LOGONMSG
EXTRACT TCT
FREE (LUTYPE6.1)
| FREE

10 CICS/ESA Application Programming Reference

FREE (MRO) SEND (3650-3653)
HANDLE AID SEND (3650-3680)
ISSUE COPY (3270 display) SEND (3735)
ISSUE COPY (3270 logical) SEND (3740)
ISSUE DISCONNECT SEND (3767)
ISSUE ENDFILE SEND (3770)
ISSUE ENDOUTPUT SEND (3790 full-function or inquiry)
ISSUE EODS SEND (3790 SCS)
ISSUE ERASEAUP SEND (3790 3270-display)
ISSUE LOAD SEND (3790 3270-printer)
ISSUE PASS WAIT SIGNAL
ISSUE PRINT WAIT TERMINAL
ISSUE RESET
ISSUE SIGNAL (LUTYPE6.1)
POINT
Transient data
RECEIVE (default) DELETEQ TD
RECEIVE (LUTYPE2/LUTYPE3) READQ TD
RECEIVE (LUTYPE4) WRITEQ TD
RECEIVE (LUTYPE6.1)
RECEIVE (MRO)
RECEIVE (System/3)
RECEIVE (System/7)
RECEIVE (2260)
RECEIVE (2741)
RECEIVE (2770)
RECEIVE (2780)
RECEIVE (2980)
RECEIVE (3270 display)
RECEIVE (3270 logical)
RECEIVE (3600 BTAM)
RECEIVE (3600-3601)
RECEIVE (3600-3614)
RECEIVE (3650)
RECEIVE (3735)
RECEIVE (3740)
RECEIVE (3767)
RECEIVE (3770)
RECEIVE (3790 full-function or inquiry)
RECEIVE (3790 3270-display)
SEND (default)
SEND (LUTYPE2/LUTYPE3)
SEND (LUTYPE4)
SEND (LUTYPE6.1)
SEND (MRO)
SEND (SCS)
SEND (System/3)
SEND (System/7)
SEND (2260)
SEND (2741)
SEND (2770)
SEND (2880)
SEND (2980)
SEND (3270 display)
SEND (3270 logical)
SEND (3600 BTAM)
SEND (3600 pipeline)
SEND (3600-3601)
SEND (3600-3614)
SEND (3650 interpreter)
SEND (3650-3270)

Chapter 1. Commands 11
ABEND

ABEND

Function
Terminate task abnormally.

Command syntax

──ABEND──┬──────────────┬──┬────────┬──┬────────┬──"
└─ABCODE(name)─┘ └─CANCEL─┘ └─NODUMP─┘

ABEND terminates a task abnormally.

The main storage associated with the terminated task is

released; optionally, a transaction dump of this storage can
be obtained.

The following example shows how to terminate a task

abnormally:
EXEC CICS ABEND ABCODE('BCDE')

ABEND options
ABCODE(name)
specifies that main storage related to the task that is
| being terminated is to be dumped. The ABCODE is
| used as a transaction dumpcode to identify the dump.
| The name should have four characters and should not
| contain any leading or imbedded blanks. If ABCODE is
| not coded, the dump is identified by ????.
Do not start the name with the letter A, because this is
reserved for CICS itself.

CANCEL
specifies that exits established by HANDLE ABEND
commands are to be ignored. An ABEND CANCEL
command cancels all exits at any level in the task (and
terminates the task abnormally). If the PL/I STAE
execution-time option has been specified, an abnormal
termination exit is established by PL/I. This exit is
revoked by the CANCEL option.

NODUMP
specifies an abend without causing a dump to be taken.

12 CICS/ESA Application Programming Reference

ADDRESS

Function
Get access to CICS storage areas.

Command syntax

──ADDRESS──┬───────────────────┬──┬───────────────┬──┬──────────────┬──┬──────────────┬──────────────────
└─COMMAREA(ptr-ref)─┘ └─ACEE(ptr-ref)─┘ └─CWA(ptr-ref)─┘ └─EIB(ptr-ref)─┘
──┬────────────────┬──┬──────────────┬──"
└─TCTUA(ptr-ref)─┘ └─TWA(ptr-ref)─┘
Conditions:
INVREQ

| Note for dynamic transaction routing

| Using ADDRESS with CWA could create inter-transaction affinities that adversely affect the use of dynamic transaction
| routing. See the CICS/ESA Application Programming Guide for more information about transaction affinities.

ADDRESS accesses the following areas: is used to pass information between application
programs. The pointer reference is set to the address of
| the communication area available to the invoked
the current COMMAREA. If the COMMAREA does not
| program (COMMAREA)
exist, the pointer reference is set to the null value,
| the access control environment element (ACEE)
X'FF000000'.
| the common work area (CWA)
| the EXEC interface block (EIB) In C, you must use ADDRESS COMMAREA to get the
| the terminal control table user area (TCTUA) address of the communication area, because this is not
| the transaction work area (TWA). passed as an argument to a C main function.

| In assembler language, no more than four options may be CWA(ptr-ref)

| specified in one ADDRESS command. provides information available to applications running in
a single CICS system. CICS sets the pointer reference
# Note: In OS/VS COBOL only, if an ADDRESS command is
to the address of the CWA. If a CWA does not exist,
# included in a COBOL program that is to be compiled
CICS sets the pointer reference to the null value,
# using the optimization feature, it must be followed by
X'FF000000'.
# SERVICE RELOAD statements to reload the BLL cell
# being used. EIB(ptr-ref)
gets addressability to the EXEC interface block in
application routines other than the first invoked by CICS
ADDRESS options (where addressability to the EIB is provided
ACEE(ptr-ref) automatically). If the application program is translated
is a pointer to the access control environment element, with SYSEIB in the XOPTS parameter list, this option
the control block that is generated by an external returns the address of the system EIB.
security manager (ESM) when the user signs on. If the If TASKDATALOC(ANY) is defined on the transaction
user is not signed on, the address of the CICS definition, the address of the data may be above or
DFLTUSER’s ACEE is returned. If an ACEE does not below the 16MB line.
exist, CICS sets the pointer reference to the null value,
X'FF000000'. If TASKDATALOC(BELOW) is defined on the transaction
definition, and the data resides above the 16MB line, the
| Note: Take care when addressing an ACEE in a server data is copied below the 16MB line, and the address of
| program invoked by a distributed program link. The this copy is returned.
| ACEE address returned depends on the link security and
| may not be the same as the address of the user signed C functions must use ADDRESS EIB to get the address
| on at the local system. of the EXEC interface block, because this address is not
| passed as an argument to a C main function. You must
COMMAREA(ptr-ref) | code an ADDRESS EIB statement at the beginning of
is the address of the currently defined communication | each application if you want access to the EIB, or if you
area for the currently executing program. COMMAREA

Chapter 1. Commands 13
ADDRESS

| are using a command that includes the RESP or RESP2 TCTUA(ptr-ref)

| option. passes information between application programs, but
only if the same terminal is associated with the
application programs involved (which can be in different
tasks). CICS sets the pointer reference to the address
of the TCTUA. If a TCTUA does not exist, CICS sets
the pointer reference to the null value, X'FF000000'.
The data area contains the address of the TCTUA of the
principal facility, not that for any alternate facility that
may have been allocated.

TWA(ptr-ref)
passes information between application programs but
only if they are in the same task. The pointer reference
is set to the address of the TWA. If a TWA does not
exist, the pointer reference is set to the null value,
X'FF000000'.
If TASKDATALOC(ANY) is defined on the transaction
definition, the address of the data may be above or
below the 16MB line.
If TASKDATALOC(BELOW) is defined on the transaction
definition, and the data resides above the 16MB line, the
data is copied below the 16MB line, and the address of
this copy is returned.

ADDRESS condition
INVREQ
indicates that the TCTUA option is not allowed in a
server program invoked by a distributed program link
(RESP2=200).
Default action: terminate the task abnormally.

14 CICS/ESA Application Programming Reference

ADDRESS SET

Function
Set the address of a structure or pointer.

Command syntax

──ADDRESS──┬─SET(data-area)──USING(ptr-ref)─┬──"
| └─SET(ptr-ref)──USING(data-area)─┘

| The value from the USING option is used to set the

| reference in the SET option.

| COBOL example of ADDRESS SET

To set the address of a structure to a known pointer value:
EXEC CICS ADDRESS SET(address of struc)
USING(ptr)

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

| EXEC CICS ADDRESS SET(ptr)
| USING(address of strucO1)

ADDRESS SET options

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

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

Chapter 1. Commands 15
ALLOCATE (APPC)

ALLOCATE (APPC)

Function
Acquire a session to a remote APPC logical unit for use by an APPC mapped conversation.

Command syntax

──ALLOCATE──┬─SYSID(systemname)──┬───────────────┬─┬──┬─────────┬──┬─────────────┬──"
│ └─PROFILE(name)─┘ │ └─NOQUEUE─┘ └─STATE(cvda)─┘
| └─PARTNER(name)────────────────────────┘
Conditions:
| CBIDERR, INVREQ, NETNAMEIDERR, PARTNERIDERR, SYSBUSY, SYSIDERR

ALLOCATE acquires the session and optionally selects a set ALLOCATE (APPC) options
of session-processing options. CICS makes one of the
sessions associated with the named system available to the | NOQUEUE
application program. | overrides the default action when a SESSBUSY or
| SYSBUSY condition arises. These conditions indicate
CICS returns, in EIBRSRCE in the EIB, the 4-byte CONVID | that the session requested is not immediately available.
(conversion identifier) that the application program uses in all | The default action is to suspend application execution
subsequent commands that relate to the conversation. | until the session is available. NOQUEUE inhibits this
| waiting; control returns immediately to the application
| If the session requested is not available, the application is | program instruction following the command.
| suspended until the session does become available. In such
| a case, the suspension of the application can be prevented | PARTNER(name)
| by specifying either the NOQUEUE or the NOSUSPEND | specifies the name (8 characters) of a set of definitions
| option. NOSUSPEND is still supported as an equivalent for | that include the names of a remote LU (NETNAME) and
| NOQUEUE, but NOQUEUE is the preferred keyword. | a communication profile to be used on the allocated
| session. You can use this option as an alternative to
| A session is available for allocation only if it is all of the | specifying SYSID and PROFILE explicitly.
| following:
PROFILE(name)
| A contention winner specifies the name (1–8 characters) of a set of
| Already bound session-processing options that are to be used during
| Not already allocated. the execution of mapped commands for the session
| specified in the SYSID option. If you specify SYSID and
# The action taken by CICS if a session is not immediately | omit PROFILE, a default profile (DFHCICSA) is selected.
# available depends on whether you specify NOQUEUE (or the
# equivalent NOSUSPEND option) and also on whether your STATE(cvda)
# application has executed a HANDLE command for the gets the state of the current conversation. The cvda
# SYSBUSY condition. The possible combinations are shown value returned by CICS is ALLOCATED.
# below:
SYSID(systemname)
# HANDLE for SYSBUSY condition issued | specifies the name (1–4 characters) by which the remote
# The command is not queued and control is returned | APPC LU is known to this CICS. This option requests
# immediately to the label specified in the HANDLE that one of the sessions to the named system is to be
# command, whether or not you have specified allocated.
# NOQUEUE. pt.No HANDLE issued for SYSBUSY
# condition pd.If you have specified NOQUEUE, the
# request is not queued and control is returned
ALLOCATE (APPC) conditions
# immediately to your application program. The CBIDERR
# SYSBUSY code (X'D3') is set in the EIBRCODE field of occurs if the requested PROFILE cannot be found.
# the EXEC interface block. You should test this field
Default action: terminate the task abnormally.
# immediately after issuing the ALLOCATE command.
# If you have omitted the NOQUEUE option, CICS queues INVREQ
# the request (and your application waits) until a session is occurs if the ALLOCATE command is not valid for the
# available. device to which it is directed.

16 CICS/ESA Application Programming Reference

ALLOCATE (APPC)

Default action: terminate the task abnormally.

| PARTNERIDERR
| occurs if the name specified in the PARTNER option is
| not recognized by CICS.
| Default action: terminate the task abnormally.

SYSBUSY
| occurs for one of the following reasons:

| The request for a session cannot be serviced

| Default action: ignore the condition.

SYSIDERR
occurs if CICS is unable to provide the application
program with a suitable session, for one of the following
reasons:

The name specified in the SYSID option is not

recognized by CICS.
The mode name derived from the PROFILE option
is not one of the mode names defined for the APPC
system entry.
All the sessions in the group specified by SYSID
and mode name are out of service, or all sessions
are out of service.
| The AID (automatic initiate descriptor) representing
| your ALLOCATE has been canceled.

Default action: terminate the task abnormally.

Chapter 1. Commands 17
ALLOCATE (LUTYPE6.1)

ALLOCATE (LUTYPE6.1)

Function
Acquire a session to a remote LUTYPE6.1 logical unit.

Command syntax

──ALLOCATE──┬─SESSION(name)─────┬──┬───────────────┬──┬─────────┬──"
└─SYSID(systemname)─┘ └─PROFILE(name)─┘ └─NOQUEUE─┘
Conditions:
CBIDERR, EOC, INVREQ, SESSBUSY, SESSIONERR, SYSBUSY, SYSIDERR

ALLOCATE acquires an alternate facility and optionally ALLOCATE (LUTYPE6.1) conditions

selects a set of session-processing options. If SYSID is
specified, CICS makes available to the application program CBIDERR
one of the sessions associated with the named system. The occurs if the requested PROFILE cannot be found.
name of this session can be obtained from EIBRSRCE in the Default action: terminate the task abnormally.
EIB. If SESSION is specified, CICS makes the named
session available. EOC
occurs when a request/response unit (RU) is received
| If the session requested is not available, the application is with the end-of-chain indicator set. Field EIBEOC also
| suspended until the session does become available. In such contains this indicator.
| a case, the suspension of the application can be prevented Default action: ignore the condition.
| by specifying either the NOQUEUE or the NOSUSPEND
| option. NOSUSPEND is still supported as an equivalent for INVREQ
| NOQUEUE, but NOQUEUE is the preferred keyword. occurs when the specified session is already allocated to
this task, or the session is an APPC session.

ALLOCATE (LUTYPE6.1) options Default action: terminate the task abnormally.

NOQUEUE SESSBUSY
overrides the default action when a SESSBUSY or occurs if the request for the specified session cannot be
SYSBUSY condition arises. These conditions indicate serviced immediately. This is only possible if
that the session requested is not immediately available. NOQUEUE is set.
The default action is to suspend application execution Default action: queue the request until a session is
until the session is available. NOQUEUE inhibits this available.
waiting; control returns immediately to the application
program instruction following the command. SESSIONERR
occurs if the name specified in the SESSION option is
PROFILE(name) not that of an LUTYPE6.1 session TCTTE, or if the
specifies the name (1–8 characters) of a set of session cannot be allocated because it is out of service.
session-processing options that are to be used during
Default action: terminate the task abnormally.
execution of terminal control commands for the session
specified in the SYSID or SESSION options. If the SYSBUSY
PROFILE option is omitted, a default profile | occurs for one of the following reasons:
(DFHCICSA) is selected.
| The request for a session cannot be serviced
SESSION(name) | immediately. This is only possible if NOQUEUE is
specifies the symbolic identifier (1–4 characters) of a | set.
session TCTTE. This option specifies the alternate
| The ALLOCATE command is issued when
facility to be used.
| persistent session recovery is still in process and
SYSID(systemname) | the sessions needed to satisfy the command are not
specifies the name (1–4 characters) of a system TCTSE. | yet recovered.
This option specifies that one of the sessions to the
| Default action: ignore the condition.
named system is to be allocated.

18 CICS/ESA Application Programming Reference

ALLOCATE (LUTYPE6.1)

SYSIDERR
occurs if CICS is unable to provide the application
program with a suitable session, for one of the following
reasons:

The name specified in the SYSID option is not

recognized by CICS.
All sessions are out of service.
| The AID (automatic initiate descriptor) representing
| your ALLOCATE has been canceled.

Default action: terminate the task abnormally.

Chapter 1. Commands 19
ALLOCATE (MRO)

ALLOCATE (MRO)

Function
Acquire an MRO session.

Command syntax

──ALLOCATE──SYSID(systemname)──┬─────────┬──┬─────────────┬──"
└─NOQUEUE─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, SYSBUSY, SYSIDERR

ALLOCATE acquires an alternate facility. CICS makes ALLOCATE (MRO) conditions

available to the application program one of the sessions
associated with the system named in the SYSID option. The INVREQ
name of this session can be obtained from EIBRSRCE in the occurs if an incorrect command has been issued for the
EIB. LU or terminal in use.
Default action: terminate the task abnormally.
(If the PROFILE option is specified, it is ignored on an MRO
session. This is useful if you want to code a command that SYSBUSY
can be used on either an LUTYPE6.1 or MRO session.) occurs if the request for a session cannot be serviced
immediately. This is only possible if NOQUEUE is set.
| If the session requested is not available, the application is
Default action: ignore the condition.
| suspended until the session does become available. In such
| a case, the suspension of the application can be prevented SYSIDERR
| by specifying the NOQUEUE option. occurs if CICS is unable to provide the application
program with a suitable session, for one of the following
For more information about MRO and IRC, see the reasons:
CICS/ESA Intercommunication Guide.
The name specified in the SYSID option is not
recognized by CICS.
ALLOCATE (MRO) options
All sessions are out of service.
NOQUEUE
| The AID (automatic initiate descriptor) representing
overrides the default action when a SESSBUSY or
| your ALLOCATE has been canceled.
SYSBUSY condition arises. These conditions indicate
that the session requested is not immediately available. Default action: terminate the task abnormally.
The default action is to suspend application execution
until the session is available. NOQUEUE inhibits this
waiting; control returns immediately to the application
program instruction following the command.

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

SYSID(systemname)
specifies the name (1–4 characters) of a system TCTSE.
This option specifies that one of the sessions to the
named system is to be allocated.

20 CICS/ESA Application Programming Reference

ASKTIME

Function
Request current date and time of day.

Command syntax

──ASKTIME──┬────────────────────┬──"
└─ABSTIME(data-area)─┘

ASKTIME updates the date (EIBDATE) and CICS time-of-day

clock (EIBTIME) fields in the EIB. These two fields initially
contain the date and time when the task started. Refer to
Appendix A, “EXEC interface block” on page 343 for details
of the EIB.

ASKTIME option
ABSTIME(data-area)
specifies the data area for the time, in packed decimal,
since 00:00 on 1 January 1900 (in milliseconds rounded
to the nearest hundredth of a second).
| You can use FORMATTIME to change the data into
| other familiar formats.
| For example, after execution of:
| EXEC CICS ASKTIME ABSTIME(utime)
| “utime” contains a value similar in format to
| 002837962864820.
The format of “data-area” is:
COBOL: PIC S9(15) COMP-3
C char data_area[8];
PL/I: FIXED DEC(15)
ASM: PL8

Chapter 1. Commands 21
ASSIGN

ASSIGN

Function
Request values from outside the application program’s local environment.

Command syntax

┌──
───────────────────────────┐ ┌─────────────────────────────┐
──ASSIGN───*┬─────────────────────────┬┴───*┬─────────────────────────┬┴──"
├─ABCODE(data-area)───────┤ ├─MAPWIDTH(data-area)─────┤
├─ABDUMP(data-area)───────┤ ├─MSRCONTROL(data-area)───┤
├─ABPROGRAM(data-area)────┤ ├─NATLANGINUSE(data-area)─┤
├─ALTSCRNHT(data-area)────┤ ├─NETNAME(data-area)──────┤
├─ALTSCRNWD(data-area)────┤ ├─NEXTTRANSID(data-area)──┤
├─APLKYBD(data-area)──────┤ ├─NUMTAB(data-area)───────┤
├─APLTEXT(data-area)──────┤ ├─OPCLASS(data-area)──────┤
├─APPLID(data-area)───────┤ ├─OPERKEYS(data-area)─────┤
| ├─ASRAINTRPT(data-area)───┤ ├─OPID(data-area)─────────┤
├─ASRAKEY(cvda)───────────┤ ├─OPSECURITY(data-area)───┤
├─ASRAPSW(data-area)──────┤ ├─ORGABCODE(data-area)────┤
├─ASRAREGS(data-area)─────┤ ├─OUTLINE(data-area)──────┤
| ├─ASRASPC(cvda)───────────┤ ├─PAGENUM(data-area)──────┤
| ├─ASRASTG(cvda)───────────┤ ├─PARTNPAGE(data-area)────┤
├─BTRANS(data-area)───────┤ ├─PARTNS(data-area)───────┤
├─CMDSEC(data-area)───────┤ ├─PARTNSET(data-area)─────┤
├─COLOR(data-area)────────┤ ├─PRINSYSID(data-area)────┤
├─CWALENG(data-area)──────┤ ├─PROGRAM(data-area)──────┤
├─DEFSCRNHT(data-area)────┤ ├─PS(data-area)───────────┤
├─DEFSCRNWD(data-area)────┤ ├─QNAME(data-area)────────┤
├─DELIMITER(data-area)────┤ ├─RESSEC(data-area)───────┤
├─DESTCOUNT(data-area)────┤ ├─RESTART(data-area)──────┤
| ├─DESTID(data-area)───────┤ ├─RETURNPROG(data-area)───┤
├─DESTIDLENG(data-area)───┤ ├─SCRNHT(data-area)───────┤
├─DSSCS(data-area)────────┤ ├─SCRNWD(data-area)───────┤
├─DS327O(data-area)───────┤ ├─SIGDATA(data-area)──────┤
├─EWASUPP(data-area)──────┤ ├─SOSI(data-area)─────────┤
├─EXTDS(data-area)────────┤ ├─STARTCODE(data-area)────┤
├─FACILITY(data-area)─────┤ ├─STATIONID(data-area)────┤
├─FCI(data-area)──────────┤ ├─SYSID(data-area)────────┤
├─GCHARS(data-area)───────┤ ├─TASKPRIORITY(data-area)─┤
├─GCODES(data-area)───────┤ ├─TCTUALENG(data-area)────┤
├─GMMI(data-area)─────────┤ ├─TELLERID(data-area)─────┤
├─HILIGHT(data-area)──────┤ ├─TERMCODE(data-area)─────┤
├─INITPARM(data-area)─────┤ ├─TERMPRIORITY(data-area)─┤
├─INITPARMLEN(data-area)──┤ ├─TEXTKYBD(data-area)─────┤
├─INPARTN(data-area)──────┤ ├─TEXTPRINT(data-area)────┤
| ├─INVOKINGPROG(data-area)─┤ ├─TRANPRIORITY(data-area)─┤
├─KATAKANA(data-area)─────┤ ├─TWALENG(data-area)──────┤
├─LANGINUSE(data-area)────┤ ├─UNATTEND(data-area)─────┤
├─LDCMNEM(data-area)──────┤ ├─USERID(data-area)───────┤
├─LDCNUM(data-area)───────┤ ├─USERNAME(data-area)─────┤
├─MAPCOLUMN(data-area)────┤ ├─USERPRIORITY(data-area)─┤
├─MAPHEIGHT(data-area)────┤ └─VALIDATION(data-area)───┘
└─MAPLINE(data-area)──────┘
Conditions:
INVREQ

ASSIGN gets values from outside the local environment of Where any of the following options apply to terminals or
the application program. The data obtained depends on the terminal-related data, the reference is always to the principal
specified options. Up to sixteen options can be specified in facility.
one ASSIGN command.
If the principal facility is a remote terminal, the data returned
is obtained from the local copy of the information; the request

22 CICS/ESA Application Programming Reference

ASSIGN

is not routed to the system to which the remote terminal is that identifies the active and alternate CICS systems).
attached. An application program is unaffected by a takeover from
the active to the alternate.
Transaction routing is as far as possible transparent to the
ASSIGN command. In general, the values returned are the ASRAINTRPT(data-area)
same whether the transaction is local or remote. returns an 8-character program status word (PSW)
containing interrupt information at the point when the
For more details on these options, see the CICS/ESA | latest abend with a code of ASRA, ASRB, ASRD, or
Intercommunication Guide. | AICA occurred.
The field contains binary zeros if no ASRA, ASRB,
ASSIGN options ASRD, or AICA abend occurred during the execution of
the issuing transaction, or if the abend originally
ABCODE(data-area) occurred in a remote DPL server program.
returns a 4-character current abend code (abend codes
are documented in the CICS/ESA Messages and Codes | ASRAKEY(cvda)
manual). If an abend has not occurred, the variable is | returns the execution key at the time of the last ASRA,
set to blanks. | ASRB, AICA, or AEYD, abend, if any. The CVDA
| values on the ASRAKEY option are as follows:
ABDUMP(data-area)
returns a 1-byte value. X'FF' indicates that a dump has | CICSEXECKEY is returned if the task was executing in
been produced and that ABCODE contains an abend | CICS-key at the time of the last ASRA,
code. X'00' indicates either that no dump has been | ASRB, AICA, or AEYD abend. Note
produced, or that ABCODE contains blanks. | that all programs execute in CICS key
| if CICS subsystem storage protection is
ABPROGRAM(data-area) | not active.
returns an 8-character name of the failing program for
the latest abend. | USEREXECKEY
| is returned if the task was executing in
If the abend originally occurred in a DPL server program | user-key at the time of the last ASRA,
running in a remote system, ABPROGRAM returns the | ASRB, AICA, or AEYD abend.
DPL server program name.
| NONCICS is returned if the execution key at the
| This field is set to binary zeros if it is not possible to | time of the last abend was not one of
| determine the failing program at the time of the abend. | the CICS keys; that is, not key 8 or key
ALTSCRNHT(data-area) | 9.
returns the alternate screen height defined for the | NOTAPPLIC is returned if there has not been an
terminal as a halfword binary variable. If the task is not | ASRA, ASRB, AICA, or AEYD abend.
initiated from a terminal, INVREQ occurs.
ASRAPSW(data-area)
ALTSCRNWD(data-area) returns an 8-character program status word (PSW) at
returns the alternate screen width defined for the | the point when the latest abend with a code of ASRA,
terminal as a halfword binary variable. If the task is not | ASRB, ASRD, or AICA occurred.
initiated from a terminal, INVREQ occurs.
| The field contains binary zeros if no ASRA, ASRB,
APLKYBD(data-area) ASRD, or AICA abend occurred during the execution of
returns a 1-byte indicator showing whether the terminal the issuing transaction, or if the abend originally
keyboard has the APL keyboard feature. X'FF' occurred in a remote DPL server program.
indicates “yes”. X'00' indicates “no”. If the task is not
ASRAREGS(data-area)
initiated from a terminal, INVREQ occurs.
returns the contents of general registers 0–15 at the
APLTEXT(data-area) | point when the latest ASRA, ASRB, ASRD, or AICA
returns a 1-byte indicator showing whether the terminal | abend occurred.
keyboard has the APL text feature. X'FF' indicates The contents of the registers are returned in the data
“yes”. X'00' indicates “no”. If the task is not initiated area (64 bytes long) in the order 0, 1, ..., 14, 15.
from a terminal, INVREQ occurs.
| Note that the data area is set to binary zeros if no
APPLID(data-area) | ASRA, ASRB, ASRD, or AICA abend occurred during
returns an 8-character applid of the CICS system owning | the execution of the issuing transaction or the abend
the transaction. originally occurred in a remote DPL server program.
If your system is using XRF (that is, XRF=YES has been
specified in the system initialization parameters), the
value returned is the generic applid (that is, the applid

Chapter 1. Commands 23
ASSIGN

| ASRASPC(cvda) capability (X'FF') or not (X'00'). If the task is not

| returns the type of space in control at the time of the last initiated from a terminal, INVREQ occurs.
| ASRA, ASRB, AICA, or AEYD, abend, if any. The
CMDSEC(data-area)
| CVDA values on the ASRASPC option are:
returns a 1-byte indicator showing whether command
| SUBSPACE is returned if the task was executing in security checking has been defined for the current task.
| either its own subspace or the common (X for “yes”, blank for “no”.)
| subspace at the time of the last ASRA,
COLOR(data-area)
| ASRB, AICA, or AEYD abend.
returns a 1-byte indicator showing whether the terminal
| BASESPACE is returned if the task was executing in is defined as having the extended color capability
| the base space at the time of the last (X'FF') or not (X'00'). If the task is not initiated from a
| ASRA, ASRB, AICA, or AEYD abend. terminal, INVREQ occurs.
| Note that all tasks execute in base
| space if transaction isolation is not CWALENG(data-area)
| active. returns a halfword binary field indicating the length of the
CWA. If no CWA exists, a zero length is returned.
| NOTAPPLIC is returned if there has not been an
| ASRA, ASRB, AICA, or AEYD abend. DEFSCRNHT(data-area)
returns a halfword binary variable that contains the
| ASRASTG(cvda)
default screen height defined for the terminal. If the task
| returns the type of storage being addressed at the time
is not initiated from a terminal, INVREQ occurs.
| of the last ASRA or AEYD, abend, if any. The CVDA
| values on the ASRASTG option are: DEFSCRNWD(data-area)
returns a halfword binary variable that contains the
| CICS is returned if the storage being
default screen width defined for the terminal. If the task
| addressed is CICS-key storage. This
is not initiated from a terminal, INVREQ occurs.
| can be in one of the CICS dynamic
| storage areas (CDSA or ECDSA), or, in DELIMITER(data-area)
| one of the read-only dynamic storage returns a 1-byte data-link control character for a 3600,
| areas (RDSA or ERDSA) when CICS is and can be:
| running with the NOPROTECT option
X'80' Input ended with end-of-text (ETX)
| on the RENTPGM system initialization
X'40' Input ended with end-of-block (ETB)
| parameter or when storage protection
X'20' Input ended with inter-record separator (IRS)
| is not active.
X'10' Input ended with start of header (SOH)
| USER is returned if the storage being X'08' Transparent input.
| addressed is user-key storage in one of
| the user dynamic storage areas (UDSA If the task is not initiated from a terminal, INVREQ
| or EUDSA). occurs.

| READONLY is returned if the storage being DESTCOUNT(data-area)

| addressed is read-only storage in one returns a halfword binary field. This option has two
| of the read-only dynamic storage areas uses:
| (RDSA or ERDSA) when CICS is
1. Following a BMS ROUTE command, it shows that
| running with the PROTECT option on
the value required is the number of different terminal
| the RENTPGM system initialization
types in the route list, and hence the number of
| parameter.
overflow control areas that may be required.
| NOTAPPLIC is returned if:
2. Within BMS overflow processing, it shows that the
| There is no ASRA or AEYD abend value required is the relative overflow control
| found for this task number of the destination that has encountered
| The affected storage in an abend overflow. If this option is specified when overflow
| is not managed by CICS processing is not in effect, the value obtained is
meaningless. If no BMS commands have been
| The ASRA abend is not caused by
issued, INVREQ occurs.
| an 0C4 abend
DESTID(data-area)
| An ASRB or AICA abend has
returns an 8-byte identifier of the outboard destination,
| occurred since the last ASRA or
padded with blanks on the right to eight characters. If
| AEYD abend.
this option is specified before a batch data interchange
BTRANS(data-area) command has been issued in the task, INVREQ occurs.
returns a 1-byte indicator showing whether the terminal
is defined as having the background transparency

24 CICS/ESA Application Programming Reference

ASSIGN

DESTIDLENG(data-area) GCODES(data-area)
returns a halfword binary length of the destination returns a halfword binary code page global identifier (the
identifier obtained by DESTID. If this option is specified CPGID). The value is a number in the range 1 through
before a batch data interchange command has been 65 534 representing the EBCDIC code page defining the
issued in the task, INVREQ occurs. code points for the characters that can be input or output
at the terminal. If the task is not initiated from a
DSSCS(data-area)
terminal, INVREQ occurs.
returns a 1-byte indicator showing whether the principal
facility is a basic SCS data stream device. (X'FF' for GMMI(data-area)
“yes”, or X'00' for “no”.) returns a 1-byte indicator showing whether a “good
morning” message applies to the terminal associated
DS3270(data-area)
with the running transaction. (X'FF' for “yes”, or X'00'
returns a 1-byte indicator showing whether the principal
for “no”.) If this option is specified and the current task
facility is a 3270 data stream device. (X'FF' for “yes”,
is not associated with a terminal, the INVREQ condition
or X'00' for “no”.)
occurs.
EWASUPP(data-area)
HILIGHT(data-area)
returns a 1-byte indicator showing whether Erase Write
returns a 1-byte indicator showing whether the terminal
Alternative is supported. (X'FF' for “yes”, X'00' for
is defined as having the extended highlight capability
“no”.)
(X'FF') or not (X'00'). If the task is not initiated from a
EXTDS(data-area) terminal, INVREQ occurs.
returns a 1-byte indicator showing whether the terminal
INITPARM(data-area)
accepts the 3270 extended data stream. Extended data
| returns the 60-character data-area containing any
stream capability is required for a terminal that supports
initialization parameters specified for the program in the
the query feature, color, extended highlighting,
INITPARM system initialization parameter. If there are
programmed symbols or validation. A terminal that
no parameters for the program, the area is filled with
accepts the query structured field command also has
binary zeros. (See the CICS/ESA System Definition
this indicator set. If extended data stream is on, the
Guide for further information about the INITPARM
device supports the write structured field COMMAND
option.)
and Outbound Query Structured field.
INITPARMLEN(data-area)
(For guidance information about query structured fields,
returns a halfword binary length of the INITPARM. If
see the CICS/ESA 3270 Data Stream Device Guide.)
there is no parameter for it, INITPARMLEN contains
If the task is not initiated from a terminal, INVREQ binary zeros.
occurs.
INPARTN(data-area)
FACILITY(data-area) returns the 1- or 2-character name of the most recent
returns a 4-byte identifier of the facility that initiated the | input partition. If no map has yet been positioned, or if
transaction; that is the facility control address as defined | BMS routing is in effect, or if the task is not initiated from
using the RDO option TYPETERM. If this option is | a terminal, INVREQ occurs.
specified, and there is no allocated facility, INVREQ
occurs. | INVOKINGPROG(data-area)
| returns the 8-character name of the application program
Note: You should always use the QNAME option
| that used the LINK or XCTL command to link or transfer
(described on page 27) to get the name of the transient
| control to the current program.
data intrapartition queue whose trigger level caused the
transaction to be initiated. | If you issue the ASSIGN INVOKINGPROG command in
| a remote program that was invoked by a distributed
FCI(data-area) | program link (DPL) command, CICS returns the name of
returns a 1-byte facility control indicator, see “ASSIGN | the program that issued the DPL command.
FCI” on page 351. This indicates the type of facility
| If you issue the ASSIGN INVOKINGPROG command in
associated with the transaction; for example, X'01'
| an application program at the highest level, CICS returns
indicates a terminal or logical unit. The obtained value
| eight blanks.
is always returned.
| If you issue the ASSIGN INVOKINGPROG command in
GCHARS(data-area)
| a
returns a halfword binary graphic character set global
| Apar 62320
identifier (the GCSGID). The value is a number in the
range 1 through 65 534 representing the set of graphic | Documentation for Apar 62320 added 15 Nov 1994
characters that can be input or output at the terminal. If | (TUCKER)
the task is not initiated from a terminal, INVREQ occurs.

Chapter 1. Commands 25
ASSIGN

| user-replaceable module or a program list table program, MAPWIDTH(data-area)

| CICS returns eight blanks. returns a halfword binary width of the most recently
# positioned map. If no map has yet been positioned, or if
Apar 67276
BMS routing is in effect, or if the task is not initiated from
# Documentation for Apar 67276 added 2 Mar 1995 a terminal, INVREQ occurs.
# (TUCKER)
MSRCONTROL(data-area)
returns a 1-byte indicator showing whether the terminal
# If you issue the ASSIGN INVOKINGPROG command
supports magnetic slot reader (MSR) control (X'FF') or
# from a global user exit, task-related exit, or application
not (X'00'). If the task is not initiated from a terminal,
# program linked to from such an exit, CICS returns the
INVREQ occurs.
# name of the most recent invoking program that was not
# a global user exit or task-related user exit. NATLANGINUSE(data-area)
# returns a 1-byte mnemonic code showing the national
KATAKANA(data-area)
# language associated with the USERID for the current
returns a 1-byte indicator showing whether the principal
# task (which could be the default USERID). Refer to the
facility supports katakana (X'FF') or not (X'00'). If the
# SIGNON command for an explanation of how this value
task is not initiated from a terminal, INVREQ occurs.
# is derived. See Appendix I, “National language codes”
# Apar 89178 | on page 373 for possible values of the code.
# Documentation for Apar 89178 added 16 Oct 1996 | (NATLANGINUSE does not show the system default
# (DONOGHUE) | language as specified on the NATLANG system
| initialization parameter.)

# LANGINUSE(data-area) NETNAME(data-area)
# returns a 3-byte mnemonic code showing the language returns the 8-character name of the logical unit in the
# in use. 3-byte mnemonic has has a 1:1 correspondence VTAM network. If the task is not initiated from a
# with the 1-byte NATLANGINUSE option. See terminal, INVREQ occurs. If the principal facility is not a
# Appendix I, “National language codes” on page 373 for local terminal, the value returned is a null string.
# possible values of the code.
NEXTTRANSID(data-area)
LDCMNEM(data-area) returns the 4-character next transaction identifier as set
returns a 1-byte logical device code (LDC) mnemonic of by SET NEXTTRANSID or RETURN TRANSID. It
the destination that has encountered overflow. If this returns blanks if there are no more transactions.
option is specified when overflow processing is not in
NUMTAB(data-area)
effect, the value obtained not significant. If no BMS
returns a 1-byte number of the tabs required to position
commands have been issued, INVREQ occurs.
the print element in the correct passbook area of the
LDCNUM(data-area) 2980. If the task is not initiated from a terminal,
returns a 1-byte LDC numeric value of the destination INVREQ occurs.
that has encountered overflow. This indicates the type
OPCLASS(data-area)
of the LDC, such as printer or console. If this option is
returns, in a 24-bit string, the operator class used by
specified when overflow processing is not in effect, the
BMS for routing terminal messages, as defined in the
value obtained is not significant.
CICS segment.
MAPCOLUMN(data-area)
OPERKEYS(data-area)
returns a halfword binary number of the column on the
is accepted for compatibility with previous releases.
display containing the origin of the most recently
positioned map. If no map has yet been positioned, or if OPID(data-area)
BMS routing is in effect, or if the task is not initiated from returns, in a 24-bit string, the operator identification used
a terminal, INVREQ occurs. by BMS for routing terminal messages, as defined in the
CICS segment.
MAPHEIGHT(data-area)
# Apar 87704
returns a halfword binary height of the most recently
positioned map. If no map has yet been positioned, or if # Documentation for Apar 87704 added 19/12/96
BMS routing is in effect, or if the task is not initiated from
a terminal, INVREQ occurs.
# If the task is initiated from a remote terminal, the OPID
MAPLINE(data-area) # returned by this command is not necessarily that
returns a halfword binary number of the line on the # associated with the user that is signed on at the remote
display containing the origin of the most recently # terminal. If you wish to to know the OPID of the
positioned map. If no map has yet been positioned, or if # signed-on user, you should use the INQUIRE
BMS routing is in effect, or if the task is not initiated from
a terminal, INVREQ occurs.

26 CICS/ESA Application Programming Reference

ASSIGN

# TERMINAL system programming command, which is An LU6.1 session to another CICS or IMS/VS
# described in the System Programming Reference. system
# Apar 92639 An APPC session to another CICS system, or to
another APPC system or device.
# - Following line removed, no longer true. If the
# task is not initiated from a terminal, INVREQ occurs. If the principal facility is not an MRO, LU6.1, or APPC
session, or if the task has no principal facility, INVREQ
# Apar PQ01572 occurs.
# The following paragraph was added by Apar Note: Special considerations apply generally when
# PQ01572 24/03/97 transaction routing. In particular an ASSIGN
PRINSYSID command cannot be used in a routed
# The OPID may also be different from that of the user transaction to find the name of the terminal-owning
# currently signed on, if it has been changed with the SET region. (See the CICS/ESA Intercommunication Guide
# TERMINAL command. for more information about transaction routing.)

OPSECURITY(data-area) PROGRAM(data-area)
is accepted for compatibility with previous releases. returns an 8-character name of the currently running
program.
ORGABCODE(data-area)
returns as a 4-byte original abend code in cases of PS(data-area)
repeated abends. returns a 1-byte indicator showing whether the terminal
is defined as having the programmed symbols capability
OUTLINE(data-area) (X'FF') or not (X'00'). If the task is not initiated from a
returns a 1-byte indicator showing whether the terminal terminal, INVREQ occurs.
is defined as having the field outlining capability (X'FF')
or not (X'00'). If the task is not initiated from a QNAME(data-area)
terminal, INVREQ occurs. returns a 4-character name of the transient data
intrapartition queue that caused this task to be initiated
PAGENUM(data-area) by reaching its trigger level. If the task is not initiated by
| returns a halfword binary current page number for the automatic transaction initiation (ATI), INVREQ occurs.
destination that has encountered an overflow. If this
option is specified when overflow processing is not in RESSEC(data-area)
effect, the value obtained is meaningless. If no BMS returns a 1-byte indicator showing whether resource
commands have been issued, INVREQ occurs. security checking has been defined for the transaction
running. (X for “yes”, blank for “no”.)
PARTNPAGE(data-area)
returns a 2-byte name of the partition that most recently RESTART(data-area)
caused page overflow. If no BMS commands have been returns a 1-byte indicator showing whether a restart of
issued, INVREQ occurs. the task (X'FF'), or a normal start of the task (X'00'),
has occurred.
PARTNS(data-area)
returns a 1-byte indicator showing whether the terminal | RETURNPROG(data-area)
supports partitions (X'FF') or not (X'00'). If the task is | returns the 8-character name of the program to which
not initiated from a terminal, INVREQ occurs. | control is to be returned when the current program has
| finished executing. The values returned depend on how
PARTNSET(data-area) | the current program was given control, as follows:
returns the name (1–6 characters) of the application
partition set. A blank value is returned if there is no | If the current program was invoked by a LINK
application partition set. If the task is not initiated from a | command, including a distributed program link,
terminal, INVREQ occurs. | RETURNPROG returns the same name as
| INVOKINGPROG.
PRINSYSID(data-area)
| If the current program was invoked by an XCTL
returns the 4-character name by which the other system
| command, RETURNPROG returns the name of the
is known in the local system; that is, the CONNECTION
| application program in the chain that last issued a
definition that defines the other system. For a
| LINK command. For example:
single-session APPC device defined by a terminal
definition, the returned value is the terminal identifier. | Program A links to program B
| Program B links to program C
This only applies when the principal facility is one of the | Program C transfers control to program D
following: | Program D issues an ASSIGN RETURNPROG command,
| and CICS returns the name of Program B.
An MRO session to another CICS system

Chapter 1. Commands 27
ASSIGN

| If the program that invoked the current program with DS A distributed program link (DPL) request, as in
| an XCTL command is at the highest level, CICS code D, with the exception that the program can
| returns eight blanks. issue syncpoint requests.
| If the ASSIGN RETURNPROG command is issued QD Transient data trigger level.
| in the program at the top level, CICS returns eight
S START command without data.
| blanks.
SD START command with data.
| If the ASSIGN RETURNPROG command is issued
| in a | SZ FEPI START command.
| Apar 62320 TD Terminal input.

| Documentation for Apar 62320 added 15 Nov U User-attached task.

| 1994 (TUCKER) STATIONID(data-area)
returns a 1-byte station identifier of a 2980. If the task is
| user-replaceable module, or a program list table not initiated from a terminal, INVREQ occurs.
| program, CICS returns eight blanks.
SYSID(data-area)
# Apar 67276 returns the 4-character name given to the local CICS
# Documentation for Apar 67276 added 2 Mar system. This value may be specified in the SYSID
# 1995 (TUCKER) option of a file control, interval control, temporary
storage, or transient data command, in which case the
# If the ASSIGN RETURNPROG is issued in a global resource to be accessed is assumed to be on the local
# user exit, task-related exit, or application program system.
# linked to from such an exit, CICS returns the name TASKPRIORITY(data-area)
# of the program that control is returned to when all returns a halfword binary current priority of the issuing
# intermediate global user exit and task-related user task (0–255). When the task is first attached, this is the
# exit programs have completed. sum of the user, terminal, and transaction priorities, but
SCRNHT(data-area) this value can be changed during execution by a
| returns a halfword binary variable that contains the CHANGE TASK command.
height of the 3270 screen defined for the current task. If TCTUALENG(data-area)
the task is not initiated from a terminal, INVREQ occurs. returns a halfword binary length of the terminal control
SCRNWD(data-area) table user area (TCTUA). If no TCTUA exists, a zero
| returns a halfword binary variable that contains the width length is returned.
of the 3270 screen defined for the current task. If the TELLERID(data-area)
task is not initiated from a terminal, INVREQ occurs. returns a 1-byte teller identifier of a 2980. If the task is
SIGDATA(data-area) not initiated from a terminal, INVREQ occurs.
| returns a 4-byte character string containing the inbound TERMCODE(data-area)
| signal data received from a logical unit. If the task is not returns a 2-byte code giving the type and model number
initiated from a terminal, INVREQ occurs. of the terminal associated with the task.
SOSI(data-area) The first byte is a code identifying the terminal type,
returns a 1-byte indicator showing whether the terminal derived from the DEVICE attribute of the TYPETERM
is defined as having the mixed EBCDIC/DBCS fields RDO attribute (described in the CICS/ESA Resource
capability (X'FF') or not (X'00'). The DBCS subfields Definition Guide). The second byte is a single-character
within an EBCDIC field are delimited by SO (shift-out) model number as specified in the TERMMODEL
and SI (shift-in) characters. If the task is not initiated attribute.
from a terminal, INVREQ occurs.
The meanings of the type codes are given in
STARTCODE(data-area) Appendix B, “Codes returned by ASSIGN” on page 351.
returns a 2-byte indicator showing how the transaction
TERMPRIORITY(data-area)
issuing the request was started. It can have the
returns a halfword binary terminal priority (0–255).
following values:
TEXTKYBD(data-area)
Code Transaction started by
returns a 1-byte indicator showing whether the principal
D A distributed program link (DPL) request. The facility supports TEXTKYBD. (X'FF' for “yes”, or X'00'
program cannot issue I/O requests against its for “no”.) If the task is not initiated from a terminal,
principal facility, nor can it issue any syncpoint INVREQ occurs.
requests.

28 CICS/ESA Application Programming Reference

ASSIGN

TEXTPRINT(data-area) ASSIGN condition

returns a 1-byte indicator showing whether the principal
facility supports TEXTPRINT. (X'FF' for “yes”, or INVREQ
X'00' for “no”.) If the task is not initiated from a occurs in any of the following situations:
terminal, INVREQ occurs.
The task does not have a signed-on user
TRANPRIORITY(data-area) (RESP2=1).
returns a halfword binary transaction priority (0–255). No BMS command has yet been issued, BMS
TWALENG(data-area) routing is in effect, or no map has yet been
returns a halfword binary length of the transaction work positioned (RESP2=2).
area (TWA). If no TWA exists, a zero length is returned. No batch data interchange (BDI) command has yet
been issued (RESP2=3).
UNATTEND(data-area)
returns a 1-byte indicator showing whether the mode of The task is not initiated by automatic transaction
| operation of the terminal is unattended, that is to say no initiation (ATI) (RESP2=4).
| person is actually attending the terminal. These | The task is not associated with a terminal; or the
| indicators are X'FF' for unattended and X'00' for | task has no principal facility; or the principal facility
| attended. If the task is not initiated from a terminal, | is not an MRO, LU6.1, or APPC session
INVREQ occurs. (RESP2=5).
USERID(data-area) Command syntax options are not allowed in a
| returns an 8-byte userid of the signed-on user. If no server program invoked by a distributed program
| user is explicitly signed on, CICS returns the default link (RESP2=200).
userid. Special considerations apply if you are using an
| Default action: terminate the task abnormally.
intercommunication environment. See the CICS/ESA
Intercommunication Guide for more information about
the ASSIGN command for LUTYPE6.1, APPC, and
MRO.
| Note: If you want to test if the user is explicitly signed
| on, use the UNATTEND option.

USERNAME(data-area)
returns a 20-character name of the user obtained from
the external security manager (ESM).

USERPRIORITY(data-area)
returns a halfword binary operator priority (0–255).

VALIDATION(data-area)
returns a 1-byte indicator showing whether the terminal
is defined as having the validation capability (X'FF') or
not (X'00'). Validation capability consists of the
mandatory fill, mandatory enter, and trigger attributes. If
the task is not initiated from a terminal, INVREQ occurs.

Chapter 1. Commands 29
BIF DEEDIT

BIF DEEDIT

Function
Deediting (built-in function).

Command syntax

──BIF DEEDIT──FIELD(data-area)──┬────────────────────┬──"
└─LENGTH(data-value)─┘
Conditions:
| LENGERR

BIF DEEDIT provides the built-in function DEEDIT. It BIF DEEDIT options
specifies that alphabetic and special characters are removed
from an EBCDIC data field, and the remaining digits FIELD(data-area)
right-aligned and padded to the left with zeros as necessary. specifies the field to be edited.

LENGTH(data-value)
If the field ends with a minus sign or a carriage-return (CR),
specifies the field length in bytes.
a negative zone (X'D') is placed in the rightmost (low-order)
byte.
| BIF DEEDIT conditions
If the zone portion of the rightmost byte contains one of the
characters X'A' through X'F', and the numeric portion | LENGERR
contains one of the hexadecimal digits X'0' through X'9', | occurs if the LENGTH value is less than 1.
the rightmost byte is returned unaltered (see the example). | Default action: terminate the task abnormally.
This permits the application program to operate on a zoned
numeric field. The returned value is in the field that initially
contained the unedited data.

Note that a 1-byte field is returned unaltered, no matter what

the field contains.

Example
EXEC CICS BIF DEEDIT
FIELD(CONTG)
LENGTH(9)

This removes all characters other than digits from CONTG, a

9-byte field, and returns the edited result in that field to the
application program. Two examples of the contents of
CONTG before and after execution of the command are:
Original value Returned value
14-67O4/B OO1467O4B
$25.68 OOOOO2568

Note that a decimal point is an EBCDIC special character

and as such is removed.

30 CICS/ESA Application Programming Reference

BUILD ATTACH (LUTYPE6.1)

Function
Specify values for an LUTYPE6.1 attach header.

Command syntax

──BUILD ATTACH──ATTACHID(name)──┬───────────────┬──┬────────────────┬──┬────────────────┬────────────────
└─PROCESS(name)─┘ └─RESOURCE(name)─┘ └─RPROCESS(name)─┘
──┬─────────────────┬──┬─────────────┬──┬────────────────────┬──┬─────────────────────┬───────────────────
└─RRESOURCE(name)─┘ └─QUEUE(name)─┘ └─IUTYPE(data-value)─┘ └─DATASTR(data-value)─┘
──┬───────────────────┬──"
└─RECFM(data-value)─┘

BUILD ATTACH (LUTYPE6.1) specifies a set of values to be O–7 reserved - must be set to zero
placed in the named attach header control block. This 8-11 OOOO - user-defined
control block contains values that are to be sent in an 1111 - SCS data stream
LUTYPE6.1 attach FMH (Function Management Header) that 111O - 327O data stream
is constructed by CICS, and is sent only when a SEND 11O1 - structured field
11OO - logical record management
ATTACHID or CONVERSE ATTACHID command is
12-15 defined by the user if bits 8-11
executed. The specified values override existing values in
are set to OOOO; otherwise reserved
the control block; unspecified values are set to default (must be set to zero)
values.
A value of “structured field” indicates that chains begin
with four bytes of data that are used to interpret the
BUILD ATTACH (LUTYPE6.1) options following data: overall length (2 bytes), class identifier (1
byte), and subclass identifier (1 byte). A value of “logical
ATTACHID(name)
record management” indicates that chains can be split
specifies that the set of values is to be placed in an
into separate fields by the data receiver.
attach header control block identified by the specified
name (1–8 characters). If the option is omitted, a value of “user-defined” is
assumed.
DATASTR(data-value)
corresponds to the data stream profile field, ATTDSP, in IUTYPE(data-value)
an LUTYPE6.1 attach FMH. corresponds to the interchange unit field, ATTIU, in an
LUTYPE6.1 attach FMH.
For communication between two CICS systems, no
particular significance is attached by CICS to the data The “data-value” is a halfword binary. Only the
stream profile field in an attach FMH. For most CICS low-order 7 bits are used. The SNA-defined meanings
applications, the option can be omitted. of the bits are as follows:
Information about CICS to IMS communication is given O–1O reserved - must be set to zero
in the CICS/ESA Intercommunication Guide. For details 11 O - not end of multichain
of communication between a CICS system and any interchange unit
other subsystem, including details of structured fields 1 - end of multichain
and logical record management, refer to documentation interchange unit
12,13 reserved - must be set to zero
supplied by the subsystem about how to use the data
14,15 OO - multichain interchange
stream profile field in an attach FMH. unit
The “data-value” is a halfword binary. Only the O1 - single-chain
low-order byte is used. The SNA-defined meanings of interchange unit
the bits are as follows: 1O - reserved
11 - reserved
If the option is omitted, values of “not end of multichain
interchange unit” and “multichain interchange unit” are
assumed.

Chapter 1. Commands 31
BUILD ATTACH (LUTYPE6.1)

PROCESS(name) RPROCESS(name)
corresponds to the process name, ATTDPN, in an corresponds to the return-process name, ATTRDPN, in
LUTYPE6.1 attach FMH. an LUTYPE6.1 attach FMH.
For communication between two CICS systems, a For communication between two CICS systems, no
transaction running in one system can acquire a session significance is attached by CICS to the return-process
to the second system and can identify the transaction to name in an attach FMH.
be attached; in the second system, the identification is
For communication between a CICS system and another
carried in the first chain of data sent across the session.
subsystem, refer to documentation supplied by the
In general, the first four bytes of data identify the subsystem about how to use the return-process name
transaction to be attached. However an attach FMH, field in an attach FMH.
identifying the transaction to be attached, can be built
RRESOURCE(name)
and sent; the PROCESS option is used to specify the
corresponds to the return-resource name, ATTRPRN, in
transaction name. (Note that the receiving CICS system
an LUTYPE6.1 attach FMH.
uses just the first four bytes of the process name as a
transaction name.) For communication between two CICS systems, no
significance is attached by CICS to the return-resource
No significance is attached by CICS to process names in
name in an attach FMH.
attach FMHs sent in chains of data other than the first.
For communication between a CICS system and another
For communication between a CICS system and another
subsystem, refer to documentation supplied by the
subsystem, refer to documentation supplied by the
subsystem about how to use the return-resource name
subsystem about how to use the process name field in
field in an attach FMH.
an attach FMH.

QUEUE(name)
corresponds to the queue name, ATTDQN, in an
LUTYPE6.1 attach FMH.
For communication between two CICS systems, no
significance is attached by CICS to the queue name in
an attach FMH.
For communication between a CICS system and another
subsystem, refer to documentation supplied by the
subsystem about how to use the queue name field in an
attach FMH.

RECFM(data-value)
corresponds to the deblocking algorithm field, ATTDBA,
in an LUTYPE6.1 attach FMH.
For communication between two CICS systems, no
particular significance is attached by CICS to the
deblocking algorithm field in an attach FMH. For most
CICS applications, the option can be omitted.
The “data-value” is a halfword binary value. Only the
low-order byte is used. The SNA-defined meanings of
the bits are as follows:
O–7 reserved - must be set to zero
8-15 X'OO' - reserved
X'O1' - variable-length
variable-blocked
X'O2' - reserved
X'O3' - reserved
X'O4' - chain of RUs
X'O5'through X'FF' - reserved
If the option is omitted, a value of “chain of RUs” is
assumed.

RESOURCE(name)
corresponds to the resource name, ATTPRN, in an
LUTYPE6.1 attach FMH.

32 CICS/ESA Application Programming Reference

BUILD ATTACH (MRO)

Function
Specify values for an MRO attach header.

Command syntax

BUILD ATTACH (MRO) specifies a set of values to be following data; overall length (2 bytes), class identifier (1
placed in the named attach header control block. This byte), and subclass identifier (1 byte). A value of “logical
control block contains values that are to be sent in an MRO record management” indicates that chains can be split
attach FMH (Function Management Header) that is into separate fields by the data receiver.
constructed by CICS, and is sent only when a SEND
If the option is omitted, a value of “user-defined” is
ATTACHID or CONVERSE ATTACHID command is
assumed.
executed. The specified values override existing values in
the control block; unspecified values are set to default IUTYPE(data-value)
values. corresponds to the interchange unit field, ATTIU, in an
LUTYPE6.1 attach FMH.
For more information about MRO and IRC, see the
The “data-value” is a halfword binary. Only the
CICS/ESA Intercommunication Guide.
low-order 7 bits are used. The SNA-defined meanings
of the bits are as follows:
BUILD ATTACH (MRO) options O–1O reserved - must be set to zero
ATTACHID(name) 11 O - not end of multichain interchange unit
1 - end of multichain interchange unit
specifies that the set of values is to be placed in an
12,13 reserved - must be set to zero
attach header control block identified by the specified
14,15 OO - multichain interchange unit
name (1–8 characters). O1 - single chain interchange unit
DATASTR(data-value) 1O - reserved
corresponds to the data stream profile field, ATTDSP, in 11 - reserved
an LUTYPE6.1 attach FMH. If the option is omitted, values of “not end of multichain
For communication between two CICS systems, no interchange unit” and “multichain interchange unit” are
particular significance is attached by CICS to the data assumed.
stream profile field in an attach FMH. For most CICS PROCESS(name)
applications, the option can be omitted. corresponds to the process name, ATTDPN, in an
The “data-value” is a binary halfword. Only the LUTYPE6.1 attach FMH.
low-order byte is used. The SNA-defined meanings of For communication between two CICS systems, a
the bits are as follows: transaction running in one system can acquire a session
O–7 reserved - must be set to zero to the second system and can identify the transaction to
8-11 OOOO - user-defined be attached; in the second system the identification is
1111 - SCS data stream carried in the first chain of data sent across the session.
111O - 327O data stream In general, the first four bytes of data identify the
11O1 - structured field transaction to be attached. However an attach FMH,
11OO - logical record management identifying the transaction to be attached, can be built
12-15 defined by the user if bits 8-11 and sent; the PROCESS option is used to specify the
are set to OOOO; otherwise reserved
transaction name. (Note that the receiving CICS system
(must be set to zero)
uses just the first four bytes of the process name as a
A value of “structured field” indicates that chains begin transaction name.)
with four bytes of data that are used to interpret the

Chapter 1. Commands 33
BUILD ATTACH (MRO)

No significance is attached by CICS to process names in

attach FMHs sent in chains of data other than the first.
For communication between a CICS system and another
subsystem, refer to documentation supplied by the
subsystem about how to use the process name field in
an attach FMH.

QUEUE(name)
corresponds to the queue name, ATTDQN, in an attach
FMH.
For communication between two CICS systems, no
significance is attached by CICS to the queue name in
an attach FMH.
For communication between a CICS system and another
subsystem, refer to documentation supplied by the
subsystem about how to use the queue name field in an
attach FMH.

RECFM(data-value)
corresponds to the deblocking algorithm field, ATTDBA,
in an LUTYPE6.1 attach FMH.
For communication between two CICS systems, no
particuorithm field,gES ponds to the o7ubsystem about how to use the queue name field in an
attach FMH.

RECFM(data-value)
CANCEL

CANCEL

Function
Cancel interval control requests.

Command syntax

| ──CANCEL──┬───────────────────────────────────────────────────────┬──"
| └─REQID(name)──┬───────────────┬──┬───────────────────┬─┘
| └─TRANSID(name)─┘ └─SYSID(systemname)─┘
| Conditions:
| ISCINVREQ, NOTAUTH, NOTFND, SYSIDERR

| Note for dynamic transaction routing

| Using CANCEL with REQID (of a POST, DELAY, or START) could create inter-transaction affinities that adversely affect
| the use of dynamic transaction routing. See the CICS/ESA Application Programming Guide for more information about
| transaction affinities.

CANCEL cancels a previously issued DELAY, POST, or CANCEL options

START command. If you include the SYSID option, the
command is shipped to a remote system. If you omit SYSID, REQID(name)
the TRANSID option, if present, indicates where the specifies a name (1–8 characters), which should be
command is to be executed. The effect of the cancelation unique, to identify a command. This name is used as a
varies depending on the type of command being canceled, temporary storage identifier. The temporary storage
as follows: queue thus identified must be defined as a local queue
on the CICS system where the CANCEL command is
A DELAY command can be canceled only before it has processed.
expired, and only by a task other than the task that
issued the DELAY command (which is suspended for This option cannot be used to cancel a POST command
the duration of the request). The REQID used by the issued by the same task (for which, the REQID option is
suspended task must be specified. The effect of the ignored if it is specified).
cancelation is the same as an early expiration of the SYSID(systemname) — remote systems only
original DELAY. That is, the suspended task becomes specifies the name (1–4 characters) of the system for
dispatchable as though the original expiration time had the CANCEL command.
been reached.
TRANSID(name)
When a POST command issued by the same task is to
# specifies the symbolic identifier (1–4 characters) of a
be canceled, no REQID need be specified. Cancelation
# transaction to be used to determine where the CANCEL
can be requested either before or after the original
# command is to be executed, if SYSID is not specified. If
request has expired. The effect of the cancelation is as
# the TRANSID is defined as REMOTE, the CANCEL
if the original request had never been made.
# request is function-shipped to the remote system. If
When a POST command issued by another task is to be SYSID is specified, the transaction is assumed to be on
canceled, the REQID of that command must be a remote system.
specified. The effect of the cancelation is the same as
an early expiration of the original POST request. That
is, the timer event control area for the other task is
posted as though the original expiration time had been
reached.
When a START command is to be canceled, the REQID
of the original command must be specified. The effect
of the cancelation is as if the original command had
never been made. The cancelation is effective only
before the original command has expired.

Chapter 1. Commands 35
CANCEL

CANCEL conditions
ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

NOTAUTH
| occurs when a resource security check has failed on the
| specified TRANSID or on the TRANSID of the START
| command that corresponds to the request identification.
Default action: terminate the task abnormally.

NOTFND
occurs if the request identifier specified fails to match an
unexpired interval control command.
Default action: terminate the task abnormally.

SYSIDERR
| occurs when the SYSID option specifies a name that is
| neither the local system nor a remote system (made
| known to CICS by defining a CONNECTION). It also
occurs when the link to the remote system is closed.
Default action: terminate the task abnormally.

36 CICS/ESA Application Programming Reference

CHANGE PASSWORD

| CHANGE PASSWORD

| Function
| Change the password recorded by an external security manager (ESM) for a specified userid.

| CHANGE PASSWORD options | Default action: terminate the task abnormally.

| USERID(data-value)
| specifies the userid, 8 characters, of the user whose
| password is being changed.

Chapter 1. Commands 37
CHANGE TASK

CHANGE TASK

Function
Change priority of a task.

Command syntax

──CHANGE TASK──┬──────────────────────┬──"
| └─PRIORITY(data-value)─┘
Conditions:
INVREQ

CHANGE TASK changes the priority of the issuing task. It

has immediate effect (unlike SET TASK), because control is
relinquished during execution of the command so that the
current task has to be redispatched. The redispatch does
not happen until tasks that are of higher or equal priority, and
that are also ready to run, are dispatched.

RCF 11362/11353
Documentation for RCFs 11362 and 11353 added
22/11/96

If you omit the PRIORITY option, the task does not lose
control and the priority remains the same. This is effectively
a no-op.

CHANGE TASK option

PRIORITY(data-value)
specifies a fullword binary value in the range 0–255,
| defining the priority of the task. You can also have a
| value of −1 but this does not change the priority or
| cause a redispatch.

CHANGE TASK condition

INVREQ
means that your PRIORITY value is outside the range
0–255 (RESP2=1).

38 CICS/ESA Application Programming Reference

CONNECT PROCESS

Function
Initiate APPC mapped conversation.

Command syntax

──CONNECT PROCESS──┬─CONVID(name)──┬──┬─PROCNAME(data-area)──┬────────────────────────┬─┬────────────────
└─SESSION(name)─┘ │ └─PROCLENGTH(data-value)─┘ │
| └─PARTNER(name)───────────────────────────────────┘
──┬───────────────────────────────────────────────┬──SYNCLEVEL(data-value)──┬─────────────┬──"
└─PIPLIST(data-area)──┬───────────────────────┬─┘ └─STATE(cvda)─┘
└─PIPLENGTH(data-value)─┘
Conditions:
| INVREQ, LENGERR, NOTALLOC, PARTNERIDERR, TERMERR

CONNECT PROCESS allows an application to specify a One byte is sufficient to identify a CICS transaction. The
process name and synchronization level to be passed to APPC architecture allows a range of 1–64 bytes but
CICS and used when the remote partner is attached. leaves each product free to set its own maximum. CICS
complies by allowing a range of 1–64 bytes. If the
remote system is CICS, this option can specify the
CONNECT PROCESS options 4-byte transaction identifier or the TPNAME value given
CONVID(name) in the relevant TRANSACTION definition. Alternatively,
identifies, as a 4-character name, the conversation which you can examine the full identifier by coding the user
the command relates to. The name specifies the token exit XZCATT.
returned by a previously executed ALLOCATE command | No character checking is performed on the TPN by
in EIBRSRCE in the EIB. | CICS.
For compatibility with earlier releases, SESSION is For programming information about the user exit
accepted as a synonym for CONVID. New programs XZCATT, see the CICS/ESA Customization Guide.
should use CONVID.
SESSION(name)
| PARTNER(name) specifies the symbolic identifier (1–4 characters) of a
| specifies the name (8 characters) of a set of definitions session TCTTE. This option specifies the alternate
| that includes the name (or extended name) of a remote facility to be used.
| partner transaction (TPNAME or XTPNAME). You can
| use this option as an alternative to PROCNAME and STATE(cvda)
| PROCLENGTH. gets the state of the current conversation. The cvda
values returned by CICS are:
PIPLENGTH(data-value)
specifies the total length (halfword binary value) of the ALLOCATED
specified process initialization parameter (PIP) list. CONFFREE
CONFRECEIVE
PIPLIST(data-area) CONFSEND
specifies the PIP data to be sent to the remote system. FREE
The PIP list consists of variable-length records, each PENDFREE
containing a single PIP. A PIP starts with a 2-byte PENDRECEIVE
inclusive length field (LL), followed by a 2-byte reserved RECEIVE
field, and then the parameter data. ROLLBACK
PROCLENGTH(data-value) SEND
specifies the length (as a halfword binary value in the SYNCFREE
range 1–64) of the name specified by the PROCNAME SYNCRECEIVE
option. SYNCSEND

PROCNAME(data-area)
specifies the partner process (that is, the transaction) to
be attached in the remote system.

Chapter 1. Commands 39
CONNECT PROCESS

SYNCLEVEL(data-value) A CANCEL TASK request by a user node error program

specifies the synchronization level (halfword binary (NEP) can cause this condition if the task has an
value) for the current conversation. The possible values outstanding terminal control request active when the
are: node abnormal condition program handles the session
error.
0 None
1 Confirm Default action: terminate the task abnormally with abend
2 Syncpoint. code ATNI.

CONNECT PROCESS conditions

INVREQ
occurs in any of the following situations:

A synchronization level other than 0, 1, or 2, has

been requested in the SYNCLEVEL option.
The command is not valid for the terminal or LU in
use.
The command has been used on a conversation
that is in use by CPI-Communications or that is an
APPC basic conversation. In the latter case, GDS
CONNECT PROCESS should have been used.
A distributed program link server application
specified the function-shipping session (its principal
facility) on the CONVID option (RESP2=200).

Default action: terminate the task abnormally.

LENGERR
occurs in any of the following situations:

An out-of-range value is supplied in the

PROCLENGTH option.
The value specified in the PIPLENGTH option is
less than 0.
The value specified in the PIPLENGTH option
exceeds the CICS implementation limit of 32 763.
A PIPLIST length element (LL) has a value less
than 4.
The sum of the length elements (LLs) in the
PIPLIST does not equal the value specified by
PIPLENGTH.

Default action: terminate the task abnormally.

NOTALLOC
occurs if the specified CONVID value does not relate to
a conversation owned by the application.
Default action: terminate the task abnormally.

| PARTNERIDERR
| occurs if the name specified in the PARTNER option is
| not recognized by CICS.
| Default action: terminate the task abnormally.

TERMERR
occurs for a session-related error. Any action on that
conversation other than a FREE causes an ATCV
abend.

40 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

CONVERSE (VTAM default)

Function
Communicate on standard CICS terminal support.

Command syntax

This form of the CONVERSE command is used by all CICS-supported VTAM terminals for which the other CONVERSE
descriptions are not appropriate.

CONVERSE (APPC)

Function
Communicate on an APPC mapped conversation.

Command syntax

──CONVERSE──┬──────────────┬──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬──────────
└─CONVID(name)─┘ └─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬──┬─────────────┬──"
└─TOFLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘ └─STATE(cvda)─┘
| └─MAXFLENGTH(data-value)─┘
Conditions:
EOC, INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

CONVERSE sends, then receives, data on an APPC mapped conversation.

Chapter 1. Commands 41
CONVERSE (VTAM)

CONVERSE (LUTYPE2/LUTYPE3)

Function
Communicate on a 3270-display logical unit (LUTYPE2) or 3270-printer logical unit (LUTYPE3).

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─┬──────────────────────┬──┬─────────────────────┬─┬──┬─TOLENGTH(data-area)──┬─────────────────────────
| │ └─ERASE──┬───────────┬─┘ └─CTLCHAR(data-value)─┘ │ └─TOFLENGTH(data-area)─┘
| │ ├─DEFAULT───┤ │
| │ └─ALTERNATE─┘ │
└─STRFIELD──────────────────────────────────────────┘
──┬────────────────────────┬──┬─────────┬──┬────────────┬──┬──────┬──"
| ├─MAXLENGTH(data-value)──┤ └─DEFRESP─┘ └─NOTRUNCATE─┘ └─ASIS─┘
| └─MAXFLENGTH(data-value)─┘
Conditions:
| EOC, LENGERR, TERMERR

CONVERSE communicates on a 3270-display logical or 3270-printer logical unit.

CONVERSE (LUTYPE4)

Function
Communicate on an LUTYPE4 logical unit.

Command syntax

CONVERSE communicates on an LUTYPE4 logical unit.

42 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

CONVERSE (LUTYPE6.1)

Function
Communicate on an LUTYPE6.1 logical unit.

Command syntax

──CONVERSE──┬───────────────────────────────────────────────────────┬──┬───────────────┬─────────────────
└─FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─────┬─┘ ├─CONVID(name)──┤
└─FROMFLENGTH(data-value)─┘ └─FMH─┘ └─SESSION(name)─┘
──┬────────────────┬──┬─INTO(data-area)─┬──┬─TOLENGTH(data-area)──┬──┬────────────────────────┬───────────
| └─ATTACHID(name)─┘ └─SET(ptr-ref)────┘ └─TOFLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤
| └─MAXFLENGTH(data-value)─┘
──┬────────────┬──┬─────────┬──"
└─NOTRUNCATE─┘ └─DEFRESP─┘
Conditions:
CBIDERR, EOC, INBFMH, LENGERR, NOTALLOC, SIGNAL, TERMERR

CONVERSE communicates on an LUTYPE6.1 logical unit.

CONVERSE (SCS)

Function
Communicate on a 3270 SCS printer logical unit.

Command syntax

CONVERSE communicates on a 3270 SNA character string (SCS) printer logical unit. The SCS printer logical unit accepts a
character string as defined by Systems Network Architecture (SNA). Some devices connected under SNA can send a signal
that can be detected by the HANDLE CONDITION SIGNAL command, which in turn can invoke an appropriate handling
routine. If necessary, a WAIT SIGNAL command can be used to make the application program wait for the signal. The PA
keys on a 3287 can be used in this way, or with a RECEIVE command.

Chapter 1. Commands 43
CONVERSE (VTAM)

CONVERSE (3270 logical)

Function
Communicate on a 3270 logical unit.

Command syntax

CONVERSE communicates on a 3270 logical unit.

CONVERSE (3600-3601)

Function
Communicate on a 3600 (3601) logical unit.

Command syntax

CONVERSE communicates on a 3600 logical unit. This form of the CONVERSE command also applies to the 4700 and the
3630 plant communication system.

A logical device code (LDC) is a code that can be included in an outbound FMH (Function Management Header) to specify the
disposition of the data (for example, to which subsystem terminal it should be sent). Each code can be represented by a
unique LDC mnemonic.

The installation can specify up to 256 2-character mnemonics for each TCTTE, and two or more TCTTEs can share a list of
these mnemonics. A numeric value (0 through 255) corresponds to each LDC mnemonic for each TCTTE.

A 3600 device and a logical page size are also associated with an LDC. “LDC” or “LDC value” is used in this book to refer to
the code specified by the user; “LDC mnemonic” refers to the 2-character symbol that represents the LDC numeric value.

44 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

When the LDC option is specified in the CONVERSE command, the numeric value associated with the mnemonic for the
particular TCTTE is inserted in the FMH. This value is chosen by the installation, and is interpreted by the 3601 application
program.

# On output, the FMH can be built by the application program or by CICS. If your program supplies the FMH, you place it at the
# front of your output data and specify the FMH option on your CONVERSE command. If you omit the FMH option, CICS will
# provide an FMH but you must reserve the first three bytes of the message for CICS to fill in.

CONVERSE (3600-3614)

Function
Communicate on a 3600 (3614) logical unit.

Command syntax

CONVERSE communicates on a 3600 logical unit.

The data stream and communication format used between a CICS application program and a 3614 is determined by the 3614.
The application program is therefore device dependent when handling 3614 communication.

For further information about designing 3614 application programs for CICS, refer to the CICS/OS/VS IBM 4700/3600/3630
Guide.

CONVERSE (3650 interpreter)

Function
Communicate on a 3650 interpreter logical unit.

Command syntax

CONVERSE communicates on a 3650 interpreter logical unit.

Chapter 1. Commands 45
CONVERSE (VTAM)

CONVERSE (3650-3270)

Function
Communicate on a 3650 host conversational (3270) logical unit.

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬─────────────────────┬──┬──────────────────────┬──┬─────────┬──┬─────┬───────
└─TOFLENGTH(data-area)─┘ └─CTLCHAR(data-value)─┘ └─ERASE──┬───────────┬─┘ └─DEFRESP─┘ └─FMH─┘
| ├─DEFAULT───┤
| └─ALTERNATE─┘
──┬────────────────────────┬──┬────────────┬──"
| ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─MAXFLENGTH(data-value)─┘
Conditions:
LENGERR, TERMERR

CONVERSE communicates on a 3650 host conversational logical unit.

CONVERSE (3650-3653)

Function
Communicate on a 3650 host conversational (3653) logical unit.

Command syntax

CONVERSE communicates on a 3650 host conversational logical unit.

46 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

CONVERSE (3650-3680)

Function
Communicate on a 3650 host command processor (3680) logical unit.

Command syntax

CONVERSE communicates on a 3650 host command processor logical unit.

CONVERSE (3767)

Function
Communicate on a 3767 interactive logical unit.

Command syntax

CONVERSE communicates on a 3767 interactive logical unit. This command also applies to the 3770 interactive logical unit.

Chapter 1. Commands 47
CONVERSE (VTAM)

CONVERSE (3770)

Function
Communicate on a 3770 batch logical unit.

Command syntax

CONVERSE communicates on a 3770 batch logical unit.

CONVERSE (3790 full-function or inquiry)

Function
Communicate on a 3790 full-function or inquiry logical unit.

Command syntax

CONVERSE communicates on a 3790 full-function or inquiry logical unit.

48 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

CONVERSE (3790 3270-display)

Function
Communicate on a 3790 (3270-display) logical unit.

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬─────────┬──┬─────────────────────┬──────────────────────────────────────────
└─TOFLENGTH(data-area)─┘ └─DEFRESP─┘ └─CTLCHAR(data-value)─┘
──┬──────────────────────────────────────────────────────────────────┬──"
| └─ERASE──┬───────────┬──┬────────────────────────┬──┬────────────┬─┘
| ├─DEFAULT───┤ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─ALTERNATE─┘ └─MAXFLENGTH(data-value)─┘
Conditions:
LENGERR, TERMERR

CONVERSE communicates on a 3790 logical unit.

Chapter 1. Commands 49
CONVERSE (VTAM)

CONVERSE (VTAM) options option is meaningful only for terminals defined using
DFHTCT TYPE=SDSCI with DEVICE=TCAM.
| ALTERNATE
If you use the DEST option, you must be aware of any
| sets the terminal to use the ALTERNATE screen size.
restrictions placed on device-dependent data streams by
ASIS the message control facility in use. See the section on
indicates that output is to be sent in transparent mode CICS-TCAM interface in the CICS/ESA Customization
(with no recognition of control characters and accepting Guide for programming information.
any of the 256 possible combinations of eight bits as
ERASE
valid transmittable data).
specifies that the screen printer buffer or partition is to
Note: If you are using a katakana terminal, you might be erased and the cursor returned to the upper left
see some messages containing mixed English and corner of the screen. (This option applies only to the
katakana characters. That is because katakana 3270, or 8775, and to the 3604 Keyboard Display.)
terminals cannot display mixed-case output. Uppercase
The first output operation in any transaction, or in a
characters in the data stream appear as uppercase
series of pseudoconversational transactions, should
English characters, but lowercase characters appear as
always specify ERASE. For transactions attached to
katakana characters. If this happens, ask your system
| 3270 screens or printers, unless explicitly overridden by
programmer to specify MSGCASE=UPPER in the
| the DEFAULT or ALTERNATE option, this also ensures
system initialization parameters so that messages
that the correct screen size is selected, as defined for
contain uppercase characters only. This note applies to
| the transaction by the SCRNSZE option in the profile
any command that is used to receive katakana
| definition.
characters, not just to CONVERSE commands.
FMH
ATTACHID(name)
specifies that a function management header has been
specifies that an attach header (created by a BUILD
included in the data to be written. If the ATTACHID
ATTACH command) is to precede, and be concatenated
option is specified as well, the concatenated FMH flag is
with, the user data supplied in the FROM option.
# set in the attach FMH. The use of FMH is optional and
“name” (1–8 characters) identifies the attach header
# is not supported for all terminal types. If not supplied,
control block to be used in the local task.
# CICS takes no action, except for 3600/4700 terminals,
CONVID(name) # where an FMH is mandatory. In this case, if FMH is not
identifies the conversation to which the command # specified, CICS supplies one and places it in the first 3
relates. The 4-character name identifies either the token # bytes of the message, which you must reserve for this
returned by a previously executed ALLOCATE command # purpose.
in EIBRSRCE in the EIB, or the token representing the
FROM(data-area)
principal session (returned by a previously executed
specifies the data to be written to the terminal or logical
ASSIGN command).
unit, or sent to the partner transaction. This option may,
For compatibility with earlier releases, SESSION is when relevant, be omitted if ATTACHID is specified.
accepted as a synonym for CONVID. New programs
should use CONVID. FROMFLENGTH(data-value)
is a fullword alternative to FROMLENGTH.
| If the option is omitted, the principal facility for the task is
| used by default. FROMLENGTH(data-value)
specifies the length, as a halfword binary value, of the
CTLCHAR(data-value) data. For a description of a safe upper limit, see
specifies a 1-byte write control character (WCC) that “LENGTH options” on page 5.
controls the CONVERSE command. A COBOL user
must specify a data area containing this character. INTO(data-area)
specifies the receiving field for the data read from the
If the option is omitted, all modified data tags are reset
terminal or logical unit, or the application target data
to zero, and the keyboard is restored.
area into which data is to be received from the
| DEFAULT application program connected to the other end of the
| sets the terminal to use the DEFAULT screen size. current conversation.

DEFRESP LDC(name)
indicates that a definite response is required when the specifies the 2-character mnemonic used to determine
output operation has been completed. the appropriate logical device code (LDC) numeric value.
The mnemonic identifies an LDC entry in the terminal
DEST(name) control table TYPE=LDC.
specifies the 4-byte symbolic name of the TCAM
destination to which the message is to be sent. This

50 CICS/ESA Application Programming Reference

CONVERSE (VTAM)

MAXFLENGTH(data-value) ALLOCATED
is a fullword alternative to MAXLENGTH. CONFFREE
CONFRECEIVE
MAXLENGTH(data-value)
CONFSEND
specifies the maximum amount (halfword binary value)
FREE
of data that CICS is to recover in response to a
PENDFREE
CONVERSE (default) command. If INTO is specified,
PENDRECEIVE
MAXLENGTH overrides the use of TOLENGTH as an
RECEIVE
input to CICS. If SET is specified, MAXLENGTH
ROLLBACK
provides a way for the program to limit the amount of
SEND
data it receives at one time.
SYNCFREE
| If the value specified is less than zero, zero is assumed. SYNCRECEIVE
SYNCSEND
If the length of data exceeds the value specified and the
NOTRUNCATE option is not present, the data is STRFIELD
truncated to that value and the LENGERR condition specifies that the data area specified in the FROM
occurs. The data area specified in the TOLENGTH option contains structured fields. If this option is
option is set to the original length of data. specified, the contents of all structured fields must be
If the length of data exceeds the value specified and the handled by the application program. The CONVERSE
NOTRUNCATE option is present, CICS retains the command must be used if the data area contains a read
remaining data and uses it to satisfy subsequent partition structured field. (Structured fields are described
RECEIVE commands. The data area specified in the in the CICS/ESA 3270 Data Stream Device Guide.)
TOLENGTH option is set to the length of data returned. CTLCHAR and ERASE are mutually exclusive with
If no argument is coded for MAXLENGTH, CICS defaults STRFIELD, and their use with STRFIELD generates an
to TOLENGTH. error message.

NOTRUNCATE TOFLENGTH(data-area)
specifies that, when the data available exceeds the is a fullword alternative to TOLENGTH.
length requested, the remaining data is not to be
TOLENGTH(data-area)
discarded but is to be retained for retrieval by
specifies the length (halfword binary value) of the data to
subsequent RECEIVE commands.
be received. If you specify INTO, but omit
SESSION(name) MAXLENGTH, “data-area” specifies the maximum length
specifies the symbolic identifier (1–4 characters) of a that the program accepts. If the value is less than zero,
session TCTTE. This option specifies the alternate zero is assumed.
facility to be used. If both this option and CONVID are If the length of the data exceeds the value specified, but
omitted, the principal facility for the task is used. NOTRUNCATE is omitted, the data is truncated to that
value, and the LENGERR condition occurs. When the
SET(ptr-ref)
data is received, the data area is set to the length of the
specifies the pointer reference to be set to the address
data.
of the data read from the terminal. pointer reference,
unless changed by other commands or statements, is For a description of a safe upper limit, see “LENGTH
valid until the next CONVERSE (default) command or options” on page 5.
the end of task.
If DATALOCATION(ANY) is associated with the CONVERSE (VTAM) conditions
application program, the address of the data can be Some of the following conditions can occur in combination
above or below the 16MB line. with others. CICS checks for these conditions in the
If DATALOCATION(BELOW) is associated with the following order:
application program, and the data resides above the 1. EODS
16MB line, the data is copied below the 16MB line, and 2. INBFMH
the address of this copy is returned. 3. EOC.
If TASKDATAKEY(USER) is specified for the running
task, and storage protection is active, the data returned If more than one occurs, only the first is passed to the
is in a user-key. If TASKDATAKEY(CICS) is specified application program. EIBRCODE, however, is set to indicate
and storage protection is active, the data returned is in a all the conditions that occurred.
CICS-key. CBIDERR
STATE(cvda) occurs if the requested attach header control block
gets the state of the current conversation. The cvda named in ATTACHID cannot be found.
values returned by CICS are:

Chapter 1. Commands 51
CONVERSE (VTAM)

Default action: terminate the task abnormally. SIGNAL

occurs when an inbound SIGNAL data-flow control
EOC
command is received from a logical unit or session, or
occurs when a request/response unit (RU) is received
the partner transaction. EIBSIG is always set when an
with the end-of-chain indicator set. Field EIBEOC also
inbound signal is received.
contains this indicator.
Default action: ignore the condition.
Default action: ignore the condition.
TERMERR
EODS
occurs for a terminal or session-related error. Any
occurs when an end-of-data-set indicator is received.
action on that conversation other than a FREE causes
Default action: terminate the task abnormally. an ATCV abend.

IGREQCD A CANCEL TASK request by a user node error program

occurs when an attempt is made to execute a (NEP) may cause this condition if the task has an
CONVERSE command after a SIGNAL data-flow control outstanding terminal control request active when the
command with a request change direction (RCD) code node abnormal condition program handles the session
has been received from an LUTYPE4 logical unit. error.

Default action: terminate the task abnormally. Default action: terminate the task abnormally with abend
code ATNI.
INBFMH
occurs if a request/response unit (RU) contains a
function management header (FMH). Field EIBFMH
contains this indicator and it should be used in
preference to INBFMH. The IGNORE CONDITION
command can be used to ignore the condition.
Default action: terminate the task abnormally.

INVREQ
occurs in any of the following situations:

The command is used on a conversation that is in

use by CPI Communications, or that is an APPC
basic conversation. In the latter case, the
application should have issued a GDS SEND
INVITE followed by a GDS RECEIVE.
A distributed program link server application
specified the function shipping session (its principal
facility) on the CONVID option (RESP2=200).

Default action: terminate the task abnormally.

LENGERR
occurs in any of the following situations:

Data received is discarded by CICS because its

length exceeds the maximum that the program
accepts (see TOLENGTH and MAXLENGTH
options), and the NOTRUNCATE option is not
specified.
An out-of-range value is supplied in one of the
options, FROMLENGTH, FROMFLENGTH,
MAXLENGTH, MAXFLENGTH, TOLENGTH, or
TOFLENGTH.

Default action: terminate the task abnormally.

NOTALLOC
occurs if the facility specified in the command is not
owned by the application, or does not relate to a
conversation owned by the application.
Default action: terminate the task abnormally.

52 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

CONVERSE (non-VTAM default)

Function
Communicate on standard CICS terminal support.

Command syntax

This form of the CONVERSE command is used by all CICS-supported terminals for which the other CONVERSE descriptions
are not appropriate.

CONVERSE (MRO)

Function
Communicate on an MRO session.

Command syntax

──CONVERSE──┬───────────────┬──┬────────────────┬────────────────────────────────────────────────────────
├─CONVID(name)──┤ └─ATTACHID(name)─┘
└─SESSION(name)─┘
──┬───────────────────────────────────────────────────────┬──┬─INTO(data-area)─┬──────────────────────────
└─FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─────┬─┘ └─SET(ptr-ref)────┘
└─FROMFLENGTH(data-value)─┘ └─FMH─┘
──┬─TOLENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬──┬─────────┬──┬─────────────┬──"
| └─TOFLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘ └─DEFRESP─┘ └─STATE(cvda)─┘
| └─MAXFLENGTH(data-value)─┘
Conditions:
CBIDERR, EOC, INBFMH, LENGERR, NOTALLOC, TERMERR

CONVERSE communicates on an MRO session. For more information about MRO and IRC, see the CICS/ESA
Intercommunication Guide.

Chapter 1. Commands 53
CONVERSE (non-VTAM)

CONVERSE (System/3)

Function
Communicate on a System/3 terminal.

Command syntax

CONVERSE communicates on a System/3 terminal. CONVERSE in this form also applies to the following devices:
2770 data communication system
2780 data transmission terminal
3660 supermarket scanning system
3780 communication terminal.

CONVERSE (System/7)

Function
Communicate on a System/7 terminal.

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬────────────┬──┬──────┬──┬───────────┬──"
└─TOFLENGTH(data-area)─┘ └─DEST(name)─┘ └─ASIS─┘ └─PSEUDOBIN─┘
Conditions:
LENGERR

CONVERSE communicates on a System/7 terminal.

Transactions are normally initiated from the System/7 by issuing a 4-character transaction code that is transmitted in BCD
mode. Pseudobinary mode can be used only while communicating with an active CICS transaction; it cannot be used to
initiate the transaction. The message length is given as the number of words to be transmitted (not as the number of
characters).

When a transaction is initiated on a System/7, CICS services that System/7 only for the duration of the transaction; that is, to
ensure efficient use of the line, any other System/7s on the same line are locked out for the duration of the transaction. CICS
application programs for the multipoint System/7 should be designed with the shortest possible execution time.

The first word (two characters) of every message sent to the System/7 must be an identification word, except words beginning
with “@”, which are reserved by CICS.

54 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

When the PSEUDOBIN option is specified on RECEIVE or SEND, the length of the data area provided by the application
program must be at least twice that of the data to be read.

In the case of a System/7 on a dial-up (switched) line, the System/7 application program must, initially, transmit a
four-character terminal identification. (This terminal identification is generated during preparation of the TCT through use of the
DFHTCT TYPE=TERMINAL, TRMIDNT=parameter specification.) CICS responds with either a ‘ready’ message, indicating that
the terminal identifier is valid and that the System/7 may proceed as if it were on a leased line, or an ‘INVALID TERMINAL
IDENTIFICATION’ message, indicating that the terminal identifier sent by the System/7 did not match the TRMIDNT=
parameter specification.

Whenever CICS initiates the connection to a dial-up System/7, CICS writes a null message, consisting of three idle characters,
prior to starting the transaction. If there is no program resident in the System/7 capable of supporting the Asynchronous
Communication Control Adapter (ACCA), BTAM error routines cause a data check message to be recorded on the CICS (host)
system console. This is normal if the task initiated by CICS is to IPL the System/7. Although the data check message is
printed, CICS ignores the error and continues normal processing. If a program capable of supporting the ACCA is resident in
the System/7 at the time this message is transmitted, no data check occurs.

When a disconnect is issued to a dial-up System/7, the “busy” bit is sometimes left on in the interrupt status word of the ACCA.
If the line connection is reestablished by dialing from the System/7 end, the ‘busy’ condition of the ACCA prevents message
transmission from the System/7. To overcome this problem, the System/7 program must reset the ACCA after each disconnect
and before message transmission is attempted. This can be done by issuing the following instruction:
PWRI O,8,3,O RESET ACCA

This procedure is not necessary when the line is reconnected by CICS (that is, by an automatically initiated transaction).

CONVERSE (2260)

Function
Communicate on a 2260 or 2265 display station.

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬──┬─────────────────────┬───────────
| └─TOFLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘ └─CTLCHAR(data-value)─┘
| └─MAXFLENGTH(data-value)─┘
──┬──────────────────────┬──┬────────────┬──┬─────────┬──"
| └─LINEADDR(data-value)─┘ └─DEST(name)─┘ └─LEAVEKB─┘
Conditions:
LENGERR

CONVERSE communicates on a 2260 or 2265 display station.

Chapter 1. Commands 55
CONVERSE (non-VTAM)

CONVERSE (2741)

Function
Communicate on a 2741 communication terminal.

Command syntax

CONVERSE communicates on a 2741 terminal.

Read attention
If the terminal operator presses the attention key on the 2741 after typing a message, it is recognized as a read attention if:
Read attention is supported by the system
The message is read by a RECEIVE command.

When this occurs, control is transferred to a CICS read-attention exit routine, if it has been generated into the system. This
routine is a skeleton program that can be tailored by the system programmer to carry out actions such as the following:
Perform data analysis or modification on a read attention.
Return a common response to the terminal operator following a read attention.
Return a response and request additional input that can be read into the initial input area or into a new area.
Request new I/O without requiring a return to the task to request additional input.

When the read-attention exit routine is completed, control is returned to the application program at the address specified in the
HANDLE CONDITION RDATT command. The return is made when either of the following occurs:
The exit routine issues no more requests for input.
The exit routine issues a RECEIVE request and the operator terminates the input with a carriage return. (If the operator
terminates the input with an attention, the exit routine is reentered and is free to issue another RECEIVE request.)

If a HANDLE CONDITION RDATT command is not included in the application program or read attention is not supported, the
attention is treated as if the return key had been pressed.

Write break
If the terminal operator presses the attention key on the 2741 while a message is being received, it is recognized as a write
break if:
Write break is supported by the system.
A HANDLE CONDITION WRBRK command is active in the application program.

When this occurs, the remaining portion of the message is not sent to the terminal. The write is terminated as though it were
successful, and a new-line character (X'15') is sent to cause a carrier return. Control is returned to the application program at
the address specified for the WRBRK condition.

If a HANDLE CONDITION WRBRK command is not included in the application program or if write break is not supported, the
break is treated as an I/O error.

56 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

CONVERSE (2770)
The support and command syntax for 2770 is the same as for System/3, see“CONVERSE (System/3)” on page 54.

The 2770 recognizes a read interrupt and responds by transmitting the contents of the I/O buffer. After the contents of the
buffer have been transmitted, the 2770 responds to the next read continue with an EOT. If the I/O buffer is empty, the 2770
transmits an EOT. CICS issues a read interrupt and read continue to relinquish use of the line and to enable the application
program to write to the 2770.

Input from a 2770 consists of one or more logical records. CICS provides one logical record for each read request to the
application program. The size of a logical record cannot exceed the size of the I/O buffer. If the input spans multiple buffers,
multiple reads must be issued by the application program.

The 2265 component of the 2770 Data Communication System is controlled by data stream characters, not by BTAM macros;
appropriate screen control characters should be included in the output area.

For 2770 input, data is deblocked to ETX, ETB, RS, and US characters. These characters are moved with the data to the
input area but are not included in the data length; characters such as NL, CR, and LF are passed in the input area as data.

CONVERSE (2780)
The support and command syntax for 2780 is the same as for System/3, see “CONVERSE (System/3)” on page 54.

Output to a 2780 requires that the application program contains an appropriate “escape sequence” for component selection
associated with the output message. For details of the 2780, see the publication IBM 2780 Data Transmission Terminal:
Component Description.

Chapter 1. Commands 57
CONVERSE (non-VTAM)

CONVERSE (3270 display)

Function
Communicate on a 3270 information display system (TCAM).

Command syntax

──CONVERSE──FROM(data-area)──┬─FROMLENGTH(data-value)──┬──┬─INTO(data-area)─┬────────────────────────────
└─FROMFLENGTH(data-value)─┘ └─SET(ptr-ref)────┘
──┬─TOLENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬────────────────────────────────────
| └─TOFLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─MAXFLENGTH(data-value)─┘
──┬─┬──────────────────────┬──┬─────────────────────┬─┬──┬────────────┬──┬──────┬──"
| │ └─ERASE──┬───────────┬─┘ └─CTLCHAR(data-value)─┘ │ └─DEST(name)─┘ └─ASIS─┘
| │ ├─DEFAULT───┤ │
| │ └─ALTERNATE─┘ │
└─STRFIELD──────────────────────────────────────────┘
Conditions:
LENGERR

CONVERSE communicates on a 3270 information display system.

CONVERSE (3600 BTAM)

Function
| Communicate on a 3600 finance communication system (BTAM) - only valid for remote terminals.

Command syntax

CONVERSE communicates on a 3600 finance communication system. This form of the CONVERSE command also applies to
| the 4700 finance communication system. See “BTAM programmable terminals” on page 358.

58 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

Input
The unit of transmission from a 3601 Finance Communication Controller to CICS is a segment consisting of the start-of-text
data-link control character (STX), the 1-byte identification of the 3600 logical workstation that issued the processor write, the
data, and either an end-of-block (ETB) or an end-of-text (ETX) control character.

A logical workstation sends a message either in one segment, in which case the segment ends with ETX, or in more than one
segment, in which case only the last segment ends with ETX, all others ending with ETB.

The input area passed to the user-written application program consists of the data only. The 1-byte field TCTTEDLM, which
can be obtained using an ASSIGN DELIMITER command, contains flags describing the data-link control character (ETB, ETX,
or IRS) that ended the segment. The application program can issue terminal control commands to read the data until it
receives a segment ending with ETX. If blocked data is transmitted, it is received by CICS as blocks of segments. Only the
first segment in a block starts with the STX control character, and all segments are separated by IRS characters. None of the
segments contains ETB or ETX characters except the last, which has the ETX character.

For blocked input, the flags in TCTTEDLM only indicate end of segment, not end of message. The CICS application program
still receives only the data, but user-defined conventions may be required to determine the end of the message.

The field TCTTEDLM also indicates the mode of the input, either transparent or nontransparent. Blocked input is
nontransparent.

The terminal control facility does not pass input containing a start-of-header (SOH) data-link control character to a user-written
application program. If it receives an SOH, it sets an indicator in TCTTEDLM, passes the input to the user exit in the terminal
control facility, and then discards it.

Output
When an application program issues a SEND command, the terminal control facility determines, from the value specified in the
BUFFER parameter of the DFHTCT TYPE=TERMINAL system macro, the number of segments to be built for the message. It
sends the message to the 3600 logical unit either in one segment consisting of a start-of-text character (STX), the data, and an
end-of-text character (ETX); or in more than one segment, in which case only the last ends with ETX, all others ending with
ETB.

The host input buffer of the 3600 controller and the input segment of the receiving logical unit must be large enough to
accommodate the data sent by CICS. However, space for the data-link control characters need not be included. The 3600
application program reads the data from the host, by means of an LREAD, until it has received the entire message.

CICS system output messages begin with DFH followed by a 4-byte message number and the message text. These
messages are sent in nontransparent mode. CICS user-written application programs should not send messages starting with
DFH to the 3601.

Resend message
When a logical unit sends a message to the host and a ‘short on storage’ condition exists or the input is unsolicited (the active
task associated with the terminal has not issued a read), the terminal control facility sends a “resend” message to the logical
unit. No message is sent to the destinations CSMT or CSTL.

The first eight bytes of data sent to CICS can be used by the 3600 application program to define a convention to associate
responses received from CICS with transactions sent to the host; for example, sequence numbers could be used.

If a CICS user-written application program has already issued a SEND command when a resend situation occurs, the resend
message is not sent to the 3601 until the user-written application program message has been sent. A 3600 logical unit cannot
receive a resend message while receiving a segmented message.

Only one resend message at a time can be queued for a logical unit. If a second resend situation occurs before CICS has
written the first, a resend message is sent containing the eight bytes of data that accompanied the second input transaction
from the 3600 logical unit.

The resend message is sent in transparent mode if the input data from the 3601 to be retransmitted is received by CICS in
transparent mode. Otherwise it is sent in nontransparent mode.

Chapter 1. Commands 59
CONVERSE (non-VTAM)

CONVERSE (3735)

Function
Communicate on a 3735 programmable buffered terminal.

Command syntax

CONVERSE communicates on a 3735 programmable buffered terminal. The 3735 programmable buffered terminal may be
serviced by CICS in response to terminal-initiated input (automatic answering), or as a result of an automatic calling or
time-initiated transaction.

CONVERSE (3740)

Function
Communicate on a 3740 data entry system.

Command syntax

CONVERSE communicates on a 3740 data entry system.

In batch mode, many files are exchanged between the 3740 and CICS in a single transmission. The transmission of an input
batch must be complete before an output transmission can be started.

60 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

CONVERSE (non-VTAM) options

| ALTERNATE
| set the terminal to use the ALTERNATE screen size.

ASIS
indicates that output is to be sent in transparent mode (with no recognition of control
characters and accepting any of the 256 possible combinations of eight bits as valid
transmittable data).
Note: If you are using a katakana terminal, you might see some messages containing
mixed English and katakana characters. That is because katakana terminals cannot
display mixed-case output. Uppercase characters in the data stream appear as
uppercase English characters, but lowercase characters appear as katakana characters.
If this happens, ask your system programmer to specify MSGCASE=UPPER in the
system initialization parameters so that messages contain uppercase characters only.

ATTACHID(name)
specifies that an attach header (created by a BUILD ATTACH command) is to precede,
and be concatenated with, the user data supplied in the FROM option. “name” (1–8
characters) identifies the attach header control block to be used in the local task.

CONVID(name)
identifies the conversation to which the command relates. The 4-character name
identifies either the token returned by a previously executed ALLOCATE command in
EIBRSRCE in the EIB, or the token representing the principal session (returned by a
previously executed ASSIGN command).

CTLCHAR(data-value)
specifies a 1-byte write control character (WCC1) that controls the CONVERSE
command. A COBOL user must specify a data area containing this character. If the
option is omitted, all modified data tags are reset to zero and the keyboard is restored.

| DEFAULT
| set the terminal to use the DEFAULT screen size.

DEFRESP
indicates that a definite response is required when the output operation has been
completed.

DEST(name)
specifies the 4-byte symbolic name of the TCAM destination to which the message is to
be sent. This option is meaningful only for terminals defined using DFHTCT
TYPE=SDSCI with DEVICE=TCAM.
If you use the DEST option, you must be aware of any restrictions placed on
device-dependent data streams by the message control facility in use. See the section
on the CICS-TCAM interface in the CICS/ESA Customization Guide for programming
information.

ERASE
specifies that the screen printer buffer or partition is to be erased and the cursor
returned to the upper left corner of the screen. (This option applies only to the 3270, or
8775, and to the 3604 Keyboard Display.)
The first output operation in any transaction, or in a series of pseudoconversational
transactions, should always specify ERASE. For transactions attached to 3270 screens
| or printers, unless explicitly overridden by the DEFAULT or ALTERNATE option, this
| also ensures that the correct screen size is selected, as defined for the transaction by
| the SCRNSZE option in the profile definition.

1 Documented in the IBM 3270 Data Stream Programmer’s Reference manual.

Chapter 1. Commands 61
CONVERSE (non-VTAM)

FMH
specifies that a function management header has been included in the data to be
written. If the ATTACHID option is specified as well, the concatenated FMH flag is set
in the attach FMH.

FROM(data-area)
specifies the data to be written to the terminal or logical unit, or sent to the partner
transaction. This option may, when relevant, be omitted if ATTACHID is specified.

FROMFLENGTH(data-value)
is a fullword alternative to FROMLENGTH.

FROMLENGTH(data-value)
specifies the length, as a halfword binary value, of the data to be written. If you use this
option, you must also specify FROM. For a description of a safe upper limit, see
“LENGTH options” on page 5.

INTO(data-area)
specifies the receiving field for the data read from the logical unit or terminal.

LEAVEKB
specifies that the keyboard is to remain locked at the completion of the data transfer.

LINEADDR(data-value)
specifies that the writing is to begin on a specific line of a 2260/2265 screen. The data
value is a halfword binary value in the range 1 through 12 for a 2260, or 1 through 15
for a 2265.

MAXFLENGTH(data-value)
is a fullword alternative to MAXLENGTH.

MAXLENGTH(data-value)
specifies the maximum amount (halfword binary value) of data that CICS is to recover in
response to a CONVERSE command. If INTO is specified, MAXLENGTH overrides the
use of TOLENGTH as an input to CICS. If SET is specified, MAXLENGTH provides a
way for the program to limit the amount of data it receives at one time.
| If the value specified is less than zero, zero is assumed.
If the length of data exceeds the value specified and the NOTRUNCATE option is not
present, the data is truncated to that value and the LENGERR condition occurs. The
data area specified in the TOLENGTH option is set to the original length of data.
If the length of data exceeds the value specified and the NOTRUNCATE option is
present, CICS retains the remaining data and uses it to satisfy subsequent RECEIVE
commands. The data area specified in the TOLENGTH option is set to the length of
data returned.
If no argument is coded for MAXLENGTH, CICS defaults to TOLENGTH.

NOTRUNCATE
specifies that, when the data available exceeds the length requested, the remaining data
is not to be discarded but retained for retrieval by subsequent RECEIVE commands.

PSEUDOBIN
specifies that the data being read and written is to be translated from System/7
pseudobinary representation to hexadecimal.

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a session TCTTE. This option
specifies the alternate facility to be used. If both this option and CONVID are omitted,
the principal facility for the task is used.

SET(ptr-ref)
specifies a pointer reference to be set to the address of data received from the
conversation partner in an MRO conversation. The pointer reference, unless changed

62 CICS/ESA Application Programming Reference

CONVERSE (non-VTAM)

by other commands or statements, is valid until the next CONVERSE (MRO) command
or the end of task.
If DATALOCATION(ANY) is associated with the application program, the address of the
data can be above or below the 16MB line.
If DATALOCATION(BELOW) is associated with the application program, and the data
resides above the 16MB line, the data is copied below the 16MB line, and the address
of this copy is returned.
If TASKDATAKEY(USER) is specified for the running task, and storage protection is
active, the data returned is in a user-key. If TASKDATAKEY(CICS) is specified and
storage protection is active, the data returned is in a CICS-key.

STATE(cvda)
gets the state of the transaction program. The cvda values returned by CICS are:

ALLOCATED
FREE
PENDFREE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

STRFIELD
specifies that the data area specified in the FROM option contains structured fields. If
this option is specified, the contents of all structured fields must be handled by the
application program. The CONVERSE command, rather than a SEND command, must
be used if the data area contains a read partition structured field. (Structured fields are
described in the CICS/ESA 3270 Data Stream Device Guide.)
CTLCHAR and ERASE are mutually exclusive with STRFIELD, and their use with
STRFIELD generates an error message.

TOFLENGTH(data-area)
is a fullword alternative to TOLENGTH.

TOLENGTH(data-area)
specifies the length, as a halfword binary value, of the data to be received. If you
specify INTO, but omit MAXLENGTH, “data-area” specifies the maximum length that the
program accepts. If the value is less than zero, zero is assumed.
If the length of the data exceeds the value specified, but NOTRUNCATE is omitted, the
data is truncated to that value, and the LENGERR condition occurs. When the data is
received, the data area is set to the length of the data.
For a description of a safe upper limit, see “LENGTH options” on page 5.

CONVERSE (non-VTAM) conditions

Some of the following conditions can occur in combination with others. CICS checks for
these conditions in the following order:
1. INBFMH
2. EOC.

If more than one occurs, only the first is passed to the application program. EIBRCODE,
however, is set to indicate all the conditions that occurred.

CBIDERR
occurs if the requested attach header control block named in ATTACHID cannot be
found.
Default action: terminate the task abnormally.

Chapter 1. Commands 63
CONVERSE (non-VTAM)

EOC
occurs when a request/response unit (RU) is received with the end-of-chain indicator
set. Field EIBEOC also contains this indicator.
Default action: ignore the condition.

EOF (not TCAM)

occurs when an end-of-file indicator is received.
Default action: terminate the task abnormally.

INBFMH
occurs if a request/response unit (RU) contains a function management header (FMH).
Field EIBFMH contains this indicator and it should be used in preference to INBFMH.
The IGNORE CONDITION command can be used to ignore the condition.
Default action: terminate the task abnormally.

LENGERR
occurs in any of the following situations:

Data is discarded by CICS because its length exceeds the maximum that the
program accepts and the NOTRUNCATE option is not specified.
An out-of-range value is supplied in the FROMLENGTH option.

Default action: terminate the task abnormally.

NOTALLOC
occurs if the facility specified in the command is not owned by the application.
Default action: terminate the task abnormally.

RDATT (not TCAM)

occurs if the “receive” part of the conversation is terminated by the attention (ATTN) key
rather than the return key.
Default action: ignore the condition.

TERMERR
occurs for a session-related error.
A CANCEL TASK request by a user node error program (NEP) may cause this condition
if the task has an outstanding terminal control request active when the node abnormal
condition program handles the session error.
Default action: terminate the task abnormally with abend code ATNI.

WRBRK
occurs if the “send” part of the conversation is terminated by the attention (ATTN) key
rather than the return key.
Default action: ignore the condition.

64 CICS/ESA Application Programming Reference

DELAY

Function
Delay the processing of a task.

Command syntax

┌─INTERVAL()──────────────────────┐
──DELAY──┼──────────────────────────────────┼──┬─────────────┬──"
├─INTERVAL(hhmmss)─────────────────┤ └─REQID(name)─┘
├─TIME(hhmmss)─────────────────────┤
│ ┌──
───────────────────────┐ │
| ├─FOR───*┬─HOURS(data-value)───┬┴───┤
| │ ├─MINUTES(data-value)─┤ │
| │ └─SECONDS(data-value)─┘ │
│ ┌──
───────────────────────┐ │
| └─UNTIL───*┬─HOURS(data-value)───┬┴─┘
| ├─MINUTES(data-value)─┤
| └─SECONDS(data-value)─┘
Conditions:
EXPIRED, INVREQ

Note for dynamic transaction routing

| Using DELAY with REQID if later CANCELed could create inter-transaction affinities that adversely affect the use of
dynamic transaction routing. See the CICS/ESA Application Programming Guide for more information about transaction
affinities.

DELAY suspends the processing of the issuing task for a SECONDS(3723) means one hour, two minutes, and
specified interval of time or until a specified time of day. It three seconds.
supersedes any previously initiated POST command for the
task.
DELAY options
| The default is INTERVAL(0), but for C the default is FOR FOR
| HOURS(0) MINUTES(0) SECONDS(0). specifies the duration of the delay.
The following example shows you how to suspend the HOURS(data-value)
processing of a task for five minutes: a fullword binary value in the range 0–99.
EXEC CICS DELAY
INTERVAL(hhmmss)
INTERVAL(5OO)
REQID('GXLBZQMR') | specifies, in packed decimal format, the interval of time
that is to elapse from the time when the DELAY
EXEC CICS DELAY FOR MINUTES(5) command is issued. The mm and ss are in the range
0–59. The time specified is added to the current clock
The following example shows you how, at 09:00, to suspend
time by CICS when the command is executed to
the processing of a task until 12:45:
calculate the expiration time.
EXEC CICS DELAY
TIME(1245OO) | When using the C language, you are recommended to
REQID('UNIQCODE') | use the FOR/UNTIL HOURS, MINUTES, and SECONDS
| options as C does not provide a packed decimal data
There are two ways to enter the time under FOR or UNTIL. | type. You may use INTERVAL, but if the value specified
| is not an integer constant, the application is responsible
A combination of at least two of HOURS(0–99),
| for ensuring that the value passed to CICS is in packed
MINUTES(0–59) and SECONDS(0–59). HOURS(1)
| decimal format.
SECONDS(3) would mean one hour and three seconds
(the minutes default to zero). MINUTES(data-value)
Any one of HOURS(0–99), MINUTES(0–5999), or | specifies a fullword binary value in the range 0–59, when
SECONDS(0–359 999). HOURS(1) means one hour. | HOURS or SECONDS are also specified, or 0–5999
MINUTES(62) means one hour and two minutes. | when MINUTES is the only option specified.

Chapter 1. Commands 65
DELAY

REQID(name)
specifies a name (1–8 characters), which should be
| unique, to identify the DELAY request. Using this option
| to specify an application-defined name enables another
| transaction to cancel the DELAY request.
| To enable other tasks to cancel unexpired DELAY
| requests, you must make the request identifier
| dynamically available. For example, storing it in a TS
| queue, whose name is known to other applications that
| may want to cancel the DELAY request, is one way you
| can pass a request identifier to other transactions.

SECONDS(data-value)
| specifies a fullword binary value in the range 0–59, when
| HOURS or MINUTES are also specified, or 0–359 999
| when SECONDS is the only option specified.

TIME(hhmmss)
| specifies, in packed decimal format, the time when the
| task should resume processing.
| When using the C language, you are recommended to
| use the FOR/UNTIL HOURS, MINUTES, and SECONDS
| options as C does not provide a packed decimal data
| type. You may use TIME, but if the value specified is
| not an integer constant, the application is responsible for
| ensuring that the value passed to CICS is in packed
| decimal format. See the section about expiration times
in the CICS/ESA Application Programming Guide.

UNTIL
| specifies the time at the end of the delay and when the
| task should resume processing.
DELAY conditions
EXPIRED
occurs if the time specified has already expired when the
command is issued.
Default action: ignore the condition.

INVREQ
occurs in any of the following situations:

The DELAY command is not valid for processing by

CICS.
Hours are out of range (RESP2=4)
Minutes are out of range (RESP2=5)
Seconds are out of range (RESP2=6).

Default action: terminate the task abnormally.

66 CICS/ESA Application Programming Reference

DELETE

Function
| Delete a record from a file — VSAM KSDS, VSAM RRDS, and data tables only.

Command syntax

──DELETE──FILE(filename)─────────────────────────────────────────────────────────────────────────────────
──┬──────────────────────────────────────────────────────────────────────────────────┬────────────────────
| ├─TOKEN(data-value)────────────────────────────────────────────────────────────────┤
└─RIDFLD(data-area)──┬───────────────────────────────────────────────────────────┬─┘
└─KEYLENGTH(data-value)──┬────────────────────────────────┬─┘
└─GENERIC──┬───────────────────┬─┘
└─NUMREC(data-area)─┘
──┬───────────────────┬──┬─────┬──"
└─SYSID(systemname)─┘ ├─RBA─┤
└─RRN─┘
Conditions:
| DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LOADING, NOTAUTH, NOTFND,
NOTOPEN, SYSIDERR

DELETE deletes a record from a file on a KSDS, a path over DELETE options
| a KSDS, a CICS or user-maintained data table, or an RRDS.
| You cannot delete from a VSAM ESDS. All references to FILE(filename)
| KSDS apply equally to CICS maintained data tables and, specifies the name of the file to be accessed.
| except where stated otherwise, to paths over a KSDS. If SYSID is specified, the data set to which this file refers
The file may be on a local or a remote system. You identify, is assumed to be on a remote system irrespective of
in the RIDFLD option, the specific record to be deleted. whether the name is defined in the FCT. Otherwise, the
FCT entry is used to find out whether the data set is on
You can delete a group of records in a similar way with a a local or a remote system.
single invocation of this command, identifying the group by
| the GENERIC option (not available for user-maintained data GENERIC (KSDS)
| tables or RRDS). specifies that the search key is a generic key with a
length specified in the KEYLENGTH option. The search
| You can also use this command to delete a single record for a record is satisfied when a record is found with a
| that has previously been retrieved for update (by a READ key that has the same starting characters (generic key)
| UPDATE command). In this case, you must not specify the as those specified.
| RIDFLD option.
If you specify GENERIC, you must also specify RIDFLD.
When this command is used to delete records from a | You cannot use GENERIC for user-maintained data
CICS-maintained data table, the update is made to both the | tables.
source VSAM KSDS data set and the in-memory data table.
KEYLENGTH(data-value)
| When this command is used to delete records from a specifies the length (halfword binary) of the key that has
| user-maintained data table, the update is made only to the been specified in the RIDFLD option, except when RBA
| in-memory data table. or RRN is specified, in which case it is not valid. This
option must be specified if GENERIC is specified, and it
The following example shows you how to delete a group of may be specified whenever a key is specified. However,
records in a VSAM data set: if the length specified is different from the length defined
EXEC CICS DELETE for the data set and the operation is not generic, the
FILE('MASTVSAM') INVREQ condition occurs.
RIDFLD(ACCTNO)
The INVREQ condition also occurs if you specify
KEYLENGTH(len)
GENERIC, and the KEYLENGTH is not less than that
GENERIC
NUMREC(NUMDEL) specified in the VSAM definition.
You should not specify a zero value of KEYLENGTH
because the results of this are unpredictable.

Chapter 1. Commands 67
DELETE

NUMREC(data-area) (KSDS) This condition cannot occur when deleting a record just
specifies a halfword binary data area that CICS sets to read for update.
the number of deleted records.
Default action: terminate the task abnormally.
RBA (KSDS except for paths over KSDS)
DUPKEY
specifies that the record identification field specified in
occurs if a record is accessed by way of an alternate
the RIDFLD option contains a relative byte address.
index with the NONUNIQUEKEY attribute, and another
This option should be used only when deleting records
alternate index record with the same key follows
using relative byte addresses instead of keys to identify
(RESP2=140).
the records.
Default action: terminate the task abnormally.
| You cannot use RBA for user-maintained data tables.
FILENOTFOUND
RIDFLD(data-area)
occurs if the file name referred to in the FILE option
# specifies the record identification field. When combined
cannot be found in the FCT (RESP2=1).
# with RBA or RRN this is a 4-character field. The
| contents can be a key, a relative byte address, or a Default action: terminate the task abnormally.
| relative record number. For a relative byte address or a
ILLOGIC
relative record number, the format of this field must be
occurs if a VSAM error occurs that does not fall within
fullword binary. For a relative byte address, the RIDFLD
one of the other CICS response categories
can be greater than or equal to zero. For a relative
(RESP2=110).
record number, the RIDFLD can be greater than or
equal to 1. # (See EIBRCODE in the EXEC interface block; refer to
Appendix A, “EXEC interface block” on page 343 for
The contents must be a key for user-maintained data
details.)
tables.
Default action: terminate the task abnormally.
You must specify this option if you have also specified
GENERIC. INVREQ
occurs in any of the following situations:
RRN (VSAM RRDS)
specifies that the record identification field specified in Delete operations are not allowed according to the
the RIDFLD option contains a relative record number. file entry specification in the FCT (RESP2=20).
This option should be used only with files referencing
| When the user-maintained data table was defined
relative record data sets.
| as a CICS file, the definition did not allow for delete
SYSID(systemname) | operations (RESP2=20).
specifies the name (1–4 characters) of the system the A DELETE command is issued for a file referring to
request is directed to. a VSAM ESDS (RESP2=21).
If you specify SYSID, and omit both RBA and RRN, you A generic delete is issued for a file that is not a
must also specify KEYLENGTH; it cannot be found in VSAM KSDS (RESP2=22).
the FCT.
The KEYLENGTH and GENERIC options are
| TOKEN(data-value) specified, and the length specified in the
| specifies as a fullword binary value a unique request KEYLENGTH option is greater than or equal to the
| identifier for a DELETE, and is used to associate it with length of a full key (RESP2=25).
| a previous READ for UPDATE request. This is an input
The KEYLENGTH option is specified (but the
| value returned by the task to file control.
GENERIC option is not specified), and the specified
length does not equal the length defined for the data
DELETE conditions set to which this file refers (RESP2=26).
Note: RESP2 values are not set for files that are on remote A DELETE command is issued for a file referring to
systems. a BDAM data set (RESP2=27).

DISABLED A DELETE command without the RIDFLD option is

occurs if a file is disabled (RESP2=50). A file may be issued for a file for which no previous READ
disabled because: UPDATE command has been issued (RESP2=31).
The KEYLENGTH and GENERIC options are
It was initially defined as disabled and has not since
specified, and the length specified in the
been enabled.
KEYLENGTH option is less than zero (RESP2=42).
It has been disabled by a SET FILE or a CEMT
| The DELETE command does not conform to the
SET FILE command.
| format of DELETE for a user-maintained data table;

68 CICS/ESA Application Programming Reference

DELETE

| for example if GENERIC were specified Default action: terminate the task abnormally.
| (RESP2=44).
NOTOPEN
| A DELETE instruction includes a token whose value occurs in any of the following situations (RESP2=60):
| cannot be matched against any token in use for an
| existing READ for UPDATE request (RESP2=47). The requested file is CLOSED and UNENABLED.
The CLOSED, UNENABLED state is reached after a
| An attempt is made to function-ship a request which
CLOSE request has been received against an
| includes a TOKEN keyword (RESP2=48).
OPEN ENABLED file and the file is no longer in
Default action: terminate the task abnormally. use. This state can also be specified as the initial
state by means of the FILSTAT parameter of the file
IOERR
control table TYPE=FILE, or by defining a file using
occurs if there is an I/O error during the file control
the RDO options STATUS=UNENABLED and
operation (RESP2=120). An I/O error is any unusual
OPENTIME=FIRSTREF.
event that is not covered by a CICS condition.
The requested file is OPEN and in use by other
For VSAM files, IOERR normally indicates a hardware
transactions, but a CLOSE request against the file
error.
has been received.
(Further information is available in the EXEC interface
This condition does not occur if the request is made to
block; refer to Appendix A, “EXEC interface block” on
either a CLOSED, ENABLED file or a CLOSED,
page 343 for details.)
DISABLED file. In the first case, the file is opened as
Default action: terminate the task abnormally. part of executing the request. In the second case, the
DISABLED condition occurs.
ISCINVREQ
occurs when the remote system indicates a failure that This condition also cannot occur when deleting a record
does not correspond to a known condition (RESP2=70). just read for update.
Default action: terminate the task abnormally. Default action: terminate the task abnormally.

| LOADING SYSIDERR
| occurs if a delete request is issued for a user-maintained | occurs when the SYSID option specifies a name that is
| data table that is currently being loaded (RESP2=104). | neither the local system nor a remote system (made
| known to CICS by defining a CONNECTION).
| A user-maintained data table cannot be modified during
SYSIDERR also occurs when the link to the remote
| loading.
system is closed (RESP2=130).
| Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
NOTAUTH
occurs when a resource security check has failed on
FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.

NOTFND
occurs if an attempt to delete a record based on the
search argument provided is unsuccessful (RESP2=80).
| A NOTFND condition occurs, for VSAM only, if the
| RIDFLD specifies a track address outside the extent of a
| BDAM data set.
| For user-maintained data tables, this condition occurs if
| an attempt to delete a record is unsuccessful because
| there is no entry with the specified key in the data table.
# This can occur on an attempt to delete a record using a
# DELETE without RIDFLD, if the delete is associated with
# a READ UPDATE request for a record that this
# transaction has deleted (using DELETE with RIDFLD)
# after it was read for update (RESP2=80).
This does not mean that there is no such record in the
source data set; it may be that such a record is present
but was either rejected during initial loading by the user
exit XDTRD, or was subsequently deleted from the
user-maintained data table.

Chapter 1. Commands 69
DELETEQ TD

DELETEQ TD

Function
Delete all transient data.

Command syntax

──DELETEQ TD──QUEUE(name)──┬───────────────────┬──"
└─SYSID(systemname)─┘
Conditions:
DISABLED, INVREQ, ISCINVREQ, NOTAUTH, QIDERR, SYSIDERR

DELETEQ TD deletes all the transient data associated with a NOTAUTH

particular intrapartition destination (queue). All storage occurs when a resource security check has failed on
associated with the destination is released (deallocated). QUEUE(name).
Note that you cannot use this command to delete an
Default action: terminate the task abnormally.
extrapartition transient data queue. An attempt to do so
results in an INVREQ condition. QIDERR
occurs if the symbolic destination to be used with
DELETEQ TD cannot be found.
DELETEQ TD options
Default action: terminate the task abnormally.
QUEUE(name)
specifies the symbolic name (1–4 alphanumeric SYSIDERR
characters) of the queue to be deleted. The name must | occurs when the SYSID option specifies a name that is
have been defined in the DCT. | neither the local system nor a remote system (made
| known to CICS by defining a CONNECTION).
If SYSID is specified, the queue is assumed to be on a
SYSIDERR also occurs when the link to the remote
remote system irrespective of whether or not the name
system is closed.
is defined in the DCT. Otherwise the entry in the DCT is
used to find out whether the data set is on a local or a Default action: terminate the task abnormally.
remote system.

SYSID(systemname) — remote systems only

specifies the name (1–4 characters) of the system the
request is directed to.

DELETEQ TD conditions
DISABLED
occurs when the queue has been disabled.
Default action: terminate the task abnormally.

INVREQ
occurs if DELETEQ names an extrapartition queue.
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

70 CICS/ESA Application Programming Reference

DELETEQ TS

Function
Delete a temporary storage queue.

Command syntax

──DELETEQ TS──QUEUE(name)──┬───────────────────┬──"
└─SYSID(systemname)─┘
Conditions:
INVREQ, ISCINVREQ, NOTAUTH, QIDERR, SYSIDERR

| Note for dynamic transaction routing

| Using this command could create inter-transaction affinities that adversely affect the use of dynamic transaction routing.
| See the CICS/ESA Application Programming Guide for more information about transaction affinities.

DELETEQ TS deletes all the temporary data associated with QIDERR

a temporary storage queue. All storage associated with the occurs when the specified queue cannot be found in
queue is freed. either main or auxiliary storage.
Default action: terminate the task abnormally.
You should delete temporary data as soon as possible to
avoid using excessive amounts of storage. SYSIDERR
| occurs when the SYSID option specifies a name that is
When a recoverable temporary storage queue is deleted, you
| neither the local system nor a remote system (made
must issue a syncpoint before issuing a subsequent WRITEQ
| known to CICS by defining a CONNECTION).
TS for the same queue.
SYSIDERR also occurs when the link to the remote
system is closed.
DELETEQ TS options Default action: terminate the task abnormally.
QUEUE(name)
specifies the symbolic name (1–8 alphanumeric
characters) of the queue to be deleted. The name may
not consist solely of binary zeros and must be unique
within the CICS system.

SYSID(systemname) — remote systems only

specifies the name (1–4 characters) of the system the
request is directed to.

DELETEQ TS conditions
INVREQ
occurs when the queue was created by CICS internal
code.
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
QUEUE(name).
Default action: terminate the task abnormally.

Chapter 1. Commands 71
DEQ

DEQ

Function
Schedule use of a resource by a task (dequeue).

Command syntax

┌─LUW───────────────┐
──DEQ──RESOURCE(data-area)──┬────────────────────┬──┼───────────────────┼──"
└─LENGTH(data-value)─┘ ├─MAXLIFETIME(cvda)─┤
└─TASK──────────────┘
Conditions:
INVREQ, LENGERR

| Note for dynamic transaction routing

DEQ causes a resource currently enqueued on by the task to DEQ options

be released for use by other tasks.
LENGTH(data-value)
If a task enqueues on, but does not dequeue from, a specifies that the resource to be dequeued from has a
resource, CICS automatically releases the resource during length given by the data value. The data value is a
syncpoint processing or when the task is terminated. A halfword binary value in the range 1 through 255. If the
resource in the context of this command is any string of value you specify is outside this range, a LENGERR
1–255 bytes, established by in-house standards, to protect condition occurs. If the LENGTH option is specified in
against conflicting actions between tasks, or to cause an ENQ command, it must also be specified in the DEQ
single-threading within a program. command for that resource, and the values of these
options must be the same.
When issuing the DEQ command, the resource to be
dequeued from must be identified by the method used when MAXLIFETIME(cvda)
enqueuing on the resource. If no enqueue has been issued specifies the duration of the ENQ being released. The
for the resource, the dequeue is ignored. values passed to CICS are:

LUW ENQ was acquired with a duration of a

If more than one ENQ command is issued for a resource by
logical unit of work. This is the default
a task, that resource remains owned by the task until the
value.
task issues a matching number of DEQ commands.
TASK ENQ was acquired with a duration of a task.
The following examples show how to dequeue from a
resource: RESOURCE(data-area)
specifies either an area whose address represents the
EXEC CICS DEQ
resource to be dequeued from, or a variable that
RESOURCE(RESNAME)
contains the resource (an employee name, for example).
EXEC CICS DEQ In the latter case, you must use the LENGTH option.
RESOURCE(SOCSECNO)
LENGTH(8)
DEQ conditions
INVREQ
occurs if the MAXLIFETIME option is set with an
incorrect CVDA (RESP2=2).
| Default action: terminate the task abnormally.

LENGERR
means that the value you specified for the LENGTH
option is outside the range 1 through 255 (RESP2=1).

72 CICS/ESA Application Programming Reference

DEQ

| Default action: terminate the task abnormally.

Chapter 1. Commands 73
DUMP TRANSACTION

DUMP TRANSACTION

Function
Request a transaction dump.

Command syntax

──DUMP TRANSACTION──DUMPCODE(name)──┬──────────────────────────────────────────┬──┬──────────┬───────────
└─FROM(data-area)──┬─LENGTH(data-value)──┬─┘ └─COMPLETE─┘
└─FLENGTH(data-value)─┘
──┬─────┬──┬───────────────────────────────────────────────────────────────────────┬──┬──────┬────────────
└─TRT─┘ └─SEGMENTLIST(data-area)──LENGTHLIST(data-area)──NUMSEGMENTS(data-area)─┘ └─TASK─┘
──┬─────────┬──┬─────────┬──┬──────────┬──┬────────┬──┬─────┬──┬─────┬──┬─────┬──┬─────┬──┬─────┬─────────
└─STORAGE─┘ └─PROGRAM─┘ └─TERMINAL─┘ └─TABLES─┘ └─DCT─┘ └─FCT─┘ └─PCT─┘ └─PPT─┘ └─SIT─┘
──┬─────┬──┬───────────────────┬──"
└─TCT─┘ └─DUMPID(data-area)─┘
Conditions:
INVREQ, IOERR, NOSPACE, NOSTG, NOTOPEN, OPENERR, SUPPRESSED

DUMP TRANSACTION dumps all, a series, or any single DUMP TRANSACTION options
main storage area related to a task, any or all of the CICS
tables (DCT, FCT, PCT, PPT, SIT, or TCT), or all of these COMPLETE
together. dumps all main storage areas related to a task, all the
CICS tables, and the DL/I control blocks.
Note that if you issue a DUMP TRANSACTION for a
DCT
DUMPCODE that is defined in the transaction dump table
dumps the destination control table.
with SYSDUMP, you also get a system dump.
DUMPCODE(name)
The following example shows how to request a dump of all specifies a name (1–4 characters) that identifies the
the task-related storage areas, the terminal control table, and | dump. If the name contains any leading or imbedded
a specified data area: | blanks, the dump is produced but INVREQ is raised. No
EXEC CICS DUMP TRANSACTION | entry is added to the system dump table.
DUMPCODE('name')
FROM(data-area) If you omit all the options except DUMPCODE, you get
LENGTH(data-value) the same TASK, but without the DL/I control blocks.

This second example (written in PL/I) shows you a case in DUMPID(data-area)

which five task-related storage areas are dumped: is a number returned by the system that identifies the
particular dump.
DCL storage_address(5) POINTER,
storage_length(5) FIXED BIN(31), FCT
nsegs FIXED BIN(31); dumps the file control table.
storage_address(1) = ADDR(areal);
storage_length(1) = CSTG(areal); FLENGTH(data-value)
..
. specifies the length (fullword binary value) of the storage
nsegs = 5; area (specified in the FROM option) that is to be
EXEC CICS DUMP TRANSACTION dumped. The maximum length that you can specify is
DUMPCODE('name') 16 777 215 bytes.
SEGMENTLIST(storage_address)
LENGTHLIST(storage_length) FLENGTH and LENGTH are mutually exclusive.
NUMSEGMENTS(nsegs);
FROM(data-area)
If there is no entry in the system dump table for the specified dumps the specified data area, which must be a valid
DUMPCODE, a temporary entry is made. This entry is lost area; that is, storage allocated by the operating system
on the next CICS start. The system dump table is described within the CICS region. In addition, the following areas
in the CICS/ESA Problem Determination Guide. are dumped:

Task control area (TCA) and, if applicable, the

transaction work area (TWA).

74 CICS/ESA Application Programming Reference

DUMP TRANSACTION

Common system area (CSA), including the user’s All program storage areas containing user-written
portion of the CSA (CWA). application programs active on behalf of the
# requesting task
Apar 63695
Register save areas (RSAs) indicated by the RSA
# Documentation for Apar 63695 added 6 Jan
chain off the TCA
# 1995 (TUCKER)
Either the terminal control table terminal entry
# If TRAN is specified for the TRTRANTY SIT (TCTTE) or the destination control table entry
# parameter, only the trace entries associated with the associated with the requesting task.
# current task are formatted. If TRTRANTY=ALL is Whenever the TCTTE is dumped, the terminal control
# specified, the entire internal trace table is formatted. table user area (if any) and the message control blocks
# This only applies when the CICS trace facility is (if any) associated with the TCTTE are dumped.
# active.
SEGMENTLIST(data-area)
Either the terminal control table terminal entry
specifies a list of addresses, which are the starting
(TCTTE) or the destination control table entry
points of the segments to be dumped. Each segment is
associated with the requesting task.
a task-related storage area. You must use both the
Whenever the TCTTE is dumped, the terminal control NUMSEGMENTS and LENGTHLIST options when you
table user area (if any) and the message control blocks use the SEGMENTLIST option.
(if any) associated with the TCTTE are dumped. The
SIT
latter are used by basic mapping support.
dumps the system initialization table.
LENGTH(data-value)
STORAGE
specifies the length (halfword binary) of the data area
specifies that storage areas associated with this task are
specified in the FROM option. For a description of a
to be dumped, as follows:
safe upper limit, see “LENGTH options” on page 5.
LENGTH and FLENGTH are mutually exclusive. Task control area (TCA) and, if applicable, the
transaction work area (TWA)
LENGTHLIST(data-area)
Common system area (CSA), including the user’s
| specifies a list of fullword binary values showing the
portion of the CSA (CWA)
| lengths of the storage areas to be dumped. This
| corresponds to the list of segments specified in the Trace entries relating to the task written to the
SEGMENTLIST option. You must use both the internal trace table (only when the CICS trace
SEGMENTLIST and NUMSEGMENTS options when you facility is active)
use the LENGTHLIST option. All transaction storage areas
NUMSEGMENTS(data-area) Either the terminal control table terminal entry
specifies the number (fullword binary) of areas to be (TCTTE) or the destination control table entry
dumped. You must use both the SEGMENTLIST and associated with the requesting task.
LENGTHLIST options when you use the
NUMSEGMENTS option. Whenever the TCTTE is dumped, the terminal control
table user area (if any) and the message control blocks
PCT (if any) associated with the TCTTE are dumped.
| formats a summary of each installed transaction
| definition. TABLES
dumps the DCT, FCT, PCT, PPT, SIT, and the TCT.
PPT
dumps the processing program table. TASK
specifies that storage areas associated with this task are
PROGRAM to be dumped, as follows:
specifies that program storage areas associated with this
task are to be dumped, as follows: | A summary of the transaction environment
| associated with this task
Task control area (TCA) and, if applicable, the
Common system area (CSA), including the user’s
transaction work area (TWA)
portion of the CSA (CWA)
Common system area (CSA), including the user’s
Trace entries relating to the task written to the
portion of the CSA (CWA)
internal trace table (only when the CICS trace
Trace entries relating to the task written to the facility is active)
internal trace table (only when the CICS trace
All program storage areas containing user-written
facility is active)
application programs active on behalf of the
requesting task

Chapter 1. Commands 75
DUMP TRANSACTION

All transaction storage areas IOERR

occurs in any of the following situations:
Either the terminal control table terminal entry
(TCTTE) or the destination control table entry The SDUMP process is not authorized (RESP2=9).
associated with the requesting task
An error occurred during system dumping
Register save areas (RSAs) indicated by the RSA (RESP2=10).
chain off the TCA
| The CICS routine issuing the SDUMP is unable to
All terminal input/output areas (TIOAs) chained off | establish a recovery routine (FESTAE) (RESP2=13).
the terminal control table terminal entry (TCTTE) for
the terminal associated with the requesting task | Default action: terminate the task abnormally.

DL/I control blocks. NOSPACE

occurs if the transaction dump is incomplete due to lack
Whenever the TCTTE is dumped, the terminal control
of space (RESP2=4).
table user area (if any) and the message control blocks
(if any) associated with the TCTTE are dumped. | Default action: terminate the task abnormally.

TCT NOSTG
dumps the terminal control table. occurs if CICS has run out of working storage
(RESP2=5).
TERMINAL
| Default action: terminate the task abnormally.
specifies that storage areas associated with the terminal
are to be dumped, as follows: NOTOPEN
occurs if the current CICS dump data set is not open
Task control area (TCA) and, if applicable, the
(RESP2=6).
transaction work area (TWA)
| Default action: terminate the task abnormally.
Common system area (CSA), including the user’s
portion of the CSA (CWA) OPENERR
Trace entries relating to the task written to the occurs if there is an error on opening, closing, or writing
internal trace table (only when the CICS trace to the current CICS dump routine (RESP2=7).
facility is active) | Default action: terminate the task abnormally.
All terminal input/output areas (TIOAs) chained off
SUPPRESSED
the terminal control table terminal entry (TCTTE) for
occurs in any of the following situations:
the terminal associated with the requesting task as
long as the request is not a write, or storage The transaction dump is suppressed by MAXIMUM
freezing is on for the task or the terminal in table (RESP2=1).
Either the terminal control table terminal entry The transaction dump is suppressed by
(TCTTE) or the destination control table entry NOTRANDUMP in table (RESP2=2).
associated with the requesting task.
The transaction dump is suppressed by a user exit
Whenever the TCTTE is dumped, the terminal control program (RESP2=3).
table user area (if any) and the message control blocks
| Default action: terminate the task abnormally.
(if any) associated with the TCTTE are dumped. The
latter are used by basic mapping support.

TRT
dumps the trace entries relating to the task written to the
internal trace table.

DUMP TRANSACTION conditions

INVREQ
occurs if an incorrect DUMPCODE is specified.
DUMPCODE contains unprintable characters, or leading
or imbedded blanks (RESP2=13).
The dump is produced but no entry is added to the
system dump table.
Default action: terminate the task abnormally.

76 CICS/ESA Application Programming Reference

ENDBR

Function
End browse of a file.

Command syntax

──ENDBR──FILE(filename)──┬───────────────────┬──┬───────────────────┬──"
└─REQID(data-value)─┘ └─SYSID(systemname)─┘
Conditions:
FILENOTFOUND, ILLOGIC, INVREQ, ISCINVREQ, NOTAUTH, SYSIDERR

| ENDBR ends a browse on a file or data table (CICS or # (See EIBRCODE in the EXEC interface block; refer to
| user-maintained) on a local or a remote system. Appendix A, “EXEC interface block” on page 343 for
details.)
You should always issue an end browse (ENDBR) command
Default action: terminate the task abnormally.
before performing any update operations on the same data
set (READ UPDATE, DELETE with RIDFLD, or WRITE), and INVREQ
before a syncpoint. You only need issue ENDBR after a occurs if the REQID, if any, does not match that of any
successful STARTBR. successful STARTBR command (RESP2=35).
Default action: terminate the task abnormally.
ENDBR options
ISCINVREQ
FILE(filename) occurs when the remote system indicates a failure that
specifies the name of the file being browsed. does not correspond to a known condition (RESP2=70).
If SYSID is specified, the data set to which this file refers Default action: terminate the task abnormally.
is assumed to be on a remote system irrespective of
whether the name is defined in the FCT. Otherwise, the NOTAUTH
FCT entry is used to find out whether the data set is on occurs when a resource security check has failed on
a local or a remote system. FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.
REQID(data-value)
specifies a unique (halfword binary value) request SYSIDERR
identifier for a browse, used to control multiple browse | occurs when the SYSID option specifies a name that is
operations on a data set. If this option is not specified, a | neither the local system nor a remote system (made
default value of zero is assumed. | known to CICS by defining a CONNECTION).
SYSIDERR also occurs when the link to the remote
SYSID(systemname)
system is closed (RESP2=130).
specifies the name (1–4 characters) of the system the
request is directed to. Default action: terminate the task abnormally.

ENDBR conditions
Note: RESP2 values are not set for files that are on remote
systems.

FILENOTFOUND
occurs if the name referred to in the FILE option cannot
be found in the FCT (RESP2=1).
Default action: terminate the task abnormally.

ILLOGIC (VSAM)
occurs if a VSAM error occurs that does not fall within
one of the other CICS response categories
(RESP2=110).

Chapter 1. Commands 77
ENQ

ENQ

Function
Schedule use of a resource by a task (enqueue).

┌─LUW───────────────┐
──ENQ──RESOURCE(data-area)──┬────────────────────┬──┼───────────────────┼──┬───────────┬──"
└─LENGTH(data-value)─┘ ├─MAXLIFETIME(cvda)─┤ └─NOSUSPEND─┘
└─TASK──────────────┘
Conditions:
ENQBUSY, LENGERR, INVREQ

| Note for dynamic transaction routing

ENQ causes further execution of the task issuing the ENQ same location or to different locations, but the contents
command to be synchronized with the availability of the of the locations must be the same. The length must be
specified resource; control is returned to the task when the supplied in the LENGTH option.
resource is available. EXEC CICS ENQ
RESOURCE(SOCSECNO)
A resource in the context of this command is any string of LENGTH(8)
1–255 bytes, established by in-house standards, to protect
against conflicting actions between tasks, or to cause single
threading within a program. | Resource unavailability
If a task enqueues on a resource but does not dequeue from | If a resource is not available when ENQUEUED, the
it, CICS automatically releases the resource during syncpoint | application program is suspended until it becomes available.
processing (including DL/I, PCB, and TERM calls), or when | However, if the NOSUSPEND option has been specified and
the task is terminated. Option LUW on MAXLIFETIME forces | the resource is unavailable, the ENQBUSY condition is
the dequeue at the end of a logical unit of work (LUW). | raised. It is also raised if you have previously issued
Option TASK on MAXLIFETIME forces the dequeue at the # HANDLE CONDITION ENQBUSY, even if NOSUSPEND is
end of a task. If there are several LUWs in a task, the # not coded. This allows the application program to handle the
enqueue carries over the LUWs. | case of resource unavailability (by HANDLE CONDITION
| ENQUEUE) without waiting for the resource to become
If more than one ENQ command is issued for the same | available.
resource by a given task, the resource remains owned by
that task until the task issues a matching number of DEQ
commands. ENQ options
LENGTH(data-value)
The resource to be enqueued on must be identified by one of
specifies that the resource to be enqueued on has a
the following methods:
length given by the data value. The data value is a
Specifying a data area that is the resource. It is the halfword binary value in the range 1–255. If the value
location (address) of the data area in storage that you specify is outside this range, a LENGERR condition
matters, not its contents. Two tasks, enqueuing on the is issued. If the LENGTH option is specified in an ENQ
same resource and using this method, must refer to the command, it must also be specified in the DEQ
same location in storage. They could both, for example, command for that resource, and the values of these
refer to the same location in the CWA. options must be the same. You must specify LENGTH
EXEC CICS ENQ when using the method that specifies a data value
RESOURCE(RESNAME) containing a unique argument, but not for the method
that specifies a data area as the resource. It is the
Specifying a data area that contains a unique argument
presence or absence of LENGTH that tells CICS which
(for example, an employee name) that represents the
method you are using.
resource. It is the contents of the data value that
matters, not its location. Two tasks, enqueuing on the
same resource and using this method, can refer to the

78 CICS/ESA Application Programming Reference

ENQ

MAXLIFETIME(cvda) ENQ conditions

specifies the duration of the ENQ to be automatically
released by CICS. The values that can be passed to ENQBUSY
CICS are: occurs when an ENQ command specifies a resource
that is unavailable and the NOSUSPEND option is
LUW The duration of the ENQ is a logical unit of specified.
| work. Examples are a syncpoint rollback or
syncpoint, if the application does not issue a If the NOSUSPEND option is not specified, and the ENQ
DEQ before the LUW ends. This is the command specifies a resource that is unavailable, the
default value. application program is suspended and the ENQBUSY
condition is not raised.
TASK The duration of the ENQ is a task. The
enqueue carries over the LUWs within the Default action: ignore the condition.
task. Use MAXLIFETIME(TASK) with great INVREQ
care because other tasks issuing ENQ occurs if the MAXLIFETIME option is set with an
commands on the same resource could be incorrect CVDA (RESP2=2).
suspended until the end of this task.
| Default action: terminate the task abnormally.
There are two ways to code this option.
LENGERR
You can assign a cvda value with the translator occurs when the value specified for the LENGTH option
routine DFHVALUE. This allows you to change a is outside the range 1 through 255 (RESP2=1).
cvda value in the program. For example:
| Default action: terminate the task abnormally.
MOVE DFHVALUE(LUW) TO AREA-A
EXEC CICS ENQ RESOURCE(RESNAME) MAXLIFETIME(AREA-A)
If the required action is always the same, you can
declare the value directly. For example:
EXEC CICS ENQ RESOURCE(RESNAME) LUW
or
EXEC CICS ENQ RESOURCE(RESNAME) TASK

NOSUSPEND
specifies that the application program is not to be
suspended if the resource on the ENQ command is
| unavailable, but the ENQBUSY condition occurs.

RESOURCE(data-area)
Identifies the resource to be enqueued on by:

Specifying an area whose address represents the

resource.
Specifying a variable that contains the resource (an
employee name, for example). In this case, you
must use the LENGTH option.

Chapter 1. Commands 79
ENTER TRACENUM

ENTER TRACENUM

Function
Write a trace entry.

Command syntax

──ENTER TRACENUM(data-value)──┬────────────────────────────────────────────┬──┬────────────────┬─────────
└─FROM(data-area)──┬───────────────────────┬─┘ └─RESOURCE(name)─┘
└─FROMLENGTH(data-area)─┘
──┬───────────┬──"
└─EXCEPTION─┘
Conditions:
INVREQ, LENGERR

The ENTER TRACENUM command makes a trace entry in EXCEPTION

the currently active trace destinations. CICS writes the trace specifies that CICS is to write a user exception trace
entry only if the master and user trace flags are on, unless entry. The EXCEPTION option overrides the master
you specify the EXCEPTION option, in which case a user user trace flag, and CICS writes the trace entry even if
trace entry is always written, even if the master and user the user trace flag is off. Exception trace entries are
trace flags are off. Exception trace entries are always written identified by the characters *EXCU when the trace
to the internal trace table (even if internal tracing is set off), entries are formatted by the trace utility program. See
but they are written to other destinations only if they are the CICS/ESA Problem Determination Guide for more
active. information about user exception trace entries.

You can use the exception trace option in an application FROM(data-area)

program to write a trace entry when the program detects an specifies a data area whose contents are to be entered
exception or abnormal condition. To do this, include an into the data field of the trace table entry. If you omit
ENTER TRACENUM(data-value) EXCEPTION command in the FROM option, two fullwords of binary zeros are
your program’s exception or abnormal condition passed.
error-handling routine.
FROMLENGTH(data-area)
specifies a halfword binary data area containing the
To write an exception trace entry in an error situation when
length of the trace data, in the range 0–4000 bytes. If
an application program has given up control, you can issue
FROMLENGTH is not specified, a length of 8 bytes is
an ENTER TRACENUM(data-value) EXCEPTION command
assumed.
from a user-written program error program (PEP). See the
CICS/ESA Customization Guide for programming information RESOURCE(name)
about modifying the DFHPEP program. specifies an 8-character name to be entered into the
resource field of the trace table entry.
Note: ENTER TRACENUM replaces the earlier ENTER
TRACEID command, which is still supported for compatibility TRACENUM(data-value)
with releases of CICS earlier than Version 3. You should specifies the trace identifier for a user trace table entry
use ENTER TRACENUM for all new programs, and as a halfword binary value in the range 0 through 199.
whenever you apply maintenance to old programs.

For information about the trace entry format, see the ENTER TRACENUM conditions
CICS/ESA Problem Determination Guide. INVREQ
| occurs in any of the following situations:
The following COBOL example shows how to write a user
trace entry with a trace identifier of 123, with trace data from | TRACENUM is outside the range 0 through 199
a data area called USER-TRACE-ENTRY: | (RESP2=1)
EXEC CICS ENTER TRACENUM(123) | There is no valid trace destination (RESP2=2)
FROM(USER-TRACE-ENTRY)
END-EXEC. | The user trace flag is set OFF and EXCEPTION has
| not been specified (RESP2=3).

ENTER TRACENUM options | Default action: terminate the task abnormally.

80 CICS/ESA Application Programming Reference

ENTER TRACENUM

LENGERR
occurs when FROMLENGTH is outside the range 0
| through 4000 (RESP2=4).
| Default action: terminate the task abnormally.

Chapter 1. Commands 81
EXTRACT ATTACH (LUTYPE6.1)

EXTRACT ATTACH (LUTYPE6.1)

Function
Retrieve values from an LUTYPE6.1 attach header.

Command syntax

──EXTRACT ATTACH──┬────────────────┬──┬────────────────────┬──┬─────────────────────┬────────────────────
├─ATTACHID(name)─┤ └─PROCESS(data-area)─┘ └─RESOURCE(data-area)─┘
├─CONVID(name)───┤
└─SESSION(name)──┘
──┬─────────────────────┬──┬──────────────────────┬──┬──────────────────┬──┬───────────────────┬──────────
└─RPROCESS(data-area)─┘ └─RRESOURCE(data-area)─┘ └─QUEUE(data-area)─┘ └─IUTYPE(data-area)─┘
──┬────────────────────┬──┬──────────────────┬──"
└─DATASTR(data-area)─┘ └─RECFM(data-area)─┘
Conditions:
CBIDERR, INVREQ, NOTALLOC

ATTACHID(name) IUTYPE(data-area)
specifies that values are to be retrieved from an attach corresponds to the interchange unit field, ATTIU, in an
header control block. The name (1–8 characters) LUTYPE6.1 attach FMH.
identifies this control block to the local task. For communication between two CICS systems, no
particular significance is attached by CICS to the
CONVID(name)
interchange unit field in an attach FMH. For most CICS
identifies the conversation to which the command
applications the option can be omitted.
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command The value returned in the data area is a halfword binary
in EIBRSRCE in the EIB, or the token representing the value. Only the low-order 7 bits are used; the
principal session (returned by a previously executed SNA-defined meanings of the bits are as follows:
ASSIGN command). O-1O reserved - must be set to zero
DATASTR(data-area) 11 O - not end of multichain interchange unit
1 - end of multichain interchange unit
corresponds to the data stream profile field, ATTDSP, in
12,13 reserved - must be set to zero
an LUTYPE6.1 attach FMH.
14,15 OO - multichain interchange unit
For communication between two CICS systems, no O1 - single-chain interchange unit
particular significance is given by CICS to the data 1O - reserved
stream profile field in an attach FMH. For most CICS 11 - reserved
applications, the option can be omitted. PROCESS(data-area)
The value returned in the data area is a halfword binary corresponds to the process name, ATTDPN, in an
value. Only the low-order byte is used; the SNA-defined LUTYPE6.1 attach FMH.
meanings of the bits are as follows: For communication between two CICS systems, a
transaction running in one system can acquire a session
to the second system and can identify the transaction to
be attached; in the second system the identification is
carried in the first chain of data sent across the session.

82 CICS/ESA Application Programming Reference

EXTRACT ATTACH (LUTYPE6.1)

In general, the first four bytes of data identify the RPROCESS(data-area)

transaction to be attached. However an attach FMH, corresponds to the return process name, ATTRDPN, in
identifying the transaction to be attached, can be built an LUTYPE6.1 attach FMH.
and sent. The receiving CICS system uses just the first
For communication between two CICS systems, no
four bytes of the process name as a transaction name.
significance is attached by CICS to the return process
No significance is attached by CICS to process names in name in an attach FMH.
attach FMHs sent in chains of data other than the first.
For communication between a CICS system and another
For communication between a CICS system and another subsystem, refer to documentation supplied by the
subsystem, refer to documentation supplied by the subsystem about how to use the return process name
subsystem about how to use the process name field in field in an attach FMH.
an attach FMH.
RRESOURCE(data-area)
QUEUE(data-area) corresponds to the return resource name, ATTRPRN, in
corresponds to the queue name, ATTDQN, in an attach an LUTYPE6.1 attach FMH.
FMH.
For communication between two CICS systems, no
For communication between two CICS systems, no significance is attached by CICS to the return resource
significance is attached by CICS to the queue name in name in an attach FMH.
an attach FMH.
For communication between a CICS system and another
For communication between a CICS system and another subsystem, refer to documentation supplied by the
subsystem, refer to documentation supplied by the subsystem about how to use the return resource name
subsystem about how to use the queue name field in an field in an attach FMH.
attach FMH.
SESSION(name)
RECFM(data-area) specifies the symbolic identifier (1–4 characters) of a
corresponds to the deblocking algorithm field, ATTDBA, session TCTTE. This option specifies the alternate
in an LUTYPE6.1 attach FMH. facility to be used.
For communication between two CICS systems, no
particular significance is attached by CICS to the EXTRACT ATTACH (LUTYPE6.1)
deblocking algorithm field in an attach FMH. For most conditions
CICS applications, the option can be omitted.
CBIDERR
For communication between a CICS system and another
occurs if the requested attach header control block
subsystem, refer to documentation supplied by the
cannot be found.
subsystem about how to use the interchange unit field in
an attach FMH. Default action: terminate the task abnormally.
The value returned in the data area is a halfword binary INVREQ
value. Only the low-order byte is used; the SNA-defined occurs if incorrect data is found.
meanings of the bits are as follows:
Default action: terminate the task abnormally.
O-7 reserved - must be set to zero
8-15 X'OO' - reserved NOTALLOC
X'O1' - variable-length occurs if the facility specified in the command is not
variable-blocked owned by the application.
X'O2' - reserved
X'O3' - reserved Default action: terminate the task abnormally.
X'O4' - chain of RUs
X'O5' through X'FF' - reserved

RESOURCE(data-area)
corresponds to the resource name, ATTPRN, in an
LUTYPE6.1 attach FMH.
For communication between two CICS systems, no
significance is attached by CICS to the resource name in
an attach FMH.
For communication between a CICS system and another
subsystem, refer to documentation supplied by the
subsystem about how to use the resource name field in
an attach FMH.

Chapter 1. Commands 83
EXTRACT ATTACH (MRO)

EXTRACT ATTACH (MRO)

Function
Retrieve values from an MRO attach header.

Command syntax

EXTRACT ATTACH retrieves a set of values that are held in O-7 reserved - must be set to zero
an attach header control block, or that have been built 8-11 OOOO - user-defined
previously. For the command to retrieve information from a 1111 - SCS data stream
received attach FMH (Function Management Header), 111O - 327O data stream
EIBATT must have been set during a RECEIVE or 11O1 - structured field
11OO - logical record management
CONVERSE command.
12-15 defined by the user if bits 8-11
For more information about MRO and IRC, see the are set to OOOO; otherwise reserved
(must be set to zero)
CICS/ESA Intercommunication Guide.
IUTYPE(data-area)
corresponds to the interchange unit field, ATTIU, in an
EXTRACT ATTACH (MRO) options
LUTYPE6.1 attach FMH.
ATTACHID(name) For communication between two CICS systems, no
specifies that values are to be retrieved from an attach particular significance is attached by CICS to the
header control block. The name (1–8 characters) interchange unit field in an attach FMH. For most CICS
identifies this control block to the local task. applications the option can be omitted.
CONVID(name) The value returned in the data area is a halfword binary
identifies the conversation to which the command value. Only the low-order 7 bits are used; the
relates. The 4-character name identifies either the token SNA-defined meanings of the bits are as follows:
returned by a previously executed ALLOCATE command
O-1O reserved - must be set to zero
in EIBRSRCE in the EIB, or the token representing the
11 O - not end of multichain interchange unit
principal session (returned by a previously executed 1 - end of multichain interchange unit
ASSIGN command). 12,13 reserved - must be set to zero
DATASTR(data-area) 14,15 OO - multichain interchange unit
O1 - single chain interchange unit
corresponds to the data stream profile field, ATTDSP, in
1O - reserved
an LUTYPE6.1 attach FMH. 11 - reserved
For communication between two CICS systems, no
PROCESS(data-area)
particular significance is given by CICS to the data
corresponds to the process name, ATTDPN, in an
stream profile field in an attach FMH. For most CICS
LUTYPE6.1 attach FMH.
applications, the option can be omitted.
For communication between two CICS systems, a
The value returned in the data area is a halfword binary
transaction running in one system can acquire a session
value. Only the low-order byte is used; the SNA-defined
to the second system and can identify the transaction to
meanings of the bits are as follows:
be attached; in the second system the identification is
carried in the first chain of data sent across the session.

84 CICS/ESA Application Programming Reference

EXTRACT ATTACH (MRO)

In general, the first four bytes of data identify the RPROCESS(data-area)

transaction to be attached. However an attach FMH, corresponds to the return process name, ATTRDPN, in
identifying the transaction to be attached, can be built an LUTYPE6.1 attach FMH.
and sent. The receiving CICS system uses just the first
For communication between two CICS systems, no
four bytes of the process name as a transaction name.
significance is attached by CICS to the return process
No significance is attached by CICS to process names in name in an attach FMH.
attach FMHs sent in chains of data other than the first.
For communication between a CICS system and another
For communication between a CICS system and another subsystem, refer to documentation supplied by the
subsystem, refer to documentation supplied by the subsystem about how to use the return process name
subsystem about how to use the process name field in field in an attach FMH.
an attach FMH.
RRESOURCE(data-area)
QUEUE(data-area) corresponds to the return resource name, ATTRPRN, in
corresponds to the queue name, ATTDQN, in an attach an LUTYPE6.1 attach FMH.
FMH.
For communication between two CICS systems, no
For communication between two CICS systems, no significance is attached by CICS to the return resource
significance is attached by CICS to the queue name in name in an attach FMH.
an attach FMH.
For communication between a CICS system and another
For communication between a CICS system and another subsystem, refer to documentation supplied by the
subsystem, refer to documentation supplied by the subsystem about how to use the return resource name
subsystem about how to use the queue name field in an field in an attach FMH.
attach FMH.
SESSION(name)
RECFM(data-area) specifies the symbolic identifier (1–4 characters) of a
corresponds to the deblocking algorithm field, ATTDBA, session TCTTE. This option specifies the alternate
in an LUTYPE6.1 attach FMH. facility to be used.
For communication between two CICS systems, no
particular significance is attached by CICS to the EXTRACT ATTACH (MRO) conditions
deblocking algorithm field in an attach FMH. For most
CICS applications, the option can be omitted. CBIDERR
occurs if the requested attach header control block
For communication between a CICS system and another cannot be found.
subsystem, refer to documentation supplied by the
subsystem about how to use the interchange unit field in Default action: terminate the task abnormally.
an attach FMH. INVREQ
The value returned in the data area is a halfword binary occurs if incorrect data is found.
value. Only the low-order byte is used; the SNA-defined Default action: terminate the task abnormally.
meanings of the bits are as follows:
O-7 reserved - must be set to zero NOTALLOC
8-15 X'OO' - reserved occurs if the facility specified in the command is not
X'O1' - variable-length owned by the application.
variable-blocked Default action: terminate the task abnormally.
X'O2' - reserved
X'O3' - reserved
X'O4' - chain of RUs
X'O5'through X'FF' - reserved

Chapter 1. Commands 85
EXTRACT ATTRIBUTES (APPC)

EXTRACT ATTRIBUTES (APPC)

| Function
| Obtains the state of the APPC conversation.

Command syntax

──EXTRACT ATTRIBUTES──┬──────────────┬──STATE(cvda)──"
└─CONVID(name)─┘
Conditions:
INVREQ, NOTALLOC

EXTRACT ATTRIBUTES extracts conversation state EXTRACT ATTRIBUTES (APPC) conditions

information for APPC mapped conversations.
INVREQ
occurs in any one of the following situations:
EXTRACT ATTRIBUTES (APPC) options
The command is issued against a
CONVID(name) CPI-Communications conversation.
identifies the conversation to which the command
The command is issued against an APPC basic
relates. The 4-character name identifies either the token
conversation. (A GDS EXTRACT ATTRIBUTES
returned by a previously executed ALLOCATE command
should have been used instead.)
in EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed | A distributed program link server application
ASSIGN command). | explicitly, or implicitly by default, specified the
| function-shipping session (its principal facility) on the
For compatibility with earlier releases, SESSION is
| CONVID option (RESP2=200).
accepted as a synonym for CONVID. New programs
should use CONVID. Default action: terminate the task abnormally.
By default, the principal facility is assumed. NOTALLOC
STATE(cvda) occurs if the CONVID value specified in the command
gets the state of the transaction program. The cvda does not relate to a conversation owned by the
values returned by CICS are: application.
Default action: terminate the task abnormally.
ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

86 CICS/ESA Application Programming Reference

EXTRACT ATTRIBUTES (MRO)

Function
Extract attributes from an MRO conversation.

Command syntax

──EXTRACT ATTRIBUTES──┬───────────────┬──STATE(cvda)──"
├─CONVID(name)──┤
└─SESSION(name)─┘
Conditions:
INVREQ, NOTALLOC

EXTRACT ATTRIBUTES (MRO) extracts conversation state EXTRACT ATTRIBUTES (MRO) conditions
information for MRO conversations.
INVREQ
occurs in any one of the following situations:
EXTRACT ATTRIBUTES (MRO) options
An incorrect command has been issued for the
CONVID(name) terminal or LU in use.
identifies the conversation to which the command
| A distributed program link server application
relates. The 4-character name identifies either the token
| explicitly, or implicitly by default, specified the
returned by a previously executed ALLOCATE command
| function-shipping session (its principal facility) on the
in EIBRSRCE in the EIB, or the token representing the
| CONVID option (RESP2=200).
principal session (returned by a previously executed
ASSIGN command). Default action: terminate the task abnormally.
SESSION(name) NOTALLOC
specifies the symbolic identifier (1–4 characters) of a occurs if the facility specified in the command is not
session TCTTE. This option specifies the alternate owned by the application.
facility to be used.
Default action: terminate the task abnormally.
If both this option and CONVID are omitted, the principal
facility for the task is used.

STATE(cvda)
gets the state of the transaction program. The cvda
values returned by CICS are:

ALLOCATED
FREE
PENDFREE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

Chapter 1. Commands 87
EXTRACT LOGONMSG

EXTRACT LOGONMSG

Function
Access VTAM logon data.

Command syntax

──EXTRACT LOGONMSG──┬─INTO(data-area)─┬──LENGTH(data-area)──"
└─SET(ptr-ref)────┘

# Condition: NOTALLOC
EXTRACT LOGONMSG accesses VTAM logon data. This If TASKDATAKEY(USER) is specified for the running
data may have been specified by the terminal operator at task, and storage protection is active, the data returned
logon or in the ISSUE PASS command, for example. This is in a user-key. If TASKDATAKEY(CICS) is specified
data is only available if the system initialization parameter and storage protection is active, the data returned is in a
LGNMSG=YES is specified. The data can only be extracted CICS-key.
once. It is possible to force the first transaction that runs on
the terminal to be that which issues EXTRACT LOGONMSG
# EXTRACT LOGONMSG condition
by using the the system initialization parameter GMTRAN.
# NOTALLOC
All the logon data is extracted and its length placed in the # occurs if the facility specified in the command is not
field specified by the LENGTH option. Because the LENGTH # owned by the application.
option cannot be used to limit the amount of data extracted,
it is recommended that a field of 256 bytes is always used # Default action: terminate the task abnormally.
for this option.

| If you use the SET option, the VTAM logon data is not freed
| until the session terminates (CLSDST). If you use the INTO
| option, the VTAM logon data is copied into user storage and
| then freed.

EXTRACT LOGONMSG options

INTO(data-area)
specifies the receiving field for the data extracted.

LENGTH(data-area)
specifies the length, as a halfword binary value, of the
data extracted. If no data is available, LENGTH is set to
zero.

SET(ptr-ref)
specifies the pointer reference that is to be set to the
address of the data extracted. The pointer reference,
unless changed by other commands or statements, is
valid until the next EXTRACT LOGONMSG command or
the end of task.
If DATALOCATION(ANY) is associated with the
application program, the address of the data can be
above or below the 16MB line.
If DATALOCATION(BELOW) is associated with the
application program, and the data resides above the
16MB line, the data is copied below the 16MB line, and
the address of this copy is returned.

88 CICS/ESA Application Programming Reference

EXTRACT PROCESS

Function
Retrieve values from APPC conversation attach header.

Command syntax

──EXTRACT PROCESS──┬────────────────────────────────────────────────────────────────────────┬────────────
└─PROCNAME(data-area)──PROCLENGTH(data-area)──┬────────────────────────┬─┘
└─MAXPROCLEN(data-value)─┘
──┬──────────────┬──┬──────────────────────┬──┬────────────────────────────────────────┬──"
└─CONVID(name)─┘ └─SYNCLEVEL(data-area)─┘ └─PIPLIST(ptr-ref)──PIPLENGTH(data-area)─┘
Conditions:
INVREQ, LENGERR, NOTALLOC

EXTRACT PROCESS lets an application program access PROCNAME(data-area)

conversation-related data, specified to CICS when the specifies the data area to receive the process name
program is attached. The attach receiver does not have to specified by the remote system that caused the task to
execute an EXTRACT PROCESS command unless it start. The data area can be 1–64 bytes long. The
requires this information. process name is padded on the right with blanks if it is
too short. The PROCNAME data area should not be
The EXTRACT PROCESS command is valid only on an shorter than the MAXPROCLEN value.
APPC conversation that is the principal facility for the task.
SYNCLEVEL(data-area)
specifies a halfword data area that is set by CICS to the
EXTRACT PROCESS options SYNCLEVEL value. For further information about
CONVID(name) synchronization levels, see the CICS/ESA
identifies the conversation to which the command Intercommunication Guide.
relates. The 4-character name identifies the token
representing the principal session. EXTRACT PROCESS conditions
For compatibility with earlier releases, SESSION is
INVREQ
accepted as a synonym for CONVID. New programs
occurs in any of the following situations:
should use CONVID.
EXTRACT PROCESS has been used on a
If this option is omitted, the principal facility is assumed.
conversation other than APPC mapped (for
MAXPROCLEN(data-value) example, LUTYPE6.1, APPC basic, or CPI
specifies the buffer length of PROCNAME. If Communications).
MAXPROCLEN is not specified, the buffer is assumed to
EXTRACT PROCESS has been used on a
have 32 bytes.
conversation that was not started by input from the
PIPLENGTH(data-area) network, and whose session is not a principal
specifies a halfword binary data area in which the total facility.
length of the process initialization parameter (PIP) list is The command is issued against a
returned. CPI-Communications conversation.
PIPLIST(ptr-ref) A distributed program link server application
specifies a pointer reference that is set to the address of specified the function-shipping session (its principal
a CICS-provided data area containing a PIP list. This facility) on the CONVID option (RESP2=200).
list contains variable-length records in the same format
Default action: terminate the task abnormally.
as the list in the CONNECT PROCESS command. A
returned value of zero means that no PIP data has been LENGERR
received by CICS. occurs if the actual length of PROCNAME is greater
than MAXPROCLEN, or greater than 32 bytes if
PROCLENGTH(data-area)
MAXPROCLEN is not specified.
specifies a halfword data area that is set by CICS to the
length of the process name. If PROCNAME is specified, | Default action: terminate the task abnormally.
this option must be specified.

Chapter 1. Commands 89
EXTRACT PROCESS

NOTALLOC
occurs if the CONVID value specified in the command
does not relate to a conversation owned by the
application.
Default action: terminate the task abnormally.

90 CICS/ESA Application Programming Reference

EXTRACT TCT

Function
Convert an 8-character name to a 4-character name on an LUTYPE6.1 logical unit.

Command syntax

──EXTRACT TCT──NETNAME(name)──┬───────────────────┬──"
├─SYSID(systemname)─┤
└─TERMID(data-area)─┘
Conditions:
# INVREQ, NOTALLOC

EXTRACT TCT converts the 8-character VTAM network

name for a logical unit into the corresponding 4-character
name it is known by in the local CICS system.

EXTRACT TCT options

NETNAME(name)
specifies the 8-character name of the logical unit in the
VTAM network.

SYSID(systemname)
specifies the variable to be set to the equivalent local
name of the system.

TERMID(data-area)
specifies the variable to be set to the equivalent local
name of the terminal.

EXTRACT TCT conditions

INVREQ
occurs if NETNAME is not valid.
Default action: terminate the task abnormally.

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

Chapter 1. Commands 91
FORMATTIME

FORMATTIME

Function
Transform absolute date and time into a specified format.

Command syntax

| ──FORMATTIME──ABSTIME(data-area)──┬─────────────────────┬──┬─────────────────┬───────────────────────────
# └─FULLDATE(data-area)─┘ └─DATE(data-area)─┘
──┬─────────────────────┬──┬───────────────────────────┬──┬─────────────────────┬─────────────────────────
└─DATEFORM(data-area)─┘ └─DATESEP──┬──────────────┬─┘ └─DAYCOUNT(data-area)─┘
└─(data-value)─┘
──┬───────────────────────┬──┬──────────────────────┬──┬───────────────────┬──┬─────────────────────┬─────
| └─DAYOFMONTH(data-area)─┘ └─DAYOFWEEK(data-area)─┘ └─DDMMYY(data-area)─┘ └─DDMMYYYY(data-area)─┘
──┬───────────────────┬──┬─────────────────────┬──┬────────────────────────┬──────────────────────────────
| └─MMDDYY(data-area)─┘ └─MMDDYYYY(data-area)─┘ └─MONTHOFYEAR(data-area)─┘
──┬────────────────────────────────────────────────┬──┬─────────────────┬──┬──────────────────┬───────────
└─TIME(data-area)──┬───────────────────────────┬─┘ └─YEAR(data-area)─┘ └─YYDDD(data-area)─┘
└─TIMESEP──┬──────────────┬─┘
└─(data-value)─┘
──┬───────────────────┬──┬───────────────────┬──┬────────────────────┬──┬─────────────────────┬───────────
| └─YYDDMM(data-area)─┘ └─YYMMDD(data-area)─┘ └─YYYYDDD(data-area)─┘ └─YYYYDDMM(data-area)─┘
──┬─────────────────────┬──"
| └─YYYYMMDD(data-area)─┘
Conditions:
INVREQ

FORMATTIME transforms the absolute date and time into To obtain an elapsed time in a particular format, the
any of a variety of formats. Normally, the ABSTIME ABSTIME data value can be the difference between two
argument is the value returned by an ASKTIME ABSTIME values returned by ASKTIME, and options such as
command. DAYCOUNT(d) and TIME(t) can be specified.

| If the milliseconds come to 500 or more, the returned

| seconds and, if necessary, the minutes and hours, are FORMATTIME options
| rounded up. The day, month, and year are, however, never | ABSTIME(data-area)
| rounded up. specifies the data value for the time, in packed decimal,
# since 00:00 hours on 1 January 1900 (in milliseconds
Apar 76793 78317
rounded to the nearest hundredth of a second) that is to
# Documentation for Apar 76793 78317 added 28 Nov be converted to an alternative format.
# 1995 (TUCKER)
The format of the parameter is:
COBOL: PIC S9(15) COMP-3
# However, in the case where the ABSTIME argument contains C: char data_ref[8];
# a value representing the half-second before midnight, no PL/I: FIXED DEC(15);
# rounding is performed, and the TIME parameter returns ASM: PL8
# 23:59:59.
DATE(data-area)
The following example shows the effect of some of the specifies the variable that is to receive the date in the
options of the command. Let “utime” contain the value format specified in the DATFORM system initialization
002837962864828 in milliseconds. parameter. The returned value is in 8-character format.
You should normally use this option only when a date is
EXEC CICS ASKTIME ABSTIME(utime)
needed for output purposes. Where a date is needed
EXEC CICS FORMATTIME ABSTIME(utime)
DATESEP('-') DDMMYY(date) for analysis, you should request the date in explicit form,
TIME(time) TIMESEP for example, using the MMDDYY option.

| This gives the values 06-12-89 for “date” and 19:01:05 for DATEFORM(data-area)
“time”. specifies the format of the installation-defined date.
CICS returns YYMMDD, DDMMYY, or MMDDYY (six

92 CICS/ESA Application Programming Reference

FORMATTIME

characters) according to the DATFORM system # 10/21/95). A separator is present if requested by the
initialization parameter. # DATESEP option. If no separator is requested, the
# returned value is left-justified in the 8-character user
DATESEP(data-value)
# field.
specifies the character to be inserted as the separator
between the year and the month, and between the day | MMDDYYYY(data-area)
and the month; or between the year and the day if form | specifies the 10-character user field where CICS is to
YYDDD is specified. | return the date, in month/day/year format (for example
| 11/21/1995).
If you omit this option, no separator is supplied. If you
omit “data-value”, a slash (/) is assumed as the MONTHOFYEAR(data-area)
separator. “data-area” is set to the relative month number of the
year as a fullword binary number (January=1,
DAYCOUNT(data-area)
December=12). You can convert this number, in your
returns the number of days since 1 January 1900 (day
application program, to the name of the month in any
1), as a fullword binary number. This is useful if you
language.
need to compare the current date with a previous date
that has, for example, been stored in a data set. TIME(data-area)
“data-area” is set as an 8-character field to the current
DAYOFMONTH(data-area)
24-hour clock time in the form hh:mm:ss, where the
returns the number of the day in the month as a fullword
separator is specified by the TIMESEP option.
binary number.
| If the milliseconds come to 500 or more, the returned
DAYOFWEEK(data-area)
| seconds and, if necessary, the minutes and hours, are
returns the relative day number of the week as a
| rounded up. The day, month, and year are, however,
fullword binary number: Sunday=0, Saturday=6. This
| never rounded up.
number can be converted to a textual form of day in any
language. TIMESEP(data-value)
specifies the character to be used as the separator in
DDMMYY(data-area)
the returned time. If you omit this option, no separator is
specifies the 8-character user field where CICS is to
assumed and six bytes are returned in an 8-character
return the date, in day/month/year format (for example,
field. If you omit the “data-value”, a colon (:) is used as
# 21/10/95). A separator is present if requested by the
a separator.
# DATESEP option. If no separator is requested, the
# returned value is left-justified in the 8-character user YEAR(data-area)
# field. specifies the full 4-figure number of the year as a
fullword binary number (for example, 1995, 2001).
| DDMMYYYY(data-area)
| specifies the 10-character user field where CICS is to YYDDD(data-area)
| return the date, in day/month/year format (for example specifies the 6-character user field where CICS is to
| 17/06/1995). A separator is present if requested by the return the date, in year/day format (for example, 95/301).
# DATESEP option. If no separator is requested, the # A separator is present if requested by the DATESEP
# returned value is left-justified in the 10-character user # option. If no separator is requested, the returned value
# field. # is left-justified in the 6-character user field.
# Apar PQ00059 YYDDMM(data-area)
# Documentation for Apar PQ00059 added 20/03/97 specifies the 8-character user field where CICS is to
return the date, in year/day/month format (for example,
# 95/30/10). A separator is present if requested by the
# FULLDATE(data-area) # DATESEP option. If no separator is requested, the
# specifies the 10-character user field where CICS is to # returned value is left-justified in the 8-character user
# return the date, in the format specified in the DATFORM # field.
# system initialization parameter, with the year expanded
# to 4 digits. A separator is present if requested by the YYMMDD(data-area)
# DATESEP option. If no separator is requested, the specifies the 8-character user field where CICS is to
# returned value is left-justified in the 10-character user return the date, in year/month/day format (for example,
# field. You should normally use this option only when a 95/10/21).
# date is needed for output purposes. Where a date is
| YYYYDDD(data-area)
# needed for analysis, you should request the date in
| specifies the 8-character user field where CICS is to
# explicit form, for example, using the MMDDYYYY option.
| return the date, in year/day format (for example
MMDDYY(data-area) | 1995/200). A separator is present if requested by the
specifies the 8-character user field in which CICS is to # DATESEP option. If no separator is requested, the
return the date, in month/day/year format (for example,

Chapter 1. Commands 93
FORMATTIME

# returned value is left-justified in the 8-character user

# field.

| YYYYDDMM(data-area)
| specifies the 10-character user field where CICS is to
| return the date, in year/day/month format (for example
| 1995/21/06). A separator is present if requested by the
# DATESEP option. If no separator is requested, the
# returned value is left-justified in the 10-character user
# field.

| YYYYMMDD(data-area)
| specifies the 10-character user field where CICS is to
| return the date, in year/month/day format (for example
| 1995/06/21). A separator is present if requested by the
# DATESEP option. If no separator is requested, the
# returned value is left-justified in the 10-character user
# field.

FORMATTIME condition
INVREQ
occurs if the ABSTIME option is in an incorrect form
(RESP2=1).
Default action: terminate the task abnormally.

94 CICS/ESA Application Programming Reference

FREE

| FREE

| Function
| Return a terminal or logical unit.

| Command syntax

|
| ──FREE──"
| Conditions:
| NOTALLOC

| FREE returns a terminal or logical unit when the transaction

| owning it no longer requires it. The principal facility is freed.

| If you are running EDF, and the transaction frees the

| principal facility, EDF is terminated.

| FREE conditions
| NOTALLOC
| occurs if the task is not associated with the terminal.
| Default action: terminate the task abnormally.

Chapter 1. Commands 95
FREE (APPC)

FREE (APPC)

Function
Return an APPC mapped session to CICS.

Command syntax

──FREE──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC

FREE returns an APPC session to CICS when a transaction FREE (APPC) conditions
owning it no longer requires it. The session can then be
allocated for use by other transactions. INVREQ
occurs in any of the following situations:
| If you omit CONVID, the principal facility is freed. Facilities
The CONVID value specified in the command
not freed explicitly are freed by CICS when the task
relates to a basic (unmapped) APPC conversation.
terminates.
The CONVID value specified in the command
If you are running EDF, and the transaction frees the relates to a CPI-Communications conversation.
principal facility, EDF is terminated.
A distributed program link server application
specified the function-shipping session (its principal
FREE (APPC) options facility) on the CONVID option (RESP2=200).

CONVID(name) Default action: terminate the task abnormally.

identifies the APPC mapped session to be freed. The
NOTALLOC
4-character name identifies either the token returned by
| occurs if the specified CONVID value does not relate to
a previously executed ALLOCATE command in
| a conversation owned by the application.
EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed Default action: terminate the task abnormally.
ASSIGN command).
If this option is omitted, the principal facility is assumed.

STATE(cvda)
gets the state of the current conversation. The STATE
option on a FREE command returns a cvda code of 00 if
there is no longer an active conversation. The other
output cvda values are:

ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

96 CICS/ESA Application Programming Reference

FREE (LUTYPE6.1)

Function
Return LUTYPE6.1 sessions to CICS.

Command syntax

──FREE──┬───────────────┬──"
├─CONVID(name)──┤
└─SESSION(name)─┘
Conditions:
INVREQ, NOTALLOC

FREE returns an LUTYPE6.1 session to CICS when a

transaction owning it no longer requires it. The session can
then be allocated for use by other transactions.

If you omit both CONVID and SESSION, the principal facility

is freed. Facilities not freed explicitly are freed by CICS
when the task terminates.

If you are running EDF, and the transaction frees the

principal facility, EDF is terminated.

FREE (LUTYPE6.1) options

CONVID(name)
identifies the LUTYPE6.1 session to be freed. The
4-character name identifies either the token returned by
a previously executed ALLOCATE command in
EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed
ASSIGN command).

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be used.

FREE (LUTYPE6.1) conditions

INVREQ
occurs if the session specified in the command was
allocated for a basic (unmapped) APPC conversation.
(See also EIBRCODE in Appendix A, “EXEC interface
block” on page 343.)
Default action: terminate the task abnormally.

NOTALLOC
occurs if the session specified in the command is not
owned by the application.
Default action: terminate the task abnormally.

Chapter 1. Commands 97
FREE (MRO)

FREE (MRO)

Function
Return MRO sessions to CICS.

Command syntax

──FREE──┬───────────────┬──┬─────────────┬──"
├─CONVID(name)──┤ └─STATE(cvda)─┘
└─SESSION(name)─┘
Conditions:
INVREQ, NOTALLOC

FREE returns an MRO session to CICS when a transaction FREE (MRO) conditions
owning it no longer requires it. The session can then be
allocated for use by other transactions. INVREQ
occurs in any one of the following situations:
If you omit both CONVID and SESSION, the principal facility
The session specified in the command was
is freed. Facilities not freed explicitly are freed by CICS
allocated for a basic (unmapped) APPC
when the task terminates.
conversation
If you are running EDF, and the transaction frees the The session is in the wrong state to be freed.
principal facility, EDF is terminated.
(See also EIBRCODE in Appendix A, “EXEC interface
block” on page 343.)
FREE (MRO) options
Default action: terminate the task abnormally.
CONVID(name)
NOTALLOC
identifies the MRO session to be freed. The 4-character
occurs if the session specified in the command is not
name identifies either the token returned by a previously
owned by the application.
executed ALLOCATE command in EIBRSRCE in the
EIB, or the token representing the principal session Default action: terminate the task abnormally.
(returned by a previously executed ASSIGN command).

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be used.

STATE(cvda)
gets the state of the current conversation. The STATE
on a FREE command returns a cvda code of 00 if there
is no longer an active conversation. The other output
cvda values are:

ALLOCATED
FREE
PENDFREE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

98 CICS/ESA Application Programming Reference

FREEMAIN

Function
Release main storage acquired by a GETMAIN command.

Command syntax

──FREEMAIN──┬─DATA(data-area)────────┬──"
| └─DATAPOINTER(ptr-value)─┘
Conditions:
INVREQ

| Note for dynamic transaction routing

| Using FREEMAIN of storage GETMAINed with SHARED, or of a resource defined with RELOAD=YES that has been
| LOADed could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See the
| CICS/ESA Application Programming Guide for more information about transaction affinities.

FREEMAIN releases main storage previously acquired by a COBOL

| GETMAIN command issued by the application, or by a LOAD
DATA DIVISION.
| for a program, map, or table, defined with RELOAD=YES. If WORKING-STORAGE SECTION.
| the task that GETMAINed the storage or LOADed the 77 AREA-POINTER USAGE IS POINTER.
| program does not release it, CICS releases it at task end, LINKAGE SECTION.
| unless: O1 WORKAREA PIC X(1OO).
| The GETMAIN command specified the SHARED option PROCEDURE DIVISION.
EXEC CICS GETMAIN SET(AREA-POINTER)
| The program is defined with RELOAD=YES LENGTH(1OO)
| The program is defined with RELOAD=NO but was END-EXEC.
.
| LOADed with the HOLD option.
SET ADDRESS OF WORKAREA TO AREA-POINTER.
| In the first two cases, the storage remains allocated until .
.
| some other task issues a FREEMAIN to release it. In the
EXEC CICS FREEMAIN DATA(WORKAREA)
| third case, the program remains available until it is
END-EXEC.
| RELEASEd by another task. EXEC CICS RETURN
END-EXEC.
You can release CICS-key storage from a program only if it
is being executed in CICS key. If the previously-acquired
storage was obtained from CICS-key storage, and the
program issuing the FREEMAIN is in user-key, an INVREQ
condition occurs with a RESP2 value of 2.

Here are some examples of the use of FREEMAIN.

Chapter 1. Commands 99
FREEMAIN

Alternatively, the previous COBOL example could free the C

storage by the following command:
#pragma XOPTS(CICS);
EXEC CICS FREEMAIN DATAPOINTER(AREA-POINTER) #define MAINSIZE 1OO;
END-EXEC. main()
{
char _buffer;
struct eib_record dfheiptr;
EXEC CICS ADDRESS EIB(dfheiptr);
EXEC CICS GETMAIN SET(buffer)
LENGTH(MAINSIZE);
buffer[2] = 'a';
.
.
EXEC CICS FREEMAIN DATA(buffer);
EXEC CICS RETURN;
}

PL/I
DCL AREA_PTR POINTER,
WORKAREA CHAR(1OO) BASED(AREA_PTR);
.
.
.
EXEC CICS GETMAIN SET(AREA_PTR) LENGTH(1OO);
.
EXEC CICS FREEMAIN DATA(WORKAREA);

Assembler
WORKAREA DS CL1OO
.
.
EXEC CICS GETMAIN SET(9) LENGTH(1OO)
USING WORKAREA,9
EXEC CICS FREEMAIN DATA(WORKAREA)

100 CICS/ESA Application Programming Reference

FREEMAIN

Alternatively, you can free storage using the DATAPOINTER FREEMAIN option
option as shown in the following example:
DATA(data-area)
WORKAREA DS CL1OO
. specifies the data area of main storage to be released.
EXEC CICS GETMAIN SET(9) LENGTH(1OO) This storage must have been acquired by a previous
USING WORKAREA,9 GETMAIN command, except in the case of BMS pages.
. (For more guidance about BMS pages, see the
. description of the SET option in the CICS/ESA
DROP 9
Application Programming Guide.)
.
EXEC CICS FREEMAIN DATAPOINTER(9) Note that this option specifies the data area that was
acquired by the GETMAIN command, not the pointer
reference that was set to that address. You must use
the DATAPOINTER option to specify a pointer-reference:
DATA and DATAPOINTER are mutually exclusive.
Therefore, in assembler language, “data-area” must be a
relocatable expression that is a data reference; in
COBOL or C it must be a data name; and in PL/I it must
be a data reference. (See the CICS/ESA Application
Programming Guide for a discussion of argument
values.)
The length of storage released is the length obtained by
the GETMAIN and not necessarily the length of the data
area.

| DATAPOINTER(ptr-value)
specifies the address of the main storage to be released.
This option is an alternative to the DATA option, and
specifies the pointer reference that was returned by a
GETMAIN command using the SET option.
The length of storage released is the length obtained by
the GETMAIN.

FREEMAIN condition
INVREQ
occurs in any one of the following situations:

The storage specified by the DATA or

DATAPOINTER parameter is not storage acquired
by a GETMAIN command (RESP2=1).
The storage area specified by the DATA or
DATAPOINTER parameter is in CICS-key storage,
and the program issuing the FREEMAIN command
is in user-key (RESP2=2).

Default action: terminate the task abnormally.

Chapter 1. Commands 101

GDS ALLOCATE

Function
Acquire a session to a remote system for use by APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS ALLOCATE──┬─SYSID(systemname)──┬────────────────┬─┬──CONVID(data-area)──RETCODE(data-area)─────────
│ └─MODENAME(name)─┘ │
| └─PARTNER(name)─────────────────────────┘
──┬─────────┬──┬─────────────┬──"
└─NOQUEUE─┘ └─STATE(cvda)─┘

GDS ALLOCATE acquires a session to a remote system. The CICS allocation algorithm has selected a
contention loser (in which case, CICS has to bid).
The return code is given in RETCODE (see Table 1 on
page 103). For a list of return code values, see the If there is a delay, the program waits until the session
CICS/ESA Distributed Transaction Programming Guide. has been acquired.
EXEC CICS conditions are never raised on GDS commands.
| PARTNER(name)
| specifies the name (8 characters) of a set of definitions
GDS ALLOCATE options | that include the names of a remote LU (NETNAME) and
| a communication profile to be used on the allocated
In general, the arguments can be replaced by absolute or | session. For APPC basic conversations, the only
relocatable assembler-language expressions. | relevant attribute set by the profile is MODENAME.
CONVID(data-area) | If you use this option as an alternative to SYSID and
specifies the 4-character application data area that is to | MODENAME, CICS uses the NETNAME and
contain the token returned by an ALLOCATE command | MODENAME from the PARTNER definition.
to identify the allocated conversation. This token is
RETCODE(data-area)
required in subsequent GDS commands issued on the
specifies the 6-byte application data area into which
conversation.
return code information is to be moved.
MODENAME(name)
STATE(cvda)
specifies the name of the mode group from which the
gets the state of the current conversation. The cvda
| session is to be acquired. If you specify SYSID and
values returned by CICS are:
| omit MODENAME, CICS selects a modename from
| those defined for the system. ALLOCATED
CONFFREE
NOQUEUE
CONFRECEIVE
specifies that the request to allocate a session is not to
CONFSEND
be queued when a suitable APPC session cannot be
FREE
acquired immediately. A session is acquired
PENDFREE
immediately only if it is a bound contention winner that is
PENDRECEIVE
not already allocated to another conversation.
RECEIVE
The return code in RETCODE indicates whether or not a ROLLBACK
session has been acquired. SEND
If the NOQUEUE option is not used, a delay may occur SYNCFREE
before control is passed back to the application program. SYNCRECEIVE
A delay can occur for any of the following reasons: SYNCSEND

All sessions for the specified SYSID and SYSID(systemname)

MODENAME are in use. specifies the remote system to which an APPC session
is to be allocated. The name, which is 1–4 characters,
The CICS allocation algorithm has selected a identifies an entry (defined as an APPC connection) in
session that is not currently bound (in which case, the CICS terminal control table.
CICS has to bind).

102 CICS/ESA Application Programming Reference

GDS ALLOCATE

Table 1. GDS ALLOCATE return codes

RETCODE Description
(hexadecimal)
01 0C 00 SYSID is unrecognized.
01 0C 04 SYSID is not an LUTYPE6.2 connection name.
01 04 04 NOQUEUE is specified but no bound
connection-winner sessions are available.
01 04 08 MODENAME is not known.
01 04 0C The MODENAME value is SNASVCMG which
is restricted to use by CICS.
01 04 0C VTAM has no class of service (COS) table for
the MODENAME value.
01 04 10 The task was canceled during queuing of the
command.
01 04 14 All modegroups are closed.
01 04 14 The requested modegroup is closed.
01 04 18 The requested modegroup is draining (closing
down).
01 08 00 All sessions in the requested modegroup are
unusable.
01 08 00 The connection is in quiesce state.
01 08 00 The connection is out of service.
01 08 00 The connection is not acquired.
01 08 00 The requested modegroup’s local max
(maximum permitted number of sessions) is 0.
01 08 00 The VTAM ACB is closed.
| 01 0C 14 The NETNAME specified in the PARTNER
| definition is not known.
| 02 0C 00 PARTNER is not known.
| 06 00 00 The PROFILE specified in the PARTNER
| definition is not known.

Chapter 1. Commands 103

GDS ASSIGN

Function
Get identifier of principal facility in use by APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS ASSIGN──┬───────────────────────┬──┬──────────────────────┬──RETCODE(data-area)──"
└─PRINCONVID(data-area)─┘ └─PRINSYSID(data-area)─┘

GDS ASSIGN gets the identifier of the principal facility.

The return code is given in RETCODE (see Table 2). For a

list of return code values, see the CICS/ESA Distributed
Transaction Programming Guide. EXEC CICS conditions are
never raised on GDS commands.

GDS ASSIGN options

In general, the arguments can be replaced by absolute or
relocatable assembler-language expressions.

PRINCONVID(data-area)
specifies a 4-byte data area in which the conversation
token (CONVID) of the principal facility is to be returned.

PRINSYSID(data-area)
specifies a 4-byte data area in which the SYSID of the
principal facility is to be returned.

RETCODE(data-area)
specifies the 6-byte application data area into which
return code information is to be moved.

Table 2. GDS ASSIGN return codes

RETCODE Description
(hexadecimal)
03 00 Principal facility is not APPC.
03 04 Principal facility is not basic.
04 No terminal principal facility exists.

104 CICS/ESA Application Programming Reference

GDS CONNECT PROCESS

Function
Initiate APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS CONNECT PROCESS──CONVID(name)──┬─PROCNAME(name)──┬────────────────────────┬─┬──────────────────────

| │ └─PROCLENGTH(data-value)─┘ │
| └─PARTNER(name)──────────────────────────────┘
──┬───────────────────────────────────────────────┬──SYNCLEVEL(data-value)──CONVDATA(data-area)───────────
└─PIPLIST(data-area)──┬───────────────────────┬─┘
└─PIPLENGTH(data-value)─┘
──RETCODE(data-area)──┬─────────────┬──"
| └─STATE(cvda)─┘

EXEC CICS conditions are never raised on GDS commands. PIPLIST(data-area)

specifies the PIP data that is to be sent to the remote
The return code is given in RETCODE (see Table 3 on process. See the CICS/ESA Distributed Transaction
page 106). For a list of return code values, see the Programming Guide for information about PIP data.
CICS/ESA Distributed Transaction Programming Guide.
EXEC CICS conditions are never raised on GDS commands. PROCLENGTH(data-value)
specifies the length (as a halfword binary value in the
GDS CONNECT PROCESS allows the application program range 1–64) of the target process name.
to specify a partner application that is to run in the remote
PROCNAME(name)
system.
specifies the name of the remote application. The APPC
architecture allows names of lengths (1–64 bytes), but
GDS CONNECT PROCESS options leaves each product free to set its own maximum. If the
remote system is CICS, you can use the standard
In general, the arguments can be replaced by absolute or 4-character transaction ID. If the remote system is
relocatable assembler-language expressions. CICS/ESA Version 3.2.1 or higher, you can also use the
CONVDATA(data-area) TPNAME value in the transaction definition.
specifies the 24-byte application data area into which RETCODE(data-area)
conversation-related information is to be moved. A specifies the 6-byte application data area into which
description of the format of the data area is given in the return code information is to be moved.
discussion of CONVDATA fields in the CICS/ESA
Distributed Transaction Programming Guide. | STATE(cvda)
| gets the state of the current conversation. The cvda
CONVID(name) | values returned by CICS are:
identifies the conversation to which the command
relates. The 4-character name identifies either the token | ALLOCATED
returned by a previously executed GDS ALLOCATE | CONFFREE
command, or the token representing the principal | CONFRECEIVE
session (returned by a previously executed GDS | CONFSEND
ASSIGN command). | FREE
| PENDFREE
| PARTNER(name) | PENDRECEIVE
| specifies the name (8 characters) of a set of definitions | RECEIVE
| that includes the name (or extended name) of a remote | ROLLBACK
| partner transaction (TPNAME or XTPNAME). You can | SEND
| use this option as an alternative to PROCNAME and | SYNCFREE
| PROCLENGTH. | SYNCRECEIVE
PIPLENGTH(data-value) | SYNCSEND
specifies the total length of the process initialization
parameter (PIP) list specified on a CONNECT
PROCESS command.

Chapter 1. Commands 105

GDS CONNECT PROCESS

SYNCLEVEL(data-value)
Table 3. GDS CONNECT PROCESS return codes
specifies the synchronization level (halfword binary
value) desired for the current conversation. The RETCODE Description
(hexadecimal)
possible values are:
| 02 0C 00 PARTNER is not known.
0 None
03 00 CONVID is for a session that is not APPC.
1 Confirm
2 Syncpoint. 03 00 CONVID is for a session that is in use by CPI
Communications.
03 04 CONVID is for a conversation that is not basic.
03 0C The SYNCLEVEL option specifies a value
other than 0, 1, or 2.
03 0C The SYNCLEVEL option requested either 1 or
2, but it was unavailable.
03 08 A state check occurred.
04 CONVID is for a session that is not allocated
to the task, or that is a relay link.
05 00 00 00 PROCLENGTH is outside the range 1–64.
00 20
05 00 00 00 The PIPLENGTH value is outside the range
7F FF 4–763.
05 00 00 00 The 2-byte length field (LL) for one of the PIPs
7F FF is less than 4.
05 00 00 00 The total of the LLs in PIP data is greater than
7F FF the PIPLENGTH value.

106 CICS/ESA Application Programming Reference

GDS EXTRACT ATTRIBUTES

Function
Access state information on an APPC basic conversation (assembler-language and C programs only).

Command syntax

| ──GDS EXTRACT ATTRIBUTES──CONVID(name)──┬─────────────┬──CONVDATA(data-area)──RETCODE(data-area)──"

└─STATE(cvda)─┘

GDS EXTRACT ATTRIBUTES accesses state information STATE(cvda)

about an APPC basic conversation. gets the state of the current conversation. The cvda
values returned by CICS are:
The return code is given in RETCODE (see Table 4). For a
list of return code values, see the CICS/ESA Distributed ALLOCATED
Transaction Programming Guide. EXEC CICS conditions are CONFFREE
never raised on GDS commands. CONFRECEIVE
CONFSEND
FREE
GDS EXTRACT ATTRIBUTES options PENDFREE
PENDRECEIVE
In general, the arguments can be replaced by absolute or
RECEIVE
relocatable assembler-language expressions.
ROLLBACK
CONVID(name) SEND
identifies the conversation to which the command SYNCFREE
relates. The 4-character name identifies either the token SYNCRECEIVE
returned by a previously executed GDS ALLOCATE SYNCSEND
command, or the token representing the principal
session (returned by a previously executed GDS Table 4. GDS EXTRACT ATTRIBUTES return codes
ASSIGN command). RETCODE Description
(hexadecimal)
| CONVDATA(data-area)
| specifies the 24-byte application data area into which 03 00 CONVID is for a session that is not APPC.
| conversation-related information is to be moved. A 03 00 CONVID is for a session that is in use by CPI
| description of the format of the data area is given in the Communications.
| discussion of CONVDATA fields in the CICS/ESA | 03 01 INVREQ for a DPL server program.
| Distributed Transaction Programming Guide.
03 04 CONVID is for a conversation that is not basic.
RETCODE(data-area) 04 CONVID is for a session that is not allocated
specifies the 6-byte application data area into which to the task, or that is a relay link.
return code information is to be moved.

Chapter 1. Commands 107

GDS EXTRACT PROCESS

Function
Retrieve values from an APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS EXTRACT PROCESS──CONVID(name)──────────────────────────────────────────────────────────────────────

──┬────────────────────────────────────────────────────────────────────────┬──┬──────────────────────┬────
└─PROCNAME(data-area)──PROCLENGTH(data-area)──┬────────────────────────┬─┘ └─SYNCLEVEL(data-area)─┘
└─MAXPROCLEN(data-value)─┘
──┬────────────────────────────────────────────┬──RETCODE(data-area)──"
└─PIPLIST(pointer-ref)──PIPLENGTH(data-area)─┘

GDS EXTRACT PROCESS retrieves values from an APPC attach function management header, is to be moved.
basic conversation. The data retrieved is valid only when the The area is padded with blanks, if necessary.
command is issued against an APPC basic principal facility.
RETCODE(data-area)
The return code is given in RETCODE (see Table 5). For a specifies the 6-byte application data area into which
list of return code values, see the CICS/ESA Distributed return code information is to be moved.
Transaction Programming Guide. EXEC CICS conditions are
SYNCLEVEL(data-area)
never raised on GDS commands.
specifies a halfword binary data area that is set to
indicate the synchronization level in effect for the current
GDS EXTRACT PROCESS options conversation. The possible values are:

In general, the arguments can be replaced by absolute or 0 None

relocatable assembler-language expressions. 1 Confirm
2 Syncpoint.
CONVID(name)
identifies the conversation the command relates to. The Table 5. GDS EXTRACT PROCESS return codes
4-character name identifies the token representing the
RETCODE Description
principal session (returned by a previously executed (hexadecimal)
GDS ASSIGN command).
03 00 CONVID is for a session that is not APPC.
MAXPROCLEN(data-value) 03 00 CONVID is for a session that is in use by CPI
specifies the length (1–64 characters) of the Communications.
PROCNAME data area. If MAXPROCLEN is not
03 00 CONVID is for a session that is not the
specified, the buffer is assumed to have 32 bytes.
principal facility.
PIPLENGTH(data-area) 03 00 Principal facility was not started by terminal
specifies a halfword binary data area that is to receive data.
the length of the PIPLIST received by a GDS EXTRACT 03 04 CONVID is for a conversation that is not basic.
PROCESS command.
04 CONVID is for a session that is not allocated
PIPLIST(pointer-ref) to the task, or that is a relay link.
specifies the pointer reference that is to be set to the 05 00 00 00 PROCLENGTH value returned is greater than
address of the PIPLIST received by a GDS EXTRACT 00 20 MAXPROCLEN value.
PROCESS command. A zero setting indicates that no
PIPLIST was received.

PROCLENGTH(data-area)
specifies a halfword binary data area that is set to the
actual length of the process name.

PROCNAME(data-area)
specifies the application target data area (1–64 bytes)
into which the process name, specified in the APPC

108 CICS/ESA Application Programming Reference

GDS FREE

Function
Return an APPC session to CICS (assembler-language and C programs only).

Command syntax

| ──GDS FREE──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"
└─STATE(cvda)─┘

GDS FREE returns the session to CICS. The issue of this STATE(cvda)
command is valid only when the conversation is finished, that gets the state of the current conversation. The STATE
is, the conversation state is FREE. on a FREE command returns a cvda code of 00 if there
is no longer an active conversation. The other output
The return code is given in RETCODE (see Table 6). For a cvda values are:
list of return code values, see the CICS/ESA Distributed
Transaction Programming Guide. EXEC CICS conditions are ALLOCATED
never raised on GDS commands. CONFFREE
CONFRECEIVE
CONFSEND
GDS FREE options FREE
PENDFREE
In general, the arguments can be replaced by absolute or
PENDRECEIVE
relocatable assembler-language expressions.
RECEIVE
| CONVDATA(data-area) ROLLBACK
| specifies the 24-byte application data area into which SEND
| conversation-related information is to be moved. A SYNCFREE
| description of the format of the data area is given in the SYNCRECEIVE
| discussion of CONVDATA fields in the CICS/ESA SYNCSEND
| Distributed Transaction Programming Guide.
Table 6. GDS FREE return codes
CONVID(name)
RETCODE Description
identifies the conversation to be freed. The 4-character
(hexadecimal)
name identifies either the token returned by a previously
executed GDS ALLOCATE command, or the token 03 00 CONVID is for a session that is not APPC.
representing the principal session (returned by a 03 00 CONVID is for a session that is in use by CPI
previously executed GDS ASSIGN command). Communications.

RETCODE(data-area) 03 04 CONVID is for a conversation that is not basic.

specifies the 6-byte application data area into which 03 08 A state check has occurred.
return code information is to be moved. 04 CONVID is for a session that is not allocated
to the task, or that is a relay link.

Chapter 1. Commands 109

GDS ISSUE ABEND

Function
Terminate APPC basic conversation abnormally (assembler-language and C programs only).

Command syntax

| ──GDS ISSUE ABEND──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"

└─STATE(cvda)─┘

GDS ISSUE ABEND causes an APPC basic conversation to STATE(cvda)

end immediately, regardless of the conversation state. The gets the state of the current conversation. The cvda
partner transaction is informed. values returned by CICS are:

The return code is given in RETCODE (see Table 7). For a ALLOCATED
list of return code values, see the CICS/ESA Distributed CONFFREE
Transaction Programming Guide. EXEC CICS conditions are CONFRECEIVE
never raised on GDS commands. CONFSEND
FREE
PENDFREE
GDS ISSUE ABEND options PENDRECEIVE
RECEIVE
In general, the arguments can be replaced by absolute or
ROLLBACK
relocatable assembler-language expressions.
SEND
CONVDATA(data-area) SYNCFREE
specifies the 24-byte application data area into which SYNCRECEIVE
conversation-related information is to be moved. A SYNCSEND
description of the format of the data area is given in the
discussion of CONVDATA fields in the CICS/ESA Table 7. GDS ISSUE ABEND return codes
Distributed Transaction Programming Guide. RETCODE Description
(hexadecimal)
CONVID(name)
identifies the conversation to which the command 03 00 CONVID is for a session that is not APPC.
relates. The 4-character name identifies either the token 03 00 CONVID is for a session that is in use by CPI
returned by a previously executed GDS ALLOCATE Communications.
command, or the token representing the principal 03 04 CONVID is for a conversation that is not basic.
session (returned by a previously executed GDS
03 08 A state check has occurred.
ASSIGN command).
04 CONVID is for a session that is not allocated
RETCODE(data-area) to the task, or that is a relay link.
specifies the 6-byte application data area into which
return code information is to be moved.

110 CICS/ESA Application Programming Reference

GDS ISSUE CONFIRMATION

Function
Issue synchronization request on APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS ISSUE CONFIRMATION──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"

└─STATE(cvda)─┘

GDS ISSUE CONFIRMATION issues a synchronization STATE(cvda)

request in response to a GDS SEND CONFIRM issued by a gets the state of the current conversation. The cvda
partner transaction. values returned by CICS are:

The return code is given in RETCODE (see Table 8). For a ALLOCATED
list of return code values, see the CICS/ESA Distributed CONFFREE
Transaction Programming Guide. EXEC CICS conditions are CONFRECEIVE
never raised on GDS commands. CONFSEND
FREE
PENDFREE
GDS ISSUE CONFIRMATION options PENDRECEIVE
RECEIVE
In general, the arguments can be replaced by absolute or
ROLLBACK
relocatable assembler-language expressions.
SEND
CONVDATA(data-area) SYNCFREE
specifies the 24-byte application data area into which SYNCRECEIVE
conversation-related information is to be moved. A SYNCSEND
description of the format of the data area is given in the
discussion of CONVDATA fields in the CICS/ESA Table 8. GDS ISSUE CONFIRMATION return codes
Distributed Transaction Programming Guide. RETCODE Description
(hexadecimal)
CONVID(name)
identifies the conversation to which the command 03 00 CONVID is for a session that is not APPC.
relates. The 4-character name identifies either the token 03 00 CONVID is for a session that is in use by CPI
returned by a previously executed GDS ALLOCATE Communications.
command, or the token representing the principal 03 04 CONVID is for a conversation that is not basic.
session (returned by a previously executed GDS
03 08 A state check has occurred.
ASSIGN command).
03 14 The command was issued for a sync level 0
RETCODE(data-area) conversation.
specifies the 6-byte application data area into which
04 CONVID is for a session that is not allocated
return code information is to be moved.
to the task, or that is a relay link.

Chapter 1. Commands 111

GDS ISSUE ERROR

Function
Inform APPC basic conversation partner of error (assembler-language and C programs only).

Command syntax

──GDS ISSUE ERROR──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"

└─STATE(cvda)─┘

GDS ISSUE ERROR informs the conversation partner that STATE(cvda)

there is an error. gets the state of the current conversation. The cvda
values returned by CICS are:
The return code is given in RETCODE, see below. For a list
of return code values, see the CICS/ESA Distributed ALLOCATED
Transaction Programming Guide. EXEC CICS conditions are CONFFREE
never raised on GDS commands. CONFRECEIVE
CONFSEND
FREE
GDS ISSUE ERROR options PENDFREE
PENDRECEIVE
In general, the arguments can be replaced by absolute or
RECEIVE
relocatable assembler-language expressions.
ROLLBACK
CONVDATA(data-area) SEND
specifies the 24-byte application data area into which SYNCFREE
conversation-related information is to be moved. A SYNCRECEIVE
description of the format of the data area is given in the SYNCSEND
discussion of CONVDATA fields in the CICS/ESA
Distributed Transaction Programming Guide. Table 9. GDS ISSUE ERROR return codes
RETCODE Description
CONVID(name)
(hexadecimal)
identifies the conversation to which the command
relates. The 4-character name identifies either the token 03 00 CONVID is for a session that is not APPC.
returned by a previously executed GDS ALLOCATE 03 00 CONVID is for a session that is in use by CPI
command, or the token representing the principal Communications.
session (returned by a previously executed GDS 03 04 CONVID is for a conversation that is not basic.
ASSIGN command).
03 08 A state check has occurred.
RETCODE(data-area) 04 CONVID is for a session that is not allocated
specifies the 6-byte application data area into which to task, or that is a relay link.
return code information is to be moved.

112 CICS/ESA Application Programming Reference

GDS ISSUE PREPARE

Function
Issue first flow of syncpoint request on APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS ISSUE PREPARE──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"

└─STATE(cvda)─┘

GDS ISSUE PREPARE issues first flow of syncpoint request. STATE(cvda)

gets the state of the current conversation. The cvda
The return code is given in RETCODE (see Table 10). For values returned by CICS are:
a list of return code values, see the CICS/ESA Distributed
Transaction Programming Guide. EXEC CICS conditions are ALLOCATED
never raised on GDS commands. CONFFREE
CONFRECEIVE
CONFSEND
GDS ISSUE PREPARE options FREE
PENDFREE
In general, the arguments can be replaced by absolute or
PENDRECEIVE
relocatable assembler-language expressions.
RECEIVE
CONVDATA(data-area) ROLLBACK
specifies the 24-byte application data area into which SEND
conversation-related information is to be moved. A SYNCFREE
description of the format of the data area is given in the SYNCRECEIVE
discussion of CONVDATA fields in the CICS/ESA SYNCSEND
Distributed Transaction Programming Guide.
Table 10. GDS ISSUE PREPARE return codes
CONVID(name)
RETCODE Description
identifies the conversation to which the command
(hexadecimal)
relates. The 4-character name identifies either the token
returned by a previously executed GDS ALLOCATE 03 00 CONVID is for a session that is not APPC.
command, or the token representing the principal 03 00 CONVID is for a session that is in use by CPI
session (returned by a previously executed GDS Communications.
ASSIGN command). 03 04 CONVID is for a conversation that is not basic.
RETCODE(data-area) 03 0C The command was issued on a conversation
specifies the 6-byte application data area into which that is not sync-level 2.
return code information is to be moved. 03 24 A state error occurred.
04 CONVID is for a session that is not allocated
to task, or that is a relay link.

Chapter 1. Commands 113

GDS ISSUE SIGNAL

Function
Request change of direction from sending transaction APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS ISSUE SIGNAL──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"

└─STATE(cvda)─┘

GDS ISSUE SIGNAL requests a change of direction. STATE(cvda)

gets the state of the current conversation. The cvda
The return code is given in RETCODE (see Table 11). For values returned by CICS are:
a list of return code values, see the CICS/ESA Distributed
Transaction Programming Guide. EXEC CICS conditions are ALLOCATED
never raised on GDS commands. CONFFREE
CONFRECEIVE
CONFSEND
GDS ISSUE SIGNAL options FREE
PENDFREE
In general, the arguments can be replaced by absolute or
PENDRECEIVE
relocatable assembler-language expressions.
RECEIVE
CONVDATA(data-area) ROLLBACK
specifies the 24-byte application data area into which SEND
conversation-related information is to be moved. A SYNCFREE
description of the format of the data area is given in the SYNCRECEIVE
discussion of CONVDATA fields in the CICS/ESA SYNCSEND
Distributed Transaction Programming Guide.
Table 11. GDS ISSUE SIGNAL return codes
CONVID(name)
RETCODE Description
identifies the conversation to which the command
(hexadecimal)
relates. The 4-character name identifies either the token
returned by a previously executed GDS ALLOCATE 03 00 CONVID is for a session that is not APPC.
command, or the token representing the principal 03 00 CONVID is for a session that is in use by CPI
session (returned by a previously executed GDS Communications.
ASSIGN command). 03 04 CONVID is for a conversation that is not basic.
RETCODE(data-area) 03 08 A state check has occurred.
specifies the 6-byte application data area into which 04 CONVID is for a session that is not allocated
return code information is to be moved. to task, or that is a relay link.

114 CICS/ESA Application Programming Reference

GDS RECEIVE

Function
Receive data on an APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS RECEIVE──CONVID(name)──┬─INTO(data-area)──┬──FLENGTH(data-area)──┬────────────────────────┬────────
└─SET(pointer-ref)─┘ └─MAXFLENGTH(data-value)─┘
──┬─BUFFER─┬──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"
└─LLID───┘ └─STATE(cvda)─┘

GDS RECEIVE receives data and indicators from a partner to the other end of the current conversation. The length
transaction. of this area must not be less than the value specified in
the MAXFLENGTH option.
The return code is given in RETCODE (see Table 12 on
page 116). For a list of return code values, see the LLID
CICS/ESA Distributed Transaction Programming Guide. specifies that the delimiter to be used by CICS to
EXEC CICS conditions are never raised on GDS commands. terminate the passing of data to the application program
is the end of a GDS structured field, if this occurs before
the MAXFLENGTH limit is reached.
GDS RECEIVE options
MAXFLENGTH(data-value)
In general, the arguments can be replaced by absolute or specifies, as a fullword binary value, either the length of
relocatable assembler-language expressions. the target data area specified in the INTO option, or the
maximum length of data to be addressed by the pointer
BUFFER
reference specified in the SET option. The length must
specifies that the length of the data passed to the
not exceed 32 767 bytes. CICS does not receive more
application program in response to the RECEIVE
data than the MAXFLENGTH value allows.
command is to be restricted only by the length specified
in the MAXFLENGTH option, and is not to be affected RETCODE(data-area)
by GDS structured field boundaries. Control is returned specifies the 6-byte application data area into which
to the application program when this length has been return code information is to be moved.
received, or when a synchronization request,
change-direction, or end-bracket is received. SET(pointer-ref)
specifies the pointer reference to be set to the address
CONVDATA(data-area) of data received from the application program connected
specifies the 24-byte application data area into which to the other end of the current conversation. The pointer
conversation-related information is to be moved. A reference, unless changed by other commands or
description of the format of the data area is given in the statements, is valid until the next RECEIVE (GDS or
discussion of CONVDATA fields in the CICS/ESA APPC) command, or the end of the task.
Distributed Transaction Programming Guide.
If DATALOCATION(ANY) is associated with the
CONVID(name) application program, the address of the data can be
identifies the conversation to which the command above or below the 16MB line.
relates. The 4-character name identifies either the token If DATALOCATION(BELOW) is associated with the
returned by a previously executed GDS ALLOCATE application program, and the data resides above the
command, or the token representing the principal 16MB line, the data is copied below the 16MB line, and
session (returned by a previously executed GDS the address of this copy is returned.
ASSIGN command).
If TASKDATAKEY(USER) is specified for the running
FLENGTH(data-area) task, and storage protection is active, the data returned
specifies a fullword binary data area that is set to the is in a user-key. If TASKDATAKEY(CICS) is specified
length of the data made available to the application and storage protection is active, the data returned is in a
program. CICS-key.
INTO(data-area)
specifies the application target data area into which data
is to be received from the application program connected

Chapter 1. Commands 115

GDS RECEIVE

STATE(cvda)
gets the state of the current conversation. The cvda
values returned by CICS are:

ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

Table 12. GDS RECEIVE return codes

RETCODE Description
(hexadecimal)
03 00 CONVID is for a session that is not APPC.
03 00 CONVID is for a session that is in use by CPI
Communications.
03 04 CONVID is for a conversation that is not basic.
03 08 A state check occurred.
04 CONVID is for a session that is not allocated
to the task, or that is a relay link.
05 00 00 00 MAXFLENGTH is outside the range 0 through
7F FF 32 767.

116 CICS/ESA Application Programming Reference

GDS SEND

Function
Send data on an APPC basic conversation (assembler-language and C programs only).

Command syntax

──GDS SEND──CONVID(name)──┬──────────────────────────────────────┬──┬────────┬──┬─────────┬──────────────
└─FROM(data-area)──FLENGTH(data-value)─┘ ├─INVITE─┤ ├─CONFIRM─┤
└─LAST───┘ └─WAIT────┘
──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"
└─STATE(cvda)─┘

GDS SEND sends data. FROM(data-area)

specifies the data that is to be sent.
The return code is given in RETCODE (see Table 13 on
page 118). For a list of return code values, see the INVITE
CICS/ESA Distributed Transaction Programming Guide. allows an application program to add a change-direction
EXEC CICS conditions are never raised on GDS commands. indicator to data already sent to a process in a
connected APPC system. Control data is not
transmitted by CICS until the subsequent execution of a
GDS SEND options WAIT or a SYNCPOINT command, unless CONFIRM or
WAIT is also coded on the GDS SEND INVITE
In general, the arguments can be replaced by absolute or
command.
relocatable assembler-language expressions.
LAST
CONFIRM
allows an application program to add CEB to data
allows an application working at synchronization level 1
already sent to a process in a connected APPC system.
or 2 to synchronize its processing with that of a process
CEB is not transmitted by CICS until the subsequent
in a remote system. The actions taken to synchronize
execution of a WAIT or a SYNCPOINT command,
processing are defined by the application programs
unless CONFIRM or WAIT is also coded on the GDS
involved. The CONFIRM option causes RQD2 to be
SEND LAST command. Note that if one of these
added to the data already sent, and forces a WAIT. On
commands fails because of a conversation-related error,
receipt of the indicator, the remote process takes the
the conversation remains in bracket. In such a case, the
agreed actions and then sends a response. When the
application program should execute a GDS RECEIVE
WAIT completes, CDBERR is set to X'00' if the
command. However, GDS SEND LAST WAIT (with no
appropriate response has been received.
data) always causes the conversation to be deallocated.
CONVDATA(data-area)
RETCODE(data-area)
specifies the 24-byte application data area into which
specifies the 6-byte application data area into which
conversation-related information is to be moved. A
return code information is to be moved.
description of the format of the data area is given in the
discussion of CONVDATA fields in the CICS/ESA
Distributed Transaction Programming Guide.

CONVID(name)
identifies the conversation to which the command
relates. The 4-character name identifies either the token
returned by a previously executed GDS ALLOCATE
command, or the token representing the principal
session (returned by a previously executed GDS
ASSIGN command).

FLENGTH(data-value)
specifies the length (as a fullword binary value in the
range 1–32 767) of the data specified in the FROM
option.

Chapter 1. Commands 117

GDS SEND

STATE(cvda)
gets the state of the current conversation. The cvda
values returned by CICS are:

ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

WAIT
ensures that all data and indicators so far sent on a
conversation are erased from the partner transaction.
If the WAIT option is not used, data from successive
SEND commands is accumulated by CICS, together with
any indicators, in an internal buffer. If the buffer
becomes full, most of the accumulated data is
transmitted to the remote system, but the accumulated
indicators are not. Transmission of the accumulated
data plus the indicators is forced by the WAIT or
CONFIRM options of the GDS SEND command, or by a
GDS WAIT command.

Table 13. GDS SEND return codes

RETCODE Description
(hexadecimal)
03 00 CONVID is for a session that is not APPC.
03 00 CONVID is for a session that is in use by CPI
Communications.
03 04 CONVID is for a conversation that is not basic.
03 08 A state check has occurred.
03 14 The CONFIRM option has been used on a
sync level 0 conversation.
03 10 LL error (incorrect or incomplete).
04 CONVID is for a session that is not allocated
to the task, or that is a relay link.
05 00 00 00 The FLENGTH value is outside the range 0
7F FF through 32 767.

118 CICS/ESA Application Programming Reference

GDS WAIT

Function
Ensure accumulated data transmitted on an APPC conversation (assembler-language and C programs only).

Command syntax

──GDS WAIT──CONVID(name)──CONVDATA(data-area)──RETCODE(data-area)──┬─────────────┬──"
└─STATE(cvda)─┘

GDS WAIT ensures that the accumulated data has been STATE(cvda)
sent. gets the state of the current conversation. The cvda
values returned by CICS are:
The return code is given in RETCODE (see Table 14). For
a list of return code values, see the CICS/ESA Distributed ALLOCATED
Transaction Programming Guide. EXEC CICS conditions are CONFFREE
never raised on GDS commands. CONFRECEIVE
CONFSEND
FREE
GDS WAIT options PENDFREE
PENDRECEIVE
In general, the arguments can be replaced by absolute or
RECEIVE
relocatable assembler-language expressions.
ROLLBACK
CONVDATA(data-area) SEND
specifies the 24-byte application data area into which SYNCFREE
conversation-related information is to be moved. A SYNCRECEIVE
description of the format of the data area is given in the SYNCSEND
discussion of CONVDATA fields in the CICS/ESA
Distributed Transaction Programming Guide. Table 14. GDS WAIT return codes
RETCODE Description
CONVID(name)
(hexadecimal)
identifies the conversation to which the command
relates. The 4-character name identifies either the token 03 00 CONVID is for a session that is not APPC.
returned by a previously executed GDS ALLOCATE 03 00 CONVID is for a session that is in use by CPI
command, or the token representing the principal Communications.
session (returned by a previously executed GDS 03 04 CONVID is for a conversation that is not basic.
ASSIGN command).
03 08 A state check has occurred.
RETCODE(data-area) 04 CONVID is for a session that is not allocated
specifies the 6-byte application data area into which to task, or that is a relay link.
return code information is to be moved.

Chapter 1. Commands 119

GETMAIN

Function
Get main storage.

Command syntax

──GETMAIN──SET(ptr-ref)──┬─FLENGTH(data-value)──┬───────┬─┬──┬─────────────────────┬──┬────────┬─────────
│ └─BELOW─┘ │ └─INITIMG(data-value)─┘ └─SHARED─┘
└─LENGTH(data-value)─────────────┘
──┬───────────┬──┬─────────────┬──"
└─NOSUSPEND─┘ ├─USERDATAKEY─┤
└─CICSDATAKEY─┘
Conditions:
LENGERR, NOSTG

| Dynamic transaction routing

| Using GETMAIN with SHARED could create inter-transaction affinities that adversely affect the use of dynamic transaction
| routing. See the CICS/ESA Application Programming Guide for more information about transaction affinities.

GETMAIN gets a main storage area of the size indicated by | CICS determines whether to obtain the requested storage
the FLENGTH option. (You can also use the LENGTH | above or below the 16MB line, from one of the CICS- or
option, but this is supported for compatibility purposes and | user-key DSAs, or from one of the shared DSAs, according
| you are strongly recommended to use FLENGTH.) The | to the following options:
| address of the area is returned in the pointer reference
The FLENGTH option with BELOW also specified
| supplied in the SET option.
The FLENGTH option alone, in conjunction with the
addressing mode of the requesting program
CICS always allocates on double-word boundaries and
The LENGTH option
rounds the requested length up to the nearest double-word
| The SHARED option.
multiple. Because there is no default initialization, you must
use the INITIMG option if you require the storage to be
The above- or below-the-line allocation is summarized in the
initialized to a specific bit configuration.
following table:
| CICS allocates storage from one of six different dynamic
| storage areas (DSAs): Options Address mode
24-bit 31-bit
The CICS dynamic storage area (CDSA), below the
16MB line FLENGTH BELOW A DSA A DSA

The user dynamic storage area (UDSA), below the FLENGTH alone A DSA An EDSA
16MB line LENGTH A DSA A DSA
| The shared dynamic storage area (SDSA), below the
| 16MB line CICS decides whether to allocate storage from a CICS-key
or user-key DSA, or from a shared DSA, according to the
The extended CICS dynamic storage area (ECDSA),
following options:
above the 16MB line
The USERDATAKEY option on the GETMAIN command.
The extended user dynamic storage area (EUDSA),
The CICSDATAKEY option on the GETMAIN command.
above the 16MB line
The TASKDATAKEY option on the transaction resource
| The extended shared dynamic storage area (ESDSA), definition under which the requesting program is running
| above the 16MB line if the USERDATAKEY or CICSDATAKEY option is
| Note: There are two other dynamic storage areas—the omitted.
| read-only DSA (RDSA) and the extended read-only DSA | The SHARED option on the GETMAIN command.
| (ERDSA)—but you cannot GETMAIN storage from these
The data-key option on the GETMAIN command overrides
| DSAs.
the TASKDATAKEY option on the transaction resource

120 CICS/ESA Application Programming Reference

GETMAIN

| definition. The effect of the data-key options, without the Specifying CICSDATAKEY ensures that the requesting
| SHARED option, is summarized in the following table: program obtains CICS-key storage from a CICS DSA, even if
TASKDATAKEY(USER) is specified on the transaction
| Without SHARED option resource definition.
No data-key USERDATAKEY CICSDATAKEY
option specified specified GETMAIN options
Determined by User-key storage CICS-key storage
TASKDATAKEY (from UDSA or (from CDSA or BELOW
on transaction EUDSA) ECDSA) specifies that storage is to be obtained below the 16MB
| definition line, that is, from the CICS DSA.

CICSDATAKEY
| The effect of the SHARED option is summarized in the specifies that CICS is to allocate storage from one of the
| following table: CICS-key DSAs (the CDSA or ECDSA), overriding the
TASKDATAKEY option specified on the transaction
| With SHARED option resource definition. If you do not specify the data key,
| No data-key USERDATAKEY CICSDATAKEY CICS determines the type of storage (CICS-key or
| option specified specified user-key) according to the TASKDATAKEY option on the
| Determined by User-key storage CICS-key storage transaction resource definition.
| TASKDATAKEY (from SDSA or (from CDSA or
FLENGTH(data-value)
| on transaction ESDSA) ECDSA)
| definition
specifies the number of bytes of storage required, in
fullword binary format.
The storage that a task gets is available until it is released | The maximum length that you can specify is the value of
with a FREEMAIN command. For an area obtained without | the corresponding DSA limit parameter, either DSALIMIT
the SHARED option, only the task that acquired the storage | or EDSALIMIT. These are the system initialization
may release it, and at task end CICS automatically releases | parameters that define the overall storage limit within
| such storage not already released. Note that any storage | which CICS can allocate and manage the individual
| acquired with the SHARED option is accessible by all tasks, | DSAs.
| including those that are running with transaction isolation. | If the length requested is bigger than the DSALIMIT or
| EDSALIMIT value, the LENGERR condition occurs. If it
A SHARED area, on the other hand, is not released at task
| is not bigger than these limits, but is more than is
end and remains until explicitly freed; any task may issue the
| available, NOSTG occurs.
FREEMAIN. This means that you can use SHARED storage
in task-to-task communication. INITIMG(data-value)
specifies an optional 1-byte initialization value. If you
You cannot, however, use the storage obtained as a TIOA specify INITIMG, CICS sets every byte of the acquired
for subsequent terminal operations, because this could cause storage to the bit string you provide. Otherwise, CICS
storage violations. does not initialize the storage. In COBOL programs
only, you must use a data area rather than a data value
The following COBOL example shows how to get a
to define the initialization bit string.
1024-byte area from user-key storage below the 16MB line
(assuming that TASKDATAKEY(USER) is specified on the LENGTH(data-value)
transaction resource definition), and initialize it to spaces: specifies the number of bytes (unsigned halfword binary
EXEC CICS GETMAIN SET(PTR) value) of storage required. LENGTH implies storage
FLENGTH(1O24) from below the 16MB line and has an upper limit of
BELOW 65 520 bytes. If you want storage above the 16MB line
INITIMG(BLANK) or a larger area, use FLENGTH.
You must define BLANK in your program as the character If LENGTH is equal to zero, LENGERR occurs. If it is
representing a space. greater than the amount of storage available, NOSTG
occurs.
The following COBOL example shows how to get a
| Note: FLENGTH, with or without BELOW, is the
2048-byte area from CICS-key storage above the 16MB line
| recommended option: the LENGTH option is supported
(regardless of the TASKDATAKEY option specified on the
| for compatibility purposes for those programs written to
transaction resource definition), and initialize it to spaces:
| run under earlier releases of CICS.
EXEC CICS GETMAIN SET(PTR)
FLENGTH(2O48) NOSUSPEND
INITIMG(BLANK) prevents CICS from suspending the task if no storage is
CICSDATAKEY available, and causes it to issue the NOSTG condition
instead.

Chapter 1. Commands 121

GETMAIN

SET(ptr-ref) GETMAIN conditions

sets the pointer reference to the address of the acquired
main storage. The pointer is set to the first byte of the LENGERR
storage area. occurs in any one of the following situations:

SHARED The FLENGTH value is less than 1 or greater than

prevents the automatic release of storage obtained by a the length of the target storage area from which the
GETMAIN command at the end of the task that request is to be satisfied (RESP2=1). See the
requested it. This enables task-to-task communication. discussion about DSAs on page 120.
An area obtained with SHARED is not released until a The LENGTH value is zero.
corresponding FREEMAIN is issued, whether by the
requesting task or some other task. Default action: terminate the task abnormally.
Be aware that if a task abends, any shared storage NOSTG
acquired is not automatically released. occurs when the storage requested is more than is
currently available in the target DSA (RESP2=2). See
USERDATAKEY
the discussion about DSAs on page 120.
specifies that CICS is to allocate storage from one of the
| user-key DSAs (the UDSA, SDSA, EUDSA, or ESDSA), Default action: suspend the task until enough main
| overriding the TASKDATAKEY option specified on the storage is available to complete the request. However,
transaction resource definition. If you do not specify the the NOSUSPEND option overrides this default; it causes
data key, CICS determines the type of storage CICS to return control to the task immediately, without
(CICS-key or user-key) according to the TASKDATAKEY the requested storage.
option on the transaction resource definition.

122 CICS/ESA Application Programming Reference

HANDLE ABEND

Function
Handle an abnormal termination exit.

Command syntax

┌─CANCEL────────┐
──HANDLE ABEND──┼───────────────┼──"
├─PROGRAM(name)─┤
├─LABEL(label)──┤
└─RESET─────────┘
Conditions:
NOTAUTH, PGMIDERR (PROGRAM only)

HANDLE ABEND is used to activate, cancel, or reactivate an HANDLE ABEND options

exit for abnormal termination processing. You can suspend
the command by means of the PUSH HANDLE and POP CANCEL
HANDLE commands as described in the CICS/ESA specifies that a previously established exit at the logical
Application Programming Guide. level of the application program in control is to be
canceled.
# When a task terminates abnormally, CICS searches for an
LABEL(label)
# active abend exit, starting at the logical level of the
specifies the program label to which control branches if
# application program in which the abend occurred, and
abnormal termination occurs.
# proceeding to successively higher levels. The first active
# abend exit found, if any, is given control. This option cannot be used for C or PL/I application
programs.
| The HANDLE ABEND command cannot intercept abends
| that are issued with the CANCEL option. Some internal PROGRAM(name)
| abends generated by CICS are issued with the CANCEL specifies the name of the program to which control is to
| option, for example the ASPx or APSJ abend codes. | be passed if the task is terminated abnormally. If this
| program has not already been defined, the program will
When the label specified in a HANDLE ABEND LABEL | be autoinstalled in the event of the abend condition
command receives control, the registers are set as follows: | being raised.
COBOL: Control returns to the HANDLE ABEND command The program named in this option should always
with the registers restored; COBOL GO TO terminate with an abend, except when handling abends
statement is then executed. generated as a result of application program logic.

ASM: R15 - Abend label. RESET

RO-14 - Contents at the time of last CICS specifies that an exit canceled by a HANDLE ABEND
service request. CANCEL command, or by CICS, is to be reactivated.

If LABEL is specified, the addressing mode and execution This option is usually issued by an abnormal termination
key used are those of the program that issued the HANDLE exit routine.
ABEND command.

If PROGRAM is specified, the addressing mode is defined by

HANDLE ABEND conditions
the way the program is link-edited and the execution key is NOTAUTH
specified by the EXECKEY option on the program’s resource occurs when a resource security check has failed on
definition. PROGRAM(name).

# If a COMMAREA has been established, it will be passed to Default action: terminate the task abnormally.
# the specified PROGRAM.

The following example shows how to establish a program as

an exit:
EXEC CICS HANDLE ABEND
PROGRAM('EXITPGM')

Chapter 1. Commands 123

HANDLE ABEND

PGMIDERR
occurs in any of the following situations:

| The program has no entry in the PPT and

| autoinstall for programs is not active (RESP2=1)
The program is disabled (RESP2=2)
The installed program definition is for a remote
program (RESP2=9).

Default action: terminate the task abnormally.

124 CICS/ESA Application Programming Reference

HANDLE AID

Function
Handle attention identifiers (AIDs).

Command syntax

┌──
─────────────────────────┐
──HANDLE AID───*┬───────────────────────┬┴──"
├─ANYKEY──┬─────────┬───┤
│ └─(label)─┘ │
├─CLEAR──┬─────────┬────┤
│ └─(label)─┘ │
├─CLRPARTN──┬─────────┬─┤
│ └─(label)─┘ │
├─ENTER──┬─────────┬────┤
│ └─(label)─┘ │
├─LIGHTPEN──┬─────────┬─┤
│ └─(label)─┘ │
├─OPERID──┬─────────┬───┤
│ └─(label)─┘ │
├─PA1-PA3──┬─────────┬──┤
│ └─(label)─┘ │
├─PF1-PF24──┬─────────┬─┤
│ └─(label)─┘ │
└─TRIGGER──┬─────────┬──┘
└─(label)─┘
Conditions:
INVREQ

HANDLE AID is used to specify the label to which control is OPERID (for the operator identification card reader, the
to be passed when an AID is received from a display device. magnetic slot reader (MSR), or the extended MSR
Control is passed after the input command is completed; that (MSRE)
is, after any data received in addition to the AID has been
PA1, PA2, or PA3 (any of the program access keys)
passed to the application program.
PF1 through PF24 (any of the program function keys)
To cause an AID to be ignored, issue a HANDLE AID
TRIGGER (for a trigger field attention).
command that specifies the associated option without a
label. This deactivates the effect of that option in any The following example shows a HANDLE AID command that
previously-issued HANDLE AID command. | specifies one label for the PA1 key; and a second label for
| CLEAR, PA2, PA3, and all the PF keys except PF10. If a
| If no HANDLE AIDs are in effect, that is none have been | PF10 AID is received or ENTER is pressed, control returns
| issued or all have been canceled, control returns to the to the application program at the instruction immediately
| application program at the instruction immediately following following the input command.
| the input command. Look in EIBAID to determine which key EXEC CICS HANDLE AID PA1(LAB1)
| was pressed. ANYKEY(LAB2) PF1O
No more than 16 options are allowed in the same command. If a task is initiated from a terminal by means of an AID, the
first RECEIVE command in the task does not read from the
The C language does not support HANDLE AID.
terminal but copies only the input buffer (even if the length of
The options that can be specified are: the data is zero) so that control may be passed by means of
a HANDLE AID command for that AID.
ANYKEY (any PA key, any PF key, or the CLEAR key,
but not ENTER) For the standard attention identifier list (DFHAID), and the
CLEAR (for the key of that name) standard attribute and printer control character list
(DFHBMSCA), see Appendix J, “BMS-related constants” on
CLRPARTN (for the key of that name) page 375.
ENTER (for the key of that name)
LIGHTPEN (for a light-pen attention)

Chapter 1. Commands 125

HANDLE AID

The execution key that the label receives control in, is the
execution key that the program was running in when the
HANDLE AID command was issued.

| A print key specified by the system PRINT initialization

| parameter takes precedence over a HANDLE AID command.

HANDLE AID condition

INVREQ
| occurs if the command was issued by a distributed
| program link server application (RESP2=200).
| Default action: terminate the task abnormally.

126 CICS/ESA Application Programming Reference

HANDLE CONDITION

Function
Handle conditions.

Command syntax

┌──
────────────────────────┐
──HANDLE CONDITION───*─condition──┬─────────┬─┴──"
└─(label)─┘

You use HANDLE CONDITION to specify the label to which Scope

control is to be passed if a condition occurs. You must
include the name of the condition and, optionally, a label to The HANDLE CONDITION command for a given condition
which control is to be passed if the condition occurs. You applies only to the program in which it is specified. The
must ensure that the HANDLE CONDITION command is HANDLE CONDITION command:
executed before the command that may give rise to the Remains active while the program is being executed, or
associated condition. until:
You cannot include more than sixteen conditions in the same – An IGNORE CONDITION command for the same
command; the conditions should be separated by at least condition is encountered, in which case the
one space. You must specify additional conditions in further HANDLE CONDITION command is overridden
HANDLE CONDITION commands. – Another HANDLE CONDITION command for the
same condition is encountered, in which case the
| If a condition occurs that is not specified in a HANDLE
new command overrides the previous one.
| CONDITION or IGNORE CONDITION command, the default
| action is taken. If, however, the default action for a condition # – A LINK command is executed to call another CICS
| not specified in a HANDLE CONDITION or IGNORE # program. The HANDLE CONDITION options are
| CONDITION command terminates the task abnormally, and # not inherited by the linked-to program.
| the condition ERROR has been specified, the action for Is temporarily deactivated by the NOHANDLE or RESP
| ERROR is taken. option on a command.
The following example shows you how to handle conditions,
such as DUPREC, LENGERR, and so on, that can occur Language considerations
when you use a WRITE command to add a record to a data
set. | In an assembler-language application program, if a HANDLE
| CONDITION and the command that causes the condition are
Suppose that you want DUPREC to be handled as a special | at the same logical level, the registers are restored to their
case; that you want standard system action (that is, to | values in the application program at the point where the
terminate the task abnormally) to be taken for LENGERR; | command that caused the condition was issued. If, however,
and that you want all other conditions to be handled by the | the command that causes a condition occurs at a lower
error routine ERRHANDL. You would code: | logical level, the registers are restored to their current values
EXEC CICS HANDLE CONDITION | saved in DFHEISTG at the HANDLE CONDITION level. On
ERROR(ERRHANDL) MVS/ESA, the addressing mode is set to that in effect at the
DUPREC(DUPRTN) LENGERR point where the HANDLE CONDITION command is issued.

The execution key that the label receives control in, is the In a PL/I application program, a branch to a label in an
execution key that the program was running in when the inactive procedure or in an inactive begin block, caused by a
HANDLE CONDITION command was issued. condition, produces unpredictable results.

The C language does not support HANDLE CONDITION.

Chapter 1. Commands 127

HANDLE CONDITION

HANDLE CONDITION option

condition(label)
specifies the name of the condition; “label” specifies the
location within the program to be branched to if the
condition occurs.
If you omit “label”, any HANDLE CONDITION command
for the condition is deactivated, and the default action is
| taken if the condition occurs. This is independent of the
| setting of the generalized ERROR condition.

For more information about the conditions, see Appendix A,

“EXEC interface block” on page 343.

128 CICS/ESA Application Programming Reference

IGNORE CONDITION

Function
Ignore conditions.

Command syntax

┌──
───────────┐
──IGNORE CONDITION───*─condition─┴──"

For more information about the conditions, see Appendix A,

“EXEC interface block” on page 343.

You use IGNORE CONDITION to specify that no action is to

be taken if a condition occurs (that is, control returns to the
instruction following the command that has failed to execute,
and the EIB is set). Execution of a command could result in
several conditions being raised. CICS checks these in a
predetermined order and only the first one that is not ignored
(by your IGNORE CONDITION command) is passed to your
application program.

The IGNORE CONDITION command for a given condition

applies only to the program in which it is specified, and it
remains active while the program is being executed, or until
a HANDLE CONDITION command for the same condition is
encountered, in which case the IGNORE CONDITION
command is overridden.

You cannot code more than sixteen conditions in the same

command; the conditions should be separated by at least
one space. You must specify additional conditions in further
IGNORE CONDITION commands.

The C language does not support IGNORE CONDITION.

IGNORE CONDITION option

condition
specifies the name of the condition to be ignored.

Chapter 1. Commands 129

ISSUE ABEND

Function
Abend the mapped conversation with an APPC partner.

Command syntax

──ISSUE ABEND──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC, TERMERR

ISSUE ABEND abnormally ends the conversation. The ISSUE ABEND conditions
partner transaction sees the TERMERR condition.
INVREQ
occurs in any of the following situations:
ISSUE ABEND options
ISSUE ABEND is used on any conversation other
CONVID(name) than an EXEC CICS APPC mapped conversation.
identifies the conversation to be abended. The
A distributed program link server application
| 4-character name identifies either the symbolic identifier
specified the function-shipping session (its principal
returned by a previously executed ALLOCATE command
facility) on the CONVID option (RESP2=200).
| in EIBRSRCE in the EIB, or the symbolic identifier
representing the principal session (returned by a Default action: terminate the task abnormally.
previously executed ASSIGN command).
NOTALLOC
For compatibility with earlier releases, SESSION is occurs if the CONVID value relates to a conversation
accepted as a synonym for CONVID. New programs that is not owned by the application.
should use CONVID.
Default action: terminate the task abnormally.
If this option is omitted, the principal facility is assumed.
TERMERR
STATE(cvda) occurs for a session-related error. Any action on that
gets the state of the current conversation. The cvda conversation other than a FREE command causes an
values returned by CICS are: ATCV abend.
ALLOCATED A CANCEL TASK request by a user node error program
CONFFREE (NEP) may cause this condition if the task has an
CONFRECEIVE outstanding terminal control request active when the
CONFSEND node abnormal condition program handles the session
FREE error.
PENDFREE
Default action: terminate the task abnormally with abend
PENDRECEIVE
code ATNI.
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

130 CICS/ESA Application Programming Reference

ISSUE ABORT

Function
End processing of a data set abnormally.

Command syntax

──ISSUE ABORT──┬────────────────────────────────────────────────┬────────────────────────────────────────
├─DESTID(data-value)──┬────────────────────────┬─┤
│ └─DESTIDLENG(data-value)─┘ │
│ ┌─CONSOLE──┐ │
└─SUBADDR(data-value)──┼──────────┼──────────────┘
├─PRINT────┤
├─CARD─────┤
├─WPMEDIA1─┤
├─WPMEDIA2─┤
├─WPMEDIA3─┤
└─WPMEDIA4─┘
──┬────────────────────────────────────────────────┬──"
└─VOLUME(data-value)──┬────────────────────────┬─┘
└─VOLUMELENG(data-value)─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE ABORT ends communication with a data set in an SUBADDR(data-value)

outboard controller, or the selected medium, abnormally. specifies the medium subaddress as a halfword binary
The data set specified in the DESTID option is deselected value (in the range 0 through 15) which allows media of
abnormally. The options CONSOLE, PRINT, CARD, and the same type, for example, “printer 1” or “printer 2”, to
WPMEDIA1–4 are alternatives to DESTID and be defined. Value 15 means a medium of any type.
DESTIDLENG. The default is zero.

VOLUME(data-value)
ISSUE ABORT options specifies the name (1–6 characters) of a diskette in an
outboard destination that contains the data set specified
CARD
in the DESTID option.
specifies that the output medium is a card reader or card
punch device. This option is not valid with DESTID and VOLUMELENG(data-value)
DESTIDLENG. specifies the length (halfword binary value) of the name
specified in the VOLUME option.
CONSOLE
specifies that the output medium is that provided for WPMEDIA1 through WPMEDIA4
messages to the operator. This option is not valid with specifies that, for each specific LUTYPE4 device, a
DESTID and DESTIDLENG. This refers to a word-processing medium is defined to relate to a specific
programmable subsystem such as the IBM 3790 data input/output device.
communication system. It does not refer to a CICS or
system console.
ISSUE ABORT conditions
DESTID(data-value)
FUNCERR
specifies the name (1–8 characters) of the data set in
occurs if there is an error during execution of the
the outboard destination.
command. Destination selection is unaffected and other
DESTIDLENG(data-value) commands for the same destination may be successful.
specifies the length (halfword binary value) of the name
Default action: terminate the task abnormally.
specified in the DESTID option.

PRINT
specifies that the output medium is a printer.

Chapter 1. Commands 131

ISSUE ABORT

INVREQ
occurs if a distributed program link server application
specified the function-shipping session (its principal
facility) on the CONVID option (RESP2=200).
Default action: terminate the task abnormally.

SELNERR
occurs if there is an error during destination selection.
The destination is not selected and other commands for
the same destination are unlikely to be successful.
Default action: terminate the task abnormally.

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

132 CICS/ESA Application Programming Reference

ISSUE ADD
ISSUE ADD

INVREQ
occurs if a distributed program link server application
specified the function-shipping session (its principal
facility) on the CONVID option (RESP2=200).

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

134 CICS/ESA Application Programming Reference

ISSUE CONFIRMATION

Function
Issue a positive response to a SEND CONFIRM on an APPC mapped conversation.

Command syntax

──ISSUE CONFIRMATION──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC, SIGNAL, TERMERR

ISSUE CONFIRMATION allows an application program to – Sync level 0

respond positively when the CONFIRM option has been – Not APPC mapped.
specified on a SEND command executed by a partner
A distributed program link server application
transaction.
specified the function-shipping session on the
CONVID option (RESP2=200).
ISSUE CONFIRMATION options Default action: terminate the task abnormally.
CONVID(name)
NOTALLOC
identifies the conversation in which to send the
occurs if the facility specified in the command is not
response. The 4-character name identifies either the
owned by the application.
token returned by a previously executed ALLOCATE
command in EIBRSRCE in the EIB, or the token Default action: terminate the task abnormally.
representing the principal session (returned by a
previously executed ASSIGN command).
For compatibility with earlier releases, SESSION is
accepted as a synonym for CONVID. New programs
should use CONVID.
If this option is omitted, the principal facility is assumed.

STATE(cvda)
gets the state of the current conversation. The cvda
values returned by CICS are:

ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

ISSUE CONFIRMATION conditions

INVREQ
occurs in any of the following situations:

ISSUE CONFIRMATION is used on a conversation

that is either of the following:

Chapter 1. Commands 135

ISSUE CONFIRMATION

SIGNAL
occurs when an inbound SIGNAL data-flow control
command is received from a partner transaction.
EIBSIG is always set when an inbound signal is
received.
Default action: ignore the condition.

TERMERR
occurs for a session-related error. Any action on that
conversation other than a FREE causes an ATCV
abend.
A CANCEL TASK request by a user node error program
(NEP) may cause this condition if the task has an
outstanding terminal control request active when the
node abnormal condition program handles the session
error.
Default action: terminate the task abnormally with abend
code ATNI.

136 CICS/ESA Application Programming Reference

ISSUE COPY (3270 display)

Function
Copy data from 3270 information display system (BTAM).

Command syntax

──ISSUE COPY──TERMID(name)──┬─────────────────────┬──┬──────┬──"
└─CTLCHAR(data-value)─┘ └─WAIT─┘
Conditions:
# NOTALLOC, TERMIDERR

ISSUE COPY copies the format and data contained in the ISSUE COPY (3270 display) condition
buffer of a specified terminal into the buffer of the terminal
that started the transaction. Both terminals must be attached # NOTALLOC
to the same remote control unit. # occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.
ISSUE COPY (3270 display) options
TERMIDERR
CTLCHAR(data-value)
occurs if the specified terminal identifier cannot be found
specifies a 1-byte copy control character (CCC) that
in the terminal control table (TCT).
defines the copy function. A COBOL user must specify
a data area containing this character. If the option is Default action: terminate the task abnormally.
omitted, the contents of the entire buffer (including nulls)
are copied.

TERMID(name)
specifies the name (1–4 characters) of the terminal
whose buffer is to be copied. The terminal must have
been defined in the TCT.

WAIT
specifies that processing of the command must be
completed before any subsequent processing is
attempted.
If the WAIT option is not specified, control is returned to
the application program when processing of the
command has started. A subsequent input or output
request (terminal control, BMS, or batch data
interchange) to the terminal associated with the task
causes the application program to wait until the previous
request has been completed.

Chapter 1. Commands 137

ISSUE COPY (3270 logical)

Function
Copy data from 3270 logical unit.

Command syntax

──ISSUE COPY──TERMID(name)──┬─────────────────────┬──┬──────┬──"
└─CTLCHAR(data-value)─┘ └─WAIT─┘
Conditions:
# LENGERR, NOTALLOC, TERMERR

ISSUE COPY copies the format and data contained in the TERMERR
buffer of a specified terminal into the buffer of the terminal occurs for a terminal-related error.
that started the transaction. Both terminals must be attached
A CANCEL TASK request by a user node error program
to the same remote control unit.
(NEP) may cause this condition if the task has an
outstanding terminal control request active when the
ISSUE COPY (3270 logical) options node abnormal condition program handles the session
error.
CTLCHAR(data-value)
specifies a 1-byte copy control character (CCC) that Default action: terminate the task abnormally with abend
defines the copy function. A COBOL user must specify code ATNI.
a data area containing this character. If the option is
omitted, the contents of the entire buffer (including nulls)
are copied.

TERMID(name)
specifies the name (1–4 characters) of the terminal
whose buffer is to be copied. The terminal must have
been defined in the TCT.

WAIT
specifies that processing of the command must be
completed before any subsequent processing is
attempted.
If the WAIT option is not specified, control is returned to
the application program once processing of the
command has started. A subsequent input or output
request (terminal control, BMS, or batch data
interchange) to the terminal associated with the task
causes the application program to wait until the previous
request has been completed.

ISSUE COPY (3270 logical) conditions

LENGERR
occurs if an out-of-range value is supplied.
Default action: terminate the task abnormally.

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

138 CICS/ESA Application Programming Reference

ISSUE DISCONNECT (default)

Function
Terminate a session between CICS and a logical unit or terminal.

Command syntax

──ISSUE DISCONNECT──"
Conditions:
SIGNAL, TERMERR

ISSUE DISCONNECT terminates sessions between CICS terminals only. Because of the asynchronous nature of
and the following terminals or logical units: this condition, the application program should check,
using SEND CONFIRM or SYNCPOINT, to make sure
3270-display logical unit (LUTYPE2)
any errors still outstanding have been resolved before it
3270-printer logical unit (LUTYPE3)
relinquishes control. If you wish to handle this condition,
LUTYPE4 logical unit
you must first issue a FREE command to free the
3270 SCS printer logical unit
session. If you do not do this, an INVREQ condition
System/7
occurs, plus an ATCV abend if you do not handle this
2260 or 2265 display station
condition.
3270 information display system (BTAM or TCAM)
3270 logical unit A CANCEL TASK request by a user node error program
3600 pipeline logical unit (NEP) may cause this condition if the task has an
3600(3601) logical unit outstanding terminal control request active when the
3600(3614) logical unit node abnormal condition program handles the session
3630 plant communication system error.
3650 interpreter logical unit
Default action: terminate the task abnormally with abend
3650 host conversational (3270) logical unit
code ATNI.
3650 host conversational (3653) logical unit
3650(3680) host command processor logical unit
3735 programmable buffered terminal
3740 data entry system
3767/3770 interactive logical unit
3770 batch logical unit
3790 logical units.

ISSUE DISCONNECT (default) conditions

For most terminal and logical unit types, ISSUE
DISCONNECT raises no conditions. Exceptions are:

SIGNAL
occurs only for an ISSUE DISCONNECT for LUTYPE4,
3600(3601), 3767 interactive, 3770 batch, and 3790
full-function logical units.
It occurs when an inbound SIGNAL data-flow control
command is received from a logical unit or session.
EIBSIG is always set when an inbound signal is
received.
Default action: ignore the condition.

TERMERR
occurs only for an ISSUE DISCONNECT for LUTYPE4
logical units.
It occurs for a terminal-related error, such as a session
failure. This condition applies to VTAM-connected

Chapter 1. Commands 139

ISSUE DISCONNECT (LUTYPE6.1)

Function
Disconnect an LUTYPE6.1 logical unit.

Command syntax

──ISSUE DISCONNECT──┬───────────────┬──"
└─SESSION(name)─┘
Conditions:
NOTALLOC, TERMERR

ISSUE DISCONNECT disconnects the unit, if

DISCREQ=YES is set in DEFINE TERMTYPE for RDO.

ISSUE DISCONNECT (LUTYPE6.1) option

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be disconnected. If this option is omitted, the
principal facility for the task is disconnected.

ISSUE DISCONNECT (LUTYPE6.1)

conditions
NOTALLOC
occurs if the facility specified in the command is not
owned by the application.
Default action: terminate the task abnormally.

TERMERR
occurs for a terminal-related error, such as a session
failure.
A CANCEL TASK request by a user node error program
(NEP) may cause this condition if the task has an
outstanding terminal control request active when the
node abnormal condition program handles the session
error.
Default action: terminate the task abnormally with abend
code ATNI.

140 CICS/ESA Application Programming Reference

ISSUE END

Function
End processing of a data set.

Command syntax

──ISSUE END──┬────────────────────────────────────────────────┬──────────────────────────────────────────
├─DESTID(data-value)──┬────────────────────────┬─┤
│ └─DESTIDLENG(data-value)─┘ │
│ ┌─CONSOLE──┐ │
└─SUBADDR(data-value)──┼──────────┼──────────────┘
├─PRINT────┤
├─CARD─────┤
├─WPMEDIA1─┤
├─WPMEDIA2─┤
├─WPMEDIA3─┤
└─WPMEDIA4─┘
──┬────────────────────────────────────────────────┬──"
└─VOLUME(data-value)──┬────────────────────────┬─┘
└─VOLUMELENG(data-value)─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE END ends communication with a data set in an SUBADDR(data-value)

outboard controller or with the selected medium. The data specifies the medium subaddress as a halfword binary
set specified in the DESTID option, or the selected medium, value (in the range 0–15) that allows media of the same
is deselected normally. The options CONSOLE, PRINT, type, for example, “printer 1” or “printer 2”, to be defined.
CARD, and WPMEDIA1–4 are alternatives to DESTID and Value 15 means a medium of any type. The default is
DESTIDLENG. zero.

VOLUME(data-value)
ISSUE END options specifies the name (1–6 characters) of a diskette in an
outboard destination that contains the data set specified
CARD
in the DESTID option.
specifies that the output medium is a card reader or card
punch device. This option is not valid with DESTID and VOLUMELENG(data-value)
DESTIDLENG. specifies the length (halfword binary value) of the name
specified in the VOLUME option.
CONSOLE
specifies that the output medium is that provided for WPMEDIA1 through WPMEDIA4
messages to the operator. This option is not valid with specifies that, for each specific LUTYPE4 device, a
DESTID and DESTIDLENG. This refers to a word-processing medium is defined to relate to a specific
programmable subsystem such as the IBM 3790 data input/output device.
communication system. It does not refer to a CICS or
system console.
ISSUE END conditions
DESTID(data-value)
FUNCERR
specifies the name (1–8 characters) of the data set in
occurs if there is an error during the execution of the
the outboard destination.
command. Destination selection is unaffected and other
DESTIDLENG(data-value) commands for the same destination may be successful.
specifies the length (halfword binary value) of the name
Default action: terminate the task abnormally.
specified in the DESTID option.

PRINT
specifies that the output medium is a printer.

Chapter 1. Commands 141

ISSUE END

INVREQ
occurs if a distributed program link server application
specified the function-shipping session (its principal
facility) on the CONVID option (RESP2=200).
| Default action: terminate the task abnormally.

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

142 CICS/ESA Application Programming Reference

ISSUE ENDFILE

Function
Indicate the end-of-file condition to the 3740 data entry system.

Command syntax

──ISSUE ENDFILE──┬───────────┬──"
└─ENDOUTPUT─┘
Conditions:
| INVREQ, NOTALLOC

ISSUE ENDFILE indicates the end-of-file condition to the 3740.

ISSUE ENDFILE option

ENDOUTPUT
indicates the end-of-output condition as well as end of
file.

| ISSUE ENDFILE conditions

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

Chapter 1. Commands 143

ISSUE ENDOUTPUT

Function
Indicate the end-of-output condition to the 3740 data entry system.

Command syntax

──ISSUE ENDOUTPUT──┬─────────┬──"
└─ENDFILE─┘
Conditions:
| INVREQ, NOTALLOC

ISSUE ENDOUTPUT indicates the end-of-output condition to the 3740.

ISSUE ENDOUTPUT option

ENDFILE
indicates the end-of-file condition as well as end of
output.

| ISSUE ENDOUTPUT conditions

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

144 CICS/ESA Application Programming Reference

ISSUE EODS

Function
Send end-of-data-set function management header to the 3650 interpreter logical unit.

Command syntax

──ISSUE EODS──"
Conditions:
| INVREQ, NOTALLOC, TERMERR

ISSUE EODS issues the end-of-data-set management header.

ISSUE EODS conditions

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

Chapter 1. Commands 145

ISSUE ERASE

Function
Delete a record from a data set.

Command syntax

──ISSUE ERASE──DESTID(data-value)──┬────────────────────────┬────────────────────────────────────────────
└─DESTIDLENG(data-value)─┘
──VOLUME(data-value)──┬────────────────────────┬──RIDFLD(data-area)───────────────────────────────────────
└─VOLUMELENG(data-value)─┘
| ──┬─KEYLENGTH(data-value)──┬───────────────────────┬─┬──┬────────────────────┬──┬─────────┬───────────────
| │ └─KEYNUMBER(data-value)─┘ │ └─NUMREC(data-value)─┘ └─DEFRESP─┘
| └─RRN──────────────────────────────────────────────┘
──┬────────┬──"
└─NOWAIT─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE ERASE deletes a record from a keyed direct data set NUMREC(data-value)
in an outboard controller, or erases a record from a DPCX or for a relative record data set, specifies as a halfword
DXAM relative record data set. binary value the number of logical records to be deleted.
Records are replaced sequentially starting with the one
identified by the RIDFLD option.
ISSUE ERASE options
For an indexed data set, NUMREC cannot be specified,
DEFRESP because only one record is deleted.
specifies that all terminal control commands issued as a
result of the ISSUE ERASE command are to request a RIDFLD(data-area)
definite response from the outboard batch program, # specifies the record identification field. When combined
irrespective of the specification of message integrity for # with RRN this is a 4-character field.
the CICS task (by the system programmer). # For a relative record data set, the RIDFLD option
DESTID(data-value) # specifies a fullword binary integer (the relative record
specifies the name (1–8 characters) of the data set in # number of the record starting from zero); and the RRN
the outboard destination. # option is used.
For an indexed data set, the RIDFLD option specifies
DESTIDLENG(data-value)
| the key that is embedded in the data. The KEYLENGTH
specifies the length (halfword binary value) of the name
option is also required.
specified in the DESTID option.
RRN
KEYLENGTH(data-value)
specifies that the record identification field specified in
specifies the length of the key specified in the RIDFLD
the RIDFLD option contains a relative record number. If
option, as a halfword binary value.
the option is not specified, RIDFLD is assumed to
KEYNUMBER(data-value) specify a key.
specifies the number, as a halfword binary value, of the
VOLUME(data-value)
index to be used to locate the record. There can be
specifies the name (1–6 characters) of a diskette in an
eight indexes (1–8). The default is 1. This option
outboard destination that contains the data set specified
applies only to DPCX or DXAM and is mutually exclusive
in the DESTID option.
with RRN.
VOLUMELENG(data-value)
NOWAIT
specifies the length (halfword binary value) of the name
specifies that the CICS task continues processing
specified in the VOLUME option.
without waiting for the ISSUE ERASE command to
complete. If this option is not specified, the task activity
is suspended until the command is completed.

146 CICS/ESA Application Programming Reference

ISSUE ERASE

ISSUE ERASE conditions

FUNCERR
occurs if there is an error during execution of the
command. Destination selection is unaffected and other
commands for the same destination may be successful.
Default action: terminate the task abnormally.

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

Chapter 1. Commands 147

ISSUE ERASEAUP

Function
Erase all unprotected fields of a 3270 buffer.

Command syntax

──ISSUE ERASEAUP──┬──────┬──"
└─WAIT─┘
Conditions:
| INVREQ, NOTALLOC, TERMERR

ISSUE ERASEAUP erases unprotected fields by: # NOTALLOC

# occurs if the facility specified in the command is not
1. Clearing all unprotected fields to nulls (X'00')
# owned by the application.
2. Resetting modified data tags in each unprotected field to
# Default action: terminate the task abnormally.
zero
3. Positioning the cursor to the first unprotected field TERMERR
occurs for a terminal-related error.
4. Restoring the keyboard.
A CANCEL TASK request by a user node error program
You can use the ISSUE ERASEAUP command for the (NEP) may cause this condition if the task has an
following types of 3270 logical units: outstanding terminal control request active when the
node abnormal condition program handles the session
3270-display logical unit (LUTYPE2)
error.
3270-printer logical unit (LUTYPE3)
3270 information display system (BTAM or TCAM) Default action: terminate the task abnormally with abend
3270 logical unit code ATNI.
3650 host conversational (3270) logical unit
3790 (3270-display) logical unit
3790 (3270-printer) logical unit.

ISSUE ERASEAUP option

WAIT
ensures that the erase is completed before control
returns to the application program. If you omit WAIT,
control returns to the application program as soon as
ISSUE ERASEAUP starts processing.

ISSUE ERASEAUP conditions

148 CICS/ESA Application Programming Reference

ISSUE ERROR

Function
Inform APPC mapped conversation partner of error.

Command syntax

──ISSUE ERROR──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC, SIGNAL, TERMERR

ISSUE ERROR allows an application program to inform a ISSUE ERROR conditions

process in a connected APPC system that some
program-detected error has occurred. For example, a INVREQ
remote CICS application is notified by having EIBERR set, occurs in any of the following situations:
with EIBERRCD=X'0889'. The actions required to recover The command is not valid for the APPC
from the error are the responsibility of logic contained in both conversation type in use.
application programs. The application program can use this
command to respond negatively when the CONFIRM option The command is issued against a
has been specified on a SEND command executed by a CPI-Communications conversation.
process in a connected APPC system. A distributed program link server application
specified the function-shipping session on the
CONVID option (RESP2=200).
ISSUE ERROR options
Default action: terminate the task abnormally.
CONVID(name)
identifies the conversation to which the command NOTALLOC
relates. The 4-character name identifies either the token occurs if CONVID does not specify the name of a token
returned by a previously executed ALLOCATE command that relates to a conversation owned by the application.
in EIBRSRCE in the EIB, or the token representing the
Default action: terminate the task abnormally.
principal session (returned by a previously executed
ASSIGN command). SIGNAL
For compatibility with earlier releases, SESSION is occurs when an inbound SIGNAL data-flow control
accepted as a synonym for CONVID. New programs command is received from a partner transaction.
should use CONVID. EIBSIG is always set when an inbound signal is
received.
If this option is omitted, the principal facility is assumed.
Default action: ignore the condition.
STATE(cvda)
gets the state of the current conversation. The cvda TERMERR
values returned by CICS are: occurs for a session-related error. Any action on that
conversation other than a FREE command causes an
ALLOCATED ATCV abend.
CONFFREE
A CANCEL TASK request by a user node error program
CONFRECEIVE
(NEP) may cause this condition if the task has an
CONFSEND
outstanding terminal control request active when the
FREE
node abnormal condition program handles the session
PENDFREE
error.
PENDRECEIVE
RECEIVE Default action: terminate the task abnormally with abend
ROLLBACK code ATNI.
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

Chapter 1. Commands 149

ISSUE LOAD

Function
Specify the name of a program on 3650 interpreter logical unit.

Command syntax

──ISSUE LOAD──PROGRAM(name)──┬──────────┬──"
└─CONVERSE─┘
Conditions:
# NONVAL, NOSTART, NOTALLOC, TERMERR

ISSUE LOAD specifies the name of the 3650 application

program that is to be loaded.

ISSUE LOAD options

CONVERSE
specifies that the 3650 application program is able to
communicate with the host processor. If this option is
not specified, the 3650 application program cannot
communicate with the host processor.

PROGRAM(name)
specifies the name (1–8 characters) of the 3650
application program that is to be loaded.

ISSUE LOAD conditions

NONVAL
occurs if the 3650 application program name is not valid.
Default action: terminate the task abnormally.

NOSTART
occurs if the 3651 is unable to initiate the requested
3650 application program.
Default action: terminate the task abnormally.

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

TERMERR
occurs for a terminal-related error.
A CANCEL TASK request by a user node error program
(NEP) may cause this condition if the task has an
outstanding terminal control request active when the
node abnormal condition program handles the session
error.
Default action: terminate the task abnormally with abend
code ATNI.

150 CICS/ESA Application Programming Reference

ISSUE NOTE

Function
Request next record number.

Command syntax

──ISSUE NOTE──DESTID(data-value)──┬────────────────────────┬─────────────────────────────────────────────
└─DESTIDLENG(data-value)─┘
──VOLUME(data-value)──┬────────────────────────┬──RIDFLD(data-area)──RRN──"
└─VOLUMELENG(data-value)─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE NOTE requests the number of the next record. It INVREQ

finds the relative record number of the next record in an occurs if a distributed program link server application
addressed direct data set. The number is returned in the specified the function-shipping session (its principal
data area specified in the RIDFLD option. The RRN option facility) on the CONVID option (RESP2=200).
must be specified, because a relative record number is
| Default action: terminate the task abnormally.
involved.
SELNERR
occurs if there is an error during destination selection.
ISSUE NOTE options The destination is not selected and other commands for
DESTID(data-value) the same destination are unlikely to be successful.
specifies the name (1–8 characters) of the data set in Default action: terminate the task abnormally.
the outboard destination.
UNEXPIN
DESTIDLENG(data-value) occurs when some unexpected or unrecognized
specifies the length (halfword binary value) of the name information is received from the outboard controller.
specified in the DESTID option.
Default action: terminate the task abnormally.
RIDFLD(data-area)
# specifies as a 4-character field a data area the relative
record number of the next record is returned in.

RRN
specifies that the record identification field specified in
the RIDFLD option contains a relative record number.

VOLUME(data-value)
specifies the name (1–6 characters) of a diskette in an
outboard destination that contains the data set specified
in the DESTID option.

VOLUMELENG(data-value)
specifies the length (halfword binary value) of the name
specified in the VOLUME option.

ISSUE NOTE conditions

Chapter 1. Commands 151

ISSUE PASS

Function
VTAM application routing.

Command syntax

──ISSUE PASS──LUNAME(name)──┬─────────────────────────────────────┬──┬─────────────────────┬─────────────
# └─FROM(data-area)──LENGTH(data-value)─┘ ├─LOGMODE(data-value)─┤
# └─LOGONLOGMODE────────┘
──┬───────────┬──"
| └─NOQUIESCE─┘
Conditions:
# INVREQ, LENGERR, NOTALLOC

ISSUE PASS disconnects the terminal from CICS after the | specifies the name (1–8 characters) of the VTAM logon
task has terminated, and transfers it to the VTAM application # mode table entry used by VTAM to establish the new
defined in the LUNAME option. # session.
# Apar 84968
This command requires that AUTH=PASS is coded on the
TYPETERM definition of the VTAM APPL macro for the # Documentation for Apar 88279 added 04/11/96
CICS terminal-owning system that issues it, with
| DISCREQ=YES or RELREQ=YES in DEFINE TYPETERM
# LOGONLOGMODE
for any terminal where this function might be used.
# specifies that the new session is to be established with
If the LUNAME specified is the name of another CICS # the VTAM logon mode table entry in use when the
system, you can use the EXTRACT LOGONMSG command # session logged on.
to access the data referred to by this command. # Note: The logmode name saved is taken from the
# X'0D' control vector in the VTAM CINIT. This is
Because of a VTAM limitation, the maximum length of the # the logmode name known in this system.
user data is restricted to 255 bytes.
# If persistent sessions (PSDINT=nnn in the SIT) is
Note: The system initialization parameter # in use then the TYPETERM definition for any
| CLSDSTP=NOTIFY|NONOTIFY allows you to have the node # terminal to be ISSUE PASSed should use
error program (NEP) and the console notified of whether the # RECOVOPTION(NONE) because the the logon
PASS was successful or not. The NEP can be coded to # LOGMODE name is not recovered across a
reestablish a session ended by an unsuccessful PASS. For # persistent sessions restart.
programming information about how to do this, see the
section about NEP in the CICS/ESA Customization Guide. # If neither LOGMODE nor LOGONLOGMODE is
# supplied, the new session will be established
# with the default LOGMODE.
ISSUE PASS options
LUNAME(name)
FROM(data-area) specifies the name (1–8 characters) of the VTAM
specifies the data area containing the logon user data application to which the terminal is to be passed.
that is to be passed to the application named in the
LUNAME option. This option may be omitted if | NOQUIESCE
ATTACHID is specified on an LUTYPE6.1 command. | specifies that the user can choose to recover from
| certain pass failures.
LENGTH(data-value)
specifies the length, as a halfword binary value, of the
data issued.

| LOGMODE(data-value)

# Apar 88279
# Documentation for Apar 84968 added 04/11/96

152 CICS/ESA Application Programming Reference

ISSUE PASS

ISSUE PASS conditions

INVREQ
occurs if the command is not valid for the logical unit in
use.
Default action: terminate the task abnormally.

LENGERR
occurs if an out-of-range value is supplied in the
LENGTH option.
Default action: terminate the task abnormally.

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

Chapter 1. Commands 153

ISSUE PREPARE

Function
Issue the first flow of a syncpoint request on an APPC mapped conversation.

Command syntax

──ISSUE PREPARE──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC, TERMERR

ISSUE PREPARE applies only to distributed transaction ISSUE PREPARE conditions

processing over APPC links. It enables a syncpoint initiator
to prepare a syncpoint slave for syncpointing by sending only INVREQ
the first flow (prepare-to-commit) of the syncpoint exchange. occurs in any of the following situations:
Depending on the reply from the syncpoint slave, the initiator The conversation is not an APPC mapped
can proceed with the syncpoint by issuing a SYNCPOINT conversation.
command, or initiate back-out by issuing a SYNCPOINT
ROLLBACK command. The conversation state is not valid for the request.
The sync level of the conversation is not 2.
ISSUE PREPARE options A distributed program link server application
specified the function-shipping session (its principal
CONVID(name) facility) on the CONVID option (RESP2=200).
specifies the symbolic identifier (1–4 characters) of an
APPC mapped conversation. This option specifies the Default action: terminate the task abnormally.
alternate facility to be used.
NOTALLOC
If this option is omitted, the principal facility is assumed. occurs if the CONVID value in the command does not
relate to a conversation that is owned by the application.
STATE(cvda)
gets the state of the current conversation. The cvda Default action: terminate the task abnormally.
values returned by CICS are:
TERMERR
ALLOCATED occurs for a session-related error. Any action on that
CONFFREE conversation other than a FREE causes an ATCV
CONFRECEIVE abend.
CONFSEND A CANCEL TASK request by a user node error program
FREE (NEP) may cause this condition if the task has an
PENDFREE outstanding terminal control request active when the
PENDRECEIVE node abnormal condition program handles the session
RECEIVE error.
ROLLBACK
SEND Default action: terminate the task abnormally with abend
SYNCFREE code ATNI.
SYNCRECEIVE
SYNCSEND

154 CICS/ESA Application Programming Reference

ISSUE PRINT

Function
Print displayed data on first available printer.

Command syntax

──ISSUE PRINT──"
Conditions:
| INVREQ, NOTALLOC, TERMERR

ISSUE PRINT prints displayed data on the first available ISSUE PRINT conditions
printer that can respond to a print request.
| INVREQ
ISSUE PRINT can be used on a number of logical units, | occurs if a distributed program link server application
using the printers defined below: | specified the function-shipping session (its principal
| facility) on the CONVID option (RESP2=200).
For a 3270 information display system (BTAM), the
printer must be on the same control unit, have buffer | Default action: terminate the task abnormally.
capacity equal to or greater than that of the display, and
# NOTALLOC
have feature-print specified in the associated DFHTCT
# occurs if the facility specified in the command is not
TYPE=TERMINAL table.
# owned by the application.
For a 3270 logical unit or a 3650 host conversational
# Default action: terminate the task abnormally.
(3270) logical unit, the printer must be defined by the
PRINTTO or ALTPRT operands of the DFHTCT TERMERR
TYPE=TERMINAL table, by RDO, or by a printer occurs for a terminal-related error.
supplied by the autoinstall user program.
An ISSUE PRINT on a BTAM 3270 information display
For a 3270-display logical unit with the PTRADAPT system cannot raise the TERMERR condition.
feature, used with a 3274 or 3276, the printer is
A CANCEL TASK request by a user node error program
allocated by the printer authorization matrix. The
(NEP) may cause this condition if the task has an
PTRADAPT feature is enabled by coding a DFHTCT
outstanding terminal control request active when the
TYPE=TERMINAL macro with TRMTYPE=LUTYPE2 and
node abnormal condition program handles the session
FEATURE=PTRADAPT.
error.
For a 3790 (3270-display) logical unit, the printer is
Default action: terminate the task abnormally with abend
allocated by the 3790.
code ATNI.
The printer must be in service, not currently attached to
a task, and owned by the same CICS system that owns
the terminal running the transaction.

Chapter 1. Commands 155

ISSUE QUERY

Function
Interrogate a data set.

Command syntax

──ISSUE QUERY──DESTID(data-value)──┬────────────────────────┬────────────────────────────────────────────
└─DESTIDLENG(data-value)─┘
──┬────────────────────────────────────────────────┬──"
└─VOLUME(data-value)──┬────────────────────────┬─┘
└─VOLUMELENG(data-value)─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE QUERY interrogates a data set. It is used to request SELNERR

that a sequential data set in an outboard controller be occurs if there is an error during destination selection.
transmitted to the host system. The application program The destination is not selected and other commands for
should either follow this command with ISSUE RECEIVE the same destination are unlikely to be successful.
commands to get the resulting inbound data, or terminate the
Default action: terminate the task abnormally.
transaction to allow CICS to start a new transaction to
process the data. UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
ISSUE QUERY options
Default action: terminate the task abnormally.
DESTID(data-value)
specifies the name (1–8 characters) of the data set in
the outboard destination.

DESTIDLENG(data-value)
specifies the length (halfword binary value) of the name
specified in the DESTID option.

VOLUME(data-value)
specifies the name (1–8 characters) of a diskette in an
outboard destination that contains the data set specified
in the DESTID option.

VOLUMELENG(data-value)
specifies the length (halfword binary value) of the name
specified in the VOLUME option.

ISSUE QUERY conditions

156 CICS/ESA Application Programming Reference

ISSUE RECEIVE

Function
Read a record from a data set.

Command syntax

──ISSUE RECEIVE──┬─INTO(data-area)─┬──┬───────────────────┬──"
└─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘
Conditions:
DSSTAT, EOC, EODS, INVREQ, LENGERR, UNEXPIN

ISSUE RECEIVE reads a sequential data set in an outboard | If you have specified SET, you must also specify
controller. | LENGTH.

The INTO option specifies the area into which the data is to SET(ptr-ref)
be placed. The LENGTH option must specify a data area specifies the pointer reference that is to be set to the
that contains the maximum length of record that the program address location of the data read from the data set.
accepts. If the record length exceeds the specified maximum If you specify the SET option, the parameter must be a
length, the record is truncated and the LENGERR condition data area. On completion of the retrieval operation, the
occurs. After the retrieval operation, the data area specified data area is set to the length of the data.
in the LENGTH option is set to the record length (before any
If DATALOCATION(ANY) is associated with the
truncation occurred).
application program, the address of the data can be
Alternatively, a pointer reference can be specified in the SET above or below the 16MB line.
option. CICS then acquires an area of sufficient size to hold If DATALOCATION(BELOW) is associated with the
the record, and sets the pointer reference to the address of application program, and the data resides above the
that area. After the retrieval operation, the data area 16MB line, the data is copied below the 16MB line, and
specified in the LENGTH option is set to the record length. the address of this copy is returned.

The outboard controller might not send the data from the If TASKDATAKEY(USER) is specified for the running
data set specified in the ISSUE QUERY command. The task, and storage protection is active, the data returned
ASSIGN command must be used to get the value of DESTID is in a user-key. If TASKDATAKEY(CICS) is specified
(which identifies the data set that has actually been and storage protection is active, the data returned is in a
transmitted) and the value of DESTIDLENG (which is the CICS-key.
length of the identifier in DESTID). | If you have specified SET, you must also specify
| LENGTH.
ISSUE RECEIVE options
INTO(data-area)
ISSUE RECEIVE conditions
specifies the receiving field for the data read from the DSSTAT
data set. occurs when the destination status changes in one of
If you specify the ISSUE RECEIVE command with the the following ways:
INTO option, the parameter must be a data area that
The data stream is abended.
specifies the maximum length of data that the program is
The data stream is suspended.
prepared to handle. If the value specified is less than
zero, zero is assumed. If the length of the data exceeds Default action: terminate the task abnormally.
the value specified, the data is truncated to that value
EOC
and the LENGERR condition occurs. On completion of
occurs if the request/response unit (RU) is received with
the retrieval operation, the data area is set to the original
the end-of-chain (EOC) indicator set. Field EIBEOC also
length of the data.
contains this indicator.
LENGTH(data-area)
Default action: ignore the condition.
specifies the length (halfword binary value) of the data
received.

Chapter 1. Commands 157

ISSUE RECEIVE

EODS
occurs when the end of the data set is encountered.
Default action: terminate the task abnormally.

LENGERR
occurs if the length of the retrieved data is greater than
the value specified by the LENGTH option.
Default action: terminate the task abnormally.

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

158 CICS/ESA Application Programming Reference

ISSUE REPLACE

Function
Update a record in a data set.

Command syntax

──ISSUE REPLACE──DESTID(data-value)──┬────────────────────────┬──────────────────────────────────────────
└─DESTIDLENG(data-value)─┘
──┬────────────────────────────────────────────────┬──FROM(data-area)──┬────────────────────┬─────────────
└─VOLUME(data-value)──┬────────────────────────┬─┘ └─LENGTH(data-value)─┘
└─VOLUMELENG(data-value)─┘
──┬────────────────────┬──RIDFLD(data-area)──┬─KEYLENGTH(data-value)──┬───────────────────────┬─┬─────────
└─NUMREC(data-value)─┘ │ └─KEYNUMBER(data-value)─┘ │
└─RRN──────────────────────────────────────────────┘
──┬─────────┬──┬────────┬──"
└─DEFRESP─┘ └─NOWAIT─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE REPLACE updates (replaces) a record in either a NOWAIT

relative (addressed direct) or an indexed (keyed direct) data specifies that the CICS task continues processing
set in an outboard controller. without waiting for the ISSUE REPLACE command to
complete. If this option is not specified, the task activity
is suspended until the command is completed.
ISSUE REPLACE options
NUMREC(data-value)
DEFRESP
for a relative data set, specifies as a halfword binary
specifies that all terminal control commands issued as a
value the number of logical records to be replaced.
result of the ISSUE REPLACE command request a
Records are replaced sequentially starting with the one
definite response from the outboard batch program,
identified by the RIDFLD option.
irrespective of the specification of message integrity for
the CICS task (by the system programmer). For an indexed data set, NUMREC cannot be specified
because only one record is replaced.
DESTID(data-value)
specifies the name (1–8 characters) of the data set in RIDFLD(data-area)
the outboard destination. # specifies the record identification field. When combined
# with RRN this is a 4-character field.
DESTIDLENG(data-value)
specifies the length (halfword binary value) of the name # For a relative record data set, the RIDFLD option
specified in the DESTID option. # specifies a fullword binary integer (the relative record
# number of the record starting from zero); and the RRN
FROM(data-area) # option is used.
specifies the data that is to be written to the data set.
For an indexed data set, the RIDFLD option specifies
KEYLENGTH(data-value) the key that is embedded in the data specified by the
specifies the length (halfword binary value) of the key FROM option. The KEYLENGTH option is also required.
specified in the RIDFLD option.
RRN
KEYNUMBER(data-value) specifies that the record identification field specified in
specifies the number, as a halfword binary value, of the the RIDFLD option contains a relative record number.
index to be used to locate the record. There can be This option is required for a relative record data set.
eight indexes (1 through 8). The default is 1. This If the option is not specified, RIDFLD is assumed to
option applies only to DPCX/DXAM and is mutually specify a key.
exclusive with RRN.
VOLUME(data-value)
LENGTH(data-value) specifies the name (1–8 characters) of a diskette in an
specifies the length (halfword binary value) of the data to outboard destination that contains the data set specified
be written. in the DESTID option.

Chapter 1. Commands 159

ISSUE REPLACE

VOLUMELENG(data-value)
specifies the length (halfword binary value) of the name
specified in the VOLUME option.

ISSUE REPLACE conditions

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

160 CICS/ESA Application Programming Reference

ISSUE RESET

Function
Relinquish use of a telecommunication line.

Command syntax

──ISSUE RESET──"
Conditions:
| INVREQ, NOTALLOC

ISSUE RESET applies only to the following devices:

System/7
2260 or 2265 display station
2741 communication terminal
3270 information display system
3600 finance communication system
3735 programmable buffered terminal
3740 data entry system.

In each case, the device is connected with BTAM, and the

next BTAM operation is a READ or WRITE INITIAL.

RESET for a VTAM logical unit is treated as an ISSUE

DISCONNECT.

ISSUE RESET conditions

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

Chapter 1. Commands 161

ISSUE SEND

Function
Send data to a named data set or to a selected medium.

Command syntax

──ISSUE SEND──┬────────────────────────────────────────────────┬─────────────────────────────────────────
├─DESTID(data-value)──┬────────────────────────┬─┤
│ └─DESTIDLENG(data-value)─┘ │
│ ┌─CONSOLE──┐ │
└─SUBADDR(data-value)──┼──────────┼──────────────┘
├─PRINT────┤
├─CARD─────┤
├─WPMEDIA1─┤
├─WPMEDIA2─┤
├─WPMEDIA3─┤
└─WPMEDIA4─┘
──┬────────────────────────────────────────────────┬──FROM(data-area)──┬────────────────────┬─────────────
└─VOLUME(data-value)──┬────────────────────────┬─┘ └─LENGTH(data-value)─┘
└─VOLUMELENG(data-value)─┘
──┬────────┬──┬─────────┬──"
└─NOWAIT─┘ └─DEFRESP─┘
Conditions:
FUNCERR, IGREQCD, INVREQ, SELNERR, UNEXPIN

ISSUE SEND sends data to a named data set in an outboard DESTIDLENG(data-value)

controller, or to a selected medium in a batch logical unit or specifies the length (halfword binary value) of the name
an LUTYPE4 logical unit. The options CONSOLE, PRINT, specified in the DESTID option.
CARD, and WPMEDIA1–4 are alternatives to DESTID and
FROM(data-area)
DESTIDLENG.
specifies the data to be written to the data set.

ISSUE SEND options LENGTH(data-value)

specifies a halfword binary value that is the length of the
CARD data to be written.
specifies that the output medium is a card reader or card
punch device. This option is not valid with DESTID and NOWAIT
DESTIDLENG. specifies that the CICS task continues processing
without waiting for the ISSUE SEND command to
CONSOLE complete. If this option is not specified, the task activity
specifies that the output medium is that provided for is suspended until the command is completed.
messages to the operator. This option is not valid with
DESTID and DESTIDLENG. This refers to a PRINT
programmable subsystem such as the IBM 3790 data specifies that the output is to the print medium.
communication system. It does not refer to a CICS or SUBADDR(data-value)
system console. specifies the medium subaddress as a halfword binary
DEFRESP value (in the range 0–15) that allows media of the same
specifies that all terminal control commands issued as a type, for example, “printer 1” or “printer 2”, to be defined.
result of the ISSUE SEND command request a definite Value 15 means a medium of any type. The default is
response from the outboard batch program, irrespective zero.
of the specification of message integrity for the CICS VOLUME(data-value)
task (by the system programmer). specifies the name (1–8 characters) of a diskette in an
DESTID(data-value) outboard destination that contains the data set specified
specifies the name (1–8 characters) of the data set in in the DESTID option.
the outboard destination.

162 CICS/ESA Application Programming Reference

ISSUE SEND

VOLUMELENG(data-value)
specifies the length of the name specified in the
VOLUME option as a halfword binary value.

WPMEDIA1 through WPMEDIA4

specifies that for each specific LUTYPE4 device, a word
processing medium is defined to relate to a specific
input/output device.

ISSUE SEND conditions

IGREQCD
occurs when an attempt is made to execute an ISSUE
SEND command after a SIGNAL RCD data-flow control
code has been received from an LUTYPE4 logical unit.
Default action: terminate the task abnormally.

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

Chapter 1. Commands 163

ISSUE SIGNAL (APPC)

Function
Request change of direction from sending transaction on an APPC mapped conversation.

Command syntax

──ISSUE SIGNAL──┬──────────────┬──┬─────────────┬──"
└─CONVID(name)─┘ └─STATE(cvda)─┘
Conditions:
| INVREQ, NOTALLOC, TERMERR

ISSUE SIGNAL, in a transaction in receive mode, signals to ISSUE SIGNAL (APPC) conditions
the sending transaction that a mode change is needed. It
raises the SIGNAL condition on the next SEND, RECEIVE, INVREQ
or CONVERSE command executed in the sending occurs in any of the following situations:
transaction, and a previously executed HANDLE CONDITION The command has been used on an APPC
command for this condition can be used either to take some conversation that is not using the EXEC CICS
action, or to ignore the request. interface, or is not a mapped conversation.
A distributed program link server application
ISSUE SIGNAL (APPC) options specified the function-shipping session (its principal
facility) on the CONVID option (RESP2=200).
CONVID(name)
identifies the conversation to which the command Default action: terminate the task abnormally.
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command NOTALLOC
in EIBRSRCE in the EIB, or the token representing the occurs if the CONVID value in the command does not
principal session (returned by a previously executed relate to a conversation that is owned by the application.
ASSIGN command). Default action: terminate the task abnormally.
For compatibility with earlier releases, SESSION is TERMERR
accepted as a synonym for CONVID. New programs occurs for a session-related error. Any action on that
should use CONVID. conversation other than a FREE causes an ATCV
If this option is omitted, the principal facility is assumed. abend.

STATE(cvda) | A CANCEL TASK request by a user node error program

gets the state of the current conversation. The cvda | (NEP) may cause TERMERR if the task has an
values returned by CICS are: | outstanding terminal control request when the node
| abnormal condition program handles the session error.
ALLOCATED
Default action: terminate the task abnormally with abend
CONFFREE
code ATNI.
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

164 CICS/ESA Application Programming Reference

ISSUE SIGNAL (LUTYPE6.1)

Function
Request change of direction from sending transaction on LUTYPE6.1 conversation.

Command syntax

──ISSUE SIGNAL──┬───────────────┬──"
├─CONVID(name)──┤
└─SESSION(name)─┘
Conditions:
| NOTALLOC, TERMERR

ISSUE SIGNAL, in a transaction in receive mode, signals to

the sending transaction that a mode change is needed. It
raises the SIGNAL condition on the next SEND, RECEIVE,
or CONVERSE command executed in the sending
transaction, and a previously executed HANDLE CONDITION
command for this condition can be used either to take some
action, or to ignore the request.

If both CONVID and SESSION are omitted, the principal

facility for the task is used.

ISSUE SIGNAL (LUTYPE6.1) options

CONVID(name)
identifies the conversation to which the command
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command
in EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed
ASSIGN command).

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be used.

ISSUE SIGNAL (LUTYPE6.1) condition

NOTALLOC
occurs if the facility specified in the command is not
owned by the application.
Default action: terminate the task abnormally.

TERMERR
occurs for a session-related error. Any action on that
conversation other than a FREE causes an ATCV
abend.
| A CANCEL TASK request by a user node error program
| (NEP) may cause TERMERR if the task has an
| outstanding terminal control request when the node
| abnormal condition program handles the session error.
Default action: terminate the task abnormally with abend
code ATNI.

Chapter 1. Commands 165

ISSUE WAIT

Function
Wait for an operation to be completed.

Command syntax

──ISSUE WAIT──┬────────────────────────────────────────────────┬─────────────────────────────────────────
├─DESTID(data-value)──┬────────────────────────┬─┤
│ └─DESTIDLENG(data-value)─┘ │
│ ┌─CONSOLE──┐ │
└─SUBADDR(data-value)──┼──────────┼──────────────┘
├─PRINT────┤
├─CARD─────┤
├─WPMEDIA1─┤
├─WPMEDIA2─┤
├─WPMEDIA3─┤
└─WPMEDIA4─┘
──┬────────────────────────────────────────────────┬──"
└─VOLUME(data-value)──┬────────────────────────┬─┘
└─VOLUMELENG(data-value)─┘
Conditions:
FUNCERR, INVREQ, SELNERR, UNEXPIN

ISSUE WAIT suspends task activity until the previous batch SUBADDR(data-value)
data interchange command is completed. This command is specifies the medium subaddress as a halfword binary
meaningful only when it follows an ISSUE ADD, ISSUE value (in the range 0–through 15) that allows media of
ERASE, ISSUE REPLACE, or ISSUE SEND command. The the same type, for example, “printer 1” or “printer 2”, to
options CONSOLE, PRINT, CARD, and WPMEDIA1–4 are be defined. Value 15 means a medium of any type.
alternatives to DESTID and DESTIDLENG. The default is zero.

VOLUME(data-value)
ISSUE WAIT options specifies the name (1–6 characters) of a diskette in an
outboard destination that contains the data set specified
CARD
in the DESTID option.
specifies that the output medium is a card reader or card
punch device. This option is not valid with DESTID and VOLUMELENG(data-value)
DESTIDLENG. specifies the length of the name specified in the
VOLUME option as a halfword binary value.
CONSOLE
specifies that the output medium is that provided for WPMEDIA1 through WPMEDIA4
messages to the operator. This option is not valid with specifies that, for each specific LUTYPE4 device, a
DESTID and DESTIDLENG. word-processing medium is defined to relate to a specific
This refers to a programmable subsystem such as the input/output device.
IBM 3790 data communication system. It does not refer
to a CICS or system console. ISSUE WAIT conditions
DESTID(data-value) FUNCERR
specifies the name (1–8 characters) of the data set in occurs if there is an error during execution of the
the outboard destination. command. Destination selection is unaffected and other
commands for the same destination may be successful.
DESTIDLENG(data-value)
specifies the length (halfword binary value) of the name Default action: terminate the task abnormally.
specified in the DESTID option.

PRINT
specifies that the output is to the print medium.

166 CICS/ESA Application Programming Reference

ISSUE WAIT

UNEXPIN
occurs when some unexpected or unrecognized
information is received from the outboard controller.
Default action: terminate the task abnormally.

Chapter 1. Commands 167

LINK

Function
Link to another program expecting return.

| The external CICS interface provides an EXEC CICS LINK command that performs all six commands of the interface in one
| invocation.

Command syntax

──LINK──PROGRAM(name)──┬─────────────────────────────────────────────────────────────────────────┬───────
└─COMMAREA(data-area)──┬────────────────────┬──┬────────────────────────┬─┘
└─LENGTH(data-value)─┘ └─DATALENGTH(data-value)─┘
──┬────────────────────────────────────────────────────────────┬──"
├─INPUTMSG(data-area)──┬─────────────────────────┬───────────┤
│ └─INPUTMSGLEN(data-value)─┘ │
└─┬───────────────────┬──┬──────────────┬──┬───────────────┬─┘
| └─SYSID(systemname)─┘ └─SYNCONRETURN─┘ └─TRANSID(name)─┘
Conditions:
INVREQ, LENGERR, NOTAUTH, PGMIDERR, ROLLEDBACK, SYSIDERR, TERMERR

LINK passes control from an application program at one Distributed program link
logical level to an application program at the next lower
| logical level. If the requested program is not defined to If you specify a remote region name on the SYSID option
| CICS, and AUTOINSTALL is active, CICS supplies a (with or without the associated TRANSID and
| definition for the program. If it is not a remote program in SYNCONRETURN options), the link is a distributed program
| another CICS region, and the linked-to program is not link (DPL). In response to a distributed program link, the
| already in main storage, CICS loads it. If the SYSID option local CICS region (the client region) ships the link request to
specifies the name of a remote CICS region, CICS ships the the remote region (the server region). The server region
link request to the remote region. When the RETURN executes the linked-to program (the server program) on
command is executed in the linked-to program, control is behalf of the program issuing the link request (the client
returned to the program initiating the link at the next program).
sequential executable instruction.
The SYSID and INPUTMSG options are mutually exclusive.
The following example shows how to request a link to an If you specify both options on a LINK command, the
application program called PROG1: translator issues error message DFH7230 (severity E)
EXEC CICS LINK PROGRAM('PROG1') indicating conflicting options. See the DFH7xxx (DFHExP
command translator diagnostic) messages entry in the
The linked-to program operates independently of the program CICS/ESA Messages and Codes manual for an explanation
that issues the LINK command with regard to handling of severity E for the different supported languages.
# conditions, attention identifiers, abends, and execution key.
For example, the effects of HANDLE CONDITION commands A server program running in the server region is restricted to
in the linking program are not inherited by the linked-to a DPL subset of the CICS API. Briefly, the server program
program, but the original HANDLE CONDITION commands cannot issue:
are restored on return to the linking program. See the Terminal control commands that reference the principal
CICS/ESA Application Programming Guide for more facility
information and an illustration of the concept of logical levels. Options of ASSIGN that return terminal attributes
BMS commands
You can use the HANDLE ABEND command to deal with Signon and signoff commands
abnormal terminations in other link levels. See the Batch data interchange commands
CICS/ESA Application Programming Guide for further details Commands that address the TCTUA.
about the relationship between LINK and HANDLE ABEND.
For details of the restricted DPL subset of the API, see
Appendix G, “API restrictions for distributed program link” on
page 367.

168 CICS/ESA Application Programming Reference

LINK

Abends in the server program: If a server program PROGRAM(name)

abends, the abend code is returned to the client program. If specifies the identifier (1–8 characters) of the program to
the client program is not written to handle the abend returned which control is to be passed unconditionally. The
by the server program, the client program abends with the specified name must have been defined as a program to
same abend code returned by the server program. | CICS, though if AUTOINSTALL is active a definition is
| autoinstalled. If the SYSID option specifies a remote
region, the linked-to program is the server program in
LINK options the server region.
COMMAREA(data-area) | Note the use of quotes:
specifies a communication area that is to be made
| EXEC CICS LINK PROGRAM('PROGX')
available to the invoked program. In this option a
pointer to the data area is passed. In a COBOL | PROGX is in quotes because it is the program name.
receiving program, you must give this data area the | EXEC CICS LINK PROGRAM(DAREA)
name DFHCOMMAREA in the receiving program. (See
the section about passing data to other programs in the | DAREA is not in quotes because it is the name of a
CICS/ESA Application Programming Guide.) | data area.

DATALENGTH(data-value) SYNCONRETURN
specifies a halfword binary value that is the length of a specifies that the server region named on the SYSID
contiguous area of storage, from the start of the option is to take a syncpoint on successful completion of
COMMAREA, to be passed to the invoked program. If the server program.
the amount of data being passed in a COMMAREA is # Apar PQ03185
small, but the COMMAREA itself is large so that the
# Documentation for Apar PQ03185 added 19/05/97
linked-to program can return the requested data, you
should specify DATALENGTH in the interest of
performance. # Synconreturn is only applicable to remote links; it is
# ignored if the link is local.
DATALENGTH cannot be used at the same time as
INPUTMSG. SYSID(systemname)
specifies the system name of the CICS server region
INPUTMSG(data-area) where the program link request is to be routed.
specifies data to be supplied to the invoked program
when it first issues a RECEIVE command. This data # If SYSID specifies a remote system, no reference is
remains available until the execution of a RECEIVE or # made to PROGRAM resource definitions held locally. If
RETURN command. An invoked program can invoke a # SYSID specifies the local system, CICS treats the LINK
further program and so on, creating a chain of linked # request as if SYSID was not specified.
programs. If a linked-to chain exists, CICS supplies the | TRANSID(name)
INPUTMSG data to the first RECEIVE command | specifies the name of the mirror transaction that the
executed in the chain. If control returns to the program remote region is to attach, and under which it is to run
that issued the LINK with INPUTMSG before the the server program. If you omit the TRANSID option,
INPUTMSG data has been accepted by a RECEIVE the server region attaches either CSMI, CPMI, or CVMI
command, CICS assumes that a RECEIVE command by default.
has been issued. This means that the original
INPUTMSG data is no longer available. The transaction name you specify on the LINK command
takes priority over any transaction specified on the
INPUTMSG cannot be used at the same time as | program resource definition. Whilst you can specify your
DATALENGTH. | own name for the mirror transaction initiated by DPL
See also the CICS/ESA Application Programming Guide | requests, the transaction must be defined in the server
for more information about the INPUTMSG option. | region, and the transaction definition must specify the
| mirror program, DFHMIRS.
INPUTMSGLEN(data-value)
specifies a halfword binary value to be used with
INPUTMSG.

LENGTH(data-value)
specifies a halfword binary value that is the length in
# bytes of the COMMAREA (communication area). This
# value may not exceed 32 500 bytes if the COMMAREA
# is to be passed between any two CICS servers (for any
# combination of product/version/release).

Chapter 1. Commands 169

LINK

LINK conditions | The COMMAREA address is zero, but the

| COMMAREA length is non zero (RESP2=26).
INVREQ
| The INPUTMSG length less than 0 or greater than
occurs in any of the following situations:
| 32767 (RESP2=27).
A LINK command with the INPUTMSG option is
Default action: terminate the task abnormally.
issued for a program that is not associated with a
terminal, or that is associated with an APPC logical Note: RESP2 values are not returned to the client for
unit, or an IRC session (RESP2=8). conditions occurring in a DPL server program.
A LINK command with the INPUTMSG option is NOTAUTH
issued for a program that is the subject of a DPL occurs when a resource security check has failed on
request; that is, SYSID is also specified | PROGRAM(name) (RESP2=101).
(RESP2=19).
Default action: terminate the task abnormally.
The SYNCONRETURN option is specified but the
program issuing the link request (the client program) PGMIDERR
is already in conversation with a mirror task in the occurs if a program:
remote region specified on the SYSID option. | Has no entry in the PPT and either program
# Apar PQ25518 | autoinstall was switched off, or the program
| autoinstall control program indicated that the
# Documentation for Apar PQ25518 added
| program should not be autoinstalled (RESP2=1)
# 17/08/99
Is disabled (RESP2=2)
| Could not be loaded because
# (That is, a logical unit-of-work (LUW) is in progress
# or the system initialization parameter | – This was the first load of the program and the
# MROFSE=YES has been specified in the client | program load failed, usually because the load
# region) In this case, the client program is in an | module could not be found.
incorrect state to support the SYNCONRETURN | – This was a subsequent load of the program, but
option (RESP2=14). | the first load failed.
The program issuing the link request is already in | In order to reset the load status the load module
conversation with a mirror task and the TRANSID | must be in the DFHRPL concatenation, and a SET
specified is different from the transaction identifier of | PROGRAM NEWCOPY will be required (RESP2=3).
the active mirror (RESP2=15). | The program autoinstall control program failed either
The TRANSID specified is all blanks (RESP2=16). | because the program autoinstall control program is
| incorrect, incorrectly defined, or as a result of an
| The program manager domain has not yet been | abend in the program autoinstall control program.
| initialized. This is probably due to a link request | Program autoinstall is disabled and message
| having been made in a first stage PLT (RESP2=30). | DFHPG0202 or DFHPG0203 written to the CSPL
Default action: terminate the task abnormally. | (RESP2=21).
| The model returned by the program autoinstall
Note: RESP2 values are not returned to the client for | control program was not defined in the PPT table, or
conditions occurring in a DPL server program. | was not enabled (RESP2=22).
LENGERR | The program autoinstall control program returned
occurs in any of the following situations: | invalid data (RESP2=23).
| Define for the program failed due to autoinstall
The length specified on the LENGTH option is | returning an invalid program name or definition
greater than the length of the data area specified in | (RESP2=24).
the COMMAREA option, and while that data was
being copied a destructive overlap occurred Default action: terminate the task abnormally.
because of the incorrect length. ROLLEDBACK
| The COMMAREA length is less than 0 or greater occurs if the SYNCONRETURN is specified and the
| than 32767 (RESP2=11). server program is unable successfully to take a
syncpoint. The server program has taken a rollback,
The length specified on the DATALENGTH option is
and all changes made to recoverable resources in the
a negative value (RESP2=12).
remote region, within the current LUW, are backed out
The length specified on the DATALENGTH option is (RESP2=29).
greater than the length specified on the LENGTH
Default action: terminate the task abnormally.
option (RESP2=13).

170 CICS/ESA Application Programming Reference

LINK

SYSIDERR TERMERR
occurs in any of the following situations: occurs if an irrecoverable error occurs during the
conversation with the mirror (for example, if the session
The SYSID specified cannot be found in the
fails, or if the server region fails) (RESP2=17).
intersystem table, or if the link to the specified
system is unavailable (RESP2=18). Default action: terminate the task abnormally.

The remote system specified by SYSID is an Note: RESP2 values are not returned to the client for
LUTYPE6.1-connected system. Distributed program conditions occurring in a DPL server program.
link requests are not supported on LUTYPE6.1
connections (RESP2=20).

Notes:

1. There is no local queuing in the event of a

SYSIDERR.
2. RESP2 values are not returned for conditions
occurring on DPL requests.

Default action: terminate the task abnormally.

Chapter 1. Commands 171

LOAD

Function
Load a program from the CICS DFHRPL concatenation library into main storage.

Command syntax

──LOAD──PROGRAM(name)──┬──────────────┬──┬────────────────────┬──┬────────────────┬──┬──────┬──"
└─SET(ptr-ref)─┘ ├─LENGTH(data-area)──┤ └─ENTRY(ptr-ref)─┘ └─HOLD─┘
└─FLENGTH(data-area)─┘
Conditions:
| INVREQ, LENGERR, NOTAUTH, PGMIDERR

| Dynamic transaction routing

| Using LOAD with HOLD, or using a resource that has been defined with RELOAD=YES, could create inter-transaction
| affinities that adversely affect the use of dynamic transaction routing. See the CICS/ESA Application Programming Guide
| for more information about transaction affinities.

| Load makes available to the invoking task a copy of an FLENGTH(data-area)

| application program, table, or map. If the program is defined specifies a fullword binary area to be set to the length of
| with RELOAD=NO, it is only fetched from the library where it the loaded program, table, or map. Use FLENGTH if the
| resides, if there is not a copy already in main storage. If the length of the loaded program is greater than 32KB.
| program is defined with RELOAD=YES, a new copy is
HOLD
| always fetched from the library. (See the CICS/ESA
| specifies that the loaded program, table, or map is not to
| Application Programming Guide for further details about
| be released (if still available) when the task issuing the
| maps.) Using LOAD can reduce system overhead. The
| LOAD command is terminated; it is to be released only
following example shows how to load a user-prepared table
| in response to a RELEASE command from this task or
called TB1:
| from another task.
EXEC CICS LOAD PROGRAM('TB1') SET(PTR)
| If you omit HOLD, the program, table, or map is
| released when the task that issued the load terminates
LOAD options | or issues a RELEASE command.
ENTRY(ptr-ref) | If, however, the program is defined with RELOAD=YES,
specifies the pointer reference that is to be set to the | neither of the above apply. RELEASE does not work,
address of the entry point in the program that has been | and a FREEMAIN must be issued to get rid of the
loaded. | program.
| The top bit of the address is set on if the program is LENGTH(data-area)
| defined with AMODE=31. specifies a halfword binary value to be set to the length
| For assembler programs without an explicit ENTRY of the loaded program, table, or map. To avoid raising
| defined in the linkedit definitions, the entry point returned the LENGERR condition, use FLENGTH if the length of
| depends on (1) whether there is a CICS stub, and (2) the loaded program is likely to be greater than 32KB.
# whether the LOAD command is issued from a PLT PROGRAM(name)
# program: specifies the identifier (1–8 characters) of a program,
# If there is a CICS stub, the entry point address is table, or map to be loaded. The specified name must
# incremented for this stub unless the LOAD | have been defined as a program to CICS, though if
# command is issued from a PLT program executed | AUTOINSTALL is active a definition is autoinstalled.
# during the first phase of initialization or the final SET(ptr-ref)
# phase of shutdown. specifies the pointer reference that is to be set to the
# If there is not a CICS stub, the entry point address address at which a program, table, or map is loaded.
# is the same as the load point address.
LOAD conditions

172 CICS/ESA Application Programming Reference

LOAD

| INVREQ
| Occurs if the program manager domain has not yet been
| initialized. This is probably due to a load request having
| been made in a first stage PLT (RESP2=30).
| Default action: terminate the task abnormally.

LENGERR
occurs when LENGTH is used and the length of the
| loaded program is not less than 32KB. (RESP2=19).
Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
| PROGRAM(name) (RESP2=101).
Default action: terminate the task abnormally.

PGMIDERR
occurs in any of the following situations:

| A program, table, or map has no entry in the PPT

| and either program autoinstall was switched off, or
| the program autoinstall control program indicated
| that the program should not be autoinstalled
| (RESP2=1).
A program is disabled (RESP2=2).
| A program could not be loaded because
| – This was the first load of the program and the
| program load failed, usually because the load
| module could not be found.
| – This was a subsequent load of the program, but
| the first load failed.
| In order to reset the load status the load module
| must be in the DFHRPL concatenation, and a SET
| PROGRAM NEWCOPY will be required (RESP2=3).
The installed program definition is for a remote
program (RESP2=9).
| The program autoinstall control program failed either
| because the program autoinstall control program is
| incorrect, incorrectly defined, or as a result of an
| abend in the program autoinstall control program.
| Program autoinstall is disabled and message
| DFHPG0202 or DFHPG0203 written to the CSPL
| (RESP2=21).
| The model returned by the program autoinstall
| control program was not defined in the PPT table, or
| was not enabled (RESP2=22).
| The program autoinstall control program returned
| invalid data (RESP2=23).
| Define for the program failed due to autoinstall
| returning an invalid program name or definition
| (RESP2=24).

Default action: terminate the task abnormally.

Chapter 1. Commands 173

MONITOR

Function
Code a user event-monitoring point.

Command syntax

──MONITOR──POINT(data-value)──┬──────────────────┬──┬──────────────────┬──┬──────────────────────┬──"
└─DATA1(data-area)─┘ └─DATA2(data-area)─┘ └─ENTRYNAME(data-area)─┘
Conditions:
INVREQ

MONITOR provides information about the performance of

your application transactions. It replaces the monitoring 1:
aspects of ENTER TRACEID. EXEC CICS MONITOR
POINT(11)
In addition to the monitoring data collected at predefined ENTRYNAME(ENTRY3)
event monitoring points (EMPs) within CICS, a user needing: DFHMCT TYPE=EMP,
application program can contribute data to user fields within CLASS=PERFORM,
ID=(ENTRY3.11),
the CICS monitoring records. You can do this by using the
CLOCK=(1,CLOCKA),
| MONITOR command to invoke user-defined EMPs. At each
PERFORM=SCLOCK(1)
| of these user EMPs, you can add or change 1–16384 bytes 2:
| of your own data in each performance monitoring record. In EXEC CICS MONITOR
| those 16384 bytes, you can have any combination of the POINT(12)
| following: ENTRYNAME(ENTRY3)
0 through 256 counters needing: DFHMCT TYPE=EMP,
0 through 256 clocks CLASS=PERFORM,
ID=(ENTRY3.12),
| A single 8192-byte character string.
PERFORM=PCLOCK(1)
3:
For example, you could use these user EMPs to count the
EXEC CICS MONITOR
number of times a certain event occurs, or to time the
POINT(13)
interval between two events. DATA1(address of data)
DATA2(length of data)
Figure 4 gives examples of MONITOR commands (and of
ENTRYNAME(ENTRY3)
the MCT entries you need for them). See the CICS/ESA needing: DFHMCT TYPE=EMP,
Customization Guide for more information about monitoring. CLASS=PERFORM,
ID=(ENTRY3.13),
Notes: PERFORM=MOVE(O,32)
1. Example 1 shows a user clock being started by an
application identified as PROG3. This is the eleventh Figure 4. Examples of coding user EMPs
EMP in this application. To prevent confusion with the
eleventh EMP in another application, this EMP is
uniquely identified by the tag ENTRY3.11. The clock
that is being started is the first clock in a string.
2. Example 2 shows the same user clock being stopped,
by the same application, but from a different EMP. The
EMP is uniquely identified by the tag ENTRY3.12.
3. Example 3 shows some user data being loaded into the
32-byte character string reserved for that purpose. The
loading starts at offset 0, and the data is no more than
32 bytes in length.

174 CICS/ESA Application Programming Reference

MONITOR

MONITOR options POINT(data-value)

specifies the monitoring point identifier as defined in the
DATA1(data-area) MCT, and is in the range 0 through 255. Note, however,
| specifies a 4-byte variable whose contents depend on that point identifiers in the range 200 through 255 are
the type of user EMP being used: reserved for use by IBM program products.
If the user EMP contains an ADDCNT, SUBCNT,
NACNT, EXCNT, or ORCNT option, the DATA1 MONITOR condition
variable is an area used as defined by the MCT
user EMP definition. INVREQ
occurs in any of the following situations:
If the MCT user EMP definition contains an
MLTCNT option, the DATA1 variable is an area with Your POINT value is outside the range 1 through
the address of a series of adjacent fullwords 255 (RESP2=1)
containing the values to be added to the user count Your POINT value is not defined in the MCT
fields defined in the MCT user EMP definition. (RESP2=2)
If the MCT user EMP definition contains a MOVE Your DATA1 value is not valid (RESP2=3)
option, the DATA1 variable is an area with the
address of the character string to be moved. Your DATA2 value is not valid (RESP2=4)
You did not specify DATA1 for an MCT operation
See the &dfha500l. for details of user EMP options.
that required it (RESP2=5)
DATA2(data-area) You did not specify DATA2 for an MCT operation
| specifies a 4-byte variable whose contents depend on that required it (RESP2=6)
the type of user EMP being used:
| Default action: terminate the task abnormally.
If the user EMP contains an ADDCNT, SUBCNT,
NACNT, EXCNT, or ORCNT option, the DATA2
variable is an area used as defined by the MCT
user EMP definition.
If the MCT user EMP definition contains an
MLTCNT option, the DATA2 variable is an area with
the number of user count fields to be updated. The
number specified in DATA2 overrides the default
value defined in the MCT for the operation. A value
of zero instructs monitoring to use the default. If
DATA2 is not specified, the MLTCNT operation
raises an INVREQ condition although the operation
was successful.
If the MCT user EMP definition contains a MOVE
option, the DATA2 variable is an area with the
length of the character string to be moved. The
number specified in DATA2 will override the default
value defined in the MCT for the operation. A value
of zero instructs monitoring to use the default. If
DATA2 is not specified, the MOVE operation raises
an INVREQ although the operation was successful.

See the &dfha500l. for details of user EMP options.

ENTRYNAME(data-area)
is the monitoring point entry name that qualifies the
POINT value and is defined in the monitoring control
table (MCT). ENTRYNAME defaults to USER if not
specified.

Chapter 1. Commands 175

POINT

Function
Get information about an LUTYPE6.1 logical unit.

Command syntax

──POINT──┬───────────────┬──"
├─CONVID(name)──┤
└─SESSION(name)─┘
Conditions:
NOTALLOC

POINT gets information about a named facility, such as

whether it owns the given facility.

This command can be used on an MRO session.

POINT options
CONVID(name)
identifies the conversation to which the command
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command
in EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed
ASSIGN command).

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be used. If both this option and CONVID are
omitted, the principal facility for the task is used.

POINT condition
NOTALLOC
occurs if the facility specified in the command is not
owned by the application.
Default action: terminate the task abnormally.

176 CICS/ESA Application Programming Reference

POP HANDLE

Function
Restore the stack.

Command syntax

──POP HANDLE──"
Conditions:
INVREQ

POP HANDLE enables you to restore the effect of IGNORE

CONDITION, HANDLE ABEND, HANDLE AID, and HANDLE
CONDITION commands to the state they were in before a
PUSH HANDLE command was executed at the current link
level. This can be useful, for example, during a branch to a
subroutine embedded in a main program.

# Normally, when a CICS program calls a subroutine (at the

# same logical level), the program or routine that receives
# control inherits the current HANDLE commands. These
# commands may not be appropriate within the called program.
# The called program can use PUSH HANDLE to suspend
# existing HANDLE commands, and before returning control to
# the caller, can then restore the original commands using the
# POP HANDLE command.
# Note: When a CICS program uses EXEC CICS LINK to call
# another CICS program, the HANDLE CONDITION
# options are NOT inherited by the linked-to program,
# but CICS will search preceding logical levels for a
# HANDLE ABEND exit. See CICS/ESA Application
# Programming Guide for further details about the
# relationship between LINK and HANDLE ABEND.

You can nest PUSH HANDLE ... POP HANDLE command

sequences within a task. Each POP HANDLE command
restores a set of specifications.

The C language does not support POP HANDLE.

POP HANDLE condition

INVREQ
occurs if no matching PUSH HANDLE command has
been executed at the current link level.
Default action: terminate the task abnormally.

Chapter 1. Commands 177

POST

Function
Request notification when a specified time has expired.

Command syntax

┌─INTERVAL()──────────────────────┐
──POST──┼──────────────────────────────────┼──SET(ptr-ref)──┬─────────────┬──"
├─INTERVAL(hhmmss)─────────────────┤ └─REQID(name)─┘
├─TIME(hhmmss)─────────────────────┤
│ ┌──
───────────────────────┐ │
| ├─AFTER───*┬─HOURS(data-value)───┬┴─┤
| │ ├─MINUTES(data-value)─┤ │
| │ └─SECONDS(data-value)─┘ │
│ ┌──
───────────────────────┐ │
| └─AT───*┬─HOURS(data-value)───┬┴────┘
| ├─MINUTES(data-value)─┤
| └─SECONDS(data-value)─┘
Conditions:
EXPIRED, INVREQ

Note for dynamic transaction routing

| Using POST if later CANCELed by another task could create inter-transaction affinities that adversely affect the use of
| dynamic transaction routing. See the CICS/ESA Application Programming Guide for more information about transaction
| affinities.

POST requests notification that a specified time has expired. The timer-event control area can be released for a variety of
In response to this command, CICS makes a timer-event reasons (see below). If this happens, the result of any other
control area available for testing. This 4-byte control area is task issuing a WAIT command on the event set up by the
initialized to binary zeros, and the pointer reference specified POST command is unpredictable.
in the SET option is set to its address.
However, other tasks can cancel the event if they have
When the time you specify has expired, the timer-event access to the REQID associated with the POST command.
control area is posted; that is, its first byte is set to X'40' (See the CANCEL command and the description of the
and its third byte to X'80'. You can test posting in either of REQID option.) A timer-event control area provided for a
the following ways: task is not released or altered (except as described above)
until one of the following events occurs:
By checking the timer-event control area at intervals.
You must give CICS the opportunity to post the area; The task issues a subsequent DELAY, POST, or START
that is, the task must relinquish control of CICS before command.
you test the area. Normally, this condition is satisfied as
The task issues a CANCEL command to cancel the
a result of other commands being issued; if a task is
POST command.
performing a long internal function, you can force control
to be relinquished by issuing a SUSPEND command. The task is terminated, normally or abnormally.

By suspending task activity by a WAIT EVENT or WAIT Any other task issues a CANCEL command for the
EXTERNAL command until the timer-event control area event set up by the POST command.
is posted. This action is similar to issuing a DELAY
A task can have only one POST command active at any
command but, with a POST and WAIT EVENT or WAIT
given time. Any DELAY, POST, or START command
EXTERNAL command sequence, you can do some
supersedes a POST command previously issued by the task.
processing after issuing the POST command; a DELAY
command suspends task activity at once. No other task
The default is INTERVAL(0), but for C the default is AFTER
should attempt to wait on the event set up by a POST
HOURS(0) MINUTES(0) SECONDS(0).
command.
| By using WAITCICS. The following example shows you how to request a
timer-event control area for a task, to be posted after 30
seconds:

178 CICS/ESA Application Programming Reference

POST

EXEC CICS POST REQID(name)

INTERVAL(3O) specifies a name (1–8 characters), which should be
REQID('RBL3D') | unique, to identify the POST request. Using this option
SET(PREF) | to specify an application-defined name is one way to
| enable another transaction to cancel the POST request.
The following example shows you how to provide a
timer-event control area for the task, to be posted when the | If you do not specify your own REQID, CICS generates
specified time of day is reached. Because no request | a unique request identifier for you in the EIBREQID field
identifier is specified in the command, CICS automatically | of the EXEC interface block. This, like your own REQID,
assigns one and returns it to the application program in the | can be used by another transaction to cancel the POST
EIBREQID field in the EIB. | request.
EXEC CICS POST | To enable other tasks to cancel unexpired POST
TIME(PACKTIME) | requests, you must make the request identifier
SET(PREF) | dynamically available. For example, storing it in a TS
| queue, whose name is known to other applications that
There are two ways to enter the time under AFTER and AT. | may want to cancel the POST request, is one way you
1. A combination of at least two of HOURS(0–99), | can pass a request identifier to other transactions.
MINUTES(0–59), and SECONDS(0–59). HOURS(1)
SECONDS(data-value)
SECONDS(3) would mean one hour and three seconds
| specifies a fullword binary value in the range 0–59, when
(the minutes default to zero).
| HOURS or MINUTES are also specified, or 0–359 999
2. As one of HOURS(0–99), MINUTES(0–5999), or | when SECONDS is the only option specified.
SECONDS(0–359 999). HOURS(1) means one hour.
MINUTES(62) means one hour and two minutes. SET(ptr-ref)
SECONDS(3723) means one hour, two minutes, and specifies the pointer reference to be set to the address
three seconds. of the 4-byte timer-event control area generated by
CICS. This area is initialized to binary zeros; on
expiration of the specified time, the first byte is set to
POST options X'40', and the third byte to X'80'.
AFTER The timer-event control area always resides below the
specifies the interval of time to elapse. | 16MB line in shared dynamic storage (SDSA).

AT TIME(hhmmss)
specifies the time when the posting of the timer-event
specifies the time of expiring.
control area should occur.
HOURS(data-value) | When using the C language, you are recommended to
specifies a fullword binary value in the range 0–99. | use the AFTER/AT HOURS, MINUTES, and SECONDS
INTERVAL(hhmmss) | options as C does not provide a packed decimal data
specifies an interval of time that is to elapse from the | type. You may use TIME, but if the value specified is
time at which the POST command is issued. The mm | not an integer constant, the application is responsible for
and ss are in the range 0–59. The time specified is | ensuring that the value passed to CICS is in packed
added to the current clock time by CICS when the | decimal format. See the section about expiration times
command is executed to calculate the expiration time. in the CICS/ESA Application Programming Guide.

This option is used to specify when the posting of the

timer-event control area should occur. POST conditions
| When using the C language, you are recommended to EXPIRED
| use the AFTER/AT HOURS, MINUTES, and SECONDS occurs if the time specified has already expired when the
| options as C does not provide a packed decimal data command is issued.
| type. You may use INTERVAL, but if the value specified
Default action: ignore the condition.
| is not an integer constant, the application is responsible
| for ensuring that the value passed to CICS is in packed INVREQ
| decimal format. occurs in any of the following situations:
MINUTES(data-value) The POST command is not valid for processing by
| specifies a fullword binary value in the range 0–59, when CICS
| HOURS or SECONDS are also specified, or 0–5999 | Hours are out of range (RESP2=4)
| when MINUTES is the only option specified. | Minutes are out of range (RESP2=5
| Seconds are out of range (RESP2=6).

Default action: terminate the task abnormally.

Chapter 1. Commands 179

PURGE MESSAGE

Function
Discontinue building a BMS logical message.

Command syntax

──PURGE MESSAGE──"
Conditions:
| Full BMS: INVREQ, TSIOERR

PURGE MESSAGE discontinues the building of a BMS

logical message. It deletes the current logical message,
including any pages of device-dependent data stream
already written to CICS temporary storage. The application
program may then build a new logical message.

The portions of the logical message already built in main

storage or in temporary storage are deleted.

See Appendix K, “BMS macro summary” on page 381 for

map definition macros.

PURGE MESSAGE is only available on full-function BMS.

For further information about BMS, see the CICS/ESA
Application Programming Guide.

PURGE MESSAGE condition

INVREQ
| occurs if the command was called in a distributed
| program link server program (RESP2=200).
Default action: terminate the task abnormally.

TSIOERR
occurs if there is an irrecoverable temporary storage
input/output error.
Default action: terminate the task abnormally.

180 CICS/ESA Application Programming Reference

PUSH HANDLE

Function
Suspend the stack.

Command syntax

──PUSH HANDLE──"

PUSH HANDLE enables you to suspend the current effect of

IGNORE CONDITION, HANDLE ABEND, HANDLE AID, and
HANDLE CONDITION commands. This can be useful, for
example, during a branch to a subroutine embedded in a
main program.

# Normally, when a CICS program calls a subroutine (at the

# same logical level), the program or routine that receives
# control inherits the current HANDLE commands. These
# commands may not be appropriate within the called program.
# The called program can use PUSH HANDLE to suspend
# existing HANDLE commands.
# Note: When a CICS program uses EXEC CICS LINK to call
# another CICS program, the HANDLE CONDITION
# options are NOT inherited by the linked-to program,
# but CICS will search preceding logical levels for a
# HANDLE ABEND exit. See CICS/ESA Application
# Programming Guide for further details about the
# relationship between LINK and HANDLE ABEND.

You can nest PUSH HANDLE ... POP HANDLE command

sequences within a task. Each PUSH HANDLE command
stacks a set of specifications.

The C language does not support PUSH HANDLE.

Chapter 1. Commands 181

QUERY SECURITY

Function
To query the security authorization of the user.

Command syntax

──QUERY SECURITY──┬─RESTYPE(data-value)───────────────────────────┬──RESID(data-value)───────────────────
└─RESCLASS(data-value)──RESIDLENGTH(data-value)─┘
──┬──────────────────┬──┬────────────┬──┬──────────────┬──┬───────────────┬──┬─────────────┬──"
└─LOGMESSAGE(cvda)─┘ └─READ(cvda)─┘ └─UPDATE(cvda)─┘ └─CONTROL(cvda)─┘ └─ALTER(cvda)─┘
Conditions:
INVREQ, LENGERR, NOTFND, QIDERR

QUERY SECURITY allows the application to determine If the ESM is RACF, the class can be CICS-supplied or
| whether the user has access to resources defined in the user-defined. RESCLASS enables you to define more
external security manager (ESM). These resources can be: narrowly the authorization to be queried; for example,
you can query at the record or field level.
In CICS resource classes
In user-defined resource classes. | The responses returned by the command reflect the
| definition of the RESID resource as defined in the
| The user in this context is the user invoking the transaction | specified RESCLASS.
that contains the QUERY SECURITY command.
RESID(data-value)
| For more information on the use of the QUERY SECURITY specifies the name of the CICS or user-defined resource
| command, see the CICS/ESA CICS-RACF Security Guide. that you want to query the users access to. The value is
a character string (1-12 characters for a CICS resource,
and 1-246 characters for a user-defined resource,
QUERY SECURITY options
# Apar PQ18509
ALTER(cvda)
enables you to query whether the user has ALTER # Documentation for Apar PQ18509 added 28/08/98
authority for the named resource. The cvda values
returned by CICS are ALTERABLE and # unless you are using the COBOL3 or OOCOBOL
NOTALTERABLE. # translator option in which case the maximum length is
# 160 characters).
CONTROL(cvda)
enables you to query whether the user has CONTROL | Note that the actual resource checked depends on
authority for the named resource. The cvda values | whether RESCLASS or RESTYPE is specified in the
returned by CICS are CTRLABLE and NOTCTRLABLE. | command and whether prefixing is active
| (SECPRFX=YES specified in the System Initialization
LOGMESSAGE(cvda) | Table).
enables you to inhibit security violation messages. The
| If RESCLASS is specified, the resource checked is
values passed to CICS are LOG (the default value), or,
| always the actual RESID data-value, whether or not
to inhibit messages, NOLOG.
| prefixing is on or off. IF RESTYPE is specified and
READ(cvda) | SECPRFX=NO, the resource checked is the RESID
enables you to query whether the user has READ | data-value as specified, however if SECPRFX=YES, the
authority for the named resource. The cvda values | resource checked is the RESID data-value prefixed with
returned by CICS are READABLE and NOTREADABLE. | the Region USERID.
READ access authority usually permits nondestructive
RESIDLENGTH(data-value)
use of a resource as, for example, in the case of READ
specifies the length, as a fullword binary, of the resource
and INQUIRE commands.
identifier in RESID. You only use this parameter when
RESCLASS(data-value) specifying the RESCLASS option.
| specifies an 8-character field identifying the name of a
RESTYPE(data-value)
| valid resource class, that could be non-CICS, in the
specifies the type of resource (1–12 characters) you
| ESM. The class name identified by RESCLASS is
want to query the user’s access to.
treated literally with no translation.

182 CICS/ESA Application Programming Reference

QUERY SECURITY

| The responses returned by the command reflect the The value you specify for RESTYPE must be one of the
| results that would be obtained if an actual attempt was following resource types:
| made to access the specified CICS resource. FILE
JOURNALNUM
PROGRAM
PSB
SPCOMMAND1
TDQUEUE
TRANSACTION
TRANSATTACH
TSQUEUE
1 See CICS/ESA CICS-RACF Security Guide

Apar 61283
Documentation for Apar 61283 added 13 Oct 1994
(TUCKER)

With dynamic transaction routing, it is not necessary to

install transaction definitions in terminal owning regions.
A QUERY SECURITY command with a RESTYPE of
TRANSATTACH returns the NOTFND condition if the
transaction is not installed. Programmers, however,
should be aware that the transaction may be routed
dynamically.

UPDATE(cvda)
enables you to query whether the user has UPDATE
authority for the named resource. The cvda values
returned by CICS are UPDATABLE and
NOTUPDATABLE. UPDATE access authority usually
permits destructive use of a resource as, for example, in
the case of WRITE, DELETE, or UPDATE commands.

QUERY SECURITY conditions

INVREQ
occurs in any of the following circumstances:

The cvda value is not valid for the LOGMESSAGE

(RESP2=7)
| The RESID is invalid or filled with blanks
| (RESP2=9)
| The external security manager (ESM) is inactive or
| not present (RESP2=10).

| Default action: terminate the task abnormally.

LENGERR
occurs if the RESIDLENGTH value is not valid, that is,
not in the range 1 through 246 (RESP2=6).
| Default action: terminate the task abnormally.

NOTFND
occurs in any of the following circumstances:

The RESID is not valid (RESP2=1)

The RESTYPE is not valid (RESP2=2)
The RESID value for RESTYPE (SPCOMMAND)
not valid (RESP2=3)

Chapter 1. Commands 183

QUERY SECURITY

The RESCLASS is not defined to the external

security manager (ESM) (RESP2=5)
# The resource is not protected (RESP2=8). This is
# only returned when QUERY SECURITY is used with
# the RESCLASS option (and never occurs with
# RESTYPE).
Possible causes include:
– RESCLASS not active
– No profile found
– ESM not active.

| Default action: terminate the task abnormally.

QIDERR
occurs if an indirect queue name associated with the
given RESID is not found (RESP2=1).
| Default action: terminate the task abnormally.

184 CICS/ESA Application Programming Reference

READ

Function
Read a record from a file.

Command syntax

──READ──FILE(filename)──┬───────────────────────────────┬──┬─INTO(data-area)─┬──┬───────────────────┬────
└─UPDATE──┬───────────────────┬─┘ └─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘
| └─TOKEN(data-value)─┘
──RIDFLD(data-area)──┬────────────────────────────────────┬──┬───────────────────┬──┬────────┬────────────
└─KEYLENGTH(data-value)──┬─────────┬─┘ └─SYSID(systemname)─┘ ├─RBA────┤
└─GENERIC─┘ ├─RRN────┤
├─DEBKEY─┤
└─DEBREC─┘
┌─EQUAL─┐
──┼───────┼──"
└─GTEQ──┘
Conditions:
| DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING,
NOTAUTH, NOTFND, NOTOPEN, SYSIDERR

READ reads a record from a file on a local or a remote The following example shows you how to read a record for
system. update from a VSAM file using a generic key and specifying
a greater-or-equal key search.
For both UPDATE and non-UPDATE commands, you must
EXEC CICS READ
identify the record to be retrieved by the record identification
INTO(RECORD)
field specified in the RIDFLD option. Immediately upon LENGTH(RECLEN)
completion of a READ UPDATE command, the RIDFLD data FILE('MASTVSAM')
area is available for reuse by the application program. RIDFLD(ACCTNO)
KEYLENGTH(4)
When this command reads a CICS-maintained data table, a GENERIC
READ request with UPDATE or RBA is always satisfied by a GTEQ
call to VSAM. For a non-UPDATE key READ, an attempt is UPDATE
first made to satisfy the request from the in-memory table. If
the record is not found, a call is made to VSAM unless it is
known that the record is not in the same data set either. READ options
See the SDTG for more detail. DEBKEY (blocked BDAM)
specifies that deblocking is to occur by key. If neither
A full key direct read that is neither a generic read nor a
DEBREC nor DEBKEY is specified, deblocking does not
READ UPDATE, is satisfied by a reference to the data table.
occur.
If the record is not found in the table, the source data set is
accessed, unless the table is known to be complete, that is, DEBREC (blocked BDAM)
all records in the source are also present in the table (which specifies that deblocking is to occur by relative record
is the case if loading is finished and none has been rejected (relative to zero). If neither DEBREC nor DEBKEY is
by a user exit). The details of the command for a specified, deblocking does not occur.
CICS-maintained table are the same as for a VSAM KSDS.
EQUAL (VSAM KSDS, paths and data tables)
| When this command reads a user-maintained data table, specifies that the search is satisfied only by a record
| only the data table is accessed once loading is complete; the having the same key (complete or generic) as that
| VSAM file is not changed in any way. specified in the RIDFLD option.

The following example shows you how to read a record from FILE(filename)
a file named MASTER into a specified data area: specifies the of the file to be accessed.
EXEC CICS READ If SYSID is specified, the data set to which this file refers
INTO(RECORD) is assumed to be on a remote system irrespective of
FILE('MASTER') whether the name is defined in the FCT. Otherwise, the
RIDFLD(ACCTNO)

Chapter 1. Commands 185

READ

FCT entry is used to find out whether the data set is on the application program is not large enough, storage
a local or a remote system. is overlaid beyond the target area.

GENERIC (VSAM KSDS, paths and data tables) When reading into a target data area longer than the
specifies that the search key is a generic key whose record being read, the contents of the target data area,
length is specified in the KEYLENGTH option. The from the end of the retrieved record to the end of the
search for a record is satisfied when a record is found target data area, are unpredictable.
that has the same starting characters (generic key) as
If you specify the INTO option, the LENGTH argument
those specified.
must be a data area that specifies the largest record the
For UMTs, GENERIC cannot be specified with UPDATE. program accepts. If the retrieved record is longer than
the value specified in the LENGTH option, the record is
GTEQ (VSAM KSDS, paths and data tables)
truncated to the specified value and the LENGERR
specifies that, if the search for a record having the same
condition occurs. In this case, the LENGTH data area is
key (complete or generic) as that specified in the
set to the length of the record prior to truncation.
RIDFLD option is unsuccessful, the first record having a
greater key is retrieved. If you specify the SET option, the LENGTH option need
not be specified but, if it is, the argument must be a data
For UMTs, GENERIC cannot be specified with UPDATE.
area.
INTO(data-area)
# RBA (VSAM ESDS, KSDS, or CMT)
specifies the data area into which the record retrieved
# (base data sets only, not paths) specifies that the record
from the data set is to be written.
# identification field specified in the RIDFLD option
KEYLENGTH(data-value) # contains a relative byte address. This option should only
specifies the length (halfword binary) of the key that has # be used when reading records from an ESDS base or
been specified in the RIDFLD option, except when RBA # when reading from a KSDS base and using relative byte
or RRN is specified, in which case KEYLENGTH is not addresses instead of keys to identify the records.
valid. This option must be specified if GENERIC is | You cannot use RBA for user-maintained data tables.
specified, and it can be specified whenever a key is
specified. However, if the length specified is different RIDFLD(data-area)
from the length defined for the data set and the # specifies the record identification field. When combined
operation is not generic, the INVREQ condition occurs. # with RBA or RRN this is a 4-character field. The
contents can be a key, a relative byte address, or
The INVREQ condition also occurs if GENERIC is
relative record number (for VSAM data sets), or a block
specified and the KEYLENGTH is not less than that
reference, a physical key, and a deblocking argument
specified in the VSAM definition.
(for BDAM data sets). For a relative byte address or a
If KEYLENGTH(0) is used with the object of reading the relative record number, the format of this field must be
first record in the data set, the GTEQ option must also fullword binary. For a relative byte address, the RIDFLD
be specified. If EQUAL is specified either explicitly or by can be greater than or equal to zero. For a relative
default with KEYLENGTH(0), the results of the READ record number, the RIDFLD can be greater than or
are unpredictable. equal to 1.

LENGTH(data-area) | Immediately upon completion of the command, the

specifies the length, as a halfword binary value, of the | RIDFLD data area is available for reuse by the
data area where the record is to be put. On completion | application program, even if UPDATE was specified.
of the READ command, the LENGTH parameter Make sure that the variable specified by RIDFLD is not
contains the actual length of the record. shorter than the KEYLENGTH specified in this command
| LENGTH must be specified with the INTO option on or, if KEYLENGTH is not specified, the key length of the
READ commands involving variable-length records. It file you are reading; otherwise, the results are
need not be specified for fixed-length records, but its unpredictable.
inclusion is recommended because:
RRN (VSAM RRDS)
It causes a check to be made that the record being specifies that the record identification field specified in
read is not too long for the available data area the RIDFLD option contains a relative record number.
This option should only be used with files referencing
When reading fixed-length records into an area
relative record data sets.
longer than the record being accessed, the
LENGERR condition is raised for VS COBOL II, C, SET(ptr-ref)
PL/I, and assembler-language applications if the indicates that CICS is to supply a buffer where the
LENGTH option is not specified. If the length record is read, and specifies the pointer reference that is
specified exceeds the file record length, CICS uses to contain the address of the retrieved record.
the longer length for the move. If the target area in

186 CICS/ESA Application Programming Reference

READ

In assembler language, if the DUPKEY condition occurs, It has been disabled by a SET FILE or a CEMT
the specified register has not been set, but can be SET FILE command.
loaded from DFHEITP1.
Default action: terminate the task abnormally.
The pointer reference is valid until the next READ
command for the same file or until completion of a DUPKEY (VSAM)
corresponding REWRITE, DELETE, or UNLOCK occurs if a record is retrieved by way of an alternate
command, or a SYNCPOINT in the case of READ index with the NONUNIQUEKEY attribute, and another
UPDATE SET. If you want to retain the data within the alternate index record with the same key follows
field addressed by the pointer, it should be moved to (RESP2=140).
your own area. In assembler language, if the SET option is being used,
If DATALOCATION(ANY) is associated with the the specified register has not been set, but can be
application program, the address of the data can be loaded from DFHEITP1.
above or below the 16MB line. Default action: terminate the task abnormally.
If DATALOCATION(BELOW) is associated with the
FILENOTFOUND
application program, the address of the data is below the
occurs if a file name referred to in the FILE option
16MB line.
cannot be found in the FCT (RESP2=1).
If TASKDATAKEY (USER) is specified for the executing
Default action: terminate the task abnormally.
transaction, the data returned is in a user-key; otherwise
it is in a CICS-key. ILLOGIC (VSAM)
occurs if a VSAM error occurs that does not fall within
If SET is not specified, LENGTH must either be specified
one of the other CICS response categories
explicitly or must be capable of being defaulted from the
(RESP2=110).
INTO option using the length attribute reference in
assembler language, or STG and CSTG in PL/I. # (See EIBRCODE in the EXEC interface block; refer to
LENGTH must be specified explicitly in OS/VS COBOL Appendix A, “EXEC interface block” on page 343 for
and C. details.)

SYSID(systemname) | For user-maintained data tables, this condition occurs

specifies the name of the system the request is directed | only for a non-UPDATE READ during loading when
to. | CICS has attempted to retrieve the record from the
| source data set.
If you specify SYSID, and omit both RBA and RRN, you
must also specify LENGTH and KEYLENGTH; they Default action: terminate the task abnormally.
cannot be found in the FCT.
INVREQ
| TOKEN(data-value) occurs in any of the following situations:
# specifies as a fullword binary value a unique request
READ is not allowed according to the file entry
| identifier for a READ, used to control multiple UPDATE
specification in the FCT (RESP2=20).
| operations on a data set. This is an output value
| provided by file control to the requesting task. A READ command with the UPDATE option is
issued to a file where update operations are not
UPDATE allowed according to the file entry specification in
specifies that the record is to be obtained for updating or the FCT (RESP2=20).
| (for VSAM and user-maintained data tables) deletion. If
The KEYLENGTH and GENERIC options are
| this option is omitted, a read-only operation is assumed.
specified, and the length specified in the
| UPDATE guarantees read integrity. KEYLENGTH option is greater than or equal to the
| You cannot use UPDATE for user-maintained data length of a full key (RESP2=25).
| tables if you also have either GENERIC or GTEQ. The KEYLENGTH option is specified (but the
GENERIC option is not specified), and the specified
READ conditions length does not equal the length defined for the data
set to which this file refers (RESP2=26).
Note: RESP2 values are not set for files that are on remote
systems. Following a READ UPDATE command for a file,
another READ UPDATE command is issued for a
DISABLED file referencing the same data set before exclusive
occurs if a file is disabled (RESP2=50). A file may be control is released by a REWRITE, UNLOCK, or
disabled because: DELETE command (RESP2=28).
It was initially defined as disabled and has not since A BDAM key conversion error occurred
been enabled (RESP2=40).

Chapter 1. Commands 187

READ

The KEYLENGTH and GENERIC options are NOTAUTH

specified, and the length specified in the occurs when a resource security check has failed on
KEYLENGTH option is less than or equal to zero FILE(filename) (RESP2=101).
(RESP2=42).
Default action: terminate the task abnormally.
| The command does not conform to the format of
NOTFND
| READ for a user-maintained data table; for example
occurs if an attempt to retrieve a record based on the
| if GTEQ is specified with UPDATE (RESP2=44).
search argument provided is unsuccessful (RESP2=80).
| An attempt is made to function-ship an UPDATE
| For user-maintained data tables, this condition occurs if
| request which includes a TOKEN keyword
| an attempt to read a record is unsuccessful because
| (RESP2=48).
| there is no entry with the specified key in the data table
Default action: terminate the task abnormally. | (RESP2=80). This does not mean that there is no such
| record in the source data set; it may be that such a
IOERR
| record is present but was either rejected during initial
occurs if there is an I/O error during the READ operation
| loading by the user exit XDTRD, or was subsequently
(RESP2=120). An I/O error is any unusual event that is
| deleted from the user-maintained data table.
not covered by a CICS condition.
Default action: terminate the task abnormally.
For VSAM files, IOERR normally indicates a hardware
error. NOTOPEN
occurs in any of the following situations (RESP2=60):
| For user-maintained data tables, this condition occurs
| only for a non-UPDATE READ during loading when The requested file is CLOSED and UNENABLED.
| CICS has attempted to retrieve the record from the The CLOSED, UNENABLED state is reached after a
| source data set. CLOSE request has been received against an
(Further information is available in the EXEC interface OPEN ENABLED file and the file is no longer in
block; refer to Appendix A, “EXEC interface block” on use. This state can also be specified as the initial
page 343 for details.) state by means of the FILSTAT parameter of the file
control table TYPE=FILE, or by defining a file using
Default action: terminate the task abnormally.
the RDO options STATUS=UNENABLED and
ISCINVREQ OPENTIME=FIRSTREF.
occurs when the remote system indicates a failure that The requested file is OPEN and in use by other
does not correspond to a known condition (RESP2=70). transactions, but a CLOSE request against the file
Default action: terminate the task abnormally. has been received.

LENGERR This condition does not occur if the request is made to

occurs in any of the following situations: either a CLOSED, ENABLED file or to a CLOSED,
DISABLED file. In the first case, the file is opened as
Neither the LENGTH option nor the SET option is part of executing the request. In the second case, the
specified on a READ command for a file with DISABLED condition occurs.
variable-length records or for a BDAM file with
Default action: terminate the task abnormally.
variable-length or undefined-format records
(RESP2=10). SYSIDERR
The length of a record read with the INTO option | occurs when the SYSID option specifies a name that is
specified exceeds the value specified in the | neither the local system nor a remote system (made
LENGTH option; the record is truncated, and the | known to CICS by defining a CONNECTION).
data area supplied in the LENGTH option is set to SYSIDERR also occurs when the link to the remote
the actual length of the record (RESP2=11). system is closed (RESP2=130).

An incorrect length is specified for a file with Default action: terminate the task abnormally.
fixed-length records (RESP2=13).

Default action: terminate the task abnormally.

188 CICS/ESA Application Programming Reference

READNEXT

Function
Read next record during a browse of a file.

Command syntax

──READNEXT──FILE(filename)──┬─INTO(data-area)─┬──┬───────────────────┬──RIDFLD(data-area)────────────────
└─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘
──┬───────────────────────┬──┬───────────────────┬──┬───────────────────┬──┬─────┬──"
└─KEYLENGTH(data-value)─┘ └─REQID(data-value)─┘ └─SYSID(systemname)─┘ ├─RBA─┤
└─RRN─┘
Conditions:
DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, NOTFND,
SYSIDERR

READNEXT can be used repeatedly to read records in READNEXT options

sequential order from a file on a local or a remote system.
Such a series of sequential read commands is known as a FILE(filename)
browse of the file. A browse can also consist of a sequence specifies the of the file to be browsed.
of READNEXT and READPREV commands in any order. A If SYSID is specified, the data set to which this file refers
browse must be initiated with the STARTBR command, to is assumed to be on a remote system irrespective of
identify the starting point of the browse, and terminated with whether the name is defined in the FCT. Otherwise, the
the ENDBR command. FCT entry is used to find out whether the data set is on
a local or a remote system.
You must provide, in the RIDFLD option, a data area that is
sufficiently large to contain a complete identifier (full key, INTO(data-area)
RBA, or RRN) of records in the file. This data area can be specifies the data area into which the record retrieved
used both as an output and as an input parameter. from the data set is to be written.

It is used as an output parameter when CICS, on completion KEYLENGTH(data-value)

of each READNEXT command, places the complete identifier specifies the length (halfword binary) of the key that has
of the record just retrieved into the RIDFLD data area. CICS been specified in the RIDFLD option, except when RBA
then holds this identifier to mark the point from which the or RRN is specified, in which case KEYLENGTH is not
subsequent READNEXT is to continue. valid.
If the browse was started without the GENERIC option
Except for BDAM, it may also be used as an input (that is a full key browse) and if the length specified is
parameter. Modifying the RIDFLD before issuing the next different from the length defined for the data set, the
READNEXT command causes that command to reposition INVREQ condition occurs.
the browse to the new identifier, from which it continues in
the usual way. If the browse was started with the GENERIC If the browse was started with the GENERIC option (that
option, the modified RIDFLD must be generic. If the browse is, a generic key browse), and if the length specified is
was started with the GTEQ option, the next record returned greater than the length specified for the data set, the
is the first record in the data set with a key greater than or INVREQ condition occurs.
equal to the modified RIDFLD. If GTEQ and GENERIC were specified on the most
recent STARTBR or RESETBR command, issuing
| A READNEXT command following a READPREV, or a READNEXT with KEYLENGTH(0) specified repositions
| STARTBR or RESETBR that specified a ‘lost’ key value, is the BROWSE at the start of the file. If EQUAL had been
| treated as though the RIDFLD value has been modified, and specified, the effect of READNEXT KEYLENGTH(0)
| results in a reposition (as above). would be unpredictable.
For a generic browse, CICS maintains a current key
length for the browse. The current key length is
initialized to be the value specified as KEYLENGTH on
the STARTBR command.
The current key length may be modified by specifying
KEYLENGTH on a READNEXT or RESETBR command.

Chapter 1. Commands 189

READNEXT

If the current key length is changed, this causes the from the end of the retrieved record to the end of the
browse to be repositioned. The browse is repositioned target data area, are unpredictable.
to the key whose initial characters match the value
If you specify the INTO option, the LENGTH argument
specified in the RIDFLD for the current key length.
must be a data area that specifies the largest record the
The current key length is zero after a request that program accepts. If the retrieved record is longer than
specifies KEYLENGTH(0). the value specified in the LENGTH option, the record is
truncated to the specified value and the LENGERR
IF KEYLENGTH is omitted on a READNEXT command,
condition occurs. In this case, the LENGTH data area is
the current key length remains the same and the browse
set to the length of the record prior to truncation.
continues without repositioning.
If you specify the SET option, the LENGTH option need
If KEYLENGTH is specified on a READNEXT command
not be specified but, if it is, the argument must be a data
and is equal to the current key length, this is treated as
area.
being no change and the browse is not repositioned.
The one exception to this is when KEYLENGTH(0) is Note that a file control command issued against a
specified, which always causes the browse to be variable-length record in a file defined on the local CICS
repositioned to the beginning of the file. system fails with a LENGERR condition if a length is not
specified. However, if the same command is issued
KEYLENGTH can be specified during a generic browse
against a file defined on a remote system, the command
with a value equal to the full key length. This does not
does not fail. The transformer which passes CICS
cause the current key length to change and the browse
commands from one CICS region to another has to pass
is not repositioned. The ability to specify the full key
a default value for the length argument if a value is not
length during a generic browse is provided to allow
specified. This is because, if the file is remote, the
requests that specify SYSID to be able to tell the
transformer cannot identify the record as fixed or
function-shipping transformers how long the key is, so
variable, and it is valid not to pass a length when issuing
that the transformers can ship the key to the file-owning
a request against a fixed-length record.
region.
A browse can be repositioned by modifying the RIDFLD # RBA (VSAM ESDS, KSDS, or CMT)
data area. A generic browse is repositioned only if the # (base data sets only, not paths)
modification to RIDFLD changes the part of RIDFLD specifies that the record identification field specified in
corresponding to the current key length. A consequence the RIDFLD option contains a relative byte address.
of this is that the browse can not be repositioned by This option must be specified when the STARTBR or
modifying the RIDFLD data area if the current key length RESETBR command specified the RBA option.
is zero.
| You cannot use RBA for user-maintained data tables.
LENGTH(data-area)
REQID(data-value)
specifies the length, as a halfword binary value, of the
specifies as a halfword binary value a unique request
record to be retrieved. On completion of a retrieval
identifier for a browse, used to control multiple browse
operation, the LENGTH parameter contains the actual
operations on a data set. If this option is not specified, a
length of the retrieved record.
default value of zero is assumed.
This option must be specified if SYSID is specified. It
must also be specified with the INTO option on RIDFLD(data-area)
commands involving variable-length records. It need not # specifies the record identification field. When combined
be specified for fixed-length records, but its inclusion is # with RBA or RRN this is a 4-character field. The
recommended because: contents can be a key, a relative byte address, or
relative record number (for VSAM data sets), or a block
It causes a check to be made that the record being reference, physical key, and deblocking argument (for
read is not too long for the available data area. BDAM data sets). For a relative byte address or a
When browsing fixed-length records into an area relative record number, the format of this field must be
longer than the record being accessed, the fullword binary. For a relative byte address, the RIDFLD
LENGERR condition is raised for can be greater than or equal to zero. For a relative
assembler-language, VS COBOL II, and PL/I record number, the RIDFLD can be greater than or
applications if the LENGTH option is not specified. equal to 1.
If the length specified exceeds the file record length, Even if the browse is generic, this field should always be
CICS uses the longer length for the move. If the large enough to accommodate the complete record
target area in the application program is not large identifier. This is because, on completion of the
enough, storage is overlaid beyond the target area. READNEXT command, the field is updated by CICS with
the complete identification of the record retrieved.
When browsing into a target data area longer than the
record being read, the contents of the target data area,

190 CICS/ESA Application Programming Reference

READNEXT

RRN (VSAM RRDS) Default action: terminate the task abnormally.

specifies that the record identification field specified in
ILLOGIC (VSAM)
the RIDFLD option contains a relative record number.
occurs if a VSAM error occurs that does not fall within
SET(ptr-ref) one of the other CICS response categories
specifies the pointer reference that is to be set to the (RESP2=110).
address of the retrieved record.
# (See EIBRCODE in the EXEC interface block; refer to
In assembler language, if the DUPKEY condition occurs, Appendix A, “EXEC interface block” on page 343 for
the register specified will not have been set, but can be details.)
loaded from DFHEITP1.
Default action: terminate the task abnormally.
The pointer reference is valid until the next READNEXT
INVREQ
or READPREV command specifying SET for the same
occurs in any of the following situations:
file. The pointer is no longer valid after an ENDBR or
SYNCPOINT command. If you want to retain the data The KEYLENGTH option is specified for a generic
within the field addressed by the pointer, you must move browse (that is one where GENERIC was specified
it to your own area. on the STARTBR or the last RESETBR) and the
If DATALOCATION(ANY) is associated with the value of KEYLENGTH was greater than the full key
application program, the address of the data can be length (RESP2=25).
above or below the 16MB line. The KEYLENGTH option is specified for a
If DATALOCATION(BELOW) is associated with the nongeneric browse, and the specified length does
application program, the address returned in the SET not equal the length defined for the data set to
pointer is below the 16MB line. which this file refers (RESP2=26).

If TASKDATAKEY(USER) is specified for the running The REQID, if any, does not match that of any
task, the data returned is in a user-key; otherwise it is in successful STARTBR command (RESP2=34).
a CICS-key. The type of record identification (for example, key or
relative byte address) used to access a data set
SYSID(systemname)
during the browse is changed by the READNEXT
specifies the name of the system to which the request is
command (RESP2=37).
directed.
The KEYLENGTH option is specified for a generic
If you specify SYSID, and omit both RBA and RRN, you
browse (that is one where GENERIC was specified
must also specify LENGTH and KEYLENGTH; they
on the STARTBR or the last RESETBR) and the
cannot be found in the FCT.
value of KEYLENGTH was less than zero
(RESP2=42).
READNEXT conditions
Default action: terminate the task abnormally.
Note: RESP2 values are not set for files that are on remote
systems. IOERR
occurs if there is an I/O error during the READNEXT
DUPKEY (VSAM) command (RESP2=120). An I/O error is any unusual
occurs if a record is retrieved by way of an alternate event that is not covered by a CICS condition.
index with the NONUNIQUEKEY attribute, and another
alternate index record with the same key follows For VSAM files, IOERR normally indicates a hardware
(RESP2=140). It does not occur as a result of a error.
READNEXT command that reads the last of the records (Further information is available in the EXEC interface
having the nonunique key. block; refer to Appendix A, “EXEC interface block” on
In assembler language, if the SET option is being used, page 343 for details.)
the register specified will not have been set, but can be Default action: terminate the task abnormally.
loaded from DFHEITP1.
ISCINVREQ
Default action: terminate the task abnormally. occurs when the remote system indicates a failure that
ENDFILE does not correspond to a known condition (RESP2=70).
occurs if an end-of-file condition is detected during the Default action: terminate the task abnormally.
browse (RESP2=90).
Default action: terminate the task abnormally.

FILENOTFOUND
occurs if a file name referred to in the FILE option
cannot be found in the FCT (RESP2=1).

Chapter 1. Commands 191

READNEXT

LENGERR
occurs in any of the following situations:

Neither the LENGTH nor the SET option is specified

for a file with variable-length records or a BDAM file
with undefined-format records (RESP2=10).
The length of the record read with the INTO option
specified exceeds the value specified in the
LENGTH option; the record is truncated, and the
data area supplied in the LENGTH option is set to
the actual length of the record (RESP2=11).
An incorrect length is specified for a file with
fixed-length records (RESP2=13).

Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.

NOTFND
occurs if an attempt to retrieve a record based on the
search argument provided is unsuccessful (RESP2=80).
This may occur if the READNEXT command immediately
follows a STARTBR command that specified the key of
the last record in the data set (a complete key of
X'FF's).
Default action: terminate the task abnormally.

192 CICS/ESA Application Programming Reference

READPREV

Function
Read previous record during a file browse; VSAM and data tables only.

Command syntax

──READPREV──FILE(filename)──┬─INTO(data-area)─┬──┬───────────────────┬──RIDFLD(data-area)────────────────
└─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘
──┬───────────────────────┬──┬───────────────────┬──┬───────────────────┬──┬─────┬──"
└─KEYLENGTH(data-value)─┘ └─REQID(data-value)─┘ └─SYSID(systemname)─┘ ├─RBA─┤
└─RRN─┘
Conditions:
DUPKEY, ENDFILE, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, NOTFND,
SYSIDERR

READPREV can be used repeatedly to read records in READPREV options

reverse sequential order from a VSAM file on a local or a
remote system. FILE(filename)
specifies the of the file being browsed.
Such a series of sequential read commands is known as a If SYSID is specified, the data set to which this file refers
browse of the file. A browse may also consist of a is assumed to be on a remote system irrespective of
sequence of READNEXT and READPREV commands in any whether the name is defined in the FCT. Otherwise, the
order. A browse must be initiated with the STARTBR FCT entry is used to find out whether the data set is on
command, to identify the start of the browse, and terminated a local or a remote system.
with the ENDBR command.
INTO(data-area)
You must provide, in the RIDFLD option, a data area that is specifies the data area into which the record retrieved
sufficiently large to contain a complete identifier (full key, from the data set is to be written.
RBA, or RRN) of records in the file. This data area is used
both as an output and as an input parameter. KEYLENGTH(data-value)
specifies the length (halfword binary) of the key that has
It is used as an output parameter when CICS, on completion been specified in the RIDFLD option, except when RBA
of each READPREV command, places the complete identifier or RRN is specified, in which case KEYLENGTH is not
of the record just retrieved into the RIDFLD data area. CICS valid. If the length specified is different from the length
then holds this identifier to mark the point from which the defined for the data set, the INVREQ condition occurs.
subsequent READPREV is to continue.
LENGTH(data-area)
It may also be used as an input parameter. Modifying the specifies the length, as a halfword binary value, of the
RIDFLD before issuing the next READPREV command record to be retrieved. On completion of a retrieval
causes that command to reposition the browse to the new operation, LENGTH contains the actual length of the
identifier, from which it continues in the usual way. The retrieved record.
modified record identifier must always be a full key, RBA, or This option must be specified if SYSID is specified. It
RRN. A generic key may not be specified, nor may a must also be specified with the INTO option on
browse that was started with the GENERIC option include a READPREV commands involving variable-length
READPREV command. records. It need not be specified for fixed-length
records, but its inclusion is recommended because:
If you include a READPREV command immediately following
a STARTBR command, your STARTBR command RIDFLD It causes a check to be made that the record being
must specify the key of a record that exists on the data set; read is not too long for the available data area.
otherwise the NOTFND condition will occur. When browsing fixed-length records into an area
longer than the record being accessed, the
A READPREV command following a READNEXT, or a
LENGERR condition is raised for VS COBOL II, C,
STARTBR or RESETBR that did not specify a ‘lost’ key
PL/I, and assembler-language applications if the
value, is treated as though the RIDFLD value had been
LENGTH option is not specified.
modified and results in a reposition (as above).

Chapter 1. Commands 193

READPREV

When reading fixed-length records into an area In assembler language, if the DUPKEY condition occurs,
longer than the record being accessed, the the specified register has not been set, but can be
LENGERR condition is raised for VS COBOL II, loaded from DFHEITP1.
PL/I, and assembler-language applications if the
The pointer reference is valid until the next READ
LENGTH option is not specified. If the length
command for the same file. If you want to retain the
specified exceeds the file record length, CICS uses
data within the field addressed by the pointer, it should
the longer length for the move. If the target area in
be moved to your own area.
the application program is not large enough, storage
is overlaid beyond the target area. If DATALOCATION(ANY) is associated with the
application program, the address returned in the SET
When browsing into a target data area longer than the pointer can be above or below the 16MB line.
record being read, the contents of the target data area,
If DATALOCATION(BELOW) is associated with the
from the end of the retrieved record to the end of the
application program, and the data resides above the
target data area, are unpredictable.
16MB line, the address returned in the SET pointer is
If you specify the INTO option, LENGTH specifies the below the 16MB line.
largest record the program accepts. If the retrieved
If TASKDATAKEY(USER) is specified for the running
record is longer than the value specified in the LENGTH
task, the data returned is in a user-key; otherwise it is in
option, the record is truncated to the specified value and
a CICS-key.
the LENGERR condition occurs. In this case, the
LENGTH data area is set to the length of the record SYSID(systemname)
prior to truncation. specifies the name of the system to which the request is
If you specify the SET option, LENGTH need not be directed.
specified. If you specify SYSID, and omit both RBA and RRN, you
must also specify LENGTH and KEYLENGTH.
# RBA (VSAM ESDS, KSDS, or CMT)
# (base data sets only, not paths)
specifies that the record identification field specified in READPREV conditions
the RIDFLD option contains a relative byte address.
Note: RESP2 values are not set for files that are on remote
You must specify this option after any STARTBR or
systems.
RESETBR command that specified the RBA option.
| You cannot use RBA for user-maintained data tables. DUPKEY
occurs if a record is retrieved by way of an alternate
REQID(data-value) index with the NONUNIQUEKEY attribute, and another
specifies as a halfword binary value a unique request alternate index record with the same key exists
identifier for a browse, used to control multiple browse (RESP2=140).
operations on a data set. If this option is not specified, a
In assembler language, if the SET option is being used,
default value of zero is assumed.
the specified register has not been set, but can be
RIDFLD(data-area) loaded from DFHEITP1.
# specifies the record identification field. When combined Default action: terminate the task abnormally.
# with RBA or RRN this is a 4-character field. The
contents can be a key, a relative byte address, or ENDFILE
relative record number. For a relative byte address or a occurs if an end-of-file condition is detected during a
relative record number, the format of this field must be browse (RESP2=90).
fullword binary. For a relative byte address, the RIDFLD Default action: terminate the task abnormally.
can be greater than or equal to zero. For a relative
record number, the RIDFLD can be greater than or FILENOTFOUND
equal to 1. occurs if a file name referred to in the FILE option
cannot be found in the FCT (RESP2=1).
On completion of the READPREV command, this field is
updated by CICS with the complete identification of the Default action: terminate the task abnormally.
record retrieved.
ILLOGIC (VSAM)
RRN (VSAM RRDS) occurs if a VSAM error occurs that does not fall within
specifies that the record identification field specified in one of the other CICS response categories
the RIDFLD option contains a relative record number. (RESP2=110).

SET(ptr-ref) # (See EIBRCODE in the EXEC interface block; refer to

specifies the pointer reference that is to be set to the Appendix A, “EXEC interface block” on page 343 for
address of the retrieved record. details.)
Default action: terminate the task abnormally.

194 CICS/ESA Application Programming Reference

READPREV

INVREQ or RESETBR command that specified GTEQ and the

occurs in any of the following situations: key of a record that does not exist on the data set.

A READPREV command is issued for a file for Default action: terminate the task abnormally.
which the previous STARTBR or RESETBR
SYSIDERR
command has the GENERIC option (RESP2=24).
occurs when the SYSID option specifies a name that
The KEYLENGTH option is specified and the has not been defined to CICS as a remote system
specified length does not equal the length defined (defined by defining a CONNECTION). SYSIDERR also
for the data set for this file refers to (RESP2=26). occurs when the link to the remote system is closed
(RESP2=130).
The type of record identification (for example, key or
relative byte address) used to access a data set Default action: terminate the task abnormally.
during the browse is changed (RESP2=37).
A READPREV is issued for a BDAM file
(RESP2=39).
The REQID, if any, does not match that of any
successful STARTBR command (RESP2=41).

Default action: terminate the task abnormally.

IOERR
occurs if there is an I/O error during the browse
(RESP2=120). An I/O error is any unusual event that is
not covered by a CICS condition.
For VSAM files, IOERR normally indicates a hardware
error. (Further information is available in the EXEC
interface block; refer to Appendix A, “EXEC interface
block” on page 343 for details.)
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition (RESP2=70).
Default action: terminate the task abnormally.

LENGERR
occurs in any of the following situations:

Neither the LENGTH nor the SET option is specified

for a file with variable-length records (RESP2=10).
The length of the record read with the INTO option
specified exceeds the value specified in the
LENGTH option; the record is truncated, and the
data area supplied in the LENGTH option is set to
the actual length of the record (RESP2=11).
An incorrect length is specified for a file with
fixed-length records (RESP2=13).

Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.

NOTFND
occurs if an attempt to retrieve a record based on the
search argument provided is unsuccessful (RESP2=80).
One place where this may occur is where the
READPREV command immediately follows a STARTBR

Chapter 1. Commands 195

READQ TD

Function
Read data from the transient data queue.

Command syntax

──READQ TD──QUEUE(name)──┬─INTO(data-area)─┬──┬───────────────────┬──┬───────────────────┬───────────────
└─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘ └─SYSID(systemname)─┘
──┬───────────┬──"
└─NOSUSPEND─┘
Conditions:
DISABLED, IOERR, INVREQ, ISCINVREQ, LENGERR, NOTAUTH, NOTOPEN, QBUSY, QIDERR, QZERO,
SYSIDERR

READQ TD reads transient data from a queue (after which READQ TD options
the record is no longer available).
INTO(data-area)
If you are using automatic transaction initiation (ATI) (see the specifies the user data area into which the data read
section on ATI in the CICS/ESA Application Programming from the transient data queue is to be placed.
# Guide for introductory information) your application should
LENGTH(data-area)
# test for the QZERO condition to ensure that termination of an
| specifies the length, as a halfword binary value, of the
automatically initiated task occurs only when the queue is
| record to be read.
empty.
If you specify the INTO option, LENGTH specifies the
The following example shows how to read a record from an maximum length of data that the program accepts. If the
intrapartition data set (queue), which in this case is the value specified is less than zero, zero is assumed. If the
control system message log (CSML), into a data area length of the data exceeds the value specified, the data
specified in the request: is truncated to that value and the LENGERR condition
EXEC CICS READQ TD occurs. On completion of the retrieval operation, the
QUEUE('CSML') data area is set to the original length of the data.
INTO(DATA)
LENGTH(LDATA) NOSUSPEND
| specifies that if the application program attempts to read
The following example shows how to read a record from an | from a queue that is already being used for output, the
extrapartition data set (queue) having fixed-length records | task is not suspended until the queue becomes
into a data area provided by CICS; the pointer reference | available. Instead, the QBUSY condition is raised.
specified by the SET option is set to the address of the This option only applies to intrapartition queues.
storage area reserved for the data record. It is assumed that
the record length is known. QUEUE(name)
specifies the symbolic name (1–4 alphanumeric
EXEC CICS READQ TD
QUEUE(EX1) characters) of the queue to be read from. The name
SET(PREF) must have been defined in the DCT.
| If SYSID is specified, the queue is assumed to be on a
If the READQ TD command attempts to access a record in a remote system irrespective of whether or not the name
logically recoverable intrapartition queue that is being written is defined as remote in the DCT. Otherwise the entry in
to, or deleted by, another task, and there are no more the DCT is used to find out whether the data set is on a
committed records, the command waits until the queue is no local or a remote system.
longer being used for output. If, however, the NOSUSPEND
option has been specified, the QBUSY condition is raised. SET(ptr-ref)
specifies a pointer reference that is to be set to the
address of the data read from the queue. CICS
acquires an area large enough to hold the record and
sets the pointer reference to the address of that area.
The area is retained until another transient data
command is executed. The pointer reference, unless

196 CICS/ESA Application Programming Reference

READQ TD

changed by other commands or statements, is valid until Default action: terminate the task abnormally.
the next READQ TD command or the end of task.
QBUSY
If DATALOCATION(ANY) is associated with the occurs if a READQ TD command attempts to access a
application program, the address of the data can be record in a logically recoverable intrapartition queue that
above or below the 16MB line. is being written to or is being deleted by another task,
If DATALOCATION(BELOW) is associated with the and there are no more committed records.
application program, and the data resides above the The NOSUSPEND option must be specified for this
16MB line, the data is copied below the 16MB line, and condition to be raised.
the address of this copy is returned.
This condition applies only to intrapartition queues.
If TASKDATAKEY(USER) is specified for the running
Default action: ignore the condition.
task, and storage protection is active, the data returned
is in a user-key. If TASKDATAKEY(CICS) is specified QIDERR
and storage protection is active, the data returned is in a occurs if the symbolic destination to be used with
CICS-key. READQ TD cannot be found.
SYSID(systemname) — remote systems only Default action: terminate the task abnormally.
specifies the name (1–4 characters) of the system to
QZERO
which the request is directed.
occurs when the destination (queue) is empty or the end
of the queue has been reached.
READQ TD conditions Default action: terminate the task abnormally.
DISABLED
SYSIDERR
occurs when the queue has been disabled.
| occurs when the SYSID option specifies a name that is
Default action: terminate the task abnormally. | neither the local system nor a remote system (made
| known to CICS by defining a CONNECTION).
INVREQ
SYSIDERR also occurs when the link to the remote
occurs if READQ names an extrapartition queue that has
system is closed.
been opened for output. This condition cannot occur for
intrapartition queues. Default action: terminate the task abnormally.
Default action: terminate the task abnormally.

IOERR
occurs when an input/output error occurs and the data
record in error is skipped.
This condition occurs as long as the queue can be read;
a QZERO condition occurs when the queue cannot be
read.
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

LENGERR
occurs if READQ names an INTO area that cannot hold
all the data that is to be returned to the application. The
check is made after the XTDIN exit has been invoked.
Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
QUEUE(name).
Default action: terminate the task abnormally.

NOTOPEN
occurs if the destination is closed. This condition applies
to extrapartition queues only.

Chapter 1. Commands 197

READQ TS

Function
Read data from temporary storage queue.

Command syntax

──READQ TS──QUEUE(name)──┬─INTO(data-area)─┬──┬───────────────────┬──┬─────────────────────┬─────────────
└─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘ └─NUMITEMS(data-area)─┘
┌─NEXT─────────────┐
──┼──────────────────┼──┬───────────────────┬──"
└─ITEM(data-value)─┘ └─SYSID(systemname)─┘
Conditions:
INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOTAUTH, QIDERR, SYSIDERR

| Note for dynamic transaction routing

READQ TS retrieves data from a temporary storage queue in LENGTH(data-area)

main or auxiliary storage. | specifies the length, as a halfword binary value, of the
| record to be read.
The following example shows how to read the first (or only)
If you specify the INTO option,
record from a temporary storage queue into a data area
specified in the request; the LENGTH data area is given the
value of the length of the record.
EXEC CICS READQ TS
ITEM(1)
QUEUE(UNIQNAME)
INTO(DATA)
LENGTH(LDATA)

The following example shows how to read the next record

from a temporary storage queue into a data area provided by
CICS; the pointer reference specified by the SET option is
set to the address of the storage area reserved for the data
record, and the LENGTH data area is given the value of the
length of the record.
EXEC CICS READQ TS
QUEUE(DESCRQ)
SET(PREF)
LENGTH(LENG)
NEXT

READQ TS options
INTO(data-area)
specifies the data area into which the data is to be
written. The data area can be any variable, array, or
structure.

ITEM(data-value)
provides a halfword binary value that specifies the item
number of the logical record to be retrieved from the
queue.
READQ TS

NUMITEMS(data-area) This condition only applies to the INTO option and

specifies a halfword binary field into which CICS stores a cannot occur with SET.
number indicating how many items there are in the
Default action: terminate the task abnormally.
# queue. This only occurs if the command completes
# normally. NOTAUTH
occurs when a resource security check has failed on
QUEUE(name)
QUEUE(name).
specifies the symbolic name (1–8 characters) of the
queue to be read from. Default action: terminate the task abnormally.

SET(ptr-ref) QIDERR
specifies the pointer reference that is set to the address occurs when the queue specified cannot be found, either
of the retrieved data. The pointer reference, unless in main or in auxiliary storage.
changed by other commands or statements, is valid until Default action: terminate the task abnormally.
the next READQ TS command or the end of task.
If the application program is defined with
DATALOCATION(ANY), the address of the data can be
above or below the 16MB line. If the application
program is defined with DATALOCATION(BELOW), the
address of the data is below the 16MB line.
If TASKDATAKEY(USER) is specified for the running
task, and storage protection is active, the data returned
is in a user-key. If TASKDATAKEY(CICS) is specified
and storage protection is active, the data returned is in a
CICS-key.

SYSID(systemname) — remote systems only

specifies the name (1–4 characters) of the system to
which the request is directed.

READQ TS conditions
INVREQ
occurs when the queue was created by CICS internal
code.
Default action: terminate the task abnormally.

IOERR
occurs when there is an irrecoverable input/output error.
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

ITEMERR
occurs in any of the following situations:

The item number specified is invalid (that is, outside

the range of item numbers written to the queue).
An attempt is made to read beyond the end of the
queue using the NEXT (default) option.

Default action: terminate the task abnormally.

LENGERR
occurs when the length of the stored data is greater than
the value specified by the LENGTH option.

Chapter 1. Commands 199

READQ TS

200 CICS/ESA Application Programming Reference

RECEIVE (VTAM)

RECEIVE (VTAM default)

Function
Receive data from standard CICS terminal support (BTAM or TCAM) or from a task that is not attached to a terminal.

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬──"
| └─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
Conditions:
INVREQ, LENGERR, NOTALLOC

This form of the RECEIVE command is used by all CICS-supported terminals for which the other RECEIVE descriptions are
not appropriate.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (APPC)

Function
Receive data on an APPC mapped conversation.

Command syntax

──RECEIVE──┬──────────────┬──┬─INTO(data-area)─┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬─────
| └─CONVID(name)─┘ └─SET(ptr-ref)────┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤
| └─MAXFLENGTH(data-value)─┘
──┬────────────┬──┬─────────────┬──"
└─NOTRUNCATE─┘ └─STATE(cvda)─┘
Conditions:
EOC, INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

RECEIVE receives data from the conversation partner in an APPC mapped conversation.

Chapter 1. Commands 201

RECEIVE (VTAM)

RECEIVE (LUTYPE2/LUTYPE3)

Function
Receive data from a 3270-display logical unit (LUTYPE2) or a 3270-printer logical unit (LUTYPE3).

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬──────┬─────────
| └─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─ASIS─┘
| └─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
──┬────────┬──┬────────────┬──"
└─BUFFER─┘ └─NOTRUNCATE─┘
Conditions:
| EOC, INVREQ, LENGERR, TERMERR

RECEIVE receives data from the terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
| attention identifier (AID) (and BUFFER has not been specified), you can omit both the INTO and SET options.

RECEIVE (LUTYPE4)

Function
Receive data from an LUTYPE4 logical unit.

Command syntax

RECEIVE receives data from the terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

202 CICS/ESA Application Programming Reference

RECEIVE (VTAM)

RECEIVE (LUTYPE6.1)

Function
Receive data on an LUTYPE6.1 session.

Command syntax

──RECEIVE──┬───────────────┬──┬─INTO(data-area)─┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬────
| └─SESSION(name)─┘ └─SET(ptr-ref)────┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤
| └─MAXFLENGTH(data-value)─┘
──┬────────────┬──"
└─NOTRUNCATE─┘
Conditions:
EOC, INBFMH, INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

RECEIVE receives data from the conversation partner in an LUTYPE6.1 conversation.

RECEIVE (3270 logical)

Function
Receive data from a 3270 logical unit.

Command syntax

RECEIVE receives data from a terminal.

Chapter 1. Commands 203

RECEIVE (VTAM)

RECEIVE (3600 pipeline)

Function
Receive initial input data from a 3600 pipeline logical unit. Subsequent RECEIVEs for further input data are not allowed.

Command syntax

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (3600-3601)

Function
Receive data from a 3600 (3601) logical unit

Command syntax

RECEIVE receives data from the terminal. This form of RECEIVE also applies to the 3630 plant communication system.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

204 CICS/ESA Application Programming Reference

RECEIVE (VTAM)

RECEIVE (3600-3614)

Function
Receive data from a 3600 (3614) logical unit.

Command syntax

RECEIVE receives data from the terminal.

The data-stream and communication format used between a CICS application program and a 3614 is determined by the 3614.
The application program is therefore device dependent when handling 3614 communication.

For further information about designing 3614 application programs for CICS, refer to the CICS/OS/VS IBM 4700/3600/3630
Guide.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (3650)

Function
Receive data from 3650 logical units.

Command syntax

RECEIVE receives data from the terminal. This form of RECEIVE also applies to the following 3650 devices:
Interpreter logical unit
Host conversational (3270) logical unit
Host conversational (3653) logical unit
3650/3680 command processor logical unit.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

Chapter 1. Commands 205

RECEIVE (VTAM)

RECEIVE (3767)

Function
Receive data from a 3767 interactive logical unit.

Command syntax

RECEIVE receives data from the terminal. This form of RECEIVE also applies to the 3770 interactive logical unit.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (3770)

Function
Receive data from a 3770 batch logical unit.

Command syntax

RECEIVE receives data from the terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

206 CICS/ESA Application Programming Reference

RECEIVE (VTAM)

RECEIVE (3790 full-function or inquiry)

Function
Receive data from a 3790 full-function or inquiry logical unit.

Command syntax

RECEIVE receives data from the terminal. This form of RECEIVE also applies to the following devices:
3650/3680 full-function logical unit
3770 full-function logical unit.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

Chapter 1. Commands 207

RECEIVE (VTAM)

RECEIVE (VTAM) options If you specify the INTO option, but omit the
MAXLENGTH option, the argument must be a data area
ASIS that specifies the maximum length that the program
specifies that lowercase characters in the 3270 input accepts. If the value specified is less than zero, zero is
data stream are not translated to uppercase; this allows assumed.
the current task to receive a message containing both
If you specify the SET option, the argument must be a
uppercase and lowercase data.
data area. When the data has been received, the data
This option has no effect on the first RECEIVE area is set to the length of the data.
command of a transaction, because terminal control
performs a READ INITIAL and uses the terminal defaults MAXFLENGTH(data-value)
to translate the operation data. A fullword alternative to MAXLENGTH.

This option has no effect if the screen contains data MAXLENGTH(data-value)

prior to a transaction being initiated. This data is read specifies the maximum amount (halfword binary value)
and translated in preparation for the next task and the of data that CICS is to recover. If INTO is specified,
first RECEIVE command in that task retrieves the MAXLENGTH overrides the use of LENGTH as an input
translated data. to CICS. If SET is specified, MAXLENGTH provides a
way for the program to limit the amount of data it
Note: If you are using a katakana terminal, you might
receives at one time.
see some messages containing mixed English and
katakana characters. That is because katakana If the length of data exceeds the value specified and the
terminals cannot display mixed-case output. Uppercase NOTRUNCATE option is not present, the data is
characters in the data stream appear as uppercase truncated to that value and the LENGERR condition
English characters, but lowercase characters appear as occurs. The data area specified in the LENGTH option
katakana characters. If this happens, ask your system is set to the original length of data.
programmer to specify MSGCASE=UPPER in the If the length of data exceeds the value specified and the
system initialization parameters so that messages NOTRUNCATE option is present, CICS retains the
contain uppercase characters only. remaining data and uses it to satisfy subsequent
BUFFER RECEIVE commands. The data area specified in the
specifies that the contents of the 3270 buffer are to be LENGTH option is set to the length of data returned.
read, beginning at buffer location 1 and continuing until If this option is omitted, the value indicated in the
all contents of the buffer have been read. All character LENGTH option is assumed.
and attribute sequences (including nulls) appear in the
input data stream in the same order as they appear in NOTRUNCATE
the 3270 buffer. specifies that, when the data available exceeds the
length requested, the remaining data is not to be
CONVID(name) discarded but is to be retained for retrieval by
identifies the conversation to which the command subsequent RECEIVE commands.
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command SESSION(name)
in EIBRSRCE in the EIB, or the token representing the specifies the symbolic identifier (1–4 characters) of a
principal session (returned by a previously executed session TCTTE. This option specifies the alternate
ASSIGN command). facility to be used. If this option is omitted, the principal
facility for the task is used.
For compatibility with earlier releases, SESSION is
accepted as a synonym for CONVID. New programs SET(ptr-ref)
should use CONVID. specifies the pointer reference that is to be set to the
address of the data read from the logical unit or terminal,
If this option is omitted, the principal facility is assumed.
# or the partner transaction. The pointer reference is valid
FLENGTH(data-area) # until the next receive command or the end of task.
A fullword alternative to LENGTH. If DATALOCATION(ANY) is associated with the
INTO(data-area) application program, the address of the data can be
specifies the receiving field for the data read from the above or below the 16MB line.
logical unit or terminal, or the application target data If DATALOCATION(BELOW) is associated with the
area into which data is to be received from the application program, and the data resides above the
application program connected to the other end of the 16MB line, the data is copied below the 16MB line, and
current conversation. the address of this copy is returned.
LENGTH(data-area) If TASKDATAKEY(USER) is specified for the running
specifies the length, as a halfword binary value, of the task, and storage protection is active, the data returned
data received.

208 CICS/ESA Application Programming Reference

RECEIVE (VTAM)

is in a user-key. If TASKDATAKEY(CICS) is specified A distributed program link server application

and storage protection is active, the data returned is in a specified the function-shipping session (its principal
CICS-key. facility) on the CONVID option (RESP2=200).

STATE(cvda) Default action: terminate the task abnormally.

gets the state of the current conversation. The cvda
LENGERR
values returned by CICS are:
occurs if data is discarded by CICS because its length
ALLOCATED exceeds the maximum the program accepts and the
CONFFREE NOTRUNCATE option is not specified.
CONFRECEIVE
Default action: terminate the task abnormally.
CONFSEND
FREE NOTALLOC
PENDFREE occurs if the RECEIVE command is issued by a
PENDRECEIVE transaction that has been started as a nonterminal task
RECEIVE by the START command, or if the CONVID value or
ROLLBACK facility specified in the command does not relate to a
SEND conversation owned by the application.
SYNCFREE
Default action: terminate the task abnormally.
SYNCRECEIVE
SYNCSEND SIGNAL
occurs when an inbound SIGNAL data-flow control
command is received from a partner transaction.
RECEIVE (VTAM) conditions EIBSIG is always set when an inbound signal is
Some of the following conditions may occur in received.
combination with others. CICS checks for these Default action: ignore the condition.
conditions in the following order:
TERMERR
1. EODS occurs for a session-related or terminal-related error.
2. INBFMH Any action on that conversation other than a FREE
3. EOC. causes an ATCV abend.
If more than one occurs, only the first is passed to the A CANCEL TASK request by a user node error program
application program. EIBRCODE, however, is set to (NEP) may cause this condition if the task has an
indicate all the conditions that occurred. outstanding terminal control request active when the
node abnormal condition program handles the session
EOC
error.
occurs when a request/response unit (RU) is received
with end-of-chain-indicator set. Field EIBEOC also Default action: terminate the task abnormally with abend
indicates this condition. code ATNI.
Default action: ignore the condition.

EODS (interpreter logical unit only)

occurs when an end-of-data-set indicator is received.
Default action: terminate the task abnormally.

INBFMH
occurs if a request/response unit (RU) contains a
function management header (FMH). Field EIBFMH
contains this indicator and it should be used in
preference to INBFMH. The IGNORE CONDITION
command can be used to ignore the condition.
Default action: terminate the task abnormally.

INVREQ
occurs if:

The command is used on an APPC conversation

that is not using the EXEC CICS interface or that is
not a mapped conversation.

Chapter 1. Commands 209

RECEIVE (non-VTAM)

RECEIVE (non-VTAM default)

Function
Receive data from standard CICS terminal support (BTAM or TCAM) or from a task that is not attached to a terminal.

Command syntax

| This form of the RECEIVE command is used by all CICS-supported terminals for which the other RECEIVE descriptions are
| not appropriate.

If data is to be received, you must specify either the INTO or the SET option.
RECEIVE (non-VTAM)

RECEIVE (System/3)

Function
Receive data from a System/3.

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬───
| └─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
──┬──────┬──"
└─ASIS─┘
Conditions:
INVREQ, LENGERR

RECEIVE receives data from the terminal. This form of the RECEIVE command also applies to the following devices:
2770 data communication system
2780 data transmission terminal
3660 supermarket scanning system
3780 communication terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (System/7)

Function
Receive data from a System/7.

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬───────────┬──┬──────┬──"
└─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ └─PSEUDOBIN─┘ └─ASIS─┘
└─SET(ptr-ref)────┘
Conditions:
INVREQ, LENGERR

RECEIVE receives data from the terminal. For a description of running with a System/7, see “CONVERSE (System/7)” on
page 54.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

Chapter 1. Commands 211

RECEIVE (non-VTAM)

RECEIVE (2260)

Function
Receive data from a 2260 or 2265 display station.

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬───
| └─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
──┬─────────┬──"
└─LEAVEKB─┘
Conditions:
INVREQ, LENGERR

RECEIVE receives data from the terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (2741)

Function
Receive data from a 2741 communication terminal.

Command syntax

RECEIVE receives data from the terminal. For more information about using a 2741 communication terminal, see
“CONVERSE (2741)” on page 56.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

212 CICS/ESA Application Programming Reference

RECEIVE (non-VTAM)

RECEIVE (2980)

Function
Receive data from a 2980 general banking terminal system.

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬───
| └─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
| └─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
──PASSBK──"
Conditions:
INVREQ, LENGERR, NOPASSBKRD

RECEIVE receives data from the terminal.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

Passbook control
All input and output requests to the passbook area of a 2980 are dependent on the presence of a passbook. The PASSBK
option is used to specify that communication is with a passbook. The conditions NOPASSBKRD (RECEIVE) and
NOPASSBKWR (SEND) occur on input and output requests respectively when a passbook is not present. These conditions
can be handled by a HANDLE CONDITION command and appropriate handling routines.

If the passbook is present on an input request, the application program generally writes back to the passbook area to update
the passbook. If the NOPASSBKWR condition occurs, CICS allows immediate output to the terminal. In a routine for the
NOPASSBKWR condition, the application program should send an error message to the journal area of the terminal to inform
the 2980 operator of this error condition. To allow the operator to insert the required passbook, CICS causes the transaction to
wait 23.5 seconds before continuing.

On regaining control from CICS after sending the error message, the application program can attempt again to update the
passbook when it has ensured that the print element is positioned correctly in the passbook area. This is generally
accomplished by issuing two carrier returns followed by the number of tabs required to move the print element to the correct
position.

If the NOPASSBKWR condition occurs during the second attempt to write to the passbook area, the application program can
send another error message or take some alternative action (for example, place the terminal “out of service”). The presence of
the Auditor Key on a 2980 Administrative Station Model 2 is controlled by the SEND PASSBK command and may be used in a
manner similar to that described above.

Output control
The unit of transmission for a 2980 is called a segment. However, for the passbook and journal areas, CICS allows an
application program to send messages that exceed the buffer size. For the passbook area, the maximum length of message is
limited to one line of a passbook to avoid spacing (“indexing”) past the bottom of the passbook. For the journal area, the
maximum length of message is specified in the LENGTH option of the SEND command.

For example, consider a 2972 buffer size of 48 characters and a 2980 Teller Station Model 4 passbook print area of 100
characters per line. The application program can send a message of 100 characters to this area; CICS segments the message
to adjust to the buffer size. The application program must insert the passbook indexing character (X'25') as the last character
written in one output request to the passbook area. This is done to control passbook indexing and thereby achieve positive
control of passbook presence.

Chapter 1. Commands 213

RECEIVE (non-VTAM)

If a message contains embedded passbook indexing characters, and segmentation is necessary because of the length of the
message, the output is terminated if the passbook spaces beyond the bottom of the passbook; the remaining segments are not
printed.

Output to a common buffer

The SEND CBUFF command is used to transmit data to a common buffer. The data is translated to the character set of the
receiving 2980 model. If more than one 2980 model type is connected to the 2972 control unit, the lengths are truncated if
they exceed the buffer size.

The DFH2980 structure

The DFH2980 structure contains constants that may only be used when writing COBOL or PL/I application programs for the
2980. The structure is obtained by copying DFH2980 into the application program.

For COBOL, DFH2980 is copied into the working-storage section; for PL/I, DFH2980 is included using a %INCLUDE statement.

The station identification is given in the field STATIONID, whose value must be determined by the ASSIGN command. To test
whether a normal or alternate station is being used, the STATIONID field is compared with values predefined in DFH2980.
The values are:
STATION-

STATION_

where normal stations. (The break symbol is hyphen (-) for COBOL, and underscore (_) for PL/I.)

The teller identification on a 2980 Teller Station Model 4 is given in the 1-byte character field TELLERID. An ASSIGN
command must be used to find out the TELLERID value.

Tab characters (X'05') must be included in the application program. The number of tabs required to position the print element
to the first position of a passbook area is given in the field NUMTAB. An ASSIGN command must be used to find out the
NUMTAB value. The value of NUMTAB is specified by the system programmer and may be unique to each terminal.

Other tab characters are inserted as needed to control formatting.

Any of the DFH2980 values TAB-ZERO through TAB-NINE for COBOL and PL/I, may be compared with NUMTAB to find out
the number of tab characters that need to be inserted in an output message to get correct positioning of the print element. The
tab character is included in DFH2980 as TABCHAR.

Thirty special characters are defined in DFH2980. Twenty-three of these can be referred to by the name SPECCHAR-# or
SPECCHAR_# (for American National Standard COBOL or PL/I) where # is an integer (0 through 22). The seven other
characters are defined with names that imply their usage, for example, TABCHAR.

Several other characters defined in DFH2980, such as HOLDPCF or TCTTEPCR, are intended for use in application programs
using CICS macros, and should not be required in application programs using CICS commands.

214 CICS/ESA Application Programming Reference

RECEIVE (non-VTAM)

RECEIVE (3270 display)

Function
Receive data from a 3270 information display system (BTAM or TCAM).

Command syntax

──RECEIVE──┬─────────────────────┬──┬─LENGTH(data-area)──┬──┬────────────────────────┬──┬────────────┬───
└─┬─INTO(data-area)─┬─┘ └─FLENGTH(data-area)─┘ ├─MAXLENGTH(data-value)──┤ └─NOTRUNCATE─┘
└─SET(ptr-ref)────┘ └─MAXFLENGTH(data-value)─┘
──┬──────┬──┬────────┬──"
└─ASIS─┘ └─BUFFER─┘
Conditions:
INVREQ, LENGERR

RECEIVE receives data from the terminal.

RECEIVE (3600 BTAM)

Function
| Receive data from a 3600 finance communication system (BTAM) - only valid for remote terminals. This form of the RECEIVE
| command also applies to the 4700 finance communication system. For more information about using the 3600 or 4700 finance
| communication system, see “CONVERSE (3600 BTAM)” on page 58 and “BTAM programmable terminals” on page 358.

Command syntax

RECEIVE receives data from the terminal. For more information about using the 3600 or 4700 finance communication system,
see “CONVERSE (3600 BTAM)” on page 58.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

Chapter 1. Commands 215

RECEIVE (non-VTAM)

RECEIVE (3735)

Function
Receive data from a 3735 Programmable Buffered Terminal.

Command syntax

RECEIVE receives data from the terminal. The 3735 Programmable Buffered Terminal may be serviced by CICS in response
to terminal-initiated input (automatic answering), or as a result of an automatic (automatic calling) or time-initiated transaction.

For more information about using the 3735 terminal, see “CONVERSE (3735)” on page 60.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

RECEIVE (3740)

Function
Receive data from a 3740 data entry system.

Command syntax

RECEIVE receives data from the terminal.

In batch mode, many files are exchanged between the 3740 and CICS in a single transmission. The transmission of an input
batch must be complete before an output transmission can be started.

If data is to be received, you must specify either the INTO or the SET option. If a RECEIVE is issued purely to detect an
attention identifier (AID) you can omit both the INTO and SET options.

216 CICS/ESA Application Programming Reference

RECEIVE (non-VTAM)

RECEIVE (3790 3270-display)

Function
Receive data from a 3790 (3270-display) logical unit.

Command syntax

RECEIVE receives data from the terminal.

Chapter 1. Commands 217

RECEIVE (non-VTAM)

RECEIVE (non-VTAM) options LEAVEKB

specifies that the keyboard is to remain locked at the
If you specify the INTO option, but omit the MAXLENGTH completion of the data transfer.
option, the argument must be a data area that specifies the
LENGTH(data-area)
maximum length that the program accepts. If the value
specifies the length, as a halfword binary value, of the
specified is less than zero, zero is assumed.
data transmitted.
If the length of the data exceeds the value specified, but the If you specify the INTO option, but omit the
NOTRUNCATE option is not specified, the data is truncated MAXLENGTH option, the argument must be a data area
to that value and the LENGERR condition occurs. When the that specifies the maximum length that the program
data has been received, the data area is set to the original accepts. If the value specified is less than zero, zero is
length of the data. assumed.

If you specify the SET option, the argument must be a data If the length of the data exceeds the value specified, but
area. When the data has been received, the data area is set the NOTRUNCATE option is not specified, the data is
to the length of the data. truncated to that value and the LENGERR condition
occurs. When the data has been received, the data
For a description of a safe upper limit, see “LENGTH area is set to the original length of the data.
options” on page 5. If you specify the SET option, the argument must be a
ASIS data area. When the data has been received, the data
indicates that output is to be sent in transparent mode area is set to the length of the data.
(with no recognition of control characters and accepting For a description of a safe upper limit, see “LENGTH
any of the 256 possible combinations of eight bits as options” on page 5.
valid transmittable data).
MAXFLENGTH(data-value)
This option has no effect on the first RECEIVE A fullword alternative to MAXLENGTH.
command of a transaction, because terminal control
performs a READ INITIAL operation and uses the MAXLENGTH(data-value)
terminal defaults to translate the data. specifies the maximum amount (halfword binary value)
of data that CICS is to recover. If INTO is specified,
This option has no effect if the screen contains data
MAXLENGTH overrides the use of LENGTH as an input
prior to a transaction being initiated. This data is read
to CICS. If SET is specified, MAXLENGTH provides a
and translated in preparation for the next task and the
way for the program to limit the amount of data it
first RECEIVE command in that task retrieves the
receives at one time.
translated data.
| If the value specified is less than zero, zero is assumed.
Note: If you are using a katakana terminal, you might
see some messages containing mixed English and If the length of data exceeds the value specified and the
katakana characters. That is because katakana NOTRUNCATE option is not present, the data is
terminals cannot display mixed-case output. Uppercase truncated to that value and the LENGERR condition
characters in the data stream appear as uppercase occurs. The data area specified in the LENGTH option
English characters, but lowercase characters appear as is set to the original length of data.
katakana characters. If this happens, ask your system If the length of data exceeds the value specified and the
programmer to specify MSGCASE=UPPER in the NOTRUNCATE option is present, CICS retains the
system initialization parameters so that messages remaining data and uses it to satisfy subsequent
contain uppercase characters only. RECEIVE commands. The data area specified in the
BUFFER (not TCAM) LENGTH option is set to the length of data returned.
specifies that the contents of the 3270 buffer are to be If this option is omitted, the value indicated in the
read, beginning at buffer location one and continuing LENGTH option is assumed.
until all contents of the buffer have been read. All
character and attribute sequences (including nulls) NOTRUNCATE
appear in the input data stream in the same order that specifies that, when the data available exceeds the
they appear in the 3270 buffer. length requested, the remaining data is not to be
discarded but is to be retained for retrieval by
FLENGTH(data-area) subsequent RECEIVE commands.
A fullword alternative to LENGTH.
PASSBK
INTO(data-area) specifies that communication is with a passbook.
specifies the receiving field for the data read from the
terminal or logical unit, or the application target area
receiving the data from the application program
connected to the other end of the current conversation.

218 CICS/ESA Application Programming Reference

RECEIVE (non-VTAM)

PSEUDOBIN EOC
specifies that the data being read is to be translated occurs when a request/response unit (RU) is received
from System/7 pseudobinary representation to with the end-of-chain indicator set. Field EIBEOC also
hexadecimal. contains this indicator.

SESSION(name) Default action: ignore the condition.

specifies the symbolic identifier (1–4 characters) of a
EOF (not TCAM)
session TCTTE. This option specifies the alternate
occurs when an end-of-file indicator is received.
facility to be used. If this option is omitted, the principal
facility for the task is used. Default action: terminate the task abnormally.

SET(ptr-ref) INBFMH
specifies a pointer reference that is to be set to the occurs if a request/response unit (RU) contains a
address of data received from the conversation partner function management header (FMH). Field EIBFMH
# in an MRO conversation. The pointer reference is valid contains this indicator and it should be used in
# until the next receive command or the end of task. preference to INBFMH. The IGNORE CONDITION
command can be used to ignore the condition.
If DATALOCATION(ANY) is associated with the
application program, the address of the data can be Default action: terminate the task abnormally.
above or below the 16MB line.
INVREQ
If DATALOCATION(BELOW) is associated with the occurs if a distributed program link server application
application program, and the data resides above the specified the function-shipping session (its principal
16MB line, the data is copied below the 16MB line, and facility) on the CONVID option (RESP2=200).
the address of this copy is returned.
| Default action: terminate the task abnormally.
If TASKDATAKEY(USER) is specified for the running
LENGERR
task, and storage protection is active, the data returned
occurs if data is discarded by CICS because its length
is in a user-key. If TASKDATAKEY(CICS) is specified
exceeds the maximum the program accepts and the
and storage protection is active, the data returned is in a
NOTRUNCATE option is not specified.
CICS-key.
Default action: terminate the task abnormally.
STATE(cvda)
gets the state of the current conversation. The cvda NOPASSBKRD
values returned by CICS are: occurs if no passbook is present.

ALLOCATED | Default action: terminate the task abnormally.

FREE
NOTALLOC
PENDFREE
occurs if the facility specified in the command is not
RECEIVE
owned by the application.
ROLLBACK
SEND Default action: terminate the task abnormally.
SYNCFREE
RDATT (not TCAM)
SYNCRECEIVE
occurs if a RECEIVE command is terminated by the
SYNCSEND
attention (ATTN) key rather than the return key.
Default action: ignore the condition.
RECEIVE (non-VTAM) conditions
TERMERR
The following conditions can occur in combination with occurs for a terminal-related error, such as a session
others. CICS checks for these conditions in the order: failure. This condition applies to VTAM-connected
1. INBFMH terminals only.
2. EOC. A CANCEL TASK request by a user node error program
(NEP) may cause this condition if the task has an
If more than one occurs, only the first is passed to the outstanding terminal control request active when the
application program. EIBRCODE, however, is set to indicate node abnormal condition program handles the session
all the conditions that occurred. error.
ENDINPT (not TCAM) Default action: terminate the task abnormally with abend
occurs when an end-of-input indicator is received. code ATNI.
Default action: terminate the task abnormally.

Chapter 1. Commands 219

RECEIVE MAP

Function
Receive screen input into an application data area. For further information about BMS, see the CICS/ESA Application
Programming Guide.

Command syntax

──RECEIVE MAP(name)──"

Minimum BMS:

┌─TERMINAL──┬──────┬──┬───────────────┬───┐
│ └─ASIS─┘ └─INPARTN(name)─┘ │
──┬──────────────┬──┬─────────────────┬──┼─────────────────────────────────────────┼──"
└─MAPSET(name)─┘ ├─INTO(data-area)─┤ └─FROM(data-area)──┬────────────────────┬─┘
└─SET(ptr-ref)────┘ └─LENGTH(data-value)─┘
Conditions:
EOC, EODS, INVMPSZ, INVPARTN, INVREQ, MAPFAIL, PARTNFAIL, RDATT, UNEXPIN

Note: INPARTN is supported by Standard and full BMS

cannot suppress uppercase translation on the data. This
data is read and translated in preparation for the next
RECEIVE MAP maps input data from a terminal into a data task and the first RECEIVE command in that task
area in an application program. retrieves the translated data.

Data from certain logical units is not mapped, but is left Note: If you are using a katakana terminal, you might
unaltered. Refer to the appropriate CICS subsystem guide to see some messages containing mixed English and
see if this is true for a particular logical unit. katakana characters. That is because katakana
terminals cannot display mixed-case output. Uppercase
Following a RECEIVE MAP command, the inbound cursor characters in the data stream appear as uppercase
position is placed in EIBCPOSN, and the terminal attention English characters, but lowercase characters appear as
identifier (AID) placed in EIBAID. katakana characters. If this happens, ask your system
programmer to specify MSGCASE=UPPER in the
See Appendix K, “BMS macro summary” on page 381 for system initialization parameters so that messages
map definitions. contain uppercase characters only.

If data is to be received, you must specify either the INTO or FROM(data-area)

the SET option. If a RECEIVE is issued purely to detect an specifies the data area containing the data to be
attention identifier (AID), you can omit both the INTO and the mapped by a RECEIVE MAP command. This includes
SET options. the 12-byte prefix generated by the TIOAPFX=YES
option on the DFHMDI and DFHMSD BMS map
definitions (see pages 395 and 401).
RECEIVE MAP options
INPARTN(name)
ASIS
specifies the name (1–2 characters) of the partition in
specifies that lowercase characters in the 3270 input
which the terminal operator is expected to enter data. If
data stream are not translated to uppercase; this allows
the terminal operator enters data in some other partition,
the current task to receive a message containing both
the INPARTN partition is activated, the keyboard is
uppercase and lowercase data.
unlocked for the partition, and an error message is
This option has no effect on the first RECEIVE output to any error message partition. This option is
command of a transaction, or if the screen contains data ignored if the terminal does not support partitions, or if
prior to a transaction being initiated. For example, if a there is no application partition set.
transaction is initiated by another transaction, and begins
by receiving data originally output by that transaction, it

220 CICS/ESA Application Programming Reference

RECEIVE MAP

INTO(data-area) EOC
specifies the data area into which the mapped data is to occurs if the request/response unit (RU) is received with
be written. If this field is not specified, the name the end-of-chain (EOC) indicator set. It applies only to
| defaults to the name of the map suffixed with an I. logical units.

LENGTH(data-value) Default action: ignore the condition.

specifies the length of the data to be formatted as a
EODS
halfword binary value. It must not exceed the length of
occurs if no data is received (only an FMH). It applies
the FROM data area, but this should include the length
only to 3770 batch LUs and to 3770 and 3790 batch
of the 12-byte prefix generated by the TIOAPFX=YES
data interchange LUs.
option on the DFHMDI and DFHMSD BMS map
definitions (see pages 395 and 401). Default action: terminate the task abnormally.

For a description of a safe upper limit, see “LENGTH INVMPSZ

options” on page 5. occurs if the specified map is too wide or too long for the
terminal.
MAP(name)
specifies the name (1–7 characters) of the map to be Default action: terminate the task abnormally.
used.
INVPARTN
MAPSET(name) occurs if the specified partition is not defined in the
specifies the unsuffixed name (1–7 characters) of the partition set associated with the application program.
| mapset to be used. The mapset must reside in the Default action: terminate the task abnormally.
| CICS program library. The mapset can be defined either
| by using RDO or by program autoinstall when the INVREQ
| mapset is first used. If this option is not specified, the occurs if a RECEIVE MAP command is issued in a
name given in the MAP option is assumed to be that of nonterminal task; these tasks do not have a TIOA or a
the mapset. TCTTE.
Default action: terminate the task abnormally.
SET(ptr-ref)
specifies the pointer that is to be set to the address of MAPFAIL
the 12-byte prefix to the mapped data. occurs if the data to be mapped has a length of zero or
# The pointer reference is valid until the next receive does not contain a set-buffer-address (SBA) sequence.
# command or the end of task. It applies only to 3270 devices. The receiving data area
contains the unmapped input data stream. The amount
If DATALOCATION(ANY) is associated with the
of unmapped data moved to the user’s area is limited to
application program, the address of the data may be
the length specified in the LENGTH option. The input
above or below the 16MB line.
map is not set to nulls.
If DATALOCATION(BELOW) is associated with the
This condition also arises if a program issues a
application program, and the data resides above the
RECEIVE MAP command to which the terminal operator
16MB line, the data is copied below the 16MB line, and
responds by pressing a CLEAR or PA key, or by
the address of this copy is returned.
pressing ENTER or a PF key without entering data.
If TASKDATAKEY(USER) is specified for the running
Default action: terminate the task abnormally.
task, and storage protection is active, the data returned
is in a user-key. If TASKDATAKEY(CICS) is specified PARTNFAIL
and storage protection is active, the data returned is in a occurs if the terminal operator attempts to enter data
CICS-key. more than three times in a partition other than that
specified by the INPARTN option.
TERMINAL
specifies that input data is to be read from the terminal Default action: terminate the task abnormally.
that originated the transaction.
RDATT
occurs if a RECEIVE MAP command is terminated by
RECEIVE MAP conditions the operator using the ATTN key rather than the
RETURN key. It applies only to the 2741
Some of the following conditions can occur in combination. If Communications Terminal, and only if 2741 read
more than one occurs, only the first is passed to the attention support has been generated for CICS.
application program.
Default action: ignore the condition.
EIBRCODE, however, is set to indicate all the conditions that
occurred.

Chapter 1. Commands 221

RECEIVE MAP

UNEXPIN
occurs when unexpected or unrecognized data is
received. This only applies to batch data interchange
terminals.
Default action: terminate the task abnormally.

222 CICS/ESA Application Programming Reference

RECEIVE MAP MAPPINGDEV

# RECEIVE MAP MAPPINGDEV

# Function
# Receive screen input into an application data area, without reference to the principal facility, if any, using terminal
# characteristics obtained from the MAPPINGDEV parameter.
# Apar PQ06521
# RECEIVE MAP MAPPINGDEV added by APAR PQ06521 12/08/97

# Command syntax

#
# ──RECEIVE MAP(name)──MAPPINGDEV(data-value)──FROM(data-area)──┬────────────────────┬─────────────────
# └─LENGTH(data-value)─┘
# ──┬──────────────┬──┬─────────────────┬──"
# └─MAPSET(name)─┘ ├─INTO(data-area)─┤
# └─SET(ptr-ref)────┘

# Conditions: INVMPSZ, INVREQ, MAPFAIL,

#
# Usage # If the AID (whether specified explicitly, or by default) is
# the subject of a HANDLE AID command, the specified
# RECEIVE MAP MAPPINGDEV allows the mapping of input # branch will be taken in the usual way.
# data from a 3270 terminal that is not necessarily the principal
# facility of the transaction. # CURSOR(data-value)
# specifies an unsigned halfword binary field containing
# MAPPINGDEV specifies the name of a 3270 terminal whose # the cursor position (relative to zero) to be used. Usually
# BMS characteristics were used to create the input data # this will be the value contained in EIBCPOSN following
# stream. This may be a terminal from which the data was # the RECEIVE operation that originally received the
# originally received using a RECEIVE command. # datastream from the terminal.
# The value specified is moved into EIBCPOSN in the
# Parameters # EXEC interface block on completion of the operation.
# No check is made that the CURSOR value specified is
# AID(data-value) # valid.
# specifies the one-byte data area containing the value of # If CURSOR(data-value) is not specified, then the cursor
# the 3270 attention identifier (AID) to be used when # value defaults to X'0000'.
# performing the mapping operation. Usually this will be
# the value contained in EIBAID following the RECEIVE # FROM(data-area)
# operation that originally received the datastream from # specifies the data area containing the data to be
# the terminal. # mapped. This must be in the format of a TIOA and must
# contain a 12-byte prefix.
# The value specified is moved into field EIBAID in the
# EXEC interface block on completion of the operation. # INTO(data-area)
# No check is made that the AID value specified is valid. # specifies the data area into which the mapped data is to
# If AID(data-value) is not specified, then the AID value # be written. If this field is not specified, the name
# defaults to X'7D' (the Enter key). # defaults to the name of the map suffixed with an I.

# If the AID byte (either explicitly, or by default) indicates # LENGTH(data-value)

# an operation other than CLEAR, PA1, PA2, or PA3, and # specifies the length of the data to be formatted as a
# CURSLOC=YES is specified for the map, then the field # halfword binary value. It must not exceed the length of
# containing the cursor is flagged by setting the X'02' bit in # the FROM data area, but this should include the length
# its flag byte. # of the 12-byte prefix generated by the TIOAPFX=YES
# option on the DFHMDI and DFHMSD BMS map
# definitions (see pages 395 and 401).

Chapter 1. Commands 223

RECEIVE MAP MAPPINGDEV

# For a description of a safe upper limit, see “LENGTH # Default action: terminate the task abnormally.
# options” on page 5.

# MAP(name)
# specifies the name (1–7 characters) of the map to be
# used.

# MAPPINGDEV(data-value)
# specifies the name of a 3270 terminal whose
# characteristics match those of the terminal from which
# the data was originally received using a RECEIVE
# command.

# MAPSET(name)
# specifies the unsuffixed name (1–7 characters) of the
# mapset to be used. The mapset must reside in the
# CICS program library. The mapset can be defined either
# by using RDO or by program autoinstall when the
# mapset is first used. If this option is not specified, the
# name given in the MAP option is assumed to be that of
# the mapset.

# SET(ptr-ref)
# specifies the pointer that is to be set to the address of
# the 12-byte prefix to the mapped data.
# The pointer reference is valid until the next RECEIVE or
# RECEIVE MAP command, or until the end of the
# transaction, unless FREEMAINed by the application.
# If "TASKDATALOC(ANY)" is specified for the running
# task, the data returned may be above or below the
# 16MB line.
# If "TASKDATALOC(BELOW)" is specified for the running
# task,the data returned is below the 16MB line.
# If "TASKDATAKEY(USER)" is specified for the running
# task, and storage protection is active, the data returned
# is in user-key. If "TASKDATAKEY(CICS)" is specified
# and storage protection is active, the data returned is in
# CICS-key.

# Error Conditions
# Some of the following conditions may occur in combination.
# If more than one occurs, only the first is passed to the
# application program.

# INVMPSZ
# occurs if the specified map is too wide or too long for the
# terminal.
# Default action: terminate the task abnormally.

# INVREQ
# occurs if the terminal specified by MAPPINGDEV does
# not exist, does not support BMS, or is not a 3270 printer
# or display.
# Default action: terminate the task abnormally.

# MAPFAIL
# occurs if the data to be mapped has a length of zero or
# does not contain a set-buffer-address (SBA) sequence.

224 CICS/ESA Application Programming Reference

RECEIVE PARTN

Function
Receive data from an 8775 terminal partition. This command is only available on standard and full BMS. For further
information about BMS, see the dfhp33h.CICS/ESA Application Programming Guide.

Command syntax

──RECEIVE PARTN(data-area)──"

Standard and full BMS:

──┬─INTO(data-area)─┬──LENGTH(data-value)──┬──────┬──"
└─SET(ptr-ref)────┘ └─ASIS─┘
Conditions:
EOC, EODS, INVPARTN, INVREQ, LENGERR

RECEIVE PARTN reads data from a partition on an 8775 Note: If you are using a katakana terminal, you might
terminal. It indicates which partition the data came from, and see some messages containing mixed English and
puts the data into the INTO or the SET data area. You can katakana characters. That is because katakana
then treat the data as though it had originated from a terminals cannot display mixed-case output. Uppercase
terminal in base (unpartitioned) state. characters in the data stream appear as uppercase
English characters, but lowercase characters appear as
Following a RECEIVE PARTN command, the inbound cursor katakana characters. If this happens, ask your system
position is placed in EIBCPOSN, and the terminal attention programmer to specify MSGCASE=UPPER in the
identifier (AID) placed in EIBAID. EIBAID and EIBCPOSN system initialization parameters so that messages
are also updated at task initiation for non-ATI tasks as well contain uppercase characters only.
as after each terminal control and BMS input.
INTO(data-area)
See Appendix K, “BMS macro summary” on page 381 for specifies the area into which the input data stripped of
map definitions. partition controls is to be written. The length of this area
must be specified by the LENGTH option. If the area is
If data is to be received, you must specify either the INTO or not large enough to hold the input data, the input data is
the SET option. If a RECEIVE is issued purely to detect an truncated, and the LENGERR condition raised. The
attention identifier (AID), you can omit both the INTO and the length option data area is set to the length of data
SET options. received, prior to any truncation.

LENGTH(data-value)
RECEIVE PARTN options specifies the length of the data to be formatted as a
ASIS halfword binary value. It must be set to the length of
specifies that lowercase characters in the 3270 input any INTO area prior to the command. After the
data stream are not translated to uppercase; this allows command, BMS sets the LENGTH option to the length of
the current task to receive a message containing both data received prior to any truncation if the INTO area is
uppercase and lowercase data. too small.

The ASIS option has no effect on the first RECEIVE For a description of a safe upper limit, see “LENGTH
command of a transaction, or if the screen contains data options” on page 5.
prior to a transaction being initiated. For example, if a PARTN(data-area)
transaction is initiated by another transaction, and begins is set to the name (1–2 characters) of the input partition.
by receiving data originally output by that transaction, it | The partition can be defined either by using RDO or by
cannot suppress uppercase translation on the data. This | program autoinstall when the partition is first used.
data is read and translated in preparation for the next
task and the first RECEIVE command in that task SET(ptr-ref)
retrieves the translated data. specifies the pointer that is to be set to the address of
# the 12-byte prefix to the mapped data. The pointer

Chapter 1. Commands 225

RECEIVE PARTN

# reference is valid until the next receive command or the

# end of task.
If DATALOCATION(ANY) is associated with the
application program, the address of the data may be
above or below the 16MB line.
If DATALOCATION(BELOW) is associated with the
application program, and the data resides above the
16MB line, the data is copied below the 16MB line, and
the address of this copy is returned.
If TASKDATAKEY(USER) is specified for the running
task, and storage protection is active, the data returned
is in a user-key. If TASKDATAKEY(CICS) is specified
and storage protection is active, the data returned is in a
CICS-key.

RECEIVE PARTN conditions

Some of the following conditions can occur in combination. If
more than one occurs, only the first one is passed to the
application program.

EOC
occurs if the request/response unit (RU) is received with
the end-of-chain (EOC) indicator set. It applies only to
logical units.
Default action: ignore the condition.

EODS
occurs if no data is received (only an FMH). It applies
only to 3770 batch LUs and to 3770 and 3790 batch
data interchange LUs.
Default action: terminate the task abnormally.

INVPARTN
occurs if the specified partition is not defined in the
partition set associated with the application program.
Default action: terminate the task abnormally.

INVREQ
occurs if a RECEIVE PARTN command is issued in a
nonterminal task; these tasks do not have a TIOA or a
TCTTE.
Default action: terminate the task abnormally.

LENGERR
occurs if the INTO area of a RECEIVE PARTN
command is not large enough to hold the input data.
Default action: truncate the data to fit within the INTO
area.

226 CICS/ESA Application Programming Reference

RELEASE

Function
Release a loaded program, table, or mapset.

Command syntax

──RELEASE──PROGRAM(name)──"
Conditions:
INVREQ, NOTAUTH, PGMIDERR

| Note for dynamic transaction routing

| Using RELEASE of a program LOADed with HOLD could create inter-transaction affinities that adversely affect the use of
| dynamic transaction routing. See the CICS/ESA Application Programming Guide for more information about transaction
| affinities.

| RELEASE releases the program, table, or mapset previously RELEASE conditions

| loaded by a LOAD command. This means that the issuing
| task can no longer use the resource unless another LOAD is INVREQ
| issued. occurs in any of the following situations:

An invalid attempt is made by the program to

| If the HOLD option is specified in the LOAD command, the
| release itself (RESP2=5). A RELEASE command
| loaded resource is not released at the end of the task. It can
| for the program that contains this command is
| only be released by a RELEASE command. This RELEASE
| allowed only when a corresponding LOAD command
| command may be issued by the task that loaded the
| for the program has been issued from the same
| resource or by any other task.
| task, or when a LOAD command with the HOLD
| If the HOLD option is not specified in the LOAD command, | option has been issued from another task.
| the loaded resource is released at the end of the task. It The command is issued for a program that is not
| may, however, be released before this by the task that loaded (RESP2=6).
| loaded the resource issuing a RELEASE command.

| The following example shows how to release an application # Apar PQ28669
| program, called PROG4, loaded in response to a LOAD
# Documentation for Apar PQ28669 added
| command:
# 09/09/99
EXEC CICS RELEASE PROGRAM('PROG4')
# Either the command is issued for a program that
RELEASE option # was loaded, without the HOLD option, by another
# task, or the program has been enabled as a global
PROGRAM(name) # user exit (RESP2=7).
specifies the identifier (1–8 characters) of a program,
table, or mapset to be deleted. The specified name | The program is defined with RELOAD=YES. It must
| must have been defined as a program to CICS, though if | be released by a FREEMAIN rather than a
| AUTOINSTALL is active a definition is autoinstalled. | RELEASE command (RESP2=17).
| The program manager domain has not yet been
| initialized. This is probably due to a release request
| having been made in a first stage PLT (RESP2=30).

Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
PROGRAM(name).
Default action: terminate the task abnormally.

Chapter 1. Commands 227

RELEASE

PGMIDERR
occurs in any of the following situations:

A program, table, or mapset has no entry in the

PPT (RESP2=1)
A program, table, or mapset is disabled (RESP2=2)
The installed program definition is for a remote
program (RESP2=9).

Default action: terminate the task abnormally.

228 CICS/ESA Application Programming Reference

RESETBR

Function
Reset start of browse.

Command syntax

──RESETBR──FILE(filename)──RIDFLD(data-area)──┬────────────────────────────────────┬─────────────────────
└─KEYLENGTH(data-value)──┬─────────┬─┘
└─GENERIC─┘
┌─GTEQ──┐
──┬───────────────────┬──┬───────────────────┬──┼───────┼──┬─────┬──"
└─REQID(data-value)─┘ └─SYSID(systemname)─┘ └─EQUAL─┘ ├─RBA─┤
└─RRN─┘
Conditions:
FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, NOTAUTH, NOTFND, SYSIDERR

RESETBR specifies, during a browse, the record in a file or that has the same starting characters (generic key) as
data table on a local or a remote system, where you want those specified.
the browse to be repositioned.
GTEQ (VSAM and data table)
When browsing a VSAM file or data table, you can use this specifies that if the search for a record having the same
command not only to reposition the browse (which can be key (complete or generic) as that specified in the
achieved more simply by modifying the RIDFLD data area on RIDFLD option is unsuccessful, the first record having a
a READNEXT or READPREV command), but also to change greater key is retrieved. Use this option only with keyed
its characteristics from those specified on STARTBR, without or RRN.
ending the browse. The characteristics that may be changed
KEYLENGTH(data-value)
are those specified by the GENERIC, GTEQ, and RBA
specifies the length (halfword binary) of the key that has
options.
been specified in the RIDFLD option, except when RBA
or RRN is specified, in which case KEYLENGTH is not
When browsing a BDAM file, you can include this command
valid.
at any time prior to issuing any other browse command. It is
similar to an ENDBR–STARTBR sequence (but with less This option must be specified if GENERIC is specified,
function), and gives the BDAM user the sort of skip and it can be specified whenever a key is specified. If
sequential capability that is available to VSAM users through the length specified is different from the length defined
use of the READNEXT command. for the data set and the operation is not generic, the
INVREQ condition occurs.
RESETBR options The INVREQ condition also occurs if a RESETBR
command specifies GENERIC, and the KEYLENGTH is
EQUAL (VSAM and data table) not less than that specified in the VSAM definition.
specifies that the search is satisfied only by a record
having the same key (complete or generic) as that If KEYLENGTH(0) is used with the object of reading the
specified in the RIDFLD option. first record in the data set, the GTEQ option must also
be specified. If EQUAL is specified either explicitly or by
FILE(filename) default with KEYLENGTH(0), the results of the
specifies the of the file to be accessed. STARTBR are unpredictable.
If SYSID is specified, the data set to which this file refers # RBA (VSAM ESDS, KSDS, or CMT)
is assumed to be on a remote system irrespective of # (base data sets only, not paths)
whether the name is defined in the FCT. Otherwise, the specifies that the record identification field specified in
FCT entry is used to find out whether the data set is on the RIDFLD option contains a relative byte address.
a local or a remote system. Use this option only when browsing a KSDS and using
GENERIC (VSAM KSDS, path or data table) relative byte addresses instead of keys to identify the
specifies that the search key is a generic key whose records.
length is specified in the KEYLENGTH option. The | You cannot use RBA for user-maintained data tables.
search for a record is satisfied when a record is found

Chapter 1. Commands 229

RESETBR

REQID(data-value) The KEYLENGTH option is specified (but the

specifies as a halfword binary value a unique request GENERIC option is not specified), and the specified
identifier for a browse, used to control multiple browse length does not equal the length defined for the data
operations on a data set. If this option is not specified, a set to which this file refers (RESP2=26).
default value of zero is assumed.
| The REQID, if any, does not match that of any
RIDFLD(data-area) | successful STARTBR command (RESP2=36).
# specifies the record identification field. When combined The KEYLENGTH and GENERIC options are
# with RBA or RRN this is a 4-character field. The specified, and the length specified in the
contents can be a key, a relative byte address, or KEYLENGTH option is less than zero (RESP2=42).
relative record number (for VSAM data sets), or a block
reference, physical key, and a deblocking argument (for Default action: terminate the task abnormally.
BDAM data sets). For a relative byte address or a
IOERR
relative record number, the format of this field must be
occurs if there is an I/O error during the file control
fullword binary. For a relative byte address, the RIDFLD
operation (RESP2=120). An I/O error is any unusual
can be greater than or equal to zero. For a relative
event that is not covered by a CICS condition.
record number, the RIDFLD can be greater than or
equal to 1. For VSAM files, IOERR normally indicates a hardware
error.
For VSAM, a full record id of X'FF's indicates that the
browse is to be positioned at the end of the data set in (Further information is available in the EXEC interface
preparation for a backwards browse using READPREV block; refer to Appendix A, “EXEC interface block” on
commands. page 343 for details.)
Default action: terminate the task abnormally.
RRN (VSAM RRDS)
specifies that the record identification field specified in ISCINVREQ
the RIDFLD option contains a relative record number. occurs when the remote system indicates a failure that
does not correspond to a known condition (RESP2=70).
SYSID(systemname)
specifies the name of the system to which the request is Default action: terminate the task abnormally.
directed.
NOTAUTH
If you specify SYSID, and omit both RBA and RRN, you occurs when a resource security check has failed on
must also specify KEYLENGTH; it cannot be found in FILE(filename) (RESP2=101).
the FCT.
Default action: terminate the task abnormally.

RESETBR conditions NOTFND

occurs if an attempt to retrieve a record based on the
Note: RESP2 values are not set for files that are on remote search argument provided is unsuccessful (RESP2=80).
systems.
NOTFND can also occur if a generic RESETBR with
FILENOTFOUND keylength(0) specifies the EQUAL option.
occurs if a file name referred to in the FILE option
Default action: terminate the task abnormally.
cannot be found in the FCT (RESP2=1).
Default action: terminate the task abnormally.

ILLOGIC (VSAM)
occurs if a VSAM error occurs that does not fall within
one of the other CICS response categories
(RESP2=110).
# (See EIBRCODE in the EXEC interface block; refer to
Appendix A, “EXEC interface block” on page 343 for
details.)
Default action: terminate the task abnormally.

INVREQ
occurs in any of the following situations:

The KEYLENGTH and GENERIC options are

specified, and the length specified in the
KEYLENGTH option is greater than or equal to the
length of a full key (RESP2=25).

230 CICS/ESA Application Programming Reference

RESETBR

Chapter 1. Commands 231

RETRIEVE

Function
Retrieve data stored for a task.

Command syntax

──RETRIEVE──┬────────────────────────────────────────────┬──┬─────────────────────┬──────────────────────
└─┬─INTO(data-area)─┬──┬───────────────────┬─┘ └─RTRANSID(data-area)─┘
| └─SET(ptr-ref)────┘ └─LENGTH(data-area)─┘
──┬────────────────────┬──┬──────────────────┬──┬──────┬──"
└─RTERMID(data-area)─┘ └─QUEUE(data-area)─┘ └─WAIT─┘
Conditions:
ENDDATA, ENVDEFERR, INVREQ, IOERR, LENGERR, NOTFND

| Note for dynamic transaction routing

| Using RETRIEVE with WAIT could create inter-transaction affinities that adversely affect the use of dynamic transaction
| routing. See the CICS/ESA Application Programming Guide for more information about transaction affinities.

RETRIEVE retrieves data stored by expired START Each data record is retrieved from temporary storage using
commands. It is the only method available for accessing the REQID of the original START command as the
such data. identification of the record in temporary storage.

A task that is not associated with a terminal can access only When all expired data records have been retrieved, the
the single data record associated with the original START ENDDATA condition occurs. The storage occupied by the
command; it does so by issuing a RETRIEVE command. single data record associated with a START command is
The storage occupied by the data associated with the task is released after the data has been retrieved by a RETRIEVE
command; any storage occupied by data that has not been
# Apar PN92143 retrieved is released when the CICS system is terminated.
# Documentation for Apar PN92143 added 28/02/97
If the retrieved data contains FMHs (Function Management
Headers), as specified by the FMH option on the associated
# normally released on execution of the RETRIEVE command, START command, field EIBFMH in the EIB is set to X'FF'.
or on termination of the task if no RETRIEVE command is If no FMH is present, EIBFMH is set to X'00'.
executed prior to termination.
The following example shows how to retrieve data stored by
# Apar PN92143 a START command for the task, and store it in the
user-supplied data area called DATAFLD.
# Documentation for Apar PN92143 added 28/02/97
EXEC CICS RETRIEVE
INTO(DATAFLD)
# If the START command specified ATTACH, the storage is LENGTH(LENG)
# not released, the SET option must be used and the length of
# the data is not returned because it is not known. The INTO The following example shows how to request retrieval of a
# option in these circumstances causes the INVREQ condition data record stored for a task into a data area provided by
# (ASSIGN STARTCODE returns 'U' rather than 'S' or 'SD'). CICS; the pointer reference (PREF) specified by the SET
option is set to the address of the storage area reserved for
A task that is associated with a terminal can access all data the data record.
records associated with all expired START commands having EXEC CICS RETRIEVE
the same transaction identifier and terminal identifier as this SET(PREF)
task, that is the task issuing the RETRIEVE command; it LENGTH(LENG)
does so by issuing consecutive RETRIEVE commands.
Expired data records are presented to the task on request in
expiration-time sequence, starting with any data stored by RETRIEVE options
the command that started the task, and including data from
any commands that have expired since the task started.

232 CICS/ESA Application Programming Reference

RETRIEVE

INTO(data-area) later if CICS enters shutdown or if the task is subject to

specifies the user data area into which retrieved data is deadlock time-out and it waits for longer than the
to be written. deadlock time-out interval (see the DTIMOUT option of
RDO DEFINE TRANSACTION).
LENGTH(data-area)
specifies a halfword binary value to define the length of An attempt to issue RETRIEVE WAIT during shutdown
the data area the retrieved data is written into. leads to an AICB abend if there is no data record
already available to satisfy the request.
If you specify the INTO option, the argument must be a
data area that specifies the maximum length of data that | If you use WAIT, you must have at least one other
the program is prepared to handle. If the value specified | option.
is less than zero, zero is assumed. If the length of the
data exceeds the value specified, the data is truncated
to that value and the LENGERR condition occurs. On
completion of the retrieval operation, the data area is set
to the original length of the data.
If you specify the SET option, the argument must be a
data area. On completion of the retrieval operation, the
data area is set to the length of the data.
For a description of a safe upper limit, see “LENGTH
options” on page 5.

QUEUE(data-area)
specifies the 8-character area for the temporary storage
queue name that may be accessed by the transaction
issuing the RETRIEVE command.

RTERMID(data-area)
specifies a 4-character area that can be used in the
TERMID option of a START command that may be
executed subsequently.

RTRANSID(data-area)
specifies a 4-character area that can be used in the
TRANSID option of a START command that may be
executed subsequently.

SET(ptr-ref)
specifies the pointer reference to be set to the address
of the retrieved data.
If DATALOCATION(ANY) is associated with the
application program, the address of the data may be
above or below the 16MB line.
If DATALOCATION(BELOW) is associated with the
application program, and the data resides above the
16MB line, the data is copied below the 16MB line, and
the address of this copy is returned.
If TASKDATAKEY(USER) is specified for the running
task, and storage protection is active, the data returned
is in a user-key. If TASKDATAKEY(CICS) is specified
and storage protection is active, the data returned is in a
CICS-key.
| If you use SET you must also include LENGTH.

WAIT
specifies that, if all expired data records have already
been retrieved, the task is to be put into a wait state until
further expired data records become available. Although
this means that the ENDDATA condition is not raised at
the time the RETRIEVE command is issued, it is raised

Chapter 1. Commands 233

RETRIEVE

RETRIEVE conditions NOTFND

occurs in any of the following situations:
ENDDATA
occurs in any of the following situations: A RETRIEVE command is issued, but some prior
task retrieved the data stored under the request
No more data is stored for the task issuing a identifier directly through temporary storage
RETRIEVE command. It can be considered a requests and then released the data.
normal end-of-file response when retrieving data
The request identifier associated with the START
records sequentially.
command is not unique, so when a RETRIEVE
The RETRIEVE command is issued by a task that is command is issued, CICS cannot find the data.
started by a START command that did not specify
any of the data options FROM, RTRANSID, Default action: terminate the task abnormally.
RTERMID, or QUEUE.
The RETRIEVE command is issued by a
nonterminal task that was not created as a result of
a START command.
WAIT was specified and the task was waiting for a
data record but none became available before the
deadlock time-out interval expired (see the
DTIMOUT option of RDO DEFINE TRANSACTION).
WAIT was specified and the task was waiting when
CICS entered shutdown. An attempt to issue
RETRIEVE WAIT during shutdown leads to an AICB
abend if there is no data record already available to
satisfy the request.
A RETRIEVE command with the WAIT option is
issued when no data is available; the task was
initiated by a START command that specified an
APPC connection or terminal in the TERMID option.

Default action: terminate the task abnormally.

ENVDEFERR
occurs when a RETRIEVE command specifies an option
not specified by the corresponding START command.
Default action: terminate the task abnormally.

INVREQ
occurs if the RETRIEVE command is not valid for
processing by CICS.
Default action: terminate the task abnormally.

IOERR
occurs if an input/output error occurs during a
RETRIEVE operation. The operation can be retried by
reissuing the RETRIEVE command.
Default action: terminate the task abnormally.

LENGERR
occurs if the length specified is less than the actual
length of the stored data.
Default action: terminate the task abnormally.

234 CICS/ESA Application Programming Reference

RETURN

Function
Return program control.

Command syntax

──RETURN──┬───────────────────────────────────────────────────────────────────────────────┬──────────────
└─TRANSID(name)──┬─────────────────────────────────────────────┬──┬───────────┬─┘
└─COMMAREA(data-area)──┬────────────────────┬─┘ └─IMMEDIATE─┘
└─LENGTH(data-value)─┘
──┬──────────────────────────────────────────────────┬──"
└─INPUTMSG(data-area)──┬─────────────────────────┬─┘
└─INPUTMSGLEN(data-value)─┘
Conditions:
INVREQ, LENGERR

RETURN returns control from an application program either This option is valid only on a RETURN command issued
to an application program at the next higher logical level, or by a program at the highest logical level, that is, a
to CICS. program returning control to CICS.

The LENGTH option specifies the length of the data to be IMMEDIATE

passed. The LENGTH value being passed must not be ensures that the transaction specified in the TRANSID
greater than the length of the data area specified in the option is attached as the next transaction regardless of
COMMAREA option. If it is, the results are unpredictable any other transactions enqueued by ATI for this terminal.
and may result in a LENGERR condition, as described in the The next transaction starts immediately and appears to
section about passing data to other programs in the the operator as having been started by terminal data. If
CICS/ESA Application Programming Guide. the terminal is using bracket protocol, the terminal is
also held in bracket. This option is valid only on a
The valid range for the COMMAREA length is 0 through RETURN command issued by a program at the highest
32 763 bytes. If the length provided is outside this range, the logical level, that is a program returning control to CICS.
LENGERR condition occurs. The COMMAREA and
# Note that in a multi region environment, using
IMMEDIATE options can be used only when the RETURN
# IMMEDIATE does not affect the transaction definition as
command is returning control to CICS; otherwise, the
# this is still found in the terminal-owning region (TOR).
INVREQ condition occurs.
INPUTMSG(data-area)
No resource security checking occurs on the RETURN specifies data to be passed either to another transaction,
TRANSID command. However, transaction security checking identified by the TRANSID option, or to a calling
is still available when CICS attaches the returned transaction. program in a multiprogram transaction. You can also
use INPUTMSG when returning control to CICS from a
RETURN options user-written dynamic transaction routing program, when
you might want to modify the initial input.
COMMAREA(data-area)
In all cases, the data in the INPUTMSG data area is
specifies a communication area that is to be made
passed to the first program to issue a RECEIVE
available to the next program that receives control. In a
command following the RETURN.
COBOL receiving program, you must give this data area
the name DFHCOMMAREA. (See the CICS/ESA See the CICS/ESA Application Programming Guide for
Application Programming Guide.) Because the data more information and illustrations about the use of
area is freed before the next program starts, a copy of INPUTMSG.
the data area is created and a pointer to the copy is
INPUTMSGLEN(data-value)
passed.
specifies a halfword binary value to be used with
The communication area specified is passed to the next INPUTMSG.
program that runs at the terminal. To ensure that the
communication area is passed to the correct program, LENGTH(data-value)
include the IMMEDIATE option. specifies a halfword binary value that is the length in
bytes of the COMMAREA. For a description of a safe
upper limit, see “LENGTH options” on page 5.

Chapter 1. Commands 235

RETURN

TRANSID(name) RETURN conditions

specifies the transaction identifier (1–4 characters) to be
used with the next input message entered from the INVREQ
terminal with which the task that issued the RETURN occurs in any of the following situations:
command has been associated. The specified name
A RETURN command with the TRANSID option is
must have been defined as a transaction to CICS.
issued in a program that is not associated with a
Apar 60841 terminal (RESP2=1).
Documentation for Apar 60841 added 15 Nov 1994 A RETURN command with the COMMAREA or
(TUCKER) IMMEDIATE option is issued by a program that is
not at the highest logical level (RESP2=2).
If TRANSID is specified for a program running on a A RETURN command with the TRANSID option is
terminal that is defined with a permanent transaction ID, issued in a program that is associated with an
the terminal's permanent transaction is initiated next APPC logical unit (RESP2=4).
rather than the transaction specified on the RETURN.
| A RETURN command with the INPUTMSG option is
| If you specify a TRANSID of binary zeros, the | issued for a program that is not associated with a
| transaction identifier for the next program to be | terminal, or that is associated with an APPC logical
| associated with the terminal may be determined from | unit, or an IRC session (RESP2=8).
| subsequent input from the terminal. Issuing a RETURN
| with a TRANSID of binary zeros and a COMMAREA can | PG domain not initialized. Parameters are not
| cause unpredictable results if the next transaction is not | allowed on the EXEC RETURN statement in first
| coded to handle the COMMAREA or if it receives a | stage PLT programs (RESP2=30).
| COMMAREA not intended for it. | A RETURN command is issued with an INPUTMSG
| If you specify TRANSID on a program that is not at the | option by a program invoked by DPL (RESP2=200).
| highest level, and there is a subsequent error on Default action: terminate the task abnormally.
| COMMAREA or INPUTMSG on the final RETURN, the
| TRANSID is cleared. LENGERR
LENGERR occurs in the following conditions:
| The next transaction identifier is also cleared on an
| abnormal termination of the transaction. | The COMMAREA length is less than 0 or greater
If IMMEDIATE is specified with this option, control is | than 32763 (RESP2=11).
passed to the transaction specified in the TRANSID | The COMMAREA ADDRESS passed was zero, but
option in preference to any transactions enqueued by | the commarea length was non zero (RESP2=26).
ATI.
| The INPUTMSG LENGTH was less than 0 or
If IMMEDIATE is not specified with this option, an ATI | greater than 32767 (RESP2=27).
initiated transaction of the same name enqueued to the
terminal nullifies this option. Default action: terminate the task abnormally.

This option is not valid if the transaction issuing the

RETURN command is not associated with a terminal, or
is associated with an APPC logical unit.

236 CICS/ESA Application Programming Reference

REWRITE

Function
Update a record in a file.

Command syntax

──REWRITE──FILE(filename)──┬───────────────────┬──FROM(data-area)──┬────────────────────┬────────────────
| └─TOKEN(data-value)─┘ └─LENGTH(data-value)─┘
──┬───────────────────┬──"
└─SYSID(systemname)─┘
Conditions:
DUPREC, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, NOSPACE, NOTAUTH,
NOTFND, SYSIDERR

REWRITE updates a record in a file on a local or a remote This option must also be specified for a file defined as
system. You must always precede this command with a | containing variable-length records; which includes
READ UPDATE to read the record to be updated. | user-maintained data tables. It need not be specified if
the file contains fixed-length records. You are
For example: recommended to include it, however, because it causes
EXEC CICS REWRITE a check to be made to ensure that the length of data
FROM(RECORD) being written is equal to that defined for the data set. If
FILE('MASTER') the lengths are not equal, the LENGERR condition
For VSAM data sets, you must not change the key field in occurs.
the record. SYSID(systemname)
specifies the name of the system to which the request is
When this command is used to update a record in a
directed.
CICS-maintained data table, the update is made to both the
source VSAM KSDS and the in-memory data table. The | TOKEN(data-value)
details of the command for a CICS-maintained table are the # specifies as a fullword binary value a unique request
same as for a VSAM KSDS. | identifier for a REWRITE, used to associate it with a
| previous READ UPDATE request.
| When this command is used to update a record in a
| user-maintained data table, the update is made to the
| in-memory data table. REWRITE conditions
Note: RESP2 values are not set for files that are on remote
REWRITE options systems.

FILE(filename) DUPREC
specifies the of the file to be accessed. occurs when an attempt is made to rewrite a record to a
data set whose upgrade set has an alternate index with
If SYSID is specified, the data set to which this file refers the UNIQUEKEY attribute, if the corresponding alternate
is assumed to be on a remote system irrespective of key already exists in the alternate index (RESP2=150).
whether the name is defined in the FCT. Otherwise, the
FCT entry is used to find out whether the data set is on Default action: terminate the task abnormally.
a local or a remote system. FILENOTFOUND
FROM(data-area) occurs if a file name referred to in the FILE option
specifies the record that is to be written to the data set cannot be found in the FCT (RESP2=1).
referred to by this file. Default action: terminate the task abnormally.
LENGTH(data-value) ILLOGIC (VSAM)
specifies the actual length, as a halfword binary value, of occurs if a VSAM error occurs that does not fall within
the record to be written. one of the other CICS response categories
This option must be specified if SYSID is specified. (RESP2=110).

Chapter 1. Commands 237

REWRITE

# (See EIBRCODE in the EXEC interface block; refer to # This may be caused by a logic error in the
Appendix A, “EXEC interface block” on page 343 for # application program.
details.)
# Default action: terminate the task abnormally.
Default action: terminate the task abnormally. NOSPACE
occurs if no space is available on the direct access
INVREQ
device for adding the updated record to the data set
occurs in any of the following situations:
| (RESP2=100). For user-maintained data tables, this
| A REWRITE command is issued without a token | condition occurs if CICS is unable to get sufficient
| and no previous READ for UPDATE (also without a | storage in the CICS address space to store the updated
| token) can be found (RESP2=30). | data table entry (RESP2=103).

A REWRITE command has attempted to change the Default action: terminate the task abnormally.
length of a BDAM variable length record or block
NOTAUTH
(RESP2=46).
occurs when a resource security check has failed on
| A REWRITE instruction includes a token whose FILE(filename) (RESP2=101).
| value cannot be matched against any token in use
Default action: terminate the task abnormally.
| for an existing READ for UPDATE request
| (RESP2=47). SYSIDERR
| occurs when the SYSID option specifies a name that is
| An attempt is made to function-ship a request which
| neither the local system nor a remote system (made
| includes a TOKEN keyword (RESP2=48).
| known to CICS by defining a CONNECTION).
Default action: terminate the task abnormally. SYSIDERR also occurs when the link to the remote
system is closed (RESP2=130).
IOERR
occurs if there is an I/O error during the file control Default action: terminate the task abnormally.
operation (RESP2=120). An I/O error is any unusual
event that is not covered by a CICS condition.
For VSAM files, IOERR normally indicates a hardware
error.
(Further information is available in the EXEC interface
block; refer to Appendix A, “EXEC interface block” on
page 343 for details.)
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition (RESP2=70).
Default action: terminate the task abnormally.

LENGERR
occurs in any of the following situations:

The LENGTH option is not specified for a file with

variable-length records, or for a BDAM file with
undefined format records (RESP2=10).
The length specified exceeds the maximum record
size (of the source data set for a data-table); the
record is truncated (RESP2=12).
An incorrect length is specified for a file with
fixed-length records (RESP2=14).

Default action: terminate the task abnormally.

# NOTFND occurs when an attempt to REWRITE a record

# to a user-maintained data table has failed because
# the REWRITE is associated with a READ UPDATE
# request for a record that this transaction has deleted
# (using DELETE with RIDFLD) after it was read for
# update (RESP2=80).

238 CICS/ESA Application Programming Reference

ROUTE

Function
Route a BMS message. (This command is only available on full BMS. The CICS/ESA Application Programming Guide has
further information about BMS.)

Command syntax

┌─INTERVAL()──────────────────────┐
──ROUTE──┼──────────────────────────────────┼──┬─────────────────────┬──┬──────────────────┬─────────────
├─INTERVAL(hhmmss)─────────────────┤ └─ERRTERM──┬────────┬─┘ └─TITLE(data-area)─┘
├─TIME(hhmmss)─────────────────────┤ └─(name)─┘
│ ┌──
───────────────────────┐ │
| *
├─AFTER───┬─HOURS(data-value)───┬┴─┤
| │ ├─MINUTES(data-value)─┤ │
| │ └─SECONDS(data-value)─┘ │
│ ┌──
───────────────────────┐ │
| └─AT───*┬─HOURS(data-value)───┬┴────┘
| ├─MINUTES(data-value)─┤
| └─SECONDS(data-value)─┘
──┬─────────────────┬──┬────────────────────┬──┬─────────────┬──┬───────────┬──┬───────┬──"
└─LIST(data-area)─┘ └─OPCLASS(data-area)─┘ └─REQID(name)─┘ └─LDC(name)─┘ └─NLEOM─┘
Conditions:
INVERRTERM, INVLDC, INVREQ, RTEFAIL, RTESOME

ROUTE routes a BMS logical message to one or more This option is effective only if PRGDLAY has been
terminals or terminal operators. specified in the system initialization parameters.

| The default is INTERVAL(0), but for C the default is AFTER | HOURS(data-value)

| HOURS(0) MINUTES(0) SECONDS(0). specifies a fullword binary value in the range 0–99. This
is a suboption of the AFTER and AT options. For its
use and meaning, see the AFTER option.
ROUTE options
INTERVAL(hhmmss)
AFTER specifies the interval of time after which the data is to be
specifies the amount of time to elapse before the route. transmitted to the terminals specified in the ROUTE
There are two ways to enter the time under AFTER and command. The mm and ss are in the range 0–59.
AT. | When using the C language, you are recommended to
1. A combination of at least two of HOURS(0–99), | use the AFTER/AT HOURS, MINUTES, and SECONDS
MINUTES(0–59), and SECONDS(0–59). HOURS(1) | options as C does not provide a packed decimal data
SECONDS(3) would mean one hour and three | type. You may use INTERVAL, but if the value specified
seconds (the minutes default to zero). | is not an integer constant, the application is responsible
| for ensuring that the value passed to CICS is in packed
2. As one of HOURS(0–99), MINUTES(0–5999), or | decimal format.
SECONDS(0–359 999). HOURS(1) means one
hour. MINUTES(62) means one hour and two LDC(name) — logical units only
minutes. SECONDS(3723) means one hour, two specifies a 2–character mnemonic to be used to
minutes, and three seconds. determine the logical device code (LDC) to be
transmitted in the FMH to the logical unit. The
AT mnemonic identifies an LDC entry specified in the
specifies the time of the route. For the ways to enter the terminal control table TYPE=LDC.
time, see the AFTER option. When an LDC is specified, BMS uses the device type,
ERRTERM(name) the page size, and the page status associated with the
specifies the name of the terminal to be notified if the LDC mnemonic to format the message. These values
message is deleted because it is undeliverable. The are taken from the extended local LDC table for the LU,
message number, title identification, and destination are if it has one. If the LU has only a local (unextended)
indicated. If no name is specified, the originating LDC table, the values are taken from the system LDC
terminal is assumed. table. The numeric value of the LDC is obtained from

Chapter 1. Commands 239

ROUTE

the local LDC table, unless this is an unextended table The option is ignored if the device receiving the
and the value is not specified, in which case it is taken message (direct or routed) is not one of those mentioned
from the system table. above.
If the LDC option is omitted, the LDC mnemonic If this option is used, buffer updating and attribute
specified in DFHMSD is used; see “DFHMSD” on modification of fields previously written into the buffer are
page 396 for further details. If the LDC option has also not allowed. CICS includes the ERASE option with
been omitted from DFHMSD, the action depends on the every write to the terminal.
type of logical unit, as follows:
The NL character occupies a buffer position. A number
3601 LU of buffer positions, equivalent to the value of the RDO
The first entry in the local or extended local options PAGESIZE or ALTPAGE or the PGESIZE or
LDC table is used, if there is one. If a ALTPGE in the terminal control table for that terminal,
default cannot be obtained in this way, a are unavailable for data. This may cause data to wrap
null LDC numeric value (X'00') is used. around in the buffer; if this occurs, the PGESIZE value
The page size used is the value that is must be reduced.
specified in the terminal control table
OPCLASS(data-area)
TYPE=TERMINAL, or (1,40) if such a value
specifies the data area that contains a list of operator
is not specified.
classes to which the data is to be routed. The classes
LUTYPE4 LU, batch LU, or batch data interchange are supplied in a 3-byte field, each bit position
LU corresponding to one of the codes in the range 1
The local LDC table is not used to supply a through 24 but in reverse order, that is, the first byte
default LDC; instead, the message is corresponds to codes 24 through 17, the second byte to
directed to the LU console. (Here, LU codes 16 through 9, and the third byte to codes 8
console means any medium on which the through 1.
LU elects to receive such messages. For a
REQID(name)
batch data interchange LU, this does not
specifies a prefix (2–character field) to be used as part
imply sending an LDC in an FMH). The
of a temporary storage identifier for CICS message
page size is obtained in the manner
recovery. Only one prefix can be specified for each
described for the 3601 LU.
logical message. The default prefix is **.
For message routing, the LDC option of the ROUTE
BMS message recovery is provided for a logical
command takes precedence over all other sources. If
message only if the PAGING option is specified in the
this option is omitted and a route list is specified (LIST
BMS SEND commands, and if the syncpoint has been
option), the LDC mnemonic in the route list is used; if
reached.
the route list contains no LDC mnemonic, or no route list
is specified, a default LDC is chosen as described | SECONDS(data-value)
above. | specifies a fullword binary value in the range 0–59, when
| HOURS or MINUTES are also specified, or 0–359 999
LIST(data-area)
| when SECONDS is the only option specified. This is a
specifies the data area that contains a list of terminals
suboption of the AFTER and AT options. For its use
and operators to which data is to be directed. If this
and meaning, see the AFTER option.
option is omitted, all terminals supported by BMS receive
the data (unless the OPCLASS option is in effect). See TIME(hhmmss)
the CICS/ESA Application Programming Guide for the specifies the time of day at which data is to be
format of the route list. transmitted to the terminals specified in the ROUTE
command.
| MINUTES(data-value)
specifies a fullword binary value in the range 0–59, when | When using the C language, you are recommended to
HOURS or SECONDS are also specified, or 0–5999 | use the AFTER/AT HOURS, MINUTES, and SECONDS
when MINUTES is the only option specified. This is a | options as C does not provide a packed decimal data
suboption of the AFTER and AT options. For its use | type. You may use TIME, but if the value specified is
and meaning, see the AFTER option. | not an integer constant, the application is responsible for
| ensuring that the value passed to CICS is in packed
NLEOM | decimal format.
specifies that data for a 3270 printer or a 3275 display
with the printer adapter feature should be built with
blanks and new-line (NL) characters, and that an
end-of-message (EM) character should be placed at the
end of the data. As the data is printed, each NL
character causes printing to continue on the next line,
and the EM character terminates printing.

240 CICS/ESA Application Programming Reference

ROUTE

TITLE(data-area)
specifies the data area that contains the title to be used
with a routing logical message. This title appears as
part of the response to a page query command. See
the CICS/ESA Application Programming Guide for the
format of the title option.

ROUTE conditions
INVERRTERM
occurs if the terminal identifier specified in the
ERRTERM option is not valid or is assigned to a type of
terminal not supported by BMS.
Default action: terminate the task abnormally.

INVLDC
occurs if the specified LDC mnemonic is not included in
the LDC list for the logical unit.
Default action: terminate the task abnormally.

INVREQ
occurs if a request for BMS services is not valid for any
of the following reasons:

Bytes 10 through 15 of a route list entry do not

contain blanks
Hours out of range (RESP2=4)
Minutes out of range (RESP2=5)
Seconds out of range (RESP2=6)
BMS commands are not supported for distributed
program link (RESP2=200).

Default action: terminate the task abnormally.

RTEFAIL
occurs in any of the following situations:

A ROUTE command would result in the message

being sent only to the terminal that initiated the
transaction.
A ROUTE command is issued against a remote
shippable terminal that is not yet installed in the
application-owning region.

Default action: return control to the application program

at the point immediately following the ROUTE command.

RTESOME
occurs if any of the terminals specified by the ROUTE
command options do not receive the message.
Default action: return control to the application program
at the point immediately following the ROUTE command.

Chapter 1. Commands 241

SEND (VTAM)

SEND (VTAM default)

Function
Write data to a standard CICS supported terminal (BTAM or TCAM).

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬──────┬──"
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─WAIT─┘
Conditions:
INVREQ, LENGERR, NOTALLOC

SEND writes data to a terminal. This form of the send command can be used by all CICS-supported terminals for which the
other SEND descriptions are not appropriate.

SEND (APPC)

Function
Send data on an APPC mapped conversation.

Command syntax

──SEND──┬──────────────┬──┬──────────────────────────────────────────┬──┬────────┬──┬─────────┬──────────
└─CONVID(name)─┘ └─FROM(data-area)──┬─LENGTH(data-value)──┬─┘ ├─INVITE─┤ ├─CONFIRM─┤
└─FLENGTH(data-value)─┘ └─LAST───┘ └─WAIT────┘
──┬─────────────┬──"
└─STATE(cvda)─┘
Conditions:
INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

SEND sends data to a conversation partner on an APPC mapped conversation.

242 CICS/ESA Application Programming Reference

SEND (VTAM)

SEND (LUTYPE2/LUTYPE3)

Function
Write data to a 3270-display logical unit (LUTYPE2) or a 3270-printer logical unit (LUTYPE3).

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬───────────────────────────────────
└─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤
└─LAST───┘
──┬─┬──────────────────────┬──┬─────────────────────┬─┬──┬─────────┬──"
│ └─ERASE──┬───────────┬─┘ └─CTLCHAR(data-value)─┘ │ └─DEFRESP─┘
| │ ├─DEFAULT───┤ │
| │ └─ALTERNATE─┘ │
└─STRFIELD──────────────────────────────────────────┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

SEND (LUTYPE4)

Function
Write data to a LUTYPE4 logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬──┬───────────┬──┬─────┬──"
| └─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤ └─FMH─┘
└─LAST───┘ └─DEFRESP───┘
Conditions:
INVREQ, IGREQCD, LENGERR, SIGNAL, TERMERR

SEND writes data to a terminal.

Chapter 1. Commands 243

SEND (VTAM)

SEND (LUTYPE6.1)

Function
Send data on an LUTYPE6.1 conversation.

Command syntax

──SEND──┬───────────────┬──┬──────┬──┬────────┬──┬────────────────┬──┬─────────────────┬─────────────────
└─SESSION(name)─┘ └─WAIT─┘ ├─INVITE─┤ └─ATTACHID(name)─┘ └─FROM(data-area)─┘
└─LAST───┘
──┬─────────────────────┬──┬─────┬──┬─────────┬──"
├─LENGTH(data-value)──┤ └─FMH─┘ └─DEFRESP─┘
└─FLENGTH(data-value)─┘
Conditions:
CBIDERR, INVREQ, LENGERR, NOTALLOC, SIGNAL, TERMERR

SEND sends data to a conversation partner on an LUTYPE6.1 conversation.

SEND (SCS)

Function
Write data to a 3270 SCS printer logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬──┬───────────┬──┬──────────┬──────
└─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤ └─STRFIELD─┘
└─LAST───┘ └─DEFRESP───┘
──┬─────┬──"
└─FMH─┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a logical unit. The SCS printer logical unit accepts a character string as defined by Systems Network
Architecture (SNA).

244 CICS/ESA Application Programming Reference

SEND (VTAM)

SEND (3270 logical)

Function
Write data to a 3270 logical unit.

Command syntax

SEND writes data to a terminal.

SEND (3600 pipeline)

Function
Write data to a 3600 pipeline logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──"
└─FLENGTH(data-value)─┘ └─WAIT─┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

Chapter 1. Commands 245

SEND (VTAM)

SEND (3600-3601)

Function
Write data to a 3600 (3601) logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬───────────┬──┬──────┬──┬────────┬──┬───────────┬──"
└─FLENGTH(data-value)─┘ ├─LDC(name)─┤ └─WAIT─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤
└─FMH───────┘ └─LAST───┘ └─DEFRESP───┘
Conditions:
INVREQ, LENGERR, SIGNAL, TERMERR

SEND writes data to a terminal. This form of SEND also applies to the 4700 and the 3630 plant communication system.

A logical device code (LDC) is a code that can be included in an outbound FMH to specify the disposition of the data (for
example, to which subsystem terminal it should be sent). Each code can be represented by a unique LDC mnemonic.

The installation can specify up to 256 2-character mnemonics for each TCTTE, and two or more TCTTEs can share a list of
these mnemonics. Corresponding to each LDC mnemonic for each TCTTE is a numeric value (0 through 255).

A 3600 device and a logical page size are also associated with an LDC. “LDC” or “LDC value” is used in this book in
reference to the code specified by the user. “LDC mnemonic” refers to the 2-character symbol that represents the LDC
numeric value.

When the LDC option is specified, the numeric value associated with the mnemonic for the particular TCTTE, is inserted in the
FMH. The numeric value associated with the LDC mnemonic is chosen by the installation, and is interpreted by the 3601
application program.

# On output, the FMH can be built by the application program or by CICS. If your program supplies the FMH, you place it at the
# front of your output data and specify the FMH option on your SEND command. If you omit the FMH option, CICS will provide
# an FMH but you must reserve the first three bytes of the message for CICS to fill in.

SEND (3600-3614)

Function
Write data to a 3600 (3614) logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬──┬───────────┬──"
└─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤
└─LAST───┘ └─DEFRESP───┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal. The data stream and communication format used between a CICS application program and a
3614 is determined by the 3614. The application program is therefore device dependent when handling 3614 communication.

For further information about designing 3614 application programs for CICS, refer to the CICS/OS/VS IBM 4700/3600/3630
Guide.

246 CICS/ESA Application Programming Reference

SEND (VTAM)

SEND (3650 interpreter)

Function
Write data to a 3650 interpreter logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬──┬─────────┬──┬─────┬──"
└─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤ └─DEFRESP─┘ └─FMH─┘
└─LAST───┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

SEND (3650-3270)

Function
Write data to a 3650 logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬─────────────────────┬──┬──────┬──────────────────────
└─FLENGTH(data-value)─┘ └─CTLCHAR(data-value)─┘ └─WAIT─┘
──┬──────────────────────┬──┬────────┬──┬───────────┬──┬─────┬──"
└─ERASE──┬───────────┬─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤ └─FMH─┘
| ├─DEFAULT───┤ └─LAST───┘ └─DEFRESP───┘
| └─ALTERNATE─┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

Chapter 1. Commands 247

SEND (VTAM)

SEND (3650-3653)

Function
Write data to a 3650 (3653) logical unit.

Command syntax

SEND writes data to a terminal.

SEND (3650-3680)

Function
Write data to a 3650 (3680) logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬────────┬──┬───────────┬──┬─────┬──"
└─FLENGTH(data-value)─┘ └─WAIT─┘ ├─INVITE─┤ ├─CNOTCOMPL─┤ └─FMH─┘
└─LAST───┘ └─DEFRESP───┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

248 CICS/ESA Application Programming Reference

SEND (VTAM)

SEND (3767)

Function
Write data to a 3767 interactive logical unit.

Command syntax

SEND writes data to a terminal. This form of SEND also applies to the 3770 interactive logical unit.

SEND (3770)

Function
Write data to a 3770 batch logical unit.

Command syntax

SEND writes data to a terminal.

Chapter 1. Commands 249

SEND (VTAM)

SEND (3790 full-function or inquiry)

Function
Write data to a 3790 full-function or inquiry logical unit.

Command syntax

SEND writes data to a terminal. This form of SEND also applies to the following devices:
3650/3680 full-function logical unit
3770 full-function logical unit.

SEND (3790 SCS)

Function
Write data to a 3790 SCS printer logical unit.

Command syntax

SEND writes data to a terminal.

250 CICS/ESA Application Programming Reference

SEND (VTAM)

SEND (3790 3270-display)

Function
Write data to a 3790 (3270-display) logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬─────────────────────┬──┬──────┬──────────────────────
└─FLENGTH(data-value)─┘ └─CTLCHAR(data-value)─┘ └─WAIT─┘
──┬──────────────────────┬──┬────────┬──┬─────────┬──"
| └─ERASE──┬───────────┬─┘ ├─INVITE─┤ └─DEFRESP─┘
| ├─DEFAULT───┤ └─LAST───┘
| └─ALTERNATE─┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

SEND (3790 3270-printer)

Function
Write data to a 3790 (3270-printer) logical unit.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬─────────────────────┬──┬──────┬──────────────────────
└─FLENGTH(data-value)─┘ └─CTLCHAR(data-value)─┘ └─WAIT─┘
──┬──────────────────────┬──┬────────┬──┬─────────┬──"
| └─ERASE──┬───────────┬─┘ ├─INVITE─┤ └─DEFRESP─┘
| ├─DEFAULT───┤ └─LAST───┘
| └─ALTERNATE─┘
Conditions:
INVREQ, LENGERR, TERMERR

SEND writes data to a terminal.

Chapter 1. Commands 251

SEND (VTAM)

SEND (VTAM) options option is meaningful only for terminals defined using
DFHTCT TYPE=SDSCI with DEVICE=TCAM.
| ALTERNATE
If you use the DEST option, you must be aware of any
| sets the terminal to use the ALTERNATE screen size.
restrictions placed on device-dependent data streams by
ATTACHID(name) the message control facility in use. See the
specifies that an attach header (created by a BUILD programming information about the CICS-TCAM
ATTACH command) is to precede, and be concatenated interface in the CICS/ESA Customization Guide.
with, the user data supplied in the FROM option.
ERASE
“name” (1–8 characters) identifies the attach header
specifies that the screen printer buffer or partition is to
control block to be used in the local task.
be erased and the cursor returned to the upper left
CNOTCOMPL corner of the screen. (This option applies only to the
indicates that the request/response unit (RU) sent as a 3270, or 8775, and to the 3604 Keyboard Display.)
result of this SEND command does not complete the The first output operation in any transaction, or in a
chain. If this option is omitted and chain assembly has series of pseudoconversational transactions, should
been specified, the RU terminates the chain. always specify ERASE. For transactions attached to
CONFIRM | 3270 screens or printers, unless explicitly overridden by
indicates that an application using a synchronization | the DEFAULT or ALTERNATE option, this also ensures
level 1 or 2 conversation requires a response from the that the correct screen size is selected, as defined for
remote application. A remote CICS application can the transaction by the SCRNSIZE option in the profile
respond positively by executing an ISSUE definition.
CONFIRMATION command, or negatively, by executing FLENGTH(data-value)
an ISSUE ERROR command, in which case the sending A fullword alternative to LENGTH.
application has EIBERR and EIBERRCD set. CICS
does not return control to the sending application until FMH
the response is received. specifies that a function management header has been
included in the data to be written. If the ATTACHID
CONVID(name) option is specified as well, the concatenated FMH flag is
identifies the conversation to which the command # set in the attach FMH. The use of FMH is optional and
relates. The 4-character name identifies either the token # is not supported for all terminal types. If not supplied,
returned by a previously executed ALLOCATE command # CICS takes no action, except for 3600/4700 terminals,
in EIBRSRCE in the EIB, or the token representing the # where an FMH is mandatory. In this case, if FMH is not
principal session (returned by a previously executed # specified, CICS supplies one and places it in the first 3
ASSIGN command). # bytes of the message, which you must reserve for this
For compatibility with earlier releases, SESSION is # purpose.
accepted as a synonym for CONVID. New programs
FROM(data-area)
should use CONVID.
FROM(data-area)
If this option is omitted, the principal facility is assumed. specifies the data to be written to the logical unit, or a
partner transaction.
CTLCHAR(data-value)
specifies a 1-byte write control character (WCC†) that INVITE
controls a SEND command for a 3270. A COBOL user allows an application program to add control data to data
must specify a data area containing this character. If the already sent to a process in a connected APPC system.
option is omitted, all modified data tags are reset to zero Control data is not transmitted by CICS until the
and the keyboard is restored. subsequent execution of a WAIT or a SYNCPOINT
command, unless CONFIRM or WAIT is also specified;
| DEFAULT
or specifies that the next terminal control command to be
| sets the terminal to use the DEFAULT screen size.
executed for this facility is a RECEIVE, this allows
DEFRESP optimal flows to occur.
indicates that a definite response is required when the
LAST
output operation has been completed.
specifies that this is the last SEND command for a
DEST(name) transaction.
specifies the 4-byte symbolic name of the TCAM
destination to which the message is to be sent. This

† Documented in the IBM 3270 Data Stream Programmer’s Reference.

252 CICS/ESA Application Programming Reference

SEND (VTAM)

LDC(name) SEND (VTAM) conditions

specifies the 2-character mnemonic used to determine
Some of the following conditions may occur in combination.
the appropriate logical device code (LDC) numeric value.
If more than one occurs, only the first is passed to the
The mnemonic represents an LDC entry in the terminal
application program.
control table TYPE=LDC.

LENGTH(data-value) EIBRCODE, however, is set to indicate all the conditions that

specifies the length, as a halfword binary value, of the occurred.
data to be written. For a description of a safe upper CBIDERR
limit, see “LENGTH options” on page 5. occurs if the requested attach header control block
SESSION(name) named in ATTACHID cannot be found.
specifies the symbolic identifier (1–4 characters) of a Default action: terminate the task abnormally.
session TCTTE. This option specifies the alternate
facility to be used. If this option is omitted, the principal IGREQCD
facility for the task is used. occurs when an attempt is made to execute a SEND
command after a SIGNAL data-flow control command
STATE(cvda) with a request change direction (RCD) code has been
gets the state of the current conversation. The cvda received from the logical unit.
values returned by CICS are:
Default action: terminate the task abnormally.
ALLOCATED
INVREQ
CONFFREE
occurs in any of the following situations:
CONFRECEIVE
CONFSEND The CONFIRM option has been specified, but the
FREE APPC conversation is not sync level 1 or 2.
PENDFREE
The SEND command has been used on an APPC
PENDRECEIVE
conversation that is not a mapped conversation or
RECEIVE
that is not using the EXEC CICS interface.
ROLLBACK
SEND | A distributed program link server application
SYNCFREE | attempted to send on its function-shipping session
SYNCRECEIVE | (its principal facility) (RESP2=200).
SYNCSEND | For SEND (APPC), a distributed program link server
STRFIELD | application specified the function-shipping session
specifies that the data area specified in the FROM | (its principal facility) on the CONVID option
option contains structured fields. If this option is | (RESP2=200).
specified, the contents of all structured fields must be Default action: terminate the task abnormally.
handled by the application program. The CONVERSE
command, rather than a SEND command, must be used LENGERR
if the data area contains a read partition structured field. occurs if an out-of-range value is supplied in the
(Structured fields are described in the CICS/ESA 3270 | LENGTH or FLENGTH option.
Data Stream Device Guide.) Default action: terminate the task abnormally.
CTLCHAR and ERASE are mutually exclusive with
NOTALLOC
STRFIELD, and their use with STRFIELD generates an
occurs if the CONVID value in the command does not
error message.
relate to a conversation that is owned by the application,
WAIT or if the facility specified in the command is not owned
specifies that processing of the command must be by the application.
completed before any subsequent processing is Default action: terminate the task abnormally.
attempted.
SIGNAL
If the WAIT option is not specified, control is returned to
occurs when an inbound SIGNAL data-flow control
the application program when processing of the
command has been received from a logical unit or
command has started. A subsequent input or output
session. EIBSIG is always set when an inbound signal
request (terminal control, BMS, or batch data
is received.
interchange) to the terminal associated with the task
causes the application program to wait until the previous Default action: ignore the condition.
request has been completed.

Chapter 1. Commands 253

SEND (VTAM)

254 CICS/ESA Application Programming Reference

SEND (non-VTAM)

SEND (non-VTAM default)

Function
Write data to a standard CICS terminal support (BTAM or TCAM).

Command syntax

SEND writes data to a terminal. This form of the send command can be used by all CICS-supported terminals for which the
other SEND descriptions are not appropriate.

SEND (MRO)

Function
Send data on an MRO conversation.

Command syntax

──SEND──┬───────────────┬──┬──────┬──┬────────┬──┬────────────────┬──┬─────────────────┬─────────────────
└─SESSION(name)─┘ └─WAIT─┘ ├─INVITE─┤ └─ATTACHID(name)─┘ └─FROM(data-area)─┘
└─LAST───┘
──┬─────────────────────┬──┬─────┬──┬─────────┬──┬─────────────┬──"
├─LENGTH(data-value)──┤ └─FMH─┘ └─DEFRESP─┘ └─STATE(cvda)─┘
└─FLENGTH(data-value)─┘
Conditions:
CBIDERR, INVREQ, LENGERR, NOTALLOC, TERMERR

SEND sends data to a conversation partner on an MRO conversation.

Chapter 1. Commands 255

SEND (non-VTAM)

SEND (System/3)

Function
Write data to a System/3.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬──────┬──┬──────┬──┬───────────┬──"
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─WAIT─┘ └─ASIS─┘ └─CNOTCOMPL─┘
Conditions:
INVREQ, LENGERR

SEND writes data to a terminal. This form of the SEND command also applies to the following devices:
2770 data communication system
2780 data transmission terminal
3660 supermarket scanning system
3780 communication terminal.

SEND (System/7)

Function
Write data to a System/7.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬──────┬──┬───────────┬──┬──────┬──"
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─WAIT─┘ └─PSEUDOBIN─┘ └─ASIS─┘
Conditions:
INVREQ, LENGERR

SEND writes data to a terminal. For a description of running with a System/7, see “CONVERSE (System/7)” on page 54.

256 CICS/ESA Application Programming Reference

SEND (non-VTAM)

SEND (2260)

Function
Write data to a 2260 or 2265 display station.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬─────────────────────┬──┬────────────┬────────────────
└─FLENGTH(data-value)─┘ └─CTLCHAR(data-value)─┘ └─DEST(name)─┘
──┬──────────────────────┬──┬──────┬──┬─────────┬──"
└─LINEADDR(data-value)─┘ └─WAIT─┘ └─LEAVEKB─┘
Conditions:
INVREQ, LENGERR

SEND writes data to a terminal.

SEND (2741)

Function
Write data to a 2741 communication terminal.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬──────┬──"
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─WAIT─┘
Conditions:
INVREQ, LENGERR, WRBRK

SEND writes data to a terminal. For more information about using a 2741 communication terminal, see “CONVERSE (2741)”
on page 56.

Chapter 1. Commands 257

SEND (non-VTAM)

SEND (2980)

Function
Write data to a 2980 general banking terminal system.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬─PASSBK─┬──"
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─CBUFF──┘
Conditions:
INVREQ, LENGERR, NOPASSBKWR

SEND writes data to a terminal. For more information about the 2980 general banking system, see “RECEIVE (2980)” on
page 213.

SEND (3270 display)

Function
Write data to a 3270 information display system (BTAM or TCAM).

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬────────────┬──┬──────┬───────────────────────────────
└─FLENGTH(data-value)─┘ └─DEST(name)─┘ └─WAIT─┘
──┬─┬──────────────────────┬──┬─────────────────────┬─┬──"
│ └─ERASE──┬───────────┬─┘ └─CTLCHAR(data-value)─┘ │
| │ ├─DEFAULT───┤ │
| │ └─ALTERNATE─┘ │
└─STRFIELD──────────────────────────────────────────┘
Conditions:
INVREQ, LENGERR

SEND writes data to a terminal.

258 CICS/ESA Application Programming Reference

SEND (non-VTAM)

SEND (3600 BTAM)

Function
| Write data to a 3600 or 4700 finance communication system (BTAM) - only valid for remote terminals. See “BTAM
| programmable terminals” on page 358.

Command syntax

──SEND──FROM(data-area)──┬─LENGTH(data-value)──┬──┬──────┬──┬──────┬──"
└─FLENGTH(data-value)─┘ └─WAIT─┘ └─ASIS─┘
Conditions:
INVREQ, LENGERR

| SEND writes data to a terminal. This form of the SEND command also applies to the 4700 finance communication system.
| For more information about using the 3600 or 4700 finance communication system, see “CONVERSE (3600 BTAM)” on
| page 58.

SEND (3735)

Function
Write data to a 3735 Programmable Buffered Terminal.

Command syntax

SEND writes data to a terminal. The 3735 Programmable Buffered Terminal may be serviced by CICS in response to
terminal-initiated input (automatic answering), or as a result of an automatic (automatic calling) or time-initiated transaction.

For more information about the 3735, see “CONVERSE (3735)” on page 60.

Chapter 1. Commands 259

SEND (non-VTAM)

SEND (3740)

Function
Write data to a 3740 data entry system.

Command syntax

SEND writes data to a terminal. In batch mode, many files are exchanged between the 3740 and CICS in a single
transmission. The transmission of an input batch must be complete before an output transmission can be started.

260 CICS/ESA Application Programming Reference

SEND (non-VTAM)

SEND (non-VTAM) options If you use the DEST option, you must be aware of any
restrictions placed on device-dependent data streams by
| ALTERNATE the message control facility in use. See the
| sets the terminal to use the ALTERNATE screen size. programming information about the CICS-TCAM
interface in the CICS/ESA Customization Guide
ASIS
indicates that output is to be sent in transparent mode ERASE
(with no recognition of control characters and accepting specifies that the screen printer buffer or partition is to
any of the 256 possible combinations of eight bits as be erased and the cursor returned to the upper left
valid transmittable data). corner of the screen. (This option applies only to the
Note: If you are using a katakana terminal, you might 3270, or 8775, and to the 3604 Keyboard Display.)
see some messages containing mixed English and The first output operation in any transaction, or in a
katakana characters. That is because katakana series of pseudoconversational transactions, should
terminals cannot display mixed-case output. Uppercase always specify ERASE. For transactions attached to
characters in the data stream appear as uppercase | 3270 screens or printers, unless explicitly overridden by
English characters, but lowercase characters appear as | the DEFAULT or ALTERNATE option, this also ensures
katakana characters. If this happens, ask your system that the correct screen size is selected, as defined for
programmer to specify MSGCASE=UPPER in the | the transaction by the SCRNSIZE option in the profile
system initialization parameters so that messages | definition.
contain uppercase characters only.
FLENGTH(data-value)
ATTACHID(name) A fullword alternative to LENGTH.
specifies that an attach header (created by a BUILD
ATTACH command) is to precede, and be concatenated FMH
with, the user data supplied in the FROM option. specifies that a function management header has been
“name” (1–8 characters) identifies the attach header included in the data to be written. If the ATTACHID
control block to be used in the local task. option is specified as well, the concatenated FMH flag is
set in the attach FMH.
CBUFF
specifies that data is to be written to a common buffer in FROM(data-area)
a 2972 control unit. The WAIT option is implied. specifies the data to be written to the logical unit or
terminal.
CNOTCOMPL
indicates that the request/response unit (RU) sent as a INVITE
result of this SEND command does not complete the specifies that the next terminal control command to be
chain. If this option is omitted and chain assembly has executed for this facility is a RECEIVE. This allows
been specified, the RU terminates the chain. optimal flows to occur.

CTLCHAR(data-value) LAST
specifies a 1-byte write control character (WCC†) that specifies that this is the last output operation for a
controls a SEND command for a 3270. A COBOL user transaction and therefore the end of a bracket.
must specify a data area containing this character. If the LEAVEKB
option is omitted, all modified data tags are reset to zero specifies that the keyboard is to remain locked at the
and the keyboard is restored. completion of the data transfer.
| DEFAULT LENGTH(data-value)
| sets the terminal to use the DEFAULT screen size. specifies the length, as a halfword binary value, of the
DEFRESP data to be written. For a description of a safe upper
indicates that a definite response is required when the limit, see “LENGTH options” on page 5.
output operation has been completed. LINEADDR(data-value)
DEST(name) specifies that the writing is to begin on a specific line of
specifies the 4-byte symbolic name of the TCAM a 2260/2265 screen. The data value is a halfword
destination to which the message is to be sent. This binary value in the range 1 through 12 for a 2260, or 1
option is meaningful only for terminals defined using through 15 for a 2265.
DFHTCT TYPE=SDSCI with DEVICE=TCAM.

† Documented in the IBM 3270 Data Stream Programmer’s Reference.

Chapter 1. Commands 261

SEND (non-VTAM)

PASSBK INVREQ
specifies that communication is with a passbook. The | occurs if a distributed program link server application
WAIT option is implied. | attempted to send on its function-shipping session (its
| principal facility) (RESP2=200).
PSEUDOBIN (start-stop only)
specifies that the data being written is to be translated Default action: terminate the task abnormally.
from System/7 hexadecimal to pseudobinary.
LENGERR
SESSION(name) occurs if an out-of-range value is supplied in the
specifies the symbolic identifier (1–4 characters) of a | LENGTH or FLENGTH option.
session TCTTE. This option specifies the alternate Default action: terminate the task abnormally.
facility to be used. If this option is omitted, the principal
facility for the task is used. NOPASSBKWR
occurs if no passbook is present.
STATE(cvda)
| Default action: terminate the task abnormally.
gets the state of the transaction program. The cvda
values returned by CICS are: NOTALLOC
occurs if the facility specified in the command is not
ALLOCATED
owned by the application.
FREE
PENDFREE Default action: terminate the task abnormally.
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

STRFIELD
specifies that the data area specified in the FROM
option contains structured fields. If this option is
specified, the contents of all structured fields must be
handled by the application program. The CONVERSE
command, rather than a SEND command, must be used
if the data area contains a read partition structured field.
(Structured fields are described in the CICS/ESA 3270
Data Stream Device Guide.)
CTLCHAR and ERASE are mutually exclusive with
STRFIELD, and their use with STRFIELD generates an
error message.

SEND (non-VTAM) conditions

CBIDERR
occurs if the requested attach header control block
named in ATTACHID cannot be found.
Default action: terminate the task abnormally.

262 CICS/ESA Application Programming Reference

SEND CONTROL

Function
Send device controls to a terminal without map or text data. The keywords are separated into those supported by minimum,
SEND CONTROL

| ALTERNATE FRSET
| sets the terminal to use the ALTERNATE screen size. specifies that the modified data tags (MDTs) of all fields
currently in the 3270 (or partition) buffer are to be reset
CURSOR(data-value)
to the unmodified condition (that is, field reset).
specifies the location to which the 3270 or 3604 cursor
is to be returned on completion of a SEND CONTROL This allows the ATTRB operand of DFHMDF for the next
command. requested map to control the final status of fields written
or rewritten in response to a BMS command, if no other
The data value must be a halfword binary value that
attribute information has been written in the symbolic
specifies the cursor position relative to zero; the range of
map.
values that can be specified depends on the size of the
screen being used. HONEOM
specifies that the default printer line length is to be used.
If ACCUM is being used, the most recent value of
This length should be the same as that specified using
CURSOR specified is used to position the cursor.
the RDO options PAGESIZE or ALTPAGE, or PGESIZE
The value specified in the CURSOR option must be or ALTPGE in the terminal control table
positive. A negative value leads to unpredictable results. TYPE=TERMINAL, and the same as the printer platen
If this option is omitted, the cursor is positioned at width; otherwise the data may not format correctly.
position zero of the screen.
LAST
| DEFAULT specifies that this is the last output operation for a
| sets the terminal to use the DEFAULT screen size. transaction and, therefore, the end of a bracket. This
option applies to logical units only.
ERASE
specifies that the screen printer buffer or partition is to LDC(name)
be erased and the cursor returned to the upper left specifies a 2-character mnemonic to be used to
corner of the screen. (This option applies only to the determine the logical device code (LDC) to be
3270, or 8775, and to the 3604 Keyboard Display.) transmitted in the FMH to the logical unit. The
mnemonic identifies an LDC entry specified in the
The first output operation in any transaction, or in a
terminal control table TYPE=LDC.
series of pseudoconversational transactions, should
always specify ERASE. For transactions attached to When an LDC is specified, BMS uses the device type,
| 3270 screens or printers, unless explicitly overridden by the page size, and the page status associated with the
| the DEFAULT or ALTERNATE option, this also ensures LDC mnemonic to format the message. These values
that the correct screen size is selected, as defined for are taken from the extended local LDC table for the LU,
| the transaction by the SCRNSIZE option in the profile if it has one. If the LU has only a local (unextended)
| definition. LDC table, the values are taken from the system LDC
table. The numeric value of the LDC is obtained from
ERASEAUP the local LDC table, unless this is an unextended table
specifies that all unprotected character locations in the and the value is not specified, in which case it is taken
partition or the entire screen are to be erased. (This from the system table.
option applies only to the 3270 and 8775.)
| L40, L64, or L80
FORMFEED specifies the line length for a 3270 printer; a carrier
specifies that a new page is required. For 3270 printers return and line feed are forced after 40, 64, or 80
and displays, the FORMFEED character is positioned at characters have been printed on a line. Unacceptable
the start of the buffer. The application program must results are likely if this differs from the page width
thus ensure that this buffer position is not overwritten by specified by the RDO options PAGESIZE or ALTPAGE,
map or text data. It is ignored if the target terminal does or the PGESIZE or ALTPGE in the terminal control table
not support FORMFEED (that is, the RDO option TYPE=TERMINAL.
FORMFEED was not used, or the terminal control table
| When using the options, refer to CTRL on page 391 for
TYPE=TERMINAL does not specify FF=YES).
| a description of the option priority.
FREEKB
MSR(data-value)
specifies that the 3270 keyboard is to be unlocked. If
specifies the 4-byte data value that controls the 10/63
FREEKB is omitted, the keyboard remains locked.
magnetic stripe reader attached to an 8775 or 3643
Note that the keyboard lock status is maintained terminal. A set of constants is provided in DFHMSRCA
separately for each partition on a terminal that supports to assist in setting this 4-byte area. See “Magnetic slot
partitions. reader (MSR) control value constants, DFHMSRCA” on
page 377 for a complete list. This option is ignored if
the RDO option MSRCNTRL was not used, or if the

Chapter 1. Commands 265

SEND CONTROL

terminal’s control table does not specify TERMINAL

FEATURE=MSRCNTRL. specifies that the output data is to be sent to the
terminal that originated the transaction.
OUTPARTN(name)
specifies the name (1–2 characters) of the partition to WAIT
which data is to be sent. This option is ignored if the specifies that control should not be returned to the
terminal does not support partitions, or if there is no application program until the output operation has been
application partition set associated with the terminal. If completed.
there is an application partition set, and the OUTPARTN
If WAIT is not specified, control returns to the application
option is omitted, data is sent to the partition named by
program when the output operation has started. A
the PARTN operand of the DFHMSD (see “DFHMSD” on
subsequent input or output command (terminal control,
page 396) or the DFHMDI (see “DFHMDI” on page 390)
BMS, or batch data interchange) causes the application
map definition macros. If maps are not used, or if there
program to wait until the previous command has been
is no PARTN operand, the output is sent to the first
completed.
partition in the partition set.

PAGING SEND CONTROL conditions

specifies that the output data is not to be sent
immediately to the terminal, but is to be placed in IGREQCD
temporary storage and displayed in response to paging occurs when an attempt is made to execute a SEND
commands entered by the terminal operator. CONTROL command after a SIGNAL data-flow control
command with a request change direction (RCD) code
If PAGING is specified with a REQID that is defined as
has been received from an LUTYPE4 logical unit.
recoverable in the temporary storage table (TST), CICS
provides message recovery for logical messages if the Default action: terminate the task abnormally.
task has reached a syncpoint.
IGREQID
PRINT occurs if the prefix specified in the REQID option is
specifies that a print operation is to be started at a 3270 different from that established by a previous REQID
printer or at a 3275 with the printer adapter feature, or option, or by default for this logical message—REQID
that data on an LUTYPE2 (3274/76 or 3790) is to be (**).
printed on a printer allocated by the controller. If this Default action: terminate the task abnormally.
option is omitted, the data is sent to the printer buffer but
is not printed. INVLDC
occurs if the specified LDC mnemonic is not included in
REQID(name) the LDC list for the logical unit.
specifies a 2-character prefix to be used as part of a
temporary storage identifier for CICS message recovery. Default action: terminate the task abnormally.
Only one prefix can be specified for each logical INVPARTN
message. The default prefix is **. occurs if the specified partition is not defined in the
BMS message recovery is provided for a logical partition set associated with the application program.
message only if the PAGING option is specified in the Default action: terminate the task abnormally.
BMS SEND commands, and if the syncpoint has been
reached. INVREQ
occurs in any of the following situations:
SET(ptr-ref)
specifies the pointer to be set to the address of the Control information is output to the same partition or
output data. LDC as mapped data while a BMS logical message
is active. If neither partitions nor LDCs are in use,
The SET option specifies that completed pages are to
control information is output to the same device as
be returned to the application program. The pointer is
mapped data.
set to the address of a list of completed pages. See the
description of the SET option in the section about A distributed program link server application
full-function BMS in the CICS/ESA Application attempted to send on its function-shipping session
Programming Guide for more guidance on using the (its principal facility) (RESP2=200).
SET option.
Default action: terminate the task abnormally.
If TIOAPFX=YES is specified in the map definition, the
| pointer returned contains the address of the TIOA prefix.
The user data starts at offset X'0C' from the start of the
| TIOA prefix.

266 CICS/ESA Application Programming Reference

SEND CONTROL

RETPAGE
occurs if the SET option is specified and a completed
page is ready for return to the application program.
Default action: return control to the application program
at the point immediately following the BMS SEND
command.

TSIOERR
occurs if there is an irrecoverable temporary storage
input/output error.
Default action: terminate the task abnormally.

WRBRK
occurs if the command is interrupted by the terminal
operator pressing the ATTN key. It applies only to the
2741 Communication Terminal, and only if write break is
supported for CICS.
Default action: ignore the condition.

Chapter 1. Commands 267

SEND MAP

Function
Send mapped output data to a terminal. The keywords are separated into those supported by minimum, standard, and full
BMS. For further information about BMS, see the CICS/ESA Application Programming Guide.

Command syntax

──SEND MAP(name)──"

Minimum BMS:

──┬──────────────┬──┬─┬─────────────────┬──┬──────────┬──┬────────────────────┬─┬────────────────────────
└─MAPSET(name)─┘ │ └─FROM(data-area)─┘ └─DATAONLY─┘ └─LENGTH(data-value)─┘ │
# └─MAPONLY───────────────────────────────────────────────────┘
──┬──────────────────────────┬──┬──────────┬──┬──────────────────────┬──┬───────┬──┬────────┬─────────────
| └─CURSOR──┬──────────────┬─┘ └─FORMFEED─┘ ├─ERASE──┬───────────┬─┤ └─PRINT─┘ └─FREEKB─┘
| └─(data-value)─┘ │ ├─DEFAULT───┤ │
| │ └─ALTERNATE─┘ │
└─ERASEAUP─────────────┘
──┬───────┬──┬───────┬──"
└─ALARM─┘ └─FRSET─┘

Standard BMS:

──┬───────┬──┬─────────────────┬──┬───────────────┬──┬─┬────────────────┬──┬────────────────┬─┬──"
└─NLEOM─┘ └─MSR(data-value)─┘ └─FMHPARM(name)─┘ │ └─OUTPARTN(name)─┘ └─ACTPARTN(name)─┘ │
└─LDC(name)──────────────────────────────┘

Full BMS:

┌─TERMINAL──┬──────┬──┬──────┬─┐
│ └─WAIT─┘ └─LAST─┘ │ ┌─HONEOM─┐
──┬───────┬──┼──────────────────────────────┼──┬─────────────┬──┬─────────┬──┼────────┼──"
└─ACCUM─┘ ├─SET(ptr-ref)─────────────────┤ └─REQID(name)─┘ └─NOFLUSH─┘ ├─L4O────┤
└─PAGING───────────────────────┘ ├─L64────┤
└─L8O────┘
Conditions:
IGREQCD, IGREQID, INVLDC, INVMPSZ, INVPARTN, INVREQ, OVERFLOW, RETPAGE, TSIOERR, WRBRK

Apar 72253
Documentation for Apar 72253 added 16 Jun 1995 (TUCKER)

SEND MAP sends output data to a terminal. SEND MAP options

When using the SEND MAP command with any of the ACCUM
ALARM, FREEKB, FRSET, HONEOM, L40, L64, L80, or specifies that this command is one of a number of
PRINT options, see CTRL on page 391 for a description of commands that are used to build a logical message.
the option priority. The logical message is completed by a SEND PAGE
command, or deleted by a PURGE MESSAGE
See Appendix K, “BMS macro summary” on page 381 for command.
map definition.

268 CICS/ESA Application Programming Reference

SEND MAP

ACTPARTN(name) that the correct screen size is selected, as defined for

specifies the name (1–2 characters) of the partition to be | the transaction by the SCRNSIZE option in the profile
activated. Activating a partition moves the cursor into definition.
the specified partition, and unlocks the keyboard for the
ERASEAUP
specified partition.
specifies that before this page of output is displayed, all
This option is ignored if the target terminal does not unprotected character locations in the partition or the
support partitions, or if there is no application partition entire screen are to be erased. (This option applies only
set. to the 3270 and 8775.)
ALARM FMHPARM(name)
specifies that the 3270 audible alarm feature is to be specifies the name (1–8 characters) of the outboard map
activated. For logical units supporting FMHs (except to be used. (This option applies only to 3650 logical
interactive and batch logical units), ALARM instructs units with outboard formatting.)
BMS to set the alarm flag in the FMH.
FORMFEED
When using the ALARM option, refer to CTRL on page
specifies that a new page is required. For 3270 printers
391 for a description of the option priority.
and displays, the FORMFEED character is positioned at
| ALTERNATE the start of the buffer. The application program must
| sets the terminal to use the ALTERNATE screen size. thus ensure that this buffer position is not overwritten by
map or text data. It is ignored if the target terminal does
CURSOR(data-value) not support FORMFEED (that is, the RDO option
specifies the location to which the 3270 or 3604 cursor FORMFEED was not used, or the terminal control table
is to be returned upon completion of a SEND MAP TYPE=TERMINAL does not specify FF=YES).
command.
FREEKB
The data value must be a halfword binary value that
specifies that the 3270 keyboard should be unlocked
specifies the cursor position relative to zero; the range of
after the data is written. If FREEKB is omitted, the
values that can be specified depends on the size of the
keyboard remains locked.
screen being used. If no data value is specified,
symbolic cursor positioning is assumed. See the section Note that the keyboard lock status is maintained
about minimum BMS in the CICS/ESA Application separately for each partition on a terminal that supports
Programming Guide for more information about symbolic partitions.
cursor positioning. When using the FREEKB option, refer to CTRL on page
This option overrides any IC option of the ATTRB 391 for a description of the option priority.
operand of DFHMDF. If ACCUM is being used, the
FROM(data-area)
most recent value of CURSOR specified is used to
specifies the data area containing the data to be
position the cursor.
processed. If this field is not specified, the name
The value specified in the CURSOR option must be | defaults to the name of the map suffixed with an O.
positive. A negative value leads to unpredictable results. This includes the 12-byte prefix generated by the
TIOAPFX=YES option on the DFHMDI and DFHMSD
DATAONLY
BMS map definitions (see pages 395 and 401).
specifies that only application program data is to be
written. The attribute characters (3270 only) must be FRSET
specified for each field in the supplied data. If the specifies that the modified data tags (MDTs) of all fields
attribute byte in the user-supplied data is set to X'00', currently in the 3270 (or partition) buffer are to be reset
the attribute byte on the screen is unchanged. Any to the unmodified condition (that is, field reset) before
default data or attributes from the map are ignored. any map data is written to the buffer.

| DEFAULT This allows the ATTRB operand of DFHMDF for the

| sets the terminal to use the DEFAULT screen size. requested map to control the final status of fields written
or rewritten in response to a BMS command, if no other
ERASE attribute information has been written in the symbolic
specifies that the screen printer buffer or partition is to map.
be erased and the cursor returned to the upper left
When using the FRSET option refer to CTRL on page
corner of the screen. (This option applies only to the
391 for a description of the option priority.
3270, or 8775, and to the 3604 Keyboard Display.)
The first output operation in any transaction, or in a HONEOM
series of pseudoconversational transactions, should specifies that the default printer line length is to be used.
always specify ERASE. For transactions attached to This length should be the same as that specified using
| 3270 screens or printers, unless explicitly overridden by the RDO options PAGESIZE or ALTPAGE, or PGESIZE
| the DEFAULT or ALTERNATE option, this also ensures or ALTPGE in the terminal control table

Chapter 1. Commands 269

SEND MAP

TYPE=TERMINAL, and the same as the printer platen | by the TIOAPFX=YES option on the DFHMDI and
width; otherwise the data may not format correctly. DFHMSD BMS map definitions (see pages 395 and
401). For a description of a safe upper limit, see
When using the HONEOM option, refer to CTRL on
“LENGTH options” on page 5.
page 391 for a description of the option priority.
| L40, L64, or L80
LAST
specifies the line length for a 3270 printer; a carrier
specifies that this is the last output operation for a
return and line feed are forced after 40, 64, or 80
transaction and, therefore, the end of a bracket. This
characters have been printed on a line. Unacceptable
option applies to logical units only.
results are likely if this differs from the page width
LDC(name) specified by the RDO options PAGESIZE or ALTPAGE,
specifies a 2-character mnemonic to be used to or the PGESIZE or ALTPGE in the terminal control table
determine the logical device code (LDC) to be TYPE=TERMINAL.
transmitted in the FMH to the logical unit. The
When using the options, refer to CTRL on page 391 for
mnemonic identifies an LDC entry specified in the
a description of the option priority.
terminal control table TYPE=LDC.
MAP(name)
When an LDC is specified, BMS uses the device type,
specifies the name (1–7 characters) of the map to be
the page size, and the page status associated with the
used.
LDC mnemonic to format the message. These values
are taken from the extended local LDC table for the MAPONLY
logical unit, if it has one. If the logical unit has only a specifies that only default data from the map is to be
local (unextended) LDC table, the values are taken from written.
the system LDC table. The numeric value of the LDC is
obtained from the local LDC table, unless this is an MAPSET(name)
unextended table and the value is not specified, in which specifies the unsuffixed name (1–7 characters) of the
case it is taken from the system table. mapset to be used. The mapset must reside in the
| CICS program library. The mapset can be defined either
If the LDC option is omitted, the LDC mnemonic
| by using RDO or by program autoinstall when the
specified in the DFHMSD macro is used; see “DFHMSD”
| mapset is first used. If this option is not specified, the
on page 396. If the LDC option has also been omitted
| name given in the MAP option is assumed to be that of
from the DFHMSD macro, the action depends on the
| the mapset.
type of logical unit, as follows:
| The number of maps per mapset is limited to a
3601 logical unit | maximum of 9 998.
The first entry in the local or extended local
LDC table is used, if there is one. If a MSR(data-value)
default cannot be obtained in this way, a specifies the 4-byte data value that controls the 10/63
null LDC numeric value (X'00') is used. magnetic stripe reader attached to an 8775 or 3643
The page size used is the value that is terminal. A set of constants is provided in DFHMSRCA
specified in the terminal control table to assist in setting this 4-byte area. See “Magnetic slot
TYPE=TERMINAL, or (1,40) if such a value reader (MSR) control value constants, DFHMSRCA” on
is not specified. page 377 for a complete list. This option is ignored if
the RDO option MSRCNTRL was not used, or if the
LUTYPE4 logical unit, batch logical unit, or batch
terminal’s control table does not specify
data interchange logical unit
FEATURE=MSRCNTRL.
The local LDC table is not used to supply a
default LDC; instead, the message is NLEOM
directed to the logical unit console (that is, specifies that data for a 3270 printer or a 3275 display
to any medium that the logical unit elects to with the printer adapter feature should be built with
receive such messages). For a batch data blanks and new-line (NL) characters, and that an
interchange logical unit, this does not imply end-of-message (EM) character should be placed at the
sending an LDC in an FMH. The page size end of the data. As the data is printed, each NL
is obtained in the manner described for the character causes printing to continue on the next line,
3601 logical unit. and the EM character terminates printing.

LENGTH(data-value) This option must be specified in the first SEND MAP

specifies the length of the data to be formatted as a command used to build a logical message. The option
halfword binary value. is ignored if the device receiving the message (direct or
routed) is not one of those mentioned above.
If the data area sending the map is longer than the data
to be mapped, LENGTH should be specified. This If this option is used, buffer updating and attribute
should include the length of the 12-byte prefix generated modification of fields previously written into the buffer are

270 CICS/ESA Application Programming Reference

SEND MAP

not allowed. CICS includes the ERASE option with SET(ptr-ref)

every write to the terminal. specifies the pointer to be set to the address of the input
or output data.
The NL character occupies a buffer position. A number
of buffer positions, equivalent to the value of the RDO The SET option specifies that completed pages are to
options PAGESIZE or ALTPAGE, or PGESIZE or be returned to the application program. The pointer is
ALTPGE in the terminal control table TYPE=TERMINAL set to the address of a list of completed pages. See the
for that terminal, is unavailable for data. This may cause description of the SET option in the section on full BMS
data to wrap around in the buffer; if this occurs, the in the CICS/ESA Application Programming Guide for
PGESIZE value must be reduced. more guidance about using the SET option.
The NLEOM option overrides the ALARM option if the The application program regains control either
latter is present. immediately following the SEND MAP command (if the
current page is not yet completed), or at the label
NOFLUSH
specified in a HANDLE CONDITION RETPAGE
specifies that CICS does not clear pages on completion
command, if the page has been completed.
but returns control to the program (having set the
OVERFLOW condition in EIBRESP). If TIOAPFX=YES is specified in the map definition, the
pointer returned contains the address of the TIOA prefix.
OUTPARTN(name) The user data starts at offset X'0C' from the start of the
specifies the name (1–2 characters) of the partition to TIOA prefix.
which data is to be sent. This option is ignored if the
terminal does not support partitions, or if there is no TERMINAL
application partition set associated with the terminal. If specifies that the output data is to be sent to the
there is an application partition set, and the OUTPARTN terminal that originated the transaction.
option is omitted, data is sent to the partition named by
WAIT
the PARTN operand of the DFHMSD or DFHMDI map
specifies that control should not be returned to the
definitions. If maps are not used, or if there is no
application program until the output operation has been
PARTN operand, the output is sent to the first partition in
completed.
the partition set.
If WAIT is not specified, control returns to the application
PAGING program when the output operation has started. A
specifies that the output data is not to be sent subsequent input or output command (terminal control,
immediately to the terminal, but is to be placed in BMS, or batch data interchange) causes the application
temporary storage and displayed in response to paging program to wait until the previous command has been
commands entered by the terminal operator. completed.
If PAGING is specified with a REQID that is defined as
recoverable in the temporary storage table (TST), CICS SEND MAP conditions
provides message recovery for logical messages if the
task has reached a syncpoint. Some of the following conditions may occur in combination.
If more than one occurs, only the first is passed to the
PRINT
application program.
specifies that a print operation is to be started at a 3270
printer or at a 3275 with the printer adapter feature, or IGREQCD
that data on an LUTYPE2 (3274/76 or 3790) is to be occurs when an attempt is made to execute a SEND
printed on a printer allocated by the controller. If this MAP command after a SIGNAL data-flow control
option is omitted, the data is sent to the printer buffer but command with a request change direction (RCD) code
is not printed. has been received from an LUTYPE4 logical unit.
When using the PRINT option, refer to CTRL on page Default action: terminate the task abnormally.
391 for a description of the option priority.
IGREQID
REQID(name) occurs if the prefix specified in the REQID option on the
specifies a 2-character prefix to be used as part of a SEND MAP command is different from that established
temporary storage identifier for CICS message recovery. by a previous REQID option, or by default for this logical
Only one prefix can be specified for each logical message—REQID (**).
message. The default prefix is **.
Default action: terminate the task abnormally.
BMS message recovery is provided for a logical
message only if the PAGING option is specified in the INVLDC
BMS SEND commands and if the syncpoint has been occurs if the specified LDC mnemonic is not included in
reached. the LDC list for the logical unit.
Default action: terminate the task abnormally.

Chapter 1. Commands 271

SEND MAP

INVMPSZ Default action: return control to the application program

occurs if the specified map is too wide for the terminal, at the point immediately following the BMS SEND MAP
or if a HANDLE CONDITION OVERFLOW command is command.
active and the specified map is too long for the terminal.
Default action: terminate the task abnormally.

INVPARTN
occurs if the specified partition is not defined in the
partition set associated with the application program.
Default action: terminate the task abnormally.

INVREQ
occurs if a request for BMS services is not valid for any
of the following reasons:

Text data is output to the same partition or LDC as

mapped data while a BMS logical message is
active. If neither partitions nor LDCs are in use, text
data is output to the same logical message as
mapped data.
A separate SEND MAP command with the ACCUM
option is issued to the terminal that originated the
transaction while a routed logical message is being
built.
A SEND MAP command is issued for a map without
field specifications by specifying the FROM option
without the DATAONLY option.
During overflow processing, data is sent to a
different LDC from the LDC that caused page
overflow.
Partitions are in use, the OUTPARTN option has not
been coded on the SEND MAP command, but the
PARTN operand has been coded in the mapset
definition. If the condition arises, it suggests that
different versions of the mapset have different
PARTN values, and that the suffix deduced for the
partition is not the same as the suffix of the loaded
mapset.
Command not allowed for a distributed program link
server program (RESP2=200).
| A SEND MAP command with the DATAONLY option
| is issued with a data area, supplied by the user, that
| resides above the 16MB line. But the length of this
| data area is not longer than the TIOA prefix.

Default action: terminate the task abnormally.

OVERFLOW
occurs if the mapped data does not fit on the current
page. This condition is only raised if a HANDLE
CONDITION OVERFLOW command is active.
Default action: ignore the condition.

RETPAGE
occurs if the SET option is specified and a completed
page is ready for return to the application program.

272 CICS/ESA Application Programming Reference

SEND MAP

TSIOERR
occurs if there is an irrecoverable temporary storage
input/output error.
Default action: terminate the task abnormally.

WRBRK
occurs if a SEND MAP command is interrupted by the
terminal operator pressing the ATTN key. It applies only
to the 2741 Communication Terminal, and only if write
break is supported for CICS.
Default action: ignore the condition.

Chapter 1. Commands 273

SEND MAP MAPPINGDEV

# SEND MAP MAPPINGDEV

# Function
# Create mapped output data formatted for the terminal described by MAPPINGDEV.
# Apar PQ06521
# SEND MAP MAPPINGDEV added by APAR PQ06521 12/08/97

# Command syntax
# Minimum BMS:

#
# ──SEND MAP(name)──MAPPINGDEV(data-value)──SET(ptr-ref)──┬──────────────┬─────────────────────────────
# └─MAPSET(name)─┘
# ──┬─┬─────────────────┬──┬──────────┬──┬────────────────────┬─┬──┬──────────────────────────┬─────────
# │ └─FROM(data-area)─┘ └─DATAONLY─┘ └─LENGTH(data-value)─┘ │ └─CURSOR──┬──────────────┬─┘
# └─MAPONLY───────────────────────────────────────────────────┘ └─(data-value)─┘
# ──┬──────────┬──┬──────────┬──┬───────┬──┬────────┬──┬───────┬──┬───────┬──"
# └─FORMFEED─┘ ├─ERASE────┤ └─PRINT─┘ └─FREEKB─┘ └─ALARM─┘ └─FRSET─┘
# └─ERASEAUP─┘

# Conditions: INVMPSZ, INVREQ

#
# Usage # about minimum BMS in the information about symbolic
# cursor positioning.
# SEND MAP MAPPINGDEV creates mapped output data
# This option overrides any IC option of the ATTRB
# formatted for a terminal that may not be the principal facility
# operand of DFHMDF.
# of the transaction. The terminal characteristics to be used
# are defined by MAPPINGDEV. # The value specified in the CURSOR option must be
# positive. A negative value leads to unpredictable results.
# The mapped data is not transmitted but is returned to the
# application in a buffer defined by the SET option. # DATAONLY
# specifies that only application program data is to be
# written. The attribute characters (3270 only) must be
# Parameters # specified for each field in the supplied data. If the
# attribute byte in the user-supplied data is set to X'00',
# ALARM # the attribute byte on the screen is unchanged. Any
# specifies that the 3270 audible alarm feature is to be # default data or attributes from the map are ignored.
# activated. For logical units supporting FMHs (except
# interactive and batch logical units), ALARM instructs # ERASE
# BMS to set the alarm flag in the FMH. # specifies that the screen printer buffer is to be erased
# and the cursor returned to the upper left corner of the
# When using the ALARM option, refer to CTRL on page
# screen. (This option applies only to the 3270, or 8775)
# 391 for a description of the option priority.
# The first output operation in any transaction, or in a
# CURSOR(data-value) # series of pseudoconversational transactions, should
# specifies the location to which the 3270 cursor is to be # always specify ERASE. For transactions attached to
# returned upon completion of a SEND MAP # 3270 screens or printers, this also ensures that the
# MAPPINGDEV command. # correct screen size is selected, as defined for the
# The data value must be a halfword binary value that # transaction by the SCRNSIZE option in the RDO
# specifies the cursor position relative to zero; the range of # PROFILE definition.
# values that can be specified depends on the size of the
# ERASEAUP
# screen being used. If no data value is specified,
# specifies that before this page of output is displayed, all
# symbolic cursor positioning is assumed. See the section
# unprotected character locations in the entire screen are

274 CICS/ESA Application Programming Reference

SEND MAP MAPPINGDEV

# to be erased. (This option applies only to the 3270 and # MAPPED command or a terminal control SEND or
# 8775.) # CONVERSE.

# FORMFEED # MAPONLY
# specifies that a new page is required. For 3270 printers # specifies that only default data from the map is to be
# and displays, the FORMFEED character is positioned at # written.
# the start of the buffer. The application program must
# MAPSET(name)
# thus ensure that this buffer position is not overwritten by
# specifies the unsuffixed name (1–7 characters) of the
# map or text data. It is ignored if the target terminal does
# mapset to be used. The mapset must reside in the
# not support FORMFEED (that is, the RDO TYPETERM
# CICS program library. The mapset can be defined either
# option FORMFEED was not used, or the terminal control
# by using RDO or by program autoinstall when the
# table TYPE=TERMINAL does not specify FF=YES).
# mapset is first used. If this option is not specified, the
# FREEKB # name given in the MAP option is assumed to be that of
# specifies that the 3270 keyboard should be unlocked # the mapset.
# after the data is written. If FREEKB is omitted, the
# The number of maps per mapset is limited to a
# keyboard remains locked.
# maximum of 9 998.
# When using the FREEKB option, refer to CTRL on page
# PRINT
# 391 for a description of the option priority.
# specifies that a print operation is to be started at a 3270
# FROM(data-area) # printer or at a 3275 with the printer adapter feature, or
# specifies the data area containing the data to be # that data on an LUTYPE2 (3274/76 or 3790) is to be
# processed. If this field is not specified, the name # printed on a printer allocated by the controller. If this
# defaults to the name of the map suffixed with an O. # option is omitted, the data is sent to the printer buffer but
# This includes the 12-byte prefix generated by the # is not printed.
# TIOAPFX=YES option on the DFHMDI and DFHMSD
# When using the PRINT option, refer to CTRL on page
# BMS map definitions (see pages 395 and 401).
# 391 for a description of the option priority.
# FRSET
# SET(ptr-ref)
# specifies that the modified data tags (MDTs) of all fields
# specifies the pointer to be set to the address of the
# currently in the 3270 buffer are to be reset to the
# mapped data.
# unmodified condition (that is, field reset) before any map
# data is written to the buffer. # The storage area containing the mapped data has the
# same format as the page buffer returned when using the
# This allows the ATTRB operand of DFHMDF for the
# SET option in the full BMS SEND command. See the
# requested map to control the final status of fields written
# description of the MAPPINGDEV facility in the
# or rewritten in response to a BMS command, if no other
# attribute information has been written in the symbolic
# map. # Error Conditions
# When using the FRSET option refer to CTRL on page # Some of the following conditions may occur in combination.
# 391 for a description of the option priority. # If more than one occurs, only the first is passed to the
# LENGTH(data-value) # application program.
# specifies the length of the data to be formatted as a # INVMPSZ
# halfword binary value. # occurs if the specified map is too wide for the terminal
# If the data area sending the map is longer than the data # specified by MAPPINGDEV or if a HANDLE CONDITION
# to be mapped, LENGTH should be specified. This # OVERFLOW command is active and the specified map
# should include the length of the 12-byte prefix generated # is too long for the terminal specified by MAPPINGDEV.
# by the TIOAPFX=YES option on the DFHMDI and # Default action: terminate the task abnormally.
# DFHMSD BMS map definitions (see pages 395 and
# 401). For a description of a safe upper limit, see # INVREQ
# “LENGTH options” on page 5. # occurs if the terminal specified by MAPPINGDEV does
# not exist, does not support BMS, or is not a 3270 printer
# MAP(name) # or display.
# specifies the name (1–7 characters) of the map to be
# used. # Default action: terminate the task abnormally.

# MAPPINGDEV(data-value)
# specifies the name of a 3270 terminal whose BMS
# characteristics match those of the terminal to which the
# data will eventually be sent using a SEND TEXT

Chapter 1. Commands 275

SEND PAGE

Function
| Send last page of data. Only supplied by full BMS. For further information about BMS, see the CICS/ESA Application
Programming Guide.

Command syntax

──SEND PAGE──┬─RELEASE──┬───────────────┬─┬──┬────────────────────┬──┬──────────────┬────────────────────
│ └─TRANSID(name)─┘ │ └─TRAILER(data-area)─┘ └─SET(ptr-ref)─┘
└─RETAIN─────────────────────┘
──┬───────────────────────┬──┬───────────┬──┬───────────────┬──┬──────┬──"
├─AUTOPAGE──┬─────────┬─┤ └─OPERPURGE─┘ └─FMHPARM(name)─┘ └─LAST─┘
│ ├─CURRENT─┤ │
│ └─ALL─────┘ │
└─NOAUTOPAGE────────────┘
Conditions:
IGREQCD, INVREQ, RETPAGE, TSIOERR, WRBRK

SEND PAGE completes a BMS logical message. It causes AUTOPAGE is assumed for 3270 printers; it does not
BMS to generate a device-dependent data stream for the last apply to 3270 display terminals. If neither AUTOPAGE
(perhaps the only) page of data. Typically, this last page is nor NOAUTOPAGE is specified, the terminal has the
only partially full. paging status specified for it using the terminal control
table TYPE=TERMINAL or the RDO option AUTOPAGE.
Options can be included to specify how much control the
terminal operator should have over the disposition of the CURRENT
logical message (AUTOPAGE, NOAUTOPAGE, and specifies that if the ATTN key on a 2741 is pressed
OPERPURGE), to determine whether control should return to while a BMS logical message is being sent to the
the application program after transmission of the logical terminal, and the WRBRK condition is not active,
message (RELEASE or RETAIN), to add trailer data to a text transmission of the current page is to cease and
logical message (TRAILER), and to return the transmission of the next page (if any) is to begin.
device-dependent data stream for the last page of a logical
FMHPARM(name)
message to the application program (SET). If this is a
specifies the name (1–8 characters) of the outboard map
paging message, the last page of the logical message is
to be used. This option applies only to 3650 logical
transmitted to temporary storage and the terminal operator
units with outboard formatting.
paging transaction is initiated. If it is a terminal logical
message, the last page is transmitted to the terminal. LAST
specifies that this is the last output operation for a
This is supported by full BMS only. transaction and, therefore, the end of a bracket. If
RELEASE is specified, LAST is assumed unless the
SEND PAGE options SEND PAGE command is terminating a routing
operation. This option applies to logical units only.
ALL
specifies that if the ATTN key on a 2741 is pressed NOAUTOPAGE
while a BMS logical message is being sent to the specifies that pages of a BMS logical message are to be
terminal, and the WRBRK condition is not active, sent one at a time to the terminal. BMS sends the first
transmission of the current page is to cease and no page to the terminal when the terminal becomes
additional pages are to be transmitted. The logical available or on request of the terminal operator.
message is deleted. Subsequent pages are sent to the terminal in response
to requests from the terminal operator. (Refer to the
AUTOPAGE CICS/ESA CICS-Supplied Transactions for more
specifies that each page of a BMS logical message is to information about terminal operator paging commands.)
be sent to the terminal as soon as it is available. If
If automatic paging is specified for the terminal by the
paging on request is specified for the terminal by the
PGESTAT operand of the terminal control table
PGESTAT operand of the terminal control table
TYPE=TERMINAL, NOAUTOPAGE overrides it for this
TYPE=TERMINAL, or the RDO option AUTOPAGE(NO),
logical message. For logical units, NOAUTOPAGE
AUTOPAGE overrides it for this logical message.
applies to all pages for all LDCs in the logical message.

276 CICS/ESA Application Programming Reference

SEND PAGE

NOAUTOPAGE does not apply to 3270 printers. If this option is specified in a program that is not at the
highest logical level, the specified transaction identifier is
OPERPURGE
used only if a new transaction identifier is not provided in
specifies that CICS is to delete the BMS logical
another SEND PAGE command (or in a RETURN
message only when the terminal operator requests
program control command) issued in a program at a
deletion. If the option is omitted, CICS deletes the
higher logical level.
message if the operator enters data that is not a paging
command.
SEND PAGE conditions
RELEASE
specifies that, after the SEND PAGE command, control IGREQCD
is to be returned to CICS. occurs when an attempt is made to execute a SEND
PAGE command after a SIGNAL data-flow control
RETAIN command with a request change direction (RCD) code
specifies that after the SEND PAGE command, control is has been received from an LUTYPE4 logical unit.
returned to the application program when the operator
has finished displaying the pages. Default action: terminate the task abnormally.

SET(ptr-ref) INVREQ
specifies the pointer to be set to the address of the occurs if a request for BMS services is not valid for any
output data. of the following reasons:

The SET option specifies that the last or only page is The disposition (TERMINAL, PAGING, or SET) of a
returned to the application program. The pointer is set BMS logical message is changed prior to its
| to the address of the current page. A list of addresses completion by the SEND PAGE command.
| is created and, if the ROUTE command is in operation, Text data is output to the same partition or LDC as
| there is an address entry for each device. If the ROUTE mapped data while a BMS logical message is
| command is not in operation, the list contains only the active. If neither partitions nor LDCs are in use, text
| one entry. See the description of the SET option in the data is output to the same logical message as
section about full BMS in the CICS/ESA Application mapped data.
Programming Guide for more guidance on using the
SET option. The TRAILER option is specified when terminating a
logical message built with SEND MAP commands
The application program regains control either only.
immediately following the SEND PAGE command (if the
current page is not yet completed), or at the label During overflow processing data is sent to a
specified in a HANDLE CONDITION RETPAGE different LDC from the LDC that caused page
command if the page has been completed. overflow.

If TIOAPFX=YES is specified in the map definition, the The length of the trailer is negative.
| pointer returned contains the address of the TIOA prefix. Command not allowed for a distributed program link
| The user data starts at offset X'0C' from the start of the server program (RESP2=200).
| TIOA prefix.
Default action: terminate the task abnormally.
TRAILER(data-area)
| specifies the text data area that contains trailer data to RETPAGE
| be placed at the bottom of the last page only. The occurs if the SET option is specified and the last or only
| format of the trailer is: completed page is ready for return to the application
program.
| 2 bytes Binary length of the data (n)
Default action: return control to the application program
| 2 bytes Binary zero
at the point immediately following the BMS SEND PAGE
| n bytes Data.
command.
| See the CICS/ESA Application Programming Guide for
TSIOERR
| more information.
occurs if there is an irrecoverable temporary storage
TRANSID(name) input/output error.
specifies the transaction identifier (1–4 alphanumeric Default action: terminate the task abnormally.
characters) to be used with the next input message from
the terminal the task is attached to. The identifier must WRBRK
have been defined using the appropriate RDO program occurs if the SEND PAGE command is interrupted by
definition. TRANSID is valid only if SEND PAGE the terminal operator pressing the ATTN key. It applies
RELEASE is specified. only to the 2741 Communication Terminal, and only if
write break is supported for CICS.

Chapter 1. Commands 277

SEND PAGE

Default action: ignore the condition.

278 CICS/ESA Application Programming Reference

SEND PARTNSET

Function
This command is available on standard and full BMS only. For further information about BMS, see the CICS/ESA Application
Programming Guide.

Command syntax

──SEND PARTNSET──┬────────┬──"
└─(name)─┘
Conditions:
INVPARTNSET, INVREQ

SEND PARTNSET associates the partition set specified by

the PARTNSET option with the application program. If the
partition set name is omitted, the terminal is reset to the base
(unpartitioned) state.
Note: A SEND PARTNSET command must not be followed
immediately by a RECEIVE command. The two commands
must be separated by a SEND MAP, SEND TEXT, or SEND
CONTROL command, so that the partition set is sent to the
terminal.

SEND PARTNSET conditions

The following conditions may occur together. If both occur,
only the first one is passed to the application program.

INVPARTNSET
occurs if the partition set named in the SEND
PARTNSET command is not a valid partition set (for
example, it may be a mapset).
Default action: terminate the task abnormally.

INVREQ
occurs in any of the following situations:

A SEND PARTNSET command is issued while a

logical message is active.
Command not allowed for a distributed program link
server program (RESP2=200).

Default action: terminate the task abnormally.

Chapter 1. Commands 279

SEND TEXT

Function
Send data without mapping. The keywords are separated into those supported by standard and full BMS. For further
information about BMS, see the CICS/ESA Application Programming Guide.

Command syntax

──SEND TEXT──"

Standard BMS:

──FROM(data-area)──┬────────────────────┬──┬────────────────────┬──┬──────────┬──────────────────────────
└─LENGTH(data-value)─┘ └─CURSOR(data-value)─┘ └─FORMFEED─┘
──┬──────────────────────┬──┬───────┬──┬────────┬──┬───────┬──┬───────┬──┬───────────────┬────────────────
| └─ERASE──┬───────────┬─┘ └─PRINT─┘ └─FREEKB─┘ └─ALARM─┘ └─NLEOM─┘ └─FMHPARM(name)─┘
| ├─DEFAULT───┤
| └─ALTERNATE─┘
──┬─┬────────────────┬──┬────────────────┬─┬──┬─────────────────┬──"
│ └─OUTPARTN(name)─┘ └─ACTPARTN(name)─┘ │ └─MSR(data-value)─┘
└─LDC(name)──────────────────────────────┘

Full BMS:

┌─TERMINAL──┬──────┬──┬──────┬─┐
│ └─WAIT─┘ └─LAST─┘ │
──┼──────────────────────────────┼──┬─────────────┬──┬───────────────────┬──┬────────────────────┬───────
├─SET(ptr-ref)─────────────────┤ └─REQID(name)─┘ └─HEADER(data-area)─┘ └─TRAILER(data-area)─┘
└─PAGING───────────────────────┘
┌─HONEOM─┐
──┬─────────────────────┬──┬───────┬──┼────────┼──"
├─JUSTIFY(data-value)─┤ └─ACCUM─┘ ├─L4O────┤
├─JUSFIRST────────────┤ ├─L64────┤
└─JUSLAST─────────────┘ └─L8O────┘
Conditions:
IGREQCD, IGREQID, INVLDC, INVPARTN, INVREQ, LENGERR, RETPAGE, TSIOERR, WRBRK

SEND TEXT sends text data without mapping. The text is SEND TEXT options
split into lines of the same width as the terminal, such that
words are not broken across line boundaries. If the text ACCUM
exceeds a page, it is split into pages that fit on the terminal specifies that this command is one of a number of
with application-defined headers and trailers. commands that are used to build a logical message.
The logical message is completed by a SEND PAGE
When using the SEND TEXT command with any of the command, or deleted by a PURGE MESSAGE
ALARM, FREEKB, FRSET, HONEOM, L40, L64, L80, or command.
PRINT options, see CTRL on page 391 for a description of
ACTPARTN(name)
the option priority.
specifies the name (1–2 characters) of the partition to be
activated. Activating a partition moves the cursor into
the specified partition, and unlocks the keyboard for the
specified partition.
This option is ignored if the target terminal does not
support partitions, or if there is no application partition
set.

280 CICS/ESA Application Programming Reference

SEND TEXT

ALARM ACCUM command, use the JUSFIRST option (see

specifies that the 3270 audible alarm feature is to be below) instead.
activated. For logical units supporting FMHs (except
FREEKB
interactive and batch logical units), ALARM instructs
specifies that the 3270 keyboard should be unlocked
BMS to set the alarm flag in the FMH.
after the data is written. If FREEKB is omitted, the
| ALTERNATE keyboard remains locked.
| sets the terminal to use the ALTERNATE screen size.
When using the FREEKB option, refer to CTRL on page
CURSOR(data-value) 391 for a description of the option priority.
specifies the location to which the 3270 or 3604 cursor Note that the keyboard lock status is maintained
is to be returned on completion of a SEND TEXT separately for each partition on a terminal that supports
command. partitions.
The data value must be a halfword binary value that
FROM(data-area)
specifies the cursor position relative to zero; the range of
specifies the data area containing the data to be sent.
values that can be specified depends on the size of the
screen being used. HEADER(data-area)
specifies the header data to be placed at the beginning
This option overrides any IC option of the ATTRB
of each page of text data. The format of the header is:
operand of DFHMDF. If ACCUM is being used, the
most recent value of CURSOR specified is used to 2 bytes Binary length of the data (n)
position the cursor. | 1 byte Page numbering required or not (blank)
The value specified in the CURSOR option must be | 1 byte Reserved field
positive. A negative value leads to unpredictable results. n bytes Data

| DEFAULT See the CICS/ESA Application Programming Guide for

| sets the terminal to use the DEFAULT screen size. more information.

ERASE HONEOM
specifies that the screen printer buffer or partition is to specifies that the default printer line length is to be used.
be erased and the cursor returned to the upper left This length should be the same as that specified using
corner of the screen. (This option applies only to the the RDO options PAGESIZE or ALTPAGE, or PGESIZE
3270, or 8775, and to the 3604 Keyboard Display.) or ALTPGE in the terminal control table
TYPE=TERMINAL, and the same as the printer platen
The first output operation in any transaction, or in a
width; otherwise the data may not format correctly.
series of pseudoconversational transactions, should
always specify ERASE. For transactions attached to When using the HONEOM option, refer to CTRL on
| 3270 screens or printers, unless explicitly overridden by page 391 for a description of the option priority.
| the DEFAULT or ALTERNATE option, this also ensures
JUSFIRST
that the correct screen size is selected, as defined for
specifies that the text data is to be placed at the top of
| the transaction by the SCRNSIZE option in the profile
the page. Any partially formatted page from previous
| definition.
requests is considered to be complete. If the HEADER
| FMHPARM(name) option is specified, the header precedes the data. See
| specifies the name (1–8 characters) of the outboard map also the description of the JUSTIFY option.
| to be used. (This option applies only to 3650 logical
JUSLAST
| units with outboard formatting.)
specifies that the text data is to be positioned at the
FORMFEED bottom of the page. The page is considered to be
specifies that a new page is required. For 3270 printers complete after the request has been processed. If the
and displays, the FORMFEED character is positioned at TRAILER option is specified, the trailer follows the data.
the start of the buffer. The application program must See also the description of the JUSTIFY option.
thus ensure that this buffer position is not overwritten by
JUSTIFY(data-value)
map or text data. It is ignored if the target terminal does
specifies the line of the page at which the text data is to
not support FORMFEED (that is, the RDO option
be positioned. The data value must be a halfword
FORMFEED was not used, or the terminal control table
binary value in the range 1 through 240. Although they
TYPE=TERMINAL does not specify FF=YES).
may not be specified as constants, the special values −1
The FORMFEED option can appear on any SEND TEXT and −2 can be supplied dynamically to signify JUSFIRST
ACCUM command. You need only specify it once within or JUSLAST, respectively.
a physical page because it always forces a FORMFEED
at the start of the physical page. To force a
FORMFEED at the start of a particular SEND TEXT

Chapter 1. Commands 281

SEND TEXT

LAST is ignored if the device receiving the message (direct or

specifies that this is the last output operation for a routed) is not one of those mentioned above.
transaction and, therefore, the end of a bracket. This
If this option is used, buffer updating and attribute
option applies to logical units only.
modification of fields previously written into the buffer are
LDC(name) not allowed. CICS includes the ERASE option with
specifies a 2-character mnemonic to be used to every write to the terminal.
determine the logical device code (LDC) to be The NL character occupies a buffer position. A number
transmitted in the FMH to the logical unit. The of buffer positions, equivalent to the value of the RDO
mnemonic identifies an LDC entry specified in the options PAGESIZE or ALTPAGE, or PGESIZE or
terminal control table TYPE=LDC. ALTPGE in the terminal control table TYPE=TERMINAL
When an LDC is specified, BMS uses the device type, for that terminal, is unavailable for data. This may cause
the page size, and the page status associated with the data to wrap around in the buffer; if this occurs, the
LDC mnemonic to format the message. These values PGESIZE value must be reduced.
are taken from the extended local LDC table for the The NLEOM option overrides the ALARM option if the
logical unit, if it has one. If the logical unit has only a latter is present.
local (unextended) LDC table, the values are taken from
the system LDC table. The numeric value of the LDC is OUTPARTN(name)
obtained from the local LDC table, unless this is an specifies the name (1–2 characters) of the partition to
unextended table and the value is not specified, in which which data is to be sent. This option is ignored if the
case it is taken from the system table. terminal does not support partitions, or if there is no
application partition set associated with the terminal. If
LENGTH(data-value) there is an application partition set, and the OUTPARTN
specifies the length of the data to be sent as a halfword option is omitted, data is sent to the partition named by
binary value. For a description of a safe upper limit, see the PARTN operand of the DFHMSD or DFHMDI map
“LENGTH options” on page 5. definition. If maps are not used, or if there is no PARTN
operand, the output is sent to the first partition in the
| L40, L64, or L80
partition set.
specifies the line length for a 3270 printer; a carrier
return and line feed are forced after 40, 64, or 80 PAGING
characters have been printed on a line. Unacceptable specifies that the output data is not to be sent
results are likely if this differs from the page width immediately to the terminal, but is to be placed in
specified by the RDO options PAGESIZE or ALTPAGE, temporary storage and displayed in response to paging
or the PGESIZE or ALTPGE in the terminal control table commands entered by the terminal operator.
TYPE=TERMINAL.
If PAGING is specified with a REQID that is defined as
When using the options, refer to CTRL on page 391 for recoverable in the temporary storage table (TST), CICS
a description of the option priority. provides message recovery for logical messages if the
task has reached a syncpoint.
MSR(data-value)
specifies the 4-byte data value that controls the 10/63 PRINT
magnetic stripe reader attached to an 8775 or 3643 specifies that a print operation is to be started at a 3270
terminal. A set of constants is provided in DFHMSRCA printer or at a 3275 with the printer adapter feature, or
to assist in setting this 4-byte area. See “Magnetic slot that data on an LUTYPE2 (3274/76 or 3790) is to be
reader (MSR) control value constants, DFHMSRCA” on printed on a printer allocated by the controller. If this
page 377 for a complete list. This option is ignored if option is omitted, the data is sent to the printer buffer but
the RDO option MSRCNTRL was not used, or if the is not printed.
terminal’s control table does not specify
When using the PRINT option, refer to CTRL on page
FEATURE=MSRCNTRL.
391 for a description of the option priority.
NLEOM
REQID(name)
specifies that data for a 3270 printer or a 3275 display
specifies a 2-character prefix to be used as part of a
with the printer adapter feature should be built with
temporary storage identifier for CICS message recovery.
blanks and new-line (NL) characters, and that an
Only one prefix can be specified for each logical
end-of-message (EM) character should be placed at the
message. The default prefix is **.
end of the data. As the data is printed, each NL
character causes printing to continue on the next line, BMS message recovery is provided for a logical
and the EM character terminates printing. message only if the PAGING option is specified in the
BMS SEND commands and if the syncpoint has been
This option must be specified in the first SEND TEXT
reached.
command used to build a logical message. The option

282 CICS/ESA Application Programming Reference

SEND TEXT

SET(ptr-ref) Default action: terminate the task abnormally.

specifies the pointer to be set to the address of the data.
INVLDC
It specifies that completed pages are to be returned to
occurs if the specified LDC mnemonic is not included in
the application program. The pointer is set to the
the LDC list for the logical unit.
address of a list of completed pages. See the
description of the SET option in the section full-function Default action: terminate the task abnormally.
BMS in the CICS/ESA Application Programming Guide
INVPARTN
for more guidance about using the SET option.
occurs if the specified partition is not defined in the
The application program regains control either partition set associated with the application program.
immediately following the BMS SEND command (if the
Default action: terminate the task abnormally.
current page is not yet completed), or at the label
specified in a HANDLE CONDITION RETPAGE INVREQ
command if the page has been completed. occurs in any of the following situations:
If TIOAPFX=YES is specified in the map definition, the
Text data is output to the same partition or LDC as
pointer returned contains the address of the TIOA prefix.
mapped data while a BMS logical message is
The user data starts at offset X'0C' from the start of the
active. If neither partitions nor LDCs are in use, text
TIOA prefix.
data is output to the same logical message as
TERMINAL mapped data.
specifies that data is to be sent to the terminal that During overflow processing, data is sent to a
originated the transaction. different LDC from the LDC that caused page
overflow.
TRAILER(data-area)
specifies the text data area that contains trailer data to The length of a header on a SEND TEXT command
be placed at the bottom of each output page. The is negative.
format of the trailer is:
The length of a trailer on a SEND TEXT command
2 bytes Binary length of the data (n) is negative.
| 1 byte Page numbering required or not (blank) Command not allowed for a distributed program link
| 1 byte Reserved field server program (RESP2=200).
n bytes Data
Default action: terminate the task abnormally.
See the CICS/ESA Application Programming Guide for
more information. LENGERR
occurs if an out-of-range value is supplied in the
WAIT LENGTH option.
specifies that control should not be returned to the
Default action: terminate the task abnormally.
application program until the output operation has been
completed. RETPAGE
If WAIT is not specified, control returns to the application occurs if the SET option is specified and a completed
program when the output operation has started. A page is ready for return to the application program.
subsequent input or output command (terminal control, Default action: return control to the application program
BMS, or batch data interchange) causes the application at the point immediately following the BMS SEND TEXT
program to wait until the previous command has been command.
completed.
TSIOERR
occurs if there is an irrecoverable temporary storage
SEND TEXT conditions input/output error.
IGREQCD Default action: terminate the task abnormally.
occurs when an attempt is made to execute a SEND
TEXT command after a SIGNAL data-flow control WRBRK
command with a request change direction (RCD) code occurs if a SEND command is interrupted by the
has been received from an LUTYPE4 logical unit. terminal operator pressing the ATTN key. It applies only
to the 2741 Communication Terminal, and only if write
Default action: terminate the task abnormally. break is supported for CICS.
IGREQID Default action: ignore the condition.
occurs if the prefix specified in the REQID option on a
BMS SEND command is different from that established
by a previous REQID option, or by default for this logical
message—REQID (**).

Chapter 1. Commands 283

SEND TEXT MAPPED

Function
Send data with mapping. Only supplied by full BMS. For further information about BMS, see the CICS/ESA Application
Programming Guide.

Command syntax

┌─TERMINAL──┬──────┬──┬──────┬─┐
│ └─WAIT─┘ └─LAST─┘ │
──SEND TEXT MAPPED──FROM(data-area)──┬────────────────────┬──┼──────────────────────────────┼────────────
└─LENGTH(data-value)─┘ └─PAGING───────────────────────┘
──┬─────────────┬──"
└─REQID(name)─┘
Conditions:
IGREQCD, IGREQID, INVREQ, TSIOERR, WRBRK

SEND TEXT MAPPED sends a page of a device-dependent If PAGING is specified with a REQID that is defined as
data stream previously built by BMS, and returned to the recoverable in the temporary storage table (TST), CICS
application program with the SET option. provides message recovery for logical messages if the
task has reached a syncpoint.
It must only be used to send data previously generated by a
BMS SEND command specifying the SET option. It REQID(name)
references a 4-byte page control area (PGA) that BMS specifies a 2-character prefix to be used as part of a
placed at the end of the device-dependent data stream. temporary storage identifier for CICS message recovery.
Only one prefix can be specified for each logical
The length of the device-dependent data stream set in the message. The default prefix is **.
TIOATDL field of the page buffer returned by the SET option
BMS message recovery is provided for a logical
does not include the PGA. The LENGTH option of the
message only if the PAGING option is specified in the
SEND TEXT MAPPED command should be set from this
BMS SEND commands and if the syncpoint has been
TIOATDL, and hence does not include the PGA. However, if
reached.
the application program copies the page buffer returned by
the SET option, it should include the PGA in the copied data. TERMINAL
specifies that input data is to be sent to the terminal that
This command is only supported by full BMS. originated the transaction.

WAIT
SEND TEXT MAPPED options specifies that control should not be returned to the
FROM(data-area) application program until the output operation has been
specifies the data area containing the data to be sent. completed.
If WAIT is not specified, control returns to the application
LAST
program when the output operation has started. A
specifies that this is the last output operation for a
subsequent input or output command (terminal control,
transaction and, therefore, the end of a bracket. This
BMS, or batch data interchange) causes the application
option applies to logical units only.
program to wait until the previous command has been
LENGTH(data-value) completed.
specifies the length of the data to be formatted as a
halfword binary value. For a description of a safe upper
SEND TEXT MAPPED conditions
limit, see “LENGTH options” on page 5.
IGREQCD
PAGING
occurs when an attempt is made to execute a SEND
specifies that the output data is not to be sent
TEXT command after a SIGNAL data-flow control
immediately to the terminal, but is to be placed in
command with a request change direction (RCD) code
temporary storage and displayed in response to paging
has been received from an LUTYPE4 logical unit.
commands entered by the terminal operator.
Default action: terminate the task abnormally.

284 CICS/ESA Application Programming Reference

SEND TEXT MAPPED

IGREQID
occurs if the prefix specified in the REQID option on a
BMS SEND command is different from that established
by a previous REQID option, or by default for this logical
message—REQID (**).
Default action: terminate the task abnormally.

TSIOERR
occurs if there is an irrecoverable temporary storage
input/output error.
Default action: terminate the task abnormally.

WRBRK
occurs if a SEND command is interrupted by the
terminal operator pressing the ATTN key. It applies only
to the 2741 Communication Terminal, and only if write
break is supported for CICS.
Default action: ignore the condition.

Chapter 1. Commands 285

SEND TEXT NOEDIT

Function
Send a page. Only supplied by full BMS. For further information about BMS, see the CICS/ESA Application Programming
Guide.

Command syntax

──SEND TEXT NOEDIT──FROM(data-area)──┬────────────────────┬──┬──────────────────────┬──┬───────┬─────────

| └─LENGTH(data-value)─┘ └─ERASE──┬───────────┬─┘ └─PRINT─┘
| ├─DEFAULT───┤
| └─ALTERNATE─┘
┌─TERMINAL──┬──────┬──┬──────┬─┐
│ └─WAIT─┘ └─LAST─┘ │
──┬────────┬──┬───────┬──┬────────────────┬──┼──────────────────────────────┼──┬─────────────┬────────────
└─FREEKB─┘ └─ALARM─┘ └─OUTPARTN(name)─┘ └─PAGING───────────────────────┘ └─REQID(name)─┘
┌─HONEOM─┐
──┼────────┼──"
├─L4O────┤
├─L64────┤
└─L8O────┘
Conditions:
IGREQCD, IGREQID, INVREQ, INVPARTN, TSIOERR, WRBRK

SEND TEXT NOEDIT sends a page of a device-dependent | DEFAULT

data stream built by the application program. The data | sets the terminal to use the DEFAULT screen size.
stream cannot contain structured fields. This command
ERASE
differs from a terminal control SEND, because the data
specifies that the screen printer buffer or partition is to
stream may be written to temporary storage and interfaced to
be erased and the cursor returned to the upper left
the terminal operator paging transaction (using the PAGING
corner of the screen. (This option applies only to the
option). Also the device-dependent data stream can be sent
3270, or 8775, and to the 3604 Keyboard Display.)
to a partition (using the OUTPARTN option).
The first output operation in any transaction, or in a
If the OUTPARTN option is specified, the data stream is sent series of pseudoconversational transactions, should
to the specified partition. This command is used to output a always specify ERASE. For transactions attached to
user-generated data stream. It differs from a terminal control | 3270 screens or printers, unless explicitly overridden by
SEND in that data may be output to temporary storage | the DEFAULT or ALTERNATE option, this also ensures
(using the PAGING option), or routed like any other BMS that the correct screen size is selected, as defined for
data. | the transaction by the SCRNSIZE option in the profile
| definition.
When using the SEND TEXT NOEDIT command with any of
the ALARM, FREEKB, FRSET, HONEOM, L40, L64, L80, or FREEKB
PRINT options, see CTRL on page 391 for a description of specifies that the 3270 keyboard should be unlocked
the option priority. after the data is written. If FREEKB is omitted, the
keyboard remains locked.
This command is supported on full BMS only.
Note that the keyboard lock status is maintained
separately for each partition on a terminal that supports
SEND TEXT NOEDIT options partitions.
ALARM When using the FREEKB option, refer to CTRL on page
specifies that the 3270 audible alarm feature is to be 391 for a description of the option priority.
activated. For logical units supporting FMHs (except
FROM(data-area)
interactive and batch logical units), ALARM instructs
specifies the data area containing the data to be sent.
BMS to set the alarm flag in the FMH.
HONEOM
| ALTERNATE
specifies that the default printer line length is to be used.
| sets the terminal to use the ALTERNATE screen size.
This length should be the same as that specified using

286 CICS/ESA Application Programming Reference

SEND TEXT NOEDIT

the RDO options PAGESIZE or ALTPAGE, or PGESIZE REQID(name)

or ALTPGE in the terminal control table specifies a 2-character prefix to be used as part of a
TYPE=TERMINAL, and the same as the printer platen temporary storage identifier for CICS message recovery.
width; otherwise the data may not format correctly. Only one prefix can be specified for each logical
message. The default prefix is **.
When using the HONEOM option, refer to CTRL on
page 391 for a description of the option priority. TERMINAL
specifies that the data is to be sent to the terminal that
LAST
originated the transaction.
specifies that this is the last output operation for a
transaction and, therefore, the end of a bracket. This WAIT
option applies to logical units only. specifies that control should not be returned to the
application program until the output operation has been
LENGTH(data-value)
completed.
specifies the length of the data to be sent as a halfword
binary value. For a description of a safe upper limit, see If WAIT is not specified, control returns to the application
“LENGTH options” on page 5. program when the output operation has started. A
subsequent input or output command (terminal control,
| L40, L64, or L80
BMS, or batch data interchange) causes the application
specifies the line length for a 3270 printer; a carrier
program to wait until the previous command has been
return and line feed are forced after 40, 64, or 80
completed.
characters have been printed on a line. Unacceptable
results are likely if this differs from the page width
specified by the RDO options PAGESIZE or ALTPAGE, SEND TEXT NOEDIT conditions
or the PGESIZE or ALTPGE in the terminal control table
IGREQCD
TYPE=TERMINAL.
occurs when an attempt is made to execute a SEND
| When using the options, refer to CTRL on page 391 for TEXT command after a SIGNAL data-flow control
| a description of the option priority. command with a request change direction (RCD) code
has been received from an LUTYPE4 logical unit.
OUTPARTN(name)
specifies the name (1–2 characters) of the partition to Default action: terminate the task abnormally.
which data is to be sent. This option is ignored if the
IGREQID
terminal does not support partitions, or if there is no
occurs if the prefix specified in the REQID option on a
application partition set associated with the terminal. If
BMS SEND command is different from that established
there is an application partition set, and the OUTPARTN
by a previous REQID option, or by default for this logical
option is omitted, data is sent to the partition named by
message—REQID (**).
the PARTN operand of the DFHMSD or DFHMDI map
definition. If maps are not used, or if there is no PARTN Default action: terminate the task abnormally.
operand, the output is sent to the first partition in the
INVPARTN
partition set.
occurs if the specified partition is not defined in the
PAGING partition set associated with the application program.
specifies that the output data is not to be sent Default action: terminate the task abnormally.
immediately to the terminal, but is to be placed in
temporary storage and displayed in response to paging INVREQ
commands entered by the terminal operator. occurs in any of the following situations:
If PAGING is specified with a REQID that is defined as Text data is output to the same partition or LDC as
recoverable in the temporary storage table (TST), CICS mapped data while a BMS logical message is
provides message recovery for logical messages if the active. If neither partitions nor LDCs are in use, text
task has reached a syncpoint. data is output to the same logical message as
mapped data.
PRINT
specifies that a print operation is to be started at a 3270 During overflow processing, data is sent to a
printer or at a 3275 with the printer adapter feature, or different LDC from the LDC that caused page
that data on an LUTYPE2 (3274/76 or 3790) is to be overflow.
printed on a printer allocated by the controller. If this The length of a header on a SEND TEXT command
option is omitted, the data is sent to the printer buffer but is negative.
is not printed.
The length of a trailer on a SEND TEXT command
When using the PRINT option, refer to CTRL on page is negative.
391 for a description of the option priority.
Command not allowed for a distributed program link
server program (RESP2=200).

Chapter 1. Commands 287

SEND TEXT NOEDIT

Default action: terminate the task abnormally.

TSIOERR
occurs if there is an irrecoverable temporary storage
input/output error.
Default action: terminate the task abnormally.

288 CICS/ESA Application Programming Reference

SIGNOFF

Function
Sign off from a terminal.

Command syntax

──SIGNOFF──"
Conditions:
INVREQ

SIGNOFF enables you to sign off from the terminal or

principal facility that you previously signed on to. When
signoff is complete, the terminal reverts to the security
capabilities and operator characteristics associated with the
default user for this CICS region. The national language
reverts to the national language of the default user, if
defined, or the national language associated with the
definition of the terminal.

Other resource managers

When this command is executed, CICS immediately
recognizes the signoff and establishes the default
attributes for the terminal. The transaction (and any
associated task-related user exits, function shipping, or
distributed transaction processing) may have invoked
other resource managers (RMs), for example, IMS, DB2,
or VSAM. It is unpredictable whether these other
RMs recognize the signoff before the transaction
terminates.

The default attributes apply for all RMs invoked by

subsequent transactions at the terminal.

SIGNOFF condition
INVREQ
occurs in any of the following situations:

No user is currently signed on (RESP2=1)

There is no terminal with this task (RESP2=2)
This task’s terminal has preset security (RESP2=3)
Signoff is attempted using transaction routing
without using the CRTE transaction (RESP2=4).
| The CICS ESM interface is not initialized
| (RESP2=18).
Command not allowed for a distributed program link
server program (RESP2=200).
| Default action: terminate the task abnormally.

Chapter 1. Commands 289

SIGNON

Function
Sign on to a terminal.

Command syntax

──SIGNON──USERID(data-value)──┬──────────────────────┬──┬────────────────────┬───────────────────────────
| └─ESMREASON(data-area)─┘ └─ESMRESP(data-area)─┘
──┬─────────────────────┬──┬──────────────────────────┬──┬──────────────────────┬─────────────────────────
| └─GROUPID(data-value)─┘ ├─LANGUAGECODE(data-value)─┤ └─LANGINUSE(data-area)─┘
└─NATLANG(data-value)──────┘
──┬─────────────────────────┬──┬──────────────────────┬──┬─────────────────────────┬──────────────────────
└─NATLANGINUSE(data-area)─┘ └─PASSWORD(data-value)─┘ └─NEWPASSWORD(data-value)─┘
──┬─────────────────────┬──"
└─OIDCARD(data-value)─┘
Conditions:
INVREQ, NOTAUTH, USERIDERR

SIGNON associates the security capabilities and operator SIGNON options

characteristics of the specified user with the terminal. It
allows all types of terminal, with the exception of APPC, to | If an optional input field contains all blanks, it is ignored.
be signed on to. SIGNON signs on to the terminal or
| ESMREASON(data-area)
principal facility associated with the issuing transaction.
| returns the reason code, in a fullword binary field, that
There is no implied signoff with the SIGNON command. If | CICS receives from the external security manager.
you want to sign on a user at a terminal to which a user is | If the ESM is RACF, this field is the RACF reason code.
already signed on, you must first issue a SIGNOFF
command. Note that there is no default value for the | ESMRESP(data-area)
USERID option. | returns the response code, in a fullword binary field, that
| CICS receives from the external security manager.
| PASSWORD is used as a parameter which means that if | If the ESM is RACF, this field is the RACF return code.
| there is a dump it will become visible. You should therefore
| clear the field as soon as possible after using PASSWORD. | GROUPID(data-value)
| assigns the user that is being signed on to a RACF user
Other resource managers | group. This overrides, for this session only, the default
When this command is executed, CICS immediately | group name specified for the user in the RACF
recognizes the signon and establishes the specified | database.
user’s security and operating attributes for the terminal. # Apar 15449
The transaction (and any associated task-related user
# Following paragraph added by Apar 15449 04/06/98
exits, function shipping, or distributed transaction
processing) may have invoked other resource managers
(RMs), for example, IMS, DB2, or VSAM. It is # If specified, this value, and the USERID, may be
unpredictable whether these other RMs recognize the # propagated to remote systems. See the CICS/ESA
signon before the transaction terminates. # CICS-RACF Security Guide for information on
# implementing LU6.2 security for remote users.
The new user attributes apply for all RMs invoked by
subsequent transactions at the terminal. | LANGUAGECODE(data-value)
| specifies the national language that the user being
| signed on wants CICS to use. You specify the language
| as a standard three-character IBM code. This is an
| alternative to the one-character code that you specify on
| the NATLANG option.
| See Appendix I, “National language codes” on page 373
| for possible values of the code.

290 CICS/ESA Application Programming Reference

SIGNON

| LANGINUSE(data-area) No terminal is associated with this task (RESP2=10)

| the LANGINUSE option allows an application program to
This task’s terminal has preset security (RESP2=11)
| receive the national language chosen by the signon
| process. The language is identified as a standard The response from CICS security modules is
| three-character IBM code, instead of the one-character unrecognized (RESP2=12)
| code used by NATLANGINUSE. It is an alternative to There is an unknown return code in ESMRESP from
| the existing NATLANGINUSE option. | the external security manager; or the external
| See Appendix I, “National language codes” on page 373 | security manager (ESM) is not active, or has failed
| for possible values of the code. in an unexpected way (RESP2=13)
The required national language is not available
NATLANG(data-value)
(RESP2=14)
specifies as 1 character field identifying the national
language the user wants to use during the signed-on Signon was attempted using transaction routing
session. without using the CRTE transaction (RESP2=15)
| See Appendix I, “National language codes” on page 373 The CICS ESM interface is not initialized
| for possible values of the code. (RESP2=18)

NATLANGINUSE(data-area) | The terminal is of an invalid type (RESP2=25)

specifies as 1 character the national language used # An error occurred during SNSCOPE checking. The
during the signed-on session. NATLANGINUSE # limit of MVS ENQ requests was
corresponds to the following (in order of decreasing # reached(RESP2=26)
priority):
The external security manager (ESM) is not active
The language supplied in the NATLANG option of (RESP2=27)
the SIGNON command.
The required national language is invalid
The language associated with the user. This is (RESP2=28)
specified in the ESM language segment.
| Command not allowed for a distributed program link
The language associated with the definition of the | server program (RESP2=200)
terminal.
| The user is already signed on. This relates to the
The language associated with the default USERID | signon scope checking (RESP2=29).
for the CICS region.
| Default action: terminate the task abnormally.
The default language specified in the system
NOTAUTH
initialization parameters.
occurs in any of the following situations:
| See Appendix I, “National language codes” on page 373
A password is required (RESP2=1)
| for possible values of the code.
The supplied password is wrong (RESP2=2)
NEWPASSWORD(data-value)
specifies an optional 8-byte field defining a new A new password is required (RESP2=3)
password. This option is only valid if PASSWORD is The new password is not acceptable (RESP2=4)
also specified.
An OIDCARD is required (RESP2=5)
OIDCARD(data-value)
The supplied OIDCARD is wrong (RESP2=6)
specifies an optional 65-byte field containing further
security data from a magnetic strip reader (MSR) on The USERID is not authorized to use this terminal
32xx devices. (RESP2=16)
The USERID is not authorized to use the application
PASSWORD(data-value)
(RESP2=17)
specifies an 8-byte password required by the external
security manager (ESM). The USERID is revoked (RESP2=19)

USERID(data-value) | The USERID’s access to the specified group has

specifies the 8-byte signon USERID. | been revoked (RESP2=20)
| The signon failed during SECLABEL checking
SIGNON conditions | (RESP2=21)
| The signon failed because the ESM is not currently
INVREQ
| accepting signon (RESP2=22)
occurs in any of the following situations:
| The GROUPID is not known to the ESM
The terminal is already signed on (RESP2=9) | (RESP2=23)

Chapter 1. Commands 291

SIGNON

| The USERID is not contained in the GROUPID

| (RESP2=24).
| Default action: terminate the task abnormally.

USERIDERR
occurs in any of the following situations:

The USERID is not known to the external security

manager (RESP2=8).
| The USERID is all blanks or nulls (RESP2=30)
| Default action: terminate the task abnormally.

292 CICS/ESA Application Programming Reference

SPOOLCLOSE

Function
Close a spool report.

Command syntax

| ┌──
───────────────────┐
| ──SPOOLCLOSE──TOKEN(data-area)──┬────────┬───*┬─NOHANDLE────────┬┴──"
| ├─KEEP───┤ └─RESP──┬───────┬─┘
| └─DELETE─┘ └─RESP2─┘
Conditions:
ALLOCERR, INVREQ, NOSPOOL, NOSTG, NOTFND, NOTOPEN, STRELERR

The SPOOLCLOSE command closes a CICS spool report Condition RESP2 Meaning
and, optionally, changes its retention characteristics. If more ALLOCERR - MVS dynamic allocation has rejected a
than one transaction is trying to read reports from JES, request to allocate an input data set.
SPOOLCLOSE should not be immediately followed by RESP2 gives the dynamic allocation response
SPOOLOPEN. It should be followed by a WAIT, so that code that denotes this error. The first two
other transactions can use the interface. characters are the information reason code
(S99INFO), and the second two are the error
A default disposition is taken if both KEEP and DELETE are reason code (S99ERROR), as defined in the
| MVS/ESA Application Development Guide:
omitted from the SPOOLCLOSE command, or if the report is
| Authorized Assembler Language Programs,
closed implicitly by a SYNCPOINT or RETURN command: | GC28-1645.
When an INPUT report is explicitly closed by a INVREQ 4 Unsupported language.
SPOOLCLOSE command, the default disposition is
INVREQ 8 Unsupported function.
DELETE.
| INVREQ 40 Subsystem interface already enabled.
In all other cases, the default disposition is KEEP.
Note: Errors 1024 and over are internal, and
should not occur. If one of these error codes
SPOOLCLOSE options is returned, contact your IBM support center.
NOSPOOL 4 No subsystem present.
DELETE
NOSPOOL 8 Interface being disabled; CICS is quiescing.
For an INPUT report, DELETE specifies that the next
report is to be read on the subsequent OPEN INPUT. NOSPOOL 12 Interface has been stopped.

For an OUTPUT report, DELETE specifies that the NOSTG - An MVS GETMAIN has failed within the JES
interface subtask (DFHPSPSS).
report is to be purged.
RESP2 gives the GETMAIN register 15 return
Note: When a JCL job is submitted using the internal code.
reader (INTRDR) with the DELETE option specified, the
NOTFND 1024 Input or output function has been corrupted,
job is sometimes run before the output is deleted.
and SPOOLCLOSE could not complete.
KEEP | NOTOPEN 8 Data set has not been opened.
For an INPUT report, KEEP specifies that the report is to STRELERR - An MVS FREEMAIN has failed within the JES
be read again when SPOOLOPEN INPUT is next interface subtask (DFHPSPSS).
issued.
RESP2 gives the FREEMAIN register 15
For an OUTPUT report, KEEP specifies that the report is return code.
to be sent to its destination node.

TOKEN(data-area)
specifies the 8-character CICS-allocated token used to
identify a report.

SPOOLCLOSE conditions
| Note: There are no default actions.

Chapter 1. Commands 293

SPOOLOPEN INPUT

Function
Open a spool report.

Command syntax

| ┌──
───────────────────┐
| ──SPOOLOPEN INPUT──TOKEN(data-area)──USERID(data-value)──┬───────────────────┬───*┬─NOHANDLE────────┬┴──"
| └─CLASS(data-value)─┘ └─RESP──┬───────┬─┘
| └─RESP2─┘
Conditions:
ALLOCERR, ILLOGIC, INVREQ, NOSPOOL, NOSTG, NOTAUTH, NOTFND, NOTOPEN, OPENERR, SPOLBUSY,
SPOLERR, STRELERR

The SPOOLOPEN INPUT command opens a spool report for SPOOLOPEN INPUT conditions
input from the system spooler to CICS.
| Note: There are no default actions.
It prepares to get (read) an existing spool data set directly
Condition RESP2 Meaning
using external writer name (USERID) and specified class. ALLOCERR - MVS dynamic allocation has rejected a
request to allocate an input data set.
Another task could have allocated a spool file for input. In
this case, you should retry after a suitable time interval. RESP2 gives the dynamic allocation response
code that denotes this error. The first two
When this command has been successfully executed, you characters are the information reason code
(S99INFO), and the second two are the error
should read the report and proceed to CLOSE as soon as
reason code (S99ERROR), as defined in the
possible, in order to permit other users to use the JES single | MVS/ESA Application Development Guide:
thread. If SPOOLCLOSE is not issued before transaction | Authorized Assembler Language Programs,
end or SYNCPOINT, CICS performs an implicit | GC28-1645.
SPOOLCLOSE KEEP, and writes a message to CSMT to ILLOGIC 3 Invalid CLASS value specified.
alert the system programmer to the possible unnecessary
INVREQ 4 Unsupported language.
retention of resources. You should not SPOOLOPEN a data
set using this command until you are prepared to process it INVREQ 8 Unsupported function.
completely. INVREQ 16 USERID missing.
INVREQ 36 INPUT|OUTPUT missing.
This command, if successful, returns a token, which is used
later to identify the report in SPOOLREAD and | INVREQ 40 Subsystem interface already enabled.
SPOOLCLOSE commands. Note: Errors 1024 and over are internal, and
should not occur. If one of these error codes
is returned, contact your IBM Support Center.
SPOOLOPEN INPUT options NOSPOOL 4 No subsystem present.
CLASS(data-value) NOSPOOL 8 Interface being disabled; CICS is quiescing.
specifies a 1-character class designation. The CLASS NOSPOOL 12 Interface has been stopped.
operand can be used as a selection parameter for input
NOSTG - An MVS GETMAIN has failed within the JES
reports. If it is omitted, the first report for the specified
interface subtask (DFHPSPSS).
USERID is obtained, regardless of its class.
RESP2 gives the GETMAIN register 15 return
TOKEN(data-area) code.
specifies the 8-character CICS-allocated token used to NOTAUTH - An application has issued a SPOOLOPEN
identify a report. INPUT command with an unauthorized
USERID. For the USERID to be authorized, its
USERID(data-value) first four characters must match the first four
specifies the 8-character user identifier. It must begin characters of the current CICS applid id.
with the same 4 characters as the CICS generic applid,
so that CICS can check that users are not attempting to
access data sets not intended for their CICS system.

294 CICS/ESA Application Programming Reference

SPOOLOPEN INPUT

Condition RESP2 Meaning

NOTFND 4 No data sets could be located for retrieval for
the specified external writer name.
# Can also be returned if the CICS region
# USERID does not have ALTER access to the
# appropriate PROFILE in the JESSPOOL
# class. See the CICS/ESA CICS-RACF
# Security Guide for more information about
# RACF authorization of JES.
NOTFND 1024 Input or output function has been corrupted,
and SPOOLCLOSE could not complete.
NOTOPEN 8 Data set has not been opened or a task which
has not issued the SPOOLOPEN for a spool
data set has attempted to access it.
NOTOPEN 1024 Subtask OPEN macro failure.
OPENERR - An internal error occurred during
SPOOLOPEN processing that has forced the
request to fail.
OPENERR 4 A VSAM SHOWCB macro failed to return the
lengths of the VSAM control blocks used to
access the JES spool file.
SPOLBUSY - The JES/input single thread within the JES
interface was not available.
SPOLBUSY 4 Interface already in use by another task.
SPOLBUSY 8 Interface already in use by current task.
SPOLERR - The MVS subsystem interface macro
(IEFSSREQ) has failed. No input data set
name was selected.
RESP2 gives the ‘IEFSSREQ’ response code.
STRELERR - An MVS FREEMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the FREEMAIN register 15
return code.

Chapter 1. Commands 295

SPOOLOPEN OUTPUT

Function
Open a spool report for output.

Command syntax

──SPOOLOPEN OUTPUT──TOKEN(data-area)──USERID(data-value)──NODE(data-value)──┬───────────────────┬────────
└─CLASS(data-value)─┘
| ┌─NOCC─┐ ┌─PRINT───────────────────────────────┐ ┌── ───────────────────┐
| ──┬───────────────────┬──┼──────┼──┼─────────────────────────────────────┼───*┬─NOHANDLE────────┬┴──"
| └─OUTDESCR(ptr-ref)─┘ ├─ASA──┤ ├─PRINT──┬──────────────────────────┬─┤ └─RESP──┬───────┬─┘
| └─MCC──┘ │ └─RECORDLENGTH(data-value)─┘ │ └─RESP2─┘
└─PUNCH───────────────────────────────┘
Conditions:
ALLOCERR, ILLOGIC, INVREQ, LENGERR, NODEIDERR, NOSPOOL, NOSTG, NOTFND, NOTOPEN, OPENERR,
OUTDESCERR, SPOLBUSY, STRELERR

The SPOOLOPEN OUTPUT command opens a spool report SPOOLOPEN OUTPUT options
for output from CICS to the system spooler and defines its
characteristics. ASA
specifies that the report has each record prefixed with an
It results in a dynamic allocation of the output file using the ASA carriage-control character, and this character must
nodeid to specify the remote destination and the userid to be used by the operating system to control formatting
specify the remote user. As this is a multithread output when the report is printed.
request, requesters of this service could interleave. This
CLASS(data-value)
SPOOLOPEN enables users to acquire the token for a report
specifies a 1-character class designation. If it is omitted,
that it expects to create (write). This token is used to identify
class A is assumed.
the report in later SPOOLWRITE and SPOOLCLOSE
commands. MCC
specifies that the report has each record prefixed with an
When printing on a local device, use the NOCC|ASA|MCC IBM machine command code carriage-control character,
options to control output formatting. If you do not specify a and this character must be used by the operating system
format, the default value of NOCC is used. to control formatting when the report is printed.
Apar PN13451 NOCC
Documentation for Apar PN13451 added 13/02/95 specifies that the report has no internal formatting
controls. When the report is printed, the operating
system prefixes each record with a carriage-control
# NODE and USERID can be used to write the data set character that causes page skipping according to the
# directly to the local spool file only if specified with a value of default operating system lines-per-page value.
# '*'.
NODE(data-value)
If you do not issue SPOOLCLOSE before the end of the specifies the 8-character identifier of a destination node
transaction, CICS performs an implicit SPOOLCLOSE that the system spooler uses to route the file. It is a
DELETE and writes a message to CSMT to alert you to the sender field.
possible unnecessary retention of resources.
OUTDESCR(ptr-ref)
Note: If you retrieve a formatted data set, the system | (MVS/SP—JES2 Version 3, or JES3 Version 4.2.1 only,
spooler could have changed the data set format. For | or a later upward-compatible release) specifies a pointer
example, the system spooler could have converted an MCC | variable to be set to the address of a field that contains
format data set to ASA format during data set creation. This | the address of a string of parameters to the OUTPUT
does not affect the final printed output. | statement of MVS JCL. This is called double indirect
| addressing. The user must set up the pointer, the
address field, and the string. This means that the
OUTDESCR option cannot be used from within CECI.
The format of the string is:

296 CICS/ESA Application Programming Reference

SPOOLOPEN OUTPUT

Offset Length Contents Sending the internal reader buffer directly to

O 4 Length (n) of following text string JES:Instead of waiting for the buffer in your address
4 n OUTPUT statement parameters space to fill up, send the contents of the internal reader
The parameters use the same keywords and values as buffer directly to JES by coding as your last record:
the OUTPUT statement but the syntax varies slightly. /_EOF
The following is the format of the OUTDESCR parameter
This control statement delimits the job in the data set,
string:
and makes it eligible for immediate processing.
keyword1(value1) [keyword2(value2)]
[keyword3(value3,value4)] ... For more information about using the internal reader,
and about other /* control statements, see the
This corresponds to the following OUTPUT statement &esajcluc..
parameter string:
keyword1=value1 [keyword2=value2]
[keyword3=(value3,value4)] ...
SPOOLOPEN OUTPUT conditions
| Note: There are no default actions.
:
| For details of valid keywords and values, see the TSO/E Condition RESP2 Meaning
| Command Reference manual (SC28-1991-0). ALLOCERR - MVS dynamic allocation has rejected a
request to allocate an input data set.
The OUTDESCR operand:
RESP2 gives the dynamic allocation response
Can override the NODE and USERID operands only code that denotes this error. The first two
if they are specified with a value of '*'. characters are the information reason code
(S99INFO), and the second two are the error
Cannot override the CLASS operand, even if it is reason code (S99ERROR), as defined in the
omitted and defaults to class A. | MVS/ESA Application Development Guide:
| Authorized Assembler Language Programs,
Use this operand to set additional attributes for the spool | GC28-1645.
data set. ILLOGIC 3 Invalid CLASS value specified.
PRINT INVREQ 4 Unsupported language.
# allows large records (maximum 32760 bytes) to be INVREQ 8 Unsupported function.
# written to the spool. This is the default setting. This is
INVREQ 16 USERID missing.
included for compatibility with the spool support provided
with CICS/DOS/VS and CICS/VSE. INVREQ 20 NODE missing.
INVREQ 36 INPUT|OUTPUT missing.
PUNCH
must be specified if the CLASS parameter for the output | INVREQ 40 Subsystem interface already enabled.
data set implies punch, and the data set is destined for a Note: Errors 1024 and over are internal, and
VM/RSCS node. This ensures that the record length should not occur. If one of these error codes
is returned, contact your IBM support center.
indicator is set to 80, which is a requirement of
VM/RSCS for punch files. INVREQ 44 Error in the OUTDESCR string.
INVREQ 48 OUTDESCR specified but function not
| RECORDLENGTH(data-value)
available (wrong level of MVS or JES).
| specifies, as a halfword binary variable, the maximum
| length of record to write to a print data set. The default INVREQ 52 OUTDESCR specified but bad pointer found
on keyword or in OUTDESCR condition.
| value is 32 760.
| LENGERR RECORDLENGTH not in the range 0 through
TOKEN(data-area) | 32760. RESP2 shows the incorrect value.
specifies the 8-character CICS-allocated token used to | NODEIDERR JES cannot identify the NODE/USERID
identify a report. | combination specified on SPOOLOPEN
| OUTPUT.
USERID(data-value)
| specifies the 8-character identifier of the destination | RESP2 gives the dynamic allocation response
| userid that processes the report. The report carries this | code that denotes this error. The first two
| characters are the information reason code
identifier, which is used to select the report at its
| (S99INFO), and the second two are the error
destination. It is a sender field and must be declared | reason code (S99ERROR), as defined in the
with a length of 8 characters. | MVS/ESA Application Development Guide:
# Apar PQ07753 | Authorized Assembler Language Programs,
| GC28-1645.
# Documentation for Apar PQ07753 added 06/10/97 NOSPOOL 4 No subsystem present.
NOSPOOL 8 Interface being disabled; CICS is quiescing.
# Validity checking is performed for USERID. Checks are
# made for blanks (X'40'), and nulls (X'00').

Chapter 1. Commands 297

SPOOLOPEN OUTPUT

Condition RESP2 Meaning

NOSPOOL 12 Interface has been stopped.
NOSTG An MVS GETMAIN has failed within the JES
interface subtask(DFHPSPSS).
RESP2 gives the GETMAIN register 15 return
code.
NOTFND 4 No data sets could be located for retrieval for
the specified external writer name.
NOTOPEN 8 Data set has not been opened.
NOTOPEN 1024 Subtask OPEN macro failure.
OPENERR - An internal error occurred during
SPOOLOPEN processing that has forced the
request to fail.
OPENERR 4 A VSAM SHOWCB macro failed to return the
lengths of the VSAM control blocks used to
access the JES spool file.
OUTDESCRERR The MVS macro OUTADD or OUTDEL
(invoked as a result of the OUTDESCR
specification) failed.
RESP2 gives the reason code from the
OUTADD or OUTDEL macro. See the
| MVS/ESA Application Development Guide:
| Authorized Assembler Language Programs,
| GC28-1645. for descriptions of codes.
SPOLBUSY - The JES/input single thread within the JES
interface was not available.
SPOLBUSY 4 Interface already in use by another task.
SPOLBUSY 8 Interface already in use by current task.
STRELERR - An MVS FREEMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the FREEMAIN register 15
return code.

298 CICS/ESA Application Programming Reference

SPOOLREAD

Function
The SPOOLREAD command obtains the next record from the system spooler.

Command syntax

──SPOOLREAD──TOKEN(data-area)──INTO(data-area)──┬────────────────────────┬──┬──────────────────────┬─────
| └─MAXFLENGTH(data-value)─┘ └─TOFLENGTH(data-area)─┘
| ┌──
───────────────────┐
| ───*┬─NOHANDLE────────┬┴──"
| └─RESP──┬───────┬─┘
| └─RESP2─┘
Conditions:
ALLOCERR, ENDFILE, ILLOGIC, INVREQ, LENGERR, NOSPOOL, NOSTG, NOTFND, NOTOPEN, SPOLBUSY,
SPOLERR, STRELERR

SPOOLREAD options
INTO(data-area)
specifies the data area for the variable-length data. It is
a receiver field.

MAXFLENGTH(data-value)
specifies, as a fullword binary variable, the maximum
length of data transferred. This is set by the user on
input. The limit of length is 32 760 bytes. This is the
maximum size of the CICS buffer used to read a record.

TOFLENGTH(data-area)
specifies, as a fullword binary variable, the length of the
data that is transferred. This is set by CICS on input. It
is optional and, if it is omitted, you are not notified of the
SPOOLREAD

Condition RESP2 Meaning

NOSTG - An MVS GETMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the GETMAIN register 15 return
code.
NOTFND 4 No data sets could be located for retrieval for
the specified external writer name.
NOTOPEN 8 Data set has not been opened.
NOTOPEN 12 Attempt to read an output file.
NOTOPEN 1024 Subtask OPEN macro failure.
SPOLBUSY - The JES/input single thread within the JES
interface was not available.
SPOLBUSY 4 Interface already in use by another task.
SPOLBUSY 8 Interface already in use by current task.
SPOLERR - The MVS subsystem interface macro
(IEFSSREQ) has failed. No input data set
name was selected.
RESP2 gives the ‘IEFSSREQ’ response code.
STRELERR - An MVS FREEMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the FREEMAIN register 15
return code.

300 CICS/ESA Application Programming Reference

SPOOLWRITE

Function
The SPOOLWRITE command writes data to a spool report.

Command syntax

┌─LINE─┐
──SPOOLWRITE──TOKEN(data-area)──FROM(data-area)──┬─────────────────────┬──┼──────┼───────────────────────
└─FLENGTH(data-value)─┘ └─PAGE─┘
| ┌──
───────────────────┐
| ───*┬─NOHANDLE────────┬┴──"
| └─RESP──┬───────┬─┘
| └─RESP2─┘
Conditions:
ALLOCERR, INVREQ, LENGERR, NOSPOOL, NOSTG, NOTOPEN, SPOLBUSY, SPOLERR, STRELERR

SPOOLWRITE options Condition RESP2 Meaning

ALLOCERR - MVS dynamic allocation has rejected a
FLENGTH(data-value) request to allocate an input data set.
specifies the fullword binary variable that is to be set to RESP2 gives the dynamic allocation response
the length of the data that is transferred. This is set by code that denotes this error. The first two
the user on output. It is optional and, if it is omitted, characters are the information reason code
CICS uses the length of the data area. (S99INFO), and the second two are the error
reason code (S99ERROR), as defined in the
| For OS/VS COBOL users, FLENGTH is mandatory. | MVS/ESA Application Development Guide:
| Authorized Assembler Language Programs,
FROM(data-area) | GC28-1645.
specifies the data area from which to take the variable
INVREQ 4 Unsupported language.
length data. The data itself is not altered in any way by
CICS. FROM is a sender field. INVREQ 8 Unsupported function.
INVREQ 28 FROM missing.
LINE|PAGE
specifies the format of the data to be sent. The default | INVREQ 40 Subsystem interface already enabled.
action is LINE. Note: Errors 1024 and over are internal, and
should not occur. If one of these error codes
| The PAGE option must be used to correctly format is returned, contact your IBM support center.
| information for the advanced function printer (AFP) page
LENGERR - The value specified in the FLENGTH
| printing devices. If a customer is creating MIXED mode
parameter on a SPOOLWRITE command is
# type data, that is LINE records and X'5A' (AFPDS or not in the valid range 1 to RECORDLENGTH
# MODCA) pagemode records, the LINE or PAGE value specified or defaulted at the
# operand must match the type record being written to SPOOLOPEN data set. If the buffer space is
# spool. too small, it receives as much data as
possible.
TOKEN(data-area)
RESP2 contains the difference between
specifies the 8-character CICS-allocated token used to
# FLENGTH and RECORDLENGTH, or zero if
identify a report. It is a receiver on SPOOLOPEN and a # FLENGTH is negative or greater than 32760.
sender on all other commands.
NOSPOOL 4 No subsystem present.
NOSPOOL 8 Interface being disabled; CICS is quiescing.
SPOOLWRITE conditions NOSPOOL 12 Interface has been stopped.
| Note: There are no default actions. NOSTG - An MVS GETMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the GETMAIN register 15 return
code.
NOTOPEN 8 Spool report has not been opened.
NOTOPEN 16 Attempt to write an input file.

Chapter 1. Commands 301

SPOOLWRITE

Condition RESP2 Meaning

NOTOPEN 1024 Subtask OPEN macro failure.
SPOLBUSY - The JES/input single thread within the JES
interface was not available.
SPOLBUSY 4 Interface already in use by another task.
SPOLBUSY 8 Interface already in use by current task.
SPOLERR - The MVS subsystem interface macro
(IEFSSREQ) has failed. No input data set
name was selected.
RESP2 gives the ‘IEFSSREQ’ response code.
STRELERR - An MVS FREEMAIN has failed within the JES
interface subtask (DFHPSPSS).
RESP2 gives the FREEMAIN register 15
return code.

302 CICS/ESA Application Programming Reference

START

| Function
| Start task at a specified time.

Command syntax

┌─INTERVAL()──────────────────────┐
──START──TRANSID(name)──┼──────────────────────────────────┼──┬─────────────┬────────────────────────────
├─INTERVAL(hhmmss)─────────────────┤ └─REQID(name)─┘
├─TIME(hhmmss)─────────────────────┤
│ ┌──
───────────────────────┐ │
| ├─AFTER───*┬─HOURS(data-value)───┬┴─┤
| │ ├─MINUTES(data-value)─┤ │
| │ └─SECONDS(data-value)─┘ │
│ ┌──
───────────────────────┐ │
| └─AT───*┬─HOURS(data-value)───┬┴────┘
| ├─MINUTES(data-value)─┤
| └─SECONDS(data-value)─┘
──┬──────────────────────────────────────────────┬──┬────────────────────┬──┬───────────────────┬─────────
| └─FROM(data-area)──LENGTH(data-value)──┬─────┬─┘ ├─TERMID(name)───────┤ └─SYSID(systemname)─┘
└─FMH─┘ └─USERID(data-value)─┘
──┬────────────────┬──┬───────────────┬──┬─────────────┬──┬─────────┬──┬─────────┬──┬────────┬──"
# └─RTRANSID(name)─┘ └─RTERMID(name)─┘ └─QUEUE(name)─┘ └─NOCHECK─┘ └─PROTECT─┘ └─ATTACH─┘
Conditions:
| INVREQ, IOERR, ISCINVREQ, LENGERR, NOTAUTH, SYSIDERR, TERMIDERR, TRANSIDERR, USERIDERR

Apar PN92143
Documentation for Apar PN92143 added 28/02/97

| Note for dynamic transaction routing

| Using START if later CANCELed by another task, or if the started transaction uses RETRIEVE WAIT, could create
| inter-transaction affinities that adversely affect the use of dynamic transaction routing. See the CICS/ESA Application
| Programming Guide for more information about transaction affinities.

START starts a task, on a local or remote system, at a following situation. One task can start a second task,
# specified time. The time is specified by INTERVAL, AFTER, passing it a transaction name and a terminal name to be
# AT or TIME. See the section about expiration times in the used when the second task starts a third task. The first task
# CICS/ESA Application Programming Guide. may also pass the name of a queue to be accessed by the
second task.
| The default is INTERVAL(0), but for C the default is AFTER
| HOURS(0) MINUTES(0) SECONDS(0). One or more constraints have to be satisfied before the
transaction to be executed can be started, as follows:
The starting task may pass data to the started task and may
The specified interval must have elapsed or the specified
also specify a terminal to be used by the started task as its
expiration time must have been reached. (For more
principal facility.
information, see the CICS/ESA Application Programming
Note that CEDF is an exception to the START command and | Guide.) The INTERVAL or AFTER options
is not valid as a TRANSID name. You should therefore not should be specified when a transaction is to be
attempt to start CEDF in this way. executed on a remote system; this avoids complications
arising when the local and remote systems are in
You can use the RTRANSID, RTERMID, and QUEUE different time zones.
options to pass further data to the started task. These
If the TERMID option is specified, the named terminal
options can contain arbitrary data values whose meanings
must exist and be available. If the named terminal does
depend on what you have specified in the started and
not exist when the time interval expires, the START is
starting tasks. One possible way of using them is in the
discarded.

Chapter 1. Commands 303

START

If the PROTECT option is specified, the starting task improve performance when the START command has to be
must have taken a successful syncpoint. This option, shipped to a remote system; it is also a prerequisite if the
coupled to extensions to system tables, reduces the shipping of the START command is queued pending the
exposure to lost or duplicated data caused by failure of a establishing of links to the remote system.
starting task.
If the transaction to be executed is on a remote system, Starting tasks without terminals
the format of the data must be declared to be the same
as that at the local system. This is done using the RDO If the task to be started is not associated with a terminal,
options DATASTREAM and RECORDFORMAT, or each START command results in a separate task being
DATASTR and RECFM on the terminal control table started. This happens regardless of whether or not data is
TYPE=SYSTEM. For CICS-CICS, these are always the passed to the started task. The following examples show
default values. For CICS-IMS/VS, care should be taken how to start a specified task, not associated with a terminal,
to specify the correct values. in one hour:
EXEC CICS START
Execution of a START command naming a transaction in the
TRANSID('TRNL')
local system cancels any outstanding POST commands INTERVAL(1OOOO)
executed by the starting task. REQID('NONGL')
| START commands are queued by means of the EXEC CICS START
| TRANSACTION definition as described in the CICS/ESA TRANSID('TRNL')
| Resource Definition Guide. AFTER HOURS(1)
REQID('NONGL')

Passing data by interval control

Starting tasks with terminals but without
If data is to be passed by interval control (using the FROM data
option), it is queued on a temporary storage queue. The
REQID option allows you to specify the name of the Only one task is started if several START commands, each
| temporary storage queue to be used. This identifier may be specifying the same transaction and terminal, expire at the
| recoverable (in temporary storage terms) or nonrecoverable. same time or before the terminal is available.
| The difference between recoverable and nonrecoverable
The following examples show how to request initiation of a
| temporary storage is described in the CICS/ESA Application
task associated with a terminal. Because no request
| Programming Guide. The CICS/ESA Resource Definition
identifier is specified in this example, CICS assigns one and
| Guide describes how to define recoverable temporary
returns it to the application program in the EIBREQID field in
| storage queues.
the EXEC interface block.
| If you also specify the PROTECT option, the temporary EXEC CICS START
| storage queue identified by the REQID option should be TRANSID('TRN1')
| defined as recoverable. If you do not specify the PROTECT TIME(185OOO)
| option, the temporary storage queue should not be defined TERMID('STA5')
| as recoverable. Unpredictable results can occur if these EXEC CICS START
| rules are not followed. TRANSID('TRN1')
AT HOURS(18) MINUTES(5O)
# If you specify the FROM and not the REQID option, CICS TERMID('STA5')
# will generate a queue name for FROM data passed on the
# START. If PROTECT is not specified, the queue name has
# a prefix ‘DF’. If PROTECT is specified, the queue name has Starting tasks with terminals and data
# a prefix of the (unprintable) character X'FC'. CICS treats all
Data is passed to a started task if one or more of the FROM,
# FC-prefixed queues are recoverable if there is a TST, and
RTRANSID, RTERMID, and QUEUE options is specified.
# non-recoverable if there is no TST.
Such data is accessed by the started task by using a
RETRIEVE command.
Error checking and performance
considerations It is possible to pass many data records to a new task by
issuing several START commands, each specifying the same
The NOCHECK option specifies that no response (to transaction and terminal.
execution of the START command) is expected by the
starting transaction. For START commands naming tasks to Execution of the first START command ultimately causes the
be started on a local system, error conditions are returned; new task to be started and allows it to retrieve the data
error conditions are not returned for tasks to be started on a specified on the command. The new task is also able to
remote system. The NOCHECK option allows CICS to retrieve data specified on subsequently executed START

304 CICS/ESA Application Programming Reference

START

| commands that expire before the new task is terminated. If The following examples show how to start a task associated
| the transaction has been defined as restartable (by defining with a terminal and pass data to it:
| the transaction using the RDO option RESTART(YES)) and EXEC CICS START
| such data has not been retrieved before the new task is TRANSID('TRN2')
| terminated, another new task is started and is able to retrieve TIME(173OOO)
| the outstanding data. If the subsequent new task fails to TERMID('STA3')
| retrieve the outstanding data, a third task will be started and REQID(DATAREC)
| so on, up to a maximum of five times, after which the data is FROM(DATAFLD)
| discarded. If the transaction has not been defined as LENGTH(1OO)
| restartable, no new task is initiated and the data is discarded. EXEC CICS START
TRANSID('TRN2')
AT HOURS(17) MINUTES(3O)
TERMID('STA3')
REQID(DATAREC)
FROM(DATAFLD)
LENGTH(1OO)

There are two ways to enter the time under AFTER and AT.
1. A combination of at least two of HOURS(0–99),
MINUTES(0–59), and SECONDS(0–59). HOURS(1)
SECONDS(3) would mean one hour and three seconds
(the minutes default to zero).
2. As one of HOURS(0–99), MINUTES(0–5999), or
SECONDS(0–359 999). HOURS(1) means one hour.
MINUTES(62) means one hour and two minutes.
SECONDS(3723) means one hour, two minutes, and
three seconds.

START failures without exception

conditions
There are some circumstances in which a START command
is executed without error, but the started task never takes
place:
When the transaction or its initial program is disabled at
the time CICS attempts to create the task.
When the START specifies a terminal and an expiration
time, and the terminal is not defined (and cannot be
located by the XICTENF or XALTENF exits) at expiration
time.
When the START specifies a terminal that is not defined
(and cannot be located by the XICTENF or XALTENF
exits) at the time CICS attempts to create the task.

These exposures result from the delay between the

execution of the START and the time of task creation. Even
when the START is immediate, CICS may delay creating the
task, either because the required terminal is not free or
because of other system constraints.

You can use INQUIRE commands to ensure that the

transaction and program are enabled at the time of the
START command, but either may become disabled before
task creation.

You get a TERMIDERR condition if the requested terminal

does not exist at the time of the START, but if it is deleted

Chapter 1. Commands 305

START

subsequently, as occurs if the user logs off, your START | MINUTES(data-value)

request is discarded with the terminal definition. | specifies a fullword binary value in the range 0–59, when
| HOURS or SECONDS are also specified, or 0–5999
| when MINUTES is the only option specified.
START options
NOCHECK
AFTER
specifies that, for a remote system, CICS should
specifies the amount of time to elapse before starting.
improve performance of the START command by
AT specifies the time of starting. providing less error checking and slightly less function.
# For more information, see the section about improving
Apar PN92143 the performance of intersystem START requests in the
# Documentation for Apar PN92143 added 28/02/97 CICS/ESA Intercommunication Guide.

PROTECT
# ATTACH specifies that the new task is not started until the starting
# specifies that a non-terminal task is to be started at once task has taken a syncpoint. If the starting task abends
# in the local system. The only other options that may be before the syncpoint is taken, the request to start the
# used with ATTACH are FROM and LENGTH. If these new task is canceled. If the REQID option is also
# are specified, the data is not written to temporary specified, the request identifier should be a name
# storage. The attached task retrieves the data in the defined as recoverable to temporary storage. If the
# normal way but in effect only its address is passed. The started transaction is remote, PROTECT specifies that it
# task issuing the start must ensure that the data is valid must not be scheduled until the local transaction has
# when it is retrieved either by synchronizing its execution successfully completed a syncpoint. For more
# with the attached task, or by placing the data in shared information about the PROTECT option with remote
# storage. transactions, see the CICS/ESA Intercommunication
# The attached task has a STARTCODE of U and cannot Guide.
# be cancelled, so EIBREQID is set to nulls. QUEUE(name)
# ATTACH allows a START issued in a PLTPI program to # specifies a name (1–8 characters) that is passed to the
# take effect before initialization has completed. # started task. If this name represents a temporary storage
# queue, the queue must be local to the started task. The
FMH # contents of the queue are not passed.
specifies that the user data to be passed to the started
task contains function management headers. If you are also specifying REQID, make sure that the
name of the REQID and the name of the QUEUE are
FROM(data-area) not the same.
specifies the data to be stored for a task that is to be
started at some future time. REQID(name)
specifies a name (1–8 characters), which should be
| HOURS(data-value) | unique, to identify a command. This option can be used
specifies a fullword binary value in the range 0–99. | when another task is to be provided with the capability of
| canceling an unexpired command.
INTERVAL(hhmmss)
specifies the expiration time as an interval of time that is | If this option is omitted, CICS generates a unique
to elapse from the time at which the START command is | request identifier in the EIBREQID field of the EXEC
issued. The mm and ss are each in the range 0–59. | interface block, unless the NOCHECK option is
The time specified is added to the current clock time by | specified, in which case field EIBREQID is set to nulls
CICS when the command is executed, to calculate the | and cannot be used subsequently to cancel the START
expiration time. | command.
| When using the C language, you are recommended to | If you include any of the data options (FROM,
| use the AFTER/AT HOURS, MINUTES, and SECONDS | RTERMID, RTRANSID or QUEUE), the data is stored in
| options as C does not provide a packed decimal data | temporary storage using the REQID name specified (or
| type. You may use INTERVAL, but if the value specified | CICS generated) as the identifier. The temporary
| is not an integer constant, the application is responsible | storage record thus identified must be local to the CICS
| for ensuring that the value passed to CICS is in packed | system where the START command is processed. The
| decimal format. START command is processed on the system identified
by the SYSID option or, if the SYSID option is omitted,
LENGTH(data-value) on the system associated with the TRANSID option.
specifies a halfword binary data value that is the length
of the data to be stored for the new task. # If the same REQID name is specified on more than one
# START command, the behavior of subsequent
# RETRIEVE and CANCEL requests is unpredictable. In

306 CICS/ESA Application Programming Reference

START

# particular, the correspondence between each START | of whether or not the transaction definition is defined as
# and its data is lost. | remote in the PCT. Otherwise the transaction definition
is used to find out whether the transaction is on a local
RTERMID(name)
or a remote system.
specifies a value (1–4 characters), for example a
terminal name, that may be retrieved when the | USERID(data-value)
transaction, specified in the TRANSID option in the | Specifies the userid under whose authority the started
START command, is started. | transaction is to run, if the started transaction is not
| associated with a terminal (that is, when TERMID is not
When retrieved, the value may be used in the TERMID
| specified). This is referred to as userid1.
option of a subsequent START command.
| If you omit both TERMID and USERID, CICS uses
RTRANSID(name)
| instead the userid under which the transaction that
specifies a value (1–4 characters), for example a
| issues the START command is running. This is referred
transaction name, that may be retrieved when the
| to as userid2.
transaction, specified in the TRANSID option in the
START command, is started. | By using either userid1 or userid2 CICS ensures that a
| started transaction always runs under a valid userid,
When retrieved, the value may be used in the TRANSID
| which must be authorized to all the resources referenced
option of a subsequent START command.
| by the started transaction.
| SECONDS(data-value) | CICS performs a surrogate security check against
| specifies a fullword binary value in the range 0–59, when | userid2 to verify that this user is authorized to userid1.
| HOURS or MINUTES are also specified, or 0–359 999 | If userid2 is not authorized, CICS returns a NOTAUTH
| when SECONDS is the only option specified. | condition. The surrogate check is not done here if
| USERID is omitted.
SYSID(systemname)
specifies the name of the system to which the request is
directed. START conditions
TERMID(name) INVREQ
specifies the symbolic identifier (1–4 alphanumeric occurs in any of the following situations:
characters) of the principal facility associated with a
transaction to be started as a result of a START Apar PQ19047
command. This principal facility can be either a terminal Documentation for Apar PQ19047 added 27/10/98,
(the usual case) or an APPC session. Where an APPC modifies RCF 11734 added 1/12/97
session is specified, the connection (or modeset) name
is used instead of a terminal identifier. This option is
# The START command is not valid for processing by
required when the transaction to be started must
# CICS
communicate with a terminal; it should be omitted
# Values specified in the INTERVAL option are out of
otherwise.
# range
The terminal identifier must be defined as either a local # The value specified in HOURS, for AFTER and AT
or a remote terminal on the system in which the START # options, is out of range (RESP2=4)
command is executed, when the start of the # The value specified in MINUTES, for AFTER and
transaction takes effect. # AT options, is out of range (RESP2=5
# The value specified in SECONDS, for AFTER and
TIME(hhmmss)
# AT options, is out of range (RESP2=6)
specifies the time when a new task should be started.
# A START operation specifies a REQID name that
| When using the C language, you are recommended to # corresponds to an existing user temporary storage
| use the AFTER/AT HOURS, MINUTES, and SECONDS # queue
| options as C does not provide a packed decimal data # An attempt was made to ship a START request with
| type. You may use TIME, but if the value specified is # the ATTACH option (RESP2=11)
| not an integer constant, the application is responsible for # A START request with the ATTACH option has
| ensuring that the value passed to CICS is in packed # failed (RESP2=12).
| decimal format. | A USERID is specified and the CICS external
| security manager interface is not initialized
TRANSID(name)
| (RESP2=18)
specifies the symbolic identifier (1–4 characters) of the
transaction to be executed by a task started as the result # Apar PN92143
of a START command.
# Documentation for Apar PN92143 added 28/02/97
| If SYSID is specified, and names a remote system, the # RESP2=11 and 12 added
| transaction is assumed to be on that system irrespective

Chapter 1. Commands 307

START

Default action: terminate the task abnormally. TRANSIDERR

occurs if the transaction identifier specified in a START
IOERR
command cannot be found in the program control table.
| occurs in any of the following situations:
Default action: terminate the task abnormally.
| An input/output error occurred during a START
| operation. | USERIDERR
| occurs in any of the following situations:
| A START operation attempts to write to temporary
| storage when the temporary storage data set is full. | The specified USERID is not known to the external
| security manager (RESP2=8).

| The external security manager is in a state such
# Uses a REQID that corresponds to an existing
| that CICS cannot determine whether a specified
# ‘recoverable’ temporary storage queue. This
| USERID is valid (RESP2=10).
# condition only occurs when the FROM option is also
# used. | Default action: Terminate the task abnormally.
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition.
Default action: terminate the task abnormally.

LENGERR
occurs if LENGTH is not greater than zero.
Default action: terminate the task abnormally.

NOTAUTH
| occurs in any of the following situations:

| A resource security check fails on TRANSID (name)

| (RESP2=7).
| A surrogate user security check fails on USERID
| (name) (RESP2=9).
| The security access capabilities of the transaction
| that issued the command do not allow the command
| to be performed with the value specified in the
| USERID option. The security access capabilities of
| the transaction have been established by the
| external security manager according to user
| security, and whether link security or the execution
| diagnostic facility (EDF) have been in use.

Default action: terminate the task abnormally.

SYSIDERR
| occurs when the SYSID option specifies a name that is
| neither the local system nor a remote system (made
| known to CICS by defining a CONNECTION).
SYSIDERR also occurs when the link to the remote
system is known but unavailable. This condition may
not be raised if the user exit XISLCLQ is enabled (see
the CICS/ESA Customization Guide for programming
information).
Default action: terminate the task abnormally.

TERMIDERR
occurs if the terminal identifier in a START command
cannot be found in the terminal control table.
Default action: terminate the task abnormally.

308 CICS/ESA Application Programming Reference

STARTBR

Function
Start browse of a file.

Command syntax

──STARTBR──FILE(filename)──RIDFLD(data-area)──┬────────────────────────────────────┬─────────────────────
└─KEYLENGTH(data-value)──┬─────────┬─┘
└─GENERIC─┘
──┬───────────────────┬──┬───────────────────┬──┬────────┬──┬───────┬──"
└─REQID(data-value)─┘ └─SYSID(systemname)─┘ ├─RBA────┤ ├─GTEQ──┤
├─RRN────┤ └─EQUAL─┘
├─DEBKEY─┤
└─DEBREC─┘
Conditions:
| DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LOADING, NOTAUTH, NOTFND,
NOTOPEN, SYSIDERR

STARTBR specifies the record in a file, or in a data table, on STARTBR options

a local or a remote system, where you want the browse to
start. No records are read until a READNEXT command (or, DEBKEY (blocked BDAM)
for VSAM and CICS-maintained tables, a READPREV specifies that deblocking is to occur by key. If neither
command) is executed. DEBREC nor DEBKEY is specified, deblocking does not
occur.
A browse operation may be:
DEBREC (blocked BDAM)
A direct browse of a key sequenced data set (KSDS) by specifies that deblocking is to occur by relative record
record key. (relative to zero). If neither DEBREC nor DEBKEY is
A direct browse of an entry sequenced data set (ESDS) specified, deblocking does not occur.
by relative byte address (RBA). EQUAL (VSAM and data table)
A direct browse of a relative record data set (RRDS) by specifies that the search is satisfied only by a record
relative record number (RRN). having the same key (complete or generic) as that
specified in the RIDFLD option.
A browse of a key sequenced data set (KSDS) using an
alternate index path. This option is the default field for a direct ESDS browse.
A browse of an entry sequenced data set (ESDS) using FILE(filename)
an alternate index path. In this case, an ESDA is specifies the of the file to be accessed.
browsed by key in the same way as a KSDS. Some of
If SYSID is specified, the data set to which this file refers
the options that are not valid for a direct ESDS browse
is assumed to be on a remote system irrespective of
are valid for an alternate index browse.
whether the name is defined in the FCT. Otherwise, the
The options specified on the STARTBR command define the FCT entry is used to find out whether the data set is on
characteristics that apply throughout the subsequent browse a local or a remote system.
operation. Specifically, if GENERIC or GTEQ are specified, GENERIC (VSAM KSDS, path or data table)
they are used not only when determining the starting point of specifies that the search key is a generic key whose
the browse, but also whenever the value of RIDFLD is length is specified in the KEYLENGTH option. The
changed before issuing a READNEXT command. search for a record is satisfied when a record is found
that has the same starting characters (generic key) as
If you specify the RBA option, it applies to every READNEXT
those specified.
or READPREV command in the browse, and causes CICS to
return the relative byte address of each retrieved record. GTEQ (VSAM or data table)
specifies that, if the search for a record having the same
None of these options can be changed during a browse, key (complete or generic) as that specified in the
except by means of the RESETBR command. For a RIDFLD option is unsuccessful, the first record having a
CICS-maintained data table, STARTBR refers to the source greater key satisfies the search.
VSAM KSDS.

Chapter 1. Commands 309

STARTBR

This option is the default for directly browsing through a This option should only be used with files referencing
KSDS or an RRDS. It is not valid for directly browsing relative record data sets.
an ESDS, although it is valid for browsing through an
SYSID(systemname)
ESDS using a path.
specifies the name of the system to which the request is
KEYLENGTH(data-value) directed.
specifies the length (halfword binary) of the key that has
If you specify SYSID, and omit both RBA and RRN, you
been specified in the RIDFLD option, except when RBA
must also specify KEYLENGTH.
or RRN is specified, in which case KEYLENGTH is not
valid.
This option must be specified if GENERIC is specified,
STARTBR conditions
and it can be specified whenever a key is specified. If Note: RESP2 values are not set for files that are on remote
the length specified is different from the length defined systems.
for the data set and the operation is not generic, the
DISABLED
INVREQ condition occurs.
occurs if a file is disabled (RESP2=50). A file may be
The INVREQ condition also occurs if a STARTBR disabled because:
command specifies GENERIC, and the KEYLENGTH is
not less than that specified in the VSAM definition. It was initially defined as disabled and has not since
been enabled.
If KEYLENGTH(0) is used with the object of positioning
on the first record in the data set, the GTEQ option must It has been disabled by a SET FILE or a CEMT
also be specified. If EQUAL is specified either explicitly SET FILE command.
or by default with KEYLENGTH(0), the results of the Default action: terminate the task abnormally.
STARTBR is unpredictable.
FILENOTFOUND
# RBA (VSAM ESDS, KSDS, or CMT) occurs if a file name referred to in the FILE option
# (base data sets only, not paths) cannot be found in the FCT and SYSID has not been
# specifies that the record identification field specified in specified (RESP2=1).
# the RIDFLD option contains a relative byte address.
# Use this option only when browsing an ESDS base, or a Default action: terminate the task abnormally.
# KSDS base when using relative byte addresses instead ILLOGIC (VSAM)
of keys to identify the records. occurs if a VSAM error occurs that does not fall within
| You cannot use RBA for user-maintained data tables. one of the other CICS response categories
(RESP2=110).
REQID(data-value)
specifies as a halfword binary value a unique request # (See EIBRCODE in the EXEC interface block; refer to
identifier for a browse, used to control multiple browse Appendix A, “EXEC interface block” on page 343 for
operations on the same or different data sets. If this details.)
option is not specified, a default value of zero is Default action: terminate the task abnormally.
assumed.
INVREQ
RIDFLD(data-area) occurs in any of the following situations:
# specifies the record identification field. When combined
# with RBA or RRN this is a 4-character field. The Browse operations are not allowed according to the
contents can be a key, a relative byte address, or file entry specification in the FCT (RESP2=20).
relative record number (for VSAM data sets), or a block The KEYLENGTH and GENERIC options are
reference, physical key, and deblocking argument (for specified, and the length defined for the data set to
BDAM data sets). For a relative byte address or a which this file specified in the KEYLENGTH option
relative record number, the format of this field must be is greater than or equal to the length of a full key
fullword binary. For a relative byte address, the RIDFLD (RESP2=25).
can be greater than or equal to zero. For a relative
The KEYLENGTH option is specified (but the
record number, the RIDFLD can be greater than or
GENERIC option is not specified), and the specified
equal to 1.
length does not equal the length defined for the data
For VSAM, a full record id of X'FF's indicates that the set to which this file refers (RESP2=26).
browse is to be positioned at the end of the data set in
An attempt is made to start a browse with a REQID
preparation for a backwards browse using READPREV
already in use for another browse (RESP2=33).
commands.
The KEYLENGTH and GENERIC options are
RRN (VSAM RRDS) specified, and the length specified in the
specifies that the record identification field specified in KEYLENGTH option is less than zero (RESP2=42).
the RIDFLD option contains a relative record number.

310 CICS/ESA Application Programming Reference

STARTBR

The specified file is a user-maintained data table This condition does not occur if the request is made
(RESP2=44). Browse commands are not in the either to a CLOSED, ENABLED file or to a CLOSED,
subset of the file control API that may be used for DISABLED file. In the first case, the file is opened as
user-maintained data tables. part of executing the request. In the second case, the
DISABLED condition occurs.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
IOERR
occurs if there is an I/O error during the file control
operation (RESP2=120). An I/O error is any unusual
event that is not covered by a CICS condition.
For VSAM files, IOERR normally indicates a hardware
error.
(Further information is available in the EXEC interface
block; refer to Appendix A, “EXEC interface block” on
page 343 for details.)
Default action: terminate the task abnormally.

ISCINVREQ
occurs when the remote system indicates a failure that
does not correspond to a known condition (RESP2=70).
Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.

NOTFND
occurs if an attempt to position on a record based on the
search argument provided is unsuccessful (RESP2=80).
NOTFND can also occur if a generic STARTBR with
KEYLENGTH(0) specifies the EQUAL option.
Default action: terminate the task abnormally.

NOTOPEN
occurs in any of the following situations (RESP2=60):

The requested file is CLOSED and UNENABLED.

The CLOSED, UNENABLED state is reached after a
CLOSE request has been received against an
OPEN ENABLED file and the file is no longer in
use. This state can also be specified as the initial
state by means of the FILSTAT parameter of the file
control table TYPE=FILE, or by defining a
user-maintained data table using the RDO options
STATUS=UNENABLED and
OPENTIME=FIRSTREF.
The requested file is OPEN and in use by other
transactions, but a CLOSE request against the file
has been received.

Chapter 1. Commands 311

STARTBR

312 CICS/ESA Application Programming Reference

SUSPEND

Function
Suspend a task.

Command syntax

──SUSPEND──"

SUSPEND relinquishes control to a task of higher or equal dispatching priority. Control is returned to the task issuing the
command as soon as no other task of a higher or equal priority is ready to be processed.

Chapter 1. Commands 313

SYNCPOINT

Function
Establish a syncpoint.

Command syntax

──SYNCPOINT──"
Conditions:
| INVREQ, ROLLEDBACK

SYNCPOINT divides a task (usually a long-running one) into

smaller LUWs. It specifies that all changes to recoverable
resources made by the task since its last syncpoint are to be
committed.

314 CICS/ESA Application Programming Reference

SYNCPOINT ROLLBACK

Function
Back out to last syncpoint.

Command syntax

──SYNCPOINT──ROLLBACK──"
Conditions:
INVREQ

SYNCPOINT ROLLBACK option

ROLLBACK
specifies that all changes to recoverable resources made
by the task since its last syncpoint are to be backed out.
This option can be used, for example, to tidy up in a
HANDLE ABEND routine, or to revoke database
changes after the application program finds irrecoverable
errors in its input data.
If the LUW updates remote recoverable resources using
an MRO or APPC session, the ROLLBACK option is
propagated to the back-end transaction.
When a distributed transaction processing conversation
is in use, the remote application program has the EIB
fields EIBSYNRB, EIBERR, and EIBERRCD set. For
the conversation to continue, the remote application
program should execute a SYNCPOINT ROLLBACK
command.
When the mirror transaction is involved in the LUW
using an MRO or APPC session, the mirror honors the
rollback request, revokes changes, and then terminates
normally.
This option is not supported across LUTYPE6.1 VTAM
sessions to the mirror or back-end transactions. In
these cases, the front-end transactions could be
abended to cause the back-end transactions to back out.

SYNCPOINT ROLLBACK condition

| INVREQ
| occurs if SYNCPOINT ROLLBACK was in a program
| that is linked to from a remote system that has not
| specified the SYNCONRETURN option, or if it has been
| linked to locally and is defined with
| EXECUTIONSET=DPLSUBSET (RESP2=200).
Default action: terminate the task abnormally.

Chapter 1. Commands 315

UNLOCK

Function
Release exclusive control.

Command syntax

──UNLOCK──FILE(filename)──┬───────────────────┬──┬───────────────────┬──"
| └─TOKEN(data-value)─┘ └─SYSID(systemname)─┘
Conditions:
| DISABLED, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, NOTAUTH, NOTOPEN, SYSIDERR

UNLOCK releases the exclusive control established in It has been disabled by a SET FILE or a CEMT
response to a READ command with the UPDATE option. SET FILE command.
You use it if you retrieve a record for update, and then
This condition cannot occur when the UNLOCK
decide that you do not want to update the record after all.
follows a successful read for update or a VSAM
However, for a data set for which the system programmer
WRITE MASSINSERT.
| has specified automatic logging, or for a user-maintained
| data table that has been defined as recoverable, the Default action: terminate the task abnormally.
resource remains under the task control enqueue until either
FILENOTFOUND
a syncpoint command is executed or the task is terminated.
occurs if a file name referred to in the FILE option
| The record can be in a data set, or in a CICS or user
cannot be found in the FCT and SYSID has not been
maintained data table, on a local or a remote system.
specified (RESP2=1).
Use this command to terminate a VSAM WRITE Default action: terminate the task abnormally.
MASSINSERT operation against a VSAM file.
ILLOGIC (VSAM and CICS-maintained data tables)
occurs if a VSAM error occurs that does not fall within
UNLOCK options one of the other CICS response categories
FILE(filename) (RESP2=110).
specifies the of the file to be released. # (See EIBRCODE in the EXEC interface block; refer to
If SYSID is specified, the data set to which this file refers Appendix A, “EXEC interface block” on page 343 for
is assumed to be on a remote system irrespective of details.)
whether the name is defined in the FCT. Otherwise, the Default action: terminate the task abnormally.
FCT entry is used to find out whether the data set is on
a local or a remote system. | INVREQ
| occurs in any of the following situations:
SYSID(systemname)
specifies the name of the system to which the request is | An unlock includes a token whose value cannot be
directed. | matched against any token in use for an existing
| READ for UPDATE request (RESP2=47).
| TOKEN(data-value)
| An attempt is made to function-ship a request which
# specifies as a fullword binary value a unique request
| includes a TOKEN keyword (RESP2=48).
| identifier for an UNLOCK, used to associate it with a
| previous READ for UPDATE request. | If an UNLOCK command does not have a token, an
| attempt is made to match it to a READ for UPDATE
| which also does not have a token. If this is not found,
UNLOCK conditions | no action is taken and a NORMAL response is returned.
Note: RESP2 values are not set for files that are on remote
| Default action: terminate the task abnormally.
systems.
IOERR
DISABLED
occurs if there is an I/O error during the file control
occurs if a file is disabled (RESP2=50). A file may be
operation (RESP2=120). An I/O error is any unusual
disabled because:
event that is not covered by a CICS condition.
It was initially defined as disabled and has not since For VSAM files, IOERR normally indicates a hardware
been enabled. error.

316 CICS/ESA Application Programming Reference

UNLOCK

(Further information is available in the EXEC interface NOTOPEN

block; refer to Appendix A, “EXEC interface block” on occurs in any of the following situations (RESP2=60):
page 343 for details.)
The requested file is CLOSED and UNENABLED.
Default action: terminate the task abnormally. The CLOSED, UNENABLED state is reached after a
CLOSE request has been received against an
ISCINVREQ
OPEN ENABLED file and the file is no longer in
occurs when the remote system indicates a failure that
use. This state can also be specified as the initial
does not correspond to a known condition (RESP2=70).
state by means of the FILSTAT parameter of the file
Default action: terminate the task abnormally. control table TYPE=FILE, or by defining a file using
the RDO options STATUS=UNENABLED and
NOTAUTH
OPENTIME=FIRSTREF.
occurs when a resource security check has failed on
FILE(filename) (RESP2=101). The requested file is OPEN and in use by other
transactions, but a CLOSE request against the file
Default action: terminate the task abnormally.
has been received.

This condition does not occur if the request is made to

either a CLOSED, ENABLED file or a CLOSED,
DISABLED file. In the first case, the file is opened as
part of executing the request. In the second case, the
DISABLED condition occurs.
It also cannot occur when the UNLOCK follows a
successful READ for update or a WRITE MASSINSERT
operation.
Default action: terminate the task abnormally.

Chapter 1. Commands 317

VERIFY PASSWORD

| VERIFY PASSWORD

| Function
| Allows an application to check that a password matches the password recorded by an external security manager (ESM) for a
| userid, and return values recorded by the external security manager for the password.

| Command syntax
|
| ──VERIFY PASSWORD(data-value)──USERID(data-value)──┬───────────────────────┬──┬─────────────────────┬────
| └─CHANGETIME(data-area)─┘ └─DAYSLEFT(data-area)─┘
| ──┬──────────────────────┬──┬────────────────────┬──┬───────────────────────┬─────────────────────────────
| └─ESMREASON(data-area)─┘ └─ESMRESP(data-area)─┘ └─EXPIRYTIME(data-area)─┘
| ──┬─────────────────────────┬──┬────────────────────────┬──"
| └─INVALIDCOUNT(data-area)─┘ └─LASTUSETIME(data-area)─┘
| Conditions:
| INVREQ, NOTAUTH, USERIDERR

| Unlike the SIGNON command, VERIFY PASSWORD does | ESMRESP(data-area)

| not depend upon the principal facility, so it can be issued | returns the response code, in a fullword binary field, that
| when the facility is an APPC session. | CICS receives from the external security manager.
| If the external security manager is RACF, this field is the
| When the external security manager is RACF, the
| RACF return code.
| CHANGETIME and EXPIRYTIME outputs always show as
| midnight. | EXPIRYTIME(data-area)
| returns the date and time the password will expire, in
| If a VERIFY PASSWORD request is successful, you should
| ABSTIME units.
| not infer that a signon would also be successful. For
| example, the USERID may be revoked in one or more RACF | When the external security manager is RACF, the time
| group connections, or may not be able to signon in this CICS | is shown as midnight.
| region.
| INVALIDCOUNT(data-area)
| | returns the number of times an invalid password was
Warning: Clear password fields after use
| entered for this user.
| You should clear the password fields on the EXEC CICS | LASTUSETIME(data-area)
| commands that have a password option as soon as | returns the data and time this userid was last accessed,
| possible after use. This is to ensure that passwords are | in ABSTIME units.
| not revealed in system or transaction dumps.
| PASSWORD(data-value)
| specifies the password, 8 characters, that you want the
| external security manager to check for the specified
| VERIFY PASSWORD options | userid. The other data is not returned if the password is
| CHANGETIME(data-area) | not valid.
| returns the date and time the password was last
| USERID(data-value)
| changed, in ABSTIME units.
| specifies the userid, 8 characters, of the user whose
| When the external security manager is RACF, the time | password is to be checked.
| is shown as midnight.
| Note: In the CHANGETIME, LASTUSETIME, and
| DAYSLEFT(data-area) | EXPIRYTIME options, the time value returned is in the same
| returns the number of days from now, in a halfword | format as the ASKTIME command, so it can be reformatted
# binary field, until the password expires. If the password | as a date and time, in a format specified by the caller, by
# is non-expiring, -1 is returned. | using the FORMATTIME command.
| ESMREASON(data-area) | Unlike the SIGNON command, the VERIFY PASSWORD
| returns the reason code, in a fullword binary field, that | command does not depend upon the principal facility, so can
| CICS receives from the external security manager. | be issued when the facility is an APPC session.
| If the ESM is RACF, this field is the RACF reason code.
| If a user has a never-expiring password that was established
| with the RACF PASSWORD USER(userid) NOINTERVAL

318 CICS/ESA Application Programming Reference

VERIFY PASSWORD

| command, the outputs DAYSLEFT and EXPIRYTIME have

| little meaning and are shown as −1.

| VERIFY PASSWORD conditions

| INVREQ
| occurs in any of the following situations:

| There is an unknown return code in ESMRESP from

| the external security manager (RESP2=13).
| The CICS external security manager interface is not
| initialized (RESP2=18).
| The external security manager is not responding
| (RESP2=29).
# Apar 69349
# Documentation for Apar 69349 added 31 May
# 1995 (TUCKER)

# The userid field contains a blank character in an

# invalid position (RESP2=32).

| Default action: terminate the task abnormally.

| NOTAUTH
| occurs in any of the following situations:

| The supplied password is wrong (RESP2=2). If the

| USERIDERR
| occurs if the USERID is not known to the external
| security manager (RESP2=8).
| Default action: terminate the task abnormally.

Chapter 1. Commands 319

WAIT CONVID (APPC)

Function
Ensure accumulated data is transmitted on an APPC mapped conversation.

Command syntax

──WAIT CONVID(name)──┬─────────────┬──"
└─STATE(cvda)─┘
Conditions:
INVREQ, NOTALLOC

WAIT CONVID allows an application program to ensure that NOTALLOC

any accumulated application data and control indicators from occurs if the CONVID value in the command does not
a SEND command, or the results of a CONNECT PROCESS relate to a conversation that is owned by the application.
command, are transmitted to the partner transaction.
Default action: terminate the task abnormally.

WAIT CONVID options

CONVID(name)
identifies the conversation to which the command
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command
in EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed
ASSIGN command).

STATE(cvda)
gets the state of the current conversation. The cvda
values returned by CICS are:

ALLOCATED
CONFFREE
CONFRECEIVE
CONFSEND
FREE
PENDFREE
PENDRECEIVE
RECEIVE
ROLLBACK
SEND
SYNCFREE
SYNCRECEIVE
SYNCSEND

WAIT CONVID conditions

INVREQ
occurs in any of the following situations:

The command is used on a conversation that is not

using the EXEC CICS interface or that is not a
mapped conversation
Command not supported for distributed program link
when it refers to the principal facility (RESP2=200).

Default action: terminate the task abnormally.

320 CICS/ESA Application Programming Reference

WAIT EVENT

Function
Wait for an event to occur.

Command syntax

──WAIT EVENT──ECADDR(ptr-value)──┬────────────┬──"
| └─NAME(name)─┘
Conditions:
INVREQ

| Note for dynamic transaction routing

WAIT EVENT synchronizes a task with the completion of an WAIT EVENT condition
event initiated by the same task or by another task. The
event would normally be the posting, at the expiration time, INVREQ
of a timer-event control area provided in response to a POST occurs in any of the following situations:
command, as described in “POST” on page 178. The WAIT The value of the pointer is zero (X'00000000')
EVENT command provides a method of directly relinquishing (RESP2=2).
control to some other task until the event being waited on is
completed. The specified event control area address is above
the 16MB line for programs executing in 24-bit
| CICS includes the addresses of all ECBs passed by WAIT mode (RESP2=3).
| EVENT commands of current tasks in the ECBLIST passed The event control area address is not aligned on a
| by CICS to the MVS WAIT facility when it runs out of work. fullword boundary (RESP2=4).
| Such ECBs can be posted using the MVS POST facility or by
| hand posting. Hand posting could, for example, be done by | The timer-event control area specified on a WAIT
| moving an appropriate value into the ECB. | EVENT is in user-key task-lifetime storage, and is
| inaccessible to another transaction. This condition
| A given ECB may not be waited on by more than one task at | can only occur if the storage for the timer-event
| the same time. If this rule is not followed and the ECBLIST | control area is obtained other than by a POST
| passed by CICS on the MVS WAIT contains duplicate ECB | command, and is for posting as an ECB by some
| addresses, MVS abends CICS. | other task on completion of an event (RESP2=6).
| Note: CICS obtains storage for a timer-event
The following example shows you how to suspend the
| control area in response to a POST command (and
processing of a task until the specified event control area is
| which can be used in conjunction with the WAIT
posted:
| EVENT command) from a shared subpool in
EXEC CICS WAIT EVENT ECADDR(PVALUE) | user-key storage. This ensures that timer-event
| control areas are in shared storage and, when
WAIT EVENT options | referenced by a subsequent WAIT EVENT
| command, do not fail with an INVREQ.
ECADDR(ptr-value)
specifies the address of the timer-event control area that Default action: terminate the task abnormally.
must be posted before task activity can be resumed.

Chapter 1. Commands 321

WAIT EXTERNAL

Function
Synchronize events.

Command syntax

┌─PURGEABLE──────────┐
──WAIT EXTERNAL──ECBLIST(ptr-value)──NUMEVENTS(data-value)──┼────────────────────┼──┬────────────┬──"
| ├─PURGEABILITY(cvda)─┤ └─NAME(name)─┘
└─NOTPURGEABLE───────┘
Conditions:
INVREQ

| Note for dynamic transaction routing

WAIT EXTERNAL waits for events that post MVS-format PTR_ECB_ADDR_LIST

ECBs. The command causes the issuing task to be ┌─────────────────┐
│A(ECB_ADDR_LIST) │
suspended until one of the ECBs has been posted, that is └──────┬──────────┘
until one of the events has occurred. The task can wait on │
one or more ECBs. If it waits on more than one, it is │ ECB_ADDR_LIST ┌──────────┐
dispatchable as soon as one of the ECBs is posted. You └─────────────────────┐ │ │ ECB1 │
must ensure that each ECB is cleared (set to binary zeros) │ A(ECB1) ├───┘ └────────┘
no later than the earliest time it could be posted. CICS ├───────────┤
│ A(ECB2) ├──────────────┐
cannot do this for you. If you wait on an ECB that has been ├───────────┤ │ ECB2 │
previously posted and not subsequently cleared, your task is │ A(ECB3) ├───┐ └────────┘
not suspended and continues to run as though the WAIT └───────────┘ │
EXTERNAL had not been issued. └──────────┐
│ ECB3 │
CICS uses extended ECBs and the MVS POST exit └────────┘
mechanism for ECBs passed by WAIT EXTERNAL; therefore DCL
do not use WAIT EXTERNAL unless you are sure that the | ECB1 FIXED BIN(31), /_ actual ecb _/
ECBs are not posted by any method other than the MVS | ECB2 FIXED BIN(31), /_ actual ecb _/
POST service or the standard ‘optimized post’ logic using a | ECB3 FIXED BIN(31); /_ actual ecb _/
compare-and-swap (CS) instruction. Note that the standard | DCL /_ list of ecb addresses _/
‘optimized post’ logic is only applicable when the ECB is not | 1 ECB_ADDR_LIST,
waiting, that is when the wait bit X'80' is not on. | 2 ECB_ADDR(3) PTR;
| DCL /_ ptr to each addr list _/
If a WAIT EXTERNAL ECB is hand posted, for example by | PTR_ECB_ADDR_LIST PTR;
ECB_ADDR(1) = ADDR(ECB1);
another task moving a value into the ECB, unpredictable
ECB_ADDR(2) = ADDR(ECB2);
errors occur. If there is any possibility of hand posting, use
ECB_ADDR(3) = ADDR(ECB3);
the WAITCICS command. Use WAIT EXTERNAL whenever /_ set up pointer _/
possible, because it usually has less overhead. PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR_LIST);
/_ PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR(1));
A given ECB must not be waited on by more than one task (alternative) _/
at the same time. If this rule is not followed, the second task EXEC CICS WAIT EXTERNAL
to wait on the ECB gets an INVREQ condition. ECBLIST(PTR_ECB_ADDR_LIST)
NUMEVENTS(3)
Figure 5 shows how to use the ECBLIST parameter to point PURGEABLE
to a list of ECB addresses that in turn point to individual
Figure 5. ECBLIST option, EXEC CICS WAIT EXTERNAL
ECBs. Note that the ECBLIST variable is a pointer pointing
to the first address of the list.

322 CICS/ESA Application Programming Reference

WAIT EXTERNAL

WAIT EXTERNAL options WAIT EXTERNAL condition

| ECBLIST(ptr-value) INVREQ
is a pointer to a list of addresses of MVS-format ECBs occurs in any of the following situations:
representing events. Both the ECBLIST and the ECBs
An ECB is not valid, for example the ECB is not
can be above the 16MB line, that is they can be 31-bit
fullword aligned (RESP2=1).
addresses. Each ECB must be fullword aligned. Null
(X'00000000') ECB addresses are ignored. An ECB is already being waited on (RESP2=2).

| NAME(name) NUMEVENTS is not a positive number (RESP2=3).

| specifies the symbolic name, 1–8 alphanumeric PURGEABILITY is specified with an incorrect CVDA
| characters, that is returned in SUSPENDVALUE or (RESP2=4).
| HVALUE, when a task issues WAIT EXTERNAL and is
No valid ECBs have been found in the list, because
| the subject of an INQ TASK command or a CEMT INQ
either the ECBLIST address is not valid or all the
| TASK.
ECB addresses are not valid (RESP2=5).
NUMEVENTS(data-value)
Default action: terminate the task abnormally.
is the number of such events, corresponding to the
number of addresses in the ECBLIST. The field is
fullword binary. When NUMEVENTS is specified as 1,
ECBLIST must still be an address that points to a list
containing just one ECB address.

PURGEABILITY(cvda)
determines the outcome of:

An attempt to perform a deadlock time-out

A SET TASK PURGE|FORCEPURGE command
A CEMT SET TASK PURGE|FORCEPURGE.

on the issuing task while it is waiting. The values

passed to CICS are PURGEABLE (the default value), or
NOTPURGEABLE. The outcome is:

Function PURGEABLE NOTPURGEABLE

DTIMOUT expired Abend AEXY No effect
CEMT SET TASK PURGE Abend AEXY No effect
EXEC CICS SET TASK
PURGE
CEMT SET TASK Abend AEXY Abend AEXY
FORCEPURGE
EXEC CICS SET TASK
FORCEPURGE

See the CICS/ESA Recovery and Restart Guide for

information about DTIMOUT and SET TASK
PURGE|FORCEPURGE.

Chapter 1. Commands 323

WAIT JOURNALNUM

Function
Synchronize with journal output.

Command syntax

──WAIT JOURNALNUM(data-value)──┬───────────────────┬──┬─────────┬──"
└─REQID(data-value)─┘ └─STARTIO─┘
Conditions:
# INVREQ, IOERR, JIDERR, NOTOPEN

WAIT JOURNALNUM synchronizes the task with the output STARTIO

of one or more journal records that have been created but specifies that output of the journal record is to be
whose output has been deferred; that is, with asynchronous initiated immediately.
journal output requests.

The journal records in the journal buffer area may already be WAIT JOURNALNUM conditions
written out to auxiliary storage, or the journal record output # INVREQ
operation may be in progress. If the output operation has # occurs if a WAIT JOURNALNUM command is issued
already been completed, control returns immediately to the # before any WRITE JOURNALNUM command has been
requesting task; if not, the requesting task waits until the # issued in the same task.
operation has been completed. If STARTIO is specified,
output is initiated immediately. # Default action: terminate the task abnormally.

IOERR
If the requesting program has made a succession of
occurs if the physical output of a journal record was not
successful asynchronous output requests to the same
accomplished because of an irrecoverable I/O error.
journal, it is necessary to synchronize on only the last of
these requests to ensure that all of the journal records have Default action: terminate the task abnormally.
reached auxiliary storage. This may be done either by
JIDERR
issuing a stand-alone WAIT JOURNALNUM command, or by
occurs if the specified journal identifier does not exist in
making the last output command itself synchronous (by
the journal control table (JCT).
specifying the WAIT option in the WRITE JOURNALNUM
command). Default action: terminate the task abnormally.

The following example shows how to request synchronization NOTOPEN

with the output of a journal record: occurs if the WAIT JOURNALNUM command cannot be
satisfied because the specified journal is not open.
EXEC CICS WAIT JOURNALNUM(4)
REQID(ENTRYID) Default action: terminate the task abnormally.

WAIT JOURNALNUM options

JOURNALNUM(data-value)
specifies a halfword numeric value in the range 1–99 to
be taken as the journal identifier. The value 1 specifies
that the system log is the journal for this operation.

REQID(data-value)
specifies a fullword binary variable set to a number that
refers to the journal record that has been created but
possibly not yet written out.
If REQID is not specified, the task is synchronized with
the output of the last record created for the journal
specified by JOURNALNUM.

324 CICS/ESA Application Programming Reference

WAIT SIGNAL

Function
Suspend task on a logical unit.

Command syntax

──WAIT SIGNAL──"
Conditions:
# NOTALLOC, SIGNAL, TERMERR

WAIT SIGNAL, for a principal facility only, suspends a task

until a SIGNAL condition occurs. Some logical units can
interrupt the normal flow of data to the application program
by a SIGNAL data-flow control command to CICS, signaling
an attention, that in turn causes the SIGNAL condition to
occur.

The HANDLE CONDITION SIGNAL command causes a

branch to a user routine when an attention is received.

The logical units for which you can code a WAIT SIGNAL
command are:
LUTYPE4
LUTYPE6.1
3600 (3601)
3767 interactive
3770 batch
3790 full-function.

WAIT SIGNAL conditions

# NOTALLOC
# occurs if the facility specified in the command is not
# owned by the application.
# Default action: terminate the task abnormally.

SIGNAL
occurs when the data-flow control command has been
received from the principal facility.
EIBSIG is always set when an inbound signal is
received.
Default action: ignore the condition.

TERMERR
occurs for a terminal-related error.
A CANCEL TASK request by a user node error program
(NEP) may cause this condition if the task has an
outstanding terminal control request active when the
node abnormal condition program (CSNE) handles the
session error.
Default action: terminate the task abnormally with abend
code ATNI.

Chapter 1. Commands 325

WAIT TERMINAL

Function
Ensure terminal operation has completed on an LUTYPE6.1 logical unit.

Command syntax

──WAIT TERMINAL──┬───────────────┬──"
├─CONVID(name)──┤
└─SESSION(name)─┘
Conditions:
INVREQ, NOTALLOC, SIGNAL

WAIT TERMINAL ensures that terminal operation has

completed.

WAIT TERMINAL options

CONVID(name)
identifies the conversation to which the command
relates. The 4-character name identifies either the token
returned by a previously executed ALLOCATE command
in EIBRSRCE in the EIB, or the token representing the
principal session (returned by a previously executed
ASSIGN command).

SESSION(name)
specifies the symbolic identifier (1–4 characters) of a
session TCTTE. This option specifies the alternate
facility to be used. If both this option and CONVID are
omitted, the principal facility for the task is used.

WAIT TERMINAL conditions

NOTALLOC
occurs if the facility specified in the command is not
owned by the application.
Default action: terminate the task abnormally.

SIGNAL
occurs when an inbound SIGNAL data-flow control
command is received from a logical unit or session.
EIBSIG is always set when an inbound signal is
received.
Default action: ignore the condition.

326 CICS/ESA Application Programming Reference

WAITCICS

Function
Synchronize events.

Command syntax

┌─PURGEABLE──────────┐
──WAITCICS──ECBLIST(ptr-value)──NUMEVENTS(data-value)──┼────────────────────┼──┬────────────┬──"
| ├─PURGEABILITY(cvda)─┤ └─NAME(name)─┘
└─NOTPURGEABLE───────┘
Conditions:
INVREQ

| Note for dynamic transaction routing

WAITCICS waits for events that post MVS-format ECBs. PTR_ECB_ADDR_LIST

The command causes the issuing task to be suspended until ┌────────────────┐
│A(ECB_ADDR_LIST)│
one of the ECBs has been posted, that is until one of the └──────┬─────────┘
events has occurred. The task can wait on one or more │
ECBs. If it waits on more than one, it is dispatchable as │ ECB_ADDR_LIST ┌──────────┐
soon as one of the ECBs is posted. You must ensure that └───────────────────┐ │ │ ECB1 │
each ECB is cleared, set to binary zeros, no later than the │ A(ECB1) ├───┘ └────────┘
earliest time it could be posted. CICS cannot do this for you. ├───────────┤
│ A(ECB2) ├──────────────┐
If you wait on an ECB that has been previously posted and ├───────────┤ │ ECB2 │
not subsequently cleared, your task is not suspended and │ A(ECB3) ├───┐ └────────┘
continues to run as though the WAITCICS had not been └───────────┘ │
issued. └──────────┐
│ ECB3 │
CICS includes the addresses of all ECBs passed by └────────┘
WAITCICS commands of current tasks in the ECBLIST DCL
passed by CICS to the MVS WAIT facility when it runs out of | ECB1 FIXED BIN(31), /_ actual ecb _/
work. Such ECBs can be posted using the MVS POST | ECB2 FIXED BIN(31), /_ actual ecb _/
facility or by hand posting. Hand posting could, for example, | ECB3 FIXED BIN(31); /_ actual ecb _/
be done by moving an appropriate value into the ECB. If | DCL /_ list of ecb addresses _/
hand posting is definitely not going to be used, it is | 1 ECB_ADDR_LIST,
preferable to use WAIT EXTERNAL. | 2 ECB_ADDR(3) PTR;
| DCL /_ ptr to each addr list _/
A given ECB may not be waited on by more than one task at | PTR_ECB_ADDR_LIST PTR;
ECB_ADDR(1) = ADDR(ECB1);
the same time. If this rule is not followed and the ECBLIST
ECB_ADDR(2) = ADDR(ECB2);
passed by CICS on the MVS WAIT contains duplicate ECB
ECB_ADDR(3) = ADDR(ECB3);
addresses, MVS abends CICS. /_ set up pointer _/
PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR_LIST);
Figure 6 shows how to use the ECBLIST parameter to point
/_ PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR(1));
to a list of ECB addresses that in turn point to individual (alternative) _/
ECBs. Note that the ECBLIST variable is a pointer pointing EXEC CICS WAITCICS
to the first address of the list. ECBLIST(PTR_ECB_ADDR_LIST)
NUMEVENTS(3)
PURGEABLE
Figure 6. ECBLIST option, EXEC CICS WAITCICS

Chapter 1. Commands 327

WAITCICS

WAITCICS options WAITCICS condition

ECBLIST(ptr-value) INVREQ
is a pointer to a list of addresses of MVS-format ECBs occurs in any of the following situations:
representing events. Both the ECBLIST and the ECBs
An ECB is not valid, for example the ECB is not
can be above the 16MB line, that is they can be 31-bit
fullword aligned, (RESP2=1).
addresses. Each ECB must be fullword aligned. Null
(X'00000000' and X'FF000000') ECB addresses are NUMEVENTS is not a positive number (RESP2=3).
ignored.
PURGEABILITY is specified with an incorrect CVDA
| NAME(name) (RESP2=4).
| specifies the symbolic name, 1–8 alphanumeric No valid ECBs have been found in the list, because
| characters, as the reason for the wait. The value you either the ECBLIST address is not valid, or all the
| specify is returned in the SUSPENDVALUE or HVALUE ECB addresses are not valid (RESP2=5).
| option respectively of the INQ TASK or CEMT INQ
| TASK commands.
| Default action: terminate the task abnormally.
NUMEVENTS(data-value)
is the number of such events, corresponding to the
number of addresses in the ECBLIST. The field is
fullword binary. When NUMEVENTS is specified as
one, ECBLIST must still be an address that points to a
list containing just one ECB address.

PURGEABILITY(cvda)
causes the issuing task to be suspended until one of the
ECBs has been posted; that is, until one of the events
has occurred. The values passed to CICS are
PURGEABLE (the default value), or NOTPURGEABLE.
The field is fullword binary. If while this task is waiting
another function attempts to purge it, the result is as
follows:

Function PURGEABLE NOTPURGEABLE

DTIMOUT expired Abend AEXY No effect
CEMT SET TASK PURGE Abend AEXY No effect
EXEC CICS SET TASK
PURGE
CEMT SET TASK Abend AEXY Abend AEXY
FORCEPURGE
EXEC CICS SET TASK
FORCEPURGE

See the CICS/ESA Recovery and Restart Guide for

information about DTIMOUT and SET TASK
PURGE|FORCEPURGE.

328 CICS/ESA Application Programming Reference

WRITE

Function
Write a record.

Command syntax

──WRITE──FILE(filename)──┬────────────┬──FROM(data-area)──┬────────────────────┬──RIDFLD(data-area)──────
└─MASSINSERT─┘ └─LENGTH(data-value)─┘
──┬───────────────────────┬──┬───────────────────┬──┬─────┬──"
└─KEYLENGTH(data-value)─┘ └─SYSID(systemname)─┘ ├─RBA─┤
└─RRN─┘
Conditions:
| DISABLED, DUPREC, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOADING,
| NOSPACE, NOTAUTH, NOTOPEN, SUPPRESSED, SYSIDERR

WRITE writes a new record to a file on a local or a remote WRITE options

system. For example:
FILE(filename)
EXEC CICS WRITE
specifies the of the file to be accessed.
FROM(RECORD)
LENGTH(DATLEN) If SYSID is specified, the data set to which this file refers
FILE('MASTER') is assumed to be on a remote system irrespective of
RIDFLD(KEYFLD) whether the name is defined in the FCT. Otherwise, the
FCT entry is used to find out whether the data set is on
When this command is used to write a record to a a local or a remote system.
CICS-maintained data table, the update is made to both the
source VSAM KSDS and the in-memory data table, unless FROM(data-area)
the XDTAD user exit rejects the record from the table. The specifies the record that is to be written to the data set
details of the command for a CICS-maintained table are the referred to by this file.
same as for a VSAM KSDS. | For user-maintained data tables, there is no need to
| include the RIDFLD option if the UMT has not been
| When this command is used to write a record to a
| pre-loaded with a VSAM file.
| user-maintained data table, the update is made to the
| in-memory data table. KEYLENGTH(data-value)
specifies the length (halfword binary) of the key that has
For a VSAM ESDS, the record is always added at the end of been specified in the RIDFLD option, except when RBA
the data set. VSAM does not use the identification field or RRN is specified, in which case KEYLENGTH is not
specified in RIDFLD when calculating the RBA of the new valid. You must code KEYLENGTH if you are also using
record, but the new RBA is returned to the application in the SYSID (unless you are also using RBA or RRN). If the
record identification field specified in the RIDFLD option. length specified is different from the length defined for
the data set, the INVREQ condition occurs.
For a VSAM KSDS, the record is added in the location
specified by the associated key; this location may be LENGTH(data-value)
anywhere in the data set. For VSAM data sets, the key in specifies the length, as a halfword binary value, of the
the record and the key in the RIDFLD identification field must record to be written.
be the same.
You must specify this option if you are using SYSID.
Records for ESDS and KSDS can be either fixed-length or You must also specify the option for a file with
variable-length. Those for a relative record data set must be | variable-length records (including user-maintained data
fixed-length. MASSINSERT operations must proceed with | tables). It need not be specified for fixed-length records,
ascending keys, and must be terminated by an UNLOCK but its inclusion is recommended because it causes a
before any other request to the same data set. check to be made that the record being written is not
longer than that defined for the data set.

Chapter 1. Commands 329

WRITE

MASSINSERT (VSAM) DUPREC

specifies that the WRITE command is part of a occurs if an attempt is made to add a record to a data
mass-insert operation, that is, a series of WRITEs each set, by referring to a file, or a path over a file (with the
specifying MASSINSERT. UNIQUEKEY attribute), in which the same key already
exists (RESP2=150).
| You cannot use MASSINSERT for user-maintained data
| tables. Default action: terminate the task abnormally.

# RBA (VSAM ESDS base) FILENOTFOUND

# specifies that the record identification field specified in occurs if a file name referred to in the FILE option
# the RIDFLD option contains a relative byte address. cannot be found in the FCT (RESP2=1).
# Use this option only when writing to an ESDS base.
Default action: terminate the task abnormally.
| You cannot use RBA for user-maintained data tables.
ILLOGIC (VSAM)
RIDFLD(data-area) occurs if a VSAM error occurs that does not fall within
# specifies the record identification field. When combined one of the other CICS response categories
# with RBA or RRN this is a 4-character field. The (RESP2=110).
contents can be a key, a relative byte address, or
# (See EIBRCODE in the EXEC interface block; refer to
relative record number (for VSAM data sets), or a block
Appendix A, “EXEC interface block” on page 343 for
reference, a physical key, and a deblocking argument
details.)
(for BDAM data sets). For a relative byte address or a
relative record number, the format of this field must be Default action: terminate the task abnormally.
fullword binary. If RBA is specified, RIDFLD contains
INVREQ
the relative byte address (greater than or equal to zero)
occurs in any of the following situations:
of the record that was written. If RRN is specified,
RIDFLD contains the relative record number (greater Add operations are not allowed according to the file
than or equal to 1) of the record that was written. entry specification in the FCT (RESP2=20).
When adding records to a keyed data set, the field must When writing records containing embedded keys,
contain the complete key. the key in the record area (FROM option) and the
key in RIDFLD do not match (RESP2=23).
RRN (VSAM RRDS)
specifies that the record identification field specified in The KEYLENGTH option is specified, and the
the RIDFLD option contains a relative record number. specified length does not equal the length defined
for the data set that this file refers to (RESP2=26).
SYSID(systemname)
A WRITE with the MASSINSERT option is issued
specifies the name of the system to which the request is
against a BDAM file (RESP2=38).
directed.
A BDAM key conversion error occurred
If you specify SYSID, and omit both RBA and RRN, you
(RESP2=40).
must also specify LENGTH and KEYLENGTH; they
cannot be found in the FCT. | The WRITE command does not conform to the
| format of WRITE for a user-maintained data table
LENGTH must either be specified explicitly or must be
| (RESP2=44).
capable of being defaulted from the FROM option using
the length attribute reference in assembler language, or Default action: terminate the task abnormally.
STG and CSTG in PL/I. LENGTH must be specified
explicitly in OS/VS COBOL or C. IOERR
occurs in any of the following situations:

WRITE conditions There is an I/O error during the file control operation
(RESP2=120). An I/O error is any unusual event
Note: RESP2 values are not set for files that are on remote
that is not covered by a CICS condition. (Further
systems.
information is available in the EXEC interface block;
DISABLED refer to Appendix A, “EXEC interface block” on
occurs if a file is disabled (RESP2=50). A file may be page 343 for details.)
disabled because: For VSAM files, IOERR normally indicates a
It was initially defined as disabled and has not since hardware error.
been enabled. You are trying to write to a BDAM track address that
It has been disabled by a SET FILE or a CEMT is not defined for the data set (RESP2=120).
SET FILE command. Default action: terminate the task abnormally.
Default action: terminate the task abnormally.

330 CICS/ESA Application Programming Reference

WRITE

ISCINVREQ This condition does not occur if the request is made to

occurs when the remote system indicates a failure that either a CLOSED, ENABLED file or a CLOSED,
does not correspond to a known condition (RESP2=70). DISABLED file. In the first case, the file is opened as
part of executing the request. In the second case, the
Default action: terminate the task abnormally.
DISABLED condition occurs.
LENGERR
| SUPPRESSED
occurs in any of the following situations:
| occurs if a user exit program that is invoked at the
The length specified for the write operation exceeds | XDTAD exit point decides not to add the record to the
the maximum record size; the record is truncated | user-maintained data table (RESP2=105).
(RESP2=12).
| Default action: terminate the task abnormally.
An incorrect length is specified for a write operation
SYSIDERR
involving fixed-length records (RESP2=14).
| occurs when the SYSID option specifies a name that is
LENGTH is omitted for a WRITE to a file with | neither the local system nor a remote system (made
variable-length records or to a BDAM file with | known to CICS by defining a CONNECTION).
undefined-format records. (RESP2=10). SYSIDERR also occurs when the link to the remote
system is closed (RESP2=130).
| LOADING
| occurs if a WRITE is issued to a user-maintained data Default action: terminate the task abnormally.
| table that is currently being loaded (RESP2=104). A
| user-maintained data table cannot be modified during
| loading.
| Default action: terminate the task abnormally.

NOSPACE
| occurs in the following situations:

| No space is available on the direct access device

| for adding records to a data set (RESP2=100).
| The maximum number of table entries specified for
| the user-maintained table has already been reached
| (RESP2=102).
| CICS is unable to get sufficient storage in the CICS
| address space to create an in-memory table entry
| for the record being written (RESP2=103).

Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
FILE(filename) (RESP2=101).
Default action: terminate the task abnormally.

NOTOPEN
occurs in any of the following situations (RESP2=60):

The requested file is CLOSED and UNENABLED.

The CLOSED, UNENABLED state is reached after a
CLOSE request has been received against an
OPEN ENABLED file and the file is no longer in
use. This state can also be specified as the initial
state by means of the FILSTAT parameter of the file
control table TYPE=FILE, or by defining a file using
the RDO options STATUS=UNENABLED and
OPENTIME=FIRSTREF.
The requested file is OPEN and in use by other
transactions, but a CLOSE request against the file
has been received.

Chapter 1. Commands 331

WRITE JOURNALNUM

Function
Create a journal record.

Command syntax

──WRITE JOURNALNUM(data-value)──JTYPEID(data-value)──FROM(data-area)──┬────────────────────┬─────────────
└─LENGTH(data-value)─┘
──┬──────────────────┬──┬─────────────────────────────────────────────┬──┬─────────┬──┬──────┬────────────
└─REQID(data-area)─┘ └─PREFIX(data-value)──┬─────────────────────┬─┘ └─STARTIO─┘ └─WAIT─┘
└─PFXLENG(data-value)─┘
──┬───────────┬──"
└─NOSUSPEND─┘
Conditions:
IOERR, JIDERR, LENGERR, NOJBUFSP, NOTAUTH, NOTOPEN

WRITE JOURNALNUM creates a journal record. The WRITE JOURNALNUM options

request can be for synchronous or asynchronous output;
definitions of these terms, and detailed information regarding FROM(data-area)
the synchronization of journal output, are contained in the specifies the user data to be built into the journal record.
CICS/ESA Application Programming Guide. JOURNALNUM(data-value)
specifies a halfword numeric value in the range 1
The following example shows how to request synchronous
through 99 to be taken as the journal identifier.
journal output and wait for the output operation to be
JOURNALNUM(1) specifies the system log.
completed:
EXEC CICS WRITE JTYPEID(data-value)
JOURNALNUM(2) specifies a 2-character identifier to be placed in the
JTYPEID('XX') journal record to identify its origin.
FROM(KEYDATA)
LENGTH(8) LENGTH(data-value)
PREFIX(PROGNAME) specifies the length (halfword binary value) in bytes of
PFXLENG(6) the user data to be built into the journal record. The
WAIT | minimum value is 0 and the maximum value is (buffer
| size−76) minus PFXLENG.
In this example, STARTIO is not specified, so the task waits
until the journal buffer is full or until output is initiated by a NOSUSPEND
STARTIO request in another task. CICS limits the wait to specifies that an application program is not to be
one second. suspended for the NOJBUFSP condition.

PFXLENG(data-value)
The following example shows how to request deferred
specifies the length (halfword binary value) in bytes of
(asynchronous) journal output:
the user prefix data to be included in the journal record.
EXEC CICS WRITE The minimum value is 0 and the maximum value is
JOURNALNUM(1) (buffer size−72) minus LENGTH.
JTYPEID('SD')
FROM(COMDATA) PREFIX(data-value)
LENGTH(1O) specifies the user prefix data to be included in the
REQID(ENTRYID) journal record. A data area must be provided in COBOL
programs.

REQID(data-area)
specifies a data area that identifies the journal record.
The data area is a fullword binary variable. CICS sets
the variable to a number that depends upon the position
in the data set of the record being created. REQID
applies to asynchronous output (WAIT option not
specified).

332 CICS/ESA Application Programming Reference

WRITE JOURNALNUM

STARTIO
specifies that output of the journal record is to be
initiated immediately. If WAIT is specified for a journal
with a low utilization, STARTIO should be specified also
to prevent the requesting task waiting for the journal
buffer to be filled. Very high utilization ensures that the
buffer is cleared quickly, so that STARTIO is
unnecessary.

WAIT
specifies that synchronous journal output is required.
The requesting task waits until the record has been
written.

WRITE JOURNALNUM conditions

IOERR
occurs if the physical output of a journal record was not
accomplished because of an irrecoverable I/O error.
Default action: terminate the task abnormally.

JIDERR
occurs if the specified journal identifier does not exist in
the journal control table (JCT).
Default action: terminate the task abnormally.

LENGERR
occurs if the computed length for the journal record
exceeds the total buffer space allocated for the journal,
as specified in the JCT entry for the journal, or if the
length specified for the prefix or for the data is negative.
Default action: terminate the task abnormally.

NOJBUFSP
occurs if the journal buffers are logically full (that is, the
current buffer is full, and I/O is in progress on the
alternate buffer) or the remaining space in the current
buffer is insufficient for this journal record.
Default action: suspend task activity until the journal
request can be satisfied. CICS ensures that both buffers
are written out to auxiliary storage, thus freeing them for
new records. (The default can be overridden by the
NOSUSPEND option.)

NOTAUTH
occurs when a resource security check has failed on
JOURNALNUM(data-value).
Default action: terminate the task abnormally.

NOTOPEN
occurs if the journal command cannot be satisfied
because the specified journal is not open.
Default action: terminate the task abnormally.

Chapter 1. Commands 333

WRITE OPERATOR

Function
Write a message on the system console.

Command syntax

──WRITE OPERATOR──TEXT(data-value)──┬────────────────────────┬───────────────────────────────────────────
└─TEXTLENGTH(data-value)─┘
──┬───────────────────────────────────────────────┬───────────────────────────────────────────────────────
└─ROUTECODES(data-value)──NUMROUTES(data-value)─┘
┌─EVENTUAL─────────────────────────────────────────────────────────────────────────────────────┐
──┼──────────────────────────────────────────────────────────────────────────────────────────────┼──"
| ├─ACTION(cvda)─────────────────────────────────────────────────────────────────────────────────┤
├─CRITICAL─────────────────────────────────────────────────────────────────────────────────────┤
├─IMMEDIATE────────────────────────────────────────────────────────────────────────────────────┤
└─REPLY(data-area)──MAXLENGTH(data-value)──┬────────────────────────┬──┬─────────────────────┬─┘
└─REPLYLENGTH(data-area)─┘ └─TIMEOUT(data-value)─┘
Conditions:
EXPIRED, INVREQ, LENGERR

WRITE OPERATOR enables an application to write a programmer for information about how this command affects
message to one or more system consoles and, if necessary, the appearance of the console screen to the operator.
wait for a reply. The command can specify route codes.
This is of particular use to application packages that need to
issue their own operator messages.
WRITE OPERATOR options
Note: CICS/VSE, unlike CICS/ESA, does not support the
As a result of a change in the way CICS handles messages options ACTION, ROUTECODES, and NUMROUTES. If a
sent to the console, text lengths of greater than 113 program containing any of these three options is translated
characters are split into two lines. on VSE, warning message DFH7117 is produced and the
option ignored.
None of the variables below can be defined as PL/I variable
character strings. | ACTION(cvda)
specifies an action code to be associated with this
Note: If ACTION (or one of the equivalent CVDA values
message. The CVDA values are:
below) is specified, the message is retained by MVS until the
console operator explicitly deletes it or CICS terminates. CRITICAL specifies that the message requires
eventual action by the operator and
The action code is identical with the MVS descriptor code to has enough critical importance to
be associated with the message. Only one of the descriptor remain on the console screen. The
codes 2, 3, or 11 may be specified for this parameter. message remains on the screen until
it is deleted by the operator.
If ACTION is not specified, no descriptor code is associated
with the message. The descriptor codes have the following EVENTUAL specifies that the operator should
meanings: take action when there is time. The
message is rolled off when other
2 Immediate action
messages fill up the screen, but is
3 Eventual action
still retained by the operating system
11 Critical eventual action.
until the operator explicitly deletes it.
The CRITICAL option is equivalent to a specification of IMMEDIATE specifies that the operator should
ACTION(11). The EVENTUAL option is equivalent to a take action immediately. The
specification of ACTION(3). The IMMEDIATE option is message remains on the console
equivalent to a specification of ACTION(2). screen until it is deleted by the
operator.
Messages retained by MVS can be handled by the console
operator in a variety of ways (see the MVS/ESA Operations:
System Commands manual). Refer to your system

334 CICS/ESA Application Programming Reference

WRITE OPERATOR

MAXLENGTH(data-value) control to this transaction. This must be in the range

is a fullword binary field that contains the length of the 0–86 400 (24 hours). The system default value is
reply area (in the range 1–119 bytes). You must specify specified in the OPERTIM system initialization table.
MAXLENGTH if you specify REPLY. You can only specify TIMEOUT if you have also
specified REPLY.
NUMROUTES(data-value)
is a fullword binary field that defines the number of
routing codes. WRITE OPERATOR conditions
REPLY(data-area) EXPIRED
provides a data area for receiving the operator’s reply. If TIMEOUT has occurred before the operator’s reply was
you specify this option, your application pauses until received (RESP2=7).
either a reply is received or the TIMEOUT period | Default action: terminate the task abnormally.
expires.
INVREQ
REPLYLENGTH(data-area) occurs in any of the following situations:
specifies the actual length (fullword binary value) of the
operator’s reply. The TEXTLENGTH value is not valid (RESP2=1)
The NUMROUTES value is not valid (RESP2=2)
ROUTECODES(data-value) The ROUTECODE value is not valid (RESP2=3)
is a variable-length field. Each code is one byte and The MAXLENGTH value is not valid (RESP2=4)
contains a binary number in the range 1–28. The The TIMEOUT value is not valid (RESP2=5)
| default is a single code, set to 2. In COBOL programs The ACTION value is not valid (RESP2=6).
| only, you must use a data-area that contains the 1-byte
| values rather than a data-value. | Default action: terminate the task abnormally.

TEXT(data-value) LENGERR
is a data value containing the text to be sent. occurs when the reply was longer than MAXLENGTH,
and has been truncated (RESP2=8).
# For COBOL programs to be compiled with a Language
# Environment-conforming compiler, and translated with | Default action: terminate the task abnormally.
# the COBOL3 translator option, there is a restriction in
# the length of data-value, which cannot exceed 160
# bytes. If you are using an earlier compiler, such as VS
# COBOL II, that does not support the COBOL3 translator
# option, you must use a data-area that contains the text
# to be sent to the operator, and not a data-value.

TEXTLENGTH(data-value)
specifies the length (fullword binary value) of the text.
| If the REPLY option is specified, the length is in the
| range 0–121 bytes.
If the REPLY option is not specified, the length is in the
range 0–690 bytes.
If the length of the text is greater than 113, CICS
formats the message in a multiline write to operator
(WTO); each line has 69 bytes with a maximum of ten
lines.
# Apar 85038
# Documentation for Apar 85038 added 11/07/96

# The output is edited in such a way that each line is

# broken, if possible, at a space character. The next line
# starts with a non-space character. If there is not room to
# reformat the data in this way within the overall limit of
# 690 bytes of ten lines of 69 bytes, the output is not
# reformatted.

TIMEOUT(data-value)
is a fullword binary field that contains the maximum time
(in seconds) that CICS waits for a reply before returning

Chapter 1. Commands 335

WRITEQ TD

Function
Write data to transient data queue.

Command syntax

──WRITEQ TD──QUEUE(name)──FROM(data-area)──┬────────────────────┬──┬───────────────────┬──"
└─LENGTH(data-value)─┘ └─SYSID(systemname)─┘
Conditions:
DISABLED, INVREQ, IOERR, ISCINVREQ, LENGERR, NOSPACE, NOTAUTH, NOTOPEN, QIDERR, SYSIDERR

WRITEQ TD writes transient data to a predefined symbolic WRITEQ TD conditions

destination.
DISABLED
The following example shows how to write data to a occurs when the queue has been disabled.
predefined symbolic destination; in this case, the control Default action: terminate the task abnormally.
system message log (CSML):
EXEC CICS WRITEQ TD INVREQ
QUEUE('CSML') occurs if WRITEQ names an extrapartition queue that
FROM(MESSAGE) has been opened for input.
LENGTH(LENG) Note: This condition cannot be raised for intrapartition
queues.
WRITEQ TD options Default action: terminate the task abnormally.
FROM(data-area) IOERR
specifies the data that is to be written to the transient occurs when an input/output error occurs and the data
data queue. record in error is skipped.
LENGTH(data-value) Default action: terminate the task abnormally.
specifies the length (halfword binary value) of the data to
ISCINVREQ
be written.
occurs when the remote system indicates a failure that
QUEUE(name) does not correspond to a known condition.
specifies the symbolic name (1–4 alphanumeric Default action: terminate the task abnormally.
characters) of the queue to be written to. The name
must have been defined in the DCT by the system LENGERR
programmer. occurs in any of the following situations:

SYSID(systemname) — remote systems only WRITEQ names an extrapartition queue and does
specifies the name (1–4 characters) of the system to not specify a length consistent with the RECFORM
which the request is directed. and RECSIZE options specified in the destination
control table TYPE=SDSCI that defined the queue.
If SYSID is specified, the data set is assumed to be on a
The check is made after the XTDOUT exit has been
remote system irrespective of whether or not the name
invoked; this exit may change the length of the data
is defined as remote in the DCT. Otherwise the entry in
to be passed to the access method.
the DCT is used to find out whether the data set is on a
local or a remote system. WRITEQ names an intrapartition queue and does
not specify a length consistent with the control
interval defined for the intrapartition data set. Again,
the check is made after the XTDOUT exit has been
invoked.

Default action: terminate the task abnormally.

336 CICS/ESA Application Programming Reference

WRITEQ TD

NOSPACE
occurs if no more space exists on the intrapartition or
extrapartition queue.
# Apar PQ07370
# The following paragraph was added by APAR PQ
# 07370 6/7/1998

# It also occurs for an intrapartition queue that has been

# defined with a size greater than 2 gigabytes, and the
# RBA (relative byte address) of the entry being written
# exceeds 2 gigabytes. When this happens, no more data
should be written to the queue because it may be lost.
Default action: terminate the task abnormally.

NOTAUTH
occurs when a resource security check has failed on
QUEUE(name).
Default action: terminate the task abnormally.

NOTOPEN
occurs if the destination is closed.
Note: This condition cannot be raised for intrapartition
queues.
Default action: terminate the task abnormally.

QIDERR
occurs if the symbolic destination to be used with a
transient data control command cannot be found.
Default action: terminate the task abnormally.

Chapter 1. Commands 337

WRITEQ TS

Function
Write data to a temporary storage queue.

Command syntax

──WRITEQ TS──QUEUE(name)──FROM(data-area)──┬────────────────────┬──┬──────────────────────────────┬──────
└─LENGTH(data-value)─┘ ├─NUMITEMS(data-area)──────────┤
└─ITEM(data-area)──┬─────────┬─┘
└─REWRITE─┘
┌─AUXILIARY─┐
──┬───────────────────┬──┼───────────┼──┬───────────┬──"
└─SYSID(systemname)─┘ └─MAIN──────┘ └─NOSUSPEND─┘
Conditions:
INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOSPACE, NOTAUTH, QIDERR, SYSIDERR

| Note for dynamic transaction routing

WRITEQ TS stores temporary data (records) in a temporary # Apar 66387

storage queue in main or auxiliary storage.
# Documentation for Apar 66387 added 13 Feb 1995
If a queue has been defined as recoverable, the program # (TUCKER)
must not issue a WRITEQ TS if a DELETEQ TS has
previously been issued within the same logical unit of work. # ITEM can be both an input and output field to CICS. As
In other words, following a DELETEQ TS, no WRITEQ TS # such, programmers should ensure that the ITEM field is
can be issued until after a syncpoint has occurred. # not defined within protected storage when issuing a
# WRITEQ command. If the ITEM value were a literal
If there is insufficient space available in the temporary # (say), command checking (CMDPROT=YES) would
storage data set to satisfy the WRITEQ TS request, the task # result in an AEYD abend occurring.
is suspended until space does become available. (Space
Note: In earlier releases, ITEM on a WRITEQ TS
may be released by other tasks in the system.) However, if
without REWRITE would perform a similar function to
space is not available in the temporary storage data set, and
NUMITEMS. This function is retained for compatibility.
the NOSUSPEND option has been specified, the NOSPACE
condition is raised. LENGTH(data-value)
specifies the length, as a halfword binary value, of the
data to be written.
WRITEQ TS options
| You must specify this option if you are using SYSID.
AUXILIARY
specifies that the temporary storage queue is on a direct # The maximum length is 32763. For a description of a
access storage device in auxiliary storage. This option safe upper limit, see “LENGTH options” on page 5.
| is ignored for an existing queue. MAIN
This is the default value for the first write. specifies that the temporary storage queue is in main
storage. This option is ignored for an existing queue.
FROM(data-area)
specifies the data to be written to temporary storage. If you use the MAIN option to write data to a temporary
storage queue on a remote system, the data is stored in
ITEM(data-area) main storage if the remote system is accessed by the
specifies, as a halfword binary value, the item number CICS multiregion operation (MRO) facility. If these
of the logical record to be replaced in the queue conditions are not met, the data is stored in auxiliary
(REWRITE option also specified). storage.

338 CICS/ESA Application Programming Reference

WRITEQ TS

| If the system is MRO and MAIN is specified, the queue ISCINVREQ

| is not recoverable and SYNCPOINT ROLLBACK does occurs when the remote system indicates a failure that
| not function. does not correspond to a known condition.

NOSUSPEND Default action: terminate the task abnormally.

specifies that the application program is not to be
| suspended if there is insufficient space in the temporary
| storage data set to satisfy the WRITEQ TS request.
| Instead, the NOSPACE condition is raised.
This does not apply to the MAIN queue.

NUMITEMS(data-area)
specifies a halfword binary field into which CICS stores a
number indicating how many items there are now in the
queue, after the WRITEQ TS command is executed.
If the record starts a new queue, the item number
assigned is 1; subsequent item numbers follow on
sequentially. NUMITEMS is not valid if REWRITE is
specified.

QUEUE(name)
specifies the symbolic name (1-8 characters) of the
queue to be written to. If the queue name appears in
the TST, and the entry is marked as remote, the request
is shipped to a remote system. The name must be
unique within the CICS system. Do not use X'FA'
| through X'FF', or **, or $$, or DF, as the first character
of the name; these characters are reserved for CICS
use. The name cannot consist solely of binary zeros.

REWRITE
specifies that the existing record in the queue is to be
overwritten with the data provided. If the REWRITE
option is specified, the ITEM option must also be
specified. If the specified queue does not exist, the
QIDERR condition occurs. If the correct item within an
existing queue cannot be found, the ITEMERR condition
occurs and the data is not stored.

SYSID(systemname) — remote systems only

specifies the name (1–4 characters) of the system to
which the request is directed.

WRITEQ TS conditions
INVREQ
occurs in any of the following situations:

A WRITEQ TS command specifies a queue name

that consists solely of binary zeros
A WRITEQ TS command specifies a queue that is
locked and awaiting ISC session recovery
The queue was created by CICS internal code

Default action: terminate the task abnormally.

IOERR
occurs when there is an irrecoverable input/output error.
Default action: terminate the task abnormally.

Chapter 1. Commands 339

WRITEQ TS

ITEMERR
occurs in any of the following situations:

| The item number specified in a WRITEQ TS

command with the REWRITE option, is not valid
(that is, it is outside the range of entry numbers
assigned for the queue).
The maximum number of items (32 767) is
exceeded.

Default action: terminate the task abnormally.

LENGERR
| occurs in any of the following situations:

| The length of the stored data is zero or negative.

# The length of the stored data is greater than 32763.
| A destructive overlay has occurred.

Default action: terminate the task abnormally.

NOSPACE
occurs when insufficient space is available in the
temporary storage data set to contain the data, and the
NOSUSPEND option is specified.
Default action: ignore the condition.

NOTAUTH
occurs when a resource security check has failed on
QUEUE(name).
Default action: terminate the task abnormally.

QIDERR
occurs when the queue specified by a WRITEQ TS
command with the REWRITE option cannot be found,
either in main or in auxiliary storage.
Default action: terminate the task abnormally.

340 CICS/ESA Application Programming Reference

XCTL

Function
Transfer program control.

Command syntax

──XCTL──PROGRAM(name)──┬─────────────────────────────────────────────┬───────────────────────────────────
└─COMMAREA(data-area)──┬────────────────────┬─┘
└─LENGTH(data-value)─┘
──┬──────────────────────────────────────────────────┬──"
└─INPUTMSG(data-area)──┬─────────────────────────┬─┘
└─INPUTMSGLEN(data-value)─┘
Conditions:
INVREQ, LENGERR, NOTAUTH, PGMIDERR

XCTL transfers control from one application program to | defined as a program to CICS, though if AUTOINSTALL
another at the same logical level. The program from which | is active a definition is autoinstalled.
control is transferred is released. If the program to which
control is transferred is not already in main storage, it is
loaded.
XCTL conditions
INVREQ
The following example shows how to request a transfer of occurs in the following circumstances:
control to an application program called PROG2:
EXEC CICS XCTL PROGRAM('PROG2') An XCTL command with the INPUTMSG option is
issued for a program that is not associated with a
terminal, or that is associated with an APPC logical
XCTL options unit, or an IRC session (RESP2=8).
COMMAREA(data-area) | EXEC XCTL is not allowed in a GLUE or TRUE
specifies a communication area to be made available to | (RESP2=29).
the invoked program. In this option a pointer to the data | The program manager domain has not yet been
area is passed. In COBOL, you must give this data area | initialized. This is probably due to a XCTL request
the name DFHCOMMAREA in the receiving program. | having been made in a first stage PLT (RESP2=30).
(See the section about passing data to other programs
in the CICS/ESA Application Programming Guide.) | An XCTL command with the INPUTMSG option is
| issued in a program invoked by DPL (RESP2=200).
INPUTMSG(data-area)
specifies data to be passed to the invoked program Default action: terminate the task abnormally.
when it first issues a RECEIVE command. If the | LENGERR
invoked program passes control to another program by a | occurs in the following conditions:
LINK command, a linked chain is created, as described
under the INPUTMSG option of the LINK command. | LENGTH is less than 0 or greater than 32763
The INPUTMSG data remains available until a RECEIVE | (RESP2=11).
command is issued or until control returns to CICS. | The COMMAREA address passed was zero, but
INPUTMSGLEN(data-value) | LENGTH was non-zero (RESP2=26).
specifies a halfword binary value that specifies the | INPUTMSGLEN was less than 0 or greater than
length of the data passed by INPUTMSG. | 32767 (RESP2=27).
LENGTH(data-value) | LENGTH or INPUTMSGLEN is greater than the
specifies the length (halfword binary data value) in bytes | length of the data area specified in the COMMAREA
of the communication area. For a description of a safe | or INPUTMSG options, and while that data was
upper limit, see “LENGTH options” on page 5. | being copied a destructive overlap occurred
| because of the incorrect length (RESP2=28).
PROGRAM(name)
specifies the identifier (1–8 alphanumeric characters) of | Default action: terminate the task abnormally.
the program to which control is to be passed
unconditionally. The specified name must have been

Chapter 1. Commands 341

XCTL

NOTAUTH PGMIDERR
occurs when a resource security check has failed on occurs in any of the following situations:
| PROGRAM(name) (RESP2=101).
| A program has no entry in the PPT and either
Default action: terminate the task abnormally. | program autoinstall was switched off, or the program
| autoinstall control program indicated that the
| program should not be autoinstalled (RESP2=1).
The program is disabled (RESP2=2).
| A program could not be loaded because
| – This was the first load of the program and the
| program load failed, usually because the load
| module could not be found.
| – This was a subsequent load of the program, but
| the first load failed.
| In order to reset the load status the load module
| must be in the DFHRPL concatenation, and a SET
| PROGRAM NEWCOPY will be required (RESP2=3).
The installed program definition is for a remote
program (RESP2=9).
| The program autoinstall control program failed either
| because the program autoinstall control program is
| incorrect, incorrectly defined, or as a result of an
| abend in the program autoinstall control program.
| Program autoinstall is disabled and message
| DFHPG0202 or DFHPG0203 written to the CSPL
| (RESP2=21).
| The model returned by the program autoinstall
| control program was not defined in the PPT table, or
| was not enabled (RESP2=22).
| The program autoinstall control program returned
| invalid data (RESP2=23).
| Define for the program failed due to autoinstall
| returning an invalid program name or definition
| (RESP2=24).

Default action: terminate the task abnormally.

342 CICS/ESA Application Programming Reference

EIBAID EIBEOC

Appendix A. EXEC interface block

This appendix contains a description of the EXEC interface COBOL: PIC X(1).
block (EIB). An application program can read all the fields in C: unsigned char eibcompl;
the EIB of the associated task by name, but must not directly PL/I: CHAR(1)
change the contents of any of them. ASM: CL1

EIBCONF
For each field, the contents and format (for each of the
indicates that a CONFIRM request has been received
application programming languages COBOL, C, PL/I, and
(X'FF') for an APPC conversation.
ASM) are given. All fields contain zeros in the absence of
meaningful information. Fields are listed in alphabetical COBOL: PIC X(1).
order. C: unsigned char eibconf;
PL/I: CHAR(1)
ASM: CL1
EIB fields EIBCPOSN
contains the cursor address (position) associated with
the last terminal control or basic mapping support (BMS)
EIBAID
input operation from a display device such as the 3270.
contains the attention identifier (AID) associated with the
last terminal control or basic mapping support (BMS) COBOL: PIC S9(4) COMP.
input operation from a display device such as the 3270. C: short int eibcposn;
PL/I: FIXED BIN(15)
COBOL: PIC X(1). ASM: H
C: unsigned char eibaid;
PL/I: CHAR(1) EIBDATE
ASM: CL1 contains the date the task is started; this field is updated
by the ASKTIME command. The date is in packed
EIBATT
decimal form (0CYYDDD+) where C shows the century
indicates that the RU contains attach header data
with values 0 for the 1900s and 1 for the 2000s. For
(X'FF').
example, the dates 31 December 1999 and 1 January
COBOL: PIC X(1). 2000 have EIBDATE values of 0099365 and 0100001
C: unsigned char eibatt; respectively.
PL/I: CHAR(1)
ASM: CL1 COBOL: PIC S9(7) COMP-3.
C: char eibdate [4];
EIBCALEN PL/I: FIXED DEC(7,O)
contains the length of the communication area that has ASM: PL4
been passed to the application program from the last
EIBDS
program, using the COMMAREA and LENGTH options.
contains the symbolic identifier of the last data set
If no communication area is passed, this field contains
referred to in a file control request.
zeros.
COBOL: PIC X(8).
COBOL: PIC S9(4) COMP.
C: char eibds [8];
C: short int eibcalen;
PL/I: CHAR(8)
PL/I: FIXED BIN(15)
ASM: CL8
ASM: H
EIBEOC
EIBCOMPL
indicates that an end-of-chain indicator appears in the
indicates, on a terminal control RECEIVE command,
RU just received (X'FF').
whether the data is complete (X'FF'). If the
NOTRUNCATE option has been used on the RECEIVE COBOL: PIC X(1).
command, CICS retains data in excess of the amount C: unsigned char eibeoc;
requested via the LENGTH or MAXLENGTH option. PL/I: CHAR(1)
EIBRECV is set indicating that further RECEIVE ASM: CL1
commands are required. EIBCOMPL is not set until the
last of the data has been retrieved.
EIBCOMPL is always set when a RECEIVE command
without the NOTRUNCATE option is executed.

EIBERR EIBFN

EIBERR O41A ISSUE ENDFILE

indicates that an error has been received (X'FF') on an O41C ISSUE PRINT
APPC conversation. O41E ISSUE SIGNAL
O42O ALLOCATE
COBOL: PIC X(1).
O422 FREE
C: unsigned char eiberr;
O424 POINT
PL/I: CHAR(1)
O426 BUILD ATTACH
ASM: CL1
O428 EXTRACT ATTACH
EIBERRCD O42A EXTRACT TCT
when EIBERR is set, contains the error code that has O42C WAIT CONVID
been received. The following values can be returned in O42E EXTRACT PROCESS
O43O ISSUE ABEND
the first two bytes of EIBERRCD:
O432 CONNECT PROCESS
X'0889' Conversation error detected O434 ISSUE CONFIRMATION
X'0824' SYNCPOINT ROLLBACK requested. O436 ISSUE ERROR
O438 ISSUE PREPARE
COBOL: PIC X(4). O43A ISSUE PASS
C: char eiberrcd [4]; O43C EXTRACT LOGONMSG
PL/I: CHAR(4) O43E EXTRACT ATTRIBUTES
ASM: CL4
O6O2 READ
See the CICS/ESA Distributed Transaction Programming
O6O4 WRITE
Guide for information about other EIBERRCD values that
O6O6 REWRITE
can occur. O6O8 DELETE
EIBFMH O6OA UNLOCK
indicates that the user data just received or retrieved O6OC STARTBR
O6OE READNEXT
contains an FMH (X'FF').
O61O READPREV
COBOL: PIC X(1). O612 ENDBR
C: unsigned char eibfmh; O614 RESETBR
PL/I: CHAR(1)
ASM: CL1 O8O2 WRITEQ TD
O8O4 READQ TD
EIBFN O8O6 DELETEQ TD
contains a code that identifies the last CICS command
issued by the task. OAO2 WRITEQ TS
COBOL: PIC X(2). OAO4 READQ TS
C: char eibfn [2]; OAO6 DELETEQ TS
PL/I: CHAR(2)
ASM: CL2 OCO2 GETMAIN
OCO4 FREEMAIN
Code Command
OEO2 LINK
O2O2 ADDRESS OEO4 XCTL
O2O4 HANDLE CONDITION OEO6 LOAD
O2O6 HANDLE AID OEO8 RETURN
O2O8 ASSIGN OEOA RELEASE
O2OA IGNORE CONDITION OEOC ABEND
O2OC PUSH OEOE HANDLE ABEND
O2OE POP
O21O ADDRESS SET 1OO2 ASKTIME
1OO4 DELAY
O4O2 RECEIVE 1OO6 POST
O4O4 SEND 1OO8 START
O4O6 CONVERSE 1OOA RETRIEVE
O4O8 ISSUE EODS 1OOC CANCEL
O4OA ISSUE COPY
O4OC WAIT TERMINAL 12O2 WAIT EVENT
O4OE ISSUE LOAD 12O4 ENQ
O41O WAIT SIGNAL 12O6 DEQ
O412 ISSUE RESET 12O8 SUSPEND
O414 ISSUE DISCONNECT
O416 ISSUE ENDOUTPUT 14O2 WRITE JOURNALNUM
O418 ISSUE ERASEAUP 14O4 WAIT JOURNALNUM

344 CICS/ESA Application Programming Reference

EIBFREE EIBRCODE

EIBFREE
16O2 SYNCPOINT indicates that the application program cannot continue
using the facility. The application program should either
18O2 RECEIVE MAP free the facility or should terminate so that the facility is
18O4 SEND MAP freed by CICS (X'FF').
18O6 SEND TEXT
18O8 SEND PAGE COBOL: PIC X(1).
18OA PURGE MESSAGE C: unsigned char eibfree;
18OC ROUTE PL/I: CHAR(1)
18OE RECEIVE PARTN ASM: CL1
181O SEND PARTNSET EIBNODAT
1812 SEND CONTROL
indicates that no data has been sent by the remote
1CO2 DUMP application (X'FF'). A message has been received from
the remote system that conveyed only control
1EO2 ISSUE ADD information. For example, if the remote application
1EO4 ISSUE ERASE executed a SEND command with the WAIT option, any
1EO6 ISSUE REPLACE data would be sent across the link. If the remote
1EO8 ISSUE ABORT application then executed a SEND INVITE command
1EOA ISSUE QUERY without using the FROM option to transmit data at the
1EOC ISSUE END same time, it would be necessary to send the INVITE
1EOE ISSUE RECEIVE instruction across the link by itself. In this case, the
1E1O ISSUE NOTE receiving application finds EIBNODAT set. The use of
1E12 ISSUE WAIT this field is restricted to application programs holding
1E14 ISSUE SEND conversations across APPC links only.
2OO2 BIF DEEDIT COBOL: PIC X(1).
C: unsigned char eibnodat;
48O2 ENTER TRACENUM PL/I: CHAR(1)
48O4 MONITOR ASM: CL1

EIBRCODE
4AO2 ASKTIME ABSTIME
4AO4 FORMATTIME contains the CICS response code returned after the
| function requested by the last CICS command to be
| 56O2 SPOOLOPEN issued by the task has been completed.
| 56O4 SPOOLREAD Note: For new commands where EIBRESP and
| 56O6 SPOOLWRITE EIBRESP2 are the strategic means of interrogating the
| 561O SPOOLCLOSE resulting condition of an executed command, byte 3 of
EIBRCODE has the same value as EIBRESP. Any
5EO6 CHANGE TASK
further information is in EIBRESP2 rather than
5E22 WAIT EXTERNAL
| 5E32 WAITCICS EIBRCODE. For a normal response, this field contains
hexadecimal zeros (6 X'00').
6AO2 QUERY SECURITY Almost all of the information in this field can be used
6CO2 WRITE OPERATOR within application programs by the HANDLE
6C12 ISSUE DFHWTO CONDITION command.
74O2 SIGNON COBOL: PIC X(6).
74O4 SIGNOFF C: char eibrcode [6];
| 74O6 VERIFY PASSWORD PL/I: CHAR(6)
| 74O8 CHANGE PASSWORD ASM: CL6
The following list contains the values of the bytes
7EO2 DUMP TRANSACTION together with the names of the conditions associated
Codes 82nn and 84nn are used by the CICS/ESA Front with the return codes.
End Programming Interface. See the CICS/ESA Front See the notes at the end of the list of values for
End Programming Interface User’s Guide for a explanations of the numbers following some of the
description. conditions.

Appendix A. EXEC interface block 345

EIBRCODE

EIBFN EIBRCODE Condition EIBFN EIBRCODE Condition

02 .. E0 .. .. .. .. .. INVREQ 0A .. D1 .. .. .. .. .. ISCINVREQ
0A .. D6 .. .. .. .. .. NOTAUTH
04 .. 04 .. .. .. .. .. EOF 0A .. E1 .. .. .. .. .. LENGERR
04 .. 10 .. .. .. .. .. EODS
04 .. C1 .. .. .. .. .. EOF 0C .. E1 .. .. .. .. .. LENGERR
04 .. C2 .. .. .. .. .. ENDINPT 0C .. E2 .. .. .. .. .. NOSTG
04 .. D0 .. .. .. .. .. SYSIDERR (see note 1)
04 .. D2 .. .. .. .. .. SESSIONERR (see note 2) 0E .. 01 .. .. .. .. .. PGMIDERR
04 .. D3 .. .. .. .. .. SYSBUSY (see note 3) # 0E .. D0 .. .. .. .. .. SYSIDERR (see note 1)
04 .. D4 .. .. .. .. .. SESSBUSY 0E .. D6 .. .. .. .. .. NOTAUTH
04 .. D5 .. .. .. .. .. NOTALLOC 0E .. E0 .. .. .. .. .. INVREQ
04 .. E0 .. .. .. .. .. INVREQ (see note 4) # 0E .. F1 .. .. .. .. .. TERMERR
04 .. E1 .. .. .. .. .. LENGERR (see note 5) | 0E .. E1 .. .. .. .. .. LENGERR
04 .. E3 .. .. .. .. .. WRBRK
04 .. E4 .. .. .. .. .. RDATT 10 .. 01 .. .. .. .. .. ENDDATA
04 .. E5 .. .. .. .. .. SIGNAL 10 .. 04 .. .. .. .. .. IOERR
04 .. E6 .. .. .. .. .. TERMIDERR 10 .. 11 .. .. .. .. .. TRANSIDERR
04 .. E7 .. .. .. .. .. NOPASSBKRD 10 .. 12 .. .. .. .. .. TERMIDERR
04 .. E8 .. .. .. .. .. NOPASSBKWR 10 .. 20 .. .. .. .. .. EXPIRED
04 .. EA .. .. .. .. .. IGREQCD 10 .. 81 .. .. .. .. .. NOTFND
04 .. EB .. .. .. .. .. CBIDERR 10 .. D0 .. .. .. .. .. SYSIDERR (see note 1)
| 04 .. EC .. .. .. .. .. PARTNERIDERR 10 .. D1 .. .. .. .. .. ISCINVREQ
| 04 .. ED .. .. .. .. .. NETNAMEIDERR 10 .. D6 .. .. .. .. .. NOTAUTH
04 .. F1 .. .. .. .. .. TERMERR | 10 .. D8 .. .. .. .. .. USERIDERR
04 .. .. 20 .. .. .. .. EOC 10 .. E1 .. .. .. .. .. LENGERR
04 .. .. 40 .. .. .. .. INBFMH 10 .. E9 .. .. .. .. .. ENVDEFERR
04 .. .. .. .. F6 .. .. NOSTART 10 .. FF .. .. .. .. .. INVREQ
04 .. .. .. .. F7 .. .. NONVAL
12 .. 32 .. .. .. .. .. ENQBUSY
06 .. 01 .. .. .. .. .. FILENOTFOUND 12 .. E0 .. .. .. .. .. INVREQ
06 .. 02 .. .. .. .. .. ILLOGIC (see note 6) 12 .. E1 .. .. .. .. .. LENGERR
06 .. 08 .. .. .. .. .. INVREQ
06 .. 0C .. .. .. .. .. NOTOPEN 14 .. 01 .. .. .. .. .. JIDERR
06 .. 0D .. .. .. .. .. DISABLED 14 .. 02 .. .. .. .. .. INVREQ
06 .. 0F .. .. .. .. .. ENDFILE 14 .. 05 .. .. .. .. .. NOTOPEN
06 .. 80 .. .. .. .. .. IOERR (see note 6) 14 .. 06 .. .. .. .. .. LENGERR
06 .. 81 .. .. .. .. .. NOTFND 14 .. 07 .. .. .. .. .. IOERR
06 .. 82 .. .. .. .. .. DUPREC 14 .. 09 .. .. .. .. .. NOJBUFSP
06 .. 83 .. .. .. .. .. NOSPACE 14 .. D6 .. .. .. .. .. NOTAUTH
06 .. 84 .. .. .. .. .. DUPKEY
06 .. 85 .. .. .. .. .. SUPPRESSED 16 .. 01 .. .. .. .. .. ROLLEDBACK
06 .. 86 .. .. .. .. .. LOADING
06 .. D0 .. .. .. .. .. SYSIDERR (see note 1) 18 .. 01 .. .. .. .. .. INVREQ
06 .. D1 .. .. .. .. .. ISCINVREQ 18 .. 02 .. .. .. .. .. RETPAGE
06 .. D6 .. .. .. .. .. NOTAUTH 18 .. 04 .. .. .. .. .. MAPFAIL
06 .. E1 .. .. .. .. .. LENGERR 18 .. 08 .. .. .. .. .. INVMPSZ (see note 7)
18 .. 20 .. .. .. .. .. INVERRTERM
08 .. 01 .. .. .. .. .. QZERO 18 .. 40 .. .. .. .. .. RTESOME
08 .. 02 .. .. .. .. .. QIDERR 18 .. 80 .. .. .. .. .. RTEFAIL
08 .. 04 .. .. .. .. .. IOERR 18 .. E1 .. .. .. .. .. LENGERR
08 .. 08 .. .. .. .. .. NOTOPEN 18 .. E3 .. .. .. .. .. WRBRK
08 .. 10 .. .. .. .. .. NOSPACE 18 .. E4 .. .. .. .. .. RDATT
08 .. C0 .. .. .. .. .. QBUSY 18 .. .. 02 .. .. .. .. PARTNFAIL
08 .. D0 .. .. .. .. .. SYSIDERR (see note 1) 18 .. .. 04 .. .. .. .. INVPARTN
08 .. D1 .. .. .. .. .. ISCINVREQ 18 .. .. 08 .. .. .. .. INVPARTNSET
08 .. D6 .. .. .. .. .. NOTAUTH 18 .. .. 10 .. .. .. .. INVLDC
08 .. D7 .. .. .. .. .. DISABLED 18 .. .. 20 .. .. .. .. UNEXPIN
08 .. E0 .. .. .. .. .. INVREQ 18 .. .. 40 .. .. .. .. IGREQCD
08 .. E1 .. .. .. .. .. LENGERR 18 .. .. 80 .. .. .. .. TSIOERR
18 .. .. .. 01 .. .. .. OVERFLOW
0A .. 01 .. .. .. .. .. ITEMERR 18 .. .. .. 04 .. .. .. EODS
0A .. 02 .. .. .. .. .. QIDERR 18 .. .. .. 08 .. .. .. EOC
0A .. 04 .. .. .. .. .. IOERR 18 .. .. .. 10 .. .. .. IGREQID
0A .. 08 .. .. .. .. .. NOSPACE
0A .. 20 .. .. .. .. .. INVREQ 1A .. E0 .. .. .. .. .. INVREQ
0A .. D0 .. .. .. .. .. SYSIDERR (see note 1) 1A .. 04 .. .. .. .. .. DSSTAT

346 CICS/ESA Application Programming Reference

EIBRCODE

EIBFN EIBRCODE Condition .

1A .. 08 .. .. .. .. .. FUNCERR Further information about SYSIDERR can be found
1A .. 0C .. .. .. .. .. SELNERR
in the CICS/ESA Intercommunication Guide.
1A .. 10 .. .. .. .. .. UNEXPIN
1A .. E1 .. .. .. .. .. LENGERR 2. When SESSIONERR occurs, further information is
1A .. .. 11 .. .. .. .. EODS provided in bytes 1 and 2 of EIBRCODE, as follows:
1A .. .. 2B .. .. .. .. IGREQCD
1A .. .. .. 20 .. .. .. EOC
.. O8 .. .. .. .. session out of service
.. OC xx .. .. .. session definition error
22 .. 80 .. .. .. .. .. INVEXITREQ .. OC OO .. .. .. name not found
| 4A .. .. .. .. 01 .. .. INVREQ .. OC OC .. .. .. profile not found.
Further information about SESSIONERR can be
56 .. .. .. .. 0D .. .. NOTFND
found in the CICS/ESA Intercommunication Guide.
56 .. .. .. .. 10 .. .. INVREQ
56 .. .. .. .. 13 .. .. NOTOPEN
56 .. .. .. .. 14 .. .. ENDFILE
56 .. .. .. .. 15 .. .. ILLOGIC
56 .. .. .. .. 16 .. .. LENGERR
56 .. .. .. .. 2A .. .. NOSTG
56 .. .. .. .. 46 .. .. NOTAUTH
56 .. .. .. .. 50 .. .. NOSPOOL
| 56 .. .. .. .. 55 .. .. ALLOCERR
| 56 .. .. .. .. 56 .. .. STRELERR
| 56 .. .. .. .. 57 .. .. OPENERR
| 56 .. .. .. .. 58 .. .. SPOLBUSY
| 56 .. .. .. .. 59 .. .. SPOLERR
| 56 .. .. .. .. 5A .. .. NODEIDERR

Notes:

1. When SYSIDERR occurs, further information is

provided in bytes 1 and 2 of EIBRCODE, as follows:
.. O4 OO .. .. .. request was for a function
that is not valid.
.. O4 O4 .. .. .. no session available and
NOQUEUE.
.. O4 O8 .. .. .. modename not found2.
.. O4 OC .. .. .. modename not valid2.
.. O4 1O .. .. .. task canceled or timed
out during allocation2.
.. O4 14 .. .. .. mode group is out of
service2.
.. O4 18 .. .. .. close - DRAIN=ALL2.
| .. O8 .. .. .. .. sysid is not available.
| .. O8 OO .. .. .. no session available,
| all sessions are out
| of service, or released,
| or being quiesced.
| .. O8 O4 .. .. .. no session available,
| request to queue rejected
| by XZIQUE global user
| exit program.
| .. O8 O8 .. .. .. no session available;
| request rejected by XZIQUE
| global user exit program.
.. OC xx .. .. .. sysid definition error.
.. OC OO .. .. .. name not that of TCTSE.
.. OC O4 .. .. .. name not that of remote
TCTSE.
.. OC O8 .. .. .. mode name not found.
.. OC OC .. .. .. profile not found

2 For APPC only.

Appendix A. EXEC interface block 347

EIBRECV EIBRESP

3. If SYSBUSY occurs on an ALLOCATE command 5. When LENGERR occurs during terminal control
that attempts to acquire a session to an APPC operations, further information is provided in byte 1
terminal or system, byte 3 of the EIBRCODE of EIBRCODE, as follows:
indicates where the error condition was detected: .. OO .. .. .. .. input data is overlong and
.. .. .. OO .. .. the request was for a has been truncated.
session to a connected .. O4 .. .. .. .. on output commands, an
terminal or system. incorrect (FROM)LENGTH has
.. .. .. O1 .. .. the request was for a been specified, either less
session to a remotely than zero or greater than
connected terminal or 32 767.
system, and the error .. O8 .. .. .. .. on input commands, an
occurred in the terminal- incorrect (TO)LENGTH has
owning region (TOR) or been specified, greater than
an intermediate system. 32 767.
.. .. .. O2 .. .. the request was for a .. OC .. .. .. .. length error has occurred on
session to a remotely ISSUE PASS command.
connected terminal or
| Note: This field is not used exclusively for the
system, and the error
| above and may take other values.
occurred in the
application-owning 6. When ILLOGIC or IOERR occurs during file control
region (AOR). operations, further information is provided in field
Further information about SYSBUSY can be found EIBRCODE, as follows:
in the CICS/ESA Intercommunication Guide. .. xx xx xx xx .. BDAM response.
.. xx .. .. .. .. VSAM return code.
4. When INVREQ occurs during terminal control
.. .. xx .. .. .. VSAM error code.
| operations, further information is provided in bytes 1
| or 3 of EIBRCODE as follows: Details of these response codes are given in the
# DFSMS/MVS Macro Instructions for Data Sets
| .. 24 .. .. .. .. ISSUE PREPARE command -
| STATE error. # manual for VSAM, and the Data Facility Product
.. .. .. O4 .. .. ALLOCATE command - TCTTE Customization Guide for BDAM.
already allocated. 7. When INVMPSZ occurs during BMS operations,
.. .. .. O8 .. .. FREE command - TCTTE in byte 3 of field EIBRCODE contains the terminal
wrong state. code:
.. .. .. OC .. .. CONNECT PROCESS command -
SYNCLVL 2 requested, but .. .. .. xx .. .. terminal code.
cannot be supported on These are the same as the mapset suffixes shown
the session in use. in Table 27 on page 400.
.. .. .. 1O .. .. EXTRACT ATTACH command -
incorrect data. 8. Codes 82nn and 84nn are used by the CICS/ESA
.. .. .. 14 .. .. SEND command - CONFIRM Front End Programming Interface. See the
option specified, but CICS/ESA Front End Programming Interface User’s
conversation not SYNCLVL 1. Guide for a description.
.. .. .. 18 .. .. EXTRACT TCT command -
incorrect netname. EIBRECV
.. .. .. 1C .. .. an incorrect command has indicates that the application program is to continue
been issued for the terminal receiving data from the facility by executing RECEIVE
or logical unit in use. commands (X'FF').
.. .. .. 2O .. .. an incorrect command has COBOL: PIC X(1).
been issued for the LUTYPE6.2 C: unsigned char eibrecv;
conversation type in use. PL/I: CHAR(1)
.. .. .. 28 .. .. GETMAIN failure on ISSUE ASM: CL1
PASS command.
EIBREQID
contains the request identifier assigned to an interval
control command by CICS; this field is not used when a
request identifier is specified in the application program.
COBOL: PIC X(8).
C: char eibreqid [8];
PL/I: CHAR(8)
ASM: CL8

348 CICS/ESA Application Programming Reference

EIBRESP2 EIBSIG

EIBRESP to which it applies. For requests to remote files,

contains a number corresponding to the RESP condition EIBRESP2 contains zeros.
that occurred. These numbers are listed below (in
For programs written in C, any value passed via the exit
decimal) for the conditions that can occur during
or return function is saved in EIBRESP2.
execution of the commands described in this manual.
COBOL: PIC S9(8) COMP.
COBOL: PIC S9(8) COMP C: long int eibresp2;
C: long int eibresp; PL/I: FIXED BIN(31)
PL/I: FIXED BIN(31) ASM: F
ASM: F
EIBRLDBK
No. Condition No. Condition indicates rollback.
00 NORMAL 44 QIDERR COBOL: PIC X(1).
45 NOJBUFSP C: unsigned char eibrldbk;
01 ERROR 46 DSSTAT
PL/I: CHAR(1)
02 RDATT 47 SELNERR
ASM: CL1
03 WRBRK 48 FUNCERR
04 EOF 49 UNEXPIN EIBRSRCE
05 EODS
contains the symbolic identifier of the resource being
06 EOC 50 NOPASSBKRD
accessed by the latest executed command:
07 INBFMH 51 NOPASSBKWR
08 ENDINPT 53 SYSIDERR Number of
09 NONVAL 54 ISCINVREQ characters
55 ENQBUSY Type of (H=halfword
10 NOSTART 56 ENVDEFERR command Resource binary)
11 TERMIDERR 57 IGREQCD
12 FILENOTFOUND 58 SESSIONERR BMS Map name 7
13 NOTFND 59 SYSBUSY File control File name 8
14 DUPREC Interval control Transaction name 4
15 DUPKEY 60 SESSBUSY Journal control Journal number H
16 INVREQ 61 NOTALLOC
Program control Program name 8
17 IOERR 62 CBIDERR
# Temporary storage TS queue name 8
18 NOSPACE 63 INVEXITREQ
control
19 NOTOPEN 64 INVPARTNSET
65 INVPARTN
Terminal control Terminal or 4
20 ENDFILE 66 PARTNFAIL logical unit
21 ILLOGIC 69 USERIDERR identifier
22 LENGERR or
23 QZERO 70 NOTAUTH LU6.1 session or 4
24 SIGNAL 72 SUPPRESSED APPC conversation
25 QBUSY identifier
| 26 ITEMERR 80 NOSPOOL Transient data TD queue name 4
27 PGMIDERR 81 TERMERR control
28 TRANSIDERR 82 ROLLEDBACK
Identifiers less than eight characters in length are
29 ENDDATA 84 DISABLED
| 85 ALLOCERR padded on the right with blanks.
| 31 EXPIRED 86 STRELERR COBOL: PIC X(8).
32 RETPAGE 87 OPENERR C: char eibrsrce [8];
| 33 RTEFAIL 88 SPOLBUSY PL/I: CHAR(8)
| 34 RTESOME 89 SPOLERR ASM: CL8
| 35 TSIOERR 90 NODEIDERR
| 36 MAPFAIL 91 TASKIDERR EIBSIG
| 37 INVERRTERM 92 TCIDERR indicates that SIGNAL has been received (X'FF').
| 38 INVMPSZ 93 DSNNOTFOUND
39 IGREQID 94 LOADING COBOL: PIC X(1).
| 95 MODELIDERR C: unsigned char eibsig;
| 40 OVERFLOW 96 OUTDESCERR PL/I: CHAR(1)
| 41 INVLDC 97 PARTNERIDERR ASM: CL1
| 42 NOSTG 98 PROFILEIDERR
| 43 JIDERR 99 NETNAMEIDERR

EIBRESP2
contains more detailed information that may help explain
why the RESP condition occurred. This field contains
meaningful values, as documented with each command

Appendix A. EXEC interface block 349

EIBSYNC EIBTRNID

EIBSYNC
indicates that the application program must take a
syncpoint or terminate. Before either is done, the
application program must ensure that any other facilities,
owned by it, are put into the send state, or are freed
(X'FF').
COBOL: PIC X(1).
C: unsigned char eibsync;
PL/I: CHAR(1)
ASM: CL1

EIBSYNRB
indicates that the application program should issue a
SYNCPOINT ROLLBACK command (X'FF'). This field
is only set in application programs holding a
conversation on an APPC or MRO link.
COBOL: PIC X(1).
C: unsigned char eibsynrb;
PL/I: CHAR(1)
ASM: CL1

EIBTASKN
contains the task number assigned to the task by CICS.
This number appears in trace table entries generated
while the task is in control. The format of the field is
packed decimal.
COBOL: PIC S9(7) COMP-3.
C: char eibtaskn [4];
PL/I: FIXED DEC(7,O)
ASM: PL4

EIBTIME
contains the time at which the task is started (this field is
# updated by the ASKTIME command). The time is in
# packed decimal form (0HHMMSS+), and can contain a
# value in the range 0000000+ to 0240000+. Both
# 0000000+ and 0240000+ are valid.
COBOL: PIC S9(7) COMP-3.
C: char eibtime [4];
PL/I: FIXED DEC(7,O)
ASM: PL4

EIBTRMID
contains the symbolic terminal identifier of the principal
facility (terminal or logical unit) associated with the task.
COBOL: PIC X(4).
C: char eibtrmid [4];
PL/I: CHAR(4)
ASM: CL4

EIBTRNID
contains the symbolic transaction identifier of the task.
COBOL: PIC X(4).
C: char eibtrnid [4];
PL/I: CHAR(4)
ASM: CL4

350 CICS/ESA Application Programming Reference

ASSIGN

Appendix B. Codes returned by ASSIGN

This appendix describes the codes returned by the ASSIGN Code Meaning
command. 1.11 ...1 X'B1' 3601
1.11 ..1. X'B2' 3614
1.11 .1.. X'B4' 3790
1.11 .1.1 X'B5' 3790 User program
ASSIGN TERMCODE 1.11 .11. X'B6' 3790 SCS printer
1.11 1... X'B8' 3650 Pipeline
This section gives the meanings of the terminal type codes in 1.11 1..1 X'B9' 3653 Host conversational
the first byte of the data area returned by the TERMCODE 1.11 1.1. X'BA' 3650 Attached 3270 HC
option of the ASSIGN command. 1.11 1.11 X'BB' 3650 User program
1.11 11.1 X'BD' Contention logical unit
The codes are derived from the DEVICE attribute of the 1.11 111. X'BE' Interactive logical unit
TYPETERM RDO resource. The second byte of the data 1.11 1111 X'BF' Batch logical unit
11.. .... X'C0' LUTYPE 6
area contains a model number in character form, as set by
the TERMMODEL RDO attribute of TYPETERM. Note: An ASSIGN TERMCODE for an ISC session returns a X'C0'
TYPETERM is described in the CICS/ESA Resource for LUTYPE 6. An INQUIRE CONNECTION then determines
Definition Guide. whether this ISC connection is using LUTYPE6.1 or APPC protocols.

The codes are listed here as both bit patterns and 11.. ...1 X'C1' LUTYPE 4
hexadecimal values. 11.1 ...1 X'D1' ISC MM conversation
11.1 ..1. X'D2' LUC mode group entry
Code Meaning 11.1 ..11 X'D3' LUC session
.... ...1 X'01' 7770 Note: X'D3' is not used.
.... ..1. X'02' System 7
.... 1... X'08' Console
...1 ..1. X'12' Sequential disk
...1 .1.. X'14' Magnetic tape ASSIGN FCI
...1 1... X'18' Card reader or line printer
...1 1..1 X'19' Spooling system printer This section gives the meanings of the facility control
...1 1.1. X'1A' Spooling internal reader indicator codes in the data area returned by the FCI option of
..1. .... X'20' Hard-copy terminals the ASSIGN command.
..1. ...1 X'21' Model 33/35 TWX
..1. ..1. X'22' Teletypewriter Code Meaning
..1. .1.. X'24' 1050 .... ...1 X'01' TERMINAL FACILITY MASK
..1. 1... X'28' 2740 .... ..1. X'02' K C P MACRO FILE MASK
..1. 1.1. X'2A' 2741 Correspondence .... .1.. X'04' NONTERMINAL FACILITY MASK
..1. 1.11 X'2B' 2741 EBCDIC .... 1... X'08' DESTINATION CONTROL TABLE
.1.. .... X'40' Video terminals ...1 .... X'10' AID FACILITY MASK
.1.. ...1 X'41' 2260 local 111. .... X'E0' reserved
.1.. 1... X'48' 2260 remote
.1.. 1.1. X'4A' 1053
.1.. 11.. X'4C' 2265
.1.1 .... X'50' TCAM
1... .... X'80' Bisynchronous
1... ..1. X'82' 2770
1... .1.. X'84' 2780
1... .1.1 X'85' 3780
1... .11. X'86' 2980
1... 1... X'88' 3735
1... 1..1 X'89' 3740
1... 1.1. X'8A' 3600 bisynchronous
1..1 ...1 X'91' 3277 remote
1..1 ..1. X'92' 3275 remote
1..1 ..11 X'93' BTAM 3284 remote and VTAM 3270P
1..1 .1.. X'94' BTAM 3286 remote
1..1 1..1 X'99' 3277 local
1..1 1.11 X'9B' BTAM 3284 local
1..1 11.. X'9C' BTAM 3286 local
1.1. .... X'A0' Bisynchronous - programmable
1.1. ...1 X'A1' System/3
1.1. .1.. X'A4' System/370
1.1. .11. X'A6' System/7 with BSCA
1.11 .... X'B0' SDLC device class

ASSIGN

352 CICS/ESA Application Programming Reference

Translated code

Appendix C. Translated code for CICS commands

Application programs can be written in COBOL, C, PL/I, or
assembler language, and contain CICS commands. CICS
PL/I
translates these programs and creates an equivalent source
For a PL/I application program, each command is always
program where each command is now translated into a call
replaced by a DO statement, a declaration of a generated
macro or statement in the language of the original source
entry name, a CALL statement, and an END statement. The
program.
ENTRY declaration ensures that the appropriate conversions
for argument values take place.

COBOL If a PL/I on-unit consists of a single EXEC CICS command,

the command should be inside a BEGIN block, for example:
For a COBOL application program, each command is
ON ERROR BEGIN;
replaced by one or more MOVE statements followed by a EXEC CICS RETURN;
COBOL CALL statement. END;
The purpose of the MOVE statements is to assign constants In a similar way, if an EXEC CICS command is associated
to COBOL data variables; this enables constants and names with a PL/I condition prefix, the command should be inside a
to be specified as arguments to options in the commands. BEGIN block, for example:
# For example, for OS/VS COBOL and VS COBOL II, a (NOZERODIVIDE): BEGIN;
# command such as: EXEC CICS GETMAIN
EXEC CICS RECEIVE MAP('A') END-EXEC. SET(ptr-ref)
LENGTH(data-value);
may be translated to: END;
MOVE ' ' TO DFHEIVO.
MOVE 'A' TO DFHCOO7O. If OPTIONS(MAIN) is specified, the translator modifies the
CALL 'DFHEI1' USING DFHEIVO DFHCOO7O AI. parameter list by inserting the EIB structure pointer as the
first parameter. If OPTIONS(MAIN) is not specified (that is, if
Declarations for the generated variables DFHEIV0 and the program is to be link-edited to the main module), the
DFHC0070 are included automatically in the working-storage parameter list is not modified, and it is the application
section; their names are reserved. The string within the programmer’s responsibility to address the EIB structure in
quotation marks moved to DFHEIV0 consists of characters the link-edited program if access to it is required. In either
some of which may be unprintable. Do not use EXEC, case, where a program commences with a valid PL/I
CICS, DLI, END-EXEC, or names starting with DFH, as PROCEDURE statement, the translator inserts the
names for user variables. declaration of the EIB structure.

# With the COBOL3 translator option the command:

# EXEC CICS RECEIVE MAP('A') END-EXEC. Assembler language
# may be translated to:
The invocation of a CICS assembler-language application
# Call 'DFHEI1' using by content x'18O2cOOOO7OOOOOOOOO4O9OOOOOO
program obeys system standards, which means that on entry
#- '2OfOfOfOfOf94O4O4O' by content 'A ' by reference to
AIthe application program, registers 1, 15, 14, and 13
# end-call.
contain the following:
The translator modifies the linkage section by inserting the Register 1 contains the address of the parameter list;
EIB structure as the first parameter, and inserts declarations # there are at least two entries in this list, as follows:
of the temporary variables that it requires into the
– Address of the EIB (EXEC interface block)
working-storage section. It also inserts a DFHCOMMAREA if
– Address of the COMMAREA; if no COMMAREA,
# the first item in the linkage section is not a DFHCOMMAREA.
entry is X'00000000'.
Register 15 contains the address of the entry point
C Register 14 contains the address of the return point
Register 13 contains the address of the save area.
For a C application program, each command is replaced by
reassignment statements followed by a dfhexec statement All other registers are undefined.
that passes the parameters.

Translated code

DFHECALL macro DFHEIRET

This macro performs epilog code; that is, it:
For an assembler-language application program, each
command is replaced by an invocation of the DFHECALL Restores registers
macro. DFHEIRET RCREG=nn, where nn (any register
number other than 13) contains the return code to be
This macro expands to a system-standard call sequence placed in register 15 after the registers are restored.
using registers 15, 14, 0, and 1, whose contents are:
Returns control to the address in register 14.
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 (DFHEAI) that must be link-edited with
your application program.

You can specify the exit from the application program by a

RETURN command in your source program. Alternatively,
you can let the translator-inserted macro DFHEIRET, which
has been inserted before the END statement, do it. This
macro only restores the registers and returns control to the
address in register 14. Note that this can be used 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 application program is
reentrant, and then invokes the EXEC interface program
(DFHEIP). DFHEIP also obeys system standards, as
described above.

In addition to the invocation of the DFHECALL macro, the

translator also inserts the following macros into your source
program:
DFHEIGBL
This macro sets globals if you are using EXEC DLI in
either a batch or an online CICS application program.
Within DFHEIGBL, if DFHEIDL is set to 1, this means that
the program contains EXEC DLI commands. If DFHEIDB
is set to 1, this means that the program is batch DL/I. If
you are not using DL/I, it is commented and set to 0.
DFHEIENT
This macro is inserted after the first CSECT or START
instruction. It performs prolog code; that is, it:
Saves registers
Gets an initial allocation of the storage defined by
DFHEISTG)
Sets up a base register (default register 3)
Sets up a dynamic storage register (default register
13)
Sets up a register to address the EIB (default register
11).

354 CICS/ESA Application Programming Reference

Translated code

DFHEISTG and DFHEIEND

Source program
These macros define dynamic storage; that is, they:
DFHEISTG DSECT
Define the storage required for the parameter list
COPY DFH$AGA INPUT MAP DSECT
Define a save area. COPY DFH$AGB OUTPUT MAP DSECT
MESSAGE DS CL39
A copybook, DFHEIBLK, containing a DSECT that describes INQUIRY CSECT
the EIB, is also included automatically. EXEC CICS RECEIVE MAP('DFH$AGA')
MVC NUMBO,KEYI
Note that the program must have an END statement because MVC MESSAGE,=CL(L'MESSAGE)'THIS IS A MESSAGE'
EXEC CICS SEND MAP('DFH$AGB') ERASE
the translator does not otherwise insert the default macros.
END
The example in Figure 7 shows a simple
assembler-language application program that uses the BMS The above source program is translated to:
command SEND MAP to send a map to a terminal. The
lower part of the figure shows the output after program DFHEIGBL , INSERTED BY TRANSLATOR
DFHEISTG DSECT
INSTRUCT has been translated. DFHEISTG INSERTED BY TRANSLATOR
COPY DFH$AGA INPUT MAP DSECT
Source program COPY DFH$AGB OUTPUT MAP DSECT
MESSAGE DS CL39
INSTRUCT CSECT INQUIRY CSECT
EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE DFHEIENT INSERTED BY TRANSLATOR
END _ EXEC CICS RECEIVE MAP('DFH$AGA')
DFHECALL =X'18O2COOOO8OOOOOOOOO4O9OOOOOO2O',
(CHA7,=CL7'DFH$AGA_'),(______RF,DFH$AGAI)
The above source program is translated to: MVC NUMBO,KEYI
MVC MESSAGE,=CL(L'MESSAGE)'THIS IS A MESSAGE'
DFHEIGBL , INSERTED BY TRANSLATOR _ EXEC CICS SEND MAP('DFH$AGB') ERASE
INSTRUCT CSECT DFHECALL =X'18O4COOOO8OOOOOOOOO4E2O4OOOO2O',
DFHEIENT INSERTED BY TRANSLATOR (CHA7,=CL7'DFH$AGB_'),(______RF,DFH$AGBO)
_ EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE DFHEIRET INSERTED BY TRANSLATOR
DFHECALL =X'18O4COOOO8OOOOOOOOO462O4OOOO2O', DFHEISTG INSERTED BY TRANSLATOR
(CHA7,=CL7'DFH$AGA_'),(______RF,DFHEIVOO) DFHEIEND INSERTED BY TRANSLATOR
DFHEIRET INSERTED BY TRANSLATOR END
DFHEISTG INSERTED BY TRANSLATOR
DFHEIEND INSERTED BY TRANSLATOR Figure 8. Translated code for user variables
END

Figure 7. Translated code for a CICS command Multiple base registers

The values provided by the automatic insertion of DFHEIENT
Extensions to dynamic storage may be inadequate for application programs that produce a
translated output greater than 4095 bytes.
You can extend dynamic storage to provide extra storage for
user variables. For example, the translator by default only sets up one base
register (register 3), or, when the DLI translator option has
You do this by defining these variables in your source been specified, the literals produced by the translator
program in a DSECT called DFHEISTG. The maximum initializing the DIB could fall outside the range of that single
amount of dynamic storage obtainable using the DFHEISTG base register.
DSECT is 65 264 bytes. (Note that DFHEISTG is a reserved
name.) This storage is initialized to X'00'. At translation, To overcome this problem, you can prevent the translator
the translator inserts the DFHEISTG macro immediately from automatically inserting its version of the DFHEIENT
following your DFHEISTG DSECT instruction. In this way macro by specifying the translator option NOPROLOG. This
the DSECT describes dynamic storage needed for the enables you to provide your own DFHEIENT macro with the
parameter list, for the command-level interface, and for any CODEREG operand so that you can specify more than one
user variables. base register. You must code your own version of the
DFHEIENT macro, which can have up to three operands, in
The example in Figure 8 shows a simple place of the first CSECT or START instruction in your source
assembler-language application program that uses such program. The three operands are as follows:
variables in dynamic storage.
CODEREG - base registers
DATAREG - dynamic-storage registers
EIBREG - register to address the EIB.

Appendix C. Translated code for CICS commands 355

Translated code

For example, the source code shown in Figure 7 would

become:
| INSTRUCT DFHEIENT CODEREG=(2,3,4),
DATAREG=(13,5),
EIBREG=6
EXEC CICS SEND
MAP('DFH$AGA')
MAPONLY ERASE
END

The symbolic register DFHEIPLR is equated to the first

DATAREG either explicitly specified or obtained by default.
It is recommended that, because register 13 points to the
save area defined in dynamic storage by DFHEISTG, you
use register 13 as the first dynamic-storage register.

DFHEIPLR is assumed by the expansion of a CICS

command to contain the value set up by DFHEIENT. You
should either dedicate this register or ensure that it is
restored before each CICS command.

Assembler-language programs, translated with the DLI

option, have a DLI initialization call inserted after each
CSECT statement. Assembler-language programs larger
than 4095 bytes, that do not use the CODEREG operand of
the DFHEIENT macro to establish multiple base registers,
must include an LTORG statement to ensure that the literals,
generated by either DFHEIENT or a DLI initialization call, fall
within the range of the base register.

Note that, in general, an LTORG statement is needed for

every CSECT that exceeds 4095 bytes in length.

356 CICS/ESA Application Programming Reference

Terminal control

Appendix D. Terminal control

This appendix contains general information that applies to all If the data exceeds the specified maximum length and the
terminals and logical units. For more detail, see the NOTRUNCATE option is specified, the remaining data is
command descriptions. made available to satisfy subsequent RECEIVE commands.
If NOTRUNCATE is not specified, the data is truncated and
the LENGERR condition occurs. In this event, if the
Commands and options for terminals and LENGTH option is specified, the named data area is set to
logical units the actual data length (before truncation occurs) when data
has been received. The first RECEIVE command in a task
This section describes the commands and options that apply started by a terminal does not issue a terminal control read
to terminals and logical units. but simply copies the input buffer, even if the data length is
zero. A second RECEIVE command must be issued to
cause a terminal control read.
Fullword lengths
When a PA key is defined as a print key by the system
For all terminal control commands, fullword length options initialization parameter PRINT, and that key is pressed in
can be used instead of halfword length options. In particular, response to a RECEIVE command, it has no effect on the
where the following options are used in CONVERSE, application program. The RECEIVE command is satisfied,
RECEIVE, or SEND, the corresponding alternative can be and the application allowed to continue, when another
specified instead (except for those noted): attention (that is, one of the other PA keys, any of the PF
Option Alternative keys, the ENTER key, or the light pen) is made at the
keyboard.
LENGTH FLENGTH
TOLENGTH TOFLENGTH
FROMLENGTH FROMFLENGTH Write to terminal or logical unit (SEND)
MAXLENGTH MAXFLENGTH
The SEND command is used to write data to a terminal or
Application programs should be consistent in their use of logical unit. The options FROM and LENGTH specify
fullword and halfword options on terminal control commands. respectively the data area from which the data is to be taken
The maximum value that can be specified as a parameter on and the length (in bytes) of the data. For a transaction
any length keyword is 32 767. See the CICS/ESA started by automatic transaction initiation (ATI), a SEND
Application Programming Guide for more information. command should always precede the first RECEIVE in a
transaction.

Read from terminal or logical unit WAIT option of SEND command: Unless the WAIT
(RECEIVE) option is specified also, the transmission of the data
associated with the SEND command is deferred until a later
The RECEIVE command is used to read data from a terminal event, such as a syncpoint, occurs. This deferred
or logical unit. The INTO option is used to specify the area transmission reduces the flows of data by allowing data-flow
into which the data is to be placed. Alternatively, a pointer controls to be transmitted with the data.
reference can be specified in the SET option. CICS acquires
an area large enough to hold the data and sets the pointer Transmission is not deferred for distributed transaction
reference to the address of that data. processing when interregion communication (IRC) is in use.

The contents of this area are available to the task until the
next terminal I/O command. However, the area does not Synchronize terminal I/O for a transaction
belong to the task and is released by CICS while processing (WAIT TERMINAL)
the next request. Therefore, this area cannot be passed
back to CICS for further processing. This command is used to ensure that a terminal operation
has completed before further processing occurs in a task
The application can use MAXLENGTH to specify the under which more than one terminal or logical unit operation
maximum length of data that the program accepts. If the is performed. Alternatively, the WAIT option can be specified
MAXLENGTH option is omitted on a RECEIVE command for in a SEND command. (A wait is always carried out for a
which the INTO option is specified, the maximum length of RECEIVE command.) Either method may cause execution
data the program accepts can be specified in the LENGTH of a task to be suspended. If suspension is necessary,
option. If the MAXLENGTH option is omitted on a RECEIVE control is returned to CICS. Execution of the task is
command for which the SET option is specified, CICS resumed when the operation is completed.
acquires enough storage to hold all the available data.

Terminal control

Even if the WAIT option is not specified in a SEND

command, the EXEC interface program ensures that the TCAM-supported terminals and logical
operation is completed before issuing a subsequent units
RECEIVE or SEND command.
Because TCAM permits many applications to share a single
network, the CICS-TCAM interface supports data streams
Converse with terminal or logical unit rather than specific terminals or logical units.
(CONVERSE)
Operations for terminals supported by TCAM use the same
For most terminals or logical unit types, a conversational options as the terminals supported by other access methods.
mode of communication can be used. The CONVERSE With the exception of the BUFFER option for the 3270, all
command is used for this purpose and means that the 3650 options applicable for input operations are supported by
application program communicates with the host processor. CICS-TCAM. However, the conditions ENDINPT and EOF
If this option is not specified, the 3650 application program do not occur.
cannot communicate with the host processor. In general, the
CONVERSE command can be considered as a combination All output requests are the same for TCAM as for other
of a SEND command followed immediately by a WAIT CICS-supported terminals, except that:
TERMINAL command and then by a RECEIVE command. The ISSUE RESET command cannot be used
However, not all options of the SEND and RECEIVE
The ISSUE COPY and ISSUE PRINT commands for the
commands are valid for the CONVERSE command; specific
3270 cannot be used
rules are given in the syntax descriptions for different
devices. The TOLENGTH option is equivalent to the The DEST option is available on CONVERSE and SEND
LENGTH option of the RECEIVE command, and the commands, in addition to other appropriate options.
FROMLENGTH option is equivalent to the LENGTH option of
the SEND command. With the exception of 3650 logical units, operations for logical
units supported by TCAM use the same options as logical
units supported by VTAM.
Send an asynchronous interrupt (ISSUE
SIGNAL)
BTAM programmable terminals
This command is used, in a transaction in receive mode, to
signal to the sending transaction that a mode change is CICS/ESA 4.1 does not support local BTAM terminals.
needed. The execution of the command raises the SIGNAL However, it does support transaction routing from BTAM
condition on the next SEND or RECEIVE command executed terminals attached to a remote system.
in the sending transaction, and a previously executed
HANDLE CONDITION command for this condition can be When BTAM is used by CICS for programmable binary
used either to action the request or to ignore it. synchronous telecommunication line management, CICS
initializes the telecommunication line with a BTAM
communication line management; CICS initializes the
Relinquish a telecommunication line communication read initial (TI); the terminal response must
(ISSUE RESET) be a write initial (TI) or the equivalent. If an application
program makes an input request, CICS issues a read
This command is used to relinquish use of a
continue (TT) to that line; if the application program makes
telecommunication line. The command applies only to binary
an output request, CICS issues a read interrupt (RVI) to that
synchronous devices using BTAM. The next BTAM
line. If end of transmission (EOT) is not received on the RVI,
operation is a read or write initial.
CICS issues a read continue (TT) until the EOT is received.

Disconnect a switched line (ISSUE When TCAM is used, all of this line control is handled by the
message control facility rather than by CICS.
DISCONNECT)
The programmable terminal response to a read interrupt
This command is used to break a line connection between a
must be “end of transmission” (EOT). The EOT response
terminal and the processor, or to break a session between
may, however, be preceded by writes, in order to exhaust the
TCAM or VTAM logical units, when the transaction is
contents of output buffers (if the input buffer size is not
completed. If the terminal is a buffered device, the data in
exceeded by this data). The input buffer size is specified by
the buffers is lost.
the system programmer during preparation of the TCT.
When used with a VTAM terminal, ISSUE DISCONNECT, CICS issues a read continue until it receives an EOT, or until
which does not become effective until the task completes, the input message is greater than the input buffer (an error
signs off the terminal, frees the COMMAREA, clears the next condition).
TRANID, stops any BMS paging, and, if autoinstall is in
effect, deletes the terminal definition.

358 CICS/ESA Application Programming Reference

Terminal control

After receiving an EOT, CICS issues a write initial (TI) or the Input data is deblocked to ETX, ETB, RS, and US
equivalent (depending on the type of line). The characters. These characters are moved with the data but
programmable terminal response must be a read initial (TI) are not included in the data length. Characters such as NL
or the equivalent. (new line), CR (carriage return), LF (line feed), and EM (end
of message) are included as data in a CICS application
If the application program makes another output request, program.
CICS issues a write continue (TT) to that line. If the
application program makes an input request after it has
made an output request, CICS turns the line around with a
Teletypewriter programming
write reset (TR). (CICS does not recognize a read interrupt.)
The Teletypewriter (World Trade only) uses two different
To ensure that binary synchronous terminals (for example,
control characters for print formatting, as follows:
System/370, 1130, 2780) remain coordinated, CICS
processes the data collection or data transmission < carriage return (X'22' in ITA2
transaction on any line to completion, before polling other code or X'15' in EBCDIC)
terminals on that line.
_= line feed (X'28' in ITA2 code
The programmable terminal actions required for the above or X'25' in EBCDIC)
activity, with the corresponding user application program
The character < should always be used first; otherwise
commands and CICS actions, are summarized in Table 15.
following characters (data) may be printed while the type bar
is moving to the left.
Table 15. BTAM programmable terminal programming
User Application CICS1 Actions Programmable
Program Terminal Action Message format
Command
Message begin: To start a message on a new line at the
Read initial (TI) Write initial (TI)
left margin, the message text must begin with X'1517'
RECEIVE Read continue (TT) Write continue (TT)
(EBCDIC). CICS recognizes the X'17' and changes it to
X'25' (X'17' is an IDLE character).
SEND Read interrupt (RVI)2 Write reset (TR) or
Message body: To write several lines with a single
Read continue (TT)3 Write continue transmission, the lines must be separated by X'1525', or if
Write reset multiple blank lines are required, by X'152525...25'.

Write initial (TI) Read initial (TI) Message end before next input: To allow input of the next
message on a new line at the left margin, the preceding
SEND Write continue (TT) Read continue (TT) message must end with X'1517'. CICS recognizes X'15'
and changes the character following it to X'25'.
RECEIVE Write reset (TR)4 Read continue (TT)
Message end before next output: In the case of two or
Read initial (TI) Write initial (TI)
more successive output messages, the “message begin” and
1. CICS issues the macro shown, or, if the line is switched, the “message end” look the same; that is X'1517', except
the equivalent. The user-written programmable terminal for the last message (see above). To make the “message
program must issue the equivalent of the BTAM operation
end” of the preceding message distinguishable from the
shown.
“message begin” of the next message, the next to last
2. An RVI sequence is indicated by the DECFLAGS field of character of the “message end” must not be X'15'.
the data event control block (DECB) being set to X'02' and
a completion code of X'7F' being returned to the event
control block (ECB). Message length
3. The read continue is issued only if the EOT character is not
received on the read interrupt. Messages for teletypewriter terminals should not exceed a
length of about 3000 bytes or approximately 300 words.
4. Write reset is issued only for point-to-point terminals.

Automatically initiated transactions attached to a device

cause the message:
DFH25O3 AUTO OUTPUT HAS BEEN REQ,
PLEASE PREPARE TO RECEIVE
to be sent to the device, which must be prepared to receive
it.

Appendix D. Terminal control 359

Terminal control

Connection through VTAM Display device operations

Both the TWX Model 33/35 Common Carrier Teletypewriter
In addition to the standard terminal control commands for
Exchange and the WTTY Teletypewriter (World Trade only)
sending and receiving data, several commands and lists are
can be connected to CICS through BTAM, or through VTAM
provided for use with display devices such as the 3270.
using NTO.
The commands are:
If a device is connected through VTAM using NTO, the
protocols used are the same as for the 3767 logical unit, and Print displayed information (ISSUE PRINT)
the application program can make use of these protocols (for Copy displayed information (ISSUE COPY)
example, HANDLE CONDITION SIGNAL). However, the Erase all unprotected fields (ISSUE ERASEAUP)
data stream is not translated to a 3767 data stream but Handle input without data (RECEIVE)
remains as that for a TWX/WTTY. Handle attention identifiers (HANDLE AID).

The lists are:

Standard attention identifier list (DFHAID)
Standard attribute and printer control character list
(DFHBMSCA).

For devices with switchable screen sizes, the size of the

screen that can be used, and the size to be used for a given
transaction, are defined by CICS table generation. These
values can be obtained by means of the ASSIGN command,
described in “ASSIGN” on page 22.

The ERASE option should always be included in the first

SEND command, to clear the screen and format it according
to the transmitted data. This first SEND with ERASE also
selects the screen size to be used, as specified using the
RDO option SCRNSIZE, or in the TCT. If ERASE is omitted,
the screen size is the same as its previous setting, which
may be incorrect.

Use the CLEAR key outside of a transaction to set the

screen to its default size.

Print displayed information (ISSUE PRINT)

ISSUE PRINT prints displayed data on the first available
printer that is eligible to respond to a print request.

For a BTAM-supported 3270, this is a printer on the same

control unit.

For a 3270 logical unit or a 3650 host-conversational (3270)

logical unit, it is a printer defined by PRINTTO or ALTPRT in
the terminal control table TYPE=TERMINAL, by RDO, or by
a printer supplied by the autoinstall user program.

For a 3270-display logical unit with the PTRADAPT feature

(LUTYPE2 specified in TRMTYPE and PTRADAPT specified
in FEATURE in the terminal control table TYPE=TERMINAL)
used with a 3274 or 3276, it is a printer allocated by the
printer authorization matrix. See An Introduction to the IBM
3270 Information Display System.

For a 3790 (3270-display) logical unit, it is a printer allocated

by the 3790.

For a printer to be available, it must be in service and not

currently attached to a task.

360 CICS/ESA Application Programming Reference

Terminal control

For a BTAM printer to be eligible, it must be attached to the Handle input without data (RECEIVE)
same control unit as the display, must have a buffer capacity
equal to or greater than that of the display, and must have The RECEIVE command with no options causes input to
FEATURE=PRINT specified in the associated terminal take place and the EIB to be updated. However, data
control table TYPE=TERMINAL. received by CICS is not passed on to the application
program and is lost. A wait is implied. Two of the fields in
For a 3270 logical unit to be eligible, it must have been the EIB that are updated are described below.
specified by PRINTTO or ALTPRT in the terminal control
table TERMINAL=TYPE, by RDO, or by a printer supplied by Cursor position (EIBCPOSN): For every terminal
the autoinstall user program, and it must have the correct control (or BMS) input operation associated with a display
buffer capacity; FEATURE=PRINT is not necessary. If device, the screen cursor address (position) is placed in the
COPY is specified with ALTPRT or PRINTTO, the printer EIBCPOSN field in the EIB. The cursor address is in the
must be on the same control unit. form of a halfword binary value and remains until updated by
a new input operation.
If an ISSUE PRINT command is executed, the printer
involved must be owned by the same CICS system that Attention identifier (EIBAID): For every terminal control
owns the terminal that is running the transaction. (or BMS) input operation associated with a display device, an
attention identifier (AID) is placed in field EIBAID in the EIB.
For some 3270 displays, it is possible also to print the
The AID indicates which method the terminal operator has
displayed information without using CICS. See An
used to initiate the transfer of information from the device to
Introduction to the IBM 3270 Information Display System
CICS; for example, the ENTER key, a program function key,
manual.
the light pen, and so on. The field contents remain unaltered
until updated by a new input operation.
Copy displayed information (ISSUE COPY)
Field EIBAID can be tested after each terminal control (or
The ISSUE COPY command is used to copy the format and BMS) input operation to determine further processing, and a
data contained in the buffer of a specified terminal into the standard attention identifier list (DFHAID) is provided for this
buffer of the terminal that started the transaction. This purpose. Alternatively, the HANDLE AID command can be
command cannot be used for an LUTYPE2 connection. Both used to pass control to specified labels when the AIDs are
terminals must be attached to the same remote control unit. received.
The terminal whose buffer is to be copied is identified in the
TERMID option. If the terminal identifier is not valid, that is, EIBAID and EIBCPOSN are also updated at task initiation for
it does not exist in the TCT, then the TERMIDERR condition non-ATI tasks and after each terminal control and BMS input.
occurs. The copy function to be performed is defined by the
copy control character (CCC) specified in the CTLCHAR
option of the ISSUE COPY command.

The WAIT option of the ISSUE COPY command ensures that

the operation has been completed before control is returned
to the application program.

Erase all unprotected fields (ISSUE

ERASEAUP)
The ISSUE ERASEAUP command is used to erase all
unprotected fields of a 3270 buffer, by the following actions:
1. All unprotected fields are cleared to nulls (X'00').
2. The modified data tags (MDTs) in each unprotected field
are reset to zero.
3. The cursor is positioned to the first unprotected field.
4. The keyboard is restored.

The WAIT option of the ISSUE ERASEAUP command

ensures that the operation has been completed before
control is returned to the application program.

Appendix D. Terminal control 361

Terminal control

362 CICS/ESA Application Programming Reference

SAA resource recovery

Appendix E. SAA Resource Recovery

SAA Resource Recovery is the recovery element of the
Systems Application Architecture (SAA) Common
Programming Interface (CPI).

SAA Resource Recovery provides that architecture’s

alternative application programming interface (API) to EXEC
CICS SYNCPOINT and EXEC CICS SYNCPOINT
ROLLBACK functions in CICS/ESA. (See the SAA Common
Programming Interface-Resource Recovery Reference,
SC31-6821, for more details.)

CICS/ESA 3.2.1 and above supports only those SAA

Resource Recovery return codes that match existing EXEC
CICS commands. This leaves only two return codes:
RR_OK and RR_BACKED_OUT.

SRRCMT
Commit call (equivalent to EXEC CICS SYNCPOINT). The
return codes are:
RR_OK
RR_COMMITTED_OUTCOME_PENDING
RR_COMMITTED_OUTCOME_MIXED
RR_PROGRAM_STATE_CHECK
RR_BACKED_OUT
RR_BACKED_OUT_OUTCOME_PENDING
RR_BACKED_OUT_OUTCOME MIXED

Because of the restriction, these are replaced by:

RR_COMMITTED_OUTCOME_PENDING, RR_OK
RR_COMMITTED_OUTCOME_MIXED, RR_OK
RR_PROGRAM_STATE_CHECK, shown as abend code
ASP2
RR_BACKED_OUT_OUTCOME_PENDING,
RR_BACKED_OUT
RR_BACKED_OUT_OUTCOME MIXED,
RR_BACKED_OUT

SRRBACK
Backout call (equivalent to EXEC CICS SYNCPOINT
ROLLBACK). The return codes are:
RR_OK
RR_COMMITTED_OUTCOME_PENDING
RR_COMMITTED_OUTCOME_MIXED

Because of the restriction, all these are replaced by RR_OK.

SAA resource recovery

364 CICS/ESA Application Programming Reference

CPI Communications

Appendix F. Common Programming Interface Communications (CPI

Communications)
Common Programming Interface Communications (CPI
Communications) is the communication element of the
Systems Applications Architecture (SAA) Common
Programming Interface (CPI).

CPI Communications in CICS provides an alternative

application programming interface (API) to existing CICS
Advanced Program-to-Program Communications (APPC)
support. CPI Communications provides distributed
transaction processing (DTP) on APPC sessions and can be
used in assembler language, COBOL, PL/I, or C.

CPI Communications defines an API that can be used in

APPC networks that include multiple system platforms, where
the consistency of a common API is seen to be of benefit.

The CPI Communications interface can converse with

applications on any system that provides an APPC API. This
includes applications on CICS platforms. You may use
APPC API commands on one end of a conversation and CPI
Communications commands on the other. CPI
Communications requires specific information (side
information) to begin a conversation with a partner program.
CICS implementation of side information is achieved using
the partner resource which your system programmer is
responsible for maintaining.

The application’s calls to the CPI Communications interface

are resolved by link-editing it with the CICS CPI
Communications link-edit stub (DFHCPLC). You can find
further guidance information in the CICS/ESA System
Definition Guide.

CPI Communications language interfaces

The CPI Communications API is defined as a general call
interface. The interface is described in the SAA Common
Programming Interface Communications Reference manual.

CPI Communications

366 CICS/ESA Application Programming Reference

API restrictions

Appendix G. API restrictions for distributed program link

This appendix lists the API commands, indicating whether or not they are supported in a program running in a resource region
in response to a distributed program link command.

Summary of the restricted API commands

Table 16. Restricted API commands

ADDRESS .... ISSUE ....
ALLOCATE PURGE MESSAGE
ASSIGN .... RECEIVE ....
CONNECT PROCESS ROUTE
CONVERSE SEND ....
EXTRACT PROCESS SIGNOFF
FREE CONVID SIGNON
HANDLE AID WAIT TERMINAL

List of API commands

The following table summarizes the CICS API commands by functional area, indicating whether or not they are supported in a
program invoked by a distributed program link command. Generally, if the program issues a command that is not supported,
CICS returns an INVREQ condition, with a RESP2 value of 200.

Table 17 (Page 1 of 4). Summary of the CICS API by functional area

Functional area Command Supported?
Abend support ABEND YES
ASSIGN
ABCODE
ASRAINTRPT
ASRAPSW
ASRAREGS
ORGABCODE
HANDLE ABEND
APPC mapped communication ALLOCATE(APPC) NO
CONNECT PROCESS
CONVERSE
EXTRACT PROCESS
FREE CONVID
ISSUE
ABEND
CONFIRMATION
ERROR
PREPARE
SIGNAL

RECEIVE
SEND
WAIT CONVID
Note: The above APPC commands are restricted only when they refer to the principal facility.
Signon SIGNON NO
SIGNOFF
Batch data interchange ISSUE NO
commands ABORT QUERY
ADD RECEIVE
END REPLACE
ERASE SEND
NOTE WAIT

API restrictions

Table 17 (Page 2 of 4). Summary of the CICS API by functional area

Functional area Command Supported?
BMS commands ASSIGN NO
# Apar 72501
# Documentation for Apar 72501 added 3 Aug 1995 (TUCKER)

# COLOR PAGENUM
# DESTCOUNT PARTNPAGE
# INPARTN PARTNS
# LDCMNEM PARTNSET
# LDCNUM PS
#
# MAPCOLUMN
# MAPHEIGHT
# MAPLINE
# MAPWIDTH
# OPCLASS
PURGE MESSAGE
RECEIVE
MAP
PARTN
ROUTE
SEND
CONTROL
MAP
PAGE
PARTNSET
TEXT
TEXT MAPPED
TEXT NOEDIT
Built-in functions BIF DEEDIT YES
Condition handling HANDLE CONDITION YES
IGNORE CONDITION
PUSH HANDLE
POP HANDLE
Console support WRITE OPERATOR YES
Diagnostic services DUMP YES
ENTER
TRACE
Environmental services ASSIGN YES
# Apar 72501
# Documentation for Apar 72501 added 3 Aug 1995 (TUCKER)

# ABCODE OPERKEYS
| ABDUMP OPID
| ABPROGRAM ORGABCODE
# APPLID PRINSYSID
# ASRAINTRPT PROGRAM
#
# ASRAKEY RESSEC
# ASRAPSW RESTART
# ASRAREGS RETURNPROG
# ASRASPC STARTCODE
# ASRASTG SYSID
#
# CMDSEC TASKPRIORITY
# CWALENG TCTUALENG
# INITPARM TRANPRIORITY
# INITPARMLEN TWALENG
# NETNAME USERID

368 CICS/ESA Application Programming Reference

API restrictions

Table 17 (Page 3 of 4). Summary of the CICS API by functional area

Functional area Command Supported?
Environmental services ASSIGN NO
# (continued) Apar 72501
# Documentation for Apar 72501 added 3 Aug 1995 (TUCKER)

# ALTSCRNHT MSRCONTROL
# ALTSCRNWD NATLANGINUSE
# APLKYBD NEXTTRANSID
# APLTEXT NUMTAB
# BTRANS OPCLASS
#
# COLOR OPSECURITY
# DEFSCRNHT OUTLINE
# DEFSCRNWD PAGENUM
# DELIMITER PARTNPAGE
# DESTCOUNT PARTNS
#
# DESTID PARTNSET
# DESTIDLENG PS
# DSSCS QNAME
# DS327O SCRNHT
# EWASUPP SCRNWD
#
# EXTDS SIGDATA
# FACILITY SOSI
# FCI STATIONID
# GCHARS TELLERID
# GCODES TERMCODE
#
# GMMI TERMPRIORITY
# HILIGHT TEXTKYBD
# INPARTN TEXTPRINT
# KATAKANA UNATTEND
# LDCMNEM USERNAME
#
# LDCNUM USERPRIORITY
# MAPCOLUMN VALIDATION
# MAPHEIGHT
# MAPLINE
# MAPWIDTH
# Environmental services ADDRESS YES
# (continued) Apar 72501
# Documentation for Apar 72501 added 3 Aug 1995 (TUCKER)

# ACEE TWA
# COMMAREA
# CWA
# EIB
# TCTUA
File control DELETE YES
ENDBR
READ
READNEXT
READPREV

RESETBR
REWRITE
STARTBR
UNLOCK
WRITE
Interval control ASKTIME YES
CANCEL
DELAY
FORMATTIME
POST

RETRIEVE
START
WAIT EVENT
Journaling WRITE JOURNALNUM YES
WAIT JOURNALNUM
Monitoring MONITOR POINT YES

Appendix G. API restrictions for distributed program link 369

API restrictions

Table 17 (Page 4 of 4). Summary of the CICS API by functional area

Functional area Command Supported?
Program control LINK YES
LOAD
RELEASE
RETURN
XCTL
| Note: LINK, RETURN and XCTL do not support INPUTMSG.
Security QUERY SECURITY YES
Storage control FREEMAIN YES
GETMAIN
Syncpoint SYNCPOINT YES
Task control ASSIGN YES
TASKPRIORITY
CHANGE TASK
DEQ
ENQ
SUSPEND
WAIT EXTERNAL
Temporary storage DELETEQ TS YES
READQ TS
WRITEQ TS
Terminal control ASSIGN NO
FACILITY
CONVERSE
HANDLE AID
RECEIVE
SEND
WAIT TERMINAL
Transient data DELETEQ TD YES
READQ TD
WRITEQ TD

370 CICS/ESA Application Programming Reference

CVDA numeric values

| Appendix H. CVDA numeric values

| This appendix lists the CVDA values and their numeric equivalents for the relevant EXEC CICS commands in this book.
| |

| Table 18. CVDAs and | Table 19. CVDAs and

372 CICS/ESA Application Programming Reference

National language codes

| Appendix I. National language codes

| Language codes are held as one character for NATLANG | There are other IBM codes not supported by CICS.
| and NATLANGINUSE, and three characters for
| LANGUAGECODE and LANGINUSE (see under Suffix and
| IBM code below).
National language codes

374 CICS/ESA Application Programming Reference

BMS

Appendix J. BMS-related constants

This appendix contains the BMS-related standard attribute and printer control characters, a bit map for attributes, MSR control
value constants, and attention identifier constants.

The standard list DFHBMSCA makes it simpler to provide field attributes and printer control characters. Table 22 lists the
symbolic names for the various combinations of attributes and control characters. If you need combinations other than the
ones shown, you must generate them separately. To help you do this, see Table 23 on page 377 for a bit map of attributes.
To find the value of an attribute constant, see the 3274 Control Unit Reference Summary.

You can get the standard attribute and printer character control list by copying copybook DFHBMSCA into your application.
For COBOL users, it consists of a set of 01 statements that can be copied into the working storage section.
For C users, it is included in applications as follows:
#include "dfhbmsca.h"
For PL/I users, it consists of DECLARE statements defining elementary character variables.
For assembler-language users, the list consists of a set of EQU statements.

| You must use the symbolic name DFHDFT in the application structure to override a map attribute with the default. You can
| use a high value, such as X'FF', to reset the COLOR, HILIGHT, OUTLINE, PS, SOSI, or VALIDN attributes to their default
| values. On the other hand, to specify default values in a set attribute (SA) sequence in text build, you should use the symbolic
names DFHDFCOL, DFHBASE, or DFHDFHI.

Table 22 (Page 1 of 2). Standard attribute and printer control character list, DFHBMSCA
Constant Meaning
DFHBMPEM Printer end-of-message
DFHBMPNL Printer new-line
DFHBMPFF Printer form feed
DFHBMPCR Printer carriage return
DFHBMASK Autoskip
DFHBMUNP Unprotected
DFHBMUNN Unprotected and numeric
DFHBMPRO Protected
DFHBMBRY Bright
DFHBMDAR Dark
DFHBMFSE MDT set
DFHBMPRF Protected and MDT set
DFHBMASF Autoskip and MDT set
DFHBMASB Autoskip and bright
DFHBMPSO shift-out value X'0E'.
DFHBMPSI shift-in value X'0F'.
DFHBMEOF Field erased
DFHBMCUR Field containing cursor flagged
DFHBMEC Erased field containing cursor (COBOL only)
DFHBMFLG Flags (COBOL only)
DFHBMDET Field detected
DFHSA1 Set attribute (SA) order
DFHERROR Error code
DFHCOLOR1 Color
DFHPS1 Programmed symbols
DFHHLT1 Highlight
DFH32701 Base 3270 field attribute
DFHVAL Validation
DFHOUTLN Field outlining attribute code
DFHBKTRN Background transparency attribute code
DFHALL1 Reset all to defaults
DFHDFT Default
DFHDFCOL1 Default color
DFHBLUE Blue
DFHRED Red
DFHPINK Pink
DFHGREEN Green
DFHTURQ Turquoise
DFHYELLO Yellow
DFHNEUTR Neutral
DFHBASE1 Base programmed symbols
DFHDFHI1 Normal

BMS

Table 22 (Page 2 of 2). Standard attribute and printer control character list, DFHBMSCA
Constant Meaning
DFHBLINK Blink
DFHREVRS Reverse video
DFHUNDLN Underscore
DFHMFIL2 Mandatory fill
DFHMENT2 Mandatory enter
DFHMFE Mandatory fill and mandatory enter
DFHMT Trigger
DFHMFT Mandatory fill and trigger
DFHMET Mandatory enter and trigger
DFHMFET Mandatory fill and mandatory enter and trigger
DFHUNNOD Unprotected, nondisplay, nonprint, nondetectable, MDT
DFHUNIMD Unprotected, intensify, light-pen detectable, MDT
DFHUNNUM Unprotected, numeric, MDT
# Apar 67669
# Documentation for Apar 67669 added 7 Feb 1995 (TUCKER)

# DFHUNNUB Unprotected, numeric, intensify, intensify, light-pen detectable

DFHUNINT Unprotected, numeric, intensify, light-pen detectable, MDT
DFHUNNON Unprotected, numeric, nondisplay, nonprint, nondetectable, MDT
DFHPROTI Protected, intensify, light-pen detectable
DFHPROTN Protected, nondisplay, nonprint, nondetectable
DFHDFFR Default outline
DFHUNDER Underline
DFHRIGHT Right vertical line
DFHOVER Overline
DFHLEFT Left vertical line
DFHBOX Underline and right vertical and overline and left vertical
DFHSOSI SOSI=yes
DFHTRANS Background transparency
DFHOPAQ No background transparency
Note: 1 For text processing only. Use for constructing embedded set attribute orders in user text.
2 Cannot be used in set attribute orders.

376 CICS/ESA Application Programming Reference

BMS

Table 23. Bit map for attributes

prot a/n hi spd ndp mdt ebcd asci char
U 40 20 b (blank)
U Y C1 41 A
U Y C4 44 D
U Y Y C5 45 E
U H Y C8 48 H
U H Y Y C9 49 I
U Y 4C 3C <
U Y Y 4D 28 (
U N 50 26 &
U N Y D1 4A J
U N Y D4 4D M
U N Y Y D5 4E N
U N H Y D8 51 Q
U N H Y Y D9 52 R
U N Y 5C 2A *
U N Y Y 5D 29 )
P 60 2D - (hyphen)
P Y 61 2F /
P Y E4 55 U
P Y Y E5 56 V
P H Y E8 59 Y
P H Y Y E9 5A Z
P Y 6C 25 %
P Y Y 6D 5F _ (underscore)
P S F0 30 0
P S Y F1 31 1
P S Y F4 34 4
P S Y Y F5 35 5
P S H Y F8 38 8
P S H Y Y F9 39 9
P S Y 7C 40 @
P S Y Y 7D 27 ’

The attributes in the headings are:

prot = protected spd = selector pen detectable

a/n = automatic skip or numeric ndp = nondisplay print
hi = high intensity mdt = modified data tag

The hexadecimal codes in the headings are:

ebcd = extended binary-coded decimal interchange code

asci = American National Standard Code for Information Interchange
char = graphic character equivalent to hex code

The characters in the body of the above table mean the following:

H = High N = Numeric S = Automatic skip

P = Protected U = Unprotected Y = Yes

Magnetic slot reader (MSR) control value constants, DFHMSRCA

A selection of MSR control value constants has been created for CICS and stored in copybook DFHMSRCA. The patterns are
stored as named constants that can be loaded by simple application program commands. Provision of such constants saves
the programmer from having to build a commonly used bit pattern whenever it is required.

MSR control byte values

A selection of MSR control byte values has been created for CICS and stored in the copybook DFHMSRCA. Table 24 on
page 378 shows the meaning of each bit. The constants supplied in DFHMSRCA are listed in Table 25 on page 378.

Appendix J. BMS-related constants 377

BMS

Table 24. MSR control byte values

Byte (purpose) Bit Value Meaning
1 (STATE MASK) 0 USER User mode. Turn the yellow
light on if the same bit is on
If a bit is on in the STATE MASK byte, the state it represents is adopted by the
in STATE VALUE.
device if the corresponding bit is also on in the STATE VALUE byte.
1 LOCK Locked/Unlocked. If locked,
MSR input is inhibited.
2 AUTO Autoenter on/off. If set on,
any card read by the MSR
causes an ENTER
operation. If off, only a
secure card causes an
ENTER.
3 Ai1S Suppress audible alarm 1.
4 Ai2S Suppress audible alarm 2.
2 (STATE VALUE)
Modifies state to on or off if the corresponding bit is set on in STATE MASK.
3 (INDICATOR MASK) 0 Light 1 (Green)
1 Light 2 (Yellow)
Performs a similar function to STATE MASK, but for indicators.
2 Light 3 (Red)
3 Audible Alarm 1 (Long buzz)
4 Audible Alarm 2 (Short buzz)
4 (INDICATOR VALUE)
Performs a similar function to STATE VALUE.

Table 25. Standard list DFHMSRCA

Constant Meaning
DFHMSRST MSR reset. All lights and buzzers off. MSR available for input.
DFHMSCON Transaction ready for more input. Green and yellow on; emit short buzz; IN PROCESS (user) mode set.
DFHMSFIN Input complete. Green on; emit short buzz; IN PROCESS mode reset.
DFHMSALR Operator alert. Green, yellow, and red on; emit long buzz; IN PROCESS mode reset.
DFHMSALS Operator alert. Green, yellow, and red on; emit long buzz; IN PROCESS mode set.
DFHMSIPY IN PROCESS state set. Yellow on.
DFHMSIPN IN PROCESS state reset.
DFHMSLKY MSR operation inhibited. Yellow on.
DFHMSLKN MSR input allowed. Green on. Yellow on.
DFHMSAEY MSR autoenter on. Yellow on.
DFHMSAEN MSR autoenter off. Yellow on.
DFHMSLBN Long buzzer suppressed. Yellow on.
DFHMSLBY Long buzzer permitted. Yellow on.
DFHMSSBN Short buzzer suppressed. Yellow on.
DFHMSSBY Short buzzer permitted. Yellow on.
DFHMSNOP Leave all MSR settings unchanged.

378 CICS/ESA Application Programming Reference

BMS

Attention identifier constants, DFHAID

The standard attention identifier list, DFHAID, simplifies testing the contents of the EIBAID field. Table 26 shows the symbolic
name for the attention identifier (AID) and the corresponding 3270 function.

You can get a copy of the list by copying DFHAID into your application program. For COBOL users, it consists of a set of 01
statements that must be copied into the working-storage section. For C users, it consists of a series of defined constants. For
PL/I users, it consists of DECLARE statements defining elementary character variables.

Table 26. Standard list DFHAID

Constant Meaning
DFHENTER ENTER key
DFHCLEAR CLEAR key
DFHPA1–DFHPA3 PA1–PA3 keys
DFHPF1–DFHPF24 PF1–PF24 keys
DFHOPID OPERID or MSR
DFHMSRE Extended (standard) MSR
DFHTRIG Trigger field
DFHPEN SELECTOR PEN or CURSOR SELECT key
DFHCLRP CLEAR PARTITION key
DFHSTRF Structured field pseudo-AID.
Note: DFHCLRP and DFHSTRF do not apply to minimum function BMS.

Appendix J. BMS-related constants 379

BMS

380 CICS/ESA Application Programming Reference

BMS macro summary

Appendix K. BMS macro summary

This appendix contains the syntax of each BMS macro,
separating the various operands and options into those ──┬────────┬──DFHMSD TYPE=FINAL──"
└─mapset─┘
appropriate to minimum, standard, and full BMS.

| When coding, you should have the title in column 1, the

“mapset” is optional, but if used it must be the same as that
| macro in column 10, continuation lines should have * in
on the DFHMSD macro that began the mapset definition.
| column 72 and continue on column 16 on the next line.

For more information about BMS, see the CICS/ESA

Application Programming Guide. Partition set definition
Partitions are defined by coding the macros DFHPSD
Mapset, map, and field definition (partition set definition) and DFHPDI (partition definition).
Each partition definition must be part of a partition set
You should ensure that the names of maps, and names of definition.
fields within a mapset (or within multiple mapsets that are
copied into one application program) are unique. Maps and Partition set definition macro (DFHPSD)
mapsets must not have the same name.
Each partition set definition contains a single DFHPSD macro
Before CICS can load a physical map, you must define a followed by one or more DFHPDI macros, and ending with a
physical map using an RDO transaction with the MAPSET partition set definition TYPE=FINAL.
attribute.
| Before CICS can load a physical map, you must define a
| An alternative to defining maps using RDO is to use the | physical map using an RDO transaction with the MAPSET
| program autoinstall exit to create the definition when the | attribute.
| mapset is first used. (For programming information about the
| autoinstall user program, see the CICS/ESA Customization | An alternative to defining maps using RDO is to use the
| Guide.) | program autoinstall exit to create the definition when the
| mapset is first used. (For programming information about the
You assemble a BMS mapset definition to generate either a | autoinstall user program, see the CICS/ESA Customization
symbolic description map or a physical map. The CICS/ESA | Guide.)
System Definition Guide tells you how to assemble and
catalog the maps.
Partition definition macro (DFHPDI)
Mapset definition macro (DFHMSD) A partition set contains one or more partitions. Each partition
is defined by coding a partition definition macro.
The DFHMSD macro defines a mapset.

Ending a partition set definition

Map definition macro (DFHMDI)
A partition set definition ends with a macro of the form:
The DFHMDI macro defines a map within the mapset defined
by the previous DFHMSD macro. A map contains zero or
more fields. ──┬──────────┬──DFHPSD TYPE=FINAL──"
└─partnset─┘

Field definition macro (DFHMDF)

The PARTNSET name (if specified) must match that
The DFHMDF macro defines a field within a map defined by specified on the DFHPSD macro that started the partition set
the previous DFHMDI macro. definition.

Ending a mapset definition

A mapset definition ends with a macro of the form:

BMS macro summary

Field groups
Very often, an output data display field has to contain several
subfields, all sharing the same display attributes, and each of
which might have to be modified separately. At output,
subfields that have not been modified by the program can
adopt default data values from the output map. For example,
a display can include a date field of a “day” subfield, “month”
subfield, and “year” subfield. The contents of the year
subfield remain constant over a relatively long period; its
value can safely be taken from a map. However, the day
value and month value must be updated regularly. Similarly,
on input the terminal operator can enter data in each subfield
separately.

You use the GRPNAME operand to define a group of

subfields that combine to produce a field. The start of the
group is indicated by a DFHMDF macro with the GRPNAME
operand. This operand defines the first subfield, and
specifies the attributes and name of the group. It is followed
by other DFHMDF macros, one for each of the other
subfields. Each of these must specify the group name, but
cannot specify attribute values. The definition of the group is
terminated by a DFHMDF macro that specifies a different
group name, by one that specifies no group name, or by a
DFHMDI or DFHMSD macro.

Briefly, a group of fields in a map would appear as follows in

the map definition:

MAPSET DFHMSD....
.
.
MAP DFHMDI....
.
.
DD DFHMDF GRPNAME=DATE,POS=4O,
LENGTH=2,ATTRB=...
.
MM DFHMDF GRPNAME=DATE,POS=46,
LENGTH=2
.
YY DFHMDF GRPNAME=DATE,POS=52,
LENGTH=2
.
FIELD DFHMDF LENGTH=5,COLOR=GREEN,...
DFHMSD TYPE=FINAL

The POS operand specifies the position of the attribute byte

of the field even though subfields of a group, other than the
first, do not have attributes. If the subfields are positioned
contiguously with no intervening blanks, the POS of the
second and succeeding subfields must specify the position of
the last character of the previous subfield.

382 CICS/ESA Application Programming Reference

DFHMDF

Command syntax

┌─,──────────────────────────────────────────────────────────────┐
──┬─────┬──DFHMDF───*┬──────────────────────────────────────────────────────────────┬┴──"
└─fld─┘ ├─POS=─┬─number────────┬───────────────────────────────────────┤
│ └─(line,column)─┘ │
├─LENGTH=number────────────────────────────────────────────────┤
├─JUSTIFY=(─┬───────┬──┬──────────────┬─)──────────────────────┤
│ ├─LEFT──┤ └─,─┬─BLANK─┬──┘ │
│ └─RIGHT─┘ └─ZERO──┘ │
├─┬─INITIAL='char-data'───────┬────────────────────────────────┤
│ ├─XINIT=hex-data────────────┤ │
(1) ─┘
│ └─GINIT='DBCS-characters'── │
│ ┌─ASKIP────────────┐ │
├─ATTRB=(─┼──────────────────┼──┬──────────────────────────┬─)─┤
│ ├─PROT─────────────┤ │ ┌──
─────────┐ │ │
│ └─UNPROT──┬──────┬─┘ └─,─┬─BRT──┬───*┬───────┬┴──┘ │
│ └─,NUM─┘ ├─NORM─┤ ├─,DET──┤ │
│ └─DRK──┘ ├─,IC───┤ │
│ └─,FSET─┘ │
│ ┌─DEFAULT─┐ │
├─COLOR=─┼─────────┼───────────────────────────────────────────┤
│ └─color───┘ │
│ ┌─BASE─┐ │
├─PS=─┴─psid─┴─────────────────────────────────────────────────┤
│ ┌─OFF───────┐ │
├─HILIGHT=─┼───────────┼───────────────────────────────────────┤
│ ├─BLINK─────┤ │
│ ├─REVERSE───┤ │
│ └─UNDERLINE─┘ │
│ ┌─,───────────┐ │
*
├─VALIDN=(──┬───────────┬┴─)───────────────────────────────────┤
│ ├─MUSTFILL──┤ │
│ ├─MUSTENTER─┤ │
│ ├─TRIGGER───┤ │
# │ └─USEREXIT──┘ │
├─GRPNAME=group-name───────────────────────────────────────────┤
├─OCCURS=number────────────────────────────────────────────────┤
├─PICIN='value'────────────────────────────────────────────────┤
├─PICOUT='value'───────────────────────────────────────────────┤
├─OUTLINE=─┬─BOX─────────────┬─────────────────────────────────┤
│ │ ┌─,───────┐ │ │
│ └─(──*┬───────┬┴─)─┘ │
│ ├─LEFT──┤ │
│ ├─RIGHT─┤ │
│ ├─OVER──┤ │
│ └─UNDER─┘ │
│ ┌─NO──┐ │
├─SOSI=─┼─────┼────────────────────────────────────────────────┤
│ └─YES─┘ │
│ ┌─YES─┐ │
├─TRANSP=─┼─────┼──────────────────────────────────────────────┤
│ └─NO──┘ │
└─CASE=MIXED───────────────────────────────────────────────────┘
Notes:
1 DBCS characters start with a shift-out character X'0E' and end with a shift-in character X'0F'.

The DFHMDF macro defines a field within a map defined by # Apar 91113 reroute of 90736
the previous DFHMDI macro. A map contains zero or more
# Documentation for Apar 91113 added 12/02/97
fields.

| “fld” is the name (1–30 characters) of the field. You should, # For more information about defining field names, see the
| however, refer to your compiler manual to make sure that # CICS/ESA Application Programming Guide. If “fld” is
| there are no other restrictions on the length.

Appendix K. BMS macro summary 383

DFHMDF

omitted, application programs cannot access the field to recognized as detectable by BMS, DET
change its attributes or alter its contents. For an output map, must also be specified.
omitting the field name may be appropriate when the INITIAL
DET specifies that the field is potentially
operand is used to specify the contents of a field. If a field
detectable.
name is specified and the map that includes the field is used
in a mapping operation, nonnull data supplied by the user The first character of a 3270 detectable field
overlays data supplied by initialization (unless default data must be one of the following:
only is being written). ? > & blank

The performance of input mapping operations is optimized if If ? or >, the field is a selection field; if & or
DFHMDF macros are arranged in numerical order of the blank, the field is an attention field. (See An
POS operand. Introduction to the IBM 3270 Information
Display System for further details about
You cannot define more than 1023 named fields for a detectable fields.)
COBOL, C, or PL/I input/output map. A field for which BRT is specified is
potentially detectable to the 3270, because
You should ensure that the names of maps, and names of
of the 3270 attribute character bit
fields within a mapset (or within multiple mapsets that are
assignments, but is not recognized as such
copied into one application program) are unique. Maps and
by BMS unless DET is also specified.
mapsets must not have the same name.
DET and DRK are mutually exclusive.
Before CICS can load a physical map, you must define a
If DET is specified for a field on a map with
physical map using an RDO transaction with the MAPSET
MODE=IN, only one data byte is reserved
attribute.
for each input field. This byte is set to
X'00', and remains unchanged if the field is
DFHMDF operands not selected. If the field is selected, the
byte is set to X'FF'.
ATTRB
This operand applies only to 3270 data stream devices; No other data is supplied, even if the field is
it is ignored for other devices, except that ATTRB=DRK a selection field and the ENTER key has
is honored for the SCS Printer Logical Unit. It is also been pressed.
ignored (except for ATTRB=DRK) if the NLEOM option is If the data in a detectable field is required,
specified on the SEND MAP command for transmission all of the following conditions must be
to a 3270 printer. In particular, ATTRB=DRK should not fulfilled:
be used as a method of protecting secure data on output
1. The field must begin with one of the
on non-3270, non-SCS printer terminals. Refer to An
following characters:
Introduction to the IBM 3270 Information Display System
for further information. ? > & blank
If ATTRB is specified within a group of fields, it must be and DET must be specified in the
specified in the first field entry. A group of fields output map.
appears as one field to the 3270. Therefore, the ATTRB 2. The ENTER key (or some other
specification refers to all of the fields in a group as one attention key) must be pressed after the
field rather than as individual fields. It specifies field has been selected, although the
device-dependent characteristics and attributes, such as ENTER key is not required for
the capability of a field to receive data, or the intensity to detectable fields beginning with & or a
be used when the field is output. It could however, be blank.
used for making an input field nondisplay for secure
entry of a password from a screen. For input map fields, 3. DET must not be specified for the field
DET and NUM are the only valid options; all others are in the input map. DET must, however,
ignored. be specified in the output map. For
more information about BMS support of
ASKIP is the default and specifies that data cannot the light pen, see the CICS/ESA
be keyed into the field and causes the Application Programming Guide.
cursor to skip over the field.
DRK specifies that the field is
BRT specifies that a high-intensity display of the nonprint/nondisplay. DRK cannot be
field is required. Because of the 3270 specified if DET is specified.
attribute character bit assignments, a field
FSET specifies that the modified data tag (MDT)
specified as BRT is also potentially
for this field should be set when the field is
detectable. However, for the field to be
sent to a terminal.

384 CICS/ESA Application Programming Reference

DFHMDF

Specification of FSET causes the 3270 to katakana display. It should not be specified if the field
treat the field as though it has been may contain valid katakana characters.
modified. On a subsequent read from the
COLOR
terminal, this field is read, whether or not it
indicates the individual color, or the default color for the
has been modified. The MDT remains set
mapset (where applicable).
until the field is rewritten without
ATTRB=FSET, or until an output mapping The valid colors are blue, red, pink, green, turquoise,
request causes the MDT to be reset. yellow, and neutral.
Either of two sets of defaults may apply The COLOR operand is ignored unless the terminal
when a field to be displayed on a 3270 is supports color, as indicated by FEATURE in the terminal
being defined but not all parameters are control table TYPE=TERMINAL, or by the RDO option
specified. If no ATTRB parameters are COLOR.
specified, ASKIP and NORM are assumed.
GINIT
If any parameter is specified, UNPROT and
specifies constant or default data for an output field.
NORM are assumed for that field unless
GINIT is used to specify data in DBCS character strings,
overridden by a specified parameter.
which must be enclosed by SO (shift out, X'0E') and SI
IC specifies that the cursor is to be placed in (shift in, X'0F') characters. When GINIT is specified,
the first position of the field. The IC the length must be even and is the number of bytes in
attribute for the last field for which it is the string (that is, not the number of DBCS characters).
specified in a map is the one that takes #
effect. If not specified for any fields in a Apar 69549
map, the default location is zero. Specifying # Documentation for Apar 69549 added 13 Apr 1995
IC with ASKIP or PROT causes the cursor # (TUCKER)
to be placed in an unkeyable field.
This option can be overridden by the # If a graphic data type (PS=X'F8') is used, and the
CURSOR option of the SEND MAP # language is COBOL2, a PIC G is generated. Only one
command that causes the write operation. of GINIT, INITIAL, or XINIT may be specified.
NORM specifies that the field intensity is to be GRPNAME
normal. is the name used to generate symbolic storage
NUM ensures that the data entry keyboard is set definitions and to combine specific fields under one
to numeric shift for this field unless the group name. The same group name must be specified
operator presses the alpha shift key, and | for each field that is to belong to the group. The length
prevents entry of nonnumeric data if the | of the name is up to 30 characters though you should
Keyboard Numeric Lock feature is installed. | refer to your compiler manual to make sure that there
| are no other restrictions on the length.
PROT specifies that data cannot be keyed into the
# Apar PQ27428
field.
If data is to be copied from one device to # Documentation for Apar PQ27428 added 24/06/99
another attached to the same 3270 control
unit, the first position (address 0) in the # For more information on defining the group name, see
buffer of the device to be copied from must # the CICS/ESA Application Programming Guide. The
not contain an attribute byte for a protected # same rules apply to group names.
field. Therefore, when preparing maps for If this operand is specified, the OCCURS operand
3270s, ensure that the first map of any page cannot be specified.
does not contain a protected field starting at
position 0. The fields in a group must follow on; there can be gaps
between them, but not other fields from outside the
UNPROT specifies that data can be keyed into the group. A field name must be specified for every field
field. that belongs to the group, and the POS operand must
CASE also be specified to ensure that the fields follow each
specifies that the field contains both uppercase and other. All the DFHMDF macros defining the fields of a
lowercase data that is to be converted to uppercase if group must be placed together, and in the correct order
FEATURE=KATAKANA has been included in the (ascending numeric order of the POS value).
terminal definition. For example, the first 20 columns of the first six lines of
This should be specified if a field is known to contain a map can be defined as a group of six fields, as long
lowercase Latin characters but may be displayed on a as the remaining columns on the first five lines are not
defined as fields.

Appendix K. BMS macro summary 385

DFHMDF

The ATTRB operand specified on the first field of the BLANK specifies that blanks are to be inserted in
group applies to all of the fields within the group. any unfilled positions in an input field.

HILIGHT ZERO specifies that zeros are to be inserted in any

specifies the default highlighting attribute for all fields in unfilled positions in an input field.
all maps in a mapset.
LEFT and RIGHT are mutually exclusive, as are BLANK
OFF is the default and indicates that no and ZERO. If certain arguments are supplied but others
highlighting is used. are not, assumptions are made as follows:

BLINK specifies that the field must blink. Specified Assumed

REVERSE specifies that the character or field is LEFT BLANK

displayed in reverse video, for example, on RIGHT ZERO
a 3278, black characters on a green BLANK LEFT
background. ZERO RIGHT
UNDERLINE If JUSTIFY is omitted, but the NUM attribute is specified,
specifies that a field is underlined. RIGHT and ZERO are assumed. If JUSTIFY is omitted,
but attributes other than NUM are specified, LEFT and
The HILIGHT operand is ignored unless the terminal BLANK are assumed.
supports highlighting, as indicated by the appropriate
RDO program definition or by FEATURE in the terminal Note: If a field is initialized by an output map or
control table TYPE=TERMINAL. contains data from any other source, data that is typed
as input overwrites only the equivalent length of the
INITIAL (or XINIT) existing data; surplus existing data remains in the field
specifies constant or default data for an output field. and could cause unexpected interpretation of the new
INITIAL is used to specify data in character form; XINIT data.
is used to specify data in hexadecimal form.
LENGTH
For fields with the DET attribute, initial data that begins specifies the length (1–256 bytes) of the field or group of
with one of the following characters: fields. This length should be the maximum length
? > & blank required for application program data to be entered into
should be supplied. the field; it should not include the one-byte attribute
indicator appended to the field by CICS for use in
The number of characters that can be specified in the | subsequent processing. The length of each individual
INITIAL operand is restricted to the continuation | subfield within a group must not exceed 256 bytes.
limitation of the assembler to be used or to the value LENGTH can be omitted if PICIN or PICOUT is
specified in the LENGTH operand (whichever is the specified, but is required otherwise. You can specify a
smaller). length of zero only if you omit the label (field name) from
Hexadecimal data is written as an even number of the DFHMDF macro. That is, the field is not part of the
hexadecimal digits, for example, XINIT=C1C2. If the application data structure and the application program
number of valid characters is smaller than the field cannot modify the attributes of the field. You can use a
length, the data is padded on the right with blanks. For field with zero length to delimit an input field on a map.
example, if LENGTH=3, XINIT=C1C2 results in an initial The map dimensions specified in the SIZE operand of
field of ‘AB’. the DFHMDI macro defining a map can be smaller than
If hexadecimal data is specified that corresponds with the actual page size or screen size defined for the
line or format control characters, the results are terminal.
unpredictable. The XINIT operand should therefore be If the LENGTH specification in a DFHMDF macro
used with care. Only one of GINIT, INITIAL, or XINIT causes the map-defined boundary on the same line to
may be specified. be exceeded, the field on the output screen is continued
JUSTIFY by wrapping.
specifies the field justifications for input operations. This OCCURS
operand is ignored for TCAM-supported 3600 and 3790, specifies that the indicated number of entries for the field
and for VTAM-supported 3600, 3650, and 3790 are to be generated in a map, and that the map
terminals, because input mapping is not available. definition is to be generated in such a way that the fields
LEFT specifies that data in the input field is are addressable as entries in a matrix or an array. This
left-adjusted. permits several data fields to be addressed by the same
name (subscripted) without generating a unique name
RIGHT specifies that data in the input field is for each field.
right-adjusted.

386 CICS/ESA Application Programming Reference

DFHMDF

OCCURS and GRPNAME are mutually exclusive; that is, O1 MAPI.

OCCURS cannot be used when fields have been O2 F1L PIC S9(4) COMP.
defined under a group name. If this operand is omitted, O2 F1A PIC X.
a value of OCCURS=1 is assumed. O2 FILLER REDEFINES F1A.
O3 F1F PIC X.
OUTLINE O2 F1I PIC X(3O).
allows lines to be included above, below, to the left, or to O2 FILLER PIC X.
the right of a field. You can use these lines in any O2 F2L PIC S9(4) COMP.
combination to construct boxes around fields or groups O2 F2A PIC X.
of fields. O2 FILLER REDEFINES F2A.
O3 F2F PIC X.
PICIN (COBOL and PL/I only) O2 F2I PIC X(1O).
specifies a picture to be applied to an input field in an IN O2 FILLER PIC X.
or INOUT map; this picture serves as an editing O2 F3L PIC S9(4) COMP.
specification that is passed to the application program, O2 F3A PIC X.
thus permitting the user to exploit the editing capabilities O2 FILLER REDEFINES F3A.
of COBOL or PL/I. BMS checks that the specified O3 F3F PIC X.
characters are valid picture specifications for the O2 F3I PIC 9999V99.
O2 FILLER PIC X.
language of the map.
O1 MAPO REDEFINES MAPI.
However, the validity of the input data is not checked by O2 FILLER PIC X(3).
BMS or the high-level language when the map is used, O2 F1O PIC X(3O).
so any desired checking must be performed by the O2 FILLER PIC X.
application program. The length of the data associated O2 FILLER PIC X(3).
with “value” should be the same as that specified in the O2 F2O PIC $$$,$$O.OO.
LENGTH operand if LENGTH is specified. If both PICIN O2 FILLER PIC X.
and PICOUT (see below) are used, an error message is O2 FILLER PIC X(3).
produced if their calculated lengths do not agree; the O2 F3O PIC ZZ9.99.
shorter of the two lengths is used. If PICIN or PICOUT O2 FILLER PIC X.
is not coded for the field definition, a character definition
of the field is automatically generated regardless of other
operands that are coded, such as ATTRB=NUM.
As an example, assume the following map definition is
created for reference by a COBOL application program:
MAPX DFHMSD TYPE=DSECT,
LANG=COBOL,
MODE=INOUT
MAP DFHMDI LINE=1,COLUMN=1,
SIZE=(1,8O)
F1 DFHMDF POS=O,LENGTH=3O
F2 DFHMDF POS=4O,LENGTH=1O,
PICOUT='$$$,$$O.OO'
F3 DFHMDF POS=6O,LENGTH=6,
PICIN='9999V99',
PICOUT='ZZ9.99'
DFHMSD TYPE=FINAL
This generates the following DSECT:

Appendix K. BMS macro summary 387

DFHMDF

The valid picture values for COBOL input maps are: # The currency sign represented by the picture
A P S V X 9 / and ( # symbol is defined in the same clause. For
# example:
The valid picture values for PL/I input maps are:
# SPECIAL NAMES.
A B E F G H I K M P R S T V # CURRENCY SIGN IS '$' WITH PICTURE SYMBOL '$'.
X Y and Z # CURRENCY SIGN IS '£' WITH PICTURE SYMBOL '£'.
# CURRENCY SIGN IS 'EUR' WITH PICTURE SYMBOL '#'.
1 2 3 6 7 8 9 / + - , . _
$ and (
# Apar PQ14850 # WORKING STORAGE SECTION.
# O1 USPRICE PIC $99.99.
# Documentation for Apar PQ14850 added 09/07/98 # O1 UKPRICE PIC £99.99.
# O1 ECPRICE PIC #99.99.
# For PL/I, a currency symbol can be used as a picture # LENGTH must be specified when PICOUT
# character. The symbol can be any sequence of # specifies a COBOL picture containing a currency
# characters enclosed in < and >, for example <DM>. # symbol that will be replaced by a currency sign
Refer to the appropriate language reference manual for # of length greater than 1.
the correct syntax of the PICTURE attribute.
POS
PICOUT (COBOL and PL/I only) specifies the location of a field. This operand specifies
is similar to PICIN, except that a picture to be applied to the individually addressable character location in a map
an output field in the OUT or INOUT map is generated. at which the attribute byte that precedes the field is
positioned.
Note: The valid picture values for COBOL output maps
are: number specifies the displacement (relative to zero)
A B E P S V X Z O 9 , . + - $ from the beginning of the map being
CR DB / and ( defined.
The valid picture values for PL/I output maps are: (line,column)
specify lines and columns (relative to one)
A B E F G H I K M P R S T V
X Y and Z within the map being defined.
The location of data on the output medium
1 2 3 6 7 8 9 / + - , . _ $ | is also dependent on DFHMDI operands.
CR DB and (
The first position of a field is reserved for an
# Apar PQ14850 attribute byte. When supplying data for
# Documentation for Apar PQ14850 added 09/07/98 input mapping from non-3270 devices, the
input data must allow space for this attribute
byte. Input data must not start in column 1
# For PL/I, a currency symbol can be used as a picture
but may start in column 2.
# character. The symbol can be any sequence of
# characters enclosed in < and >, for example <DM>. The POS operand always contains the
location of the first position in a field, which
Refer to the appropriate language reference manual for
is normally the attribute byte when
the correct syntax of the PICTURE attribute.
communicating with the 3270. For the
Note: second and subsequent fields of a group,
# Apar PQ21323 the POS operand points to an assumed
attribute-byte position, ahead of the start of
# Documentation for Apar PQ21323 added the data, even though no actual attribute
# 11/12/98 byte is necessary. If the fields follow on
immediately from one another, the POS
# COBOL supports multiple currency signs and operand should point to the last character
# multi-character currency signs in PICTURE position in the previous field in the group.
# specifications.
When a position number is specified that
# The default currency picture symbol is the dollar represents the last character position in the
# sign ($),which represents the national currency 3270, two special rules apply:
# symbol; for example the dollar ($), the pound (£),
ATTRIB=IC should not be coded. The
# or the yen (¥).
cursor can be set to location zero by
# The default currency picture symbol may be using the CURSOR option of a SEND
# replaced by a different currency picture symbol MAP, SEND CONTROL, or SEND
# that is defined in the SPECIAL NAMES clause. TEXT command.

388 CICS/ESA Application Programming Reference

DFHMDF

If the field is to be used in an output move the cursor from an empty field raises
mapping operation with the INHIBIT INPUT condition
MAP=DATAONLY on the SEND MAP
TRIGGER specifies that this field is a trigger field.
command, an attribute byte for that field
Trigger fields are discussed in the
must be supplied in the symbolic map
CICS/ESA Application Programming Guide.
data structure by the application
# Apar PQ12071
program.

PS specifies that programmed symbols are to be used. This # Documentation for Apar PQ12071
overrides any PS operand set by the DFHMDI macro or # added 12/03/98
the DFHMSD macro.
# USEREXIT
BASE is the default and specifies that the base # specifies that this field is to be processed by
symbol set is to be used. # the BMS global user exits, XBMIN and
psid specifies a single EBCDIC character, or a # XBMOUT, if this field is received or
hexadecimal code of the form X'nn', that # transmitted in a 3270 datastream when the
identifies the set of programmed symbols to # respective exit is enabled. For further
be used. # information on the use of the BMS global
# user exits, refer to the CICS/ESA
The PS operand is ignored unless the terminal supports # Customization Guide.
programmed symbols, as indicated by
PROGSYMBOLS(YES) on the RDO TYPETERM # The MUSTFILL, MUSTENTER and TRIGGER
definition, or by FEATURE in the terminal control table # specifications are valid only for terminals that support the
TYPE=TERMINAL. # field validation extended attribute, otherwise they are
# ignored. The USEREXIT specification applies to all
SOSI # 3270 devices.
indicates that the field may contain a mixture of EBCDIC
and DBCS data. The DBCS subfields within an EBCDIC # Note: The USEREXIT specification is totally
field are delimited by SO (shift out) and SI (shift in) # unconnected with the field validation extended
characters. SO and SI both occupy a single screen # attribute as defined in the 3270 datastream
position (normally displayed as a blank). They can be # architecture.
included in any non-DBCS field on output, if they are The VALIDN operand is ignored unless the terminal
correctly paired. The terminal user can transmit them supports validation, as indicated by VALIDATION(YES)
inbound if they are already present in the field, but can option on the RDO TYPETERM definition, or by
add them to an EBCDIC field only if the field has the FEATURE in the terminal control table
SOSI attribute. TYPE=TERMINAL.
TRANSP XINIT
determines whether the background of an alphanumeric see INITIAL, earlier in the list. Only one of GINIT,
field is transparent or opaque, that is, whether an INITIAL, or XINIT may be specified.
underlying (graphic) presentation space is visible
between the characters.

VALIDN
specifies:

# the validation that is to be used on an 8775 terminal

# that this field is to be processed by the BMS global
# user exits

This overrides any VALIDN operand on the DFHMDI

macro or the DFHMSD macro.

MUSTFILL specifies that the field must be filled

completely with data. An attempt to move
the cursor from the field before it has been
filled, or to transmit data from an incomplete
field, raises the INHIBIT INPUT condition
MUSTENTER
specifies that data must be entered into the
field, though need not fill it. An attempt to

Appendix K. BMS macro summary 389

DFHMDI

Function
Map definition.

Command syntax
Minimum BMS:

┌─,─────────────────────────┐ ┌─,───────────────────────────────┐
*┬─────────────────────────┬┴───*┬───────────────────────────────┬┴──"
──map──DFHMDI───
├─SIZE=(line,column)──────┤ ├─PS=─┬─BASE─┬──────────────────┤
├─TERM=type───────────────┤ │ └─psid─┘ │
# │ ┌─,────────┐ │ │ ┌─,───────────┐ │
# *
├─CTRL=(──┬────────┬┴─)───┤ *
├─VALIDN=(──┬───────────┬┴─)────┤
# │ ├─PRINT──┤ │ │ ├─MUSTFILL──┤ │
# │ ├─length─┤ │ │ ├─MUSTENTER─┤ │
# │ ├─FREEKB─┤ │ │ ├─TRIGGER───┤ │
# │ ├─ALARM──┤ │ │ └─USEREXIT──┘ │
│ └─FRSET──┘ │ ├─COLUMN=number─────────────────┤
│ ┌─NO──────┐ │ ├─LINE=number───────────────────┤
├─EXTATT=─┼─────────┼─────┤ ├─FIELDS=NO─────────────────────┤
│ ├─MAPONLY─┤ │ │ ┌─,────────────┐ │
│ └─YES─────┘ │ ├──*MAPATTS=(attr)┴──────────────┤
│ ┌─DEFAULT─┐ │ │ ┌─,───────────┐ │
├─COLOR=─┼─────────┼──────┤ ├──*DSATTS=(attr)┴───────────────┤
│ └─color───┘ │ ├─OUTLINE=─┬─BOX─────────────┬──┤
│ ┌─NO──┐ │ │ │ ┌─,───────┐ │ │
├─CURSLOC=─┼─────┼────────┤ │ └─(──*┬───────┬┴─)─┘ │
│ └─YES─┘ │ │ ├─LEFT──┤ │
│ ┌─OFF───────┐ │ │ ├─RIGHT─┤ │
└─HILIGHT=─┼───────────┼──┘ │ ├─OVER──┤ │
├─BLINK─────┤ │ └─UNDER─┘ │
├─REVERSE───┤ │ ┌─NO──┐ │
└─UNDERLINE─┘ ├─SOSI=─┼─────┼─────────────────┤
│ └─YES─┘ │
│ ┌─YES─┐ │
├─TRANSP=─┼─────┼───────────────┤
│ └─NO──┘ │
└─JUSTIFY=BOTTOM────────────────┘

Standard BMS:

┌─,───────────────────────────────┐
───*┬───────────────────────────────┬┴──"
├─PARTN=(name)─┬─────────────┬──┤
│ └─,──ACTIVATE─┘ │
├─OBFMT=─┬─YES─┬────────────────┤
│ └─NO──┘ │
│ ┌─FIELD─┐ │
├─DATA=─┼───────┼───────────────┤
│ └─BLOCK─┘ │
│ ┌─NO──┐ │
├─TIOAPFX=─┴─YES─┴──────────────┤
└─FLDSEP=─┬─char────────┬───────┘
└─X'hex-char'─┘

390 CICS/ESA Application Programming Reference

DFHMDI

Full BMS:

┌─,─────────────────────────────────────────┐
───*┬─────────────────────────────────────────┬┴──"
│ ┌─SAME───┐ │
├─COLUMN=─┼────────┼──────────────────────┤
│ ├─number─┤ │
│ └─NEXT───┘ │
│ ┌─NEXT───┐ │
├─LINE=─┼────────┼────────────────────────┤
│ ├─number─┤ │
│ └─SAME───┘ │
│ ┌─LEFT──┐ │
├─JUSTIFY=(─┼───────┼──┬──────────────┬─)─┤
│ └─RIGHT─┘ └─,─┬─FIRST─┬──┘ │
│ └─LAST──┘ │
├─HEADER=YES──────────────────────────────┤
└─TRAILER=YES─────────────────────────────┘

The DFHMDI macro defines a map within the mapset defined page margin are not available for subsequent use on the
by a previous DFHMSD macro. A map contains zero or page for any lines included in the map.
more fields.
NUMBER is the column from the left or right page
“map” is the name (1–7 characters) of the map. margin where the left or right map margin is
to be established.
You should ensure that the names of maps, and names of
NEXT indicates that the left or right map margin is
fields within a mapset (or within multiple mapsets that are
to be placed in the next available column
copied into one application program) are unique. Maps and
from the left or right on the current line.
mapsets must not have the same name.
SAME indicates that the left or right map margin is
Before CICS can load a physical map, you must define a to be established in the same column as the
physical map using an RDO transaction with the MAPSET last nonheader or nontrailer map used that
attribute. specified COLUMN=number and the same
JUSTIFY operands as this macro.
Note for COBOL users: If the maps are for use in a
For input operations, the map is positioned
COBOL program, and STORAGE=AUTO has not been
at the extreme left-hand or right-hand side,
specified in the DFHMSD macro, they must be specified in
depending on whether JUSTIFY=LEFT or
descending size sequence. (Size refers to the generated
JUSTIFY=RIGHT has been specified.
01-level data areas and not to the size of the map on the
screen.) CTRL
defines characteristics of IBM 3270 terminals. Use of
DFHMDI operands any of the control options in the SEND MAP command
overrides all control options in the DFHMDI macro,
COLOR which in turn overrides all control options in the
indicates the individual color, or the default color for the DFHMSD macro.
mapset (where applicable). This is overridden by the
If CTRL is used with cumulative BMS paging (that is, the
COLOR operand of the DFHMDF macro.
ACCUM option is used on the BMS SEND MAP
The valid colors are blue, red, pink, green, turquoise, commands), it must be specified on the last (or only)
yellow, and neutral. map of a page, unless it is overridden by the ALARM,
The COLOR operand is ignored unless the terminal FREEKB and so on, options on the SEND MAP or
supports color, as indicated by FEATURE in the terminal accumulated SEND CONTROL command.
control table TYPE=TERMINAL, or with the RDO PRINT must be specified if the printer is to be
TYPETERM definition option COLOR. started; if omitted, the data is sent to the
COLUMN printer buffer but is not printed. This
specifies the column in a line at which the map is to be operand is ignored if the mapset is used
placed, that is, it establishes the left or right map margin. with 3270 displays without the Printer
The JUSTIFY operand of the DFHMDI macro controls Adapter feature.
whether map and page margin selection and column LENGTH indicates the line length on the printer;
counting are to be from the left or right side of the page. length can be specified as L40, L64, L80, or
The columns between the specified map margin and the HONEOM. L40, L64, and L80 force a new
line after 40, 64, or 80 characters,

Appendix K. BMS macro summary 391

DFHMDI

respectively. HONEOM causes the default CURSLOC

printer line length to be used. If this option indicates that for all RECEIVE MAP operations using this
is omitted, BMS sets the line length from the map on 3270 terminals, BMS sets a flag in the
TCT page size. application data structure element for the field where the
cursor is located.
FREEKB causes the keyboard to be unlocked after
the map is written. If FREEKB is not The flag may be tested by DFHBMCUR (see copybook
specified, the keyboard remains locked; data DFHBMSCA in Appendix J, “BMS-related constants” on
entry from the keyboard is inhibited until this page 375).
status is changed.
To test the flag (COBOL example):
ALARM activates the 3270 audible alarm. For (DFHBMSCA)
non-3270 VTAM terminals it sets the alarm ...
flag in the FMH. (This feature is not O2 DFHBMEOF PIC X VALUE X'8O'.
supported by interactive and batch logical O2 DFHBMCUR PIC X VALUE X'O2'.
units.) O2 DFHBMEC PIC X VALUE X'82'.
O2 DFHBMFLG PIC X.
FRSET specifies that the modified data tags (MDTs)
88 DFHERASE VALUES ARE X'8O', X'82'.
of all fields currently in the 3270 buffer are
88 DFHCURSR VALUES ARE X'O2', X'82'.
to be reset to an unmodified condition (that MOVE FLD1F TO DFHBMFLG.
is, field reset) before map data is written to IF DFHERASE THEN ...
the buffer. This allows the DFHMDF macro ELSE ...
with the ATTRB operand to control the final IF DFHCURSR THEN ...
status of any fields written or rewritten in ELSE ...
response to a BMS command.
Notes:

1. If CURSLOC=YES is specified for the MAP

definitions, and there is no data for any field of the
application data structure, but the cursor lies within
a field known to the application data structure, BMS
sets the cursor flag for the appropriate field, but the
data for all fields in the application data structure is
null, and the MAPFAIL condition does not occur.
The unmapped data stream is not available to the
application program unless it is a RECEIVE DATA
FROM request.
2. A valid CURSLOC definition in DFHMDI overrides
the definition in DFHMSD.

DATA
specifies the format of the data.

FIELD specifies that the data is passed as

contiguous fields, each field having the
format:

LL A data field

“LL” is two bytes specifying the length of the

data as input from the terminal (ignored in
output processing). “A” is a byte into which
the programmer can place an attribute to
override that specified in the map used to
process this data (see copybook
DFHBMSCA in Appendix J, “BMS-related
constants” on page 375).
BLOCK specifies that the data is passed as a
continuous stream in the following format:

A data field space

392 CICS/ESA Application Programming Reference

DFHMDI

This stream is processed as line segments BLINK specifies that the field must blink.
of the length specified in the map used to
REVERSE specifies that the character or field is
process the data. The data is in the form in
displayed in reverse video, for example, on
which it appears at the terminal; that is, it
a 3278, black characters on a green
contains data fields and interspersed blanks
background.
corresponding to any spaces that are to
appear between the fields on output. You UNDERLINE
cannot use DSATTS=YES if you specify specifies that a field is underlined.
DATA=BLOCK.
The HILIGHT operand is ignored unless the terminal
Block data is further discussed in the supports highlighting, as indicated by HILIGHT(YES) on
CICS/ESA Application Programming Guide. the RDO TYPETERM definition, or by FEATURE in the
terminal control table TYPE=TERMINAL.
DSATTS
specifies the attribute types to be included in the JUSTIFY
symbolic description map. These types can be one or specifies the position of the map on the page.
more of the following: COLOR, HILIGHT, OUTLINE, PS,
LEFT specifies that the map is to be positioned
SOSI, TRANSP, and VALIDN. Any type included in
starting at the specified column from the left
DSATTS should also be included in MAPATTS.
margin on the specified line.
EXTATT
RIGHT specifies that the map is to be positioned
this operand is supported for compatibility with previous
starting at the specified column from the
releases. Each of the extended attributes can be
right margin on the specified line.
defined individually. For new maps, the operands
DSATTS and MAPATTS should be used instead. FIRST specifies that the map is to be positioned as
the first map on a new page. Any partially
NO is equivalent to specifying neither the formatted page from preceding BMS
DSATTS operand nor the MAPATTS commands is considered to be complete.
operand. This operand can be specified for only one
YES is equivalent to: map per page.
MAPATTS=(COLOR,HILIGHT,PS,VALIDN) LAST indicates that the map is to be positioned at
DSATTS=(COLOR,HILIGHT,PS,VALIDN) the bottom of the current page. This
operand can be specified for multiple maps
MAPONLY is equivalent to:
to be placed on one page. However, maps
MAPATTS=(COLOR,HILIGHT,PS,VALIDN) other than the first map for which it is
FIELDS specified must be able to be positioned
specifies whether or not the map contains fields. If you horizontally without requiring that more lines
specify FIELDS=NO, you create a null map that defines be used.
a “hole” in BMS’s view of the screen. BMS cannot BOTTOM for a SEND MAP ACCUM command has the
change the contents of such a hole after it has created it same effect as LAST, above. For a SEND
by sending a null map. MAP command (without ACCUM) and a
RECEIVE MAP command,
FLDSEP
JUSTIFY=BOTTOM positions the map at the
specifies the field separator sequence (1–4 characters)
bottom of the screen if the number of lines
for input from non-3270 devices. Input from non-3270
in the map is specified in the SIZE operand.
devices can be entered as a single string of data with
No account is taken of trailer maps in the
the field separator sequence delimiting fields. The data
mapset. JUSTIFY=BOTTOM is equivalent
between the field separators is moved to the input fields
to specifying
in the map in order.
LINE=(screendepth−mapdepth+1)
HEADER
on the map definition, but it allows the same
allows the map to be used during page building without
map to be used for different screen sizes.
terminating the OVERFLOW condition. This operand
JUSTIFY=BOTTOM is ignored if the number
may be specified for more than one map in a mapset.
of lines is not also specified. If
HILIGHT JUSTIFY=BOTTOM and LINE are both
specifies the default highlighting attribute for all fields in specified, the value specified in LINE is
all maps in a mapset. This is overridden by the ignored.
HILIGHT operand of the DFHMDF.
LEFT and RIGHT are mutually exclusive, as are FIRST
OFF is the default and indicates that no and LAST. If neither FIRST nor LAST is specified, the
highlighting is used. data is mapped at the next available position as

Appendix K. BMS macro summary 393

DFHMDI

determined by other parameters of the map definition YES specifies that this map definition can be
and the current mapping operation. FIRST or LAST is used in outboard formatting.
ignored unless ACCUM is specified on SEND MAP
NO specifies that this map definition cannot be
commands; otherwise only one map is placed on each
used in outboard formatting.
page.
OUTLINE
Note: If a field is initialized by an output map or
allows lines to be included above, below, to the left, or to
contains data from any other source, data that is keyed
the right of a field. You can use these lines in any
as input overwrites only the equivalent length of the
combination to construct boxes around fields or groups
existing data; surplus existing data remains in the field
of fields.
and could cause unexpected interpretation of the new
data. PARTN
specifies the default partition to be associated with maps
LINE
in this mapset. If the ACTIVATE option is specified, the
specifies the starting line on a page in which data for a
specified partition is also activated when maps in this
map is to be formatted.
mapset are output to a terminal that supports partitions.
NUMBER is a value in the range 1–240, specifying a
This option overrides the PARTN option of the DFHMSD
starting line number. A request to map, on
macro and is overridden by any OUTPARTN or
a line and column, data that has been
ACTPARTN option on the SEND MAP command, or the
formatted in response to a preceding BMS
INPARTN option on a RECEIVE MAP command.
command, causes the current page to be
treated as though complete. The new data The PARTN option is ignored if the target terminal does
is formatted at the requested line and not support partitions, or if there is no partition set
column on a new page. associated with the transaction.

NEXT specifies that formatting of data is to begin PS specifies that programmed symbols are to be used. This
on the next available completely empty line. overrides the PS operand of the DFHMSD macro and is
If LINE=NEXT is specified in the DFHMDI overridden by the PS operand of the DFHMDF macro.
macro, it is ignored for input operations and
BASE specifies that the base symbol set is to be
LINE=1 is assumed.
used.
SAME specifies that formatting of data is to begin
psid specifies a single EBCDIC character, or a
on the same line as that used for a
hexadecimal code of the form X'nn', that
preceding BMS command. If
identifies the set of programmed symbols to
COLUMN=NEXT is specified, it is ignored
be used.
for input operations and COLUMN=1 is
assumed. If the data does not fit on the The PS operand is ignored unless the terminal supports
same line, it is placed on the next available programmed symbols, as indicated by the
completely-empty line. PROGSYMBOLS(YES) on the RDO TYPETERM
definition, or by FEATURE in the terminal control table
MAPATTS
TYPE=TERMINAL.
specifies the attribute types to be included in the
physical map. These types can be one or more of the SIZE
following: COLOR, HILIGHT, OUTLINE, PS, SOSI, specifies the size of a map.
TRANSP, and VALIDN. This list must include all the
attribute types to be specified for individual fields in the line is a value in the range 1–240, specifying the
map (DFHMDF macro). depth of a map as a number of lines.

Where possible these values are deduced from column is a value in the range 1–240, specifying the
operands already specified in the DFHMDI and width of a map as a number of columns.
DFHMSD macros. For example, if COLOR=BLUE has This operand is required in the following
been specified, MAPATTS=COLOR is assumed. cases:
OBFMT An associated DFHMDF macro with the
specifies whether outboard formatting is to be used. POS operand is used.
This operand is available only for 3650 logical units, or
The map is to be referred to in a SEND
for an 8100 series processor running DPS Release 2
MAP command with the ACCUM option.
and defined to CICS as an LUTYPE2 logical unit. For
more information, see the CICS/ESA Application The map is to be used when referring
Programming Guide. to input data from other than a 3270
terminal in a RECEIVE MAP command.
The OBFMT operand overrides the OBFMT operand on
the DFHMSD macro.

394 CICS/ESA Application Programming Reference

DFHMDI

SOSI MUSTENTER
indicates that the field may contain a mixture of EBCDIC specifies that data must be entered into the
and DBCS data. The DBCS subfields within an EBCDIC field, though need not fill it. An attempt to
field are delimited by SO (shift out) and SI (shift in) move the cursor from an empty field raises
characters. SO and SI both occupy a single screen the INHIBIT INPUT condition
position (normally displayed as a blank). They can be
TRIGGER specifies that this field is a trigger field.
included in any non-DBCS field on output, if they are
Trigger fields are discussed in the
correctly paired. The terminal user can transmit them
CICS/ESA Application Programming Guide.
inbound if they are already present in the field, but can
# Apar PQ12071
add them to an EBCDIC field only if the field has the
SOSI attribute. # Documentation for Apar PQ12071
TERM # added 12/03/98
kept for compatibility with previous releases.
# USEREXIT
TIOAPFX # specifies that this field is to be processed by
specifies whether BMS should include a filler in the # the BMS global user exits, XBMIN and
symbolic description maps to allow for the unused TIOA # XBMOUT, if this field is received or
prefix. This operand overrides the TIOAPFX operand # transmitted in a 3270 datastream when the
specified for the DFHMSD macro. # respective exit is enabled. For further
YES specifies that the filler should be included in # information on the use of the BMS global
the symbolic description maps. If # user exits, refer to the CICS/ESA
TIOAPFX=YES is specified, all maps within # Customization Guide.
the mapset have the filler. TIOAPFX=YES # The MUSTFILL, MUSTENTER and TRIGGER
should always be used for command-level # specifications are valid only for terminals that support the
application programs. # field validation extended attribute, otherwise they are
NO is the default and specifies that the filler is # ignored. The USEREXIT specification applies to all
not to be included. # 3270 devices.

TRAILER # Note: The USEREXIT specification is totally

allows the map to be used during page building without # unconnected with the field validation extended
terminating the OVERFLOW condition. This operand # attribute as defined in the 3270 datastream
may be specified for more than one map in a mapset. If # architecture.
a trailer map is used other than in the overflow The VALIDN operand is ignored unless the terminal
environment, the space normally reserved for overflow supports validation, as indicated by VALIDATION(YES)
trailer maps is not reserved while mapping the trailer on the RDO TYPETERM definition, or by FEATURE in
map. the terminal control table TYPE=TERMINAL.
TRANSP
determines whether the background of an alphanumeric
field is transparent or opaque, that is, whether an
underlying (graphic) presentation space is visible
between the characters.

VALIDN
# specifies:

# the validation that is to be used on an 8775 terminal

# that this field is to be processed by the BMS global
# user exits

This is overridden by the VALIDN operand of the

DFHMDF macro, and overrides the VALIDN operand of
the DFHMSD macro.

MUSTFILL specifies that the field must be filled

completely with data. An attempt to move
the cursor from the field before it has been
filled, or to transmit data from an incomplete
field, raises the INHIBIT INPUT condition

Appendix K. BMS macro summary 395

DFHMSD

Function
Mapset definition.

Command syntax
Minimum BMS:

# Apar 69549
# Documentation for Apar 69549 added 13 Apr 1995 (TUCKER)

┌─,───────────────────────┐ ┌─,───────────────────────────────┐
──mapset──DFHMSD──TYPE=─┬─DSECT─┬────*┬───────────────────────┬┴───*┬───────────────────────────────┬┴──"
├─MAP───┤ │ ┌─OUT───┐ │ │ ┌─NO──┐ │
└─FINAL─┘ ├─MODE=─┼───────┼───────┤ ├─CURSLOC=─┼─────┼──────────────┤
│ ├─IN────┤ │ │ └─YES─┘ │
│ └─INOUT─┘ │ │ ┌─OFF───────┐ │
│ ┌─LOWER─┐ │ ├─HILIGHT=─┼───────────┼────────┤
├─FOLD=─┼───────┼───────┤ │ ├─BLINK─────┤ │
│ └─UPPER─┘ │ │ ├─REVERSE───┤ │
│ ┌─NO──┐ │ │ └─UNDERLINE─┘ │
├─TRIGRAPH=─┼─────┼─────┤ ├─PS=─┬─BASE─┬──────────────────┤
│ └─YES─┘ │ │ └─psid─┘ │
# │ ┌─ASM────┐ │ │ ┌─,───────────┐ │
# ├─LANG=─┼────────┼──────┤ *
├─VALIDN=(──┬───────────┬┴─)────┤
# │ ├─COBOL──┤ │ │ ├─MUSTFILL──┤ │
# │ ├─COBOL2─┤ │ │ ├─MUSTENTER─┤ │
# │ ├─PLI────┤ │ │ ├─TRIGGER───┤ │
# │ └─C──────┘ │ │ └─USEREXIT──┘ │
├─┬──────────────┬──────┤ ├─┬─TERM=type─┬─────────────────┤
│ ├─STORAGE=AUTO─┤ │ │ └─SUFFIX=n──┘ │
│ └─BASE=name────┘ │ │ ┌─NO──┐ │
│ ┌─,────────┐ │ ├─TIOAPFX=─┼─────┼──────────────┤
├─CTRL=(──*┬────────┬┴─)─┤ │ └─YES─┘ │
│ ├─PRINT──┤ │ │ ┌─,────────────┐ │
│ ├─length─┤ │ ├──*MAPATTS=(attr)┴──────────────┤
│ ├─FREEKB─┤ │ │ ┌─,───────────┐ │
│ ├─ALARM──┤ │ ├──*DSATTS=(attr)┴───────────────┤
│ └─FRSET──┘ │ ├─OUTLINE=─┬─BOX─────────────┬──┤
│ ┌─NO──────┐ │ │ │ ┌─,───────┐ │ │
├─EXTATT=─┼─────────┼───┤ │ └─(──*┬───────┬┴─)─┘ │
│ ├─MAPONLY─┤ │ │ ├─LEFT──┤ │
│ └─YES─────┘ │ │ ├─RIGHT─┤ │
│ ┌─DEFAULT─┐ │ │ ├─OVER──┤ │
└─COLOR=─┼─────────┼────┘ │ └─UNDER─┘ │
└─color───┘ │ ┌─NO──┐ │
├─SOSI=─┼─────┼─────────────────┤
│ └─YES─┘ │
│ ┌─YES─┐ │
└─TRANSP=─┼─────┼───────────────┘
└─NO──┘

396 CICS/ESA Application Programming Reference

DFHMSD

Standard BMS:

┌─,───────────────────────────────┐
───*┬───────────────────────────────┬┴──"
├─PARTN=(name)─┬─────────────┬──┤
│ └─,──ACTIVATE─┘ │
├─LDC=mnemonic──────────────────┤
│ ┌─NO──┐ │
├─OBFMT=─┼─────┼────────────────┤
│ └─YES─┘ │
│ ┌─,─────┐ │
*
├─HTAB=────tab──┴───────────────┤
│ ┌─,─────┐ │
├─VTAB=──*──tab──┴───────────────┤
│ ┌─FIELD─┐ │
├─DATA=─┼───────┼───────────────┤
│ └─BLOCK─┘ │
└─FLDSEP=─┬─char────────┬───────┘
└─X'hex-char'─┘

A DFHMSD macro defines a mapset; it begins: COLOR

DFHMSD TYPE=MAP (or TYPE=DSECT) indicates the individual color, or the default color for the
mapset (where applicable). This is overridden by the
and ends: COLOR operand of the DFHMDI macro, which is in turn
DFHMSD TYPE=FINAL overridden by the COLOR operand of the DFHMDF
macro.
“mapset” is the name (1–7 characters) of the mapset.
The valid colors are blue, red, pink, green, turquoise,
A DFHMSD macro contains one or more map definition yellow, and neutral.
macros, each of which contains one or more field definition
The COLOR operand is ignored unless the terminal
macros.
supports color, as indicated by FEATURE in the terminal
You should ensure that the names of maps, and names of control table TYPE=TERMINAL, or with the RDO
fields within a mapset (or within multiple mapsets that are TYPETERM definition COLOR.
copied into one application program) are unique. Maps and CTRL
mapsets must not have the same name. defines characteristics of IBM 3270 terminals. Use of
any of the control options in the SEND MAP command
Before CICS can load a physical map, you must define a
overrides all control options in the DFHMDI macro,
physical map using an RDO transaction with the MAPSET
which in turn overrides all control options in the
attribute.
DFHMSD macro.
You assemble a BMS mapset definition to generate either a If CTRL is used with cumulative BMS paging (that is, the
symbolic description map or a physical map. The CICS/ESA ACCUM option is used on the BMS SEND MAP
System Definition Guide tells you how to assemble and commands), it must be specified on the last (or only)
catalog the maps. map of a page, unless it is overridden by the ALARM,
FREEKB and so on, options on the SEND MAP or
DFHMSD operands accumulated SEND CONTROL command.

BASE PRINT must be specified if the printer is to be

specifies that the same storage base is used for the started; if omitted, the data is sent to the
symbolic description maps from more than one mapset. printer buffer but is not printed. This
The same name is specified for each mapset that is to operand is ignored if the mapset is used
share the same storage base. Because all mapsets with with 3270 displays without the Printer
the same base describe the same storage, data related Adapter feature.
to a previously used mapset may be overwritten when a LENGTH indicates the line length on the printer;
new mapset is used. Different maps within the same length can be specified as L40, L64, L80, or
mapset also overlay one another. HONEOM. L40, L64, and L80 force a new
This operand is not valid for assembler-language line after 40, 64, or 80 characters,
programs, and cannot be used when STORAGE=AUTO respectively. HONEOM causes the default
has been specified. printer line length to be used. If this option
is omitted, BMS sets the line length from the
TCT page size.

Appendix K. BMS macro summary 397

DFHMSD

FREEKB causes the keyboard to be unlocked after FIELD specifies that the data is passed as
the map is written. If FREEKB is not contiguous fields, each field having the
specified, the keyboard remains locked; data format:
entry from the keyboard is inhibited until this
status is changed. LL A data field
ALARM activates the 3270 audible alarm. For
non-3270 VTAM terminals, it sets the alarm “LL” is two bytes specifying the length of the
flag in the FMH. (This feature is not data as input from the terminal (these two
supported by interactive and batch logical bytes are ignored in output processing). “A”
units.) is a byte into which the programmer can
place an attribute to override that specified
FRSET specifies that the modified data tags (MDTs)
in the map used to process this data (see
of all fields currently in the 3270 buffer are
copybook DFHBMSCA in Appendix J,
to be reset to a not-modified condition (that
“BMS-related constants” on page 375).
is, field reset) before map data is written to
the buffer. This allows the DFHMDF macro BLOCK specifies that the data is passed as a
with the ATTRB operand to control the final continuous stream in the following format:
status of any fields written or rewritten in
response to a BMS command. A data field space

CURSLOC
indicates that for all RECEIVE MAP operations using this This stream is processed as line segments
map on 3270 terminals, BMS sets a flag in the of the length specified in the map used to
application data structure element for the field where the process the data. The data is in the form
cursor is located. that it appears on the terminal; that is, it
contains data fields and interspersed blanks
The flag may be tested by DFHBMCUR (see copybook corresponding to any spaces that are to
DFHBMSCA in Appendix J, “BMS-related constants” on appear between the fields on output. You
page 375). cannot use DSATTS=YES, if you specify
To test the flag (COBOL example): DATA=BLOCK.
(DFHBMSCA) Block data is further discussed in the
... CICS/ESA Application Programming Guide.
O2 DFHBMEOF PIC X VALUE X'8O'.
O2 DFHBMCUR PIC X VALUE X'O2'. DSATTS
O2 DFHBMEC PIC X VALUE X'82'. specifies the attribute types to be included in the
O2 DFHBMFLG PIC X. symbolic description map. These types can be one or
88 DFHERASE VALUES ARE X'8O', X'82'. more of the following: COLOR, HILIGHT, OUTLINE, PS,
88 DFHCURSR VALUES ARE X'O2', X'82'. SOSI, TRANSP, and VALIDN. Any type included in
MOVE FLD1F TO DFHBMFLG. DSATTS should also be included in MAPATTS.
IF DFHERASE THEN ...
ELSE ... EXTATT
IF DFHCURSR THEN ... this operand is supported for compatibility with previous
ELSE ... releases. Each of the extended attributes can be
defined individually. For new maps, the operands
Notes:
DSATTS and MAPATTS should be used instead.
1. If CURSLOC=YES is specified for the MAP
NO is equivalent to specifying neither the
definitions, and there is no data for any field of the
DSATTS operand nor the MAPATTS
application data structure, but the cursor lies within
operand.
a field known to the application data structure, BMS
sets the cursor flag for the appropriate field, but the YES is equivalent to:
data for all fields in the application data structure is MAPATTS=(COLOR,HILIGHT,PS,VALIDN)
null, and the MAPFAIL condition does not occur. DSATTS=(COLOR,HILIGHT,PS,VALIDN)
The unmapped data stream is not available to the
application program unless it is a RECEIVE DATA MAPONLY is equivalent to:
FROM request. MAPATTS=(COLOR,HILIGHT,PS,VALIDN)
2. A valid CURSLOC definition in DFHMDI overrides FLDSEP
the definition in DFHMSD. specifies the field separator sequence (1–4 characters)
for input from non-3270 devices. Input from non-3270
DATA devices can be entered as a single string of data with
specifies the format of the data. the field separator sequence delimiting fields. The data

398 CICS/ESA Application Programming Reference

DFHMSD

between the field separators is moved to the input fields Where possible these values are deduced from
in the map in order. operands already specified in the DFHMDI and
DFHMSD macros. For example, if COLOR=BLUE has
FOLD
been specified, MAPATTS=COLOR is assumed.
specifies whether to generate lowercase or uppercase
characters in C language programs. MODE
specifies whether the mapset is to be used for input,
FOLD is only available for programs written in C.
output, or both.
HILIGHT
OBFMT
specifies the default highlighting attribute for all fields in
specifies whether outboard formatting is to be used.
all maps in a mapset. This is overridden by the
This operand is available only for 3650 logical units, or
HILIGHT operand of the DFHMDI, which is in turn
for an 8100 series processor running DPS Release 2
overridden by the HILIGHT operand of the DFHMDF.
and defined to CICS as an LUTYPE2 logical unit. For
OFF is the default and indicates that no more information, see the CICS/ESA Application
highlighting is used. Programming Guide.
BLINK specifies that the field must blink. The OBFMT operand on DFHMSD is overridden by the
OBFMT operand on DFHMDI.
REVERSE specifies that the character or field is
displayed in reverse video, for example, on YES specifies that all maps within this mapset
a 3278, black characters on a green can be used in outboard formatting, except
background. those for which OBFMT=NO is specified in
UNDERLINE the DFHMDI macro.
specifies that a field is underlined. NO specifies that no maps within this mapset
can be used in outboard formatting, except
The HILIGHT operand is ignored unless the terminal
those for which OBFMT=YES is specified in
supports highlighting, as indicated by HILIGHT(YES) on
DFHMDI.
the RDO TYPETERM definition or by FEATURE in the
terminal control table TYPE=TERMINAL. OUTLINE
allows lines to be included above, below, to the left, or to
HTAB
the right of a field. You can use these lines in any
specifies one or more tab positions for use with
combination to construct boxes around fields or groups
interactive and batch logical units and SCS printers with
of fields.
horizontal forms control.
PARTN
LANG
specifies the default partition to be associated with maps
specifies the source language of the application
in this mapset. If the ACTIVATE option is specified, the
programs into which the symbolic description maps in
specified partition is also activated when maps in this
the mapset are copied. This option need only be coded
mapset are output to a terminal that supports partitions.
for DFHMSD TYPE=DSECT. If a mapset is to be used
This option is overridden by the PARTN operand of the
by more than one program, and the programs are not all
DFHMDI macro, which is in turn overridden by any
written in the same source language, a separate version
OUTPARTN or ACTPARTN option on the SEND MAP
of the mapset must be defined for each programming
command, or the INPARTN option on a RECEIVE MAP
language.
command.
LDC
The PARTN operand is ignored if the target terminal
specifies the code to be used by CICS to determine the
does not support partitions, or if there is no partition set
logical device mnemonic to be used for a BMS output
associated with the transaction.
operation. If no LDC operand has been specified on any
previous BMS output in the logical message, this LDC PS specifies that programmed symbols are to be used. This
will be transmitted in the function management header to is overridden by the PS operand of the DFHMDI macro,
the logical unit. This operand is used only for TCAM which is in turn overridden by the PS operand of the
and VTAM-supported 3600 terminals, and batch logical DFHMDF macro.
units.
BASE specifies that the base symbol set is to be
MAPATTS used.
specifies the attribute types to be included in the
psid specifies a single EBCDIC character, or a
physical map. These types can be one or more of the
hexadecimal code of the form X'nn', that
following: COLOR, HILIGHT, OUTLINE, PS, SOSI,
identifies the set of programmed symbols to
TRANSP, and VALIDN. This list must include all the
be used.
attribute types to be specified for individual fields in the
map (DFHMDF macro).

Appendix K. BMS macro summary 399

DFHMSD

The PS operand is ignored unless the terminal supports TERM

programmed symbols, as indicated by specifies the type of terminal or logical unit (LU)
PROGSYMBOLS(YES) on the RDO TYPETERM associated with the mapset. If no terminal type or LU is
definition, or by FEATURE on the terminal control table specified, 3270 is assumed. The terminal types and LUs
TYPE=TERMINAL. you can specify, together with their generated suffixes,
are shown in Table 27.
SOSI
indicates that the field may contain a mixture of EBCDIC
Table 27. BMS terminal types
and DBCS data. The DBCS subfields within an EBCDIC
field are delimited by SO (shift out) and SI (shift in) TYPE Suffix
characters. SO and SI both occupy a single screen CRLP1 A
position (normally displayed as a blank). They can be TAPE B
included in any non-DBCS field on output provided they DISK C
are correctly paired. The terminal user can transmit TWX D
them inbound if they are already present in the field, but 1050 E
2740 F
can add them to an EBCDIC field only if the field has the
2741 G
SOSI attribute. 2770 I
2780 J
STORAGE
3780 K
The meaning of this operand depends upon the
3270-1 (40-column) L
language in which application programs are written, as 3270-2 (80-column) M
follows: INTLU/3767/3770I/SCS2 P
For a COBOL program, STORAGE=AUTO specifies that 2980 Q
2980-4 R
the symbolic description maps in the mapset are to
32703 blank
occupy separate (that is, not redefined) areas of storage. 3601 U
This operand is used when the symbolic description 36534 V
maps are copied into the working-storage section and 3650UP5 W
the storage for the separate maps in the mapset is to be 3650/32706 X
used concurrently. BCHLU/3770B7 Y
ALL (all the above) blank
For a C program, STORAGE=AUTO specifies that the Notes:
symbolic description maps are to be defined as having
1. Card-reader-in/line-printer-out.
the automatic storage class. If STORAGE=AUTO is not
specified, they are declared as pointers. You cannot 2. All interactive LUs including 3790 full-function LU and SCS
specify both BASE=name and STORAGE=AUTO for the printer LUs (3270 and 3790).
same mapset. If STORAGE=AUTO is specified and 3. Default if TERM omitted.
TIOAPFX is not, TIOAPFX=YES is assumed. Same as ALL; used when no need to distinguish between models.
4. Plus host-conv (3653) LU.
For a PL/I program, STORAGE=AUTO specifies that the
symbolic description maps are to be declared as having 5. Plus interpreter LU.
the AUTOMATIC storage class. If STORAGE=AUTO is 6. Plus host-conv (3270) LU.
not specified, they are declared as BASED. You cannot 7. Plus all batch and BDI LUs.
specify both BASE=name and STORAGE=AUTO for the
same mapset. If STORAGE=AUTO is specified and
TIOAPFX is not, TIOAPFX=YES is assumed. In addition, you should note the following:

For an assembler-language program, For TCAM-connected terminals (other than 3270 or SNA
STORAGE=AUTO specifies that individual maps within a devices), use either CRLP or ALL; for TCAM-connected
mapset are to occupy separate areas of storage instead 3270s or SNA devices, select the appropriate parameter
of overlaying one another. in the normal way.
If ALL is specified, ensure that device dependent
SUFFIX
characters are not included in the mapset and that
specifies a 1-character, user-defined, device-dependent
format characteristics such as page size are suitable for
suffix for this mapset, as an alternative to a suffix
all input/output operations (and all terminals) in which
generated by the TERM operand. The suffix specified
the mapset is applied. For example, some terminals are
by this operand should match the value of a transaction
limited to 480 bytes, others to 1920 bytes; the 3604 is
defined with ALTSUFFIX, or ALTSFX in the terminal
limited to six lines of 40 characters each. Within these
control table TYPE=TERMINAL. Use a numeric value to
guidelines, use of ALL can offer important advantages.
avoid conflict with suffixes generated by the TERM
Because an assembly run is required for each map
operand.
generation, the use of ALL, indicating that one map is to
be used for more than one terminal, can result in
significant time and storage savings.

400 CICS/ESA Application Programming Reference

DFHMSD

However, better run-time performance for maps used by before an application program can use
single terminal types is achieved if the terminal type them.
(rather than ALL) is specified. Alternatively, BMS
If both map and DSECT are to be generated in the
support for device-dependent mapsets can be bypassed
same job, the SYSPARM option can be used in the
by specifying NODDS in the BMS operand of the system
assembler job execution step, as described in the
initialization parameters. For more information, see the
CICS/ESA Installation Guide.
CICS/ESA Resource Definition Guide.
VALIDN
TIOAPFX
specifies whether BMS should include a filler in the
# specifies:
symbolic description maps to allow for the unused TIOA
prefix. # the validation that is to be used on an 8775 terminal
YES specifies that the filler should be included in # that this field is to be processed by the BMS global
the symbolic description maps. If # user exits
TIOAPFX=YES is specified, all maps within
This is overridden by the VALIDN operand of the
the mapset have the filler, except when
DFHMDI macro, which is in turn overridden by the
TIOAPFX=NO is specified on the DFHMDI
VALIDN operand of the DFHMDF macro.
macro. TIOAPFX=YES should always be
used for command-level application MUSTFILL specifies that the field must be filled
programs. completely with data. An attempt to move
NO is the default and specifies that the filler is the cursor from the field before it has been
not to be included. The filler may still be filled, or to transmit data from an incomplete
included for a map if TIOAPFX=YES is field, raises the INHIBIT INPUT condition.
specified on DFHMDI. MUSTENTER
specifies that data must be entered into the
TRANSP
field, though need not fill it. An attempt to
determines whether the background of an alphanumeric
move the cursor from an empty field raises
field is transparent or opaque, that is, whether an
the INHIBIT INPUT condition.
underlying (graphic) presentation space is visible
between the characters. TRIGGER specifies that this field is a trigger field.
Trigger fields are discussed in the
TRIGRAPH
CICS/ESA Application Programming Guide.
specifies trigraph sequences to be used in C/370
# Apar PQ12071
language symbolic description maps.
When TRIGRAPH=YES, trigraph sequences are # Documentation for Apar PQ12071
produced: # added 12/03/98

{ prints as ??<
# USEREXIT
} prints as ??>
# specifies that this field is to be processed by
[ prints as ??(
# the BMS global user exits, XBMIN and
] prints as ??)
# XBMOUT, if this field is received or
This option is only available for programs written in C. # transmitted in a 3270 datastream when the
# respective exit is enabled. For further
TYPE # information on the use of the BMS global
specifies the type of map to be generated using the # user exits, refer to the CICS/ESA
definition. Both types of map must be generated before # Customization Guide.
the mapset can be used by an application program. If
aligned symbolic description maps are required, you # The MUSTFILL, MUSTENTER and TRIGGER
should ensure that you specify SYSPARM=ADSECT and # specifications are valid only for terminals that support the
SYSPARM=AMAP when you assemble the symbolic and # field validation extended attribute, otherwise they are
physical maps respectively. # ignored. The USEREXIT specification applies to all
# 3270 devices.
DSECT specifies that a symbolic description map is
to be generated. Symbolic description maps # Note: The USEREXIT specification is totally
must be copied into the source program # unconnected with the field validation extended
before it is translated and compiled. # attribute as defined in the 3270 datastream
# architecture.
MAP specifies that a physical map is to be
generated. Physical maps must be The VALIDN operand is ignored unless the terminal
assembled or compiled, link-edited, and supports validation, as indicated by VALIDATION(YES)
cataloged in the CICS program library

Appendix K. BMS macro summary 401

DFHMSD

in the RDO TYPETERM definition or by FEATURE in the

terminal control table TYPE=TERMINAL.

VTAB
specifies one or more tab positions for use with
interactive and batch logical units and SCS printers
having vertical forms control.

402 CICS/ESA Application Programming Reference

DFHPDI

Function
Partition definition.

Command syntax

┌─,────────────────────────┐
──┬───────┬──DFHPDI──VIEWPOS=(lines,columns)──,VIEWSZE=(lines,columns)───*┬────────────────────────┬┴──"
└─partn─┘ ├─BUFSZE=(lines,columns)─┤
├─CHARSZE=(vpels,hpels)──┤
├─MAPSFX=mapset-suffix───┤
└─ATTRB=ERROR────────────┘

A partition set contains one or more partitions. Each partition defaults for individual partitions by coding CHARSZE in
is defined by coding a partition definition macro. the DFHPDI macro.

“partn” is a partition name (1–2 characters). It allows you to MAPSFX=mapset-suffix

refer to the partition in your application programs. specifies the partition’s 1-character mapset suffix. BMS
uses the suffix to select mapset versions in the same
Every partition in a partition set must have a different name. way as for the RDO option ALTSUFFIX, or ALTSFX in
Only the error partition can be unnamed (see the terminal control terminal TYPE=TERMINAL macro.
ATTRB=ERROR operand). If this operand is omitted, a suffix L is assumed if the
“columns” value of the BUFSZE operand is less than or
Partitions are defined by coding the macros DFHPSD equal to 40; otherwise M is assumed.
(partition set definition) and DFHPDI (partition definition).
Each partition definition must be part of a partition set VIEWPOS=(lines,columns)
definition. specifies the position of the top left-hand corner of this
partition’s viewport. You specify the position in numbers
of lines and numbers of columns.
DFHPDI operands
The DFHPDI macro checks that viewports do not
ATTRB overlap. If you have coded the RDO ALTSCREEN
specifies that error messages are to be directed to this option, or the ALTSCRN operand of the DFHPSD
partition whenever possible. The partition is cleared macro, DFHPDI also checks that all viewports fit within
before an error message is displayed. The RDO option the usable area of the terminal screen.
ERRHILIGHT, or ERRATT in the terminal control table
Note: The information given here on positioning
TYPE=TERMINAL is honored, but the LASTLINE option
viewports is necessarily brief. For more information you
is ignored.
should consult the component description for the device
BUFSZE=(lines,columns) you are using.
specifies the size of the presentation space for the
VIEWSZE=(lines,columns)
partition. Device limitations mean that the “columns”
specifies the size, in lines and columns, of the partition’s
value must be equal to the “columns” value specified by
viewport. The DFHPDI macro checks that viewports do
the VIEWSZE operand. The “lines” value can be greater
not overlap. If you code the RDO ALTSCREEN option,
than or, by default, equal to the value specified by the
or the ALTSCRN operand of the DFHPSD macro
VIEWSZE operand. A greater lines value implies that
partition set definition macro, DFHPDI checks that the
the target terminal supports vertical scrolling.
partitions all fit within the usable area of the display
CHARSZE(vpels,hpels) screen.
specifies the size of the character cell to be reserved for
each character displayed in a partition. You specify the
size as numbers of vertical picture elements (vpels) and
numbers of horizontal picture elements (hpels). You can
specify this operand on either the DFHPSD macro only,
or on both the DFHPSD and DFHPDI macros. The
values specified in the DFHPSD become the defaults for
all partitions in the partition set. You can override these

Appendix K. BMS macro summary 403

DFHPSD

Function
Partition set definition.

Command syntax

┌─,─────────────────────────┐
──partnset DFHPSD───*┬─────────────────────────┬┴──"
├─SUFFIX=user-suffix──────┤
├─ALTSCRN=(lines,columns)─┤
└─CHARSZE=(vpels,hpels)───┘

Each partition set definition contains a single DFHPSD macro SUFFIX=user-suffix

followed by one or more DFHPDI macros, and ending with a specifies a 1-character user suffix for this version of the
DFHPSD TYPE=FINAL partition set definition macro. partition set. It allows different versions of a partition set
to be associated with different terminals. When the
“partnset” is a partition set name (1–6 characters). partition set is to be loaded, CICS looks for a version
whose suffix matches the RDO option ALTSUFFIX or
Partitions are defined by coding the macros DFHPSD
the ALTSFX in the terminal control table
(partition set definition) and DFHPDI (partition definition).
TYPE=TERMINAL. If it cannot find the correct partition
Each partition definition must be part of a partition set
set version, it loads a version with a default suffix (M or
definition.
L). If it cannot find a suffixed version either, it loads an
unsuffixed one. If it cannot find this, it abends with
Ending DFHPSD APCT.

[partnset] DFHPSD TYPE=FINAL

The PARTNSET name (if specified) must match that

specified on the DFHPSD macro that started the partition set
definition.

DFHPSD operands
ALTSCRN(lines,columns)
specifies the size, in characters, of the usable area of
the target terminal. This is normally the same as the
RDO ALTSCREEN option, or the ALTSCRN operand of
the terminal control table TYPE=TERMINAL entry for the
terminal. You use ALTSCRN to ensure that the
viewports of partitions within a partition set fit into the
usable area of the screen.

CHARSZE(vpels,hpels)
specifies the size of the character cell to be reserved for
each character displayed in a partition. You specify the
size as numbers of vertical picture elements (vpels) and
numbers of horizontal picture elements (hpels). You can
specify this operand on either the DFHPSD macro only,
or on both the DFHPSD and DFHPDI macros. The
values specified in this operand become the defaults for
all partitions in the partition set. You can override this
default for individual partitions by coding CHARSZE in
the DFHPDI macro.

404 CICS/ESA Application Programming Reference

Index
3650 Store System (continued)
Numerics interpreter logical unit 45, 145, 150, 205, 247
16MB line 121 3650/3680 Full-function Logical Unit
2260 Display Station RECEIVE 207
CONVERSE 55 SEND 250
ISSUE RESET 161 3650/3680 Store System
RECEIVE 212 host command processor LU 248
SEND 257 3660 Supermarket Scanning System
2265 Display Station CONVERSE 54
CONVERSE 55 RECEIVE 211
ISSUE RESET 161 SEND 256
RECEIVE 212 3680 Host Command Processor
SEND 257 CONVERSE 47
2741 Communication Terminal 3680 Programmable Store System
CONVERSE 56 host command processor LU 248
ISSUE RESET 161 3735 Programmable Buffered Terminal 60, 216, 259
RECEIVE 212 3740 Data Entry System 60, 143, 144, 216
SEND 257 3767 Communication Terminal
2770 Data Communication System interactive logical unit 47, 206, 249
CONVERSE 54, 57 3770 Data Communication System
RECEIVE 211 batch logical unit 48, 206, 249
SEND 256 3770 Full Function Logical Unit
2780 Data Transmission Terminal RECEIVE 207
CONVERSE 54, 57 SEND 250
RECEIVE 211 3770 interactive logical unit
SEND 256 RECEIVE 206
2980 General Banking Terminal System SEND 249
DFH2980 structure 214 3780 Data Communication Terminal
output control 213 CONVERSE 54
output to common buffer 214 RECEIVE 211
passbook control 213 SEND 256
RECEIVE/SEND commands 213, 258 3790 Communication System
3270 Information Display System 3270-display logical unit 49, 217, 251
(BTAM or TCAM supported) 58, 215, 258 Full Function Logical Unit 48
(BTAM supported) 137, 161 full-function logical unit 207, 250
logical unit 44, 138, 203, 245 SCS printer logical unit 250
3600 Finance Communication System 4700 Finance Communication System
3601 logical unit 44, 204, 246 CONVERSE command 58
3614 logical unit 45, 205, 246 RECEIVE command 215
CONVERSE command 58 SEND command 259
pipeline logical units 245
RECEIVE command 215
SEND command 259 A
3630 Plant Communication System ABCODE option
RECEIVE 204 ABEND 12
SEND 246 ASSIGN 23
3650 Host Command Processor ABDUMP option
CONVERSE 47 ASSIGN 23
3650 Logical Units ABEND AICA timeout 2
RECEIVE 205 ABEND command 12
3650 Store System ABEND exit, reactivating 123
host conversational abend support commands 9
LU 3270 247
LU 3653 248

abnormal termination, task 123 ALTERNATE option (continued)
ABPROGRAM option SEND CONTROL 265
ASSIGN 23 SEND MAP 269
absolute expressions 4 SEND TEXT 281
ABSTIME option SEND TEXT NOEDIT 286
ASKTIME 21 ALTSCRN operand
FORMATTIME 92 DFHPSD 404
access to system information ALTSCRNHT option
ADDRESS command 13 ASSIGN 23
ADDRESS SET command 15 ALTSCRNWD option
ASSIGN command 22 ASSIGN 23
CICS storage areas 13, 15 ANYKEY option
ACCUM option HANDLE AID 125
SEND CONTROL 264 APLKYBD option
SEND MAP 268 ASSIGN 23
SEND TEXT 280 APLTEXT option
ACEE option ASSIGN 23
ADDRESS 13 APPC basic conversations
ACTION option commands 9
WRITE OPERATOR 334 APPC logical unit
ACTPARTN option acquiring session to 16
SEND CONTROL 264 initiating conversation with 39
SEND MAP 269 returning mapped sessions to CICS 96
SEND TEXT 280 sending and receiving 41
ADDRESS command 13 APPC mapped conversations
ADDRESS SET command 15 abending 130
address, cursor 361 commands 9
AFTER option ensuring transmission of accumulated data 320
POST 179 extracting attributes of 86
ROUTE 239 informing partner of error 149
START 306 issuing a positive response 135
AID option receiving data 201
RECEIVE MAP MAPPINGDEV command 223 requesting change of direction 164
ALARM option retrieving values from attach header 89
SEND CONTROL 264 returning sessions to CICS 96
SEND MAP 269 sending data 242
SEND MAP MAPPINGDEV command 274 application performance, monitoring 174
SEND TEXT 281 APPLID option
SEND TEXT NOEDIT 286 ASSIGN 23
ALARM value argument values
DFHMDI 392 assembler language 4
DFHMSD 398 C 2
ALIGNED attribute COBOL 2
PL/I 4 PL/I 3
ALL option ASA option
SEND PAGE 276 SPOOLOPEN 296
ALLOCATE (APPC) command 16 ASIS option
ALLOCATE (LUTYPE6.1) command 18 CONVERSE (non-VTAM) 61
ALLOCATE (MRO) command 20 CONVERSE (VTAM) 50
ALTER option RECEIVE (non-VTAM) 218
QUERY SECURITY 182 RECEIVE (VTAM) 208
ALTERNATE option RECEIVE MAP 220
CONVERSE (non-VTAM) 61 RECEIVE PARTN 225
CONVERSE (VTAM) 50 SEND (non-VTAM) 261
SEND (non-VTAM) 261 ASKIP value
SEND (VTAM) 252 DFHMDF 384

406 CICS/ESA Application Programming Reference

ASKTIME command 21 BASE value (continued)
ASRAINTRPT option DFHMSD 399
ASSIGN 23 basic mapping support (BMS)
ASRAKEY option commands 9
ASSIGN 23 completing a logical message 276
ASRAPSW option deleting a logical message 180
ASSIGN 23 determining input partition 225
ASRAREGS option field definition macro 381, 383
ASSIGN 23 full BMS
ASRASPC option RECEIVE MAP 220
ASSIGN 24 RECEIVE PARTN 225
ASRASTG option SEND CONTROL 264
ASSIGN 24 SEND MAP 268
assembler language SEND PAGE 276
argument values 4 SEND PARTNSET 279
LENGTH option default 4 SEND TEXT 280
program exit 354 SEND TEXT MAPPED 284
register contents 353 SEND TEXT NOEDIT 286
translated code 353 full-function BMS
ASSIGN command 22 PURGE MESSAGE 180
asynchronous interrupt 358 map definition macro 381, 391
AT option mapping input data 220
POST 179 mapping input data with MAPPINGDEV 223
ROUTE 239 mapset definition macro 381, 397
START 306 minimum BMS
ATTACH option RECEIVE MAP 220
START 306 RECEIVE MAP MAPPINGDEV command 223
ATTACHID option SEND CONTROL 264
BUILD ATTACH (LUTYPE6.1) 31 SEND MAP 268
BUILD ATTACH (MRO) 33 SEND MAP MAPPINGDEV command 274
CONVERSE (non-VTAM) 61 partition definition macro 381, 403
CONVERSE (VTAM) 50 partition set definition macro 381, 404
EXTRACT ATTACH (LUTYPE6.1) 82 related constants 375
EXTRACT ATTACH (MRO) 84 routing a logical message 239
SEND (non-VTAM) 261 sending previously mapped data 284
SEND (VTAM) 252 sending user-defined data stream 286
attention identifier (AID) 125 standard BMS
ATTRB operand RECEIVE MAP 220
DFHMDF 384 RECEIVE PARTN 225
DFHPDI 403 SEND CONTROL 264
attributes SEND MAP 268
control character list, DFHBMSCA 375 SEND PARTNSET 279
authentication commands 9 SEND TEXT 280
AUTOPAGE option batch data interchange (BDI)
SEND PAGE 276 add record to data set 133
AUXILIARY option commands 9
WRITEQ TS 338 delete a record from data set 146
exceptional conditions 151
read record from data set 157
B request next record number 151
back out to a syncpoint 315 send data to output device 162
BASE operand terminate data set 131, 141
DFHMSD 397 update a record in data set 159
BASE value wait for function completion 166
DFHMDF 389 batch logical unit, 3770 48, 206, 249
DFHMDI 394

Index 407
batch mode application, 3740 60, 216, 260 CASE operand
BELOW option DFHMDF 385
GETMAIN 121 CBIDERR condition
BIF DEEDIT command 30 ALLOCATE (APPC) 16
BLANK value ALLOCATE (LUTYPE6.1) 18
DFHMDF 386 CONVERSE (non-VTAM) 63
BLINK value CONVERSE (VTAM) 51
DFHMDF 386 EXTRACT ATTACH (LUTYPE6.1) 83
DFHMDI 393 EXTRACT ATTACH (MRO) 85
DFHMSD 399 SEND (non-VTAM) 262
BLOCK value SEND (VTAM) 253
DFHMDI 392 CBUFF option
DFHMSD 398 SEND (non-VTAM) 261
BMS CHANGE PASSWORD command 37
See basic mapping support CHANGE TASK command 38
BOTTOM value CHANGETIME option
DFHMDI 393 VERIFY PASSWORD 318
browse operation CHARSZE operand
ending 77 DFHPDI 403
read next record 189 DFHPSD 404
read previous record 193 CICSDATAKEY option
reset starting point 229 GETMAIN 121
starting 309 CLASS option
BRT value SPOOLOPEN 296
DFHMDF 384 SPOOLOPEN INPUT 294
BTAM programmable terminals 358 CLEAR option
BTRANS option HANDLE AID 125
ASSIGN 24 CLRPARTN option
BUFFER option HANDLE AID 125
GDS RECEIVE 115 CMDSEC option
RECEIVE (non-VTAM) 218 ASSIGN 24
RECEIVE (VTAM) 208 CNOTCOMPL option
BUFSZE operand SEND (non-VTAM) 261
DFHPDI macro 403 SEND (VTAM) 252
BUILD ATTACH (LUTYPE6.1) command 31 COBOL
BUILD ATTACH (MRO) command 33 argument values 2
built-in functions translated code 353
commands 9 CODEREG operand 355
COLOR operand
DFHMDF 385
C DFHMDI 391
C language DFHMSD 397
ADDRESS COMMAREA 13 COLOR option
ADDRESS EIB 13 ASSIGN 24
argument values 2 COLUMN operand
LENGTH option default 3 DFHMDI 391
translated code 353 command language translator
CANCEL command 35 translated code 353
CANCEL option commands
ABEND 12 format, arguments 1
HANDLE ABEND 123 security 10
CARD option spool 10
ISSUE ABORT 131 temporary storage control 10
ISSUE END 141 COMMAREA option
ISSUE SEND 162 ADDRESS 13
ISSUE WAIT 166 LINK 169

408 CICS/ESA Application Programming Reference

COMMAREA option (continued) CONVERSE (3740) command 60
RETURN 235 CONVERSE (3767) command 47
XCTL 341 CONVERSE (3770) command 48
common buffer, output to, 2980 214 CONVERSE (3790 3270-display) command 49
common programming interface communications (CPI CONVERSE (3790 full-function or inquiry) command 48
Communications) 365 CONVERSE (APPC) command 41
COMPLETE option CONVERSE (LUTYPE2/LUTYPE3) command 42
DUMP TRANSACTION 74 CONVERSE (LUTYPE4) command 42
CONFIRM option CONVERSE (LUTYPE6.1) command 43
GDS SEND 117 CONVERSE (MRO) command 53
SEND (VTAM) 252 CONVERSE (non-VTAM default) command 53
CONNECT PROCESS command 39 CONVERSE (SCS) command 43
CONSOLE option CONVERSE (System/3) command 54
ISSUE ABORT 131 CONVERSE (System/7) command 54
ISSUE END 141 CONVERSE (VTAM default) command 41
ISSUE SEND 162 CONVERSE option
ISSUE WAIT 166 ISSUE LOAD 150
console support commands 9 converse with terminal or LU 358
constants CONVID option
AID values, DFHAID 379 CONNECT PROCESS 39
attribute values, DFHBMSCA 375 CONVERSE (non-VTAM) 61
for 3270 attributes 375 CONVERSE (VTAM) 50
for examining EIBAID field 379 EXTRACT ATTACH (LUTYPE6.1) 82
for MSR control values 377 EXTRACT ATTACH (MRO) 84
for printer format controls 375 EXTRACT ATTRIBUTES (APPC) 86
MSR control, DFHtex read 377 EXTRACT ATTRIBUTES (MRO) 87
printer control values, DFHBMSCA 375 EXTRACT PROCESS 89
CONTROL option FREE (APPC) 96
QUERY SECURITY 182 FREE (LUTYPE6.1) 97
CONVDATA option FREE (MRO) 98
GDS CONNECT PROCESS 105 GDS ALLOCATE 102
GDS EXTRACT ATTRIBUTES 107 GDS CONNECT PROCESS 105
GDS FREE 109 GDS EXTRACT ATTRIBUTES 107
GDS ISSUE ABEND 110 GDS EXTRACT PROCESS 108
GDS ISSUE CONFIRMATION 111 GDS FREE 109
GDS ISSUE ERROR 112 GDS ISSUE ABEND 110
GDS ISSUE PREPARE 113 GDS ISSUE CONFIRMATION 111
GDS ISSUE SIGNAL 114 GDS ISSUE ERROR 112
GDS RECEIVE 115 GDS ISSUE PREPARE 113
GDS SEND 117 GDS ISSUE SIGNAL 114
GDS WAIT 119 GDS RECEIVE 115
CONVERSE (2260) command 55 GDS SEND 117
CONVERSE (2741) command 56 GDS WAIT 119
CONVERSE (2770) command 57 ISSUE ABEND 130
CONVERSE (2780) command 57 ISSUE CONFIRMATION 135
CONVERSE (3270 display) command 58 ISSUE ERROR 149
CONVERSE (3270 logical) command 44 ISSUE PREPARE 154
CONVERSE (3600 BTAM) command 58 ISSUE SIGNAL (APPC) 164
CONVERSE (3600-3601) command 44 ISSUE SIGNAL (LUTYPE6.1) 165
CONVERSE (3600-3614) command 45 POINT 176
CONVERSE (3650 interpreter) command 45 RECEIVE (VTAM) 208
CONVERSE (3650-3270) command 46 SEND (VTAM) 252
CONVERSE (3650-3653) command 46 WAIT CONVID 320
CONVERSE (3650-3680) command 47 WAIT TERMINAL 326
CONVERSE (3735) command 59 copy displayed information 361

Index 409
copybooks CVDA options (continued)
DFHAID 379 PURGEABILITY
DFHBMSCA 375 WAIT EXTERNAL 323
DFHEIBLK 355 WAITCICS 328
DFHMSRCA 377 READ
CPI Communications (SAA) 365 QUERY SECURITY 182
create a journal record 332 STATE 51, 63, 209, 219, 253, 262
CSMT transaction ALLOCATE (APPC) 16
resend message destination 59 ALLOCATE (MRO) 20
CSTL transaction CONNECT PROCESS 39
resend message destination 59 EXTRACT ATTRIBUTES (APPC) 86
CTLCHAR option EXTRACT ATTRIBUTES (MRO) 87
CONVERSE (non-VTAM) 61 FREE (APPC) 96
CONVERSE (VTAM) 50 FREE (MRO) 98
ISSUE COPY (3270 display) 137 GDS ALLOCATE 102
ISSUE COPY (3270 logical) 138 GDS CONNECT PROCESS 105
SEND (non-VTAM) 261 GDS EXTRACT ATTRIBUTES 107
SEND (VTAM) 252 GDS FREE 109
CTRL operand GDS ISSUE ABEND 110
DFHMDI 391 GDS ISSUE CONFIRMATION 111
DFHMSD 397 GDS ISSUE ERROR 112
CURRENT option GDS ISSUE PREPARE 113
SEND PAGE 276 GDS ISSUE SIGNAL 114
CURSLOC operand GDS RECEIVE 116
DFHMDI 392 GDS SEND 118
DFHMSD 398 GDS WAIT 119
cursor address 361 ISSUE ABEND 130
CURSOR option ISSUE CONFIRMATION 135
RECEIVE MAP MAPPINGDEV command 223 ISSUE ERROR 149
SEND CONTROL 265 ISSUE PREPARE 154
SEND MAP 269 ISSUE SIGNAL (APPC) 164
SEND MAP MAPPINGDEV command 274 WAIT CONVID 320
SEND TEXT 281 UPDATE
cursor position QUERY SECURITY 183
terminal control 361 CVDA values
CVDA (CICS-value data area) ALLOCATED
argument values 2 ALLOCATE (APPC) 16
command format 2 ALLOCATE (MRO) 20
passing and receiving 5 CONNECT PROCESS 39
values in alphabetic order 371 EXTRACT ATTRIBUTES (APPC) 86
values in numeric order 371 EXTRACT ATTRIBUTES (MRO) 87
CVDA options FREE (APPC) 96
ACTION FREE (MRO) 98
WRITE OPERATOR 334 GDS ALLOCATE 102
ALTER GDS CONNECT PROCESS 105
QUERY SECURITY 182 GDS EXTRACT ATTRIBUTES 107
ASRAKEY GDS FREE 109
ASSIGN 23 GDS ISSUE ABEND 110
ASRASPC GDS ISSUE CONFIRMATION 111
ASSIGN 24 GDS ISSUE ERROR 112
CONTROL GDS ISSUE PREPARE 113
QUERY SECURITY 182 GDS ISSUE SIGNAL 114
LOGMESSAGE GDS RECEIVE 116
QUERY SECURITY 182 GDS SEND 118
MAXLIFETIME GDS WAIT 119
DEQ 72 ISSUE ABEND 130
ENQ 79 ISSUE CONFIRMATION 135

410 CICS/ESA Application Programming Reference

CVDA values (continued) CVDA values (continued)
ALLOCATED (continued) CONFRECEIVE (continued)
ISSUE ERROR 149 ISSUE CONFIRMATION 135
ISSUE PREPARE 154 ISSUE ERROR 149
ISSUE SIGNAL (APPC) 164 ISSUE PREPARE 154
RECEIVE (APPC) 209 ISSUE SIGNAL (APPC) 164
RECEIVE (MRO) 219 RECEIVE (APPC) 209
SEND (APPC) 253 SEND (APPC) 253
SEND (MRO) 262 WAIT CONVID 320
WAIT CONVID 320 CONFSEND
ALTERABLE CONNECT PROCESS 39
QUERY SECURITY 182 EXTRACT ATTRIBUTES (APPC) 86
BASESPACE FREE (APPC) 96
ASSIGN 24 GDS ALLOCATE 102
CICSEXECKEY GDS CONNECT PROCESS 105
ASSIGN 23 GDS EXTRACT ATTRIBUTES 107
CONFFREE GDS FREE 109
CONNECT PROCESS 39 GDS ISSUE ABEND 110
EXTRACT ATTRIBUTES (APPC) 86 GDS ISSUE CONFIRMATION 111
FREE (APPC) 96 GDS ISSUE ERROR 112
GDS ALLOCATE 102 GDS ISSUE PREPARE 113
GDS CONNECT PROCESS 105 GDS ISSUE SIGNAL 114
GDS EXTRACT ATTRIBUTES 107 GDS RECEIVE 116
GDS FREE 109 GDS SEND 118
GDS ISSUE ABEND 110 GDS WAIT 119
GDS ISSUE CONFIRMATION 111 ISSUE ABEND 130
GDS ISSUE ERROR 112 ISSUE CONFIRMATION 135
GDS ISSUE PREPARE 113 ISSUE ERROR 149
GDS ISSUE SIGNAL 114 ISSUE PREPARE 154
GDS RECEIVE 116 ISSUE SIGNAL (APPC) 164
GDS SEND 118 RECEIVE (APPC) 209
GDS WAIT 119 SEND (APPC) 253
ISSUE ABEND 130 WAIT CONVID 320
ISSUE CONFIRMATION 135 CRITICAL
ISSUE ERROR 149 WRITE OPERATOR 334
ISSUE PREPARE 154 CTRLABLE
ISSUE SIGNAL (APPC) 164 QUERY SECURITY 182
RECEIVE (APPC) 209 EVENTUAL
SEND (APPC) 253 WRITE OPERATOR 334
WAIT CONVID 320 FREE
CONFRECEIVE CONNECT PROCESS 39
CONNECT PROCESS 39 EXTRACT ATTRIBUTES (APPC) 86
EXTRACT ATTRIBUTES (APPC) 86 EXTRACT ATTRIBUTES (MRO) 87
FREE (APPC) 96 FREE (APPC) 96
GDS ALLOCATE 102 FREE (MRO) 98
GDS CONNECT PROCESS 105 GDS ALLOCATE 102
GDS EXTRACT ATTRIBUTES 107 GDS CONNECT PROCESS 105
GDS FREE 109 GDS EXTRACT ATTRIBUTES 107
GDS ISSUE ABEND 110 GDS FREE 109
GDS ISSUE CONFIRMATION 111 GDS ISSUE ABEND 110
GDS ISSUE ERROR 112 GDS ISSUE CONFIRMATION 111
GDS ISSUE PREPARE 113 GDS ISSUE ERROR 112
GDS ISSUE SIGNAL 114 GDS ISSUE PREPARE 113
GDS RECEIVE 116 GDS ISSUE SIGNAL 114
GDS SEND 118 GDS RECEIVE 116
GDS WAIT 119 GDS SEND 118
ISSUE ABEND 130 GDS WAIT 119

Index 411
CVDA values (continued) CVDA values (continued)
FREE (continued) PENDFREE (continued)
ISSUE ABEND 130 ISSUE PREPARE 154
ISSUE CONFIRMATION 135 ISSUE SIGNAL (APPC) 164
ISSUE ERROR 149 RECEIVE (APPC) 209
ISSUE PREPARE 154 RECEIVE (MRO) 219
ISSUE SIGNAL (APPC) 164 SEND (APPC) 253
RECEIVE (APPC) 209 SEND (MRO) 262
RECEIVE (MRO) 219 WAIT CONVID 320
SEND (APPC) 253 PENDRECEIVE
SEND (MRO) 262 CONNECT PROCESS 39
WAIT CONVID 320 EXTRACT ATTRIBUTES (APPC) 86
IMMEDIATE FREE (APPC) 96
WRITE OPERATOR 334 GDS ALLOCATE 102
LOG GDS CONNECT PROCESS 105
QUERY SECURITY 182 GDS EXTRACT ATTRIBUTES 107
LUW GDS FREE 109
DEQ 72 GDS ISSUE ABEND 110
ENQ 79 GDS ISSUE CONFIRMATION 111
NOLOG GDS ISSUE ERROR 112
QUERY SECURITY 182 GDS ISSUE PREPARE 113
NONCICS GDS ISSUE SIGNAL 114
ASSIGN 23 GDS RECEIVE 116
NOTALTERABLE GDS SEND 118
QUERY SECURITY 182 GDS WAIT 119
NOTAPPLIC ISSUE ABEND 130
ASSIGN 23, 24 ISSUE CONFIRMATION 135
NOTCTRLABLE ISSUE ERROR 149
QUERY SECURITY 182 ISSUE PREPARE 154
NOTPURGEABLE ISSUE SIGNAL (APPC) 164
WAIT EXTERNAL 323 RECEIVE (APPC) 209
WAITCICS 328 SEND (APPC) 253
NOTREADABLE WAIT CONVID 320
QUERY SECURITY 182 PURGEABLE
NOTUPDATABLE WAIT EXTERNAL 323
QUERY SECURITY 183 WAITCICS 328
PENDFREE READABLE
CONNECT PROCESS 39 QUERY SECURITY 182
EXTRACT ATTRIBUTES (APPC) 86 RECEIVE
EXTRACT ATTRIBUTES (MRO) 87 CONNECT PROCESS 39
FREE (APPC) 96 CONVERSE (MRO) 63
FREE (MRO) 98 EXTRACT ATTRIBUTES (APPC) 86
GDS ALLOCATE 102 EXTRACT ATTRIBUTES (MRO) 87
GDS CONNECT PROCESS 105 FREE (APPC) 96
GDS EXTRACT ATTRIBUTES 107 FREE (MRO) 98
GDS FREE 109 GDS ALLOCATE 102
GDS ISSUE ABEND 110 GDS CONNECT PROCESS 105
GDS ISSUE CONFIRMATION 111 GDS EXTRACT ATTRIBUTES 107
GDS ISSUE ERROR 112 GDS FREE 109
GDS ISSUE PREPARE 113 GDS ISSUE ABEND 110
GDS ISSUE SIGNAL 114 GDS ISSUE CONFIRMATION 111
GDS RECEIVE 116 GDS ISSUE ERROR 112
GDS SEND 118 GDS ISSUE PREPARE 113
GDS WAIT 119 GDS ISSUE SIGNAL 114
ISSUE ABEND 130 GDS RECEIVE 116
ISSUE CONFIRMATION 135 GDS SEND 118
ISSUE ERROR 149 GDS WAIT 119

412 CICS/ESA Application Programming Reference

CVDA values (continued) CVDA values (continued)
RECEIVE (continued) SEND (continued)
ISSUE ABEND 130 GDS RECEIVE 116
ISSUE CONFIRMATION 135 GDS SEND 118
ISSUE ERROR 149 GDS WAIT 119
ISSUE PREPARE 154 ISSUE ABEND 130
ISSUE SIGNAL (APPC) 164 ISSUE CONFIRMATION 135
RECEIVE (APPC) 209 ISSUE ERROR 149
RECEIVE (MRO) 219 ISSUE PREPARE 154
SEND (APPC) 253 ISSUE SIGNAL (APPC) 164
SEND (MRO) 262 RECEIVE (APPC) 209
WAIT CONVID 320 RECEIVE (MRO) 219
ROLLBACK SEND (APPC) 253
CONNECT PROCESS 39 SEND (MRO) 262
CONVERSE (MRO) 63 WAIT CONVID 320
EXTRACT ATTRIBUTES (APPC) 86 SUBSPACE
EXTRACT ATTRIBUTES (MRO) 87 ASSIGN 24
FREE (APPC) 96 SYNCFREE
FREE (MRO) 98 CONNECT PROCESS 39
GDS ALLOCATE 102 CONVERSE (MRO) 63
GDS CONNECT PROCESS 105 EXTRACT ATTRIBUTES (APPC) 86
GDS EXTRACT ATTRIBUTES 107 EXTRACT ATTRIBUTES (MRO) 87
GDS FREE 109 FREE (APPC) 96
GDS ISSUE ABEND 110 FREE (MRO) 98
GDS ISSUE CONFIRMATION 111 GDS ALLOCATE 102
GDS ISSUE ERROR 112 GDS CONNECT PROCESS 105
GDS ISSUE PREPARE 113 GDS EXTRACT ATTRIBUTES 107
GDS ISSUE SIGNAL 114 GDS FREE 109
GDS RECEIVE 116 GDS ISSUE ABEND 110
GDS SEND 118 GDS ISSUE CONFIRMATION 111
GDS WAIT 119 GDS ISSUE ERROR 112
ISSUE ABEND 130 GDS ISSUE PREPARE 113
ISSUE CONFIRMATION 135 GDS ISSUE SIGNAL 114
ISSUE ERROR 149 GDS RECEIVE 116
ISSUE PREPARE 154 GDS SEND 118
ISSUE SIGNAL (APPC) 164 GDS WAIT 119
RECEIVE (APPC) 209 ISSUE ABEND 130
RECEIVE (MRO) 219 ISSUE CONFIRMATION 135
SEND (APPC) 253 ISSUE ERROR 149
SEND (MRO) 262 ISSUE PREPARE 154
WAIT CONVID 320 ISSUE SIGNAL (APPC) 164
SEND RECEIVE (APPC) 209
CONNECT PROCESS 39 RECEIVE (MRO) 219
CONVERSE (MRO) 63 SEND (APPC) 253
EXTRACT ATTRIBUTES (APPC) 86 SEND (MRO) 262
EXTRACT ATTRIBUTES (MRO) 87 WAIT CONVID 320
FREE (APPC) 96 SYNCRECEIVE
FREE (MRO) 98 CONNECT PROCESS 39
GDS ALLOCATE 102 CONVERSE (MRO) 63
GDS CONNECT PROCESS 105 EXTRACT ATTRIBUTES (APPC) 86
GDS EXTRACT ATTRIBUTES 107 EXTRACT ATTRIBUTES (MRO) 87
GDS FREE 109 FREE (APPC) 96
GDS ISSUE ABEND 110 FREE (MRO) 98
GDS ISSUE CONFIRMATION 111 GDS ALLOCATE 102
GDS ISSUE ERROR 112 GDS CONNECT PROCESS 105
GDS ISSUE PREPARE 113 GDS EXTRACT ATTRIBUTES 107
GDS ISSUE SIGNAL 114 GDS FREE 109

Index 413
CVDA values (continued) CWA option
SYNCRECEIVE (continued) ADDRESS 13
GDS ISSUE ABEND 110 CWALENG option
GDS ISSUE CONFIRMATION 111 ASSIGN 24
GDS ISSUE ERROR 112
GDS ISSUE PREPARE 113
GDS ISSUE SIGNAL 114 D
GDS RECEIVE 116 Data Facility Product (DFP)
GDS SEND 118 duct xi
GDS WAIT 119 DATA operand
ISSUE ABEND 130 DFHMDI 392
ISSUE CONFIRMATION 135 DFHMSD 398
ISSUE ERROR 149 DATA option
ISSUE PREPARE 154 FREEMAIN 101
ISSUE SIGNAL (APPC) 164 data sets
RECEIVE (APPC) 209 add records to 133
RECEIVE (MRO) 219 interrogating 156
SEND (APPC) 253 processing termination 141
SEND (MRO) 262 read records from 157
WAIT CONVID 320 update records 159
SYNCSEND data tables
CONNECT PROCESS 39 CICS/user-maintained
CONVERSE (MRO) 63 DELETE 67
EXTRACT ATTRIBUTES (APPC) 86 ENDBR 77
EXTRACT ATTRIBUTES (MRO) 87 READ 185
FREE (APPC) 96 READNEXT 189
FREE (MRO) 98 READPREV 193
GDS ALLOCATE 102 RESETBR 229
GDS CONNECT PROCESS 105 REWRITE 237
GDS EXTRACT ATTRIBUTES 107 STARTBR 309
GDS FREE 109 UNLOCK 316
GDS ISSUE ABEND 110 WRITE 329
GDS ISSUE CONFIRMATION 111 data to output device, sending 162
GDS ISSUE ERROR 112 data-area argument
GDS ISSUE PREPARE 113 CICS command format 2
GDS ISSUE SIGNAL 114 definition 1
GDS RECEIVE 116 data-value argument
GDS SEND 118 CICS command format 2
GDS WAIT 119 definition 1
ISSUE ABEND 130 data, deleting
ISSUE CONFIRMATION 135 file control records 67
ISSUE ERROR 149 temporary storage queues 71
ISSUE PREPARE 154 transient data queues 70
ISSUE SIGNAL (APPC) 164 data, passing to new tasks 305
RECEIVE (APPC) 209 DATA1 option
RECEIVE (MRO) 219 MONITOR 175
SEND (APPC) 253 DATA2 option
SEND (MRO) 262 MONITOR 175
WAIT CONVID 320 DATALENGTH option
TASK LINK 169
DEQ 72 DATAONLY option
ENQ 79 SEND MAP 269
UPDATABLE SEND MAP MAPPINGDEV command 274
QUERY SECURITY 183 DATAPOINTER option
USEREXECKEY FREEMAIN 101
ASSIGN 23

414 CICS/ESA Application Programming Reference

DATAREG operand 355 delay processing, task 65
DATASTR option DELETE command 67
BUILD ATTACH (LUTYPE6.1) 31 delete loaded program 227
BUILD ATTACH (MRO) 33 DELETE option
EXTRACT ATTACH (LUTYPE6.1) 82 SPOOLCLOSE 293
EXTRACT ATTACH (MRO) 84 delete records
DATE option batch data interchange records 146
FORMATTIME 92 DELETEQ TD command 70
DATEFORM option DELETEQ TS command 71
FORMATTIME 92 deleting data
DATESEP option temporary storage queues 71
FORMATTIME 93 transient data queues 70
DAYCOUNT option DELIMITER option
FORMATTIME 93 ASSIGN 24
DAYOFMONTH option DEQ command 72
FORMATTIME 93 dequeue from resource 72
DAYOFWEEK option DEST option
FORMATTIME 93 CONVERSE (non-VTAM) 61
DAYSLEFT option CONVERSE (VTAM) 50
VERIFY PASSWORD 318 SEND (non-VTAM) 261
DCT option SEND (VTAM) 252
DUMP TRANSACTION 74 DESTCOUNT option
DDMMYY option ASSIGN 24
FORMATTIME 93 DESTID option
DDMMYYYY option ASSIGN 24
FORMATTIME 93 ISSUE ABORT 131
DEBKEY option ISSUE ADD 133
READ 185 ISSUE END 141
STARTBR 309 ISSUE ERASE 146
DEBREC option ISSUE NOTE 151
READ 185 ISSUE QUERY 156
STARTBR 309 ISSUE REPLACE 159
DEFAULT option ISSUE SEND 162
CONVERSE (non-VTAM) 61 ISSUE WAIT 166
CONVERSE (VTAM) 50 DESTIDLENG option
SEND (non-VTAM) 261 ASSIGN 25
SEND (VTAM) 252 ISSUE ABORT 131
SEND CONTROL 265 ISSUE ADD 133
SEND MAP 269 ISSUE END 141
SEND TEXT 281 ISSUE ERASE 146
SEND TEXT NOEDIT 286 ISSUE NOTE 151
DEFRESP option ISSUE QUERY 156
CONVERSE (non-VTAM) 61 ISSUE REPLACE 159
CONVERSE (VTAM) 50 ISSUE SEND 162
ISSUE ADD 133 ISSUE WAIT 166
ISSUE ERASE 146 DET value
ISSUE REPLACE 159 DFHMDF 384
ISSUE SEND 162 DFH2980 structure 214
SEND (non-VTAM) 261 DFHAID attention identifier list 379
SEND (VTAM) 252 DFHBMSCA, standard attribute and printer control character
DEFSCRNHT option list, BMS 375
ASSIGN 24 DFHEAI interface processor 354
DEFSCRNWD option DFHECALL macro 353
ASSIGN 24 DFHEIBLK copybook 355
DELAY command 65 DFHEICAL macro, use DFHECALL 353

Index 415
DFHEIEND macro 353 DSSCS option
DFHEIENT macro ASSIGN 25
CODEREG 355 DSSTAT condition
DATAREG 355 ISSUE RECEIVE 157
defaults 355 DUMP TRANSACTION command 74
description 353 DUMPCODE option
EIBREG 355 DUMP TRANSACTION 74
DFHEIGBL macro 353 DUMPID option
DFHEIPLR symbolic register 356 DUMP TRANSACTION 74
DFHEIRET macro 354 DUPKEY condition
DFHEISTG macro 355 DELETE 68
DFHMDF macro 383 READ 187
DFHMDI macro 390 READNEXT 191
DFHMIRS 169 READPREV 194
DFHMSD macro 396 DUPREC condition
DFHMSRCA, MSR control value constants 377 REWRITE 237
DFHPDI macro 403 WRITE 330
DFHPSD macro 404 dynamic allocation 296
DFHRESP, built-in function 5 dynamic storage, extensions 355
DFHVALUE, translator routine 5
DFP, Data Facility Product xi
diagnostic services commands 9 E
DISABLED condition ECADDR option
DELETE 68 WAIT EVENT 321
DELETEQ TD 70 ECBLIST option
READ 187 WAIT EXTERNAL 323
READQ TD 197 WAITCICS 328
STARTBR 310 EDF, execution diagnostic facility 308
UNLOCK 316 EIB fields
WRITE 330 EIBAID 343
WRITEQ TD 336 EIBATT 343
disconnect a switched line 358 EIBCALEN 343
display-device operations EIBCOMPL 343
attention identifier (AID) 361 EIBCONF 343
attention identifier list, DFHAID 379 EIBCPOSN 343
copy displayed information 361 EIBDATE 343
cursor address 361 EIBDS 343
erase all unprotected fields 361 EIBEOC 343
input operation without data 361 EIBERR 344
pass control on receipt of an AID 125, 129 EIBERRCD 344
print displayed information 360 EIBFMH 344
standard attribute and printer control character list, EIBFN 344
DFHBMSCA 375 EIBFREE 345
terminal 360 EIBNODAT 345
distributed program link (DPL) EIBRCODE 345
ogram link 367 EIBRECV 348
DPL, distributed program link 367 EIBREQID 348
DRK value EIBRESP 349
DFHMDF 384 EIBRESP2 349
DS3270 option EIBRLDBK 349
ASSIGN 25 EIBRSRCE 349
DSATTS operand EIBSIG 349
DFHMDI 393 EIBSYNC 350
DFHMSD 398 EIBSYNRB 350
DSECT value EIBTASKN 350
DFHMSD 401 EIBTIME 350

416 CICS/ESA Application Programming Reference

EIB fields (continued) EOF condition (continued)
EIBTRMID 350 RECEIVE (non-VTAM) 219
EIBTRNID 350 EQUAL option
EIB option READ 185
ADDRESS 13 RESETBR 229
EIBAID 361 STARTBR 309
examining contents of field 379 equated symbols 4
EIBREG operand 355 erase all unprotected fields 361
ENDBR command 77 ERASE option
ENDDATA condition CONVERSE (non-VTAM) 61
RETRIEVE 234 CONVERSE (VTAM) 50
ENDFILE condition SEND (non-VTAM) 261
READNEXT 191 SEND (VTAM) 252
READPREV 194 SEND CONTROL 265
ENDFILE option SEND MAP 269
ISSUE ENDOUTPUT 144 SEND MAP MAPPINGDEV command 274
ENDINPT condition SEND TEXT 281
RECEIVE (non-VTAM) 219 SEND TEXT NOEDIT 286
ENDOUTPUT option ERASEAUP option
ISSUE ENDFILE 143 SEND CONTROL 265
English and katakana characters, mixed 61, 220, 225 SEND MAP 269
ENQ command 78 SEND MAP MAPPINGDEV command 274
ENQBUSY condition ERRTERM option
ENQ 79 ROUTE 239
ENTER option ESDS (entry-sequenced data set)
HANDLE AID 125 DELETE 68
ENTER TRACEID READ 186
monitoring aspects replaced by MONITOR 174 STARTBR 310
tracing aspects replaced by ENTER TRACENUM 80 WRITE 329
ENTER TRACENUM command 80 ESM
ENTRY option ACEE pointer 13
LOAD 172 QUERY SECURITY, NOTFND 184
entry to assembler-language program 353 QUERY SECURITY, RESCLASS 182
ENTRYNAME option USERNAME 29
MONITOR 175 ESM, external security manager 308
ENVDEFERR condition ESMREASON option
RETRIEVE 234 CHANGE PASSWORD 37
environment services SIGNON 290
commands 9 VERIFY PASSWORD 318
EOC condition ESMRESP option
ALLOCATE (LUTYPE6.1) 18 CHANGE PASSWORD 37
CONVERSE (non-VTAM) 64 SIGNON 290
CONVERSE (VTAM) 52 VERIFY PASSWORD 318
ISSUE RECEIVE 157 events, timer
RECEIVE (non-VTAM) 219 control area, timer 178
RECEIVE (VTAM) 209 monitoring point 174
RECEIVE MAP 221 waiting for 321
RECEIVE PARTN 226 EWASUPP option
EODS condition ASSIGN 25
CONVERSE (VTAM) 52 EXCEPTION option
ISSUE RECEIVE 158 ENTER TRACENUM 80
RECEIVE (VTAM) 209 exception support commands 9
RECEIVE MAP 221 exclusive control release, UNLOCK command 316
RECEIVE PARTN 226 EXEC CICS command format 1
EOF condition EXEC CICS DLI interface
CONVERSE (non-VTAM) 64 No longer documented xi

Index 417
execution diagnostic facility (EDF) 308 FILE option (continued)
exit from ASM program 354 READ 185
exit, abnormal termination recovery 123 READNEXT 189
expiration time, notification when reached 178 READPREV 193
EXPIRED condition RESETBR 229
DELAY 66 REWRITE 237
POST 179 STARTBR 309
WRITE OPERATOR 335 UNLOCK 316
EXPIRYTIME option WRITE 329
VERIFY PASSWORD 318 filename
EXTATT operand definition 2, 3, 4
DFHMDI 393 filename argument, CICS command format 2
DFHMSD 398 FILENOTFOUND condition
EXTDS option DELETE 68
ASSIGN 25 ENDBR 77
external security manager (ESM) 182, 308 READ 187
EXTRACT ATTACH (LUTYPE6.1) command 82 READNEXT 191
EXTRACT ATTACH (MRO) command 84 READPREV 194
EXTRACT ATTRIBUTES (APPC) command 86 RESETBR 230
EXTRACT ATTRIBUTES (MRO) command 87 REWRITE 237
EXTRACT LOGONMSG command 88 STARTBR 310
EXTRACT PROCESS command 89 UNLOCK 316
EXTRACT TCT command 91 WRITE 330
FIRST value
DFHMDI 393
F FLDSEP operand
FACILITY option DFHMDI 393
ASSIGN 25 DFHMSD 398
FCI option FLENGTH option
ASSIGN 25, 351 DUMP TRANSACTION 74
FCT option fullword alternative to LENGTH 357
DUMP TRANSACTION 74 GDS RECEIVE 115
field definition macro, BMS 381 GDS SEND 117
field edit built-in function GETMAIN 121
See BIF DEEDIT LOAD 172
FIELD option RECEIVE (non-VTAM) 218
BIF DEEDIT 30 RECEIVE (VTAM) 208
field separator operand 393, 398 SEND (non-VTAM) 261
FIELD value SEND (VTAM) 252
DFHMDI 392 SPOOLWRITE 301
DFHMSD 398 FMH option
FIELDS operand CONVERSE (non-VTAM) 62
DFHMDI 393 CONVERSE (VTAM) 50
file control SEND (non-VTAM) 261
commands 10 SEND (VTAM) 252
deleting VSAM records 67 START 306
end browse operation 77 FMHPARM option
read next record 189 SEND MAP 269
read previous record 193 SEND PAGE 276
release exclusive control 316 SEND TEXT 281
specify start for browse 309 FOLD operand
update a record 237 DFHMSD 399
writing new record 329 FOR option
FILE option DELAY 65
DELETE 67 FORMATTIME command 92
ENDBR 77

418 CICS/ESA Application Programming Reference

FORMFEED option FRSET option
SEND CONTROL 265 SEND CONTROL 265
SEND MAP 269 SEND MAP 269
SEND MAP MAPPINGDEV command 275 SEND MAP MAPPINGDEV command 275
SEND TEXT 281 FRSET value
FREE (APPC) command 96 DFHMDI 392
FREE (LUTYPE6.1) command 97 DFHMSD 398
FREE (MRO) command 98 FSET value
FREE command 95 DFHMDF 384
free main storage 99 Full Function Logical Unit, 3790 48, 207, 250
FREEKB option FULLDATE option
SEND CONTROL 265 FORMATTIME 93
SEND MAP 269 fullword length option 357
SEND MAP MAPPINGDEV command 275 FUNCERR condition
SEND TEXT 281 ISSUE ABORT 131
SEND TEXT NOEDIT 286 ISSUE ADD 133
FREEKB value ISSUE END 141
DFHMDI 392 ISSUE ERASE 147
DFHMSD 398 ISSUE NOTE 151
FREEMAIN command 99 ISSUE QUERY 156
FROM option ISSUE REPLACE 160
CONVERSE (non-VTAM) 62 ISSUE SEND 163
CONVERSE (VTAM) 50 ISSUE WAIT 166
DUMP TRANSACTION 74 function management header
ENTER TRACENUM 80 See FMH
GDS SEND 117
ISSUE ADD 133
ISSUE PASS 152 G
ISSUE REPLACE 159 GCHARS option
ISSUE SEND 162 ASSIGN 25
RECEIVE MAP 220 GCODES option
RECEIVE MAP MAPPINGDEV command 223 ASSIGN 25
REWRITE 237 GDS (generalized data stream) 9
SEND (non-VTAM) 261 GDS ALLOCATE command 102
SEND (VTAM) 252 GDS ASSIGN command 104
SEND MAP 269 GDS CONNECT PROCESS command 105
SEND MAP MAPPINGDEV command 275 GDS EXTRACT ATTRIBUTES command 107
SEND TEXT 281 GDS EXTRACT PROCESS command 108
SEND TEXT MAPPED 284 GDS FREE command 109
SEND TEXT NOEDIT 286 GDS ISSUE ABEND command 110
SPOOLWRITE 301 GDS ISSUE CONFIRMATION command 111
START 306 GDS ISSUE ERROR command 112
WRITE 329 GDS ISSUE PREPARE command 113
WRITE JOURNALNUM 332 GDS ISSUE SIGNAL command 114
WRITEQ TD 336 GDS RECEIVE command 115
WRITEQ TS 338 GDS SEND command 117
FROMFLENGTH option GDS WAIT command 119
CONVERSE (non-VTAM) 62 General Banking Terminal System (2980 General Banking
CONVERSE (VTAM) 50 Terminal System) 213
fullword alternative to FROMLENGTH 357 generalized data stream (GDS) 9
FROMLENGTH option generic applid, XRF 23
CONVERSE (non-VTAM) 62 GENERIC option
CONVERSE (VTAM) 50 DELETE 67
ENTER TRACENUM 80 READ 186
fullword length alternative (FROMFLENGTH) 357 RESETBR 229
STARTBR 309

Index 419
get main storage 120 IGREQCD condition
GETMAIN command 120 CONVERSE (VTAM) 52
GINIT operand ISSUE SEND 163
DFHMDF 385 SEND (VTAM) 253
GMMI option SEND CONTROL 266
ASSIGN 25 SEND MAP 271
GROUPID option SEND PAGE 277
SIGNON 290 SEND TEXT 283
GRPNAME operand SEND TEXT MAPPED 284
DFHMDF 385 SEND TEXT NOEDIT 287
GTEQ option IGREQID condition
READ 186 SEND CONTROL 266
RESETBR 229 SEND MAP 271
STARTBR 309 SEND TEXT 283
SEND TEXT MAPPED 285
SEND TEXT NOEDIT 287
H ILLOGIC condition
HANDLE ABEND command 123 DELETE 68
HANDLE AID command 125 EIBRCODE 348
HANDLE CONDITION command 127 ENDBR 77
HEADER operand READ 187
DFHMDI 393 READNEXT 191
HEADER option READPREV 194
SEND TEXT 281 RESETBR 230
hhmmss argument, CICS command format 2 REWRITE 237
HILIGHT operand STARTBR 310
DFHMDF 386 UNLOCK 316
DFHMDI 393 WRITE 330
DFHMSD 399 IMMEDIATE option
HILIGHT option RETURN 235
ASSIGN 25 implicit SPOOLCLOSE 294
HOLD option INBFMH condition
LOAD 172 CONVERSE (non-VTAM) 64
HONEOM option CONVERSE (VTAM) 52
SEND CONTROL 265 RECEIVE (non-VTAM) 219
SEND MAP 269 RECEIVE (VTAM) 209
SEND TEXT 281 INITIAL operand
SEND TEXT NOEDIT 286 DFHMDF 386
host command processor LU, 3650/3680 248 initialize main storage 120
host conversational LU 3650 initiate a task 305
(3270) 46, 247 INITIMG option
(3653) 46, 248 GETMAIN 121
HOURS option INITPARM option
DELAY 65 ASSIGN 25
POST 179 INITPARMLEN option
ROUTE 239 ASSIGN 25
START 306 INPARTN option
HTAB operand ASSIGN 25
DFHMSD 399 RECEIVE MAP 220
input operation without data 361
INPUTMSG option
I LINK 169
IC value
RETURN 235
DFHMDF 385
XCTL 341
IGNORE CONDITION command 129
INPUTMSGLEN option
LINK 169

420 CICS/ESA Application Programming Reference

INPUTMSGLEN option (continued) INVITE option (continued)
RETURN 235 SEND (VTAM) 252
XCTL 341 INVLDC condition
interactive logical units 47, 206, 249 ROUTE 241
interface processor DFHEAI 354 SEND CONTROL 266
interface to JES 6 SEND MAP 271
interpreter logical unit, 3650 SEND TEXT 283
CONVERSE 45 INVMPSZ condition
ISSUE EODS 145 EIBRCODE byte 3 348
ISSUE LOAD 150 RECEIVE MAP 221
RECEIVE 205 RECEIVE MAP MAPPINGDEV command 224
SEND (VTAM) 247 SEND MAP 272
interrogate a data set 156 SEND MAP MAPPINGDEV command 275
interval control INVOKINGPROG option
ASKTIME options 21 ASSIGN 25
cancel interval control command 35 INVPARTN condition
CANCEL options 35 RECEIVE MAP 221
commands 10 RECEIVE PARTN 226
DELAY options 65 SEND CONTROL 266
delay processing of task 65 SEND MAP 272
FORMATTIME options 92 SEND TEXT 283
notification when specified time expires 178 SEND TEXT NOEDIT 287
request current time of day 21 INVPARTNSET condition
retrieve data stored for task 232 SEND PARTNSET 279
start a task 303 INVREQ condition
wait for event to occur 321 ADDRESS 14
INTERVAL option ALLOCATE (APPC) 16
DELAY 65 ALLOCATE (LUTYPE6.1) 18
POST 179 ALLOCATE (MRO) 20
ROUTE 239 ASSIGN 29
START 306 CHANGE PASSWORD 37
INTO option CHANGE TASK 38
CONVERSE (non-VTAM) 62 CONNECT PROCESS 40
CONVERSE (VTAM) 50 CONVERSE (VTAM) 52
EXTRACT LOGONMSG 88 DELAY 66
GDS RECEIVE 115 DELETE 68
ISSUE RECEIVE 157 DELETEQ TD 70
READ 186 DELETEQ TS 71
READNEXT 189 DEQ 72
READPREV 193 DUMP TRANSACTION 76
READQ TD 196 EIBRCODE bytes 1-3 348
READQ TS 198 ENDBR 77
RECEIVE (non-VTAM) 218 ENQ 79
RECEIVE (VTAM) 208 ENTER TRACENUM 80
RECEIVE MAP 221 EXTRACT ATTACH (LUTYPE6.1) 83
RECEIVE MAP MAPPINGDEV command 223 EXTRACT ATTACH (MRO) 85
RECEIVE PARTN 225 EXTRACT ATTRIBUTES (APPC) 86
RETRIEVE 233 EXTRACT ATTRIBUTES (MRO) 87
SPOOLREAD 299 EXTRACT PROCESS 89
INVALIDCOUNT option EXTRACT TCT 91
VERIFY PASSWORD 318 FORMATTIME 94
INVERRTERM condition FREE (APPC) 96
ROUTE 241 FREE (LUTYPE6.1) 97
INVITE option FREE (MRO) 98
GDS SEND 117 FREEMAIN 101
SEND (non-VTAM) 261 HANDLE AID 126

Index 421
INVREQ condition (continued) INVREQ condition (continued)
ISSUE ABEND 130 SIGNOFF 289
ISSUE ABORT 132 SIGNON 291
ISSUE ADD 134 START 307
ISSUE CONFIRMATION 135 STARTBR 310
ISSUE END 142 SYNCPOINT 314
ISSUE ENDFILE 143 SYNCPOINT ROLLBACK 315
ISSUE ENDOUTPUT 144 UNLOCK 316
ISSUE EODS 145 VERIFY PASSWORD 319
ISSUE ERASE 147 WAIT CONVID 320
ISSUE ERASEAUP 148 WAIT EVENT 321
ISSUE ERROR 149 WAIT EXTERNAL 323
ISSUE NOTE 151 WAIT JOURNALNUM 324
ISSUE PASS 153 WAIT TERMINAL 326
ISSUE PREPARE 154 WAITCICS 328
ISSUE PRINT 155 WRITE 330
ISSUE QUERY 156 WRITE OPERATOR 335
ISSUE RECEIVE 158 WRITEQ TD 336
ISSUE REPLACE 160 WRITEQ TS 339
ISSUE RESET 161 XCTL 341
ISSUE SEND 163 IOERR condition
ISSUE SIGNAL (APPC) 164 DELETE 69
ISSUE WAIT 167 DUMP TRANSACTION 76
LINK 170 EIBRCODE 348
LOAD 173 READ 188
MONITOR 175 READNEXT 191
POP HANDLE 177 READPREV 195
POST 179 READQ TD 197
PURGE MESSAGE 180 READQ TS 199
QUERY SECURITY 183 RESETBR 230
READ 187 RETRIEVE 234
READNEXT 191 REWRITE 238
READPREV 195 START 308
READQ TD 197 STARTBR 311
READQ TS 199 UNLOCK 316
RECEIVE (non-VTAM) 219 WAIT JOURNALNUM 324
RECEIVE (VTAM) 209 WRITE 330
RECEIVE MAP 221 WRITE JOURNALNUM 333
RECEIVE MAP MAPPINGDEV command 224 WRITEQ TD 336
RECEIVE PARTN 226 WRITEQ TS 339
RELEASE 227 ISCINVREQ condition
RESETBR 230 CANCEL 36
RETRIEVE 234 DELETE 69
RETURN 236 DELETEQ TD 70
REWRITE 238 DELETEQ TS 71
ROUTE 241 ENDBR 77
SEND (non-VTAM) 262 READ 188
SEND (VTAM) 253 READNEXT 191
SEND CONTROL 266 READPREV 195
SEND MAP 272 READQ TD 197
SEND MAP MAPPINGDEV command 275 READQ TS 199
SEND PAGE 277 RESETBR 230
SEND PARTNSET 279 REWRITE 238
SEND TEXT 283 START 308
SEND TEXT MAPPED 285 STARTBR 311
SEND TEXT NOEDIT 287 UNLOCK 317

422 CICS/ESA Application Programming Reference

ISCINVREQ condition (continued)
WRITE 331 J
WRITEQ TD 336 JES (job entry subsystem)
WRITEQ TS 339 CICS interface to 6
ISSUE ABEND command 130 exits 8
ISSUE ABORT command 131 input 8
ISSUE ADD command 133 internal limits 6
ISSUE CONFIRMATION command 135 output 8
ISSUE COPY (3270 display) command 137 RESP and RESP2 options 8
ISSUE COPY (3270 logical) command 138 retrieve data from JES spool 7
ISSUE COPY command send file to destination 7
general information 361 spooler commands 8
ISSUE DISCONNECT (default) command 139 write directly to JES spool 7
ISSUE DISCONNECT (LUTYPE6.1) command 140 JIDERR condition
ISSUE DISCONNECT command WAIT JOURNALNUM 324
general information 358 WRITE JOURNALNUM 333
ISSUE END command 141 journal record, creating 332
ISSUE ENDFILE command 143 journaling commands 10
ISSUE ENDOUTPUT command 144 JOURNALNUM option
ISSUE EODS command 145 WAIT JOURNALNUM 324
ISSUE ERASE command 146 WRITE JOURNALNUM 332
ISSUE ERASEAUP command 148 JTYPEID option
general information 361 WRITE JOURNALNUM 332
ISSUE ERROR command 149 JUSFIRST option
ISSUE LOAD command 150 SEND TEXT 281
ISSUE NOTE command 151 JUSLAST option
ISSUE PASS command 152 SEND TEXT 281
ISSUE PREPARE command 154 JUSTIFY operand
ISSUE PRINT command 155 DFHMDF 386
general information 360 DFHMDI 393
ISSUE QUERY command 156 JUSTIFY option
ISSUE RECEIVE command 157 SEND TEXT 281
ISSUE REPLACE command 159
ISSUE RESET command 161
general information 358
K
katakana and English characters, mixed 61, 225
ISSUE SEND command 162
KATAKANA option
ISSUE SIGNAL (APPC) command 164
ASSIGN 26
ISSUE SIGNAL (LUTYPE6.1) command 165
katakana terminals
ISSUE SIGNAL command
CONVERSE (3270 display) 61
general information 358
CONVERSE (3270 logical) 50
ISSUE WAIT command 166
CONVERSE (3600 BTAM) 61
ITEM option
CONVERSE (3735) 61
READQ TS 198
CONVERSE (3740) 61
WRITEQ TS 338
CONVERSE (LUTYPE2/LUTYPE3) 50
ITEMERR condition
CONVERSE (System/3) 61
READQ TS 199
CONVERSE (System/7) 61
WRITEQ TS 340
RECEIVE (3270 display) 218
IUTYPE option
RECEIVE (3270 logical) 208
BUILD ATTACH (LUTYPE6.1) 31
RECEIVE (3790 3270-display) 218
BUILD ATTACH (MRO) 33
RECEIVE (LUTYPE2/LUTYPE3) 208
EXTRACT ATTACH (LUTYPE6.1) 82
RECEIVE (System/3) 218
EXTRACT ATTACH (MRO) 84
RECEIVE (System/7) 218
RECEIVE MAP 220
RECEIVE PARTN 225
SEND (3600 BTAM) 261

Index 423
katakana terminals (continued) LDC option
SEND (3735) 261 CONVERSE (VTAM) 50
SEND (3740) 261 ROUTE 239
SEND (System/3) 261 SEND (VTAM) 253
SEND (System/7) 261 SEND CONTROL 265
KEEP option SEND MAP 270
SPOOLCLOSE 293 SEND TEXT 282
KEYLENGTH option LDCMNEM option
DELETE 67 ASSIGN 26
ISSUE ERASE 146 LDCNUM option
ISSUE REPLACE 159 ASSIGN 26
READ 186 LEAVEKB option
READNEXT 189 CONVERSE (non-VTAM) 62
READPREV 193 RECEIVE (non-VTAM) 218
RESETBR 229 SEND (non-VTAM) 261
STARTBR 310 LEFT value
WRITE 329 DFHMDF 386
KEYNUMBER option DFHMDI 393
ISSUE ERASE 146 LENGERR condition
ISSUE REPLACE 159 BIF DEEDIT 30
keyword length 357 CONNECT PROCESS 40
CONVERSE (non-VTAM) 64
CONVERSE (VTAM) 52
L DEQ 72
L40, L64, or L80 options EIBRCODE byte 1 348
SEND CONTROL 265 ENQ 79
SEND MAP 270 ENTER TRACENUM 81
SEND TEXT 282 EXTRACT PROCESS 89
SEND TEXT NOEDIT 287 GETMAIN 122
label argument, CICS command format 2 ISSUE COPY (3270 logical) 138
LABEL option ISSUE PASS 153
HANDLE ABEND 123 ISSUE RECEIVE 158
LANG operand LINK 170
DFHMSD 399 LOAD 173
LANGINUSE option QUERY SECURITY 183
ASSIGN 26 READ 188
SIGNON 291 READNEXT 192
language codes 373 READPREV 195
LANGUAGECODE option READQ TD 197
SIGNON 290 READQ TS 199
LAST option RECEIVE (non-VTAM) 219
GDS SEND 117 RECEIVE (VTAM) 209
SEND (non-VTAM) 261 RECEIVE PARTN 226
SEND (VTAM) 252 RETRIEVE 234
SEND CONTROL 265 RETURN 236
SEND MAP 270 REWRITE 238
SEND PAGE 276 SEND (non-VTAM) 262
SEND TEXT 282 SEND (VTAM) 253
SEND TEXT MAPPED 284 SEND TEXT 283
SEND TEXT NOEDIT 287 START 308
LAST value WRITE 331
DFHMDI 393 WRITE JOURNALNUM 333
LASTUSETIME option WRITE OPERATOR 335
VERIFY PASSWORD 318 WRITEQ TD 336
LDC operand WRITEQ TS 340
DFHMSD 399 XCTL 341

424 CICS/ESA Application Programming Reference

LENGTH operand LINE value
DFHMDF 386 DFHMDI 394
LENGTH option line, telecommunication 358
BIF DEEDIT 30 LINEADDR option
built-in function 30 CONVERSE (non-VTAM) 62
default (assembler language) 4 SEND (non-VTAM) 261
default (C) 3 LINK command 168
default (PL/I) 4 link to program expecting return 168
DEQ 72 LIST option
DUMP TRANSACTION 75 ROUTE 240
ENQ 78 literal constants 4
EXTRACT LOGONMSG 88 LLID option
fullword length alternative (FLENGTH) 357 GDS RECEIVE 115
GETMAIN 121 LOAD command 172
ISSUE ADD 133 load programs, tables, or maps 172
ISSUE PASS 152 LOADING condition
ISSUE RECEIVE 157 DELETE 69
ISSUE REPLACE 159 READ 188
ISSUE SEND 162 STARTBR 311
LINK 169 WRITE 331
LOAD 172 logical device code (LDC) 44, 246
READ 186 logical messages, BMS
READNEXT 190 completing a logical message 276
READPREV 193 full BMS
READQ TD 196 ROUTE 239
READQ TS 198 purging a logical message 180
RECEIVE (non-VTAM) 218 routing a logical message 239
RECEIVE (VTAM) 208 LOGMESSAGE option
RECEIVE MAP 221 QUERY SECURITY 182
RECEIVE MAP MAPPINGDEV command 223 LOGMODE option
RECEIVE PARTN 225 ISSUE PASS 152
RETRIEVE 233 LOGONLOGMODE option
RETURN 235 ISSUE PASS 152
REWRITE 237 LU (logical unit)
SEND (non-VTAM) 261 3270 Information Display System 44, 138, 203, 245
SEND (VTAM) 253 3270 SCS Printer 43, 244
SEND MAP 270 3270-Display, LUTYPE2 42, 202, 243
SEND MAP MAPPINGDEV command 275 3270-Display, LUTYPE3 202, 243
SEND TEXT 282 3600 (3601) 44, 204, 246
SEND TEXT MAPPED 284 3600 (3614) 45, 205, 246
SEND TEXT NOEDIT 287 3600 pipeline 204, 245
START 306 3650 host conversational (3270) 46, 247
WRITE 329 3650 host conversational (3653) 46, 248
WRITE JOURNALNUM 332 3650 interpreter 45, 145, 150, 205, 247
WRITEQ TD 336 3650/3680 host command processor 248
WRITEQ TS 338 3770 batch 48, 206, 249
XCTL 341 3790 (3270-display) 49, 217, 251
LENGTH value 3790 (3270-printer) 251
DFHMDI 391 3790 full-function 207, 250
DFHMSD 397 3790 full-function or inquiry 48
LENGTHLIST option 3790 SCS printer 250
DUMP TRANSACTION 75 batch 48, 206, 249
LIGHTPEN option conversing with (CONVERSE) 358
HANDLE AID 125 interactive 47
LINE option reading data from 157, 357
SPOOLWRITE 301 writing data to 133, 357

Index 425
LUNAME option maps, loading 172
ISSUE PASS 152 mapset definition macro (DFHMSD) 381, 397
LUTYPE2, 3270-Display LU 42, 202, 243 MAPSET option
LUTYPE3, 3270-Display LU 202, 243 RECEIVE MAP 221
LUTYPE4 RECEIVE MAP MAPPINGDEV command 224
logical unit 42, 202, 243 SEND MAP 270
LUTYPE6.1 logical unit SEND MAP MAPPINGDEV command 275
acquiring a session 18 MAPSFX operand
communicating on LUTYPE6.1 session 43 DFHPDI 403
converting 8-character names to 4 characters 91 MAPWIDTH option
disconnecting 140 ASSIGN 26
ensuring terminal operation has completed 326 MASSINSERT option
getting information about 176 WRITE 330
receiving data 203 MAXFLENGTH option
requesting change of direction 165 CONVERSE (non-VTAM) 62
retrieving values from an LUTYPE6.1 header 82 CONVERSE (VTAM) 51
sending data 244 fullword alternative to MAXLENGTH 357
specifying values for an MRO attach header 33 GDS RECEIVE 115
specifying values for LUTYPE6.1 attach header 31 RECEIVE (non-VTAM) 218
RECEIVE (VTAM) 208
SPOOLREAD 299
M MAXLENGTH option
macros, BMS, summary 381 CONVERSE (non-VTAM) 62
magnetic slot reader (MSR) 377 CONVERSE (VTAM) 51
MAIN option fullword length alternative (MAXFLENGTH) 357
WRITEQ TS 338 RECEIVE (non-VTAM) 218
main storage 120 RECEIVE (VTAM) 208
map definition macro, BMS 381, 391 WRITE OPERATOR 335
MAP option MAXLIFETIME option
RECEIVE MAP 221 DEQ 72
RECEIVE MAP MAPPINGDEV command 224 ENQ 79
SEND MAP 270 MAXPROCLEN option
SEND MAP MAPPINGDEV command 275 EXTRACT PROCESS 89
MAP value GDS EXTRACT PROCESS 108
DFHMSD 401 MCC option
MAPATTS operand SPOOLOPEN 296
DFHMDI 394 MINUTES option
DFHMSD 399 DELAY 65
MAPCOLUMN option POST 179
ASSIGN 26 ROUTE 240
MAPFAIL condition START 306
RECEIVE MAP 221 MMDDYY option
RECEIVE MAP MAPPINGDEV command 224 FORMATTIME 93
MAPHEIGHT option MMDDYYYY option
ASSIGN 26 FORMATTIME 93
MAPLINE option MODE operand
ASSIGN 26 DFHMSD 399
MAPONLY option model codes (terminal) 351
SEND MAP 270 MODENAME option
SEND MAP MAPPINGDEV command 275 GDS ALLOCATE 102
MAPONLY value MONITOR command 174
DFHMDI 393 monitoring application performance 174
DFHMSD 398 monitoring commands 10
MAPPINGDEV option MONTHOFYEAR option
RECEIVE MAP MAPPINGDEV command 224 FORMATTIME 93
SEND MAP MAPPINGDEV command 275

426 CICS/ESA Application Programming Reference

MSR (magnetic slot reader) NEXTTRANSID option
control byte values and constants 377 ASSIGN 26
DFHMSRCA, 377 NLEOM option
MSR option ROUTE 240
SEND CONTROL 265 SEND MAP 270
SEND MAP 270 SEND TEXT 282
SEND TEXT 282 NO value
MSRCONTROL option DFHMDI 393, 394, 395
ASSIGN 26 DFHMSD 398, 401
multi region operation (MRO) commands NOAUTOPAGE option
ALLOCATE 20 SEND PAGE 276
BUILD ATTACH 33 NOCC option
CONVERSE 53 SPOOLOPEN 296
EXTRACT ATTACH 84 NOCHECK option
EXTRACT ATTRIBUTES 87 START 306
FREE 98 NODE option
RECEIVE 210 SPOOLOPEN 296
SEND 255 NODUMP option
multiple base registers 355 ABEND 12
MUSTENTER NOFLUSH option
DFHMDF 389 SEND MAP 271
DFHMDI 395 NOHANDLE option
DFHMSD 401 deactivating HANDLE CONDITION 127
MUSTFILL option 5
DFHMDF 389 overriding HANDLE AID 6
DFHMDI 395 NOJBUFSP condition
DFHMSD 401 WRITE JOURNALNUM 333
NONVAL condition
ISSUE LOAD 150
N NOPASSBKRD condition
name argument, CICS command format 2 RECEIVE (non-VTAM) 219
NAME option NOPASSBKWR condition
WAIT EVENT 321 SEND (non-VTAM) 262
WAIT EXTERNAL 323 NOQUEUE option
WAITCICS 328 ALLOCATE (APPC) 16
naming restriction 353 ALLOCATE (LUTYPE6.1) 18
National language codes 373 ALLOCATE (MRO) 20
NATLANG option GDS ALLOCATE 102
SIGNON 291 NOQUIESCE
NATLANGINUSE option ISSUE PASS 152
ASSIGN 26 NORM value
SIGNON 291 DFHMDF 385
NETNAME option NOSPACE condition
ASSIGN 26 DUMP TRANSACTION 76
EXTRACT TCT 91 REWRITE 238
NETNAMEIDERR condition WRITE 331
ALLOCATE (APPC) 17 WRITEQ TD 337
new tasks, passing data to 305 WRITEQ TS 340
NEWPASSWORD option NOSTART condition
CHANGE PASSWORD 37 ISSUE LOAD 150
SIGNON 291 NOSTG condition
NEXT option DUMP TRANSACTION 76
READQ TS 198 GETMAIN 122
NEXT value NOSUSPEND option
DFHMDI 391, 394 ALLOCATE (APPC) 16
ALLOCATE (LUTYPE6.1) 18

Index 427
NOSUSPEND option (continued) NOTAUTH condition (continued)
ENQ 79 READ 188
GETMAIN 121 READNEXT 192
READQ TD 196 READPREV 195
WRITE JOURNALNUM 332 READQ TD 197
WRITEQ TS 339 READQ TS 199
NOTALLOC condition RELEASE 227
CONNECT PROCESS 40 RESETBR 230
CONVERSE (non-VTAM) 64 REWRITE 238
CONVERSE (VTAM) 52 SIGNON 291
EXTRACT ATTACH (LUTYPE6.1) 83 START 308
EXTRACT ATTACH (MRO) 85 STARTBR 311
EXTRACT ATTRIBUTES (APPC) 86 UNLOCK 317
EXTRACT ATTRIBUTES (MRO) 87 VERIFY PASSWORD 319
EXTRACT LOGONMSG 88 WRITE 331
EXTRACT PROCESS 90 WRITE JOURNALNUM 333
EXTRACT TCT 91 WRITEQ TD 337
FREE 95 WRITEQ TS 340
FREE (APPC) 96 XCTL 342
FREE (LUTYPE6.1) 97 NOTFND condition
FREE (MRO) 98 CANCEL 36
ISSUE ABEND 130 DELETE 69
ISSUE CONFIRMATION 135 QUERY SECURITY 183
ISSUE COPY (3270 display) 137 READ 188
ISSUE COPY (3270 logical) 138 READNEXT 192
ISSUE DISCONNECT (LUTYPE6.1) 140 READPREV 195
ISSUE ENDFILE 143 RESETBR 230
ISSUE ENDOUTPUT 144 RETRIEVE 234
ISSUE EODS 145 REWRITE 238
ISSUE ERASEAUP 148 STARTBR 311
ISSUE ERROR 149 NOTOPEN condition
ISSUE LOAD 150 DELETE 69
ISSUE PASS 153 DUMP TRANSACTION 76
ISSUE PREPARE 154 READ 188
ISSUE PRINT 155 READQ TD 197
ISSUE RESET 161 STARTBR 311
ISSUE SIGNAL (APPC) 164 UNLOCK 317
ISSUE SIGNAL (LUTYPE6.1) 165 WAIT JOURNALNUM 324
POINT 176 WRITE 331
RECEIVE (non-VTAM) 219 WRITE JOURNALNUM 333
RECEIVE (VTAM) 209 WRITEQ TD 337
SEND (non-VTAM) 262 NOTRUNCATE option
SEND (VTAM) 253 CONVERSE (non-VTAM) 62
WAIT CONVID 320 CONVERSE (VTAM) 51
WAIT SIGNAL 325 RECEIVE (non-VTAM) 218
WAIT TERMINAL 326 RECEIVE (VTAM) 208
NOTAUTH condition NOWAIT option
CANCEL 36 ISSUE ADD 133
CHANGE PASSWORD 37 ISSUE ERASE 146
DELETE 69 ISSUE REPLACE 159
DELETEQ TD 70 ISSUE SEND 162
DELETEQ TS 71 NUM value
ENDBR 77 DFHMDF 385
HANDLE ABEND 123 NUMBER value
LINK 170 DFHMDI 391, 394
LOAD 173

428 CICS/ESA Application Programming Reference

NUMEVENTS option OUTLINE operand
WAIT EXTERNAL 323 DFHMDF 387
WAITCICS 328 DFHMDI 394
NUMITEMS option DFHMSD 399
READQ TS 199 OUTLINE option
WRITEQ TS 339 ASSIGN 27
NUMREC option OUTPARTN option
DELETE 68 SEND CONTROL 266
ISSUE ADD 133 SEND MAP 271
ISSUE ERASE 146 SEND TEXT 282
ISSUE REPLACE 159 SEND TEXT NOEDIT 287
NUMROUTES option output control, 2980 General Banking Terminal System 213
WRITE OPERATOR 335 output to common buffer, 2980 214
NUMSEGMENTS option OVERFLOW condition
DUMP TRANSACTION 75 SEND MAP 272
NUMTAB option
ASSIGN 26
P
PA1–PA3 option
O HANDLE AID 125
OBFMT operand PAGE option
DFHMDI 394 SPOOLWRITE 301
DFHMSD 399 PAGENUM option
OCCURS operand ASSIGN 27
DFHMDF 386 PAGING option
OFF value SEND CONTROL 266
DFHMDF 386 SEND MAP 271
DFHMDI 393 SEND TEXT 282
DFHMSD 399 SEND TEXT MAPPED 284
OIDCARD option SEND TEXT NOEDIT 287
SIGNON 291 partition definition macro (DFHPDI) 381, 403
OPCLASS option partition set definition macro (DFHPSD) 381, 404
ASSIGN 26 PARTN operand
ROUTE 240 DFHMDI 394
OPENERR condition DFHMSD 399
DUMP TRANSACTION 76 PARTN option
OPERID option RECEIVE PARTN 225
HANDLE AID 125 PARTNER option
OPERKEYS option ALLOCATE(APPC) 16
ASSIGN 26 CONNECT PROCESS 39
OPERPURGE option GDS ALLOCATE 102
SEND PAGE 277 GDS CONNECT PROCESS 105
OPID option PARTNERIDERR condition
ASSIGN 26 ALLOCATE (APPC) 17
OPSECURITY option CONNECT PROCESS 40
ASSIGN 27 PARTNFAIL condition
options RECEIVE MAP 221
BMS 220, 223, 280 PARTNPAGE option
length 357 ASSIGN 27
OPTIONS(MAIN) PARTNS option
in PL/I 353 ASSIGN 27
ORGABCODE option PARTNSET option
ASSIGN 27 ASSIGN 27
OUTDESCR option PASSBK option
SPOOLOPEN 296 RECEIVE (non-VTAM) 218
SEND (non-VTAM) 262

Index 429
passbook control, 2980 213 posting timer-event control area 178
passing a session 152 PPT option
passing control DUMP TRANSACTION 75
expecting return (LINK) 168 PREFIX option
on receipt of an AID (HANDLE AID) 125 WRITE JOURNALNUM 332
on receipt of an AID (IGNORE AID) 129 PRINCONVID option
without return (XCTL) 341 GDS ASSIGN 104
passing data to new tasks 305 PRINSYSID option
PASSWORD option ASSIGN 27
CHANGE PASSWORD 37 GDS ASSIGN 104
SIGNON 291 print displayed information 360
VERIFY PASSWORD 318 PRINT option
PCT option ISSUE ABORT 131
DUMP TRANSACTION 75 ISSUE END 141
performance, application, monitoring 174 ISSUE SEND 162
PF1–24 option ISSUE WAIT 166
HANDLE AID 125 SEND CONTROL 266
PFXLENG option SEND MAP 271
WRITE JOURNALNUM 332 SEND MAP MAPPINGDEV command 275
PGMIDERR condition SEND TEXT 282
HANDLE ABEND 124 SEND TEXT NOEDIT 287
LINK 170 SPOOLOPEN 297
LOAD 173 PRINT value
RELEASE 228 DFHMDI 391
XCTL 342 DFHMSD 397
PICIN operand printer control character list, DFHBMSCA 375
DFHMDF 387 priority of task, changing 38
PICOUT operand PRIORITY option
DFHMDF 388 CHANGE TASK 38
pipeline logical units 204, 245 PROCESS option
PIPLENGTH option BUILD ATTACH (LUTYPE6.1) 32
CONNECT PROCESS 39 BUILD ATTACH (MRO) 33
EXTRACT PROCESS 89 EXTRACT ATTACH (LUTYPE6.1) 82
GDS CONNECT PROCESS 105 EXTRACT ATTACH (MRO) 84
GDS EXTRACT PROCESS 108 processing task, control delay of 65
PIPLIST option PROCLENGTH option
CONNECT PROCESS 39 CONNECT PROCESS 39
EXTRACT PROCESS 89 EXTRACT PROCESS 89
GDS CONNECT PROCESS 105 GDS CONNECT PROCESS 105
GDS EXTRACT PROCESS 108 GDS EXTRACT PROCESS 108
PL/I language PROCNAME option
argument values 3 CONNECT PROCESS 39
LENGTH option default 4 EXTRACT PROCESS 89
PROCEDURE statement 353 GDS CONNECT PROCESS 105
STAE option 12 GDS EXTRACT PROCESS 108
translated code 353 PROFILE option
POINT command 176 ALLOCATE (APPC) 16
POINT option ALLOCATE (LUTYPE6.1) 18
MONITOR 175 program control
pointer-ref argument, CICS command format 2 commands 10
pointer-value argument, CICS command format 2 deleting loaded program 227
POP HANDLE command 177 LINK options 169
POS operand 382 linking to another program 168
DFHMDF 388 load a program, table, or map 172
POST command 178 returning program control 235
transfer program control 341

430 CICS/ESA Application Programming Reference

PROGRAM option QUEUE option (continued)
ASSIGN 27 START 306
DUMP TRANSACTION 75 WRITEQ TD 336
HANDLE ABEND 123 WRITEQ TS 339
ISSUE LOAD 150 QZERO condition
LINK 169 READQ TD 197
LOAD 172
RELEASE 227
XCTL 341 R
PROT value RBA option
DFHMDF 385 DELETE 68
PROTECT option READ 186
START 306 READNEXT 190
PS operand READPREV 194
DFHMDF 389 RESETBR 229
DFHMDI 394 STARTBR 310
DFHMSD 399 WRITE 330
PS option RDATT condition
ASSIGN 27 CONVERSE (non-VTAM) 64
PSEUDOBIN option RECEIVE (non-VTAM) 219
CONVERSE (non-VTAM) 62 RECEIVE MAP 221
RECEIVE (non-VTAM) 219 reactivate an ABEND exit 123
SEND (non-VTAM) 262 read attention 56
PUNCH option READ command 185
SPOOLOPEN 297 READ option
PURGE MESSAGE command 180 QUERY SECURITY 182
PURGEABILITY option reading records
WAIT EXTERNAL 323 batch data interchange 157
WAITCICS 328 browsing, next 189
PUSH HANDLE command 181 browsing, previous (VSAM) 193
file control 185
from temporary storage queue 198
Q from terminal or LU 357
QBUSY condition from transient data queue 196
READQ TD 197 READNEXT command 189
QIDERR condition READPREV command 193
DELETEQ TD 70 READQ TD command 196
DELETEQ TS 71 READQ TS command 198
QUERY SECURITY 184 RECEIVE (2260) command 212
READQ TD 197 RECEIVE (2741) command 212
READQ TS 199 RECEIVE (2980) command 213
WRITEQ TD 337 RECEIVE (3270 display) command 215
WRITEQ TS 340 RECEIVE (3270 logical) command 203
QNAME option RECEIVE (3600 BTAM) command 215
ASSIGN 27 RECEIVE (3600 pipeline) command 204
QUERY SECURITY command 182 RECEIVE (3600-3601) command 204
QUEUE option RECEIVE (3600-3614) command 205
BUILD ATTACH (LUTYPE6.1) 32 RECEIVE (3650) command 205
BUILD ATTACH (MRO) 34 RECEIVE (3735) command 216
DELETEQ TD 70 RECEIVE (3740) command 216
DELETEQ TS 71 RECEIVE (3767) command 206
EXTRACT ATTACH (LUTYPE6.1) 83 RECEIVE (3770) command 206
EXTRACT ATTACH (MRO) 85 RECEIVE (3790 3270-display) command 217
READQ TD 196 RECEIVE (3790 full-function or inquiry) command 207
READQ TS 199 RECEIVE (APPC) command 201
RETRIEVE 233

Index 431
RECEIVE (LUTYPE2/LUTYPE3) command 202 REQID option (continued)
RECEIVE (LUTYPE4) command 202 WRITE JOURNALNUM 332
RECEIVE (LUTYPE6.1) command 203 RESCLASS option
RECEIVE (MRO) command 210 QUERY SECURITY 182
RECEIVE (non-VTAM) command 210 RESET option
RECEIVE (System/3) command 211 HANDLE ABEND 123
RECEIVE (System/7) command 211 reset start for browse 229
RECEIVE (VTAM default) command 201 RESETBR command 229
RECEIVE command RESID option
input operation without data 361 QUERY SECURITY 182
read from terminal or logical unit 357 RESIDLENGTH option
RECEIVE MAP command 220 QUERY SECURITY 182
RECEIVE MAP MAPPINGDEV command 223 RESOURCE option
RECEIVE PARTN command 225 BUILD ATTACH (LUTYPE6.1) 32
RECFM option BUILD ATTACH (MRO) 34
BUILD ATTACH (LUTYPE6.1) 32 DEQ 72
BUILD ATTACH (MRO) 34 ENQ 79
EXTRACT ATTACH (LUTYPE6.1) 83 ENTER TRACENUM 80
EXTRACT ATTACH (MRO) 85 EXTRACT ATTACH (LUTYPE6.1) 83
RECORDLENGTH option EXTRACT ATTACH (MRO) 85
SPOOLOPEN 297 resource scheduling 72
records RESP
deleting VSAM 67 deactivating NOHANDLE 127
reading 157, 185 option 5
release exclusive control 316 values in EIBRESP 349
requesting next number 151 RESP and RESP2 options
updating 159, 237 for interface to JES 8
writing new 329 RESP2
writing new (adding) 133 EXPIRED in messages to console operators 335
register contents in assembler language 353 INVREQ in messages to console operators 335
relative byte address (RBA) 68 INVREQ in SIGNOFF (Security control) 289
RELEASE command 227 INVREQ in SIGNON (Security control) 291
RELEASE option INVREQ in WAIT EXTERNAL 323
SEND PAGE 277 INVREQ on WAITCICS 328
relocatable expression 4 LENGERR in messages to console operators 335
REPLY option NOTAUTH in SIGNON (Security control) 291
WRITE OPERATOR 335 option 5
REPLYLENGTH option USERIDERR in SIGNON (Security control) 292
WRITE OPERATOR 335 values in EIBRESP2 349
REQID option RESSEC option
CANCEL 35 ASSIGN 27
DELAY 66 RESTART option
ENDBR 77 ASSIGN 27
POST 179 RESTYPE option
READNEXT 190 QUERY SECURITY 182
READPREV 194 RETAIN option
RESETBR 230 SEND PAGE 277
ROUTE 240 RETCODE option
SEND CONTROL 266 GDS ALLOCATE 102
SEND MAP 271 GDS ASSIGN 104
SEND TEXT 282 GDS CONNECT PROCESS 105
SEND TEXT MAPPED 284 GDS EXTRACT ATTRIBUTES 107
SEND TEXT NOEDIT 287 GDS EXTRACT PROCESS 108
START 306 GDS FREE 109
STARTBR 310 GDS ISSUE ABEND 110
WAIT JOURNALNUM 324 GDS ISSUE CONFIRMATION 111

432 CICS/ESA Application Programming Reference

RETCODE option (continued) RRESOURCE option (continued)
GDS ISSUE ERROR 112 EXTRACT ATTACH (LUTYPE6.1) 83
GDS ISSUE PREPARE 113 EXTRACT ATTACH (MRO) 85
GDS ISSUE SIGNAL 114 RRN option
GDS RECEIVE 115 DELETE 68
GDS SEND 117 ISSUE ADD 133
GDS WAIT 119 ISSUE ERASE 146
RETPAGE condition ISSUE NOTE 151
SEND CONTROL 267 ISSUE REPLACE 159
SEND MAP 272 READ 186
SEND PAGE 277 READNEXT 191
SEND TEXT 283 READPREV 194
RETRIEVE command 232 RESETBR 230
retrieve data stored for task 232 STARTBR 310
RETURN command 235 WRITE 330
return program control 235 RTEFAIL condition
RETURNPROG option ROUTE 241
ASSIGN 27 RTERMID option
REVERSE value RETRIEVE 233
DFHMDF 386 START 307
DFHMDI 393 RTESOME condition
DFHMSD 399 ROUTE 241
REWRITE command 237 RTRANSID option
REWRITE option RETRIEVE 233
WRITEQ TS 339 START 307
RIDFLD option
DELETE 68
ISSUE ADD 133 S
ISSUE ERASE 146 SAA (Systems Application Architecture)
ISSUE NOTE 151 Communications (CPI) 365
ISSUE REPLACE 159 Resource Recovery 363
READ 186 SAME value
READNEXT 190 DFHMDI 391, 394
READPREV 194 schedule use of resource by task 72, 78
RESETBR 230 SCRNHT option
STARTBR 310 ASSIGN 28
WRITE 330 SCRNWD option
RIGHT value ASSIGN 28
DFHMDF 386 SCS (SNA character string)
DFHMDI 393 CONVERSE 43
ROLLBACK option SEND 244
SYNCPOINT ROLLBACK 315 SEND (VTAM) 250
ROLLEDBACK condition SCS printer logical unit, 3790 250
LINK 170 SECONDS option
SYNCPOINT 314 DELAY 66
ROUTE command 239 POST 179
ROUTECODES option ROUTE 240
WRITE OPERATOR 335 START 307
RPROCESS option security commands 10
BUILD ATTACH (LUTYPE6.1) 32 SEGMENTLIST option
BUILD ATTACH (MRO) 34 DUMP TRANSACTION 75
EXTRACT ATTACH (LUTYPE6.1) 83 SELNERR condition
EXTRACT ATTACH (MRO) 85 ISSUE ABORT 132
RRESOURCE option ISSUE ADD 134
BUILD ATTACH (LUTYPE6.1) 32 ISSUE END 142
BUILD ATTACH (MRO) 34 ISSUE ERASE 147

Index 433
SELNERR condition (continued) SESSION option (continued)
ISSUE NOTE 151 CONVERSE (non-VTAM) 62
ISSUE QUERY 156 CONVERSE (VTAM) 51
ISSUE REPLACE 160 EXTRACT ATTACH (LUTYPE6.1) 83
ISSUE SEND 163 EXTRACT ATTACH (MRO) 85
ISSUE WAIT 167 EXTRACT ATTRIBUTES (MRO) 87
SEND (2260) command 257 FREE (LUTYPE6.1) 97
SEND (2741) command 257 FREE (MRO) 98
SEND (2980) command 258 ISSUE DISCONNECT (LUTYPE6.1) 140
SEND (3270 display) command 258 ISSUE SIGNAL (LUTYPE6.1) 165
SEND (3270 logical) command 245 POINT 176
SEND (3600 BTAM) command 259 RECEIVE (non-VTAM) 219
SEND (3600 pipeline) command 245 RECEIVE (VTAM) 208
SEND (3600-3601) command 246 SEND (non-VTAM) 262
SEND (3600-3614) command 246 SEND (VTAM) 253
SEND (3650 interpreter) command 247 WAIT TERMINAL 326
SEND (3650-3270) command 247 session, passing 152
SEND (3650-3653) command 248 SESSIONERR condition
SEND (3650-3680) command 248 ALLOCATE (LUTYPE6.1) 18
SEND (3735) command 259 EIBRCODE bytes 1-2 347
SEND (3740) command 260 SET option
SEND (3767) command 249 ADDRESS SET 15
SEND (3770) command 249 CONVERSE (non-VTAM) 62
SEND (3790 3270-display) command 251 CONVERSE (VTAM) 51
SEND (3790 3270-printer) command 251 EXTRACT LOGONMSG 88
SEND (3790 full-function or inquiry) command 250 GDS RECEIVE 115
SEND (3790 SCS) command 250 GETMAIN 122
SEND (APPC) command 242 ISSUE RECEIVE 157
SEND (LUTYPE2/LUTYPE3) command 243 LOAD 172
SEND (LUTYPE4) command 243 POST 179
SEND (LUTYPE6.1) command 244 READ 186
SEND (MRO) command 255 READNEXT 191
SEND (non-VTAM default) command 255 READPREV 194
SEND (SCS) command 244 READQ TD 196
SEND (System/3) command 256 READQ TS 199
SEND (System/7) command 256 RECEIVE (non-VTAM) 219
SEND (vtam default) command 242 RECEIVE (VTAM) 208
send asynchronous interrupt 358 RECEIVE MAP 221
SEND command RECEIVE MAP MAPPINGDEV command 224
write to terminal 357 RECEIVE PARTN 225
SEND CONTROL command 264 RETRIEVE 233
SEND MAP command 268 SEND CONTROL 266
SEND MAP MAPPINGDEV command 274 SEND MAP 271
SEND PAGE command 276 SEND MAP MAPPINGDEV command 275
SEND PARTNSET command 279 SEND PAGE 277
SEND TEXT command 280 SEND TEXT 283
SEND TEXT MAPPED command 284 SHARED option
SEND TEXT NOEDIT command 286 GETMAIN 122
sending data to output device 162 SIGDATA option
sequential retrieval, browsing ASSIGN 28
reading records 185 SIGNAL condition
SESSBUSY condition CONVERSE (VTAM) 52
ALLOCATE (LUTYPE6.1) 18 ISSUE CONFIRMATION 136
SESSION option ISSUE DISCONNECT (default) 139
ALLOCATE (LUTYPE6.1) 18 ISSUE ERROR 149
CONNECT PROCESS 39 RECEIVE (VTAM) 209

434 CICS/ESA Application Programming Reference

SIGNAL condition (continued) STATE option (continued)
SEND (VTAM) 253 GDS ISSUE ERROR 112
WAIT SIGNAL 325 GDS ISSUE PREPARE 113
WAIT TERMINAL 326 GDS ISSUE SIGNAL 114
SIGNOFF command 289 GDS RECEIVE 116
SIGNON command 290 GDS SEND 118
single thread used with JES 294 GDS WAIT 119
SIT option ISSUE ABEND 130
DUMP TRANSACTION 75 ISSUE CONFIRMATION 135
SIZE operand ISSUE ERROR 149
DFHMDI 394 ISSUE PREPARE 154
SNA character string ISSUE SIGNAL (APPC) 164
See SCS RECEIVE (non-VTAM) 219
SOSI operand RECEIVE (VTAM) 209
DFHMDF 389 SEND (non-VTAM) 262
DFHMDI 395 SEND (VTAM) 253
DFHMSD 400 WAIT CONVID 320
SOSI option STATIONID option
ASSIGN 28 ASSIGN 28
SPCOMMAND storage area length 22
RESID value not valid 183 storage control commands 10
RESTYPE values 183 STORAGE operand
Spool commands 10 DFHMSD 400
SPOOLCLOSE command 293 STORAGE option
SPOOLCLOSE, implicit 294 DUMP TRANSACTION 75
spooler, JES 6 storage, dynamic 355
SPOOLOPEN INPUT command 294 STRFIELD option
SPOOLOPEN OUTPUT 296 CONVERSE (non-VTAM) 63
SPOOLREAD command 299 CONVERSE (VTAM) 51
SPOOLWRITE command 301 SEND (non-VTAM) 262
STAE option, PL/I 12 SEND (VTAM) 253
standard attribute and printer control character list, BMS stub, program 354
(DFHBMSCA) 375 SUBADDR option
START command 303 ISSUE ABORT 131
STARTBR command 309 ISSUE END 141
STARTCODE option ISSUE SEND 162
ASSIGN 28 ISSUE WAIT 166
STARTIO option SUFFIX operand
WAIT JOURNALNUM 324 DFHMSD 400
WRITE JOURNALNUM 333 DFHPSD 404
STATE option SUPPRESSED condition
ALLOCATE (APPC) 16 DUMP TRANSACTION 76
ALLOCATE (MRO) 20 WRITE 331
CONNECT PROCESS 39 SUSPEND command 313
CONVERSE (non-VTAM) 63 switched line disconnection 358
CONVERSE (VTAM) 51 symbolic register DFHEIPLR 356
EXTRACT ATTRIBUTES (APPC) 86 synchronization levels
EXTRACT ATTRIBUTES (MRO) 87 basic conversations 108
FREE (APPC) 96 synchronize, action
FREE (MRO) 98 journal output (WAIT JOURNALNUM) 324
GDS ALLOCATE 102 terminal input/output 357
GDS CONNECT PROCESS 105 SYNCLEVEL option
GDS EXTRACT ATTRIBUTES 107 CONNECT PROCESS 40
GDS FREE 109 EXTRACT PROCESS 89
GDS ISSUE ABEND 110 GDS CONNECT PROCESS 106
GDS ISSUE CONFIRMATION 111 GDS EXTRACT PROCESS 108

Index 435
SYNCONRETURN option SYSIDERR condition (continued)
LINK 169 RESETBR 231
syncpoint REWRITE 238
backing out 315 START 308
commands 10 STARTBR 312
establishing 314 UNLOCK 317
SYNCPOINT command 314 WRITE 331
SYNCPOINT ROLLBACK command 315 WRITEQ TD 337
syntax notation 1 WRITEQ TS 340
SYSBUSY condition System/3
ALLOCATE (APPC) 17 CONVERSE 54
ALLOCATE (LUTYPE6.1) 18 RECEIVE 211
ALLOCATE (MRO) 20 SEND 256
EIBRCODE byte 3 348 System/7
SYSID option CONVERSE 54
ALLOCATE (APPC) 16 RECEIVE 211
ALLOCATE (LUTYPE6.1) 18 SEND 256
ALLOCATE (MRO) 20 systemname
ASSIGN 28 definition 2, 3, 4
CANCEL 35 systemname argument, CICS command format 2
DELETE 68
DELETEQ TD 70
DELETEQ TS 71 T
ENDBR 77 TABLES option
EXTRACT TCT 91 DUMP TRANSACTION 75
GDS ALLOCATE 102 tables, loading 172
LINK 169 task control commands 10
READ 187 task initiation 305
READNEXT 191 TASK option
READPREV 194 DUMP TRANSACTION 75
READQ TD 197 task, abnormal termination 123
READQ TS 199 task, delay processing of 65
RESETBR 230 TASKDATALOC resource definition option 13
REWRITE 237 TASKPRIORITY option
START 307 ASSIGN 28
STARTBR 310 TCAM-supported terminals and logical units 358
UNLOCK 316 TCT option
WRITE 330 DUMP TRANSACTION 76
WRITEQ TD 336 TCTUA option
WRITEQ TS 339 ADDRESS 14
SYSIDERR condition TCTUALENG option
ALLOCATE (APPC) 17 ASSIGN 28
ALLOCATE (LUTYPE6.1) 19 telecommunication line, relinquishing 358
ALLOCATE (MRO) 20 teletypewriter
CANCEL 36 messages 359
DELETE 69 programming 359
DELETEQ TD 70 TELLERID option
DELETEQ TS 71 ASSIGN 28
EIBRCODE bytes 1-2 347 temporary storage control commands 10
ENDBR 77 TERM operand
LINK 171 DFHMDI 395
READ 188 DFHMSD 400
READNEXT 192 TERMCODE option
READPREV 195 ASSIGN 28, 351
READQ TD 197 TERMERR condition
READQ TS 200 CONNECT PROCESS 40

436 CICS/ESA Application Programming Reference

TERMERR condition (continued) TEXTPRINT option
CONVERSE (non-VTAM) 64 ASSIGN 29
CONVERSE (VTAM) 52 time of day, requesting 21
ISSUE ABEND 130 TIME option
ISSUE CONFIRMATION 136 DELAY 66
ISSUE COPY (3270 logical) 138 FORMATTIME 93
ISSUE DISCONNECT (default) 139 POST 179
ISSUE DISCONNECT (LUTYPE6.1) 140 ROUTE 240
ISSUE EODS 145 START 307
ISSUE ERASEAUP 148 TIMEOUT option
ISSUE ERROR 149 WRITE OPERATOR 335
ISSUE LOAD 150 timer-event control area 178
ISSUE PREPARE 154 TIMESEP option
ISSUE PRINT 155 FORMATTIME 93
ISSUE SIGNAL (APPC) 164 TIOAPFX operand
ISSUE SIGNAL (LUTYPE6.1) 165 DFHMDI 395
LINK 171 DFHMSD 401
RECEIVE (non-VTAM) 219 TITLE option
RECEIVE (VTAM) 209 ROUTE 241
SEND (non-VTAM) 263 TOFLENGTH option
SEND (VTAM) 254 CONVERSE (non-VTAM) 63
WAIT SIGNAL 325 CONVERSE (VTAM) 51
TERMID option fullword alternative to TOLENGTH 357
EXTRACT TCT 91 SPOOLREAD 299
ISSUE COPY (3270 display) 137 TOKEN option
ISSUE COPY (3270 logical) 138 DELETE 68
START 307 READ 187
TERMIDERR condition REWRITE 237
ISSUE COPY (3270 display) 137 SPOOLCLOSE 293
START 308 SPOOLOPEN 294, 297
terminal control 357 SPOOLREAD 299
commands 10 SPOOLWRITE 301
terminal model codes 351 UNLOCK 316
terminal operator paging, initiate paging transaction 276 TOLENGTH option
TERMINAL option CONVERSE (non-VTAM) 63
DUMP TRANSACTION 76 CONVERSE (VTAM) 51
RECEIVE MAP 221 fullword length alternative (TOFLENGTH) 357
SEND CONTROL 266 TRACENUM option
SEND MAP 271 ENTER TRACENUM 80
SEND TEXT 283 TRAILER operand
SEND TEXT MAPPED 284 DFHMDI 395
SEND TEXT NOEDIT 287 TRAILER option
terminal type codes 351 SEND PAGE 277
terminate data set processing SEND TEXT 283
abnormal 131 TRANPRIORITY option
normal 141 ASSIGN 29
terminology notes ix transfer program control 341
TERMPRIORITY option TRANSID option
ASSIGN 28 CANCEL 35
TEXT option LINK 169
WRITE OPERATOR 335 RETURN 236
TEXTKYBD option SEND PAGE 277
ASSIGN 28 START 307
TEXTLENGTH option TRANSIDERR condition
WRITE OPERATOR 335 START 308

Index 437
transient data commands 11 UNLOCK command 316
transient data control UNPROT value
delete intrapartition queue 70 DFHMDF 385
read data from TD queue 196 UNTIL option
write data to TD queue 336 DELAY 66
translated code 353 UPDATE option
TRANSP operand QUERY SECURITY 183
DFHMDF 389 READ 187
DFHMDI 395 updating records
DFHMSD 401 batch data interchange 159
TRIGGER option file control 237
HANDLE AID 125 USERDATAKEY option
TRIGGER value GETMAIN 122
DFHMDF 389 USEREXIT value
DFHMDI 395 DFHMDF 389
DFHMSD 401 DFHMDI 395
TRIGRAPH operand DFHMSD 401
DFHMSD 401 USERID option
TRT option ASSIGN 29
DUMP TRANSACTION 76 CHANGE PASSWORD 37
TSIOERR condition SIGNON 291
PURGE MESSAGE 180 SPOOLCLOSE 294
SEND CONTROL 267 SPOOLOPEN 297
SEND MAP 273 START 307
SEND PAGE 277 VERIFY PASSWORD 318
SEND TEXT 283 USERIDERR condition
SEND TEXT MAPPED 285 CHANGE PASSWORD 37
SEND TEXT NOEDIT 288 SIGNON 292
TWA option START 308
ADDRESS 14 VERIFY PASSWORD 319
TWALENG option USERNAME option
ASSIGN 29 ASSIGN 29
type codes (terminal) 351 USERPRIORITY option
TYPE operand ASSIGN 29
DFHMSD 401 USING option
ADDRESS SET 15

U
UNATTEND option V
ASSIGN 29 VALIDATION option
UNDERLINE value ASSIGN 29
DFHMDF 386 VALIDN operand
DFHMDI 393 DFHMDF 389
DFHMSD 399 DFHMDI 395
UNEXPIN condition DFHMSD 401
ISSUE ABORT 132 VERIFY PASSWORD command 318
ISSUE ADD 134 VIEWPOS operand
ISSUE END 142 DFHPDI 403
ISSUE ERASE 147 VIEWSZE operand
ISSUE NOTE 151 DFHPDI 403
ISSUE QUERY 156 VOLUME option
ISSUE RECEIVE 158 ISSUE ABORT 131
ISSUE REPLACE 160 ISSUE ADD 133
ISSUE SEND 163 ISSUE END 141
ISSUE WAIT 167 ISSUE ERASE 146
RECEIVE MAP 222 ISSUE NOTE 151

438 CICS/ESA Application Programming Reference

VOLUME option (continued) WPMEDIA option (continued)
ISSUE QUERY 156 ISSUE SEND 163
ISSUE REPLACE 159 ISSUE WAIT 166
ISSUE SEND 162 WRBRK condition
ISSUE WAIT 166 CONVERSE (non-VTAM) 64
VOLUMELENG option SEND (non-VTAM) 263
ISSUE ABORT 131 SEND CONTROL 267
ISSUE ADD 133 SEND MAP 273
ISSUE END 141 SEND PAGE 277
ISSUE ERASE 146 SEND TEXT 283
ISSUE NOTE 151 SEND TEXT MAPPED 285
ISSUE QUERY 156 SEND TEXT NOEDIT 288
ISSUE REPLACE 160 write break 56
ISSUE SEND 163 WRITE command 329
ISSUE WAIT 166 WRITE JOURNALNUM command 332
VSAM WRITE MASSINSERT WRITE OPERATOR command 334
DISABLED cannot occur 316 critical action 334
NOTOPEN cannot occur 317 eventual action 334
terminate operation 316 immediate action 334
VTAB operand WRITEQ TD command 336
DFHMSD 402 WRITEQ TS command 338
VTAM logon data, access to 88 writing data
to temporary storage queue 338
to terminal or logical unit 357
W to transient data queue 336
WAIT CONVID (APPC) command 320 writing records to data sets
WAIT EVENT command 321 batch data interchange 133
WAIT EXTERNAL command 322 file control 329
WAIT JOURNALNUM command 324
WAIT option
GDS SEND 118 X
ISSUE COPY (3270 display) 137 XCTL command 341
ISSUE COPY (3270 logical) 138 XINIT operand
ISSUE ERASEAUP 148 DFHMDF 389
RETRIEVE 233 XRF, generic applid 23
SEND (non-VTAM) 262
SEND (VTAM) 253
SEND command 357 Y
SEND CONTROL 266 YEAR option
SEND MAP 271 FORMATTIME 93
SEND TEXT 283 YES value
SEND TEXT MAPPED 284 DFHMDI 393, 394, 395
SEND TEXT NOEDIT 287 DFHMSD 398, 401
terminal control 357 YYDDD option
WRITE JOURNALNUM 333 FORMATTIME 93
WAIT SIGNAL command 325 YYDDMM option
WAIT TERMINAL command 326 FORMATTIME 93
general information 357 YYMMDD option
WAITCICS command 327 FORMATTIME 93
waits YYYYDDD option
batch data interchange 166 FORMATTIME 93
for event to occur 321 YYYYDDMM option
terminal control operation 357 FORMATTIME 94
WPMEDIA option YYYYMMDD option
ISSUE ABORT 131 FORMATTIME 94
ISSUE END 141

Index 439
Z
ZERO value
DFHMDF 386

440 CICS/ESA Application Programming Reference

Sending your comments to IBM
CICS for MVS/ESA.

Application Programming Reference

SC33-1170-03

If you especially like or dislike anything about this book, please use one of the methods listed below to
send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on the accuracy,
organization, subject matter, or completeness of this book. Please limit your comments to the information
in this book and the way in which the information is presented.

When you send comments to IBM, you grant s1tr9talusntatrightentsase uke ortributeimit your comm IBM
Readers’ Comments
CICS for MVS/ESA.

Application Programming Reference

SC33-1170-03
Use this form to tell us what you think about this manual. If you have found errors in it, or if you want
to express your opinion about it (such as organization, subject matter, appearance) or make
suggestions for improvement, this is the form to use.

To request additional publications, or to ask questions or make comments about the functions of IBM
products or systems, you should talk to your IBM representative or to your IBM authorized remarketer.
This form is provided for comments about the information in this manual and the way it is presented.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your
comments in any way it believes appropriate without incurring any obligation to you.

Be sure to print your name and address below if you would like a reply.

Name Address

Company or Organization

Telephone Email
CICS for MVS/ESA.

CICS/ESA Application Programming Reference SC33-1170-03

IBM
You can send your comments POST FREE on this form from any one of these countries:

Cut along this line

Australia Finland Iceland Netherlands Singapore United States
Belgium France Israel New Zealand Spain of America
Bermuda Germany Italy Norway Sweden
Cyprus Greece Luxembourg Portugal Switzerland
Denmark Hong Kong Monaco Republic of Ireland United Arab Emirates

If your country is not listed here, your local IBM representative will be pleased to forward your comments
to us. Or you can pay the postage and send the form direct to IBM (this includes mailing in the U.K.).
Fold along this line

By air mail NE PAS AFFRANCHIR

Par avion
IBRS/CCRI NUMBER: PHQ - D/1348/SO

NO STAMP REQUIRED

REPONSE PAYEE
GRANDE-BRETAGNE
IBM United Kingdom Laboratories Limited
Information Development Department (MP 095)
Hursley Park
WINCHESTER, Hants
SO21 2ZZ United Kingdom

Fold along this line

From: Name
Company or Organization
Cut along this line

Address

EMAIL
Telephone

Fasten here with adhesive tape

IBM 

Program Number: 5655-018

Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.

SC33-117O-O3
Spine information:

IBM CICS for MVS/ESA. Application Programming Ref Version 4 Release 1

THE LTSPICE XVII SIMULATOR: Commands and Applications
From Everand
THE LTSPICE XVII SIMULATOR: Commands and Applications
Gilles Brocard
5/5 (1)
Pacbase User Interface Guide
No ratings yet
Pacbase User Interface Guide
236 pages
Administration PDF
50% (2)
Administration PDF
341 pages
ProCash DDC V1400 ProConsult DDC V1200 UserGuide en
100% (2)
ProCash DDC V1400 ProConsult DDC V1200 UserGuide en
432 pages
ProCash NDC V2000 ProConsult NDC V2000 UserGuide en
No ratings yet
ProCash NDC V2000 ProConsult NDC V2000 UserGuide en
420 pages
35 Cics Diagnosis Ref
No ratings yet
35 Cics Diagnosis Ref
2,253 pages
Cics 1
No ratings yet
Cics 1
260 pages
VTAM Operations
No ratings yet
VTAM Operations
679 pages
Tso Sys
No ratings yet
Tso Sys
162 pages
CICS TS For ZOS - System Programming Reference
No ratings yet
CICS TS For ZOS - System Programming Reference
633 pages
ROSCOE - B001712e - System Commands Guide
No ratings yet
ROSCOE - B001712e - System Commands Guide
150 pages
Iea1a331 PDF
No ratings yet
Iea1a331 PDF
328 pages
Control M PDF
No ratings yet
Control M PDF
608 pages
Open Data Structures: An Introduction
From Everand
Open Data Structures: An Introduction
Pat Morin
4/5 (4)
Procash/Ndc V3.0/00 Proconsult/Ndc V3.0/00: User Guide
No ratings yet
Procash/Ndc V3.0/00 Proconsult/Ndc V3.0/00: User Guide
438 pages
Techref Ktechrf2
No ratings yet
Techref Ktechrf2
436 pages
Iea1a421 PDF
No ratings yet
Iea1a421 PDF
340 pages
Iea1a741 PDF
No ratings yet
Iea1a741 PDF
1,170 pages
Jes 2 Messages - Zos
No ratings yet
Jes 2 Messages - Zos
372 pages
QRG
No ratings yet
QRG
1,894 pages
Parameter Guide
No ratings yet
Parameter Guide
584 pages
MX800 Programmers Guide
No ratings yet
MX800 Programmers Guide
344 pages
CL Commands III
No ratings yet
CL Commands III
890 pages
Brocade Reference Guide
No ratings yet
Brocade Reference Guide
394 pages
Vse ICCF User's Guide
100% (2)
Vse ICCF User's Guide
509 pages
CNC Machining Handbook: Building, Programming, and Implementation
From Everand
CNC Machining Handbook: Building, Programming, and Implementation
Alan Overby
No ratings yet
CONTROL-M Parameter Guide
No ratings yet
CONTROL-M Parameter Guide
584 pages
cpm22 M
No ratings yet
cpm22 M
317 pages
CICS Custom Is at Ion Guide
No ratings yet
CICS Custom Is at Ion Guide
727 pages
Tsunami A2MP-81XX-CPE - ReferenceManualv2.2 - SWv2.3.5
No ratings yet
Tsunami A2MP-81XX-CPE - ReferenceManualv2.2 - SWv2.3.5
88 pages
AOS R13.12.0 Command Reference Guide
No ratings yet
AOS R13.12.0 Command Reference Guide
5,278 pages
CoreABC_HB
No ratings yet
CoreABC_HB
85 pages
Interproduct Communication: Cics Family
No ratings yet
Interproduct Communication: Cics Family
95 pages
XPCICSCOBOLUserGuide PDF
No ratings yet
XPCICSCOBOLUserGuide PDF
194 pages
Mpasm Users Guide
No ratings yet
Mpasm Users Guide
164 pages
Bti7800 Cli Ref Guide
No ratings yet
Bti7800 Cli Ref Guide
298 pages
Hspice Cmdref
No ratings yet
Hspice Cmdref
900 pages
F001681E
No ratings yet
F001681E
224 pages
Iea1a121 PDF
No ratings yet
Iea1a121 PDF
474 pages
CICS Supplied Transaction
No ratings yet
CICS Supplied Transaction
317 pages
CICS Family Interproduct Communication
No ratings yet
CICS Family Interproduct Communication
93 pages
Cfe Usersguide
No ratings yet
Cfe Usersguide
1,195 pages
Questa Sim Ref
100% (1)
Questa Sim Ref
1,198 pages
Tib RV Administration
No ratings yet
Tib RV Administration
457 pages
BSPLCML
No ratings yet
BSPLCML
762 pages
XPCICSAssemblerUserGuide (9.4)
No ratings yet
XPCICSAssemblerUserGuide (9.4)
178 pages
Rexx
No ratings yet
Rexx
572 pages
BMC Atrium Orchestra Tor Version 7.6.05.00 Base Adapters
No ratings yet
BMC Atrium Orchestra Tor Version 7.6.05.00 Base Adapters
706 pages
SQN AT Commands Reference PDF
No ratings yet
SQN AT Commands Reference PDF
314 pages
Cics 400 Administration and Operations Guide
No ratings yet
Cics 400 Administration and Operations Guide
343 pages
PCIe Express
No ratings yet
PCIe Express
362 pages
Manual Workcenter 3315
No ratings yet
Manual Workcenter 3315
264 pages
ProCash NDC V1400 ProConsult NDC V1200 UserGuide en
100% (1)
ProCash NDC V1400 ProConsult NDC V1200 UserGuide en
398 pages
Basic 52 Manual
No ratings yet
Basic 52 Manual
220 pages
Mx800 Reference Manual v2
No ratings yet
Mx800 Reference Manual v2
74 pages
Control M Userguide
No ratings yet
Control M Userguide
190 pages
Modelsim Ref
No ratings yet
Modelsim Ref
542 pages
Us905 Usermanual
No ratings yet
Us905 Usermanual
112 pages
Quasi-Monte Carlo Methods in Finance: With Application to Optimal Asset Allocation
From Everand
Quasi-Monte Carlo Methods in Finance: With Application to Optimal Asset Allocation
Mario Rometsch
No ratings yet
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
1/5 (1)
Mainframe Resume
100% (1)
Mainframe Resume
4 pages
LE Migration Cookbook v4.3
No ratings yet
LE Migration Cookbook v4.3
19 pages
MJResume
No ratings yet
MJResume
4 pages
DB2 DBA Course Contents - Mainframesguru
No ratings yet
DB2 DBA Course Contents - Mainframesguru
4 pages
Lzlabs Software Defined Mainframe Product Data Sheet
No ratings yet
Lzlabs Software Defined Mainframe Product Data Sheet
4 pages
Timothy J. Perkins
No ratings yet
Timothy J. Perkins
3 pages
Ca Telon
No ratings yet
Ca Telon
3 pages
IBM Common Data Provider
No ratings yet
IBM Common Data Provider
44 pages
Teradata API
No ratings yet
Teradata API
237 pages
Architecting EBusinees Access To CICS PDF
No ratings yet
Architecting EBusinees Access To CICS PDF
378 pages
Cics Training Class - 03
No ratings yet
Cics Training Class - 03
21 pages
CICS V5 TechOverview
No ratings yet
CICS V5 TechOverview
94 pages
Resume of Rbburpo
No ratings yet
Resume of Rbburpo
2 pages
AS400 Glossary: A AIX - Apache
No ratings yet
AS400 Glossary: A AIX - Apache
6 pages
Servlet
No ratings yet
Servlet
620 pages
Cics VR
No ratings yet
Cics VR
32 pages
cobol ppt
No ratings yet
cobol ppt
38 pages
Stephen A. Dowell - Resume - 11 12 2013
No ratings yet
Stephen A. Dowell - Resume - 11 12 2013
4 pages
IBM Debug Tool - User Document
No ratings yet
IBM Debug Tool - User Document
6 pages
22 zTidBits (IMS - Then&ToDay) PDF
No ratings yet
22 zTidBits (IMS - Then&ToDay) PDF
11 pages
Cics Eib
No ratings yet
Cics Eib
2 pages
GC33-0155-2 CICS VS Version 1.6 and 1.7 General Information Jul85 PDF
No ratings yet
GC33-0155-2 CICS VS Version 1.6 and 1.7 General Information Jul85 PDF
101 pages
Tivoli and WebSphere Application Server On Z-OS Sg247062
No ratings yet
Tivoli and WebSphere Application Server On Z-OS Sg247062
384 pages
Program Directory For Websphere MQ For Z/Os
No ratings yet
Program Directory For Websphere MQ For Z/Os
68 pages
WILY, Managing Critical Applications With Wily Introscope, Robert Dring
No ratings yet
WILY, Managing Critical Applications With Wily Introscope, Robert Dring
92 pages
Eazytrieve
No ratings yet
Eazytrieve
310 pages
Control Flow
No ratings yet
Control Flow
14 pages
RDZ Workbench - BMS Map Editor
100% (1)
RDZ Workbench - BMS Map Editor
80 pages
Mainframe Architecture Product Overview 1218153498319609 9
100% (1)
Mainframe Architecture Product Overview 1218153498319609 9
69 pages