CICS Application Guide

CICS Transaction Server for z/OSVersion 4 Release 1

Application Programming Guide

SC34-7022-03

NoteBefore using this information and the product it supports, read the information in Notices on page 807.

This edition applies to Version 4 Release 1 of CICS Transaction Server for z/OS (product number 5655-S97) and toall subsequent releases and modifications until otherwise indicated in new editions.

Copyright IBM Corporation 1989, 2012.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsPreface . . . . . . . . . . . . . . xiiiWhat this manual is about . . . . . . . . . xiii

Who should read this manual . . . . . . . xiii

Changes in CICS Transaction Serverfor z/OS, Version 4 Release 1 . . . . . xv

Part 1. Writing CICS applications . . 1

Chapter 1. Overview: Writing CICSApplications . . . . . . . . . . . . . 3What is a CICS application? . . . . . . . . . 3CICS programs, transactions and tasks. . . . . . 3CICS programming . . . . . . . . . . . . 4CICS programming commands . . . . . . . . 5EXEC interface block (EIB). . . . . . . . . . 5Translation . . . . . . . . . . . . . . . 5Testing for CICS . . . . . . . . . . . . . 6CICS programming roadmap . . . . . . . . . 6

Part 2. Programming languages andLanguage Environment . . . . . . . 9

Chapter 2. Language Environment . . . 11Language Environment callable services . . . . . 12Language Environment abend and conditionhandling . . . . . . . . . . . . . . . 13Language Environment storage . . . . . . . . 15Mixing languages in Language Environment . . . 15Dynamic Link Libraries (DLLs) . . . . . . . . 17Defining runtime options for LanguageEnvironment . . . . . . . . . . . . . . 18

CEEBXITA and CEECSTX user exits . . . . . 20CICSVAR, CICS environment variable . . . . 21

CEEBINT exit for Language Environment . . . . 22

Chapter 3. Programming in COBOL . . 23COBOL programming restrictions and requirements 24

Language Environment CBLPSHPOP option . . 27Using the DL/I CALL interface. . . . . . . 27

VS COBOL II programs . . . . . . . . . . 28Using based addressing with COBOL. . . . . . 29Calling subprograms from COBOL programs . . . 30

Flow of control between programs andsubprograms . . . . . . . . . . . . . 31Rules for calling subprograms . . . . . . . 33

COBOL2 and COBOL3 translator options . . . . 35CICS translator actions for COBOL programs . . . 36Batch compilation for COBOL programs . . . . . 39Nested COBOL programs. . . . . . . . . . 41Upgrading OS/VS COBOL programs . . . . . . 44

Chapter 4. Programming in C and C++ 49C and C++ programming restrictions andrequirements . . . . . . . . . . . . . . 50Passing arguments in C and C++ . . . . . . . 54Accessing the EIB from C and C++ . . . . . . 55Locale support for C and C++ . . . . . . . . 56XPLink and C and C++ programming . . . . . 56

XPLink uses X8 and X9 mode TCBs . . . . . 57Passing control between XPLink and non-XPLinkobjects . . . . . . . . . . . . . . . 57Global user exits and XPLink . . . . . . . 57

Chapter 5. Programming in PL/I . . . . 59PL/I programming restrictions and requirements . . 59Language Environment coding requirements forPL/I applications . . . . . . . . . . . . 60Fetched PL/I routines . . . . . . . . . . . 62

Chapter 6. Programming in assemblerlanguage . . . . . . . . . . . . . . 65Assembler language programming restrictions andrequirements . . . . . . . . . . . . . . 65Language Environment coding requirements forassembler language applications . . . . . . . 66Calling assembler language programs . . . . . 69

Part 3. Translating, compiling,installing and testing applicationprograms . . . . . . . . . . . . . 73

Chapter 7. Translation and compilation 75The integrated CICS translator . . . . . . . . 75

Using the integrated CICS translator . . . . . 76Specifying CICS translator options. . . . . . 76

The translation process . . . . . . . . . . 77The CICS-supplied translators . . . . . . . . 80

Dynamic invocation of the separate translator . . 80Using a CICS translator . . . . . . . . . . 81Defining translator options . . . . . . . . . 83

Translator options . . . . . . . . . . . 83Translator options table . . . . . . . . . 93

Using COPY statements . . . . . . . . . . 95The CICS-supplied interface modules. . . . . . 95

The EXEC interface modules . . . . . . . 95The CPI Communications interface module. . . 95The SAA Resource Recovery interface module . . 96

Using the EXEC interface modules . . . . . . 96COBOL. . . . . . . . . . . . . . . 97PL/I. . . . . . . . . . . . . . . . 97C and C++ . . . . . . . . . . . . . 98Assembler language . . . . . . . . . . 98EXAMPLE Assembler language PROGRAMusing LEASM . . . . . . . . . . . . 99

Copyright IBM Corp. 1989, 2012 iii

Chapter 8. Installing applicationprograms . . . . . . . . . . . . . 103Program installation steps . . . . . . . . . 103Using dynamic program LIBRARY resources . . . 104

Examples of using dynamic LIBRARY resources 105Defining MVS residence and addressing modes . . 114

Establishing a program's addressing mode. . . 114CICS address space considerations . . . . . 115Making programs permanently resident . . . 115

Running applications in the link pack area . . . 116Running application programs in the RDSAs . . . 116

Assembler . . . . . . . . . . . . . 116C and C/++ . . . . . . . . . . . . . 117COBOL . . . . . . . . . . . . . . 118PL/I . . . . . . . . . . . . . . . 118

Using BMS map sets in application programs. . . 119Using the CICS-supplied procedures to installapplication programs . . . . . . . . . . . 120

Installing programs in load library secondaryextents . . . . . . . . . . . . . . 121

Including the CICS-supplied interface modules . . 121Installing assembler language application programs 122Installing COBOL application programs . . . . 123

Sample JCL to install COBOL applicationprograms . . . . . . . . . . . . . . 124

Installing PL/I application programs . . . . . 127Sample JCL to install PL/I application programs 127PL/I procedure with an integrated translator 128

Installing C application programs . . . . . . 129Sample JCL to install C application programs 131

Using your own job streams . . . . . . . . 133Translator requirements . . . . . . . . . 133Online programs that use EXEC CICS or EXECDLI commands . . . . . . . . . . . . 133Online programs that use the CALL DLIinterface . . . . . . . . . . . . . . 136Batch or BMP programs that use EXEC DLIcommands . . . . . . . . . . . . . 136Batch or BMP programs that use DL/I CALLcommands . . . . . . . . . . . . . 136

Chapter 9. Installing map sets andpartition sets . . . . . . . . . . . 137Installing map sets . . . . . . . . . . . 138

Types of map sets . . . . . . . . . . . 138Installing physical map sets . . . . . . . 140Installing symbolic description map sets . . . 141Installing physical and symbolic descriptionmaps together . . . . . . . . . . . . 143

Installing partition sets . . . . . . . . . . 146Defining programs, map sets, and partition sets toCICS . . . . . . . . . . . . . . . . 147

Chapter 10. Testing applications . . . 149Preparing the application for testing. . . . . . 150Preparing the system for testing . . . . . . . 150

Chapter 11. Execution diagnosticfacility (EDF). . . . . . . . . . . . 153Restrictions when using EDF . . . . . . . . 154

OPEN TCBs and EDF . . . . . . . . . 156Parameter list stacking . . . . . . . . . 156Security considerations . . . . . . . . . 156

What does EDF display? . . . . . . . . . 156The header . . . . . . . . . . . . . 157The body . . . . . . . . . . . . . . 157

Using EDF . . . . . . . . . . . . . . 164Interrupting program execution . . . . . . 164Using EDF in single-screen mode. . . . . . 165Using EDF in dual-screen mode . . . . . . 167EDF and remote transactions . . . . . . . 167EDF and non-terminal transactions . . . . . 167EDF and DTP programs . . . . . . . . . 168Stopping EDF . . . . . . . . . . . . 168

Overtyping to make changes . . . . . . . . 169EDF responses . . . . . . . . . . . . 170

Using EDF menu functions . . . . . . . . . 171

Chapter 12. Temporary storagebrowse (CEBR) . . . . . . . . . . 177Using the CEBR transaction . . . . . . . . 177What does the CEBR transaction display? . . . . 179

The header . . . . . . . . . . . . . 179The command area . . . . . . . . . . 179The body . . . . . . . . . . . . . . 179The message line . . . . . . . . . . . 179

Using the CEBR function keys. . . . . . . . 180Using the CEBR commands . . . . . . . . 181Using the CEBR transaction with transient data 183

Chapter 13. Command-levelinterpreter (CECI). . . . . . . . . . 185What does CECI display? . . . . . . . . . 185

The command line . . . . . . . . . . 185The status line . . . . . . . . . . . . 186The body . . . . . . . . . . . . . . 189The message line . . . . . . . . . . . 189CECI options on function keys . . . . . . 190

Using CECI . . . . . . . . . . . . . . 190Making changes . . . . . . . . . . . 191

