IBM SC34-6814-04 - page 671

This field is not used by the distributed routing program. On invocation, it is set

to 'N'.

DYRERROR

has a value only when DYRFUNC is set to 1. It indicates the type of error that

occurred during the last attempt at route selection. The possible values are:

0The selected sysid is unknown.

1The selected system is not in service.

2The selected system is in service, but no sessions are available.

3An allocate request has been rejected, and SYSIDERR returned to the

application program. This error occurs for one of the following reasons:

1. An XZIQUE global user exit program requested that the allocate be

rejected, or

2. CICS rejected the allocate request automatically because the

QUEUELIMIT value specified on the CONNECTION resource

definition has been reached.

4A queue of allocate requests has been purged, and SYSIDERR

returned to all the waiting application programs. This error occurs for

one of the following reasons:

1. An XZIQUE global user exit program requested that the queue be

purged, or

2. CICS purged the queue automatically because the MAXQTIME limit

specified on the CONNECTION resource definition has been

reached.

5The selected system does not support this function.

For BTS processes and activities and non-terminal-related START

requests, this error occurs if the distributed routing program tries to

route a request to a region that is not connected by an MRO or APPC

parallel-session link.

For method requests for enterprise beans and CORBA stateless

objects, this error occurs if the distributed routing program tries to route

a request to a region that is not connected by an MRO link.

For inbound Web services requests, this error occurs if the distributed

routing program tries to route a request to a pre-CICS TS for z/OS,

Version 3.1 region.

The next six values all apply to attempts to route STARTrequests. For the

meanings of these error conditions, see the CICS Application Programming

Reference manual.

6The EXEC CICS STARTcommand returned LENGERR.

8The EXEC CICS STARTcommand returned INVREQ.

9The EXEC CICS STARTcommand returned NOTAUTH.

CThe EXEC CICS STARTcommand returned TRANSIDERR.

DThe EXEC CICS STARTcommand returned IOERR.

EThe EXEC CICS STARTcommand returned USERIDERR.

FAn XPCERES or XICERES global user exit program on the target

region has set a return code of UERCRESU, meaning that a required

Chapter18. Writing a distributed routing program 649

Contents

