cics customization guide - ibm€¦ · cics transaction server for z/os cics customization guide...

CICS Transaction Server for z/OS

CICS Customization GuideVersion 3 Release 1

SC34-6429-08

��

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

This edition applies to Version 3 Release 1 of CICS Transaction Server for z/OS, program number 5655-M15, andto all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you areusing the correct edition for the level of the product.

© Copyright IBM Corporation 1977, 2011.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xixWhat this book is about . . . . . . . . . . . . . . . . . . . . . xixWho this book is for . . . . . . . . . . . . . . . . . . . . . . . xixWhat you need to know to understand this book . . . . . . . . . . . . xixHow to use this book . . . . . . . . . . . . . . . . . . . . . . xixNotes on terminology . . . . . . . . . . . . . . . . . . . . . . xixSyntax notation and conventions used in this book . . . . . . . . . . . . xx

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 3 Release 1 . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 2 Release 3 . . . . . xxiChanges for CICS Transaction Server for z/OS, Version 2 Release 2 . . . . xxiiChanges for CICS Transaction Server for OS/390, Version 1 Release 3 . . . xxiii

Part 1. Customizing with user exit programs . . . . . . . . . . . . . . . . . . 1

Chapter 1. Global user exit programs . . . . . . . . . . . . . . . . 3Overview — what is a global user exit? . . . . . . . . . . . . . . . . 3Writing global user exit programs . . . . . . . . . . . . . . . . . . 4

Register conventions . . . . . . . . . . . . . . . . . . . . . . 431-bit addressing implications . . . . . . . . . . . . . . . . . . . 5Using CICS services . . . . . . . . . . . . . . . . . . . . . . 5Using channels and containers . . . . . . . . . . . . . . . . . . 6Assembler programs and LEASM . . . . . . . . . . . . . . . . . 6Using EDF with global user exits . . . . . . . . . . . . . . . . . . 6The global work area . . . . . . . . . . . . . . . . . . . . . . 7Making trace entries . . . . . . . . . . . . . . . . . . . . . . 7Parameters passed to the global user exit program . . . . . . . . . . . 7Returning values to CICS . . . . . . . . . . . . . . . . . . . . 11Restrictions on the use of fields as programming interfaces . . . . . . . 12Exit programs and the CICS storage protection facility . . . . . . . . . 12Errors in user exit programs . . . . . . . . . . . . . . . . . . . 13Defining, enabling, and disabling an exit program . . . . . . . . . . . 14Invoking more than one exit program at a single exit . . . . . . . . . . 14Invoking a single exit program at more than one exit . . . . . . . . . . 15Making programs threadsafe . . . . . . . . . . . . . . . . . . . 15Sample global user exit programs . . . . . . . . . . . . . . . . . 16

List of global user exit points . . . . . . . . . . . . . . . . . . . . 22Activity keypoint program exit XAKUSER . . . . . . . . . . . . . . . 28

Exit XAKUSER . . . . . . . . . . . . . . . . . . . . . . . . 28Basic Mapping Support exits XBMIN and XBMOUT . . . . . . . . . . . 30

Exit XBMIN . . . . . . . . . . . . . . . . . . . . . . . . . 31Exit XBMOUT . . . . . . . . . . . . . . . . . . . . . . . . 31The field element table structure . . . . . . . . . . . . . . . . . 32Programming the XBMIN exit . . . . . . . . . . . . . . . . . . 33Programming the XBMOUT exit. . . . . . . . . . . . . . . . . . 33

Bridge facility exit XFAINTU . . . . . . . . . . . . . . . . . . . . 35Exit XFAINTU . . . . . . . . . . . . . . . . . . . . . . . . 35

Data tables management exits XDTRD, XDTAD, and XDTLC . . . . . . . . 37Exit XDTRD . . . . . . . . . . . . . . . . . . . . . . . . . 37Exit XDTAD . . . . . . . . . . . . . . . . . . . . . . . . . 40Exit XDTLC . . . . . . . . . . . . . . . . . . . . . . . . . 41

DBCTL interface control program exit XXDFA . . . . . . . . . . . . . 43

© Copyright IBM Corp. 1977, 2011 iii

||||

DBCTL tracking program exits XXDFB and XXDTO . . . . . . . . . . . 44Exit XXDFB . . . . . . . . . . . . . . . . . . . . . . . . . 44Exit XXDTO . . . . . . . . . . . . . . . . . . . . . . . . . 45

Dispatcher domain exits XDSBWT and XDSAWT . . . . . . . . . . . . 46Exit XDSBWT . . . . . . . . . . . . . . . . . . . . . . . . 46Exit XDSAWT . . . . . . . . . . . . . . . . . . . . . . . . 47

DL/I interface program exits XDLIPRE and XDLIPOST . . . . . . . . . . 48Exit XDLIPRE . . . . . . . . . . . . . . . . . . . . . . . . 49Exit XDLIPOST. . . . . . . . . . . . . . . . . . . . . . . . 51

Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT. . . . . 53Exit XDUREQ . . . . . . . . . . . . . . . . . . . . . . . . 53The sample program for the XDUREQ exit, DFH$XDRQ . . . . . . . . 56Exit XDUREQC. . . . . . . . . . . . . . . . . . . . . . . . 56Exit XDUCLSE . . . . . . . . . . . . . . . . . . . . . . . . 59Exit XDUOUT . . . . . . . . . . . . . . . . . . . . . . . . 60

Enqueue EXEC interface program exits XNQEREQ and XNQEREQC. . . . . 61Exit XNQEREQ. . . . . . . . . . . . . . . . . . . . . . . . 61Exit XNQEREQC . . . . . . . . . . . . . . . . . . . . . . . 62The command-level parameter structure . . . . . . . . . . . . . . 63Sample exit program, DFH$XNQE. . . . . . . . . . . . . . . . . 67

EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT . . . 69The command parameter list . . . . . . . . . . . . . . . . . . . 69Bypassing commands . . . . . . . . . . . . . . . . . . . . . 70Exit XEIIN. . . . . . . . . . . . . . . . . . . . . . . . . . 70Exit XEISPIN . . . . . . . . . . . . . . . . . . . . . . . . 71Exit XEIOUT. . . . . . . . . . . . . . . . . . . . . . . . . 72Exit XEISPOUT. . . . . . . . . . . . . . . . . . . . . . . . 72

File control domain exits, XFCFRIN and XFCFROUT . . . . . . . . . . . 74XFCFRIN . . . . . . . . . . . . . . . . . . . . . . . . . . 74XFCFROUT . . . . . . . . . . . . . . . . . . . . . . . . . 75Exit XFCFRIN . . . . . . . . . . . . . . . . . . . . . . . . 75Exit XFCFROUT . . . . . . . . . . . . . . . . . . . . . . . 82

File control EXEC interface API exits XFCREQ and XFCREQC . . . . . . . 88The command-level parameter structure . . . . . . . . . . . . . . 89Modifying fields in the command-level parameter structure . . . . . . . . 92Modifying the EID . . . . . . . . . . . . . . . . . . . . . . . 93Use of the task token UEPTSTOK . . . . . . . . . . . . . . . . . 95Use of the parameter UEPFSHIP . . . . . . . . . . . . . . . . . 95The EIB . . . . . . . . . . . . . . . . . . . . . . . . . . 95Example of how XFCREQ and XFCREQC can be used . . . . . . . . . 96Exit XFCREQ . . . . . . . . . . . . . . . . . . . . . . . . 96Exit XFCREQC . . . . . . . . . . . . . . . . . . . . . . . . 98

File control EXEC interface SPI exits XFCAREQ and XFCAREQC . . . . . 100Exit XFCAREQ . . . . . . . . . . . . . . . . . . . . . . . 101Exit XFCAREQC . . . . . . . . . . . . . . . . . . . . . . . 102The command-level parameter structure . . . . . . . . . . . . . . 103Modifying fields in the command-level parameter structure . . . . . . . 109Modifying the EID . . . . . . . . . . . . . . . . . . . . . . 112Use of the task token UEPTSTOK . . . . . . . . . . . . . . . . 112Modifying user arguments . . . . . . . . . . . . . . . . . . . 112

File control file state program exits XFCSREQ and XFCSREQC . . . . . . 114Exit XFCSREQ . . . . . . . . . . . . . . . . . . . . . . . 115Exit XFCSREQC . . . . . . . . . . . . . . . . . . . . . . . 118

File control open/close program exit XFCNREC . . . . . . . . . . . . 124Using XFCNREC with a back out recovery setting mismatch . . . . . . 124Using XFCNREC with a BWO mismatch . . . . . . . . . . . . . . 124

iv CICS TS for z/OS: CICS Customization Guide

Exit XFCNREC . . . . . . . . . . . . . . . . . . . . . . . 125File control quiesce receive exit, XFCVSDS . . . . . . . . . . . . . . 127

Exit XFCVSDS . . . . . . . . . . . . . . . . . . . . . . . 128File control quiesce send exit XFCQUIS . . . . . . . . . . . . . . . 130File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and

XFCLDEL . . . . . . . . . . . . . . . . . . . . . . . . . 132Order of invocation . . . . . . . . . . . . . . . . . . . . . . 132Enabling the exit programs . . . . . . . . . . . . . . . . . . . 132Exit XFCBFAIL, file control backout failure exit . . . . . . . . . . . . 133Exit XFCBOUT, file control backout exit . . . . . . . . . . . . . . 137Exit XFCBOVER, file control backout override exit . . . . . . . . . . 139Exit XFCLDEL, file control logical delete exit . . . . . . . . . . . . 141

Front End Programming Interface exits XSZARQ and XSZBRQ . . . . . . 144“Good morning” message program exit XGMTEXT . . . . . . . . . . . 145HTTP client open and send exits, XWBOPEN and XWBSNDO . . . . . . . 146Intersystem communication program exits XISCONA and XISLCLQ . . . . . 147

The XISCONA exit . . . . . . . . . . . . . . . . . . . . . . 147The XISLCLQ exit . . . . . . . . . . . . . . . . . . . . . . 150

Interval control program exits XICREQ, XICEXP, and XICTENF . . . . . . 152Exit XICREQ . . . . . . . . . . . . . . . . . . . . . . . . 152Exit XICEXP . . . . . . . . . . . . . . . . . . . . . . . . 153Exit XICTENF . . . . . . . . . . . . . . . . . . . . . . . . 153

Interval control EXEC interface program exits XICEREQ, XICERES, andXICEREQC . . . . . . . . . . . . . . . . . . . . . . . . . 154Parameters passed to each of the exits . . . . . . . . . . . . . . 155Exit XICEREQ. . . . . . . . . . . . . . . . . . . . . . . . 156Exit XICERES. . . . . . . . . . . . . . . . . . . . . . . . 157Exit XICEREQC . . . . . . . . . . . . . . . . . . . . . . . 158The command-level parameter structure . . . . . . . . . . . . . . 160

