IBM SC34-6814-04 User Manual

CICS Transaction Server for z/OS

Customization Guide

Version 3 Release 2

SC34-6814-04

CICS Transaction Server for z/OS

Customization Guide

Version 3 Release 2

SC34-6814-04

Note!

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

This edition applies to Version 3 Release 2 of CICS Transaction Server for z/OS, program number 5655-M15, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 1977, 2011.

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

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . .	. .	.	xvii
What this book is about . . . . . . . . . . . . . . . . . .	. .	.	xvii
Who this book is for . . . . . . . . . . . . . . . . . . . .	. .	.	xvii
What you need to know to understand this book . . . . . . . . .	. .	.	xvii
How to use this book . . . . . . . . . . . . . . . . . . .	. .	.	xvii

Notes on terminology . . . . . . . . . . . . . . . . . . . . . . xvii Syntax notation and conventions used in this book . . . . . . . . . . . xviii

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xix Changes for CICS Transaction Server for z/OS, Version 3 Release 2 . . . . . xix Changes for CICS Transaction Server for z/OS, Version 3 Release 1 . . . . . xix Changes for CICS Transaction Server for z/OS, Version 2 Release 3 . . . . . xx

Part 1. Customizing with user exit programs . . . . . . . . . . . . . .	. . . . 1
Chapter 1. Global user exit programs . . . . . . . . . . . .	.	. .	.	3
Writing global user exit programs . . . . . . . . . . . . . .	.	. .	.	3
Register conventions . . . . . . . . . . . . . . . . . .	.	. .	.	3
31-bit addressing implications . . . . . . . . . . . . . . . . . . . 4
Using CICS services . . . . . . . . . . . . . . . . . .	.	. .	.	4
Using channels and containers . . . . . . . . . . . . . .	.	. .	.	5
Assembler programs and LEASM . . . . . . . . . . . . .	.	. .	.	6
EDF and global user exits . . . . . . . . . . . . . . . .	.	. .	.	6
The global work area . . . . . . . . . . . . . . . . . .	.	. .	.	6
Making trace entries . . . . . . . . . . . . . . . . . . . . . . 6
Parameters passed to the global user exit program . . . . . . .	.	. .	.	7
Returning values to CICS . . . . . . . . . . . . . . . .	.	. .	.	10
Restrictions on the use of fields as programming interfaces . . .	.	. .	.	11
Exit programs and the CICS storage protection facility . . . . .	.	. .	.	11
Errors in user exit programs . . . . . . . . . . . . . . .	.	. .	.	12
Defining, enabling, and disabling an exit program . . . . . . . .	.	. .	.	12
Viewing active global user exits . . . . . . . . . . . . . . .	.	. .	.	13
Invoking more than one exit program at a single exit . . . . . . .	.	. .	.	13
Invoking a single exit program at more than one exit . . . . . . .	.	. .	.	14
Making programs threadsafe . . . . . . . . . . . . . . . . . . . . 14
Sample global user exit programs . . . . . . . . . . . . . .	.	. .	.	15
Basic sample and example programs . . . . . . . . . . .	.	. .	.	15
Sample programs for specific exits . . . . . . . . . . . .	.	. .	.	18
Alphabetical list of global user exit points . . . . . . . . . . .	.	. .	.	25
Global user exit points by functional area . . . . . . . . . . .	.	. .	.	32
Activity keypoint program exit XAKUSER . . . . . . . . . .	.	. .	.	32
Application Associated Data exit, XAPADMGR, in the AP domain .	.	. .	.	33
Basic Mapping Support exits XBMIN and XBMOUT . . . . . .	.	. .	. 34
Bridge facility exit XFAINTU . . . . . . . . . . . . . . .	.	. .	.	38
Data tables management exits XDTRD, XDTAD, and XDTLC . . . . . . . 40
DBCTL interface control program exit XXDFA . . . . . . . .	.	. .	.	45
DBCTL tracking program exits XXDFB and XXDTO . . . . . .	.	. .	. 46
Dispatcher domain exits XDSBWT and XDSAWT . . . . . . .	.	. .	. 47
DL/I interface program exits XDLIPRE and XDLIPOST . . . . .	.	. .	.	48

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

Enqueue EXEC interface program exits XNQEREQ and XNQEREQC. . . .		60
EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT		67
File control domain exits, XFCFRIN and XFCFROUT . . . . . . . . .	.	72

© Copyright IBM Corp. 1977, 2011

iii

File control EXEC interface API exits XFCREQ and XFCREQC . . . . . . 85 File control EXEC interface SPI exits XFCAREQ and XFCAREQC . . . . . 98

File control file state program exits XFCSREQ and XFCSREQC . . . .	. 111
File control open/close program exit XFCNREC . . . . . . . . . .	.	121
File control quiesce receive exit, XFCVSDS . . . . . . . . . . . .	.	122
File control quiesce send exit XFCQUIS . . . . . . . . . . . . .	.	124
File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and
XFCLDEL . . . . . . . . . . . . . . . . . . . . . . .	.	126
Front End Programming Interface exits XSZARQ and XSZBRQ . . . .	. 137
Good morning message program exit XGMTEXT . . . . . . . . . .	. 138
HTTP client open and send exits: XWBAUTH, XWBOPEN and XWBSNDO		138

Intersystem communication program exits XISCONA and XISLCLQ . . . . 138 Interval control program exits XICREQ, XICEXP, and XICTENF . . . . . 143 Interval control EXEC interface program exits XICEREQ, XICERES, and

XICEREQC . . . . . . . . . . . . . . . . . . . . . . . . 145

Loader domain exits XLDLOAD and XLDELETE . . . . . . . . . .	. 162
Log manager domain exit XLGSTRM . . . . . . . . . . . . . .	.	164
Message domain exit XMEOUT . . . . . . . . . . . . . . . .	.	168
Monitoring domain exit XMNOUT. . . . . . . . . . . . . . . .	.	172

Pipeline domain exits . . . . . . . . . . . . . . . . . . . . . 174

Program control program exits XPCREQ, XPCERES, XPCREQC,
XPCFTCH, XPCHAIR, XPCTA, and XPCABND. . . . . . . .	.	.	. 175
Resource manager interface program exits XRMIIN and XRMIOUT .	.	.	. 193
Resource management install and discard exit XRSINDI . . . . .	.	.	.	195
Signon and signoff exits XSNON, XSNOFF, and XSNEX . . . . .	.	.	. 199
Statistics domain exit XSTOUT . . . . . . . . . . . . . .	.	.	.	202
System recovery program exit XSRAB . . . . . . . . . . . .	.	.	.	203
System termination program exit XSTERM . . . . . . . . . .	.	.	.	206

Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . . 207

Temporary storage EXEC interface program exits XTSEREQ and
XTSEREQC . . . . . . . . . . . . . . . . . . . .	.	.	.	212
Terminal allocation program exit XALCAID . . . . . . . . . .	.	.	.	221

Terminal control program exits XTCIN, XTCOUT, and XTCATT . . . . . . 223