Main Page Page Page Contents Part 1. Customizing with user exit programs ..................1 iv Page Part 2. Customizing with initialization and shutdown programs ........423 vi Part 3. Customizing with user-replaceable programs .............433 viii Page x Page Part 4. Customizing the XRF overseer program................687 Part 5. CICS journaling, monitoring, and statistics ..............707 xii Part 6. Customizing CICS compatibility interfaces ..............779 Part 7. Customizing CICS security processing ................787 Part 8. Examining and modifying resource attributes .............807 Part 9. Appendixes .............................831 xiv Page 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 xviii Summary of changes Changes for CICS Transaction Server for z/OS, Version 3 Release 2 Changes for CICS Transaction Server for z/OS, Version 3 Release 1 Changes for CICS Transaction Server for z/OS, Version 2 Release 3 xx Page Page Chapter 1. Global user exit programs Writing global user exit programs Register conventions 31-bit addressing implications Access register implications 4 Using CICS services Using EXEC CICS and XPI calls in the same exit program Using channels and containers Assembler programs and LEASM EDF and 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 fields 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 Exit programs and transaction isolation Errors in user exit programs Defining, enabling, and disabling an exit program 12 Viewing active global user exits Invoking more than one exit program at a single exit Invoking a single exit program at more than one exit Making programs threadsafe 14 Sample global user exit programs Basic sample and example programs Global work area (GWA) sample exit programs The DFH$PCPI program 16 Sample program definitions Example program Sample programs for specific exits 18 The Application Associated Data sample exit program The Basic Mapping Support sample exit program The data tables sample exit programs The dump domain sample exit program The enqueue EXEC interface sample exit program The file control state program sample exit program The file control recovery program sample exit programs The function-shipping and DPL queue control sample exit program The HTTP client sample exit programs 20 DFH$WBPI DFH$WBEX DFH$WBX1 DFH$WBX2 22 The interval control EXEC interface sample exit program The log manager domain sample exit program The message domain sample exit programs The MRO and APPC session queue management sample exit program The pipeline sample exit program 24 The session queue management sample exit program, for IPIC connections The transaction-abend sample exit program Alphabetical list of global user exit points 26 Page 28 Page 30 | Global user exit points by functional area Activity keypoint program exit XAKUSER 32 Exit XAKUSER Application Associated Data exit, XAPADMGR, in the APdomain Exit XAPADMGR Sample exit program, DFH$APAD Basic Mapping Support exits XBMIN and XBMOUT 34 Sample program, DFH$BMXT Exit XBMIN Exit XBMOUT The field element table structure 36 Programming the XBMIN exit Programming the XBMOUT exit Bridge facility exit XFAINTU 38 Exit XFAINTU Page Data tables management exits XDTRD, XDTAD, and XDTLC 40 Exit XDTRD 42 Exit XDTAD Exit XDTLC 44 DBCTL interface control program exit XXDFA DBCTL tracking program exits XXDFB and XXDTO Exit XXDFB 46 Exit XXDTO Dispatcher domain exits XDSBWT and XDSAWT Exit XDSBWT Exit XDSAWT DL/I interface program exits XDLIPRE and XDLIPOST 48 Exit XDLIPRE 50 Exit XDLIPOST 52 Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT Exit XDUREQ 54 Page Exit XDUREQC 56 Page 58 Exit XDUCLSE Exit XDUOUT Enqueue EXEC interface program exits XNQEREQ and XNQEREQC Exit XNQEREQ 60 Exit XNQEREQC 62 Page 64 Page Sample exit program, DFH$XNQE 66 EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT The command parameter list 68 Bypassing commands Exit XEIIN Exit XEISPIN 70 Exit XEIOUT Exit XEISPOUT File control domain exits, XFCFRIN and XFCFROUT XFCFRIN 72 XFCFROUT Exit XFCFRIN 74 Page 76 Page 78 Page Exit XFCFROUT 80 Page 82 Page 84 File control EXEC interface API exits XFCREQ and XFCREQC 86 Page 88 Page 90 Modifying fields in the command-level parameter structure Modifying the EID 92 Use of the task token UEPTSTOK Use of the parameter UEPFSHIP The EIB 94 Example of how XFCREQ and XFCREQC can be used Exit XFCREQ Exit XFCREQC 96 Page Example program File control EXEC interface SPI exits XFCAREQ and XFCAREQC 98 Exit XFCAREQ Exit XFCAREQC 100 Page 102 Page 104 Page 106 Modifying fields in the command-level parameter structure |||| 108 Page Modifying the EID Use of the task token UEPTSTOK 110 Modifying user arguments File control file state program exits XFCSREQ and XFCSREQC Exit XFCSREQ 112 Page 114 Page Exit XFCSREQC 116 Page 118 Page 120 File control open/close program exit XFCNREC Using XFCNREC with a back out recovery setting mismatch Using XFCNREC with a BWO mismatch File control quiesce receive exit, XFCVSDS 122 Exit XFCVSDS File control quiesce send exit XFCQUIS 124 Page File control recovery program exits XFCBFAIL, XFCBOUT,XFCBOVER, and XFCLDEL Order of invocation 126 Enabling the exit programs Exit XFCBFAIL, file control backout failure exit 128 Page 130 Exit XFCBOUT, file control backout exit Exit XFCBOVER, file control backout override exit 132 Page 134 Exit XFCLDEL, file control logical delete exit 136 Front End Programming Interface exits XSZARQ and XSZBRQ Good morning message program exit XGMTEXT HTTP client open and send exits: XWBAUTH, XWBOPEN and XWBSNDO 138 Intersystem communication program exits XISCONA and XISLCLQ The XISCONA exit Page 140 The XISLCLQ exit 142 Interval control program exits XICREQ, XICEXP, and XICTENF Exit XICREQ Exit XICEXP 144 Exit XICTENF Interval control EXEC interface program exits XICEREQ, XICERES, and XICEREQC Parameters passed to each of the exits Exit XICEREQ 146 Page Exit XICERES 148 Exit XICEREQC 150 ADDRD Seconds | monthofyear Chapter1. Global user exit programs 151 Figure1. The command-level parameter structure for interval control 152 Page 154 Page 156 Page 158 Page 160 Page Loader domain exits XLDLOAD and XLDELETE 162 Exit XLDLOAD Exit XLDELETE Log manager domain exit XLGSTRM 164 Page Exit XLGSTRM 166 An example of how XLGSTRM can be used The sample program for the XLGSTRM exit, DFH$LGLS Message domain exit XMEOUT 168 Exit XMEOUT 170 The sample XMEOUT global user exit programs Monitoring domain exit XMNOUT Exit XMNOUT 172 Page Pipeline domain exits Exit XWSPRROO Exit-specific parameters 174 Return codes Program control program exits XPCREQ, XPCERES, XPCREQC, XPCFTCH, XPCHAIR, XPCTA, and XPCABND XPCREQ, XPCERES, and XPCREQC 176 Page 178 Page 180 Page 182 Page 184 Page Exit XPCFTCH 186 Page The sample XPCFTCH global user exit program, DFH$PCEX Exit XPCHAIR 188 Page Exit XPCTA 190 The sample XPCTA global user exit program, DFH$PCTA Exit XPCABND 192 Resource manager interface program exits XRMIIN and XRMIOUT Exit XRMIIN Exit XRMIOUT 194 Resource management install and discard exit XRSINDI Exit XRSINDI 196 Page 198 Signon and signoff exits XSNON, XSNOFF, and XSNEX Exit XSNON Exit XSNOFF 200 Exit XSNEX Statistics domain exit XSTOUT Exit XSTOUT 202 System recovery program exit XSRAB 204 Page System termination program exit XSTERM Exit XSTERM 206 Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT Exit XTSQRIN Exit XTSQROUT 208 Page Exit XTSPTIN 210 Exit XTSPTOUT Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC 212 Exit XTSEREQ Exit XTSEREQC 214 Page 216 Page 218 Page 220 Terminal allocation program exit XALCAID Exit XALCAID 222 Terminal control program exits XTCIN, XTCOUT, and XTCATT Exit XTCIN Exit XTCOUT Exit XTCATT Terminal not known condition exits XALTENF and XICTENF 224 The exits Exit XALTENF 226 Page Exit XICTENF 228 Page The sample program for the XALTENF and XICTENF exits, DFHXTENF 230 Page Transaction manager domain exit XXMATT Exit XXMATT 232 Page Transient data program exits XTDREQ, XTDIN, and XTDOUT Exit XTDREQ 234 Exit XTDIN Exit XTDOUT Transient data EXEC interface program exits XTDEREQ and XTDEREQC Example program 236 Exit XTDEREQ Exit XTDEREQC 238 Page 240 Page 242 Page User log record recovery program exits XRCINIT and XRCINPT 244 Coding the exit programs Enabling the exit programs Exit XRCINIT Exit XRCINPT 246 VTAM terminal management program exit XZCATT Exit XZCATT VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE Exit XZCIN 248 Exit XZCOUT Exit XZCOUT1 XZIQUE exit for managing MRO and APPC intersystem queues 250 Page 252 Page 254 Page Designing an XZIQUE global user exit program 256 Page XISQUE exit for managing IPIC intersystem queues When the XISQUE exit is invoked 258 Exit XISQUE Page Using an XISQUE global user exit program 260 Statistics fields in DFHISRDS Designing an XISQUE global user exit program Using IPCONN statistics 262 The sample exit program, DFH$XISQ XRF request-processing program exit XXRSTAT Exit XXRSTAT 264 Page Page Chapter 2. Task-related user exit programs Introduction to the task-related user exit mechanism (the adapter) THEADAPTER 268 The stub program Returning control to the application program Task-related user exits and EDF 270 Writing a task-related user exit program Obligations of OPENAPI task-related user exits Threadsafe restrictions Calling an OPENAPI task-related user exit 272 User exit parameter lists DFHUEPAR 274 Page 276 Page DFHUERTR (the function definition) 278 Caller parameter lists 280 Page 282 Page 284 Summary of the task-related user exit parameter lists Figure7. Task-related user exit parameter lists 286 The schedule flag word Register handling in the task-related user exit program Saving CICS registers 288 The calling programs registers The RMI registers Addressing-mode implications Exit programs and the CICS storage protection facility Execution key for task-related user exit programs 290 Data storage key for task-related user exit programs Recursion within a task-related user exit program Using CICS services in your task-related user exit program Using channels and containers Assembler programs and LEASM 292 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 Increasing efficiency single-update and read-only protocols Return codes 294 What is expected of your resource manager Sample code for a TRUE invoked by the CICS syncpoint manager 296 Resynchronization Coding a program to be invoked by the CICS task manager Coding a program to be invoked at CICS termination 298 Sample code for a TRUE invoked at CICS termination 300 Using EDF with your task-related user exit program Administering the adapter 302 What you must do before using the adapter Enabling for specific invocation-types The administration routines Tracing a task-related user exit program 304 Chapter 3. The user exit programming interface (XPI) Overview of the XPI 306 Page Making an XPI call 308 Page 310 Page Setting up the XPI environment XPI register usage 312 The XPI copy books Reentrancy considerations resulting from XPI calls Global user exit XPI examples, showing the use of storage Page Page 316 Page An example showing how to build a parameter list incrementally 318 XPI syntax 320 Directory domain XPI functions The BIND_LDAP call BIND_LDAP RESPONSE and REASON values for BIND_LDAP: 322 The END_BROWSE_RESULTS call END_BROWSE_RESULTS RESPONSE and REASON values for END_BROWSE_RESULTS: The FLUSH_LDAP_CACHE call FLUSH_LDAP_CACHE The FREE_SEARCH_RESULTS call 324 FREE_SEARCH_RESULTS RESPONSE and REASON values for FREE_SEARCH_RESULTS: The GET_ATTRIBUTE_VALUE call GET_ATTRIBUTE_VALUE RESPONSE and REASON values for GET_ATTRIBUTE_VALUE: The GET_NEXT_ATTRIBUTE call 326 GET_NEXT_ATTRIBUTE RESPONSE and REASON values for GET_NEXT_ATTRIBUTE: The GET_NEXT_ENTRY call GET_NEXT_ENTRY RESPONSE and REASON values for GET_NEXT_ENTRY: The SEARCH_LDAP call 328 SEARCH_LDAP RESPONSE and REASON values for SEARCH_LDAP: The START_BROWSE_RESULTS call START_BROWSE_RESULTS START_BROWSE_RESULTS: The UNBIND_LDAP call 330 UNBIND_LDAP RESPONSE and REASON values for UNBIND_LDAP: Dispatcher XPI functions Synchronization protocols for SUSPEND and RESUME processing The normal synchronization protocol The synchronization protocol and task purge 332 Alternative approach to task purge The ADD_SUSPEND call ADD_SUSPEND 334 RESPONSE and REASON values for ADD_SUSPEND: The SUSPEND call SUSPEND 336 Page RESPONSE and REASON values for SUSPEND: 338 The RESUME call RESUME RESPONSE and REASON values for RESUME: The DELETE_SUSPEND call DELETE_SUSPEND 340 RESPONSE and REASON values for DELETE_SUSPEND: The WAIT_MVS call WAIT_MVS 342 Page RESPONSE and REASON values for WAIT_MVS: The CHANGE_PRIORITY call 344 CHANGE_PRIORITY RESPONSE and REASON values for CHANGE_PRIORITY: Dump control XPI functions The SYSTEM_DUMP call SYSTEM_DUMP RESPONSE and REASON values for SYSTEM_DUMP: 346 The TRANSACTION_DUMP call TRANSACTION_DUMP RESPONSE and REASON values for TRANSACTION_DUMP: 348 Enqueue domain XPI functions The ENQUEUE function ENQUEUE RESPONSE and REASON values for ENQUEUE The DEQUEUE function 350 DEQUEUE RESPONSE and REASON values for DEQUEUE Kernel domain XPI functions The START_PURGE_PROTECTION function START_PURGE_PROTECTION RESPONSE values for START_PURGE_PROTECTION: The STOP_PURGE_PROTECTION function STOP_PURGE_PROTECTION Nesting purge protection calls Loader XPI functions The DEFINE_PROGRAM call DEFINE_PROGRAM 354 RESPONSE and REASON values for DEFINE_PROGRAM: The ACQUIRE_PROGRAM call ACQUIRE_PROGRAM 356 Page RESPONSE and REASON values for ACQUIRE_PROGRAM: The RELEASE_PROGRAM call 358 RELEASE_PROGRAM RESPONSE and REASON values for RELEASE_PROGRAM: The DELETE_PROGRAM call DELETE_PROGRAM RESPONSE and REASON values for DELETE_PROGRAM: Log manager XPI functions 360 The INQUIRE_PARAMETERS call INQUIRE_PARAMETERS RESPONSE and REASON values for INQUIRE_PARAMETERS: The SET_PARAMETERS call SET_PARAMETERS RESPONSE and REASON values for SET_PARAMETERS: Monitoring XPI functions The MONITOR call MONITOR 362 Page RESPONSE and REASON values for MONITOR: The INQUIRE_MONITORING_DATAcall 364 INQUIRE_MONITORING_DATA INQUIRE_MONITORING_DATA: Program management XPI functions The INQUIRE_PROGRAM call 366 INQUIRE_PROGRAM Page 368 Page 370 Page 372 RESPONSE and REASON values for INQUIRE_PROGRAM: The INQUIRE_CURRENT_PROGRAM call INQUIRE_CURRENT_PROGRAM 374 INQUIRE_CURRENT_PROGRAM: The SET_PROGRAM call SET_PROGRAM 376 Page RESPONSE and REASON values for SET_PROGRAM: 378 The START_BROWSE_PROGRAM call START_BROWSE_PROGRAM START_BROWSE_PROGRAM: The GET_NEXT_PROGRAM call GET_NEXT_PROGRAM 380 RESPONSE and REASON values for GET_NEXT_PROGRAM: The END_BROWSE_PROGRAM call END_BROWSE_PROGRAM RESPONSE and REASON values for END_BROWSE_PROGRAM: The INQUIRE_AUTOINSTALL call INQUIRE_AUTOINSTALL 382 RESPONSE and REASON values for INQUIRE_AUTOINSTALL: The SET_AUTOINSTALL call SET_AUTOINSTALL RESPONSE and REASON values for SET_AUTOINSTALL: State data access XPI functions The INQ_APPLICATION_DATA call 384 INQ_APPLICATION_DATA Page RESPONSE and REASON values for INQ_APPLICATION_DATA: The INQUIRE_SYSTEM call 386 The INQUIRE_SYSTEM call gives you access to CICS system data in the AP domain. INQUIRE_SYSTEM Page 388 Page RESPONSE and REASON values for INQUIRE_SYSTEM 390 The SET_SYSTEM call SET_SYSTEM RESPONSE and REASON values for SET_SYSTEM: Storage control XPI functions 392 The GETMAIN call GETMAIN RESPONSE and REASON values for GETMAIN: 394 The FREEMAIN call FREEMAIN RESPONSE and REASON values for FREEMAIN: The INQUIRE_ACCESS call INQUIRE_ACCESS The INQUIRE_ELEMENT_LENGTH call 396 INQUIRE_ELEMENT_LENGTH INQUIRE_ELEMENT_LENGTH: The INQUIRE_SHORT_ON_STORAGE call INQUIRE_SHORT_ON_STORAGE INQUIRE_SHORT_ON_STORAGE: The INQUIRE_TASK_STORAGE call 398 INQUIRE_TASK_STORAGE RESPONSE and REASON values for INQUIRE_TASK_STORAGE: The SWITCH_SUBSPACE call SWITCH_SUBSPACE RESPONSE and REASON values for SWITCH_SUBSPACE: Trace control XPI function The TRACE_PUT call TRACE_PUT 400 RESPONSE values for TRACE_PUT Transaction management XPI functions The INQUIRE_CONTEXT call INQUIRE_CONTEXT RESPONSE and REASON values for INQUIRE_CONTEXT: 402 The INQUIRE_DTRTRAN call INQUIRE_DTRTRAN RESPONSE and REASON values for INQUIRE_DTRTRAN: The INQUIRE_MXT call INQUIRE_MXT RESPONSE and REASON values for INQUIRE_MXT: 404 The INQUIRE_TCLASS call INQUIRE_TCLASS RESPONSE and REASON values for INQUIRE_TCLASS: The INQUIRE_TRANDEF call 406 INQUIRE_TRANDEF Page 408 Page 410 Page 412 Page RESPONSE and REASON values for INQUIRE_TRANDEF: The INQUIRE_TRANSACTION call 414 INQUIRE_TRANSACTION Page 416 Page RESPONSE and REASON values for INQUIRE_TRANSACTION: The SET_TRANSACTION call 418 SET_TRANSACTION RESPONSE and REASON values for SET_TRANSACTION: User journaling XPI function The WRITE_JOURNAL_DATA call WRITE_JOURNAL DATA RESPONSE and REASON values for WRITE_JOURNAL_DATA: 420 Page Page Page Page Chapter 4. Writing initialization and shutdown programs Writing initialization programs First-phase PLT programs Second phase PLT programs 426 Effect of delayed recovery on PLTPI processing Writing shutdown programs First phase PLT programs 428 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 Execution key for PLT programs Non-Java Programs Java Programs 430 Data storage key for PLT programs Page Page Page Chapter 5. General notes about user-replaceable programs Rewriting user-replaceable programs Assembling and link-editing user-replaceable programs 436 User-replaceable programs and the storage protection facility Execution key for user-replaceable programs Data storage key for user-replaceable programs 438 Chapter 6. Writing a program error program 440 Page 442 The sample program error programs Page Chapter 7. Writing a transaction restart program The DFHREST communications area 446 The CICS-supplied transaction restart program Page Chapter 8. Writing a terminal error program Background to error handling for sequential devices When an abnormal condition occurs Terminal control program Terminal abnormal condition program 450 Terminal error program The communication area Terminal abnormal condition line entry (TACLE) The sample terminal error program Components of the sample terminal error program TEP error table 452 TEP default table Structure of the sample terminal error program Entry and initialization Terminal ID and error code lookup 454 Error processor selection Error processing execution General exit Common subroutines Sample terminal error program messages 456 Page Generating the sample terminal error program 458 Job control for generating the sample terminal error program DFHTEPMgenerating the sample DFHTEP module 460 Page DFHTEPM TYPE=ENTRY and EXITfor user entry and exit routines DFHTEPM TYPE=ERRPROCreplacing error processors 462 DFHTEPM TYPE=FINALending the sample DFHTEP module DFHTEPM macro examples DFHTEPTgenerating the sample DFHTEP tables 464 DFHTEPT TYPE=INITIALestablishing the control section DFHTEPT TYPE=PERMTIDassigning permanent terminal error blocks DFHTEPT TYPE=PERMCODE|ERRCODEdefining error status elements 466 Page DFHTEPT TYPE=BUCKETusing the error bucket for specific errors 468 DFHTEPT TYPE=FINALterminating DFHTEPT entries DFHTEPTexamples of how the macros are used Writing your own terminal error program Why write your own terminal error program? 470 Restrictions on the use of EXEC CICS commands Addressing the contents of the communication area Resetting the flags in the user action byte, TEPCAACT 472 Addressing the contents of the TACLE 474 Example of a user-written terminal error program DFHTEP recursive retry routine 476 Page 478 Chapter 9. Writing a node error program Background to CICS-VTAM error handling Why use a NEP to supplement CICS default actions? 480 An overview of writing a NEP The default NEP The sample NEP 482 The node error table Coding the sample NEP 484 Multiple NEPs When an abnormal condition occurs 486 The communication area 488 Page 490 The user option bytes (TWAOPTL) 492 Page Additional information for the NEP (TWAADINF) 494 The additional system parameters (TWASYSPM) XRF parameters (TWAXRNOT) The sample node error program Compatibility with the sample terminal error program 496 Components of the sample node error program Entry section Routing mechanism Node error table Optional common subroutines Optional error processors for 3270 logical units 498 Optional error processor for interactive logical units Generating the sample node error program DFHSNEP TYPE=USTOR and USTORENDdefining user storage DFHSNEP TYPE=INITIALgenerating the routing mechanism DFHSNEP TYPE=DEF3270including error processors for 3270 LUs 500 DFHSNEP TYPE=DEFILUincluding error processors for INTLUs DFHSNEP TYPE=FINALterminating DFHSNEP entries DFHSNEP TYPE=ERRPROCspecifying a user error processor 502 DFHSNETgenerating the node error table DSECTs 504 Writing your own node error program Restrictions on the use of EXEC CICS commands Entry and addressability Coding for the 3270 unavailable printer condition 506 Coding for session failures Coding for specific VTAM sense codes Writing multiple NEPs 508 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 510 How DFHZNAC passes the DFHZC2351 reason code to DFHZNEP How DFHZNEP can modify the force-close action for the current terminal The node error program with persistent session support Changing the recovery notification Changing the recovery message Changing the recovery transaction 512 Using the node error program with VTAM generic resources Page Page Chapter 10. Writing a program to control autoinstall of terminals Autoinstalling terminalspreliminary considerations Coding entries in the VTAM LOGON mode table Using model terminal support (MTS) 516 Coding entries for MTS The autoinstall control program for terminals The communication area at INSTALL for terminals 518 How CICS builds the list of autoinstall models Returning information to CICS 520 Selecting the autoinstall model Setting the TERMINAL name 522 CICS action on return from the control program 524 The communication area at DELETE for terminals Testing and debugging 526 The sample autoinstall control programs for terminals Customizing the sample program Assembler language 528 Page COBOL 530 PL/I 532 Page Page Chapter 11. Writing a program to control autoinstall of consoles Autoinstalling consolespreliminary considerations Leaving it all to CICS Using an autoinstall control program The communication area at INSTALL for consoles 536 Page How CICS builds the list of autoinstall models Returning information to CICS 538 Selecting the autoinstall model Setting the TERMINAL name CICS action on return from the control program 540 Page Page Chapter 12. Writing a program to control autoinstall of APPC connections Autoinstalling APPC connectionspreliminary 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 544 Requirements for autoinstall The autoinstall control program for APPC connections Recovery and restart The communication area at INSTALL for APPC connections 546 Page 548 When autoinstalled APPC connections are deleted Single-session connections installed via a CINIT Synclevel 1 connections installed via a BIND Synclevel 2 connections installed via a BIND 550 The sample autoinstall control program for APPC connections Default actions of the sample program Resource definitions Page Chapter 13. Writing a program to control autoinstall of IPIC connections Autoinstalling IPIC connections: preliminary considerations Autoinstall templates for IPCONNs Requirements for autoinstall When the user program is invoked 554 The autoinstall user program for IPCONNs Recovery and restart The autoinstall user program at INSTALL The communication area at INSTALL for IPCONNs The autoinstall user program at DELETE 556 When autoinstalled IPCONNs are deleted The sample autoinstall user program for IPIC connections (IPCONN) Default actions of the sample program At INSTALL 558 At DELETE Resource definitions Chapter 14. Writing a program to control autoinstall of shipped terminals Installing shipped terminals and connections CICS-generated aliases Resetting the terminal identifier 560 Example The communications area at INSTALL for shipped terminals 562 Page 564 Default actions of the sample programs Page Chapter 15. Writing a program to control autoinstall of virtual terminals How Client virtual terminals are autoinstalled Autoinstall models Terminal identifiers Why override TERMIDs? Overriding CICS-generated TERMIDs 568 Overriding Client-specified TERMIDs How bridge facility virtual terminals are autoinstalled Using the terminal autoinstall control program for bridge facilities 570 Autoinstall of a START bridge facility Autoinstall of a Link3270 bridge facility Bridge facility name uniqueness The communications area at INSTALL for Client virtual terminals 572 The communications area at INSTALL for bridge facility virtual terminals 574 The communications area at DELETE for Client virtual terminals The communications area at DELETE for bridge facility virtual terminals 576 Default actions of the sample programs Page Chapter 16. Writing a program to control autoinstall of programs Autoinstalling programspreliminary considerations Autoinstall model definitions Autoinstalling programs invoked by EXEC CICS LINK commands 580 Autoinstall processing of mapsets System autoinstall Benefits of autoinstalling programs Reduced system administration costs Saving in virtual storage Faster startup times Warm and emergency starts 582 Initial and cold starts Requirements for program autoinstall Page 584 Page The sample autoinstall control program for programs, DFHPGADX Customizing the sample program 586 Resource definition Testing and debugging your program 588 Chapter 17. Writing a dynamic routing program Routing transactions dynamically Dynamic transactions 590 When the dynamic routing program is invoked Information passed to the dynamic routing program Using a common transaction definition in the TOR 592 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 594 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 596 Monitoring the output TIOA Unit of work considerations Routing DPL requests dynamically When the dynamic routing program is invoked 598 Changing the program name Changing the transaction ID Telling CICS whether to route or terminate a DPL request 600 Special casecare! Using the XPCERES exit to check the availability of resources on the Invoking the dynamic routing program at end of routed requests Modifying the applications input communications area 602 Monitoring the applications output communications area Unit of work considerations Routing bridge requests dynamically Changing bridge request parameters Changing the Link3270 bridge request SYSID 604 Changing the bridge request TRANSID Changing the Link3270 bridge request transaction priority 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 Re-invoking the dynamic routing program after Link3270 bridge requests Link3270 bridge dynamic routing considerations 606 Modifying the applications containers Routing by user ID Parameters passed to the dynamic routing program 608 Page 610 Page 612 Page 614 Page 616 Page 618 Page 620 Naming your dynamic routing program Testing your dynamic routing program Dynamic transaction routing sample programs 622 Chapter 18. Writing a distributed routing program Differences between the distributed and dynamic routing interfaces 624 Routing BTS activities Which BTS activities can be dynamically routed? 626 Telling CICS whether to route the activity 628 Routing method requests for enterprise beans and CORBA stateless objects Where workload balancing occurs Local and remote clients 630 Page 632 Page Telling CICS whether to route the method request 634 Dealing with a disabled CorbaServer 636 Performing a rolling upgrade of an EJB/CORBA server Routing non-terminal-related START requests 638 Telling CICS whether to route the request Using the XICERES exit to check the availability of resources on the 640 Routing inbound Web service requests 642 Telling CICS whether to route the request Routing by user ID Dealing with an abend on the target region 644 Parameters passed to the distributed routing program 646 Page 648 Page 650 Page 652 Page 654 Page Naming your distributed routing program 656 Distributed transaction routing sample programs Page Chapter 19. Writing a CICSDBCTL interface status program The sample CICSDBCTL interface status program 660 Chapter 20. Writing a 3270 bridge exit program Page Chapter 21. Writing a security exit program for IIOP 664 The sample programs DFHXOPUS Page Chapter 22. Writing programs to customize JVMs Writing Java classes to redirect JVM stdout and stderr output The com.ibm.cics.server.OutputRedirectionPlugin interface 668 Possible destinations for output Handling output redirection errors and internal errors Using DFHJVMRO to modify the Language Environment enclave for a JVM 670 Using DFHJVMAT to modify options in a JVM profile Options in the JVM profile that are available to DFHJVMAT 672 Page 674 Chapter 23. Writing a distinguished name program for clients of enterprise beans 676 Sample programs and copy books Page Chapter 24. Writing an EJB event program Overview of the EJB event program The DFHEJEP communications area 680 Event codes Table36 shows the codes and meanings of all EJB events that may be passed to the EJB event program. The EJB event sample program Actions of the default program Writing your own EJB event program 682 Page Page Chapter 25. Writing programs to customize Language Environment run-time options for XPLink programs DFHAPXPO Defining run-time options Page Page Page Chapter 26. The extended recovery facility overseer program The sample XRF overseer program The functions of the sample program The display function 690 The restart-in-place function Opening CAVM data sets dynamically 692 How the sample overseer program interfaces with CICS How to tell the overseer which actives and alternates to monitor 694 The DFHWOSM macros The DFHWOSM tokens DFHWOSM FUNC=BUILD macro DFHWOSM FUNC=CLOSE macro 696 DFHWOSM FUNC=DSECT macro DFHWOSM FUNC=JJC macro DFHWOSM FUNC={JJS|QJJS} macro DFHWOSM FUNC=OPEN macro 698 DFHWOSM FUNC=OSCMD macro DFHWOSM FUNC=READ macro 700 Page Reading DBCTL status information from the CAVM data sets 702 DFHWOSM FUNC=TERM macro Customizing the sample XRF overseer program 704 Loop or wait detection Assembling and link-editing the overseer program Page Page 708 Chapter 27. CICS logging and journaling The CICS log manager Log stream storage 710 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 712 SMF records Format of general log block header Format of general log journal record 714 Page Start-of-run record Format of caller data 716 Caller data written by file control Read-only, read-update, write-update, write-add, write-add complete record types 718 Page 720 Write-delete record types File-close record types 722 Page Tie-up record types 724 FLJB_TUR_BASE_CI_SIZE 4-byte CI size of base data set. Figure86. Format of TIE_UP_RECORD_DATA section Chapter27. CICS logging and journaling 725 Terminal control prefix data 726 FEPI prefix data 728 Structure and content of COMPAT41-format journal records SMF records Format of COMPAT41 journal control label header 730 32 JCRLL 2-byte length of record. X'0000' 2-bytes containing X'0000'. Fixedlength 104 Format of journal record 732 Page 734 Page 736 Identifying records for the start of tasks and UOWs Format of journal records written to SMF The SMF block header 738 Page The CICS product section 740 Page The CICS data section 742 Chapter 28. CICS monitoring Introduction to CICS monitoring How CICS monitoring data is passed to SMF Coding additional event-monitoring points Application naming event monitoring points 744 Examples of invoking application naming EMPs 746 The monitoring control table (MCT) DFHMCT TYPE=EMP DFHMCT TYPE=RECORD 748 Examples of MCT coding with MONITOR commands Example 1: Starting a user clock DFHMCT TYPE=EMP entries for DBCTL CICS monitoring record formats SMF header and SMF product section 750 Page 752 Page CICS data section Dictionary data sections 754 Page Page Page 758 Page 760 Performance data sections Relationship of the dictionary record to the performance records: field connectors 762 How the string of field connectors is constructed Exception data sections 764 Transaction resource data sections 766 Page 768 Chapter 29. 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 770 CICS statistics record format SMF header and SMF product section 772 CICS statistics data section Page Page Using an XSTOUT global user exit program to filter statistics records 776 Processing the output from CICS statistics Page Page 780 Chapter 30. The dynamic allocation sample program Overview of the dynamic allocation program Installing the program and transaction definitions The dynamic allocation programterminal operation 782 Using the dynamic allocation programs Help feature The dynamic allocation programvalues Abbreviation rules for keywords System programming considerations 784 The flow of control when a DYNALLOC request is issued Page Page Page 788 Chapter 31. Invoking an external security manager An overview of the CICS-ESM interface The MVS router The MVS router exit The MVS router parameter list Router exit return codes 790 Passing control to a user-supplied ESM 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 792 The installation data parameter list 794 Page CICS security control points 796 Using early verification processing Writing an early verification routine 798 Using CICS API commands in an early verification routine Return and reason codes from the early verification routine Page Chapter 32. Writing a good night program The communications area of the good night program 802 The sample good night program, DFH0GNIT What the sample program does Customizing the sample good night program 804 Page Page Page 808 Chapter 33. Using the programmable interface to CEDA When to use the programmable interface Using DFHEDAP in a DTP environment 810 Page Page Chapter 34. 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 814 The EXTRACT command When the user program is invoked Parameters passed from DFHCSDUP to the user program The sample EXTRACT programs 816 Page The CSD cross-referencing program The DB2 formatting program 818 The CSD backup utility program Assembling and link-editing EXTRACT programs An assembler-language version A Language Environment version 820 Invoking DFHCSDUP from a user program Entry parameters for DFHCSDUP 822 Page Responsibilities of the user program The user exit points in DFHCSDUP 824 Parameters passed to the user exit routines The initialization exit The get-command exit The extract exit 826 The put-message exit The termination exit 828 The sample program, DFH$CUS1 Page Page Page 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 834 VTAM MODEENT macro operands 836 Page 838 Page PSERVIC screen size values for LUTYPEx devices 840 Matching models and LOGON mode entries 842 Page 844 Page 846 Page 848 Page LOGON mode definitions for CICS-supplied autoinstall models 850 Page 852 Page Page Appendix B. Default actions of the node abnormal condition program DFHZNACdefault actions for terminal error codes 856 Page 858 Page 860 CICS messages associated with VTAM errors 862 Page 864 Page DFHZNACdefault actions for system sense codes 866 Page Action flag settings and meanings 868 Page Page Appendix C. Analyzing CICS restart information Page Appendix D. Using the transient data write-to-terminal program (DFH$TDWT) DFH$TDWTresource definitions required Page Appendix E. Uppercase translation Translating national characters to uppercase Using the XZCIN exit Using DFHTCTxx Translating TS data sharing messages to uppercase 876 Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE 878 Page 880 Page 882 Page 884 Page 886 Page 888 Page 890 Page 892 Appendix G. Threadsafe XPI commands Page Bibliography The CICS Transaction Server for z/OS library The entitlement set PDF-only books CICS books for CICS Transaction Server for z/OS CICSPlex SM books for CICS Transaction Server for z/OS 896 CICS family books Licensed publications Other CICS books Books from related libraries MVS books VTAM books Other related books 898 Determining if a publication is current Page Page Accessibility Page Index Special characters Numerics A B C 904 D 906 Page 908 E F G 910 I J K L M N 912 Page O P 914 Q R S T 916 Page U 918 V W X 920 Page Page Notices Page Trademarks Page Readers Comments We'd Like to Hear from You Readers Comments We'd Like to Hear from You ___________________________________________________________________________________________________ SC34-6814-04