CICS Application Programming Guide

CICS Transaction Server for OS/390

CICS Application Programming GuideRelease 3

SC33-1687-02

IBM

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

Third edition (March 1999)

This edition applies to Release 3 of CICS Transaction Server for OS/390, program number 5655-147, and to allsubsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are usingthe correct edition for the level of the product.

This edition replaces and makes obsolete the previous edition, SC33-1687-01. The technical changes for this editionare summarized under Summary of changes and are indicated by a vertical bar to the left of a change.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications arenot 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 anyway it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 1989, 1999. All rights reserved.US Government Users Restricted Rights Use duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsNotices . . . . . . . . . . . . . . xiProgramming Interface information . . . . . . xiiTrademarks. . . . . . . . . . . . . . xii

Preface . . . . . . . . . . . . . . xiiiWhat this book is about . . . . . . . . . . xiii

Who should read this book. . . . . . . . xiii

Bibliography . . . . . . . . . . . . xvCICS Transaction Server for OS/390 . . . . . xv

CICS books for CICS Transaction Server forOS/390 . . . . . . . . . . . . . . xvCICSPlex SM books for CICS TransactionServer for OS/390 . . . . . . . . . . xviOther CICS books . . . . . . . . . . xvi

Books from related libraries . . . . . . . . xviDL/I . . . . . . . . . . . . . . . xviMVS . . . . . . . . . . . . . . . xviDB2 . . . . . . . . . . . . . . . xviiScreen definition facility II (SDF II) . . . . . xviiCommon programming interface . . . . . . xviiCommon user access . . . . . . . . . xviiProgramming languages . . . . . . . . xviiTeleprocessing Network Simulator (TPNS) . . xviiiDistributed Processing Programming Executive(DPPX): . . . . . . . . . . . . . . xviiiLanguage Environment:. . . . . . . . . xviiiMiscellaneous books. . . . . . . . . . xviii

Determining if a publication is current . . . . . xix

Summary of Changes . . . . . . . . xxiChanges for this CICS Transaction Server forOS/390 Release 3 edition . . . . . . . . . xxiChanges for this CICS Transaction Server forOS/390 Release 2 edition . . . . . . . . . xxiChanges for the CICS Transaction Server forOS/390 Release 1 edition . . . . . . . . . xxi

Part 1. Getting started . . . . . . . 1

Chapter 1. Preparing your applicationto run . . . . . . . . . . . . . . . 3Writing CICS programs . . . . . . . . . . 3Preparing your program. . . . . . . . . . 4Locale support . . . . . . . . . . . . . 5The translation process . . . . . . . . . . 6Specifying translator options . . . . . . . . 7Translator options. . . . . . . . . . . . 8Preparing BMS maps . . . . . . . . . . 19

Chapter 2. Programming in COBOL 21Based addressing . . . . . . . . . . . 21

WITH DEBUGGING MODE . . . . . . . 22

Restrictions . . . . . . . . . . . . . 22Restrictions for 31-bit addressing . . . . . 24DL/I CALL interface . . . . . . . . . . 24

Mixing languages . . . . . . . . . . . . 25Calling subprograms from COBOL . . . . . . 26COBOL with the ANSI 85 COBOL standards . . . 30Literals intervening in blank lines. . . . . . . 31

Translator action . . . . . . . . . . . 31Sequence numbers containing any character . . 31

Translator action . . . . . . . . . . . 31REPLACE statement . . . . . . . . . . 32

Translator action . . . . . . . . . . . 32Batch compilation. . . . . . . . . . . . 32

Translator action . . . . . . . . . . . 32Compiler and linkage editor . . . . . . . 32

Nested programs . . . . . . . . . . . . 35Translator action . . . . . . . . . . . 35

Reference modification . . . . . . . . . . 38Translator action . . . . . . . . . . . 39

Global variables . . . . . . . . . . . . 39Translator action . . . . . . . . . . . 39

Comma and semicolon as delimiters . . . . . 39Translator action . . . . . . . . . . . 39

Symbolic character definition . . . . . . . . 39Translator action . . . . . . . . . . . 40

Summary of restrictions. . . . . . . . . . 40COBOL2 translator option . . . . . . . . . 40

Translator action . . . . . . . . . . . 41COBOL3 translator option . . . . . . . . . 41

Translator action . . . . . . . . . . . 41OO COBOL translator option . . . . . . . . 41

Translator action . . . . . . . . . . . 42Nesting programs. . . . . . . . . . . 42

Chapter 3. Programming in C and C++ 43Data declarations needed for C and C++ . . . . 44Naming EIB fields. . . . . . . . . . . . 44

Data types in EIB fields . . . . . . . . . 44Restrictions . . . . . . . . . . . . . . 45

Passing values as arguments . . . . . . . 46ADDRESS EIB command . . . . . . . . 48ADDRESS COMMAREA command . . . . . 48

C++ considerations . . . . . . . . . . . 49Restrictions . . . . . . . . . . . . . 49

Chapter 4. Programming in PL/I . . . . 51Restrictions . . . . . . . . . . . . . . 51PL/I STAE execution-time option . . . . . . . 52OPTIONS(MAIN) specification . . . . . . . 52Program segments . . . . . . . . . . . 52PL/I and dynamic storage . . . . . . . . . 52

Chapter 5. Programming in Assembler 55Compilers supported. . . . . . . . . . . 55Restrictions for 31-bit addressing . . . . . . 55

Copyright IBM Corp. 1989, 1999 iii

MVS restrictions . . . . . . . . . . . . 55Invoking assembler language applicationprograms with a call . . . . . . . . . . 56

Chapter 6. Language Environment . . 59Levels of support in Language Environment . . . 59Abend handling in an LE environment . . . . . 60Defining run-time options . . . . . . . . . 60

Part 2. Object Orientedprogramming in CICS . . . . . . . 61

Chapter 7. Object Oriented (OO)programming concepts . . . . . . . 63What is OO? . . . . . . . . . . . . . 63

Encapsulation . . . . . . . . . . . . 63Data structures . . . . . . . . . . . 63

OO Terminology . . . . . . . . . . . . 64Accessing CICS services from OO programs. . . 66

Chapter 8. Programming in Java . . . 67The JCICS Java classes . . . . . . . . . 67

Translation . . . . . . . . . . . . . 67JavaBeans . . . . . . . . . . . . . 68Library structure . . . . . . . . . . . 68CICS resources . . . . . . . . . . . 69Command arguments . . . . . . . . . 69Using the Java Record Framework . . . . . 69Threads . . . . . . . . . . . . . . 70

JCICS programming considerations . . . . . . 70Storage management . . . . . . . . . 70Abnormal termination in Java . . . . . . . 70Exception handling in Java . . . . . . . 71CICS Intercommunication . . . . . . . . 73BMS . . . . . . . . . . . . . . . 74Terminal Control . . . . . . . . . . . 74File control services . . . . . . . . . . 74Program control services . . . . . . . . 74Unit of Work (UOW) services . . . . . . . 74Temporary storage queue services . . . . . 74Transient data queue services . . . . . . 75Environment services . . . . . . . . . 75Unsupported CICS services . . . . . . . 77System.out and System.err . . . . . . . 78

Using JCICS . . . . . . . . . . . . . 78Writing the main method . . . . . . . . 78Creating objects . . . . . . . . . . . 78Using objects . . . . . . . . . . . . 78

Chapter 9. JCICS sample programs 81Supplied sample components . . . . . . . . 81Building the Java samples . . . . . . . . . 82

Building the Java samples for ET/390 . . . . 82Building the Java samples for the JVM. . . . 83

Building the CICS native applications . . . . . 83Resource definitions . . . . . . . . . . 83

Running the Hello World sample . . . . . . . 83Running the Program Control sample . . . . . 84Running the TDQ sample . . . . . . . . . 84

Running the TSQ sample . . . . . . . . . 85

Chapter 10. Support for VisualAge forJava, Enterprise ToolKit for OS/390 87Building a CICS Java program . . . . . . . 88

Preparing prerequisite environment . . . . . 88Compiling and binding a program usingVisualAge for Java . . . . . . . . . . 89Developing a Java program using javac . . . 92Using the ET/390 binder . . . . . . . . 92

Running a CICS Java program . . . . . . . 95Interactive debug using the Debug Tool . . . 95Run-time requirements . . . . . . . . . 96

Chapter 11. Using the CICS Javavirtual machine . . . . . . . . . . . 97JVM execution environment . . . . . . . . 97Running JVM programs. . . . . . . . . . 98

