CICS® Transaction Server for OS/390® IBM CICS Customization Guide Release 3 SC33-1683-02
CICS® Transaction Server for OS/390® IBM CICS Customization Guide Release 3 SC33-1683-02
Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page xvii. Third edition (March 1999) This edition applies to Release 3 of CICS Transaction Server for OS/390, program number 5655-147, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.
Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Programming interface information . . . . . . . . . . . . . . . . . xviii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xix Preface . . . . . . . . . . . . . . . . What this book is about . . . . . . . . . . Who this book is for. . . . . . . . . . . . What you need to know to understand this book . How to use this book . . . . . . . . . . . Notes on terminology . . . . . . . . . . .
Exit XBMIN . . . . . . . . . . . . . . . . . . . . . . . Exit XBMOUT . . . . . . . . . . . . . . . . . . . . . . The field element table structure . . . . . . . . . . . . . . . Programming the XBMIN exit . . . . . . . . . . . . . . . . Programming the XBMOUT exit . . . . . . . . . . . . . . . Bridge facility exit . . . . . . . . . . . . . . . . . . . . . Exit XFAINTU . . . . . . . . . . . . . . . . . . . . . . Data tables management exits XDTRD, XDTAD, and XDTLC . . . . . Exit XDTRD . . . . . . . . . . . .
Modifying user arguments . . . . . . . . . . . . . . . . . . File control file state program exits XFCSREQ and XFCSREQC . . . . . Exit XFCSREQ . . . . . . . . . . . . . . . . . . . . . . Exit XFCSREQC . . . . . . . . . . . . . . . . . . . . . . File control open/close program exit XFCNREC . . . . . . . . . . . Exit XFCNREC . . . . . . . . . . . . . . . . . . . . . . File control quiesce receive exit, XFCVSDS . . . . . . . . . . . . . Exit XFCVSDS . . . . . . . . . . . . . . . . . . . . . .
Exit XSTOUT . . . . . . . . . . . . . . . . . . . . . . . System recovery program exit XSRAB . . . . . . . . . . . . . . . Exit XSRAB. . . . . . . . . . . . . . . . . . . . . . . . System termination program exit XSTERM . . . . . . . . . . . . . Exit XSTERM . . . . . . . . . . . . . . . . . . . . . . . Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT . . . . . . . . . . . . . . . . . . . . . . . . Exit XTSQRIN . . . . . . . . . . . . . . . . . . . . . . . Exit XTSQROUT . . . . . . . .
Introduction to the task-related user exit mechanism (the adapter). . The stub program . . . . . . . . . . . . . . . . . . . Returning control to the application program . . . . . . . . . Task-related user exits and EDF . . . . . . . . . . . . . The task-related user exit program . . . . . . . . . . . . . User exit parameter lists . . . . . . . . . . . . . . . . The schedule flag word . . . . . . . . . . . . . . . . Register handling in the task-related user exit program . . . . .
The INQUIRE_PARAMETERS call . . . . The SET_PARAMETERS call . . . . . . Monitoring functions. . . . . . . . . . . The MONITOR call . . . . . . . . . . The INQUIRE_MONITORING_DATA call . . Program management functions . . . . . . The INQUIRE_PROGRAM call. . . . . . The INQUIRE_CURRENT_PROGRAM call . The SET_PROGRAM call . . . . . . . The START_BROWSE_PROGRAM call . . The GET_NEXT_PROGRAM call . . . . . The END_BROWSE_PROGRAM call . . . The INQUIRE_AUTOINSTALL call . . . . The SET_AUTOINSTALL call . . . . . .
Rewriting user-replaceable programs . . . . . . . . . Assembling and link-editing user-replaceable programs. . . User-replaceable programs and the storage protection facility Execution key for user-replaceable programs . . . . . Data storage key for user-replaceable programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 402 405 405 406 Chapter 6. Writing a program error program. . . . . . . . . . . . . 407 The sample programs and copy books . . . . . . . . . . .
The node error program in an XRF environment . . . . The node error program with persistent session support . Changing the recovery notification . . . . . . . . . Changing the recovery message . . . . . . . . . . Changing the recovery transaction . . . . . . . . . Using the node error program with VTAM generic resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 481 481 482 482 482 Chapter 10.
Installing shipped terminals and connections . . . . . . . CICS-generated aliases . . . . . . . . . . . . . . Resetting the terminal identifier . . . . . . . . . . . The autoinstall control program at INSTALL . . . . . . . . The communications area at INSTALL for shipped terminals . The autoinstall control program at DELETE . . . . . . . . Default actions of the sample programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the transaction ID. . . . . . . . . . . . . . Telling CICS whether to route or terminate a DPL request. . . If an error occurs in route selection . . . . . . . . . . . Invoking the dynamic routing program at end of routed requests Modifying the application’s input communications area . . . . Monitoring the application’s output communications area . . . Some processing considerations . . . . . . . . . . . . Unit of work considerations . . . . . . . . . . . . . .
DFHWOSM FUNC=CLOSE macro . . DFHWOSM FUNC=DSECT macro . . DFHWOSM FUNC=JJC macro. . . . DFHWOSM FUNC={JJS|QJJS} macro . DFHWOSM FUNC=OPEN macro . . . DFHWOSM FUNC=OSCMD macro . . DFHWOSM FUNC=READ macro . . . DFHWOSM FUNC=TERM macro . . . Customizing the sample overseer program Loop or wait detection . . . . . . . Assembling and link-editing the overseer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part 6. Customizing CICS compatibility interfaces . . . . . . . . . . . . . . .689 Chapter 26. Using TCAM with CICS . . . . CICS with TCAM SNA . . . . . . . . . . Protocol management . . . . . . . . . Function management header processing. . Batch processing. . . . . . . . . . . Error processing for batch logical units . . . Error processing . . . . . . . . . . . The TCAM application program interface . . . The CICS-TCAM interface . . . . . . . . Data format . . . . . . . . . . . . . Logic flow . . . . . .
Chapter 29. Writing a “good night” program The sample “good night” program, DFH0GNIT . What the sample program does . . . . . Customizing the sample program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 735 736 736 Part 8. Examining and modifying resource attributes . . . . . . . . . . . . .739 Chapter 30. User programs for the system definition utility program (DFHCSDUP) . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823 Sending your comments to IBM xvi CICS TS for OS/390: CICS Customization Guide . . . . . . . . . . . . . . . . .
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Programming License Agreement, or any equivalent agreement between us. This book contains sample programs. Permission is hereby granted to copy and store the sample programs into a data processing machine and to use the stored copies for study and instruction only. No permission is granted to use the sample programs for any other purpose.
Trademarks The following terms are trademarks of International Business Machines Corporation in the United States, or other countries, or both: ACF/VTAM BookManager C/370 CICS CICS/ESA CICSPlex DB2 DFSMS IBM IMS IMS/ESA Language Environment MVS/ESA MQSeries OS/390 RACF System/370 VTAM Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems Inc, in the United States, or other countries, or both.
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® Transaction Server for OS/390® system to match your requirements. It describes how you can tailor your system by coding exit programs, by replacing specific CICS-supplied default programs with versions that you write yourself, and by adapting sample programs.
CICS Transaction Server for OS/390 Release 3 supports CICS applications written in: v Assembler language v C v COBOL v PL/I. In this book, the phrase “the languages supported by CICS” refers to the above languages. Syntax notation and conventions used in this book The symbols { }, [ ], and | are used in the syntax descriptions of the EXEC CICS commands and macros referred to in this book. They are not part of the command and you should not include them in your code.
Bibliography CICS Transaction Server for OS/390 CICS CICS CICS CICS CICS CICS Transaction Transaction Transaction Transaction Transaction Transaction Server Server Server Server Server Server for for for for for for OS/390: OS/390: OS/390: OS/390: OS/390: OS/390: Planning for Installation Release Guide Migration Guide Installation Guide Program Directory Licensed Program Specification GC33-1789 GC34-5352 GC34-5353 GC33-1681 GC33-1706 GC33-1707 CICS books for CICS Transaction Server for OS/390 General
CICSPlex SM books for CICS Transaction Server for OS/390 General CICSPlex SM Master Index CICSPlex SM Concepts and Planning CICSPlex SM User Interface Guide CICSPlex SM View Commands Reference Summary Administration and Management CICSPlex SM Administration CICSPlex SM Operations Views Reference CICSPlex SM Monitor Views Reference CICSPlex SM Managing Workloads CICSPlex SM Managing Resource Usage CICSPlex SM Managing Business Applications Programming CICSPlex SM Application Programming Guide CICSPlex SM App
MVS books Short Title Full Title Assembler Programming Guide OS/390 MVS Assembler Services Guide, GC28-1762 Authorized Assembler Programming Guide OS/390 MVS Authorized Assembler Services Guide, GC28-1763 Authorized Assembler Programming Reference Volume 1 OS/390 MVS Authorized Assembler Services Reference ALE-DYN, GC28-1764 Authorized Assembler Programming Reference Volume 2 OS/390 MVS Authorized Assembler Services Reference ENF-IXG, GC28-1765 Authorized Assembler Programming Reference Volume 3
Determining if a publication is current IBM regularly updates its publications with new and changed information. When first published, both hardcopy and BookManager softcopy versions of a publication are usually in step. However, due to the time required to print and distribute hardcopy books, the BookManager version is more likely to have had last-minute changes made to it before publication. Subsequent updates will probably be available in softcopy before they are available in hardcopy.
Summary of changes | | | This book is based on the Customization Guide for CICS Transaction Server for OS/390 Release 2, SC33-1683-01. Changes from that edition are indicated by vertical bars in the left margin. Changes for this edition | These are the most significant changes for this edition: v The following new global user exits are described in “Chapter 1.
– In – In XEISPOUT the file control recovery program: XFCAREQ XFCAREQC the 3270 bridge facility management program: - XFAINTU v The following new exit programming interface (XPI) function calls were introduced: – INQUIRE_CONTEXT v A new user-replaceable program was described in “Chapter 19. Writing a 3270 bridge exit program” on page 599.
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. Task-related user exit programs” on page 249 describes how task-related user exits can be invoked for SPI calls; and, if CICS is in-doubt about the outcome of a unit of work, can be told to wait rather than to take a forced decision.
– 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.
2 CICS TS for OS/390: CICS Customization Guide
Chapter 1. Global user exit programs This chapter describes the CICS global user exit points, and how you can use them, in conjunction with programs of a special type that you write yourself (global user exit programs), to customize your CICS system. The chapter is divided into the following sections: 1. “Overview — what is a global user exit?” is an introduction to global user exits, describing their main features and what they can be used for. 2.
global user exit programs Each global user exit point has a unique identifier, and is located at a point in the module or domain at which it could be useful to do some extra processing. For example, at exit point XSTOUT in the statistics domain, an exit program can be given control before each statistics record is written to the SMF data set, and can access the relevant statistics record.
global user exit programs v Register 15 contains the entry address of the exit program. No other register values are guaranteed, and they should not be relied on. The exit program should save and restore any registers that it modifies, using the save area addressed by register 13. 31-bit addressing implications v The global user exit is invoked in 31-bit AMODE. v The global user exit may be either RMODE 24 or RMODE ANY.
global user exit programs All exit programs that issue EXEC CICS commands, and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See “Returning values to CICS” on page 10. Important v If your global user exit program does not contain EXEC CICS commands, do not use the CICS command-level translator when assembling the program. v Do not make non-CICS (for example, RACF® or MVS) system service calls from global user exit programs.
global user exit programs Application programs can communicate with user exit programs that use or share the same global work area. The application program uses the EXEC CICS EXTRACT EXIT command to obtain the address and length of the global work area. A work area is freed only when all of the exit programs that use it are disabled. For examples of how to use a global work area, see the sample global user exit programs. They are listed in “Sample global user exit programs” on page 14.
global user exit programs If your exit program is to be invoked at every global user exit point, you can code: DFHUEXIT TYPE=EP,ID=ALL If your user exit program is to be used both as a global user exit program and as a task-related user exit program, you must code both: DFHUEXIT TYPE=EP,ID=exit_point_identifier and: DFHUEXIT TYPE=RM (in this order) to generate the DSECTs appropriate to both types of user exit.
global user exit programs UEPTCA points to fetch-protect storage. Use of this field results in an abend ASRD at execution time. UEPCSA points to fetch-protect storage. Use of this field results in an abend ASRD at execution time. UEPEPSA points to a save area in which the exit program should store its own registers on entry. When the exit program is entered, register 13 is also pointing to this area. The convention is to save registers 14, 15, 0–12 at offset 12 (decimal) onward.
global user exit programs | Table 1. TCB indicators in DFHUEPAR (continued). Description | | Symbolic value 2-byte code | UEPTRP RP The ONC/RPC mode TCB | UEPTSZ SZ The FEPI mode TCB | UEPTJ8 J8 The JVM mode TCB | UEPTL8 L8 An open mode TCB | UEPTSL SL The sockets listener mode TCB | UEPTSO SO The sockets mode TCB | UEPTS8 S8 The secure sockets layer mode TCB | UEPSTACK points to the kernel stack entry.
global user exit programs as if the exit program had not been invoked, and it is a valid option at most global user exit points. The exceptions are shown in the list of return codes provided with each exit description. The return code currently established for an exit is addressed by parameter UEPCRCA of DFHUEPAR, and it is needed when two or more exit programs are used at one exit. For more information, see “Invoking more than one exit program at a single exit” on page 13.
global user exit programs 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 You are strongly recommended to specify EXECKEY(CICS) when defining both global user exit programs and programs to which an exit program passes control.
global user exit programs recursive command (such as a TS command at exit point XTSEREQ). The exits most likely to be affected provide a recursion count parameter, UEPRECUR, that you can use to prevent such loops. Important When coding user exit programs, you should bear in mind that the code is executed as an extension of CICS code, rather than as a transaction, and any errors could have disastrous results.
global user exit programs 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 user exit programs Global work area (GWA) 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 (GWA). v Obtain the address of an exit program’s GWA. v Access CICS system information, and make that information available to other global user exit programs.
global user exit programs Most of the above information is obtained using EXEC CICS API commands such as: – INQUIRE SYSTEM – ASSIGN – ADDRESS – ASKTIME – FORMATTIME. v Uses the START option of the EXEC CICS ENABLE command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINKs and XCTLs. v Links to the dummy program, DFH$PCPL, in order to drive DFH$PCEX. v Uses the STOP option of the EXEC CICS DISABLE command to make DFH$PCEX unavailable for execution.
global user exit programs | DFH$PCPI is designed to be run as a PLT program. If you write a similar program, you should define it in the second part of the PLTPI list (after the PROGRAM=DFHDELIM entry). Information about how to do this is in the CICS Resource Definition Guide.
global user exit programs DFH$FCBV A sample exit program designed to be invoked at the XFCBOVER exit; it allows you to decide whether to allow an update to be backed out, following a batch update run that has overridden retained locks. See “DFH$FCBV sample global user exit program” on page 121. DFH$FCLD A sample exit program designed to be invoked at the XFCLDEL exit, which allows you to perform logical deletion of records from a VSAM ESDS data set or a BDAM data set, during backout.
global user exit programs The terminal-not-known sample exit program You can use this sample global user exit program to handle terminal-not-known conditions arising from START and ATI requests: DFHXTENF A sample global user exit program, designed to be invoked at the XALTENF or XICTENF exit. The sample source code is shown on page “The sample program for the XALTENF and XICTENF exits, DFHXTENF” on page 214.
global user exit points Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XDSAWT Dispatcher domain After an operating system wait. 42 Before an operating system wait. 42 When a write request is issued to a data table. 36 XDTLC At the completion of loading of a data table. 37 XDTRD During the loading of a data table, whenever a record is retrieved from the source data set.
global user exit points Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Page XFCBFAIL File control recovery control program When an error occurs during the backout of a UOW. 112 When CICS is about to back out a file update. 117 XFCBOUT XFCBOVER When CICS is about to skip backout of 119 a UOW because a batch program has overridden RLS retained lock protection and opened a data set for batch processing.
global user exit points Table 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.
global user exit points Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XRMIIN Resource Before execution of an EXEC DLI, manager interface EXEC SQL, or RMI command. program After execution of an EXEC DLI, EXEC SQL, or RMI command. XRMIOUT Where or when invoked XRSINDI Resource management modules XSNOFF Security manager After a terminal user signs off. domain After a terminal user signs on.
global user exit points Table 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 In the alternate CICS when active DBCTL fails. 41 XXDTO XXMATT Transaction manager domain When a user transaction is attached. 216 XXRSTAT XRF request processing program After a VTAM failure or a predatory takeover.
activity keypoint program exit Activity keypoint program exit XAKUSER The XAKUSER exit is invoked during the activity keypointing process. You can use this exit to record, on the system log, user data that must be restored following an emergency restart. For further information about the use of the exit, see the CICS Recovery and Restart Guide. For best performance, journal control requests should not specify WAIT.
activity keypoint program exit 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 | | 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.
Basic Mapping Support exits | Sample program, DFH$BMXT CICS supplies a sample program, DFH$BMXT, that shows how mapped input and output data can be modified with reference to the information provided in the “field element” table. A copybook, DFHXBMDS, is also supplied. This copybook is a DSECT which defines the structure of the field element. | | | | | | | Exit XBMIN | | When invoked After BMS has successfully processed an input mapping operation.
Basic Mapping Support exits | | | | | UERCPURG Task purged during XPI call. XPI calls All can be used. The field element table structure | | | | The field element table contains one or more elements which provide information about each “field of interest” passed to the exit. A “field of interest” is a field which has been defined as VALIDN=USEREXIT in the map source file used to create the mapset referenced in the mapping operation.
Basic Mapping Support exits | | | control, the TIOA is disposed of in accordance with the disposition of the TERMINAL (the default), SET, or PAGING option specified on the SEND MAP request. | | | BMXATTR is only relevant in the XBMOUT exit. It is the address of the attributes (if any) which BMS has placed in the output datastream preceding this field. | | | BMXMAPOF is the offset of the field in the map.
Basic Mapping Support exits | | | The actual data length (in BMXACTLN) may be less than the length defined in the map (in BMXMAPLN). This occurs due to the compression of trailing nulls performed by BMS for each output field. | | | | | The actual length of data cannot be changed in the exit program. The exit is invoked after the output datastream has been generated; consequently, an attempt to alter the data length could result in an invalid datastream.
Bridge facility exit Bridge facility exit When enabled, XFAINTU (Facility Initialization and Tidy Up) is called: v Just after a new bridge facility has been built. v Just before a bridge facility is deleted. This may be at the end of a task (when zero keep time is specified), or when a keep time expires before the facility is re-used. Exit XFAINTU When invoked Just after a bridge facility is created and just before it is freed.
data tables program exits Data tables management exits XDTRD, XDTAD, and XDTLC | These exits apply to both: v CICS shared data tables v CICS coupling facility data tables. | | XDTRD and XDTAD allow you to control the selection of records for inclusion in a data table, XDTRD being used to make such selections during loading, and XDTAD being invoked when records are subsequently added to a loaded data table (or to a CFDT that did not require loading).
data tables program exits This normally occurs when the loading process retrieves a record during the sequential copying of the source data set. However, it can also occur when an application retrieves a record that is not in the data table and: v For a user-maintained data table, loading is still in progress, or v For a CICS-maintained data table, loading terminated before the end of the source data set was reached (because, for example, the data table was full).
data tables program exits | | | UEPDTCFT(X'10') The exit has been invoked by coupling facility data table support. | | | UEPDTUMT (X'08') This is a user-maintained table. Only meaningful if UEPDTSDT is on. UEPDTRA The address of the data record. UEPDTRBL The fullword length of the data table buffer. UEPDTRL The fullword length of the data record. For user-maintained tables, the exit program can set a new length in this field, if it amends the record. UEPDTKA The address of the data table key.
data tables program exits Exit XDTAD The XDTAD user exit is invoked when a write request is issued to a data table. v For a user-maintained data table and coupling facility data table, the user exit is invoked once—before the record is added to the data table. v For a CICS-maintained data table, the user exit is invoked twice—before the record is added to the source data set and then again before the record is added to the data table.
data tables program exits UEPDTRL The fullword length of the data record. UEPDTKA The address of the data table key. UEPDTKL The fullword length of the data table key. UEPDTDSL The fullword length of the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on. UEPDTDSN A 44-character field containing the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on. Return codes UERCDTAC Add the record to the data table.
data tables program exits UEPDTCMT (X'40') This is a CICS-maintained table. Only meaningful if UEPDTSDT is on. | | | UEPDTCFT(X'10') The exit has been invoked by coupling facility data table support. | | | UEPDTUMT (X'08') This is a user-maintained table. Only meaningful if UEPDTSDT is on. UEPDTORC Data table open result code. The possible values are: UEPDTLCS Load successful UEPDTLFL Load unsuccessful. UEPDTDSL The fullword length of the name of the source data set.
DBCTL interface control program exit DBCTL interface control program exit XXDFA When invoked By an active CICS when its connection to DBCTL fails. Your exit program is invoked after the active CICS has informed the alternate CICS of the failure. Exit-specific parameters UEPDBXR Address of CICS XRF information for use with DBCTL. The CICS XRF information can be mapped using the DSECT DFHDXUEP. Return codes UERCNOAC Take no action. UERCSWCH Switch to the alternate DBCTL. UERCABNO Abend CICS without a dump.
DBCTL tracking program exits 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 different central processing complexes (CPCs). More information about these exits is provided in the CICS IMS Database Control Guide.
DBCTL tracking program exits Exit XXDTO When invoked By an alternate CICS when it performs takeover under the following conditions: v The active and alternate CICS systems are in different MVS images, perhaps in different processors. v The active CICS was connected to, or trying to connect to, a DBCTL subsystem. (This does not include disconnecting from one DBCTL and reconnecting to another.
dispatcher domain exits Dispatcher domain exits XDSBWT and XDSAWT The XDSBWT and XDSAWT 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 XDSAWT exits can be used to control the swapping state of the CICS address-space. It should be noted, however, that if the default state of the address-space is non-swappable then these exits cannot be used to override this state.
dispatcher domain exits still exceeds the count of SYSEVENT OKSWAPs. Further SYSEVENT OKSWAPs must be requested before a SYSEVENT OKSWAP is issued by CICS. Return codes UERCNORM Continue processing. UERCNOSW Issue SYSEVENT to suppress address-space swapping. XPI calls Must not be used. Chapter 1.
DL/I interface program exits DL/I interface program exits XDLIPRE and XDLIPOST The XDLIPRE and XDLIPOST exit points are invoked following the issue of an EXEC DLI command or DL/I call. Exit XDLIPRE is invoked before the request is processed and XDLIPOST is invoked after the request is processed. When the request is function shipped, the exits are invoked from both the application-owning region and the database-owning region.
DL/I interface program exits Exit XDLIPRE When invoked On entry to the DL/I interface program. Exit-specific parameters UEPCTYPE Address of type-of-request byte. Values are: UEPCEXEC The original request was an EXEC DLI request. UEPCCALL The original request was a CALL-level request. UEPCSHIP The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below.
DL/I interface program exits UEPIOAX Address of I/O area existence flag byte: UEPIOA1 I/O area exists. For UEPCSHIP requests, the I/O area existence flag is always off. UEPIOA Address of I/O area. This is the application’s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit: the new contents are used when the DL/I request is processed.
DL/I interface program exits Exit XDLIPOST When invoked On exit from the DL/I interface program. Exit-specific parameters UEPCTYPE Address of type-of-request byte. Values are: UEPCEXEC An EXEC DLI request. UEPCCALL A CALL-level request. UEPCSHIP The request has been function shipped from another region. When this value is set, restrictions apply to the setting and use of the rest of the exit parameters, as described below. UEPAPLIST Address of application’s parameter list.
DL/I interface program exits UEPIOAX Address of I/O area existence flag byte: UEPIOA1 I/O area exists. For UEPCSHIP requests, the I/O area existence flag is always off. UEPIOA Address of I/O area. This is the application’s IOAREA, or DFHEDP’s IOAREA in the case of EXEC DLI. The contents of the IOAREA can be overwritten in the exit and are returned to the application program in the new form.
dump domain exits Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT There are four exits in the dump domain. Exit XDUREQ When invoked Immediately before a system or transaction dump is taken. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name, or nulls if there is no current application. UEPDUMPC Address of copy of the 8-byte dump code.
dump domain exits UEPXDSCP Address of a 1-byte field indicating the current dump table DUMPSCOPE setting. It contains one of the following values: UEPXDLOC A system dump will be taken on the local MVS image only. UEPXDREL System dumps will be taken on both the local MVS image, and on related MVS images within the sysplex. This field may be modified by the exit to update the dump table DUMPSCOPE setting. UEPXDTXN Address of a 1-byte field indicating the current dump table TRANDUMP setting.
dump domain exits 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.
dump domain exits Return codes UERCNORM Continue processing. UERCBYP Suppress dump. UERCPURG Task purged during XPI call. XPI calls WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls. The sample program for the XDUREQ exit, DFH$XDRQ CICS supplies a sample program for the XDUREQ exit. The sample shows you how to manipulate the dump table entry, and how to permit or suppress the dump.
dump domain exits UEPDUMPT Address of the 1-byte dump-type identifier, which contains one of the following values: UEPDTRAN A transaction dump was requested. UEPDSYST A system dump was requested. Note: The dump-type identifier indicates the type of dump request that was passed to the dump domain. It does not reflect any modification that may have been made to the original request by a user entry in the dump table. UEPXDSCP Address of a 1-byte field indicating the current dump table DUMPSCOPE setting.
dump domain exits UEPXDYES The CICS system is to shutdown. UEPXDNO The CICS system is not to shutdown. This field may be modified by the exit to update the dump table SHUTDOWN setting. UEPXDMAX Address of a 4-byte field which contains the current dump table MAXIMUM setting. This field may be modified by the exit to change the current dump table MAXIMUM setting. UEPDXDCNT Address of a 4-byte field which contains the current dump table CURRENT setting.
dump domain exits XPI calls WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls. Exit XDUCLSE When invoked Immediately after a transaction dump data set has been closed. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name. UEPDMPDD Address of the 8-byte dump data set ddname.
dump domain exits UEPDMPRE Dump is about to restart after autoswitch. UEPDMPAB Abnormal termination of dump. UEPDMPDY Buffer is about to be written, and the CICS dump data set is a dummy file or is closed. UEPDMPBF Address of the dump buffer, whose length is addressed by the parameter UEPDMPLEN. UEPDMPLEN Address of the 2-byte dump-buffer length. Return codes UERCNORM Continue processing. UERCBYP Suppress dump record output. XPI calls WAIT_MVS can be used. Do not use any other calls.
enqueue EXEC interface program exits Enqueue EXEC interface program exits XNQEREQ and XNQEREQC The XNQEREQ exit allows you to intercept enqueue API requests before any action has been taken on the request. The XNQEREQC exit allows you to intercept the response after an enqueue API request has completed. The API requests affected are: v EXEC CICS ENQ v EXEC CICS DEQ. Using XNQEREQ, you can: v Analyze the API parameter list (function, keywords, argument values, and responses).
enqueue EXEC interface program exits between successive enqueue requests within the same task (for example, between successive invocations of the XNQEREQ exit). UEPRECUR Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call. UEPSCOPE Address of the 4-byte ENQSCOPE name to be used. | | Return codes UERCBYP Bypass this request. UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used.
enqueue EXEC interface program exits 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. | | UEPSCOPE Address of the 4-byte ENQSCOPE name used. Return codes UERCNORM Continue processing.
enqueue EXEC interface program exits End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.
enqueue EXEC interface program exits X'20' Set if the request contains an argument for the MAXLIFETIME keyword. If set, NQ_ADDR3 is meaningful. NQ_BITS2 Two bytes not used by the enqueue domain. NQ_EIDOPT5 One byte not used by the enqueue domain. NQ_EIDOPT6 One byte not used by the enqueue domain. NQ_EIDOPT7 One byte not used by the enqueue domain. NQ_EIDOPT8 Indicates whether certain keywords were specified on the request. X'04' NOSUSPEND was specified. X'02' DEQ was specified.
enqueue EXEC interface program exits 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: Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted.
enqueue EXEC interface program exits Removing user arguments User exit programs can remove arguments (for which the program is totally responsible) associated with the LENGTH and MAXLIFETIME keywords: Assuming that the argument to be removed exists, the user exit program must: 1. Switch the corresponding argument existence bit to ’0’b in the EID 2. Modify the parameter list to reflect the new end of list indicator.
enqueue EXEC interface program exits | | | Notes about the use of XNQEREQ to alter ENQ or DEQ scope. | | | | | | | Note: Use of either the ENQMODEL resource definition or the user exit allows this in most cases, but those applications where the resource name is determined dynamically and not known in advance can only be so converted by use of this exit. 2. Sysplex and region scope enqueues use separate namespaces.
EXEC interface program exits EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT There are four global user exit points in the EXEC interface program: XEIIN Invoked before the execution of any EXEC CICS application programming interface (API) or system programming interface (SPI) command. XEISPIN Invoked before the execution of any EXEC CICS SPI command except: v EXEC CICS ENABLE v EXEC CICS DISABLE v EXEC CICS EXTRACT EXIT.
EXEC interface program exits 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.
EXEC interface program exits 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 Task purged during XPI call. XPI calls All can be used. Exit XEISPIN When invoked Before the execution of any EXEC CICS SPI command except: v EXEC CICS ENABLE v EXEC CICS DISABLE v EXEC CICS EXTRACT EXIT.
EXEC interface program exits Exit XEIOUT When invoked After the execution of any EXEC CICS API or SPI command. Exit-specific parameters UEPARG Address of the EXEC command parameter list. UEPEXECB Address of the system EIB. UEPUSID Address of the 8-character userid. UEPPGM Address of the 8-character application program name. UEPLOAD Address of the application program’s load-point. UEPRSA Address of the application’s register save area.
EXEC interface program exits 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 Task purged during XPI call. XPI calls All can be used. Chapter 1.
file control EXEC interface API exits 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.
file control EXEC interface API exits The command-level parameter structure The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data associated with the request. (For example, the second address always points to the file name.
file control EXEC interface API exits 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' STARTBR X'0E' READNEXT X'10' READPREV X'12' ENDBR X'14' RESETBR FC_BITS1 Existence bits that define which keywords that contain values were specified. To obtain the value associated with a keyword, you need to use the appropriate address from the command-level parameter structure.
file control EXEC interface API exits X'01' SET (and not INTO) was specified. Note: Your program must test for keywords at the bit level, because there may be more than one of these keywords present. FC_EIDOPT6 Indicates whether certain keywords that do not take values were specified on the request. X'80' RBA specified. X'40' GENERIC specified. X'20' GTEQ specified. X'10' UNCOMMITTED specified. X'08' CONSISTENT specified. X'04' REPEATABLE specified.
file control EXEC interface API exits v A 4-byte address returned for SET (if the request is READ, READNEXT, or READPREV, and if FC_EIDOPT5 indicates that this is SET). v Data returned for INTO (if the request is READ, READNEXT, or READPREV, and if FC_EIDOPT5 indicates that this is not SET). v Data from FROM (if the request is WRITE or REWRITE). FC_ADDR3 is the address of one of the following: v The halfword value of LENGTH (if the request is READ, WRITE, REWRITE, READNEXT, or READPREV).
file control EXEC interface API exits 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 Table 4. A dash (—) means that the keyword cannot be specified on the request. Table 4. LENGTH and RIDFLD as input and output fields Request LENGTH RIDFLD READ Output See Note 1. WRITE Input See Note 2. REWRITE Input — DELETE — See Note 3.
file control EXEC interface API exits Modifying output fields The technique described in “Modifying input fields” on page 75 is not suitable for modifying output fields. (The results would be returned to the new area instead of the application’s area, and would be invisible to the application.) An output field is modified by altering the data that is pointed to by the command-level parameter list.
file control EXEC interface API exits X'01' NOSUSPEND specified (on READ, READNEXT, READPREV, WRITE, DELETE, or REWRITE). Bits in the EID should be modified in place. You should not modify the pointer to the EID: any attempt to do so is ignored by CICS. The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the file control request only.
file control EXEC interface API exits been function shipped to this region. In this case, if your exit program wants to bypass file control (by setting a return code of UERCBYP), it must set the 3 fullwords as follows: Fullword 1 The length of the buffer area Fullword 2 The length of the record Fullword 3 The length of the modified RIDFLD. Doing this ensures that the data and RIDFLD are correctly shipped back.
file control EXEC interface API exits In XFCREQC: 1. Check ‘UEPRCODE’ to make sure that the file control request completed without error. 2. Use UEPFCTOK to find the address of the area. This area now holds the compressed data. 3. Decompress the data in place. 4. Copy the data from the new area to the user’s INTO area. Use the user-specified LENGTH (from the command-level parameter list) to ensure that the data fits and that the copy does not cause a storage violation. 5.
file control EXEC interface API exits UEPFSHIP Address of a 16 byte area. See “Use of the parameter UEPFSHIP” on page 77. UEPRSRCE Address of an 8-character copy of the EIB resource value, EIBRSRCE. Return codes UERCNORM Continue processing. UERCBYP The file control EXEC interface program should ignore this request. UERCPURG Task purged during XPI call. XPI calls All can be used.
file control EXEC interface API exits UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. Note: If the file that has just been accessed is remote, the addressed field contains zeros (even if UEPRCODE is non-zero). UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. Note: If the file that has just been accessed is remote, the addressed field contains zeros (even if UEPRCODE is non-zero).
file control EXEC interface API exits Example program CICS supplies, in CICSTS13.CICS.SDFHSAMP, an example program, DFH$XTSE, that shows how to modify fields in the command-level parameter structure passed to EXEC interface exits. DFH$XTSE is listed on page 807.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC Exit XFCAREQ When invoked Before CICS processes a file control SPI request. Exit-specific parameters UEPCLPS Address of a copy of the SPI command parameter list. See “The command-level parameter structure” on page 86. UEPFATOK Address of a 4-byte area that can be used to pass information between XFCAREQ and XFCAREQC on a single file control SPI request. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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. UEPFATOK Address of a 4-byte area that can be used to pass information between XFCAREQ and XFCAREQC on a single file control SPI request.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2, the values used by file control for SPI requests are specified in DSECT DFHFAUED. Note: Take care when using recursive commands.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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. To obtain the argument associated with a keyword, you need to obtain the appropriate address from the command-level parameter structure. Before using this address you must check the associated existence bit.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC X'02' Set if the request contains an argument for the ENABLESTATUS keyword. If set, FC_ADDR15 is meaningful. X'01' Set if the request contains an argument for the RECOVSTATUS keyword. If set, FC_ADDR16 is meaningful. FC_EIDOPT4 Not used by file control. FC_EIDOPT5 Not used by file control. FC_EIDOPT6 Not used by file control. FC_BITS3 Existence bits which specify which arguments were specified. The comments below FC_BITS1 also apply to FC_BITS3.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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 TABLE keyword. If set, FC_ADDR33 is meaningful. X'40' Set if the request contains an argument for the MAXNUMRECS keyword. If set, FC_ADDR34 is meaningful. X'20' Set if the request contains an argument for the READINTEG keyword.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC 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 FWDRECOVSTATUS. FC_ADDR4 is the address of a 4-byte area containing the data from STRINGS. FC_ADDR5 is the address of a 44-byte area containing the name from BASEDSNAME.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC FC_ADDR23 is the address of a 4-byte area containing the CVDA from BLOCKFORMAT. FC_ADDR24 is the address of a 4-byte area containing the CVDA from KEYLENGTH. FC_ADDR25 is the address of a 4-byte area containing the data from KEYPOSITION. FC_ADDR26 is the address of a 4-byte area containing the data from RECORDSIZE. FC_ADDR27 is the address of a 4-byte area containing the CVDA from RELTYPE.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC Table 5. INQUIRE FILE requests. The relationship between arguments, keywords, data types, and input/output types. 92 Argument Keyword Data Type Input/Output Arg1 FILE CHAR(8) See note.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC Note: The file parameter on INQUIRE FILE commands is: v An input field if the request does not specify START, NEXT, or END v An output field if the request specifies NEXT v Omitted if the request specifies START or END. Table 6. SET FILE requests. The relationship between arguments, keywords, data types, and input/output types.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC Table 6. SET FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Data Type Input/Output Arg36 RLSACCESS BIN(31) Input Modifying input fields The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data.
File control EXEC interface SPI exits XFCAREQ and XFCAREQC Note: If you modify the EID, you must be careful not to create inconsistent parameters. For example, if the original request specified SET FILE OPEN and your exit turned on the EID bit for CLOSED, the resulting SET FILE request would specify both OPEN and CLOSED. In this case, the results of the command would be unpredictable.
file control file state program exits File control file state program exits XFCSREQ and XFCSREQC Two user exits are provided in the file control state program. You can use XFCSREQ, which is invoked before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE request is acted on, to gather information about the state of the file—for example, which file requests (SERVREQs) are valid, which journaling options are set. Based on this information, you can suppress the request, if appropriate.
file control file state program exits Exit XFCSREQ When invoked Before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE is attempted. Exit-specific parameters UEPFSREQ Address of a 2-byte field that indicates the type of file request. The first byte contains one of the following values: UEPFSOPN Open request UEPFSCLS Close request UEPFSENB Enable request UEPFSDIS Disable request UEPFSCAN Cancel close file request.
file control file state program exits UEFLNAME The 8-character file name. UEDSNAME The 44-character dsname of the data set associated with the file, if this has been set before the file request was issued. UEFSERV One byte indicating the SERVREQ settings for this file. The possible values are: UEFRDIM Read valid UEFUPDIM Update valid UEFADDIM Add valid UEFDELIM Delete valid UEFBRZIM Browse valid. UEFDSJL One byte indicating the automatic journaling options set for this file.
file control file state program exits 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. UEFCDATE Set to nulls for this exit. UEFCTIME Set to nulls for this exit. UEFBCAS Set to nulls for this exit. UEFACBCP This field is set to nulls in this exit. Note: Only the first seven fields of UEPFINFO are set for this exit.
file control file state program exits UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls All can be used. Notes: 1. Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCSREQ exit. Use of the recursion counter UEPRECUR is recommended. 2. Exit programs that issue EXEC CICS commands must first address the EIB. See “Using CICS services” on page 5. 3.
file control file state program exits UEPFSCP Close pending UEPFSELM End of load mode close UEPFSIMM Immediate close UEPFSICP Immediate close pending UEPFSQU RLS quiesce close. UEPFILE Address of the 8-byte file name. UEPFINFO Address of a storage area containing information about the file. The area can be mapped using the DSECT DFHUEFDS, which contains the following fields: UEFLNAME The 8-character file name. UEDSNAME The 44-character dsname of the data set associated with the file.
file control file state program exits 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: UEFJWAC Write add complete. UEFDSJID One byte containing the number of the journal to be used for automatic journaling, if any. UEFDSACC One byte indicating the access method of the file. The possible values are: UEFVSAM VSAM file UEFBDAM BDAM file.
file control file state program exits VSAM sphere with which it is associated. It contains the date when activity against the VSAM sphere was brought to an end (quiesced). UEFCTIME A time (HHMMSST+) in packed decimal format. This field is set only when the file is the last file to close against the VSAM sphere with which it is associated. It contains the time when activity against the VSAM sphere was brought to an end. UEFBCAS A flag-byte indicating the availability of this data set.
file control file state program exits Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls All can be used. Notes: 1. Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCSREQC exit. Use of the recursion counter UEPRECUR is recommended. 2. Exit programs that issue EXEC CICS commands must first address the EIB.
file control open/close program exit File control open/close program exit XFCNREC You can use XFCNREC to suppress the open failure that occurs when a mismatch is detected between the backout recovery setting for a file and its associated (non-RLS) data set. Note: This exit is not invoked for RLS opens. For RLS, recovery is a property of the data set. Therefore it is not possible for files and their base data set to have unmatched recovery attributes.
file control open/close program exit Exit XFCNREC When invoked Before file open when a mismatch is detected between the backout recovery setting for the file and its associated non-RLS data set. Exit-specific parameters UEFILE Address of the 8-bit file name. If the file name is less than 8 characters in length, it will be padded with blanks. UEDSETN Address of the 44-byte base data set name. If the data set name is less than 44 characters in length, it will be padded with blanks.
file control quiesce receive exit File control quiesce receive exit, XFCVSDS The XFCVSDS exit is invoked when VSAM RLS notifies CICS that processing is required as a result of some data set-related events occurring in the sysplex. XFCVSDS is invoked before CICS processing takes place, and only if a data set name block (DSNB) exists for the data set. The actions that cause XFCVSDS to be invoked are: v A data set is being quiesced throughout the sysplex.
file control quiesce receive exit Exit XFCVSDS When invoked Invoked after VSAM RLS has informed CICS that processing is required as a result of a data set-related action occurring in the sysplex. Exit-specific parameters UEPDSNAM Address of a 44-byte field containing the name of the data set to which the action applies UEPVSACT Address of a 1-byte field indicating the RLS action of which CICS has been informed.
file control quiesce receive exit 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 You can use CICS API and SPI commands at this exit. In general all can be used, with the following restrictions: v You should avoid the use of commands that cause the issuing task to suspend.
file control quiesce send 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 QUIESCESTATE command. The exit is invoked regardless of whether the QUIESCESTATE action has completed successfully or unsuccessfully. This enables you to perform, or schedule, any processing that cannot take place until quiesce or unquiesce processing has finished.
file control quiesce send exit UEQTIMED Failed because quiesce was canceled due to timeout (UEQSD and UEIMQSD only). UEQMIGRT Failed because the data set has been migrated. UEPQCONF Address of a 1-byte field indicating the reason why the quiesce or unquiesce was rejected (for UEQREJEC only). Possible values are: UEQUIINP Quiesce is in progress (UEQSD and UEIMQSD status only). UEUNQINP Unquiesce is in progress. UENBWINP Non-BWO copy is in progress. UEBWOINP BWO copy is in progress.
file control recovery program exits File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and XFCLDEL CICS provides four global user exits that you can use in connection with file control recovery operations. These are: XFCBFAIL Invoked when an error occurs during backout. XFCBOUT Invoked when CICS is about to back out a file update.
file control recovery program exits If more than one file is associated with a single data set, only the first record in the first of the files to fail backout within the UOW causes CICS to invoke the exit. All subsequent records are failed with the same error, but the exit is not invoked again. v For the first record for each data set that fails during any retry of the backout for this UOW. It is not invoked for backout failures to other (non-file-control) resources within the UOW.
file control recovery program exits 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). UENOSPAC Data set out of storage. UEOPENER Error opening the file. UERLSERR SMSVSAM RLS server failure. UERLSDIS RLS access is currently disabled.
file control recovery program exits API and SPI calls Although this exit is allowed to issue API and SPI calls, you should be very careful about which commands you use because the exit is invoked during file backout, which is part of syncpoint phase 2. It is recommended that you restrict EXEC CICS commands to inquiries, and avoid commands that update CICS resources, because the resources may themselves be in a state of recovery. In particular, the following restrictions apply: 1.
file control recovery program exits request. This request is issued by file control backout to delete a new record added to a VSAM data set. Use parameter UEPFCRSP to determine which error occurred. XBFENO The failure that occurred during file control backout was not as a result of an error response from the file control file-request-handler program. Use parameter UEPFCRSP to determine which error occurred.
file control recovery program exits v Sets a response code of UERCNORM and takes the normal exit from the program. A return code of UERCNORM specifies that CICS backout failure processing is to be carried out. This means that CICS issues a backout failure error message and, for a VSAM data set, ensures that the record remains locked until the backout can be retried and saves the log record for later retry.
file control recovery program exits Exit-specific parameters UEPFLOGR The address of the file control portion of the log record that is being presented for backout. This is mapped by the DSECT DFHFCLGD. Return codes UERCNORM Continue processing. A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this exit is invoked during syncpoint phase 2, and therefore cannot get a purged response from any calls it makes.
file control recovery program exits Exit XFCBOVER, file control backout override exit XFCBOVER is part of the support CICS file control provides for “batch windows” in a VSAM RLS environment. VSAM RLS locks individual records within a data set, and these locks are converted to retained locks for those UOWs that are not completed because of backout or in-doubt failures, thus preserving data integrity.
file control recovery program exits When invoked Whenever CICS is about to ignore a UOW log record that is due to be backed out, because the lock that protected the updated record could have been overridden by a non-RLS batch program. Exit-specific parameters UEPOLOGR Address of the file control portion of a shunted log record that represents an update to a data set for which retained locks may have been overridden. The file control portion of the log record can be mapped using the DSECT DFHFCLGD.
file control recovery program exits DFH$FCBV sample global user exit program DFH$FCBV provides sample processing for the file control backout override global user exit, XFCBOVER. The exit program, if enabled at the XFCBOVER exit point, is invoked when a log record is presented to file control for backing out an update to a data set in RLS access mode, after the data set has been used in a batch update despite the existence of retained locks.
file control recovery program exits Exit XFCLDEL, file control logical delete exit XFCLDEL is invoked whenever a WRITE to a VSAM ESDS, or to a BDAM data set, is being backed out. Because these types of data set do not support deletion, you can use XFCLDEL to perform a logical delete by amending the record in some way that flags it as deleted. When invoked Invoked when backing out a WRITE to a VSAM ESDS or a BDAM data set.
file control recovery program exits It is recommended that you restrict EXEC CICS commands to inquiries, and avoid commands that update CICS resources, because the resources may themselves be in a state of recovery. In particular, the following restrictions apply: 1. Do not issue any recoverable operations. 2. Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable. 3.
file control recovery program exits v Normal exit from the program: – Makes a user trace entry if tracing is active for file control. This has trace point id X'01F1' and traces: - An eye-catcher ‘DFH$FCLD EXIT OK’ - An eye-catcher ‘RECORD MARKED AS DELETED’ - The marked file control request data - The file control portion of the log record. – Returns to CICS with return code UERCLDEL, which instructs CICS to rewrite the marked record and therefore to logically delete it.
Front End Programming Interface exits 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. Chapter 1.
good morning message program exit “Good morning” message program exit XGMTEXT When invoked Before the “good morning” message is transmitted. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However, fields TIOASAL and TIOASCA are not programming interfaces. Return codes UERCNORM Continue processing.
intersystem communication program exits Intersystem communication program exits XISCONA and XISLCLQ The two exits in the intersystem communication program allow you to control the length of intersystem queues. Note: There are several methods that you can use to control the length of intersystem queues. For a description of the available methods, see the CICS Intercommunication Guide.
intersystem communication program exits 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. Your exit program could: v Stipulate that queuing is never to be used. This is the simplest way to code the exit, and avoids complexities of tuning. It should be effective if you define enough contention winner sessions to handle the peak transaction load for the connection.
intersystem communication program exits | Exit-specific parameters UEPISPCA Address of a parameter list containing the following fields. You 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). Your exit program can map the record using the DSECT DFHA14DS. See notes. UEPMODST Address of the Mode Entry statistics record, or zero.
intersystem communication program exits XPI calls All can be used. Important There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. The choice is whether or not to take the system default action of queuing the request. The XISLCLQ exit XISLCLQ enables you to specify what action to take after a function shipping request fails to allocate a session with a remote system for one of the following reasons: v The remote system is not in service.
intersystem communication program exits Note: No DSECT is provided for the above parameter list. You have to code your own DSECT to access the named fields. Return codes UERCSYS Take the system action. This is determined by the value of the LOCALQ attribute in the local TRANSACTION definition for the remote transaction: LOCALQ(YES) The request is queued locally. LOCALQ(NO) ‘SYSIDERR’ is returned to the application program.
interval control program exits Interval control program exits XICREQ, XICEXP, and XICTENF You can use some XPI calls in exit programs invoked from the interval control program. However, when any of these exits are invoked for expiry analysis, any actions that delay the execution of the interval control program can have adverse effects on other transactions that are waiting for intervals to expire.
interval control program exits Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls The following must not be used: ADD_SUSPEND DELETE_SUSPEND DEQUEUE ENQUEUE RESUME | | SUSPEND WAIT_MVS. Exit XICEXP When invoked After an interval control time interval has expired. Exit-specific parameters UEPICE Address of the interval control element (ICE) that has just expired. The ICE can be mapped using the DSECT DFHICEDS. Return codes UERCNORM Continue processing.
interval control EXEC interface program exits Interval control EXEC interface program exits XICEREQ and XICEREQC XICEREQ is invoked on entry to the interval control program before CICS processes an interval control request. Using XICEREQ, you can: v Analyze the request to determine its type, the keywords specified, and their values. v Modify any value specified by the request before the command is executed.
interval control EXEC interface program exits UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task. See “Using the task token UEPTSTOK” on page 145. UEPRECUR Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call. UEPRSRCE Address of an 8-character copy of the EIB resource value, EIBRSRCE.
interval control EXEC interface program exits ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual. UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task. See “Using the task token UEPTSTOK” on page 145. UEPRECUR Address of a halfword recursion counter.
interval control EXEC interface program exits The command-level parameter structure X'02' X'04' X'06' X'08' X'0A' X'0C' - ASKTIME DELAY POST START RETRIEVE CANCEL X'80' INTERVAL|TIME - REQID (cancel) - A(INTO)|SET (retrieve) X'40' REQID - LENGTH (retrieve) X'20' X'10' X'08' X'04' X'02' X'01' X'80' X'40' X'20' X'10' X'08' X'04' TRANSID (cancel|start) - SET|INTO FROM LENGTH TERMID SYSID RTRANSID RTERMID QUEUE HOURS MINUTES SECONDS USERID X'01' SET (not INTO) X'20' X'10' X'08' X'04' X'02' X'01' ADDR0
interval control EXEC interface program exits 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 START requests. You can examine the EID to determine the type of request and the keywords specified. You can examine the other parameters in the list to determine the values of the keywords.
interval control EXEC interface program exits 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' DELAY X'06' POST X'08' START X'0A' RETRIEVE X'0C' CANCEL IC_BITS1 Existence bits that define which arguments were specified. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure.
interval control EXEC interface program exits X'20' Set if the request specifies HOURS. If set, IC_ADDRB is meaningful. X'10' Set if the request specifies MINUTES. If set, IC_ADDRC is meaningful. X'08' Set if the request specifies SECONDS. If set, IC_ADDRD is meaningful. X'04' Set if the request specifies USERID. If set, IC_ADDRE is meaningful. IC_BITS3 One byte not used by interval control. IC_EIDOPT5 Indicates whether certain keywords were specified on the request.
interval control EXEC interface program exits IC_ADDR1 is the address of one of the following: v An 8-byte area containing the value of the INTERVAL keyword (or TIME keyword if IC_EIDOPT7 indicates that TIME is specified). v An 8-byte area containing the value of REQID (if the request is CANCEL). v Data returned for INTO (if the request is RETRIEVE, and if IC_EIDOPT5 indicates that this is not SET). v A 4-byte address returned for SET (if the request is RETRIEVE and IC_EIDOPT5 indicates that this is SET).
interval control EXEC interface program exits IC_ADDRE is the address of an area containing the value of USERID. Modifying fields in the command-level parameter structure Some fields that are passed to interval control are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.
interval control EXEC interface program exits An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified anyway. Modifying the EID It is not possible to modify the EID to make major changes to requests, such as changing a DELAY request to a START request.
interval control EXEC interface program exits 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 START request should be set on a START request. ASKTIME requests X'13' ASKTIME request. This value is fixed for all ASKTIME requests, and should not be modified. DELAY requests X'20' DELAY request X'08' TIME specified X'04' REQID specified.
interval control EXEC interface program exits 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.
interval control EXEC interface program exits 6. Set the X'02' existence bit on in IC_BITS1 to indicate that a SYSID is specified. 7. Return to CICS. In XICEREQC: 1. Scan the global work area (GWA) and locate the entry for the CICS region specified in the SYSID parameter. 2. Decrement the use count for this system. 3. If a GETMAIN was issued in XICEREQ to obtain an area to hold the SYSID, issue a FREEMAIN for the address held in UEPICTOK. 4. Return to CICS.
loader domain exits | | 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.
loader domain exits | | XPI calls Must not be used. | | API and SPI calls Must not be used. | Exit XLDELETE | | | When invoked After an instance of a program is released by CICS, and before the program is freed from storage. | Exit-specific parameters | | | UEPPROGN Address of an 8-character field containing the name of the program that is being freed. | | | UEPPROGL Address of a 4-byte field containing the length, in bytes, of the program that is being freed.
log manager domain exit Log manager domain exit XLGSTRM There is one exit point, XLGSTRM, in the log manager domain. You can use XLGSTRM to modify a request to MVS to create a new log stream. You can change the model log stream name and other parameters before they are passed to the MVS system logger.
log manager domain exit An XLGSTRM global user exit program can set explicit attributes for the log stream definition, and can also set a return code that causes the log stream definition to be bypassed. Exit XLGSTRM When invoked After the CICS log manager detects that a log stream does not exist and before calling the MVS system logger to define the log stream dynamically. Exit-specific parameters UEPTRANID The address of the 4-byte transaction id.
log manager domain exit 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. To avoid having to define explicitly each log stream used by each CICS region, you decide to use model definitions.
message domain exit Message domain exit XMEOUT The XMEOUT exit allows you to suppress or reroute CICS messages that use the message domain. Note that your exit program is subject to certain restrictions: v It cannot suppress or reroute messages sent to terminal operators, but only those sent to the system console or to transient data queues. (XMEOUT is not invoked for the former type of message.) v It can only suppress or reroute messages that use the message domain.
message domain exit 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 Transaction manager messages DFHXM0212, DFHXM0213, DFHXM0304 and DFHXM0308. v Application messages DFHAP0001, DFHAP0002, DFHAP0004, DFHAP0601, DFHAP0602, and DFHAP0603.
message domain exit UEPMNUM Address of a 4-byte field containing the message number. UEPMDOM Address of a 2-byte field containing the domain identifier of the CICS message. UEPMROU Address of an array of up to 28 route codes. Route codes must be numbers in the range 1 through 28. UEPMNRC Address of a halfword containing the number of route codes in the route code array. UEPMTDQ Address of an array of up to 25 transient data queue names to which the message is to be sent.
message domain exit UEPNRTE Address of 1-character flag indicating whether or not the message can be rerouted by XMEOUT. The possible values are: C'0:' The message can be routed. C'1:' The message cannot be routed. Return codes UERCNORM Continue processing. UERCBYP Suppress the message for all destinations. XPI calls WAIT_MVS can be used. Do not use any other calls.
monitoring domain exit 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. You can use this exit to examine the record, to suppress its output to SMF, or to change the data it contains. You must be ensure that any changes you make do not conflict with the dictionary description of the data. You can also add data to performance class data records.
monitoring domain exit UEPMRTYP Address of the halfword monitoring record type. If the value is 3, the type is performance class. If the value is 4, the type is exception class. UEPMRLEN Address of the fullword monitoring record length. UEPMREC Address of monitoring record, whose length is addressed by the parameter UEPMRLEN. UEPSRCTK Address of the MVS workload manager service reporting class token for the current transaction.
program control program exits Program control program exits XPCREQ, XPCREQC, XPCFTCH, XPCHAIR, XPCTA, and XPCABND There are six user exit points in the program control program. XPCREQ and XPCREQC XPCREQ is invoked by the EXEC interface program before a link request is processed. If the request is a distributed program link, the XPCREQ exit is driven on both sides of the link; that is, in both the client and the server regions.
program control program exits Return codes UERCBYP Program control is to ignore the request. UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used. Exit XPCREQC When invoked On completion of a program control link request.
program control program exits 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: Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a program control request is issued from the XPCREQ or XPCREQC exits. Use of the recursion counter UEPRECUR is recommended.
program control program exits PC_ADDR0 is the address of a 7-byte area called the EXEC interface descriptor (EID), which is made up as follows: PC_GROUP PC_FUNCT PC_BITS1 PC_BITS2 PC_EIDOPT5 PC_EIDOPT6 PC_GROUP Always X'0E', indicating that this is a program control request. PC_FUNCT One byte which defines the type of request, which for XPCREQ and XPCREQC is always X'02', indicating a LINK request. PC_BITS1 Existence bits that define which keywords that contain values were specified.
program control program exits PC_BITS2 Two bytes not used by program control. PC_EIDOPT5 Not used by program control. PC_EIDOPT6 Indicates whether the request specifies the SYNCONRETURN option. If it does, X'80' is set. PC_ADDR1 is the address of an 8-byte area containing the program name from the PROGRAM parameter. PC_ADDR2 is the address of the COMMAREA data. PC_ADDR3 is the address of a 2-byte area containing the length of the COMMAREA, as a half-word binary value.
program control program exits An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field you can modify the application’s data in place, because the application is expecting the field to be modified anyway. Modifying the EID It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change a LINK request to a different type of Program Control request.
program control program exits example, if you need to pass information between successive invocations of the XPCREQ exit, UEPTSTOK provides a means of doing this. The EIB Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit, so that you can: v Modify or set completion or resource information in XPCREQ and XPCREQC. v Examine completion information in XPCREQC. You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP and EIBRESP2 that you are given in the parameter list.
program control program exits 3. If a GETMAIN was issued in XPCREQ to obtain an area to hold the SYSID, issue a FREEMAIN for the address held in UEPPCTOK. 4. Return to CICS. Exit XPCFTCH XPCFTCH is invoked before a PPT-defined program (including internal CICS modules) receives control, which could be because it is the first program in a transaction, or as a result of a LINK, XCTL, or HANDLE ABEND PROGRAM request. You can use this exit to modify the entry address used when linking to the program.
program control program exits PCUE_LOAD_POINT The program’s load point. PCUE_ENTRY_POINT The program’s entry point. PCUE_PROGRAM_SIZE Fullword containing the size of the program, in bytes. PCUE_COMMAREA_ADDRESS Address of the program’s communication area. PCUE_COMMAREA_SIZE Fullword containing the length of the program’s communication area. PCUE_LOGICAL_LEVEL Fullword containing the number of chained DFHRSADS blocks (that is, logical level). PCUE_BRANCH_ADDRESS Fullword.
program control program exits Exit-specific parameters UEPPCDS Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCHAIR is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal. PCUE_TASK_NUMBER 3-character packed decimal field containing the task number.
program control program exits Exit XPCTA XPCTA 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. You can use it to: v Set a resume address, instead of letting CICS process the abend v Specify the subspace that control is passed in. If a resume address is passed back, registers 0 through 13 and 15 are restored to their values at the time of the abend.
program control program exits 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. UEPTACB Address of the transaction abend control block (TACB) for the abend.
program control program exits Exit-specific parameters UEPPCDS Address of a storage area that contains program-related and terminal-related information. The storage area is mapped by the DSECT DFHPCUE. When XPCABND is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS A 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal. PCUE_TASK_NUMBER A 3-character packed decimal field containing the task number.
resource manager interface program exits Resource manager interface program exits XRMIIN and XRMIOUT Exit XRMIIN When invoked Before a task-related user exit program is invoked due to an application program issuing an RMI API request. Exit-specific parameters UEPTRUEN Address of the name of the task-related user exit program. UEPTRUEP Address of the parameter list to be passed to the task-related user exit program. See note. UEPRECUR Address of a halfword recursion counter.
resource manager interface program exits Exit XRMIOUT When invoked After a task-related user exit program has returned from handling an RMI API request. Exit-specific parameters UEPTRUEN Address of the name of the task-related user exit program. UEPTRUEP Address of the parameter list passed to the task-related user exit program. See note. UEPRECUR Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
resource management module exit 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.
resource management module exit UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name. UEPIDREQ Address of the 1-byte install or discard identifier. The values are: UEIDINS This request is for an install (or in the case of a log stream, it is a connection to a log stream). UEIDDIS This request is for a discard (or in the case of a log stream, it is a disconnection from a log stream). UEPIDTYP Address of the 1-byte type of resource.
resource management module exit UEIDMODE A modegroup | | UEIDNQRN An ENQMODEL UEIDPART A partner UEIDPROF A profile UEIDPROG A program | | UEIDPRTY A BTS process-type UEIDPSET A partitionset | | UEIDRQMD A request model (IIOP) UEIDSESS A session UEIDSTRM An MVS log stream UEIDTCLS A transaction class | | UEIDTCPS A TCP/IP service UEIDTDQU A transient data queue UEIDTERM A terminal UEIDTRAN A transaction | | UEIDTSMD A temporary storage queue model.
resource management module exit 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 Task purged during XPI call. XPI calls You can use all XPI calls. Important Abends in a program enabled at the XRSINDI exit point may cause CICS to terminate, because for some resources the exit is driven during syncpoint.
sign on and sign off exits Signon and signoff 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-off 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.
sign on and sign off exits UEPSNFL Signon failed. Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. Exit XSNOFF When invoked When a user signs off. Exit-specific parameters UEPUSRID Address of the terminal userid. UEPUSRLN Address of the terminal userid length. UEPGRPID Address of the group ID. UEPGRPLN Address of the group ID length. UEPNETN Address of the terminal’s netname. UEPTRMID Address of the terminal id.
sign on and sign off exits UERCPURG Task purged during XPI call. XPI calls All can be used. Chapter 1.
statistics domain exit Statistics domain exit XSTOUT On invocation, XSTOUT is passed the address of a buffer containing one or more statistics records. The buffer can contain records for various resource types (for example, connections and modenames), and both specific and global information (for example, loader statistics for individual programs, and loader statistics for all programs). Your exit program can identify the types of records in the buffer by their STID values.
statistics domain exit UEPSDATE 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). UEPSIVAL Address of a 6-byte character field containing the interval time (HHMMSS). This field has meaning only for interval statistics. UEPSIVN Address of the 4-byte interval number. This field has meaning only for interval statistics.
system recovery program exit System recovery program exit XSRAB Exit XSRAB When invoked When the system recovery program (DFHSRP) finds a match in the SRT for an MVS/ESA™ abend code. For information about defining entries in the SRT, refer to the CICS Resource Definition Guide. Note: The SRT table is only processed, and the exit driven, when an an MVS abend occurs under a CICS essential TCB—that is, one of QR, RO, CO, SZ, RP, FO.
system recovery program exit SRP_USER_CODE The abend occurred while running user application code. SRP_PPT_ENTRY The abend occurred while running SRP_ERROR_PPT_NAME. If this flag is not set, the abend occurred while running SRP_ERROR_STACK_NAME. SRP_VALID_OFFSET A meaningful offset could be determined. SRP_VALID_REASON MVS has supplied a reason code for the abend. SRP_NOT_CICS_RB CICS RB was not in control at the time of the abend (that is, the abend occurred in a system service invoked by CICS).
system recovery program exit SRP_ERROR_FP_REGS An area describing the contents of the floating point registers at the time of the abend. It contains: SRP_FP_REG_0 FP register 0 SRP_FP_REG_2 FP register 2 SRP_FP_REG_4 FP register 4 SRP_FP_REG_6 FP register 6. Notes: 1. If flag SRP_NOT_CICS_RB is set, SRP_CICS_ERROR_DATA describes the last thing that CICS did, prior to the abend; SRP_SYSTEM_ERROR_DATA describes the last thing that the system service (for example, VTAM, VSAM, or MVS) did. 2.
system recovery program exit Important Notes: 1. Take care when coding a program to run at the XSRAB exit point. If your exit program causes the system recovery program to be reentered (if, for example, a program check occurs) then CICS terminates abnormally, with a DFHSR06xx message. 2. The default return code is ‘UERCNOCA’. This ensures that the task abends if the exit is in error. 3. There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. 4.
system termination program exit System termination program exit XSTERM The XSTERM exit could be used to output final statistics to your statistics SMF data sets, and to close them. (Note that CICS VSAM and BDAM data sets have already been closed by CICS file control before the exit is invoked.) Exit XSTERM When invoked During the second quiesce stage of a normal system shutdown, immediately before the transient data and temporary storage buffers are cleared.
temporary storage domain exits Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT The temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT allow you to: v Specify, for a request that creates a queue, whether the queue is to be held in main or auxiliary storage, and its recoverability v Monitor the use of temporary storage v Control security for temporary storage queues.
temporary storage domain exits UEP_TS_DATA_P Address of a fullword containing the address of the data. (Write and rewrite requests). UEP_TS_DATA_L Address of a fullword containing the length of the data. (Write and rewrite requests). UEP_TS_ITEM_NUMBER Address of a fullword containing the item number. (Rewrite, read_into and read_set requests). UEP_TS_STORAGE_TYPE Address of a byte containing the storage type. (Write requests).
temporary storage domain exits UEPPROG Address of the 8-byte application program name. UEP_TS_FUNCTION Address of a byte containing the function: UEP_TS_FUN_WRITE UEP_TS_FUN_REWRITE UEP_TS_FUN_READ_INTO UEP_TS_FUN_READ_SET UEP_TS_FUN_READ_NEXT_INTO UEP_TS_FUN_READ_NEXT_SET UEP_TS_FUN_DELETE | UEP_TS_QUEUE_NAME Address of a 16-byte field containing the queue name. UEP_TS_DATA_P Address of a fullword containing the address of the data. (All requests except delete).
temporary storage domain exits Exit XTSPTIN When invoked Before execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or BMS queues). Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name.
temporary storage domain exits UEP_TS_STORAGE_TYPE_AUX_RECOV_NO Auxiliary storage (non-recoverable). Return codes UERCNORM Normal. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls None can be used. Exit XTSPTOUT When invoked After execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or BMS queues). After execution of a TSPT request. No parameters may be modified.
temporary storage domain exits UEP_TS_RESPONSE_OK UEP_TS_RESPONSE_PURGED UEP_TS_RESPONSE_EXCEPTION UEP_TS_RESPONSE_DISASTER UEP_TS_RESPONSE_INVALID Return codes UERCNORM Normal response. UERCPURG A purged response was received from an XPI request. XPI calls All can be used. API and SPI calls None can be used.
temporary storage EXEC interface program exits Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC The XTSEREQ exit allows you to intercept temporary storage API requests before any action has been taken on the request. The XTSEREQC exit allows you to intercept the response after a temporary storage API request has completed. The API requests affected are: v EXEC CICS WRITEQ TS v EXEC CICS READQ TS v EXEC CICS DELETEQ TS.
temporary storage EXEC interface program exits Exit XTSEREQ When invoked Before CICS processes a temporary storage API request. Exit-specific parameters UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 196. UEPTQTOK Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary storage request. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE.
temporary storage EXEC interface program exits Exit XTSEREQC When invoked After a temporary storage API request has completed, before return from the temporary storage EXEC interface program. Exit-specific parameters UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 196. UEPTQTOK Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary storage request.
temporary storage EXEC interface program exits You must set valid temporary storage responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by temporary storage to describe a valid completion. CICS does not check the consistency of EIBRCODE, EIBRESP, and EIBRESP2. If EIBRCODE is set to a non-zero value and EIBRESP is set to zero, CICS will override EIBRESP with a non-zero value.
temporary storage EXEC interface program exits 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. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure.
temporary storage EXEC interface program exits X'80' WRITEQ MAIN or READQ ITEM specified. X'04' WRITEQ REWRITE or READQ NUMITEMS specified. TS_EIDOPT8 Indicates whether certain keywords were specified on the request. X'80' ITEM was specified (otherwise NUMITEMS). TS_ADDR1 is the address of area containing 8-byte name from QUEUE. or 16-byte name from QNAME. To determine which of these is applied, see 197.
temporary storage EXEC interface program exits NUMITEMS SET LENGTH is an input field on a WRITEQ request, and an output field on a READQ request that specifies SET. It is both an input and an output field on a READQ request that specifies INTO. ITEM is an input field on a READQ request, and on a WRITEQ request that specifies REWRITE. It is both an input and an output field on a WRITEQ request that does not specify REWRITE.
temporary storage EXEC interface program exits X'10' The existence bit for NOSUSPEND. X'08' The existence bit for MAIN. The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the temporary storage request only. Note: Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted.
temporary storage EXEC interface program exits Table 9.
temporary storage EXEC interface program exits Example program CICS supplies—in hardcopy only—an example program, DFH$XTSE, that shows how temporary storage requests can be modified. See “Appendix E. The example program for the XTSEREQ global user exit, DFH$XTSE” on page 807.
terminal allocation program exit Terminal allocation program exit XALCAID XALCAID is driven when an AID with data is canceled in one of the following ways: v By means of the CEMT transaction v During execution of a SET TERMINAL or SET CONNECTION command v During reinstallation of a terminal or connection. XALCAID is invoked only if there is data associated with the AID. Exit XALCAID When invoked Whenever an AID with data is canceled.
terminal allocation program exit contains FMHs, as specified by the FMH option on the associated START command; or hexadecimal zeros otherwise. UEPALSTC Address of a 2-byte field containing the start code. This is "SZ" for FEPI starts; otherwise it is "SD". Return codes UERCNORM No other return codes are supplied. The value of the return code is not inspected. XPI calls You can use: INQ_APPLICATION_DATA INQUIRE_SYSTEM No other XPI calls should be used. API and SPI commands No EXEC CICS commands can be used.
terminal control program exits Terminal control program exits XTCIN, XTCOUT, XTCATT, XTCTIN, and XTCTOUT Exit XTCIN When invoked After an input event for a sequential device. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). Your exit program should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
terminal control program exits Exit XTCATT When invoked Before task attach. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However, fields TIOASAL and TIOASCA are not programming interfaces. UEPTCTLE Address of the terminal control table line entry (TCTLE).
terminal control program exits Exit XTCTOUT When invoked Before a TCAM output event. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However, fields TIOASAL and TIOASCA are not programming interfaces. UEPTCTLE Address of the terminal control table line entry (TCTLE).
terminal not known condition exits ‘Terminal not known’ condition exits XALTENF and XICTENF The ‘terminal not known’ condition can occur when intercommunicating CICS regions use both SHIPPABLE terminal definitions and automatic transaction initiation (ATI). The condition is especially likely to arise if autoinstall is used. SHIPPABLE attribute Terminals defined with the SHIPPABLE attribute in a terminal-owning region (TOR) do not need a definition in a connected application-owning region (AOR).
terminal not known condition exits CICS drives the XICTENF exit when the ‘terminal not known’ condition occurs after the interval control program has been invoked by an EXEC CICS START command. CICS drives the XALTENF exit when the ‘terminal not known’ condition occurs after the terminal allocation program has been invoked by the transient data trigger level or the interval control program. Note that an EXEC CICS START command could result in both exits being invoked.
terminal not known condition exits Exit-specific parameters UEPALEVT Address of 2 bytes containing the type of request. The equated values of the types are: UEPALESD START command with data UEPALES START command without data UEPALETD Transient data trigger level reached. UEPALTR Address of 1 byte containing an indication of whether the task issuing the START command was started by transaction routing.
terminal not known condition exits For START 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 START command situations and for transient data trigger level events, the field pointed to contains blanks. UEPALSYI Address of 4 bytes containing, if UEPALNTI contains a netname, the corresponding sysid. If UEPALNTI does not contain a netname, the field pointed to is blank.
terminal not known condition exits Exit XICTENF When invoked By the interval control program when the terminal that an EXEC CICS START command requires is unknown in this system. The exit program is expected to give a return code indicating whether the terminal exists on another connected CICS system and, if so, on which one. Exit-specific parameters UEPICEVT Address of 2 bytes containing the type of request.
terminal not known condition exits UEPICNTI Address of 8 bytes containing, for function-shipped START commands, the netname of the last system from which the request came. For START 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 START command situations, the field pointed to contains blanks. UEPICSYI Address of 4 bytes containing, if UEPICNTI contains a netname, the corresponding SYSID.
terminal not known condition exits DELETE_SUSPEND DEQUEUE ENQUEUE RESUME SUSPEND | | WAIT_MVS. The sample program for the XALTENF and XICTENF exits, DFHXTENF One program can be used for both exits, or a separate program can be written for each. Figure 2 shows the executable code from the supplied sample program DFHXTENF, which can be used for both exits. DFHXTENF rejects transient data requests, because the action in this case is very much installation-dependent.
terminal not known condition exits *BLDNETNM DS 0H * * Build a netname by taking the first character of the * terminal ID and appending it to the characters 'CICS'.
transaction manager domain exit Transaction manager domain exit XXMATT Exit XXMATT When invoked During transaction attach. This exit is able to change some of the attributes of the transaction that is being attached. Exit-specific parameters UEPTRANID The address of transaction id (see Notes). UEPUSER The address of the userid associated with the transaction if the current task is a user task (see Notes). UEPTERM The address of the terminal id associated with the transaction, if any (see Notes).
transaction manager domain exit UEPATTTK The address of a doubleword containing a transaction token. Note that some of the transaction manager XPI calls require this token to identify the transaction that is being attached. Return codes UERCNORM Continue attach processing. XPI calls The user exit can inquire on the transaction being attached, using the UEPATTTK transaction token as input to the XMIQ INQUIRE_TRANSACTION XPI call.
transient data program exits Transient 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. Values are: UEPTDPUT PUT request UEPTDGET GET request UEPTDPUR PURGE request. Return codes UERCNORM Continue TD processing. UERCTDOK Quit TD processing – returning ‘NORMAL’ to the caller. UERCTDNA Quit TD processing – returning ‘NOTAUTH’ to the caller.
transient data program exits Exit XTDIN When invoked After receiving data from QSAM (for extrapartition) or VSAM (for intrapartition). Exit-specific parameters UEPTDQUE Address of the 4-byte TD queue name. UEPTDAUD Address of the unmodified TD data. UEPTDLUD Address of the fullword length of the unmodified TD data. UEPTDAMD Address of the TD data modified by the exit program. UEPTDLMD Address of the fullword length of the TD data modified by the exit program. Return codes UERCNORM Continue TD processing.
transient data program exits Exit XTDOUT When invoked Before passing the data to a QSAM (for extrapartition) or VSAM (for intrapartition) user-defined transient data queue. Exit-specific parameters UEPTDQUE Address of the 4-byte TD queue name. UEPTDAUD Address of the unmodified TD data. UEPTDLUD Address of the fullword length of the unmodified TD data. UEPTDAMD Address of the TD data modified by the exit program. UEPTDLMD Address of the fullword length of TD data modified by the exit program.
transient data EXEC interface program exits Transient data EXEC interface program exits XTDEREQ and XTDEREQC The XTDEREQ exit allows you to intercept a transient data request before any action has been taken on it by transient data. The XTDEREQC exit allows you to intercept a transient data request after transient data has completed its processing. Using XTDEREQ, you can: v Analyze the request to determine its type, the keywords specified, and their values.
transient data EXEC interface program exits UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual. UEPRESP Address of a 4-byte binary copy of the EIB response code ‘EIBRESP’. UEPRESP2 Address of a 4-byte binary copy of the EIB response code ‘EIBRESP2’. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task. See “Use of the task token UEPTSTOK” on page 228.
transient data EXEC interface program exits Exit XTDEREQC When invoked After a transient data API request has completed, and before return from the transient data EXEC interface program. Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 225. UEPTDTOK Address of the 4 byte token to be passed to XTDEREQC. This allows you, for example, to pass a work area to exit XTDEREQC.
transient data EXEC interface program exits The command-level parameter structure X'02' X'04' X'06' WRITEQ READQ DELETEQ X'80' X'40' X'20' X'10' X'08' X'04' X'02' X'01' QUEUE FROM|SET|INTO LENGTH SYSID X'01' SET X'40' X'80' X'C0' X'04' WRITEQ READQ READQ(nosuspend) DELETEQ 08 .. .. 00 08 .. 00 .. 00 Addr0 Addr1 queue name char(4) set address or data fullword/char(*) data length halfword system id char(4) Addr2 Addr3 Addr4 Addr5 dummy args Addr6 Addr7 Figure 3.
transient data EXEC interface program exits End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.
transient data EXEC interface program exits TD_BITS1 Existence bits that define which arguments were specified. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the argument was not specified in the request and the address should not be used. X'80' Set if the request contains an argument for the QUEUE keyword.
transient data EXEC interface program exits TD_ADDR4 is the address of a value intended for CICS internal use only. It must not be used. TD_ADDR5 is the address of a value intended for CICS internal use only. It must not be used. TD_ADDR6 is the address of a value intended for CICS internal use only. It must not be used. TD_ADDR7 is the address of an area containing the value of SYSID. TD_ADDR8 is the address of a value intended for CICS internal use only. It must not be used.
transient data EXEC interface program exits An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified. Modifying fields used for both input and output An example of a field that is used for both input and output is LENGTH on a READQ request that specifies INTO.
transient data EXEC interface program exits 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. You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list.
user log record recovery program exits User log record recovery program exits XRCINIT and XRCINPT At warm and emergency restart, updates made to recoverable CICS resources that were not committed when the system terminated must be backed out. XRCINIT and XRCINPT are invoked from the user log record recovery program, which is used to back out, where necessary, user-written system log entries.
user log record recovery program exits 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_DATA, MONITOR and INQUIRE_MONITOR_DATA until the second phase of the PLTPI. v There are also restrictions on the use of EXEC CICS commands in these exits: – You cannot use EXEC CICS commands to access terminal control services.
user log record recovery program exits 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.
user log record recovery program exits 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. UEPTAID Address of a 4-byte field containing the task identifier. UEPTRID Address of a 4-byte field containing the transaction identifier. UEPTEID Address of a 4-byte field containing the terminal identifier.
VTAM terminal management program exit VTAM terminal management program exit XZCATT Exit XZCATT When invoked Before task attach for terminal tasks. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). The TIOA can be mapped using the DSECT DFHTIOA. However, fields TIOASAL and TIOASCA are not programming interfaces.
VTAM working-set module exits VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE Note: None of the exits in the VTAM working-set module is available for advanced program-to-program communication (APPC, or LUTYPE6.2) links. Exit XZCIN When invoked After an input event. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA).
VTAM working-set module exits XPI calls All can be used. However, we do not recommend that you use a GETMAIN call to obtain terminal-class storage for use as a replacement TIOA. This is because there are several internal pointers to the TIOA, and if any one of these is not updated the application may experience problems. Exit XZCOUT1 When invoked Before a message is broken into RUs. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE).
VTAM working-set module exits XZIQUE exit for managing intersystem queues You can use the XZIQUE exit to control the number of queued requests for sessions on intersystem links (allocate queues). Note: There are several methods that you can use to control the length of intersystem queues. For a description of the various methods, see the CICS Intercommunication Guide. | | | | The XZIQUE exit enables you detect queuing problems (bottlenecks) early.
VTAM working-set module exits 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. Your program communicates its decision to CICS by means of one of the return codes CICS provides.
VTAM working-set module exits If the queue limit has been reached but the performance of allocate processing against the queue is below the acceptable limits defined in your user exit program, you can return control to CICS as follows: v For non-specific allocate requests, use return code UERCAKLL. UERCAKLL also returns SYSIDERR to all application programs waiting on the purged allocate requests.
VTAM working-set module exits A14EALRJ: Each time an XZIQUE global user exit program returns with a request to reject a request, CICS increments a new field in the system entry connection statistics. This is A14EALRJ (allocate rejected) in DSECT DFHA14DS. This field is provided to help you to tune the queue limit. Normally, if the number of sessions and the queue limit defined for a link are correctly balanced, and there has been no abnormal congestion on the link, the A14EALRJ should be zero.
VTAM working-set module exits 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. UEPPAD A 1-byte padding field. UEPFSPL Address of the 10-byte function shipping parameter list. UEPCONST Address of the 158-byte system entry statistics record (this can be mapped using DSECT DFHA14DS).
VTAM working-set module exits Non-specific allocates data:The following three fields contain data relating to MRO, LU6.1, and non-specific APPC allocates: UEPSAQTS A double-word binary field containing the time stamp from the TCT system entry indicating the time the queue of non-specific requests was started. UEPSACNT A half-word binary field containing the number of all non-specific allocates processed since the queue was started (see UEPSAQTS for the start time).
VTAM working-set module exits modegroup specified on this allocate request and send an information message to the operator console. Retry the modegroup after an interval. UERCPURG Task purged during XPI call. In the case of a successful allocate following the use of UERCAKLL or UERCAKLM, on a previous invocation of the exit, use one of the following: UERCNORM Resume normal operation of the link or modegroup. UERCPUR Reject the allocate request with SYSIDERR. XPI calls All can be used.
VTAM working-set module exits Sample exit program design A sample XZIQUE exit program is provided with CICS Transaction Server for OS/390 Release 3 as a base for you to design your own global user exit program. It is called DFH$XZIQ, and is supplied in the CICSTS13.CICS.SDFHSAMP library. The DSECT used by the sample program to map the area addressed by UEPZDATA is called DFHXZIDS, and this is supplied in the CICSTS13.CICS.SDFHMAC library.
VTAM working-set module exits 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 XRF request-processing program exit XXRSTAT XXRSTAT enables you to decide whether to terminate CICS when either of the following occurs: v CICS is notified of a VTAM failure by the TPEND exit. v A predatory takeover. A “predatory takeover” can occur, if you are using VTAM Release 3.4.0 or above, and a VTAM application with the same APPLID as that of the executing CICS system assumes control of all the sessions of the executing CICS system.
XRF request-processing program exit Return codes UERCNORM Take the system action. The system action depends on the reason why the exit was invoked: v For XRF, in the event of a VTAM failure: CICS continues processing as if the exit program had not been invoked. v For VTAM persistent sessions, in the event of a predatory takeover: CICS abends without a dump. UERCCOIG Ignore. UERCABNO Abend CICS without a dump. UERCABDU Abend CICS with a dump. UERCPURG Task purged during XPI call. XPI calls All can be used.
XRF request-processing program exit 248 CICS TS for OS/390: CICS Customization Guide
Chapter 2. Task-related user exit programs This chapter describes a special kind of user exit called a task-related user exit. A task-related user exit allows you to write your own program to access a resource, such as a database, that would not otherwise be available to your CICS system. Such a resource is known as a non-CICS resource. The exit is said to be task-related because it becomes part of the task that invoked it and because, unlike a global user exit, it is not associated with an exit point.
the adapter Application program Stub program Administration routines THE Taskrelated user program Resource manager Non-CICS resource ADAPTER Figure 4. The adapter concept The task-related user exit program is provided with a parameter list (DFHUEPAR) by the CICS management module that handles task-related user exits. This parameter list gives the task-related user exit access to information such as the addresses and sizes of its own work areas.
the stub program Application program . CALL statname . . Stub statname ENTRY statname . . DFHRMCAL TO=ename . END Task-related user exit ename Figure 5. The stub concept 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.
the stub program 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’. Task-related user exits and EDF When a task-related user exit (TRUE) is invoked for a call to a non-CICS resource manager from an application that is being monitored by EDF, EDF’s default action is to display the parameters that are addressed by the parameter list passed by the DFHRMCAL macro.
the task-related user exit program User exit parameter lists When a task-related user exit is invoked, the CICS management module that handles task-related user exits provides the exit with a parameter list. The address of this parameter list is passed in register 1.
the task-related user exit program command. The global work area is described on page “The global work area” on page 269. CICS initializes this work area to X'00' when the task-related user exit program is enabled. UEPGAL Address of a halfword containing the length (binary value) of the global work area. UEPTCA This field is retained for historical reasons. It should not be referenced by your exit program. UEPCSA This field is retained for historical reasons.
the task-related user exit program UEPUOWDS Address of the APPC unit of work (UOW) identifier. UEPSECFLG Address of the user security flag. The user security flag is a 1-byte field that can take the following values: UEPNOSEC (X'80') Security is not active for this CICS system. UEPSEC (X'20') Security is active for this CICS system. Only in this case is the address of the “user security block” set. UEPSECBLK Address of a fullword that addresses the “user security block”—that is, the ACEE.
the task-related user exit program | | | 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: | | | | UEPTANY (X'80') The application can accept addresses above 16MB. If the symbolic value is not UEPTANY, the application must be returned an address below 16MB.
the task-related user exit program UEPTRLV1 (X'80') RMI level 1 trace is active. UEPTRLV2 (X'40') RMI level 2 trace is active. Having tested this field, the task-related user exit could, for example, issue an EXEC CICS SET TRACETYPE command to reset the level of RMI tracing. DFHUERTR (the function definition) The function definition identifies the caller of the task-related user exit program. The DSECT contains two symbolic definitions (fields). UERTFGP A single byte that is set to X'00'.
the task-related user exit program exit program can be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM commands on which the CONNECTST or QUALIFIER option is specified. This allows applications to query whether the exit program is connected to its resource manager, and its entryname-qualifier. For information about the INQUIRE EXITPROGRAM command, see the CICS System Programming Reference manual.
the task-related user exit program 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. UERTWAIT (X'04') Resource manager must wait for the outcome of this unit of recovery. This value is set at phase two of a two-phase commit, if CICS is in-doubt about the outcome of a UOW.
the task-related user exit program Parameter 6 Address of a 4-byte, packed-decimal field containing the date of the failing syncpoint, in the format 00yyddd+. See note 1. Parameter 7 Address of a 4-byte, packed-decimal field containing the time of the failing syncpoint, in the format 0hhmmss+. See note 1. Parameter 8 Address of an 8-byte field containing the resource manager qualifier. See note 1.
the task-related user exit program The significance of the parameters is as follows: Parameter 1 The address of a single byte with bit definitions indicating the reason for the call: UERTSOTR (X'40') Start of CICS task UERTEOTR (X'80') End of CICS task. Parameter 2 This parameter is passed only on end-of-task calls. It is the address of a 4-character field which contains the next transaction code specified on the EXEC CICS RETURN command.
the task-related user exit program UEPEDFFI The input flag byte. When a task-related user exit is invoked by EDF, UEPEDFFI can take the following bit settings: UEPEDFRQ (X'80') “About to Execute” invocation. UEPEDFRS (X'40') “Command Execution Complete” invocation. UEPEDFRA (X'20') About to display command to EDF. UEPEDFRC (X'10') Command has been displayed to EDF. UEPEDFSC (X'08') EDF user has changed the screen. UEPEDFWS (X'04') EDF user has changed working storage.
the task-related user exit program DISPLAY DATA UEPEDFPA Address of attribute byte Address of data field Address of attribute byte . . . Address of attribute byte Address of data field Figure 6. Display data parameter list 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.
the task-related user exit program CICS SPI call DFHUEPAR UEPEXN UEPGAA UEPGAL UEPHMSA UEPTAA UEPTAL UEPEIB UEPURID UEPFLAGS UEPRMSTK UEPUOWDS UEPSECFLG UEPSECBLK UEPRMQUA UEPCALAM UEPSYNCA UEPTIND UEPPBTOK UEPTRCE DFHUERTR Application program call DFHUEPAR UEPEXN UEPGAA UEPGAL UEPHMSA UEPTAA UEPTAL UEPEIB UEPURID UEPFLAGS UEPRMSTK UEPUOWDS UEPSECFLG UEPSECBLK UEPRMQUA UEPCALAM UEPSYNCA UEPTIND UEPPBTOK UEPTRCE DFHUERTR Syncpoint Task manager manager call call DFHUEPAR UEPEXN UEPGAA UEPGAL UEPHMSA UE
the task-related user exit program 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 DFHUEPAR.
the task-related user exit program program to be called at the start as well as at the end of a task, you must specify TASKSTART on the EXEC CICS ENABLE command for the TRUE. This causes the TRUE to be invoked at the start and end of every task.) If the last two bytes of the schedule flag word are set to X'1000', this indicates that the task-related user exit is interested in being invoked by EDF to format requests for display.
the task-related user exit program significance of register settings on return are either described in your resource manager’s documentation, or defined locally. Addressing-mode implications The task-related user exit is invoked in the AMODE of the caller, unless the exit has been enabled with the LINKEDITMODE option of the EXEC CICS ENABLE command. This option enables the task-related user exit in its link-edit AMODE.
the task-related user exit program 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 You are strongly recommended to specify EXECKEY(CICS) when defining both task-related user exit programs, and programs to which an exit program passes control.
the task-related user exit program 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.
the task-related user exit program that is exclusively for the exit program’s use. It is specified using the TALENGTH option of the EXEC CICS ENABLE command and is accessed using the UEPTAA parameter of DFHUEPAR.
the task-related user exit program Increasing efficiency – single-update and read-only protocols If your resource manager is capable of performing a single-phase commit, you can increase the efficiency of your system by means of CICS single-update and read-only protocols. Single-update protocol: Many CICS transactions use only one external resource manager. In this case, a single-phase commit is in order.
the task-related user exit program Table 12.
the task-related user exit program if UERTFID = UERTSYNC then /* Caller is CICS syncpoint manager */ select; /* Type of syncpoint manager request */ when (UERTONLY) /* ONLY resource manager */ invoke RM for single-phase commit /* Single-phase commit */ if RM single-phase commit succeeded then give CICS syncpoint manager 'YES' vote (UERFOK) else /* Single-phase commit failed */ /* If RM completed backout */ if RM single-phase commit failed and backed out give CICS syncpoint manager 'NO' vote (UERFBOUT) else
the task-related user exit program a UERTELUW call. Because no updates were made, data integrity is not at risk, and therefore no action is taken if the commit fails. On receiving a request to perform the first phase of a two-phase commit, the resource manager is expected to get into a state where recoverable changes made since the last syncpoint can be either committed or backed out on demand, even if there is an intervening system failure. For example, buffer contents must be moved to nonvolatile storage.
the task-related user exit program 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. Typically, your program shows interest in task manager events if it needs to save task-related information, such as performance or accounting data, before the task ends. Limitations If your exit program is invoked at end-of-task, you must be alert to possible limitations on exit program activity at task-detach.
the task-related user exit program The limitations on what your program can do, if invoked, depend on the type of termination: Orderly shutdown (UERTCORD) Your 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.
the task-related user exit program JTRUE1A CSECT TERMINATION TRUE ENTRYPOINT STM 14,12,12(13) Save registers USING JTRUE1A,R3 LR R3,R15 Use R3 as base register USING DFHUEPAR,R1 Address DFHUEPAR parameter list L R2,UEPEXN USING DFHUERTR,R2 CLI UERTFID,UERTCTER CICS Termination call? BNE CONT No, so continue L R10,UEPHMSA Address Host register save area USING SA,R10 L R5,RSAR1 Get Caller's R1 USING DFHCTERM,R5 L R5,CTERML Get termination type USING CTERMLIST,R5 TM CTERMTYPE,UERTCORD CICS orderly shutdown? B
the task-related user exit program * * * * * EXIT * MVC DFHEIBP,UEPEIB MVC DFHEICAP,=X'80000000' ..... Insert code here for all types of call other than when CICS is abending (CICS services can be used) .....
the task-related user exit program Task-related user exit interface Task-related user exit (T1) Prepare 'About to Execute' EDF screen EDF (E1) Display screen Task-related user exit (T2) Response EDF user Task-related user exit (T3) Access resource manager Task-related user exit (T4) Prepare 'Command Execution Complete' EDF screen EDF (E2) Display screen Task-related user exit (T5) Response EDF user Figure 10.
the task-related user exit program 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.
adapter administration user exit should invoke its resource manager to free any task-related resources, such as the thread. However, the resource manager should maintain any locks held by the UOW, and record that the UOW is in-doubt. When CICS receives the outcome of the UOW from its coordinator, a resynchronization task is attached to notify the task-related user exit about the outcome of the UOW.
adapter administration Tracing 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. You 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 Transaction Server for OS/390 Release 3. It is divided into the following sections: v “Overview” is an introduction to the XPI. v “General form of an XPI call” on page 286 contains information that applies to all the XPI calls. v “Global user exit XPI examples, showing the use of storage” on page 292 contains two pieces of sample code.
user exit programming interface v Using the XPI dump control functions, you can: – Request a system dump—see “The SYSTEM_DUMP call” on page 314 – Request a transaction dump—see “The TRANSACTION_DUMP call” on page 316. v Using the XPI enqueue domain functions, you can: – Enqueue on a named resource—see “The ENQUEUE function” on page 318 – Release a resource previously enqueued by an ENQUEUE function call—see “The DEQUEUE function” on page 319.
user exit programming interface – Change the settings of the autoinstall function for programs, mapsets, and partitionsets—see “The SET_AUTOINSTALL call” on page 350. v Using the XPI state data access functions, you can: – Inquire on application system data in the AP domain—see “The INQ_APPLICATION_DATA call” on page 352 – Inquire on CICS system data in the AP domain—see “The INQUIRE_SYSTEM call” on page 355 – Set CICS system data values in the AP domain—see “The SET_SYSTEM call” on page 359.
user exit programming interface Note: Using the XPI feature table, you can register a CICS-supplied feature (such as ONC/RPC) to CICS. After it has been registered, you can inquire on the feature, update it, write a trace entry, and deregister it. For details of the XPI feature table, see the CICS External Interfaces Guide. Important 1. You cannot use all of the XPI calls at every global user exit point.
form of an XPI call The general format (omitting the assembler-language continuation character) of all XPI calls is: macro-name [CALL], [CLEAR], [IN, FUNCTION(call_name), mandin1(value), mandin2(value), ... [optin1(value),] [optin2(value),] ...] [OUT, mandout1(value), mandout2(value), ... [optout1(value),] [optout2(value),] ... RESPONSE, REASON] XPI calls follow assembler-language coding conventions: v The “macro-name” must begin before column 16. v The continuation lines must begin in column 16.
form of an XPI call 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.
form of an XPI call the name of a field in which you want the RESPONSE value to be placed. You 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’, ‘INVALID’, ‘KERNERROR’, and ‘PURGED’.
form of an XPI call Note that if an XPI call other than DFHDSSRX SUSPEND or WAIT_MVS gets this RESPONSE, your exit program should set the return code to ‘UERCPURG’ and return to the caller. If a DFHDSSRX SUSPEND or WAIT_MVS call specifies an INTERVAL and gets this RESPONSE with a REASON of ‘TIMED_OUT’, it indicates that the INTERVAL you specified has passed. It is up to you to decide what you do next.
form of an XPI call CICS to perform the XPI call processing. You must not use any of these fields: if you do so, your user exit program will have unpredictable results. The user exit program should be in 31-bit addressing mode. XPI register usage Before you can issue an XPI call from a global user exit program, you must move the contents of the parameter UEPSTACK (the kernel stack entry) of DFHUEPAR to the exit program’s register 13.
form of an XPI call # # to to obtain more than the extra 64 bytes provided, obtain it by either a DFHSMMCX FUNCTION (GETMAIN) macro, or an MVS GETMAIN request. # # # # Information to be kept across invocations of an exit program can be stored in the global work area that you can define for an exit program (or group of exit programs). The 320 bytes of LIFO storage cannot be used for this purpose because it is dynamic.
XPI examples TITLE 'GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI' ************************************************************************* * The first three instructions set up the global user exit * * environment, identify the user exit point, prepare for the use of * * the exit programming interface, and copy in the definitions that * * are to be used by the XPI function.
XPI examples ************************************************************************* * The next seven instructions form the normal start of a global user * * exit program, setting the program addressing mode to 31-bit, saving * * the calling program's registers, establishing base addressing, and * * establishing the addressing of the user exit parameter list.
XPI examples ************************************************************************* * Issue the DFHSMMCX macro call, specifying: * * * * CALL -the macro is to be called immediately * * * * CLEAR -initialize the parameter list before inserting values. * * * * IN -input values follow. * * * * FUNCTION(GETMAIN) -- acquire storage * * GET_LENGTH(120) -- 120 bytes of it * * SUSPEND(NO) -- don't suspend if storage not available * * INITIAL_IMAGE(X'00') -- clear acquired storage * * to hex zero throughout.
XPI examples ************************************************************************* * Test SMMC_RESPONSE -- if OK, then branch round error handling. * ************************************************************************* * * CLI SMMC_RESPONSE,SMMC_OK CHECK RESPONSE AND... BE STOK ...IF OK, BYPASS ERROR ROUTINES * * . . . error-handling routines . . . ************************************************************************** * The next section maps TRANSTOR on the acquired storage.
XPI examples ************************************************************************* * Issue the DFHSMMCX macro call, specifying: * * * * CALL -the macro is to be called immediately. * * * * CLEAR -initialize the parameter list before inserting values. * * * * IN -input values follow. * * * * FUNCTION(FREEMAIN) -- release storage * * ADDRESS((R6)) -- address of storage is in register 6. * * STORAGE_CLASS(USER) -- class of acquired storage was * * 31-bit user storage.
XPI examples 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 You must set your parameters using only the XPI functions. The XPI functions The following sections of the chapter provide details of the individual XPI function calls. The description of each function defines only the options that are specific to that call.
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).
the XPI functions maxlen The maximum data length as {namel | (Rn) | expression}: namel The name of a location containing a binary fullword giving the maximum data length in bytes (Rn) A register, the contents of which specify in fullword binary the maximum number of bytes of data expression A decimal integer, or any arithmetic expression, including symbolic values, valid in assembler language; for example: L'AREA ; L'AREA+10 ; L'AREA+X'22' ; SYMB/3+20 .
dispatcher functions v Issuing the SUSPEND call. 2. Task B performs the action by: v Getting the parameters v Performing the action v Setting the results v Terminating (or waiting for new work). 3. Task A ends the interaction by: v Getting the results left by task B.
dispatcher functions Set parameters; Get parameters; Process request; Clean up 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.
dispatcher functions ADD_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(ADD_SUSPEND), [RESOURCE_NAME(name16 | string | 'string'),] [RESOURCE_TYPE(name8 | string | 'string'),]] [OUT, SUSPEND_TOKEN(name4 | (Rn)), RESPONSE(name1 | *), REASON(name1 | *)] | | RESOURCE_NAME(name16 | string | "string") specifies a 16-character string that can be used to document andtrace the resource involved in suspend and resume processing. You cannot use register notation to specify the address of the string.
dispatcher functions RESPONSE and REASON values for ADD_SUSPEND: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None None None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. The SUSPEND call SUSPEND suspends execution of a running task. The task can be resumed in one of two ways.
dispatcher functions (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 Table 14. Specifying PURGEABLE(NO) tells the dispatcher: v To reject any attempt to PURGE the task. v To suppress the deadlock time-out (DTIMOUT) facility (if applicable to this task) for the duration of this request. Table 14.
dispatcher functions "string" A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string. If you want to document a name (label) in your program, use this form. Notes: 1. CICS does not use the RESOURCE_TYPE information but includes it in trace entries, and displays it on appropriate CEMT screens to help you to see what your task is doing. CICS internal requests specify values, and you should use different values to avoid ambiguity.
dispatcher functions Note: This is the default reason given to the wait if you suspend a task and do not specify the WLM_WAIT_TYPE parameter. OTHER_PRODUCT Waiting on another product to complete its function; for example, when the workload has been passed to DB2. SESS_LOCALMVS Waiting on the establishment of a session in the MVS image on which this CICS region is running. SESS_NETWORK Waiting on the establishment of a session elsewhere in the network (that is, not on this MVS image).
dispatcher functions corresponding RESUME. You must ensure that you keep account of the SUSPEND and RESUME requests issued from your exit program. RESUME DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(RESUME), SUSPEND_TOKEN(name4 | (Rn)), [COMPLETION_CODE(name1 | (Rn)),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] COMPLETION_CODE(name1 | (Rn)) specifies a user-defined “reason for RESUME” code during suspend and resume processing.
dispatcher functions DELETE_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(DELETE_SUSPEND), SUSPEND_TOKEN(name4 | (Rn)),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] SUSPEND_TOKEN(name4 | (Rn) ) specifies a token assigned by the system to identify the SUSPEND/RESUME pair of operations used on the task. name4 The name of a 4-byte field, where the token obtained by an ADD_SUSPEND call has been stored (Rn) A register containing the token value previously obtained.
dispatcher functions WAIT_MVS DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(WAIT_MVS), {ECB_ADDRESS(name4 | (Ra)) | ECB_LIST_ADDRESS(name4 | (Ra)),} PURGEABLE(YES|NO), [INTERVAL(name4 | (Rn)),] [RESOURCE_NAME(name16 | string | 'string'),] [RESOURCE_TYPE(name8 | string | 'string'),]] [TIME_UNIT(SECOND|MILLI_SECOND),] [WLM_WAIT_TYPE,] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] | | ECB_ADDRESS(name4 | (Ra)) specifies the address of the ECB to be waited on.
dispatcher functions Table 15. WAIT_MVS call - RESPONSE(PURGED) REASON TASK_CANCELLED TIMED_OUT CONDITION PURGE FORCEPURGE DTIMOUT INTERVAL PURGEABLE (NO) Canceled Proceeds normally Canceled Proceeds normally PURGEABLE (YES) Proceeds normally Proceeds normally Proceeds normally Proceeds normally Note: A FORCEPURGE always assumes that the user wants the task to be purged, and so overrides the PURGEABLE(NO) option.
dispatcher functions | | | MILLI_SECOND The INTERVAL option specifies the number of milliseconds before timeout. | WLM_WAIT_TYPE(name1) specifies, in a 1-byte location, the reason for suspending the task. This indicates the nature of the task’s wait state to the MVS workload manager. The equated values for the type of wait are as follows: CMDRESP Waiting on a command response. CONV Waiting on a conversation. DISTRIB Waiting on a distributed request.
dispatcher functions RESPONSE and REASON values for WAIT_MVS: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None None None None None TASK_CANCELLED TIMED_OUT Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘TIMED_OUT’ is returned if the INTERVAL expires, or if a deadlock time-out interval expires. 3. ‘TASK_CANCELLED’ means that the task has been canceled by operator action or by an application command.
dispatcher functions literalconst A number in the form of a literal, for example B'00000000', X'FF', X'FCF4', "0" or an equate symbol with a similar value. RESPONSE and REASON values for CHANGE_PRIORITY: RESPONSE OK DISASTER INVALID KERNERROR REASON None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. Dump control functions There are two XPI dump control functions.
dump control functions CALLER(block-descriptor) specifies the source of a system dump request. The information that you supply here appears in the dump header, so you could use it to identify the exit program that initiated the system dump request. For a description of valid block-descriptors, see page 298. DUMPID(name9 | *) returns the dump identifier. name9 The name of a 9-byte field to receive the assigned ID.
dump control functions The TRANSACTION_DUMP call TRANSACTION_DUMP causes a transaction dump to be taken. If the transaction dump code that you supply on input is in the transaction dump code table, the dump may be suppressed and, optionally, a system dump may be taken. For information about the dump table and how it works, refer to the CICS Problem Determination Guide and the CICS System Programming Reference manual. Important There is a restriction in using the XPI early during initialization.
dump control functions and SEGMENT_LIST are mutually exclusive. TCA(NO|YES) specifies whether the task control area (TCA) is to be included in the transaction dump. The default is NO. TERMINAL(NO|YES) specifies whether all terminal storage areas associated with the task are to be included in the transaction dump. The default is NO. TRANSACTION(NO|YES) specifies whether all transaction storage areas associated with the task are to be included in the transaction dump. The default is NO.
dump control functions Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘NOT_OPEN’ means that the CICS dump data set is closed. 3. ‘OPEN_ERROR’ means that an error occurred while a CICS dump data set was being opened. 4. ‘PARTIAL’ means that the transaction dump resulting from this request is incomplete. | | Enqueue domain functions There are two XPI enqueue domain functions. These are the DFHNQEDX macro calls ENQUEUE and DEQUEUE.
enqueue domain functions | | | | | However, as no recovery services are provided for abending global user exits, CICS ensures that any outstanding XPI enqueues are dequeued automatically when the dispatcher task terminates. Note that if the dispatcher task is running a CICS transaction, the dispatcher task terminates when the CICS transaction terminates (whether normally or abnormally).
kernel domain functions | Kernel domain functions The START_PURGE_PROTECTION function The START_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.
kernel domain functions Nesting purge protection calls Note that the START_ and STOP_PURGE_PROTECTION functions can be nested. You should ensure that, if multiple START_PURGE_PROTECTION calls are issued for a task, that the correct number of STOP_PURGE_PROTECTION calls are issued to cancel the purge protection. If you issue two starts and only one stop, purge protection is left on for the current task. For example, for any current task, more than one global user exit program may be driven.
loader functions DEFINE_PROGRAM DFHLDLDX [CALL,] [CLEAR,] [IN, FUNCTION(DEFINE_PROGRAM), PROGRAM_NAME(name8 | string | 'string' ), [EXECUTION_KEY(CICS|USER),] [PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),] [PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),] [REQUIRED_AMODE(24|31|AMODE_ANY),] [REQUIRED_RMODE(24|RMODE_ANY),]] [OUT, [NEW_PROGRAM_TOKEN(name4),] RESPONSE(name1 | *), REASON(name1 | *)] EXECUTION_KEY(CICS|USER) specifies, in conjunction with other program attributes, the type of dynamic storage a
loader functions Table 16. Summary of attributes defining DSA eligibility (continued) EXECUTION_KEY option Reentrant Above or below 16MB line Dynamic storage area (DSA) USER Yes Above ERDSA NEW_PROGRAM_TOKEN(name4) returns the token supplied for the newly-defined program. name4 The name of a location to contain the 4-byte token obtained. PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT) specifies the residency status of the program.
loader functions 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 (LPA), is reentrant, and is protected. TYPE_ANY Either the RPL or the LPA copy of the program may be used, though preference is given to the LPA copy. REQUIRED_AMODE(24|31|AMODE_ANY) specifies the addressing mode of the program.
loader functions 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.
loader functions storage unless deleted. RESIDENT programs must be at least quasireentrant. Any program of PROGRAM_TYPE SHARED has the RESIDENT attribute by default. The DELETE_PROGRAM call has no effect on this type of RESIDENT program. REUSABLE Similar to RESIDENT, except that a REUSABLE program that is not in use can be removed from storage by CICS, for storage optimization reasons.
loader functions 2. A REASON of ‘NO_STORAGE’ with a RESPONSE of ‘EXCEPTION’ means that there was insufficient storage to satisfy this request, and SUSPEND(NO) was specified. 3. A REASON of ‘PROGRAM_NOT_FOUND’ is returned if the program has not been included in the library concatenation, or if the link-edit failed. In such a case, the program is marked as “not executable”; it must be re-linked before it can be successfully acquired.
loader functions RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED REASON PROGRAM_NOT_DEFINED PROGRAM_NOT_IN_USE None None None None Notes: 1. For more detail, refer to the explanation of RESPONSE and REASON in “General form of an XPI call” on page 286. 2. ‘PROGRAM_NOT_DEFINED’ is returned if the program that you name is not known to the system. 3. ‘PROGRAM_NOT_IN_USE’ is returned when the use count for the named program is already zero.
log manager functions Log manager functions There are two XPI log manager functions. These are the DFHLGPAX calls: INQUIRE_PARAMETERS SET_PARAMETERS These calls allow you to inquire upon, and set, the log manager parameter, KEYPOINT_FREQUENCY. The value in this parameter specifies the activity keypoint frequency of the CICS region. The INQUIRE_PARAMETERS call INQUIRE_PARAMETERS returns information about the activity keypoint frequency of the system.
log manager functions SET_PARAMETERS DFHLGPAX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PARAMETERS), [KEYPOINT_FREQUENCY(name4 | (Rn) ),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] KEYPOINT_FREQUENCY(name4 | *) specifies the activity keypointing frequency of the CICS region. Permitted values are 0, or any integer between 200 and 65535 inclusive. name4 The name of a 4-byte location that contains the new frequency value. (Rn) A register that contains the new frequency value.
monitoring functions The user event-monitoring points must be defined in the usual way in the monitoring control table (MCT). For more information about CICS monitoring, read “Chapter 24. CICS monitoring” on page 657. At a user EMP, you can add your own data (up to 256 counters, up to 256 clocks, and a single character string of up to 256 bytes) to fields reserved unconditionally for you in performance class monitoring data records.
monitoring functions DATA2(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 DATA2 variable is an area used as defined by the user EMP definition. v If the MCT user EMP definition contains an MLTCNT option, the DATA2 variable is an area with the number of user count fields to be updated.
monitoring functions expression A valid assembler-language expression that can be expressed in 2 bytes. name2 The name of a 2-byte source of point data (Rn) A register containing the point data in the low-order 2 bytes RESPONSE and REASON values for MONITOR: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None DATA1_NOT_SPECIFIED DATA2_NOT_SPECIFIED POINT_NOT_DEFINED INVALID_DATA1_VALUE INVALID_DATA2_VALUE None None None None Notes: 1.
monitoring functions INQUIRE_MONITORING_DATA DFHMNMNX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_MONITORING_DATA), DATA_BUFFER(buffer-descriptor),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] Important There is a restriction in using the XPI early during initialization. Do not start exit programs that use the XPI functions TRANSACTION_DUMP, WRITE_JOURNAL_DATA, MONITOR, and INQUIRE_MONITOR_DATA until the second phase of the PLTPI. For further information about the PLTPI, refer to “Chapter 4.
program management functions and the DFHPGAQX calls: INQUIRE_AUTOINSTALL SET_AUTOINSTALL. Used with the Loader functions DEFINE_PROGRAM, ACQUIRE_PROGRAM, RELEASE_PROGRAM, and DELETE_PROGRAM, these calls give you a comprehensive set of tools for manipulating programs. (Note, however, that the tokens returned in the NEW_PROGRAM_TOKEN fields of DFHPGISX calls are different from those returned by DFHLDLDX Loader calls. You should not use a token obtained from a DFHPGISX call in a DFHLDLDX call, or vice versa.
program management functions CICS CICS-key NONE The program has not been loaded READ_ONLY Readonly USER User-key. AVAIL_STATUS(DISABLED|ENABLED) returns a value indicating whether the program can be used—that is, whether or not it has been enabled. CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC) returns the EDF status of the program. CEDF When the program is running under the control of the CICS execution diagnostic facility (EDF), EDF diagnostic screens are displayed. NOCEDF EDF diagnostic screens are not displayed.
program management functions ENTRY_POINT(name4) returns the program’s entry point address, as it would be returned by a Loader domain ACQUIRE_PROGRAM call. EXECUTION_KEY(CICS|NOT_APPLIC|USER) returns the key in which CICS gives control to the program, which determines whether the program can modify CICS-key storage. CICS CICS gives control to the program in CICS key.
program management functions 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 PLTPI program. LANGUAGE_DEDUCED(ASSEMBLER|C370|COBOL|COBOL2|LE370| NOT_APPLIC|NOT_DEDUCED|PLI) returns the language deduced by CICS for the program.
program management functions MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM) returns the kind of program resource. NEW_PROGRAM_TOKEN(name4) returns a token that can be used to identify the named program. name4 The name of a location to receive a 4-byte token that identifies this program. If PROGRAM_NAME is specified on the request, NEW_PROGRAM_TOKEN is set to a program token that can be used on subsequent requests for the same program.
program management functions NOT_APPLIC Not applicable. The program is remote. PRIVATE The program is to be loaded from the relocatable program library (RPL). A PRIVATE program need not be reentrant, and is given only limited protection against unauthorized overwriting. The degree of protection depends on the type of dynamic storage area into which the program is loaded (see the description of the PROGRAM_TYPE option of the DEFINE_PROGRAM call).
program management functions RESPONSE and REASON values for INQUIRE_PROGRAM: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None PROGRAM_NOT_DEFINED_TO_LD PROGRAM_NOT_DEFINED_TO_PG ABEND LOCK_ERROR INVALID_PROGRAM_TOKEN None None The INQUIRE_CURRENT_PROGRAM call INQUIRE_CURRENT_PROGRAM returns information about the attributes of the program that is currently running.
program management functions CURRENT_AMODE(24|31) returns the addressing mode which the running program is currently using. CURRENT_CEDF_STATUS(CEDF|NOCEDF) returns the EDF status of the current instance of the program. The value returned is the same as for CEDF_STATUS, which is the EDF status specified on the program definition. See the CEDF_STATUS option of INQUIRE_PROGRAM. CURRENT_ENTRY_POINT(name4) returns the entry point address of the current program.
program management functions RESPONSE and REASON values for INQUIRE_CURRENT_PROGRAM: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None NO_CURRENT_PROGRAM LOCK_ERROR ABEND None None None The SET_PROGRAM call SET_PROGRAM allows you to set selected attributes in the definition of a specified program.
program management functions Note: If the program has been link-edited as reentrant with AMODE(31),RMODE(ANY), the EXECUTION_KEY option is ignored, and it is loaded into the extended readonly DSA (ERDSA). For details of the type of storage allocated for the ERDSA, see the RENTPGM system initialization parameter. EXECUTION_SET(DPLSUBSET|FULLAPI) specifies whether CICS is to link to and run the program as if it were running in a remote CICS region.
program management functions name4 The name of a location containing a 4-byte token obtained from a previous INQUIRE_PROGRAM, INQUIRE_CURRENT_PROGRAM, START_BROWSE_PROGRAM, or GET_NEXT_PROGRAM call. PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY) specifies where the program is to be loaded from. PRIVATE The program is in the relocatable program library (RPL). A PRIVATE program need not be reentrant, and is given only limited protection against unauthorized overwriting.
program management functions RESPONSE and REASON values for SET_PROGRAM: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None CEDF_STATUS_NOT_FOR_MAPSET CEDF_STATUS_NOT_FOR_PTNSET CEDF_STATUS_NOT_FOR_REMOTE EXEC_KEY_NOT_FOR_MAPSET EXEC_KEY_NOT_FOR_PTNSET EXEC_KEY_NOT_FOR_REMOTE EXEC_SET_NOT_FOR_MAPSET EXEC_SET_NOT_FOR_PTNSET EXEC_SET_NOT_FOR_REMOTE PROGRAM_NOT_DEFINED_TO_LD PROGRAM_NOT_DEFINED_TO_PG ABEND CATALOG_ERROR CATALOG_NOT_OPERATIONAL LOCK_ERROR INVALID_MODE_COMBINATION INVALID_P
program management functions 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.
program management functions GET_NEXT_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(GET_NEXT_PROGRAM), BROWSE_TOKEN(name4),] [OUT, PROGRAM_NAME(name8), [ACCESS(CICS|NONE|READ_ONLY|USER),] [AVAIL_STATUS(DISABLED|ENABLED),] [CEDF_STATUS(CEDF|NOCEDF|NOT_APPLIC),] [DATA_LOCATION(ANY|BELOW|NOT_APPLIC),] [ENTRY_POINT(name4),] [EXECUTION_KEY(CICS|NOT_APPLIC|USER),] [EXECUTION_SET(DPLSUBSET|FULLAPI|NOT_APPLIC),] [HOLD_STATUS(CICS_LIFE|NOT_APPLIC|TASK_LIFE),] [INSTALL_TYPE(AUTO|CATALOG|GROUPLIST|MANUAL|RDO|SYSAUT
program management functions NEW_PROGRAM_TOKEN(name4) returns a token that identifies the next definition in the browse sequence. You 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). You can also use it in the PROGRAM_TOKEN field of INQUIRE_PROGRAM and SET_PROGRAM calls. name4 The name of a location to receive a 4-byte token that identifies the next program definition.
program management functions The INQUIRE_AUTOINSTALL call INQUIRE_AUTOINSTALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets.
program management functions SET_AUTOINSTALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_AUTOINSTALL), [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] [LANGUAGES_AVAILABLE(NO|YES),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] AUTOINSTALL_CATALOG(ALL|MODIFY|NONE) specifies the catalog status for autoinstalled program definitions. ALL All autoinstalled program, map, and partitionset definitions are to be cataloged.
state data access functions 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_APPLICATION_DATA call The INQ_APPLICATION_DATA call enables you to inquire on application system data in the AP domain.
state data access functions SYSEIB(name4 | (Rn) | *) returns the address of the system EXEC interface block of the current task. name4 The name of a fullword area that is to receive the address of the system EXEC interface block. (Rn) A register that is to receive the address of the system EXEC interface block. * The parameter list itself, name APIQ_SYSEIB, is used to hold the address. TCTUA(name4 | (Rn) | *) returns the address of the terminal control table user area (TCTUA) for the current task.
state data access functions RESPONSE and REASON values for INQ_APPLICATION_DATA: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED 354 CICS TS for OS/390: CICS Customization Guide REASON None DPL_PROGRAM NO_TRANSACTION_ENVIRONMENT TRANSACTION_DOMAIN_ERROR ABEND LOOP INQ_FAILED INVALID_FUNCTION None None
state data access functions The INQUIRE_SYSTEM call The INQUIRE_SYSTEM call gives you access to CICS system data in the AP domain.
state data access functions 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 Transaction Server under which CICS is running. | | name6 | | | The name of a 6-byte area that is to receive the release characters as hexadecimal values.
state data access functions 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. INITSTATUS(FIRSTINIT|INITCOMPLETE|SECONDINIT|THIRDINIT) returns a value indicating the stage reached during CICS initialization. FIRSTINIT The first stage of CICS initialization. INITCOMPLETE CICS initialization is complete. SECONDINIT The second stage of CICS initialization.
state data access functions 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. PLTPI(name2 | *) returns the suffix that identifies the program list table (PLT) containing the list of programs to be run during CICS initialization—the program list table post initialization (PLTPI) list. name2 The name of a 2-byte area that is to receive the suffix.
state data access functions 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. TIMEOFDAY(name4 | *) returns the current time-of-day in packed decimal form (4-bytes hhmmsstc where hh=hours, mm=minutes, ss=seconds, t=tenths of a second, and c is the sign).
state data access functions SET_SYSTEM DFHSAIQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_SYSTEM), [DTRPRGRM(name8 | string | 'string'),] [GMMLENGTH(name2 | (Rn) | expression),] [GMMTEXT(name8 | (Rn)),]] [OUT, RESPONSE (name1 | * ), REASON (name1 | * )] DTRPRGRM(name8 | string | ’string’) specifies the name of the dynamic routing program. name8 The name of an 8-byte area that contains the name of the dynamic routing program.
storage control functions Storage control functions There are seven XPI storage control functions. These are the DFHSMMCX macro calls GETMAIN, FREEMAIN, INQUIRE_ELEMENT_LENGTH, and INQUIRE_TASK_STORAGE, and the DFHSMSRX calls INQUIRE_ACCESS, INQUIRE_SHORT_ON_STORAGE, and SWITCH_SUBSPACE. DFHSMMCX calls cannot be used in any exit program invoked from any global user exit point in the: v Dispatcher domain v v v v Dump domain Monitor domain Statistics domain Transient data program.
storage control functions GETMAIN DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION(GETMAIN), GET_LENGTH(name4 | (Rn) | expression), STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL), SUSPEND(NO|YES), [INITIAL_IMAGE(name1 | literalconst),] [TCTTE_ADDRESS(name4 | (Ra)),]] [OUT, ADDRESS(name4 | (Rn) | *), RESPONSE(name1 | *), REASON(name1 | *)] ADDRESS(name4 | (Rn) | *) returns the address of the storage obtained by the call.
storage control functions 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 Table 17. Table 17.
storage control functions 2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request was specified with SUSPEND(NO), and there was not enough storage available to satisfy the request. 3. ‘PURGED’ is returned if the GETMAIN request was specified with SUSPEND (YES), there was not enough storage to satisfy the request, and the task was purged. The FREEMAIN call FREEMAIN releases an area of storage that is currently allocated to your exit program.
storage control functions 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_ONLY|USER) returns the access-key of the storage element. CICS CICS-key READ_ONLY Readonly storage USER User-key. ELEMENT_ADDRESS(name4 | (Rn) | *) specifies the address of the storage element.
storage control functions INQUIRE_ELEMENT_LENGTH DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION (INQUIRE_ELEMENT_LENGTH), ADDRESS (name4 | (Rn) | *),] [OUT, ELEMENT_ADDRESS(name4 | (Rn) | *), ELEMENT_LENGTH(name4 | (Rn) | *), RESPONSE (name1 | *), REASON (name1 | *)] ADDRESS(name4 | (Rn) | *) specifies an address that lies within an element of task-lifetime storage of the current task.
storage control functions INQUIRE_SHORT_ON_STORAGE DFHSMSRX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_SHORT_ON_STORAGE),] [OUT, SOS_ABOVE_THE_LINE(NO|YES), SOS_BELOW_THE_LINE(NO|YES), RESPONSE (name1 | *), REASON (name1 | *)] SOS_ABOVE_THE_LINE(NO|YES), returns YES if CICS is currently short-on-storage in any of the DSAs above the 16MB line, and NO if not. SOS_BELOW_THE_LINE(NO|YES), returns YES if CICS is currently short-on-storage in any of the DSAs below the 16MB line, and NO if not.
storage control functions | | | lengths of the elements of task-lifetime storage belonging to either the specified task or, by default, the current task. The lengths returned do not include the leading or trailing check zones. | For a description of a buffer descriptor, see 299. NUMBER_OF_ELEMENTS(name4 | (Rn) | *) returns the number of entries in each of the two buffers, ELEMENT_BUFFER and LENGTH_BUFFER, as a full-word binary value.
trace control function Trace 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 Transient data program. The TRACE_PUT call TRACE_PUT writes a trace entry to the active trace destinations.
trace control function 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 511 (X'100' through X'1FF'). This range is not used in CICS modules, but is reserved for user exits.
transaction management functions name8 The name of an 8-byte location to receive the name of the bridge exit program. BRIDGE_FACILITY_TOKEN(name4) returns a token that contains the address of the bridge facility used by this task. This has the same format as a TCTTE and can be mapped using the DSECT DFHTCTTE. If CONTEXT returns NORMAL, the contents of this field are meaningless. name4 The name of a 4-byte location to receive the token.
transaction management functions 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.
transaction management functions name4 The name of a 4-byte location that is to receive the current number of active user tasks, expressed as a binary value. (Rn) A register to receive the current number of active user tasks, expressed as a binary value. MXT_LIMIT(name4 | (Rn)) returns the current number of the MXT parameter. name4 The name of a 4-byte location that is to receive the maximum number of all user tasks currently allowed, expressed as a binary value.
transaction management functions 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).
transaction management functions name4 The name of a 4-byte location that is to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value. (Rn) A register to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value. PURGE_THRESHOLD(name4 | (Rn)) returns the purge threshold limit for this transaction class.
transaction management functions INQUIRE_TRANDEF DFHXMXDX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TRANDEF), INQ_TRANSACTION_ID(name4 | string | ‘string’),] [OUT, [BREXIT(name8),] [CMDSEC(name1),] [DTIMEOUT(name4 | (Rn)),] [DUMP(name1),] [DYNAMIC(name1),] [INDOUBT(name1),] [INDOUBT_WAIT(name1),] [INDOUBT_WAIT_TIME(name4),] [INITIAL_PROGRAM(name8),] [ISOLATE(name1),] [LOCAL_QUEUING(name1),] [PARTITIONSET(name1),] [PARTITIONSET_NAME(name8),] [PROFILE_NAME(name8),] [REMOTE(name1),] [REMOTE_NAME(name8),] [REMOTE
transaction management functions CMDSEC(name1) returns, in a 1-byte location (name1), a value indicating whether command security checking is required for the transaction. YES Command security checking is required. NO Command security checking is not required. DTIMEOUT(name4) returns the deadlock time-out value for the transaction. name4 The name of a 4-byte location that is to receive the deadlock time-out value, expressed as a binary value.
transaction management functions YES The UOW is to wait, pending recovery from the failure, to determine whether recoverable resources are to be backed out or committed. INDOUBT_WAIT_TIME(name4) returns the length of time, in minutes, after a failure during the in-doubt period, before the transaction is to take the action returned in the INDOUBT field. The returned value is valid only if the unit of work is in-doubt and INDOUBT_WAIT returns YES.
transaction management functions PARTITIONSET(name1) returns, in a 1-byte location (name1), the partitionset specified on the transaction definition. KEEP The reserved name KEEP is specified for the partitionset, which means tasks running under this transaction definition use the application partitionset for the terminal associated with the transaction. NAMED The partitionset is named specifically on the transaction definition. The name is returned on the PARTITIONSET_NAME parameter.
transaction management functions RESSEC(name1) returns, in a 1-byte location (name1), a value indicating whether resource security checking is required for the transaction. NO Resource security checking is not required. YES Resource security checking is required. RESTART(name1) returns, in a 1-byte location (name1), a value indicating whether the transaction is to be considered for transaction restart. NO The transaction cannot be restarted. YES The transaction can be restarted.
transaction management functions DISABLED The transaction definition is disabled. ENABLED The transaction definition is enabled. STORAGE_CLEAR(name1) returns, in a 1-byte location (name1), a value indicating whether task-lifetime storage, of tasks associated with this transaction definition, is to be cleared before it is freed by a FREEMAIN command. NO Task-lifetime storage need not be cleared before it’s freed. YES Task-lifetime storage must be cleared before it’s freed.
transaction management functions TCLASS_NAME(name8) returns the name of the transaction class to which the transaction belongs. name8 The name of an 8-byte location to receive transaction class name to which the transaction belongs. TPURGE(name1) returns, in a 1-byte location (name1), a value indicating whether the transaction is defined as purgeable in the event of a VTAM terminal error. NO The transaction can not be purged if a terminal error occurs.
transaction management functions (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 OK EXCEPTION INVALID DISASTER PURGED REASON None UNKNOWN_TRANSACTION_ID None LOGIC_ERROR None The INQUIRE_TRANSACTION call The INQUIRE_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to obtain information about a transaction that is attached (task).
transaction management functions The descriptions of the following parameters are the same as the corresponding parameters on the INQUIRE_TRANDEF function call. DTIMEOUT DYNAMIC INITIAL_PROGRAM REMOTE REMOTE_NAME REMOTE_SYSTEM RESTART SPURGE STATUS TCLASS TRAN_ROUTING_PROFILE TRANSACTION_ID The parameter descriptions that follow explain briefly the possible values that can be returned on an INQUIRE_TRANSACTION call.
transaction management functions ORIGINAL_TRANSACTION_ID(name4) returns the transaction id that was used to attach the transaction. For example, if an alias was used at a terminal, this field returns the alias. name4 The name of a 4-byte location to receive the name of the original transaction identifier. OUT_TRANSACTION_TOKEN(name8) returns the token that represents the task. name8 The name of an 8-byte location to receive the transaction token for the task.
transaction management functions T A terminal input attach. TT A permanent transaction terminal attach. SUSPEND_TIME(name4 | (Rn)) returns the length of time that the task has been in its current suspended state. name4 The name of a 4-byte location to receive the number of seconds, rounded down, the task has been suspended, expressed as a binary value. (Rn) A register to receive the number of seconds, rounded down, the task has been suspended, expressed as a binary value.
transaction management functions RESPONSE and REASON values for INQUIRE_TRANSACTION: RESPONSE OK DISASTER INVALID EXCEPTION KERNERROR REASON None ABEND LOOP None NO_TRANSACTION_ENVIRONMENT BUFFER_TOO_SMALL INVALID_TRANSACTION_TOKEN None The SET_TRANSACTION call The SET_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to change the task priority and transaction class of the current task.
transaction management functions RESPONSE and REASON values for SET_TRANSACTION: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR REASON None NO_TRANSACTION_ENVIRONMENT UNKNOWN_TCLASS INVALID_TRANSACTION_TOKEN ABEND LOOP None None User journaling function There is one XPI user journaling function, which is the DFHJCJCX call WRITE_JOURNAL_DATA.
user journaling function WRITE_JOURNAL DATA DFHJCJCX [CALL,] [CLEAR,] [IN, FUNCTION(WRITE_JOURNAL_DATA), FROM(block-descriptor), JOURNALNAME(name8 | string | 'string' ) | JOURNAL_RECORD_ID(name2 | string | 'string'), WAIT(YES|NO), [RECORD_PREFIX(block-descriptor),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] Important There is a restriction in using the XPI early during initialization.
user journaling function RESPONSE and REASON values for WRITE_JOURNAL_DATA: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None IO_ERROR JOURNAL_NOT_FOUND JOURNAL_NOT_OPEN LENGTH_ERROR STATUS_ERROR None None None 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.
392 CICS TS for OS/390: CICS Customization Guide
Chapter 4. Writing initialization and shutdown programs You 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 (PLT). Information about how to code the PLT is provided in the CICS Resource Definition Guide. The chapter is divided into the following sections: 1. “Initialization programs” 2. “Shutdown programs” on page 394 3. “General considerations” on page 396.
initialization programs system initialization parameter. The autoinstall user program is not invoked to allow the definitions to be modified. The programs are defined with the following attributes: LANGUAGE(Assembler) RELOAD(No) STATUS(Enabled) CEDF(No) DATALOCATION(Below) EXECKEY(CICS) EXECUTIONSET(Fullapi) If any of the default attributes are unsuitable, you must define the programs statically (by defining entries in the CSD and installing the definitions).
shutdown programs First phase PLT programs Programs that are to execute during the first quiesce stage of CICS shutdown are specified in the first half of the PLT (before the DFHDELIM statement). You must define first stage PLTSD programs to CICS. You can either define the programs statically, or use program autoinstall.
shutdown programs v On an immediate shutdown, CICS does not allow running tasks to finish and backout is not performed until emergency restart. This can cause an unacceptable number of units of work to be shunted, and locks to be retained unnecessarily. The purpose of the shutdown assist transaction is to help solve these problems; that is, to ensure that as many tasks as possible commit or back out cleanly within a reasonable time.
PLT programs—general However, if a PLT-defined shutdown program itself passes control to another program (via a link or transfer-control command), the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition. Important You are strongly recommended to specify EXECKEY(CICS) when defining both PLT programs and programs to which a PLT program passes control.
PLT programs—general 398 CICS TS for OS/390: CICS Customization Guide
Part 3. Customizing with user-replaceable programs © Copyright IBM Corp.
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. You can modify the supplied program by including your own logic, or replace it with a version that you write yourself. The chapter is divided into the following sections: 1.
notes about user-replaceable programs Assembling and link-editing user-replaceable programs The source for the CICS-supplied user-replaceable programs is installed in the CICSTS13.CICS.SDFHSAMP library. If you intend changing any of these programs, take a copy of the CICSTS13.CICS.SDFHSAMP library and update the copy only. If the original SDFHSAMP is serviced, and a user-replaceable program is modified, you may like to reflect the changes in your own version of the code.
notes about user-replaceable programs Notes: 1 This job stream uses the CICS-supplied procedure DFHASMVS to assemble and link-edit user-replaceable programs. The DFHASMVS procedure refers to the MVS library SYS1.MODGEN. If you have not yet restructured MVS/ESA (moving members from SYS1.AMODGEN to SYS1.MODGEN), change the SYS1.MODGEN reference to SYS1.AMODGEN in the DFHASMVS procedure, until you have restructured MVS/ESA. When you have restructured MVS/ESA, you must return the SYS1.
notes about user-replaceable programs 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.
notes about user-replaceable programs Link-edit statements for DFHZATDX. ORDER DFHEAI this CSECT is in SDFHLOAD(DFHEAI) ORDER DFHZATDX this CSECT is in USERTEXT(DFHZATDX) ORDER DFHEAI0 this CSECT is in SDFHLOAD(DFHEAI0) INCLUDE SDFHLOAD(DFHEAI) INCLUDE USERTEXT(DFHZATDX) INCLUDE SDFHLOAD(DFHEAI0) MODE AMODE(31),RMODE(ANY) NAME DFHZATDX(R) Link-edit statements for DFHDYP.
notes about user-replaceable programs program, the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition. Important You 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. The CICS-supplied default program error program (DFHPEP) contains code to: v Obtain program addressability v Access the communication area v Return control to CICS through an EXEC CICS RETURN command.
the program error program v The program status word (PSW) at the time of the (current) abend, at PEP_COM_PSW. The full contents of PEP_COM_PSW are significant for abend codes ‘ASRA’, ‘ASRB’, and ‘ASRD’ only; the last four characters (the PSW address) apply also to code ‘AICA’. v The GP registers (0-15) at the time of the (current) abend, at PEP_COM_REGISTERS. v The execution key of the program at the time it suffered the (current) abend, at PEP_COM_KEY.
the program error program DFHEISTG DSECT , * * Insert your own storage definitions here * DFHPCOM TYPE=DSECT *********************************************************************** * * * * * P R O G R A M E R R O R * * * * * * * * * * P R O G R A M * * * * * *********************************************************************** DFHPEP CSECT PROGRAM ERROR PROGRAM CSECT DFHPEP RMODE ANY DFHREGS , EQUATE REGISTERS XR R1,R1 ICM R1,B'0011',EIBCALEN Get Commarea length BZ RETURNX ...
the program error program * * Debugging information (program, PSW, registers and execution key at * time of abend, hit storage indicator). If the abend occurred in a * DPL server program running remotely, only program is meaningful.
Chapter 7. Writing a transaction restart program The transaction restart user-replaceable program (DFHREST) enables you to participate in the decision as to whether a transaction should be restarted or not. CICS invokes DFHREST when a transaction abends, if RESTART(YES) is specified in the transaction’s resource definition (the default is RESTART(NO)).
the transaction restart program All the following conditions must be true for CICS to invoke the transaction restart program: v A transaction must be terminating abnormally. v The transaction abend which caused the transaction to be terminating abnormally must have been detected before the commit point of the implicit syncpoint at the end of the transaction has been reached. v The transaction must be defined as restartable in its transaction definition.
the transaction restart program XMRS_WRITE Indicates, in a 1-byte field, whether the transaction has issued any terminal write requests. The equated values for this parameter are: XMRS_WRITE_YES Means a terminal write has been performed by the transaction. XMRS_WRITE_NO Means a terminal write has not been performed by the transaction. XMRS_SYNCPOINT Indicates, in a 1-byte field, whether the transaction has performed any syncpoints.
the transaction restart program The CICS-supplied transaction restart program The CICS-supplied default transaction restart program requests that the transaction be restarted if: 1. The transaction has not performed a terminal read (other than reading the initial input data), terminal write or syncpoint, and 2. The restart count is less than 20 (to limit the number of restarts), and 3.
Chapter 8. Writing a terminal error program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. This chapter contains information about the CICS terminal error program (TEP), which handles error conditions for devices that use the TCAM DCB interface or the sequential access method.
background When an abnormal condition occurs When an abnormal condition associated with a particular terminal or line occurs, the terminal control program puts the terminal out of service and passes control to the terminal abnormal condition program (DFHTACP) which, in turn, passes control to a version of the terminal error program (DFHTEP, either CICS-supplied or user-written), so that it can take the appropriate action.
background DFHTEP module and tables by means of the DFHTEPM and DFHTEPT macros, respectively. You can select the appropriate options in this sample program, and you can base your own version on it. There is a description of the CICS-supplied sample terminal error program (DFHXTEP), and advice about how to generate a user-written version, later in this chapter. Note: If DFHTEP abends, then the default actions specified in DFHTACP are reinstated.
the sample terminal error program the operating environment by selecting the appropriate generation options and variables. Because each error condition is processed by a separate routine, you can replace a CICS-provided routine with a user-written one when the sample TEP is generated. Components of the sample terminal error program The sample terminal error program consists of the terminal error program itself and two terminal error program tables: v The TEP error table v The TEP default table.
the sample terminal error program You 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. SYMBOLIC TERMINAL ID . . . ERROR STATUS ELEMENT . . . . . . COMMON ERROR BUCKET Figure 17.
the sample terminal error program 1. 2. 3. 4. 5. Entry and initialization Terminal identification and error code lookup Error processor selection Error processing execution General exit 6. Common subroutines. These areas are described in detail in the sections that follow. Figure 18 on page 423 gives an overview of the structure of the sample terminal error program. Entry and initialization On entry, the sample TEP uses DFHEIENT to establish base registers and addressability to EXEC Interface components.
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. Subroutines are provided in the sample TEP to maintain count and time threshold totals for each error associated with a particular terminal to assist the error processor to make its decision.
the sample terminal error program TEPPUTTD Used to output character or hexadecimal data to a user-defined transient data destination. TEPTMCHK Used by TEPINCR to determine whether the time threshold has been passed. TEPWGHT Used to update the weight/time threshold values maintained in the terminal’s error status elements.
the sample terminal error program DFHTACP Entry and initialization Terminal ID and error code lookup Error processing selection Error processor Error processor ... Error processor General exit Error processor Common subroutine DFHTACP Figure 18.
the sample terminal error program six types, each identified by a unique message prefix. You can control the selection of each type of message by using the appropriate parameters specified on the PRINT operand of DFHTEPM TYPE=INITIAL. These messages are: DFHTEP, ERROR – error text During DFHTEP module generation, the PRINT parameter specified ERRORS. This message can be suppressed by using the NOERRORS option.
the sample terminal error program This message contains the symbolic terminal ID of the device associated with the error. This message can be suppressed by using the NOTID option. DFHTEP, DECB - DECB information During the DFHTEP module generation, the PRINT parameter specified DECB. This two-line message contains the DECB (printed in hexadecimal format) of the terminal causing the error. The DECB is contained in the TACLE (displacement +16 [decimal]).
the sample terminal error program 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.
the sample terminal error program This macro indicates the end of user storage definitions. Its use is mandatory if DFHTEPM TYPE=USTOR has been coded. If you use DFHTEPM TYPE=USTOR to define storage, then both it and DFHTEPM TYPE=USTOREND must be coded before DFHTEPM TYPE=INITIAL.
the sample terminal error program NOEXITS No branches are taken to user routines. TIME|NOTIME specifies whether threshold tests are to be controlled over prescribed time intervals. An example might be putting a terminal out of service if more than three instances of a given type of error occur in one hour. The parameter must be the same as the OPTIONS operand in the DFHTEPT TYPE=INITIAL macro. TIME This type of threshold testing is supported. NOTIME This type of threshold testing is not supported.
the sample terminal error program TID|NOTID specifies whether the symbolic terminal ID of the terminal associated with an error is to be recorded on the transient data destination. TID The terminal ID is to be logged. NOTID No terminal IDs are to be logged. DECB|NODECB specifies whether the DECB of the line associated with error is to be recorded on the transient data destination. DECB The DECB is logged. The hexadecimal representation of the DECB is logged as two 24-byte messages.
the sample terminal error program The macro required for a user “ENTRY” routine is: DFHTEPM TYPE=ENTRY This macro must be immediately followed by user “ENTRY” routine code, starting with the label “TEPENTRY” and ending with a BR 14 instruction. The macro required for a user “EXIT” routine is: DFHTEPM TYPE=EXIT This macro must be immediately followed by user “EXIT” routine code, starting with the label “TEPEXIT” and ending with a BR 14 instruction.
the sample terminal error program to be logged to the TEPQ transient data destination. The CICS DSECTs are not printed on the sample DFHTEP assembler-language listing. There are two error processor routines (codes ‘87’ and ‘9F’ respectively).
the sample terminal error program DFHTEPT–generating the sample DFHTEP tables The following macros are required to generate the terminal error program tables: v DFHTEPT TYPE=INITIAL—to establish the control section. v DFHTEPT TYPE=PERMTID—to define permanently reserved terminal error blocks (TEBs) for specific terminals. v DFHTEPT TYPE=PERMCODE|ERRCODE—to define permanently reserved error status elements (ESEs).
the sample terminal error program NOTIME Time 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: DFHTEPT TYPE=PERMTID ,TRMIDNT=name TYPE=PERMTID defines permanently reserved terminal error blocks for specific terminals.
the sample terminal error program CODE={errcode|BUCKET} identifies the error code referred to by the TYPE=PERMCODE|ERRCODE parameter. These codes are listed in Figure 22 on page 443. CODE=BUCKET is only applicable to the DFHTEPT TYPE=ERRCODE macro. It is used to override the default threshold constants established for the common error bucket. COUNT=number can be used in either the DFHTEPT TYPE=PERMCODE or TYPE=ERRCODE macro to override the sample DFHTEP default count threshold (see Table 20 on page 435).
the sample terminal error program number The interval in units of one hundredth of a second. Parentheses are not required if this method is used. The maximum number must be less than 8 640 000 (24 hours). (number,SEC) The interval in whole seconds, which must be enclosed in parentheses. The maximum number must be less than 86 400 (24 hours). (number,MIN) The interval in whole minutes, which must be enclosed in parentheses. The maximum number must be less than 1440 (24 hours).
the sample terminal error program 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: DFHTEPT TYPE=BUCKET ,CODE=errcode TYPE=BUCKET generates the macro to account for specific error conditions in the common error bucket. If MAXERR=25 on the DFHTEPT TYPE=INITIAL macro, this macro cannot be used.
the sample terminal error program * TABLE SPECIFICATIONS DFHTEPT TYPE=INITIAL,MAXTIDS=10, MAXERRS=5 * PERMANENT TERMINAL DEFINITIONS DFHTEPT TYPE=PERMTID,TRMIDNT=TM02 * PERMANENT ERROR CODE DEFINITIONS DFHTEPT DFHTEPT TYPE=PERMCODE,CODE=81 TYPE=PERMCODE,CODE=87, COUNT=2,TIME=(1,MIN) * OTHER THRESHOLD OVERRIDES DFHTEPT TYPE=ERRCODE,CODE=BUCKET, COUNT=3,TIME=(3,MIN) * CONCLUDE TABLE GENERATION DFHTEPT END TYPE=FINAL Figure 20.
user-written terminal error programs Table 21. Supplied source files and macros (continued) Name DFHTEPCA Type Macro Description Assembler-language communication area Library CICSTS13.CICS.SDFHMAC The user-written DFHTEP receives control in the same manner as the CICS-supplied sample DFHTEP, described in “The communication area” on page 417. It should therefore use the communication area as its basic interface with DFHTACP.
user-written terminal error programs You generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program. The layout of the communication area is shown in Figure 21.
user-written terminal error programs SIGNOFF (X'02') Call sign-off program. On entry to DFHTEP, the above flags represent the default actions set by DFHTACP. The write-abend bit (communication area field ABORTWR) and the abend-task bit (communication area field ABENDT) are always set if the place-line-out-of-service bit (X'80') is set; but both bits are suppressed if “dummy terminal” is indicated (see Resetting the flags in the user action byte, TEPCAACT).
user-written terminal error programs and DFHTACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message to CSMT; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or, rarely, ‘AEXZ’. v Abend write has no effect if the TCTTE was associated with a READ request. In this case the normal result is that, if the line and terminal remain in service, the read is retried.
user-written terminal error programs L TCTTEAR,TCTLEPTE USING DFHTCTTE,TCTTEAR DROP TCTLEAR L TCTLEAR,TCTTELEA USING DFHTCTLE,TCTLEAR POINT TO ERROR TCTTE POINT TO TCTLE After you have carried out the required functions and, optionally, altered the default actions scheduled by DFHTACP, the user-written DFHTEP must return control to DFHTACP by issuing the EXEC CICS RETURN command. DFHTACP then performs the actions specified in the TACLE and causes the error processing task to terminate.
user-written terminal error programs TERMINAL ABNORMAL CONDITION LINE ENTRY Dec 0 4 BYTES Hex 0 TCTLEPSA STORAGE ACCOUNTING AREA 4 4 RESERVED 8 8 TCTLEPFL TCTLEPF2 NOT USED ERROR FLAGS 12 SPECIAL IND C TCTLEPTE TCTTE ADDRESS 16 10 TCTLEECB BEGINNING OF DECB 20 14 24 18 TCAM RETURN CODE RESERVED FOR DFHTACP TCTLEDCB ACTUAL LINE ENTRY ADDRESS 28 1C 44 2C TCTLECSW NOT USED BSAM STATUS 48 30 TCTLEALP BSAM SENSE 60 3C TCTLEOA Figure 22.
user-written terminal error programs Displacement Dec Hex 0 0 Code Bytes Label Meaning 4 Storage accounting TCTLEPSA RESERVED 8 8 1 81 TCTLEPFL 84 85 87 88 8C 8D 8E 8F 94 95 TCT search error Write not valid Unsolicited input Input event rejected Output event rejected Output length of zero No output area Output area exceeded Unit check Unit check (should not occur) Unit exception Unit exception (should not occur) Undetermined I/O error Invalid destination (TCAM) 96 97 99 9F . . . .
user-written terminal error programs Example of a user-written terminal error program The “DFHTEP recursive retry routine” on page 446 is an example of the logic steps necessary to design a portion of the terminal error program. In Figure 23 on page 446, 10 retries are provided for each terminal; however, the logic could be used for any number of retries. The following assumptions are made: USER FIELD A (PCISAVE) represents a 6-byte field in the process control information (PCI) area of the TCTTE.
user-written terminal error programs DFHTEP recursive retry routine *ASM XOPTS(NOPROLOG NOEPILOG SP) ************************************************************************ * * * DFHTEP RECURSIVE RETRY ROUTINE * * * ************************************************************************ DFHEISTG DFHEIEND DFHTEPCA TYPE=DSECT COMMAREA passed by TACP COPY DFHA06DS Statistics DSECT USING DFHA06DS,STATBAR PCIAREA DSECT PCISAVE DS XL6 User Field A PCICNT DS PL2 User Field B * TCTLEAR EQU 2 Pointer to TACLE STA
* * * * * INCR * * * * * * * * * CKCOUNT * * * * * * * * RETRY * * * * NORETRY * * * * * EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) Get statistics for this terminal using TERMID passed in Commarea MVC PCISAVE,A06TENI DS AP 0H PCICNT,=P'1' CP PCICNT,=P'10' BNE RETRY ZAP PCICNT,=P'0' MVC B PCISAVE,A06TENI NORETRY Save the current system counts. This is a new error, or first time through.
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 Transaction Server for OS/390 Release 3. Node error programs, not terminal error programs, must be used for terminals and logical units supported via the ACF/VTAM interface.
background to VTAM error handling Background to CICS-VTAM error handling In general, errors detected by CICS-VTAM terminal control are queued for handling by a special task, the CICS node error handler (transid CSNE). (Note that CICS finds it convenient to use the same technique for some housekeeping work, such as sending “good morning” messages, and logging session starts and ends, which are not errors at all.
background to VTAM error handling v There could be application-related activity to be performed when a node error occurs. For example, if a message fails to be delivered to a terminal, it may need redirecting to another. With messages sent with exception-response only, CICS may not have the data available to send it again, but the requesting application might be able to re-create it.
background to VTAM error handling v Status changes (for example, of TCTTE) v Clean-up work (cancel any associated transaction, end the VTAM session). The action flags can be set or reset within DFHZNEP. The action flags set by DFHZNAC for specific error codes and sense codes are listed in “Appendix B. Default actions of the node abnormal condition program” on page 789.
background to VTAM error handling 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. You can give the table any name you like. The default is DFHNET. The table consists of sets of error-recording areas. Each set is called a node error block (NEB) and is used to count node errors relating to a single LU.
background to VTAM error handling The initial code first tests the internal error code passed from DFHZNAC to see if it belongs to a group that the NEP needs to handle. (The groups are identified by the code you supply between the DFHSNEP INITIAL and FINAL macros. This is described in “Generating the sample node error program” on page 469.) If the particular error code is not of interest to the NEP, control is returned at once to DFHZNAC, to take default actions.
background to VTAM error handling The code for non-SNA 3270s can be generated by coding DFHSNEP TYPE=DEF3270 where you would otherwise code a DFHSNEP TYPE=ERRPROC macro plus logic of your own. In effect, TYPE=DEF3270 defines two error groups, and associates each with an error processor. The first group comprises the four DFHZNAC error codes X'D9', X'DC', X'DD', and X'F2'.
background to VTAM error handling The DFHZNEPI macros (see “DFHZNEPI macros” on page 478) generate a DFHZNEP module that is purely a routing module. This inspects the NEPCLASS in effect for the node error passed by DFHZNAC, and transfers control (links) to another module, the real NEP, according to a NEPCLASS/name routing table built up by the macros. If no NEPCLASS is in effect (equivalent to CEDA DEFINE PROFILE NEPCLASS(0)), or the NEPCLASS is not in the routing table, a default module is invoked.
when an abnormal condition occurs 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 VTAM section: DFHZCA, DFHZCB, DFHZCC, DFHZCP, DFHZCQ, DFHZCW, DFHZCX, DFHZCY, and DFHZCZ. v The node abnormal condition program, DFHZNAC. v The CICS-supplied default node error program, DFHZNEP, or your own version of it.
when an abnormal condition occurs When control is returned from DFHZNEP, DFHZNAC performs the actions specified in field TWAOPTL (except when disconnecting logical units, as noted above), issuing messages and setting error codes, as necessary. The communication area After DFHZNEP receives control from DFHZNAC, it obtains the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command. Figure 24 illustrates the general structure of the communication area.
when an abnormal condition occurs ********************************************************************** ** Header ** ** These fields are READ ONLY ** ********************************************************************** NEPCAHDR DS 0XL4 Standard Header NEPCAFNC DS XL1 Function Code Always '1' NEPCACMP DS XL2 Component Code Always 'ZC' DS XL1 Reserved ********************************************************************** ** Error_being_processed ** ** Identity of terminal and the error code associated with
when an abnormal condition occurs ********************************************************************** ** VTAM information Any VTAM sense and RPL codes ** ** These fields are READ ONLY ** ********************************************************************** TWAVTAM DS 0XL12 VTAM information TWARPLCD DS H VTAM RPL feedback codes DS H Reserved TWASENSS DS 0F Sense codes to be sent TWASS1 DS XL1 System sense byte No 1 TWASS2 DS XL1 System sense byte No 2 TWAUS1 DS XL1 User sense byte No 1 TWAUS2 DS XL1 User
when an abnormal condition occurs ********************************************************************** ** Additional system parameters ** **Except for TWAPNETN, TWAPNTID, TWAUPRRC these fields are READ ONLY** ********************************************************************** TWASYSPM DS 0XL68 TWATCTA DS AL4 Address of TCTTE being processed TWARPL DS AL4 Address of VTAM RPL TWATIOAA DS AL4 Address of data portion of TIOA TWATIOAL DS H Length of data portion of TIOA TWACOMML DS H Length of commarea data
when an abnormal condition occurs 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 (TWAODNTA) 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 TWAOAT in TWAOPT2 is also set on.
when an abnormal condition occurs TWAOGMM (X'08') “good morning” message to be sent TWAOPBP (X'04') Purge any BMS pages for this session TWAOASM (X'02') SIMLOGON required. Notes: 1. If a definite response SEND has been performed, CICS has to issue a RECEIVE in order to obtain the response. If the response is negative, DFHZNAC is entered and sets flags TWAOAS (abandon the SEND) and TWAOAR (abandon the RECEIVE). TWAOAR must be left on to ensure that the RECEIVE for the response is abandoned. 2.
when an abnormal condition occurs TWAOOS 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, TWAOOS or TWAONINT causes the system entry to be put out of service if, as a result of the specified action, there are no allocatable sessions left.
when an abnormal condition occurs 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=PASS request is in progress by examining field TWAPFLG for the pass-in-progress indicator, TWAPIP. The success or failure of the CLSDST OPTCD=PASS request can be determined by examining the error code at TWAEC.
the sample node error program v A general environment within which your error processing programs can be added v The default node error program in a system that has several node error programs. The CICS-supplied sample node error program is described in greater detail below. Compatibility with the sample terminal error program Receipt of sense or status codes corresponds to error codes X'D9', X'DC', X'DD', and X'F2'. Weighted counts of these messages are maintained against numeric and time thresholds.
the sample node error program Routing mechanism The routing mechanism invokes the appropriate error processor depending on the error code provided by the node abnormal condition program. Groups of one or more error codes are defined in the DFHSNEP macro (see below). Each group is associated with an index (in the range X'01' through X'FF') and an error processor. A translate table is generated and the group index is placed at the appropriate offset for each error code.
the sample node error program Node Error Table Node Error Block NODE ERROR TABLE HEADER NODE ERROR BLOCK HEADER NODE ERROR BLOCK ERROR STATUS BLOCK PERMANENTLY ASSIGNED NEBs ESBs DYNAMICALLY ASSIGNED NEBs Figure 26. Format of node error table and node error block 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.
the sample node error program with an IC PUT command. Otherwise the default actions are taken. (For more details, see the section “Coding for the 3270 ‘unavailable printer’ condition” on page 476.) Optional error processor for interactive logical units Only one error processor is supplied for interactive LUs: group index 1, with error code X'DC'. This error code, in combination with a user sense value of X'081B', indicates a ‘receiver in transmit mode’ condition.
the sample node error program DFHSNEP TYPE=USTOR 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 DFHSNEP TYPE=USTOR your storage definitions, and then by DFHSNEP TYPE=USTOREND. If you use DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL.
the sample node error program TYPE=DEF3270 specifies that the CICS-supplied error processors for 3270 logical units are to be included in the node error program. This macro causes the following source code to be generated: DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=(D9,DC,DD,F2) Sense/status error processor code. DFHSNEP TYPE=ERRPROC,GROUP=2,CODE=42 Unavailable printer error processor code.
the sample node error program GROUP=error-group-index specifies an error group index for the error processor. This index is used to name the error processor, locate its address from the error processor vector table (EPVT), and optionally associate it with an ESB in each NEB. The index specified must be a 2-character representation of a 1-byte hexadecimal number in the range X'01' through X'FF' (a leading zero can be omitted).
the sample node error program 4. Registers 4 through 9 can be saved by common subroutines in an area reserved in EXEC interface storage at label NEPCSRS. They must be restored before return from the subroutines. DFHSNET—generating the node error table The DFHSNET macro is used to generate a node error table. Each node error table that you generate must be defined to CICS.
the sample node error program TIME=(7,MIN)|(interval,units) specifies the time interval that is to be stored in the NET header for use by the common subroutines to maintain error counts in standard ESBs. If the threshold specified in the COUNT operand is not exceeded before this time interval elapses, the error count is reset to 0. Specify “units” as SEC, MIN, or HRS. The maximum values for “interval” are as follows: (86400,SEC), (1440,MIN), or (24,HRS).
the sample node error program DFHNEPC CSVTNEP CSVTESBL CSVTNEBD CSVTECUP DSECT DS DS DS DS DS DS F F A A A A Load instruction Branch instruction Node error program base address NEPESBL - ESB locate routine NEPNEBD - NEB delete routine NEPECUP - error count update routine User-written node error programs You can write your own NEP in any of the CICS-supported languages. However, CICS-supplied NEP code is provided in assembler language only.
user-written node error programs v Updates to recoverable resources. If the resources are locked by another task, the CSNE unit of work could be suspended or shunted. You should also note that you cannot use the NEP to suppress DFHZNAC messages. Entry and addressability On entry, your NEP should issue the commands: EXEC CICS ADDRESS COMMAREA EXEC CICS ADDRESS EIB These commands provide addressability to the communication area passed by DFHZNAC, and to the EXEC interface block, respectively.
user-written node error programs 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.
user-written node error programs If used in this way, the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however, that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened. Refer to “Restrictions on the use of EXEC CICS commands” on page 475.
user-written node error programs 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. DFHZNEPI TYPE=INITIAL [,DEFAULT=name] DEFAULT=name specifies the name of the default transaction-class routine to be used.
user-written node error programs | 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.
the node error program and XRF One of the steps in the conversation-restart process is to link to the node error program with error code X'3F'. If you want to be able to change any of the system-wide recovery notification options (whether terminal users are notified of a recovery, the recovery message, or the recovery transaction) for some terminals, you should write your own error processor to handle code X'3F'.
the node error program and XRF notification that service has been restored. To achieve this, you could code RECOVNOTIFY(MESSAGE) in the TYPETERM definition, and then use the node error program to change the recovery notification to NONE for the relatively few terminals that are not to be notified. Changing the recovery message If you define a terminal with RECOVNOTIFY(MESSAGE) in its TYPETERM definition, a recovery message is sent to the terminal after takeover.
the node error program and generic resources specific TOR within the CICS generic resource group, you must specify LUNAME as the member name—that is, the CICS APPLID, as in the first example.) Note that, if the system that issues an ISSUE PASS LUNAME(grname) command is the only CICS currently registered under the generic resource name (for example, the others have all been shut down), the ISSUE PASS command does not fail with an INVREQ.
484 CICS TS for OS/390: CICS Customization Guide
Chapter 10. Writing a program to control autoinstall of terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. This chapter describes how to write a program to control the automatic installation of locally-attached VTAM terminals (including APPC single-session devices).
the autoinstall control program for terminals For an overview of autoinstall, see the CICS Resource Definition Guide. You should also read the sections in the same manual that describe the CEDA commands that create the environment in which your control program can work. If you choose automatic installation for some or all of your terminals, you must: v Create some model TERMINAL definitions. v Define the terminals to VTAM, so that their definitions in VTAM match the model TERMINAL definitions in CICS.
the autoinstall control program for terminals Using model terminal support (MTS) CICS Transaction Server for OS/390 supports the model terminal support (MTS) function of VTAM 3.3 and above. Using MTS, you can define the model name, the printer (PRINTER), and the alternate printer (ALTPRINTER) for each terminal in a VTAM table. This information is sent by VTAM in an extended CINIT RU. CICS captures it as part of autoinstall processing at logon, and uses it to create a TCTTE for the terminal.
the autoinstall control program for terminals described in “The communications area at INSTALL for shipped terminals” on page 526 . The parameter list passed at INSTALL of client virtual terminals is described in “The communications area at INSTALL for Client virtual terminals” on page 534. The parameter list passed at INSTALL of MVS consoles is described in “Chapter 11. Writing a program to control autoinstall of consoles” on page 505.
the autoinstall control program for terminals For example, if a 3270 printer attempts to autoinstall, the subset of matching models includes all the types in VTAM category 2 that you have defined as models. This subset could include any of the following: v v v v v v DEVICE(3270) TERMMODEL(2) DEVICE(3270) TERMMODEL(1) DEVICE(3270P) TERMMODEL(2) DEVICE(3270P) TERMMODEL(1) DEVICE(3275) TERMMODEL(2) DEVICE(3275) TERMMODEL(1).
the autoinstall control program for terminals 'FO' Z C Fullword 2 LL LL nn nn Netname Fullword 3 Fullword 4 Autinstmodelname_1 Fullword 5 Autinstmodelname_n LL LL Cinit_RU Modelname i/o i/o i/o i/o i/o i/o i/o i/o Terminal ID Printer ID Altprinter ID Return code Note: i/o Printer NETNAME i/o i/o i/o i/o i/o i/o i/o i/o Altprinter NETNAME i/o i/o i/o i/o i/o i/o i/o i/o designates an input/output field. The other fields in SELECTED_PARMS are output only.
the autoinstall control program for terminals VTAM 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.
the autoinstall control program for terminals 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 VTAM supplies the PRINTER and ALTPRINTER NETNAMEs, if specified. The printers need not be installed at this stage; however, they must be installed before you use Print Key support. PRINTER and ALTPRINTER IDs override PRINTER and ALTPRINTER NETNAMEs.
the autoinstall control program for terminals 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. Your control program could go through a table of special case NETNAMEs, choosing the specified model for each. The default model would be used for any terminal not in the table.
the autoinstall control program for terminals 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. You could create a table in main temporary storage, so that it is placed in extended storage, above the 16MB line. You could use a VSAM file rather than a table, to avoid the storage problem. However, this might be slower, because of the I/O associated with a file.
the autoinstall control program for terminals A suggested course of action is as follows: 1. Determine whether a model such as ‘mmmmmmmm’ is suitable. If there are several models that have identical BIND images, differing only in end-user options, then only the first such model is named in the above message. It will be up to your control program to make the choice, when the logmode table entry is corrected. 2. Identify the VTAM logmode table entry that is being used. 3.
the autoinstall control program for terminals 1. Standard Header. Byte 1 indicates the request type. For deletion of local terminals (including APPC single-session devices installed via CINIT requests) the value is X'F1'. Note: A value of X'F5' or X'F6' represents the deletion of a local APPC connection that was installed by a BIND request—see page 519. A value of X'FA' or X'FB' represents the deletion of a shipped terminal or connection—see page 528.
naming and testing the control program 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. You can also make the program interactive, sending and receiving data from the terminal. If you find that CICS does not offer any autoinstall models to your program, you can create a test autoinstall program that forces the model name (AUTINSTNAME) you want.
sample autoinstall programs Table 25. Autoinstall programs and copy books (continued) Language Member name Alias Library Copy books: Assembler COBOL PL/I C/370 DFHTCUDS DFHTCUDO DFHTCUDP DFHTCUDH None DFHTCUDS DFHTCUDS DFHTCUDS SDFHMAC SDFHCOB SDFHPL1 SDFHC370 Note: If you use the COBOL version of the program, you must compile it using the VS COBOL II compiler. The module generated from the assembler-language source program is part of the pregenerated library shipped in CICSTS13.CICS.SDFHLOAD.
sample autoinstall programs 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.
sample autoinstall programs * VALIDT * LOOP2 * * * * * R7 now points to model name MTS model name supplied? Yes Count of models Were any presented? No First model name CLI BNE LH LTR BZ LA SELECTED_MODELNAME,C' ' VALIDM1 R6,MODELNAME_COUNT R6,R6 RETURN R8,MODELNAME CLC BE 8(8,R7),0(R8) VALIDM Is this model name here? LA BCT R8,L'MODELNAME(R8) R6,LOOP2 Next model name Now we know the required model name was not presented to this exit by CICS, a return rejects the logon B RETURN * * At this point
sample autoinstall programs . * * * * * * * * * * * * Redefine the netname so that the last 4 characters (of 7) can be used to select the autoinstall model to be used. The netnames to be supplied are known to be of the form: HVMXNNN HVM is the prefix X is the system name NNN is the address of the terminal NETNAME-BITS. 02 FIRST-CHRS PIC X(3). 02 NEXT-CHRS. 03 NODE-LETTER PIC X(1). 03 NODE-ADDRESS PIC X(3). 02 LAST-CHR PIC X(1). . . PROCEDURE DIVISION. . .
sample autoinstall programs DCL 1 CINIT 2 CINIT_LENG 2 CINIT_RU DCL SAVE_CINIT BASED(INSTALL_CINIT_PTR), FIXED BIN(15), CHAR(256); CHAR(256); /* Temp save area for CINIT RU */ DCL 1 SCRNSZ BASED(ADDR(SAVE_CINIT)), 2 SPARE CHAR(31), /* Bypass first part of CINIT and reach */ /* into BIND image carried in CINIT */ 2 DHGT BIT(8), /* Screen default height in BIND PS area */ 2 DWID BIT(8), /* Screen default width in BIND PS area */ 2 AHGT BIT(8), /* Screen alternate height in BIND PS area */ 2 AWID BIT(8); /* S
/* 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 11. Writing a program to control autoinstall of consoles Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. | | | | This chapter describes how to write a program to control the automatic installation of MVS console devices (including TSO consoles).
the autoinstall control program for consoles | 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 (DFHZATDX or DFHZATDY), or write your own program, using the source code of the default program and the customization examples in this chapter as a basis. | | | | | Notes: 1.
the autoinstall control program for consoles | | | The communication area at INSTALL for consoles The layout of the communication area is shown in Figure 34. Fullword 1 Byte 1 Bytes 2 - 3 Byte 4 Fullword 2 Fullword 3 Fullword 4 Fullword 5 Standard Header Function Code (X'FD' for INSTALL) Component Code Always 'ZC' Reserved Always X'00' Pointer to CONSOLENAME_FIELD Pointer to MODELNAME_LIST Pointer to SELECTED_PARMS Reserved Figure 34.
the autoinstall control program for consoles 'FD' Z C Fullword 2 LL LL Console name Fullword 3 nn | nn Fullword 4 Autinstmodelname_1 Autinstmodelname_n Modelname Terminal ID Reserved Reserved Return code i/o Reserved Reserved Reserved Delete Delay Note: i/o i/o i/o i/o i/o designates an input/output field. The other fields in SELECTED_PARMS are output only. Figure 35.
the autoinstall control program for consoles | | | | | | | | | If you want an INSTALL 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. DFHZATDX and DFHZATDY take the last four non-blank characters of the console name (addressed by fullword 2 of the parameter list) as the terminal name.
the autoinstall control program for consoles | 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 autoinstall control program for consoles | | | | | | 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. Chapter 11.
512 CICS TS for OS/390: CICS Customization Guide
Chapter 12. Writing a program to control autoinstall of APPC connections Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. This chapter describes how to write a program to control the automatic installation of local APPC connections. For information about controlling the automatic installation of local VTAM terminals, see “Chapter 10.
the autoinstall control program for APPC connections Local APPC parallel-session and single-session connections initiated by BIND If autoinstall is enabled, and an incoming APPC BIND request is received for an APPC service manager (SNASVCMG) session (or for the only session of a single-session connection), and there is no matching CICS CONNECTION definition, a new connection is created and installed automatically.
the autoinstall control program for APPC connections DFHZATDX, described in “Chapter 10. Writing a program to control autoinstall of terminals” on page 485. Thus, you can use a customized version of DFHZATDY to autoinstall both terminals and APPC connections. Note: Both DFHZATDX and DFHZATDY provide function to install shipped terminals and connections, and Client virtual terminals. You may find the supplied version of DFHZATDY adequate for your purposes.
autoinstall control program at INSTALL described in “The communications area at INSTALL for shipped terminals” on page 526 . The parameter list passed at INSTALL of Client virtual terminals is described in “The communications area at INSTALL for Client virtual terminals” on page 534. This section describes only INSTALL of local APPC connections initiated by BIND requests.
autoinstall control program at INSTALL INSTALL_APPC_EXIT_FUNCTION A 1-byte field that defines the install request type. The equated values are: INSTALL_APPC_PS_CINIT X'F2' represents an install request for an APPC parallel-session connection from a secondary node via a CINIT request. Note: These requests cannot be received by CICS Transaction Server for OS/390 Release 3. INSTALL_APPC_PS_BIND X'F3' represents an install request for an APPC parallel-session connection via a BIND.
autoinstall control program at INSTALL X'0001' Synclevel 1 X'0002' Synclevel 2. INSTALL_APPC_TEMPLATE_NETNAME_PTR A fullword pointer to an 8-byte input/output area (TEMPLATE_NETNAME). On invocation, TEMPLATE_NETNAME normally contains blanks. However, if both the partner and the local CICS are registered as generic resources, it contains the NETNAME of the generic resource name connection, if one is present. (Generic resource name connections are described in the CICS Intercommunication Guide.
autoinstall control program at INSTALL 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. INSTALL_APPC_GR_TYPE_PTR A fullword pointer to a 1-byte input field indicating whether this is a connection between generic resources and, if so, whether the NETNAME passed on the BIND is the partner’s generic resource name or its member name.
autoinstall control program at DELETE 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.
sample autoinstall programs The actions taken by the supplied version of the program are to: 1. Examine the request type passed in the INSTALL_APPC_EXIT_FUNCTION field: X'F0' An incoming CINIT for a terminal or APPC single-session device. Proceed as for DFHZATDX. See “Chapter 10. Writing a program to control autoinstall of terminals” on page 485. X'F1' A delete request for a terminal or APPC single-session device. Proceed as for DFHZATDX. See “Chapter 10.
sample autoinstall programs DFHZATDY is defined as follows in DFHAI62: DEFINE PROGRAM(DFHZATDY) DESCRIPTION(Assembler definition for sessions autoinstall control program) GROUP(DFHAI62) LANGUAGE(ASSEMBLER) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) STATUS(ENABLED) CEDF(NO) DATALOCATION(ANY) EXECKEY(CICS) EXECUTIONSET(FULLAPI) 522 CICS TS for OS/390: CICS Customization Guide
Chapter 13. Writing a program to control autoinstall of shipped terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. This chapter describes how to write a program to control the installation of shipped terminals and connections.
the autoinstall control program for shipped terminals CICS-generated aliases The autoinstall control program is invoked once for each shipped terminal or connection definition to be installed. If CICS detects that the name on a shipped definition clashes with the name of a remote terminal or connection already installed in the AOR, it generates an alias TERMID and passes it to the control program in field SELECTED_SHIPPED_TERMID of the communications area.
the autoinstall control program for shipped terminals v Whether your application programs record TERMIDs for later use. For example, an application might issue an EXEC CICS START TERMID command, with a time interval after which the transaction is to be initiated against the named terminal. If, during the delay interval, the terminal definition is deleted, re-shipped, and re-installed with a different local TERMID, the started transaction could fail because the TERMID no longer exists.
the autoinstall control program for shipped terminals INSTALL of local terminals and APPC single-session connections initiated by CINIT is described in “The communication area at INSTALL for terminals” on page 488. The parameter list passed at INSTALL of local APPC connections initiated by BIND requests is described in “The communication area at INSTALL for APPC connections” on page 516.
the autoinstall control program for shipped terminals INSTALL_SHIPPED_CLASH A 1-character input field that indicates whether the TERMID of the shipped definition is already in use in the AOR. Y The name by which the terminal or connection is known in the TOR (the value of the TERMINAL or CONNECTION attribute on the shipped definition) is already in use in the AOR to identify an installed remote terminal or connection.
the autoinstall control program for shipped terminals INSTALL_SHIPPED_CORRID_PTR A fullword pointer to an 8-character input field containing the shipped definition’s correlation identifier. A correlation identifier is a unique “instance token” that is created when a CICS/ESA 4.1 or later terminal or connection definition is installed, and stored within the definition. Thus, if the definition is shipped to another region, the value of the token is shipped too.
the autoinstall control program for shipped terminals DELETE_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being deleted. The equated values are: DELETE_SHIPPED_TERM (X'FA') A shipped terminal DELETE_SHIPPED_RSE (X'FB') A shipped connection (remote system entry). Note: A value of X'F1' represents the deletion of a local terminal, or an APPC single-session device that was autoinstalled via a CINIT request—see page 495.
530 CICS TS for OS/390: CICS Customization Guide
Chapter 14. Writing a program to control autoinstall of Client virtual terminals Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. This chapter describes how to write a program to control the installation of virtual terminals. Virtual terminals are used by the External Presentation Interface (EPI) and terminal emulator functions of the CICS Clients products.
the autoinstall control program for virtual terminals Terminal 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_EpiAddTerminal function, if specified by the Client EPI program. For the Client terminal emulator:From the /n parameter of the cicsterm command used to start the emulator, if specified by the workstation user. 2.
the autoinstall control program for virtual terminals 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)? You may not need to; it may depend on the way in which your server programs are written. By “server programs” we mean both the transaction programs started by Client EPI programs, and those started from the Client terminal emulator.
the autoinstall control program for virtual terminals Overriding Client-specified TERMIDs If TERMIDs are always nominated, in a consistent way, by your Client EPI programs, the problem of data mismatch due to server programs recording TERMIDs should not occur. However, Client-specified TERMIDs could clash with non-Client remote TERMIDs; or, if several Clients are attached to the same CICS system, with each other.
the autoinstall control program for virtual terminals *--------------------------------------------------------------------------* * Remote install parameter list - Client virtual terminal function 9 * *--------------------------------------------------------------------------* INSTALL_SHIPPED_COMMAREA DSECT Install Parameter List * INSTALL_SHIPPED_STANDARD DS F Standard field ORG INSTALL_SHIPPED_STANDARD INSTALL_SHIPPED_EXIT_FUNCTION DS XL1 Install type INSTALL_SHIPPED_TERM EQU X'F9' Install virtual termin
the autoinstall control program for virtual terminals 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 INSTALL_SHIPPED_CLASH is set to 'N' (indicating no conflict of terminal names), SELECTED_SHIPPED_TERMID contains the same value as the field pointed to by INSTALL_SHIPPED_TERMID_PTR (the supplied name).
the autoinstall control program for virtual terminals DELETE_SHIPPED_COMMAREA DELETE_SHIPPED_STANDARD DELETE_SHIPPED_EXIT_FUNCTION DELETE_SHIPPED_TERM DELETE_SHIPPED_EXIT_COMPONENT DELETE_SHIPPED_TERMID DELETE_SHIPPED_APPLID DELETE_SHIPPED_LTERMID DELETE_SHIPPED_NETNAME DSECT , DS F DS XL1 EQU X'FC' DS CL2 DS CL1 DS CL4 DS CL8 DS CL4 DS CL8 Delete parameter list Standard field Delete type Delete virtual terminal Component ID 'ZC' Reserved TERMID Applid of Client workstation TERMID in this region Netname o
the autoinstall control program for virtual terminals 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 DFHZATDX or DFHZATDY 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. This chapter describes the user-replaceable program that controls the automatic installation of programs, mapsets, and partitionsets.
the autoinstall control program for programs v CICS calls any user-replaceable program other than the program or terminal autoinstall program. v A program is named in the PLTPI or PLTSD list. Autoinstall model definitions Like autoinstall for terminals, program autoinstall uses model definitions, together with a user-replaceable control program, to create explicit definitions for resources that need to be autoinstalled.
the autoinstall control program for programs | Autoinstall processing of mapsets Table 26 shows the differences in mapset processing between CICS regions with program autoinstall active and inactive. Table 26. Differences in mapset processing between autoinstall and non-autoinstall Program autoinstall INACTIVE Program autoinstall ACTIVE CSD definition is required. CICS attempts to load a referenced mapset with a suffix. If this fails, CICS tries an unsuffixed version.
the autoinstall control program for programs Faster startup times Warm and emergency starts If you are using program autoinstall with cataloging, restart times are similar to those of restarting a CICS region that is not using program autoinstall. This is because, in both cases, resource definitions are reinstalled from the catalog during the restart. The definitions after the restart are those that existed before the system was terminated.
the autoinstall control program for programs The autoinstall control program at INSTALL On invocation, CICS passes a parameter list to the autoinstall control program by means of a communication area addressed by DFHEICAP. The communications area is mapped by a copybook that is supplied in each of the languages supported by CICS. The assembler form of the parameter list is as follows: PGAC_PROGRAM passes the 8-byte name of the object to be autoinstalled.
the autoinstall control program for programs 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. You should not need to specify the language of executable programs that have been translated using the EXEC CICS translator before compiling.
the autoinstall control program for programs PGAC_LPA_NO CICS is to load a private copy from its own DFHRPL library concatenation. PGAC_EXECUTION_SET allows you to specify, in a 1-byte field, whether or not the program is restricted to using the distributed program link (DPL) subset of the CICS API. The equated values are: PGAC_DPLSUBSET The program is to be restricted to the DPL subset of the EXEC CICS API. PGAC_FULLAPI The program can use the full API.
the autoinstall control program for programs named explicitly on the SYSID option of the EXEC CICS LINK command, the routing program can route the request to the region on which the program is to execute. | | | | The sample autoinstall control program for programs, DFHPGADX The CICS-supplied default autoinstall program is an assembler-language command-level program, named DFHPGADX. The source of the default program is provided in COBOL, PL/I, and C, as well as in assembler language.
sample autoinstall programs v You can discard definitions after they have been installed; they are reinstalled when next referenced. v You must ensure that the parameters you return to CICS are valid, and consistent with other system attributes in your CICS region. For example: – Do not return PGAC_LPA_YES on the PGAC_USE_LPA_COPY parameter if CICS is running with the system initialization parameter LPA=NO.
sample autoinstall programs v Autoinstall control program definition for DFHPGAOX. This defines the CICS-supplied COBOL version, and its status is set to DISABLED: GROUP(DFHPGAIP) PROGRAM(DFHPGAOX) DESCRIPTION(COBOL definition for program autoinstall exit) LANGUAGE(COBOL) EXECKEY(CICS) EXECUTIONSET(FULLAPI) RELOAD(NO) RESIDENT(NO) USAGE(NORMAL) STATUS(DISABLED) CEDF(NO) DATALOCATION(ANY) v Autoinstall control program definition for DFHPGAHX.
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.
the dynamic routing program 4. “Naming your dynamic routing program” on page 573 5. “Testing your dynamic routing program” on page 573 6. “Dynamic transaction routing sample programs” on page 574. Dynamic transaction routing This section refers to the dynamic routing of transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands. | | When you define transactions to CICS, you can describe them as “remote” or “local”.
dynamic transaction routing | | 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. Requesting region Route selection Notification Route selection error Transaction/link request termination Transaction abend Figure 43.
dynamic transaction routing 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 (ATI)—for example, by the expiry of an interval control start request—but the transaction is ineligible for dynamic routing. In this case, the dynamic routing program is called only to notify it of where the transaction is going to run.
dynamic transaction routing which transactions are to be routed. For information about defining remote transactions for dynamic transaction routing, see the CICS Intercommunication Guide. Important To route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is 'Y'). If you leave DYTDTRRJ set to 'Y', the transaction is rejected.
dynamic transaction routing If you want to terminate the transaction without issuing a message or abend, set a return code of X'4'. Warning: Setting a return code of X'4' for APPC transaction routing leads to unpredictable results, and should be avoided. Returning a value in DYRRETC has no effect when the routing program is invoked for notification or at termination of the transaction.
dynamic transaction routing 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. You could use this invocation to initiate a user-defined program in response to the transaction abend. If the routed transaction abends, the DFHAPRT program in the TOR: 1. Passes back a response to the CICS transaction manager indicating that a transaction abend has occurred 2.
dynamic transaction routing may also need to change the input communications area passed to the routed application. Field DYRACMAA of the routing program’s communications area enables you to do this; it is a pointer to the application’s communications area. Receiving information from a routed transaction If your dynamic routing program chooses to be reinvoked at the end of a routed transaction, it can obtain information about the transaction by monitoring its output communications area and output TIOA.
dynamic transaction routing v If you want to keep information about how transactions are routed, it must be done in the user routing program, perhaps by writing the information to a temporary storage queue associated with this terminal. v Several transactions can form a single conversation with the end user. At the start of the conversation, resources are allocated to record the state of the conversation.
dynamic routing of DPL requests | | | | | | v v v v A program-link request received from outside CICS can be dynamically routed by: v Defining the program to CICS Transaction Server for OS/390 as DYNAMIC(YES) v Coding your dynamic routing program to route the request.
dynamic routing of DPL requests | | v If an abend is detected after the link request has been shipped to the specified remote system, if reinvocation was requested by the routing program. | | Figure 43 on page 551 shows the points at which the dynamic routing program is invoked.
dynamic routing of DPL requests | | | | | 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. You can specify a local or remote program, depending on the region to which the request is to be routed.
dynamic routing of DPL requests | | | | | | | | | | | | | | If an error occurs in route selection If an error occurs in route selection—for example, if the SYSID returned by the dynamic routing program is unavailable or unknown, or the link fails on the specified target region— the dynamic routing program is invoked again. When this happens, you have a choice of actions: v You can tell CICS not to continue trying to route the request, by issuing a non-zero return code in DYRRETC.
dynamic routing of DPL requests 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.
parameters passed to DFHDYP DS OCL4 DYRFUNC DS CL1 DYRCOMP DS CL2 DYRFILL1 DS CL1 DYRERROR DS CL1 DYROPTER DS CL1 DYRQUEUE DS CL1 DYRFILL2 DS CL1 DYRRETC DS F DYRSYSID DS CL4 DYRVER DS H DYRTYPE DS CL1 DYRFILL3 DS H DYRTRAN DS CL8 DYRCOUNT DS F DYRBPNTR DS F DYRBLGTH DS F DYRRTPRI DS CL1 DYRFILL4 DS CL1 DYRPRTY DS H DYRNETNM DS CL8 DYRLPROG DS CL8 DYRDTRXN DS CL1 DYRDTRRJ DS CL1 DYRFILL5 DS CL2 DYRSRCTK DS XL4 DYRABNLC DS XL4 DYRABCDE DS CL4 DYRCABP DS CL1 DYRFILL6 DS CL1 DYRFILL7 DS CL2 DYRACMAA DS F DYRAC
parameters passed to DFHDYP | | | | | | | | | | 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.
parameters passed to DFHDYP Your routing program can alter the data in the application’s communications area. DYRACMAL is the length of the routed-to application’s communications area. If there is no communications area, this field is set to zero. | | DYRACTCMP is not used by the dynamic routing program. On invocation, it is set to nulls. | | DYRACTID is not used by the dynamic routing program. On invocation, it is set to nulls. | | DYRACTN is not used by the dynamic routing program.
parameters passed to DFHDYP There is no default value. DYRCOMP is the CICS component code. For calls to the dynamic routing program, it is always set to 'RT'. | | | DYRCOUNT is a count of the times the dynamic routing program has been invoked for this transaction or link request with DYRFUNC set to ‘0’, ‘1’, or ‘3’. This field allows you to limit the number of times your program tries to route a request.
parameters passed to DFHDYP For an explanation of the DTRTRAN system initialization parameter, see the CICS System Definition Guide. | DYRERROR has a value only when DYRFUNC is set to ‘1’. It indicates the type of error that occurred during the last attempt at route selection. The possible values are: 0 The selected sysid is unknown. 1 The selected system is not in service. 2 The selected system is in service, but no sessions are available.
parameters passed to DFHDYP | | 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.
parameters passed to DFHDYP | | You can change DYRLPROG on any call to the dynamic routing program, but it is effective only when DYRFUNC is ‘0’ or ‘1’. DYRNETNM is the netname of the CICS region identified in DYRSYSID. | | | If the DYRNETNM value is changed by the initial invocation of the dynamic routing program, CICS tries to route the request to the CICS region with the new netname.
parameters passed to DFHDYP Transaction routing The possible values are: | 0 Continue processing the transaction. 4 Terminate the transaction without message or abend. 8 Terminate the transaction with either a message or an abend. Whenever the routing program is invoked, DYRRETC is set to ‘0’. When it is invoked for route selection or because an error occurs in route selection, if you want CICS to continue processing the transaction, you must leave it set to ‘0’.
parameters passed to DFHDYP | | DYRSYSID is the system identifier (sysid) of a CICS region. The exact meaning of this parameter depends on the values of DYRFUNC and DYRTYPE: v When DYRFUNC is set to ‘0’ (route selection): – If DYRTYPE is set to ‘0’, ‘2’, or ‘3’ (any type of transaction routing), DYRSYSID contains: - The CICS region name specified on the REMOTESYSTEM option of the installed transaction definition, or, - If REMOTESYSTEM is not specified, the system name of the local CICS region.
parameters passed to DFHDYP 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. | Transaction 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 Naming your dynamic routing program The supplied, user-replaceable dynamic routing program is named DFHDYP. If you write your own version, you can name it differently. After the system has been loaded, to find the name of the dynamic routing program currently identified to CICS, use the EXEC CICS INQUIRE SYSTEM command. Field DTRPROGRAM contains the name of the current program. The default is DFHDYP.
sample transaction routing programs Dynamic transaction routing sample programs The CICS-supplied sample dynamic routing program is named DFHDYP. The corresponding copy book that defines the communications area is DFHDYPDS. There are assembler-language, COBOL, PL/I, and C source-level samples and copy books. The supplied programs and copy books, and the CICSTS13.CICS libraries in which they can be found, are summarized in Table 28. | | | | Table 28.
| | | | | | | Chapter 17. Writing a distributed routing program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. | | | | This chapter describes the CICS default distributed routing program and tells you how to write your own version.
the distributed routing program 6. “Distributed transaction routing sample programs” on page 593. | | | Differences from the dynamic routing interface This section discusses some significant ways in which the distributed routing interface differs from the dynamic routing interface. If you have previously written a dynamic routing program, and are about to write a distributed routing program, bear in mind that: 1.
differences 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. (Any value set in the DYRTRAN field of the communications area is ignored.) v Change the initial program associated with a routed request.
routing BTS activities | When the distributed routing program is invoked | | For BTS processes and activities started by RUN ASYNCHRONOUS commands, CICS invokes the distributed routing program at the following points: | | | | On the requesting region: 1. Either of the following: v For routing the activity. This occurs when the transaction associated with the activity is defined as DYNAMIC(YES). v For notification of a statically-routed request.
routing BTS activities | Changing the target CICS region | | | | | | The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the process or activity is to be routed. This is derived from the value of the REMOTESYSTEM option of the installed transaction definition on the requesting region. If REMOTESYSTEM is not specified, the sysid passed is that of the local CICS region.
routing BTS activities 2. You can tell CICS to treat the request as “unserviceable”, by issuing a non-zero return code in DYRRETC. Sometimes, perhaps because of a transaction affinity, it is essential that an activity should execute on a particular target region, and on no other. If this is the case, and the target region is unavailable, classify the request as unserviceable. Instead of reinvoking the routing program for a route selection error, CICS: a.
routing BTS activities | | | | | | | | Note that, because the routing program is distributed, all the CICS regions in the transaction routing set must have access to the data set. v The distributed routing program can be RMODE ANY but must be AMODE 31. Routing of non-terminal-related START requests This section describes how to use a distributed routing program to dynamically route non-terminal-related EXEC CICS START requests.
routing of non-terminal-related STARTs | When the distributed routing program is invoked | | For non-terminal-related START requests that are eligible for enhanced routing, CICS invokes the distributed routing program at the following points: | | | | | | | On the requesting region: 1. Either of the following: v For routing the request. v For notification of a statically-routed request.
routing of non-terminal-related STARTs Requesting region Target region Route selection Transaction initiation Notification Transaction termination Route selection error Transaction abend Routing attempt complete Figure 47.
routing of non-terminal-related STARTs | 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. You can try to route the request to a different target region, by changing the sysid, and issuing a return code of ‘0’ in DYRRETC.
routing of non-terminal-related STARTs | | | | | | | | v The distributed routing program can be RMODE ANY but must be AMODE 31. Parameters passed to the distributed routing program Figure 48 shows the communications area passed to the distributed routing program. The communications area is mapped by the copy book DFHDYPDS, which is in the appropriate CICS library for all the supported programming languages.
parameters passed to DFHDSRP | | | | | | | | | | | | 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.
parameters passed to DFHDSRP | | This field applies only to the routing of BTS processes and activities, not to the routing of non-terminal-related START requests. | | | DYRACTN is the name of the BTS activity being routed. (When a process is being routed, DYRACTN returns the name of the root activity—that is, DFHROOT.) | | This field applies only to the routing of BTS processes and activities, not to the routing of non-terminal-related START requests.
parameters passed to DFHDSRP 2. CICS rejected the allocate request automatically because the QUEUELIMIT value specified on the CONNECTION resource definition has been reached. | | | 4 | | | A queue of allocate requests has been purged, and SYSIDERR returned to all the waiting application programs. This error occurs for one of the following reasons: 1. An XZIQUE global user exit program requested that the queue be purged, or 2.
parameters passed to DFHDSRP For detailed information about which non-terminal-related START requests are eligible for dynamic routing, see the CICS Intercommunication Guide. | | | | | 4 This invocation occurs on the target region. | | | 5 Invoked for transaction initiation. The transaction associated with the routed request is about to be started on the target region. This invocation occurs on the target region. | | | Invoked because the transaction associated with the routed request abended.
parameters passed to DFHDSRP | | | This field applies only to the routing of BTS processes and activities, not to the routing of non-terminal-related START requests. Its contents are significant on transaction termination calls. | The possible values are: | Y This is the final activation of the BTS process. | N This is not the final activation of the BTS process.
parameters passed to DFHDSRP | | | | | | DYRRTPRI indicates whether or not the dispatch priority of the transaction should be passed to the application-owning region, if the connection between the terminal-owning region and the application-owning region is MRO. This field is not used by the distributed routing program. On invocation, it is set to 'N'. | | | DYRSRCTK is the MVS workload management service and reporting class token for the routed transaction.
parameters passed to DFHDSRP | | | v When DYRFUNC is set to ‘5’ (transaction initiation), DYRSYSID contains the name of the target region on which the routed request is to be executed. (This is also the region on which the distributed routing program is invoked.) | | | v When DYRFUNC is set to ‘6’ (routing completed), DYRSYSID contains the name of the target region to which CICS tried (successfully or unsuccessfully) to route the request. DYRTRAN contains the transaction name.
parameters passed to DFHDSRP | | | | | DYRVER is the version number of the dynamic routing interface. For CICS Transaction Server for OS/390 Release 3, the number is “5”. Naming your distributed routing program | | The supplied, sample distributed routing program is named DFHDSRP. If you write your own version, you can name it differently. | | | After the system has been loaded, to find the name of the distributed routing program currently identified to CICS, use the EXEC CICS INQUIRE SYSTEM command.
sample distributed routing programs If you want to route requests dynamically, you must customize DFHDSRP, or replace it completely with your own routing program.
Chapter 18. Writing a CICS–DBCTL interface status program Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. The CICS–DBCTL interface status program DFHDBUEX is a user-replaceable program forming part of the support for the CICS–DBCTL interface. It is designed to invoke user-supplied code whenever CICS successfully connects to or disconnects from DBCTL.
the CICS–DBCTL interface status program DBUSHEAD DBUREQT DBUCOMP DBURESV DBUREAS DBUSUFF DBUDBCTL DS DS DS DS DS DS DS OCL4 CL1 CL2 CL1 CL1 CL2 CL4 Standard Header Function Code Component Code Always "DB" Reserved Reason for disconnection DRA startup table suffix DBCTL identifier Figure 49. The DFHDBUEX communication area The parameter list contains the following information: DBUREQT Request Type. The function code has one of the following values: DBUCONN (X'01') Connected DBUDISC (X'02') Disconnected.
the CICS–DBCTL interface status program The sample contains an example, as part of a comment, of how to enable and how to disable a transaction. To use the program, it is necessary for transactions using DBCTL to be defined in the CSD as DISABLED. You 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. In the bridge environment, terminal commands are intercepted by CICS and passed to a bridge exit user-replaceable program.
600 CICS TS for OS/390: CICS Customization Guide
| | | | | | | Chapter 20. Writing a security exit program for IIOP Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. | | | Incoming requests using the Internet Inter-Orb Protocol (IIOP) are processed by CICS under a default USERID, unless you provide a security user-replaceable program to assign a new USERID.
602 CICS TS for OS/390: CICS Customization Guide
| | | | | | | | Chapter 21. Writing a program to tailor JVM execution environment variables Considerations common to all user-replaceable programs Note that the comments contained in “Chapter 5. General notes about user-replaceable programs” on page 401 apply to this chapter. | | | This chapter describes how to write a user-replaceable program to tailor the environment variables that control the execution of the CICS Java® virtual machine (JVM). The supplied program is called DFHJVMAT.
the JVM execution options program | | | | | 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 DFHJVMAT for information only, any changes will be ignored by CICS. | | | | CICS_PROGRAM_CLASS Specifies the CICS user class name. This is the equivalent of the JVMCLASS attribute on the CICS PROGRAM resource definition. No value is set in SDFHENV.
the JVM execution options program | | | | MAXHEAPSIZE Sets the maximum heap size for the JVM, in bytes. A default value of 8000000 bytes (8M) is set in SDFHENV. This is the recommended default for the MVS JVM. This is above-the-line storage. | | | | MINHEAPSIZE Sets the minimum heap size for the JVM, in bytes. A default value of 1000000 bytes (1M) is set in SDFHENV. This is the recommended default for the MVS JVM. This is above-the-line storage.
606 CICS TS for OS/390: CICS Customization Guide
Part 4. Customizing the XRF overseer program © Copyright IBM Corp.
A general note about user-written programs On return from any user-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual.
Chapter 22. The extended recovery facility overseer program The information in this chapter is of interest only to users of the extended recovery facility (XRF). Details of XRF are provided in the CICS/ESA 3.3 XRF Guide. Guidance information about running the overseer, including a sample job stream, is provided in the CICS Operations and Utilities Guide.
the XRF overseer program 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 (CAVM) data sets that it has previously failed to open. The full format of the operator command entered at the MVS console is: MODIFY overseer-jobname,command-identifier where “command-identifier” is Display, Restart, Snap, End, or Open, or an abbreviation of any of these.
the XRF overseer program which was in an intermediate state when the Display command was processed. Reissuing the Display command causes UNKN to be replaced by another status value. OLD The information displayed for the alternate refers to out-of-date information about the system that was the alternate until a recent takeover. That system is the current active, and the information displayed for the alternate is marked as OLD until a new alternate is signed on and running normally.
the XRF overseer program related regions to be taken over, because the new active region can continue communication with the other active regions. Takeover is therefore likely to be your preferred course of action. Enabling and disabling restart in place: The restart-in-place function of the overseer program can be enabled and disabled using the Restart command. When you enter this command, restart processing is enabled or disabled for all generic applids that the overseer is monitoring.
the XRF overseer program Opening CAVM data sets dynamically When the overseer program is initialized, it is possible that some CAVM data sets have not yet been formatted by a CICS system. The overseer program obtains an ‘open error’ return code on these data sets, and subsequent attempts to display details about the associated CICS systems receive the response ‘NO ACTIVE DATA AVAILABLE’. This problem arises only if the overseer is initialized before all the CAVM data sets have been formatted.
the XRF overseer program each active-alternate pair. You create this data set and initialize it with information about active-alternate pairs before you use the overseer for the first time. You also have to redefine the DFHOSD data set whenever you want to change the information that it holds.
DFHWOSM macros DFHWOSM FUNC=READ Retrieve status information for a named generic applid from the CAVM data sets DFHWOSM FUNC=TERM Close communication with DFHWOS. The macros are described in detail in the following sections. For all the DFHWOSM macros, the following rules apply: v The “label” field is optional. v If the macro has an input parameter list, the address of that parameter list must be supplied as the value of the PARM operand.
DFHWOSM macros Register 15 Contains one of the following completion codes: 0 Communication successfully initialized between the overseer program and DFHWOS 4 Incorrect TOKEN value supplied 8 Insufficient storage. DFHWOSM FUNC=CLOSE macro The DFHWOSM FUNC=CLOSE macro terminates access to the CAVM data sets for a named generic applid.
DFHWOSM macros v An 8-byte JES job ID v A 256-byte SSOB return area. The TOKEN value is the ENTRY token. Output Register 15 Contains the following completion codes: 0 JES cancel completed; SSOB and status array returned from JES Nonzero Return code from JES. DFHWOSM FUNC={JJS|QJJS} macro Supplied with a job name and JES job identifier, both versions of the DFHWOSM FUNC={JJS|QJJS} macro return the current JES job status into a copy of the JES subsystem options block (SSOB).
DFHWOSM macros Nonzero Return code from JES. DFHWOSM FUNC=OPEN macro The DFHWOSM FUNC=OPEN macro initializes access to the CAVM data sets for a named generic applid. label DFHWOSM FUNC=OPEN [,PARM={parm address|1}] [,TOKEN={token register|14}] Input The PARM value is a pointer to three further addresses, and these are: 1. The address of the generic applid 2. The address of the ddname of the control data set 3. The address of the ddname of the message data set. The TOKEN value is the BUILD token.
DFHWOSM macros the required MVS command is provided as input to the macro, and the OSCMD service issues an SVC 34 specifying this command text. In addition, the OSCMD service issues an MVS WTO request so that a copy of the command text appears on the MVS console to keep the operator informed of what is about to happen. This copy has the comment ‘(BY IOP)’ appended to show that the command is going to be issued by an overseer program.
DFHWOSM macros Parameter list pointer Generic Applid Address Generic Applid DBLLIST Address OUTPUT INPUT Item 1 address DBLID 1 Item 1 length Item 2 address DBLID 2 Item 2 length . . . . DBLID n Item n length . . Item n address OUTPUT Figure 50.
DFHWOSM macros DBLIDs for the alternate: DBLID257 DBLID258 DBLID259 DBLID260 DBLID261 DBLID262 DBLID263 DBLID264 DBLID265 DBLID266 DBLID267 DBLID268 DBLID288 DBLID289 DBLID290 DBLID291 DBLID292 DBLID293 DBLID294 DBLID295 DBLID296 EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU X'0101' X'0102' X'0103' X'0104' X'0105' X'0106' X'0107' X'0108' X'0109' X'010A' X'010B' X'010C' – X'011F' X'0120' X'0121' X'0122' X'0123' X'0124' X'0125' X'0126' X'0127' X'0128' JOB NAME JES JOB
DFHWOSM macros Reading DBCTL status information from the CAVM 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 CAVM data sets. However, the supplied sample overseer program does not read the DBCTL information from the CAVM data set. If you want the overseer to retrieve this information and to display or use it, you must write your own overseer program.
DFHWOSM macros Output Register 15 Contains the following completion codes: 0 Communication terminated successfully Nonzero Request failed. Customizing the sample overseer program The sample overseer program consists of four modules link-edited together. The main module is DFH$AXRO; the other three modules are subroutines, described below: DFH$AGCB sets up request parameter lists (RPLs), access method control blocks (ACBs), and parameter lists. DFH$ADSP displays status information.
customizing the sample overseer v To extend the function of the overseer program, you can incorporate the CEBT command, which is normally issued by the console operator to control the alternate. The CEBT command is described in the CICS Supplied Transactions manual.
customizing the sample overseer To include this LOOP WARNING code, set the variable &LOOPWARN to ‘1’ and reassemble the sample. Assembling and link-editing the overseer program The non-specific job control statements required to assemble and link-edit the overseer program are the same as those required for user-replaceable programs, and are described in “Assembling and link-editing user-replaceable programs” on page 402.
626 CICS TS for OS/390: CICS Customization Guide
Part 5. CICS journaling, monitoring, and statistics © Copyright IBM Corp.
A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 5 of this book: v Upon return from any user-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information).
Chapter 23. CICS logging and journaling The CICS log manager provides facilities for the creation, control, and retrieval of journals during real-time CICS execution. Journals are intended to record, in chronological order, any information that you may later need to reconstruct data or events. For example, you could create journals to act as audit trails; to record database updates, additions, and deletions for backup purposes; or to track transaction activity in the system.
journaling 3. Tertiary 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.
journaling Secondary storage LSN1 Primary storage Current Data Set MVS1 System Logger Data Space LSN1 Full Data Set Staging Data Sets DFHSM Storage Tertiary storage Figure 54. The types of storage used by the MVS system logger. This diagram shows a log stream that uses DASD-only logging. Primary storage consists of a data space in the same MVS image as the system logger, and a single staging data set.
journaling Reading journal records offline Access to journaled data in log streams is provided through an MVS subsystem interface (SSI), LOGR. Your existing user programs can read the general log streams, providing you specify, in your batch job JCL, the SUBSYS parameter and supporting options on the DD for log streams. By specifying the LOGR subsystem name on the SUBSYS parameter, you enable LOGR to intercept data set open and read requests at the SSI, and convert them into log stream accesses.
journaling 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 Transaction Server for OS/390 format.. Each general log comprises a stream of contiguous blocks of journaled data. Each block comprises a block header followed by a variable number of CICS journal records.
journaling Format of general log block header The log block header contains information of a general system-wide nature such as the CICS applid writing the journal block. Figure 56 shows the format of the log block header. Fixed length 8 > DF Ht r n n 8 Start time (GMT) LGBH GLOBAL INFO LGBH START GMT CICS applid LGBH GENERIC APPLID Wh e r e t = L o g t y p e r = reserved nn = block version number Figure 56.
journaling 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.
journaling Start-of-run record When CICS connects to a general log, it writes a start-of-run record to it as the first record for this run of CICS. This record comprises a record header (with the same format as that for any general log journal record) followed by a start-of-run body. Its format is shown in Figure 58. Fixed length 4 8 8 CICS rele ase SOR CICS RELEASE CICS applid SOR SPECIFIC APPLID CI CS use rna me SOR CICS USERNAME Figure 58.
journaling F ix e d le n g th 4 2 2 Va ria b le le n g th 4 R e s e rv e d P re fix le n g th C L UH PR EFIX LEN G TH P re fix a re a U s e r d a ta J o u rn a l ty p e C L U H JO U R N A L TY P E H e a d e r le n g th C L U H LE N G TH Figure 59. Format of the API user header Caller data written by file control The file log and journal block (FLJB) describes the caller data that file control writes as part of its journal records. The copybook DFHFCLGD defines the FLJB DSECT.
journaling v The FLJB_COMMON_DATA section, and v The caller data image sections which consist of the FLJB_CD_KEY (the length of which is given in FLJB_COMMON_DATA) and the FLJB_CD_DATA section. The FLJB_CD_DATA section (the length of which is given in FLJB_COMMON_DATA) contains the image of the caller data. The format of such a record written for these record types is shown in Figure 60.
journaling Fixed length 1 1 8 File name 2 Reserved FLJB FILE NAME Record type Flag byte FLJB RECORD TYPE FLJB BITS X'80' read-only X'80' file control autojournal record X'81' read-update X'40' forward recovery log record X'82' write-update X'20' system log record X'83' write-add X'10' log-of-log record X'84' write-add complete X'86' write-delete X'8E' file-close X'8F' file tie-up record Figure 61.
journaling Write-delete record types There are four sections in the journal records written for write-delete record types: v The FLJB_GENERAL_DATA section, v The FLJB_WRITE_DELETE_DATA section, and v The two caller data image sections, which consist of: – FLJB_WDD_BASE_KEY (the length of which is given by FLJB_WDD_BASE_KEY_LENGTH in FLJB_WRITE_DELETE_DATA) – FLJB_WDD_PATH_KEY (the length of which is given by FLJB_WDD_PATH_KEY_LENGTH in FLJB_WRITE_DELETE_DATA).
journaling F ix ed le n g th 4 R e la tiv e b y te a d d re s s o f re c o rd in b a s e d a ta s e t fo r E D S (0 if file d oe s no t refe r to E S D S ) F LJB W D D B A S E E S D S R B A B a s e k e y le n g th FLJB W D D B A S E K E Y LE N G T H 2 2 1 3 R e s e rv e d F la g b y te FLJB W D D B ITS X '8 0 ' U O W h a s b e e n s h u n te d a t le a s t o n c e X '4 0 ' fix e d le n g th re c o rd P a th k e y le n g th (0 if file d o e s n o t re fe r to a p a th ) F L JB W D D PAT H K E Y L E N G
journaling Fixed length 26 1 1 Log stream name of the forward recovery log FLJB FCD FWDRECOVLOG NAME Flag byte FLJB FCD BITS X'80' forward recovery specified for file or data set X'40' autojournaling specified for file Reserved Figure 66. Format of the FILE_CLOSE_DATA section Tie-up record types There are two sections in the journal records written for tie-up record types: v The FLJB_GENERAL_DATA section v The TIE_UP_RECORD_DATA section.
journaling F ix e d le n g th 4 4 4 2 1 1 C I s iz e o f b a s e d a ta s e t R e c o rd fo rm a t F L J B T U R B A S E C I S IZ E F L J B T U R R E C O R D F O R M AT x 'E 5 ' = Va ria b le x 'C 6 ' = F ixe d M a x im u m re c o rd le n g th F L JB T U R M A X IM U M L R E C L D a ta s e t ty p e B a s e k e y p o s itio n in re c o rd F L J B T U R D ATA S E T T Y P E F L J B T U R B A S E K E Y P O S IT IO N x 'C 5 ' = E S D S x 'D 2 ' = KSDS B a s e k e y le n g th x 'D 7 ' = P ath
journaling 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. Terminal control prefix data CICS terminal control (TC) writes journal records to track the messages it issues. Each TC journal record contains a prefix area, which lies in the position of the prefix area in the API user header. For LU6.
journaling Fixed length 1111 2 8 8 8 4 Reserved Pool name UP FEPPL Reserved Escape character Target name UP FEPTG for keystroke UP FEPES Conversation identifier Data function UP FEPCV UP FEPDF Module identifier UP SVMID Module function UP MODFN Figure 70. Format of the FEPI prefix area See the CICS Front End Programming Interface User’s Guide for more information about FEPI journaling.
journaling A graphical overview of the format of a general log, showing the format of a complete block, is shown in Figure 71. Log block Journal control Journal label record header 1 Log block Log block Journal record 2 Log block Journal record nn Figure 71. Format of general log formatted using the COMPAT41 option Format of COMPAT41 journal control label header Each log block starts with a journal control label header. There is one journal control label header per log block.
journaling Fixed length 2 2 Len gth of r ecor d 2 2 2 Record number JCRLL w i t h i n b l oc k JCRLRN X'0000' User-type ID JCRUTRID '0000' if CICS journal request. Otherwise code specified in JTYPEID System-type ID ke ywo rd o f use r r e qu es t JCRSTRID '0 000 ' i f user jo ur nal re qu est. Otherwise 1-byte function ID fol lowed by 1-byte module ID Figure 73.
journaling 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. Fixed length Variable length 10 System header System prefix User prefix Journal data Figure 75. Format of COMPAT41 journal record The system header is 10 bytes long. Its format is shown in Figure 76.
journaling The field JCRSTRID (the system-type ID) and the field JCRUTRID (the user-type ID) in the system header allow you to distinguish those journal records output by CICS (by such components as terminal control), from those issued by direct user requests. For CICS journal requests, JCRUTRID contains binary zeros, and JCRSTRID contains a 1-byte function code followed by a 1-byte module code.
journaling command via the JTYPEID, PREFIX, and PFXLENG parameters. Its format is shown in Figure 78. Variable length Length of user prefix User prefix data Figure 78. Format of the user prefix 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.
journaling *********************************************************************** * * F U N C T I O N I D E N T I F I E R S * * *********************************************************************** * * * X'20' PLUS X'8-' ...USE FOR AUTOMATIC JOURNALING * * X'40' PLUS X'8-' ...USE FOR AUTOMATIC LOGGING * *********************************************************************** * * JOURNAL CONTROL * * *********************************************************************** FIDJCLAB EQU X'80' ...
journaling *********************************************************************** * TERMINAL CONTROL FUNCTION IDENTIFIERS * * * FIDTCML EQU X'F0' SYNCPOINT - LOG SEQUENCE * NUMBERS * * CAN BE OR'ED WITH ANY OF * THE FOLLOWING THREE FIELDS: FIDTCDWL EQU X'01' ...DEFERRED WRITE DATA FIDTCFMH EQU X'02' ...+ FUNCTION MANAGEMENT * HEADER FIDTCDIP EQU X'04' ...+ DIP REQUEST * * * EQU X'08' ...DYNAMIC BACKOUT MASK * RESERVED FIDTCAL EQU X'40' AUTOMATIC LOGGING MASK... FIDTCAJ EQU X'20' AUTOMATIC JOURNALING MASK..
journaling Identifying records for the start of tasks and UOWs You can identify records written to mark the start of tasks by examining the value of the system prefix field JCSPF1. If the JCSPSOTK bit is set, the record has been written at the start of the task. If the JCSPLSTK bit is set in field JCSPF1, then the record has been written at the start of the UOW. Format of journal records written to SMF This section describes the format of journaling records that are written to an SMF data set.
journaling The SMF block header This block describes the system creating the output. Its format is shown in Figure 82. Fixed length 2 2 1 1 4 4 4 4 2 2 2 4 2 2 4 2 2 Ti m e r e c o r d N o.
journaling F ix e d le n g th 2 8 2 8 P ro d u c t n a m e (g e n e ric A P P L ID ) SM FPS PRN X '0v rm ' SM FPS VRM 54 R e c o rd m a in te n a n c e in d ic a to r S M FP S M FL R e s e rv e d P ro d u c t n a m e (sp e cific A P P L ID ) SM FPS SPN v = v e rs io n r = re le a s e m = m o d ific a tio n set by DFHSYS F ix e d le n g th 8 8 Journal nam e S M FP S JN M Job name S M FPS JBN 4 4 8 J o b tim e SM FPS RST (lo c a l) 8 U se r ID SM FPS UIF O p .
656 CICS TS for OS/390: CICS Customization Guide
Chapter 24. CICS monitoring This chapter describes the monitoring facilities of CICS Transaction Server for OS/390, and tells you how to: v Control the types of monitoring data collected by CICS v Gather more performance data about specific transactions than is provided automatically by CICS. The chapter is divided into the following sections: 1. “Introduction to CICS monitoring” describes the classes of monitoring data, event-monitoring points, and the use of the monitoring control table. 2.
monitoring—introduction You 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. You cannot relocate these monitoring points, but you can create additional ones, at which user-defined performance data can be gathered.
monitoring—introduction v To tell CICS that you want specific system-defined performance data not to be recorded during a particular CICS run. See “DFHMCT TYPE=RECORD”. Full details of the DFHMCT macros are provided in the CICS Resource Definition Guide, and you should refer to that book when reading the following sections. DFHMCT TYPE=EMP There must be a DFHMCT TYPE=EMP macro definition for every user-coded EMP.
monitoring—introduction 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 DFHTASK, and has the numeric identifier ‘031’. Using these identifiers, you can exclude specific fields or groups of fields, and reduce the size of the performance records. Examples of MCT coding The examples below show some EXEC CICS MONITOR commands with the MCT entries that must be coded for them.
monitoring—introduction Example 3: EXEC CICS MONITOR command EXEC CICS MONITOR POINT(13) DATA1(address of data) DATA2(length of data) ENTRYNAME(PROG3) MCT entry DFHMCT TYPE=EMP, * CLASS=PERFORM, * ID=(PROG3.13), * PERFORM=MOVE(0,32) Example 3 shows 32 bytes of user data being updated in the character string reserved for that purpose. The updated data starts at offset 0, and the data is not more than 32 bytes in length.
monitoring—introduction v v v v v Wait Wait Wait Wait Wait for for for for for temporary storage data set extension shared temporary storage shared temporary storage pool file string file buffer v Wait for LSRPOOL string. An exception record is created each time any of the resources covered by exception class monitoring becomes constrained by system bottlenecks. If performance data is also being recorded, it keeps a count of the number of exception records generated for each task.
monitoring—introduction 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. You can use the master terminal CEMT INQ|SET MONITOR command, which is described in the CICS Supplied Transactions manual. 2.
monitoring record formats 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.
monitoring record formats * * * SMFMNRVN SMFMNPRN SMFMNSPN SMFMNMFL START OF THE SMF PRODUCT SECTION DS XL2 DS CL8 DS CL8 DS XL2 DS XL2 SMFMNCL DS XL2 * * * SMFMNDCA DS XL4 SMFMNDCL DS XL2 SMFMNDCN DS XL2 SMFMNDRA DS XL4 SMFMNDRL DS XL2 SMFMNDRN DS XL2 * DS XL20 SMFMNTAD DS XL4 SMFMNLSO DS XL8 SMFMNDTO DS XL8 DS XL2 SMFMNJBN DS CL8 SMFMNRSD DS XL4 SMFMSRST DS XL4 SMFMNUIF DS CL8 SMFMNPDN DS CL8 * * THIS CONCLUDES THE RECORD VERSION (CICS) PRODUCT NAME (GENERIC APPLID) PRODUCT NAME (SPECIFIC APPLID) RECOR
monitoring record formats 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. You can identify which of these you are dealing with by looking at the value of field SMFMNCL in the SMF product section. Each of the data section types is described in the sections that follow. Dictionary data sections Dictionary data sections describe all the fields in the performance data records that are gathered during this CICS run.
monitoring record formats DFHMCTDR TYPE=(PREFIX,CMO) CMO is the default label prefix. CMODNAME CMODTYPE * * * * * CMODIDNT * CMODLENG CMODCONN CMODOFST CMODHEAD CMODNEXT DS DS CL8 C + 0 + 8 DS CL3 +9 DS DS DS DS EQU H XL2 XL2 CL8 * +12 +14 +16 +18 The DSECT is as follows: NAME OF OWNER (entry name) OBJECT TYPE 'S' = STOPWATCH (CLOCK) 'A' = ACCUMULATOR (COUNT) 'C' = BYTE-STRING FIELD 'T' = TIMESTAMP (STCK FORMAT) 'P' = PACKED-DECIMAL FIELD ID WITHIN TYPE CLOCK-, COUNT-, OR FIELD-NO.
monitoring record formats FIELD-NAME DFHTASK C001 DFHTERM C002 DFHCICS C089 DFHTASK C004 DFHCICS T005 DFHCICS T006 DFHTASK P031 DFHTASK A109 DFHTASK C166 DFHTERM C111 DFHPROG C071 DFHTASK C097 DFHTASK C098 DFHCICS C130 DFHCICS A131 DFHTASK T132 DFHCICS C167 DFHCICS C168 DFHTASK C163 DFHTASK A164 DFHTERM A165 DFHTERM C169 DFHTASK C124 DFHTASK C190 DFHCBTS C200 DFHCBTS C201 DFHCBTS C202 DFHCBTS C203 DFHCBTS C204 DFHSOCK C244 DFHTASK C082 DFHTASK C064 DFHPROG C113 DFHPROG C114 DFHCICS C112 DFHTERM A034 DFHTERM
monitoring record formats FIELD-NAME DFHSTOR A117 DFHSTOR A120 DFHSTOR A033 DFHSTOR A106 DFHSTOR A116 DFHSTOR A119 DFHSTOR A095 DFHSTOR A107 DFHSTOR A118 DFHSTOR A121 DFHSTOR A144 DFHSTOR A145 DFHSTOR A146 DFHSTOR A147 DFHSTOR A148 DFHSTOR A149 DFHSTOR A087 DFHSTOR A139 DFHSTOR A108 DFHSTOR A142 DFHSTOR A143 DFHSTOR A122 DFHSTOR A162 DFHSTOR A161 DFHSTOR A160 DFHFILE A036 DFHFILE A037 DFHFILE A038 DFHFILE A039 DFHFILE A040 DFHFILE A093 DFHFILE A070 DFHDEST A041 DFHDEST A042 DFHDEST A043 DFHDEST A091 DFHTEMP
monitoring record formats FIELD-NAME DFHTASK A059 DFHTASK A066 DFHSYNC A060 DFHCICS A025 DFHFEPI A150 DFHFEPI A151 DFHFEPI A152 DFHFEPI A153 DFHFEPI A154 DFHFEPI A155 DFHFEPI A157 DFHFEPI A158 DFHFEPI A159 DFHCBTS A205 DFHCBTS A206 DFHCBTS A207 DFHCBTS A208 DFHCBTS A209 DFHCBTS A210 DFHCBTS A211 DFHCBTS A212 DFHCBTS A213 DFHCBTS A214 DFHCBTS A215 DFHCBTS A216 DFHCBTS A217 DFHCBTS A218 DFHCBTS A219 DFHCBTS A220 DFHCBTS A221 DFHCBTS A222 DFHWEBB A231 DFHWEBB A232 DFHWEBB A233 DFHWEBB A234 DFHWEBB A235 DFHWEBB
monitoring record formats FIELD-NAME DFHTASK S008 DFHTASK S014 DFHTASK S102 DFHTASK S255 DFHTASK S256 DFHTASK S257 DFHTASK S258 DFHTASK S259 DFHTASK S260 DFHTASK S261 DFHTASK S249 DFHTASK S250 DFHCICS S103 DFHTERM S009 DFHFILE S063 DFHJOUR S010 DFHTEMP S011 DFHTERM S100 DFHDEST S101 DFHPROG S115 DFHTASK S125 DFHTASK S126 DFHTASK S127 DFHTASK S129 DFHTASK S123 DFHTERM S133 DFHTERM S134 DFHFEPI S156 DFHTASK S170 DFHTASK S171 DFHSYNC S173 DFHFILE S174 DFHFILE S175 DFHTASK S128 DFHTASK S181 DFHTASK S182 DFHTASK
monitoring record formats Performance data sections Each performance data section is made up of a string of field connectors, followed by one or more performance data records. All of the performance records produced by a single CICS run have the same format, and each record is, by default, 664 bytes long. However, the length of the performance records changes if you add user data at user EMPs, or if you exclude any system-defined data from the monitoring process.
monitoring record formats Dictionary Record Dictionary Dictionary Dictionary Dictionary Entry 1 Entry 2 Entry 3 Entry 4 Field Connectors 001 Dictionary Entry n 002 004 nnn Performance Record 1 Data for field 1 Data for field 2 Data for field 4 Data for field n Performance Record 2 Data for field 1 Data for field 2 Data for field 4 Data for field n Performance Record 3 Data for field1 Data for field2 Data for field4 Data for fieldn Performance Record 4 Data for field 1 Data for field
monitoring record formats 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. SMF Header SMF Product Section Exception Data Section Figure 91.
monitoring record formats 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. Chapter 24.
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 STATISTICS command. 2. “CICS statistics record format” on page 682 describes the format of CICS statistics SMF type 110 records. 3. “Global user exit in the CICS statistics domain” on page 687 suggests ways in which you can use the XSTOUT statistics exit. 4.
statistics—introduction or v The RECORDING option of the EXEC CICS SET STATISTICS command is set to ON. The TS data sharing server writes interval statistics if statistics recording was set to SMF or BOTH by the STATSOPTIONS server initialization parameter, or by the server command SET STATSOPTIONS. When interval statistics are written, the statistics counters are reset. See “Resetting statistics counters” on page 681.
statistics—introduction v EXEC CICS SET STATISTICS ON|OFF RECORDNOW. CICS writes requested statistics to SMF even if, on one of the following, you have specified OFF: v The STATRCD system initialization parameter v The CEMT SET STATISTICS command v The RECORDING option of the EXEC CICS SET STATISTICS command. Statistics counters are not reset. Requested reset statistics differ from requested statistics in that all statistics are collected, and all statistics counters are reset.
statistics—introduction 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.
statistics—introduction | | | 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. Transaction classes Whenever an installed transaction class definition is discarded, CICS collects the statistics covering the installed period since the last interval.
statistics—introduction Important Statistics counters are reset in various ways. Specific counters may be reset to: v 0 v 1 v A new peak value v Not reset v None of the above. For information about the resetting of specific statistics counters, refer to the CICS Performance Guide. The EXEC CICS COLLECT STATISTICS command In addition to the types of statistics data described above, there is an online EXEC CICS COLLECT STATISTICS function.
format of statistics records 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.
format of statistics records * * STSMFDS SMFSTLEN SMFSTSEQ SMFSTFLG SMFSTRTY SMFSTTME SMFSTDTE SMFSTSID SMFSTSSI SMFSTSTY * SMFSTTRN SMFSTAPS SMFSTLPS SMFSTNPS SMFSTASS SMFSTASL SMFSTASN * * * * * SMFSTRVN SMFSTPRN SMFSTSPN SMFSTMFL START THE SMF HEADER DSECT DS DS DS DC DS DS DS DS DS XL2 XL2 X X'6E' XL4 XL4 XL4 CL4'CICS' XL2 DS DS DS DS DS DS DS DS XL2 XL2 XL4 XL2 XL2 XL4 XL2 XL2 RECORD LENGTH SEGMENT DESCRIPTOR OPERATING SYSTEM INDICATOR (see note 1) RECORD TYPE 110 FOR CICS TIME RECORD MOVED TO SMF
format of statistics records | | | | | | | 3. Fields SMFSTINT and SMFSTINO are only relevant if SMFSTRQT is ‘INT’. Otherwise both values should be ignored. 4. For TS data sharing, the record subtype is X’0003’ and certain fields are not set or are used in a different way. SMFSTPRN and SMFSTSPN contain the server prefix (DFHXQ) and the pool name. 5. For coupling facility data table (CFDT) servers, the record subtype is X'0004' and certain fields are not set or are used in a different way.
format of statistics records 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.
format of statistics records STID STID Symbolic Value name - 121 122 123 Copy book Type of record DFHXQS1D DFHXQS2D DFHXQS3D TS server list structure stats id TS buffer stats id TS storage stats id Figure 98.
processing statistics Processing the output from CICS statistics There are several utilities to help you process statistics output. You can use: The CICS-supplied DFHSTUP program For information about how to run DFHSTUP, refer to the CICS Operations and Utilities Guide. For information about how to interpret the report produced by DFHSTUP, see the CICS Performance Guide. Your own program to report and analyze the data in the statistics records.
Part 6. Customizing CICS compatibility interfaces © Copyright IBM Corp.
A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 6 of this book: v Upon return from any customer-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information).
Chapter 26. Using TCAM with CICS This chapter describes the use of the telecommunications access method (TCAM) with CICS Transaction Server for OS/390 Release 3. Important CICS Transaction Server for OS/390 Release 3 supports only the DCB interface to TCAM, and not the ACB interface. This means that, in order for CICS to use it, TCAM has to be run as a VTAM application—it cannot be used independently of ACF/VTAM. The chapter is divided into the following sections: 1.
CICS with TCAM SNA 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. You must be prepared to write an appropriate TCAM SNA message control program to complement the CICS support and the SNA devices attached to the system.
CICS with TCAM SNA Transaction control In the transaction control method of protocol management, the transaction controls the protocol. The SNA session should be bound with a protocol of HDX-FF with brackets when running this type of management. When using transaction control, the communication control byte (CCB) is used to relay information from the transaction to the DMH. For example: v EXEC CICS SEND LAST should be used to end a transaction.
CICS with TCAM SNA Batch processing When running a batch logical unit, a point to consider is how to get the transaction identification to CICS on the “begin data set” condition. The alternative methods are discussed below. The first method is for the DMH to recognize the “begin data set” condition by interrogating the FMH and by editing the transaction ID into the input data. This method is demonstrated in the sample message control programs DFHSPTM1 and DFHSPTM2.
the TCAM API 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 contains the DCB. The DDNAME specified in the terminal control table macro (DFHTCT TYPE=SDSCI,DDNAME=name) names the DD card.
the CICS-TCAM interface 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.
the CICS-TCAM interface For information about the DFHTCT macros, see the CICS Resource Definition Guide. Logic flow The following is a generalized description of the sequence of events that occurs in CICS when interfacing with TCAM. INPUT STEP ACTION A TCAM notifies CICS that it has data for a particular input TCTLE, by posting its ECB. B CICS gets a TIOA and attaches it to the special input TCTTE in the TCTLE.
the CICS-TCAM interface TCAM input process queue Input TCTLE Special TCTTE TIOA Figure 102. CICS issues a TCAM read OUTPUT STEP ACTION 698 A You 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.
the CICS-TCAM interface TCAM input process queue Input TCTLE QUTQ= (ABC) Special TCTTE TIOA Output TCTLE Terminal ABC Individual TCTTEs Figure 103. After a TCAM read, CICS attaches a TIOA to the corresponding TCTTE Terminal 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 Table 32 on page 700 are unique to TCAM, and should be considered in DFHTEP. Chapter 26.
the CICS-TCAM interface Table 32. DFHTEP error codes and conditions unique to TCAM Error code Condition Action X'87'(TCEMCUI) Unsolicited input Terminal ‘receive only’ Terminal ‘out of service’ Task has not issued a read No available TCTTE from pool. a a, b No default No default X'9F'(TCEMIDR) TCAM has issued an invalid destination return code to CICS. c where: a = Release TCAM TIOA (X'04' in TEPCAACT) b = Terminal out of service (X'20' in TEPCAACT) c = Abend transaction (X'10' in TEPCAACT).
the CICS-TCAM interface The possible values of TCTTETCM are: Value Message segment X'00' Null X'40' Intermediate portion of message X'F1' First portion of message X'F2' Last portion of message X'F3' Entire message X'F4' Intermediate portion of message, end of record X'F5' First portion of message, end of record X'F6' Last portion of message, end of record X'F7' Entire message, end of record X'FE' TCAM is not active X'FF' INQUIRE attempted on non-TCAM terminal.
the CICS-TCAM interface locked until a TCTTE becomes available because the task has ended. The number of TCTTEs in the pool influences the degree of multitasking. You should consider providing enough terminal entries in the pool to avoid an ‘unsolicited input’ condition (see “TCAM queues” on page 703), because there is no available entry in the pool. When DFHTCAM scans for a free entry, it does not scan the entire table because it carries a pseudo-end-of-table value.
the CICS-TCAM interface 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. To keep messages flowing smoothly through the queue, it is essential that each message be processed as soon as it arrives.
the CICS-TCAM interface To allow processing of input to continue, DFHTEP may take either of the following steps: v If the input line is placed in service by DFHTEP, the CICS-TCAM interface retries the operation. In this case, a count mechanism is recommended in DFHTEP to prevent a loop occurring if the task never issues a READ, or a TCTTE never becomes available. v Perhaps when a count limit is reached, DFHTEP might abend the task, dispose of the data, and place the line in service.
TCAM devices The terminal services parameters that do not set bits in the communication control byte are SEND, WAIT TERMINAL, and SAVE. Bits in the communication control byte are set for the ISSUE DISCONNECT and CONVERSE parameters, and for the FMH and LAST parameters on the EXEC CICS SEND command. The CICS-TCAM interface does not support the RESET parameter or the 3270 parameters READB and COPY. All messages to TCAM from CICS are prefixed with the standard CICS-TCAM communication area.
TCAM devices Device-dependent data Dependent on the device: 3270, or other. See the following sections on the relevant devices. FMH Function management header. SNA only = length in first byte non-SNA = not applicable. Message User data. TCAM with 3270 devices The CCB and device-dependent data for an input message from TCAM to CICS have the following format: CCB1 1 byte SNA only CCB2 1 byte SNA only Attention identifier 1 byte CURSOR 2 bytes The CCB is present for TCAM SNA lines only.
TCAM user exits TCAM user exits There are three TCAM global user exit points: 1. XTCATT, invoked before issuing a transaction manager ATTACH for a transaction identification received in response to polling 2. XTCTIN, invoked following the completion of any TCAM input event, (that is, after the individual TCTTE has been located, but just before CICS checks to see if a task is attached to the TCTTE) 3. XTCTOUT, invoked for output events before placing data on the TCAM output process queue.
starting and terminating TCAM 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-TCAM program interrelationship CICS and TCAM: program interrelationship Figure 104 illustrates the interrelationship between the TCAM message control program (MCP) and the TCAM application program. CICS is regarded as an application program by TCAM.
CICS-TCAM program interrelationship TCAM message control program (non-SNA) This section gives an example of a non-SNA TCAM message control program. This MCP shows the relationship between the MCP definition and the CICS terminal control table generation. It should not be construed as a typical or usable MCP for CICS. For further information about MCP definition for a variety of devices, see the ACF/TCAM Installation and Migration Guide.
S75A POLLST1 POLLST2 POLL70R * TOTCAM * MH3270 SOH TOCICS DCBOFLGS TERMINAL QBY=T,DCB=PG3270,RLN=1,TERM=327R,QUEUES=MO, ADDR=E2E240402D,NTBLKSZ=1856 INVLIST ORDER=(TRM1+02) INVLIST ORDER=(TRM2+02) INVLIST ORDER=(T32C-C1C17F7F2D,S70A+C1C140402D, S70B+C1C1C1C12D, S75A+C2C27F7F2D,S75A+C2C240402D), EOT=37 STARTMH LC=OUT INHDR CODE FORWARD DEST=C'RIS1' INMSG INEND OUTHDR OUTEND * * * * 2260 MH PROCESS INCOMING MSG HEADER PROCESS INCOMING COMPLETE MSG END OF INCOMING SECTION PROCESS OUTGOING MSG HEADER E
712 CICS TS for OS/390: CICS Customization Guide
Chapter 27. The dynamic allocation sample program This chapter suggests ways in which you can customize the dynamic allocation sample application program, used to allocate or deallocate data sets dynamically. It is divided into the following sections: 1. “Overview of the dynamic allocation program” 2. “Installing the program and transaction definitions” on page 714 3. “Terminal operation” on page 714 4. “Help feature” on page 715 5. “Values” on page 715 6.
the dynamic allocation sample program v Have read the relevant sections of the MVS/ESA SPL: Application Development Guide and have that manual available for reference while using the sample program, in particular for looking up error and reason codes returned by DYNALLOC. The application uses a 3270 display screen terminal, and adjusts its formatting to suit the screen size. BMS is not required.
help feature Help feature The program includes a limited “help” feature, driven by the program’s keyword table. In response to “?”, the verb keywords are displayed. In response to “verb?”, all the operand keywords of that verb are displayed. For “verb operand(?)” a short description of the value expected for that operand is displayed. When a command containing “?” is entered, no DYNALLOC SVC is issued. “?” is recognized only in the positions specified above; the rest of the command is ignored.
keywords and values Maximum and minimum lengths For character and numeric values, the maximum and minimum lengths of the value are checked by the program. For a fixed-length string, these values are the same. The value is still passed to DYNALLOC as specified. Convertible to n byte binary A numeric value is required, of a magnitude representable in binary in the specified number of bytes. Values that are too large are truncated to the maximum possible for the width.
DYNALLOC flow of control The flow of control when a DYNALLOC request is issued The flow in a normal invocation is as follows. The main program, DFH99M, receives control from CICS and carries out initialization. This includes determining the screen size, allocating input and output buffer sections, and issuing initial messages. It then invokes DFH99GI to get the input command from the terminal. Upon return, if the command was null, the main program terminates, issuing a final message.
DYNALLOC flow of control returned value corresponds to a keyword value, DFH99KR is called to look up the value in the description, and issue the message. Processing of the command is now complete, and the main program is reinitialized for the next one, and loops back to the point where it calls DFH99GI. Messages are issued at many places, using macros. The macro expansion ends with a call to DFH99MP, which ensures that a new line is started for each new message, and calls DFH99ML, the message editor.
Part 7. Customizing CICS security processing © Copyright IBM Corp.
General notes The following comments apply to the chapters in Part 7 of this book: v The only aspects of CICS security processing covered are: – Invoking a user-written external security manager – Writing a “good night” transaction. For a comprehensive view of security processing using the Resource Access Control Facility (RACF) product, see the CICS RACF Security Guide.
Chapter 28. Invoking a user-written external security manager CICS provides an interface to an external security manager (ESM), which may be user-written or may be the Resource Access Control Facility (RACF) program product. This chapter gives an overview of the CICS-ESM interface, and describes how you can use the MVS router exit to pass control to a user-written ESM. It describes how ESM exit programs can access CICS-related information. Finally, it lists the control points at which CICS invokes the ESM.
the MVS router The MVS router exit The MVS router provides an optional installation exit that is invoked whether or not RACF is installed and active on the system. If your installation does not use RACF, you can use the router exit to pass control to your own ESM. If you do use RACF, you could use the exit for preprocessing before RACF is invoked. The MVS router exit routine is invoked whenever CICS (or another component of your system) issues a RACROUTE macro.
the MVS router Router exit return codes Your exit routine must return a return code in register 15. The hexadecimal values of the return code are shown in Table 35. Table 35. MVS router exit return codes Code Meaning 0 The exit has completed successfully. Control proceeds to the RACF front-end routine for further security processing and an invocation of RACF. C8 The exit has completed successfully.
ESM exit programs 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.
ESM exit programs Table 37. Obtaining the address of the installation data parameter list RACROUTE REQUEST type VERIFY AUTH FASTAUTH LIST EXTRACT RACF exit Exit list mapping macro Parameter list field name ICHRIX01 ICHRIXP RIXINSTL ICHRIX02 ICHRIXP RIXINSTL ICHRCX01 ICHRCXP RCXINSTL ICHRCX02 ICHRCXP RCXINSTL ICHRFX01 ICHRFXP RFXANSTL ICHRFX02 ICHRFXP RFXANSTL ICHRLX01 ICHRLX1P RLX1INST ICHRLX02 ICHRLX2P RLX2PRPA See note 2. Not available Not available None Notes: 1.
ESM exit programs UXPBLKID The name of the block identifier (UXPARMS). UXPPHASE Address of a 1-byte code that indicates the reason for the call to the ESM (that is, the security event being processed). The code can have one of the following values: DEFAULT_SIGN_ON (X'01') Signon of default userid PRESET_SIGN_ON (X'02') Signon of preset security terminal IRC_SIGN_ON (X'03') Link signon for IRC (MRO) links LU61_SIGN_ON (X'04') Link signon for LUTYPE6.
ESM exit programs USER_RESOURCE_CHECK (X'60') Resource checking for user LINK_RESOURCE_CHECK (X'61') Resource checking for link USER_QUERY_CHECK (X'70') Query checking for user LINK_QUERY_CHECK (X'71') Query checking for link INITIALIZE_SECURITY (X'80') Initialization of CICS security REBUILD_SECURITY (X'81') CEMT or command-level SECURITY REBUILD XRF_TRACK_INITIALIZE (X'82') XRF tracking of initial or rebuild. UXPSUBSY Address of an area containing the CICS subsystem identifier.
CICS security control points RACROUTE REQUEST=VERIFY Issued at operator signon (with the parameter ENVIR=CREATE), and at sign-off (with the parameter ENVIR=DELETE). This macro creates or destroys an access control environment element (ACEE). It is issued at the following CICS control points: Normal signon through EXEC CICS SIGNON Signon of the default userid DFLTUSER Signon of preset security terminals Signon of MRO sessions Signon of LUTYPE6.
CICS security control points v After a call to FASTAUTH indicates an access failure that requires logging. v When a QUERY SECURITY request with the RESCLASS option is used. This indicates a request for a resource for which CICS has not built in-storage profiles. (If CICS has in fact built in-storage profiles, REQUEST=AUTH uses them.) RACROUTE REQUEST=LIST Issued to create and delete the in-storage profile lists needed by REQUEST=FASTAUTH. (One REQUEST=LIST macro is required for each resource class.
early verification processing APPL The APPLID of the CICS region on which the user is signing on. Which APPLID is passed depends on what is specified as system initialization parameters. INSTLN A pointer to a vector of CICS-related information, which you can map using the DFHXSUXP mapping macro. This pointer is valid only if ESMEXITS=INSTLN is specified as a system initialization parameter for the CICS region.
early verification processing INCLUDE INCLUDE ORDER ENTRY SYSLIB(DFHXSEAI) SYSLIB(DFHEAI) DFHEAI,verify-program,DFHEAI0 verify-program The DFHEIENT and DFHEIRET macros are inserted by the CICS translator unless you specify *ASM XOPTS(NOPROLOG,NOEPILOG) as the first statement of the program. The DFHEIENT macro assumes that register 15 points to its first executable instruction. Upon return from the DFHEIENT macro, a CICS storage area mapped by the DFHEISTG macro has been established.
732 CICS TS for OS/390: CICS Customization Guide
Chapter 29. Writing a “good night” program You can use the GNTRAN system initialization parameter to specify a “good night” transaction that you want CICS to invoke when a user’s terminal-timeout period expires. The default value for GNTRAN is 'NO', which means that CICS does not schedule a “good night” transaction, but instead tries to sign off the terminal user. (Whether or not the sign off is successful depends on the value of the SIGNOFF attribute on the terminal’s TYPETERM definition.) Notes: 1.
writing a good night program DFHSNGS DFHSNGS_FIXED GNTRAN_START_TRANSID GNTRAN_PSEUDO_CONV_FLAG GNTRAN_SCREEN_TRUNCATED GNTRAN_TRANSLATE_TIOA GNTRAN_TIMEOUT_TIME GNTRAN_TIMEOUT_REASON GNTRAN_PSEUDO_CONV_TRANSID GNTRAN_SCREEN_LENGTH GNTRAN_CURSOR_POSITION GNTRAN_SCREEN_WIDTH GNTRAN_SCREEN_HEIGHT GNTRAN_USER_FIELD DFHSNGS_VARIABLE GNTRAN_SCREEN_BUFFER DS 0CL64 Fixed part of parameter list DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS CL4 CL1 CL1 CL1 CL9 CL8 CL1 CL11 CL4 FL2 FL2 FL2 FL2 CL16 0X 0X TRAN
writing a good night program GNTRAN_PSEUDO_CONV_TRANSID The identifier of the next transaction, if the terminal timed out during a pseudoconversational sequence. (If the terminal did not time out during a pseudoconversational sequence, the value of this field is meaningless.) GNTRAN_SCREEN_LENGTH The length of the screen buffer. GNTRAN_CURSOR_POSITION The cursor position. GNTRAN_SCREEN_WIDTH The width of the screen in use when the terminal timed out.
sample good night program What the sample program does The DFH0GNIT sample program: 1. Checks that it has been invoked for a terminal timeout, by testing the GNTRAN_START_TRANSID field of the communications area passed by CICS. If this contains anything other than 'CEGN', it quits. 2. If a flag within GNTRAN_USER_FIELD shows that this is the first invocation for this timeout: a.
sample good night program | | | | | | | | | | v Your program should always start, like the sample program, by testing the GNTRAN_START_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 START 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.
A general note about user-written programs The following comment applies to all user-written programs mentioned in Part 8 of this book: v Upon return from any customer-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information).
Chapter 30. User programs for the system definition utility program (DFHCSDUP) This chapter tells you how to write programs for use with the CICS system definition utility program (DFHCSDUP). It is divided into the following sections: 1. “An overview of DFHCSDUP” contains background information. 2. “DFHCSDUP as a batch program” on page 742 describes the DFHCSDUP EXTRACT command, and tells you how to write a user program to be invoked from DFHCSDUP. 3.
user programs for DFHCSDUP DFHCSDUP as a part of the resource definition process is described in the CICS Resource Definition Guide. Guidance information about the execution JCL for DFHCSDUP, and the formats of the DFHCSDUP commands, are given in the CICS Operations and Utilities Guide. DFHCSDUP as a batch program This section refers to DFHCSDUP as a batch program. It describes the DFHCSDUP EXTRACT command, and the three sample programs that can be invoked during EXTRACT processing.
DFHCSDUP as a batch program 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. You must supply a USERPROGRAM value.
DFHCSDUP as a batch program 0 2 4 6 8 10 12 14 16 Initial call List start call Group start call Object start call Keyword detail call Object end call Group end call List end call 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.
DFHCSDUP as a batch program Table 39. Sample EXTRACT user programs for the DFHCSDUP utility program Program names Languages Description DFH$CRFA 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.
DFHCSDUP as a batch program The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) or: EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword. For this program only, in addition to the EXTRACT command, you must define, in a sequential data set, the objects and keywords for which you want a cross-reference listing.
DFHCSDUP as a batch program The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) or: EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword. Note the following points when using DFH0CBDC: v It can deal with only one set of data during each invocation of DFHCSDUP; if two EXTRACT commands are issued, the second set of data overwrites the first.
DFHCSDUP as a batch program 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. //DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid //* . //* Assembler job step here //* . //LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET' //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLIB DD DSN=CICSTS13.CICS.SDFHLOAD,DISP=SHR //SYSLMOD DD DSN=user.
DFHCSDUP as a batch program 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. //DFHCRFC JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid // . // COBOL compile job step here // . //LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET' //SYSLIB DD DSN=SYS1.COBOL2.COB2LIB,DISP=SHR //CICSLIB DD DSN=CICSTS13.CICS.SDFHLOAD,DISP=SHR //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLMOD DD DSN=user.
DFHCSDUP as a batch program 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. //DFHCRFP JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid //* . //* PL/I compile job step here //* . //LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET' //SYSLIB DD DSN=object.module.library,DISP=SHR // DD DSN=SYS1.PLI.PLIBASE,DISP=SHR // DD DSN=CICSTS13.CICS.SDFHLOAD,DISP=SHR //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLMOD DD DSN=user.
DFHCSDUP as a batch program | A Language Environment version | | | | The sample job in Figure 110 shows the link-edit statements you need for a DFHCSDUP user program written in a Language Environment/370 (LE)-conforming high-level language. //DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid //* . //* Compile job step here //* . //LINK EXEC PGM=IEWL,PARM='XREF,LIST,LET' //SYSLIB DD DSN=PP.ADLE370.OS39025.SCEELKED //CICSLIB DD DSN=CICSTS13.CICS.CICS.
invoking DFHCSDUP from a user program Notes: 1. In a TSO environment, it is normally possible for the terminal operator to interrupt processing at any time by means of an ATTENTION 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.
invoking DFHCSDUP from a user program The length of the page number data (field ‘bb’ in Figure 111) must be 0 or 4. The page number, if supplied, must be four numeric EBCDIC characters. The field, if present, is updated upon exit from DFHCSDUP with a number one greater than that of the last page printed. DCBS The addresses of a set of data control blocks for use internally by DFHCSDUP. Any DCBs (or ACBs) that you specify are used internally, instead of those normally used by DFHCSDUP.
invoking DFHCSDUP from a user program 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 v v v If the ‘bb’ field for any parameter is zero, the parameter is ignored. If a subentry in the functional data is all binary zeros, it is ignored. If any subentry is not within the length indicated by ‘bb’, it is ignored.
invoking DFHCSDUP from a user program The user exit points in DFHCSDUP There are five user exit points in DFHCSDUP. By specifying the appropriate entry parameters, you can cause DFHCSDUP to pass control to an exit routine at any of these points. None of the user exits supports XPI calls. Parameters passed to the user exit routines The address of a parameter list is passed to the user exit routine in register 1.
invoking DFHCSDUP from a user program The get-command exit The purpose of the get-command exit is to read in command lines. If it is specified, no commands are read from SYSIN. On invocation, your exit routine must supply the address and length of a complete command. It must return control with either the normal return code ‘UERCNORM’ or with the code ‘UERCDONE’, signifying that it has no more commands to pass.
invoking DFHCSDUP from a user program The extract exit The extract exit is invoked at various points during processing of the EXTRACT command. The points are listed on page 743. Notes: 1. If you do not specify an EXTRACT user exit routine on the entry linkage to DFHCSDUP, or on the USERPROGRAM keyword, a syntax error occurs. 2. A user exit routine specified on the USERPROGRAM keyword is used in preference to one specified on the entry linkage.
invoking DFHCSDUP from a user program to the user program” on page 743.) However, when DFHCSDUP is invoked from a user program, the parameter list also includes the standard parameters mentioned under “Parameters passed to the user exit routines” on page 755. Return codes UERCNORM (X'00') Continue processing. UERCERR Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’. XPI calls Must not be used.
invoking DFHCSDUP from a user program 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 ATTENTION interrupt. (See “Invoking DFHCSDUP from a user program” on page 751.) Or you could use it to provide messages in the operator’s national language.
invoking DFHCSDUP from a user program The termination exit The purpose of the termination exit is to allow you to perform final housekeeping duties. It is invoked before a normal or an abnormal termination of DFHCSDUP. When invoked Invoked once, before termination of DFHCSDUP. Exit-specific parameters UEPTRMFL Address of a 1-byte field that indicates the mode of termination. Its possible values are: X'00' Normal termination X'F0' Abnormal 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.
the programmable interface to CEDA Notes: 1. An attempt to start CEDA from an application program by an EXEC CICS START command must fail. This is because CEDA’s first action is to request input from its associated terminal, whereas an automatically initiated transaction must first send data to the terminal. An attempt to start CEDA under CECI by an EXEC CICS START command fails for similar reasons. 2. The RDO command passed in address 1 of the CEDAPARM parameter list must be valid.
DFHEDAP in a DTP environment from a back-end application program whose session is in SEND state (and which has never issued a SYNCPOINT), the session will be put into RECEIVE state. If the code invoked by DFHEDAP then issues a SYNCPOINT, an abend occurs. This can be prevented by all DTP applications issuing a SYNCPOINT request when they get into SEND state (on all of their sessions) and before they issue the LINK DFHEDAP command.
764 CICS TS for OS/390: CICS Customization Guide
Part 9. Appendixes © Copyright IBM Corp.
766 CICS TS for OS/390: CICS Customization Guide
Appendix A. Coding entries in the VTAM LOGON mode table This appendix shows you what to code in your VTAM 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. “VTAM MODEENT macro operands” on page 770 4. “PSERVIC screen size values for LUTYPEx devices” on page 775 5. “Matching models and LOGON mode entries” on page 776 6.
TYPETERM device types TYPETERM device types and pointers to related LOGON mode data Search Table 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 Table 41 on page 770, what has to be coded on the VTAM MODEENT macros. Note that Table 40 is a complete list of TYPETERM device types; not all of these can be used with autoinstall. Those that cannot are marked with an asterisk (*).
TYPETERM device types Table 40.
VTAM MODEENT macro operands VTAM MODEENT macro operands Table 41 VTAM LOGON mode table entry for each TYPETERM you might define. You should have reached this table by looking up the TYPETERM device types in Table 40 on page 768. Look down the left hand side of the table for the reference number (RN) that brought you here from Table 40 on page 768. When you find it, look across to the middle column. This shows the macro operands that affect the way CICS handles automatic installation.
VTAM MODEENT macro operands Table 41. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 5 FMPROF=X'04' TSPROF=X'03' PRIPROT=X'B1' SECPROT=X'90' COMPROT=B'0110.000 00000.00' 6 FMPROF=X'04' TSPROF=X'04' PRIPROT=X'31' SECPROT=X'30' COMPROT=B'0110.000 00000.00' 7 FMPROF=X'04' TSPROF=X'04' PRIPROT=X'B0' SECPROT=X'30' COMPROT=B'0100.000 00000.00' 8 FMPROF=X'03' TSPROF=X'03' PRIPROT=X'B1' SECPROT=X'90' COMPROT=B'0011.
VTAM MODEENT macro operands Table 41. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 13 FMPROF=X'03' TSPROF=X'03' PRIPROT=X'B1' SECPROT=X'B0' COMPROT=B'0011.000 10000.00' PSERVIC=X'01' 14 15 772 FMPROF=X'03' TSPROF=X'04' PRIPROT=X'B1' SECPROT=X'B0' COMPROT=B'0111.000 PSERVIC=B'00000001 ........ 00000000 10000.00' 00110001 00011000 0100000. 00000000 10010010 00000000 ........
VTAM MODEENT macro operands Table 41. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 18 FMPROF=X'03' TSPROF=X'03' PRIPROT=X'B1' SECPROT=B'10..0000' COMPROT=B'0011.000 10000.
VTAM MODEENT macro operands Table 41. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 23 FMPROF=X'04' TSPROF=X'04' PRIPROT=X'B1' SECPROT=X'B0' COMPROT=B'0111.000 00000.00' 24 TYPE=X'00' FMPROF=X'13' TSPROF=X'07' PRIPROT=X'B0' SECPROT=X'B0' COMPROT=B'101.000 10110.01' PSERVIC='00000110 00000010 ........ 00000000 00000000 00000000 ........ 00000000 00000000 00000000 ........ 0010..
PSERVIC screen size values PSERVIC screen size values for LUTYPEx devices Table 42 is to help you decide what screen size values you should specify on the PSERVIC operand of the VTAM MODEENT macro, for LUTYPE0, LUTYPE2, and LUTYPE3 devices. If, on your CICS TYPETERM definition, you code the values shown in columns 1 through 4 of Table 42, the screen size values in the CICS model bind image are as shown in column 5. The values you code for screen sizes on the PSERVIC operand must match this. Table 42.
PSERVIC screen size values Table 43.
matching models and LOGON mode entries AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3278 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3278 GROUP ==> PDATD DEVICE ==> 3270 TERMMODEL ==> 2 LIGHTPEN ==> YES AUDIBLEALARM ==> YES UCTRAN ==> YES IOAREALEN ==> 2000,2000 ERRLASTLINE ==> YES ERRINTENSIFY ==> YES USERAREALEN ==> 32 ATI ==> YES TTI ==> YES AUTOCONNECT ==> NO LOGONMSG ==> YES BIND SENT BY CICS depends on PSERVIC value on LOGMODE definition above: EITHER : 0102027
matching models and LOGON mode entries LOGONMSG DISCREQ RECEIVESIZE BUILDCHAIN ==> ==> ==> ==> YES YES 256 YES BIND SENT BY CICS : 010303B1 B0308000 0085C780 00028000 00000018 5018507F 00000000 00000000 ****************************************************************** 3) 3770 BATCH LU (3777) ****************************************************************** BATCH MODEENT LOGMODE=BATCH, 3770 BATCH TYPE=1, FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'B0', COMPROT=X'7080', PSERVIC=X'01310C70E100D
matching models and LOGON mode entries TERMINAL definition ************************* AUTINSTNAME ==> M6670 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T6670 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T6670 GROUP ==> PDATD DEVICE ==> LUTYPE4 BUILDCHAIN ==> YES DISCREQ ==> YES RECEIVESIZE ==> 256 UCTRAN ==> YES IOAREALEN ==> 256,4096 FORMFEED ==> YES HORIZFORM ==> YES VERTFORM ==> YES ATI ==> YES TTI ==> YES PAGESIZE ==> 50,80 AUTOPAGE ==> YES LOGONMSG ==> NO LDCLIST =
matching models and LOGON mode entries PRIPROT=X'B1', SECPROT=X'B0', RUSIZES=X'8585', COMPROT=X'7080' TERMINAL definition ************************* AUTINSTNAME ==> M3790A AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3790A INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3790A GROUP ==> PDATD DEVICE ==> 3790 SENDSIZE ==> 256 RECEIVESIZE ==> 256 SESSIONTYPE ==> USERPROG BRACKET ==> YES IOAREALEN ==> 256 ATI ==> YES TTI ==> YES BIND SENT BY CICS : 010404B1 B0708000 00858580
matching models and LOGON mode entries BIND SENT BY CICS : 010304B1 B0708000 00858580 00013118 40000092 0000E100 50000000 00000000 ****************************************************************** 7) 3790 SCSPRT ****************************************************************** S3790C MODEENT LOGMODE=S3790C, 3790 WITH SCS TYPE=1, FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'B0', COMPROT=X'3080', RUSIZES=X'8585', PSERVIC=X'010000000000000000000000' TERMINAL definition ************************* AUT
matching models and LOGON mode entries ATI TTI BRACKET RECEIVESIZE SENDSIZE ==> ==> ==> ==> ==> YES YES YES 256 256 BIND SENT BY CICS : 010303B1 90308000 00000080 00010000 ****************************************************************** 9) 3650 INTERPRETER LU (SESTYPE = USERPROG BRACKET = YES) ****************************************************************** S3650A MODEENT LOGMODE=S3650A, 3650 SESTYPE=USERPROG TYPE=1, BRACKET=YES FMPROF=X'04', TSPROF=X'04', PRIPROT=X'31', SECPROT=X'30', COMPROT=X'60
matching models and LOGON mode entries SESSIONTYPE RELREQ DISCREQ IOAREALEN BRACKET RECEIVESIZE ATI TTI ==> ==> ==> ==> ==> ==> ==> ==> 3270 YES YES 256 YES 240 NO YES BIND SENT BY CICS : 010403B1 90600000 00000080 00000000 ****************************************************************** 11) 3650 HOST CONVERSATIONAL (3653) LU (N.B.
matching models and LOGON mode entries DEVICE SESSIONTYPE BRACKET RELREQ DISCREQ RECEIVESIZE IOAREALEN ATI TTI ==> ==> ==> ==> ==> ==> ==> ==> ==> 3650 USERPROG NO NO NO 256 256 YES YES BIND SENT BY CICS : 01040430 30400000 00000080 00000000 ****************************************************************** 13) 8815 SCANMASTER (APPC SINGLE SESSION) ****************************************************************** SIN62 MODEENT LOGMODE=SIN62, 8815 SCANMASTER.
matching models and LOGON mode entries AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3290 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3290 GROUP ==> PDATD DEVICE ==> LUTYPE2 TERMMODEL ==> 2 ALTSCREEN ==> 62,160 DEFSCREEN ==> 24,80 AUDIBLEALARM ==> YES UCTRAN ==> YES IOAREALEN ==> 2000,2000 ERRLASTLINE ==> YES ERRINTENSIFY ==> YES USERAREALEN ==> 32 ATI ==> YES TTI ==> YES LOGONMSG ==> YES ERRHILIGHT ==> BLINK RECEIVESIZE ==> 1024 BIND SENT BY CICS : 010303B1 90308000
matching models and LOGON mode entries 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 VTAM LOGON mode table definitions that match the CICS-supplied TYPETERM and model TERMINAL definitions for autoinstall. The first six entries are example definitions; that is, they are not supplied with VTAM.
matching models and LOGON mode entries DFHLU2 MODEENT LOGMODE=DFHLU2, SNA LUTYPE2 3270 TYPE=1, FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'B0', COMPROT=X'3080', RUSIZES=X'85C7', PSERVIC=X'028000000000000000000300' The following entries are those LOGMODE definitions supplied by VTAM that match CICS-supplied TYPETERM definitions.
matching models and LOGON mode entries DFHLU2E3 MODEENT LOGMODE=SNX32703, LU2 model 3 queryable FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'90', COMPROT=X'3080', RUSIZES=X'87F8', PSERVIC=X'028000000000185020507F00' DFHLU2E4 MODEENT LOGMODE=SNX32704, LU2 model 4 queryable FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1', SECPROT=X'90', COMPROT=X'3080', RUSIZES=X'87F8', PSERVIC=X'02800000000018502B507F00' DFHLU2M2 MODEENT LOGMODE=D4A32782, LU2 model 2 nonqueryable FMPROF=X'03', TSPROF=X'03', PRIPROT=X'B1',
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 VTAM. In most cases, DFHZNAC issues messages and sets one or more “action flags” in the communication area passed to the node error program, DFHZNEP.
default actions of DFHZNAC Table 44.
default actions of DFHZNAC Table 44.
default actions of DFHZNAC Table 44.
default actions of DFHZNAC Table 44.
default actions of DFHZNAC Table 44.
default actions of DFHZNAC Notes: 1. See message DFHZC2497 or DFHZC3493, depending on the device type. 2. “Good morning” message to be sent. 3. Cancel task, and close VTAM session owing to quick close or abend. CICS messages associated with VTAM errors Table 45.
default actions of DFHZNAC Table 45.
default actions of DFHZNAC Table 45.
default actions of DFHZNAC Table 45.
default actions of DFHZNAC Table 45.
default actions of DFHZNAC Table 45.
default actions for system sense codes Table 46.
default actions for system sense codes 3. Action flags 2 and 3 are set for negative response received for a SEND that requested a definite response. 4. Presentation space error. 5. Presentation error on read. Display buffer alteration, due to operator intervention, detected on a READ command to a compatibility-mode logical unit. 6. Function abend received from a device. A negative response to a chain was sent, but purged.
Appendix C. Transient data write-to-terminal program (DFH$TDWT) DFH$TDWT is a sample program that sends transient data messages to a terminal or printer. You can use it to send messages from a single transient data queue, or from several queues, to one terminal. In the definition for the transient data queue, you can specify that particular categories of message (for example, those from the abnormal condition program and signon and sign-off messages) should be sent to destinations defined as indirect.
804 CICS TS for OS/390: CICS Customization Guide
Appendix D. Uppercase translation This appendix describes how to translate lower- and mixed-case characters to uppercase. “Uppercase translation of national characters” describes how to translate national characters that CICS cannot handle by standard means. “TS data sharing messages” on page 806 describes how to translate operator messages produced by CICS temporary storage data sharing.
uppercase translation MACRO NATLANG DFHUCTRT CSECT Resume UCTRAN table CSECT .* .* This example translates lowercase 'a' ( EBCDIC X'81') to .* uppercase 'A' (EBCDIC X'C1') for a US code page. .* ORG TCZUCTAB+X'81' Reset the counter to the character to be translated. DC X'C1' Declare the replacement character as a constant. .* .* Repeat the above two statements for each extra character you wish .* to be translated. .
Appendix E. The example program for the XTSEREQ global user exit, DFH$XTSE This appendix lists the example global user exit program, DFH$XTSE. The example shows you how to: v Use EXEC CICS commands in a global user exit program v Use EXEC CICS commands and XPI calls in the same exit program v Modify the command parameter list in EXEC interface exits such as XTSEREQ, XICEREQ, and XFCREQ v Modify Temporary Storage (TS) requests.
example XTSEREQ global user exit program * * * It is not safe to use the following storage: * * Program storage (DFHEISTG) since this is freed as soon * * as the exit program returns control to CICS. * * * * 2) When adding or removing a field in the command parameter list, * * you must remember: * * a) To set/clear the field's existence bit in the EID * * b) To set/clear the appropriate address in the Addr_List * * c) To set the hi-order bit in the LAST address in the * * Addr_List.
example XTSEREQ global user exit program *---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries.
example XTSEREQ global user exit program * Registers: * * R1 = UEPAR plist (set on entry) * * = Work register * * R2 = UEPAR plist * * R3 = Program base register (set by DFHEIENT) * * R6 = Linkage register * * R11= EIB register * * R13= EISTG register (set by DFHEIENT) * * R15= Work register * * User Exit Return Code * * * * Logic: * * DFH$XTSE: * * Exec Interface Entry * * Address DFHUEPAR plist * * Set OK Return Code * * Address the EIB * * Trace entry * * Select Exitid * * When(XTSEREQ) then call TS_Requ
example XTSEREQ global user exit program *=====================================================================* * 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.
example XTSEREQ global user exit program *=====================================================================* TS_REQUEST DS 0H * Check for possible recursion L R1,UEPRECUR Address of recursive count LH R1,0(R1) Fetch count LTR R1,R1 Has exit been invoked recursively? BNZ ERROR2 ..Yes Branch to error routine * * Extract pointer to the EID and TS queue name from CLPS L R8,UEPCLPS Fetch address of Command Plist USING TS_ADDR_LIST,R8 Use R8 to address CLPS L R1,TS_ADDR0 Address the EID..
example XTSEREQ global user exit program *=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point * * Free any shared storage that was acquired during previous * * invocation at XTSEREQ.
example XTSEREQ global user exit program *=====================================================================* * 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.
example XTSEREQ global user exit program *=====================================================================* * 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.
example XTSEREQ global user exit program * ROUTE1 * * Update the Sysid in CLPS DS 0H MVC SHARED_SYSID,NEW_SYSID Copy SYSID into shared storage L R8,UEPCLPS Address the CLPS.. USING TS_ADDR_LIST,R8 ..with Register 8 L R1,TS_ADDR0 Address the EID.. USING TS_EID,R1 ..
example XTSEREQ global user exit program * Logic: * * Entry_Not_Found: * * Call Getmain_Shared * * Copy default_sysid into shared storage * * Address the command plist * * Update ADDR7 to point to the address of the default SYSID * * Set the SYSID existence bit in the EID * * Set the Hi-order bit in last address in CLPS * * Return * *=====================================================================* ENTRY_NOT_FOUND DS 0H BAL R6,GETMAIN_SHARED GETMAIN SHARED storage L R12,UEPTQTOK Fetch address of token
example XTSEREQ global user exit program *=====================================================================* * GETMAIN_SHARED - Obtain Shared storage * * * * Registers: * * R0 = Used by EXEC CICS call * * R1 = Used by EXEC CICS call * * Work Register * * R6 = Link Register - Return Address * * R11= EIB register (set on entry) * * R12= Work register * * R14= Used by EXEC CICS call * * R15= Used by EXEC CICS call * * * * Logic: * * Getmain_Shared: * * EXEC CICS GETMAIN LENGTH(32) SET(UEPTQTOK) SHARED RESP
example XTSEREQ global user exit program *=====================================================================* * FREEMAIN_SHARED - Free shared storage * * Free the shared storage associated with this command.
example XTSEREQ global user exit program USING DFHTRPT_ARG,R1 TRACE_ENTRY DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ENTRY) B ISSUE_TRACE TRACE_EXIT DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_EXIT) B ISSUE_TRACE TRACE_ERROR DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ERROR), X DATA1(TR_ERROR_N,1) BAL R6,ISSUE_TRACE B RETURN * *---------------------------------------------------------------------* * Issue the Trace XPI call *
example XTSEREQ global user exit program ERROR4 DS 0H MVI TR_ERROR_N,4 B TRACE_ERROR ERROR5 DS 0H MVI TR_ERROR_N,5 B TRACE_ERROR ERROR6 DS 0H MVI TR_ERROR_N,6 B TRACE_ERROR ERROR7 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR ERROR8 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR ERROR9 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR EJECT , DROP R2 Drop DFHUEPAR DROP R11 Drop EIB LTORG , *********************************************************************** * CONSTANTS * ****************************************************************
TS_ROUTING_TABLE DS 0D ENTRY_NAME_1 DC CL8'AAAAAAAA' NEW_NAME_1 DC CL8'BBBBBBBB' QOR_SYSID_1 DC CL4' ' ACTION_1 DC XL1'01' FILLER_1 DC CL3' ' ENTRY_NAME_2 DC CL8'A1 ' NEW_NAME_2 DC CL8'B1 ' QOR_SYSID_2 DC CL4' ' ACTION_2 DC XL1'01' FILLER_2 DC CL3' ' ENTRY_NAME_3 DC CL8'A2 ' NEW_NAME_3 DC CL8'B2 ' QOR_SYSID_3 DC CL4' ' ACTION_3 DC XL1'01' FILLER_3 DC CL3' ' ENTRY_NAME_4 DC CL8'RRRRRRRR' NEW_NAME_4 DC CL8'REMOTE ' QOR_SYSID_4 DC CL4'MQ1 ' ACTION_4 DC XL1'02' FILLER_4 DC CL3' ' ENTRY_NAME_5 DC CL8'R1 ' NEW_NA
Index Special Characters “good night” transaction customizing the sample program 736 overview 733 sample program, DFH0GNIT 735 Numerics 3270 bridge bridge exit 599 bridge exit program 599 3270 information display system error processors (optional) 468 TCAM 706 unavailable printer DFHZNEP 476 A abends abend and restart, TCAM 707 transaction bit 440 abnormal conditions in terminal error programs 437 sample node error program 465 sample terminal error program 417 user-written node error programs 475 abort wr
automatic installation of terminals control program action at delete 495 action at install 487 action on return 494 information returned to CICS 491 link-edit statements 405 naming 496 testing and debugging 496 parameter list at logon 488 the sample programs customizing 499 DFHZATDX 497 DFHZCTDX 497 DFHZDTDX 497 DFHZPTDX 497 VTAM LOGON mode table 486 automatic installation of virtual terminals control program parameter list at delete 536 parameter list at install 534 introduction 531 B Basic Mapping Suppor
DBCTL (database control) (continued) DFHDBUEX 622 DFHMCT TYPE=EMP entries 661 in an XRF environment 623 interface status 595 DBLID values 620 DD card correlation TCAM 694 DECB, terminal error program information 425 operand 425 DEFAULT operand DFHZNEPI TYPE=INITIAL 479 default threshold count limits DFHTEP (terminal error program) 434 DEFINE PROGRAM function of the XPI 321 defining terminal error blocks 433 DELETE PROGRAM function of the XPI 328 DELETE SUSPEND function of the XPI 308 DEQUEUE function of the
DFHPGADX, user-replaceable autoinstall program (continued) introduction to 546 parameter list at install 543 sample program 546 supplied definition of 547 use of model definitions 540 when invoked 539 DFHPGAQX macro 334 DFHPGISX macro 334 DFHREST, transaction restart program communications area 412 default program 414 introduction 411 link-edit statements 404 transactions suitable for restart 411 when invoked 411 DFHRMCAL macro 249 DFHSAIQX macro 355, 359 DFHSIT (system initialization table) entries for CIC
DFHZNEP, user-replaceable node error program 449 DFHZNEPI macros TYPE=ENTRY 479 TYPE=FINAL 479 TYPE=INITIAL 479 dictionary data section, CICS monitoring records 666, 672 disabling journals 631 dispatcher functions of the XPI 300 display function of the overseer program 610 distributed program link (DPL) dynamic routing of requests changing the program name 559 changing the target region 559 eligibility for routing 557 error handling 561 terminating a request 560 when the routing program is invoked 558 distr
dynamic routing program (DFHDYP) (continued) UOW considerations 553, 562 when invoked 550, 558 dynamic transactions 550 E EDF (Execution Diagnostic Facility) with global user exits 6 with task-related user exits 252 EMP (event-monitoring point) 658 END_BROWSE_PROGRAM function of the XPI 349 ENQUEUE 318 enqueue domain functions of the XPI 318 error group index 467, 473 error groups 452 error processing in node error program (NEP) 465 in terminal error program (TEP) 415 error status block (ESB) 473 error sta
global user exits (continued) in DBCTL interface control program 19 in DBCTL tracking program 40 in dispatcher domain 42 in DL/I interface program 44 in dump domain 49 in enqueue EXEC interface program 57 in EXEC interface program 65 in file control EXEC interface program 70, 83 in file control file state program 96 in file control open/close program 105 in file control quiesce receive program 107 in file control quiesce send program 110 in file control recovery program 112 in Front End Programming Interfac
INQUIRE_TRANDEF function of the XPI 375 INQUIRE_TRANSACTION function of the XPI 383 interactive logical unit error processor 469 intersystem queues controlling the length of using the XISCONA global user exit 127 using the XZIQUE global user exit 237 INTLU error processor 469 ISSUE PASS command 464 ISTINCLM entries for automatic installation 770 J job control for sample DFHTEP generation 426 journal control label header 646 journal module identifiers 652 journal record, old format 648 journal record format
N NAME operand DFHSNEP TYPE=INITIAL 470 DFHSNET macro 473 national characters uppercase translation 805 NEB (node error block) 474 NEBNAME operand DFHSNET macro 473 NEBS operand DFHSNET macro 473 NEP (node error program) 3270 unavailable printer 476 ACF/VTAM error handling background 450 application routing failure 464 common subroutine vector table (CSVT) 474 communication area 458 conventions for registers 472 default actions of DFHZNAC for system sense codes 800 for terminal error codes 789 default node
node error program (NEP) (continued) DFHZNAC logging facility 476 DFHZNEP 450, 457 DFHZNEPI interface module 478 DFHZNEPI macros 478 DFHZNEPI TYPE=INITIAL 479 DSECTs 474 error groups 452 error status blocks 474 error table header 474 in an XRF environment 480 changing the recovery message 482 changing the recovery notification 481 changing the recovery transaction 482 link-edit statements 404 multiple NEPs 455 NEPCLASS 455 NET generation 452 node abnormal condition program 457 node error block, format 468 n
PLTSD programs (continued) general considerations 395 introduction 394 second phase 395 POOL feature, TCAM 701 pool of common TCTTEs 696 PRINT operand DFHTEPM TYPE=INITIAL 428 processing output from CICS statistics 688 program error program (PEP) communication area for assembler-language programs 409 link-edit statements 404 source code 409 writing 407 program list table (PLT) programs general considerations 396 PLTPI programs first phase 393 introduction 393 second phase 394 PLTSD programs first phase 395
SETEOM macro 694 shipped terminals, automatic installation of 523 shutdown (PLTSD) programs considerations when writing 394 shutdown assist program, DFHCESD 396 shutdown assist transaction 396 SMF (system management facility) 662 header 654, 663, 683 product section 654, 683 SNA character string (SCS) 692 specifying processing at EMPs MCT entries for DBCTL 661 START_BROWSE_PROGRAM function of the XPI 346 start-of-run record, journal records 636 START_PURGE_PROTECTION function of the XPI 320 startup, TCAM 70
task-related user exits 280 (continued) schedule flag word 280 SPI parameters 257 stub program 249, 250 ename 251 statname 251 syncpoint manager calls 270 backing out changes 274 committing changes 274 restart resynchronization 274 sample pseudocode 272 syncpoint manager parameters 258 table entries 280 task manager calls 274 limitations 275 task manager parameters 260 UEPCALAM, address of the caller’s AMODE indication byte 255 UEPEIB, address of EIB 254 UEPEXN, address of function definition 253 UEPFLAGS,
TEP (terminal error program) (continued) system count (TCTTENI) 416 user field a (PCISAVE) 445 user field b (PCICNT) 445 DFHTEP tables 432 DFHTEPM TYPE=ENTRY 429 DFHTEPM TYPE=EXIT 430 DFHTEPT TYPE=PERMCODE|ERRCODE 433 error processor source 429 error table 418 errors and actions unique to TCAM 699 generating 425 job control for sample DFHTEP generation 426 link-edit statements 404 replace error processors, DFHTEPM TYPE=ERRPROC 430 sample action flag names 424 common subroutines 421 components 418 DECB infor
termination, TCAM 708 TIE_UP_RECORD_DATA section, journal records 642 TIME operand DFHSNET macro 474 of DFHTEPT TYPE=PERMCODE|ERRCODE macro 434 TPROCESS block 694 trace control functions of the XPI 369 TRACE_PUT function of the XPI 369 trace table entries, global user exit interface 7 transaction abends program error program (PEP) 407 transaction-class error-handling routine 457, 479 transaction control TCAM SNA 693 TRANSACTION DUMP function of the XPI 316 transaction management functions of the XPI 370 tra
XFCAREQC, global user exit (continued) parameter list and return codes 83 XFCBFAIL, global user exit 112 XFCBOUT, global user exit 117 XFCBOVER, global user exit 119 XFCFAIL, global user exit DFH$FCBF sample program 116 XFCLDEL, global user exit 122 XFCNREC, global user exit description 105 parameter list and return codes 106 XFCQUIS, global user exit description 110 XFCREQ, global user exit command parameter structure 71 description 70 example of use 78 parameter list and return codes 79 UEPCLPS parameter
XPI (exit programming interface) (continued) GETMAIN 302 INQUIRE_ACCESS 364 INQUIRE_ELEMENT_LENGTH 365 INQUIRE_SHORT_ON_STORAGE 366 INQUIRE_TASK_STORAGE 367 SWITCH_SUBSPACE 368 trace control function TRACE_PUT 369 transaction management functions INQUIRE_CONTEXT 370 INQUIRE_DTRTRAN 371 INQUIRE_MXT 372 INQUIRE_TCLASS 374 INQUIRE_TRANDEF 375 INQUIRE_TRANSACTION 383 SET_TRANSACTION 387 XRCINIT, global user exit 232 XRCINPT, global user exit 232 XRF (extended recovery facility) node error program 480 overseer p
840 CICS TS for OS/390: CICS Customization Guide
Sending your comments to IBM If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information in this book and the way in which the information is presented.
IBMR Program Number: 5655-147 Printed in the United States of America on recycled paper containing 10% recovered post-consumer fiber.
Spine information: IBM CICS TS for OS/390 CICS Customization Guide Release 3