Loader domain exits XLDLOAD and XLDELETE . . . . . . . . . . . . 171Exit XLDLOAD . . . . . . . . . . . . . . . . . . . . . . . 171Exit XLDELETE . . . . . . . . . . . . . . . . . . . . . . . 172

Log manager domain exit XLGSTRM . . . . . . . . . . . . . . . . 173Exit XLGSTRM . . . . . . . . . . . . . . . . . . . . . . . 174An example of how XLGSTRM can be used . . . . . . . . . . . . 175The sample program for the XLGSTRM exit, DFH$LGLS . . . . . . . . 176

Message domain exit XMEOUT . . . . . . . . . . . . . . . . . . 177Exit XMEOUT . . . . . . . . . . . . . . . . . . . . . . . . 178The sample XMEOUT global user exit programs . . . . . . . . . . . 180

Monitoring domain exit XMNOUT. . . . . . . . . . . . . . . . . . 182Exit XMNOUT . . . . . . . . . . . . . . . . . . . . . . . . 182

Program control program exits XPCREQ, XPCERES, XPCREQC, XPCFTCH,XPCHAIR, XPCTA, and XPCABND . . . . . . . . . . . . . . . . 185XPCREQ, XPCERES, and XPCREQC. . . . . . . . . . . . . . . 185Exit XPCFTCH . . . . . . . . . . . . . . . . . . . . . . . 195Exit XPCHAIR. . . . . . . . . . . . . . . . . . . . . . . . 197Exit XPCTA. . . . . . . . . . . . . . . . . . . . . . . . . 198Exit XPCABND . . . . . . . . . . . . . . . . . . . . . . . 200

Resource manager interface program exits XRMIIN and XRMIOUT . . . . . 202Exit XRMIIN . . . . . . . . . . . . . . . . . . . . . . . . 202Exit XRMIOUT . . . . . . . . . . . . . . . . . . . . . . . 203

Resource management install and discard exit XRSINDI . . . . . . . . . 204Exit XRSINDI . . . . . . . . . . . . . . . . . . . . . . . . 204

Signon and signoff exits XSNON, XSNOFF, and XSNEX . . . . . . . . . 208Exit XSNON . . . . . . . . . . . . . . . . . . . . . . . . 208Exit XSNOFF . . . . . . . . . . . . . . . . . . . . . . . . 209

Contents v

||

||

Exit XSNEX . . . . . . . . . . . . . . . . . . . . . . . . 210Statistics domain exit XSTOUT . . . . . . . . . . . . . . . . . . 211

Exit XSTOUT . . . . . . . . . . . . . . . . . . . . . . . . 211System recovery program exit XSRAB. . . . . . . . . . . . . . . . 213

Exit XSRAB . . . . . . . . . . . . . . . . . . . . . . . . 213System termination program exit XSTERM . . . . . . . . . . . . . . 216

Exit XSTERM . . . . . . . . . . . . . . . . . . . . . . . . 216Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and

XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . . . 217Exit XTSQRIN. . . . . . . . . . . . . . . . . . . . . . . . 217Exit XTSQROUT . . . . . . . . . . . . . . . . . . . . . . . 218Exit XTSPTIN . . . . . . . . . . . . . . . . . . . . . . . . 219Exit XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . 220

Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC 222Exit XTSEREQ . . . . . . . . . . . . . . . . . . . . . . . 222Exit XTSEREQC . . . . . . . . . . . . . . . . . . . . . . . 223The command-level parameter structure . . . . . . . . . . . . . . 225

Terminal allocation program exit XALCAID . . . . . . . . . . . . . . 231Exit XALCAID . . . . . . . . . . . . . . . . . . . . . . . . 231

Terminal control program exits XTCIN, XTCOUT, and XTCATT . . . . . . . 233Exit XTCIN . . . . . . . . . . . . . . . . . . . . . . . . . 233Exit XTCOUT . . . . . . . . . . . . . . . . . . . . . . . . 233Exit XTCATT . . . . . . . . . . . . . . . . . . . . . . . . 234

‘Terminal not known’ condition exits XALTENF and XICTENF . . . . . . . 235The exits . . . . . . . . . . . . . . . . . . . . . . . . . 235Exit XALTENF. . . . . . . . . . . . . . . . . . . . . . . . 236Exit XICTENF . . . . . . . . . . . . . . . . . . . . . . . . 238The sample program for the XALTENF and XICTENF exits, DFHXTENF 240

Transaction manager domain exit XXMATT . . . . . . . . . . . . . . 243Exit XXMATT . . . . . . . . . . . . . . . . . . . . . . . . 243

Transient data program exits XTDREQ, XTDIN, and XTDOUT . . . . . . . 245Exit XTDREQ . . . . . . . . . . . . . . . . . . . . . . . . 245Exit XTDIN . . . . . . . . . . . . . . . . . . . . . . . . . 246Exit XTDOUT . . . . . . . . . . . . . . . . . . . . . . . . 247

Transient data EXEC interface program exits XTDEREQ and XTDEREQC 248Exit XTDEREQ . . . . . . . . . . . . . . . . . . . . . . . 248Exit XTDEREQC . . . . . . . . . . . . . . . . . . . . . . . 250The command-level parameter structure . . . . . . . . . . . . . . 252

User log record recovery program exits XRCINIT and XRCINPT . . . . . . 257Coding the exit programs . . . . . . . . . . . . . . . . . . . 257Enabling the exit programs . . . . . . . . . . . . . . . . . . . 258Exit XRCINIT . . . . . . . . . . . . . . . . . . . . . . . . 259Exit XRCINPT. . . . . . . . . . . . . . . . . . . . . . . . 259

VTAM terminal management program exit XZCATT . . . . . . . . . . . 261Exit XZCATT . . . . . . . . . . . . . . . . . . . . . . . . 261

VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE 262Exit XZCIN . . . . . . . . . . . . . . . . . . . . . . . . . 262Exit XZCOUT . . . . . . . . . . . . . . . . . . . . . . . . 263Exit XZCOUT1 . . . . . . . . . . . . . . . . . . . . . . . 263XZIQUE exit for managing intersystem queues. . . . . . . . . . . . 264Designing an XZIQUE global user exit program . . . . . . . . . . . 270

XRF request-processing program exit XXRSTAT . . . . . . . . . . . . 273Exit XXRSTAT. . . . . . . . . . . . . . . . . . . . . . . . 273

Chapter 2. Task-related user exit programs . . . . . . . . . . . . . 275Introduction to the task-related user exit mechanism (the adapter) . . . . . 275

vi CICS TS for z/OS: CICS Customization Guide

The stub program . . . . . . . . . . . . . . . . . . . . . . . 277Returning control to the application program . . . . . . . . . . . . 278Task-related user exits and EDF . . . . . . . . . . . . . . . . . 278

Writing a task-related user exit program . . . . . . . . . . . . . . . 278Obligations of OPENAPI task-related user exits . . . . . . . . . . . 279User exit parameter lists . . . . . . . . . . . . . . . . . . . . 281The schedule flag word . . . . . . . . . . . . . . . . . . . . 293Register handling in the task-related user exit program. . . . . . . . . 294Addressing-mode implications . . . . . . . . . . . . . . . . . . 295Exit programs and the CICS storage protection facility . . . . . . . . . 295Recursion within a task-related user exit program. . . . . . . . . . . 296Purging tasks . . . . . . . . . . . . . . . . . . . . . . . . 296Using CICS services in your task-related user exit program . . . . . . . 297Using channels and containers . . . . . . . . . . . . . . . . . 297Assembler programs and LEASM . . . . . . . . . . . . . . . . 298Wait states in your task-related user exit program . . . . . . . . . . 298Work areas . . . . . . . . . . . . . . . . . . . . . . . . . 298Coding a program to be invoked by the CICS SPI . . . . . . . . . . 298Coding a program to be invoked by the CICS syncpoint manager . . . . . 299Coding a program to be invoked by the CICS task manager . . . . . . . 303Coding a program to be invoked at CICS termination . . . . . . . . . 303Using EDF with your task-related user exit program . . . . . . . . . . 306

Administering the adapter . . . . . . . . . . . . . . . . . . . . 307What you must do before using the adapter . . . . . . . . . . . . . 308Tracing a task-related user exit program . . . . . . . . . . . . . . 309

Chapter 3. The user exit programming interface (XPI) . . . . . . . . . 311Overview of the XPI . . . . . . . . . . . . . . . . . . . . . . 311Making an XPI call . . . . . . . . . . . . . . . . . . . . . . . 314

Setting up the XPI environment . . . . . . . . . . . . . . . . . 318XPI register usage . . . . . . . . . . . . . . . . . . . . . . 318The XPI copy books . . . . . . . . . . . . . . . . . . . . . 319Reentrancy considerations resulting from XPI calls . . . . . . . . . . 319

Global user exit XPI examples, showing the use of storage . . . . . . . . 319An example showing how to build a parameter list incrementally . . . . . 324

The XPI functions . . . . . . . . . . . . . . . . . . . . . . . 325Dispatcher XPI functions . . . . . . . . . . . . . . . . . . . . . 327

Synchronization protocols for SUSPEND and RESUME processing . . . . 327The ADD_SUSPEND call . . . . . . . . . . . . . . . . . . . 329The SUSPEND call . . . . . . . . . . . . . . . . . . . . . . 331The RESUME call . . . . . . . . . . . . . . . . . . . . . . 334The DELETE_SUSPEND call . . . . . . . . . . . . . . . . . . 335The WAIT_MVS call . . . . . . . . . . . . . . . . . . . . . 336The CHANGE_PRIORITY call . . . . . . . . . . . . . . . . . . 340

Dump control XPI functions . . . . . . . . . . . . . . . . . . . . 341The SYSTEM_DUMP call . . . . . . . . . . . . . . . . . . . 341The TRANSACTION_DUMP call . . . . . . . . . . . . . . . . . 343

Enqueue domain XPI functions . . . . . . . . . . . . . . . . . . 345The ENQUEUE function . . . . . . . . . . . . . . . . . . . . 345The DEQUEUE function . . . . . . . . . . . . . . . . . . . . 346

Kernel domain XPI functions . . . . . . . . . . . . . . . . . . . 347The START_PURGE_PROTECTION function . . . . . . . . . . . . 347The STOP_PURGE_PROTECTION function . . . . . . . . . . . . 348Nesting purge protection calls . . . . . . . . . . . . . . . . . . 348

