Size:
3.35 Mb
Download

CICS® Transaction Server for OS/390®

CICS Customization Guide

Release 3

IBM

SC33-1683-02

CICS® Transaction Server for OS/390®

CICS Customization Guide

Release 3

IBM

SC33-1683-02

Note!

Before using this information and the product it supports, be sure to read the general information under ªNoticesº on page xvii.

Third edition (March 1999)

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

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

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below.

At the back of this publication is a page entitled ªSending your comments to IBMº. If you want to make comments, but the methods described are not available to you, please address them to:

IBM United Kingdom Laboratories, Information Development,

Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 1977, 1999. All rights reserved.

US Government Users Restricted Rights ± Use duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Programming interface information . . . . . . . . . . . .

. .

.

.

. xviii

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Preface . . . . . . . . . . . . . . . . . . . . . .

. .

.

.

.

xxi

What this book is about . . . . . . . . . . . . . . . .

. .

.

.

.

xxi

Who this book is for. . . . . . . . . . . . . . . . . .

. .

.

.

.

xxi

What you need to know to understand this book . . . . . . .

. .

.

.

.

xxi

How to use this book . . . . . . . . . . . . . . . . .

. . . . . xxi

Notes on terminology . . . . . . . . . . . . . . . . . . . . . . xxi

Syntax notation and conventions used in this book . . . . . .

. .

.

.

. xxii

Bibliography . . . . . . . . . . . . . . . . . . . .

. .

.

.

.

xxiii

CICS Transaction Server for OS/390 . . . . . . . . . . .

. .

.

.

. xxiii

CICS books for CICS Transaction Server for OS/390 . . . .

. .

.

.

. xxiii

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

. .

.

.

. xxiv

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

. .

.

.

. xxiv

Books from related libraries . . . . . . . . . . . . . . . . . . . . xxiv

ACF/TCAM books . . . . . . . . . . . . . . . . .

. .

.

.

. xxiv

MVS books . . . . . . . . . . . . . . . . . . . .

. .

.

.

.

xxv

VTAM books . . . . . . . . . . . . . . . . . . .

. . . . . xxv

Other related books . . . . . . . . . . . . . . . . . . . . . . xxv

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

. .

.

.

. xxvi

Summary of changes. . . . . . . . . . . . . . . . . . . . . . xxvii Changes for this edition . . . . . . . . . . . . . . . . . . . . . xxvii

Changes for CICS Transaction Server for OS/390 Release 2

.

.

. . .

.

. xxvii

Changes for CICS Transaction Server for OS/390 Release 1

.

.

. . .

.

.xxviii

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

1

Chapter 1. Global user exit programs . . . . . . . . . . . . . . .

3

Overview Ð what is a global user exit? . . . . . . . . . . . . . . .

3

Global user exit programs . . . . . . . . . . . . . . . . . . . .

4

Register conventions . . . . . . . . . . . . . . . . . . . . .

4

31-bit addressing implications . . . . . . . . . . . . . . . . . .

5

Using CICS services . . . . . . . . . . . . . . . . . . . . .

5

Using EDF with global user exits . . . . . . . . . . . . . . . . .

6

The global work area . . . . . . . . . . . . . . . . . . . . .

6

Making trace entries . . . . . . . . . . . . . . . . . . . . .

7

Parameters passed to the global user exit program . . . . . . . . . .

7

Returning values to CICS . . . . . . . . . . . . . . . . . . .

10

Restrictions on the use of ®elds as programming interfaces. . . . . . .

11

Exit programs and the CICS storage protection facility . . . . . . . . .

11

Errors in user exit programs. . . . . . . . . . . . . . . . . . .

12

De®ning, enabling, and disabling an exit program. . . . . . . . . . .

13

Invoking more than one exit program at a single exit . . . . . . . . .

13

Invoking a single exit program at more than one exit . . . . . . . . .

14

Sample global user exit programs . . . . . . . . . . . . . . . .

14

List of global user exit points . . . . . . . . . . . . . . . . . . .

19

Activity keypoint program exit XAKUSER . . . . . . . . . . . . . . .

25

Exit XAKUSER . . . . . . . . . . . . . . . . . . . . . . .

25

Basic Mapping Support exits XBMIN and XBMOUT . . . . . . . . . . .

27

© Copyright IBM Corp. 1977, 1999

iii

Exit XBMIN . . . . . . . . . . . . . . . . . . . . . . . . .

28

Exit XBMOUT . . . . . . . . . . . . . . . . . . . . . . . .

28

The ®eld element table structure. . . . . . . . . . . . . . . . .

29

Programming the XBMIN exit . . . . . . . . . . . . . . . . . .

30

Programming the XBMOUT exit . . . . . . . . . . . . . . . . .

30

Bridge facility exit . . . . . . . . . . . . . . . . . . . . . . .

32

Exit XFAINTU . . . . . . . . . . . . . . . . . . . . . . . .

32

Data tables management exits XDTRD, XDTAD, and XDTLC . . . . . . .

33

Exit XDTRD . . . . . . . . . . . . . . . . . . . . . . . .

33

Exit XDTAD. . . . . . . . . . . . . . . . . . . . . . . . .

36

Exit XDTLC . . . . . . . . . . . . . . . . . . . . . . . . . 37

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

39

DBCTL tracking program exits XXDFB and XXDTO . . . . . . . . . . .

40

Exit XXDFB. . . . . . . . . . . . . . . . . . . . . . . . .

40

Exit XXDTO . . . . . . . . . . . . . . . . . . . . . . . .

41

Dispatcher domain exits XDSBWT and XDSAWT . . . . . . . . . . . .

42

Exit XDSBWT . . . . . . . . . . . . . . . . . . . . . . . .

42

Exit XDSAWT . . . . . . . . . . . . . . . . . . . . . . . .

42

DL/I interface program exits XDLIPRE and XDLIPOST . . . . . . . . . .

44

Exit XDLIPRE . . . . . . . . . . . . . . . . . . . . . . . .

45

Exit XDLIPOST . . . . . . . . . . . . . . . . . . . . . . .

47

Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT . . . .

49

Exit XDUREQ . . . . . . . . . . . . . . . . . . . . . . . .

49

The sample program for the XDUREQ exit, DFH$XDRQ . . . . . . . .

52

Exit XDUREQC . . . . . . . . . . . . . . . . . . . . . . .

52

Exit XDUCLSE . . . . . . . . . . . . . . . . . . . . . . .

55

Exit XDUOUT . . . . . . . . . . . . . . . . . . . . . . . .

55

Enqueue EXEC interface program exits XNQEREQ and XNQEREQC . . . .

57

Exit XNQEREQ . . . . . . . . . . . . . . . . . . . . . . .

57

Exit XNQEREQC. . . . . . . . . . . . . . . . . . . . . . .

58

The command-level parameter structure . . . . . . . . . . . . . .

59

Sample exit program, DFH$XNQE . . . . . . . . . . . . . . . .

63

EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT . . . 65

The command parameter list . . . . . . . . . . . . . . . . . .

65

Bypassing commands . . . . . . . . . . . . . . . . . . . . .

66

Exit XEIIN . . . . . . . . . . . . . . . . . . . . . . . . .

66

Exit XEISPIN . . . . . . . . . . . . . . . . . . . . . . . .

67

Exit XEIOUT . . . . . . . . . . . . . . . . . . . . . . . .

68

Exit XEISPOUT . . . . . . . . . . . . . . . . . . . . . . .

68

File control EXEC interface API exits XFCREQ and XFCREQC. . . . . . . 70

The command-level parameter structure . . . . . . . . . . . . . .

71

Modifying ®elds in the command-level parameter structure . . . . . . .

74

Modifying the EID . . . . . . . . . . . . . . . . . . . . . .

76

Use of the task token UEPTSTOK . . . . . . . . . . . . . . . .

77

Use of the parameter UEPFSHIP . . . . . . . . . . . . . . . . .

77

The EIB . . . . . . . . . . . . . . . . . . . . . . . . . .

78

Example of how XFCREQ and XFCREQC can be used . . . . . . . .

78

Exit XFCREQ . . . . . . . . . . . . . . . . . . . . . . . .

79

Exit XFCREQC . . . . . . . . . . . . . . . . . . . . . . .

80

File control EXEC interface SPI exits XFCAREQ and XFCAREQC . . . . .

83

Exit XFCAREQ . . . . . . . . . . . . . . . . . . . . . . .

84

Exit XFCAREQC . . . . . . . . . . . . . . . . . . . . . . .

85

The command-level parameter structure . . . . . . . . . . . . . .

86

Modifying ®elds in the command-level parameter structure . . . . . . .

91

Modifying the EID . . . . . . . . . . . . . . . . . . . . . .

94

Use of the task token UEPTSTOK . . . . . . . . . . . . . . . .

95

iv CICS TS for OS/390: CICS Customization Guide

Modifying user arguments . . . . . . . . . . . . . . . . . . . 95 File control ®le state program exits XFCSREQ and XFCSREQC . . . . . . 96

Exit XFCSREQ . . . . . . . . . . . . . . . . . . . . . .

.

97

Exit XFCSREQC . . . . . . . . . . . . . . . . . . . . . .

. 100

File control open/close program exit XFCNREC . . . . . . . . . . .

. 105

Exit XFCNREC . . . . . . . . . . . . . . . . . . . . . .

. 106

File control quiesce receive exit, XFCVSDS . . . . . . . . . . . . .

. 107

Exit XFCVSDS . . . . . . . . . . . . . . . . . . . . . .

. 108

File control quiesce send exit XFCQUIS . . . . . . . . . . . . . .

.

110

File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and

 

 

XFCLDEL . . . . . . . . . . . . . . . . . . . . . . . .

.

112

Order of invocation . . . . . . . . . . . . . . . . . . . . .

.

112

Exit XFCBFAIL, ®le control backout failure exit. . . . . . . . . . .

.

112

Exit XFCBOUT, ®le control backout exit . . . . . . . . . . . . .

.

117

Exit XFCBOVER, ®le control backout override exit . . . . . . . . .

. 119

Exit XFCLDEL, ®le control logical delete exit . . . . . . . . . . .

. 122

Front End Programming Interface exits XSZARQ and XSZBRQ . . . . .

. 125

ªGood morningº message program exit XGMTEXT . . . . . . . . . .

. 126

Intersystem communication program exits XISCONA and XISLCLQ . . . .

. 127

The XISCONA exit . . . . . . . . . . . . . . . . . . . . .

. 127

The XISLCLQ exit . . . . . . . . . . . . . . . . . . . . . . 130

Interval control program exits XICREQ, XICEXP, and XICTENF

.

.

. .

.

. 132

Exit XICREQ . . . . . . . . . . . . . . . . . .

.

.

. .

.

. 132

Exit XICEXP . . . . . . . . . . . . . . . . . .

.

.

. .

.

. 133

Exit XICTENF . . . . . . . . . . . . . . . . . . . . . . . . 133 Interval control EXEC interface program exits XICEREQ and XICEREQC . . . 134

Exit XICEREQ . . . . . . . . . . . . . . . . . . . . . . .

. 134

Exit XICEREQC . . . . . . . . . . . . . . . . . . . . . .

. 135

The command-level parameter structure . . . . . . . . . . . . .

. 137

Loader domain exits XLDLOAD and XLDELETE . . . . . . . . . . .

. 147

Exit XLDLOAD . . . . . . . . . . . . . . . . . . . . . .

. 147

Exit XLDELETE . . . . . . . . . . . . . . . . . . . . . .

. 148

Log manager domain exit XLGSTRM . . . . . . . . . . . . . . .

. 149

Exit XLGSTRM . . . . . . . . . . . . . . . . . . . . . .

. 150

An example of how XLGSTRM can be used. . . . . . . . . . . .

. 151

Message domain exit XMEOUT . . . . . . . . . . . . . . . . .

. 152

Exit XMEOUT . . . . . . . . . . . . . . . . . . . . . . .

. 153

The sample XMEOUT global user exit programs . . . . . . . . . .

. 155

Monitoring domain exit XMNOUT . . . . . . . . . . . . . . . . .

. 156

Exit XMNOUT . . . . . . . . . . . . . . . . . . . . . . . . 156

Program control program exits XPCREQ, XPCREQC, XPCFTCH, XPCHAIR,

 

XPCTA, and XPCABND . . . . . . . . . . . . . . . . . . . . 158

XPCREQ and XPCREQC . . . . . . . . . . . . . . . . . .

. 158

Exit XPCFTCH . . . . . . . . . . . . . . . . . . . . . .

. 165

Exit XPCHAIR . . . . . . . . . . . . . . . . . . . . . . .

. 166

Exit XPCTA . . . . . . . . . . . . . . . . . . . . . . . .

. 168

Exit XPCABND . . . . . . . . . . . . . . . . . . . . . .

. 169

Resource manager interface program exits XRMIIN and XRMIOUT . . . .

. 171

Exit XRMIIN . . . . . . . . . . . . . . . . . . . . . . .

. 171

Exit XRMIOUT. . . . . . . . . . . . . . . . . . . . . . . . 172

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

. 173

Exit XRSINDI . . . . . . . . . . . . . . . . . . . . . . . . 173

Signon and signoff exits XSNON and XSNOFF . . . . . . . . . . .

. 177

Exit XSNON . . . . . . . . . . . . . . . . . . . . . . .

. 177

Exit XSNOFF . . . . . . . . . . . . . . . . . . . . . . . . 178

Statistics domain exit XSTOUT . . . . . . . . . . . . . . . . .

. 180

Contents v

Exit XSTOUT . . . . . . . . . . . . . . . . . . . . . . . . 180

System recovery program exit XSRAB . . . . . . . . . . . . . . .

. 182

Exit XSRAB. . . . . . . . . . . . . . . . . . . . . . . . . 182

System termination program exit XSTERM . . . . . . . . . . . . .

. 186

Exit XSTERM . . . . . . . . . . . . . . . . . . . . . . . . 186

Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and

 

XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . .

. 187

Exit XTSQRIN . . . . . . . . . . . . . . . . . . . . . . .

. 187

Exit XTSQROUT . . . . . . . . . . . . . . . . . . . . . .

. 188

Exit XTSPTIN . . . . . . . . . . . . . . . . . . . . . . .

. 190

Exit XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . 191 Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC . 193

Exit XTSEREQ . . . . . . . . . . . . . . . . . . . . . .

. 194

Exit XTSEREQC . . . . . . . . . . . . . . . . . . . . . .

. 195

The command-level parameter structure . . . . . . . . . . . . .

. 196

Terminal allocation program exit XALCAID . . . . . . . . . . . . .

. 203

Exit XALCAID . . . . . . . . . . . . . . . . . . . . . . . . 203

Terminal control program exits XTCIN, XTCOUT, XTCATT, XTCTIN, and

 

XTCTOUT . . . . . . . . . . . . . . . . . . . . . . . .

. 205

Exit XTCIN . . . . . . . . . . . . . . . . . . . . . . . .

. 205

Exit XTCOUT . . . . . . . . . . . . . . . . . . . . . . .

. 205

Exit XTCATT . . . . . . . . . . . . . . . . . . . . . . .

. 206

Exit XTCTIN . . . . . . . . . . . . . . . . . . . . . . .

. 206

Exit XTCTOUT . . . . . . . . . . . . . . . . . . . . . .

. 207

`Terminal not known' condition exits XALTENF and XICTENF . . . . . .

. 208

The exits . . . . . . . . . . . . . . . . . . . . . . . . .

. 208

Exit XALTENF . . . . . . . . . . . . . . . . . . . . . . .

. 209

Exit XICTENF . . . . . . . . . . . . . . . . . . . . . . .

. 212

The sample program for the XALTENF and XICTENF exits, DFHXTENF .

. 214

Transaction manager domain exit XXMATT . . . . . . . . . . . . .

. 216

Exit XXMATT . . . . . . . . . . . . . . . . . . . . . . . . 216

Transient data program exits XTDREQ, XTDIN, and XTDOUT . . . . . .

. 218

Exit XTDREQ . . . . . . . . . . . . . . . . . . . . . . .

. 218

Exit XTDIN . . . . . . . . . . . . . . . . . . . . . . . .

. 219

Exit XTDOUT . . . . . . . . . . . . . . . . . . . . . . . . 220

Transient data EXEC interface program exits XTDEREQ and XTDEREQC .

. 221

Exit XTDEREQ . . . . . . . . . . . . . . . . . . . . . .

. 221

Exit XTDEREQC . . . . . . . . . . . . . . . . . . . . . .

. 223

The command-level parameter structure . . . . . . . . . . . . .

. 224

User log record recovery program exits XRCINIT and XRCINPT . . . . .

. 230

Coding the exit programs. . . . . . . . . . . . . . . . . . .

. 230

Enabling the exit programs . . . . . . . . . . . . . . . . . .

. 231

Exit XRCINIT . . . . . . . . . . . . . . . . . . . . . . .

. 232

Exit XRCINPT . . . . . . . . . . . . . . . . . . . . . . . . 232

VTAM terminal management program exit XZCATT . . . . . . . . . .

. 234

Exit XZCATT . . . . . . . . . . . . . . . . . . . . . . .

. 234

VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE . . 235

Exit XZCIN . . . . . . . . . . . . . .

. . . . . . . .

. .

. 235

Exit XZCOUT . . . . . . . . . . . . .

. . . . . . . .

. .

. 235

Exit XZCOUT1 . . . . . . . . . . . .

. . . . . . . .

. .

. 236

XZIQUE exit for managing intersystem queues .

. . . . . . . .

. .

. 237

Designing an XZIQUE global user exit program

. . . . . . . .

. .

. 243

XRF request-processing program exit XXRSTAT .

. . . . . . . . . . . 246

Exit XXRSTAT . . . . . . . . . . . . . . . . . . . . . . . . 246

Chapter 2. Task-related user exit programs . .

. . . . . . . .

. .

. 249

vi CICS TS for OS/390: CICS Customization Guide

Introduction to the task-related user exit mechanism (the adapter). . . . . . 249

The stub program . . . . . . . . . . . . . . . . . . . . . .

. 250

Returning control to the application program. . . . . . . . . . . .

. 251

Task-related user exits and EDF . . . . . . . . . . . . . . . .

. 252

The task-related user exit program . . . . . . . . . . . . . . . .

. 252

User exit parameter lists . . . . . . . . . . . . . . . . . . .

. 253

The schedule ¯ag word . . . . . . . . . . . . . . . . . . .

. 265

Register handling in the task-related user exit program . . . . . . . .

. 266

Addressing-mode implications . . . . . . . . . . . . . . . . .

. 267

Exit programs and the CICS storage protection facility . . . . . . . .

. 267

Recursion within a task-related user exit program . . . . . . . . . .

. 268

Using CICS services in your task-related user exit program . . . . . .

. 268

Work areas . . . . . . . . . . . . . . . . . . . . . . . . . 269 Coding a program to be invoked by the CICS SPI . . . . . . . . . . 270 Coding a program to be invoked by the CICS syncpoint manager . . . . . 270 Coding a program to be invoked by the CICS task manager . . . . . . . 274

Coding a program to be invoked at CICS termination . . . . . . . .

. 275

Using EDF with your task-related user exit program . . . . . . . . .

. 278

Adapter administration . . . . . . . . . . . . . . . . . . . . .

. 280

What you must do before using the adapter . . . . . . . . . . . .

. 280

Tracing a task-related user exit program . . . . . . . . . . . . .

. 282

Chapter 3. The user exit programming interface (XPI) . . . . . . . .

. 283

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 283

General form of an XPI call . . . . . . . . . . . . . . . . . . .

. 286

Setting up the XPI environment . . . . . . . . . . . . . . . .

. 290

XPI register usage . . . . . . . . . . . . . . . . . . . . .

. 291

The XPI copy books . . . . . . . . . . . . . . . . . . . .

. 291

Reentrancy considerations resulting from XPI calls . . . . . . . . .

. 291

Global user exit XPI examples, showing the use of storage . . . . . . .

. 292

An example showing how to build a parameter list incrementally . . . .

. 297

The XPI functions . . . . . . . . . . . . . . . . . . . . . .

. 298

Dispatcher functions . . . . . . . . . . . . . . . . . . . . .

. 300

Synchronization protocols for SUSPEND and RESUME processing . . .

. 300

The ADD_SUSPEND call. . . . . . . . . . . . . . . . . . .

. 302

The SUSPEND call . . . . . . . . . . . . . . . . . . . . .

. 304

The RESUME call . . . . . . . . . . . . . . . . . . . . .

. 307

The DELETE_SUSPEND call . . . . . . . . . . . . . . . . .

. 308

The WAIT_MVS call . . . . . . . . . . . . . . . . . . . .

. 309

The CHANGE_PRIORITY call . . . . . . . . . . . . . . . . . . 313

Dump control functions . .

. . . .

.

.

. . .

.

.

. . . . . . .

. 314

The SYSTEM_DUMP call

. . . .

.

.

. . .

.

.

. . . . . . .

. 314

The TRANSACTION_DUMP call . . . . . . . . . . . . . . . . . 316

Enqueue domain functions . . . . . .

.

. . . . .

.

. . . . . .

. 318

The ENQUEUE function . . . . . .

.

. . . . .

.

. . . . . .

. 318

The DEQUEUE function . . . . . . . . . . . . . . . . . . . . 319

Kernel domain functions . . . . . . . . . .

. . . . .

.

.

.

. .

. 320

The START_PURGE_PROTECTION function .

. . . . .

.

.

.

. .

. 320

The STOP_PURGE_PROTECTION function. . . . . . . . . . . . . 320

Nesting purge protection calls . . . . . . . . . .

. . . . . . .

. 321

Loader functions . . . . . . . . . . . . . . . .

. . . . . . .

. 321

The DEFINE_PROGRAM call . . . . . . . . . .

. . . . . . .

. 321

The ACQUIRE_PROGRAM call . . . . . . . . .

. . . . . . .

. 325

The RELEASE_PROGRAM call . . . . . . . . .

. . . . . . .

. 327

The DELETE_PROGRAM call .

.

.

. . . . .

. . . . . . .

. .

. 328

Log manager functions . . . .

.

.

. . . . .

. . . . . . .

. .

. 329

Contents vii

The INQUIRE_PARAMETERS call . . .

. . . . . . . . . . . . . 329

The SET_PARAMETERS call . . . . . . . . . . . . . . . . . . 329

Monitoring functions. . . . . . . . . .

. . . .

. . . . . .

.

.

. 330

The MONITOR call . . . . . . . . .

. . . .

. . . . . .

.

.

. 330

The INQUIRE_MONITORING_DATA call .

. . . .

. . . . . .

.

.

. 333

Program management functions . . . . .

. . . .

. . . . . .

.

.

. 334

The INQUIRE_PROGRAM call. . . . .

. . . .

. . . . . .

.

.

. 335

The INQUIRE_CURRENT_PROGRAM call

. . . .

. . . . . .

.

.

. 341

The SET_PROGRAM call . . . . . .

. . . .

. . . . . .

.

.

. 343

The START_BROWSE_PROGRAM call .

. . . .

. . . . . .

.

.

. 346

The GET_NEXT_PROGRAM call . . . . . . . . . . . . . . . . . 347 The END_BROWSE_PROGRAM call . . . . . . . . . . . . . . . 349

The INQUIRE_AUTOINSTALL call . .

. . . . .

. .

.

. .

. .

.

. 350

The SET_AUTOINSTALL call . . . .

. . . . .

. .

.

. .

. .

.

. 350

State data access functions . . . . . .

. . . . .

. .

.

. .

. .

.

. 352

The INQ_APPLICATION_DATA call . .

. . . . .

. .

.

. .

. .

.

. 352

The INQUIRE_SYSTEM call . . . .

. . . . .

. . . . . . . . . 355

The SET_SYSTEM call . . . . . . . . . . . . . . . . . . . . 359

Storage control functions . . . . . . .

. . . . .

. .

.

. .

. .

.

. 361

The GETMAIN call . . . . . . . .

. . . . .

. .

.

. .

. .

.

. 361

The FREEMAIN call . . . . . . .

. . . . .

. .

.

. .

. .

.

. 364

The INQUIRE_ACCESS call . . . .

. . . . .

. . . . . . . . . 364

The INQUIRE_ELEMENT_LENGTH call . . . . . . . . . . . . . . 365

The INQUIRE_SHORT_ON_STORAGE call . . . . . . . . . . . . . 366

The INQUIRE_TASK_STORAGE call .

. . . . .

. . . . . . . . . 367

The SWITCH_SUBSPACE call. . . . . . . . . . . . . . . . . . 368

Trace control function . . . . . . . .

. . . . .

. .

.

. .

. .

.

. 369

The TRACE_PUT call . . . . . . .

. . . . .

. .

.

. .

. .

.

. 369

Transaction management functions . . .

. . . . .

. .

.

. .

. .

.

. 370

The INQUIRE_CONTEXT call . . . .

. . . . .

. .

.

. .

. .

.

. 370

The INQUIRE_DTRTRAN call . . . .

. . . . .

. .

.

. .

. .

.

. 371

The INQUIRE_MXT call . . . . . .

. . . . .

. .

.

. .

. .

.

. 372

The INQUIRE_TCLASS call . . . . .

. . . . .

. .

.

. .

. .

.

. 374

The INQUIRE_TRANDEF call . . . .

. . . . .

. . . . . . . . . 375

The INQUIRE_TRANSACTION call . . . . . . . . . . . . . . . . 383

The SET_TRANSACTION call . . . . . . . . . . . . . . . . . . 387

User journaling function . . . . . . .

. . . . .

. .

.

. .

. .

.

. 388

The WRITE_JOURNAL_DATA call . .

. . . . .

. .

.

. .

. .

.

. 388

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

.

.391

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

.

. 393

Initialization programs . . . . . . . . . . . . . . . . . . . .

.

. 393

First phase PLT programs . . . . . . . . . . . . . . . . .

.

. 393

Second phase PLT programs . . . . . . . . . . . . . . . .

.

. 394

Shutdown programs. . . . . . . . . . . . . . . . . . . . .

.

. 394

First phase PLT programs . . . . . . . . . . . . . . . . .

.

. 395

PLT programs for the second quiesce stage . . . . . . . . . . .

.

. 395

The shutdown assist utility program, DFHCESD . . . . . . . . .

.

. 395

General considerations . . . . . . . . . . . . . . . . . . .

.

. 396

Storage keys for PLT programs . . . . . . . . . . . . . . .

.

. 396

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

Chapter 5. General notes about user-replaceable programs. . . . . . . 401

viii CICS TS for OS/390: CICS Customization Guide

Rewriting user-replaceable programs . . . . . . . . . .

.

. .

.

.

. 401

Assembling and link-editing user-replaceable programs. . . .

.

. .

.

.

. 402

User-replaceable programs and the storage protection facility .

.

. .

.

.

. 405

Execution key for user-replaceable programs . . . . . .

.

. .

.

.

. 405

Data storage key for user-replaceable programs . . . . .

.

. .

.

.

. 406

Chapter 6. Writing a program error program. . . . . . .

.

. .

.

.

. 407

The sample programs and copy books . . . . . . . . . .

.

. .

.

.

. 410

Chapter 7. Writing a transaction restart program . . . . .

.

. .

.

.

. 411

The DFHREST communications area . . . . . . . . . .

.

. .

.

.

. 412

The CICS-supplied transaction restart program. . . . . . .

.

. .

.

.

. 414

Chapter 8. Writing a terminal error program . . . . . . .

.

. .

.

.

. 415

Background to error handling for TCAM and sequential devices

.

. .

.

.

. 415

When an abnormal condition occurs. . . . . . . . . .

.

. .

.

.

. 416

Terminal control program . . . . . . . . . . . . . . . . . . . . 416

Terminal abnormal condition program .

.

. . . . .

.

. . . .

.

.

.

416

Terminal error program . . . . . .

.

. . . . .

.

. . . .

.

.

.

416

The communication area . . . . . . . . . . . . . . . . . . . . 417

Terminal abnormal condition line entry (TACLE) . . . . .

.

. .

. .

. 417

The sample terminal error program . . . . . . . . . . .

.

. .

. .

. 417

Components of the sample terminal error program . . . .

.

. .

. .

. 418

Structure of the sample terminal error program . . . . . .

.

. .

. .

. 419

Sample terminal error program messages . . . . . . .

.

. .

. .

. 423

Generating the sample terminal error program . . . . . .

.

. .

. .

. 425

User-written terminal error programs . . . . . . . . . .

.

. .

. .

. 437

Why write your own terminal error program? . . . . . .

.

. .

. .

. 438

Restrictions on the use of EXEC CICS commands . . . .

.

. .

. .

. 438

Addressing the contents of the communication area . . . .

.

. .

. .

. 438

Addressing the contents of the TACLE . . . . . . . . .

.

. .

. .

. 441

Example of a user-written terminal error program . . . . .

.

. .

. .

. 445

Chapter 9. Writing a node error program . . . . . . . .

.

. .

. .

. 449

Background to CICS-VTAM error handling . . . . . . . .

.

. .

. .

. 450

Why use a NEP to supplement CICS default actions? . . .

.

. .

. .

. 450

An overview of writing a NEP . . . . . . . . . . . .

.

. .

. .

. 451

The default NEP . . . . . . . . . . . . . . . . .

.

. .

. .

. 452

The sample NEP . . . . . . . . . . . . . . . . . . . . . . . 452

Multiple NEPs . . . . . . . . . . . . . . .

. . . .

. .

. .

. 455

When an abnormal condition occurs. . . . . . . .

. . . .

. .

. .

. 457

The communication area . . . . . . . . . . .

. . . .

. .

. .

. 458

The sample node error program . . . . . . . . .

. . . .

. .

. .

. 465

Compatibility with the sample terminal error program

. . . .

. .

. .

. 466

Components of the sample node error program . .

. . . .

. .

. .

. 466

Generating the sample node error program . . . .

. . . .

. .

. .

. 469

User-written node error programs. . . . . . . . .

. . . .

. .

. .

. 475

Restrictions on the use of EXEC CICS commands .

. . . .

. .

. .

. 475

Entry and addressability . . . . . . . . . . . . . . . . . . . . 476

Coding for the 3270 `unavailable printer' condition