Compile-time requirements. . . . . . . . 99Run-time requirements . . . . . . . . . 99CICS-supplied .jar files . . . . . . . . . 100JVM directory . . . . . . . . . . . . 100JVM environment variables . . . . . . . 100stdin, stdout and stderr . . . . . . . . . 101

JCICS programming considerations for JVMprograms . . . . . . . . . . . . . . 101

Java System Properties. . . . . . . . . 102Using the Abstract Windows Toolkit (AWT) classes 103

Remote Abstract Windows Toolkit . . . . . 103Using Remote AWT with CICS . . . . . . 103

Part 3. Application design . . . . .105

Chapter 12. Designing efficientapplications . . . . . . . . . . . . 109Program structure. . . . . . . . . . . . 109

Program size . . . . . . . . . . . . 110Choosing between pseudoconversational andconversational design . . . . . . . . . 111

General programming techniques . . . . . . 113Virtual storage . . . . . . . . . . . . 113Reducing paging effects . . . . . . . . 114Exclusive control of resources . . . . . . 116Processor usage . . . . . . . . . . . 117Recovery design implications . . . . . . . 118Terminal interruptibility . . . . . . . . . 118Operational control . . . . . . . . . . 119Operating system waits . . . . . . . . . 119Runaway tasks . . . . . . . . . . . 120Auxiliary trace . . . . . . . . . . . . 120The NOSUSPEND option . . . . . . . . 120Multithreading . . . . . . . . . . . . 121

Storing data within a transaction . . . . . . . 124Transaction work area (TWA) . . . . . . . 124User storage . . . . . . . . . . . . 125COMMAREA in LINK and XCTL commands 125Program storage . . . . . . . . . . . 126

Lengths of areas passed to CICS commands . . 126LENGTH options . . . . . . . . . . . 126

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

Journal records . . . . . . . . . . . 127Data set definitions . . . . . . . . . . 127Recommendation . . . . . . . . . . . 127

EXEC interface stubs . . . . . . . . . . 127COBOL and PL/I . . . . . . . . . . . 128C and C++ . . . . . . . . . . . . . 128Assembler language . . . . . . . . . . 128Temporary storage . . . . . . . . . . 128Intrapartition transient data. . . . . . . . 130GETMAIN SHARED command . . . . . . 130Your own data sets . . . . . . . . . . 131

Data operations . . . . . . . . . . . . 131Database operations. . . . . . . . . . 131Data set operations . . . . . . . . . . 131Browsing (in non-RLS mode) . . . . . . . 133Logging . . . . . . . . . . . . . . 133Sequential data set access . . . . . . . 134

Terminal operations . . . . . . . . . . . 134Length of the data stream sent to the terminal 134Basic mapping support considerations . . . . 135Page-building and routing operations . . . . 138Requests for printed output . . . . . . . 140Additional terminal control considerations . . . 140

Chapter 13. Sharing data acrosstransactions . . . . . . . . . . . . 143Common work area (CWA) . . . . . . . . 143

Protecting the CWA . . . . . . . . . . 144TCTTE user area (TCTUA) . . . . . . . . 147COMMAREA in RETURN commands . . . . . 148Display screen. . . . . . . . . . . . . 148

Chapter 14. Affinity . . . . . . . . . 151What is affinity? . . . . . . . . . . . . 151

Types of affinity . . . . . . . . . . . 152Techniques used by CICS application programs topass data . . . . . . . . . . . . . . 153

Safe techniques . . . . . . . . . . . 153Unsafe techniques . . . . . . . . . . 153Suspect techniques . . . . . . . . . . 154

Safe programming techniques . . . . . . . 154The COMMAREA. . . . . . . . . . . 155The TCTUA. . . . . . . . . . . . . 156Using ENQ and DEQ commands withENQMODEL resource definitions . . . . . 158BTS containers . . . . . . . . . . . 159

Unsafe programming techniques . . . . . . . 159Using the common work area . . . . . . . 159Using GETMAIN SHARED storage . . . . . 160Using the LOAD PROGRAM HOLD command 161Sharing task-lifetime storage . . . . . . . 162Using the WAIT EVENT command . . . . . 164Using ENQ and DEQ commands withoutENQMODEL resource definitions . . . . . 165

Suspect programming techniques . . . . . . 166Using temporary storage . . . . . . . . 166Using transient data . . . . . . . . . . 169Using the RETRIEVE WAIT and STARTcommands . . . . . . . . . . . . . 170

Using the START and CANCEL REQIDcommands . . . . . . . . . . . . . 171Using the DELAY and CANCEL REQIDcommands . . . . . . . . . . . . . 173Using the POST and CANCEL REQIDcommands . . . . . . . . . . . . . 175

Detecting inter-transaction affinities . . . . . . 176Inter-transaction affinities caused by applicationgenerators . . . . . . . . . . . . . 176

Duration and scope of inter-transaction affinities 177Affinity transaction groups . . . . . . . . 177Relations and lifetimes . . . . . . . . . 177

Recommendations . . . . . . . . . . . 183

Chapter 15. Using CICS documents 185The DOCUMENT application programminginterface . . . . . . . . . . . . . . . 185

Creating a document. . . . . . . . . . 185Programming with documents. . . . . . . . 186

Setting symbol values . . . . . . . . . 187Embedded template commands . . . . . . 187Using templates in your application . . . . . 188The lifespan of a document . . . . . . . 189

Chapter 16. Using named counterservers . . . . . . . . . . . . . . 195Overview . . . . . . . . . . . . . . 195

The named counter fields . . . . . . . . 195Named counter pools . . . . . . . . . . 196

Named counter options table . . . . . . . 196The named counter API commands . . . . . . 198The named counter CALL interface . . . . . . 199

Chapter 17. Intercommunicationconsiderations . . . . . . . . . . . 201Design considerations . . . . . . . . . . 201

Programming language . . . . . . . . . 202Transaction routing . . . . . . . . . . . 202Function shipping . . . . . . . . . . . . 202Distributed program link (DPL) . . . . . . . 203

Using the distributed program link function . . 204Examples of distributed program link . . . . 206Programming considerations for distributedprogram link . . . . . . . . . . . . 211

Asynchronous processing . . . . . . . . . 215Distributed transaction processing (DTP) . . . . 215Common Programming Interface Communications(CPI Communications) . . . . . . . . . . 215External CICS interface (EXCI) . . . . . . . 216

Chapter 18. Recovery considerations 217Journaling . . . . . . . . . . . . . . 217

Journal records . . . . . . . . . . . 217Journal output synchronization . . . . . . 217

Syncpointing . . . . . . . . . . . . . 219

Chapter 19. Minimizing errors. . . . . 223Protecting CICS from application errors . . . . 223Testing applications . . . . . . . . . . . 223

Contents v

Chapter 20. Dealing with exceptionconditions . . . . . . . . . . . . . 225Default CICS exception handling. . . . . . . 225Handling exception conditions by in-line code . . 226

How to use the RESP and RESP2 options . . 227An example of exception handling in C. . . . 227An example of exception handling in COBOL 229

Modifying the default CICS exception handling 229Use of HANDLE CONDITION command . . . 231Use of the HANDLE CONDITION ERRORcommand . . . . . . . . . . . . . 232How to use the IGNORE CONDITIONcommand . . . . . . . . . . . . . 233Use of the HANDLE ABEND command . . . 234RESP and NOHANDLE options . . . . . . 234How CICS keeps track of what to do . . . . 234

Chapter 21. Access to systeminformation . . . . . . . . . . . . 237System programming commands . . . . . . 237EXEC interface block (EIB) . . . . . . . . 237

Chapter 22. Abnormal terminationrecovery . . . . . . . . . . . . . . 239Creating a program-level abend exit . . . . . 240Restrictions on retrying operations . . . . . . 241Trace . . . . . . . . . . . . . . . . 242

Trace entry points . . . . . . . . . . 243Monitoring . . . . . . . . . . . . . . 244Dump. . . . . . . . . . . . . . . . 244

Part 4. Files and databases . . . .247

Chapter 23. An overview of file control 249VSAM data sets . . . . . . . . . . . . 249

Key-sequenced data set (KSDS). . . . . . 250Entry-sequenced data set (ESDS) . . . . . 250Relative record data set (RRDS) . . . . . . 250Empty data sets . . . . . . . . . . . 251VSAM alternate indexes . . . . . . . . 251Accessing files in RLS mode . . . . . . . 252

BDAM data sets . . . . . . . . . . . . 252CICS shared data tables . . . . . . . . . 254Coupling facility data tables . . . . . . . . 254

Coupling facility data table models . . . . . 256Comparison of different techniques for sharingdata . . . . . . . . . . . . . . . . 257Reading records . . . . . . . . . . . . 259