Loader XPI functions . . . . . . . . . . . . . . . . . . . . . . 349The DEFINE_PROGRAM call . . . . . . . . . . . . . . . . . . 349

Contents vii

||||

The ACQUIRE_PROGRAM call . . . . . . . . . . . . . . . . . 352The RELEASE_PROGRAM call . . . . . . . . . . . . . . . . . 354The DELETE_PROGRAM call . . . . . . . . . . . . . . . . . . 355

Log manager XPI functions . . . . . . . . . . . . . . . . . . . . 356The INQUIRE_PARAMETERS call . . . . . . . . . . . . . . . . 356The SET_PARAMETERS call . . . . . . . . . . . . . . . . . . 357

Monitoring XPI functions . . . . . . . . . . . . . . . . . . . . . 357The MONITOR call . . . . . . . . . . . . . . . . . . . . . . 358The INQUIRE_MONITORING_DATA call . . . . . . . . . . . . . . 361

Program management XPI functions . . . . . . . . . . . . . . . . 362The INQUIRE_PROGRAM call . . . . . . . . . . . . . . . . . 362The INQUIRE_CURRENT_PROGRAM call . . . . . . . . . . . . . 369The SET_PROGRAM call . . . . . . . . . . . . . . . . . . . 371The START_BROWSE_PROGRAM call . . . . . . . . . . . . . . 374The GET_NEXT_PROGRAM call. . . . . . . . . . . . . . . . . 375The END_BROWSE_PROGRAM call . . . . . . . . . . . . . . . 377The INQUIRE_AUTOINSTALL call . . . . . . . . . . . . . . . . 378The SET_AUTOINSTALL call . . . . . . . . . . . . . . . . . . 379

State data access XPI functions . . . . . . . . . . . . . . . . . . 380The INQ_APPLICATION_DATA call . . . . . . . . . . . . . . . . 380The INQUIRE_SYSTEM call . . . . . . . . . . . . . . . . . . 383The SET_SYSTEM call . . . . . . . . . . . . . . . . . . . . 387

Storage control XPI functions . . . . . . . . . . . . . . . . . . . 388The GETMAIN call . . . . . . . . . . . . . . . . . . . . . . 389The FREEMAIN call . . . . . . . . . . . . . . . . . . . . . 391The INQUIRE_ACCESS call . . . . . . . . . . . . . . . . . . 392The INQUIRE_ELEMENT_LENGTH call . . . . . . . . . . . . . . 393The INQUIRE_SHORT_ON_STORAGE call . . . . . . . . . . . . . 393The INQUIRE_TASK_STORAGE call . . . . . . . . . . . . . . . 394The SWITCH_SUBSPACE call . . . . . . . . . . . . . . . . . 395

Trace control XPI function . . . . . . . . . . . . . . . . . . . . 396The TRACE_PUT call . . . . . . . . . . . . . . . . . . . . . 396

Transaction management XPI functions . . . . . . . . . . . . . . . 397The INQUIRE_CONTEXT call . . . . . . . . . . . . . . . . . . 397The INQUIRE_DTRTRAN call . . . . . . . . . . . . . . . . . . 399The INQUIRE_MXT call . . . . . . . . . . . . . . . . . . . . 400The INQUIRE_TCLASS call. . . . . . . . . . . . . . . . . . . 401The INQUIRE_TRANDEF call . . . . . . . . . . . . . . . . . . 402The INQUIRE_TRANSACTION call . . . . . . . . . . . . . . . . 410The SET_TRANSACTION call . . . . . . . . . . . . . . . . . . 415

User journaling XPI function . . . . . . . . . . . . . . . . . . . 416The WRITE_JOURNAL_DATA call . . . . . . . . . . . . . . . . 416

Part 2. Customizing with initialization and shutdown programs . . . . . . . . 419

Chapter 4. Writing initialization and shutdown programs. . . . . . . . 421Writing initialization programs . . . . . . . . . . . . . . . . . . . 421

First phase PLT programs . . . . . . . . . . . . . . . . . . . 421Second phase PLT programs . . . . . . . . . . . . . . . . . . 422Effect of delayed recovery on PLTPI processing . . . . . . . . . . . 423

Writing shutdown programs . . . . . . . . . . . . . . . . . . . . 423First phase PLT programs . . . . . . . . . . . . . . . . . . . 423PLT programs for the second quiesce stage. . . . . . . . . . . . . 423The shutdown assist utility program, DFHCESD . . . . . . . . . . . 424

General considerations when writing initialization and shutdown programs 425Storage keys for PLT programs . . . . . . . . . . . . . . . . . 425

viii CICS TS for z/OS: CICS Customization Guide

Part 3. Customizing with user-replaceable programs . . . . . . . . . . . . . 427

Chapter 5. General notes about user-replaceable programs . . . . . . 429Rewriting user-replaceable programs . . . . . . . . . . . . . . . . 429Assembling and link-editing user-replaceable programs . . . . . . . . . 430User-replaceable programs and the storage protection facility . . . . . . . 431

Execution key for user-replaceable programs . . . . . . . . . . . . 431Data storage key for user-replaceable programs . . . . . . . . . . . 432

Chapter 6. Writing a program error program . . . . . . . . . . . . 433The sample program error programs . . . . . . . . . . . . . . . . 436

Chapter 7. Writing a transaction restart program . . . . . . . . . . . 437The DFHREST communications area . . . . . . . . . . . . . . . . 438The CICS-supplied transaction restart program . . . . . . . . . . . . 439

Chapter 8. Writing a terminal error program . . . . . . . . . . . . . 441Background to error handling for sequential devices . . . . . . . . . . . 441

When an abnormal condition occurs . . . . . . . . . . . . . . . 441Terminal control program. . . . . . . . . . . . . . . . . . . . 442Terminal abnormal condition program . . . . . . . . . . . . . . . 442Terminal error program . . . . . . . . . . . . . . . . . . . . 442The communication area . . . . . . . . . . . . . . . . . . . . 442Terminal abnormal condition line entry (TACLE) . . . . . . . . . . . 443

The sample terminal error program . . . . . . . . . . . . . . . . . 443Components of the sample terminal error program . . . . . . . . . . 443Structure of the sample terminal error program. . . . . . . . . . . . 445Sample terminal error program messages . . . . . . . . . . . . . 448Generating the sample terminal error program . . . . . . . . . . . . 450

Writing your own terminal error program . . . . . . . . . . . . . . . 462Why write your own terminal error program? . . . . . . . . . . . . 462Restrictions on the use of EXEC CICS commands . . . . . . . . . . 462Addressing the contents of the communication area . . . . . . . . . . 463Addressing the contents of the TACLE. . . . . . . . . . . . . . . 465Example of a user-written terminal error program . . . . . . . . . . . 468

Chapter 9. Writing a node error program . . . . . . . . . . . . . . 471Background to CICS-VTAM error handling . . . . . . . . . . . . . . 472

Why use a NEP to supplement CICS default actions? . . . . . . . . . 472An overview of writing a NEP . . . . . . . . . . . . . . . . . . 473The default NEP . . . . . . . . . . . . . . . . . . . . . . . 474The sample NEP. . . . . . . . . . . . . . . . . . . . . . . 474Multiple NEPs . . . . . . . . . . . . . . . . . . . . . . . . 477

When an abnormal condition occurs . . . . . . . . . . . . . . . . 478The communication area . . . . . . . . . . . . . . . . . . . . 479

The sample node error program . . . . . . . . . . . . . . . . . . 487Compatibility with the sample terminal error program . . . . . . . . . 488Components of the sample node error program . . . . . . . . . . . 488Generating the sample node error program . . . . . . . . . . . . . 490

Writing your own node error program . . . . . . . . . . . . . . . . 496Restrictions on the use of EXEC CICS commands . . . . . . . . . . 497Entry and addressability . . . . . . . . . . . . . . . . . . . . 497Coding for the 3270 ‘unavailable printer’ condition . . . . . . . . . . 498Coding for session failures . . . . . . . . . . . . . . . . . . . 499Coding for specific VTAM sense codes . . . . . . . . . . . . . . 499Writing multiple NEPs . . . . . . . . . . . . . . . . . . . . . 499

Contents ix

DFHZNEPI macros . . . . . . . . . . . . . . . . . . . . . . 500Handling shutdown hung terminals in the node error program . . . . . . 501

Using the node error program with XRF or persistent sessions . . . . . . . 502The node error program in an XRF environment . . . . . . . . . . . 502The node error program with persistent session support . . . . . . . . 502Changing the recovery notification . . . . . . . . . . . . . . . . 503Changing the recovery message . . . . . . . . . . . . . . . . . 503Changing the recovery transaction . . . . . . . . . . . . . . . . 503

Using the node error program with VTAM generic resources. . . . . . . . 503

Chapter 10. Writing a program to control autoinstall of terminals . . . . 505Autoinstalling terminals—preliminary considerations . . . . . . . . . . . 505

Coding entries in the VTAM LOGON mode table . . . . . . . . . . . 506Using model terminal support (MTS) . . . . . . . . . . . . . . . 506The autoinstall control program for terminals . . . . . . . . . . . . 507

The autoinstall control program at INSTALL . . . . . . . . . . . . . . 507The communication area at INSTALL for terminals . . . . . . . . . . 508How CICS builds the list of autoinstall models . . . . . . . . . . . . 509Returning information to CICS . . . . . . . . . . . . . . . . . . 510CICS action on return from the control program . . . . . . . . . . . 513

The autoinstall control program at DELETE . . . . . . . . . . . . . . 515The communication area at DELETE for terminals . . . . . . . . . . 515

Naming, testing, and debugging your autoinstall control program . . . . . . 516Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 516Testing and debugging . . . . . . . . . . . . . . . . . . . . 516

The sample autoinstall control programs for terminals . . . . . . . . . . 517Customizing the sample program. . . . . . . . . . . . . . . . . 519

Chapter 11. Writing a program to control autoinstall of consoles . . . . 525Autoinstalling consoles—preliminary considerations . . . . . . . . . . . 525

Leaving it all to CICS . . . . . . . . . . . . . . . . . . . . . 525Using an autoinstall control program . . . . . . . . . . . . . . . 525

The autoinstall control program at INSTALL . . . . . . . . . . . . . . 526The communication area at INSTALL for consoles . . . . . . . . . . 526How CICS builds the list of autoinstall models . . . . . . . . . . . . 528Returning information to CICS . . . . . . . . . . . . . . . . . . 528CICS action on return from the control program . . . . . . . . . . . 529

The autoinstall control program at DELETE . . . . . . . . . . . . . . 530The sample autoinstall control programs for consoles . . . . . . . . . . 530

