0% found this document useful (0 votes)

844 views729 pages

CICS Application Programming Guide

Uploaded by

Srinivas Bedarakota

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

844 views729 pages

CICS Application Programming Guide

Uploaded by

Srinivas Bedarakota

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 729

CICS Transaction Server for z/OS 򔻐򗗠򙳰

CICS Application Programming Guide

Version 3 Release 1

SC34-6433-00
CICS Transaction Server for z/OS 򔻐򗗠򙳰

CICS Application Programming Guide

Version 3 Release 1

SC34-6433-00
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
699.

First edition (March 2005)

This edition applies to Version 3 Release 1 of CICS Transaction Server for z/OS, program number 5655-M15, and
to all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are
using the correct edition for the level of the product.
© Copyright International Business Machines Corporation 1989, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
What this book is about . . . . . . . . . . . . . . . . . . . . . xix
Who should read this book . . . . . . . . . . . . . . . . . . . xix

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xxi

Changes for CICS Transaction Server for z/OS, Version 3 Release 1 . . . . . xxi
Changes for CICS Transaction Server for z/OS, Version 2 Release 3 . . . . . xxi
Changes for CICS Transaction Server for z/OS, Version 2 Release 2 . . . . . xxi
Changes for CICS Transaction Server for z/OS, Version 2 Release 1 . . . . . xxi
Changes for CICS Transaction Server for OS/390, Version 1 Release 3 . . . xxii

Part 1. Writing CICS Applications . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. What is a CICS application? . . . . . . . . . . . . . . . 3

CICS programs, transactions and tasks . . . . . . . . . . . . . . . . 3

Chapter 2. CICS programming . . . . . . . . . . . . . . . . . . . 5

CICS programming commands . . . . . . . . . . . . . . . . . . . 5
System programming commands . . . . . . . . . . . . . . . . . . 6
EXEC interface block (EIB) . . . . . . . . . . . . . . . . . . . . 6
Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Translator Options . . . . . . . . . . . . . . . . . . . . . . . 6
Testing for CICS . . . . . . . . . . . . . . . . . . . . . . . . . 7
CICS programming roadmap . . . . . . . . . . . . . . . . . . . . 7

Chapter 3. Language Environment . . . . . . . . . . . . . . . . . 9

Language Environment services . . . . . . . . . . . . . . . . . . 10
Using Language Environment Abend-handling . . . . . . . . . . . . . 11
User-written Language Environment condition handlers . . . . . . . . . 11
Managing Language Environment storage . . . . . . . . . . . . . . . 12
Mixing languages in Language Environment . . . . . . . . . . . . . . 13
Using Dynamic Link Libraries and Language Environment . . . . . . . . . 15
Defining runtime options for Language Environment . . . . . . . . . . . 15
Runtime options in child enclaves . . . . . . . . . . . . . . . . . 17
CEEBXITA coding . . . . . . . . . . . . . . . . . . . . . . . 18
Determining which options were used . . . . . . . . . . . . . . . 18
Writing a CEEBINT initialization exit for Language Environment . . . . . . . 18

Chapter 4. Programming in COBOL . . . . . . . . . . . . . . . . 21

COBOL programming considerations . . . . . . . . . . . . . . . . . 21
Programming restrictions . . . . . . . . . . . . . . . . . . . . 21
Using the DL/I CALL interface . . . . . . . . . . . . . . . . . . 24
Language Environment considerations for COBOL applications . . . . . . . 25
CBLPSHPOP option . . . . . . . . . . . . . . . . . . . . . . 26
Using based addressing with COBOL . . . . . . . . . . . . . . . . 26
Using WITH DEBUGGING MODE . . . . . . . . . . . . . . . . . 27
Calling subprograms from COBOL . . . . . . . . . . . . . . . . . . 27
Rules for calling subprograms . . . . . . . . . . . . . . . . . . 29
Flow of control between programs and subprograms . . . . . . . . . . 31
Using the COBOL2 and COBOL3 translator options . . . . . . . . . . . 33
Literals intervening in blank lines . . . . . . . . . . . . . . . . . 33
Lower case characters . . . . . . . . . . . . . . . . . . . . . 34
Sequence numbers containing any character . . . . . . . . . . . . . 34
© Copyright IBM Corp. 1989, 2005 iii
REPLACE statement . . . . . . . . . . . . . . . . . . . . . . 35
Batch compilation . . . . . . . . . . . . . . . . . . . . . . . 35
Nested programs . . . . . . . . . . . . . . . . . . . . . . . 37
Reference modification . . . . . . . . . . . . . . . . . . . . . 41
Global variables . . . . . . . . . . . . . . . . . . . . . . . 41
Comma and semicolon as delimiters . . . . . . . . . . . . . . . . 41
Symbolic character definition . . . . . . . . . . . . . . . . . . . 41
Using the OO COBOL translator option . . . . . . . . . . . . . . . . 42
Translator action . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 5. Programming in C and C++ . . . . . . . . . . . . . . . 43

C and C++ programming considerations . . . . . . . . . . . . . . . 43
| XPLink considerations for C and C++ programming . . . . . . . . . . 47
Passing arguments in C or C++ . . . . . . . . . . . . . . . . . . . 49
Accessing the EIB . . . . . . . . . . . . . . . . . . . . . . . . 50
Naming EIB fields . . . . . . . . . . . . . . . . . . . . . . . 50
Using Locale support . . . . . . . . . . . . . . . . . . . . . . 51
Programming in C++ . . . . . . . . . . . . . . . . . . . . . . . 51
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 6. Programming in PL/I . . . . . . . . . . . . . . . . . . 53

PL/I programming restrictions . . . . . . . . . . . . . . . . . . . 53
Language Environment considerations for PL/I applications . . . . . . . . 54

Chapter 7. Programming in Assembler . . . . . . . . . . . . . . . 57

Language Environment considerations for Assembler applications . . . . . . 58
Calling Assembler programs . . . . . . . . . . . . . . . . . . . . 60

Part 2. Preparing applications to run . . . . . . . . . . . . . . . . . . . . . 63

Chapter 8. Translation and compilation . . . . . . . . . . . . . . . 67

The integrated CICS translator . . . . . . . . . . . . . . . . . . . 67
Using the integrated CICS translator . . . . . . . . . . . . . . . . 68
Specifying CICS translator options . . . . . . . . . . . . . . . . . 68
The translation process . . . . . . . . . . . . . . . . . . . . . . 69
The CICS-supplied translators . . . . . . . . . . . . . . . . . . . 72
Dynamic invocation of the separate translator . . . . . . . . . . . . 72
Using a CICS translator . . . . . . . . . . . . . . . . . . . . . 73
Defining translator options . . . . . . . . . . . . . . . . . . . . . 74
Translator options . . . . . . . . . . . . . . . . . . . . . . . 75
Translator options table . . . . . . . . . . . . . . . . . . . . . 85
Using COPY statements . . . . . . . . . . . . . . . . . . . . . 86
The CICS-supplied interface modules . . . . . . . . . . . . . . . . 86
The EXEC interface modules. . . . . . . . . . . . . . . . . . . 86
The CPI Communications interface module . . . . . . . . . . . . . 86
The SAA Resource Recovery interface module . . . . . . . . . . . . 86
Using the EXEC interface modules . . . . . . . . . . . . . . . . . 87
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 87
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
C and C++ . . . . . . . . . . . . . . . . . . . . . . . . . 88
Assembler language . . . . . . . . . . . . . . . . . . . . . . 89
| EXAMPLE Assembler language PROGRAM using LEASM . . . . . . . . 89

Chapter 9. Installing application programs . . . . . . . . . . . . . . 99

Program installation roadmap . . . . . . . . . . . . . . . . . . . 99
Preparing for program installation . . . . . . . . . . . . . . . . 100

iv CICS TS for z/OS: CICS Application Programming Guide

Defining MVS residence and addressing modes . . . . . . . . . . . . 101
Establishing a program’s addressing mode . . . . . . . . . . . . . 101
CICS address space considerations . . . . . . . . . . . . . . . . 101
Making programs permanently resident . . . . . . . . . . . . . . 102
Running applications in the link pack area . . . . . . . . . . . . . . 102
Running application programs in the RDSAs . . . . . . . . . . . . . 103
Assembler . . . . . . . . . . . . . . . . . . . . . . . . . 103
C and C/++ . . . . . . . . . . . . . . . . . . . . . . . . . 104
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 105
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using BMS map sets in application programs . . . . . . . . . . . . . 106
Using the CICS-supplied procedures to install application programs . . . . . 106
Installing programs in load library secondary extents . . . . . . . . . 107
Including the CICS-supplied interface modules . . . . . . . . . . . . . 108
Installing assembler language application programs . . . . . . . . . . . 108
Installing COBOL application programs . . . . . . . . . . . . . . . 110
Sample JCL to install COBOL application programs . . . . . . . . . . 111
Installing PL/I application programs . . . . . . . . . . . . . . . . . 114
Sample JCL to install PL/I application programs . . . . . . . . . . . 114
PL/I procedure with an integrated translator . . . . . . . . . . . . . 115
Installing C application programs . . . . . . . . . . . . . . . . . . 117
Sample JCL to install C application programs . . . . . . . . . . . . 118
Using your own job streams. . . . . . . . . . . . . . . . . . . . 119
Translator requirements . . . . . . . . . . . . . . . . . . . . 119
Online programs that use EXEC CICS or EXEC DLI commands . . . . . 119
Online programs that use the CALL DLI interface . . . . . . . . . . . 122
Batch or BMP programs that use EXEC DLI commands . . . . . . . . 123
Batch or BMP programs that use DL/I CALL commands . . . . . . . . 123

Chapter 10. Installing map sets and partition sets . . . . . . . . . . 125

Installing map sets . . . . . . . . . . . . . . . . . . . . . . . 126
Types of map sets . . . . . . . . . . . . . . . . . . . . . . 126
Installing physical map sets . . . . . . . . . . . . . . . . . . . 128
Installing symbolic description map sets . . . . . . . . . . . . . . 129
Installing physical and symbolic description maps together . . . . . . . 131
Installing partition sets . . . . . . . . . . . . . . . . . . . . . . 133
Defining programs, map sets, and partition sets to CICS . . . . . . . . . 134

Part 3. Application design . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Chapter 11. Application design . . . . . . . . . . . . . . . . . . 139

Pseudoconversational and conversational design . . . . . . . . . . . . 140
Terminal interruptibility . . . . . . . . . . . . . . . . . . . . . 142
How tasks are started . . . . . . . . . . . . . . . . . . . . . . 142
Which transaction? . . . . . . . . . . . . . . . . . . . . . . . 143
Separating business and presentation logic . . . . . . . . . . . . . . 146
Multithreading: Reentrant, quasi-reentrant and threadsafe programs . . . . . 147
Quasi-reentrant application programs . . . . . . . . . . . . . . . 147
Threadsafe programs . . . . . . . . . . . . . . . . . . . . . 149
| OPENAPI programs . . . . . . . . . . . . . . . . . . . . . 153
Using the FORCEQR system initialization parameter . . . . . . . . . 155
Non-reentrant programs . . . . . . . . . . . . . . . . . . . . 155
Storing data within a transaction . . . . . . . . . . . . . . . . . . 155
Transaction work area (TWA) . . . . . . . . . . . . . . . . . . 156
User storage . . . . . . . . . . . . . . . . . . . . . . . . 156
COMMAREA in LINK and XCTL commands . . . . . . . . . . . . . 157

Contents v
| Channels in LINK and XCTL commands . . . . . . . . . . . . . . 157
Program storage . . . . . . . . . . . . . . . . . . . . . . . 158
Temporary storage . . . . . . . . . . . . . . . . . . . . . . 158
Intrapartition transient data . . . . . . . . . . . . . . . . . . . 159
GETMAIN SHARED command . . . . . . . . . . . . . . . . . 160
Your own data sets . . . . . . . . . . . . . . . . . . . . . . 160
Lengths of areas passed to CICS commands . . . . . . . . . . . . . 161
LENGTH options . . . . . . . . . . . . . . . . . . . . . . . 161
Journal records . . . . . . . . . . . . . . . . . . . . . . . 161
Data set definitions . . . . . . . . . . . . . . . . . . . . . . 161
Recommendation . . . . . . . . . . . . . . . . . . . . . . 161
Minimizing errors . . . . . . . . . . . . . . . . . . . . . . . . 162
Protecting CICS from application errors . . . . . . . . . . . . . . 162
Testing applications . . . . . . . . . . . . . . . . . . . . . . 162
Non-terminal transaction security . . . . . . . . . . . . . . . . . . 163

Chapter 12. Design for performance . . . . . . . . . . . . . . . . 165

Program size . . . . . . . . . . . . . . . . . . . . . . . . . 165
Virtual storage. . . . . . . . . . . . . . . . . . . . . . . . . 166
Reducing paging effects . . . . . . . . . . . . . . . . . . . . 167
Exclusive control of resources . . . . . . . . . . . . . . . . . . . 169
Operational control . . . . . . . . . . . . . . . . . . . . . . . 170
Operating system waits . . . . . . . . . . . . . . . . . . . . . 171
The NOSUSPEND option . . . . . . . . . . . . . . . . . . . . 171
Efficient data operations . . . . . . . . . . . . . . . . . . . . . 172
Efficient database operations . . . . . . . . . . . . . . . . . . 172
Efficient data set operations. . . . . . . . . . . . . . . . . . . 172
Efficient browsing (in non-RLS mode) . . . . . . . . . . . . . . . 174
Efficient logging . . . . . . . . . . . . . . . . . . . . . . . 175
Efficient sequential data set access . . . . . . . . . . . . . . . . 175
Efficient terminal operations . . . . . . . . . . . . . . . . . . . . 176
Length of the data stream sent to the terminal . . . . . . . . . . . . 176
Basic mapping support considerations . . . . . . . . . . . . . . . 176
Page-building and routing operations . . . . . . . . . . . . . . . 179
Requests for printed output . . . . . . . . . . . . . . . . . . . 181
Additional terminal control considerations . . . . . . . . . . . . . . 181

Chapter 13. Sharing data across transactions . . . . . . . . . . . . 183

Using the common work area (CWA) . . . . . . . . . . . . . . . . 183
Protecting the CWA . . . . . . . . . . . . . . . . . . . . . . 184
Using the TCTTE user area (TCTUA) . . . . . . . . . . . . . . . . 186
Using the COMMAREA in RETURN commands . . . . . . . . . . . . 187
| Using a channel on RETURN commands . . . . . . . . . . . . . . . 187
Using the display screen to share data . . . . . . . . . . . . . . . 188

Chapter 14. Enhanced inter-program data transfer: channels as

vi CICS TS for z/OS: CICS Application Programming Guide

The current channel . . . . . . . . . . . . . . . . . . . . . . 196
Current channel example, with LINK commands . . . . . . . . . . . 196
Current channel example, with XCTL commands . . . . . . . . . . . 198
Current channel: START and RETURN commands . . . . . . . . . . 199
The scope of a channel . . . . . . . . . . . . . . . . . . . . . 200
Scope example, with LINK commands . . . . . . . . . . . . . . . 200
Scope example, with LINK and XCTL commands . . . . . . . . . . . 202
Discovering which containers a program’s been passed . . . . . . . . . 204
Discovering which containers were returned from a link . . . . . . . . . 204
CICS read only containers . . . . . . . . . . . . . . . . . . . . 204
Designing a channel: best practices . . . . . . . . . . . . . . . . . 205
Constructing and using a channel: an example. . . . . . . . . . . . . 206
Channels and BTS activities . . . . . . . . . . . . . . . . . . . 207
Context . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Using channels from JCICS . . . . . . . . . . . . . . . . . . . . 209
Dynamic routing with channels . . . . . . . . . . . . . . . . . . 209
Data conversion . . . . . . . . . . . . . . . . . . . . . . . . 210
Why is data conversion needed? . . . . . . . . . . . . . . . . . 210
Preparing for code page conversion with channels . . . . . . . . . . 210
Data conversion with channels . . . . . . . . . . . . . . . . . 212
Benefits of channels . . . . . . . . . . . . . . . . . . . . . . 215
Migrating from COMMAREAs to channels . . . . . . . . . . . . . . 216
Migration of existing functions . . . . . . . . . . . . . . . . . . 216
Migration to the new function . . . . . . . . . . . . . . . . . . 216

Chapter 15. Affinity . . . . . . . . . . . . . . . . . . . . . . 219

Types of affinity . . . . . . . . . . . . . . . . . . . . . . . . 220
Inter-transaction affinity . . . . . . . . . . . . . . . . . . . . 220
Transaction-system affinity . . . . . . . . . . . . . . . . . . . 220
Programming techniques and affinity . . . . . . . . . . . . . . . . 221
Safe techniques . . . . . . . . . . . . . . . . . . . . . . . 221
Unsafe techniques . . . . . . . . . . . . . . . . . . . . . . 221
Suspect techniques . . . . . . . . . . . . . . . . . . . . . . 222
Recommendations . . . . . . . . . . . . . . . . . . . . . . 222
Safe programming to avoid affinity . . . . . . . . . . . . . . . . . 222
The COMMAREA . . . . . . . . . . . . . . . . . . . . . . 223
The TCTUA . . . . . . . . . . . . . . . . . . . . . . . . 224
Using ENQ and DEQ commands with ENQMODEL resource definitions 226
BTS containers . . . . . . . . . . . . . . . . . . . . . . . 227
Unsafe programming for affinity . . . . . . . . . . . . . . . . . . 227
Using the common work area . . . . . . . . . . . . . . . . . . 227
Using GETMAIN SHARED storage . . . . . . . . . . . . . . . . 228
Using the LOAD PROGRAM HOLD command . . . . . . . . . . . . 229
Sharing task-lifetime storage . . . . . . . . . . . . . . . . . . 230
Using the WAIT EVENT command . . . . . . . . . . . . . . . . 232
Using ENQ and DEQ commands without ENQMODEL resource definitions 233
Suspect programming for affinity . . . . . . . . . . . . . . . . . . 234
Using temporary storage . . . . . . . . . . . . . . . . . . . . 234
Using transient data . . . . . . . . . . . . . . . . . . . . . 237
Using the RETRIEVE WAIT and START commands . . . . . . . . . . 238
Using the START and CANCEL REQID commands . . . . . . . . . . 239
Using the DELAY and CANCEL REQID commands . . . . . . . . . . 241
Using the POST and CANCEL REQID commands . . . . . . . . . . 242
Detecting inter-transaction affinities . . . . . . . . . . . . . . . . . 244
Inter-transaction affinities caused by application generators . . . . . . . 244
Duration and scope of inter-transaction affinities . . . . . . . . . . . . 244

Contents vii
Affinity transaction groups . . . . . . . . . . . . . . . . . . . 245
Relations and lifetimes . . . . . . . . . . . . . . . . . . . . 245

Chapter 16. Recovery design . . . . . . . . . . . . . . . . . . 253

Journaling . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Journal records . . . . . . . . . . . . . . . . . . . . . . . 253
Journal output synchronization . . . . . . . . . . . . . . . . . . 253
Syncpointing . . . . . . . . . . . . . . . . . . . . . . . . . 255

Chapter 17. Dealing with exception conditions . . . . . . . . . . . 257

Default CICS exception handling . . . . . . . . . . . . . . . . . . 257
Handling exception conditions by in-line code . . . . . . . . . . . . . 258
How to use the RESP and RESP2 options . . . . . . . . . . . . . 258
An example of exception handling in C . . . . . . . . . . . . . . 259
An example of exception handling in COBOL . . . . . . . . . . . . 260
Modifying default CICS exception handling . . . . . . . . . . . . . . 261
Using the HANDLE CONDITION command . . . . . . . . . . . . . . 263
RESP and NOHANDLE options . . . . . . . . . . . . . . . . . 264
How CICS keeps track of what to do . . . . . . . . . . . . . . . 264
Using the HANDLE CONDITION ERROR command. . . . . . . . . . . 265
Using the IGNORE CONDITION command . . . . . . . . . . . . . . 265
Using the HANDLE ABEND command . . . . . . . . . . . . . . . . 266
Using PUSH HANDLE and POP HANDLE commands . . . . . . . . . . 267

Chapter 18. Abnormal termination recovery . . . . . . . . . . . . . 269

Chapter 19. The QUERY SECURITY command . . . . . . . . . . . . 277

Using the QUERY SECURITY command . . . . . . . . . . . . . . . 277
Security protection at the record or field level . . . . . . . . . . . . 277
CICS-defined resource identifiers . . . . . . . . . . . . . . . . . 278
SEC system initialization parameter . . . . . . . . . . . . . . . . 278
Programming hints . . . . . . . . . . . . . . . . . . . . . . 278

Part 4. Data Management . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Chapter 20. An overview of file control . . . . . . . . . . . . . . . 283

VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . 283
Key-sequenced data set (KSDS) . . . . . . . . . . . . . . . . . 283
Entry-sequenced data set (ESDS) . . . . . . . . . . . . . . . . 284
Relative record data set (RRDS) . . . . . . . . . . . . . . . . . 284
Empty data sets . . . . . . . . . . . . . . . . . . . . . . . 284
VSAM alternate indexes . . . . . . . . . . . . . . . . . . . . 285
Accessing files in RLS mode . . . . . . . . . . . . . . . . . . 285
BDAM data sets . . . . . . . . . . . . . . . . . . . . . . . . 286
CICS shared data tables . . . . . . . . . . . . . . . . . . . . . 287
Coupling facility data tables . . . . . . . . . . . . . . . . . . . . 288
Coupling facility data table models . . . . . . . . . . . . . . . . 289
Techniques for sharing data . . . . . . . . . . . . . . . . . . . . 290
Using CICS commands to read records . . . . . . . . . . . . . . . 292
Direct reading (using READ command) . . . . . . . . . . . . . . 293

viii CICS TS for z/OS: CICS Application Programming Guide

Sequential reading (browsing) . . . . . . . . . . . . . . . . . . 294
Skip-sequential processing . . . . . . . . . . . . . . . . . . . 296
Using CICS commands to update records . . . . . . . . . . . . . . 297
Using CICS commands to delete records . . . . . . . . . . . . . . . 298
Deleting single records . . . . . . . . . . . . . . . . . . . . 298
Deleting groups of records (generic delete) . . . . . . . . . . . . . 299
Read integrity . . . . . . . . . . . . . . . . . . . . . . . . 299
Using CICS commands to add records . . . . . . . . . . . . . . . 299
Adding to a KSDS . . . . . . . . . . . . . . . . . . . . . . 299
Adding to an ESDS . . . . . . . . . . . . . . . . . . . . . . 300
Adding to an RRDS. . . . . . . . . . . . . . . . . . . . . . 300
Records that are already locked . . . . . . . . . . . . . . . . . 300
Specifying record length . . . . . . . . . . . . . . . . . . . . 300
Sequential adding of records (WRITE MASSINSERT command) . . . . . 300
File control command options . . . . . . . . . . . . . . . . . . . 301
The RIDFLD option . . . . . . . . . . . . . . . . . . . . . . 301
The INTO and SET options . . . . . . . . . . . . . . . . . . . 301
The FROM option . . . . . . . . . . . . . . . . . . . . . . 302
The TOKEN option . . . . . . . . . . . . . . . . . . . . . . 302
KEYLENGTH option for remote data sets. . . . . . . . . . . . . . 302
Transaction deadlocks . . . . . . . . . . . . . . . . . . . . . . 303
VSAM-detected deadlocks (RLS only) . . . . . . . . . . . . . . . 304
Rules for avoiding deadlocks . . . . . . . . . . . . . . . . . . 305

Chapter 21. File control—VSAM considerations . . . . . . . . . . . 307

VSAM record identification . . . . . . . . . . . . . . . . . . . . 307
Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Relative byte address (RBA) and relative record number (RRN) . . . . . 307
Locking of VSAM records in recoverable files . . . . . . . . . . . . . 308
Update locks and delete locks (non-RLS mode only) . . . . . . . . . 308
RLS Record level locking . . . . . . . . . . . . . . . . . . . . 309
Exclusive locks and shared locks . . . . . . . . . . . . . . . . . 309
Conditional VSAM file update requests . . . . . . . . . . . . . . . 312
File control implementation of NOSUSPEND . . . . . . . . . . . . 312
CICS locking for writing to ESDS . . . . . . . . . . . . . . . . . . 312

Chapter 22. File control—BDAM considerations . . . . . . . . . . . 315

Identifying BDAM records . . . . . . . . . . . . . . . . . . . . 315
Block reference subfield . . . . . . . . . . . . . . . . . . . . 315
Physical key subfield . . . . . . . . . . . . . . . . . . . . . 315
Deblocking argument subfield . . . . . . . . . . . . . . . . . . 315
Browsing records from BDAM data sets . . . . . . . . . . . . . . . 316
Adding records to BDAM data sets . . . . . . . . . . . . . . . . . 317
Updating records from BDAM data sets . . . . . . . . . . . . . . 318

Chapter 23. Database control . . . . . . . . . . . . . . . . . . 319

DL/I databases . . . . . . . . . . . . . . . . . . . . . . . . 319
DB2 databases . . . . . . . . . . . . . . . . . . . . . . . . 319
Requests to DB2 . . . . . . . . . . . . . . . . . . . . . . . 319

Chapter 24. CICS documents . . . . . . . . . . . . . . . . . . 321

Using the DOCUMENT programming interface . . . . . . . . . . . . . 321
Creating a document . . . . . . . . . . . . . . . . . . . . . 321
Setting up document templates . . . . . . . . . . . . . . . . . . 322
Templates in a partitioned data set . . . . . . . . . . . . . . . . 322
Templates in a CICS program . . . . . . . . . . . . . . . . . . 323

Contents ix
Templates in CICS files, z/OS UNIX System Services HFS files, temporary
storage, or transient data . . . . . . . . . . . . . . . . . . . 323
Creating templates in exit programs . . . . . . . . . . . . . . . . 324
Programming with documents and document templates . . . . . . . . . 325
Symbols and symbol lists . . . . . . . . . . . . . . . . . . . 325
Setting symbol values . . . . . . . . . . . . . . . . . . . . . 326
Embedded template commands . . . . . . . . . . . . . . . . . 328
Using templates in your application . . . . . . . . . . . . . . . . 329
The lifespan of a document . . . . . . . . . . . . . . . . . . . 330
Constructing a document . . . . . . . . . . . . . . . . . . . . 332
Using Bookmarks . . . . . . . . . . . . . . . . . . . . . . 334
Code page conversion for documents . . . . . . . . . . . . . . . 335

Chapter 25. Named counter servers . . . . . . . . . . . . . . . . 337

The named counter fields . . . . . . . . . . . . . . . . . . . . 337
Named counter pools . . . . . . . . . . . . . . . . . . . . . . 338
Named counter options table . . . . . . . . . . . . . . . . . . 338
Using the named counter EXEC interface . . . . . . . . . . . . . . 339
Using the named counter CALL interface . . . . . . . . . . . . . . . 341
Application programming considerations . . . . . . . . . . . . . . 341
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Return codes . . . . . . . . . . . . . . . . . . . . . . . . 351
Named counter recovery . . . . . . . . . . . . . . . . . . . . . 354

Part 5. Data Communication . . . . . . . . . . . . . . . . . . . . . . . . . 357

Chapter 26. Terminal control . . . . . . . . . . . . . . . . . . . 361

Terminal access method support . . . . . . . . . . . . . . . . . . 362
Terminal control commands . . . . . . . . . . . . . . . . . . . . 362
Send/receive mode . . . . . . . . . . . . . . . . . . . . . . 363
Speaking out of turn . . . . . . . . . . . . . . . . . . . . . 364
Interrupting . . . . . . . . . . . . . . . . . . . . . . . . . 365
Terminal waits . . . . . . . . . . . . . . . . . . . . . . . . 365
Using data transmission commands . . . . . . . . . . . . . . . . . 366
What you get on a RECEIVE . . . . . . . . . . . . . . . . . . 366
Device control commands . . . . . . . . . . . . . . . . . . . . 367
Terminal device support . . . . . . . . . . . . . . . . . . . . . 368
Finding out about your terminal . . . . . . . . . . . . . . . . . . 371
EIB feedback on terminal control operations . . . . . . . . . . . . . 373
Using VTAM . . . . . . . . . . . . . . . . . . . . . . . . . 374
Chaining input data . . . . . . . . . . . . . . . . . . . . . . 374
Chaining output data . . . . . . . . . . . . . . . . . . . . . 374
Handling logical records . . . . . . . . . . . . . . . . . . . . 375
Response protocol . . . . . . . . . . . . . . . . . . . . . . 375
Using function management headers . . . . . . . . . . . . . . . 376
Preventing interruptions (bracket protocol) . . . . . . . . . . . . . 376
Using sequential terminal support . . . . . . . . . . . . . . . . . 377
Coding considerations for sequential terminals . . . . . . . . . . . . 378
| Using TCAM . . . . . . . . . . . . . . . . . . . . . . . . . 379
| Coding for the TCAM/DCB interface. . . . . . . . . . . . . . . . 379
Using batch data interchange . . . . . . . . . . . . . . . . . . . 379
Destination selection and identification . . . . . . . . . . . . . . . 381
Definite response . . . . . . . . . . . . . . . . . . . . . . 381
Waiting for function completion . . . . . . . . . . . . . . . . . 381

Chapter 27. The 3270 family of terminals . . . . . . . . . . . . . . 383

x CICS TS for z/OS: CICS Application Programming Guide

History of the 3270 . . . . . . . . . . . . . . . . . . . . . . . 383
Screen fields . . . . . . . . . . . . . . . . . . . . . . . . 384
Personal computers . . . . . . . . . . . . . . . . . . . . . 384
The 3270 buffer . . . . . . . . . . . . . . . . . . . . . . . . 386
The output datastream . . . . . . . . . . . . . . . . . . . . . 386
3270 write commands . . . . . . . . . . . . . . . . . . . . . 386
3270 display fields . . . . . . . . . . . . . . . . . . . . . . . 388
Display characteristics . . . . . . . . . . . . . . . . . . . . . 388
3270 field attributes . . . . . . . . . . . . . . . . . . . . . . . 388
Protection . . . . . . . . . . . . . . . . . . . . . . . . . 389
Modification . . . . . . . . . . . . . . . . . . . . . . . . 389
Intensity . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Base color . . . . . . . . . . . . . . . . . . . . . . . . . 390
Extended attributes . . . . . . . . . . . . . . . . . . . . . . 390
Orders in the data stream . . . . . . . . . . . . . . . . . . . . 391
The start field order . . . . . . . . . . . . . . . . . . . . . . 391
The modify field order . . . . . . . . . . . . . . . . . . . . . 392
The set buffer address order . . . . . . . . . . . . . . . . . . 393
The set attribute order . . . . . . . . . . . . . . . . . . . . . 393
Outbound data stream sample . . . . . . . . . . . . . . . . . . . 394
Input from a 3270 terminal . . . . . . . . . . . . . . . . . . . . 396
Data keys . . . . . . . . . . . . . . . . . . . . . . . . . 396
Keyboard control keys . . . . . . . . . . . . . . . . . . . . . 396
Attention keys . . . . . . . . . . . . . . . . . . . . . . . . 396
Reading from a 3270 terminal . . . . . . . . . . . . . . . . . . . 398
Inbound field format . . . . . . . . . . . . . . . . . . . . . . 398
Input data stream example . . . . . . . . . . . . . . . . . . . . 399
Unformatted mode . . . . . . . . . . . . . . . . . . . . . . . 399

Chapter 28. CICS support for printing . . . . . . . . . . . . . . . 401

Formatting for CICS printers . . . . . . . . . . . . . . . . . . . 401
CICS 3270 printers . . . . . . . . . . . . . . . . . . . . . . . 402
CICS 3270 printer options . . . . . . . . . . . . . . . . . . . . 403
PRINT option and print control bit . . . . . . . . . . . . . . . . 403
ERASE option . . . . . . . . . . . . . . . . . . . . . . . . 404
Line width options: L40, L64, L80, and HONEOM . . . . . . . . . . . 404
NLEOM option . . . . . . . . . . . . . . . . . . . . . . . 404
FORMFEED . . . . . . . . . . . . . . . . . . . . . . . . 405
PRINTERCOMP option . . . . . . . . . . . . . . . . . . . . 406
Non-3270 CICS printers . . . . . . . . . . . . . . . . . . . . . 406
SCS input . . . . . . . . . . . . . . . . . . . . . . . . . 407
Determining the characteristics of a CICS printer . . . . . . . . . . . . 407
BMS page size, 3270 printers . . . . . . . . . . . . . . . . . . 408
Supporting multiple printer types . . . . . . . . . . . . . . . . . 408
Using CICS printers . . . . . . . . . . . . . . . . . . . . . . 409
Printing with a START command . . . . . . . . . . . . . . . . . 409
Printing with transient data . . . . . . . . . . . . . . . . . . . 409
Printing with BMS routing . . . . . . . . . . . . . . . . . . . 411
Using Non-CICS printers . . . . . . . . . . . . . . . . . . . . . 411
Formatting for non-CICS printers . . . . . . . . . . . . . . . . . 411
Non-CICS printers: Delivering the data . . . . . . . . . . . . . . . 411
Programming for non-CICS printers . . . . . . . . . . . . . . . . 412
Notifying the print application . . . . . . . . . . . . . . . . . . 413
Printing display screens . . . . . . . . . . . . . . . . . . . . . 414
CICS print key . . . . . . . . . . . . . . . . . . . . . . . 414
ISSUE PRINT and ISSUE COPY . . . . . . . . . . . . . . . . . 414

Contents xi
Hardware print key . . . . . . . . . . . . . . . . . . . . . . 415
BMS screen copy . . . . . . . . . . . . . . . . . . . . . . 415

Chapter 29. CICS interface to JES . . . . . . . . . . . . . . . . 417

Using the CICS interface to JES . . . . . . . . . . . . . . . . . . 419
Spool interface restrictions . . . . . . . . . . . . . . . . . . . 419
Creating output spool files . . . . . . . . . . . . . . . . . . . . 419
Using the MVS internal reader . . . . . . . . . . . . . . . . . . 420
Reading input spool files . . . . . . . . . . . . . . . . . . . . . 420
JES exits . . . . . . . . . . . . . . . . . . . . . . . . . 421
Identifying spool files . . . . . . . . . . . . . . . . . . . . . . 421
Examples of SPOOL commands . . . . . . . . . . . . . . . . . . 425
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 425
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
ASSEMBLER . . . . . . . . . . . . . . . . . . . . . . . . 427

Chapter 30. CICS intercommunication . . . . . . . . . . . . . . .

429
Design considerations . . . . . . . . . . . . . . . . . . . . . .
429
Programming language . . . . . . . . . . . . . . . . . . . .
430
Transaction routing . . . . . . . . . . . . . . . . . . . . . . .
430
Function shipping . . . . . . . . . . . . . . . . . . . . . . .
430
Distributed program link (DPL) . . . . . . . . . . . . . . . . . . .
431
Using the distributed program link function . . . . . . . . . . . . .
432
Examples of distributed program link . . . . . . . . . . . . . . .
433
Programming considerations for distributed program link . . . . . . . .
438
Asynchronous processing . . . . . . . . . . . . . . . . . . . .
442
Distributed transaction processing (DTP) . . . . . . . . . . . . . . .
442
Common Programming Interface Communications (CPI Communications) 442
External CICS interface (EXCI) . . . . . . . . . . . . . . . . . . 443

Part 6. Basic Mapping Support (BMS) . . . . . . . . . . . . . . . . . . . . 445

Chapter 31. Basic mapping support . . . . . . . . . . . . . . . . 449

BMS support levels . . . . . . . . . . . . . . . . . . . . . . . 449
Minimum BMS . . . . . . . . . . . . . . . . . . . . . . . 449
Standard BMS . . . . . . . . . . . . . . . . . . . . . . . 449
Full BMS . . . . . . . . . . . . . . . . . . . . . . . . . 450
A BMS output example . . . . . . . . . . . . . . . . . . . . . 451

Chapter 32. Creating the map . . . . . . . . . . . . . . . . . . 455

Defining map fields: DFHMDF . . . . . . . . . . . . . . . . . . . 455
Defining the map: DFHMDI . . . . . . . . . . . . . . . . . . . . 457
Defining the map set: DFHMSD . . . . . . . . . . . . . . . . . . 458
Writing BMS macros . . . . . . . . . . . . . . . . . . . . . . 459
Assembling the map . . . . . . . . . . . . . . . . . . . . . . 461
Physical and symbolic map sets . . . . . . . . . . . . . . . . . 461
The SDF II alternative . . . . . . . . . . . . . . . . . . . . . 462
Grouping maps into map sets . . . . . . . . . . . . . . . . . . 462
The Application Data Structure (ADS) . . . . . . . . . . . . . . . 463
Using complex fields . . . . . . . . . . . . . . . . . . . . . . 463
Composite fields: the GRPNAME option . . . . . . . . . . . . . . 464
Repeated fields: the OCCURS option . . . . . . . . . . . . . . . 465
Block data . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Support for non-3270 terminals . . . . . . . . . . . . . . . . . . 466
Output considerations for non-3270 devices . . . . . . . . . . . . . 466

xii CICS TS for z/OS: CICS Application Programming Guide

Differences on input . . . . . . . . . . . . . . . . . . . . . 468
Special options for non-3270 terminals. . . . . . . . . . . . . . . 469
Device-dependent maps . . . . . . . . . . . . . . . . . . . . . 469
Device dependent support: DDS . . . . . . . . . . . . . . . . . 470
Finding out about your terminal . . . . . . . . . . . . . . . . . 472

Chapter 33. Sending BMS mapped output . . . . . . . . . . . . . 473

Acquiring and defining storage for the maps . . . . . . . . . . . . . . 473
BASE and STORAGE options . . . . . . . . . . . . . . . . . . 474
Initializing the output map . . . . . . . . . . . . . . . . . . . . 474
Moving the variable data to the map . . . . . . . . . . . . . . . . 475
Setting the display characteristics . . . . . . . . . . . . . . . . . 475
Changing the attributes . . . . . . . . . . . . . . . . . . . . 476
Attribute value definitions: DFHBMSCA . . . . . . . . . . . . . . 477

Chapter 34. Using the SEND MAP command . . . . . . . . . . . . 479

SEND MAP control options . . . . . . . . . . . . . . . . . . . . 479
Other BMS SEND options: WAIT and LAST . . . . . . . . . . . . . 480
Merging the symbolic and physical maps . . . . . . . . . . . . . . . 480
MAPONLY option . . . . . . . . . . . . . . . . . . . . . . 480
DATAONLY option . . . . . . . . . . . . . . . . . . . . . . 481
The SEND CONTROL command . . . . . . . . . . . . . . . . . 481
Building the output screen . . . . . . . . . . . . . . . . . . . . 481
What you start with . . . . . . . . . . . . . . . . . . . . . . 482
What is sent . . . . . . . . . . . . . . . . . . . . . . . . 482
Where the values come from . . . . . . . . . . . . . . . . . . 482
Outside the map . . . . . . . . . . . . . . . . . . . . . . . 483
Using GDDM and BMS . . . . . . . . . . . . . . . . . . . . 484
Positioning the cursor . . . . . . . . . . . . . . . . . . . . . . 484
Sending invalid data and other errors . . . . . . . . . . . . . . . . 485
Output disposition options: TERMINAL, SET, and PAGING . . . . . . . . 485
Using SET . . . . . . . . . . . . . . . . . . . . . . . . . 486

Chapter 35. Receiving mapped data . . . . . . . . . . . . . . . . 489

An input-output example . . . . . . . . . . . . . . . . . . . . . 489
The symbolic input map . . . . . . . . . . . . . . . . . . . . 491
Programming mapped input . . . . . . . . . . . . . . . . . . . . 492
Using the RECEIVE MAP command . . . . . . . . . . . . . . . . 492
Getting storage for mapped input . . . . . . . . . . . . . . . . . . 493
Formatted screen input . . . . . . . . . . . . . . . . . . . . . 493
Modified data . . . . . . . . . . . . . . . . . . . . . . . . 494
Upper case translation . . . . . . . . . . . . . . . . . . . . 495
Using the attention identifier . . . . . . . . . . . . . . . . . . . 495
Using the HANDLE AID command . . . . . . . . . . . . . . . . 495
Finding the cursor . . . . . . . . . . . . . . . . . . . . . . . 496
Processing the mapped input . . . . . . . . . . . . . . . . . . . 496
Handling input errors . . . . . . . . . . . . . . . . . . . . . . 497
Flagging errors . . . . . . . . . . . . . . . . . . . . . . . 497
Saving the good input . . . . . . . . . . . . . . . . . . . . . 498
Rechecking . . . . . . . . . . . . . . . . . . . . . . . . . 498
Sending mapped output after mapped input . . . . . . . . . . . . . . 499
MAPFAIL and other exceptional conditions . . . . . . . . . . . . . . 500
EOC condition. . . . . . . . . . . . . . . . . . . . . . . . 500
Formatting other input . . . . . . . . . . . . . . . . . . . . . . 501

Chapter 36. BMS logical messages . . . . . . . . . . . . . . . . 503

Contents xiii
Building logical messages . . . . . . . . . . . . . . . . . . . . 503
The SEND PAGE command . . . . . . . . . . . . . . . . . . . 504
RETAIN and RELEASE . . . . . . . . . . . . . . . . . . . . . 504
The AUTOPAGE option . . . . . . . . . . . . . . . . . . . . . 506
Terminal operator paging: the CSPG transaction . . . . . . . . . . . . 506
Logical message recovery . . . . . . . . . . . . . . . . . . . . 507

Chapter 37. Cumulative output — the ACCUM option . . . . . . . . . 509

Floating maps: how BMS places maps using ACCUM . . . . . . . . . . 509
Page breaks: BMS overflow processing . . . . . . . . . . . . . . . 510
Map placement rules . . . . . . . . . . . . . . . . . . . . . . 511
ASSIGN options for cumulative processing . . . . . . . . . . . . . 513
Input from a composite screen . . . . . . . . . . . . . . . . . . . 513
Performance considerations. . . . . . . . . . . . . . . . . . . . 513
Minimizing path length . . . . . . . . . . . . . . . . . . . . . 513
Reducing message lengths . . . . . . . . . . . . . . . . . . . 514

Chapter 38. Text output . . . . . . . . . . . . . . . . . . . . . 517

The SEND TEXT command . . . . . . . . . . . . . . . . . . . . 517
Text logical messages . . . . . . . . . . . . . . . . . . . . . 517
Text pages . . . . . . . . . . . . . . . . . . . . . . . . . . 518
Text lines . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Header and trailer format. . . . . . . . . . . . . . . . . . . . . 520
SEND TEXT MAPPED and SEND TEXT NOEDIT . . . . . . . . . . . 521

Chapter 39. Message routing . . . . . . . . . . . . . . . . . . 523

Message destinations . . . . . . . . . . . . . . . . . . . . . . 523
Eligible terminals . . . . . . . . . . . . . . . . . . . . . . . 524
Destinations specified with OPCLASS only . . . . . . . . . . . . . 524
OPCLASS and LIST omitted . . . . . . . . . . . . . . . . . . 525
Route list provided . . . . . . . . . . . . . . . . . . . . . . 525
Route list format . . . . . . . . . . . . . . . . . . . . . . . . 526
Message delivery . . . . . . . . . . . . . . . . . . . . . . . 527
Undeliverable messages . . . . . . . . . . . . . . . . . . . . 528
Recoverable messages . . . . . . . . . . . . . . . . . . . . . 528
Message identification . . . . . . . . . . . . . . . . . . . . . 529
Programming considerations with routing . . . . . . . . . . . . . . . 530
Routing and page overflow . . . . . . . . . . . . . . . . . . . 530
Routing with SET . . . . . . . . . . . . . . . . . . . . . . 531
Interleaving a conversation with message routing . . . . . . . . . . . 531

Chapter 40. The MAPPINGDEV facility . . . . . . . . . . . . . . . 533

SEND MAP with the MAPPINGDEV option . . . . . . . . . . . . . . 533
RECEIVE MAP with the MAPPINGDEV option . . . . . . . . . . . . . 534
Sample assembler MAPPINGDEV application . . . . . . . . . . . . . 535

Chapter 41. Partition support . . . . . . . . . . . . . . . . . . 537

Uses for partitioned screens . . . . . . . . . . . . . . . . . . . 538
Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Data entry . . . . . . . . . . . . . . . . . . . . . . . . . 538
Lookaside . . . . . . . . . . . . . . . . . . . . . . . . . 538
Data comparison . . . . . . . . . . . . . . . . . . . . . . . 539
Error messages . . . . . . . . . . . . . . . . . . . . . . . 539
Partition definition . . . . . . . . . . . . . . . . . . . . . . . 539
3290 character size . . . . . . . . . . . . . . . . . . . . . . 540
Establishing partitioning . . . . . . . . . . . . . . . . . . . . . 540

xiv CICS TS for z/OS: CICS Application Programming Guide

Partition options for BMS SEND commands . . . . . . . . . . . . . . 541
Determining the active partition . . . . . . . . . . . . . . . . . 541
Partition options for BMS RECEIVE commands . . . . . . . . . . . . 542
ASSIGN options for partitions . . . . . . . . . . . . . . . . . . 542
Partitions and logical messages . . . . . . . . . . . . . . . . . . 542
Partitions and routing . . . . . . . . . . . . . . . . . . . . . 543
Attention identifiers and exception conditions . . . . . . . . . . . . . 543
Terminal sharing . . . . . . . . . . . . . . . . . . . . . . . . 544

Chapter 42. Support for special hardware . . . . . . . . . . . . . 545

Logical device components . . . . . . . . . . . . . . . . . . . . 545
Defining logical device components . . . . . . . . . . . . . . . . 545
Sending data to a logical device component . . . . . . . . . . . . . 546
LDCs and logical messages . . . . . . . . . . . . . . . . . . 546
LDCs and routing . . . . . . . . . . . . . . . . . . . . . . 546
10/63 magnetic slot reader . . . . . . . . . . . . . . . . . . . . 547
Field selection features . . . . . . . . . . . . . . . . . . . . . 547
Trigger field support . . . . . . . . . . . . . . . . . . . . . 547
Cursor and pen-detectable fields . . . . . . . . . . . . . . . . . . 548
Selection fields . . . . . . . . . . . . . . . . . . . . . . . 549
Attention fields . . . . . . . . . . . . . . . . . . . . . . . 549
BMS input from detectable fields . . . . . . . . . . . . . . . . . 549
Outboard formatting . . . . . . . . . . . . . . . . . . . . . . 550

Part 7. CICS management functions . . . . . . . . . . . . . . . . . . . . . 551

Chapter 43. Interval control . . . . . . . . . . . . . . . . . . . 553

Expiration times . . . . . . . . . . . . . . . . . . . . . . . . 554
Request identifiers . . . . . . . . . . . . . . . . . . . . . . . 555

Chapter 44. Task control . . . . . . . . . . . . . . . . . . . . 557

Controlling sequence of access to resources . . . . . . . . . . . . . 558

Chapter 45. Program control . . . . . . . . . . . . . . . . . . . 561

Program linking . . . . . . . . . . . . . . . . . . . . . . . . 562
Application program logical levels . . . . . . . . . . . . . . . . 562
Link to another program expecting return . . . . . . . . . . . . . . 562
Passing data to other programs . . . . . . . . . . . . . . . . . . 563
COMMAREA . . . . . . . . . . . . . . . . . . . . . . . . 563
| Channels . . . . . . . . . . . . . . . . . . . . . . . . . 565
INPUTMSG. . . . . . . . . . . . . . . . . . . . . . . . . 565
Using mixed addressing modes . . . . . . . . . . . . . . . . . . 567
Using LINK to pass data . . . . . . . . . . . . . . . . . . . . . 568
Using RETURN to pass data . . . . . . . . . . . . . . . . . . . 571

Chapter 46. Storage control . . . . . . . . . . . . . . . . . . . 575

Overview of CICS storage protection and transaction isolation . . . . . . . 576
Storage protection . . . . . . . . . . . . . . . . . . . . . . 576
Transaction isolation . . . . . . . . . . . . . . . . . . . . . 577
Defining the storage key for applications . . . . . . . . . . . . . . . 578
System-wide storage areas . . . . . . . . . . . . . . . . . . . 579
Task lifetime storage . . . . . . . . . . . . . . . . . . . . . 579
Program working storage specifically for exit and PLT programs . . . . . 579
Passing data by a COMMAREA . . . . . . . . . . . . . . . . . 579
The GETMAIN command . . . . . . . . . . . . . . . . . . . 580
Selecting the execution and storage key . . . . . . . . . . . . . . . 581

Contents xv
User-key applications . . . . . . . . . . . . . . . . . . . . . 582
CICS-key applications . . . . . . . . . . . . . . . . . . . . . 582
Using transaction isolation . . . . . . . . . . . . . . . . . . . . 585
MVS subspaces . . . . . . . . . . . . . . . . . . . . . . . . 587
Subspaces and basespaces for transactions . . . . . . . . . . . . 587
The common subspace and shared storage . . . . . . . . . . . . . 588

Chapter 47. Transient data control . . . . . . . . . . . . . . . . 591

Intrapartition transient data queues . . . . . . . . . . . . . . . . . 591
Extrapartition queues . . . . . . . . . . . . . . . . . . . . . . 592
Indirect queues . . . . . . . . . . . . . . . . . . . . . . . . 593
Automatic transaction initiation (ATI) . . . . . . . . . . . . . . . . 593

Chapter 48. Temporary storage control . . . . . . . . . . . . . . 595

Temporary storage queues . . . . . . . . . . . . . . . . . . . . 595
Typical uses of temporary storage control . . . . . . . . . . . . . . 596

Part 8. Testing and debugging applications . . . . . . . . . . . . . . . . . 599

Chapter 49. Testing applications . . . . . . . . . . . . . . . . . 601

Preparing the application for testing . . . . . . . . . . . . . . . . . 602
Preparing the system for testing . . . . . . . . . . . . . . . . . . 602

Chapter 50. Execution diagnostic facility (EDF) . . . . . . . . . . . 605

Restrictions when using EDF . . . . . . . . . . . . . . . . . . . 606
# OPEN TCBs and EDF . . . . . . . . . . . . . . . . . . . . . 607
Parameter list stacking . . . . . . . . . . . . . . . . . . . . 607
Security considerations . . . . . . . . . . . . . . . . . . . . 607
What does EDF display? . . . . . . . . . . . . . . . . . . . . . 609
The header . . . . . . . . . . . . . . . . . . . . . . . . . 609
The body . . . . . . . . . . . . . . . . . . . . . . . . . 610
Using EDF . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Interrupting program execution . . . . . . . . . . . . . . . . . 617
Using EDF in single-screen mode . . . . . . . . . . . . . . . . 618
Using EDF in dual-screen mode . . . . . . . . . . . . . . . . . 620
EDF and remote transactions . . . . . . . . . . . . . . . . . . 620
EDF and non-terminal transactions . . . . . . . . . . . . . . . . 620
EDF and DTP programs . . . . . . . . . . . . . . . . . . . . 621
Stopping EDF . . . . . . . . . . . . . . . . . . . . . . . . 622
Overtyping to make changes . . . . . . . . . . . . . . . . . . . 622
EDF responses . . . . . . . . . . . . . . . . . . . . . . . 624
Using EDF menu functions . . . . . . . . . . . . . . . . . . . . 624

Chapter 51. Temporary storage browse (CEBR) . . . . . . . . . . . 631

Using the CEBR transaction . . . . . . . . . . . . . . . . . . . 631
What does the CEBR transaction display? . . . . . . . . . . . . . . 633
The header . . . . . . . . . . . . . . . . . . . . . . . . . 633
The command area . . . . . . . . . . . . . . . . . . . . . . 633
The body . . . . . . . . . . . . . . . . . . . . . . . . . 633
The message line . . . . . . . . . . . . . . . . . . . . . . 633
Using the CEBR function keys . . . . . . . . . . . . . . . . . . . 634
Using the CEBR commands . . . . . . . . . . . . . . . . . . . 635
Using the CEBR transaction with transient data . . . . . . . . . . . . 637

Chapter 52. Command-level interpreter (CECI) . . . . . . . . . . . . 639

What does CECI display? . . . . . . . . . . . . . . . . . . . . 639

xvi CICS TS for z/OS: CICS Application Programming Guide

The command line . . . . . . . . . . . . . . . . . . . . . . 639
The status line . . . . . . . . . . . . . . . . . . . . . . . 640
The body . . . . . . . . . . . . . . . . . . . . . . . . . 644
The message line . . . . . . . . . . . . . . . . . . . . . . 644
CECI options on function keys . . . . . . . . . . . . . . . . . . 644
Using CECI. . . . . . . . . . . . . . . . . . . . . . . . . . 646
Making changes . . . . . . . . . . . . . . . . . . . . . . . 647
Using the CECI function keys . . . . . . . . . . . . . . . . . . . 648
Expanded area . . . . . . . . . . . . . . . . . . . . . . . 648
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . 648
The EXEC interface block (EIB) . . . . . . . . . . . . . . . . . 650
Error messages display . . . . . . . . . . . . . . . . . . . . 650
Saving commands . . . . . . . . . . . . . . . . . . . . . . . 651
How CECI runs . . . . . . . . . . . . . . . . . . . . . . . . 652
CECI sessions . . . . . . . . . . . . . . . . . . . . . . . 652
Abends . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Exception conditions . . . . . . . . . . . . . . . . . . . . . 652
Program control commands . . . . . . . . . . . . . . . . . . . 653
Terminal sharing . . . . . . . . . . . . . . . . . . . . . . . 653

Chapter 53. Using debuggers with CICS applications . . . . . . . . . 655

Debugging profiles . . . . . . . . . . . . . . . . . . . . . . . 656
Using debugging profiles to select programs for debugging . . . . . . . . 657
Using generic parameters in debugging profiles . . . . . . . . . . . . 659

Chapter 54. Debugging CICS applications from a workstation. . . . . . 661

Preparing to debug applications from a workstation . . . . . . . . . . . 661

Chapter 55. Using Debug Tool with CICS applications . . . . . . . . . 663

About Debug Tool . . . . . . . . . . . . . . . . . . . . . . . 663
Preparing to debug applications with Debug Tool . . . . . . . . . . . . 663

Part 9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

Appendix A. Using the phonetic conversion subroutine DFHPHN . . . . 667

Appendix B. Migration for OS/VS COBOL programs . . . . . . . . . 669

Conversion to Enterprise COBOL . . . . . . . . . . . . . . . . . 669
Based addressing . . . . . . . . . . . . . . . . . . . . . . 669
Artificial assignments . . . . . . . . . . . . . . . . . . . . . 671

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 673
The CICS Transaction Server for z/OS library . . . . . . . . . . . . . 673
The entitlement set . . . . . . . . . . . . . . . . . . . . . . 673
PDF-only books . . . . . . . . . . . . . . . . . . . . . . . 673
Other CICS books . . . . . . . . . . . . . . . . . . . . . . . 675
Books from related libraries . . . . . . . . . . . . . . . . . . . . 675
DL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Screen definition facility II (SDF II) . . . . . . . . . . . . . . . . 675
Common programming interface . . . . . . . . . . . . . . . . . 676
Common user access . . . . . . . . . . . . . . . . . . . . . 676
Programming languages . . . . . . . . . . . . . . . . . . . . 676
Teleprocessing Network Simulator (TPNS) . . . . . . . . . . . . . 676
Language Environment: . . . . . . . . . . . . . . . . . . . . 676
Miscellaneous books . . . . . . . . . . . . . . . . . . . . . 677

Contents xvii
Determining if a publication is current . . . . . . . . . . . . . . . . 677

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . 679

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 700

Sending your comments to IBM . . . . . . . . . . . . . . . . . 701

xviii CICS TS for z/OS: CICS Application Programming Guide

Preface
What this book is about
This book gives guidance about the development of procedural application
programs that use the CICS® EXEC application programming interface to access
CICS services and resources; it complements the reference information in the
CICS Application Programming Reference manual. For guidance information on
debugging such CICS applications, see the CICS Problem Determination Guide.
For guidance on developing application programs using the Java™ language, see
Java Applications in CICS, and for guidance on using the CICS OO classes, see
CICS C++ OO Class Libraries.

Who should read this book

This book is mainly for experienced application programmers. Those who are
relatively new to CICS should be able to understand it. If you are a system
programmer or system analyst, you should still find it useful.

What you need to know to understand this book

You must be able to program in COBOL, C, C++, PL/I, or assembler language, and
have a basic knowledge of CICS application programming, at the Designing and
Programming CICS Applications level.

How to use this book

Read the parts covering what you need to know. (Each part has a full table of
contents to help you find what you want.) The book is a guide, not a reference
manual. On your first reading, it probably helps to work through any one part of it
more or less from start to finish.

Notes on terminology
API refers to the CICS command-level application programming interface unless
otherwise stated.
ASM is sometimes used as the abbreviation for assembler language.
™
MVS refers to the operating system, which can be either an element of z/OS® ,
OS/390®, or MVS/Enterprise System Architecture System Product
(MVS/ESA™ SP™).
VTAM®
refers to ACF/VTAM.

In the sample programs described in this book, the dollar symbol ($) is used as a
national currency symbol and is assumed to be assigned the EBCDIC code point
X’5B’. In some countries a different currency symbol, for example the pound symbol
(£), or the yen symbol (¥), is assigned the same EBCDIC code point. In these
countries, the appropriate currency symbol should be used instead of the dollar
symbol.

What is not covered in this book

Guidance for usage of the CICS Front End Programming Interface is not discussed
in this book. See the CICS Front End Programming Interface User’s Guide for
background information about FEPI design considerations and programming
information about its API.

© Copyright IBM Corp. 1989, 2005 xix

Guidance for usage of the EXEC CICS WEB commands is not discussed in this
book. See the CICS Internet Guide for this information.

Guidance for the use of object oriented programming languages and techniques is
not included in this book. For guidance on developing application programs using
the Java language, see Java Applications in CICS, and for guidance on using the
CICS OO classes, see CICS C++ OO Class Libraries.

xx CICS TS for z/OS: CICS Application Programming Guide

Summary of changes
This book is based on the CICS Application Programming Guide for CICS
Transaction Server for z/OS, Version 2 Release 3. Changes from that edition are
marked by vertical bars in the left margin.

Changes for CICS Transaction Server for z/OS, Version 3 Release 1

The more significant changes for this edition are:
v Technical changes:
– Enhanced inter-program data transfer: channels as modern-day COMMAREAs
is a new chapter that describes how programs can use “channels” and
“containers” to exchange data.
Structural changes :
v The chapter “Writing Web-aware application programs” has been moved to the
CICS Internet Guide.

Changes for CICS Transaction Server for z/OS, Version 2 Release 3

The more significant changes for this edition are:
v Technical changes:
– Chapter 53, “Using debuggers with CICS applications,” on page 655,
Chapter 54, “Debugging CICS applications from a workstation,” on page 661
and Chapter 55, “Using Debug Tool with CICS applications,” on page 663
have been added.
There are no significant structural changes.

Changes for CICS Transaction Server for z/OS, Version 2 Release 2

The more significant changes for this edition are:
v Technical changes:
– The use of Language Environment® is assumed in all programming guidance
information.
v Structural changes :
– Information in “Creating a document” on page 321, describing the use of
document templates, has been expanded to incorporate information that was
previously in the CICS Internet Guide

Changes for CICS Transaction Server for z/OS, Version 2 Release 1

The following new function has been added:
v Support for an integrated translator. Some compilers can now interpret CICS
commands and translate them without the need for a separate translation step,
see “The integrated CICS translator” on page 67.

Changes have been made to titles and headings throughout the book, to make
them more meaningful, particularly when the book is explored online in the CICS
Information Center. Links and cross references have been improved.
v Part 1, Writing CICS applications, has been expanded to include an introduction
to basic CICS concepts and an application development roadmap. See “CICS
programming roadmap” on page 7.
© Copyright IBM Corp. 1989, 2005 xxi
v Part 2 in the previous edition, Object Oriented programming in CICS, has been
removed. For guidance on developing application programs using the Java
language, see the Java Applications in CICS component of the CICS Information
Center, and for guidance on using the CICS OO classes, see CICS C++ OO
Class Libraries.
v A new part 2 has been introduced, to bring together all information needed to
translate and compile CICS applications. Chapters describing the installation of
CICS programs and maps have been moved here from the CICS System
Definition Guide.
v Part 3, Application design, now separates general application design concepts,
see Chapter 11, “Application design,” on page 139, from application design for
performance, see Chapter 12, “Design for performance,” on page 165.
v BMS has been restructured into separate chapters, to form a new Part 6.
v The previous Appendix 1, mapping EXEC CICS commands to obsolete CICS
macros has been removed.

Changes for CICS Transaction Server for OS/390, Version 1 Release 3

The following significant changes were made for this edition.
v The addition of the JCICS Java classes to access CICS services from Java
application programs. Now moved to the Java Applications in CICS component of
the CICS Information Center
v Support for running CICS Java programs using the VisualAge® for Java,
Enterprise Edition for OS/390. Now moved to the Java Applications in CICS
component of the CICS Information Center.
v Support for running CICS Java programs using the CICS Java Virtual Machine
(JVM). Now moved to the Java Applications in CICS component of the CICS
Information Center.
v The addition of sysplex-wide ENQ and DEQ. See “Using ENQ and DEQ
commands with ENQMODEL resource definitions” on page 226.
v The addition of support for coupling facility data tables (CFDT). See “Coupling
facility data tables” on page 288.
v Support for named counter servers. See Chapter 25, “Named counter servers,”
on page 337.
v Support for documents, and the EXEC CICS DOCUMENT commands. See
Chapter 24, “CICS documents,” on page 321.
v The programming considerations section has been reorganized into separate
chapters for each supported language, including new chapters for OO and Java
support in CICS.

xxii CICS TS for z/OS: CICS Application Programming Guide

Part 1. Writing CICS Applications
Chapter 1. What is a CICS application? . . . . . . . . . . . . . . . 3
CICS programs, transactions and tasks . . . . . . . . . . . . . . . . 3

Chapter 2. CICS programming . . . . . . . . . . . . . . . . . . . 5

Chapter 3. Language Environment . . . . . . . . . . . . . . . . . 9

Chapter 4. Programming in COBOL . . . . . . . . . . . . . . . . 21

COBOL programming considerations . . . . . . . . . . . . . . . . . 21
Programming restrictions . . . . . . . . . . . . . . . . . . . . 21
Using the DL/I CALL interface . . . . . . . . . . . . . . . . . . 24
Language Environment considerations for COBOL applications . . . . . . . 25
CBLPSHPOP option . . . . . . . . . . . . . . . . . . . . . . 26
Using based addressing with COBOL . . . . . . . . . . . . . . . . 26
Using WITH DEBUGGING MODE . . . . . . . . . . . . . . . . . 27
Calling subprograms from COBOL . . . . . . . . . . . . . . . . . . 27
Rules for calling subprograms . . . . . . . . . . . . . . . . . . 29
Translation . . . . . . . . . . . . . . . . . . . . . . . . 29
Compilation . . . . . . . . . . . . . . . . . . . . . . . . 29
Link-editing . . . . . . . . . . . . . . . . . . . . . . . . 29
CICS CSD entries without program autoinstall . . . . . . . . . . . 29
Return from subprogram . . . . . . . . . . . . . . . . . . . 30
Language of subprogram . . . . . . . . . . . . . . . . . . . 30
Contents of subprogram . . . . . . . . . . . . . . . . . . . 30
Passing parameters to subprogram . . . . . . . . . . . . . . . 30
Storage . . . . . . . . . . . . . . . . . . . . . . . . . 30
CICS condition, AID and abend handling . . . . . . . . . . . . . 31
Location of subprogram . . . . . . . . . . . . . . . . . . . . 31
Flow of control between programs and subprograms . . . . . . . . . . 31
Using the COBOL2 and COBOL3 translator options . . . . . . . . . . . 33
Literals intervening in blank lines . . . . . . . . . . . . . . . . . 33
Translator action . . . . . . . . . . . . . . . . . . . . . . 34
Lower case characters . . . . . . . . . . . . . . . . . . . . . 34
Translator action . . . . . . . . . . . . . . . . . . . . . . 34
Sequence numbers containing any character . . . . . . . . . . . . . 34

© Copyright IBM Corp. 1989, 2005 1

REPLACE statement . . . . . . . . . . . . . . . . . . . . . . 35
Translator action . . . . . . . . . . . . . . . . . . . . . . 35
Batch compilation . . . . . . . . . . . . . . . . . . . . . . . 35
Translator action . . . . . . . . . . . . . . . . . . . . . . 35
Compiler and linkage editor . . . . . . . . . . . . . . . . . . 35
Nested programs . . . . . . . . . . . . . . . . . . . . . . . 37
Integrated CICS translator . . . . . . . . . . . . . . . . . . . 37
Translator action . . . . . . . . . . . . . . . . . . . . . . 37
Reference modification . . . . . . . . . . . . . . . . . . . . . 41
Translator action . . . . . . . . . . . . . . . . . . . . . . 41
Global variables . . . . . . . . . . . . . . . . . . . . . . . 41
Translator action . . . . . . . . . . . . . . . . . . . . . . 41
Comma and semicolon as delimiters . . . . . . . . . . . . . . . . 41
Translator action . . . . . . . . . . . . . . . . . . . . . . 41
Symbolic character definition . . . . . . . . . . . . . . . . . . . 41
Translator action . . . . . . . . . . . . . . . . . . . . . . 42
Using the OO COBOL translator option . . . . . . . . . . . . . . . . 42
Translator action . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 5. Programming in C and C++ . . . . . . . . . . . . . . . 43

C and C++ programming considerations . . . . . . . . . . . . . . . 43
| XPLink considerations for C and C++ programming . . . . . . . . . . 47
| XPLink, and the X8 and X9 TCBs . . . . . . . . . . . . . . . . 47
| Writing C and C++ programs, which are to be compiled with the XPLINK
| option, for the CICS environment . . . . . . . . . . . . . . . 48
| Passing control between XPLink and non-XPLink objects . . . . . . . 48
| Changing CICS definitions to obtain CICS support for objects compiled
| with the XPLINK option . . . . . . . . . . . . . . . . . . . 48
| Global User exits and XPLink . . . . . . . . . . . . . . . . . 48
Passing arguments in C or C++ . . . . . . . . . . . . . . . . . . . 49
Accessing the EIB . . . . . . . . . . . . . . . . . . . . . . . . 50
Naming EIB fields . . . . . . . . . . . . . . . . . . . . . . . 50
Data types in EIB fields . . . . . . . . . . . . . . . . . . . . 50
Using Locale support . . . . . . . . . . . . . . . . . . . . . . 51
Programming in C++ . . . . . . . . . . . . . . . . . . . . . . . 51
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 6. Programming in PL/I . . . . . . . . . . . . . . . . . . 53

PL/I programming restrictions . . . . . . . . . . . . . . . . . . . 53
Language Environment considerations for PL/I applications . . . . . . . . 54

Chapter 7. Programming in Assembler . . . . . . . . . . . . . . . 57

Language Environment considerations for Assembler applications . . . . . . 58
Calling Assembler programs . . . . . . . . . . . . . . . . . . . . 60

2 CICS TS for z/OS: CICS Application Programming Guide

Chapter 1. What is a CICS application?
An application is a collection of related programs that together perform a business
operation, such as processing a product order or preparing a company payroll.
CICS applications execute under CICS control, using CICS services and interfaces
to access programs and files.

CICS is a transaction processing subsystem. That means that it provides services

for you to run applications online, by request, at the same time as many other users
are submitting requests to run the same applications, using the same files and
programs. CICS manages the sharing of resources; integrity of data and
prioritization of execution, with fast response.

CICS applications are traditionally run by submitting a transaction request.

Execution of the transaction consists of running one or more application programs
that implement the required function. In CICS documentation you may find CICS
application programs sometimes simply called programs, and sometimes the term
transaction is used to imply the processing done by the application programs.

CICS applications can also take the form of Enterprise JavaBeans™. You can find
out more about this form of programming in Java Applications in CICS in the CICS
Information Center.

You should note that the term transaction is now used extensively in the IT
industry to describe a unit of recovery or what CICS calls a unit of work. This is
typically a complete operation that is recoverable; it can be committed or backed
out as an entirety as a result of programmed command or system failure. In many
cases the scope of a CICS transaction is also a single unit of work, but you should
be aware of the difference in meaning when reading CICS documentation.

CICS programs, transactions and tasks

To develop and run CICS applications, you need to understand the relationship
between CICS programs, transactions and tasks. These terms are used throughout
CICS documentation and appear in many commands.:
Transaction
A transaction is a piece of processing initiated by a single request. This is
usually from an end-user at a terminal, but may also be made from a Web
page, from a remote workstation program, from an application in another
CICS system or triggered automatically at a predefined time. TheCICS
Internet Guide and the CICS External Interfaces Guide describe different
ways of running CICS transactions.
A single transaction consists of one or more application programs that,
when run, carry out the processing needed.
However, the term transaction is used in CICS to mean both a single
event and all other transactions of the same type. You describe each
transaction type to CICS with a TRANSACTION resource definition. This
definition gives the transaction type a name ( the transaction identifier, or
TRANSID) and tells CICS several things about the work to be done; such
as what program to invoke first, and what kind of authentication is required
throughout the execution of the transaction.

© Copyright IBM Corp. 1989, 2005 3

You run a transaction by submitting its TRANSID to CICS. CICS uses the
information recorded in the TRANSACTION definition to establish the
correct execution environment, and starts the first program.
The term transaction is now used extensively in the IT industry to describe
a unit of recovery or what CICS calls a unit of work. This is typically a
complete operation that is recoverable; it can be committed or backed out
as an entirety as a result of programmed command or system failure. In
many cases the scope of a CICS transaction is also a single unit of work,
but you should be aware of the difference in meaning when reading
non-CICS documentation.
Task You will also see the word task used extensively in CICS documentation.
This word also has a specific meaning in CICS. When CICS receives a
request to run a transaction, it starts a new task that is associated with this
one instance of the execution of the transaction. type. That is, one
execution of a transaction, with a particular set of data, usually on behalf of
a particular user at a particular terminal. You can also consider it as
analogous to a thread.. When the transaction completes, the task is
terminated.

4 CICS TS for z/OS: CICS Application Programming Guide

Chapter 2. CICS programming
You write a CICS program in much the same way as you write any other program.
You can use COBOL, C, C++, Java, PL/I, or assembler language to write CICS
application programs. Most of the processing logic is expressed in standard
language statements, but you use CICS commands, or the Java and C++ class
libraries to request CICS services.

This book describes the use of the CICS command level programming interface,
’EXEC CICS’, that can be used in COBOL, C, C++, PL/I or assembler programs.
These commands are defined in detail in the CICS Application Programming
Reference.

Programming in Java with the JCICS class library is described in the Java
Applications in CICS component of the CICS Information Center.

Programming in C++ with the CICS C++ classes is described in the CICS C++ OO
Class Libraries documentation.

For information about writing Web applications to process HTTP/1.0 requests and
responses, see the CICS Internet Guide.

For further guidance on language use with CICS, see Chapter 4, “Programming in
COBOL,” on page 21, Chapter 5, “Programming in C and C++,” on page 43,
Chapter 6, “Programming in PL/I,” on page 53..

CICS allows you to use SQL statements, DLI requests, CPI statements, and the
CICS Front End Programming Interface (FEPI) commands in your program as well
as CICS commands. You need to consult additional manuals for information:
v SQL Reference manual and the Application Programming and SQL Guide (for
SQL)
v Application Programming:EXEC DLI Commands manual and the Application
Programming: DL/I Calls manual (for DL/I)
v IBM SAA: CPI Reference manual and the SAA Common Programming Interface
for Resource Recovery Reference manual (for CPI)
v CICS Front End Programming Interface User’s Guide (for programming
information about FEPI commands)

CICS programming commands

The general format of a CICS command is EXECUTE CICS (or EXEC CICS)
followed by the name of the required command and possibly one or more options.

You can write many application programs using the CICS command-level interface
without any knowledge of, or reference to, the fields in the CICS control blocks and
storage areas. However, you might need to get information that is valid outside the
local environment of your application program.

You can use the ADDRESS and ASSIGN commands to access such information.
For programming information about these commands, see the CICS Application
Programming Reference manual.

When using the ADDRESS and ASSIGN commands, various fields can be read but
should not be set or used in any other way. This means that you should not use
© Copyright IBM Corp. 1989, 2005 5
any of the CICS fields as arguments in CICS commands, because these fields may
be altered by the EXEC interface modules.

System programming commands

The INQUIRE, SET, and PERFORM commands allow application programs to
access information about CICS resources. The application program can retrieve and
modify information for CICS data sets, terminals, system entries, mode names,
system attributes, programs, and transactions. These commands plus the spool
commands of the CICS interface to JES, are primarily for the use of the system
programmer. For programming information, see the CICS System Programming
Reference manual.

EXEC interface block (EIB)

In addition to the usual CICS control blocks, each task in a command-level
environment has a control block known as the EXEC interface block (EIB)
associated with it. An application program can access all of the fields in the EIB by
name. The EIB contains information that is useful during the execution of an
application program, such as the transaction identifier, the time and date (initially
when the task is started, and subsequently, if updated by the application program
using ASKTIME), and the cursor position on a display device. The EIB also contains
information that is helpful when a dump is used to debug a program. For
programming information about EIB fields, see the CICS Application Programming
Reference manual.

Translation
Most compilers (and assemblers) cannot process CICS commands directly. This
means that an additional step is needed to convert your program into executable
code. This step is called translation, and consists of converting CICS commands
into the language in which the rest of the program is coded, so that the compiler (or
assembler) can understand them.

Some compilers now contain integrated translators that can interpret CICS
commands and convert them automatically to calls to CICS service routines. If you
use one of these compilers, you do not need to perform the translation tasks
described in “The translation process” on page 69.

CICS provides a translator program for each of the languages in which you may
write, to handle both EXEC CICS and EXEC DLI statements.

Translator Options
You can specify a number of options for the translation process, and you may need
to do this for certain types of programs. If you are using EXEC DLI, for example,
you need to tell the translator this fact. “Using a CICS translator” on page 73
explains how to specify options, and “Defining translator options” on page 74
defines the options available.

6 CICS TS for z/OS: CICS Application Programming Guide

Testing for CICS
Your program can determine whether it is running in CICS in two different ways:
iscics
If you are adapting an existing C language program or writing a new program
that is designed to run outside CICS as well as under CICS, the C language
iscics() function may prove useful. It returns a non-zero value if your program is
currently running under CICS, or zero otherwise. This function is an extension
to the C library.
DFH3QSS
Your program can call the DFH3QSS program to query the the CICS
environment and API capability. On return, register 15 addresses a result
structure that consists of a half-word length (that includes itself) followed by a
reserved half-word (currently zero) followed by a bit string:
Bit 0 When set to 1, this means that the caller is running in a CICS
environment (on a CICS-managed TCB or one of its
descendants).
Bit 1 When set to 1, this means that the CICS API is available to the
caller (in the current PSW key, ASC-mode, AMODE and
cross-memory environment).

The output structure remains accessible as long as the TCB under which the
request was issued has not terminated and DFH3QSS itself is still present in virtual
storage. Any change of execution state ( such as PSW key, ASC-mode, AMODE or
cross-memory environment ) might affect the availability of the CICS API. Registers
are preserved.

CICS programming roadmap

Follow these steps to develop a CICS application that uses the EXEC CICS
command level programming interface:
1. Design your application, identifying the CICS resources and services you will
use. See Chapter 11, “Application design,” on page 139 and Chapter 12,
“Design for performance,” on page 165 for guidance on designing CICS
applications.
2. Write your program in the language of your choice, including EXEC CICS
commands to request CICS services. See the CICS Application Programming
Reference for a list of CICS commands.
3. If you are using a compiler that incorporates “The integrated CICS translator” on
page 67, you will only need to compile your program, and then install it in CICS,
using the process described in “Program installation roadmap” on page 99.
Otherwise, you will need to define translator options for your program, using the
process described in “Using a CICS translator” on page 73, and then translate
and compile your program, and install it in CICS, using the process described in
“Program installation roadmap” on page 99.
4. Define your program and related transaction to CICS with PROGRAM resource
definitions and TRANSACTION resource definitions as described in the CICS
Resource Definition Guide .
5. Define any CICS resources that your program uses, such as files, queues or
terminals.
6. Make the resources known to CICS using the CEDA INSTALL command
described in the CICS Resource Definition Guide.

Chapter 2. CICS programming 7

7. Run your program, by entering the transaction identifier at a CICS terminal, or
by using any of the methods described in the CICS External Interfaces Guide
and the CICS Internet Guide.

8 CICS TS for z/OS: CICS Application Programming Guide

Chapter 3. Language Environment
Language Environment, supplied as an element of z/OS, is designed to provide a
common set of runtime libraries to replace the native runtime libraries that were
provided with older compilers such as VS COBOL II, OS PL/I and C/370™.

Before the introduction of Language Environment, each of the high-level languages

(HLLs) had to provide a separate runtime environment. With Language
Environment, you use one runtime environment for your applications, regardless of
the programming language or system resource needs, because most system
dependencies have been removed. This common environment offers two significant
advantages:
1. You can mix all the languages supported by CICS in a single program.
2. The same Language Environment callable services are available to all
programs. This means, for example, that:
v A linked-list created with storage obtained using Language Environment
callable services in a PL/I program can be processed later and the storage
freed using the callable services from a COBOL routine.
v The currency symbol to be used on a series of reports can be set in an
assembler routine, even though the reports themselves are produced by
COBOL programs.
v System messages from programs written in different languages are all sent to
the same output destination.
See the z/OS: Language Environment Concepts Guide for more information.

Because of these advantages, high-level language support under CICS depends

upon Language Environment.

The CICS programming guidance documentation requires that your CICS system is
using the services of Language Environment, which provides a common runtime
environment for IBM® implementations of assembler and those high-level languages
(HLLs) supported by CICS, namely COBOL, PL/I, C, and C++.

Language libraries, other than the Language Environment libraries, should not be
present in your CICS startup JCL. If, perhaps for commonality with other CICS
systems, the JCL for your CICS startup job includes other language libraries, the
Language Environment libraries must be above all the other language libraries in
the JCL concatenations of the CICS startup job for both STEPLIB and DFHRPL.
This ensures that the programs are processed by Language Environment.

| CICS supports application programs compiled using compilers that are supported
| by Language Environment. This includes Language Environment-conforming
| application programs compiled by fully-conforming compilers, and non-Language
| Environment-conforming application programs that can execute under Language
| Environment in compatibility mode. The exception to this rule is for application
| programs compiled with the following non-Language Environment-conforming
| compilers, which are supported by Language Environment but not by CICS:
| v OS PL/1 Versions 1 and 2
| v C/370 V1 and V2
| For a list of compilers that are supported in this release of CICS Transaction Server
| for z/OS, see the CICS Release Guide.

© Copyright IBM Corp. 1989, 2005 9

| CICS Transaction Server for z/OS Version 3 allows you to produce Language
| Environment-conforming assembler MAIN programs.

When modifying existing application programs, or writing new programs, you must
use a compiler supported by Language Environment. This requires that your
application programs must be link-edited using the Language Environment
SCEELKED library, and this in turn means that the resulting application load module
can execute only under Language Environment.

If any of your existing application programs do not run under Language

Environment, see the z/OS Language Environment Run-Time Migration Guide for
guidance on migrating them. The application programs might need to be recompiled
or relinked.

| Note: Support for OS/VS COBOL programs is now withdrawn. These programs,
| which had runtime support in CICS Transaction Server for z/OS Version 2,
| cannot run under CICS Transaction Server for z/OS Version 3. OS/VS
| COBOL programs must be upgraded to a supported level of COBOL, and
| recompiled against a level of COBOL compiler supported by CICS.
| Appendix B, “Migration for OS/VS COBOL programs,” on page 669 provides
| assistance with converting OS/VS COBOL programs to a supported level of
| COBOL.

Language Environment services

The following points apply to all programs using Language Environment under
CICS.
Callable services
Language Environment provides callable services, which are classified in the
following categories:
Storage services
These allow you to allocate and free storage from the Language
Environment heaps.
Error handling services
These provide a common method of obtaining information to enable you to
process errors.
Message services
These provide a common method of handling and issuing messages.
Date and time
These allow you to read, calculate, and write values representing the date
and time. Language Environment offers unique pattern-matching capabilities
that let you process almost any date and time format contained in an input
record or produced by operating system services.
National language support
These allow you to customize Language Environment output (such as
messages, RPTOPTS reports, RPTSTG reports, and dumps) for a given
country.
Locale
These allow you to customize culturally-sensitive output for a given national
language, country, and codeset by specifying a locale name.

10 CICS TS for z/OS: CICS Application Programming Guide

General
These are a set of callable services that are not directly related to a specific
Language Environment function, for example, dump.
Mathematical
These allow you to perform standard mathematical computations.

For further information about the details of these services, see the z/OS:
Language Environment Programming Guide. For information about the syntax
required to call any of the services, see the z/OS: Language Environment
Programming Reference.
CICS condition and AID handling
Language Environment condition handling does not alter the behavior of
applications that use CICS HANDLE CONDITION or HANDLE AID commands.
Language Environment is not involved in the handling of CICS-defined
exception conditions, which are raised and handled only by CICS. Similarly, AID
detection is a CICS function unaffected by Language Environment .
Abend handling
Language Environment Abend handling depends on the use of CICS HANDLE
ABEND. See “Using Language Environment Abend-handling”for details.
Storage
Language Environment uses storage obtained from CICS for each run-unit. See
“Managing Language Environment storage” on page 12 for information about
CICS parameters to control this.
Message and dump destinations
When the CEEMOUT (dispatch a message) and CEE3DMP (generate dump)
services are running under CICS, both the messages and dumps are sent to a
transient data queue called CESE, and not to their usual destinations. These
usual destinations are the ddname specified in the MSGFILE runtime option for
messages and the ddname given in the fname argument of the CEE3DMP
service for dumps. CICS ignores both of these ddnames.

Using Language Environment Abend-handling

When a CICS application is running under Language Environment , the action taken
when a task is scheduled for abnormal termination depends on whether a CICS
HANDLE ABEND is active or not active.

When a HANDLE ABEND is active, Language Environment condition handling does

not gain control for any abends or program interrupts, and any user-written
condition handlers that have been established by CEEHDLR are ignored. Instead,
the action defined in the CICS HANDLE ABEND takes place.

When a CICS HANDLE ABEND is not active, Language Environment condition

handling does gain control for abends and program interrupts if the runtime option
TRAP(ON) is specified. Normal Language Environment condition handling is then
performed. If TRAP(OFF) is specified, no error handling takes place; the abend
proceeds. For details of the actions taken during normal Language Environment
condition handling, see the z/OS: Language Environment Programming Guide.

User-written Language Environment condition handlers

The runtime option USRHDLR allows you to register a user-written condition
handler at the highest level. At a lower level, for example after a subroutine CALL,
you can use the CEEHDLR service to register a condition handler for that level.

Chapter 3. Language Environment 11

This lower level handler is automatically unregistered on return from the lower level.
If desired you can explicitly unregister it by using the CEEHDLU service. For an
explanation of stack levels and for details of the USRHDLR runtime option and the
CEEHDLR and CEEHDLU services, see the z/OS: Language Environment
Programming Guide.

If you write your own user-written Language Environment condition handler (other
than in COBOL), you can use most CICS commands, provided they are coded with
a NOHANDLE, RESP or RESP2 option, to prevent further conditions being raised
during execution of the condition handler. The only commands you cannot use are
the following, which must not appear in either the condition handler or any program
it calls:
v ABEND
v HANDLE ABEND
v HANDLE AID
v HANDLE CONDITION
v IGNORE CONDITION
v POP HANDLE
v PUSH HANDLE

Unless you use the NOLINKAGE translator option (see “NOLINKAGE” on page 80),
do not use the CICS translator to translate a COBOL user-written condition handler
that you have registered for a routine using the CEEHDLR service. This is because
the CICS translator adds two extra arguments to the PROCEDURE DIVISION
header of the COBOL program, the EXEC Interface Block (EIB) and the
COMMAREA. These arguments do not match the arguments passed by Language
Environment. A COBOL condition handler cannot, therefore, contain any CICS
commands.

However, a user-written condition handler can call a subroutine to perform CICS

commands (and this could be a COBOL routine). If you need to pass arguments to
this subroutine, place two dummy arguments before them in the caller. The called
subroutine must issue EXEC CICS ADDRESS EIB(DFHEIPTR) before executing
any other CICS commands.

For full details of the required interface to any Language Environment condition
handling routine, see the z/OS: Language Environment Programming Guide.

Managing Language Environment storage

When each program is first used, Language Environment tells CICS how much
storage the run unit work area (RUWA) requires. The allocation of storage depends
on the setting of the CICS system initialization parameter, RUWAPOOL.

If you specify RUWAPOOL=NO, at the start of each CICS link level, CICS issues a
GETMAIN for this storage and passes it to Language Environment to use for its
control blocks and for storage areas such as STACK, LIBSTACK, and HEAP. The
storage is acquired in the default key specified on the transaction. The storage is
freed (using FREEMAIN) when the program terminates.

If you specify RUWAPOOL=YES, the first run of a transaction is the same as with
RUWAPOOL=NO, but CICS keeps a history of the total storage for RUWAs that is
requested to run the transaction. This means that when the transaction is run again,
CICS issues a single GETMAIN for the total storage (and a single FREEMAIN at
task end), creating a RUWAPOOL. If the transaction follows the same path, CICS
allocates the storage from the RUWAPOOL, and no further GETMAIN has to be

12 CICS TS for z/OS: CICS Application Programming Guide

issued. If more storage is required for RUWAs because of different or extra CICS
links, CICS issues a GETMAIN and updates the history, so that next time the single
GETMAIN (and FREEMAIN) is for the larger amount. For transactions that issue a
large number of CICS LINK commands, the performance improvement can be
considerable.

If you specify AUTODST=YES, CICS indicates to Language Environment that it is

able to support dynamic storage tuning (see the CICS System Definition Guide).

If a program specifies a runtime option of ALL31(OFF) and Language Environment

needs to use storage below the 16MB line, two areas of storage are allocated, one
below 16MB and one above the 16MB line.

If necessary, any application can obtain CICSDATAKEY or USERDATAKEY storage

by using a CICS GETMAIN command. However, a program with an EXECKEY of
USER cannot use CICSDATAKEY storage.

Mixing languages in Language Environment

This section tells you how to build an application that is composed of programs that
have been written in different high-level source languages.

Assembler subroutines called from an HLL program are fairly straightforward and
not uncommon. A subroutine called from one HLL but written in another needs
much more careful consideration and involves what is called interlanguage
communication (ILC). Language Environment defines an ILC application as one
built of two or more HLLs and, optionally, assembler. See z/OS Language
Environment Writing Interlanguage Communication Applications for full details on
this subject.

Language Environment dictates that if there is any ILC within a run unit under
CICS, each compile unit must be compiled with a Language Environment-
conforming compiler. CICS supports three HLLs: C/C++, COBOL, and PL/I. We
consider the interfaces in pairs. If your application contains only two HLLs, consult
the appropriate section. If your application contains all three HLLs, consult those
sections corresponding to each of the interfaces within your application.
C/C++ and COBOL
The conditions under which Language Environment supports ILC between
routines written in C/C++ and COBOL depend on the following:
v Whether the language is C or C++
v Which COBOL compiler is being used and whether or not DLL is specified as
a compiler option
v Whether the call is static or dynamic
v Whether the function being invoked is within the module or exported from a
DLL
v Whether or not the program is reentrant
v What, if any, #pragma linkage statement you have in your C program
v Whether your C program exports functions or variables
v What, if any, extern statement you have in your C++ program
The results of all this are specified in five tables in z/OS Language Environment
Writing Interlanguage Communication Applications; you should consult this book
if your application mixes C/C++ and COBOL.

Chapter 3. Language Environment 13

C/C++ and PL/I
Under CICS, if all the components of your C/C++ and PL/I application are
reentrant, Language Environment supports ILC between routines compiled by
OS/390 C/C++ and PL/I for MVS & VM or VisualAge PL/I for OS/390 as follows:
v C/C++ routines can statically call PL/I routines and PL/I routines can statically
call C/C++ routines.
v C/C++ routines can fetch() PL/I routines that have OPTIONS(FETCHABLE)
specified. If the called routine contains any CICS commands, then C/C++
must pass the EIB and the COMMAREA as the first two parameters on the
call statement.
v PL/I routines can FETCH only those OS/390 C/C++ routines that have not
been processed by the CICS translator. This is because during the dynamic
call certain static fields created by the translator cannot be correctly set.
COBOL and PL/I
Under CICS, Language Environment supports ILC between routines compiled
with Language Environment-supported COBOL and PL/I compilers, as follows:
v COBOL routines can statically call PL/I routines, and PL/I routines can
statically call COBOL routines.
v COBOL programs can dynamically call PL/I routines that have
OPTIONS(FETCHABLE) specified and PL/I routines can FETCH COBOL
programs.
If the called routine contains any CICS commands then the calling routine must
pass the EIB and the COMMAREA as the first two parameters on the CALL
statement.
Assembler
The following rules apply:
v You can make static or dynamic calls from any Language
Environment-conforming HLL program to a Language Environment-
conforming assembler subroutine. Conversely, a Language
Environment-conforming assembler routine can make a static call to any
Language Environment-conforming routine, and can dynamically load another
routine, either assembler or HLL, by using either of the Language
Environment macros CEEFETCH or CEELOAD.
v You cannot delete (release) an ILC module that has been loaded using
CEELOAD.
v You can use the CEERELES macro to release an ILC module which has
been fetched using CEEFETCH.
v Use the language that fetched it to delete an assembler routine. This can
only be done from C/C++, COBOL, and PL/I, if there is no ILC with PL/I in
the module being released.
Additionally, you can make static calls from any Language Environment-
conforming HLL program or assembler subroutine to a non-conforming
assembler subroutine. However, a non-conforming assembler routine cannot
make a static call to any Language Environment-conforming routine, nor can it
fetch or load a conforming routine, since it cannot use the Language
Environment macros.

Note: For assembler to call C or C++, you must include the following
statement:
C #pragma linkage(,OS)
C++ extern "OS"

14 CICS TS for z/OS: CICS Application Programming Guide

DL/I
If you are using DL/I in your ILC application under CICS, calls to DL/I, either by
an EXEC DLI statement or by a CALL xxxTDLI, can be made only in programs
with the same language as the main program.
Language Environment does not support CALL CEETDLI under CICS.

Using Dynamic Link Libraries and Language Environment

The z/OS dynamic link library (DLL) facility provides a mechanism for packaging
programs and data into load modules (DLLs) that can be accessed from other
separate load modules. A DLL can export symbols representing routines that can be
called from outside the DLL, and can import symbols representing routines or data
or both in other DLLs, avoiding the need to link the target routines into the same
load module as the referencing routine. When an application references a separate
DLL for the first time, the system automatically loads the DLL into memory.

You should define all potential DLL executable modules as PROGRAM resources to
CICS.

DLL support is available for applications under CICS where the code has been
compiled using any of the compilers listed in the z/OS Language Environment
Programming Guide. See that manual for more information on building and using
DLLs.

Defining runtime options for Language Environment

Language Environment provides runtime options to control your program’s
processing. Under CICS, exactly which options apply to the execution of a particular
program depends not only on the program, but also on how it is run. Java programs
and programs initiated from the Web or through CICS IIOP services use the
Language Environment preinitialization module, CEEPIPI. This has its own version
of the CEEDOPT CSECT and such programs get their runtime options from this
CSECT. For normal CICS tasks, such as those started from a terminal, use any of
the methods listed below to set the Language Environment runtime options. The
methods are shown in the order in which they are processed. Each setting could be
overridden by a following one. This is, in effect, a reverse order of precedence.
1. In the CEEDOPT CSECT, where the installation default options for CICS are
located. This CSECT is generated from the CEECOPT sample and is
incorporated into the CEECCICS load module.
2. In the CEEROPT CSECT, where the region-wide default options are located.
This CSECT is link-edited into a load module of the same name and placed in a
data set in the DFHRPL library concatenation for the CICS job.
| 3. The user replacable program DFHAPXPO ( applies to XPLINK programs only).
4. In the CEEUOPT CSECT, where user-supplied application program-level
runtime options are located. This CSECT is linked with the application program
itself.
5. In the application source code using the programming language options
statements, as follows:
v In C programs, through the #pragma runopts statement in the program
source. For example:
#pragma runopts(rptstg(on))
v In PL/I programs, through the PLIXOPT declaration statement within the
program. For example:

Chapter 3. Language Environment 15

DECLARE PLIXOPT CHARACTER(18) VARYING STATIC EXTERNAL INIT(’RPTOPTS(ON) NOSTAE’);

Note: There is no source code mechanism that allows the setting of runtime
options within COBOL programs or within C++ programs.
6. In the Language Environment options specified in a debugging profile. For more
information, see “Debugging profiles” on page 656.

In most installations, the first method in the list above is not available to application
programmers, and the second is often not available. However, application
programmer can use the last two methods. They are in effect equivalent (some of
the newer compilers, for example VisualAge for PL/I, make them equivalent by
generating a CEEUOPT CSECT when PLIXOPT is declared). Choose either
methods 3 or method 4; do not attempt to use both methods. For details of
generating a CEEUOPT CSECT to link with your application, see z/OS Language
Environment Customization.
Notes:
1. Both CEEDOPT and CEEROPT are able to set any option so that it cannot be
overridden by a later specification.
2. Under CICS many of the Language Environment option settings are ignored.
These are all the Fortran-only options plus the following:

ABPERC AIXBLD CBLOPTS CBLQDA

DEBUG EXECOPS INTERRUPT LIBRARY
MSGFILE NONIPTSTACK PLITASKCOUNT POSIX
RTEREUS RTLS SIMVRD THREADHEAP
VERSION

| 3. CICS provides an environment variable called CICSVAR to allow the

| CONCURRENCY and API program attributes to be closely associated with the
| application program itself by using the ENVAR runtime option. Whilst it may be
| used in a CEEDOPT CSECT to set an installation default, it is most useful to be
| set in a CEEUOPT CSECT linkedited with an individual program, or set via a
| #pragma statement in the source of a C or C++ program, or set via a PLIXOPT
| statement in a PL/I program.
| For example, when a program has been coded to threadsafe standards it can
| be defined as such without having to change an PROGRAM resource definition,
| or adhere to an installation defined naming standard to allow a program
| autoinstall exit to install it with the correct attributes. CICSVAR can be used for
| Language Environment conforming assembler, for PLI, for COBOL and for C
| and C++ programs (both those compiled with the XPLINK option, and those
| compiled without it) that have been compiled using a Language Environment
| conforming compiler. CICSVAR cannot be used for assembler programs that are
| not Language Environment conforming or for java programs.
| Use of CICSVAR overrides the settings on a PROGRAM resource definition
| installed via standard RDO interfaces, or via program autoinstall. Prior to the
| program being run for the first time, an INQUIRE PROGRAM command shows
| the keyword settings from the program definition. Once the application has been
| run once, an INQUIRE PROGRAM command shows the settings with any
| CICSVAR overrides applied. CICSVAR can take one of three values,
| QUASIRENT, THREADSAFE or OPENAPI.

| CICSVAR=QUASIRENT results in a program with attributes

| CONCURRENCY(QUASIRENT) APIST(CICSAPI)

16 CICS TS for z/OS: CICS Application Programming Guide

| This can be assembled and linkedited into a into a load module and then the
| CEEUOPT load module linkedited together with any language program
| supported by Language Environment as explained above.
| Alternatively for C and C++ programs, add the following statement at the start of
| the program source before any other C statements:
| #pragma runopts(ENVAR(CICSVAR=THREADSAFE))
| For PL/I programs add the following statement following the PL/I MAIN
| procedure statement:
| DCL PLIXOPT CHAR(25) VAR STATIC EXTERNAL INIT(’ENVAR(CICSVAR=THREADSAFE)’);

Finally, be aware that , after all the above changes, there are two exits that are
called in the following order and both of these can change some of the options as
follows:
1. By setting the CEEAUE_A_OPTION return parameter of the CEEBXITA
Language Environment user exit (apart from the LIBRARY, RTLS, STACK, and
VERSION options).
2. In the storage tuning user exit, CEECSTX, the options STACK, LIBSTACK,
HEAP, ANYHEAP, and BELOWHEAP can be set.

The storage tuning exit, like the CEEROPT CSECT, is region wide, but CEEBXITA
is linked into every program. Language Environment calls CEEBXITA the assembler
exit because, like CEECSTX, it is invoked before the environment is fully
established and must therefore be coded in assembler.

Language Environment supplies a sample source version of CEEBXITA in the

SCEESAMP library (it simply returns to its caller for whatever reason it is called).
You can use this as it is or modify it for use as the installation default version.
However, you can link-edit a specifically tailored version of CEEBXITA with any
application program and this version is then used instead of the installation default
version. Take great care if you choose this method since CEEBXITA is invoked for
up to five different reasons during the course of program execution, and an
application-specific version of CEEBXITA must be capable of handling all these
invocations.

For more details on both CEEBXITA and CEECSTX see z/OS Language
Environment Customization.

Runtime options in child enclaves

Under CICS the execution of a CICS LINK command creates what Language
Environment calls a Child Enclave. A new environment is initialized and the child
enclave gets its runtime options exactly as discussed above. These runtime options

Chapter 3. Language Environment 17

are completely independent of those that existed in the creating enclave. Frequent
use of EXEC CICS LINK, and the individual setting of many runtime options could
affect performance (see also the CICS system initialization parameter RUWAPOOL
for CICS LINK performance considerations). A static or dynamic call does not incur
these overheads. If you need to use CEEUOPT to specify options, specifying only
those options that are different from the defaults will improve performance.

Something similar happens when a CICS XCTL command is executed. In this case
we do not get a child enclave, but the existing enclave is terminated and then
reinitialized with the runtime options determined for the new program. The same
performance considerations apply.

CEEBXITA coding
If you write your own version of CEEBXITA, you must write it in assembler. You can
use all CICS commands except the ones listed here, provided you specify the
NOHANDLE, RESP or RESP2 option, to prevent conditions being raised during the
execution of the exit. These are the commands that cannot be used within
CEEBXITA, or any routines called by CEEBXITA:
v ABEND
v HANDLE ABEND
v HANDLE AID
v HANDLE CONDITION
v IGNORE CONDITION
v POP HANDLE
v PUSH HANDLE

Determining which options were used

If you want to know which options were in effect when your program ran, specify
the option RPTOPTS(ON). When the program ends this produces a list of all the
runtime options used. The list is written to the CESE TD queue. The list contains
not only the actual settings of the options, but also their origin, that is, whether they
are the default for the installation or the region, or whether they were set by the
programmer or in one of the exits.

Note: Do not use RPTOPTS(ON) in a production environment - there is significant

overhead and it causes a large amount of data to be written to the CESE
queue.

For more information about how to specify Language Environment runtime options
and also for their meanings, see z/OS Language Environment Programming
Reference.

Writing a CEEBINT initialization exit for Language Environment

All programs running under Language Environment invoke a subroutine called
CEEBINT at program initialization time, just after invocation of the CEEBXITA and
CEECSTX exits. The runtime environment is fully operational at this point and
Language Environment calls this program the HLL user exit. Language Environment
provides a module containing this program in the SCEELKED library (it simply
returns to its caller) and this is, therefore, the installation default version. However,
you can also write and link-edit a tailored version in to any program to replace the
default.

Ordinary Language Environment coding rules apply to CEEBINT, and you can write
it in C, C++, PL/I, or Language Environment-conforming assembler. CEEBINT

18 CICS TS for z/OS: CICS Application Programming Guide

applies to COBOL programs just as any others, but it cannot be written in COBOL
or call COBOL programs. If CEEBINT introduces a second HLL to a program, the
rules for mixing HLLs described in “Mixing languages in Language Environment” on
page 13 apply.

For more information on the High Level Language user exit, CEEBINT, see the
z/OS Language Environment Programming Guide.

Chapter 3. Language Environment 19

20 CICS TS for z/OS: CICS Application Programming Guide
Chapter 4. Programming in COBOL
| CICS supports COBOL programs that have been compiled by the supported
| compilers listed in the CICS Release Guide. All COBOL programs are executed
| under the runtime support provided by Language Environment.

All references to COBOL in CICS Transaction Server for z/OS, Version 3 Release 1
documentation imply the use of a supported Language Environment-conforming
compiler such as Enterprise COBOL for z/OS and OS/390, unless specifically stated
otherwise.

Note
| Runtime support for OS/VS COBOL is withdrawn in CICS Transaction Server
| for z/OS Version 3.

CICS does not provide translate and compile time support for old non-Language
Environment-conforming compilers. These compilers and their runtime libraries are
now out of service. See “Conversion to Enterprise COBOL” on page 669 for
information about conversion of programs compiled with unsupported compilers.

This chapter describes:

v “COBOL programming considerations”
v “Language Environment considerations for COBOL applications” on page 25
v “Using based addressing with COBOL” on page 26
v “Calling subprograms from COBOL” on page 27
v “Using the COBOL2 and COBOL3 translator options” on page 33
v “Using the OO COBOL translator option” on page 42

COBOL programming considerations

With COBOL you must use only EXEC CICS commands to invoke operating system
services. Some COBOL statements must not be used. Some features of COBOL
that are of interest to the CICS programmer are:
v Simplified based addressing using cell pointer variables and the ADDRESS
special register.
v The ability to use COBOL CALL statements to call assembler language, other
COBOL programs, and PL/I or C/C++ programs.
v The LENGTH special register, which CICS uses to deduce the length of data
items.
v The ability to use the RETURN-CODE special register in a CICS application
program. This register allows you to set and access return codes in COBOL
programs.

With compiler option DATA(24), the WORKING-STORAGE SECTION is allocated

below the 16MB line. With compiler option DATA(31), the WORKING-STORAGE
SECTION is allocated above the 16MB line.

Programming restrictions
This section describes COBOL language elements that you cannot use under CICS,
or whose use is restricted or can cause problems under CICS.

© Copyright IBM Corp. 1989, 2005 21

In general, neither the CICS translator nor the COBOL compiler detects the use of
COBOL words affected by the following restrictions. The use of a restricted word in
a CICS environment may cause a failure at execution time. However, COBOL
provides the WORD(CICS) compiler option, which causes the compiler to use
IGYCCICS, a table of words reserved for CICS. This allows the COBOL compiler to
flag any occurrences of COBOL reserved words that conflict with CICS restrictions.

The following restrictions apply to a COBOL program that is to be used as a CICS

application program. (See the appropriate COBOL programming guide for more
information about these functions.)
v If no IDENTIFICATION DIVISION is present, only the CICS commands are
expanded.
If the IDENTIFICATION DIVISION only is present, only DFHEIVAR, DFHEIBLK,
and DFHCOMMAREA are produced.
v Statements that produce variable-length areas, such as OCCURS DEPENDING
ON, should be used with caution within the WORKING-STORAGE SECTION.
v If you have any CICS applications written in COBOL, you may need to review the
COBOL runtime options in use at your installation. In particular, if your
applications are not coded to ensure that the WORKING-STORAGE SECTION is
properly initialized (for example, cleared with binary zeros before sending maps),
you should use the STORAGE runtime option. See z/OS Language Environment
Customization for information about customizing runtime options.
v You cannot use entry points in COBOL in CICS.
v When a debugging line is to be used as a comment, it must not contain any
unmatched quotation marks.
v Do not use COBOL statements that invoke operating system functions. Instead,
use CICS commands.
v Do not use EXEC CICS commands in a Declaratives Section.
v You must use CICS commands for most input and output processing. Therefore,
do not describe files or code any OPEN, CLOSE, READ, START, REWRITE,
WRITE, or DELETE statements. Instead, use CICS commands to retrieve,
update, insert, and delete data.
v Do not use a format-1 ACCEPT statement in a CICS program. Format-2
ACCEPT statements are supported by Language Environment enabled
compilers. See “Language Environment considerations for COBOL applications”
on page 25 for more information about Language Environment .
v Do not use DISPLAY . . . UPON CONSOLE and DISPLAY . . . UPON
SYSPUNCH. DISPLAY to the system logical output device ( SYSOUT,
SYSLIST,SYSLST) is supported.
v Do not use STOP “literal”.
v There are restrictions on the use of the SORT statement. See the Enterprise
COBOL for z/OS and OS/390: Programming Guide for information. Do not use
MERGE.
v Do not use:
– USE declaratives (except USE FOR DEBUGGING). You may specify USE
FOR DEBUGGING, but it has no effect because the DEBUG Language
Environment option is ignored in CICS.
| – ENVIRONMENT DIVISION and FILE SECTION entries associated with data
| management, because CICS handles data management. (These can be used
| when they are associated with the limited SORT facility referenced above.)
– User-specified parameters to the main program.

22 CICS TS for z/OS: CICS Application Programming Guide

v Do not use the following compiler options:
DYNAM (if program is to be translated)
NOLIB (if program is to be translated)
NORENT
v The use of the TEST(SYM,NOSEPARATE) compiler option results in a very large
increase in program size. Therefore, short-of-storage problems may occur when
using this option. You can achieve the same functionality with
TEST(SYM,SEPARATE) without an increase in program size. For more
information about the TEST compiler option, see the Enterprise COBOL for z/OS
and OS/390 Programming Guide.
| v Use TRUNC(OPT) for handling binary data items if they conform to the PICTURE
| definitions. Otherwise use TRUNC(OPT) as the compiler option, and USAGE
| COMP-5 for items where the binary value might be larger than the PICTURE
| clause would allow. TRUNC(BIN) inhibits runtime performance, so only use this
| option if you have no control over binary data items (such as those created by a
| code generator). (TRUNC(STD) is the default.)
v For VS COBOL II programs with Language Environment runtime, the following
limits apply to the length of WORKING-STORAGE:
– When the compiler option DATA(24) is used, the limit is the available space
below the 16MB line.
– When the compiler option DATA(31) is used, the limit is 128MB.
80 bytes are required for storage accounting and save areas, and this must be
included within the limits.
| v The use of the RMODE(24) compiler option means that the program always
| resides below the 16MB line, so this is not recommended. RMODE(ANY) or
| RMODE(AUTO) should be used instead. For more information about the RMODE
| compiler option, see the Enterprise COBOL for z/OS and OS/390 Programming
| Guide.
v If the DLI option is specified and an ENTRY statement immediately follows the
PROCEDURE DIVISION header, you are recommended to change the
PROGRAM-ID name to the ENTRY statement literal, then delete the ENTRY
statement.
v The following compiler options have no effect in a CICS environment:
ADV
| AWO
| EXPORTALL
FASTSRT
| NAME
OUTDD
| THREAD
v If you use HANDLE CONDITION or HANDLE AID, you can avoid addressing
problems by using SET(ADDRESS OF A-DATA) or SET(A-POINTER) where
A-DATA is a structure in the LINKAGE SECTION and A-POINTER is defined with
the USAGE IS POINTER clause.
v For a COBOL program running above the 16MB line, these restrictions apply for
31-bit addressing:
– If the receiving program is link-edited with AMODE(31), addresses passed to it
must be 31-bits long (or 24-bits long with the left-most byte set to zeros).
– If the receiving program is link-edited with AMODE(24), addresses passed to it
must be 24-bits long.

Chapter 4. Programming in COBOL 23

| Specify the DATA(24) compiler option for programs running in 31-bit addressing
| mode that are passing data arguments to programs in 24-bit addressing mode.
| This ensures that the data will be addressable by the called program.

Using the DL/I CALL interface

If you have programs that use CALL DL/I, you must:
v Retain the DLIUIB declaration and at least one PCB declaration in the LINKAGE
SECTION.
v Change the PCB call to specify the UIB directly, as follows:
CALL ’CBLTDLI’ USING PCB-CALL
PSB-NAME
ADDRESS OF DLIUIB.
v Obtain the address of the required PCB from the address list in the UIB.
Figure 1 on page 25 illustrates the whole of the above process. The example in the
figure assumes that you have three PCBs defined in the PSB and want to use the
second PCB in the database CALL. Therefore, when setting up the ADDRESS
special register of the LINKAGE SECTION group item PCB, the program uses 2 to
index the working-storage table, PCB-ADDRESS-LIST. To use the nth PCB, you
use the number n to index PCB-ADDRESS-LIST.

24 CICS TS for z/OS: CICS Application Programming Guide

WORKING-STORAGE SECTION.
77 PCB-CALL PIC X(4) VALUE ’PCB ’.
77 GET-HOLD-UNIQUE PIC X(4) VALUE ’GHU ’.
77 PSB-NAME PIC X(8) VALUE ’CBLPSB’.
77 SSA1 PIC X(40) VALUE SPACES.
01 DLI-IO-AREA.
02 DLI-IO-AREA1 PIC X(99).
*
LINKAGE SECTION.
COPY DLIUIB.
01 OVERLAY-DLIUIB REDEFINES DLIUIB.
02 PCBADDR USAGE IS POINTER.
02 FILLER PIC XX.
01 PCB-ADDR-LIST.
02 PCB-ADDRESS-LIST USAGE IS POINTER
OCCURS 10 TIMES.
01 PCB.
02 PCB-DBD-NAME PIC X(8).
02 PCB-SEG-LEVEL PIC XX.
02 PCB-STATUS-CODE PIC XX.
*
PROCEDURE DIVISION.
*SCHEDULE THE PSB AND ADDRESS THE UIB
CALL ’CBLTDLI’ USING PCB-CALL PSB-NAME ADDRESS OF DLIUIB.
*
*MOVE VALUE OF UIBPCBAL, ADDRESS OF PCB ADDRESS LIST (HELD IN UIB)
*(REDEFINED AS PCBADDR, A POINTER VARIABLE), TO
*ADDRESS SPECIAL REGISTER OF PCB-ADDR-LIST TO PCBADDR.
SET ADDRESS OF PCB-ADDR-LIST TO PCBADDR.
*MOVE VALUE OF SECOND ITEM IN PCB-ADDRESS-LIST TO ADDRESS SPECIAL
*REGISTER OF PCB, DEFINED IN LINKAGE SECTION.
SET ADDRESS OF PCB TO PCB-ADDRESS-LIST(2).
*PERFORM DATABASE CALLS ......
........
MOVE ........ TO SSA1.
CALL ’CBLTDLI’ USING GET-HOLD-UNIQUE PCB DLI-IO-AREA SSA1.
*CHECK SUCCESS OF CALLS .......
IF UIBFCTR IS NOT EQUAL LOW-VALUES THEN
...... error diagnostic code
........
IF PCB-STATUS-CODE IS NOT EQUAL SPACES THEN
...... error diagnostic code
........

Figure 1. Using the DL/I CALL interface

Language Environment considerations for COBOL applications

| CICS supports COBOL programs that have been compiled by the supported
| compilers listed in the CICS Release Guide. Programs compiled by any of these
| compilers can run under Language Environment.

There are some considerations associated with the use of a VS COBOL II compiler:
Re-linking VS COBOL II programs
If object modules are not available for re-linking existing VS COBOL II programs
to run under Language Environment, a sample job stream for performing the
task is provided in the IGZWRLKA member of the SCEESAMP sample library.
CICS stub
Although VS COBOL II programs linked with the old CICS stub, DFHECI, run

Chapter 4. Programming in COBOL 25

under Language Environment, use of the DFHELII stub is recommended and
could be essential in a mixed language environment.
Using CEEWUCHA
If you are adapting VS COBOL II programs to run under Language
Environment, the sample user condition handler, CEEWUCHA, supplied by
Language Environment in the SCEESAMP library, can be used to advantage. It
does the following:
v It provides compatibility with existing VS COBOL II applications running
under CICS by allowing EXEC CICS HANDLE ABEND LABEL statements to
get control when a runtime detected error occurs.
v It converts all unhandled runtime detected errors to the corresponding user
1xxx abend issued by VS COBOL II.
v It suppresses all IGZ0014W messages, which are generated when IGZETUN
or IGZEOPT is link-edited with a VS COBOL II application. (Performance is
better if the programs are not link-edited with IGZETUN or IGZEOPT.)

For information on migrating existing COBOL programs to run under Language

Environment, see the Enterprise COBOL for z/OS and OS/390: Compiler and
Run-Time Migration Guide, GC27-1409.

CBLPSHPOP option
The CBLPSHPOP runtime option controls whether Language Environment
automatically issues an EXEC CICS PUSH HANDLE command during initialization
and an EXEC CICS POP HANDLE command during termination whenever a
COBOL subroutine is called.

If your application makes many COBOL subroutine CALLs under CICS,

performance is better with CBLPSHPOP(OFF) than with CBLPSHPOP(ON). You
can set CBLPSHPOP on an individual transaction basis by using CEEUOPT, as
explained in “Defining runtime options for Language Environment” on page 15.
However, because condition handling has not been stacked, be aware that:
v If your called routine raises a condition that causes CICS to attempt to pass
control to a condition handler in the calling routine, this is an error and your
transaction will be abnormally terminated.
v If you use any of the PUSHable CICS commands, HANDLE ABEND, HANDLE
AID, HANDLE CONDITION, or IGNORE CONDITION, within the called routine,
you will be changing the settings of your caller and this could lead to later errors.

Using based addressing with COBOL

CICS application programs need to access data dynamically when the data is in a
CICS internal area, and only the address is passed to the program. Examples are:
v CICS areas such as the CWA, TWA, and TCTTE user area (TCTUA), accessed
using the ADDRESS command
v Input data, obtained by EXEC CICS commands such as READ and RECEIVE
with the SET option

COBOL provides a simple method of obtaining addressability to the data areas

defined in the LINKAGE SECTION using pointer variables and the ADDRESS
special register. Figure 2 on page 27 gives an example of this.

The ADDRESS special register holds the address of a record defined in the
LINKAGE SECTION with level 01 or 77. This register can be used in the SET

26 CICS TS for z/OS: CICS Application Programming Guide

option of any command in ADDRESS mode. These commands include GETMAIN,
LOAD, READ, and READQ. For programming information, including a complete list
of these commands, see the CICS Application Programming Reference manual..

Figure 2 shows the use of ADDRESS special registers in COBOL. If the records in
the READ or REWRITE commands are of fixed length, no LENGTH option is
required. This example assumes variable-length records. After the read, you can get
the length of the record from the field named in the LENGTH option (here,
LRECL-REC1). In the REWRITE command, you must code a LENGTH option if you
want to replace the updated record with a record of a different length.

WORKING-STORAGE SECTION.
77 LRECL-REC1 PIC S9(4) COMP.
LINKAGE SECTION.
01 REC-1.
02 FLAG1 PIC X.
02 MAIN-DATA PIC X(5000).
02 OPTL-DATA PIC X(1000).
01 REC-2.
02 ...
PROCEDURE DIVISION.
EXEC CICS READ UPDATE...
SET(ADDRESS OF REC-1)
LENGTH(LRECL-REC1)
END-EXEC.
IF FLAG1 EQUAL X’Y’
MOVE OPTL-DATA TO ...
.
.
.
EXEC CICS REWRITE...
FROM(REC-1)
END-EXEC.

Figure 2. Addressing CICS data areas in locate mode

Using WITH DEBUGGING MODE

If a “D” is placed in column seven of the first line of a COBOL EXEC CICS
command, that “D” is also found in the translated CALL statements. This translated
command is only executed if WITH DEBUGGING MODE is specified. A “D” placed
on any line other than the first line of the EXEC CICS statement is not required and
is ignored by the translator.

Calling subprograms from COBOL

In a CICS system, when control is transferred from the active program to an
external program, but the transferring program remains active and control can be
returned to it, the program to which control is transferred is called a subprogram.

There are three ways of transferring control to a subprogram:

EXEC CICS LINK
The calling program contains a command in one of these forms:
EXEC CICS LINK PROGRAM(’subpgname’)
EXEC CICS LINK PROGRAM(name)

In the first form, the called subprogram is explicitly named as a nonnumeric

literal within quotation marks. In the second form, name refers to the COBOL
data area with length equal to that required for the name of the subprogram.

Chapter 4. Programming in COBOL 27

Static COBOL call
The calling program contains a COBOL statement of the form:
CALL ’subpgname’

The called subprogram is explicitly named as a literal string.

Dynamic COBOL call
The calling program contains a COBOL statement of the form:
CALL identifier

The identifier is the name of a COBOL data area that must contain the name of
the called subprogram.

For information about the performance implications of using each of these methods
to call a subprogram, see the Enterprise COBOL for z/OS and OS/390:
Programming Guide, and the IBM Enterprise COBOL Version 3 Release 1
Performance Tuning Paper. The White Paper is available on the Web at
www.ibm.com/software/ad/cobol/library

COBOL programs can call any language programs statically or dynamically. LINK or
XCTL are not required for inter-language communication, unless you wish to use
CICS functions such as COMMAREA. See Language Environment Writing Inter
Language Communication Applications for guidance on mixing languages under
Language Environment control.

“Rules for calling subprograms” on page 29 gives the rules governing the use of the
three ways to call a subprogram. This information refers to CICS application logical
levels. Each LINK command creates a new logical level, the called program being
at a level one lower than the level of the calling program (CICS is taken to be at
level 0). Figure 3 on page 32 shows logical levels and the effect of RETURN
commands and CALL statements in linked and called programs.

The term run unit is used in Figure 3 on page 32. A run unit is a running set of one
or more programs that communicate with each other by COBOL static or dynamic
CALL statements. In a CICS environment, a run unit is entered at the start of a
CICS task, or invoked by a LINK or XCTL command. A run unit can be defined as
the execution of a program defined by a PROGRAM resource definition, even
though for dynamic CALL, the subsequent PROGRAM definition is needed for the
called program. When control is passed by a XCTL command, the program
receiving control cannot return control to the calling program by a RETURN
command or a GOBACK statement, and is therefore not a subprogram.

The terms ’translator’ and ’translation’ in “Rules for calling subprograms” on page
29 refer to the separate translator. This step is not required if a compiler with an
integrated translator is used.

28 CICS TS for z/OS: CICS Application Programming Guide

Rules for calling subprograms
The following rules describe the requirements and behavior of called or linked
subprograms.

Translation
LINK
The linked subprogram must be translated if it, or any subprogram invoked from
it, contains CICS function.
Static and Dynamic COBOL CALL
The called subprogram must be translated if it contains CICS commands or
references to the EXEC interface block (DFHEIBLK) or to the CICS
communication area (DFHCOMMAREA).

Compilation
(You must always use the NODYNAM compiler option (the default) when you
compile a COBOL program that is to run with CICS, even if the program issues
dynamic calls.)

Link-editing
LINK
The linked subprogram must be compiled and link-edited as a separate
program.
Static COBOL CALL
The called subprogram must be link-edited with the calling program to form a
single load module (but the programs can be compiled separately). This can
produce large program modules, and it also stops two programs that call the
same program from sharing a copy of that program.
Dynamic COBOL CALL
The called subprogram must be compiled and link-edited as a separate load
module. It can reside in the link pack area or in a library that is shared with
other CICS and non-CICS regions at the same time.

CICS CSD entries without program autoinstall

(If you use program autoinstall, you do not need an entry in the CSD.)
LINK
The linked subprogram must be defined using RDO. If the linked subprogram is
unknown or unavailable, even though autoinstall is active, the LINK fails with
the PGMIDERR condition.
Static COBOL CALL
The calling program must be defined in the CSD. If program A calls program B
and then program B attempts to call program A, COBOL issues a message and
an abend(1015). The subprogram is part of the calling program so no CSD
entry is required.
Dynamic COBOL CALL
The calling program must be defined in the CSD. If program A calls program B
and then program B attempts to call program A, COBOL issues a message and
an abend(1015). The called subprogram must be defined in the CSD. If the
called subprogram cannot be loaded or is unavailable even though autoinstall is
active, COBOL issues a message and abends (1029).

Chapter 4. Programming in COBOL 29

Return from subprogram
LINK
The linked subprogram must return using either RETURN or a native language
return command such as the COBOL statement GOBACK.
Static and Dynamic COBOL CALL
The called subprogram must return using a native language return statement
such as the COBOL statement GOBACK or EXIT PROGRAM. The use of
RETURN in the called subprogram terminates the calling program.

Language of subprogram
LINK, Static and Dynamic COBOL CALL
Any language supported by CICS.

Contents of subprogram
The contents of any called or linked subprogram can be any function supported by
CICS for the language (including calls to external databases, for example, DB2®
and DL/I) with the exception that an assembler language subprogram cannot CALL
a lower level subprogram.

Passing parameters to subprogram

Data can be passed by any of the standard CICS methods (COMMAREA, TWA,
TCTUA, TS queues) if the called or linked subprogram is processed by the CICS
translator.
LINK
If the COMMAREA is used, its address must be passed in the LINK command.
If the linked subprogram uses 24-bit addressing, and the COMMAREA is above
the 16MB line, CICS copies it to below the 16MB line, and recopies it on return.
Static COBOL CALL
The CALL statement may pass DFHEIBLK and DFHCOMMAREA as the first
two parameters, if the called program is to issue EXEC CICS requests, or the
called program can issue EXEC CICS ADDRESS commands. The COMMAREA
is optional but if other parameters are passed, a dummy COMMAREA must
also be passed. The rules for nested programs can be different. See “Nesting:
what the application programmer must do” on page 38
Dynamic COBOL CALL
The CALL statement may pass DFHEIBLK and DFHCOMMAREA as the first
two parameters, if the called program is to issue EXEC CICS requests, or the
called program can issue EXEC CICS ADDRESS commands. The COMMAREA
is optional but if other parameters are passed, a dummy COMMAREA must
also be passed. If the called subprogram uses 24-bit addressing and any
parameter is above the 16MB line, COBOL issues a message and
abends(1033) .

Storage
LINK
On each entry to the linked subprogram, a new initialized copy of its
WORKING-STORAGE SECTION is provided, and the run unit is reinitialized (in
some circumstances, this can cause a performance degradation).

30 CICS TS for z/OS: CICS Application Programming Guide

Static and Dynamic COBOL CALL
On the first entry to the called subprogram within a CICS logical level, a new
initialized copy of its WORKING-STORAGE SECTION is provided. On
subsequent entries to the called subprogram at the same logical level, the same
WORKING STORAGE is provided in its last-used state, that is, no storage is
freed, acquired, or initialized. If performance is unsatisfactory with LINK
commands, COBOL calls may give improved results.

CICS condition, AID and abend handling

LINK
On entry to the called subprogram, no abend or condition handling is active.
Within the subprogram, the normal CICS rules apply. In order to establish an
abend or condition handling environment, that exists for the duration of the
subprogram, a new HANDLE command should be issued on entry to the
subprogram. The environment so created remains in effect until either a further
HANDLE command is issued, or the subprogram returns control to the caller.
Static and Dynamic COBOL CALL
If the dynamic COBOL CALL fails, CICS abend handling is not invoked, and
you may get a COBOL abend code (1013).If the dynamic COBOL CALL fails,
with Language Environment and CBLPSHPOP ON:
v On entry to the called subprogram, no abend or condition handling is active.
Within the subprogram, the normal CICS rules apply. On entry to the called
subprogram, COBOL issues a PUSH HANDLE to stack the calling program’s
condition or abend handlers. In order to establish an abend or condition
handling environment that exists for the duration of the subprogram, a new
HANDLE command should be issued on entry to the subprogram. The
environment that this creates remains in effect until either a further HANDLE
command is issued or the subprogram returns control to the caller. When
control is returned to the calling program from the subprogram, COBOL
unstacks the condition and abend handlers using a POP HANDLE.
If the dynamic COBOL CALL fails, with CBLPSHPOP OFF:
v The condition/AID and abend handling for the calling program remain in
effect.

Location of subprogram
LINK
Can be remote.
Static and Dynamic COBOL CALL
Must be local.

Flow of control between programs and subprograms

Figure 3 on page 32 shows the possible flows between COBOL main and
subprograms (also known as run units).

A main, or level 1 program can use the COBOL GOBACK or STOP RUN
statements, or the CICS RETURN command to terminate and return to CICS. It can
use a COBOL CALL statement to call a subprogram at the same logical level (level
1), or a CICS LINK command to call a subprogram at a lower logical level. A called
subprogram at level 1 can return to the caller using the COBOL GOBACK
statement, or can terminate and return to CICS using EXEC CICS RETURN.

Chapter 4. Programming in COBOL 31

A subprogram executing at level 2 can use the COBOL GOBACK or STOP RUN
statements, or the CICS RETURN command to terminate and return to the level 1
calling program. It can use a COBOL CALL statement or a CICS XCTL command to
call a subprogram at the same level (level 2). A subprogram called using the
COBOL CALL at level 2 can return to the caller ( at level 2) using the COBOL
GOBACK statement, or can return to the level 1 calling program using EXEC CICS
RETURN. A subprogram called using XCTL at level 2 can only return to the level 1
calling program, using GOBACK, STOP RUN or EXEC CICS RETURN.

See “Application program logical levels” on page 562 for more information about
program logical levels.

CICS Level
0

Program U
GOBACK
...
STOP RUN
...
EXEC CICS RETURN
Run ... Level
Unit CALL Program V 1
A ... GOBACK
... ...
... EXEC CICS RETURN
EXEC CICS LINK
...

Program W
GOBACK
...
STOP RUN
Run ...
Unit EXEC CICS RETURN
B ...
CALL Program X
... GOBACK
... ...
... EXEC CICS RETURN
EXEC CICS XCTL
... Level
2

Program Y
CALL Program Z
... GOBACK
... ...
GOBACK STOP RUN
Run ... ...
Unit STOP RUN EXEC CICS RETURN
C ...
EXEC CICS RETURN

Figure 3. Flow of control between COBOL programs, run units, and CICS

32 CICS TS for z/OS: CICS Application Programming Guide

Using the COBOL2 and COBOL3 translator options
# The following CICS translator options for COBOL are available in CICS TS for
# z/OS, Version 3.1:
# v COBOL2
# v COBOL3
# v OOCOBOL
# The ANSI85 translator option ceased to be available in CICS Transaction Server for
# z/OS, Version 2 Release 2.

The OOCOBOL translator option should be used if the program contains OO

COBOL syntax.

# The COBOL2 option is the default. It does not have the same effect on the
# translator as it did in CICS Transaction Server for z/OS, Version 2 Release 1 and
# earlier releases. COBOL2 instructs the translator to translate as COBOL3, but in
# addition to include declarations of temporary variables for use in EXEC CICS and
# EXEC DLI requests.

# Choose the COBOL2 option if you are re-translating old programs which were
# written in such a way that they require the use of temporary variables. In particular,
# note that the use of temporary variables might circumvent errors that would
# normally occur when an argument value in a program is incorrectly defined. The
# COBOL2 option in CICS Transaction Server for z/OS, Version 2 Release 1 and
# earlier releases provided declarations of temporary variables. Because of this
# feature, incorrect definitions of argument values might be present, but not
# noticeable at runtime, in programs that were originally translated with the COBOL2
# option in earlier releases of CICS Transaction Server. Translating these programs
# with the COBOL3 option can reveal these errors for the first time. To assist with
# migration to the newer releases of CICS, you may use the new COBOL2 option to
# continue to circumvent the errors in the programs, rather than correcting them.

# If you are confident that your program do not need the translator’s temporary
# variables, you may use COBOL3, which results in smaller working storage. The
# COBOL3 option includes all features of the older COBOL2 and ANSI85 translator
# options, except for declarations of temporary variables.

# Note: COBOL2 and COBOL3 are mutually exclusive. If you specify both options by
# different methods, the COBOL3 option is always used, regardless of where
# the two options have been specified. If this happens, the translator issues a
# warning message.

# The following topics describe specific translator action that is taken when the
# COBOL3 option is used. Processing with the COBOL2 option is the same in all
# respects, except for declarations of temporary variables.

For information about translating your program and preparing it for execution, see
Chapter 8, “Translation and compilation,” on page 67.

Literals intervening in blank lines

Blank lines can appear anywhere in a COBOL source program. A blank line
contains nothing but spaces between columns 7 and 72 inclusive.

Chapter 4. Programming in COBOL 33

Translator action
If blank lines occur within literals in a COBOL source program, the translator
eliminates them from the translated output but includes them in the translated
listing.

Lower case characters

Lower case characters can occur anywhere in any COBOL word, including
user-defined names, system names, and reserved words.

Translator action
The translator listing and output preserve the case of COBOL text as entered.

In addition, the translator accepts mixed case in:

v Translator options
v EXEC CICS commands, both for keywords and for arguments to keywords
v CBL and PROCESS statements
v Compiler directives such as EJECT and SKIP1

The translator does not translate lower case text into upper case. Some names in
COBOL text, for example file names and transaction IDs, must match with
externally defined names. Such names must always be entered in the same case
as the external definition.

If you specify the LINKAGE translator option, or allow it to default, a mixed-case

version of the EIB structure (DFHEIBLC) is inserted into the LINKAGE SECTION.

Sequence numbers containing any character

In a COBOL source program, the sequence number field can contain any character
in the computer’s character set. The sequence number fields need not be in any
order and need not be unique.

34 CICS TS for z/OS: CICS Application Programming Guide

REPLACE statement
COBOL programs can include the REPLACE statement, which allows the
replacement of identified text by defined substitution text. The text to be replaced
and inserted can be pseudo-text, an identifier, a literal, or a COBOL word.
REPLACE statements are processed after COPY statements.

Translator action
If you process your COBOL source statements with the CICS-supplied translator,
the translator accepts REPLACE statements but does not translate text between
pseudo-text delimiters, with the exception of CICS built-in functions (DFHRESP and
DFHVALUE), which are translated wherever they occur. CICS commands should
not be placed between pseudo-text delimiters.

If you use the integrated translator, the translator accepts REPLACE statements
and does translate text between pseudo-text delimiters. CICS commands can be
placed between pseudo-text delimiters.

Batch compilation
Separate COBOL programs can be compiled together as one input file. An END
PROGRAM header statement terminates each program and is optional for the last
program in the batch.

Translator action
The translator accepts separate COBOL programs in a single input file, and
interprets END PROGRAM header statements.

Translator options specified as parameters when invoking the translator are in effect
for the whole batch, but can be overridden for a unit of compilation by options
specified in the CBL or PROCESS card that initiates the unit.

The options for a unit of compilation are determined according to the following order
of priority:
| 1. Options fixed as installation non-user-modifiable options.
2. Options specified in the CBL or PROCESS card that initiates the unit.
3. Options specified when the translator is invoked.
4. Default options.

For more information about compilation, see Chapter 9, “Installing application

programs,” on page 99.

Compiler and linkage editor

If you are using batch compilation, you must take some additional action to ensure
that compilation and linkage editing are successful, as follows:
v Include the compiler NAME option as a parameter in the JCL statement that
invokes the compiler or in a CBL statement for each top-level (non-nested)
program. This causes the inclusion of a NAME statement at the end of each
program. See Figure 4 on page 36 for more information.
v Edit the compiler output to add INCLUDE and ORDER statements for the CICS
COBOL stub to each object module. These statements cause the linkage editor
to include the stub at the start of each load module. These statements can be
anywhere in the module, though by convention they are at the start. You may find
it convenient to place them at the end of the module, immediately before each
NAME statement. Figure 5 on page 37 shows the output from Figure 4 after
editing in this way.

Chapter 4. Programming in COBOL 35

For batch compilation you must vary the procedure described in the Chapter 9,
“Installing application programs,” on page 99. The following is a suggested method:
1. Split the supplied cataloged procedure DFHYITVL into two procedures; PROC1
containing the translate and compilation steps (TRN and COB), and PROC2
containing the linkage editor steps COPYLINK and LKED.
2. In PROC1, add the NAME option to the parameters in the EXEC statement for
the compiler, which then looks like this:
//COB EXEC PGM=IGYCRCTL,REGION=..,
// PARM=’....,NAME,....’,

3. In PROC1, change the name and disposition of the compiler output data set
&&LOADSET. At least remove the initial && from the data set name and change
the disposition to CATLG. The SYSLIN statement should then read:
//SYSLIN DD DSN=LOADSET,DISP=(NEW,CATLG),
// UNIT=&WORK,SPACE=(80,(250,100))
4. Run PROC1.

.................
....program a....
.................
NAME PROGA(R)
.................
.................
....program b....
.................
.................
NAME PROGB(R)
.................
....program c....
.................
NAME PROGC(R)

Figure 4. Compiler output before editing

5. Edit the compiler output in the data set LOADSET to add the INCLUDE and
ORDER statements as shown in Figure 5 on page 37. If you use large numbers
of programs in batches, you should write a simple program or REXX EXEC to
insert the ORDER and INCLUDE statements.
6. In PROC2, add a DD statement for the library that includes the CICS stub. The
standard name of this library is CICSTS31.CICS.SDFHLOAD. The INCLUDE
statement for the stub refers to this library by the DD name. In Figure 5 on page
37, it is assumed you have used the DD name SYSLIB ( or concatenated this
library to SYSLIB). The suggested statement is:
//SYSLIB DD DSN=CICSTS31.CICS.SDFHLOAD,
// DISP=SHR
7. In PROC2, replace the SYSLIN concatenation with the single statement:
//SYSLIN DD DSN=LOADSET,
// DISP=(OLD,DELETE)
In this statement it is assumed that you have renamed the compiler output data
set LOADSET.
8. Run PROC2.

36 CICS TS for z/OS: CICS Application Programming Guide

....program a....
.................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGA(R)
.................
.................
....program b....
.................
.................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGB(R)
.................
....program c....
.................
INCLUDE SYSLIB(DFHELII)
ORDER DFHELII
NAME PROGC(R)

Figure 5. Linkage editor input

Note: You are recommended to use the DFHELII stub, but DFHECI is still supplied,
and can be used.

Nested programs
v COBOL programs can contain COBOL programs.
v Contained programs are included immediately before the END PROGRAM
statement of the containing program.
v A contained program can also be a containing program, that is, it can itself
contain other programs.
v Each contained or containing program is terminated by an END PROGRAM
statement.

For an explanation of valid calls to nested programs and of the COMMON attribute
of a nested program, see the Enterprise COBOL for z/OS and OS/390:
Customization Guide.

Integrated CICS translator

When using the integrated CICS translator no action is necessary for nested
programs that contain EXEC CICS commands. The compiler, in effect, declares
DFHEIBLK and DFHCOMMAREA as global in the top-level program. This means
that explicit coding of EIB and COMMAREA on the USING phrases on CALL and
on the PROCEDURE DIVISION are not required, as described in “Translator
action,” for the separate translator.

Existing or modified programs will require appropriate modification for use with the
CICS integrated translator. If modification is difficult the user should continue to use
separate translation and compilation.

Translator action
The CICS translator treats top-level and nested programs differently.

The translator translates a top-level program (a program that is not contained by

any other program) in the normal way, with one addition. The translator assigns the
GLOBAL attribute for all translator-generated variables in the WORKING-STORAGE
SECTION.

Chapter 4. Programming in COBOL 37

The translator translates nested or contained programs in a special way as follows:
v A DATA DIVISION and LINKAGE SECTION are added if they do not already
exist.
v Declarations for DFHEIBLK (EXEC interface block) and DFHCOMMAREA
(communication area) are inserted into the LINKAGE SECTION.
v EXEC CICS commands and CICS built-in functions are translated.
v The PROCEDURE DIVISION header is not modified.
v No translator-generated temporary variables, used for pre-call assignments, are
inserted in the WORKING-STORAGE SECTION.

Recognition of nested programs: The translator interprets that the input source
starts with a top-level program if the first non-comment record is any of the
following:
v IDENTIFICATION DIVISION statement
v CBL card
v PROCESS card

If the first record is none of these, the translator treats the input as part of the
PROCEDURE DIVISION of a nested program. The first CBL or PROCESS card
indicates the start of a top-level program and of a new unit of compilation. Any
IDENTIFICATION DIVISION statements that are found before the first top-level
program indicate the start of a new nested program.

The practical effect of these rules is that nested programs cannot be held in
separate files and translated separately. A top-level program and all its directly- and
indirectly- contained programs constitute a single unit of compilation and should be
submitted together to the translator.

Positioning of comments: The translator treats comments that follow an END

PROGRAM statement as belonging to the next program in the input source.
Comments that precede an IDENTIFICATION DIVISION statement appear in the
listing after the IDENTIFICATION DIVISION statement.

To avoid confusion always place comments:

v After the IDENTIFICATION DIVISION statement that initiates the program to
which they refer
and
v Before the END PROGRAM statement that terminates the program to which they
refer.

Nesting: what the application programmer must do:

1. Submit a top-level containing program and all its directly and indirectly
contained programs as a single unit of compilation.
2. In each nested program that contains EXEC CICS commands, CICS built-in
functions, or references to the EIB or COMMAREA, code DFHEIBLK and
DFHCOMMAREA as the first two parameters of the PROCEDURE DIVISION
header as follows:
PROCEDURE DIVISION USING DFHEIBLK
DFHCOMMAREA PARM1 PARM2 ...
3. In every call to a nested program that contains EXEC CICS commands, CICS
built-in functions, or references to the EIB or COMMAREA, code DFHEIBLK and
DFHCOMMAREA as the first two parameters of the CALL statement as follows:

38 CICS TS for z/OS: CICS Application Programming Guide

CALL ’PROGA’ USING DFHEIBLK
DFHCOMMAREA PARM1 PARM2 ...
4. For every call that forms part of the control hierarchy between the top-level
program and a nested program that contains EXEC CICS commands, CICS
built-in functions, or references to the EIB or COMMAREA, code DFHEIBLK and
DFHCOMMAREA as the first two parameters of the CALL statement. In the
PROCEDURE DIVISION in the called programs code DFHEIBLK and
DFHCOMMAREA. This is necessary to allow addressability to the EIB and
COMMAREA to be passed to programs not directly contained by the top-level
program.
5. If it is not necessary to insert DFHEIBLK and DFHCOMMAREA in the
PROCEDURE DIVISION of a nested program for any of the reasons given
above (2, 3, and 4), calls to that program should not include DFHEIBLK and
COMMAREA in the parameter list of the CALL statement.

An example of a nested program: A unit of compilation (see Figure 6) consists

of a top-level program W and three nested programs, X, Y, and Z, all directly
contained by W.
Program W
During initialization and termination, calls Y and Z to do initial CICS
processing and non-CICS file access. Calls X to do main processing.
Program X
Calls Z for non-CICS file access and Y for CICS processing.
Program Y
Issues CICS commands. Calls Z for non-CICS file access.
Program Z
Accesses files in batch mode.

PROGRAM W

PROGRAM X PROGRAM Y PROGRAM Z

Figure 6. Nested program example—nesting structure

Applying the rules:

v Y must be COMMON to enable a call from X.
v Z must be COMMON to enable calls from X and Y.
v Y issues CICS commands, therefore:
– All calls to Y must have DFHEIBLK and a COMMAREA as the first two
parameters.
– Y’s PROCEDURE DIVISION header must have DFHEIBLK and
DFHCOMMAREA as the first two parameters.
v Though X does not access the EIB or the communication area, it calls Y, which
issues CICS commands. Therefore the call to X must have DFHEIBLK and a
COMMAREA as the first two parameters and X’s PROCEDURE DIVISION
header must have DFHEIBLK and DFHCOMMAREA as its first two parameters.

Chapter 4. Programming in COBOL 39

Figure 7 illustrates the points in “Nesting: what the application programmer must do”
on page 38.

IDENTIFICATION DIVISION.
PROGRAM-ID. W.
.
.
PROCEDURE DIVISION.
.
.
CALL Z.
.
.
CALL Y USING DFHEIBLK COMMAREA.
.
.
CALL X USING DFHEIBLK COMMAREA.
.
.
IDENTIFICATION DIVISION.
PROGRAM-ID. X.
.
.
PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA
.
.
CALL Z.
.
.
CALL Y USING DFHEIBLK COMMAREA.
.
.
END PROGRAM X.
IDENTIFICATION DIVISION.
PROGRAM-ID. Y IS COMMON.
.
.
PROCEDURE DIVISION USING DFHEIBLK DFHCOMMAREA.
.
.
CALL Z.
.
.
EXEC CICS...
.
.
END PROGRAM Y.
IDENTIFICATION DIVISION.
PROGRAM-ID. Z IS COMMON.
.
.
PROCEDURE DIVISION.
.
.
END PROGRAM Z.
END PROGRAM W.

Figure 7. Nested program example: coding

40 CICS TS for z/OS: CICS Application Programming Guide

Reference modification
Reference modification supports a method of referencing a substring of a character
data item by specifying the starting (leftmost) position of the substring in the data
item and, optionally, the length of the substring. The acceptable formats are:
data-name (leftmost-character-position:)
data-name (leftmost-character-position: length)

Data-name can be subscripted or qualified or both. Both leftmost-character-position

and length can be arithmetic expressions. For more information about reference
modification, qualification and subscripting, see the Enterprise COBOL for z/OS and
OS/390 Language Reference, SC27-1408.

Translator action
The translator accepts reference modification wherever the name of a character
variable is permitted in a COBOL program or in an EXEC CICS command.

Note: If a CICS command uses reference modification in defining a data value, it

should include a LENGTH option to specify the data length, unless the
NOLENGTH translator option is used. Otherwise the translator generates a
COBOL call with a LENGTH register reference in the form:
LENGTH OF (reference modification)

This is rejected by the compiler.

Global variables
The GLOBAL variable storage class is supported. A variable defined with the
GLOBAL variable storage class in a top-level program (see “Translator action” on
page 37) can be referred to in any of its nested programs, whether directly or
indirectly contained.

Translator action
The translator accepts the GLOBAL keyword.

Comma and semicolon as delimiters

A separator comma is a comma followed by a space. A separator semicolon is a
semicolon followed by a space. A separator comma or a separator semicolon can
be used as a separator wherever a space alone can be used.

Translator action
The translator accepts the use in COBOL statements of a separator comma or a
separator semicolon wherever a space can be used. For example, the translator
accepts the statement:
IDENTIFICATION; DIVISION

The translator does not support the use of the separator comma and separator
semicolon as delimiters in EXEC CICS commands. The only acceptable word
delimiter in an EXEC CICS command continues to be a space.

Symbolic character definition

Symbolic characters can be defined in the SPECIAL-NAMES paragraph after the
ALPHABET clause. A symbolic character is a program-defined word that represents
a 1-character figurative constant.

Chapter 4. Programming in COBOL 41

Translator action
The translator accepts the use of symbolic characters as specified in the standard.

Note: In general, the compiler does not accept the use of figurative constants and
symbolic characters as arguments in CALL statements. For this reason, do
not use figurative constants or symbolic constants in EXEC CICS
commands, which are converted into CALL statements by the translator.
There is one exception to this restriction: a figurative constant is acceptable
in an EXEC CICS command as an argument to pass a value if it is of the
correct data type. For example, a numeric figurative constant can be used in
the LENGTH option.

Using the OO COBOL translator option

For information about translating your program and preparing it for execution, see
Chapter 8, “Translation and compilation,” on page 67.

You should use the DFHEIBLC copybook, which is a lower-case version of

DFHEIBLK. Apart from case, DFHEIBLC is the same as DFHEIBLK in all other
respects except that the top-level name is 01 dfheiblk. instead of 01 EIBLK. . The
DFHEIBLC copybook can optionally be used in programs translated with the
NOLINKAGE option.

Translator action
OOCOBOL implements the same translator action as COBOL3, as described in
“Using the COBOL2 and COBOL3 translator options” on page 33. In addition:
v The translator considers each class to be a separate unit of compilation.
v The translator does not monitor correct use of syntax. It makes the following
assumptions about a user program:
– Classes and methods are correctly terminated.
– A class encapsulates only methods.
– Methods do not encapsulate anything else.
– A unit of compilation contains either a class or a program.
v The translator rejects any EXEC statements that appear in the PROCEDURE
DIVISION of a class.
v The translator checks that a DATA DIVISION statement and a
WORKING-STORAGE SECTION both exist in a class definition.

42 CICS TS for z/OS: CICS Application Programming Guide

Chapter 5. Programming in C and C++
CICS supports C and C++ programs that have been compiled by the supported
compilers listed in the CICS Release Guide.

This chapter describes:

v “C and C++ programming considerations”
v “XPLink considerations for C and C++ programming” on page 47
v “Passing arguments in C or C++” on page 49
v “Accessing the EIB” on page 50
v “Using Locale support” on page 51
v “Programming in C++” on page 51

C and C++ programming considerations

All the EXEC CICS commands available in COBOL, PL/I, and assembler language
applications are also supported in C and C++ applications, with the exception of
those commands related to nonstructured exception handling, see “Nonstructured
exception handling” for more information.

C++ applications can also use the CICS C++ OO classes to access CICS services,
instead of the EXEC CICS interface. See the CICS C++ OO Class Libraries
manual, for more information about this interface.

Also note the following programming considerations:

Exception handling
nonstructured exception handling
The EXEC CICS commands related to nonstructured exception handling:
v HANDLE ABEND LABEL(label)
v HANDLE AID
v HANDLE CONDITION
v IGNORE CONDITION
v PUSH HANDLE
v POP HANDLE
are not supported in C and C++ applications. Use of these commands is
diagnosed by the translator.
Condition handling
In a C or C++ application, every EXEC CICS command is treated as if it
had the NOHANDLE or RESP option specified. This means that the set of
“system action” transaction abends that result from a condition occurring but
not being handled, is not possible in a C or C++ application. Control always
flows to the next instruction, and it is up to the application to test for a
normal response.
ABEND handling
HANDLE ABEND PROGRAM commands are allowed, but you cannot use
PUSH HANDLE or POP HANDLE.
COMMAREA
The address of the communication area is not passed as an argument to a C or
C++ main function. This means that C and C++ functions must use ADDRESS
COMMAREA to obtain the address of the communications area.

© Copyright IBM Corp. 1989, 2005 43

EIB
The address of the EIB is not passed as an argument to a C or C++ main
function. This means that C and C++ functions must use ADDRESS EIB to
obtain the address of the EIB.
OVERFLOW conditions
If you want any OVERFLOW condition to be indicated in the RESP field on
return from a SEND MAP command with the ACCUM option, you should specify
the NOFLUSH option.
AMODE
All C and C++ language programs running under CICS must be link-edited with
the attributes, AMODE(31), RMODE(ANY). They may reside above the 16MB
line.
Invoking CSP programs
Consequently, when passing parameters to a program produced by the
Cross-System Product (CSP) interactive application generator, you must
either:
v Pass parameters below 16MB, or
v Re-link the CSP load library with AMODE(31).
Working storage
In C and C++, working storage consists of the stack and the heap. The location
of the stack and heap, with respect to the 16MB line, is controlled by the
ANYWHERE and BELOW options on the stack and heap run time options. The
default is that both the stack and heap are located above the 16MB line.
Return value
If you terminate a C or C++ program with an exit() function or the return
statement, instead of a CICS RETURN command, the value passed through the
exit() function is saved in the EIBRESP2 field of the EIB on return from the
program.

# Note: If a program uses DPL to link to a program in another CICS region,

# EIBRESP2 values from the remote region are not returned to the
# program doing the DPL.
Sample programs
A set of sample application programs is provided in Table 1 to show how EXEC
CICS commands can be used in a program written in the C or C++ language.
Table 1. Sample programs
Sample program Map set Map source Transaction ID
DFH$DMNU Operator DFH$DGA DFH$DMA DMNU
instruction (3270)
DFH$DALL Update (3270) DFH$DGB DFH$DMB DINQ, DADD, DUPD
DFH$DBRW Browse (3270) DFH$DGC DFH$DMC DBRW
DFH$DREN Order entry DFH$DGK DFH$DMK DORD
(3270)
DFH$DCOM Order entry DFH$DGL DFH$DML DORQ
queue print (3270)
DFH$DREP Report (3270) DFH$DGD DFH$DMD DREP

The transaction and program definitions are provided in group DFH$DFLA in

the CSD and should be installed using the command:

44 CICS TS for z/OS: CICS Application Programming Guide

CEDA INSTALL GROUP(DFH$DFLA)

The following record description files are provided as C or C++ language

header files:
DFH$DFIL—FILEA record descriptor
DFH$DL86—L860 record descriptor
Data declarations
The following data declarations are provided by CICS for C and C++:
v Execution interface block definitions (EIB)
v BMS screen attributes definitions: C and C++ versions of the DFHBMSCA,
DFHMSRCA, and DFHAID files are supplied by CICS, and may be included
by the application programmer when using BMS.
v DL/I support: a C language version of DFHDIB is included by the DLI
translator if the translator option has been specified. (You have to include
DLIUIB if the CALL DLI interface is used.)

The EIB declarations are enclosed in #ifndef and #endif lines, and are included
in all translated files. The C or C++ compiler ignores duplicated declarations.
The inserted code contains definitions of all the fields in the EIB, coded in C
and C++.
Fetch function
Language Environment-conforming programs support the fetch() and release()
functions. Modules to be fetched must be defined as PROGRAM resources to
CICS, either explicitly or implicitly through autoinstall.
System function
CICS does not support the system() function, but two CICS commands, LINK
and XCTL, provide equivalent function.
Macros
C and C++ do not support the use of CICS commands in macros.
Clock function
The clock() function returns a value (time_t) of -1.
Locale functions
All locale functions are supported for locales that have been defined in the
CSD. CSD definitions for the IBM-supplied locales are provided in member
CEECCSD of the SCEESAMP library. The setlocale() function returns NULL if
the locale is not defined.
Debugging functions
The dump functions csnap(), cdump(), and ctrace() are supported. The output is
sent to the CESE transient data queue. The dump cannot be written if the
queue does not have a sufficient record length (LRECL). An LRECL of at least
161 is recommended.
iscics function
If you are adapting an existing program or writing a new program that is
designed to run outside CICS as well as under CICS, the iscics() function may
prove useful. It returns a non-zero value if your program is currently running
under CICS, or zero otherwise. This function is an extension to the C library.
Restrictions
The following lists describe some of the restrictions that exist with C or C++

Chapter 5. Programming in C and C++ 45

programs using Language Environment under CICS. You should check the
relevant language guide for more specific details about those that apply to your
installation:
v CICS does not support extended precision floating point.
v C and C++ languages do not support packed decimal data. The application
has access to packed decimal data using the character string data type. No
C or C++ standard library functions are available to perform arithmetic on this
data, but you may write your own.
v You can easily use HOURS, MINUTES, and SECONDS options. You may
define expiration times using TIME or INTERVAL options if you provide
functions to handle them in your application.
v You can enter all CICS keywords in mixed case, except for CICS keywords
on #pragma directives, which must be in upper case only.
v If you do not specify the LENGTH option on commands that support
LENGTH (for example, READ, READNEXT, READPREV, and WRITE
commands), the translator does not supply a default value. In effect,
NOLENGTH is implicit for C programs.
v All native C and C++ functions are allowed in the source program, but the
following functions are not recommended. Some are not executable and
result in return codes or pointers indicating that the function has failed. Some
may work but impact the performance or execution of CICS.
– CDUMP
– CSNAP
– CTEST
– CTRACE
– CLOCK
– CTDLI
– SVC99
– SYSTEM
– SETLOCALE
For further information see the relevant User’s Guide. Native C or C++
functions are implemented in the C or C++ runtime library.
v Native C or C++ file operations operate only on files opened with
type=memory specified. I/O to CICS-supported access methods must use the
CICS API.
v The string handling functions in the C or C++ standard library use a null
character as an end-of-string marker. Because CICS does not recognize a
null as an end-of-string marker, you must take care when using C or C++
functions, for example strcmp, to operate on CICS data areas.
v Two arguments, argc and argv, are normally passed to a C or C++ main
function. argc denotes how many variables have been passed; argv is an
array of zero-terminated variable strings. In CICS, the value of argc is 1,
argv[0] is the transaction ID, and argv[1] is NULL.
v Where CICS expects a fixed-length character string such as a program
name, map name, or queue name, you must pad the literal with blanks up to
the required length if it is shorter than expected.
For EXEC DLI commands, the SEGMENT name is padded by the translator
if a literal is passed.
v Take care not to use field names, which, though acceptable to the assembler,
cause the C or C++ compiler to abend. These include $, #, and @.

46 CICS TS for z/OS: CICS Application Programming Guide

| XPLink considerations for C and C++ programming
| Extra Performance Linkage, (from here on it is abbreviated to XPLink), is a z/OS
| feature which provides high performance subroutine call and return mechanisms.
| This results in short and highly optimized execution path lengths.

| Object Oriented programming is built upon the concept of sending ’messages’ to

| objects which result in that object performing some actions. The message sending
| activity is implemented as a subroutine invocation. Subroutines, known as member
| functions in C++ terminology, are normally small pieces of code. The characteristic
| execution flow of a typical C++ program is of many subroutine invocations to small
| pieces of code. Programs of this nature benefit from the XPLink optimization
| technology.

| MVS has a standard subroutine calling convention which can be traced back to the
| early days of System/360. This convention was optimized for an environment in
| which subroutines were more complex, there were relatively few of them, and they
| were invoked relatively infrequently. Object oriented programming conventions have
| changed this. Subroutines have become simpler but they are numerous, and the
| frequency of subroutine invocations has increased by orders of magnitude. This
| change in the size, numbers, and usage pattern, of subroutines made it desirable
| that the system overhead involved be optimized. XPLink is the result of this
| optimization.
|

| PLEASE NOTE!
| For z/OS 1.4 and above, and CICS TS 3.1 and above, the advice here that
| you CAN use the XPLINK compiler option with CICS application programs,
| overrides advice in z/OS and Language Environment manuals to the contrary.

| z/OS and Language Environment manuals for C and C++ advise you that the
| XPLINK compiler option is not available to CICS application programs,
| because that used to be the case. Although these manuals are now being
| changed, you may be working with a copy of one of these manuals produced
| before this change.
|
|

| The following topics cover:

| v “XPLink, and the X8 and X9 TCBs”
| v “Writing C and C++ programs, which are to be compiled with the XPLINK option,
| for the CICS environment” on page 48
| v “Passing control between XPLink and non-XPLink objects” on page 48
| v “Changing CICS definitions to obtain CICS support for objects compiled with the
| XPLINK option” on page 48
| v “Global User exits and XPLink” on page 48

| XPLink, and the X8 and X9 TCBs

| CICS provides support for C and C++ programs compiled with the XPLINK option
| by using the multiple TCB feature in the CICS Open Transaction Environment
| (OTE) technology. X8 and X9 mode TCBs are defined to support XPLink tasks in
| CICS key and USER key. Each instance of an XPLink program uses one X8 or X9
| TCB.

| To use XPLink, your C or C++ application code must be re-entrant and threadsafe.
| The same code instance can be executing on more than one MVS TCB and,

Chapter 5. Programming in C and C++ 47

| without threadsafe mechanisms to protect shared resources, the execution behavior
| of application code is unpredictable. This cannot be too strongly emphasized.

| Writing C and C++ programs, which are to be compiled with the

| XPLINK option, for the CICS environment
| The application developer is expected to do the following to take advantage of
| CICS XPLink support;
| v Develop the code, strictly adhering to threadsafe programming principles and
| techniques
| v Compile the C or C++ program with the XPLINK option set on
| v Indicate in the PROGRAM resource definition that the program is threadsafe
| v Consider the use of CICSVAR in CEEUOPT or in #pragma, (see note 3 in
| “Defining runtime options for Language Environment” on page 15 for details).
| All programs using CICS XPLink support must be re-entrant and threadsafe. Only
| the application developer can guarantee that the code for a particular application
| satisfies these requirements.

| Passing control between XPLink and non-XPLink objects

| Each transfer of control from XPLink objects to non-XPLink objects, or the reverse,
| causes a switch between the QR TCB and an open TCB, (either an X8 or an X9
| TCB). In performance terms, TCB switching is costly, you must take this
| performance overhead into account.

| An XPLink object can invoke a non-XPLink object using either the EXEC CICS
| interface or the Language Environment interface.

| A non-XPLink object can only invoke an XPLink object using the EXEC CICS
| interface. Use of the Language Environment interface for such invocations is not
| supported.

| Changing CICS definitions to obtain CICS support for objects

| compiled with the XPLINK option
| CICS support for programs compiled with the XPLINK option requires only that you
| show in the PROGRAM resource definition that the program is threadsafe. This
| indication, and the XPLink “signature” in the load module, are the only things
| required to put the task on an X8 or X9 TCB.

| In the selection of a suitable TCB for a particular program, XPLink takes

| precedence over the existence of the OPENAPI value for the API attribute on the
| PROGRAM resource definition.

| .

| Global User exits and XPLink

| XPCFTCH
| When the exit XPCFTCH is invoked for a C or C++ program that was
| compiled with the XPLINK option, a flag is set indicating that any modified
| entry point address, if specified by the exit, will be ignored.
| XPCTA
| When the exit XPCTA is invoked for a C or C++ program that was compiled
| with the XPLINK option, a flag is set indicating that a resume address, if
| specified by the exit, will be ignored.

| Other Global User exits are unaffected by XPLink support.

48 CICS TS for z/OS: CICS Application Programming Guide

Passing arguments in C or C++
Arguments in C and C++ language are copied to the program stack at run time,
where they are read by the function. These arguments can either be values in their
own right, or they can be pointers to areas of memory that contain the data being
passed. Passing a pointer is also known as passing a value by reference.

Other languages, such as COBOL and PL/I, usually pass their arguments by
reference, which means that the compiler passes a list of addresses pointing to the
arguments to be passed. This is the call interface supported by CICS. To pass an
argument by reference, you prefix the variable name with &, unless it is already a
pointer, as in the case when an array is being passed.

As part of the build process, the compiler may convert arguments from one data
type to another. For example, an argument of type char may be converted to type
short or type long.

When you send values from a C or C++ program to CICS, the translator takes the
necessary action to generate code that results in an argument list of the correct
format being passed to CICS. The translator does not always have enough
information to enable it to do this, but in general, if the argument is a
single-character or halfword variable, the translator makes a precall assignment to a
variable of the correct data type and passes the address of this temporary variable
in the call.

When you receive data from CICS, the translator prefixes the receiving variable
name with &, which causes the C or C++ compiler to pass it values by reference
rather than by value (with the exception of a character string name, which is left
unchanged). Without the addition of &, the compiler would copy the receiving
variable and then pass the address of the copy to CICS. Any promotion occurring
during this copying could result in data returned by CICS being lost.

Table 2 shows the rules that apply when passing values as arguments in EXEC
CICS commands.
Table 2. Rules for passing values as arguments in EXEC CICS commands
Data type Usage Coding the argument
Character literal Data-value (Sender) The user must specify the character literal
directly. The translator takes care of any
required indirection.
Character variable Data-area (Receiver) The user must specify a pointer to the
(char) variable, possibly by prefixing the variable
name with &.
Character variable Data-value (Sender) The user must specify the character variable
(char) directly. The translator takes care of any
required indirection.
Character string literal Name (Sender) The user can either code the string directly
as a literal string or use a pointer which
points to the first character of the string.
Character string Data-area (Receiver) Whether receiving or sending, the argument
variable Name (Sender) should be the name of the character array
containing the string—the address of the
first element of the array.

Chapter 5. Programming in C and C++ 49

Table 2. Rules for passing values as arguments in EXEC CICS commands (continued)
Data type Usage Coding the argument
Integer variable Data-area (Receiver) The user must specify a pointer to the
(short, long, or int) variable, possibly by prefixing the variable
name with &.
Integer variable Data-value (Sender) The user must specify the name of the
(short, long, or int) variable. The translator looks after any
indirection that is required.
Integer constant Data-value (Sender) The user must specify the integer constant
(short, long, or int) directly. The translator takes care of any
required indirection.
Structure or union Data-area (Sender) The user must code the address of the start
Data-area (Receiver) of the structure or union, possibly by
prefixing its name with &.
Array (of anything) Data-area (Receiver) The translator does nothing. You must code
Data-value (Sender) the address of the first member of the array.
This is normally done simply by coding the
name of the array, which the compiler
interprets as the address of the first
member.
Pointer (to anything) Ptr-ref (Receiver) Whether receiving or sending, the argument
Data-area (Sender) should be the name of the variable that
denotes the address of interest. The
translator takes care of the extra level of
indirection that is necessary to allow CICS
to update the pointer.
Note: Receiver is where data is being received from CICS; Sender is where data is being
passed to CICS.

Accessing the EIB

The address of the exec interface block (EIB) is not passed as an argument to a C
or C++ main function. This means that C and C++ functions must use the
ADDRESS EIB command to obtain the address of the EIB.

Addressability is achieved by using the command:

EXEC CICS ADDRESS EIB(dfheiptr);

or by passing the EIB address or particular fields therein as arguments to the CALL
statement that invokes the external procedure.

If access to the EIB is required, an ADDRESS EIB command is required at the

beginning of each program.

Naming EIB fields

Within a C or C++ application program, fields in the EIB are referred to in lower
case and fully qualified as, for example, “dfheiptr->eibtrnid”.

Data types in EIB fields

The following mapping of data types is used:
v Halfword binary integers are defined as “short int”
v Fullword binary integers are defined as “long int”
v Single-character fields are defined as “unsigned char”

50 CICS TS for z/OS: CICS Application Programming Guide

v Character strings are defined as “unsigned char” arrays

Using Locale support

The translator, by default, assumes that programs written in the C language have
been edited with the codeset IBM-1047, also known as the Coded Character Set for
Latin 1/Open Systems.

The codeset may also be specified in a pragma filetag compiler directive at the
start of the application program. The CICS translator scans for the presence of this
directive, but currently CICS provides support only for the default IBM-1047 and for
the codeset for Germany, IBM-273

For example, if the program has been prepared with an editor using the codeset
specific to Germany, it should begin with the following directive:
??=pragma filetag ("IBM-273")

The presence of the pragma filetag implies that the program is compiled with the
IBM C for MVS/ESA compiler.

A comparison of some of the code-points and characters is shown below:

Table 3. C language codesets
Character IBM-1047 IBM-273
\ backslash E0 EC
} right brace D0 DC
{ left brace C0 43
# hash 7B 7B

Programming in C++
C++ supports object-oriented programming and you can use this language in the
same way as you would use the C language. You must specify that the translator is
to translate C++ using the CPP option.

C++ programs must also be defined with the LANGUAGE(LE370) option. See
Chapter 3, “Language Environment,” on page 9 for information about this
environment.

Restrictions
C++ uses ‘//’ for single line comments. Do not put a comment in the middle of an
EXEC CICS command. For instance, this example does not work:
EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen) // Send error message to screen
RESP(rcode)
RESP2(rcode2);

These examples are valid:

EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen)
RESP(rcode)
RESP2(rcode2); //Send error message to screen

Chapter 5. Programming in C and C++ 51

EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen) /* Send error message to screen */
RESP(rcode)
RESP2(rcode2);

52 CICS TS for z/OS: CICS Application Programming Guide

Chapter 6. Programming in PL/I
| CICS supports PL/I programs that have been compiled by the supported compilers
| listed in the CICS Release Guide. All PL/I programs are executed under the runtime
| support provided by Language Environment.

Runtime options, if needed, can be specified in a plixopt character string. See

“Defining runtime options for Language Environment” on page 15 and the Language
Environment Customization manual or information about customizing runtime
options.

If you are converting a program that was previously compiled with a non-Language
Environment conforming compiler, you must ensure that neither NOSTAE nor
NOSPIE is specified in a plixopt string, because this will cause Language
Environment to set TRAP (OFF). TRAP (ON) must be in effect for applications to
run successfully.

If OPTIONS(MAIN) is specified in an application program, that program can be the

first program of a transaction, or control can be passed to it by means of a LINK or
XCTL command.

In application programs where OPTIONS(MAIN) is not specified, it cannot be the

first program in a transaction, nor can it have control passed to it by an LINK or
XCTL command, but it can be link-edited to a main program.

This chapter describes:

v “PL/I programming restrictions”
v “Language Environment considerations for PL/I applications” on page 54

PL/I programming restrictions

The following restrictions apply to a PL/I program that is to be used as a CICS
application program.
v You cannot use the multitasking built-in functions:
COMPLETION
PRIORITY
STATUS
v You cannot use the multitasking options:
EVENT
PRIORITY
TASK
v You should not use the PL/I statements:
CLOSE DELAY
DELETE DISPLAY
EXIT GET
HALT LOCATE
OPEN PUT
READ REWRITE
STOP WRITE
UNLOCK
The following commands are supported :
FETCH
RELEASE

© Copyright IBM Corp. 1989, 2005 53

You are provided with EXEC CICS commands for the storage and retrieval of
data, and for communication with terminals. (However, you can use CLOSE,
PUT, and OPEN, for SYSPRINT.)
v You cannot use PL/I Sort/Merge.
v You cannot use static storage (except for read-only data).
v If you declare a variable with the STATIC attribute and EXTERNAL attribute you
should also include the INITIAL attribute. If you do not, such a declaration
generates a common CSECT that cannot be handled by CICS.
v You cannot use the PL/I 48-character set option in EXEC CICS statements.
v Do not define variables or structures with variable names that are the same as
variable names generated by the translator. These begin with DFH. Care must be
taken with the LIKE keyword to avoid implicitly generating such variable names.
v All PROCEDURE statements must be in upper case, with the exception of the
PROCEDURE name, which may be in lower case.
v The suboptions of the XOPTS option of the *PROCESS statement must be in
upper case.
v If a CICS command uses the SUBSTR built-in function in defining a data value, it
should include a LENGTH option to specify the data length, unless the translator
option NOLENGTH is specified. If it does not, the translator generates a PL/I call
including an invocation of the CSTG built-in function in the form:
CSTG(SUBSTR(..,..,..))
This is rejected by the compiler.

Language Environment considerations for PL/I applications

The advice and restrictions listed in Chapter 6, “Programming in PL/I,” on page 53
apply to PL/I programs running under Language Environment.

Language Environment-conforming PL/I programs can CALL a program that

appears in a FETCH or RELEASE statement and can RELEASE it subsequently.

There are some restrictions on the PL/I for MVS & VM statements that can be used
in a fetched procedure. These restrictions are described in PL/I MVS & VM
Language Reference.. Many of the restrictions have been removed with VisualAge
PL/I. See the VisualAge PL/I for OS/390 Compiler and Run-Time Migration Guide.

To enable a PL/I procedure to be fetched, code the option FETCHABLE in the

OPTIONS on the PROCEDURE statement. This option indicates that the procedure
can only be invoked dynamically. An OPTIONS(MAIN) procedure cannot be
fetched; FETCHABLE and MAIN are mutually exclusive options. Treat the
FETCHABLE procedure like a normal CICS program: that is, link-edited with any
required subroutines, placed in the CICS application program library, defined, and
installed as a program, either in the CSD or using program autoinstall.

No special considerations apply to the use of FETCH when both the fetching and
the fetched programs have the same AMODE attribute. Language Environment,
however, also supports the fetching of a load module that has an AMODE attribute
different to the program issuing the FETCH. In this case, Language Environment
performs the AMODE switch, and the following constraints apply:
v If any fetched module is to execute in 24-bit addressing mode, the fetching
module must have the RMODE(24) attribute regardless of its AMODE attribute.
v Any variables passed to a fetched routine must be addressable in the AMODE of
the fetched procedure.

54 CICS TS for z/OS: CICS Application Programming Guide

Communicating between modules compiled with different compilers
You can link-edit non-Language Environment-conforming PL/I subroutines with
a Language Environment-conforming main program. Static calls are supported
from any version of PL/I, but dynamic calls are supported only from Language
Environment-conforming procedures. Called subroutines can issue CICS
commands if the address of the EIB is available in the subroutine. You can
achieve this either by passing the address of the EIB to the subroutine, or by
coding EXEC CICS ADDRESS EIB(DFHEIPTR) in the subroutine before issuing
any other CICS commands.
Entry point
CEESTART is the only entry point for PL/I applications running under Language
Environment. This entry point is set for programs compiled using Language
Environment-conforming compilers. You can re-link object modules produced by
non-Language Environment-conforming compilers for running under Language
Environment by using the following linkage-editor statements:
INCLUDE SYSLIB(CEESTART)
INCLUDE SYSLIB(CEESG010)
INCLUDE SYSLIB(DFHELII)
REPLACE PLISTART
CHANGE PLIMAIN(CEEMAIN)
INCLUDE mainprog
INCLUDE subprog1
.......
.......
ORDER CEESTART
ENTRY CEESTART
NAME progname(R)

The INCLUDE statement for the object modules must come immediately after
the CHANGE statement and there is also a requirement under Language
Environment that the main program must be included before any subroutines.
(This requirement did not exist for modules produced by non-conforming
compilers.) For Enterprise PL/I programs that are compiled with
OPTIONS(FETCHABLE), the binder ENTRY statement must be the name of the
PROCEDURE.
Re-link utility for PL/I
If you have only the load module for a CICS program compiled by a
non-conforming compiler, there is a file of linkage editor input, IBMWRLKC,
specifically for CICS programs, located in the sample library SCEESAMP, to
replace OS PL/I library routines in a non-conforming executable program with
Language Environment routines. For more information about using IBMWRLKC,
see the PL/I MVS & VM V1R1.1 Compiler & Runtime Migration Guide.
Abend codes
If a CICS PL/I program abends under Language Environment , your CICS
abend handlers are given a Language Environment abend code, rather than a
PL/I abend code. To avoid changing your programs, you can modify the sample
user condition handler, CEEWUCHA, supplied by Language Environment in the
SCEESAMP library. This user condition handler can be made to return PL/I
abend codes instead of the Language Environment codes. Use the USRHDLR
runtime option to register it to do this. For details of this option see the z/OS
Language Environment Programming Guide.

Chapter 6. Programming in PL/I 55

56 CICS TS for z/OS: CICS Application Programming Guide
Chapter 7. Programming in Assembler
| CICS supports assembler programs that have been compiled by the supported
| compilers listed in the CICS Release Guide. All assembler programs are executed
| under the runtime support provided by Language Environment.

Note the following Assembler language programming considerations:

Language restrictions
1. The following instructions cannot be used in an assembler language
program that is to be used as a CICS application program:
COM Identify blank common control section.
ICTL Input format control.
OPSYN Equate operation code.

| 2. The following additional restrictions apply if an assembler language program

| is to be translated with the LEASM option, see “LEASM” on page 77.
| v Register 2 cannot be used as a code base register.
| v Register 12 is reserved by Language Environment to point to the
| Language Environment common anchor area (CAA) and so cannot be
| used at all by the program without being saved and restored as
| appropriate.
| v Register 13 must be used as the one and only working storage base
| register.
| v The program cannot be a Global User Exit program (GLUE) or a
| Task-Related User Exit program (TRUE).
| v The program must not use, or depend on, any AMODE(24) code.
BAKR
When using BAKR instructions (branch and stack) to provide linkage between
assembler programs, take care that the linked-to program does not issue EXEC
CICS requests. If CICS receives control and performs a task switch before the
linked-to program returns by a PR instruction (program return), then other tasks
might be dispatched and issue further BAKR / PR calls. These modify the
linkage-stack and result in the wrong environment being restored when the
original task issues its PR instruction.
Working storage
Working storage is allocated either above or below the 16MB line, according to
the value of the DATALOCATION parameter on the PROGRAM definition in the
CSD.
HANDLE ABEND LABEL
CICS does not allow the use of HANDLE ABEND LABEL in Assembler
programs that do not use DFHEIENT and DFHEIRET. Assembler programs that
use the Language Environment stub CEESTART should either use HANDLE
ABEND PROGRAM or a Language Environment service such as CEEHDLR.
31–bit addressing
The following restrictions apply to an assembler language application program
executing in 31-bit mode:

© Copyright IBM Corp. 1989, 2005 57

v The interval control command WAIT EVENT is not supported when the
associated event control block (ECB) resides above the 16MB line. Instead,
you can use the task control command WAIT EXTERNAL with the ECBLIST
option.
v The COMMAREA option is restricted in a mixed addressing mode transaction
environment. For a discussion of the restriction, see “Using mixed addressing
modes” on page 567.
MVS restrictions
The following restrictions apply to an assembler language application program
that uses access registers to exploit the extended addressability of ESA/370
processors:
v You must be in primary addressing mode when invoking any CICS service.
The primary address-space must be the home address-space. All parameters
passed to CICS must reside in the primary address-space.
v CICS does not always preserve access registers. You must save them
before you invoke a CICS service, and restore them before using the access
registers again.

For more guidance information about using access registers, see the z/OS:
MVS Programming: Extended Addressability Guide.

Language Environment considerations for Assembler applications

Like HLL programs, assembler programs are classified as either conforming or
non-conforming with respect to Language Environment. For assembler programs,
conformance depends on the linkage and register conventions observed, rather
than the assembler used. By definition, a Language Environment-conforming
assembler routine is defined as one coded using the CEEENTRY and associated
Language Environment macros.

Conformance governs the use of assembler programs by call from an HLL program.
Both conforming and non-conforming assembler subroutines may be called either
statically or dynamically from C or C++, COBOL or PL/I. However, there are
differences in register conventions and other requirements for the two types. These
are described below. Rules for mixing languages, including assembler, are
discussed in “Mixing languages in Language Environment” on page 13.
| Conforming MAIN programs
| If you are coding a new assembler MAIN program that you want to conform to
| the Language Environment interface or if your assembler routine calls
| Language Environment services, observe the following:
| v Use the macros provided by Language Environment. For a list of these
| macros, see the z/OS Language Environment Programming Guide.
| v Ensure that the CEEENTRY macro contains the option MAIN=YES. (
| MAIN=YES is the default).
| v Translate your assembler routine with *ASM XOPTS( LEASM) or, if it
| contains CICS commands, with *ASM XOPTS( LEASM NOPROLOG
| NOEPILOG).
| Conforming sub-routines programs
| If you are coding a new assembler sub-routine that you want to conform to the
| Language Environment interface or if your assembler routine calls Language
| Environment services, observe the following:

58 CICS TS for z/OS: CICS Application Programming Guide

| v Use the macros provided by Language Environment. For a list of these
| macros, see the z/OS Language Environment Programming Guide.
| v Ensure that the CEEENTRY macro contains the option MAIN=NO. (
| MAIN=YES is the default).
| v Translate your assembler routine with *ASM XOPTS(NOPROLOG
| NOEPILOG) if it contains CICS commands.
| v Ensure that the CEEENTRY macro contains the option NAB=NO if your
| routine is invoked by a static call from VS COBOL II. (NAB is Next Available
| Byte (of storage). NAB=NO means that this field may not be available, so the
| CEEENTRY macro generates code to find the available storage.)
| All conforming routines
To communicate properly with assembler routines, observe certain register
conventions on entry to the assembler routine, while it is running, and on exit
from the assembler routine.
Entry
On entry into a Language Environment-conforming assembler subroutine,
these registers must contain the following values when NAB=YES is
specified on the CEEENTRY macro:
R0 Reserved
R1 Address of the parameter list, or zero
R12 Common anchor area (CAA) address
R13 Caller’s dynamic storage area (DSA)
R14 Return address
R15 Entry point address

Language Environment-conforming HLLs generate code that follows these

register conventions, and the supplied macros do the same when you use
them to write your Language Environment-conforming assembler routine.
On entry to an assembler routine, CEEENTRY saves the caller’s registers
(R14 through R12) in the DSA provided by the caller. It allocates a new
DSA and sets the NAB field correctly in this new DSA. The first half word of
the new DSA is set to binary zero and the back chain in the second word is
set to point to the caller’s DSA.
While the subroutine is running
R13 must point to the routine’s DSA at all times while the Language
Environment-conforming assembler routine is running.
At any point in your code where you CALL another program, R12 must
contain the common anchor area (CAA) address, except in the following
cases:
v When calling a COBOL program
v When calling an assembler routine that is not Language
Environment-conforming
v When calling a Language Environment-conforming assembler routine that
specifies NAB=NO on the CEEENTRY macro
Exit

Chapter 7. Programming in Assembler 59

On exit from a Language Environment-conforming assembler routine, R0,
R1, R14, and R15 are undefined. All the other registers must have the
contents they had upon entry.
The CEEENTRY macro automatically sets a module to AMODE (ANY) and
RMODE (ANY). If you are converting an existing assembler routine to be
Language Environment-conforming and the routine contains data
management macros coded using 24-bit addressing mode, then you should
change the macros to use 31-bit mode. If it is not possible to change all the
modules making up a program to use 31-bit addressing mode, and if none
of the modules explicitly sets RMODE (24), then you should set the
program to be RMODE (24) during the link-edit process.
Non-conforming routines
Observe the following conventions when running non-Language
Environment-conforming subroutines under Language Environment:
v R13 must contain the address of the executing routine’s register save area.
v The first two bytes of the register save area must be binary zeros.
v The register save area back chain must be set to a valid 31-bit address (the
high-order byte must be zero if it is a 24-bit address).
If your assembler routine relies on C/C++, COBOL, or PL/I control blocks (for
example, a routine that tests flags or switches in these control blocks), check
that these control blocks have not changed under Language Environment . For
more information, see the appropriate Language Environment migration guide.
Non-conforming routines cannot use Language Environment callable services.

Note: CICS does not allow the use of HANDLE ABEND LABEL in Assembler
programs that do not use DFHEIENT and DFHEIRET. Assembler programs
that use the Language Environment stub CEESTART should either use
HANDLE ABEND PROGRAM or a Language Environment service such as
CEEHDLR. See “Using Language Environment Abend-handling” on page 11
for information about CEEHDLR.

For more information or for explanations of the terms used in this section see the
chapter on ″Assembler Considerations″ in the z/OS Language Environment
Programming Guide.

Calling Assembler programs

Assembler language application programs that contain commands can have their
own RDO program definition. Such programs can be invoked by COBOL, C or C++,
PL/I, or assembler language application programs using LINK or XCTL commands
(see Chapter 45, “Program control,” on page 561). However, because programs that
contain commands are invoked by a system standard call, they can also be invoked
by a COBOL, C, C++, or PL/I CALL statement or by an assembler language CALL
macro.

A single CICS application program, as defined in an RDO program definition, may

consist of separate CSECTs compiled or assembled separately, but linked together.

An assembler language application program that contains commands can be linked

with other assembler language programs, or with programs written in one or more
high-level languages (COBOL, C, C++, or PL/I). For details of mixing languages in
an application load module, refer to z/OS Language Environment Writing
Interlanguage Communications Applications.

60 CICS TS for z/OS: CICS Application Programming Guide

If an assembler language program (that is link edited separately) contains
command-level calls, and is called from a high-level language program, it requires
its own CICS interface stub. If the assembler program is link edited with the
high-level language program that calls it, then the assembler program does not
need a stub, but if you provide one, the message MSGIEW024I is issued, but this
can be ignored.

Because assembler language application programs containing commands are

always passed the parameters EIB and COMMAREA when invoked, the CALL
statement or macro must pass these two parameters followed, optionally, by other
parameters.

For example, the PL/I program in file PLITEST PLI calls the assembler language
program ASMPROG, which is in file ASMTEST ASSEMBLE. The PL/I program
passes three parameters to the assembler language program, the EIB, the
COMMAREA, and a message string.

PLIPROG:PROC OPTIONS(MAIN);
DCL ASMPROG ENTRY EXTERNAL;
DCL COMA CHAR(20), MSG CHAR(14) INIT(’HELLO FROM PLI’);
CALL ASMPROG(DFHEIBLK,COMA,MSG);
EXEC CICS RETURN;
END;

Figure 8. PLITEST PLI

The assembler language program performs an EXEC CICS SEND TEXT command,
which displays the message string passed from the PL/I program.

DFHEISTG DSECT
MSG DS CL14
MYRESP DS F
ASMPROG CSECT
L 5,8(1)
L 5,0(5)
MVC MSG,0(5)
EXEC CICS SEND TEXT FROM(MSG) LENGTH(14) RESP(MYRESP)
END

Figure 9. ASMTEST ASSEMBLE

You can use JCL procedures supplied by CICS to compile and link the application,
as follows:
1. Assemble and link ASMTEST using the DFHEITAL procedure:
//ASMPROG EXEC DFHEITAL
//TRN.SYSIN DD *
.... program source ...
/*
//LKED.SYSIN DD *
NAME ASMTEST(R)
/*
2. Compile and link PLITEST using the DFHYITPL procedure, and provide linkage
editor control statements that include the ASMTEST load module created by the
DFHEITAL procedure:
//PLIPROG EXEC DFHYITPL
//TRN.SYSIN DD *
.... program source ...
/*

Chapter 7. Programming in Assembler 61

//LKED.SYSIN DD *
INCLUDE SYSLIB(ASMTEST)
ENTRY CEESTART
NAME PLITEST(R)
/*

Note: Step 2 assumes that the ASMTEST load module created by DFHEITAL was
stored in a library included in the SYSLIB dataset concatenation.

The load module created by the DFHYITPL procedure includes both the DFHEAI
stub (included by DFHEITAL) and the DFHELII stub (included by DFHYITPL). This
causes the linkage editor or binder program to issue a warning message because
both stubs contain an entry point named DFHEII. This message can be ignored.

If you are writing your own JCL, you only need to include the DFHELII stub,
because this contains the entry points needed for all languages.

An assembler language application program that is called by another begins with

the DFHEIENT macro and ends with the DFHEIRET macro. The CICS translator
inserts these for you, so if the program contains EXEC CICS commands and is to
be passed to the translator, as in the example just given, you do not need to code
these macros.

62 CICS TS for z/OS: CICS Application Programming Guide

Part 2. Preparing applications to run
Chapter 8. Translation and compilation . . . . . . . . . . . . . . . 67
The integrated CICS translator . . . . . . . . . . . . . . . . . . . 67
Using the integrated CICS translator . . . . . . . . . . . . . . . . 68
Specifying CICS translator options . . . . . . . . . . . . . . . . . 68
The translation process . . . . . . . . . . . . . . . . . . . . . . 69
The CICS-supplied translators . . . . . . . . . . . . . . . . . . . 72
Dynamic invocation of the separate translator . . . . . . . . . . . . 72
Translator option list . . . . . . . . . . . . . . . . . . . . . 72
Data definition (DD name) list . . . . . . . . . . . . . . . . . 72
Using a CICS translator . . . . . . . . . . . . . . . . . . . . . 73
Defining translator options . . . . . . . . . . . . . . . . . . . . . 74
Translator options . . . . . . . . . . . . . . . . . . . . . . . 75
APOST . . . . . . . . . . . . . . . . . . . . . . . . . . 75
CBLCARD . . . . . . . . . . . . . . . . . . . . . . . . 75
CICS . . . . . . . . . . . . . . . . . . . . . . . . . . 75
# COBOL2 . . . . . . . . . . . . . . . . . . . . . . . . . 75
COBOL3 . . . . . . . . . . . . . . . . . . . . . . . . . 75
CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
CPSM . . . . . . . . . . . . . . . . . . . . . . . . . . 76
DBCS . . . . . . . . . . . . . . . . . . . . . . . . . . 76
DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . 76
DLI . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
EDF . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
EPILOG . . . . . . . . . . . . . . . . . . . . . . . . . 76
EXCI . . . . . . . . . . . . . . . . . . . . . . . . . . 76
FEPI . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
FLAG (I, W, E, or S) . . . . . . . . . . . . . . . . . . . . . 77
GDS . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
GRAPHIC . . . . . . . . . . . . . . . . . . . . . . . . . 77
| LEASM . . . . . . . . . . . . . . . . . . . . . . . . . . 77
LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . 78
LINECOUNT(n) . . . . . . . . . . . . . . . . . . . . . . . 78
LINKAGE . . . . . . . . . . . . . . . . . . . . . . . . . 78
MARGINS(m,n[,c]) . . . . . . . . . . . . . . . . . . . . . 78
NATLANG(EN or KA) . . . . . . . . . . . . . . . . . . . . 79
NOCBLCARD . . . . . . . . . . . . . . . . . . . . . . . 79
NOCPSM . . . . . . . . . . . . . . . . . . . . . . . . . 79
NODEBUG . . . . . . . . . . . . . . . . . . . . . . . . 79
NOEDF . . . . . . . . . . . . . . . . . . . . . . . . . 80
NOEPILOG . . . . . . . . . . . . . . . . . . . . . . . . 80
NOFEPI . . . . . . . . . . . . . . . . . . . . . . . . . 80
NOLENGTH . . . . . . . . . . . . . . . . . . . . . . . . 80
NOLINKAGE. . . . . . . . . . . . . . . . . . . . . . . . 80
NONUM . . . . . . . . . . . . . . . . . . . . . . . . . 80
NOOPSEQUENCE . . . . . . . . . . . . . . . . . . . . . 80
NOOPTIONS . . . . . . . . . . . . . . . . . . . . . . . 81
NOPROLOG . . . . . . . . . . . . . . . . . . . . . . . . 81
NOSEQ . . . . . . . . . . . . . . . . . . . . . . . . . 81
NOSEQUENCE . . . . . . . . . . . . . . . . . . . . . . 81
NOSOURCE . . . . . . . . . . . . . . . . . . . . . . . . 81
NOSPIE . . . . . . . . . . . . . . . . . . . . . . . . . 81
NOVBREF . . . . . . . . . . . . . . . . . . . . . . . . 81
NUM . . . . . . . . . . . . . . . . . . . . . . . . . . 81

© Copyright IBM Corp. 1989, 2005 63

OOCOBOL . . . . . . . . . . . . . . . . . . . . . . . . 82
OPMARGINS(m,n[,c]) . . . . . . . . . . . . . . . . . . . . 82
OPSEQUENCE(m,n) . . . . . . . . . . . . . . . . . . . . . 82
OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 82
PROLOG . . . . . . . . . . . . . . . . . . . . . . . . . 82
QUOTE . . . . . . . . . . . . . . . . . . . . . . . . . 83
SEQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
SEQUENCE(m,n) . . . . . . . . . . . . . . . . . . . . . . 83
SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . 83
SP . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
SPACE(1 or 2 or 3) . . . . . . . . . . . . . . . . . . . . . 84
SPIE . . . . . . . . . . . . . . . . . . . . . . . . . . 84
SYSEIB . . . . . . . . . . . . . . . . . . . . . . . . . 84
VBREF . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Translator options table . . . . . . . . . . . . . . . . . . . . . 85
Using COPY statements . . . . . . . . . . . . . . . . . . . . . 86
The CICS-supplied interface modules . . . . . . . . . . . . . . . . 86
The EXEC interface modules. . . . . . . . . . . . . . . . . . . 86
The CPI Communications interface module . . . . . . . . . . . . . 86
The SAA Resource Recovery interface module . . . . . . . . . . . . 86
Using the EXEC interface modules . . . . . . . . . . . . . . . . . 87
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 87
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
C and C++ . . . . . . . . . . . . . . . . . . . . . . . . . 88
Assembler language . . . . . . . . . . . . . . . . . . . . . . 89
| EXAMPLE Assembler language PROGRAM using LEASM . . . . . . . . 89

Chapter 9. Installing application programs . . . . . . . . . . . . . . 99

Program installation roadmap . . . . . . . . . . . . . . . . . . . 99
Preparing for program installation . . . . . . . . . . . . . . . . 100
Defining MVS residence and addressing modes . . . . . . . . . . . . 101
Establishing a program’s addressing mode . . . . . . . . . . . . . 101
CICS address space considerations . . . . . . . . . . . . . . . . 101
Making programs permanently resident . . . . . . . . . . . . . . 102
Running applications in the link pack area . . . . . . . . . . . . . . 102
Running application programs in the RDSAs . . . . . . . . . . . . . 103
Assembler . . . . . . . . . . . . . . . . . . . . . . . . . 103
C and C/++ . . . . . . . . . . . . . . . . . . . . . . . . . 104
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . 105
PL/I . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using BMS map sets in application programs . . . . . . . . . . . . . 106
Using the CICS-supplied procedures to install application programs . . . . . 106
Installing programs in load library secondary extents . . . . . . . . . 107
Including the CICS-supplied interface modules . . . . . . . . . . . . . 108
Installing assembler language application programs . . . . . . . . . . . 108
Installing COBOL application programs . . . . . . . . . . . . . . . 110
Sample JCL to install COBOL application programs . . . . . . . . . . 111
Installing PL/I application programs . . . . . . . . . . . . . . . . . 114
Sample JCL to install PL/I application programs . . . . . . . . . . . 114
PL/I procedure with an integrated translator . . . . . . . . . . . . . 115
Installing C application programs . . . . . . . . . . . . . . . . . . 117
Sample JCL to install C application programs . . . . . . . . . . . . 118
Including pre-translated code with your C source code . . . . . . . . 119
Using your own job streams. . . . . . . . . . . . . . . . . . . . 119
Translator requirements . . . . . . . . . . . . . . . . . . . . 119
Online programs that use EXEC CICS or EXEC DLI commands . . . . . 119

64 CICS TS for z/OS: CICS Application Programming Guide

Online programs that use the CALL DLI interface . . . . . . . . . . . 122
Batch or BMP programs that use EXEC DLI commands . . . . . . . . 123
Batch or BMP programs that use DL/I CALL commands . . . . . . . . 123

Chapter 10. Installing map sets and partition sets . . . . . . . . . . 125

Installing map sets . . . . . . . . . . . . . . . . . . . . . . . 126
Types of map sets . . . . . . . . . . . . . . . . . . . . . . 126
Defining the type of map set you require . . . . . . . . . . . . . 127
Using extended data stream terminals . . . . . . . . . . . . . . 127
Installing physical map sets . . . . . . . . . . . . . . . . . . . 128
Installing symbolic description map sets . . . . . . . . . . . . . . 129
Installing physical and symbolic description maps together . . . . . . . 131
Using the DFHMAPT procedure to install HTML templates from BMS
maps . . . . . . . . . . . . . . . . . . . . . . . . . 131
JCL to install physical and symbolic description maps . . . . . . . . 132
Adding a CSECT to your map assembly . . . . . . . . . . . . . 132
Installing partition sets . . . . . . . . . . . . . . . . . . . . . . 133
Defining programs, map sets, and partition sets to CICS . . . . . . . . . 134

Part 2. Preparing applications to run 65

66 CICS TS for z/OS: CICS Application Programming Guide
Chapter 8. Translation and compilation
Most older compilers (and assemblers) cannot process CICS commands directly.
This means that an additional step is needed to convert your program into
executable code. This step is called translation, and consists of converting CICS
commands into the language in which the rest of the program is coded, so that the
compiler (or assembler) can understand them.

Modern compilers can use the integrated CICS translator approach, where the
compiler interfaces with CICS at compile time to interpret CICS commands and
convert them automatically to calls to CICS service routines. If you use the
integrated CICS translator approach then many of the translation tasks described in
“The translation process” on page 69 are done at compile time for you, and you do
not need to execute the additional translator step.

This section describes:

v “The integrated CICS translator”
v “The translation process” on page 69
v “The CICS-supplied translators” on page 72
v “Using a CICS translator” on page 73
v “Defining translator options” on page 74
v “Using COPY statements” on page 86
v “The CICS-supplied interface modules” on page 86
v “Using the EXEC interface modules” on page 87

The integrated CICS translator

In earlier CICS releases, CICS application programs had to be translated before
they could be compiled. The translators find EXEC CICS commands, make them
into comments, and generate CALLs appropriate to the language. The
CICS-supplied jobs for compiling user application programs all contain an initial job
step that invokes the translator appropriate to the compiler invoked in the following
job step.

The CICS-supplied separate translators change the line numbers in source

programs, which means that an intermediate listing, with the translator-generated
CALLs, which must be used when debugging an application program. With the
integrated translator, application development is made easier because there is only
one listing — the original source statements, and the CICS error messages are
included in the compiler listing. The process of translating and compiling is also less
error-prone because it is no longer necessary to translate included members
separately.

The Language Environment-conforming language compilers that support the

integrated CICS translator scan the application source and call the integrated CICS
translator at relevant points.

| The releases of the COBOL and PL/I compilers which support the CICS integrated
| translator are listed in the CICS Release Guide. If you use any other compiler,
| including Assembler, you will need to translate your program in the traditional way
| described in Chapter 8, “Translation and compilation.”

© Copyright IBM Corp. 1989, 2005 67

Using the integrated CICS translator
The language compilers provide various procedures that you can use with the
integrated CICS translator. They are documented in the Programming Guides for
Enterprise COBOL for z/OS and OS/390 and for Enterprise PL/I for z/OS and
OS/390.

The procedure that you use needs to have CICSTS31.CICS.SDFHLOAD added to

the STEPLIB concatenation for the compile step and the link-edit step should
include the interface module DFHELII at the start of the step.

To use the integrated CICS translator for PL/I you must specify the compiler option
SYSTEM(CICS).

To use the integrated CICS translator for COBOL the compiler options CICS, LIB,
NODYNAM, and RENT must be in effect. You cannot use SIZE(MAX) when
compiling large programs using CICS statements. Storage must be left in the user
region for integrated CICS translator services.

If you are running DB2 Version 7 or later and preparing a COBOL program using a
compiler with integrated translator, the compiler also provides an SQL statement
coprocessor (which produces a DBRM), so you do not need to use a separate DB2
precompiler. See the CICS DB2 Guide and the DB2 for OS/390 and z/OS
Application Programming and SQL Guide for more information on using the SQL
statement coprocessor.

Specifying CICS translator options

To specify CICS translator options when using the PL/I compiler specify the
compiler option, PP(CICS), with the translator options enclosed in apostrophes and
inside parenthesis. For example:
PP(CICS(’opt1 opt2 optn ...’))

For more information on specifying PL/I compiler options see the Enterprise PL/I for
z/OS and OS/390 Programming Guide.

To specify CICS translator options when using the COBOL compiler specify the
compiler option, CICS, with the translator options enclosed in apostrophes and
inside parenthesis. For example:
CICS(’opt1 opt2 optn ...’)

Note: The XOPTS translator option must be changed to the CICS compiler option.
XOPTS is not accepted when using the integrated CICS translator.

For more information on specifying COBOL compiler options see the Enterprise
COBOL for z/OS and OS/390: Programming Guide.

For a description of all of the translator options see “Defining translator options” on
page 74.

Many of the translator options, such as those associated with translator listings, do
not apply when using the integrated CICS translator. These options, if specified, are
ignored. The EXCI option is not supported, the CICS option is assumed. For
COBOL the OOCOBOL option is assumed.

The translator options that can be used effectively with the integrated CICS
translator are:

68 CICS TS for z/OS: CICS Application Programming Guide

v APOST or QUOTE
v CPSM or NOCPSM
v CICS
v DBCS
v DEBUG or NODEBUG
v DLI
v EDF or NOEDF
v FEPI or NOFEPI
v GRAPHIC
v LENGTH or NOLENGTH
v LINKAGE or NOLINKAGE
v NATLANG
v OOCOBOL
v SP
v SYSEIB

The translation process

For compilers without integrated translators, CICS provides a translator program for
each of the languages in which you may write, to handle both EXEC CICS and
EXEC DLI statements.

For compilers with integrated translators, the compilers interface with CICS to
handle both EXEC CICS and EXEC DLI statements.

A language translator reads your source program and creates a new one; most
normal language statements remain unchanged, but CICS commands are
translated into CALL statements of the form required by the language in which you
are coding. The calls invoke CICS-provided “EXEC” interface modules, which later
get link-edited into your load module, and these in turn invoke the requested
services at execution time.

There are three steps: translation, compilation (assembly), and link-edit. Figure 10
on page 70 shows these 3 steps.

Chapter 8. Translation and compilation 69

SYSIN
(source
program)

CICS
Translation
Command- SYSPRINT
level (translator
language listing)
translator SYSPUNCH
(translated
source
program)

High-level High-level
language language
Compilation compiler compiler (or
(assembly) (or assembler) assembler)
listing
Object
module

Link-editor
Link-editor listing

Link Edit

Load
library

Figure 10. Preparing an application program

The translators for all languages use one input and two output files:
SYSIN (Translator input) is the file that contains your source program.
If the SYSIN file is defined as a fixed blocked data set, the maximum record
length that the data set can possess is 80 bytes. Passing a fixed blocked
data set with a record length of greater than 80 bytes to the translator
results in termination of translator execution. If the SYSIN file is defined as
a variable blocked data set, the maximum record length that the data set
can possess is 100 bytes. Passing a variable blocked data set with a record
length greater than 100 bytes to the translator causes the translator to stop
with an error.
SYSPUNCH
(Translated source) is the translated version of your source code, which
becomes the input to the compile (assemble) step. In this file, your source
has been changed as follows:
v The EXEC interface block (EIB) structure has been inserted.
v EXEC CICS, EXEC CPSM and EXEC DLI commands have been turned
into function call statements.

70 CICS TS for z/OS: CICS Application Programming Guide

v CICS DFHRESP, EYUVALUE, and DFHVALUE built-in functions have
been processed.
v A data interchange block (DIB) structure and initialization call have been
inserted if the program contains EXEC DLI statements.
The CICS commands that get translated still appear in the source, but as
comments only. Generally the non-CICS statements are unchanged. The
output from the translator always goes to an 80 byte fixed-record length
data set.
SYSPRINT
(Translator listing) shows the number of messages produced by the
translator, and the highest severity code associated with any message. The
options used in translating your program also appear, unless these have
been suppressed with the NOOPTIONS option.
For COBOL, C, C++, and PL/I programs, SYSPRINT also contains the
messages themselves. In addition, if you specify the SOURCE option of the
translator, you also get an annotated listing of the source in SYSPRINT.
This listing contains almost the same information as the subsequent
compilation listing, and therefore many installations elect to omit it (the
NOSOURCE option). One item you may need from this listing which is not
present in the compile listing, however, is the line numbers, if the translator
is assigning them. Line numbers are one way to indicate points in the code
when you debug with the execution diagnostic facility (EDF). If you specify
the VBREF option, you also get a list of the commands in your program,
cross-referenced by line number, and you can use this as an alternative to
the source listing for EDF purposes.
For assembler language programs, SYSPRINT contains only the translator
options, the message count and maximum severity code. The messages
themselves are inserted into the SYSPUNCH file as comments after the
related statement. This causes the assembler to copy them through to the
assembler listing, where you can check them. You may also see MNOTEs
that are generated by the assembler as the result of problems encountered
by the translator.

Note: If you use EXEC SQL, you need additional steps to translate the SQL
statements and bind; see the Application Programming and SQL Guide for
information about these extra steps.

CICS provides a procedure to execute these steps in sequence for each of the
languages it supports. “Using the CICS-supplied procedures to install application
programs” on page 106 describes how to use these procedures, and exactly what
they do.

You can control the translation process by specifying a number of options. For
example, if your program uses EXEC DLI calls, you need to tell the translator.

The translator may produce error messages, and it is as important to check these
messages as it is to check the messages produced by the compiler and link-editor.
See “The CICS-supplied translators” on page 72 for the location of these
messages.

EXEC commands are translated into CALL statements that invoke CICS interface
modules. These modules get incorporated into your object module in the link-edit
step, and you see them in your link-edit output listing. You can read more about
these modules in “The CICS-supplied interface modules” on page 86.

Chapter 8. Translation and compilation 71

The CICS-supplied translators
The following CICS-supplied translators are installed in the
CICSTS31.CICS.SDFHLOAD library:

Assembler DFHEAP1$
C DFHEDP1$
COBOL DFHECP1$
PL/I DFHEPP1$

Dynamic invocation of the separate translator

You can invoke the command-level language translator dynamically from a batch
assembler-language program using an ATTACH, CALL, LINK, or XCTL macro; or
from a C, PL/I, or COBOL program using CALL. If you use ATTACH, LINK, or
XCTL, use the appropriate translator load module, DFHExP1$, where x=A for
assembler language, x=C for COBOL, x=D for C, or x=P for PL/I.

If you use CALL, specify PREPROC as the entry point name to call the translator.

In all cases, pass the following address parameters to the translator:

v The address of the translator option list
v The address of a list of DD names used by the translator (this is optional)

These addresses must be in adjacent fullwords, aligned on a fullword boundary.

Register 1 must point to the first address in the list, and the high-order bit of the last
address must be set to one, to indicate the end of the list. This is true for both one
or two addresses.

Translator option list

The translator option list must begin on a halfword boundary. The first two bytes
contain a binary count of the number of bytes in the list (excluding the count field).
The remainder of the list can contain any of the translator option keywords,
separated by commas, blanks, or both.

Data definition (DD name) list

The DD name list must begin on a halfword boundary. The first two bytes contain a
binary count of the number of bytes in the list (excluding the count field). Each entry
in the list must occupy an 8-byte field. The sequence of entries is:

Entry Standard Entry Standard Entry Standard

DD name DD name DD name
1 not applicable 3 not applicable 5 SYSIN
2 not applicable 4 not applicable 6 SYSPRINT
7 SYSPUNCH

If you omit an applicable entry, the translator uses the standard DD name. If you
use a DD name less than 8 bytes long, fill the field with blanks on the right. You can
omit an entry by placing X'FF' in the first byte. You can omit entries at the end of
the list entirely.

72 CICS TS for z/OS: CICS Application Programming Guide

Using a CICS translator
A language translator reads your source program and creates a new one; most
normal language statements remain unchanged, but CICS commands are
translated into CALL statements of the form required by the language in which you
are coding. The calls invoke CICS-provided “EXEC” interface modules, which later
get link-edited into your load module, and these in turn invoke the requested
services at execution time.

You can control the translation process by specifying translator options.

The translator options you can choose are listed in “Defining translator options” on
page 74. You can specify your choices in one of two ways:
v List them as suboptions of the XOPTS option on the statement that the compiler
(assembler) provides for specifying options. These statements are:
Language Statement
COBOL CBL
COBOL PROCESS
C #pragma
C++ #pragma
PL/I * PROCESS
Assembler *ASM or *PROCESS¹
v List your options in the PARM operand of the EXEC job control statement for the
translate step. Most installations use catalogued procedures to translate, compile
(assemble) and link CICS programs, and therefore you specify this PARM field in
the EXEC job control statement that invokes the procedure.
For example, if the name of the procedure for COBOL programs is DFHYITVL,
and the name of the translate step within is TRN, you set translator options for a
COBOL program with a statement such as this one:
// EXEC DFHEITCL,PARM.TRN=(VBREF,QUOTE,SPACE(2),NOCBLCARD)

If you specify an option by one method and the same option or an option that
conflicts by the other method, the specifications in the language statement override
those in the EXEC statement. Similarly, if you specify multiple values for a single
option or options that conflict on either type of statement, the last setting takes
precedence. Except for COBOL programs, these statements must precede each
source program; there is no way to batch the processing of multiple programs in
other languages.

Translator options may appear in any order, separated by one or more blanks or by
a comma. If you specify them on the language statement for options, they must
appear in parentheses following the XOPTS parameter, because other options are
ignored by the translator and passed through to the compiler. The following COBOL
example shows both translator and compiler options being passed together:
CBL LIB XOPTS(QUOTE SPACE(2))

These examples show translator options being passed alone:

#pragma XOPTS(FLAG(W) SOURCE);
* PROCESS XOPTS(FLAG(W) SOURCE);
*ASM XOPTS(NOPROLOG NOEPILOG)

Chapter 8. Translation and compilation 73

If you use the PARM operand of the EXEC job control statement to specify options,
the XOPTS keyword is unnecessary, because the only options permitted here are
translator options. However, you may use XOPTS, with or without its associated
parentheses. If you use XOPTS with parentheses, be sure to enclose all of the
translator options. For example, the following forms are valid:
PARM=(op1 op2 .. opn)
PARM=(XOPTS op1 op2 .. opn)
PARM=XOPTS(op1 op2 .. opn)

but the following is not valid:

PARM=(XOPTS(op1 op2) opn)

(For compatibility with previous releases, the keyword CICS can be used as an
alternative to XOPTS, except when you are translating batch EXEC DLI programs.)
Remember, if you alter the default margins for C or C++ #pragma card processing
using the PARM operand, the sequence margins should be altered too. You can do
this using the NOSEQUENCE option.
Notes:
1. For assembler programs, *ASM statements contain translator options only. They
are treated as comments by the assembler. *PROCESS statements can contain
translator or assembler options for the High Level assembler, HLASM.
2. Translator and assembler options must not coexist on the same *PROCESS
statement.
3. *PROCESS and *ASM statements must be at the beginning of the input and no
assembler statements must appear before them. This includes comments and
statements such as “PRINT ON” and “EJECT”. Both *PROCESS and *ASM
statements can be included, in any order.
4. *PROCESS statements containing only translator options contain information for
the translator only and are not passed to the assembler
5. *PROCESS statements containing assembler options are placed in the
translated program.

Defining translator options

You can specify the translator options that apply to all languages except where
stated otherwise. Table 4 on page 85 lists all the translator options, the program
languages that apply, and any valid abbreviations.

If your installation uses the CICS-provided procedures in the distributed form, the
default options are used. These are explicitly noted in the following option
descriptions. You can tell which options get used by default at your installation by
looking at the SYSPRINT translator listing output from the translate step (see “The
CICS-supplied translators” on page 72). If you want an option that is not the default,
you must specify it, as described in “Using a CICS translator” on page 73.

74 CICS TS for z/OS: CICS Application Programming Guide

Translator options
APOST
(COBOL only)

APOST indicates that literals are delineated by the apostrophe (’). This is the
default—QUOTE is the alternative. The same value must be specified for the
translator step and the following compile step.

The CICS-supplied COBOL copybooks use APOST.

Note: COBOL for MVS & VM and later compilers can use either apostrophes or
quotes or both in the same program, and this option is not so important for
these compilers.

CBLCARD
(COBOL only) Abbreviation: CBL

CBLCARD specifies that the translator is to generate a CBL statement. This is the
default—the alternative is NOCBLCARD.

CICS
CICS specifies that the translator is to process EXEC CICS commands. It is the
default specification in the translator. CICS is also an old name for the XOPTS
keyword for specifying translator options, which means that you can specify the
CICS option explicitly either by including it in your XOPTS list or by using it in place
of XOPTS to name the list. The only way to indicate that there are no CICS
commands is to use the XOPTS keyword without the option CICS. You must do this
in a batch DL/I program using EXEC DLI commands. For example, to translate a
batch DL/I program written in assembler language, specify:
*ASM XOPTS(DLI)

To translate a batch program written in COBOL, containing EXEC API commands,

specify:
CBL XOPTS(EXCI)

# COBOL2
# (COBOL only) Abbreviation: CO2

# COBOL2 specifies that the translator is to generate temporary variables for use in
# the translated EXEC statements. In all other respects, the program is translated in
# the same manner as with the “COBOL3” option. COBOL2 and COBOL3 are
# mutually exclusive. COBOL2 is the default for COBOL.

# Note: If you specify COBOL2 and COBOL3 by different methods, the COBOL3
# option is always used, regardless of where the two options have been
# specified. If this happens, the translator issues a warning message.

COBOL3
(COBOL only) Abbreviation: CO3

COBOL3 specifies that the translator is to translate programs that are Language
Environment-conforming. COBOL3 and COBOL2 are mutually exclusive. “Using the
COBOL2 and COBOL3 translator options” on page 33 explains how the translator
treats specific coding situations. Chapter 3, “Language Environment,” on page 9
explains what Language Environment-conforming compilers are available.

Chapter 8. Translation and compilation 75

CPP
(C++ only)CPP specifies that the translator is to translate C++ programs for
compilation by a supported C++ compiler, such as IBM C/C++ for MVS.

CPSM
CPSM specifies that the translator is to process EXEC CPSM commands. The
alternative is NOCPSM, which is the default.

DBCS
(COBOL only)

DBCS specifies that the source program may contain double-byte characters. It
causes the translator to treat hexadecimal codes X'0E' and X'0F' as shift-out (SO)
and shift-in (SI) codes, respectively, wherever they appear in the program.

For more detailed information about how to program in COBOL using DBCS, see
the section on DBCS character strings in Enterprise COBOL for z/OS and OS/390:
Language Reference.

DEBUG
(COBOL, C, C++, and PL/I only)

DEBUG instructs the translator to produce code that passes the line number
through to CICS for use by the execution diagnostic facility (EDF). DEBUG is the
default—NODEBUG is the alternative.

DLI
DLI specifies that the translator is to process EXEC DLI commands. You must
specify it with the XOPTS option, that is, XOPTS(DLI).

EDF
EDF specifies that the execution diagnostic facility is to apply to the program. EDF
is the default—the alternative is NOEDF.

EPILOG
(Assembler language only)

EPILOG® specifies that the translator is to insert the macro DFHEIRET at the end
of the program being translated. DFHEIRET returns control from the issuing
program to the program which invoked it. If you want to use any of the options of
the RETURN command, you should use RETURN and specify NOEPILOG.

EPILOG is the default—the alternative, NOEPILOG, prevents the translator inserting

the macro DFHEIRET. (See the CICS Application Programming Reference manual
for programming information about the DFHEIRET macro.)

EXCI
EXCI specifies that the translator is to process EXEC API commands for the
External CICS Interface (EXCI). These commands must be used only in batch
programs, and so the EXCI translator option is mutually exclusive to the CICS
translator option, or any translator option that implies the CICS option. An error
message is produced if both CICS and EXCI are specified, or EXCI and a translator
option that implies CICS are specified.

76 CICS TS for z/OS: CICS Application Programming Guide

The EXCI option is also mutually exclusive to the DLI option. EXEC API commands
for the External CICS Interface cannot be coded in batch programs using EXEC DLI
commands. An error message is produced if both EXCI and DLI translator
commands are specified.

The EXCI translator option is specified by XOPTS, that is, XOPTS(EXCI).

FEPI
FEPI allows access to the FEPI API commands of the CICS Front End
Programming Interface (FEPI). FEPI is only available if you have installed the CICS
Front End Programming Interface. The alternative is NOFEPI. FEPI commands and
design are described in the CICS Front End Programming Interface User’s Guide.

FLAG (I, W, E, or S)
(COBOL, C, C++, and PL/I only) Abbreviation: F

FLAG specifies the minimum severity of error in the translation which requires a
message to be listed.
I All messages.
W (Default) All except information messages.
E All except warning and information messages.
S Only severe and unrecoverable error messages.

GDS
(C, C++, and assembler language only)

GDS specifies that the translator is to process CICS GDS (generalized data stream)
commands. For programming information about these commands, see the CICS
Application Programming Reference manual.

GRAPHIC
(PL/I only)

GRAPHIC specifies that the source program may contain double-byte characters. It
causes the translator to treat hexadecimal codes X'0E' and X'0F' as shift-out (SO)
and shift-in (SI) codes, respectively, wherever they appear in the program.

It also prevents the translator from generating parameter lists that contain the
shift-out and shift-in values in hexadecimal form. Wherever these values would
ordinarily appear, the translator expresses them in binary form, so that there are no
unintended DBCS delimiters in the data stream that the compiler receives.

If the compiler you are using supports DBCS, you need to prevent unintended
shift-out and shift-in codes, even if you are not using double-byte characters. You
can do this by specifying the GRAPHIC option for the translator, so that it does not
create them, or by specifying NOGRAPHIC on the compile step, so that the
compiler does not interpret them as DBCS delimiters.

For more detailed information about how to program in PL/I using DBCS, see the
relevant language reference manual.

| LEASM
| (Assembler only)

Chapter 8. Translation and compilation 77

| LEASM instructs the translator to generate code for a Language
| Environment-conforming assembler MAIN program.

| If the LEASM option is specified, the DFHEISTG, DFHEIENT, DFHEIRET and

| DFHEIEND macros expand differently to create a Language Environment-
| conforming assembler MAIN program, instead of the form of macro expansion used
| for assembler sub-routines in a CICS environment. This allows customer programs
| that have used NOPROLOG and NOEPILOG and coded their own DFHEIENT and
| other macros to take advantage of Language Environment support without changing
| their program source. For example, all programs that require more than one code
| base register fall into this category because the translator does not support multiple
| code base registers.

| For an example of an assembler program translated using the LEASM option see
| “EXAMPLE Assembler language PROGRAM using LEASM” on page 89.

LENGTH
(COBOL, Assembler and PL/I only)

LENGTH instructs the translator to generate a default length if the LENGTH option
is omitted from a CICS command in the application program. The alternative is
NOLENGTH.

LINECOUNT(n)
Abbreviation: LC

LINECOUNT specifies the number of lines to be included in each page of translator

listing, including heading and blank lines. The value of “n” must be an integer in the
range 1 through 255; if “n” is less than 5, only the heading and one line of listing
are included on each page. The default is 60.

LINKAGE
(COBOL only) Abbreviation: LIN

LINKAGE requests the translator to modify the LINKAGE SECTION and

PROCEDURE DIVISION statements in top-level programs according to the existing
rules.

This means that the translator will insert a USING DFHEIBLK DFHCOMMAREA
statement in the PROCEDURE DIVISION, if one does not already exist, and will
ensure that the LINKAGE SECTION (creating one if necessary) contains definitions
for DFHEIBLK and DFHCOMMAREA.

LINKAGE is the default—the alternative is NOLINKAGE.

The LINKAGE option has no effect on the translation of classes and methods.

MARGINS(m,n[,c])
(C, C++, and PL/I only) Abbreviation: MAR

MARGINS specifies the columns of each line or record of input that contain
language or CICS statements. The translator does not process data that is outside
these limits, though it does include it in the source listings.

78 CICS TS for z/OS: CICS Application Programming Guide

The option can also specify the position of an American National Standard printer
control character to format the listing produced when the SOURCE option is
specified; otherwise, the input records are listed without any intervening blank lines.
The margin parameters are:
m Column number of left-hand margin.
n Column number of right-hand margin. It must be greater than m.

Note: When used as a C or C++ compiler option, the asterisk (*) is

allowable for the second argument on the MARGIN option. For the
translator, however, a numeric value between 1 and 100 inclusive
must be specified. When the input data set has fixed-length records,
the maximum value allowable for the right hand margin is 80. When
the input data set has variable-length records, the maximum value
allowable is 100.
c Column number of the American National Standard printer control character.
It must be outside the values specified for m and n. A zero value for c
means no printer control character. If c is nonzero, only the following printer
control characters can appear in the source:
(blank)
Skip 1 line before printing.
0 Skip 2 lines before printing.
− Skip 3 lines before printing.
+ No skip before printing.
1 New page.

The default for C and C++ is MARGINS(1,72,0) for fixed-length records, and for
variable-length records it is the same as the record length (1,record length,0). The
default for PL/I is MARGINS(2,72,0) for fixed-length records, and
MARGINS(10,100,0) for variable-length records.

NATLANG(EN or KA)
NATLANG specifies what language is to be used for the translator message output:
EN (Default) English.
KA Kanji.

(Take care not to confuse this option with the NATLANG API option.)

NOCBLCARD
(COBOL only)

NOCBLCARD specifies that the translator is not to generate a CBL statement. The
compiler options that CICS requires are specified by the DFHYITVL procedure. You
should ensure that RENT, NODYNAM, and LIB are specified..

NOCPSM
NOCPSM specifies that the translator is not to process EXEC CPSM commands.
This is the default—the alternative is CPSM.

NODEBUG
(COBOL, C, C++, and PL/I only)

NODEBUG instructs the translator not to produce code that passes the line number
through to CICS for use by the execution diagnostic facility (EDF).

Chapter 8. Translation and compilation 79

NOEDF
NOEDF specifies that the execution diagnostic facility is not to apply to the
program. There is no performance advantage in specifying NOEDF, but the option
can be useful to prevent commands in well-debugged subprograms appearing on
EDF displays.

NOEPILOG
(Assembler language only)

NOEPILOG instructs the translator not to insert the macro DFHEIRET at the end of
the program being translated. DFHEIRET returns control from the issuing program
to the program which invoked it. If you want to use any of the options of the EXEC
CICS RETURN command, you should use EXEC CICS RETURN and specify
NOEPILOG. NOEPILOG prevents the translator inserting the macro DFHEIRET.
The alternative is EPILOG, which is the default. (See the CICS Application
Programming Reference manual for programming information about the DFHEIRET
macro.)

NOFEPI
NOFEPI disallows access to the FEPI API commands of the CICS Front End
Programming Interface (FEPI). NOFEPI is the default—the alternative is FEPI.

NOLENGTH
(COBOL, Assembler and PL/I only)

NOLENGTH instructs the translator not to generate a default length if the LENGTH
option is omitted from a CICS command in the application program. The default is
LENGTH.

NOLINKAGE
(COBOL only)

NOLINKAGE requests the translator not to modify the LINKAGE SECTION and
PROCEDURE DIVISION statements to supply missing DFHEIBLK and
DFHCOMMAREA statements, or insert a definition of the EIB structure in the
LINKAGE section..

This means that you can provide COBOL copybooks to define a COMMAREA and
use the EXEC CICS ADDRESS command.

LINKAGE is the default.

NONUM
(COBOL only)

NONUM instructs the translator not to use the line numbers appearing in columns
one through six of each line of the program as the line number in its diagnostic
messages and cross-reference listing, but to generate its own line numbers.
NONUM is the default—the alternative is NUM.

NOOPSEQUENCE
(C, C++, and PL/I only) Abbreviation: NOS

NOOPSEQUENCE specifies the position of the sequence field in the translator

output records. The default for C and C++ is OPSEQUENCE(73,80) for fixed-length

80 CICS TS for z/OS: CICS Application Programming Guide

records and NOOPSEQUENCE for variable-length records. For PL/I, the default is
OPSEQUENCE(73,80) for both types of records.

NOOPTIONS
Abbreviation: NOP

NOOPTIONS instructs the translator not to include a list of the options used during
this translation in its output listing.

NOPROLOG
(Assembler language only)

NOPROLOG instructs the translator not to insert the macros DFHEISTG,

DFHEIEND, and DFHEIENT into the program being assembled. These macros
define local program storage and execute at program entry. (See the CICS
Application Programming Reference manual for programming information about
these “prolog” macros.)

NOSEQ
(COBOL only)

NOSEQ instructs the translator not to check the sequence field of the source
statements, in columns 1-6. The alternative, SEQ, is the default. If SEQ is specified
and a statement is not in sequence, it is flagged.

NOSEQUENCE
(C, C++, and PL/I only) Abbreviation: NSEQ

NOSEQUENCE specifies that statements in the translator input are not sequence
numbered and that the translator must assign its own line numbers.

The default for fixed-length records is SEQUENCE(73,80). For variable-length

records in C and C++, the default is NOSEQUENCE and for variable-length records
in PL/I the default is SEQUENCE(1,8).

NOSOURCE
NOSOURCE instructs the translator not to include a listing of the translated source
program in the translator listing.

NOSPIE
NOSPIE prevents the translator from trapping irrecoverable errors; instead, a dump
is produced. You should use NOSPIE only when requested to do so by the IBM
support center.

NOVBREF
(COBOL, C, C++ and PL/I only)

NOVBREF instructs the translator not to include a cross-reference of commands

with line numbers in the translator listing. (NOVBREF used to be called NOXREF;
for compatibility, NOXREF is still accepted.) NOVBREF is the default—the
alternative is VBREF.

NUM
(COBOL only)

Chapter 8. Translation and compilation 81

NUM instructs the translator to use the line numbers appearing in columns one
through six of each line of the program as the line number in its diagnostic
messages and cross-reference listing. The alternative is NONUM, which is the
default.

OOCOBOL
(OO COBOL only) Abbreviation: OO

OOCOBOL instructs the translator to recognize the object-oriented COBOL (OO

COBOL) syntax. The phrases:
v CLASS-ID xxx...xxx
v END CLASS xxx...xxx
v METHOD-ID xxx...xxx
v END METHOD xxx...xxx

are recognized but their correct usage is not monitored. The translator considers
each class as a separate unit of compilation. This option implies the COBOL3
option.

OPMARGINS(m,n[,c])
(C, C++ and PL/I only) Abbreviation: OM

OPMARGINS specifies the translator output margins, that is, the margins of the
input to the following compiler. Normally these are the same as the input margins
for the translator. For a definition of input margins and the meaning of “m”, “n”, and
“c”, see MARGINS. The default for C and C++ is OPMARGINS(1,72,0) and for PL/I,
the default is OPMARGINS(2,72,0).

The maximum “n” value allowable for the OPMARGINS option is 80. The output
from the translator is always of a fixed-length record format.

If the OPMARGINS option is used to set the output from the translator to a certain
format, it may be necessary to change the input margins for the compiler being
used. If the OPMARGINS value is allowed to default this is not necessary.

OPSEQUENCE(m,n)
(C, C++, and PL/I only) Abbreviation: OS

OPSEQUENCE specifies the position of the sequence field in the translator output
records. For the meaning of “m” and “n”, see SEQUENCE. The default for C and
C++ is OPSEQUENCE(73,80) for fixed-length records and NOOPSEQUENCE for
variable-length records. For PL/I, the default is OPSEQUENCE(73,80) for both
types of records.

OPTIONS
Abbreviation: OP

OPTIONS instructs the translator to include a list of the options used during this
translation in its output listing.

PROLOG
(Assembler language only)

PROLOG instructs the translator to insert the macros DFHEISTG, DFHEIEND, and
DFHEIENT into the program being assembled. These macros define local program
storage and execute at program entry. (See the CICS Application Programming

82 CICS TS for z/OS: CICS Application Programming Guide

Reference manual for programming information about these “prolog” macros.)
PROLOG is the default—the alternative is NOPROLOG.

QUOTE
(COBOL only) Abbreviation: Q

QUOTE indicates that literals are delineated by the double quotation mark (”). The
same value must be specified for the translator step and the following compiler
step.

The CICS-supplied COBOL copybooks use APOST, the default, instead of QUOTE.

Note: COBOL for MVS & VM and later compilers can use either apostrophes or
quotes or both in the same program, and this option is not so important for
these compilers.

SEQ
(COBOL only)

SEQ instructs the translator to check the sequence field of the source statements,
in columns 1-6. SEQ is the default—the alternative is NOSEQ. If a statement is not
in sequence, it is flagged.

SEQUENCE(m,n)
(C, C++, and PL/I only) Abbreviation: SEQ

SEQUENCE specifies that statements in the translator input are sequence

numbered and the columns in each line or record that contain the sequence field.
The translator uses this number as the line number in error messages and
cross-reference listings. No attempt is made to sort the input lines or records into
sequence. If no sequence field is specified, the translator assigns its own line
numbers. The SEQUENCE parameters are:
m Leftmost sequence number column.
n Rightmost sequence number column.

The sequence number field must not exceed eight characters and must not overlap
the source program (as specified in the MARGINS option).

The default for fixed-length records is SEQUENCE(73,80). For variable-length

records in C and C++ the default is NOSEQUENCE and for variable-length records
in PL/I the default is SEQUENCE(1,8).

SOURCE
Abbreviation: S

SOURCE instructs the translator to include a listing of the translated source

program in the translator listing. SOURCE is the default—the alternative is
NOSOURCE.

SP
SP must be specified for application programs that contain special (SP) CICS
commands or they will be rejected at translate time. These commands are
ACQUIRE, COLLECT, CREATE, DISABLE, DISCARD, ENABLE, EXTRACT,

Chapter 8. Translation and compilation 83

INQUIRE, PERFORM, RESYNC, and SET™. They are generally used by system
programmers. For programming information about these commands, see the CICS
System Programming Reference manual .

SPACE(1 or 2 or 3)
(COBOL only)

SPACE indicates the type of spacing to be used in the output listing: SPACE(1)
specifies single spacing, SPACE(2) double spacing, and SPACE(3) triple spacing.
SPACE(3) is the default.

SPIE
SPIE specifies that the translator is to trap irrecoverable errors. SPIE is the
default—the alternative is NOSPIE.

SYSEIB
SYSEIB indicates that the program is to use the system EIB instead of the
application EIB. The SYSEIB option allows programs to execute CICS commands
without updating the application EIB, making that aspect of execution transparent to
the application. However, this option imposes restrictions on programs using it, and
should be used only in special situations. A program translated with the SYSEIB
option must:
v Execute in AMODE(31), as the system EIB is assumed to be located in
“TASKDATALOC(ANY)” storage.
v Obtain the address of the system EIB using the ADDRESS EIB command (if the
program is translated with the SYSEIB option, this command automatically
returns the address of the system EIB).
v Be aware that the use of the SYSEIB option implies the use of the NOHANDLE
option on all CICS commands issued by the program. (Commands should use
the RESP option as required.)

VBREF
(COBOL, C, C++, and PL/I only)

VBREF specifies whether the translator is to include a cross-reference of

commands with line numbers in the translator listing. (VBREF used to be called
XREF, and is still accepted.)

84 CICS TS for z/OS: CICS Application Programming Guide

Translator options table
Table 4. Translator options applicable to programming language
Translator option COBOL C C++ PL/I Assembler
APOST or QUOTE X
CBLCARD or NOCBLCARD X
CICS X X X X X
# COBOL2 X
COBOL3 X
CPP X
CPSM or NOCPSM X X X X X
DBCS X
DEBUG or NODEBUG X X X X
DLI X X X X X
EDF or NOEDF X X X X X
EPILOG or NOEPILOG X
EXCI X X X X X
FEPI or NOFEPI X X X X X
FLAG(I or W or E or S) X X X X
GDS X X X
GRAPHIC X
| LEASM X
LENGTH or NOLENGTH X X X
LINECOUNT(n) X X X X X
LINKAGE or NOLINKAGE X
MARGINS(m,n) X X X
NATLANG X X X X X
NUM or NONUM X
OOCOBOL X
OPMARGINS(m,n[,c ]) X X X
OPSEQUENCE(m,n) or X X X
NOOPSEQUENCE
OPTIONS or NOOPTIONS X X X X X
PROLOG or NOPROLOG X
QUOTE or APOST X
SEQ or NOSEQ X
SEQUENCE(m,n) or NOSEQUENCE X X X
SOURCE or NOSOURCE X X X
SP X X X X X
SPACE(1 or 2 or 3) X
SPIE or NOSPIE X X X X X
SYSEIB X X X X X
VBREF or NOVBREF X X X X

Chapter 8. Translation and compilation 85

Using COPY statements
The compiler (or assembler) reads the translated version of your program as input,
rather than your original source. This affects what you see on your compiler
(assembler) listing. It also means that COPY statements in your source code must
not bring in untranslated CICS commands, because it is too late for the translator to
convert them.

If you are using a separate translator and the source within any copybook contains
CICS commands, you must translate it separately before translation and compilation
of the program in which it will be included. If you are using the integrated CICS
translator and the source within any copybook contains CICS commands, you do
not have to translate it separately before compilation of the program in which it will
be included.

The external program must always be passed through the CICS translator, or
compiled with a compiler that has an integrated CICS translator, even if all the
CICS commands are in included copybooks.

The CICS-supplied interface modules

Each of your application programs to run under CICS requires one or more
interface modules (also known as stubs) to use the following facilities:
v The EXEC interface
v The CPI Communications facility
v The SAA® Resource Recovery facility
v The CICSPlex® SM application programming interface (for information about
CICSPlex SM stubs, see CICSPlex SM Application Programming Guide).

The EXEC interface modules

Each of your CICS application programs must contain an interface to CICS. This
takes the form of an EXEC interface module, used by the CICS high-level
programming interface. The module, installed in the CICSTS31.CICS.SDFHLOAD
library, must be link-edited with your application program to provide communication
between your code and the EXEC interface program, DFHEIP.

The CPI Communications interface module

Each of your CICS application programs that uses the Common Programming
Interface for Communications (CPI Communications) must contain an interface to
CPI Communications. This takes the form of an interface module, used by the CICS
high-level programming interface, common to all the programming languages. The
module, DFHCPLC, that is installed in the CICSTS31.CICS.SDFHLOAD library,
must be link-edited with each application program that uses CPI Communications.

The SAA Resource Recovery interface module

Each of your CICS application programs that uses SAA Resource Recovery must
contain an interface to SAA Resource Recovery. This takes the form of an interface
module, used by the CICS high-level programming interface, common to all the
programming languages. The module, DFHCPLRR, that is installed in the
CICSTS31.CICS.SDFHLOAD library, must be link-edited with each application
program that uses the SAA Resource Recovery facility.

86 CICS TS for z/OS: CICS Application Programming Guide

Using the EXEC interface modules
A language translator reads your source program and creates a new one; normal
language statements remain unchanged, but CICS commands are translated into
CALL statements of the form required by the language in which you are coding. The
calls invoke CICS-provided “EXEC” interface modules or stubs , which is a
function-dependent piece of code used by the CICS high-level programming
interface. The stub, provided in the SDFHLOAD library, must be link-edited with
your application program to provide communication between your code and the
CICS EXEC interface program, DFHEIP. These stubs are invoked during execution
of EXEC CICS and EXEC DLI commands.

There are stubs for each programming language.

Table 5. Interface modules
Language Interface module name
| ASSEMBLER DFHELII and DFHEAI0
All HLL languages and Assembler MAIN DFHELII
programs using the LEASM option

The CICS-supplied stub routines work with an internal programming interface, the
CICS command-level interface, which is never changed in an incompatible way.
Consequently, these stub modules are upward and downward compatible, and
CICS application modules never need to be re-linked to include a later level of any
of these stubs.

With the exception of DFHEAI0, these stubs all provide the same function, which is
to provide a linkage from EXEC CICS commands to the required CICS service. The
stubs make this possible by providing various entry points that are called from the
translated EXEC CICS commands, and then executing a sequence of instructions
that pass control to the EXEC interface function of CICS.

DFHELII contains multiple entry points, most of which provide compatibility for very
old versions of the CICS PL/I translator. It contains the entries DFHEXEC (for C
and C++ application programs), DFHEI1 (for COBOL and assembler), and DFHEI01
(for PL/1).

Each of these stubs begins with an 8 byte eyecatcher in the form DFHYxnnn,
where x indicates the language supported by the stub (for example, A represents
assembler, and I indicates that the stub is language independent), and nnn
indicates the CICS release from which the stub was included. The letter Y in the
eyecatcher indicates that the stub is read-only. Stubs supplied with very early
releases of CICS contained eyecatchers in the form DFHExxxx in which the letter E
denotes that the stub is not read-only.The eyecatcher for DFHELII in CICS
Transaction Server for z/OS, Version 3 Release 1 is DFHYI640.

The eyecatcher can be helpful if you are trying to determine the CICS release at
which a CICS application load module was most recently linked.

COBOL
Each EXEC command is translated into a COBOL CALL statement that refers to the
entry DFHEI1.

Chapter 8. Translation and compilation 87

The following example shows the output generated by the translator when
processing a simple EXEC CICS RETURN command:
*EXEC CICS RETURN END-EXEC
Call ’DFHEI1’ using by content x’0e0800000600001000’
end-call.

The reference to DFHEI1 is resolved by the inclusion of the DFHELII stub routine in
the linkage editor step of the CICS-supplied procedures such as DFHYITVL or
DFHZITCL.

PL/I
When translating PL/I programs each EXEC command generates a call to the entry
point DFHEI01. This is done using a variable entry point DFHEI0 that is associated
with the entry DFHEI01. The translator enables this by inserting the following
statements near the start of each translated program:
DCL DFHEI0 ENTRY VARIABLE INIT(DFHEI01) AUTO;
DCL DFHEI01 ENTRY OPTIONS(INTER ASSEMBLER);

The translator creates a unique entry name based on DFHEI0 for each successfully
translated EXEC command. The following example shows the output generated by
the translator when processing a simple EXEC CICS RETURN command:
/* EXEC CICS RETURN TRANSID(NEXT) */
DO;
DCL DFHENTRY_B62D3C38_296F2687 BASED(ADDR(DFHEI0)) OPTIONS(INTER ASSEM
BLER) ENTRY(*,CHAR(4));
CALL DFHENTRY_B62D3C38_296F2687(’xxxxxxxxxxxxxxxxx’ /* ’0E 08 80 00 03
00 00 10 00 F0 F0 F0 F0 F0 F0 F1 F0 ’X */, NEXT);
END;

In the example above, DFHENTRY_B62D3C38_296F2687 is based on the entry

variable DFHEI0 that is associated with the real entry DFHEI01. This technique
allows the translator to create a PL/I data descriptor list for each variable entry
name. The PL/I compiler can then check that variable names referenced in EXEC
commands are defined with attributes that are consistent with the attributes defined
by the translator in the data descriptor list. In this example, ENTRY(*,CHAR(4))
specifies that the variable (named NEXT) associated with the TRANSID option
should be a character string with a length of four.

The reference to DFHEI01 is resolved by the inclusion of the DFHELII stub routine
in the linkage editor step of one of the CICS-supplied procedures such as
DFHYITPL.

C and C++
In a C and C++, each EXEC CICS command is translated by the command
translator into a call to the function DFHEXEC. The translator enables this by
inserting the following statements near the start of each translated program:
#pragma linkage(DFHEXEC,OS) /* force OS linkage */
void DFHEXEC(); /* function to call CICS */

The following example shows the output generated by the translator when
processing a simple EXEC CICS RETURN command:
/* EXEC CICS RETURN */
{
DFHEXEC( "\x0E\x08\x00\x2F\x00\x00\x10\x00\xF0\xF0\xF0\xF0\xF1\xF8\xF0\xF0");
}

88 CICS TS for z/OS: CICS Application Programming Guide

The reference to DFHEXEC is resolved by the inclusion of the DFHELII stub routine
in the linkage editor step of one of the CICS-supplied procedures such as
DFHYITDL.

Assembler language
Each EXEC command is translated into an invocation of the DFHECALL macro.

The following example shows the output generated by the translator when
processing a simple EXEC CICS RETURN command:
* EXEC CICS RETURN
DFHECALL =X’0E0800000800001000’

The assembly of the DFHECALL macro invocation shown above generates code
that builds a parameter list addressed by register 1, loads the address of entry
DFHEI1 in register 15, and issues a BALR instruction to call the stub routine.
DS 0H
LA 1,DFHEITPL
LA 14,=x’0E08000008001000’
ST 14,0(,1)
OI 0(1),x’80’
L 15,=V(DFHEI1)
BALR 14,15

The reference to DFHEI1 is resolved by the inclusion of the DFHEAI stub routine in
the linkage editor step of one of the CICS-supplied procedures such as DFHEITAL.
The eyecatcher for DFHEAI in CICS Transaction Server for z/OS, Version 3
Release 1 is DFHYA640, with the release numbers indicating this stub was supplied
with CICS Transaction Server for z/OS, Version 3 Release 1.

The DFHEAI0 stub for assembler application programs is included by the automatic
call facility of the linkage editor or binder utility. It is called by code generated by the
DFHEIENT and DFHEIRET macros to obtain and free, respectively, an assembler
application program’s dynamic storage area. This stub is required only in assembler
application programs; there are no stubs required or supplied to provide an
equivalent function for programs written in the high level languages.

| EXAMPLE Assembler language PROGRAM using LEASM

|
| Figure 11. a simple CICS assembler program.
|

Chapter 8. Translation and compilation 89

| When translated and assembled, it expands to Figure 12:
|
| ASM XOPTS(LEASM)
| DFHEIGBL ,,,LE INSERTED BY TRANSLATOR
| *,&DFHEIDL; SETB 0 1 MEANS EXEC DLI IN PROGRAM 01-DFHEI
| *,&DFHEIDB; SETB 0 1 MEANS BATCH PROGRAM 01-DFHEI
| *,&DFHEIRS; SETB 0 1 MEANS RSECT 01-DFHEI
| *,&DFHEILE; SETB 1 1 MEANS LE MAIN 01-DFHEI
| DFHEISTG DSECT
| DFHEISTG INSERTED BY TRANSLATOR
| ***********************************************************************
| * EXEC INTERFACE DYNAMIC STORAGE *
| ***********************************************************************
| DFHEISTG DSECT EXEC INTERFACE STORAGE @BBAC81A 01-DFHEI
| USING *,DFHEIPLR ESTABLISH ADDRESSABILITY @BBAC81A 01-DFHEI
| *
| **********************************************************************
| * D Y N A M I C S T O R A G E A R E A ( D S A ) *
| **********************************************************************
| *
| CEEDSA DS 0D Just keep the same label for formulae 02-CEEDS
| *
| CEEDSAFLAGS DS XL2 DSA flags 02-CEEDS
| CEEDSALNGC EQU X’1000’ C library DSA 02-CEEDS
| CEEDSALNGP EQU X’0800’ PL/I library DSA 02-CEEDS
| CEEDSAEXIT EQU X’0008’ An Exit DSA 02-CEEDS
| CEEDSAMEMD DS XL2 Member defined 02-CEEDS
| CEEDSABKC DS A Addr of DSA of caller 02-CEEDS
| CEEDSAFWC DS A Addr of DSA of last called rtn 02-CEEDS
| CEEDSAR14 DS F Save area for register 14 02-CEEDS
| CEEDSAR15 DS F Save area for register 15 02-CEEDS
| CEEDSAR0 DS F Save area for register 0 02-CEEDS
| CEEDSAR1 DS F Save area for register 1 02-CEEDS
| CEEDSAR2 DS F Save area for register 2 02-CEEDS
| CEEDSAR3 DS F Save area for register 3 02-CEEDS
| CEEDSAR4 DS F Save area for register 4 02-CEEDS
| CEEDSAR5 DS F Save area for register 5 02-CEEDS
| CEEDSAR6 DS F Save area for register 6 02-CEEDS
| CEEDSAR7 DS F Save area for register 7 02-CEEDS
| CEEDSAR8 DS F Save area for register 8 02-CEEDS
| CEEDSAR9 DS F Save area for register 9 02-CEEDS
| CEEDSAR10 DS F Save area for register 10 02-CEEDS
| CEEDSAR11 DS F Save area for register 11 02-CEEDS
| CEEDSAR12 DS F Save area for register 12 02-CEEDS
| CEEDSALWS DS A Addr of PL/I Language Working Space 02-CEEDS
| CEEDSANAB DS A Addr of next available byte 02-CEEDS
| CEEDSAPNAB DS A Addr of end-of-prolog NAB 02-CEEDS
| DS 4F 02-CEEDS
| CEEDSATRAN DS 0A HPL TxArea or 02-CEEDS
| CEEDSARENT DS A Program reentry address-IPAT 02-CEEDS
| CEEDSACILC DS A C to Fortran ILC save area 02-CEEDS
| CEEDSAMODE DS A Return address of module that 02-CEEDS
| * caused the last mode switch
| DS 2F 02-CEEDS
| CEEDSARMR DS A Addr of language specific 02-CEEDS
| * exception handler
| *
| DS F Reserved 02-CEEDS
| CEEDSAAUTO DS 0D Automatic storage starts here 02-CEEDS
| CEEDSAEND DS 0D End of DSA 02-CEEDS

|
| Figure 12. the Translated assembled version (Part 1 of 8)
|
|

90 CICS TS for z/OS: CICS Application Programming Guide

CEEDSASZ EQU CEEDSAEND-CEEDSA Size of DSA 02-CEEDS
CEEDSA_STDCEEDSA EQU X’0000’ flag values of standard CEE DSA 02-CEEDS
*
*
*
DFHEISA DS 18F SAVE AREA R14-R12 AT 12 OFF @BBAC81A 01-DFHEI
DFHEILWS DS F RESERVED @BBAC81A 01-DFHEI
DFHEINAB DS F RESERVED @BBAC81A 01-DFHEI
DFHEIRS0 DS F RESERVED @BBAC81A 01-DFHEI
DFHEIR13 DS F REGISTER 13 @BBAC81A 01-DFHEI
DFHEIRS1 DS F RESERVED @BBAC81A 01-DFHEI
DFHEIBP DS F EIB POINTER (NOT USED IF BATCH) 01-DFHEI
DFHEICAP DS F COMMAREA POINTER (NOT USED IF BATCH) 01-DFHEI
DFHEIV00 DS H HALFWORD TEMP USED BY DFHECALL 01-DFHEI
DFHEIRS2 DS H RESERVED @BBAC81A 01-DFHEI
DFHEIPL DS 13F PARAMETER LIST @05C 01-DFHEI
DS 51F ALLOW 64 PARAMETERS FOR DLI @L2A 01-DFHEI
* AND IN XA2 ON, FOR EXEC CICS ALSO
DFHEIRS3 DS F RESERVED @L2A 01-DFHEI
DFHEIRS4 DS F RESERVED @L2A 01-DFHEI
DFHEITP1 DS F TEMPORARY POINTER 1 @L2A 01-DFHEI
DFHEITP2 DS F TEMPORARY POINTER 2 @L2A 01-DFHEI
DFHEITP3 DS F TEMPORARY POINTER 3 @L2A 01-DFHEI
DFHEITP4 DS F TEMPORARY POINTER 4 @L2A 01-DFHEI
***********************************************************************
* START DEFINITION OF USER DYNAMIC STORAGE *
***********************************************************************
DFHEIUSR DS 0D ALIGN USER DYNAMIC STORAGE @BBAC81A 01-DFHEI
*
OUTAREA DS CL200 DATA OUTPUT AREA
*
TESTLE CSECT ,
DFHEIENT INSERTED BY TRANSLATOR
***********************************************************************
* *
* CONTROL BLOCK NAME = DFHEIBLK *
* *
* NAME OF MATCHING PL/AS CONTROL BLOCK = None *
* *
* DESCRIPTIVE NAME = %PRODUCT EXEC Interface Block. *
* *
* @BANNER_START 02 *
* Licensed Materials - Property of IBM *
* *
* "Restricted Materials of IBM" *
* *
* 5697-E93 *
* *
* (C) Copyright IBM Corp. 1990, 1993 *
* *
* *
* *
* *
* @BANNER_END *
* *
* STATUS = %XA20 *
* *

Figure 12. the Translated assembled version (Part 2 of 8)

Chapter 8. Translation and compilation 91

* FUNCTION = EXEC Interface Block. *
* *
* The exec interface block contains information on the *
* transaction identifier, the time and date, and the cursor *
* position on a display device. Some of the other fields are *
* set indicating the next action that a program should take *
* in certain circumstances. *
* DFHEIBLK also contains information that will be helpful *
* when a dump is being used to debug a program. *
* This control block is included automatically by an *
* application program using the command-level interface. *
* EISEIBA in the EIS addresses the EIB. *
* *
* *
* *
* NOTES : *
* DEPENDENCIES = S/370 *
* MODULE TYPE = Control block definition *
* PROCESSOR = Assembler *
* *
*-------------------------------------------------------------------- *
* *
* CHANGE ACTIVITY : *
* $SEG(DFHEIBLK),COMP(COMMAND),PROD(%PRODUCT) : *
* *
* PN= REASON REL YYMMDD HDXXIII : REMARKS *
* $L1= 550 %0G 900515 HDFSPC : Add an EIB length equate *
* $D1= I05119 %B1 930226 HDDHDMA : Correct comments for date field *
* $P1= M60581 %B0 900116 HDAEGB : Change for PLXMAP to data areas *
* *
***********************************************************************
* EXEC INTERFACE BLOCK *
***********************************************************************
DFHEIBLK DSECT EXEC INTERFACE BLOCK @BBAC81A 01-DFHEI
USING *,DFHEIBR @BBAC81A 01-DFHEI
EIBTIME DS PL4 TIME IN 0HHMMSS FORMAT @BBAC81A 01-DFHEI
EIBDATE DS PL4 DATE IN 0CYYDDD+ FORMAT, @D1C 01-DFHEI
* where C is the century @D1A
* indicator (0=1900, 1=2000), @D1A
* YY is the year, DDD is the @D1A
* day number and ’+’ is the @D1A
* sign byte (positive) @D1A
EIBTRNID DS CL4 TRANSACTION IDENTIFIER @BBAC81A 01-DFHEI
EIBTASKN DS PL4 TASK NUMBER @BBAC81A 01-DFHEI
EIBTRMID DS CL4 TERMINAL IDENTIFIER @BBAC81A 01-DFHEI
EIBRSVD1 DS H RESERVED @BBAC81A 01-DFHEI
EIBCPOSN DS H CURSOR POSITION @BBAC81A 01-DFHEI
EIBCALEN DS H COMMAREA LENGTH @BBAC81A 01-DFHEI
EIBAID DS CL1 ATTENTION IDENTIFIER @BBAC81A 01-DFHEI
EIBFN DS CL2 FUNCTION CODE @BBAC81A 01-DFHEI
EIBRCODE DS CL6 RESPONSE CODE @BBAC81A 01-DFHEI
EIBDS DS CL8 DATASET NAME @BBAC81A 01-DFHEI
EIBREQID DS CL8 REQUEST IDENTIFIER @BBAC81A 01-DFHEI
EIBRSRCE DS CL8 RESOURCE NAME @BBDIA0U 01-DFHEI
EIBSYNC DS C X’FF’ SYNCPOINT REQUESTED @BBDIA0U 01-DFHEI
EIBFREE DS C X’FF’ FREE REQUESTED @BBDIA0U 01-DFHEI
EIBRECV DS C X’FF’ RECEIVE REQUIRED @BBDIA0U 01-DFHEI

Figure 12. the Translated assembled version (Part 3 of 8)

92 CICS TS for z/OS: CICS Application Programming Guide

EIBSEND DS C RESERVED @BM13417 01-DFHEI
EIBATT DS C X’FF’ ATTACH RECEIVED @BBDIA0U 01-DFHEI
EIBEOC DS C X’FF’ EOC RECEIVED @BBDIA0U 01-DFHEI
EIBFMH DS C X’FF’ FMHS RECEIVED @BBDIA0U 01-DFHEI
EIBCOMPL DS C X’FF’ DATA COMPLETE 01-DFHEI
EIBSIG DS C X’FF’ SIGNAL RECEIVED 01-DFHEI
EIBCONF DS C X’FF’ CONFIRM REQUESTED 01-DFHEI
EIBERR DS C X’FF’ ERROR RECEIVED 01-DFHEI
EIBERRCD DS CL4 ERROR CODE RECEIVED 01-DFHEI
EIBSYNRB DS C X’FF’ SYNC ROLLBACK REQ’D 01-DFHEI
EIBNODAT DS C X’FF’ NO APPL DATA RECEIVED 01-DFHEI
EIBRESP DS F INTERNAL CONDITION NUMBER 01-DFHEI
EIBRESP2 DS F MORE DETAILS ON SOME RESPONSES 01-DFHEI
EIBRLDBK DS CL1 ROLLED BACK 01-DFHEI
*
EIBLENG EQU *-EIBTIME Length of EIB @L1A 01-DFHEI
***********************************************************************
* END OF EXEC INTERFACE BLOCK *
***********************************************************************
DFHEIBR EQU 11 EIB REGISTER @BA02936 01-DFHEI
***********************************************************************
* PROLOG CODE FOR EXEC INTERFACE *
***********************************************************************
*&DFHEICS; CEEENTRY PPA=DFHPPA,MAIN=YES,PLIST=OS,
* BASE=&CODEREG;,
* AUTO=(DFHEIEND-DFHEISTG)
TESTLE CSECT , 02-CEEEN
TESTLE RMODE ANY 02-CEEEN
TESTLE AMODE ANY 02-CEEEN
ENTRY TESTLE 02-CEEEN
PUSH USING 02-CEEEN
DROP , @02A 02-CEEEN
USING *,15 02-CEEEN
B CEEZ0007 02-CEEEN
DC X’00C3C5C5’ 02-CEEEN
CEEY0007 DC A((((DFHEIEND-DFHEISTG)+7)/8)*8) X02-CEEEN
. Size of automatic storage.
DC A(DFHPPA-TESTLE) . Address of PPA for this program 02-CEEEN
B 1(,15) 02-CEEEN
CEEZ0007 EQU * 02-CEEEN
STM 14,12,CEEDSAR14-CEEDSA(13) 02-CEEEN
L 2,CEEINPL0007 5@01D @01C 02-CEEEN
L 15,CEEINT0007 @01C 02-CEEEN
DROP 15 @01A 02-CEEEN
BALR 14,15 02-CEEEN
LR 2,1 02-CEEEN
L 14,752(,12) 02-CEEEN
OI 8(14),X’80’ 02-CEEEN
BALR 3,0 @01A 02-CEEEN
USING *,3 @01A 02-CEEEN
L 3,CEEOEPV0007 @01A 02-CEEEN
POP USING @01A 02-CEEEN
USING TESTLE,3 @01A 02-CEEEN
L 1,CEEDSANAB-CEEDSA(,13) Get the current NAB 02-CEEEN
L 0,CEEY0007 02-CEEEN
ALR 0,1 Compute new value. 02-CEEEN
CL 0,CEECAAEOS-CEECAA(,12) Compare with EOS. 02-CEEEN

Figure 12. the Translated assembled version (Part 4 of 8)

Chapter 8. Translation and compilation 93

BNH CEEX0007 02-CEEEN
L 15,CEECAAGETS-CEECAA(,12) Get address overflow routine 02-CEEEN
BALR 14,15 Get another stack segment. 02-CEEEN
LR 1,15 02-CEEEN
B CEEX0007 Branch around statics @01A 02-CEEEN
CEEINPL0007 DC A(CEEINPL) @01A 02-CEEEN
CEEINT0007 DC V(CEEINT) @01A 02-CEEEN
CEEOEPV0007 DC A(TESTLE) @01A 02-CEEEN
CEEX0007 EQU * 02-CEEEN
ST 13,CEEDSABKC-CEEDSA(,1) Set back chain. 02-CEEEN
ST 0,CEEDSANAB-CEEDSA(,1) Set new NAB value 02-CEEEN
XC CEEDSAFLAGS-CEEDSA(,1),CEEDSAFLAGS-CEEDSA(1) . Clear 02-CEEEN
ST 1,CEEDSAFWC-CEEDSA(,13) Set forward chain. 02-CEEEN
LR 13,1 Set save area address 02-CEEEN
USING CEEDSA,13 Addresability to SF V1R2M0 02-CEEEN
MVC CEEDSALWS,CEECAALWS-CEECAA(12) Get LWS addr V1R2M0 02-CEEEN
LR 1,2 02-CEEEN
BAL 1,*+8 @L2A 01-DFHEI
* The following gives an assembler message if DFHEISTG is too big @P7A
DS 0S((DFHEISTG+65264-DFHEIEND-4096)/4096) @04C 01-DFHEI
DC AL2(DFHEIEND-DFHEISTG) LENGTH OF STORAGE @L2A 01-DFHEI
DC H’0’ Parameter list version number @P6C 01-DFHEI
***********************************************************************
* ESTABLISH DATA ADDRESSIBILITY *
***********************************************************************
DFHEIPLR EQU 13 PARAMETER LIST REGISTER @BBAC81A 01-DFHEI
LR DFHEIPLR,15 @BBAC81A 01-DFHEI
USING DFHEISTG,13 @BBAC81A 01-DFHEI
MVC DFHEIBP(L’DFHEIBP+L’DFHEICAP),0(1) @D3AX01-DFHEI
COPY EIB AND CA PTRS @D3A
***********************************************************************
* ESTABLISH EIB ADDRESSIBILITY *
***********************************************************************
L DFHEIBR,DFHEIBP @BBAC81A 01-DFHEI
USING DFHEIBLK,DFHEIBR @BBAC81A 01-DFHEI
***********************************************************************
* END OF PROLOG CODE FOR EXEC INTERFACE *
***********************************************************************
MVC OUTAREA(40),MSG1
MVC OUTAREA(4),EIBTRMID
* EXEC CICS SEND TEXT FROM(OUTAREA) LENGTH(43) FREEKB ERASE
DFHECALL =X’180660000800C20000082204000020’,,(______RF,OUTAREA*
),(FB_2,=Y(43))
***********************************************************************
DS 0H 01-DFHEC
LA 1,DFHEIPL 01-DFHEC
LA 14,=X’180660000800C20000082204000020’ 01-DFHEC
SR 15,15 01-DFHEC
LA 0,OUTAREA 01-DFHEC
STM 14,0,0(1) 01-DFHEC
LA 14,=Y(43) 01-DFHEC
ST 14,12(,1) 01-DFHEC
OI 12(1),X’80’ LAST ARGUMENT 01-DFHEC
L 15,=V(DFHEI1) 01-DFHEC
BALR 14,15 INVOKE EXEC INTERFACE 01-DFHEC
***********************************************************************
* EXEC CICS RECEIVE

Figure 12. the Translated assembled version (Part 5 of 8)

94 CICS TS for z/OS: CICS Application Programming Guide

DFHECALL =X’040200000800000014000040000000’
***********************************************************************
DS 0H 01-DFHEC
LA 1,DFHEIPL 01-DFHEC
LA 14,=X’040200000800000014000040000000’ 01-DFHEC
ST 14,0(,1) 01-DFHEC
OI 0(1),X’80’ LAST ARGUMENT 01-DFHEC
L 15,=V(DFHEI1) 01-DFHEC
BALR 14,15 INVOKE EXEC INTERFACE 01-DFHEC
***********************************************************************
MVC OUTAREA(13),MSG2
* EXEC CICS SEND TEXT FROM(OUTAREA) LENGTH(13) FREEKB ERASE
DFHECALL =X’180660000800C20000082204000020’,,(______RF,OUTAREA*
),(FB_2,=Y(13))
***********************************************************************
DS 0H 01-DFHEC
LA 1,DFHEIPL 01-DFHEC
LA 14,=X’180660000800C20000082204000020’ 01-DFHEC
SR 15,15 01-DFHEC
LA 0,OUTAREA 01-DFHEC
STM 14,0,0(1) 01-DFHEC
LA 14,=Y(13) 01-DFHEC
ST 14,12(,1) 01-DFHEC
OI 12(1),X’80’ LAST ARGUMENT 01-DFHEC
L 15,=V(DFHEI1) 01-DFHEC
BALR 14,15 INVOKE EXEC INTERFACE 01-DFHEC
***********************************************************************
* EXEC CICS RETURN
DFHECALL =X’0E0800000800001000’
***********************************************************************
DS 0H 01-DFHEC
LA 1,DFHEIPL 01-DFHEC
LA 14,=X’0E0800000800001000’ 01-DFHEC
ST 14,0(,1) 01-DFHEC
OI 0(1),X’80’ LAST ARGUMENT 01-DFHEC
L 15,=V(DFHEI1) 01-DFHEC
BALR 14,15 INVOKE EXEC INTERFACE 01-DFHEC
***********************************************************************
*
MSG1 DC C’xxxx: ASM program invoked. ENTER TO END.’
MSG2 DC C’PROGRAM ENDED’
DFHEIRET INSERTED BY TRANSLATOR
***********************************************************************
* EPILOG CODE FOR EXEC INTERFACE *
***********************************************************************
DS 0H @BBAC81A 01-DFHEI
LA 1,CEET0014 Get address of termination list 02-CEETE
L 15,=V(CEETREC) Get address of termination rtn 02-CEETE
BALR 14,15 Call termination routine. 02-CEETE

CEET0014 DC A(*+8) Parm 1 02-CEETE

DC A(*+8+X’80000000’) Parm 2 02-CEETE
DC A(0) Enc_Modifier 02-CEETE
DC A(0) Return code. 02-CEETE
CEEMAIN CSECT 02-CEETE
CEEMAIN RMODE ANY 02-CEETE
CEEMAIN AMODE ANY 02-CEETE

Figure 12. the Translated assembled version (Part 6 of 8)

Chapter 8. Translation and compilation 95

DC A(TESTLE) @04A 02-CEETE
DC F’0’ 02-CEETE
TESTLE CSECT 02-CEETE
***********************************************************************
* END OF EPILOG CODE FOR EXEC INTERFACE *
***********************************************************************
LTORG , @BBAC81A 01-DFHEI
=V(DFHEI1)
=V(CEETREC)
=Y(43)
=Y(13)
=X’180660000800C20000082204000020’
=X’040200000800000014000040000000’
=X’0E0800000800001000’
DS 0H @F8E1S @L1C 01-DFHEI
DFHEISTG INSERTED BY TRANSLATOR
DFHEIEND INSERTED BY TRANSLATOR
*
**********************************************************************
* P R O G R A M P R O L O G A R E A 1 ( P P A 1) *
**********************************************************************
*
PPA10018 DS 0F 02-CEEPP
DFHPPA DS 0F 02-CEEPP
DC AL1(PPANL0018-*) Offset to the entry name length 02-CEEPP
DC X’CE’ LE/370 Indicator. 02-CEEPP
DC B’10100000’ . PPA flags 02-CEEPP
* Bit 0 0 = Internal Procedure
* 1 = External Procedure
* Bit 1 0 = Primary Entry Point
* 1 = Secondary Entry Point
* Bit 2 0 = Block doesn’t have a DSA
* 1 = Block has a DSA
* Bit 3 0 = compiled object
* 1 = library object
* Bit 4 0 = sampling interrupts to library
* 1 = sampling interrupts to code
* Bit 5 0 = not an exit DSA
* 1 = Exit DSA
* Bit 6 0 = own exception model
* 1 = inherited (callers) exception model
* Bit 7 Reserved
DC X’00’ Member flags 02-CEEPP
DC A(PPA20018) Addr of Compile Unit Block (PPA2) 02-CEEPP
DC A(0) 02-CEEPP
DC A(0) Data Descriptors for this entry point 02-CEEPP
DS 0H 02-CEEPP
PPANL0018 DC AL2(6) . Length of Entry Point Name 02-CEEPP
DC CL6’TESTLE’ . Entry Point Name 02-CEEPP
CEEINPL DS 0D 02-CEEPP
DC A(PPA2M0018) 02-CEEPP
DC A(CEEINPLSTST-CEEINPL) 02-CEEPP
CEEINPLSTST DS 0F 02-CEEPP
DC X’00’ Control Level @01A 02-CEEPP
DC X’00’ ENCLAVE=NO @01A 02-CEEPP
DC X’00’ @01A 02-CEEPP
DC X’07’ Number of items. @01C 02-CEEPP

Figure 12. the Translated assembled version (Part 7 of 8)

96 CICS TS for z/OS: CICS Application Programming Guide

DC A(PPA2M0018) . A of A(first entry point in comp unit) 02-CEEPP
DC V(CEESTART) . A(Address of CEESTART) 02-CEEPP
DC V(CEEBETBL) 02-CEEPP
DC A(15) . Memeber id 02-CEEPP
DC A(0) 02-CEEPP
DC XL4’00070000’ . EXECOPS(ON), PLIST 02-CEEPP
DS 0H 02-CEEPP
*
**********************************************************************
* P R O G R A M P R O L O G A R E A 2 ( P P A 2) *
**********************************************************************
*
EXTRN CEESTART 02-CEEPP
PPA20018 DS 0F 02-CEEPP
DC AL1(15) Member ID 02-CEEPP
DC AL1(0) Sub ID 02-CEEPP
DC AL1(0) Member defined 02-CEEPP
DC AL1(1) Level of PPAx control blocks 02-CEEPP
PPA2S0018 DC A(CEESTART) A(CEESTART for this load module) 02-CEEPP
DC A(0) A(Compile Debug Information (CDI) ) 02-CEEPP
DC A(CEETIMES-PPA20018) A(Offset to time stamp) 02-CEEPP
PPA2M0018 DC A(TESTLE) . A(first entry point in comp. unit) 02-CEEPP
*
**********************************************************************
* T I M E S T A M P *
**********************************************************************
*
* Time Stamp
*,Time Stamp = 2004/06/17 08:51:00 02-CEEPP
*,Version 1 Release 1 Modification 0 02-CEEPP
CEETIMES DS 0F 02-CEEPP
DC CL4’2004’ Year 02-CEEPP
DC CL2’06’ Month 02-CEEPP
DC CL2’17’ Day 02-CEEPP
DC CL2’08’ Hours 02-CEEPP
DC CL2’51’ Minutes 02-CEEPP
DC CL2’00’ Seconds 02-CEEPP
DC CL2’1’ Version 02-CEEPP
DC CL2’1’ Release 02-CEEPP
DC CL2’0’ Modification 02-CEEPP
***********************************************************************
* C O M M O N A N C H O R A R E A ( C A A ) *
***********************************************************************
***********************************************************************
***********************************************************************
LEPTRLEN EQU 4 03-CEEDN
*
CEECAA DSECT , CAA mapping 02-CEECA

(Definition of LE CAA removed)

* TERMINATE DEFINITION OF DYNAMIC STORAGE *

DFHEISTG DSECT @BBAC81A 01-DFHEI
ORG 01-DFHEI
DFHEIEND DS 0X END OF DYNAMIC STORAGE @BBAC81A 01-DFHEI
END

| Figure 12. the Translated assembled version (Part 8 of 8)

Chapter 8. Translation and compilation 97

98 CICS TS for z/OS: CICS Application Programming Guide
Chapter 9. Installing application programs
This section describes what you have to do to install an application program to run
under CICS. Installation of a CICS application program involves translation and
compilation of the source statements, and link-edit of the resulting object modules
into CICS libraries.

An application program generally means any user program that uses the CICS
command-level application programming interface (API). Such programs can also
use:
v SQL statements
v DLI requests
v Common programming interface (CPI) statements
v SAA Resource Recovery statements
v External CICS interface commands

Note: If you are developing application programs to use the CICS dynamic
| transaction routing facility, use the CICS Interdependency Analyzer to detect
whether the programs are likely to cause intertransaction affinity. See
Chapter 15, “Affinity,” on page 219 for a description of intertransaction
affinity.

This chapter includes:

v “Program installation roadmap”
v “Defining MVS residence and addressing modes” on page 101
v “Running application programs in the RDSAs” on page 103
v “Using BMS map sets in application programs” on page 106
v “Using the CICS-supplied procedures to install application programs” on page
106
v “Including the CICS-supplied interface modules” on page 108
v “Installing assembler language application programs” on page 108
v “Installing COBOL application programs” on page 110
v “Installing PL/I application programs” on page 114
v “Installing C application programs” on page 117
v “Using your own job streams” on page 119

Program installation roadmap

The following steps are required to install application programs to run under CICS.
For detailed information about using the CICS-supplied procedures to install
application programs, see “Using the CICS-supplied procedures to install application
programs” on page 106. To use your own JCL to install application programs, see
“Using your own job streams” on page 119.
1. Compile your program source if you are using a compiler with an integrated
translator.
2. If your compiler does not translate CICS commands, you will need to translate
the program source code, turning CICS commands into calls that are
understood by the compiler, then compile or assemble the translator output to
produce object code.
Notes:
a. If your program does not use CICS commands and is only invoked by a
running transaction (and never directly by CICS task initiation), no translator
step is needed.

© Copyright IBM Corp. 1989, 2005 99

b. CICS command-level programs that access DL/I services through either the
DL/I CALL or EXEC DLI interfaces must also be translated. Applications that
access IBM DATABASE 2 (DB2) services using the EXEC SQL interface
need an additional precompilation step. For information about this step, see
the IBM DATABASE 2 Application Programming and SQL Guide.
3. Link-edit the object module to produce a load module, which you store in an
application load library that is concatenated to the DFHRPL DD statement of the
CICS startup job stream. Additional INCLUDE statements are required for
applications that access DB2 services using the EXEC SQL interface. For
information about these extra statements, see the IBM DATABASE 2 Application
Programming and SQL Guide.
4. Create resource definition entries, in the CSD, for any transaction that calls the
program, and install them..
5. Do one of the following:
v If you are using program autoinstall, ensure that the autoinstall
user-replaceable module can correctly install a resource definition for the
program.
v If you are not using program autoinstall, create a resource definition entry in
the CSD for the program, and install it.

References to the CSA or to the TCA are not allowed. You can specify YES for the
system initialization parameter DISMACP to cause CICS to disable any transaction
whose program invokes an obsolete CICS macro or references the CSA or the
TCA.

CICS provides a utility program, DFHMSCAN, to identify the macro-level programs

used by your CICS applications. For information about using the DFHMSCAN utility
to identify macro-level programs, see theCICS Operations and Utilities Guide.

Preparing for program installation

Points to consider when installing application programs.
v If you want your application program to use CPI Communications or SAA
Resource Recovery, make the appropriate interface modules available to your
program. For information about the CPI Communications interface module and
the SAA Resource Recovery interface module, see “The CICS-supplied interface
modules” on page 86.
v If you want your application program to reside in the MVS link pack area (LPA),
specify appropriate options when installing your program. Options appropriate to
each language are given for the sample job streams in the following sections. For
information on preparing programs to run in the link pack area (LPA), see
“Running applications in the link pack area” on page 102.
For information on preparing programs to run in the read-only DSAs, see
“Running application programs in the RDSAs” on page 103.
v If you want your application program to use BMS maps, first prepare the map
sets. For more information, see “Using BMS map sets in application programs”
on page 106.

100 CICS TS for z/OS: CICS Application Programming Guide

Defining MVS residence and addressing modes
This section describes the effect of the MVS residence and addressing modes on
application programs, how you can change the modes, and how you can make
application programs permanently resident. An application written to run on
MVS/370 can run on any MVS system, if it is link-edited with the AMODE(24) and
RMODE(24) options.

A command-level program can reside above 16MB, and address areas above
16MB. The program can contain EXEC CICS, EXEC DLI, and CALL DL/I
commands.

Establishing a program’s addressing mode

Every program that executes in MVS is assigned two attributes: an addressing
mode (AMODE), and a residency mode (RMODE). AMODE specifies the
addressing mode in which your program is designed to receive control. Generally,
your program is designed to execute in that mode, although you can switch modes
in the program, and have different AMODE attributes for different entry points within
a load module. The RMODE attribute indicates where in virtual storage your
program can reside. Valid AMODE and RMODE specifications are:

AMODE(24) Specifies 24-bit addressing mode.

AMODE(31) Specifies 31-bit addressing mode.
AMODE(ANY) Specifies either 24- or 31-bit addressing mode.
RMODE(24) Indicates that the module must reside in virtual storage below 16MB. You
can specify RMODE(24) for 31-bit programs that have 24-bit
dependencies.
RMODE(ANY) Indicates that the module can reside anywhere in virtual storage.

Note: C or C++ language programs must be link-edited with AMODE(31).

If you do not specify any AMODE or RMODE attributes for your program, MVS
assigns the system defaults AMODE(24) and RMODE(24). To override these
defaults, you can specify AMODE and RMODE in one or more of the following
places. Assignments in this list overwrite assignments later in the list.
1. On the link-edit MODE control statement:
MODE AMODE(31),RMODE(ANY)
2. Either of the following:
a. In the PARM string on the EXEC statement of the link-edit job step:
//LKED EXEC PGM=IEWL,PARM=’AMODE(31),RMODE(ANY),..’
b. On the LINK TSO command, which causes processing equivalent to that of
the EXEC statement in the link-edit step.
3. On AMODE or RMODE statements within the source code of an assembler
program. (You can also set these modes in COBOL by means of the compiler
options; for information about COBOL compiler options, see the relevant
application programming guide for your COBOL compiler.)

CICS address space considerations

Table 6 gives the valid combinations of the AMODE and RMODE attributes and
their effects:

Chapter 9. Installing application programs 101

Table 6. Valid AMODE and RMODE specifications and their effects
AMODE RMODE Residence Addressing
24 24 Below 16MB 24-bit mode
31 24 Below 16MB 31-bit mode
ANY 24 Below 16MB 31-bit mode
31 ANY Above 16MB 31-bit mode

The following example shows link-edit control statements for a program coded to
31-bit standards:
//LKED.SYSIN DD *
MODE AMODE(31),RMODE(ANY)
NAME anyname(R) ("anyname" is your load module name)
/*
//

Making programs permanently resident

If you define a program in the CSD with the resident attribute, RESIDENT(YES), it
is loaded on first reference. This applies to programs link-edited with either
RMODE(ANY) or RMODE(24). However, be aware that the storage compression
algorithm that CICS uses does not remove resident programs.

If there is not enough storage for a task to load a program, the task is suspended
until enough storage becomes available. If any of the DSAs get close to being short
on storage, CICS frees the storage occupied by programs that are not in use. (For
more information about the dynamic storage areas in CICS, see the CICS System
Definition Guide.)

Instead of making RMODE(24) programs resident, you can make them non-resident
and use the library lookaside (LLA) function. The space occupied by such a
program is freed when its usage count reaches zero, making more virtual storage
available. LLA keeps its library directory in storage and stages (places) copies of
LLA-managed library modules in a data space managed by the virtual lookaside
facility (VLF). CICS locates a program module from LLA’s directory in storage,
rather than searching program directories on DASD. When CICS requests a staged
module, LLA gets it from storage without any I/O.

Running applications in the link pack area

Programs written in assembler language, C, COBOL, or PL/I , can reside in the link
pack area (LPA). To do so, they must be read-only and have been link-edited with
the RENT and REFR options. Other requirements are as follows:
Assembler
Use the RENT assembler option.
C Use the RENT compiler option.
COBOL
Do not overwrite WORKING STORAGE. (The CICS translator generates a CBL
statement with the required compiler RENT option (unless you specify the
translator option NOCBLCARD).
PL/I
Do not overwrite STATIC storage. (The CICS translator inserts the required
REENTRANT option into the PROCEDURE statement.)

102 CICS TS for z/OS: CICS Application Programming Guide

If you want CICS to use modules that you have written to these standards, and
installed in the LPA, specify USELPACOPY(YES) on the program resource
definitions in the CSD.

For information about installing CICS modules in the LPA, see the CICS Transaction
Server for z/OS Installation Guide.

Running application programs in the RDSAs

Programs that are eligible to reside above 16MB, and are read-only, can reside in
the CICS extended read-only DSA (ERDSA). Therefore, to be eligible for the
ERDSA, programs must be:
v Properly written to read-only standards
v Written to 31-bit addressing standards
v Link-edited with the RENT attribute and the RMODE(ANY) residency attribute

Programs that are not eligible to reside above 16MB, and are read-only, can reside
in the CICS read-only DSA (RDSA) below 16MB. Therefore, to be eligible for the
RDSA, programs must be:
v Properly written to read-only standards
v Link-edited with the RENT attribute

Note: When you are running CICS with RENTPGM=PROTECT specified as a

system initialization parameter, the RDSAs are allocated from key-0
read-only storage.

Programs link-edited with RENT and RMODE(ANY) are automatically loaded by

CICS into the ERDSA.

ERDSA requirements for the specific languages are described as follows.

Assembler
If you want CICS to load your assembler programs in the ERDSA, assemble and
link-edit them with the following options:
1. The RENT assembler option
2. The link-edit RENT attribute
3. The RMODE(ANY) residency mode

Note: If you specify these options, ensure that the program is truly read-only (that
is, does not modify itself in any way—for example, by writing to static
storage), otherwise storage exceptions occur. The program must also be
written to 31-bit addressing standards. See the CICS Problem Determination
Guide for some possible causes of storage protection exceptions in
programs resident in the ERDSA.

The CICS-supplied procedure, DFHEITAL, has a LNKPARM parameter that

specifies the XREF and LIST options only. To link-edit an ERDSA-eligible program,
override LNKPARM from the calling job, specifying the RENT and RMODE(ANY)
options in addition to any others you require.

For example:
//ASMPROG JOB 1,user_name,MSGCLASS=A,CLASS=A,NOTIFY=userid
//EITAL EXEC DFHEITAL,
.

Chapter 9. Installing application programs 103

(other parameters as necessary)
.
// LNKPARM=’LIST,XREF,RMODE(ANY),RENT’

Note: The CICS EXEC interface module for assembler programs (DFHEAI)
specifies AMODE(ANY) and RMODE(ANY). However, because the
assembler defaults your application to AMODE(24) and RMODE(24), the
resulting load module also becomes AMODE(24) and RMODE(24).

If you want your application program link-edited as AMODE(31) and

RMODE(ANY), you are recommended to use appropriate statements in your
assembler program. For example:
MYPROG CSECT
MYPROG AMODE 31
MYPROG RMODE ANY

There are two ways of setting AMODE and RMODE:

v You can set the required AMODE and RMODE specification by using
link-edit (or binder) control information in the JCL PARM keyword. For
example:
//EITAL EXEC DFHEITAL,
LNKPARM=’LIST,XREF,RENT,AMODE(31),RMODE(ANY)’
v Alternatively, you can use the MODE control statement in the SYSIN
dataset in the link-edit, or the binder step in your JCL.
When using the binder, you may see unexpected warning messages about
conflicting AMODE and RMODE specifications.

C and C/++
If you want CICS to load your C and C++ programs into the ERDSA, compile and
link-edit them with:
1. The RENT compiler option.

| The CICS-supplied procedures DFHYITDL or DFHYITFL (for C) and DFHYITEL or

| DFHYITGL (for C++) have a LNKPARM parameter that specifies a number of
link-edit options. To link-edit an ERDSA-eligible program, override this parameter
from the calling job, and add RENT to the other options you require. You do not
need to add the RMODE(ANY ) option, because the CICS EXEC interface module
for C (DFHELII) is link-edited with AMODE(31) and RMODE(ANY). Therefore, your
program is link-edited as AMODE(31) and RMODE(ANY) automatically when you
include the CICS EXEC interface stub, see “The CICS-supplied interface modules”
on page 86.

The following sample job statements show the LNKPARM parameter with the RENT
option added:
//CPROG JOB 1,user_name,MSGCLASS=A,CLASS=A,NOTIFY=userid
//YITDL EXEC DFHYITDL,
.
(other parameters as necessary)
.
// LNKPARM=’LIST,MAP,LET,XREF,RENT’

104 CICS TS for z/OS: CICS Application Programming Guide

COBOL
If you use the integrated CICS translator then the compile requires the RENT
compiler option, so no CBL card needs to be added during translation. COBOL
programs that use a separate translation step are automatically eligible for the
ERDSA, because:
v The translator option, CBLCARD (the default), causes the required compiler
option, RENT, to be included automatically on the CBL statement generated by
the CICS translator. If you use the translator option, NOCBLCARD, you can
specify the RENT option either on the PARM statement of the compile job step,
or by using the COBOL macro IGYCOPT to set installation-defined options.
v The COBOL compiler automatically generates code that conforms to read-only
and 31-bit addressing standards.
v The CICS EXEC interface module for COBOL (DFHELII) is link-edited with
AMODE(31) and RMODE(ANY). Therefore, your program is link-edited as
AMODE(31) and RMODE(ANY) automatically when you include the CICS EXEC
interface interface stub, see “The CICS-supplied interface modules” on page 86.

You also need to specify the reentrant attribute to link-edit. The CICS-supplied
procedure, DFHYITVL, has a LNKPARM parameter that specifies a number of
link-edit options. To link-edit an ERDSA-eligible program, override this parameter
from the calling job, and add RENT to any other options you require. For example:
//COBPROG JOB 1,user_name,MSGCLASS=A,CLASS=A,NOTIFY=userid
//YITVL EXEC DFHYITVL,
.
(other parameters as necessary)
.
// LNKPARM=’LIST,XREF,RENT’

PL/I
CICS PL/I programs are generally eligible for the ERDSA, provided they do not
change static storage. The following requirements are enforced, either by CICS or
PL/I:
v The required REENTRANT option is included automatically, by the CICS
translator, on the PL/I PROCEDURE statement.
v The PL/I compiler automatically generates code that conforms to 31-bit
addressing standards.
v The CICS EXEC interface module for PL/I (DFHELII) is link-edited with
AMODE(31) and RMODE(ANY). Therefore, your program is link-edited as
AMODE(31) and RMODE(ANY) automatically when you include the CICS EXEC
interface stub, see “The CICS-supplied interface modules” on page 86.

You also need to specify the reentrant attribute to the link-edit. The CICS-supplied
procedure, DFHYITPL, has a LNKPARM parameter that specifies a number of
link-edit options. To link-edit an ERDSA-eligible program, override this parameter
from the calling job, and add RENT to any other options you require. For example:
//PLIPROG JOB 1,user_name,MSGCLASS=A,CLASS=A,NOTIFY=userid
//YITPL EXEC DFHYITPL,
.
(other parameters as necessary)
.
// LNKPARM=’LIST,XREF,RENT’

Note: Do not specify the RENT attribute on the link-edit step unless you have
ensured the program is truly read-only (and does not, for example, write to
static storage), otherwise storage exceptions will occur. See the CICS

Chapter 9. Installing application programs 105

Problem Determination Guide for some possible causes of storage protection
exceptions in programs resident in the ERDSA.

Using BMS map sets in application programs

This section describes what to do to use BMS map sets in application programs.

Before you install an application program to run under CICS:

v Create any BMS map sets used by the program, as described in Chapter 10,
“Installing map sets and partition sets,” on page 125.
v Include the physical map sets (used by BMS in its formatting activities) in a
library that is in the DFHRPL concatenation.
v Either include the symbolic map sets (copied into the application programs) in a
user copy library, or insert them directly into the application program source.

The DFHMAPS procedure writes the symbolic map set output to the library
specified on the DSCTLIB parameter, which defaults to the
CICSTS31.CICS.SDFHMAC library. If you want to include symbolic map sets in a
user copy library:
v Specify the library name by the DSCTLIB=name operand on the EXEC statement
for the DFHMAPS procedure used to install physical and symbolic map sets
together.
v Include a DD statement for the user copy library in the SYSLIB concatenation of
the job stream used to assemble and compile the application program.
If you choose to let the DFHMAPS procedure write the symbolic map sets to the
CICSTS31.CICS.SDFHMAC library (the default), include a DD statement for the
CICSTS31.CICS.SDFHMAC library in the SYSLIB concatenation of the job
stream used to compile the application program. This is not necessary for the
DFHEITAL procedure used to assemble assembler-language programs, because
these jobs already include a DD statement for the CICSTS31.CICS.SDFHMAC
library in the SYSLIB concatenation.
v For PL/I, specify a library that has a block size of 32760 bytes. This is necessary
to overcome the blocksize restriction on the PL/I compiler.

For more information about installing map sets, see Chapter 10, “Installing map sets
and partition sets,” on page 125. For information about writing programs to use
BMS services, seeChapter 31, “Basic mapping support,” on page 449.

Using the CICS-supplied procedures to install application programs

CICS supplies job control statements (JCL) for the translate (if required), compile,
and link-edit steps, in separate cataloged procedures for each programming
language supported. After CICS is installed, you should copy these procedures,
installed in the CICSTS31.CICS.SDFHPROC library, into a procedure library.

Each procedure has a name of the form DFHwxTyL, where the variables w, x, and
y depend on the type of program (EXCI batch or CICS online), the type of compiler,
and the programming language. Using the preceding naming convention, the
procedure names are given in Table 7 on page 107.

106 CICS TS for z/OS: CICS Application Programming Guide

Table 7. Procedures for installing application programs
Language Language Environment-conforming non-Language
compilers Environment-conforming
compilers
Stand-alone EXCI Integrated Stand-alone EXCI
translator translator translator
Assembler - - - DFHEITAL DFHEXTAL
C DFHYITDL DFHYXTDL - - -
(see note 1)
| C using the DFHYITFL - - - -
| XPLINK (see note 2)
| compiler
| option
C++ DFHYITEL DFHYXTEL - - -
(see note 1)
| C++ using DFHYITGL - - - -
| the XPLINK (see note 2)
| compiler
| option
COBOL (see DFHYITVL DFHYXTVL DFHZITCL - -
note 3) (see note 2)
PL/I (see DFHYITPL DFHYXTPL DFHZITPL - -
note 4) (see note 2) (see note 2)

Notes:
1. DFHYITEL may also be used for C as long as you specify the correct name of
the C compiler on the COMPILER parameter.
# 2. The output library for the generated module is a PDSE (not a PDS).
# 3. DFHZITCL is the recommended procedure for compiling COBOL modules,
# because it uses the version of the Enterprise COBOL compiler which includes
# the integrated CICS translator.
# 4. DFHZITPL is the recommended procedure for compiling PL/I modules as it uses
# the version of the Enterprise PL/I compiler which includes the integrated CICS
# translator.
# 5. For programs that issue EXEC DLI commands in a batch environment under
# Language Environment (IMS routines), use the following special procedures:
# DFHYBTPL
# PL/I application programs
# DFHYBTVL
# COBOL application programs

Installing programs in load library secondary extents

CICS supports load library secondary extents that are created while CICS is
running. If you define libraries in the DFHRPL concatenation with primary and
secondary extents, and secondary extents are added as a result of link-editing into
the DFHRPL library while CICS is running, the CICS loader detects the occurrence,
closes, and then reopens the library. This means that you can introduce new
versions using the CEMT NEWCOPY command, even if the new copy of the
program has caused a new library extent.

Chapter 9. Installing application programs 107

However, this can increase the search time when loading modules from the
secondary extents. You should avoid using secondary extents if possible.

Note: If you are using DFHXITPL, the SYSLMOD DD statement in the binder step
must refer to a PDSE (not a PDS as for the older PL/I compilers).

Including the CICS-supplied interface modules

The CICS-supplied procedures to install your online application programs in a CICS
library specify the CICS library member that contains the INCLUDE statement for
the appropriate language EXEC interface module. For example, the DFHYITVL
procedure uses the following statements:
//COPYLINK EXEC PGM=IEBGENER,COND=(7,LT,COB)
//SYSUT1 DD DSN=&INDEX..SDFHSAMP(&STUB),DISP=SHR
//SYSUT2 DD DSN=&&COPYLINK,DISP=(NEW,PASS),
// DCB=(LRECL=80,BLKSIZE=400,RECFM=FB),
// UNIT=&WORK,SPACE=(400,(20,20))
//SYSPRINT DD SYSOUT=&OUTC
//SYSIN
. DD DUMMY
.
.
//SYSLIN DD DSN=&&COPYLINK,DISP=(OLD,DELETE)
// DD DSN=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN

In this COBOL example, the symbolic parameter STUB defaults to DFHEILID. The
DFHEILID member contains the statement INCLUDE SYSLIB(DFHELII).

The supplied procedures for PL/I and C also refer to DFHEILID, which means that
the DFHELII stub is used.

If your application program is to use CPI Communications or the SAA Resource

Recovery facility, do one of the following:
v Add appropriate INCLUDE statements to the LKED.SYSIN override in the job
used to call the CICS-supplied procedure to install your application program. Add
the following INCLUDE statements:
– INCLUDE SYSLIB(DFHCPLC) if your program uses CPI Communications
– INCLUDE SYSLIB(DFHCPLRR) if your program uses SAA Resource
Recovery

Warning messages may appear during the link-edit step, indicating DUPLICATE
definitions for the DFHEI1 entry. You may ignore these messages.

For more information about link-edit requirements, see “Using your own job
streams” on page 119.

Installing assembler language application programs

You can use the DFHEITAL or DFHEXTAL procedure to translate, assemble, and
link-edit application programs written in assembler language.

You can use the sample job control statements shown in Figure 13 on page 109 to
process application programs written in assembler language. In the procedure
name, “x” depends on whether your programs are CICS application programs or
EXCI batch programs. For the names of the CICS-supplied procedures, see Table 7
on page 107

108 CICS TS for z/OS: CICS Application Programming Guide

//jobname JOB accounting info,name,MSGLEVEL=1
// EXEC PROC=DFHExTAL 1
//TRN.SYSIN DD *
*ASM XOPTS(translator options . . .) 2
.
assembler-language source statements
.
/*
//LKED.SYSIN DD *
NAME anyname(R)
/*
//

where anyname is your load module name

Figure 13. Sample job control statements to call the DFHExTAL procedures

Notes:

1 If you are installing a program into either of the read-only DSAs, see “Running
application programs in the RDSAs” on page 103 for more details.

If you are installing a program that is to be used from the LPA, add:
v RENT to the PARM options in the EXEC statement for the ASM step of the
DFHEITAL procedure
v RENT and REFR options to the LNKPARM parameter on the call to the
DFHEITAL procedure
(See “Running applications in the link pack area” on page 102.)

2 For information about the translator options you can include on the XOPTS
statement, see “Defining translator options” on page 74.

Figure 14 on page 110 shows the Assembler source program processed by the
command level translator to produce a translator listing and an output file. This
output file is then processed by the Assembler, with reference to CICS.SDFHMAC,
to produce an assembler listing and a further output file.This output file is then
processed by the linkage editor, with reference to CICS.SDFHLOAD to produce a
linkage editor listing and a load module that is stored in CICS.SDFHLOAD.

Chapter 9. Installing application programs 109

Assembler-language
source

Translator
Command-level listing
language translator

Intermediate
storage
Assembly
Assembler listing
CICS.
SDFHMAC

Intermediate
storage

Linkage Editor
Linkage Editor listing
CICS.
SDFHLOAD

CICS.
SDFHLOAD

Figure 14. Installing assembler language programs using the DFHEITAL procedure

Installing COBOL application programs

Figure 15 on page 111 illustrates the flow of control in the cataloged procedures for
COBOL and PL/I programs that require a separate translator step. If you use an
# integrated translator, there is no separate translator step. The high-level language
source and CICS.SDFHLOAD both input to the compiler, and a combined translator
and compiler listing is produced.

110 CICS TS for z/OS: CICS Application Programming Guide

High-level language
source

Translator
Command-level
listing
CICS. language translator
SDFHLOAD

Intermediate
storage
DFHBMSCA
DFHAID Compiler
High-level listing
CICS. language compiler
SDFHCOB
or SDFHPL1 DFHEILIC
DFHEILIP

Intermediate
storage
DFHECI
DFHEPI Linkage Editor
Linkage Editor listing
CICS.
SDFHLOAD

DFHPL1OI

SYS1.PLIBASE CICS.
or COBLIB SDFHLOAD

Figure 15. Installing COBOL and PL/I programs

Sample JCL to install COBOL application programs

You can use the job control statements shown in Figure 16 on page 112 to process
COBOL application programs with a separate translator. The procedure name
depends on whether it is a CICS application program or an EXCI batch program.
For the names of the CICS-supplied COBOL procedures, see Table 7 on page 107.

Chapter 9. Installing application programs 111

//jobname JOB accounting info,name,MSGLEVEL=1
// EXEC PROC=procname 1
//TRN.SYSIN DD * 2
CBL XOPTS(Translator options . . .) 3
.
COBOL source statements
.
/*
//LKED.SYSIN DD * 4
NAME anyname(R)
/*
//

where procname is the name of the procedure,

and anyname is your load module name.

Figure 16. Sample job control statements to call the DFHYITVL or DFHYXTVL procedures

To use the procedure DFHZITCL to invoke the integrated translator, you can use
the job control statements shown in Figure 17:

//jobname JOB accounting info,name,MSGLEVEL=1

// EXEC DFHZITCL,PROGLIB=dsnname 1
//COBOL.SYSIN DD *
.
. COBOL source statements
.
/*
//LKED.SYSIN DD *
NAME anyname(R)
/*
//

where anyname is your load module name.

Figure 17. Sample job control statements to use the DFHZITCL procedure

Notes for installing COBOL programs

1 Translator options:

Specify the COBOL3, COBOL2 or OOCOBOL translator option according to the

version of the COBOL functionality required in the compile step.

Compiler options:

To compile a COBOL program, you need the compiler options RENT, NODYNAM,
and LIB.

If you use the translator option, CBLCARD (the default), the CICS translator
automatically generates a CBL statement containing these options. You can prevent
the generation of a CBL or PROCESS card by specifying the translator option
NOCBLCARD.

The PARM statement of the COB step in the CICS-supplied COBOL procedures
specifies values for the compiler options. For example,
//COB EXEC PGM=IGYCRCTL,REGION=&REG,
// PARM=’NODYNAM,LIB,OBJECT,RENT,APOST,MAP,XREF’

112 CICS TS for z/OS: CICS Application Programming Guide

To compile a COBOL program with a compiler that has an integrated translator, you
also need to use the CICS compiler option to indicate that you want the compiler to
invoke the translator. The DFHZITCL procedure includes this compiler option:
CBLPARM=’NODYNAM,LIB,MAP,CICS(’’COBOL3’’)’

Note: If you specify CICS translator options for the integrated translator in the
PARM string, you need double apostrophes as shown in this example. If,
however, you specify the options in your source program, you need single
apostrophes (for example, you might have CBL CICS(’COBOL3,SP’) APOST as
the CBL statement in your source program.

The CICS-supplied COBOL procedures do not specify values for the SIZE and BUF
options. The defaults are SIZE=MAX, and BUF=4K. SIZE defines the amount of
virtual storage available to the compiler, and BUF defines the amount of dynamic
storage to be allocated to each compiler buffer work file. You can change these
options with a PARM.COB parameter in the EXEC statement that invokes the
procedure. For example:
EXEC PROC=procname,PARM.COB=’SIZE=512K,BUF=16K,.,.,.’

You can change compiler options by using any of the following methods:
v By overriding the PARM statement defined on the COB step of the
CICS-supplied COBOL procedures.
If you specify a PARM statement in the job that calls the procedure, it overrides
all the options specified in the procedure JCL. Ensure that all the options you
want are specified in the override, or in a CBL statement.
v Specifying a CBL statement at the start of the source statements in the job
stream used to call the the CICS-supplied COBOL procedures.
v The COBOL installation defaults macro, IGYCOPT. This is needed if you do not
use a CBL statement (that is, you have specified the translator option
NOCBLCARD).

For information about the translator option CBLCARD|NOCBLCARD, see “Defining

translator options” on page 74. If you choose to use the NOCBLCARD option, also
specify the COBOL compiler option ALOWCBL=NO to prevent an error message of
IGYOS4006-E being issued. For more information about the ALOWCBL compiler
option, see the relevant Installation and Customization manual for your version of
COBOL.

2 If you have no input for the translator, you can specify DD DUMMY instead of DD *.
However, if you specify DD DUMMY, also code a suitable DCB operand. (The
translator does not supply all the data control block information for the SYSIN data
set.)

3 If the stand-alone translator supplied with CICS TS is used, the translator
options on the XOPTS statement override similar options in the CICS-supplied
COBOL procedures.

For information about the translator options you can include on the XOPTS
statement, see “Defining translator options” on page 74.

When the integrated CICS translator is used, the COBOL compiler recognizes only
the keyword CICS for defining translator options, not XOPTS.

4 You can ignore weak external references unresolved by the link-edit.

Chapter 9. Installing application programs 113

The link-edit job step requires access to the libraries containing the
environment-specific modules for CICS, and the Language Environment link-edit
modules, as appropriate. Override or change the names of these libraries if the
modules and library subroutines are installed in libraries with different names.

If you are installing a program into either of the read-only DSAs, see “Running
application programs in the RDSAs” on page 103 for more details.

If you are installing a program that is to be used from the LPA, add the RENT and
REFR options to the LNKPARM parameter on the call to the CICS-supplied COBOL
procedures. (See “Running applications in the link pack area” on page 102.)

Installing PL/I application programs

Figure 15 on page 111 illustrates the flow of control in the cataloged procedures for
PL/I programs.

For more information about preparing PL/I programs, see the PL/I Programming
Guide.

Sample JCL to install PL/I application programs

You can use the job control statements shown in Figure 18 to process PL/I
application programs with a separate translator.

In the procedure name, the value of “x” depends on whether it is a CICS application
program or an EXCI batch program. For the names of the CICS-supplied
procedures, see Table 7 on page 107.

//jobname JOB accounting info,name,MSGLEVEL=1

// EXEC PROC=DFHYxTPL 1
//TRN.SYSIN DD * 2
*PROCESS XOPTS(translator options...)PL/I compiler options...; 3
.
PL/I source statements 4
.
/*
//LKED.SYSIN DD * 5
NAME anyname(R)
/*
//

where anyname is your load module name

Figure 18. Sample job control statements to call the DFHYxTPL procedures

Notes for installing a PL/I program:

1 The PL/I COUNT runtime option is not supported by Language Environment.
The REPORT option is replaced by the RPTSTG and RPTUPTS Language
Environment options. See the z/OS Language Environment Migration Guide.

2 If you have no input for the translator, you can specify DD DUMMY instead of DD *.
However, if you specify DD DUMMY also code a suitable DCB operand. (The translator
does not supply all the data control block information for the SYSIN data set.)

3 Translator and compiler options:

114 CICS TS for z/OS: CICS Application Programming Guide

For information about the translator options you can include on the XOPTS
statement, see “Defining translator options” on page 74.

Ignore the message from the PL/I compiler: “IEL0548I PARAMETER TO MAIN
PROCEDURE NOT VARYING CHARACTER STRING”.

Warning messages may appear from the PL/I compiler stating that arguments and
parameters do not match for calls to procedure DFHxxxx. These messages indicate
that arguments specified in operands to CICS commands may not have the correct
data type. Carefully check all fields mentioned in these messages, especially
receiver fields.

4 If you include the CALL PLIDUMP statement in an application program, output
goes to the CESE transient data destination. The CICS supplied resource definition
group, in the CSD, DFHDCTG, contains an entry for CPLD.

5 Link-edit considerations:

You can ignore weak external references unresolved by the link-edit.

If you are installing a program into either of the read-only DSAs, see “Running
application programs in the RDSAs” on page 103 for more details.

If you are installing a program that is to be used from the LPA, add the RENT and
REFR options to the LNKPARM parameter on the call to the DFHYxTPL procedure.
(See “Running applications in the link pack area” on page 102 for more
information.)

PL/I procedure with an integrated translator

To use the new procedure DFHZITPL to invoke the integrated translator, you can
use the following sample JCL:

//jobname JOB accounting info,name,MSGLEVEL=1

// EXEC DFHZITPL,PROGLIB=dsnname 1
//PLI.SYSIN DD *
.
. PLI source statements
.
/*
//LKED.SYSIN DD *
NAME anyname(R)
/*
//

where anyname is your load module name.

Figure 19. Sample job control statements to use the DFHZITPL procedure

Notes for installing PLI programs with an integrated translator

1 Translator options:

The DFHZITPL procedure includes the following compiler options to indicate that
you want the compiler to invoke the translator:
PLIPARM=(’SOURCE,OPTIONS,SYSTEM(CICS),PP(CICS)’)

Chapter 9. Installing application programs 115

Note: In this procedure, the SYSLMOD DD statement in the LKED step must refer
to a PDSE (not a PDS as for the older PL/I compilers).

116 CICS TS for z/OS: CICS Application Programming Guide

Installing C application programs
Figure 20 shows the flow of control in the DFHYxTzL cataloged procedures for C
command-level programs.

High-level language
source

Translator
Command-level
listing
CICS. language translator
SDFHLOAD

Intermediate
storage

High-level Compiler
EDC.V1R2M0 DFHBMSCA language compiler listing
SEDCHDRS DFHAID
SEDCMSGS
(EDCMSGE)

Intermediate
storage

Pre-linkage
Pre-linkage editor
EDC.V1R2M0 editor listing
SEDCLINK
SEDCCOMP
SEDCMSGS
(EDCMSGE)

EDC.V2R2M1 Intermediate
SIBMLINK storage

DFHEILID
DFHELII
Linkage Editor
Linkage Editor listing
CICS.
SDFHLOAD

EDC.V1R2M0
SEDCBASE

EDC.V2R2M1 CICS.
SIBMBASE SDFHLOAD

Figure 20. Installing C programs using the DFHYxTzL procedure

Chapter 9. Installing application programs 117

There are translator, compiler, pre-linkage editor and linkage editor steps, each
producing a listing and an intermediate file that is passed to the next step. C
libraries are referenced in the compiler, pre linkage editor and linkage editor steps.

# Note: When you choose the XPLINK compiler option, there is no pre-link step in
# the diagram above.

Before you can install any C programs, you must have installed the C library and
compiler and generated CICS support for C. (See the CICS Transaction Server for
z/OS Installation Guide.)

Sample JCL to install C application programs

You can use the job control statements shown in Figure 21 to process C application
programs. In the procedure name, x depends on whether your program is a CICS
application program or an EXCI batch program. For the names of the
CICS-supplied procedures, see Table 7 on page 107.

//jobname JOB accounting info,name,MSGLEVEL=1

// EXEC PROC=DFHYxTzL 1
//TRN.SYSIN DD * 2
#pragma XOPTS(Translator options . . .) 3
.
C source statements
.
/*
//LKED.SYSIN DD * 4
NAME anyname(R)
/*
//

where anyname is your load module name

Figure 21. Sample JCL to call the DFHYxTzL procedures

Notes for installing a C program:

1 Compiler options:

You can code compiler options by using the parameter override (PARM.C) in the
EXEC statement that invokes the procedure, or on a ~pragma options directive.

3 Translator options: For information about the translator options you can
include on the XOPTS statement, see “Defining translator options” on page 74 .

4 If you are installing a program into either of the read-only DSAs, see “Running
application programs in the RDSAs” on page 103 for more details.

If you are installing a program that is to be used from the LPA, add the RENT and
REFR options to the LNKPARM parameter on the call to the DFHYxTzL procedure.
(See “Running applications in the link pack area” on page 102 for more
information.)

118 CICS TS for z/OS: CICS Application Programming Guide

C language programs must be link-edited with AMODE(31), so the DFHYxTzL
procedures specify AMODE(31) by default.

Including pre-translated code with your C source code

The translator may generate dfhexec or DFHEXEC. If both versions are present in
your program, you will see error message IEW2456E. There are two ways to
prevent this error.
1. Recompile the old code containing dfhexec.
2. Use the prelinker RENAME control statement in the job, as shown below.

//jobname JOB accounting info,name,MSGLEVEL=1

// EXEC PROC=DFHYxTzL
//TRN.SYSIN DD *
#pragma XOPTS(Translator options . . .)
.
C source statements
.
/*
//PLKED.SYSLIN DD *
RENAME dfhexec DFHEI1
//LKED.SYSLIN DD *
NAME anyname(R)
/*
//

where anyname is your load module name

Figure 22. Sample JCL to rename dfhexec

Using your own job streams

If you want to write your own JCL to translate, assemble (or compile), and link-edit
your application programs, you can use the supplied cataloged procedures as a
model. They are installed in the CICSTS31.CICS.SDFHPROC library.

The rest of this section summarizes the important points about the translator and
each of the main categories of program. For simplicity, the following discussion
states that you load programs into CICSTS31.CICS.SDFHLOAD or IMS™.PGMLIB.
In fact, you can use any libraries, but only when they are either included in the
DFHRPL library concatenation in the CICS job stream, or included in the STEPLIB
library concatenation in the batch job stream (for a stand-alone IMS batch program).

Note: The IMS libraries referred to in the job streams are identified by IMS.libnam
(for example IMS.PGMLIB). If you use your own naming convention for IMS
libraries, please rename the IMS libraries accordingly.

Translator requirements
The CICS translator requires a minimum of 256KB of virtual storage. You may need
to use the translator options CICS and DLI.

Online programs that use EXEC CICS or EXEC DLI commands

1. Always use the translator option CICS. If the program issues EXEC DLI
commands, use the translator option DLI.
2. The link-edit input (defined by the SYSLIN DD statement) must include the
correct interface module before the object deck. Therefore, place an INCLUDE

Chapter 9. Installing application programs 119

statement for the interface module before the object deck. Also put ORDER
statements before the INCLUDE statements, and an ENTRY statement after all
the INCLUDE statements.
The interface modules are:
DFHEAI
Assembler
DFHELII
All HLL languages
In the CICS-supplied procedures, the input to the link-edit step (defined by the
SYSLIN DD statement) concatenates a library member with the object deck.
This member contains an INCLUDE statement for the required interface module.
For example, the DFHYITVL procedure concatenates the library member
DFHEILID, which contains the following INCLUDE statement:
INCLUDE SYSLIB(DFHELII)
3. Place the load module output from the link-edit (defined by the SYSLMOD DD
statement) in CICSTS31.CICS.SDFHLOAD, or your own program library.

Figure 23 on page 121 shows sample JCL and an inline procedure, based on the
CICS-supplied procedure DFHYITVL, that can be used to install COBOL application
programs. The procedure does not include the COPYLINK step and concatenation
of the library member DFHEILID that contains the INCLUDE statement for the
required interface module (as included in the DFHYITVL procedure). Instead, the
JCL provides the following INCLUDE statement:
INCLUDE SYSLIB(DFHELII)

If this statement was not provided, the link-edit would return an error message for
unresolved external references, and the program output would be marked as not
executable.

120 CICS TS for z/OS: CICS Application Programming Guide

//* The following JCL could be used to execute this procedure
//*
//APPLPROG EXEC MYYITVL,
// INDEX=’CICSTS31.CICS
// PROGLIB=’CICSTS31.CICS.SDFHLOAD’,
// DSCTLIB=’CICSTS31.CICS.SDFHCOB’,
// INDEX2=’user.qualif’
// OUTC=A, Class for print output
// REG=4M, Region size for all steps
// LNKPARM=’LIST,XREF’, Link edit parameters
// WORK=SYSDA Unit for work datasets

//TRN.SYSIN DD *
//* .
//* . Application program
//* .
//*
//LKED.SYSIN DD *
INCLUDE SYSLIB(DFHELII)
NAME anyname(R)
//*
//MYYITVL PROC SUFFIX=1$, Suffix for translator module
// INDEX=’CICSTS31.CICS’, Qualifier(s) for CICS libraries
// PROGLIB=’CICSTS31.CICS.SDFHLOAD’, Name of o/p library
// DSCTLIB=’CICSTS31.CICS.SDFHCOB’, Private macro/dsect
// AD370HLQ=’SYS1’, Qualifier(s) for AD/Cycle compiler
// LE370HLQ=’SYS1’, Qualifier(s) for Language Environment libraries
// OUTC=A, Class for print output
// REG=4M, Region size for all steps
// LNKPARM=’LIST,XREF’, Link edit parameters
// WORK=SYSDA Unit for work datasets
//*

Figure 23. Sample user-defined JCL to install a COBOL program (Part 1 of 2)

Chapter 9. Installing application programs 121

//* This procedure contains 3 steps
//* 1. Exec the COBOL translator (using the supplied suffix 1$)
//* 2. Exec the COBOL compiler
//* 3. Linkedit the output into dataset &PROGLIB

//TRN EXEC PGM=DFHECP &SUFFIX,,

// PARM=’COBOL3’,
// REGION=&REG

//STEPLIB DD DSN=&INDEX..SDFHLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=&OUTC
//SYSPUNCH DD DSN=&&SYSCIN,
// DISP=(,PASS),UNIT=&WORK,
// DCB=BLKSIZE=400,
// SPACE=(400,(400,100))
//*
//COB EXEC PGM=IGYCRCTL,REGION=&REG,
// PARM=’NODYNAM,LIB,OBJECT,RENT,RES,APOST,MAP,XREF’
//STEPLIB DD DSN=&AD370HLQ..SIGYCOMP,DISP=SHR
//SYSLIB DD DSN=&DSCTLIB,DISP=SHR
// DD DSN=&INDEX..SDFHCOB,DISP=SHR
// DD DSN=&INDEX..SDFHMAC,DISP=SHR
// DD DSN=&INDEX..SDFHSAMP,DISP=SHR
//SYSPRINT DD SYSOUT=&OUTC
//SYSIN DD DSN=&&SYSCIN,DISP=(OLD,DELETE)
//SYSLIN DD DSN=&&LOADSET,DISP=(MOD,PASS),
// UNIT=&WORK,SPACE=(80,(250,100))
//SYSUT1 DD UNIT=&WORK,SPACE=(460,(350,100))
//SYSUT2 DD UNIT=&WORK,SPACE=(460,(350,100))
//SYSUT3 DD UNIT=&WORK,SPACE=(460,(350,100))
//SYSUT4 DD UNIT=&WORK,SPACE=(460,(350,100))
//SYSUT5 DD UNIT=&WORK,SPACE=(460,(350,100))
//SYSUT6 DD UNIT=&WORK,SPACE=(460,(350,100))
//*
//LKED EXEC PGM=IEWL,REGION=&REG,
// PARM=’&LNKPARM’,COND=(5,LT,COB)
//SYSLIB DD DSN=&INDEX..SDFHLOAD,DISP=SHR
// DD DSN=&LE370HLQ..SCEELKED,DISP=SHR
//SYSLMOD DD DSN=&PROGLIB,DISP=SHR
//SYSUT1 DD UNIT=&WORK,DCB=BLKSIZE=1024,
// SPACE=(1024,(200,20))
//SYSPRINT DD SYSOUT=&OUTC
//SYSLIN DD DSN=&&COPYLINK,DISP=(OLD,DELETE)
// DD DSN=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//PEND
//*

Figure 23. Sample user-defined JCL to install a COBOL program (Part 2 of 2)

Online programs that use the CALL DLI interface

1. Specify the translator option CICS, but not the translator option DLI.

Note: For a program that does not use CICS commands and is only invoked by
a running transaction (and never directly by CICS task initiation), no
translator step is needed.
2. The interface module, DFHDLIAI, is automatically included by the link-edit. If
you use an INCLUDE statement in the link-edit input, place it after the object
deck.
3. Include the module DLIUIB.

122 CICS TS for z/OS: CICS Application Programming Guide

4. Place the load module output from the link-edit (defined by the SYSLMOD DD
statement) in CICSTS31.CICS.SDFHLOAD, or a user-defined application
program library.

Batch or BMP programs that use EXEC DLI commands

1. The translator option DLI is required. Do not specify the translator option CICS.
2. The INCLUDE statement for the interface module must follow the object deck
in the input to the link-edit (defined by the SYSLIN DD statement). The interface
module, DFSLI000, which resides on IMS.RESLIB, is the same for all
programming languages. If you include CICSTS31.CICS.SDFHLOAD in the
input to the link-edit (defined by the SYSLIB DD statement), concatenate it after
IMS.RESLIB.
3. Place the load module output from the link-edit (defined by the SYSLMOD DD
statement) in IMS.PGMLIB, or a library concatenated in the STEPLIB DD
statement of the batch job stream.

Batch or BMP programs that use DL/I CALL commands

If you want to prepare assembler, COBOL, or PL/I programs that use the DL/I CALL
interface, do not use any of the CICS-supplied procedures. Programs that contain
CALL ASMTDLI, CALL CBLTDLI, or CALL PLITDLI should be assembled or
compiled, and link-edited, as IMS applications, and are not subject to any CICS
requirements. See the relevant IMS manual for information about how to prepare
application programs that use the DL/I CALL interface.

Chapter 9. Installing application programs 123

124 CICS TS for z/OS: CICS Application Programming Guide
Chapter 10. Installing map sets and partition sets
This chapter describes how to assemble and link-edit map sets and partition sets
for use with the basic mapping (BMS) facility of CICS. It also describes how to
install HTML templates generated from BMS maps. See “Using the DFHMAPT
procedure to install HTML templates from BMS maps” on page 131 and the CICS
Internet Guide for information about using HTML templates.

If your program uses BMS maps, you need to create the maps. The traditional
method for doing this is to code the map in BMS macros and assemble these
macros. You actually do the assembly twice, with different output options.
v One assembly creates a set of definitions. You copy these definitions into your
program using the appropriate language statement, and they allow you to refer to
the fields in the map by name.
v The second assembly creates an object module that is used when your program
actually executes.

The process is illustrated in the following diagram:.

BMS macro
statements Ty p e =
Assembler
defining DSECT Copy
map set library

Ty p e = Assembler
MAP listing

Assembler
Assembler
listing

Link edit
Object Link Editor listing
module
library

CICS load
library

Figure 24. Preparing a map

Whatever way you produce maps, you need to create a map before you compile
(assemble) any program that uses it. In addition, if you change the map, you

© Copyright IBM Corp. 1989, 2005 125

usually need to recompile (reassemble) all programs that use it. Some changes
affect only the physical map and are not reflected in the corresponding symbolic
map used by the program. One of these is a change in field position that does not
alter the order of the fields. However, changes in data type, field length, field
sequence, and others do affect the symbolic map, and it is always safest to
recompile (reassemble).

CICS also supports the definition of BMS map sets and partition sets interactively
by using licensed programs such as the IBM Screen Definition Facility II (SDF II),
program number 5665-366. For more information about SDF II, see the Screen
Definition Facility II Primer for CICS/BMS Programs and Screen Definition Facility II
General Information manuals.

For information about writing programs to use BMS services, see Chapter 31,
“Basic mapping support,” on page 449.

CICS loads BMS map sets and partition sets above the 16MB line if you specify the
residency mode for the map set or partition set as RMODE(ANY) in the link-edit
step. If you are using either map sets or partition sets from earlier releases of CICS,
you can load them above the 16MB line by link-editing them again with
RMODE(ANY). For examples of link-edit steps specifying RMODE(ANY), see the
sample job streams in this chapter.

This chapter includes:

v “Installing map sets”
v “Installing partition sets” on page 133
v “Defining programs, map sets, and partition sets to CICS” on page 134

Installing map sets

This section first describes the types of map sets, how you define them, and how
CICS recognizes them. This is followed by a description of how to prepare physical
map sets and symbolic description map sets separately. Finally, there is a
description of how to prepare both physical and symbolic description map sets in
one job. In these descriptions, it is assumed that the SYSPARM parameter is used
to distinguish the two types of map sets.

Types of map sets

To install a map set, you must actually prepare two types of map sets:
v A physical map set, used by BMS to translate data from the standard
device-independent form used by application programs to the device-dependent
form required by terminals.
v A symbolic description map set, used in the application program to define the
standard device-independent form of the user data. This is a DSECT in
assembler language, a data definition in COBOL, a BASED or AUTOMATIC
structure in PL/I, and a “struct” in C/370.

Physical map sets must be cataloged in the CICS load library. Symbolic description
map sets can be cataloged in a user copy library, or inserted directly into the
application program itself.

The map set definition macros are assembled twice; once to produce the physical
map set used by BMS in its formatting activities, and once to produce the symbolic
description map set that is copied into the application program.

126 CICS TS for z/OS: CICS Application Programming Guide

Defining the type of map set you require
The two types of map set can be distinguished by either:
v The TYPE operand of the DFHMSD macro
v Use of the SYSPARM operand on the EXEC statement of the job used to
assemble the map set
If you use the SYSPARM operand for this purpose, the TYPE operand of the
DFHMSD macro is ignored. Using SYSPARM allows both the physical map set and
the symbolic description map set to be generated from the same unchanged set of
BMS map set definition macros.

Map sets can be assembled as either unaligned or aligned (an aligned map is one
in which the length field is aligned on a halfword boundary). Use unaligned maps
except in cases where an application package needs to use aligned maps.

The SYSPARM value alone determines whether the map set is aligned or
unaligned, and is specified on the EXEC PROC=DFHMAPS statement. The
SYSPARM operand can also be used to specify whether a physical map set or a
symbolic description map set (DSECT) is to be assembled, in which case it
overrides the TYPE operand. If neither operand is specified, an unaligned DSECT is
generated.

The TYPE operand of the DFHMSD macro can only define whether a physical or
symbolic description map set is required.

For the possible combinations of operands to generate the various types of map
set, see Table 8.
Table 8. SYSPARM and DFHMSD operand combinations for map assembly
Type of map set SYSPARM operand of EXEC TYPE operand of
DFHMAPS statement DFHMSD macro
Aligned symbolic A Not specified
description map A DSECT
set (DSECT) ADSECT Any (takes SYSPARM)
Aligned A MAP
physical map set AMAP Any (takes SYSPARM)
Unaligned Not specified Not specified
symbolic Not specified DSECT
description map DSECT Any (takes SYSPARM)
set (DSECT)
Unaligned Not specified MAP
physical map set MAP Any (takes SYSPARM)

The physical map set indicates whether it was assembled for aligned or unaligned
maps. This information is tested at execution time, and the appropriate map
alignment used. Thus aligned and unaligned map sets can be mixed.

Using extended data stream terminals

Applications and maps designed for the 3270 Information Display System run
unchanged on devices supporting extensions to the 3270 data stream such as
color, extended highlighting, programmed symbols, and validation. To use fixed
extended attributes such as color, you only need to reassemble the physical map
set. If dynamic attribute modification by the application program is needed, you

Chapter 10. Installing map sets and partition sets 127

must reassemble both the physical and symbolic description map sets, and you
must reassemble or recompile the application program.

Installing physical map sets

Figure 25 shows the the assembler and linkage editor steps for installing physical
map sets.

Macro statements
defining the map set

Assembly
Assembler
listing
CICS.
SDFHMAC

Linkage
Editor
input
(object)

Linkage Editor Linkage Editor

listing

CICS.
SDFHLOAD

Figure 25. Installing physical map sets

Figure 26 gives an example job stream for the assembly and link-editing of physical
map sets.

//PREP JOB ’accounting information’,CLASS=A,MSGLEVEL=1

//STEP1 EXEC PROC=DFHASMVS,PARM.ASSEM=’SYSPARM(MAP)’ 1
//SYSPUNCH DD DSN=&&TEMP,DCB=(RECFM=FB,BLKSIZE=2960),
// SPACE=(2960,(10,10)),UNIT=SYSDA,DISP=(NEW,PASS)
//SYSIN
. DD *
.
.
. Macro statements defining the map set
.
.
/*
//STEP2 EXEC PROC=DFHLNKVS,PARM=’LIST,LET,XREF’ 2
//SYSLIN DD DSN=&&TEMP,DISP=(OLD,DELETE)
// DD *
MODE RMODE(ANY|24) 3
NAME mapsetname(R) 4
/*
//

Figure 26. Assembling and link-editing a physical map set

128 CICS TS for z/OS: CICS Application Programming Guide

Notes:

1 For halfword-aligned length fields, specify the option SYSPARM(AMAP) instead
of SYSPARM(MAP).

2 Physical map sets are loaded into CICS-key storage, unless they are link-edited
with the RMODE(ANY) and RENT options. If they are link-edited with these options,
they are loaded into key-0 protected storage, provided that RENTPGM=PROTECT
is specified on the RENTPGM initialization parameter. However, it is recommended
that map sets (except for those that are only sent to 3270 or LU1 devices) should
not be link-edited with the RENT or the REFR options because, in some cases,
CICS modifies the map set. Generally, use the RENT or REFR options for map sets
that are only sent to 3270 or LU1 devices.For more information about the storage
protection facilities available in CICS, see the CICS System Definition Guide.

3 The MODE statement specifies whether the map set is to be loaded above
(RMODE(ANY)) or below (RMODE(24)) the 16MB line. RMODE(ANY) indicates that
CICS can load the map set anywhere in virtual storage, but tries to load it above
the 16MB line, if possible.

4 Use the NAME statement to specify the name of the physical map set that BMS
loads into storage. If the map set is device-dependent, derive the map set name by
appending the device suffix to the original 1- to 7-character map set name used in
the application program. The suffixes to be appended for the various terminals
supported by CICS BMS depend on the parameter specified in the TERM or
SUFFIX operand of the DFHMSD macros used to define the map set. For
programming information giving a complete list of map set suffixes, see the CICS
Application Programming Reference manual.

To use a physical map set, you must define and install a resource definition for it.
You can do this either by using the program autoinstall function or by using the
CEDA DEFINE MAPSET and INSTALL commands. as described in “Defining
programs, map sets, and partition sets to CICS” on page 134.

Installing symbolic description map sets

Symbolic description map sets enable the application programmer to make symbolic
references to fields in the physical map set. Figure 27 shows the preparation of
symbolic description map sets for BMS.

Macro statements
defining the
symbolic map

Assembly
Assembler listing
CICS.
SDFHMAC

SYSPUNCH

Figure 27. Installing symbolic description map sets using the DFHASMVS procedure

Chapter 10. Installing map sets and partition sets 129

To use a symbolic description map set in a program, you must assemble the source
statements for the map set and obtain a punched copy of the storage definition
through SYSPUNCH. The first time this is done, you can direct the SYSPUNCH
output to SYSOUT=A to get a listing of the symbolic description map set. If many
map sets are to be used at your installation, or there are multiple users of common
map sets, establish a private user copy library for each language that you use.

When a symbolic description is prepared under the same name for more than one
programming language, a separate copy of the symbolic description map set must
be placed in each user copy library. You must ensure that the user copy libraries
are correctly concatenated with SYSLIB.

You need only one symbolic description map set corresponding to all the different
suffixed versions of the physical map set. For example, to run the same application
on terminals with different screen sizes, you would:
1. Define two map sets each with the same fields, but positioned to suit the screen
sizes. Each map set has the same name but a different suffix, which would
match the suffix specified for the terminal.
2. Assemble and link-edit the different physical map sets separately, but create
only one symbolic description map set, because the symbolic description map
set would be the same for all physical map sets.

You can use the sample job stream in Figure 28 to obtain a listing of a symbolic
description map set. It applies to all the programming languages supported by
CICS.

//DSECT JOB ’accounting information’,CLASS=A,MSGLEVEL=1

//ASM EXEC PROC=DFHASMVS,PARM.ASSEM=’SYSPARM(DSECT)’
//SYSPUNCH DD SYSOUT=A
//SYSIN
. DD *
.
.
. Macro statements defining the map set
.
.
/*
//

Figure 28. Listing of a symbolic description map set

If you want to assemble symbolic description map sets in which length fields are
halfword-aligned, change the EXEC statement of the sample job in Figure 28 to the
following:
//ASSEM EXEC PROC=DFHASMVS,PARM.ASSEM=’SYSPARM(ADSECT)’

To obtain a punched copy of a symbolic description map set, code the

//SYSPUNCH statement in the above example to direct output to the punch data
stream. For example:
//SYSPUNCH DD SYSOUT=B

To store a symbolic description map set in a private copy library, use job control
statements similar to the following:
//SYSPUNCH DD DSN=USER.MAPLIB.ASM(map set name),DISP=OLD
//SYSPUNCH DD DSN=USER.MAPLIB.COB(map set name),DISP=OLD
//SYSPUNCH DD DSN=USER.MAPLIB.PLI(map set name),DISP=OLD

130 CICS TS for z/OS: CICS Application Programming Guide

Installing physical and symbolic description maps together
Figure 29 shows the DFHMAPS procedure for installing physical and symbolic
description maps together. The DFHMAPS procedure consists of the following four
steps, shown in Figure 29:
1. The BMS macros that you coded for the map set are added to a temporary
sequential data set.
2. The macros are assembled to create the physical map set. The MAP option is
coded in the SYSPARM global variable in the EXEC statement
(PARM='SYSPARM(MAP)').
3. The physical map set is link-edited to the CICS load library.
4. Finally, the macros are assembled again, this time to produce the symbolic
description map set. In this step, DSECT is coded in the SYSPARM global
variable in the EXEC statement (PARM='SYSPARM(DSECT)'). Output is
directed to the destination specified in the //SYSPUNCH DD statement. In the
DFHMAPS procedure, that destination is the CICSTS31.CICS.SDFHMAC
library.

1
Macro statements
defining the map set

2
Assembly
Assembler listing
CICS.
SDFHMAC

Linkage
Editor
input
(object)

3
Linkage Editor Linkage Editor
CICS. listing
SDFHLOAD

4
Macro statements Assembler
defining the map set
CICS.
SDFHMAC

Figure 29. Installing a physical map set and a symbolic description map set together

Using the DFHMAPT procedure to install HTML templates from

BMS maps
The DFHMAPT procedure is similar to DFHMAPS, with an additional step that
installs HTML templates generated from the BMS maps. In this step, TEMPLATE is
coded in the SYSPARM global variable in the EXEC statement
(PARM='SYSPARM(TEMPLATE)'). In the DFHMAPT procedure, the output is
directed to CICSTS31.CICS.SDFHHTML.

Chapter 10. Installing map sets and partition sets 131

If you wish to use your own macro to customize HTML templates, and you do not
wish to add your macro to the BMS source you should modify step ASMTEMPL:
1. Change the PARM parameter of the EXEC statement to
PARM=’SYSPARM(TEMPLATE,macro_name),DECK,NOOBJECT’
2. Add the library that contains your macro to the SYSLIB concatenation.

JCL to install physical and symbolic description maps

The load module from the assembly of the physical map set and the source
statements for the symbolic description map set can be produced in the same job
by using the sample job stream in Figure 30.

//PREPARE JOB ’accounting information’,CLASS=A,MSGLEVEL=1

//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24 (see note)
//SYSUT1
. DD *
.
.
. Macro statements defining the map set
.
.
/*
//

Figure 30. Installing physical and symbolic description maps together

Note: The RMODE statement specifies whether the map set is to be loaded above
(RMODE=ANY) or below (RMODE=24) the 16MB line. RMODE=ANY
indicates that CICS can load the map set anywhere in virtual storage, but
tries to load it above the 16MB line, if possible.

The DFHMAPS procedure produces map sets that are not halfword-aligned. If you
want the length fields in input maps to be halfword-aligned, you have to code A=A
on the EXEC statement. In the sample job in Figure 30, change the EXEC
statement to:
//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,A=A

This change results in the SYSPARM operands in the assembly steps being altered
to SYSPARM(AMAP) and SYSPARM(ADSECT) respectively.

The DFHMAPS procedure directs the symbolic description map set output
(SYSPUNCH) to the CICSTS31.CICS.SDFHMAC library. Override this by specifying
DSCTLIB=name on the EXEC statement, where “name” is the name of the chosen
user copy library.

Adding a CSECT to your map assembly

It is possible that you might need to generate your BMS maps with a CSECT. For
example, you might need to specify AMODE and RMODE options to ensure your
maps reside above 16MB, or you might need to use the DFSMS binder IDENTIFY
statement for reasons of change management. In this case, you need not only
include the appropriate CSECT at the front of your BMS macro statements, but also
add some conditional assembler statements to ensure that the CSECT statement is
not included in the symbolic description map. The following example shows how
you can add both a CSECT name and AMODE and RMODE statements:

132 CICS TS for z/OS: CICS Application Programming Guide

//PREPARE JOB ’accounting information’,CLASS=A,MSGLEVEL=1
//ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24
//SYSUT1 DD *
.
AIF (’&SYSPARM’ EQ ’DSECT’).SKIPSD
AIF (’&SYSPARM’ EQ ’ADSECT’).SKIPSD
ANYNAME CSECT Binder IDENTIFY requires CSECT name
ANYNAME AMODE 31
ANYNAME RMODE ANY
.SKIPSD ANOP ,
DFH0STM DFHMSD TYPE=DSECT,MODE=INOUT,CTRL=FREEKB,LANG=COBOL, C
TIOAPFX=YES,TERM=3270-2,MAPATTS=(COLOR,HILIGHT), C
DSATTS=(COLOR,HILIGHT)
SPACE
DFH0STM DFHMDI SIZE=(24,80)
.
.
.
SPACE
DFHMSD TYPE=FINAL
END
.
/*
//

Figure 31. Adding a CSECT to the map assembly

Installing partition sets

Partition sets are installed in the same way as physical map sets (as illustrated in
Figure 25 on page 128). There is no concept of a symbolic description partition set.
The job stream in Figure 32 is an example of the assembly and link-edit of partition
sets.

//PREP JOB ’accounting information’,CLASS=A,MSGLEVEL=1

//STEP1 EXEC PROC=DFHASMVS
//SYSPUNCH DD DSN=&&TEMP,DCB=(RECFM=FB,BLKSIZE=2960),
// SPACE=(2960,(10,10)),UNIT=SYSDA,DISP=(NEW,PASS)
//SYSIN DD *
.
Macro statements defining the partition set
.
/*
//STEP2 EXEC PROC=DFHLNKVS,PARM=’LIST,LET,XREF’ 1
//SYSLIN DD DSN=&&TEMP,DISP=(OLD,DELETE)
// DD *
MODE RMODE(ANY|24) 2
NAME partitionsetname(R) 3
/*
//

Figure 32. Assembling and link-editing a partition set

Chapter 10. Installing map sets and partition sets 133

Notes:

1 A partition set is loaded into CICS-key storage, unless it is link-edited with the
RMODE(ANY) and RENT options. If it is link-edited with these options, it is loaded
into key-0 protected storage, provided that RENTPGM=PROTECT is specified on
the RENTPGM initialization parameter.

For more information about the storage protection facilities available in CICS, see
the CICS System Definition Guide.

2 The MODE statement specifies whether the partition set is to be loaded above
(RMODE(ANY)) or below (RMODE(24)) the 16MB line. RMODE(ANY) indicates that
CICS can load the partition set anywhere in virtual storage, but tries to load it above
the 16MB line, if possible.

3 Use the NAME statement to specify the name of the partition set which BMS
loads into storage. If the partition set is device-dependent, derive the partition set
name by appending the device suffix to the original 1- to 7-character partition set
name used in the application program. The suffixes that BMS appends for the
various terminals depend on the parameter specified in the SUFFIX operand of the
DFHPSD macro that defined the partition set.

For programming information giving a complete list of partition-set suffixes, see the
CICS Application Programming Guide.

To use a partition set, you must define and install a resource definition for it. You
can do this either by using the program autoinstall function or by using the CEDA
DEFINE PARTITIONSET and INSTALL commands, as described in the CICS
Resource Definition Guide.

Defining programs, map sets, and partition sets to CICS

To be able to use a program that you have installed in one of the load libraries
specified in your CICS startup JCL, the program, and any map sets and partition
sets that it uses, must be defined to CICS. To do this, CICS uses the resource
definitions MAPSET (for map sets), PARTITIONSET (for partition sets), and
PROGRAM (for programs). You can create and install such resource definitions in
any of the following ways:
v CICS can dynamically create, install, and catalog a definition for the program,
map set, or partition set when it is first loaded, by using the autoinstall for
programs function.
v You can create a specific resource definition for the program, map set, or
partition set and install that resource definition in your CICS region.
You can install resource definitions in either of the following ways:
– At CICS initialization, by including the resource definition group in the group
list specified on the GRPLIST system initialization parameter.
– While CICS is running, by the CEDA INSTALL command.

For information about defining programs to CICS, see the CICS Resource Definition
Guide.

134 CICS TS for z/OS: CICS Application Programming Guide

Part 3. Application design
Chapter 11. Application design . . . . . . . . . . . . . . . . . . 139
Pseudoconversational and conversational design . . . . . . . . . . . . 140
Terminal interruptibility . . . . . . . . . . . . . . . . . . . . . 142
How tasks are started . . . . . . . . . . . . . . . . . . . . . . 142
Which transaction? . . . . . . . . . . . . . . . . . . . . . . . 143
Separating business and presentation logic . . . . . . . . . . . . . . 146
Multithreading: Reentrant, quasi-reentrant and threadsafe programs . . . . . 147
Quasi-reentrant application programs . . . . . . . . . . . . . . . 147
Threadsafe programs . . . . . . . . . . . . . . . . . . . . . 149
Threadsafe considerations for statically or dynamically called routines 153
| OPENAPI programs . . . . . . . . . . . . . . . . . . . . . 153
| Obligations of OPENAPI programs . . . . . . . . . . . . . . . 153
Using the FORCEQR system initialization parameter . . . . . . . . . 155
Non-reentrant programs . . . . . . . . . . . . . . . . . . . . 155
Storing data within a transaction . . . . . . . . . . . . . . . . . . 155
Transaction work area (TWA) . . . . . . . . . . . . . . . . . . 156
User storage . . . . . . . . . . . . . . . . . . . . . . . . 156
COMMAREA in LINK and XCTL commands . . . . . . . . . . . . . 157
| Channels in LINK and XCTL commands . . . . . . . . . . . . . . 157
Program storage . . . . . . . . . . . . . . . . . . . . . . . 158
Temporary storage . . . . . . . . . . . . . . . . . . . . . . 158
Intrapartition transient data . . . . . . . . . . . . . . . . . . . 159
GETMAIN SHARED command . . . . . . . . . . . . . . . . . 160
Your own data sets . . . . . . . . . . . . . . . . . . . . . . 160
Lengths of areas passed to CICS commands . . . . . . . . . . . . . 161
LENGTH options . . . . . . . . . . . . . . . . . . . . . . . 161
Journal records . . . . . . . . . . . . . . . . . . . . . . . 161
Data set definitions . . . . . . . . . . . . . . . . . . . . . . 161
Recommendation . . . . . . . . . . . . . . . . . . . . . . 161
Minimizing errors . . . . . . . . . . . . . . . . . . . . . . . . 162
Protecting CICS from application errors . . . . . . . . . . . . . . 162
Testing applications . . . . . . . . . . . . . . . . . . . . . . 162
Non-terminal transaction security . . . . . . . . . . . . . . . . . . 163

Chapter 12. Design for performance . . . . . . . . . . . . . . . . 165

Program size . . . . . . . . . . . . . . . . . . . . . . . . . 165
Virtual storage. . . . . . . . . . . . . . . . . . . . . . . . . 166
Reducing paging effects . . . . . . . . . . . . . . . . . . . . 167
Locality of reference . . . . . . . . . . . . . . . . . . . . 167
Working set . . . . . . . . . . . . . . . . . . . . . . . 168
Reference set . . . . . . . . . . . . . . . . . . . . . . . 168
Exclusive control of resources . . . . . . . . . . . . . . . . . . . 169
Operational control . . . . . . . . . . . . . . . . . . . . . . . 170
Operating system waits . . . . . . . . . . . . . . . . . . . . . 171
The NOSUSPEND option . . . . . . . . . . . . . . . . . . . . 171
Efficient data operations . . . . . . . . . . . . . . . . . . . . . 172
Efficient database operations . . . . . . . . . . . . . . . . . . 172
Efficient data set operations. . . . . . . . . . . . . . . . . . . 172
VSAM data sets . . . . . . . . . . . . . . . . . . . . . . 173
BDAM data sets . . . . . . . . . . . . . . . . . . . . . . 174
Efficient browsing (in non-RLS mode) . . . . . . . . . . . . . . . 174
Efficient logging . . . . . . . . . . . . . . . . . . . . . . . 175
Efficient sequential data set access . . . . . . . . . . . . . . . . 175

© Copyright IBM Corp. 1989, 2005 135

Efficient terminal operations . . . . . . . . . . . . . . . . . . . . 176
Length of the data stream sent to the terminal . . . . . . . . . . . . 176
Basic mapping support considerations . . . . . . . . . . . . . . . 176
Avoid turning on modified data tags (MDTs) unnecessarily . . . . . . 176
Use FRSET to reduce inbound traffic . . . . . . . . . . . . . . 177
Do not send blank fields to the screen . . . . . . . . . . . . . . 177
Address CICS areas correctly . . . . . . . . . . . . . . . . . 177
Use the MAPONLY option when possible . . . . . . . . . . . . . 177
Send only changed fields to an existing screen . . . . . . . . . . 177
Design data entry operations to reduce line traffic . . . . . . . . . 178
Compress data sent to the screen . . . . . . . . . . . . . . . 178
Use nulls instead of blanks . . . . . . . . . . . . . . . . . . 178
Use methods that avoid the need for nulls or blanks. . . . . . . . . 179
Page-building and routing operations . . . . . . . . . . . . . . . 179
Sending multipage output . . . . . . . . . . . . . . . . . . 179
Sending messages to destinations other than the input terminal . . . . 180
Sending pages built from multiple maps . . . . . . . . . . . . . 180
Using the BMS page-copy facility. . . . . . . . . . . . . . . . 180
Requests for printed output . . . . . . . . . . . . . . . . . . . 181
Additional terminal control considerations . . . . . . . . . . . . . . 181
Use only one physical SEND command per screen . . . . . . . . . 181
Use the CONVERSE command . . . . . . . . . . . . . . . . 181
Limit the use of message integrity options . . . . . . . . . . . . 181
Avoid using the DEFRESP option on SEND commands . . . . . . . 182
Avoid using unnecessary transactions . . . . . . . . . . . . . . 182
Send unformatted data without maps . . . . . . . . . . . . . . 182

Chapter 13. Sharing data across transactions . . . . . . . . . . . . 183

Chapter 14. Enhanced inter-program data transfer: channels as

modern-day COMMAREAs . . . . . . . . . . . . . . . . . . . 189
Channels: quick start . . . . . . . . . . . . . . . . . . . . . . 189
Containers and channels . . . . . . . . . . . . . . . . . . . . 189
Basic examples . . . . . . . . . . . . . . . . . . . . . . . 190
Using channels: some typical scenarios . . . . . . . . . . . . . . . 192
One channel, one program . . . . . . . . . . . . . . . . . . . 192
One channel, several programs (a component) . . . . . . . . . . . 193
Several channels, one component . . . . . . . . . . . . . . . . 193
Multiple interactive components . . . . . . . . . . . . . . . . . 194
Creating a channel . . . . . . . . . . . . . . . . . . . . . . . 195
The current channel . . . . . . . . . . . . . . . . . . . . . . 196
Current channel example, with LINK commands . . . . . . . . . . . 196
Current channel example, with XCTL commands . . . . . . . . . . . 198
Current channel: START and RETURN commands . . . . . . . . . . 199
The scope of a channel . . . . . . . . . . . . . . . . . . . . . 200
Scope example, with LINK commands . . . . . . . . . . . . . . . 200
Scope example, with LINK and XCTL commands . . . . . . . . . . . 202
Discovering which containers a program’s been passed . . . . . . . . . 204
Discovering which containers were returned from a link . . . . . . . . . 204
CICS read only containers . . . . . . . . . . . . . . . . . . . . 204

136 CICS TS for z/OS: CICS Application Programming Guide

Designing a channel: best practices . . . . . . . . . . . . . . . . . 205
Constructing and using a channel: an example. . . . . . . . . . . . . 206
Channels and BTS activities . . . . . . . . . . . . . . . . . . . 207
Context . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Using channels from JCICS . . . . . . . . . . . . . . . . . . . . 209
Dynamic routing with channels . . . . . . . . . . . . . . . . . . 209
Data conversion . . . . . . . . . . . . . . . . . . . . . . . . 210
Why is data conversion needed? . . . . . . . . . . . . . . . . . 210
Preparing for code page conversion with channels . . . . . . . . . . 210
Data conversion with channels . . . . . . . . . . . . . . . . . 212
How to cause CICS to convert character data automatically . . . . . . 213
Using containers to do code page conversion . . . . . . . . . . . 214
A SOAP example . . . . . . . . . . . . . . . . . . . . . 214
Benefits of channels . . . . . . . . . . . . . . . . . . . . . . 215
Migrating from COMMAREAs to channels . . . . . . . . . . . . . . 216
Migration of existing functions . . . . . . . . . . . . . . . . . . 216
Migration to the new function . . . . . . . . . . . . . . . . . . 216
Migrating LINK commands that pass COMMAREAs . . . . . . . . . 216
Migrating XCTL commands that pass COMMAREAs . . . . . . . . 217
Migrating pseudoconversational COMMAREAs on RETURN commands 217
Migrating START data . . . . . . . . . . . . . . . . . . . . 218
Migrating dynamically-routed applications . . . . . . . . . . . . . 218

Chapter 15. Affinity . . . . . . . . . . . . . . . . . . . . . . 219

Types of affinity . . . . . . . . . . . . . . . . . . . . . . . . 220
Inter-transaction affinity . . . . . . . . . . . . . . . . . . . . 220
Transaction-system affinity . . . . . . . . . . . . . . . . . . . 220
Using INQUIRE and SET commands and global user exits . . . . . . 220
Programming techniques and affinity . . . . . . . . . . . . . . . . 221
Safe techniques . . . . . . . . . . . . . . . . . . . . . . . 221
Unsafe techniques . . . . . . . . . . . . . . . . . . . . . . 221
Suspect techniques . . . . . . . . . . . . . . . . . . . . . . 222
Recommendations . . . . . . . . . . . . . . . . . . . . . . 222
Safe programming to avoid affinity . . . . . . . . . . . . . . . . . 222
The COMMAREA . . . . . . . . . . . . . . . . . . . . . . 223
The TCTUA . . . . . . . . . . . . . . . . . . . . . . . . 224
Using the TCTUA in an unsafe way . . . . . . . . . . . . . . . 225
Using ENQ and DEQ commands with ENQMODEL resource definitions 226
Overview of sysplex enqueue and dequeue . . . . . . . . . . . . 226
Benefits . . . . . . . . . . . . . . . . . . . . . . . . . 227
BTS containers . . . . . . . . . . . . . . . . . . . . . . . 227
Unsafe programming for affinity . . . . . . . . . . . . . . . . . . 227
Using the common work area . . . . . . . . . . . . . . . . . . 227
Using GETMAIN SHARED storage . . . . . . . . . . . . . . . . 228
Using the LOAD PROGRAM HOLD command . . . . . . . . . . . . 229
Sharing task-lifetime storage . . . . . . . . . . . . . . . . . . 230
Using the WAIT EVENT command . . . . . . . . . . . . . . . . 232
Using ENQ and DEQ commands without ENQMODEL resource definitions 233
Suspect programming for affinity . . . . . . . . . . . . . . . . . . 234
Using temporary storage . . . . . . . . . . . . . . . . . . . . 234
Naming conventions for remote queues . . . . . . . . . . . . . 235
Exception conditions for globally accessible queues . . . . . . . . . 236
Using transient data . . . . . . . . . . . . . . . . . . . . . 237
Exception conditions for globally accessible queues . . . . . . . . . 237
Using the RETRIEVE WAIT and START commands . . . . . . . . . . 238
Using the START and CANCEL REQID commands . . . . . . . . . . 239

Part 3. Application design 137

Using the DELAY and CANCEL REQID commands . . . . . . . . . . 241
Using the POST and CANCEL REQID commands . . . . . . . . . . 242
Detecting inter-transaction affinities . . . . . . . . . . . . . . . . . 244
Inter-transaction affinities caused by application generators . . . . . . . 244
Duration and scope of inter-transaction affinities . . . . . . . . . . . . 244
Affinity transaction groups . . . . . . . . . . . . . . . . . . . 245
Relations and lifetimes . . . . . . . . . . . . . . . . . . . . 245
The global relation . . . . . . . . . . . . . . . . . . . . . 245
The LUname (terminal) relation . . . . . . . . . . . . . . . . 246
The userid relation . . . . . . . . . . . . . . . . . . . . . 248
The BAPPL relation . . . . . . . . . . . . . . . . . . . . . 249

Chapter 16. Recovery design . . . . . . . . . . . . . . . . . . 253

Chapter 17. Dealing with exception conditions . . . . . . . . . . . 257

Default CICS exception handling . . . . . . . . . . . . . . . . . . 257
Handling exception conditions by in-line code . . . . . . . . . . . . . 258
How to use the RESP and RESP2 options . . . . . . . . . . . . . 258
Use of RESP and DFHRESP in COBOL and PL/I. . . . . . . . . . 258
Use of RESP and DFHRESP in C and C++ . . . . . . . . . . . . 259
Use of DFHRESP in assembler . . . . . . . . . . . . . . . . 259
An example of exception handling in C . . . . . . . . . . . . . . 259
An example of exception handling in COBOL . . . . . . . . . . . . 260
Modifying default CICS exception handling . . . . . . . . . . . . . . 261
Using the HANDLE CONDITION command . . . . . . . . . . . . . . 263
RESP and NOHANDLE options . . . . . . . . . . . . . . . . . 264
How CICS keeps track of what to do . . . . . . . . . . . . . . . 264
Using the HANDLE CONDITION ERROR command. . . . . . . . . . . 265
Using the IGNORE CONDITION command . . . . . . . . . . . . . . 265
Using the HANDLE ABEND command . . . . . . . . . . . . . . . . 266
Using PUSH HANDLE and POP HANDLE commands . . . . . . . . . . 267

Chapter 18. Abnormal termination recovery . . . . . . . . . . . . . 269

Creating a program-level abend exit . . . . . . . . . . . . . . . . 270
Retrying operations . . . . . . . . . . . . . . . . . . . . . . . 271
Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Trace entry points . . . . . . . . . . . . . . . . . . . . . . 273
System trace entry points . . . . . . . . . . . . . . . . . . 273
User trace entry points . . . . . . . . . . . . . . . . . . . 273
Exception trace entry points. . . . . . . . . . . . . . . . . . 273
User exception trace entry points . . . . . . . . . . . . . . . . 273
Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Chapter 19. The QUERY SECURITY command . . . . . . . . . . . . 277

138 CICS TS for z/OS: CICS Application Programming Guide

Chapter 11. Application design
This chapter introduces some basic concepts to help you design CICS applications.
Changes are suggested that can improve performance and efficiency, but further
guidance on programming for efficiency is provided in Chapter 12, “Design for
performance,” on page 165.

The programming models implemented in CICS are inherited from those designed
for 3270s, and exhibit many of the characteristics of conversational,
terminal-oriented applications. There are basically three styles of programming
model:
v Terminal-initiated, that is, the conversational model
v Distributed program link (DPL), or the RPC model
v START, that is, the queuing model.

Once initiated, the applications typically use these and other methods of continuing
and distributing themselves, for example, with pseudoconversations, RETURN
IMMEDIATE or DTP. The main difference between these models is in the way that
they maintain state ( for example, security), and hence state becomes an integral
part of the application design. This presents the biggest problem when you attempt
to convert to another application model.

A pseudoconversational model is mostly associated with terminal-initiated

transactions and was developed as an efficient implementation of the
conversational model. With increased use of 1-in and 1-out protocols such as
HTTP, it is becoming necessary to add the pseudoconversational characteristic to
the DPL or RPC model.
v “Pseudoconversational and conversational design” on page 140
v “How tasks are started” on page 142
v “Which transaction?” on page 143
v “Separating business and presentation logic” on page 146
v “Multithreading: Reentrant, quasi-reentrant and threadsafe programs” on page
147
v “Storing data within a transaction” on page 155
v “Lengths of areas passed to CICS commands” on page 161
v “Minimizing errors” on page 162
v “Non-terminal transaction security” on page 163

© Copyright IBM Corp. 1989, 2005 139

Pseudoconversational and conversational design
In a conversational transaction, the length of time spent in processing each of a
user’s responses is extremely short when compared to the amount of time waiting
for the input. A conversational transaction is one that involves more than one input
from the terminal, so that the transaction and the user enter into a conversation. A
nonconversational transaction has only one input (the one that causes the
transaction to be invoked). It processes that input, responds to the terminal and
terminates.

Processor speeds, even allowing for accessing data sets, are considerably faster
than terminal transmission times, which are considerably faster than user response
times. This is especially true if users have to think about the entry or have to enter
many characters of input. Consequently, conversational transactions tie up storage
and other resources for much longer than nonconversational transactions.

A pseudoconversational transaction sequence contains a series of

nonconversational transactions that look to the user like a single conversational
transaction involving several screens of input. Each transaction in the sequence
handles one input, sends back the response, and terminates.

Before a pseudoconversational transaction terminates, it can pass data forward to

be used by the next transaction initiated from the same terminal, whenever that
transaction arrives. A pseudoconversational transaction can specify what the next
transaction is to be, using the TRANSID option of the RETURN command,
However, you should be aware that if another transaction is started for that device,
it may interrupt the pseudoconversational chain you have designed, unless you
specify the IMMEDIATE option on the RETURN command. In this case, the
transaction specified by the TRANSID command is attached regardless of any other
transactions queued for this terminal.

The RETURN command is described in the CICS Application Programming

Reference manual.

No transaction exists for the terminal from the time a response is written until the
user sends the next input and CICS starts the next transaction to respond to it.
Information that would normally be stored in the program between inputs is passed
from one transaction in the sequence to the next using the COMMAREA or one of
the other facilities that CICS provides for this purpose. (See Chapter 13, “Sharing
data across transactions,” on page 183 for details.)

There are two major issues to consider in choosing between conversational and
pseudoconversational programming.
v The effect of the transaction on contention resources, such as storage and
processor usage. Storage is required for control blocks, data areas, and
programs that make up a transaction, and the processor is required to start,
process, and terminate tasks. Conversational programs have a very high impact
on storage, because they last so long, relative to the sum of the transactions that
make up an equivalent pseudoconversational sequence. However, there is less
processor overhead, because only one transaction is initiated instead of one for
every input.
v The effect on exclusive-use resources, such as records in recoverable data
sets, recoverable transient data queues, enqueue items, and so on. Again, a
conversational transaction holds on to these resources for much longer than the
corresponding sequence of nonconversational transactions. From this point of

140 CICS TS for z/OS: CICS Application Programming Guide

view, pseudoconversational transactions are better for quick responses, but
recovery and integrity implications may mean that you prefer to use
conversational transactions.

To summarize, although conversational tasks may be easier to write, they have

serious disadvantages—both in performance (especially the need for virtual
storage) and in their effect on the overall operability of the CICS systems containing
them. Processors are now larger, with more real storage and more power than in
the past, and this makes conversational tasks less painful in small amounts; but if
you use conversational applications, you may rapidly run into virtual storage
constraint. If you run application programs above the line, you will probably
encounter ENQ problems before running into virtual storage constraints.

CICS ensures that changes to recoverable resources (such as data sets, transient
data, and temporary storage) made by a unit of work (UOW) are made completely
or not at all. A UOW is equivalent to a transaction, unless that transaction issues
SYNCPOINT commands, in which case a UOW lasts between syncpoints. For a
more detailed description of syncpoints and UOWs, see the CICS Recovery and
Restart Guide.

When a transaction makes a change to a recoverable resource, CICS makes that

resource unavailable to any other transaction that wants to change it until the
original transaction has completed. In the case of a conversational transaction, the
resources in question may be unavailable to other terminals for relatively long
periods.

For example, if one user tries to update a particular record in a recoverable data
set, and another user tries to do so before the first one finishes, the second user’s
transaction is suspended. This has advantages and disadvantages. You would not
want the second user to begin updating the record while the first user is changing it,
because one of them is working from what is about to become an obsolete version
of the record, and these changes erase the other user’s changes. On the other
hand, you also do not want the second user to experience the long, unexplained
wait that occurs when that transaction attempts to READ for UPDATE the record
that is being changed.

If you use pseudoconversational transactions, however, the resources are only very
briefly unavailable (that is, during the short component transactions). However,
unless all recoverable resources can be updated in just one of these transactions,
recovery is impossible because UOWs cannot extend across transactions. So, if
you cannot isolate updates to recoverable resources in this way, you must use
conversational transactions.

The previous example poses a further problem for pseudoconversational

transactions. Although you could confine all updating to the final transaction of the
sequence, there is nothing to prevent a second user from beginning an update
transaction against the same record while the first user is still entering changes.
This means that you need additional application logic to ensure integrity. You can
use some form of enqueuing, or you can have the transaction compare the original
version of the record with the current version before actually applying the update.

Chapter 11. Application design 141

Terminal interruptibility
When a conversational task is running, CICS allows nothing else to send messages
to that task’s terminal. This has advantages and disadvantages. The advantage is
that unexpected messages (for example, broadcasts) cannot interrupt the
user-machine dialogue and, worse, corrupt the formatted screen. The disadvantage
is that the end user cannot then be informed of important information, such as the
intention of the control operator to shut down CICS after 10 minutes. More
importantly, the unwitting failure of the end user to terminate the conversation may
in fact prevent or delay a normal CICS shutdown.

Pseudoconversational applications can allow messages to come through between

message pairs of a conversation. This means that notices like shutdown warnings
can be delivered. This might disturb the display screen contents, and can
sometimes interfere with transaction sequences controlled by the RETURN
command with the TRANSID option. However, this can be prevented by using the
IMMEDIATE option, or by forcing the terminal into NOATI status during the middle
of a linked sequence of interactions.

How tasks are started

Work is started in CICS—that is, tasks are initiated—in one of two ways:
1. From unsolicited input
2. By automatic task initiation (ATI)

Automatic task initiation occurs when:

v An existing task asks CICS to create another one. The START command, the
IMMEDIATE option on a RETURN command (discussed in “RETURN
IMMEDIATE” on page 363), and the SEND PAGE command (in “The SEND
PAGE command” on page 504) all do this.
v CICS creates a task to process a transient data queue (see “Automatic
transaction initiation (ATI)” on page 593).
v CICS creates a task to deliver a message sent by a BMS ROUTE request (see
Chapter 39, “Message routing,” on page 523). The CSPG tasks you see after
using the CICS-supplied transaction CMSG are an example of this. CMSG uses
a ROUTE command which creates a CSPG transaction for each target terminal
in your destination list.

The primary mechanism for initiating tasks, however, is unsolicited input. When a
user transmits input from a terminal which is not the principal facility of an existing
task, CICS creates a task to process it. The terminal that sent the input becomes
the principal facility of the new task.
Principal facility
CICS allows a task to communicate directly with only one terminal, namely
its principal facility. CICS assigns the principal facility when it initiates the
task, and the task “owns” the facility for its duration. No other task can use
that terminal until the owning task ends. If a task needs to communicate
with a terminal other than its principal facility, it must do so indirectly, by
creating another task that has the terminal as its principal facility. This
requirement arises most commonly in connection with printing, and how you
can create such a task is explained in “Using CICS printers” on page 409.
Notes:
1. You can specify a terminal destination other than your principal facility in
a SEND command if the destination is under TCAM control, an apparent

142 CICS TS for z/OS: CICS Application Programming Guide

exception to this rule. This is possible because communications with
TCAM terminals are always queued. Thus your task does not write
directly to the destination terminal, but instead writes to a queue that will
be delivered to it subsequently by TCAM (see “Using TCAM” on page
379) . BMS routing, described in Chapter 39, “Message routing,” on
page 523, is another form of indirect access to other terminals by
queues.
| 2. In CICS TS 3.1, local TCAM terminals are not supported. The only
| TCAM terminals supported are remote terminals connected to a
| pre-CICS TS 3.1 terminal-owning region by the DCB (not ACB) interface
| of TCAM.

Unsolicited inputs from other systems are handled in the same way: CICS creates a
task to process the input, and assigns the conversation over which the input arrived
as the principal facility. (Thus a conversation with another system may be either a
principal or alternate facility. In the case where a task in one CICS region initiates a
conversation with another CICS region, the conversation is an alternate facility of
the initiating task, but the principal facility of the partner task created by the
receiving system. By contrast, a terminal is always the principal facility.)
Alternate facility
Although a task may communicate directly with only one terminal, it can
also establish communications with one or more remote systems. It does
this by asking CICS to assign a conversation with that system to it as an
alternate facility. The task “owns” its alternate facilities in the same way
that it owns its principal facility. Ownership lasts from the point of
assignment until task end or until the task releases the facility.

Not all tasks have a principal facility. Tasks that result from unsolicited input always
do, by definition, but a task that comes about from automatic task initiation may or
may not need one. When it does, CICS waits to initiate the task until the requested
facility is available for assignment to the task.

Which transaction?
Having received an unsolicited input, how does CICS decide what to do with it?
That is, what transaction should the task created to process it execute? The short
answer is that the previous task with the same principal facility usually tells CICS
what transaction to execute next just before it ends, by the TRANSID option on its
final RETURN. This is almost always the case in a pseudoconversational
transaction sequence, and usually in menu-driven applications as well. Failing that,
and in any case to get a sequence started, CICS interprets the first few characters
of the input as a transaction code. However, it is more complicated than that; the
exact process goes as follows. The step numbers indicate the order in which the
tests are made and refer to Figure 33 on page 144, a diagram of this logic.

Chapter 11. Application design 143

0
Terminal Yes Has query Initiate CQRY
No
defined as to been run to this
be queried? terminal? *
No
Yes
1
3270 Yes Initiate printing
print request
key? *
No
2
Terminal Yes Paging Yes Initiate CSPG
supported by command
paging? entered? *
No
No
3
Transaction Yes Initiate specified
specified by transaction
TCT
TRANSID? *
No
4
Transaction Yes Initiate specified
specified by transaction
TRANSID of
RETURN? *
No
5
Initiate
Attach Yes transaction
FMH present? specified in
* attach FMH

No
6
Initiate
Yes PA, PF, LPA, Yes TASKREQ= Yes
transaction
3270?
or OPID? specified? specified by
* term input AID

No No
No
7
Terminal Initiate
Yes
input begins transaction
specified by
with tranid? * terminal input

* No * Global user exit XZCATT in

module DFHZATT is invoked
Send at these points.
"invalid tranid"
message
to terminal

Figure 33. Determining which transaction to execute

0. On the very first input from a terminal, CICS sometimes schedules a

preliminary task before creating one to process the input. This task
executes the CICS-supplied “query” transaction, CQRY, which causes the

144 CICS TS for z/OS: CICS Application Programming Guide

terminal to transmit an encoded description of some of its hardware
characteristics—extended attributes, character sets, and so on.
CQRY allows the system programmer to simplify maintenance of the
terminal network by omitting these particulars from the terminal definitions.
It occurs only if the terminal definition so specifies, and has no effect on the
subsequent determination of what transaction to use to process the input,
which goes as follows.
1. If the terminal is a 3270 and the input is the “print request key”, the
CICS-supplied transaction that prints the contents of the screen, CSPP, is
initiated. See “CICS print key” on page 414 for more information about this
feature. For this purpose, a “3270 logical unit” or any other device that
accepts the 3270 data stream counts as a 3270.
2. If full BMS support is present, the terminal is of a type supported by BMS
terminal paging, and the input is a paging command, the CICS-supplied
transaction CSPG is initiated to process the request. BMS support levels
are explained in “BMS support levels” on page 449, and the same section
contains a list of the terminals that BMS supports. The PGRET, SKRxxxx,
PGCHAIN, PGCOPY, and PGPURGE options in the system initialization
table define the paging commands. As paging requires full BMS, this step is
skipped if the CICS system contains less than that level.
3. If the terminal definition indicates that a specific transaction should be used
to process all unsolicited inputs from that terminal, the indicated transaction
is executed. (If present, this information appears in the TRANSACTION
attribute of the TERMINAL definition.)
4. If the previous task at the terminal specified the TRANSID option of the
RETURN command that ended it, the transaction named is executed.
5. If an attach function management header is present in the input, the attach
names in the header are converted to a 4-character CICS transaction
identifier, and that transaction is executed.
6. If the terminal is a 3270, and the attention identifier is defined as a
transaction, that transaction is executed. “Attention keys” on page 396
explains attention identifiers. You define one as a transaction identifier with
the TASKREQ attribute of the corresponding TRANSACTION definition.
7. If all of the preceding tests fail, the initial characters of the input are used to
identify the transaction to be executed. The characters used are the first
ones (up to four) after any control information in the data stream and before
the first field separator character or the next 3270 Control Character (X'00'
to X'3F'). Field separators are defined in the FLDSEP option of the system
initialization table (the default is a blank).
If there are no such characters in the input, as occurs when you use the
CLEAR key, for example, or if there is no transaction definition that matches
the input, CICS cannot determine what transaction to execute and sends an
“invalid transaction identification” message to the terminal.

Note: This logic for deciding which transaction to execute applies only to tasks
initiated to process unsolicited inputs. For automatic transaction initiation, the
transaction is always known. You specify it in the TRANSID option when you
create a task with a START or RETURN IMMEDIATE. Similarly, you specify
what transaction should be used to process a transient data queue in the
queue definition. Tasks created to route messages always execute the
CICS-supplied transaction CSPG.

Chapter 11. Application design 145

Separating business and presentation logic
In general, it is good practice to split applications into a part containing the business
code that is reusable, and a part responsible for presentation to the client. This
technique enables you to improve performance by optimizing the parts separately,
and allows you to reuse your business logic with different forms of presentation.

When separating the business and presentation logic, you need to consider the
following:
v Avoid affinities between the two parts of the application.
v Be aware of the DPL-restricted API; see CICS Application Programming
Reference for details.
v Be aware of hidden presentation dependencies, such as EIBTRMID usage.

Figure 34 illustrates a simple CICS application that accepts data from an end user,
updates a record in a file, and sends a response back to the end user. The
transaction that runs this program is the second in a pseudoconversation. The first
transaction has sent a BMS map to the end user’s terminal, and the second
transaction reads the data with the EXEC CICS RECEIVE MAP command, updates
the record in the file, and sends the response with the EXEC CICS SEND MAP
command.

The EXEC CICS RECEIVE and EXEC CICS SEND MAP commands are part of the
transaction’s presentation logic, while the EXEC CICS READ UPDATE and EXEC
CICS REWRITE commands are part of the business logic.

..
EXEC CICS RECEIVE MAP
..
EXEC CICS READ UPDATE
..
EXEC CICS REWRITE
..
EXEC CICS SEND MAP
..

Figure 34. CICS functions in a single application program

A sound principle of modular programming in CICS application design is to separate

the presentation logic from the business logic, and to use a communication area
and the EXEC CICS LINK command to make them into a single transaction.
Figure 35 and Figure 36 on page 147illustrate this approach to application design.

..
EXEC CICS RECEIVE MAP
..
EXEC CICS LINK..
..
EXEC CICS SEND MAP
..

Figure 35. Presentation logic

146 CICS TS for z/OS: CICS Application Programming Guide

..
EXEC CICS ADDRESS COMMAREA
..
EXEC CICS READ UPDATE
..
EXEC CICS REWRITE
..
EXEC CICS RETURN..

Figure 36. Business logic

Once the business logic of a transaction has been isolated from the presentation
logic and given a communication area interface, it is available for reuse with
different presentation methods. For example, you could use Distributed Program
Link (DPL) to implement a two-tier model, or CICS Web support with the CICS
business logic interface, where the presentation logic is HTTP-based.

Multithreading: Reentrant, quasi-reentrant and threadsafe programs

Multithreading is a technique that allows a single copy of an application program to
be processed by several transactions concurrently. For example, one transaction
may begin to execute an application program. When an EXEC CICS command is
reached, causing a CICS WAIT and call to the dispatcher, another transaction may
then execute the same copy of the application program. (Compare this with
single-threading, which is the execution of a program to completion: processing of
the program by one transaction is completed before another transaction can use it.)

Multithreading requires that all CICS application programs be quasi- reentrant; that
is, they must be serially reusable between entry and exit points. CICS application
programs using the EXEC CICS interface obey this rule automatically. For COBOL,
C, and C++ programs, reentrancy is ensured by a fresh copy of working storage
being obtained each time the program is invoked. You should always use the RENT
option on the compile or pre-link utility even for C and C++ programs that do not
have writable statics and are naturally reentrant. Temporary variables and
DFHEIPTR fields inserted by the CICS translator are usually defined as writable
static variables and require the RENT option. For these programs to stay reentrant,
variable data should not appear as static storage in PL/I, or as a DC in the program
CSECT in assembler language.

As well as requiring that your application programs are compiled and link-edited as
reentrant, CICS also identifies programs as being either quasi-reentrant or
threadsafe. These attributes are discussed in the following sections.

Quasi-reentrant application programs

CICS runs user programs under a CICS-managed task control block (TCB). If your
programs are defined as quasi-reentrant (on the CONCURRENCY attribute of the
program resource definition), CICS always invokes them under the CICS
quasi-reentrant (QR) TCB. The requirements for a quasi-reentrant program in a
multithreading context are less stringent than if the program were to execute
concurrently on multiple TCBs.

CICS requires that an application program is reentrant so that it guarantees

consistent conditions. In practice, an application program may not be truly reentrant;
CICS expects “quasi-reentrancy”. This means that the application program should
be in a consistent state when control is passed to it, both on entry, and before and
after each EXEC CICS command. Such quasi-reentrancy guarantees that each

Chapter 11. Application design 147

invocation of an application program is unaffected by previous runs, or by
concurrent multi-threading through the program by multiple CICS tasks.

For example, application programs could modify their executable code, or the
variables defined within the program storage, but these changes must be undone,
or the code and variables reinitialized, before there is any possibility of the task
losing control and another task executing the same program.

CICS quasi-reentrant user programs (application programs, user-replaceable

modules, global user exits, and task-related user exits) are given control by the
CICS dispatcher under the QR TCB. When running under this TCB, a program can
be sure that no other quasi-reentrant program can run until it relinquishes control
during a CICS request, at which point the user task is suspended, leaving the
program still “in use”.The same program can then be reinvoked for another task,
which means the application program can be in use concurrently by more than one
task, although only one task at a time can actually be executing.

To ensure that programs cannot interfere with each others working storage, CICS
obtains a separate copy of working storage for each execution of an application
program. Thus, if a user application program is in use by 11 user tasks, there are
11 copies of working storage in the appropriate dynamic storage area (DSA).

Quasi-reentrancy allows programs to access globally shared resources—for

example, the CICS common work area (CWA)—without the need to protect those
resources from concurrent access by other programs. Such resources are
effectively locked exclusively to the running program, until it issues its next CICS
request. Thus, for example, an application can update a field in the CWA without
using compare and swap (CS) instructions or locking (enqueuing on) the resource.

Note: The CICS QR TCB provides protection through exclusive control of global
resources only if all user tasks that access those resources run under the
QR TCB. It does not provide automatic protection from other tasks that
execute concurrently under another (open) TCB.

Take care if a program involves lengthy calculations: because an application

program retains control from one EXEC CICS command to the next, the processing
of other transactions on the QR TCB is completely excluded. However, you can use
the task-control SUSPEND command to allow other transaction processing to
proceed; see Chapter 44, “Task control,” on page 557 for details. Note that runaway
task time interval is controlled by the transaction definition and the system
initialization parameter ICVR. CICS purges a task that does not return control
before expiry of the IVCR-specified interval.

148 CICS TS for z/OS: CICS Application Programming Guide

Threadsafe programs
In the CICS open transaction environment (OTE), when application programs,
task-related user exits (TRUEs), global user exit programs, and user-replaceable
modules are defined to CICS as threadsafe, they can run concurrently on open
TCBs. Because of this, they cannot rely on quasi-reentrancy to protect shared
resources from concurrent access by another program. Furthermore,
quasi-reentrant programs might also be placed at risk if they access shared
resources that can also be accessed by a user task running concurrently under an
open TCB. The techniques used by user programs to access shared resources
must therefore take into account the possibility of simultaneous access by other
programs. To gain the performance benefits of the open transaction environment
while maintaining the integrity of shared resources, serialization techniques must be
used to prohibit concurrent access to shared resources. Programs that use
appropriate serialization techniques when accessing shared resources are
described as threadsafe. (The term fully reentrant is also used sometimes, but this
can be misunderstood, hence threadsafe is the preferred term.)

The performance benefits of being threadsafe can only be gained by applications

that involve a task-related user exit (TRUE) enabled using the OPENAPI option on
the ENABLE PROGRAM command. Task-related user exits like this are known as
open API TRUEs. An open API TRUE will be given control under an L8 mode open
TCB, and can use non-CICS APIs without having to create, manage and switch
between subtask TCBs. The CICS DB2 task-related user exit that is used by the
CICS DB2 attachment facility operates as an open API TRUE when CICS is
connected to DB2 Version 6 or later, which means that CICS DB2 applications can
gain performance benefits from being threadsafe (as explained in “SQL, threadsafe
and other programming considerations for CICS DB2 applications” in the CICS DB2
Guide). These are the only applications that might or might not be able to run on an
open TCB.

The goal of making programs threadsafe is to enable them to remain on an open

TCB, rather than switching back and forth between the open TCB and the QR TCB.
When CICS is connected to DB2 Version 6 or later, TCB switching occurs in the
following circumstances:
v When a program that is not defined as threadsafe makes a DB2 request, CICS
switches from the QR TCB (where the program is executing) to an open TCB,
and back to the QR TCB again when the DB2 request is complete.
v When a user exit program that is not defined as threadsafe is used in the course
of a DB2 request, CICS switches from the open TCB (where the DB2 request is
executing) to the QR TCB. The user exit program is executed on the QR TCB,
and then the task is switched back to the open TCB to complete the DB2
request. For example, the XRMIIN and XRMIOUT global user exits might be
invoked in the course of the DB2 request. If the exit programs are not defined as
threadsafe, this TCB switching occurs. If the exit programs are defined as
threadsafe, processing will continue throughout on the open TCB.
v When a program that is defined as threadsafe and is executing on an open TCB
invokes any EXEC CICS commands which are not threadsafe, CICS switches
back from the open TCB to the QR TCB to execute the non-threadsafe code.
The program then continues to execute on the QR TCB. If the program does not
make any further DB2 requests, then the switch back to the QR TCB is only a
disadvantage because it increases the usage of your QR TCB for the time taken
to run any remaining application code. However, if the program makes any
further DB2 requests, CICS must switch back again to the open TCB.

Chapter 11. Application design 149

v When a program that is defined as threadsafe and is executing on an open TCB
invokes a task-related user exit program which is not defined as threadsafe,
CICS switches back to the QR TCB and gives control to the task-related user
exit program. When the task-related user exit program completes processing, the
application program continues to execute on the QR TCB, in the same way as it
would after issuing a non-threadsafe EXEC CICS command.
v When a program that is defined as threadsafe and is executing on an open TCB
invokes a threadsafe CICS command, it is possible for a global user exit to be
invoked as part of executing the command. If a global user exit program is used
which is not defined as threadsafe, CICS switches back to the QR TCB and
gives control to the global user exit program. When the user exit program
completes processing, CICS switches back to the open TCB to continue
processing the threadsafe CICS command.
v When a program that is defined as threadsafe and is executing on an open TCB
completes, CICS switches back to the QR TCB for task termination. This switch
is always necessary.
The maximum TCB switching for a CICS DB2 application would occur if your
program used a non-threadsafe user exit program and a non-threadsafe EXEC
CICS command after every DB2 request. In particular, the use of a non-threadsafe
exit program on the CICS-DB2 mainline path (for example, a program that is
enabled at XRMIIN or XRMIOUT) causes more TCB switching than what is
experienced when CICS is connected to Version 5 or earlier.

If you want to make an application program remain on an open TCB:

1. Ensure that the program’s logic is threadsafe. That is, the native language
code in between the EXEC CICS commands must be threadsafe. If you define
a program to CICS as threadsafe but include application logic that is not
threadsafe, the results are unpredictable, and CICS is not able to protect you
from the possible consequences. Later in this topic, we have more information
about producing threadsafe application logic.
2. Ensure that the program uses only threadsafe EXEC CICS commands. The
commands that are threadsafe are indicated in the command syntax diagrams
in the CICS Application Programming Reference and the CICS System
Programming Reference with the statement ″This command is threadsafe″, and
are listed in Appendix L of the CICS Application Programming Reference and
Appendix D of the CICS System Programming Reference. If you include a
non-threadsafe EXEC CICS command in a program which is running on an
open TCB, CICS switches back from the open TCB to the QR TCB to ensure
that the command is processed safely. The TCB switching could be detrimental
to the application’s performance.
3. Ensure that the program is defined to CICS as threadsafe. Use the
CONCURRENCY attribute of the program resource definition to do this. By
defining a program to CICS as threadsafe, you are only specifying that the
application logic is threadsafe, not that all the EXEC CICS commands included
in the program are threadsafe. CICS can ensure that EXEC CICS commands
are processed safely by using TCB switching. In order to permit your program to
run on an open TCB, CICS needs you to guarantee that your application logic is
threadsafe.
4. Ensure that any user exit programs in the execution path used by the
program are coded to threadsafe standards and defined to CICS as
threadsafe. This might include dynamic plan exits, global user exits, or
task-related user exits. (Note for task-related user exits, enabling the exit
program using the OPENAPI option on the ENABLE PROGRAM command
means that CICS overrides the CONCURRENCY setting on the exit’s program

150 CICS TS for z/OS: CICS Application Programming Guide

definition with OPENAPI.) When CICS is connected to DB2 Version 6 or later,
the CICS DB2 task-related user exit DFHD2EX1 is threadsafe. “SQL, threadsafe
and other programming considerations for CICS DB2 applications” in the CICS
DB2 Guide has more information on other exits that are particularly important
for CICS DB2 requests. These exits include the default dynamic plan exit
DSNCUEXT (which is not defined as threadsafe), the alternative dynamic plan
exit DFHD2PXT (which is defined as threadsafe), and the global user exits
XRMIIN and XRMIOUT. Also be aware of the global user exits XEIIN and
XEIOUT, which are invoked before and after EXEC CICS commands, and
XPCFTCH, which is invoked before a PPT-defined program receives control. Be
sure that user exit programs supplied by any vendor software are coded to
threadsafe standards and defined to CICS as threadsafe.
5. If you are coding a user exit program (a global user exit or a task-related
user exit), you can define it as threadsafe so that it will be used on the same L8
TCB as a threadsafe application which calls it. Additionally, a task-related user
exit can be enabled using the OPENAPI option on the ENABLE PROGRAM
command so that it will be given control under an L8 TCB, use non-CICS APIs
without having to create and manage subtask TCBs, and exploit the open
transaction environment for itself. (Enabling the exit program using the
OPENAPI option on the ENABLE PROGRAM command means that CICS
overrides the CONCURRENCY setting on the exit’s program definition with
OPENAPI.) Global user exit programs can be handled in the same way as an
ordinary application program—by using threadsafe application logic and
threadsafe EXEC CICS commands, and defining the program as threadsafe.
“Writing global user exit programs” in the CICS Customization Guide has
general information about writing this type of program. For task-related user exit
programs, see “Writing a task-related user exit program” in the CICS
Customization Guide for more detailed information about how this type of
program can exploit the open transaction environment safely. Note when you
enable an exit program using the OPENAPI option, this indicates to CICS that
the program’s logic is threadsafe.

To make your program’s application logic threadsafe, ensure that it uses appropriate
serialization techniques when accessing shared resources. For most resources,
such as files, transient data queues, temporary storage queues, and DB2 tables,
CICS processing automatically ensures access in a threadsafe manner. As
described above, some of the CICS commands that operate on these resources are
coded to use appropriate serialization techniques that allow them to execute on
open TCBs (that is, they are threadsafe commands). Where this is not the case,
CICS ensures threadsafe processing by forcing a switch to the QR TCB, so that
access to the resources is serialized regardless of the behaviour of the command.
However, for any other resources which are accessed directly by user programs,
such as shared storage, it is the responsibility of the user program to ensure
threadsafe processing.

Typical examples of shared storage are the CICS CWA, the global work areas for
global user exits, and storage acquired explicitly by the application program with the
shared option. You can check whether your application programs use these types of
shared storage by looking for occurrences of the following EXEC CICS commands:
v ADDRESS CWA
v EXTRACT EXIT
v GETMAIN SHARED
Although some of these commands are themselves threadsafe, they all give access
to global storage areas, so the application logic that follows these commands and

Chapter 11. Application design 151

uses the global storage areas has the potential to be non-threadsafe. To ensure it is
threadsafe, an application program must include the necessary synchronization
logic to guard against concurrent update.

The load module scanner utility includes a sample table, DFHEIDTH, to help you
identify whether the application logic in your existing application programs is
threadsafe. DFHEIDTH contains the filter set for CICS commands that give access
to shared storage. The use of these commands could make a program not
threadsafe, unless it has the necessary synchronization logic in place to ensure
serialization and prevent concurrent update.

Remember that DFHEIDTH, as supplied, is not testing the programs for

non-threadsafe CICS commands (that is, commands that cause a switch to the QR
TCB), but rather to determine if the application is using CICS commands which give
rise to the possibility that the application logic could be not threadsafe. You can
modify the supplied sample table to add any non-threadsafe CICS commands that
you want to detect. Another sample table, DFHEIDNT, is supplied to help identify
the CICS commands in your application which are non-threadsafe. For more
information on using the load module scanner, see the CICS Operations and
Utilities Guide.

Note: When identifying programs that use shared resources, you should also
include any program that modifies itself. Such a program is effectively
sharing storage and should be considered at risk.

Techniques that you can use to provide threadsafe processing when accessing a
shared resource are as follows:
v Retry access, if the resource has been changed concurrently by another
program, using the compare and swap instruction.
v Enqueue on the resource, to obtain exclusive control and ensure that no other
program can access the resource, using:
– An EXEC CICS ENQ command, in an application program
– An XPI ENQUEUE function call to the CICS enqueue (NQ) domain, in a
global user exit program
– An MVS service such as ENQ (in an open API task-related user exit only
when L8 TCBs are enabled for use). Note that the use of MVS services in an
application which can execute under the QR TCB might result in performance
degradation due to the TCB being placed in a wait.
v Perform accesses to shared resources only in a program that is defined as
quasi-reentrant, by linking to the quasi-reentrant program using the EXEC CICS
LINK command.
This technique applies to threadsafe application programs and open API
task-related user exits only. A linked-to program defined as quasi-reentrant runs
under the QR TCB and can take advantage of the serialization provided by CICS
quasi-reentrancy. Note that even in quasi-reentrant mode, serialization is
provided only for as long as the program retains control and does not wait (see
“Quasi-reentrant application programs” on page 147 for more information).
v Place all transactions that access the shared resource into a restricted
transaction class (TRANCLASS), one that is defined with the number of active
tasks specified as MAXACTIVE(1).This last approach effectively provides a very
coarse locking mechanism, but may have a severe impact on performance.

Note: Although the term threadsafe is defined in the context of individual programs,
a user application as a whole can only be considered threadsafe if all the

152 CICS TS for z/OS: CICS Application Programming Guide

application programs that access shared resources obey the rules. A
program that is written correctly to threadsafe standards cannot safely
update shared resources if another program that accesses the same
resources does not obey the threadsafe rules.

Threadsafe considerations for statically or dynamically called

routines
If you define a program with CONCURRENCY(THREADSAFE), all routines which
are statically or dynamically called from that program (for example, Cobol routines)
must also be coded to threadsafe standards.

When an EXEC CICS LINK command is used to link from one program to another,
the program link stack level is incremented. However, a routine that is statically
called, or dynamically called, does not involve passing through the CICS command
level interface, and so does not cause the program link stack level to be
incremented. With Cobol routines, for a static call, a simple branch and link is
involved to an address that is resolved at linkedit time. For a dynamic call, although
there is a program definition involved, this is required only to allow Language
Environment to load the program. After that, a simple branch and link is executed.
So when a routine is called by either of these methods, CICS does not regard this
as a change of program. The program that called the routine is still considered to
be executing, and so the program definition for that program is still considered to be
the current one.

If the program definition for the calling program states

CONCURRENCY(THREADSAFE), the called routine must also comply with this
specification. Programs with the CONCURRENCY(THREADSAFE) attribute remain
on an open TCB when they return from a DB2 call, and this is not appropriate for a
program that is not threadsafe. For example, consider the situation where the initial
program of a transaction, program A, issues a dynamic call to program B, which is
a Cobol routine. Because the CICS command level interface was not involved,
CICS is unaware of the call to program B, and considers the current program to be
program A. Program B issues a DB2 call. On return from the DB2 call, CICS needs
to determine whether the program can remain on the open TCB, or whether the
program has to switch back to the QR TCB to ensure threadsafe processing. To do
this, CICS examines the CONCURRENCY attribute of what it considers to be the
current program, which is program A. If program A is defined as
CONCURRENCY(THREADSAFE), then CICS allows processing to continue on the
open TCB. In fact program B is executing, so if processing is to continue safely,
program B must be coded to threadsafe standards.

| OPENAPI programs
| OPENAPI programs (that is, those defined in the resource definition with the
| OPENAPI attribute) are invoked on an open L8 or L9 mode TCB (depending on the
| EXECKEY attribute) instead of the main CICS QR TCB.

| Obligations of OPENAPI programs

| An OPENAPI program, although freed from the constraints imposed by the QR
| TCB, nevertheless does have obligations both to the CICS system as a whole and
| to future users of the L8 or L9 TCB it is using. An L8 or L9 TCB is dedicated for use
| by the CICS task to which it is allocated, but once the CICS task has completed,
| the TCB is returned to the dispatcher-managed pool of such TCBs, provided it is
| still in a ″clean ″ state. (An unclean TCB in this context means that the task using
| the L8 or L9 mode TCB suffered an unhandled abend in an OPENAPI program, and
| not that the program has broken the threadsafe restrictions, which CICS would not
| detect.) Note that the TCB is not dedicated for use by a particular OPENAPI

Chapter 11. Application design 153

| program, but is used by all OPENAPI programs and OPENAPI TRUEs invoked by
| the CICS task to which the L8 mode TCB is allocated. Also, if an application
| program invoking an OPENAPI program is coded to threadsafe standards, and
| defined to CICS as threadsafe, it continues to execute on the L8 mode TCB on
| return from the program.

| Threadsafe restrictions: An OPENAPI program must not treat the executing

| open TCB environment in such a way that it causes problems for:
| v Application program logic that could run on the open TCB
| v OPENAPI TRUEs called by the same task
| v Future tasks that might use the open TCB
| v CICS management code.
| At your own risk, if your OPENAPI program decides to use other (non CICS) APIs,
| you must be aware of the following:
| v When invoking CICS services, or when returning to CICS, an OPENAPI program
| must ensure it restores the MVS programming environment as it was on entry to
| the program. This includes cross-memory mode, ASC mode, request block (RB)
| level, linkage stack level, TCB dispatching priority, in addition to cancelling any
| ESTAEs added.
| v At CICS task termination, an OPENAPI program must ensure it leaves the open
| TCB in a state suitable to be reused by another CICS transaction. In particular, it
| must ensure that all non-CICS resources acquired specifically on behalf of the
| terminating task are freed. Such resources might include:
| – Dynamically allocated data sets
| – Open ACBs or DCBs
| – STIMERM requests
| – MVS managed storage
| – ENQ requests
| – Attached subtasks
| – Loaded modules
| – Owned data spaces
| – Added access list entries
| – Name/token pairs
| – Fixed pages
| – Security settings (TCBSENV must be set to zero)
| v An OPENAPI program must not use the following MVS system services that will
| affect overall CICS operation:
| – CHKPT
| – ESPIE
| – QEDIT
| – SPIE
| – STIMER
| – TTIMER
| – XCTL / XCTLX
| – Any TSO/E services.
| v An OPENAPI program must not invoke under the L8 or L9 mode TCB a
| Language Environment program that is using MVS Language Environment
| services, because L8 and L9 mode TCBs are initialized for Language
| Environment using CICS services.
154 CICS TS for z/OS: CICS Application Programming Guide
| Using the FORCEQR system initialization parameter
If you are running applications with programs defined as threadsafe to exploit OTE
(for example, in CICS DB2 applications) problems could occur that indicate that one
or more programs is not actually threadsafe. If this happens, you can force all your
applications programs on to the QR TCB using the FORCEQR system initialization
parameter. This could be particularly useful in a production region, where you
cannot afford to have applications out of service while you investigate the problem.

The default for this parameter is FORCEQR=NO, which means that CICS honors
the CONCURRENCY attribute on your program resource definitions. As a
temporary measure, while you investigate and resolve problems connected with
threadsafe-defined programs, you can set FORCEQR=YES. Remember to change
this back to FORCEQR=NO when you are ready for your programs to resume use
of open TCBs under the OTE.

Non-reentrant programs
There is nothing to prevent non-reentrant application programs being executed by
CICS. However, such an application program would not provide consistent results in
a multi-threading environment.

To use non-reentrant application programs, or tables or control blocks that are

modifiable by the execution of associated application programs, specify the
RELOAD(YES) option on their resource definition. RELOAD(YES) results in a fresh
copy of the program or module being loaded into storage for each request. This
option ensures that multithreading tasks that access a non- reentrant program or
table each work from their own copy of the program, and are unaffected by
changes made to another version of the program by other concurrent tasks running
in the CICS region.

For information about RELOAD(YES), see the CICS Resource Definition Guide.

CICS/ESA® loads any program link-edited with the RENT attributes into a CICS
read-only dynamic storage area (DSA). CICS uses the RDSA for RMODE(24)
programs, and the ERDSA for RMODE(ANY) programs.By default, the storage for
these DSAs is allocated from read-only key-0 protected storage, protecting any
modules loaded into them from all except programs running in key-zero or
supervisor state.(If CICS initializes with the RENTPGM=NOPROTECT system
initialization parameter, it does not use read-only key-0 storage, and use CICS-key
storage instead.)

If you want to execute a non-reentrant program or module, it must be loaded into a

non-read-only DSA. The SDSA and ESDSA are user-key storage areas for
non-reentrant user-key programs and modules.

For more information about CICS DSAs, refer to the CICS System Definition Guide.

Storing data within a transaction

CICS provides a variety of facilities for storing data within and between
transactions. Each one differs according to how available it leaves data to other
programs within a transaction and to other transactions; in the way it is
implemented; and in its overhead, recovery, and enqueuing characteristics.

Storage facilities that exist for the lifetime of a transaction include:

v Transaction work area (TWA)

Chapter 11. Application design 155

v User storage (by a GETMAIN command issued without the SHARED option)
v COMMAREA
v Program storage

All of these areas are main storage facilities and come from the same basic
source—the dynamic storage areas (DSAs) and extended dynamic storage areas
(EDSAs). None of them is recoverable, and none can be protected by resource
security keys. They differ, however, in accessibility and duration, and therefore each
meets a different set of storage needs.

Transaction work area (TWA)

The transaction work area (TWA) is allocated when a transaction is initiated, and is
initialized to binary zeroes. It lasts for the entire duration of the transaction, and is
accessible to all local programs in the transaction. Any remote programs that are
linked by a distributed program link command do not have access to the TWA of the
client transaction. The size of the TWA is determined by the TWASIZE option on the
transaction resource definition. If this size is nonzero, the TWA is always allocated.
See the CICS Resource Definition Guide for more information about determining
the TWASIZE.

Processor overhead associated with using the TWA is minimal. You do not need a
GETMAIN command to access it, and you address it using a single ADDRESS
command. The TASKDATAKEY option governs whether the TWA is obtained in
CICS-key or user-key storage. (See Chapter 46, “Storage control,” on page 575 for
a full explanation of CICS-key and user-key storage.) The TASKDATALOC option of
the transaction definition governs whether the acquired storage can be above the
16MB line or not.

The TWA is suitable for quite small data storage requirements and for larger
requirements that are both relatively fixed in size and are used more or less for the
duration of the transaction. Because the TWA exists for the entire transaction, a
large TWA size has much greater effect for conversational than for
nonconversational transactions.

User storage
User storage is available to all the programs in a transaction, but some effort is
required to pass it between programs using LINK or XCTL commands. Its size is
not fixed, and it can be obtained (using GETMAIN commands) just when the
transaction requires it and returned as soon as it is not needed. Therefore, user
storage is useful for large storage requirements that are variable in size or are
shorter-lived than the transaction.

See Chapter 46, “Storage control,” on page 575 for information about how
USERDATAKEY and CICSDATAKEY override the TASKDATAKEY option of the
GETMAIN command.

The SHARED option of the GETMAIN command causes the acquired storage to be
retained after the end of the task. The storage can be passed in the communication
area from one task to the next at the same terminal. The first task returns the
address of the communication area in the COMMAREA option of the RETURN
command. The second task accesses the address in the COMMAREA option of the
ADDRESS command. You must use the SHARED option of the GETMAIN
command to ensure that your storage is in common storage.

156 CICS TS for z/OS: CICS Application Programming Guide

The amount of processor overhead involved in a GETMAIN command means that
you should not use it for a small amount of storage. You should use the TWA for
the smaller amounts or group them together into a larger request. Although the
storage acquired by a GETMAIN command may be held somewhat longer when
using combined requests, the processor overhead and the reference set size are
both reduced.

COMMAREA in LINK and XCTL commands

A communication area (COMMAREA) is a facility used to transfer information
between two programs within a transaction or between two transactions from the
same terminal. For information about using COMMAREA between transactions, see
“Using the COMMAREA in RETURN commands” on page 187.

Information in COMMAREA is available only to the two participating programs,

unless those programs take explicit steps to make the data available to other
programs that may be invoked later in the transaction. When one program links to
another, the COMMAREA may be any data area to which the linking program has
access. It is often in the working storage or LINKAGE SECTION of that program. In
this area, the linking program can both pass data to the program it is invoking and
receive results from that program. When a program transfers control (an XCTL
command) to another, CICS may copy the specified COMMAREA into a new area
of storage, because the invoking program and its control blocks may no longer be
available after it transfers control. In either case, the address of the area is passed
to the program that is receiving control, and the CICS command-level interface sets
up addressability. See Chapter 45, “Program control,” on page 561 for further
information.

CICS ensures that any COMMAREA is addressable by the program that receives it,
by copying below the 16MB line and/or to the USERKEY storage where necessary,
depending on the addressing mode and EXECKEY attributes of the receiving
program. See Chapter 46, “Storage control,” on page 575 for more information
about EXECKEY.

CICS contains algorithms designed to reduce the number of bytes to be

transmitted. The algorithms remove some trailing binary zeros from the
COMMAREA before transmission and restore them after transmission. The
operation of these algorithms is transparent to the application programs, which
always see the full-size COMMAREA.

The overhead for using COMMAREA in an LINK command is minimal; it is slightly

more with the XCTL and RETURN commands, when CICS creates the
COMMAREA from a larger area of storage used by the program.

| Channels in LINK and XCTL commands

| Instead of using a communication area (COMMAREA), a more modern method of
| transferring data between CICS programs is to use a channel. Channels have
| several advantages over COMMAREAs—see Benefits of channels. To pass a
| channel on a LINK or XCTL command, you use the CHANNEL option in place of
| the COMMAREA option.

| Channels are described in Enhanced inter-program data transfer: channels as

| modern-day COMMAREAs.

Chapter 11. Application design 157

Program storage
CICS creates a separate copy of the variable area of a CICS program for each
transaction using the program. This area is known as program storage. This area
is called the WORKING-STORAGE SECTION in COBOL, automatic storage in C,
C++, and PL/I, and the DFHEISTG section in assembler language. Like the TWA,
this area is of fixed size and is allocated by CICS without you having to issue a
GETMAIN command. The EXEC CICS interface sets up addressability
automatically. Unlike the TWA, however, this storage lasts only while the program is
being run, not for the duration of the transaction. This makes it useful for data areas
that are not required outside the program and that are either small or, if large, are
fixed in size and are required for all or most of the execution time of the program.

Temporary storage
Temporary storage is the primary CICS facility for storing data that must be
available to multiple transactions.

Data items in temporary storage are kept in queues whose names are assigned
dynamically by the program storing the data. A temporary storage queue containing
multiple items can be thought of as a small data set whose records can be
addressed either sequentially or directly, by item number. If a queue contains only a
single item, it can be thought of as a named scratch-pad area.

Temporary storage data sharing means that main or auxiliary storage can be
replaced by one or more temporary storage pools.

Temporary storage is implemented by the following methods:

v By using a particular queue that is determined by what is specified on the
command that creates the first item
v By specifying the MAIN option so that the queue is kept in main storage, in
space taken from the dynamic storage area
v By using the AUXILIARY option so that the queue is written to an
entry-sequenced VSAM data set
Whichever method you use, CICS maintains an index of items in main storage.

Note that if the QNAME option matches the prefix of an installed TSMODEL
resource definition, the MAIN or AUXILIARY value specified in the TSMODEL takes
precedence over that specified in the command.

See the CICS Resource Definition Guide for more information about the use of
TSMODELs to define temporary storage queues.

The addition of temporary storage data sharing gives another type of temporary
storage queue that can be supported concurrently. These temporary storage queues
can be defined as local, remote, or shared, and they can be stored in TS pools in
the coupling facility.

These methods have characteristics that you should bear in mind:

v Main temporary storage requires much more virtual storage than auxiliary. In
general, you should use it only for small queues that have short lifetimes or are
accessed frequently. Auxiliary temporary storage is specifically designed for
relatively large amounts of data that have a relatively long lifetime or are

158 CICS TS for z/OS: CICS Application Programming Guide

accessed infrequently. You may find it useful to establish a cutoff point of a
lifetime of one second to decide which queues should be in main storage and
which should be in auxiliary.
v You can make queues in auxiliary storage recoverable, but not queues in main
storage:
v Shared temporary storage applies only to non-recoverable queues.
– Only one transaction at a time can update a recoverable temporary storage
queue. So, if you choose to make queues recoverable, bear in mind the
probability of enqueues.
– You should ensure that there are enough buffers and VSAM strings to
eliminate as much contention as possible.
v If a task tries to write to temporary storage and there is no space available, CICS
normally suspends it, although the task can regain control in this situation by
using either a HANDLE CONDITION NOSPACE command, or the RESP or
NOHANDLE option on the WRITEQ TS command. If suspended, the task is not
resumed until some other task frees the necessary space in main storage or the
VSAM data set. This can produce unexplained response delays, especially if the
waiting task owns exclusive-use resources, in which case all other tasks needing
those resources must also wait.
v It can be more efficient to use main temporary storage exclusively in very
low-volume systems that have no need for recovery. You need to balance the
needs for additional main storage requirement for the VSAM access method and
a larger temporary storage program with the need for main storage for the
temporary storage records.

The following points apply to temporary storage in general:

v You must use an EXEC CICS command every time data is written to or read
from a temporary storage queue, and CICS must find or insert the data using its
internal index. This means that the overhead for using main temporary storage is
greater than for the CWA or TCTUA. With auxiliary storage, (often the most
frequently used), there is usually data set I/O as well, which increases overhead
even more.
v You need not allocate temporary storage until it is required; you need keep it only
as long as it is required, and the item size is not fixed until you issue the
command that creates it. This makes it a good choice for relatively high-volume
data and data that varies in length or duration.
v The fact that temporary storage queues can be named as they are created
provides a very powerful form of direct access to saved data. You can access
scratch-pad areas for terminals, data set records, and so on, simply by including
the terminal name or record key in the queue name.
v Resource protection is available for temporary storage.

Intrapartition transient data

Intrapartition transient data has some characteristics in common with auxiliary
temporary storage. (See “Efficient sequential data set access” on page 175 for
information about extrapartition transient data.) Like temporary storage,
intrapartition transient data consists of queues of data, kept together in a single
data set, with an index that CICS maintains in main storage.

You can use transient data for many of the purposes for which you would use
auxiliary temporary storage, but there are some important differences.
v Transient data does not have the same dynamic characteristics as temporary
storage. Unlike temporary storage queues, transient data queues cannot be

Chapter 11. Application design 159

created at the time data is written by an application program. However, transient
data queues can be defined and installed using RDO while CICS is running.
v Transient data queues must be read sequentially. Each item can be read only
once. After a transaction reads an item, that item is removed from the queue and
is not available to any other transaction. In contrast, items in temporary storage
queues may be read either sequentially or directly (by item number). They can
be read any number of times and are not removed from the queue until the entire
queue is purged.
These two characteristics make transient data inappropriate for scratch-pad data
but suitable for queued data such as audit trails and output to be printed. In fact,
for data that is read sequentially once, transient data is preferable to temporary
storage.
v Items in a temporary storage queue can be changed; items in transient data
queues cannot.
v Transient data queues are always written to a data set. (There is no form of
transient data that corresponds to main temporary storage.)
v You can define transient data queues so that writing items to the queue causes a
specific transaction to be initiated (for example, to process the queue).
Temporary storage has nothing that corresponds to this “trigger” mechanism,
although you may be able to use a START command to perform a similar
function.
v Transient data has more recovery options than temporary storage. Transient data
queues can be physically or logically recoverable.
v Because the commands for intrapartition and extrapartition transient data are
identical, you can switch between the two types of data set. To do this, change
only the transient data queue definitions and not your application programs
themselves. Temporary storage has no corresponding function of this kind.

GETMAIN SHARED command

Storage acquired using the SHARED option of the GETMAIN command is not
released when the acquiring task ends. This enables one task to leave data in
storage for use by another task. The storage is not released until a FREEMAIN
command is issued, either by the acquiring task or by another task.

Your own data sets

You can also use your own data sets to save data between transactions. This
method probably has the largest overhead in terms of instructions processed,
buffers, control blocks, and user programming requirements, but does provide extra
functions and flexibility. Not only can you define data sets as recoverable resources,
but you can log changes to them for forward recovery. You can specify the number
of strings for the data set, (as well as on the temporary storage and transient data
sets), to ensure against access contention, and you can use resource security.

160 CICS TS for z/OS: CICS Application Programming Guide

Lengths of areas passed to CICS commands
When a CICS command includes a LENGTH option, it usually accepts the length as
a signed halfword binary value. This places a theoretical upper limit of 32KB on the
length. In practice, the limits are less than this and vary for each command. The
limits depend on data set definitions, recoverability requirements, buffer sizes, and
local networking characteristics.

LENGTH options
In COBOL, C, C++, PL/I, and assembler language, the translator deals with lengths.
See the CICS Application Programming Reference manual for programming
information, including details of when you need to specify the LENGTH option. You
should not let the length specified in CICS command options exceed 24KB, if
possible.

Many commands involve the transfer of data between the application program and
CICS. In all cases, the length of the data to be transferred must be provided by the
application program.

In most cases, the LENGTH option must be specified if the SET option is used; the
syntax of each command and its associated options show whether this rule applies.

There are options on the WAIT EXTERNAL command and a number of QUERY
SECURITY commands that give the resource status or definition. CICS supplies the
values associated with these options, hence the name, CICS-value data areas. The
options are shown in the syntax of the commands with the term “cvda” in
parentheses. For programming information about CVDAs, see the CICS Application
Programming Reference manual.

For journal commands, the restrictions apply to the sum of the LENGTH and
PFXLENG values. (See “Journaling” on page 253.)

Journal records
For journal records, the journal buffer size may impose a limit lower than 64KB.
Note that the limit applies to the sum of the LENGTH and PFXLENG values.

Data set definitions

For temporary storage, transient data, and file control, the data set definitions can
impose limits lower than 24KB. For details, see the CICS System Definition Guide
(for information about creating data sets) and the CICS Resource Definition Guide
(for information about resource definition for files).

Recommendation
For any command in any system, 24KB is a good working limit for LENGTH
specifications. Subject to user-specified record and buffer sizes, this limit is
unlikely either to cause an error or to place a constraint on applications.

You will probably not find a 24KB limit too much of a hindrance; online programs do
not often handle such large amounts of data, for the sake of efficiency and
response time.

Note: The value in the LENGTH option should never exceed the length of the data
area addressed by the command.

Chapter 11. Application design 161

Minimizing errors
This section describes ways of making your applications error-free. Some of these
suggestions apply not only to programming, but also to operations and systems.

What often happens is that, when two application systems that run perfectly by
themselves are run together, performance goes down and you begin experiencing
“lockouts” or waits. The scope of each system has not been defined well enough.

The key points in a well-designed application system are:

v At all levels, each function is defined clearly with inputs and outputs well-stated
v Resources that the system uses are adequately-defined
v Interactions with other systems are known

Protecting CICS from application errors

There are various tools and techniques you can use to minimize errors in your
application programs. In general:
v You can use the storage protection facility to prevent CICS code and control
blocks from being overwritten accidentally by your application programs. You can
choose whether you want to use this facility by means of CICS system
initialization parameters. See the CICS System Definition Guide for more
information about this facility.
v Consider using standards that avoid problems that may be caused by techniques
such as the use of GETMAIN commands.

Testing applications
The following general rules apply to testing applications:
v Do not test on a production CICS system—use a test system, where you can
isolate errors without affecting “live” databases.
v Have the testing done by someone other than the application developer, if
possible.
v Document the data you use for testing.
v Test your applications several times. See Chapter 49, “Testing applications,” on
page 601 for more information about testing applications.
v Use the CEDF transaction for initial testing. See Chapter 50, “Execution
diagnostic facility (EDF),” on page 605 for more information about using CEDF.
v Use stress or volume testing to catch problems that may not arise in a
single-user environment. Teleprocessing Network Simulator (TPNS, licensed
program number 5740-XT4) is a good tool for doing this.
TPNS is a telecommunications testing package that enables you to test and
evaluate application programs before you install them. You can use TPNS for
testing logic, user exit routines, message logging, data encryption, and
device-dependencies, if these are used in application programs in your
organization. It is useful in investigating system performance and response times,
stress testing, and evaluating TP network design. For further information, see the
TPNS General Information manual.
v Test whether the application can handle correct data and incorrect data.
v Test against complete copies of the related databases.
v Consider using multiregion operation. (See the CICS Intercommunication Guide
for more information.)
v Before you move an application to the production system, it is a good idea to run
a final set of tests against a copy of the production database to catch any errors.

162 CICS TS for z/OS: CICS Application Programming Guide

In particular, look for destroyed storage chains.

Assembler language programs (if not addressing data areas properly) can be
harder to identify because they can alter something that affects (and abends)
another transaction.

For more information about solving a problem, see the CICS Problem Determination
Guide.

Non-terminal transaction security

CICS can now protect, against unauthorized use, resources used in transactions
that are not associated with a terminal. These transactions are of three types:
v Transactions that are started by a START command and that do not specify a
terminal ID.
v Transactions that are started, without a terminal, as a result of the trigger level
being reached for an intrapartition transient data queue.
v The CICS internal transaction (CPLT), which runs during CICS startup, to
execute programs specified in the program list table (PLT). This transaction
executes both first and second phases of PLTs.

Also, resource security checking can now be carried out for PLT programs that are
run during CICS shutdown. PLT shutdown programs execute as part of the
transaction that requests the shutdown, and therefore run under the authorization of
the user issuing the shutdown command.

The START command handles security for non-terminal transactions started by the
START command.

A surrogate user who is authorized to attach a transaction for another user, or

cause it to be attached, or who inherits all the resource access authorizations for
that transaction, can act for the user.

CICS can issue up to three surrogate user security checks on a single START
command, depending on the circumstances:
1. The userid of the transaction that issues the START command, if USERID is
specified
2. The userid of the CEDF transaction, if the transaction that issues the START
command is being run in CEDF dual-screen mode
3. The CICS region userid of the remote system, if the START command is
function shipped to another CICS system and link security is in effect.

A separate surrogate user security check is done for each of these userids, as
required, before the transaction is attached.

For programming information about the USERID option, USERIDERR condition,

and INVREQ, and NOTAUTH conditions, see the CICS Application Programming
Reference manual.

Chapter 11. Application design 163

164 CICS TS for z/OS: CICS Application Programming Guide
Chapter 12. Design for performance
In this chapter, design changes are suggested that can improve performance and
efficiency without much change to the application program itself.
v “Program size”
v “Virtual storage” on page 166
v “Exclusive control of resources” on page 169
v “Operational control” on page 170
v “Operating system waits” on page 171
v “The NOSUSPEND option” on page 171
v “Efficient data operations” on page 172
v “Efficient terminal operations” on page 176

Other aspects of application design are addressed in Chapter 11, “Application

design,” on page 139

If you have a performance problem that applies in a particular situation, try to

isolate the changes you make so that their effects apply only in that situation. After
fixing the problem and testing the changes, use them in your most commonly-used
programs and transactions, where the effects on performance are most noticeable.

Program size
The early emphasis on small programs led CICS programmers to break up
programs into units that were as small as possible, and to transfer control using the
XCTL command, or link using the LINK command, between them. In current
systems, however, it is not always better to break up programs into such small
units, because there is CICS processing overhead for each transfer and, for LINK
commands, there is also storage overhead for the register save areas (RSAs).

For modestly-sized blocks of code that are processed sequentially, inline code is
most efficient. The exceptions to this rule are blocks of code that are:
v Fairly long and used independently at several different points in the application
v Subject to frequent change (in which case, you balance the overhead of LINK or
XCTL commands with ease of maintenance)
v Infrequently used, such as error recovery logic and code to handle uncommon
data combinations

If you have a block of code that for one of these reasons, has to be written as a
subroutine, the best way of dealing with this from a performance viewpoint is to use
a closed subroutine within the invoking program (for example, code that is dealt
with by a PERFORM command in COBOL). If it is needed by other programs, it
should be a separate program. A separate program can be called, with a CALL
statement (macro), or it can be kept separate and processed using an XCTL or a
LINK command. Execution overhead is least for a CALL, because no CICS services
are invoked; for example, the working storage of the program being called is not
copied. A called program, however, must be linked into the calling one and so
cannot be shared by other programs that need it unless you use special COBOL, C,
or PL/I facilities. A called subroutine is loaded as part of each program that CALLs it
and hence uses more storage. Thus, subsequent transactions using the program
may or may not have the changes in the working storage made to the called
program. This depends entirely on whether CICS has loaded a new copy of the
program into storage.

© Copyright IBM Corp. 1989, 2005 165

Overhead (but also flexibility) is highest with the XCTL and LINK commands. Both
processor and storage requirements are much greater for a LINK command than for
an XCTL command. Therefore, if the invoking program does not need to have
control returned to it after the invoked program is processed, it should use an XCTL
command.

The load module resulting from any application program can occupy up to two
gigabytes of main storage. Clearly, there is an extra cost associated with loading
and initializing very large load modules, and CICS dynamic storage limits (EDSA)
would need to be set correspondingly high. You should, if possible, avoid the use of
large load modules. However large applications written in an object-oriented
language, such as C++, can easily exceed 16M in size. Experience with C++
classes bound into a single DLL is that performance of the classes is degraded if
the single DLL is reorganized into two or more DLLs. This is due to the processing
required to resolve function references between multiple DLLs.

You may get an abend code of APCG if your program occupies all the available
storage in the dynamic storage area (DSA).

Virtual storage
A truly conversational CICS task is one that converses with the terminal user for
several or many interactions, by issuing a terminal read request after each write (for
example, using either a SEND command followed by a RECEIVE command, or a
CONVERSE command). This means that the task spends most of its extended life
waiting for the next input from the terminal user.

Any CICS task requires some virtual storage throughout its life and, in a
conversational task, some of this virtual storage is carried over the periods when
the task is waiting for terminal I/O. The storage areas involved include the TCA and
associated task control blocks (including EIS or EIB) and the storage required for all
programs that are in use when any terminal read request is issued. Also included
are the work areas (such as copies of COBOL working storage) associated with this
task’s use of those programs.

With careful design, you can sometimes arrange for only one very small program to
be retained during the period of the conversation. The storage needed could be
shared by other users. You must multiply the rest of the virtual storage requirement
by the number of concurrent conversational sessions using that code.

By contrast, a pseudoconversational sequence of tasks requires almost all of its

virtual storage only for the period actually spent processing message pairs.
Typically, this takes a period of 1-3 seconds in each minute (the rest being time
waiting for operator input). The overall requirement for multiple concurrent users is
thus perhaps five percent of that needed for conversational tasks. However, you
should allow for data areas that are passed from each task to the next. This may be
a COMMAREA of a few bytes or a large area of temporary storage. If it is the latter,
you are normally recommended to use temporary storage on disk rather than in
main storage, but that means adding extra temporary storage I/O overhead in a
pseudoconversational setup, which you do not need with conversational processing.

The extra virtual storage you need for conversational applications usually means
that you need a correspondingly greater amount of real storage. The paging you
need to control storage involves additional overhead and virtual storage. The

166 CICS TS for z/OS: CICS Application Programming Guide

adverse effects of paging increase as transaction rates go up, and so you should
minimize its use as much as possible. See Reducing paging effects for information
about doing so.

Reducing paging effects

Reducing paging effects is a technique used by CICS in a virtual-storage
environment. The key objective of programming in this environment is the reduction
of page faults. A page fault occurs when a program refers to instructions or data
that do not reside in real storage, in which case the page in virtual storage that
contains the instructions or data referred to must be paged into real storage. The
more paging required, the lower the overall system performance.

Although an application program may be able to communicate directly with the

operating system, the results of such action are unpredictable and can degrade
performance.

An understanding of the following terms is necessary for writing application

programs to be run in a virtual-storage environment:
Locality of reference
The consistent reference, during the execution of the application program,
to instructions and data within a relatively small number of pages
(compared to the total number of pages in a program) for relatively long
periods.
Working set
The number and combination of pages of a program needed during a given
period.
Reference set
Direct reference to the required pages, without intermediate storage
references that retrieve useless data.

Locality of reference
Keep the instructions processed and data used in a program within a relatively
small number of pages (4096-byte segments). This quality in a program is known
as “locality of reference”. You can do this by:
v Making the execution of the program as linear as possible.
v Keeping any subroutines you use in the normal execution sequence as close as
possible to the code that invokes them.
v Placing code inline, even if you have to repeat it, if you have a short subroutine
that is called from only a small number of places.
v Separating error-handling and other infrequently processed code from the main
flow of the program.
v Separating data used by such code from data used in normal execution.
v Defining data items (especially arrays and other large structures) in the order in
which they are referred to.
v Defining the elements within a data structure in the approximate order in which
they are referred to. For example, in PL/I, all the elements of one row are stored,
then the next row, and so on. You should define an array so that you can
process it by row rather than by column.
v Initializing data as close as possible to where it is first used.
v Avoiding COBOL variable MOVE operations because these expand into
subroutine calls.

Chapter 12. Design for performance 167

v Issuing as few GETMAIN commands as possible. It is generally better for the
program to add up its requirements and do one GETMAIN command than to do
several smaller ones, unless the durations of these requirements vary greatly.
v Avoiding use of the INITIMG option on a GETMAIN command, if possible. It
causes an immediate page reference to the storage that is obtained, which might
otherwise not occur until much later in the program, when there are other
references to the same area.

Note: Some of the suggestions above may conflict with your installation’s
programming standards if these are aimed at the readability and
maintainability of the code, rather than speed of execution in a
virtual-storage environment. Some structured programming methods, in
particular modular programming techniques, make extensive use of the
PERFORM command in COBOL (and the equivalent programming
techniques in C, PL/I, and assembler language) to make the structure of the
program clear. This may also result in more exceptions to sequential
processing than are found in a nonstructured program. Nevertheless, the
much greater productivity associated with structured code may be worth the
possible loss of locality of reference.

Working set
The working set is the number and combination of pages of a program needed
during a given period. To minimize the size of the working set, the amount of
storage that a program refers to in a given period should be as small as possible.
You can do this by:
v Writing modular programs and structuring the modules according to frequency
and anticipated time of reference. Do not modularize merely for the sake of size;
consider duplicate code inline as opposed to subroutines or separate modules.
v Using separate subprograms whenever the flow of the program suggests that
execution is not be sequential.
v Not tying up main storage awaiting a reply from a terminal user.
v Using command-level file control locate-mode input/output rather than
move-mode.
v In COBOL programs, specifying constants as literals in the PROCEDURE
DIVISION, rather than as data variables in the WORKING STORAGE section.
v In C, C++, and PL/I programs, using static storage for constant data.
v Avoiding the use of LINK commands where possible, because they generate
requests for main storage.

Reference set
Try to keep the overall number of pages that a program uses during normal
operation as small as possible. These pages are termed the reference set, and
they give an indication of the real storage requirement of the program. You can
reduce the reference set by:
v Specifying constants in COBOL programs as literals in the PROCEDURE
DIVISION, rather than as data variables in the WORKING STORAGE SECTION.
The reason for this is that there is a separate copy of working storage for every
task executing the program, whereas literals are considered part of the program
itself, of which only one copy is used in CICS.
v Using static storage in C, C++, and PL/I for data that is genuinely constant, for
the same reason as in the previous point.
v Reusing data areas in the program as much as possible. You can do this with the
REDEFINES clause in COBOL, the union clause in C and C++, based storage in

168 CICS TS for z/OS: CICS Application Programming Guide

PL/I, and ORG or equivalents in assembler language. In particular, if you have a
map set that uses only one map at a time, code the DFHMSD map set definition
without specifying either the STORAGE=AUTO or the BASE operand. This allows
the maps in the map set to redefine one another.

Refer to data directly by:

v Avoiding long searches for data in tables
v Using data structures that can be addressed directly, such as arrays, rather than
structures that must be searched, such as chains
v Avoiding methods that simulate indirect addressing

No attempt should be made to use overlays (paging techniques) in an application

program. System paging is provided automatically and has superior performance.
The design of an application program for a virtual-storage environment is similar to
that for a real environment. The system should have all modules resident so that
code on pages not referred to need not be paged in.

If the program is dynamic, the entire program must be loaded across adjacent
pages before execution begins. Dynamic programs can be purged from storage if
they are not being used and an unsatisfied storage request exists. Allowing
sufficient dynamic area to prevent purging is more expensive than making them
resident, because a dynamic program does not share unused space on a page with
another program.

Exclusive control of resources

The very fundamental and powerful recovery facilities that CICS provides have
performance implications. CICS serializes updates to recoverable resources so that
if a transaction fails, its changes to those resources can be backed out
independently of those made by any other transaction. Consequently, a transaction
updating a recoverable resource gets control of that resource until it terminates or
indicates that it wants to commit those changes with a SYNCPOINT command.
Other transactions requiring the same resource must wait until the first transaction
finishes with it.

The primary resources that produce these locking delays are data sets, DL/I
databases, temporary storage, and transient data queues. The unit where protection
is based is the individual record (key) for data sets, the program specification block
(PSB) for DL/I databases, and the queue name for temporary storage. For transient
data, the “read” end of the queue is considered a separate resource from the “write”
end (that is, one transaction can read from a queue while another is writing to it).

To reduce transaction delays from contention for resource ownership, the length of
time between the claiming of the resource and its release (the end of the UOW)
should be minimized. In particular, conversational transactions should not own a
critical resource across a terminal read.

Note: Even for nonrecoverable data sets, VSAM prevents two transactions from
reading the same record for update at the same time. This enqueue ends as
soon as the update is complete, however, rather than at the end of the
UOW. Even this protection for a BDAM data set, can be relinquished by
defining them with “no exclusive control” (SERVREQ=NOEXCTL) in the file
control table.

Chapter 12. Design for performance 169

This protection scheme can also produce deadlocks as well as delays, unless
specific conventions are observed. If two transactions update more than one
recoverable resource, they should always update the resources in the same order.
If they each update two data sets, for example, data set “A” should be updated
before data set “B” in all transactions. Similarly, if transactions update several
records in a single data set, they should always do so in some predictable order
(low key to high, or conversely). You might also consider including the TOKEN
keyword with each READ UPDATE command. See “The TOKEN option” on page
302 for information about the TOKEN keyword. Transient data, temporary storage,
and user journals must be included among such resources. The CICS Recovery
and Restart Guide contains further information on the extent of resource protection.

It may be appropriate here to note the difference between CICS data sets on a
VSAM control interval, and VSAM internal locks on the data set. Because CICS has
no information about VSAM enqueue, a SHARE OPTION 4 control interval that is
updated simultaneously from batch and CICS can result in, at best, reduced
performance and, at worst, an undetectable deadlock situation between batch and
CICS. You should avoid such simultaneous updates between batch and CICS. In
any case, if a data set is updated by both batch and CICS, CICS is unable to
ensure data integrity.

Operational control
The following operational techniques can be used to influence the performance and
efficiency of the CICS system:
MXT
The CICS system initialization parameter MXT specifies the maximum number
of user tasks that can exist in a CICS system at the same time. MXT is
invaluable for avoiding short-on-storage (SOS) conditions and for controlling
contention for resources in CICS systems. It works by delaying the creation of
user tasks to process input messages, if there are already too many activities in
the CICS system. In particular, the virtual storage occupied by a message
awaiting processing is usually much less than that needed for the task to
process it, so you save virtual storage by delaying the processing of the
message until you can do so quickly.
Transaction classes are useful in limiting the number of tasks of a particular
user-defined type, or class, if these are heavy resource users.
Runaway tasks
CICS only resets a task’s runaway time (ICVR) when a task is suspended. An
EXEC CICS command cannot be guaranteed to cause a task to suspend during
processing because of the unique nature of each CICS implementation. The
runaway time may be exceeded causing a task to abend AICA. This abend can
be prevented by coding an EXEC CICS SUSPEND command in the application
This causes the dispatcher to suspend the task that issued the request and
allow any task of higher priority to run. If there is no task ready to run, the
program that issued the suspend is resumed. For further information about
abend AICA, see the CICS Problem Determination Guide.
Auxiliary trace
Use auxiliary trace to review your application programs. For example, it can
show up any obviously unnecessary code, such as a data set browse from the
beginning of a data set instead of after a SETL, too many or too large

170 CICS TS for z/OS: CICS Application Programming Guide

GETMAIN commands, failure to release storage when it is no longer needed,
unintentional logic loops, and failure to unlock records held for exclusive control
that are no longer needed.

Operating system waits

You should avoid using facilities that cause operating system waits. All CICS activity
stops when one of these waits occurs, and all transactions suffer response delays.
The chief sources of such waits are:
v Extrapartition transient data sets. (See “Efficient sequential data set access” on
page 175.)
v Those COBOL, C, C++, and PL/I language facilities that you should not use in
CICS programs and for which CICS generally provides alternative facilities. For
guidance information about the language restrictions, see Chapter 4,
“Programming in COBOL,” on page 21, Chapter 5, “Programming in C and C++,”
on page 43, and Chapter 6, “Programming in PL/I,” on page 53.
v SVCs and assembler language macros that invoke operating system services,
such as write-to-operator (WTO).

The NOSUSPEND option

The default action for the ENQBUSY, NOJBUFSP, NOSPACE, NOSTG, QBUSY,
SESSBUSY, and SYSBUSY conditions is to suspend the execution of the
application until the required resource (for example, storage) becomes available,
and then resume processing the command. The commands that can give rise to
these conditions are: ALLOCATE, ENQ, GETMAIN, WRITE JOURNALNAME,
WRITE JOURNALNUM, READQ TD, and WRITEQ TS.

On these commands, you can use the NOSUSPEND option (also known as the
NOQUEUE option in the case of the ALLOCATE command) to inhibit this waiting
and cause an immediate return to the instruction in the application program
following the command.

CICS maintains a table of conditions referred to by the HANDLE CONDITION and

IGNORE CONDITION commands in a COBOL application program1. Execution of
these commands either updates the existing entry, or causes a new entry to be
made if the condition has not yet been the subject of such a command. Each entry
indicates one of the three states described below:
v A label is currently specified, as follows:
HANDLE CONDITION condition(label)
v The condition is to be ignored, as follows:
IGNORE CONDITION
v No label is currently specified, as follows:
HANDLE CONDITION

1. HANDLE CONDITION and IGNORE CONDITION commands are not supported for C and C++ programs.

Chapter 12. Design for performance 171

When the condition occurs, the following tests are made:
1. If the command has the NOHANDLE or RESP option, control returns to the next
instruction in the application program. Otherwise, the condition table is scanned
to see what to do.
2. If an entry for the condition exists, this determines the action.
3. If no entry exists and the default action for this condition is to suspend
execution:
v If the command has the NOSUSPEND or NOQUEUE option, control returns
to the next instruction.
v If the command does not have one of these options, the task is suspended.
4. If no entry exists and the default action for this condition is to abend, a second
search is made looking for the ERROR condition:
v If found, this entry determines the action.
v If ERROR is searched for and not found, the task is abended.

Efficient data operations

CICS supports:
v DL/I database operations
v VSAM and BDAM data set operations
v Browsing
v Logging
v Sequential data set access

Efficient database operations

The following recommendations apply to using DL/I with CICS:
v Use command codes with CALL level and keywords with command level to
reduce the number of requests whenever appropriate. See the CICS IMS
Database Control Guide for more information. For example, a DL/I path call is
more efficient than a number of individual DL/I calls. With individual DL/I calls,
the GN call gives the best performance. Although several DL/I calls may get their
information from the DL/I or VSAM buffers, some of the instructions have to be
processed within a DL/I call. You should, therefore, consider the number of DL/I
calls needed for the processing of a transaction.
v It is more efficient to use qualified segment-search areas (SSAs) than to check
on “segment found” in the application program.
v Scheduling calls should be issued at the latest possible time, so as to minimize
the time that the transaction has exclusive control of the PSB. (This control is
released at the end of the UOW, which occurs at the next TERM call, explicit
SYNCPOINT command, or the syncpoint implicit in task termination.)
v Be aware of the effects of explicit syncpointing on performance and recovery.

Efficient data set operations

The efficiency of database and data set operations is an important factor in the
performance of any CICS system. In VSAM, the main impact on efficiency, and thus
on response time, comes from contention for serial-use resources (record keys,
control intervals, and strings), and for storage use and processor overhead. As is
usual in these situations, any improvements you make in one area may be at the
expense of other areas.

172 CICS TS for z/OS: CICS Application Programming Guide

VSAM data sets
To minimize contention delays using VSAM data sets:
v Minimize the time that VSAM resources are reserved for exclusive use. The
exclusive use enqueue is the way CICS and VSAM prevent concurrent updates.
If you use VSAM record-level sharing, described in “Accessing files in RLS
mode” on page 285, VSAM locks a record that has been requested for update,
so that no other transaction can attempt to update the record at the same time. If
the file is recoverable, VSAM releases the lock at the next syncpoint. If the file is
not recoverable, VSAM releases the lock when the request is complete. The
recoverability of a file is defined in the integrated catalog facility (ICF) catalog.
If you do not use VSAM record-level sharing, CICS serializes update requests by
base cluster record key. The complete VSAM control interval (CI) containing the
requested record is held for exclusive use while an individual command (for
example, a READ command with the UPDATE option) is being executed on the
record. Once each command is complete, the control interval is released, and
only the requested record remains locked. For nonrecoverable data sets, both
the VSAM exclusive use and the CICS exclusive use of the record end when the
update request is complete in VSAM terms; for example, when the REWRITE
command has completed. For recoverable data sets, however, the CICS
exclusive use does not end until the task ends or issues a SYNCPOINT
command. Recoverability is specified in the data set resource definition. See the
CICS Resource Definition Guide for more information about the FILE resource
definitions.
v Hold position in a VSAM data set for as short a time as possible. Table 9 shows
which commands hold position and when the hold is released.
Table 9. Commands that hold position and when hold is released
Command Released by VSAM at
READ.. UPDATE REWRITE/DELETE/UNLOCK
WRITE.. MASSINSERT UNLOCK
STARTBR ENDBR

Each request in progress against a VSAM data set requires at least one string.
Requests that hold position tie up a string until a command is issued to release
the hold position. Requests that do not hold position release the string as soon
as that request is complete.

Chapter 12. Design for performance 173

To minimize processor overhead when using VSAM data sets:
v Use the MASSINSERT option if you are adding many records in sequence. This
improves performance by minimizing processor overheads and therefore
improves the response times. For ESDSs and KSDSs, adding records with
MASSINSERT causes CICS to use sequential VSAM processing. This changes
the way VSAM places records within control intervals when a split is required,
resulting in fewer splits and less unused space within the affected CIs.
v Use skip sequential processing if you are reading many records in sequence
whose keys are relatively close together but not necessarily adjacent. (Skip
sequential processing begins with a start browse (STARTBR command).) Each
record is retrieved with an READNEXT command, but the key feedback area
pointed to by RIDFLD is supplied with the key of the next requested record
before the READNEXT command is issued.
v Use the GENERIC option on the DELETE command when deleting a group of
records whose keys start with a common character string. CICS internally
optimizes a generic DELETE.

BDAM data sets

BDAM data sets are less efficient than VSAM because CICS has to do some
single-thread processing and issue some operating system waits to handle BDAM
data set requests. Therefore, if possible, you should use a relative record VSAM
data set or an entry-sequenced data set addressed by relative byte address (RBA)
in place of a BDAM data set.

If you are using BDAM data sets in update mode, you should be aware that
performance is affected dramatically by the means of data set integrity you choose.

If you specify exclusive control in file control table SERVREQ operands for a
BDAM data set, CICS requests the operating system to prevent concurrent updates.
However, this involves significant overhead.

Efficient browsing (in non-RLS mode)

A data set browse is often the source of the output in transactions that produce a
large number of output screens, which can monopolize system resources. A long
browse can put a severe load on the system, locking out other transactions and
increasing overall response time, in addition to the overhead needed for BMS, task
control, and terminals. This is because CICS control philosophy is based on the
assumption that the terminal operator initiates a transaction that accesses a few
data records, processes the information, and returns the results to the operator.
This process involves numerous waits that enable CICS to do multitasking.
However, CICS is not an interrupt-driven multitasking system, so tasks that involve
small amounts of I/O relative to processing can monopolize the system regardless
of priority. A browse of a data set with many records in a control interval is just such
a transaction.

You can prevent this by issuing DELAY or SUSPEND commands periodically, so

that other tasks can get control. If the browse produces paged output, you should
consider breaking the transaction up in one of the ways suggested in “Page-building
and routing operations” on page 179.

174 CICS TS for z/OS: CICS Application Programming Guide

Efficient logging
CICS provides options to log some or all types of activity against a data set.
Logging updates enables you to reconstruct data sets from backup copies, if
necessary. You may also want to log reads for security reasons. Again, you have to
balance the need for data integrity and security against the performance effects of
logging. These are the actual operations needed to do the logging and the possible
delays caused because of the exclusive control that logging implies.

Efficient sequential data set access

CICS provides a number of different sequential processing options. Temporary
storage and intrapartition transient data queues (already discussed in “Temporary
storage” on page 158 and in “Intrapartition transient data” on page 159) are the
most efficient to use, but they must be created and processed entirely within CICS.

Extrapartition transient data is the CICS way of handling standard sequential

(QSAM/BSAM) data sets. It is the least efficient of the three forms of sequential
support listed, because CICS has to issue operating system waits to process the
data sets, as it does when handling BDAM. Moreover, extrapartition transient data
sets are not recoverable. VSAM ESDSs, on the other hand, are recoverable within
limitations, and processing is more efficient. The recovery limitation is that records
added to an ESDS during an uncompleted UOW cannot be removed physically
during the backout process, because of VSAM restrictions. They can, however, be
flagged as deleted by a user exit routine.

CICS journals provide another good alternative to extrapartition transient data,

although only for output data sets. Journals are managed by the MVS system
logger, but flexible processing options permit very efficient processing. Each journal
command specifies operation characteristics, for example, synchronous or
asynchronous, whereas extrapartition operations are governed entirely by the
parameters in the transient data queue definition.

Transactions should journal asynchronously, if possible, to minimize task waits in

connection with journaling. However, if integrity considerations require that the
journal records be physically written before end of task, you must use a
synchronous write. If there are several journal writes, the transaction should use
asynchronous writes for all but the last logical record, so that the logical records for
the task are written with a minimum number of physical I/Os and only one wait.

You can use journals for input (in batch) as well as output (online) while CICS is
running. The supplied batch utility DFHJUP can be used for access to journal data,
for example, by printing or copying. Note that reading a journal in batch involves the
following restrictions:
v Access to MVS system logger log stream data is provided through a subsystem
interface, LOGR.
v Reading records from a journal is possible offline by means of a batch job only.

Chapter 12. Design for performance 175

Efficient terminal operations
There are some design factors, related to communicating with terminals, that may
affect performance.

Length of the data stream sent to the terminal

Good screen design and effective use of 3270 hardware features can significantly
affect the number of bytes transmitted on a teleprocessing link. It is particularly
important to keep the number of bytes as small as possible because, in most
cases, this is the slowest part of the path a transaction takes. The efficiency of the
data stream therefore affects both response time and line usage.

Basic mapping support considerations

When building a formatted data stream with basic mapping support (BMS), you
should bear in mind, the factors described in the following sections.

Avoid turning on modified data tags (MDTs) unnecessarily

The MDT is the bit in the attribute byte that determines whether a field should be
transmitted on a READ MODIFIED command (the command used by CICS for all
but copy operations).

The MDT for a field is normally turned on by the 3270 hardware when the user
enters data into a field. However, you can also turn the tag on when you send a
map to the screen, either by specifying FSET in the map or by sending an override
attribute byte that has the tag on. You should never set the tag on in this way for a
field that is constant in the map, or for a field that has no label (and is not sent to
the program that receives the map).

Also, you do not normally need to specify FSET for an ordinary input field. This is
because, as already mentioned, the MDT is turned on automatically in any field in
which the user enters data. This is then included in the next RECEIVE command.
These tags remain on, no matter how many times the screen is sent, until explicitly
turned off by the program (by the FRSET, ERASEAUP, or ERASE option, or by an
override attribute with the tag off).

You can store information, between inputs, that the user did not enter on the
screen. This is an intended reason for turning the MDT on by a program. However,
this storage technique is appropriate only to small amounts of data, and is more
suitable for local than for remote terminals, because of the transmission overhead
involved. For example, this technique is particularly useful for storing default values
for input fields. In some applications, the user must complete a screen in which
some fields already contain default values. A user who does not want to change a
default just skips that field. The program processing the input has to be informed
what these defaults are. If they are always the same, they can be supplied as
constants in the program. If they are variable, however, and depend on earlier
inputs, you can simply save them on the screen by turning the MDT on with FSET
in the map that writes the screen. The program reading the screen then receives
the default value from a user who does not change the field and the new value from
a user who does.

Note: The saved values are not returned to the screen if the CLEAR, PA1, PA2, or
PA3 key is pressed.

176 CICS TS for z/OS: CICS Application Programming Guide

Use FRSET to reduce inbound traffic
If you have a screen with many input fields, which you may have to read several
times, you can reduce the length of the input data stream by specifying FRSET
when you write back to the screen in preparation for the next read. FRSET turns off
the MDTs, so that fields entered before that write are not present unless the user
reenters them the next time. If you are dealing with a relatively full screen and a
process where there may be a number of error cycles (or repeat transmissions for
some other reason), this can be a substantial saving. However, because only
changed fields are sent on subsequent reads, the program must save input from
each cycle and merge the new data with the old. This is not necessary if you are
not using FRSET, because the MDTs remain on, and all fields are sent regardless
of when they were entered.

Do not send blank fields to the screen

Sending fields to the screen that consist entirely of blanks or that are filled out on
the right by trailing blanks usually wastes line capacity. The only case where BMS
requires you to do this is when you need to erase a field on the screen that
currently contains data, or to replace it with data shorter than that currently on the
screen, without changing the rest of the screen.

This is because, when BMS builds the data stream representing your map, it
includes blanks (X'40') but omits nulls (X'00'). This makes the output data stream
shorter. BMS omits any field whose first data character is null, regardless of
subsequent characters in the field.

BMS requires you to initialize to nulls any area to be used to build a map. This is
done by moving nulls (X'00') to the mapnameO field in the symbolic map structure.
See “Initializing the output map” on page 474 for more information. BMS uses nulls
in attribute positions and in the first position of data to indicate that no change is to
be made to the value in the map. If you are reusing a map area in a program or in
a TIOA, you should take special care to clear it in this way.

Address CICS areas correctly

There are several ways to check that CICS areas are addressed correctly. Ensure
that:
v Each COBOL program with a LINKAGE SECTION structure that exceeds 4KB
has the required definition and the setting of more than one contiguous BLL cell.
v Every BLL pointer points to an area that is a 01-level item.
v Call level DL/I is only used with PSBs that are correctly addressed.

Use the MAPONLY option when possible

The MAPONLY option sends only the constant data in a map, and does not merge
any variable data from the program. The resulting data stream is not always shorter,
but the operation has a shorter path length in BMS. When you send a skeleton
screen to be used for data entry, you can often use MAPONLY.

Send only changed fields to an existing screen

Sending only changed fields is important when, for example, a message is added to
the screen, or one or two fields on an input screen are highlighted to show errors.
In these situations, you should use the DATAONLY option to send a map that
consists of nulls except for the changed fields. For fields where the only the
attribute byte has changed, you need send only that byte, and send the remaining
fields as nulls. BMS uses this input to build a data stream consisting of only the
fields in question, and all other fields on the screen remain unchanged.

Chapter 12. Design for performance 177

It may be tempting to ignore this advice and send an unnecessarily long data
stream. For example, when a program that is checking an input screen for errors
finds one, there are two options.
v It can simply add the error information to the input map (highlighted attributes,
error messages, and so on) and resend it.
v It can build an entirely new screen, consisting of just the error and message
fields.

The former is slightly easier to code (you do not need to have two map areas or
move any fields), but it may result in very much longer transmissions because the
output data stream contains the correct input fields as well as the error and
message fields. In fact, it may even be longer than the original input stream
because, if there were empty or short fields in the input, BMS may have replaced
the missing characters with blanks or zeros.

With the 3270 hardware, if the input stream for a terminal exceeds 256 bytes, the
terminal control unit automatically breaks it up into separate transmissions of 256
bytes maximum. This means that a long input stream may require several physical
I/O operations. Although this is transparent to the application program, it does
cause additional line and processor overhead. The output stream is generally sent
in a single transmission.

Design data entry operations to reduce line traffic

Often, users are required to complete the same screen several times. Only the data
changes on each cycle; the titles, field labels, instructions, and so on remain
unchanged. In this situation, when an entry is accepted and processed, you can
respond with a SEND CONTROL ERASEAUP command (or a map that contains
only a short confirmation message and specifies the ERASEAUP option). This
causes all the unprotected fields on the screen (that is, all the input data from the
last entry) to be erased and to have their MDTs reset. The labels and other text,
which are in protected fields, are unchanged, the screen is ready for the next
data-entry cycle, and only the necessary data has been sent.

Compress data sent to the screen

When you send unformatted data to the screen, or create a formatted screen
outside BMS, you can compress the data further by inserting set buffer address
(SBA) and repeat-to-address (RA) orders into the data stream. SBA allows you to
position data on the screen, and RA causes the character following it to be
generated from the current point in the buffer until a specified ending address. SBA
is useful whenever there are substantial unused areas on the screen that are
followed by data. RA is useful when there are long sequences of the same
character, such as blanks or dashes, on the screen. However, you should note that
the speed with which RA processes is not uniform across all models of 3270 control
units. You should check how it applies to your configuration before use.

CICS provides an exit that is driven just before output is sent to a terminal (XTC
OUT). You may want to add SBA and RA substitutions to this exit to compress the
data stream using a general subroutine. This has the dual benefit of removing
compression logic from your application program and of applying to all output data
streams, whether they are produced by BMS or not.

Use nulls instead of blanks

You should note that, outside BMS, nulls have no special significance in an output
data stream. If you need a blank area on a screen, you can send either blanks or

178 CICS TS for z/OS: CICS Application Programming Guide

nulls to it; they take up the same space in the output stream. However, if the blank
field is likely to be changed by the user and subsequently read, use nulls, because
they are not transmitted back.

Use methods that avoid the need for nulls or blanks

For any large area of a screen that needs to be blank, you should consider
methods other than transmitting blanks or nulls; for example, when using BMS,
putting SBA and RA orders directly into the data stream, or using the ERASE and
ERASEAUP options.

Page-building and routing operations

BMS page-building facilities provide a powerful and flexible tool for building and
displaying long messages, sending messages to multiple destinations, and
formatting a single message for several devices with different physical
characteristics. However, as for any high-function tool, it requires a substantial
overhead, as mentioned in “Efficient browsing (in non-RLS mode)” on page 174.
You may need the page-building option (ACCUM) when:
v Sending messages whose length exceeds the capacity of the output device
(multipage output)
v Using destinations other than the input terminal
v Sending pages built from multiple maps
v Using the BMS page-copy facility

Sending multipage output

Transactions that produce very large output messages, consisting of many
screen-size pages, tend to tax system resources. First, all the pages have to be
created, which involves processor activity, execution of the CSPG transaction, and
data set I/O activity. The pages must then be saved in temporary storage. If the
terminal user looks at every page in a message, a large number of transactions are
run to process the paging requests, each of which needs line and processor
overhead. Obviously some overhead is caused by the size and complexity of the
transaction, and it may be unavoidable. Indeed, if several users are scrolling rapidly
through paged output at the same time, the transactions needed can monopolize a
system.

If users really need to see all the pages, and need to scroll backward and forward
frequently, it may be more efficient to produce all the pages at the same time and
present them using “traditional” CICS paging services. However, if users need only
a few of the pages, or can easily specify how far back or forward in the message
they would like to scroll, there are two choices:
1. First, construct a pseudoconversational transaction to produce just one screen
of output. The first time this transaction is run, it produces the first page of the
many-page output. The output screen contains space for users to indicate the
page they want next. The transaction always sets the next transaction identifier
to point to itself, so that it can display the requested page when it is next run.
You will probably want to give users some of the options that CICS provides
(such as one page forward, one page back, and skip to a selected page) and
some relevant to the application, such as a data set key at which to begin the
next page of output.
2. The alternative is to page-build a multipage output message with the ACCUM
option, but to limit the number of pages in the message (say to five). Users
page through the subset pages with the usual CICS page commands. On the
last screen of the output, you add an indication that there is more output and a
place for them to indicate whether they want to see the next segment. As in the

Chapter 12. Design for performance 179

first example, the next transaction identifier is set to the original transaction so
that, if CICS does not receive a paging command, it invokes that transaction.

Sending messages to destinations other than the input terminal

If you need to send a message to a terminal other than the input terminal
associated with a task, BMS routing may be the most efficient way of doing so. This
is especially so if the message must be sent to multiple destinations or if it involves
multiple pages. Routing is the recommended method if the message recipients
need CICS paging commands to access it.

However, if neither of the above conditions apply, you have a choice of two other
methods of delivering output to a terminal not associated with the transaction.
1. You can use a START command, with the TERMID option, to specify the
terminal to which you want to write and the FROM option to specify the data
you want to send. Your own transaction is the started transaction. It issues an
RETRIEVE command for the message and then sends it to its own terminal.
See the CICS Application Programming Reference manual for programming
information about the START command.
2. Similarly, you can put messages destined for a particular terminal on to an
intrapartition transient data queue. The definition for the transient data queue
must specify:
v The destination as a TERMINAL
v The terminal identifier
v A trigger level
v A transaction name
Your own transaction reads the transient data queue and sends the message to
its terminal. It repeats this sequence until the queue is empty, and then
terminates. The trigger level you specified means that it is invoked every time
the specified number of messages have been placed on the queue. The
CICS/ESA Sample Applications Guide describes the DFHœTDWT sample
program that performs this function.

Note: Because of the overhead associated with routing messages (by whatever
means), you should use facilities such as ROUTE=ALL with caution.

Sending pages built from multiple maps

Although you can easily build a screen gradually using different maps, you can
sometimes avoid considerable overhead by not using page-building operations,
especially where there is only one screen of output and no other need for paging.
An example of this is an application whose output consists of a header map,
followed by a variable number of detail segments, sent with a second map, and
finally a trailer map following the detail. Suppose the average output screen for
such an application contains eight (2-line) detail segments, plus header and trailer,
and all this fits on a single screen. Writing this screen with page-building requires 11
BMS calls (header, details, trailer, and page-out) whereas, if the program builds the
output screen internally, it only needs one call.

Using the BMS page-copy facility

Because the individual pages that make up an accumulated BMS message are
saved in temporary storage, BMS enables the terminal user to copy individual
pages to other terminals. However, if the ability to copy is the only reason for using
page-building, you should consider using either the 3274 control unit copy facilities
or the CICS copy key facility instead.

180 CICS TS for z/OS: CICS Application Programming Guide

The 3274 copy facilities require no participation from CICS and no transmission,
and are by far the most efficient method. The CICS copy key facility does have an
overhead (see “Requests for printed output”), although of a different type from the
BMS copy facility. It also has destination restrictions that do not apply to BMS
copying.

Requests for printed output

A CICS print request asks CICS to copy what is on the requesting screen to the
first available printer on the same control unit. The overhead involved depends on
whether a printer is available, and whether the requesting terminal is remote or
local to CICS.

If no printer is available, and the request is from a remote or a local device:

v CICS reads the buffer to the display terminal. This involves transmitting every
position on the screen, including nulls.
For requests from a local device, the READ BUFFER command takes place at
channel speeds, so that the large input message size does not increase
response time too much, and does not monopolize the line.
v An error task is generated so that the terminal error program can dispose of the
message. If a printer is available and the request is from a local device, this step
is not needed.
v The 3270 print task (CSPP) is attached to write the entire buffer to the printer
when it is available.

If a printer is available, and the request is from a remote device, CICS sends a very
short data stream to the control unit asking for a copy of the requesting device
buffer to be sent to the output device buffer.

Additional terminal control considerations

The following sections describe additional points to consider when using the CICS
terminal control services.

Use only one physical SEND command per screen

We mentioned earlier that it is usually more efficient to create a screen with a single
call to BMS, than to build the screen with a series of SEND MAP ACCUM
commands. It is important to send the screen in a single physical output to the
terminal. It is very inefficient to build a screen in parts and send each part with a
separate command, because of the additional processor overhead of using several
commands and the additional line and access method overhead.

Use the CONVERSE command

Use the CONVERSE command rather than the SEND and RECEIVE commands (or
a SEND, WAIT, RECEIVE command sequence if your program is conversational).
They are functionally equivalent, but the CONVERSE command crosses the CICS
services interface only once, which saves processor time.

Limit the use of message integrity options

Like specifying the WAIT option on the final SEND command of a transaction, the
MSGINTEG option of CEDA requires CICS to keep the transaction running until the
last message has been delivered successfully.

The PROTECT option of the PROFILE definition implies message integrity and
causes the system to log all input and output messages, which adds to I/O and
processor overhead.

Chapter 12. Design for performance 181

Avoid using the DEFRESP option on SEND commands
Avoid using the DEFRESP option on SEND commands, unless the transaction must
verify successful delivery of the output message. It delays termination of the
transaction in the same way as MSGINTEG.

Avoid using unnecessary transactions

Avoid situations that may cause users to enter an incorrect transaction or to use the
CLEAR key unnecessarily, thus adding to terminal input, task control processing,
terminal output, and overhead. Good screen design and standardized PF and PA
key assignments should minimize this.

Send unformatted data without maps

If your output to a terminal is entirely or even mostly unformatted, you can send it
using terminal control commands rather than BMS commands (that is, using a BMS
SEND command without the MAP or TEXT options).

182 CICS TS for z/OS: CICS Application Programming Guide

Chapter 13. Sharing data across transactions
CICS facilities for sharing data across transactions include:
v The Common Work Area (CWA)
v The TCTTE user area (TCTUA)
v The COMMAREA
v The display screen
| v Channels and containers

Data stored in the TCTUA and the CWA is available to any transaction in the
system. Subject to resource security and storage protection restrictions, any
transaction may write to them and any transaction may read them.

The use of some of these facilities may cause inter-transaction affinities. See
Chapter 15, “Affinity,” on page 219 for more information about transaction affinities.

This chapter describes:

v “Using the common work area (CWA)”
v “Using the TCTTE user area (TCTUA)” on page 186
v “Using the COMMAREA in RETURN commands” on page 187
| v “Using a channel on RETURN commands” on page 187
v “Using the display screen to share data” on page 188

Using the common work area (CWA)

The common work area (CWA) is a single control block that is allocated at system
startup time and exists for the duration of that CICS session. The size is fixed, as
specified in the system initialization parameter, WRKAREA. The CWA has the
following characteristics:
v There is almost no overhead in storing or retrieving data from the CWA.
Command-level programs must issue one ADDRESS command to get the
address of the area but, after that, they can access it directly.
v Data in the CWA is not recovered if a transaction or the system fails.
v It is not subject to resource security.
v CICS does not regulate use of the CWA. All programs in all applications that use
the CWA must follow the same rules for shared use. These are usually set down
by the system programmers, in cooperation with application developers, and
require all programs to use the same “copy” module to describe the layout of the
area.
You must not exceed the length of the CWA, because this causes a storage
violation. Furthermore, you must ensure that the data used in one transaction
does not overlay data used in another. One way to protect CWA data is to use
the storage protection facility that protects the CWA from being written to by
user-key applications. See “Protecting the CWA” on page 184 for more
information.
v The CWA is especially suitable for small amounts of data, such as status
information, that are read or updated frequently by multiple programs in an
application.
v The CWA is not suitable for large-volume or short-lived data because it is always
allocated.

© Copyright IBM Corp. 1989, 2005 183

Protecting the CWA
The CWAKEY system initialization parameter allows you to specify whether the
CWA is to be allocated from CICS-key or user-key storage. See the CICS System
Definition Guide for details about the CWAKEY parameter.

If you want to restrict write access to the CWA, you can specify CWAKEY=CICS.
This means that CICS allocates the CWA from CICS-key storage, restricting
application programs defined with EXECKEY(USER) to read-only access to the
CWA. The only programs allowed to write to a CWA allocated from CICS-key
storage are those you define with EXECKEY(CICS).

Because any program that executes in CICS key can also write to CICS storage,
you should ensure that such programs are thoroughly tested to make sure that they
do not overwrite CICS storage.

If you want to give preference to protecting CICS rather than the CWA, specify
CWAKEY=USER for the CWA, and EXECKEY(USER) for all programs that write to
the CWA. This ensures that if a program exceeds the length of the CWA it does not
overwrite CICS storage. For more information about storage protection, see
Chapter 46, “Storage control,” on page 575.

Figure 37 illustrates a particular use of the CWA where the CWA itself is protected
from user-key application programs by CWAKEY=CICS.

CWA
(defined with
CWAKEY=CICS)

appl1_id Application
Storage Area
ptr_ref1 (for appl1)
(obtained from
appl2_id CICS-key storage)

ptr_ref2
Application
Storage Area
(for appl2)
(obtained from
user-key storage)

The CWA is initialized by an AMODE(31) PLTPI program,

which obtains storage for application-related
tables, and stores the addresses of the GETMAINed
storage in the CWA.

Figure 37. Example of use of CWA in CICS-key storage. This illustrates how the CWA can be
used to reference storage that is obtained in user-key or CICS-key storage for use by
application programs, while the CWA itself is protected by being in CICS-key storage.

In this illustration, the CWA is not used directly to store application data and
constants. The CWA contains pairs of application identifiers and associated
addresses, with the address fields containing the addresses of data areas that hold
the application-related data. For protection, the CWA is defined with
CWAKEY=CICS, therefore the program which in this illustration is a program
defined in the program list table post initialization (PLTPI) list, and that loads the
CWA with addresses and application identifiers must be defined with
EXECKEY(CICS). Any application programs requiring access to the CWA should be

184 CICS TS for z/OS: CICS Application Programming Guide

defined with EXECKEY(USER), thereby ensuring the CWA is protected from
overwriting by application programs. In Figure 37 on page 184, one of the data
areas is obtained from CICS-key storage, while the other is obtained from user-key
storage.

In the sample code shown in Figure 38, the program list table post-initialization
(PLTPI) program is setting up the application data areas, with pointers to the data
stored in the CWA.

This example illustrates how to create global data for use by application programs,
with addresses of the data stored in the CWA—for example, by a PLTPI program.
The first data area is obtained from CICS-key storage, which is the default on a
GETMAIN command issued by a PLTPI program, the second from user-key storage
by specifying the USERDATAKEY option. The CWA itself is in CICS-key storage,
and PLTPROG is defined with EXECKEY(CICS).

ID DIVISION.
PROGRAM-ID. PLTPROG.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 APPLID PIC X(8) VALUE SPACES.
77 SYSID PIC X(4) VALUE SPACES.
01 COMM-DATA.
03 AREA-PTR USAGE IS POINTER.
03 AREA-LENGTH PIC S9(8) COMP.
LINKAGE SECTION.
01 COMMON-WORK-AREA.
03 APPL-1-ID PIC X(4).
03 APPL-1-PTR USAGE IS POINTER.
03 APPL-2-ID PIC X(4).
03 APPL-2-PTR USAGE IS POINTER.
PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.
* Obtain APPLID and SYSID values
EXEC CICS ASSIGN APPLID(APPLID)
SYSID(SYSID)
END-EXEC.
* Set up addressability to the CWA
EXEC CICS ADDRESS
CWA(ADDRESS OF COMMON-WORK-AREA)
END-EXEC.
* Get 12KB of CICS-key storage for the first application (’APP1’)
MOVE 12288 TO AREA-LENGTH.
EXEC CICS GETMAIN SET(AREA-PTR)
FLENGTH(AREA-LENGTH)
SHARED
END-EXEC.
* Initialize CWA fields and link to load program
* for storage area 1.
MOVE ’APP1’ TO APPL-1-ID.
SET APPL-1-PTR TO AREA-PTR.
EXEC CICS LINK PROGRAM(’LOADTAB1’)
COMMAREA(COMM-DATA)
END-EXEC.

Figure 38. Sample code for loading the CWA (Part 1 of 2)

Chapter 13. Sharing data across transactions 185

* Get 2KB of user-key storage for the second application (’APP2’)
MOVE 2048 TO AREA-LENGTH.
EXEC CICS GETMAIN SET(AREA-PTR)
FLENGTH(AREA-LENGTH)
SHARED
USERDATAKEY
END-EXEC.
* Initialize CWA fields and link to load program
* for storage area 2.
MOVE ’APP2’ TO APPL-2-ID.
SET APPL-2-PTR TO AREA-PTR.
EXEC CICS LINK PROGRAM(’LOADTAB2’)
COMMAREA(COMM-DATA)
END-EXEC.
EXEC CICS RETURN
END-EXEC.
MAIN-PROCESSING-EXIT.
GOBACK.

Figure 38. Sample code for loading the CWA (Part 2 of 2)

Using the TCTTE user area (TCTUA)

The TCT user area (TCTUA) is an optional extension to the terminal control table
entry (TCTTE). Each entry in the TCT specifies whether this extension is present
and, if so, how long it is (by means of the USERAREALEN attribute of the
TYPETERM resource definition used for the terminal). See the CICS Resource
Definition Guide for more information about the TYPETERM resource definition.

The system initialization parameters TCTUALOC and TCTUAKEY specify the

location and storage key for all TCTUAs.
v TCTUALOC=BELOW or ANY specifies whether you want 24- or 31-bit
addressability to the TCTUAs, and whether TCTCUAs must be stored below the
16MB line or may be either above or below the line.
v TCTUAKEY=USER or CICS specifies whether you want the TCTUAs allocated
from user-key or CICS-key storage.
TCTUAs have the following characteristics in common with the CWA:
v Minimal processor overhead (only one ADDRESS command needed)
v No recovery
v No resource security
v No regulation of use by CICS
v Fixed length
v Unsuitability for large-volume or short-lived data
Unlike the CWA, however, the TCTUA for a particular terminal is usually shared
only among transactions using that terminal. It is therefore useful for storing small
amounts of data of fairly standard length between a series of transactions in a
pseudoconversational sequence. Another difference is that it is not necessarily
permanently allocated, because the TCTUA only exists while the TCTTE is set up.
For non-autoinstall terminals the TCTUA is allocated from system startup; for
autoinstall terminals the TCTUA is allocated when the TCTTE is generated.

Using the TCTUA in this way does not require special discipline among using
transactions, because data is always read by the transaction following the one that
wrote it. However, if you use TCTUAs to store longer-term data (for example,
terminal or operator information needed by an entire application), they require the

186 CICS TS for z/OS: CICS Application Programming Guide

same care as the CWA to ensure that data used in one transaction does not
overlay data used in another. You should not exceed the length of the allocated
TCTUA, because this produces a storage violation.

Using the COMMAREA in RETURN commands

The COMMAREA option of the RETURN command is designed specifically for
passing data between successive transactions in a pseudoconversational sequence.
It is implemented as a special form of user storage, although the EXEC interface,
rather than the application program, issues the GETMAIN and FREEMAIN requests.

The COMMAREA is allocated from the CICS shared subpool in main storage, and
is addressed by the TCTTE, between tasks of a pseudoconversational application.
The COMMAREA is freed unless it is passed to the next task.

The first program in the next task has automatic addressability to the passed
COMMAREA, as if the program had been invoked by either a LINK command or an
XCTL command (see “COMMAREA in LINK and XCTL commands” on page 157).
You can also use the COMMAREA option of the ADDRESS command to obtain the
address of the COMMAREA.

For a COMMAREA passed between successive transactions in a

pseudoconversational sequence in a distributed environment, VTAM imposes a limit
of 32KB on the size of the total data length. This limit applies to the entire
transmitted package, which includes control data added by VTAM. The amount of
control data increases if the transmission uses intermediate links.

To summarize:
v Processor overhead is low (equivalent to using COMMAREA with an XCTL
command and approximately equal to using main temporary storage).
v It is not recoverable.
v There is no resource security.
v It is not suitable for very large amounts of data (because main storage is used,
and it is held until the terminal user responds).
v As with using COMMAREA to transfer data between programs, it is available only
to the first program in a transaction, unless that program explicitly passes the
data or its address to succeeding programs.

| Using a channel on RETURN commands

| Instead of using a communication area (COMMAREA), a more modern method of
| passing data to the next program in a pseudoconversation is to use a channel.
| Channels have several advantages over COMMAREAs—see Benefits of channels.
| To pass a channel on a RETURN command, you use the CHANNEL option in place
| of the COMMAREA option.

| Channels are described in Enhanced inter-program data transfer: channels as

| modern-day COMMAREAs.

Chapter 13. Sharing data across transactions 187

Using the display screen to share data
You can also store data between pseudoconversational transactions from a 3270
display terminal on the display screen itself. For example, if users make errors in
data that they are asked to enter on a screen, the transaction processing the input
usually points out the errors on the screen (with highlights or messages), sets the
next transaction identifier to point to itself (so that it processes the corrected input),
and returns to CICS.

The transaction has two ways of using the valid data. It can save it (for example, in
COMMAREA), and pass it on for the next time it is run. In this case, the transaction
must merge the changed data on the screen with the data from previous entries.
Alternatively, it can save the data on the screen by not turning off the modified data
tags of the keyed fields.

Saving the data on the screen is very easy to code, but it is not very secure. You
are not recommended to save screens that contain large amounts of data as errors
may occur because of the additional network traffic needed to resend the
unchanged data. (This restriction does not apply to locally-attached terminals.)

Secondly, if the user presses the CLEAR key, the screen data is lost, and the
transaction must be able to recover from this. You can avoid this by defining the
CLEAR key to mean CANCEL or QUIT, if this is appropriate for the application
concerned.

Data other than keyed data may also be stored on the screen. This data can be
protected from changes (except those caused by CLEAR) and can be nondisplay, if
necessary.

188 CICS TS for z/OS: CICS Application Programming Guide

Chapter 14. Enhanced inter-program data transfer: channels
as modern-day COMMAREAs
Traditionally, CICS programs have used communication areas (COMMAREAs) to
exchange data. This topic describes an improved method of transferring data
between programs, in amounts that far exceed the 32KB limit that applies to
COMMAREAs.

This section contains:

v “Channels: quick start”
v “Using channels: some typical scenarios” on page 192
v “Creating a channel” on page 195
v “The current channel” on page 196
v “The scope of a channel” on page 200
v “Discovering which containers a program’s been passed” on page 204
v “Discovering which containers were returned from a link” on page 204
v “CICS read only containers” on page 204
v “Designing a channel: best practices” on page 205
v “Constructing and using a channel: an example” on page 206
v “Channels and BTS activities” on page 207
v “Using channels from JCICS” on page 209
v “Dynamic routing with channels” on page 209
v “Data conversion” on page 210
v “Benefits of channels” on page 215
v “Migrating from COMMAREAs to channels” on page 216

Channels: quick start

Containers and channels

Containers are named blocks of data designed for passing information between
programs. You can think of them as “named communication areas (COMMAREAs)”.
Programs can pass any number of containers between each other. Containers are
grouped together in sets called channels. A channel is analogous to a parameter
list.

To create named containers and assign them to a channel, a program uses EXEC
CICS PUT CONTAINER(container-name) CHANNEL(channel-name) commands. It
can then pass the channel (and its containers) to a second program using the
CHANNEL(channel-name) option of the EXEC CICS LINK, XCTL, START, or
RETURN commands.

The second program can read containers passed to it using the EXEC CICS GET
CONTAINER(container-name) command. This command reads the named container
belonging to the channel that the program was invoked with.

If the second program is invoked by a LINK command, it can also return containers
to the calling program. It can do this by creating new containers, or by reusing
existing containers.

Channels and containers are visible only to the program that creates them and the
programs they are passed to. When these programs terminate, CICS automatically
destroys the containers and their storage.

© Copyright IBM Corp. 1989, 2005 189

Channel containers are not recoverable. If you need to use recoverable containers,
use CICS business transaction services (BTS) containers. The relationship between
channel and BTS containers is described in “Channels and BTS activities” on page
207. For detailed information about BTS, see the CICS Business Transaction
Services manual.

Basic examples
Figure 39 on page 191 shows a COBOL program, CLIENT1, that:
1. Uses PUT CONTAINER(container-name) CHANNEL(channel-name) commands
to create a channel called inqcustrec and add two containers, custno and
branchno, to it; these contain a customer number and a branch number,
respectively.
2. Uses a LINK PROGRAM(program-name) CHANNEL(channel-name) command
to link to program SERVER1, passing the inqcustrec channel.
3. Uses a GET CONTAINER(container-name) CHANNEL(channel-name) command
to retrieve the customer record returned by SERVER1. The customer record is in
the custrec container of the inqcustrec channel.

Note that the same COBOL copybook, INQINTC, is used by both the client and
server programs. Line 3 and lines 5 through 7 of the copybook represent the
INQUIRY-CHANNEL and its containers. These lines are not strictly necessary to the
working of the programs, because containers and channels are created simply by
being named (on, for example, PUT CONTAINER commands); they do not have to
be defined. However, the inclusion of these lines in the copybook used by both
programs makes for easier maintenance; they record the names of the containers
used.

Recommendation

For ease of maintenance of a client/server application that uses a channel, create a

copybook that records the names of the containers used and defines the data fields
that map to the containers. Include the copybook in both the client and the server
program.

Note: This example shows two COBOL programs. The same techniques can be
used in any of the other languages supported by CICS. However, for COBOL
programs only, if the server program uses the SET option (instead of INTO)
on the EXEC CICS GET CONTAINER command, the structure of the storage
pointed to by SET must be defined in the LINKAGE section of the program.
This means that you will require two copybooks rather than one. The first, in
the WORKING-STORAGE section of the program, names the channel and
containers used. The second, in the LINKAGE section, defines the storage
structure.

190 CICS TS for z/OS: CICS Application Programming Guide

IDENTIFICATION DIVISION.
PROGRAM-ID. CLIENT1.

WORKING-STORAGE SECTION.

COPY INQINTC
* copybook INQINTC
* Channel name
* 01 INQUIRY-CHANNEL PIC X(16) VALUE ’inqcustrec’.
* Container names
* 01 CUSTOMER-NO PIC X(16) VALUE ’custno’.
* 01 BRANCH-NO PIC X(16) VALUE ’branchno’.
* 01 CUSTOMER-RECORD PIC X(16) VALUE ’custrec’.
* Define the data fields used by the program
* 01 CUSTNO PIC X(8).
* 01 BRANCHNO PIC X(5).
* 01 CREC.
* 02 CUSTNAME PIC X(80).
* 02 CUSTADDR1 PIC X(80).
* 02 CUSTADDR2 PIC X(80).
* 02 CUSTADDR3 PIC X(80).

PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.

*
* INITIALISE CUSTOMER RECORD
*
... CREATE CUSTNO and BRANCHNO
*
* GET CUSTOMER RECORD
*
EXEC CICS PUT CONTAINER(CUSTOMER-NO) CHANNEL(INQUIRY-CHANNEL)
FROM(CUSTNO) FLENGTH(LENGTH OF CUSTNO)
END-EXEC
EXEC CICS PUT CONTAINER(BRANCH-NO) CHANNEL(INQUIRY-CHANNEL)
FROM(BRANCHNO) FLENGTH(LENGTH OF BRANCHNO)
END-EXEC

EXEC CICS LINK PROGRAM(’SERVER1’) CHANNEL(INQUIRY-CHANNEL) END-EXEC

EXEC CICS GET CONTAINER(CUSTOMER-RECORD) CHANNEL(INQUIRY-CHANNEL)

INTO(CREC) END-EXEC

*
* PROCESS CUSTOMER RECORD
*
... FURTHER PROCESSING USING CUSTNAME and CUSTADDR1 etc...

EXEC CICS RETURN END-EXEC

EXIT.

Figure 39. A simple example of a program that creates a channel and passes it to a second
program

Figure 40 on page 192 shows the SERVER1 program linked to by CLIENT1. SERVER1
retrieves the data from the custno and branchno containers it has been passed, and
uses it to locate the full customer record in its database. It then creates a new
container, custrec, on the same channel, and returns the customer record in it.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 191
Note that the programmer hasn’t specified the CHANNEL keyword on the GET and PUT
commands in SERVER1: if the channel isn’t specified explicitly, the current channel is
used—that is, the channel that the program was invoked with.

IDENTIFICATION DIVISION.
PROGRAM-ID. SERVER1.

WORKING-STORAGE SECTION.

PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.

EXEC CICS GET CONTAINER(CUSTOMER-NO)

INTO(CUSTNO) END-EXEC
EXEC CICS GET CONTAINER(BRANCH-NO)
INTO(BRANCHNO) END-EXEC

... USE CUSTNO AND BRANCHNO TO FIND CREC IN A DATABASE

EXEC CICS PUT CONTAINER(CUSTOMER-RECORD)

FROM(CREC)
FLENGTH(LENGTH OF CREC) END-EXEC

EXEC CICS RETURN END-EXEC

EXIT.

Figure 40. A simple example of a linked to program that retrieves data from the channel it
has been passed. This program is linked-to by program CLIENT1 shown in Figure 39 on
page 191.

Using channels: some typical scenarios

Channels and containers provide a powerful way to pass data between programs.
This section contains some examples of how channels can be used.

One channel, one program

Figure 41 on page 193 shows the simplest scenario—a “standalone” program with a
single channel with which it can be invoked.

192 CICS TS for z/OS: CICS Application Programming Guide

PAYR program

EXEC CICS LINK PROGRAM('payr')

CHANNEL('payroll')

Figure 41. A standalone program with a single channel

One channel, several programs (a component)

In Figure 42, there is a single channel to the top-level program in a set of
inter-related programs. The set of programs within the shaded area can be
regarded as a “component”. The client program “sees” only the external channel
and has no knowledge of the processing that takes place nor of the existence of the
back-end programs.

Inside the component, the programs can pass the channel between themselves.
Alternatively, a component program could, for example, pass a subset of the
original channel, by creating a new channel and adding one or more containers
from the original channel.

CH
EXEC CICS LINK PROGRAM('payr')
CHANNEL('payroll')

Figure 42. A “component”—a set of related programs invoked through a single external channel. “CH” indicates that
the programs within the component can pass channels between themselves.

Several channels, one component

As in the previous example, we have a set of inter-related programs that can be
regarded as a component. However, this time there are two, alternative, external
channels with which the component can be invoked. The top-level program in the
component issues an EXEC CICS ASSIGN CHANNEL command to determine
which channel it has been invoked with, and tailors its processing accordingly.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 193
The “loose coupling” between the client program and the component permits easy
evolution. That is, the client and the component can be upgraded at different times.
For example, first the component could be upgraded to handle a third channel,
consisting of a different set of containers from the first or second channels. Next,
the client program could be upgraded (or a new client written) to pass the third
channel.

EXEC CICS LINK PROGRAM('payr')

CHANNEL('payroll-2003') CH
EXEC CICS ASSIGN
CHANNEL(ch-name)

:
CH
EXEC CICS LINK PROGRAM('payr') : CH
CHANNEL('payroll-2004')

Figure 43. Multiple external channels to the same component. “CH” indicates that the programs within the component
may pass channels between themselves.

Multiple interactive components

Figure 44 on page 195 shows a “Human resources” component and a “Payroll”
component, each with a channel with which it can be invoked. The Payroll
component is invoked from both a standalone program and the Human resources
component.

194 CICS TS for z/OS: CICS Application Programming Guide

CH
EXEC CICS PUT
CONTAINER...

EXEC CICS LINK

CH CH
PROGRAM('payr')
CHANNEL('payroll')

EXEC CICS LINK PROGRAM('payr') Containers

CHANNEL('payroll')
CH

Human resources component

Containers

Payroll component

Figure 44. Multiple components which interact through their channels

Creating a channel
You create a channel by naming it on one of the following commands:
EXEC CICS LINK PROGRAM CHANNEL
EXEC CICS MOVE CONTAINER CHANNEL TOCHANNEL
EXEC CICS PUT CONTAINER CHANNEL
EXEC CICS RETURN TRANSID CHANNEL
EXEC CICS START TRANSID CHANNEL
EXEC CICS XCTL PROGRAM CHANNEL
If the channel doesn’t already exist, within the current program scope, it is created.

The most straightforward way to create a channel, and populate it with containers of
data, is to issue a succession of EXEC CICS PUT CONTAINER(container-name)
CHANNEL(channel-name) FROM(data_area) commands. The first PUT command
creates the channel (if it doesn’t already exist), and adds a container to it; the
subsequent commands add further containers to the channel. If the containers
already exist, their contents are overwritten by the new data.

An alternative way to add containers to a channel is to move them from another

channel. To do this, use the following command:
EXEC CICS MOVE CONTAINER(container-name) AS(container-new-name)
CHANNEL(channel-name1) TOCHANNEL(channel-name2)

Note:

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 195
1. If the CHANNEL or TOCHANNEL option isn’t specified, the current channel is
implied.
2. The source channel must be in program scope.
3. If the target channel doesn’t already exist, within the current program
scope, it is created.
4. If the source container doesn’t exist, an error occurs.
5. If the target container doesn’t already exist, it is created; if it already
exists, its contents are overwritten.

You can use MOVE CONTAINER, instead of GET CONTAINER and PUT
CONTAINER, as a more efficient way of transferring data between channels.

If the channel named on the following commands doesn’t already exist, within the
current program scope, an empty channel is created:
v EXEC CICS LINK PROGRAM CHANNEL(channel-name)
v EXEC CICS RETURN TRANSID CHANNEL(channel-name)
v EXEC CICS START TRANSID CHANNEL(channel-name)
v EXEC CICS XCTL PROGRAM CHANNEL(channel-name)

The current channel

A program’s current channel is the channel (if any) with which it was invoked. The
program can create other channels. However, the current channel, for a particular
invocation of a particular program, does not change. It is analogous to a parameter
list.

Current channel example, with LINK commands

The following figure illustrates the origin of a program’s current channel. It shows
five interactive programs. Program A is a top-level program started by, for example,
a terminal end-user. It isn’t started by a program and doesn’t have a current
channel.

B, C, D, and E are second-, third-, fourth-, and fifth-level programs, respectively.

Program B’s current channel is X, passed by the CHANNEL option on the EXEC
CICS LINK command issued by program A. Program B modifies channel X by
adding one container and deleting another.

Program C’s current channel is also X, passed by the CHANNEL option on the
EXEC CICS LINK command issued by program B.

Program D has no current channel, because C doesn’t pass it one.

Program E’s current channel is Y, passed by the CHANNEL option on the EXEC
CICS LINK command issued by D.

196 CICS TS for z/OS: CICS Application Programming Guide

Current CH: none

PROG A
PUT CONTAINER(ONE) CHANNEL(X) FROM(area1)
PUT CONTAINER(TWO) CHANNEL(X) FROM(area2)
LINK PROGRAM(B) CHANNEL(X)
:
:

Current CH: X

PROG B
:
PUT CONTAINER(THREE) FROM(area-a)
DELETE CONTAINER(TWO)
LINK PROGRAM(C) CHANNEL(X)
:
:
RETURN

Current CH: X
PROG C
:
LINK PROGRAM(D)
:
:
RETURN

Current CH: none

PROG D
:
PUT CONTAINER(first) CHANNEL(Y) FROM(a1)
PUT CONTAINER(second) CHANNEL(Y) FROM(a2)
LINK PROGRAM(E) CHANNEL(Y)
:
RETURN
LINK PROGRAM(E) INTERFACE(Y)

Current CH: Y
PROG E
:
:
RETURN

Figure 45. Current channel: example with LINK commands

The following table lists the name of the current channel (if any) of each of the five
programs shown in the previous figure.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 197
Table 10. The current channels of interactive programs—example with LINK commands
Prog. Current Issues commands Comments
CH
. Program A creates channel X and passes it to
EXEC CICS PUT CONTAINER(ONE) program B.
CHANNEL(X) FROM(area1)
EXEC CICS PUT CONTAINER(TWO) Note that, by the time control is returned to
A None CHANNEL(X) FROM(area2) program A by program B, the X channel has
EXEC CICS LINK PROGRAM(B) CHANNEL(X) been modified—it doesn’t contain the same set
. of containers as when it was created by
program A. (Container TWO has been deleted
and container THREE added by program B.)
. Program B modifies channel X (its current
EXEC CICS PUT CONTAINER(THREE) channel) by adding and deleting containers, and
FROM(area-a) passes the modified channel to program C.
EXEC CICS DELETE CONTAINER(TWO)
B X EXEC CICS LINK PROGRAM(C) CHANNEL(X) Program B doesn’t need to specify the
. CHANNEL option on the PUT CONTAINER and
. DELETE CONTAINER commands; its current
EXEC CICS RETURN
channel is implied.
. Program C links to program D, but does not
EXEC CICS LINK PROGRAM(D) pass it a channel.
C X .
.
EXEC CICS RETURN
. Program D creates a new channel, Y, which it
EXEC CICS PUT CONTAINER(first) passes to program E.
CHANNEL(Y) FROM(a1)
EXEC CICS PUT CONTAINER(second)
D None CHANNEL(Y) FROM(a2)
EXEC CICS LINK PROGRAM(E) CHANNEL(Y)
.
.
EXEC CICS RETURN
. Program E performs some processing on the
E Y RETURN data it’s been passed and returns.
.

Current channel example, with XCTL commands

Figure 46 on page 199 shows four interactive programs. A1 is a top-level program
started by, for example, a terminal end-user. It isn’t started by a program and
doesn’t have a current channel. B1, B2, and B3 are all second-level programs.

B1’s current channel is X, passed by the CHANNEL option on the EXEC CICS LINK
command issued by A1.

B2 has no current channel, because B1 doesn’t pass it one.

B3’s current channel is Y, passed by the CHANNEL option on the EXEC CICS
XCTL command issued by B2.

When B3 returns, channel Y and its containers are deleted by CICS.

198 CICS TS for z/OS: CICS Application Programming Guide

Current CH: none

PROG A1

LINK PROGRAM(B1) CHANNEL(X)

RETURN

XCTL PROGRAM(B3)
CHANNEL(Y)
Current CH: X Current CH: none Current CH: Y

PROG B1 XCTL PROGRAM(B2) PROG B2 PROG B3

Figure 46. Current channels—example, with XCTL commands

The following table lists the name of the current channel (if any) of each of the four
programs shown in Figure 46.
Table 11. The current channels of interactive programs—example
Program Current Issues command
channel
.
A1 None EXEC CICS LINK PROGRAM(B1) CHANNEL(X)
.
.
B1 X EXEC CICS XCTL PROGRAM(B2)
.
.
B2 None EXEC CICS XCTL PROGRAM(B3) CHANNEL(Y)
.
.
B3 Y EXEC CICS RETURN
.

Current channel: START and RETURN commands

Besides EXEC CICS LINK and XCTL, two other commands can be used to invoke
a program and pass it a channel:
EXEC CICS START TRANSID(tranid) CHANNEL(channel-name)
The program that implements the started transaction (or the first program, if
there are more than one) is passed the channel, which becomes its current
channel.
EXEC CICS RETURN TRANSID(tranid) CHANNEL(channel-name)
The CHANNEL option is valid only:

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 199
v On pseudoconversational RETURNs—that is, on RETURN commands that
specify, on the TRANSID option, the next transaction to be run at the user
terminal.
v If issued by a program at the highest logical level—that is, a program that
returns control to CICS.
The program that implements the next transaction is passed the channel, which
becomes its current channel.

The scope of a channel

The scope of a channel is the code from which it can be accessed.

Scope example, with LINK commands

The following figure shows the same five interactive programs previously described
in “Current channel example, with LINK commands”.

The scope of the X channel—the code from which it can be accessed—is programs
A, B, and C.

The scope of the Y channel is programs D and E.

Note that, by the time control is returned to program A by program B, the X channel
has been modified—it doesn’t contain the same set of containers as when it was
created by program A.

200 CICS TS for z/OS: CICS Application Programming Guide

Current Channel: none

PROG A
Scope of Channel X
PUT CONTAINER(ONE) CHANNEL(X) FROM(area1)
PUT CONTAINER(TWO) CHANNEL(X) FROM(area2)
LINK PROGRAM(B) CHANNEL(X)
:
:

Current Channel: X

PROG B
:
PUT CONTAINER(THREE) FROM(area-a)
DELETE CONTAINER(TWO)
LINK PROGRAM(C) CHANNEL(X)
:
:
RETURN

Current Channel: X
PROG C
:
LINK PROGRAM(D)
:
:
RETURN

Current Channel: Y
PROG E
:
:
RETURN

Figure 47. The scope of a channel—example showing LINK commands

The following table lists the name and scope of the current channel (if any) of each
of the five programs shown in the previous figure.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 201
Table 12. The scope of a channel—example with LINK commands
Program Current channel Scope of channel
A None Not applicable
B X A, B, C
C X A, B, C
D None Not applicable
E Y D, E

Scope example, with LINK and XCTL commands

Figure 48 on page 203 shows the same four interactive programs previously
described in “Current channel example, with XCTL commands”, plus a third-level
program, C1, that is invoked by an EXEC CICS LINK command from program B1.

The scope of the X channel is restricted to A1 and B1.

The scope of the Y channel is B2 and B3.

The scope of the Z channel is B1 and C1.

Note that, by the time control is returned to program A1 by program B3, it’s possible
that the X channel may have been modified by program B1—it might not contain
the same set of containers as when it was created by A1.

202 CICS TS for z/OS: CICS Application Programming Guide

Channel X scope =

Channel Y scope = Current CH: none

Channel Z scope = PROG A1

X and Z scope =

LINK PROGRAM(B1) CHANNEL(X)

RETURN

XCTL PROGRAM(B3)
CHANNEL(Y)
Current CH: X
Current CH: none Current CH: Y

XCTL PROGRAM(B2) PROG B2 PROG B3

PROG B1

LINK PROGRAM(C1) CHANNEL(Z)

Current CH: Z

PROG C1

Figure 48. The scope of a channel—example showing LINK and XCTL commands

The following table lists the name and scope of the current channel (if any) of each
of the five programs shown in Figure 48.
Table 13. The scope of a channel—example with LINK and XCTL commands
Program Current channel Scope of channel
A1 None Not applicable
B1 X A1 and B1
B2 None Not applicable
B3 Y B2 and B3
C1 Z B1 and C1

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 203
Discovering which containers a program’s been passed
Typically, programs that exchange a channel are written to handle that channel.
That is, both client and server programs know the name of the channel, and the
names and number of the containers in the channel. However, if, for example, a
server program or component is written to handle more than one channel, on
invocation it must discover which of the possible channels it’s been passed.

A program can discover its current channel—that is, the channel with which it was
invoked—by issuing an EXEC CICS ASSIGN CHANNEL command. (If there is no
current channel, the command returns blanks.)

The program can also (should it need to) get the names of the containers in its
current channel by browsing. Typically, this is not necessary. A program written to
handle several channels is often coded to be aware of the names and number of
the containers in each possible channel.

To get the names of the containers in the current channel, use the browse
commands:
v EXEC CICS STARTBROWSE CONTAINER BROWSETOKEN(data-area) .
v EXEC CICS GETNEXT CONTAINER(data-area) BROWSETOKEN(token).
v EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(token).

Having retrieved the name of its current channel and, if necessary, the names of
the containers in the channel, a server program can adjust its processing to suit the
kind of data that it’s been passed.

Discovering which containers were returned from a link

A program creates a channel, which it passes to a second program by means of an
EXEC CICS LINK PROGRAM(program-name) CHANNEL(channel-name)
command. The second program performs some processing on the data it’s been
passed, and returns the results in the same channel (its current channel).

On return, the first program knows the name of the channel which has been
returned, but not necessarily the names of the containers in the channel. (Does the
returned channel contain the same containers as the passed channel, or has the
second program deleted some or created others?) The first program can discover
the container-names by browsing. To do this, it uses the commands:
v EXEC CICS STARTBROWSE CONTAINER BROWSETOKEN(data-area)
CHANNEL(channel-name).
v EXEC CICS GETNEXT CONTAINER(data-area) BROWSETOKEN(token).
v EXEC CICS ENDBROWSE CONTAINER BROWSETOKEN(token).

CICS read only containers

CICS can create channels and containers for its own use, and pass them to user
programs. In some cases CICS marks these containers as read only, so that the
user program cannot modify data which CICS needs on return from the user
program.

User programs cannot create read only containers.

You cannot overwrite, move, or delete a read only container. Thus, if you specify a
read only container on a PUT CONTAINER, MOVE CONTAINER, or DELETE
CONTAINER command an INVREQ condition occurs.

204 CICS TS for z/OS: CICS Application Programming Guide

Designing a channel: best practices
It’s possible to use containers to pass data in the same way as communication
areas (COMMAREAs) have traditionally been used. However, channels have
several advantages over COMMAREAs (see “Benefits of channels” on page 215)
and it pays to design your channels to make the most of these improvements.

At the end of a DPL call, input containers that have not been changed by the
server program are not returned to the client. Input containers whose contents
have been changed by the server program, and containers created by the server
program, are returned. Therefore, for optimal DPL performance:
v Use separate containers for input and output data.
v The server program, not the client, should create the output containers.
v Use separate containers for read-only and read-write data.
v If a structure is optional, make it a separate container.
v Use dedicated containers for error information.

Here are some general tips on designing a channel. They include and expand on
the recommendations for achieving optimal DPL performance.
v Use separate containers for input and output data. This leads to:
– Better encapsulation of the data, making your programs easier to maintain.
– Greater efficiency when a channel is passed on a DPL call, because smaller
containers flow in each direction.
v The server program, not the client, should create the output containers. If the
client creates them, empty containers will be sent to the server region.
v Use separate containers for read-only and read-write data. This leads to:
– A simplification of your copybook structure, making your programs easier to
understand.
– Avoidance of the problems with REORDER overlays.
– Greater transmission efficiency between CICS regions, because read-only
containers sent to a server region will not be returned.
v Use separate containers for each structure. This leads to:
– Better encapsulation of the data, making your programs easier to understand
and maintain.
– Greater ease in changing one of the structures, because you don’t need to
recompile the entire component.
– The ability to pass a subset of the channel to sub-components, by using the
MOVE CONTAINER command to move containers between channels.
v If a structure is optional, make it a separate container. This leads to greater
efficiency, because the structure is passed only if the container is present.
v Use dedicated containers for error information. This leads to:
– Better documentation of what is error information.
– Greater efficiency, because:
1. The structure containing the error information is passed back only if an
error occurs.
2. It is more efficient to check for the presence of an error container by
issuing a GET CONTAINER(known-error-container-name) command (and
possibly receiving a NOTFOUND condition) than it is to initiate a browse
of the containers in the channel.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 205
v When you need to pass data of different types—for example, binary data and
character data—use separate containers for each type, rather than one container
with a complicated structure. This improves your ability to move between different
code pages.
v When you need to pass a large amount of data, split it between multiple
containers, rather than put it all into one container.
When a channel is passed to a remote program or transaction, passing a large
amount of data may affect performance. This is particularly true if the local and
remote regions are connected by an ISC, rather than MRO, connection.
v Take care not to create so many large containers that you limit the amount of
storage available to other applications.

For information about migrating programs that use COMMAREAs to use channels
instead, see “Migration to the new function” on page 216.

Constructing and using a channel: an example

Figure 49 shows a CICS client program that:
1. Uses EXEC CICS PUT CONTAINER commands to construct (and put data in) a
set of containers. The containers are all part of the same named
channel—“payroll-2004”.
2. Issues an EXEC CICS LINK command to invoke the PAYR server program,
passing it the payroll-2004 channel.
3. Issues an EXEC CICS GET CONTAINER command to retrieve the server’s
program output, which it knows will be in the status container of the
payroll-2004 channel.

* create the employee container on the payroll-2004 channel

EXEC CICS PUT CONTAINER(’employee’) CHANNEL(’payroll-2004’) FROM(’John Doe’)

* create the wage container on the payroll-2004 channel

EXEC CICS PUT CONTAINER(’wage’) CHANNEL(’payroll-2004’) FROM(’100’)

* invoke the payroll service, passing the payroll-2004 channel

EXEC CICS LINK PROGRAM(’PAYR’) CHANNEL(’payroll-2004’)

* examine the status returned on the payroll-2004 channel

EXEC CICS GET CONTAINER(’status’) CHANNEL(’payroll-2004’) INTO(stat)

Figure 49. How a client program can construct a channel, pass it to a server program, and
retrieve the server’s output

Figure 50 on page 207 shows part of the PAYR server program invoked by the client.
The server program:
1. Queries the channel with which it’s been invoked.
2. Issues EXEC CICS GET CONTAINER commands to retrieve the input from the
employee and wage containers of the payroll-2004 channel.
3. Processes the input data.
4. Issues an EXEC CICS PUT CONTAINER command to return its output in the
status container of the payroll-2004 channel.

206 CICS TS for z/OS: CICS Application Programming Guide

"PAYR", CICS COBOL server program

* discover which channel I’ve been invoked with

EXEC CICS ASSIGN CHANNEL(ch_name)
:
WHEN ch_name ’payroll-2004’
* my current channel is "payroll-2004"
* get the employee passed into this program
EXEC CICS GET CONTAINER(’employee’) INTO(emp)
* get the wage for this employee
EXEC CICS GET CONTAINER(’wage’) INTO(wge)
:
* process the input data
:
:
* return the status to the caller by creating the status container
* on the payroll channel and putting a value in it
EXEC CICS PUT CONTAINER(’status’) FROM(’OK’)
:
:
WHEN ch_name ’payroll-2005’
* my current channel is "payroll-2005"
:
:
:

Figure 50. How a server program can query the channel it’s been passed, retrieve data from
the channel’s containers, and return output to the caller

Channels and BTS activities

The PUT, GET, MOVE, and DELETE CONTAINER commands used to build and
interact with a channel are similar to those used in CICS business transaction
services (BTS) applications. (For information about BTS, see the CICS Business
Transaction Services manual.) Thus, programmers with experience of BTS will find
it easy to use containers in non-BTS applications. Furthermore, server programs
that use containers can be called from both channel and BTS applications. An
example of this is shown in Figure 51 on page 208.

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 207
CICS Channel program CICS BTS program
DEFINE ACTIVITY('payroll')
PROGRAM('payact')

* create the employee container * create the employee container

* on the payroll-2004 Channel * on the payroll-2004 Channel
EXEC CICS PUT CONTAINER('employee') EXEC CICS PUT CONTAINER('employee')
CHANNEL('payroll-2004') FROM('John Doe') ACTIVITY('payroll-2004') FROM('John Doe')

* create the wage container * create the wage container

* on the payroll-2004 Channel * on the payroll-2004 Channel
EXEC CICS PUT CONTAINER('wage') EXEC CICS PUT CONTAINER('wage')
CHANNEL('payroll-2004') FROM('100') ACTIVITY('payroll-2004') FROM('100')

* invoke the payroll service,

* invoke the payroll service, * passing the payroll-2004 Channel
* passing the payroll-2004 Channel EXEC CICS LINK ACTIVITY('payroll-2004')
EXEC CICS LINK PROGRAM('PAYR')
CHANNEL('payroll-2004')
* examine the status returned on
* examine the status returned on * the payroll-2004 Channel
* the payroll-2004 Channel EXEC CICS GET CONTAINER('status')
EXEC CICS GET CONTAINER('status') ACTIVITY('payroll-2004') INTO(stat)
CHANNEL('payroll-2004') INTO(stat)

Simple client uses a Channel to BTS event-driven wrapper controls

pass containers to the service a more sophisticated application

Program PAYACT

EXEC CICS RETRIEVE EVENT(...

WHEN('....
EXEC CICS LINK PROGRAM('payr')

Program PAYR
* get the employee passed into this program
EXEC CICS GET CONTAINER('employee')
INTO(emp) Container-aware programs can
: be called from both Channel
:
* return the status to the caller
and BTS applications
EXEC CICS PUT CONTAINER('status')
FROM('OK')

Figure 51. Channels and BTS activities

Context
As shown in Figure 51, a program that issues container commands can be used,
without change, as part of a channel application or as part of a BTS activity.

For a program to be used in both a channel and a BTS context, the container
commands that it issues must not specify any options that identify them as either
channel or BTS commands. The options to be avoided on each of the container
commands are:
DELETE CONTAINER
ACQACTIVITY (BTS-specific)

208 CICS TS for z/OS: CICS Application Programming Guide

ACQPROCESS (BTS-specific)
ACTIVITY (BTS-specific)
CHANNEL (channel-specific)
PROCESS (BTS-specific)
GET CONTAINER
ACQACTIVITY (BTS-specific)
ACQPROCESS (BTS-specific)
ACTIVITY (BTS-specific)
CHANNEL (channel-specific)
INTOCCSID (channel-specific)
PROCESS (BTS-specific)
MOVE CONTAINER
FROMACTIVITY (BTS-specific)
CHANNEL (channel-specific)
FROMPROCESS (BTS-specific)
TOACTIVITY (BTS-specific)
TOCHANNEL (channel-specific)
TOPROCESS (BTS-specific)
PUT CONTAINER
ACQACTIVITY (BTS-specific)
ACQPROCESS (BTS-specific)
ACTIVITY (BTS-specific)
CHANNEL (channel-specific)
DATATYPE (channel-specific)
FROMCCSID (channel-specific)
PROCESS (BTS-specific)

When a container command is executed, CICS analyzes the context (channel, BTS,
or neither) in which it occurs, in order to determine how to process the command.
To determine the context, CICS uses the following sequence of tests:
1. Channel: does the program have a current channel?
2. BTS: is the program part of a BTS activity?
3. None: the program has no current channel and is not part of a BTS activity. It
therefore has no context in which to execute container commands. The
command is rejected with an INVREQ condition and a RESP2 value of 4.

Using channels from JCICS

For information about using channels with JCICS, see Java Applications in CICS.

Dynamic routing with channels

EXEC CICS LINK and EXEC CICS START commands, which can pass either
COMMAREAs or channels, can be dynamically routed. Thus the following types of
channel-related request can be dynamically routed:
v Program-link (DPL) requests
v Transactions started by terminal-related START requests
v Non-terminal-related START requests

The routing program is passed, in the DYRCHANL field of its communication area,
the name of the channel, if any, associated with the program-link or START
command. The DYRCHANL field applies only to the three types of request listed
above. For other types of request, or if there is no channel associated with the
request, it contains blanks.
Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 209
Note: The routing program‘s communication area is mapped by the DFHDYPDS
DSECT.

Note that the routing program is given the name of the channel, not its address,
and so is unable to use the DYRCHANL field to inspect or change the contents of
the containers.

When a LINK or START command passes a COMMAREA rather than a channel,

the routing program can, depending on the type of request, inspect or change the
COMMAREA‘s contents. For LINK requests and transactions started by
terminal-related START requests (which are handled by the dynamic routing
program) but not for non-terminal-related START requests (which are handled by
the distributed routing program) the routing program is given, in the DYRACMAA
field of DFHDYPDS, the address of the application‘s COMMAREA, and can inspect
and change its contents.

To give the routing program the same kind of functionality with channels, an
application that uses a channel can create, within the channel, a special container
named DFHROUTE. If the application issues a LINK or terminal-related START
request (but not a non-terminal-related START request) that is to be dynamically
routed, the dynamic routing program is given, in the DYRACMAA field of
DFHDYPDS, the address of the DFHROUTE container, and can inspect and
change its contents.

If you are migrating a program to pass a channel rather than a COMMAREA, you
could use its existing COMMAREA structure to map DFHROUTE.

For introductory information about dynamic and distributed routing, see the CICS
Intercommunication Guide. For information about writing a dynamic or distributed
routing program, see the CICS Customization Guide.

Data conversion

Why is data conversion needed?

Here are some cases in which data conversion is necessary:
v When character data is passed between platforms that use different encoding
standards—for example, EBCDIC and ASCII.
v When you want to change the encoding of some character data from one Coded
Character Set Identifier (CCSID) to another. (For an explanation of CCSIDs, and
a list of the CCSIDs supported by CICS, see the CICS Family: Communicating
from CICS on System/390® manual.)

Preparing for code page conversion with channels

The conversion of data to or from either UTF-8 or UTF-16 and EBCDIC and ASCII
codepages, depends on the selection of suitable conversion images. Conversion
between the UTF-8 and UTF-16 forms of Unicode is also supported.

Appendix F of the z/OS Support for Unicode: Using Conversion Services manual
-SA22 -7649 records those conversions which are supported though these services.
These are not limited to Unicode, but include the ability to convert between a broad
range of character encodings, including EBCDIC, ASCII and Unicode.

Note:

210 CICS TS for z/OS: CICS Application Programming Guide

1. The conversion between 037 and 500, as used, for example, with the
MQ transport is an EBCDIC to EBCDIC conversion brought about by
small differences in the character encodings used by CICS and MQ.
2. You need to be aware that not all points in each codepage have direct
counterparts in other codepages. The EBCDIC character NL is one such
example. Java and z/OS conversion services may differ in the
conversions that they perform. ″Technotes″, and other Internet
discussions may offer guidance on particular points. It is also worth
observing that programming communities are themselves divided on the
question of what is the more appropriate conversion in particular
circumstances.

CICS now supports any of these character conversions by making use of the z/OS
conversion services. However, those conversions that earlier releases of CICS
carried out using a set of tables, continue to be supported in that manner. It is only
if CICS TS 3.1 is asked to carry out a conversion between a pair of CCSIDs that
are unsupported via these tables, that it attempts the conversion using the z/OS
services.
Ensuring that required conversion images are available
Those CCSIDs used as part of CICS applications must be made known to
the System Programmers responsible for maintaining the z/OS Conversion
Image, so that specific conversions are available to the CICS regions where
these applications execute.
Handling CCSID 1200
CICS supports conversions involving UTF-16 data using any of the
following CCSID’s: 1200, 1201, and 1202. The z/OS conversion services
permit CCSID 1200, in its big-endian form, to be used, but does not contain
support for the little-endian form or for CCSIDs 1201 or 1202. CICS
transforms any source data that is identified in any of these unsupported
forms to the big-endian form of 1200 before passing the data to z/OS for
conversion. If the target data is one of the unsupported forms then CICS
receives the data as the big-endian form of 1200 and transforms it to the
required CCSID. If the target CCSID is 1200 then CICS assumes the
encoding to be in big-endian form. If the conversion is between any of
these CCSIDs then CICS will carry out the transformation without calling
the z/OS conversion services.
When setting up the z/OS conversion image for conversions involving any
of these forms of UTF-16 then CCSID 1200 must be specified. CCSIDs
1201 and 1202 will not be recognised by z/OS when attempting to create a
conversion image.
CICS respects the byte order marker for inbound conversions, but is not
able to retain that information when handling a related outbound
conversion. All outbound data for CCSID 1200 is UTF16-BE. Application
programmers need to know about this and perform their own BE to LE
conversions if they so require.
Sharing a conversion image
v Unless the PTF for APAR OA05744 is applied, do not specify a search
order for those conversions, installed into the z/OS image which are
intended for use by CICS.
v If the same conversions are needed for COBOL you must define the
conversion image with two separate statements:
– one with no search order, and

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 211
– the other explicitly specifying a search order of ’RECLM’.
for example:.

CONVERSION 850,037;
CONVERSION 850,037,RECLM;
With the APAR installed, CICS and COBOL can make use of those
supported conversions which specify the default search order implicitly or
explicitly, removing the need to provide two control statements in the image
generation file.
JAVA programs
Codepage conversion facilities exist within JAVA, So it is not neccessary to
duplicate these in CICS. The conversion facilities described here do not
extend to JAVA programs. For an example, see the putting data into a
container topic in the Java applications in CICS manual.

Data conversion with channels

Applications that use channels to exchange data use a simple data conversion
model. Frequently, no conversion is required and, when it is, a single programming
instruction can be used to tell CICS to handle it automatically.

Note the following:

v Usually, when a (non-Java) CICS TS program calls another (non-Java) CICS TS
program, no data conversion is required, because both programs use EBCDIC
encoding. For example, if a CICS TS C-language program calls a CICS TS
COBOL program, passing it some containers holding character data, the only
reason for using data conversion would be the unusual one of wanting to change
the CCSID of the data.
v The data conversion model used by channel applications is much simpler than
that used by COMMAREA applications. Applications that use COMMAREAs to
exchange data use the traditional data conversion model described in the CICS
Family: Communicating from CICS on System/390 manual. Conversion is done
under the control of the system programmer, using the DFHCNV conversion
table, the DFHCCNV conversion program and, optionally, the DFHUCNV
user-replaceable conversion program.
In contrast, the data in channel containers is converted under the control of the
application programmer, using API commands.
v The application programmer is responsible only for the conversion of user
data—that is, the data in containers created by his application programs. System
data is converted automatically by CICS, where necessary.
v The application programmer is concerned only with the conversion of character
data. The conversion of binary data (between big-endian and little-endian) is not
supported.
v Your applications can use the container API as a simple means of converting
character data from one code page to another—see “Using containers to do code
page conversion” on page 214.

For data conversion purposes, CICS recognizes two types of data:

CHAR Character data—that is, a text string. The data in the container is converted
(if necessary) to the code page of the application that retrieves it. If the
application that retrieves the data is a client on an ASCII-based system, this
will be an ASCII code page. If it is a CICS Transaction Server for z/OS
application, it will be an EBCDIC code page.

212 CICS TS for z/OS: CICS Application Programming Guide

All the data in a container is converted as if it were a single character
string. For single-byte character set (SBCS) code pages, a structure
consisting of several character fields is equivalent to a single-byte character
string. However, for double-byte character set (DBCS) code pages this is
not the case. If you use DBCS code pages, to ensure that data conversion
works correctly you must put each character string into a separate
container.
BIT All non-character data—that is, everything that is not designated as being of
type CHAR. The data in the container cannot be converted. This is the
default value.

The API commands used for data conversion are:

v EXEC CICS PUT CONTAINER [CHANNEL] [DATATYPE] [FROMCCSID]
v EXEC CICS GET CONTAINER [CHANNEL] [INTOCCSID]

For detailed information about the PUT CONTAINER (CHANNEL) command, see
PUT CONTAINER (CHANNEL). For detailed information about the GET
CONTAINER (CHANNEL) command, see GET CONTAINER (CHANNEL).

How to cause CICS to convert character data automatically

1. In the client program, use the DATATYPE(DFHVALUE(CHAR)) option of the
PUT CONTAINER command to specify that a container holds character data
and that the data is eligible for conversion. For example:
EXEC CICS PUT CONTAINER(cont_name) CHANNEL(’payroll’)
FROM(data1) DATATYPE(DFHVALUE(CHAR))

There is no need to specify the FROMCCSID option unless the data is not in
the default CCSID of the client platform. (For CICS TS regions, the default
CCSID is specified on the LOCALCCSID system initialization parameter.) The
default CCSID is implied.
2. In the server program, issue a GET CONTAINER command to retrieve the
data from the program’s current channel:
EXEC CICS GET CONTAINER(cont_name) INTO(data_area1)

The data is returned in the default CCSID of the server platform. There is no
need to specify the INTOCCSID option unless you want the data to be
converted to a CCSID other than the default. If the client and server platforms
are different, data conversion takes place automatically.
3. In the server program, issue a PUT CONTAINER command to return a value
to the client:
EXEC CICS PUT CONTAINER(status) FROM(data_area2)
DATATYPE(DFHVALUE(CHAR))

The DATATYPE(DFHVALUE(CHAR)) option specifies that the container holds

character data and that the data is eligible for conversion. There is no need to
specify the FROMCCSID option unless the data is not in the default CCSID of
the server platform.
4. In the client program, issue a GET CONTAINER command to retrieve the
status returned by the server program:
EXEC CICS GET CONTAINER(status) CHANNEL(’payroll’)
INTO(status_area)

The status is returned in the default CCSID of the client platform. There is no
need to specify the INTOCCSID option unless you want the data to be

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 213
converted to a CCSID other than the default. If the client and server platforms
are different, data conversion takes place automatically.

Using containers to do code page conversion

Your applications can use the container API as a simple means of converting
character data from one code page to another. The following example converts data
from codepage1 to codepage2:
EXEC CICS PUT CONTAINER(temp) DATATYPE(DFHVALUE(CHAR))
FROMCCSID(codepage1) FROM(input-data)
EXEC CICS GET CONTAINER(temp) INTOCCSID(codepage2)
SET(data-ptr) FLENGTH(data-len)

The following example converts data from the region’s default EBCDIC code page
to a specified UTF8 code page:
EXEC CICS PUT CONTAINER(temp) DATATYPE(DFHVALUE(CHAR))
FROM(ebcdic-data)
EXEC CICS GET CONTAINER(temp) INTOCCSID(utf8_ccsid)
SET(utf8-data-ptr) FLENGTH(utf8-data-len)

When using the container API in this way, bear the following in mind:
v On GET CONTAINER commands, use the SET option, rather than INTO, unless
the converted length is known. (You can retrieve the length of the converted data
by issuing a GET CONTAINER(cont_name) NODATA FLENGTH(len) command.)
v To avoid a storage overhead, after conversion copy the converted data and
delete the container.
v To avoid shipping the channel, use a temporary channel.
v All-to-all conversion is not possible. That is, a code page conversion error occurs
if a specified code page and the channel’s code page are an unsupported
combination.

A SOAP example
A CICS TS SOAP application:
1. Retrieves a UTF8 or UTF16 message from a socket or MQ message queue.
2. Puts the message into a container, in UTF8 format.
3. Puts EBCDIC data structures into other containers on the same channel.
4. Makes a distributed program link (DPL) call to a handler program on a back-end
AOR, passing the channel.

The back-end handler program, also running on CICS TS, can use EXEC CICS
GET CONTAINER commands to retrieve the EBCDIC data structures or the
messages. It can get the messages in UTF8 or UTF16, or in its own or the region’s
EBCDIC code page. Similarly, it can use EXEC CICS PUT CONTAINER commands
to place data into the containers, in UTF8, UTF16, or EBCDIC.

To retrieve one of the messages in the region’s EBCDIC code page, the handler
can issue the command:
EXEC CICS GET CONTAINER(input_msg) INTO(msg)

Because the INTOCCSID option is not specified, the message data is automatically
converted to the region’s EBCDIC code page. (This assumes that the PUT
CONTAINER command used to store the message data in the channel specified a
DATATYPE of CHAR; if it specified a DATATYPE of BIT, the default, no conversion
is possible.)

214 CICS TS for z/OS: CICS Application Programming Guide

To return some output in the region’s EBCDIC code page, the handler can issue the
command:
EXEC CICS PUT CONTAINER(output) FROM(output_msg)

Because CHAR is not specified, no data conversion will be permitted. Because the
FROMCCSID option is not specified, the message data is taken to be in the
region’s EBCDIC code page.

To retrieve one of the messages in UTF8, the handler can issue the command:
EXEC CICS GET CONTAINER(input_msg) INTO(msg) INTOCCSID(utf8)

The INTOCCSID option is necessary to prevent automatic conversion of the data to

the region’s EBCDIC code page.

To return some output in UTF8, the server program can issue the command:
EXEC CICS PUT CONTAINER(output) FROM(output_msg) FROMCCSID(utf8)

The FROMCCSID option specifies that the message data is currently in UTF8
format. Because CHAR is not specified, no data conversion will be permitted.

Benefits of channels
The channel/container model has several advantages over the communication
areas (COMMAREAs) traditionally used by CICS programs to exchange data. For
example:
v Unlike COMMAREAs, channels are not limited in size to 32KB. There is no limit
to the number of containers that can be added to a channel, and the size of
individual containers is limited only by the amount of storage that you have
available.
CAUTION:
Take care not to create so many large containers that you limit the amount
of storage available to other applications.
v Because a channel can comprise multiple containers, it can be used to pass data
in a more structured way. In contrast, a COMMAREA is a monolithic block of
data.
v Unlike COMMAREAs, channels don’t require the programs that use them to
know the exact size of the data returned.
v A channel is a standard mechanism for exchanging data between CICS
programs. A channel can be passed on LINK, START, XCTL, and RETURN
commands. Distributed program link (DPL) is supported, and the transactions
started by START CHANNEL and RETURN TRANSID commands may be
remote.

Note: When a channel is to be passed to a remote program or transaction, be

aware that passing a large amount of data may affect performance. This is
particularly true if the local and remote regions are connected by an ISC,
rather than MRO, connection.
v Channels can be used by CICS application programs written in any of the
CICS-supported languages. For example, a Java client program on one CICS
region can use a channel to exchange data with a COBOL server program on a
back-end AOR.
v A server program can be written to handle multiple channels. It can, for example:
1. Discover, dynamically, the channel that it was invoked with

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 215
2. Browse the containers in the channel
3. Vary its processing according to the channel it’s been passed
v You can build “components” from sets of related programs invoked through one
or more channels.
v The loose coupling between clients and components permits easy evolution.
Clients and components can be upgraded at different times. For example, first a
component could be upgraded to handle a new channel, then the client program
upgraded (or a new client written) to use the new channel.
v The programmer is relieved of storage management concerns. CICS
automatically destroys containers (and their storage) when they go out of scope.
v The data conversion model used by channel applications is much simpler than
that used by COMMAREA applications. Also, whereas in COMMAREA
applications data conversion is controlled by the system programmer, in channel
applications it is controlled by the application programmer, using simple API
commands.
v Programmers with experience of CICS business transaction services (BTS) will
find it easy to use containers in non-BTS applications.
v Programs that use containers can be called from both channel and BTS
applications.
v Non-BTS applications that use containers can be migrated into full BTS
applications. (They form a migration route to BTS.)

Migrating from COMMAREAs to channels

Migration of existing functions

v CICS application programs that use traditional communications areas
(COMMAREAS) to exchange data continue to work as before.
v If you employ a user-written dynamic or distributed routing program for workload
management, rather than CICSPlex SM, you must modify your program to
handle the new values that it may be passed in the DYRTYPE field of the
DFHDYPDS communications area—see the Customization Guide.

Migration to the new function

This section describes how you can migrate several types of existing application to
use channels and containers rather than communication areas (COMMAREAs).

It‘s possible to replace a COMMAREA by a channel with a single container. While

this may seem the simplest way to move from COMMAREAs to channels and
containers, it‘s not good practice to do this. Because you‘re taking the time to
change your application programs to exploit this new function, you should
implement the “best practices” for channels and containers—see “Designing a
channel: best practices” on page 205. Channels have several advantages over
COMMAREAs (see “Benefits of channels” on page 215) and it pays to design your
channels to make the most of these improvements.

Migrating LINK commands that pass COMMAREAs

To migrate two programs which use a COMMAREA on a LINK command to
exchange a structure, change the instructions shown in Table 14 on page 217.

216 CICS TS for z/OS: CICS Application Programming Guide

Table 14. Migrating LINK commands that pass COMMAREAs
Program Before After
PROG1 EXEC CICS LINK PROGRAM(PROG2) EXEC CICS PUT CONTAINER(structure-name)
COMMAREA(structure) CHANNEL(channel-name) FROM(structure)
EXEC CICS LINK PROGRAM(PROG2)
.. CHANNEL(channel-name)
.
EXEC CICS GET CONTAINER(structure-name)
CHANNEL(channel-name) INTO(structure)
PROG2 EXEC CICS ADDRESS COMMAREA(structure-ptr) EXEC CICS GET CONTAINER(structure-name)
... INTO(structure)
RETURN ...
EXEC CICS PUT CONTAINER(structure-name)
FROM(structure)
RETURN

Note: In the COMMAREA example, PROG2, having put data in the COMMAREA,
has only to issue a RETURN command to return the data to PROG1. In the
channel example, to return data PROG2 must issue a PUT CONTAINER
command before the RETURN.

Migrating XCTL commands that pass COMMAREAs

To migrate two programs which use a COMMAREA on an XCTL command to pass
a structure, change the instructions shown in Table 15.
Table 15. Migrating XCTL commands that pass COMMAREAs
Program Before After
PROG1 EXEC CICS XCTL PROGRAM(PROG2) EXEC CICS PUT CONTAINER(structure-name)
COMMAREA(structure) CHANNEL(channel-name) FROM(structure)
EXEC CICS XCTL PROGRAM(PROG2)
.. CHANNEL(channel-name)
.

PROG2 EXEC CICS ADDRESS COMMAREA(structure-ptr) EXEC CICS GET CONTAINER(structure-name)

... INTO(structure)
...

Migrating pseudoconversational COMMAREAs on RETURN

commands
To migrate two programs which use COMMAREAs to exchange a structure as part
of a pseudoconversation, change the instructions shown in Table 16.
Table 16. Migrating pseudoconversational COMMAREAs on RETURN commands
Program Before After
PROG1 EXEC CICS RETURN TRANSID(PROG2) EXEC CICS PUT CONTAINER(structure-name)
COMMAREA(structure) CHANNEL(channel-name) FROM(structure)
EXEC CICS RETURN TRANSID(TRAN2)
CHANNEL(channel-name)
PROG2 EXEC CICS ADDRESS COMMAREA(structure-ptr) EXEC CICS GET CONTAINER(structure-name)
INTO(structure)

Chapter 14. Enhanced inter-program data transfer: channels as modern-day COMMAREAs 217
Migrating START data
To migrate two programs which use START data to exchange a structure, change
the instructions shown in Table 17.
Table 17. Migrating START data
Program Before After
PROG1 EXEC CICS START TRANSID(TRAN2) EXEC CICS PUT CONTAINER(structure-name)
FROM(structure) CHANNEL(channel-name) FROM(structure)
EXEC CICS START TRANSID(TRAN2)
CHANNEL(channel-name)
PROG2 EXEC CICS RETRIEVE INTO(structure) EXEC CICS GET CONTAINER(structure-name)
INTO(structure)

Note that the new version of PROG2 is the same as that in the
pseudoconversational example.

Migrating dynamically-routed applications

EXEC CICS LINK and EXEC CICS START commands, which can pass either
COMMAREAs or channels, can be dynamically routed.

When a LINK or START command passes a COMMAREA rather than a channel,

the routing program can, depending on the type of request, inspect or change the
COMMAREA‘s contents. For LINK requests and transactions started by
terminal-related START requests (which are handled by the dynamic routing
program) but not for non-terminal-related START requests (which are handled by
the distributed routing program) the routing program is given, in the DYRACMAA
field of its communication area, the address of the application‘s COMMAREA, and
can inspect and change its contents.

Note: The routing program‘s communication area is mapped by the DFHDYPDS

DSECT.

If you migrate a dynamically-routed EXEC CICS LINK or START command to use a

channel rather than a COMMAREA, the routing program is passed, in the
DYRCHANL field of DFHDYPDS, the name of the channel. Note that the routing
program is given the name of the channel, not its address, and so is unable to use
the DYRCHANL field to inspect or change the contents of the channel‘s containers.

If you are migrating a program to pass a channel rather than a COMMAREA, you
could use its existing COMMAREA structure to map DFHROUTE.

218 CICS TS for z/OS: CICS Application Programming Guide

Chapter 15. Affinity
CICS transactions and programs use many different techniques to pass data from
one to another. Some of these techniques require that the transactions or programs
exchanging data must execute in the same CICS region. This imposes restrictions
on the regions to which transactions and distributed program link (DPL) requests
can be dynamically routed. If transactions or programs exchange data in ways that
impose such restrictions, there is said to be an affinity among them.

Java
This guidance on affinity between transactions describes applications written
using the EXEC CICS API. However, many of the comments are equally valid
for Java applications and enterprise beans executing in a CICSplex. For
guidance on developing Java applications and enterprise beans, see Java
Applications in CICS.

Transactions, program-link requests, EXEC CICS START requests, CICS business

transaction services (BTS) activities, and enterprise bean method calls can all be
dynamically routed.

You can use a dynamic routing program to dynamically route:

v Transactions started from terminals
v Transactions started by eligible terminal-related EXEC CICS START commands
v Eligible CICS-to-CICS DPL requests
v Eligible program-link requests received from outside CICS.

You can use a distributed routing program to dynamically route:

v Eligible BTS processes and activities. (BTS is described in the CICS Business
Transaction Services manual.)
v Eligible non-terminal-related EXEC CICS START requests.

For detailed introductory information about dynamic and distributed routing, see the
CICS Intercommunication Guide.

Important
The following sections talk exclusively about affinities between transactions.
Keep in mind throughout the chapter that:
v Affinities can also exist between programs. (Although, strictly speaking, we
could say that it is the transactions associated with the programs that have
the affinity.) This may impose restrictions on the regions to which
program-link requests can be routed.
v The sections on safe, unsafe, and suspect programming techniques apply
to the routing of program-link and START requests, as well as to the routing
of transactions.

This chapter describes:

v “Types of affinity” on page 220
v “Programming techniques and affinity” on page 221
v “Safe programming to avoid affinity” on page 222
v “Unsafe programming for affinity” on page 227

© Copyright IBM Corp. 1989, 2005 219

v “Suspect programming for affinity” on page 234
v “Detecting inter-transaction affinities” on page 244
v “Duration and scope of inter-transaction affinities” on page 244

Types of affinity
There are two types of affinity that affect dynamic routing:
v Inter-transaction affinity
v Transaction-system affinity

Inter-transaction affinity
Transaction affinity among two or more CICS transactions is caused by the
transactions using techniques to pass information between one another, or to
synchronize activity between one another, in a way that requires the transactions to
execute in the same CICS region. This type of affinity is inter-transaction affinity,
where a set of transactions share a common resource and/or coordinate their
processing. Inter-transaction affinity, which imposes restrictions on the dynamic
routing of transactions, can occur in the following circumstances:
v One transaction terminates, leaving ‘state data’ in a place that a second
transaction can only access by running in the same CICS region as the first
transaction.
v One transaction creates data that a second transaction accesses while the first
transaction is still running. For this to work safely, the first transaction usually
waits on some event, which the second transaction posts when it has read the
data created by the first transaction. This technique requires that both
transactions are routed to the same CICS region.
v Two transactions synchronize, using an event control block (ECB) mechanism.
Because CICS has no function shipping support for this technique, this type of
affinity means the two transactions must be routed to the same CICS region.

Note: The same is true if two transactions synchronize, using an enqueue

(ENQ) mechanism, unless you have used appropriate ENQMODEL
resource definitions to give sysplex-wide scope to the ENQs. See the
CICS Resource Definition Guide .

Transaction-system affinity
There is another type of transaction affinity that is not an affinity among transactions
themselves. It is an affinity between a transaction and a particular CICS region,
where the transaction interrogates or changes the properties of that CICS
region—transaction-system affinity.

Transactions with affinity to a particular system, rather than another transaction, are
not eligible for dynamic routing. In general, they are transactions that use INQUIRE
and SET commands, or have some dependency on global user exit programs,
which also have an affinity with a particular CICS region.

Using INQUIRE and SET commands and global user exits

There is no remote (that is, function shipping) support for INQUIRE and SET
commands, nor is there a SYSID option on them, hence transactions using these
commands must be routed to the CICS regions that own the resources to which
they refer. In general, such transactions cannot be dynamically routed to any target
region, and therefore transactions that use INQUIRE and SET should be statically
routed.

220 CICS TS for z/OS: CICS Application Programming Guide

Global user exits running in different CICS regions cannot exchange data. It is
unlikely that user transactions pass data or parameters by means of user exits, but
if such transactions do exist, they must run in the same target region as the global
user exits.

Programming techniques and affinity

From the point of view of inter-transaction affinity in a dynamic or distributed routing
environment, the programming techniques used by your application programs can
be considered in three broad categories:
v Those techniques that are generally safe and do not cause inter-transaction
affinities
v Those techniques that are inherently unsafe
v Those techniques that are suspect in that they may, or may not, create affinities
depending on exactly how they are implemented

Safe techniques
The programming techniques in the generally safe category are:
v The use of the communication area (COMMAREA), supported by the CICS API
on a number of CICS commands. However, it is the COMMAREA option on the
CICS RETURN command only that is of interest in a dynamic or distributed
routing environment with regard to transaction affinity, because it is the
COMMAREA on a RETURN command that is passed to the next transaction in a
pseudoconversational transaction.
v The use of a TCT user area (TCTUA) that is optionally available for each
terminal defined to CICS.
v Synchronization or serialization of tasks using CICS commands:
– ENQ / DEQ,provided that you have used appropriate ENQMODEL resource
definitions to give sysplex-wide scope to the ENQs. See “Using ENQ and
DEQ commands with ENQMODEL resource definitions” on page 226 and the
CICS Resource Definition Guide for a description of ENQMODELs.
v The use of containers to pass data between CICS Business Transaction Services
(BTS) activities. Container data is saved in an RLS-enabled BTS VSAM file.

For more information about the COMMAREA and the TCTUA, see “Safe
programming to avoid affinity” on page 222.

Unsafe techniques
The programming techniques in the unsafe category are:
v The use of long-life shared storage:
– The common work area (CWA)
– GETMAIN SHARED storage
– Storage obtained by a LOAD PROGRAM HOLD
v The use of task-lifetime local storage shared by synchronized tasks
It is possible for one task to pass the address of some task-lifetime storage to
another task.
It may be safe for the receiving task to use the passed address, provided the
owning task does not terminate. It is possible, but ill-advised, to use a CICS
task-synchronization technique to allow the receiving task to prevent the sending
task from terminating (or freeing the storage in some other way) before the
receiver has finished with the address. However, such designs are not robust
because there is a danger of the sending task being purged by some outside
agency.

Chapter 15. Affinity 221

See “Sharing task-lifetime storage” on page 230 for more details.
v Synchronization or serialization of tasks using CICS commands:
– WAIT EVENT / WAIT EXTERNAL / WAITCICS
– ENQ / DEQ,unless you have used appropriate ENQMODEL resource
definitions to give sysplex-wide scope to the ENQs. See “Using ENQ and
DEQ commands with ENQMODEL resource definitions” on page 226 and the
CICS Resource Definition Guide for a description of ENQMODELs.

For more information about unsafe programming techniques, see “Unsafe

programming for affinity” on page 227.

Suspect techniques
Some programming techniques may, or may not, create affinity depending on
exactly how they are implemented. A good example is the use of temporary
storage. Application programs using techniques in this category must be checked to
determine whether they work without restrictions in a dynamic or distributed routing
environment. The programming techniques in the suspect category are:
v The use of temporary storage queues with restrictive naming conventions
v Transient data queues and the use of trigger levels
v Synchronization or serialization of tasks using CICS commands:
– RETRIEVE WAIT / START
– START / CANCEL REQID
– DELAY / CANCEL REQID
– POST / CANCEL REQID
v INQUIRE and SET commands and global user exits

For more information about suspect programming techniques, see “Suspect

programming for affinity” on page 234.

Recommendations
The best way to deal with inter-transaction affinity is to avoid creating
inter-transaction affinity in the first place.

Where it is not possible to avoid affinities, you should:

v Make the inter-transaction affinity easily recognizable, by using appropriate
naming conventions, and
v Keep the lifetime of the affinities as short as possible.

Even if you could avoid inter-transaction affinities by changing your application

programs, this is not absolutely necessary provided you include logic in your
dynamic and distributed routing programs to cope with the affinities. Finally, you can
statically route the affected transactions.

Safe programming to avoid affinity

Some techniques for passing data between transactions are generally safe in that
they do not create inter-transaction affinity. These involve the use of a
communication area (COMMAREA), a terminal control table user area (TCTUA), or
BTS containers.

However, to remain free from affinity, COMMAREAs, TCTUAs, and BTS containers
must not contain addresses. Generally the storage referenced by such addresses

222 CICS TS for z/OS: CICS Application Programming Guide

would have to be long-life storage, the use of which is an unsafe programming
technique in a dynamic transaction routing environment.

The COMMAREA
The use of the COMMAREA option on the RETURN command is the principal
example of a safe programming technique that you can use to pass data between
successive transactions in a CICS pseudoconversational transaction. CICS treats
the COMMAREA as a special form of user storage, even though it is CICS that
issues the GETMAIN and FREEMAIN requests for the storage, and not the
application program.

CICS ensures that the contents of the COMMAREA specified on a RETURN

command are always made available to the first program in the next transaction.
This is true even when the sending and receiving transactions execute in different
target regions. In a pseudoconversation, regardless of the target region to which a
dynamic routing program chooses to route the next transaction, CICS ensures the
COMMAREA specified on the previous RETURN command is made available in the
target region. This is illustrated in Figure 52 on page 224.

Some general characteristics of a COMMAREA are:

v Processor overhead is low.
v It is not recoverable.
v The length of a COMMAREA on a RETURN command can vary from transaction
to transaction, up to a theoretical upper limit of 32 763 bytes. (However to be
safe, you should not exceed 24KB (1KB = 1024 bytes), as recommended in the
Application Programming Reference manual, because of a number of factors that
can reduce the limit from the theoretical maximum.)
v CICS holds a COMMAREA in CICS main storage until the terminal user
responds with the next transaction. This may be an important consideration if you
are using large COMMAREAs, because the number of COMMAREAs held by
CICS relates to terminal usage, and not to the maximum number of tasks in a
region at any one time.
v A COMMAREA is available only to the first program in the next transaction,
unless that program explicitly passes the data to another program or a
succeeding transaction.

Chapter 15. Affinity 223

TOR1
(1) Using DTR,
routes TRN1
to AOR1.

(2) Using DTR,

routes TRN2
to AOR2

AOR1 AOR2

Executes TRN1 Executes TRN2

TRN1 terminates TRN2 has access

with to the COMMAREA
EXEC CICS RETURN data passed by
COMMAREA(DATA) TRN1
TRANSID(TRN2)

Figure 52. The use of a COMMAREA by a pseudoconversation in a dynamic transaction

routing environment

The COMMAREA used in a pseudoconversational transaction, as shown in

Figure 52, can be passed from transaction to transaction across a CICSplex, and,
provided the COMMAREA contains only data and not addresses of storage areas,
no inter-transaction affinity is created.

The TCTUA
The TCTUA is an optional extension to the terminal control table entry (TCTTE),
each entry specifying whether the extension is present, and its length. You specify
that you want a TCTUA associated with a terminal by defining its length on the
USERAREALEN parameter of a TYPETERM resource definition. This means that
the TCTUAs are of fixed length for all the terminals created using the same
TYPETERM definition.

A terminal control table user area (TCTUA) is safe to use in a dynamic transaction
routing environment as a means of passing data between successive transactions
in a pseudoconversational transaction. Like the COMMAREA, the TCTUA is always
accessible to transactions initiated at a user terminal, even when the transactions in
a pseudoconversation are routed to different target regions. This is illustrated in
Figure 53 on page 225. Some other general characteristics of TCTUAs are:
v Minimal processor overhead (only one CICS command is needed to obtain the
address).
v It is not recoverable.
v The length is fixed for the group of terminals associated with a given TYPETERM
definition. It is suitable only for small amounts of data, the maximum size allowed
being 255 bytes.
v If the terminal is autoinstalled, the TCTUA lasts as long as the TCTTE, the
retention of which is determined by the AILDELAY system initialization parameter.
The TCTTE, and therefore any associated TCTUA, is deleted when the
AILDELAY interval expires after a session between CICS and a terminal is
ended.
If the terminal is defined to CICS by an explicit terminal definition, the TCTTE
and its associated TCTUA are created when the terminal is installed and remain
until the next initial or cold start of CICS.

224 CICS TS for z/OS: CICS Application Programming Guide

Note that the TCTUA is available to a dynamic routing environment in the routing
region as well as application programs in the target region. It can be used store
information relating to the dynamic routing of a transaction. For example, you can
use the TCTUA to store the name of the selected target region to which a
transaction is routed.

TOR1
(1) Using DTR,
routes TRN1
to AOR1.

(2) Using DTR,

routes TRN2
to AOR2

AOR1 AOR2

Executes TRN1 Executes TRN2

which: which:
(1) Gets TCTUA (1) Gets address
address of the TCTUA
(2) Stores data
in TCTUA (2) Accesses the
for next data stored
transaction by TRN1.
(3) Ends with
EXEC CICS RETURN
TRANSID(TRN2)

Figure 53. The use of a TCTUA by a pseudoconversation in a dynamic routing environment

Using the TCTUA in an unsafe way

The EXEC CICS ADDRESS TCTUA(ptr-ref) provides direct addressability to the
TCTUA, and this is how each task requiring access to a TCTUA should obtain the
TCTUA address. If tasks attempt to pass the address of their TCTUAs in some
other way, such as in a temporary storage queue, or to use the TCTUA itself to
pass addresses of other storage areas, the TCTUA ceases to provide a safe
programming technique for use in a dynamic transaction routing environment.

It is also possible for a task to obtain the TCTUA of a principal facility other than its
own, by issuing an INQUIRE TERMINAL command that names the terminal
associated with another task (the INQUIRE TERMINAL command returns the
TCTUA address of the specified terminal). Using the TCTUA address of a terminal
other than a task’s own principal facility is another example an unsafe use of the
TCTUA facility. Depending on the circumstances, particularly in a dynamic routing
environment , the TCTUA of a terminal that is not the inquiring task’s principal
facility could be deleted after the address has been obtained. For example, in an
target region, an INQUIRE TERMINAL command could return the TCTUA address
associated with a surrogate terminal that is running a dynamically routed
transaction. If the next transaction from the terminal is routed to a different target
region, the TCTUA address ceases to be valid.

Chapter 15. Affinity 225

Using ENQ and DEQ commands with ENQMODEL resource definitions
The ENQ and DEQ commands are used to serialize access to a shared resource.
In earlier releases of CICS, these commands were limited to the scope of CICS
tasks running in the same region, and could not be used to serialize access to a
resource shared by tasks in different regions. Now, provided that the ENQs and
DEQs are supported by appropriate ENQMODEL resource definitions (see the CICS
Resource Definition Guide for a description of ENQMODELs) they can have
sysplex-wide scope.

This is primarily of interest to the system programmer who will determine

transaction routing decisions, but application programmers should be aware of the
advantages now available.

Overview of sysplex enqueue and dequeue

Changes to the CICS enqueue/dequeue function extend the CICS application
programming interface to provide an enqueue mechanism that serializes access to
a named resource across a specified set of CICS regions operating within a
sysplex. This applies equally to a CICSplex within a single MVS image and to a
CICSplex that resides in more than one MVS. (Note that sysplex-wide enqueue is
supported only for a resource, and not for an enqueue on an address.)

Local enqueues within a single CICS region are managed within the CICS address
space. Sysplex-wide enqueues that affect more than one CICS region are managed
by Global Resource Services (GRS). The main points of the changes to the CICS
enqueue/dequeue mechanism are as follows:
v Sysplex enqueue and dequeue expands the scope of an EXEC CICS ENQ|DEQ
command from region to sysplex, by introducing a new CICS resource definition
type, ENQMODEL, to define resource names that are to be sysplex-wide.
v ENQSCOPE, an attribute of the ENQMODEL resource definition, defines the set
of regions that share the same enqueue scope.
v When an EXEC CICS ENQ (or DEQ) command is issued for a resource whose
name matches that of an installed ENQMODEL resource definition, CICS checks
the value of the ENQSCOPE attribute to determine whether the scope is local or
sysplex-wide, as follows:
– If the ENQSCOPE attribute is left blank (the default value), CICS treats the
ENQ|DEQ as local to the issuing CICS region.
– If the ENQSCOPE is non-blank, CICS treats the ENQ|DEQ as sysplex-wide,
and passes a queue name and the resource name to GRS to manage the
enqueue. The resource name is as specified on the EXEC CICS ENQ|DEQ
command, and the queue name is made up by prefixing the 4-character
ENQSCOPE with the letters DFHE.
v The CICS regions that need to use sysplex-wide enqueue/dequeue function must
all have the required ENQMODELs defined and installed.
The recommended way to ensure this is for the CICS regions to share a CSD,
and for the initialization group lists to include the same ENQMODEL groups.

Existing applications can use sysplex enqueues simply by defining appropriate

ENQMODELs, without any change to the application programs.

226 CICS TS for z/OS: CICS Application Programming Guide

Benefits
Sysplex enqueue provides the following benefits:
v Eliminates one of the most common causes of inter-transaction affinity.
v Enables better exploitation of a parallel sysplex providing better
price/performance, capacity, and availability.
v Reduces the need for inter-transaction affinity rules in dynamic and distributed
routing programs thereby lowering the systems management cost of exploiting
parallel sysplex.
v Enables serialization of concurrent updates to shared temporary storage queues,
performed by multiple CICS tasks across the sysplex.
v Makes it possible to prevent interleaving of records written by concurrent tasks in
different CICS regions to a remote transient data queue.
v Allows the single-threading and synchronization of tasks across the sysplex. It is
not designed for the locking of recoverable resources.

BTS containers
A container is owned by a BTS activity. Containers cannot be used outside of an
activity; for more information, see the CICS Business Transaction Services manual .
A container may be used to pass data between BTS activities or between different
activations of the same activity. An activity uses GET and PUT container to update
the container’s contents. CICS ensures that the appropriate containers are available
to an activity by saving all the information (including containers) associated with a
BTS activity in an RLS-enabled VSAM file. For this reason, note that a BTS
environment cannot extend outside a sysplex (see CICS Business Transaction
Services), but you can use dynamic routing within a sysplex passing data in
containers.

Some general characteristics of containers are:

v An activity may own any number of containers; you are not limited to one.
v There is no size restriction.
v They are recoverable.
v They exist in main storage only while the associated activity is executing.
Otherwise they are held on disk. Therefore, you do not need to be overly
concerned with their storage requirements, unlike terminal COMMAREAs.

Unsafe programming for affinity

Some CICS application programming techniques, notably those that pass, or obtain,
addresses to shared storage, create an affinity between transactions.

The programming techniques that are generally unsafe are described in the
following sections.

Using the common work area

The CWA in a CICS region is created (optionally) during CICS initialization, exists
until CICS terminates, and is not recovered on a CICS restart (warm or
emergency). The ADDRESS CWA(ptr-ref) command provides direct addressability
to the CWA.

Chapter 15. Affinity 227

A good example of how the use of long-life shared storage such as the CWA can
create affinity is when one task stores data in the CWA, and a later task reads the
data from it. Clearly, the task retrieving the data must run in the same target region
as the task that stored the data, or it references a completely different storage area
in a different address space. This restricts the workload balancing capability of the
dynamic or distributed routing program, as shown in Figure 54.

TOR
If the dynamic routing program
DTR routes TRN2 to AOR3 as shown,
program TRN2 will fail to access the
data stored for it by TRN1.

AOR1 AOR2 AOR3

CWA CWA CWA

TRN1 writes TRN2 fails

data to CWA to read the
intended TRN1 data
for TRN2 from the CWA

CWA

Figure 54. Illustration of inter-transaction affinity created by use of the CWA. The dynamic
routing program needs to be aware of this CWA affinity, and ensure it routes TRN2 to the
same target region as TRN1.

However, if the CWA contains read-only data, and this data is replicated in more
than one target region, it is possible to use the CWA and continue to have the full
benefits of dynamic routing. For example, you can run a program during the
post-initialization phase of CICS startup (a PLTPI program) that loads the CWA with
read-only data in each of a number of selected target regions. In this way, all
transactions routed to target regions loaded with the same CWA data have equal
access to the data, regardless of which of the target regions to which the
transactions are routed. With CICS subsystem storage protection, you can ensure
the read-only integrity of the CWA data by requesting the CWA from CICS-key
storage, and define all the programs that read the CWA to execute in user key.

Using GETMAIN SHARED storage

Shared storage is allocated by a GETMAIN SHARED command, and remains
allocated until explicitly freed by the same, or by a different, task. Shared storage
can be used to exchange data between any CICS tasks that run during the lifetime
of the shared storage. Transactions designed in this way must execute in the same
CICS region to work correctly. The dynamic or distributed routing program should
ensure that transactions using shared storage are routed to the same target region.

Figure 55 on page 229 illustrates the use of shared storage.

228 CICS TS for z/OS: CICS Application Programming Guide

TOR In this example, the TOR
must route TRN2 to AOR1,
DTR because it needs access
program to shared storage obtained
by TRN1 in that region.

AOR1 AOR2

Executes TRN1
which:

(1) GETMAINs some

SHARED storage
(2) Stores data in
shared storage
(3) WRITEs address
to a TS queue
Executes TRN2
Terminates which:
(leaving shared
storage still (1) READs address
allocated) from TS queue
(2) Reads data from
shared storage
(3) FREEMAINs the
shared storage

Terminates

Figure 55. Illustration of inter-transaction affinity created by use of shared storage. The
dynamic transaction routing program needs to be aware of this affinity, and ensure it routes
TRN2 to the same target region as TRN1.

If the two transactions shown in Figure 55 are parts of a pseudoconversational

transaction, the use of shared storage should be replaced by a COMMAREA
(provided that the amount of storage fits within the COMMAREA size limits).

Using the LOAD PROGRAM HOLD command

A program (or table) that CICS loads in response to a LOAD PROGRAM HOLD
command remains in directly addressable storage until explicitly released by the
same, or by a different, task. Any CICS tasks that run while the loaded program
(table) is held in storage can use the loaded program’s storage to exchange data,
provided that:
v The program is not loaded into read-only storage, or
v The program is not defined to CICS with RELOAD(YES)

Although you could use a temporary storage queue to make the address of the
loaded program’s storage available to other tasks, the more usual method would be
for other tasks to issue a LOAD PROGRAM command also, with the SET(ptr_ref)
option so that CICS can return the address of the held program.

The nature of the affinity caused by the use of the LOAD PROGRAM HOLD
command is virtually identical to that caused by the use of GETMAIN SHARED
storage (see Figure 55 and Figure 56 on page 230), and the same rule applies: to
preserve the application design, the dynamic or distributed routing program must

Chapter 15. Affinity 229

ensure that all transactions that use the address of the loaded program (or table)
are routed to the same target region.

TOR
In this example, the TOR
DTR must route to AOR1 all other
program transactions that require
access to the program (table)
loaded by TRN1.

AOR1 AOR2

Executes TRN1
which:

(1) Issues LOAD

PROGRAM HOLD
command.

(2) Terminates. Executes other

transactions
that:

(1) Issue LOAD

PROGRAM with
SET option.

(2) Read data from

the loaded
program (table)

(3) Terminate.

Figure 56. Illustration of inter-transaction affinity created by use of LOAD PROGRAM HOLD.
The dynamic routing program needs to be aware of this affinity, and ensure it routes TRN2 to
the same target region as TRN1.

Note: This rule applies also to programs defined with the RESIDENT option on the
resource definition for the loaded program (whether or not the HOLD option
is specified on the LOAD command). However, regardless of affinity
considerations, it is unsafe to use the RESIDENT option to enable
transactions to share data, because programs defined with RESIDENT are
subject to SET PROGRAM(program_name) NEWCOPY commands, and can
therefore be changed.

The rule also applies to a non-resident, non-held, loaded program where the
communicating tasks are synchronized.

Sharing task-lifetime storage

The use of any task-lifetime storage belonging to one task can be shared with
another task, provided the owning task can pass the address to the other task in
the same CICS address space. This technique creates an affinity among the
communicating tasks, and requires that any task retrieving and using the passed
address must execute in the same target region as the task owning the task-lifetime
storage.

230 CICS TS for z/OS: CICS Application Programming Guide

For example, it is possible to use a temporary storage queue to pass the address of
a PL/I automatic variable, or the address of a COBOL working-storage structure
(see Figure 57 for an example).

TOR

DTR
program

AOR

TRN1

1. Stores the address

of task-lifetime
storage (in TS
queue) for TRN2

2. Suspends until TRN2 TRN2

completes
. 1. Reads address from TS
(waiting) queue.
. 2. Accesses the storage.
. 3. Resumes TRN1.
3. Continues.

Figure 57. Illustration of inter-transaction affinity created by use of task-lifetime storage. TRN2
must execute in the same target region as TRN1. Also, TRN1 must not terminate until TRN2
has finished using its task-lifetime storage.

For two tasks to share task-lifetime storage belonging to one of them requires that
the tasks are synchronized in some way. See Table 18 for commands that provide
ways of suspending and resuming a task that passes the address of its local
storage.
Table 18. Methods for suspending and resuming (synchronizing) tasks
Suspending operation Resuming operation
WAIT EVENT, WAIT EXTERNAL, WAITCICS POST
RETRIEVE WAIT START
DELAY CANCEL
POST CANCEL
START CANCEL
ENQ DEQ

Some of these techniques themselves require that the transactions using them must
execute in the same target region, and these are discussed later in this chapter.
However, even in those cases where tasks running in different target regions can
be synchronized, it is not safe to pass the address of task-lifetime storage from one
to the other. Even without dynamic routing, designs that are based on the
synchronization techniques shown in Table 18 are fundamentally unsafe because it
is possible that the storage-owning task could be purged.

Chapter 15. Affinity 231

Notes:
1. Using synchronization techniques, such as RETRIEVE WAIT/START, to allow
sharing of task-lifetime storage is unsafe in CICS Version 2 because the task
issuing, for example, the RETRIEVE WAIT could be purged by a CEMT SET
TASK(...) PURGE command. In CICS/ESA Version 3 and later, the SPURGE
parameter on the transaction definition could be used to protect the first task,
but even so the design is not recommended.
2. No inter-transaction affinity is caused in those cases where the task sharing
another task’s task-lifetime storage is started by an START command, except
when the START command is function-shipped or routed to a remote system.

Using the WAIT EVENT command

The WAIT EVENT command is used to synchronize a task with the completion of
an event performed by some other CICS or MVS task.

The completion of the event is signalled (posted) by the setting of a bit pattern into
the event control block (ECB). Both the waiting task and the posting task must have
direct addressability to the ECB, hence both tasks must execute in the same target
region. The use of a temporary storage queue is one way that the waiting task can
pass the address of the ECB to another task.

This synchronization technique is illustrated in Figure 58.

TOR

DTR
program

AOR

TRN1

1. Stores the address

of ECB in temporary
storage queue for
TRN2
2. Suspends with WAIT TRN2
EVENT ECADDR(ptr-ref)
. 1. At end of processing,
. (completion of event)
(waiting) reads address of ECB
. from TS queue.
. 2. Posts ECB (by MVS POST
. or 'hand-posted')
. 3. Returns control to CICS
3. Resumed by CICS

Figure 58. Illustration of inter-transaction affinity created by use of WAIT EXTERNAL

command. TRN2 must execute in the same target region as TRN1.

If TRN2 shown in Figure 58 executed in a different target region from TRN1, the
value of ptr-ref would be invalid, the post operation would have unpredictable
results, and the waiting task would never be resumed. For this reason, a dynamic

232 CICS TS for z/OS: CICS Application Programming Guide

or distributed routing program must ensure that a posting task executes in the same
target region as the waiting task to preserve the application design. The same
considerations apply to the use of WAIT EXTERNAL and WAITCICS commands for
synchronizing tasks.

Using ENQ and DEQ commands without ENQMODEL resource

definitions
The ENQ and DEQ commands are used to serialize access to a shared resource.
These commands only work for CICS tasks running in the same region, and cannot
be used to serialize access to a resource shared by tasks in different regions,
unless they are supported by appropriate ENQMODEL resource definitions so that
they have sysplex-wide scope.See “Using ENQ and DEQ commands with
ENQMODEL resource definitions” on page 226 and the CICS Resource Definition
Guide for a description of ENQMODELs.

Note that any ENQ that does not specify the LENGTH option is treated as an
enqueue on an address and therefore has only local scope.The use of ENQ and
DEQ for serialization (without ENQMODEL definitions to give sysplex-wide scope) is
illustrated in Figure 59.

TOR

DTR
program

AOR

TRN1

1. Issues ENQ command

on resource name TRN2
of shared resource
1. Issues ENQ command on
2. Modifies or uses resource name of shared
shared resource resource
.
. 2. Suspended by CICS while
resource in use by TRN1
3. Issues DEQ command
on shared resource. 3. Resumed by CICS when
resource free

Figure 59. Illustration of inter-transaction affinity created by use of ENQ/DEQ commands.

TRN2 must execute in the same target region as TRN1.

If TRN2 shown in Figure 59 executed in a different target region from TRN1, TRN2
would not be suspended while TRN1 accessed the shared resource. For this
reason, a dynamic or distributed routing program must ensure that all tasks that
enqueue on a given resource name must execute in the same target region to
preserve the application design. TRN2 would, of course, be serialized with other
CICS tasks that issue ENQ commands on the same resource name in its target
region.

Chapter 15. Affinity 233

Suspect programming for affinity
Some CICS application programming techniques may create an affinity between
transactions depending on how they are implemented.

The programming techniques that may be suspect are described in the following
sections.

Using temporary storage

CICS application programs commonly use temporary storage (TS) queues to hold
temporary application data, and to act as scratch pads.

Sometimes a TS queue is used to pass data between application programs that

execute under one instance of a transaction (for example, between programs that
pass control by a LINK or XCTL command in a multi-program transaction). Such
use of a TS queue requires that the queue exists only for the lifetime of the
transaction instance, and therefore it does not need to be shared between different
target regions, because a transaction instance executes in one, and only one, target
region.

Note: This latter statement is not strictly true in the case of a multi-program
transaction, where one of the programs is linked by a distributed program
link command and the linked-to program resides in a remote system. In this
case, the program linked by a DPL command runs under another CICS task
in the remote region. The recommended method for passing data to a DPL
program is by a COMMAREA, but if a TS queue is used for passing data in
a DPL application, the queue must be shared between the two regions.

Sometimes a TS queue holds information that is specific to the target region, or

holds read-only data. In this case the TS queue can be replicated in each target
region, and no sharing of data between target regions is necessary.

However, in many cases a TS queue is used to pass data between transactions, in

which case the queue must be globally accessible to enable the transactions using
the queue to run in any dynamically selected target region. It is possible to make a
temporary storage queue globally accessible by function shipping TS requests to a
queue-owning region (QOR), provided the TS queue can be defined as remote.
Shared queues are defined by using a temporary storage pool in a coupling facility.
Shared temporary storage applies only to non-recoverable queues. You can make
queues in auxiliary storage recoverable, but not queues in main storage.

In a pseudoconversational transaction, you can change the program to use a

COMMAREA to pass data between the phases of the conversation. However, using
temporary storage data-sharing avoids inter-transaction affinity by being able to use
dynamic routing to any target region. Shared temporary storage queue requests for
specific SYSIDs are routed in the same way as remote queue requests. The SYSID
value defined to shared TS pools is TST TYPE=SHARED.

The methods for specifying TS pool make it easy to migrate queues from a QOR to
a TS data-sharing pool. You can use the temporary storage global user exit,
XTSEREQ, to modify the SYSID on a TS request so that it references a TS
data-sharing pool. Figure 60 shows four AORs that are using the same TST
(TST=XX). The SYSIDNT option on the TST TYPE=SHARED macro maps
temporary storage requests to a pool of shared TS queues called DFHXQTS1. You
should define DFHXQTS1 in the poolname parameter of the JCL to start up the TS

234 CICS TS for z/OS: CICS Application Programming Guide

data sharing server DFHXQMN. See the CICS System Definition Guide for more
information about setting up a data sharing server.

TOR

DTR
program

DFHTSTXX

Prefix| Sysid

AAAA* CICQ
AOR1 AOR2 AOR3 AOR4 ABCD* CICQ
XXXX* CICQ
TST=XX TST=XX TST=XX TST=XX ZZZZ* CICQ

Sysid Pool

CICQ DFHXQTS1

DFHXQMN
TS Server

Coupling
Facility

Figure 60. Example of the use of the temporary storage data-sharing server

Naming conventions for remote queues

To define a queue as remote you must include an entry for the queue in a
temporary storage table (TST), or use an appropriate TSMODEL. TS queue names
are frequently generated dynamically, but they can also be unique fixed names.
v The TST naming convention allows for dynamic names by accepting generic
names formed by a constant prefix, to which a CICS application program can
add a variable suffix. (Generic names are formed from the leading characters of
the 8-character queue names and can be up to seven characters long. Names in
a TST entry using all eight characters specify unique TS queues.)
v The names of TS queues defined by TSMODEL resource definitions may have a
prefix of up to 16 characters (using a specified set of character) if defined by the
Prefix or Remoteprefix option, or of up to 32 characters (using any hexadecimal
string) if defined by the XPrefix or XRemoteprefix option. The CICS Resource
Definition Guide has more information about Prefix, Remoteprefix, XPrefix and
XRemoteprefix.

The usual convention is a 4-character prefix (for example, the transaction identifier)
followed by a 4-character terminal identifier as the suffix. This generates queue
names that are unique for a given terminal. Such generic queue names can be
defined easily as remote queues that are owned, for example, by:
v A QOR (thus avoiding transaction affinity problems)
v Shared queues residing in temporary storage data-sharing queue pools
v Remote queues that are owned by an target region, or in a temporary storage
data-sharing queue pool

Chapter 15. Affinity 235

Remote queues and shared queues can be defined in the same way for application
programs, but requests for specific SYSIDs are routed to a temporary storage data
server by means of TST TYPE=SHARED. However, if the naming convention for
dynamically named queues does not conform to this rule, the queue cannot be
defined as remote, and all transactions that access the queue must be routed to the
target region where the queue was created. Furthermore, a TS queue name cannot
be changed from a local to a remote queue name using the global user exits for TS
requests.

See Figure 61 for an illustration of the use of a remote queue-owning region.

TOR

DTR
program

DFHTSTXX

Prefix Sysid
AOR1 AOR2 AOR3 AOR4
AAAA* CICQ
TST=XX TST=XX TST=XX TST=XX ABCD* CICQ
XXXX* CICQ
ZZZZ* CICQ

ROR

Figure 61. Using remote queues to avoid inter-transaction affinity relating to temporary
storage. This example shows a combined file-owning and queue-owning region. Separate
regions can be used, but these require special care during recovery operations because of
‘in-doubt’ windows that can occur when recovering data managed independently by file
control and temporary storage control.

Exception conditions for globally accessible queues

When you eliminate inter-transaction affinity relating to TS queues by the use of a
global QOR, you must also take care to review exception condition handling. This is
because some exception conditions can occur that previously were not possible
when the transactions and the queue were local in the same region. This situation
arises because the target region and QOR can fail independently, causing
circumstances where:
v The queue already exists, because only the target region failed while the QOR
continued.
v The queue is not found, because only the QOR failed while the target region
continued.

236 CICS TS for z/OS: CICS Application Programming Guide

Using transient data
Another form of data queue that CICS application programs commonly use is the
transient data queue (TD). The dynamic transaction routing considerations for TD
queues have much in common with those for temporary storage. To enable
transactions that use a TD queue that needs to be shared, to be dynamically routed
to an target region, you must ensure that the TD queues are globally accessible.

All transient data queues must be defined to CICS, and must be installed before the
resources become available to a CICS region. These definitions can be changed to
support a remote transient data queue-owning region (QOR).

However, there is a restriction for TD queues that use the trigger function. The
transaction to be invoked when the trigger level is reached must be defined as a
local transaction in the region where the queue resides (in the QOR). Thus the
trigger transaction must execute in the QOR. However, any terminal associated with
the queue need not be defined as a local terminal in the QOR. This does not create
an inter-transaction affinity.

Figure 62 illustrates the use of a remote transient data queue-owning region.

TOR

DTR
program

TDQ defn.

Queue Syst.
AOR1 AOR2 AOR3 AOR4
AAAA CICQ
ABCD CICQ
XXXX CICQ
ZZZZ CICQ

TDQ definition

Queue Trig. Tran. Term.

FOR QOR
(CICQ) AAAA nn BBBB Tnnn
ABCD nn CCCC Pnnn
XXXX
ZZZZ

Figure 62. Using remote queues to avoid inter-transaction affinity relating to transient data.
The transient data queue definitions installed in the target regions are defined as owned by
the QOR (CICQ). All the transient data queue definitions installed in the QOR are local, some
with trigger levels.

Exception conditions for globally accessible queues

When you eliminate inter-transaction affinity relating to TD queues by the use of a
global QOR, there should not be any new exception conditions (other than
SYSIDERR if there is a system definition error or failure).

Chapter 15. Affinity 237

Using the RETRIEVE WAIT and START commands
The use of some synchronization techniques permit the sharing of task-lifetime
storage between two synchronized tasks. For example, the RETRIEVE WAIT and
START commands could be used for this purpose, as illustrated in Figure 63.

In this example, TRN1 is designed to retrieve data from an asynchronous task,

TRN2, and therefore must wait until TRN2 makes the data available. Note that for
this mechanism to work, TRN1 must be a terminal-related transaction.

The steps are as follows:

1. TRN1 writes data to a TS queue, containing its TRANSID and TERMID.
2. To cause itself to suspend, TRN1 issues a RETRIEVE WAIT command, which
causes CICS to suspend the task until the RETRIEVE can be satisfied, which is
not until TRN2 issues a START command with data passed by the FROM
parameter.
3. However, TRN2 can only issue a START command to resume TRN1 if it knows
the TRANSID and TERMID of the suspended task (TRN1 in our example). Thus
it reads the TS queue to obtain the information written by TRN1. Using a
temporary storage queue is one way that this information can be passed by the
suspending task.
4. Using the information from the TS queue, TRN2 issues the START command for
TRN1, causing CICS to resume TRN1 by satisfying the outstanding RETRIEVE
WAIT.

TOR

DTR
program

AOR

TRN1

1. Stores its TRANSID

and TERMID in a TS
queue for TRN2

2. Suspends by issuing TRN2

a RETRIEVE WAIT
. 1. Reads TRANSID & TERMID
. of TRN1 from TS queue
(suspended) .
. (process)
. .
3. Resumes TRN1 by issuing
3. Resumes. START with FROM option.

Figure 63. Illustration of task synchronization using RETRIEVE WAIT and START commands

238 CICS TS for z/OS: CICS Application Programming Guide

In the example of task synchronization using RETRIEVE WAIT and START
commands shown in Figure 63 on page 238, the START command that satisfies the
RETRIEVE WAIT must:
v Be issued in same target region as the transaction (TRN1 in our example)
issuing the RETRIEVE WAIT command, or
v Specify the SYSID of the target region where the RETRIEVE WAIT command
was executed, or
v Specify a TRANSID (TRN1 in our example) that is defined as a remote
transaction residing on the target region that executed the RETRIEVE WAIT
command.

An application design based on the remote TRANSID technique only works for two
target regions. An application design using the SYSID option on the START
command only works for multiple target regions if all target regions have
connections to all other target regions (which may not be desirable). In either case,
the application programs need to be modified: there is no acceptable way to use
this programming technique in a dynamic or distributed routing program except by
imposing restrictions on the routing program. In general, this means that the
dynamic or distributed routing program has to ensure that TRN2 has to execute in
the same region as TRN1 to preserve the application design.

Using the START and CANCEL REQID commands

Using this CICS application programming technique, one transaction issues a
START command to start another transaction after a specified interval. Another
transaction (not the one requested on the START command) determines that it is no
longer necessary to run the requested transaction, (which is identified by the
REQID parameter) and cancels the START request. Note that the cancel is only
effective if the specified interval has not yet expired.

A temporary storage queue is one way that the REQID can be passed from task to
task.

Note: To use this technique, the CANCEL command must specify the REQID
option, but the START command need not. This is because, provided the
NOCHECK option is not specified on the START command, CICS generates
a REQID for the request and stores it in the EXEC interface block (EIB) in
field EIBREQID.

Figure 64 on page 240 illustrates this programming technique.

Chapter 15. Affinity 239

TOR

DTR
program

AOR

TRN1

1. Starts TRNX and

obtains the REQID

2. Writes the REQID for

the START request to
a TS queue

3. Terminates.
(suspended)

TRN2

1. Reads REQID from TS

2. Cancels TRNX using REQID

Figure 64. Illustration of the use of the START and CANCEL REQID commands

Using this application programming technique, the CANCEL command that cancels
the START request must:
v Be issued in same target region that the START command was executed in, or
v Specify the SYSID of the target region where the START command was
executed, or
v Specify a TRANSID (TRNX in our example) that is defined as a remote
transaction residing on the target region where the START command was
executed.

Note: A START command is not necessarily executed in the same region as the
application program issuing the command. It can be function shipped (or, in
the case of a non-terminal-related START, routed) and executed in a different
CICS region. The above rules apply to the region where the START
command is finally executed.

An application design based on the remote TRANSID technique only works for two
target regions. An application design using the SYSID option on the cancel
command only works for multiple target regions if all target regions have
connections to all other target regions. In either case, the application programs
need to be modified: there is no acceptable way to use this programming technique
in a dynamic or distributed routing program except by imposing restrictions on the
routing program.

In general, this means that the dynamic or distributed routing program has to
ensure that TRN2 executes in the same region as TRN1 to preserve the application
design, and also that TRNX is defined as a local transaction in the same region.

240 CICS TS for z/OS: CICS Application Programming Guide

Using the DELAY and CANCEL REQID commands
Using this CICS application programming technique, one task can resume another
task that has been suspended by a DELAY command.A DELAY request can only be
cancelled by a different task from the one issuing the DELAY command, and the
CANCEL command must specify the REQID associated with DELAY command.
Both the DELAY and CANCEL command must specify the REQID option to use this
technique.

The steps involved in this technique using a temporary storage queue to pass the
REQID are as follows:
1. A task (TRN1) writes a predefined DELAY REQID to a TS queue. For example:
EXEC CICS WRITEQ TS
QUEUE(’DELAYQUE’) FROM(reqid_value)
2. The task waits on another task by issuing a DELAY command, using the
reqid_value as the REQID. For example:
EXEC CICS DELAY
INTERVAL(1000) REQID(reqid_value)
3. Another task, TRN2, reads the REQID of the DELAY request from TS queue
called ‘DELAYQUE’.
4. TRN2 completes its processing, and resumes TRN1 by cancelling the DELAY
request.

The process using a TS queue is illustrated in Figure 65.

TOR

DTR
program

AOR

TRN1

1. Writes DELAY command

REQID to TS queue for
use by TRN2

2. Issues DELAY to wait TRN2

until TRN2 issues
CANCEL command 1. Reads REQID of DELAY
. from TS queue
. .
(suspended) (process)
. .
. 2. Completes processing
.
. 3. Resumes TRN1 by
3. Resumes. CANCELing the DELAY.

Figure 65. Illustration of the use of the DELAY and CANCEL REQID commands

Chapter 15. Affinity 241

Another way to pass the REQID when employing this technique would be for TRN1
to start TRN2 using the START command with the FROM and TERMID options.
TRN2 could then obtain the REQID with the RETRIEVE command, using the INTO
option.

Using this application programming technique, the CANCEL command that cancels
the DELAY request must:
v Be issued in same target region as the DELAY command was executed in, or
v Specify the SYSID of the target region where the DELAY command was
executed, or
v Specify a TRANSID (TRN1 in our example) that is defined as a remote
transaction residing on the target region where the DELAY command was
executed.

An application design based on the remote TRANSID technique only works for two
target regions. An application design using the SYSID option on the cancel
command only works for multiple target regions if all target regions have
connections to all other target regions. In either case, the application programs
need to be modified: there is no acceptable way to use this programming technique
in a dynamic or distributed routing environment except by imposing restrictions on
the routing program.

If the CANCEL command is issued by a transaction that is initiated from a terminal,

it is possible that the transaction could be dynamically routed to the wrong target
region.

Using the POST and CANCEL REQID commands

The CICS POST command is used to request notification that a specified time has
expired. Another transaction (TRN2) can force notification, as if the specified time
has expired, by issuing a CANCEL of the POST request.

The time limit is signalled (posted) by CICS by setting a bit pattern in the event
control block (ECB). To determine whether notification has been received, the
requesting transaction (TRN1) has either to test the ECB periodically, or to issue a
WAIT command on the ECB.

A TS storage queue is one way that can be used to pass the REQID of the POST
request from task to task.

Figure 66 on page 243 illustrates this technique.

242 CICS TS for z/OS: CICS Application Programming Guide

TOR

DTR
program

AOR

TRN1

1. Issues POST command

2. Stores REQID of POST
in TS queue for use TRN2
by TRN2
. 1. Reads REQID of POST
(process) request
. .
. (process)
. .
3. Periodically check 2. Completes processing
if posted 3. Resumes TRN1 by
4. Resumes when time CANCELing the POST.
expired, or when POST
cancelled by TRN2.

Figure 66. Illustration of the use of the POST command

If this technique is used, the dynamic or distributed routing program has to ensure
that TRN2 executes in the same CICS region as TRN1 to preserve the application
design.

The CANCEL command that notifies the task that issued the POST must:
v Be issued in same target region that the POST command was executed in, or
v Specify the SYSID of the target region where the POST command was executed,
or
v Specify a TRANSID (TRN1 in our example) that is defined as a remote
transaction residing on the target region where the POST command was
executed.

In general, this means that the dynamic or distributed routing program has to
ensure that TRN2 executes in the same region as TRN1 to preserve the application
design.

Clearly, there is no problem if the CANCEL is issued by the same task that issued
the POST. If a different task cancels the POST command, it must specify REQID to
identify the particular instance of that command. Hence the CANCEL command with

Chapter 15. Affinity 243

REQID is indicative of an inter-transaction affinity problem. However, REQID need
not be specified on the POST command because CICS automatically generates a
REQID and pass it to the application in EIBREQID.

Detecting inter-transaction affinities

To manage transaction affinities in a dynamic routing environment, you must first
discover which transactions have affinities. How do you do this?

| The recommended way is to use the CICS Interdependency Analyzer to detect

affinities. The CICS Interdependency Analyzer for z/OS User’s Guide and
Reference describes the utility and how to use it.

Note: If you dynamically route program-link requests, you must discover which
programs (or their associated transactions) have affinities. You cannot use
| the CICS Interdependency Analyzer to do this.

If you do not use the utility, you can use one of the following methods to detect
affinities, although you are strongly recommended to use the utility.
v Review application design, paying particular attention to the techniques used for
inter-transaction communication.
v Search the source of application programs, looking for instances of the EXEC
CICS commands that can give rise to inter-transaction affinity.
v Run a trace analysis program that can analyze CICS auxiliary trace. For
example, if you run the CICS trace utility program, DFHTUP, with the ABBREV
option to format CICS auxiliary trace output, you can analyze the resulting
abbreviated trace data to find instances of suspect commands.

Inter-transaction affinities caused by application generators

Application generators may give rise to particularly difficult problems of
inter-transaction affinity:
v The affinity may be hidden from the application programmer.
v The application generator may have a different concept of a transaction to CICS:
it is affinity among CICS transactions that is of concern, because these are the
entities that are dynamically routed.
v Some application generators use a single transaction code for all transactions
within an application, making it difficult for the router to select those instances of
transactions that have affinities.

Duration and scope of inter-transaction affinities

When planning your dynamic routing strategy, and planning how to manage
inter-transaction affinities, it is important to understand the concepts of affinity
relations and affinity lifetimes. The relations and lifetimes of inter-transaction
affinities must be taken into account when designing a dynamic or distributed
routing program, because they define the scope and duration of inter-transaction
affinities. Clearly, the ideal situation for a dynamic or distributed routing program is
for there to be no inter-transaction affinities at all, which means there are no
restrictions in the choice of available target regions for dynamic routing. However,
even when inter-transaction affinities do exist, there are limits to the scope of these
affinities, the scope of the affinity being determined by affinity relation and affinity
lifetime.

244 CICS TS for z/OS: CICS Application Programming Guide

Understanding the relations and lifetimes of transaction affinities is important in
deciding how to manage them in a dynamic routing environment.

Affinity transaction groups

In order to manage affinities within a dynamic routing environment, you must first
categorize transactions by their affinity. One way to do this is to place transactions
in groups, where a group is a set of transactions that have inter-transaction affinity.
Each affinity transaction group (or affinity group, for short) thus represents a group
of transactions that have an affinity with one another. Defining affinity groups is one
way that a dynamic or distributed routing program can determine to which target
region a transaction should be routed.

Clearly, the more inter-transaction affinity you have in a given CICS workload, the
less effective a dynamic routing program can be in balancing the workload across a
CICSplex. To minimize the impact of inter-transaction affinity, affinities within an
affinity group can characterized by their relation and lifetime. These relation and
lifetime attributes determine the scope and duration of an affinity.

Thus, ideally, an affinity transaction group consists of an affinity group identifier, a

set of transactions that constitute the affinity group, with the affinity relation and
affinity lifetime associated with the group.

Relations and lifetimes

When you create an affinity group, you should assign to the group the appropriate
affinity relation and affinity lifetime attributes. The relation determines how the
dynamic or distributed routing program is to select a target region for a transaction
instance associated with the affinity, and the lifetime determines when the affinity is
ended.

There are four possible affinity relations that you can assign to your affinity groups:
1. Global
2. LUname
3. Userid
4. BAPPL

These are described in the following sections, together with the permitted lifetimes
for each relation.

The global relation

A group of transactions whose affinity relation is defined as global is one where all
instances of all transactions in the group that are initiated from any terminal, by any
START command, or by any CICS BTS process, must execute in the same target
region for the lifetime of the affinity. The affinity lifetime for global relations can be
as follows:
System
The affinity lasts for as long as the target region exists, and ends whenever
the target region terminates (at a normal, immediate, or abnormal
termination).
Permanent
The affinity extends across all CICS restarts. This is the most restrictive of
all the inter-transaction affinities. If you are running CICSPlex SM, this
affinity lasts for as long as any CMAS involved in managing the CICSplex
using the workload is active.

Chapter 15. Affinity 245

An example of a global inter-transaction affinity with a lifetime of permanent is
where the transaction uses (reads and/or writes) a local, recoverable, temporary
storage queue, and where the TS queue name is not derived from the terminal.
(You can only specify that a TS queue is recoverable in the CICS region in which
the queue is local.)

Generally, transactions in this affinity category are not suitable candidates for
dynamic routing and you should consider making them statically routed
transactions.

An example of a global relation is illustrated in Figure 67.

Terminal

User TOR
enters
tranid Calls DTR DTR program Affinity group
GGGG program
1. Checks affinity Relation: GLOBAL
Routes GGGG groups for GGGG Lifetime: PERM
to AOR2 2. Start global
affinity for Transids: GGGG
transid GGGG
3. Select AOR from
candidate list
4. Records choice
of AOR (for
example, AOR2)
for this group. GGGG sent to AOR2

AOR1 AOR2 AOR3 AOR4 AOR5 AOR6

GGGG

Figure 67. Managing inter-transaction affinity with global relation and permanent lifetime

In this example, the transaction GGGG is defined in a group with a permanent

global affinity relation. The first instance of transid GGGG, from any terminal, starts
a permanent-lifetime affinity. The first instance of GGGG can be routed to any
suitable target region. In this example, AOR2 is selected from the possible range
AOR1 through AOR6, but all other instances, from any terminal, must also be
routed to the same region, AOR2.

The LUname (terminal) relation

A group of transactions whose affinity relation is defined as LUname is one where
all instances of all transactions in the group that are associated with the same
terminal must execute in the same target region for the lifetime of the affinity. The
affinity lifetime for LUname relations can be as follows:
Pseudoconversation
The affinity lasts for the whole pseudoconversation, and ends when the
pseudoconversation ends at the terminal. Each transaction must end with
an EXEC CICS RETURN TRANSID, not with the pseudoconversation mode
of END.
Logon
The affinity lasts for as long as the terminal remains logged-on to CICS,
and ends when the terminal logs off.

246 CICS TS for z/OS: CICS Application Programming Guide

System
The affinity lasts for as long as the target region exists, and ends whenever
the target region terminates (at a normal, immediate, or abnormal
termination).
Permanent
The affinity extends across all CICS restarts. If you are running
CICSPlex SM, this affinity lasts for as long as any CMAS involved in
managing the CICSplex using the workload is active.
Delimit
The affinity continues until a transaction with a pseudoconversation mode of
END is encountered.

A typical example of transactions that have an LUname relation are those that:
v Use a local TS queue to pass data between the transactions in a
pseudoconversation, and
v The TS queue name is derived, in part, from the terminal name (see “Naming
conventions for remote queues” on page 235 for information about TS queue
names).

These types of transaction can be placed in an affinity group with a relation of

terminal and lifetime of pseudoconversation. When the dynamic routing program
detects the first transaction in the pseudoconversation initiated by a specific
terminal (LUname), it is free to route the transaction to any target region that is a
valid candidate for that transaction. However, any subsequent transaction within the
affinity group that is initiated at the same terminal must be routed to the same
target region as the transaction that started the pseudoconversation. When the
affinity ends (at the end of the pseudoconversation on a given terminal), the
dynamic routing program is again free to route the first transaction to any candidate
target region.

This form of affinity is manageable and does not impose too severe a constraint on
dynamic transaction routing, and may occur commonly in many CICSplexes. It can
be managed easily by a dynamic routing program, and should not inhibit the use of
dynamic routing.

This example is illustrated in Figure 68 on page 248.

Chapter 15. Affinity 247

LUNAME= TOR
IGKS201
User Calls DTR DTR program Affinity group
enters program
tranid 1. Checks affinity Relation: LUNAME
AAAA Routes AAAA groups for AAAA Lifetime: PCONV
to AOR4 2. Detects start
of pseudoconv. Transids: AAAA
3. Selects an AOR BBBB
from candidate .
list. .
4. Records choice ZZZZ
of AOR (for
example, AOR4)
for this group. AAAA on IGKS201
sent to AOR4

AOR1 AOR2 AOR3 AOR4 AOR5 AOR6

AAAA

Figure 68. Managing inter-transaction affinity with LUname relation and pseudoconversation
lifetime

In this example, each instance of transid AAAA from a terminal starts a

pseudoconversational-lifetime affinity. AAAA can be routed to any suitable target
region (AOR1 through AOR6), but other transactions in the group, in the same
pseudoconversation with the same terminal (IGKS201 in this example) must be
routed to whichever target region is selected for AAAA.

The userid relation

A group of transactions whose affinity relation is defined as userid is one where all
instances of the transactions that are initiated from a terminal, by a START
command, or by a CICS BTS activity, and executed on behalf of the same userid,
must execute in the same target region for the lifetime of the affinity. The affinity
lifetime for userid relations can be as follows:
Pseudoconversation
The affinity lasts for the whole pseudoconversation, and ends when the
pseudoconversation ends for that userid. Each transaction must end with an
EXEC CICS RETURN TRANSID, not with the pseudoconversation mode of
END.
Signon
The affinity lasts for as long as the user is signed on, and ends when the
user signs off. Note this lifetime is only possible in those situations where
only one user per userid is permitted. Signon lifetime cannot be detected if
multiple users are permitted to be signed on with the same userid at the
same time (at different terminals).
System
The affinity lasts for as long as the target region exists, and ends whenever
the target region terminates (at a normal, immediate, or abnormal
termination).
Permanent
The affinity extends across all CICS restarts. If you are running
CICSPlex SM, this affinity lasts for as long as any CMAS involved in
managing the CICSplex using the workload is active.

248 CICS TS for z/OS: CICS Application Programming Guide

Delimit
The affinity continues until a transaction with a pseudoconversation mode of
END is encountered.

A typical example of transactions that have a userid relation is where the userid is
used dynamically to identify a resource, such as a TS queue. The least restrictive of
the affinities in this category is one that lasts only for as long as the user remains
signed on.

An example of an affinity group with the userid relation and a signon lifetime is
shown in Figure 69.

Userid= TOR
ANOTHER
User Calls DTR DTR program Affinity group
enters program
tranid 1. Checks affinity Relation: USERID
WWWW Routes WWWW groups for WWWW Lifetime: SIGNON
to AOR4 2. Detects start
of pseudoconv. Transids: WWWW
3. Selects an AOR XXXX
from candidate .
list. .
4. Records choice YYYY
of AOR (for
example, AOR4)
for this group. WWWW sent to AOR4
for user=ANOTHER

AOR1 AOR2 AOR3 AOR4 AOR5 AOR6

WWWW

Figure 69. Managing inter-transaction affinity with userid relation and sign-on lifetime

In this example, any instance of a transaction from a terminal starts a sign-on

lifetime affinity. It can be routed to any suitable target region (AOR1 through AOR6),
but other transactions in the group for the same user (ANOTHER in this example)
must be routed to whichever target region is selected for the first instance of a
transaction in the group.

The BAPPL relation

A group of transactions whose affinity relation is defined as BAPPL is one where all
instances of all transactions in the group that are associated with the same BTS
process are to be directed to the same target region. The affinity lifetimes for
BAPPL relations can be as follows:
Process
The affinity lasts for as long as the associated process exists.
Activity
The affinity lasts for as long as the associated activity exists.
System
The affinity lasts for as long as the target region exists, and ends whenever
the target region terminates (at a normal, immediate, or abnormal
termination).

Chapter 15. Affinity 249

Permanent
The affinity extends across all CICS restarts. If you are running
CICSPlex SM, this affinity lasts for as long as any CMAS involved in
managing the CICSplex using the workload is active.

A typical example of transactions that have a BAPPL relation is where a local

temporary storage queue is used to pass data between the transactions within a
BTS activity or process.

An example of an affinity group with the BAPPL relation is shown in Figure 70.

AOR 1
BAPPL Calls
activity dynamic Dynamic routing Affinity group
started program
routing Relation: BAPPL
Transid 1. Checks affinity
program Lifetime: ACTIVITY
BAP1 groups for BAP1.
Routes BAP1 2. Start BAPPL
to AOR4 affinity for Transid : BAP1
transid BAP1
3. Select target
region from
candidate list
4. Record choice
of target Sent BAP1 to AOR4
region (for
example, AOR4)
for this group.

AOR2 AOR3 AOR4 AOR5 AOR6

Figure 70. Managing inter-transaction affinity with BAPPL relation and activity lifetime

In this example, the first instance of BTS transaction BAP1 starts a BAPPL–activity
affinity. The first instance of BAP1 can be routed to any suitable target region
(AOR1 through AOR6), but all other instances of the activity must be routed to
whichever target region is selected for BAP1.

Although BTS itself does not introduce any affinities, and discourages programming
techniques that do, it does support existing code that may introduce affinities. You
must define such affinities to workload management. It is particularly important to
specify each affinity’s lifetime. Failure to do this may restrict unnecessarily the
workload management routing options.

It is important to note that a given activity can be run both synchronously and
asynchronously. Workload management is only able to honour invocations that are
made asynchronously. Furthermore, you are strongly encouraged not to create
these affinities, particularly activity and process affinities, because these affinities
are synchronized across the BTS-set. This could have serious performance impacts
on your systems.

You should also note that, with CICSPlex SM, the longest time that an affinity can
be maintained is while a CMAS involved in the workload is active; that is, an affinity

250 CICS TS for z/OS: CICS Application Programming Guide

of PERMANENT. If there is a total system failure, or a planned shutdown, affinities
will be lost, but activities in CICS will be recovered from the BTS RLS data set.

Chapter 15. Affinity 251

252 CICS TS for z/OS: CICS Application Programming Guide
Chapter 16. Recovery design
CICS provides two techniques that can help you to recover or reconstruct events or
data changes during CICS execution:
v “Journaling”
v “Syncpointing” on page 255

Journaling
CICS provides facilities for creating and managing journals during CICS
processing. Journals may contain any and all data the user needs to facilitate
subsequent reconstruction of events or data changes. For example, a journal might
act as an audit trail, a change-file of database updates and additions, or a record of
transactions passing through the system (often referred to as a log). Each journal
can be written from any task.

Journal control commands are provided to allow the application programmer to:
v Create a journal record (WRITE JOURNALNAME or WRITE JOURNALNUM
command)
v Synchronize with (wait for completion of) journal output (WAIT JOURNALNAME
or WAIT JOURNALNUM command)

Exception conditions that occur during execution of a journal control command are
handled as described in Chapter 17, “Dealing with exception conditions,” on page
257. (The earlier JFILEID option is supported for compatibility purposes only.)

Journal records
Each journal is identified by a name or number known as the journal identifier. This
number may range from 1 through 99. The name DFHLOG is reserved for the
journal known as the system log.

When a journal record is built, the data is moved to the journal buffer area. All
buffer space and other work areas needed for journal operations are acquired and
managed by CICS. The user task supplies only the data to be written to the journal.
Log manager is designed so that the application programmer requesting output
services does not have to be concerned with the detailed layout and precise
contents of journal records. The programmer has to know only which journal to use,
what user data to specify, and which user-identifier to supply.

Journal output synchronization

When a synchronous journal record is created by issuing the WRITE
JOURNALNAME or WRITE JOURNALNUM command with the WAIT option, the
requesting task can wait until the output has been completed. By specifying that this
should happen, the application programmer ensures that the journal record is
written on the external storage device associated with the journal before processing
continues; the task is said to be synchronized with the output operation.

The application programmer can also request asynchronous journal output. This
causes a journal record to be created in the journal buffer area but allows the
requesting task to retain control and thus to continue with other processing. The
task may check and wait for output completion (that is, synchronize) later by issuing
the WAIT JOURNALNAME or WAIT JOURNALNUM command.

Note: In some cases, a SHUTDOWN IMMEDIATE can cause user journal records
to be lost, if they have been written to a log manager buffer but not to
external storage. This is also the case if the CICS shut-down assist
transaction (CESD) forces SHUTDOWN IMMEDIATE during a normal
shutdown, because normal shutdown is hanging. To avoid the risk of losing
journal records, you are recommended to issue CICS WAIT JOURNALNUM
requests periodically, and before ending your program.

Without WAIT, CICS does not write data to the log stream until it has a full buffer of
data, or until some other unrelated activity requests that the buffer be hardened,
thus reducing the number of I/O operations. Using WAIT makes it more difficult for
CICS to calculate accurately log structure buffer sizes. For CF log streams, this
could lead to inefficient use of storage in the coupling facility.

The basic process of building journal records in the CICS buffer space of a given
journal continues until one of the following events occurs:
v For system logs:
– Whenever the system requires it to ensure integrity and to permit a future
emergency restart
– The log stream buffer is filled
v For user journals:
– The log stream buffer is filled (or, if the journal resides on SMF, when the
journal buffer is filled)
– A request specifying the WAIT option is made (from any task) for output of a
journal record
– An EXEC CICS SET JOURNALNAME command is issued
– An EXEC CICS DISCARD JOURNALNAME command is issued
– Any of the above occurring for any other journal which maps onto the same
log stream
– On a normal shutdown
v For forward recovery logs:
– The log stream buffer is filled
– At syncpoint (first phase)
– On file closure
v For autojournals:
– The log stream buffer is filled
– A request specifying the WAIT option is made (from any task) for output of a
journal record
– On file closure
v For the log-of-logs (DFHLGLOG):
– On file OPEN and CLOSE requests

When any one of these occurs, all journal records present in the buffer, including
any deferred output resulting from asynchronous requests, are written to the log
stream as one block.

The advantages that may be gained by deferring journal output are:

v Transactions may get better response times by waiting less.
v The load of physical I/O requests on the host system may be reduced.

254 CICS TS for z/OS: CICS Application Programming Guide

v Log streams may contain fewer but larger blocks and so better utilize primary
storage.

However, these advantages are achievable only at the cost of greater programming
complexity. It is necessary to plan and program to control synchronizing with journal
output. Additional decisions that depend on the data content of the journal record
and how it is to be used must be made in the application program. In any case, the
full benefit of deferring journal output is obtained only when the load on the journal
is high.

If the journal buffer space available at the time of the request is not sufficient to
contain the journal record, the NOJBUFSP condition occurs. If no HANDLE
CONDITION command is active for this condition, the requesting task loses control,
the contents of the current buffer are written, and the journal record is built in the
resulting freed buffer space before control returns to the requesting task.

If the requesting task is not willing to lose control (for example, if some
housekeeping must be performed before other tasks get control), a HANDLE
CONDITION command should be issued. If the NOJBUFSP condition occurs, no
journal record is built for the request, and control is returned directly to the
requesting program at the location provided in the HANDLE CONDITION command.
The requesting program can perform any housekeeping needed before reissuing
the journal output request.

Journal commands can cause immediate or deferred output to the journal. System
log records are distinguished from all other records by specifying
JOURNALNAME(DFHLOG) on the request. User journal records are created using
some other JOURNALNAME or a JOURNALNUM. All records must include a
journal type identifier, (JTYPEID). If the user journaling is to the system log, the
journal type identifier (according to the setting of the high-order bit) also serves to
control the presentation of these to the global user exit XRCINPT at a warm or
emergency restart. Records are presented during the backward scan of the log as
follows:
v For in-flight or in-doubt tasks only (high-order bit off)
v For all records encountered until the scan is terminated (high-order bit on)

See the CICS Customization Guide for information about the format and structure of
journal records. See the section on emergency restart in the CICS Recovery and
Restart Guide for background information and a description of the recovery process.

Syncpointing
To facilitate recovery in the event of abnormal termination of a CICS task or of
failure of the CICS system, the system programmer can, during CICS table
generation, define specific resources (for example, files) as recoverable. If a task is
terminated abnormally, these resources are restored to the condition they were in at
the start of the task, and can then be rerun. The process of restoring the resources
associated with a task is termed backout.

If an individual task fails, backout is performed by the dynamic transaction backout

program. If the CICS system fails, backout is performed as part of the emergency
restart process. See the CICS Recovery and Restart Guide which describes these
facilities, which in general have no effect on the coding of application programs.

However, for long-running programs, it may be undesirable to have a large number

of changes, accumulated over a period of time, exposed to the possibility of

Chapter 16. Recovery design 255

backout in the event of task or system failure. This possibility can be avoided by
using the SYNCPOINT command to split the program into logically separate
sections known as units of work (UOWs); the end of an UOW is referred to as a
synchronization point (syncpoint). For more information about syncpoints, see the
CICS Recovery and Restart Guide.

If failure occurs after a syncpoint but before the task has been completed, only
changes made after the syncpoint are backed out.

Alternatively, you can use the SAA Resource Recovery interface instead of the
SYNCPOINT command. This provides an alternative API to existing CICS resource
recovery services. You may wish to use the SAA Resource Recovery interface in
networks that include multiple SAA platforms, where the consistency of a common
API is seen to be of benefit. In a CICS system, the SAA Resource Recovery
interface provides the same function as the EXEC CICS API.2

The SAA Resource Recovery interface is implemented as a call interface, having

two call types:
SRRCMIT
Commit—Equivalent to SYNCPOINT command.
SRRBACK
Backout—Equivalent to SYNCPOINT ROLLBACK command.

For further information about the SAA Resource Recovery interface, see SAA
Common Programming Interface for Resource Recovery Reference manual.

UOWs should be entirely logically independent, not merely with regard to protected
resources, but also with regard to execution flow. Typically, an UOW comprises a
complete conversational operation bounded by SEND and RECEIVE commands. A
browse is another example of an UOW; an ENDBR command must therefore
precede the syncpoint.

In addition to a DL/I termination call being considered to be a syncpoint, the

execution of a SYNCPOINT command causes CICS to issue a DL/I termination call.
If a DL/I PSB is required in a subsequent UOW, it must be rescheduled using a
program control block (PCB) call or a SCHEDULE command.

With distributed program link (DPL), it is possible to specify that a syncpoint is

taken in the server program, to commit the server resources before returning control
to the client. This is achieved by using the SYNCONRETURN option on the LINK
command. For programming information about the SYNCONRETURN option, see
″The SYNCONRETURN option for the server program″ on page 5 on page 436 and
the CICS Application Programming Reference manual.

A BMS logical message, started but not completed when a SYNCPOINT command
is processed, is forced to completion by an implied SEND PAGE command.
However, you should not rely on this because a logical message whose first page is
incomplete is lost. You should also code an explicit SEND PAGE command before
the SYNCPOINT command or before termination of the transaction.

Consult your system programmer if syncpoints are to be issued in a transaction that

is eligible for transaction restart.

2. Full SAA Resource Recovery provides some return codes that are not supported in its CICS implementation. (See the CICS
appendix in the SAA Common Programming Interface for Resource Recovery Reference manual.)

256 CICS TS for z/OS: CICS Application Programming Guide

Chapter 17. Dealing with exception conditions
Every time you process an EXEC CICS command in one of your applications, CICS
automatically raises a condition, or return code, to tell you what happened. You can
choose to have this condition, which is usually NORMAL, passed back by the CICS
EXEC interface program to your application. It is sometimes called a RESP value,
because you may get hold of it by using the RESP option in your command.
Alternatively, you may obtain this value by reading it from the EXEC interface block
(EIB).

If something out of the ordinary happens, you get an exception condition, which
simply means a condition other than NORMAL. By testing this condition, you can
find out what has happened and, possibly, why.

Many exception conditions have an additional (RESP2) value associated with them,
which gives further information. You may obtain this RESP2 value either by using
the RESP2 option in your command in addition to the RESP option, or by reading it
from the EIB.

Not all conditions denote an error situation, even if they are not NORMAL. For
example, if you get an ENDFILE condition on a READNEXT command during a file
browse, it might be exactly what you expect. For information about all possible
conditions and the commands on which they can occur, see the CICS Application
Programming Reference manual.

This chapter describes:

v Default CICS exception handling
v “Handling exception conditions by in-line code” on page 258
v “Modifying default CICS exception handling” on page 261

Default CICS exception handling

If your application is written in a language other than C, C++, or Java and you do
not specify otherwise, CICS uses its built-in exception handling whenever an
exception condition occurs. If your application is written in C or C++, CICS itself
takes no action when an exception condition occurs and it is left to the application
to handle it. See “Handling exception conditions by in-line code” on page 258 for
information on handling exception conditions.

The most common action by CICS is to cause an abend of some type to happen.
The particular behaviors for each condition and for each command are detailed in
the CICS Application Programming Reference and CICS System Programming
Reference manuals.

Sometimes you will be satisfied with the CICS default exception handling, in which
case you need do nothing. More often you will prefer some other course of action.

These are the different ways of turning off the default CICS handling of exception
conditions.
v Turn off the default CICS handling of exception conditions on a particular EXEC
CICS command call by specifying the NOHANDLE option.
v Alternatively, turn off the default CICS handling of exception conditions by
specifying the RESP option on the command. This, of itself, switches off the
default CICS exception handling in the same way as NOHANDLE does. It also

causes the variable named by the argument of RESP to be updated with the
value of the condition returned by the command. This is described in more detail
in “Handling exception conditions by in-line code.”
v Write your application program in C or C++.

If the default CICS exception handling is turned off you should ensure that your
program copes with anything that may happen in the command call.

The traditional, but no longer recommended, way to specify some other course of
action is available only if you are programming in a language other than C or C++:
it is to use combinations of the HANDLE ABEND, HANDLE CONDITION, and
IGNORE CONDITION commands to modify the default CICS exception handling.
This is described in “Modifying default CICS exception handling” on page 261.

Handling exception conditions by in-line code

This section describes the method of handling exception conditions which is
recommended for new applications and is the only available choice if your programs
are in C or C++ language. If your program is not written in C or C++, it involves
either using the NOHANDLE option or specifying the RESP option on EXEC CICS
commands, which prevents CICS performing its default exception handling.
Additionally, the RESP option makes the value of the exception condition directly
available to your program, for it to take remedial action.

If your program is written in C or C++, in-line code is the only means you have of
handling exception conditions.

If you use the NOHANDLE or RESP option, you should ensure that your program
can cope with whatever condition may arise in the course of executing the
commands. The RESP value is available to enable your program to decide what to
do and more information which it may need to use is carried in the EXEC interface
block (EIB). In particular, the RESP2 value is contained in one of the fields of the
EIB. See the CICS Application Programming Reference manual for more
information on the EIB. Alternatively, if your program specifies RESP2 in the
command, the RESP2 value is returned by CICS directly.

The DFHRESP built-in translator function makes it very easy to test the RESP
value. It allows, you to examine RESP values symbolically. This is easier than
examining binary values that are less meaningful to someone reading the code.

How to use the RESP and RESP2 options

The argument of RESP is a user-defined fullword binary data area (long integer).
On return from the command, it contains a value corresponding to the condition that
may have been raised. Normally its value is DFHRESP(NORMAL).

Use of RESP and DFHRESP in COBOL and PL/I

Here is an example of an EXEC CICS call in COBOL which uses the RESP option.
A PL/I example would be similar, but would end in “;” instead of END-EXEC.
EXEC CICS WRITEQ TS FROM(abc)
QUEUE(qname)
NOSUSPEND
RESP(xxx)
END-EXEC.

An example of using DFHRESP to check the RESP value is:

IF xxx=DFHRESP(NOSPACE) THEN ...

258 CICS TS for z/OS: CICS Application Programming Guide

Use of RESP and DFHRESP in C and C++
Here is an example of an EXEC CICS call in C, which uses the RESP option,
including the declaration of the RESP variable:
long
. response;
.
.
EXEC CICS WRITEQ TS FROM(abc)
QUEUE(qname)
NOSUSPEND
RESP(response);

An example of using DFHRESP to check the RESP value is:

if (response == DFHRESP(NOSPACE))
{
.
.
.
}

Use of DFHRESP in assembler

An example of a test for the RESP value in assembler language is:
CLC xxx,DFHRESP(NOSPACE)
BE ...

An example of exception handling in C

The following example is a typical function which could be used to receive a BMS
map and to cope with exception conditions:

int ReadAccountMap(char mapname, void map)

{
long response;
int ExitKey;
EXEC CICS RECEIVE MAP(mapname)
MAPSET("ACCOUNT")
INTO(map)
RESP(response);
switch (response)
{
case DFHRESP(NORMAL):
ExitKey = dfheiptr->eibaid;
ModifyMap(map);
break;
case DFHRESP(MAPFAIL):
ExitKey = dfheiptr->eibaid;
break;
default:
ExitKey = DFHCLEAR;
break;
}
return ExitKey;
}

Figure 71. An example of exception handling in C

The ReadAccountMap function has two arguments:

1. mapname is the variable which contains the name of the map which is to be
received.
2. map is the address of the area in memory to which the map is to be written.

The RESP value will be returned in response. The declaration of response sets up
the appropriate type of automatic variable.

Chapter 17. Dealing with exception conditions 259

The EXEC CICS statement asks for a map of the name given by mapname, of the
mapset ACCOUNT, to be read into the area of memory to which the variable map
points, with the value of the condition being held by the variable response.

The condition handling can be done by using if statements. However, to improve

readability, it is often better, as here, to use a switch statement, instead of
compound if ... else statements. The effect on program execution time is negligible.

Specific cases for two conditions:

1. A condition of NORMAL is what is normally expected. If a condition of NORMAL
is detected in the example here, the function then finds out what key the user
pressed to return to CICS and this value is passed to ExitKey. The program
then makes some update to the map held in memory by the ModifyMap
function, which need not concern us further.
2. A condition of MAPFAIL, signifying that the user has made no updates to the
screen, is also fairly normal and is specifically dealt with here. In this case the
program again updates ExitKey but does not call ModifyMap.

In this example, any other condition is held to be an error. The example sets
ExitKey to DFHCLEAR—the same value that it would have set if the user had
cleared the screen—which it then returns to the calling program. By checking the
return code from ReadAccountMap, the calling program would know that the map
had not been updated and that some remedial action is required.

An example of exception handling in COBOL

The following example is a typical function which could be used to receive a BMS
map and to cope with exception conditions:

# 03 RESPONSE PIC S9(8) BINARY.

## 03
. EXITKEY PIC X.
## .
.
# EXEC CICS RECEIVE MAP(MAPNAME)
# MAPSET(’ACCOUNT’)
# INTO(MAP)
# RESP(RESPONSE)
# END-EXEC.
# IF (RESPONSE NOT = DFHRESP(NORMAL)) AND
# (RESPONSE NOT = DFHRESP(MAPFAIL))
# MOVE DFHCLEAR TO EXITKEY
# ELSE
# MOVE EIBAID TO EXITKEY
# IF RESPONSE = DFHRESP(NORMAL)
# GO TO MODIFYMAP
# END-IF
## END-IF.
.
## .
.
## MODIFYMAP.
.
## .
.

#
# Figure 72. An example of exception handling in COBOL
#
MAPNAME is the variable which contains the name of the map which is to be
received.

The RESP value is returned in RESPONSE. RESPONSE is declared as a fullword

binary variable in the data section.

260 CICS TS for z/OS: CICS Application Programming Guide

The EXEC CICS statement asks for a map of the name given by MAPNAME, of the
mapset ACCOUNT, to be read, with the value of the condition being held by the
variable RESPONSE.

The condition handling is done by using IF ... statements. If the condition is neither
NORMAL nor MAPFAIL the program behaves as if the user had cleared the screen.

If the condition is either NORMAL or MAPFAIL the program saves the value of the
key which the user pressed to exit the screen in EXITKEY. In addition, if the
condition is NORMAL, the program branches to MODIFYMAP to perform some
additional function.

Modifying default CICS exception handling

CICS provides the following EXEC CICS commands which modify the default CICS
exception handling and one which modifies the way CICS handles abends:

Note: These commands cannot be used in C, C++, or Java programs. The rest of
this chapter is not relevant for these languages.
HANDLE CONDITION
Specify the label to which control is to be passed if a condition occurs.
IGNORE CONDITION
Specify that no action is to be taken if a condition occurs.
HANDLE ABEND
Activate, cancel, or reactivate an exit for abnormal termination processing.

An abend is the commonest way in which CICS handles exception conditions.

The current effect of IGNORE CONDITION, HANDLE ABEND, and HANDLE

CONDITION may be suspended by using PUSH HANDLE and reinstated by using
POP HANDLE .

You have two ways of passing control to a specified label:

1. Use a HANDLE CONDITION condition(label) command, where condition is the
name of an exception condition
2. Use a HANDLE CONDITION ERROR(label) command

The HANDLE CONDITION command sets up some CICS code to name conditions
that interest you, and then uses this code to pass control to appropriate sections of
your application if those conditions arise. So with an active HANDLE CONDITION
command, control goes to whichever label you specified for that particular condition.

The same condition can arise, in some cases, on many different commands, and
for a variety of reasons. For example, you can get an IOERR condition during file
control operations, interval control operations, and others. One of your first tasks,
therefore, is to sort out which command has raised a particular condition; only
when you have discovered that, can you begin to investigate why it has happened.
This, for many programmers, is reason enough to start using the RESP option in
their new CICS applications. Although you need only one HANDLE CONDITION
command to set your error-handling for several conditions, it can sometimes be
awkward to pinpoint exactly which of several HANDLE CONDITION commands is
currently active when a CICS command fails somewhere in your code.

Chapter 17. Dealing with exception conditions 261

If a condition which you have not named arises, CICS takes the default action,
unless this is to abend the task, in which case it raises the ERROR condition. If you
name the condition but leave out its label, any HANDLE CONDITION command for
that condition is deactivated, and CICS reverts to taking the default action for it, if
and when it occurs.

The need to deal with all conditions is a common source of errors when using the
HANDLE CONDITION command. When using an unfamiliar command, you should
refer to the description of the command in the CICS Application Programming
Reference manual to find out which exception conditions are possible. Even if you
then issue HANDLE commands for all of these, you may not finish all the
error-handling code adequately. The outcome is sometimes an error-handling
routine that, by issuing a RETURN command, allows incomplete or incorrect data
changes to be committed.

The best approach is to use the HANDLE CONDITION command, but to let the
system default action take over if you cannot see an obvious way round a particular
problem.

Bearing in mind the distinction between an error condition, a condition that merely
causes a wait (see page “How CICS keeps track of what to do” on page 264 for
examples of conditions that cause a wait), and the special case of the SEND MAP
command overflow processing, a HANDLE CONDITION command is active after a
HANDLE CONDITION condition(label), or HANDLE CONDITION ERROR(label)
command has been run in your application.

If no HANDLE CONDITION command is active for a condition, but one is active for
ERROR, control passes to the label for ERROR, if the condition is an error, not a
wait.

If you use HANDLE CONDITION commands, or are maintaining an application that

uses them, do not include any commands in your error routine that can cause the
same condition that gave you the original branch to the routine, because you will
cause a loop.

Take special care not to cause a loop on the ERROR condition itself. You can avoid
a loop by reverting temporarily to the system default action for the ERROR
condition. Do this by coding a HANDLE CONDITION ERROR command with no
label specified. At the end of your error processing routine, you can reinstate your
error action by including a HANDLE CONDITION ERROR command with the
appropriate label. If you know the previous HANDLE CONDITION state, you can do
this explicitly. In a general subroutine, which might be called from several different
points in your code, the PUSH HANDLE and POP HANDLE command may be
useful—see “Using PUSH HANDLE and POP HANDLE commands” on page 267.

262 CICS TS for z/OS: CICS Application Programming Guide

Using the HANDLE CONDITION command
Use the HANDLE CONDITION command to specify the label to which control is to
be passed if a condition occurs. You must include the name of the condition and
you must ensure that the HANDLE CONDITION command is executed before the
command that may give rise to the associated condition.

You cannot include more than 16 conditions in the same command. You must
specify any additional conditions in further HANDLE CONDITION commands. You
can also use the ERROR condition within the same list to specify that all other
conditions are to cause control to be passed to the same label.

The HANDLE CONDITION command for a given condition applies only to the
program in which it is specified. The HANDLE CONDITION command:
v Remains active while the program is running, or until:
– An IGNORE CONDITION command for the same condition is met, in which
case the HANDLE CONDITION command is overridden
– Another HANDLE CONDITION command for the same condition is met, in
which case the new command overrides the previous one
v Is temporarily deactivated by the NOHANDLE or RESP option on a command

When control passes to another program, by a LINK or XCTL command, the

HANDLE CONDITION commands that were active in the calling program are
deactivated. When control returns to a program from a program at a lower logical
level, the HANDLE CONDITION commands that were active in the higher-level
program before control was transferred from it are reactivated, and those in the
lower-level program are deactivated. (Refer to “Application program logical levels”
on page 562 for information about logical levels.)

The following example shows you how to handle conditions, such as DUPREC,
LENGERR, and so on, that can occur when you use a WRITE command to add a
record to a data set. Suppose that you want DUPREC to be handled as a special
case; that you want standard system action (that is, to terminate the task
abnormally) to be taken for LENGERR; and that you want all other conditions to be
handled by the error routine ERRHANDL. You would code:
EXEC CICS HANDLE CONDITION
ERROR(ERRHANDL)
DUPREC(DUPRTN) LENGERR
END-EXEC.

In a PL/I application program, a branch to a label in an inactive procedure or in an

inactive begin block, caused by a condition, produces unpredictable results.

In an assembler language application program, if a HANDLE condition and the

command that caused the condition are at the same logical level, the registers are
restored to their values in the application program at the point where the command
that caused the condition was issued. However, when the command that causes a
condition occurs at a lower logical level, the registers are restored to the values
saved in DFHEISTG when control is passed from the HANDLE CONDITION level.

Chapter 17. Dealing with exception conditions 263

RESP and NOHANDLE options
You can temporarily deactivate the effect of any HANDLE CONDITION command
by using the RESP or NOHANDLE option on a command. The way to use these
options is described in “Handling exception conditions by in-line code” on page 258.
If you do this, you lose the ability to use any system default action for that
command. In other words, you have to do your own “catch-all” error processing.

How CICS keeps track of what to do

CICS has a table of the conditions referred to by HANDLE CONDITION and
IGNORE CONDITION commands in your application. Each execution of one of
these commands either updates an existing entry in this table, or causes CICS to
make a new entry if this is the first time the condition has been quoted in such a
command. Each entry tells CICS what to do by indicating one of the three
exception-handling states your application can be in, namely:
1. Let the program continue, with control coming straight back from CICS to the
next instruction following the command that has failed in your program. You can
then find out what happened by testing, for example, the RESP value that CICS
returns after executing a command. The result of this test enables you decide
what to do next. For details, see “Handling exception conditions by in-line code”
on page 258.
This is the recommended method, which is the approach taken in the “File A”
sample programs referred to in the Sample Applications Guide and in the
COBOL sample application in the Designing and Programming CICS
Applications. It is also the recommended approach for any new CICS
applications. It lends itself to structured code and removes the need for implied
GOTOs that CICS required in the past.
2. Pass control to a specified label if a named condition arises. You do this by
using a HANDLE CONDITION command or HANDLE CONDITION ERROR
command to name both the condition and the label of a routine in your code to
deal with it. For details, see “Using the HANDLE CONDITION command” on
page 263 and “Using the HANDLE CONDITION ERROR command” on page
265.
3. Taking the CICS system default action, where for most conditions, this is to
terminate the task abnormally and means that you do nothing by way of testing
or handling conditions.

For the conditions ENQBUSY, NOJBUFSP, NOSTG, QBUSY, SESSBUSY, and

SYSBUSY, the normal default is to force the task to wait until the required resource
(for example, storage) becomes available, and then resume processing the
command. You can change this behavior to ignoring the condition by using the
NOSUSPEND option. For the condition NOSPACE, the normal default is to wait if
processing a WRITEQ TS command, but to abend the task if processing a WRITEQ
TD, WRITE, or REWRITE command. Coding the WRITEQ TS command with the
NOSUSPEND option makes it ignore any NOSPACE condition that arises. For more
information see the CICS Application Programming Reference manual.

CICS keeps a table of these conditions for each link level. Essentially, therefore,
each program level has its own HANDLE state table governing its own condition
handling.

This behavior is modified by HANDLE CONDITION ERROR and IGNORE

CONDITION.

264 CICS TS for z/OS: CICS Application Programming Guide

Using the HANDLE CONDITION ERROR command
Figure 73 shows the first of only two HANDLE CONDITION commands used in
program ACCT01:

PROCEDURE DIVISION.
*
* INITIALIZE.
* TRAP ANY UNEXPECTED ERRORS.
EXEC CICS HANDLE CONDITION
ERROR(OTHER-ERRORS)
END-EXEC.
*

Figure 73. Trapping the unexpected with the HANDLE CONDITION ERROR command

It passes control to the paragraph at label OTHER-ERRORS if any condition arises

for a command that does not specify NOHANDLE or RESP.

The HANDLE CONDITION ERROR command is the first command executed in the
procedure division of this COBOL program. This is because a HANDLE
CONDITION command must be processed before any CICS command is processed
that can raise the condition being handled. Note, however, that your program does
not see the effects when it processes the HANDLE CONDITION command; it only
sees them later, if and when it issues a CICS command that actually raises one of
the named conditions.

In this, and the other ACCT programs, you generally use the RESP option. All the
commands specifying the RESP option have been written with a “catch-all” test (IF
RESPONSE NOT = DFHRESP(NORMAL) GO TO OTHER-ERRORS) after any
explicit tests for specific conditions So any exceptions, other than those you might
particularly “expect”, take control to the paragraph at OTHER-ERRORS in each
program. Those relatively few commands that do not have RESP on them take
control to exactly the same place if they result in any condition other than NORMAL
because of this HANDLE CONDITION ERROR command.

Using the IGNORE CONDITION command

Just as you can arrange for control to pass to a particular label for a specific
condition with a HANDLE CONDITION command, so you can have the program
continue when a specific condition occurs. You do this by setting up an IGNORE
CONDITION command to ignore one or more of the conditions that can potentially
arise on a command. The IGNORE CONDITION command means that no action is
to be taken if a condition occurs; control returns to the instruction following the
command and return codes are set in the EIB. The following example ignores the
MAPFAIL condition:
EXEC CICS IGNORE CONDITION MAPFAIL
END-EXEC.

While a single EXEC CICS command is being processed, it can raise several
conditions.3 CICS checks these and passes back to your application program the
first one that is not ignored (by your IGNORE CONDITION command). CICS
passes back only one exception condition at a time to your application program.

3. For example, you may have a file control command that is not only invalid but also applies to a file not defined in the file control
table.

Chapter 17. Dealing with exception conditions 265

An IGNORE CONDITION command for a given condition applies only to the
program you put it in, and it remains active while the program is running, or until a
later HANDLE CONDITION command naming the same condition is met, in which
case the IGNORE CONDITION command is overridden.

You can choose an IGNORE CONDITION command if you have a program reading
records that are sometimes longer than the space you provided, but you do not
consider this an error and do not want anything done about it. You might, therefore,
code IGNORE CONDITION LENGERR before issuing READ commands.

You can also use an IGNORE CONDITION ERROR command to catch any
condition considered as an error for which there is no currently active HANDLE
CONDITION command that includes a label. When an error occurs, control is
passed to the next statement and it is up to the program to check for return codes
in the EIB. See page “How CICS keeps track of what to do” on page 264 for
examples of conditions that are not considered as errors.

You can also switch from ignoring a condition to handling it, or to using the system
default action. For example, you could code:
* MIXED ERROR PROCESSING
EXEC CICS IGNORE CONDITION LENGERR
. END-EXEC.
.
.
EXEC CICS HANDLE CONDITION DUPREC(DUPRTN)
LENGERR
ERROR(ERRHANDL)
END-EXEC.

Because this code initially ignores condition LENGERR, nothing happens if the
program raises a LENGERR condition; the application simply continues its
processing. Of course, if the fact that LENGERR has arisen means that the
application cannot sensibly continue, you have a problem.

Later in the code, you can explicitly set condition LENGERR to the system default
action by naming it in a HANDLE CONDITION command without a label. When this
command has been executed, the program no longer ignores condition LENGERR,
and if it subsequently occurs, it now causes the system default action. The point
about mixing methods is that you can, and that each condition is treated separately.

You cannot code more than 16 conditions in the same command. You must specify
additional conditions in further IGNORE CONDITION commands.

Using the HANDLE ABEND command

Note to Java, C and C++ programmers
Handle ABEND is not applicable to Java programs. Although HANDLE ABEND
is supported in C and C++ when used with the PROGRAM option, it is not
helpful in the context of this chapter because exception conditions in C and
C++ programs do not cause abends.

The HANDLE ABEND command activates or reactivates a program-level abend exit

within your application program; you can also use this command to cancel a
previously activated exit. For more information see the CICS Application
Programming Reference manual .

266 CICS TS for z/OS: CICS Application Programming Guide

CICS does not allow the use of HANDLE ABEND LABEL in Assembler programs
that do not use DFHEIENT and DFHEIRET. Assembler programs that use the
Language Environment stub CEESTART should either use HANDLE ABEND
PROGRAM or a Language Environment service such as CEEHDLR.

HANDLE ABEND lets you supply your own code to be executed when an abend is
processed. This means that your application can cope with the abnormal situation in
an orderly manner and carry on executing. You provide the user exit programs and
rely on CICS calling them when required.

The flow of control during abend processing is shown in Figure 74 on page 272.

Using PUSH HANDLE and POP HANDLE commands

PUSH HANDLE
Suspends the current effect of HANDLE CONDITION, IGNORE
CONDITION, HANDLE ABEND and HANDLE AID commands.
POP HANDLE
Reinstates the effect of HANDLE CONDITION, IGNORE CONDITION,
HANDLE ABEND and HANDLE AID commands to what they were before
the previous PUSH HANDLE was called.

CICS also keeps a table of conditions for each PUSH HANDLE command which
has not been countermanded by a matching POP HANDLE command.

When each condition occurs, CICS performs the following sequence of tests:
1. If the command has the RESP or NOHANDLE option, control returns to the next
instruction in your application program. Otherwise, CICS scans the condition
table to see what to do.
2. If an entry for the condition exists, this determines the action.
3. If no entry exists and the default action for this condition is to suspend
execution:
a. If the command has the NOSUSPEND or NOQUEUE option, control returns
to the next instruction.
b. If the command does not have one of these options, the task is suspended.
4. If no entry exists and the default action for this condition is to abend, a second
search is made, this time for the ERROR condition:
a. If found, this entry determines the action.
b. If ERROR cannot be found, the task is abended. You can choose to handle
abends. For information about the HANDLE ABEND command, see the
CICS Application Programming Reference.

Note: The OVERFLOW condition on aSEND MAP command is an exception to the

above rules. See the CICS Application Programming Reference for more
information.

The commands ALLOCATE, ENQ, GETMAIN, WRITE JOURNALNAME, WRITE

JOURNALNUM, READQ TD, and WRITEQ TS can all raise conditions for which the
default action is to suspend your application program until the specified resource
becomes available. So, on these commands, you have the NOSUSPEND option to
inhibit this waiting and return immediately to the next instruction in your application
program.

Chapter 17. Dealing with exception conditions 267

Some conditions can occur during the execution of a number of unrelated
commands. If you want the same action for all occurrences, code a single HANDLE
CONDITION command at the start of your program.

Note: As using RESP implies NOHANDLE, be careful when using RESP with the
RECEIVE command, because it overrides the HANDLE AID command as
well as the HANDLE CONDITION command. This means that PF key
responses are ignored, and is the reason for testing them earlier in the
ACCT code. See “Using the HANDLE AID command” on page 495.

268 CICS TS for z/OS: CICS Application Programming Guide

Chapter 18. Abnormal termination recovery
CICS provides a program-level abend exit facility so that you can write exits of your
own which can receive control during abnormal termination of a task. The “cleanup”
of a program that has started but not completed normally is an example of a
function performed by such an abend exit.

Here are some causes of abnormal terminations:

v A user request by, for example:
EXEC CICS ABEND ABCODE(...)
v A CICS request as a result of an invalid user request. For example, an invalid
FREEMAIN request gives the transaction abend code ASCF.
v A program check, in which case the system recovery program (DFHSRP) is
driven, and the task abends with code ASRA.
v An operating system abend, in which case DFHSRP is driven, and the task
abends with code ASRB.
v A looping task, in which case DFHSRP is driven, and the task abends with code
AICA.

Note: If an ASRB or ASRA is detected in CICS code, CICS produces a dump

before calling your HANDLE ABEND exit.

See the CICS Problem Determination Guide for full details about fixing problems,
and see the CICS Messages and Codes for information about the transaction
abend codes for abnormal terminations that are initiated by CICS, their meanings,
and your responses.

The HANDLE ABEND command activates or reactivates a program-level abend exit

within your application program; you can also use this command to cancel a
previously activated exit.

When activating an exit, you must use the PROGRAM option to specify the name of
a program to receive control, or (except for C, C++, and PL/I programs) the LABEL
option to specify a routine label to which control branches when an abnormal
termination condition occurs. Using an ON ERROR block in PL/I is the equivalent of
using the HANDLE ABEND LABEL command.

A HANDLE ABEND command overrides any preceding such command in any

application program at the same logical level. Each application program of a
transaction can have its own abend exit, but only one abend exit at each logical
level can be active. (Logical levels are explained in Chapter 45, “Program control,”
on page 561.)

When a task terminates abnormally, CICS searches for an active abend exit,
starting at the logical level of the application program in which the abend occurred,
and proceeding to successively higher levels. The first active abend exit found, if
any, is given control. This procedure is shown in Figure 74 on page 272, which also
shows how subsequent abend processing is determined by the user-written abend
exit.

If CICS finds no abend exit, it passes control to the abnormal condition program to
terminate the task abnormally. This program invokes the user replaceable program

error program, DFHPEP. See the CICS Customization Guide for programming
information about how to customize DFHPEP.

CICS deactivates the exit upon entry to the exit routine or program to prevent
recursive abends in an abend exit. If you wish to retry the operation, you can
branch to a point in the program that was in control at the time of the abend and
issue a HANDLE ABEND RESET command to reactivate the abend exit. You can
also use this command to reactivate an abend exit (at the logical level of the issuing
program) that was canceled previously by a HANDLE ABEND CANCEL command.
You can suspend the HANDLE ABEND command by means of the PUSH HANDLE
and POP HANDLE commands as described in “Using PUSH HANDLE and POP
HANDLE commands” on page 267.

Note that when an abend is handled, the dynamic transaction backout program is
not be invoked. If you need the dynamic transaction backout program, you take an
implicit or explicit syncpoint or issue SYNCPOINT ROLLBACK or issue an ABEND
command.

Where the abend is the result of a failure in a transaction running in an

IRC-connected system, for example AZI2, the syncpoint processing may abend
ASP1 if it attempts to use the same IRC connection during its backout processing.

The HANDLE ABEND command cannot intercept ASPx or APSJ abend codes.

This chapter describes:

v “Creating a program-level abend exit”
v “Retrying operations” on page 271
v “Trace” on page 272
v “Monitoring” on page 273
v “Dump” on page 274

Creating a program-level abend exit

You can either define abend exits by using RDO or by using the program autoinstall
exit. If you use the autoinstall method, the program definition is not available at the
time of the HANDLE ABEND. This may mean that a program functions differently
the first time it is invoked. If the program is not defined at the time the HANDLE
ABEND is issued, and program autoinstall is active, the security check on the name
of the program is the only one which takes place. Other checks occur at the time
the abend program is invoked. If the autoinstall fails, the task abends APCT and
control is passed to the next higher level.

Abend exit programs can be coded in any supported language, but abend exit
routines must be coded in the same language as their program.

For abend exit routines, the addressing mode and execution key are set to the
addressing mode and execution key in which the HANDLE ABEND command has
been issued.

Upon entry to an abend exit program, no addressability can be assumed other than
that normally assumed for any application program coded in that language. There
are no register values for C, C++, or PL/I languages as these languages do not
support HANDLE ABEND label.

270 CICS TS for z/OS: CICS Application Programming Guide

Upon entry to an abend exit routine, the register values are:
COBOL
Control returns to the HANDLE ABEND command with the registers restored; a
COBOL GOTO is then executed.
Assembler
Reg 15
Abend label.
Reg 0-14
Contents at the time of the last CICS service request.

There are three means of terminating processing in an abend exit routine or

program, as listed below. It is recommended that when abend routines and
programs are called by CICS internal logic they should terminate with an abend
because further processing is likely to cause more problems.
1. Using a RETURN command to indicate that the task is to continue running with
control passed to the program on the next higher logical level. If no such
program exists, the task is terminated normally, and any recoverable resources
are committed.
2. Using an ABEND command to indicate that the task is to be abnormally
terminated with control passed either to an abend exit specified for a program
on a higher logical level or, if there is not one, to the abnormal condition
program for abnormal termination processing.
3. Branching to retry an operation. When you are using this method of retrying an
operation, and you want to reenter the original abend exit routine or program if
a second failure occurs, the abend exit routine or program should issue the
HANDLE ABEND RESET command before branching. This is because CICS
has disabled the exit routine or program to prevent it reentering the abend exit.

In the case of an abend caused by a timeout on an outstanding RECEIVE

command, it is important to let the CICS abend continue, so that CICS can cancel
the RECEIVE.

Retrying operations
If an abend occurs during the invocation of a CICS service, you should be aware
that issuing a further request for the same service may cause unpredictable
results, because the reinitialization of pointers and work areas, and the freeing of
storage areas in the exit routine, may not have been completed.

You should not try to recover from ATNI or ATND abends by attempting further I/O
operations. Either of these abends results in a TERMERR condition, requiring the
session to be terminated in all cases. You should not try to issue terminal control
commands while recovering from an AZCT abend, or an AZIG abend, as CICS has
not fully cleaned up from the RTIMOUT, and an indefinite wait can occur.

If intersystem communication is being used, an abend in the remote system might

cause a branch to the specified program or label, but subsequent requests to use
the same resource in the remote system might fail. If an abend occurs as a result of
a failure in the connection to the remote system, subsequent requests to use any
resources in the remote system might fail.

If an abend occurs as a result of a BMS command, control blocks are not tidied up
before control is returned to the BMS program, and results are unpredictable if the
command is retried.

Chapter 18. Abnormal termination recovery 271

Task ABEND

Is there Deactivate Transfer control

an exit active Yes
the exit to program or
at this level? branch to label

Is
Yes Action taken in
application
Terminate the task exit program
program at highest
abnormally or routine ABEND
level?

No RETURN

Is
Look at the next application Yes
higher level program at highest Terminate the task
normally
level?

Exit to program
at the next higher
level

Figure 74. ABEND exit processing

Trace
CICS trace is a debugging aid for application programmers, system programmers,
and IBM field engineers. It produces trace entries in response to trace commands.
The trace entries can be sent to any trace destination that is currently active. The
destinations are:
v Internal trace table
v Auxiliary trace data set
v Generalized trace facility (GTF) data set

For information about trace destinations, see the CICS Problem Determination
Guide.

You can:
v Specify user trace entry points (ENTER TRACENUM ). (The earlier ENTER
TRACEID command is supported for compatibility purposes. See the CICS for
MVS/ESA 4.1 Migration Guide for details.)
v Switch CICS internal trace on or off using the SET TRACEDEST, SET
TRACEFLAG, and SET TRACETYPE commands.

272 CICS TS for z/OS: CICS Application Programming Guide

Trace entry points
The points at which trace entries are produced during CICS operation are of four
types: system trace entry points, user trace entry points, exception trace entry
points, and user exception trace entry points. See the CICS Problem Determination
Guide for more information about tracing.

System trace entry points

These are points within CICS at which trace control requests are made. The most
important system trace entry points for application programmers are for the EXEC
interface program. These produce entries in the trace table whenever a CICS
command is processed.

Two trace entries are made: the first when the command is issued, and the second
when CICS has performed the required function and is about to return control to
your application program. Between them, these two trace entries allow you to trace
the flow of control through an application, and to check which exception conditions,
if any, occurred during its execution. The ABEND, RETURN, TRACEFLAG, and
XCTL commands produce single entries only.

User trace entry points

These are additional points within your application program that you can include in
the trace table to allow complete program debugging. For example, you could
specify an entry for a program loop containing a counter value showing the number
of times that the loop had been entered.

A trace entry is produced wherever the ENTER TRACENUM command is run. Each
trace entry request, which can be given a unique identifier, causes data to be
placed in the trace table.

Exception trace entry points

These are additional points where CICS has detected an exception condition.
These are made from specific points in the CICS code, and data is taken from
areas that might provide some information about the cause. Exception trace entry
points do not have an associated “level” attribute; trace calls are only ever made
from them when exception conditions occur.

User exception trace entry points

These are trace entries that are always written to the internal trace table (even if
internal tracing is set off), but are written to other destinations only if they are
active. You can identify them by the character string *EXCU in any formatted trace
output produced by the CICS utility programs. See the CICS Problem Determination
Guide for general information about user exception trace entry points; programming
information is in the CICS Customization Guide.

Monitoring
CICS monitoring provides information about the performance of your application
transactions.

You should use the MONITOR command for user event monitoring points.

In addition to the monitoring data collected from a system defined elsewhere,

monitoring points (EMPs) within CICS, a user application program can contribute
data to user fields within the CICS monitoring records. You can do this by using the
MONITOR POINT command to invoke user-defined EMPs. At each of these EMPs,

Chapter 18. Abnormal termination recovery 273

you can add or change up to 4096 bytes of your own data in each performance
monitoring record. In those 4096 bytes, you can have any combination of the
following:
v In the range 0 through 256 counters
v In the range 0 through 256 clocks
v A single 256-byte character string

For example, you could use these user EMPs to count the number of times a
certain event occurs, or to time the interval between two events. For programming
information about monitoring, see the CICS Customization Guide; for background
information, see the CICS Performance Guide.

Dump
CICS dump allows you to specify areas of main storage to be dumped, by means of
the DUMP TRANSACTION , onto a sequential data set, which can be either on disk
or tape.

The PERFORM DUMP command allows you to request a system dump. See the
CICS System Programming Reference manual for programming information about
PERFORM DUMP.

You can format the contents of the dump data set and you can print them offline
using the CICS dump utility program (DFHDU640) for transaction dumps or the
interactive problem control system (IPCS) for system dumps. Instructions on using
these programs are given in the CICS Operations and Utilities Guide.

Only one dump control command is processed at a time. If you issue additional
dump control commands, while another task is taking a transaction dump, activity
within the tasks associated with those commands is suspended until the dump is
completed. Remaining dump commands are processed in the order in which they
are made. Using the DUMP TRANSACTION command causes some fields (for
example, EIBFN and EIBRCODE) in the EIB and the TCA to be overwritten.See the
CICS Application Programming Reference manual for programming information
about DUMP TRANSACTION.

Options on the DUMP TRANSACTION command allow you to dump the following
areas of main storage in various combinations:
v Task-related storage areas: selected main storage areas related to the requesting
task. You would normally use a dump of these areas to test and debug your
application program. (CICS automatically provides this service if the related task
is terminated abnormally.)
v CICS control tables:
– File control table (FCT)
– Program control table (PCT)
– Processing program table (PPT)
– System initialization table (SIT)
– Terminal control table (TCT)
A dump of these tables is typically the first dump taken in a test in which the
base of the test must be established; subsequent dumps are usually of the
task-related storage type.
v It is sometimes appropriate during execution of a task to have a dump of both
task-related storage areas and CICS control tables. Specifying one CICS control
tables dump and a number of task-related storage dumps is generally more

274 CICS TS for z/OS: CICS Application Programming Guide

efficient than specifying a comparable number of complete dumps. However, you
should not use this facility excessively because CICS control tables are primarily
static areas.
v In addition, the DUMP TRANSACTION command used with the three options,
SEGMENTLIST, LENGTHLIST, and NUMSEGMENTS, allows you to dump a
series of task-related storage areas simultaneously.

Program storage is not dumped for programs defined with the attribute
RELOAD(YES).

You also get a list of the CICS nucleus modules and active PPT programs, indexed
by address, at the end of the printed dump.

Chapter 18. Abnormal termination recovery 275

276 CICS TS for z/OS: CICS Application Programming Guide
Chapter 19. The QUERY SECURITY command
QUERY SECURITY is effective with RACF® or any equivalent external security
manager (ESM). You can use this command to query whether the terminal user has
access to resources that are defined to the external security manager. These can
be:
v Resources in CICS resource classes
v Resources in user-defined resource classes

The terminal user in this context is the user invoking the transaction that contains
the QUERY SECURITY command.

Java and C++

The application programming interface described in this chapter is the EXEC
CICS API, which is not used in Java programs. For information about Java
programs using the JCICS classes to access security control services, see the
Java Applications in CICS component of the CICS Information Center and the
JCICS Javadoc html documentation. For information about C++ programs
using the CICS C++ classes, see the CICS C++ OO Class Libraries manual.

In response to a QUERY SECURITY command, CICS returns information about the

terminal user’s security authorizations. CICS obtains this information from the
external security manager. You can code the application to proceed in different
ways depending on the user’s permitted accesses.

You specify the type of resource that you are querying by the CICS resource type
name. For example, if you want to query a user’s authorization to access a file, you
can specify RESTYPE(‘FILE’). To identify a particular file within the type, you
specify the RESID parameter.

Using the QUERY SECURITY command

A typical use of the QUERY SECURITY command is to check whether a user is
authorized to use a particular transaction before displaying the transaction code in
a menu.

Security protection at the record or field level

Another use for QUERY SECURITY is to enable you to control access to data at
the record or field level. The normal CICS resource security checking for file
resources, for example, works only at the file level. To control access to individual
records, or even fields within records, you can use QUERY SECURITY. For this
purpose, your security administrator must define resource profile names, with
appropriate access authorizations, for the records or fields that you want to protect.
These profiles are defined in user resource classes defined by the administrator,
not in CICS resource classes.

To query these classes and resources, the QUERY SECURITY command uses the
RESCLASS and RESID options (RESCLASS and RESTYPE are mutually exclusive
options). You can use the CVDA values returned by QUERY SECURITY to
determine whether to access the record or field.

CICS-defined resource identifiers
In all cases except for the SPCOMMAND resource type, the resource identifiers are
user-defined. However, for the SPCOMMAND type, the identifiers are fixed by
CICS. The CICS RACF Security Guide details the possible RESID values for the
SPCOMMAND resource type.

SEC system initialization parameter

The setting of the SEC system initialization parameter affects the CVDA values
returned by the QUERY SECURITY command. The SEC system initialization
parameters are described in more detail in the CICS RACF Security Guide.

Programming hints
v A transaction can use the QUERY SECURITY command to query a number of
resources in order to prepare a list of resources to which the terminal user has
access. The use of this technique could generate up to four resource violation
messages for each query on a resource that the transaction is not authorized to
access. These messages appear on the system console, the CSCS TD queue,
and the SMF log data set. If you want to suppress these messages, code
NOLOG in the QUERY SECURITY command.
v If a transaction accesses the same resource many times in one execution, you
can probably improve performance by defining the transaction with RESSEC(NO)
in the transaction resource definition. You can then code the transaction to issue
a single QUERY SECURITY command, and to permit access to the resource
according to the CVDA values returned. For detailed guidance, see the CICS
RACF Security Guide.

278 CICS TS for z/OS: CICS Application Programming Guide

Part 4. Data Management
Chapter 20. An overview of file control . . . . . . . . . . . . . . . 283
VSAM data sets . . . . . . . . . . . . . . . . . . . . . . . . 283
Key-sequenced data set (KSDS) . . . . . . . . . . . . . . . . . 283
Entry-sequenced data set (ESDS) . . . . . . . . . . . . . . . . 284
Relative record data set (RRDS) . . . . . . . . . . . . . . . . . 284
Empty data sets . . . . . . . . . . . . . . . . . . . . . . . 284
VSAM alternate indexes . . . . . . . . . . . . . . . . . . . . 285
Accessing files in RLS mode . . . . . . . . . . . . . . . . . . 285
Some RLS limitations . . . . . . . . . . . . . . . . . . . . 286
BDAM data sets . . . . . . . . . . . . . . . . . . . . . . . . 286
CICS shared data tables . . . . . . . . . . . . . . . . . . . . . 287
Coupling facility data tables . . . . . . . . . . . . . . . . . . . . 288
Coupling facility data table models . . . . . . . . . . . . . . . . 289
Techniques for sharing data . . . . . . . . . . . . . . . . . . . . 290
Using CICS commands to read records . . . . . . . . . . . . . . . 292
Direct reading (using READ command) . . . . . . . . . . . . . . 293
Direct reading from a KSDS . . . . . . . . . . . . . . . . . 293
Direct reading from an ESDS . . . . . . . . . . . . . . . . . 293
Direct reading from an RRDS . . . . . . . . . . . . . . . . . 293
Direct reading by way of a path . . . . . . . . . . . . . . . . 293
Read integrity (in RLS mode) . . . . . . . . . . . . . . . . . 294
Sequential reading (browsing) . . . . . . . . . . . . . . . . . . 294
Browsing through a KSDS . . . . . . . . . . . . . . . . . . 295
Browsing through an ESDS . . . . . . . . . . . . . . . . . . 296
Browsing through an RRDS . . . . . . . . . . . . . . . . . . 296
Browsing using a path . . . . . . . . . . . . . . . . . . . . 296
Browse integrity (in RLS mode) . . . . . . . . . . . . . . . . 296
Ending the browse . . . . . . . . . . . . . . . . . . . . . 296
Simultaneous browse operations . . . . . . . . . . . . . . . . 296
Skip-sequential processing . . . . . . . . . . . . . . . . . . . 296
Using CICS commands to update records . . . . . . . . . . . . . . 297
Using CICS commands to delete records . . . . . . . . . . . . . . . 298
Deleting single records . . . . . . . . . . . . . . . . . . . . 298
Updating and deleting records in a browse (VSAM RLS only) . . . . . 298
Deleting groups of records (generic delete) . . . . . . . . . . . . . 299
Read integrity . . . . . . . . . . . . . . . . . . . . . . . . 299
Using CICS commands to add records . . . . . . . . . . . . . . . 299
Adding to a KSDS . . . . . . . . . . . . . . . . . . . . . . 299
Adding to an ESDS . . . . . . . . . . . . . . . . . . . . . . 300
Adding to an RRDS. . . . . . . . . . . . . . . . . . . . . . 300
Records that are already locked . . . . . . . . . . . . . . . . . 300
Specifying record length . . . . . . . . . . . . . . . . . . . . 300
Sequential adding of records (WRITE MASSINSERT command) . . . . . 300
File control command options . . . . . . . . . . . . . . . . . . . 301
The RIDFLD option . . . . . . . . . . . . . . . . . . . . . . 301
The INTO and SET options . . . . . . . . . . . . . . . . . . . 301
The FROM option . . . . . . . . . . . . . . . . . . . . . . 302
The TOKEN option . . . . . . . . . . . . . . . . . . . . . . 302
KEYLENGTH option for remote data sets. . . . . . . . . . . . . . 302
Transaction deadlocks . . . . . . . . . . . . . . . . . . . . . . 303
VSAM-detected deadlocks (RLS only) . . . . . . . . . . . . . . . 304
Rules for avoiding deadlocks . . . . . . . . . . . . . . . . . . 305

Chapter 21. File control—VSAM considerations . . . . . . . . . . . 307
VSAM record identification . . . . . . . . . . . . . . . . . . . . 307
Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Relative byte address (RBA) and relative record number (RRN) . . . . . 307
RBA . . . . . . . . . . . . . . . . . . . . . . . . . . 307
RRN . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Locking of VSAM records in recoverable files . . . . . . . . . . . . . 308
Update locks and delete locks (non-RLS mode only) . . . . . . . . . 308
RLS Record level locking . . . . . . . . . . . . . . . . . . . . 309
Exclusive locks and shared locks . . . . . . . . . . . . . . . . . 309
Exclusive locks . . . . . . . . . . . . . . . . . . . . . . 310
Shared locks . . . . . . . . . . . . . . . . . . . . . . . 310
Lock duration . . . . . . . . . . . . . . . . . . . . . . . 310
Active and retained states for locks . . . . . . . . . . . . . . . 311
Conditional VSAM file update requests . . . . . . . . . . . . . . . 312
File control implementation of NOSUSPEND . . . . . . . . . . . . 312
CICS locking for writing to ESDS . . . . . . . . . . . . . . . . . . 312

Chapter 22. File control—BDAM considerations . . . . . . . . . . . 315

Chapter 23. Database control . . . . . . . . . . . . . . . . . . 319

DL/I databases . . . . . . . . . . . . . . . . . . . . . . . . 319
DB2 databases . . . . . . . . . . . . . . . . . . . . . . . . 319
Requests to DB2 . . . . . . . . . . . . . . . . . . . . . . . 319

Chapter 24. CICS documents . . . . . . . . . . . . . . . . . . 321

Using the DOCUMENT programming interface . . . . . . . . . . . . . 321
Creating a document . . . . . . . . . . . . . . . . . . . . . 321
The BINARY option . . . . . . . . . . . . . . . . . . . . . 321
The TEXT option . . . . . . . . . . . . . . . . . . . . . . 321
The FROMDOC option . . . . . . . . . . . . . . . . . . . 322
Setting up document templates . . . . . . . . . . . . . . . . . . 322
Templates in a partitioned data set . . . . . . . . . . . . . . . . 322
Templates in a CICS program . . . . . . . . . . . . . . . . . . 323
Templates in CICS files, z/OS UNIX System Services HFS files, temporary
storage, or transient data . . . . . . . . . . . . . . . . . . . 323
Creating templates in exit programs . . . . . . . . . . . . . . . . 324
Programming with documents and document templates . . . . . . . . . 325
Symbols and symbol lists . . . . . . . . . . . . . . . . . . . 325
Setting symbol values . . . . . . . . . . . . . . . . . . . . . 326
Embedded template commands . . . . . . . . . . . . . . . . . 328
Using templates in your application . . . . . . . . . . . . . . . . 329
The lifespan of a document . . . . . . . . . . . . . . . . . . . 330
Retrieving the document without control information . . . . . . . . . 331
Constructing a document . . . . . . . . . . . . . . . . . . . . 332
Using Bookmarks . . . . . . . . . . . . . . . . . . . . . . 334
Replacing data in the document . . . . . . . . . . . . . . . . 335
Code page conversion for documents . . . . . . . . . . . . . . . 335

280 CICS TS for z/OS: CICS Application Programming Guide

Chapter 25. Named counter servers . . . . . . . . . . . . . . . . 337
The named counter fields . . . . . . . . . . . . . . . . . . . . 337
Named counter pools . . . . . . . . . . . . . . . . . . . . . . 338
Named counter options table . . . . . . . . . . . . . . . . . . 338
Using the named counter EXEC interface . . . . . . . . . . . . . . 339
Using the named counter CALL interface . . . . . . . . . . . . . . . 341
Application programming considerations . . . . . . . . . . . . . . 341
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Checking for result overflow. . . . . . . . . . . . . . . . . . 349
Example of DFHNCTR calls with null parameters . . . . . . . . . . 349
Return codes . . . . . . . . . . . . . . . . . . . . . . . . 351
Named counter recovery . . . . . . . . . . . . . . . . . . . . . 354

Part 4. Data Management 281

282 CICS TS for z/OS: CICS Application Programming Guide
Chapter 20. An overview of file control
CICS data management services have traditionally been known as CICS file
control. CICS file control l offers you access to data sets that are managed by
either the virtual storage access method (VSAM) or the basic direct access method
(BDAM).

CICS file control lets you read, update, add, and browse data in VSAM and BDAM
data sets and delete data from VSAM data sets. You can also access CICS shared
data tables and coupling facility data tables using file control.

A CICS application program reads and writes its data in the form of individual
records. Each read or write request is made by a CICS command.

To access a record, the application program must identify both the record and the
data set that holds it. It must also specify the storage area into which the record is
to be read or from which it is to be written.

This chapter describes:

v “VSAM data sets”
v “BDAM data sets” on page 286
v “CICS shared data tables” on page 287
v “Coupling facility data tables” on page 288
v “Techniques for sharing data” on page 290
v “Using CICS commands to read records” on page 292
v “Using CICS commands to update records” on page 297
v “Using CICS commands to delete records” on page 298
v “Using CICS commands to add records” on page 299
v “File control command options” on page 301
v “Transaction deadlocks” on page 303

VSAM data sets

CICS supports access to the following types of data set:
v Key-sequenced data set (KSDS)
v Entry-sequenced data set (ESDS)
v Relative record data set (RRDS) (both fixed and variable record lengths)

VSAM data sets are held on direct access storage devices (DASD) auxiliary
storage. VSAM divides its data set storage into control areas (CA), which are
further divided into control intervals (CI). Control intervals are the unit of data
transmission between virtual and auxiliary storage. Each one is of fixed size and, in
general, contains a number of records. A KSDS or ESDS can have records that
extend over more than one control interval. These are called spanned records.

Key-sequenced data set (KSDS)

A key-sequenced data set has each of its records identified by a key. (The key of
each record is simply a field in a predefined position within the record.) Each key
must be unique in the data set.

When the data set is initially loaded with data, or when new records are added, the
logical order of the records depends on the collating sequence of the key field. This
also fixes the order in which you retrieve records when you browse through the
data set.

To find the physical location of a record in a KSDS, VSAM creates and maintains
an index. This relates the key of each record to the record’s relative location in the
data set. When you add or delete records, this index is updated accordingly.

With releases of DFSMS/MVS® 1.4 and later, a data set can be greater than 4GB in
size if it is defined as extended format and extended addressability in the storage
class. CICS supports, in both RL and non-RLS mode, KSDS data sets that are
defined with these extended attributes.

Entry-sequenced data set (ESDS)

An entry-sequenced data set is one in which each record is identified by its
relative byte address (RBA).

Records are held in an ESDS in the order in which they were first loaded into the
data set. New records added to an ESDS always go after the last record in the data
set. You may not delete records or alter their lengths. After a record has been
stored in an ESDS, its RBA remains constant. When browsing, records are
retrieved in the order in which they were added to the data set.

With releases of DFSMS/MVS 1.5 and later, a data set can be greater than 4GB in
size if it is defined as extended format and extended addressability in the storage
class. However, CICS does not support ESDS data sets that are defined with these
extended attributes. Attempts to open data sets defined with the extended attribute
fail with error message DFHFC0966, codes 8504, 0008,0068.

Relative record data set (RRDS)

A relative record data set has records that are identified by their relative record
number (RRN). The first record in the data set is RRN 1, the second is RRN 2, and
so on.

Records in an RRDS can be fixed or variable length records, and the way in which
VSAM handles the data depends on whether the data set is a fixed or variable
RRDS. A fixed RRDS has fixed-length slots predefined to VSAM, into which records
are stored. The length of a record on a fixed RRDS is always equal to the size of
the slot. VSAM locates records in a fixed RRDS by multiplying the slot size by the
RRN (which you supply on the file control request), to calculate the byte offset from
the start of the data set.

A variable RRDS, on the other hand, can accept records of any length up to the
maximum for the data set. In a variable RRDS VSAM locates the records by means
of an index.

A fixed RRDS generally offers better performance. A variable RRDS offers greater
function.

With releases of DFSMS/MVS 1.5 and later, a data set can be greater than 4GB in
size if it is defined as extended format and extended addressability in the storage
class. However, CICS does not support RRDS or VRRDS data sets that are defined
with these extended attributes. Attempts to open data sets defined with the
extended attribute fail with error message DFHFC0966, codes 8504, 0008,0068.

Empty data sets

An empty data set is a data set that has not yet had any records written to it. VSAM
imposes several restrictions on an empty data set that is opened in non-RLS

284 CICS TS for z/OS: CICS Application Programming Guide

access mode. However, CICS hides all these restrictions from you, allowing you to
use an empty data set in the same way as a data set that contains data, regardless
of the access mode.

VSAM alternate indexes

Sometimes you want to access the same set of records in different ways. For
example, you may have records in a personnel data set that have as their key an
employee number. No matter how many Smiths you have, each of them has a
unique employee number. Think of this as the primary key.

If you were producing a telephone directory from the data set, you would want to
list people by name rather than by employee number. You can identify records in a
data set with a secondary (alternate) key instead of the primary key described
above. So the primary key is the employee number, and the employee name is the
alternate key. Alternate keys are just like the primary key in a KSDS—fields of
fixed length and fixed position within the record. You can have any number of
alternate keys per base file and, unlike the primary or base key, alternate keys need
not be unique.

To continue the personnel example, the employee’s department code might be

defined as a further alternate key.

VSAM allows KSDS and ESDS (but not RRDS) data sets to have alternate keys.
When the data set is created, one secondary or alternate index is built for each
alternate key in the record and is related to the primary or base key. To access
records using an alternate key, you must define a further VSAM object, an
alternate index path. The path then behaves as if it were a KSDS in which records
are accessed using the alternate key.

When you update a record by way of a path, the corresponding alternate index is
updated to reflect the change. However, if you update the record directly by way of
the base, or by a different path, the alternate index is only updated if it has been
defined to VSAM (when created) to belong to the upgrade set of the base data set.
For most applications, you probably want your alternate index to be in the upgrade
set.

A CICS application program disregards whether the file it is accessing is a path or

the base. In a running CICS system, access to a single base data set can be made
by way of the base and by any of the paths defined to it, if each access route is
defined in the file control table (FCT).

It is also possible for a CICS application program to access a file that has been
directly defined as an alternate index rather than a path. This results in index data
being returned to the application program rather than file data. This operation is not
supported for files opened in record-level sharing (RLS) mode.

Accessing files in RLS mode

Record-level sharing (RLS) is a VSAM function, provided by DFSMS Version 1
Release 3 and later releases, that enables VSAM data to be shared, with full
update capability, between many applications running in many CICS regions.

With RLS, CICS regions that share VSAM data sets can reside in one or more MVS
images within an MVS parallel sysplex. RLS also provides some benefits when data
sets are being shared between CICS regions and batch jobs.

Chapter 20. An overview of file control 285

If you open a file in RLS mode, locking takes place at the record level instead of
the Control-Interval level, thus reducing the risk of deadlocks.

CICS supports record-level sharing (RLS) access to the following types of VSAM
data set:
v Key sequenced data sets (KSDS). Note that if you are using KSDS, you cannot
use the relative byte address (RBA) to access files.
v Entry sequenced data sets (ESDS). Note that although RLS access mode is
permitted for entry sequenced data sets (ESDS), it is not recommended, as it
can have a negative effect on the performance and availability of the data set
when you are adding records. (See the CICS Performance Guide).
v Relative record data sets (RRDS), for both fixed and variable length records.

Note: If you issue the SET FILE EMPTY command for a file that specifies RLS
mode, the request is accepted but is ignored all the time the file is opened in
RLS mode. If you close and switch the file to non-RLS mode, the data set is
then reset to empty (provided it is defined as reusable on its IDCAMS
definition).

Some RLS limitations

Most types of data set are eligible to participate in VSAM record level sharing and
most CICS applications can benefit from this mode of access. However, there are
some limitations that could affect some applications. The following types of file, data
set, or method of access are not supported in RLS mode:
v RBA access to a KSDS
v Key-range data sets
v Temporary data sets
v VSAM clusters with the IMBED attribute
v Direct opening of an alternate index
v Opening individual components of a cluster
v Access to catalogs or to VVDS data sets
v CICS-maintained data tables
v Hiperbatch™

BDAM data sets

CICS supports access to keyed and nonkeyed BDAM data sets. BDAM support
uses the physical nature of a record on a DASD device. BDAM data sets consist of
unblocked records with the following format:

Physical
Count (recorded) Data
key

Physical record

Figure 75. Format of unblocked records in a BDAM data set

Keyed BDAM files have a physical key identifying the BDAM record. The count area
contains the physical key length, the physical data length, and the record’s data
location.

CICS can define a further structure on top of BDAM data sets, introducing the
concept of blocked-data sets:

286 CICS TS for z/OS: CICS Application Programming Guide

Count Physical Data
key

logrec 1 logrec 2

Physical record

Figure 76. Blocked-data set

The data portion of the physical record is viewed as a block containing logical
records. CICS supports the retrieval of logical records from the data part of the
physical record. CICS also supports unblocked records (where the structure reverts
to the original BDAM concept of one logical record per physical record).

To retrieve data from a physical record in a BDAM file under CICS, a record
identification field (RIDFLD) has to be defined to specify how the physical record
should be retrieved. This may be done using the physical key, by relative address,
or by absolute address.

If the data set is defined to CICS as being blocked, individual records within the
block can be retrieved (deblocked) in two addressing modes: by key or by relative
record.

Deblocking by key uses the key of the logical record (that is, the key contained in
the logical record) to identify which record is required from the block. Deblocking by
relative record uses the record number in the block, relative to zero, of the record to
be retrieved.

You specify the key or relative record number used for deblocking in a subfield of
the RIDFLD option used when accessing CICS BDAM files. The addressing mode
for CICS BDAM files is set in the FCT using the RELTYPE keyword.

For more details about record identification and BDAM record access, see
Chapter 22, “File control—BDAM considerations,” on page 315.

CICS shared data tables

The file control commands can access shared data tables. Shared data tables offer
a method of constructing, maintaining, and gaining rapid access to data records
contained in tables held in virtual storage, above the 16MB line. Each shared data
table is associated with a VSAM KSDS, known as its source data set. For more
information about shared data tables, see the CICS Shared Data Tables Guide.

A table is defined using the CEDA DEFINE FILE panel. When a table is opened,
CICS builds it by extracting data from the table’s corresponding source data set and
loading it into virtual storage above the 16MB line.

CICS supports two types of shared data table, as follows:

CICS-maintained tables (CMTs)
This type of data table is kept in synchronization with its source data set by
CICS. All changes to the data table are reflected in the source data set.
Similarly all changes to the source data set are reflected in the data table.
Note that the source for a CICS-maintained data table cannot be a file
opened in RLS access mode.

Chapter 20. An overview of file control 287

User-maintained tables (UMTs)
This type of data table is completely detached from its source data set after
it has been loaded. Changes to the table are not automatically reflected in
the source data set.

The full file control API appropriate to VSAM KSDS data sets is supported for
CICS-maintained data tables. Requests that cannot be satisfied by reference to the
data table result in calls to VSAM to access the source data set. Tables defined to
be recoverable are supported with full integrity.

A subset of the file control API is supported for user-maintained tables. For
programming information about the commands, you should see the CICS
Application Programming Reference manual where they are listed separately under
the file control command name, followed by UMT. For example, the information on
writing a record to a user-maintained table is given under WRITE(UMT). A table
defined as recoverable participates in dynamic transaction backout but is not
recovered at restart or XRF takeover.

Coupling facility data tables

The CICS file control commands can access coupling facility data tables (CFDTs).
Coupling facility data tables provide a method of file data sharing, without the need
for a file-owning region, and without the need for VSAM RLS support. CICS
coupling facility data table support is designed to provide rapid sharing of working
data across a sysplex, with update integrity. The data is held in a coupling facility, in
a table that is similar in many ways to a shared user-maintained data table. A
coupling facility data table is different from a UMT in one important respect in that
initial loading from a VSAM source data set is optional . You can specify LOAD(NO)
and load the table by writing data directly from a user application program. The API
used to store and retrieve the data is based on the file control API used for
user-maintained data tables. Read access and write access to CFDTs have similar
performance, making this form of table particularly useful for informal shared data.
Informal shared data is characterised as:
v Data that is relatively short-term in nature (it is either created as the application is
running, or is initially loaded from an external source)
v Data volumes that are not usually very large
v Data that needs to be accessed fast
v Data of which the occasional loss can be tolerated by user applications
v Data that commonly requires update integrity.

Typical uses might include sharing scratchpad data between CICS regions across a
sysplex, or sharing of files for which changes do not have to be permanently saved.
There are many different ways in which applications use informal shared data, and
most of these could be implemented using coupling facility data tables. Coupling
facility data tables are particularly useful for grouping data into different tables,
where the items can be identified and retrieved by their keys. For example, you
could use a record in a coupling facility data table to maintain the next free order
number for use by an order processing application. Other examples are:
v Look-up tables of telephone numbers or the numbers of stolen credit cards
v Working data consisting of a few items, such as a subset of customers from a
customer list
v Information that is specific to the user of the application, or that relates to the
terminal from which the application is being run
v Data extracted from a larger file or database for further processing.

288 CICS TS for z/OS: CICS Application Programming Guide

Coupling facility data tables allow various types of access to your informal data:
read-only, single updater, multiple updaters, sequential access, random access,
random insertion and deletion.

For many purposes, because it is global in scope, coupling facility data tables can
offer significant advantages over resources such as the CICS common work area
(CWA).

To an application program, a CFDT appears much like a sysplex-wide

user-maintained data table: a CFDT is accessed using the same subset of the API
as a UMT (that is, the full file control API except for the MASSINSERT and RBA
options). However, a CFDT is restricted to a maximum key-length of 16 bytes.

Note the following comparisons with user-maintained data tables:

v Updates to a CFDT, like updates to a UMT, are not reflected in the base VSAM
data set (if the table was initially loaded from one). Updates are made to the
CFDT only.
v A CFDT is loaded once only, when the table is first created in the coupling facility
data table, and remains in existence in the coupling facility, even when the last
file referring to the CFDT is closed (whereas a UMT is deleted each time the
owning region terminates). You can force a reload of a CFDT from the original
source data set only by first deleting the table from the CFDT pool, using a
CFDT server DELETE TABLE command. The first file opened against the CFDT
after the delete operation causes the server to reload the table.

Note: A coupling facility data table pool is defined as a coupling facility list
structure, and can hold more than one data table (see the CICS System
Definition Guide for information about creating a list structure for coupling
facility data tables).
v The access rules for a UMT that is in the course of loading allow any direct read
request to be satisfied either from the table (if the record has already been
loaded) or from the source data set, but reject any update request, or imprecise
read or browse request, with the LOADING condition. For a CFDT, any request is
allowed during loading, but requests succeed only for records that are within the
key range already loaded.

Coupling facility data table models

There are two models of coupling facility data table:
Contention model
This gives optimal performance, but requires programs that are written to
handle the situation where the data has been changed since it issued a
read-for-update request. The new CHANGED response can occur on a
REWRITE or DELETE command. There is also a new use for the existing
NOTFND response, which may be returned to indicate to the application
program that the record has been deleted since the program issued the
read-for-update request.

Note: It might be possible to use existing programs with the contention

model if you are sure they cannot receive the CHANGED or
NOTFND exceptions on a REWRITE or DELETE. An example of this
could be where an application program operates only on records that
relate to the user of the program, and therefore no other user could
be updating the same records.

Chapter 20. An overview of file control 289

Locking model
This model is API-compatible with existing programs that conform to the
UMT subset of the file control API. The locking model can be:
Non-recoverable
For updates to non-recoverable CFDTs, locks do not last until
syncpoint (they are released on completion of the file control
request) and updates are not backed out if a unit of work fails
Recoverable
CFDTs are recoverable in the event of a unit of work failure, and in
the event of a CICS region failure, a CFDT server failure, and an
MVS failure (updates made by units of work that were in-flight at
the time of the failure are backed out).
The recoverable locking model supports in-doubt and backout
failures: if a unit of work fails when backing out an update to the
CFDT, or if it fails in-doubt during syncpoint processing, the locks
are converted to retained locks and the unit of work is shunted.
CFDTs cannot be forward recoverable. A CFDT does not survive
the loss of the CF structure in which it resides.

You specify the update model you want for each table on its file resource definition,
enabling different tables to use different models.

Techniques for sharing data

This topic indicates when you should consider using a coupling facility data table by
comparing, in tabular form, the various CICS techniques that you can use for
different situations.
Table 19. Techniques for sharing scratchpad data
Constraints and factors Single Region Single MVS Sysplex
Technique no longer
recommended (too TWA — —
restrictive)
| Recommended method for
| COMMAREA or COMMAREA or COMMAREA or
| single area for each
| channel channel channel
| transaction
Existing application
programs use temporary Local TS queue Remote TS queue Shared TS queue
storage (TS) queues
Existing programs use
UMT
Random insert and CFDT (contention
UMT Remote UMT
delete required model)
Multiple types of
data stored

In Table 19, different techniques are considered for passing scratchpad data
between phases of a transaction, where only one task is accessing the data at a
time, but the data may be passed from a task in one region to a task in another.
Note that ‘remote UMT’ means a shared user-maintained data table that is
accessed from AORs either by function shipping where necessary (that is, for
update accesses) or by SDT cross-memory sharing for non-update accesses. The
table shows that, within a Parallel Sysplex®, a coupling facility data table is the best

290 CICS TS for z/OS: CICS Application Programming Guide

solution for random insertion and deletion of data, and where multiple types of data
need to be stored. Without these constraints, shared TS queues are a more
appropriate choice if the application programs are already using temporary storage.
Table 20. Techniques for sharing queues of data
Constraints and factors Single Region Single MVS Sysplex
Read-only at head,
Local transient
write-only at tail Remote TD Remote TD
data (TD)
Triggering required
Process batches of items Remote TS or remote Shared TS or
TS queue or UMT
UMT CFDT
Delete each item after
processing. Random insert UMT Remote UMT CFDT
and delete required.

In Table 20, different techniques for sharing queues of data are shown, where
information is stored in a specific sequence, to be processed by another application
program or task in the same sequence. The CICS transient data and temporary
storage queue facilities are recommended in the majority of cases, with a few
instances where data tables provide a more appropriate solution for handling
sequenced data.
Table 21. Techniques for sharing control records
Constraints and factors Single Single MVS Sysplex
Region
Technique no longer
CWA MVS CSA —
recommended
Single updating region, Shared TS queue or
TS queue or Remote TS queue or
single record CFDT (contention
UMT UMT
model)
Multiple updating regions or
UMT Remote UMT CFDT
multiple records

In Table 21, different techniques for managing control records are shown. This
illustrates where a central control record is used to make information available to all
transactions. For example, this may contain the next unused order number, or
customer number, to make it easier for programs to create new records in a keyed
file or database. (For this type of application, you should also consider the named
counter function, which is also a sysplex-wide facility. See Chapter 25, “Named
counter servers,” on page 337 for details.)

The table shows that within an MVS image, if there is a single region that makes all
the updates to a single record, you can use a UMT without any function shipping
overheads.

Where there are multiple regions updating the control record, or there is more than
one control record to update, then a coupling facility data table is the only solution
within a Parallel Sysplex environment, and it could also be more effective than
function shipping the updates to a UMT within a single MVS.

Chapter 20. An overview of file control 291

Table 22. Techniques for sharing keyed data
Constraints and factors Single Single MVS Sysplex
Region
Read-only or rarely updated UMT UMT Replicated UMT
Single updating region Replicated UMT or
UMT UMT
CFDT
Multiple updating regions Remote UMT or
UMT CFDT
Recoverable (backout only) CFDT

In Table 22, different techniques for sharing keyed data are shown. This covers
applications that use data similar in structure to a conventional keyed file, but where
the information does not need to be stored permanently, and the performance
benefits are sufficient to justify the use of main storage or coupling facility resources
to store the relevant data.

This kind of data is most appropriately accessed using the file control API, which
means that within a Parallel Sysplex, the solution is to use:
v A replicated user-maintained data table where the highest performance is
required, and where access is either read-only, or updates are rare and you can
arrange to make these from a single region and refresh the replicated UMT in
other regions
v A coupling facility data table.
Note that recovery support for UMTs is limited to transaction backout after a failure.
For coupling facility data tables, recovery is also provided for CICS and CFDT
server failures, and also for in-doubt failures,

Using CICS commands to read records

This section describes the facilities available to application programs for accessing
data sets. Although VSAM data sets, are discussed, most of the facilities apply
equally to BDAM. It describes:
v “Direct reading (using READ command)” on page 293
v “Sequential reading (browsing)” on page 294
v “Skip-sequential processing” on page 296

A file can be defined in the file definition as containing either fixed-length or

variable-length records. Fixed-length records should be defined only if:
v The definition of the VSAM data set (using access method services) specifies an
average record size that is equal to the maximum record size
v and All the records in the data set are of that length.

For direct reading and browsing, if the file contains fixed-length records, and if the
application program provides an area into which the record is to be read, that area
must be of the defined length. If the file contains variable-length records, the
command must also specify the length of the area provided to hold them (which
should normally be the maximum length of records in the file).

For fixed-length records and for records retrieved into storage provided by CICS
(when you use the SET option), you need not specify the LENGTH argument.
However, although the LENGTH argument is optional, you are recommended to
specify it when using the INTO option, because it causes CICS to check that the

292 CICS TS for z/OS: CICS Application Programming Guide

record being read is not too long for the available data area. If you specify
LENGTH, CICS uses the LENGTH field to return the actual length of the record
retrieved.

Direct reading (using READ command)

You read a record in the file with the READ command. This must identify the record
you want and say whether it is to be read into an area of storage provided by your
application program (READ INTO), or into CICS SET storage acquired by file
control (READ SET). If the latter, the address of the data in the CICS SET storage
is returned to your program.

CICS SET storage normally remains valid until the next syncpoint, or the end of the
task, or until next READ against the same file, whichever comes first.

Direct reading from a KSDS

When reading from a KSDS, you can identify the record you want uniquely by
specifying its full key, or you can retrieve the first (lowest key) record whose key
meets certain requirements. There are two options that qualify your key value;
GENERIC and GTEQ.

The GENERIC option indicates that you require a match on only a part of the key;
when you specify the GENERIC option, you also must specify the KEYLENGTH
option, to say how many positions of the key, starting from the left, must match. For
the READ command, CICS uses only the first KEYLENGTH option characters.

The GTEQ option indicates that you want the first record whose key is “greater than
or equal to” the key you have specified. You can use GTEQ with either a full or a
generic key.

The opposite of the GTEQ option is the EQUAL option (the default), which means
that you want only a record whose key matches exactly that portion (full or generic)
of the key that you have specified.

Direct reading from an ESDS

When reading from an ESDS, the individual record you want is identified by an
RBA. Because the RBA of a record in an ESDS cannot change, your application
program can keep track of the values of the RBAs corresponding to the records it
wants to access. An RBA must always point to the beginning of a record. There is
no equivalent to the GENERIC or GTEQ options that you can use to position
approximately in a KSDS.

Direct reading from an RRDS

When reading from an RRDS, the record to be retrieved is identified by its relative
record number. The application program must know the RRN values of the records
it wants. There is no equivalent to the GENERIC or GTEQ options that you can use
to position approximately in a KSDS.

Direct reading by way of a path

If a KSDS or an ESDS has an alternate index and an alternate index path (and an
appropriate entry in the FCT), you can retrieve a record in the file by using the
alternate key that you set up in the alternate index. The GENERIC option and the
GTEQ (greater than or equal to) option still work in the same way as for a read
from a KSDS using the primary key.

Chapter 20. An overview of file control 293

If the alternate key in a READ command is not unique, the first record in the file
with that key is read and you get the DUPKEY condition. To retrieve other records
with the same alternate key, you have to start a browse operation at this point.

Read integrity (in RLS mode)

CICS supports three options to control read integrity with RLS. You can specify
these options on the file control API. Alternatively, if the application request does not
specify any of the options (UNCOMMITTED, CONSISTENT, or REPEATABLE), the
value from the file resource definition is used. These options are:
UNCOMMITTED
There is no read integrity and shared locks are not used for read requests. (See
“RLS Record level locking” on page 309 for information about shared and
exclusive locks.) This is the default and is the way in which file control works for
files that are opened in non-RLS mode.
CONSISTENT
A request to read a record is queued if the record is being updated by another
task. The read completes only when the update is complete, and the updating
unit of work (UOW) relinquishes its exclusive lock. UOWs and syncpoints are
discussed in “Syncpointing” on page 255.
REPEATABLE
Processing of the read request is the same as for consistent read requests.
However, in this case, the reader holds on to its shared lock until syncpoint.
This applies to both recoverable and non-recoverable files. This ensures that a
record read in a UOW cannot be modified while the UOW makes further read
requests. It is particularly useful when you issue a series of related read
requests and you want to ensure that none of the records is modified before the
last record is read.

Note: Specify read integrity only when an application cannot tolerate ‘stale’ data.
This is because RLS uses locks to support read integrity, and as a result
your applications could encounter deadlocks that do not occur in releases of
CICS that do not support read integrity. This is particularly important if you
define read integrity on file resource definitions. The application programs
that reference these files may have been written for releases of CICS that do
not support read integrity, and are not designed to deal with deadlock
conditions on read-only file accesses.

If you specify either CONSISTENT or REPEATABLE, you can also specify the
NOSUSPEND option on a READ command to ensure that the request does not
wait if the record is locked by VSAM with an active lock. See “Active and retained
states for locks” on page 311 for more information about active locks.

Sequential reading (browsing)

You start a browse with the STARTBR command, identifying a particular record in
the same way as for a direct read. However, the STARTBR command only identifies
the starting position for the browse; it does not retrieve a record.

The READNEXT command reads records sequentially from this starting point. On
completion of each READNEXT command, CICS returns the full key of the record it
retrieved in the field specified in the RIDFLD option. (Be sure to provide a field as
long as the full key, even if you use a STARTBR command with a shorter generic
key.)

294 CICS TS for z/OS: CICS Application Programming Guide

As in the case of a direct read, the record may be read into an area supplied by the
application program (when you use the INTO option), or into storage provided by
CICS (when you use the SET option). In the latter case, the CICS storage
addressed by the SET pointer remains valid until the next operation in the browse,
or until the browse ends, syncpoint, or end of task, whichever occurs first.

You can also browse backwards in the file, by using READPREV commands
instead of READNEXT commands, and you can switch from one direction to the
other at any time. The READPREV command is like the READPREV command,
except that the records are read sequentially backward from the current position.
As you switch from one direction to the other, you retrieve the same record twice,
unless you reposition.

When the browse has started, you can change the current browse position either by
using a RESETBR command, or a READNEXT command, or a READPREV
command. The RESETBR command can also be used for other purposes, however.

For VSAM, but not for BDAM, you can reposition simply by varying the value in
RIDFLD when you issue the next READNEXT or READPREV command. When you
change RIDFLD, the record identifier must be in the same form as on the previous
STARTBR or RESETBR command (key, RBA, or RRN). In addition, you can change
the length of a generic key by specifying a KEYLENGTH in your READPREV
command, which is different from the current generic key length and not equal to
the full length. If you change the length of a generic key in this way, you reposition
to the generic key specified by RIDFLD option.

RESETBR command must be used to change the browse position in a BDAM file. If
you wish to change the form of the key from key to RBA or vice versa, you must
use a RESETBR command. You must also use a RESETBR command to switch
between generic and full keys or between “equal to” and “greater than or equal to”
searches. You can also only use X'FF' characters to point to the last record in the
file if you are using a RESETBR or STARTBR command.

Under certain conditions, CICS uses VSAM skip-sequential processing when you
change the key in this way, as explained in “Skip-sequential processing” on page
296.

Browsing through a KSDS

You can use a generic key on the STARTBR command when browsing through a
KSDS. However, the browse can only continue forward through the file. If you
process a READPREV command during such a browse, you get the INVREQ
condition.

You can use the options “key equal to” and “key greater than or equal to” on the
STARTBR command and they have the same meaning as on the READ command.
However, the STARTBR command assumes that you want to position at the key
specified or the first key greater if that key does not exist. That is, option GTEQ is
the default for the STARTBR command, whereas EQUAL is the default for the
READ command.

You can start a forward browse through a KSDS at the start of the file by specifying
a key of hexadecimal zeros, or by specifying options GENERIC, GTEQ, and
KEYLENGTH(0) on the STARTBR, RESETBR, READNEXT, or READPREV
command. (In the latter case, you need the RIDFLD keyword although its value is
not used and, after the command completes, CICS is using a generic key length of
one.)

Chapter 20. An overview of file control 295

You can start from the end of the data set by specifying a complete key of X'FF'
characters on the STARTBR or RESETBR command. This points to the last record
in the file ready for a backward browse.

A STARTBR, RESETBR , or READNEXT command having the option

KEYLENGTH(0) is always treated as if KEYLENGTH(1) and a partial key of one
byte of binary zeros have been specified.

Browsing through an ESDS

Positioning for a browse in an ESDS is identical to that for reading. If you want to
begin reading at the beginning of the data set, use an RBA of low values (X'00'),
and to begin at the end, use high values (X'FF').

Browsing through an RRDS

You can use the GTEQ option on a STARTBR command when browsing through an
RRDS. It is the default, even though on a direct READ this option has no effect. A
direct read command with the GTEQ option that specifies an RRN that does not
exist returns the NOTFND condition, because only the EQUAL option is taken.
However, a STARTBR GTEQ command using the same RRN completes
successfully, and sets a pointer to the relevant position in the data set for the start
of the browse. The first record in the file is identified using an RRN of 1, and the
last record by high values (X'FF').

Browsing using a path

Browsing can also use an alternate index path to a KSDS or an ESDS. The browse
is just like that for a KSDS, but using the alternate key. The records are retrieved in
alternate key order.

If the alternate key is not unique, the DUPKEY condition is raised for each retrieval
operation except the last occurrence of the duplicate key. For example, if there are
three records with the same alternate key, DUPKEY is raised on the first two, but
not the third. The order in which records with duplicate alternate keys are returned
is the order in which they were written to the data set. This is true whether you are
using a READNEXT or a READPREV command. For this reason, you cannot
retrieve records with the same alternate key in reverse order.

Browse integrity (in RLS mode)

The options UNCOMMITTED, CONSISTENT, REPEATABLE, and NOSUSPEND,
discussed in “Read integrity (in RLS mode)” on page 294, also apply to the CICS
browse commands.

Ending the browse

Trying to browse past the last record in a file raises the ENDFILE condition. Stop a
browse with the ENDBR command. You must issue the ENDBR command before
performing an update operation on the same file (a READ UPDATE, DELETE with
RIDFLD, or WRITE command). If you do not, you get unpredictable results, possibly
including deadlock within your own transaction.

Simultaneous browse operations

CICS allows a transaction to perform more than one browse on the same file at the
same time. You distinguish between browse operations by including the REQID
option on each browse command.

Skip-sequential processing
When possible, CICS uses VSAM “skip-sequential” processing to speed browsing.
Skip-sequential processing applies only to forward browsing of a file when RIDFLD

296 CICS TS for z/OS: CICS Application Programming Guide

is specified in key form. CICS uses it when you increase the key value in RIDFLD
on your READNEXT command and make no other key-related specification, such
as KEYLENGTH. In this situation, VSAM locates the next desired record by reading
forward through the index, rather than repositioning from scratch. This method is
faster if the records you are retrieving are relatively close to each other but not
necessarily adjacent; it can have the opposite effect if the records are very far apart
in a large file. If you know that the key you are repositioning to is much higher in
the file, and that you may incur a long index scan, you may wish to consider using
a RESETBR command which forces a reposition from scratch.

Using CICS commands to update records

To update a record, you must first retrieve it using one of the file control read
commands that specifies the UPDATE option. The record is identified in exactly the
same way as for a direct read. In a KSDS or ESDS, the record may (as with a
direct read) be accessed by way of a file definition that refers either to the base, or
to a path defined to it. For files opened in RLS mode you can specify the
NOSUSPEND option as well as the UPDATE option on an EXEC CICS command
to ensure that the request does not wait if the record is already locked by VSAM
with an active lock.

After modification by the application program, the record is written back to the data
set using the REWRITE command, which does not identify the record being
rewritten. Within a unit of work, each REWRITE command should be associated
with a previous READ UPDATE by a common keyword (TOKEN). You can have
one READ UPDATE without a TOKEN outstanding at any one time. Attempts to
perform multiple concurrent update requests within a unit of work, upon the same
data set without the use of TOKENS, are prevented by CICS. If you want to release
the string held by a READ UPDATE without rewriting or deleting the record, use the
UNLOCK command. The UNLOCK command releases any CICS storage acquired
for the READ command, and releases VSAM resources held by the READ
command. If TOKEN is specified with the UNLOCK command, CICS attempts to
match this with an outstanding READ UPDATE whose TOKEN has the same value.
(For more explanation about the TOKEN option, see “The TOKEN option” on page
302.)

For both update and non-update commands, you must identify the record to be
retrieved by the record identification field specified in the RIDFLD option.
Immediately on completion of a READ UPDATE command, the RIDFLD data area
is available for reuse by the application program.

A record retrieved as part of a browse operation can only be updated during the
browse if the file is opened in RLS mode (see “Updating and deleting records in a
browse (VSAM RLS only)” on page 298). For files opened in non-RLS mode, the
application program must end the browse, read the desired record with a READ
UPDATE command, and perform the update. Failure to end the browse before
issuing the READ UPDATE command may cause a deadlock.

The record to be updated may (as in the case of a direct read) be read into an area
of storage supplied by the application program or into storage set by CICS. For a
READ UPDATE command, CICS SET storage remains valid until the next
REWRITE, UNLOCK, DELETE without RIDFLD, or SYNCPOINT command,
whichever is encountered first.

For a KSDS, the base key in the record must not be altered when the record is
modified. Similarly, if the update is being made by way of a path, the alternate key

Chapter 20. An overview of file control 297

used to identify the record must not be altered either, although other alternate keys
may be altered. If the file definition allows variable-length records, the length of the
record may be changed.

The length of records in an ESDS, a fixed-length RRDS, or a fixed-length KSDS

must not be changed on update.

For a file defined to CICS as containing fixed-length records, the length of record
being rewritten must equal the original length. For variable-length records, you
must specify the LENGTH option with both the READ UPDATE and the REWRITE
commands. The length must not be greater than the maximum defined to VSAM.

Using CICS commands to delete records

Records can never be deleted from an ESDS.

Deleting single records

You delete a single record in a KSDS or RRDS in one of three ways:
1. Retrieve it for update with a READ UPDATE command, and then issue a
DELETE command without specifying the RIDFLD option.
2. Issue a DELETE command specifying the RIDFLD option.
3. For a file opened in RLS mode, retrieve the record with a READNEXT or
READPREV command with the UPDATE option, and then issue a DELETE
command. This method is described in “Updating and deleting records in a
browse (VSAM RLS only).”

If a full key is provided with the DELETE command, a single record with that key is
deleted. So, if the data set is being accessed by way of an alternate index path that
allows non-unique alternate keys, only the first record with that key is deleted. After
the deletion, you know whether further records exist with the same alternate key,
because you get the DUPKEY condition if they do.

Updating and deleting records in a browse (VSAM RLS only)

For files accessed in RLS mode, you can specify the UPDATE option on a
READNEXT or READPREV command and then update or delete the record by
issuing a DELETE or REWRITE command. If the browse command returns a
TOKEN, the TOKEN remains valid only until the next browse request. The TOKEN
is invalidated by REWRITE, DELETE, or UNLOCK commands, that specify the
same value for TOKEN or by the commands READNEXT, READPREV, or ENDBR
that specify the same REQID. If you issue many READNEXT commands with the
UPDATE and TOKEN options, the TOKENS invalidate each other and only the last
one will be usable. (For more explanation about the TOKEN option, see “The
TOKEN option” on page 302.)

Use of the UPDATE option in a browse is subject to the following rules:

v You can specify UPDATE within a browse only if the file is accessed in RLS
mode. If you specify UPDATE for a file accessed in non-RLS mode, CICS returns
an INVREQ condition.
v You can specify UPDATE only on the READNEXT and READPREV commands,
not on the STARTBR or RESETBR commands.
v CICS supports only one TOKEN in a browse sequence, and the TOKEN value on
each READNEXT or READPREV command overwrites the previous value.
v You can mix update and non-update requests within the same browse.

298 CICS TS for z/OS: CICS Application Programming Guide

v You must specify on the READNEXT, DELETE, or UNLOCK command the
TOKEN to be returned by the corresponding READNEXT or READPREV
command.

Locks for UPDATE: Specifying UPDATE on a READNEXT or READPREV

command acquires an exclusive lock. The duration of these exclusive locks within a
browse depends on the action your application program takes and on whether the
file is recoverable or not.
v If the file is recoverable and you decide to DELETE or REWRITE the last record
acquired by a read for update in a browse (using the associated token), the
VSAM exclusive lock remains active until completion of the UOW. That is, until
successful syncpoint or rollback.
v If the file is not recoverable and you decide to DELETE or REWRITE the last
record acquired, the lock is released either when you next issue an ENDBR
command or when you issue a subsequent READNEXT or READPREV
command. This is explained more fully in “RLS Record level locking” on page
309.
v If you decide not to update the last record read, CICS frees the exclusive lock
either when your program issues another READNEXT or READPREV command
in the browse, or ends the browse.

Note: An UNLOCK command does not free an RLS exclusive lock held by VSAM
against a record acquired during a browse operation. An UNLOCK within a
browse simply invalidates the TOKEN returned by the last request. Another
READNEXT or READPREV in the browse also invalidates the TOKEN for
the record read by the previous READNEXT or READPREV UPDATE
command. Therefore, it’s not necessary to use UNLOCK in an application
program that decides not to update a particular record.

Deleting groups of records (generic delete)

You can use a generic key with the DELETE command. Then, instead of deleting a
single record, all the records in the file whose keys match the generic key are
deleted with the single command. However, this cannot be used if the KEYLENGTH
value is equal to the length of the whole key (even if duplicate keys are allowed).
The number of records deleted is returned to the application program if the
NUMREC option is included with the command. If access is by way of an alternate
index path, the records deleted are all those whose alternate keys match the
generic key.

Read integrity
The NOSUSPEND option discussed in “Read integrity (in RLS mode)” on page 294,
also applies to the CICS browse commands when you are using them to update a
file.

Using CICS commands to add records

Add new records to a file with the WRITE command. They must always be written
from an area provided by the application program.

Adding to a KSDS
When adding a record to a KSDS, the base key of the record identifies the position
in the data set where the record is to be inserted. Although the key is part of the
record, CICS also requires the application program to specify the key separately
using the RIDFLD option on the WRITE command.

Chapter 20. An overview of file control 299

A record added to a KSDS by way of an alternate index path is also inserted into
the data set in the position determined by the base key. However, the command
must also include the alternate index key as the record identifier.

Adding to an ESDS
A record added to an ESDS is always added to the end of the file. You cannot
insert a record in an ESDS between existing records. After the operation is
completed, the relative byte address in the file where the record was placed is
returned to the application program.

When adding a record to an ESDS by way of an alternate index path, the record is
also placed at the end of the data set. The command must include the alternate
index key in the same way as for a KSDS path.

Adding to an RRDS
To add a record to an RRDS, include the relative record number as a record
identifier on the WRITE command. The record is then stored in the file in the
position corresponding to the RRN.

Records that are already locked

The NOSUSPEND option, described in “Read integrity (in RLS mode)” on page 294
also applies to the WRITE command for a file opened in RLS mode.

Specifying record length

When writing to a fixed-length file, the record length must match the value specified
at the time the file was created. In this case, you need not include the length with
the command, although you may do so to check whether the length agrees with
that originally defined to VSAM. If the file is defined as containing variable-length
records, the command must always include the length of the record.

Sequential adding of records (WRITE MASSINSERT command)

MASSINSERT on a WRITE command offers potential improved performance where
there is more than one record to add to a KSDS, ESDS, or path. The performance
improvement is only obtained when the keys in successive WRITE MASSINSERT
requests are in ascending order.

A MASSINSERT is completed by the UNLOCK command. This ensures that all the
records are written to the file and the position is released. Always issue an
UNLOCK command before performing an update operation on the same data set
(read update, delete with RIDFLD, or write). If you do not, you may get
unpredictable results, possibly including a deadlock.

Without an UNLOCK command, the MASSINSERT is completed when a syncpoint

is issued, or at task termination.

Note: A READ command does not necessarily retrieve a record that has been
added by an incomplete MASSINSERT operation.

See “VSAM data sets” on page 173 for more information about MASSINSERT.

300 CICS TS for z/OS: CICS Application Programming Guide

File control command options
Some of the file control command options you may specify are:
v “The RIDFLD option”
v “The INTO and SET options”
v “The FROM option” on page 302
v “The TOKEN option” on page 302
v “KEYLENGTH option for remote data sets” on page 302

Use of the LENGTH option varies, depending on how you use the other options.

The RIDFLD option

Whatever you do to a record (read, add, delete, or start a browse), you identify the
record by the RIDFLD option, except when you have read the record for update
first. However, there is no RIDFLD for ENDBR, REWRITE, and UNLOCK
commands. Further, during a browse using READNEXT or READPREV commands,
you must include the RIDFLD option to give CICS a way to return the identifier of
each record retrieved.

The RIDFLD option identifies a field containing the record identification appropriate
to the access method and the type of file being accessed.

The RIDFLD option by itself is not always enough to identify a specific record in the
file. So, when retrieving records from a KSDS, or from a KSDS or ESDS by way of
an alternate index path, or when setting a starting position for a browse in this type
of data set, you can have one or both of the further options GTEQ and GENERIC
with your command.

With READNEXT or READPREV commands, the application program would not

usually set the RIDFLD field. After each command, CICS updates this field with the
actual identifier of the record retrieved. (You can alter the RIDFLD value to set a
new position from which to continue the browse.)

The INTO and SET options

With the READ, READNEXT or READPREV commands, the record is retrieved and
put in main storage according to your INTO and SET options.

The INTO option specifies the main storage area into which the record is to be put.

For fixed-length records, you need not include the LENGTH option. If you do, the
length specified must exactly match the defined length; otherwise, you get the
LENGERR condition.

For variable-length records, always specify (in the LENGTH option) the longest
record your application program accepts (which must correspond to the value
defined as the maximum record size when the data set was created); otherwise,
you get the LENGERR condition. LENGERR occurs if the record exceeds the
length specified, and the record is then truncated to that length. After the record
retrieval, if you include the LENGTH option, the data area specified in it is set to the
actual record length (before any truncation occurs).

The SET option specifies a pointer to the buffer in main storage acquired by CICS
to hold the record. When using the SET option, you need not include the LENGTH
option. If you do include it, the data area specified is set to the actual record length
after the record has been retrieved.

Chapter 20. An overview of file control 301

The FROM option
When you add records (using the EXEC CICS WRITE command), or update
records (using the REWRITE command), specify the record to be written with the
FROM option.

The FROM option specifies the main storage area that contains the record to be
written. In general, this area is part of the storage owned by your application
program. With the REWRITE command, the FROM area is usually (but not
necessarily) the same as the corresponding INTO area on the READ UPDATE
command. The length of the record can be changed when rewriting to a KSDS with
variable-length records.

Always include the LENGTH option when writing to a file with variable-length
records. If the value specified exceeds the maximum allowed in the cluster
definition, LENGERR is raised when the command is executed. LENGERR is also
raised if the LENGTH option is omitted when accessing a file with variable-length
records.

When writing to a file with fixed-length records, CICS uses the length specified in
the cluster definition as the length of the record to be written, so you need not have
the LENGTH option. If you do, its value is checked against the defined value and
you get a LENGERR condition if the values do not match.

The TOKEN option

The TOKEN option is a unique value within a task that is supplied by CICS on any
valid read for update command, and you return this to CICS with an associated
REWRITE, DELETE, or UNLOCK command. For each file that is being updated by
a task, at any one time you can have only one outstanding read request with the
UPDATE option that does not specify the TOKEN option.

You can perform multiple concurrent updates on the same data set using the same
task by including the TOKEN option with a read for update command, and
specifying the token on the associated REWRITE, DELETE, or the UNLOCK
command. Note that, for files accessed in non-RLS mode, a set of concurrent
updates fails if more than one record is being updated in the same CI, irrespective
of the TOKEN associated with the request. Also, only one token remains valid for a
given REQID on a browse, and that is the one returned on the last READNEXT or
READPREV command (see “Updating and deleting records in a browse (VSAM
RLS only)” on page 298).

You can function ship a read for update request containing the TOKEN option.
However, if you function ship a request specifying TOKEN to a member of the CICS
family of products that does not recognize this keyword, the request fails.

KEYLENGTH option for remote data sets

In general, file control commands need the RIDFLD and KEYLENGTH options. The
KEYLENGTH option can be specified explicitly in the command, or determined
implicitly from the file definition.

For remote files for which the SYSID option has been specified, the KEYLENGTH
option must be specified if the RIDFLD option is passing a key to file control. If the
remote file is being browsed, the KEYLENGTH option is not required for the
READNEXT or READPREV command.

302 CICS TS for z/OS: CICS Application Programming Guide

For a remote BDAM file, where the DEBKEY or DEBREC options have been
specified, KEYLENGTH (when specified explicitly) should be the total length of the
key (that is, all specified subfields).

Transaction deadlocks
Design your applications so as to avoid transaction deadlocks. A deadlock occurs if
each of two transactions (for example, A and B) needs exclusive use of some
resource (for example, a particular record in a data set) that the other already
holds. Transaction A waits for the resource to become available. However, if
transaction B is not in a position to release it because it, in turn, is waiting on some
resource held by A, both are deadlocked and the only way of breaking the deadlock
is to cancel one of the transactions, thus releasing its resources.

A transaction needs exclusive control of resources while executing file control

commands. For both VSAM and BDAM data sets, any record that is being modified
is held in exclusive control by CICS from the time when the modification begins (for
example, when a READ UPDATE command is issued to obtain control of the
record), to the time when it ends (for example, when a REWRITE command has
finished making a change to the record).

With VSAM files accessed in RLS mode, only the individual record is ever locked
during this process. With VSAM files accessed in non-RLS mode, when VSAM
receives a command that requires control of the record, it locks the complete
control interval containing the record. CICS then obtains an enqueue on the record
that it requires, and releases the control interval, leaving only the record locked.
The control interval lock is released after each command, and only the individual
record is locked for the whole of the modification process. (For more information
about how the control interval lock is released, see CICS Recovery and Restart
Guide.)

In releases prior to CICS Transaction Server for z/OS, Version 2 Release 2, the
access method would also hold its lock on the complete control interval between
the commands, from the time when the modification began, to the time when it
ended. This is no longer the case.

As well as CICS having exclusive control of a record during the modification

process, there is an extra locking period when a transaction modifies a record in a
recoverable file. In this situation, CICS (or VSAM if the file is accessed in RLS
mode) locks that record to the transaction even after the request that performed the
change has completed. The transaction can continue to access and modify the
same record; other transactions must wait until the transaction releases the lock,
either by terminating or by issuing a syncpoint request. For more information, see
“Syncpointing” on page 255.

Whether a deadlock actually occurs depends on the relative timing of the

acquisition and release of the resources by different concurrent transactions.
Application programs may continue to be used for some time before meeting
circumstances that cause a deadlock; it is important to recognize and allow for the
possibility of deadlock early in the application program design stages.

Here are examples of different types of deadlock found in recoverable data sets:
v Two transactions running concurrently are modifying records within a single
recoverable file, through the same FCT entry, as follows:

Chapter 20. An overview of file control 303

Transaction 1
READ UPDATE record 1
UNLOCK record 1

WRITE record 2

Transaction 2
DELETE record 2

READ UPDATE record 1

REWRITE record 1

Transaction 1 has acquired the record lock for record 1 (even though it has
completed the READ UPDATE command with an UNLOCK command).
Transaction 2 has similarly acquired the record lock for record 2. The
transactions are then deadlocked because each wants to acquire the CICS lock
held by the other. The CICS lock is not released until syncpoint.
v Two transactions running concurrently are modifying two recoverable files as
follows:

Transaction 1 Transaction 2
READ UPDATE file 1, record 1 READ UPDATE file 2, record 2
REWRITE file 1, record 1 REWRITE file 2, record 2

READ UPDATE file 2, record 2 READ UPDATE file 1, record 1

REWRITE file 2, record 2 REWRITE file 1, record 1

Here, the record locks have been acquired on different files as well as different
records; however, the deadlock is similar to the first example.

For VSAM files accessed in non-RLS mode, CICS detects deadlock situations, and
a transaction about to enter a deadlock is abended with the abend code AFCF if it
is deadlocked by another transaction, or with abend code AFCG if it has
deadlocked itself.

VSAM-detected deadlocks (RLS only)

With files accessed in RLS mode, deadlocks can arise between two different CICS
regions, possibly running under different MVS images. In these cases, deadlock
detection and resolution cannot be performed by CICS, and therefore it is
performed by VSAM.

If VSAM detects an RLS deadlock condition it returns a deadlock exception

condition to CICS, causing CICS file control to abend the transaction with an AFCW
abend code. CICS also writes messages and trace entries that identify the
members of the deadlock chain.

However, VSAM cannot detect a cross-resource deadlock (for example, a deadlock

arising from use of RLS and DB2 resources) where another resource manager is
involved. A cross-resource deadlock is resolved by VSAM when the timeout period
expires, and the waiting request is timed out. In this situation, VSAM cannot
determine whether the timeout is caused by a cross-resource deadlock, or a
timeout caused by another transaction acquiring an RLS lock and not releasing it. In
the event of a timeout, CICS writes trace entries and messages to identify the
holder of the lock for which a timed-out transaction is waiting.

304 CICS TS for z/OS: CICS Application Programming Guide

All file control requests issued in RLS mode have an associated timeout value. This
timeout value is that defined by DTIMEOUT if DTIMEOUT is active for the
transaction, or FTIMEOUT from the system initialization table if DTIMEOUT is not
active.

Rules for avoiding deadlocks

You can avoid deadlocks by following these rules:
v All applications that update (modify) multiple resources should do so in the same
order. For instance, if a transaction is updating more than one record in a data
set, it can do so in ascending key order. A transaction that is accessing more
than one file should always do so in the same predefined sequence of files.
If a data set has an alternate index, beware of mixing transactions that perform
several updates by the base key with transactions that perform several updates
by the alternate key. Assume that the transactions that perform updates always
access records in ascending key sequence. Then transactions that perform all
updates by the base key will not deadlock with other transactions that perform all
updates by the base key. Likewise, transactions that perform all updates by the
alternate key do not deadlock with other transactions that perform all updates by
the alternate key. But transactions that perform all updates by the base key may
deadlock with transactions that perform all updates by the alternate key. This is
because the key that is locked is always the base key. Consequently, a
transaction performing updates by the alternate key may be acquiring locks in a
different order to a transaction performing updates by the base key.
v An application that issues a READ UPDATE command should follow it with a
REWRITE, DELETE without RIDFLD, or UNLOCK command to release the
position before doing anything else to the file, or should include the TOKEN
option with both parts of each update request.
v A sequence of WRITE MASSINSERT commands must terminate with the
UNLOCK command to release the position. No other operation on the file should
be performed before the UNLOCK command has been issued.
v An application must end all browses on a file by means of ENDBR commands
(thereby releasing the VSAM lock) before issuing a READ UPDATE, WRITE, or
DELETE with RIDFLD command, to the file.

Chapter 20. An overview of file control 305

306 CICS TS for z/OS: CICS Application Programming Guide
Chapter 21. File control—VSAM considerations
This chapter explains how to perform:
v “VSAM record identification”
v “Locking of VSAM records in recoverable files” on page 308
v “RLS Record level locking” on page 309
v “Active and retained states for locks” on page 311
v “CICS locking for writing to ESDS” on page 312

VSAM record identification

You identify records in data sets by:
v Key
v Relative byte address (RBA) and relative record number (RRN)

Key
Generally, if you use a key, you can specify either a complete key or a generic
(partial) key. The exceptions to this rule are when you write a record to a KSDS or
when you write a record by an alternate index path. In either of these cases you
must specify the complete key in the RIDFLD option of the command.

When you use a generic key, you must specify its length in the KEYLENGTH option
and you must specify the GENERIC option on the command. A generic key cannot
have a key length equal to the full key length. You must define it to be shorter than
the complete key.

You can also specify the GTEQ option on certain commands, for both complete and
generic keys. The command then positions at, or applies to, the record with the
next higher key if a matching key cannot be found. When accessing a data set by
way of an alternate index path, the record identified is the one with the next higher
alternate key when a matching record cannot be found.

Even when using generic keys, always use a storage area for the record
identification field that is equal in length to the length of the complete key. During a
browse operation, after retrieving a record, CICS copies into the record identification
area the actual identifier of the record retrieved. CICS returns a complete key to
your application, even when you specified a generic key on the command. For
example, a generic browse through a KSDS returns the complete key to your
application on each READNEXT and READPREV command.

Relative byte address (RBA) and relative record number (RRN)

You can use the RBA and RRN options on most commands that access data sets.
In effect, they define the format of the record identification field (RIDFLD). Unless
you specify either the RBA or the RRN, the RIDFLD option should hold a key to be
used for accessing a KSDS (or a KSDS or ESDS by way of an alternate index).

RBA
RBA specifies that the record identification field contains the relative byte address of
the record to be accessed. A relative byte address is used to access an ESDS, and
it may also be used to access a KSDS that is not opened in RLS access mode. All
file control commands that refer to an ESDS base, and specify the RIDFLD option,
must also specify the RBA option.

Note: If a KSDS is accessed in this way, the RBA of the record may change during
the transaction as a result of another transaction adding records to, or
deleting records from, the same data set.

RRN
RRN specifies that the record identification field contains the relative record number
of the record to be accessed. The first record in the data set is number one. All file
control commands that refer to an RRDS, and specify the RIDFLD option, must also
specify the RRN option.

Locking of VSAM records in recoverable files

Earlier, the prevention of transaction deadlocks in terms of the record locks
acquired whenever records in a recoverable file are modified was explained. These
locks are acquired by VSAM if the file is accessed in record-level sharing (RLS)
mode, and by CICS if not. The locks are held on behalf of the transaction doing the
change until it issues a syncpoint request or terminates (at which time a syncpoint
is automatically performed). For VSAM recoverable file processing, note the
following:
v Whenever a VSAM record is obtained for modification or deletion, CICS file
control (or VSAM in the case of RLS) locks the record with an ENQUEUE
request using the primary record identifier as the enqueue argument.
If a record is modified by way of a path, the enqueue uses the base key or the
base RBA as an argument. So CICS permits only one transaction at a time to
perform its request, the other transactions having to wait until the first has
reached a syncpoint.
v For the READ UPDATE and REWRITE-related commands the record lock is
acquired as soon as the READ UPDATE command has been issued.
For a DELETE command that has not been preceded by a READ UPDATE
command, or for a WRITE command, the record lock is acquired at the time the
VSAM command is executed.
For a WRITE MASSINSERT command (which consists of a series of WRITE
commands), a separate record lock is acquired at the time each individual
WRITE command is performed. Similarly, for a DELETE GENERIC command,
each record deleted acquires a separate lock on behalf of the transaction issuing
the request.

Update locks and delete locks (non-RLS mode only)

The record locks referred to above are known as update locks, because they are
acquired whenever a record is updated (modified). A further type of lock (a delete
lock) may also be acquired by file control whenever a DELETE, WRITE, or WRITE
MASSINSERT command is being performed for a recoverable KSDS or a
recoverable path over a KSDS. A delete operation therefore may acquire two
separate locks on the record being deleted.

The separate delete lock is needed because of the way file control does its write
operations. Before executing a WRITE MASSINSERT command to a KSDS or
RRDS, file control finds and locks the empty range into which the new record or
records are to go. The empty range is locked by identifying the next existing record
in the data set and acquiring its delete lock.

The empty range is locked to stop other requests simultaneously adding records
into it. Moreover, the record defining the end of the empty range cannot be removed
during the add operation. If another transaction issues a request to add records into

308 CICS TS for z/OS: CICS Application Programming Guide

the empty range or to delete the record at the end of the range, the delete lock
makes the transaction wait until the WRITE or WRITE MASSINSERT command is
complete. The record held with a delete lock may, however, be updated by another
transaction during the write operation if it is in another CI.

Unlike an update lock, a delete lock is held only for the duration of a delete or write
operation, or a sequence of WRITE MASSINSERT commands terminated by an
UNLOCK command. A WRITE MASSINSERT command that adds records to the file
into more than one empty range releases the previous delete lock as it moves into
a new empty range.

The CICS enqueuing mechanism is only for updates and deletes and does not
prevent a read request being satisfied before the next syncpoint. The integrity of a
READ command in these circumstances is not guaranteed.

RLS Record level locking

Files opened in RLS mode can be accessed by many CICS regions simultaneously.
This means it is impractical for the individual CICS regions to attempt to control
record locking, and therefore VSAM maintains a single central lock structure using
the lock-assist mechanism of the MVS coupling facility. This central lock structure
provides sysplex-wide locking at a record level—control interval (CI) locking is not
used. This is in contrast to the locks for files in non-RLS mode, the scope of which
is limited to a single CICS region, and that are either CI locks or CICS ENQs.

Record locks within RLS are owned by a named UOW within a named CICS region.
The lock owner name is the APPLID of the CICS region, plus the UOW id. For
example, when CICS makes a request that may create a lock, CICS passes to
VSAM the UOW id. This enables VSAM to build the lock name using the UOW id,
the record key, and the name of the CICS region.

CICS releases all locks on completion of a UOW using a VSAM interface.

When more than one request requires an exclusive lock against the same resource,
VSAM queues the second and subsequent requests until the resource is freed and
the lock can be granted. However, VSAM does not queue requests for resources
locked by a retained lock (see “Active and retained states for locks” on page 311).

Note: For MASSINSERT operations on a file opened in RLS access mode, CICS
acquires a separate update lock at the time each individual WRITE
command is issued. Unlike the non-RLS mode operation (described under
“Locking of VSAM records in recoverable files” on page 308) CICS does not
acquire the separate delete lock in addition to the update lock. There is no
equivalent to range locking for the MASSINSERT function for files opened in
non-RLS mode.

Exclusive locks and shared locks

VSAM supports two types of lock for files accessed in RLS mode:
1. Exclusive locks
2. Shared locks

Exclusive locks can be active or retained; shared locks can only be active (see
“Active and retained states for locks” on page 311). Note that there are no delete
locks in RLS mode.

Chapter 21. File control—VSAM considerations 309

Exclusive locks
Exclusive locks protect updates to file resources, both recoverable and
non-recoverable. They can be owned by only one transaction at a time. Any
transaction that requires an exclusive lock must wait if another task currently owns
an exclusive lock or a shared lock against the requested resource.

Shared locks
Shared locks support read integrity (see “Read integrity (in RLS mode)” on page
294). They ensure that a record is not in the process of being updated during a
read-only request. Shared locks can also be used to prevent updates of a record
between the time that a record is read and the next syncpoint.

A shared lock on a resource can be owned by several tasks at the same time.
However, although several tasks can own shared locks, there are some
circumstances in which tasks can be forced to wait for a lock:
v A request for a shared lock must wait if another task currently owns an exclusive
lock on the resource.
v A request for an exclusive lock must wait if other tasks currently own shared
locks on this resource.
v A new request for a shared lock must wait if another task is waiting for an
exclusive lock on a resource that already has a shared lock.

Lock duration
Shared locks for repeatable read requests, for recoverable and non-recoverable
data sets, are held until the next syncpoint.

Exclusive locks against records in a non-recoverable data set remain held only for
the duration of the request—that is, they are acquired at the start of a request and
released on completion of it. For example, a lock acquired by a WRITE request is
released when the WRITE request is completed, and a lock acquired by a READ
UPDATE request is released as soon as the following REWRITE or DELETE
request is completed. Exceptionally, locks acquired by sequential requests may
persist beyond the completion of the immediate operation. Sequential requests are
WRITE commands that specify the MASSINSERT option and browse for update
requests. A lock acquired by a WRITE command with the MASSINSERT option is
always released by the time the corresponding UNLOCK command completes, but
may have been released by an earlier request in the WRITE MASSINSERT
sequence. The exact request in the sequence that causes the lock to be released is
not predictable. Similarly, a lock acquired by a READNEXT UPDATE command may
still exist after the following DELETE or REWRITE command completes. Although
this lock is guaranteed to be released by the time the subsequent ENDBR
command completes, it may be released by some intermediate request in the
browse sequence.

If a request is made to update a recoverable data set, the associated exclusive lock
must remain held until the next syncpoint. This ensures that the resource remains
protected until a decision is made to commit or back out the request. If CICS fails,
VSAM continues to hold the lock until CICS is restarted.

310 CICS TS for z/OS: CICS Application Programming Guide

Task 1 Task 2
CICS: READ(filea) UPDATE KEY(99)
VSAM: grants exclusive lock - key 99
CICS: READ(filea) KEY(99)
with integrity
VSAM: Queues request for shared lock
CICS: REWRITE(filea) KEY(99)
VSAM: holds exclusive lock until syncpoint

CICS: task completes and takes syncpoint

VSAM: frees exclusive lock
VSAM grants shared lock to task 2

Figure 77. Illustration of lock contention between CICS tasks on a recoverable data set

Active and retained states for locks

VSAM RLS supports active and retained states for locks. The difference between
these two types of lock is that whereas a request for a resource that has an active
lock is queued until the resource becomes available, a request for a resource that
has a retained lock fails immediately.

The active state is applicable to both exclusive and shared locks. However, only
exclusive locks against recoverable resources can have their state changed from
active to retained. The important characteristic of these states is that they determine
whether or not a task must wait for a lock:
v A request for a lock is made to wait if there is already an active lock against the
requested resource, except in two cases:
1. A request for a shared lock does not have to wait if the current active lock is
also a shared lock, and there are no exclusive lock requests waiting.
2. An update request that specifies NOSUSPEND does not wait for a lock if an
active lock already exists. In this case, CICS returns an exception condition
indicating that the “record is busy”.
v A request for a lock is rejected immediately with the LOCKED condition if there is
a retained lock against the requested resource.

When a lock is first acquired, it is an active lock. It is then either released, the
duration of the lock depending on the type of lock, or if an event occurs which
causes a UOW to fail temporarily and which would therefore cause the lock to be
held for an abnormally long time, it is converted into a retained lock. The types of
event that can cause a lock to become retained are:
v Failure of the CICS system, the VSAM server or the whole MVS system
v A unit of work entering the backout failed state
v A distributed unit of work becoming indoubt owing to the failure of either the
coordinating system or of links to the coordinating system

If a UOW fails, VSAM continues to hold the exclusive record locks that were owned
by the failed UOW for recoverable data sets. To avoid new requests being made to
wait for locks owned by the failed UOW, VSAM converts the active locks owned by
the failed UOW into retained locks. Retaining locks ensures that data integrity for
the locked records is maintained until the UOW is completed.

Exclusive recoverable locks are also converted into retained locks in the event of a
CICS failure, to ensure data integrity is maintained until CICS is restarted and
performs recovery.

Chapter 21. File control—VSAM considerations 311

Exclusive recoverable locks are also converted into retained locks if the VSAM
data-sharing server (SMSVSAM) fails (the conversion is carried out by the other
servers in the Sysplex, or by the first server to restart if all servers have failed). This
means that a UOW does not itself have to fail in order to hold retained RLS locks.

Any shared locks owned by a failed CICS region are discarded, and therefore an
active shared lock can never become retained. Similarly, active exclusive
non-recoverable locks are discarded. Only locks that are both exclusive and apply
to recoverable resources are eligible to become retained.

Conditional VSAM file update requests

On file control update requests against files opened in RLS mode, you can avoid
waiting for a lock by making your request conditional upon being given a lock
immediately. You do this by specifying the NOSUSPEND option on the request. If
another task already holds an active lock, CICS returns the RECORDBUSY
condition instead of queueing your request.

You can specify NOSUSPEND on READ, READNEXT, READPREV, WRITE,

REWRITE, and DELETE commands.

It is important to distinguish between the LOCKED and RECORDBUSY responses:

v A LOCKED response occurs when a request attempts to access a record that is
locked by a retained lock.
v A RECORDBUSY response occurs when a request attempts to access a record
that is locked by an active lock. Remember that this could be caused by a
DEADLOCK, in which case retries may not work. It may be necessary to issue a
SYNCPOINT with or without rollback to resolve the condition.

Note: Requests that specify NOSUSPEND wait for at least 1 second before
CICS returns the RECORDBUSY response.

If you do not specify NOSUSPEND on your request, CICS causes it to wait for a
lock if the record is already locked by an active lock. If you specify NOSUSPEND,
your request receives a RECORDBUSY response if the record is locked by an
active lock.

If you issue a request (with or without the NOSUSPEND option) against a record
locked by a retained lock, CICS returns a LOCKED response.

File control implementation of NOSUSPEND

There is a slight difference in the way that NOSUSPEND works on file control
commands compared with the way that NOSUSPEND works on other CICS
commands. If you issue HANDLE CONDITION(RECORDBUSY) it does not cause
NOSUSPEND to be assumed on subsequent file control requests. On the other
hand, specifying HANDLE CONDITION(QBUSY) causes NOSUSPEND to be
assumed on subsequent transient data commands even when it is not explicitly
specified.

CICS locking for writing to ESDS

CICS write operations to ESDS are single threaded, for both RLS and non-RLS
mode access. However, the lock held for serialization can be held for slightly longer
for RLS-mode access compared with non-RLS mode. You can compensate for the
possible increase in overhead by increasing the task priority of those transactions

312 CICS TS for z/OS: CICS Application Programming Guide

that add new records to ESDS files. It is possible that when you switch an ESDS
RLS mode from non-RLS mode that you might see an increase in time-outs for
those transactions that add new records.

Using RLS mode access for an ESDS can also cause availability problems. If a
CICS region fails while writing to an ESDS, the data set might be locked until the
CICS region is restarted. It is recommended that you do not use RLS mode access
for ESDS.

Chapter 21. File control—VSAM considerations 313

314 CICS TS for z/OS: CICS Application Programming Guide
Chapter 22. File control—BDAM considerations
This chapter explains how to perform the following functions :
v “Identifying BDAM records”
v “Browsing records from BDAM data sets” on page 316
v “Adding records to BDAM data sets” on page 317

Note: When a blocked record is read for update, CICS maintains exclusive control
of the containing block. An attempt to read a second record from the block
before the first is updated (by a REWRITE command), or before exclusive
control is released (by an UNLOCK command), causes a deadlock.

Identifying BDAM records

You identify records in BDAM data sets by a block reference, a physical key
(keyed data set), or a deblocking argument (blocked-data set). The record
identification (in the RIDFLD option) has a subfield for each item. These subfields,
when used, must be in the above order.

Note: When using EDF, only the first of the above three fields (the block reference
subfield) is displayed.

Block reference subfield

This is one of the following:
v Relative block address: 3-byte binary, beginning at relative block zero
(RELTYPE=BLK).
v Relative track and record (hexadecimal format): 2-byte TT, 1-byte R
(RELTYPE=HEX).
The 2-byte TT begins at relative track zero. The 1-byte R begins at relative
record one.
v Relative track and record (zoned decimal format): 6-byte TTTTTT, 2-byte RR
(RELTYPE=DEC).
v Actual (absolute) address: 8-byte MBBCCHHR (RELTYPE operand omitted).

The system programmer must specify the type of block reference you are using in
the RELTYPE operand of the DFHFCT TYPE=FILE system macro that defines the
data set.

Physical key subfield

You only need this if the data set has been defined to contain recorded keys. If
used, it must immediately follow the block reference. Its length must match the
length specified in the BLKKEYL operand of the DFHFCT TYPE=FILE system
macro that defines the data set.

Deblocking argument subfield

You only need this if you want to retrieve specific records from a block. If used, it
must immediately follow the physical key (if present) or the block reference. If you
omit it, you retrieve an entire block.

The deblocking argument can be a key or a relative record number. If it is a key,

specify the DEBKEY option on a READ or STARTBR command and make sure its
length matches that specified in the KEYLEN operand of the DFHFCT TYPE=FILE

system macro. If it is a relative record number, specify the DEBREC option on a
READ or STARTBR command. It is a 1-byte binary number (first record=zero).

Figure 78 shows examples of the following possible forms of BDAM record

identifiers. The examples assume a physical key of four bytes and a deblocking key
of three bytes:
v Relative block number followed by relative record number for search by relative
block and deblock by relative record
v Relative block number followed by a key for search by relative block and deblock
by key
v TTR followed by physical key and deblocking key for search by relative track and
record and key and deblock by key
v MBBCCHHR followed by relative record number for search by actual address
and deblock by relative relative record
v TTTTTRR followed by physical key and deblocking key for search by zoned
decimal relative track and record and key and deblock by key
v TR followed by physical key for search by relative track and record and deblock
by key

Byte Number

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

RELBLK# N Search by relative block;

deblock by relative record

RELBLK# KEY Search by relative block;

deblock by key

T T R PH KEY KEY Search by relative track

and record and key;
deblock by key

M B B C C H H R N Search by actual address;

deblock by relative record

T T T T T T R R PH KEY KEY Search by zoned decimal

relative track and record
and key; deblock by key

T T R KEY Search by relative track

and record; deblock by key

Figure 78. Examples of BDAM record identification

Browsing records from BDAM data sets

The record identification field must contain a block reference (for example, TTR or
MBBCCHHR) that conforms to the addressing method defined for the data set.
Processing begins with the specified block and continues with each subsequent
block until you end the browse.

If the data set contains blocked records, processing begins at the first record of the
first block and continues with each subsequent record, regardless of the contents of
the record identification field.

316 CICS TS for z/OS: CICS Application Programming Guide

In other words, CICS uses only the information held in the TTR or MBBCCHHR
subfield of the RIDFLD to identify the record. It ignores all other information, such
as physical key and relative record, or logical key.

After the READNEXT command, CICS updates the RIDFLD with the complete
identification of the record retrieved. For example, assume a browse is to be started
with the first record of a blocked, keyed data set, and deblocking by logical key is to
be performed. Before issuing the STARTBR command, put the TTR (assuming that
is the addressing method) of the first block in the record identification field. After the
first READNEXT command, the record identification field might contain
X'0000010504', where X'000001' represents the TTR value, X'05' represents the
block key, (of length 1), and X'04' represents the logical record key.

Now assume that a blocked, nonkeyed data set is being browsed using relative
record deblocking and the second record from the second physical block on the
third relative track is read by a READNEXT command. Upon return to the
application program, the record identification field contains X'00020201', where
X'0002' represents the track, X'02' represents the block, and X'01' represents the
number of the record in the block relative to zero.

Note: Specify the options DEBREC and DEBKEY on the STARTBR command
when browsing blocked-data sets. This enables CICS to return the correct
contents in the RIDFLD. Specifying DEBREC on the STARTBR command
causes the relative record number to be returned. Specifying DEBKEY on
the STARTBR command causes the logical record key to be returned.

Do not omit DEBREC or DEBKEY when browsing a blocked file. If you do,
the logical record is retrieved from the block, the length parameter is set
equal to the logical record length, but the RIDFLD is not updated with the
full identification of the record. Do not use this method.

Compare this with what happens if you omit the DEBREC or DEBKEY option
when reading from a blocked BDAM data set. In this case, you retrieve the
whole block, and the length parameter is set equal to the length of the
block.

Adding records to BDAM data sets

When adding records to a BDAM data set, bear in mind the following:
v When adding undefined or variable-length records (keyed or nonkeyed), you
must specify the track on which each new record is to be added. If space is
available on the track, the record is written following the last previously written
record, and the record number is put in the “R” portion of the record identification
field of the record. The track specification may be in any format except relative
block. If you use zoned-decimal relative format, the record number is returned as
a 2-byte zoned decimal number in the seventh and eighth positions of the record
identification field.
The extended search option allows the record to be added to another track if no
space is available on the specified track. The location at which the record is
added is returned to the application program in the record identification field
being used.
When adding records of undefined length, use the LENGTH option to specify the
length of the record. When an undefined record is retrieved, the application
program must find out its length.

Chapter 22. File control—BDAM considerations 317

v When adding keyed fixed-length records, you must first format the data set with
dummy records or “slots” into which the records may be added. You signify a
dummy record by a key of X'FF's. The first byte of data contains the record
number.
v When adding nonkeyed fixed-length records, give the block reference in the
record identification field. The new records are written in the location specified,
destroying the previous contents of that location.
v When adding keyed fixed-length records, track information only is used to search
for a dummy key and record, which, when found, is replaced by the new key and
record. The location of the new record is returned to the application program in
the block reference subfield of the record identification field.
For example, for a record with the following identification field:
0 3 0 ALPHA
T T R KEY
the search starts at relative track three. When control is returned to the
application program, the record identification field is:
0 4 6 ALPHA
showing that the record is now record six on relative track four.
v When adding variable-length blocked records you must include a 4-byte record
description field (RDF) in each record. The first two bytes specify the length of
the record (including the 4-byte RDF); the other two bytes consist of zeros.

Updating records from BDAM data sets

You cannot change the record length of a variable blocked or unblocked BDAM
record on a REWRITE command which specifies deblocking. You cannot change
the record length of an undefined format BDAM record on a REWRITE command
either.

318 CICS TS for z/OS: CICS Application Programming Guide

Chapter 23. Database control
This chapter introduces DL/I databases and “DB2 databases.”

DL/I databases
You get a logical view of the database in terms of a hierarchy of segments. DL/I lets
you manipulate these segments without needing to know how they are organized.
DL/I databases are processed by the IBM licensed program Information
Management System/Enterprise Systems Architecture (IMS/ESA®).

CICS has two programming interfaces to DL/I. We recommend that you use the
higher-level EXEC DLI interface. It is straightforward, works with EDF, and can fully
exploit a 31-bit environment. The lower-level DL/I programming interface is the DL/I
CALL interface.

DB2 databases
DB2 databases also provide data independence, offering a logical view of the
database as a series of tables that you can interrelate more or less as you wish.
DB2 lets you manipulate these tables without needing to know how they are
organized. DB2 databases are processed by the IBM licensed program DB2
Universal Database™ for z/OS and OS/390.

CICS has one interface to DB2—the EXEC SQL interface, which offers powerful
statements for manipulating sets of tables—thus relieving the application program of
record-by-record (segment-by-segment, in the case of DL/I) processing.

CICS applications that process DB2 tables can also access DL/I databases. Any
CICS resources (files, transient data, and so on), DL/I, and DB2 can be accessed
from within one transaction. See the CICS IMS Database Control Guide for
information about what databases and resources you can access.

For information about SQL commands, which are not discussed in this book, see
the DB2 Universal Database for OS/390 and z/OS Application Programming and
SQL Guide.

Requests to DB2
Requests from CICS applications to DB2 are made using EXEC SQL commands.
DB2 runs in its own address space, like DBCTL. The CICS-DB2 and the
CICS-DBCTL interfaces are similar in that they both use the task-related user exit
interface (also known as the resource manager interface (RMI)) and have a
two-phase commit process. However, they differ in a number of respects. For
example, the CICS-DB2 interface uses the task-related user exit interface (also
known as the resource manager interface, RMI) and has a two-phase commit
process. CICS supports DBCTL and remote DL/I, and has to determine at PSB
schedule time which of them is being used.

When an application issues an EXEC SQL command, the following processing

takes place:
1. The RMI is invoked from a stub that is link-edited to the application.
2. If this is the first DB2 request from this task, the RMI sets up a task interface
element (TIE).

3. The RMI invokes the DB2 task-related user exit.
4. The DB2 task-related user exit services the request. It suspends the task that
made the request: returns the response and data to the application, then
resumes the requesting task, before returning control to the RMI.
5. Control is returned to the application.
The processing steps are illustrated in Figure 79. and are the responsibility of DB2,
until control is returned to the RMI

EXEC SQL request

Application
Invoke RMI

First
N request for Y
DB2 from this
task?

RMI

Set up task interface

element (TIE)

Invoke DB2
task-related user exit

Service request

Suspend task that

made DB2 request

Return response and DB2

any data to
applications

Resume task that

made DB2 request

Return control to RMI

Return control RMI

to application

Application

Figure 79. How EXEC SQL requests are processed

320 CICS TS for z/OS: CICS Application Programming Guide

Chapter 24. CICS documents
The CICS document handler allows you to build up formatted data areas, known as
documents. Some examples of how these formatted areas, or documents, can be
used, are:
v Constructing a COMMAREA.
v Sending HTML data to be displayed by a Web client.
v Creating standard formats for printing (for example, using your own letterhead,
address, and so on).

Using the DOCUMENT programming interface

This section explains the function and use of the commands in the DOCUMENT
application programming interface:
v DOCUMENT CREATE
v DOCUMENT INSERT
v DOCUMENT RETRIEVE
v DOCUMENT SET

Creating a document
You can create an empty document using the DOCUMENT CREATE command,
and then build the contents with subsequent DOCUMENT INSERT commands, or
use DOCUMENT CREATE to create and build the document in one step.
DOCUMENT CREATE has a mandatory DOCTOKEN parameter requiring a
16–byte data-area. The document handler domain uses the DOCTOKEN operand to
return a token, which is used to identify the document on subsequent calls. The
following example creates an empty document, and returns the token in the variable
MYDOC:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC)

To create a document with data, use the DOCUMENT CREATE command in any of
the following ways:
v Using the BINARY option
v Using the TEXT option
v Using the FROMDOC option to copy an existing document
v Using the TEMPLATE option. “Setting up document templates” on page 322
describes this option.

The BINARY option

Use this option to add to the document the contents of a data-area that must not
undergo conversion to a client code page when the data is sent.
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC1)
BINARY(DATA-AREA)

The TEXT option

Use this option to add the specified contents to the document. For example, if you
define a character string variable called DOCTEXT and initialise it to This is an
example of text to be added to a document, you can use the following command to
create a document consisting of this text string:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC2)
TEXT(DOCTEXT)
LENGTH(53)

The FROMDOC option
To copy an existing document into a new document, you can use the DOCUMENT
CREATE command with the FROMDOC option. The following example shows this:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(MYDOC3)
FROMDOC(MYDOC2)

where MYDOC2 and MYDOC3 are 16–character variables. MYDOC2 must contain
the token returned by a previous DOCUMENT CREATE command.

This results in two identical documents, each containing the text This is an example
of text to be added to a document.

Setting up document templates

Document templates are portions of a document which can be created off-line, or in
another CICS program, and inserted into the document in the application program.
Document templates are CICS resources, which you define using DOCTEMPLATE
definitions; the name of the template is specified in the TEMPLATENAME attribute.

Templates can contain static data, and symbols whose values are inserted into the
template when you issue the DOCUMENT CREATE or DOCUMENT INSERT
command. The values to be subsituted are specified in the application program;
they are associated with a particular document and cannot be used in a different
document.

Templates can be retrieved from several different sources, to suit the way they are
used in the application program; the DOCTEMPLATE definition specifies the source
of the template:
v from a partitioned data set
v from a CICS program
v from a CICS file
| v from a z/OS UNIX® System Services HFS file
v from a temporary storage queue
v from a transient data queue
v from an exit program
If you attempt to use a template for which there is no installed DOCTEMPLATE
definition, CICS attempts to retrieve the template from the partitioned data set with
a DDNAME of DFHHTML.

Templates in a partitioned data set

Consider storing your templates in a partitioned data set when any of the following
apply:
v You want to edit your template on-line, or import the template from an HTML
editor.
v You want to use templates that have been created from BMS maps

CICS loads a copy of the template from the partitioned data set when you install the
corresponding DOCTEMPLATE definition. Therefore you can modify the template in
the partitioned data set while CICS is running, and reinstall the definition in order to
activate the changes.

322 CICS TS for z/OS: CICS Application Programming Guide

A partitioned data set used to store templates may have one of the following record
formats:
v FB (fixed length blocked)
v VB (variable length blocked)
v U (unblocked)
Records may contain sequence numbers in the following cases:
v When the record format is FB, and the record length is 80; the sequence
numbers must be in positions 73 through 80.
v When the record format is VB; the sequence numbers must be in positions 1
through 8.
In other cases, there must be no sequence numbers in the records. If you use
sequence numbers, they must be present in all the records; do not used partially
sequenced members.

Templates in a CICS program

Consider coding a CICS program to contain a template when:
v You need to minimize the overhead of retrieving the template
v The template is static; in other words, the contents of the template do not change
dynamically
v The same template is used by a several applications

To code a program which contains a template:

1. Code an Assembler CSECT containing
a. An ENTRY statement, which denotes the start of the template
b. Character constants (DC statements) defining the text that you wish to
include in your template.
c. An END statement
For example:
ENTRY WKLYHDR
WKLYHDR CSECT
DC CL4’<HR>’
DC CL29’<H2>Weekly Status Report</H2>’
END
2. Assemble and link edit the program into your CICS application program library.
Note that the name you give to the program can be different from the name of
the entry point.
3. Create and install a DOCTEMPLATE definition which specifies the name of the
program in the Program attribute.
CICS will autoinstall the program on first reference, or you can create and install a
PROGRAM definition.

Templates in CICS files, z/OS UNIX System Services HFS files,

temporary storage, or transient data
Consider using one of these resources when you want to use dynamic data from an
application program in a template. Which resource you use will depend upon:
v how the application program stores its data
v whether the existing data can be used directly in the template, or needs to be
modified
v whether the data must be preserved after it is used in the template

Chapter 24. CICS documents 323

In general, when a template is inserted into a document, all the data contained in
the resource is used:
Temporary storage
The queue is read, in sequence, by ITEM number, and therefore all records
in the queue are read, regardless of which records have been read by other
applications.
Transient data
Because transient data uses a destructive read, when you insert data from
a transient data queue into a template, the contents of the queue are no
longer available to other applications.
CICS file
v Entry-sequenced data sets (ESDS) are read in sequence of relative byte
address.
v Relative record data sets (RRDS) are read in sequence of relative record
number.
v Other data sets are read in sequence of key field.
| z/OS UNIX System Services HFS file
| v All the data in the file is used.
| v In the DOCTEMPLATE definition, you need to provide the fully-qualified
| name of the HFS file, which can be up to 255 characters in length.
| v The CICS region must have permissions to access z/OS UNIX, and it
| must have permission to access the HFS directory containing the file,
| and the file itself. Java Applications in CICS explains how to achieve this.

Creating templates in exit programs

Consider using an exit program for a template when:
v You need to minimize the overhead of retrieving the template
v The contents of the template change dynamically
v The same template is used by a several applications
v You want to retrieve the contents of the template from a non-CICS resource (for
example, DB2)

When an application program requests a template which is defined as being

created in an exit program, CICS calls the specified program, and passes a
communication area; the communication area is mapped by the following
copybooks:
v DFHDHTXD (Assembler)
v DFHDHTXH (C)
v DFHDHTXL (PL/I)
v DFHDHTXO (COBOL)
The communication area contains the following fields:
dhtx_template_name_ptr
Contains a pointer to the name (up to 48 characters) of the template that is
being requested.
dhtx_buffer_ptr
Contains the pointer of the CICS-supplied buffer in which the exit program
returns the template.

324 CICS TS for z/OS: CICS Application Programming Guide

dhtx_buffer_len
(Fullword binary.) Contains the length of the CICS-supplied buffer in which the
exit program returns the template.
dhtx_message_len
(Fullword binary.) Use this field to return the length of a message that is issued
when the exit program is unable to return a template. If there is no message,
return a value of zero.
dhtx_message_ptr
Use this field to return the pointer of a message that explains why the exit
program was unsuccessful. CICS writes this message to the CSDH transient
data destination. If there is no message, return a value of zero.
dhtx_template_len
(Fullword binary.) Use this field to return the actual length of the template.
dhtx_append_crlf
Use the characters ‘1’ (append) or ‘0’ (do not append) to specify whether or not
to add carriage return and line feed characters to the end of each line.
dhtx_return_code
(Fullword binary.) Use this field to indicate whether the exit program has
successfully returned a template:
v A return code of 0 indicates that the exit has returned a template.
v A return code of 8 indicates that the exit has not returned a template. In this
case, CICS raises a TEMPLATERR condition in the application program.

If the template to be returned is longer than dhtx_buffer_len, the template must be

truncated to length dhtx_buffer_len and the exit program must set the length
required in dhtx_template_len. The exit program is then called again with a larger
buffer.

If your exit program sets a return code of 8, you can return an explanatory
message, which is written to the CSDH transient data destination. Return the
address and length of the message in dhtx_message_ptr and dhtx_message_len
respectively. The storage which contains the message must be accessible to the
caller of the exit program. For example, your exit program can issue a GETMAIN
command to acquire storage for the message. CICS will release the storage when
the task ends, unless you specify the SHARED option on the command.

Programming with documents and document templates

This section covers the following topics:
v “Symbols and symbol lists”
v “Setting symbol values” on page 326
v “Embedded template commands” on page 328
v “Using templates in your application” on page 329
v “The lifespan of a document” on page 330
v “Constructing a document” on page 332
v “Using Bookmarks” on page 334
v “Code page conversion for documents” on page 335

Symbols and symbol lists

Symbols represent variable data that is resolved at the time the template is added
to the document - at the time the DOCUMENT CREATE or DOCUMENT INSERT is
issued.

Chapter 24. CICS documents 325

The application program needs to define values for the symbols that will be
substituted when the template is used. These values can be defined on the
DOCUMENT CREATE or the DOCUMENT SET commands. These commands both
take a SYMBOLLIST operand which allows several symbols to be defined in a
single command. You can also define individual symbols by using the SYMBOL and
VALUE operands on the DOCUMENT SET command.

When you are planning your use of symbols and templates, note that:
1. When a template containing symbols has been inserted into a document, you
cannot change the substituted values of those symbols in the document that is
being composed. If you set different values for the symbols, the new values will
be used the next time that the template is inserted into a document. Your
changes will not affect the values that have already been inserted into the
document.
2. If you insert a template before the symbols contained in it are set, the symbols
will never be substituted. This can occur if you create a document from a
template without specifying a symbol list.
3. Symbol substitution does not occur in html comments.

The support for symbols and symbol lists in the DOCUMENT application
programming interface is designed to interpret data with a content type of
application/x-www-form-urlencoded, as described in the HTML specification (at
http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4). This is the format in
which data is returned when it has been entered into a form on a web page.

In CICS, the DOCUMENT application programming interface extends this

specification in respect of space characters. You can use simple space characters
to indicate spaces within values in a symbol list or in the VALUE option; you do not
have to use a plus sign to indicate a space. However, if you want to adhere more
closely to the specification, it is suggested that you do use a plus sign instead of a
space character when possible. Note, though, that you cannot use a plus sign to
indicate a space character when the UNESCAPED option is used to prevent CICS
from unescaping symbol values contained in a symbol list or in the VALUE option.
In these cases, you must use a space character to indicate a space, because plus
signs are not converted to spaces when the UNESCAPED option is used.

Setting symbol values

You can define values for symbols using the DOCUMENT SET command or the
DOCUMENT CREATE command.

The DOCUMENT CREATE and DOCUMENT SET commands both take a

SYMBOLLIST operand which allows several symbols to be defined in a single
command. The SYMBOLLIST operand is a character string consisting of one or
more definitions with single byte separators. By default, the symbol separator is an
ampersand, but you can override this by using the DELIMITER option of the
DOCUMENT SET or DOCUMENT CREATE commands. A definition for a symbol
consists of a name, an equals sign, and a value.

Here is an example of a symbol list:

mytitle=New+Authors&auth1=Halliwell+Sutcliffe&auth2=Stanley+Weyman

This example defines three symbols. The first symbol called mytitle has the value
’New Authors’. The second symbol called auth1 has the value ’Halliwell Sutcliffe’
and the last symbol called auth2 has the value ’Stanley Weyman’. To adhere to the
specification for the content type application/x-www-form-urlencoded, plus signs
326 CICS TS for z/OS: CICS Application Programming Guide
have been used to indicate spaces within the symbol values; they will be converted
to spaces when the symbol values are put into the symbol table.

The following rules apply when setting symbols using a SYMBOLLIST:

v The name of each symbol must contain only uppercase and lowercase letters,
numbers and the special characters dollar (’$’), underscore (’_’), hyphen (’-’),
number sign (’#’), period (’.’) and at sign (’@’). The name is case-sensitive, so
uppercase letters are regarded as different from lowercase letters.
v The values in the symbol list can contain any characters. However, special
coding is required if you need to include the following characters in symbol
values in the symbol list:
– The character that you have used as the symbol separator (which defaults to
an ampersand, but can be overridden by use of the DELIMITER option).
– The plus sign and the percent sign.
You can use the percent sign, followed by two characters that are hexadecimal
digits (that is, 0–9, a-f, and A-F), to include characters such as these that have a
special meaning. When the value is put into the symbol table, a percent sign and
the two hexadecimal digits following it are interpreted as the EBCDIC equivalent
of the single ASCII character denoted by the two digits. Some useful
combinations are as follows:
– If you want a plus sign in the value in the symbol table, put %2B in the value
in the symbol list.
– If you want a percent sign in the value in the symbol table, put %25 in the
value in the symbol list.
– If you want an ampersand in the value in the symbol table, put %26 in the
value in the symbol list.
– You can also use this coding to specify a space in the value in the symbol
table—put %20 in the value in your symbol list. Alternatively, you can use the
space character or the plus sign, as described below.
If you prefer not to use this special coding, you can specify the UNESCAPED
option on the DOCUMENT CREATE or DOCUMENT SET command. When you
specify this option, no conversion takes place, and the symbol values are put into
the symbol table exactly as you entered them. The example below shows you
how to do this. However, the UNESCAPED option does not allow you to include
the character that you have used as the symbol separator, within a symbol value
in a symbol list. If you want to use the UNESCAPED option, choose a symbol
separator that will never be used within a symbol value. Alternatively, you can
use the SYMBOL and VALUE options on the DOCUMENT SET command to
specify symbol values that contain the character you have used as the symbol
separator, because the symbol separator has no special meaning when used in
the VALUE option.
v If you want to include spaces in a value, CICS allows you to use the space
character. However, to adhere more closely to the specification for the content
type, it is suggested that you use a plus sign instead of a space character. The
plus sign is interpreted as a space when the symbol value is put into the symbol
table. However, you cannot use a plus sign to indicate a space character when
the UNESCAPED option is used to prevent CICS from unescaping symbol values
contained in a symbol list or in the VALUE option. In these cases, you must use
a space character to indicate a space, because plus signs are not converted to
spaces when the UNESCAPED option is used.

Chapter 24. CICS documents 327

The following example shows you how, without using special coding, you can pass
symbol values to the document handler containing embedded plus signs, percent
signs, and ampersands, none of which are to undergo unescape processing:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
DELIMITER(’!’)
SYMBOLLIST(’COMPANY=BLOGGS & SON!ORDER=NUTS+BOLTS’)
LISTLENGTH(37)
UNESCAPED

Here the symbol COMPANY has a value of ’BLOGGS & SON’, and the symbol
ORDER has a value of ’NUTS+BOLTS’. The symbol separator used in this example
is ’!’, but it is best to use a non-printable character that does not appear in the
symbol value. The use of a character other than the ampersand as the symbol
separator means that an ampersand can be used in ’BLOGGS & SON’. The use of
the UNESCAPED option ensures that the plus sign in ’NUTS+BOLTS’ does not get
converted to a space. Because the UNESCAPED option has been used, you must
use a space character, rather than a plus sign, to indicate where a space is
required in the symbol value, and the data no longer conforms to the specification
for the content type application/x-www-form-urlencoded.

Depending on your application, you might find that instead of specifying the exact
list length for your symbol list each time you define values for the symbols, it is
more convenient to choose a permanent value for the LISTLENGTH option, which
will provide a fixed list length for your symbol list. The fixed list length that you
choose should be long enough to include the maximum length of symbol list that
you expect to supply. However, on those occasions when the fixed list length that
you have specified for your symbol list is greater than the actual length of the
symbols that you supply, you might find that there are trailing spaces or
unpredictable characters in the value of the last symbol in the list. You can avoid
this issue by including an extra dummy symbol at the end of your symbol list, such
as ’&END=’. Do not include this symbol in any templates or documents. Any trailing
spaces or unpredictable characters will be assigned to the dummy symbol and will
not appear in your documents, so you can continue to specify a list length that is
greater than the actual length of the symbols.

As an alternative to using a symbol list, the DOCUMENT SET command allows you
to set individual symbol values with the SYMBOL and VALUE options. The
SYMBOL option specifies the name of the symbol, and the VALUE option specifies
the value for that symbol. The rules for including spaces in a symbol value in a
symbol list also apply to the VALUE option: you can use a simple space character
or a plus sign, unless the UNESCAPED option of the DOCUMENT SET command
has been specified, in which case you must use a space character. Also, the
special coding that is required to include a plus sign or percent sign in symbol lists
is similarly required in the VALUE option, unless the UNESCAPED option of the
DOCUMENT SET command has been specified. However, ampersands, or any
other character that you have specified as a symbol separator for the symbol list,
have no special significance when used in the VALUE option.

Embedded template commands

The Document Handler recognises three commands that can be embedded in the
template. These commands follow the syntax rules for Server Side Include
commands. A Server Side Include command starts with the characters left angle
bracket, exclamation mark, hyphen, hyphen, number sign followed by the command
and it is terminated with the characters hyphen, hyphen, right angle bracket. For
example:

328 CICS TS for z/OS: CICS Application Programming Guide

The characters used to start and end the Server Side Include must be in codepage
037, otherwise the command will be ignored. The hexadecimal equivalents for these
character sequences are X’4C5A60607B’ and X’60606E’.

The three commands that are supported are #set, #echo and #include.
#set
The #set command is used to set the values of symbols and is useful for setting
up default values for symbols. The #set command in the template will be
ignored if the symbol has already been given a value using the DOCUMENT
SET command. If a previous #set command has been used to assign a value to
the symbol, the value will be overridden. A symbol which has been assigned a
value using the DOCUMENT SET command can only be changed by issuing
another DOCUMENT SET command.
#echo
The #echo command identifies a symbol that must be substituted when the
template is inserted into the document. The string containing the #echo
command will be completely replaced by the value associated with the symbol.
If no symbol has been defined with that name, the #echo command will remain
in the output data.
An alternative method to using the #echo command is to specify the symbol
name, preceding it with an ampersand and terminating it with a semicolon. If we
set a symbol called ASYM and give it a value of ’sample’, the following two
templates will give the same result after substitution.
Template 1:
This is an example template.

This is a  symbol.
Template 2:
This is an example template.

This is a &ASYM; symbol.
Result of substitution:
This is an example template.
This is a sample symbol.
#include
The #include command allows a template to be embedded within another
template. Up to 32 levels of embedding are allowed.
For example:

wheretemplatename is the name of the template (the 48 byte name) defined in

the doctemplate definition. The template name can also be enclosed in double
quotes.

Using templates in your application

If you have created a template and defined it to CICS, the following example shows
how you can use the template to create the contents of a document. The following
template is created and defined to CICS with the name ASampleTemplate.

Chapter 24. CICS documents 329

This is a sample document which has been created by user
.

In the application program, you can define a 48-byte variable called

TEMPLATENAME and initialize it to a value of ’ASampleTemplate’. Once again you
must define a 16-byte field for the document token (in this example, ATOKEN). You
can then issue the command to create the document.
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
TEMPLATE(TEMPLATENAME)

This will result in a document being created with the content “ This is a sample
document which has been created by user DFLTUSER.”.

To change the symbol to another value, you can issue the DOCUMENT CREATE
command with the SYMBOLLIST option:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
TEMPLATE(TEMPLATENAME)
SYMBOLLIST(’ASYM=Joe Soap’)
LISTLENGTH(13)

This will result in a document being created with the content “This is a sample
document which has been created by user Joe Soap.”.

The lifespan of a document

Documents created by an application exist only for the length of the CICS task in
which they are created. This means that when the last program in the CICS task
returns control to CICS, all documents created during the task’s lifetime are deleted.
It is the application’s responsibility to save a document before terminating if the
document is going to be used in another task. You can obtain a copy of the
document by using the DOCUMENT RETRIEVE. The application can then save this
copy to a location of its choice, such as a temporary storage queue. The copy can
then be used to recreate the document.

The following sequence of commands show how a document can be created,

retrieved and stored on a temporary storage queue, assuming that the following
variables have been defined and initialised in the application program:
v A 16-byte field ATOKEN to hold the document token
v A 20-byte buffer DOCBUF to hold the retrieved document
v A fullword binary field called FWORDLEN to hold the length of the data retrieved
v A halfword binary field called HWORDLEN to hold the length for the temporary
storage WRITE command.
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
TEXT(’A sample document.’)
LENGTH(18)
EXEC CICS DOCUMENT RETRIEVE
DOCTOKEN(ATOKEN)
INTO(DOCBUF)
LENGTH(FWORDLEN)
MAXLENGTH(20)
EXEC CICS WRITEQ TS
QUEUE(’AQUEUE’)
FROM(DOCBUF)
LENGTH(HWORDLEN)

330 CICS TS for z/OS: CICS Application Programming Guide

You can now use the following sequence of commands to recreate the document in
the same or another application.
EXEC CICS READQ TS
QUEUE(’AQUEUE’)
INTO(DOCBUF)
LENGTH(HWORDLEN)
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
FROM(DOCBUF)
LENGTH(FWORDLEN)

When the document is retrieved, the data that is delivered to the application buffer
is stored in a form which contains control information necessary to reconstruct an
exact replica of the document. The document that is created from the retrieved copy
is therefore identical to the original document. To help the application calculate the
size of the buffer needed to hold a retrieved document, each document command
which alters the size of the document has a DOCSIZE option. This is a fullword
value which gives the maximum size that the buffer must be to contain the
document when it is retrieved. This size is calculated to include all the control
information and data. The size should not be taken as an accurate size of the
document as the actual length delivered to the application can often be slightly
smaller than this size. The length delivered will however never exceed the length in
the DOCSIZE option.

The above example introduced the use of the FROM option on the DOCUMENT
CREATE command. The data passed on the FROM option was the buffer returned
to the application when the DOCUMENT RETRIEVE command was issued. It is
possible for the application to supply data on the FROM option that did not originate
from the DOCUMENT RETRIEVE command. When this happens, the document
handler treats the data as a template and parses the data for template commands
and symbols.

Retrieving the document without control information

The document data containing control information is only useful to an application
that wishes to recreate a copy of the original document. It is possible to issue a
DOCUMENT RETRIEVE command and ask for the control information to be
omitted. The following command sequence uses the DATAONLY option on the
DOCUMENT RETRIEVE command to instruct the Document Handler to return only
the data. This example assumes that the following variables have been defined and
initialised in the application program:
v A 16-byte field ATOKEN to hold the document token
v A 20-byte buffer DOCBUF to hold the retrieved document
v A fullword binary field called FWORDLEN to hold the length of the data retrieved.
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
TEXT(’A sample document.’)
LENGTH(18)
EXEC CICS DOCUMENT RETRIEVE
DOCTOKEN(ATOKEN)
INTO(DOCBUF)
LENGTH(FWORDLEN)
MAXLENGTH(20)
DATAONLY

When the commands have executed, the buffer DOCBUF will contain the string “A
sample document.”.

Chapter 24. CICS documents 331

Constructing a document
Once a document has been created, the contents can be extended by issuing one
or more DOCUMENT INSERT commands. The options on the DOCUMENT
INSERT command work in the same way as the equivalent commands on the
DOCUMENT CREATE command.

332 CICS TS for z/OS: CICS Application Programming Guide

The following sequence of commands shows an empty document being created
followed by two INSERT commands:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Sample line 1. ’)
LENGTH(15)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Sample line 2. ’)
LENGTH(15)

The document resulting from the above commands will contain:

Sample line 1. Sample line 2.

You can use the DOCUMENT RETRIEVE and DOCUMENT INSERT commands to
insert a whole document into an existing document. The following variables must
first be defined and initialized in the application program:
v A 16-byte field RTOKEN which contains the document token of the document to
be retrieved
v A buffer DOCBUF of sufficient length to hold the retrieved document
v A fullword binary field called RETRIEVLEN to hold the length of the data
retrieved
v A fullword binary field called MAXLEN to hold the maximum amount of data the
buffer can receive, i.e. the length of DOCBUF
v A 16-byte field ITOKEN which contains the document token of the document that
is being inserted into

The following sequence of commands shows a document indicated by RTOKEN

being inserted into another document indicated by ITOKEN:
EXEC CICS DOCUMENT RETRIEVE
DOCTOKEN(RTOKEN)
INTO(DOCBUF)
LENGTH(RETRIEVLEN)
MAXLENGTH(MAXLEN)

EXEC CICS DOCUMENT INSERT

DOCTOKEN(ITOKEN)
FROM(DOCBUF)
LENGTH(RETRIEVLEN)

The retrieved document is inserted at the end of the document specified in the
DOCUMENT INSERT command, and all the control information of the retrieved
document will be present in the second document. The LENGTH parameter of the
DOCUMENT INSERT command must be equal to the value returned from the
DOCUMENT RETRIEVE command into the field RETRIEVLEN.

The DOCUMENT INSERT command allows an operand called SYMBOL to be used

to add blocks of data to the document. SYMBOL must contain the name of a valid
symbol whose value has been set. The Document Handler inserts the value that is
associated with the symbol into the document.

Note that when a value associated with a symbol has been inserted into a
document, you cannot change that value in the document that is being composed. If
you set a different value for the symbol, the new value will be used the next time

Chapter 24. CICS documents 333

that symbol is inserted into a document. Your change will not affect the value that
has already been inserted into the document.

Using Bookmarks
The sequence in which an application inserts data into a document might not reflect
the desired sequence that the data should appear in the document. Bookmarks
allow the application to insert blocks of data in any order yet still control the
sequence of the data in the document. A bookmark is a label that the application
inserts between blocks of data. Note: a bookmark cannot be inserted in the middle
of a block of data.

The following example creates a document with two blocks of text and a bookmark:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
TEXT(’Pre-bookmark text. ’)
LENGTH(19)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
BOOKMARK(’ABookmark ’)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Post-bookmark text. ’)
LENGTH(20)

The document will now contain:

Pre-bookmark text. <ABookmark>Post-bookmark text.

Note that the text <ABookmark> does not appear in the document content but
serves merely as a pointer to that position in the document. To add data to this
document, you can insert text at the bookmark as follows:
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Inserted at a bookmark. ’)
LENGTH(25)
AT(’ABookmark ’)

Logically, the data of the document will contain the following (Note that in this
instance, only the data is being shown and not the position of the bookmark).
Pre-bookmark text. Inserted at a bookmark. Post-bookmark text.

If the AT option is omitted, the data is always appended to the end of the document.
A special bookmark of ’TOP’ can be used to insert data at the top of the document,
making it unnecessary to define a bookmark which will mark the top of the
document.

334 CICS TS for z/OS: CICS Application Programming Guide

Replacing data in the document
The following example shows how data between two bookmarks can be replaced:
EXEC CICS DOCUMENT CREATE
DOCTOKEN(ATOKEN)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Initial sample text. ’)
LENGTH(21)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
BOOKMARK(’BMark1 ’)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Text to be replaced. ’)
LENGTH(21)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
BOOKMARK(’BMark2 ’)
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Final sample text. ’)
LENGTH(19)

At this point the logical structure of the document will be as follows:

Initial sample text. <BMark1>Text to be replaced. <BMark2>Final
sample text.

You can now issue the command to replace the text between the two bookmarks,
BMark1 and BMark2:
EXEC CICS DOCUMENT INSERT
DOCTOKEN(ATOKEN)
TEXT(’Replacement Text. ’)
LENGTH(18)
AT(’BMark1 ’)
TO(’BMark2 ’)

The document now has the following logical structure:

Initial sample text. <BMark1>Replacement Text. <BMark2>Final
sample text.

Code page conversion for documents

The documents that an application creates may be transmitted to systems running
on other platforms; for example, when a document is used to supply a Web page to
a client. Textual data that is in the code pages used by the CICS system must be
converted to the code pages used on the target system. This process is known as
code page conversion. A code page used by the CICS system is usually described
as a host code page, except when CICS is acting as an HTTP client. A code page
used by the target system is described as a client code page, or where the target
system is a Web client or server using ASCII, it can be referred to as a character
set.

You can make CICS documents include information about the code pages in which
they have been created. When you create a document using the EXEC CICS
DOCUMENT CREATE and EXEC CICS DOCUMENT INSERT commands, you can
use the HOSTCODEPAGE option together with any of the TEXT, FROM,
TEMPLATE and SYMBOL options, to indicate the code page for that block of data.
Each block can be specified in a different code page.

Chapter 24. CICS documents 335

When you use the EXEC CICS DOCUMENT RETRIEVE command to retrieve a
document for sending, you can specify the CLNTCODEPAGE option to make the
Document Handler to convert all the individual blocks from their respective host
code pages, into a single client code page that is suitable for use by the target
system.

| For CICS Web support, when a CICS document is specified for sending by a
| Web-aware application program using the EXEC CICS WEB API commands, the
| EXEC CICS DOCUMENT RETRIEVE command is not used by the application
| program. Instead, the document token of the CICS document is specified, and CICS
| manages retrieval of the document. Conversion to a client code page is handled by
| CICS, according to options that the application program specifies on the EXEC
| CICS WEB API commands.

| Also for CICS Web support, when a CICS document template is specified in a
| URIMAP definition to provide a static response to a Web client, conversion to a
| client code page is handled by CICS. The host code page in which the template
| exists, and the client code page to which it should be converted, are specified in the
| URIMAP definition. When the static response is required, CICS creates a document
| using the template, retrieves the document, and carries out appropriate code page
| conversion.

| CICS documents and document templates cannot be converted to or from the

| UTF-8 and UTF-16 character encodings. This restriction applies whether they are
| used as a static response in CICS Web support, retrieved by CICS in response to
| EXEC CICS WEB API commands, or retrieved by an application program using an
| EXEC CICS DOCUMENT RETRIEVE command.

336 CICS TS for z/OS: CICS Application Programming Guide

Chapter 25. Named counter servers
This chapter describes the services provided by CICS named counter servers.

CICS provides a facility for generating unique sequence numbers for use by
application programs in a Parallel Sysplex environment. This facility is controlled by
a named counter server, which maintains each sequence of numbers as a named
counter. Each time a sequence number is assigned, the corresponding named
counter is incremented automatically. By default, the increment is 1, ensuring that
the next request gets the next number in sequence. You can vary the increment
when using the EXEC CICS GET command to request the next number.

There are various uses for this facility, such as obtaining a unique number for
documents (for example, customer orders, invoices, and despatch notes), or for
obtaining a block of numbers for allocating customer record numbers in a customer
file.

In a single CICS region, there are various methods you can use to control the
allocation of a unique number. For example, you could use the CICS common work
area (CWA) to store a number that is updated by each application program that
uses the number. The problem with the CWA method is that the CWA is unique to
the CICS address space, and cannot be shared by other regions that are running
the same application. A CICS shared data table could be used to provide such a
service, but the CICS regions would all have to reside in the same MVS image. The
named counter facility overcomes all the sharing difficulties presented by other
methods by maintaining its named counters in the coupling facility, and providing
access through a named counter server running in each MVS image in the sysplex.
This ensures that all CICS regions throughout the Parallel Sysplex have access to
the same named counters.

When you use a named counter server, each normal request (to assign the next
counter value) only requires a single coupling facility access. This provides a
significant improvement in performance compared to the use of files for this
purpose. The named counter server also performs better than coupling facility data
tables in this respect, because at least two coupling facility accesses are required to
update a coupling facility data table. Depending on your hardware configuration,
you should easily be able to make many thousands of named counter server
requests each second.

This chapter describes:

v “The named counter fields”
v “Named counter pools” on page 338
v “Using the named counter EXEC interface” on page 339
v “Using the named counter CALL interface” on page 341
v “Named counter recovery” on page 354

The named counter fields

Each named counter consists of:
The counter name
The name can be up to 16-bytes, comprising the characters A
through Z, 0 through 9, $ @ # and _. Names less than 16 bytes
should be padded with trailing blanks.

The current value
The next number to be assigned to a requesting application
program.
The minimum value
Specifies the minimum number for a counter, and the number to
which a counter is reset by the server in response to a REWIND
command.
The maximum value
Specifies the maximum number that can be assigned by a counter,
after which the counter must be explicitly reset by a REWIND
command (or automatically by the WRAP option).

All values are stored internally as 8-byte (doubleword) binary numbers. The EXEC
CICS interface allows you to use them as either fullword signed binary numbers or
doubleword unsigned binary numbers. This can give rise to overflow conditions if
you define a named counter using the doubleword command (see “Using the
named counter EXEC interface” on page 339) and request numbers from the server
using the signed fullword version of the command.

Named counter pools

A named counter is stored in a named counter pool, which resides in a list structure
in a coupling facility. Each pool, even if its list structure is defined with the minimum
size of 256KB, can hold up to a thousand named counters.

You create a named counter pool by defining the coupling facility list structure for
the pool, and then starting the first named counter server for the pool. Pool names
are of 1 to 8 bytes from the same character set for counter names. Although pool
names can be made up from any of the allowed characters, names of the form
DFHNCxxx are recommended.

You can create different pools to suit your needs. You could create a pool for use
by production CICS regions (for example, called DFHNCPRD), and others for test
and development regions (for example, using names like DFHNCTST and
DFHNCDEV). See “Named counter options table” for information about how you
can use logical pool names in your application programs, and how these are
resolved to actual pool names at runtime.

Defining a list structure for a named counter server, and starting a named counter
server, is explained in the CICS System Definition Guide.

Named counter options table

The POOL(name) parameter is optional on all the EXEC CICS COUNTER and
DCOUNTER commands (see “Using the named counter EXEC interface” on page
339 for more information). If you specify the POOL parameter, it can refer to either
an actual or a logical pool name. Whether you specify a POOL parameter or omit it,
CICS resolves the actual pool name by reference to the named counter options
table, which is loaded from the link list.

The named counter options table, DFHNCOPT, provides several methods for
determining the actual pool name referenced by a named counter API command, all
of which are described in the CICS System Definition Guide. This also describes
the DFHNCO macro that you can use to create your own options table.

338 CICS TS for z/OS: CICS Application Programming Guide

This section discusses how the POOLSEL parameter in the default options table
works in conjunction with the POOL(name) option on the API. The default options
table is supplied in source and object form. The pregenerated version is in
hlq.SDFHLINK, and the source version, which is supplied in the hlq.SDFHSAMP
library ( where hlq represents the high-level qualifier for the library names,
established at CICS installation time), contains the following entries:
DFHNCO POOLSEL=DFHNC*,POOL=YES
DFHNCO POOL=
END DFHNCOPT

The default options table entries work as follows:

POOLSEL=DFHNC*
This pool selection parameter defines a generic logical pool name
beginning with the letters DFHNC. If any named counter API request
specifies a pool name that matches this generic name, the pool name is
determined by the POOL= operand in the DFHNCO entry. Because this is
POOL=YES in the default table, the name passed on the POOL(name)
option of the API command is taken to be an actual name. Thus, the default
options table specifies that all logical pool names beginning with DFHNC
are actual pool names.
POOL=
This entry in the default table is the 'default' entry. Because the POOLSEL
parameter is not specified, it defaults to POOLSEL=*, which means it is
taken to match any value on a POOL parameter that does not find a more
explicit match. Thus, any named counter API request that:
v Secifies a POOL value that begins with other than DFHNC, or
v Omits the POOL name parameter altogether
is mapped to the the default pool (indicated by a POOL= options table
parameter that omits a name operand).
You can specify the default pool name to be used by a CICS region by
specifying the NCPLDFT system initialization parameter. If NCPLDFT is
omitted, the pool name defaults to DFHNC001.

You can see from the above that you do not need to create you own options table,
and named counter API commands do not need to specify the POOL option, if:
v You use pool names of the form DFHNCxxx, or
v Your CICS region uses only one pool that can be defined by the NCPLDFT
system initialization parameter.
Notes:
1. DFHNCOPT named counter options tables are not suffixed. A CICS region loads
the first table found in the MVS link list.
2. There must be a named counter server running, in the same MVS image as
your CICS region, for each named counter pool used by your application
programs.

Using the named counter EXEC interface

Although all named counter values are held internally as doubleword unsigned
binary numbers, the CICS API provides both a fullword (COUNTER) and
doubleword (DCOUNTER) set of commands, which you should not mix. These
EXEC CICS commands allow you to perform the following operations on named
counters:

Chapter 25. Named counter servers 339

DEFINE
Defines a new named counter, setting minimum and maximum values, and
specifying the current number at which the counter is to start.
DELETE
Deletes a named counter from its named counter pool.
GET
Gets the current number from the named counter, provided the maximum
number has not already been allocated.
Using the WRAP option: If the maximum number has been allocated to a
previous request, the counter is in a counter-at-limit condition and the request
fails, unless you specify the WRAP option. This option specifies that a counter
in the the counter-at-limit condition is to be reset automatically to its defined
minimum value. After the reset, the minimum value is returned as the current
number, and the counter is updated ready for the next request.
Using the INCREMENT option: By default, a named counter is updated by an
increment of 1, after the server has assigned the current number to a GET
request. If you want more than one number at a time, you can specify the
INCREMENT option, which effectively reserves a block of numbers from the
current number. For example , if you specify INCREMENT(50), and the server
returns 100 025:
v Your application program can use 100 025 through 100 074
v As a result of updating the current number (100 025) by 50, the current
number is left at 100 075 ready for the next request.
This example assumes that updating the current value by the INCREMENT(50)
option does not exceed the maximum value by more than 1. If the range of
numbers between the current value and the maximum value plus 1 is less than
the specified increment, the request fails unless you also specify the REDUCE
option.

Using the REDUCE option: To ensure that a request does not fail because the
remaining range of numbers is too small to satisfy your INCREMENT value (the
current number is too near the maximum value), specify the REDUCE option.
With the reduce option, the server automatically adjusts the increment to allow it
to assign all the remaining numbers, leaving the counter in the counter-at-limit
condition.

Using both the WRAP and REDUCE options: If you specify both options, only
one is effective depending on the state of the counter:
v If the counter is already at its limit when the server receives the GET
request, the REDUCE option has no effect and the WRAP option is obeyed.
v If the counter is not quite at its limit when the server receives the GET
request, but the remaining range is too small for increment, the REDUCE
option is obeyed and the WRAP option has no effect.

Using the COMPAREMIN and COMPAREMAX options: You can use these
options to make the named counter GET (and UPDATE) operation conditional
upon the current number being within a specified range, or being greater than,
or less than, one of the specified comparison values.
QUERY
Queries the named counter to obtain the current, minimum, and maximum
values. Note that you cannot use more than one named counter command in a
way that is atomic, and you cannot rely on the information returned on a

340 CICS TS for z/OS: CICS Application Programming Guide

QUERY command not having been changed by another task somewhere in the
sysplex. Even the CICS sysplex-wide ENQ facility cannot lock a counter for
you, because a named counter could be accessed by a batch application
program using the named counter CALL interface. If you want to make an
operation conditional upon the current value being within a certain range, or
greater than, or less than, a certain number, use the COMPAREMIN and
COMPAREMAX parameters on your request.
REWIND
Rewinds a named counter that is in the counter-at-limit condition back to its
defined minimum value.
UPDATE
Updates the current value of a named counter to a new current value. For
example, you could set the current value to the next free key in a database.
Like the GET command, this can be made conditional by specifying
COMPAREMIN and COMPAREMAX values.

Using the named counter CALL interface

In addition to the CICS named counter API, CICS provides a call interface that you
can use from a batch application to access the same named counters. This could
be important where you have an application that uses both CICS and batch
programs, and both need to access the same named counter to obtain unique
numbers from a specified range. The call interface does not depend on CICS
services, therefore it can also be used in applications running under any release of
CICS.

The named counter call interface does not use CICS command-level API, therefore
the system initialization parameter CMDPROT=YES has no effect. If the interface is
called from a CICS application program that is excuting in user key, it switches to
CICS key while processing the request but CICS does not attempt to verify that the
program has write access to the output parameter fields.

The first request by an application region that addresses a particular pool

automatically establishes a connection to the server for that pool. This connection is
associated with the current MVS TCB (which for CICS is the quasi-reentrant (QR)
TCB) and normally lasts until the TCB terminates at end of job. This connection can
only be used from the TCB under which the connection was established. A request
issued from another TCB will establish a separate connection to the server.

Note: The named counter server interface uses MVS name/token services
internally. A consequence of this is that jobs using the named counter
interface cannot use MVS checkpoint/restart services (as described in APAR
OW06685).

Application programming considerations

To use the named counter callable interface:
1. Ensure your application programs include the appropriate copybook that defines
the parameter list definition for the application programming language. The
copybook defines symbolic constants for the function codes and return codes,
and also defines the callable entry point for high level languages. The copybook
name is of the form DFHNCxxx where xxx indicates the programming language,
as follows:

Chapter 25. Named counter servers 341

ASM or EQU for Assembler
C for C/C++
COB for COBOL
PLI for PL/I
2. Ensure the application program is link-edited with the callable interface linkage
routine, DFHNCTR.
3. Ensure the named counter server interface module, DFHNCIF, and the options
table, DFHNCOPT, are available to the CICS region. That is, these objects must
be in a STEPLIB library, in a linklist library, or in the LPA. To support CICS
application programs that run in user key, DFHNCIF must be loaded from an
APF-authorized library. The default option table and the named counter server
interface module are supplied in CICSTS31.CICS.SDFHLINK.

CICS provides copybooks for all the supported languages:

Assembler
The standard assembler named counter interface definitions are provided in
copybook DFHNCASM. Include these in your application programs using COPY
DFHNCASM within a constant CSECT area. The symbolic values are defined
as static fullword constants, in fhe form NC_name DC F'nnn'. For example:
NC_BROWSE_NEXT DC F’7’

An alternative set of definitions is provided as symbolic equated values in copy

book DFHNCEQU. These symbols are all of the form NC_EQU_name to avoid
conflict with the static constants. Note that when these equated values are used
for function codes or return code comparisons, they should be used as address
constant values, so that for example the function code NC_ASSIGN can be
replaced by a reference to =A(NC_EQU_ASSIGN).

The syntax of the assembler version of the call to the named counter interface
is as follows:
CALL DFHNCTR,(function,return_code,pool_selector,counter_name, X
value_length,current_value,minimum_value,maximum_value, X
counter_options,update_value,compare_min,compare_max),VL

The CALL macro must specify the VL option to set the end of list indication, as
shown in the following example:
CALL DFHNCTR,(NC_ASSIGN,RC,POOL,NAME,CTRLEN,CTR),VL
C/C++
The named counter interface definitions for C/C++ are provided in header file
DFHNCC. The symbolic constant names are in upper case. The function name
is dfhnctr, in lower case.
COBOL
The named counter interface definitions for COBOL are provided in copybook
DFHNCCOB.
COBOL does not allow underscores within names, therefore the symbolic
names provided in copy book DFHNCCOB use a hyphen instead of an
underscore (for example NC-ASSIGN and NC-COUNTER-AT-LIMIT).
Note that the RETURN-CODE special register is set by each call, which affects
the program overall return code if it is not explicitly set again before the
program terminates.
PL/I
The named counter interface definitions for PL/I are provided in include file
DFHNCPLI.

342 CICS TS for z/OS: CICS Application Programming Guide

Syntax
The syntax of the named counter call is as follows:

CALL DFHNCTR(function,return_code,pool_selector,counter_name,
value_length,current_value,minimum_value,maximum_value,
counter_options,update_value,compare_min,compare_max);

Figure 80. DFHNCTR call syntax-PL/I illustration

Notes:
1. All functions that refer to a named counter require at least the first four
parameters, but the remaining parameters are optional, and trailing unused
parameters can be omitted.
If you do not want to use an imbedded optional parameter, either specify the
default value or ensure that the parameter list contains a null address for the
omitted parameter. For an example of a call that omits an optional parameter,
see “Example of DFHNCTR calls with null parameters” on page 349.
2. The NC_FINISH function requires the first three parameters only.
function
specifies the function to be performed, as a 32-bit integer, using one of the
following symbolic constants.
NC_CREATE Create a new named counter, using the initial value, range
limits, and default options specified on the current_value,
minimum_value, maximum_value, update_value and
counter_options parameters.
If you omit an optional value parameter, the new named counter
is created using the default for the omitted value. For example,
if you omit all the optional parameters, the counter is created
with an initial value of 0, a minimum value of 0, and a maximum
value of high values (the double word field is filled with X'FF').
NC_ASSIGN Assign the current value of the named counter, then increment
it ready for the next request. When the number assigned equals
the maximum number specified for the counter, it is
incremented finally to a value 1 greater than the maximum. This
ensures that any subsequent NC_ASSIGN requests for the
named counter fail (with NC_COUNTER_AT_LIMIT) until the
counter is reset using the NC_REWIND function, or
automatically rewound by the NC_WRAP counter option (see
the counter_options parameter).
This operation can include a conditional test on the current
value of the named counter, using the compare_min and
compare_max parameters.
The server returns the minimum and maximum values if you
specify these fields on the call parameter list and the request is
successful.
You can use the counter_options parameter on the
NC_ASSIGN request to override the counter options set by the
NC_CREATE request.
You can use the update_value parameter to specify the
increment to be used on this request only for the named
counter (the default increment is 1). This enables you to obtain

Chapter 25. Named counter servers 343

a range of numbers on a single request. For more information,
see the description of the update_value parameter.
Note that the named counter is incremented by update_value
after the current value is assigned. For example:

If the current value is 109

and update_value specifies 25

the named counter server returns 109 and sets the current
value to 134 ready for the next NC_ASSIGN request, effectively
assigning numbers in the range 109 through 133. The
increment can be any value between zero and the limit is
determined by the minimum and maximum values set for the
named counter. Thus the increment limit is ((maximum_value
plus 1) minus minimum value). An increment of zero causes
NC_ASSIGN to operate the same as NC_INQUIRE, except for
any comparison options.

When the increment is greater than 1, and the named counter

is near the maximum limit, the server may not be able to
increment the current number by the whole value of the
specified increment. This situation occurs when incrementing
the counter would exceed the maximum value plus 1. You
control what action the named counter server takes in this
situation through the counter_options NC_NOREDUCE |
NC_REDUCE, and NC_NOWRAP | NC_WRAP. See
counter_options parameter for information about the operation
of these options.
NC_BROWSE_FIRST
Return the details of the first named counter with a name
greater than or equal to the specified name, and update the
counter_name field accordingly.
NC_BROWSE_NEXT
Return the details of the next named counter with a name
greater than the specified name, and update the counter_name
field accordingly.
NC_DELETE Delete the specified named counter. The server returns the
current_value, minimum_value, maximum_value, and
counter_options if you specify these fields on the parameter list
and the request is successful.
NC_FINISH Terminate the connection between the current MVS task (TCB)
and the named counter server for the specified pool. If a further
request is made to the same pool, a new connection is
established.
This function does not apply to a specific counter, therefore the
only parameters required are the function, the return code and
the pool name.
Use this function only when there is a special reason to
terminate the connection (for example, to allow the server to be
shut down).
NC_INQUIRE Return the details (current_value, minimum_value,
maximum_value and counter_options) of a named counter

344 CICS TS for z/OS: CICS Application Programming Guide

without modifying it. The current value is the value to be
returned on the next NC_ASSIGN call. If the maximum value of
the named counter has already been assigned, the server
returns a current value one greater than the maximum value.
NC_REWIND Reset the named counter to its minimum value. This function is
valid only when the last number permitted by the maximum
value has been assigned, leaving the counter in the
NC_COUNTER_AT_LIMIT condition. If an NC_ASSIGN call
causes the server to assign the last number for the named
counter, use the NC_REWIND function to reset the counter.
This operation can include a conditional test on the current
value of the named counter, using the compare_min and
compare_max parameters.
The server returns the new current value, minimum value, and
maximum value if you specify these fields on the parameter list
and the request is successful.
If any option parameter or update_value parameter was
specified on an NC_ASSIGN request which failed because the
named counter was at its limit, the same parameter values
must also be specified on the NC_REWIND request, so that it
can check whether the original NC_ASSIGN would still fail. The
NC_REWIND request is suppressed with return code 102
(NC_COUNTER_NOT_AT_LIMIT) whenever the corresponding
NC_ASSIGN request would succeed.
If the NC_WRAP option is in effect, or the update_value
parameter is zero, NC_REWIND is suppressed because
NC_ASSIGN always succeeds with these conditions. See the
counter_options parameter for information about the NC_WRAP
option.
NC_UPDATE Set the named counter to a new value. This operation can
include a conditional test on the current value of the named
counter, using the compare_min and compare_max parameters.
You specify the new value on the update_value parameter. If
you don’t specify a new value, the named counter remains
unchanged.
You can specify a valid counter_options override parameter (or
a null address) with this function, but counter options have no
effect. Specify either a null address or NC_NONE as the
counter_options parameter.
return_code
specifies a 32-bit integer field to receive the return code. The same information
is also returned in register 15, which for COBOL callers is stored in the
RETURN-CODE special register.
Each return code has a corresponding symbolic constant. See “Return codes”
on page 351 for details of these.
pool_selector
specifies an 8-character pool selection parameter that you use to identify the
pool in which the named counter resides.
This parameter is optional. If you omit the pool selection parameter, a string of
8 blank X'40') characters is assumed.

Chapter 25. Named counter servers 345

The acceptable characters for pool_selector are A through Z, 0 through 9, $ @
# and _ (underscore) but the first character cannot be numeric or an
underscore. The parameter should be padded to fill 8 characters with trailing
spaces as necessary. The parameter can be all spaces to use the default pool
for the current region, provided this is mapped by the options table to a valid
non-blank named counter name).
Depending on the named counter options table in use, you can use the pool
selector parameter either as an actual pool name, or as a logical pool name
that is mapped to a real pool name through the options table. The default
options table assumes:
v That any pool selection parameter beginning with DFHNC (matching the
table entry with POOLSEL=DFHNC*) is an actual pool name
v That any other pool selection parameter (including all blanks) maps to the
default pool name.

Note: The default pool name for the call interface is DFHNC001. The default
pool nam