100% found this document useful (1 vote)

590 views661 pages

CICS Application Programming Guide

This edition applies to Version 2 Release 1 of CICS Transaction Server for z / OS, program number 5697-E93. Make sure you are using the correct edition for the level of the product. When you send information to IBM, you grant it a nonexclusive right to use or distribute it.

Uploaded by

Venkat Koyagura

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

100% found this document useful (1 vote)

590 views661 pages

CICS Application Programming Guide

Uploaded by

Venkat Koyagura

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/ 661

CICS Transaction Server for z/OS

CICS Application Programming Guide

V ersion 2 Release 1

SC34-5702-00

CICS Transaction Server for z/OS

CICS Application Programming Guide

V ersion 2 Release 1

SC34-5702-00

Note! Before using this information and the product it supports, be sure to read the general information under Notices on page 631.

First edition (March 2001) This edition applies to Version 2 Release 1 of CICS Transaction Server for z/OS, program number 5697-E93, 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. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. At the back of this publication is a page entitled Sending your comments to IBM. If you want to make comments, but the methods described are not available to you, please address them to: IBM United Kingdom Laboratories, Information Development, Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1989, 2001. 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 . . . . . . Changes for CICS Transaction Server Changes for CICS Transaction Server Changes for CICS Transaction Server . . . . . . . . . . . . . for z/OS Version 2 Release 1 . . for OS/390 Version 1 Release 3 . for OS/390 Version 1 Release 2 . . . . . . . . . . . . . xxi xxi xxi 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 . . CICS programming commands . . System programming commands. EXEC interface block (EIB) . . . Translation . . . . . . . . . . Translator Options . . . . . . CICS programming roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 6 6 6 6 6

| | | | | |

Chapter 3. Programming in COBOL . . . . . Using based addressing with COBOL . . . . . Using WITH DEBUGGING MODE . . . . . COBOL programming restrictions . . . . . . Restrictions for 31-bit addressing . . . . . Using the DL/I CALL interface . . . . . . Mixing languages . . . . . . . . . . . . Calling subprograms from COBOL. . . . . . Using COBOL with the ANSI 85 standard . . . Literals intervening in blank lines . . . . . Sequence numbers containing any character . REPLACE statement. . . . . . . . . . Batch compilation . . . . . . . . . . . Nested programs . . . . . . . . . . . Reference modification . . . . . . . . . Global variables . . . . . . . . . . . Comma and semicolon as delimiters . . . . Symbolic character definition . . . . . . . Summary of ANS185 restrictions . . . . . Using the COBOL2 translator option . . . . . Translator action . . . . . . . . . . . Using the COBOL3 translator option . . . . . Translator action . . . . . . . . . . . Using the OO COBOL translator option . . . . Translator action . . . . . . . . . . . Nesting programs . . . . . . . . . . . Chapter 4. Programming in C and C++ C and C++ programming restrictions . . Passing arguments in C or C++. . . . Accessing the EIB. . . . . . . . .
Copyright IBM Corp. 1989, 2001

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . 9 . . . 9 . . . 10 . . . 10 . . . 12 . . . 12 . . . 13 . . . 14 . . . 18 . . . 19 . . . 19 . . . 20 . . . 20 . . . 22 . . . 27 . . . 27 . . . 27 . . . 27 . . . 28 . . . 28 . . . 28 . . . 29 . . . 29 . . . 29 . . . 30 . . . 30 . . . . . . . . . . . . 31 32 34 36

. . . .

iii

Naming EIB fields . Using Locale support Programming in C++ . Restrictions . . .

. . . .

36 37 37 37

Chapter 5. Programming in PL/I . . . . . . . . . . . . . . . . . . 39 PL/I programming restrictions . . . . . . . . . . . . . . . . . . . 39 Using PL/I and dynamic storage . . . . . . . . . . . . . . . . . . 40 Chapter 6. Programming in Assembler . . . . . . . . . . . . . . . 43 Calling Assembler programs . . . . . . . . . . . . . . . . . . . . 44 Chapter 7. Language Environment . . . . . . . . . . Levels of support in Language Environment . . . . . . . Language Environment services . . . . . . . . . . . Using Language Environment Abend-handling . . . . . . User-written LE condition handlers. . . . . . . . . . Managing Language Environment storage . . . . . . . . Using C/C++ applications with Language Environment . . . Using COBOL applications with Language Environment . . . Using PL/I applications with Language Environment . . . . Using Assembler applications with Language Environment . . Mixing languages in Language Environment . . . . . . . Using Dynamic Link Libraries and Language Environment . . Defining run-time options for Language Environment . . . . Run-time options in child enclaves. . . . . . . . . . CEEBXITA coding . . . . . . . . . . . . . . . . Determining which options were used . . . . . . . . Writing a CEEBINT initialization exit for Language Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 47 48 49 50 50 51 52 54 55 57 59 60 61 61 62 62

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

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

Chapter 9. Installing application programs. . . . . . . . . . . . . . 89 Program installation roadmap . . . . . . . . . . . . . . . . . . . 89

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Preparing for program installation . . . . . . . . . . . . Defining MVS residence and addressing modes. . . . . . . . Establishing a programs addressing mode . . . . . . . . CICS address space considerations . . . . . . . . . . . Making programs permanently resident . . . . . . . . . . Running applications in the link pack area . . . . . . . . . . Running application programs in the RDSAs . . . . . . . . . Assembler . . . . . . . . . . . . . . . . . . . . C and C/++ . . . . . . . . . . . . . . . . . . . . COBOL . . . . . . . . . . . . . . . . . . . . . PL/I . . . . . . . . . . . . . . . . . . . . . . . Using BMS map sets in application programs . . . . . . . . Using the CICS-supplied procedures to install application programs Installing programs in load library secondary extents . . . . . Including the CICS-supplied interface modules . . . . . . . . Installing assembler language application programs . . . . . . Sample JCL to install assembler application programs . . . . Installing COBOL application programs . . . . . . . . . . Sample JCL to install COBOL application programs . . . . . Installing PL/I application programs . . . . . . . . . . . . Sample JCL to install PL/I application programs . . . . . . Installing C application programs . . . . . . . . . . . . . Sample JCL to install C application programs . . . . . . . Using your own job streams . . . . . . . . . . . . . . Translator requirements . . . . . . . . . . . . . . . Online programs that use EXEC CICS or EXEC DLI commands Online programs that use the CALL DLI interface . . . . . . Batch or BMP programs that use EXEC DLI commands . . . Batch or BMP programs that use DL/I CALL commands . . . Chapter 10. Installing map sets and partition sets . . . Installing map sets . . . . . . . . . . . . . . . . Types of map sets . . . . . . . . . . . . . . . Installing physical map sets . . . . . . . . . . . . Installing symbolic description map sets . . . . . . . Installing physical and symbolic description maps together Installing partition sets . . . . . . . . . . . . . . . Defining programs, map sets, and partition sets to CICS . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. 90 . 91 . 91 . 91 . 92 . 92 . 93 . 93 . 94 . 94 . 95 . 96 . 96 . 97 . 97 . 98 . 99 . 100 . 101 . 104 . 104 . 106 . 107 . 108 . 109 . 109 . 112 . 112 . 112 . . . . . . . . 113 114 114 116 118 119 121 123

| | | | | | |

Part 3. Application design . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Contents

Temporary storage . . . . . . . . . Intrapartition transient data . . . . . . GETMAIN SHARED command . . . . Your own data sets . . . . . . . . . Lengths of areas passed to CICS commands LENGTH options. . . . . . . . . . Journal records . . . . . . . . . . Data set definitions . . . . . . . . . Recommendation . . . . . . . . . Minimizing errors. . . . . . . . . . . Protecting CICS from application errors . Testing applications . . . . . . . . . Non-terminal transaction security . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

141 142 143 143 143 144 144 144 144 144 145 145 146 147 147 148 149 151 152 153 153 154 154 154 156 156 156 157 157 157 160 162 163 165 165 165 168 169 169

Chapter 12. Design for performance . . . . . Program size . . . . . . . . . . . . . . Virtual storage. . . . . . . . . . . . . . Reducing paging effects . . . . . . . . . Exclusive control of resources . . . . . . . . Operational control . . . . . . . . . . . . Operating system waits . . . . . . . . . . The NOSUSPEND option . . . . . . . . . Efficient data operations . . . . . . . . . . Efficient database operations . . . . . . . Efficient data set operations. . . . . . . . Efficient browsing (in non-RLS mode) . . . . Efficient logging . . . . . . . . . . . . Efficient sequential data set access . . . . . Efficient terminal operations. . . . . . . . . Length of the data stream sent to the terminal . Basic mapping support considerations . . . . Page-building and routing operations . . . . Requests for printed output . . . . . . . . Additional terminal control considerations . . . Chapter 13. Sharing data across transactions Using the common work area (CWA) . . . . Protecting the CWA. . . . . . . . . . Using the TCTTE user area (TCTUA) . . . . Using the COMMAREA in RETURN commands Using the display screen to share data . . . Chapter 14. Affinity . . . . . . . Types of affinity . . . . . . . . . Inter-transaction affinity . . . . . Transaction-system affinity . . . . Programming techniques and affinity . Safe techniques . . . . . . . . Unsafe techniques . . . . . . . Suspect techniques . . . . . . . Recommendations . . . . . . . Safe programming to avoid affinity . . The COMMAREA . . . . . . . The TCTUA . . . . . . . . . Using ENQ and DEQ commands with BTS containers . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENQMODEL resource definitions . . . . . . . . . . . . .

171 172 172 172 173 173 173 174 174 174 175 176 177 . . 179

CICS Transaction Server: CICS Application Programming Guide

Unsafe programming for affinity . . . . . . . . . . . . . Using the common work area . . . . . . . . . . . . . Using GETMAIN SHARED storage . . . . . . . . . . . Using the LOAD PROGRAM HOLD command . . . . . . . Sharing task-lifetime storage . . . . . . . . . . . . . Using the WAIT EVENT command . . . . . . . . . . . Using ENQ and DEQ commands without ENQMODEL resource Suspect programming for affinity . . . . . . . . . . . . . Using temporary storage . . . . . . . . . . . . . . . Using transient data . . . . . . . . . . . . . . . . Using the RETRIEVE WAIT and START commands . . . . . Using the START and CANCEL REQID commands . . . . . Using the DELAY and CANCEL REQID commands . . . . . Using the POST and CANCEL REQID commands . . . . . Detecting inter-transaction affinities . . . . . . . . . . . . Inter-transaction affinities caused by application generators . . Duration and scope of inter-transaction affinities . . . . . . . Affinity transaction groups . . . . . . . . . . . . . . Relations and lifetimes . . . . . . . . . . . . . . . Chapter 15. Recovery design . Journaling . . . . . . . . . Journal records . . . . . . Journal output synchronization. Syncpointing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

179 179 180 181 182 184 185 186 186 188 189 191 193 194 196 196 197 197 197 205 205 205 205 207 209 209 210 210 211 212 213 214 215 215 216 217 218 218 221 222 223 224 225 225 226 229 229 229 230 230 230

Chapter 16. Dealing with exception conditions . Default CICS exception handling . . . . . . . . Handling exception conditions by in-line code . . . How to use the RESP and RESP2 options . . . An example of exception handling in C . . . . An example of exception handling in COBOL . . Modifying default CICS exception handling . . . . Using the HANDLE CONDITION command . . . . RESP and NOHANDLE options . . . . . . . How CICS keeps track of what to do . . . . . Using the HANDLE CONDITION ERROR command. Using the IGNORE CONDITION command . . . . Using the HANDLE ABEND command . . . . . . Using PUSH HANDLE and POP HANDLE commands Chapter 17. Abnormal termination recovery . Creating a program-level abend exit . . . . Retrying operations . . . . . . . . . . . Trace . . . . . . . . . . . . . . . . Trace entry points . . . . . . . . . . Monitoring . . . . . . . . . . . . . . Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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

Contents

vii

Part 4. Data Management . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Chapter 19. An overview of file control. . . . . . VSAM data sets . . . . . . . . . . . . . . . Key-sequenced data set (KSDS) . . . . . . . . Entry-sequenced data set (ESDS) . . . . . . . Relative record data set (RRDS) . . . . . . . . Empty data sets . . . . . . . . . . . . . . VSAM alternate indexes . . . . . . . . . . . Accessing files in RLS mode . . . . . . . . . BDAM data sets . . . . . . . . . . . . . . . CICS shared data tables . . . . . . . . . . . . Coupling facility data tables . . . . . . . . . . . Coupling facility data table models . . . . . . . Techniques for sharing data. . . . . . . . . . . Using CICS commands to read records . . . . . . Direct reading (using READ command) . . . . . Sequential reading (browsing) . . . . . . . . . Skip-sequential processing . . . . . . . . . . Using CICS commands to update records . . . . . Using CICS commands to delete records . . . . . . Deleting single records . . . . . . . . . . . Deleting groups of records (generic delete) . . . . Read integrity . . . . . . . . . . . . . . . Using CICS commands to add records . . . . . . Adding to a KSDS . . . . . . . . . . . . . Adding to an ESDS . . . . . . . . . . . . . Adding to an RRDS. . . . . . . . . . . . . Records that are already locked . . . . . . . . Specifying record length . . . . . . . . . . . Sequential adding of records (WRITE MASSINSERT File control command options . . . . . . . . . . The RIDFLD option . . . . . . . . . . . . . The INTO and SET options . . . . . . . . . . The FROM option . . . . . . . . . . . . . The TOKEN option . . . . . . . . . . . . . KEYLENGTH option for remote data sets. . . . . Transaction deadlocks. . . . . . . . . . . . . VSAM-detected deadlocks (RLS only) . . . . . . Rules for avoiding deadlocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . command) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 235 235 236 236 236 237 237 238 239 240 241 242 244 245 246 248 249 250 250 251 251 251 251 252 252 252 252 252 252 253 253 253 254 254 255 256 257 259 259 259 259 260 260 261 261 264 264 264

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

Chapter 21. File controlBDAM considerations . . . . . . . . . . . 267 Identifying BDAM records . . . . . . . . . . . . . . . . . . . . 267 Block reference subfield . . . . . . . . . . . . . . . . . . . . 267

viii

CICS Transaction Server: CICS Application Programming Guide

Physical key subfield . . . . . . . Deblocking argument subfield . . . . Browsing records from BDAM data sets . Adding records to BDAM data sets . . . Updating records from BDAM data sets Chapter 22. Database control DL/I databases . . . . . . DATABASE 2 (DB2) databases Requests to DB2. . . . . . . . . . . . . . . . . . . . .

. . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

267 267 268 269 270 271 271 271 271 273 273 273 274 274 275 276 277 279 280 281 283 283 284 284 285 287 287 289 296

Chapter 23. CICS documents . . . . . . Using the DOCUMENT programming interface . Creating a document . . . . . . . . . Programming with documents . . . . . . . Setting symbol values . . . . . . . . . Embedded template commands . . . . . Using templates in your application . . . . The lifespan of a document . . . . . . . Constructing a document. . . . . . . . Using Bookmarks . . . . . . . . . . Codepages and codepage conversion . . . Chapter 24. Named counter servers . . The named counter fields . . . . . . Named counter pools . . . . . . . . Named counter options table . . . . Using the named counter EXEC interface Using the named counter CALL interface . Application programming considerations Syntax . . . . . . . . . . . . Return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part 5. Data Communication. . . . . . . . . . . . . . . . . . . . . . . . . 299

Chapter 25. Terminal control . . . . . . . Terminal access method support . . . . . . Terminal control commands . . . . . . . . Send/receive mode . . . . . . . . . . Speaking out of turn . . . . . . . . . Interrupting . . . . . . . . . . . . . Terminal waits . . . . . . . . . . . . Using data transmission commands . . . . . What you get on a RECEIVE . . . . . . Device control commands . . . . . . . . Terminal device support . . . . . . . . . Finding out about your terminal . . . . . . EIB feedback on terminal control operations. Using VTAM . . . . . . . . . . . . . Chaining input data . . . . . . . . . . Chaining output data . . . . . . . . . Handling logical records . . . . . . . . Response protocol . . . . . . . . . . Using function management headers . . . Preventing interruptions (bracket protocol) . Using sequential terminal support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 303 304 304 306 306 307 307 308 309 309 314 315 316 316 317 317 318 318 319 319

Contents

Coding considerations for sequential terminals . Using TCAM . . . . . . . . . . . . . . Coding for the DCB interface . . . . . . . Coding for the ACB interface . . . . . . . Using batch data interchange . . . . . . . . Destination selection and identification . . . . Definite response . . . . . . . . . . . Waiting for function completion . . . . . . Chapter 26. The 3270 family of terminals History of the 3270 . . . . . . . . . Screen fields . . . . . . . . . . Personal computers . . . . . . . The 3270 buffer . . . . . . . . . . The output datastream . . . . . . . 3270 write commands . . . . . . . Write control character . . . . . . 3270 display fields . . . . . . . . . Display characteristics . . . . . . . 3270 field attributes. . . . . . . . . Protection . . . . . . . . . . . Modification . . . . . . . . . . Intensity . . . . . . . . . . . . Base color . . . . . . . . . . . Extended attributes . . . . . . . . Orders in the data stream . . . . . . The start field order. . . . . . . . The modify field order . . . . . . . The set buffer address order . . . . The set attribute order . . . . . . . Outbound data stream sample. . . . . Input from a 3270 terminal . . . . . . Data keys . . . . . . . . . . . Keyboard control keys. . . . . . . Attention keys . . . . . . . . . . Reading from a 3270 terminal . . . . . Inbound field format . . . . . . . . Input data stream example . . . . . . Unformatted mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

320 321 321 322 322 323 324 324 325 325 326 326 328 328 328 329 329 330 330 330 331 331 332 332 333 333 334 335 335 336 338 338 338 338 339 340 341 341 343 343 344 345 345 346 346 346 347 348 348 349 349 349 350 350

Chapter 27. CICS support for printing . . . . . Formatting for CICS printers . . . . . . . . . CICS 3270 printers . . . . . . . . . . . . . CICS 3270 printer options . . . . . . . . . . PRINT option and print control bit . . . . . . ERASE option. . . . . . . . . . . . . . Line width options: L40, L64, L80, and HONEOM. NLEOM option . . . . . . . . . . . . . FORMFEED . . . . . . . . . . . . . . PRINTERCOMP option . . . . . . . . . . Non-3270 CICS printers . . . . . . . . . . . SCS input . . . . . . . . . . . . . . . Determining the characteristics of a CICS printer . . BMS page size, 3270 printers . . . . . . . . Supporting multiple printer types . . . . . . . Using CICS printers . . . . . . . . . . . .

CICS Transaction Server: CICS Application Programming Guide

Printing with a START command . . . Printing with transient data . . . . . Printing with BMS routing . . . . . Using Non-CICS printers . . . . . . . Formatting for non-CICS printers . . . Non-CICS printers: Delivering the data. Programming for non-CICS printers . . Notifying the print application . . . . Printing display screens . . . . . . . CICS print key . . . . . . . . . ISSUE PRINT and ISSUE COPY. . . Hardware print key . . . . . . . . BMS screen copy . . . . . . . . Chapter 28. CICS interface to JES Using the CICS interface to JES . . Spool interface restrictions . . . Creating output spool files . . . . Using the MVS internal reader. . Reading input spool files . . . . . JES exits . . . . . . . . . Identifying spool files . . . . . . Examples of SPOOL commands . . COBOL . . . . . . . . . . PL/I . . . . . . . . . . . C . . . . . . . . . . . . ASSEMBLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

350 351 352 353 353 353 353 355 355 355 356 356 357 359 361 361 361 362 362 363 363 367 367 368 368 369

