IBM SC33-1683-02 User Manual

3.35 Mb
Loading...

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

+ 825 hidden pages