‘Terminal not known’ condition exits XALTENF and XICTENF . .	. . .	.	224
Transaction manager domain exit XXMATT . . . . . . . . .	. . .	.	232

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

Transient data EXEC interface program exits XTDEREQ and XTDEREQC		236
User log record recovery program exits XRCINIT and XRCINPT . . . .	. 244
VTAM terminal management program exit XZCATT . . . . . . . . .	.	247
VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE		248
XISQUE exit for managing IPIC intersystem queues. . . . . . . . .	.	258
XRF request-processing program exit XXRSTAT . . . . . . . . . .	.	263
Chapter 2. Task-related user exit programs . . . . . . . . . . . .	.	267
Introduction to the task-related user exit mechanism (the adapter) . . . .	.	267

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

Returning control to the application program . . . . . . . . . .	.	.	270
Task-related user exits and EDF . . . . . . . . . . . . . . .	.	.	270
Writing a task-related user exit program . . . . . . . . . . . . .	.	.	271
Obligations of OPENAPI task-related user exits . . . . . . . . .	.	.	271
User exit parameter lists . . . . . . . . . . . . . . . . . .	.	.	273
The schedule flag word . . . . . . . . . . . . . . . . . .	.	.	287
Register handling in the task-related user exit program. . . . . . .	.	.	288
Addressing-mode implications . . . . . . . . . . . . . . . .	.	.	289
Exit programs and the CICS storage protection facility . . . . . . .	.	.	290

iv Customization Guide

Recursion within a task-related user exit program. . . . . .	. .	. .	.	290
Purging tasks . . . . . . . . . . . . . . . . . . .	. .	. .	.	290
Using CICS services in your task-related user exit program . .	. .	. .	.	291
Using channels and containers . . . . . . . . . . . .	. .	. .	.	292
Assembler programs and LEASM . . . . . . . . . . .	. .	. .	.	292
Wait states in your task-related user exit program . . . . .	. .	. .	.	292

Work areas . . . . . . . . . . . . . . . . . . . . . . . . . 292 Coding a program to be invoked by the CICS SPI . . . . . . . . . . 293 Coding a program to be invoked by the CICS syncpoint manager . . . . . 293 Coding a program to be invoked by the CICS task manager . . . . . . . 297

Coding a program to be invoked at CICS termination . . . . . . .	.	.	298
Using EDF with your task-related user exit program . . . . . . . .	.	.	301
Administering the adapter . . . . . . . . . . . . . . . . . .	.	.	302
What you must do before using the adapter . . . . . . . . . . .	.	.	303
Tracing a task-related user exit program . . . . . . . . . . . .	.	.	304
Chapter 3. The user exit programming interface (XPI) . . . . . . .	.	.	305
Overview of the XPI . . . . . . . . . . . . . . . . . . . .	.	.	305
Making an XPI call . . . . . . . . . . . . . . . . . . . . .	.	.	308
Setting up the XPI environment . . . . . . . . . . . . . . .	.	.	312
XPI register usage . . . . . . . . . . . . . . . . . . . .	.	.	312
The XPI copy books . . . . . . . . . . . . . . . . . . .	.	.	313
Reentrancy considerations resulting from XPI calls . . . . . . . .	.	.	313
Global user exit XPI examples, showing the use of storage . . . . . .	.	.	313
An example showing how to build a parameter list incrementally . . .	.	.	318

XPI syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Directory domain XPI functions	. . . . . . . . . . . . .	. .	.	.	.	321
The BIND_LDAP call . . .	. . . . . . . . . . . . .	. .	.	.	.	321

The END_BROWSE_RESULTS call. . . . . . . . . . . . . . . . 323 The FLUSH_LDAP_CACHE call . . . . . . . . . . . . . . . . . 323 The FREE_SEARCH_RESULTS call . . . . . . . . . . . . . . . 324 The GET_ATTRIBUTE_VALUE call . . . . . . . . . . . . . . . . 325

The GET_NEXT_ATTRIBUTE call . . . . . . . .	. . . . . .	.	.	326
The GET_NEXT_ENTRY call . . . . . . . . . .	. . . . . .	.	.	327
The SEARCH_LDAP call. . . . . . . . . . . .	. . . . . .	.	.	328

The START_BROWSE_RESULTS call . . . . . . . . . . . . . . . 329 The UNBIND_LDAP call . . . . . . . . . . . . . . . . . . . . 330 Dispatcher XPI functions . . . . . . . . . . . . . . . . . . . . . 331

Synchronization protocols for SUSPEND and RESUME processing . .	.	. 331
The ADD_SUSPEND call . . . . . . . . . . . . . . . . .	.	.	334
The SUSPEND call . . . . . . . . . . . . . . . . . . . .	.	.	335
The RESUME call . . . . . . . . . . . . . . . . . . . .	.	.	339
The DELETE_SUSPEND call . . . . . . . . . . . . . . . .	.	.	340
The WAIT_MVS call . . . . . . . . . . . . . . . . . . .	.	.	340

The CHANGE_PRIORITY call . . . . . . . . . . . . . . . . . . 344

Dump control XPI functions .	. . . . . .	. . . . . . . . .	. .	.	.	345
The SYSTEM_DUMP call	. . . . . .	. . . . . . . . .	. .	.	.	345

The TRANSACTION_DUMP call . . . . . . . . . . . . . . . . . 347

Enqueue domain XPI functions	. . . . . . . . .	. . . . . . .	.	.	349
The ENQUEUE function . .	. . . . . . . . .	. . . . . . .	.	.	349

The DEQUEUE function . . . . . . . . . . . . . . . . . . . . 350

Kernel domain XPI functions . . . . . . . . . . . .	. .	. . . .	.	351
The START_PURGE_PROTECTION function . . . . .	. .	. . . .	. 351
The STOP_PURGE_PROTECTION function . . . . .	. .	. . . .	. 351
Nesting purge protection calls . . . . . . . . . . .	. .	. . . .	.	352
Loader XPI functions . . . . . . . . . . . . . . .	. .	. . . .	.	352

Contents v

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

The ACQUIRE_PROGRAM call . . .	. . . . . . . . .	. . . .	. 356
The RELEASE_PROGRAM call . . .	. . . . . . . . .	. . . .	. 358

The DELETE_PROGRAM call . . . . . . . . . . . . . . . . . . 359

Log manager XPI functions . . . . . . . . . . . . . . .	. . . .	.	360
The INQUIRE_PARAMETERS call . . . . . . . . . . .	. . . .	.	360
The SET_PARAMETERS call . . . . . . . . . . . . .	. . . .	.	361
Monitoring XPI functions . . . . . . . . . . . . . . . .	. . . .	.	361
The MONITOR call . . . . . . . . . . . . . . . . .	. . . .	.	362
The INQUIRE_MONITORING_DATA call . . . . . . . . .	. . . .	.	364
Program management XPI functions . . . . . . . . . . .	. . . .	.	366
The INQUIRE_PROGRAM call . . . . . . . . . . . .	. . . .	.	366
The INQUIRE_CURRENT_PROGRAM call . . . . . . . .	. . . .	. 373
The SET_PROGRAM call . . . . . . . . . . . . . .	. . . .	.	375
The START_BROWSE_PROGRAM call . . . . . . . . .	. . . .	. 379