Chapter 29. CICS intercommunication . . . . . . . . . . . . . Design considerations . . . . . . . . . . . . . . . . . . . . Programming language . . . . . . . . . . . . . . . . . . Transaction routing . . . . . . . . . . . . . . . . . . . . . Function shipping . . . . . . . . . . . . . . . . . . . . . Distributed program link (DPL). . . . . . . . . . . . . . . . . Using the distributed program link function . . . . . . . . . . . Examples of distributed program link . . . . . . . . . . . . . Programming considerations for distributed program link . . . . . . Asynchronous processing . . . . . . . . . . . . . . . . . . Distributed transaction processing (DTP) . . . . . . . . . . . . . Common Programming Interface Communications (CPI Communications) External CICS interface (EXCI) . . . . . . . . . . . . . . . .

371 371 372 372 372 373 374 376 381 385 385 385 . . 386

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

Chapter 30. Basic mapping BMS support levels . . . . Minimum BMS . . . . Standard BMS . . . . Full BMS . . . . . . A BMS output example . . support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 393 393 393 394 394 399 399 401 402 403

Chapter 31. Creating the map Defining map fields: DFHMDF . Defining the map: DFHMDI . . Defining the map set: DFHMSD Writing BMS macros . . . .

Contents

Assembling the map . . . . . . . . . . Physical and symbolic map sets . . . . . The SDF II alternative . . . . . . . . . Grouping maps into map sets . . . . . . The Application Data Structure (ADS) . . . Using complex fields . . . . . . . . . . Composite fields: the GRPNAME option . . Repeated fields: the OCCURS option . . . Block data . . . . . . . . . . . . . . Support for non-3270 terminals . . . . . . Output considerations for non-3270 devices . Differences on input . . . . . . . . . Special options for non-3270 terminals. . . Device-dependent maps . . . . . . . . . Device dependent support: DDS . . . . . Finding out about your terminal . . . . . Chapter 32. Sending BMS mapped output Acquiring and defining storage for the maps. BASE and STORAGE options . . . . . Initializing the output map . . . . . . . Moving the variable data to the map . . . Setting the display characteristics . . . . Changing the attributes . . . . . . . Attribute value definitions: DFHBMSCA . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

405 405 406 406 406 407 407 408 409 410 410 411 411 412 413 416 417 417 418 418 419 419 420 421 423 423 424 424 424 425 425 425 426 426 426 427 428 428 429 429 430 433 433 435 436 436 437 438 438 439 439 439 440

Chapter 33. Using the SEND MAP command . . . . SEND MAP control options . . . . . . . . . . . . Other BMS SEND options: WAIT and LAST . . . . . Merging the symbolic and physical maps . . . . . . . MAPONLY option . . . . . . . . . . . . . . DATAONLY option . . . . . . . . . . . . . . The SEND CONTROL command . . . . . . . . . Building the output screen . . . . . . . . . . . . What you start with . . . . . . . . . . . . . . What is sent . . . . . . . . . . . . . . . . Where the values come from . . . . . . . . . . Outside the map . . . . . . . . . . . . . . . Using GDDM and BMS . . . . . . . . . . . . Positioning the cursor . . . . . . . . . . . . . . Sending invalid data and other errors . . . . . . . . Output disposition options: TERMINAL, SET, and PAGING Using SET . . . . . . . . . . . . . . . . . Chapter 34. Receiving mapped data . An input-output example . . . . . . The symbolic input map . . . . . Programming mapped input. . . . . Using the RECEIVE MAP command . Getting storage for mapped input. . . Formatted screen input . . . . . . Modified data . . . . . . . . . Upper case translation . . . . . Using the attention identifier . . . . Using the HANDLE AID command . Finding the cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xii

CICS Transaction Server: CICS Application Programming Guide

Processing the mapped input . . . . . . Handling input errors . . . . . . . . . Flagging errors . . . . . . . . . . Saving the good input . . . . . . . . Rechecking. . . . . . . . . . . . Sending mapped output after mapped input . MAPFAIL and other exceptional conditions . EOC condition. . . . . . . . . . . Formatting other input . . . . . . . . .

. . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

440 441 441 442 443 443 444 445 445 447 447 448 448 449 450 451 453 453 454 455 457 457 457 457 458 461 461 461 462 463 463 465 467 467 468 468 469 469 470 471 472 472 473 473 473 474 474 475 475 476 477

Chapter 35. BMS logical messages . . . . Building logical messages . . . . . . . . The SEND PAGE command . . . . . . . RETAIN and RELEASE . . . . . . . . . The AUTOPAGE option . . . . . . . . . Terminal operator paging: the CSPG transaction Logical message recovery . . . . . . . .

Chapter 36. Cumulative output the ACCUM option Floating maps: how BMS places maps using ACCUM . Page breaks: BMS overflow processing . . . . . . Map placement rules . . . . . . . . . . . . . ASSIGN options for cumulative processing . . . . Input from a composite screen. . . . . . . . . . Performance considerations. . . . . . . . . . . Minimizing path length. . . . . . . . . . . . Reducing message lengths . . . . . . . . . . Chapter 37. Text output. . . . The SEND TEXT command. . . Text logical messages . . . . Text pages . . . . . . . . . Text lines . . . . . . . . . Header and trailer format. . . . SEND TEXT MAPPED and SEND . . . . . . . . . . . . TEXT . . . . . . . . . . . . . . . . . . . . . . . . NOEDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 38. Message routing . . . . . . . . Message destinations . . . . . . . . . . . . Eligible terminals. . . . . . . . . . . . . Destinations specified with OPCLASS only . . . OPCLASS and LIST omitted . . . . . . . . Route list provided . . . . . . . . . . . . Route list format . . . . . . . . . . . . . . Message delivery . . . . . . . . . . . . . Undeliverable messages . . . . . . . . . . Recoverable messages . . . . . . . . . . . Message identification . . . . . . . . . . . Programming considerations with routing . . . . . Routing and page overflow . . . . . . . . . Routing with SET . . . . . . . . . . . . Interleaving a conversation with message routing . Chapter 39. The MAPPINGDEV facility . . . SEND MAP with the MAPPINGDEV option . . RECEIVE MAP with the MAPPINGDEV option . Sample assembler MAPPINGDEV application . . . . . . . . .

Contents

xiii

Chapter 40. Partition support . . . . . . Uses for partitioned screens . . . . . . . Scrolling . . . . . . . . . . . . . . Data entry . . . . . . . . . . . . . Lookaside . . . . . . . . . . . . . Data comparison. . . . . . . . . . . Error messages . . . . . . . . . . . Partition definition . . . . . . . . . . . 3290 character size. . . . . . . . . . Establishing partitioning . . . . . . . . . Partition options for BMS SEND commands . . Determining the active partition . . . . . Partition options for BMS RECEIVE commands ASSIGN options for partitions . . . . . . Partitions and logical messages . . . . . . Partitions and routing . . . . . . . . . Attention identifiers and exception conditions . Terminal sharing . . . . . . . . . . . . Chapter 41. Support for special hardware . Logical device components . . . . . . . . Defining logical device components . . . . Sending data to a logical device component. LDCs and logical messages . . . . . . LDCs and routing . . . . . . . . . . 10/63 magnetic slot reader . . . . . . . . Field selection features . . . . . . . . . Trigger field support . . . . . . . . . Cursor and pen-detectable fields . . . . . . Selection fields . . . . . . . . . . . Attention fields . . . . . . . . . . . BMS input from detectable fields . . . . . Outboard formatting . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

479 480 480 480 480 481 481 481 482 482 483 483 484 484 484 485 485 486 487 487 487 488 488 488 489 489 489 490 491 491 491 492

Part 7. CICS management functions . . . . . . . . . . . . . . . . . . . . . 493

Chapter 42. Interval control . . . . . . . . . . . . . . . . . . . 495 Expiration times . . . . . . . . . . . . . . . . . . . . . . . . 496 Request identifiers . . . . . . . . . . . . . . . . . . . . . . . 497 Chapter 43. Task control . . . . . . . . . . . . . . . . . . . . 499 Controlling sequence of access to resources . . . . . . . . . . . . . 500 Chapter 44. Program control. . . Program linking . . . . . . . . Application program logical levels Link to another program expecting Passing data to other programs . . COMMAREA . . . . . . . . INPUTMSG. . . . . . . . . Using mixed addressing modes . . Using LINK to pass data . . . . . Using RETURN to pass data . . . . . . . . . . . . return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 504 504 504 505 505 507 509 509 512

Chapter 45. Storage control . . . . . . . . . . . . . . . . . . . 517 Overview of CICS storage protection and transaction isolation . . . . . . . 518

xiv

CICS Transaction Server: CICS Application Programming Guide

Storage protection . . . . . . . . . . . . . Transaction isolation . . . . . . . . . . . . Defining the storage key for applications . . . . . . System-wide storage areas . . . . . . . . . . Task lifetime storage . . . . . . . . . . . . Program working storage specifically for exit and PLT Passing data by a COMMAREA . . . . . . . . The GETMAIN command . . . . . . . . . . Selecting the execution and storage key . . . . . . User-key applications . . . . . . . . . . . . CICS-key applications . . . . . . . . . . . . Using transaction isolation . . . . . . . . . . . MVS subspaces . . . . . . . . . . . . . . . Subspaces and basespaces for transactions . . . The common subspace and shared storage . . . . Chapter 46. Transient data control Intrapartition transient data queues . Extrapartition queues . . . . . . Indirect queues . . . . . . . . Automatic transaction initiation (ATI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

518 519 520 521 521 521 521 522 523 524 524 527 529 529 530 533 533 534 534 535

Chapter 47. Temporary storage control . . . . . . . . . . . . . . 537 Temporary storage queues . . . . . . . . . . . . . . . . . . . . 537 Typical uses of temporary storage control . . . . . . . . . . . . . . 538

Part 8. Testing applications . . . . . . . . . . . . . . . . . . . . . . . . . 541

Chapter 48. Testing applications . . . . . . . . . . . . . . . . . 543 Preparing the application for testing . . . . . . . . . . . . . . . . . 544 Preparing the system for testing . . . . . . . . . . . . . . . . . . 544 Chapter 49. Execution diagnostic facility Restrictions when using EDF . . . . . Parameter list stacking . . . . . . Security considerations . . . . . . What does EDF display? . . . . . . . The header . . . . . . . . . . . The body . . . . . . . . . . . Using EDF . . . . . . . . . . . . Interrupting program execution . . . Using EDF in single-screen mode . . Using EDF in dual-screen mode . . . EDF and remote transactions . . . . EDF and non-terminal transactions . . EDF and DTP programs . . . . . . Stopping EDF . . . . . . . . . . Overtyping to make changes . . . . . EDF responses . . . . . . . . . Using EDF menu functions . . . . . . (EDF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 548 549 549 549 550 551 557 557 559 560 560 561 561 562 562 564 564 571 571 573 573 573

Chapter 50. Temporary storage browse (CEBR) Using the CEBR transaction . . . . . . . . What does the CEBR transaction display? . . . The header . . . . . . . . . . . . . . The command area . . . . . . . . . . .

Contents

The body . . . . . . . . . . . The message line . . . . . . . . Using the CEBR function keys. . . . . Using the CEBR commands . . . . . Using the CEBR transaction with transient

. . . . . . . . data

. . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

573 573 573 574 576 579 579 579 580 582 583 583 584 585 586 586 586 588 588 589 590 590 590 590 591 591

Chapter 51. Command-level interpreter (CECI) . What does CECI display? . . . . . . . . . The command line . . . . . . . . . . . The status line . . . . . . . . . . . . The body . . . . . . . . . . . . . . The message line . . . . . . . . . . . CECI options on function keys. . . . . . . Using CECI. . . . . . . . . . . . . . . Making changes . . . . . . . . . . . . Using the CECI function keys . . . . . . . . Expanded area . . . . . . . . . . . . Variables. . . . . . . . . . . . . . . The EXEC interface block (EIB) . . . . . . Error messages display . . . . . . . . . Saving commands . . . . . . . . . . . . How CECI runs . . . . . . . . . . . . . CECI sessions . . . . . . . . . . . . Abends . . . . . . . . . . . . . . . Exception conditions . . . . . . . . . . Program control commands . . . . . . . . Terminal sharing . . . . . . . . . . . .

Part 9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

Appendix. Using OS/VS COBOL . . . . . . Programming with OS/VS COBOL . . . . . . Programming restrictions . . . . . . . . . Restricted OS/VS COBOL language statements Base locator for linkage . . . . . . . . . BLL and chained storage areas . . . . . . BLL and OCCURS DEPENDING ON clauses . BLL and large storage areas . . . . . . . SERVICE RELOAD statement . . . . . . . NOTRUNC compiler option . . . . . . . . Program segments . . . . . . . . . . . OS/VS COBOL translator options . . . . . OS/VS Cobol bibliography . . . . . . . . Conversion to VS COBOL II . . . . . . . . Based addressing . . . . . . . . . . . Artificial assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 595 595 597 597 598 599 600 601 602 602 603 603 603 603 606 607 607 607 608 608 608 608 609 609

Bibliography . . . . . . . . . . . . . . . . CICS Transaction Server for z/OS . . . . . . . . CICS books for CICS Transaction Server for z/OS . CICSPlex SM books for CICS Transaction Server for Other CICS books . . . . . . . . . . . . . Books from related libraries . . . . . . . . . . . DL/I . . . . . . . . . . . . . . . . . . MVS . . . . . . . . . . . . . . . . . . DB2 . . . . . . . . . . . . . . . . . .

. . . . . . z/OS . . . . . . . . . .

xvi

CICS Transaction Server: CICS Application Programming Guide

Screen definition facility II (SDF II) . . . . . . . . Common programming interface . . . . . . . . . Common user access . . . . . . . . . . . . . Programming languages . . . . . . . . . . . . Teleprocessing Network Simulator (TPNS) . . . . . Distributed Processing Programming Executive (DPPX): Language Environment: . . . . . . . . . . . . Miscellaneous books . . . . . . . . . . . . . Determining if a publication is current . . . . . . . .

. . . . . . . . .

609 609 609 609 610 610 610 610 611

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 632 Sending your comments to IBM . . . . . . . . . . . . . . . . . 633

Contents

xvii

xviii

CICS Transaction Server: 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 know about CICS application programming at the CICS Application Programming Primer (VS COBOL II) 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 ASM MVS refers to the CICS command-level application programming interface unless otherwise stated. is sometimes used as the abbreviation for assembler language. 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). 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 X5B. 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.

VTAM

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 Users Guide for background information about FEPI design considerations and programming information about its API.

Copyright IBM Corp. 1989, 2001

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.

CICS Transaction Server: CICS Application Programming Guide

Summary of changes
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 6. 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 Java Applications in CICS, 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 129, from application design for performance, see Chapter 12. Design for performance on page 147. 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 for this edition are indicated by vertical lines to the left of the changes. v The addition of the JCICS Java classes to access CICS services from Java application programs. Now moved to Java Applications in CICS v Support for running CICS Java programs using the VisualAge for Java, Enterprise ToolKit for OS/390. Now moved to Java Applications in CICS. v Support for running CICS Java programs using the CICS Java Virtual Machine (JVM). Now moved to Java Applications in CICS. v The addition of sysplex-wide ENQ and DEQ. See Using ENQ and DEQ commands with ENQMODEL resource definitions on page 177. v The addition of support for coupling facility data tables (CFDT). See Coupling facility data tables on page 240. v Support for named counter servers. See Chapter 24. Named counter servers on page 283. v Support for documents, and the EXEC CICS DOCUMENT commands. See Chapter 23. CICS documents on page 273. 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.
Copyright IBM Corp. 1989, 2001

xxi

Changes for CICS Transaction Server for OS/390 Version 1 Release 2

Significant changes for this edition are indicated by vertical lines to the left of the changes. v The enhancement of the BMS map definition macros to build an Application Data Structure (ADS) descriptor record in the mapset. See The Application Data Structure (ADS) on page 406. v The addition of the MAPPINGDEV option (by APAR) that is specified on the RECEIVE MAP and SEND MAP commands to allow you to perform mapping operations for a device that is not the principal facility. See Chapter 39. The MAPPINGDEV facility on page 475.

xxii

CICS Transaction Server: CICS Application Programming Guide

Part 1. Writing CICS Applications

| | | | | |

Chapter 3. Programming in COBOL . . . . . Using based addressing with COBOL . . . . . Using WITH DEBUGGING MODE . . . . . COBOL programming restrictions . . . . . . Restrictions for 31-bit addressing . . . . . Using the DL/I CALL interface . . . . . . Mixing languages . . . . . . . . . . . . Calling subprograms from COBOL. . . . . . Using COBOL with the ANSI 85 standard . . . Literals intervening in blank lines . . . . . Separate Translator action. . . . . . . Integrated translator action . . . . . . Sequence numbers containing any character . Separate Translator action. . . . . . . Integrated translator action . . . . . . REPLACE statement. . . . . . . . . . Separate translator action . . . . . . . Integrated Translator action . . . . . . Batch compilation . . . . . . . . . . . Translator action . . . . . . . . . . Compiler and linkage editor . . . . . . Nested programs . . . . . . . . . . . Integrated CICS translator . . . . . . . Translator action . . . . . . . . . . Reference modification . . . . . . . . . Translator action . . . . . . . . . . Global variables . . . . . . . . . . . Translator action . . . . . . . . . . Comma and semicolon as delimiters . . . . Translator action . . . . . . . . . . Symbolic character definition . . . . . . . Translator action . . . . . . . . . . Summary of ANS185 restrictions . . . . . Using the COBOL2 translator option . . . . . Translator action . . . . . . . . . . . Using the COBOL3 translator option . . . . . Translator action . . . . . . . . . . . Using the OO COBOL translator option . . . . Translator action . . . . . . . . . . . Nesting programs . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . 9 . . . 9 . . . 10 . . . 10 . . . 12 . . . 12 . . . 13 . . . 14 . . . 18 . . . 19 . . . 19 . . . 19 . . . 19 . . . 19 . . . 20 . . . 20 . . . 20 . . . 20 . . . 20 . . . 20 . . . 20 . . . 22 . . . 23 . . . 23 . . . 27 . . . 27 . . . 27 . . . 27 . . . 27 . . . 27 . . . 27 . . . 28 . . . 28 . . . 28 . . . 28 . . . 29 . . . 29 . . . 29 . . . 30 . . . 30

Chapter 4. Programming in C and C++ . . . . . . . . . . . . . . . 31

C and C++ programming restrictions Passing arguments in C or C++. . Accessing the EIB. . . . . . . Naming EIB fields . . . . . . Data types in EIB fields . . . Using Locale support . . . . . Programming in C++ . . . . . . Restrictions . . . . . . . .

. . . . . . . .

32 34 36 36 36 37 37 37

CICS Transaction Server: 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 the Java Applications in CICS. 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, 2001

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

CICS Transaction Server: 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, OO 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, OO 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 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 3. Programming in COBOL on page 9, Chapter 4. Programming in C and C++ on page 31, Chapter 5. Programming in PL/I on page 39, and Java Applications in CICS. 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 Users 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, 2001

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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 the 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 separate translator on page 73 explains how to specify options, and Defining translator options on page 74 defines the options available.

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 129 and Chapter 12. Design for performance on page 147 for guidance on designing CICS applications.

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | |

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 89. Otherwise, you will need to define translator options for your program, using the process described in Using a separate 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 89. 4. Define your program and related transaction to CICS with PROGRAM and TRANSACTION resource definition statements and the CEDA transaction 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. 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.

Chapter 2. CICS programming

CICS Transaction Server: CICS Application Programming Guide

Chapter 3. Programming in COBOL

For programming in COBOL language, you can find information about appropriate compilers in the CICS Transaction Server for z/OS Migration Guide or the relevant COBOL manuals. Note: OS/VS COBOL is supported for migration purposes to enable you to maintain existing programs. You are not recommended to write new applications using OS/VS COBOL. For information about OS/VS COBOL language considerations and restrictions, see Appendix. Using OS/VS COBOL on page 595. References to COBOL in this chapter do not always apply to OS/VS COBOL. With COBOL and COBOL/370 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 and other COBOL 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. v There is no need for the SERVICE RELOAD statement. If included, it is ignored. Users of COBOL with DBCS should not use the copybook DFHTCADS in their programs; copybook DFHCAKJ should be used instead. With compiler option DATA(24), working storage is allocated below the 16MB line. With compiler option DATA(31), working storage is allocated either above or below the 16MB line. This chapter describes: v Using based addressing with COBOL v COBOL programming restrictions on page 10 v Mixing languages on page 13 v Calling subprograms from COBOL on page 14 v Using COBOL with the ANSI 85 standard on page 18 v Using the COBOL2 translator option on page 28 v Using the COBOL3 translator option on page 29 v Using the OO COBOL translator option on page 29

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

Copyright IBM Corp. 1989, 2001

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 1 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 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 1 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 1. Addressing CICS data areas in locate mode

Using WITH DEBUGGING MODE

If a D is placed in column seven 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.

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

CICS Transaction Server: CICS Application Programming Guide

restrictions. How to use and create installation-specific COBOL reserved word tables is documented in the VS COBOL II Installation and Customization for MVS, and COBOL for OS/390 & VM Customization under OS/390 manuals. 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 run-time options in use at your installation. In particular, if your applications are not coded to ensure that working storage is properly initialized (for example, cleared with binary zeros before sending maps), you should use the WSCLEAR run-time option. The default, as supplied in the COBOL module IGZEOPD (alias of IGZ9OPD) is NOWSCLEAR. The WSCLEAR function is included in VS COBOL II Version 1 Release 3 as supplied. For information about customizing run-time options, see the VS COBOL II Installation and Customization for MVS manual. 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. Some format-2 ACCEPT statements are supported by Language Environment enabled compilers. See Using COBOL applications with Language Environment on page 52 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 under CICS only by Language Environment enabled compilers. v Do not use STOP literal, where literal does not identify a contained subprogram. v There are restrictions on the use of the SORT statement. See the VS COBOL II Application Programming Guide or the COBOL for OS/390 & VM 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 LE option is ignored in CICS. ENVIRONMENT DIVISION and FILE SECTION entries associated with data management, because CICS handles data management

| | | | | | | | | | | | | |

Chapter 3. Programming in COBOL

| | | |

| | |

User-specified parameters to the main program v Do not use the following compiler options: DYNAM NOLIB (if program is to be translated) NORENT NORES TRUNC v The use of the FDUMP compiler option results in a very large increase in program size. Therefore, short-of-storage problems may occur when using this option. For more information about the FDUMP option, see the VS COBOL II Application Programming Guide or the COBOL3 Application Programming Guide. v Use TRUNC(OPT) for handling binary data items if they conform to the PICTURE definitions, otherwise use TRUNC(BIN). (TRUNC(STD) is the default and TRUNC(BIN) is slower.) v The length of working storage, plus 80 bytes for storage accounting and save areas, must not exceed 64KB when the COBOL compiler option DATA(24) is used. If, however, the compiler option DATA(31) is used, up to 128MB are available. v If the DLI option is specified and an ENTRY statement immediately follows the PROCEDURE DIVISION header, it is recommended that the ENTRY statement be terminated with a period (.). v VS COBOL II and PL/I application programs cannot be link-edited together. For further information about using COBOL with other languages, see the VS COBOL II Application Programming Guide. v The following compiler options have no effect in a CICS environment: ADV FASTSRT OUTDD 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.

Restrictions for 31-bit addressing

These restrictions apply to a COBOL program running above the 16MB line: v 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). v If the receiving program is link-edited with AMODE(24), addresses passed to it must be 24-bits long.