Using the CECI function keys . . . . . . . . 192Expanded area . . . . . . . . . . . . 192Variables . . . . . . . . . . . . . . 192The EXEC interface block (EIB) . . . . . . 194Error messages display . . . . . . . . . 194

Saving commands . . . . . . . . . . . . 195How CECI runs . . . . . . . . . . . . 196

CECI sessions . . . . . . . . . . . . 196Abends . . . . . . . . . . . . . . 196Exception conditions . . . . . . . . . . 197Program control commands . . . . . . . 197Terminal sharing . . . . . . . . . . . 197Shared storage: ENQ commands withoutLENGTH option . . . . . . . . . . . 197

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

Chapter 14. Preparing to usedebuggers with CICS applications . . 199Debugging profiles . . . . . . . . . . . 200Using debugging profiles to select programs fordebugging . . . . . . . . . . . . . . 201Using generic parameters in debugging profiles 203

Chapter 15. Debugging CICSapplications from a workstation . . . 205Preparing to debug applications from aworkstation . . . . . . . . . . . . . . 205

Chapter 16. Using Debug Tool withCICS applications . . . . . . . . . 207About Debug Tool. . . . . . . . . . . . 207Preparing to debug applications with Debug Tool 207

Part 4. CICS applicationprogramming techniques . . . . . 209

Chapter 17. Application design . . . . 211Pseudoconversational and conversational design 211

Terminal interruptibility . . . . . . . . . 213How tasks are started . . . . . . . . . . 213Which transaction? . . . . . . . . . . . 215Separating business and presentation logic . . . 218Multithreading: Reentrant, quasi-reentrant andthreadsafe programs . . . . . . . . . . . 219

Quasi-reentrant application programs . . . . 219Threadsafe programs . . . . . . . . . . 220OPENAPI programs . . . . . . . . . . 225Using the FORCEQR system initializationparameter . . . . . . . . . . . . . 229Non-reentrant programs . . . . . . . . . 229

Storing data within a transaction . . . . . . . 230Transaction work area (TWA) . . . . . . . 230User storage . . . . . . . . . . . . . 231COMMAREA in LINK and XCTL commands 231Channels in LINK and XCTL commands . . . 232Program storage . . . . . . . . . . . 232Temporary storage . . . . . . . . . . 232Intrapartition transient data . . . . . . . 234GETMAIN SHARED command . . . . . . 234Your own data sets . . . . . . . . . . 235

Lengths of areas passed to CICS commands . . . 235LENGTH options . . . . . . . . . . . 235Journal records . . . . . . . . . . . . 235Data set definitions . . . . . . . . . . 235Recommendation . . . . . . . . . . . 236

Minimizing errors . . . . . . . . . . . . 236Protecting CICS from application errors . . . 236Testing applications . . . . . . . . . . 236

Non-terminal transaction security . . . . . . 237

Chapter 18. Design for performance 239Program size . . . . . . . . . . . . . 239Virtual storage . . . . . . . . . . . . . 240

Reducing paging effects . . . . . . . . . 241

Exclusive control of resources . . . . . . . . 243Operational control . . . . . . . . . . . 244Operating system waits . . . . . . . . . . 245The NOSUSPEND option . . . . . . . . . 245Efficient sequential data set access . . . . . . 246Efficient logging . . . . . . . . . . . . 247

Chapter 19. Sharing data acrosstransactions . . . . . . . . . . . . 249Using the common work area (CWA) . . . . . 249

Protecting the CWA . . . . . . . . . . 250Using the TCTTE user area (TCTUA) . . . . . 253Using the COMMAREA in RETURN commands 253Using a channel on RETURN commands . . . . 254Using the display screen to share data . . . . . 254

Chapter 20. Enhanced inter-programdata transfer: channels asmodern-day COMMAREAs . . . . . . 257Channels: quick start . . . . . . . . . . . 257

Containers and channels. . . . . . . . . 257Basic examples . . . . . . . . . . . . 258

Using channels: some typical scenarios . . . . . 260One channel, one program . . . . . . . . 260One channel, several programs (a component) 261Several channels, one component . . . . . . 261Multiple interactive components . . . . . . 262

Creating a channel . . . . . . . . . . . 263The current channel . . . . . . . . . . . 264

Current channel example, with LINK commands 264Current channel example, with XCTLcommands . . . . . . . . . . . . . 266Current channel: START and RETURNcommands . . . . . . . . . . . . . 267

The scope of a channel . . . . . . . . . . 268Scope example, with LINK commands . . . . 268Scope example, with LINK and XCTLcommands . . . . . . . . . . . . . 270

Discovering which containers were passed to aprogram . . . . . . . . . . . . . . . 272Discovering which containers were returned from alink. . . . . . . . . . . . . . . . . 272CICS read only containers . . . . . . . . . 272Designing a channel: best practices . . . . . . 273Constructing and using a channel: an example . . 274Channels and BTS activities . . . . . . . . 275

Context . . . . . . . . . . . . . . 276Using channels from JCICS . . . . . . . . . 277Dynamic routing with channels . . . . . . . 277Data conversion . . . . . . . . . . . . 278

Why is data conversion needed? . . . . . . 278Preparing for code page conversion withchannels . . . . . . . . . . . . . . 278Data conversion with channels . . . . . . 280

Benefits of channels . . . . . . . . . . . 284Migrating from COMMAREAs to channels . . . 285

Migrating LINK commands that passCOMMAREAs . . . . . . . . . . . . 286Migrating XCTL commands that passCOMMAREAs . . . . . . . . . . . . 286

Contents v

Migrating pseudoconversational COMMAREAson RETURN commands . . . . . . . . . 287Migrating START data . . . . . . . . . 287Migrating programs that use temporary storageto pass data . . . . . . . . . . . . . 288Migrating dynamically-routed applications . . 288

Chapter 21. Program control . . . . . 291Program linking . . . . . . . . . . . . 292

Application program logical levels . . . . . 292Link to another program expecting return . . . 292

Passing data to other programs . . . . . . . 293COMMAREA . . . . . . . . . . . . 293Channels . . . . . . . . . . . . . . 295INPUTMSG . . . . . . . . . . . . . 295

Using mixed addressing modes . . . . . . . 297Using LINK to pass data . . . . . . . . . 298Using RETURN to pass data . . . . . . . . 299

Chapter 22. Affinity . . . . . . . . . 303Types of affinity . . . . . . . . . . . . 303

Inter-transaction affinity . . . . . . . . . 304Transaction-system affinity . . . . . . . . 304

Programming techniques and affinity . . . . . 304Safe techniques . . . . . . . . . . . . 305Unsafe techniques . . . . . . . . . . . 305Suspect techniques . . . . . . . . . . 306Recommendations . . . . . . . . . . . 306

Programming techniques that avoid affinity . . . 306The COMMAREA . . . . . . . . . . . 307The TCTUA . . . . . . . . . . . . . 308Using ENQ and DEQ commands withENQMODEL resource definitions. . . . . . 309BTS containers . . . . . . . . . . . . 311

Programming techniques that create affinities. . . 311Using the common work area . . . . . . . 311Using GETMAIN SHARED storage . . . . . 312Using the LOAD PROGRAM HOLD command 313Sharing task-lifetime storage . . . . . . . 314Using the WAIT EVENT command . . . . . 316Using ENQ and DEQ commands withoutENQMODEL resource definitions. . . . . . 317

Programming techniques that might createaffinities . . . . . . . . . . . . . . . 317

Using temporary storage . . . . . . . . 318Using transient data . . . . . . . . . . 320Using the RETRIEVE WAIT and STARTcommands . . . . . . . . . . . . . 321Using the START and CANCEL REQIDcommands . . . . . . . . . . . . . 323Using the DELAY and CANCEL REQIDcommands . . . . . . . . . . . . . 325Using the POST and CANCEL REQIDcommands . . . . . . . . . . . . . 326

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

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

Chapter 23. Recovery design. . . . . 337Journaling . . . . . . . . . . . . . . 337

Journal records . . . . . . . . . . . . 337Journal output synchronization . . . . . . 337

Syncpointing . . . . . . . . . . . . . 339

Chapter 24. Dealing with exceptionconditions. . . . . . . . . . . . . 343Default CICS exception handling . . . . . . . 343Handling exception conditions by in-line code . . 344

How to use the RESP and RESP2 options . . . 344An example of exception handling in C . . . 345An example of exception handling in COBOL 346

Modifying default CICS exception handling . . . 347Using the HANDLE CONDITION command . . . 349

RESP and NOHANDLE options . . . . . . 349How CICS keeps track of what to do . . . . 350

Using the HANDLE CONDITION ERRORcommand . . . . . . . . . . . . . . 351Using the IGNORE CONDITION command . . . 351Using the HANDLE ABEND command . . . . 352Using PUSH HANDLE and POP HANDLEcommands . . . . . . . . . . . . . . 353

Chapter 25. Abnormal terminationrecovery . . . . . . . . . . . . . 355Creating a program-level abend exit . . . . . . 356Retrying operations . . . . . . . . . . . 357Trace . . . . . . . . . . . . . . . . 358

Trace entry points . . . . . . . . . . . 359Monitoring application performance. . . . . . 359Dump . . . . . . . . . . . . . . . . 360

