Contents
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
Notes on terminology
Figures
Tables
Customizing with user exit programs
Global user exit programs
Overview -- what is a global user exit?
Writing global user exit programs
Register conventions
31-bit addressing implications
Using CICS services
Using channels and containers
Assembler programs and LEASM
Using EDF with global user exits
The global work area
Making trace entries
Parameters passed to the global user exit program
Returning values to CICS
Restrictions on the use of fields as programming interfaces
Exit programs and the CICS storage protection facility
Errors in user exit programs
Defining, 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
Making programs threadsafe
Sample global user exit programs
List of global user exit points
Activity keypoint program exit XAKUSER
Exit XAKUSER
Basic Mapping Support exits XBMIN and XBMOUT
Exit XBMIN
Exit XBMOUT
The field element table structure
Programming the XBMIN exit
Programming the XBMOUT exit
Bridge facility exit XFAINTU
Exit XFAINTU
Data tables management exits XDTRD, XDTAD, and XDTLC
Exit XDTRD
Exit XDTAD
Exit XDTLC
DBCTL interface control program exit XXDFA
DBCTL tracking program exits XXDFB and XXDTO
Exit XXDFB
Exit XXDTO
Dispatcher domain exits XDSBWT and XDSAWT
Exit XDSBWT
Exit XDSAWT
DL/I interface program exits XDLIPRE and XDLIPOST
Exit XDLIPRE
Exit XDLIPOST
Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT
Exit XDUREQ
The sample program for the XDUREQ exit, DFH$XDRQ
Exit XDUREQC
Exit XDUCLSE
Exit XDUOUT
Enqueue EXEC interface program exits XNQEREQ and XNQEREQC
Exit XNQEREQ
Exit XNQEREQC
The command-level parameter structure
Sample exit program, DFH$XNQE
EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT
The command parameter list
Bypassing commands
Exit XEIIN
Exit XEISPIN
Exit XEIOUT
Exit XEISPOUT
File control domain exits, XFCFRIN and XFCFROUT
XFCFRIN
XFCFROUT
Exit XFCFRIN
Exit XFCFROUT
File control EXEC interface API exits XFCREQ and XFCREQC
The command-level parameter structure
Modifying fields in the command-level parameter structure
Modifying the EID
Use of the task token UEPTSTOK
Use of the parameter UEPFSHIP
The EIB
Example of how XFCREQ and XFCREQC can be used
Exit XFCREQ
Exit XFCREQC
File control EXEC interface SPI exits XFCAREQ and XFCAREQC
Exit XFCAREQ
Exit XFCAREQC
The command-level parameter structure
Modifying fields in the command-level parameter structure
Modifying the EID
Use of the task token UEPTSTOK
Modifying user arguments
File control file state program exits XFCSREQ and XFCSREQC
Exit XFCSREQ
Exit XFCSREQC
File control open/close program exit XFCNREC
Using XFCNREC with a back out recovery setting mismatch
Using XFCNREC with a BWO mismatch
Exit XFCNREC
File control quiesce receive exit, XFCVSDS
Exit XFCVSDS
File control quiesce send exit XFCQUIS
File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and XFCLDEL
Order of invocation
Enabling the exit programs
Exit XFCBFAIL, file control backout failure exit
Exit XFCBOUT, file control backout exit
Exit XFCBOVER, file control backout override exit
Exit XFCLDEL, file control logical delete exit
Front End Programming Interface exits XSZARQ and XSZBRQ
"Good morning" message program exit XGMTEXT
HTTP client open and send exits, XWBOPEN and XWBSNDO
Intersystem communication program exits XISCONA and XISLCLQ
The XISCONA exit
The XISLCLQ exit
Interval control program exits XICREQ, XICEXP, and XICTENF
Exit XICREQ
Exit XICEXP
Exit XICTENF
Interval control EXEC interface program exits XICEREQ, XICERES, and XICEREQC
Parameters passed to each of the exits
Exit XICEREQ
Exit XICERES
Exit XICEREQC
The command-level parameter structure
Loader domain exits XLDLOAD and XLDELETE
Exit XLDLOAD
Exit XLDELETE
Log manager domain exit XLGSTRM
Exit XLGSTRM
An example of how XLGSTRM can be used
The sample program for the XLGSTRM exit, DFH$LGLS
Message domain exit XMEOUT
Exit XMEOUT
The sample XMEOUT global user exit programs
Monitoring domain exit XMNOUT
Exit XMNOUT
Program control program exits XPCREQ, XPCERES, XPCREQC, XPCFTCH, XPCHAIR, XPCTA, and XPCABND
XPCREQ, XPCERES, and XPCREQC
Exit XPCFTCH
Exit XPCHAIR
Exit XPCTA
Exit XPCABND
Resource manager interface program exits XRMIIN and XRMIOUT
Exit XRMIIN
Exit XRMIOUT
Resource management install and discard exit XRSINDI
Exit XRSINDI
Signon and signoff exits XSNON, XSNOFF, and XSNEX
Exit XSNON
Exit XSNOFF
Exit XSNEX
Statistics domain exit XSTOUT
Exit XSTOUT
System recovery program exit XSRAB
Exit XSRAB
System termination program exit XSTERM
Exit XSTERM
Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT
Exit XTSQRIN
Exit XTSQROUT
Exit XTSPTIN
Exit XTSPTOUT
Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC
Exit XTSEREQ
Exit XTSEREQC
The command-level parameter structure
Terminal allocation program exit XALCAID
Exit XALCAID
Terminal control program exits XTCIN, XTCOUT, and XTCATT
Exit XTCIN
Exit XTCOUT
Exit XTCATT
‘Terminal not known’ condition exits XALTENF and XICTENF
The exits
Exit XALTENF
Exit XICTENF
The sample program for the XALTENF and XICTENF exits, DFHXTENF
Transaction manager domain exit XXMATT
Exit XXMATT
Transient data program exits XTDREQ, XTDIN, and XTDOUT
Exit XTDREQ
Exit XTDIN
Exit XTDOUT
Transient data EXEC interface program exits XTDEREQ and XTDEREQC
Exit XTDEREQ
Exit XTDEREQC
The command-level parameter structure
User log record recovery program exits XRCINIT and XRCINPT
Coding the exit programs
Enabling the exit programs
Exit XRCINIT
Exit XRCINPT
VTAM terminal management program exit XZCATT
Exit XZCATT
VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE
Exit XZCIN
Exit XZCOUT
Exit XZCOUT1
XZIQUE exit for managing intersystem queues
Designing an XZIQUE global user exit program
XRF request-processing program exit XXRSTAT
Exit XXRSTAT
Task-related user exit programs
Introduction to the task-related user exit mechanism (the adapter)
The stub program
Returning control to the application program
Task-related user exits and EDF
Writing a task-related user exit program
Obligations of OPENAPI task-related user exits
User exit parameter lists
The schedule flag word
Register handling in the task-related user exit program
Addressing-mode implications
Exit programs and the CICS storage protection facility
Recursion within a task-related user exit program
Purging tasks
Using CICS services in your task-related user exit program
Using channels and containers
Assembler programs and LEASM
Wait states in your task-related user exit program
Work areas
Coding a program to be invoked by the CICS SPI
Coding a program to be invoked by the CICS syncpoint manager
Coding a program to be invoked by the CICS task manager
Coding a program to be invoked at CICS termination
Using EDF with your task-related user exit program
Administering the adapter
What you must do before using the adapter
Tracing a task-related user exit program
The user exit programming interface (XPI)
Overview of the XPI
Making an XPI call
Setting up the XPI environment
XPI register usage
The XPI copy books
Reentrancy considerations resulting from XPI calls
Global user exit XPI examples, showing the use of storage
An example showing how to build a parameter list incrementally
The XPI functions
Dispatcher XPI functions
Synchronization protocols for SUSPEND and RESUME processing
The ADD_SUSPEND call
The SUSPEND call
The RESUME call
The DELETE_SUSPEND call
The WAIT_MVS call
The CHANGE_PRIORITY call
Dump control XPI functions
The SYSTEM_DUMP call
The TRANSACTION_DUMP call
Enqueue domain XPI functions
The ENQUEUE function
The DEQUEUE function
Kernel domain XPI functions
The START_PURGE_PROTECTION function
The STOP_PURGE_PROTECTION function
Nesting purge protection calls
Loader XPI functions
The DEFINE_PROGRAM call
The ACQUIRE_PROGRAM call
The RELEASE_PROGRAM call
The DELETE_PROGRAM call
Log manager XPI functions
The INQUIRE_PARAMETERS call
The SET_PARAMETERS call
Monitoring XPI functions
The MONITOR call
The INQUIRE_MONITORING_DATA call
Program management XPI functions
The INQUIRE_PROGRAM call
The INQUIRE_CURRENT_PROGRAM call
The SET_PROGRAM call
The START_BROWSE_PROGRAM call
The GET_NEXT_PROGRAM call
The END_BROWSE_PROGRAM call
The INQUIRE_AUTOINSTALL call
The SET_AUTOINSTALL call
State data access XPI functions
The INQ_APPLICATION_DATA call
The INQUIRE_SYSTEM call
The SET_SYSTEM call
Storage control XPI functions
The GETMAIN call
The FREEMAIN call
The INQUIRE_ACCESS call
The INQUIRE_ELEMENT_LENGTH call
The INQUIRE_SHORT_ON_STORAGE call
The INQUIRE_TASK_STORAGE call
The SWITCH_SUBSPACE call
Trace control XPI function
The TRACE_PUT call
Transaction management XPI functions
The INQUIRE_CONTEXT call
The INQUIRE_DTRTRAN call
The INQUIRE_MXT call
The INQUIRE_TCLASS call
The INQUIRE_TRANDEF call
The INQUIRE_TRANSACTION call
The SET_TRANSACTION call
User journaling XPI function
The WRITE_JOURNAL_DATA call
Customizing with initialization and shutdown programs
Writing initialization and shutdown programs
Writing initialization programs
First phase PLT programs
Second phase PLT programs
Effect of delayed recovery on PLTPI processing
Writing shutdown programs
First phase PLT programs
PLT programs for the second quiesce stage
The shutdown assist utility program, DFHCESD
General considerations when writing initialization and shutdown programs
Storage keys for PLT programs
Customizing with user-replaceable programs
General notes about user-replaceable programs
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
User-replaceable programs and the storage protection facility
Execution key for user-replaceable programs
Data storage key for user-replaceable programs
Writing a program error program
The sample program error programs
Writing a transaction restart program
The DFHREST communications area
The CICS-supplied transaction restart program
Writing a terminal error program
Background to error handling for sequential devices
When an abnormal condition occurs
Terminal control program
Terminal abnormal condition program
Terminal error program
The communication area
Terminal abnormal condition line entry (TACLE)
The sample terminal error program
Components of the sample terminal error program
Structure of the sample terminal error program
Sample terminal error program messages
Generating the sample terminal error program
Writing your own terminal error program
Why write your own terminal error program?
Restrictions on the use of EXEC CICS commands
Addressing the contents of the communication area
Addressing the contents of the TACLE
Example of a user-written terminal error program
Writing a node error program
Background to CICS-VTAM error handling
Why use a NEP to supplement CICS default actions?
An overview of writing a NEP
The default NEP
The sample NEP
Multiple NEPs
When an abnormal condition occurs
The communication area
The sample node error program
Compatibility with the sample terminal error program
Components of the sample node error program
Generating the sample node error program
Writing your own node error program
Restrictions on the use of EXEC CICS commands
Entry and addressability
Coding for the 3270 ‘unavailable printer’ condition
Coding for session failures
Coding for specific VTAM sense codes
Writing multiple NEPs
DFHZNEPI macros
Handling shutdown hung terminals in the node error program
Using the node error program with XRF or persistent sessions
The node error program in an XRF environment
The node error program with persistent session support
Changing the recovery notification
Changing the recovery message
Changing the recovery transaction
Using the node error program with VTAM generic resources
Writing a program to control autoinstall of terminals
Autoinstalling terminals--preliminary considerations
Coding entries in the VTAM LOGON mode table
Using model terminal support (MTS)
The autoinstall control program for terminals
The autoinstall control program at INSTALL
The communication area at INSTALL for terminals
How CICS builds the list of autoinstall models
Returning information to CICS
CICS action on return from the control program
The autoinstall control program at DELETE
The communication area at DELETE for terminals
Naming, testing, and debugging your autoinstall control program
Naming
Testing and debugging
The sample autoinstall control programs for terminals
Customizing the sample program
Writing a program to control autoinstall of consoles
Autoinstalling consoles--preliminary considerations
Leaving it all to CICS
Using an autoinstall control program
The autoinstall control program at INSTALL
The communication area at INSTALL for consoles
How CICS builds the list of autoinstall models
Returning information to CICS
CICS action on return from the control program
The autoinstall control program at DELETE
The sample autoinstall control programs for consoles
Writing a program to control autoinstall of APPC connections
Autoinstalling APPC connections--preliminary considerations
Local APPC single-session connections initiated by CINIT
Local APPC parallel-session and single-session connections initiated by BIND
Autoinstall templates for APPC connections
Benefits of autoinstall
Requirements for autoinstall
The autoinstall control program for APPC connections
Recovery and restart
The autoinstall control program at INSTALL
The communication area at INSTALL for APPC connections
The autoinstall control program at DELETE
When autoinstalled APPC connections are deleted
The sample autoinstall control program for APPC connections
Default actions of the sample program
Resource definitions
Writing a program to control autoinstall of shipped terminals
Installing shipped terminals and connections
CICS-generated aliases
Resetting the terminal identifier
The autoinstall control program at INSTALL
The communications area at INSTALL for shipped terminals
The autoinstall control program at DELETE
Default actions of the sample programs
Writing a program to control autoinstall of virtual terminals
How Client virtual terminals are autoinstalled
Autoinstall models
Terminal identifiers
Why override TERMIDs?
How bridge facility virtual terminals are autoinstalled
Using the terminal autoinstall control program for bridge facilities
Bridge facility name uniqueness
The autoinstall control program at INSTALL
The communications area at INSTALL for Client virtual terminals
The communications area at INSTALL for bridge facility virtual terminals
The autoinstall control program at DELETE
The communications area at DELETE for Client virtual terminals
The communications area at DELETE for bridge facility virtual terminals
Default actions of the sample programs
Writing a program to control autoinstall of programs
Autoinstalling programs--preliminary considerations
Autoinstall model definitions
Autoinstalling programs invoked by EXEC CICS LINK commands
Autoinstall processing of mapsets
System autoinstall
Benefits of autoinstalling programs
Reduced system administration costs
Saving in virtual storage
Faster startup times
Requirements for program autoinstall
The autoinstall control program at INSTALL
The sample autoinstall control program for programs, DFHPGADX
Customizing the sample program
Resource definition
Testing and debugging your program
Writing a dynamic routing program
Routing transactions dynamically
Dynamic transactions
When the dynamic routing program is invoked
Information passed to the dynamic routing program
Changing the target CICS region
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
Invoking the dynamic routing program on abend
Modifying the initial terminal data
Modifying the application’s communications area
Receiving information from a routed transaction
Some processing considerations
Unit of work considerations
Routing DPL requests dynamically
When the dynamic routing program is invoked
Changing the target CICS region
Changing the program name
Changing the transaction ID
Telling CICS whether to route or terminate a DPL request
If an error occurs in route selection
Using the XPCERES exit to check the availability of resources on the target region
Invoking the dynamic routing program at end of routed requests
Modifying the application’s input communications area
Monitoring the application’s output communications area
Some processing considerations
Unit of work considerations
Routing bridge requests dynamically
Changing bridge request parameters
Rejecting a Link3270 bridge request
Handling route selection errors of Link3270 bridge requests
Using the XPCERES exit to check the availability of resources on the target region
Re-invoking the dynamic routing program after Link3270 bridge requests
Link3270 bridge dynamic routing considerations
Modifying the application’s containers
Routing by user ID
Parameters passed to the dynamic routing program
Naming your dynamic routing program
Testing your dynamic routing program
Dynamic transaction routing sample programs
Writing a distributed routing program
Differences between the distributed and dynamic routing interfaces
Routing BTS activities
Which BTS activities can be dynamically routed?
When the distributed routing program is invoked
Changing the target CICS region
Telling CICS whether to route the activity
If an error occurs in route selection
Invoking the distributed routing program on the target region
Routing method requests for enterprise beans and CORBA stateless objects
Where workload balancing occurs
Which requests can be dynamically routed?
When the distributed routing program is invoked
Changing the target CICS region
Telling CICS whether to route the method request
If an error occurs in route selection
Invoking the distributed routing program on the target region
Dealing with a disabled CorbaServer
Performing a rolling upgrade of an EJB/CORBA server
Routing non-terminal-related START requests
Which requests can be dynamically routed?
When the distributed routing program is invoked
Changing the target CICS region
Telling CICS whether to route the request
If an error occurs in route selection
Using the XICERES exit to check the availability of resources on the target region
Invoking the distributed routing program on the target region
Routing inbound Web service requests
Which requests can be dynamically routed?
When the distributed routing program is invoked
Changing the target CICS region
Telling CICS whether to route the request
If an error occurs in route selection
Invoking the distributed routing program on the target region
Routing by user ID
Dealing with an abend on the target region
Some processing considerations
Parameters passed to the distributed routing program
Naming your distributed routing program
Distributed transaction routing sample programs
Writing a CICS-DBCTL interface status program
The sample CICS-DBCTL interface status program
Writing a 3270 bridge exit program
Writing a security exit program for IIOP
The sample programs
DFHXOPUS
DFHEBURM
Writing programs to customize JVMs
Writing Java classes to redirect JVM stdout and stderr output
The com.ibm.cics.server.OutputRedirectionPlugin interface
Possible destinations for output
Handling output redirection errors and internal errors
Using DFHJVMRO to modify the Language Environment enclave for a JVM
Using DFHJVMAT to modify options in a JVM profile
Options in the JVM profile that are available to DFHJVMAT
Writing a distinguished name program for clients of enterprise beans
Sample programs and copy books
Writing an EJB event program
Overview of the EJB event program
The DFHEJEP communications area
Event codes
The EJB event sample program
Actions of the default program
Writing your own EJB event program
Writing programs to customize Language Environment run-time options for XPLink programs
DFHAPXPO
Defining run-time options
Customizing the XRF overseer program
The extended recovery facility overseer program
The sample XRF overseer program
The functions of the sample program
How the sample overseer program interfaces with CICS
How to tell the overseer which actives and alternates to monitor
The DFHWOSM macros
The DFHWOSM tokens
DFHWOSM FUNC=BUILD macro
DFHWOSM FUNC=CLOSE macro
DFHWOSM FUNC=DSECT macro
DFHWOSM FUNC=JJC macro
DFHWOSM FUNC={JJS|QJJS} macro
DFHWOSM FUNC=OPEN macro
DFHWOSM FUNC=OSCMD macro
DFHWOSM FUNC=READ macro
DFHWOSM FUNC=TERM macro
Customizing the sample XRF overseer program
Loop or wait detection
Assembling and link-editing the overseer program
CICS journaling, monitoring, and statistics
CICS logging and journaling
The CICS log manager
Log stream storage
Enabling, disabling, and reading journals
Enabling and disabling a journal
Reading journal records offline
Structure and content of CICS Transaction Server for z/OS format journal records
Format of general log block header
Format of general log journal record
Start-of-run record
Format of caller data
Structure and content of COMPAT41-format journal records
Format of COMPAT41 journal control label header
Format of journal record
Identifying records for the start of tasks and UOWs
Format of journal records written to SMF
The SMF block header
The CICS product section
The CICS data section
CICS monitoring
Introduction to CICS monitoring
The classes of monitoring data
Performance class data
Exception class data
Transaction resource class data
How CICS monitoring data is passed to SMF
Controlling CICS monitoring
CICS monitoring record formats
SMF header and SMF product section
CICS data section
Processing the output from the CICS Monitoring Facility
Writing statistics collection and analysis programs
Writing a program to collect CICS statistics
Background information
Resetting statistics counters
Using the EXEC CICS COLLECT and EXTRACT STATISTICS commands
CICS statistics record format
SMF header and SMF product section
CICS statistics data section
Using an XSTOUT global user exit program to filter statistics records
Processing the output from CICS statistics
Customizing CICS compatibility interfaces
The dynamic allocation sample program
Overview of the dynamic allocation program
Installing the program and transaction definitions
The dynamic allocation program--terminal operation
Using the dynamic allocation program’s Help feature
The dynamic allocation program--values
Abbreviation rules for keywords
System programming considerations
The flow of control when a DYNALLOC request is issued
Customizing CICS security processing
Invoking an external security manager
An overview of the CICS-ESM interface
The MVS router
The MVS router exit
Using ESM exit programs to access CICS-related information
For non-RACF users -- the ESM parameter list
For RACF users -- the RACF user exit parameter list
The installation data parameter list
CICS security control points
Using early verification processing
Writing an early verification routine
Using CICS API commands in an early verification routine
Return and reason codes from the early verification routine
Writing a "good night" program
The communications area of the "good night" program
The sample "good night" program, DFH0GNIT
What the sample program does
Customizing the sample "good night" program
Examining and modifying resource attributes
User programs for the system definition utility program (DFHCSDUP)
An overview of DFHCSDUP
Invoking a user program from DFHCSDUP
Writing a program to be invoked during EXTRACT processing
The EXTRACT command
When the user program is invoked
Parameters passed from DFHCSDUP to the user program
The sample EXTRACT programs
Assembling and link-editing EXTRACT programs
Invoking DFHCSDUP from a user program
Entry parameters for DFHCSDUP
Responsibilities of the user program
The user exit points in DFHCSDUP
Parameters passed to the user exit routines
The initialization exit
The get-command exit
The extract exit
The put-message exit
The termination exit
The sample program, DFH$CUS1
Using the programmable interface to CEDA
When to use the programmable interface
Using DFHEDAP in a DTP environment
Appendixes
Appendix A. Coding entries in the VTAM LOGON mode table
Overview of the VTAM LOGON mode table
TYPETERM device types and pointers to related LOGON mode data
VTAM MODEENT macro operands
PSERVIC screen size values for LUTYPEx devices
Matching models and LOGON mode entries
LOGON mode definitions for CICS-supplied autoinstall models
Appendix B. Default actions of the node abnormal condition program
DFHZNAC--default actions for terminal error codes
CICS messages associated with VTAM errors
DFHZNAC--default actions for system sense codes
Action flag settings and meanings
Appendix C. Analysing CICS restart information
Appendix D. Using the transient data write-to-terminal program (DFH$TDWT)
DFH$TDWT--resource definitions required
Appendix E. Uppercase translation
Translating national characters to uppercase
Using the XZCIN exit
Using DFHTCTxx
Translating TS data sharing messages to uppercase
Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE
Appendix G. Threadsafe XPI commands
Bibliography
The CICS Transaction Server for z/OS library
The entitlement set
PDF-only books
Other CICS books
Books from related libraries
MVS books
VTAM books
Other related books
Accessibility
Index
Notices
Programming interface information
Trademarks
[[
Contents
Previous Page
|
Next Page
Index
]]