Using the DL/I CALL interface

You should make the following changes to programs that use CALL DL/I: v Remove BLL cells for addressing the user interface block (UIB) and program control blocks (PCBs). 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.

CICS Transaction Server: CICS Application Programming Guide

Figure 2 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.
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 2. Using the DL/I CALL interface

Mixing languages
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.

Chapter 3. Programming in COBOL

An LE (Language Environment) run-unit can support a mixture of language levels, but if you are not using LE, a COBOL run unit can contain only: v COBOL programs compiled with the same compiler v Assembler language routines A CICS transaction can consist of many run units, each of which can be at a different language level. This means that a single transaction can consist of programs compiled by different compilers (including non-COBOL compilers). | | | | | | VS COBOL II programs can call VS COBOL II or assembler programs dynamically or statically, but programs compiled by different compilers can communicate with each other only using LINK or XCTL commands. COBOL for MVS & VM and later compilers can call any language programs statically or dynamically; LINK or XCTL are not required for inter-language communication.

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. 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. Table 1 on page 15 gives the rules governing the use of the three ways to call a subprogram. This table 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 18 shows logical levels and the effect of RETURN commands and CALL statements in linked and called programs. The term run unit, used in Figure 3 on page 18, is defined under the heading Mixing languages on page 13. When control is passed by a XCTL command, the

CICS Transaction Server: CICS Application Programming Guide

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 Table 1 refer to the separate translator. This step is not required if a compiler with an integrated translator is used.
Table 1. Rules governing methods of calling subprograms LINK Translation The linked subprogram must be translated if it, or any subprogram invoked from it, contains CICS function. The linked subprogram must be compiled and link-edited as a separate program. Static COBOL CALL 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). 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. 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.

Link-editing (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.)

CICS system definition data set (CSD) entries without program autoinstall (If you use program autoinstall, you do not need an entry in the CSD.)

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.

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

Return from called subprogram

The linked subprogram must return using either RETURN or the COBOL statement GOBACK. Any language supported by CICS.

The called subprogram must return using the COBOL statement GOBACK or EXIT PROGRAM. The use of RETURN in the called subprogram terminates the calling program. COBOL or assembler language.

Language of called subprogram

Chapter 3. Programming in COBOL

Table 1. Rules governing methods of calling subprograms (continued) LINK Contents of called or linked subprogram Static COBOL CALL Dynamic COBOL CALL

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 Data can be passed by any of the standard CICS methods to the subprogram (COMMAREA, TWA, TCTUA, TS queues) if the called or linked subprogram is processed by the CICS translator. 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. 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 Nestingwhat the application programmer must do on page 24. If the called subprogram uses 24-bit addressing and any parameter is above the 16MB line, COBOL issues a message and abends (1033). See the VS COBOL II Application Programming Debugging manual for information about this abend code.

Storage

On each entry to the linked subprogram, a new initialized copy of its working storage is provided, and the run unit is reinitialized (in some circumstances, this can cause a performance degradation).

On the first entry to the called subprogram within a CICS logical level, a new initialized copy of its working storage 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 Transaction Server: CICS Application Programming Guide

Table 1. Rules governing methods of calling subprograms (continued) LINK CICS condition/AID On entry to the called and abend handling 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 COBOL CALL Dynamic COBOL CALL If the dynamic COBOL CALL fails, CICS abend handling is not invoked, and you may get a COBOL abend code (1013). For COBOL calls without Language Environment/370 and COBOL calls with Language Environment/370 and CBLPSHPOP ON: 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 programs 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. For COBOL calls with Language Environment/370 and CBLPSHPOP OFF: The condition/AID and abend handling for the calling program remain in effect. Location of called or linked program Can be remote. Must be local. Must be local.

Chapter 3. Programming in COBOL

CICS

Level 0

Run Unit A

Program U GOBACK ... STOP RUN ... EXEC CICS RETURN ... CALL ... ... ... EXEC CICS LINK ...

Program V GOBACK ... EXEC CICS RETURN

Level 1

Run Unit B

Program W GOBACK ... STOP RUN ... EXEC CICS RETURN ... CALL ... ... ... EXEC CICS XCTL ...

Program X GOBACK ... EXEC CICS RETURN Level 2

Run Unit C

Program Y CALL ... ... GOBACK ... STOP RUN ... EXEC CICS RETURN

Program Z GOBACK ... STOP RUN ... EXEC CICS RETURN

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

Using COBOL with the ANSI 85 standard

| | Note: In the rest of this section the term translator refers to the use of separate translator and not to the use of an integrated translator. COBOL supports the ANSI85 COBOL standard. The CICS translator option ANSI85 supports this standard. If invoked with the ANSI85 option, the translator uses the COBOL2 option. The OOCOBOL and COBOL3 options imply both the ANSI85 and COBOL2 options. CICS support for this standard takes the form of changes to the translator. Because the translator is not a compiler, it is not affected by the ANSI85 standard.

CICS Transaction Server: CICS Application Programming Guide

The 1985 COBOL rules that affect the separate translator are: v Literals intervening in blank lines v Sequence numbers containing any character v Lower-case characters supported in all COBOL words v REPLACE statement v Batch compilation v Nested programs v Reference modification v Global variables v Interchangeability of comma, semicolon, and space v Symbolic character definition If a standard is not fully supported by the translator, a programming restriction applies. The 1985 COBOL rules are described under their appropriate headings, and each description is followed by a Separate Translator action. Summary of ANS185 restrictions on page 28 summarizes this information. The translator actions assume that you have specified the ANSI85 translator option. The term unit of compilation means a section of source input from which the compiler produces a single object program. A unit of compilation can contain a program and other programs nested within it.

Literals intervening in blank lines

Blank lines can appear anywhere in a COBOL source program. A blank line is a line that contains only blanks between margin C (the continuation column) and margin R (the last character in the line) inclusive.

Separate 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. (If the ANSI85 option is not specified, a blank line in a literal causes a translator error.) | | |

Integrated translator action

If blank lines occur within literals in a COBOL source program, this will have no effect on the translation.

Sequence numbers containing any character

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

Separate Translator action

The translator makes no check on the contents or sequence of the sequence number fields. If you specify the SEQ translator option, the translator issues a message saying that the SEQ option has no effect when you specify the ANSI85 option. See pageSEQ on page 83 for more information about this option.

Chapter 3. Programming in COBOL

| | | | |

Integrated translator action

The compiler checks the sequence numbers if the SEQ COBOL compiler option is in effect. If you specify the SEQ translator option the integrated translator issues a message saying that the SEQ option has no effect when you specify the ANSI85 option.

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 is specified as in the REPLACING option of the COPY statement, and can be pseudo-text, an identifier, a literal, or a COBOL word. REPLACE statements are processed after COPY statements.

Separate translator action

The separate 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. | | | |

Integrated Translator action

The integrated 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 according to the ANSI85 standard. 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 specified in the CBL or PROCESS card that initiates the unit 2. Options specified when the translator is invoked 3. Default options For more information about compilation, see the Chapter 9. Installing application programs on page 89.

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 (nonnested) program. This causes the inclusion of a NAME statement at the end of each program. See Figure 4 on page 21 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

CICS Transaction Server: CICS Application Programming Guide

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 22 shows the output from Figure 4 after editing in this way. For batch compilation you must vary the procedure described in the Chapter 9. Installing application programs on page 89. The following is a suggested method: 1. Split the supplied cataloged procedure DFHEITCL into two procedures; PROC1 containing the translate and compilation steps (TRN and COB), and PROC2 containing the linkage editor step 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, PARM='....,NAME,....', REGION=1024K

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 22. 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. Note: For Language Environment/370 applications, a different COBOL stub should be used and the order statement in Figure 5 on page 22 should be changed. The new sequence of statements reads as follows:
INCLUDE SDFHCOB(DFHELII) ORDER DFHELII NAME PROGA(R)

To use the new stub, the procedure DFHEITCL (DFHEITVL for COBOL users) should be changed. The line that reads STUB=DFHEILIC should be changed to STUB=DFHEILID and the line LIB=SDFHCOB should be changed to LIB=SDFHC370. An alternative method would be to specify
Chapter 3. Programming in COBOL

STUB=DFHEILID when invoking the procedure to include DFHELII. This can be done by passing the stub value as a parameter when invoking the procedure as follows:
// EXEC PROC=DFHEITCL

or
// EXEC PROC=DFHEITCL,STUB=DFHEILID,LIB=SDFHC370

6. In PROC2, add a DD statement for the library that includes the CICS stub. The standard name of this library is CICSTS21.CICS.SDFHCOB. The INCLUDE statement for the stub refers to this library by the DD name. In Figure 5, it is assumed you have used the DD name SDFHCOB. The suggested statement is:
//SDFHCOB DD DSN=CICSTS21.CICS.SDFHCOB, // 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.
....program a.... ................. INCLUDE SDFHCOB(DFHECI) ORDER DFHECI NAME PROGA(R) ................. ................. ....program b.... ................. ................. INCLUDE SDFHCOB(DFHECI) ORDER DFHECI NAME PROGB(R) ................. ....program c.... ................. INCLUDE SDFHCOB(DFHECI) ORDER DFHECI NAME PROGC(R)

Figure 5. Linkage editor input

Nested programs
Under the ANSI85 standard: 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.

CICS Transaction Server: CICS Application Programming Guide

For an explanation of valid calls to nested programs and of the COMMON attribute of a nested program, see the VS COBOL II Application Programming 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 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 uses the GLOBAL storage class for all translator-generated variables in the WORKING-STORAGE SECTION. 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 statement 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: If the ANSI85 option is specified, the translator interprets that the input source starts with a top-level program if the first noncomment 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.
Chapter 3. Programming in COBOL

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. Nestingwhat 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 statement 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:
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 COMMAREA as the first two parameters of the CALL For a PROCEDURE DIVISION statements in the calling and called programs respectively 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 on page 25) 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.

CICS Transaction Server: CICS Application Programming Guide

PROGRAM W

PROGRAM X

PROGRAM Y

PROGRAM Z

Figure 6. Nested program examplenesting 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. Ys PROCEDURE DIVISION statement 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 Xs PROCEDURE DIVISION statement must have DFHEIBLK and DFHCOMMAREA as its first two parameters. Figure 7 on page 26 illustrates the points in Nestingwhat the application programmer must do on page 24.

Chapter 3. Programming in COBOL

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

CICS Transaction Server: PROCEDURE Programming Guide CICS Application DIVISION.

. . .

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 (starting-position:) data-name (starting-position: length)

Data-name can be subscripted or qualified or both. Both starting-position and length can be arithmetic expressions.

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 must include a LENGTH option to specify the data length. 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 23) 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. (VS COBOL II Release 1.2 restricts the use of commas and semicolons to positions specifically defined in individual statement formats.)

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 3. Programming in COBOL

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.

Summary of ANS185 restrictions

The following is a summary of the programming restrictions associated with CICS translator support for the ANSI85 COBOL standard: v With the ANSI85 option, the translator varies the rule for parameters to be passed by a static COBOL call. For details, see Nestingwhat the application programmer must do on page 24. v A REPLACE statement must not contain an EXEC CICS command in pseudo-text. v Programs cannot use a comma or semicolon as a word separator in a CICS command. v Programs cannot use a symbolic character as an argument in a CICS command. v Comments should not precede the IDENTIFICATION DIVISION statement or follow the END PROGRAM statement. v CICS commands that use reference modification to define a character data value must include a LENGTH option to define the data length. v A name that must match an external definition, for example a file name or a transaction ID, must be coded in the same case as the external definition.

Using the COBOL2 translator option

If you are using the COBOL2 option you must use the VS COBOL II Compiler (5668-958 and 5668-023) to process your COBOL application programs. This compiler is a licensed program that conforms to the standard set by American National Standard COBOL, X3.23-1974. When you translate this program, you must use the COBOL2 translator option. For information about translating your program and preparing it for execution, see Chapter 8. Translation and compilation on page 67. Lower-case characters can occur anywhere in any COBOL word, including user-defined names, system names, and reserved words. A lower-case character can be used wherever an upper-case character is required by a COBOL compiler that does not conform to the ANSI85 standard.

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

CICS Transaction Server: CICS Application Programming Guide

(If the ANSI85 option is not specified, the translator expects COBOL words to consist entirely of upper-case characters.) Notes: 1. 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 should always be entered in the same case as the external definition. 2. CBL and PROCESS statements must be in upper case.

Using the COBOL3 translator option

If you are using the COBOL3 option you must use a Language Environment conforming compiler to process your application programs. See Levels of support in Language Environment on page 47. You can use either the COBOL3 or OOCOBOL translator option, depending on whether the program contains OO COBOL syntax. For information about translating your program and preparing it for execution, see Chapter 8. Translation and compilation on page 67. 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 v v v v addition, the translator accepts mixed case in: Translator options EXEC CICS commands, both for keywords and for arguments to keywords CBL and PROCESS statements Compiler directives such as EJECT and SKIP1

Using the OO COBOL translator option

If you are using the OOCOBOL option, you must use a Language Environment conforming compiler to process your application programs. See Levels of support in Language Environment on page 47. For information about translating your program and preparing it for execution, see Chapter 8. Translation and compilation on page 67. Lower-case characters can occur anywhere in any COBOL word, including user-defined names, system names, and reserved words.

Chapter 3. Programming in COBOL

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 should 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. The translator considers each class to be a separate unit of compilation. The translator does not monitor correct use of syntax. It makes the following assumptions about a user program: v Classes and methods are correctly terminated. v A class encapsulates only methods. v Methods do not encapsulate anything else. v A unit of compilation contains either a class or a program. The translator rejects any EXEC statements that appear in the PROCEDURE DIVISION of a class. The translator checks that a DATA DIVISION statement and a WORKING STORAGE SECTION both exist in a class definition.

Nesting programs
For OO COBOL, 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.

CICS Transaction Server: CICS Application Programming Guide

Chapter 4. Programming in C and C++

For programming in C, you can find information about appropriate compilers in the CICS Transaction Server for z/OS Migration Guide or the relevant C or C++ manual. 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. 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: v HANDLE ABEND LABEL(label) v HANDLE AID v HANDLE CONDITION v IGNORE CONDITION v PUSH HANDLE v POP HANDLE Use of these commands is diagnosed by the translator. Note the following programming considerations: 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. 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 C and C++ language programs must be link-edited with the attributes AMODE(31), and may reside above the 16MB line in the same way as PL/I programs. See Using PL/I and dynamic storage on page 40 for information about PL/I programs. 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.

Copyright IBM Corp. 1989, 2001

Return codes On return from a C or C++ language application, any value passed by C or C++ by the exit function or the return statement is saved in EIBRESP2. Sample programs A set of sample application programs is provided in Table 2 to show how EXEC CICS commands can be used in a program written in the C or C++ language.
Table 2. Sample programs Sample program DFH$DMNU Operator instruction (3270) DFH$DALL Update (3270) DFH$DBRW Browse (3270) DFH$DREN Order entry (3270) DFH$DCOM Order entry queue print (3270) DFH$DREP Report (3270) Map set DFH$DGA DFH$DGB DFH$DGC DFH$DGK DFH$DGL DFH$DGD Map source DFH$DMA DFH$DMB DFH$DMC DFH$DMK DFH$DML DFH$DMD Transaction ID DMNU DINQ, DADD, DUPD DBRW DORD DORQ DREP

The transaction and program definitions are provided in group DFH$DFLA in the CSD and should be installed using the command:
CEDA INSTALL GROUP(DFH$DFLA)

The following record description files are provided as C or C++ language header files: DFH$DFILFILEA record descriptor DFH$DL86L860 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 definitionsC 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 supporta 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++.

C and C++ programming restrictions