The GET_NEXT_PROGRAM call. . . . . . . . . . . . . . . . . 380

The END_BROWSE_PROGRAM call . . . . . . . . .	. .	. . . . 381
The INQUIRE_AUTOINSTALL call . . . . . . . . . .	. .	. . . . 382
The SET_AUTOINSTALL call . . . . . . . . . . . .	. .	. . . . 382
State data access XPI functions . . . . . . . . . . . .	. .	. . . . 384
The INQ_APPLICATION_DATA call . . . . . . . . . .	. .	. . . . 384
The INQUIRE_SYSTEM call . . . . . . . . . . . .	. .	. . . . 386

The SET_SYSTEM call . . . . . . . . . . . . . . . . . . . . 391

Storage control XPI functions . . . . . . . . . . . . . . . . . .	.	392
The GETMAIN call . . . . . . . . . . . . . . . . . . . . .	.	392
The FREEMAIN call . . . . . . . . . . . . . . . . . . . .	.	395
The INQUIRE_ACCESS call . . . . . . . . . . . . . . . . .	.	395
The INQUIRE_ELEMENT_LENGTH call . . . . . . . . . . . . .	.	396
The INQUIRE_SHORT_ON_STORAGE call . . . . . . . . . . . .	. 397
The INQUIRE_TASK_STORAGE call . . . . . . . . . . . . . .	.	398
The SWITCH_SUBSPACE call . . . . . . . . . . . . . . . .	.	399
Trace control XPI function . . . . . . . . . . . . . . . . . . .	.	399

The TRACE_PUT call . . . . . . . . . . . . . . . . . . . . . 400

Transaction management XPI functions . . . .	. . . . . . . . .	.	.	401
The INQUIRE_CONTEXT call . . . . . . .	. . . . . . . . .	.	.	401

The INQUIRE_DTRTRAN call . . . . . . . . . . . . . . . . . . 403

The INQUIRE_MXT call . . . . . . . .	. . . . . . . . .	. .	.	403
The INQUIRE_TCLASS call. . . . . . .	. . . . . . . . .	. .	.	405

The INQUIRE_TRANDEF call . . . . . . . . . . . . . . . . . . 406

The INQUIRE_TRANSACTION call . . . . . . . . . . . . .					. . . 414
The SET_TRANSACTION call . . . . . . . . . . . . . . .					. . . 418
User journaling XPI function . . . .	. . . .	. . . . .	. .	. .		.	.	419
The WRITE_JOURNAL_DATA call .	. . . .	. . . . .	. .	. .		.	.	419

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

Chapter 4. Writing initialization and shutdown programs. . . . . . . . 425 Writing initialization programs . . . . . . . . . . . . . . . . . . . 425 First-phase PLT programs . . . . . . . . . . . . . . . . . . . 425

Second phase PLT programs . . . . . . . . . . . . . . . . .	.	426
Effect of delayed recovery on PLTPI processing . . . . . . . . . .	.	427
Writing shutdown programs . . . . . . . . . . . . . . . . . . .	.	428
First phase PLT programs . . . . . . . . . . . . . . . . . .	.	428
PLT programs for the second quiesce stage. . . . . . . . . . . .	.	428
The shutdown assist utility program, DFHCESD . . . . . . . . . .	.	429
General considerations when writing initialization and shutdown programs		429

vi Customization Guide

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

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

Chapter 5. General notes about user-replaceable programs . . . . . . 435 Rewriting user-replaceable programs . . . . . . . . . . . . . . . . 435

Assembling and link-editing user-replaceable programs . . . . . .	. .	.	436
User-replaceable programs and the storage protection facility . . . .	. .	.	437
Execution key for user-replaceable programs . . . . . . . . .	. .	.	437
Data storage key for user-replaceable programs . . . . . . . .	. .	.	438
Chapter 6. Writing a program error program . . . . . . . . .	. .	.	439
The sample program error programs . . . . . . . . . . . . .	. .	.	443
Chapter 7. Writing a transaction restart program . . . . . . . .	. .	.	445
The DFHREST communications area . . . . . . . . . . . . .	. .	.	446
The CICS-supplied transaction restart program . . . . . . . . .	. .	.	447
Chapter 8. Writing a terminal error program. . . . . . . . . .	. .	.	449
Background to error handling for sequential devices . . . . . . . .	. .	.	449
When an abnormal condition occurs . . . . . . . . . . . .	. .	.	449

Terminal control program . . . . . . . . . . . . . . . . . . . . 450

Terminal abnormal condition program . . . . . . . .	. . .	.	.	.	.	450
Terminal error program . . . . . . . . . . . . .	. . .	.	.	.	.	450

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

Terminal abnormal condition line entry (TACLE) . . . .	. . .	. . . . 451
The sample terminal error program . . . . . . . . . .	. . .	. . . . 451
Components of the sample terminal error program . . .	. . .	. . . . 451
Structure of the sample terminal error program. . . . .	. . .	. . . . 453
Sample terminal error program messages . . . . . .	. . .	. . . . 456
Generating the sample terminal error program . . . . .	. . .	. . . . 458
Writing your own terminal error program . . . . . . . .	. . .	. . . . 470
Why write your own terminal error program? . . . . .	. . .	. . . . 470
Restrictions on the use of EXEC CICS commands . . .	. . .	. . . . 470
Addressing the contents of the communication area . . .	. . .	. . . . 471
Addressing the contents of the TACLE. . . . . . . .	. . .	. . . . 473
Example of a user-written terminal error program . . . .	. . .	. . . . 475
Chapter 9. Writing a node error program . . . . . . .	. . .	. . . . 479
Background to CICS-VTAM error handling . . . . . . .	. . .	. . . . 480
Why use a NEP to supplement CICS default actions? . .	. . .	. . . . 480
An overview of writing a NEP . . . . . . . . . . .	. . .	. . . . 481
The default NEP . . . . . . . . . . . . . . . .	. . .	. . . . 482

The sample NEP. . . . . . . . . . . . . . . . . . . . . . . 482

Multiple NEPs . . . . . . . . . . . . . . .	. . .	. .	. . . . 485
When an abnormal condition occurs . . . . . . .	. . .	. .	. . . . 486
The communication area . . . . . . . . . . .	. . .	. .	. . . . 487
The sample node error program . . . . . . . . .	. . .	. .	. . . . 496
Compatibility with the sample terminal error program	. . .	. .	. . . . 496
Components of the sample node error program . .	. . .	. .	. . . . 496
Generating the sample node error program . . . .	. . .	. .	. . . . 499
Writing your own node error program . . . . . . .	. . .	. .	. . . . 505
Restrictions on the use of EXEC CICS commands .	. . .	. .	. . . . 505

Entry and addressability . . . . . . . . . . . . . . . . . . . . 506

Coding for the 3270 ‘unavailable printer’ condition	. . .	. . .	.	. .	.	506
Coding for session failures . . . . . . . . .	. . .	. . .	.	. .	.	507