Chapter 12. Writing a program to control autoinstall of APPC connections 531Autoinstalling APPC connections—preliminary considerations . . . . . . . 531

Local APPC single-session connections initiated by CINIT . . . . . . . 531Local APPC parallel-session and single-session connections initiated by

BIND . . . . . . . . . . . . . . . . . . . . . . . . . . 531Autoinstall templates for APPC connections . . . . . . . . . . . . . 532Benefits of autoinstall . . . . . . . . . . . . . . . . . . . . . 532Requirements for autoinstall . . . . . . . . . . . . . . . . . . 532The autoinstall control program for APPC connections . . . . . . . . . 533Recovery and restart . . . . . . . . . . . . . . . . . . . . . 533

The autoinstall control program at INSTALL . . . . . . . . . . . . . . 533The communication area at INSTALL for APPC connections . . . . . . . 534

The autoinstall control program at DELETE . . . . . . . . . . . . . . 537When autoinstalled APPC connections are deleted . . . . . . . . . . 537

The sample autoinstall control program for APPC connections . . . . . . . 538Default actions of the sample program. . . . . . . . . . . . . . . 538

x CICS TS for z/OS: CICS Customization Guide

Resource definitions . . . . . . . . . . . . . . . . . . . . . 539

Chapter 13. Writing a program to control autoinstall of shipped terminals 541Installing shipped terminals and connections . . . . . . . . . . . . . 541

CICS-generated aliases . . . . . . . . . . . . . . . . . . . . 542Resetting the terminal identifier . . . . . . . . . . . . . . . . . 542

The autoinstall control program at INSTALL . . . . . . . . . . . . . . 543The communications area at INSTALL for shipped terminals . . . . . . . 544

The autoinstall control program at DELETE . . . . . . . . . . . . . . 546Default actions of the sample programs . . . . . . . . . . . . . . . 547

Chapter 14. Writing a program to control autoinstall of virtual terminals 549How Client virtual terminals are autoinstalled . . . . . . . . . . . . . 549

Autoinstall models . . . . . . . . . . . . . . . . . . . . . . 549Terminal identifiers . . . . . . . . . . . . . . . . . . . . . . 550Why override TERMIDs? . . . . . . . . . . . . . . . . . . . . 551

How bridge facility virtual terminals are autoinstalled . . . . . . . . . . 552Using the terminal autoinstall control program for bridge facilities . . . . . 552Bridge facility name uniqueness . . . . . . . . . . . . . . . . . 553

The autoinstall control program at INSTALL . . . . . . . . . . . . . . 553The communications area at INSTALL for Client virtual terminals . . . . . 554The communications area at INSTALL for bridge facility virtual terminals 555

The autoinstall control program at DELETE . . . . . . . . . . . . . . 557The communications area at DELETE for Client virtual terminals . . . . . 557The communications area at DELETE for bridge facility virtual terminals 558

Default actions of the sample programs . . . . . . . . . . . . . . . 559

Chapter 15. Writing a program to control autoinstall of programs . . . . 561Autoinstalling programs—preliminary considerations . . . . . . . . . . . 561

Autoinstall model definitions. . . . . . . . . . . . . . . . . . . 562Autoinstalling programs invoked by EXEC CICS LINK commands. . . . . 562Autoinstall processing of mapsets . . . . . . . . . . . . . . . . 563System autoinstall . . . . . . . . . . . . . . . . . . . . . . 563

Benefits of autoinstalling programs . . . . . . . . . . . . . . . . . 563Reduced system administration costs . . . . . . . . . . . . . . . 563Saving in virtual storage . . . . . . . . . . . . . . . . . . . . 563Faster startup times . . . . . . . . . . . . . . . . . . . . . 564

Requirements for program autoinstall . . . . . . . . . . . . . . . . 564The autoinstall control program at INSTALL . . . . . . . . . . . . . . 565The sample autoinstall control program for programs, DFHPGADX . . . . . 568

Customizing the sample program. . . . . . . . . . . . . . . . . 569Resource definition . . . . . . . . . . . . . . . . . . . . . . 570Testing and debugging your program . . . . . . . . . . . . . . . 570

Chapter 16. Writing a dynamic routing program . . . . . . . . . . . 571Routing transactions dynamically . . . . . . . . . . . . . . . . . . 572

Dynamic transactions . . . . . . . . . . . . . . . . . . . . . 572When the dynamic routing program is invoked . . . . . . . . . . . . 572Information passed to the dynamic routing program . . . . . . . . . . 573Changing the target CICS region . . . . . . . . . . . . . . . . . 574Changing the program name . . . . . . . . . . . . . . . . . . 575Telling CICS whether to route or terminate a transaction . . . . . . . . 575If the system is unavailable or unknown . . . . . . . . . . . . . . 576Invoking the dynamic routing program at end of routed transactions . . . . 576Invoking the dynamic routing program on abend . . . . . . . . . . . 576Modifying the initial terminal data . . . . . . . . . . . . . . . . . 577

Contents xi

Modifying the application’s communications area . . . . . . . . . . . 578Receiving information from a routed transaction . . . . . . . . . . . 578Some processing considerations . . . . . . . . . . . . . . . . . 578Unit of work considerations . . . . . . . . . . . . . . . . . . . 579

Routing DPL requests dynamically . . . . . . . . . . . . . . . . . 579When the dynamic routing program is invoked . . . . . . . . . . . . 580Changing the target CICS region . . . . . . . . . . . . . . . . . 581Changing the program name . . . . . . . . . . . . . . . . . . 581Changing the transaction ID . . . . . . . . . . . . . . . . . . 581Telling CICS whether to route or terminate a DPL request . . . . . . . 582If an error occurs in route selection . . . . . . . . . . . . . . . . 582Using the XPCERES exit to check the availability of resources on the target

region . . . . . . . . . . . . . . . . . . . . . . . . . . 583Invoking the dynamic routing program at end of routed requests . . . . . 584Modifying the application’s input communications area . . . . . . . . . 584Monitoring the application’s output communications area . . . . . . . . 584Some processing considerations . . . . . . . . . . . . . . . . . 584Unit of work considerations . . . . . . . . . . . . . . . . . . . 584

Routing bridge requests dynamically . . . . . . . . . . . . . . . . 585Changing bridge request parameters . . . . . . . . . . . . . . . 586Rejecting a Link3270 bridge request . . . . . . . . . . . . . . . 587Handling route selection errors of Link3270 bridge requests . . . . . . . 587Using the XPCERES exit to check the availability of resources on the target

region . . . . . . . . . . . . . . . . . . . . . . . . . . 587Re-invoking the dynamic routing program after Link3270 bridge requests 588Link3270 bridge dynamic routing considerations . . . . . . . . . . . 588

Modifying the application’s containers . . . . . . . . . . . . . . . . 588Routing by user ID . . . . . . . . . . . . . . . . . . . . . . . 589Parameters passed to the dynamic routing program . . . . . . . . . . . 589Naming your dynamic routing program. . . . . . . . . . . . . . . . 603Testing your dynamic routing program . . . . . . . . . . . . . . . . 603Dynamic transaction routing sample programs . . . . . . . . . . . . . 604

Chapter 17. Writing a distributed routing program . . . . . . . . . . 605Differences between the distributed and dynamic routing interfaces . . . . . 606Routing BTS activities . . . . . . . . . . . . . . . . . . . . . . 607

Which BTS activities can be dynamically routed? . . . . . . . . . . . 607When the distributed routing program is invoked . . . . . . . . . . . 607Changing the target CICS region . . . . . . . . . . . . . . . . . 609Telling CICS whether to route the activity . . . . . . . . . . . . . . 609If an error occurs in route selection . . . . . . . . . . . . . . . . 609Invoking the distributed routing program on the target region . . . . . . 610

Routing method requests for enterprise beans and CORBA stateless objects 610Where workload balancing occurs . . . . . . . . . . . . . . . . 610Which requests can be dynamically routed?. . . . . . . . . . . . . 613When the distributed routing program is invoked . . . . . . . . . . . 614Changing the target CICS region . . . . . . . . . . . . . . . . . 615Telling CICS whether to route the method request . . . . . . . . . . 616If an error occurs in route selection . . . . . . . . . . . . . . . . 616Invoking the distributed routing program on the target region . . . . . . 616Dealing with a disabled CorbaServer . . . . . . . . . . . . . . . 617Performing a rolling upgrade of an EJB/CORBA server. . . . . . . . . 618

Routing non-terminal-related START requests . . . . . . . . . . . . . 619Which requests can be dynamically routed?. . . . . . . . . . . . . 619When the distributed routing program is invoked . . . . . . . . . . . 620Changing the target CICS region . . . . . . . . . . . . . . . . . 621

xii CICS TS for z/OS: CICS Customization Guide

||

Telling CICS whether to route the request . . . . . . . . . . . . . 621If an error occurs in route selection . . . . . . . . . . . . . . . . 622Using the XICERES exit to check the availability of resources on the target

region . . . . . . . . . . . . . . . . . . . . . . . . . . 622Invoking the distributed routing program on the target region . . . . . . 622

Routing inbound Web service requests . . . . . . . . . . . . . . . 623Which requests can be dynamically routed?. . . . . . . . . . . . . 623When the distributed routing program is invoked . . . . . . . . . . . 624Changing the target CICS region . . . . . . . . . . . . . . . . . 625Telling CICS whether to route the request . . . . . . . . . . . . . 625If an error occurs in route selection . . . . . . . . . . . . . . . . 626Invoking the distributed routing program on the target region . . . . . . 626

Routing by user ID . . . . . . . . . . . . . . . . . . . . . . . 626Dealing with an abend on the target region . . . . . . . . . . . . . . 626Some processing considerations . . . . . . . . . . . . . . . . . . 627Parameters passed to the distributed routing program . . . . . . . . . . 627Naming your distributed routing program . . . . . . . . . . . . . . . 639Distributed transaction routing sample programs . . . . . . . . . . . . 639

Chapter 18. Writing a CICS–DBCTL interface status program . . . . . . 641The sample CICS–DBCTL interface status program . . . . . . . . . . . 642

Chapter 19. Writing a 3270 bridge exit program . . . . . . . . . . . 643

Chapter 20. Writing a security exit program for IIOP . . . . . . . . . 645The sample programs . . . . . . . . . . . . . . . . . . . . . . 647

DFHXOPUS . . . . . . . . . . . . . . . . . . . . . . . . 647DFHEBURM . . . . . . . . . . . . . . . . . . . . . . . . 648

Chapter 21. Writing programs to customize JVMs . . . . . . . . . . 649Writing Java classes to redirect JVM stdout and stderr output . . . . . . . 649

