IBM SC33-1683-02 manual

CIC S® T ransa ct i o n Se rv er f o r OS /39 0® CI CS C u st o miz a ti o n G ui d e Relea se 3 SC33-1683-02 IBM[...]

[...]

CIC S® T ransa ct i o n Se rv er f o r OS /39 0® CI CS C u st o miz a ti o n G ui d e Relea se 3 SC33-1683-02 IBM[...]

Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page xvii. Third edition (March 1999) This edition applies to Release 3 of CICS T ransaction Server for OS/390, program number 5655-147, and to all subsequent versions, releases, and modifications until otherwise indicate[...]

Contents Notices ........................... xvii Programming interface information ................. xviii T rademarks .......................... x i x Preface ........................... x x i What this book is about ..................... x x i Who this book is for ....................... x x i What you need to know to understand this book ......[...]

Exit XBMIN ......................... 2 8 Exit XBMOUT ........................ 2 8 The field element table structure ................. 2 9 Programming the XBMIN exit .................. 3 0 Programming the XBMOUT exit ................. 3 0 Bridge facility exit ....................... 3 2 Exit XF AINTU ........................ 3 2 Data tables managem[...]

Modifying user arguments ................... 9 5 File control file state program exits XFCSREQ and XFCSREQC ...... 9 6 Exit XFCSREQ ....................... 9 7 Exit XFCSREQC ....................... 1 0 0 File control open/close program exit XFCNREC ............ 1 0 5 Exit XFCNREC ....................... 1 0 6 File control quiesce receive exit, XFC[...]

Exit XSTOUT ........................ 1 8 0 System recovery program exit XSRAB ................ 1 8 2 Exit XSRAB ......................... 1 8 2 System termination program exit XSTERM .............. 1 8 6 Exit XSTERM ........................ 1 8 6 T emporary storage domain exits XTSQRIN, XTSQROUT , XTSPTIN, and XTSPTOUT ......................... 1 8[...]

Introduction to the task-related user exit mechanism (the adapter) ...... 2 4 9 The stub program ....................... 2 5 0 Returning control to the application program ............. 2 5 1 T ask-related user exits and EDF ................. 2 5 2 The task-related user exit program ................. 2 5 2 User exit parameter lists ................[...]

The INQUIRE_P ARAMETERS call ................ 3 2 9 The SET_P ARAMETERS call .................. 3 2 9 Monitoring functions ....................... 3 3 0 The MONITOR call ...................... 3 3 0 The INQUIRE_MONITORING_DA T A call .............. 3 3 3 Program management functions .................. 3 3 4 The INQUIRE_PROGRAM call ................[...]

Rewriting user-replaceable programs ................ 4 0 1 Assembling and link-editing user-replaceable programs .......... 4 0 2 User-replaceable programs and the storage protection facility ....... 4 0 5 Execution key for user-replaceable programs ............ 4 0 5 Data storage key for user-replaceable programs ........... 4 0 6 Chapter 6. Writi[...]

The node error program in an XRF environment ........... 4 8 0 The node error program with persistent session support ........ 4 8 1 Changing the recovery notification ................ 4 8 1 Changing the recovery message ................. 4 8 2 Changing the recovery transaction ................ 4 8 2 Using the node error program with VT AM generic[...]

Installing shipped terminals and connections ............. 5 2 3 CICS-generated aliases .................... 5 2 4 Resetting the terminal identifier ................. 5 2 4 The autoinstall control program at INST ALL .............. 5 2 5 The communications area at INST ALL for shipped terminals ....... 5 2 6 The autoinstall control program at DELE[...]

Changing the transaction ID ................... 5 6 0 T elling CICS whether to route or terminate a DPL request ........ 5 6 0 If an error occurs in route selection ................ 5 6 1 Invoking the dynamic routing program at end of routed requests ..... 5 6 1 Modifying the application’s input communications area ......... 5 6 1 Monitoring the [...]

DFHWOSM FUNC=CLOSE macro ................ 6 1 6 DFHWOSM FUNC=DSECT macro ................ 6 1 6 DFHWOSM FUNC=JJC macro .................. 6 1 6 DFHWOSM FUNC={JJS|QJJS} macro ............... 6 1 7 DFHWOSM FUNC=OPEN macro ................. 6 1 8 DFHWOSM FUNC=OSCMD macro ................ 6 1 8 DFHWOSM FUNC=READ macro ................. 6 1 9 DFHWOSM FU[...]

Part 6. Customizing CICS compatibility interfaces ............... 6 8 9 Chapter 26. Using TCAM with CICS ................ 6 9 1 CICS with TCAM SNA ...................... 6 9 2 Protocol management ..................... 6 9 2 Function management header processing .............. 6 9 3 Batch processing ....................... 6 9 4 Error processing for[...]

Chapter 29. Writing a “good night” program ............ 7 3 3 The sample “good night” program, DFH0GNIT ............. 7 3 5 What the sample program does ................. 7 3 6 Customizing the sample program ................. 7 3 6 Part 8. Examining and modifying resource attributes ............. 7 3 9 Chapter 30. User programs for the syst[...]

Index ............................ 8 2 3 Sending your comments to IBM ................. 8 4 1 xvi CICS TS for OS/390: CICS Customization Guide[...]

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or [...]

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Programming License Agreement, or any equivalent agreement between us. This book contains sample programs. Permission is hereby granted to copy and store the sample programs into[...]

T rademarks The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both: ACF/VT AM IMS BookManager IMS/ESA C/370 Language Environment CICS MVS/ESA CICS/ESA MQSeries CICSPlex OS/390 DB2 RACF DFSMS System/370 IBM VT AM Java and all Java-based trademarks and logos are trademarks o[...]

xx CICS TS for OS/390: CICS Customization Guide[...]

Preface What this book is about This book provides the information needed to extend and modify an IBM® CICS® T ransaction Server for OS/390® system to match your requirements. It describes how you can tailor your system by coding exit programs, by replacing specific CICS-supplied default programs with versions that you write yourself, and by ad[...]

CICS T ransaction Server for OS/390 Release 3 supports CICS applications written in: v Assembler language v C v COBOL v PL/I. In this book, the phrase “the languages supported by CICS” refers to the above languages. Syntax notation and conventions used in this book The symbols { }, [ ], and | are used in the syntax descriptions of the EXEC CICS[...]

Bibliography CICS T ransaction Server for OS/390 CICS T ransaction Server for OS/390: Planning for Installation GC33-1789 CICS T ransaction Server for OS/390: Release Guide GC34-5352 CICS T ransaction Server for OS/390: Migration Guide GC34-5353 CICS T ransaction Server for OS/390: Installation Guide GC33-1681 CICS T ransaction Server for OS/390: P[...]

CICSPlex SM books for CICS T ransaction Server for OS/390 General CICSPlex SM Master Index SC33-1812 CICSPlex SM Concepts and Planning GC33-0786 CICSPlex SM User Interface Guide SC33-0788 CICSPlex SM View Commands Reference Summary SX33-6099 Administration and Management CICSPlex SM Administration SC34-5401 CICSPlex SM Operations Views Reference SC[...]

MVS books Short Title Full Title Assembler Programming Guide OS/390 MVS Assembler Services Guide , GC28-1762 Authorized Assembler Programming Guide OS/390 MVS Authorized Assembler Services Guide , GC28-1763 Authorized Assembler Programming Reference V olume 1 OS/390 MVS Authorized Assembler Services Reference ALE-DYN , GC28-1764 Authorized Assemble[...]

Determining if a publication is current IBM regularly updates its publications with new and changed information. When first published, both hardcopy and BookManager softcopy versions of a publication are usually in step. However , due to the time required to print and distribute hardcopy books, the BookManager version is more likely to have had la[...]

Summary of changes This book is based on the Customization Guide for CICS T ransaction Server for OS/390 Release 2, SC33-1683-01. Changes from that edition are indicated by vertical bars in the left margin. Changes for this edition These are the most significant changes for this edition: v The following new global user exits are described in “Ch[...]

- XEISPOUT – In the file control recovery program: - XFCAREQ - XFCAREQC – In the 3270 bridge facility management program: - XF AINTU v The following new exit programming interface (XPI) function calls were introduced: – INQUIRE_CONTEXT v A new user-replaceable program was described in “Chapter 19. Writing a 3270 bridge exit program” on p[...]

The following global user exits became obsolete: – XDBDERR – XDBFERR – XDBIN – XDBINIT – XJCWB – XJCWR – XKCREQ – XRCFCER – XRCOPER – XTSIN – XTSOUT – XTSREQ v Changes to task-related user exits : “Chapter 2. T ask-related user exit programs” on page 249 describes how task-related user exits can be invoked for SPI calls;[...]

– The descriptions of fields in CICS-produced monitoring records, previously in “Chapter 24. CICS monitoring” on page 657, were moved to the CICS Performance Guide . xxx CICS TS for OS/390: CICS Customization Guide[...]

Part 1. Customizing with user exit programs © Copyright IBM Corp. 1977, 1999 1[...]

2 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 1. Global user exit programs This chapter describes the CICS global user exit points , and how you can use them, in conjunction with programs of a special type that you write yourself ( global user exit programs ), to customize your CICS system. The chapter is divided into the following sections: 1. “Overview — what is a global user exi[...]

Each global user exit point has a unique identifier , and is located at a point in the module or domain at which it could be useful to do some extra processing. For example, at exit point XSTOUT in the statistics domain, an exit program can be given control before each statistics record is written to the SMF data set, and can access the relevant s[...]

v Register 15 contains the entry address of the exit program. No other register values are guaranteed, and they should not be relied on. The exit program should save and restore any registers that it modifies, using the save area addressed by register 13. 31-bit addressing implications v The global user exit is invoked in 31-bit AMODE. v The globa[...]

All exit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See “Returning values to CICS” on page 10. Important v If your global user exit program does not contain EXEC CICS commands, do not use the CICS command-level translator when assembling the pro[...]

Application programs can communicate with user exit programs that use or share the same global work area. The application program uses the EXEC CICS EXTRACT EXIT command to obtain the address and length of the global work area. A work area is freed only when all of the exit programs that use it are disabled. For examples of how to use a global work[...]

If your exit program is to be invoked at every global user exit point, you can code: DFHUEXIT TYPE=EP,ID=ALL If your user exit program is to be used both as a global user exit program and as a task-related user exit program, you must code both: DFHUEXIT TYPE=EP,ID=exit_point_identifier and: DFHUEXIT TYPE=RM (in this order) to generate the DSECT s a[...]

UEPTCA points to fetch-protect storage. Use of this field results in an abend ASRD at execution time. UEPCSA points to fetch-protect storage. Use of this field results in an abend ASRD at execution time. UEPEPSA points to a save area in which the exit program should store its own registers on entry . When the exit program is entered, register 13 [...]

T able 1. TCB indicators in DFHUEP AR (continued). Description Symbolic value 2-byte code Description UEPTRP RP The ONC/RPC mode TCB UEPTSZ SZ The FEPI mode TCB UEPTJ8 J8 The JVM mode TCB UEPTL8 L8 An open mode TCB UEPTSL SL The sockets listener mode TCB UEPTSO SO The sockets mode TCB UEPTS8 S8 The secure sockets layer mode TCB UEPST ACK points to [...]

as if the exit program had not been invoked, and it is a valid option at most global user exit points. The exceptions are shown in the list of return codes provided with each exit description. The return code currently established for an exit is addressed by parameter UEPCRCA of DFHUEP AR, and it is needed when two or more exit programs are used at[...]

program (via a link or transfer-control command), the program thus invoked is executed according to the execution key (EXECKEY) defined in its program resource definition. Important Y ou are strongly recommended to specify EXECKEY(CICS) when defining both global user exit programs and programs to which an exit program passes control. Data storag[...]

recursive command (such as a TS command at exit point XTSEREQ). The exits most likely to be affected provide a recursion count parameter , UEPRECUR, that you can use to prevent such loops. Important When coding user exit programs, you should bear in mind that the code is executed as an extension of CICS code, rather than as a transaction, and any e[...]

The following rules apply to return codes if a second user exit program sets a different return code value from that selected by the previous program: – If the new program supplies the same return code value as the current return code (addressed by UEPCRCA), then CICS acts on that value. – If the new program supplies a different return code val[...]

Global work area (GW A) sample exit programs This set of sample programs shows you how to: v Enable a global user exit program and allocate a global work area (GW A). v Obtain the address of an exit program’s GW A. v Access CICS system information, and make that information available to other global user exit programs. v Share a GW A between glob[...]

Most of the above information is obtained using EXEC CICS API commands such as: – INQUIRE SYSTEM – ASSIGN – ADDRESS – ASKTIME – FORMA TTIME. v Uses the ST ART option of the EXEC CICS ENABLE command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINKs and XCTLs. v Links to the dummy program, DFH$PCPL, i[...]

DFH$PCPI is designed to be run as a PL T program. If you write a similar program, you should define it in the second part of the PL TPI list (after the PROGRAM=DFHDELIM entry). Information about how to do this is in the CICS Resource Definition Guide . The Basic Mapping Support sample exit program CICS supplies a sample global user exit program f[...]

DFH$FCBV A sample exit program designed to be invoked at the XFCBOVER exit; it allows you to decide whether to allow an update to be backed out, following a batch update run that has overridden retained locks. See “DFH$FCBV sample global user exit program” on page 121. DFH$FCLD A sample exit program designed to be invoked at the XFCLDEL exit, w[...]

The terminal-not-known sample exit program Y ou can use this sample global user exit program to handle terminal-not-known conditions arising from ST ART and A TI requests: DFHXTENF A sample global user exit program, designed to be invoked at the XAL TENF or XICTENF exit. The sample source code is shown on page “The sample program for the XAL TENF[...]

T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XDSA WT Dispatcher domain After an operating system wait. 42 XDSBWT Before an operating system wait. 42 XDT AD Data tables management When a write request is issued to a data table. 36 XDTLC At the completion of loading of a data[...]

T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XFCBF AIL File control recovery control program When an error occurs during the backout of a UOW . 11 2 XFCBOUT When CICS is about to back out a file update. 11 7 XFCBOVER When CICS is about to skip backout of a UOW because a ba[...]

T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XISCONA Intersystem communication program When a function shipping or DPL request is about to be queued because no sessions to the remote region are immediately available. 127 XISLCLQ After an attempt to allocate a session for a [...]

T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XRMIIN Resource manager interface program Before execution of an EXEC DLI, EXEC SQL, or RMI command. 171 XRMIOUT After execution of an EXEC DLI, EXEC SQL, or RMI command. 171 XRSINDI Resource management modules Immediately after [...]

T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XXDFB DBCTL tracking program In the alternate CICS when DBCTL fails. 40 XXDTO In the alternate CICS when active DBCTL fails. 41 XXMA TT Transaction manager domain When a user transaction is attached. 216 XXRST A T XRF request pro[...]

Activity keypoint program exit XAKUSER The XAKUSER exit is invoked during the activity keypointing process. Y ou can use this exit to record, on the system log, user data that must be restored following an emergency restart. For further information about the use of the exit, see the CICS Recovery and Restart Guide . For best performance, journal co[...]

WRITE JOURNALNAME. Important Only the listed EXEC CICS commands are allowed in the XAKUSER exit. The exit should link only to other programs with the same restrictions. activity keypoint program exit 26 CICS TS for OS/390: CICS Customization Guide[...]

Basic Mapping Support exits XBMIN and XBMOUT The XBMIN exit allows you to intercept a RECEIVE MAP request after BMS has successfully processed the request. The XBMOUT exit allows you to intercept a SEND MAP request after BMS has successfully processed the request; or , if cumulative mapping is in progress, on completion of each page of output. The [...]

Sample program, DFH$BMXT CICS supplies a sample program, DFH$BMXT , that shows how mapped input and output data can be modified with reference to the information provided in the “field element” table. A copybook, DFHXBMDS, is also supplied. This copybook is a DSECT which defines the structure of the field element. Exit XBMIN When invoked Af[...]

UERCPURG T ask purged during XPI call. XPI calls All can be used. The field element table structure The field element table contains one or more elements which provide information about each “field of interest” passed to the exit. A “field of interest” is a field which has been defined as V ALIDN=USEREXIT in the map source file used [...]

control, the TIOA is disposed of in accordance with the disposition of the TERMINAL (the default), SET , or P AGING option specified on the SEND MAP request. BMXA TTR is only relevant in the XBMOUT exit. It is the address of the attributes (if any) which BMS has placed in the output datastream preceding this field. BMXMAPOF is the offset of the ?[...]

The actual data length (in BMXACTLN) may be less than the length defined in the map (in BMXMAPLN). This occurs due to the compression of trailing nulls performed by BMS for each output field. The actual length of data cannot be changed in the exit program. The exit is invoked after the output datastream has been generated; consequently , an attem[...]

Bridge facility exit When enabled, XF AINTU (Facility Initialization and T idy Up) is called: v Just after a new bridge facility has been built. v Just before a bridge facility is deleted. This may be at the end of a task (when zero keep time is specified), or when a keep time expires before the facility is re-used. Exit XF AINTU When invoked Just[...]

Data tables management exits XDTRD, XDT AD, and XDTLC These exits apply to both: v CICS shared data tables v CICS coupling facility data tables. XDTRD and XDT AD allow you to control the selection of records for inclusion in a data table, XDTRD being used to make such selections during loading, and XDT AD being invoked when records are subsequently[...]

This normally occurs when the loading process retrieves a record during the sequential copying of the source data set. However , it can also occur when an application retrieves a record that is not in the data table and: v For a user-maintained data table, loading is still in progress, or v For a CICS-maintained data table, loading terminated befor[...]

UEPDTCFT(X'10') The exit has been invoked by coupling facility data table support. UEPDTUMT (X'08') This is a user-maintained table. Only meaningful if UEPDTSDT is on. UEPDTRA The address of the data record. UEPDTRBL The fullword length of the data table buffer . UEPDTRL The fullword length of the data record. For user-maintaine[...]

Exit XDT AD The XDT AD user exit is invoked when a write request is issued to a data table. v For a user-maintained data table and coupling facility data table, the user exit is invoked once—before the record is added to the data table. v For a CICS-maintained data table, the user exit is invoked twice—before the record is added to the source d[...]

UEPDTRL The fullword length of the data record. UEPDTKA The address of the data table key . UEPDTKL The fullword length of the data table key . UEPDTDSL The fullword length of the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on. UEPDTDSN A 44-character field containing the name of the source data set. Only meaning[...]

UEPDTCMT (X'40') This is a CICS-maintained table. Only meaningful if UEPDTSDT is on. UEPDTCFT(X'10') The exit has been invoked by coupling facility data table support. UEPDTUMT (X'08') This is a user-maintained table. Only meaningful if UEPDTSDT is on. UEPDTORC Data table open result code. The possible values are: UEPD[...]

DBCTL interface control program exit XXDF A When invoked By an active CICS when its connection to DBCTL fails. Y our exit program is invoked after the active CICS has informed the alternate CICS of the failure. Exit-specific parameters UEPDBXR Address of CICS XRF information for use with DBCTL. The CICS XRF information can be mapped using the DSEC[...]

DBCTL tracking program exits XXDFB and XXDTO Exit XXDFB When invoked By the alternate CICS when it receives a message from the active CICS indicating that connection to DBCTL has failed. The alternate and active CICS systems are running in different MVS images, perhaps in dif ferent central processing complexes (CPCs). More information about these [...]