Contents vii

Coding for specific VTAM sense codes . . . . . . . . . . . . . . 508 Writing multiple NEPs . . . . . . . . . . . . . . . . . . . . . 508 DFHZNEPI macros . . . . . . . . . . . . . . . . . . . . . . 508 Handling shutdown hung terminals in the node error program . . . . . . 510 Using the node error program with XRF or persistent sessions . . . . . . . 510

The node error program in an XRF environment . . . . . . . .	.	.	.	510
The node error program with persistent session support . . . . .	.	.	.	511
Changing the recovery notification . . . . . . . . . . . . .	.	.	.	511
Changing the recovery message . . . . . . . . . . . . . .	.	.	.	512
Changing the recovery transaction . . . . . . . . . . . . .	.	.	.	512

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

Chapter 10. Writing a program to control autoinstall of terminals . . . .	515
Autoinstalling terminals—preliminary considerations . . . . . . . . . . .	515
Coding entries in the VTAM LOGON mode table . . . . . . . . . . .	516
Using model terminal support (MTS) . . . . . . . . . . . . . . .	516
The autoinstall control program for terminals . . . . . . . . . . . .	517
The autoinstall control program at INSTALL . . . . . . . . . . . . . .	517
The communication area at INSTALL for terminals . . . . . . . . . .	518
How CICS builds the list of autoinstall models . . . . . . . . . . . .	519
Returning information to CICS . . . . . . . . . . . . . . . . . .	520
CICS action on return from the control program . . . . . . . . . . .	523
The autoinstall control program at DELETE . . . . . . . . . . . . . .	525
The communication area at DELETE for terminals . . . . . . . . . .	525
Naming, testing, and debugging your autoinstall control program . . . . . .	526
Finding the name of an autoinstall control program . . . . . . . . . .	526
Testing and debugging . . . . . . . . . . . . . . . . . . . .	526
The sample autoinstall control programs for terminals . . . . . . . . . .	527
Customizing the sample program. . . . . . . . . . . . . . . . .	528
Chapter 11. Writing a program to control autoinstall of consoles . . . .	535
Autoinstalling consoles—preliminary considerations . . . . . . . . . . .	535
Leaving it all to CICS . . . . . . . . . . . . . . . . . . . . .	535
Using an autoinstall control program . . . . . . . . . . . . . . .	535
The autoinstall control program at INSTALL . . . . . . . . . . . . . .	536
The communication area at INSTALL for consoles . . . . . . . . . .	536
How CICS builds the list of autoinstall models . . . . . . . . . . . .	538
Returning information to CICS . . . . . . . . . . . . . . . . . .	538
CICS action on return from the control program . . . . . . . . . . .	540
The autoinstall control program at DELETE . . . . . . . . . . . . . .	540
The sample autoinstall control programs for consoles . . . . . . . . . .	541
Chapter 12. Writing a program to control autoinstall of APPC connections	543
Autoinstalling APPC connections—preliminary considerations . . . . . . .	543
Local APPC single-session connections initiated by CINIT . . . . . . .	543

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

BIND . . . . . . . . . . . . . . . . . . . . . . . . . . 543 Autoinstall templates for APPC connections . . . . . . . . . . . . . 544 Benefits of autoinstall . . . . . . . . . . . . . . . . . . . . . 544

Requirements for autoinstall . . . . . . . . . . . . . . . . .	.	544
The autoinstall control program for APPC connections . . . . . . . .	.	545
Recovery and restart . . . . . . . . . . . . . . . . . . . .	.	545
The autoinstall control program at INSTALL . . . . . . . . . . . . .	.	545

The communication area at INSTALL for APPC connections . . . . . . . 545 The autoinstall control program at DELETE . . . . . . . . . . . . . . 549 When autoinstalled APPC connections are deleted . . . . . . . . . . 549

viii Customization Guide

The sample autoinstall control program for APPC connections . . . . . . . 550

Default actions of the sample program . . . . . . . . . . . . . .	.	550
Resource definitions . . . . . . . . . . . . . . . . . . . .	.	551
Chapter 13. Writing a program to control autoinstall of IPIC connections		553
Autoinstalling IPIC connections: preliminary considerations . . . . . . .	.	553
The autoinstall user program at INSTALL . . . . . . . . . . . . . .	.	555
The autoinstall user program at DELETE . . . . . . . . . . . . . .	.	556
When autoinstalled IPCONNs are deleted . . . . . . . . . . . .	.	557
The sample autoinstall user program for IPIC connections (IPCONN) . . .	.	557
Default actions of the sample program . . . . . . . . . . . . . .	.	558
Resource definitions . . . . . . . . . . . . . . . . . . . .	.	558
Chapter 14. Writing a program to control autoinstall of shipped terminals		559
Installing shipped terminals and connections . . . . . . . . . . . .	.	559

CICS-generated aliases . . . . . . . . . . . . . . . . . . . . 560

Resetting the terminal identifier . . . . . . . . . .	. . . . .	.	.	560
The autoinstall control program at INSTALL . . . . . . .	. . . . .	.	.	561

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

The autoinstall control program at DELETE . . . . . . . . . . . . .	.	564
Default actions of the sample programs . . . . . . . . . . . . . .	.	565
Chapter 15. Writing a program to control autoinstall of virtual terminals		567
How Client virtual terminals are autoinstalled . . . . . . . . . . . .	.	567

Autoinstall models . . . . . . . . . . . . . . . . . . . . . . 567

Terminal identifiers . . . . . . . . . . . .	. . . . . . . .	.	.	567
Why override TERMIDs? . . . . . . . . . .	. . . . . . . .	.	.	568
How bridge facility virtual terminals are autoinstalled	. . . . . . . .	.	.	570

Using the terminal autoinstall control program for bridge facilities . . . . . 570

Bridge facility name uniqueness . . . . . . . . . . . . . . .	.	.	571
The autoinstall control program at INSTALL . . . . . . . . . . . .	.	.	571
The communications area at INSTALL for Client virtual terminals . . .	.	.	571
The communications area at INSTALL for bridge facility virtual terminals			573
The autoinstall control program at DELETE . . . . . . . . . . . .	.	.	575
The communications area at DELETE for Client virtual terminals . . .	.	.	575
The communications area at DELETE for bridge facility virtual terminals			576
Default actions of the sample programs . . . . . . . . . . . . .	.	.	577
Chapter 16. Writing a program to control autoinstall of programs . .	.	.	579
Autoinstalling programs—preliminary considerations . . . . . . . . .	.	.	579

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

Benefits of autoinstalling programs . . . . . . . . . . . . . . .	.	.	581
Reduced system administration costs . . . . . . . . . . . . .	.	.	581
Saving in virtual storage . . . . . . . . . . . . . . . . . .	.	.	581
Faster startup times . . . . . . . . . . . . . . . . . . .	.	.	582
Requirements for program autoinstall . . . . . . . . . . . . . .	.	.	582
The autoinstall control program at INSTALL . . . . . . . . . . . .	.	.	583
The sample autoinstall control program for programs, DFHPGADX . . .	.	.	586
Customizing the sample program. . . . . . . . . . . . . . .	.	.	586