. . . . . . .

. .

. 476

Coding for session failures . . . . . . . . .

. . . . . . .

. .

. 477

Coding for speci®c VTAM sense codes. . . . .

. . . . . . .

. .

.

478

Writing multiple NEPs . . . . . . . . . . .

. . . . . . .

. .

.

478

DFHZNEPI macros . . . . . . . . . . . . . . . . . . . . . . 478 Handling shutdown hung terminals in the node error program . . . . . . 480 Using the node error program with XRF or persistent sessions . . . . . . . 480

Contents ix

The node error program in an XRF environment . . . .

.

.

.

. . .

. 480

The node error program with persistent session support .

.

.

.

. . .

. 481

Changing the recovery noti®cation . . . . . . . . .

.

.

.

. . .

. 481

Changing the recovery message . . . . . . . . . .

.

.

.

. . .

.

482

Changing the recovery transaction . . . . . . . . .

.

.

.

. . .

.

482

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

Chapter 10. Writing a program to control autoinstall of terminals . . . . 485 Preliminary considerations . . . . . . . . . . . . . . . . . . . . 485

Coding entries in the VTAM LOGON mode table . . . . . . .

. .

.

. 486

Using model terminal support (MTS) . . . . . . . . . . .

. .

.

. 487

The autoinstall control program for terminals, DFHZATDX . . . .

. .

.

. 487

The autoinstall control program at INSTALL . . . . . . . . . .

. .

.

. 487

The communication area at INSTALL for terminals . . . . . .

. .

.

. 488

How CICS builds the list of autoinstall models . . . . . . . .

. .

.

. 490

Returning information to CICS . . . . . . . . . . . . . .

. .

.

. 491

CICS action on return from the control program . . . . . . .

. .

.

. 494

The autoinstall control program at DELETE . . . . . . . . . .

. .

.

. 495

The communication area at DELETE for terminals . . . . . .

. .

.

. 495

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

. .

.

. 496

Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 496

Testing and debugging. . . . . . . . . . . . . . . . .

. .

.

. 496

The sample programs and copy books . . . . . . . . . . . .

. .

.

. 497

Customizing the sample program . . . . . . . . . . . . .

. .

.

. 499

Chapter 11. Writing a program to control autoinstall of consoles

. .

.

. 505

Preliminary considerations . . . . . . . . . . . . . . . . . . . . 505

Leaving it all to CICS . . . . . . . . . . . . . . . . . . . .

. 505

Using an autoinstall control program. . . . . . . . . . . . . . .

. 506

The autoinstall control program at INSTALL . . . . . . . . . . . . .

. 506

The communication area at INSTALL for consoles . . . . . . . . .

. 507

How CICS builds the list of autoinstall models . . . . . . . . . . .

. 508

Returning information to CICS . . . . . . . . . . . . . . . . .

. 508

CICS action on return from the control program . . . . . . . . . .

. 510

The autoinstall control program at DELETE . . . . . . . . . . . . .

. 510

The sample programs and copy books . . . . . . . . . . . . . . .

. 511

Chapter 12. Writing a program to control autoinstall of APPC connections

513

Preliminary considerations . . . . . . . . . . . . . . . . . . .

. 513

Local APPC single-session connections initiated by CINIT . . . . . .

. 513

Local APPC parallel-session and single-session connections initiated by

 

BIND . . . . . . . . . . . . . . . . . . . . . . . . . . 514

Autoinstall templates for APPC connections . . . . . . . . . . . .

. 514

Bene®ts of autoinstall . . . . . . . . . . . . . . . . . . . . . 514

Requirements for autoinstall. . . . . . . . . . . .

.

.

. .

.

.

. 514

The autoinstall control program for APPC connections . .

.

.

. .

.

.

. 515

Recovery and restart . . . . . . . . . . . . . .

.

.

. .

.

.

.

515

The autoinstall control program at INSTALL . . . . . . .

.

.

. .

.

.

.

515

The communication area at INSTALL for APPC connections . . . . . . . 516

The autoinstall control program at DELETE . . . . . . . .

. . . .

.

. 519

When autoinstalled APPC connections are deleted . . . .

. . . .

.

. 520

The sample autoinstall control program for APPC connections .

. . . .

.

. 520

Default actions of the sample program . . . . . . . . .

. . . .

.

. 520

Resource de®nitions . . . . . . . . . . . . . . . . . . . . . 521

Chapter 13. Writing a program to control autoinstall of shipped terminals . 523

x CICS TS for OS/390: CICS Customization Guide

Installing shipped terminals and connections . . . . . . . . . . . . . 523 CICS-generated aliases . . . . . . . . . . . . . . . . . . . . 524

Resetting the terminal identi®er . . . . . . . .

.

. . . .

.

. .

.

524

The autoinstall control program at INSTALL . . . . .

.

. . . .

.

. .

.

525

The communications area at INSTALL for shipped terminals . . . . . . . 526

The autoinstall control program at DELETE . . . . . . . . . . . .

.

. 528

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

.

. 529

Chapter 14. Writing a program to control autoinstall of Client virtual

 

 

 

terminals . . . . . . . . . . . . . . . . . . . . . . .

.

.

531

How Client virtual terminals are autoinstalled . . . . . . . . . . .

.

.

531

Autoinstall models . . . . . . . . . . . . . . . . . . . . . . 531

Terminal identi®ers . . . . . . . . . . . . . . . . . . .

. .

. 532

Why override TERMIDs? . . . . . . . . . . . . . . . . .

. .

. 533

The autoinstall control program at INSTALL . . . . . . . . . . .

. .

. 534

The communications area at INSTALL for Client virtual terminals . .

. .

. 534

The autoinstall control program at DELETE . . . . . . . . . . .

. .

. 536

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

. .

. 537

Chapter 15. Writing a program to control autoinstall of programs .

. .

. 539

Preliminary considerations . . . . . . . . . . . . . . . . . . . . 539 Autoinstall model de®nitions. . . . . . . . . . . . . . . . . . . 540 Autoinstalling programs invoked by EXEC CICS LINK commands . . . . . 540 Autoinstall processing of mapsets . . . . . . . . . . . . . . . . 541 System autoinstall . . . . . . . . . . . . . . . . . . . . . . 541

Bene®ts of autoinstall . . . . . . . . . . . . . . . . . . . . . . 541 Reduced system administration costs . . . . . . . . . . . . . . . 541 Saving in virtual storage . . . . . . . . . . . . . . . . . . . . 541 Faster startup times. . . . . . . . . . . . . . . . . . . . . . 542

Requirements for autoinstall. . . . . . . . . . . . . . . . . . .

. 542

The autoinstall control program at INSTALL . . . . . . . . . . . . .

. 543

The sample autoinstall control program for programs, DFHPGADX . . . .

.

546

Customizing the sample program . . . . . . . . . . . . . . . .

.

546

Resource de®nition. . . . . . . . . . . . . . . . . . . . . . 547

Testing and debugging your program . . . . . . . .

. . . .

. .

. 548

Chapter 16. Writing a dynamic routing program . . . .

. . . .

. .

. 549

Dynamic transaction routing . . . . . . . . . . . . . . . . . . . . 550 Dynamic transactions . . . . . . . . . . . . . . . . . . . . . 550

When the dynamic routing program is invoked . . . . .

.

. .

. . .

. 550

Information passed to the dynamic routing program . . .

.

. .

. . .

. 551

Changing the target CICS region . . . . . . . . . .

.

. .

. . .

. 552

Changing the program name . . . . . . . . . . .

.

. .

. . .

. 553

Telling CICS whether to route or terminate a transaction .

.

. .

. . .

. 553

If the system is unavailable or unknown . . . . . . .

.

. .

. . .

. 554

Invoking the dynamic routing program at end of routed transactions . . . . 554

Invoking the dynamic routing program on abend . . . .

.

. .

.

. .

. 555

Modifying the initial terminal data . . . . . . . . . .

.

. .

.

. .

. 555

Modifying the application's communications area . . . .

.

. .

.

. .

. 555

Receiving information from a routed transaction . . . .

.

. .

.

. .

. 556

Some processing considerations . . . . . . . . . .

.

. .

.

. .

. 556

Unit of work considerations . . . . . . . . . . . .

.

. .

.

. .

. 557

Dynamic routing of DPL requests . . . . . . . . . . .

.

. .

.

. .

. 557

When the dynamic routing program is invoked . . . . .

.

. .

.

. .

. 558

Changing the target CICS region . . . . . . . . . .

.

. .

.

. .

. 559

Changing the program name . . . . . . . . . . .

.

. .

.

. .

. 559

Contents xi

Changing the transaction ID. . . . . . . . . . . . . . . . .

.

. 560

Telling CICS whether to route or terminate a DPL request. . . . . .

.

. 560

If an error occurs in route selection . . . . . . . . . . . . . .

.

. 561

Invoking the dynamic routing program at end of routed requests . . .

.

. 561

Modifying the application's input communications area . . . . . . .

.

. 561

Monitoring the application's output communications area . . . . . .

.

. 562

Some processing considerations . . . . . . . . . . . . . . .

.

. 562

Unit of work considerations . . . . . . . . . . . . . . . . .

.

. 562

Parameters passed to the dynamic routing program . . . . . . . . .

.

. 562

Naming your dynamic routing program . . . . . . . . . . . . . .

.

. 573

Testing your dynamic routing program . . . . . . . . . . . . . .

.

. 573

Dynamic transaction routing sample programs . . . . . . . . . . .

.

. 574

Chapter 17. Writing a distributed routing program . . . . . . . .

.

.

575

Differences from the dynamic routing interface . . . . . . . . . . .

.

. 576

Distributed routing of BTS activities . . . . . . . . . . . . . . .

.

. 577

Which BTS activities can be dynamically routed? . . . . . . . . .

.

. 577

When the distributed routing program is invoked . . . . . . . . .

.

. 578

Changing the target CICS region . . . . . . . . . . . . . . .

.

. 579

Telling CICS whether to route the activity . . . . . . . . . . . .

.

. 579

If an error occurs in route selection . . . . . . . . . . . . . .

.

. 579

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

Some processing considerations . . . . . . . . . . . . . . .

.

. 580

Routing of non-terminal-related START requests . . . . . . . . . .

.

. 581

Which requests can be dynamically routed? . . . . . . . . . . .

.

. 581

When the distributed routing program is invoked . . . . . . . . .

.

. 582

Changing the target CICS region . . . . . . . . . . . . . . .

.

. 583

Telling CICS whether to route the request. . . . . . . . . . . .

.

. 583

If an error occurs in route selection . . . . . . . . . . . . . .

.

. 584

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

Some processing considerations . . . . . . . . . . . . . . .

.

. 584

Parameters passed to the distributed routing program . . . . . . . .

.

. 585

Naming your distributed routing program . . . . . . . . . . . . .

.

. 593

Distributed transaction routing sample programs . . . . . . . . . .

.

. 593

Chapter 18. Writing a CICS±DBCTL interface status program . . . .

.

.

595

The sample program and copy book . . . . . . . . . . . . . .

.

. 596

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

.

.

599

Chapter 20. Writing a security exit program for IIOP . . . . . . .

.

.

601

Chapter 21. Writing a program to tailor JVM execution environment

 

 

 

variables. . . . . . . . . . . . . . . . . . . . . . . . . . 603

Environment variables . . . . . . . . . . . . . . . . . . . .

.

.

603

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

.

.

.607

Chapter 22. The extended recovery facility overseer program . . .

.

.

. 609

The sample overseer program . . . . . . . . . . . . . . . .

.

.

. 609

The functions of the sample program . . . . . . . . . . . .

.

.

. 609

How the sample overseer program interfaces with CICS . . . . .

.

.

. 613

How to tell the overseer which actives and alternates to monitor . .

.

.

. 613

The DFHWOSM macros . . . . . . . . . . . . . . . . . .

.

.

. 614

The DFHWOSM tokens . . . . . . . . . . . . . . . . . . . . 615

DFHWOSM FUNC=BUILD macro . . . . . . . . . . . . .

.

.

. 615

xii CICS TS for OS/390: CICS Customization Guide

DFHWOSM FUNC=CLOSE macro . . . . . . . . . . . . . . . . 616 DFHWOSM FUNC=DSECT macro . . . . . . . . . . . . . . . . 616 DFHWOSM FUNC=JJC macro. . . . . . . . . . . . . . . . . . 616 DFHWOSM FUNC={JJS|QJJS} macro . . . . . . . . . . . . . . . 617 DFHWOSM FUNC=OPEN macro. . . . . . . . . . . . . . . . . 618 DFHWOSM FUNC=OSCMD macro . . . . . . . . . . . . . . . . 618 DFHWOSM FUNC=READ macro . . . . . . . . . . . . . . . . . 619 DFHWOSM FUNC=TERM macro. . . . . . . . . . . . . . . . . 622

Customizing the sample overseer program . . . .

. . . .

.

.

. .

.

. 623

Loop or wait detection . . . . . . . . . . .

. . . .

.

.

. .

.

.

624

Assembling and link-editing the overseer program

. . . .

.

.

. .

.

.

625

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

.627

Chapter 23. CICS logging and journaling . . . . . . . . . . . . .

.

629

Log stream storage . . . . . . . . . . . . . . . . . . . . . . . 629

Enabling, disabling, and reading journals . . . . . . . . . . . . . .

. 631

Enabling and disabling a journal . . . . . . . . . . . . . . . .

. 631

Reading journal records offline . . . . . . . . . . . . . . . . .

. 632

Structure and content of CICS Transaction Server for OS/390 format journal

 

 

records . . . . . . . . . . . . . . . . . . . . . . . . .

.

632

Format of general log block header . . . . . . . . . . . . . . .

. 634

Format of general log journal record. . . . . . . . . . . . . . .

. 635

Start-of-run record . . . . . . . . . . . . . . . . . . . . . . 636

Format of caller data . . . . . . . . . . . . . . . . . . . .

.

636

Structure and content of COMPAT41-format journal records . . . . . . .

. 645

Format of COMPAT41 journal control label header . . . . . . . . .

. 646

Format of journal record . . . . . . . . . . . . . . . . . . .

.

648

Identifying records for the start of tasks and UOWs . . . . . . . . .

. 653

Format of journal records written to SMF . . . . . . . . . . . . . .

. 653

The SMF block header . . . . . . . . . . . . . . . . . . .

. 654

The CICS product section . . . . . . . . . . . . . . . . . .

. 654

The CICS data section. . . . . . . . . . . . . . . . . . . .

. 655

Chapter 24. CICS monitoring . . . . . . . . . . . . . . . . . .

.

657

Introduction to CICS monitoring . . . . . . . . . . . . . . . . .

. 657

The classes of monitoring data . . . . . . . . . . . . . . . .

. 657

Performance class monitoring data . . . . . . . . . . . . . . .

. 658

Exception class data . . . . . . . . . . . . . . . . . . . .

.

661

How performance and exception class data is passed to SMF . . . . .

. 662

Controlling CICS monitoring . . . . . . . . . . . . . . . . . . . 662

CICS monitoring record formats . . . . . . . . . . . . . . . . .

. 663

SMF header and SMF product section . . . . . . . . . . . . . .

. 663

CICS data section . . . . . . . . . . . . . . . . . . . . . . 666

Chapter 25. CICS statistics . . . . . . . . . . . . . . . . . .

.

677

Introduction to CICS statistics . . . . . . . . . . . . . . . . . .

.

677

Types of statistics data . . . . . . . . . . . . . . . . . . .

.

677

Resetting statistics counters. . . . . . . . . . . . . . . . . .

.

681

The EXEC CICS COLLECT STATISTICS command . . . . . . . . .

. 682

CICS statistics record format . . . . . . . . . . . . . . . . . .

. 682

SMF header and SMF product section . . . . . . . . . . . . . .

. 683

CICS statistics data section . . . . . . . . . . . . . . . . . .

. 685

Global user exit in the CICS statistics domain . . . . . . . . . . . .

. 687

Processing the output from CICS statistics . . . . . . . . . . . . .

. 688

Contents xiii

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

. . . . . .689

Chapter 26. Using TCAM with CICS . . . . . . . . . .

