IBM SC33-1683-02 User Manual
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 modifications 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 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 ...........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 field 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 fields in the command-level parameter structure .......74
Modifying the EID ......................76
Use of the task token UEPTSTOK ................77
Use of the parameter UEPFSHIP.................77
TheEIB..........................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 fields 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 file 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, file control backout failure exit ............112
Exit XFCBOUT, file control backout exit ..............117
Exit XFCBOVER, file control backout override exit ..........119
Exit XFCLDEL, file 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 flag 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 specific 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 notification ................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
Benefits 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 definitions .....................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 identifier .................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 identifiers ......................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 definitions...................540
Autoinstalling programs invoked by EXEC CICS LINK commands .....540
Autoinstall processing of mapsets ................541
System autoinstall ......................541
Benefits 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 definition ......................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 flow .........................697
Terminal error program ....................699
Message routing .......................700
Segment processing .....................700
Line pool specifications ....................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 definitions ............714
Terminal operation .......................714
Help feature .........................715
Values............................715
Abbreviation rules for keywords .................716
System programming considerations ...............716
The flow 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 verification processing....................729
Writing an early verification routine ................730
Using CICS API commands in an early verification routine .......730
Return and reason codes from the early verification 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 definition 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 definitions 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 flag settings and meanings .................802
Appendix C. Transient data write-to-terminal program (DFH$TDWT) ...803
Resource definitions 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
identified 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 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 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
Reference
manual and the
CICS System Programming Reference
CICS Application Programming
manual.
Resource definition information is in the
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
and Codes
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 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.
manual, the
manual.
CICS Resource Definition Guide
CICS Problem Determination Guide
,orthe
.
CICS Messages
CICS Diagnosis
© Copyright IBM Corp. 1977, 1999 xxi
CICS Transaction Server for OS/390 Release 3 supports CICS applications written
in:
v Assembler language
v C
v COBOL
v PL/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:
v Braces { } enclose two or more alternatives, one of which you must code.
v Square brackets [ ] tell you that the enclosed is optional.
v The “or” symbol | separates alternatives.
In addition to these symbols, the following conventions apply:
v Punctuation symbols and uppercase characters should be coded exactly as
shown.
v Lowercase characters indicate that user text should be coded as required.
v Default values are shown like this: DEFAULT.
v Options that are enclosed neither in braces { } nor in square brackets[]are
mandatory.
v The ellipsis ... means that the immediately preceding option can be coded one or
more times.
v All 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
CICS Transaction Server for OS/390: Release Guide
CICS Transaction Server for OS/390: Migration Guide
CICS Transaction Server for OS/390: Installation Guide
CICS Transaction Server for OS/390: Program Directory
CICS Transaction Server for OS/390: Licensed Program Specification
CICS books for CICS Transaction Server for OS/390
General
CICS Master Index
CICS User’s Handbook
CICS Glossary
Administration
CICS System Definition Guide
CICS Customization Guide
CICS Resource Definition Guide
CICS Operations and Utilities Guide
CICS Supplied Transactions
Programming
CICS Application Programming Guide
CICS Application Programming Reference
CICS System Programming Reference
CICS Front End Programming Interface User’s Guide
CICS C⁺⁺OO Class Libraries
CICS Distributed Transaction Programming Guide
CICS Business Transaction Services
Diagnosis
CICS Problem Determination Guide
CICS Messages and Codes
CICS Diagnosis Reference
CICS Data Areas
CICS Trace Entries
CICS Supplementary Data Areas
Communication
CICS Intercommunication Guide
CICS Family: Interproduct Communication
CICS Family: Communicating from CICS on System/390
CICS External Interfaces Guide
CICS Internet Guide
Special topics
CICS Recovery and Restart Guide
CICS Performance Guide
CICS IMS Database Control Guide
CICS RACF Security Guide
CICS Shared Data Tables Guide
CICS Transaction Affinities Utility Guide
CICS DB2 Guide
(softcopy only) GC33-1705
GC33-1789
GC34-5352
GC34-5353
GC33-1681
GC33-1706
GC33-1707
SC33-1704
SX33-6104
SC33-1682
SC33-1683
SC33-1684
SC33-1685
SC33-1686
SC33-1687
SC33-1688
SC33-1689
SC33-1692
SC34-5455
SC33-1691
SC34-5268
GC33-1693
GC33-1694
LY33-6088
LY33-6089
SC34-5446
LY33-6090
SC33-1695
SC33-0824
SC33-1697
SC33-1944
SC34-5445
SC33-1698
SC33-1699
SC33-1700
SC33-1701
SC33-1702
SC33-1777
SC33-1939
© Copyright IBM Corp. 1977, 1999 xxiii
CICSPlex SM books for CICS Transaction Server for OS/390
General
CICSPlex SM Master Index
CICSPlex SM Concepts and Planning
CICSPlex SM User Interface Guide
CICSPlex SM View Commands Reference Summary
Administration and Management
CICSPlex SM Administration
CICSPlex SM Operations Views Reference
CICSPlex SM Monitor Views Reference
CICSPlex SM Managing Workloads
CICSPlex SM Managing Resource Usage
CICSPlex SM Managing Business Applications
Programming
CICSPlex SM Application Programming Guide
CICSPlex SM Application Programming Reference
Diagnosis
CICSPlex SM Resource Tables Reference
CICSPlex SM Messages and Codes
CICSPlex SM Problem Determination
Other CICS books
SC33-1812
GC33-0786
SC33-0788
SX33-6099
SC34-5401
SC33-0789
SC34-5402
SC33-1807
SC33-1808
SC33-1809
SC34-5457
SC34-5458
SC33-1220
GC33-0790
GC33-0791
CICS Application Programming Primer (VS COBOL II)
CICS Application Migration Aid Guide
CICS Family: API Structure
CICS Family: Client/Server Programming
CICS Family: General Information
CICS 4.1 Sample Applications Guide
CICS/ESA 3.3 XRF Guide
If you have any questions about the CICS Transaction Server for OS/390 library,
CICS Transaction Server for OS/390: Planning for Installation
see
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
ACF/TCAM System Programmer’s Guide
ACF/TCAM Version 3 Application Programming
SC33-0674
SC33-0768
SC33-1007
SC33-1435
GC33-0155
SC33-1173
SC33-0661
which discusses
, SC30-3121
, SC30-3117
, 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
Reference Volume 1
Authorized Assembler Programming
Reference Volume 2
Authorized Assembler Programming
Reference Volume 3
Authorized Assembler Programming
Reference Volume 4
Data Areas Volume 1 OS/390 MVS Data Areas, Vol 1
Data Areas Volume 2 OS/390 MVS Data Areas, Vol 2
Data Areas Volume 3 OS/390 MVS Data Areas, Vol 3 (IVT-RCWK)
Data Areas Volume 4 OS/390 MVS Data Areas, Vol 4 (RD-SRRA)
Data Areas Volume 5 OS/390 MVS Data Areas, Vol 5
—
System Management Facilities OS/390 MVS System Management Facilities
OS/390 MVS Authorized Assembler Services
Reference ALE-DYN
OS/390 MVS Authorized Assembler Services
Reference ENF-IXG
OS/390 MVS Authorized Assembler Services
Reference LLA-SDU
OS/390 MVS Authorized Assembler Services
Reference SET-WTO
(ABEP-DALT)
(DCCB-ITTCTE)
SY28-1166
SY28-1167
(SSAG-XTLST)
MVS/ESA Resource Measurement Facility
(RMF), Version 5–MonitorI&IIReference
and User’s Guide
(SMF)
, GC28-1783
, GC28-1764
, GC28-1765
, GC28-1766
, GC28-1767
, SY28-1164
, SY28-1165
, SY28-1168
, LY28-1007
,
,
,
VTAM books
OS/390 eNetwork Communications Server: SNA Network Implementation
SC31-8563
OS/390 eNetwork Communications Server: SNA Programming
Other related books
IBM ESA/370 Principles of Operation
IMS/ESA Application Programming: DL/I Calls
OS/390 Security Server External Security Interface (RACROUTE) Macro
Reference
OS/390 Security Server (RACF) Security Administrator’s Guide
Service Level Reporter Version 3 General Information
SNA Formats
SNA Sessions Between Logical Units
,
, SC31-8573
, SA22-7200
, SC26-3062
, GC28-1922
, SC28-1915
, GH19-6529
, GA27-3136
, GC20-1868
Bibliography xxv
Determining if a publication is current
IBM regularly updates its publications with new and changed information. When first
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
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.
CD-ROM, SK2T-0730-xx. Each
xxvi CICS TS for OS/390: CICS Customization Guide
Summary of changes
|
|
|
This book is based on the
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 significant changes for this edition:
v The 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
v The following global user exits have been modified:
– XDTAD, XDTLC, and XDTRD
– XISCONA
– XNQEREQ and XNQEREQC
– XFAINTU
– XRSINDI
– XTSPTIN, XTSQRIN, and XTSQROUT
– XTSEREQ and XTSEREQC
v Information 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.
Customization Guide
for CICS Transaction Server for
v A new user-replaceable program, DFHDSRP, is described in “Chapter 17. Writing
a distributed routing program” on page 575.
v A 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.
v A 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 significant changes:
v The 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 file control recovery program:
- XFCAREQ
- XFCAREQC
– In the 3270 bridge facility management program:
- XFAINTU
v The following new exit programming interface (XPI) function calls were
introduced:
– INQUIRE_CONTEXT
v A 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 significant changes for this edition:
v Changes to global user exits:
The following new global user exits were described in “Chapter 1. Global user
exit programs” on page 3:
– In the file control recovery program:
- XFCBFAIL
- XFCBOUT
- XFCBOVER
- XFCLDEL
– In the file 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
Loading...