Resource definition . . . . . . . . . . . . . . . . . . . . . . 587 Testing and debugging your program . . . . . . . . . . . . . . . 588

Chapter 17. Writing a dynamic routing program . . . . . . . . . . . 589

Contents ix

Routing transactions dynamically . . . . . . . . . . . . . . . . . . 590 Dynamic transactions . . . . . . . . . . . . . . . . . . . . . 590

When the dynamic routing program is invoked . . . . . . . .	. . . . 590
Information passed to the dynamic routing program . . . . . .	. . . . 591
Changing the target CICS region . . . . . . . . . . . . .	. . . . 592
Changing the program name . . . . . . . . . . . . . .	. . . . 593
Telling CICS whether to route or terminate a transaction . . . .	. . . . 593
If the system is unavailable or unknown . . . . . . . . . .	. . . . 594

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

Invoking the dynamic routing program on abend . .	. . . . . . .	.	.	594
Modifying the initial terminal data . . . . . . . .	. . . . . . .	.	.	595
Modifying the application’s communications area . .	. . . . . . .	.	.	595
Receiving information from a routed transaction . .	. . . . . . .	.	.	596

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

Unit of work considerations . . . . . . . . . . . .	. . .	. . . . 597
Routing DPL requests dynamically . . . . . . . . . .	. . .	. . . . 597
When the dynamic routing program is invoked . . . . .	. . .	. . . . 598
Changing the target CICS region . . . . . . . . . .	. . .	. . . . 599
Changing the program name . . . . . . . . . . .	. . .	. . . . 599
Changing the transaction ID . . . . . . . . . . .	. . .	. . . . 600
Telling CICS whether to route or terminate a DPL request	. . .	. . . . 600
If an error occurs in route selection . . . . . . . . .	. . .	. . . . 600

Using the XPCERES exit to check the availability of resources on the target region . . . . . . . . . . . . . . . . . . . . . . . . . . 601

Invoking the dynamic routing program at end of routed requests . . .	.	.	602
Modifying the application’s input communications area . . . . . . .	.	.	602
Monitoring the application’s output communications area . . . . . .	.	.	602

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

Unit of work considerations . . . . . . . . . . . . . . . . . .	.	603
Routing bridge requests dynamically . . . . . . . . . . . . . . .	.	603
Changing bridge request parameters . . . . . . . . . . . . . .	.	604
Rejecting a Link3270 bridge request . . . . . . . . . . . . . .	.	605
Handling route selection errors of Link3270 bridge requests . . . . . .	.	605
Using the XPCERES exit to check the availability of resources on the target
region . . . . . . . . . . . . . . . . . . . . . . . . .	.	605
Re-invoking the dynamic routing program after Link3270 bridge requests		606
Link3270 bridge dynamic routing considerations . . . . . . . . . .	.	606
Modifying the application’s containers . . . . . . . . . . . . . . .	.	607
Routing by user ID . . . . . . . . . . . . . . . . . . . . . .	.	607
Parameters passed to the dynamic routing program . . . . . . . . . .	.	607
Naming your dynamic routing program. . . . . . . . . . . . . . .	.	621
Testing your dynamic routing program . . . . . . . . . . . . . . .	.	621
Dynamic transaction routing sample programs . . . . . . . . . . . .	.	622
Chapter 18. Writing a distributed routing program . . . . . . . . .	.	623
Differences between the distributed and dynamic routing interfaces . . . .	.	624

Routing BTS activities . . . . . . . . . . . . . . . . . . . . . . 625

Which BTS activities can be dynamically routed? . . . . . . . . . .	.	625
When the distributed routing program is invoked . . . . . . . . . .	.	626
Changing the target CICS region . . . . . . . . . . . . . . . .	.	627
Telling CICS whether to route the activity . . . . . . . . . . . . .	.	627
If an error occurs in route selection . . . . . . . . . . . . . . .	.	628
Invoking the distributed routing program on the target region . . . . .	.	628
Routing method requests for enterprise beans and CORBA stateless objects		629
Where workload balancing occurs . . . . . . . . . . . . . . .	.	629
Which requests can be dynamically routed?. . . . . . . . . . . .	.	631

x Customization Guide

When the distributed routing program is invoked . . . . .	. . . . .	.	632
Changing the target CICS region . . . . . . . . . . .	. . . . .	.	633
Telling CICS whether to route the method request . . . .	. . . . .	.	634
If an error occurs in route selection . . . . . . . . . .	. . . . .	.	634
Invoking the distributed routing program on the target region	. . . . .	.	634
Dealing with a disabled CorbaServer . . . . . . . . .	. . . . .	.	635
Performing a rolling upgrade of an EJB/CORBA server. . .	. . . . .	.	637
Routing non-terminal-related START requests . . . . . . .	. . . . .	.	637
Which requests can be dynamically routed?. . . . . . .	. . . . .	.	637
When the distributed routing program is invoked . . . . .	. . . . .	.	638
Changing the target CICS region . . . . . . . . . . .	. . . . .	.	639
Telling CICS whether to route the request . . . . . . .	. . . . .	.	639
If an error occurs in route selection . . . . . . . . . .	. . . . .	.	640

Using the XICERES exit to check the availability of resources on the target region . . . . . . . . . . . . . . . . . . . . . . . . . . 640

Invoking the distributed routing program on the target region	. . . . .	.	641
Routing inbound Web service requests . . . . . . . . .	. . . . .	.	641
Which requests can be dynamically routed?. . . . . . .	. . . . .	.	641
When the distributed routing program is invoked . . . . .	. . . . .	.	642
Changing the target CICS region . . . . . . . . . . .	. . . . .	.	643
Telling CICS whether to route the request . . . . . . .	. . . . .	.	643
If an error occurs in route selection . . . . . . . . . .	. . . . .	.	644
Invoking the distributed routing program on the target region	. . . . .	.	644
Routing by user ID . . . . . . . . . . . . . . . . .	. . . . .	.	644
Dealing with an abend on the target region . . . . . . . .	. . . . .	.	644

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

Parameters passed to the distributed routing program . . . . . . .		. .	.	645
Naming your distributed routing program . . . . . . . . . . . .		. .	.	656
Distributed transaction routing sample programs . . . . . . . . .		. .	.	657
Chapter 19.	Writing a CICS–DBCTL interface status program . . .	. .	.	659
The sample CICS–DBCTL interface status program . . . . . . . .		. .	.	660
Chapter 20.	Writing a 3270 bridge exit program . . . . . . . .	. .	.	661
Chapter 21.	Writing a security exit program for IIOP . . . . . .	. .	.	663

The sample programs . . . . . . . . . . . . . . . . . . . . . . 665 DFHXOPUS . . . . . . . . . . . . . . . . . . . . . . . . 665 DFHEBURM . . . . . . . . . . . . . . . . . . . . . . . . 666