The com.ibm.cics.server.OutputRedirectionPlugin interface . . . . . . . 650Possible destinations for output . . . . . . . . . . . . . . . . . 651Handling output redirection errors and internal errors . . . . . . . . . 651

Using DFHJVMRO to modify the Language Environment enclave for a JVM 652Using DFHJVMAT to modify options in a JVM profile . . . . . . . . . . 653

Options in the JVM profile that are available to DFHJVMAT . . . . . . . 655

Chapter 22. Writing a distinguished name program for clients ofenterprise beans . . . . . . . . . . . . . . . . . . . . . . 657

Sample programs and copy books . . . . . . . . . . . . . . . . . 659

Chapter 23. Writing an EJB event program . . . . . . . . . . . . . 661Overview of the EJB event program. . . . . . . . . . . . . . . . . 661The DFHEJEP communications area . . . . . . . . . . . . . . . . 662Event codes . . . . . . . . . . . . . . . . . . . . . . . . . 663The EJB event sample program . . . . . . . . . . . . . . . . . . 664

Actions of the default program . . . . . . . . . . . . . . . . . . 664Writing your own EJB event program . . . . . . . . . . . . . . . 664

Chapter 24. Writing programs to customize Language Environmentrun-time options for XPLink programs . . . . . . . . . . . . . . 667

DFHAPXPO . . . . . . . . . . . . . . . . . . . . . . . . . 667Defining run-time options. . . . . . . . . . . . . . . . . . . . 667

Part 4. Customizing the XRF overseer program. . . . . . . . . . . . . . . . 669

Contents xiii

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

|||||||

Chapter 25. The extended recovery facility overseer program . . . . . . 671The sample XRF overseer program . . . . . . . . . . . . . . . . . 671

The functions of the sample program . . . . . . . . . . . . . . . 671How the sample overseer program interfaces with CICS . . . . . . . . 675How to tell the overseer which actives and alternates to monitor . . . . . 675

The DFHWOSM macros . . . . . . . . . . . . . . . . . . . . . 676The DFHWOSM tokens . . . . . . . . . . . . . . . . . . . . 677DFHWOSM FUNC=BUILD macro . . . . . . . . . . . . . . . . 677DFHWOSM FUNC=CLOSE macro . . . . . . . . . . . . . . . . 677DFHWOSM FUNC=DSECT macro . . . . . . . . . . . . . . . . 678DFHWOSM FUNC=JJC macro . . . . . . . . . . . . . . . . . 678DFHWOSM FUNC={JJS|QJJS} macro . . . . . . . . . . . . . . . 678DFHWOSM FUNC=OPEN macro . . . . . . . . . . . . . . . . 679DFHWOSM FUNC=OSCMD macro . . . . . . . . . . . . . . . . 680DFHWOSM FUNC=READ macro. . . . . . . . . . . . . . . . . 681DFHWOSM FUNC=TERM macro . . . . . . . . . . . . . . . . 684

Customizing the sample XRF overseer program . . . . . . . . . . . . 684Loop or wait detection . . . . . . . . . . . . . . . . . . . . . 686Assembling and link-editing the overseer program . . . . . . . . . . 686

Part 5. CICS journaling, monitoring, and statistics . . . . . . . . . . . . . . 687

Chapter 26. CICS logging and journaling . . . . . . . . . . . . . . 689The CICS log manager . . . . . . . . . . . . . . . . . . . . . 689Log stream storage . . . . . . . . . . . . . . . . . . . . . . . 689Enabling, disabling, and reading journals . . . . . . . . . . . . . . . 691

Enabling and disabling a journal . . . . . . . . . . . . . . . . . 691Reading journal records offline . . . . . . . . . . . . . . . . . 692

Structure and content of CICS Transaction Server for z/OS format journalrecords . . . . . . . . . . . . . . . . . . . . . . . . . . 692Format of general log block header . . . . . . . . . . . . . . . . 694Format of general log journal record . . . . . . . . . . . . . . . 695Start-of-run record . . . . . . . . . . . . . . . . . . . . . . 696Format of caller data . . . . . . . . . . . . . . . . . . . . . 696

Structure and content of COMPAT41-format journal records . . . . . . . . 709Format of COMPAT41 journal control label header . . . . . . . . . . 709Format of journal record . . . . . . . . . . . . . . . . . . . . 711Identifying records for the start of tasks and UOWs . . . . . . . . . . 717

Format of journal records written to SMF . . . . . . . . . . . . . . . 717The SMF block header . . . . . . . . . . . . . . . . . . . . 718The CICS product section . . . . . . . . . . . . . . . . . . . 719The CICS data section . . . . . . . . . . . . . . . . . . . . 721

Chapter 27. CICS monitoring . . . . . . . . . . . . . . . . . . 723Introduction to CICS monitoring . . . . . . . . . . . . . . . . . . 723

The classes of monitoring data . . . . . . . . . . . . . . . . . 723Performance class data . . . . . . . . . . . . . . . . . . . . 724Exception class data . . . . . . . . . . . . . . . . . . . . . 730Transaction resource class data . . . . . . . . . . . . . . . . . 731How CICS monitoring data is passed to SMF . . . . . . . . . . . . 731Controlling CICS monitoring. . . . . . . . . . . . . . . . . . . 731

CICS monitoring record formats . . . . . . . . . . . . . . . . . . 732SMF header and SMF product section . . . . . . . . . . . . . . . 732CICS data section . . . . . . . . . . . . . . . . . . . . . . 735

Processing the output from the CICS Monitoring Facility . . . . . . . . . 749

xiv CICS TS for z/OS: CICS Customization Guide

Chapter 28. Writing statistics collection and analysis programs . . . . . 751Writing a program to collect CICS statistics . . . . . . . . . . . . . . 751

Background information . . . . . . . . . . . . . . . . . . . . 751Resetting statistics counters . . . . . . . . . . . . . . . . . . 752Using the EXEC CICS COLLECT and EXTRACT STATISTICS commands 752

CICS statistics record format . . . . . . . . . . . . . . . . . . . 753SMF header and SMF product section . . . . . . . . . . . . . . . 753CICS statistics data section . . . . . . . . . . . . . . . . . . . 755

Using an XSTOUT global user exit program to filter statistics records . . . . 757Processing the output from CICS statistics . . . . . . . . . . . . . . 757

Part 6. Customizing CICS compatibility interfaces . . . . . . . . . . . . . . 759

Chapter 29. The dynamic allocation sample program . . . . . . . . . 761Overview of the dynamic allocation program . . . . . . . . . . . . . 761Installing the program and transaction definitions . . . . . . . . . . . . 762The dynamic allocation program—terminal operation . . . . . . . . . . 762Using the dynamic allocation program’s Help feature . . . . . . . . . . 762The dynamic allocation program—values . . . . . . . . . . . . . . . 763

Abbreviation rules for keywords . . . . . . . . . . . . . . . . . 764System programming considerations . . . . . . . . . . . . . . . 764

The flow of control when a DYNALLOC request is issued. . . . . . . . . 764

Part 7. Customizing CICS security processing . . . . . . . . . . . . . . . . 767

Chapter 30. Invoking an external security manager . . . . . . . . . . 769An overview of the CICS-ESM interface . . . . . . . . . . . . . . . 769The MVS router . . . . . . . . . . . . . . . . . . . . . . . . 769

The MVS router exit . . . . . . . . . . . . . . . . . . . . . 769Using ESM exit programs to access CICS-related information . . . . . . . 771

For non-RACF users — the ESM parameter list . . . . . . . . . . . 772For RACF users — the RACF user exit parameter list . . . . . . . . . 772The installation data parameter list . . . . . . . . . . . . . . . . 773

CICS security control points. . . . . . . . . . . . . . . . . . . . 775Using early verification processing . . . . . . . . . . . . . . . . . 777

Writing an early verification routine . . . . . . . . . . . . . . . . 778Using CICS API commands in an early verification routine . . . . . . . 778Return and reason codes from the early verification routine . . . . . . . 778

Chapter 31. Writing a “good night” program . . . . . . . . . . . . 781The communications area of the “good night” program . . . . . . . . . . 781The sample “good night” program, DFH0GNIT . . . . . . . . . . . . . 783

What the sample program does . . . . . . . . . . . . . . . . . 783Customizing the sample “good night” program . . . . . . . . . . . . . 784

Part 8. Examining and modifying resource attributes . . . . . . . . . . . . . 787

Chapter 32. User programs for the system definition utility program(DFHCSDUP) . . . . . . . . . . . . . . . . . . . . . . . . 789

An overview of DFHCSDUP . . . . . . . . . . . . . . . . . . . 789Invoking a user program from DFHCSDUP . . . . . . . . . . . . . . 790

Writing a program to be invoked during EXTRACT processing . . . . . . 790The EXTRACT command . . . . . . . . . . . . . . . . . . . 790When the user program is invoked . . . . . . . . . . . . . . . . 791Parameters passed from DFHCSDUP to the user program . . . . . . . 791

Contents xv

The sample EXTRACT programs. . . . . . . . . . . . . . . . . 792Assembling and link-editing EXTRACT programs . . . . . . . . . . . 795

Invoking DFHCSDUP from a user program . . . . . . . . . . . . . . 797Entry parameters for DFHCSDUP . . . . . . . . . . . . . . . . 798Responsibilities of the user program . . . . . . . . . . . . . . . 800

The user exit points in DFHCSDUP . . . . . . . . . . . . . . . . . 800Parameters passed to the user exit routines. . . . . . . . . . . . . 800The initialization exit . . . . . . . . . . . . . . . . . . . . . 801The get-command exit. . . . . . . . . . . . . . . . . . . . . 802The extract exit . . . . . . . . . . . . . . . . . . . . . . . 803The put-message exit . . . . . . . . . . . . . . . . . . . . . 805The termination exit. . . . . . . . . . . . . . . . . . . . . . 806

The sample program, DFH$CUS1 . . . . . . . . . . . . . . . . . 806

Chapter 33. Using the programmable interface to CEDA . . . . . . . . 807When to use the programmable interface. . . . . . . . . . . . . . . 808Using DFHEDAP in a DTP environment . . . . . . . . . . . . . . . 808

Part 9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

Appendix A. Coding entries in the VTAM LOGON mode table . . . . . . 813Overview of the VTAM LOGON mode table . . . . . . . . . . . . . . 813TYPETERM device types and pointers to related LOGON mode data . . . . 814VTAM MODEENT macro operands . . . . . . . . . . . . . . . . . 816PSERVIC screen size values for LUTYPEx devices . . . . . . . . . . . 821Matching models and LOGON mode entries . . . . . . . . . . . . . 822LOGON mode definitions for CICS-supplied autoinstall models . . . . . . . 838