Exit XXDT O When invoked By an alternate CICS when it performs takeover under the following conditions: v The active and alternate CICS systems are in different MVS images, perhaps in different processors. v The active CICS was connected to, or trying to connect to, a DBCTL subsystem. (This does not include disconnecting from one DBCTL and reconnec[...]

Dispatcher domain exits XDSBWT and XDSA WT The XDSBWT and XDSA WT exit points are located before and after the operating system wait. CICS services cannot be used in any exit program invoked from these exit points. The XDSBWT and XDSA WT exits can be used to control the swapping state of the CICS address-space. It should be noted, however , that if[...]

still exceeds the count of SYSEVENT OKSW APs. Further SYSEVENT OKSW APs must be requested before a SYSEVENT OKSW AP is issued by CICS. Return codes UERCNORM Continue processing. UERCNOSW Issue SYSEVENT to suppress address-space swapping. XPI calls Must not be used. dispatcher domain exits Chapter 1. Global user exit programs 43[...]

DL/I interface program exits XDLIPRE and XDLIPOST The XDLIPRE and XDLIPOST exit points are invoked following the issue of an EXEC DLI command or DL/I call. Exit XDLIPRE is invoked before the request is processed and XDLIPOST is invoked after the request is processed. When the request is function shipped, the exits are invoked from both the applicat[...]

Exit XDLIPRE When invoked On entry to the DL/I interface program. Exit-specific parameters UEPCTYPE Address of type-of-request byte. V alues are: UEPCEXEC The original request was an EXEC DLI request. UEPCCALL The original request was a CALL-level request. UEPCSHIP The request has been function shipped from another region. When this value is set, [...]

UEPIOAX Address of I/O area existence flag byte: UEPIOA1 I/O area exists. For UEPCSHIP requests, the I/O area existence flag is always off. UEPIOA Address of I/O area. This is the application’ s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit: the new contents are used when the DL/[...]

Exit XDLIPOST When invoked On exit from the DL/I interface program. Exit-specific parameters UEPCTYPE Address of type-of-request byte. V alues are: UEPCEXEC An EXEC DLI request. UEPCCALL A CALL-level request. UEPCSHIP The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the[...]

UEPIOAX Address of I/O area existence flag byte: UEPIOA1 I/O area exists. For UEPCSHIP requests, the I/O area existence flag is always off. UEPIOA Address of I/O area. This is the application’ s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit and are returned to the application pro[...]

Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT There are four exits in the dump domain. Exit XDUREQ When invoked Immediately before a system or transaction dump is taken. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address[...]

UEPXDSCP Address of a 1-byte field indicating the current dump table DUMPSCOPE setting. It contains one of the following values: UEPXDLOC A system dump will be taken on the local MVS image only . UEPXDREL System dumps will be taken on both the local MVS image, and on related MVS images within the sysplex. This field may be modified by the exit t[...]

MAXIMUM setting will not suppress this dump request. A return code of UERCBYP may be used to suppress the current dump request. UEPDXDCNT Address of a 4-byte field which contains the current dump table CURRENT setting. UEPXDTST Address of a 16-byte field which contains the current dump table statistics for this dump code. The addressed field con[...]

Return codes UERCNORM Continue processing. UERCBYP Suppress dump. UERCPURG T ask purged during XPI call. XPI calls W AIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls . The sample program for the XDUREQ exit, DFH$XDRQ CICS supplies a sample program for the XDUREQ exit. The sample s[...]

UEPDUMPT Address of the 1-byte dump-type identifier , which contains one of the following values: UEPDTRAN A transaction dump was requested. UEPDSYST A system dump was requested. Note: The dump-type identifier indicates the type of dump request that was passed to the dump domain. It does not reflect any modification that may have been made to t[...]

UEPXDYES The CICS system is to shutdown. UEPXDNO The CICS system is not to shutdown. This field may be modified by the exit to update the dump table SHUTDOWN setting. UEPXDMAX Address of a 4-byte field which contains the current dump table MAXIMUM setting. This field may be modified by the exit to change the current dump table MAXIMUM setting.[...]

XPI calls W AIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls. Exit XDUCLSE When invoked Immediately after a transaction dump data set has been closed. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address o[...]

UEPDMPRE Dump is about to restart after autoswitch. UEPDMP AB Abnormal termination of dump. UEPDMPDY Buffer is about to be written, and the CICS dump data set is a dummy file or is closed. UEPDMPBF Address of the dump buffer , whose length is addressed by the parameter UEPDMPLEN. UEPDMPLEN Address of the 2-byte dump-buffer length. Return codes UER[...]

Enqueue EXEC interface program exits XNQEREQ and XNQEREQC The XNQEREQ exit allows you to intercept enqueue API requests before any action has been taken on the request. The XNQEREQC exit allows you to intercept the response after an enqueue API request has completed. The API requests affected are: v EXEC CICS ENQ v EXEC CICS DEQ. Using XNQEREQ , yo[...]

between successive enqueue requests within the same task (for example, between successive invocations of the XNQEREQ exit). UEPRECUR Address of a halfword recursion counter . The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call. UEPSCOPE Address of the 4-byte ENQSCOPE name to be used. Return codes UERC[...]

UEPTSTOK Address of a 4-byte token which can be used to pass information between successive enqueue requests within the same task (for example, between successive invocations of the XNQEREQC exit). UEPRECUR Address of a halfword recursion counter . The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call. [...]

End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter . Therefore, if you modify the length of the parameter list, you must also[...]

X'20' Set if the request contains an argument for the MAXLIFETIME keyword. If set, NQ_ADDR3 is meaningful. NQ_BITS2 T wo bytes not used by the enqueue domain. NQ_EIDOPT5 One byte not used by the enqueue domain. NQ_EIDOPT6 One byte not used by the enqueue domain. NQ_EIDOPT7 One byte not used by the enqueue domain. NQ_EIDOPT8 Indicates whet[...]

X'04' The existence bit for NOSUSPEND. The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the enqueue request only . Note: Y our user exit program is prevented from making major changes to the EID. However , you must take great care when making[...]

Removing user arguments User exit programs can remove arguments (for which the program is totally responsible) associated with the LENGTH and MAXLIFETIME keywords: Assuming that the argument to be removed exists, the user exit program must: 1. Switch the corresponding argument existence bit to ’0’b in the EID 2. Modify the parameter list to re?[...]

Notes about the use of XNQEREQ to alter ENQ or DEQ scope. 1. XNQEREQ enables you to allow existing applications to be converted to use sysplex enqueues without changing the application. Note: Use of either the ENQMODEL resource definition or the user exit allows this in most cases, but those applications where the resource name is determined dynam[...]

EXEC interface program exits XEIIN, XEIOUT , XEISPIN, and XEISPOUT There are four global user exit points in the EXEC interface program: XEIIN Invoked before the execution of any EXEC CICS application programming interface (API) or system programming interface (SPI) command. XEISPIN Invoked before the execution of any EXEC CICS SPI command except :[...]

The correspondence between command parameters (such as PROGRAM) and their positions and values in the parameter list (in this case, argument 1, ‘MYPROG’) can be deduced from the translated code for the particular command. Important Modifying CICS commands by tampering with argument 0 is not supported, and leads to unexpected errors or results. [...]

UEPRSA Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command. Return codes UERCNORM Continue processing. UERCBYP Bypass the execution of this command. UERCPURG T ask purged during XPI call. XPI calls All can be used. Exit XEISPIN When invoked Before [...]

Exit XEIOUT When invoked After the execution of any EXEC CICS API or SPI command. Exit-specific parameters UEP ARG Address of the EXEC command parameter list. UEPEXECB Address of the system EIB. UEPUSID Address of the 8-character userid. UEPPGM Address of the 8-character application program name. UEPLOAD Address of the application program’s load[...]

UEPRSA Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command. Return codes UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls All can be used. EXEC interface program exits Chapter 1. Global user exit programs 69[...]

File control EXEC interface API exits XFCREQ and XFCREQC The XFCREQ exit allows you to intercept a file control application programming interface ( API ) request before any action has been taken on it by file control. The XFCREQC exit allows you to intercept a file control API request after file control has completed its processing. Note: For i[...]

The command-level parameter structure The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data a[...]

FC_FUNCT One byte that defines the type of request: X'02' READ X'04' WRITE X'06' REWRITE X'08' DELETE X'0A' UNLOCK X'0C' ST ARTBR X'0E' READNEXT X'10' READPREV X'12' ENDBR X'14' RESETBR FC_BITS1 Existence bits that define which keywords that contai[...]

X'01' SET (and not INT O) was specified. Note: Y our program must test for keywords at the bit level, because there may be more than one of these keywords present. FC_EIDOPT6 Indicates whether certain keywords that do not take values were specified on the request. X'80' RBA specified. X'40' GENERIC specified. X&apo[...]

v A 4-byte address returned for SET (if the request is READ, READNEXT , or READPREV , and if FC_EIDOPT5 indicates that this is SET). v Data returned for INTO (if the request is READ, READNEXT , or READPREV , and if FC_EIDOPT5 indicates that this is not SET). v Data from FROM (if the request is WRITE or REWRITE). FC_ADDR3 is the address of one of th[...]

KEYLENGTH REQID SYSID The following are always output fields: INTO NUMREC SET Whether LENGTH and RIDFLD are input or output fields depends on the request, as shown in T able 4. A dash (—) means that the keyword cannot be specified on the request. T able 4. LENGTH and RIDFLD as input and output fields Request LENGTH RIDFLD READ Output See Note[...]

Modifying output fields The technique described in “Modifying input fields” on page 75 is not suitable for modifying output fields. (The results would be returned to the new area instead of the application’s area, and would be invisible to the application.) An output field is modified by altering the data that is pointed to by the comman[...]

X'01' NOSUSPEND specified (on READ, READNEXT , READPREV , WRITE, DELETE, or REWRITE). Bits in the EID should be modified in place. Y ou should not modify the pointer to the EID: any attempt to do so is ignored by CICS. The EID is reset to its original value before return to the application program. That is, changes made to the EID are r[...]

been function shipped to this region. In this case, if your exit program wants to bypass file control (by setting a return code of UERCBYP), it must set the 3 fullwords as follows: Fullword 1 The length of the buffer area Fullword 2 The length of the record Fullword 3 The length of the modified RIDFLD. Doing this ensures that the data and RIDFLD [...]

In XFCREQC: 1. Check ‘UEPRCODE’ to make sure that the file control request completed without error . 2. Use UEPFCTOK to find the address of the area. This area now holds the compressed data. 3. Decompress the data in place. 4. Copy the data from the new area to the user ’s INTO area. Use the user-specified LENGTH (from the command-level pa[...]

UEPFSHIP Address of a 16 byte area. See “Use of the parameter UEPFSHIP” on page 77. UEPRSRCE Address of an 8-character copy of the EIB resource value, EIBRSRCE. Return codes UERCNORM Continue processing. UERCBYP The file control EXEC interface program should ignore this request. UERCPURG T ask purged during XPI call. XPI calls All can be used.[...]

UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. Note: If the file that has just been accessed is remote, the addressed field contains zeros (even if UEPRCODE is non-zero). UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. Note: If the file that has just been accessed is remote, the [...]

Example program CICS supplies, in CICSTS13.CICS.SDFHSAMP , an example program, DFH$XTSE, that shows how to modify fields in the command-level parameter structure passed to EXEC interface exits. DFH$XTSE is listed on page 807. file control EXEC interface API exits 82 CICS TS for OS/390: CICS Customization Guide[...]

File control EXEC interface SPI exits XFCAREQ and XFCAREQC The XFCAREQ exit allows you to intercept a file control system programming interface ( SPI ) request before any action has been taken on it by file control. The XFCAREQC exit allows you to intercept the response after a file control SPI request has completed. Note: For information about [...]

Exit XFCAREQ When invoked Before CICS processes a file control SPI request. Exit-specific parameters UEPCLPS Address of a copy of the SPI command parameter list. See “The command-level parameter structure” on page 86. UEPF A TOK Address of a 4-byte area that can be used to pass information between XFCAREQ and XFCAREQC on a single file contro[...]

Exit XFCAREQC When invoked After a file control SPI request has completed, before return from the file control SPI EXEC interface program. Exit specific parameters: UEPCLPS Address of a copy of the API command parameter list. See “The command-level parameter structure” on page 86. UEPF A TOK Address of a 4-byte area that can be used to pass [...]

file control to describe a valid completion. CICS does not check the consistency of the values you set. If EIBRCODE is set to a non-zero value and EIBRESP is set to zero, CICS overrides EIBRESP with a non-zero value. T o help you set values for EIBRCODE, EIBRESP , and EIBRESP2, the values used by file control for SPI requests are specified in DS[...]

FC_BITS8 FC_GROUP Always X'4C', indicating that this is a file control SPI request. FC_FUNCT One byte that defines the type of request: X'02' INQUIRE FILE X'04' SET FILE. FC_BITS1 Existence bits which specify which arguments were specified. T o obtain the argument associated with a keyword, you need to obtain the ap[...]

X'02' Set if the request contains an argument for the ENABLEST A TUS keyword. If set, FC_ADDR15 is meaningful. X'01' Set if the request contains an argument for the RECOVST A TUS keyword. If set, FC_ADDR16 is meaningful. FC_EIDOPT4 Not used by file control. FC_EIDOPT5 Not used by file control. FC_EIDOPT6 Not used by file cont[...]

X'01' Not used by file control. FC_BITS5 Existence bits which specify which arguments were specified. The comments below FC_BITS1 also apply to FC_BITS5. X'80' Set if the request contains an argument for the T ABLE keyword. If set, FC_ADDR33 is meaningful. X'40' Set if the request contains an argument for the MAXNUMR[...]

FC_ADDR1 is the address of an 8-byte area containing the name from FILE. FC_ADDR2 is the address of a 44-byte area containing the name from DSNAME. FC_ADDR3 is the address of a 4-byte area containing the CVDA from FWDRECOVST A TUS. FC_ADDR4 is the address of a 4-byte area containing the data from STRINGS. FC_ADDR5 is the address of a 44-byte area c[...]

FC_ADDR23 is the address of a 4-byte area containing the CVDA from BLOCKFORMA T . FC_ADDR24 is the address of a 4-byte area containing the CVDA from KEYLENGTH. FC_ADDR25 is the address of a 4-byte area containing the data from KEYPOSITION. FC_ADDR26 is the address of a 4-byte area containing the data from RECORDSIZE. FC_ADDR27 is the address of a 4[...]

T able 5. INQUIRE FILE requests. The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Data T ype Input/Output Arg1 FILE CHAR(8) See note. Arg2 DSNAME CHAR(44) Output Arg3 FWDRECST A TUS BIN(31) Output Arg4 STRINGS BIN(31) Output Arg5 BASEDSNAME CHAR(44) Output Arg6 LSRPOOLID BIN(31) Output Arg7 READ BIN[...]

Note: The file parameter on INQUIRE FILE commands is: v An input field if the request does not specify ST ART , NEXT , or END v An output field if the request specifies NEXT v Omitted if the request specifies ST ART or END. T able 6. SET FILE requests. The relationship between arguments, keywords, data types, and input/output types. Argument K[...]

T able 6. SET FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Data T ype Input/Output Arg36 RLSACCESS BIN(31) Input Modifying input fields The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parame[...]

Note: If you modify the EID, you must be careful not to create inconsistent parameters. For example, if the original request specified SET FILE OPEN and your exit turned on the EID bit for CLOSED, the resulting SET FILE request would specify both OPEN and CLOSED. In this case, the results of the command would be unpredictable. Use of the task toke[...]

File control file state program exits XFCSREQ and XFCSREQC T wo user exits are provided in the file control state program. Y ou can use XFCSREQ, which is invoked before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE request is acted on, to gather information about the state of the file—for example, which file requests (SERVREQs) are va[...]

Exit XFCSREQ When invoked Before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE is attempted. Exit-specific parameters UEPFSREQ Address of a 2-byte field that indicates the type of file request. The first byte contains one of the following values: UEPFSOPN Open request UEPFSCLS Close request UEPFSENB Enable request UEPFSDIS Disable reque[...]

UEFLNAME The 8-character file name. UEDSNAME The 44-character dsname of the data set associated with the file, if this has been set before the file request was issued. UEFSERV One byte indicating the SERVREQ settings for this file. The possible values are: UEFRDIM Read valid UEFUPDIM Update valid UEF ADDIM Add valid UEFDELIM Delete valid UEFBRZ[...]

UEFDSACC One byte indicating the access method of the file. The possible values are: UEFVSAM VSAM file UEFBDAM BDAM file. UEFBCRV Set to nulls for this exit. UEFFRLOG Set to nulls for this exit. UEFFRCLG Set to blanks for this exit. UEFCDA TE Set to nulls for this exit. UEFCTIME Set to nulls for this exit. UEFBCAS Set to nulls for this exit. UEF[...]

UERCPURG T ask purged during XPI call. XPI calls All can be used. API and SPI calls All can be used. Notes: 1. T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCSREQ exit. Use of the recursion counter UEPRECUR is recommen[...]

UEPFSCP Close pending UEPFSELM End of load mode close UEPFSIMM Immediate close UEPFSICP Immediate close pending UEPFSQU RLS quiesce close. UEPFILE Address of the 8-byte file name. UEPFINFO Address of a storage area containing information about the file. The area can be mapped using the DSECT DFHUEFDS, which contains the following fields: UEFLNAM[...]

UEFJDSN Dsname has been journaled UEFJSYN Journal read synchronously UEFJASY Journal write asynchronously . UEFDSVJL One byte indicating a further automatic journaling option which applies to VSAM files only . The value is: UEFJW AC Write add complete. UEFDSJID One byte containing the number of the journal to be used for automatic journaling, if a[...]

VSAM sphere with which it is associated. It contains the date when activity against the VSAM sphere was brought to an end (quiesced). UEFCTIME A time (HHMMSST+) in packed decimal format. This field is set only when the file is the last file to close against the VSAM sphere with which it is associated. It contains the time when activity against t[...]

Return codes UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls All can be used. API and SPI calls All can be used. Notes: 1. T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCSREQC exit. Use o[...]

File control open/close program exit XFCNREC Y ou can use XFCNREC to suppress the open failure that occurs when a mismatch is detected between the backout recovery setting for a file and its associated (non-RLS) data set. Note: This exit is not invoked for RLS opens. For RLS, recovery is a property of the data set. Therefore it is not possible for[...]

Exit XFCNREC When invoked Before file open when a mismatch is detected between the backout recovery setting for the file and its associated non-RLS data set. Exit-specific parameters UEFILE Address of the 8-bit file name. If the file name is less than 8 characters in length, it will be padded with blanks. UEDSETN Address of the 44-byte base da[...]

File control quiesce receive exit, XFCVSDS The XFCVSDS exit is invoked when VSAM RLS notifies CICS that processing is required as a result of some data set-related events occurring in the sysplex. XFCVSDS is invoked before CICS processing takes place, and only if a data set name block (DSNB) exists for the data set. The actions that cause XFCVSDS [...]

Exit XFCVSDS When invoked Invoked after VSAM RLS has informed CICS that processing is required as a result of a data set-related action occurring in the sysplex. Exit-specific parameters UEPDSNAM Address of a 44-byte field containing the name of the data set to which the action applies UEPVSACT Address of a 1-byte field indicating the RLS action[...]

CICS is not to carry out the processing required for the VSAM RLS action, and is to cancel the action throughout the sysplex. A return code of UERCPURG is not allowed. XPI calls All can be used. API and SPI calls Y ou can use CICS API and SPI commands at this exit. In general all can be used, with the following restrictions: v Y ou should avoid the[...]

File control quiesce send exit XFCQUIS The XFCQUIS global user exit is invoked on completion of a VSAM RLS quiesce or unquiesce of a data set that was requested either by a CEMT or EXEC CICS SET DSNAME QUIESCEST A TE command. The exit is invoked regardless of whether the QUIESCEST A TE action has completed successfully or unsuccessfully . This enab[...]

UEQTIMED Failed because quiesce was canceled due to timeout (UEQSD and UEIMQSD only). UEQMIGRT Failed because the data set has been migrated. UEPQCONF Address of a 1-byte field indicating the reason why the quiesce or unquiesce was rejected (for UEQREJEC only). Possible values are: UEQUIINP Quiesce is in progress (UEQSD and UEIMQSD status only). U[...]

File control recovery program exits XFCBF AIL, XFCBOUT , XFCBOVER, and XFCLDEL CICS provides four global user exits that you can use in connection with file control recovery operations. These are: XFCBF AIL Invoked when an error occurs during backout. XFCBOUT Invoked when CICS is about to back out a file update. XFCBOVER Invoked when CICS is abou[...]

If more than one file is associated with a single data set, only the first record in the first of the files to fail backout within the UOW causes CICS to invoke the exit. All subsequent records are failed with the same error , but the exit is not invoked again. v For the first record for each data set that fails during any retry of the backout[...]

UEDLOCK Deadlock detected. UEDUPREC Duplicate key on unique alternate index. UEIOEROR I/O error . UELCKFUL RLS lock structure full. UENOLDEL Logical delete not carried out (XFCLDEL exit point is either not enabled or the XFCLDEL global user exit program chose not to perform the logical delete). UENOSP AC Data set out of storage. UEOPENER Error open[...]

API and SPI calls Although this exit is allowed to issue API and SPI calls, you should be very careful about which commands you use because the exit is invoked during file backout, which is part of syncpoint phase 2. It is recommended that you restrict EXEC CICS commands to inquiries, and avoid commands that update CICS resources, because the reso[...]

request. This request is issued by file control backout to delete a new record added to a VSAM data set. Use parameter UEPFCRSP to determine which error occurred. XBFENO The failure that occurred during file control backout was not as a result of an error response from the file control file-request-handler program. Use parameter UEPFCRSP to det[...]

v Sets a response code of UERCNORM and takes the normal exit from the program. A return code of UERCNORM specifies that CICS backout failure processing is to be carried out. This means that CICS issues a backout failure error message and, for a VSAM data set, ensures that the record remains locked until the backout can be retried and saves the log[...]

Exit-specific parameters UEPFLOGR The address of the file control portion of the log record that is being presented for backout. This is mapped by the DSECT DFHFCLGD. Return codes UERCNORM Continue processing. A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this exit is invoked during syncpoint ph[...]

Exit XFCBOVER, file control backout override exit XFCBOVER is part of the support CICS file control provides for “batch windows” in a VSAM RLS environment. VSAM RLS locks individual records within a data set, and these locks are converted to retained locks for those UOWs that are not completed because of backout or in-doubt failures, thus pre[...]

When invoked Whenever CICS is about to ignore a UOW log record that is due to be backed out, because the lock that protected the updated record could have been overridden by a non-RLS batch program. Exit-specific parameters UEPOLOGR Address of the file control portion of a shunted log record that represents an update to a data set for which retai[...]

DFH$FCBV sample global user exit program DFH$FCBV provides sample processing for the file control backout override global user exit, XFCBOVER. The exit program, if enabled at the XFCBOVER exit point, is invoked when a log record is presented to file control for backing out an update to a data set in RLS access mode, after the data set has been us[...]

Exit XFCLDEL, file control logical delete exit XFCLDEL is invoked whenever a WRITE to a VSAM ESDS, or to a BDAM data set, is being backed out. Because these types of data set do not support deletion, you can use XFCLDEL to perform a logical delete by amending the record in some way that flags it as deleted. When invoked Invoked when backing out a[...]

It is recommended that you restrict EXEC CICS commands to inquiries, and avoid commands that update CICS resources, because the resources may themselves be in a state of recovery . In particular , the following restrictions apply: 1. Do not issue any recoverable operations. 2. Do not use operations that access systems or resource owners external to[...]

v Normal exit from the program: – Makes a user trace entry if tracing is active for file control. This has trace point id X'01F1' and traces: - An eye-catcher ‘DFH$FCLD EXIT OK’ - An eye-catcher ‘RECORD MARKED AS DELETED’ - The marked file control request data - The file control portion of the log record. – Returns to CICS [...]

Front End Programming Interface exits XSZARQ and XSZBRQ Exits XSZARQ and XSZBRQ are invoked from the CICS/ESA Front End Programming Interface (FEPI), if FEPI is installed. For details of these exits, see the CICS Front End Programming Interface User’s Guide . Front End Programming Interface exits Chapter 1. Global user exit programs 125[...]

“Good morning” message program exit XGMTEXT When invoked Before the “good morning” message is transmitted. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using t[...]

Intersystem communication program exits XISCONA and XISLCLQ The two exits in the intersystem communication program allow you to control the length of intersystem queues. Note: There are several methods that you can use to control the length of intersystem queues. For a description of the available methods, see the CICS Intercommunication Guide . Th[...]

3. If it is invoked, your exit program must decide whether or not to queue the request by analyzing the statistics provided through the user exit parameter list. Y our exit program could: v Stipulate that queuing is never to be used. This is the simplest way to code the exit, and avoids complexities of tuning. It should be effective if you define [...]

Exit-specific parameters UEPISPCA Address of a parameter list containing the following fields. Y ou can map the parameter list using the DSECT DFHXISDS. UEPCONST Address of the Connection statistics record. Connection statistics records are of type STICONSR (STID value 52). Y our exit program can map the record using the DSECT DFHA14DS. See notes[...]

XPI calls All can be used. Important There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. The choice is whether or not to take the system default action of queuing the request. The XISLCLQ exit XISLCLQ enables you to specify what action to take after a function shipping request fails to allocate a [...]

Note: No DSECT is provided for the above parameter list. Y ou have to code your own DSECT to access the named fields. Return codes UERCSYS T ake the system action. This is determined by the value of the LOCALQ attribute in the local TRANSACTION definition for the remote transaction: LOCALQ(YES) The request is queued locally . LOCALQ(NO) ‘SYSIDE[...]

Interval control program exits XICREQ, XICEXP , and XICTENF Y ou can use some XPI calls in exit programs invoked from the interval control program. However , when any of these exits are invoked for expiry analysis, any actions that delay the execution of the interval control program can have adverse effects on other transactions that are waiting fo[...]

Return codes UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls The following must not be used: ADD_SUSPEND DELETE_SUSPEND DEQUEUE ENQUEUE RESUME SUSPEND W AIT_MVS. Exit XICEXP When invoked After an interval control time interval has expired. Exit-specific parameters UEPICE Address of the interval control element (ICE) [...]

Interval control EXEC interface program exits XICEREQ and XICEREQC XICEREQ is invoked on entry to the interval control program before CICS processes an interval control request. Using XICEREQ, you can: v Analyze the request to determine its type, the keywords specified, and their values. v Modify any value specified by the request before the comm[...]

UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task. See “Using the task token UEPTSTOK” on page 145. UEPRECUR Address of a halfword recursion counter . The counter is set to 0 when the exit is first invoked, and is incremented for each[...]

‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual. UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task.[...]

The command-level parameter structure The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a 9-byte X'02' ASKTIME X'80' INTERVAL|TIME X'80' RTERMID X'04' DELAY - REQID (cancel) X'40' QUEUE X'[...]

area that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data associated with the request. For example, the second address points to the interval for ST ART requests. Y ou can examine the EID to determine the type of request and the keywords specified. Y ou can exa[...]

IC_EIDOPT7 IC_EIDOPT8 IC_GROUP Always X'10', indicating that this is an interval control request. IC_FUNCT One byte that defines the type of request: X'02' ASKTIME X'04' DELA Y X'06' POST X'08' ST ART X'0A' RETRIEVE X'0C' CANCEL IC_BITS1 Existence bits that define which argumen[...]

X'20' Set if the request specifies HOURS. If set, IC_ADDRB is meaningful. X'10' Set if the request specifies MINUTES. If set, IC_ADDRC is meaningful. X'08' Set if the request specifies SECONDS. If set, IC_ADDRD is meaningful. X'04' Set if the request specifies USERID. If set, IC_ADDRE is meaningful. IC_BI[...]

IC_ADDR1 is the address of one of the following: v An 8-byte area containing the value of the INTERV AL keyword (or TIME keyword if IC_EIDOPT7 indicates that TIME is specified). v An 8-byte area containing the value of REQID (if the request is CANCEL). v Data returned for INTO (if the request is RETRIEVE, and if IC_EIDOPT5 indicates that this is n[...]

IC_ADDRE is the address of an area containing the value of USERID. Modifying fields in the command-level parameter structure Some fields that are passed to interval control are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depen[...]

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified anyway . Modifying the EID It is not possible to modify the EID to make major changes to request[...]

X'01' The existence bit for NOCHECK. IC_EIDOPT7 Bits in IC_EIDOPT7 should only be modified within the same functional group - that is, only those existence bits defined as valid for a ST ART request should be set on a ST ART request. ASKTIME requests X'13' ASKTIME request. This value is fixed for all ASKTIME requests, and sho[...]

Using the task token UEPTSTOK UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive interval control requests in the same task. (By contrast, UEPICTOK is usable only for the duration of a single interval control request, because its contents may be destroyed at the end of the request.) For example, i[...]

6. Set the X'02' existence bit on in IC_BITS1 to indicate that a SYSID is specified. 7. Return to CICS. In XICEREQC: 1. Scan the global work area (GWA) and locate the entry for the CICS region specified in the SYSID parameter . 2. Decrement the use count for this system. 3. If a GETMAIN was issued in XICEREQ to obtain an area to hold th[...]

Loader domain exits XLDLOAD and XLDELETE There are two global user exits in the loader domain. XLDLOAD is invoked when a new instance of a program is loaded into storage, before the program is made available for use. XLDELETE is invoked after an instance of a program is released by CICS and before the program is freed from storage. For LP A-residen[...]

XPI calls Must not be used. API and SPI calls Must not be used. Exit XLDELETE When invoked After an instance of a program is released by CICS, and before the program is freed from storage. Exit-specific parameters UEPPROGN Address of an 8-character field containing the name of the program that is being freed. UEPPROGL Address of a 4-byte field c[...]

Log manager domain exit XLGSTRM There is one exit point, XLGSTRM, in the log manager domain. Y ou can use XLGSTRM to modify a request to MVS to create a new log stream. Y ou can change the model log stream name and other parameters before they are passed to the MVS system logger . If a log stream connection request from CICS to the MVS system logge[...]

An XLGSTRM global user exit program can set explicit attributes for the log stream definition, and can also set a return code that causes the log stream definition to be bypassed. Exit XLGSTRM When invoked After the CICS log manager detects that a log stream does not exist and before calling the MVS system logger to define the log stream dynamic[...]

UERCBYP CICS does not attempt to define the log stream. The process that was attempting to use the log stream may fail (for example, a data set open). XPI calls All can be used. API and SPI commands Must not be used. An example of how XLGSTRM can be used Imagine that you have 200 CICS regions, running on, say , 20 MVS images. T o avoid having to d[...]

Message domain exit XMEOUT The XMEOUT exit allows you to suppress or reroute CICS messages that use the message domain. Note that your exit program is subject to certain restrictions: v It cannot suppress or reroute messages sent to terminal operators, but only those sent to the system console or to transient data queues. (XMEOUT is not invoked for[...]

Important Because of the danger of recursion, your XMEOUT exit program should not try to reroute: v Any DFHTDxxxx messages, produced by the transient data program. v User domain messages in the range DFHUS0002-DFHUS0006, plus message DFHUS0150. v T ransaction manager messages DFHXM0212, DFHXM0213, DFHXM0304 and DFHXM0308. v Application messages DFH[...]

UEPMNUM Address of a 4-byte field containing the message number . UEPMDOM Address of a 2-byte field containing the domain identifier of the CICS message. UEPMROU Address of an array of up to 28 route codes. Route codes must be numbers in the range 1 through 28. UEPMNRC Address of a halfword containing the number of route codes in the route code [...]

UEPNRTE Address of 1-character flag indicating whether or not the message can be rerouted by XMEOUT . The possible values are: C'0:' The message can be routed. C'1:' The message cannot be routed. Return codes UERCNORM Continue processing. UERCBYP Suppress the message for all destinations. XPI calls W AIT_MVS can be used. Do not[...]

Monitoring domain exit XMNOUT XMNOUT is invoked before an exception class monitoring record is passed to SMF , and before a performance class monitoring record is written to the performance record buffer . Y ou can use this exit to examine the record, to suppress its output to SMF , or to change the data it contains. Y ou must be ensure that any ch[...]

UEPMRTYP Address of the halfword monitoring record type. If the value is 3, the type is performance class. If the value is 4, the type is exception class. UEPMRLEN Address of the fullword monitoring record length. UEPMREC Address of monitoring record, whose length is addressed by the parameter UEPMRLEN. UEPSRCTK Address of the MVS workload manager [...]

Program control program exits XPCREQ, XPCREQC, XPCFTCH, XPCHAIR, XPCT A, and XPCABND There are six user exit points in the program control program. XPCREQ and XPCREQC XPCREQ is invoked by the EXEC interface program before a link request is processed. If the request is a distributed program link, the XPCREQ exit is driven on both sides of the link; [...]

Return codes UERCBYP Program control is to ignore the request. UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used. Exit XPC[...]

XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used. Note: T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a[...]

PC_ADDR0 is the address of a 7-byte area called the EXEC interface descriptor (EID), which is made up as follows: PC_GROUP PC_FUNCT PC_BITS1 PC_BITS2 PC_EIDOPT5 PC_EIDOPT6 PC_GROUP Always X'0E', indicating that this is a program control request. PC_FUNCT One byte which defines the type of request, which for XPCREQ and XPCREQC is always X[...]

PC_BITS2 T wo bytes not used by program control. PC_EIDOPT5 Not used by program control. PC_EIDOPT6 Indicates whether the request specifies the SYNCONRETURN option. If it does, X'80' is set. PC_ADDR1 is the address of an 8-byte area containing the program name from the PROGRAM parameter . PC_ADDR2 is the address of the COMMAREA data. PC_[...]

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field you can modify the application’s data in place, because the application is expecting the field to be modified anyway . Modifying the EID It is not possible to modify the EID to make major changes to requests[...]

example, if you need to pass information between successive invocations of the XPCREQ exit, UEPTSTOK provides a means of doing this. The EIB Copies of EIBRSRCE, EIBRCODE, EIBRESP , and EIBRESP2 are passed to the exit, so that you can: v Modify or set completion or resource information in XPCREQ and XPCREQC. v Examine completion information in XPCRE[...]

3. If a GETMAIN was issued in XPCREQ to obtain an area to hold the SYSID, issue a FREEMAIN for the address held in UEPPCTOK. 4. Return to CICS. Exit XPCFTCH XPCFTCH is invoked before a PPT -defined program (including internal CICS modules) receives control, which could be because it is the first program in a transaction, or as a result of a LINK,[...]

PCUE_LOAD_POINT The program’s load point. PCUE_ENTR Y_POINT The program’s entry point. PCUE_PROGRAM_SIZE Fullword containing the size of the program, in bytes. PCUE_COMMAREA_ADDRESS Address of the program’s communication area. PCUE_COMMAREA_SIZE Fullword containing the length of the program’s communication area. PCUE_LOGICAL_LEVEL Fullword [...]

Exit-specific parameters UEPPCDS Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCHAIR is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a termi[...]

Exit XPCT A XPCT A is invoked immediately after a transaction abend, and before any processing that might modify the existing environment so that the task could not be resumed. Y ou can use it to: v Set a resume address, instead of letting CICS process the abend v Specify the subspace that control is passed in. If a resume address is passed back, r[...]

PCUE_BRANCH_CICS CICS key . If storage protection is active, and you do not specify a value, the resumed task executes in User key . If storage protection is not active, the resumed task executes in CICS key . UEPT ACB Address of the transaction abend control block (T ACB) for the abend. If the abend occurred because of a program check, the informa[...]

Exit-specific parameters UEPPCDS Address of a storage area that contains program-related and terminal-related information. The storage area is mapped by the DSECT DFHPCUE. When XPCABND is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS A 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked [...]

Resource manager interface program exits XRMIIN and XRMIOUT Exit XRMIIN When invoked Before a task-related user exit program is invoked due to an application program issuing an RMI API request. Exit-specific parameters UEPTRUEN Address of the name of the task-related user exit program. UEPTRUEP Address of the parameter list to be passed to the tas[...]

Exit XRMIOUT When invoked After a task-related user exit program has returned from handling an RMI API request. Exit-specific parameters UEPTRUEN Address of the name of the task-related user exit program. UEPTRUEP Address of the parameter list passed to the task-related user exit program. See note. UEPRECUR Address of a halfword recursion counter [...]

Resource management install and discard exit XRSINDI The XRSINDI global user exit is driven, if it is enabled, immediately after CICS successfully installs or discards a resource definition. The install and discard activities that drive the exit are as follows: v The install function of the group list on an initial or cold start of CICS v The CEDA[...]

UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name. UEPIDREQ Address of the 1-byte install or discard identifier . The values are: UEIDINS This request is for an install (or in the case of a log stream, it is a connection to a log stream). UEIDDIS This request is for a discard (or in the case of a log[...]

UEIDMODE A modegroup UEIDNQRN An ENQMODEL UEIDP ART A partner UEIDPROF A profile UEIDPROG A program UEIDPRTY A BTS process-type UEIDPSET A partitionset UEIDRQMD A request model (IIOP) UEIDSESS A session UEIDSTRM An MVS log stream UEIDTCLS A transaction class UEIDTCPS A TCP/IP service UEIDTDQU A transient data queue UEIDTERM A terminal UEIDTRAN A t[...]

UEIDKEEP The resources are recoverable at a warm or emergency restart. UEIDLOSE The resources are not recoverable. Note: The exit is not driven during a CICS restart. Return codes UERCNORM Continue processing. This is the default. UERCPURG T ask purged during XPI call. XPI calls Y ou can use all XPI calls. Important Abends in a program enabled at t[...]

Signon and signof f exits XSNON and XSNOFF Exit XSNON is invoked after a terminal user signs on, and exit XSNOFF is invoked after a terminal user signs off (whether the signon or sign-of f is successful or not). XSNON and XSNOFF do not make any security decisions; they are merely a means of tracking users logging on and off a CICS system. The activ[...]

UEPSNFL Signon failed. Return codes UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls All can be used. Exit XSNOFF When invoked When a user signs off. Exit-specific parameters UEPUSRID Address of the terminal userid. UEPUSRLN Address of the terminal userid length. UEPGRPID Address of the group ID. UEPGRPLN Address of t[...]

UERCPURG T ask purged during XPI call. XPI calls All can be used. sign on and sign of f exits Chapter 1. Global user exit programs 179[...]

Statistics domain exit XST OUT On invocation, XSTOUT is passed the address of a buffer containing one or more statistics records. The buf fer can contain records for various resource types (for example, connections and modenames), and both specific and global information (for example, loader statistics for individual programs, and loader statistic[...]

UEPSDA TE Address of a 6-byte character field containing the collection date (MMDDYY). UEPSTIME Address of a 6-byte character field containing the collection time (HHMMSS). UEPSIV AL Address of a 6-byte character field containing the interval time (HHMMSS). This field has meaning only for interval statistics. UEPSIVN Address of the 4-byte inter[...]

System recovery program exit XSRAB Exit XSRAB When invoked When the system recovery program (DFHSRP) finds a match in the SRT for an MVS/ESA™ abend code. For information about defining entries in the SRT , refer to the CICS Resource Definition Guide . Note: The SRT table is only processed, and the exit driven, when an an MVS abend occurs under[...]

SRP_USER_CODE The abend occurred while running user application code. SRP_PPT_ENTR Y The abend occurred while running SRP_ERROR_PPT_NAME. If this flag is not set, the abend occurred while running SRP_ERROR_ST ACK_NAME. SRP_V ALID_OFFSET A meaningful offset could be determined. SRP_V ALID_REASON MVS has supplied a reason code for the abend. SRP_NOT[...]

SRP_ERROR_FP_REGS An area describing the contents of the floating point registers at the time of the abend. It contains: SRP_FP_REG_0 FP register 0 SRP_FP_REG_2 FP register 2 SRP_FP_REG_4 FP register 4 SRP_FP_REG_6 FP register 6. Notes: 1. If flag SRP_NOT_CICS_RB is set, SRP_CICS_ERROR_DA T A describes the last thing that CICS did, prior to the a[...]

Important Notes: 1. T ake care when coding a program to run at the XSRAB exit point. If your exit program causes the system recovery program to be reentered (if, for example, a program check occurs) then CICS terminates abnormally , with a DFHSR06xx message. 2. The default return code is ‘UERCNOCA ’. This ensures that the task abends if the exi[...]

System termination program exit XSTERM The XSTERM exit could be used to output final statistics to your statistics SMF data sets, and to close them. (Note that CICS VSAM and BDAM data sets have already been closed by CICS file control before the exit is invoked.) Exit XSTERM When invoked During the second quiesce stage of a normal system shutdown[...]

T emporary storage domain exits XTSQRIN, XTSQROUT , XTSPTIN, and XTSPT OUT The temporary storage domain exits XTSQRIN, XTSQROUT , XTSPTIN, and XTSPTOUT allow you to: v Specify , for a request that creates a queue, whether the queue is to be held in main or auxiliary storage, and its recoverability v Monitor the use of temporary storage v Control se[...]

UEP_TS_DA T A_P Address of a fullword containing the address of the data. (Write and rewrite requests). UEP_TS_DA T A_L Address of a fullword containing the length of the data. (Write and rewrite requests). UEP_TS_ITEM_NUMBER Address of a fullword containing the item number . (Rewrite, read_into and read_set requests). UEP_TS_STORAGE_TYPE Address o[...]

UEPPROG Address of the 8-byte application program name. UEP_TS_FUNCTION Address of a byte containing the function: UEP_TS_FUN_WRITE UEP_TS_FUN_REWRITE UEP_TS_FUN_READ_INTO UEP_TS_FUN_READ_SET UEP_TS_FUN_READ_NEXT_INTO UEP_TS_FUN_READ_NEXT_SET UEP_TS_FUN_DELETE UEP_TS_QUEUE_NAME Address of a 16-byte field containing the queue name. UEP_TS_DA T A_P [...]

Exit XTSPTIN When invoked Before execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or BMS queues). Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte app[...]

UEP_TS_STORAGE_TYPE_AUX_RECOV_NO Auxiliary storage (non-recoverable). Return codes UERCNORM Normal. UERCPURG T ask purged during XPI call. XPI calls All can be used. API and SPI calls None can be used. Exit XTSPT OUT When invoked After execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or[...]

UEP_TS_RESPONSE_OK UEP_TS_RESPONSE_PURGED UEP_TS_RESPONSE_EXCEPTION UEP_TS_RESPONSE_DISASTER UEP_TS_RESPONSE_INV ALID Return codes UERCNORM Normal response. UERCPURG A purged response was received from an XPI request. XPI calls All can be used. API and SPI calls None can be used. temporary storage domain exits 192 CICS TS for OS/390: CICS Customiza[...]

T emporary storage EXEC interface program exits XTSEREQ and XTSEREQC The XTSEREQ exit allows you to intercept temporary storage API requests before any action has been taken on the request. The XTSEREQC exit allows you to intercept the response after a temporary storage API request has completed. The API requests affected are: v EXEC CICS WRITEQ TS[...]

Exit XTSEREQ When invoked Before CICS processes a temporary storage API request. Exit-specific parameters UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 196. UEPTQTOK Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary s[...]

Exit XTSEREQC When invoked After a temporary storage API request has completed, before return from the temporary storage EXEC interface program. Exit-specific parameters UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 196. UEPTQTOK Address of a 4-byte area which can be used to pass i[...]

Y ou must set valid temporary storage responses. Y ou must set all three of EIBRCODE, EIBRESP , and EIBRESP2 to a consistent set of values, such as would be set by temporary storage to describe a valid completion. CICS does not check the consistency of EIBRCODE, EIBRESP , and EIBRESP2. If EIBRCODE is set to a non-zero value and EIBRESP is set to ze[...]

TS_FUNCT TS_BITS1 TS_BITS2 TS_EIDOPT5 TS_EIDOPT6 TS_EIDOPT7 TS_EIDOPT8 TS_GROUP Always X'0A', indicating that this is a temporary storage request. TS_FUNCT One byte that defines the type of request: X'02' WRITEQ X'04' READQ X'06' DELETEQ TS_BITS1 Existence bits that define which arguments were specified. T[...]

X'80' WRITEQ MAIN or READQ ITEM specified. X'04' WRITEQ REWRITE or READQ NUMITEMS specified. TS_EIDOPT8 Indicates whether certain keywords were specified on the request. X'80' ITEM was specified (otherwise NUMITEMS). TS_ADDR1 is the address of area containing 8-byte name from QUEUE. or 16-byte name from QNAME. T o [...]

NUMITEMS SET LENGTH is an input field on a WRITEQ request, and an output field on a READQ request that specifies SET . It is both an input and an output field on a READQ request that specifies INTO. ITEM is an input field on a READQ request, and on a WRITEQ request that specifies REWRITE. It is both an input and an output field on a WRITEQ [...]

X'10' The existence bit for NOSUSPEND. X'08' The existence bit for MAIN. The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the temporary storage request only . Note: Y our user exit program is prevented from making major changes to t[...]

T able 9. DELETEQ TS: User arguments and associated keywords, data types, and input/output types Argument Keyword Data type Input/output type Arg1 QUEUE CHAR(8) input Arg1 QNAME CHAR(16) input Arg2 * * * Arg3 * * * Arg4 * * * Arg5 * * * Arg6 * * * Arg7 SYSID CHAR(4) input Modifying user arguments User exit programs can modify user arguments, as fol[...]

Example program CICS supplies—in hardcopy only—an example program, DFH$XTSE, that shows how temporary storage requests can be modified. See “Appendix E. The example program for the XTSEREQ global user exit, DFH$XTSE” on page 807. temporary storage EXEC interface program exits 202 CICS TS for OS/390: CICS Customization Guide[...]

T erminal allocation program exit XALCAID XALCAID is driven when an AID with data is canceled in one of the following ways: v By means of the CEMT transaction v During execution of a SET TERMINAL or SET CONNECTION command v During reinstallation of a terminal or connection. XALCAID is invoked only if there is data associated with the AID. Exit XALC[...]

contains FMHs, as specified by the FMH option on the associated ST ART command; or hexadecimal zeros otherwise. UEP ALSTC Address of a 2-byte field containing the start code. This is "SZ" for FEPI starts; otherwise it is "SD". Return codes UERCNORM No other return codes are supplied. The value of the return code is not inspect[...]

T erminal control program exits XTCIN, XTCOUT , XTCA TT , XTCTIN, and XTCT OUT Exit XTCIN When invoked After an input event for a sequential device. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIO[...]

Exit XTCA TT When invoked Before task attach. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However , fields TIOASAL and TIOASCA are not progr[...]

Exit XTCT OUT When invoked Before a TCAM output event. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However , fields TIOASAL and TIOASCA are [...]

‘T erminal not known’ condition exits XAL TENF and XICTENF The ‘terminal not known’ condition can occur when intercommunicating CICS regions use both SHIPP ABLE terminal definitions and automatic transaction initiation (A TI). The condition is especially likely to arise if autoinstall is used. SHIPP ABLE attribute T erminals defined with [...]

CICS drives the XICTENF exit when the ‘terminal not known’ condition occurs after the interval control program has been invoked by an EXEC CICS ST ART command. CICS drives the XAL TENF exit when the ‘terminal not known’ condition occurs after the terminal allocation program has been invoked by the transient data trigger level or the interva[...]

Exit-specific parameters UEP ALEVT Address of 2 bytes containing the type of request. The equated values of the types are: UEP ALESD ST ART command with data UEP ALES ST ART command without data UEP ALETD T ransient data trigger level reached. UEP AL TR Address of 1 byte containing an indication of whether the task issuing the ST ART command was s[...]

For ST ART commands issued in this system by transaction routing to a task, the netname of the last system from which the task was routed. For other ST ART command situations and for transient data trigger level events, the field pointed to contains blanks. UEP ALSYI Address of 4 bytes containing, if UEP ALNTI contains a netname, the corresponding[...]

Exit XICTENF When invoked By the interval control program when the terminal that an EXEC CICS ST ART command requires is unknown in this system. The exit program is expected to give a return code indicating whether the terminal exists on another connected CICS system and, if so, on which one. Exit-specific parameters UEPICEVT Address of 2 bytes co[...]

UEPICNTI Address of 8 bytes containing, for function-shipped ST ART commands, the netname of the last system from which the request came. For ST ART commands issued in this system by transaction routing to a task, the netname of the last system from which the task was routed. For other ST ART command situations, the field pointed to contains blank[...]

DELETE_SUSPEND DEQUEUE ENQUEUE RESUME SUSPEND W AIT_MVS. The sample program for the XAL TENF and XICTENF exits, DFHXTENF One program can be used for both exits, or a separate program can be written for each. Figure 2 shows the executable code from the supplied sample program DFHXTENF , which can be used for both exits. DFHXTENF rejects transient da[...]

*BLDNETNM DS 0H * * Build a netname by taking the first character of the * terminal ID and appending it to the characters 'CICS'. * L R2,UEPICNTO access the output netname field L R3,UEPICRTR access ID of requested terminal MVC 0(8,R2),=C'CICS ' MVC 4(1,R2),0(R3) first character of terminal ID LH R15,NETNAME netname returned B E[...]

T ransaction manager domain exit XXMA TT Exit XXMA TT When invoked During transaction attach. This exit is able to change some of the attributes of the transaction that is being attached. Exit-specific parameters UEPTRANID The address of transaction id (see Notes). UEPUSER The address of the userid associated with the transaction if the current ta[...]

UEP A TTTK The address of a doubleword containing a transaction token. Note that some of the transaction manager XPI calls require this token to identify the transaction that is being attached. Return codes UERCNORM Continue attach processing. XPI calls The user exit can inquire on the transaction being attached, using the UEP A TTTK transaction to[...]

T ransient data program exits XTDREQ, XTDIN, and XTDOUT Exit XTDREQ When invoked Before request analysis. Exit-specific parameters UEPTDQUE Address of 4-byte TD queue name. UEPTDTYP Address of 1-byte TD request type. V alues are: UEPTDPUT PUT request UEPTDGET GET request UEPTDPUR PURGE request. Return codes UERCNORM Continue TD processing. UERCTDO[...]

Exit XTDIN When invoked After receiving data from QSAM (for extrapartition) or VSAM (for intrapartition). Exit-specific parameters UEPTDQUE Address of the 4-byte TD queue name. UEPTDAUD Address of the unmodified TD data. UEPTDLUD Address of the fullword length of the unmodified TD data. UEPTDAMD Address of the TD data modified by the exit progr[...]

Exit XTDOUT When invoked Before passing the data to a QSAM (for extrapartition) or VSAM (for intrapartition) user-defined transient data queue. Exit-specific parameters UEPTDQUE Address of the 4-byte TD queue name. UEPTDAUD Address of the unmodified TD data. UEPTDLUD Address of the fullword length of the unmodified TD data. UEPTDAMD Address of [...]

T ransient data EXEC interface program exits XTDEREQ and XTDEREQC The XTDEREQ exit allows you to intercept a transient data request before any action has been taken on it by transient data. The XTDEREQC exit allows you to intercept a transient data request after transient data has completed its processing. Using XTDEREQ, you can: v Analyze the requ[...]

UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual. UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK A[...]

Exit XTDEREQC When invoked After a transient data API request has completed, and before return from the transient data EXEC interface program. Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 225. UEPTDTOK Address of the 4 byte token to be passed to XTDEREQC. [...]

The command-level parameter structure The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of an 8-byte area that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data[...]

End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter . Therefore, if you modify the length of the parameter list, you must also[...]

TD_BITS1 Existence bits that define which arguments were specified. T o obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the argument was not specified in the r[...]

TD_ADDR4 is the address of a value intended for CICS internal use only . It must not be used. TD_ADDR5 is the address of a value intended for CICS internal use only . It must not be used. TD_ADDR6 is the address of a value intended for CICS internal use only . It must not be used. TD_ADDR7 is the address of an area containing the value of SYSID. TD[...]

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified. Modifying fields used for both input and output An example of a field that is used for both i[...]

The EIB Copies of EIBRSRCE, EIBRCODE, EIBRESP , and EIBRESP2 are passed to the exit, so that you can: v Modify or set completion and resource information in XTDEREQ and XTDEREQC v Examine completion and resource information in XTDEREQC. Y ou can update the copies of EIBRSRCE, EIBRCODE, EIBRESP , and EIBRESP2 that you are given in the parameter list[...]

User log record recovery program exits XRCINIT and XRCINPT At warm and emergency restart, updates made to recoverable CICS resources that were not committed when the system terminated must be backed out. XRCINIT and XRCINPT are invoked from the user log record recovery program, which is used to back out, where necessary , user-written system log en[...]

v There is a restriction on using the XPI early during initialization: do not invoke exit programs that use the XPI functions TRANSACTION_DUMP , WRITE_JOURNAL_DA T A, MONITOR and INQUIRE_MONITOR_DA T A until the second phase of the PL TPI. v There are also restrictions on the use of EXEC CICS commands in these exits: – Y ou cannot use EXEC CICS c[...]

programs” on page 393. Exit XRCINIT When invoked At warm and emergency restart: v Before the first user recovery record is delivered to XRCINPT v When all such records have been delivered to XRCINPT . Exit-specific parameters UEPTREQ Address of a 1-byte flag indicating the reason for the call. When UEPTREQ has a value of UEUSINIT , the exit ha[...]

be mapped using the information supplied in “Chapter 23. CICS logging and journaling” on page 629. UEPLGLEN Address of a fullword containing the length of the log record. UEPT AID Address of a 4-byte field containing the task identifier . UEPTRID Address of a 4-byte field containing the transaction identifier . UEPTEID Address of a 4-byte ?[...]

VT AM terminal management program exit XZCA TT Exit XZCA TT When invoked Before task attach for terminal tasks. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the [...]

VT AM working-set module exits XZCIN, XZCOUT , XZCOUT1, and XZIQUE Note: None of the exits in the VT AM working-set module is available for advanced program-to-program communication (APPC, or LUTYPE6.2) links. Exit XZCIN When invoked After an input event. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE[...]

XPI calls All can be used. However , we do not recommend that you use a GETMAIN call to obtain terminal-class storage for use as a replacement TIOA. This is because there are several internal pointers to the TIOA, and if any one of these is not updated the application may experience problems. Exit XZCOUT1 When invoked Before a message is broken int[...]

XZIQUE exit for managing intersystem queues Y ou can use the XZIQUE exit to control the number of queued requests for sessions on intersystem links (allocate queues). Note: There are several methods that you can use to control the length of intersystem queues. For a description of the various methods, see the CICS Intercommunication Guide . The XZI[...]

modegroups, depending on the session request. Non-specific allocate requests are for MRO, LU6.1, and APPC sessions that do not specify a modegroup. Using the information passed in the parameter list, your global user exit program can decide (based on queue length, for example) whether CICS is to queue the allocate request. Y our program communicat[...]

If the queue limit has been reached but the performance of allocate processing against the queue is below the acceptable limits defined in your user exit program, you can return control to CICS as follows: v For non-specific allocate requests, use return code UERCAKLL. UERCAKLL also returns SYSIDERR to all application programs waiting on the purg[...]

A14EALRJ: Each time an XZIQUE global user exit program returns with a request to reject a request, CICS increments a new field in the system entry connection statistics. This is A14EALRJ (allocate rejected) in DSECT DFHA14DS. This field is provided to help you to tune the queue limit. Normally , if the number of sessions and the queue limit defi[...]

UEPRC8 The exit program returned control to CICS on the previous invocation with return code 8. UEPRC12 The exit program returned control to CICS on the previous invocation with return code 12. UEPP AD A 1-byte padding field. UEPFSPL Address of the 10-byte function shipping parameter list. UEPCONST Address of the 158-byte system entry statistics r[...]

Non-specific allocates data: The following three fields contain data relating to MRO, LU6.1, and non-specific APPC allocates: UEPSAQTS A double-word binary field containing the time stamp from the TCT system entry indicating the time the queue of non-specific requests was started. UEPSACNT A half-word binary field containing the number of all[...]

modegroup specified on this allocate request and send an information message to the operator console. Retry the modegroup after an interval. UERCPURG T ask purged during XPI call. In the case of a successful allocate following the use of UERCAKLL or UERCAKLM, on a previous invocation of the exit, use one of the following: UERCNORM Resume normal op[...]

Sample exit program design A sample XZIQUE exit program is provided with CICS T ransaction Server for OS/390 Release 3 as a base for you to design your own global user exit program. It is called DFH$XZIQ, and is supplied in the CICSTS13.CICS.SDFHSAMP library . The DSECT used by the sample program to map the area addressed by UEPZDA T A is called DF[...]

CICS invokes the exit program to enable it to indicate that normal processing can continue. In this case, the exit program returns with UERCNORM to indicate that CICS is to continue processing normally . This also causes the UEPRC8 flag to be unset following this invocation, and CICS to issue message DFHZC2301. The sample program also monitors the[...]

XRF request-processing program exit XXRST A T XXRST A T enables you to decide whether to terminate CICS when either of the following occurs: v CICS is notified of a VT AM failure by the TPEND exit. v A predatory takeover . A “predatory takeover” can occur , if you are using VT AM Release 3.4.0 or above, and a VT AM application with the same AP[...]

Return codes UERCNORM T ake the system action. The system action depends on the reason why the exit was invoked: v For XRF , in the event of a VT AM failure: CICS continues processing as if the exit program had not been invoked. v For VT AM persistent sessions, in the event of a predatory takeover: CICS abends without a dump. UERCCOIG Ignore. UERCA[...]

XRF request-processing program exit 248 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 2. T ask-related user exit programs This chapter describes a special kind of user exit called a task-related user exit .A task-related user exit allows you to write your own program to access a resource, such as a database, that would not otherwise be available to your CICS system. Such a resource is known as a non-CICS resource. The exit i[...]

The task-related user exit program is provided with a parameter list (DFHUEP AR) by the CICS management module that handles task-related user exits. This parameter list gives the task-related user exit access to information such as the addresses and sizes of its own work areas. The task-related user exit program may be invoked by the CICS task mana[...]

statname is a label that can be referenced externally . It should conform to the requirements of an assembler-language ENTRY statement, and typically resolves a V -type address constant, or the target of a high-level language CALL. A single stub may contain several such labels. ename is the entry name (specified on the EXEC CICS ENABLE command) of[...]

If you do not specify RTNABND=YES and the task-related user exit is not available, the application program terminates abnormally with the abend code ‘AEY9’. T ask-related user exits and EDF When a task-related user exit (TRUE) is invoked for a call to a non-CICS resource manager from an application that is being monitored by EDF , EDF’s defau[...]

User exit parameter lists When a task-related user exit is invoked, the CICS management module that handles task-related user exits provides the exit with a parameter list. The address of this parameter list is passed in register 1. The list contains the following information: v The identity of the caller v Addresses and sizes of any work areas tha[...]

command. The global work area is described on page “The global work area” on page 269. CICS initializes this work area to X'00' when the task-related user exit program is enabled. UEPGAL Address of a halfword containing the length (binary value) of the global work area. UEPTCA This field is retained for historical reasons. It should [...]

UEPUOWDS Address of the APPC unit of work (UOW) identifier . UEPSECFLG Address of the user security flag. The user security flag is a 1-byte field that can take the following values: UEPNOSEC (X'80') Security is not active for this CICS system. UEPSEC (X'20') Security is active for this CICS system. Only in this case is the [...]

data locations can be above or below 16MB; whether the application’s storage is in CICS-key or user-key storage; and whether the TRUE has been called by an unexpected TCB: UEPT ANY (X'80') The application can accept addresses above 16MB. If the symbolic value is not UEPT ANY , the application must be returned an address below 16MB. UEPT[...]

UEPTRL V1 (X'80') RMI level 1 trace is active. UEPTRL V2 (X'40') RMI level 2 trace is active. Having tested this field, the task-related user exit could, for example, issue an EXEC CICS SET TRACETYPE command to reset the level of RMI tracing. DFHUERTR (the function definition) The function definition identifies the caller of[...]

exit program can be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM commands on which the CONNECTST or QUALIFIER option is specified. This allows applications to query whether the exit program is connected to its resource manager , and its entryname-qualifier . For information about the INQUIRE EXITPROGRAM command, see the CICS System Programmin[...]

UERTBACK (X'20') Backout. UERTDGCS (X'10') Unit of recovery has been lost because of an initial start of CICS. UERTDGNK (X'08') Resource manager should not be in doubt about this unit of recovery . UERTW AIT (X'04') Resource manager must wait for the outcome of this unit of recovery . This value is set at pha[...]

Parameter 6 Address of a 4-byte, packed-decimal field containing the date of the failing syncpoint, in the format 00yyddd+. See note 1. Parameter 7 Address of a 4-byte, packed-decimal field containing the time of the failing syncpoint, in the format 0hhmmss+. See note 1. Parameter 8 Address of an 8-byte field containing the resource manager qual[...]

The significance of the parameters is as follows: Parameter 1 The address of a single byte with bit definitions indicating the reason for the call: UERTSOTR (X'40') Start of CICS task UERTEOTR (X'80') End of CICS task. Parameter 2 This parameter is passed only on end-of-task calls. It is the address of a 4-character field whi[...]

UEPEDFFI The input flag byte. When a task-related user exit is invoked by EDF , UEPEDFFI can take the following bit settings: UEPEDFRQ (X'80') “About to Execute” invocation. UEPEDFRS (X'40') “Command Execution Complete” invocation. UEPEDFRA (X'20') About to display command to EDF . UEPEDFRC (X'10') C[...]

Notes: 1. CICS provides a list of named standard attribute bytes that you may want to use. These standard attribute bytes are contained within DFHBMSCA, which must be copied into your program. For programming information, including a list of the attribute bytes and their meanings, refer to the CICS Application Programming Reference manual. 2. The h[...]

CICS SPI Application Syncpoint Task manager Termination CICS EDF call program call manager call call manager call call DFHUEPAR DFHUEPAR DFHUEPAR DFHUEPAR DFHUEPAR DFHUEPAR UEPEXN UEPEXN UEPEXN UEPEXN UEPEXN UEPEXN UEPGAA UEPGAA UEPGAA UEPGAA UEPGAA UEPGAA UEPGAL UEPGAL UEPGAL UEPGAL UEPGAL UEPGAL UEPHMSA UEPHMSA UEPHMSA UEPHMSA UEPHMSA UEPHMSA UEP[...]

The schedule flag word The schedule flag word is a fullword indicator that the task-related user exit program uses to control its own invocation. It is also used by CICS to schedule the first invocation of a task-related user exit program. The schedule flag word is accessed by the address parameter UEPFLAGS of DFHUEP AR. There is a unique sched[...]

program to be called at the start as well as at the end of a task, you must specify T ASKST ART on the EXEC CICS ENABLE command for the TRUE. This causes the TRUE to be invoked at the start and end of every task.) If the last two bytes of the schedule flag word are set to X'1000', this indicates that the task-related user exit is interes[...]

significance of register settings on return are either described in your resource manager ’s documentation, or defined locally . Addressing-mode implications The task-related user exit is invoked in the AMODE of the caller , unless the exit has been enabled with the LINKEDITMODE option of the EXEC CICS ENABLE command. This option enables the ta[...]

another program (via a link or transfer-control command), the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition. Important Y ou are strongly recommended to specify EXECKEY(CICS) when defining both task-related user exit programs, and programs to which an exit program passes control.[...]

v DFHEIENT and DFHEIRET must be in your program. But see the note about not using DFHEIENT in abend invocations, on page 276. For further details of the DFHEIENT and DFHEIRET macros, see the CICS Application Programming Reference manual. v If your exit program entry point is immediately followed by an occurrence of a DFHEIENT macro, inserted either[...]

that is exclusively for the exit program’s use. It is specified using the T ALENGTH option of the EXEC CICS ENABLE command and is accessed using the UEPT AA parameter of DFHUEP AR. Coding a program to be invoked by the CICS SPI If you enable your task-related exit program with the SPI option of the EXEC CICS ENABLE PROGRAM command (or your progr[...]

Increasing ef ficiency – single-update and read-only protocols If your resource manager is capable of performing a single-phase commit, you can increase the eff iciency of your system by means of CICS single-update and read-only protocols. Single-update protocol: Many CICS transactions use only one external resource manager . In this case, a sing[...]

T able 12. V alid return codes for a TRUE invoked by the CICS syncpoint manager Request-type Return codes Meaning UERTPREP UERFPREP Phase 1 of 2-phase commit successful UERFBACK Phase 1 of 2-phase commit unsuccessful UERTW AIT None Not applicable UERTCOMM UERFDONE Phase 2 of 2-phase commit successful UERFHOLD Phase 2 of 2-phase commit unsuccessful [...]

As described in “Increasing eff iciency – single-update and read-only protocols” on page 271 , if the UERTONL Y bit is set (indicating that the resource manager is the only one to have updated resources) the exit program should cause the resource manager to perform a single-phase commit. If the commit is successful, the exit program should re[...]

a UERTELUW call. Because no updates were made, data integrity is not at risk, and therefore no action is taken if the commit fails. On receiving a request to perform the first phase of a two-phase commit, the resource manager is expected to get into a state where recoverable changes made since the last syncpoint can be either committed or backed o[...]

invocation is at start- or end-of-task, you can examine the CICS task manager parameters described in “CICS task manager parameters” on page 260. T ypically , your program shows interest in task manager events if it needs to save task-related information, such as performance or accounting data, before the task ends. Limitations If your exit pro[...]

The limitations on what your program can do, if invoked, depend on the type of termination: Orderly shutdown (UERTCORD) Y our exit program must follow the rules for programs that execute during the first quiesce stage of CICS shutdown—that is, all CICS services are available, but programs must not start any new tasks. Immediate shutdown (UERTCIM[...]

JTRUE1A CSECT TERMINATION TRUE ENTRYPOINT STM 14,12,12(13) Save registers USING JTRUE1A,R3 LR R3,R15 Use R3 as base register USING DFHUEPAR,R1 Address DFHUEPAR parameter list L R2,UEPEXN USING DFHUERTR,R2 CLI UERTFID,UERTCTER CICS Termination call? BNE CONT No, so continue L R10,UEPHMSA Address Host register save area USING SA,R10 L R5,RSAR1 Get Ca[...]

Using EDF with your task-related user exit program If your exit program sets the EDF bit in the schedule flag word and EDF is active, the exit program is invoked before and after each API request to format screens for EDF to display . Communication between the task-related user exit and EDF is controlled by the task-related user exit interface. Th[...]

T able 13 describes each stage of the interface between the task-related user exit and EDF , relating the descriptions to the (T n ) and (E n ) expressions in Figure 10. T able 13. Description of each stage of the task-related user exit/EDF interface Invocation Description (T1) T ask-related user exit invoked to set up its EDF requirements. At this[...]

Important The E1/T2 and E2/T5 cycles can be used repeatedly . This may occur , for example, if the EDF user changes the screen a number of times. Adapter administration Careful use of task-related user exits can allow your application programmers to be unaffected by the invocation of non-CICS resource managers from CICS application programs. Enabli[...]

user exit should invoke its resource manager to free any task-related resources, such as the thread. However , the resource manager should maintain any locks held by the UOW , and record that the UOW is in-doubt. When CICS receives the outcome of the UOW from its coordinator , a resynchronization task is attached to notify the task-related user exi[...]

T racing a task-related user exit program CICS outputs a trace entry just before control is passed to the task-related user exit and just after returning from the exit. Y ou can control these trace entries using the RI option of the CETR trace control transaction or the EXEC CICS SET TRACETYPE command. adapter administration 282 CICS TS for OS/390:[...]

Chapter 3. The user exit programming interface (XPI) This chapter describes the user exit programming interface (XPI) of CICS T ransaction Server for OS/390 Release 3. It is divided into the following sections: v “Overview” is an introduction to the XPI. v “General form of an XPI call” on page 286 contains information that applies to all th[...]

v Using the XPI dump control functions , you can: – Request a system dump—see “The SYSTEM_DUMP call” on page 314 – Request a transaction dump—see “The TRANSACTION_DUMP call” on page 316. v Using the XPI enqueue domain functions , you can: – Enqueue on a named resource—see “The ENQUEUE function” on page 318 – Release a reso[...]

– Change the settings of the autoinstall function for programs, mapsets, and partitionsets—see “The SET_AUTOINST ALL call” on page 350. v Using the XPI state data access functions , you can: – Inquire on application system data in the AP domain—see “The INQ_APPLICA TION_DA T A call” on page 352 – Inquire on CICS system data in the[...]

Note: Using the XPI feature table, you can register a CICS-supplied feature (such as ONC/RPC) to CICS. After it has been registered, you can inquire on the feature, update it, write a trace entry , and deregister it. For details of the XPI feature table, see the CICS External Interfaces Guide . Important 1. Y ou cannot use all of the XPI calls at e[...]

The general format (omitting the assembler-language continuation character) of all XPI calls is: macro-name [CALL], [CLEAR], [IN, FUNCTION(call_name), mandin1(value), mandin2(value), ... [optin1(value),] [optin2(value),] ...] [OUT, mandout1(value), mandout2(value), ... [optout1(value),] [optout2(value),] ... RESPONSE, REASON] XPI calls follow assem[...]

Note: If you build your parameter list incrementally , do not specify CLEAR when you finally issue the call, because the CLEAR option sets the parameter list to zeros, which will cause you to lose the preset values. CLEAR sets the existence bits in the parameter list (both mandatory and optional parameters) to binary zeros. Each macro has a COPY c[...]

the name of a field in which you want the RESPONSE value to be placed. Y ou need not code the RESPONSE option if you are using the macro without CALL to build a parameter list. The response from any XPI call is always one of ‘OK’, ‘EXCEPTION’, ‘DISASTER’, ‘INV ALID’, ‘KERNERROR’, and ‘PURGED’. There are standardized names ([...]

Note that if an XPI call other than DFHDSSRX SUSPEND or W AIT_MVS gets this RESPONSE, your exit program should set the return code to ‘UERCPURG’ and return to the caller . If a DFHDSSRX SUSPEND or W AIT_MVS call specifies an INTERV AL and gets this RESPONSE with a REASON of ‘TIMED_OUT’, it indicates that the INTERV AL you specified has pa[...]

CICS to perform the XPI call processing. Y ou must not use any of these fields: if you do so, your user exit program will have unpredictable results. The user exit program should be in 31-bit addressing mode. XPI register usage Before you can issue an XPI call from a global user exit program, you must move the contents of the parameter UEPST ACK ([...]

to to obtain more than the extra 64 bytes provided, obtain it by either a DFHSMMCX FUNCTION (GETMAIN) macro, or an MVS GETMAIN request. Information to be kept across invocations of an exit program can be stored in the global work area that you can define for an exit program (or group of exit programs). The 320 bytes of LIFO storage cannot be used [...]

TITLE 'GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI' ************************************************************************* * The first three instructions set up the global user exit * * environment, identify the user exit point, prepare for the use of * * the exit programming interface, and copy in the definitions that * * are to be use[...]

************************************************************************* * The next seven instructions form the normal start of a global user * * exit program, setting the program addressing mode to 31-bit, saving * * the calling program's registers, establishing base addressing, and * * establishing the addressing of the user exit parameter [...]

************************************************************************* * Issue the DFHSMMCX macro call, specifying: * * * * CALL -- the macro is to be called immediately * * * * CLEAR -- initialize the parameter list before inserting values. * * * * IN -- input values follow. * * * * FUNCTION(GETMAIN) -- acquire storage * * GET_LENGTH(120) -- 12[...]

************************************************************************* * Test SMMC_RESPONSE -- if OK, then branch round error handling. * ************************************************************************* * * CLI SMMC_RESPONSE,SMMC_OK CHECK RESPONSE AND... BE STOK ...IF OK, BYPASS ERROR ROUTINES * * . . . error-handling routines . . . ***[...]

An example showing how to build a parameter list incrementally In the following example, the parameter list is built incrementally . The initialization of the parameter list (using the CLEAR option), the building of the parameter list, and the GETMAIN call are separated into discrete steps. **********************************************************[...]

DFHSMMCX CLEAR . . . DFHSMMCX GET_LENGTH(100) . . . DFHSMMCX CALL, * IN, * FUNCTION(GETMAIN), * GET_LENGTH(*), * SUSPEND(NO), * INITIAL_IMAGE(X'00'), * STORAGE_CLASS(USER), * OUT, * ADDRESS((R6)), * RESPONSE(*), * REASON(*) Important Y ou must set your parameters using only the XPI functions. The XPI functions The following sections of th[...]

OPTION(addr,len) addr The data address as {namea | (Ra) | aliteral}: namea The name of a location containing the data address (Ra) A register containing the data address aliteral An address constant literal; for example: A(data). len The data length as {namel | (Rn) | expression}: namel The name of a location containing a binary fullword giving the[...]

maxlen The maximum data length as {namel | (Rn) | expression}: namel The name of a location containing a binary fullword giving the maximum data length in bytes (Rn) A register , the contents of which specify in fullword binary the maximum number of bytes of data expression A decimal integer , or any arithmetic expression, including symbolic values[...]

v Issuing the SUSPEND call. 2. T ask B performs the action by: v Getting the parameters v Performing the action v Setting the results v T erminating (or waiting for new work). 3. T ask A ends the interaction by: v Getting the results left by task B. This sequence looks like: Ignoring the Resume and Suspend, the execution amounts to: where these act[...]

The difference is that Set results and Get results are replaced by Clean up. It is vital that only these two sequences can happen; this means that both programs must be coded correctly . CICS ensures that both tasks are told either that SUSPEND and RESUME processing worked, or that it failed. The following shows the programming steps that conform t[...]

ADD_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(ADD_SUSPEND), [RESOURCE_NAME(name16 | string | 'string'),] [RESOURCE_TYPE(name8 | string | 'string'),]] [OUT, SUSPEND_TOKEN(name4 | (Rn)), RESPONSE(name1 | *), REASON(name1 | *)] RESOURCE_NAME(name16 | string | "string") specifies a 16-character string that can be us[...]

RESPONSE and REASON values for ADD_SUSPEND: RESPONSE REASON OK None EXCEPTION None DISASTER None INV ALID 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 page 286. The SUSPEND call SUSPEND suspends execution of a running task. The task can be resumed in o[...]

(Rn) A register containing the interval value, a binary fullword. PURGEABLE(YES|NO) specifies whether your code can cope with the request being abnormally terminated as a result of a purge. There are four types of purge, as shown in T able 14. Specifying PURGEABLE(NO) tells the dispatcher: v T o reject any attempt to PURGE the task. v T o suppress[...]

"string" A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string. If you want to document a name (label) in your program, use this form. Notes: 1. CICS does not use the RESOURCE_TYPE information but includes it in trace entries, and displays it on appropriate CEMT screens to help you to see what you[...]

Note: This is the default reason given to the wait if you suspend a task and do not specify the WLM_W AIT_TYPE parameter . OTHER_PRODUCT W aiting on another product to complete its function; for example, when the workload has been passed to DB2. SESS_LOCALMVS W aiting on the establishment of a session in the MVS image on which this CICS region is r[...]

corresponding RESUME. Y ou must ensure that you keep account of the SUSPEND and RESUME requests issued from your exit program. RESUME DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(RESUME), SUSPEND_TOKEN(name4 | (Rn)), [COMPLETION_CODE(name1 | (Rn)),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] COMPLETION_CODE(name1 | (Rn)) specifies a user-defined ?[...]

DELETE_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(DELETE_SUSPEND), SUSPEND_TOKEN(name4 | (Rn)),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] SUSPEND_TOKEN(name4 | (Rn) ) specifies a token assigned by the system to identify the SUSPEND/RESUME pair of operations used on the task. name4 The name of a 4-byte field, where the token obtained by [...]

W AIT_MVS DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(WAIT_MVS), {ECB_ADDRESS(name4 | (Ra)) | ECB_LIST_ADDRESS(name4 | (Ra)),} PURGEABLE(YES|NO), [INTERVAL(name4 | (Rn)),] [RESOURCE_NAME(name16 | string | 'string'),] [RESOURCE_TYPE(name8 | string | 'string'),]] [TIME_UNIT(SECOND|MILLI_SECOND),] [WLM_WAIT_TYPE,] [OUT, RESPONSE(name1 [...]

T able 15. W AIT_MVS call - RESPONSE(PURGED) REASON T ASK_CANCELLED TIMED_OUT CONDITION PURGE FORCEPURGE DTIMOUT INTERV AL PURGEABLE (NO) Canceled Proceeds normally Canceled Proceeds normally PURGEABLE (YES) Proceeds normally Proceeds normally Proceeds normally Proceeds normally Note: A FORCEPURGE always assumes that the user wants the task to be p[...]

MILLI_SECOND The INTERV AL option specifies the number of milliseconds before timeout. WLM_W AIT_TYPE(name1) specifies, in a 1-byte location, the reason for suspending the task. This indicates the nature of the task’s wait state to the MVS workload manager . The equated values for the type of wait are as follows: CMDRESP W aiting on a command r[...]

RESPONSE and REASON values for W AIT_MVS: RESPONSE REASON OK None EXCEPTION None DISASTER None INV ALID None KERNERROR None PURGED T ASK_CANCELLED TIMED_OUT Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘TIMED_OUT’ is returned if the INTER V AL expires, or if a de[...]

literalconst A number in the form of a literal, for example B'00000000', X'FF', X'FCF4', "0" or an equate symbol with a similar value. RESPONSE and REASON values for CHANGE_PRIORITY : RESPONSE REASON OK None DISASTER None INV ALID None KERNERROR None Note: For more detail, refer to the explanation of RESPONSE[...]

CALLER(block-descriptor) specifies the source of a system dump request. The information that you supply here appears in the dump header , so you could use it to identify the exit program that initiated the system dump request. For a description of valid block-descriptors, see page 298. DUMPID(name9 | *) returns the dump identifier . name9 The nam[...]

The TRANSACTION_DUMP call TRANSACTION_DUMP causes a transaction dump to be taken. If the transaction dump code that you supply on input is in the transaction dump code table, the dump may be suppressed and, optionally , a system dump may be taken. For information about the dump table and how it works, refer to the CICS Problem Determination Guide a[...]

and SEGMENT_LIST are mutually exclusive. TCA(NO|YES) specifies whether the task control area (TCA) is to be included in the transaction dump. The default is NO. TERMINAL(NO|YES) specifies whether all terminal storage areas associated with the task are to be included in the transaction dump. The default is NO. TRANSACTION(NO|YES) specifies whethe[...]

Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘NOT_OPEN’ means that the CICS dump data set is closed. 3. ‘OPEN_ERROR’ means that an error occurred while a CICS dump data set was being opened. 4. ‘P ARTIAL ’ means that the transaction dump resulting from th[...]

However , as no recovery services are provided for abending global user exits, CICS ensures that any outstanding XPI enqueues are dequeued automatically when the dispatcher task terminates. Note that if the dispatcher task is running a CICS transaction, the dispatcher task terminates when the CICS transaction terminates (whether normally or abnorma[...]

Kernel domain functions The ST ART_PURGE_PROTECTION function The ST ART_PURGE_PROTECTION function is provided on the DFHKEDSX macro call. It inhibits purge, but not force-purge, for the current task. This function can be used by all global user exit programs if they want to inhibit purge during a global user exit call. In general, each ST ART_PURGE[...]

Nesting purge protection calls Note that the ST ART_ and STOP_PURGE_PROTECTION functions can be nested. Y ou should ensure that, if multiple ST ART_PURGE_PROTECTION calls are issued for a task, that the correct number of STOP_PURGE_PROTECTION calls are issued to cancel the purge protection. If you issue two starts and only one stop, purge protectio[...]

DEFINE_PROGRAM DFHLDLDX [CALL,] [CLEAR,] [IN, FUNCTION(DEFINE_PROGRAM), PROGRAM_NAME(name8 | string | 'string' ), [EXECUTION_KEY(CICS|USER),] [PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),] [PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),] [REQUIRED_AMODE(24|31|AMODE_ANY),] [REQUIRED_RMODE(24|RMODE_ANY),]] [OUT, [NEW_PROGRAM_TOKEN(name4),[...]

T able 16. Summary of attributes defining DSA eligibility (continued) EXECUTION_KEY option Reentrant Above or below 16MB line Dynamic storage area (DSA) USER Y es Above ERDSA NEW_PROGRAM_TOKEN(name4) returns the token supplied for the newly-defined program. name4 The name of a location to contain the 4-byte token obtained. PROGRAM_A TTRIBUTE(RELO[...]

ECDSA Cannot be overwritten by USER tasks ERDSA Complete—cannot be overwritten by USER tasks or CICS tasks EUDSA None RDSA Complete—cannot be overwritten by USER tasks or CICS tasks UDSA None. SHARED The program is located in the link pack area (LP A), is reentrant, and is protected. TYPE_ANY Either the RPL or the LP A copy of the program may b[...]

The ACQUIRE_PROGRAM call ACQUIRE_PROGRAM returns the entry and load point addresses, the length, and a new program token for a usable copy of the named program, which can be identified by either its name or a program token. ACQUIRE_PROGRAM DFHLDLDX [CALL,] [CLEAR,] [IN, FUNCTION(ACQUIRE_PROGRAM), {PROGRAM_NAME(name8 | string | 'string')|[...]

storage unless deleted. RESIDENT programs must be at least quasireentrant. Any program of PROGRAM_TYPE SHARED has the RESIDENT attribute by default. The DELETE_PROGRAM call has no effect on this type of RESIDENT program. REUSABLE Similar to RESIDENT , except that a REUSABLE program that is not in use can be removed from storage by CICS, for storage[...]

2. A REASON of ‘NO_STORAGE’ with a RESPONSE of ‘EXCEPTION’ means that there was insuff icient storage to satisfy this request, and SUSPEND(NO) was specified. 3. A REASON of ‘PROGRAM_NOT_FOUND’ is returned if the program has not been included in the library concatenation, or if the link-edit failed. In such a case, the program is marked[...]

RESPONSE REASON EXCEPTION PROGRAM_NOT_DEFINED PROGRAM_NOT_IN_USE DISASTER None INV ALID None KERNERROR None PURGED None Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘PROGRAM_NOT_DEFINED’ is returned if the program that you name is not known to the system. 3. ‘P[...]

Log manager functions There are two XPI log manager functions. These are the DFHLGP AX calls: INQUIRE_P ARAMETERS SET_P ARAMETERS These calls allow you to inquire upon, and set, the log manager parameter , KEYPOINT_FREQUENCY . The value in this parameter specifies the activity keypoint frequency of the CICS region. The INQUIRE_P ARAMETERS call INQ[...]

SET_P ARAMETERS DFHLGPAX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PARAMETERS), [KEYPOINT_FREQUENCY(name4 | (Rn) ),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] KEYPOINT_FREQUENCY(name4 | *) specifies the activity keypointing frequency of the CICS region. Permitted values are 0, or any integer between 200 and 65535 inclusive. name4 The name of a 4-byt[...]

The user event-monitoring points must be defined in the usual way in the monitoring control table (MCT). For more information about CICS monitoring, read “Chapter 24. CICS monitoring” on page 657. At a user EMP , you can add your own data (up to 256 counters, up to 256 clocks, and a single character string of up to 256 bytes) to fields reserv[...]

DA T A2(expression | name4 | (Rn) | *) specifies a fullword binary variable whose contents depend on the type of user EMP being used: v If the MCT user EMP definition contains an ADDCNT , SUBCNT , NACNT , EXCNT , or ORCNT option, the DA T A2 variable is an area used as defined by the user EMP definition. v If the MCT user EMP definition contai[...]

expression A valid assembler-language expression that can be expressed in 2 bytes. name2 The name of a 2-byte source of point data (Rn) A register containing the point data in the low-order 2 bytes RESPONSE and REASON values for MONITOR: RESPONSE REASON OK None EXCEPTION DA T A1_NOT_SPECIFIED DA T A2_NOT_SPECIFIED POINT_NOT_DEFINED INV ALID_DA T A1[...]

INQUIRE_MONITORING_DA T A DFHMNMNX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_MONITORING_DATA), DATA_BUFFER(buffer-descriptor),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] Important There is a restriction in using the XPI early during initialization. Do not start exit programs that use the XPI functions TRANSACTION_DUMP , WRITE_JOURNAL_DA T A, MONIT[...]

and the DFHPGAQX calls: INQUIRE_AUTOINST ALL SET_AUTOINST ALL. Used with the Loader functions DEFINE_PROGRAM, ACQUIRE_PROGRAM, RELEASE_PROGRAM, and DELETE_PROGRAM, these calls give you a comprehensive set of tools for manipulating programs. (Note, however , that the tokens returned in the NEW_PROGRAM_TOKEN fields of DFHPGISX calls are different fr[...]

CICS CICS-key NONE The program has not been loaded READ_ONL Y Readonly USER User-key . A V AIL_ST A TUS(DISABLED|ENABLED) returns a value indicating whether the program can be used—that is, whether or not it has been enabled. CEDF_ST A TUS(CEDF|NOCEDF|NOT_APPLIC) returns the EDF status of the program. CEDF When the program is running under the co[...]

ENTR Y_POINT(name4) returns the program’s entry point address, as it would be returned by a Loader domain ACQUIRE_PROGRAM call. EXECUTION_KEY(CICS|NOT_APPLIC|USER) returns the key in which CICS gives control to the program, which determines whether the program can modify CICS-key storage. CICS CICS gives control to the program in CICS key . The p[...]

MANUAL The program is a CICS internal module explicitly defined to the Program Manager by another CICS component. RDO RDO commands. SYSAUTO System autoinstall (that is, autoinstalled by CICS without calling the autoinstall user program). The program may be a CICS internal module or , for example, a first phase PL TPI program. LANGUAGE_DEDUCED(ASS[...]

MODULE_TYPE(MAPSET|P ARTITIONSET|PROGRAM) returns the kind of program resource. NEW_PROGRAM_TOKEN(name4) returns a token that can be used to identify the named program. name4 The name of a location to receive a 4-byte token that identifies this program. If PROGRAM_NAME is specified on the request, NEW_PROGRAM_TOKEN is set to a program token that [...]

NOT_APPLIC Not applicable. The program is remote. PRIV A TE The program is to be loaded from the relocatable program library (RPL). A PRIV A TE program need not be reentrant, and is given only limited protection against unauthorized overwriting. The degree of protection depends on the type of dynamic storage area into which the program is loaded (s[...]

RESPONSE and REASON values for INQUIRE_PROGRAM: RESPONSE REASON OK None EXCEPTION PROGRAM_NOT_DEFINED_TO_LD PROGRAM_NOT_DEFINED_TO_PG DISASTER ABEND LOCK_ERROR INV ALID INV ALID_PROGRAM_TOKEN KERNERROR None PURGED None The INQUIRE_CURRENT_PROGRAM call INQUIRE_CURRENT_PROGRAM returns information about the attributes of the program that is currently [...]

CURRENT_AMODE(24|31) returns the addressing mode which the running program is currently using. CURRENT_CEDF_ST A TUS(CEDF|NOCEDF) returns the EDF status of the current instance of the program. The value returned is the same as for CEDF_ST A TUS, which is the EDF status specified on the program definition. See the CEDF_ST A TUS option of INQUIRE_P[...]

RESPONSE and REASON values for INQUIRE_CURRENT_PROGRAM: RESPONSE REASON OK None EXCEPTION NO_CURRENT_PROGRAM DISASTER LOCK_ERROR ABEND INV ALID None KERNERROR None PURGED None The SET_PROGRAM call SET_PROGRAM allows you to set selected attributes in the definition of a specified program. SET_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PRO[...]

Note: If the program has been link-edited as reentrant with AMODE(31),RMODE(ANY), the EXECUTION_KEY option is ignored, and it is loaded into the extended readonly DSA (ERDSA). For details of the type of storage allocated for the ERDSA, see the RENTPGM system initialization parameter . EXECUTION_SET(DPLSUBSET|FULLAPI) specifies whether CICS is to l[...]

name4 The name of a location containing a 4-byte token obtained from a previous INQUIRE_PROGRAM, INQUIRE_CURRENT_PROGRAM, ST ART_BROWSE_PROGRAM, or GET_NEXT_PROGRAM call. PROGRAM_TYPE(PRIV A TE|SHARED|TYPE_ANY) specifies where the program is to be loaded from. PRIV A TE The program is in the relocatable program library (RPL). A PRIV A TE program n[...]

RESPONSE and REASON values for SET_PROGRAM: RESPONSE REASON OK None EXCEPTION CEDF_ST A TUS_NOT_FOR_MAPSET CEDF_ST A TUS_NOT_FOR_PTNSET CEDF_ST A TUS_NOT_FOR_REMOTE EXEC_KEY_NOT_FOR_MAPSET EXEC_KEY_NOT_FOR_PTNSET EXEC_KEY_NOT_FOR_REMOTE EXEC_SET_NOT_FOR_MAPSET EXEC_SET_NOT_FOR_PTNSET EXEC_SET_NOT_FOR_REMOTE PROGRAM_NOT_DEFINED_TO_LD PROGRAM_NOT_DEF[...]

string A string of characters naming the program. 'string' A string of characters in quotation marks. The string length is set to 8 by padding with blanks or truncating. RESPONSE and REASON values for ST ART_BROWSE_PROGRAM: RESPONSE REASON OK None EXCEPTION None DISASTER ABEND INV ALID_DIRECTORY LOCK_ERROR INV ALID None KERNERROR None PUR[...]

GET_NEXT_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(GET_NEXT_PROGRAM), BROWSE_TOKEN(name4),] [OUT, PROGRAM_NAME(name8), [ACCESS(CICS|NONE|READ_ONLY|USER),] [AVAIL_STATUS(DISABLED|ENABLED),] [CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC),] [DATA_LOCATION(ANY|BELOW|NOT_APPLIC),] [ENTRY_POINT(name4),] [EXECUTION_KEY(CICS|NOT_APPLIC|USER),] [EXECUTION_SET(D[...]

NEW_PROGRAM_TOKEN(name4) returns a token that identifies the next definition in the browse sequence. Y ou can use it in the BROWSE_TOKEN field of your next GET_NEXT_PROGRAM call (or END_BROWSE_PROGRAM call, if you want to end the sequence). Y ou can also use it in the PROGRAM_TOKEN field of INQUIRE_PROGRAM and SET_PROGRAM calls. name4 The name [...]

The INQUIRE_AUTOINST ALL call INQUIRE_AUTOINST ALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets. INQUIRE_AUTOINST ALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_AUTOINSTALL),] [OUT, [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE [...]

SET_AUTOINST ALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_AUTOINSTALL), [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] [LANGUAGES_AVAILABLE(NO|YES),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] AUTOINST ALL_CA T ALOG(ALL|MODIFY|NONE) specifies the catalog status for autoinstall[...]

State data access functions The state data access functions allow you to inquire on and set certain system data in the AP domain. The INQ_APPLICA TION_DA T A call The INQ_APPLICA TION_DA T A call enables you to inquire on application system data in the AP domain. INQ_APPLICA TION_DA T A DFHAPIQX [CALL,] [CLEAR,] [IN, FUNCTION(INQ_APPLICATION_DATA),[...]

SYSEIB(name4 | (Rn) | *) returns the address of the system EXEC interface block of the current task. name4 The name of a fullword area that is to receive the address of the system EXEC interface block. (Rn) A register that is to receive the address of the system EXEC interface block. * The parameter list itself, name APIQ_SYSEIB, is used to hold th[...]

RESPONSE and REASON values for INQ_APPLICA TION_DA T A: RESPONSE REASON OK None EXCEPTION DPL_PROGRAM NO_TRANSACTION_ENVIRONMENT TRANSACTION_DOMAIN_ERROR DISASTER ABEND LOOP INQ_F AILED INV ALID INV ALID_FUNCTION KERNERROR None PURGED None state data access functions 354 CICS TS for OS/390: CICS Customization Guide[...]

The INQUIRE_SYSTEM call The INQUIRE_SYSTEM call gives you access to CICS system data in the AP domain. INQUIRE_SYSTEM DFHSAIQX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_SYSTEM), [GMMTEXT(name4),]] [OUT, [CICSREL(name4 | *),] [CICSSTATUS(ACTIVE | FINALQUIESCE | FIRSTQUIESCE| INITIALIZING),] [CICSSYS(name1 | *),] [CICTSLEVEL(name6 | *),] [CWA(name4 | (R[...]

CICSSYS(name1 | *) returns the operating system for which the running CICS has been built. name1 The name of a 1-byte area that is to receive the hexadecimal character of the operating system. A value of “X” represents MVS/ESA. CICSTSLEVEL(name6 | *) returns the release of CICS T ransaction Server under which CICS is running. name6 The name of [...]

GMMTRANID(name4 | *) returns the transaction identifier of the CICS good morning transaction. name4 The name of a 4-byte area that is to receive the CICS good morning transaction id. INITST A TUS(FIRSTINIT|INITCOMPLETE|SECONDINIT|THIRDINIT) returns a value indicating the stage reached during CICS initialization. FIRSTINIT The first stage of CICS [...]

name1 The name of a 4-byte area that is to receive the version and release number of OS/390 on which CICS is running. A value of “0240” represents OS/390 Release 4. PL TPI(name2 | *) returns the suff ix that identifies the program list table (PL T) containing the list of programs to be run during CICS initialization—the program list table po[...]

name4 The name of a 4-byte location that is to receive the startup date of this CICS system. TERMURM(name8 | *) returns the name of the autoinstall user program for terminals. name8 The name of an 8-byte area that is to receive the name of the autoinstall user program for terminals. TIMEOFDA Y(name4 | *) returns the current time-of-day in packed de[...]

SET_SYSTEM DFHSAIQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_SYSTEM), [DTRPRGRM(name8 | string | 'string'),] [GMMLENGTH(name2 | (Rn) | expression),] [GMMTEXT(name8 | (Rn)),]] [OUT, RESPONSE (name 1|*) , REASON (name 1|*) ] DTRPRGRM(name8 | string | ’string’) specifies the name of the dynamic routing program. name8 The name of an 8-byte are[...]

Storage control functions There are seven XPI storage control functions. These are the DFHSMMCX macro calls GETMAIN, FREEMAIN, INQUIRE_ELEMENT_LENGTH, and INQUIRE_T ASK_STORAGE, and the DFHSMSRX calls INQUIRE_ACCESS, INQUIRE_SHORT_ON_ST ORAGE, and SWITCH_SUBSP ACE. DFHSMMCX calls cannot be used in any exit program invoked from any global user exit [...]

GETMAIN DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION(GETMAIN), GET_LENGTH(name4 | (Rn) | expression), STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL), SUSPEND(NO|YES), [INITIAL_IMAGE(name1 | literalconst),] [TCTTE_ADDRESS(name4 | (Ra)),]] [OUT, ADDRESS(name4 | (Rn) | *), RESPONSE(name1 | *), REASON(na[...]

STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL) specifies the class of the storage that is the subject of the call. The values you can assign to this option, and the type of storage each represents, are listed in T able 17. T able 17. CICS storage classes STORAGE_CLASS T ype of storage CICS T as[...]

2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request was specified with SUSPEND(NO), and there was not enough storage available to satisfy the request. 3. ‘PURGED’ is returned if the GETMAIN request was specified with SUSPEND (YES), there was not enough storage to satisfy the request, and the task was purged. The FREEMAIN call FRE[...]

INQUIRE_ACCESS DFHSMSRX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_ACCESS), ELEMENT_ADDRESS(name4 | (Rn) | *), ELEMENT_LENGTH(name4 | (Rn) | *),] [OUT, ACCESS(CICS | READ_ONLY | USER), RESPONSE(name1 | *), REASON(name1 | *)] ACCESS(CICS|READ_ONL Y|USER) returns the access-key of the storage element. CICS CICS-key READ_ONL Y Readonly storage USER User-k[...]

INQUIRE_ELEMENT_LENGTH DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION (INQUIRE_ELEMENT_LENGTH), ADDRESS (name4 | (Rn) | *),] [OUT, ELEMENT_ADDRESS(name4 | (Rn) | *), ELEMENT_LENGTH(name4 | (Rn) | *), RESPONSE (name1 | *), REASON (name1 | *)] ADDRESS(name4 | (Rn) | *) specifies an address that lies within an element of task-lifetime storage of the current[...]

INQUIRE_SHORT_ON_STORAGE DFHSMSRX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_SHORT_ON_STORAGE),] [OUT, SOS_ABOVE_THE_LINE(NO|YES), SOS_BELOW_THE_LINE(NO|YES), RESPONSE (name1 | *), REASON (name1 | *)] SOS_ABOVE_THE_LINE(NO|YES), returns YES if CICS is currently short-on-storage in any of the DSAs above the 16MB line, and NO if not. SOS_BELOW_THE_LINE(N[...]

lengths of the elements of task-lifetime storage belonging to either the specified task or , by default, the current task. The lengths returned do not include the leading or trailing check zones. For a description of a buffer descriptor , see 299. NUMBER_OF_ELEMENTS(name4 | (Rn) | *) returns the number of entries in each of the two buffers, ELEMEN[...]

T race control function There is one XPI trace control function. This is the DFHTRPTX call TRACE_PUT . DFHTRPTX calls cannot be used in any exit program invoked from any global user exit point in the: v Dispatcher domain v Dump domain v Monitor domain v Statistics domain v T ransient data program. The TRACE_PUT call TRACE_PUT writes a trace entry t[...]

call within a calling domain should specify a unique POINT_ID. This enables you to locate the origin of a trace call when examining a formatted trace. The POINT_IDs must be in the range decimal 256 through 51 1 (X'100' through X'1FF'). This range is not used in CICS modules, but is reserved for user exits. literalconst A number [...]

name8 The name of an 8-byte location to receive the name of the bridge exit program. BRIDGE_F ACILITY_TOKEN(name4) returns a token that contains the address of the bridge facility used by this task. This has the same format as a TCTTE and can be mapped using the DSECT DFHTCTTE. If CONTEXT returns NORMAL, the contents of this field are meaningless.[...]

The DTR transaction definition provides common attributes for transactions that are to be dynamically routed and which do not have a specific transaction definition. It is specified on the DTRTRAN system initialization parameter; the CICS-supplied default definition is CRTX. INQUIRE_DTRTRAN DFHXMSRX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_DTRTR[...]

name4 The name of a 4-byte location that is to receive the current number of active user tasks, expressed as a binary value. (Rn) A register to receive the current number of active user tasks, expressed as a binary value. MXT_LIMIT(name4 | (Rn)) returns the current number of the MXT parameter . name4 The name of a 4-byte location that is to receive[...]

The INQUIRE_TCLASS call The INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Its purpose is to provide current information about the specified transaction class (TCLASS). INQUIRE_TCLASS DFHXMCLX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TCLASS), INQ_TCLASS_NAME(name8 | string | ‘ string ’ ),] [OUT, [CURRENT_ACTIVE(name4 | (Rn)),] [[...]

name4 The name of a 4-byte location that is to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value. (Rn) A register to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value. PURGE_THRESHOLD(name4 | (Rn)) re[...]

INQUIRE_TRANDEF DFHXMXDX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TRANDEF), INQ_TRANSACTION_ID(name4 | string | ‘ string ’ ),] [OUT, [BREXIT(name8),] [CMDSEC(name1),] [DTIMEOUT(name4 | (Rn)),] [DUMP(name1),] [DYNAMIC(name1),] [INDOUBT(name1),] [INDOUBT_WAIT(name1),] [INDOUBT_WAIT_TIME(name4),] [INITIAL_PROGRAM(name8),] [ISOLATE(name1),] [LOCAL_QU[...]

CMDSEC(name1) returns, in a 1-byte location ( name1 ), a value indicating whether command security checking is required for the transaction. YES Command security checking is required. NO Command security checking is not required. DTIMEOUT(name4) returns the deadlock time-out value for the transaction. name4 The name of a 4-byte location that is to [...]

YES The UOW is to wait, pending recovery from the failure, to determine whether recoverable resources are to be backed out or committed. INDOUBT_W AIT_TIME(name4) returns the length of time, in minutes, after a failure during the in-doubt period, before the transaction is to take the action returned in the INDOUBT field. The returned value is vali[...]

P ARTITIONSET(name1) returns, in a 1-byte location ( name1 ), the partitionset specified on the transaction definition. KEEP The reserved name KEEP is specified for the partitionset, which means tasks running under this transaction definition use the application partitionset for the terminal associated with the transaction. NAMED The partitions[...]

RESSEC(name1) returns, in a 1-byte location ( name1 ), a value indicating whether resource security checking is required for the transaction. NO Resource security checking is not required. YES Resource security checking is required. REST ART(name1) returns, in a 1-byte location ( name1 ), a value indicating whether the transaction is to be consider[...]

DISABLED The transaction definition is disabled. ENABLED The transaction definition is enabled. STORAGE_CLEAR(name1) returns, in a 1-byte location ( name1 ), a value indicating whether task-lifetime storage, of tasks associated with this transaction definition, is to be cleared before it is freed by a FREEMAIN command. NO T ask-lifetime storage [...]

TCLASS_NAME(name8) returns the name of the transaction class to which the transaction belongs. name8 The name of an 8-byte location to receive transaction class name to which the transaction belongs. TPURGE(name1) returns, in a 1-byte location ( name1 ), a value indicating whether the transaction is defined as purgeable in the event of a VT AM ter[...]

(Rn) A register to receive the size of the transaction work area, expressed as a binary value. RESPONSE and REASON values for INQUIRE_TRANDEF: RESPONSE REASON OK None EXCEPTION UNKNOWN_TRANSACTION_ID INV ALID None DISASTER LOGIC_ERROR PURGED None The INQUIRE_TRANSACTION call The INQUIRE_TRANSACTION function is provided on the DFHXMIQX macro call. I[...]

The descriptions of the following parameters are the same as the corresponding parameters on the INQUIRE_TRANDEF function call. DTIMEOUT DYNAMIC INITIAL_PROGRAM REMOTE REMOTE_NAME REMOTE_SYSTEM RESTART SPURGE STATUS TCLASS TRAN_ROUTING_PROFILE TRANSACTION_ID The parameter descriptions that follow explain briefly the possible values that can be ret[...]

ORIGINAL_TRANSACTION_ID(name4) returns the transaction id that was used to attach the transaction. For example, if an alias was used at a terminal, this field returns the alias. name4 The name of a 4-byte location to receive the name of the original transaction identifier . OUT_TRANSACTION_TOKEN(name8) returns the token that represents the task. [...]

T A terminal input attach. TT A permanent transaction terminal attach. SUSPEND_TIME(name4 | (Rn)) returns the length of time that the task has been in its current suspended state. name4 The name of a 4-byte location to receive the number of seconds, rounded down, the task has been suspended, expressed as a binary value. (Rn) A register to receive t[...]

RESPONSE and REASON values for INQUIRE_TRANSACTION: RESPONSE REASON OK None DISASTER ABEND LOOP INV ALID None EXCEPTION NO_TRANSACTION_ENVIRONMENT BUFFER_TOO_SMALL INV ALID_TRANSACTION_TOKEN KERNERROR None The SET_TRANSACTION call The SET_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to change the task pri[...]

RESPONSE and REASON values for SET_TRANSACTION: RESPONSE REASON OK None EXCEPTION NO_TRANSACTION_ENVIRONMENT UNKNOWN_TCLASS INV ALID_TRANSACTION_TOKEN DISASTER ABEND LOOP INV ALID None KERNERROR None User journaling function There is one XPI user journaling function, which is the DFHJCJCX call WRITE_JOURNAL_DA T A. DFHJCJCX calls cannot be used in [...]

WRITE_JOURNAL DA T A DFHJCJCX [CALL,] [CLEAR,] [IN, FUNCTION(WRITE_JOURNAL_DATA), FROM(block-descriptor), JOURNALNAME(name8 | string | 'string' ) | JOURNAL_RECORD_ID(name2 | string | 'string'), WAIT(YES|NO), [RECORD_PREFIX(block-descriptor),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] Important There is a restriction in usin[...]

RESPONSE and REASON values for WRITE_JOURNAL_DA T A: RESPONSE REASON OK None EXCEPTION IO_ERROR JOURNAL_NOT_FOUND JOURNAL_NOT_OPEN LENGTH_ERROR ST A TUS_ERROR DISASTER None INV ALID 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 page 286. user journaling[...]

Part 2. Customizing with initialization and shutdown programs © Copyright IBM Corp. 1977, 1999 391[...]

392 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 4. Writing initialization and shutdown programs Y ou can write programs to run during the initialization and shutdown phases of CICS processing. Any program that is to run at these times must be defined to CICS in a program list table (PL T). Information about how to code the PL T is provided in the CICS Resource Definition Guide . The ch[...]

system initialization parameter . The autoinstall user program is not invoked to allow the definitions to be modified. The programs are defined with the following attributes: LANGUAGE(Assembler) RELOAD(No) ST A TUS(Enabled) CEDF(No) DA T ALOCA TION(Below) EXECKEY(CICS) EXECUTIONSET(Fullapi) If any of the default attributes are unsuitable, you mu[...]

First phase PL T programs Programs that are to execute during the first quiesce stage of CICS shutdown are specified in the first half of the PL T (before the DFHDELIM statement). Y ou must define first stage PL TSD programs to CICS. Y ou can either define the programs statically , or use program autoinstall. Although terminals are still avai[...]

v On an immediate shutdown, CICS does not allow running tasks to finish and backout is not performed until emergency restart. This can cause an unacceptable number of units of work to be shunted, and locks to be retained unnecessarily . The purpose of the shutdown assist transaction is to help solve these problems; that is, to ensure that as many [...]

However , if a PL T -defined shutdown program itself passes control to another program (via a link or transfer-control command), the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition. Important Y ou are strongly recommended to specify EXECKEY(CICS) when defining both PL T programs [...]

PL T programs—general 398 CICS TS for OS/390: CICS Customization Guide[...]

Part 3. Customizing with user-replaceable programs © Copyright IBM Corp. 1977, 1999 399[...]

400 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 5. General notes about user-replaceable programs The comments in this chapter apply to all the user-replaceable programs described in Part 3 of this book. A user-replaceable program is a CICS-supplied program that is always invoked at a particular point in CICS processing, as if it were part of the CICS code. Y ou can modify the supplied pr[...]

Assembling and link-editing user-replaceable programs The source for the CICS-supplied user-replaceable programs is installed in the CICSTS13.CICS.SDFHSAMP library . If you intend changing any of these programs, take a copy of the CICSTS13.CICS.SDFHSAMP library and update the copy only . If the original SDFHSAMP is serviced, and a user-replaceable [...]

Notes:  1  This job stream uses the CICS-supplied procedure DFHASMVS to assemble and link-edit user-replaceable programs. The DFHASMVS procedure refers to the MVS library SYS1.MODGEN. If you have not yet restructured MVS/ESA (moving members from SYS1.AMODGEN to SYS1.MODGEN), change the SYS1.MODGEN reference to SYS1.AMODGEN in the DFHASMVS pro[...]

Link-edit statements for DFHPEP . ORDER DFHEAI this CSECT is in SDFHLOAD(DFHEAI) ORDER DFHPEP this CSECT is in USERTEXT(DFHPEP) ORDER DFHEAI0 this CSECT is in SDFHLOAD(DFHEAI0) INCLUDE SDFHLOAD(DFHEAI) INCLUDE USERTEXT(DFHPEP) INCLUDE SDFHLOAD(DFHEAI0) MODE AMODE(31),RMODE(ANY) ENTRY DFHPEP NAME DFHPEP(R) Link-edit statements for DFHREST . ORDER DF[...]

User-replaceable programs and the storage protection facility When you are running CICS with the storage protection facility , there are two points you need to consider: v The execution key in which your user-replaceable programs run v The storage key of data storage obtained for your user-replaceable programs. Execution key for user-replaceable pr[...]

program, the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition. Important Y ou are strongly recommended to specify EXECKEY(CICS) when defining both user-replaceable programs and programs to which a user-replaceable program passes control. Data storage key for user-replaceable progra[...]

Chapter 6. Writing a program error program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . The CICS-supplied default program error program (DFHPEP) contains code to: v Obtain program addressability v Access t[...]

v The program status word (PSW) at the time of the (current) abend, at PEP_COM_PSW . The full contents of PEP_COM_PSW are significant for abend codes ‘ASRA ’, ‘ASRB’, and ‘ASRD’ only; the last four characters (the PSW address) apply also to code ‘AICA ’. v The GP registers (0-15) at the time of the (current) abend, at PEP_COM_REGIS[...]

DFHEISTG DSECT , * * Insert your own storage definitions here * DFHPCOM TYPE=DSECT *********************************************************************** ***** PROGRAM ERROR ***** ***** PROGRAM ***** *********************************************************************** DFHPEP CSECT PROGRAM ERROR PROGRAM CSECT DFHPEP RMODE ANY DFHREGS , EQUATE RE[...]

The sample programs and copy books T wo source-level versions of the default program are provided: DFHPEP , coded in assembler language, and DFHPEPD, coded in C. Both are in the CICSTS13.CICS.SDFHSAMP library . There is an assembler-language macro, DFHPCOM, and a corresponding C copy book, DFHPCOMD, that you can use to define the communication are[...]

Chapter 7. Writing a transaction restart program The transaction restart user-replaceable program (DFHREST) enables you to participate in the decision as to whether a transaction should be restarted or not. CICS invokes DFHREST when a transaction abends, if REST ART(YES) is specified in the transaction’s resource definition (the default is REST[...]

All the following conditions must be true for CICS to invoke the transaction restart program: v A transaction must be terminating abnormally . v The transaction abend which caused the transaction to be terminating abnormally must have been detected before the commit point of the implicit syncpoint at the end of the transaction has been reached. v T[...]

XMRS_WRITE Indicates, in a 1-byte field, whether the transaction has issued any terminal write requests. The equated values for this parameter are: XMRS_WRITE_YES Means a terminal write has been performed by the transaction. XMRS_WRITE_NO Means a terminal write has not been performed by the transaction. XMRS_SYNCPOINT Indicates, in a 1-byte field[...]

The CICS-supplied transaction restart program The CICS-supplied default transaction restart program requests that the transaction be restarted if: 1. The transaction has not performed a terminal read (other than reading the initial input data), terminal write or syncpoint, and 2. The restart count is less than 20 (to limit the number of restarts), [...]

Chapter 8. Writing a terminal error program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter contains information about the CICS terminal error program (TEP), which handles error conditions for de[...]

When an abnormal condition occurs When an abnormal condition associated with a particular terminal or line occurs, the terminal control program puts the terminal out of service and passes control to the terminal abnormal condition program (DFHT ACP) which, in turn, passes control to a version of the terminal error program (DFHTEP , either CICS-supp[...]

DFHTEP module and tables by means of the DFHTEPM and DFHTEPT macros, respectively . Y ou can select the appropriate options in this sample program, and you can base your own version on it. There is a description of the CICS-supplied sample terminal error program (DFHXTEP), and advice about how to generate a user-written version, later in this chapt[...]

the operating environment by selecting the appropriate generation options and variables. Because each error condition is processed by a separate routine, you can replace a CICS-provided routine with a user-written one when the sample TEP is generated. Components of the sample terminal error program The sample terminal error program consists of the [...]

Y ou should assign permanent TEBs to terminals that are critical to the network. For the remainder of the network, you can generate a pool of reusable TEBs. Each TEB currently in use or permanently assigned contains the symbolic terminal identifier of the terminal, and one or more error status elements (ESEs), as shown in Figure 17. An ESE records[...]

1. Entry and initialization 2. T erminal identification and error code lookup 3. Error processor selection 4. Error processing execution 5. General exit 6. Common subroutines. These areas are described in detail in the sections that follow . Figure 18 on page 423 gives an overview of the structure of the sample terminal error program. Entry and in[...]

processor , are to be performed. The common error bucket is processed by the specific error processor . However , the thresholds of the common error bucket are used in determining whether the limit has been reached. Subroutines are provided in the sample TEP to maintain count and time threshold totals for each error associated with a particular te[...]

TEPPUTTD Used to output character or hexadecimal data to a user-defined transient data destination. TEPTMCHK Used by TEPINCR to determine whether the time threshold has been passed. TEPWGHT Used to update the weight/time threshold values maintained in the terminal’s error status elements. the sample terminal error program 422 CICS TS for OS/390:[...]

Sample terminal error program messages The messages logged to the transient data destination CSMT (or , optionally , to the destination specified in the OPTIONS operand of DFHTEPM TYPE=INITIAL) are of DFHTACP Entry and initialization Terminal ID and error code lookup Error processing selection Error Error ... Error Error processor processor proces[...]

six types, each identified by a unique message prefix. Y ou can control the selection of each type of message by using the appropriate parameters specified on the PRINT operand of DFHTEPM TYPE=INITIAL. These messages are: DFHTEP , ERROR – error text During DFHTEP module generation, the PRINT parameter specified ERRORS. This message can be sup[...]

This message contains the symbolic terminal ID of the device associated with the error . This message can be suppressed by using the NOTID option. DFHTEP , DECB - DECB information During the DFHTEP module generation, the PRINT parameter specified DECB. This two-line message contains the DECB (printed in hexadecimal format) of the terminal causing [...]

to generate a sample error program and tables that include your user-written routines. Some of the parameters specified in the DFHTEPM and DFHTEPT macros are related and care must be taken to ensure compatibility . The parameters concerned are identified in the descriptions of the macros later in this chapter . If you use the sample terminal erro[...]

This macro indicates the end of user storage definitions. Its use is mandatory if DFHTEPM TYPE=UST OR has been coded. If you use DFHTEPM TYPE=USTOR to define storage, then both it and DFHTEPM TYPE=UST OREND must be coded before DFHTEPM TYPE=INITIAL. TYPE=INITIAL establishes the beginning of the generation of the sample DFHTEP module itself. DSECT[...]

NOEXITS No branches are taken to user routines. TIME|NOTIME specifies whether threshold tests are to be controlled over prescribed time intervals. An example might be putting a terminal out of service if more than three instances of a given type of error occur in one hour . The parameter must be the same as the OPTIONS operand in the DFHTEPT TYPE=[...]

TID|NOTID specifies whether the symbolic terminal ID of the terminal associated with an error is to be recorded on the transient data destination. TID The terminal ID is to be logged. NOTID No terminal IDs are to be logged. DECB|NODECB specifies whether the DECB of the line associated with error is to be recorded on the transient data destination[...]

The macro required for a user “ENTRY” routine is: This macro must be immediately followed by user “ENTRY” routine code, starting with the label “TEPENTRY” and ending with a BR 14 instruction. The macro required for a user “EXIT” routine is: This macro must be immediately followed by user “EXIT” routine code, starting with the la[...]

to be logged to the TEPQ transient data destination. The CICS DSECT s are not printed on the sample DFHTEP assembler-language listing. There are two error processor routines (codes ‘87’ and ‘9F’ respectively). * GENERATE USER STORAGE DFHTEPM TYPE=USTOR USORFLD DS F DFHTEPM TYPE=USTOREND * MODULE SPECIFICATIONS DFHTEPM TYPE=INITIAL, * OPTION[...]

DFHTEPT–generating the sample DFHTEP tables The following macros are required to generate the terminal error program tables: v DFHTEPT TYPE=INITIAL—to establish the control section. v DFHTEPT TYPE=PERMTID—to define permanently reserved terminal error blocks (TEBs) for specific terminals. v DFHTEPT TYPE=PERMCODE|ERRCODE—to define permanen[...]

NOTIME T ime threshold space is not reserved. DFHTEPT TYPE=PERMTID–assigning permanent terminal error blocks The DFHTEPT TYPE=PERMTID macro to define permanently reserved terminal error blocks for specific terminals is: TYPE=PERMTID defines permanently reserved terminal error blocks for specific terminals. Permanent TEBs are defined for term[...]

CODE={errcode|BUCKET} identifies the error code referred to by the TYPE=PERMCODE|ERRCODE parameter . These codes are listed in Figure 22 on page 443. CODE=BUCKET is only applicable to the DFHTEPT TYPE=ERRCODE macro. It is used to override the default threshold constants established for the common error bucket. COUNT=number can be used in either th[...]

number The interval in units of one hundredth of a second. Parentheses are not required if this method is used. The maximum number must be less than 8 640 000 (24 hours). (number ,SEC) The interval in whole seconds, which must be enclosed in parentheses. The maximum number must be less than 86 400 (24 hours). (number ,MIN) The interval in whole min[...]

DFHTEPT TYPE=BUCKET–using the error bucket for specific errors The DFHTEPT TYPE=BUCKET macro is used to ensure that specific error conditions are always accounted for in the common error bucket: TYPE=BUCKET generates the macro to account for specific error conditions in the common error bucket. If MAXERR=25 on the DFHTEPT TYPE=INITIAL macro, t[...]

This example generates 10 terminal error blocks, one of which is reserved for the terminal whose symbolic ID is TM02, and the other nine are reusable. Each TEB has space for five error status elements plus a common error bucket. Of the five ESEs, two are reserved for error codes ‘81’ and ‘87’; the remaining ESEs are available to be assign[...]

T able 21. Supplied source files and macros (continued) Name T ype Description Library DFHTEPCA Macro Assembler-language communication area CICSTS13.CICS.SDFHMAC The user-written DFHTEP receives control in the same manner as the CICS-supplied sample DFHTEP , described in “The communication area” on page 417. It should therefore use the communi[...]

Y ou generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program. The layout of the communication area is shown in Figure 21. The parameter list contains the following information: TEPCALDS Function Code. The Function Code is a printable character representing the identity of the task within the TCP which invoked DFHTEP . It[...]

SIGNOFF (X'02') Call sign-off program. On entry to DFHTEP , the above flags represent the default actions set by DFHT ACP . The write-abend bit (communication area field ABORTWR ) and the abend-task bit (communication area field ABENDT ) are always set if the place-line-out-of-service bit (X'80') is set; but both bits are sup[...]

and DFHT ACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message to CSMT ; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or , rarely , ‘AEXZ’. v Abend write has no effect if the TCTTE was associated with a READ request. In this case the normal result is that, if the line and terminal remain in service, the read is[...]

L TCTTEAR,TCTLEPTE POINT TO ERROR TCTTE USING DFHTCTTE,TCTTEAR DROP TCTLEAR L TCTLEAR,TCTTELEA POINT TO TCTLE USING DFHTCTLE,TCTLEAR After you have carried out the required functions and, optionally , altered the default actions scheduled by DFHT ACP , the user-written DFHTEP must return control to DFHT ACP by issuing the EXEC CICS RETURN command. [...]

TERMINAL ABNORMAL CONDITION LINE ENTRY Dec Hex 4 BYTES 00 TCTLEPSA STORAGE ACCOUNTING AREA 44 RESERVED 88 TCTLEPFL TCTLEPF2 NOT USED ERROR FLAGS SPECIAL IND 12 C TCTLEPTE TCTTE ADDRESS 16 10 TCTLEECB TCAM BEGINNING RESERVED RETURN OF DECB FOR DFHTACP CODE 20 14 24 18 TCTLEDCB ACTUAL LINE ENTRY ADDRESS 28 1C 44 2C TCTLECSW NOT USED BSAM STATUS 48 30[...]

Displacement Dec Hex Code Bytes Label Meaning 0 0 4 TCTLEPSA Storage accounting RESERVED 8 8 1 TCTLEPFL Error flags 81 Message too long 84 TCT search error 85 Write not valid 87 Unsolicited input 88 Input event rejected 8C Output event rejected 8D Output length of zero 8E No output area 8F Output area exceeded 94 Unit check 95 Unit check (should no[...]

Example of a user-written terminal error program The “DFHTEP recursive retry routine” on page 446 is an example of the logic steps necessary to design a portion of the terminal error program. In Figure 23 on page 446, 10 retries are provided for each terminal; however , the logic could be used for any number of retries. The following assumption[...]

DFHTEP recursive retry routine *ASM XOPTS(NOPROLOG NOEPILOG SP) ************************************************************************ * * * DFHTEP RECURSIVE RETRY ROUTINE * * * ************************************************************************ DFHEISTG DFHEIEND DFHTEPCA TYPE=DSECT COMMAREA passed by TACP COPY DFHA06DS Statistics DSECT USIN[...]

EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) * Get statistics for this terminal * using TERMID passed in Commarea * MVC PCISAVE,A06TENI Save the current system counts. This * is a new error, or first time * through. INCR DS 0H AP PCICNT,=P'1' Increment the number of times this * error has occurred (recursive count) * CP PC[...]

448 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 9. Writing a node error program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter contains information about the node error program (NEP) of CICS T ransaction Server for OS/390 Release 3. N[...]

Background to CICS-VT AM error handling In general, errors detected by CICS-VT AM terminal control are queued for handling by a special task, the CICS node error handler (transid CSNE). (Note that CICS finds it convenient to use the same technique for some housekeeping work, such as sending “good morning” messages, and logging session starts a[...]

v There could be application-related activity to be performed when a node error occurs. For example, if a message fails to be delivered to a terminal, it may need redirecting to another . With messages sent with exception-response only , CICS may not have the data available to send it again, but the requesting application might be able to re-create[...]

v Status changes (for example, of TCTTE) v Clean-up work (cancel any associated transaction, end the VT AM session). The action flags can be set or reset within DFHZNEP . The action flags set by DFHZNAC for specific error codes and sense codes are listed in “Appendix B. Default actions of the node abnormal condition program” on page 789. The[...]

The node error table must be defined as a RESIDENT program. This makes it easy for the NEP to find it (using a CICS LOAD request), and ensures that any counters are not reset by reloading. Y ou can give the table any name you like. The default is DFHNET . The table consists of sets of error-recording areas. Each set is called a node error block ([...]

The initial code first tests the internal error code passed from DFHZNAC to see if it belongs to a group that the NEP needs to handle. (The groups are identified by the code you supply between the DFHSNEP INITIAL and FINAL macros. This is described in “Generating the sample node error program” on page 469.) If the particular error code is not[...]

The code for non-SNA 3270s can be generated by coding DFHSNEP TYPE=DEF3270 where you would otherwise code a DFHSNEP TYPE=ERRPROC macro plus logic of your own. In effect, TYPE=DEF3270 defines two error groups, and associates each with an error processor . The first group comprises the four DFHZNAC error codes X'D9', X'DC', X&ap[...]

The DFHZNEPI macros (see “DFHZNEPI macros” on page 478) generate a DFHZNEP module that is purely a routing module. This inspects the NEPCLASS in effect for the node error passed by DFHZNAC, and transfers control (links) to another module, the real NEP , according to a NEPCLASS/name routing table built up by the macros. If no NEPCLASS is in effe[...]

When an abnormal condition occurs The following CICS components are involved when an abnormal condition is detected from a logical unit: v The terminal control program VT AM section: DFHZCA, DFHZCB, DFHZCC, DFHZCP , DFHZCQ, DFHZCW , DFHZCX, DFHZCY , and DFHZCZ. v The node abnormal condition program, DFHZNAC. v The CICS-supplied default node error p[...]

When control is returned from DFHZNEP , DFHZNAC performs the actions specified in field TW AOPTL (except when disconnecting logical units, as noted above), issuing messages and setting error codes, as necessary . The communication area After DFHZNEP receives control from DFHZNAC, it obtains the address of the communication area by means of an EXE[...]

********************************************************************** ** Header ** ** These fields are READ ONLY ** ********************************************************************** NEPCAHDR DS 0XL4 Standard Header NEPCAFNC DS XL1 Function Code Always '1' NEPCACMP DS XL2 Component Code Always 'ZC' DS XL1 Reserved *********[...]

********************************************************************** ** VTAM information - Any VTAM sense and RPL codes ** ** These fields are READ ONLY ** ********************************************************************** TWAVTAM DS 0XL12 VTAM information TWARPLCD DS H VTAM RPL feedback codes DS H Reserved TWASENSS DS 0F Sense codes to be se[...]

The next sections describe fields in the parameter list that can be reset within DFHZNEP . See also “Coding for the 3270 ‘unavailable printer ’ condition” on page 476, which describes the use of the flags in the “unavailable printer return code” field, and “Using the node error program with XRF or persistent sessions” on page 480[...]

aids. The first five flags cause DFHZNAC to write the desired information to the CSNE log if the appropriate bit is set. Setting the sixth flag (TW AODNT A) on causes CICS to take a system dump when there is no task attached to the terminal at the time of error detection, if the flag TW AOA T in TW AOPT2 is also set on. The flags are: TW AOAF[...]

TW AOGMM (X'08') “good morning” message to be sent TW AOPBP (X'04') Purge any BMS pages for this session TW AOASM (X'02') SIMLOGON required. Notes: 1. If a definite response SEND has been performed, CICS has to issue a RECEIVE in order to obtain the response. If the response is negative, DFHZNAC is entered and set[...]

TW AOOS indicates that no further processing is to be done for this node. The node is logically out of service. For an LU6.1 intersystem communication session, TW AOOS or TW AONINT causes the system entry to be put out of service if, as a result of the specified action, there are no allocatable sessions left. (A session can also be put out of serv[...]

This notification results in an informative message being issued, and causes DFHZNAC to invoke your NEP , whether the CLSDST request has failed or succeeded. The NEP can discover that a CLSDST OPTCD=P ASS request is in progress by examining field TW APFLG for the pass-in-progress indicator , TW APIP . The success or failure of the CLSDST OPTCD=P [...]

v A general environment within which your error processing programs can be added v The default node error program in a system that has several node error programs. The CICS-supplied sample node error program is described in greater detail below . Compatibility with the sample terminal error program Receipt of sense or status codes corresponds to er[...]

Routing mechanism The routing mechanism invokes the appropriate error processor depending on the error code provided by the node abnormal condition program. Groups of one or more error codes are defined in the DFHSNEP macro (see below). Each group is associated with an index (in the range X'01' through X'FF') and an error proce[...]

Note: If you write your own node error program, you must generate a NET , even if it contains no entries because your error processors do not use it. Optional common subroutines The common subroutines are addressed via the CSVT and provide error processors with the following functions: v Locate or assign NEBs and ESBs on the basis of node ID and er[...]

with an IC PUT command. Otherwise the default actions are taken. (For more details, see the section “Coding for the 3270 ‘unavailable printer ’ condition” on page 476.) Optional error processor for interactive logical units Only one error processor is supplied for interactive LUs: group index 1, with error code X'DC'. This error c[...]

DFHSNEP TYPE=UST OR and USTOREND—defining user storage The DFHSNEP TYPE=USTOR macro has the following format: This macro indicates the start of user storage definitions. It must be followed by your storage definitions, and then by DFHSNEP TYPE=USTOREND. If you use DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND mu[...]

TYPE=DEF3270 specifies that the CICS-supplied error processors for 3270 logical units are to be included in the node error program. This macro causes the following source code to be generated: DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=(D9,DC,DD,F2) Sense/status error processor code. DFHSNEP TYPE=ERRPROC,GROUP=2,CODE=42 Unavailable printer error processor [...]

GROUP=error-group-index specifies an error group index for the error processor . This index is used to name the error processor , locate its address from the error processor vector table (EPVT), and optionally associate it with an ESB in each NEB. The index specified must be a 2-character representation of a 1-byte hexadecimal number in the range[...]

4. Registers 4 through 9 can be saved by common subroutines in an area reserved in EXEC interface storage at label NEPCSRS. They must be restored before return from the subroutines. DFHSNET—generating the node error table The DFHSNET macro is used to generate a node error table. Each node error table that you generate must be defined to CICS. No[...]

TIME=(7,MIN)|(interval,units) specifies the time interval that is to be stored in the NET header for use by the common subroutines to maintain error counts in standard ESBs. If the threshold specified in the COUNT operand is not exceeded before this time interval elapses, the error count is reset to 0. Specify “units” as SEC, MIN, or HRS. The[...]

DFHNEPC DSECT DS F Load instruction DS F Branch instruction CSVTNEP DS A Node error program base address CSVTESBL DS A NEPESBL - ESB locate routine CSVTNEBD DS A NEPNEBD - NEB delete routine CSVTECUP DS A NEPECUP - error count update routine User-written node error programs Y ou can write your own NEP in any of the CICS-supported languages. However[...]

v Updates to recoverable resources. If the resources are locked by another task, the CSNE unit of work could be suspended or shunted. Y ou should also note that you cannot use the NEP to suppress DFHZNAC messages. Entry and addressability On entry , your NEP should issue the commands: EXEC CICS ADDRESS COMMAREA EXEC CICS ADDRESS EIB These commands [...]

Before linking to the node error program, DFHZNAC inserts the primary and secondary printer netnames and terminal IDs into the communication area, indicating also whether either printer is eligible for a print request. DFHZNAC links to the node error program with no default actions set. On return from the node error program, DFHZNAC checks the addi[...]

If used in this way , the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however , that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened. Refer to “Restrictions on the use of EXEC CICS command[...]

DFHZNEPI TYPE=INITIAL—specifying the default routine The DFHZNEPI TYPE=INITIAL macro specifies the name of the default transaction-class routine to be used for the DFNZNEPI module. DEF AUL T=name specifies the name of the default transaction-class routine to be used. A link is made to this default routine if you specify for the transaction (usi[...]

Handling shutdown hung terminals in the node error program Error Code: X'6F' Symbolic Name: TCZSDAS Message Number: DFHZC2351 For error code X'6F', DFHZNAC passes the setting of TCSACTN and the DFHZC2351 reason code to DFHZNEP , and DFHZNEP can modify the force-close action for the current terminal. How DFHZNAC passes the settin[...]

One of the steps in the conversation-restart process is to link to the node error program with error code X'3F'. If you want to be able to change any of the system-wide recovery notification options (whether terminal users are notified of a recovery , the recovery message, or the recovery transaction) for some terminals, you should writ[...]

notification that service has been restored. T o achieve this, you could code RECOVNOTIFY(MESSAGE) in the TYPETERM definition, and then use the node error program to change the recovery notification to NONE for the relatively few terminals that are not to be notified. Changing the recovery message If you define a terminal with RECOVNOTIFY(MESS[...]

specific T OR within the CICS generic resource group, you must specify LUNAME as the member name—that is, the CICS APPLID, as in the first example.) Note that, if the system that issues an ISSUE P ASS LUNAME(grname) command is the only CICS currently registered under the generic resource name (for example, the others have all been shut down), t[...]

484 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 10. Writing a program to control autoinstall of terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a program to control the automatic installation of locally[...]

For an overview of autoinstall, see the CICS Resource Definition Guide . Y ou should also read the sections in the same manual that describe the CEDA commands that create the environment in which your control program can work. If you choose automatic installation for some or all of your terminals, you must: v Create some model TERMINAL definition[...]

Using model terminal support (MTS) CICS T ransaction Server for OS/390 supports the model terminal support (MTS) function of VT AM 3.3 and above. Using MTS, you can define the model name, the printer (PRINTER), and the alternate printer (AL TPRINTER) for each terminal in a VT AM table. This information is sent by VT AM in an extended CINIT RU. CIC[...]

described in “The communications area at INST ALL for shipped terminals” on page 526 . The parameter list passed at INST ALL of client virtual terminals is described in “The communications area at INST ALL for Client virtual terminals” on page 534. The parameter list passed at INST ALL of MVS consoles is described in “Chapter 1 1. Writing[...]

For example, if a 3270 printer attempts to autoinstall, the subset of matching models includes all the types in VT AM category 2 that you have defined as models. This subset could include any of the following: v DEVICE(3270) TERMMODEL(2) v DEVICE(3270) TERMMODEL(1) v DEVICE(3270P) TERMMODEL(2) v DEVICE(3270P) TERMMODEL(1) v DEVICE(3275) TERMMODEL([...]

How CICS builds the list of autoinstall models If CICS finds an MTS model name (and the model is defined to CICS and is compatible with the VT AM information describing the resource), CICS puts the model name into the model name list (Autinstmodelname_1), and also into the model name field (Modelname) in the selection list addressed by fullword [...]

VT AM characteristics of the device attempting to log on. The number in the right-hand column of the figure indicates the selection of the subset from the full list. When a terminal with a given combination of DEVICE, SESSIONTYPE, and TERMMODEL values attempts to logon, the subset of matching models passed to the control program includes all the m[...]

before returning to CICS. If you need information about the formats and acceptable character ranges for any of the return values, refer to the CICS Resource Definition Guide . If you are using MTS, then VT AM supplies the PRINTER and AL TPRINTER NETNAMEs, if specified. The printers need not be installed at this stage; however , they must be insta[...]

bisynchronous devices, which do not support QUERY , one approach is to make the definition as straightforward as possible, with no special features. If you need special models for special cases, you can use a simple mapping of, for example, NETNAME (generic or specific) to AUTINSTNAME. Y our control program could go through a table of special cas[...]

Using a table has two disadvantages, each of which loses you some of the benefits of autoinstall: it takes up storage and it must be maintained. Y ou could create a table in main temporary storage, so that it is placed in extended storage, above the 16MB line. Y ou could use a VSAM file rather than a table, to avoid the storage problem. However ,[...]

A suggested course of action is as follows: 1. Determine whether a model such as ‘mmmmmmmm’ is suitable. If there are several models that have identical BIND images, differing only in end-user options, then only the first such model is named in the above message. It will be up to your control program to make the choice, when the logmode table [...]

1. Standard Header . Byte 1 indicates the request type. For deletion of local terminals (including APPC single-session devices installed via CINIT requests) the value is X'F1'. Note: A value of X'F5' or X'F6' represents the deletion of a local APPC connection that was installed by a BIND request—see page 519. A value[...]

parameter list in your test program, upon which operations can be performed. Running your program on a terminal before you use it properly means that you can use the EDF transaction to help debug your program. Y ou can also make the program interactive, sending and receiving data from the terminal. If you find that CICS does not offer any autoinst[...]

T able 25. Autoinstall programs and copy books (continued) Language Member name Alias Library Copy books: Assembler COBOL PL/I C/370 DFHTCUDS DFHTCUDO DFHTCUDP DFHTCUDH None DFHTCUDS DFHTCUDS DFHTCUDS SDFHMAC SDFHCOB SDFHPL1 SDFHC370 Note: If you use the COBOL version of the program, you must compile it using the VS COBOL II compiler . The module g[...]

Customizing the sample program Here are three pieces of code that customize the sample program. Assembler language Figure 31, in assembler language, limits logon to netnames L77A and L77B. The model names utilized are known in advance. A logon request from any other terminal, or a request for a model which cannot be found, is rejected. * REGISTER C[...]

COBOL Figure 32 on page 501, in COBOL, redefines the NETNAME, so that the last four characters are used to select a more suitable model than that selected in the sample control program. * R7 now points to model name VALIDT CLI SELECTED_MODELNAME,C' ' MTS model name supplied? BNE VALIDM1 Yes LH R6,MODELNAME_COUNT Count of models LTR R6,R6[...]

PL/I Figure 33 on page 502, in PL/I, extracts information from the VT AM CINIT RU, which carries the BIND image. Part of this information is the screen presentation services information, such as the default screen size and alternate screen size. The alternate screen size is used to determine the model of terminal that is requesting logon. The prese[...]

DCL 1 CINIT BASED(INSTALL_CINIT_PTR), 2 CINIT_LENG FIXED BIN(15), 2 CINIT_RU CHAR(256); DCL SAVE_CINIT CHAR(256); /* Temp save area for CINIT RU */ DCL 1 SCRNSZ BASED(ADDR(SAVE_CINIT)), 2 SPARE CHAR(31), /* Bypass first part of CINIT and reach */ /* into BIND image carried in CINIT */ 2 DHGT BIT(8), /* Screen default height in BIND PS area */ 2 DWI[...]

/* Now access the screen PS area in the portion of the BIND image presented in the CINIT RU */ /* using the screen alternate height as a guide to the model of terminal attempting logon. If this cannot be determined then default to the first model in the table */ SELECT (AHGT); /* NOW GET SCRN ALTERNATE HEIGHT */ WHEN (12) NAME = 'M1'; /* [...]

504 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 1 1. Writing a program to control autoinstall of consoles Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a program to control the automatic installation of MVS con[...]

Using an autoinstall control program If you choose to have your autoinstall control program invoked for consoles, follow these steps: v Use the default autoinstall control program for terminals (DFHZA TDX or DFHZA TDY), or write your own program, using the source code of the default program and the customization examples in this chapter as a basis.[...]

The communication area at INST ALL for consoles The layout of the communication area is shown in Figure 34. The parameter list contains the following information: 1. A standard header . Byte 1 indicates the request type (this is hexadecimal character X’FD’ for INST ALL), and bytes 2 to 3 contain the component code, which is always ZC for consol[...]

How CICS builds the list of autoinstall models CICS builds the list of autoinstall models by selecting from its complete list of terminal models those models that define console devices. The complete list of autoinstall models available to CICS at any time comprises all the definitions with AUTINSTMODEL(YES) and AUTINSTMODEL(ONL Y) that are insta[...]

If you want an INST ALL request to proceed, perform these steps in your autoinstall control program: v Return an autoinstall model name in the first 8 bytes of the area addressed by fullword 4 of the parameter list. v Supply a CICS terminal name (TERMID) in the next four bytes of the return area. DFHZA TDX and DFHZA TDY take the last four non-blan[...]

CICS action on return from the control program When CICS receives control back from the autoinstall control program, it examines the return code field: v If the return code is zero, and the other required information supplied is satisfactory , CICS schedules the transaction specified on the MODIFY command to complete the request. If the installat[...]

The sample programs and copy books IBM supplies a default autoinstall control program, written in each of the supported programming languages, all of which contain the necessary support for handling consoles. For details of these, see “The sample programs and copy books” on page 497. the autoinstall control program for consoles Chapter 1 1. Wri[...]

512 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 12. Writing a program to control autoinstall of APPC connections Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a program to control the automatic installation of [...]

Local APPC parallel-session and single-session connections initiated by BIND If autoinstall is enabled, and an incoming APPC BIND request is received for an APPC service manager (SNASVCMG) session (or for the only session of a single-session connection), and there is no matching CICS CONNECTION definition, a new connection is created and installed[...]

DFHZA TDX, described in “Chapter 10. Writing a program to control autoinstall of terminals” on page 485. Thus, you can use a customized version of DFHZA TDY to autoinstall both terminals and APPC connections. Note: Both DFHZA TDX and DFHZA TDY provide function to install shipped terminals and connections, and Client virtual terminals. Y ou may [...]

described in “The communications area at INST ALL for shipped terminals” on page 526 . The parameter list passed at INST ALL of Client virtual terminals is described in “The communications area at INST ALL for Client virtual terminals” on page 534. This section describes only INST ALL of local APPC connections initiated by BIND requests. Th[...]

INST ALL_APPC_EXIT_FUNCTION A 1-byte field that defines the install request type. The equated values are: INST ALL_APPC_PS_CINIT X'F2' represents an install request for an APPC parallel-session connection from a secondary node via a CINIT request. Note: These requests cannot be received by CICS T ransaction Server for OS/390 Release 3. [...]

X'0001' Synclevel 1 X'0002' Synclevel 2. INST ALL_APPC_TEMPLA TE_NETNAME_PTR A fullword pointer to an 8-byte input/output area (TEMPLA TE_NETNAME). On invocation, TEMPLA TE_NETNAME normally contains blanks. However , if both the partner and the local CICS are registered as generic resources, it contains the NETNAME of the generi[...]

partner . This field is set whenever the local CICS is registered as a generic resource. At all other times it has a value of 0. INST ALL_APPC_GR_TYPE_PTR A fullword pointer to a 1-byte input field indicating whether this is a connection between generic resources and, if so, whether the NETNAME passed on the BIND is the partner ’s generic resou[...]

When autoinstalled APPC connections are deleted Any autoinstalled APPC connection entry is deleted if the connection is discarded (using the CEMT DISCARD command). In addition, connection entries can be deleted when the terminal or system logs off, or is disconnected from CICS. This kind of “implicit deletion” occurs for the following types of [...]

The actions taken by the supplied version of the program are to: 1. Examine the request type passed in the INST ALL_APPC_EXIT_FUNCTION field: X'F0' An incoming CINIT for a terminal or APPC single-session device. Proceed as for DFHZA TDX. See “Chapter 10. Writing a program to control autoinstall of terminals” on page 485. X'F1&ap[...]

DFHZA TDY is defined as follows in DFHAI62: DEFINE PROGRAM(DFHZATDY) DESCRIPTION(Assembler definition for sessions autoinstall control program) GROUP(DFHAI62) LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) STATUS(ENABLED) CEDF(NO) DATALOCATION(ANY) EXECKEY(CICS) EXECUTIONSET(FULLAPI) sample autoinstall programs 522 CICS TS for OS/390: C[...]

Chapter 13. Writing a program to control autoinstall of shipped terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a program to control the installation of shipped t[...]

CICS-generated aliases The autoinstall control program is invoked once for each shipped terminal or connection definition to be installed. If CICS detects that the name on a shipped definition clashes with the name of a remote terminal or connection already installed in the AOR, it generates an alias TERMID and passes it to the control program in[...]

v Whether your application programs record TERMIDs for later use. For example, an application might issue an EXEC CICS ST ART TERMID command, with a time interval after which the transaction is to be initiated against the named terminal. If, during the delay interval, the terminal definition is deleted, re-shipped, and re-installed with a differen[...]

INST ALL of local terminals and APPC single-session connections initiated by CINIT is described in “The communication area at INST ALL for terminals” on page 488. The parameter list passed at INST ALL of local APPC connections initiated by BIND requests is described in “The communication area at INST ALL for APPC connections” on page 516. T[...]

INST ALL_SHIPPED_CLASH A 1-character input field that indicates whether the TERMID of the shipped definition is already in use in the AOR. Y The name by which the terminal or connection is known in the T OR (the value of the TERMINAL or CONNECTION attribute on the shipped definition) is already in use in the AOR to identify an installed remote t[...]

INST ALL_SHIPPED_CORRID_PTR A fullword pointer to an 8-character input field containing the shipped definition’s correlation identifier . A correlation identifier is a unique “instance token” that is created when a CICS/ESA 4.1 or later terminal or connection definition is installed, and stored within the definition. Thus, if the defin[...]

DELETE_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being deleted. The equated values are: DELETE_SHIPPED_TERM (X'F A') A shipped terminal DELETE_SHIPPED_RSE (X'FB') A shipped connection (remote system entry). Note: A value of X'F1' represents the deletion of a local terminal, or an APPC si[...]

530 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 14. Writing a program to control autoinstall of Client virtual terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a program to control the installation of vi[...]

T erminal identifiers The terminal identifier (TERMID) passed to the CICS autoinstall function at install of a virtual terminal is determined using the following sequence: 1. For EPI programs: From the NetName parameter of the CICS_EpiAddT erminal function, if specified by the Client EPI program. For the Client terminal emulator: From the /n par[...]

Why override TERMIDs? Why might you want to create an alias for the supplied TERMID (or , in the case of a clash of names, to override the alias generated by CICS)? Y ou may not need to; it may depend on the way in which your server programs are written. By “server programs” we mean both the transaction programs started by Client EPI programs, [...]

Overriding Client-specified TERMIDs If TERMIDs are always nominated, in a consistent way , by your Client EPI programs, the problem of data mismatch due to server programs recording TERMIDs should not occur . However , Client-specified TERMIDs could clash with non-Client remote TERMIDs; or , if several Clients are attached to the same CICS system[...]

INST ALL_SHIPPED_ST ANDARD A fullword input field containing the following information: INST ALL_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being installed. For install of Client virtual terminals the equated value is INST ALL_SHIPPED_TERM (X'F7'). INST ALL_SHIPPED_EXIT_COMPONENT A 2-byte component code, wh[...]

long, it must be padded with trailing blanks. For a list of the characters you can use in terminal names, see the CICS Resource Definition Guide . On invocation, if INST ALL_SHIPPED_CLASH is set to 'N' (indicating no conflict of terminal names), SELECTED_SHIPPED_TERMID contains the same value as the field pointed to by INST ALL_SHIPPED[...]

At DELETE, all fields in the communications area are input only . Fields not listed below are as described for INST ALL. DELETE_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being deleted. The equated value for Client virtual terminals is DELETE_SHIPPED_TERM (X'FC'). Note: A value of X'F1' represents[...]

2. Permits the remote definition to be installed by leaving the return code field set to its default value of RETURN_OK, and returning. When DFHZA TDX or DFHZA TDY is invoked at DELETE of a Client virtual terminal, it takes no action and returns. the autoinstall control program for virtual terminals 538 CICS TS for OS/390: CICS Customization Guid[...]

Chapter 15. Writing a program to control autoinstall of programs Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes the user-replaceable program that controls the automatic installation of[...]

v CICS calls any user-replaceable program other than the program or terminal autoinstall program. v A program is named in the PL TPI or PL TSD list. Autoinstall model definitions Like autoinstall for terminals, program autoinstall uses model definitions, together with a user-replaceable control program, to create explicit definitions for resourc[...]

Autoinstall processing of mapsets T able 26 shows the differences in mapset processing between CICS regions with program autoinstall active and inactive. T able 26. Dif ferences in mapset processing between autoinstall and non-autoinstall Program autoinstall INACTIVE Program autoinstall ACTIVE CSD definition is required. CICS attempts to load a re[...]

Faster startup times W arm and emergency starts If you are using program autoinstall with cataloging , restart times are similar to those of restarting a CICS region that is not using program autoinstall. This is because, in both cases, resource definitions are reinstalled from the catalog during the restart. The definitions after the restart are[...]

The autoinstall control program at INST ALL On invocation, CICS passes a parameter list to the autoinstall control program by means of a communication area addressed by DFHEICAP . The communications area is mapped by a copybook that is supplied in each of the languages supported by CICS. The assembler form of the parameter list is as follows: PGAC_[...]

If you do not set this field, the autoinstall routine uses the language defined in the model, if one is specified. However , when control is passed to the program, CICS determines the language from the program itself, and overrides any specification provided. Y ou should not need to specify the language of executable programs that have been tra[...]

PGAC_LP A_NO CICS is to load a private copy from its own DFHRPL library concatenation. PGAC_EXECUTION_SET allows you to specify , in a 1-byte field, whether or not the program is restricted to using the distributed program link (DPL) subset of the CICS API. The equated values are: PGAC_DPLSUBSET The program is to be restricted to the DPL subset of[...]

named explicitly on the SYSID option of the EXEC CICS LINK command, the routing program can route the request to the region on which the program is to execute. The sample autoinstall control program for programs, DFHPGADX The CICS-supplied default autoinstall program is an assembler-language command-level program, named DFHPGADX. The source of the [...]

v Y ou can discard definitions after they have been installed; they are reinstalled when next referenced. v Y ou must ensure that the parameters you return to CICS are valid, and consistent with other system attributes in your CICS region. For example: – Do not return PGAC_LP A_YES on the PGAC_USE_LP A_COPY parameter if CICS is running with the [...]

v Autoinstall control program definition for DFHPGAOX. This defines the CICS-supplied COBOL version, and its status is set to DISABLED: GROUP(DFHPGAIP) PROGRAM(DFHPGAOX) DESCRIPTION(COBOL definition for program autoinstall exit) LANGUAGE(COBOL) EXECKEY(CICS) EXECUTIONSET(FULLAPI) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) STATUS(DISABLED) CEDF(NO) DAT[...]

Chapter 16. Writing a dynamic routing program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes the CICS default dynamic routing program and tells you how to write your own version. It as[...]

4. “Naming your dynamic routing program” on page 573 5. “T esting your dynamic routing program” on page 573 6. “Dynamic transaction routing sample programs” on page 574. Dynamic transaction routing This section refers to the dynamic routing of transactions initiated from user terminals or by eligible terminal-related EXEC CICS ST ART co[...]

v If the routed transaction abends, if the routing program has requested to be reinvoked at termination. Figure 43 shows the points at which the dynamic routing program is invoked. Information passed to the dynamic routing program The CICS relay program, DFHAPRT , passes information to the dynamic routing program by means of a communications area. [...]

Sometimes, the dynamic routing program may be invoked for transactions that are routed statically . This happens if a transaction defined as DYNAMIC(YES) is initiated by automatic transaction initiation (A TI)—for example, by the expiry of an interval control start request—but the transaction is ineligible for dynamic routing. In this case, th[...]

which transactions are to be routed. For information about defining remote transactions for dynamic transaction routing, see the CICS Intercommunication Guide . Important T o route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is[...]

If you want to terminate the transaction without issuing a message or abend, set a return code of X'4'. W arning: Setting a return code of X'4' for APPC transaction routing leads to unpredictable results, and should be avoided. Returning a value in DYRRETC has no effect when the routing program is invoked for notification or at[...]

Invoking the dynamic routing program on abend If you have set DYROPTER to 'Y', and the routed transaction abends, the dynamic routing program is invoked again to notify it of the abend. Y ou could use this invocation to initiate a user-defined program in response to the transaction abend. If the routed transaction abends, the DFHAPRT pro[...]

may also need to change the input communications area passed to the routed application. Field DYRACMAA of the routing program’s communications area enables you to do this; it is a pointer to the application’s communications area. Receiving information from a routed transaction If your dynamic routing program chooses to be reinvoked at the end o[...]

v If you want to keep information about how transactions are routed, it must be done in the user routing program, perhaps by writing the information to a temporary storage queue associated with this terminal. v Several transactions can form a single conversation with the end user . At the start of the conversation, resources are allocated to record[...]

– The CICS Gateway for Java™ v Calls from external CICS interface (EXCI) client programs v External Call Interface (ECI) calls from any of the CICS Client workstation products v Distributed Computing Environment (DCE) remote procedure calls (RPCs) v ONC/RPC calls. A program-link request received from outside CICS can be dynamically routed by: v[...]

v If an abend is detected after the link request has been shipped to the specified remote system, if reinvocation was requested by the routing program. Figure 43 on page 551 shows the points at which the dynamic routing program is invoked. Changing the target CICS region The communications area passed to the dynamic routing program initially conta[...]

When it is invoked for routing 9 (not for notification of a statically-routed request), your routing program can, by overwriting the DYRLPROG field, specify that an alternative program is to be linked. Y ou can specify a local or remote program, depending on the region to which the request is to be routed. Care! Be aware that, if you change the v[...]

If an error occurs in route selection If an error occurs in route selection—for example, if the SYSID returned by the dynamic routing program is unavailable or unknown, or the link fails on the specified target region— the dynamic routing program is invoked again. When this happens, you have a choice of actions: v Y ou can tell CICS not to con[...]

this; it is a pointer to the application’s communications area (or null, if no communications area was specified on the LINK command). Monitoring the application’ s output communications area A routed application can pass information back to the dynamic transaction routing program in its output communications area. If your dynamic routing prog[...]

DS OCL4 Standard header DYRFUNC DS CL1 Function code DYRCOMP DS CL2 Component code DYRFILL1 DS CL1 Reserved DYRERROR DS CL1 Route selection error code DYROPTER DS CL1 Transaction termination option DYRQUEUE DS CL1 Queue-the-request indicator DYRFILL2 DS CL1 Reserved DYRRETC DS F Return code DYRSYSID DS CL4 Default/Selected sysid DYRVER DS H Version[...]

Important The same communications area is passed to both the dynamic routing program and the distributed routing program. Some parameters are meaningful to one routing program but not to the other . Some parameter-values may be passed to one routing program but never to the other . The following list describes in detail only the parameters that are[...]

Y our routing program can alter the data in the application’s communications area. DYRACMAL is the length of the routed-to application’s communications area. If there is no communications area, this field is set to zero. DYRACTCMP is not used by the dynamic routing program. On invocation, it is set to nulls. DYRACTID is not used by the dynamic[...]

There is no default value. DYRCOMP is the CICS component code. For calls to the dynamic routing program, it is always set to 'RT'. DYRCOUNT is a count of the times the dynamic routing program has been invoked for this transaction or link request with DYRFUNC set to ‘0’, ‘1’, or ‘3’. This field allows you to limit the number o[...]

For an explanation of the DTRTRAN system initialization parameter , see the CICS System Definition Guide . 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: 0 The selected sysid is unknown. 1 The selected system is not in servi[...]

2 Invoked because a previously routed transaction or program-link request has terminated successfully . 3 Invoked for notification of the destination of a statically-routed request. This applies in the following cases: A TI requests A transaction defined as DYNAMIC(YES) has been initiated by a terminal-related automatic transaction initiation (A [...]

Y ou can change DYRLPROG on any call to the dynamic routing program, but it is effective only when DYRFUNC is ‘0’ or ‘1’. DYRNETNM is the netname of the CICS region identified in DYRSYSID. If the DYRNETNM value is changed by the initial invocation of the dynamic routing program, CICS tries to route the request to the CICS region with the n[...]

T ransaction routing The possible values are: 0 Continue processing the transaction. 4 T erminate the transaction without message or abend. 8 T erminate the transaction with either a message or an abend. Whenever the routing program is invoked, DYRRETC is set to ‘0’. When it is invoked for route selection or because an error occurs in route sel[...]

DYRSYSID is the system identifier (sysid) of a CICS region. The exact meaning of this parameter depends on the values of DYRFUNC and DYRTYPE: v When DYRFUNC is set to ‘0’ (route selection): – If DYRTYPE is set to ‘0’, ‘2’, or ‘3’ (any type of transaction routing), DYRSYSID contains: - The CICS region name specified on the REMOTE[...]

v When DYRFUNC is set to ‘4’ (abend), DYRSYSID contains the name of the CICS region on which the transaction abended. DYRTRAN contains the remote transaction id. T ransaction routing When DYRFUNC is set to ‘0’ or ‘3’, DYRTRAN contains the remote transaction id specified on the REMOTENAME option of the installed transaction definition.[...]

Naming your dynamic routing program The supplied, user-replaceable dynamic routing program is named DFHDYP . If you write your own version, you can name it differently . After the system has been loaded, to find the name of the dynamic routing program currently identified to CICS, use the EXEC CICS INQUIRE SYSTEM command. Field DTRPROGRAM contain[...]

Dynamic transaction routing sample programs The CICS-supplied sample dynamic routing program is named DFHDYP . The corresponding copy book that defines the communications area is DFHDYPDS. There are assembler-language, COBOL, PL/I, and C source-level samples and copy books. The supplied programs and copy books, and the CICSTS13.CICS libraries in w[...]

Chapter 17. Writing a distributed routing program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes the CICS default distributed routing program and tells you how to write your own versio[...]

6. “Distributed transaction routing sample programs” on page 593. Dif ferences from the dynamic routing interface This section discusses some significant ways in which the distributed routing interface differs from the dynamic routing interface. If you have previously written a dynamic routing program, and are about to write a distributed rout[...]

v Select a target region by supplying a netname (any value set in the DYRNETNM field of the communications area is ignored). The target must be specified by its CICS system identifier (sysid). v Change the remote transaction name passed to the target region. (Any value set in the DYRTRAN field of the communications area is ignored.) v Change th[...]

When the distributed routing program is invoked For BTS processes and activities started by RUN ASYNCHRONOUS commands, CICS invokes the distributed routing program at the following points: On the requesting region: 1. Either of the following: v For routing the activity . This occurs when the transaction associated with the activity is defined as D[...]

Changing the target CICS region The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the process or activity is to be routed. This is derived from the value of the REMOTESYSTEM option of the installed transaction definition o[...]

2. Y ou can tell CICS to treat the request as “unserviceable”, by issuing a non-zero return code in DYRRETC. Sometimes, perhaps because of a transaction aff inity , it is essential that an activity should execute on a particular target region, and on no other . If this is the case, and the target region is unavailable, classify the request as u[...]

Note that, because the routing program is distributed, all the CICS regions in the transaction routing set must have access to the data set. v The distributed routing program can be RMODE ANY but must be AMODE 31. Routing of non-terminal-related ST ART requests This section describes how to use a distributed routing program to dynamically route non[...]

When the distributed routing program is invoked For non-terminal-related ST ART requests that are eligible for enhanced routing, CICS invokes the distributed routing program at the following points: On the requesting region: 1. Either of the following: v For routing the request. v For notification of a statically-routed request. This occurs when a[...]

Changing the target CICS region The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the request is to be routed. This is derived from the value of the REMOTESYSTEM option of the installed transaction definition on the reques[...]

If an error occurs in route selection If an error occurs in route selection—for example, if the sysid returned by the distributed routing program is unavailable or unknown—the routing program is invoked again. When this happens, you have a choice of actions: 1. Y ou can try to route the request to a different target region, by changing the sysi[...]

v The distributed routing program can be RMODE ANY but must be AMODE 31. Parameters passed to the distributed routing program Figure 48 shows the communications area passed to the distributed routing program. The communications area is mapped by the copy book DFHDYPDS, which is in the appropriate CICS library for all the supported programming langu[...]

Important The same communications area is passed to both the distributed routing program and the dynamic routing program. Some parameters are meaningful to one routing program but not to the other . Some parameter-values may be passed to one routing program but never to the other . The following list describes in detail only the parameters that are[...]

This field applies only to the routing of BTS processes and activities, not to the routing of non-terminal-related ST ART requests. DYRACTN is the name of the BTS activity being routed. (When a process is being routed, DYRACTN returns the name of the root activity—that is, DFHROOT .) This field applies only to the routing of BTS processes and a[...]

2. CICS rejected the allocate request automatically because the QUEUELIMIT value specified on the CONNECTION resource definition has been reached. 4 A 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 [...]

For detailed information about which non-terminal-related ST ART requests are eligible for dynamic routing, see the CICS Intercommunication Guide . 4 Invoked because the transaction associated with the routed request abended. This invocation occurs on the target region. 5 Invoked for transaction initiation. The transaction associated with the route[...]

This field applies only to the routing of BTS processes and activities, not to the routing of non-terminal-related ST ART requests. Its contents are significant on transaction termination calls. The possible values are: Y This is the final activation of the BTS process. N This is not the final activation of the BTS process. When it is invoked a[...]

DYRRTPRI indicates whether or not the dispatch priority of the transaction should be passed to the application-owning region, if the connection between the terminal-owning region and the application-owning region is MRO. This field is not used by the distributed routing program. On invocation, it is set to 'N'. DYRSRCTK is the MVS worklo[...]

v When DYRFUNC is set to ‘5’ (transaction initiation), DYRSYSID contains the name of the target region on which the routed request is to be executed. (This is also the region on which the distributed routing program is invoked.) v When DYRFUNC is set to ‘6’ (routing completed), DYRSYSID contains the name of the target region to which CICS t[...]

DYRVER is the version number of the dynamic routing interface. For CICS T ransaction Server for OS/390 Release 3, the number is “5”. Naming your distributed routing program The supplied, sample distributed routing program is named DFHDSRP . If you write your own version, you can name it differently . After the system has been loaded, to find t[...]

If you want to route requests dynamically , you must customize DFHDSRP , or replace it completely with your own routing program. sample distributed routing programs 594 CICS TS for OS/390: CICS Customization Guide | |[...]

Chapter 18. Writing a CICS–DBCTL interface status program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . The CICS–DBCTL interface status program DFHDBUEX is a user-replaceable program forming part of the[...]

The parameter list contains the following information: DBUREQT Request T ype. The function code has one of the following values: DBUCONN (X'01') Connected DBUDISC (X'02') Disconnected. DBUREAS Reason for Disconnection. Contains flags: DBUMENU (X'01') Disconnected from menu DBUDBCC (X'02') Checkpoint Freeze i[...]

The sample contains an example, as part of a comment, of how to enable and how to disable a transaction. T o use the program, it is necessary for transactions using DBCTL to be defined in the CSD as DISABLED. Y ou can code your own CICS–DBCTL interface status program in any of the languages supported by CICS. For information about the job contro[...]

598 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 19. Writing a 3270 bridge exit program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . The 3270 bridge provides an interface so that you can run 3270-based CICS transactions without a 3270 terminal. I[...]

600 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 20. Writing a security exit program for IIOP Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . Incoming requests using the Internet Inter-Orb Protocol (IIOP) are processed by CICS under a default USERID[...]

602 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 21. Writing a program to tailor JVM execution environment variables Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter . This chapter describes how to write a user-replaceable program to tailor the environ[...]

CICS_PROGRAM Contains the name of the CICS program (1-8 characters) associated with the Java class to be run. No value is set in SDFHENV . This name is established at run-time; it is returned to DFHJVMA T for information only , any changes will be ignored by CICS. CICS_PROGRAM_CLASS Specifies the CICS user class name. This is the equivalent of the[...]

MAXHEAPSIZE Sets the maximum heap size for the JVM, in bytes. A default value of 8000000 bytes (8M) is set in SDFHENV . This is the recommended default for the MVS JVM. This is above-the-line storage. MINHEAPSIZE Sets the minimum heap size for the JVM, in bytes. A default value of 1000000 bytes (1M) is set in SDFHENV . This is the recommended defau[...]

606 CICS TS for OS/390: CICS Customization Guide[...]

Part 4. Customizing the XRF overseer program © Copyright IBM Corp. 1977, 1999 607[...]

A general note about user-written programs On return from any user-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information). For information abo[...]

Chapter 22. The extended recovery facility overseer program The information in this chapter is of interest only to users of the extended recovery facility (XRF). Details of XRF are provided in the CICS/ESA 3.3 XRF Guide . Guidance information about running the overseer , including a sample job stream, is provided in the CICS Operations and Utilitie[...]

Snap to take a snap dump of the sample program End to terminate the sample program Open to ask the overseer to try to open CICS availability manager (CA VM) data sets that it has previously failed to open. The full format of the operator command entered at the MVS console is: MODIFY overseer-jobname,command-identifier where “command-identifier?[...]

which was in an intermediate state when the Display command was processed. Reissuing the Display command causes UNKN to be replaced by another status value. OLD The information displayed for the alternate refers to out-of-date information about the system that was the alternate until a recent takeover . That system is the current active, and the in[...]

related regions to be taken over , because the new active region can continue communication with the other active regions. T akeover is therefore likely to be your preferred course of action. Enabling and disabling restart in place: The restart-in-place function of the overseer program can be enabled and disabled using the Restart command. When you[...]

Opening CA VM data sets dynamically When the overseer program is initialized, it is possible that some CA VM data sets have not yet been formatted by a CICS system. The overseer program obtains an ‘open error ’ return code on these data sets, and subsequent attempts to display details about the associated CICS systems receive the response ‘NO[...]

each active-alternate pair . Y ou create this data set and initialize it with information about active-alternate pairs before you use the overseer for the first time. Y ou also have to redefine the DFHOSD data set whenever you want to change the information that it holds. CICS provides a sample job stream that you can use to: v Delete and define[...]

DFHWOSM FUNC=READ Retrieve status information for a named generic applid from the CA VM data sets DFHWOSM FUNC=TERM Close communication with DFHWOS. The macros are described in detail in the following sections. For all the DFHWOSM macros, the following rules apply: v The “label” field is optional. v If the macro has an input parameter list, th[...]

Register 15 Contains one of the following completion codes: 0 Communication successfully initialized between the overseer program and DFHWOS 4 Incorrect T OKEN value supplied 8 Insuff icient storage. DFHWOSM FUNC=CLOSE macro The DFHWOSM FUNC=CLOSE macro terminates access to the CA VM data sets for a named generic applid. Input The P ARM value is a [...]

v An 8-byte JES job ID v A 256-byte SSOB return area. The T OKEN value is the ENTRY token. Output Register 15 Contains the following completion codes: 0 JES cancel completed; SSOB and status array returned from JES Nonzero Return code from JES. DFHWOSM FUNC={JJS|QJJS} macro Supplied with a job name and JES job identifier , both versions of the DFH[...]

Nonzero Return code from JES. DFHWOSM FUNC=OPEN macro The DFHWOSM FUNC=OPEN macro initializes access to the CA VM data sets for a named generic applid. Input The P ARM value is a pointer to three further addresses, and these are: 1. The address of the generic applid 2. The address of the ddname of the control data set 3. The address of the ddname o[...]

the required MVS command is provided as input to the macro, and the OSCMD service issues an SVC 34 specifying this command text. In addition, the OSCMD service issues an MVS WTO request so that a copy of the command text appears on the MVS console to keep the operator informed of what is about to happen. This copy has the comment ‘(BY IOP)’ app[...]

Parameter list pointer Generic Applid Address Generic Applid DBLLIST Address OUTPUT INPUT OUTPUT Item 1 address DBLID 1 Item 1 length Item 2 address DBLID 2 Item 2 length .. . .. . Item n address DBLID n Item n length Figure 50. Input to and output from the DFHWOSM FUNC=READ macro DBLIDs for the active: DBLID1 EQU X'0001' JOB NAME DBLID2 [...]

Notes: 1. The data structures of the status information pointed to by items X'0024' and X'0124' are provided in DSECT DFHXRHDS of CICSTS13.CICS.SDFHMAC. 2. The data structures of the status information pointed to by items X'0025' and X'0125' are provided in DSECT DFHXRGDS of CICSTS13.CICS.SDFHMAC. 3. The data[...]

Reading DBCTL status information from the CA VM data sets If you are using DBCTL and have active and alternate DBCTL subsystems, status information about the subsystem connected to the active CICS is written to the CA VM data sets. However , the supplied sample overseer program does not read the DBCTL information from the CA VM data set. If you wan[...]

Output Register 15 Contains the following completion codes: 0 Communication terminated successfully Nonzero Request failed. Customizing the sample overseer program The sample overseer program consists of four modules link-edited together . The main module is DFH$AXRO ; the other three modules are subroutines, described below: DFH$AGCB sets up reque[...]

v T o extend the function of the overseer program, you can incorporate the CEBT command, which is normally issued by the console operator to control the alternate. The CEBT command is described in the CICS Supplied T ransactions manual. All of the CEBT functions are available for use in the overseer program, though it is unlikely that you will fin[...]

T o include this LOOP W ARNING code, set the variable &LOOPW ARN to ‘1’ and reassemble the sample. Assembling and link-editing the overseer program The non-specific job control statements required to assemble and link-edit the overseer program are the same as those required for user-replaceable programs, and are described in “Assembling [...]

626 CICS TS for OS/390: CICS Customization Guide[...]

Part 5. CICS journaling, monitoring, and statistics © Copyright IBM Corp. 1977, 1999 627[...]

A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 5 of this book: v Upon return from any user-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers r[...]

Chapter 23. CICS logging and journaling The CICS log manager provides facilities for the creation, control, and retrieval of journals during real-time CICS execution. Journals are intended to record, in chronological order , any information that you may later need to reconstruct data or events. For example, you could create journals to act as audit[...]

3. T ertiary storage—a form of archive storage, used as specified in your hierarchical storage manager (HSM) policy . Optionally , older records can be migrated to tertiary storage, which can be either DASD data sets or tape volumes. Figure 53 and Figure 54 on page 631 show the types of storage used by the MVS system logger . MVS1 Current Data S[...]

Enabling, disabling, and reading journals Journal records are written to a log stream either directly from a user application program, or from a CICS management program on behalf of a user application. Journal records can be written from a user application using the EXEC CICS WRITE JOURNALNAME command. For programming information about the EXEC CIC[...]

Reading journal records of fline Access to journaled data in log streams is provided through an MVS subsystem interface (SSI), LOGR. Y our existing user programs can read the general log streams, providing you specify , in your batch job JCL, the SUBSYS parameter and supporting options on the DD for log streams. By specifying the LOGR subsystem nam[...]

Server for OS/390 Release 1. Each journal record in these logs, if presented in the newer format, contains more information than in the equivalent journal record presented in the CICS/ESA 4.1 format. System logs are always presented in CICS T ransaction Server for OS/390 format.. Each general log comprises a stream of contiguous blocks of journaled[...]

Format of general log block header The log block header contains information of a general system-wide nature such as the CICS applid writing the journal block. Figure 56 shows the format of the log block header . Start time (GMT) Start time (Local) 88 8 8 LGBH GLOBAL INFO LGBH GENERIC APPLID LGBH ST ART GMT LGBH ST ART LOCAL CICS applid nn = block [...]

Format of general log journal record The journal record comprises a record header followed by caller data. The record header contains information that describes some of the attributes of the record, such as the time it was written. Figure 57 shows the format of the record header . The caller data differs depending on the CICS component issuing the [...]

Start-of-run record When CICS connects to a general log, it writes a start-of-run record to it as the first record for this run of CICS. This record comprises a record header (with the same format as that for any general log journal record) followed by a start-of-run body . Its format is shown in Figure 58. Format of caller data Caller data follow[...]

Caller data written by file control The file log and journal block (FLJB) describes the caller data that file control writes as part of its journal records. The copybook DFHFCLGD defines the FLJB DSECT . There are two sections in the FLJB: the first section contains data that is applicable to all journal records written by file control; the s[...]

v The FLJB_COMMON_DA T A section, and v The caller data image sections which consist of the FLJB_CD_KEY (the length of which is given in FLJB_COMMON_DA T A) and the FLJB_CD_DA T A section. The FLJB_CD_DA T A section (the length of which is given in FLJB_COMMON_DA T A) contains the image of the caller data. The format of such a record written for th[...]

The format of the FLJB_COMMON_DA T A section is shown in Figure 62 . 11 Fixed length 82 Record type Flag by te X'80' fil e control autojo urnal record X'40' forward recovery log record X'20' system log reco rd X'10' log-of-log record Reserved File name FLJB FILE NAME FLJB BITS FL JB RECORD TYPE X'80&apos[...]

Write-delete record types There are four sections in the journal records written for write-delete record types: v The FLJB_GENERAL_DA T A section, v The FLJB_WRITE_DELETE_DA T A section, and v The two caller data image sections, which consist of: – FLJB_WDD_BASE_KEY (the length of which is given by FLJB_WDD_BASE_KEY_LENGTH in FLJB_WRITE_DELETE_DA[...]

File-close record types There are two sections in the journal records written for file-close record types: v The FLJB_GENERAL_DA T A section v The FLJB_CLOSE_DA T A section. The format of such a record written for file-close record types is shown in Figure 65. See Figure 61 on page 639 for the format of the FLJB_GENERAL_DA T A section. The format[...]

Tie-up record types There are two sections in the journal records written for tie-up record types: v The FLJB_GENERAL_DA T A section v The TIE_UP_RECORD_DA T A section. The format of such a record written for tie-up record types is shown in Figure 67. See Figure 61 on page 639 for the format of the FLJB_GENERAL_DA T A section. The format of the TIE[...]

44 4 2 1 1 26 24 4 44 2 FLJB T UR B I TS Fi xed l engt h Fi xed l engt h Fi xed l engt h Fi xed l engt h Log str eam nam e of forward r ecovery l og FL JB TUR FWDRECOVLOG NAME FLJB TUR PA TH DSN AME FLJ B TUR BASE DSNAME FLJ B TU R BASE DSN AME LENGTH FLJB TUR R ECO RD FOR MAT FLJB TUR DAT ASET TY PE Base dat a set name Path dat a set nam e P ath d[...]

Note: The format of caller data in journal records written by file control in RLS mode is identical to that in journal records written by file control in non-RLS mode except for FLJB_TUR_BITS where a value of X'80' indicates RLS-access. T erminal control prefix data CICS terminal control (TC) writes journal records to track the message[...]

See the CICS Front End Programming Interface User’s Guide for more information about FEPI journaling. Structure and content of COMP A T41-format journal records SMF records The following description does not apply to journal records written to an SMF data set. These are described on page 653. CICS allows you to format journal records so that they[...]

A graphical overview of the format of a general log, showing the format of a complete block, is shown in Figure 71. Format of COMP A T41 journal control label header Each log block starts with a journal control label header . There is one journal control label header per log block. It is 42 bytes long, and comprises a length field, label header , [...]

The label prefix part of the journal control label header is 32 bytes long, and its format is shown in Figure 74. Record number within block JCRLRN Length of record JCRLL 2 2 22 2 User-type ID JCRUTRID System-type ID JCRSTRID X'0000' '0000' if CICS journal request. Otherwise code specified in JTYPEID keyword of user reques t &a[...]

Format of journal record Each CICS journal record comprises a system header , system prefix, user prefix, and journaled data. The format of a journal record is shown in Figure 75. The system header is 10 bytes long. Its format is shown in Figure 76. System header V ariable length User prefix Journal data Fixed length System prefix 10 Figure 75. F[...]

The field JCRSTRID (the system-type ID) and the field JCRUTRID (the user-type ID) in the system header allow you to distinguish those journal records output by CICS (by such components as terminal control), from those issued by direct user requests. For CICS journal requests, JCRUTRID contains binary zeros, and JCRSTRID contains a 1-byte function[...]

command via the JTYPEID, PREFIX, and PFXLENG parameters. Its format is shown in Figure 78. Field JCSPUP is set in the system prefix area if a user prefix is present in a journal record. The journaled data then follows. If you want a length field for the data, you must include it in the data. Alternatively , you can compute the length of the data[...]

*********************************************************************** ** FUNCTION IDENTIFIERS ** *********************************************************************** * * * X'20' PLUS X'8-' ...USE FOR AUTOMATIC JOURNALING * * X'40' PLUS X'8-' ...USE FOR AUTOMATIC LOGGING * ********************************[...]

*********************************************************************** * TERMINAL CONTROL FUNCTION IDENTIFIERS * * * FIDTCML EQU X'F0' SYNCPOINT - LOG SEQUENCE * NUMBERS * * CAN BE OR'ED WITH ANY OF * THE FOLLOWING THREE FIELDS: FIDTCDWL EQU X'01' ...DEFERRED WRITE DATA FIDTCFMH EQU X'02' ...+ FUNCTION MANAGEMENT[...]

Identifying records for the start of tasks and UOWs Y ou can identify records written to mark the start of tasks by examining the value of the system prefix field JCSPF1. If the JCSPSOTK bit is set, the record has been written at the start of the task. If the JCSPLSTK bit is set in field JCSPF1, then the record has been written at the start of t[...]

The SMF block header This block describes the system creating the output. Its format is shown in Figure 82. Note: CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFH_LG). SMF sets the remainder of the byte according to the operating system level and other factors. For an explanation of the [...]

The CICS data section This section contains a variable number of CICS journal records. Each record comprises a general log record header , the format of which is shown in Figure 57 on page 635. This is followed by a user header , the format of which is shown in Figure 59 on page 637. This is then followed by the caller data. If this is the first r[...]

656 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 24. CICS monitoring This chapter describes the monitoring facilities of CICS T ransaction Server for OS/390, and tells you how to: v Control the types of monitoring data collected by CICS v Gather more performance data about specific transactions than is provided automatically by CICS. The chapter is divided into the following sections: 1.[...]

Y ou can choose which classes of monitoring data you want to be collected. How to do this is described in “Controlling CICS monitoring” on page 662. Performance class monitoring data CICS performance class monitoring data is collected at system-defined event-monitoring points (EMPs) in the CICS code. Y ou cannot relocate these monitoring point[...]

v T o tell CICS that you want specific system-defined performance data not to be recorded during a particular CICS run. See “DFHMCT TYPE=RECORD”. Full details of the DFHMCT macros are provided in the CICS Resource Definition Guide , and you should refer to that book when reading the following sections. DFHMCT TYPE=EMP There must be a DFHMCT [...]

also has its own numeric identifier that is unique within the group identifier . For example, the transaction sequence number field in a performance record belongs to the group DFHT ASK, and has the numeric identifier ‘031’. Using these identifiers, you can exclude specific fields or groups of fields, and reduce the size of the performa[...]

Example 3: Example 3 shows 32 bytes of user data being updated in the character string reserved for that purpose. The updated data starts at of fset 0, and the data is not more than 32 bytes in length. DFHMCT TYPE=EMP entries for DBCTL The following MCT entries make use of the two event-monitoring points in the performance class used by the CICS-DB[...]

v W ait for temporary storage data set extension v W ait for shared temporary storage v W ait for shared temporary storage pool v W ait for file string v W ait for file buffer v W ait for LSRPOOL string. An exception record is created each time any of the resources covered by exception class monitoring becomes constrained by system bottlenecks. I[...]

When CICS is running, you can control the monitoring facility dynamically . Just as at CICS initialization, you can switch monitoring on or off, and you can change the classes of monitoring data that are being collected. There are two ways of doing this: 1. Y ou can use the master terminal CEMT INQ|SET MONIT OR command, which is described in the CI[...]

The label ‘MNSMFDS’ is the default DSECT name, and SMF is the default PREFIX value, so you could also generate the DSECT simply by coding: DFHMNSMF The MNSMFDS DSECT has the format shown in Figure 85. * START OF THE SMF HEADER * MNSMFDS DSECT SMFMNLEN DS XL2 RECORD LENGTH SMFMNSEG DS XL2 SEGMENT DESCRIPTOR SMFMNFLG DS X OPERATING SYSTEM INDICAT[...]

Notes: 1. CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFMNFLG). SMF sets the remainder of the byte according to the operating system level and other factors. For an explanation of the setting of the other bits, refer to the OS/390 MVS System Management Facilities (SMF) manual. 2. For di[...]

CICS data section The CICS data section can be made up of a dictionary data section, a performance data section, or an exception data section. Y ou can identify which of these you are dealing with by looking at the value of field SMFMNCL in the SMF product section. Each of the data section types is described in the sections that follow . Dictionar[...]

Whenever the monitoring of performance class data is switched on, whether at CICS initialization or while CICS is running, a dictionary data section is written. So, if the monitoring of performance class data is switched on and off three times during a single CICS run, there are three separate, but identical, dictionary data sections for that run. [...]

FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHTASK C001 4 X'0001' X'0000' TRAN DFHTERM C002 4 X'0002' X'0004' TERM DFHCICS C089 8 X'0003' X'0008' USERID DFHTASK C004 4 X'0004' X'0010' TTYPE DFHCICS T005 8 X'0005' X'0014' START DFHCICS T006 8 X'00[...]

FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHSTOR A117 4 X'0033' X'01C4' SCCGETCT DFHSTOR A120 4 X'0034' X'01C8' SCCGETCT DFHSTOR A033 4 X'0035' X'01CC' SCUSRHWM DFHSTOR A106 4 X'0036' X'01D0' SCUSRHWM DFHSTOR A116 4 X'0037' X'01D4' SC24CHWM DFHSTOR [...]

FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHTASK A059 4 X'0066' X'02A0' ICPUINCT DFHTASK A066 4 X'0067' X'02A4' ICTOTCT DFHSYNC A060 4 X'0068' X'02A8' SPSYNCCT DFHCICS A025 4 X'0069' X'02AC' CFCAPICT DFHFEPI A150 4 X'006A' X'02B0' SZALLOCT DFHFEPI A[...]

Note: The “field types” in Figure 88 are: A Count C Byte-string P Packed decimal number S Clock T T ime stamp. FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHTASK S008 8 X'0099' X'0370' USRCPUT DFHTASK S014 8 X'009A' X'0378' SUSPTIME DFHTASK S102 8 X'009B' X'0380' DISPWTT DFHTASK S255 8[...]

Performance data sections Each performance data section is made up of a string of field connectors, followed by one or more performance data records. All of the performance records produced by a single CICS run have the same format, and each record is, by default, 664 bytes long. However , the length of the performance records changes if you add u[...]

How the string of field connectors is constructed: When CICS is initialized, a unique connector value is assigned to every dictionary entry . CICS then examines the MCT entries for this run to see if you have excluded any system-defined performance data. If you have, the offset values for their corresponding dictionary entries are set to X'F[...]

Exception data sections The format of an exception data record (including the SMF header and SMF product section) is shown in Figure 91. The exception data section contains a single exception record representing one exception condition. The format of the exception data section can be mapped by the DSECT MNEXCDS, which you can generate using the DFH[...]

For further information about exception class data, see the CICS Performance Guide , which lists all the system-defined data that can be produced by CICS monitoring. monitoring record formats Chapter 24. CICS monitoring 675[...]

676 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 25. CICS statistics This chapter is divided into the following sections: 1. “Introduction to CICS statistics” describes the types of statistics data, and the use of the EXEC CICS COLLECT ST A TISTICS command. 2. “CICS statistics record format” on page 682 describes the format of CICS statistics SMF type 1 10 records. 3. “Global us[...]

or v The RECORDING option of the EXEC CICS SET ST A TISTICS command is set to ON. The TS data sharing server writes interval statistics if statistics recording was set to SMF or BOTH by the ST A TSOPTIONS server initialization parameter , or by the server command SET ST A TSOPTIONS. When interval statistics are written, the statistics counters are [...]

v EXEC CICS SET ST A TISTICS ON|OFF RECORDNOW . CICS writes requested statistics to SMF even if, on one of the following, you have specified OFF: v The ST A TRCD system initialization parameter v The CEMT SET ST A TISTICS command v The RECORDING option of the EXEC CICS SET ST A TISTICS command. Statistics counters are not reset. Requested reset st[...]

If an autoinstall terminal logs on again before the expiry of the delay interval, then the accumulation of statistics continues until the next interval. At that interval, the accumulation of statistics is restarted. DBCTL Whenever CICS disconnects from DBCTL, CICS collects the statistics covering the whole of the DBCTL connection period. DB2 Whenev[...]

System dumps Whenever a system dump table entry is deleted, CICS collects the statistics covering the period since the last interval. TCP/IP services Whenever a TCP/IP service is closed, CICS collects the statistics covering the installed period since the last interval. T ransaction classes Whenever an installed transaction class definition is dis[...]

Important Statistics counters are reset in various ways. Specific counters may be reset to: v 0 v 1 v A new peak value v Not reset v None of the above. For information about the resetting of specific statistics counters, refer to the CICS Performance Guide . The EXEC CICS COLLECT ST A TISTICS command In addition to the types of statistics data de[...]

SMF header and SMF product section The SMF header describes the system creating the output. The SMF product section identifies the subsystem to which the statistics data relates, which, in the case of CICS statistics, is the CICS region, or the TS data sharing server . Both the SMF header and the SMF product section can be mapped by the DSECT STSM[...]

Notes: 1. CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFSTFLG). SMF sets the remainder of the byte according to the operating system level and other factors. For an explanation of the setting of the other bits, refer to the OS/390 MVS System Management Facilities (SMF) manual. 2. The co[...]

3. Fields SMFSTINT and SMFSTINO are only relevant if SMFSTRQT is ‘INT’. Otherwise both values should be ignored. 4. For TS data sharing, the record subtype is X’0003’ and certain fields are not set or are used in a different way . SMFSTPRN and SMFSTSPN contain the server prefix (DFHXQ) and the pool name. 5. For coupling facility data tabl[...]

on page 682. For further guidance information about the fields within the statistics data records, see the CICS Performance Guide . STIVERS takes the value ‘1’ for this release of CICS. The TS data sharing statistics use no symbolic names, but relate to the STID values as follows: STID STID Symbolic Value Copy book Type of record name STISMDSA[...]

The coupling facility data table server statistics use no symbolic names, but relate to the STID values as follows: The named sequence number server statistics use no symbolic names, but relate to the STID values as follows: Global user exit in the CICS statistics domain There is one global user exit point (XSTOUT) in the CICS statistics domain. Th[...]

Processing the output from CICS statistics There are several utilities to help you process statistics output. Y ou can use: The CICS-supplied DFHSTUP program For information about how to run DFHSTUP , refer to the CICS Operations and Utilities Guide . For information about how to interpret the report produced by DFHSTUP , see the CICS Performance G[...]

Part 6. Customizing CICS compatibility interfaces © Copyright IBM Corp. 1977, 1999 689[...]

A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 6 of this book: v Upon return from any customer-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registe[...]

Chapter 26. Using TCAM with CICS This chapter describes the use of the telecommunications access method (TCAM) with CICS T ransaction Server for OS/390 Release 3. Important CICS T ransaction Server for OS/390 Release 3 supports only the DCB interface to TCAM, and not the ACB interface. This means that, in order for CICS to use it, TCAM has to be ru[...]

CICS with TCAM SNA The CICS-TCAM interface has an enhanced data stream support that enables an appropriate TCAM message control program (MCP) to control the SNA session. The TCAMFET=SNA operand in DFHTCT TYPE=LINE allows TCTTEs to be specified for SNA devices. Y ou must be prepared to write an appropriate TCAM SNA message control program to comple[...]

T ransaction control In the transaction control method of protocol management, the transaction controls the protocol. The SNA session should be bound with a protocol of HDX-FF with brackets when running this type of management. When using transaction control, the communication control byte (CCB) is used to relay information from the transaction to [...]

Batch processing When running a batch logical unit, a point to consider is how to get the transaction identification to CICS on the “begin data set” condition. The alternative methods are discussed below . The first method is for the DMH to recognize the “begin data set” condition by interrogating the FMH and by editing the transaction ID[...]

each output queue from CICS. In CICS, there are corresponding terminal control table line entries (TCTLEs) for each input queue, and for each output queue (that is, for each TPROCESS block). DD cards (such as those shown in Figure 101) are used to correlate the TCAM control blocks with the CICS control blocks. The CICS terminal control table contai[...]

The CICS terminal control table terminal entries (TCTTEs) define the terminals associated with a particular line entry (TCTLE). For each physical terminal communicating with CICS through TCAM, a corresponding TCTTE containing the terminal identification must be associated with a TCTLE. Duplicating individual TCTTEs for both the input TCTLE and th[...]

For information about the DFHTCT macros, see the CICS Resource Definition Guide . Logic flow The following is a generalized description of the sequence of events that occurs in CICS when interfacing with TCAM. INPUT STEP ACTION A TCAM notifies CICS that it has data for a particular input TCTLE, by posting its ECB. B CICS gets a TIOA and attaches[...]

OUTPUT STEP ACTION A Y ou issue an EXEC CICS SEND request in your application program. B The TCP terminal scan recognizes the SEND request. C CICS checks whether an output user exit (XTCTOUT) has been specified. If it has, CICS links to the user exit routine, where you may edit your output data before passing it to TCAM. (See the discussion of XTC[...]

T erminal error program The CICS-TCAM interface implementation has resulted in the expansion of the CICS terminal error program (DFHTEP) error codes and conditions. The errors and actions shown in T able 32 on page 700 are unique to TCAM, and should be considered in DFHTEP . TCAM input process queue Input TCTLE QUTQ= (ABC) Special TCTTE TIOA Output[...]

T able 32. DFHTEP error codes and conditions unique to TCAM Error code Condition Action X'87'(TCEMCUI) Unsolicited input T erminal ‘receive only’ T erminal ‘out of service’ T ask has not issued a read No available TCTTE from pool. a a, b No default No default X'9F'(TCEMIDR) TCAM has issued an invalid destination return c[...]

The possible values of TCTTETCM are: V alue Message segment X'00' Null X'40' Intermediate portion of message X'F1' First portion of message X'F2' Last portion of message X'F3' Entire message X'F4' Intermediate portion of message, end of record X'F5' First portion of message, end [...]

locked until a TCTTE becomes available because the task has ended. The number of TCTTEs in the pool influences the degree of multitasking. Y ou should consider providing enough terminal entries in the pool to avoid an ‘unsolicited input’ condition (see “TCAM queues” on page 703), because there is no available entry in the pool. When DFHTCA[...]

permanently locked. TCAM queues Because a queue is a sequential data set, the second message on the queue cannot be retrieved until the first message has been processed. T o keep messages flowing smoothly through the queue, it is essential that each message be processed as soon as it arrives. In the CICS-TCAM interface, “processing the message?[...]

T o allow processing of input to continue, DFHTEP may take either of the following steps: v If the input line is placed in service by DFHTEP , the CICS-TCAM interface retries the operation. In this case, a count mechanism is recommended in DFHTEP to prevent a loop occurring if the task never issues a READ, or a TCTTE never becomes available. v Perh[...]

The terminal services parameters that do not set bits in the communication control byte are SEND, W AIT TERMINAL, and SA VE. Bits in the communication control byte are set for the ISSUE DISCONNECT and CONVERSE parameters, and for the FMH and LAST parameters on the EXEC CICS SEND command. The CICS-TCAM interface does not support the RESET parameter [...]

Device-dependent data Dependent on the device: 3270, or other . See the following sections on the relevant devices. FMH Function management header . SNA only = length in first byte non-SNA = not applicable. Message User data. TCAM with 3270 devices The CCB and device-dependent data for an input message from TCAM to CICS have the following format: [...]

TCAM user exits There are three TCAM global user exit points: 1. XTCA TT , invoked before issuing a transaction manager A TT ACH for a transaction identification received in response to polling 2. XTCTIN , invoked following the completion of any TCAM input event, (that is, after the individual TCTTE has been located, but just before CICS checks to[...]

CICS-TCAM termination CICS is terminated in the normal manner . No modifications to termination procedures are required to support the CICS-TCAM interface. If both CICS and TCAM are being terminated, CICS should be terminated first, to avoid an abnormal termination of CICS. starting and terminating TCAM 708 CICS TS for OS/390: CICS Customization [...]

CICS and TCAM: program interrelationship Figure 104 illustrates the interrelationship between the TCAM message control program (MCP) and the TCAM application program. CICS is regarded as an application program by TCAM. S70A T erminal S70B S75A T32C 3271 MH 3270 message handler PG 3270 DCB TRM 2 TRM1 LG2260 DCB TO TCA M message handler 3270 (Rem ot [...]

TCAM message control program (non-SNA) This section gives an example of a non-SNA TCAM message control program. This MCP shows the relationship between the MCP definition and the CICS terminal control table generation. It should not be construed as a typical or usable MCP for CICS. For further information about MCP definition for a variety of dev[...]

S75A TERMINAL QBY=T,DCB=PG3270,RLN=1,TERM=327R,QUEUES=MO, * ADDR=E2E240402D,NTBLKSZ=1856 POLLST1 INVLIST ORDER=(TRM1+02) POLLST2 INVLIST ORDER=(TRM2+02) POLL70R INVLIST ORDER=(T32C-C1C17F7F2D,S70A+C1C140402D, * S70B+C1C1C1C12D, * S75A+C2C27F7F2D,S75A+C2C240402D), * EOT=37 * TOTCAM STARTMH LC=OUT 2260 MH INHDR PROCESS INCOMING MSG HEADER CODE FORWAR[...]

712 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 27. The dynamic allocation sample program This chapter suggests ways in which you can customize the dynamic allocation sample application program, used to allocate or deallocate data sets dynamically . It is divided into the following sections: 1. “Overview of the dynamic allocation program” 2. “Installing the program and transaction [...]

v Have read the relevant sections of the MVS/ESA SPL: Application Development Guide and have that manual available for reference while using the sample program, in particular for looking up error and reason codes returned by DYNALLOC. The application uses a 3270 display screen terminal, and adjusts its formatting to suit the screen size. BMS is not[...]

Help feature The program includes a limited “help” feature, driven by the program’s keyword table. In response to “?”, the verb keywords are displayed. In response to “verb?”, all the operand keywords of that verb are displayed. For “verb operand(?)” a short description of the value expected for that operand is displayed. When a c[...]

Maximum and minimum lengths For character and numeric values, the maximum and minimum lengths of the value are checked by the program. For a fixed-length string, these values are the same. The value is still passed to DYNALLOC as specified. Convertible to n byte binary A numeric value is required, of a magnitude representable in binary in the spe[...]

The flow of control when a DYNALLOC request is issued The flow in a normal invocation is as follows. The main program, DFH99M, receives control from CICS and carries out initialization. This includes determining the screen size, allocating input and output buffer sections, and issuing initial messages. It then invokes DFH99GI to get the input com[...]

returned value corresponds to a keyword value, DFH99KR is called to look up the value in the description, and issue the message. Processing of the command is now complete, and the main program is reinitialized for the next one, and loops back to the point where it calls DFH99GI. Messages are issued at many places, using macros. The macro expansion [...]

Part 7. Customizing CICS security processing © Copyright IBM Corp. 1977, 1999 719[...]

General notes The following comments apply to the chapters in Part 7 of this book: v The only aspects of CICS security processing covered are: – Invoking a user-written external security manager – Writing a “good night” transaction. For a comprehensive view of security processing using the Resource Access Control Facility (RACF) product, se[...]

Chapter 28. Invoking a user-written external security manager CICS provides an interface to an external security manager (ESM), which may be user-written or may be the Resource Access Control Facility (RACF) program product. This chapter gives an overview of the CICS-ESM interface, and describes how you can use the MVS router exit to pass control t[...]

The MVS router exit The MVS router provides an optional installation exit that is invoked whether or not RACF is installed and active on the system. If your installation does not use RACF , you can use the router exit to pass control to your own ESM. If you do use RACF , you could use the exit for preprocessing before RACF is invoked. The MVS route[...]

Router exit return codes Y our exit routine must return a return code in register 15. The hexadecimal values of the return code are shown in T able 35. T able 35. MVS router exit return codes Code Meaning 0 The exit has completed successfully . Control proceeds to the RACF front-end routine for further security processing and an invocation of RACF [...]

How ESM exit programs access CICS-related information When CICS invokes the ESM, it passes information about the current CICS environment, for use by an ESM exit program, in an installation data parameter list . How your exit programs access the installation data parameter list depends on whether or not your ESM is RACF . For non-RACF users — the[...]

T able 37. Obtaining the address of the installation data parameter list RACROUTE REQUEST type RACF exit Exit list mapping macro Parameter list field name VERIFY ICHRIX01 ICHRIXP RIXINSTL ICHRIX02 ICHRIXP RIXINSTL AUTH ICHRCX01 ICHRCXP RCXINSTL ICHRCX02 ICHRCXP RCXINSTL F AST AUTH ICHRFX01 ICHRFXP RFXANSTL ICHRFX02 ICHRFXP RFXANSTL LIST ICHRLX01 I[...]

UXPBLKID The name of the block identifier (UXP ARMS). UXPPHASE Address of a 1-byte code that indicates the reason for the call to the ESM (that is, the security event being processed). The code can have one of the following values: DEF AUL T_SIGN_ON (X'01') Signon of default userid PRESET_SIGN_ON (X'02') Signon of preset securi[...]

USER_RESOURCE_CHECK (X'60') Resource checking for user LINK_RESOURCE_CHECK (X'61') Resource checking for link USER_QUER Y_CHECK (X'70') Query checking for user LINK_QUER Y_CHECK (X'71') Query checking for link INITIALIZE_SECURITY (X'80') Initialization of CICS security REBUILD_SECURITY (X'81&ap[...]

RACROUTE REQUEST=VERIFY Issued at operator signon (with the parameter ENVIR=CREA TE), and at sign-off (with the parameter ENVIR=DELETE). This macro creates or destroys an access control environment element (ACEE). It is issued at the following CICS control points: Normal signon through EXEC CICS SIGNON Signon of the default userid DFL TUSER Signon [...]

v After a call to F AST AUTH indicates an access failure that requires logging. v When a QUERY SECURITY request with the RESCLASS option is used. This indicates a request for a resource for which CICS has not built in-storage profiles. (If CICS has in fact built in-storage profiles, REQUEST=AUTH uses them.) RACROUTE REQUEST=LIST Issued to create [...]

APPL The APPLID of the CICS region on which the user is signing on. Which APPLID is passed depends on what is specified as system initialization parameters. INSTLN A pointer to a vector of CICS-related information, which you can map using the DFHXSUXP mapping macro. This pointer is valid only if ESMEXITS=INSTLN is specified as a system initializa[...]

INCLUDE SYSLIB(DFHXSEAI) INCLUDE SYSLIB(DFHEAI) ORDER DFHEAI, verify-program ,DFHEAI0 ENTRY verify-program The DFHEIENT and DFHEIRET macros are inserted by the CICS translator unless you specify *ASM XOPTS(NOPROLOG,NOEPILOG) as the first statement of the program. The DFHEIENT macro assumes that register 15 points to its first executable instructi[...]

732 CICS TS for OS/390: CICS Customization Guide[...]

Chapter 29. Writing a “good night” program Y ou can use the GNTRAN system initialization parameter to specify a “good night” transaction that you want CICS to invoke when a user ’s terminal-timeout period expires. The default value for GNTRAN is 'NO', which means that CICS does not schedule a “good night” transaction, but in[...]

GNTRAN_ST ART_TRANSID The identifier of the transaction that started the “good night” transaction. If it was started by CICS because of a terminal timeout, GNTRAN_ST ART_TRANSID is set to 'CEGN'. Y our program should examine this field to check that timeout processing is appropriate (that is, that the “good night” transaction wa[...]

GNTRAN_PSEUDO_CONV_TRANSID The identifier of the next transaction, if the terminal timed out during a pseudoconversational sequence. (If the terminal did not time out during a pseudoconversational sequence, the value of this field is meaningless.) GNTRAN_SCREEN_LENGTH The length of the screen buffer . GNTRAN_CURSOR_POSITION The cursor position. G[...]

What the sample program does The DFH0GNIT sample program: 1. Checks that it has been invoked for a terminal timeout, by testing the GNTRAN_ST ART_TRANSID field of the communications area passed by CICS. If this contains anything other than 'CEGN', it quits. 2. If a flag within GNTRAN_USER_FIELD shows that this is the first invocation f[...]

v Y our program should always start, like the sample program, by testing the GNTRAN_ST ART_TRANSID field of the communications area passed by CICS. If it finds that the “good night” transaction was started for any reason other than a terminal timeout (for example, by an EXEC CICS ST ART request), timeout processing may not be appropriate. v T[...]

sample good night program 738 CICS TS for OS/390: CICS Customization Guide[...]

Part 8. Examining and modifying resource attributes © Copyright IBM Corp. 1977, 1999 739[...]

A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 8 of this book: v Upon return from any customer-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registe[...]

Chapter 30. User programs for the system definition utility program (DFHCSDUP) This chapter tells you how to write programs for use with the CICS system definition utility program (DFHCSDUP). It is divided into the following sections: 1. “An overview of DFHCSDUP” contains background information. 2. “DFHCSDUP as a batch program” on page 74[...]

DFHCSDUP as a part of the resource definition process is described in the CICS Resource Definition Guide . Guidance information about the execution JCL for DFHCSDUP , and the formats of the DFHCSDUP commands, are given in the CICS Operations and Utilities Guide . DFHCSDUP as a batch program This section refers to DFHCSDUP as a batch program. It d[...]

v The names of all the resource definitions within the specified group v The names of all the groups within the specified list. 2. If you specify the OBJECTS option, all the attributes of the resource definitions are also extracted. USERPROGRAM is the name of the user-written program that is to process the data retrieved by the EXTRACT command.[...]

0 Initial call 2 List start call 4 Group start call 6 Object start call 8 Keyword detail call 10 Object end call 12 Group end call 14 List end call 16 Final call. Workarea Ptr This is the address of a field containing the address of a fullword to be used by the user application to store the address of any user-acquired work area. Back translated c[...]

T able 39. Sample EXTRACT user programs for the DFHCSDUP utility program Program names Languages Description DFH$CRF A DFH0CRFC DFH$CRFP Assembler VS COBOL II PL/I Produces a cross-reference listing of the resource definitions defined in the group or list you specify on the EXTRACT command. DFH$FORA DFH0FORC DFH$FORP Assembler VS COBOL II PL/I Fo[...]

The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) or: EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword. For this program only , in addition to the EXTRACT command, you must define, in a sequent[...]

The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) or: EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword. Note the following points when using DFH0CBDC: v It can deal with only one set of data dur[...]

An assembler-language version The sample job in Figure 107 shows the link-edit statements you need for an assembler-language version of a DFHCSDUP user program. Notes for the assembler job:  1  Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXAI. (See  3  .)  2  The CICS-supplied stub, DF[...]

A VS COBOL II version The sample job in Figure 108 shows the link-edit statements you need for a VS COBOL II version of a DFHCSDUP user program. Notes for the VS COBOL II job:  1  Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXCI. (See  3  .)  2  The CICS-supplied stub, DFHEXCI, is gene[...]

A PL/I version The sample job in Figure 109 shows the link-edit statements you need for a PL/I version of a DFHCSDUP user program. Notes for the PL/I job:  1  Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXPI (see  3  ).  2  The CICS-supplied stub, DFHEXPI, is generated with a link to t[...]

A Language Environment version The sample job in Figure 1 10 shows the link-edit statements you need for a DFHCSDUP user program written in a Language Environment/370 (LE)-conforming high-level language. Notes for the LE job:  1  Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXLE (see  3  ). ?[...]

Notes: 1. In a TSO environment, it is normally possible for the terminal operator to interrupt processing at any time by means of an A TTENTION interrupt. In order to protect the integrity of the CSD file, DFHCSDUP does not respond to such an interrupt until after it has completed the processing associated with the current command. It then writes [...]

The length of the page number data (field ‘bb’ in Figure 1 1 1) must be 0 or 4. The page number , if supplied, must be four numeric EBCDIC characters. The field, if present, is updated upon exit from DFHCSDUP with a number one greater than that of the last page printed. DCBS The addresses of a set of data control blocks for use internally by [...]

v The parameters DCBS and EXITS are aligned on a fullword boundary , and the first four bytes ‘00bb’ contain the binary number of fullwords in the following functional data. v If the ‘bb’ field for any parameter is zero, the parameter is ignored. v If a subentry in the functional data is all binary zeros, it is ignored. v If any subentry [...]

The user exit points in DFHCSDUP There are five user exit points in DFHCSDUP . By specifying the appropriate entry parameters, you can cause DFHCSDUP to pass control to an exit routine at any of these points. None of the user exits supports XPI calls. Parameters passed to the user exit routines The address of a parameter list is passed to the user[...]

The get-command exit The purpose of the get-command exit is to read in command lines. If it is specified, no commands are read from SYSIN. On invocation, your exit routine must supply the address and length of a complete command. It must return control with either the normal return code ‘UERCNORM’ or with the code ‘UERCDONE’, signifying th[...]

The extract exit The extract exit is invoked at various points during processing of the EXTRACT command. The points are listed on page 743. Notes: 1. If you do not specify an EXTRACT user exit routine on the entry linkage to DFHCSDUP , or on the USERPROGRAM keyword, a syntax error occurs. 2. A user exit routine specified on the USERPROGRAM keyword[...]

to the user program” on page 743.) However , when DFHCSDUP is invoked from a user program, the parameter list also includes the standard parameters mentioned under “Parameters passed to the user exit routines” on page 755. Return codes UERCNORM (X'00') Continue processing. UERCERR Irrecoverable error . This causes DFHCSDUP to termin[...]

The put-message exit The put-message exit is invoked whenever a message is to be issued. If you are running under TSO, you could use this exit to terminate DFHCSDUP after the operator inputs an A TTENTION interrupt. (See “Invoking DFHCSDUP from a user program” on page 751.) Or you could use it to provide messages in the operator ’s national l[...]

The termination exit The purpose of the termination exit is to allow you to perform final housekeeping duties. It is invoked before a normal or an abnormal termination of DFHCSDUP . When invoked Invoked once, before termination of DFHCSDUP . Exit-specific parameters UEPTRMFL Address of a 1-byte field that indicates the mode of termination. Its p[...]

Chapter 31. The programmable interface to the RDO transaction, CEDA This chapter describes a programmable interface to the resource definition online (RDO) transaction, CEDA. The functions provided by RDO can be invoked from application programs, by a command such as: EXEC CICS LINK PROGRAM('DFHEDAP') COMMAREA(CEDAPARM) where DFHEDAP is [...]

Notes: 1. An attempt to start CEDA from an application program by an EXEC CICS ST ART command must fail. This is because CEDA ’s first action is to request input from its associated terminal, whereas an automatically initiated transaction must first send data to the terminal. An attempt to start CEDA under CECI by an EXEC CICS ST ART command fa[...]

from a back-end application program whose session is in SEND state (and which has never issued a SYNCPOINT), the session will be put into RECEIVE state. If the code invoked by DFHEDAP then issues a SYNCPOINT , an abend occurs. This can be prevented by all DTP applications issuing a SYNCPOINT request when they get into SEND state (on all of their se[...]

764 CICS TS for OS/390: CICS Customization Guide[...]

Part 9. Appendixes © Copyright IBM Corp. 1977, 1999 765[...]

766 CICS TS for OS/390: CICS Customization Guide[...]

Appendix A. Coding entries in the VT AM LOGON mode table This appendix shows you what to code in your VT AM LOGON mode table for a terminal to be automatically installed. It is divided into the following sections: 1. “Overview” 2. “TYPETERM device types and pointers to related LOGON mode data” on page 768 3. “VT AM MODEENT macro operands?[...]

TYPETERM device types and pointers to related LOGON mode data Search T able 40 for the TYPETERM device type that corresponds to the terminal you want to autoinstall. When you find the right one, use the number to its right to locate, in T able 41 on page 770, what has to be coded on the VT AM MODEENT macros. Note that T able 40 is a complete list [...]

T able 40. TYPETERM device types, with cross-references to VT AM logmode entries (continued) TYPETERM device type Reference number in T able 41 on page 770 DEVICE(3275) TERMMODEL(1) BRACKET(NO) 1 DEVICE(3600) 16, 22, 23 DEVICE(3600) SESSIONTYPE(PIPELINE) * 21 DEVICE(3600) SESSIONTYPE(PIPELN) * 21 DEVICE(3614) * 3 DEVICE(3650) SESSIONTYPE(PIPELINE) [...]

VT AM MODEENT macro operands T able 41 VT AM LOGON mode table entry for each TYPETERM you might define. Y ou should have reached this table by looking up the TYPETERM device types in T able 40 on page 768. Look down the left hand side of the table for the reference number (RN) that brought you here from T able 40 on page 768. When you find it, lo[...]

T able 41. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 5 FMPROF=X'04' TSPROF=X'03' PRIPROT=X'B1' SECPROT=X'90' COMPROT=B'0110.000 00000.00' 6 FMPROF=X'04' TSPROF=X'04&[...]

T able 41. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 13 FMPROF=X'03' TSPROF=X'03' PRIPROT=X'B1' SECPROT=X'B0' COMPROT=B'0011.000 10000.00' PSERVIC=X'01' SCS3790 See note [...]

T able 41. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 18 FMPROF=X'03' TSPROF=X'03' PRIPROT=X'B1' SECPROT=B'10..0000' COMPROT=B'0011.000 10000.00' PSERVIC=B'00000010 10000000 00[...]

T able 41. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 23 FMPROF=X'04' TSPROF=X'04' PRIPROT=X'B1' SECPROT=X'B0' COMPROT=B'0111.000 00000.00' 24 TYPE=X'00' FMPROF=X'13&[...]

PSER VIC screen size values for LUTYPEx devices T able 42 is to help you decide what screen size values you should specify on the PSERVIC operand of the VT AM MODEENT macro, for LUTYPE0, LUTYPE2, and LUTYPE3 devices. If, on your CICS TYPETERM definition, you code the values shown in columns 1 through 4 of T able 42, the screen size values in the C[...]

T able 43. Equivalent PSER VIC screen size values Bytes 20—24 of CICS model bind V alid screen size values on PSERVIC definition 0000 0000 01 0000 0000 00 0000 0000 01 0C28 0000 7E 0000 0000 02 0000 0000 00 0000 0000 02 1850 0000 7E 0000 0000 03 0000 0000 00 0000 0000 03 1850 0000 03 xxxx 0000 7E Plus, if xxxx=1850 0000 0000 00 xxxx 0000 7E 0000[...]

AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3278 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3278 GROUP ==> PDATD DEVICE ==> 3270 TERMMODEL ==> 2 LIGHTPEN ==> YES AUDIBLEALARM ==> YES UCTRAN ==> YES IOAREALEN ==> 2000,2000 ERRLASTLINE ==> YES ERRINTENSIFY ==> YES US[...]

LOGONMSG ==> YES DISCREQ ==> YES RECEIVESIZE ==> 256 BUILDCHAIN ==> YES BIND SENT BY CICS : 010303B1 B0308000 0085C780 00028000 00000018 5018507F 00000000 00000000 ****************************************************************** 3) 3770 BATCH LU (3777) ****************************************************************** BATCH MODEENT LO[...]

TERMINAL definition ************************* AUTINSTNAME ==> M6670 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T6670 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T6670 GROUP ==> PDATD DEVICE ==> LUTYPE4 BUILDCHAIN ==> YES DISCREQ ==> YES RECEIVESIZE ==> 256 UCTRAN ==> YES I[...]

PRIPROT=X'B1', SECPROT=X'B0', RUSIZES=X'8585', COMPROT=X'7080' TERMINAL definition ************************* AUTINSTNAME ==> M3790A AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3790A INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3790A GROUP ==> PDATD[...]

BIND SENT BY CICS : 010304B1 B0708000 00858580 00013118 40000092 0000E100 50000000 00000000 ****************************************************************** 7) 3790 SCSPRT ****************************************************************** S3790C MODEENT LOGMODE=S3790C, 3790 WITH SCS TYPE=1, FMPROF=X'03', TSPROF=X'03', PRIPROT=[...]

ATI ==> YES TTI ==> YES BRACKET ==> YES RECEIVESIZE ==> 256 SENDSIZE ==> 256 BIND SENT BY CICS : 010303B1 90308000 00000080 00010000 ****************************************************************** 9) 3650 INTERPRETER LU (SESTYPE = USERPROG BRACKET = YES) ****************************************************************** S3650A MOD[...]

SESSIONTYPE ==> 3270 RELREQ ==> YES DISCREQ ==> YES IOAREALEN ==> 256 BRACKET ==> YES RECEIVESIZE ==> 240 ATI ==> NO TTI ==> YES BIND SENT BY CICS : 010403B1 90600000 00000080 00000000 ****************************************************************** 11) 3650 HOST CONVERSATIONAL (3653) LU (N.B. LOGMODE SAME AS HC (3270) LU)[...]

DEVICE ==> 3650 SESSIONTYPE ==> USERPROG BRACKET ==> NO RELREQ ==> NO DISCREQ ==> NO RECEIVESIZE ==> 256 IOAREALEN ==> 256 ATI ==> YES TTI ==> YES BIND SENT BY CICS : 01040430 30400000 00000080 00000000 ****************************************************************** 13) 8815 SCANMASTER (APPC SINGLE SESSION) ***********[...]

AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3290 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3290 GROUP ==> PDATD DEVICE ==> LUTYPE2 TERMMODEL ==> 2 ALTSCREEN ==> 62,160 DEFSCREEN ==> 24,80 AUDIBLEALARM ==> YES UCTRAN ==> YES IOAREALEN ==> 2000,2000 ERRLASTLINE ==> [...]

LDC=(DS=1), DVC=3604, PGESIZE=(6,40), PGESTAT=PAGE DFHTCT TYPE=LDC,LDC=SYSTEM BIND SENT BY CICS : 010404B1 B0700000 00000080 00000000 LOGON mode definitions for CICS-supplied autoinstall models This section contains VT AM LOGON mode table definitions that match the CICS-supplied TYPETERM and model TERMINAL definitions for autoinstall. The first[...]

DFHLU2 MODEENT LOGMODE=DFHLU2, SNA LUTYPE2 3270 TYPE=1, FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'B0', COMPROT=X'3080', RUSIZES=X'85C7', PSERVIC=X'028000000000000000000300' The following entries are those LOGMODE definitions supplied by VT AM that match CICS-supplied [...]

DFHLU2E3 MODEENT LOGMODE=SNX32703, LU2 model 3 queryable FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'90', COMPROT=X'3080', RUSIZES=X'87F8', PSERVIC=X'028000000000185020507F00' DFHLU2E4 MODEENT LOGMODE=SNX32704, LU2 model 4 queryable FMPROF=X'03', TSPROF=X'[...]

Appendix B. Default actions of the node abnormal condition program This appendix describes the default actions of the node abnormal condition program, DFHZNAC. The actions vary , depending on the terminal error code and system sense codes received from VT AM. In most cases, DFHZNAC issues messages and sets one or more “action flags” in the com[...]

T able 44. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'1E' TCZSRCV2 DFHZC2408 2391 01 12 4 X'20' TCZVT AMI DFHZC2417 None X'21' TCZLUCF1 DFHZC4902 3 9 10 1 1 24 X'22' TCZLUCF2 DFHZC4903 3 9 10 1 1 24 X'23' TCZF[...]

T able 44. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'48' TCZOPSIN DFHZC3461 None X'49' TCZCLSIN DFHZC3462 None X'4A' TCZOP ACB DFHZC3463 None X'4B' TCZICPUT DFHZC2498 None X'4C' TCZDSPCL DFHZC3481 2391 01 12 [...]

T able 44. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'74' TCZSDSE5 DFHZC2423 3 9 10 1 1 24 X'75' TCZSESE1 DFHZC2424 3 9 10 1 1 15 24 X'76' TCZLGNA DFHZC2487 3 X'77' TCZDMRY DFHZC2488 None X'78' TCZSDRE2 DFHZC2[...]

T able 44. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'A7' TCZBOEB DFHZC2449 2 3 1 1 18 22 24 X'A8' TCZFMHLE DFHZC2471 2341 01 12 22 4 X'A9' TCZRACRF DFHZC2472 1 1 X'AA' TCZSDSE9 DFHZC2473 3 9 1 1 X'AB' TCZLUER[...]

T able 44. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'D3' TCZDMPD DFHZC2463 None X'D4' TCZCXRR DFHZC2453 12391 0 X'D5' TCZCXE2 DFHZC2452 3 9 10 1 1 18 24 X'D6' TCZSXC2 DFHZC2441 None X'D7' TCZSXC1 DFHZC2440 No[...]

Notes: 1. See message DFHZC2497 or DFHZC3493, depending on the device type. 2. “Good morning” message to be sent. 3. Cancel task, and close VT AM session owing to quick close or abend. CICS messages associated with VT AM errors T able 45. CICS messages associated with VT AM errors Message Symbolic label Error code Action flags set DFHZC0101 TC[...]

T able 45. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC2418 TCZSEXUC X'BB' 2391 01 12 32 4 DFHZC2419 TCZSSXUC X'82' 2391 01 12 32 4 DFHZC2420 TCZSAXUC X'B5' 2391 01 12 32 4 DFHZC2421 TCZUNCMD X'60' 2391 01 12 4 DFHZC2422 TCZLGCER X'90&ap[...]

T able 45. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC2458 TCZPXE2 X'DD' None DFHZC2459 TCZSDSE7 X'99' 3 9 1 1 DFHZC2463 TCZDMPD X'D3' None DFHZC2467 TCZLEXCI X'88' 2391 01 12 32 4 DFHZC2468 TCZLEXUS X'89' 2391 01 12 4 DFHZC2469 TC[...]

T able 45. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC3441 TCZVT AMO X'63' None DFHZC3442 TCZVT AMK X'67' None DFHZC3443 TCZVT AMA X'64' None DFHZC3444 TCZTIOAE X'6A' 12391 01 12 4 DFHZC3452 TCZSIGR X'66' None DFHZC3454 TCZBRUAC X&[...]

T able 45. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC4903 TCZLUCF2 X'22' 3 9 10 1 1 24 DFHZC4904 TCZFSMBE X'23' 3 10 1 1 9 24 DFHZC4905 TCZFSMCS X'24' 3 10 1 1 9 24 DFHZC4906 TCZFSMCR X'25' 3 10 1 1 9 24 DFHZC4907 TCZSDLER X'26' 3[...]

T able 45. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC4946 TCZINV A T X'F9' 2 3 24 DFHZC4947 TCZLUSEC X'F A' 2 3 24 DFHZC4949 TCZRABUS X'7D' 2391 01 12 4 DFHZC6590 TCZXRST X'3F' None DFHZC6591 TCZXERR X'3E' 9 10 1 1 15 24 DFHZC6593[...]

T able 46. Messages issued and flags set by DFHZNAC for specific sense codes (continued) Sense code Message Action flags set X'0829' DFHZC3407 1, 2, 3, 10, 1 1, 24 X'082A' None 4 9 X'082B' DFHZC3408 2, 3, 10, 1 1, 13 X'082D' DFHZC3413 None X'082E' DFHZC3412 None X'082F' DFHZC3414 2, 3, [...]

3. Action flags 2 and 3 are set for negative response received for a SEND that requested a definite response. 4. Presentation space error . 5. Presentation error on read. Display buffer alteration, due to operator intervention, detected on a READ command to a compatibility-mode logical unit. 6. Function abend received from a device. A negative re[...]

Appendix C. T ransient data write-to-terminal program (DFH$TDWT) DFH$TDWT is a sample program that sends transient data messages to a terminal or printer . Y ou can use it to send messages from a single transient data queue, or from several queues, to one terminal. In the definition for the transient data queue, you can specify that particular cat[...]

804 CICS TS for OS/390: CICS Customization Guide[...]

Appendix D. Uppercase translation This appendix describes how to translate lower- and mixed-case characters to uppercase. “Uppercase translation of national characters” describes how to translate national characters that CICS cannot handle by standard means. “TS data sharing messages” on page 806 describes how to translate operator messages[...]

If you use this method, you must reassemble your modified copy of DFHTCTDY , keeping the 'DY' suff ix. The 'DY' suff ix is necessary because, even if you use RDO for all your terminals and have TCT=NO specified in your SIT or its overrides, CICS uses DFHTCTDY by default to create control blocks for RDO-defined and autoinstall[...]

Appendix E. The example program for the XTSEREQ global user exit, DFH$XTSE This appendix lists the example global user exit program, DFH$XTSE. The example shows you how to: v Use EXEC CICS commands in a global user exit program v Use EXEC CICS commands and XPI calls in the same exit program v Modify the command parameter list in EXEC interface exit[...]

* * * It is not safe to use the following storage: * * Program storage (DFHEISTG) since this is freed as soon * * as the exit program returns control to CICS. * * * * 2) When adding or removing a field in the command parameter list, * * you must remember: * * a) To set/clear the field's existence bit in the EID * * b) To set/clear the appropri[...]

*---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries. Each entry * * can be mapped by the TABLE_ENTRY DSECT * *---------------------------------------------------------------------* TABLE_ENTRY DSECT ENTRY_NAME DS CL8 NEW_NAME DS CL8 NEW_SYSID DS CL4 ENTRY_ACTION DS XL1 FILLER[...]

* Registers: * * R1 = UEPAR plist (set on entry) * * = Work register * * R2 = UEPAR plist * * R3 = Program base register (set by DFHEIENT) * * R6 = Linkage register * * R11= EIB register * * R13= EISTG register (set by DFHEIENT) * * R15= Work register * * User Exit Return Code * * * * Logic: * * DFH$XTSE: * * Exec Interface Entry * * Address DFHUEP[...]

*=====================================================================* * TS_REQUEST - Invoked at XTSEREQ exit point * * Determine the TS Queue Name and scan the TS_Routing_Table for * * a match. If an entry exists in the table, then check the action * * field and call the ROUTE_REQUEST or LOCAL_REQUEST routines. * * * * The TS_Routing_Table is mad[...]

*=====================================================================* TS_REQUEST DS 0H * Check for possible recursion L R1,UEPRECUR Address of recursive count LH R1,0(R1) Fetch count LTR R1,R1 Has exit been invoked recursively? BNZ ERROR2 ..Yes Branch to error routine * * Extract pointer to the EID and TS queue name from CLPS L R8,UEPCLPS Fetch a[...]

*=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point * * Free any shared storage that was acquired during previous * * invocation at XTSEREQ. * * * * Registers: * * R1 = Work register * * R6 = Linkage register * * R8 = Command Parameter List (CLPS) * * * * Logic: * * TS_Reque[...]

*=====================================================================* * LOCAL_REQUEST: Process Local TS Queues * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. If required, rename the TS Queue Name, but do not * * modify the SYSID. * * * * Registers: * * R1 = Work register * * R6 = Link Register * * R7 = Address of [...]

*=====================================================================* * ROUTE_REQUEST: Ship request to remote system * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. The request is modified by adding a SYSID to the * * command and renaming the queue if required. * * * * Registers: * * R1 = Work register * * R6 = Lin[...]

* Update the Sysid in CLPS ROUTE1 DS 0H MVC SHARED_SYSID,NEW_SYSID Copy SYSID into shared storage L R8,UEPCLPS Address the CLPS.. USING TS_ADDR_LIST,R8 ..with Register 8 L R1,TS_ADDR0 Address the EID.. USING TS_EID,R1 ..with Register 1 OI TS_BITS1,TS_SYSID_V Indicate SYSID now present in CLPS DROP R1 Drop addressability to EID LA R1,SHARED_SYSID Fe[...]

* Logic: * * Entry_Not_Found: * * Call Getmain_Shared * * Copy default_sysid into shared storage * * Address the command plist * * Update ADDR7 to point to the address of the default SYSID * * Set the SYSID existence bit in the EID * * Set the Hi-order bit in last address in CLPS * * Return * *=======================================================[...]

*=====================================================================* * GETMAIN_SHARED - Obtain Shared storage * * * * Registers: * * R0 = Used by EXEC CICS call * * R1 = Used by EXEC CICS call * * Work Register * * R6 = Link Register - Return Address * * R11= EIB register (set on entry) * * R12= Work register * * R14= Used by EXEC CICS call * * [...]

*=====================================================================* * FREEMAIN_SHARED - Free shared storage * * Free the shared storage associated with this command. * * Registers: * * R0 = Used by EXEC CICS call * * R1 = Used by EXEC CICS call * * R6 = Link Register - Return Address * * R11= EIB register (set on entry) * * R12= Work register *[...]

USING DFHTRPT_ARG,R1 TRACE_ENTRY DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ENTRY) B ISSUE_TRACE TRACE_EXIT DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_EXIT) B ISSUE_TRACE TRACE_ERROR DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ERROR), X DATA1(TR_ERROR_N,1) BAL R6,ISS[...]

ERROR4 DS 0H MVI TR_ERROR_N,4 B TRACE_ERROR ERROR5 DS 0H MVI TR_ERROR_N,5 B TRACE_ERROR ERROR6 DS 0H MVI TR_ERROR_N,6 B TRACE_ERROR ERROR7 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR ERROR8 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR ERROR9 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR EJECT , DROP R2 Drop DFHUEPAR DROP R11 Drop EIB LTORG , ******************************[...]

TS_ROUTING_TABLE DS 0D ENTRY_NAME_1 DC CL8'AAAAAAAA' Rename Queue AAAAAAAA as NEW_NAME_1 DC CL8'BBBBBBBB' BBBBBBBBB QOR_SYSID_1 DC CL4' ' ACTION_1 DC XL1'01' Local request FILLER_1 DC CL3' ' ENTRY_NAME_2 DC CL8'A1 ' Rename Queue A1 as NEW_NAME_2 DC CL8'B1 ' B1 QOR_SYSID_2 DC CL4&[...]

Index Special Characters “good night” transaction customizing the sample program 736 overview 733 sample program, DFH0GNIT 735 Numerics 3270 bridge bridge exit 599 bridge exit program 599 3270 information display system error processors (optional) 468 TCAM 706 unavailable printer DFHZNEP 476 A abends abend and restart, TCAM 707 transaction bit [...]

automatic installation of terminals control program action at delete 495 action at install 487 action on return 494 information returned to CICS 491 link-edit statements 405 naming 496 testing and debugging 496 parameter list at logon 488 the sample programs customizing 499 DFHZA TDX 497 DFHZCTDX 497 DFHZDTDX 497 DFHZPTDX 497 VT AM LOGON mode table[...]

DBCTL (database control) (continued) DFHDBUEX 622 DFHMCT TYPE=EMP entries 661 in an XRF environment 623 interface status 595 DBLID values 620 DD card correlation TCAM 694 DECB, terminal error program information 425 operand 425 DEF AUL T operand DFHZNEPI TYPE=INITIAL 479 default threshold count limits DFHTEP (terminal error program) 434 DEFINE PROG[...]

DFHPGADX, user-replaceable autoinstall program (continued) introduction to 546 parameter list at install 543 sample program 546 supplied definition of 547 use of model definitions 540 when invoked 539 DFHPGAQX macro 334 DFHPGISX macro 334 DFHREST , transaction restart program communications area 412 default program 414 introduction 41 1 link-edit[...]

DFHZNEP , user-replaceable node error program 449 DFHZNEPI macros TYPE=ENTRY 479 TYPE=FINAL 479 TYPE=INITIAL 479 dictionary data section, CICS monitoring records 666, 672 disabling journals 631 dispatcher functions of the XPI 300 display function of the overseer program 610 distributed program link (DPL) dynamic routing of requests changing the pro[...]

dynamic routing program (DFHDYP) (continued) UOW considerations 553, 562 when invoked 550, 558 dynamic transactions 550 E EDF (Execution Diagnostic Facility) with global user exits 6 with task-related user exits 252 EMP (event-monitoring point) 658 END_BROWSE_PROGRAM function of the XPI 349 ENQUEUE 318 enqueue domain functions of the XPI 318 error [...]

global user exits (continued) in DBCTL interface control program 19 in DBCTL tracking program 40 in dispatcher domain 42 in DL/I interface program 44 in dump domain 49 in enqueue EXEC interface program 57 in EXEC interface program 65 in file control EXEC interface program 70, 83 in file control file state program 96 in file control open/close p[...]

INQUIRE_TRANDEF function of the XPI 375 INQUIRE_TRANSACTION function of the XPI 383 interactive logical unit error processor 469 intersystem queues controlling the length of using the XISCONA global user exit 127 using the XZIQUE global user exit 237 INTLU error processor 469 ISSUE P ASS command 464 ISTINCLM entries for automatic installation 770 J[...]

N NAME operand DFHSNEP TYPE=INITIAL 470 DFHSNET macro 473 national characters uppercase translation 805 NEB (node error block) 474 NEBNAME operand DFHSNET macro 473 NEBS operand DFHSNET macro 473 NEP (node error program) 3270 unavailable printer 476 ACF/VT AM error handling background 450 application routing failure 464 common subroutine vector tab[...]

node error program (NEP) (continued) DFHZNAC logging facility 476 DFHZNEP 450, 457 DFHZNEPI interface module 478 DFHZNEPI macros 478 DFHZNEPI TYPE=INITIAL 479 DSECT s 474 error groups 452 error status blocks 474 error table header 474 in an XRF environment 480 changing the recovery message 482 changing the recovery notification 481 changing the re[...]

PL TSD programs (continued) general considerations 395 introduction 394 second phase 395 POOL feature, TCAM 701 pool of common TCTTEs 696 PRINT operand DFHTEPM TYPE=INITIAL 428 processing output from CICS statistics 688 program error program (PEP) communication area for assembler-language programs 409 link-edit statements 404 source code 409 writin[...]

SETEOM macro 694 shipped terminals, automatic installation of 523 shutdown (PL TSD) programs considerations when writing 394 shutdown assist program, DFHCESD 396 shutdown assist transaction 396 SMF (system management facility) 662 header 654, 663, 683 product section 654, 683 SNA character string (SCS) 692 specifying processing at EMPs MCT entries [...]

task-related user exits 280 (continued) schedule flag word 280 SPI parameters 257 stub program 249, 250 ename 251 statname 251 syncpoint manager calls 270 backing out changes 274 committing changes 274 restart resynchronization 274 sample pseudocode 272 syncpoint manager parameters 258 table entries 280 task manager calls 274 limitations 275 task [...]

TEP (terminal error program) (continued) system count (TCTTENI) 416 user field a (PCISA VE) 445 user field b (PCICNT) 445 DFHTEP tables 432 DFHTEPM TYPE=ENTRY 429 DFHTEPM TYPE=EXIT 430 DFHTEPT TYPE=PERMCODE|ERRCODE 433 error processor source 429 error table 418 errors and actions unique to TCAM 699 generating 425 job control for sample DFHTEP gen[...]

termination, TCAM 708 TIE_UP_RECORD_DA T A section, journal records 642 TIME operand DFHSNET macro 474 of DFHTEPT TYPE=PERMCODE|ERRCODE macro 434 TPROCESS block 694 trace control functions of the XPI 369 TRACE_PUT function of the XPI 369 trace table entries, global user exit interface 7 transaction abends program error program (PEP) 407 transaction[...]

XFCAREQC, global user exit (continued) parameter list and return codes 83 XFCBF AIL, global user exit 1 12 XFCBOUT , global user exit 1 17 XFCBOVER, global user exit 1 19 XFCF AIL, global user exit DFH$FCBF sample program 1 16 XFCLDEL, global user exit 122 XFCNREC, global user exit description 105 parameter list and return codes 106 XFCQUIS, global[...]

XPI (exit programming interface) (continued) GETMAIN 302 INQUIRE_ACCESS 364 INQUIRE_ELEMENT_LENGTH 365 INQUIRE_SHORT_ON_ST ORAGE 366 INQUIRE_T ASK_STORAGE 367 SWITCH_SUBSP ACE 368 trace control function TRACE_PUT 369 transaction management functions INQUIRE_CONTEXT 370 INQUIRE_DTRTRAN 371 INQUIRE_MXT 372 INQUIRE_TCLASS 374 INQUIRE_TRANDEF 375 INQUI[...]

840 CICS TS for OS/390: CICS Customization Guide[...]

Sending your comments to IBM If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy , organization, subject matter , or completeness of this book. Please limit your comments to t[...]

IBMR Program Number: 5655-147 Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber . SC33-1683-02[...]

Spine information: IBM CI CS TS f o r OS /3 9 0 CI CS C ust o mizati o n G ui d e Re lease 3[...]