Chapter 26. The QUERY SECURITYcommand . . . . . . . . . . . . . 363Using the QUERY SECURITY command . . . . 363

Security protection at the record or field level 363CICS-defined resource identifiers . . . . . . 364SEC system initialization parameter . . . . . 364Programming hints . . . . . . . . . . 364

Chapter 27. CICS intercommunication 365Design considerations . . . . . . . . . . 365

Programming language . . . . . . . . . 366Transaction routing . . . . . . . . . . . 366Function shipping . . . . . . . . . . . . 366Distributed program link (DPL) . . . . . . . 367

Using the distributed program link function . . 368Examples of distributed program link . . . . 369Programming considerations for distributedprogram link . . . . . . . . . . . . 374

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

Part 5. Data mappings . . . . . . 381

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

||

Chapter 28. Mapping and transformingapplication data and XML . . . . . . 383The CICS XML assistant . . . . . . . . . . 383

DFHLS2SC: high-level language to XML schemaconversion . . . . . . . . . . . . . 384DFHSC2LS: XML schema to high-level languageconversion . . . . . . . . . . . . . 390Mapping levels for the CICS assistants . . . . 398High-level language and XML schema mapping 402Variable arrays of elements . . . . . . . . 429Support for XML attributes . . . . . . . . 433Support for and xsd:anyType . . . 436Support for . . . . . . . . 438Support for . . . . . . . 440Support for substitution groups . . . . . . 440Support for abstract elements and abstract datatypes . . . . . . . . . . . . . . . 441How to handle variably repeating content inCOBOL . . . . . . . . . . . . . . 443Support for variable-length values and whitespace . . . . . . . . . . . . . . . 446

Generating mappings from language structures . . 449Generating mappings from an XML schema . . . 451Transforming application data to XML . . . . . 453Transforming XML to application data . . . . . 454Querying XML from an application . . . . . . 455Handling XML by data type . . . . . . . . 456Handling data types . . . . . . . 457Validating XML transformations . . . . . . . 458

Part 6. Business services andbundles . . . . . . . . . . . . . 459

Chapter 29. Creating businessservices from CICS applications . . . 461Service Component Architecture (SCA) . . . . . 461SCA composites and wiring . . . . . . . . 462Best practices for creating and deployingcomposites . . . . . . . . . . . . . . 464Creating a channel-based service . . . . . . . 465Creating an XML-based service . . . . . . . 467CICS processing of services. . . . . . . . . 468Troubleshooting SCA problems . . . . . . . 470

Chapter 30. Creating user resourcetypes in bundles . . . . . . . . . . 471The bundle registration interface . . . . . . . 471

Writing a registration program . . . . . . 472Containers used in the registration interface . . 472

Writing a callback program. . . . . . . . . 475Containers used in the callback interface . . . . 477

DFHRL-CONTROL container . . . . . . . 477DFHRL-DATA container. . . . . . . . . 478DFHRL-NAME container . . . . . . . . 478DFHRL-ROOT container . . . . . . . . 478DFHRL-TYPE container . . . . . . . . . 478

The bundle manifest schema . . . . . . . . 478The SCA composite schema . . . . . . . . 480

Part 7. File control . . . . . . . . 481

Chapter 31. Understanding file control 483VSAM data sets: KSDS, ESDS, RRDS . . . . . 483

Empty data sets . . . . . . . . . . . 484VSAM alternate indexes . . . . . . . . . 485Accessing files in RLS mode . . . . . . . 485

Identifying VSAM records . . . . . . . . . 486Key . . . . . . . . . . . . . . . 486Relative record number (RRN), relative byteaddress (RBA) and extended relative byteaddress (XRBA) . . . . . . . . . . . 487

Upgrading to extended addressing for ESDS . . . 488Locking of VSAM records in recoverable files . . 490

Update locks and delete locks (non-RLS modeonly) . . . . . . . . . . . . . . . 490

RLS Record level locking . . . . . . . . . 491Exclusive locks and shared locks . . . . . . 491Lock duration . . . . . . . . . . . . 492Active and retained states for locks . . . . . 492

BDAM data sets . . . . . . . . . . . . 493Identifying BDAM records . . . . . . . . 494

CICS shared data tables . . . . . . . . . . 496Coupling facility data tables . . . . . . . . 497Techniques for sharing data . . . . . . . . 499Transaction deadlocks . . . . . . . . . . 501

VSAM-detected deadlocks (RLS only) . . . . 503Rules for avoiding deadlocks . . . . . . . 503

Chapter 32. File control operations 505Using CICS commands to read records . . . . . 505

Direct reading (using READ command) . . . 505Sequential reading (browsing) . . . . . . . 508Browsing records from BDAM data sets . . . 511Skip-sequential processing . . . . . . . . 512

Using CICS commands to update records . . . . 512The TOKEN option . . . . . . . . . . 514Conditional VSAM file update requests . . . 514Updating records from BDAM data sets . . . 515

Using CICS commands to delete records . . . . 515Updating and deleting records in a browse (VSAMRLS only) . . . . . . . . . . . . . . 516

Locks for UPDATE . . . . . . . . . . 516Using CICS commands to add records . . . . . 517

CICS locking for writing to ESDS. . . . . . 518Adding records to BDAM data sets . . . . . 518

Efficient data set operations . . . . . . . . 519VSAM data sets . . . . . . . . . . . 519BDAM data sets . . . . . . . . . . . 520Efficient browsing (in non-RLS mode) . . . . 521

Part 8. Terminal control . . . . . . 523

Chapter 33. Terminal access methodsupport . . . . . . . . . . . . . . 525

Chapter 34. Terminal controlcommands . . . . . . . . . . . . 527Send/receive mode . . . . . . . . . . . 527

Contents vii

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

|||

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

Contention for the terminal. . . . . . . . 528RETURN IMMEDIATE . . . . . . . . . 528

Speaking out of turn . . . . . . . . . . . 528Interrupting . . . . . . . . . . . . . . 529Terminal waits . . . . . . . . . . . . . 529

Chapter 35. Using data transmissioncommands . . . . . . . . . . . . 531What you get on a RECEIVE . . . . . . . . 531

Input chaining . . . . . . . . . . . . 531Logical messages . . . . . . . . . . . 532NOTRUNCATE option . . . . . . . . . 532Print key . . . . . . . . . . . . . . 532

Chapter 36. Device control commands 533

Chapter 37. Terminal device support 535

Chapter 38. Finding out about yourterminal . . . . . . . . . . . . . . 539EIB feedback on terminal control operations . . . 540

Chapter 39. Using VTAM. . . . . . . 543Chaining input data . . . . . . . . . . . 543Chaining output data. . . . . . . . . . . 543Handling logical records. . . . . . . . . . 544Response protocol . . . . . . . . . . . . 544Using function management headers . . . . . 545

Inbound FMH . . . . . . . . . . . . 545Outbound FMH . . . . . . . . . . . 545

Preventing interruptions (bracket protocol) . . . 545

Chapter 40. Using sequential terminalsupport . . . . . . . . . . . . . . 547Coding considerations for sequential terminals . . 547

Print formatting . . . . . . . . . . . 548GOODNIGHT convention . . . . . . . . 548

Chapter 41. Using TCAM . . . . . . 549Coding for the TCAM/DCB interface . . . . . 549

Chapter 42. Using batch datainterchange . . . . . . . . . . . . 551

Chapter 43. Terminal control: designfor performance . . . . . . . . . . 555

Chapter 44. The 3270 family ofterminals . . . . . . . . . . . . . 557The 3270 buffer. . . . . . . . . . . . . 557The output datastream . . . . . . . . . . 557

3270 write commands . . . . . . . . . 5583270 display fields. . . . . . . . . . . . 559

Display characteristics . . . . . . . . . 5593270 field attributes . . . . . . . . . . . 560

Protection . . . . . . . . . . . . . 560Modification. . . . . . . . . . . . . 561

Intensity . . . . . . . . . . . . . . 561Base color . . . . . . . . . . . . . 561Extended attributes . . . . . . . . . . 562

Orders in the data stream . . . . . . . . . 562The start field order . . . . . . . . . . 563The modify field order . . . . . . . . . 563The set buffer address order . . . . . . . 564The set attribute order . . . . . . . . . 565

Outbound data stream sample. . . . . . . . 565Input from a 3270 terminal . . . . . . . . . 567

Data keys . . . . . . . . . . . . . 568Keyboard control keys . . . . . . . . . 568Attention keys . . . . . . . . . . . . 568

Reading from a 3270 terminal . . . . . . . . 569Inbound field format . . . . . . . . . . . 570Input data stream example . . . . . . . . . 570Unformatted mode . . . . . . . . . . . 571

Part 9. Interval control and taskcontrol . . . . . . . . . . . . . . 573

Chapter 45. Interval control . . . . . 575Expiration times . . . . . . . . . . . . 576Request identifiers. . . . . . . . . . . . 577

Chapter 46. Task control . . . . . . 579Controlling sequence of access to resources . . . 580

Part 10. Storage protection andtransaction isolation . . . . . . . 583