. . . .

.

. 691

CICS with TCAM SNA . . . . . . . . . . . . . . . .

. . . . . . 692

Protocol management . . . . . . . . . . . . . . . . . . . . . 692

Function management header processing. . . . . . . .

. . . .

.

. 693

Batch processing. . . . . . . . . . . . . . . . .

. . . .

.

. 694

Error processing for batch logical units . . . . . . . . .

. . . .

.

. 694

Error processing . . . . . . . . . . . . . . . . .

. . . .

.

. 694

The TCAM application program interface . . . . . . . . .

. . . .

.

. 694

The CICS-TCAM interface . . . . . . . . . . . . . .

. . . .

.

. 695

Data format . . . . . . . . . . . . . . . . . . .

. . . . . . 696

Logic ¯ow . . . . . . . . . . . . . . . . . . . . . . . . . 697

Terminal error program . . . . . . . . . . . . . .

. . . . . . 699

Message routing . . . . . . . . . . . . . . . . . . . . . . . 700

Segment processing . . . . . . . . . . . . . . .

. . . .

.

. 700

Line pool speci®cations . . . . . . . . . . . . . .

. . . .

.

. 701

Line locking. . . . . . . . . . . . . . . . . . .

. . . . . . 702

TCAM queues . . . . . . . . . . . . . . . . . . . . . . . . 703

TCAM devices. . . . . . . . . . . . . . . . . . . . . . . . . 704

Generalized TCAM message format . . . . . . . . . .

. . . .

.

. 705

TCAM with 3270 devices . . . . . . . . . . . . . .

. . . . . . 706

TCAM user exits . . . . . . . . . . . . . . . . . . . . . . . . 707

Starting and terminating TCAM . . . . . . . . . . . .

. . . . . . 707

CICS-TCAM startup. . . . . . . . . . . . . . . . . . . . . . 707

CICS-TCAM abend and restart . . . . . . . . . . .

. . . . . . 707

CICS-TCAM termination . . . . . . . . . . . . . . . . . . . . 708

CICS and TCAM: program interrelationship . . . . . . . .

. . . .

.

. 709

TCAM message control program (non-SNA) . . . . . . .

. . . .

.

. 710

Chapter 27. The dynamic allocation sample program . . .

. . . .

.

. 713

Overview of the dynamic allocation program. . . . . . . .

. . . .

.

. 713

Installing the program and transaction de®nitions. . . . . .

. . . .

.

. 714

Terminal operation . . . . . . . . . . . . . . . . .

. . . .

.

. 714

Help feature . . . . . . . . . . . . . . . . . . .

. . . . . . 715

Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

Abbreviation rules for keywords . . . . . . . . . . .

. . . .

.

. 716

System programming considerations . . . . . . . . .

. . . .

.

. 716

The ¯ow of control when a DYNALLOC request is issued. . .

. . . .

.

. 717

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

. . . . .719

Chapter 28. Invoking a user-written external security manager

. .

.

.

. 721

An overview of the CICS-ESM interface . . . . . . . . . .

. .

.

.

. 721

The MVS router . . . . . . . . . . . . . . . . . . .

. .

.

.

. 721

The MVS router exit . . . . . . . . . . . . . . . .

. .

.

.

. 722

How ESM exit programs access CICS-related information. . . .

. .

.

.

. 724

For non-RACF users Ð the ESM parameter list . . . . . .

. .

.

.

. 724

For RACF users Ð the RACF user exit parameter list . . . .

. .

.

.

. 724

The installation data parameter list . . . . . . . . . . .

. .

.

.

. 725

CICS security control points . . . . . . . . . . . . . . .

. .

.

.

. 727

Early veri®cation processing. . . . . . . . . . . . . . . . . . . . 729

Writing an early veri®cation routine . . . . . . . . . . .

. .

.

.

. 730

Using CICS API commands in an early veri®cation routine . .

. .

.

.

. 730

Return and reason codes from the early veri®cation routine. .

. .

.

.

. 731

xiv CICS TS for OS/390: CICS Customization Guide

Chapter 29. Writing a ªgood nightº program

. . . . .

.

.

.

.

. .

. 733

The sample ªgood nightº program, DFH0GNIT.

. . . . .

.

.

.

.

. .

. 735

What the sample program does . . . . .

. . . . .

.

.

.

.

. .

. 736

Customizing the sample program . . . . .

. . . . .

.

.

.

.

. .

. 736

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

.739

Chapter 30. User programs for the system de®nition utility program

 

(DFHCSDUP) . . . . . . . . . . . . . . . . . . . . . . .

. 741

An overview of DFHCSDUP. . . . . . . . . . . . . . . . . . . . 741

DFHCSDUP as a batch program . . . . . . . . . . . . . . . . .

. 742

Writing a program to be invoked during EXTRACT processing . . . . .

. 742

The EXTRACT command . . . . . . . . . . . . . . . . . .

. 742

When the user program is invoked . . . . . . . . . . . . . . .

. 743

Parameters passed from DFHCSDUP to the user program . . . . . .

. 743

The sample EXTRACT programs . . . . . . . . . . . . . . . .

. 744

Assembling and link-editing EXTRACT programs . . . . . . . . . .

. 747

Invoking DFHCSDUP from a user program . . . . . . . . . . . . .

. 751

Entry parameters for DFHCSDUP . . . . . . . . . . . . . . .

. 752

Responsibilities of the user program. . . . . . . . . . . . . . .

. 754

The user exit points in DFHCSDUP . . . . . . . . . . . . . . .

. 755

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

. 760

Chapter 31. The programmable interface to the RDO transaction, CEDA. . 761

Use of the programmable interface . . . . . . . . . . . . . . . .

. 762

Using DFHEDAP in a DTP environment . . . . . . . . . . . . . .

. 762

Part 9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .765

Appendix A. Coding entries in the VTAM LOGON mode table . . . . . . 767 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 767

TYPETERM device types and pointers to related LOGON mode data . .

.

. 768

VTAM MODEENT macro operands . . . . . . . . . . . . . . .

.

. 770

PSERVIC screen size values for LUTYPEx devices . . . . . . . . .

.

. 775

Matching models and LOGON mode entries. . . . . . . . . . . .

.

. 776

LOGON mode de®nitions for CICS-supplied autoinstall models. . . . .

.

. 786

Appendix B. Default actions of the node abnormal condition program

.

. 789

Default actions for terminal error codes . . . . . . . . . . . . .

.

. 789

CICS messages associated with VTAM errors . . . . . . . . . . .

.

. 795

Default actions for system sense codes . . . . . . . . . . . . .

.

. 800

Action ¯ag settings and meanings . . . . . . . . . . . . . . .

.

. 802

Appendix C. Transient data write-to-terminal program (DFH$TDWT) .

.

. 803

Resource de®nitions required . . . . . . . . . . . . . . . . . . . 803

Appendix D. Uppercase translation . . . . . . . . . . . . . .

.

. 805

Uppercase translation of national characters. . . . . . . . . . . .

.

. 805

Using the XZCIN exit . . . . . . . . . . . . . . . . . . .

.

. 805

Using DFHTCTDY . . . . . . . . . . . . . . . . . . . .

.

. 805

TS data sharing messages . . . . . . . . . . . . . . . . . .

.

. 806

Appendix E. The example program for the XTSEREQ global user exit,

 

 

DFH$XTSE . . . . . . . . . . . . . . . . . . . . . . .

.

. 807

Contents xv

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

Sending your comments to IBM . . . . . . . . . . . . . . . . . 841

xvi CICS TS for OS/390: CICS Customization Guide

Notices

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

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

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106, Japan

The following paragraph does not apply in the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ªAS ISº WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you.

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

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

© Copyright IBM Corp. 1977, 1999

xvii

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

This book contains sample programs. Permission is hereby granted to copy and store the sample programs into a data processing machine and to use the stored copies for study and instruction only. No permission is granted to use the sample programs for any other purpose.

Programming interface information

This book is intended to help you to customize your CICS Transaction Server for OS/390 Release 3 system. This book primarily documents Product-sensitive Programming Interface and Associated Guidance Information provided by CICS.

Product-sensitive programming interfaces allow the customer installation to perform tasks such as diagnosing, modifying, monitoring, repairing, tailoring, or tuning of CICS. Use of such interfaces creates dependencies on the detailed design or implementation of the IBM software product. Product-sensitive programming interfaces should be used only for these specialized purposes. Because of their dependencies on detailed design and implementation, it is to be expected that programs written to such interfaces may need to be changed in order to run with new product releases or versions, or as a result of service.

However, this book also documents General-use Programming Interface and

Associated Guidance Information.

General-use programming interfaces allow the customer to write programs that request or receive the services of CICS.

General-use Programming Interface and Associated Guidance Information is identi®ed where it occurs, either by an introductory statement to a chapter or section or by the following marking:

General-use programming interface

General-use Programming Interface and Associated Guidance Information...

End of General-use programming interface

xviii CICS TS for OS/390: CICS Customization Guide

Trademarks

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

ACF/VTAM

IMS

BookManager

IMS/ESA

C/370

Language Environment

CICS

MVS/ESA

CICS/ESA

MQSeries

CICSPlex

OS/390

DB2

RACF

DFSMS

System/370

IBM

VTAM

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

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

Notices xix

xx CICS TS for OS/390: CICS Customization Guide

Preface

What this book is about

This book provides the information needed to extend and modify an IBM® CICS® Transaction Server for OS/390® system to match your requirements. It describes how you can tailor your system by coding exit programs, by replacing speci®c CICS-supplied default programs with versions that you write yourself, and by adapting sample programs.

Who this book is for

This book is for those responsible for extending and enhancing a CICS system to meet the special processing needs of an installation.

What you need to know to understand this book

To use the information in this book, you need to be familiar with some of the architecture of CICS and the programming interface to CICS. General-use programming interface information is given in the CICS Application Programming Reference manual and the CICS System Programming Reference manual.

Resource de®nition information is in theCICS Resource De®nition Guide.

To use the following chapters you need to be familiar with the telecommunications access methods (IBM ACF/VTAM® and IBM TCAM):

vªChapter 8. Writing a terminal error programº

vªChapter 9. Writing a node error programº

vªChapter 10. Writing a program to control autoinstall of terminalsº

vªChapter 12. Writing a program to control autoinstall of APPC connectionsº

vªChapter 26. Using TCAM with CICSº.

If your task involves error processing, you may need to consult the CICS Messages and Codes manual, the CICS Problem Determination Guide, or the CICS Diagnosis Reference manual.

How to use this book

The parts and chapters of the book are self-contained. Use an individual part or chapter as a guide when performing the task described in it.

Notes on terminology

In this book, the term ªCICSº, used without any quali®cation, refers to the CICS element of IBM CICS Transaction Server for OS/390. The term ªVTAM®º refers to ACF/VTAM. The term ªTCAMº refers to the DCB interface of ACF/TCAM. The term ªAPPCº (advanced program-to-program communication) refers to the LUTYPE6.2 intersystem connection (ISC) protocol.

© Copyright IBM Corp. 1977, 1999

xxi

CICS Transaction Server for OS/390 Release 3 supports CICS applications written in:

vAssembler language

vC

vCOBOL

vPL/I.

In this book, the phrase ªthe languages supported by CICSº refers to the above languages.

Syntax notation and conventions used in this book

The symbols { }, [ ], and | are used in the syntax descriptions of the EXEC CICS commands and macros referred to in this book. They are not part of the command and you should not include them in your code. Their meanings are as follows:

vBraces { } enclose two or more alternatives, one of which you must code.

vSquare brackets [ ] tell you that the enclosed is optional.

vThe ªorº symbol | separates alternatives.

In addition to these symbols, the following conventions apply:

vPunctuation symbols and uppercase characters should be coded exactly as shown.

vLowercase characters indicate that user text should be coded as required.

vDefault values are shown like this: DEFAULT.

vOptions that are enclosed neither in braces { } nor in square brackets [ ] are mandatory.

vThe ellipsis ... means that the immediately preceding option can be coded one or more times.

