IBM SC33-1683-02 The SUSPEND call

RESPONSE and REASON values for ADD_SUSPEND:

RESPONSE REASON

OK None

EXCEPTION None

DISASTER None

INVALID None

KERNERROR None

PURGED None

Note: For more detail, refer to the explanation of RESPONSE and REASON in

“General form of an XPI call” on page286.

The SUSPEND call

SUSPEND suspends execution of a running task. The task can be resumed in one

of two ways. Youcan issue the XPI RESUME call, or the task is resumed

automatically if the INTERVALvalue that you specify on the DFHDSSRX macro

expires. Suspended tasks can also be purged by the operator, or by an application,

or by the deadlock time-out facility.

SUSPEND

DFHDSSRX [CALL,]

[CLEAR,]

[IN,

FUNCTION(SUSPEND),

PURGEABLE(YES|NO),

SUSPEND_TOKEN(name4 | (Rn)),

[INTERVAL(name4 | (Rn)),]

[RESOURCE_NAME(name16 | string | 'string'),]

[RESOURCE_TYPE(name8 | string | 'string'),]

[TIME_UNIT(SECOND|MILLI_SECOND),]

[WLM_WAIT_TYPE,]]

[OUT,

[COMPLETION_CODE(name1 | (Rn)),]

RESPONSE(name1 | *),

REASON(name1 | *)]

COMPLETION_CODE (name1 | (Rn))

returns a user-deﬁned “reason for action” code during suspend and resume

processing.

name1 The name of a 1-byte area to receive the code. The value in this ﬁeld is

user-deﬁned, and is ignored by CICS.

(Rn) A register in which the low-order byte contains the completion code and

the other bytes are zero.

INTERVAL(name4| (Rn))

speciﬁes in seconds or milliseconds the time after which the task is

automatically resumed and given a RESPONSE value of ‘PURGED’ and a

REASON value of ‘TIMED_OUT’. The time unit used on the INTERVALoption

depends on the setting of the TIME_UNIT option. The INTERVALvalue

overrides any time-out (DTIMOUT) value speciﬁed for the transaction.

name4 The name of a 4-byte area, which is interpreted as a binary fullword.

dispatcher functions

304 CICS TS for OS/390: CICS Customization Guide

Contents

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