Chapter 47. CICS storage protectionand transaction isolation . . . . . . 585Storage control . . . . . . . . . . . . . 585Storage protection . . . . . . . . . . . . 586

Storage categories . . . . . . . . . . . 587Transaction isolation . . . . . . . . . . . 588

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

Defining the storage key for applications . . . . 589System-wide storage areas . . . . . . . . 589Task lifetime storage . . . . . . . . . . 589Program working storage specifically for exitand PLT programs. . . . . . . . . . . 590Passing data by a COMMAREA . . . . . . 590The GETMAIN command . . . . . . . . 590

Selecting the execution and storage key . . . . 591User-key applications. . . . . . . . . . 592CICS-key applications . . . . . . . . . 593

Using transaction isolation . . . . . . . . . 595MVS subspaces . . . . . . . . . . . . . 597

Subspaces and basespaces for transactions. . . 597The common subspace and shared storage . . 598

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

Part 11. Transient data andtemporary storage . . . . . . . . 601

Chapter 48. Transient data control 603Intrapartition transient data queues . . . . . . 603Extrapartition queues. . . . . . . . . . . 604Indirect queues . . . . . . . . . . . . . 605Automatic transaction initiation (ATI) . . . . . 605

Chapter 49. Temporary storagecontrol . . . . . . . . . . . . . . 607Temporary storage queues . . . . . . . . . 607Typical uses of temporary storage control . . . . 608

Part 12. CICS documents . . . . . 611

Chapter 50. Introduction todocuments and document templates . 613Symbols and symbol lists . . . . . . . . . 614Caching and refreshing of document templates . . 617Code page conversion for documents . . . . . 618

Chapter 51. Setting up documenttemplates . . . . . . . . . . . . . 621Templates in a partitioned data set . . . . . . 621Templates in z/OS UNIX System Services files . . 621Templates in CICS files, temporary storage, ortransient data . . . . . . . . . . . . . 622Templates in CICS programs . . . . . . . . 623

DFHDHTL - program template prolog andepilog macro . . . . . . . . . . . . 624

Templates in exit programs . . . . . . . . . 625Communication area for templates in exitprograms . . . . . . . . . . . . . . 625

Using symbols in document templates . . . . . 627Embedded template commands . . . . . . . 628

Chapter 52. Programming withdocuments and document templates . 631Creating a document . . . . . . . . . . . 631Defining symbol values . . . . . . . . . . 632Rules for specifying symbols and symbol lists . . 634Adding more data to a document . . . . . . 637Replacing data in a document . . . . . . . . 638Retrieving, storing and reusing a document . . . 639Deleting a document . . . . . . . . . . . 642

Part 13. Named counter servers 643

Chapter 53. Overview: Named counterservers . . . . . . . . . . . . . . 645The named counter fields . . . . . . . . . 645Named counter pools. . . . . . . . . . . 646

Named counter options table . . . . . . . 646

Chapter 54. Using the named counterEXEC interface. . . . . . . . . . . 649

Chapter 55. Using the named counterCALL interface . . . . . . . . . . . 651Application programming considerations . . . . 651Syntax. . . . . . . . . . . . . . . . 652

Checking for result overflow . . . . . . . 659Example of DFHNCTR calls with nullparameters . . . . . . . . . . . . . 659

Return codes . . . . . . . . . . . . . 660

Chapter 56. Named counter recovery 665

Part 14. Printing and spool files 667

Chapter 57. CICS support for printing 669Formatting for CICS printers . . . . . . . . 669Requests for printed output . . . . . . . . 670CICS 3270 printers . . . . . . . . . . . 670CICS 3270 printer options . . . . . . . . . 671

PRINT option and print control bit . . . . . 672ERASE option . . . . . . . . . . . . 672Line width options: L40, L64, L80, andHONEOM . . . . . . . . . . . . . 672NLEOM option. . . . . . . . . . . . 673FORMFEED . . . . . . . . . . . . . 674PRINTERCOMP option . . . . . . . . . 674

Non-3270 CICS printers . . . . . . . . . . 674SCS input . . . . . . . . . . . . . 675

Chapter 58. Using printers with CICS 677Determining the characteristics of a CICS printer 677

BMS page size, 3270 printers . . . . . . . 677Supporting multiple printer types . . . . . 678

Using CICS printers . . . . . . . . . . . 678Printing with a START command. . . . . . 679Printing with transient data . . . . . . . 679Printing with BMS routing . . . . . . . . 680

Using Non-CICS printers . . . . . . . . . 681Formatting for non-CICS printers. . . . . . 681Non-CICS printers: Delivering the data. . . . 681Programming for non-CICS printers . . . . . 681Notifying the print application . . . . . . 683

Printing display screens . . . . . . . . . . 683CICS print key . . . . . . . . . . . . 684ISSUE PRINT and ISSUE COPY . . . . . . 684Hardware print key . . . . . . . . . . 684BMS screen copy . . . . . . . . . . . 685

Chapter 59. CICS interface to JES . . 687Using the CICS interface to JES . . . . . . . 688

Spool interface restrictions . . . . . . . . 689Creating output spool files . . . . . . . . . 689

Using the MVS internal reader . . . . . . 690Reading input spool files . . . . . . . . . 690

JES exits . . . . . . . . . . . . . . 691Identifying spool files . . . . . . . . . . 691Examples of SPOOL commands . . . . . . . 694

Contents ix

COBOL . . . . . . . . . . . . . . 694PL/I . . . . . . . . . . . . . . . 695C . . . . . . . . . . . . . . . . 696ASSEMBLER . . . . . . . . . . . . 696

Part 15. Basic Mapping Support(BMS) . . . . . . . . . . . . . . 697Chapter 60. Basic mapping support 699BMS support levels . . . . . . . . . . . 699

Minimum BMS . . . . . . . . . . . . 700Standard BMS . . . . . . . . . . . . 700Full BMS . . . . . . . . . . . . . . 700

A BMS output example . . . . . . . . . . 701

Chapter 61. Creating the map . . . . 705Defining map fields: DFHMDF . . . . . . . 705Defining the map: DFHMDI . . . . . . . . 707Defining the map set: DFHMSD . . . . . . . 708Writing BMS macros . . . . . . . . . . . 709Assembling the map . . . . . . . . . . . 711

Physical and symbolic map sets . . . . . . 711The SDF II alternative . . . . . . . . . 712Grouping maps into map sets . . . . . . . 712The Application Data Structure (ADS) . . . . 712

Using complex fields . . . . . . . . . . . 713Composite fields: the GRPNAME option . . . 714Repeated fields: the OCCURS option . . . . 715

Block data . . . . . . . . . . . . . . 716Support for non-3270 terminals . . . . . . . 716

Output considerations for non-3270 devices . . 717Differences on input . . . . . . . . . . 717Special options for non-3270 terminals . . . . 718

Device-dependent maps . . . . . . . . . . 718Device dependent support: DDS . . . . . . 719Finding out about your terminal . . . . . . 721

Chapter 62. Sending BMS mappedoutput . . . . . . . . . . . . . . 723Acquiring and defining storage for the maps . . . 723

BASE and STORAGE options . . . . . . . 724Initializing the output map . . . . . . . . . 725Moving the variable data to the map . . . . . 725Setting the display characteristics. . . . . . . 725

Changing the attributes . . . . . . . . . 726Attribute value definitions: DFHBMSCA . . . 727

Chapter 63. Using the SEND MAPcommand . . . . . . . . . . . . . 729SEND MAP control options . . . . . . . . 729

Other BMS SEND options: WAIT and LAST . . 730Merging the symbolic and physical maps . . . . 730

MAPONLY option. . . . . . . . . . . 730DATAONLY option . . . . . . . . . . 731The SEND CONTROL command . . . . . . 731

Building the output screen . . . . . . . . . 731What you start with . . . . . . . . . . 732What is sent . . . . . . . . . . . . . 732Where the values come from . . . . . . . 732

Outside the map . . . . . . . . . . . 733Using GDDM and BMS . . . . . . . . . 734

Positioning the cursor . . . . . . . . . . 734Sending invalid data and other errors . . . . . 735Output disposition options: TERMINAL, SET, andPAGING . . . . . . . . . . . . . . . 735

Using SET . . . . . . . . . . . . . 736

Chapter 64. Receiving mapped data 739An input-output example . . . . . . . . . 739

The symbolic input map. . . . . . . . . 741Programming mapped input . . . . . . . . 742Using the RECEIVE MAP command. . . . . . 742Getting storage for mapped input . . . . . . 743Formatted screen input . . . . . . . . . . 743

Modified data . . . . . . . . . . . . 744Upper case translation . . . . . . . . . 744

Using the attention identifier . . . . . . . . 745Using the HANDLE AID command . . . . . 745

Finding the cursor. . . . . . . . . . . . 746Processing the mapped input . . . . . . . . 746Handling input errors . . . . . . . . . . 747

Flagging errors . . . . . . . . . . . . 747Saving the good input . . . . . . . . . 748Rechecking . . . . . . . . . . . . . 748

Sending mapped output after mapped input . . . 749MAPFAIL and other exceptional conditions . . . 750

EOC condition . . . . . . . . . . . . 750Formatting other input . . . . . . . . . . 751