The following list describes some of the restrictions that exist in various versions of the C run-time libraries. 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.

CICS Transaction Server: CICS Application Programming Guide

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 You must specify the LENGTH option from commands that support the LENGTH option (for example, READ, READNEXT, READPREV, and WRITE commands). 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 The following commands are supported only if you use a Language Environment (LE) conforming compiler: FETCH RELEASE For further information see the Users Guide. Native C or C++ functions are implemented in the C or C++ run-time library. 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. 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. 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. 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. Take care not to use field names, which, though acceptable to the assembler compiler, cause the C or C++ compiler to abend. These include $, #, and @. See the relevant users guide for more information.

v v

Chapter 4. Programming in C and C++

v In C and C++ there is a STACK option with a 4KB default and suboptions of ANY and below. Additionally there are ANYHEAP (for heap storage above the 16MB line) and BELOWHEAP to control heap allocations. There is a heap manager that optimizes allocations.

Chapter 4. Programming in C and C++ on page 31 Passing arguments in C or C++ Accessing the EIB on page 36 Using Locale support on page 37 Programming in C++ on page 37

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, 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 3 shows the rules that apply when passing values as arguments in EXEC CICS commands.

CICS Transaction Server: CICS Application Programming Guide

Table 3. Rules for passing values as arguments in EXEC CICS commands Data type Character literal Usage Data-value (S) Coding the argument The user must specify the character literal directly. The translator takes care of any required indirection. The user must specify a pointer to the variable, possibly by prefixing the variable name with &. The user must specify the character variable directly. The translator takes care of any required indirection. 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. Whether receiving or sending, the argument should be the name of the character array containing the stringthe address of the first element of the array. The user must specify a pointer to the variable, possibly by prefixing the variable name with &. The user must specify the name of the variable. The translator looks after any indirection that is required. The user must specify the integer constant directly. The translator takes care of any required indirection. The user must code the address of the start of the structure or union, possibly by prefixing its name with &.

Character variable (char)

Data-area (R)

Data-value (S)

Character string literal

Name (S)

Character string variable

Data-area (R) Name (S)

Integer variable (short, long, or int) Data-area (R)

Data-value (S)

Integer constant (short, long, or int)

Data-value (S)

Structure or union

Data-area (S) Data-area (R)

Chapter 4. Programming in C and C++

Table 3. Rules for passing values as arguments in EXEC CICS commands (continued) Data type Array (of anything) Usage Data-area (R) Data-value (S) Coding the argument The translator does nothing. You must code 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. Whether receiving or sending, the argument 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.

Pointer (to anything)

Ptr-ref (R) Data-area (S)

Note: (R) indicates Receiver, where data is being received from CICS; (S) indicates Sender, 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 application. This applies to any commands that include RESP or RESP2 options.

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, in contrast to EIBTRNID as used in other CICS applications.

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

CICS Transaction Server: CICS Application Programming Guide

v Single-character fields are defined as unsigned char 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 4. C language codesets Character \ backslash } right brace { left brace # hash IBM-1047 E0 D0 C0 7B IBM-273 EC DC 43 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 as Language Environment/370. See Chapter 7. Language Environment on page 47 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 4. Programming in C and C++

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

CICS Transaction Server: CICS Application Programming Guide

Chapter 5. Programming in PL/I

For information about suitable compilers for PL/I, you should see the CICS Transaction Server for z/OS Migration Guide or the relevant PL/I manual. Note the following programming considerations: STAE execution-time option If this option is specified, an abend occurring in the transaction is handled by PL/I error handling routines, and the transaction may terminate normally, in which case, CICS facilities, such as dynamic transaction backout (DTB), are not invoked. If you issue an ABEND command with the STAE option specified, you can suppress the dump by using the NODUMP option. To get a meaningful abend code, you must also use the ABCODE option. Alternatively, specify the NOSTAE option, which bypasses PL/I routines handling the abend, allowing a meaningful abend code to be issued. Further information about PL/I and the STAE option is given in the CICS Recovery and Restart Guide. OPTIONS(MAIN) 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 Using PL/I and dynamic storage on page 40

PL/I programming restrictions

The following restrictions apply to a PL/I program that is to be used as a CICS application program. Refer to the PL/I Optimizing Compiler Programmers Guide for more guidance information about these facilities. 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 DELETE EXIT HALT DELAY DISPLAY GET LOCATE

Copyright IBM Corp. 1989, 2001

OPEN READ STOP UNLOCK

PUT REWRITE WRITE

The following commands are supported only if you use a Language Environment (LE) conforming compiler:
FETCH RELEASE

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.) Refer to the PL/I Optimizing Compiler Programmers Guide for more guidance information about when the use of these PL/I statements is necessary and the consequences of using them. 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 must include a LENGTH option to specify the data length. 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.

Using PL/I and dynamic storage

If your program is running LE-enabled, storage allocation is performed in accordance with the LE-run-time options you have established. For more information about running PL/I applications as LE-enabled programs, refer to the PL/I for MVS and VM Programming Guide. If you are using PL/I and your load module requires more than 64KB of dynamic storage to initialize, this results in the PL/I abend, APLG. With MVS, this limit is increased to one megabyte for areas that you allocate explicitly above the 16MB line using a GETMAIN command with the FLENGTH option. However, you should be aware that all automatic storage and DSA for PL/I save areas are below the 16MB line even when the program is specified as AMODE(31) and RMODE(ANY). This is because PL/I has to do a single GETMAIN operation below the line for this storage and CICS has a restriction of 64KB in a single GETMAIN operation below the 16MB line. The ISA size should be sufficient to satisfy all storage allocation. To

CICS Transaction Server: CICS Application Programming Guide

estimate this size, activate the REPORT option during the test phase. This option tells you if the ISA size is sufficient or if you need to perform GETMAIN operations during program processing. You can avoid this problem happening in an ESA AMODE(31) environment by coding your program as follows. Instead of making your biggest PL/I structures and arrays AUTOMATIC, define them as BASED on a POINTER variable, which you initialize using GETMAIN SET (pointer) FLENGTH(length). (Note that you must use FLENGTH instead of LENGTH.) For example, suppose you have a PL/I program with these arrays declared:
DCL A(10,10) FLOAT

and
DCL B(100,10) CHAR(100)

These arrays need 400 (that is, 10 x 10 x 4) and 100000 (that is, 100 x 10 x 100), respectively. You code your PL/I program as illustrated in Figure 8.
DCL (APOINTER, BPOINTER) DCL A(10,10) B(100,10) CSTG EXEC CICS GETMAIN SET(APOINTER) FLENGTH(CSTG(A)); EXEC CICS GETMAIN SET(BPOINTER) FLENGTH(CSTG(B)); POINTER; FLOAT BASED(APOINTER), CHAR(100) BASED(BPOINTER), BUILTIN;

Figure 8. Example of a PL/I program with arrays declared

This prevents a PL/I abend (APLG) occurring, and means that your program can use storage above the line that would otherwise have been needed below the line.

Chapter 5. Programming in PL/I

CICS Transaction Server: CICS Application Programming Guide

Chapter 6. Programming in Assembler

For programming in assembler language, you can find information about appropriate compilers in the CICS Transaction Server for z/OS Migration Guide or the relevant assembler manual. Note the following Assembler language programming considerations: Language restrictions 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. 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. 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. 31bit addressing The following restrictions apply to an assembler language application program executing in 31-bit mode: 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 509. 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 OS/390 MVS Programming: Extended Addressability Guide.
Copyright IBM Corp. 1989, 2001

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 44. Program control on page 503). 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 in one, and only one, of the high-level languages (COBOL, C, C++, or PL/I). When you do this, the high-level language program must be listed ahead of the assembler language program when you link edit, and the RDO program definition must specify that high-level language. If an assembler language program contains command-level calls, and is called from a high-level language program, it requires its own CICS interface stub. 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 9. PLITEST PLI

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

CICS Transaction Server: CICS Application Programming Guide

DFHEISTG MSG MYRESP ASMPROG

DSECT DS CL14 DS F 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 10. ASMTEST ASSEMBLE

For this to work, first link edit the assembler language program, as follows: and then link the PL/I and assembler language programs together:
INCLUDE SYSLIB(DFHEAI) INCLUDE OBJECT NAME ASMTEST(R)

INCLUDE SYSLIB(DFHPL1OI) INCLUDE OBJECT INCLUDE SYSLIB(ASMTEST) NAME PLITEST(R)

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.

Chapter 6. Programming in Assembler

CICS Transaction Server: CICS Application Programming Guide

Chapter 7. Language Environment

CICS supports Language Environment, which provides a common run-time environment for IBM implementations of assembler and those high-level languages (HLLs) supported by CICS, namely COBOL, PL/I, C, and C++. Before the introduction of Language Environment, each of the HLLs had to provide a separate run-time environment. With Language Environment, you can use one run-time 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. The compatibility and consistency problems of mixing different languages that occurred in the past are largely overcome. 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. Because of these advantages, enhancements to language support under CICS depend upon Language Environment. See the OS/390 Language Environment for OS/390 Concepts Guide for more information. Note: If you are using the CICS JVM to run to CICS Java programs or enterprise beans, you will need to have Language Environment installed and enabled. See Java Applications in CICS for more information about requirements for the CICS JVM.

Levels of support in Language Environment

Language Environment provides two levels of support for HLLs, depending on the compiler used. These two levels are: Language Environment-conforming support If an application program is compiled by a fully-conforming compiler, that program is said to be Language Environment-conforming. A conforming program can take advantage of Language Environment services in a CICS region and cannot execute without Language Environment support. The following fully Language Environment-conforming compilers are available: v OS/390 C/C++ v C/C++ for MVS/ESA v AD/CYCLE C/370 v COBOL for OS/390 & VM v COBOL for MVS & VM v AD/CYCLE for COBOL/370 v PL/I for MVS & VM v AD/CYCLE PL/I for MVS & VM v VisualAge PL/I for OS/390
Copyright IBM Corp. 1989, 2001

Language Environment also provides macros that enable assembler programs to be fully-conforming and so take advantage of the facilities provided under Language Environment. For details of these macros, see the OS/390 Language Environment for OS/390 & VM Programming Guide. Compatibility support Language Environment also supports the execution of programs that are not compiled with Language Environment-conforming compilers and assembler programs that do not use the macros provided. Such programs are known as non-Language Environment-conforming. They do not have to be recompiled or re-link-edited to run correctly in what Language Environment defines as compatibility mode. However, few of the advantages of Language Environment are available to such programs. The language in the PROGRAM definition for non-conforming programs does not have to be Language Environment for the program to execute correctly. Specify either the actual language or no language. 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. The following are the non-Language Environment-conforming compilers supported: v C/370 V1 & V2 v AD/Cycle C/370 V1R1 v OS/VS COBOL v VS COBOL II v OS PL/I Version 1 Release 3.0 onwards v OS PL/I Version 2

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.

CICS Transaction Server: CICS Application Programming Guide

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. 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. With the exception of date and time services which may be dynamically called by VS COBOL II programs, these services are only available to Language Environment-conforming programs. For further information about the details of these services, see the OS/390 Language Environment for OS/390 & VM Programming Guide. For information about the syntax required to call any of the services, see the OS/390 Language Environment for OS/390 & VM 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-handlingfor details. Storage Language Environment uses storage obtained from CICS for each run-unit. See Managing Language Environment storage on page 50 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 run-time 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.
Chapter 7. Language Environment

When a CICS HANDLE ABEND is not active, Language Environment condition handling does gain control for abends and program interrupts if the run-time 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 OS/390 Language Environment for OS/390 & VM Programming Guide.

User-written LE condition handlers

The run-time 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. 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 run-time option and the CEEHDLR and CEEHDLU services, see the OS/390 Language Environment for OS/390 & VM 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 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 OS/390 Language Environment for OS/390 & VM 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.

CICS Transaction Server: CICS Application Programming Guide

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 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 a program specifies a run-time 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.

Using C/C++ applications with Language Environment

The information given in Chapter 4. Programming in C and C++ on page 31 applies to C and C++ programs using Language Environment under CICS, except for the differences noted below. 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/C++ does 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.

Chapter 7. Language Environment

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. Return value If you terminate a C or C++ program with an exit() function or 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. Invoking CSP programs All C/C++ programs running under CICS must run with AMODE(31), RMODE(ANY). 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).

Using COBOL applications with Language Environment

CICS supports COBOL programs that have been compiled by any of the following compilers: v COBOL for OS/390 & VM v COBOL for MVS & VM v COBOL/370 v VS COBOL II v OS/VS COBOL Programs compiled by any of these compilers can run under Language Environment, but only the first three (COBOL for OS/390 & VM, COBOL for MVS & VM, and COBOL/370) are Language Environment-conforming. There are some restrictions associated with the others, as described below: Communication between modules compiled by different COBOL compilers Calls between COBOL programs compiled with one of the three Language Environment-conforming compilers, both static and dynamic, are fully supported, and there are no restrictions on the called program. Programs compiled with the VS COBOL II compiler and link-edited using the Language Environment library fall into the same category with respect to calls. However, the only way that programs in this category can invoke or be invoked by any OS/VS COBOL program is by a CICS LINK or XCTL command. Language Environment callable services Programs compiled by one of the Language Environment-conforming COBOL compilers can use all Language Environment callable services, either dynamically or statically. VS COBOL II programs can make dynamic calls to the date and time callable services, but no other calls, either static or dynamic, to Language Environment callable services are supported. No callable services are available to OS/VS COBOL programs. OS/VS COBOL restrictions Language Environment provides a set of compatibility library routines that permit you to run OS/VS COBOL applications under CICS in compatibility mode. When you run an OS/VS COBOL application under CICS, the

CICS Transaction Server: CICS Application Programming Guide

environment that is established for a run unit by the compatibility library routines supports only OS/VS COBOL. This compatibility library does not contain many of the services normally offered under Language Environment. In particular: v Language Environment run-time options and callable services are not supported. v Only static calls are permitted, and only to other OS/VS COBOL-compiled programs and assembler programs. v The called program cannot contain CICS commands. Utilities for re-linking If object modules are not available for re-linking existing COBOL programs to run under Language Environment, three sample jobs are provided in the SCEESAMP sample library that can be used to replace all OS/VS COBOL and VS COBOL II library routines in load modules containing OS/VS COBOL and VS COBOL II programs. These sample jobs are: v IGZWRLKA to re-link-edit a VS COBOL II load module with Language Environment v IGZWRLKB to re-link-edit an OS/VS COBOL load module with Language Environment v IGZWRLKC to re-link-edit a load module that contains both OS/VS COBOL programs and VS COBOL II programs with Language Environment. CICS stub Although COBOL programs linked with the old CICS stub, DFHECI, run under Language Environment, use of the DFHELII stub is recommended and could be essential in a mixed language environment. CBLPSHPOP option The CBLPSHPOP run-time 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 for OS/390 & VM, COBOL for MVS & VM, COBOL/370 or a VS COBOL II 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 run-time options for Language Environment on page 60. 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 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 run-time detected error occurs.

Chapter 7. Language Environment

v It converts all unhandled run-time 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 further information on migrating existing COBOL programs to run under Language Environment, see the COBOL for OS/390 & VM Compiler and Run-Time Migration Guide.

Using PL/I applications with Language Environment

The advice and restrictions listed in Chapter 5. Programming in PL/I on page 39apply to PL/I programs running under Language Environment, except that the restriction on FETCH and RELEASE statements has been removed. 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 for MVS & VM Language Reference. Many of the restrictions have been removed with VisualAge PL/I. 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. 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

CICS Transaction Server: CICS Application Programming Guide

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.) 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 PL/I for MVS & VM Compiler and Run-Time 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 run-time option to register it to do this. For details of this option see the OS/390 Language Environment for OS/390 & VM Programming Guide.

Using Assembler applications with Language Environment

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/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 57. Conforming routines If you are coding a new assembler routine that you want to conform to the Language Environment interface or if your assembler routine calls Language Environment services, observe the following:
Chapter 7. Language Environment

v Use the macros provided by Language Environment. For a list of these macros, see the OS/390 Language Environment for OS/390 & VM Programming Guide. v Ensure that the CEEENTRY macro contains the option MAIN=NO. ( Language Environment-conforming assembler main routines are not supported under CICS and 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 OS/VS COBOL or 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.) 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 R1 R12 R13 R14 R15 Reserved Address of the parameter list, or zero Common anchor area (CAA) address Callers dynamic storage area (DSA) Return address 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 callers 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 callers DSA. While the subroutine is running R13 must point to the routines 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

CICS Transaction Server: CICS Application Programming Guide

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 (see DFSMS/MVS Macro Instructions for Data Sets). 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 routines 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. For more information or for explanations of the terms used in this section see the chapter on Assembler Considerations in the OS/390 Language Environment for OS/390 & VM Programming Guide.

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 OS/390 Language Environment Writing Interlanguage 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 Environmentconforming compiler. However, you can make programs that have been compiled with earlier versions of compilers Language Environment-conforming by re-link-editing. This will achieve the same result. 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.

Chapter 7. Language Environment

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 the OS/390 Language Environment for OS/390 & VM Writing Interlanguage Communication Applicationsmanual; you should consult this book if your application mixes C/C++ and COBOL. 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 COBOL for OS/390 & VM, COBOL for MVS & VM or COBOL/370, and PL/I for MVS & VM or VisualAge PL/I for OS/390 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 Environmentconforming 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

CICS Transaction Server: CICS Application Programming Guide

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 Environmentconforming 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. Notes: 1. For assembler to call C or C++, you must include the following statement: C #pragma linkage(,OS) C++ extern OS 2. If you want to call a Language Environment-conforming assembler routine from a VS COBOL II program, specify NAB=NO on the CEEENTRY macro. 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 OS/390 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. DLL support is available for applications under CICS where the code has been compiled using any of the compilers for the following programming languages, specifying the DLL compiler option where required: v C and C++ v COBOL for OS/390 and VM v VisualAge PL/I for OS/390 You should define all potential DLL executable modules as PROGRAM resources to CICS. For more information on building and using DLLs, see the OS/390 Language Environment for OS/390 & VM Programming Guide.

Chapter 7. Language Environment

Defining run-time options for Language Environment

Language Environment provides run-time options to control your programs 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. Programs initiated from the Web, Java or through the CICS IIOP services use the Language Environment preinitialization module, CEEPEPI. This has its own version of the CEEDOPT CSECT and such programs get their run-time 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 run-time 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. In the CEEUOPT CSECT, where user-supplied application program-level run-time options are located. This CSECT is linked with the application program itself. 4. 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:
DECLARE PLIXOPT CHARACTER(18) VARYING STATIC EXTERNAL INIT('RPTOPTS(ON) NOSTAE');

Note: There is no source code mechanism that allows the setting of run-time options within COBOL programs or within C++ programs. 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 Language Environment for OS/390 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 DEBUG MSGFILE RTEREUS VERSION AIXBLD EXECOPS NONIPTSTACK RTLS CBLOPTS INTERRUPT PLITASKCOUNT SIMVRD CBLQDA LIBRARY POSIX THREADHEAP

CICS Transaction Server: CICS Application Programming Guide

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 Language Environment for OS/390 Customization.

Run-time 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 run-time options exactly as discussed above. These run-time options are completely independent of those that existed in the creating enclave. Frequent use of EXEC CICS LINK, and the individual setting of many run-time 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 run-time 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
Chapter 7. Language Environment

v v v v

HANDLE CONDITION IGNORE CONDITION POP HANDLE 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 run-time 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 run-time options and also for their meanings, see the OS/390 Language Environment for OS/390 & VM Programming Guide.

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 run-time 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 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 57 apply. For more information on the High Level Language user exit, CEEBINT, see the OS/390 Language Environment for OS/390 & VM Programming Guide.