vAll EXEC CICS commands require a delimiter appropriate to the language of the application. For a COBOL program this is `END-EXEC', for example. Delimiters are not included in the syntax descriptions of the commands.

xxii CICS TS for OS/390: CICS Customization Guide

Bibliography

CICS Transaction Server for OS/390

CICS Transaction Server for OS/390: Planning for Installation

GC33-1789

CICS Transaction Server for OS/390: Release Guide

GC34-5352

CICS Transaction Server for OS/390: Migration Guide

GC34-5353

CICS Transaction Server for OS/390: Installation Guide

GC33-1681

CICS Transaction Server for OS/390: Program Directory

GC33-1706

CICS Transaction Server for OS/390: Licensed Program Speci®cation

GC33-1707

CICS books for CICS Transaction Server for OS/390

General

 

CICS Master Index

SC33-1704

CICS User's Handbook

SX33-6104

CICS Glossary (softcopy only)

GC33-1705

Administration

 

CICS System De®nition Guide

SC33-1682

CICS Customization Guide

SC33-1683

CICS Resource De®nition Guide

SC33-1684

CICS Operations and Utilities Guide

SC33-1685

CICS Supplied Transactions

SC33-1686

Programming

 

CICS Application Programming Guide

SC33-1687

CICS Application Programming Reference

SC33-1688

CICS System Programming Reference

SC33-1689

CICS Front End Programming Interface User's Guide

SC33-1692

CICS Càà OO Class Libraries

SC34-5455

CICS Distributed Transaction Programming Guide

SC33-1691

CICS Business Transaction Services

SC34-5268

Diagnosis

 

CICS Problem Determination Guide

GC33-1693

CICS Messages and Codes

GC33-1694

CICS Diagnosis Reference

LY33-6088

CICS Data Areas

LY33-6089

CICS Trace Entries

SC34-5446

CICS Supplementary Data Areas

LY33-6090

Communication

 

CICS Intercommunication Guide

SC33-1695

CICS Family: Interproduct Communication

SC33-0824

CICS Family: Communicating from CICS on System/390

SC33-1697

CICS External Interfaces Guide

SC33-1944

CICS Internet Guide

SC34-5445

Special topics

 

CICS Recovery and Restart Guide

SC33-1698

CICS Performance Guide

SC33-1699

CICS IMS Database Control Guide

SC33-1700

CICS RACF Security Guide

SC33-1701

CICS Shared Data Tables Guide

SC33-1702

CICS Transaction Affinities Utility Guide

SC33-1777

CICS DB2 Guide

SC33-1939

© Copyright IBM Corp. 1977, 1999

xxiii

CICSPlex SM books for CICS Transaction Server for OS/390

General

 

CICSPlex SM Master Index

SC33-1812

CICSPlex SM Concepts and Planning

GC33-0786

CICSPlex SM User Interface Guide

SC33-0788

CICSPlex SM View Commands Reference Summary

SX33-6099

Administration and Management

 

CICSPlex SM Administration

SC34-5401

CICSPlex SM Operations Views Reference

SC33-0789

CICSPlex SM Monitor Views Reference

SC34-5402

CICSPlex SM Managing Workloads

SC33-1807

CICSPlex SM Managing Resource Usage

SC33-1808

CICSPlex SM Managing Business Applications

SC33-1809

Programming

 

CICSPlex SM Application Programming Guide

SC34-5457

CICSPlex SM Application Programming Reference

SC34-5458

Diagnosis

 

CICSPlex SM Resource Tables Reference

SC33-1220

CICSPlex SM Messages and Codes

GC33-0790

CICSPlex SM Problem Determination

GC33-0791

Other CICS books

CICS Application Programming Primer (VS COBOL II)

SC33-0674

CICS Application Migration Aid Guide

SC33-0768

CICS Family: API Structure

SC33-1007

CICS Family: Client/Server Programming

SC33-1435

CICS Family: General Information

GC33-0155

CICS 4.1 Sample Applications Guide

SC33-1173

CICS/ESA 3.3 XRF Guide

SC33-0661

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

Books from related libraries

This section lists the non-CICS books that are referred to in this manual.

ACF/TCAM books

ACF/TCAM Installation and Migration Guide, SC30-3121

ACF/TCAM System Programmer's Guide, SC30-3117

ACF/TCAM Version 3 Application Programming, SC30-3233.

xxiv CICS TS for OS/390: CICS Customization Guide

MVS books

Short Title

Full Title

 

 

Assembler Programming Guide

OS/390 MVS Assembler Services Guide,

 

GC28-1762

 

 

Authorized Assembler Programming Guide

OS/390 MVS Authorized Assembler Services

 

Guide, GC28-1763

 

 

Authorized Assembler Programming

OS/390 MVS Authorized Assembler Services

Reference Volume 1

Reference ALE-DYN, GC28-1764

 

 

Authorized Assembler Programming

OS/390 MVS Authorized Assembler Services

Reference Volume 2

Reference ENF-IXG, GC28-1765

 

 

Authorized Assembler Programming

OS/390 MVS Authorized Assembler Services

Reference Volume 3

Reference LLA-SDU, GC28-1766

 

 

Authorized Assembler Programming

OS/390 MVS Authorized Assembler Services

Reference Volume 4

Reference SET-WTO, GC28-1767

 

 

Data Areas Volume 1

OS/390 MVS Data Areas, Vol 1

 

(ABEP-DALT), SY28-1164

 

 

Data Areas Volume 2

OS/390 MVS Data Areas, Vol 2

 

(DCCB-ITTCTE), SY28-1165

 

 

Data Areas Volume 3

OS/390 MVS Data Areas, Vol 3 (IVT-RCWK),

 

SY28-1166

 

 

Data Areas Volume 4

OS/390 MVS Data Areas, Vol 4 (RD-SRRA),

 

SY28-1167

 

 

Data Areas Volume 5

OS/390 MVS Data Areas, Vol 5

 

(SSAG-XTLST), SY28-1168

 

 

 

MVS/ESA Resource Measurement Facility

Ð

(RMF), Version 5±Monitor I & II Reference

 

and User's Guide, LY28-1007

 

 

System Management Facilities

OS/390 MVS System Management Facilities

 

(SMF), GC28-1783

 

 

VTAM books

OS/390 eNetwork Communications Server: SNA Network Implementation,

SC31-8563

OS/390 eNetwork Communications Server: SNA Programming, SC31-8573

Other related books

IBM ESA/370 Principles of Operation, SA22-7200

IMS/ESA Application Programming: DL/I Calls, SC26-3062

OS/390 Security Server External Security Interface (RACROUTE) Macro

Reference, GC28-1922

OS/390 Security Server (RACF) Security Administrator's Guide, SC28-1915

Service Level Reporter Version 3 General Information, GH19-6529

SNA Formats, GA27-3136

SNA Sessions Between Logical Units, GC20-1868

Bibliography xxv

Determining if a publication is current

IBM regularly updates its publications with new and changed information. When ®rst published, both hardcopy and BookManager softcopy versions of a publication are usually in step. However, due to the time required to print and distribute hardcopy books, the BookManager version is more likely to have had last-minute changes made to it before publication.

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

For CICS Transaction Server books, these softcopy updates appear regularly on the

Transaction Processing and Data Collection Kit CD-ROM, SK2T-0730-xx. Each reissue of the collection kit is indicated by an updated order number suffix (the -xx part). For example, collection kit SK2T-0730-06 is more up-to-date than SK2T-0730-05. The collection kit is also clearly dated on the cover.

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

xxvi CICS TS for OS/390: CICS Customization Guide

 

Summary of changes

|

This book is based on the Customization Guide for CICS Transaction Server for

|

OS/390 Release 2, SC33-1683-01. Changes from that edition are indicated by

|

vertical bars in the left margin.

 

 

 

Changes for this edition

|

These are the most signi®cant changes for this edition:

vThe following new global user exits are described in ªChapter 1. Global user exit programsº on page 3:

±XBMIN and XBMOUT, in CICS Basic Mapping Support

±XLDLOAD and XLDELETE, in the CICS loader domain

vThe following global user exits have been modi®ed:

±XDTAD, XDTLC, and XDTRD

±XISCONA

±XNQEREQ and XNQEREQC

±XFAINTU

±XRSINDI

±XTSPTIN, XTSQRIN, and XTSQROUT

±XTSEREQ and XTSEREQC

vInformation about using the dynamic routing program to route DPL requests and transactions started by EXEC CICS START commands has been added to ªChapter 16. Writing a dynamic routing programº on page 549.

vA new user-replaceable program, DFHDSRP, is described in ªChapter 17. Writing a distributed routing programº on page 575.

vA new user-replaceable program, DFHJVMAT, is described in ªChapter 21. Writing a program to tailor JVM execution environment variablesº on page 603. DFHJVMAT can be used to customize the execution attributes of the CICS Java virtual machine.

vA new user-replaceable program, DFHXOPUS, is described in ªChapter 20. Writing a security exit program for IIOPº on page 601. DFHXOPUS provides a

|

USERID for inbound IIOP requests.

Changes for CICS Transaction Server for OS/390 Release 2

These were the most signi®cant changes:

vThe following new global user exits were described in ªChapter 1. Global user exit programsº on page 3:

±In the dump domain:

-XDUREQC

±In the enqueue EXEC interface program:

-XNQEREQ

-XNQEREQC

±In the EXEC interface program:

-XEISPIN

© Copyright IBM Corp. 1977, 1999

xxvii

-XEISPOUT

±In the ®le control recovery program:

-XFCAREQ

-XFCAREQC

±In the 3270 bridge facility management program:

-XFAINTU

vThe following new exit programming interface (XPI) function calls were introduced:

± INQUIRE_CONTEXT

vA new user-replaceable program was described in ªChapter 19. Writing a 3270 bridge exit programº on page 599.

Changes for CICS Transaction Server for OS/390 Release 1

These were the most signi®cant changes for this edition:

vChanges to global user exits:

The following new global user exits were described in ªChapter 1. Global user exit programsº on page 3:

±In the ®le control recovery program:

-XFCBFAIL

-XFCBOUT

-XFCBOVER

-XFCLDEL

±In the ®le control quiesce program:

-XFCQUIS

-XFCVSDS

±In the Log Manager domain:

-XLGSTRM

±In the Temporary Storage domain:

-XTSPTIN

-XTSPTOUT

-XTSQRIN

-XTSQROUT

Changes were made to the following global user exits:

±XALTENF

±XFCNREC

±XFCREQ

±XFCREQC

±XFCSREQ

±XFCSREQC

±XICTENF

±XRCINIT

±XRCINPT

±XRSINDI

xxviii CICS TS for OS/390: CICS Customization Guide

The following global user exits became obsolete:

±XDBDERR

±XDBFERR

±XDBIN

±XDBINIT

±XJCWB

±XJCWR

±XKCREQ

±XRCFCER

±XRCOPER

±XTSIN

±XTSOUT

±XTSREQ

v Changes to task-related user exits:

ªChapter 2. Task-related user exit programsº on page 249 describes how task-related user exits can be invoked for SPI calls; and, if CICS is in-doubt about the outcome of a unit of work, can be told to wait rather than to take a forced decision.

vChanges to the exit programming interface (XPI): The following new XPI function calls were introduced:

±INQUIRE_PARAMETERS

±SET_PARAMETERS

The following existing XPI calls were modi®edÐthat is, new options were added, or obsolete options removed:

±INQUIRE_SYSTEM

±INQUIRE_TRANDEF

±INQUIRE_TRANSACTION

±SET_SYSTEM

±WRITE_JOURNAL_DATA

v Extensions to the interface to the autoinstall user program: Two new chapters were added:

±ªChapter 13. Writing a program to control autoinstall of shipped terminalsº on page 523

±ªChapter 14. Writing a program to control autoinstall of Client virtual terminalsº on page 531.

Also, ªChapter 12. Writing a program to control autoinstall of APPC connectionsº on page 513 was extended, to describe extensions for generic resource support.

vThe CICS log manager:

ªChapter 23. CICS logging and journalingº on page 629 was rewritten and extended to describe the functions of the new CICS log manager.

vMiscellaneous changes:

±ªThe shutdown assist utility program, DFHCESDº on page 395 describes the utility program that replaces the DFH$SDAP program of CICS/ESA® 4.1.

Summary of changes xxix

±The descriptions of ®elds in CICS-produced monitoring records, previously in ªChapter 24. CICS monitoringº on page 657, were moved to theCICS Performance Guide.

xxx CICS TS for OS/390: CICS Customization Guide

Part 1. Customizing with user exit programs

© Copyright IBM Corp. 1977, 1999

1

2 CICS TS for OS/390: CICS Customization Guide

Chapter 1. Global user exit programs

This chapter describes the CICS global user exit points, and how you can use them, in conjunction with programs of a special type that you write yourself (global user exit programs), to customize your CICS system. The chapter is divided into the 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.ªGlobal user exit programsº on page 4 covers topics that you need to consider when writing a global user exit program. It deals with the following:

vªRegister conventionsº on page 4

vª31-bit addressing implicationsº on page 5

vªUsing CICS servicesº on page 5

vªUsing EDF with global user exitsº on page 6

vªThe global work areaº on page 6

vªMaking trace entriesº on page 7

vªParameters passed to the global user exit programº on page 7

vªReturning values to CICSº on page 10

vªRestrictions on the use of ®elds as programming interfacesº on page 11

vªExit programs and the CICS storage protection facilityº on page 11

vªErrors in user exit programsº on page 12

vªDe®ning, enabling, and disabling an exit programº on page 13

vªInvoking more than one exit program at a single exitº on page 13

vªInvoking a single exit program at more than one exitº on page 14

vªSample global user exit programsº on page 14.

3.ªList of global user exit pointsº on page 19 lists the global user exit points in alphabetical order. The sections that follow contain detailed information about each global user exit point, including the place in the CICS code at which it occurs, and the speci®c (as distinct from the standard) parameters that are passed 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 a place in a CICS module or domain 1 at which CICS can transfer control to a program that you have written (a global user exit program), and at which CICS can resume control when your exit program has ®nished its work. You do not have to use any of the global user exits, but you can use them to extend and customize the function of your CICS system according to your own requirements. For a complete list of the global user exit points, see Table 2 on page 19.

1.A domain is an isolated functional unit of CICS Transaction Server for OS/390 Release 3 that communicates with the rest of CICS and with other programs using a set of strictly de®ned and controlled interfaces.

© Copyright IBM Corp. 1977, 1999

3

global user exit programs

Each global user exit point has a unique identi®er, and is located at a point in the module or domain at which it could be useful to do some extra processing. For example, at exit point XSTOUT in the statistics domain, an exit program can be given control before each statistics record is written to the SMF data set, and can access the relevant statistics record. You might want to use an exit program at this exit point to examine the statistics record and suppress the writing of unwanted records.

Global user exit support is provided automatically by CICS. However, there are several conventions that govern how you write your exit program, which are described in ªGlobal user exit programsº. Also in that section is a list of the standard 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 or domain, there are limits on the use you can make of CICS services. Most global user exit programs cannot use EXEC CICS commands. By contrast, most global user exit programs can invoke some CICS services using the exit programming interface (XPI). For more information, see ªUsing CICS servicesº on page 5.

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

Global user exit programs

A global user exit program must be written in assembler language and must be quasireentrant. However, if your user exit program calls the XPI, it must be fully reentrant. 2 (For details about coding programs using XPI calls, refer to ªChapter 3. The user exit programming interface (XPI)º on page 283.)

Register conventions

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

vRegister 1 contains the address of the user exit parameter list DFHUEPAR.

Write-to-operator (WTO) commands use register 1. If your exit program uses WTO commands, you should save the address of DFHUEPAR ®rst.

vRegister 13 contains the address of the standard register save area where your exit program should store its own registers immediately after being invoked. This address is also in the ®eld UEPEPSA in the parameter list pointed to by register 1.

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

vRegister 14 contains the return address to which the exit program should branch on completion of its work. You do this using the BR 14 instruction after restoring the calling module's registers, or using the RETURN macro.

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

4 CICS TS for OS/390: CICS Customization Guide

global user exit programs

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 exit program should save and restore any registers that it modi®es, using the save area addressed by register 13.

31-bit addressing implications

vThe global user exit is invoked in 31-bit AMODE.

vThe global user exit may be either RMODE 24 or RMODE ANY.

vIf you ®nd it necessary to switch to 24-bit AMODE in the exit program, be sure to return correctly in 31-bit AMODE.

vEnsure the exit program is in 31-bit AMODE for XPI calls.

vSome of parameters passed in DFHUEPAR are addresses of storage above the 16MB line.

Access register implications

vThe global user exit is invoked in primary-space translation mode. For information about translation modes, see the IBM ESA/370 Principles of Operation manual.

vThe contents of the access registers are unpredictable. For information about access registers, see the IBM ESA/370 Principles of Operation manual.

vIf the global user exit modi®es any access registers, it must restore them before returning control. CICS does not provide a save area for this purpose.

vThe global user exit must return control in primary addressing mode.

Using CICS services

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

vNo CICS services can be invoked from any exit point in the dispatcher domain.

vCICS 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 for each exit and each of the XPI macros. The XPI is described in ªChapter 3. The user exit programming interface (XPI)º on page 283.

vSome CICS services can be requested using EXEC CICS commands from some exits. The valid commands are listed in the detailed descriptions of the exits. If no commands are listed, it means that no EXEC CICS API or SPI commands are supported.

|

An exit program invoked at an exit that does not support the use of EXEC CICS

|

commands should not call a task-related user exit program (TRUE). (Calling a

|

TRUE is equivalent to issuing an EXEC CICS command.) TRUEs are described

|

in ªChapter 2. Task-related user exit programsº on page 249.

vAll exit programs that issue EXEC CICS commands must ®rst address the EIB. This is not done automatically via the DFHEIENT macro, as is the case with normal EXEC assembler-language programs. Therefore, the ®rst EXEC command to be issued from an exit program must be EXEC CICS ADDRESS EIB (eib-register), where ªeib-registerº is the default register (R11) or the register given as a parameter to the DFHEIENT macro.

Chapter 1. Global user exit programs 5

global user exit programs

All exit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See ªReturning values to CICSº on page 10.

Important

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

vDo not make non-CICS (for example, RACF® or MVS) system service calls from global user exit programs.

vIf an operating system request causes a wait, your whole CICS system will stop until the operating system request has been serviced.

Using EXEC CICS and XPI calls in the same exit program

There are a number of exits where you can use both EXEC CICS commands and XPI calls, but you should ensure that there is no con¯ict in the usage of register 13. To avoid such con¯ict, use the DATAREG option on the DFHEIENT macro (see ªXPI register usageº on page 291 for information).

For an example of how to use EXEC CICS commands and XPI calls in the same global user exit program, see ªAppendix E. The example program for the XTSEREQ global user exit, DFH$XTSEº on page 807

Using EDF with global user exits

If you use the Execution Diagnostic Facility (EDF) to debug your applications, you must take care when compiling exit programs that issue EXEC CICS commands.

Normally, if an exit program issues EXEC CICS commands, these are displayed by EDF, if the latter is active. They appear between the ªStart of Commandº and ªEnd of Commandº screens for the command that caused the exit to be driven. If you want to suppress the display of EXEC CICS commands issued by your exit

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

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

The global work area

When you enable an exit program, you can ask CICS to provide a global work area for the exit program. An exit program can have its own global work area, or it can share a work area that is owned by another exit program. Note that the work area is associated with the exit program rather than with the exit point. For ease of problem determination, the global work area should be shared only by exit programs that are invoked from the same management module or domain. The address and length of the global work area are addressed by parameters UEPGAA and UEPGAL of the DFHUEPAR parameter list, which is described in ªDFHUEPAR standard parametersº on page 8. If a user exit program does not own a global work area, UEPGAA is set to zero.

6 CICS TS for OS/390: CICS Customization Guide

global user exit programs

Application programs can communicate with user exit programs that use or share the same global work area. The application program uses the EXEC CICS EXTRACT 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. For examples of how to use a global work area, see the sample global user exit programs. They are listed in ªSample global user exit programsº on page 14.

Making trace entries

If tracing is active, an entry in the CICS trace table can be made immediately before and immediately after the execution of an exit program. To specify that these entries are to be made, use the UE option of either:

vThe CETR transaction

vThe EXEC CICS SET TRACETYPE command.

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

In some cases, when tracing is active, you can also make trace entries from within a user exit program, using the XPI DFHTRPTX TRACE_PUT macro described in ªChapter 3. The user exit programming interface (XPI)º on page 283. The individual descriptions of the global user exit points show whether the XPI DFHTRPTX macro can be used at each point.

Parameters passed to the global user exit program

The 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 exit programs, and may also contain some exit-speci®c parameters that are unique to the exit point from which the exit program is being invoked. Not all of the exit points have these extra parameters.

The exit-speci®c parameters are described with the individual exits in the section ªList of global user exit pointsº on page 19. The standard parameter list is described in the following section.

You can map the parameter list using the DSECT DFHUEPAR, which is generated by the macro instruction

DFHUEXIT TYPE=EP,ID=exit_point_identifier

The ID parameter provides the extra data de®nitions that you need to map any exit-speci®c parameters. For example, the macro instruction

DFHUEXIT TYPE=EP,ID=XTDIN

generates the DSECT to map the standard parameters followed by the parameters that are speci®c to exit point XTDIN in the transient data program. If your exit program is to be invoked at more than one exit point, you can code up to 256 characters of relevant exit identi®ers on a single DFHUEXIT macro instruction. For example:

DFHUEXIT TYPE=EP,ID=(XMNOUT,XSTOUT,XTDIN)

Chapter 1. Global user exit programs 7

global user exit programs

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 a task-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 an external RMI, the DFHRMCAL macro instruction must follow the DFHUEXIT macro.

DFHUEPAR standard parameters

DFHUEPAR DSECT

*STANDARD PARAMETERS

UEPEXN

DS

A

ADDRESS OF EXIT NUMBER

UEPGAA

DS

A

ADDRESS OF GLOBAL WORK AREA

*

 

 

(ZERO = NO WORK AREA)

UEPGAL

DS

A

ADDRESS OF GLOBAL WORK AREA LENGTH

UEPCRCA

DS

A

ADDRESS OF CURRENT RETURN-CODE

UEPTCA

DS

A

RESERVED

UEPCSA

DS

A

RESERVED

UEPEPSA

DS

A

ADDRESS OF REGISTER SAVE AREA

*

 

 

FOR USE BY EXIT PROGRAM

UEPHMSA

DS

A

ADDRESS OF SAVE AREA USED FOR

*

 

 

HOST MODULE©S REGISTERS

UEPGIND

DS

A

ADDRESS OF CALLER©S TASK INDICATORS

UEPSTACK DS

A

ADDRESS OF KERNEL STACK ENTRY

UEPXSTOR DS

A

ADDRESS OF STORAGE FOR XPI PARAMETERS

UEPTRACE DS

A

ADDRESS OF TRACE FLAG

UEPEXN

points to a 1-byte binary ®eld whose contents identify the global user exit point from which the exit program is being invoked. You need this information if your exit program can be invoked from more than one exit point.

DFHUEXIT TYPE=EP generates a list of equated values that relate the exit names (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 in any future releases of CICS.

UEPGAA

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

UEPGAL

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

UEPCRCA

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

8 CICS TS for OS/390: CICS Customization Guide

global user exit programs

UEPTCA

points to fetch-protect storage. Use of this ®eld results in an abend ASRD at execution time.

UEPCSA

points to fetch-protect storage. Use of this ®eld results in an abend ASRD at execution time.

UEPEPSA

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

UEPHMSA

points to the save area containing the registers of the calling module. Values for registers 14, 15, 0±13 are stored in this order from offset 12 (decimal) in this area.

 

 

Apart from register 15, which contains the return code value from the exit

 

 

program, the values in this save area are used by CICS to reload the registers

 

 

when returning to the calling CICS module. They should not be corrupted.

 

 

This address is not passed to global user exit programs invoked from exit

 

 

points in CICS domains.

|

UEPGIND

 

 

 

|

 

points to a 3-byte ®eld containing indicators for use in AP domain user exits.

|

 

For non-AP domain user exits, the indicators are always zero.

|

 

The ®rst indicator byte can take one of two symbolic values, UEPGANY and

|

 

UEPGCICS, which you can test to determine whether data locations can be

|

 

above or below 16MB, and whether the application's storage is in CICS-key or

|

 

user-key storage:

 

|

 

UEPGANY

 

|

 

 

The application can accept addresses above 16MB. If the symbolic

|

 

 

value is not UEPGANY, the application must be returned an address

|

 

 

below 16MB.

 

|

 

UEPGCICS

 

|

 

 

The application's working storage and the task's life-time storage are in

|

 

 

CICS-key storage (TASKDATAKEY=CICS). If the symbolic value is not

|

 

 

UEPGCICS, the application's working storage and the task's life-time

|

 

 

storage are in user-key storage (TASKDATAKEY=USER).

|

 

The second and third bytes contain a value indicating the TCB mode of the

|

 

global user exit program's caller. This is represented in DFHUEPAR as both a

|

 

two-character code and a symbolic value, as follows:

|

 

Table 1. TCB indicators in DFHUEPAR. Description

|

 

 

 

 

 

 

Symbolic

 

2-byte

Description

|

 

value

 

code

 

|

 

 

 

 

 

 

UEPTQR

 

QR

The quasi-reentrant mode TCB

|

 

 

 

 

 

 

UEPTCO

 

CO

The concurrent mode TCB

|

 

 

 

 

 

 

UEPTFO

 

FO

The ®le-owning mode TCB

|

 

 

 

 

 

 

UEPTRO

 

RO

The resource-owning mode TCB

 

 

 

 

 

 

Chapter 1. Global user exit programs 9

global user exit programs

|

Table 1. TCB indicators in DFHUEPAR (continued). Description

|

 

 

 

Symbolic

2-byte

Description

|

value

code

 

|

 

 

 

UEPTRP

RP

The ONC/RPC mode TCB

|

 

 

 

UEPTSZ

SZ

The FEPI mode TCB

|

 

 

 

UEPTJ8

J8

The JVM mode TCB

|

 

 

 

UEPTL8

L8

An open mode TCB

|

 

 

 

UEPTSL

SL

The sockets listener mode TCB

|

 

 

 

UEPTSO

SO

The sockets mode TCB

|

 

 

 

UEPTS8

S8

The secure sockets layer mode TCB

 

 

 

 

|

UEPSTACK

 

 

 

points to the kernel stack entry. This value must be moved to the exit program's

 

register 13 before invoking the XPI. For more information, refer to ªChapter 3.

 

The user exit programming interface (XPI)º on page 283. The storage

 

addressed by this ®eldmust not be altered. If it is corrupted, your exit program

 

will have unpredictable effects on your CICS system.

 

UEPXSTOR

#

points to a 320-byte area of DFHUEH-owned LIFO storage that the exit

#

program should use when invoking the XPI. For more information, refer to

#

ªChapter 3. The user exit programming interface (XPI)º on page 283.

UEPTRACE

points to the trace ¯ag, which indicates whether tracing is on in the calling management module or domain. This enables you to control your use of the XPI TRACE_PUT macro in line with the tracing in the CICS module or domain. The XPI TRACE_PUT function should be used only when tracing is on. The trace ¯ag is a single byte, whose top bit is set on when tracing is switched on. You test this setting using the symbolic value UEPTRON. The rest of the byte addressed by UEPTRACE is reserved, and its contents should not be corrupted.

Returning values to CICS

At some exit points, you can in¯uence what CICS does on return from an exit program by supplying a return code value. The return code value must be set in register 15 before leaving the exit program. Character strings equating to valid return code values are provided with the parameter list appropriate for each exit point. Always use the equated values rather than using hard-coded values. For example, at exit XMNOUT in the monitor domain, you are presented with the address of a monitoring record. If you decide in your exit program that this record should not be written to SMF, you can set the return code value UERCBYP (meaning ªbypass this recordº) before returning to CICS, and CICS suppresses the record.

You cannot in¯uence CICS actions in this way at all exit points. If you supply a return code value that is not expected at a particular exit point, the default return code indicating a normal response (usually UERCNORM) is assumed, unless the return code UERCPURG is set (see note below about UERCPURG). You are strongly advised not to let the return code default to the normal response as the result can be unpredictable. The normal response tells CICS to continue processing

10 CICS TS for OS/390: CICS Customization Guide

global user exit programs

as if the exit program had not been invoked, and it is a valid option at most global user exit points. The exceptions are shown in the list of return codes provided with each exit description.

The return code currently established for an exit is addressed by parameter UEPCRCA of DFHUEPAR, and it is needed when two or more exit programs are used at one exit. For more information, see ªInvoking more than one exit program at a single exitº on page 13.

The return codes that are valid at each of the global user exit points are described in ªList of global user exit pointsº on page 19.

Important

vAt some exit points, the return code UERCPURG is valid. These exits are identi®ed in the following tables. To prevent unpredictable results, you must not set the return code UERCPURG except as described on page 289.

vExit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. The DFHEIRET macro:

±Restores registers

±Places a return code in register 15 after the registers are restored

±Returns control to the address in register 14.

For example:

DFHEIRET RCREG=nn

where ªnnº is the number of any register (other than 13) that contains the return code to be placed in register 15 after the registers are restored.

Restrictions on the use of ®elds as programming interfaces

The CICS Data Areas manual contains de®nitions of the control block ®elds that form part of the Product-sensitive and General-use programming interfaces of CICS. Fields that are not de®ned in theCICS Data Areas manual as either Product-sensitive programming interface or General-use programming interface ®elds arenot intended for your use as part of a CICS programming interface.

Exit programs and the CICS storage protection facility

When you are running CICS with the storage protection facility, there are two points you need to consider for global user exits:

1.The execution key in which your user exit programs run

2.The storage key of data storage obtained for your exit programs.

Execution key for global user exit programs

When you are running with storage protection active, CICS always invokes global user exit programs in CICS key. Even if you specify EXECKEY(USER) on the program resource de®nition, CICS forces CICS key when it passes control to the exit program. However, if a global user exit program itself passes control to another

Chapter 1. Global user exit programs 11

global user exit programs

program (via a link or transfer-control command), the program thus invoked is executed according to the execution key (EXECKEY) de®ned in its program resource de®nition.

Important

You are strongly recommended to specify EXECKEY(CICS) when de®ning both global user exit programs and programs to which an exit program passes control.

Data storage key for global user exit programs

The storage key of storage used by global user exit programs depends on how the storage is obtained:

vThe CICS-supplied storage addressed by the UEPXSTOR parameter of DFHUEPAR, and any global work area speci®ed when an exit program is enabled, are always in CICS key.

vGlobal user exit programs that can issue EXEC CICS commands can obtain storage by:

±Explicit EXEC CICS GETMAIN commands

±Implicit storage requests as a result of EXEC CICS commands that use the SET option.

The default storage key for storage obtained by EXEC CICS commands is set by the TASKDATAKEY of the transaction under which the exit program is invoked.

As an example, consider a transaction de®ned with TASKDATAKEY(USER) that issues a ®le control request, which causes an XFCREQ global user exit program to be invoked. In this case, any implicit or explicit storage acquired by the exit program by means of an EXEC CICS command is, by default, in user-key storage. However, on an EXEC CICS GETMAIN command, the exit program can override the TASKDATAKEY option by specifying either CICSDATAKEY or USERDATAKEY.

vWhen an exit program obtains storage by means of an XPI GETMAIN call, the storage key depends on the value speci®ed on the STORAGE_CLASS option, which is mandatory, and which overrides the value of TASKDATAKEY.

Errors in user exit programs

Because global user exit programs are an extension to CICS code, they are subject to the environment that CICS is running in when they are called. If an error is detected at an exit point, CICS issues messages indicating which exit program was in error, the place in the program at which the error occurred, and the name of the associated exit point. The detection of an error is not guaranteed, because it depends on the CICS environment at the time of error, and on the nature of the error. For example, CICS might not recognize a looping user exit program, since the detection mechanism may have been turned off. Also, an abend in one of the exits XPCABND, XPCTA, or XSRAB may cause CICS to terminate abnormally, because an abend during abend processing causes CICS to terminate.

Exit programs invoked at some exit points (for example, XTSEREQ, XTSEREQC, XICEREQ, XICEREQC, XTDEREQ, or XTDEREQC) can enter a loop by issuing a

12 CICS TS for OS/390: CICS Customization Guide

global user exit programs

recursive command (such as a TS command at exit point XTSEREQ). The exits most likely to be affected provide a recursion count parameter, UEPRECUR, that you can use to prevent such loops.

Important

When coding user exit programs, you should bear in mind that the code is executed as an extension of CICS code, rather than as a transaction, and any errors could have disastrous results.

De®ning, enabling, and disabling an exit program

When you have written an exit program, you must de®ne it to CICS using the CEDA DEFINE PROGRAM command. (Note that you must specify RELOAD(NO).)

Having de®ned the exit program, you must also enable it. You do this using the EXEC CICS ENABLE command.3 When you have ®nished using the exit program, you should disable it, using the EXEC CICS DISABLE command.

Note: If a global user exit program is enabled before it has been installed and LPA=YES is speci®ed as a system initialization parameter, CICS scans the LPA for the program. If message DFHLD0107I is issued, it means that CICS was unable to ®nd the program in the LPA and is using the DFHRPL version.

For programming information about the EXEC CICS ENABLE and DISABLE commands, see the CICS System Programming Reference manual. For examples of how to enable and disable global user exit programs, see the sample programs listed on page 14.

Invoking more than one exit program at a single exit

There may be times when you want to invoke more than one exit program from a single global user exit point. For example, you might have two or more application packages that supply programs for the same CICS exit. Although such programs may work independently, you should note the following points:

vAn exit program is only called at an exit if it has been made available for execution with the START option of the EXEC CICS ENABLE command. The order of invocation, when more than one exit program has been started at an exit point, is the order in which the programs were activated (that is, the order in which the EXEC CICS ENABLE commands associated them with the exit point). When programs work on the same data area, you should consider the order in which they are invoked. For example, in a terminal control output exit, an exit program might manipulate the same message in different ways, depending on the way an earlier exit program acted.

vReturn code management is more complicated than it is for single programs. Each exit program sets a return code in register 15 as usual. The second and subsequent programs invoked from a single exit point can access the return code value set by the preceding program (the ªcurrent return codeº) using the parameter UEPCRCA of DFHUEPAR.

3.Exit programs for exits in the user log record recovery program and the ®le control recovery control program can also be enabled using the TBEXITS system initialization parameter.

Chapter 1. Global user exit programs 13

global user exit programs

The following rules apply to return codes if a second user exit program sets a different return code value from that selected by the previous program:

± If the new program supplies the same return code value as the current return code (addressed by UEPCRCA), then CICS acts on that value.

± If the new program supplies a different return code value from the current value addressed by UEPCRCA, CICS ignores both values and resets the ªcurrent return codeº to the default value, usually UERCNORM, before calling any further exit programs for that exit point.

± If the new program sets an eligible value in register 15 and changes the ªcurrent valueº ®eld to match (as addressed by UEPCRCA), the new value is adopted and passed on to the next program (if any), or back to the calling CICS module or domain.

Invoking a single exit program at more than one exit

To invoke a single exit program from more than one exit point, you must issue an ENABLE command for each of the exit points. For programming information about how to issue an ENABLE command, see the CICS System Programming Reference manual. Be careful to specify GALENGTH or GAENTRYNAME on only the ®rst ENABLE command, otherwise `INVEXITREQ' may be returned.