Chapter 65. BMS logical messages 753Building logical messages . . . . . . . . . 753The SEND PAGE command . . . . . . . . 754RETAIN and RELEASE . . . . . . . . . . 754The AUTOPAGE option . . . . . . . . . . 755Terminal operator paging: the CSPG transaction 756Logical message recovery . . . . . . . . . 757

Chapter 66. Cumulative output theACCUM option . . . . . . . . . . . 759Floating maps: how BMS places maps usingACCUM . . . . . . . . . . . . . . . 759Page breaks: BMS overflow processing . . . . . 760Map placement rules . . . . . . . . . . . 761

ASSIGN options for cumulative processing . . 763Input from a composite screen. . . . . . . . 763Performance considerations. . . . . . . . . 763

Minimizing path length . . . . . . . . . 763Reducing message lengths . . . . . . . . 764

Chapter 67. Text output . . . . . . . 767The SEND TEXT command. . . . . . . . . 767

Text logical messages . . . . . . . . . . 767Text pages . . . . . . . . . . . . . . 768Text lines . . . . . . . . . . . . . . . 769Header and trailer format . . . . . . . . . 769SEND TEXT MAPPED and SEND TEXT NOEDIT 770

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

Chapter 68. Message routing. . . . . 773Message destinations . . . . . . . . . . . 773

Eligible terminals . . . . . . . . . . . 774Destinations specified with OPCLASS only . . 774OPCLASS and LIST omitted . . . . . . . 775Route list provided . . . . . . . . . . 775

Route list format . . . . . . . . . . . . 776Message delivery . . . . . . . . . . . . 777

Undeliverable messages . . . . . . . . . 778Recoverable messages . . . . . . . . . . 778

Message identification . . . . . . . . . 779Programming considerations with routing . . . . 779

Routing and page overflow. . . . . . . . 779Routing with SET . . . . . . . . . . . 780Interleaving a conversation with messagerouting . . . . . . . . . . . . . . 780

Chapter 69. The MAPPINGDEV facility 781SEND MAP with the MAPPINGDEV option . . . 781RECEIVE MAP with the MAPPINGDEV option 782Sample assembler MAPPINGDEV application . . 783

Chapter 70. Partition support . . . . 785Uses for partitioned screens . . . . . . . . 786

Scrolling . . . . . . . . . . . . . . 786Data entry . . . . . . . . . . . . . 786Lookaside . . . . . . . . . . . . . 786Data comparison . . . . . . . . . . . 787Error messages . . . . . . . . . . . . 787

Partition definition . . . . . . . . . . . 7873290 character size . . . . . . . . . . 788

Establishing partitioning. . . . . . . . . . 788Partition options for BMS SEND commands . . . 789

Determining the active partition . . . . . . 789Partition options for BMS RECEIVE commands . . 790

ASSIGN options for partitions . . . . . . . 790Partitions and logical messages . . . . . . . 790

Partitions and routing . . . . . . . . . 791Attention identifiers and exception conditions . . 791

Terminal sharing . . . . . . . . . . . . 791

Chapter 71. Support for specialhardware . . . . . . . . . . . . . 793Logical device components . . . . . . . . . 793

Defining logical device components . . . . . 793Sending data to a logical device component . . 794LDCs and logical messages . . . . . . . . 794LDCs and routing . . . . . . . . . . . 794

10/63 magnetic slot reader . . . . . . . . . 795Field selection features . . . . . . . . . . 795

Trigger field support . . . . . . . . . . 795Cursor and pen-detectable fields . . . . . . . 796

Selection fields . . . . . . . . . . . . 797Attention fields. . . . . . . . . . . . 797BMS input from detectable fields . . . . . . 797

Outboard formatting . . . . . . . . . . . 798

Chapter 72. BMS: design forperformance . . . . . . . . . . . . 799Page-building and routing operations . . . . . 802

Part 16. Appendixes . . . . . . . 805

Notices . . . . . . . . . . . . . . 807Trademarks . . . . . . . . . . . . . . 808

Bibliography. . . . . . . . . . . . 809CICS books for CICS Transaction Server for z/OS 809CICSPlex SM books for CICS Transaction Serverfor z/OS . . . . . . . . . . . . . . . 810Other CICS publications . . . . . . . . . . 810Other IBM publications . . . . . . . . . . 810

Accessibility . . . . . . . . . . . . 813

Index . . . . . . . . . . . . . . . 815

Contents xi

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

Preface

What this manual is aboutThis manual documents intended Programming Interfaces that allow the customerto write programs to obtain the services of Version 4 Release 1.

This manual gives guidance about the development of procedural applicationprograms that use the CICS EXEC application programming interface to accessCICS services and resources; it complements the reference information in the CICSApplication Programming Reference manual. For guidance information on debuggingsuch CICS applications, see the CICS Problem Determination Guide. For guidance ondeveloping application programs using the Java language, see Java Applications inCICS, and for guidance on using the CICS OO classes, see CICS C++ OO ClassLibraries.

Who should read this manualThis manual 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 manualYou must be able to program in COBOL, C, C++, PL/I, or assembler language, andhave a basic knowledge of CICS application programming, at the Designing andProgramming CICS Applications level.

How to use this manualRead the parts covering what you need to know. (Each part has a full table ofcontents to help you find what you want.) The manual 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 z/OS ,OS/390, or MVS/Enterprise System Architecture System Product(MVS/ESA SP).

VTAM

refers to ACF/VTAM.

In the sample programs described in this book, the dollar symbol ($) is used as anational currency symbol and is assumed to be assigned the EBCDIC code pointX'5B'. 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.

Copyright IBM Corp. 1989, 2012 xiii

What is not covered in this manualGuidance for usage of the CICS Front End Programming Interface is not discussedin this manual. See the CICS Front End Programming Interface User's Guide forbackground information about FEPI design considerations and programminginformation about its API.

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

Guidance for the use of object oriented programming languages and techniques isnot included in this manual. For guidance on developing application programsusing the Java language, see Java Applications in CICS, and for guidance on usingthe CICS OO classes, see CICS C++ OO Class Libraries.

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

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

For information about changes that have been made in this release, please refer toWhat's New in the information center, or the following publications:v CICS Transaction Server for z/OS What's Newv CICS Transaction Server for z/OS Upgrading from CICS TS Version 3.2v CICS Transaction Server for z/OS Upgrading from CICS TS Version 3.1v CICS Transaction Server for z/OS Upgrading from CICS TS Version 2.3

Any technical changes that are made to the text after release are indicated by avertical bar (|) to the left of each new or changed line of information.

Copyright IBM Corp. 1989, 2012 xv

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

Part 1. Writing CICS applications

Copyright IBM Corp. 1989, 2012 1

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

Chapter 1. Overview: Writing CICS ApplicationsA brief introduction to CICS applications and the procedures for creating programsto run in CICS.

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

CICS is a transaction processing subsystem. That means that it provides servicesfor you to run applications online, by request, at the same time as many otherusers are submitting requests to run the same applications, using the same filesand programs. CICS manages the sharing of resources; integrity of data andprioritization 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 programsthat implement the required function. In CICS documentation you may find CICSapplication programs sometimes called programs, and sometimes the termtransaction is used to imply the processing done by the application programs.

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

CICS programs, transactions and tasksTo develop and run CICS applications, you need to understand the relationshipbetween CICS programs, transactions and tasks.

These terms are used throughout CICS documentation and appear in manycommands:

Transaction

A transaction is a piece of processing initiated by a single request. This isusually from an end-user at a terminal, but may also be made from a Webpage, from a remote workstation program, from an application in anotherCICS system or triggered automatically at a predefined time. The CICSInternet Guide and the CICS External Interfaces Guide describe different waysof 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 eventand all other transactions of the same type. You describe each transactiontype to CICS with a TRANSACTION resource definition. This definitiongives the transaction type a name ( the transaction identifier, or TRANSID)


and tells CICS several things about the work to be done; such as whatprogram to invoke first, and what kind of authentication is requiredthroughout the execution of the transaction.

You run a transaction by submitting its TRANSID to CICS. CICS uses theinformation recorded in the TRANSACTION definition to establish thecorrect execution environment, and starts the first program.

The term transaction is now used extensively in the IT industry to describea unit of recovery or what CICS calls a unit of work. This is typically acomplete operation that is recoverable; it can be committed or backed outas an entirety as a result of programmed command or system failure. Inmany 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 readingnon-CICS documentation.

Task You will also see the term task used extensively in CICS documentation.This term also has a specific meaning in CICS. When CICS receives arequest to run a transaction, it starts a new task that is associated with thisone instance of the execution of the transaction type; that is, one executionof a transaction, with a particular set of data, usually on behalf of aparticular user at a particular terminal. You can also consider it asanalogous to a thread. When the transaction completes, the task ends.

CICS programmingYou write a CICS program in much the same way as you write any other program.You can use COBOL, C, C++, Java, PL/I, or assembler language to write CICSapplication programs. Most of the processing logic is expressed in standardlanguage statements, but you use CICS commands, or the Java and C++ classlibraries to request CICS services.

