Instruction/ maintenance manual of the product SC33-1683-02 IBM
Go to page of 875
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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.
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.
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 Enviro.
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.
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.
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.
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 .
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 , GC2.
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.
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.
- 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.
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.
– 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 .
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.
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.
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.
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.
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.
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-re.
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 .
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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 .
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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’.
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.
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.
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.
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.
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.
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.
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.
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.
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_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.
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.
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.
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 Modify.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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).
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.
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.
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).
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.
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.
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.
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.
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.
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.
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,.
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.
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.
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.
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 .
“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.
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.
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.
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).
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.
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 .
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 ex.
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.
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.
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 .
‘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’.
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-b.
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.
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'.
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.
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).
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.
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 .
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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_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 .
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 .
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.
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 p.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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 sess.
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.
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.
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.
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 exampl.
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).
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 .
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_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.
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.
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.
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 cre.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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 * .
Example program CICS supplies—in hardcopy only—an example program, DFH$XTSE, that shows how temporary storage requests can be modified. See “Appendix E.
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.
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.
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.
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.
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).
‘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.
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.
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.
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.
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.
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.
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.
*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,UEPICRT.
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).
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.
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.
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.
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.
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.
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’.
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.
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.
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 .
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.
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 .
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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’.
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.
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.
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.
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.
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.
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 .
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 .
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+.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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 com.
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.
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 co.
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.
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.
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 DFHUERT.
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.
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.
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.
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.
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.
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 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.
– 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: .
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 .
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), .
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.
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’.
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 .
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.
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).
TITLE 'GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI' ************************************************************************* * The first three instructions set up the global user exit * * en.
************************************************************************* * The next seven instructions form the normal start of a global user * * exit program, setting the program addressing mode to .
************************************************************************* * 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.
************************************************************************* * Test SMMC_RESPONSE -- if OK, then branch round error handling. * ************************************************************************* * * CLI SMMC_RESPONSE,SMMC_OK CHECK RESPONSE AND.
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.
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).
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.
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).
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.
ADD_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(ADD_SUSPEND), [RESOURCE_NAME(name16 | string | 'string'),] [RESOURCE_TYPE(name8 | string | 'string'),]] [OUT, SUSPEND_TOKEN(name.
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.
(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.
"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.
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.
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(nam.
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.
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 |.
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 PURGEABL.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
DEFINE_PROGRAM DFHLDLDX [CALL,] [CLEAR,] [IN, FUNCTION(DEFINE_PROGRAM), PROGRAM_NAME(name8 | string | 'string' ), [EXECUTION_KEY(CICS|USER),] [PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRAN.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 RE.
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.
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.
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.
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.
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.
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.
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.
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 KERNERRO.
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.
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.
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 .
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.
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_NO.
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.
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.
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.
The INQUIRE_AUTOINST ALL call INQUIRE_AUTOINST ALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets.
SET_AUTOINST ALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_AUTOINSTALL), [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] [LANGUAGES_AV.
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.
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.
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 A.
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, .
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.
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.
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.
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.
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.
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.
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), S.
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.
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.
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.
INQUIRE_ELEMENT_LENGTH DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION (INQUIRE_ELEMENT_LENGTH), ADDRESS (name4 | (Rn) | *),] [OUT, ELEMENT_ADDRESS(name4 | (Rn) | *), ELEMENT_LENGTH(name4 | (Rn) | *), RESPONS.
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.
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.
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.
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').
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.
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.
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 .
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).
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.
INQUIRE_TRANDEF DFHXMXDX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TRANDEF), INQ_TRANSACTION_ID(name4 | string | ‘ string ’ ),] [OUT, [BREXIT(name8),] [CMDSEC(name1),] [DTIMEOUT(name4 | (Rn)),] [DUMP.
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.
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.
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.
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.
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.
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.
(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.
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 RESTAR.
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 .
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.
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.
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.
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 | 's.
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.
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).
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) RE.
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.
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 .
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.
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.
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 .
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.
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 .
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.
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.
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 .
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 ’.
DFHEISTG DSECT , * * Insert your own storage definitions here * DFHPCOM TYPE=DSECT *********************************************************************** ***** PROGRAM ERROR ***** ***** PROGRAM *****.
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.
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.
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.
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.
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.
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 .
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 t.
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.
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.
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.
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.
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.
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.
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 .
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 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.
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 .
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.
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 .
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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 .
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 .
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.
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 .
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 I.
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.
DFHTEP recursive retry routine *ASM XOPTS(NOPROLOG NOEPILOG SP) ************************************************************************ * * * DFHTEP RECURSIVE RETRY ROUTINE * * * ********************.
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.
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.
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).
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 .
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.
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 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.
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 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.
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.
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 .
********************************************************************** ** Header ** ** These fields are READ ONLY ** ********************************************************************** NEPCAHDR DS .
********************************************************************** ** VTAM information - Any VTAM sense and RPL codes ** ** These fields are READ ONLY ** ******************************************.
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.
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.
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.
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.
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 .
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.
Routing mechanism The routing mechanism invokes the appropriate error processor depending on the error code provided by the node abnormal condition program.
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.
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'.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 notificatio.
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.
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.
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 .
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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(3.
/* 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.
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 .
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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).
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 .
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.
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.
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(.
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 .
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 clash.
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.
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.
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 .
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.
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).
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 .
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.
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.
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 .
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').
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 &.
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').
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.
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 .
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
which transactions are to be routed. For information about defining remote transactions for dynamic transaction routing, see the CICS Intercommunication Guide .
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.
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.
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.
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 .
– 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.
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.
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.
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.
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.
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 DY.
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 .
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.
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’.
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.
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.
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.
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’.
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): – I.
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.
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.
Chapter 17. Writing a distributed routing program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5.
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.
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.
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 .
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.
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 .
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.
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.
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.
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.
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.
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 .
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 .
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.
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.
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.
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.
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.
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 .
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 Custom.
Chapter 18. Writing a CICS–DBCTL interface status program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5.
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.
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.
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.
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.
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 .
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.
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.
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).
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).
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.
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 .
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.
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.
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.
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.
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.
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.
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 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.
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 .
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.
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.
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 .
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.
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 req.
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 re.
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.
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 .
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.
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.
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.
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.
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 .
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 .
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.
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 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 re.
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.
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.
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.
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 F.
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.
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.
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.
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.
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.
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.
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.
*********************************************************************** ** FUNCTION IDENTIFIERS ** *********************************************************************** * * * X'20' PLUS X'8-' ...USE FOR AUTOMATIC JOURNALING * * X'40' PLUS X'8-' .
*********************************************************************** * 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' .
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.
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.
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.
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.
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.
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.
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’.
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.
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.
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.
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.
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.
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.
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&a.
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&apo.
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&apos.
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'03.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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 .
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.
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.
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 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.
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 .
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 alway.
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.
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.
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.
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.
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 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.
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.
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.
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 .
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.
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 o.
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.
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.
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.
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.
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.
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.
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.
CICS and TCAM: program interrelationship Figure 104 illustrates the interrelationship between the TCAM message control program (MCP) and the TCAM application program.
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.
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+C1C.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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 .
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 IC.
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).
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 .
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).
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.
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.
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.
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.
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'.
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 .
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.
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.
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 alway.
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.
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 .
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.
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.
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.
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.
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.
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.
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 ).
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.
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.
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.
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.
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.
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.
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.
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.
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.
Chapter 31. The programmable interface to the RDO transaction, CEDA This chapter describes a programmable interface to the resource definition online (RDO) transaction, CEDA.
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.
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.
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.
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.
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 DEVI.
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.
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.
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.
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.
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.
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.
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 000.
AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3278 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3278 GROUP ==> PDATD DEVICE ==> 3270 TERMMOD.
LOGONMSG ==> YES DISCREQ ==> YES RECEIVESIZE ==> 256 BUILDCHAIN ==> YES BIND SENT BY CICS : 010303B1 B0308000 0085C780 00028000 00000018 5018507F 00000000 00000000 ************************.
TERMINAL definition ************************* AUTINSTNAME ==> M6670 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T6670 INSERVICE ==> YES TYPETERM definition **********************.
PRIPROT=X'B1', SECPROT=X'B0', RUSIZES=X'8585', COMPROT=X'7080' TERMINAL definition ************************* AUTINSTNAME ==> M3790A AUTINSTMODEL ==> ONLY .
BIND SENT BY CICS : 010304B1 B0708000 00858580 00013118 40000092 0000E100 50000000 00000000 ****************************************************************** 7) 3790 SCSPRT **************************.
ATI ==> YES TTI ==> YES BRACKET ==> YES RECEIVESIZE ==> 256 SENDSIZE ==> 256 BIND SENT BY CICS : 010303B1 90308000 00000080 00010000 ****************************************************.
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.
DEVICE ==> 3650 SESSIONTYPE ==> USERPROG BRACKET ==> NO RELREQ ==> NO DISCREQ ==> NO RECEIVESIZE ==> 256 IOAREALEN ==> 256 ATI ==> YES TTI ==> YES BIND SENT BY CICS : 010404.
AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3290 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3290 GROUP ==> PDATD DEVICE ==> LUTYPE2 TERM.
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.
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.
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'87F.
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.
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.
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' T.
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'7.
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&apos.
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' TC.
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.
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&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 .
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 .
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&apos.
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 .
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 .
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.
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.
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.
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 term.
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.
* * * 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.
*---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries. Each entry * * can be mapped by the TABLE_ENTRY DSECT * *----------------.
* 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= EIST.
*=====================================================================* * 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.
*=====================================================================* 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 .
*=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point * * Free any shared storage that was acquired during previous * * invocation at XTSEREQ.
*=====================================================================* * 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.
*=====================================================================* * 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.
* 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 .
* 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.
*=====================================================================* * GETMAIN_SHARED - Obtain Shared storage * * * * Registers: * * R0 = Used by EXEC CICS call * * R1 = Used by EXEC CICS call * * .
*=====================================================================* * FREEMAIN_SHARED - Free shared storage * * Free the shared storage associated with this command.
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.
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_ERRO.
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' Lo.
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 inf.
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 deb.
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 .
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 5.
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 dispat.
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.
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 progra.
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 u.
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 (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.
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 .
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 (s.
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 2.
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=.
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 .
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 DF.
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 functi.
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.
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.
An important point after buying a device IBM SC33-1683-02 (or even before the purchase) is to read its user manual. We should do this for several simple reasons:
If you have not bought IBM SC33-1683-02 yet, this is a good time to familiarize yourself with the basic data on the product. First of all view first pages of the manual, you can find above. You should find there the most important technical data IBM SC33-1683-02 - thus you can check whether the hardware meets your expectations. When delving into next pages of the user manual, IBM SC33-1683-02 you will learn all the available features of the product, as well as information on its operation. The information that you get IBM SC33-1683-02 will certainly help you make a decision on the purchase.
If you already are a holder of IBM SC33-1683-02, but have not read the manual yet, you should do it for the reasons described above. You will learn then if you properly used the available features, and whether you have not made any mistakes, which can shorten the lifetime IBM SC33-1683-02.
However, one of the most important roles played by the user manual is to help in solving problems with IBM SC33-1683-02. Almost always you will find there Troubleshooting, which are the most frequently occurring failures and malfunctions of the device IBM SC33-1683-02 along with tips on how to solve them. Even if you fail to solve the problem, the manual will show you a further procedure – contact to the customer service center or the nearest service center