Direct reading (using READ command) . . . 259Sequential reading (browsing). . . . . . . 261Skip-sequential processing. . . . . . . . 263

Updating records . . . . . . . . . . . . 264Deleting records . . . . . . . . . . . . 265

Deleting single records . . . . . . . . . 265Deleting groups of records (generic delete) 266Read integrity . . . . . . . . . . . . 266

Adding records . . . . . . . . . . . . 266Adding to a KSDS . . . . . . . . . . 266Adding to an ESDS . . . . . . . . . . 267

Adding to an RRDS . . . . . . . . . . 267Records that are already locked . . . . . . 267Specifying record length . . . . . . . . 267Sequential adding of records (WRITEMASSINSERT command) . . . . . . . . 267

Review of file control command options . . . . 268The RIDFLD option . . . . . . . . . . 268The INTO and SET options . . . . . . . 268The FROM option. . . . . . . . . . . 269The TOKEN option . . . . . . . . . . 269

Avoiding transaction deadlocks . . . . . . . 270VSAM-detected deadlocks (RLS only) . . . . 271Rules for avoiding deadlocks . . . . . . . 272

KEYLENGTH option for remote data sets . . . . 272

Chapter 24. File controlVSAMconsiderations . . . . . . . . . . . 273Record identification . . . . . . . . . . . 273

Key . . . . . . . . . . . . . . . 273Relative byte address (RBA) and relative recordnumber (RRN) . . . . . . . . . . . . 273

Locking of VSAM records in recoverable files . . 274Update locks and delete locks (non-RLS modeonly) . . . . . . . . . . . . . . . 274

Record locking of VSAM records for files accessedin RLS mode . . . . . . . . . . . . . 275

Exclusive locks and shared locks . . . . . 276Conditional update requests . . . . . . . . 278

File control implementation of NOSUSPEND 279CICS locking for writing to ESDS . . . . . . 279

Chapter 25. File controlBDAMconsiderations . . . . . . . . . . . 281Record identification . . . . . . . . . . . 281

Block reference subfield . . . . . . . . 281Physical key subfield . . . . . . . . . 281Deblocking argument subfield. . . . . . . 282

Updating records from BDAM data sets . . . . 282Browsing records from BDAM data sets . . . . 282Adding records to BDAM data sets . . . . . . 283BDAM exclusive control. . . . . . . . . . 284

Chapter 26. Database control . . . . . 285DL/I databases . . . . . . . . . . . . 285DATABASE 2 (DB2) databases . . . . . . . 285

Requests to DB2 . . . . . . . . . . . 285

Part 5. Data communication . . . .287

Chapter 27. Introduction to datacommunication . . . . . . . . . . . 291Basic CICS terms. . . . . . . . . . . . 292How tasks are started . . . . . . . . . . 293Which transaction? . . . . . . . . . . . 294CICS APIs for terminals. . . . . . . . . . 297Topics elsewhere in this book . . . . . . . . 297Where to find more information . . . . . . . 298

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

Chapter 28. The 3270 family ofterminals . . . . . . . . . . . . . 299Background. . . . . . . . . . . . . . 299

Screen fields . . . . . . . . . . . . 300Personal computers . . . . . . . . . . 300

The 3270 buffer . . . . . . . . . . . . 302Writing to a 3270 terminal . . . . . . . . 3023270 write commands . . . . . . . . . 303Write control character . . . . . . . . . 303

3270 display data: defining 3270 fields. . . . . 304Display characteristics . . . . . . . . . 3043270 field attributes . . . . . . . . . . 305Extended attributes . . . . . . . . . . 306Orders in the data stream . . . . . . . . 307Outbound data stream sample . . . . . . 310

Input from a 3270 terminal . . . . . . . . . 312Data keys . . . . . . . . . . . . . 313Keyboard control keys . . . . . . . . . 313Attention keys . . . . . . . . . . . . 313Reading from a 3270 terminal. . . . . . . 314Inbound field format . . . . . . . . . . 315Input example . . . . . . . . . . . . 315

Unformatted mode . . . . . . . . . . . 316

Chapter 29. Basic mapping support 317Other sources on BMS . . . . . . . . . . 318

BMS support levels . . . . . . . . . . 318A BMS output example . . . . . . . . . 319Creating the map . . . . . . . . . . . 322Defining map fields: DFHMDF . . . . . . 323Defining the map: DFHMDI . . . . . . . 325Defining the map set: DFHMSD . . . . . . 325Rules for writing BMS macros. . . . . . . 326Assembling the map . . . . . . . . . . 328ADS Descriptor . . . . . . . . . . . 330Complex fields. . . . . . . . . . . . 331

Sending mapped output: basics . . . . . . . 333The SEND MAP command. . . . . . . . 333Acquiring and defining storage for the maps 333Initializing the output map . . . . . . . . 335Moving the variable data to the map . . . . 335Setting the display characteristics . . . . . 336Control options on the SEND MAP command 338Options for merging the symbolic and physicalmaps . . . . . . . . . . . . . . . 339Summary: what appears on the screen . . . 340Positioning the cursor . . . . . . . . . 343Sending invalid data and other errors . . . . 344

Receiving data from a display. . . . . . . . 344An input-output example . . . . . . . . 344The symbolic input map. . . . . . . . . 347Programming simple mapped input . . . . . 347The RECEIVE MAP command . . . . . . 348Getting storage for mapped input: INTO andSET . . . . . . . . . . . . . . . 348Reading from a formatted screen: what comesin . . . . . . . . . . . . . . . . 349Other information from RECEIVE MAP. . . . 350Processing the mapped input . . . . . . . 352Handling input errors. . . . . . . . . . 353

Mapped output after mapped input . . . . . 354MAPFAIL and other exceptional conditions . . 355Formatting other input . . . . . . . . . 356

Support for non-3270 terminals . . . . . . . 357Output considerations for non-3270 devices 357Differences on input . . . . . . . . . . 357Special options for non-3270 terminals . . . . 358Device-dependent maps: map suffixes . . . . 359

The MAPPINGDEV facility . . . . . . . . . 362SEND MAP with the MAPPINGDEV option 362RECEIVE MAP with the MAPPINGDEV option 363Sample assembler MAPPINGDEV application 364

Block data . . . . . . . . . . . . . . 365Sending mapped output: additional facilities . . . 366

Output disposition options: TERMINAL, SET,and PAGING . . . . . . . . . . . . 367BMS logical messages . . . . . . . . . 367Terminal operator paging: the CSPG transaction 370Changing your mind: The PURGE MESSAGEcommand . . . . . . . . . . . . . 371Logical message recovery . . . . . . . . 371

Page formation: the ACCUM option . . . . . . 372Floating maps: how BMS places maps usingACCUM . . . . . . . . . . . . . . . 372

Page breaks: BMS overflow processing . . . 373Map placement rules. . . . . . . . . . 374ASSIGN options for cumulative processing . . 376Input from a composite screen . . . . . . 376Performance considerations . . . . . . . 377

Formatting text output . . . . . . . . . . 378The SEND TEXT command . . . . . . . 379Text logical messages . . . . . . . . . 379Page format for text messages . . . . . . 379How BMS breaks text into lines . . . . . . 380Header and trailer format for text messages 381SEND TEXT extensions: SEND TEXT MAPPEDand SEND TEXT NOEDIT . . . . . . . . 382

Message routing: the ROUTE command . . . . 383How routing works . . . . . . . . . . 384Specifying destinations for a routed message 384Route list format . . . . . . . . . . . 386Delivery conditions . . . . . . . . . . 388Undeliverable messages . . . . . . . . 389Temporary storage and routing . . . . . . 389Programming considerations with routing . . . 390

Using SET . . . . . . . . . . . . . . 391Partition support . . . . . . . . . . . . 393

Uses for partitioned screens . . . . . . . 394How to define partitions. . . . . . . . . 3953290 character size . . . . . . . . . . 396Programming considerations . . . . . . . 396Establishing the partitioning . . . . . . . 397Partition options for BMS SEND commands 398Determining the active partition . . . . . . 398Partition options for BMS RECEIVE commands 398ASSIGN options for partitions . . . . . . . 399Partitions and logical messages . . . . . . 399Partitions and routing . . . . . . . . . 400New attention identifiers and exceptionconditions . . . . . . . . . . . . . 400Terminal sharing . . . . . . . . . . . 400

Contents vii

Restrictions on partitioned screens . . . . . 401Logical device components . . . . . . . . 401

Defining logical device components . . . . . 401Sending data to a logical device component 402LDCs and logical messages . . . . . . . 402LDCs and routing . . . . . . . . . . . 403