This information describes the use of the CICS command level programminginterface, EXEC CICS, that can be used in COBOL, C, C++, PL/I or assemblerprograms. These commands are defined in detail in the CICS ApplicationProgramming Reference. The following programming information is also available:v Programming in Java with the JCICS class library is described in Javaprogramming using JCICS in Java Applications in CICS.

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

v For information about writing Web applications to process HTTP requests andresponses, see CICS Web support concepts and structures in the CICS InternetGuide.

For further guidance on language use with CICS, see Chapter 3, Programming inCOBOL, on page 23, Chapter 4, Programming in C and C++, on page 49, andChapter 5, Programming in PL/I, on page 59.

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 aboutthese:v SQL: DB2 Universal Database for z/OS SQL Reference, SC26-9944, and DB2

Universal Database for z/OS Application Programming and SQL Guide, SC26-9933v DL/I: IMS: Application Programming: EXEC DLI Commands for CICS and IMS,SC27-1288,and IMS: Application Programming: Database Manager, SC27-1286


v CPI: IBM SAA: CPI Reference manual and the SAA Common Programming Interfacefor Resource Recovery Reference manual

v FEPI: CICS Front End Programming Interface User's Guide

CICS programming commandsThe 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 interfacewithout any knowledge of, or reference to, the fields in the CICS control blocksand storage areas. However, you might need to get information that is validoutside the local environment of your application program.

You can use ADDRESS and ASSIGN commands to access such information.

When using the ADDRESS and ASSIGN commands, various fields can be read butshould not be set or used in any other way. This means that you should not useany of the CICS fields as arguments in CICS commands, because these fields maybe altered by the EXEC interface modules.

The INQUIRE, SET, and PERFORM commands allow application programs toaccess information about CICS resources. These commands are known as systemprogramming commands. The application program can retrieve and modifyinformation for CICS data sets, terminals, system entries, mode names, systemattributes, programs, and transactions. These commands plus the spool commandsof the CICS interface to JES, are primarily for the use of the system programmer.

EXEC interface block (EIB)In addition to the usual CICS control blocks, each task in a command-levelenvironment 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 EIBcontains information that is useful during the execution of an application program,such as the transaction identifier, the time and date (initially when the task isstarted, and subsequently, if updated by the application program using ASKTIME),and the cursor position on a display device. The EIB also contains information thatis helpful when a dump is used to debug a program. For programminginformation about EIB fields, see the CICS Application Programming Reference.

TranslationMost compilers (and assemblers) cannot process CICS commands directly. Thismeans that an additional step is needed to convert your program into executablecode. This step is called translation, and consists of converting CICS commandsinto 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 CICScommands and convert them automatically to calls to CICS service routines. If youuse one of these compilers, you do not need to perform the translation tasksdescribed in The translation process on page 77.

Chapter 1. Overview: Writing CICS Applications 5

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

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

Testing for CICSAbout this task

Your program can determine whether it is running in CICS in two different ways:

iscicsIf you are adapting an existing C language program or writing a new programthat is designed to run outside CICS as well as under CICS, the C languageiscics() function may prove useful. It returns a non-zero value if your programis currently running under CICS, or zero otherwise. This function is anextension to the C library.

DFH3QSSYour program can call the DFH3QSS program to query the CICS environmentand API capability. Link DFH3QSS statically into your own application. Onreturn, register 15 addresses a result structure that consists of a half-wordlength (that includes itself) followed by a reserved half-word (currently zero)followed by a bit string:

Bit 0 When set to 1, this means that the caller is running in a CICSenvironment (on a CICS-managed TCB or one of its descendants).

Bit 1 When set to 1, this means that the CICS API is available to the caller(in the current PSW key, ASC-mode, AMODE and cross-memoryenvironment).

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

CICS programming roadmapAbout this task

Follow these steps to develop a CICS application that uses the EXEC CICScommand level programming interface:1. Design your application, identifying the CICS resources and services you will

use. See Chapter 17, Application design, on page 211 and Chapter 18, Designfor performance, on page 239 for guidance on designing CICS applications.

2. Write your program in the language of your choice, including EXEC CICScommands to request CICS services. See the CICS Application ProgrammingReference for a list of CICS commands.

3. If you are using a compiler that incorporates The integrated CICS translatoron page 75, you will only need to compile your program, and then install it inCICS, using the process described in Program installation steps on page 103.


Otherwise, you will need to define translator options for your program, usingthe process described in Using a CICS translator on page 81, and thentranslate and compile your program, and install it in CICS, using the processdescribed in Program installation steps on page 103.

4. Define your program and related transaction to CICS with PROGRAM resourcedefinitions and TRANSACTION resource definitions as described in theCICSResource Definition Guide .

5. Define any CICS resources that your program uses, such as files, queues orterminals.

6. Make the resources known to CICS using the CEDA INSTALL commanddescribed in the CICS Resource Definition Guide.

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

Chapter 1. Overview: Writing CICS Applications 7

Part 2. Programming languages and Language EnvironmentInformation for programmers about Language Environment, andlanguage-specific guidance for programming in COBOL, C, PL/I and Assembler.


Chapter 2. Language EnvironmentLanguage Environment, supplied as an element of z/OS, provides a common setof runtime libraries. Before the introduction of Language Environment, each of thehigh-level languages (HLLs) had to provide a separate runtime environment. WithLanguage Environment, you use one runtime environment for your applications,regardless of the programming language or system resource needs, because mostsystem dependencies have been removed.

The runtime libraries provided by Language Environment replace the nativeruntime libraries that were provided with older compilers such as VS COBOL II,OS PL/I and C/370. The common environment offers two significant advantages:1. You can mix all the languages supported by CICS in a single program.2. The same Language Environment callable services are available to all programs.

This means, for example, that:v A linked-list created with storage obtained using Language Environmentcallable services in a PL/I program can be processed later and the storagefreed using the callable services from a COBOL routine.

v The currency symbol to be used on a series of reports can be set in anassembler routine, even though the reports themselves are produced byCOBOL programs.

v System messages from programs written in different languages are all sent tothe same output destination.

See the z/OS Language Environment Concepts Guide for more information. Because ofthese advantages, high-level language support under CICS depends uponLanguage Environment.

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

CICS supports application programs compiled using most of the compilers that aresupported by Language Environment. For a list of compilers that are supported inthis release of CICS Transaction Server for z/OS, see the CICS Transaction Server forz/OS What's New.

Most of the compilers supported by CICS and Language Environment areLanguage Environment-conforming compilers, meaning that programs compiled bythese compilers can take advantage of all Language Environment facilities that areavailable to a CICS region. CICS and Language Environment also supportprograms compiled by some pre-Language Environment compilers (which are notLanguage Environment-conforming). However, CICS does not support all thepre-Language Environment compilers which are supported by LanguageEnvironment.

Applications compiled and linked with pre-Language Environment compilersmight execute successfully using the runtime support provided by LanguageEnvironment. They might not have to be recompiled or re-link-edited. In somecircumstances, you might need to adjust Language Environment runtime optionsto enable these applications to execute correctly. Refer to the z/OS Language


Environment Run-Time Application Migration Guide, and the Compiler and Run-TimeMigration Guide for the language in use, for further information. Becausepre-Language Environment compilers are not Language Environment-conforming,programs compiled by these compilers cannot take advantage of all LanguageEnvironment facilities that are available to a CICS region.

The native runtime libraries provided with pre-Language Environment compilersare not supported. Language libraries, other than the Language Environmentlibraries, should not be present in your CICS startup JCL.

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

CICS Transaction Server for z/OS allows you to produce LanguageEnvironment-conforming assembler MAIN programs. For more information aboutassembler programs, see Chapter 6, Programming in assembler language, onpage 65.

Language Environment callable servicesLanguage Environment provides callable services, which can be accessed byprograms running under CICS.

The callable services provided by Language Environment are classified in thefollowing categories:

Storage servicesThese allow you to allocate and free storage from the Language Environmentheaps.

Error handling servicesThese provide a common method of obtaining information to enable you toprocess errors.

Message servicesThese provide a common method of handling and issuing messages.

Date and timeThese allow you to read, calculate, and write values representing the date andtime. Language Environment offers unique pattern-matching capabilities thatlet you process almost any date and time format contained in an input recordor produced by operating system services.

National language supportThese allow you to customize Language Environment output (such asmessages, RPTOPTS reports, RPTSTG reports, and dumps) for a given country.

LocaleThese allow you to customize culturally-sensitive output for a given nationallanguage, country, and codeset by specifying a locale name.

GeneralThese are a set of callable services that are not directly related to a specificLanguage Environment function, for example, dump.

MathematicalThese allow you to perform standard mathematical computations.


These services are normally only available to programs compiled with LanguageEnvironment-conforming compilers. As an exception, VS COBOL II programs canmake dynamic calls to the date and time callable services, but they cannot makeany other dynamic calls or any static calls to Language Environment callableservices.

For further information about the details of these services, see the z/OS LanguageEnvironment Programming Guide.For information about the syntax required to callany of the services, see the z/OS Language Environment Programming Reference.

Message and dump services

