Main
Page
Page
Page
Contents
Part 1. Customizing with user exit programs ................. 1
iv
Page
vi
Page
Part 2. Customizing with initialization and shutdown programs.........391
Part 3. Customizing with user-replaceable programs..............399
viii
Page
x
Page
Part 4. Customizing the XRF overseer program ................607
xii
Part 5. CICS journaling, monitoring, and statistics...............627
Part 6. Customizing CICS compatibility interfaces ...............689
Part 7. Customizing CICS security processing.................719
xiv
Part 8. Examining and modifying resource attributes .............739
Part 9. Appendixes .............................765
Page
Notices
Programming interface information
xviii
Trademarks
Page
Preface
What this book is about
Who this book is for
What you need to know to understand this book
How to use this book
Syntax notation and conventions used in this book
xxii
Bibliography
CICS Transaction Server for OS/390
CICS books for CICS Transaction Server for OS/390
CICSPlex SM books for CICS Transaction Server for OS/390
Other CICS books
xxiv
ACF/TCAM Version 3 Application Programming
ACF/TCAM Installation and Migration Guide
MVS books
VTAM books
SNA Sessions Between Logical Units
SNA Formats
Service Level Reporter Version 3 General Information
Determining if a publication is current
Transaction Processing and Data Collection Kit
xxvi
Summary of changes
Customization Guide
Changes for this edition
Changes for CICS Transaction Server for OS/390 Release 2
Changes for CICS Transaction Server for OS/390 Release 1
xxviii
Page
Page
Page
Page
Chapter 1. Global user exit programs
Overview what is a global user exit?
program
point
Global user exit programs
Register conventions
4
31-bit addressing implications
Access register implications
IBM ESA/370 Principles of Operation
Using CICS services
Using EXEC CICS and XPI calls in the same exit program
Using EDF with global user exits
6
The global work area
Making trace entries
Parameters passed to the global user exit program
DFHUEPAR standard parameters
8
Page
Returning values to CICS
10
Restrictions on the use of elds as programming interfaces
Exit programs and the CICS storage protection facility
Execution key for global user exit programs
Data storage key for global user exit programs
Errors in user exit programs
12
Dening, enabling, and disabling an exit program
Invoking more than one exit program at a single exit
Invoking a single exit program at more than one exit
Sample global user exit programs
14
Global work area (GWA) sample exit programs
The DFH$PCPI program:
Sample program denitions:
16
The Basic Mapping Support sample exit program
The data tables sample exit programs
CICS Shared Data TablesGuide
The dump domain sample exit program
The enqueue EXEC interface sample exit program
The function-shipping and DPL queue control sample exit program
The interval control EXEC interface sample exit program
The ISC session queue management sample exit program
The message domain sample exit programs
18
List of global user exit points
except
20
except
Page
22
|||
Page
24
Activity keypoint program exit XAKUSER
Recovery and Restart Guide
Exit XAKUSER
activity keypoint program exit
Page
Basic Mapping Support exits XBMIN and XBMOUT
eld element table
Exit XBMIN
Exit XBMOUT
28
The eld element table structure
eld element table
Programming the XBMIN exit
Programming the XBMOUT exit
30
Cumulative mapping operations
Message routing
Bridge facility exit
Exit XFAINTU
Bridge facility exit
32
Data tables management exits XDTRD, XDTAD, and XDTLC
CICS Shared Data TablesGuide
Exit XDTRD
34
Page
Exit XDTAD
CICS Shared Data TablesGuide
36
Exit XDTLC
38
DBCTL interface control program exit XXDFA
DBCTL interface control program exit
DBCTL tracking program exits XXDFB and XXDTO Exit XXDFB
CICS IMS Database Control Guide
40
DBCTL tracking program exits
Exit XXDTO
DBCTL tracking program exits
Dispatcher domain exits XDSBWT and XDSAWT
Exit XDSBWT
42
Exit XDSAWT
dispatcher domain exits
Page
DL/I interface program exits XDLIPRE and XDLIPOST
CICS IMS Database Control Guide
44
IMS/ESA Application Programming: DL/I Calls
Exit XDLIPRE
46
Exit XDLIPOST
48
Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT
Exit XDUREQ
50
current
The sample program for the XDUREQ exit, DFH$XDRQ
Exit XDUREQC
52
Page
54
Exit XDUCLSE
Exit XDUOUT
56
Enqueue EXEC interface program exits XNQEREQ and XNQEREQC
Exit XNQEREQ
Exit XNQEREQC
58
Page
60
Page
Modifying user arguments
62
Sample exit program, DFH$XNQE
Notes about the use of XNQEREQ to alter ENQ or DEQ scope.
64
EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT
The command parameter list
CICS Application
this execution
Bypassing commands
Exit XEIIN
66
Exit XEISPIN
Exit XEIOUT
Exit XEISPOUT
68
Page
File control EXEC interface API exits XFCREQ and XFCREQC
70
Page
72
Page
Modifying elds in the command-level parameter structure
A list of input and output elds
74
Page
Modifying the EID
76
Example of modifying read integrity bits
Use of the task token UEPTSTOK
Use of the parameter UEPFSHIP
The EIB
Example of how XFCREQ and XFCREQC can be used
78
users
Exit XFCREQ
Exit XFCREQC
80
Page
Page
File control EXEC interface SPI exits XFCAREQ and XFCAREQC
Exit XFCAREQ
84
Exit XFCAREQC
86
Page
88
Page
90
Modifying elds in the command-level parameter structure
92
Page
Modifying the EID
except for
94
Use of the task token UEPTSTOK
Modifying user arguments
File control le state program exits XFCSREQ and XFCSREQC
96
Exit XFCSREQ
98
Page
Exit XFCSREQC
100
Page
nn
102
nn
Page
104
File control open/close program exit XFCNREC
Recovery and Restart Guide
le control open/close program exit
Exit XFCNREC
le control open/close program exit
106
File control quiesce receive exit, XFCVSDS
Exit XFCVSDS
108
Page
File control quiesce send exit XFCQUIS
le control quiesce send exit
110
le control quiesce send exit
File control recovery program exits XFCBFAIL, XFCBOUT,XFCBOVER, and XFCLDEL
Order of invocation
112
Exit XFCBFAIL, le control backout failure exit
Page
114
Values of the error-type byte referenced by UEPERR
DFH$FCBF sample global user exit program
116
Exit XFCBOUT, le control backout exit
Migration note
118
Exit XFCBOVER, le control backout override exit
Retained lock override for batch
Effect of retained lock override on CICS
120
DFH$FCBV sample global user exit program
Exit XFCLDEL, le control logical delete exit
122
DFH$FCLD sample global user exit program
124
Page
Good morning message program exit XGMTEXT
good morning message program exit
126
Intersystem communication program exits XISCONA and XISLCLQ
The XISCONA exit
only if all bound contention winner sessions are in use
The sample XISCONA global user exit program, DFHXIS
Exit XISCONA
128
Page
The XISLCLQ exit
Exit XISLCLQ
130
Page
Interval control program exits XICREQ, XICEXP, and XICTENF
Exit XICREQ
132
interval control program exits
Exit XICEXP
Exit XICTENF
interval control program exits
Interval control EXEC interface program exits XICEREQ and XICEREQC
Exit XICEREQ
134
Exit XICEREQC
136
Figure 1. The command-level parameter structure for interval control
Chapter1. Global user exit programs 137
138
Page
140
Page
142
Page
Using the interval control request token UEPICTOK
144
Using the task token UEPTSTOK
Example of how XICEREQ and XICEREQC can be used
146
Loader domain exits XLDLOAD and XLDELETE
Exit XLDLOAD
loader domain exits
Exit XLDELETE
loader domain exits
148
Log manager domain exit XLGSTRM
sysname
OS/390 MVS Authorized Assembler Services Reference ALE-DYN
Exit XLGSTRM
OS/390 MVS Authorized Assembler Services Reference ALE-DYN
150
An example of how XLGSTRM can be used
Message domain exit XMEOUT
152
Any
Exit XMEOUT
date time applid
154
journalname
module
lename
journalname
The sample XMEOUT global user exit programs
Monitoring domain exit XMNOUT
Exit XMNOUT
156
monitoring domain exit
Program control program exits XPCREQ, XPCREQC, XPCFTCH, XPCHAIR, XPCTA, and XPCABND
XPCREQ and XPCREQC
158
Exit XPCREQ
Exit XPCREQC
The command parameter structure
The UEPCLPS exit-specic parameter:
160
Page
Modifying elds in the command parameter structure
Modifying input elds:
162
Modifying output elds:
Using the program control request token, UEPPCTOK
Using the task token UEPTSTOK
Example of how XPCREQ and XPCREQC can be used
In XPCREQ:
164
In XPCREQC:
Exit XPCFTCH
before the original program is invoked
instead of
The sample XPCFTCH global user exit program, DFH$PCEX
Exit XPCHAIR
166
Page
Exit XPCTA
168
The sample XPCTA global user exit program, DFH$PCTA
Exit XPCABND
170
Resource manager interface program exits XRMIIN and XRMIOUT Exit XRMIIN
resource manager interface program exits
Exit XRMIOUT
resource manager interface program exits
172
Resource management install and discard exit XRSINDI
resource_name
Exit XRSINDI
174
Page
176
Signon and signoff exits XSNON and XSNOFF
Exit XSNON
sign on and sign off exits
Exit XSNOFF
sign on and sign off exits
178
Page
Statistics domain exit XSTOUT
Exit XSTOUT
180
statistics domain exit
System recovery program exit XSRAB Exit XSRAB
182
Page
184
Page
System termination program exit XSTERM
Exit XSTERM
186
system termination program exit
Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT
Exit XTSQRIN
Exit XTSQROUT
188
Page
Exit XTSPTIN
190
Exit XTSPTOUT
192
Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC
Exit XTSEREQ
CICS/ESA
194
Exit XTSEREQC
CICS/ESA
196
Page
198
Page
200
Modifying user arguments
Page
Terminal allocation program exit XALCAID
Exit XALCAID
terminal allocation program exit
204
Terminal control program exits XTCIN, XTCOUT, XTCATT, XTCTIN, and XTCTOUT Exit XTCIN
Exit XTCOUT
Exit XTCATT
Exit XTCTIN
206
Exit XTCTOUT
Terminal not known condition exits XALTENF and XICTENF
CICS Resource
208
The exits
Data returned by exit
Exit XALTENF
210
Page
Exit XICTENF
212
Page
The sample program for the XALTENF and XICTENF exits, DFHXTENF
214
Figure 2. Sample program for XALTENFand XICTENF exits (Part 2 of 2)
Transaction manager domain exit XXMATT Exit XXMATT
transaction manager domain exit
216
transaction manager domain exit
Transient data program exits XTDREQ, XTDIN, and XTDOUT Exit XTDREQ
218
Exit XTDIN
Exit XTDOUT
220
Transient data EXEC interface program exits XTDEREQ and XTDEREQC
Exit XTDEREQ
222
Exit XTDEREQC
224
Page
226
Page
228
Page
User log record recovery program exits XRCINIT and XRCINPT
Coding the exit programs
230
Enabling the exit programs
Exit XRCINIT
Exit XRCINPT
232
Page
VTAM terminal management program exit XZCATT Exit XZCATT
VTAMterminal management program exit
234
VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE
Exit XZCIN
Exit XZCOUT
Exit XZCOUT1
236
XZIQUE exit for managing intersystem queues
Interaction with the XISCONA exit
When the XZIQUE exit is invoked
Using an XZIQUE global user exit program
238
Statistics elds in DFHA14DS and DFHA20DS
A14EALRJ:
A14EQPCT and A20EQPCT:
Exit XZIQUE
240
Page
242
Designing an XZIQUE global user exit program
Design considerations
Some guidance on the use of IRC/ISC statistics
Sample exit program design
Overview of the sample exit program:
244
Extensions to the sample program:
XRF request-processing program exit XXRSTAT
CICS/ESA 3.3 XRF Guide
246
Exit XXRSTAT
XRF request-processing program exit
Page
Chapter 2. Task-related user exit programs
Introduction to the task-related user exit mechanism (the adapter)
The stub program
the adapter
250
Returning control to the application program
the stub program
Task-related user exits and EDF
The task-related user exit program
252
the stub program
User exit parameter lists
DFHUEPAR
254
Page
256
DFHUERTR (the function denition)
Caller parameter lists
CICS SPI parameters:
Application program parameters:
258
CICS syncpoint manager parameters:
Page
CICS task manager parameters:
260
CICS termination manager parameters:
CICS EDF build parameters:
262
Summary of the task-related user exit parameter lists
Figure 7. Task-relateduser exit parameter lists
264
The schedule ag word
Register handling in the task-related user exit program
Saving CICS registers
266
The calling programs registers
Addressing-mode implications
always
Exit programs and the CICS storage protection facility
Execution key for task-related user exit programs
Data storage key for task-related user exit programs
Recursion within a task-related user exit program
268
Using CICS services in your task-related user exit program
But see the note about not using DFHEIENT in abend invocations, on page 276.
Work areas
The global work area
The local work area
Coding a program to be invoked by the CICS SPI
Coding a program to be invoked by the CICS syncpoint manager
270
Increasing efficiency single-update and read-only protocols
Single-update protocol:
Read-only protocol:
Return codes
What is expected of your resource manager
Sample code for a TRUE invoked by the CICS syncpoint manager
272
Page
Resynchronization
Coding a program to be invoked by the CICS task manager
274
Coding a program to be invoked at CICS termination
OS/390 MVS Authorized Assembler Services Guide
Sample code for a TRUE invoked at CICS termination
276
Page
Using EDF with your task-related user exit program
278
Figure 10. Interface between the task-related user exit and EDF
) and (E
) expressions in Figure 10.
Table13. Description of each stage of the task-related user exit/EDF interface
Adapter administration
What you must do before using the adapter
280
Enabling for specic invocation-types
The administration routines
adapter administration
Page
Chapter 3. The user exit programming interface (XPI)
Overview
284
Page
CICS External Interfaces Guide
General form of an XPI call
xxyy
286
xxyy
Page
288
Page
Setting up the XPI environment
290
XPI register usage
The XPI copy books
Reentrancy considerations resulting from XPI calls
Global user exit XPI examples, showing the use of storage
292
Figure 11.Global user exit program with XPI (Part 1 of 5)
Figure 11.Global user exit program with XPI (Part 2 of 5)
294
Figure 11.Global user exit program with XPI (Part 3 of 5)
Figure 11.Global user exit program with XPI (Part 4 of 5)
296
An example showing how to build a parameter list incrementally
Figure 11.Global user exit program with XPI (Part 5 of 5)
The XPI functions
298
the XPI functions
Dispatcher functions
Synchronization protocols for SUSPEND and RESUME processing
300
The normal synchronization protocol
the XPI functions
The synchronization protocol and task purge
Problem Determination Guide
The ADD_SUSPEND call
302
Page
RESPONSE and REASON values for ADD_SUSPEND:
The SUSPEND call
304
Page
306
RESPONSE and REASON values for SUSPEND:
The RESUME call
RESPONSE and REASON values for RESUME:
The DELETE_SUSPEND call
308
RESPONSE and REASON values for DELETE_SUSPEND:
The WAIT_MVS call
310
Page
312
RESPONSE and REASON values for WAIT_MVS:
The CHANGE_PRIORITY call
RESPONSE and REASON values for CHANGE_PRIORITY:
Dump control functions
314
The SYSTEM_DUMP call
RESPONSE and REASON values for SYSTEM_DUMP:
The TRANSACTION_DUMP call
set
316
RESPONSE and REASON values for TRANSACTION_DUMP:
Enqueue domain functions
The ENQUEUE function
318
RESPONSE and REASON values for ENQUEUE
The DEQUEUE function
RESPONSE and REASON values for DEQUEUE
enqueue domain functions
Kernel domain functions The START_PURGE_PROTECTION function
RESPONSE values for START_PURGE_PROTECTION:
The STOP_PURGE_PROTECTION function
RESPONSE values for STOP_PURGE_PROTECTION:
kernel domain functions
Nesting purge protection calls
Loader functions
The DEFINE_PROGRAM call
kernel domain functions
322
Page
RESPONSE and REASON values for DEFINE_PROGRAM:
324
The ACQUIRE_PROGRAM call
RESPONSE and REASON values for ACQUIRE_PROGRAM:
326
The RELEASE_PROGRAM call
RESPONSE and REASON values for RELEASE_PROGRAM:
The DELETE_PROGRAM call
RESPONSE and REASON values for DELETE_PROGRAM:
328
Log manager functions
The INQUIRE_PARAMETERS call
RESPONSE and REASON values for INQUIRE_PARAMETERS:
The SET_PARAMETERS call
log manager functions
Monitoring functions
330
The MONITOR call
log manager functions
Page
332
RESPONSE and REASON values for MONITOR:
The INQUIRE_MONITORING_DATAcall
No
All
INQUIRE_MONITORING_DATA:
Program management functions
334
The INQUIRE_PROGRAM call
336
Page
338
Page
340
RESPONSE and REASON values for INQUIRE_PROGRAM:
The INQUIRE_CURRENT_PROGRAM call
unless
342
that was not a global user exit or task-related user exit program
INQUIRE_CURRENT_PROGRAM:
The SET_PROGRAM call
344
Page
RESPONSE and REASON values for SET_PROGRAM:
The START_BROWSE_PROGRAM call
346
START_BROWSE_PROGRAM:
The GET_NEXT_PROGRAM call
348
RESPONSE and REASON values for GET_NEXT_PROGRAM:
The END_BROWSE_PROGRAM call
RESPONSE and REASON values for END_BROWSE_PROGRAM:
The INQUIRE_AUTOINSTALL call
RESPONSE and REASON values for INQUIRE_AUTOINSTALL:
350
The SET_AUTOINSTALL call
RESPONSE and REASON values for SET_AUTOINSTALL:
State data access functions
The INQ_APPLICATION_DATA call
352
Page
RESPONSE and REASON values for INQ_APPLICATION_DATA:
354
The INQUIRE_SYSTEM call
356
Page
358
RESPONSE and REASON values for INQUIRE_SYSTEM
The SET_SYSTEM call
RESPONSE and REASON values for SET_SYSTEM:
360
Storage control functions
The GETMAIN call
362
RESPONSE and REASON values for GETMAIN:
The FREEMAIN call
RESPONSE and REASON values for FREEMAIN:
364
The INQUIRE_ACCESS call
RESPONSE and REASON values for INQUIRE_ACCESS:
The INQUIRE_ELEMENT_LENGTH call
INQUIRE_ELEMENT_LENGTH:
The INQUIRE_SHORT_ON_STORAGE call
366
INQUIRE_SHORT_ON_STORAGE:
The INQUIRE_TASK_STORAGE call
RESPONSE and REASON values for INQUIRE_TASK_STORAGE:
The SWITCH_SUBSPACE call
RESPONSE and REASON values for SWITCH_SUBSPACE:
368
Trace control function
The TRACE_PUT call
trace control function
RESPONSE values for TRACE_PUT
Transaction management functions
370
The INQUIRE_CONTEXT call
trace control function
byte1
The INQUIRE_DTRTRAN call
RESPONSE and REASON values for INQUIRE_DTRTRAN:
The INQUIRE_MXT call
372
RESPONSE and REASON values for INQUIRE_MXT:
The INQUIRE_TCLASS call
374
RESPONSE and REASON values for INQUIRE_TCLASS:
The INQUIRE_TRANDEF call
376
Page
378
Page
380
Page
382
(Rn) A register to receive the size of the transaction work area, expressed as a binary value.
RESPONSE and REASON values for INQUIRE_TRANDEF:
The INQUIRE_TRANSACTION call
384
Page
386
RESPONSE and REASON values for INQUIRE_TRANSACTION:
The SET_TRANSACTION call
RESPONSE and REASON values for SET_TRANSACTION:
User journaling function
388
The WRITE_JOURNAL_DATA call
user journaling function
RESPONSE and REASON values for WRITE_JOURNAL_DATA:
390
user journaling function
Page
Page
Chapter 4. Writing initialization and shutdown programs
Initialization programs
First phase PLT programs
Second phase PLT programs
Shutdown programs
394
initialization programs
First phase PLT programs
PLT programs for the second quiesce stage
shutdown assist transaction
The shutdown assist utility program, DFHCESD
shutdown programs
General considerations
Storage keys for PLT programs
396
Execution key for PLT programs
shutdown programs
Data storage key for PLT programs
PLT programsgeneral
Page
Page
Page
Chapter 5. General notes about user-replaceable programs
Rewriting user-replaceable programs
IBM ESA/370 Principles of Operation
Assembling and link-editing user-replaceable programs
402
Page
Link-edit statements for DFHPEP.
404
Link-edit statements for DFHREST.
Figure 13. Link-edit statements for user-replaceableprograms (Part 1 of 2)
Link-edit statements for DFHTEP.
Link-edit statements for DFHZNEP.
User-replaceable programs and the storage protection facility
Execution key for user-replaceable programs
Data storage key for user-replaceable programs
406
Chapter 6. Writing a program error program
CICS Recovery and Restart Guide
408
Figure 14. Source code of the default program error program (DFHPEP)
Figure 15. Source of DFHPEPcommunication area (assembler-language) (Part 1 of 2)
410
Figure 15. Source of DFHPEPcommunication area (assembler-language) (Part 2 of 2)
Chapter 7. Writing a transaction restart program
CICS Recovery and Restart Guide
The DFHREST communications area
412
Page
The CICS-supplied transaction restart program
414
Chapter 8. Writing a terminal error program
Background to error handling for TCAM and sequential devices
When an abnormal condition occurs
Terminal control program
416
Terminal abnormal condition program
Terminal error program
The communication area
Terminal abnormal condition line entry (TACLE)
The sample terminal error program
background
Components of the sample terminal error program
TEP error table
418
TEP default table
Structure of the sample terminal error program
Entry and initialization
Terminal ID and error code lookup
420
Error processor selection
Error processing execution
General exit
Common subroutines
Page
Sample terminal error program messages
Figure 18. Overview of the sample terminal error program (DFHXTEP)
424
Generating the sample terminal error program
Job control for generating the sample terminal error program
DFHTEPMgenerating the sample DFHTEP module
426
Page
428
DFHTEPM TYPE=ENTRY and EXITfor user entry and exit routines
DFHTEPM TYPE=ERRPROCreplacing error processors
DFHTEPM TYPE=FINALending the sample DFHTEP module
430
DFHTEPM macro examples
Figure 19. Example of DFHTEPM macros used to generate a sample DFHTEPmodule
DFHTEPTgenerating the sample DFHTEP tables
DFHTEPT TYPE=INITIALestablishing the control section
432
DFHTEPT TYPE=PERMTIDassigning permanent terminal error blocks
DFHTEPT TYPE=PERMCODE|ERRCODEdening error status elements
434
Page
DFHTEPT TYPE=BUCKETusing the error bucket for specic errors
DFHTEPT TYPE=FINALterminating DFHTEPT entries
436
DFHTEPTexamples of how the macros are used
User-written terminal error programs
Why write your own terminal error program?
Restrictions on the use of EXEC CICS commands
438
are
Addressing the contents of the communication area
Page
Resetting the ags in the user action byte, TEPCAACT
440
Addressing the contents of the TACLE
Page
Figure 22. Format description of the TACLEDSECT (Part 1 of 2)
Figure 22. Format description of the TACLEDSECT (Part 2 of 2)
444
Example of a user-written terminal error program
DFHTEP recursive retry routine
Figure 23. DFHTEPrecursive retry routine (Part 1 of 2)
446
Figure 23. DFHTEPrecursive retry routine (Part 2 of 2)
Page
Chapter 9. Writing a node error program
Background to CICS-VTAM error handling
Why use a NEP to supplement CICS default actions?
450
An overview of writing a NEP
The default NEP
The sample NEP
452
The node error table
Coding the sample NEP
translated code
454
Multiple NEPs
456
When an abnormal condition occurs
The communication area
458
Figure 25. The DFHZNAC/DFHZNEPcommunication area (Part 1 of 3)
Figure 25. The DFHZNAC/DFHZNEPcommunication area (Part 2 of 3)
460
Figure 25. The DFHZNAC/DFHZNEPcommunication area (Part 3 of 3)
The user option bytes (TWAOPTL)
462
Page
Additional information for the NEP (TWAADINF)
TWANLD and TWANLDL using the DFHZNAC logging facility:
464
TWAPIP and application routing failure:
The additional system parameters (TWASYSPM)
The sample node error program
Compatibility with the sample terminal error program
Components of the sample node error program
466
Entry section
Routing mechanism
Node error table
Optional common subroutines
Optional error processors for 3270 logical units
468
Optional error processor for interactive logical units
Generating the sample node error program
DFHSNEP TYPE=USTOR and USTORENDdening user storage
DFHSNEP TYPE=INITIALgenerating the routing mechanism
470
DFHSNEP TYPE=DEF3270including error processors for 3270 LUs
DFHSNEP TYPE=DEFILUincluding error processors for INTLUs
DFHSNEP TYPE=FINALterminating DFHSNEP entries
DFHSNEP TYPE=ERRPROCspecifying a user error processor
472
DFHSNETgenerating the node error table
DSECTs
474
User-written node error programs
Restrictions on the use of EXEC CICS commands
are
Entry and addressability
Coding for the 3270 unavailable printer condition
476
Coding for session failures
Coding for specic VTAM sense codes
Writing multiple NEPs
478
DFHZNEPI macros
DFHZNEPI TYPE=INITIALspecifying the default routine
DFHZNEPI TYPE=ENTRYspecifying a transaction-class routine
DFHZNEPI TYPE=FINALterminating DFHZNEPI entries
Handling shutdown hung terminals in the node error program
How DFHZNAC passes the setting of TCSACTN to DFHZNEP
How DFHZNAC passes the DFHZC2351 reason code to DFHZNEP
How DFHZNEP can modify the force-close action for the current terminal
Using the node error program with XRF or persistent sessions
The node error program with persistent session support
Changing the recovery notication
the node error program and XRF
Changing the recovery message
Changing the recovery transaction
482
Using the node error program with VTAM generic resources
the node error program and XRF
Page
Page
Chapter 10. Writing a program to control autoinstall of terminals
Coding entries in the VTAM LOGON mode table
486
Using model terminal support (MTS)
Coding entries for MTS
The autoinstall control program for terminals, DFHZATDX
The communication area at INSTALL for terminals
SNA Network Product Formats
488
Page
How CICS builds the list of autoinstall models
490
CICS Messages and Codes
Returning information to CICS
Selecting the autoinstall model
492
Setting the TERMINAL name
CICS action on return from the control program
494
ACF/VTAM Version3 Programming
The communication area at DELETE for terminals
Naming, testing, and debugging your autoinstall control program Naming
Testing and debugging
496
naming and testing the control program
498
Here are three pieces of code that customize the sample program.
Assembler language
Figure 31. Example of how to customize the DFHZATDXsample program (Part 1 of 2)
COBOL
Figure 31. Example of how to customize the DFHZATDXsample program (Part 2 of 2)
500
PL/I
Figure 32. Example of how to customize the DFHZCTDX sample program
Figure 33. Example of how to customize the DFHZPTDX sample program (Part 1 of 2)
502
Figure 33. Example of how to customize the DFHZPTDX sample program (Part 2 of 2)
Page
Chapter 11. Writing a program to control autoinstall of consoles
Leaving it all to CICS
Using an autoinstall control program
506
The communication area at INSTALL for consoles
How CICS builds the list of autoinstall models
Returning information to CICS
508
Selecting the autoinstall model
Setting the TERMINAL name
CICS action on return from the control program
510
Page
Page
Chapter 12. Writing a program to control autoinstall of APPC connections
Local APPC single-session connections initiated by CINIT
Local APPC parallel-session and single-session connections initiated by BIND
Autoinstall templates for APPC connections
514
Benets of autoinstall
Requirements for autoinstall
The autoinstall control program for APPC connections
Recovery and restart
the autoinstall control program for APPC connections
The communication area at INSTALL for APPC connections
516
INSTALL_APPC_STANDARDheader A fullword input eld comprising the following information:
Page
518
Page
When autoinstalled APPC connections are deleted
Single-session connections installed via a CINIT
520
Synclevel 1 connections installed via a BIND
Synclevel 2 connections installed via a BIND
Resource denitions
Page
Chapter 13. Writing a program to control autoinstall of shipped terminals
Installing shipped terminals and connections
CICS-generated aliases
Resetting the terminal identier
524
same
Example
guarantee
in the TOR
The communications area at INSTALL for shipped terminals
526
Page
correlation identier
528
has
different
Default actions of the sample programs
Page
Chapter 14. Writing a program to control autoinstall of Client virtual terminals
CICS for MVS/ESA Server support for CICS Clients
CICS Clients: Administration
CICS Family: Client/Server Programming
How Client virtual terminals are autoinstalled
Terminal identiers
System Denition Guide
532
supplied name
Why override TERMIDs?
Overriding CICS-generated TERMIDs
Overriding Client-specied TERMIDs
The communications area at INSTALL for Client virtual terminals
534
Page
536
Default actions of the sample programs
Page
Chapter 15. Writing a program to control autoinstall of programs
Autoinstall model denitions
Autoinstalling programs invoked by EXEC CICS LINK commands
chooses
540
Autoinstall processing of mapsets
System autoinstall
after
Benets of autoinstall
Reduced system administration costs
Faster startup times
Warm and emergency starts
542
without cataloging
with cataloging
Page
544
Page
The sample autoinstall control program for programs, DFHPGADX
546
Resource denition
Testing and debugging your program
548
Chapter 16. Writing a dynamic routing program
distributed
CICSPlex SM Concepts and Planning
Dynamic transaction routing
Dynamic transactions
When the dynamic routing program is invoked
the dynamic routing program
550
Information passed to the dynamic routing program
Using a common transaction denition in the TOR
552
Changing the program name
Telling CICS whether to route or terminate a transaction
If the system is unavailable or unknown
Invoking the dynamic routing program at end of routed transactions
554
Invoking the dynamic routing program on abend
Modifying the initial terminal data
Modifying the applications communications area
Receiving information from a routed transaction
Monitoring the output communications area
556
Monitoring the output TIOA
Unit of work considerations
Dynamic routing of DPL requests
or
When the dynamic routing program is invoked
but the routing program is not reinvoked for a route selection error
that the routing program may route locally
558
Changing the program name
Changing the transaction ID
Telling CICS whether to route or terminate a DPL request
560
but the routing program is not reinvoked for a route selection error
that the routing program may route locally
Invoking the dynamic routing program at end of routed requests
Modifying the applications input communications area
Monitoring the applications output communications area
Unit of work considerations
Parameters passed to the dynamic routing program
562
Figure 45. The communications area passed to a dynamic routing program
other than a transaction abend
564
Page
tranid
566
Page
568
Page
570
Page
572
Naming your dynamic routing program
System Programming Reference
CICS Application Programming Guide
Testing your dynamic routing program
naming your dynamic routing program
Dynamic transaction routing sample programs
sample transaction routing programs
574
Chapter 17. Writing a distributed routing program
CICS Business Transaction Services
distributed
CICSPlex SM Concepts and Planning
Differences from the dynamic routing interface
the distributed routing program
576
Distributed routing of BTS activities
CICS Business Transaction Services
neither dynamically nor statically
Which BTS activities can be dynamically routed?
differences from the dynamic routing interface
When the distributed routing program is invoked
578
Telling CICS whether to route the activity
unserviceable
CICS Business Transaction Services
Invoking the distributed routing program on the target region
on the target region
580
Routing of non-terminal-related START requests
Which requests can be dynamically routed?
statically
When the distributed routing program is invoked
582
Telling CICS whether to route the request
Invoking the distributed routing program on the target region
on the target region
This is effective only if the target region is CICS TS Release 3 or later.
584
Parameters passed to the distributed routing program
other than a transaction abend
586
Page
588
on the target region
not to be invoked on the target region
590
Page
the name by which the transaction is known in the requesting region
the call on the requesting region that caused the transaction initiation call to occur
never
592
Naming your distributed routing program
System Programming Reference
Distributed transaction routing sample programs
Page
Chapter 18. Writing a CICSDBCTL interface status program
The sample program and copy book
the CICSDBCTL interface status program
596
Page
Page
Chapter 19. Writing a 3270 bridge exit program
External Interfaces Guide
Page
Chapter 20. Writing a security exit program for IIOP
CICS Internet Guide
Page
Chapter 21. Writing a program to tailor JVM execution environment variables
Environment variables
the JVM execution options program
604
the JVM execution options program
Page
Page
608
Chapter 22. The extended recovery facility overseer program
CICS/ESA 3.3 XRF Guide
CICS Operations and Utilities Guide
The sample overseer program
The functions of the sample program
The display function
610
The restart-in-place function
Enabling and disabling restart in place:
612
Rules that control restart in place:
CICS Operations and Utilities Guide
Opening CAVM data sets dynamically
How the sample overseer program interfaces with CICS
How to tell the overseer which actives and alternates to monitor
CICS Operations and Utilities Guide
The DFHWOSM macros
614
The DFHWOSM tokens
DFHWOSM FUNC=BUILD macro
DFHWOSM FUNC=CLOSE macro
DFHWOSM FUNC=DSECT macro
616
DFHWOSM FUNC=JJC macro
DFHWOSM FUNC={JJS|QJJS} macro
DFHWOSM FUNC=OPEN macro
DFHWOSM FUNC=OSCMD macro
618
DFHWOSM FUNC=READ macro
Figure 50. Input to and output from the DFHWOSM FUNC=READ macro
620
Figure 51. DBLIDs for the DFHWOSM FUNC=READ macro (Part 1 of 2)
Page
Reading DBCTL status information from the CAVM data sets
DFHWOSM FUNC=TERM macro
622
Customizing the sample overseer program
Loop or wait detection
customizing the sample overseer
624
Assembling and link-editing the overseer program
customizing the sample overseer
Page
Page
628
Chapter 23. CICS logging and journaling
Log stream storage
630
Primary storage
Tertiarystorage
Secondary storage
Enabling, disabling, and reading journals
Enabling and disabling a journal
Reading journal records offline
Structure and content of CICS Transaction Server for OS/390 format journal records
632
Page
Format of general log block header
634
Figure 56. Format of a general log block header
Format of general log journal record
Chapter23. CICS logging and journaling 635
Figure 57. Format of a general log record header
Reserved
on the function being journaled.
Start-of-run record
Format of caller data
636
Caller data written by le control
Read-only, read-update, write-update, write-add, write-add complete record types
638
The format of the FLJB_COMMON_DATAsection is shown in Figure 62 .
Figure 61. Format of FLJB_GENERAL_DATAsection
Figure 62. Format of FLJB_COMMON_DATAsection
3
14224
Write-delete record types
640
File-close record types
Tie-up record types
642
Figure 68. Format of TIE_UP_RECORD_DATAsection
Chapter23. CICS logging and journaling 643
Terminal control prex data
FEPI prex data
644
CICS Front End Programming Interface Users Guide
Structure and content of COMPAT41-format journal records
Format of COMPAT41 journal control label header
646
Figure 73. Format of label header part of journal control label header
Figure 74. Format of label prex part of journal control label header
13 12
Fixed length 4444
Format of journal record
648
Figure 76. Format of the system header
The system header is 10 bytes long. Its format is shown in Figure 76.
Figure 75. Format of COMPAT41journal record
Page
650
Figure 79. Journal function identiers (Part 1 of 2)
Figure 79. Journal function identiers (Part 2 of 2)
652
Figure 80. Journal module identiers
Identifying records for the start of tasks and UOWs
Format of journal records written to SMF
The SMF block header
This block describes the system creating the output. Its format is shown in Figure 82.
654
Figure 82. Format of the SMFblock header
OS/390 MVS System Management Facilities (SMF)
The CICS data section
28 8
Figure 83. Format of the CICS product section
Fixed length
Fixed length 254
Page
Chapter 24. CICS monitoring
Introduction to CICS monitoring
The classes of monitoring data
Performance class monitoring data
Coding additional event-monitoring points
658
The monitoring control table (MCT)
DFHMCT TYPE=EMP
DFHMCT TYPE=RECORD
exclude
Examples of MCT coding
Example 1:
660
Example 2:
Example 3:
Exception class data
How performance and exception class data is passed to SMF
Controlling CICS monitoring
662
CICS monitoring record formats
SMF header and SMF product section
664
The MNSMFDS DSECT has the format shown in Figure 85.
Figure 85. Format of the SMFheader and product section for monitoring records (Part 1 of 2)
OS/390 MVS System Management Facilities (SMF)
CICS data section
Dictionary data sections
666
Page
Figure 88. Default CICS dictionary entries (Part 1 of 4)
668
Figure 88. Default CICS dictionary entries (Part 2 of 4)
Figure 88. Default CICS dictionary entries (Part 3 of 4)
670
Figure 88. Default CICS dictionary entries (Part 4 of 4)
Performance data sections
Relationship of the dictionary record to the performance records
672
How the string of eld connectors is constructed:
Exception data sections
674
Figure 92. CICS monitoring exception record DSECT
The MNEXCDS DSECT has the format shown in Figure 92.
SMF SMF Product Exception Header Section Data Section
Page
Page
Chapter 25. CICS statistics
Introduction to CICS statistics
Types of statistics data
678
Page
680
Supplied Transactions
Resetting statistics counters
The EXEC CICS COLLECT STATISTICS command
CICS statistics record format
682
SMF header and SMF product section
684
Figure 94. Format of the SMFheader and product section for statistics records
OS/390 MVS System Management Facilities (SMF)
CICS statistics data section
686
. STIVERS takes the value 1 for this release of CICS.
Figure 97. Statistics data record copy books related to STID name and value
The TS data sharing statistics use no symbolic names, but relate to the STID values as follows:
Global user exit in the CICS statistics domain
Processing the output from CICS statistics
processing statistics
688
Page
690
Chapter 26. Using TCAM with CICS
CICS with TCAM SNA
Protocol management
692
Device message handler control
Transaction control
Function management header processing
Batch processing
Error processing for batch logical units
694
Error processing
The TCAM application program interface
The CICS-TCAM interface
the TCAM API
Data format
696
Logic ow
698
Terminal error program
Message routing
Segment processing
700
ACF/TCAM Version 3 Application Programming
Line pool specications
Line pool restrictions
Line locking
702
TCAM queues
TCAM devices
704
Generalized TCAM message format
vice versa
TCAM devices
TCAM with 3270 devices
TCAM devices
706
TCAM user exits
Starting and terminating TCAM CICS-TCAM startup
CICS-TCAM abend and restart
ACF/TCAM Version 3 Application Programming
TCAM user exits
Page
CICS and TCAM: program interrelationship
Chapter26. Using TCAM with CICS 709
Figure 104. TCAM message control and application program
TCAM MCP CICS Application program
CICS-TCAM program interrelationship
TCAM message control program (non-SNA)
ACF/TCAM Installation and Migration Guide
710
CICS-TCAM program interrelationship
Figure 105. Example of a TCAM message control program (non-SNA) (Part 2 of 2)
Page
Chapter 27. The dynamic allocation sample program
Overview of the dynamic allocation program
MVS/ESA SPL: Application Development Guide
MVS/ESA SPL: Application Development
Installing the program and transaction denitions
Terminal operation
714
the dynamic allocation sample program
Help feature
Values
help feature
Abbreviation rules for keywords
System programming considerations
716
keywords and values
The ow of control when a DYNALLOC request is issued
DYNALLOC ow of control
718
Page
720
Chapter 28. Invoking a user-written external security manager
An overview of the CICS-ESM interface
The MVS router
The MVS router exit
The MVS router parameter list
722
OS/390 Security Server External Security Interface (RACROUTE) Macro Reference
the MVS router
Router exit return codes
Passing control to a user-supplied ESM
MVS Authorized Assembler Programming Reference
the MVS router
How ESM exit programs access CICS-related information
For non-RACF users the ESM parameter list
724
For RACF users the RACF user exit parameter list
OS/390 Security Server (RACF) Security Administrators Guide
The installation data parameter list
726
CICS security control points
CICS security control points
728
OS/390 Security Server External Security Interface (RACROUTE) Macro Reference
Early verication processing
CICS security control points
Writing an early verication routine
Using CICS API commands in an early verication routine
730
instead of
must
Return and reason codes from the early verication routine
early verication processing
Page
Chapter 29. Writing a good night program
writing a good night program
734
The sample good night program, DFH0GNIT
writing a good night program
What the sample program does
sample good night program
736
sample good night program
Page
Page
740
Chapter 30. User programs for the system denition utility program (DFHCSDUP)
An overview of DFHCSDUP
DFHCSDUP as a batch program
Writing a program to be invoked during EXTRACT processing
The EXTRACT command
user programs for DFHCSDUP
742
When the user program is invoked
Parameters passed from DFHCSDUP to the user program
The sample EXTRACT programs
744
The CSD cross-referencing program
The DB2 formatting program
The CSD backup utility program
746
Assembling and link-editing EXTRACT programs
An assembler-language version
748
A VS COBOL II version
A PL/I version
750
A Language Environment version
Invoking DFHCSDUP from a user program
CICS Resource
Entry parameters for DFHCSDUP
752
Page
Responsibilities of the user program
754
The user exit points in DFHCSDUP
Parameters passed to the user exit routines
The initialization exit
The get-command exit
756
The extract exit
758
The put-message exit
The termination exit
The sample program, DFH$CUS1
760
Chapter 31. The programmable interface to the RDO transaction, CEDA
compatibility mode
Use of the programmable interface
Using DFHEDAP in a DTP environment
762
CICS Distributed Transaction Programming Guide
the programmable interface to CEDA
DFHEDAP in a DTP environment
Page
Page
Page
Appendix A. Coding entries in the VTAM LOGON mode table
Overview
TYPETERM device types and pointers to related LOGON mode data
TYPETERM device types
768
Table40. TYPETERM device types, with cross-references to VTAM logmode entries (continued)
TYPETERM device types
VTAM MODEENT macro operands
ACF/VTAM Network Implementation Guide
770
VTAM MODEENT macro operands
772
VTAM MODEENT macro operands
774
PSERVIC screen size values for LUTYPEx devices
PSERVIC screen size values
Table43. Equivalent PSERVIC screen size values
Matching models and LOGON mode entries
776
PSERVIC screen size values
Page
778
Page
780
Page
782
Page
784
Page
LOGON mode denitions for CICS-supplied autoinstall models
786
Page
788
Appendix B. Default actions of the node abnormal condition program
Default actions for terminal error codes
Messages and Codes
790
Page
792
Page
794
CICS messages associated with VTAM errors
Table45. CICS messages associated with VTAM errors
796
Page
798
Page
Default actions for system sense codes
Table46. Messages issued and ags set by DFHZNAC for specic sense codes
800
Table46. Messages issued and ags set by DFHZNAC for specic sense codes (continued)
default actions for system sense codes
Action ag settings and meanings
default actions for system sense codes
802
Appendix C. Transient data write-to-terminal program (DFH$TDWT)
Resource denitions required
Page
Appendix D. Uppercase translation
Uppercase translation of national characters
Character Data Representation Architecture Level 1 - Registry
Using the XZCIN exit
Using DFHTCTDY
TS data sharing messages
uppercase translation
806
Appendix E. The example program for the XTSEREQ global user exit, DFH$XTSE
Figure 113.Example exit program for the XTSEREQ exit (Part 1 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 2 of 16)
808
Figure 113.Example exit program for the XTSEREQ exit (Part 3 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 4 of 16)
810
Figure 113.Example exit program for the XTSEREQ exit (Part 5 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 6 of 16)
812
Figure 113.Example exit program for the XTSEREQ exit (Part 7 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 8 of 16)
814
Figure 113.Example exit program for the XTSEREQ exit (Part 9 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 10 of 16)
816
Figure 113.Example exit program for the XTSEREQ exit (Part 11 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 12 of 16)
818
Figure 113.Example exit program for the XTSEREQ exit (Part 13 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 14 of 16)
820
Figure 113.Example exit program for the XTSEREQ exit (Part 15 of 16)
Figure 113.Example exit program for the XTSEREQ exit (Part 16 of 16)
822
Index Special Characters
Numerics
A
B
C
824
D
Page
826
Page
E
F
828
G
I
J
K
830
L
M
N
O
P
832
Q
R
S
T
834
Page
836
U
V
W
X
838
Page
Page
Sending your comments to IBM