Appendix B. Default actions of the node abnormal condition program 841DFHZNAC—default actions for terminal error codes . . . . . . . . . . . 841CICS messages associated with VTAM errors . . . . . . . . . . . . . 847DFHZNAC—default actions for system sense codes. . . . . . . . . . . 852Action flag settings and meanings . . . . . . . . . . . . . . . . . 854

Appendix C. Analysing CICS restart information . . . . . . . . . . . 857

Appendix D. Using the transient data write-to-terminal program(DFH$TDWT) . . . . . . . . . . . . . . . . . . . . . . . . 859

DFH$TDWT—resource definitions required . . . . . . . . . . . . . . 859

Appendix E. Uppercase translation . . . . . . . . . . . . . . . . 861Translating national characters to uppercase . . . . . . . . . . . . . 861

Using the XZCIN exit . . . . . . . . . . . . . . . . . . . . . 861Using DFHTCTxx . . . . . . . . . . . . . . . . . . . . . . 861

Translating TS data sharing messages to uppercase . . . . . . . . . . 862

Appendix F. The example program for the XTSEREQ global user exit,DFH$XTSE . . . . . . . . . . . . . . . . . . . . . . . . . 863

Appendix G. Threadsafe XPI commands . . . . . . . . . . . . . . 879

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 881The CICS Transaction Server for z/OS library . . . . . . . . . . . . . 881

The entitlement set . . . . . . . . . . . . . . . . . . . . . . 881PDF-only books . . . . . . . . . . . . . . . . . . . . . . . 881

Other CICS books . . . . . . . . . . . . . . . . . . . . . . . 883

xvi CICS TS for z/OS: CICS Customization Guide

||

Books from related libraries . . . . . . . . . . . . . . . . . . . . 883MVS books . . . . . . . . . . . . . . . . . . . . . . . . . 883VTAM books . . . . . . . . . . . . . . . . . . . . . . . . 884Other related books. . . . . . . . . . . . . . . . . . . . . . 884

Determining if a publication is current . . . . . . . . . . . . . . . . 884

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . 885

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 905Programming interface information . . . . . . . . . . . . . . . . . 906Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 907

Sending your comments to IBM . . . . . . . . . . . . . . . . . 909

Contents xvii

xviii CICS TS for z/OS: CICS Customization Guide

Preface

What this book is aboutThis book provides the information needed to extend and modify an IBM® CICS®

Transaction Server for z/OS® system to match your requirements. It describes howyou can tailor your system by coding exit programs, by replacing specificCICS-supplied default programs with versions that you write yourself, and byadapting sample programs.

Who this book is forThis book is for those responsible for extending and enhancing a CICS system tomeet the special processing needs of an installation.

What you need to know to understand this bookTo use the information in this book, you need to be familiar with some of thearchitecture of CICS and the programming interface to CICS. General-useprogramming interface information is given in the CICS Application ProgrammingReference manual and the CICS System Programming Reference manual.

Resource definition information is in the CICS Resource Definition Guide.

To use the following chapters you need to be familiar with the IBM ACF/VTAMtelecommunications access method:v Chapter 9, “Writing a node error program,” on page 471v Chapter 10, “Writing a program to control autoinstall of terminals,” on page 505v Chapter 12, “Writing a program to control autoinstall of APPC connections,” on

page 531

If your task involves error processing, you may need to consult the CICS Messagesand Codes manual, the CICS Problem Determination Guide, or the CICS DiagnosisReference manual.

How to use this bookThe parts and chapters of the book are self-contained. Use an individual part orchapter as a guide when performing the task described in it.

Notes on terminologyIn this book, the term “CICS”, used without any qualification, refers to the CICSelement of IBM CICS Transaction Server for z/OS. The term “VTAM” refers toACF/VTAM. The term “APPC” (advanced program-to-program communication)refers to the LUTYPE6.2 intersystem connection (ISC) protocol.

© Copyright IBM Corp. 1977, 2011 xix

The term “MVS” refers to those services and functions that are provided by theBase Control Program (BCP) of OS/390®. The BCP is a base element of OS/390.

CICS Transaction Server for z/OS, Version 3 Release 1 supports CICS applicationswritten in:v Assembler languagev Cv COBOLv PL/I.

In this book, the phrase “the languages supported by CICS” refers to the abovelanguages.

Syntax notation and conventions used in this bookThe symbols { }, [ ], and | are used in the syntax descriptions of the EXEC CICScommands and macros referred to in this book. They are not part of the commandand you should not include them in your code. Their meanings are as follows:

v Braces { } enclose two or more alternatives, one of which you must code.v Square brackets [ ] tell you that the enclosed is optional.v The “or” symbol | separates alternatives.

In addition to these symbols, the following conventions apply:

v Punctuation symbols and uppercase characters should be coded exactly asshown.

v Lowercase characters indicate that user text should be coded as required.v Default values are shown like this: DEFAULT.v Options that are enclosed neither in braces { } nor in square brackets [ ] are

mandatory.

v The ellipsis ... means that the immediately preceding option can be coded one ormore times.

v All EXEC CICS commands require a delimiter appropriate to the language of theapplication. For a COBOL program this is ‘END-EXEC’, for example. Delimitersare not included in the syntax descriptions of the commands.

xx CICS TS for z/OS: CICS Customization Guide

Summary of changes

This book is based on the CICS Customization Guide for CICS Transaction Serverfor z/OS, Version 2 Release 3, SC34-6227-00. Changes from that edition aremarked by vertical bars in the left margin.

This part lists briefly the changes that have been made for the following recentreleases:v “Changes for CICS Transaction Server for z/OS, Version 3 Release 1.”v “Changes for CICS Transaction Server for z/OS, Version 2 Release 3.”v “Changes for CICS Transaction Server for z/OS, Version 2 Release 2” on page

xxii.v “Changes for CICS Transaction Server for OS/390, Version 1 Release 3” on page

xxiii.

Changes for CICS Transaction Server for z/OS, Version 3 Release 1The more significant changes for this edition are:

v Because of the removal of support for Java™ hot-pooling, the following itemshave been removed:

– Information about the user-replaceable programs DFHAPH8O and DFHJHPAT.DFHAPH8O was provided to allow you to alter the default LanguageEnvironment® run-time options for the Language Environment enclave wherea Java program object was to be run. DFHJHPAT was optional and could beused for your own purposes; it was called before a Java program object wasinvoked.

– The HOTPOOL attribute is removed from the DFHPGISX XPI calls INQUIREPROGRAM and SET PROGRAM.

– The TCB indicator UEPTH8 is no longer available in DFHUEPAR.

v Because of the removal of support for TCAM local terminals, the followinginformation has been removed or rewritten:

– The sections about the XTCTIN and XTCTOUT global user exits in theterminal control program (which were invoked on TCAM input and outputevents) have been removed.

– “Using TCAM with CICS” (chapter 28 in the CICS TS 2.3 book) has beenremoved.

– Chapter 8, “Writing a terminal error program,” on page 441 has beenrewritten.

v There are minor changes to the parameters passed to the exit programs at thefollowing global user exit points:

XICEREQCXPCREQCXTDEREQCXTSEREQC

v Appendix G, “Threadsafe XPI commands,” on page 879 is a new section.

Changes for CICS Transaction Server for z/OS, Version 2 Release 3The more significant changes for this edition were:

© Copyright IBM Corp. 1977, 2011 xxi

v A new global user exit, XICERES, in the interval EXEC interface control program,was described in “The XICERES global user exit” on page 154 and “Using theXICERES exit to check the availability of resources on the target region” on page622.

v A new global user exit, XPCERES, in the program control program, wasdescribed in “The XPCERES global user exit” on page 185, “Using theXPCERES exit to check the availability of resources on the target region” onpage 583, and “Using the XPCERES exit to check the availability of resources onthe target region” on page 587.

v The XSNEX signon and signoff global user exit, introduced as a temporarymigration aid in CICS TS 2.2, is to be retained in CICS TS 2.3. You can useXSNEX to make CICS handle EXEC CICS SIGNON and SIGNOFF commands inthe same way as in CICS TS 1.3 and earlier—see “Exit XSNEX” on page 210.

v “Writing Java classes to redirect JVM stdout and stderr output” on page 649 is anew section.

v The following new sections were added to Chapter 17, “Writing a distributedrouting program,” on page 605:– “Dealing with a disabled CorbaServer” on page 617– “Dealing with an abend on the target region” on page 626

Changes for CICS Transaction Server for z/OS, Version 2 Release 2The more significant changes for this edition were:

v Changes to global and task-related user exit programs:– Two new global user exits in the file control domain, XFCFRIN and

XFCFROUT, were described in “File control domain exits, XFCFRIN andXFCFROUT” on page 74.

– A new signon global user exit, XSNEX, was described in “Exit XSNEX” onpage 210.

– The following global user exits were modified:- XFAINTU—see “Bridge facility exit XFAINTU” on page 35.- XFCREQ and XFCREQC—see “File control EXEC interface API exits

XFCREQ and XFCREQC” on page 88- XFCAREQ and XFCAREQC—see “File control EXEC interface SPI exits

XFCAREQ and XFCAREQC” on page 100.- XRSINDI—see “Resource management install and discard exit XRSINDI”

on page 204

– A new sample global user exit program, DFH$LGLS, for use at the XLGSTRMexit, was described in “The sample program for the XLGSTRM exit,DFH$LGLS” on page 176.

– A new sample global user exit program, DFH$REQC, for use at the file controlstate program exit, XFCSREQC, was described in “The DFH$REQC sampleglobal user exit program” on page 122.

– “Making programs threadsafe” on page 15 was added to support theintroduction of OTE support in the CICS DB2® attachment facility.

– “Obligations of OPENAPI task-related user exits” on page 279 explained anumber of important OTE considerations.

– “Wait states in your task-related user exit program” on page 298 describedhow tasks that are active in a task-related user exit can be purged.

v Changes to user-replaceable programs:– A new user-replaceable program, DFHDJEP, was described in Chapter 23,

“Writing an EJB event program,” on page 661.

xxii CICS TS for z/OS: CICS Customization Guide

– Chapter 14, “Writing a program to control autoinstall of virtual terminals,” onpage 549 was extended to cover autoinstall of virtual terminals used by theCICS Link3270 bridge.

– Chapter 16, “Writing a dynamic routing program,” on page 571 was extendedto cover the dynamic routing of Link3270 bridge requests.