Chapter 22. Writing programs to customize JVMs . . . . . . . .	.	.	667
Writing Java classes to redirect JVM stdout and stderr output . . . . .	.	.	667
The com.ibm.cics.server.OutputRedirectionPlugin interface . . . . .	.	.	668
Possible destinations for output . . . . . . . . . . . . . . .	.	.	669
Handling output redirection errors and internal errors . . . . . . .	.	.	669
Using DFHJVMRO to modify the Language Environment enclave for a JVM			670
Using DFHJVMAT to modify options in a JVM profile . . . . . . . .	.	.	671

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

Chapter 23. Writing a distinguished name program for clients of
enterprise beans . . . . . . . . . . . . . . . . . . .	.	.	.	675
Sample programs and copy books . . . . . . . . . . . . . .	.	.	.	677
Chapter 24. Writing an EJB event program . . . . . . . . . .	.	.	.	679
Overview of the EJB event program. . . . . . . . . . . . . .	.	.	.	679
The DFHEJEP communications area . . . . . . . . . . . . .	.	.	.	680

Contents xi

Event codes . . . . . . . . . . . . . . . . . . . . . . . .	.	681
The EJB event sample program . . . . . . . . . . . . . . . . .	.	682
Actions of the default program . . . . . . . . . . . . . . . . .	.	682
Writing your own EJB event program . . . . . . . . . . . . . .	.	682
Chapter 25. Writing programs to customize Language Environment
run-time options for XPLink programs . . . . . . . . . . . . .	.	685
DFHAPXPO . . . . . . . . . . . . . . . . . . . . . . . . . 685
Defining run-time options. . . . . . . . . . . . . . . . . . .	.	685

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

Chapter 26. The extended recovery facility overseer program . . . . .	.	689
The sample XRF overseer program . . . . . . . . . . . . . . . .	.	689
The functions of the sample program . . . . . . . . . . . . . .	.	689
How the sample overseer program interfaces with CICS . . . . . . .	.	693
How to tell the overseer which actives and alternates to monitor . . . .	.	693
The DFHWOSM macros . . . . . . . . . . . . . . . . . . . .	.	695

The DFHWOSM tokens . . . . . . . . . . . . . . . . . . . . 695

DFHWOSM FUNC=BUILD macro . . . . . . . . .	. . . .	. .	. 696
DFHWOSM FUNC=CLOSE macro . . . . . . . . .	. . . .	. .	. 696
DFHWOSM FUNC=DSECT macro . . . . . . . . .	. . . .	. .	. 697
DFHWOSM FUNC=JJC macro . . . . . . . . . .	. . . .	. .	. 697

DFHWOSM FUNC={JJS|QJJS} macro . . . . . . . . . . . . . . . 697 DFHWOSM FUNC=OPEN macro . . . . . . . . . . . . . . . . 698 DFHWOSM FUNC=OSCMD macro . . . . . . . . . . . . . . . . 699 DFHWOSM FUNC=READ macro. . . . . . . . . . . . . . . . . 699

DFHWOSM FUNC=TERM macro . . . . . .	. . . . .	. . .	.	. 703
Customizing the sample XRF overseer program . .	. . . . .	. . .	.	.	703
Loop or wait detection . . . . . . . . . . .	. . . . .	. . .	.	.	705
Assembling and link-editing the overseer program	. . . . .	. . .	.	.	705

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

Chapter 27. CICS logging and journaling . . . . .	. .	. . . . . .	.	709
The CICS log manager . . . . . . . . . . . .	. .	. . . . . .	.	709

Log stream storage . . . . . . . . . . . . . . . . . . . . . . . 709

Enabling, disabling, and reading journals . . . . . . . . . . . . .	.	.	711
Enabling and disabling a journal . . . . . . . . . . . . . . .	.	.	711
Reading journal records offline . . . . . . . . . . . . . . .	.	.	712
Structure and content of CICS Transaction Server for z/OS format journal
records . . . . . . . . . . . . . . . . . . . . . . . .	.	.	712
Format of general log block header . . . . . . . . . . . . . .	.	.	713
Format of general log journal record . . . . . . . . . . . . .	.	.	714

Start-of-run record . . . . . . . . . . . . . . . . . . . . . . 716

Format of caller data . . . . . . . . . . . . . . . . . . .	.	.	716
Structure and content of COMPAT41-format journal records . . . . . .	.	.	729
Format of COMPAT41 journal control label header . . . . . . . .	.	.	729
Format of journal record . . . . . . . . . . . . . . . . . .	.	.	731
Identifying records for the start of tasks and UOWs . . . . . . . .	.	.	737
Format of journal records written to SMF . . . . . . . . . . . . .	.	.	737
The SMF block header . . . . . . . . . . . . . . . . . .	.	.	738
The CICS product section . . . . . . . . . . . . . . . . .	.	.	740
The CICS data section . . . . . . . . . . . . . . . . . .	.	.	742

xii Customization Guide

Chapter 28. CICS monitoring . . . . . . . . . . . . . . . . .	.	743
Introduction to CICS monitoring . . . . . . . . . . . . . . . . .	.	743
How CICS monitoring data is passed to SMF . . . . . . . . . . .	.	743
Coding additional event-monitoring points . . . . . . . . . . . .	.	744
Application naming event monitoring points . . . . . . . . . . . .	.	744
The monitoring control table (MCT) . . . . . . . . . . . . . . .	.	747
CICS monitoring record formats . . . . . . . . . . . . . . . . .	.	750
SMF header and SMF product section . . . . . . . . . . . . . .	.	750
CICS data section . . . . . . . . . . . . . . . . . . . . . . 754
Chapter 29. Writing statistics collection and analysis programs . . . . . 769
Writing a program to collect CICS statistics . . . . . . . . . . . . .	.	769
Background information . . . . . . . . . . . . . . . . . . . . 769
Resetting statistics counters . . . . . . . . . . . . . . . . .	.	770
Using the EXEC CICS COLLECT and EXTRACT STATISTICS commands		770
CICS statistics record format . . . . . . . . . . . . . . . . . .	.	771
SMF header and SMF product section . . . . . . . . . . . . . .	.	771
CICS statistics data section . . . . . . . . . . . . . . . . . .	.	773
Using an XSTOUT global user exit program to filter statistics records . . .	.	776
Processing the output from CICS statistics . . . . . . . . . . . . .	.	777

Part 6. Customizing CICS compatibility interfaces . . . . . . . .		. . . . . . 779
Chapter 30. The dynamic allocation sample program . .	.	. . . .	.	.	781
Overview of the dynamic allocation program . . . . . .	.	. . . .	.	.	781
Installing the program and transaction definitions . . . . .	.	. . . .	.	.	782
The dynamic allocation program—terminal operation . . .	.	. . . .	.	.	782
Using the dynamic allocation program’s Help feature . . .	.	. . . .	.	.	782
The dynamic allocation program—values . . . . . . . .	.	. . . .	.	.	783
Abbreviation rules for keywords . . . . . . . . . .	.	. . . .	.	.	784
System programming considerations . . . . . . . .	.	. . . .	.	.	784
The flow of control when a DYNALLOC request is issued. .	.	. . . .	.	.	784