CICS Transaction Server: CICS Application Programming Guide

Part 2. Preparing applications to run

| | | | Chapter 8. Translation and compilation . . . The integrated CICS translator . . . . . . . Supported compilers . . . . . . . . . . Using the integrated CICS translator . . . . Specifying CICS translator options. . . . . The translation process . . . . . . . . . . The CICS-supplied translators . . . . . . . Dynamic invocation of the separate translator Translator option list . . . . . . . . . Data definition (DD name) list . . . . . Using a separate translator . . . . . . . . Defining translator options . . . . . . . . . Translator options . . . . . . . . . . . ANS185 . . . . . . . . . . . . . APOST. . . . . . . . . . . . . . CBLCARD . . . . . . . . . . . . CICS . . . . . . . . . . . . . . COBOL2 . . . . . . . . . . . . . COBOL3 . . . . . . . . . . . . . CPP . . . . . . . . . . . . . . . CPSM . . . . . . . . . . . . . . DBCS . . . . . . . . . . . . . . DEBUG . . . . . . . . . . . . . DLI . . . . . . . . . . . . . . . EDF . . . . . . . . . . . . . . . EPILOG . . . . . . . . . . . . . EXCI . . . . . . . . . . . . . . FE . . . . . . . . . . . . . . . FEPI. . . . . . . . . . . . . . . FLAG (I, W, E, or S) . . . . . . . . . GDS. . . . . . . . . . . . . . . GRAPHIC. . . . . . . . . . . . . LENGTH . . . . . . . . . . . . . LINECOUNT(n). . . . . . . . . . . LINKAGE . . . . . . . . . . . . . MARGINS(m,n[,c]) . . . . . . . . . NATLANG(EN or KA) . . . . . . . . NOCBLCARD . . . . . . . . . . . NOCPSM . . . . . . . . . . . . . NODEBUG . . . . . . . . . . . . NOEDF . . . . . . . . . . . . . NOEPILOG . . . . . . . . . . . . NOFE . . . . . . . . . . . . . . NOFEPI . . . . . . . . . . . . . NOLENGTH . . . . . . . . . . . . NOLINKAGE. . . . . . . . . . . . NONUM . . . . . . . . . . . . . NOOPSEQUENCE . . . . . . . . . NOOPTIONS . . . . . . . . . . . NOPROLOG. . . . . . . . . . . . NOSEQ . . . . . . . . . . . . . NOSEQUENCE . . . . . . . . . . NOSOURCE. . . . . . . . . . . .
Copyright IBM Corp. 1989, 2001

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

67 67 67 68 68 69 72 72 72 72 73 74 75 75 75 75 75 75 75 76 76 76 76 76 76 76 76 77 77 77 77 77 78 78 78 78 79 79 79 79 79 79 80 80 80 80 80 80 80 81 81 81 81

NOSPIE . . . . . . . . . . . . . NOVBREF . . . . . . . . . . . . NUM . . . . . . . . . . . . . . OOCOBOL . . . . . . . . . . . . OPMARGINS(m,n[,c]) . . . . . . . . OPSEQUENCE(m,n). . . . . . . . . OPTIONS . . . . . . . . . . . . . PROLOG . . . . . . . . . . . . . QUOTE . . . . . . . . . . . . . SEQ . . . . . . . . . . . . . . . SEQUENCE(m,n) . . . . . . . . . . SOURCE . . . . . . . . . . . . . SP . . . . . . . . . . . . . . . SPACE(1 or 2 or 3) . . . . . . . . . SPIE . . . . . . . . . . . . . . SYSEIB . . . . . . . . . . . . . VBREF . . . . . . . . . . . . . . Translator options table . . . . . . . . . Using COPY statements . . . . . . . . . The CICS-supplied interface modules . . . . The EXEC interface modules. . . . . . . The CPI Communications interface module . The SAA Resource Recovery interface module Using the EXEC interface modules . . . . . COBOL and PL/I . . . . . . . . . . . C and C++ . . . . . . . . . . . . . Assembler language . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . .

81 81 81 82 82 82 82 82 82 83 83 83 83 83 84 84 84 84 85 86 86 86 86 86 87 87 87

| | | | | | | | | | | | | | | | | | | | | | | | | | |

Chapter 9. Installing application programs. . . . . . . . . Program installation roadmap . . . . . . . . . . . . . . Preparing for program installation . . . . . . . . . . . . Defining MVS residence and addressing modes. . . . . . . . Establishing a programs addressing mode . . . . . . . . CICS address space considerations . . . . . . . . . . . Making programs permanently resident . . . . . . . . . . Running applications in the link pack area . . . . . . . . . . Running application programs in the RDSAs . . . . . . . . . Assembler . . . . . . . . . . . . . . . . . . . . C and C/++ . . . . . . . . . . . . . . . . . . . . COBOL . . . . . . . . . . . . . . . . . . . . . PL/I . . . . . . . . . . . . . . . . . . . . . . . Using BMS map sets in application programs . . . . . . . . Using the CICS-supplied procedures to install application programs Installing programs in load library secondary extents . . . . . Including the CICS-supplied interface modules . . . . . . . . Installing assembler language application programs . . . . . . Sample JCL to install assembler application programs . . . . Installing COBOL application programs . . . . . . . . . . Sample JCL to install COBOL application programs . . . . . Installing PL/I application programs . . . . . . . . . . . . Sample JCL to install PL/I application programs . . . . . . Installing C application programs . . . . . . . . . . . . . Sample JCL to install C application programs . . . . . . . Using your own job streams . . . . . . . . . . . . . . Translator requirements . . . . . . . . . . . . . . . Online programs that use EXEC CICS or EXEC DLI commands

. 89 . 89 . 90 . 91 . 91 . 91 . 92 . 92 . 93 . 93 . 94 . 94 . 95 . 96 . 96 . 97 . 97 . 98 . 99 . 100 . 101 . 104 . 104 . 106 . 107 . 108 . 109 . 109

CICS Transaction Server: CICS Application Programming Guide

| | |

Online programs that use the CALL DLI interface . . . . . . . . . . . 112 Batch or BMP programs that use EXEC DLI commands . . . . . . . . 112 Batch or BMP programs that use DL/I CALL commands . . . . . . . . 112 Chapter 10. Installing map sets and partition sets . . . Installing map sets . . . . . . . . . . . . . . . . Types of map sets . . . . . . . . . . . . . . . Defining the type of map set you require . . . . . . Using extended data stream terminals . . . . . . . Installing physical map sets . . . . . . . . . . . . Installing symbolic description map sets . . . . . . . Installing physical and symbolic description maps together JCL to install physical and symbolic description maps . Adding a CSECT to your map assembly . . . . . . Installing partition sets . . . . . . . . . . . . . . . Defining programs, map sets, and partition sets to CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 114 114 115 116 116 118 119 120 121 121 123

| | | | | | | | | | |

Part 2. Preparing applications to run

CICS Transaction Server: CICS Application Programming Guide

Chapter 8. Translation and compilation

| | | | | | | | | | 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 separate 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 allow you to 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. This chapter describes: v The integrated CICS translator v The translation process on page 69 v The CICS-supplied translators on page 72 v Using a separate translator on page 73 v Defining translator options on page 74 v Using COPY statements on page 85 v The CICS-supplied interface modules on page 86 v Using the EXEC interface modules on page 86 | | | | | | | | | | | | | | | | | | | | | | | |

The integrated CICS translator

In earlier CICS releases, CICS application programs had to be translated before they could be 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 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.

Supported compilers
The CICS integrated translator is supported by the following releases of the COBOL and PL/I compilers: v IBM COBOL for OS/390 & VM, Version 2 Release 2, program number 5648-A25, with APAR PQ45462 applied. v IBM VisualAge PL/I for OS/390, Version 2 Release 2.1, program number 5655-B22, with APAR PQ45562 applied.

Copyright IBM Corp. 1989, 2001

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

If you use any other compiler, you will need to translate your program in the traditional way descibed in Chapter 8. Translation and compilation on page 67.

Using the integrated CICS translator

The language compilers provide various procedures that you can use with the integrated CICS translator. These procedures are documented in APAR PQ45462 for COBOL, and APAR PQ45562 for PL/I. The procedure that you use needs to have CICSTS21.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, RENT and NOANALYZE 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.

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 VisualAge PL/I for 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 COBOL for OS/390 & VM Programming Guide. For more information on the CICS compiler option, see APAR PQ45462. 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: v APOST or QUOTE v CPSM or NOCPSM v CICS v DBCS

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | |

v v v v v v v v v v v

DEBUG or NODEBUG DLI EDF or NOEDF FEPI or NOFEPI GRAPHIC LENGTH or NOLENGTH LINKAGE or NOLINKAGE NATLANG OOCOBOL SP 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 11 on page 70 shows the process.

Chapter 8. Translation and compilation

SYSIN (source program)

CICS Translation

Commandlevel language translator

SYSPUNCH (translated source program)

SYSPRINT (translator listing)

Compilation (assembly)

High-level language compiler (or assembler) Object module

High-level language compiler (or assembler) listing

Link-editor

Link-editor listing

Link Edit

Load library

Figure 11. 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 and EXEC DLI commands have been turned into function call statements. v CICS DFHRESP and DFHVALUE built-in functions have been processed.

CICS Transaction Server: CICS Application Programming Guide

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. The 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 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 Page-building and routing operations on page 160.

Chapter 8. Translation and compilation

The CICS-supplied translators

The following CICS-supplied translators are installed in the CICSTS21.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 1 2 Standard DD name Entry Standard DD name Entry Standard DD name SYSIN SYSPRINT SYSPUNCH

not applicable 3 not applicable 4

not applicable 5 not applicable 6 7

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.

CICS Transaction Server: CICS Application Programming Guide

Using a separate 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 DFHEITCL, 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 translated with the ANSI85 option, 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

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 5 on page 84 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 the ones that are underlined or explicitly noted. Many installations change the defaults, however. 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 separate translator on page 73. Note: Translator options for programs to be compiled with OS/VS COBOL are described in Appendix. Using OS/VS COBOL on page 595. OS/VS COBOL is supported for migration purposes to enable you to maintain existing programs. You are not recommended to write new applications using OS/VS COBOL.

CICS Transaction Server: CICS Application Programming Guide

Translator options
ANS185
(COBOL only) ANS185 specifies that the translator is to translate COBOL programs that implement the ANSI85 standards. Note: This option causes the COBOL2 and NOSEQ options to be used, even if you have specified SEQ. ANSI85 is implied by either OOCOBOL or COBOL3 options.

APOST
(COBOL only) APOST indicates that literals are delineated by the apostrophe (). This is the defaultQUOTE is the alternative. The same value must be specified for the translator step and the following compile step. | | APOST and QUOTE apply only to VS COBOL II and COBOL /370. Later compilers can use either option with both types of delimiters in the same program. The CICS-supplied COBOL copybooks use APOST.

CBLCARD
(COBOL only) CBLCARD specifies that the translator is to generate a CBL statement. This is the defaultthe 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) COBOL2 specifies that the translator is to translate programs compiled by the VS COBOL II (or later) compilers.

COBOL3
(COBOL only) COBOL3 specifies that the translator is to translate programs compiled by a Language Environment conforming compiler. See Levels of support in Language Environment on page 47. This option implies the ANSI85 and COBOL2 options.
Chapter 8. Translation and compilation

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 the VS COBOL II Application Programming: Language Reference and the COBOL for OS/390 &VM Language Reference. If you specify this option, the COBOL2 option is assumed.

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 defaultNODEBUG 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 defaultthe 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 defaultthe 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.

CICS Transaction Server: 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).

FE
(COBOL only) FE produces translator information messages that print (in hexadecimal notation) the bit pattern corresponding to the first argument of the translated call. This bit pattern has the encoded information that CICS uses to determine which function is required and which options are specified. All diagnostic messages are listed, whatever the FLAG option specifies. The alternative is NOFE, which is the default.

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 not discussed in this book, but are discussed in the CICS Front End Programming Interface Users 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 S All except warning and information messages. Only severe and unrecoverable error messages.

Note: The FE option overrides the FLAG option.

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.

Chapter 8. Translation and compilation

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 PL/I Programming: Language Reference manual.

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) 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. | | DFHEIBLK is defined in upper-case, but if OOCOBOL or COBOL3 are also specified, a mixed-case version of the EIB structure (DFHEIBLC) is inserted. LINKAGE is the defaultthe 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. 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 n Column number of left-hand margin. Column number of right-hand margin. It must be greater than m.

CICS Transaction Server: CICS Application Programming Guide

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 KA (Default) English. 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 parameters which the CICS translator normally inserts must be set using VS COBOL IIs IGYCOPT macro. These parameters are RENT, RES, NODYNAM, and LIB.

NOCPSM
NOCPSM specifies that the translator is not to process EXEC CPSM commands. This is the defaultthe 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).

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)
Chapter 8. Translation and compilation

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

NOFE
(COBOL only) NOFE does not produce translator information messages that print the bit pattern corresponding to the first argument of the translated call. NOFE is the defaultthe alternative is FE.

NOFEPI
NOFEPI disallows access to the FEPI API commands of the CICS Front End Programming Interface (FEPI). NOFEPI is the defaultthe 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. 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 defaultthe 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 records and NOOPSEQUENCE for variable-length records. For PL/I, the default is OPSEQUENCE(73,80) for both types of records.

NOOPTIONS
Abbreviation: NOP

CICS Transaction Server: CICS Application Programming Guide

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. If you specify the ANSI85 option for COBOL, the translator does no sequence checking and the SEQ or NOSEQ option is ignored.

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
(C, C++ and PL/I only) 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 defaultthe alternative is VBREF.

NUM
(COBOL only) 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.
Chapter 8. Translation and compilation

OOCOBOL
(OO COBOL only) 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 ANSI85, COBOL2, and COBOL3 options.

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
Abbreviations: 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 Reference manual for programming information about these prolog macros.) PROLOG is the defaultthe alternative is NOPROLOG.

QUOTE
(COBOL only)

CICS Transaction Server: CICS Application Programming Guide

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 defaultthe alternative is NOSEQ. If a statement is not in sequence, it is flagged. If you specify the ANSI85 option for COBOL, the translator does no sequence checking and the SEQ option is ignored.

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 n Leftmost sequence number column. 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
(C, C++, and PL/I only) SOURCE instructs the translator to include a listing of the translated source program in the translator listing. SOURCE is the defaultthe 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, 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)
Chapter 8. Translation and compilation

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

Translator options table

Table 5. Translator options applicable to programming language Translator option ANSI85 APOST or QUOTE CBLCARD or NOCBLCARD CICS COBOL2 COBOL3 CPP CPSM or NOCPSM DBCS DEBUG or NODEBUG DLI EDF or NOEDF EPILOG or NOEPILOG EXCI FE or NOFE X X X X X X X X X X X X X X X X X X X X X X X X COBOL X X X X X X X X X X X X X X C C++ PL/I Assembler

CICS Transaction Server: CICS Application Programming Guide

Table 5. Translator options applicable to programming language (continued) Translator option FEPI or NOFEPI FLAG(I or W or E or S) GDS GRAPHIC LENGTH or NOLENGTH LINECOUNT(n) LINKAGE or NOLINKAGE MARGINS(m,n) NATLANG NUM or NONUM OOCOBOL OPMARGINS(m,n[,c ]) OPSEQUENCE(m,n) or NOOPSEQUENCE OPTIONS or NOOPTIONS PROLOG or NOPROLOG QUOTE or APOST SEQ or NOSEQ SEQUENCE(m,n) or NOSEQUENCE SOURCE or NOSOURCE SP SPACE(1 or 2 or 3) SPIE or NOSPIE SYSEIB VBREF or NOVBREF X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X COBOL X X C X X X C++ X X X X X X X X PL/I X X X Assembler X

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

Chapter 8. Translation and compilation

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 CICSTS21.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 CICSTS21.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 CICSTS21.CICS.SDFHLOAD library, must be link-edited with each application program that uses the SAA Resource Recovery facility.

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.. Java application programs that use the VisualAge for Java, Enterprise ToolKit for OS/390 do not need EXEC interface stubs, but there are stubs for each of the other supported programming languages. Language Environment-conforming languages require the DFHELII interface module. Otherwise, you should use the following interface modules for the assembler, C, COBOL, and PL/I programming languages:
Table 6. Interface modules Language ASSEMBLER Interface module name DFHEAI and DFHEA10

CICS Transaction Server: CICS Application Programming Guide

Table 6. Interface modules (continued) Language C COBOL PL/I Language Environment enabled Interface module name DFHELII DFHECI DFHPL1OI supplied by PL/I ( and DFHEPI which is part of the PL/I DFHPLIO1 module). DFHELII

COBOL and PL/I

Each EXEC command is translated into a COBOL CALL statement or PL/I CALL statement (as appropriate) by the command translator. The external entry point invoked by the CALL statement is resolved to an entry in the stub. The COBOL command-level interface has an assembler language stub in the COBOL library. Similarly, a PL/I application program must include a PL/I-supplied stub as well as the EXEC interface stub. This stub is included by automatic library call.

C and C++
These programs must include the EXEC interface stub called DFHELII. There is no library stub. The stub must be link-edited with your application program to provide communication between your code and the EXEC interface program (DFHEIP). For C and C++, each EXEC CICS command is translated by the command translator into a C or C++ function invocation. The external entry point is invoked by the function and is resolved by an entry in the stub.

Assembler language
Each EXEC command is translated into an invocation of the DFHECALL macro by the command translator and the external entry point invoked by DFHECALL is resolved to an entry in the stub.

Chapter 8. Translation and compilation

CICS Transaction Server: 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 Transaction Affinities Utility to detect whether the programs are likely to cause intertransaction affinity. See Chapter 14. Affinity on page 171 for a description of intertransaction affinity. This chapter includes: v Program installation roadmap v Defining MVS residence and addressing modes on page 91 v Running application programs in the RDSAs on page 93 v Using BMS map sets in application programs on page 96 v Using the CICS-supplied procedures to install application programs on page 96 v Including the CICS-supplied interface modules on page 97 v Installing assembler language application programs on page 98 v Installing COBOL application programs on page 100 v Installing PL/I application programs on page 104 v Installing C application programs on page 106 v Using your own job streams on page 108

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 96. To use your own JCL to install application programs, see Using your own job streams on page 108. 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. 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
Copyright IBM Corp. 1989, 2001

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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. Pre-link any C and C++ programs. 4. 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. 5. Create resource definition entries, in the CSD, for any transaction that calls the program, and install them.. 6. 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. If you have macro-level programs from an earlier release of CICS, recode them as command-level programs. Furthermore, 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 a 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 the CICS 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 92. For information on preparing programs to run in the read-only DSAs, see Running application programs in the RDSAs on page 93. 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 96.

CICS Transaction Server: 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 written in assembler language, C/370, VS COBOL II, or PL/I Version 1 Release 5.1 or later, can reside above 16MB, and address areas above 16MB. The program can contain EXEC CICS, EXEC DLI, and CALL DL/I commands.

Establishing a programs 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) AMODE(31) AMODE(ANY) RMODE(24) Specifies 24-bit addressing mode. Specifies 31-bit addressing mode. Specifies either 24- or 31-bit addressing mode. 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. Indicates that the module can reside anywhere in virtual storage.

RMODE(ANY)

Note: C/370 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.) 4. The link-edit modules DFHECI and DFHEPI assign AMODE(31) and RMODE(ANY) to COBOL and PL/I programs.

CICS address space considerations