BMS support for other special hardware . . . . 40310/63 magnetic slot reader. . . . . . . . 403Field selection features . . . . . . . . . 404Cursor and pen-detectable fields. . . . . . 405Outboard formatting . . . . . . . . . . 407

Chapter 30. Terminal control . . . . . 409Access method support . . . . . . . . . . 409Terminal control commands . . . . . . . . 410

Data transmission commands. . . . . . . 410Send/receive mode . . . . . . . . . . 411Speaking out of turn . . . . . . . . . . 412Interrupting . . . . . . . . . . . . . 413Terminal waits . . . . . . . . . . . . 413What you get on a RECEIVE . . . . . . . 414Control commands . . . . . . . . . . 415Finding the right commands . . . . . . . 415Finding out about your terminal . . . . . . 420EIB feedback on terminal control operations 422

VTAM considerations . . . . . . . . . . 422Chaining input data . . . . . . . . . . 423Chaining output data. . . . . . . . . . 423Handling logical records . . . . . . . . 423Response protocol . . . . . . . . . . 424Using function management headers . . . . 424Preventing interruptions (bracket protocol) . . 425

Sequential terminal support . . . . . . . . 426Coding considerations for sequential terminals 426

TCAM considerations . . . . . . . . . . 427Coding for the DCB interface . . . . . . . 428Coding for the ACB interface . . . . . . . 428

Batch data interchange . . . . . . . . . . 429Destination selection and identification . . . . 430Definite response . . . . . . . . . . . 430Waiting for function completion . . . . . . 430

Chapter 31. CICS support for printing 433Formatting for CICS printers . . . . . . . . 433

3270 printers . . . . . . . . . . . . 434Options for 3270 printers . . . . . . . . 435Non-3270 CICS printers . . . . . . . . 438Determining the characteristics of a CICSprinter . . . . . . . . . . . . . . 439

CICS printers: getting the data to the printer . . . 441Printing with a START command. . . . . . 441Printing with transient data. . . . . . . . 442Printing with BMS routing . . . . . . . . 443

Non-CICS printers . . . . . . . . . . . 443Formatting for non-CICS printers. . . . . . 443Non-CICS printers: Delivering the data. . . . 444CICS API considerations . . . . . . . . 444Notifying the print application . . . . . . . 445

Printing display screens. . . . . . . . . . 446CICS print key . . . . . . . . . . . . 446ISSUE PRINT and ISSUE COPY . . . . . 447

Hardware print key . . . . . . . . . . 447BMS screen copy. . . . . . . . . . . 447

Chapter 32. CICS interface to JES . . . 449Creating a spool file . . . . . . . . . . . 449

Reading input spool files . . . . . . . . 450Identifying spool files . . . . . . . . . 451Some examples of SPOOLOPEN for OUTPUTwith OUTDESCR option . . . . . . . . 454Programming note for spool commands . . . 456Spool interface restrictions . . . . . . . . 456

Part 6. CICS management functions 457

Chapter 33. Interval control. . . . . . 459Expiration times . . . . . . . . . . . . 459Request identifiers . . . . . . . . . . . 461

Chapter 34. Task control . . . . . . . 463Controlling sequence of access to resources. . . 464

Chapter 35. Program control . . . . . 467Application program logical levels . . . . . . 468Link to another program expecting return . . . . 468Passing data to other programs . . . . . . . 469

COMMAREA . . . . . . . . . . . . 469INPUTMSG. . . . . . . . . . . . . 471Using the INPUTMSG option on the RETURNcommand . . . . . . . . . . . . . 473Other ways of passing data . . . . . . . 473Mixed addressing mode transactions . . . . 473Examples of passing data with the LINKcommand . . . . . . . . . . . . . 474Examples of passing data with the RETURNcommand . . . . . . . . . . . . . 476

Chapter 36. Storage control . . . . . 479Overview of CICS storage protection andtransaction isolation . . . . . . . . . . . 480Storage protection . . . . . . . . . . . 480

Terminology. . . . . . . . . . . . . 481Selecting the execution key for applications 481Defining the execution key . . . . . . . . 482Selecting and defining the storage key forapplications. . . . . . . . . . . . . 482

Deciding what execution and storage key tospecify . . . . . . . . . . . . . . . 485

User-key applications . . . . . . . . . 485CICS-key applications . . . . . . . . . 486

Storage protection exception conditions . . . . 488Transaction isolation . . . . . . . . . . . 488

Reducing system outages . . . . . . . . 489Protecting application data . . . . . . . . 489Protecting CICS from being passed invalidaddresses . . . . . . . . . . . . . 489Aiding application development . . . . . . 489

Using transaction isolation . . . . . . . . . 490MVS subspaces . . . . . . . . . . . . 491

Subspaces and basespaces for transactions 492

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

The common subspace and shared storage 493

Chapter 37. Transient data control. . . 495Intrapartition queues . . . . . . . . . . . 495Extrapartition queues . . . . . . . . . . 496Indirect queues . . . . . . . . . . . . 496Automatic transaction initiation (ATI) . . . . . 497

Chapter 38. Temporary storage control 499Temporary storage queues. . . . . . . . . 500Typical uses of temporary storage control . . . . 500

Chapter 39. Security control . . . . . 503QUERY SECURITY command . . . . . . . 503

Using QUERY SECURITY . . . . . . . . 503Non-terminal transaction security. . . . . . . 504

Part 7. Testing applications . . . .507

Chapter 40. Testing applications: theprocess . . . . . . . . . . . . . . 509Preparing the application and system table entries 509Preparing the system for debugging. . . . . . 510Single-thread testing . . . . . . . . . . . 510Multithread testing . . . . . . . . . . . 510Regression testing . . . . . . . . . . . 510

Chapter 41. Execution diagnosticfacility (EDF) . . . . . . . . . . . . 513Getting started. . . . . . . . . . . . . 513Where does EDF intercept the program? . . . . 514What does EDF display? . . . . . . . . . 515

The header . . . . . . . . . . . . . 515The body . . . . . . . . . . . . . 516How you can intervene in program execution 522EDF menu functions . . . . . . . . . . 523

How to use EDF . . . . . . . . . . . . 529Using EDF in single-screen mode . . . . . 530Using EDF in dual-screen mode . . . . . . 531EDF and remote transactions . . . . . . . 531EDF and non-terminal transactions . . . . . 532EDF and DTP programs . . . . . . . . 532EDF and distributed program link commands 533Stopping EDF . . . . . . . . . . . . 533Overtyping to make changes . . . . . . . 533Restrictions when using EDF . . . . . . . 535

Security considerations . . . . . . . . . . 536

Chapter 42. Temporary storage browse(CEBR) . . . . . . . . . . . . . . 537How to use the CEBR transaction . . . . . . 537What does the CEBR transaction display? . . . 539

The header . . . . . . . . . . . . . 539The command area . . . . . . . . . . 539The body . . . . . . . . . . . . . 539

The message line. . . . . . . . . . . 539The CEBR options on function keys. . . . . 540

The CEBR commands . . . . . . . . . . 541Using the CEBR transaction with transient data 543Security considerations . . . . . . . . . . 544

Chapter 43. Command-level interpreter(CECI) . . . . . . . . . . . . . . . 545How to use CECI . . . . . . . . . . . . 545What does CECI display? . . . . . . . . . 546

The command line . . . . . . . . . . 546The status line. . . . . . . . . . . . 547The body . . . . . . . . . . . . . 550The message line. . . . . . . . . . . 551CECI options on function keys . . . . . . 551

Additional displays . . . . . . . . . . . 552Expanded area . . . . . . . . . . . 552Variables . . . . . . . . . . . . . 552The EXEC interface block (EIB) . . . . . . 554Error messages display . . . . . . . . . 555

Making changes . . . . . . . . . . . . 556How CECI runs . . . . . . . . . . . . 556

CECI sessions. . . . . . . . . . . . 556Abends . . . . . . . . . . . . . . 557Exception conditions . . . . . . . . . . 557Program control commands . . . . . . . 557Terminal sharing . . . . . . . . . . . 557Saving commands . . . . . . . . . . 558

Security considerations . . . . . . . . . . 559

Part 8. Appendixes . . . . . . . .561

Appendix A. CICS commands and theirequivalent obsolete macros . . . . . 563

Appendix B. OS/VS COBOL . . . . . 567Translator options. . . . . . . . . . . . 567Programming restrictions . . . . . . . . . 567

Restricted OS/VS COBOL language statements 569Base locator for linkage. . . . . . . . . 569BLL and chained storage areas . . . . . . 570BLL and OCCURS DEPENDING ON clauses 571BLL and large storage areas . . . . . . . 572SERVICE RELOAD statement . . . . . . 573NOTRUNC compiler option . . . . . . . 574Program segments . . . . . . . . . . 574