Part 7. Customizing CICS security processing . . . . . . . . . . . . .	. .	.	787
Chapter 31. Invoking an external security manager . . . . . . .	. .	.	789
An overview of the CICS-ESM interface . . . . . . . . . . . .	. .	.	789
The MVS router . . . . . . . . . . . . . . . . . . . . .	. .	.	789
The MVS router exit . . . . . . . . . . . . . . . . . .	. .	.	789
Using ESM exit programs to access CICS-related information . . . .	. .	.	791
For non-RACF users — the ESM parameter list . . . . . . . .	. .	.	792
For RACF users — the RACF user exit parameter list . . . . . .	. .	.	792
The installation data parameter list . . . . . . . . . . . . .	. .	.	793
CICS security control points. . . . . . . . . . . . . . . . .	. .	.	796
Using early verification processing . . . . . . . . . . . . . .	. .	.	797
Writing an early verification routine . . . . . . . . . . . . .	. .	.	798
Using CICS API commands in an early verification routine . . . .	. .	.	799
Return and reason codes from the early verification routine . . . .	. .	.	799
Chapter 32. Writing a “good night” program . . . . . . . . .	. .	.	801
The communications area of the “good night” program . . . . . . .	. .	.	801
The sample “good night” program, DFH0GNIT . . . . . . . . . .	. .	.	803
What the sample program does . . . . . . . . . . . . . .	. .	.	803
Customizing the sample “good night” program . . . . . . . . . .	. .	.	804

Contents xiii

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

Chapter 33. Using the programmable interface to CEDA . . . . . . .	.	809
When to use the programmable interface. . . . . . . . . . . . . .	.	810
Using DFHEDAP in a DTP environment . . . . . . . . . . . . . .	.	810
Chapter 34. User programs for the system definition utility program
(DFHCSDUP) . . . . . . . . . . . . . . . . . . . . . . .	.	813
An overview of DFHCSDUP . . . . . . . . . . . . . . . . . .	.	813
Invoking a user program from DFHCSDUP . . . . . . . . . . . . .	.	814

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

The EXTRACT command . . . . . . . . . . . . . .	.	. . . . 814
When the user program is invoked . . . . . . . . . . .	.	. . . . 815
Parameters passed from DFHCSDUP to the user program . .	.	. . . . 815
The sample EXTRACT programs. . . . . . . . . . . .	.	. . . . 816
Assembling and link-editing EXTRACT programs . . . . . .	.	. . . . 819
Invoking DFHCSDUP from a user program . . . . . . . . .	.	. . . . 821
Entry parameters for DFHCSDUP . . . . . . . . . . .	.	. . . . 822
Responsibilities of the user program . . . . . . . . . .	.	. . . . 824
The user exit points in DFHCSDUP . . . . . . . . . . . .	.	. . . . 824
Parameters passed to the user exit routines. . . . . . . .	.	. . . . 824
The initialization exit . . . . . . . . . . . . . . . .	.	. . . . 825
The get-command exit. . . . . . . . . . . . . . . .	.	. . . . 825
The extract exit . . . . . . . . . . . . . . . . . .	.	. . . . 826
The put-message exit . . . . . . . . . . . . . . . .	.	. . . . 827
The termination exit. . . . . . . . . . . . . . . . .	.	. . . . 828
The sample program, DFH$CUS1 . . . . . . . . . . . .	.	. . . . 829

Part 9. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831

Appendix A. Coding entries in the VTAM LOGON mode table . . . . . . 833

Overview of the VTAM LOGON mode table . . . . . . . . . . . .	.	.	833
TYPETERM device types and pointers to related LOGON mode data . .	.	. 833
VTAM MODEENT macro operands . . . . . . . . . . . . . . .	.	.	835
PSERVIC screen size values for LUTYPEx devices . . . . . . . . .	.	.	840
Matching models and LOGON mode entries . . . . . . . . . . .	.	.	841
LOGON mode definitions for CICS-supplied autoinstall models . . . . .	.	.	850
Appendix B. Default actions of the node abnormal condition program			855
DFHZNAC—default actions for terminal error codes . . . . . . . . .	.	.	855
CICS messages associated with VTAM errors . . . . . . . . . . .	.	.	861
DFHZNAC—default actions for system sense codes. . . . . . . . .	.	.	866
Action flag settings and meanings . . . . . . . . . . . . . . .	.	.	868
Appendix C. Analyzing CICS restart information . . . . . . . . .	.	.	871

Appendix D. Using the transient data write-to-terminal program

(DFH$TDWT) . . . . . . . . . . . . . . . . . . . . . . . . 873

DFH$TDWT—resource definitions required . . . .	.	. . . . . . .	.	.	873
Appendix E. Uppercase translation . . . . . .	.	. . . . . . .	.	.	875
Translating national characters to uppercase . . .	.	. . . . . . .	.	.	875
Using the XZCIN exit . . . . . . . . . . .	.	. . . . . . .	.	.	875
Using DFHTCTxx . . . . . . . . . . . .	.	. . . . . . .	.	.	875
Translating TS data sharing messages to uppercase	.	. . . . . . .	.	.	876

xiv Customization Guide

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

Appendix G. Threadsafe XPI commands . . . . . . . . . . . . .	.	893
Bibliography . . . . . . . . . . . . . . . . . . . . . . . .	.	895
The CICS Transaction Server for z/OS library . . . . . . . . . . . .	.	895
The entitlement set . . . . . . . . . . . . . . . . . . . . .	.	895
PDF-only books . . . . . . . . . . . . . . . . . . . . . .	.	895
Other CICS books . . . . . . . . . . . . . . . . . . . . . .	.	897
Books from related libraries . . . . . . . . . . . . . . . . . . .	.	897
MVS books . . . . . . . . . . . . . . . . . . . . . . . .	.	897
VTAM books . . . . . . . . . . . . . . . . . . . . . . .	.	898

Other related books. . . . . . . . . . . . . . . . . . . . . . 898 Determining if a publication is current . . . . . . . . . . . . . . . . 898

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . 901

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 923

Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . 925

Contents xv

xvi Customization Guide

Preface

What this book is about

This book provides the information needed to extend and modify an IBM® CICS® Transaction Server for z/OS® system to match your requirements. It describes how you can tailor your system by coding exit programs, by replacing specific 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 this information, you must be familiar with some of the architecture of CICS and the programming interface to CICS. Programming interface information is described in the CICS Application Programming Reference and the CICS System Programming Reference.

Resource definition information is described in the CICS Resource Definition Guide.

To use the following information, you must be familiar with the IBM ACF/VTAM telecommunications access method:

vChapter 9, “Writing a node error program,” on page 479

vChapter 10, “Writing a program to control autoinstall of terminals,” on page 515

vChapter 12, “Writing a program to control autoinstall of APPC connections,” on page 543

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

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 qualification, refers to the CICS element of IBM CICS Transaction Server for z/OS. The term “VTAM” refers to ACF/VTAM. The term “APPC” (advanced program-to-program communication) refers to the LUTYPE6.2 intersystem connection (ISC) protocol.

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