– A new user-replaceable program, DFHEJDNX, was described in Chapter 22,“Writing a distinguished name program for clients of enterprise beans,” onpage 657. DFHEJDNX is used to return a string representation of thedistinguished name of an Enterprise JavaBean (EJB) client, when the clienthas not presented an X.509 certificate containing a name. A sample programis provided.

– A new user-replaceable program, DFHSJJ8O, was described in Chapter 21,“Writing programs to customize JVMs,” on page 649. DFHSJJ8O allows youto specify the run-time options that are used to create the LanguageEnvironment enclave in which a CICS JVM runs.

– Two new user-replaceable programs, DFHAPH8O and DFHJHPAT, weredescribed. DFHAPH8O allows you to alter the default Language Environmentrun-time options for the Java hot-pooling environment. DFHJHPAT is anoptional module that can be used for your own purposes, such as tracing.(These user-replaceable programs were removed in CICS Transaction Serverfor z/OS Version 3 Release 1.)

– The distributed routing program, DFHDSRP, was modified. You can now useDFHDSRP to route requests for enterprise beans and CORBA statelessobjects, as well as BTS activities and non-terminal-related EXEC CICSSTART requests. See “Routing method requests for enterprise beans andCORBA stateless objects” on page 610.

– The security exit program for IIOP, DFHXOPUS, was modified. You can nowuse DFHXOPUS to assign USERIDs to inbound EJB requests, as well as toCORBA requests. See Chapter 20, “Writing a security exit program for IIOP,”on page 645.

v Miscellaneous changes:– The use of Language Environment is assumed in all programming guidance

information. Support for non-Language Environment conforming compilerswas withdrawn. Runtime support is maintained for non-Language Environmentconforming compilers and runtime libraries, but no guidance is given.

Changes for CICS Transaction Server for OS/390, Version 1 Release 3These were the most significant changes for this edition:

v The following new global user exits were described in Chapter 1, “Global userexit programs,” on page 3:– XBMIN and XBMOUT, in CICS Basic Mapping Support– XLDLOAD and XLDELETE, in the CICS loader domain

v The following global user exits were modified:– XDTAD, XDTLC, and XDTRD– XISCONA– XNQEREQ and XNQEREQC– XFAINTU– XRSINDI– XTSPTIN, XTSQRIN, and XTSQROUT– XTSEREQ and XTSEREQC

Summary of changes xxiii

v Information about using the dynamic routing program to route DPL requests andtransactions started by EXEC CICS START commands was added to Chapter 16,“Writing a dynamic routing program,” on page 571.

v A new user-replaceable program, DFHDSRP, was described in Chapter 17,“Writing a distributed routing program,” on page 605.

v A new user-replaceable program, DFHJVMAT, was described in Chapter 21,“Writing programs to customize JVMs,” on page 649. DFHJVMAT can be used tocustomize the execution attributes of the CICS Java virtual machine.

v A new user-replaceable program, DFHXOPUS, was described in Chapter 20,“Writing a security exit program for IIOP,” on page 645. DFHXOPUS provides aUSERID for inbound IIOP requests.

xxiv CICS TS for z/OS: CICS Customization Guide

2 CICS TS for z/OS: CICS Customization Guide

Chapter 1. Global user exit programs

This chapter describes the CICS global user exit points, and how you can usethem, in conjunction with programs of a special type that you write yourself (globaluser exit programs), to customize your CICS system. The chapter is divided intothe following sections:

1. “Overview — what is a global user exit?” is an introduction to global user exits,describing their main features and what they can be used for.

2. “Writing global user exit programs” on page 4 covers topics that you need toconsider when writing a global user exit program. It deals with the following:v “Register conventions” on page 4v “31-bit addressing implications” on page 5v “Using CICS services” on page 5v “Using channels and containers” on page 6v “Assembler programs and LEASM” on page 6v “Using EDF with global user exits” on page 6v “The global work area” on page 7v “Making trace entries” on page 7v “Parameters passed to the global user exit program” on page 7v “Returning values to CICS” on page 11v “Restrictions on the use of fields as programming interfaces” on page 12v “Exit programs and the CICS storage protection facility” on page 12v “Errors in user exit programs” on page 13v “Defining, enabling, and disabling an exit program” on page 14v “Invoking more than one exit program at a single exit” on page 14v “Invoking a single exit program at more than one exit” on page 15v “Making programs threadsafe” on page 15v “Sample global user exit programs” on page 16.

3. “List of global user exit points” on page 22 lists the global user exit points inalphabetical order. The sections that follow contain detailed information abouteach global user exit point, including the place in the CICS code at which itoccurs, and the specific (as distinct from the standard) parameters that arepassed to an exit program.

Overview — what is a global user exit?A global user exit point (sometimes referred to simply as a “global user exit”) is aplace in a CICS module or domain 1 at which CICS can transfer control to aprogram that you have written (a global user exit program), and at which CICS canresume control when your exit program has finished its work. You do not have touse any of the global user exits, but you can use them to extend and customize thefunction of your CICS system according to your own requirements. For a completelist of the global user exit points, see Table 2 on page 22.

Each global user exit point has a unique identifier, and is located at a point in themodule or domain at which it could be useful to do some extra processing. Forexample, at exit point XSTOUT in the statistics domain, an exit program can begiven control before each statistics record is written to the SMF data set, and can

1. A domain is an isolated functional unit of CICS Transaction Server for z/OS, Version 3 Release 1 that communicates with the restof CICS and with other programs using a set of strictly defined and controlled interfaces.

© Copyright IBM Corp. 1977, 2011 3

||

access the relevant statistics record. You might want to use an exit program at thisexit point to examine the statistics record and suppress the writing of unwantedrecords.

Global user exit support is provided automatically by CICS. However, there areseveral conventions that govern how you write your exit program, which aredescribed in “Writing global user exit programs.” Also in that section is a list of thestandard parameters that the calling modules and domains pass to an exit program,and some information about returning values to the caller.

Because global user exit programs work as if they were part of the CICS module ordomain, there are limits on the use you can make of CICS services. Most globaluser exit programs cannot use EXEC CICS commands. By contrast, most globaluser exit programs can invoke some CICS services using the exit programminginterface (XPI). For more information, see “Using CICS services” on page 5.

Note: Neither source nor object compatibility of CICS management modules isguaranteed from release to release. Any changes that affect exit programsare documented in the appropriate manual.

Writing global user exit programsA global user exit program must be written in assembler language and must bequasireentrant. However, if your user exit program calls the XPI, it must be fullyreentrant. 2 (For details about coding programs using XPI calls, refer to Chapter 3,“The user exit programming interface (XPI),” on page 311.)

Register conventionsThe following register values are provided on entry to an exit program:

v Register 1 contains the address of the user exit parameter list DFHUEPAR.Write-to-operator (WTO) commands use register 1. If your exit program usesWTO commands, you should save the address of DFHUEPAR first.

v Register 13 contains the address of the standard register save area where yourexit program should store its own registers immediately after being invoked. Thisaddress is also in the field UEPEPSA in the parameter list pointed to by register1.

If you want to issue operating system requests that use register 13 to point to asave area, you must switch register 13 to point to another save area. You mustrestore register 13 to its original contents before returning from your user exitprogram to the caller.

v Register 14 contains the return address to which the exit program should branchon completion of its work. You do this using the BR 14 instruction after restoringthe calling module’s registers, or using the RETURN macro.

v Register 15 contains the entry address of the exit program.

No other register values are guaranteed, and they should not be relied on. The exitprogram should save and restore any registers that it modifies, using the save areaaddressed by register 13.

2. A “reentrant” program is coded to allow one copy of itself to be used concurrently by several tasks; it does not modify itself whilerunning. A “quasireentrant” program is serially reusable by different tasks. When it receives control it must be in the same state aswhen it relinquished control. Such a program can modify itself while running, and is therefore not fully reentrant.

global user exit programs


31-bit addressing implicationsv The global user exit is invoked in 31-bit AMODE.v The global user exit may be either RMODE 24 or RMODE ANY.v If you find it necessary to switch to 24-bit AMODE in the exit program, be sure to

return correctly in 31-bit AMODE.

v Ensure the exit program is in 31-bit AMODE for XPI calls.v Some of parameters passed in DFHUEPAR are addresses of storage above the

16MB line.

Access register implicationsv The global user exit is invoked in primary-space translation mode. For

information about translation modes, see the IBM ESA/370 Principles ofOperation manual.

v The contents of the access registers are unpredictable. For information aboutaccess registers, see the IBM ESA/370 Principles of Operation manual.

v If the global user exit modifies any access registers, it must restore them beforereturning control. CICS does not provide a save area for this purpose.

v The global user exit must return control in primary addressing mode.

Using CICS servicesThe rules governing the use of CICS services in exit programs vary, depending onthe exit point from which the exit program is being invoked. The following generalrules apply:

v No CICS services can be invoked from any exit point in the dispatcher domain.v CICS services can be invoked using the exit programming interface (XPI) from

most exits. If you use the XPI, note the rules and restrictions that are listed foreach exit and each of the XPI macros. The XPI is described in Chapter 3, “Theuser exit programming interface (XPI),” on page 311.

v Some CICS services can be requested using EXEC CICS commands from someexits. The valid commands are listed in the detailed descriptions of the exits. Ifno commands are listed, it means that no EXEC CICS API or SPI commands aresupported. EXEC CICS commands that cause an XCTL (either directly orimplied)—for example, EXEC CICS XCTL or EXEC CICS SHUTDOWN—mustnever be used.

An exit program invoked at an exit that does not support the use of EXEC CICScommands should not call a task-related user exit program (TRUE). (Calling aTRUE is equivalent to issuing an EXEC CICS command.) Exceptions to this ruleare programs invoked from the XFCFRIN and XFCFROUT exits, which may calla TRUE. TRUEs are described in Chapter 2, “Task-related user exit programs,”on page 275.

Note: In exits which support the use of EXEC CICS File Control commands, filecommands that form a related sequence (such as EXEC CICS STARTBR,EXEC CICS READNEXT, and EXEC CICS ENDBR) should all be issuedin the same invocation of the exit program.

For example, if one invocation of an exit program issues an EXEC CICSSTARTBR command, and the next invocation of the exit program for thatsame task issues an EXEC CICS READNEXT command, the READNEXTfails with an INVREQ condition.

v All exit programs that issue EXEC CICS commands must first address the EIB.This is not done automatically via the DFHEIENT macro, as is the case with


Chapter 1. Global user exit programs 5

normal EXEC assembler-language programs. Therefore, the first EXECcommand to be issued from an exit program must be EXEC CICS ADDRESSEIB (eib-register), where “eib-register” is the default register (R11) or the registergiven as a parameter to the DFHEIENT macro.