Converting to VS COBOL II . . . . . . . . 575Based addressing . . . . . . . . . . 575Artificial assignments . . . . . . . . . 577

Bibliography . . . . . . . . . . . . . 577

Index . . . . . . . . . . . . . . . 579

Sending your comments to IBM. . . . 591

Contents ix

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

NoticesThis information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the users responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply in the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore this statement may not applyto you.

This publication could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

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

Copyright IBM Corp. 1989, 1999 xi

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Programming License Agreement, or any equivalent agreementbetween us.

Programming Interface informationThis book is intended to help you learn about application programming techniquesfor CICS applications. This book documents General-use Programming Interfaceand Associated Guidance Information provided by CICS.

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

Trademarks

The following terms are trademarks of International Business MachinesCorporation in the United States, or other countries, or both:

BookManager DFSMS MVS/ESAC/370 eNetwork OS/2C/MVS ESA/390 OS/390CICS GDDM OpenEditionCICS/400 Hiperbatch Parallel SysplexCICS/6000 IBM RACFCICS/ESA IBMLink System/36CICS/MVS IMS System/38COBOL/370 IMS/ESA System/390CUA InfoWindow VisualAgeDATABASE 2 Language Environment VTAMDB2

UNIX is a registered trademark in the United States and other countries licensedexclusively through X/Open Company Limited.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Other company, product, and service names may be trademarks or service marksof others.

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

Preface

What this book is about

This book gives guidance about the CICS application programming interface; itcomplements the reference information in the CICS Application ProgrammingReference manual. For guidance information on debugging CICS applications, seethe CICS Problem Determination Guide.

Who should read this bookThis book is mainly for experienced application programmers. Those who arerelatively new to CICS should be able to understand it. If you are a systemprogrammer 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, andknow about CICS application programming at the CICS Application ProgrammingPrimer (VS COBOL II) level, or you must be able to program in Java.

How to use this book

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

Notes on terminologyAPI refers to the CICS command-level application programming interface

unless otherwise stated.

ASM is sometimes used as the abbreviation for assembler language.

MVS refers to the operating system, which can be either an element of OS/390,or MVS/Enterprise System Architecture System Product (MVS/ESA SP).

VTAMrefers to ACF/VTAM.

In the sample programs described in this book, the dollar symbol ($) is used as anational currency symbol and is assumed to be assigned the EBCDIC code pointX5B. In some countries a different currency symbol, for example the poundsymbol (), or the yen symbol (), is assigned the same EBCDIC code point. Inthese countries, the appropriate currency symbol should be used instead of thedollar symbol.

What is not covered in this book

Guidance for usage of the CICS Front End Programming Interface is not discussedin this book. See the CICS Front End Programming Interface Users Guide forbackground information about FEPI design considerations and programminginformation about its API.

Copyright IBM Corp. 1989, 1999 xiii

|||

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

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

||

BibliographyCICS Transaction Server for OS/390

CICS Transaction Server for OS/390: Planning for Installation GC33-1789CICS Transaction Server for OS/390 Release Guide GC34-5352CICS Transaction Server for OS/390 Migration Guide GC34-5353CICS Transaction Server for OS/390 Installation Guide GC33-1681CICS Transaction Server for OS/390 Program Directory GI10-2506CICS Transaction Server for OS/390 Licensed Program Specification GC33-1707

CICS books for CICS Transaction Server for OS/390General

CICS Master Index SC33-1704CICS Users Handbook SX33-6104CICS Transaction Server for OS/390 Glossary (softcopy only) GC33-1705

AdministrationCICS System Definition Guide SC33-1682CICS Customization Guide SC33-1683CICS Resource Definition Guide SC33-1684CICS Operations and Utilities Guide SC33-1685CICS Supplied Transactions SC33-1686

ProgrammingCICS Application Programming Guide SC33-1687CICS Application Programming Reference SC33-1688CICS System Programming Reference SC33-1689CICS Front End Programming Interface Users Guide SC33-1692CICS C++ OO Class Libraries SC34-5455CICS Distributed Transaction Programming Guide SC33-1691CICS Business Transaction Services SC34-5268

DiagnosisCICS Problem Determination Guide GC33-1693CICS Messages and Codes GC33-1694CICS Diagnosis Reference LY33-6088CICS Data Areas LY33-6089CICS Trace Entries SC34-5446CICS Supplementary Data Areas LY33-6090

CommunicationCICS Intercommunication Guide SC33-1695CICS Family: Interproduct Communication SC33-0824CICS Family: Communicating from CICS on System/390 SC33-1697CICS External Interfaces Guide SC33-1944CICS Internet Guide SC34-5445

Special topicsCICS Recovery and Restart Guide SC33-1698CICS Performance Guide SC33-1699CICS IMS Database Control Guide SC33-1700CICS RACF Security Guide SC33-1701CICS Shared Data Tables Guide SC33-1702CICS Transaction Affinities Utility Guide SC33-1777CICS DB2 Guide SC33-1939

Copyright IBM Corp. 1989, 1999 xv

CICSPlex SM books for CICS Transaction Server for OS/390General

CICSPlex SM Master Index SC33-1812CICSPlex SM Concepts and Planning GC33-0786CICSPlex SM User Interface Guide SC33-0788CICSPlex SM View Commands Reference Summary SX33-6099

Administration and ManagementCICSPlex SM Administration SC34-5401CICSPlex SM Operations Views Reference SC33-0789CICSPlex SM Monitor Views Reference SC34-5402CICSPlex SM Managing Workloads SC33-1807CICSPlex SM Managing Resource Usage SC33-1808CICSPlex SM Managing Business Applications SC33-1809

ProgrammingCICSPlex SM Application Programming Guide SC34-5457CICSPlex SM Application Programming Reference SC34-5458

DiagnosisCICSPlex SM Resource Tables Reference SC33-1220CICSPlex SM Messages and Codes GC33-0790CICSPlex SM Problem Determination GC33-0791

Other CICS booksCICS Application Programming Primer (VS COBOL II) SC33-0674CICS Application Migration Aid Guide SC33-0768CICS Family: API Structure SC33-1007CICS Family: Client/Server Programming SC33-1435CICS Family: General Information GC33-0155CICS 4.1 Sample Applications Guide SC33-1173CICS/ESA 3.3 XRF Guide SC33-0661

If you have any questions about the CICS Transaction Server for OS/390 library,see CICS Transaction Server for OS/390: Planning for Installation which discusses bothhardcopy and softcopy books and the ways that the books can be ordered.

Books from related libraries

DL/IIf you use the CICS-DL/I interface, see the following manuals:

IMS/ESA V5 Application Programming: Design Guide, SC26-8016IMS/ESA V3.1 Application Programming: CICS, SC26-8018IMS/ESA V3.1 Application Programming: DL/I Calls, SC26-4274IMS/ESA V3.1 Database Administration Guide, SC26-4281

MVSFor information about MVS, see the following manuals:

VS COBOL II V1.4.0 Installation and Customization for MVS, SC26-4048OS/390 MVS Programming: Extended Addressability Guide, GC28-1769

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

DB2

For information about executing SQL in a CICS application program, see thefollowing manuals:

IBM Database 2 V2.3 Application Programming and SQL Guide, SC26-4377IBM Database 2 V2.3 DB2 Administration Guide, SC26-4 374IBM Database 2 V2.3 SQL Reference, SC26-4380

The guide describes DB2 and explains how to write application programs thataccess DB2 data in a CICS environment. It tells you how to use SQL, as well ashow to prepare, execute, and test an application program.

Screen definition facility II (SDF II)For information about Screen Definition Facility II, see the following manuals:

Screen Definition Facility II General Information, GH19-6114.Screen Definition Facility II General Introduction Part 1, SH19-8128Screen Definition Facility II General Introduction Part 2, SH19-8129Screen Definition Facility II Primer for CICS/BMS Programs SH19-6118.Screen Definition Facility II Preparing a Prototype, SH19-6458

Common programming interfaceFor information about the SAA interface, see the following manuals:

SAA CPI-C Reference, SC09-1308Common Programming Interface Communications Reference, SC26-4399SAA Common Programming Interface for Resource Recovery Reference, SC31-6821

Common user accessFor information about screens that conform to the CUA standard, see the followingmanuals:

SAA: Common User Access. Basic Interface Design Guide, SC26-4583SAA: Common User Access. Advanced Interface Design Guide, SC26-4582

Programming languagesFor information on programming in VS COBOL II, see the following manuals:

VS COBOL II V1.4 Application Programming: Language Reference, GC26-4047VS COBOL II V1.4 Application Programming Guide, SC26-4045VS COBOL II Usage in a CICS/ESA and CICS/MVS Environment, GG24-3509VS COBOL II V1.4 Application Programming Debugging, SC26-4049VS COBOL II Installation and Customization Guide for MVS, SC26-4048

For information on programming in COBOL/370, see the following manuals:COBOL/370 General Information, GC26-4762COBOL/370 Programming Guide, SC26-4767COBOL/370 Language Reference, SC26-4769COBOL/370 Planning and Customization, ST00-9734

Bibliography xvii

For information on programming in COBOL for MVS and VM, see the followingmanuals:

COBOL for MVS and VM Installation, SC26-4766COBOL for MVS and VM Programming Guide, SC26-4767

For information on programming in C, see the following manuals:C/C++ for MVS V3.1 C/MVS Language Reference, SC09-2063C/C++ for MVS V3.1 C/MVS Users Guide, SC09-2061C/MVS Programming Guide, SC09-2062C/MVS Reference and Summary, SX09-1303

For information on programming in C++, see the following manuals:C++/MVS Language Reference, SC09-1992C++/MVS Users Guide, SC09-1993C++/MVS Programming Guide, SC09-1994

For information on programming in PL/I, see the following manuals:OS PL/I Programming V2.3: Language Reference, SC26-4308OS PL/I Optimizing Compiler Programmers Guide, SC33-0006PL/I MVS & VM Programming Guide, SC26-3113

For information on programming in assembler language, see the followingmanuals:

Assembler H Version 2 Application Programming Guide, SC26-4036Assembler H Version 2 Application Programming Language Reference, GC26-4037

Teleprocessing Network Simulator (TPNS)TPNS General Information, GH20-2487TPNS Language Reference, SH20-2489

Distributed Processing Programming Executive (DPPX):DPPX/370 Users Guide, SC33-0665

Language Environment:Language Environment V1.4 Concepts Guide, GC26-4786Language Environment V1.5 Programming Guide, SC26-4818Language Environment V1.5 Debugging and Run-Time Messages, SC26-4829

Miscellaneous books2780 Data Transmission Terminal: Component Description, GA27-30058775 Display Terminal: Terminal Users Guide, GA33-3045IBM InfoWindow 3471 and 3472 Introduction and Installation Planning Guide,GA18-29423270 Information Display System Data Stream Programmers Reference, GA23-00593290 Information Display Panel Description and Reference, GA23-00218775 Display Terminal Component Description, GA33-3044IBM CICS/ESA 3.3 3270 Data Stream Device Guide, SC33-0232

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

Determining if a publication is currentIBM regularly updates its publications with new and changed information. Whenfirst published, both hardcopy and BookManager softcopy versions of a publicationare usually in step. However, due to the time required to print and distributehardcopy books, the BookManager version is more likely to have had last-minutechanges made to it before publication.

Subsequent updates will probably be available in softcopy before they are availablein hardcopy. This means that at any time from the availability of a release, softcopyversions should be regarded as the most up-to-date.

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

Updates to the softcopy are clearly marked by revision codes (usually a #character) to the left of the changes.

Bibliography xix

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

Summary of ChangesChanges for this CICS Transaction Server for OS/390 Release 3 edition

Significant changes for this edition are indicated by vertical lines to the left of thechanges.v The addition of the JCICS Java classes to access CICS services from Java

application programs. See The JCICS Java classes on page 67

v Support for running CICS Java programs using the VisualAge for Java,Enterprise ToolKit for OS/390. See Chapter 10. Support for VisualAge for Java,Enterprise ToolKit for OS/390 on page 87.

v Support for running CICS Java programs using the CICS Java Virtual Machine(JVM). See Chapter 11. Using the CICS Java virtual machine on page 97.

v The addition of sysplex-wide ENQ and DEQ. See Using ENQ and DEQcommands with ENQMODEL resource definitions on page 158.

v The addition of support for coupling facility data tables (CFDT). See Couplingfacility data tables on page 254.

v Support for named counter servers. See Chapter 16. Using named counterservers on page 195.

v Support for documents, and the EXEC CICS DOCUMENT commands. SeeChapter 15. Using CICS documents on page 185.

v The programming considerations section has been reorganized into separatechapters for each supported language, including new chapters for OO and Javasupport in CICS.

Changes for this CICS Transaction Server for OS/390 Release 2 editionSignificant changes for this edition are indicated by vertical lines to the left of thechanges.v The enhancement of the BMS map definition macros to build an Application

Data Structure (ADS) descriptor record in the mapset. See ADS Descriptor onpage 330.

v The addition of the MAPPINGDEV option (by APAR) that is specified on theRECEIVE MAP and SEND MAP commands to allow you to perform mappingoperations for a device that is not the principal facility. See The MAPPINGDEVfacility on page 362.

Changes for the CICS Transaction Server for OS/390 Release 1 editionv The addition of support for the COBOL for MVS and VM (release 1 and 2)

compiler. See COBOL3 translator option on page 41.

v The addition of support for object-oriented COBOL. See OO COBOL translatoroption on page 41.

v The addition of support for VSAM record-level sharing. See Accessing files inRLS mode on page 252.

Copyright IBM Corp. 1989, 1999 xxi

||||

v The addition of support for resource definition online for transient data. SeeChapter 37. Transient data control on page 495.

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

Part 1. Getting startedChapter 1. Preparing your application to run 3Writing CICS programs . . . . . . . . . . 3Preparing your program. . . . . . . . . . 4Locale support . . . . . . . . . . . . . 5The translation process . . . . . . . . . . 6Specifying translator options . . . . . . . . 7Translator options. . . . . . . . . . . . 8Preparing BMS maps . . . . . . . . . . 19

Chapter 2. Programming in COBOL . . . . . 21Based addressing . . . . . . . . . . . 21

WITH DEBUGGING MODE . . . . . . . 22Restrictions . . . . . . . . . . . . . 22Restrictions for 31-bit addressing . . . . . 24DL/I CALL interface . . . . . . . . . . 24

Mixing languages . . . . . . . . . . . . 25Calling subprograms from COBOL . . . . . . 26COBOL with the ANSI 85 COBOL standards . . . 30Literals intervening in blank lines. . . . . . . 31

Translator action . . . . . . . . . . . 31Sequence numbers containing any character . . 31

Translator action . . . . . . . . . . . 31REPLACE statement . . . . . . . . . . 32

Translator action . . . . . . . . . . . 32Batch compilation. . . . . . . . . . . . 32

Translator action . . . . . . . . . . . 32Compiler and linkage editor . . . . . . . 32

Nested programs . . . . . . . . . . . . 35Translator action . . . . . . . . . . . 35

Recognition of nested programs . . . . . 35Positioning of comments . . . . . . . 36Nestingwhat the application programmermust do . . . . . . . . . . . . . 36An example of a nested program . . . . 37

Reference modification . . . . . . . . . . 38Translator action . . . . . . . . . . . 39

Global variables . . . . . . . . . . . . 39Translator action . . . . . . . . . . . 39

Comma and semicolon as delimiters . . . . . 39Translator action . . . . . . . . . . . 39

Symbolic character definition . . . . . . . . 39Translator action . . . . . . . . . . . 40

Summary of restrictions. . . . . . . . . . 40COBOL2 translator option . . . . . . . . . 40

Translator action . . . . . . . . . . . 41COBOL3 translator option . . . . . . . . . 41

Translator action . . . . . . . . . . . 41OO COBOL translator option . . . . . . . . 41

Translator action . . . . . . . . . . . 42Nesting programs. . . . . . . . . . . 42

Chapter 3. Programming in C and C++ . . . . 43Data declarations needed for C and C++ . . . . 44Naming EIB fields. . . . . . . . . . . . 44

Data types in EIB fields . . . . . . . . . 44Restrictions . . . . . . . . . . . . . . 45

Passing values as arguments . . . . . . . 46ADDRESS EIB command . . . . . . . . 48ADDRESS COMMAREA command . . . . . 48

C++ considerations . . . . . . . . . . . 49Restrictions . . . . . . . . . . . . . 49

Chapter 4. Programming in PL/I . . . . . . 51Restrictions . . . . . . . . . . . . . . 51PL/I STAE execution-time option . . . . . . . 52OPTIONS(MAIN) specification . . . . . . . 52Program segments . . . . . . . . . . . 52PL/I and dynamic storage . . . . . . . . . 52

Chapter 5. Programming in Assembler . . . . 55Compilers supported. . . . . . . . . . . 55Restrictions for 31-bit addressing . . . . . . 55MVS restrictions . . . . . . . . . . . . 55

Invoking assembler language applicationprograms with a call . . . . . . . . . . 56

Chapter 6. Language Environment . . . . . 59Levels of support in Language Environment . . . 59Abend handling in an LE environment . . . . . 60Defining run-time options . . . . . . . . . 60

Copyright IBM Corp. 1989, 1999 1

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

Chapter 1. Preparing your application to runThis chapter describes what you need to do to make your application run in aCICS environment.v Writing CICS programsv Preparing your program on page 4v The translation process on page 6v Specifying translator options on page 7v Translator options on page 8v Preparing BMS maps on page 19

Writing CICS programsYou 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 towrite CICS application programs. Most of the processing logic is expressed instandard language statements, but you use CICS commands, or the Java and C++class libraries to request CICS services.

Other chapters in this book tell you the functions that CICS provides and indicateby example how CICS commands are written. However, you may need to consultthe following sources for detailed descriptions of the CICS commands:v The CICS Application Programming Reference manual for information about

programming CICS commands, including the full list of options associated witheach command and the exact syntax

v The CICS C++ OO Class Libraries manual for information about the CICS C++classes

v The Javadoc HTML shipped in dfjcics_docs.zip for information about the JCICSJava classes

v The CICS Internet Guide for information about writing Web applications toprocess HTTP/1.0 requests and responses.

There are a few restrictions on normal language use under CICS and these aredescribed in Chapter 2. Programming in COBOL on page 21, Chapter 3.Programming in C and C++ on page 43, Chapter 4. Programming in PL/I onpage 51, and Chapter 8. Programming in Java on page 67.

CICS allows you to use SQL statements, DLI requests, CPI statements, and theCICS Front End Programming Interface (FEPI) commands in your program as wellas 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)