When the Language Environment services CEEMOUT (dispatch a message) andCEE3DMP (generate dump) are running under CICS, both the messages anddumps are sent to a transient data queue called CESE, and not to their usualdestinations.

The usual destinations for Language Environment messages and dumps are theddname specified in the MSGFILE runtime option for messages and the ddnamegiven in the fname argument of the CEE3DMP service for dumps. CICS ignoresboth of these ddnames.

Language Environment abend and condition handlingLanguage Environment abend handling depends on the use of CICS HANDLEABEND. User-written condition handlers can be used when a CICS HANDLEABEND is not active. Language Environment is not involved in the handling ofCICS-defined exception conditions, or in the detection of attention identifiers(AIDs).

Abend handling

When a CICS application is running under Language Environment, the actiontaken when a task is scheduled for abnormal termination depends on whether aCICS HANDLE ABEND is active or not active:v When a HANDLE ABEND is active, the action defined in the CICS HANDLEABEND occurs. Language Environment condition handling does not gain controlfor any abends or program interrupts, and any user-written condition handlersthat are established by CEEHDLR are ignored.

v When a CICS HANDLE ABEND is not active, Language Environment conditionhandling gains control for abends and program interrupts if the runtime optionTRAP(ON) is specified. Normal Language Environment condition handling isthen performed. If TRAP(OFF) is specified, no error handling occurs and theabend proceeds. For details of normal Language Environment conditionhandling, see the z/OS Language Environment Programming Guide.

User-written Language Environment condition handlers

You can use the Language Environment runtime option USRHDLR to register auser-written condition handler at the highest level. At a lower level, for exampleafter a subroutine CALL, you can use the CEEHDLR service to register a conditionhandler for that level. This lower level handler is automatically unregistered onreturn from the lower level. If desired, you can explicitly unregister it by using theCEEHDLU service. For an explanation of stack levels and for details of the

Chapter 2. Language Environment 13

USRHDLR runtime option and the CEEHDLR and CEEHDLU services, see thez/OS Language Environment Programming Guide.

If you create a user-written Language Environment condition handler (other thanin COBOL), you can use most CICS commands, provided that they are coded witha NOHANDLE, RESP or RESP2 option, to prevent further conditions being raisedduring execution of the condition handler. The only commands you cannot use arethe following, which must not appear in either the condition handler or anyprogram it calls:v ABENDv HANDLE ABENDv HANDLE AIDv HANDLE CONDITIONv IGNORE CONDITIONv POP HANDLEv PUSH HANDLE

Unless you use the NOLINKAGE translator option (see NOLINKAGE on page89), do not use the CICS translator to translate a COBOL user-written conditionhandler that you have registered for a routine using the CEEHDLR service. This isbecause the CICS translator adds two extra arguments to the PROCEDUREDIVISION header of the COBOL program, the EXEC Interface Block (EIB) and theCOMMAREA. These arguments do not match the arguments passed by LanguageEnvironment. A COBOL condition handler cannot, therefore, contain any CICScommands.

However, a user-written condition handler can call a subroutine to perform CICScommands (and this could be a COBOL routine). If you need to pass arguments tothis subroutine, place two dummy arguments before them in the caller. The calledsubroutine must issue EXEC CICS ADDRESS EIB(DFHEIPTR) before executing anyother CICS commands.

For an application to use a user-written Language Environment condition handler,the condition handler must be available at runtime (for example by using theSTEPLIB concatenation or LPA). Define such condition handlers in the CICSsystem definition data set (CSD) for your CICS region, rather than using programautoinstall. This includes the sample user-written condition handler CEEWUCHAthat is supplied by Language Environment in the SCEESAMP library.

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

CICS condition and attention identifier (AID) handlingLanguage Environment condition handling does not alter the behavior ofapplications that use CICS HANDLE CONDITION or HANDLE AID commands.Language Environment is not involved in the handling of CICS-defined exceptionconditions, which are raised and handled only by CICS. Similarly, AID detection isa CICS function unaffected by Language Environment.


||||||

Language Environment storageLanguage Environment uses storage obtained from CICS for each run-unit. Wheneach program is first used, Language Environment tells CICS how much storagethe run unit work area (RUWA) requires. The allocation of storage depends on thesetting of the CICS system initialization parameter, RUWAPOOL.

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

If you specify RUWAPOOL=YES, the first run of a transaction is the same as withRUWAPOOL=NO, but CICS keeps a history of the total storage for RUWAs that isrequested to run the transaction. This means that when the transaction is runagain, CICS issues a single GETMAIN for the total storage (and a singleFREEMAIN at task end), creating a RUWAPOOL. If the transaction follows thesame path, CICS allocates the storage from the RUWAPOOL, and no furtherGETMAIN has to be issued. If more storage is required for RUWAs because ofdifferent or extra CICS links, CICS issues a GETMAIN and updates the history, sothat next time the single GETMAIN (and FREEMAIN) is for the larger amount. Fortransactions that issue a large number of CICS LINK commands, the performanceimprovement can be considerable.

If you specify the CICS system initialization parameter AUTODST=YES, CICSindicates to Language Environment that it is able to support dynamic storagetuning.

If a program specifies a runtime option of ALL31(OFF) and Language Environmentneeds to use storage below the 16MB line, two areas of storage are allocated, onebelow 16MB and one above the 16MB line.

If necessary, any application can obtain CICSDATAKEY or USERDATAKEY storageby using a CICS GETMAIN command. However, a program with an EXECKEY ofUSER cannot use CICSDATAKEY storage.

Mixing languages in Language EnvironmentLanguage Environment enables you to build an application that is composed ofprograms that have been written in different high-level source languages, andassembler language.

Assembler language subroutines called from an HLL program are fairlystraightforward and not uncommon. A subroutine called from one HLL but writtenin another needs much more careful consideration and involves interlanguagecommunication (ILC). Language Environment defines an ILC application as onebuilt of two or more HLLs and, optionally, assembler language. See z/OS LanguageEnvironment Writing Interlanguage Communication Applications for full information onthis subject.

Language Environment dictates that if there is any ILC within a run unit underCICS, each compile unit must be compiled with a Language Environment-conforming compiler. CICS supports three HLLs: C/C++, COBOL, and PL/I. Weconsider the interfaces in pairs. If your application contains only two HLLs, consult


the appropriate section. If your application contains all three HLLs, consult thosesections corresponding to each of the interfaces within your application.

C/C++ and COBOL

The conditions under which Language Environment supports ILC betweenroutines 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 acompiler option.

v Whether the call is static or dynamic.v Whether the function being invoked is within the module or exported from aDLL.

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 z/OS Language Environment WritingInterlanguage Communication Applications. Consult this book if your applicationmixes C/C++ and COBOL.

C/C++ and PL/I

Under CICS, if all the components of your C/C++ and PL/I application arereentrant, Language Environment supports ILC between routines compiled byC/C++ and PL/I as follows:v C/C++ routines can statically call PL/I routines and PL/I routines can staticallycall 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++ mustpass the EIB and the COMMAREA as the first two parameters on the callstatement.

v PL/I routines can FETCH only those C/C++ routines that have not beenprocessed by the CICS translator. This is because during the dynamic call certainstatic fields created by the translator cannot be correctly set.

COBOL and PL/I

Under CICS, Language Environment supports ILC between routines compiled withLanguage Environment-supported COBOL and PL/I compilers, as follows:v COBOL routines can statically call PL/I routines, and PL/I routines canstatically call COBOL routines.

v COBOL programs can dynamically call PL/I routines that haveOPTIONS(FETCHABLE) specified and PL/I routines can FETCH COBOLprograms.

If the called routine contains any CICS commands then the calling routine mustpass the EIB and the COMMAREA as the first two parameters on the CALLstatement.


Assembler languagev You can make static or dynamic calls from any Language Environment-conforming HLL program to a Language Environment-conforming assemblerlanguage subroutine. Conversely, a Language Environment-conformingassembler language routine can make a static call to any LanguageEnvironment-conforming routine, and can dynamically load another routine,either assembler language or HLL, by using either of the Language Environmentmacros CEEFETCH or CEELOAD.

v You cannot delete (release) an ILC module that has been loaded usingCEELOAD.

v You can use the CEERELES macro to release an ILC module which has beenfetched using CEEFETCH.

v Use the language that fetched it to delete an assembler language routine. Thiscan only be done from C/C++, COBOL, and PL/I, if there is no ILC with PL/Iin the module being released.

Additionally, you can make static calls from any Language Environment-conforming HLL program or assembler language subroutine to a non-conformingassembler language subroutine. However, a non-conforming assembler languageroutine cannot make a static call to any Language Environment-conformingroutine, nor can it fetch or load a conforming routine, because it cannot use theLanguage Environment macros.

For assembler language to call C or C++, you must include the followingstatement:

C #pragma linkage(,OS)

C++ extern "OS"

DL/I

If you are using DL/I in your ILC application under CICS, calls to DL/I, either byan EXEC DLI statement or by a CALL xxxTDLI, can be made only in programswith the same language as the main program.

Language Environment does not support CALL CEETDLI under CICS.

-