Take into account the restrictions that apply to the use of CICS services, because these are dictated by the exit point itself rather than by the exit program. A command that can be issued from one exit point may cause problems when issued from a different exit point.

The global work area is associated with the exit program, rather than with the exit point: this means that the same global work area is used at each of the exit points at which the exit program is invoked.

Sample global user exit programs

 

CICS provides sample global user exit programs for the following global user exit

 

points:

 

v

XALTENF and XICTENF

|

v

XBMIN and XBMOUT

 

v XDTAD, XDTLC, and XDTRD

 

v

XDUREQ

 

v XFCBFAIL, XFCBOVER, and XFCLDEL

|

v

XICEREQ

 

v

XISCONA

 

v

XMEOUT

|

v

XNQEREQ and XNQEREQC

 

v

XPCFTCH

 

v

XPCTA

 

v

XZCATT

 

v

XZIQUE

The source of all the sample programs, and any associated copy books, is supplied in the CICSTS13.CICS.SDFHSAMP library. You can use the supplied programs as models on which to base your own versions.

14 CICS TS for OS/390: CICS Customization Guide

global user exit programs

Global work area (GWA) sample exit programs

This set of sample programs shows you how to:

vEnable a global user exit program and allocate a global work area (GWA).

vObtain the address of an exit program's GWA.

vAccess CICS system information, and make that information available to other global user exit programs.

vShare a GWA between global user exit programs, thereby making the information it contains available to more than one program, and overcoming limitations on the size of GWAs.

vAccess information held in a global user exit program's GWA.

The GWA sample programs and copy books are:

DFH$PCEX

A sample global user exit program, designed to be invoked at the XPCFTCH exit.

CICS also provides copy book DFH$PCGA for use in this sample program.

DFH$ZCAT

A sample global user exit program, designed to be invoked at the XZCATT exit.

CICS also provides copy book DFH$ZCGA for use in this sample program.

DFH$PCPI and DFH$PCPL

DFH$PCPI is designed to be invoked during program list table post initialization (PLTPI) processing, and is described in ªThe DFH$PCPI programº.

DFH$PCPL is a dummy program, invoked by DFH$PCPI, that causes the XPCFTCH user exit to be driven.

The DFH$PCPI program: DFH$PCPI consists of three main sections:

1.Section 1 obtains and processes any parameters passed to DFH$PCPI on the INITPARMS system initialization parameter.

2.Section 2 shows how to use standard CICS facilities to obtain system information, and make that information available to a global user exit program. It performs the following processing:

v Uses the EXEC CICS ENABLE command to enable the XPCFTCH sample user exit program, DFH$PCEX, and allocate it a global work area.

vUses the EXEC CICS EXTRACT EXIT command to obtain the address of DFH$PCEX's global work area.

vObtains CICS system information, and places it in DFH$PCEX's global work area. The information obtained includes:

±Job name

±Applid

±Sysid

±CICS release

±Date in various formats, including DATFORM

±The address of the common work area (CWA)

±CICS startup type (COLD, WARM).

Chapter 1. Global user exit programs 15

global user exit programs

Most of the above information is obtained using EXEC CICS API commands such as:

±INQUIRE SYSTEM

±ASSIGN

±ADDRESS

±ASKTIME

±FORMATTIME.

vUses the START option of the EXEC CICS ENABLE command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINKs and XCTLs.

vLinks to the dummy program, DFH$PCPL, in order to drive DFH$PCEX.

vUses the STOP option of the EXEC CICS DISABLE command to make DFH$PCEX unavailable for execution. Note that this leaves DFH$PCEX's global work area still allocated and accessible through the EXEC CICS EXTRACT EXIT command.

3.Section 3 of DFH$PCPI shows how to share the system information in an exit program's global work area with other exit programs. (In doing so it demonstrates how application programs can access the same information by means of the EXEC CICS EXTRACT EXIT command.) It also shows how to use CICS shared storage to overcome the limitation of 32KB on the size of a GWA. The program obtains an area of 64KB below 16MB and an area of 128KB above 16MB (using GETMAIN). The use of shared storage enables the second user exit program (DFH$ZCAT) to use a work area of only 12 bytes below 16MB.

The section performs the following processing:

vUses EXEC CICS ENABLE to enable the DFH$ZCAT user exit program, and allocate it a global work area

vUses EXEC CICS EXTRACT EXIT to obtain the address of DFH$ZCAT's global work area

vStores the address of DFH$PCEX's global work area in DFH$ZCAT's global work area

vUses GETMAIN to obtain the shared storage above and below the 16MB line, and stores the addresses in DFH$ZCAT's global work area.

Sample program de®nitions: The following are examples of the RDO de®nitions required to de®ne the sample programs to the CSD:

DEFINE PROGRAM(DFH$PCEX) GROUP(EXITGRP)

LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)

USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY) EXECKEY(CICS)

DEFINE PROGRAM(DFH$PCPI) GROUP(EXITGRP)

LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)

USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)

EXECKEY(CICS)

DEFINE PROGRAM(DFH$PCPL) GROUP(EXITGRP)

LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)

USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)

EXECKEY(CICS)

DEFINE PROGRAM(DFH$ZCAT) GROUP(EXITGRP)

LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)

USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)

EXECKEY(CICS)

16 CICS TS for OS/390: CICS Customization Guide

 

global user exit programs

 

DFH$PCPI is designed to be run as a PLT program. If you write a similar program,

 

you should de®ne it in thesecond part of the PLTPI list (after the

 

PROGRAM=DFHDELIM entry). Information about how to do this is in the CICS

|

Resource De®nition Guide.

|

The Basic Mapping Support sample exit program

|

CICS supplies a sample global user exit program for the Basic Mapping support

|

exits:

|

DFH$BMXT

|

A sample global user exit program, designed to be invoked at the XBMIN

|

and XBMOUT exits. The program shows how you can use the exits to

|

modify mapped input and output data.

|

The data tables sample exit programs

 

CICS supplies one sample global user exit program for each of the data tables exit

 

points. These are:

 

DFH$DTAD

 

A sample global user exit program, designed to be invoked at the XDTAD

 

exit.

 

DFH$DTLC

 

A sample global user exit program, designed to be invoked at the XDTLC

 

exit.

 

DFH$DTRD

 

A sample global user exit program, designed to be invoked at the XDTRD

 

exit.

 

DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data

 

Tables Guide.

 

The dump domain sample exit program

 

There is one dump domain sample global user exit program:

 

DFH$XDRQ

 

A sample global user exit program, designed to be invoked at the XDUREQ

 

exit.

|

The enqueue EXEC interface sample exit program

|

There is one sample global user exit program for the enqueue EXEC interface.

|

DFH$XNQE

|

A sample global user exit program, designed to be invoked at the

|

XNQEREQ and XNQEREQC exits. The program demonstrates three ways

|

of adding a SCOPE value to EXEC CICS ENQ and DEQ requests, to make

|

the requests apply to multiple regions within the sysplex.

|

The ®le control recovery program sample exit programs

 

CICS provides three sample ®le control global user exit programs:

 

DFH$FCBF

 

A sample exit program designed to be invoked at the XFCBAIL exit for

 

handling backout failures. See ªDFH$FCBF sample global user exit

 

programº on page 116.

Chapter 1. Global user exit programs 17

global user exit programs

DFH$FCBV

A sample exit program designed to be invoked at the XFCBOVER exit; it allows you to decide whether to allow an update to be backed out, following a batch update run that has overridden retained locks. See ªDFH$FCBV sample global user exit programº on page 121.

DFH$FCLD

A sample exit program designed to be invoked at the XFCLDEL exit, which allows you to perform logical deletion of records from a VSAM ESDS data set or a BDAM data set, during backout. See ªDFH$FCLD sample global user exit programº on page 123.

 

You can de®ne these programs by including the supplied resource group,

 

DFH$FCB, in your startup grouplist, or by using CEDA to install DFH$FCB.

 

The function-shipping and DPL queue control sample exit

 

program

|

You can use the XISCONA sample global user exit program to control the queueing

|

of function-shipping and DPL requests:

 

DFHXIS

 

A sample global user exit program, designed to be invoked at the XISCONA

 

exit.

|

The interval control EXEC interface sample exit program

|

DFH$ICCN

|

A sample global user exit program, designed to be invoked at the XICEREQ

|

exit. DFH$ICCN is for use in a distributed routing environment, where you

|

want to cancel a previously-issued interval control request but have no way

|

of knowing to which region to direct the CANCEL. For examples of

|

situations which DFH$ICCN is designed to cope with, see the CICS

|

Intercommunication Guide.

|

The ISC session queue management sample exit program

 

This sample program implements the same basic function provided by the

 

QUEUELIMIT and MAXQTIME parameters on a connection resource de®nition.

 

These parameters are passed to the XZIQUE global user program, which can

 

change the way in which these parameters are used:

 

DFH$XZIQ

 

A sample global user exit program, designed to be invoked at the XZIQUE

 

exit, which is described on page ªXZIQUE exit for managing intersystem

 

queuesº on page 237.

 

See ªSample exit program designº on page 244 for more details.

 

The message domain sample exit programs

 

These sample programs show you how to write a program to be invoked at a

 

speci®c exit, to do a speci®c task. For example, the DFH$SXP4 sample program

 

shows you how to use the XMEOUT exit to reroute a console message to a

 

transient data queue.

 

DFH$SXPn

 

A set of sample global user exit programs designed to be invoked at the

 