Copyright IBM Corp. 1989, 1999 3

|

||||||||||

Preparing your programBecause the compilers (and assemblers) cannot process CICS commands directly,an additional step is needed to convert your program into executable code. Thisstep is called translation, and consists of converting CICS commands into thelanguage in which the rest of the program is coded, so that the compiler (orassembler) can understand them.

Java programs that use the VisualAge for Java, Enterprise ToolKit for OS/390do not need to be processed by a CICS translator.

CICS provides a translator program for each of the other languages in which youmay write, to handle both EXEC CICS and EXEC DLI statements. There are threesteps: translation, compilation (assembly), and link-edit. Figure 1 shows theprocess.

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

SYSIN(sourceprogram)

Command-levellanguagetranslator SYSPUNCH(translated

sourceprogram)

Objectmodule

SYSPRINT(translatorlisting)

Loadlibrary

CICSTranslation

Compilation(assembly)

Link Edit

High-levellanguagecompiler(or assembler)

High-levellanguagecompiler (orassembler)listing

Link-editorLink-editorlisting

Figure 1. Preparing an application program


||

CICS provides a procedure to execute these steps in sequence for each of thelanguages it supports. The CICS System Definition Guide describes how to use theseprocedures, and exactly what they do. Consequently, the additional translation stephas little effect on what you do as a programmer. There are a few points to note,however:

v You can specify a number of options for the translation process, and you mayneed to do this for certain types of programs. If you are using EXEC DLI, forexample, you need to tell the translator this fact. Specifying translator optionson page 7 explains how to specify options, and Translator options on page 8

defines the options available.

v The translator may produce error messages, and it is as important to check thesemessages as it is to check the messages produced by the compiler andlink-editor. See The translation process on page 6 for the location of thesemessages.

v The compiler (or assembler) reads the translated version of your program asinput, rather than your original source. This affects what you see on yourcompiler (assembler) listing. It also means that COPY statements in your sourcecode must not bring in untranslated CICS commands, because it is too late forthe translator to convert them. (Copying in pretranslated code is possible, butnot recommended; it may produce unpredictable results.)

v EXEC commands are translated into CALL statements that invoke CICS interfacemodules. These modules get incorporated into your object module in thelink-edit step, and you see them in your link-edit output listing. You can readmore about these modules in the CICS System Definition Guide.

Locale supportThe translator, by default, assumes that programs written in the C language havebeen edited with the codeset IBM-1047, also known as the Coded Character Set forLatin 1/Open Systems.

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

For example, if the program has been prepared with an editor using the codesetspecific 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 theIBM C for MVS/ESA compiler.

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

Table 1. C language codesetsCharacter IBM-1047 IBM-273

\ backslash E0 EC

} right brace D0 DC

{ left brace C0 43

# hash 7B 7B

Chapter 1. Preparing your application to run 5

||

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

The translation processA language translator reads your source program and creates a new one; normallanguage statements remain unchanged, but CICS commands are translated intoCALL statements of the form required by the language in which you are coding.The calls invoke CICS-provided EXEC interface modules, which later getlink-edited into your load module, and these in turn invoke the requested servicesat execution time.

Java programs that use the VisualAge for Java, Enterprise ToolKit for OS/390 donot need to be processed by a CICS translator. The translators for all of the otherlanguages 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 maximumrecord length that the data set can possess is 80 bytes. Passing a fixedblocked data set with a record length of greater than 80 bytes to thetranslator results in termination of translator execution. If the SYSIN file isdefined as a variable blocked data set, the maximum record length that thedata set can possess is 100 bytes. Passing a variable blocked data set with arecord length greater than 100 bytes to the translator causes the translatorto stop with an error.

SYSPUNCH(Translated source) is the translated version of your source code, whichbecomes the input to the compile (assemble) step. In this file, your sourcehas 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.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 ascomments only. Generally the non-CICS statements are unchanged. Theoutput from the translator always goes to an 80 byte fixed-record lengthdata set.

SYSPRINT(Translator listing) shows the number of messages produced by thetranslator, and the highest severity code associated with any message. Theoptions used in translating your program also appear, unless these havebeen suppressed with the NOOPTIONS option.

For COBOL, C, C++, and PL/I programs, SYSPRINT also contains themessages themselves. In addition, if you specify the SOURCE option of thetranslator, you also get an annotated listing of the source in SYSPRINT.This listing contains almost the same information as the subsequentcompilation listing, and therefore many installations elect to omit it (theNOSOURCE option). One item you may need from this listing which isnot present in the compile listing, however, is the line numbers, if thetranslator is assigning them. Line numbers are one way to indicate pointsin the code when you debug with the execution diagnostic facility (EDF). Ifyou 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 analternative to the source listing for EDF purposes.

For assembler language programs, SYSPRINT contains only the translatoroptions, the message count and maximum severity code. The messagesthemselves are inserted into the SYSPUNCH file as comments after therelated statement. This causes the assembler to copy them through to theassembler listing, where you can check them. You may also see MNOTEsthat are generated by the assembler as the result of problems encounteredby the translator.

Specifying translator optionsThe translator options you can choose are listed in Translator options on page 8.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:

LanguageStatement

COBOLCBL

COBOLPROCESS (with LE)

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 forthe translate step. Most installations use catalogued procedures to translate,compile (assemble) and link CICS programs, and therefore you specify thisPARM 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 fora 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 thatconflicts by the other method, the specifications in the language statement overridethose in the EXEC statement. Similarly, if you specify multiple values for a singleoption or options that conflict on either type of statement, the last setting takesprecedence. Except for COBOL programs translated with the ANSI85 option, thesestatements must precede each source program; there is no way to batch theprocessing of multiple programs in other languages.

Translator options may appear in any order, separated by one or more blanks or bya comma. If you specify them on the language statement for options, they mustappear in parentheses following the XOPTS parameter, because other options areignored by the translator and passed through to the compiler. The followingCOBOL example shows both translator and compiler options being passedtogether:


||

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)

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 aretranslator options. However, you may use XOPTS, with or without its associatedparentheses. If you use XOPTS with parentheses, be sure to enclose all of thetranslator 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 analternative to XOPTS, except when you are translating batch EXEC DLI programs.)Remember, if you alter the default margins for C or C++ #PRAGMA cardprocessing 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 cancontain translator or assembler options for the High Level assembler, HLASM.Translator and assembler options must not coexist on the same *PROCESSstatement. *PROCESS and *ASM statements must be at the beginning of theinput and no assembler statements must appear before them. This includescomments and statements such as PRINT ON and EJECT. Both *PROCESSand *ASM statements can be included, in any order. *PROCESS statementscontaining only translator options are retained by the translator; *PROCESSstatements containing assembler options are placed in the translated program.

Translator optionsYou can specify the translator options that apply to all languages except wherestated otherwise. Table 2 on page 18 lists all the translator options, the programlanguages that apply, and any valid abbreviations.