Dynamic Link Libraries (DLLs)The z/OS dynamic link library (DLL) facility provides a mechanism for packagingprograms and data into load modules (DLLs) that can be accessed from otherseparate load modules.

A DLL can export symbols representing routines that can be called from outsidethe DLL, and can import symbols representing routines or data or both in otherDLLs, avoiding the need to link the target routines into the same load module asthe referencing routine. When an application references a separate DLL for the firsttime, the system automatically loads the DLL into memory.

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


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

Defining runtime options for Language EnvironmentLanguage Environment provides runtime options to control your program'sprocessing. Under CICS, exactly which options apply to the execution of aparticular program depends not only on the program, but also on how it is run.

Java programs and programs initiated from the Web or through CICS IIOP servicesuse the Language Environment preinitialization module, CEEPIPI. This has its ownversion of the CEEDOPT CSECT and such programs get their runtime optionsfrom this CSECT.

For normal CICS tasks, such as those started from a terminal, use any of thefollowing methods listed to set the Language Environment runtime options. Formore information about the full order of precedence for Language Environmentruntime options see z/OS V1R11.0 Language Environment Programming GuideSA22-7561-10. 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 reverseorder of precedence.1. The CEEDOPT CSECT built into CEECCICS contains the IBM Language

Environment default runtime options. You can change these default runtimeoptions by using the CEEWCOPT sample job located in SCEESAMP. Thisoption is supported but using the CEEPRMxx parmlib member to specifyruntime options is the preferred and easiest method.

2. The CEEPRMxx parmlib member provides support for the CEECOPT optiongroup which is the preferred method for setting your default LanguageEnvironment runtime options for CICS.

3. 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 ina data set in the DFHRPL library concatenation for the CICS job.

4. The user replaceable program DFHAPXPO (applies to XPLINK programs only).5. In the CEEUOPT CSECT, where user-supplied application program-level

runtime options are located. This CSECT is linked with the application programitself.

6. In the application source code using the programming language optionsstatements, as follows:v In C programs, through the #pragma runopts statement in the programsource. For example:#pragma runopts(rptstg(on))

v In PL/I programs, through the PLIXOPT declaration statement within theprogram. 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 runtimeoptions within COBOL programs or within C++ programs.

7. In the Language Environment options specified in a debugging profile. Formore information, see Debugging profiles on page 200.


In most installations, the first method in the previous list is unavailable toapplication programmers, and the second is often unavailable. However,application programmers can use method 4 or method 5. Choose one method only;do not attempt to use both method 4 and method 5. For information aboutgenerating a CEEUOPT CSECT to link with your application, see z/OS LanguageEnvironment Customization.

Both CEEDOPT and CEEROPT are able to set any option so that it cannot beoverridden by a later specification.

For more information about how to specify Language Environment runtimeoptions and also for their meanings, see z/OS Language Environment ProgrammingReference.

Runtime options ignored under CICS

Under CICS many of the Language Environment runtime option settings areignored. These are all the Fortran-only options plus the following:v ABPERCv AIXBLDv CBLOPTSv CBLQDAv DEBUGv EXECOPSv INTERRUPTv LIBRARYv MSGFILEv NONIPTSTACKv PLITASKCOUNTv POSIX (unless XPLINK or Java program)v RTEREUSv RTLSv SIMVRDv THREADHEAPv VERSION

Determining which runtime options were used

If you want to know which Language Environment runtime options were in effectwhen your program ran, specify the option RPTOPTS(ON). When the programends this produces a list of all the runtime options used. The list is written to theCESE TD queue. The list contains not only the actual settings of the options, butalso their origin, that is, whether they are the default for the installation or theregion, 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 significantoverhead and it causes a large amount of data to be written to the CESE queue.


Runtime options in child enclaves: performance considerations

Under CICS the execution of a CICS LINK command creates what LanguageEnvironment calls a Child Enclave. A new environment is initialized and the childenclave gets its runtime options. These runtime options are independent of thosethat existed in the creating enclave.

Frequent use of EXEC CICS LINK, and the individual setting of many runtimeoptions, could affect performance. A static or dynamic call does not incur theseoverheads. If you must use CEEUOPT to specify options, specifying only thoseoptions that are different from the defaults improves performance.

Something similar happens when a CICS XCTL command is executed. In this casewe do not get a child enclave, but the existing enclave is terminated and thenreinitialized with the runtime options determined for the new program. The sameperformance considerations apply.

CEEBXITA and CEECSTX user exitsThese two Language Environment user exits can change some of the LanguageEnvironment runtime options.v Setting the CEEAUE_A_OPTION return parameter of the CEEBXITA user exitcan change options (apart from the LIBRARY, RTLS, STACK, and VERSIONoptions).

v In the storage tuning user exit, CEECSTX, the options STACK, LIBSTACK,HEAP, ANYHEAP, and BELOWHEAP can be set.

The exits are called in the order in which they are listed above.

The storage tuning exit CEECSTX, like the CEEROPT CSECT, is region-wide, butCEEBXITA 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 becoded in assembler language.

Language Environment supplies a sample source version of CEEBXITA in theSCEESAMP library (it returns to its caller for whatever reason it is called). You canuse 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 applicationprogram and this version is then used instead of the installation default version.Take great care if you choose this method, because CEEBXITA is invoked for up tofive different reasons during the course of program execution, and anapplication-specific version of CEEBXITA must be capable of handling all theseinvocations.

If you write your own version of CEEBXITA, you must write it in assemblerlanguage. You can use all CICS commands except the ones listed here, providedyou specify the NOHANDLE, RESP or RESP2 option, to prevent conditions beingraised during the execution of the exit. These are the commands that cannot beused within CEEBXITA, or any routines called by CEEBXITA:v ABENDv HANDLE ABENDv HANDLE AIDv HANDLE CONDITION


v IGNORE CONDITIONv POP HANDLEv PUSH HANDLE

For more details on both CEEBXITA and CEECSTX, see z/OS Language EnvironmentCustomization.

CICSVAR, CICS environment variableCICS provides an environment variable called CICSVAR to allow theCONCURRENCY and API program attributes to be closely associated with theapplication program itself. You can specify this environment variable using theLanguage Environment runtime option ENVAR.

CICSVAR may be used in a CEEDOPT CSECT to set an installation default, but itis most useful to be set in a CEEUOPT CSECT link-edited with an individualprogram, or set by a #pragma statement in the source of a C or C++ program, orset by a PLIXOPT statement in a PL/I program. For example, when a program hasbeen coded to threadsafe standards it can be defined as such without having tochange an PROGRAM resource definition, or adhere to an installation-definednaming standard to allow a program autoinstall exit to install it with the correctattributes.

CICSVAR can be used for Language Environment-conforming assembler language,for PL/I, for COBOL, and for C and C++ programs (both those compiled with theXPLINK option, and those compiled without it), provided that the programs havebeen compiled using a Language Environment-conforming compiler. CICSVARcannot be used for assembler language programs that are not LanguageEnvironment-conforming, or for Java programs.

The use of CICSVAR overrides the settings on a PROGRAM resource definitioninstalled through the standard RDO interfaces, or through program autoinstall.Prior to the program being run for the first time, an INQUIRE PROGRAMcommand shows the keyword settings from the program definition. When theapplication has been run once, an INQUIRE PROGRAM command shows thesettings with any CICSVAR overrides applied.

CICSVAR can take one of three values, QUASIRENT, THREADSAFE or OPENAPI

CICSVAR=QUASIRENTResults in a program with the attributes CONCURRENCY(QUASIRENT)and APIST(CICSAPI).

CICSVAR=THREADSAFEResults in a program with the attributes CONCURRENCY(THREADSAFE)and APIST(CICSAPI).

CICSVAR=OPENAPIResults in a program with the attributes CONCURRENCY(THREADSAFE)and APIST(OPENAPI).

An example of the Language Environment runtime option ENVAR coded in aCEEUOPT CSECT is:CEEUOPT CSECTCEEUOPT AMODE ANYCEEUOPT RMODE ANY

CEEXOPT ENVAR=(CICSVAR=THREADSAFE)END


This can be assembled and link-edited into a load module, and then the CEEUOPTload module can be link-edited together with any language program supported byLanguage Environment.

Alternatively, for C and C++ programs, add the following statement at the start ofthe program source before any other C statements:#pragma runopts(ENVAR(CICSVAR=THREADSAFE))

For PL/I programs add the following statement following the PL/I MAINprocedure statement:DCL PLIXOPT CHAR(25) VAR STATIC EXTERNAL INIT(ENVAR(CICSVAR=THREADSAFE));

CEEBINT exit for Language EnvironmentAll programs running under Language Environment invoke a subroutine calledCEEBINT at program initialization time, just after invocation of the CEEBXITA andCEECSTX exits. The runtime environment is fully operational at this point.Language Environment calls this program the High Level Language (HLL) userexit.

Language Environment provides a module containing this program in theSCEELKED library (it returns to its caller) and this is, therefore, the installationdefault version. However, you can also write and link-edi

CICS Application Guide

Documents

cics programs

cics programming commands

cics programming roadmap

cics environment variable

cics applications1chapter

integrated cics translator

cics translator actions

pli programming restrictions