Table 7 gives the valid combinations of the AMODE and RMODE attributes and their effects:
Chapter 9. Installing application programs

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Table 7. Valid AMODE and RMODE specifications and their effects AMODE 24 31 ANY 31 RMODE 24 24 24 ANY Residence Below 16MB Below 16MB Below 16MB Above 16MB Addressing 24-bit mode 31-bit mode 31-bit mode 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 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 LLAs 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, VS COBOL II or later, or PL/I Release 5.1, 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). For the COBOL and COBOL2 translator options, the translator also generates the RES compiler option.)

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

PL/I Version 1 Release 5.1 or later Do not overwrite STATIC storage. (The CICS translator inserts the required REENTRANT option into the PROCEDURE statement.) 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 wayfor 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

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

(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 MYPROG MYPROG CSECT AMODE 31 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 (for C) and DFHYITEL (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/370 (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:
//C370PROG JOB 1,user_name,MSGCLASS=A,CLASS=A,NOTIFY=userid //EYTDL EXEC DFHEYTDL, . (other parameters as necessary) . // LNKPARM='LIST,MAP,LET,XREF,RENT'

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.

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

LE-conforming COBOL and VS COBOL II programs that require 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 (DFHECI) 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 (and also DFHEITVL), 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:
//COB2PROG 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 (DFHEPI, which is part of the PL/I DFHPL1OI module) 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 (and DFHEITPL), 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

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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 113. 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 CICSTS21.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 CICSTS21.CICS.SDFHMAC library (the default), include a DD statement for the CICSTS21.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 CICSTS21.CICS.SDFHMAC library in the SYSLIB concatenation. v For PL/I, specify a library that has a block size of 400 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 113. For information about writing programs to use BMS services, seeChapter 30. Basic mapping support on page 393.

Using the CICS-supplied procedures to install application programs

CICS supplies job control statements (JCL) for the translate, 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 CICSTS21.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 8 on page 97.

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Table 8. Procedures for installing application programs Language LE-conforming compilers Online Assembler C C++ COBOL PL/I DFHYITDL DFHYITEL DFHYITVL DFHYITPL EXCI DFHYXTDL DFHYXTEL DFHYXTVL DFHYXTPL non-LE-conforming compilers Online DFHEITAL DFHEITDL DFHEITVL DFHEITPL EXCI DFHEXTAL DFHEXTDL DFHEXTVL DFHEXTPL

Note: DFHYITEL may also be used for C as long as you specify the correct name of the C compiler on the COMPILER parameter. All the sample job streams shown apply if your program source statements are imbedded in the text. If your program source is a member of a partitioned data set, replace the //TRN.SYSIN statement by a statement in one of the following forms:
//TRN.SYSIN DD DSN=partition.dataset.name(programname),DISP=SHR //SYSIN DD DSN=partition.dataset.name(programname),DISP=SHR

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. However, this can increase the search time when loading modules from the secondary extents. You should avoid using secondary extents if possible.

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. These library members are named DFHEILIx, where x is A for assembler, C for COBOL, D for C, or P for PL/I. For example, the DFHYITVL procedure uses the following statements:
//COPYLINK //SYSUT1 //SYSUT2 // // //SYSPRINT //SYSIN . . . //SYSLIN // // EXEC PGM=IEBGENER,COND=(7,LT,COB) DD DSN=&INDEX..SDFHCOB(&STUB),DISP=SHR DD DSN=&&COPYLINK,DISP=(NEW,PASS), DCB=(LRECL=80,BLKSIZE=400,RECFM=FB), UNIT=&WORK,SPACE=(400,(20,20)) DD SYSOUT=&OUTC DD DUMMY 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 DFHEILIC. The DFHEILIC member contains the statement INCLUDE SYSLIB(DFHECI).

Chapter 9. Installing application programs

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

In the DFHEITPL procedure for installing PL/I application programs, the SYS1.PL1BASE library is included in the SYSLIB concatenation. This is needed because the INCLUDE statement in the DFHEILIP module specifies INCLUDE SYSLIB(DFHPL1OI), where DFHPL1OI is the name of the PL/I interface module supplied by PL/I. . In the DFHEILIP module, after the INCLUDE statement, there is the REPLACE PLISTART link-edit command. This command causes the CSECT PLISTART, which is inserted by the compiler, to be removed because equivalent function is in the stub DFHPL1OI. The REPLACE PLISTART command is needed for programs to run under Language Environment, but is optional for other PL/I programs that run under CICS. 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 v Rely on the link-edit automatic library-call mechanism to include the necessary modules. Warning messages may appear during the link-edit step, indicating DUPLICATE definitions for the DFHEI1 module. You may ignore these messages. For more information about link-edit requirements, see Using your own job streams on page 108.

Installing assembler language application programs

You can use the DFHEITAL procedure (see Figure 12 on page 99) to translate, assemble, and link-edit application programs written in assembler language.

CICS Transaction Server: CICS Application Programming Guide

|
Assembler-language source

Command-level language translator

Translator listing

Intermediate storage Assembler Assembly listing

CICS. SDFHMAC

Intermediate storage Linkage Editor CICS. SDFHLOAD Linkage Editor listing

CICS. SDFHLOAD

| | Figure 12. Installing assembler language programs using the DFHEITAL procedure | | | | | | | | |

Sample JCL to install assembler application programs

You can use the sample job control statements shown in Figure 13 on page 100 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 8 on page 97.

Chapter 9. Installing application programs

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//jobname JOB accounting info,name,MSGLEVEL=1 // EXEC PROC=DFHExTAL //TRN.SYSIN DD * *ASM XOPTS(translator options . . .) . assembler-language source statements . /* //LKED.SYSIN DD * NAME anyname(R) /* //

1 2

where anyname is your load module name

Figure 13. Sample job control statements to call the DFHwxTAL 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 93 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 92.) 2 For information about the translator options you can include on the XOPTS statement, see Defining translator options on page 74. .

Installing COBOL application programs

Figure 14 on page 101 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, the high-level language source and CICS.SDFHLOAD both input to the compiler, and a combined translator and compiler listing is produced.

100

CICS Transaction Server: CICS Application Programming Guide

|
High-level language source

CICS. SDFHLOAD

Command-level language translator

Translator listing

Intermediate storage DFHBMSCA DFHAID CICS. SDFHCOB or SDFHPL1 High-level language compiler Compiler listing

DFHEILIC DFHEILIP Intermediate storage DFHECI DFHEPI Linkage Editor Linkage Editor listing

CICS. SDFHLOAD

DFHPL1OI

SYS1.PLIBASE or COBLIB

CICS. SDFHLOAD

| | Figure 14. Installing COBOL and PL/I programs | | | | | | | | |

Sample JCL to install COBOL application programs

You can use the job control statements shown in Figure 15 on page 102 to process COBOL application programs. In the procedure name, wx depends on whether your programs are to be compiled by an LE-conforming compiler or otherwise, and whether it is a CICS application program or an EXCI batch program. For the names of the CICS-supplied COBOL procedures, see Table 8 on page 97.

Chapter 9. Installing application programs

101

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//jobname JOB accounting info,name,MSGLEVEL=1 // EXEC PROC=DFHwxTVL //TRN.SYSIN DD * CBL XOPTS(Translator options . . .) . COBOL source statements . /* //LKED.SYSIN DD * NAME anyname(R) /* //

1 2 3

where anyname is your load module name

Figure 15. Sample job control statements to call the DFHwxTVL procedures

Notes for installing COBOL programs 1 Translator options: Specify the following translator options according to the version of the COBOL compiler called in the compile step. OOCOBOL for the IBM COBOL for MVS & VM, and COBOL for OS/390 & VM compilers. This option is only needed if the object-oriented syntax (such as class-id and method-id), is used in the application program. The OOCOBOL option implies the COBOL3, ANSI85 and COBOL2 translator options. COBOL3 for one of the LE-conforming COBOL compilers. COBOL3 implies the ANSI85 and COBOL2 translator options. ANSI85 for the VS COBOL II compiler. This option specifies that the translator is to translate VS COBOL II programs that implement the ANSI85 standards. ANSI85 implies the COBOL2 option. COBOL2 for the VS COBOL II compiler. Compiler options: To compile a VS COBOL II application program, you need the compiler options: RENT, RES, 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. To compile a COBOL program with one of the LE-conforming compilers, you need the compiler options: RENT, NODYNAM, and LIB. To compile a COBOL program with a compiler that has an integrated translator, you also need to use the CICS compiler option. The PARM statement of the COB step in DFHwxTVL specifies values for the compiler options. For example,

102

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//COB //

EXEC PGM=IGYCRCTL,REGION=&REG, PARM='NODYNAM,LIB,OBJECT,RENT,RES,APOST,MAP,XREF'

It does 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=DFHwxTVL,PARM.COB='SIZE=512K,BUF=16K,.,.,.'

Ensure that the APOST|QUOTE option in effect for the VS COBOL II compiler matches that for the translator. There is no BATCH compiler option for VS COBOL II. For information about VS COBOL II compiler options, see Defining translator options on page 74. 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 DFHwxTCL procedure. 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 DFHwxTCL procedure. v The COBOL installation defaults macro, IGYCOPT. This is needed if you do not use a CBL statement; that is, have specified the translator option NOCBLCARD, and the compiler option ALOWCBL=NO. 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. The ALOWCBL=NO option can be overridden at compile time by the JCL PARM option or a TSO command. 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 The translator options on the XOPTS statement override similar options in the DFHwxTVL procedure. Any translator options you specify should include the type of COBOL translator option, COBOL2 or COBOL3. For information about the translator options you can include on the XOPTS statement, see Defining translator options on page 74. 4 You can ignore weak external references unresolved by the link-edit. The link-edit job step requires access to the libraries containing the environment-specific modules for CICS, the general VS COBOL II library subroutines, and the Language Environment link-edit modules, as appropriate. The
Chapter 9. Installing application programs

103

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

required libraries are included in the SYSLIB concatenation of procedures for VS COBOL II. 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 93 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 DFHEITVL procedure. (See Running applications in the link pack area on page 92.)

Installing PL/I application programs

Figure 14 on page 101 illustrates the flow of control in the cataloged procedures for PL/I programs. PL/I-CICS application programs must be link-edited in a different way than non-CICS PL/I applications. This is because the normal entry point, control section PLISTART, is not required on CICS systems. Instead, the module DFHPL1OI is provided by PL/I, which acts as the entry point to the program and must be link-edited with the application program. The CICS loader requires that DFHPL1OI be positioned at the head of the load module. For example, assuming the PL/I application is made up of members PLIAPP and EXTSUB, which reside in the library defined by ddname L1, and that the SYSLIB data set contains DFHPL1OI, then the following link-edit statements should be used:
INCLUDE SYSLIB (DFHPL1OI) Ensure that DFHPL1OI is at the head of the load module. REPLACE PLISTART Delete unwanted CSECTs from following INCLUDE. INCLUDE L1 (PLIAPP) Application procedure (1). REPLACE PLISTART Delete unwanted CSECTs from following INCLUDE. INCLUDE L1 (EXTSUB) Application procedure (2). INCLUDE DFHSHRE (PLISHRE) Optional. Use if shared library is to be used. NAME APROG (R) Optional. Defines name of load module.

For more information about preparing PL/I programs, see the OS PL/I Version 2 Programming Guide, SC26-4307-02.

Sample JCL to install PL/I application programs

You can use the job control statements shown in Figure 16 on page 105 to process PL/I application programs. In the procedure name, wx depends on whether your programs are to be compiled by an LE-conforming compiler or otherwise, and whether it is a CICS application program or an EXCI batch program. For the names of the CICS-supplied procedures, see Table 8 on page 97.

104

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//jobname JOB accounting info,name,MSGLEVEL=1 // EXEC PROC=DFHwxTPL 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 16. Sample job control statements to call the DFHwxTPL procedures

Notes for installing a PL/I program: These notes apply to the DFHEITPL procedure only. 1 In the DFHEITPL procedure, the link-edit step includes module DFHPL1OI. This module is generated during the installation of PL/I and is normally placed either in the CICSTS21.CICS.SDFHLOAD library, the SYS1.PLIBASE library, or a user library. Find out which library contains this module, and either copy the module to the CICSTS21.CICS.SDFHLOAD library or concatenate the appropriate library in LKED.SYSLIB. If you include the PL/I REPORT and COUNT execution time options, output goes to the CPLI transient data destination. There is an example of this transient data queue coded in the sample destination control table in the CICSTS21.CICS.SDFHSAMP library. 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: 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 CPLD transient data destination. The CICS supplied resource definition group, in the CSD, DFHDCTG, contains an entry for CPLD. 5 link-edit considerations:

Chapter 9. Installing application programs

105

| | | | | | | | | | | | | | | | | | | | | | | |

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 93 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 DFHEITPL procedure. (See Running applications in the link pack area on page 92 for more information.) To use the PL/I shared library facility, generate the module PLISHRE (see CICS Transaction Server for z/OS Installation Guide) before you compile and link-edit your application programs. When you have re-link-edited the PLISHRE module into the CICSTS21.CICS.SDFHLOAD library, put the INCLUDE SYSLIB(PLISHRE) control statement immediately after the INCLUDE SYSLIB(DFHPL1OI) statement in the DFHEILIP member in the CICSTS21.CICS.SDFHPL1 library. Also, code a LKED.SYSLIB DD statement to concatenate the library that contains the PLISHRE module in front of the SYS1.PLIBASE library. For example:
//LKED.SYSLIB // DD DSN=CICSTS21.CICS.SDFHLOAD,DISP=SHR DD DSN=SYS1.PLIBASE,DISP=SHR

Installing C application programs

Figure 17 on page 107 illustrates the flow of control in the cataloged procedures for C command-level programs. Before you can install any C programs, have installed the C library and compiler and generated CICS support for C. (See CICS Transaction Server for z/OS Installation Guide.)

106

CICS Transaction Server: CICS Application Programming Guide

|
High-level language source

CICS. SDFHLOAD

Command-level language translator

Translator listing

Intermediate storage High-level language compiler Compiler listing

EDC.V1R2M0 SEDCHDRS SEDCMSGS (EDCMSGE)

DFHBMSCA DFHAID

Intermediate storage Pre-linkage editor Pre-linkage editor listing

EDC.V1R2M0 SEDCLINK SEDCCOMP SEDCMSGS (EDCMSGE) EDC.V2R2M1 SIBMLINK

Intermediate storage

DFHEILID DFHELII Linkage Editor CICS. SDFHLOAD Linkage Editor listing

EDC.V1R2M0 SEDCBASE

EDC.V2R2M1 SIBMBASE

CICS. SDFHLOAD

| | Figure 17. Installing C programs using the DFHxyTzL procedure | | | | | |

Sample JCL to install C application programs

You can use the job control statements shown in Figure 18 on page 108 to process C application programs. In the procedure name, w and x depend on whether your programs are to be compiled by an LE-conforming compiler or otherwise, and
Chapter 9. Installing application programs

107

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

whether it is a CICS application program or an EXCI batch program. For the names of the CICS-supplied procedures, see Table 8 on page 97.
//jobname JOB accounting info,name,MSGLEVEL=1 // EXEC PROC=DFHwxTDL //TRN.SYSIN DD * #pragma XOPTS(Translator options . . .) . C source statements . /* //LKED.SYSIN DD * NAME anyname(R) /* // 1 2 3

where anyname is your load module name

Figure 18. Sample JCL to call the DFHwxTDL 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 by a C statement at the start of the source statements. If you use a C statement, you need a parameter override of BATCH on the EXEC PROC=DFHEITyL statement. You can compile your C/370 applications under Version 1 Release 2 of the C/370 compiler and run them under Version 1 Release 2 of the C/370 library. 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 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 93 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 DFHEITyL procedure. (See Running applications in the link pack area on page 92 for more information.) C language programs must be link-edited with AMODE(31), so the DFHwxTDL procedures specify AMODE(31) by default.

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 CICSTS21.CICS.SDFHPROC library.

108

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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

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 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 C DFHECI COBOL DFHPL1OI PL/I DFHELII LE-conforming compilers Note: Assembler and PL/I programs require additional modules, DFHEAI0 and DFHEPI respectively. In each case, inclusion of the interface module named above generates a reference to the additional module, and it is automatically included. 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 DFHEITVL procedure concatenates the library member DFHEILIC, which contains the following INCLUDE statement:
INCLUDE SYSLIB(DFHECI)

Chapter 9. Installing application programs

109

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

3. Place the load module output from the link-edit (defined by the SYSLMOD DD statement) in CICSTS21.CICS.SDFHLOAD, or a user-defined application program library. Figure 19 shows sample JCL and an inline procedure, based on the CICS-supplied procedure DFHEITVL, that can be used to install VS COBOL II application programs. The procedure does not include the COPYLINK step and concatenation of the library member DFHEILIC that contains the INCLUDE statement for the required interface module (as included in the DFHEITVL procedure). Instead, the JCL provides the following INCLUDE statement:
INCLUDE SYSLIB(DFHECI)

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.
//COB2APPL JOB accounting info,name,MSGCLASS=A,MSGLEVEL=(1,1), // CLASS=A //* //********************************************************************* //* THIS JOB CAN BE USED TO INSTALL A VS COBOL II PROGRAM. //* //* THE JOB ILLUSTRATES THE USE OF: //* //* 1) AN INLINE PROCEDURE BASED ON THE CICS=SUPPLIED PROCEDURE, DFHEITVL //* //* 2) INCLUDE AND ORDER STATEMENTS FOR INTERFACE MODULE DFHECI //* //********************************************************************* //* //MYEITVL PROC SUFFIX=1$, // INDEX='CICSTS21.CICS', // INDEX2='CICSTS21.CICS', // OUTC=A, // REG=5M, // LNKPARM='XREF,RENT,REFR', // WORK=SYSDA //* //* THIS PROCEDURE CONTAINS 3 STEPS //* 1. EXEC THE COBOL TRANSLATOR (USING SUFFIX 1$) //* 2. EXEC THE VS COBOL II COMPILER //* 3. LINKEDIT THE OUTPUT TO SDFHLOAD LIBRARY //*

Figure 19. Sample user-defined JCL to install a VS COBOL II program (Part 1 of 2)

110

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//TRN EXEC PGM=DFHECP&SUFFIX, // PARM='COBOL2', // 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=PP.COB2.COB2COMP,DISP=SHR //SYSLIB DD DSN=&INDEX..SDFHCOB,DISP=SHR // DD DSN=&INDEX..SDFHSAMP,DISP=SHR //* DD DSN=&INDEX2..SAMPLIB,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)) //SYSUT7 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=SYS2.COB2.COB2CICS,DISP=SHR // DD DSN=SYS2.COB2.COB2LIB,DISP=SHR //* SYSLMOD DD DSN=&INDEX2..LOADLIB,DISP=SHR //SYSLMOD DD DSN=&INDEX2..SDFHLOAD,DISP=SHR //SYSUT1 DD UNIT=&WORK,DCB=BLKSIZE=1024, // SPACE=(1024,(200,20)) //SYSPRINT DD SYSOUT=&OUTC //SYSLIN DD DSN=&&LOADSET,DISP=(OLD,DELETE) // DD DDNAME=SYSIN // PEND //* //COB2TEST EXEC MYEITVL, // INDEX='CICSTS21.CICS', QUALIFIER FOR CICS LIBRARIES // INDEX2='user.qualif', QUALIFIER FOR USER LIBRARIES // OUTC='*', // REG='2048K', SYSOUT CLASS // WORK='SYSDA', UNIT FOR TEMPORARY DATA SETS // LNKPARM='XREF,LIST,RENT' //TRN.SYSIN DD * ... VS COBOL II source statements ... /* //LKED.SYSIN DD * INCLUDE SYSLIB(DFHECI) NAME name(R) /* //

Figure 19. Sample user-defined JCL to install a VS COBOL II program (Part 2 of 2)

Chapter 9. Installing application programs

111

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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. 4. Place the load module output from the link-edit (defined by the SYSLMOD DD statement) in CICSTS21.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 CICSTS21.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.

112

CICS Transaction Server: 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. 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 defining map set

Ty p e = DSECT

Assembler

Copy library

Ty p e = MAP

Assembler listing

Assembler

Assembler listing

Object module library

Link Editor

Link edit listing

CICS load library

| | | | |

Figure 20. 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, 2001

113

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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 30. Basic mapping support on page 393. 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. CICS also provides the DFHASMVS procedure (installed in the CICSTS21.CICS.SDFHPROC library) that you can use to assemble and link-edit map sets. Note: The DFHASMVS procedure refers to the MVS library SYS1.MODGEN. If you have not yet restructured MVS (moving members from SYS1.AMODGEN to SYS1.MODGEN), change the SYS1.MODGEN reference to SYS1.AMODGEN in the DFHASMVS procedure, until you have restructured MVS. When you have restructured MVS, you must return the SYS1.AMODGEN reference to SYS1.MODGEN. This chapter includes: v Installing map sets v Installing partition sets on page 121 v Defining programs, map sets, and partition sets to CICS on page 123

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.

114

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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.

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=DFHASMVS statement. The TYPE operand of the DFHMSD macro can only define whether a physical or symbolic description map set is required. 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. For the possible combinations of operands to generate the various types of map set, see Table 9.
Table 9. SYSPARM and DFHMSD operand combinations for map assembly Type of map set Aligned symbolic description map set (DSECT) Aligned physical map set Unaligned symbolic description map set (DSECT) Unaligned physical map set SYSPARM operand of EXEC DFHASMVS statement A A ADSECT A AMAP Not specified Not specified DSECT Not specified MAP TYPE operand of DFHMSD macro Not specified DSECT Any (takes SYSPARM) MAP Any (takes SYSPARM) Not specified DSECT Any (takes SYSPARM) MAP Any (takes SYSPARM)

Chapter 10. Installing map sets and partition sets

115

| | | | | | | | | | | | | | |

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 must reassemble both the physical and symbolic description map sets, and you must reassemble or recompile the application program.

Installing physical map sets

Figure 21 shows the procedure for installing physical map sets.

Macro statements defining the map set

Assembler CICS. SDFHMAC

Assembly listing

Linkage Editor input (object)

Linkage Editor

Linkage Editor listing

CICS. SDFHLOAD

| | | | | |

Figure 21. Installing physical map sets

Figure 22 on page 117 gives an example job stream for the assembly and link-editing of physical map sets.

116

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//PREP //STEP1 //SYSPUNCH // //SYSIN . . . . . .

JOB 'accounting information',CLASS=A,MSGLEVEL=1 EXEC PROC=DFHASMVS,PARM.ASSEM='SYSPARM(MAP)' DD DSN=&&TEMP,DCB=(RECFM=FB,BLKSIZE=2960), SPACE=(2960,(10,10)),UNIT=SYSDA,DISP=(NEW,PASS) DD *

Macro statements defining the map set

/* //STEP2 //SYSLIN // /* //

EXEC DD DD MODE NAME

PROC=DFHLNKVS,PARM='LIST,LET,XREF' DSN=&&TEMP,DISP=(OLD,DELETE) * RMODE(ANY|24) mapsetname(R)

2 3 4

Figure 22. Assembling and link-editing a physical map set

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

Chapter 10. Installing map sets and partition sets

117

| | | | | |

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 23 shows the preparation of symbolic description map sets for BMS.

Macro statements defining the symbolic map

CICS. SDFHMAC

Assembler

Assembly listing

SYSPUNCH

| | | | | | | | | | | | | | | | | | | | | | | | | |

Figure 23. Installing symbolic description map sets using the DFHASMVS procedure

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 24 on page 119 to obtain a listing of a symbolic description map set. It applies to all the programming languages supported by CICS.

118

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

//DSECT //ASM //SYSPUNCH //SYSIN . . . . . . /* //

JOB EXEC DD DD

'accounting information',CLASS=A,MSGLEVEL=1 PROC=DFHASMVS,PARM.ASSEM='SYSPARM(DSECT)' SYSOUT=A *

Macro statements defining the map set

Figure 24. 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 24 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 //SYSPUNCH DD //SYSPUNCH DD DSN=USER.MAPLIB.ASM(map set name),DISP=OLD DSN=USER.MAPLIB.COB(map set name),DISP=OLD DSN=USER.MAPLIB.PLI(map set name),DISP=OLD

Installing physical and symbolic description maps together

Figure 25 on page 120 shows the DFHMAPS procedure for installing physical and symbolic description maps together. The DFHMAPS procedure consists of the following four steps, shown in Figure 25: 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 CICSTS21.CICS.SDFHMAC library.

Chapter 10. Installing map sets and partition sets

119

1
Macro statements defining the map set

2
CICS. SDFHMAC Assembler

Assembly listing

Linkage Editor input (object)

3
CICS. SDFHLOAD Linkage Editor Linkage Editor listing

4
Macro statements defining the map set Assembler CICS. SDFHMAC

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Figure 25. Installing a physical map set and a symbolic description map set together

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 CICSTS21.CICS.SDFHHTML.

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 26.
//PREPARE JOB 'accounting information',CLASS=A,MSGLEVEL=1 //ASSEM EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24 //SYSUT1 DD * . . . . . . /* // Macro statements defining the map set (see note)

Figure 26. 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.

120

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

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 26 on page 120, 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 CICSTS21.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:
//PREPARE //ASSEM //SYSUT1 ... . . . 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, TIOAPFX=YES,TERM=3270-2,MAPATTS=(COLOR,HILIGHT), DSATTS=(COLOR,HILIGHT) SPACE DFH0STM DFHMDI SIZE=(24,80) . . . . . SPACE DFHMSD TYPE=FINAL END. . . /* // JOB 'accounting information',CLASS=A,MSGLEVEL=1 EXEC PROC=DFHMAPS,MAPNAME=mapsetname,RMODE=ANY|24 DD *

C C

| | Figure 27. 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 21 on page 116). There is no concept of a symbolic description partition set.
Chapter 10. Installing map sets and partition sets

121

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

The job stream in Figure 28 is an example of the assembly and link-edit of partition sets.
//PREP //STEP1 //SYSPUNCH // //SYSIN . . . . . . JOB 'accounting information',CLASS=A,MSGLEVEL=1 EXEC PROC=DFHASMVS DD DSN=&&TEMP,DCB=(RECFM=FB,BLKSIZE=2960), SPACE=(2960,(10,10)),UNIT=SYSDA,DISP=(NEW,PASS) DD *

Macro statements defining the partition set

/* //STEP2 //SYSLIN // /* //

EXEC DD DD MODE NAME

PROC=DFHLNKVS,PARM='LIST,LET,XREF' DSN=&&TEMP,DISP=(OLD,DELETE) * RMODE(ANY|24) partitionsetname(R)

1 2 3

Figure 28. Assembling and link-editing a partition set

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 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 Reference manual. 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.

122

CICS Transaction Server: CICS Application Programming 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.

Chapter 10. Installing map sets and partition sets

123

124

CICS Transaction Server: CICS Application Programming Guide

Part 3. Application design

Chapter 11. Application design . . . . . . . Pseudoconversational and conversational design . Terminal interruptibility . . . . . . . . . . How tasks are started . . . . . . . . . . . Which transaction? . . . . . . . . . . . . Separating business and presentation logic . . . Multithreading . . . . . . . . . . . . . . Quasi-reentrant application programs . . . . Threadsafe programs . . . . . . . . . . Non-reentrant programs . . . . . . . . . Storing data within a transaction . . . . . . . Transaction work area (TWA) . . . . . . . User storage . . . . . . . . . . . . . COMMAREA in LINK and XCTL commands . . Program storage . . . . . . . . . . . . Temporary storage . . . . . . . . . . . Intrapartition transient data . . . . . . . . GETMAIN SHARED command . . . . . . Your own data sets . . . . . . . . . . . Lengths of areas passed to CICS commands . . LENGTH options. . . . . . . . . . . . Journal records . . . . . . . . . . . . Data set definitions . . . . . . . . . . . Recommendation . . . . . . . . . . . Minimizing errors. . . . . . . . . . . . . Protecting CICS from application errors . . . Testing applications . . . . . . . . . . . Non-terminal transaction security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 129 131 131 132 135 136 136 137 138 139 139 139 140 141 141 142 143 143 143 144 144 144 144 144 145 145 146 147 147 148 149 149 150 150 151 152 153 153 154 154 154 154 156 156 156 156 157 157 157 157 158

Chapter 12. Design for performance . . . . . . . . . . Program size . . . . . . . . . . . . . . . . . . . Virtual storage. . . . . . . . . . . . . . . . . . . Reducing paging effects . . . . . . . . . . . . . . Locality of reference . . . . . . . . . . . . . . Working set . . . . . . . . . . . . . . . . . Reference set . . . . . . . . . . . . . . . . . Exclusive control of resources . . . . . . . . . . . . . Operational control . . . . . . . . . . . . . . . . . Operating system waits . . . . . . . . . . . . . . . The NOSUSPEND option . . . . . . . . . . . . . . Efficient data operations . . . . . . . . . . . . . . . Efficient database operations . . . . . . . . . . . . Efficient data set operations. . . . . . . . . . . . . VSAM data sets . . . . . . . . . . . . . . . . BDAM data sets . . . . . . . . . . . . . . . . Efficient browsing (in non-RLS mode) . . . . . . . . . Efficient logging . . . . . . . . . . . . . . . . . Efficient sequential data set access . . . . . . . . . . Efficient terminal operations. . . . . . . . . . . . . . Length of the data stream sent to the terminal . . . . . . Basic mapping support considerations . . . . . . . . . Avoid turning on modified data tags (MDTs) unnecessarily Use FRSET to reduce inbound traffic . . . . . . . .
Copyright IBM Corp. 1989, 2001

125

Do not send blank fields to the screen . . . . . . . . . . Address CICS areas correctly . . . . . . . . . . . . . Use the MAPONLY option when possible. . . . . . . . . Send only changed fields to an existing screen . . . . . . Design data entry operations to reduce line traffic . . . . . Compress data sent to the screen . . . . . . . . . . . Use nulls instead of blanks . . . . . . . . . . . . . . Use methods that avoid the need for nulls or blanks. . . . . Page-building and routing operations . . . . . . . . . . . Sending multipage output . . . . . . . . . . . . . . Sending messages to destinations other than the input terminal Sending pages built from multiple maps . . . . . . . . . Using the BMS page-copy facility. . . . . . . . . . . . Requests for printed output . . . . . . . . . . . . . . . Additional terminal control considerations . . . . . . . . . . Use only one physical SEND command per screen . . . . . On BTAM, avoid the WAIT option on a SEND command . . . Use the CONVERSE command . . . . . . . . . . . . Limit the use of message integrity options . . . . . . . . Avoid using the DEFRESP option on SEND commands . . . Avoid using unnecessary transactions . . . . . . . . . . Send unformatted data without maps . . . . . . . . . . Chapter 13. Sharing data across transactions Using the common work area (CWA) . . . . Protecting the CWA. . . . . . . . . . Using the TCTTE user area (TCTUA) . . . . Using the COMMAREA in RETURN commands Using the display screen to share data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

158 159 159 159 159 160 160 160 160 160 161 162 162 162 163 163 163 163 163 163 163 163 165 165 165 168 169 169 171 172 172 172 172 173 173 173 174 174 174 175 176 177 177 178 178 179 179 179 180 181 182 184 185 186

Chapter 14. Affinity . . . . . . . . . . . . . . . . . . . . . Types of affinity . . . . . . . . . . . . . . . . . . . . . . . Inter-transaction affinity . . . . . . . . . . . . . . . . . . . Transaction-system affinity . . . . . . . . . . . . . . . . . . Using INQUIRE and SET commands and global user exits . . . . . Programming techniques and affinity . . . . . . . . . . . . . . . Safe techniques . . . . . . . . . . . . . . . . . . . . . . Unsafe techniques . . . . . . . . . . . . . . . . . . . . . Suspect techniques . . . . . . . . . . . . . . . . . . . . . Recommendations . . . . . . . . . . . . . . . . . . . . . Safe programming to avoid affinity . . . . . . . . . . . . . . . . The COMMAREA . . . . . . . . . . . . . . . . . . . . . The TCTUA . . . . . . . . . . . . . . . . . . . . . . . Using the TCTUA in an unsafe way . . . . . . . . . . . . . . Using ENQ and DEQ commands with ENQMODEL resource definitions Overview of sysplex enqueue and dequeue . . . . . . . . . . . Benefits . . . . . . . . . . . . . . . . . . . . . . . . BTS containers . . . . . . . . . . . . . . . . . . . . . . Unsafe programming for affinity . . . . . . . . . . . . . . . . . Using the common work area . . . . . . . . . . . . . . . . . Using GETMAIN SHARED storage . . . . . . . . . . . . . . . Using the LOAD PROGRAM HOLD command . . . . . . . . . . . Sharing task-lifetime storage . . . . . . . . . . . . . . . . . Using the WAIT EVENT command . . . . . . . . . . . . . . . Using ENQ and DEQ commands without ENQMODEL resource definitions Suspect programming for affinity . . . . . . . . . . . . . . . . .

126

CICS Transaction Server: CICS Application Programming Guide

Using temporary storage . . . . . . . . . . . . . Naming conventions for remote queues . . . . . . Exception conditions for globally accessible queues . . Using transient data . . . . . . . . . . . . . . Exception conditions for globally accessible queues . . Using the RETRIEVE WAIT and START commands . . . Using the START and CANCEL REQID commands . . . Using the DELAY and CANCEL REQID commands . . . Using the POST and CANCEL REQID commands . . . Detecting inter-transaction affinities . . . . . . . . . . Inter-transaction affinities caused by application generators Duration and scope of inter-transaction affinities . . . . . Affinity transaction groups . . . . . . . . . . . . Relations and lifetimes . . . . . . . . . . . . . The global relation . . . . . . . . . . . . . . The LUname (terminal) relation . . . . . . . . . The userid relation . . . . . . . . . . . . . . The BAPPL relation. . . . . . . . . . . . . . Chapter 15. Recovery design . Journaling . . . . . . . . . Journal records . . . . . . Journal output synchronization. Syncpointing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

186 187 188 188 189 189 191 193 194 196 196 197 197 197 197 199 200 201 205 205 205 205 207 209 209 210 210 210 211 211 211 212 213 214 215 215 216 217 218 218 221 222 223 224 225 225 225 225 225 225 226

Chapter 16. Dealing with exception conditions . . Default CICS exception handling . . . . . . . . . Handling exception conditions by in-line code . . . . How to use the RESP and RESP2 options . . . . Use of RESP and DFHRESP in COBOL and PL/I. Use of RESP and DFHRESP in C and C++ . . . Use of DFHRESP in assembler . . . . . . . An example of exception handling in C . . . . . An example of exception handling in COBOL . . . Modifying default CICS exception handling . . . . . Using the HANDLE CONDITION command . . . . . RESP and NOHANDLE options . . . . . . . . How CICS keeps track of what to do . . . . . . Using the HANDLE CONDITION ERROR command. . Using the IGNORE CONDITION command . . . . . Using the HANDLE ABEND command . . . . . . . Using PUSH HANDLE and POP HANDLE commands . Chapter 17. Abnormal termination recovery . Creating a program-level abend exit . . . . Retrying operations . . . . . . . . . . . Trace . . . . . . . . . . . . . . . . Trace entry points . . . . . . . . . . System trace entry points . . . . . . User trace entry points . . . . . . . Exception trace entry points. . . . . . User exception trace entry points. . . . Monitoring . . . . . . . . . . . . . . Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 18. The QUERY SECURITY command . . . . . . . . . . . . 229

Part 3. Application design

127

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

. . level . . . . . .

. . . . .

229 229 230 230 230

128

CICS Transaction Server: 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 147. v Pseudoconversational and conversational design v How tasks are started on page 131 v Which transaction? on page 132 v Separating business and presentation logic on page 135 v Multithreading on page 136 v Storing data within a transaction on page 139 v Lengths of areas passed to CICS commands on page 143 v Minimizing errors on page 144 v Non-terminal transaction security on page 146

Pseudoconversational and conversational design

In a conversational transaction, the length of time spent in processing each of a users 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
Copyright IBM Corp. 1989, 2001

129

the other facilities that CICS provides for this purpose. (See Chapter 13. Sharing data across transactions on page 165 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 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 disadvantagesboth 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 users 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 users 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,

130

CICS Transaction Server: CICS Application Programming Guide

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.

Terminal interruptibility
When a conversational task is running, CICS allows nothing else to send messages to that tasks 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 CICSthat is, tasks are initiatedin 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 305), and the SEND PAGE command (in The SEND PAGE command on page 448) all do this. v CICS creates a task to process a transient data queue (see Automatic transaction initiation (ATI) on page 535). v CICS creates a task to deliver a message sent by a BMS ROUTE request (see Chapter 38. Message routing on page 467). 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.

Chapter 11. Application design

131

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 350.1 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 29 on page 133, a diagram of this logic.

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 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 321). BMS routing, described in Chapter 38. Message routing on page 467, is another form of indirect access to other terminals by queues.

132

CICS Transaction Server: CICS Application Programming Guide

0
Terminal defined as to be queried? No Yes Has query been run to this terminal? Yes Yes Initiate printing No Initiate CQRY

1
3270 print request key? No Terminal supported by paging? No Yes Paging command entered? Yes Initiate CSPG

3
Transaction specified by TCT TRANSID? No Yes

No Initiate specified transaction

4
Transaction specified by TRANSID of RETURN? No Yes Initiate specified transaction

5
Attach FMH present? Yes

Initiate transaction specified in attach FMH

6
Yes 3270? PA, PF, LPA, or OPID? Yes TASKREQ= specified? Yes

Initiate transaction specified by term input AID

7
Terminal input begins with tranid? Yes

Initiate transaction specified by terminal input

Send "invalid tranid" message to terminal

Global user exit XZCATT in module DFHZATT is invoked at these points.

Figure 29. Determining which transaction to execute

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

Chapter 11. Application design

133

terminal to transmit an encoded description of some of its hardware characteristicsextended 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 355 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. 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 393, 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. 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.) If the previous task at the terminal specified the TRANSID option of the RETURN command that ended it, the transaction named is executed. 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. If the terminal is a 3270, and the attention identifier is defined as a transaction, that transaction is executed. Attention keys on page 338 explains attention identifiers. You define one as a transaction identifier with the TASKREQ attribute of the corresponding TRANSACTION definition. 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. 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.

4. 5.

134

CICS Transaction Server: CICS Application Programming Guide

| | | | | | | | | | | |

Separating business and presentation logic

Figure 30 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 users 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 transactions presentation logic, while the EXEC CICS READ UPDATE and EXEC CICS REWRITE commands are part of the business logic.
.. EXEC .. EXEC .. EXEC .. EXEC ..

CICS RECEIVE MAP CICS READ UPDATE CICS REWRITE CICS SEND MAP

Figure 30. 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 31 and Figure 32illustrate this approach to application design.
.. EXEC CICS RECEIVE MAP .. EXEC CICS LINK.. .. EXEC CICS SEND MAP ..

Figure 31. Presentation logic .. EXEC .. EXEC .. EXEC .. EXEC CICS ADDRESS COMMAREA CICS READ UPDATE CICS REWRITE CICS RETURN..

Figure 32. 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.
Chapter 11. Application design

135

Multithreading
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 DFHEPTR 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 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.

136

CICS Transaction Server: CICS Application Programming Guide

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 resourcesfor 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 43. Task control on page 499 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.

Threadsafe programs
In the CICS open transaction environment, threadsafe application programs and open task-related user exits, global user exit programs, and user-replaceable modules cannot rely on quasi-reentrancy, because they can run concurrently on an open TCB. Furthermore, even quasi-reentrant programs are at risk if they access resources that can also be accessed by a user task running concurrently under an open TCB. This means that the techniques used by user programs to access shared resources must take into account the possibility of simultaneous access by other programs. 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.) For most resources, such as files, transient data queues, temporary storage queues, and DB2 tables, CICS processing automatically ensures access in a threadsafe manner. However, for any other resources, such as shared storage, which are accessed directly by user programs, it is the responsibility of the user program to ensure threadsafe processing. Typical examples of shared storage are the CICS CWA, global user exit global work areas, and storage acquired by EXEC CICS GETMAIN SHARED commands. 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 considerd 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:
Chapter 11. Application design

137

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). v Perform accesses to shared resources only in a program that is defined as quasirent, by linking to the quasirent 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 136 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 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.

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

138

CICS Transaction Server: CICS Application Programming Guide

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) 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 sourcethe 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 45. Storage control on page 517 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

Chapter 11. Application design

139

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 45. Storage control on page 517 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. 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 169. 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 44. Program control on page 503 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 45. Storage control on page 517 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.

140

CICS Transaction Server: CICS Application Programming Guide

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.

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 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
Chapter 11. Application design

141

v v

accessed frequently. Auxiliary temporary storage is specifically designed for relatively large amounts of data that have a relatively long lifetime or are 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. You can make queues in auxiliary storage recoverable, but not queues in main storage: 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. 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. 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 156 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:

142

CICS Transaction Server: CICS Application Programming Guide

v Transient data does not have the same dynamic characteristics as temporary storage. Unlike temporary storage queues, transient data queues cannot be 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.

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.

Chapter 11. Application design

143

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 of your CICS commands 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 205.)

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.

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.

144

CICS Transaction Server: CICS Application Programming Guide

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 systemuse 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 48. Testing applications on page 543 for more information about testing applications. v Use the CEDF transaction for initial testing. See Chapter 49. Execution diagnostic facility (EDF) on page 547 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. 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.
Chapter 11. Application design

145

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.

146

CICS Transaction Server: 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 148 v Exclusive control of resources on page 151 v Operational control on page 152 v Operating system waits on page 153 v The NOSUSPEND option on page 153 v Efficient data operations on page 154 v Efficient terminal operations on page 157 Other aspects of application design are addressed in Chapter 11. Application design on page 129 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/370, 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.

147

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, JCA, and LLAif used) 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 tasks 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 13 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

148

CICS Transaction Server: 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

149

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 installations 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/370, 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 PL/I, and ORG or equivalents in assembler language. In particular, if you have a

150

CICS Transaction Server: CICS Application Programming Guide

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. v Using the COBOL RES option. COBOL subroutines coded with this option are not link-edited into the calling program, but instead are loaded on their first use. They can then be shared by any other COBOL program requiring them. v Using the PL/I shared library (PLISHRE) for such subroutines. 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

Chapter 12. Design for performance

151

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. 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 254 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 tasks 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

152

CICS Transaction Server: CICS Application Programming Guide

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 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 156.) 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 3. Programming in COBOL on page 9, Chapter 4. Programming in C and C++ on page 31, and Chapter 5. Programming in PL/I on page 39. 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 program2. 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

When the condition occurs, the following tests are made:

2. HANDLE CONDITION and IGNORE CONDITION commands are not supported for C and C++ programs. Chapter 12. Design for performance

153

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.

VSAM data sets

To minimize contention delays using VSAM data sets:

154

CICS Transaction Server: CICS Application Programming Guide

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 237, 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. VSAM serializes by enqueuing on the control interval (CI), so that no transaction can update a record in the same control interval as another record being updated. The VSAM hold for exclusive use ends when the request is complete in VSAM terms. For example, in an update operation, exclusive use that starts with the READ command with the UPDATE option and ends when VSAM has completed the REWRITE command. For nonrecoverable data sets, the CICS exclusive use ends at the same time. For recoverable data sets, however, it 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. Table 10 shows which requests require exclusive use and when that reservation terminates. This table applies only if you are not using record-level sharing.
Table 10. Requests that require exclusive use and when reservation terminates Command READ.. UPDATE WRITE.. MASSINSERT WRITE DELETE.. RIDFLD Released by VSAM at REWRITE/DELETE/UNLOCK UNLOCK Completion of WRITE Completion of DELETE

v Hold position in a VSAM data set for as short a time as possible. Table 11 shows which commands hold position and when the hold is released.
Table 11. Commands that hold position and when hold is released Command READ.. UPDATE WRITE.. MASSINSERT STARTBR Released by VSAM at REWRITE/DELETE/UNLOCK UNLOCK 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. 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.

Chapter 12. Design for performance

155

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

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

156

CICS Transaction Server: CICS Application Programming Guide

storage on page 141 and in Intrapartition transient data on page 142) 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.

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).
Chapter 12. Design for performance

157

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.

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.

158

CICS Transaction Server: CICS Application Programming Guide

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 418 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. 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
Chapter 12. Design for performance

159

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

160

CICS Transaction Server: CICS Application Programming Guide

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 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
Chapter 12. Design for performance

161

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

162

CICS Transaction Server: CICS Application Programming Guide

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.

On BTAM, avoid the WAIT option on a SEND command

Note: CICS does not support BTAM. You can run BTAM transactions on CICS if you initiate them from a system that supports BTAM transactions, and use transaction routing to CICS Transaction Server for z/OS, Version 2 Release 1. If your program is pseudoconversational, it has only one SEND command, by definition. (See Pseudoconversational and conversational design on page 129.) Unless you require notification to this program of an error on the SEND command, omit the WAIT option. This allows CICS task control to reclaim the control blocks and user storage for your program long before it would otherwise be able to do so. Indeed, use of the WAIT option reduces substantially the savings effected by pseudoconversational programming.

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.

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).
Chapter 12. Design for performance

163

164

CICS Transaction Server: 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 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 14. Affinity on page 171 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 168 v Using the COMMAREA in RETURN commands on page 169 v Using the display screen to share data on page 169

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

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.
Copyright IBM Corp. 1989, 2001

165

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 45. Storage control on page 517. Figure 33 illustrates a particular use of the CWA where the CWA itself is protected from user-key application programs by CWAKEY=CICS. 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 defined with EXECKEY(USER), thereby ensuring the CWA is protected from overwriting by application programs. In Figure 33, one of the data areas is obtained from CICS-key storage, while the other is obtained from user-key storage.
CWA (defined with CWAKEY=CICS) appl1_id ptr_ref1 appl2_id 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 33. 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.

Application Storage Area (for appl1) (obtained from CICS-key storage)

In the sample code shown in Figure 34 on page 167, the program list table post-initialization (PLTPI) program is setting up the application data areas, with pointers to the data stored in the CWA.

166

CICS Transaction Server: CICS Application Programming Guide

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 34. Sample code for loading the CWA (Part 1 of 2). This example illustrates how to create global data for use by application programs, with addresses of the data stored in the CWAfor 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).

Chapter 13. Sharing data across transactions

167

* 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 34. Sample code for loading the CWA (Part 2 of 2). This example illustrates how to create global data for use by application programs, with addresses of the data stored in the CWAfor 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).

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.

168

CICS Transaction Server: CICS Application Programming Guide

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

Chapter 13. Sharing data across transactions

169

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.

170

CICS Transaction Server: CICS Application Programming Guide

Chapter 14. 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 172 v Programming techniques and affinity on page 173 v Safe programming to avoid affinity on page 174 v Unsafe programming for affinity on page 179
Copyright IBM Corp. 1989, 2001

171

v Suspect programming for affinity on page 186 v Detecting inter-transaction affinities on page 196 v Duration and scope of inter-transaction affinities on page 197

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 (see the CICS Resource Definition Guide for a description of ENQMODELs) to give sysplex-wide scope to the ENQs.

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

172

CICS Transaction Server: 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 (see Using ENQ and DEQ commands with ENQMODEL resource definitions on page 177 and the CICS Resource Definition Guide for a description of ENQMODELs) to give sysplex-wide scope to the ENQs. 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 174.

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 14. Affinity

173

See Sharing task-lifetime storage on page 182 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 (see Using ENQ and DEQ commands with ENQMODEL resource definitions on page 177 and the CICS Resource Definition Guide for a description of ENQMODELs) to give sysplex-wide scope to the ENQs. For more information about unsafe programming techniques, see Unsafe programming for affinity on page 179.

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

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

174

CICS Transaction Server: 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 35 on page 176. 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 14. Affinity

175

TOR1 (1) Using DTR, routes TRN1 to AOR1. (2) Using DTR, routes TRN2 to AOR2 AOR1 Executes TRN1 TRN1 terminates with EXEC CICS RETURN COMMAREA(DATA) TRANSID(TRN2) AOR2 Executes TRN2 TRN2 has access to the COMMAREA data passed by TRN1

Figure 35. 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 35, 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 36 on page 177. 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.

176

CICS Transaction Server: 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 Executes TRN1 which: (1) Gets TCTUA address (2) Stores data in TCTUA for next transaction (3) Ends with EXEC CICS RETURN TRANSID(TRN2)

AOR2 Executes TRN2 which: (1) Gets address of the TCTUA (2) Accesses the data stored by TRN1.

Figure 36. 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 tasks 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 tasks 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.

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
Chapter 14. Affinity

177

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. Changes have been made to the CICS Affinity Utility to make it easier to create affinity groups for enqueues by address separately from enqueues by name. Existing applications can use sysplex enqueues simply by defining appropriate ENQMODELs, without any change to the application programs.

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.

178

CICS Transaction Server: CICS Application Programming Guide

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 containers 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. 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 37 on page 180.

Chapter 14. Affinity

179

TOR DTR program If the dynamic routing program routes TRN2 to AOR3 as shown, TRN2 will fail to access the data stored for it by TRN1.

AOR1 CWA

AOR2 CWA

AOR3 CWA

TRN1 writes data to CWA intended for TRN2

TRN2 fails to read the TRN1 data from the CWA

CWA
Figure 37. 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 38 on page 181 illustrates the use of shared storage.

180

CICS Transaction Server: CICS Application Programming Guide

TOR DTR program

In this example, the TOR must route TRN2 to AOR1, because it needs access to shared storage obtained by TRN1 in that region.

AOR1 Executes TRN1 which: (1) GETMAINs some SHARED storage (2) Stores data in shared storage (3) WRITEs address to a TS queue Terminates (leaving shared storage still allocated) Executes TRN2 which: (1) READs address from TS queue (2) Reads data from shared storage (3) FREEMAINs the shared storage Terminates

AOR2

Figure 38. 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 38 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 programs 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 programs 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 38 and Figure 39 on page 182), and the same rule applies: to preserve the application design, the dynamic or distributed routing program must

Chapter 14. Affinity

181

ensure that all transactions that use the address of the loaded program (or table) are routed to the same target region.

TOR DTR program In this example, the TOR must route to AOR1 all other transactions that require access to the program (table) loaded by TRN1.

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

AOR2

Figure 39. Illustration of inter-transaction affinity created by use of shared storage. 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.

182

CICS Transaction Server: 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 40 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 completes . (waiting) . . 3. Continues. TRN2 1. Reads address from TS queue. 2. Accesses the storage. 3. Resumes TRN1.

Figure 40. 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 12 for commands that provide ways of suspending and resuming a task that passes the address of its local storage.
Table 12. Methods for suspending and resuming (synchronizing) tasks Suspending operation WAIT EVENT, WAIT EXTERNAL, WAITCICS RETRIEVE WAIT DELAY POST START ENQ Resuming operation POST START CANCEL CANCEL CANCEL 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 12 are fundamentally unsafe because it is possible that the storage-owning task could be purged.

Chapter 14. Affinity

183

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 tasks 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 41.

TOR DTR program

AOR TRN1 1. Stores the address of ECB in temporary storage queue for TRN2 2. Suspends with WAIT EVENT ECADDR(ptr-ref) . . (waiting) . . . . 3. Resumed by CICS

TRN2 1. At end of processing, (completion of event) reads address of ECB from TS queue. 2. Posts ECB (by MVS POST or 'hand-posted') 3. Returns control to CICS

Figure 41. 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 41 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

184

CICS Transaction Server: 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 (see Using ENQ and DEQ commands with ENQMODEL resource definitions on page 177 and the CICS Resource Definition Guide for a description of ENQMODELs) so that they have sysplex-wide scope. 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 42.

TOR DTR program

AOR TRN1 1. Issues ENQ command on resource name of shared resource 2. Modifies or uses shared resource . . 3. Issues DEQ command on shared resource. TRN2 1. Issues ENQ command on resource name of shared resource 2. Suspended by CICS while resource in use by TRN1 3. Resumed by CICS when resource free

Figure 42. 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 42 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

Chapter 14. Affinity

185

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.

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

186

CICS Transaction Server: CICS Application Programming Guide

data-sharing pool. See Figure 43 for an illustration of a temporary storage data-sharing server.

TOR DTR program DFHTSTXX Prefix| Sysid AOR1 TST=XX AOR2 TST=XX AOR3 TST=XX AOR4 TST=XX AAAA* ABCD* XXXX* ZZZZ* Sysid CICQ DFHXQMN TS Server CICQ CICQ CICQ CICQ Pool DFHXQTS1

Coupling Facility
Figure 43. 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 14. Affinity

187

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 44 for an illustration of the use of a remote queue-owning region.

TOR DTR program

DFHTSTXX Prefix Sysid AOR1 TST=XX AOR2 TST=XX AOR3 TST=XX AOR4 TST=XX AAAA* ABCD* XXXX* ZZZZ* CICQ CICQ CICQ CICQ

ROR

Figure 44. 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.

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.

188

CICS Transaction Server: CICS Application Programming Guide

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 45 illustrates the use of a remote transient data queue-owning region.

TOR DTR program

TDQ defn. Queue AOR1 AOR2 AOR3 AOR4 AAAA ABCD XXXX ZZZZ CICQ CICQ CICQ CICQ Syst.

TDQ definition Queue FOR QOR (CICQ) AAAA ABCD XXXX ZZZZ Trig. Tran. Term. nn nn BBBB CCCC Tnnn Pnnn

Figure 45. 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).

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 46 on page 190. 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.

Chapter 14. Affinity

189

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 a RETRIEVE WAIT . . (suspended) . . 3. Resumes. TRN2 1. Reads TRANSID & of TRN1 from TS . (process) . 3. Resumes TRN1 by START with FROM TERMID queue

issuing option.

Figure 46. Illustration of task synchronization using RETRIEVE WAIT and START commands

In the example of task synchronization using RETRIEVE WAIT and START commands shown in Figure 46, 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.

190

CICS Transaction Server: CICS Application Programming Guide

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 47 on page 192 illustrates this programming technique.

Chapter 14. Affinity

191

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

192

CICS Transaction Server: 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 48 on page 194. 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.

Chapter 14. Affinity

193

TOR DTR program

AOR TRN1 1. Writes DELAY command REQID to TS queue for use by TRN2 2. Issues DELAY to wait until TRN2 issues CANCEL command . . (suspended) . . . . 3. Resumes. TRN2 1. Reads REQID of DELAY from TS queue . (process) . 2. Completes processing 3. Resumes TRN1 by CANCELing the DELAY.

Figure 48. Illustration of the use of the DELAY and CANCEL REQID commands

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.

194

CICS Transaction Server: CICS Application Programming Guide

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 49 illustrates this technique.

TOR DTR program

AOR TRN1 1. Issues POST command 2. Stores REQID of POST in TS queue for use by TRN2 . (process) . . . 3. Periodically check if posted 4. Resumes when time expired, or when POST cancelled by TRN2.

TRN2 1. Reads REQID of POST request . (process) . 2. Completes processing 3. Resumes TRN1 by CANCELing the POST.

Figure 49. 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. 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

Chapter 14. Affinity

195

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. 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 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 Transaction Affinities Utility to detect affinities. The CICS Transaction Affinities Utility Guide 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 Transaction Affinities Utility 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.

196

CICS Transaction Server: CICS Application Programming Guide

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. 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
Chapter 14. Affinity

197

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

Terminal User enters tranid GGGG TOR Calls DTR program Routes GGGG to AOR2 DTR program Affinity group Relation: GLOBAL Lifetime: PERM Transids: GGGG

1. Checks affinity groups for GGGG 2. Start global affinity for 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 GGGG

AOR3

AOR4

AOR5

AOR6

Figure 50. Managing inter-transaction affinity with global relation and permanent lifetime

In this example, 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 (AOR1 through AOR6), but all other instances, from any terminal, must be routed to whichever target region is selected for GGGG.

198

CICS Transaction Server: CICS Application Programming Guide

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. 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 187 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 51 on page 200.

Chapter 14. Affinity

199

LUNAME= IGKS201 User enters tranid AAAA

TOR Calls DTR program Routes AAAA to AOR4 DTR program Affinity group Relation: LUNAME Lifetime: PCONV Transids: AAAA BBBB . . ZZZZ AAAA on IGKS201 sent to AOR4

1. Checks affinity groups for AAAA 2. Detects start of pseudoconv. 3. Selects an AOR from candidate list. 4. Records choice of AOR (for example, AOR4) for this group.

AOR1

AOR2

AOR3

AOR4 AAAA

AOR5

AOR6

Figure 51. 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 from 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.

200

CICS Transaction Server: 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 52.

Userid= ANOTHER User enters tranid WWWW

TOR Calls DTR program Routes WWWW to AOR4 DTR program Affinity group Relation: USERID Lifetime: SIGNON Transids: WWWW XXXX . . YYYY WWWW sent to AOR4 for user=ANOTHER

1. Checks affinity groups for WWWW 2. Detects start of pseudoconv. 3. Selects an AOR from candidate list. 4. Records choice of AOR (for example, AOR4) for this group.

AOR1

AOR2

AOR3

AOR4 WWWW

AOR5

AOR6

Figure 52. 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 14. Affinity

201

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

AOR 1 BAPPL activity started Transid BAP1 Calls dynamic routing program Routes BAP1 to AOR4 Dynamic routing program 1. Checks affinity groups for BAP1. 2. Start BAPPL affinity for transid BAP1 3. Select target region from candidate list 4. Record choice of target region (for example, AOR4) for this group. Affinity group Relation: BAPPL Lifetime: ACTIVITY Transid : BAP1

Sent BAP1 to AOR4

AOR2

AOR3

AOR4

AOR5

AOR6

Figure 53. Managing inter-transaction affinity with BAPPL relation and activity lifetime

In this example, the first instance of BTS transaction BAP1 starts a BAPPLactivity 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 affinitys 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.

202

CICS Transaction Server: CICS Application Programming Guide

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 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 14. Affinity

203

204

CICS Transaction Server: CICS Application Programming Guide

Chapter 15. 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 207

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 16. Dealing with exception conditions on page 209. (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.

205

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.

206

CICS Transaction Server: 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 15. Recovery design

207

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.3 The SAA Resource Recovery interface is implemented as a call interface, having two call types: SRRCMIT CommitEquivalent to SYNCPOINT command. SRRBACK BackoutEquivalent 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 379 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.
3. 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.)

208

CICS Transaction Server: CICS Application Programming Guide

Chapter 16. 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 210 v Modifying default CICS exception handling on page 213

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 210 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
Copyright IBM Corp. 1989, 2001

209

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 wit