XMEOUT exit (where `n' is 1 through 6).

18 CICS TS for OS/390: CICS Customization Guide

global user exit programs

The terminal-not-known sample exit program

You can use this sample global user exit program to handle terminal-not-known conditions arising from START and ATI requests:

DFHXTENF

A sample global user exit program, designed to be invoked at the XALTENF or XICTENF exit. The sample source code is shown on page ªThe sample program for the XALTENF and XICTENF exits, DFHXTENFº on page 214.

The transaction-abend sample exit program

There is one sample global user exit program for the XPCTA exit point:

DFH$PCTA

This sample global user exit program is designed to be invoked at the XPCTA exit, to test whether the abend was caused by a storage protection exception condition. It is described on page ªThe sample XPCTA global user exit program, DFH$PCTAº on page 169.

Example program

As well as the sample programs supplied in source code, there is an example listing, DFH$XTSE, that shows you how to:

vUse EXEC CICS commands in a global user exit program

vUse EXEC CICS commands and XPI calls in the same exit program

vModify the command parameter list in EXEC interface exits such as XTSEREQ and XICEREQ.

DFH$XTSE is listed on page 807.

List of global user exit points

Table 2 lists the global user exit points in alphabetical order, giving a brief description and a page reference at which more information about each exit can be found.

 

Table 2. Alphabetical list of global user exit points

 

 

 

 

 

 

 

Exit name

Module or

Where or when invoked

Page

 

 

domain

 

 

 

 

 

 

 

 

XAKUSER

Activity keypoint

Immediately before the `end of keypoint'

25

 

 

program

record is written.

 

 

 

 

 

 

 

XALCAID

Terminal

Whenever an AID with data is canceled.

203

 

 

allocation

 

 

 

XALTENF

When an ATI request from transient

209

 

program

 

 

data or interval control requires a

 

 

 

 

 

 

 

 

terminal that is unknown in this system.

 

|

 

 

 

 

XBMIN

Basic Mapping

When an input mapping operation

28

|

 

Support

completes successfully.

 

|

 

 

 

 

XBMOUT

 

When a page of output has been built

28

|

 

 

successfully.

 

 

 

 

 

 

 

XDLIPOST

DL/I interface

On exit from the DL/I interface program.

47

 

 

program

 

 

 

XDLIPRE

On entry to the DL/I interface program.

45

 

 

 

 

 

 

 

Chapter 1. Global user exit programs 19

global user exit points

Table 2. Alphabetical list of global user exit points (continued)

Exit name

Module or

Where or when invoked

Page

 

domain

 

 

 

 

 

 

XDSAWT

Dispatcher

After an operating system wait.

42

 

domain

 

 

XDSBWT

Before an operating system wait.

42

 

 

 

 

 

XDTAD

Data tables

When a write request is issued to a

36

 

management

data table.

 

 

 

 

 

XDTLC

 

At the completion of loading of a data

37

 

 

table.

 

 

 

 

 

XDTRD

 

During the loading of a data table,

34

 

 

whenever a record is retrieved from the

 

 

 

source data set.

 

 

 

 

 

XDUCLSE

Dump domain

After the domain closes a transaction

55

 

 

dump data set.

 

 

 

 

 

XDUOUT

 

Before the domain writes a record to

55

 

 

the transaction dump data set.

 

 

 

 

 

XDUREQ

 

Before the domain takes a system or

49

 

 

transaction dump.

 

 

 

 

 

XDUREQC

 

After a system or transaction dump has

52

 

 

been taken (or failed or been

 

 

 

suppressed).

 

 

 

 

 

XEIIN

EXEC interface

Before the execution of any EXEC

66

 

program

CICS API or SPI command.

 

 

 

 

 

XEIOUT

 

After the execution of any EXEC CICS

68

 

 

API or SPI command.

 

 

 

 

 

XEISPIN

 

Before the execution of any EXEC

67

 

 

CICS SPI command except EXEC

 

 

 

CICS ENABLE, EXEC CICS DISABLE,

 

 

 

or EXEC CICS EXTRACT EXIT.

 

 

 

 

 

XEISPOUT

 

After the execution of any EXEC CICS

68

 

 

SPI command except EXEC CICS

 

 

 

ENABLE, EXEC CICS DISABLE, or

 

 

 

EXEC CICS EXTRACT EXIT.

 

 

 

 

 

XFAINTU

3270 bridge

When a bridge facility is created or

32

 

facility

deleted.

 

 

management

 

 

 

program

 

 

 

 

 

 

XFCAREQ

File control EXEC

Before CICS processes a ®le control

83

 

interface program

SPI request.

 

 

 

 

 

XFCAREQC

 

After a ®le control SPI request has

83

 

 

completed.

 

 

 

 

 

20 CICS TS for OS/390: CICS Customization Guide

global user exit points

Table 2. Alphabetical list of global user exit points (continued)

Exit name

Module or

Where or when invoked

Page

 

domain

 

 

 

 

 

 

XFCBFAIL

File control

When an error occurs during the

112

 

recovery control

backout of a UOW.

 

 

program

 

 

XFCBOUT

When CICS is about to back out a ®le

117

 

 

 

update.

 

 

 

 

 

XFCBOVER

 

When CICS is about to skip backout of

119

 

 

a UOW because a batch program has

 

 

 

overridden RLS retained lock protection

 

 

 

and opened a data set for batch

 

 

 

processing.

 

 

 

 

 

XFCLDEL

 

When backing out writes to a VSAM

122

 

 

ESDS or a BDAM data set.

 

 

 

 

 

XFCNREC

File control

When a mismatch is detected between

106

 

open/close

the backout recovery setting for a ®le

 

 

program

and its associated data set during ®le

 

 

 

open processing.

 

 

 

 

 

XFCQUIS

File control

On completion, successful or failed, of a

110

 

quiesce send

SET DSNAME QUIESCESTATE

 

 

program

command.

 

 

 

 

 

XFCREQ

File control EXEC

Before CICS processes a ®le control

79

 

interface program

API request.

 

 

 

 

 

XFCREQC

 

After a ®le control API request has

80

 

 

completed.

 

 

 

 

 

XFCSREQ

File control ®le

Before a ®le OPEN, CLOSE, ENABLE,

96

 

state program

or DISABLE command is attempted.

 

 

 

 

 

XFCSREQC

 

After a ®le OPEN, CLOSE, CANCEL

96

 

 

CLOSE, ENABLE, or DISABLE

 

 

 

command has been completed.

 

 

 

 

 

XFCVSDS

File control

After RLS has informed CICS that

107

 

quiesce receive

processing is required as a result of a

 

 

program

data set-related action occurring in the

 

 

 

sysplex.

 

 

 

 

 

XGMTEXT

ªGood morningº

Before the ªgood morningº message is

126

 

message program

sent.

 

 

 

 

 

XICEREQ

Interval control

Before CICS processes an interval

134

 

EXEC interface

control API request.

 

 

program

 

 

XICEREQC

After an interval control API request has

135

 

 

 

completed.

 

 

 

 

 

XICEXP

Interval control

After expiry of an interval control time

133

 

program

interval.

 

 

 

 

 

XICREQ

 

At the start of the interval control

132

 

 

program, before request analysis.

 

 

 

 

 

XICTENF

 

When an EXEC CICS START command

212

 

 

requires a terminal that is unknown in

 

 

 

this system.

 

 

 

 

 

Chapter 1. Global user exit programs 21

global user exit points

 

Table 2. Alphabetical list of global user exit points (continued)

 

 

 

 

 

 

 

Exit name

Module or

Where or when invoked

Page

 

 

domain

 

 

|

 

 

 

 

XISCONA

Intersystem

When a function shipping or DPL

127

|

 

communication

request is about to be queued because

 

|

 

program

no sessions to the remote region are

 

|

 

 

immediately available.

 

 

 

 

 

 

 

XISLCLQ

 

After an attempt to allocate a session

130

 

 

 

for a function shipped START

 

 

 

 

NOCHECK request fails because the

 

 

 

 

remote system is not in service, a

 

 

 

 

connection to the remote system cannot

 

 

 

 

be established, or no sessions are

 

 

 

 

immediately available and your

 

 

 

 

XISCONA exit program has speci®ed

 

 

 

 

that the request is not to be queued in

 

 

 

 

the issuing region.

 

|

 

 

 

 

XLDLOAD

Loader domain

After an instance of a program is

147

|

 

 

brought into storage, and before the

 

|

 

 

program is made available for use.

 

|

 

 

 

 

XLDELETE

 

After an instance of a program is

148

|

 

 

released by CICS and just before the

 

|

 

 

program is freed from storage.

 

 

 

 

 

 

 

XLGSTRM

Log manager

After the CICS log manager detects that

149

 

 

domain

a log stream does not exist, and before

 

 

 

 

calling the MVS system logger to de®ne

 

 

 

 

the log stream.

 

 

 

 

 

 

 

XMEOUT

Message domain

Before a message is sent from the

153

 

 

 

message domain to its destination.

 

 

 

 

 

 

 

XMNOUT

Monitoring

Before a record is either written to SMF

156

 

 

domain

or buffered before a write to SMF.

 

 

 

 

 

 

 

XNQEREQ

Enqueue EXEC

Before CICS processes an enqueue

57

 

 

interface program

API request.

 

 

 

 

 

 

 

XNQEREQC

 

After an enqueue API request has

58

 

 

 

completed.

 

 

 

 

 

 

 

XPCABND

Program control

Before a dump call is made.

169

 

 

program

 

 

 

XPCFTCH

Before an application program is given

165

 

 

 

 

 

control.

 

 

 

 

 

 

 

XPCHAIR

 

Before a HANDLE ABEND routine is

166

 

 

 

given control.

 

 

 

 

 

 

 

XPCREQ

 

Before a LINK request is processed.

158

 

 

 

 

 

 

XPCREQC

 

After a LINK request has been

159

 

 

 

completed.

 

 

 

 

 

 

 

XPCTA

 

After an abend occurs, and before the

168

 

 

 

environment is modi®ed.

 

 

 

 

 

 

 

XRCINIT

User log record

During warm and emergency restart, if

232

 

 

recovery program

user recovery log records are detected

 

 

 

 

in the CICS system log.

 

 

 

 

 

 

 

XRCINPT

 

During warm and emergency restart, for

232

 

 

 

each user recovery log record found in

 

 

 

 

the CICS system log.

 

 

 

 

 

 

22 CICS TS for OS/390: CICS Customization Guide

global user exit points

Table 2. Alphabetical list of global user exit points (continued)

Exit name

Module or

Where or when invoked

Page

 

domain

 

 

 

 

 

 

XRMIIN

Resource

Before execution of an EXEC DLI,

171

 

manager interface

EXEC SQL, or RMI command.

 

 

program

 

 

XRMIOUT

After execution of an EXEC DLI, EXEC

171

 

 

 

SQL, or RMI command.

 

 

 

 

 

XRSINDI

Resource

Immediately after a successful install or

173

 

management

discard of a resource.

 

 

modules

 

 

 

 

 

 

XSNOFF

Security manager

After a terminal user signs off.

178

 

domain

 

 

XSNON

After a terminal user signs on.

177

 

 

 

 

 

XSRAB

System recovery

When the system recovery program

182

 

program

®nds a match for an MVS abend code

 

 

 

in the SRT.

 

 

 

 

 

XSTERM

System

During a normal system shutdown,

186

 

termination

immediately before TD buffers are

 

 

program

cleared.

 

 

 

 

 

XSTOUT

Statistics domain

Before a statistics record is written to

180

 

 

SMF.

 

 

 

 

 

XSZARQ

Front End

After a FEPI request has completed.

125

 

Programming

 

 

XSZBRQ

Before a FEPI request is actioned.

125

Interface

 

 

 

 

 

 

 

XTCATT

Terminal control

Before task attach.

206

 

program

 

 

XTCIN

After an input event.

205

 

 

 

 

 

XTCOUT

 

Before an output event.

205

 

 

 

 

XTCTIN

 

After a TCAM input event.

206

 

 

 

 

XTCTOUT

 

Before a TCAM output event.

207

 

 

 

 

XTDEREQ

Transient data

Before CICS processes a transient data

221

 

EXEC interface

API request.

 

 

program

 

 

XTDEREQC

After a transient data API request has

223

 

 

 

completed.

 

 

 

 

 

XTDIN

Transient data

After receiving data from QSAM

219

 

program

(extrapartition) or VSAM (intrapartition).

 

 

 

 

 

XTDOUT

 

Before passing data to a QSAM

220

 

 

(extrapartition) or VSAM (intrapartition)

 

 

 

user-de®ned transient data queue.

 

 

 

 

 

XTDREQ

 

Before request analysis.

218

 

 

 

 

XTSEREQ

Temporary

Before CICS processes a temporary

194

 

storage EXEC

storage API request.

 

 

interface program

 

 

XTSEREQC

After a temporary storage API request

195

 

 

 

has completed.

 

 

 

 

 

XTSPTIN

Temporary

Before invocation of a TSPT function.

190

 

storage domain

 

 

XTSPTOUT

After invocation of a TSPT function.

191

 

 

 

 

 

XTSQRIN

 

Before invocation of a TSQR function.

187

 

 

 

 

XTSQROUT

 

After invocation of a TSQR function.

188

 

 

 

 

XXDFA

DBCTL interface

In the active CICS when CICS-DBCTL

39

 

control program

connection fails.

 

 

 

 

 

Chapter 1. Global user exit programs 23

global user exit points

Table 2. Alphabetical list of global user exit points (continued)

Exit name

Module or

Where or when invoked

Page

 

domain

 

 

 

 

 

 

XXDFB

DBCTL tracking

In the alternate CICS when DBCTL

40

 

program

fails.

 

 

 

 

 

XXDTO

 

In the alternate CICS when active

41

 

 

DBCTL fails.

 

 

 

 

 

XXMATT

Transaction

When a user transaction is attached.

216

 

manager domain

 

 

 

 

 

 

XXRSTAT

XRF request

After a VTAM failure or a predatory

246

 

processing

takeover.

 

 

program

 

 

 

 

 

 

XZCATT

VTAM terminal

Before task attach.

234

 

management

 

 

 

program

 

 

 

 

 

 

XZCIN

VTAM working set

After an input event.

235

 

module

 

 

XZCOUT

Before an output event.

235

 

 

 

 

 

XZCOUT1

 

Before a message is broken into RUs.

236

 

 

 

 

XZIQUE

 

1. When an allocate request for a

237

 

 

 

 

 

session is about to be queued.

 

 

 

2. When an allocate request succeeds

 

 

 

following previous suppression of

 

 

 

queuing.

 

 

 

 

 

The following sections give detailed information about each of the global user exit points, including:

vThe exit identi®er

vThe location of the exit

vThe DFHUEPAR parameters, if any, that are unique to the exit

vThe return codes that are valid for this exit point

vXPI calls that can be invoked.

In the following sections, the exit points are grouped according to their functional relationships. This usually means according to the CICS module or domain in which they occur. However, where exit points in different modules serve a similar function (XALTENF in the terminal allocation program and XICTENF in the interval control program, for example), the exits are grouped under a generic name (for example, ªTerminal not knownº condition exits). The groups of exits are presented in alphabetical order of module or generic name.

Accessing ®elds in CICS control blocks

When writing a program to be invoked from any of the global user exit points, note the warning contained in ªRestrictions on the use of ®elds as programming interfacesº on page 11 about the use of control block ®elds as programming interfaces.

24 CICS TS for OS/390: CICS Customization Guide

activity keypoint program exit

Activity keypoint program exit XAKUSER

The XAKUSER exit is invoked during the activity keypointing process. You can use this exit to record, on the system log, user data that must be restored following an emergency restart. For further information about the use of the exit, see the CICS Recovery and Restart Guide.

For best performance, journal control requests should not specify WAIT. CICS will force the records by writing a synchronous end of keypoint record upon return from the exit program.

Your exit program should be translated with the NOEDF option. Any program it links to should also be translated with this option. It is not possible to link to programs written in PL/I.

To ensure that it is called during every keypoint, your exit program should be enabled by means of a ®rst phase PLTPI programÐsee ªInitialization programsº on page 393. However, if it enabled at this stage, your program should not attempt to link to any program coded in VS COBOL II or C, as it may be invoked before these are initialized.

Important

Your exit program forms part of a critical CICS system activity. If it fails, CICS terminates.

Exit XAKUSER

When invoked

During the activity keypointing process.

Exit-speci®c parameters

UEPAKTYP

Address of a 1-byte ®eld indicating the type of keypoint for which the exit is invoked. The possible values are:

UEPAKPER

Activity keypoint

UEPAKWSD

Warm shutdown keypoint.

Return codes

UERCNORM

Continue processing.

XPI calls

XPI must not be used.

API and SPI calls

The following commands are supported:

ADDRESS CWA

ADDRESS EIB

LINK (but only to local programs; distributed program links may not be used).

RETURN

Chapter 1. Global user exit programs 25

activity keypoint program exit

WRITE JOURNALNAME.

Important

Only the listed EXEC CICS commands are allowed in the XAKUSER exit. The exit should link only to other programs with the same restrictions.

26 CICS TS for OS/390: CICS Customization Guide

 

Basic Mapping Support exits

|

 

 

Basic Mapping Support exits XBMIN and XBMOUT

|

|

The XBMIN exit allows you to intercept a RECEIVE MAP request after BMS has

|

successfully processed the request. The XBMOUT exit allows you to intercept a

|

SEND MAP request after BMS has successfully processed the request; or, if

|

cumulative mapping is in progress, on completion of each page of output.

|

The XBMIN exit is called, if enabled, when all the following are true:

|

v A RECEIVE MAP command has been successfully processed.

|

v The map referenced in the command contains at least one ®eld speci®ed as

|

VALIDN=USEREXIT.

|

v At least one USEREXIT ®eld has been returned in the inbound datastream and

|

has been mapped into the application data structure.

|

Using XBMIN, you can:

|

v Analyze each ®eld de®ned as VALIDN=USEREXIT mapped to the application on

|

this request

|

v Use the mapset name, map name, and ®eld length de®ned in the map, and the

|

actual length of ®eld data returned in the inbound datastream

|

v Modify the data in each ®eld.

|

The XBMOUT exit is called, if enabled, when all the following are true:

|

v A SEND MAP command has been successfully processed.

|

v The map referenced in the command contains at least one ®eld speci®ed as

|

VALIDN=USEREXIT.

|

v At least one USEREXIT ®eld has been generated in the outbound datastream.

|

Using XBMOUT, you can:

|

v Analyze each ®eld de®ned as VALIDN=USEREXIT which has been generated in

|

the outbound datastream

|

v Use the mapset name, map name, and ®eld length de®ned in the map, and the

|

actual length of ®eld data placed in the outbound datastream

|

v Modify the data in each ®eld

|

v Modify the attributes sent with each ®eld.

|

Both exits are passed four exit-speci®c parameters:

|

1. The address of the TCTTE associated with the mapping request

|

2. The address of the system EIB associated with the task issuing the mapping

|

request

|

3. The address of a halfword binary count of the number of elements in the ®eld

|

element table

|

4. The address of the ®eld element table.

Chapter 1. Global user exit programs 27

Basic Mapping Support exits

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

Sample program, DFH$BMXT

CICS supplies a sample program, DFH$BMXT, that shows how mapped input and output data can be modi®ed with reference to the information provided in the ª®eld elementº table. A copybook, DFHXBMDS, is also supplied. This copybook is a DSECT which de®nes the structure of the ®eld element.

Exit XBMIN

When invoked

After BMS has successfully processed an input mapping operation.

Exit-speci®c parameters

UEPBMTCT

Address of the TCTTE associated with the mapping request.

UEPEXECB

Address of the system EIB associated with the task.

UEPBMCNT

Address of the halfword binary number of ª®eld elementsº in the ®eld element table.

UEPBMTAB

Address of the ®eld element table.

Return codes

UERCNORM

Continue processing.

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

Exit XBMOUT

When invoked

After BMS has successfully completed a page of output during an output mapping operation.

Exit-speci®c parameters

UEPBMTCT

Address of the TCTTE associated with the mapping request.

UEPEXECB

Address of the system EIB associated with the task.

UEPBMCNT

Address of the halfword binary number of ª®eld elementsº in the ®eld element table.

UEPBMTAB

Address of the ®eld element table.

Return codes

UERCNORM

Continue processing.

28 CICS TS for OS/390: CICS Customization Guide

Basic Mapping Support exits

|

UERCPURG

|

Task purged during XPI call.

|

XPI calls

|

All can be used.

|

The ®eld element table structure

|

The ®eld element tablecontains one or more elements which provide information

|

about each ª®eld of interestº passed to the exit. A ª®eld of interestº is a ®eld which

|

has been de®ned as VALIDN=USEREXIT in the map source ®le used to create the

|

mapset referenced in the mapping operation.

|

Each ®eld element has the following structure:

|

BMXMAPST

|

is an 8-byte area which contains the name of the mapset associated with this

|

®eld. If terminal or alternate suffixes are used with mapset names in your CICS

|

installation, the mapset name may have a suffix appended to the name

|

speci®ed in the mapping request.

|

BMXMAP

|

is a 7-byte area which contains the name of the map associated with this ®eld.

|

BMXFDFB

|

is a one-byte ®eld copied from the ®eld speci®cation in the map load module. It

|

contains indicators as follows:

|

X©80© CASE=MIXED

|

X©40© Group ®eld entry

|

X©20© Group ®eld descriptor

|

X©10© ATTRB=DET

|

X©08© JUSTIFY=ZERO

|

X©04© JUSTIFY=RIGHT

|

X©02© INITIAL,XINIT, or GINIT speci®ed

|

X©01© Named ®eld (DSECT entry exists)

|

BMXMAPLN

|

is a halfword binary value which contains the ®eld length de®ned in the

|

LENGTH option of the DFHMDF macro.

|

BMXACTLN

|

is a halfword binary value which contains the actual length of the data received

|

or transmitted in this ®eld.

|

BMXDATA

|

is the address of the ®eld data.

|

In the XBMIN exit, BMXDATA points into a work area which BMS has obtained

|

for input mapping purposes. When the exit returns control, this work area is

|

copied to the application data structure associated with this map.

|

In the XBMOUT exit, BMXDATA points into a terminal input/output area (TIOA)

|

in which BMS has generated an output datastream. When the exit returns

Chapter 1. Global user exit programs 29

 

Basic Mapping Support exits

 

|

control, the TIOA is disposed of in accordance with the disposition of the

|

TERMINAL (the default), SET, or PAGING option speci®ed on the SEND MAP

|

request.

|

BMXATTR

 

|

is only relevant in the XBMOUT exit. It is the address of the attributes (if any)

|

which BMS has placed in the output datastream preceding this ®eld.

|

BMXMAPOF

|

is the offset of the ®eld in the map. For example, if a map is de®ned as

|

MYMAP

DFHMDI SIZE=(12,40)

|

and a ®eld in this map is de®ned as

|

FLDA

DFHMDF POS=(5,1)

|

the offset of this ®eld (relative to zero) is 160 in decimal notation. In this

|

example, BMXMAPOF would contain the value X©00A0©.

|

BMXBUF

 

|

is the offset of the ®eld in the device buffer. UsuallyÐthat is, when the map

|

dimensions are the same as the current screensize in use by the deviceÐthis

|

value will be the same as that of BMXMAPOF. However, using the example

|

given in the BMXMAPOF description above, if MYMAP is sent to a device

|

currently using a 24 by 80 screensize, the offset of the ®eld in the device buffer

|

(again relative to zero) is 320 in decimal notation. In this example, BMXBUF

|

would contain the value X©0140©.

|

Programming the XBMIN exit

|

This section contains some considerations speci®c to the XBMIN exit.

|

The actual data length (in BMXACTLN) may be less than the length de®ned in the

|

map (in BMXMAPLN). This could happen, for example, if a terminal operator does

|

not completely ®ll a data entry ®eld. In this case, BMS will have rightor left-justi®ed

|

the data in the ®eld and padded the ®eld with blank or zero characters. This

|

justi®cation and padding occurs before the exit is invoked. Your exit program can,

|

by checking the bit settings in the BMXFDFB ®eld, determine how BMS performed

|

justi®cation and padding for the ®eld.

|

The actual data length (in BMXACTLN) may be greater than the length de®ned in

|

the map (in BMXMAPLN). This could happen, for example, if a map contains an

|

unprotected ®eld which is not immediately followed by another ®eld. This allows the

|

terminal operator to enter data past the end of the ®eld. When this occurs, the data

|

®eld is truncated by BMS according to the length de®ned for the ®eld in the map.

|

However, BMXACTLN contains the length of data found in the inbound datastream.

|

When modifying data in the XBMIN exit, the safest method is to use the length

|

provided in BMXMAPLN, but to ensure that any pad characters added by BMS are

|

preserved.

 

|

BMXATTR must be ignored in the XBMIN exit; it always contains binary zeroes.

|

Programming the XBMOUT exit

|

This section contains some considerations speci®c to the XBMOUT exit.

30 CICS TS for OS/390: CICS Customization Guide

 

Basic Mapping Support exits

|

The actual data length (in BMXACTLN) may be less than the length de®ned in the

|

map (in BMXMAPLN). This occurs due to the compression of trailing nulls

|

performed by BMS for each output ®eld.

|

The actual length of data cannot be changed in the exit program. The exit is

|

invoked after the output datastream has been generated; consequently, an attempt

|

to alter the data length could result in an invalid datastream. Therefore, if an

|

XBMOUT exit program modi®es data, it must do so with reference to the length

|

value in BMXACTLN.

|

BMXDATA may contain a null value. This can be caused by a SEND MAP request

|

with the MAPONLY option when the map has ®elds without default data; this causes

|

BMS to send an attribute sequence for the ®eld but no data.

|

BMXATTR may contain a null value. This can be caused by a SEND MAP request

|

with the DATAONLY option, when the application is updating the data in a ®eld and

|

not the attributes.

|

Cumulative mapping operations

|

When an application is performing cumulative mappingÐthat is, issuing a sequence

|

of SEND MAP commands with the ACCUM optionÐBMS builds composite display

|

in which a single page of output might be constructed from multiple SEND MAP

|

requests. When cumulative mapping occurs, the XBMOUT exit is called when a

|

page has been built, not as each SEND MAP request is processed.

|

Message routing

|

When an application builds a routing messageÐfor example, it issues a ROUTE

|

command followed by one or more SEND MAP commands with the SET or

|

PAGING option speci®edÐthe XBMOUT exit is invoked in the same way as for a

|

non-routed mapping request.

|

However, the UEPBMTCT parameter is passed as a null value for a routed

|

message. This is because a routed message may be destined for multiple devices,

|

and BMS has optimized the features supported by the devices targeted by the

|

routed message. When processing a routed message in the XBMOUT exit,

|

referencing the TCTTE for any of these devices would probably not be relevant.

Chapter 1. Global user exit programs 31

Bridge facility exit

Bridge facility exit

When enabled, XFAINTU (Facility Initialization and Tidy Up) is called: v Just after a new bridge facility has been built.

v Just before a bridge facility is deleted. This may be at the end of a task (when zero keep time is speci®ed), or when a keep time expires before the facility is re-used.

Exit XFAINTU

When invoked

 

Just after a bridge facility is created and just before it is freed.

 

Exit-speci®c parameters

 

UEPFAREQ

 

Address of a 1-byte ®eld that indicates why the exit has been

 

called. Possible values are:

 

UEPFAIN

 

Initialization.

 

UEPFATU

 

Tidy-up.

 

UEPFATUT

 

Address of a 1-byte ®eld that indicates the type of tidy-up required.

 

Possible values are:

 

UEPFANTU

 

Normal tidy-up.

 

UEPFAETU

 

Expired tidy-up.

 

UEPFANAM

 

Address of the bridge facility name.

 

UEPFATYP

 

Address of a 1-byte ®eld that indicates the facility type. The value is

 

always:

 

UEPFABR

 

3270 bridge facility.

 

UEPFAUAA

 

Address of the bridge facility user area (TCTUA).

 

UEPFAUAL

 

Address of a one-byte ®eld containing the length of the bridge

 

facility user area.

 

Return codes

 

UERCNORM

 

Continue processing.

 

XPI calls

|

All can be used, except those that use Recovery Manager services.

 

API calls

|

All can be used except those that invoke task-related user exits, or use

|

Recovery Manager services.

32 CICS TS for OS/390: CICS Customization Guide

data tables program exits

 

Data tables management exits XDTRD, XDTAD, and XDTLC

|

These exits apply to both:

 

v CICS shared data tables

|

v CICS coupling facility data tables.

 

XDTRD and XDTAD allow you to control the selection of records for inclusion in a

 

data table, XDTRD being used to make such selections during loading, and XDTAD

 

being invoked when records are subsequently added to a loaded data table (or to a

 

CFDT that did not require loading). XDTRD also allows the contents of records that

|

are included in a user-maintained table, or a coupling facility data table, to be

|

modi®ed before they are added.

 

For CICS shared data tables, XDTLC enables you to take action based on the fact

 

that a data table has completed loading, which might be to end some restrictions

 

that you have decided to place on access to the data table during loading, or to

 

cater for an unsuccessful completion of the loading.

|

For a coupling facility data table, XDTLC allows your global user exit program to

|

decide whether to accept an unsuccessfully loaded coupling facility data table. If the

|

user exit program decides to accept the table, it remains open and available for

|

access, but CICS does not mark it as loading completed. This is also the default

|

action if no XDTLC exit is enabled. This means that application programs continue

|

to receive the LOADING condition for any records that are beyond the key range of

|

records successfully loaded into the table. This ensures that application programs

|

are aware that not all the expected data is available. It also allows you to retry the

|

load, when the cause of the failure has been corrected, by closing the ®le that

|

initiated the load and reopening it. Alternatively, you could open another

|

load-capable ®le that refers to the same data table. If your exit program decides to

|

reject the table, it is closed and the records already loaded remain in the table. If

|

the cause of the failure is corrected, a subsequent open for the data table allows

|

the load to complete. XDTLC is not invoked for a coupling facility data table that is

|

not loaded from a source data set.

 

Note that a program invoked from any of these exit points must declare a DSECT

 

de®ning the data tables user exit parameter list pointed to by ®eld UEPDTPL.

 

(Although UEPDTPL is de®ned by a DFHUEXIT call, the parameter list that it

 

addresses is not.) To do this, your program can include the copybook DFHXDTDS,

 

which de®nes the DT_UE_PLIST DSECT.

 

If any tables specify OPENTIME=STARTUP or are opened implicitly, you should

 

provide a program list table post-initialization (PLTPI) program to activate the user

 

exits. Otherwise, the data table may start loading before the exits can be enabled.

 

For more details about PLTPI programs, see ªChapter 4. Writing initialization and

 

shutdown programsº on page 393.

 

Note: For additional information about using these exits with CICS shared data

 

table support, see the CICS Shared Data Tables Guide.

Exit XDTRD

The XDTRD user exit is invoked just before CICS attempts to add to the data table a record that has been retrieved from the source data set.

Chapter 1. Global user exit programs 33

data tables program exits

 

This normally occurs when the loading process retrieves a record during the

 

sequential copying of the source data set. However, it can also occur when an

 

application retrieves a record that is not in the data table and:

 

v For a user-maintained data table, loading is still in progress, or

 

v For a CICS-maintained data table, loading terminated before the end of the

 

source data set was reached (because, for example, the data table was full).

|

Note: For a coupling facility data table the XDTRD exit is invoked only for a table

|

that is loaded from a source data set.

|

The record retrieved from the source data set is passed as a parameter to the user

 

exit programÐsee ®elds UEPDTRA and UEPDTRL. Your exit program can choose

 

(depending, for example, on the key valueÐsee ®elds UEPDTKA and UEPDTKL)

 

whether to include the record in the data table or not.

 

Alternatively, the exit program can request that all subsequent records up to a

 

speci®ed key are skippedÐsee ®eld UEPDTSKA; these records are not passed to

 

the exit program. This facility is available only during loading. You can specify the

 

key as a complete key, or you can specify just the leading characters by padding

 

the skip-key area with binary zeros.

 

For a user-maintained data table, the program can also modify the data in the

 

record to reduce the storage needed for the data table. Application programs that

 

use the data table must be aware of any changes made to the record format by the

 

exit program. If the record length is changed, the exit program must set the new

 

length in the parameter listÐsee ®eld UEPDTRL. The new length must not exceed

 

the data buffer lengthÐsee ®eld UEPDTRBL.

 

When invoked

 

Just before CICS tries to add to the data table a record that has been

 

retrieved from the source data set.

 

Exit-speci®c parameters

 

UEPDTPL

 

Address of the data table user exit parameter list, which is mapped

 

by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table

 

user exit parameter list contains:

 

UEPDTNAM

 

The 8-character data table name.

 

UEPDTFLG

 

A 1-byte ¯ag ®eld. The possible bit settings are:

 

UEPDTSDT (X©80©)

 

The exit has been invoked by CICS shared data

 

table support.

 

UEPDTCMT (X©40©)

 

This is a CICS-maintained table. Only meaningful if

 

UEPDTSDT is on.

 

UEPDTOPT (X©20©)

 

The exit has been invoked for table loading. This

 

means that optimization by skipping can be

 

requested.

34 CICS TS for OS/390: CICS Customization Guide

 

data tables program exits

|

UEPDTCFT(X©10©)

|

The exit has been invoked by coupling facility data

|

table support.

|

UEPDTUMT (X©08©)

|

This is a user-maintained table. Only meaningful if

|

UEPDTSDT is on.

 

UEPDTRA

 

The address of the data record.

 

UEPDTRBL

 

The fullword length of the data table buffer.

 

UEPDTRL

 

The fullword length of the data record.

 

For user-maintained tables, the exit program can set a new

 

length in this ®eld, if it amends the record.

 

UEPDTKA

 

The address of the data table key.

 

UEPDTKL

 

The fullword length of the data table key.

 

UEPDTDSL

 

The fullword length of the name of the source data set.

 

Only meaningful if either UEPDTSDT or UEPDTCFT is on.

 

UEPDTDSN

 

A 44-character ®eld containing the name of the source data

 

set. Only meaningful if either UEPDTSDT or UEPDTCFT is

 

on.

 

UEPDTSKA

 

The address of a skip-key area. When invoked for table

 

loading, your exit program can return a key of length

 

UEPDTKL in this area, and request load optimization by

 

setting a return code of UERCDTOP. Only meaningful if

 

either UEPDTSDT or UEPDTCFT is on.

 

Return codes

 

UERCDTAC

 

Add the record to the data table.

 

UERCDTRJ

 

Reject the record: that is, do not add it to the table.

 

UERCDTOP

 

Skip this and the following records until a key is found that is equal

 

to or greater than the key speci®ed in the skip-key area. Only

 

meaningful if either UEPDTSDT or UEPDTCFT is on.

 

XPI calls

 

All can be used.

Chapter 1. Global user exit programs 35

 

data tables program exits

 

Exit XDTAD

 

The XDTAD user exit is invoked when a write request is issued to a data table.

|

v For a user-maintained data table and coupling facility data table, the user exit is

 

invoked onceÐbefore the record is added to the data table.

vFor a CICS-maintained data table, the user exit is invoked twiceÐbefore the record is added to the source data set and then again before the record is added to the data table.

The record written by the application is passed as a parameter to the user exit programÐsee ®elds UEPDTRA and UEPDTRL. Your exit program can choose (depending on the key value, for exampleÐsee ®elds UEPDTKA and UEPDTKL) whether to include the record in the data table or not. This decision is indicated by setting the return code.

The XDTAD exit must not modify the data in the record. If you used XDTRD to truncate the data records when the data table was loaded, you must code your application so that it only tries to write records of the correct format for the data table.

 

A sample XDTAD exit program is listed in the CICS Shared Data Tables Guide.

 

When invoked

 

One or more times during the processing of a write request to a data table.

 

Exit-speci®c parameters

 

UEPDTPL

 

Address of the data table user exit parameter list, which is mapped

 

by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table

 

user exit parameter list contains:

 

UEPDTNAM

 

The 8-character data table name.

 

UEPDTFLG

 

A 1-byte ¯ag ®eld. The possible bit settings are:

 

UEPDTSDT (X©80©)

 

The exit has been invoked by CICS shared data

 

table support.

 

UEPDTCMT (X©40©)

 

This is a CICS-maintained table. Only meaningful if

 

UEPDTSDT is on.

|

UEPDTCFT(X©10©)

|

The exit has been invoked by coupling facility data

|

table support.

|

UEPDTUMT (X©08©)

|

This is a user-maintained table. Only meaningful if

|

UEPDTSDT is on.

 

UEPDTRA

 

The address of the data record.

 

UEPDTRBL

 

The fullword length of the data table buffer.

36 CICS TS for OS/390: CICS Customization Guide

data tables program exits

UEPDTRL

The fullword length of the data record.

UEPDTKA

The address of the data table key.

UEPDTKL

The fullword length of the data table key.

UEPDTDSL

The fullword length of the name of the source data set.

Only meaningful if either UEPDTSDT or UEPDTCFT is on.

UEPDTDSN

A 44-character ®eld containing the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on.

Return codes

UERCDTAC

Add the record to the data table.

UERCDTRJ

Reject the record: that is, do not add it to the table.

 

XPI calls

 

All can be used.

 

Exit XDTLC

 

The XDTLC user exit is invoked at the completion of data table loadingÐwhether

 

successful or not. The user exit is not invoked if the data table is closed for

|

any reason before loading is complete. The XDTLC exit is invoked for a coupling

|

facility data table only if the table is loaded from a source data set.

 

The exit program is informed if the loading did not complete successfullyÐsee ®eld

 

UEPDTORC. This could occur, for example, if the maximum number of records was

 

reached or there was insufficient virtual storage. In this case, the exit program can

 

request that the ®le is closed immediately, by setting the return code.

 

When invoked

 

At the completion of table loading. It is not invoked if the loading process

 

was terminated because the data table had been closed.

 

Exit-speci®c parameters

 

UEPDTPL

 

Address of the data table user exit parameter list, which is mapped

 

by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table

 

user exit parameter list contains:

 

UEPDTNAM

 

The 8-character data table name.

 

UEPDTFLG

 

A 1-byte ¯ag ®eld. The possible bit settings are:

 

UEPDTSDT (X©80©)

 

The exit has been invoked by CICS shared data

 

table support.

Chapter 1. Global user exit programs 37

 

data tables program exits

 

UEPDTCMT (X©40©)

 

This is a CICS-maintained table. Only meaningful if

 

UEPDTSDT is on.

|

UEPDTCFT(X©10©)

|

The exit has been invoked by coupling facility data

|

table support.

|

UEPDTUMT (X©08©)

|

This is a user-maintained table. Only meaningful if

|

UEPDTSDT is on.

 

UEPDTORC

 

Data table open result code. The possible values are:

 

UEPDTLCS

 

Load successful

 

UEPDTLFL

 

Load unsuccessful.

 

UEPDTDSL

 

The fullword length of the name of the source data set.

 

Only meaningful if either UEPDTSDT or UEPDTCFT is on.

 

UEPDTDSN

 

A 44-character ®eld containing the name of the source data

 

set. Only meaningful if either UEPDTSDT or UEPDTCFT is

 

on.

 

Return codes

 

UERCDTOK

 

Accept the data table in its present state

 

UERCDTCL

 

Close the data table.

 

XPI calls

 

All can be used.

38 CICS TS for OS/390: CICS Customization Guide

DBCTL interface control program exit

DBCTL interface control program exit XXDFA

When invoked

By an active CICS when its connection to DBCTL fails. Your exit program is invoked after the active CICS has informed the alternate CICS of the failure.

Exit-speci®c parameters

UEPDBXR

Address of CICS XRF information for use with DBCTL. The CICS

XRF information can be mapped using the DSECT DFHDXUEP.

Return codes

UERCNOAC

Take no action.

UERCSWCH

Switch to the alternate DBCTL.

UERCABNO

Abend CICS without a dump.

UERCABDU

Abend CICS with a dump.

XPI calls

TRANSACTION_DUMP must not be used.

Chapter 1. Global user exit programs 39

DBCTL tracking program exits

DBCTL tracking program exits XXDFB and XXDTO

Exit XXDFB

When invoked

By the alternate CICS when it receives a message from the active CICS indicating that connection to DBCTL has failed. The alternate and active CICS systems are running in different MVS images, perhaps in different central processing complexes (CPCs). More information about these exits is provided in the CICS IMS Database Control Guide.

Exit-speci®c parameters

UEPDBXR

Address of CICS XRF information for use with DBCTL. The CICS

XRF information can be mapped using the DSECT DFHDXUEP.

Return codes

UERCNOAC

Take no action.

UERCSWCH

Switch to the alternate DBCTL.

UERCABNO

Abend CICS without a dump.

UERCABDU

Abend CICS with a dump.

The return code `UERCNORM' is not available for use at this exit point.

XPI calls

The following must not be used:

INQUIRE_MONITORING_DATA

MONITOR

TRANSACTION_DUMP

WRITE_JOURNAL_DATA.

40 CICS TS for OS/390: CICS Customization Guide

DBCTL tracking program exits

Exit XXDTO

When invoked

By an alternate CICS when it performs takeover under the following conditions:

vThe active and alternate CICS systems are in different MVS images, perhaps in different processors.

vThe active CICS was connected to, or trying to connect to, a DBCTL subsystem. (This does not include disconnecting from one DBCTL and reconnecting to another.)

vThe takeover was not initiated by the XXDFB exit, or the takeover was initiated by XXDFB but the active system reestablished a DBCTL connection before takeover occurred and XXDTO was driven for a new DBCTL takeover decision.

Exit-speci®c parameters

UEPDBXR

Address of CICS XRF information for use with DBCTL. The CICS

XRF information can be mapped using the DSECT DFHDXUEP.

Return codes

UERCNOAC

Take no action.

UERCSWCH

Switch to the alternate DBCTL.

UERCABNO

Abend CICS without a dump.

UERCABDU

Abend CICS with a dump.

The return code UERCNORM is not available for use at this exit point.

XPI calls

The following must not be used:

INQUIRE_MONITORING_DATA

MONITOR

TRANSACTION_DUMP

WRITE_JOURNAL_DATA.

Chapter 1. Global user exit programs 41

dispatcher domain exits

Dispatcher domain exits XDSBWT and XDSAWT

The XDSBWT and XDSAWT exit points are located before and after the operating system wait. CICS services cannot be used in any exit program invoked from these exit points.

The XDSBWT and XDSAWT exits can be used to control the swapping state of the CICS address-space. It should be noted, however, that if the default state of the address-space is non-swappable then these exits cannot be used to override this state.

CICS uses a counter which is incremented for every SYSEVENT DONTSWAP request and decremented for every SYSEVENT OKSWAP request down to a minimum of 0. A SYSEVENT DONTSWAP request is issued when this counter goes up from 0 to 1. A SYSEVENT OKSWAP request is issued when this counter goes down from 1 to 0. In all other circumstances, the SYSEVENT is not issued.

Exit XDSBWT

When invoked

Before an operating system wait issued by the quasireentrant CICS TCB.

Exit-speci®c parameters

None.

Return codes

UERCNORM

Continue processing.

UERCSWAP

Issue SYSEVENT to allow address-space swapping.

XPI calls

Must not be used.

Exit XDSAWT

When invoked

After an operating system wait issued by the quasireentrant CICS TCB.

Exit-speci®c parameters

UEPSYSRC

Address of the 4-byte return code from the SYSEVENT request made before the operating system wait. This return code will be in one of two different forms:

1.The SYSEVENT OKSWAP return code, or

2.If the SYSEVENT request was rejected by CICS, a special CICS return code which will take one of the following fullword decimal values:

17 The SYSEVENT OKSWAP was not issued. The outstanding count of SYSEVENT OKSWAP requests exceeds the count of SYSEVENT DONTSWAP requests. Before a SYSEVENT OKSWAP can be issued, a SYSEVENT DONTSWAP must be requested.

19 The SYSEVENT OKSWAP was not issued. The outstanding count of SYSEVENT DONTSWAP requests

42 CICS TS for OS/390: CICS Customization Guide

dispatcher domain exits

still exceeds the count of SYSEVENT OKSWAPs. Further SYSEVENT OKSWAPs must be requested before a SYSEVENT OKSWAP is issued by CICS.

Return codes

UERCNORM

Continue processing.

UERCNOSW

Issue SYSEVENT to suppress address-space swapping.

XPI calls

Must not be used.

Chapter 1. Global user exit programs 43

DL/I interface program exits

DL/I interface program exits XDLIPRE and XDLIPOST

The XDLIPRE and XDLIPOST exit points are invoked following the issue of an EXEC DLI command or DL/I call. Exit XDLIPRE is invoked before the request is processed and XDLIPOST is invoked after the request is processed.

When the request is function shipped, the exits are invoked from both the application-owning region and the database-owning region. However, there are restrictions when they are invoked in a database-owning region, as described below.

The CICS IMS Database Control Guide contains a sample program for the

XDLIPRE exit.

Notes:

1.The descriptions of the exits that follow show the general format of the application's parameter list. For detailed information about the format of the CALL-level DL/I parameter list, refer to the IMS/ESA Application Programming: DL/I Calls manual.

2.For all EXEC DLI calls, the application's parameter list is in assembler-language format (that is, the value of the program language byte pointed to by UEPLANG is always UEPASM, and the parameter list pointed to by UEPAPLIST is always in assembler-language format). This is because all EXEC DLI calls are converted into assembler-language CALL-level requests.

3.In an XDLIPRE exit program you can change the PSB name and the SYSID name. This helps availability if the originally speci®ed SYSID fails.

You can change the SYSID from:

vA remote value to another remote value

vThe local value to a remote value

vA remote value to the local value.

Changing the SYSID has an effect only if the associated PSB has a PDIR entry. The SYSID may be the local CICS (that is, the SYSIDNT speci®ed on the CICS region) or a remote connection name. For the new SYSID to be used, the PSB name must have a PDIR entry; if it does not have a PDIR entry, the assumption is made that the local CICS is connected to DBCTL, and an attempt is made to run the IMS™ request there. An IMS schedule failure is handled in the same

way as a failure to route to a connection that does not exist. If the SYSID is changed to either the same value as the SYSIDNT of the local CICS or blanks (hex '40404040'), CICS attempts to run the IMS request on the local system.

44 CICS TS for OS/390: CICS Customization Guide

DL/I interface program exits

Exit XDLIPRE

When invoked

On entry to the DL/I interface program.

Exit-speci®c parameters

UEPCTYPE

Address of type-of-request byte. Values are:

UEPCEXEC

The original request was an EXEC DLI request.

UEPCCALL

The original request was a CALL-level request.

UEPCSHIP

The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below.

UEPAPLIST

Address of application's parameter list. The general format for

COBOL and assembler language is:

plist address --> parm1 address

--> parm1

parm2 address --

> parm2

parm3 address --

> parm3

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

 

up to a maximum of 18 parameters excluding the optional parmcount.

The general format for PL/I is:

plist address

--> parm1 address --> parm1 (parmcount)

parm2

address --

> locator descriptor --

>

parm2

parm3

address --

> locator descriptor --

>

parm3

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

 

 

 

up to

a maximum

of 18 parameters

 

 

When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list. For UEPCSHIP requests, your exit program cannot change any of the parameters. Furthermore, for UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in

the above format, but which contains only the ®rst two parameters,parm1 and parm2.

Note: For PL/I applications, parm1 may or may not contain a parameter-count. Your exit program should check this ®eld before using it.

UEPLANG

Address of program language byte. Values are:

UEPPLI

PL/I

UEPCBL

COBOL

UEPASM

Assembler language.

For UEPCSHIP requests, the language is always assembler.

Chapter 1. Global user exit programs 45

DL/I interface program exits

UEPIOAX

Address of I/O area existence ¯ag byte:

UEPIOA1

I/O area exists.

For UEPCSHIP requests, the I/O area existence ¯ag is always off.

UEPIOA

Address of I/O area. This is the application's IOAREA, or DFHEDP's IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit: the new contents are used when the DL/I request is processed. However, it should be noted that IOAREAs can be in a program's static storage and, in this case, should not be overwritten.

For UEPCSHIP requests, UEPIOA is always zero.

UEPPSBNX

Address of PSB existence ¯ag byte:

UEPPSB1

A PSB exists.

UEPPSBNM

Address of an area containing the 8-character PSB name. The contents of the area can be overwritten by the exit, for all types of request including UEPCSHIP; the new contents are used when the DL/I request is processed.

UEPSYSDX

Address of the SYSID existence ¯ag byte:

UEPSYS1

A SYSID exists.

UEPSYSID

Address of an area containing the 4-character SYSID name. The contents of the area can be overwritten by the exit, for all types of request including UEPCSHIP; the new contents are used when the DL/I request is processed.

Return codes

UERCNORM

Continue processing

UERCBYP

Bypass DL/I request and return

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

46 CICS TS for OS/390: CICS Customization Guide

DL/I interface program exits

Exit XDLIPOST

When invoked

On exit from the DL/I interface program.

Exit-speci®c parameters

UEPCTYPE

Address of type-of-request byte. Values are:

UEPCEXEC

An EXEC DLI request.

UEPCCALL

A CALL-level request.

UEPCSHIP

The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below.

UEPAPLIST

Address of application's parameter list. The general format for

COBOL and assembler language is:

plist address --> parm1 address

--> parm1

parm2 address --

> parm2

parm3 address --

> parm3

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

 

up to a maximum of 18 parameters excluding the optional parmcount.

 

The

general

format for PL/I is:

plist address

--> parm1 address

--> parm1 (parmcount)

parm2

address --

> locator descriptor --

> parm2

parm3

address --

> locator descriptor --

> parm3

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

 

 

 

up to

a maximum

of 18 parameters.

 

When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list. For UEPCSHIP requests, your exit program cannot change any of the parameters. Furthermore, for

UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in the above format, but which contains only the ®rst two parametersparm1 and parm2. See also the notes on page 44.

Note: For PL/I applications, parm1 may or may not contain a parameter-count. Your exit program should check this ®eld before using it.

UEPLANG

Address of program language byte. Its values are:

UEPPLI

PL/I

UEPCBL

COBOL

UEPASM

Assembler language.

For UEPCSHIP requests, the language is always assembler.

Chapter 1. Global user exit programs 47

DL/I interface program exits

UEPIOAX

Address of I/O area existence ¯ag byte:

UEPIOA1

I/O area exists.

For UEPCSHIP requests, the I/O area existence ¯ag is always off.

UEPIOA

Address of I/O area. This is the application's IOAREA, or DFHEDP's IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit and are returned to the application program in the new form. However, it should be noted that the application's IOAREA could be in the program's static storage and, in this case, should not be overwritten.

For UEPCSHIP requests, UEPIOA is always zero.

UEPUIBX

Address of UIB existence ¯ag byte:

UEPUIB1

a UIB exists.

UEPUIB

Address of the UIB, which is mapped by DFHUIB in module DFHDBCOP. The contents of the UIB can be overwritten in the exit for all types of request, including UEPCSHIP. The new contents are returned to the application or to the region that function shipped the request.

Return codes

UERCNORM

Continue processing.

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

48 CICS TS for OS/390: CICS Customization Guide

dump domain exits

Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT

There are four exits in the dump domain.

Exit XDUREQ

When invoked

Immediately before a system or transaction dump is taken.

Exit-speci®c parameters

UEPTRANID

Address of the 4-byte transaction ID.

UEPUSER

Address of the 8-byte user ID.

UEPTERM

Address of the 4-byte terminal ID.

UEPPROG

Address of the 8-byte application program name, or nulls if there is no current application.

UEPDUMPC

Address of copy of the 8-byte dump code.

UEPABCDE

Address of a copy of the 8-byte Kernel error code in the format xxx/yyyy. xxx denotes the 3-digit hexadecimal MVS completion code (for example 0C1 or D37). If an MVS completion code is not applicable, xxx is three hyphens. The 4-digit code yyyy is a user abend code produced either by CICS or by another product on your system. UEPABCDE is completed only for abend codes corresponding to the following dump codes:

AP0001

SR0001

ASRA

ASRB

ASRD

Otherwise this ®eld contains null characters.

UEPDUMPT

Address of the 1-byte dump-type identi®er, which contains one of the following values:

UEPDTRAN

A transaction dump was requested.

UEPDSYST

A system dump was requested.

Note: The dump-type identi®er indicates the type of dump request that was passed to the dump domain. It does not re¯ect any modi®cation that may have been made to the original request by a user entry in the dump table.

Chapter 1. Global user exit programs 49

dump domain exits

UEPXDSCP

Address of a 1-byte ®eld indicating the current dump table

DUMPSCOPE setting. It contains one of the following values:

UEPXDLOC

A system dump will be taken on the local MVS image only.

UEPXDREL

System dumps will be taken on both the local MVS image, and on related MVS images within the sysplex.

This ®eld may be modi®ed by the exit to update the dump table

DUMPSCOPE setting.

UEPXDTXN

Address of a 1-byte ®eld indicating the current dump table

TRANDUMP setting. It contains one of the following values:

UEPXDYES

A transaction dump will be taken.

UEPXDNO

A transaction dump will not be taken.

This ®eld may be modi®ed by the exit to update the dump table

TRANDUMP setting.

Note: This ®eld is only valid if UEPDUMPT contains the value

UEPDTRAN.

UEPXDSYS

Address of a 1-byte ®eld indicating the current dump table

SYSDUMP setting. It contains one of the following values:

UEPXDYES

A system dump will be taken.

UEPXDNO

A system dump will not be taken.

This ®eld may be modi®ed by the exit to update the dump table

SYSDUMP setting.

UEPXDTRM

Address of a 1-byte ®eld indicating the current dump table

SHUTDOWN setting. It contains one of the following values:

UEPXDYES

The CICS system is to shutdown.

UEPXDNO

The CICS system is not to shutdown.

This ®eld may be modi®ed by the exit to update the dump table

SHUTDOWN setting.

UEPXDMAX

Address of a 4-byte ®eld which contains the current dump table MAXIMUM setting. This ®eld may be modi®ed by the exit to change the current dump table MAXIMUM setting. A change to the

50 CICS TS for OS/390: CICS Customization Guide

dump domain exits

MAXIMUM setting will not suppress this dump request. A return code of UERCBYP may be used to suppress the current dump request.

UEPDXDCNT

Address of a 4-byte ®eld which contains the current dump table CURRENT setting.

UEPXDTST

Address of a 16-byte ®eld which contains the current dump table statistics for this dump code. The addressed ®eld consists of four 4-byte ®elds containing binary integers:

Number of transaction dumps taken

Number of transaction dumps suppressed

Number of system dumps taken

Number of system dumps suppressed

Note: Statistics for transaction dumps are valid only if UEPDUMPT contains the value UEPDTRAN.

UEPXDDAE

Address of a 1-byte ®eld which represents the current dump table DAEOPTION setting. It contains one of the following values:

UEPXDYES

The dump is eligible for DAE suppression.

UEPXDNO

The dump will not be suppressed by DAE.

This ®eld may be modi®ed by the exit to update the dump table DAEOPTION setting.

UEPDMPID

Address of a 9-character ®eld in the format xxxx/xxxx, containing the dump identi®er. The dump ID is the same as that output by the corresponding dump message.

UEPFMOD

Address of an 8-byte area containing, if the dump code is AP0001, the name of the failing module; otherwise null characters.

Note that ®eld UEPPROG always addresses the name of the current application, regardless of where the failure occurred. UEPFMOD addresses the name of the module where the failure occurred, if known.

If the dump code is AP0001, there are three possibilities:

1.The ®eld addressed by UEPFMOD contains the same name as the ®eld addressed by UEPPROGÐthe failure occured in application code.

2.The ®eld addressed by UEPFMOD contains a different name from the ®eld addressed by UEPPROGÐthe failure occurred in non-application code.

3.The ®eld addressed by UEPFMOD contains ©????????©Ðthe failure was not in application code, but CICS was unable to determine the name of the failing module.

Chapter 1. Global user exit programs 51

dump domain exits

Return codes

UERCNORM

Continue processing.

UERCBYP

Suppress dump.

UERCPURG

Task purged during XPI call.

XPI calls

WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls.

The sample program for the XDUREQ exit, DFH$XDRQ

CICS supplies a sample program for the XDUREQ exit. The sample shows you how to manipulate the dump table entry, and how to permit or suppress the dump.

Exit XDUREQC

When invoked

Immediately after a system or transaction dump has been taken (or has failed or been suppressed).

Exit-speci®c parameters

UEPTRANID

Address of the 4-byte transaction ID.

UEPUSER

Address of the 8-byte user ID.

UEPTERM

Address of the 4-byte terminal ID.

UEPPROG

Address of the 8-byte application program name.

UEPDUMPC

Address of copy of the 8-byte dump code.

UEPABCDE

Address of a copy of the 8-byte Kernel error code in the format xxx/yyyy. xxx denotes the 3-digit hexadecimal MVS completion code (for example X©0C1© or X©D37©). If an MVS completion code is not applicable, xxx is three hyphens. The 4-digit code yyyy is a user abend code produced either by CICS or by another product on your system. UEPABCDE is completed only for abend codes corresponding to the following dump codes:

AP0001

SR0001

ASRA

ASRB

ASRD

Otherwise this ®eld contains null characters.

52 CICS TS for OS/390: CICS Customization Guide

dump domain exits

UEPDUMPT

Address of the 1-byte dump-type identi®er, which contains one of the following values:

UEPDTRAN

A transaction dump was requested.

UEPDSYST

A system dump was requested.

Note: The dump-type identi®er indicates the type of dump request that was passed to the dump domain. It does not re¯ect any modi®cation that may have been made to the original request by a user entry in the dump table.

UEPXDSCP

Address of a 1-byte ®eld indicating the current dump table DUMPSCOPE setting. It contains one of the following values:

UEPXDLOC

A system dump will be taken on the local MVS image only.

UEPXDREL

System dumps will be taken on both the local MVS image, and on related MVS images within the sysplex.

This ®eld may be modi®ed by the exit to update the dump table DUMPSCOPE setting.

UEPXDTXN

Address of a 1-byte ®eld indicating the current dump table TRANDUMP setting. It contains one of the following values:

UEPXDYES

A transaction dump will be taken.

UEPXDNO

A transaction dump will not be taken.

This ®eld may be modi®ed by the exit to update the dump table TRANDUMP setting.

Note: This ®eld is only valid if UEPDUMPT contains the value UEPDTRAN.

UEPXDSYS

Address of a 1-byte ®eld indicating the current dump table SYSDUMP setting. It contains one of the following values:

UEPXDYES

A system dump will be taken.

UEPXDNO

A system dump will not be taken.

This ®eld may be modi®ed by the exit to update the dump table SYSDUMP setting.

UEPXDTRM

Address of a 1-byte ®eld indicating the current dump table SHUTDOWN setting. It contains one of the following values:

Chapter 1. Global user exit programs 53

dump domain exits

UEPXDYES

The CICS system is to shutdown.

UEPXDNO

The CICS system is not to shutdown.

This ®eld may be modi®ed by the exit to update the dump table

SHUTDOWN setting.

UEPXDMAX

Address of a 4-byte ®eld which contains the current dump table MAXIMUM setting. This ®eld may be modi®ed by the exit to change the current dump table MAXIMUM setting.

UEPDXDCNT

Address of a 4-byte ®eld which contains the current dump table

CURRENT setting.

UEPXDTST

Address of a 16-byte ®eld which contains the current dump table statistics for this dumpcode. The addressed ®eld consists of four 4-byte ®elds containing binary integers:

Number of transaction dumps taken

Number of transaction dumps suppressed

Number of system dumps taken

Number of system dumps suppressed.

Note: Statistics for transactions dumps are valid only if

UEPDUMPT contains the value UEPDTRAN.

UEPXDDAE

Address of a 1-byte ®eld which represents the current dump table

DAEOPTION setting. It contains one of the following values:

UEPXDYES

The dump was suppressed by DAE.

UEPXDNO

The dump was not suppressed by DAE.

This ®eld may be modi®ed by the exit to update the dump table

DAEOPTION setting.

UEPDMPID

Address of a 9-character ®eld in the format xxxx/xxxx, containing the dump identi®er. The dump ID is the same as that output by the corresponding dump message.

UEPDRESP

Address of the 2-byte dump response code.

UEPDREAS

Address of the 2-byte dump reason code.

Return codes

UERCNORM

Continue processing.

54 CICS TS for OS/390: CICS Customization Guide

dump domain exits

XPI calls

WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls.

Exit XDUCLSE

When invoked

Immediately after a transaction dump data set has been closed.

Exit-speci®c parameters

UEPTRANID

Address of the 4-byte transaction ID.

UEPUSER

Address of the 8-byte user ID.

UEPTERM

Address of the 4-byte terminal ID.

UEPPROG

Address of the 8-byte application program name.

UEPDMPDD

Address of the 8-byte dump data set ddname.

UEPDMPDSN

Address of the 44-byte dump data set dsname.

Return codes

UERCNORM

Continue processing.

UERCSWCH

The autoswitch ¯ag is set on.

XPI calls

WAIT_MVS can be used. Do not use any other calls.

Exit XDUOUT

When invoked

Before a record is written to the transaction dump data set.

Exit-speci®c parameters

UEPTRANID

Address of the 4-byte transaction ID.

UEPUSER

Address of the 8-byte user ID.

UEPTERM

Address of the 4-byte terminal ID.

UEPPROG

Address of the 8-byte application program name.

UEPDMPFC

Address of the 1-byte function code. The equated values are:

UEPDMPWR

Buffer is about to be written.

Chapter 1. Global user exit programs 55

dump domain exits

UEPDMPRE

Dump is about to restart after autoswitch.

UEPDMPAB

Abnormal termination of dump.

UEPDMPDY

Buffer is about to be written, and the CICS dump data set is a dummy ®le or is closed.

UEPDMPBF

Address of the dump buffer, whose length is addressed by the parameter UEPDMPLEN.

UEPDMPLEN

Address of the 2-byte dump-buffer length.

Return codes

UERCNORM

Continue processing.

UERCBYP

Suppress dump record output.

XPI calls

WAIT_MVS can be used. Do not use any other calls.

56 CICS TS for OS/390: CICS Customization Guide

enqueue EXEC interface program exits

Enqueue EXEC interface program exits XNQEREQ and XNQEREQC

The XNQEREQ exit allows you to intercept enqueue API requests before any action has been taken on the request. The XNQEREQC exit allows you to intercept the response after an enqueue API request has completed.

The API requests affected are: v EXEC CICS ENQ

v EXEC CICS DEQ.

Using XNQEREQ, you can:

v Analyze the API parameter list (function, keywords, argument values, and responses).

v Modify any input parameter value prior to execution of a request.

v Prevent execution of a request. This enables you to replace the CICS function with your own processing.

Using XNQEREQC, you can analyze the API parameter list.

You can also:

v Pass data between your XNQEREQ and XNQEREQC exit programs when they

 

are invoked for the same request

 

v Pass data between your enqueue exit programs when they are invoked within

 

the same task.

 

Exit XNQEREQ

 

When invoked

|

Before CICS processes an EXEC CICS ENQ or DEQ request, or attempts

|

to match it to an installed ENQMODEL resource de®nition.

 

Exit-speci®c parameters

 

UEPCLPS

 

Address of a copy of the command parameter list. See ªThe

 

command-level parameter structureº on page 59.

 

UEPNQTOK

 

Address of a 4-byte area which can be used to pass information

 

between XNQEREQ and XNQEREQC for a single enqueue

 

request.

 

UEPRCODE

 

Address of a 6-byte hexadecimal copy of the EIB return code

 

EIBRCODE. For details of EIB return codes, see the CICS

 

Application Programming Reference manual.

 

UEPRESP

 

Address of a 4-byte binary copy of the EIB response code

 

EIBRESP.

 

UEPRESP2

 

Address of a 4-byte binary copy of the EIB response code

 

EIBRESP2.

 

UEPTSTOK

 

Address of a 4-byte token which can be used to pass information

Chapter 1. Global user exit programs 57

enqueue EXEC interface program exits

 

between successive enqueue requests within the same task (for

 

example, between successive invocations of the XNQEREQ exit).

 

UEPRECUR

 

Address of a halfword recursion counter. The counter is set to 0

 

when the exit is ®rst invoked, and is incremented for each recursive

 

call.

|

UEPSCOPE

|

Address of the 4-byte ENQSCOPE name to be used.

 

Return codes

 

UERCBYP

 

Bypass this request.

 

UERCNORM

 

Continue processing.

 

UERCPURG

 

Task purged during XPI call.

 

XPI calls

 

All can be used.

 

API and SPI commands

 

All can be used.

 

Note: Take care when issuing recursive commands. For example, you must avoid

 

entering a loop when issuing an enqueue request from the XNQEREQ exit.

 

Use of the recursion counter UEPRECUR is recommended.

Exit XNQEREQC

When invoked

After an enqueue API request has completed, before return from the enqueue EXEC interface program.

Exit-speci®c parameters

UEPCLPS

Address of a copy of the command parameter list. See ªThe command-level parameter structureº on page 59.

UEPNQTOK

Address of a 4-byte area which can be used to pass information between XNQEREQ and XNQEREQC for a single enqueue request.

UEPRCODE

Address of a 6-byte hexadecimal copy of the EIB return code

EIBRCODE. For details of EIB return codes, see the CICS

Application Programming Reference manual.

UEPRESP

Address of a 4-byte binary copy of the EIB response code

EIBRESP.

UEPRESP2

Address of a 4-byte binary copy of the EIB response code

EIBRESP2.

58 CICS TS for OS/390: CICS Customization Guide

enqueue EXEC interface program exits

UEPTSTOK

 

Address of a 4-byte token which can be used to pass information

 

between successive enqueue requests within the same task (for

 

example, between successive invocations of the XNQEREQC exit).

 

UEPRECUR

 

Address of a halfword recursion counter. The counter is set to 0

 

when the exit is ®rst invoked, and is incremented for each recursive

 

call.

|

UEPSCOPE

|

Address of the 4-byte ENQSCOPE name used.

 

Return codes

 

UERCNORM

 

Continue processing.

 

UERCPURG

 

Task purged during XPI call.

 

XPI calls

 

All can be used.

 

API and SPI commands

 

All can be used.

 

You can update the copies of EIBRCODE, EIBRESP, and EIBRESP2 that you are

 

given in the parameter list. If you update the values, CICS copies the new values

 

into the application program's EIB after the completion of XNQEREQC or if you

 

specify a return code of UERCBYP in XNQEREQ.

 

You must set valid enqueue responses. You must set all three of EIBRCODE,

 

EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by

 

the enqueue domain to describe a valid completion. CICS does not check the

 

consistency of EIBRCODE, EIBRESP, and EIBRESP2. If EIBRCODE is set to a

 

non-zero value and EIBRESP is set to zero, CICS will override EIBRESP with a

 

non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2,

 

the values used by the enqueue domain are speci®ed in DSECT DFHNQUED.

 

Note: Take care when issuing recursive commands not to cause a loop. For

 

example, it is your responsibility to avoid entering a loop when issuing an

 

enqueue request from the XNQEREQC exit. Use of the recursion counter

 

UEPRECUR is recommended.

The command-level parameter structure

The command-level parameter structure consists of a series of addresses. The ®rst address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identi®es each keyword speci®ed with the request. The remaining addresses point to pieces of data associated with the request.

You can examine the EID to determine the type of request and the keywords speci®ed. You can examine the other parameters in the list to determine the values of the keywords. You can also modify values of keywords speci®ed on the request.

Chapter 1. Global user exit programs 59

enqueue EXEC interface program exits

End of parameter list indicator

The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to ®nd the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.

The UEPCLPS exit-speci®c parameter

The UEPCLPS exit-speci®c parameter is included in both exit XNQEREQ and exit XNQEREQC. It is the address of the command-level parameter structure. The command-level parameter structure contains four addresses, NQ_ADDR0 through NQ_ADDR3. It is de®ned in the DSECT NQ_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHNQUED.

The command-level parameter list is made up as follows.

Note: The relationship between arguments, keywords, data types, and input/output types is summarized for the enqueue commands in Table 3 on page 62.

NQ_ADDR0

is the address of a 9-byte area called the EID, which is made up as follows:

NQ_GROUP

NQ_FUNCT

NQ_BITS1

NQ_BITS2

NQ_EIDOPT5

NQ_EIDOPT6

NQ_EIDOPT7

NQ_EIDOPT8

NQ_GROUP

Always X©12©, indicating that this is a task control request.

NQ_FUNCT

One byte that de®nes the type of request:

X©04© ENQ

X©06© DEQ

NQ_BITS1

Existence bits that de®ne which arguments were speci®ed. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the argument was not speci®ed in the request and the address should not be used.

X©80© Set if the request contains an argument for the RESOURCE keyword. If set, NQ_ADDR1 is meaningful.

X©40© Set if the request contains an argument for the LENGTH keyword. If set, NQ_ADDR2 is meaningful.

60 CICS TS for OS/390: CICS Customization Guide

enqueue EXEC interface program exits

X©20© Set if the request contains an argument for the MAXLIFETIME keyword. If set, NQ_ADDR3 is meaningful.

NQ_BITS2

Two bytes not used by the enqueue domain.

NQ_EIDOPT5

One byte not used by the enqueue domain.

NQ_EIDOPT6

One byte not used by the enqueue domain.

NQ_EIDOPT7

One byte not used by the enqueue domain.

NQ_EIDOPT8

Indicates whether certain keywords were speci®ed on the request.

X©04© NOSUSPEND was speci®ed.

X©02© DEQ was speci®ed.

X©01© ENQ was speci®ed.

NQ_ADDR1

is the address of an area containing the value from RESOURCE.

NQ_ADDR2

is the address of the halfword value of LENGTH.

NQ_ADDR3

is the address of the fullword value of MAXLIFETIME.

Modifying ®elds in the command-level parameter structure

The ®elds that are passed to the enqueue domain are used as input to the request. The correct method of modifying an input ®eld is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data.

Notes:

1.You must never modify an input ®eld by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the ®eld.

2.There are no output ®elds on EXEC CICS ENQ and DEQ requests.

Modifying the EID

It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change an ENQ request to a DEQ request. However, you can make minor changes to requests, such as to turn on the existence bit for LENGTH. The list that follows shows the bits in the EID that can be modi®ed. Any attempt to modify any other part of the EID is ignored.

NQ_BITS1

X©40© The existence bit for LENGTH

X©20© The existence bit for MAXLIFETIME.

NQ_EIDOPT7

A user exit program at XNQEREQ can set the following on or off for ENQ commands:

Chapter 1. Global user exit programs 61

enqueue EXEC interface program exits

X©04© The existence bit for NOSUSPEND.

The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the enqueue request only.

Note: Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modi®cations that are permitted.

Use of the task token UEPTSTOK

UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive enqueue requests in the same task. (By contrast, UEPNQTOK is usable only for the duration of a single enqueue request, because its contents may be destroyed at the end of the request.) For example, if you need to pass information between successive invocations of the XNQEREQ exit, UEPTSTOK provides a means of doing this.

Table 3. User arguments and associated keywords, data types, and input/output types

Argument

Keyword

Data type

Input/output type

 

 

 

 

Arg1

RESOURCE

DATA-AREA

input

 

 

 

 

Arg2

LENGTH

BIN(15)

input

 

 

 

 

Arg3

MAXLIFETIME

CVDA

input

 

 

 

 

Modifying user arguments

User exit programs can modify user input arguments by:

1.Obtaining sufficient storage to hold the modi®ed argument

2.Setting the storage to the required value

3.Setting the associated pointer in the parameter list to the address of the newly-acquired area.

Notes:

1.CICS does not check changes to argument values, so any changes must be veri®ed by the user exit program making the changes.

2.It is not advisable for XNQEREQC to modify input arguments.

Adding user arguments

Global user exit programs can add arguments associated with the LENGTH and MAXLIFETIME keywords. You must ensure that the arguments you specify or modify in your exit programs are valid. The valid values for MAXLIFETIME are DFHVALUE(TASK) and DFHVALUE(UOW), which are 233 and 246 respectively.

Assuming that the argument to be added does not already exist, the user exit program must:

1.Obtain storage for the argument to be added

2.Initialize the storage to the required value

3.Select and set up the appropriate pointer from the parameter list

4.Select and set up the appropriate argument existence bit in the EID

5.Modify the parameter list to re¯ect the new end of list indicator.

62 CICS TS for OS/390: CICS Customization Guide

enqueue EXEC interface program exits

 

Removing user arguments

 

User exit programs can remove arguments (for which the program is totally

 

responsible) associated with the LENGTH and MAXLIFETIME keywords:

 

Assuming that the argument to be removed exists, the user exit program must:

 

1. Switch the corresponding argument existence bit to '0'b in the EID

 

2. Modify the parameter list to re¯ect the new end of list indicator.

 

Sample exit program, DFH$XNQE

|

CICS supplies a sample exit program, DFH$XNQE, for the XNQEREQ exit.

|

The program gives examples of:

 

v Coding Exec Interface Global User Exits

 

v Issuing a mixture of XPI and EXEC CICS API calls within Global User Exits

 

v Three methods of adding a SCOPE value to exec ENQ and DEQ requests, so

 

that they apply to multiple regions within the Sysplex. Methods A and B force a

 

match to an installed ENQMODEL resource de®nition. Method C bypasses the

 

use of ENQMODEL resource de®nitions even if there would have been a match.

 

The methods are:

 

Method A

 

Pre®x the Resource name with a 1- to 255-character value (this sample

 

uses a 4-character value) for the ENQNAME on the ENQMODEL

 

resource de®nition to which you wish to force a match. The exit

 

terminates and processing continues as though the chosen ENQMODEL

 

had been matched normally. The scope is then supplied by the matched

 

ENQMODEL de®nition.

 

This method applies only to resource names shorter than 255-n (where n

 

is the length of you chosen pre®x).

Method B

Similar to method A, but you replace the ®rst 1- to 8-characters of the resource name with your chosen string instead of pre®xing it. This method:

±applies only to resource names of length equal to or greater than that of your replacement string.

±is an alternative to method A when a resource name too long to allow the use of that method.

Method C

Place a 4-character Scope value in UEPSCOPE, and return UERCSCPE in R15. This will bypass any installed ENQMODEL resource de®nition, forcing a Sysplex Scope ENQ/DEQ request.

This method is not recommended if you have an ENQMODEL table, because the latter is designed to preserve data integrity by preventing the possibility of a region scope enqueue and a sysplex scope enqueue (or two sysplex scope enqueues with different scopes) existing for the same resource. (Because sysplex and region scope enqueues use separate namespaces, a region scope enqueue will never wait on a sysplex enqueue, nor will a sysplex scope enqueue wait on a region enqueue.)

Chapter 1. Global user exit programs 63

 

enqueue EXEC interface program exits

|

Notes about the use of XNQEREQ to alter ENQ or DEQ scope.

|

1. XNQEREQ enables you to allow existing applications to be converted to use

|

sysplex enqueues without changing the application.

|

Note: Use of either the ENQMODEL resource de®nition or the user exit allows

|

this in most cases, but those applications where the resource name is

|

determined dynamically and not known in advance can only be so

|

converted by use of this exit.

|

2. Sysplex and region scope enqueues use separate namespaces. A region scope

|

enqueue will never wait on a sysplex enqueue, nor will a sysplex scope

|

enqueue wait on a region enqueue.

|

Note: This situation can only arise when you use the exit. Use of the

|

ENQMODEL resource de®nitions as your only method of de®ning the

|

SCOPE of an ENQ or DEQ avoids this potential risk.

|

3. Both region and sysplex scope are supported for string ENQs, but sysplex

|

scope is not supported for address ENQs.

64 CICS TS for OS/390: CICS Customization Guide

EXEC interface program exits

EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT

There are four global user exit points in the EXEC interface program:

XEIIN Invoked before the execution of any EXEC CICS application programming interface (API) or system programming interface (SPI) command.

XEISPIN

Invoked before the execution of any EXEC CICS SPI command except:

vEXEC CICS ENABLE

vEXEC CICS DISABLE

vEXEC CICS EXTRACT EXIT.

The sequence is:

TRACE ± XEIIN ± XEISPIN ± EDF ± command

XEIOUT

Invoked after the execution of any EXEC CICS API or SPI command.

XEISPOUT

Invoked after the execution of any EXEC CICS SPI command except those listed for XEISPIN.

The sequence is:

command ± EDF ± XEISPOUT ± XEIOUT ± TRACE

Note: Asynchronous processing of these exits may occur if the transaction is suspended (for example, during ®le I/O wait). This situation may also occur under CEDF because CEDF issues its own EXEC CICS commands between the application's XEISPIN and XEISPOUT exits.

If, for example, the same GWA is shared between the XEIIN and XEIOUT exits, you must allow for the possibility of asynchronous processing, in order to ensure integrity of the data and to prevent unpredictable results.

On entry to the exits, the exit-speci®c parameter UEPARG contains the address of the command parameter list.

The command parameter list

The ®rst parameter in the list points to a string of data known asargument 0. The other parameters point to the values speci®ed for the parameters passed on the command.

Argument 0 begins with a 2-byte function code that identi®es the command. (Function codes are documented in Appendix A of the CICS Application Programming Reference manual and in Appendix B of the CICS System Programming Reference manual.) The function code is followed by a 2-byte ®eld containing ªexistence bitsº which indicate whether arguments are passed on the command. For example, consider the command:

EXEC CICS LINK PROGRAM(‘MYPROG’)

Here, argument 0 begins with the function code X©0E02© (LINK). Existence bit 1 is set, indicating that there is an argument 1 (namely, `MYPROG').

Chapter 1. Global user exit programs 65

EXEC interface program exits

The correspondence between command parameters (such as PROGRAM) and their positions and values in the parameter list (in this case, argument 1, `MYPROG') can be deduced from the translated code for the particular command.

Important

Modifying CICS commands by tampering with argument 0 is not supported, and leads to unexpected errors or results.

For example, if an application program is written in assembler or PL/I and you modify argument 0, you will be writing to program storage (that is, storage occupied by the program itself), which could cause 0C4 abends. Furthermore, modifying argument 0 not only alters the CICS command for this execution of the command in the application program, it changes the CICS command in the virtual storage copy of the application program. This means that the next task to invoke the same copy of the program will also execute the modi®ed command.

This particular example of the danger of tampering with argument 0 does not apply to COBOL or C/370™ application programs, but nevertheless you should not modify CICS commands for application programs written in any supported language.

Bypassing commands

An XEIIN or XEISPIN exit program can bypass execution of a command by setting the UERCBYP return code. If it does this, EDF is not invoked, but XEISPOUT, XEIOUT, and exit trace are invoked if they are active.

Bypassing an EXEC CICS command allows an exit program to replace the CICS function with its own processing, for example.

Before setting UERCBYP, your program should check the value pointed to by UEPPGM, to ensure that it is not bypassing an EXEC CICS command issued by CICS.

Exit XEIIN

When invoked

Before the execution of any EXEC CICS API or SPI command.

Exit-speci®c parameters

UEPARG

Address of the EXEC command parameter list.

UEPEXECB

Address of the system EIB.

UEPUSID

Address of the 8-character userid.

UEPPGM

Address of the 8-character application program name.

UEPLOAD

Address of the application program's load-point.

66 CICS TS for OS/390: CICS Customization Guide

EXEC interface program exits

UEPRSA

Address of the application's register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.

Return codes

UERCNORM

Continue processing.

UERCBYP

Bypass the execution of this command.

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

Exit XEISPIN

When invoked

Before the execution of any EXEC CICS SPI command except:

vEXEC CICS ENABLE

vEXEC CICS DISABLE

vEXEC CICS EXTRACT EXIT.

Exit-speci®c parameters

UEPARG

Address of the EXEC command parameter list.

UEPEXECB

Address of the system EIB.

UEPUSID

Address of the 8-character userid.

UEPPGM

Address of the 8-character application program name.

UEPLOAD

Address of the application program's load-point.

UEPRSA

Address of the application's register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.

Return codes

UERCNORM

Continue processing.

UERCBYP

Bypass the execution of this command.

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

Chapter 1. Global user exit programs 67

EXEC interface program exits

Exit XEIOUT

When invoked

After the execution of any EXEC CICS API or SPI command.

Exit-speci®c parameters

UEPARG

Address of the EXEC command parameter list.

UEPEXECB

Address of the system EIB.

UEPUSID

Address of the 8-character userid.

UEPPGM

Address of the 8-character application program name.

UEPLOAD

Address of the application program's load-point.

UEPRSA

Address of the application's register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.

Return codes

UERCNORM

Continue processing.

UERCPURG

Task purged during XPI call.

XPI calls

All can be used.

Exit XEISPOUT

When invoked

After the execution of any EXEC CICS SPI command except:

vEXEC CICS ENABLE

vEXEC CICS DISABLE

vEXEC CICS EXTRACT EXIT.

Exit-speci®c parameters

UEPARG

Address of the EXEC command parameter list.

UEPEXECB

Address of the system EIB.

UEPUSID

Address of the 8-character userid.

UEPPGM

Address of the 8-character application program name.

UEPLOAD

Address of the application program's load-point.

68 CICS TS for OS/390: CICS Customization Guide