All exit programs that issue EXEC CICS commands, and that use the DFHEIENTmacro, should use the DFHEIRET macro to set a return code and return toCICS. See “Returning values to CICS” on page 11.

Important

v If your global user exit program does not contain EXEC CICS commands,do not use the CICS command-level translator when assembling theprogram.

v Do not make non-CICS (for example, RACF® or MVS™) system servicecalls from global user exit programs.

v If an operating system request causes a wait, your whole CICS system willstop until the operating system request has been serviced.

Using EXEC CICS and XPI calls in the same exit programThere are a number of exits where you can use both EXEC CICS commands andXPI calls, but you should ensure that there is no conflict in the usage of register 13.To avoid such conflict, use the DATAREG option on the DFHEIENT macro (see“XPI register usage” on page 318 for information).

For an example of how to use EXEC CICS commands and XPI calls in the sameglobal user exit program, see Appendix F, “The example program for the XTSEREQglobal user exit, DFH$XTSE,” on page 863

Using channels and containersGlobal user exit programs cannot access channels and containers created byapplication programs. They can, however, create their own channels and pass themto programs which they call.

For information about channels and containers, see the CICS ApplicationProgramming Guide.

Assembler programs and LEASMAssembler programs translated with the LEASM option cannot be used as globaluser exit programs.

LEASM is used to produce Language Environment conforming main programs inassembler. For information about the LEASM translator option, see the CICSApplication Programming Guide.

Using EDF with global user exitsIf you use the Execution Diagnostic Facility (EDF) to debug your applications, youmust take care when compiling exit programs that issue EXEC CICS commands.

Normally, if an exit program issues EXEC CICS commands, these are displayed byEDF, if the latter is active. They appear between the “Start of Command” and “Endof Command” screens for the command that caused the exit to be driven. If youwant to suppress the display of EXEC CICS commands issued by your exit



|

|||

||

|

||

|||

program, you must specify the NOEDF option when you translate the program. Youshould always specify NOEDF for programs in a production environment.

If an exit program that may be invoked during recovery processing issues EXECCICS commands, you must translate it with the NOEDF option. Failure to do somay cause EDF to abend.

The global work areaWhen you enable an exit program, you can ask CICS to provide a global work areafor the exit program. An exit program can have its own global work area, or it canshare a work area that is owned by another exit program. Note that the work areais associated with the exit program rather than with the exit point. For ease ofproblem determination, the global work area should be shared only by exitprograms that are invoked from the same management module or domain. Theaddress and length of the global work area are addressed by parameters UEPGAAand UEPGAL of the DFHUEPAR parameter list, which is described in “DFHUEPARstandard parameters” on page 8. If a user exit program does not own a global workarea, UEPGAA is set to zero.

Application programs can communicate with user exit programs that use or sharethe same global work area. The application program uses the EXEC CICSEXTRACT EXIT command to obtain the address and length of the global work area.

A work area is freed only when all of the exit programs that use it are disabled. Forexamples of how to use a global work area, see the sample global user exitprograms. They are listed in “Sample global user exit programs” on page 16.

Making trace entries

If tracing is active, an entry in the CICS trace table can be made immediatelybefore and immediately after the execution of an exit program. To specify that theseentries are to be made, use the UE option of either:v The CETR transactionv The EXEC CICS SET TRACETYPE command.

For global user exits in domains, extra trace calls giving more information are alsoavailable if you have set the AP option of EXEC CICS SET TRACETYPE to level 1or 2. For information about trace entries, refer to the CICS Problem DeterminationGuide.

In some cases, when tracing is active, you can also make trace entries from withina user exit program, using the XPI DFHTRPTX TRACE_PUT macro described inChapter 3, “The user exit programming interface (XPI),” on page 311. The individualdescriptions of the global user exit points show whether the XPI DFHTRPTX macrocan be used at each point.

Parameters passed to the global user exit programThe address of a parameter list is passed to the user exit program in register 1.The list contains some standard parameters that are passed to all global user exitprograms, and may also contain some exit-specific parameters that are unique tothe exit point from which the exit program is being invoked. Not all of the exit pointshave these extra parameters.



The exit-specific parameters are described with the individual exits in the section“List of global user exit points” on page 22. The standard parameter list is describedin the following section.

You can map the parameter list using the DSECT DFHUEPAR, which is generatedby the macro instructionDFHUEXIT TYPE=EP,ID=exit_point_identifier

The ID parameter provides the extra data definitions that you need to map anyexit-specific parameters. For example, the macro instructionDFHUEXIT TYPE=EP,ID=XTDIN

generates the DSECT to map the standard parameters followed by the parametersthat are specific to exit point XTDIN in the transient data program. If your exitprogram is to be invoked at more than one exit point, you can code up to 256characters of relevant exit identifiers on a single DFHUEXIT macro instruction. Forexample:DFHUEXIT TYPE=EP,ID=(XMNOUT,XSTOUT,XTDIN)

If your exit program is to be invoked at every global user exit point, you can code:DFHUEXIT TYPE=EP,ID=ALL

If your user exit program is to be used both as a global user exit program and as atask-related user exit program, you must code both:DFHUEXIT TYPE=EP,ID=exit_point_identifier

and:DFHUEXIT TYPE=RM

(in this order) to generate the DSECTs appropriate to both types of user exit.

If a global user exit program needs to use the DFHRMCAL macro to invoke anexternal RMI, the DFHRMCAL macro instruction must follow the DFHUEXIT macro.

DFHUEPAR standard parameters

DFHUEPAR DSECT* STANDARD PARAMETERSUEPEXN DS A ADDRESS OF EXIT NUMBERUEPGAA DS A ADDRESS OF GLOBAL WORK AREA* (ZERO = NO WORK AREA)UEPGAL DS A ADDRESS OF GLOBAL WORK AREA LENGTHUEPCRCA DS A ADDRESS OF CURRENT RETURN-CODEUEPTCA DS A RESERVEDUEPCSA DS A RESERVEDUEPEPSA DS A ADDRESS OF REGISTER SAVE AREA* FOR USE BY EXIT PROGRAMUEPHMSA DS A ADDRESS OF SAVE AREA USED FOR* HOST MODULE’S REGISTERSUEPGIND DS A ADDRESS OF CALLER’S TASK INDICATORSUEPSTACK DS A ADDRESS OF KERNEL STACK ENTRYUEPXSTOR DS A ADDRESS OF STORAGE FOR XPI PARAMETERSUEPTRACE DS A ADDRESS OF TRACE FLAG

UEPEXNpoints to a 1-byte binary field whose contents identify the global user exit point



from which the exit program is being invoked. You need this information if yourexit program can be invoked from more than one exit point.

DFHUEXIT TYPE=EP generates a list of equated values that relate the exitnames (exitids) to the exit numbers used internally by CICS to identify the exits.You should always use the exitids, because the exit numbers may change inany future releases of CICS.

UEPGAApoints to the global work area that was provided for the exit program when itwas enabled. This is set to zero if no global work area is provided.

UEPGALpoints to a halfword that contains the length of the global work area.

UEPCRCApoints to a halfword that is to contain the return code value from the exitprogram. When more than one program is called at a user exit, this fieldcontains (on entry to the second and subsequent programs) the return codethat was set by the previously invoked program.

For an example of how an exit program can set a different return code from thatreturned by a previous exit program at the same exit point, see the codesnippet in “Invoking more than one exit program at a single exit” on page 14.

UEPTCApoints to fetch-protect storage. Use of this field results in an abend ASRD atexecution time.

UEPCSApoints to fetch-protect storage. Use of this field results in an abend ASRD atexecution time.

UEPEPSApoints to a save area in which the exit program should store its own registerson entry. When the exit program is entered, register 13 is also pointing to thisarea. The convention is to save registers 14, 15, 0–12 at offset 12 (decimal)onward.

UEPHMSApoints to the save area containing the registers of the calling module. Values forregisters 14, 15, 0–13 are stored in this order from offset 12 (decimal) in thisarea.

Apart from register 15, which contains the return code value from the exitprogram, the values in this save area are used by CICS to reload the registerswhen returning to the calling CICS module. They should not be corrupted.

This address is not passed to global user exit programs invoked from exitpoints in CICS domains.

UEPGINDpoints to a 3-byte field containing indicators for use in AP domain user exits.For non-AP domain user exits, the indicators are always zero.

The first indicator byte can take one of two symbolic values, UEPGANY andUEPGCICS, which you can test to determine whether data locations can beabove or below 16MB, and whether the application’s storage is in CICS-key oruser-key storage:

UEPGANYThe application can accept addresses above 16MB. If the symbolicvalue is not UEPGANY, the application must be returned an address



|||

below 16MB.

UEPGCICSThe application’s working storage and the task’s life-time storage are inCICS-key storage (TASKDATAKEY=CICS). If the symbolic value is notUEPGCICS, the application’s working storage and the task’s life-timestorage are in user-key storage (TASKDATAKEY=USER).

The second and third bytes contain a value indicating the TCB mode of theglobal user exit program's caller. This is represented in DFHUEPAR as both atwo-character code and a symbolic value, as follows:

Table 1. TCB indicators in DFHUEPAR. Description

Symbolicvalue

2-bytecode

Description

UEPTQR QR The quasi-reentrant mode TCB

UEPTRO RO The resource-owning mode TCB

UEPTCO CO The concurrent mode TCB

UEPTSZ SZ The FEPI mode TCB

UEPTRP RP The ONC/RPC mode TCB

UEPTFO FO The file-owning mode TCB

UEPTSL SL The sockets listener mode TCB

UEPTSO SO The sockets mode TCB

UEPTS8 S8 The secure sockets layer mode TCB

UEPTD2 D2 The CICS–DB2 housekeeping mode TCB

UEPTJ8 J8 The J8 open TCB, used for JVMs that are in CICS key

UEPTJ9 J9 The J9 open TCB, used for JVMs that are in user key

UEPTJM JM The JM open TCB, used for the master JVM that initializes theshared class cache

UEPTL8 L8 An L8 open TCB, used for OPENAPI TRUEs, or OPENAPIprograms that are in CICS key

UEPTL9 L9 An L9 open TCB, used for OPENAPI programs that are in userkey

UEPTX8 X8 An X8 open TCB, used for C and C++ programs, compiled withthe XPLINK option, that are in CICS key

UEPTX9 X9 An X9 open TCB, used for C and C++ programs, compiled withthe XPLINK option, that are in user key

UEPSTACKpoints to the kernel stack entry. This value must be moved to the exit program’sregister 13 before invoking the XPI. For more information, refer to Chapter 3,“The user exit programming

cics customization guide - ibm€¦ · cics transaction server for z/os cics customization guide...

Documents