If your installation uses the CICS-provided procedures in the distributed form, thedefault options are the ones that are underlined or explicitly noted. Manyinstallations change the defaults, however. You can tell which options get used bydefault at your installation by looking at the SYSPRINT translator listing outputfrom the translate step (see The translation process on page 6). If you want anoption that is not the default, you must specify it, as described in Specifyingtranslator options on page 7.

Note: Translator options for programs to be compiled with OS/VS COBOL aredescribed in Appendix B. OS/VS COBOL on page 567. OS/VS COBOL issupported for migration purposes to enable you to maintain existingprograms. You are not recommended to write new applications usingOS/VS COBOL.


|

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

||||||

ANSI85(COBOL only)

specifies that the translator is to translate COBOL programs that implement theANSI85 standards.

Note: This option causes the COBOL2 and NOSEQ options to be used, even ifyou have specified SEQ. ANSI85 is implied by either OOCOBOL orCOBOL3 options.

APOST(COBOL only)

indicates that literals are delineated by the apostrophe (). This is thedefaultQUOTE is the alternative. The same value must be specified for thetranslator step and the following compiler step.

The CICS-supplied COBOL copybooks use APOST.

CBLCARD(COBOL only)

specifies that the translator is to generate a CBL statement. This is thedefaultthe alternative is NOCBLCARD.

CICSspecifies that the translator is to process EXEC CICS commands. It is thedefault specification in the translator. CICS is also an old name for the XOPTSkeyword for specifying translator options, which means that you can specifythe CICS option explicitly either by including it in your XOPTS list or by usingit in place of XOPTS to name the list. The only way to indicate that there areno 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. Forexample, 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 APIcommands, specify:CBL XOPTS(EXCI)

COBOL2(COBOL only)

specifies that the translator is to translate programs compiled by the VSCOBOL II (or later) compilers.

COBOL3(COBOL only)

specifies that the translator is to translate programs compiled by theCOBOL/370 or COBOL for MVS and VM compilers. This option implies theANSI85 and COBOL2 options.

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


|

CPSMspecifies that the translator is to process EXEC CPSM commands. Thealternative is NOCPSM, which is the default.

DBCS(COBOL only)

specifies that the source program may contain double-byte characters. It causesthe translator to treat hexadecimal codes X'0E' and X'0F' as shift-out (SO) andshift-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 ApplicationProgramming: Language Reference manual.

If you specify this option, the COBOL2 option is assumed.

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

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

DLIspecifies that the translator is to process EXEC DLI commands. You mustspecify it with the XOPTS option, that is, XOPTS(DLI).

EDFspecifies that the execution diagnostic facility is to apply to the program. EDFis the defaultthe alternative is NOEDF.

EPILOG(Assembler language only)

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

EPILOG is the defaultthe alternative, NOEPILOG, prevents the translatorinserting the macro DFHEIRET. (See the CICS Application Programming Referencemanual for programming information about the DFHEIRET macro.)

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

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

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


FE(COBOL only)

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

FEPIallows access to the FEPI API commands of the CICS Front End ProgrammingInterface (FEPI). FEPI is only available if you have installed the CICS FrontEnd Programming Interface. The alternative is NOFEPI. FEPI commands anddesign are not discussed in this book, but are discussed in the CICS Front EndProgramming Interface Users Guide.

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

specifies the minimum severity of error in the translation which requires amessage to be listed.

I All messages.

W (Default) All except information messages.

E All except warning and information messages.

S Only severe and unrecoverable error messages.

Note: The FE option overrides the FLAG option.

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

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

GRAPHIC(PL/I only)

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

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

If the compiler you are using supports DBCS, you need to prevent unintendedshift-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 itdoes not create them, or by specifying NOGRAPHIC on the compile step, sothat the compiler does not interpret them as DBCS delimiters.


For more detailed information about how to program in PL/I using DBCS, seethe PL/I Programming: Language Reference manual.

LENGTH(COBOL, Assembler and PL/I only)

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

LINECOUNT(n)Abbreviation: LC

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 therange 1 through 255; if n is less than 5, only the heading and one line oflisting are included on each page. The default is 60.

LINKAGE(COBOL only)

requests the translator to modify the LINKAGE SECTION and PROCEDUREDIVISION statements in top-level programs according to the existing rules.

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

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

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

The option can also specify the position of an American National Standardprinter control character to format the listing produced when the SOURCEoption is specified; otherwise, the input records are listed without anyintervening blank lines. The margin parameters are:

m Column number of left-hand margin.

n Column number of right-hand margin. It must be greater than m.

Note: When used as a C or C++ compiler option, the asterisk (*) isallowable for the second argument on the MARGIN option. Forthe translator, however, a numeric value between 1 and 100inclusive must be specified. When the input data set hasfixed-length records, the maximum value allowable for the righthand margin is 80. When the input data set has variable-lengthrecords, the maximum value allowable is 100.

c Column number of the American National Standard printer controlcharacter. 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 thefollowing 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, andfor variable-length records it is the same as the record length (1,recordlength,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)specifies what language is to be used for the translator message output:

EN (Default) English.

KA Kanji.

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

NOCBLCARD(COBOL only)

specifies that the translator is not to generate a CBL statement. The parameterswhich the CICS translator normally inserts must be set using VS COBOL IIsIGYCOPT macro. These parameters are RENT, RES, NODYNAM, and LIB.

NOCPSMspecifies that the translator is not to process EXEC CPSM commands. This isthe defaultthe alternative is CPSM.

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

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

NOEDFspecifies that the execution diagnostic facility is not to apply to the program.There is no performance advantage in specifying NOEDF, but the option canbe useful to prevent commands in well-debugged subprograms appearing onEDF displays.

NOEPILOG(Assembler language only)

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


NOFE(COBOL only)

does not produce translator information messages that print the bit patterncorresponding to the first argument of the translated call. NOFE is thedefaultthe alternative is FE.

NOFEPIdisallows access to the FEPI API commands of the CICS Front EndProgramming Interface (FEPI). NOFEPI is the defaultthe alternative is FEPI.

NOLENGTH(COBOL, Assembler and PL/I only)

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

NOLINKAGE(COBOL only) requests the translator not to modify the LINKAGE SECTIONand PROCEDURE DIVISION statements to supply missing DFHEIBLK andDFHCOMMAREA statements.

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

LINKAGE is the default.

NONUM(COBOL only)

instructs the translator not to use the line numbers appearing in columns onethrough six of each line of the program as the line number in its diagnosticmessages 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

specifies the position of the sequence field in the translator output records. Thedefault for C and C++ is OPSEQUENCE(73,80) for fixed-length records andNOOPSEQUENCE for variable-length records. For PL/I, the default isOPSEQUENCE(73,80) for both types of records.

NOOPTIONSAbbreviation: NOP

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

NOPROLOG(Assembler language only)

instructs the translator not to insert the macros DFHEISTG, DFHEIEND, andDFHEIENT into the program being assembled. These macros define localprogram storage and initialize at program entry. (See the CICS ApplicationProgramming Reference manual for programming information about theseprolog macros.)


|||||

NOSEQ(COBOL only)

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 astatement is not in sequence, it is flagged.

If you specify the ANSI85 option for COBOL, the translator does no sequencechecking and the SEQ or NOSEQ option is ignored.

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

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

The default for fixed-length records is SEQUENCE(73,80). For variable-lengthrecords in C and C++, the default is NOSEQUENCE and for variable-lengthrecords in PL/I the default is SEQUENCE(1,8).

NOSOURCE(C, C++ and PL/I only)

instructs the translator not to include a listing of the translated source programin the translator listing.

NOSPIEprevents the translator from trapping irrecoverable errors; instead, a dump isproduced. You should use NOSPIE only when requested to do so by the IBMsupport center.

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

instructs the translator not to include a cross-reference of commands with linenumbers in the translator listing. (NOVBREF used to be called NOXREF; forcompatibility, NOXREF is still accepted.) NOVBREF is the defaultthealternative is VBREF.

NUM(COBOL only)

instructs the translator to use the line numbers appearing in columns onethrough six of each line of the program as the line number in its diagnosticmessages and cross-reference listing. The alternative is NONUM, which is thedefault.

OOCOBOL(OO COBOL only)

instructs the translator to recognize the object-oriented COBOL (OO COBOL)syntax. The phrases:

v CLASS-ID xxx...xxxv END CLASS xxx...xxxv METHOD-ID xxx...xxxv END METHOD xxx...xxx


are recognized but their correct usage is not monitored. The translatorconsiders each class as a separate unit of compilation. This option implies theANSI85, COBOL2, and COBOL3 options.

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

specifies the translator output margins, that is, the margins of the input to thefollowing compiler. Normal

CICS Application Programming Guide

Documents

Transcript of CICS Application Programming Guide