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
The following global user exits became obsolete:
– XDBDERR
– XDBFERR
– XDBIN
– XDBINIT
– XJCWB
– XJCWR
– XKCREQ
– XRCFCER
– XRCOPER
– XTSIN
– XTSOUT
– XTSREQ
v Changes to task-related user exits:
“Chapter 2. Task-related user exit programs” on page 249 describes how
task-related user exits can be invoked for SPI calls; and, if CICS is in-doubt
about the outcome of a unit of work, can be told to wait rather than to take a
forced decision.
v Changes to the exit programming interface (XPI):
The following new XPI function calls were introduced:
– INQUIRE_PARAMETERS
– SET_PARAMETERS
The following existing XPI calls were modified—that is, new options were added,
or obsolete options removed:
– INQUIRE_SYSTEM
– INQUIRE_TRANDEF
– INQUIRE_TRANSACTION
– SET_SYSTEM
– WRITE_JOURNAL_DATA
v Extensions to the interface to the autoinstall user program:
Two new chapters were added:
– “Chapter 13. Writing a program to control autoinstall of shipped terminals” on
page 523
– “Chapter 14. Writing a program to control autoinstall of Client virtual terminals”
on page 531.
Also, “Chapter 12. Writing a program to control autoinstall of APPC connections”
on page 513 was extended, to describe extensions for generic resource support.
v The CICS log manager:
“Chapter 23. CICS logging and journaling” on page 629 was rewritten and
extended to describe the functions of the new CICS log manager.
v Miscellaneous changes:
– “The shutdown assist utility program, DFHCESD” on page 395 describes the
utility program that replaces the DFH$SDAP program of CICS/ESA® 4.1.
Summary of changes xxix
– The descriptions of fields in CICS-produced monitoring records, previously in
“Chapter 24. CICS monitoring” on page 657, were moved to the
Performance Guide
.
CICS
xxx CICS TS for OS/390: CICS Customization Guide
Part 1. Customizing with user exit programs
© Copyright IBM Corp. 1977, 1999 1
2 CICS TS for OS/390: CICS Customization Guide
Chapter 1. Global user exit programs
This chapter describes the CICS global user exit points, and how you can use
them, in conjunction with programs of a special type that you write yourself (global
user exit programs), to customize your CICS system. The chapter is divided into
the following sections:
1. “Overview — what is a global user exit?” is an introduction to global user
exits, describing their main features and what they can be used for.
2. “Global user exit programs” on page 4 covers topics that you need to
consider when writing a global user exit program. It deals with the following:
v “Register conventions” on page 4
v “31-bit addressing implications” on page 5
v “Using CICS services” on page 5
v “Using EDF with global user exits” on page 6
v “The global work area” on page 6
v “Making trace entries” on page 7
v “Parameters passed to the global user exit program” on page 7
v “Returning values to CICS” on page 10
v “Restrictions on the use of fields as programming interfaces” on page 11
v “Exit programs and the CICS storage protection facility” on page 11
v “Errors in user exit programs” on page 12
v “Defining, enabling, and disabling an exit program” on page 13
v “Invoking more than one exit program at a single exit” on page 13
v “Invoking a single exit program at more than one exit” on page 14
v “Sample global user exit programs” on page 14.
3. “List of global user exit points” on page 19 lists the global user exit points in
alphabetical order. The sections that follow contain detailed information about
each global user exit point, including the place in the CICS code at which it
occurs, and the specific (as distinct from the standard) parameters that are
passed to an exit program.
Overview — what is a global user exit?
A global user exit
place in a CICS module or domain
program that you have written (a global user exit
resume control when your exit program has finished its work. You do not have to
use any of the global user exits, but you can use them to extend and customize the
function of your CICS system according to your own requirements. For a complete
list of the global user exit points, see Table 2 on page 19.
point
(sometimes referred to simply as a “global user exit”) is a
1
at which CICS can transfer control to a
program
), and at which CICS can
1. A domain is an isolated functional unit of CICS Transaction Server for OS/390 Release 3 that communicates with the rest of CICS
and with other programs using a set of strictly defined and controlled interfaces.
© Copyright IBM Corp. 1977, 1999
3
global user exit programs
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 “Global user exit programs”. Also in that section is a list of the standard
parameters that the calling modules and domains pass to an exit program, and
some information about returning values to the caller.
Because global user exit programs work as if they were part of the CICS module or
domain, there are limits on the use you can make of CICS services. Most global
user exit programs cannot use EXEC CICS commands. By contrast, most global
user exit programs can invoke some CICS services using the exit programming
interface (XPI). For more information, see “Using CICS services” on page 5.
Note: Neither source nor object compatibility of CICS management modules is
guaranteed from release to release. Any changes that affect exit programs
are documented in the appropriate manual.
Global user exit programs
A global user exit program must be written in assembler language and must be
quasireentrant. However, if your user exit program calls the XPI, it must be fully
reentrant.
2
(For details about coding programs using XPI calls, refer to “Chapter 3.
The user exit programming interface (XPI)” on page 283.)
Register conventions
The following register values are provided on entry to an exit program:
v Register 1 contains the address of the user exit parameter list DFHUEPAR.
Write-to-operator (WTO) commands use register 1. If your exit program uses
WTO commands, you should save the address of DFHUEPAR first.
v Register 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.
v Register 14 contains the return address to which the exit program should branch
on completion of its work. You do this using the BR 14 instruction after restoring
the calling module’s registers, or using the RETURN macro.
2. A “reentrant” program is coded to allow one copy of itself to be used concurrently by several tasks; it does not modify itself while
running. A “quasireentrant” program is serially reusable by different tasks. When it receives control it must be in the same state as
when it relinquished control. Such a program can modify itself while running, and is therefore not fully reentrant.
CICS TS for OS/390: CICS Customization Guide
4
v Register 15 contains the entry address of the exit program.
No other register values are guaranteed, and they should not be relied on. The exit
program should save and restore any registers that it modifies, using the save area
addressed by register 13.
31-bit addressing implications
v The global user exit is invoked in 31-bit AMODE.
v The global user exit may be either RMODE 24 or RMODE ANY.
v If you find it necessary to switch to 24-bit AMODE in the exit program, be sure to
return correctly in 31-bit AMODE.
v Ensure the exit program is in 31-bit AMODE for XPI calls.
v Some of parameters passed in DFHUEPAR are addresses of storage above the
16MB line.
Access register implications
v The global user exit is invoked in primary-space translation mode. For
information about translation modes, see the
Operation
v The contents of the access registers are unpredictable. For information about
access registers, see the
v If 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.
v The global user exit must return control in primary addressing mode.
manual.
global user exit programs
IBM ESA/370 Principles of
IBM ESA/370 Principles of Operation
manual.
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:
v No CICS services can be invoked from any exit point in the dispatcher domain.
v CICS services can be invoked using the exit programming interface (XPI) from
v Some CICS services can be requested using EXEC CICS commands from some
|
|
|
|
v All exit programs that issue EXEC CICS commands must first address the EIB.
most exits. If you use the XPI, note the rules and restrictions that are listed for
each exit and each of the XPI macros. The XPI is described in “Chapter 3. The
user exit programming interface (XPI)” on page 283.
exits. The valid commands are listed in the detailed descriptions of the exits. If
no commands are listed, it means that no EXEC CICS API or SPI commands are
supported.
An exit program invoked at an exit that does not support the use of EXEC CICS
commands should not call a task-related user exit program (TRUE). (Calling a
TRUE is equivalent to issuing an EXEC CICS command.) TRUEs are described
in “Chapter 2. Task-related user exit programs” on page 249.
This is not done automatically via 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.
Chapter 1. Global user exit programs 5
global user exit programs
All exit programs that issue EXEC CICS commands, and that use the DFHEIENT
macro, should use the DFHEIRET macro to set a return code and return to
CICS. See “Returning values to CICS” on page 10.
Important
v If your global user exit program does
do not use the CICS command-level translator when assembling the
program.
v Do not make non-CICS (for example, RACF® or MVS) system service calls
from global user exit programs.
v If 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 291 for information).
For an example of how to use EXEC CICS commands and XPI calls in the same
global user exit program, see “Appendix E. The example program for the XTSEREQ
global user exit, DFH$XTSE” on page 807
Using EDF with global user exits
If you use the Execution Diagnostic Facility (EDF) to debug your applications, you
must take care when compiling exit programs that issue EXEC CICS commands.
not
contain EXEC CICS commands,
Normally, if an exit program issues EXEC CICS commands, these are displayed by
EDF, if the latter is active. They appear between the “Start of Command” and “End
of Command” screens for the command that caused the exit to be driven. If you
want to suppress the display of EXEC CICS commands issued by your exit
program, you must specify the NOEDF option when you translate the program. You
should always specify NOEDF for programs in a production environment.
If an exit program that may be invoked during recovery processing issues EXEC
CICS commands, you must translate it with the NOEDF option. Failure to do so
may cause EDF to abend.
The global work area
When you enable an exit program, you can ask CICS to provide a global work area
for the exit program. An exit program can have its own global work area, or it can
share a work area that is owned by another exit program. Note that the work area
is associated with the exit program rather than with the exit point. For ease of
problem determination, the global work area should be shared only by exit
programs that are invoked from the same management module or domain. The
address and length of the global work area are addressed by parameters UEPGAA
and UEPGAL of the DFHUEPAR parameter list, which is described in “DFHUEPAR
standard parameters” on page 8. If a user exit program does not own a global work
area, UEPGAA is set to zero.
CICS TS for OS/390: CICS Customization Guide
6
Application programs can communicate with user exit programs that use or share
the same global work area. The application program uses the EXEC CICS
EXTRACT EXIT command to obtain the address and length of the global work area.
A work area is freed only when all of the exit programs that use it are disabled. For
examples of how to use a global work area, see the sample global user exit
programs. They are listed in “Sample global user exit programs” on page 14.
Making trace entries
If tracing is active, an entry in the CICS trace table can be made immediately
before and immediately after the execution of an exit program. To specify that these
entries are to be made, use the UE option of either:
v The CETR transaction
v The EXEC CICS SET TRACETYPE command.
For global user exits in domains, extra trace calls giving more information are also
available if you have set the AP option of EXEC CICS SET TRACETYPE to level 1
or 2. For information about trace entries, refer to the
.
Guide
In some cases, when tracing is active, you can also make trace entries from within
a user exit program, using the XPI DFHTRPTX TRACE_PUT macro described in
“Chapter 3. The user exit programming interface (XPI)” on page 283. The individual
descriptions of the global user exit points show whether the XPI DFHTRPTX macro
can be used at each point.
global user exit programs
CICS Problem Determination
Parameters passed to the global user exit program
The address of a parameter list is passed to the user exit program in register 1.
The list contains some standard parameters that are passed to all global user exit
programs, and may also contain some exit-specific parameters that are unique to
the exit point from which the exit program is being invoked. Not all of the exit points
have these extra parameters.
The exit-specific parameters are described with the individual exits in the section
“List of global user exit points” on page 19. The standard parameter list is described
in the following section.
You can map the parameter list using the DSECT DFHUEPAR, which is generated
by the macro instruction
DFHUEXIT TYPE=EP,ID=exit_point_identifier
The ID parameter provides the extra data 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)
Chapter 1. Global user exit programs 7
global user exit programs
If your exit program is to be invoked at every global user exit point, you can code:
DFHUEXIT TYPE=EP,ID=ALL
If your user exit program is to be used both as a global user exit program and as a
task-related user exit program, you must code both:
DFHUEXIT TYPE=EP,ID=exit_point_identifier
and:
DFHUEXIT TYPE=RM
(in this order) to generate the DSECTs appropriate to both types of user exit.
If a global user exit program needs to use the DFHRMCAL macro to invoke an
external RMI, the DFHRMCAL macro instruction must follow the DFHUEXIT macro.
DFHUEPAR standard parameters
DFHUEPAR DSECT
* STANDARD PARAMETERS
UEPEXN DS A ADDRESS OF EXIT NUMBER
UEPGAA DS A ADDRESS OF GLOBAL WORK AREA
* (ZERO = NO WORK AREA)
UEPGAL DS A ADDRESS OF GLOBAL WORK AREA LENGTH
UEPCRCA DS A ADDRESS OF CURRENT RETURN-CODE
UEPTCA DS A RESERVED
UEPCSA DS A RESERVED
UEPEPSA DS A ADDRESS OF REGISTER SAVE AREA
* FOR USE BY EXIT PROGRAM
UEPHMSA DS A ADDRESS OF SAVE AREA USED FOR
* HOST MODULE'S REGISTERS
UEPGIND DS A ADDRESS OF CALLER'S TASK INDICATORS
UEPSTACK DS A ADDRESS OF KERNEL STACK ENTRY
UEPXSTOR DS A ADDRESS OF STORAGE FOR XPI PARAMETERS
UEPTRACE DS A ADDRESS OF TRACE FLAG
UEPEXN
points to a 1-byte binary 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.
CICS TS for OS/390: CICS Customization Guide
8
global user exit programs
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.
Apart from register 15, which contains the return code value from the exit
program, the values in this save area are used by CICS to reload the registers
when returning to the calling CICS module. They should not be corrupted.
This address is not passed to global user exit programs invoked from exit
points in CICS domains.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||||
|||
|||
|||
|||
UEPGIND
points to a 3-byte field containing indicators for use in AP domain user exits.
For non-AP domain user exits, the indicators are always zero.
The first indicator byte can take one of two symbolic values, UEPGANY and
UEPGCICS, which you can test to determine whether data locations can be
above or below 16MB, and whether the application’s storage is in CICS-key or
user-key storage:
UEPGANY
The application can accept addresses above 16MB. If the symbolic
value is not UEPGANY, the application must be returned an address
below 16MB.
UEPGCICS
The application’s working storage and the task’s life-time storage are in
CICS-key storage (TASKDATAKEY=CICS). If the symbolic value is not
UEPGCICS, the application’s working storage and the task’s life-time
storage are in user-key storage (TASKDATAKEY=USER).
The second and third bytes contain a value indicating the TCB mode of the
global user exit program’s caller. This is represented in DFHUEPAR as both a
two-character code and a symbolic value, as follows:
Table 1. TCB indicators in DFHUEPAR. Description
Symbolic
value
UEPTQR QR The quasi-reentrant mode TCB
UEPTCO CO The concurrent mode TCB
UEPTFO FO The file-owning mode TCB
UEPTRO RO The resource-owning mode TCB
2-byte
code
Description
Chapter 1. Global user exit programs 9
global user exit programs
|
|||||
|||
|||
|||
|||
|||
|||
|||
|
Table 1. TCB indicators in DFHUEPAR (continued). Description
Symbolic
value
UEPTRP RP The ONC/RPC mode TCB
UEPTSZ SZ The FEPI mode TCB
UEPTJ8 J8 The JVM mode TCB
UEPTL8 L8 An open mode TCB
UEPTSL SL The sockets listener mode TCB
UEPTSO SO The sockets mode TCB
UEPTS8 S8 The secure sockets layer mode TCB
2-byte
code
Description
UEPSTACK
points to the kernel stack entry. This value must be moved to the exit program’s
register 13 before invoking the XPI. For more information, refer to “Chapter 3.
The user exit programming interface (XPI)” on page 283. The storage
addressed by this field must not be altered. If it is corrupted, your exit program
will have unpredictable effects on your CICS system.
UEPXSTOR
#
#
#
points to a 320-byte area of DFHUEH-owned LIFO storage that the exit
program should use when invoking the XPI. For more information, refer to
“Chapter 3. The user exit programming interface (XPI)” on page 283.
UEPTRACE
points to the trace flag, which indicates whether tracing is on in the calling
management module or domain. This enables you to control your use of the
XPI TRACE_PUT macro in line with the tracing in the CICS module or domain.
The XPI TRACE_PUT function should be used only when tracing is on. The
trace flag is a single byte, whose top bit is set on when tracing is switched on.
You test this setting using the symbolic value UEPTRON. The rest of the byte
addressed by UEPTRACE is reserved, and its contents should not be
corrupted.
Returning values to CICS
At some exit points, you can influence what CICS does on return from an exit
program by supplying a return code value. The return code value must be set in
register 15 before leaving the exit program. Character strings equating to valid
return code values are provided with the parameter list appropriate for each exit
point. Always use the equated values rather than using hard-coded values. For
example, at exit XMNOUT in the monitor domain, you are presented with the
address of a monitoring record. If you decide in your exit program that this record
should not be written to SMF, you can set the return code value UERCBYP
(meaning “bypass this record”) before returning to CICS, and CICS suppresses the
record.
You cannot influence CICS actions in this way at all exit points. If you supply a
return code value that is not expected at a particular exit point, the default return
code indicating a normal response (usually UERCNORM) is assumed, unless the
return code UERCPURG is set (see note below about UERCPURG). You are
strongly advised not to let the return code default to the normal response as the
result can be unpredictable. The normal response tells CICS to continue processing
CICS TS for OS/390: CICS Customization Guide
10
global user exit programs
as if the exit program had not been invoked, and it is a valid option at most global
user exit points. The exceptions are shown in the list of return codes provided with
each exit description.
The return code currently established for an exit is addressed by parameter
UEPCRCA of DFHUEPAR, and it is needed when two or more exit programs are
used at one exit. For more information, see “Invoking more than one exit program
at a single exit” on page 13.
The return codes that are valid at each of the global user exit points are described
in “List of global user exit points” on page 19.
Important
v At some exit points, the return code UERCPURG is valid. These exits are
identified in the following tables. To prevent unpredictable results, you must
not set the return code UERCPURG except as described on page 289.
v 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. The DFHEIRET macro:
– Restores registers
– Places a return code in register 15 after the registers are restored
– Returns control to the address in register 14.
For example:
DFHEIRET RCREG=nn
where “nn” is the number of any register (other than 13) that contains the
return code to be placed in register 15 after the registers are restored.
Restrictions on the use of fields as programming interfaces
The
CICS Data Areas
form part of the Product-sensitive and General-use programming interfaces of
CICS. Fields that are not defined in the
Product-sensitive programming interface or General-use programming interface
fields are not intended for your use as part of a CICS programming interface.
manual contains definitions of the control block fields that
CICS Data Areas
manual as either
Exit programs and the CICS storage protection facility
When you are running CICS with the storage protection facility, there are two points
you need to consider for global user exits:
1. The execution key in which your user exit programs run
2. The storage key of data storage obtained for your exit programs.
Execution key for global user exit programs
When you are running with storage protection active, CICS always invokes global
user exit programs in CICS key. Even if you specify EXECKEY(USER) on the
program resource definition, CICS forces CICS key when it passes control to the
exit program. However, if a global user exit program itself passes control to another
Chapter 1. Global user exit programs 11
global user exit programs
program (via a link or transfer-control command), the program thus invoked is
executed according to the execution key (EXECKEY) defined in its program
resource definition.
Important
You are strongly recommended to specify EXECKEY(CICS) when defining
both global user exit programs and programs to which an exit program passes
control.
Data storage key for global user exit programs
The storage key of storage used by global user exit programs depends on how the
storage is obtained:
v The CICS-supplied storage addressed by the UEPXSTOR parameter of
DFHUEPAR, and any global work area specified when an exit program is
enabled, are always in CICS key.
v Global user exit programs that can issue EXEC CICS commands can obtain
storage by:
– Explicit EXEC CICS GETMAIN commands
– Implicit storage requests as a result of EXEC CICS commands that use the
SET option.
The default storage key for storage obtained by EXEC CICS commands is set by
the TASKDATAKEY of the transaction under which the exit program is invoked.
As an example, consider a transaction defined with TASKDATAKEY(USER) that
issues a file control request, which causes an XFCREQ global user exit program
to be invoked. In this case, any implicit or explicit storage acquired by the exit
program by means of an EXEC CICS command is, by default, in user-key
storage. However, on an EXEC CICS GETMAIN command, the exit program can
override the TASKDATAKEY option by specifying either CICSDATAKEY or
USERDATAKEY.
v When an exit program obtains storage by means of an XPI GETMAIN call, the
storage key depends on the value specified on the STORAGE_CLASS option,
which is mandatory, and which overrides the value of TASKDATAKEY.
Errors in user exit programs
Because global user exit programs are an extension to CICS code, they are subject
to the environment that CICS is running in when they are called. If an error is
detected at an exit point, CICS issues messages indicating which exit program was
in error, the place in the program at which the error occurred, and the name of the
associated exit point. The detection of an error is not guaranteed, because it
depends on the CICS environment at the time of error, and on the nature of the
error. For example, CICS might not recognize a looping user exit program, since the
detection mechanism may have been turned off. Also, an abend in one of the exits
XPCABND, XPCTA, or XSRAB may cause CICS to terminate abnormally, because
an abend during abend processing causes CICS to terminate.
Exit programs invoked at some exit points (for example, XTSEREQ, XTSEREQC,
XICEREQ, XICEREQC, XTDEREQ, or XTDEREQC) can enter a loop by issuing a
CICS TS for OS/390: CICS Customization Guide
12
recursive command (such as a TS command at exit point XTSEREQ). The exits
most likely to be affected provide a recursion count parameter, UEPRECUR, that
you can use to prevent such loops.
Important
When coding user exit programs, you should bear in mind that the code is
executed as an extension of CICS code, rather than as a transaction, and any
errors could have disastrous results.
Defining, enabling, and disabling an exit program
When you have written an exit program, you must define it to CICS using the CEDA
DEFINE PROGRAM command. (Note that you must specify RELOAD(NO).)
global user exit programs
Having defined the exit program, you must also enable it. You do this using the
EXEC CICS ENABLE command.
3
When you have finished using the exit program,
you should disable it, using the EXEC CICS DISABLE command.
Note: If a global user exit program is enabled before it has been installed and
LPA=YES is specified as a system initialization parameter, CICS scans the
LPA for the program. If message DFHLD0107I is issued, it means that CICS
was unable to find the program in the LPA and is using the DFHRPL version.
For programming information about the EXEC CICS ENABLE and DISABLE
commands, see the
CICS System Programming Reference
of how to enable and disable global user exit programs, see the sample programs
listed on page 14.
Invoking more than one exit program at a single exit
There may be times when you want to invoke more than one exit program from a
single global user exit point. For example, you might have two or more application
packages that supply programs for the same CICS exit. Although such programs
may work independently, you should note the following points:
v An exit program is only called at an exit if it has been made available for
execution with the START option of the EXEC CICS ENABLE command. The
order of invocation, when more than one exit program has been started at an exit
point, is the order in which the programs were activated (that is, the order in
which the EXEC CICS ENABLE commands associated them with the exit point).
When programs work on the same data area, you should consider the order in
which they are invoked. For example, in a terminal control output exit, an exit
program might manipulate the same message in different ways, depending on
the way an earlier exit program acted.
v Return code management is more complicated than it is for single programs.
Each exit program sets a return code in register 15 as usual. The second and
subsequent programs invoked from a single exit point can access the return code
value set by the preceding program (the “current return code”) using the
parameter UEPCRCA of DFHUEPAR.
manual. For examples
3. Exit programs for exits in the user log record recovery program and the file control recovery control program can also be enabled
using the TBEXITS system initialization parameter.
Chapter 1. Global user exit programs 13
global user exit programs
The following rules apply to return codes if a second user exit program sets a
different return code value from that selected by the previous program:
– If the new program supplies the same return code value as the current return
code (addressed by UEPCRCA), then CICS acts on that value.
– If the new program supplies a different return code value from the current
value addressed by UEPCRCA, CICS ignores both values and resets the
“current return code” to the default value, usually UERCNORM, before calling
any further exit programs for that exit point.
– If the new program sets an eligible value in register 15 and changes the
“current value” field to match (as addressed by UEPCRCA), the new value is
adopted and passed on to the next program (if any), or back to the calling
CICS module or domain.
Invoking a single exit program at more than one exit
To invoke a single exit program from more than one exit point, you must issue an
ENABLE command for each of the exit points. For programming information about
how to issue an ENABLE command, see the
manual. Be careful to specify GALENGTH or GAENTRYNAME on only the first
ENABLE command, otherwise ‘INVEXITREQ’ may be returned.
Take into account the restrictions that apply to the use of CICS services, because
these are dictated by the exit point itself rather than by the exit program. A
command that can be issued from one exit point may cause problems when issued
from a different exit point.
CICS System Programming Reference
The global work area is associated with the exit program, rather than with the exit
point: this means that the same global work area is used at each of the exit points
at which the exit program is invoked.
Sample global user exit programs
CICS provides sample global user exit programs for the following global user exit
points:
v XALTENF and XICTENF
|
|
|
v XBMIN and XBMOUT
v XDTAD, XDTLC, and XDTRD
v XDUREQ
v XFCBFAIL, XFCBOVER, and XFCLDEL
v XICEREQ
v XISCONA
v XMEOUT
v XNQEREQ and XNQEREQC
v XPCFTCH
v XPCTA
v XZCATT
v XZIQUE
The source of all the sample programs, and any associated copy books, is supplied
in the CICSTS13.CICS.SDFHSAMP library. You can use the supplied programs as
models on which to base your own versions.
CICS TS for OS/390: CICS Customization Guide
14
global user exit programs
Global work area (GWA) sample exit programs
This set of sample programs shows you how to:
v Enable a global user exit program and allocate a global work area (GWA).
v Obtain the address of an exit program’s GWA.
v Access CICS system information, and make that information available to other
global user exit programs.
v Share a GWA between global user exit programs, thereby making the information
it contains available to more than one program, and overcoming limitations on
the size of GWAs.
v Access information held in a global user exit program’s GWA.
The GWA sample programs and copy books are:
DFH$PCEX
A sample global user exit program, designed to be invoked at the
XPCFTCH exit.
CICS also provides copy book DFH$PCGA for use in this sample program.
DFH$ZCAT
A sample global user exit program, designed to be invoked at the XZCATT
exit.
CICS also provides copy book DFH$ZCGA for use in this sample program.
DFH$PCPI and DFH$PCPL
DFH$PCPI is designed to be invoked during program list table post
initialization (PLTPI) processing, and is described in “The DFH$PCPI
program”.
DFH$PCPL is a dummy program, invoked by DFH$PCPI, that causes the
XPCFTCH user exit to be driven.
The DFH$PCPI program:
1. Section 1 obtains and processes any parameters passed to DFH$PCPI on the
INITPARMS system initialization parameter.
2. Section 2 shows how to use standard CICS facilities to obtain system
information, and make that information available to a global user exit program. It
performs the following processing:
v Uses the EXEC CICS ENABLE command to enable the XPCFTCH sample
user exit program, DFH$PCEX, and allocate it a global work area.
v Uses the EXEC CICS EXTRACT EXIT command to obtain the address of
DFH$PCEX’s global work area.
v Obtains CICS system information, and places it in DFH$PCEX’s global work
area. The information obtained includes:
– Job name
– Applid
– Sysid
– CICS release
– Date in various formats, including DATFORM
– The address of the common work area (CWA)
– CICS startup type (COLD, WARM).
DFH$PCPI consists of three main sections:
Chapter 1. Global user exit programs 15
global user exit programs
v Uses the START option of the EXEC CICS ENABLE command to make
v Links to the dummy program, DFH$PCPL, in order to drive DFH$PCEX.
v Uses the STOP option of the EXEC CICS DISABLE command to make
3. Section 3 of DFH$PCPI shows how to share the system information in an exit
program’s global work area with other exit programs. (In doing so it
demonstrates how application programs can access the same information by
means of the EXEC CICS EXTRACT EXIT command.) It also shows how to use
CICS shared storage to overcome the limitation of 32KB on the size of a GWA.
The program obtains an area of 64KB below 16MB and an area of 128KB
above 16MB (using GETMAIN). The use of shared storage enables the second
user exit program (DFH$ZCAT) to use a work area of only 12 bytes below
16MB.
The section performs the following processing:
v Uses EXEC CICS ENABLE to enable the DFH$ZCAT user exit program, and
v Uses EXEC CICS EXTRACT EXIT to obtain the address of DFH$ZCAT’s
v Stores the address of DFH$PCEX’s global work area in DFH$ZCAT’s global
v Uses GETMAIN to obtain the shared storage above and below the 16MB
Most of the above information is obtained using EXEC CICS API commands
such as:
– INQUIRE SYSTEM
– ASSIGN
– ADDRESS
– ASKTIME
– FORMATTIME.
DFH$PCEX available for execution. This causes DFH$PCEX to be driven for
all LINKs and XCTLs.
DFH$PCEX unavailable for execution. Note that this leaves DFH$PCEX’s
global work area still allocated and accessible through the EXEC CICS
EXTRACT EXIT command.
allocate it a global work area
global work area
work area
line, and stores the addresses in DFH$ZCAT’s global work area.
Sample program definitions:
required to define the sample programs to the CSD:
DEFINE PROGRAM(DFH$PCEX) GROUP(EXITGRP)
DEFINE PROGRAM(DFH$PCPI) GROUP(EXITGRP)
DEFINE PROGRAM(DFH$PCPL) GROUP(EXITGRP)
DEFINE PROGRAM(DFH$ZCAT) GROUP(EXITGRP)
CICS TS for OS/390: CICS Customization Guide
16
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS)
LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL)
USELPACOPY(NO) STATUS(ENABLED) CEDF(YES) DATALOCATION(ANY)
EXECKEY(CICS)
The following are examples of the RDO definitions
global user exit programs
DFH$PCPI is designed to be run as a PLT program. If you write a similar program,
you should define it in the second part of the PLTPI list (after the
PROGRAM=DFHDELIM entry). Information about how to do this is in the
|
Resource Definition Guide
.
CICS
|
|
|
|
|
|
|
|
The Basic Mapping Support sample exit program
CICS supplies a sample global user exit program for the Basic Mapping support
exits:
DFH$BMXT
A sample global user exit program, designed to be invoked at the XBMIN
and XBMOUT exits. The program shows how you can use the exits to
modify mapped input and output data.
The data tables sample exit programs
CICS supplies one sample global user exit program for each of the data tables exit
points. These are:
DFH$DTAD
A sample global user exit program, designed to be invoked at the XDTAD
exit.
DFH$DTLC
A sample global user exit program, designed to be invoked at the XDTLC
exit.
DFH$DTRD
A sample global user exit program, designed to be invoked at the XDTRD
exit.
DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the
Tables Guide
.
CICS Shared Data
The dump domain sample exit program
There is one dump domain sample global user exit program:
DFH$XDRQ
A sample global user exit program, designed to be invoked at the XDUREQ
exit.
|
|
|
|
|
|
|
|
The enqueue EXEC interface sample exit program
There is one sample global user exit program for the enqueue EXEC interface.
DFH$XNQE
A sample global user exit program, designed to be invoked at the
XNQEREQ and XNQEREQC exits. The program demonstrates three ways
of adding a SCOPE value to EXEC CICS ENQ and DEQ requests, to make
the requests apply to multiple regions within the sysplex.
The file control recovery program sample exit programs
CICS provides three sample file control global user exit programs:
DFH$FCBF
A sample exit program designed to be invoked at the XFCBAIL exit for
handling backout failures. See “DFH$FCBF sample global user exit
program” on page 116.
Chapter 1. Global user exit programs 17
global user exit programs
DFH$FCBV
DFH$FCLD
You can define these programs by including the supplied resource group,
DFH$FCB, in your startup grouplist, or by using CEDA to install DFH$FCB.
The function-shipping and DPL queue control sample exit
program
A sample exit program designed to be invoked at the XFCBOVER exit; it
allows you to decide whether to allow an update to be backed out, following
a batch update run that has overridden retained locks. See “DFH$FCBV
sample global user exit program” on page 121.
A sample exit program designed to be invoked at the XFCLDEL exit, which
allows you to perform logical deletion of records from a VSAM ESDS data
set or a BDAM data set, during backout. See “DFH$FCLD sample global
user exit program” on page 123.
|
|
|
|
|
|
|
|
|
|
|
You can use the XISCONA sample global user exit program to control the queueing
of function-shipping and DPL requests:
DFHXIS
A sample global user exit program, designed to be invoked at the XISCONA
exit.
The interval control EXEC interface sample exit program
DFH$ICCN
A sample global user exit program, designed to be invoked at the XICEREQ
exit. DFH$ICCN is for use in a distributed routing environment, where you
want to cancel a previously-issued interval control request but have no way
of knowing to which region to direct the CANCEL. For examples of
situations which DFH$ICCN is designed to cope with, see the
Intercommunication Guide
.
CICS
The ISC session queue management sample exit program
This sample program implements the same basic function provided by the
QUEUELIMIT and MAXQTIME parameters on a connection resource definition.
These parameters are passed to the XZIQUE global user program, which can
change the way in which these parameters are used:
DFH$XZIQ
A sample global user exit program, designed to be invoked at the XZIQUE
exit, which is described on page “XZIQUE exit for managing intersystem
queues” on page 237.
See “Sample exit program design” on page 244 for more details.
The message domain sample exit programs
These sample programs show you how to write a program to be invoked at a
specific exit, to do a specific task. For example, the DFH$SXP4 sample program
shows you how to use the XMEOUT exit to reroute a console message to a
transient data queue.
DFH$SXPn
A set of sample global user exit programs designed to be invoked at the
XMEOUT exit (where ‘n’ is 1 through 6).
CICS TS for OS/390: CICS Customization Guide
18
global user exit programs
The terminal-not-known sample exit program
You can use this sample global user exit program to handle terminal-not-known
conditions arising from START and ATI requests:
DFHXTENF
A sample global user exit program, designed to be invoked at the XALTENF
or XICTENF exit. The sample source code is shown on page “The sample
program for the XALTENF and XICTENF exits, DFHXTENF” on page 214.
The transaction-abend sample exit program
There is one sample global user exit program for the XPCTA exit point:
DFH$PCTA
This sample global user exit program is designed to be invoked at the
XPCTA exit, to test whether the abend was caused by a storage protection
exception condition. It is described on page “The sample XPCTA global
user exit program, DFH$PCTA” on page 169.
Example program
As well as the sample programs supplied in source code, there is an example
listing, DFH$XTSE, that shows you how to:
v Use EXEC CICS commands in a global user exit program
v Use EXEC CICS commands and XPI calls in the same exit program
v Modify the command parameter list in EXEC interface exits such as XTSEREQ
and XICEREQ.
DFH$XTSE is listed on page 807.
List of global user exit points
Table 2 lists the global user exit points in alphabetical order, giving a brief
description and a page reference at which more information about each exit can be
found.
Table 2. Alphabetical list of global user exit points
Exit name Module or
XAKUSER Activity keypoint
XALCAID Terminal
XALTENF When an ATI request from transient
||||||
||||
XBMIN Basic Mapping
XBMOUT When a page of output has been built
XDLIPOST DL/I interface
XDLIPRE On entry to the DL/I interface program. 45
domain
program
allocation
program
Support
program
Where or when invoked Page
Immediately before the ‘end of keypoint’
record is written.
Whenever an AID with data is canceled. 203
data or interval control requires a
terminal that is unknown in this system.
When an input mapping operation
completes successfully.
successfully.
On exit from the DL/I interface program. 47
25
209
28
28
Chapter 1. Global user exit programs 19
global user exit points
Table 2. Alphabetical list of global user exit points (continued)
Exit name Module or
XDSAWT Dispatcher
XDSBWT Before an operating system wait. 42
XDTAD Data tables
XDTLC At the completion of loading of a data
XDTRD During the loading of a data table,
XDUCLSE Dump domain After the domain closes a transaction
XDUOUT Before the domain writes a record to
XDUREQ Before the domain takes a system or
XDUREQC After a system or transaction dump has
XEIIN EXEC interface
XEIOUT After the execution of any EXEC CICS
XEISPIN Before the execution of any EXEC
XEISPOUT After the execution of any EXEC CICS
XFAINTU 3270 bridge
XFCAREQ File control EXEC
XFCAREQC After a file control SPI request has
domain
domain
management
program
facility
management
program
interface program
Where or when invoked Page
After an operating system wait. 42
When a write request is issued to a
data table.
table.
whenever a record is retrieved from the
source data set.
dump data set.
the transaction dump data set.
transaction dump.
been taken (or failed or been
suppressed).
Before the execution of any EXEC
CICS API or SPI command.
API or SPI command.
CICS SPI command
CICS ENABLE, EXEC CICS DISABLE,
or EXEC CICS EXTRACT EXIT.
SPI command
ENABLE, EXEC CICS DISABLE, or
EXEC CICS EXTRACT EXIT.
When a bridge facility is created or
deleted.
Before CICS processes a file control
SPI request.
completed.
except
except
EXEC
EXEC CICS
36
37
34
55
55
49
52
66
68
67
68
32
83
83
CICS TS for OS/390: CICS Customization Guide
20
global user exit points
Table 2. Alphabetical list of global user exit points (continued)
Exit name Module or
domain
XFCBFAIL File control
recovery control
XFCBOUT When CICS is about to back out a file
XFCBOVER When CICS is about to skip backout of
XFCLDEL When backing out writes to a VSAM
XFCNREC File control
XFCQUIS File control
XFCREQ File control EXEC
XFCREQC After a file control API request has
XFCSREQ File control file
XFCSREQC After a file OPEN, CLOSE, CANCEL
XFCVSDS File control
XGMTEXT “Good morning”
XICEREQ Interval control
XICEREQC After an interval control API request has
XICEXP Interval control
XICREQ At the start of the interval control
XICTENF When an EXEC CICS START command
program
open/close
program
quiesce send
program
interface program
state program
quiesce receive
program
message program
EXEC interface
program
program
Where or when invoked Page
When an error occurs during the
backout of a UOW.
update.
a UOW because a batch program has
overridden RLS retained lock protection
and opened a data set for batch
processing.
ESDS or a BDAM data set.
When a mismatch is detected between
the backout recovery setting for a file
and its associated data set during file
open processing.
On completion, successful or failed, of a
SET DSNAME QUIESCESTATE
command.
Before CICS processes a file control
API request.
completed.
Before a file OPEN, CLOSE, ENABLE,
or DISABLE command is attempted.
CLOSE, ENABLE, or DISABLE
command has been completed.
After RLS has informed CICS that
processing is required as a result of a
data set-related action occurring in the
sysplex.
Before the “good morning” message is
sent.
Before CICS processes an interval
control API request.
completed.
After expiry of an interval control time
interval.
program, before request analysis.
requires a terminal that is unknown in
this system.
112
117
119
122
106
110
79
80
96
96
107
126
134
135
133
132
212
Chapter 1. Global user exit programs 21
global user exit points
|
|
|
|
|||
|
|
|
||
|
|
|
Table 2. Alphabetical list of global user exit points (continued)
Exit name Module or
domain
XISCONA Intersystem
communication
program
XISLCLQ After an attempt to allocate a session
XLDLOAD Loader domain After an instance of a program is
XLDELETE After an instance of a program is
XLGSTRM Log manager
domain
XMEOUT Message domain Before a message is sent from the
XMNOUT Monitoring
domain
XNQEREQ Enqueue EXEC
interface program
XNQEREQC After an enqueue API request has
XPCABND Program control
XPCFTCH Before an application program is given
XPCHAIR Before a HANDLE ABEND routine is
XPCREQ Before a LINK request is processed. 158
XPCREQC After a LINK request has been
XPCTA After an abend occurs, and before the
XRCINIT User log record
XRCINPT During warm and emergency restart, for
program
recovery program
Where or when invoked Page
When a function shipping or DPL
request is about to be queued because
no sessions to the remote region are
immediately available.
for a function shipped START
NOCHECK request fails because the
remote system is not in service, a
connection to the remote system cannot
be established, or no sessions are
immediately available and your
XISCONA exit program has specified
that the request is not to be queued in
the issuing region.
brought into storage, and before the
program is made available for use.
released by CICS and just before the
program is freed from storage.
After the CICS log manager detects that
a log stream does not exist, and before
calling the MVS system logger to define
the log stream.
message domain to its destination.
Before a record is either written to SMF
or buffered before a write to SMF.
Before CICS processes an enqueue
API request.
completed.
Before a dump call is made. 169
control.
given control.
completed.
environment is modified.
During warm and emergency restart, if
user recovery log records are detected
in the CICS system log.
each user recovery log record found in
the CICS system log.
127
130
147
148
149
153
156
57
58
165
166
159
168
232
232
CICS TS for OS/390: CICS Customization Guide
22
global user exit points
Table 2. Alphabetical list of global user exit points (continued)
Exit name Module or
domain
XRMIIN Resource
manager interface
XRMIOUT After execution of an EXEC DLI, EXEC
XRSINDI Resource
XSNOFF Security manager
XSNON After a terminal user signs on. 177
XSRAB System recovery
XSTERM System
XSTOUT Statistics domain Before a statistics record is written to
XSZARQ Front End
XSZBRQ Before a FEPI request is actioned. 125
XTCATT Terminal control
XTCIN After an input event. 205
XTCOUT Before an output event. 205
XTCTIN After a TCAM input event. 206
XTCTOUT Before a TCAM output event. 207
XTDEREQ Transient data
XTDEREQC After a transient data API request has
XTDIN Transient data
XTDOUT Before passing data to a QSAM
XTDREQ Before request analysis. 218
XTSEREQ Temporary
XTSEREQC After a temporary storage API request
XTSPTIN Temporary
XTSPTOUT After invocation of a TSPT function. 191
XTSQRIN Before invocation of a TSQR function. 187
XTSQROUT After invocation of a TSQR function. 188
XXDFA DBCTL interface
program
management
modules
domain
program
termination
program
Programming
Interface
program
EXEC interface
program
program
storage EXEC
interface program
storage domain
control program
Where or when invoked Page
Before execution of an EXEC DLI,
EXEC SQL, or RMI command.
SQL, or RMI command.
Immediately after a successful install or
discard of a resource.
After a terminal user signs off. 178
When the system recovery program
finds a match for an MVS abend code
in the SRT.
During a normal system shutdown,
immediately before TD buffers are
cleared.
SMF.
After a FEPI request has completed. 125
Before task attach. 206
Before CICS processes a transient data
API request.
completed.
After receiving data from QSAM
(extrapartition) or VSAM (intrapartition).
(extrapartition) or VSAM (intrapartition)
user-defined transient data queue.
Before CICS processes a temporary
storage API request.
has completed.
Before invocation of a TSPT function. 190
In the active CICS when CICS-DBCTL
connection fails.
171
171
173
182
186
180
221
223
219
220
194
195
39
Chapter 1. Global user exit programs 23
global user exit points
Table 2. Alphabetical list of global user exit points (continued)
Exit name Module or
XXDFB DBCTL tracking
XXDTO In the alternate CICS when active
XXMATT Transaction
XXRSTAT XRF request
XZCATT VTAM terminal
XZCIN VTAM working set
XZCOUT Before an output event. 235
XZCOUT1 Before a message is broken into RUs. 236
XZIQUE
domain
program
manager domain
processing
program
management
program
module
Where or when invoked Page
In the alternate CICS when DBCTL
fails.
DBCTL fails.
When a user transaction is attached. 216
After a VTAM failure or a predatory
takeover.
Before task attach. 234
After an input event. 235
1. When an allocate request for a
session is about to be queued.
2. When an allocate request succeeds
following previous suppression of
queuing.
40
41
246
237
The following sections give detailed information about each of the global user exit
points, including:
v The exit identifier
v The location of the exit
v The DFHUEPAR parameters, if any, that are unique to the exit
v The return codes that are valid for this exit point
v XPI calls that can be invoked.
In the following sections, the exit points are grouped according to their functional
relationships. This usually means according to the CICS module or domain in which
they occur. However, where exit points in different modules serve a similar function
(XALTENF in the terminal allocation program and XICTENF in the interval control
program, for example), the exits are grouped under a generic name (for example,
“Terminal not known” condition exits). The groups of exits are presented in
alphabetical order of module or generic name.
Accessing fields in CICS control blocks
When writing a program to be invoked from any of the global user exit points,
note the warning contained in “Restrictions on the use of fields as
programming interfaces” on page 11 about the use of control block fields as
programming interfaces.
CICS TS for OS/390: CICS Customization Guide
24
Activity keypoint program exit XAKUSER
The XAKUSER exit is invoked during the activity keypointing process. You can use
this exit to record, on the system log, user data that must be restored following an
emergency restart. For further information about the use of the exit, see the
Recovery and Restart Guide
For best performance, journal control requests should not specify WAIT. CICS will
force the records by writing a synchronous end of keypoint record upon return from
the exit program.
Your exit program should be translated with the NOEDF option. Any program it links
to should also be translated with this option. It is not possible to link to programs
written in PL/I.
To ensure that it is called during every keypoint, your exit program should be
enabled by means of a first phase PLTPI program—see “Initialization programs” on
page 393. However, if it enabled at this stage, your program should not attempt to
link to any program coded in VS COBOL II or C, as it may be invoked before these
are initialized.
.
activity keypoint program exit
CICS
Exit XAKUSER
Important
Your exit program forms part of a critical CICS system activity. If it fails, CICS
terminates.
When invoked
During the activity keypointing process.
Exit-specific parameters
UEPAKTYP
Address of a 1-byte field indicating the type of keypoint for which
the exit is invoked. The possible values are:
UEPAKPER
Activity keypoint
UEPAKWSD
Warm shutdown keypoint.
Return codes
UERCNORM
Continue processing.
XPI calls
XPI must not be used.
API and SPI calls
The following commands are supported:
ADDRESS CWA
ADDRESS EIB
LINK (but only to local programs; distributed program links may not be
used).
RETURN
Chapter 1. Global user exit programs 25
activity keypoint program exit
Important
Only the listed EXEC CICS commands are allowed in the XAKUSER exit. The
exit should link only to other programs with the same restrictions.
WRITE JOURNALNAME.
CICS TS for OS/390: CICS Customization Guide
26
|
|
Basic Mapping Support exits XBMIN and XBMOUT
Basic Mapping Support exits
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The XBMIN exit allows you to intercept a RECEIVE MAP request after BMS has
successfully processed the request. The XBMOUT exit allows you to intercept a
SEND MAP request after BMS has successfully processed the request; or, if
cumulative mapping is in progress, on completion of each page of output.
The XBMIN exit is called, if enabled, when all the following are true:
v A RECEIVE MAP command has been successfully processed.
v The map referenced in the command contains at least one field specified as
VALIDN=USEREXIT.
v At least one USEREXIT field has been returned in the inbound datastream and
has been mapped into the application data structure.
Using XBMIN, you can:
v Analyze each field defined as VALIDN=USEREXIT mapped to the application on
this request
v Use the mapset name, map name, and field length defined in the map, and the
actual length of field data returned in the inbound datastream
v Modify the data in each field.
The XBMOUT exit is called, if enabled, when all the following are true:
v A SEND MAP command has been successfully processed.
v The map referenced in the command contains at least one field specified as
VALIDN=USEREXIT.
v At least one USEREXIT field has been generated in the outbound datastream.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using XBMOUT, you can:
v Analyze each field defined as VALIDN=USEREXIT which has been generated in
the outbound datastream
v Use the mapset name, map name, and field length defined in the map, and the
actual length of field data placed in the outbound datastream
v Modify the data in each field
v Modify the attributes sent with each field.
Both exits are passed four exit-specific parameters:
1. The address of the TCTTE associated with the mapping request
2. The address of the system EIB associated with the task issuing the mapping
request
3. The address of a halfword binary count of the number of elements in the
field
element table
4. The address of the field element table.
Chapter 1. Global user exit programs 27
Basic Mapping Support exits
|
|
|
|
|
||
|
Exit XBMIN
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sample program, DFH$BMXT
CICS supplies a sample program, DFH$BMXT, that shows how mapped input
and output data can be modified with reference to the information provided in
the “field element” table. A copybook, DFHXBMDS, is also supplied. This
copybook is a DSECT which defines the structure of the field element.
When invoked
After BMS has successfully processed an input mapping operation.
Exit-specific parameters
UEPBMTCT
Address of the TCTTE associated with the mapping request.
UEPEXECB
Address of the system EIB associated with the task.
UEPBMCNT
Address of the halfword binary number of “field elements” in the
field element table.
UEPBMTAB
Address of the field element table.
Return codes
|
|
|
|
|
|
Exit XBMOUT
|
|
|
|
|
|
|
|
|
|
|
|
|
|
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
When invoked
After BMS has successfully completed a page of output during an output
mapping operation.
Exit-specific parameters
UEPBMTCT
Address of the TCTTE associated with the mapping request.
UEPEXECB
Address of the system EIB associated with the task.
UEPBMCNT
Address of the halfword binary number of “field elements” in the
field element table.
UEPBMTAB
Address of the field element table.
|
|
|
CICS TS for OS/390: CICS Customization Guide
28
Return codes
UERCNORM
Continue processing.
Basic Mapping Support exits
|
|
|
|
|
The field element table structure
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
XPI calls
The
about each “field of interest” passed to the exit. A “field of interest” is a field which
has been defined as VALIDN=USEREXIT in the map source file used to create the
mapset referenced in the mapping operation.
Each field element has the following structure:
BMXMAPST
BMXMAP
BMXFDFB
UERCPURG
Task purged during XPI call.
All can be used.
field element table
is an 8-byte area which contains the name of the mapset associated with this
field. If terminal or alternate suffixes are used with mapset names in your CICS
installation, the mapset name may have a suffix appended to the name
specified in the mapping request.
is a 7-byte area which contains the name of the map associated with this field.
is a one-byte field copied from the field specification in the map load module. It
contains indicators as follows:
contains one or more elements which provide information
||
||
||
||
||
||
||
||
|
|
|
|
|
|
|
|
|
|
|
X'80' CASE=MIXED
X'40' Group field entry
X'20' Group field descriptor
X'10' ATTRB=DET
X'08' JUSTIFY=ZERO
X'04' JUSTIFY=RIGHT
X'02' INITIAL,XINIT, or GINIT specified
X'01' Named field (DSECT entry exists)
BMXMAPLN
is a halfword binary value which contains the field length defined in the
LENGTH option of the DFHMDF macro.
BMXACTLN
is a halfword binary value which contains the actual length of the data received
or transmitted in this field.
BMXDATA
is the address of the field data.
In the XBMIN exit, BMXDATA points into a work area which BMS has obtained
for input mapping purposes. When the exit returns control, this work area is
copied to the application data structure associated with this map.
|
|
In the XBMOUT exit, BMXDATA points into a terminal input/output area (TIOA)
in which BMS has generated an output datastream. When the exit returns
Chapter 1. Global user exit programs 29
Basic Mapping Support exits
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
control, the TIOA is disposed of in accordance with the disposition of the
TERMINAL (the default), SET, or PAGING option specified on the SEND MAP
request.
BMXATTR
is only relevant in the XBMOUT exit. It is the address of the attributes (if any)
which BMS has placed in the output datastream preceding this field.
BMXMAPOF
is the offset of the field in the map. For example, if a map is defined as
MYMAP DFHMDI SIZE=(12,40)
and a field in this map is defined as
FLDA DFHMDF POS=(5,1)
the offset of this field (relative to zero) is 160 in decimal notation. In this
example, BMXMAPOF would contain the value X'00A0'.
BMXBUF
is the offset of the field in the device buffer. Usually—that is, when the map
dimensions are the same as the current screensize in use by the device—this
value will be the same as that of BMXMAPOF. However, using the example
given in the BMXMAPOF description above, if MYMAP is sent to a device
currently using a 24 by 80 screensize, the offset of the field in the device buffer
(again relative to zero) is 320 in decimal notation. In this example, BMXBUF
would contain the value X'0140'.
Programming the XBMIN exit
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This section contains some considerations specific to the XBMIN exit.
The actual data length (in BMXACTLN) may be less than the length defined in the
map (in BMXMAPLN). This could happen, for example, if a terminal operator does
not completely fill a data entry field. In this case, BMS will have right- or left-justified
the data in the field and padded the field with blank or zero characters. This
justification and padding occurs before the exit is invoked. Your exit program can,
by checking the bit settings in the BMXFDFB field, determine how BMS performed
justification and padding for the field.
The actual data length (in BMXACTLN) may be greater than the length defined in
the map (in BMXMAPLN). This could happen, for example, if a map contains an
unprotected field which is not immediately followed by another field. This allows the
terminal operator to enter data past the end of the field. When this occurs, the data
field is truncated by BMS according to the length defined for the field in the map.
However, BMXACTLN contains the length of data found in the inbound datastream.
When modifying data in the XBMIN exit, the safest method is to use the length
provided in BMXMAPLN, but to ensure that any pad characters added by BMS are
preserved.
BMXATTR must be ignored in the XBMIN exit; it always contains binary zeroes.
Programming the XBMOUT exit
|
|
CICS TS for OS/390: CICS Customization Guide
30
This section contains some considerations specific to the XBMOUT exit.
Basic Mapping Support exits
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The actual data length (in BMXACTLN) may be less than the length defined in the
map (in BMXMAPLN). This occurs due to the compression of trailing nulls
performed by BMS for each output field.
The actual length of data cannot be changed in the exit program. The exit is
invoked after the output datastream has been generated; consequently, an attempt
to alter the data length could result in an invalid datastream. Therefore, if an
XBMOUT exit program modifies data, it must do so with reference to the length
value in BMXACTLN.
BMXDATA may contain a null value. This can be caused by a SEND MAP request
with the MAPONLY option when the map has fields without default data; this causes
BMS to send an attribute sequence for the field but no data.
BMXATTR may contain a null value. This can be caused by a SEND MAP request
with the DATAONLY option, when the application is updating the data in a field and
not the attributes.
Cumulative mapping operations
When an application is performing cumulative mapping—that is, issuing a sequence
of SEND MAP commands with the ACCUM option—BMS builds composite display
in which a single page of output might be constructed from multiple SEND MAP
requests. When cumulative mapping occurs, the XBMOUT exit is called when a
page has been built, not as each SEND MAP request is processed.
|
|
|
|
|
|
|
|
|
|
Message routing
When an application builds a routing message—for example, it issues a ROUTE
command followed by one or more SEND MAP commands with the SET or
PAGING option specified—the XBMOUT exit is invoked in the same way as for a
non-routed mapping request.
However, the UEPBMTCT parameter is passed as a null value for a routed
message. This is because a routed message may be destined for multiple devices,
and BMS has optimized the features supported by the devices targeted by the
routed message. When processing a routed message in the XBMOUT exit,
referencing the TCTTE for any of these devices would probably not be relevant.
Chapter 1. Global user exit programs 31
Bridge facility exit
Bridge facility exit
When enabled, XFAINTU (Facility Initialization and Tidy Up) is called:
v Just after a new bridge facility has been built.
v Just before a bridge facility is deleted. This may be at the end of a task (when
zero keep time is specified), or when a keep time expires before the facility is
re-used.
Exit XFAINTU
When invoked
Exit-specific parameters
Just after a bridge facility is created and just before it is freed.
UEPFAREQ
Address of a 1-byte field that indicates why the exit has been
called. Possible values are:
UEPFAIN
Initialization.
UEPFATU
Tidy-up.
UEPFATUT
UEPFANAM
UEPFATYP
UEPFAUAA
UEPFAUAL
Return codes
Address of a 1-byte field that indicates the type of tidy-up required.
Possible values are:
UEPFANTU
Normal tidy-up.
UEPFAETU
Expired tidy-up.
Address of the bridge facility name.
Address of a 1-byte field that indicates the facility type. The value is
always:
UEPFABR
3270 bridge facility.
Address of the bridge facility user area (TCTUA).
Address of a one-byte field containing the length of the bridge
facility user area.
UERCNORM
Continue processing.
XPI calls
|
API calls
|
|
CICS TS for OS/390: CICS Customization Guide
32
All can be used, except those that use Recovery Manager services.
All can be used except those that invoke task-related user exits, or use
Recovery Manager services.
data tables program exits
Data tables management exits XDTRD, XDTAD, and XDTLC
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
These exits apply to both:
v CICS shared data tables
v CICS coupling facility data tables.
XDTRD and XDTAD allow you to control the selection of records for inclusion in a
data table, XDTRD being used to make such selections during loading, and XDTAD
being invoked when records are subsequently added to a loaded data table (or to a
CFDT that did not require loading). XDTRD also allows the contents of records that
are included in a user-maintained table, or a coupling facility data table, to be
modified before they are added.
For CICS shared data tables, XDTLC enables you to take action based on the fact
that a data table has completed loading, which might be to end some restrictions
that you have decided to place on access to the data table during loading, or to
cater for an unsuccessful completion of the loading.
For a coupling facility data table, XDTLC allows your global user exit program to
decide whether to accept an unsuccessfully loaded coupling facility data table. If the
user exit program decides to accept the table, it remains open and available for
access, but CICS does not mark it as loading completed. This is also the default
action if no XDTLC exit is enabled. This means that application programs continue
to receive the LOADING condition for any records that are beyond the key range of
records successfully loaded into the table. This ensures that application programs
are aware that not all the expected data is available. It also allows you to retry the
load, when the cause of the failure has been corrected, by closing the file that
initiated the load and reopening it. Alternatively, you could open another
load-capable file that refers to the same data table. If your exit program decides to
reject the table, it is closed and the records already loaded remain in the table. If
the cause of the failure is corrected, a subsequent open for the data table allows
the load to complete. XDTLC is not invoked for a coupling facility data table that is
not loaded from a source data set.
Exit XDTRD
Note that a program invoked from any of these exit points must declare a DSECT
defining the data tables user exit parameter list pointed to by field UEPDTPL.
(Although UEPDTPL is defined by a DFHUEXIT call, the parameter list that it
addresses is not.) To do this, your program can include the copybook DFHXDTDS,
which defines the DT_UE_PLIST DSECT.
If any tables specify OPENTIME=STARTUP or are opened implicitly, you should
provide a program list table post-initialization (PLTPI) program to activate the user
exits. Otherwise, the data table may start loading before the exits can be enabled.
For more details about PLTPI programs, see “Chapter 4. Writing initialization and
shutdown programs” on page 393.
Note: For additional information about using these exits with CICS shared data
table support, see the
The XDTRD user exit is invoked just before CICS attempts to add to the data table
a record that has been retrieved from the source data set.
CICS Shared Data Tables Guide
Chapter 1. Global user exit programs 33
.
data tables program exits
This normally occurs when the loading process retrieves a record during the
sequential copying of the source data set. However, it can also occur when an
application retrieves a record that is not in the data table and:
v For a user-maintained data table, loading is still in progress, or
v For a CICS-maintained data table, loading terminated before the end of the
source data set was reached (because, for example, the data table was full).
|
|
|
Note: For a coupling facility data table the XDTRD exit is invoked only for a table
that is loaded from a source data set.
The record retrieved from the source data set is passed as a parameter to the user
exit program—see fields UEPDTRA and UEPDTRL. Your exit program can choose
(depending, for example, on the key value—see fields UEPDTKA and UEPDTKL)
whether to include the record in the data table or not.
Alternatively, the exit program can request that all subsequent records up to a
specified key are skipped—see field UEPDTSKA; these records are not passed to
the exit program. This facility is available only during loading. You can specify the
key as a complete key, or you can specify just the leading characters by padding
the skip-key area with binary zeros.
For a user-maintained data table, the program can also modify the data in the
record to reduce the storage needed for the data table. Application programs that
use the data table must be aware of any changes made to the record format by the
exit program. If the record length is changed, the exit program must set the new
length in the parameter list—see field UEPDTRL. The new length must not exceed
the data buffer length—see field UEPDTRBL.
When invoked
Just before CICS tries to add to the data table a record that has been
retrieved from the source data set.
Exit-specific parameters
UEPDTPL
CICS TS for OS/390: CICS Customization Guide
34
Address of the data table user exit parameter list, which is mapped
by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table
user exit parameter list contains:
UEPDTNAM
The 8-character data table name.
UEPDTFLG
A 1-byte flag field. The possible bit settings are:
UEPDTSDT (X'80')
The exit has been invoked by CICS shared data
table support.
UEPDTCMT (X'40')
This is a CICS-maintained table. Only meaningful if
UEPDTSDT is on.
UEPDTOPT (X'20')
The exit has been invoked for table loading. This
means that optimization by skipping can be
requested.
data tables program exits
|
|
|
|
|
|
UEPDTCFT(X'10')
The exit has been invoked by coupling facility data
table support.
UEPDTUMT (X'08')
This is a user-maintained table. Only meaningful if
UEPDTSDT is on.
UEPDTRA
The address of the data record.
UEPDTRBL
The fullword length of the data table buffer.
UEPDTRL
The fullword length of the data record.
For user-maintained tables, the exit program can set a new
length in this field, if it amends the record.
UEPDTKA
The address of the data table key.
UEPDTKL
The fullword length of the data table key.
UEPDTDSL
The fullword length of the name of the source data set.
Only meaningful if either UEPDTSDT or UEPDTCFT is on.
Return codes
UERCDTAC
UERCDTRJ
UERCDTOP
XPI calls
All can be used.
UEPDTDSN
A 44-character field containing the name of the source data
set. Only meaningful if either UEPDTSDT or UEPDTCFT is
on.
UEPDTSKA
The address of a skip-key area. When invoked for table
loading, your exit program can return a key of length
UEPDTKL in this area, and request load optimization by
setting a return code of UERCDTOP. Only meaningful if
either UEPDTSDT or UEPDTCFT is on.
Add the record to the data table.
Reject the record: that is, do not add it to the table.
Skip this and the following records until a key is found that is equal
to or greater than the key specified in the skip-key area. Only
meaningful if either UEPDTSDT or UEPDTCFT is on.
Chapter 1. Global user exit programs 35
data tables program exits
Exit XDTAD
|
The XDTAD user exit is invoked when a write request is issued to a data table.
v For a user-maintained data table and coupling facility data table, the user exit is
invoked once—before the record is added to the data table.
v For a CICS-maintained data table, the user exit is invoked twice—before the
record is added to the source data set and then again before the record is added
to the data table.
The record written by the application is passed as a parameter to the user exit
program—see fields UEPDTRA and UEPDTRL. Your exit program can choose
(depending on the key value, for example—see fields UEPDTKA and UEPDTKL)
whether to include the record in the data table or not. This decision is indicated by
setting the return code.
The XDTAD exit must not modify the data in the record. If you used XDTRD to
truncate the data records when the data table was loaded, you must code your
application so that it only tries to write records of the correct format for the data
table.
A sample XDTAD exit program is listed in the
When invoked
One or more times during the processing of a write request to a data table.
Exit-specific parameters
UEPDTPL
Address of the data table user exit parameter list, which is mapped
by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table
user exit parameter list contains:
UEPDTNAM
The 8-character data table name.
UEPDTFLG
A 1-byte flag field. The possible bit settings are:
UEPDTSDT (X'80')
The exit has been invoked by CICS shared data
table support.
UEPDTCMT (X'40')
This is a CICS-maintained table. Only meaningful if
UEPDTSDT is on.
|
|
|
UEPDTCFT(X'10')
The exit has been invoked by coupling facility data
table support.
CICS Shared Data Tables Guide
.
|
|
|
UEPDTRA
UEPDTRBL
CICS TS for OS/390: CICS Customization Guide
36
UEPDTUMT (X'08')
This is a user-maintained table. Only meaningful if
UEPDTSDT is on.
The address of the data record.
The fullword length of the data table buffer.
Return codes
UERCDTAC
UERCDTRJ
XPI calls
All can be used.
data tables program exits
UEPDTRL
The fullword length of the data record.
UEPDTKA
The address of the data table key.
UEPDTKL
The fullword length of the data table key.
UEPDTDSL
The fullword length of the name of the source data set.
Only meaningful if either UEPDTSDT or UEPDTCFT is on.
UEPDTDSN
A 44-character field containing the name of the source data
set. Only meaningful if either UEPDTSDT or UEPDTCFT is
on.
Add the record to the data table.
Reject the record: that is, do not add it to the table.
Exit XDTLC
|
|
The XDTLC user exit is invoked at the completion of data table loading—whether
successful or not. The user exit is not invoked if the data table is closed for
any reason before loading is complete. The XDTLC exit is invoked for a coupling
facility data table only if the table is loaded from a source data set.
The exit program is informed if the loading did not complete successfully—see field
UEPDTORC. This could occur, for example, if the maximum number of records was
reached or there was insufficient virtual storage. In this case, the exit program can
request that the file is closed immediately, by setting the return code.
When invoked
At the completion of table loading. It is not invoked if the loading process
was terminated because the data table had been closed.
Exit-specific parameters
UEPDTPL
Address of the data table user exit parameter list, which is mapped
by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table
user exit parameter list contains:
UEPDTNAM
The 8-character data table name.
UEPDTFLG
A 1-byte flag field. The possible bit settings are:
UEPDTSDT (X'80')
The exit has been invoked by CICS shared data
table support.
Chapter 1. Global user exit programs 37
data tables program exits
UEPDTCMT (X'40')
This is a CICS-maintained table. Only meaningful if
UEPDTSDT is on.
|
|
|
|
|
|
UEPDTCFT(X'10')
The exit has been invoked by coupling facility data
table support.
UEPDTUMT (X'08')
This is a user-maintained table. Only meaningful if
UEPDTSDT is on.
UEPDTORC
Data table open result code. The possible values are:
UEPDTLCS
Load successful
UEPDTLFL
Load unsuccessful.
UEPDTDSL
The fullword length of the name of the source data set.
Only meaningful if either UEPDTSDT or UEPDTCFT is on.
UEPDTDSN
A 44-character field containing the name of the source data
set. Only meaningful if either UEPDTSDT or UEPDTCFT is
on.
Return codes
UERCDTOK
Accept the data table in its present state
XPI calls
UERCDTCL
Close the data table.
All can be used.
CICS TS for OS/390: CICS Customization Guide
38
DBCTL interface control program exit
DBCTL interface control program exit XXDFA
When invoked
By an active CICS when its connection to DBCTL fails. Your exit program is
invoked after the active CICS has informed the alternate CICS of the
failure.
Exit-specific parameters
UEPDBXR
Address of CICS XRF information for use with DBCTL. The CICS
XRF information can be mapped using the DSECT DFHDXUEP.
Return codes
UERCNOAC
Take no action.
UERCSWCH
Switch to the alternate DBCTL.
UERCABNO
Abend CICS without a dump.
UERCABDU
Abend CICS with a dump.
XPI calls
TRANSACTION_DUMP must not be used.
Chapter 1. Global user exit programs 39
DBCTL tracking program exits
DBCTL tracking program exits XXDFB and XXDTO
Exit XXDFB
When invoked
By the alternate CICS when it receives a message from the active CICS
indicating that connection to DBCTL has failed. The alternate and active
CICS systems are running in different MVS images, perhaps in different
central processing complexes (CPCs). More information about these exits is
provided in the
Exit-specific parameters
UEPDBXR
Address of CICS XRF information for use with DBCTL. The CICS
XRF information can be mapped using the DSECT DFHDXUEP.
Return codes
UERCNOAC
Take no action.
UERCSWCH
Switch to the alternate DBCTL.
UERCABNO
Abend CICS without a dump.
CICS IMS Database Control Guide
.
XPI calls
UERCABDU
Abend CICS with a dump.
The return code ‘UERCNORM’ is not available for use at this exit point.
The following must not be used:
INQUIRE_MONITORING_DATA
MONITOR
TRANSACTION_DUMP
WRITE_JOURNAL_DATA.
CICS TS for OS/390: CICS Customization Guide
40
Exit XXDTO
DBCTL tracking program exits
When invoked
By an alternate CICS when it performs takeover under the following
conditions:
v The active and alternate CICS systems are in different MVS images,
perhaps in different processors.
v The active CICS was connected to, or trying to connect to, a DBCTL
subsystem. (This does not include disconnecting from one DBCTL and
reconnecting to another.)
v The takeover was not initiated by the XXDFB exit, or the takeover was
initiated by XXDFB but the active system reestablished a DBCTL
connection before takeover occurred and XXDTO was driven for a new
DBCTL takeover decision.
Exit-specific parameters
UEPDBXR
Address of CICS XRF information for use with DBCTL. The CICS
XRF information can be mapped using the DSECT DFHDXUEP.
Return codes
UERCNOAC
Take no action.
XPI calls
UERCSWCH
Switch to the alternate DBCTL.
UERCABNO
Abend CICS without a dump.
UERCABDU
Abend CICS with a dump.
The return code UERCNORM is not available for use at this exit point.
The following must not be used:
INQUIRE_MONITORING_DATA
MONITOR
TRANSACTION_DUMP
WRITE_JOURNAL_DATA.
Chapter 1. Global user exit programs 41
dispatcher domain exits
Dispatcher domain exits XDSBWT and XDSAWT
The XDSBWT and XDSAWT exit points are located before and after the operating
system wait. CICS services cannot be used in any exit program invoked from these
exit points.
The XDSBWT and XDSAWT exits can be used to control the swapping state of the
CICS address-space. It should be noted, however, that if the default state of the
address-space is non-swappable then these exits cannot be used to override this
state.
CICS uses a counter which is incremented for every SYSEVENT DONTSWAP
request and decremented for every SYSEVENT OKSWAP request down to a
minimum of 0. A SYSEVENT DONTSWAP request is issued when this counter goes
up from 0 to 1. A SYSEVENT OKSWAP request is issued when this counter goes
down from 1 to 0. In all other circumstances, the SYSEVENT is not issued.
Exit XDSBWT
When invoked
Before an operating system wait issued by the quasireentrant CICS TCB.
Exit-specific parameters
None.
Exit XDSAWT
Return codes
UERCNORM
Continue processing.
UERCSWAP
Issue SYSEVENT to allow address-space swapping.
XPI calls
Must not be used.
When invoked
After an operating system wait issued by the quasireentrant CICS TCB.
Exit-specific parameters
UEPSYSRC
Address of the 4-byte return code from the SYSEVENT request
made before the operating system wait. This return code will be in
one of two different forms:
1. The SYSEVENT OKSWAP return code, or
2. If the SYSEVENT request was rejected by CICS, a special
CICS return code which will take one of the following fullword
decimal values:
CICS TS for OS/390: CICS Customization Guide
42
17 The SYSEVENT OKSWAP was not issued. The
outstanding count of SYSEVENT OKSWAP requests
exceeds the count of SYSEVENT DONTSWAP
requests. Before a SYSEVENT OKSWAP can be
issued, a SYSEVENT DONTSWAP must be requested.
19 The SYSEVENT OKSWAP was not issued. The
outstanding count of SYSEVENT DONTSWAP requests
Return codes
UERCNORM
UERCNOSW
XPI calls
Must not be used.
dispatcher domain exits
still exceeds the count of SYSEVENT OKSWAPs.
Further SYSEVENT OKSWAPs must be requested
before a SYSEVENT OKSWAP is issued by CICS.
Continue processing.
Issue SYSEVENT to suppress address-space swapping.
Chapter 1. Global user exit programs 43
DL/I interface program exits
DL/I interface program exits XDLIPRE and XDLIPOST
The XDLIPRE and XDLIPOST exit points are invoked following the issue of an
EXEC DLI command or DL/I call. Exit XDLIPRE is invoked before the request is
processed and XDLIPOST is invoked after the request is processed.
When the request is function shipped, the exits are invoked from both the
application-owning region and the database-owning region. However, there are
restrictions when they are invoked in a database-owning region, as described
below.
CICS IMS Database Control Guide
The
XDLIPRE exit.
Notes:
1. The descriptions of the exits that follow show the general format of the
application’s parameter list. For detailed information about the format of the
CALL-level DL/I parameter list, refer to the
DL/I Calls
2. For all EXEC DLI calls, the application’s parameter list is in assembler-language
format (that is, the value of the program language byte pointed to by UEPLANG
is always UEPASM, and the parameter list pointed to by UEPAPLIST is always
in assembler-language format). This is because all EXEC DLI calls are
converted into assembler-language CALL-level requests.
3. In an XDLIPRE exit program you can change the PSB name and the SYSID
name. This helps availability if the originally specified SYSID fails.
You can change the SYSID from:
v A remote value to another remote value
v The local value to a remote value
v A remote value to the local value.
Changing the SYSID has an effect only if the associated PSB has a PDIR entry.
The SYSID may be the local CICS (that is, the SYSIDNT specified on the CICS
region) or a remote connection name. For the new SYSID to be used, the PSB
name must have a PDIR entry; if it does not have a PDIR entry, the assumption
is made that the local CICS is connected to DBCTL, and an attempt is made to
run the IMS™ request there. An IMS schedule failure is handled in the same
way as a failure to route to a connection that does not exist. If the SYSID is
changed to either the same value as the SYSIDNT of the local CICS or blanks
(hex ’40404040’), CICS attempts to run the IMS request on the local system.
manual.
contains a sample program for the
IMS/ESA Application Programming:
CICS TS for OS/390: CICS Customization Guide
44
Exit XDLIPRE
DL/I interface program exits
When invoked
On entry to the DL/I interface program.
Exit-specific parameters
UEPCTYPE
Address of type-of-request byte. Values are:
UEPCEXEC
The original request was an EXEC DLI request.
UEPCCALL
The original request was a CALL-level request.
UEPCSHIP
The request has been function shipped from another region.
When this value is set, restrictions apply to the setting and
use of the rest of the exit parameters, as described below.
UEPAPLIST
Address of application’s parameter list. The general format for
COBOL and assembler language is:
plist address --> parm1 address --> parm1
parm2 address --> parm2
parm3 address --> parm3
..............
up to a maximum of 18 parameters
excluding the optional parmcount.
The general format for PL/I is:
plist address --> parm1 address --> parm1 (parmcount)
parm2 address --> locator descriptor --> parm2
parm3 address --> locator descriptor --> parm3
..............
up to a maximum of 18 parameters
When UEPCTYPE is not UEPCSHIP, your exit program can change any of
the parameters in the application parameter list. For UEPCSHIP requests,
your exit program cannot change any of the parameters. Furthermore, for
UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in
the above format, but which contains only the first two parameters, parm1
and parm2.
Note: For PL/I applications, parm1 may or may not contain a
parameter-count. Your exit program should check this field before
using it.
UEPLANG
Address of program language byte. Values are:
UEPPLI
PL/I
UEPCBL
COBOL
UEPASM
Assembler language.
For UEPCSHIP requests, the language is always assembler.
Chapter 1. Global user exit programs 45
DL/I interface program exits
UEPIOAX
Address of I/O area existence flag byte:
UEPIOA1
I/O area exists.
For UEPCSHIP requests, the I/O area existence flag is
always off.
UEPIOA
Address of I/O area. This is the application’s IOAREA, or
DFHEDP’s IOAREA in the case of EXEC DLI. The contents
of the IOAREA can be overwritten in the exit: the new
contents are used when the DL/I request is processed.
However, it should be noted that IOAREAs can be in a
program’s static storage and, in this case, should not be
overwritten.
For UEPCSHIP requests, UEPIOA is always zero.
UEPPSBNX
Address of PSB existence flag byte:
UEPPSB1
A PSB exists.
Return codes
UERCNORM
UERCBYP
UERCPURG
UEPPSBNM
Address of an area containing the 8-character PSB name.
The contents of the area can be overwritten by the exit, for
all types of request including UEPCSHIP; the new contents
are used when the DL/I request is processed.
UEPSYSDX
Address of the SYSID existence flag byte:
UEPSYS1
A SYSID exists.
UEPSYSID
Address of an area containing the 4-character SYSID name.
The contents of the area can be overwritten by the exit, for
all types of request including UEPCSHIP; the new contents
are used when the DL/I request is processed.
Continue processing
Bypass DL/I request and return
Task purged during XPI call.
XPI calls
All can be used.
CICS TS for OS/390: CICS Customization Guide
46
Exit XDLIPOST
DL/I interface program exits
When invoked
On exit from the DL/I interface program.
Exit-specific parameters
UEPCTYPE
Address of type-of-request byte. Values are:
UEPCEXEC
An EXEC DLI request.
UEPCCALL
A CALL-level request.
UEPCSHIP
The request has been function shipped from another region.
When this value is set, restrictions apply to the setting and
use of the rest of the exit parameters, as described below.
UEPAPLIST
Address of application’s parameter list. The general format for
COBOL and assembler language is:
plist address --> parm1 address --> parm1
parm2 address --> parm2
parm3 address --> parm3
..............
up to a maximum of 18 parameters
excluding the optional parmcount.
The general format for PL/I is:
plist address --> parm1 address --> parm1 (parmcount)
parm2 address --> locator descriptor --> parm2
parm3 address --> locator descriptor --> parm3
..............
up to a maximum of 18 parameters.
When UEPCTYPE is not UEPCSHIP, your exit program can change any of
the parameters in the application parameter list. For UEPCSHIP requests,
your exit program cannot change any of the parameters. Furthermore, for
UEPCSHIP requests, UEPAPLIST points to a copy of the parameter list in
the above format, but which contains only the first two parameters parm1
and parm2. See also the notes on page 44.
Note: For PL/I applications, parm1 may or may not contain a
parameter-count. Your exit program should check this field before
using it.
UEPLANG
Address of program language byte. Its values are:
UEPPLI
PL/I
UEPCBL
COBOL
UEPASM
Assembler language.
For UEPCSHIP requests, the language is always assembler.
Chapter 1. Global user exit programs 47
DL/I interface program exits
UEPIOAX
Address of I/O area existence flag byte:
UEPIOA1
I/O area exists.
For UEPCSHIP requests, the I/O area existence flag is
always off.
UEPIOA
Address of I/O area. This is the application’s IOAREA, or
DFHEDP’s IOAREA in the case of EXEC DLI. The contents
of the IOAREA can be overwritten in the exit and are
returned to the application program in the new form.
However, it should be noted that the application’s IOAREA
could be in the program’s static storage and, in this case,
should not be overwritten.
For UEPCSHIP requests, UEPIOA is always zero.
UEPUIBX
Address of UIB existence flag byte:
UEPUIB1
a UIB exists.
Return codes
UERCNORM
UERCPURG
XPI calls
All can be used.
UEPUIB
Address of the UIB, which is mapped by DFHUIB in module
DFHDBCOP. The contents of the UIB can be overwritten in
the exit for all types of request, including UEPCSHIP. The
new contents are returned to the application or to the region
that function shipped the request.
Continue processing.
Task purged during XPI call.
CICS TS for OS/390: CICS Customization Guide
48
dump domain exits
Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT
There are four exits in the dump domain.
Exit XDUREQ
When invoked
Immediately before a system or transaction dump is taken.
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Address of the 4-byte terminal ID.
UEPPROG
Address of the 8-byte application program name, or nulls if there is
no current application.
UEPDUMPC
Address of copy of the 8-byte dump code.
UEPABCDE
Address of a copy of the 8-byte Kernel error code in the format
xxx/yyyy. xxx denotes the 3-digit hexadecimal MVS completion code
(for example 0C1 or D37). If an MVS completion code is not
applicable, xxx is three hyphens. The 4-digit code yyyy is a user
abend code produced either by CICS or by another product on your
system. UEPABCDE is completed only for abend codes
corresponding to the following dump codes:
Otherwise this field contains null characters.
UEPDUMPT
Address of the 1-byte dump-type identifier, which contains one of
the following values:
UEPDTRAN
UEPDSYST
AP0001
SR0001
ASRA
ASRB
ASRD
A transaction dump was requested.
A system dump was requested.
Note: The dump-type identifier indicates the type of dump request
that was passed to the dump domain. It does not reflect any
modification that may have been made to the original
request by a user entry in the dump table.
Chapter 1. Global user exit programs 49
dump domain exits
UEPXDSCP
Address of a 1-byte field indicating the current dump table
DUMPSCOPE setting. It contains one of the following values:
UEPXDLOC
A system dump will be taken on the local MVS image only.
UEPXDREL
System dumps will be taken on both the local MVS image,
and on related MVS images within the sysplex.
This field may be modified by the exit to update the dump table
DUMPSCOPE setting.
UEPXDTXN
Address of a 1-byte field indicating the current dump table
TRANDUMP setting. It contains one of the following values:
UEPXDYES
A transaction dump will be taken.
UEPXDNO
A transaction dump will not be taken.
This field may be modified by the exit to update the dump table
TRANDUMP setting.
Note: This field is only valid if UEPDUMPT contains the value
UEPXDSYS
Address of a 1-byte field indicating the current dump table
SYSDUMP setting. It contains one of the following values:
UEPXDYES
UEPXDNO
This field may be modified by the exit to update the dump table
SYSDUMP setting.
UEPXDTRM
Address of a 1-byte field indicating the current dump table
SHUTDOWN setting. It contains one of the following values:
UEPXDYES
UEPXDNO
This field may be modified by the exit to update the dump table
SHUTDOWN setting.
UEPDTRAN.
A system dump will be taken.
A system dump will not be taken.
The CICS system is to shutdown.
The CICS system is not to shutdown.
UEPXDMAX
CICS TS for OS/390: CICS Customization Guide
50
Address of a 4-byte field which contains the current dump table
MAXIMUM setting. This field may be modified by the exit to change
the current dump table MAXIMUM setting. A change to the
MAXIMUM setting will not suppress this dump request. A return
code of UERCBYP may be used to suppress the current dump
request.
UEPDXDCNT
Address of a 4-byte field which contains the current dump table
CURRENT setting.
UEPXDTST
Address of a 16-byte field which contains the current dump table
statistics for this dump code. The addressed field consists of four
4-byte fields containing binary integers:
Number of transaction dumps taken
Number of transaction dumps suppressed
Number of system dumps taken
Number of system dumps suppressed
Note: Statistics for transaction dumps are valid only if UEPDUMPT
UEPXDDAE
Address of a 1-byte field which represents the current dump table
DAEOPTION setting. It contains one of the following values:
dump domain exits
contains the value UEPDTRAN.
UEPXDYES
UEPXDNO
This field may be modified by the exit to update the dump table
DAEOPTION setting.
UEPDMPID
Address of a 9-character field in the format xxxx/xxxx, containing
the dump identifier. The dump ID is the same as that output by the
corresponding dump message.
UEPFMOD
Address of an 8-byte area containing, if the dump code is AP0001,
the name of the failing module; otherwise null characters.
Note that field UEPPROG always addresses the name of the
current
UEPFMOD addresses the name of the module where the failure
occurred, if known.
If the dump code is AP0001, there are three possibilities:
1. The field addressed by UEPFMOD contains the same name as
2. The field addressed by UEPFMOD contains a different name
3. The field addressed by UEPFMOD contains '????????'—the
The dump is eligible for DAE suppression.
The dump will not be suppressed by DAE.
application, regardless of where the failure occurred.
the field addressed by UEPPROG—the failure occured in
application code.
from the field addressed by UEPPROG—the failure occurred in
non-application code.
failure was not in application code, but CICS was unable to
determine the name of the failing module.
Chapter 1. Global user exit programs 51
dump domain exits
Return codes
UERCNORM
Continue processing.
UERCBYP
Suppress dump.
UERCPURG
Task purged during XPI call.
XPI calls
WAIT_MVS can be used only when a UEPDUMPT indicates that a
transaction dump is being taken. Do not use any other calls.
The sample program for the XDUREQ exit, DFH$XDRQ
CICS supplies a sample program for the XDUREQ exit. The sample shows you how
to manipulate the dump table entry, and how to permit or suppress the dump.
Exit XDUREQC
When invoked
Immediately after a system or transaction dump has been taken (or has
failed or been suppressed).
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Address of the 4-byte terminal ID.
UEPPROG
Address of the 8-byte application program name.
UEPDUMPC
Address of copy of the 8-byte dump code.
UEPABCDE
Address of a copy of the 8-byte Kernel error code in the format
xxx/yyyy. xxx denotes the 3-digit hexadecimal MVS completion code
(for example X'0C1' or X'D37'). If an MVS completion code is not
applicable, xxx is three hyphens. The 4-digit code yyyy is a user
abend code produced either by CICS or by another product on your
system. UEPABCDE is completed only for abend codes
corresponding to the following dump codes:
AP0001
SR0001
ASRA
ASRB
ASRD
CICS TS for OS/390: CICS Customization Guide
52
Otherwise this field contains null characters.
UEPDUMPT
Address of the 1-byte dump-type identifier, which contains one of
the following values:
UEPDTRAN
UEPDSYST
Note: The dump-type identifier indicates the type of dump request
UEPXDSCP
Address of a 1-byte field indicating the current dump table
DUMPSCOPE setting. It contains one of the following values:
UEPXDLOC
UEPXDREL
dump domain exits
A transaction dump was requested.
A system dump was requested.
that was passed to the dump domain. It does not reflect any
modification that may have been made to the original
request by a user entry in the dump table.
A system dump will be taken on the local MVS image only.
System dumps will be taken on both the local MVS image,
and on related MVS images within the sysplex.
This field may be modified by the exit to update the dump table
DUMPSCOPE setting.
UEPXDTXN
Address of a 1-byte field indicating the current dump table
TRANDUMP setting. It contains one of the following values:
UEPXDYES
UEPXDNO
This field may be modified by the exit to update the dump table
TRANDUMP setting.
Note: This field is only valid if UEPDUMPT contains the value
UEPXDSYS
Address of a 1-byte field indicating the current dump table
SYSDUMP setting. It contains one of the following values:
UEPXDYES
UEPXDNO
A transaction dump will be taken.
A transaction dump will not be taken.
UEPDTRAN.
A system dump will be taken.
A system dump will not be taken.
This field may be modified by the exit to update the dump table
SYSDUMP setting.
UEPXDTRM
Address of a 1-byte field indicating the current dump table
SHUTDOWN setting. It contains one of the following values:
Chapter 1. Global user exit programs 53
dump domain exits
UEPXDYES
The CICS system is to shutdown.
UEPXDNO
The CICS system is not to shutdown.
This field may be modified by the exit to update the dump table
SHUTDOWN setting.
UEPXDMAX
Address of a 4-byte field which contains the current dump table
MAXIMUM setting. This field may be modified by the exit to change
the current dump table MAXIMUM setting.
UEPDXDCNT
Address of a 4-byte field which contains the current dump table
CURRENT setting.
UEPXDTST
Address of a 16-byte field which contains the current dump table
statistics for this dumpcode. The addressed field consists of four
4-byte fields containing binary integers:
Number of transaction dumps taken
Number of transaction dumps suppressed
Number of system dumps taken
Number of system dumps suppressed.
UEPXDDAE
UEPDMPID
UEPDRESP
UEPDREAS
Return codes
Note: Statistics for transactions dumps are valid only if
UEPDUMPT contains the value UEPDTRAN.
Address of a 1-byte field which represents the current dump table
DAEOPTION setting. It contains one of the following values:
UEPXDYES
The dump was suppressed by DAE.
UEPXDNO
The dump was not suppressed by DAE.
This field may be modified by the exit to update the dump table
DAEOPTION setting.
Address of a 9-character field in the format xxxx/xxxx, containing
the dump identifier. The dump ID is the same as that output by the
corresponding dump message.
Address of the 2-byte dump response code.
Address of the 2-byte dump reason code.
UERCNORM
CICS TS for OS/390: CICS Customization Guide
54
Continue processing.
Exit XDUCLSE
dump domain exits
XPI calls
WAIT_MVS can be used only when a UEPDUMPT indicates that a
transaction dump is being taken. Do not use any other calls.
When invoked
Immediately after a transaction dump data set has been closed.
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Address of the 4-byte terminal ID.
UEPPROG
Address of the 8-byte application program name.
UEPDMPDD
Address of the 8-byte dump data set ddname.
UEPDMPDSN
Address of the 44-byte dump data set dsname.
Exit XDUOUT
Return codes
UERCNORM
Continue processing.
UERCSWCH
The autoswitch flag is set on.
XPI calls
WAIT_MVS can be used. Do not use any other calls.
When invoked
Before a record is written to the transaction dump data set.
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Address of the 4-byte terminal ID.
UEPPROG
Address of the 8-byte application program name.
UEPDMPFC
Address of the 1-byte function code. The equated values are:
UEPDMPWR
Buffer is about to be written.
Chapter 1. Global user exit programs 55
dump domain exits
UEPDMPRE
Dump is about to restart after autoswitch.
UEPDMPAB
Abnormal termination of dump.
UEPDMPDY
Buffer is about to be written, and the CICS dump data set is
a dummy file or is closed.
UEPDMPBF
Address of the dump buffer, whose length is addressed by the
parameter UEPDMPLEN.
UEPDMPLEN
Address of the 2-byte dump-buffer length.
Return codes
UERCNORM
Continue processing.
UERCBYP
Suppress dump record output.
XPI calls
WAIT_MVS can be used. Do not use any other calls.
CICS TS for OS/390: CICS Customization Guide
56
enqueue EXEC interface program exits
Enqueue EXEC interface program exits XNQEREQ and XNQEREQC
The XNQEREQ exit allows you to intercept enqueue API requests before any action
has been taken on the request. The XNQEREQC exit allows you to intercept the
response after an enqueue API request has completed.
The API requests affected are:
v EXEC CICS ENQ
v EXEC CICS DEQ.
Using XNQEREQ, you can:
v Analyze the API parameter list (function, keywords, argument values, and
responses).
v Modify any input parameter value prior to execution of a request.
v Prevent execution of a request. This enables you to replace the CICS function
with your own processing.
Using XNQEREQC, you can analyze the API parameter list.
You can also:
v Pass data between your XNQEREQ and XNQEREQC exit programs when they
are invoked for the same request
v Pass data between your enqueue exit programs when they are invoked within
the same task.
Exit XNQEREQ
|
|
When invoked
Before CICS processes an EXEC CICS ENQ or DEQ request, or attempts
to match it to an installed ENQMODEL resource definition.
Exit-specific parameters
UEPCLPS
Address of a copy of the command parameter list. See “The
command-level parameter structure” on page 59.
UEPNQTOK
Address of a 4-byte area which can be used to pass information
between XNQEREQ and XNQEREQC for a single enqueue
request.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code
EIBRCODE. For details of EIB return codes, see the
Application Programming Reference
UEPRESP
Address of a 4-byte binary copy of the EIB response code
EIBRESP.
UEPRESP2
Address of a 4-byte binary copy of the EIB response code
EIBRESP2.
CICS
manual.
UEPTSTOK
Address of a 4-byte token which can be used to pass information
Chapter 1. Global user exit programs 57
enqueue EXEC interface program exits
between successive enqueue requests within the same task (for
example, between successive invocations of the XNQEREQ exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0
when the exit is first invoked, and is incremented for each recursive
call.
|
|
Exit XNQEREQC
UEPSCOPE
Address of the 4-byte ENQSCOPE name to be used.
Return codes
UERCBYP
Bypass this request.
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
API and SPI commands
All can be used.
Note: Take care when issuing recursive commands. For example, you must avoid
entering a loop when issuing an enqueue request from the XNQEREQ exit.
Use of the recursion counter UEPRECUR is recommended.
When invoked
After an enqueue API request has completed, before return from the
enqueue EXEC interface program.
Exit-specific parameters
UEPCLPS
UEPNQTOK
UEPRCODE
UEPRESP
UEPRESP2
CICS TS for OS/390: CICS Customization Guide
58
Address of a copy of the command parameter list. See “The
command-level parameter structure” on page 59.
Address of a 4-byte area which can be used to pass information
between XNQEREQ and XNQEREQC for a single enqueue
request.
Address of a 6-byte hexadecimal copy of the EIB return code
EIBRCODE. For details of EIB return codes, see the
Application Programming Reference
Address of a 4-byte binary copy of the EIB response code
EIBRESP.
Address of a 4-byte binary copy of the EIB response code
EIBRESP2.
manual.
CICS
UEPTSTOK
Address of a 4-byte token which can be used to pass information
between successive enqueue requests within the same task (for
example, between successive invocations of the XNQEREQC exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0
when the exit is first invoked, and is incremented for each recursive
call.
enqueue EXEC interface program exits
|
|
Return codes
XPI calls
API and SPI commands
You can update the copies of EIBRCODE, EIBRESP, and EIBRESP2 that you are
given in the parameter list. If you update the values, CICS copies the new values
into the application program’s EIB after the completion of XNQEREQC or if you
specify a return code of UERCBYP in XNQEREQ.
You must set valid enqueue responses. You must set all three of EIBRCODE,
EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by
the enqueue domain to describe a valid completion. CICS does not check the
consistency of EIBRCODE, EIBRESP, and EIBRESP2. If EIBRCODE is set to a
non-zero value and EIBRESP is set to zero, CICS will override EIBRESP with a
non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2,
the values used by the enqueue domain are specified in DSECT DFHNQUED.
UEPSCOPE
Address of the 4-byte ENQSCOPE name used.
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
All can be used.
All can be used.
Note: Take care when issuing recursive commands not to cause a loop. For
example, it is your responsibility to avoid entering a loop when issuing an
enqueue request from the XNQEREQC exit. Use of the recursion counter
UEPRECUR is recommended.
The command-level parameter structure
The command-level parameter structure consists of a series of addresses. The first
address points to the EXEC interface descriptor (EID), which consists of a bit string
that describes the type of request and identifies each keyword specified with the
request. The remaining addresses point to pieces of data associated with the
request.
You can examine the EID to determine the type of request and the keywords
specified. You can examine the other parameters in the list to determine the values
of the keywords. You can also modify values of keywords specified on the request.
Chapter 1. Global user exit programs 59
enqueue EXEC interface program exits
End of parameter list indicator
The high-order bit is set on in the last address set in the parameter list to
indicate that it is the last one in the list. On return from your user exit program,
CICS scans the parameter list for the high-order bit to find the last parameter.
Therefore, if you modify the length of the parameter list, you must also reset
the high-order bit to indicate which is the new last address.
The UEPCLPS exit-specific parameter
The UEPCLPS exit-specific parameter is included in both exit XNQEREQ and exit
XNQEREQC. It is the address of the command-level parameter structure. The
command-level parameter structure contains four addresses, NQ_ADDR0 through
NQ_ADDR3. It is defined in the DSECT NQ_ADDR_LIST, which you should copy
into your exit program by including the statement COPY DFHNQUED.
The command-level parameter list is made up as follows.
Note: The relationship between arguments, keywords, data types, and input/output
types is summarized for the enqueue commands in Table 3 on page 62.
NQ_ADDR0
is the address of a 9-byte area called the EID, which is made up as follows:
NQ_GROUP
NQ_FUNCT
NQ_BITS1
NQ_BITS2
NQ_EIDOPT5
NQ_EIDOPT6
NQ_EIDOPT7
NQ_EIDOPT8
NQ_GROUP
Always X'12', indicating that this is a task control request.
NQ_FUNCT
One byte that defines the type of request:
X'04' ENQ
X'06' DEQ
NQ_BITS1
Existence bits that define which arguments were specified. To obtain
the argument associated with a keyword, you need to use the
appropriate address from the command-level parameter structure.
Before using this address, you must check the associated existence bit.
If the existence bit is set off, the argument was not specified in the
request and the address should not be used.
CICS TS for OS/390: CICS Customization Guide
60
X'80' Set if the request contains an argument for the RESOURCE
keyword. If set, NQ_ADDR1 is meaningful.
X'40' Set if the request contains an argument for the LENGTH
keyword. If set, NQ_ADDR2 is meaningful.
enqueue EXEC interface program exits
X'20' Set if the request contains an argument for the MAXLIFETIME
keyword. If set, NQ_ADDR3 is meaningful.
NQ_BITS2
Two bytes not used by the enqueue domain.
NQ_EIDOPT5
One byte not used by the enqueue domain.
NQ_EIDOPT6
One byte not used by the enqueue domain.
NQ_EIDOPT7
One byte not used by the enqueue domain.
NQ_EIDOPT8
Indicates whether certain keywords were specified on the request.
X'04' NOSUSPEND was specified.
X'02' DEQ was specified.
X'01' ENQ was specified.
NQ_ADDR1
is the address of an area containing the value from RESOURCE.
NQ_ADDR2
is the address of the halfword value of LENGTH.
NQ_ADDR3
is the address of the fullword value of MAXLIFETIME.
Modifying fields in the command-level parameter structure
The fields that are passed to the enqueue domain are used as input to the request.
The correct method of modifying an input field is to create a new copy of it, and to
change the address in the command-level parameter list to point to your new data.
Notes:
1. You must never modify an input field by altering the data that is pointed to by
the command-level parameter list. To do so would corrupt storage belonging to
the application program and would cause a failure when the program attempted
to reuse the field.
2. There are no output fields on EXEC CICS ENQ and DEQ requests.
Modifying the EID
It is not possible to modify the EID to make major changes to requests. It is not
possible, for example, to change an ENQ request to a DEQ request. However, you
can make minor changes to requests, such as to turn on the existence bit for
LENGTH. The list that follows shows the bits in the EID that can be modified. Any
attempt to modify any other part of the EID is ignored.
NQ_BITS1
X'40' The existence bit for LENGTH
X'20' The existence bit for MAXLIFETIME.
NQ_EIDOPT7
A user exit program at XNQEREQ can set the following on or off for ENQ
commands:
Chapter 1. Global user exit programs 61
enqueue EXEC interface program exits
X'04' The existence bit for NOSUSPEND.
The EID is reset to its original value before return to the application program. That
is, changes made to the EID are retained for the duration of the enqueue request
only.
Note: Your user exit program is prevented from making major changes to the EID.
However, you must take great care when making the minor modifications
that are permitted.
Use of the task token UEPTSTOK
UEPTSTOK provides the address of a 4-byte area that you can use to pass
information between successive enqueue requests in the same task. (By contrast,
UEPNQTOK is usable only for the duration of a single enqueue request, because
its contents may be destroyed at the end of the request.) For example, if you need
to pass information between successive invocations of the XNQEREQ exit,
UEPTSTOK provides a means of doing this.
Table 3. User arguments and associated keywords, data types, and input/output types
Argument Keyword Data type Input/output type
Arg1 RESOURCE DATA-AREA input
Arg2 LENGTH BIN(15) input
Arg3 MAXLIFETIME CVDA input
Modifying user arguments
User exit programs can modify user input arguments by:
1. Obtaining sufficient storage to hold the modified argument
2. Setting the storage to the required value
3. Setting the associated pointer in the parameter list to the address of the
newly-acquired area.
Notes:
1. CICS does not check changes to argument values, so any changes must be
verified by the user exit program making the changes.
2. It is not advisable for XNQEREQC to modify input arguments.
Adding user arguments
Global user exit programs can add arguments associated with the LENGTH and
MAXLIFETIME keywords. You must ensure that the arguments you specify or
modify in your exit programs are valid. The valid values for MAXLIFETIME are
DFHVALUE(TASK) and DFHVALUE(UOW), which are 233 and 246 respectively.
Assuming that the argument to be added does not already exist, the user exit
program must:
1. Obtain storage for the argument to be added
2. Initialize the storage to the required value
3. Select and set up the appropriate pointer from the parameter list
4. Select and set up the appropriate argument existence bit in the EID
5. Modify the parameter list to reflect the new end of list indicator.
CICS TS for OS/390: CICS Customization Guide
62
Removing user arguments
User exit programs can remove arguments (for which the program is totally
responsible) associated with the LENGTH and MAXLIFETIME keywords:
Assuming that the argument to be removed exists, the user exit program must:
1. Switch the corresponding argument existence bit to ’0’b in the EID
2. Modify the parameter list to reflect the new end of list indicator.
Sample exit program, DFH$XNQE
enqueue EXEC interface program exits
|
|
CICS supplies a sample exit program, DFH$XNQE, for the XNQEREQ exit.
The program gives examples of:
v Coding Exec Interface Global User Exits
v Issuing a mixture of XPI and EXEC CICS API calls within Global User Exits
v Three methods of adding a SCOPE value to exec ENQ and DEQ requests, so
that they apply to multiple regions within the Sysplex. Methods A and B force a
match to an installed ENQMODEL resource definition. Method C bypasses the
use of ENQMODEL resource definitions even if there would have been a match.
The methods are:
Method A
Prefix the Resource name with a 1- to 255-character value (this sample
uses a 4-character value) for the ENQNAME on the ENQMODEL
resource definition to which you wish to force a match. The exit
terminates and processing continues as though the chosen ENQMODEL
had been matched normally. The scope is then supplied by the matched
ENQMODEL definition.
This method applies only to resource names shorter than 255-n (where n
is the length of you chosen prefix).
Method B
Similar to method A, but you replace the first 1- to 8-characters of the
resource name with your chosen string instead of prefixing it. This
method:
– applies only to resource names of length equal to or greater than that
of your replacement string.
– is an alternative to method A when a resource name too long to allow
the use of that method.
Method C
Place a 4-character Scope value in UEPSCOPE, and return UERCSCPE
in R15. This will bypass any installed ENQMODEL resource definition,
forcing a Sysplex Scope ENQ/DEQ request.
This method is not recommended if you have an ENQMODEL table,
because the latter is designed to preserve data integrity by preventing
the possibility of a region scope enqueue and a sysplex scope enqueue
(or two sysplex scope enqueues with different scopes) existing for the
same resource. (Because sysplex and region scope enqueues use
separate namespaces, a region scope enqueue will never wait on a
sysplex enqueue, nor will a sysplex scope enqueue wait on a region
enqueue.)
Chapter 1. Global user exit programs 63
enqueue EXEC interface program exits
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Notes about the use of XNQEREQ to alter ENQ or DEQ scope.
1. XNQEREQ enables you to allow existing applications to be converted to use
sysplex enqueues without changing the application.
Note: Use of either the ENQMODEL resource definition or the user exit allows
this in most cases, but those applications where the resource name is
determined dynamically and not known in advance can only be so
converted by use of this exit.
2. Sysplex and region scope enqueues use separate namespaces. A region scope
enqueue will never wait on a sysplex enqueue, nor will a sysplex scope
enqueue wait on a region enqueue.
Note: This situation can only arise when you use the exit. Use of the
ENQMODEL resource definitions as your only method of defining the
SCOPE of an ENQ or DEQ avoids this potential risk.
3. Both region and sysplex scope are supported for string ENQs, but sysplex
scope is not supported for address ENQs.
CICS TS for OS/390: CICS Customization Guide
64
EXEC interface program exits
EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT
There are four global user exit points in the EXEC interface program:
XEIIN Invoked before the execution of any EXEC CICS application programming
interface (API) or system programming interface (SPI) command.
XEISPIN
Invoked before the execution of any EXEC CICS SPI command
v EXEC CICS ENABLE
v EXEC CICS DISABLE
v EXEC CICS EXTRACT EXIT.
The sequence is:
TRACE – XEIIN – XEISPIN – EDF – command
XEIOUT
Invoked after the execution of any EXEC CICS API or SPI command.
XEISPOUT
Invoked after the execution of any EXEC CICS SPI command
listed for XEISPIN.
except
except
:
those
The sequence is:
command – EDF – XEISPOUT – XEIOUT – TRACE
Note: Asynchronous processing of these exits may occur if the transaction is
suspended (for example, during file I/O wait). This situation may also occur
under CEDF because CEDF issues its own EXEC CICS commands between
the application’s XEISPIN and XEISPOUT exits.
If, for example, the same GWA is shared between the XEIIN and XEIOUT
exits, you must allow for the possibility of asynchronous processing, in order
to ensure integrity of the data and to prevent unpredictable results.
On entry to the exits, the exit-specific parameter UEPARG contains the address of
the command parameter list.
The command parameter list
The first parameter in the list points to a string of data known as argument 0. The
other parameters point to the values specified for the parameters passed on the
command.
Argument 0 begins with a 2-byte function code that identifies the command.
(Function codes are documented in Appendix A of the
Programming Reference
Programming Reference
containing “existence bits” which indicate whether arguments are passed on the
command. For example, consider the command:
EXEC CICS LINK PROGRAM(‘MYPROG’)
CICS Application
manual and in Appendix B of the
manual.) The function code is followed by a 2-byte field
CICS System
Here, argument 0 begins with the function code X'0E02' (LINK). Existence bit 1 is
set, indicating that there is an argument 1 (namely, ‘MYPROG’).
Chapter 1. Global user exit programs 65
EXEC interface program exits
The correspondence between command parameters (such as PROGRAM) and their
positions and values in the parameter list (in this case, argument 1, ‘MYPROG’) can
be deduced from the translated code for the particular command.
Important
Modifying CICS commands by tampering with argument 0 is
and leads to unexpected errors or results.
For example, if an application program is written in assembler or PL/I and you
modify argument 0, you will be writing to program storage (that is, storage
occupied by the program itself), which could cause 0C4 abends. Furthermore,
modifying argument 0 not only alters the CICS command for
the command in the application program, it changes the CICS command in the
virtual storage copy of the application program. This means that the next task
to invoke the same copy of the program will also execute the modified
command.
This particular example of the danger of tampering with argument 0 does not
apply to COBOL or C/370™ application programs, but nevertheless you
should not modify CICS commands for application programs written in any
supported language.
not
supported,
this execution
of
Bypassing commands
An XEIIN or XEISPIN exit program can bypass execution of a command by setting
the UERCBYP return code. If it does this, EDF is not invoked, but XEISPOUT,
XEIOUT, and exit trace are invoked if they are active.
Bypassing an EXEC CICS command allows an exit program to replace the CICS
function with its own processing, for example.
Before setting UERCBYP, your program should check the value pointed to by
UEPPGM, to ensure that it is not bypassing an EXEC CICS command issued by
CICS.
Exit XEIIN
When invoked
Before the execution of any EXEC CICS API or SPI command.
Exit-specific parameters
UEPARG
UEPEXECB
UEPUSID
Address of the EXEC command parameter list.
Address of the system EIB.
Address of the 8-character userid.
UEPPGM
UEPLOAD
CICS TS for OS/390: CICS Customization Guide
66
Address of the 8-character application program name.
Address of the application program’s load-point.
Exit XEISPIN
UEPRSA
Return codes
UERCNORM
UERCBYP
UERCPURG
XPI calls
All can be used.
When invoked
Before the execution of any EXEC CICS SPI command
v EXEC CICS ENABLE
v EXEC CICS DISABLE
v EXEC CICS EXTRACT EXIT.
EXEC interface program exits
Address of the application’s register save area. This contains the
contents of the registers at the point when the program issued the
EXEC CICS command.
Continue processing.
Bypass the execution of this command.
Task purged during XPI call.
except
:
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
UEPPGM
Address of the 8-character application program name.
UEPLOAD
Address of the application program’s load-point.
UEPRSA
Address of the application’s register save area. This contains the
contents of the registers at the point when the program issued the
EXEC CICS command.
Return codes
UERCNORM
Continue processing.
UERCBYP
Bypass the execution of this command.
XPI calls
UERCPURG
Task purged during XPI call.
All can be used.
Chapter 1. Global user exit programs 67
EXEC interface program exits
Exit XEIOUT
When invoked
After the execution of any EXEC CICS API or SPI command.
Exit-specific parameters
UEPARG
UEPEXECB
UEPUSID
UEPPGM
UEPLOAD
UEPRSA
Address of the EXEC command parameter list.
Address of the system EIB.
Address of the 8-character userid.
Address of the 8-character application program name.
Address of the application program’s load-point.
Address of the application’s register save area. This contains the
contents of the registers at the point when the program issued the
EXEC CICS command.
Exit XEISPOUT
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
When invoked
After the execution of any EXEC CICS SPI command
v EXEC CICS ENABLE
v EXEC CICS DISABLE
v EXEC CICS EXTRACT EXIT.
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
except
:
UEPPGM
UEPLOAD
CICS TS for OS/390: CICS Customization Guide
68
Address of the 8-character application program name.
Address of the application program’s load-point.
Loading...