CICS Transaction Server for z/OS, Version 3 Release 2 supports CICS applications written in:

v Assembler language

© Copyright IBM Corp. 1977, 2011

xvii

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.

xviii Customization Guide

Summary of changes

This book is based on the CICS Customization Guide for CICS Transaction Server for z/OS, Version 3 Release 1, SC34-6429-00. Changes from that edition are marked by vertical bars in the left margin.

Changes for CICS Transaction Server for z/OS, Version 3 Release 2

For information about changes that have been made in CICS Transaction Server for z/OS, Version 3 Release 2, please refer to What's New in the information center, or the following publications:

vCICS Transaction Server for z/OS Release Guide

vCICS Transaction Server for z/OS Migration from CICS TS Version 3.1

vCICS Transaction Server for z/OS Migration from CICS TS Version 2.3

vCICS Transaction Server for z/OS Migration from CICS TS Version 2.2

vCICS Transaction Server for z/OS Migration from CICS TS Version 1.3

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

The more significant changes for this edition are:

vBecause of the removal of support for Java hot-pooling, the following items have been removed:

–Information about the user-replaceable programs DFHAPH8O and DFHJHPAT.

DFHAPH8O was provided to allow you to alter the default Language Environment® run-time options for the Language Environment enclave where a Java program object was to be run. DFHJHPAT was optional and could be used for your own purposes; it was called before a Java program object was invoked.

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

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

vBecause of the removal of support for TCAM local terminals, the following information has been removed or rewritten:

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

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

–Chapter 8, “Writing a terminal error program,” on page 449 has been rewritten.

vThere are minor changes to the parameters passed to the exit programs at the following global user exit points:

XICEREQC XPCREQC XTDEREQC XTSEREQC

vAppendix G, “Threadsafe XPI commands,” on page 893 is a new section.

© Copyright IBM Corp. 1977, 2011

xix

Changes for CICS Transaction Server for z/OS, Version 2 Release 3

The more significant changes for this edition were:

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

vA new global user exit, XPCERES, in the program control program, was described in The XPCERES global user exit, “Using the XPCERES exit to check the availability of resources on the target region” on page 601, and “Using the XPCERES exit to check the availability of resources on the target region” on page 605.

vThe XSNEX signon and signoff global user exit, introduced as a temporary migration aid in CICS TS 2.2, is to be retained in CICS TS 2.3. You can use XSNEX to make CICS handle EXEC CICS SIGNON and SIGNOFF commands in the same way as in CICS TS 1.3 and earlier—see “Exit XSNEX” on page 201.

v“Writing Java classes to redirect JVM stdout and stderr output” on page 667 is a new section.

vThe following new sections were added to Chapter 18, “Writing a distributed routing program,” on page 623:

–“Dealing with a disabled CorbaServer” on page 635

–“Dealing with an abend on the target region” on page 644

xx Customization Guide

Part 1. Customizing with user exit programs

© Copyright IBM Corp. 1977, 2011

1

2 Customization Guide

Chapter 1. Global user exit programs

You can use the CICS global user exit points, in conjunction with programs of a special type that you write yourself (global user exit programs), to customize your CICS system.

A global user exit point, sometimes referred to as a global user exit is a place in a CICS module or domain at which CICS can transfer control to a global user exit program that you have written and at which CICS can resume control when your exit program has finished its work.

Each global user exit point has a unique identifier, 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 “Writing global user exit programs.” 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, but can invoke some CICS services using the exit programming interface (XPI). For more information, see “Using CICS services” on page 4.

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.

Writing 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. (For details about coding programs using XPI calls, refer to Chapter 3, “The user exit programming interface (XPI),” on page 305.)

Remember: 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.

Register conventions

Register values are provided on entry to an exit program and only certain register values are guaranteed.

The register values that you can use on entry to an exit program are as follows:

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 first.

© Copyright IBM Corp. 1977, 2011

3

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 field 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.

vRegister 15 contains the entry address of the exit program.

The exit program must save and restore any registers that it modifies, 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 find 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 modifies 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 305.

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. EXEC CICS commands that cause an XCTL (either directly or implied); for example, EXEC CICS XCTL or EXEC CICS SHUTDOWN must never be used.

4 Customization Guide

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

Note: In exits which support the use of EXEC CICS file control commands, file commands that form a related sequence (such as EXEC CICS STARTBR,

EXEC CICS READNEXT, and EXEC CICS ENDBR) must all be issued in the same invocation of the exit program.

For example, if one invocation of an exit program issues an EXEC CICS STARTBR command, and the next invocation of the exit program for that same task issues an EXEC CICS READNEXT command, the READNEXT fails with an INVREQ condition.

vAll exit programs that issue EXEC CICS commands must first address the EIB. This is not done automatically using the DFHEIENT macro, as is the case with normal EXEC assembler-language programs. Therefore, the first 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.

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.

Note:

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 conflict in the usage of register 13. To avoid such conflict, use the DATAREG option on the DFHEIENT macro (see “XPI register usage” on page 312 for information).

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

Using channels and containers

Global user exit programs can access channels and containers created by application programs. They can also create their own channels and pass them to programs which they call.

For information about channels and containers, see the CICS Application

Programming Guide.

Chapter 1. Global user exit programs 5

Assembler programs and LEASM

Assembler programs translated with the LEASM option cannot be used as global user exit programs.

LEASM is used to produce Language Environment conforming main programs in assembler. For information about the LEASM translator option, see the CICS Application Programming Guide.

EDF and 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.

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 7. If a user exit program does not own a global work area, UEPGAA is set to zero.

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 15.

Making trace entries

If tracing is active, you can specify that an entry in the CICS trace table is made immediately before and immediately after the exit program runs.

vUse either of the following methods to create a trace entry before and after the exit program runs:

–The UE option of the CETR transaction.

–The UE option of the EXEC CICS SET TRACETYPE command.

6 Customization Guide

vIf your global user exit is in a domain, you can add extra trace calls to provide additional diagnostic information by setting the AP option of EXEC CICS SET TRACETYPE to level 1 or 2.

vDepending on which exit point you are using, you might be able to use the XPI DFHTRPTX TRACE_PUT macro to create trace entries in the user exit program. This macro is described in Chapter 3, “The user exit programming interface (XPI),” on page 305. The individual descriptions of the global user exit points indicate whether you can use the XPI DFHTRPTX macro.

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 might also contain some exit-specific parameters that are unique to the exit point from which the exit program is being invoked.

The exit-specific parameters are described with the individual exits in the section “Alphabetical list of global user exit points” on page 25. 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 definitions that you need to map any exit-specific 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 specific 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 identifiers on a single DFHUEXIT macro instruction. For example:

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

If your exit program is to be invoked at every global user exit point, you can code:

DFHUEXIT TYPE=EP,ID=ALL

If your user exit program is to be used both as a global user exit program and as 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

Chapter 1. Global user exit programs 7

*			(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 field 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 field contains (on entry to the second and subsequent programs) the return code that was set by the previously invoked program.

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

UEPTCA

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

UEPCSA

points to fetch-protect storage. Use of this field 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.

8 Customization Guide