CICS Transaction Server for z/OS Customization Guide Version 3 Release 2 SC34-6814-04
CICS Transaction Server for z/OS Customization Guide Version 3 Release 2 SC34-6814-04
Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page 923. This edition applies to Version 3 Release 2 of CICS Transaction Server for z/OS, program number 5655-M15, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 1977, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents 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 . . . . . . . . . . . Syntax notation and conventions used in this book Summary of changes . . . . . . Changes for CICS Transaction Server Changes for CICS Transaction Server Changes for CICS Transaction Server . . . . . . . . . . . . . . . . . . . . . . . .
File control EXEC interface API exits XFCREQ and XFCREQC . . . . . . 85 File control EXEC interface SPI exits XFCAREQ and XFCAREQC . . . . . 98 File control file state program exits XFCSREQ and XFCSREQC . . . . . 111 File control open/close program exit XFCNREC . . . . . . . . . . . 121 File control quiesce receive exit, XFCVSDS . . . . . . . . . . . . . 122 File control quiesce send exit XFCQUIS . . . . . . . . . . . . . . 124 File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and XFCLDEL . .
Recursion within a task-related user exit program. . . . . . . Purging tasks . . . . . . . . . . . . . . . . . . . . Using CICS services in your task-related user exit program . . . Using channels and containers . . . . . . . . . . . . . Assembler programs and LEASM . . . . . . . . . . . . Wait states in your task-related user exit program . . . . . . Work areas . . . . . . . . . . . . . . . . . . . . . Coding a program to be invoked by the CICS SPI . . . . . .
The DEFINE_PROGRAM call . . . . . . The ACQUIRE_PROGRAM call . . . . . The RELEASE_PROGRAM call . . . . . The DELETE_PROGRAM call . . . . . . Log manager XPI functions . . . . . . . . The INQUIRE_PARAMETERS call . . . . The SET_PARAMETERS call . . . . . . Monitoring XPI functions . . . . . . . . . The MONITOR call . . . . . . . . . . The INQUIRE_MONITORING_DATA call . . Program management XPI functions . . . . The INQUIRE_PROGRAM call . . . . . The INQUIRE_CURRENT_PROGRAM call . The SET_PROGRAM call . . . .
Storage keys for PLT programs . . . . . . . . . . . . . . . . . 430 Part 3. Customizing with user-replaceable programs . . . . . . . . . . . . . 433 Chapter 5. General notes about user-replaceable programs 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 . . . . . . . . . . .
Coding for specific VTAM sense codes . . . . . . . . Writing multiple NEPs . . . . . . . . . . . . . . . DFHZNEPI macros . . . . . . . . . . . . . . . . Handling shutdown hung terminals in the node error program Using the node error program with XRF or persistent sessions . The node error program in an XRF environment . . . . . The node error program with persistent session support . . Changing the recovery notification . . . . . . . . . . Changing the recovery message . . . . . . . . . . .
The sample autoinstall control program for APPC connections . . . . . . . 550 Default actions of the sample program . . . . . . . . . . . . . . . 550 Resource definitions . . . . . . . . . . . . . . . . . . . . . 551 Chapter 13. Writing a program to control autoinstall of IPIC connections Autoinstalling IPIC connections: preliminary considerations . . . . . . . The autoinstall user program at INSTALL . . . . . . . . . . . . . . The autoinstall user program at DELETE . . . . . . . . . . . . . .
Routing transactions dynamically . . . . . . . . . . . . . . . . . . Dynamic transactions . . . . . . . . . . . . . . . . . . . . . When the dynamic routing program is invoked . . . . . . . . . . . . Information passed to the dynamic routing program . . . . . . . . . . Changing the target CICS region . . . . . . . . . . . . . . . . . Changing the program name . . . . . . . . . . . . . . . . . . Telling CICS whether to route or terminate a transaction . . . . . . . . If the system is unavailable or unknown .
When the distributed routing program is invoked . . . . . Changing the target CICS region . . . . . . . . . . . Telling CICS whether to route the method request . . . . If an error occurs in route selection . . . . . . . . . . Invoking the distributed routing program on the target region Dealing with a disabled CorbaServer . . . . . . . . . Performing a rolling upgrade of an EJB/CORBA server. . . Routing non-terminal-related START requests . . . . . . . Which requests can be dynamically routed?. . . . . . .
Event codes . . . . . . . . . . The EJB event sample program . . . Actions of the default program . . . Writing your own EJB event program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681 682 682 682 Chapter 25. Writing programs to customize Language Environment run-time options for XPLink programs . . . . . . . . . . . . . . 685 DFHAPXPO . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 28. CICS monitoring . . . . . . Introduction to CICS monitoring . . . . . . How CICS monitoring data is passed to SMF Coding additional event-monitoring points . Application naming event monitoring points . The monitoring control table (MCT) . . . . CICS monitoring record formats . . . . . . SMF header and SMF product section . . . CICS data section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part 8. Examining and modifying resource attributes . . . . . . . . . . . . . 807 Chapter 33. Using the programmable interface to CEDA . . . . . . . . 809 When to use the programmable interface . . . . . . . . . . . . . . . 810 Using DFHEDAP in a DTP environment . . . . . . . . . . . . . . . 810 Chapter 34. User programs for the system definition utility program (DFHCSDUP) . . . . . . . . . . . . . . . . . . . . . An overview of DFHCSDUP . . . . . . . . . . . . . . . .
Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE . . . . . . . . . . . . . . . . . . . . . . . . . 877 Appendix G. Threadsafe XPI commands . . . . . . . . . . . . . . 893 Bibliography . . . . . . . . . . . . The CICS Transaction Server for z/OS library The entitlement set . . . . . . . . . PDF-only books . . . . . . . . . . Other CICS books . . . . . . . . . . Books from related libraries . . . . . . . MVS books . . . . . . . . . . . . VTAM books . . . . . . . . . . .
xvi Customization Guide
Preface What this book is about This book provides the information needed to extend and modify an IBM® CICS® Transaction Server for z/OS® 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.
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. Their meanings are as follows: v Braces { } enclose two or more alternatives, one of which you must code.
Summary of changes This book is based on the CICS Customization Guide for CICS Transaction Server for z/OS, Version 3 Release 1, SC34-6429-00. Changes from that edition are marked by vertical bars in the left margin.
Changes for CICS Transaction Server for z/OS, Version 2 Release 3 The more significant changes for this edition were: v A new global user exit, XICERES, in the interval EXEC interface control program, was described in The XICERES global user exit and “Using the XICERES exit to check the availability of resources on the target region” on page 640.
Part 1. Customizing with user exit programs © Copyright IBM Corp.
2 Customization Guide
Chapter 1. Global user exit programs You can use the CICS global user exit points, in conjunction with programs of a special type that you write yourself (global user exit programs), to customize your CICS system. A global user exit point, sometimes referred to as a global user exit is a place in a CICS module or domain at which CICS can transfer control to a global user exit program that you have written and at which CICS can resume control when your exit program has finished its work.
v Register 13 contains the address of the standard register save area where your exit program should store its own registers immediately after being invoked. This address is also in the field UEPEPSA in the parameter list pointed to by register 1. If you want to issue operating system requests that use register 13 to point to a save area, you must switch register 13 to point to another save area.
An exit program invoked at an exit that does not support the use of EXEC CICS commands must not call a task-related user exit program (TRUE). Calling a TRUE is equivalent to issuing an EXEC CICS command. Exceptions to this rule are programs invoked from the XFCFRIN and XFCFROUT exits, which may call a TRUE. TRUEs are described in Chapter 2, “Task-related user exit programs,” on page 267.
Assembler programs and LEASM Assembler programs translated with the LEASM option cannot be used as global user exit programs. LEASM is used to produce Language Environment conforming main programs in assembler. For information about the LEASM translator option, see the CICS Application Programming Guide. EDF and global user exits If you use the Execution Diagnostic Facility (EDF) to debug your applications, you must take care when compiling exit programs that issue EXEC CICS commands.
v If your global user exit is in a domain, you can add extra trace calls to provide additional diagnostic information by setting the AP option of EXEC CICS SET TRACETYPE to level 1 or 2. v Depending on which exit point you are using, you might be able to use the XPI DFHTRPTX TRACE_PUT macro to create trace entries in the user exit program. This macro is described in Chapter 3, “The user exit programming interface (XPI),” on page 305.
* UEPGAL UEPCRCA UEPTCA UEPCSA UEPEPSA * UEPHMSA * UEPGIND UEPSTACK UEPXSTOR UEPTRACE DS DS DS DS DS A A A A A DS A DS DS DS DS A A A A (ZERO = NO WORK AREA) ADDRESS OF GLOBAL WORK AREA LENGTH ADDRESS OF CURRENT RETURN-CODE RESERVED RESERVED ADDRESS OF REGISTER SAVE AREA FOR USE BY EXIT PROGRAM ADDRESS OF SAVE AREA USED FOR HOST MODULE’S REGISTERS ADDRESS OF CALLER’S TASK INDICATORS ADDRESS OF KERNEL STACK ENTRY ADDRESS OF STORAGE FOR XPI PARAMETERS ADDRESS OF TRACE FLAG UEPEXN points to a 1-byte bi
Apart from register 15, which contains the return code value from the exit program, the values in this save area are used by CICS to reload the registers when returning to the calling CICS module. They should not be corrupted. This address is not passed to global user exit programs invoked from exit points in CICS domains. UEPGIND points to a 3-byte field containing indicators for use in AP domain user exits. For non-AP domain user exits, the indicators are always zero.
Table 1. TCB indicators in DFHUEPAR (continued). Description Symbolic value 2-byte code UEPTX9 X9 Description An X9 open TCB, used for C and C++ programs, compiled with the XPLINK option, that are in user key UEPSTACK points to the kernel stack entry. This value must be moved to the exit program’s register 13 before invoking the XPI. For more information, refer to Chapter 3, “The user exit programming interface (XPI),” on page 305. The storage addressed by this field must not be altered.
If you supply a return code value that is not expected at a particular exit point, the default return code indicating a normal response (usually UERCNORM) is assumed, unless you set the return code UERCPURG. You are strongly advised not to let the return code default to the normal response as the result can be unpredictable. The normal response tells CICS to continue processing as if the exit program had not been invoked, and it is a valid option at most global user exit points.
storage. However, on an EXEC CICS GETMAIN command, the exit program can override the TASKDATAKEY option by specifying either CICSDATAKEY or USERDATAKEY. v When an exit program obtains storage using an XPI GETMAIN call, the storage key depends on the value specified on the STORAGE_CLASS option, which is mandatory, and which overrides the value of TASKDATAKEY.
v Otherwise, use the EXEC CICS ENABLE command to enable the user exit program. If you enable a global user exit program before it has been installed and LPA=YES is specified as a system initialization parameter, CICS scans the LPA for the program. If message DFHLD0109I is issued, it means that CICS was unable to find the program in the LPA and is using the version in DFHRPL or a dynamic LIBRARY. 4. When you have finished using the exit program, you can disable it using the EXEC CICS DISABLE command.
– If the new program supplies a different return code value from the current value addressed by UEPCRCA, CICS ignores both values and resets the “current return code” to the default value, usually UERCNORM, before calling any further exit programs for that exit point.
If a CICS DB2 application program has been written and defined as threadsafe to obtain the benefits of the CICS open transaction environment (OTE), the benefit is lost if TCB switching is caused by a non-threadsafe exit program.
v Share a GWA between global user exit programs, thereby making the information it contains available to more than one program, and overcoming limitations on the size of GWAs. v Access information held in a global user exit program’s GWA. The GWA sample programs and copy books are: DFH$PCEX A sample global user exit program, designed to be invoked at the XPCFTCH exit. CICS also provides copy book DFH$PCGA for use in this sample program.
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. Note that this leaves DFH$PCEX’s global work area still allocated and accessible through the EXEC CICS EXTRACT EXIT command. 3.
Example program As well as the sample programs supplied in source code, there is an example listing, DFH$XTSE, that 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 and XICEREQ. DFH$XTSE is listed on page Appendix F, “The example program for the XTSEREQ global user exit, DFH$XTSE,” on page 877.
DFH$DTRD A sample global user exit program, designed to be invoked at the XDTRD exit. DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data Tables Guide. Related concepts “Data tables management exits XDTRD, XDTAD, and XDTLC” on page 40 Data tables management exits apply to both CICS shared data tables and CICS coupling facility data tables.
a batch update run that has overridden retained locks. See “DFH$FCBV sample global user exit program” on page 134. 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. See “DFH$FCLD sample global user exit program” on page 136. You can define these programs by including the supplied resource group, DFH$FCB, in your startup grouplist, or by using CEDA to install DFH$FCB.
PROXY=proxyurl This optional keyword stores the URL (in the form http://proxyserver) of a proxy server into the Web global work area, then enables the supplied DFH$WBEX sample program as the XWBOPEN global user exit. LDAPBIND=profilename This optional keyword stores the name of an LDAP bind profile into the Web global work area, then enables the supplied DFH$WBX1 sample program as the XWBAUTH global user exit. Note that you cannot specify both LDAPBIND and STS.
racfcid=uuuuuuuu is the current userid, obtained from UEPUSER ibm-httprealm=rrrrrrrr is the HTTP 401 realm, obtained from UEPREALM (if this exists) labeledURI=xxxxxxxx is the target URL, obtained by concatenating “http://” with the hostname from UEPHOST and the path from UEPPATH v v v v v v v v cn=BasicAuth is an arbitrary suffix that is configured into the LDAP server for the purpose of storing Basic Authentication credentials.
Note: It is not necessary to specify a pipeline in the DFHWS-PIPELINE container. The pipeline is dynamically created by DFHPIRT when CHANNEL(DFHWSTC-V1) is specified on the command. v Links to DFHPIRT, specifying CHANNEL(DFHWSTC-V1), after constructing all the required containers. This sends the request to the STS and receives the response into the DFHWS-RESTOKEN container.
Related concepts “The sample XMEOUT global user exit programs” on page 171 The MRO and APPC session queue management sample exit program This sample program implements the same basic function provided by the QUEUELIMIT and MAXQTIME parameters on a connection resource definition.
XPCTA exit, to test whether the abend was caused by a storage protection exception condition. It is described on page “The sample XPCTA global user exit program, DFH$PCTA” on page 191.
Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Topic XDTAD Data tables management When a write request is issued to a data table. “Exit XDTAD” on page 43 XDTLC At the completion of loading of a data table. “Exit XDTLC” on page 44 XDTRD During the loading of a data table, whenever a record is retrieved from the source data set. “Exit XDTRD” on page 41 After the domain closes a transaction dump data set.
Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Topic XFCBFAIL File control recovery control program When an error occurs during the backout of a UOW. “Exit XFCBFAIL, file control backout failure exit” on page 127 XFCBOUT When CICS is about to back out a file update.
Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Topic XICEREQ Interval control EXEC interface program Before CICS processes an interval control API request. “Exit XICEREQ” on page 146 XICEREQC After an interval control API request has completed.
Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Topic XPCABND Program control program After a transaction abend and before a dump call is “Exit XPCABND” made. on page 192 XPCERES Before CICS processes a program link or Link3270 “Exit XPCERES” bridge request that has been dynamically routed to on page 178 this region, where the routing region supports the “resource unavailable” (RESUNAVAIL) condition.
Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked Topic XSZARQ Front End Programming Interface After a FEPI request has completed. “Front End Programming Interface exits XSZARQ and XSZBRQ” on page 137 Before a FEPI request is actioned. “Front End Programming Interface exits XSZARQ and XSZBRQ” on page 137 Before task attach. “Exit XTCATT” on page 224 XTCIN After an input event.
Table 2. Alphabetical list of global user exit points (continued) | Exit name Module or domain Where or when invoked Topic XWBAUTH Web domain During processing of an EXEC CICS WEB SEND command. “HTTP client open and send exits: XWBAUTH, XWBOPEN and XWBSNDO” on page 138 XWBOPEN During processing of an EXEC CICS WEB OPEN or EXEC CICS INVOKE WEBSERVICE command. “HTTP client open and send exits: XWBAUTH, XWBOPEN and XWBSNDO” on page 138 XWBSNDO During processing of an EXEC CICS WEB SEND command.
Global user exit points by functional area The exit points are grouped according to their functional relationships. This usually means according to the CICS module or domain in which they occur. However, where exit points in different modules serve a similar function, the exits are grouped under a generic name. The groups of exits are presented in alphabetical order of module or generic name.
Return codes UERCNORM Continue processing. XPI calls XPI must not be used. API and SPI calls The following commands are supported: v ADDRESS CWA v ADDRESS EIB v LINK (but only to local programs; distributed program links may not be used). v RETURN v WRITE JOURNALNAME. Application Associated Data exit, XAPADMGR, in the AP domain Use the XAPADMGR exit for distributed transactions.
UERCNORM Continue processing. XPI calls All can be used. API and SPI calls All can be used, except for: v EXEC CICS ABEND v EXEC CICS PERFORM SHUTDOWN Sample exit program, DFH$APAD CICS provides a sample global user exit program, DFH$APAD, for use at the XAPADMGR exit point. The exit program is invoked, if enabled, when non-system tasks for which no input Origin Descriptor Record is provided are attached.
v Use the mapset name, map name, and field length defined in the map, and the actual length of field data placed in the outbound datastream v Modify the data in each field v Modify the attributes sent with each field. Both exits are passed four exit-specific parameters: 1. The address of the TCTTE associated with the mapping request 2. The address of the system EIB associated with the task issuing the mapping request 3.
UEPBMTCT Address of the TCTTE associated with the mapping request. UEPEXECB Address of the system EIB associated with the task. UEPBMCNT Address of the halfword binary number of “field elements” in the field element table. UEPBMTAB Address of the field element table. Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used.
BMXACTLN is a halfword binary value which contains the actual length of the data received or transmitted in this field. BMXDATA is the address of the field data. In the XBMIN exit, BMXDATA points into a work area which BMS has obtained for input mapping purposes. When the exit returns control, this work area is copied to the application data structure associated with this map. In the XBMOUT exit, BMXDATA points into a terminal input/output area (TIOA) in which BMS has generated an output datastream.
When modifying data in the XBMIN exit, the safest method is to use the length provided in BMXMAPLN, but to ensure that any pad characters added by BMS are preserved. BMXATTR must be ignored in the XBMIN exit; it always contains binary zeroes. Programming the XBMOUT exit This section contains some considerations specific to the XBMOUT exit. The actual data length (in BMXACTLN) may be less than the length defined in the map (in BMXMAPLN).
Exit-specific parameters UEPFAREQ Address of a 1-byte field that indicates why the exit has been called. Possible values are: UEPFAIN Initialization. UEPFATU Tidy-up. UEPFATUT Address of a 1-byte field that indicates the type of tidy-up required. Possible values are: UEPFANTU Normal tidy-up. UEPFAETU Expired tidy-up. UEPFANAM Address of the bridge facility name. UEPFATYP Address of a 1-byte field that indicates the facility type. The value is always: UEPFABR 3270 bridge facility.
Return codes UERCNORM Continue processing. XPI calls All can be used, except those that use recoverable resources. API calls All can be used except those that invoke task-related user exits or use recoverable resources. Data tables management exits XDTRD, XDTAD, and XDTLC Data tables management exits apply to both CICS shared data tables and CICS coupling facility data tables.
Note: For additional information about using these exits with CICS shared data table support, see the CICS Shared Data Tables Guide. Related concepts “The data tables sample exit programs” on page 18 Exit XDTRD The XDTRD user exit is invoked just before CICS attempts to add to the data table a record that has been retrieved from the source data set. This normally occurs when the loading process retrieves a record during the sequential copying of the source data set.
UEPDTCMT (X'40') This is a CICS-maintained table. Only meaningful if UEPDTSDT is on. UEPDTOPT (X'20') The exit has been invoked for table loading. This means that optimization by skipping can be requested. 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.
XPI calls All can be used. 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.
UEPDTRBL The fullword length of the data table buffer. 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.
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. Only meaningful if either UEPDTSDT or UEPDTCFT is on.
UERCABDU Abend CICS with a dump. XPI calls TRANSACTION_DUMP must not be used. 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.
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. UERCABDU Abend CICS with a dump. The return code UERCNORM is not available for use at this exit point. XPI calls The following must not be used: v INQUIRE_MONITORING_DATA v MONITOR v TRANSACTION_DUMP v WRITE_JOURNAL_DATA.
XPI calls Must not be used. Exit XDSAWT When invoked After an operating system wait issued by the quasireentrant CICS TCB. Exit-specific parameters UEPSYSRC Address of the 4-byte return code from the SYSEVENT request made before the operating system wait. This return code will be in one of two different forms: 1. The SYSEVENT OKSWAP return code, or 2.
1. The descriptions of the exits that follow show the general format of the application’s parameter list. For detailed information about the format of the CALL-level DL/I parameter list, refer to the IMS/ESA® Application Programming: DL/I Calls manual. 2.
UEPAPLIST Address of application’s parameter list. The general format for COBOL and assembler language is: plist address --> parm1 address --> parm1 parm2 address --> parm2 parm3 address --> parm3 .............. up to a maximum of 18 parameters excluding the optional parmcount. The general format for PL/I is: plist address --> parm1 address --> parm1 (parmcount) parm2 address --> locator descriptor --> parm2 parm3 address --> locator descriptor --> parm3 ..............
UEPPSB1 A PSB exists. UEPPSBNM Address of an area containing the 8-character PSB name. The contents of the area can be overwritten by the exit, for all types of request including UEPCSHIP; the new contents are used when the DL/I request is processed. UEPSYSDX Address of the SYSID existence flag byte: UEPSYS1 A SYSID exists. UEPSYSID Address of an area containing the 4-character SYSID name.
The general format for PL/I is: plist address --> parm1 address --> parm1 (parmcount) parm2 address --> locator descriptor --> parm2 parm3 address --> locator descriptor --> parm3 .............. up to a maximum of 18 parameters. When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list. For UEPCSHIP requests, your exit program cannot change any of the parameters.
Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT There are four exits in the dump domain. Related concepts “The dump domain sample exit program” on page 19 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.
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. It contains one of the following values: UEPXDLOC A system dump will be taken on the local MVS image only.
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. A change to the 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.
3. The field addressed by UEPFMOD contains '????????'—the failure was not in application code, but CICS was unable to determine the name of the failing module. 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.
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.
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. UEPXDTST Address of a 16-byte field which contains the current dump table statistics for this dumpcode.
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. UEPDMPDSN Address of the 44-byte dump data set dsname. Return codes UERCNORM Continue processing. UERCSWCH The autoswitch flag is set on.
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.
UEPNQTOK Address of a 4-byte area which can be used to pass information between XNQEREQ and XNQEREQC for a single enqueue request. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see EIB fields, in 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.
UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 63. UEPNQTOK Address of a 4-byte area which can be used to pass information between XNQEREQ and XNQEREQC for a single enqueue request. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see EIB fields, in the CICS Application Programming Reference manual. UEPRESP Address of a 4-byte binary copy of the EIB response code EIBRESP.
non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2, the values used by the enqueue domain are specified in DSECT DFHNQUED. Note: Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when issuing an enqueue request from the XNQEREQC exit. Use of the recursion counter UEPRECUR is recommended. The command-level parameter structure The command-level parameter structure consists of a series of addresses.
NQ_FUNCT One byte that defines the type of request: X'04' ENQ X'06' DEQ NQ_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.
2. There are no output fields on EXEC CICS ENQ and DEQ requests. 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 an ENQ request to a DEQ request. However, you can make minor changes to requests, such as to turn on the existence bit for LENGTH. The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.
1. CICS does not check changes to argument values, so any changes must be verified by the user exit program making the changes. 2. It is not advisable for XNQEREQC to modify input arguments. Adding user arguments: Global user exit programs can add arguments associated with the LENGTH and MAXLIFETIME keywords. You must ensure that the arguments you specify or modify in your exit programs are valid. The valid values for MAXLIFETIME are DFHVALUE(TASK) and DFHVALUE(UOW), which are 233 and 246 respectively.
– applies only to resource names of length equal to or greater than that of your replacement string. – is an alternative to method A when a resource name too long to allow the use of that method. Method C Place a 4-character Scope value in UEPSCOPE, and return UERCSCPE in R15. This will bypass any installed ENQMODEL resource definition, forcing a Sysplex Scope ENQ/DEQ request.
XEIOUT Invoked after the execution of any EXEC CICS API or SPI command. XEISPOUT Invoked after the execution of any EXEC CICS SPI command except those listed for XEISPIN. The sequence is: command – EDF – XEISPOUT – XEIOUT – TRACE Note: Asynchronous processing of these exits may occur if the transaction is suspended (for example, during file I/O wait). This situation may also occur under CEDF because CEDF issues its own EXEC CICS commands between the application’s XEISPIN and XEISPOUT exits.
This particular example of the danger of tampering with argument 0 does not apply to COBOL or C application programs, but nevertheless you should not modify CICS commands for application programs written in any supported language. Bypassing commands An XEIIN or XEISPIN exit program can bypass execution of a command by setting the UERCBYP return code. If it does this, EDF is not invoked, but XEISPOUT, XEIOUT, and exit trace are invoked if they are active.
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 v EXEC CICS PERFORM DUMP v EXEC CICS RESYNC ENTRYNAME 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.
XPI calls All can be used. 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.
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. This contains the contents of the registers at the point when the program issued the EXEC CICS command.
v An internal CICS request to process a system file. Note that: v If the exit program passes the request to CICS file control (without choosing to redirect it to a remote region), it is not allowed to make changes to any of the parameters. v If the exit program intercepts the request and bypasses file control: – It must return all the responses and output parameters that would otherwise have been returned by file control. These are marked output in the descriptions of the exit-specific parameters below.
Exit XFCFRIN When invoked Before the execution of a file control request. The request may have originated from: v The execution of an application request to process a user file v The receipt of a function-shipped request v An internal CICS request to process a system file. 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.
UEP_FC_BUFFER_L Address of a fullword containing (for READ, READ NEXT, and READ PREV requests) the value of the LENGTH of the buffer into which the record is to be read. UEP_FC_RECORD_P Address of one of the following: v If the request is a READ, READ NEXT, or READ PREV with the SET option, a fullword in which is to be returned the address (output) of a buffer, into which the record will be placed.
The full length of the record identifier is returned as a mandatory output field on READ NEXT and READ PREV requests. The value is used by CICS function shipping. UEP_FC_RECORD_ID_TYPE Address of a byte containing (for READ, WRITE, DELETE, START BR, READ NEXT, READ PREV, and RESET BR requests) the RIDFLD type.
UEP_FC_SEQUENTIAL_WRITE Records are to be written in sequential mode. UEP_FC_DIRECT_WRITE Records are to be written in direct mode. UEP_FC_READ_INTEGRITY Address of a byte containing (for non-update READ, READ NEXT, and READ PREV requests) the read integrity setting. (In current versions of CICS, this setting applies only to VSAM RLS.) On input to the exit, this parameter will be set to one of: UEP_FC_CR Consistent read integrity is to be used.
UEP_FC_DUPLICATE_KEY_CODE Address of a 1-byte output area indicating whether the request found more than one record for the supplied key. The possible values are: v UEP_FC_DUPLICATE KEY v UEP_FC_NOT_DUPLICATE KEY UEP_FC_ACCMETH_RETURN_CODE Address of a 4-byte output area in which access-methoddependent information is to be returned when either of the responses UEP_FC_REASON_ACCMETH_REQUEST_ERROR or UEP_FC_REASON_IO_ERROR is returned. The returned value is placed in bytes 2–5 of the EIBRCODE.
v v v v v v v v v v v v v v v v v v v v v v v v v v UEP_FC_REASON_DUPLICATE_RECORD UEP_FC_REASON_DUPLICATE_REQID UEP_FC_REASON_END_OF_FILE UEP_FC_REASON_FILE_DISABLED UEP_FC_REASON_FILE_NOT_OPEN UEP_FC_REASON_FILE_NOT_FOUND UEP_FC_REASON_FULL_KEY_WRONG_LENGTH UEP_FC_REASON_GENERIC_DELETE_NOT_KSDS UEP_FC_REASON_GENERIC_KEY_TOO_LONG UEP_FC_REASON_ILLEGAL_KEY_TYPE_CHANGE UEP_FC_REASON_INSUFFICIENT_SPACE UEP_FC_REASON_INVALID_UPDATE_TOKEN UEP_FC_REASON_IO_ERROR UEP_FC_REASON_KEY_LENGTH_NEGATIVE UEP_FC_REASON_K
UERCBYPL Bypass CICS processing of this request. If the exit program has been invoked for a function-shipped request, the mirror transaction must not terminate. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls None can be used. Exit XFCFROUT When invoked After the completion of a file control request. 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.
UEP_FC_BUFFER_P Address of a fullword containing the address of the buffer provided by the originator of the request, in which the record is returned on completion of a READ, READ NEXT, or READ PREV request with the INTO option. UEP_FC_BUFFER_L Address of a fullword containing (for READ, READ NEXT, and READ PREV requests) the value of the LENGTH of the buffer into which the record was read.
UEP_FC_KEY VSAM KSDS or AIX PATH access UEP_FC_RBA VSAM ESDS or KSDS via RBA access UEP_FC_RRN VSAM RRDS access UEP_FC_DEBKEY BDAM deblocking by key (READ, DELETE, START BR, and RESET BR requests only) UEP_FC_DEBREC BDAM deblocking by relative record (READ, DELETE, START BR, and RESET BR requests only) UEP_FC_XRBA VSAM extended ESDS access UEP_FC_REQID Address (for START BR, READ NEXT, READ PREV, RESET BR, and END BR requests) of the halfword value of REQID.
UEP_FC_CR Consistent read integrity. UEP_FC_FCT_VALUE Read integrity according to the setting in the FILE definition. UEP_FC_NRI No read integrity. UEP_FC_RR Repeatable read integrity. UEP_FC_TOKEN Address of a fullword containing the value of TOKEN. If the request is READ, READ NEXT, or READ PREV with update, and the address is not null, the area is an output field in which the token is returned. If the request is REWRITE, DELETE without RIDFLD, or UNLOCK, the area is an input field.
UEP_FC_REASON Address of a 1-byte area containing, if the request completed with an EXCEPTION response, the reason.
v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v UEP_FC_REASON_NOTAUTH UEP_FC_REASON_NOT_EXTENDED UEP_FC_REASON_PREVIOUS_RLS_FAILURE UEP_FC_REASON_RBA_ACCESS_TO_RLS_KSDS UEP_FC_REASON_READ_NOT_AUTHORISED UEP_FC_REASON_READPREV_IN_GENERIC_BROWSE UEP_FC_REASON_RECLEN_EXCEEDS_LOGGER_BFSZ UEP_FC_REASON_RECORD_BUSY UEP_FC_REASON_RECORD_NOT_FOUND UEP_FC_REASON_REMOTE_INVREQ UEP_FC_REASON_RESTART_FAILED UEP_FC_REASON_REWRITE_BEFORE_READ_UPDATE UEP_FC_REASON_RIDFLD_KEY_NOT_RECORD_KEY UEP_FC_REAS
Note: For information about the XFCAREQ and XFCAREQC exits that are invoked for file control SPI requests, see “File control EXEC interface SPI exits XFCAREQ and XFCAREQC” on page 98. Important The XFCREQ and XFCREQC exits are not invoked, on the target region, for function-shipped requests. That is, if a file control API request is function-shipped to a remote region, the exits are not invoked on the remote region.
v The address of a 16-byte area that is used if the request has been function shipped. 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.
FC_GROUP Always X'06', indicating that this is a file control request. FC_FUNCT One byte that defines the type of request: X'02' READ X'04' WRITE X'06' REWRITE X'08' DELETE X'0A' UNLOCK X'0C' 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.
X'04' MASSINSERT specified. X'02' RRN specified. 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.
X'08' XRBA specified. If the XRBA bit is on, FC_RIDFLD (described in DSECT DFHFCEDS) points to an 8-byte extended relative byte address (XRBA). FC_ADDR1 is the address of an 8-byte area containing the name specified on the FILE keyword. FC_ADDR2 is the address of one of the following: 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).
Modifying fields in the command-level parameter structure Some fields that are passed to file 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.
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. Note: You must never modify an input field by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field.
X'04' REPEATABLE specified. X'02' UPDATE specified on READNEXT or READPREV. 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.
Use of the parameter UEPFSHIP UEPFSHIP contains the address of a 16-byte area. This area consists of 4 characters, followed by 3 fullwords. If the first byte contains 'Y', this request has been function shipped to this region. In this case, if your exit program wants to bypass file control (by setting a return code of UERCBYP), it must set the 3 fullwords as follows: Fullword 1 The length of the buffer area Fullword 2 The length of the record Fullword 3 The length of the modified RIDFLD.
In XFCREQC: 1. Check ‘UEPRCODE’ to make sure that the file control request completed without error. 2. Use UEPFCTOK to find the address of the area. This area now holds the compressed data. 3. Decompress the data in place. 4. Copy the data from the new area to the user’s INTO area. 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.
UEPFSHIP Address of a 16 byte area. See “Use of the parameter UEPFSHIP” on page 94. 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. 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.
‘EIBRCODE’. For details of EIB return codes, refer to EIB fields, in the CICS Application Programming Reference manual. 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’.
3. 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. Example program CICS supplies, in CICSTS32.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 Appendix F, “The example program for the XTSEREQ global user exit, DFH$XTSE,” on page 877.
4. XFCAREQC v For the INQUIRE FILE command, only the XFCAREQ and XFCAREQC exits are invoked: 1. XFCAREQ 2. 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 101. 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.
Note: Take care when using recursive commands. For example, you must avoid entering a loop when issuing a file control SPI request from the XFCAREQ exit. Use of the recursion counter UEPRECUR is recommended. 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 101.
values into the application program’s EXEC interface block (EIB) after the completion of XFCAREQC or if you specify a return code of UERCBYP in XFCAREQ. You must set valid file control responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by file control to describe a valid completion. CICS does not check the consistency of the values you set.
v v v v v FCIS_BITS4 FCIS_BITS5 FCIS_BITS6 FCIS_BITS7 FCIS_BITS8 FCIS_GROUP Always X'4C', indicating that this is a file control SPI request. FCIS_FUNCT One byte that defines the type of request: X'02' INQUIRE FILE X'04' SET FILE. FCIS_EIDOPT2 Not used by file control. FCIS_EIDOPT3 Not used by file control. FCIS_EIDOPT4 Not used by file control. FCIS_BITS1 Existence bits which specify which arguments were specified.
X'40' Set if the request contains an argument for the ADD keyword. If set, FCIS_ADDR10 is meaningful. X'20' Set if the request contains an argument for the DELETE keyword. If set, FCIS_ADDR11 is meaningful. X'10' Set if the request contains an argument for the DISPOSITION keyword. If set, FCIS_ADDR12 is meaningful. X'08' Set if the request contains an argument for the EMPTYSTATUS keyword. If set, FCIS_ADDR13 is meaningful. X'04' Set if the request contains an argument for the OPENSTATUS keyword.
X'10' Set if the request contains an argument for the EXCLUSIVE keyword. If set, FCIS_ADDR28 is meaningful. X'08' Set if the request contains an argument for the BLOCKKEYLEN keyword. If set, FCIS_ADDR29 is meaningful. X'04' Set if the request contains an argument for the BLOCKSIZE keyword. If set, FCIS_ADDR30 is meaningful. X'02' Not used by file control. X'01' Not used by file control. FCIS_BITS5 Existence bits which specify which arguments were specified.
X'08' Set if the request contains the LOADTYPE keyword. X'04' Set if the request contains the POOL keyword. X'02' Set if the request contains the TABLENAME keyword. X'01' Set if the request contains the UPDATEMODEL keyword. FCIS_BITS8 | X'80' Set if the request contains the REMOTETABLE keyword. X'40' Set if the request contains the RBATYPE keyword. X'20' Not used by file control. X'10' Not used by file control. X'08' Not used by file control. X'04' Not used by file control.
FCIS_ADDR15 is the address of a 4-byte area containing the CVDA from ENABLESTATUS. FCIS_ADDR16 is the address of a 4-byte area containing the CVDA from RECOVSTATUS. FCIS_ADDR17 is the address of a 4-byte area containing the CVDA from ACCESSMETHOD. FCIS_ADDR18 is the address of a 4-byte area containing the CVDA from TYPE. FCIS_ADDR19 is the address of a 4-byte area containing the CVDA from OBJECT. FCIS_ADDR20 is the address of a 4-byte area containing the name from REMOTESYSTEM.
FCIS_ADDR37 to FCIS_ADDR51 are not used by file control. FCIS_ADDR52 is the address of a 4-byte area containing the data from JOURNALNUM. FCIS_ADDR53 is the address of a 4-byte area containing the data from LOADTYPE. FCIS_ADDR54 is the address of a 4-byte area containing the data from CFDTPOOL. FCIS_ADDR55 is the address of a 4-byte area containing the data from TABLENAME. FCIS_ADDR56 is the address of a 4-byte area containing the data from UPDATEMODEL.
Table 5. INQUIRE FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types.
Table 6. SET FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types.
Note: You must never modify an input field by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field. Modifying output fields: The technique described in “Modifying input fields” on page 109 is not suitable for modifying output fields.
Modifying user arguments User exit programs can modify user arguments as follows: v For input arguments, your exit program should obtain sufficient storage to hold the modified argument, set up the required value, and set the associated pointer in the parameter list to the address of the newly acquired area.
For a CLOSE WAIT command, the exits are invoked as follows. XFCSREQ is invoked, the task requests a closure of the file and waits for the closure to happen. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that closed it. Finally, because the closure has now been completed, the task that issued the CLOSE WAIT is resumed, completes its CLOSE request, and invokes XFCSREQC.
UEPFSOFB Open for backout. If the first byte indicates a close request (UEPFSCLS), the second byte shows the type of close: UEPFSNC Normal close 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.
UEFJRU Journal read for update UEFJWU Journal write update UEFJWA Journal write add 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.
UEFACBCP This field is set to nulls in this exit. Note: Only the first seven fields of UEPFINFO are set for this exit. Of the remaining fields, URFFRCLG is set to blanks, and the others are set to nulls. 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. Return codes UERCNORM Continue processing. UERCBYP Suppress the file request.
Exit XFCSREQC When invoked After a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE command has completed. Note: The exit is not invoked for function-shipped requests. 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 file close request.
UEFLNAME The 8-character file name. UEDSNAME The 44-character dsname of the data set associated with the file. 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.
UEFVSAM VSAM file UEFBDAM BDAM file | | UEFDTBL Data table file | | UEFDTUM User data table file | | UEFCFDT Coupling facility data table UEFBCRV One byte indicating the recovery attributes of the data set associated with this file. The possible values are: UEFBCFR Forward recovery specified UEFBCLOG Logging specified UEFBCVAL Flag indicating that recovery attributes are valid.
UEPFBCAS Data set marked unavailable. UEFACBCP Address of a read-only copy of the ACB for a VSAM file, or the DCB for a BDAM file. Set only after completion of a successful open. If UEFDTBL and UEFDTUM have been set on, then the storage addressed by UEFACBCP is undefined. This pointer should not be used. | | | UEPFSRSP Address of a byte containing the return codes for the request. This has one of the following values: UEFSNORM Normal response. UEFSWARN Warning response. UEFSFAIL Failure response.
UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. Note: 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. See “Using CICS services” on page 4. 3.
associated with the file, as described by fields UEFLNAME and UEDSNAME in the DFHUEFDS DSECT. 3. Issues a WRITE OPERATOR command to write as much data as has been created in the 690 bytes of storage to the system console. 4. Returns a normal response of zero in register 15. The sample program contains logic to write the same messages and data areas that are written on the default processing path to a transient data queue. In this case, output is edited into lines of 132 bytes.
XFCNREC. If the base cluster block is set as unrecoverable and a mismatch has been allowed, access may be allowed to the data set, via an unrecoverable file, before the data set is fully recovered. To provide a means of selecting which mismatches to accept and which to reject, three parameters are passed to the exit. These are the address of the filename, the address of the base data set name, and the address of a byte containing the file backout indicator.
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.
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. v You must not use EXEC CICS SHUTDOWN or EXEC CICS XCTL.
UEPQRCDE Address of a 1-byte field indicating the result of the quiesce or unquiesce. Possible values are: UEQOK Successful. UEQREJEC Rejected—see UEPQCONF for the reason code. UEQUNKNO Failed because data set not known to DFSMS as a VSAM data set. UEQIOERR Failed because of RLS error or SMSVSAM server not available. UEQCANCL Failed because quiesce was canceled by user (UEQSD and UEIMQSD only). UEQTIMED Failed because quiesce was canceled due to timeout (UEQSD and UEIMQSD only).
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. XFCBOVER Invoked when CICS is about to skip unit-of-work (UOW) backout because a batch program has overridden RLS retained lock protection and opened a data set for batch processing.
point; the TBEXITS parameter allows only one exit program at each exit point. PLTPI processing is described in Chapter 4, “Writing initialization and shutdown programs,” on page 425. Exit XFCBFAIL, file control backout failure exit XFCBFAIL is invoked whenever there is a failure during backout of an update made to a file record.
UEPFCRSP Address of the file control response byte. This can have one of the following values: UEAIXFUL No space in non-unique alternate index. UECACHE RLS cache failure or cache connectivity failure. UENBWBAK Non-BWO backup in progress. UEDLOCK Deadlock detected. UEDUPREC Duplicate key on unique alternate index. UEIOEROR I/O error. UELCKFUL RLS lock structure full.
UERCBYP Ignore the error (do not invoke CICS backout failure control) and continue. Setting this return code could be damaging to the integrity of your data. A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because the conditions under which this exit is invoked mean that a purged condition cannot be returned by any XPI or API calls. XPI calls All can be used, but subject to the same caution as for API and SPI calls.
record on the data set with the “before-image” held in the log record addressed by UEPBLOGR. Use parameter UEPFCRSP to determine which error occurred. XBFEWR An error response has been returned from the file control file-request-handler program while processing a WRITE request. This request is issued by file control backout to add the “before-image” of a deleted record. Use parameter UEPFCRSP to determine which error occurred.
The sample program takes this step to demonstrate the use of the UERCBYP return code. It is not recommended that you use UERCBYP with important data sets. v Examines the file control response code and issues a message to the console describing the procedure to be followed for this error. The sample program provides slots for each possible file control response code, and includes suggested messages for some of them.
Because the same backout code is executed following an emergency restart as at any other time, XFCBOUT replaces both XRCINPT and XDBIN for file data. The address of an FBO entry is not supplied (there is no FBO table in CICS Transaction Server for z/OS, Version 3 Release 2). However, the file name is in the log record, so your exit program can use an EXEC CICS INQUIRE FILE command to get information about the file.
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. To avoid corruption of a data set by a non-RLS batch job, which is not aware of the retained record locks, a data set cannot normally be opened for update in non-RLS mode if it has any locked records.
UERCNORM Do not perform the backout of this log record. Any updates performed by the batch run should take precedence. UERCBCKO Perform the backout. It is known that the actions of the batch job could not have affected this update. A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this global user exit is invoked during syncpoint phase 2, and therefore cannot get a purged response from any calls that it makes.
– The data set name – The file control portion of the log record. v Checks the data set name to see if it is one of those for which it is known that batch programs never update existing records, but only insert new records, or do not make updates at all. The sample program contains a table of such data sets. If this data set is in the table, UERCBCKO is returned.
UEPFLEN Address of a fullword containing the length of the data in the file control request. Return codes UERCFAIL Do not perform the logical delete, and treat this as a backout failure. This is the default action taken if the exit is not enabled. UERCLDEL Perform the logical delete by reapplying the updated record. A return code of UERCPURG is not allowed.
– An eye-catcher ‘DFH$FCLD ENTRY’ – The unmarked file control request data – The file control portion of the log record. v Issues an EXEC CICS INQUIRE FILE command to check the access method and type to confirm that the file is a VSAM ESDS or BDAM data set. The logical delete exit should have been invoked only if the file is one of these types. v For a VSAM ESDS: – Flags the record (whose address is passed to the exit in UEPFDATA) as logically deleted.
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. UERCPURG Task purged during XPI call.
If you already have an XISCONA exit program, you may be able to modify it for use at the XZIQUE exit point. The purpose of XISCONA is to help you prevent the performance problems that can occur when function shipping or DPL requests awaiting free sessions for a connection are queued in the issuing region. The exit permits you to control the number of outstanding ALLOCATE requests by allowing you to reject any function shipping or DPL request that would otherwise be queued.
v Examine the type of request and the resource being accessed (which can be discovered by examining the request parameter list). The program could, for example, reject file read requests but queue file updates. Note: Because a failure of the exit program could affect system availability, it is recommended that you make the logic of your program as simple as possible, thus reducing the possibility of errors. There are some problems that XISCONA cannot solve.
UEPEIPPL Address of the request parameter list. UEPCONTY A 1-byte field indicating the connection-type. Possible values are: UEPMRO (X'80') Request for an MRO connection UEPLU6 (X'40') Request for an LU6.1 connection UEPLUC (X'20') Request for an LU6.2 connection. UEPNETNM An 8-character field containing the NETNAME for the connection- that is, the identifier (applid) of the remote CICS region or system. Note: 1.
Note that this exit is invoked only if the request to be shipped is of type EXEC CICS START NOCHECK. For EXEC CICS requests other than those with the NOCHECK option (which is only available on START commands) the ‘SYSIDERR’ condition is raised in the application program. You can use the exit to specify whether or not the failed request is to be locally queued, to be executed when the connection is reestablished.
UERCPURG Task purged during XPI call. 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 to take the system default action or to handle the error in some other way. Interval control program exits XICREQ, XICEXP, and XICTENF You can use some XPI calls in exit programs invoked from the interval control program.
Note: 1. The contents of the fields addressed by UEPICQID and UEPICTID are unpredictable if the associated data items were not specified on the request. You must test the copy of TCAICTR to determine whether they contain meaningful values. 2. Your exit program can change the values of the fields addressed by UEPICQID, UEPICTID UEPICTI, and UEPICRT. Changing the values of the fields addressed by UEPICRQ1 or UEPICRQ2 has no effect. Return codes UERCNORM Continue processing.
Exit XICTENF When invoked Exit XICTENF is also invoked from the interval control program. However, this exit relates to the ‘terminal not known’ condition and so is considered in detail in “‘Terminal not known’ condition exits XALTENF and XICTENF” on page 224. Interval control EXEC interface program exits XICEREQ, XICERES, and XICEREQC XICEREQ XICEREQ is invoked on entry to the interval control program before CICS processes an interval control request.
v For dynamically-routed transactions—only dynamically-routed (non-terminal-related) START requests cause the exit to be invoked. Thus, a dynamically-routed transaction that was initiated by a terminal-related EXEC CICS START command does not cause the exit to be invoked. v If it is disabled. v If an XICEREQ exit program chooses to bypass the request. You can use XICERES to check that all resources required by the transaction to be started are available on the target region.
Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 152. UEPICTOK Address of a 4-byte token to be passed to XICEREQC. This allows you, for example, to pass a work area to exit XICEREQC. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to EIB fields, in the CICS Application Programming Reference manual.
EXEC CICS SHUTDOWN EXEC CICS XCTL Note: Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when an interval control request is issued from the XICEREQ exit. Use of the recursion counter UEPRECUR is recommended.
UERCNORM Continue processing. UERCPURG Task purged during XPI call. UERCRESU A required resource is unavailable. Setting this value causes CICS to reject the routed request, and to return a value of 'F' (resource unavailable) in the DYRERROR field of the routing program's communications area. XPI calls All can be used. You can also use EXEC CICS API commands at this user exit.
UEPDATE Address of a fullword copy of the EIB date value, EIBDATE. UEPTIME Address of a fullword copy of the EIB time value, EIBTIME. UEP_IC_REMOTE_SYSTEM If the request is to be sent to a remote region, is the address of an area containing the 4-byte name of the remote region. (The remote region may have been specified by, for example, the SYSID option of the START command, work-load management, or the REMOTESYSTEM option of the TRANSACTION definition.
X'10’ X'4A’ Interval control, except ASKTIME or FORMATTIME If IC_GROUP = X’10’ X'02' ASKTIME X'04' DELAY X'06' POST X'08' START X'0A' RETRIEVE X'0C' - CANCEL If IC_GROUP = X’4A’ X'02' - ASKTIME X’04’ - FORMATTIME 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' TRANSID (cancel|start) - SET|INTO FROM LENGTH TERMID SYSID RTRANSID X'80' ADDR0 .. .. .. .. 08 .. .. .. ..
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. You can also modify values of keywords specified on the request. For example, you could change the SYSID specified in the request.
IC_GROUP X'10' This is an interval control request. X'4A' This is an ASKTIME or FORMATTIME command. IC_FUNCT One byte that defines the type of request. If IC_GROUP = X'10': X'02' ASKTIME X'04' DELAY X'06' POST X'08' START X'0A' RETRIEVE X'0C' CANCEL If IC_GROUP = X'4A': X'02' ASKTIME X'04' FORMATTIME IC_BITS1 Existence bits that define which arguments were specified.
X'80' Set if the request specifies RTERMID, or if a FORMATTIME request specifies DATESEP. If set, IC_ADDR9 is meaningful. X'40' Set if the request specifies QUEUE. If set, IC_ADDRA is meaningful. 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.
X'04' YEAR was specified on a FORMATTIME command, or MINUTES was specified. X'02' TIME was specified on a FORMATTIME command, or PROTECT was specified. X'01' TIMESEP was specified on a FORMATTIME command, or NOCHECK was specified. IC_EIDOPT7 Indicates whether certain functions or keywords were specified on the request. X'F0' CANCEL specified. X'82' RETRIEVE specified. X'80' YYYYDD specified on a FORMATTIME command. X'40' YYYYMMDD specified on a FORMATTIME command, or START specified.
IC_ADDR2 is the address of one of the following: v An 8-byte area containing the value of REQID (if the request is DELAY, POST or START). v A halfword containing the value of LENGTH (if the request is RETRIEVE). Warning: For requests that specify INTO, do not change the value of LENGTH to a value greater than that specified by the application. To do so causes a storage overlay in the application. v An area containing the value of YYDD.
v A fullword containing the value of DAYCOUNT. IC_ADDRB is the address of one of the following: v An area containing the value of HOURS. v A fullword containing the value of DAYOFWEEK. IC_ADDRC is the address of one of the following: v An area containing the value of MINUTES. v A fullword containing the value of DAYOFMONTH. IC_ADDRD is the address of one of the following: v An area containing the value of SECONDS. v A fullword containing the value of MONTHOFYEAR.
The following are always input fields: v INTERVAL v TIME v REQID v FROM v v v v v v v TERMID SYSID HOURS MINUTES SECONDS USERID CHANNEL The following are always output fields: v DATE v DATEFORM v DAYCOUNT v DAYOFMONTH v DAYOFWEEK v DDMMYY v DDMMYYYY v v v v FULLDATE INTO MMDDYY MMDDYYYY v v v v MONTHOFYEAR SET TIME YEAR v YYDDD v YYDDMM v YYMMDD v YYYYDDD v YYYYDDMM v YYYYMMDD The following are input fields on a START request and output fields on a RETRIEVE request: v RTRANSID v RTERMID v QUEUE LENGTH
ABSTIME is an input field on a FORMATTIME request, and an output field on an ASKTIME request. DATESEP and TIMESEP can be input fields on a FORMATTIME request. 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. Note: You must never modify an input field by altering the data that is pointed to by the command-level parameter list.
X'40' The existence bit for QUEUE X'20' The existence bit for HOURS X'10' The existence bit for MINUTES X'08' The existence bit for SECONDS. IC_EIDOPT6 X'20' The secondary existence bit for HOURS X'10' The existence bit for FMH X'08' The secondary existence bit for SECONDS X'04' The secondary existence bit for MINUTES X'02' The existence bit for PROTECT X'01' The existence bit for NOCHECK.
IC_EIDOPT8 X'20' Unused 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 interval control 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.
1. Scan the global work area (GWA) to locate a suitable CICS region (for example, the region currently processing the least number of START requests). 2. Having decided which system to route the request to, increment the use count for this system. 3. Obtain a 4-byte area in which to store the SYSID for this request. This can be allocated from the GWA to avoid issuing a GETMAIN. If the area is obtained by issuing a GETMAIN, set UEPICTOK to the address of the storage obtained. 4.
These are both information-only exits. Any changes made to the exit parameters by the exit program are ignored by CICS, as is any return code which it sets. Exit XLDLOAD When invoked After an instance of a program is brought into storage, and before the program is made available for use. Exit-specific parameters UEPPROGN Address of an 8-character field containing the name of the program that is being loaded.
UEPPROGL Address of a 4-byte field containing the length, in bytes, of the program that is being freed. UEPLDPT Address of a 4-byte field containing the address at which the program resides in storage. UEPENTRY Address of a 4-byte field containing the address of the program’s entry point. UEPTRANID Zero, or the address of a 4-byte field containing the transaction ID which applied when the exit was invoked.
If you do not provide a JOURNALMODEL resource definition for DFHLOG and DFHSHUNT, or if you use the CICS definitions supplied in group DFHLGMOD, the model log stream names default to &sysname.DFHLOG.MODEL and &sysname.DFHSHUNT.MODEL. For example, if a CICS region issues a request to create a log stream for its primary system log, and CICS is running in an MVS image with a sysid of MV10 and using the default JOURNALMODEL definition, the MVS system logger expects to find a model log stream named MV10.DFHLOG.
For information about the IXGINVNT service, see the OS/390 MVS Authorized Assembler Services manual. 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. Note: If you want XLGSTRM to intercept the connection of the CICS system logs, you must enable your exit program in a first-phase PLT program.
UEPSYSLG The log stream is for a CICS system log. UEPGENLG The log stream is for a general log (a forward recovery log, a user journal, or auto-journal). Return codes UERCNORM CICS continues and attempts to define the log stream. 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.
Note: To run the sample program “as is”, you must first create a model log stream called 'CICSAD01.DEPT0001.MODEL100'. However, you will probably want to tailor the sample to suit your own environment. The code contains comments to help you do this. Related concepts “The log manager domain sample exit program” on page 23 Message domain exit XMEOUT The XMEOUT exit allows you to suppress or reroute CICS and CICSPlex SM messages that use the CICS message domain.
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.
UEPTERM Address of the 4-byte ID of the terminal under which the current transaction is running. If the current transaction is not associated with a terminal, the addressed field contains hexadecimal zeroes. UEPPROG Address of the 8-byte application program name, or nulls if there is no current application. UEPMNUM Address of a 4-byte field containing the message number.For CICSPlex SM messages, this field contains binary zeros.
DFHFC0531 date time applid Automatic journal journal journalname, opened for file filename is not of type MVS. Module module. The XMEOUT inserts are date, time, applid, journal, journalname, filename, and module. The fourth insert (journal) is the number specified for JOURNAL on the file definition. 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.
DFH$SXP5 Reroute a TDQ message to another TDQ DFH$SXP6 Reroute a TDQ message to a console.
UEPDICT Address of the dictionary. The sequence of dictionary entries is mapped by the DSECT generated from the macro DFHMCTDR. This field only has meaning for performance class records. If the monitoring record type is exception class (type 4) or transaction resource (type 5), this field is set to 0 (see parameter UEPMRTYP). UEPDICTE Address of the fullword number of dictionary entries. This field only has meaning for performance class records.
UERCNORM Continue processing. UERCBYP Suppress monitor record output. UERCPURG Task purged during XPI call. XPI calls WAIT_MVS can be used. Do not use any other calls. Pipeline domain exits Use the pipeline domain exits to customize the processing that occurs for inbound and outbound Web services in the pipeline. | | | | Exit XWSPRROO | | | | You can use this exit to issue API and SPI commands to examine the containers on the current channel.
UEPAPABN (X'40') The Web service provider application completed its processing successfully. | | | | | | UEPAPSF A 1-byte field indicating if the Web service provider application set a SOAP fault. Valid values are as follows: | | UEPAPSFY (X'80') The Web service provider application is returning a SOAP fault. | | UEPAPSFN (X'40') The Web service provider application is not returning a SOAP fault. | Return codes | | UERCNORM Continue processing.
Note: 1. The attributes of the local PROGRAM definition are not passed to the exit program. If the exit program needs to know, for example, the value of the REMOTESYSTEM attribute, it can issue an EXEC CICS INQUIRE PROGRAM command. 2. If you use XPCREQ to change the target SYSID, remember that: a. If SYSID specifies a remote region, no reference is made to the local PROGRAM resource definition.
2. Reinvoke the routing program, on the routing region, for route selection failure. 3. Return a RESUNAVAIL condition on the EXEC CICS LINK command executed by the mirror on the target region. (This condition is not returned to the application program.) CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.
UEPRSRCE Address of an 8-character copy of the EIB resource value, EIBRSRCE. UEP_PC_PBTOK Address of a 4-byte field containing the z/OS Workload Manager (WLM) Performance Block Token. An exit program can use this token to access information (such as the service class token, SERVCLS) in the WLM Performance Block. To do so, it must use the WLM EXTRACT macro, IWMMEXTR, passing the Performance Block Token as the MONTKN input parameter.
UEPRECUR Address of a halfword recursion counter. Because the XPCERES exit can never be called recursively in the same transaction, the value of this field is always 0. UEPRESP Address of a 4-byte copy of EIBRESP. UEPRESP2 Address of a 4-byte copy of 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 185. UEPRSRCE Address of an 8-character copy of the EIB resource value, EIBRSRCE.
UEPCLPS Address of the command parameter list. UEPPCTOK Address of a 4-byte token passed from XPCREQ. This allows XPCREQ to, for example, pass a work area to XPCREQC. UEPRCODE Address of a 6-byte hexadecimal copy of EIBRCODE. 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. UEPRESP Address of a 4-byte copy of EIBRESP. UEPRESP2 Address of a 4-byte copy of EIBRESP2.
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, except for: EXEC CICS SHUTDOWN EXEC CICS XCTL 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.
PC_ADDRA. It is defined in the DSECT PC_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHPCEDS. The command-level parameter list is made up as follows: PC_ADDR0 is the address of a 7-byte area called the EXEC interface descriptor (EID), which is made up as follows: v PC_GROUP v PC_FUNCT v PC_BITS1 v v v v PC_BITS2 PC_EIDOPT4 PC_EIDOPT5 PC_EIDOPT6 PC_GROUP Always X'0E', indicating that this is a program control request.
PC_EXIST7 (X'02 ') Set if the request specifies the SYSID parameter. If set, PC_ADDR7 is meaningful. PC_EXIST8 (X'01 ') Set if the request specifies the TRANSID parameter. If set, PC_ADDR8 is meaningful. PC_BITS2 One byte containing one of the following values: PC_EXIST9 (X'80') Not used. PC_EXISTA (X'40') Set if the request specifies the CHANNEL parameter. If set, PC_ADDRA is meaningful. PC_EIDOPT4 Not used by program control. PC_EIDOPT5 Not used by program control.
PC_ADDRA is the address of the 16-byte channel name, as specified on the CHANNEL parameter. Modifying fields in the command parameter structure: Some fields that are passed to program 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.
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 program control request only. Your user exit program is prevented from making major changes to the EID.
1. Scan the global work area (GWA) to locate a suitable CICS region - for example, the region currently processing the least number of LINK requests. 2. Having decided which system to route the request to, increment the use count for this system. 3. Obtain a 4-byte area in which to store the SYSID for this request (this can be allocated from the GWA to avoid issuing a GETMAIN). If the area is obtained by issuing a GETMAIN, set UEPPCTOK to the address of the storage obtained. 4.
terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCFTCH is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS v 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal. v A setting of PCUENOTX (X'40') indicates that the program is not command level. v A flag, PCUE_NO_MODIFY, in PCUE_CONTROL_BITS indicates that a modified entry address is not supported.
address. Set the top bit to specify that the alternative program is to run AMODE (31). PCUE_REAL_ENTRY From z/OS 1.7 onwards, this field provides the real entry point for Language Environment conforming programs. Previously only PCUE_ENTRY_POINT was available to you, but for Language Environment conforming programs this did not contain the entry point that you needed to know about. Note: With z/OS 1.7, this field provides a solution to the problem raised by APAR PQ43992.
BASSM 15,0 USING *,15 When invoked Before a HANDLE ABEND routine is given control. 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.
XPI calls All can be used. 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. Register 14 is used to branch to the resume address.
PCUE_LOGICAL_LEVEL Fullword containing the number of chained DFHRSADS blocks (that is, logical level). PCUE_BRANCH_ADDRESS Fullword. You can use this field to supply a resume address. Set the top bit to specify that the resumed task is to run AMODE (31). PCUE_BRANCH_EXECKEY If storage protection is active, you can use this 1-byte field to specify the execution key of the resumed task. The possible values are: PCUE_BRANCH_USER User key PCUE_BRANCH_CICS CICS key.
DFH$PCTA can be extended for transaction isolation. Related concepts “The transaction-abend sample exit program” on page 24 Exit XPCABND XPCABND is invoked after a transaction abend and before a transaction dump call: you can use it to suppress the dump. When invoked After a transaction abend and before a transaction dump call is made. 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.
UERCBYP Suppress the dump call. UERCPURG Task purged during XPI call. XPI calls All can be used. 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.
UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI commands All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. However, CALLDLI, EXEC DLI, or EXEC SQL commands must not be used. 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.
Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI commands All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. However, CALLDLI, EXEC DLI, or EXEC SQL commands must not be used. Note: It is not recommended that your exit program make calls to other external resource managers that use the RMI, because this causes recursion, and may result in a loop. It is your exit program's responsibility to avoid entering a loop.
connection is a concatenation of a FEPI node name and a FEPI target name, each of which is 8 characters long (fixed length) with no separator. The exit is driven once for each individual resource in a group list installed during a CICS initial or cold start. If you are concerned about the performance overhead on an initial or cold start, do not enable the exit until after the group list is installed.
UEIDDB2E A DB2 entry (DB2ENTRY) UEIDDB2T A DB2 transaction (DB2TRAN) UEIDDJAR A deployed JAR file (DJAR) UEIDDOCT A DOCTEMPLATE UEIDFECO A FEPI connection UEIDFENO A FEPI node UEIDFEPO A FEPI pool UEIDFEPS A FEPI propertyset UEIDFETA A FEPI target UEIDFILE A file UEIDIPCO An IPIC connection ( “IPCONN”) UEIDJNMD A journal model UEIDJNNM A journal name UEIDLBRY A LIBRARY resource UEIDMAP A mapset UEIDMODE A modegroup UEIDNQRN An ENQMODEL UEIDPART A partner UEIDPIPE A pipeline (PIPELINE) UEIDPROF A profile UEI
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. UEIDURIM A URI map (URIMAP) UEIDWEBS A Web service (WEBSERVICE) UEPIDLEN Address of the length of an individual resource name, as a full-word binary value.
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. If the exit returns code UERCPURG during syncpoint for these resources, abend code AUEP is produced and CICS terminates.
UEPTRMID Address of the terminal id. UEPTCTUA Address of the TCT user area. UEPTCTUL Address of the TCT user area length. UEPTRMTY Address of the terminal-type byte. UEPSNFLG Address of a 2-byte field containing flags: Table 8. Flags set in the UEPSNFLG field of XSNON Flag Equivalent Meaning UEPSNOK 0 Signon was successful. UEPSNFL 1 Signon failed. UEPSNPSS 2 The persistent sessions signon succeeded. UEPSNPSF 3 The persistent sessions signon failed. Return codes UERCNORM Continue processing.
UEPTRMTY Address of the terminal-type byte. UEPSNFLG Address of a 2-byte field containing flags: UEPSNOK Sign-off was successful UEPSNFL Sign-off failed UEPSNNML Normal sign-off UEPSNTIM Timeout sign-off. Return codes UERCNORM Continue processing. UERCPURG Task purged during XPI call. XPI calls All can be used. Exit XSNEX The purpose of XSNEX, in conjunction with its supporting sample programs, is to provide a short-term migration aid.
To use this program, add an entry to the first section of your PLTPI table (that is, before the DFHDELIM statement). For example: DFHPLT DFHPLT DFHPLT DFHPLT END TYPE=INITIAL,SUFFIX=SN TYPE=ENTRY,PROGRAM=DFH$SNPI TYPE=ENTRY,PROGRAM=DFHDELIM TYPE=FINAL Statistics domain exit XSTOUT On invocation, XSTOUT is passed the address of a buffer containing one or more statistics records.
UEPSTYPE Address of the 3-byte character field statistics type. The values of the types are: INT Interval statistics EOD End-of-day statistics REQ Requested statistics RRT Requested reset statistics USS Unsolicited statistics. 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).
SRP_ERROR_TYPE The 4-character error type—always ‘ASRB’. SRP_SYS_ABCODE 2 bytes containing the system abend code XXX in binary format (for example, D37). SRP_USER_ABCODE 2 bytes containing the user abend code NNNN in binary format (for example, 0999). SRP_ERROR_TRANID 4-character field containing the ID of the abending transaction. SRP_ERROR_STACK_NAME 8-character field containing the name of the current kernel stack entry for the transaction at the time of the abend.
SRP_CICS_ERROR_REASON 4-character field containing the MVS abend reason code. It contains a value only if flag SRP_VALID_REASON is set. SRP_CICS_ERROR_DATA An area describing the last thing that CICS did, prior to the abend.
2. The format of SRP_ERROR_DATA is shown in the CICS Data Areas manual. Return codes UERCNOCA Abnormally terminate the task with abend code ‘ASRB’. Do not cancel any program-level abend exits that are associated with this task. UERCCANC Abnormally terminate the task with abend code ‘ASRB’. Cancel any program-level abend exits that are associated with this task. UERCCICS Abnormally terminate CICS.
XPI calls All other XPI calls except WRITE_JOURNAL_DATA can be used. However, their use is not recommended, because they could cause the task to lose control, thus allowing another task to write more monitoring data.
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. (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).
UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name. UEP_TS_FUNCTION Address of a byte containing the function: v UEP_TS_FUN_WRITE v UEP_TS_FUN_REWRITE v v v v v 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).
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.
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. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID.
v UEP_TS_RESPONSE_EXCEPTION v UEP_TS_RESPONSE_DISASTER v 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 XTSEREQ and XTSEREQC The XTSEREQ exit allows you to intercept temporary storage API requests before any action has been taken on the request.
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 215. 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.
Note: Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a temporary storage request from the XTSEREQ exit. Use of the recursion counter UEPRECUR is recommended. 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 215.
UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI commands All can be used, except for: EXEC CICS SHUTDOWN EXEC CICS XCTL You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. If you update the values, temporary storage copies the new values into the application program’s EIB after the completion of XTSEREQC or if you specify a return code of UERCBYP in XTSEREQ. You must set valid temporary storage responses.
The command-level parameter list is made up as follows. Note: The relationship between arguments, keywords, data types, and input/output types is summarized for the temporary storage commands in the following tables: Table 9.
X'02' Set if the request contains an argument for the SYSID keyword. If set, TS_ADDR7 is meaningful. TS_BITS2 Two bytes not used by temporary storage. TS_EIDOPT5 Indicates whether certain keywords were specified on the request. X'80' QNAME was specified (otherwise QUEUE). You can modify this bit in your user exit if you wish. TS_EIDOPT6 One byte not used by temporary storage. TS_EIDOPT7 Indicates whether certain functions and/or keywords were specified on the request. X'10' WRITEQ NOSUSPEND specified.
TS_ADDR7 is the address of an area containing the value of SYSID. Modifying fields in the command-level parameter structure: Some fields that are passed to temporary storage 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.
However, you can make minor changes to requests, such as to turn on the existence bit for SYSID so that the request can be changed into one that is shipped to a remote system. The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored. TS_BITS1 X'02' The existence bit for SYSID. TS_EIDOPT7 A user exit program at XTSEREQ can set the following on or off for all WRITEQ TS commands: X'10' The existence bit for NOSUSPEND.
Table 11. READQ TS: User arguments and associated keywords, data types, and input/output types Argument Keyword Data type Input/output type Arg1 QUEUE CHAR(8) input Arg1 QNAME CHAR(16) input Arg2 SET DATA-AREA, PTR output Arg2 INTO DATA-AREA output Arg3 LENGTH BIN(15) input/output Arg4 NUMITEMS BIN(15) output Arg5 ITEM BIN(15) input Arg6 * * Arg7 SYSID CHAR(4) input Table 12.
1. 2. 3. 4. 5. Obtain storage for the argument to be added Initialize the storage to the required value Select and set up the appropriate pointer from the parameter list Select and set up the appropriate argument existence bit in the EID Modify the parameter list to reflect the new end of list indicator.
UEPALLEN Address of a fullword binary field containing the length of the FROM data; or hexadecimal zeros, in either of the following cases: v The AID was created by a START request without a FROM option. v The AID is associated with a channel (in which case the field pointed to by UEPALCHN will be set to a name other than blanks). UEPALRQD Address of an 8-byte field containing the value of the REQID associated with the FROM data. The data was stored in a temporary storage queue with this name.
Note: The XALTENF exit, used to handle the “terminal not known” condition, is also invoked from the terminal allocation program. XALTENF is described on page “‘Terminal not known’ condition exits XALTENF and XICTENF” on page 224. Terminal control program exits XTCIN, XTCOUT, and XTCATT 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.
XPI calls All can be used. However, note that you cannot use a GETMAIN call to obtain terminal-class storage for use as a replacement TIOA. 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.
in the local system. If the requested terminal is remote, the terminal allocation program ships an ATI request to the remote system, which initiates transaction routing back to the local system. For guidance information about ATI, refer to the CICS Intercommunication Guide. ‘Terminal not known’ condition The ‘terminal not known’ condition arises when an ATI request is made for a terminal not known in the region.
UERCNETN Netname of TOR returned UERCSYSI Sysid of TOR returned. For return codes UERCNETN and UERCSYSI, the exit program must place the netname or sysid of the terminal-owning region in fields UEPxxNTO or UEPxxSYO (where xx is AL or IC). If the terminal-owning region is a member of a VTAM generic resource, the exit program should place the netname of the terminal in field UEPxxNNO.
UEPALTRN Address of 4 bytes containing the name of the transaction to be run. UEPALRTR Address of 4 bytes containing the name of the terminal on which the transaction should run. (If a transient data trigger level was reached and the transient data queue definition specified a system, then this would contain a system identifier.
run. It is important that your exit program supply a terminal netname if the TOR to which it directs the ATI request is a member of a VTAM generic resource. Return codes UERCTEUN Terminal unknown, reject request. UERCNETN Terminal known, netname returned in UEPALNTO. UERCSYSI Terminal known, sysid returned in UEPALSYO. XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM. No other XPI calls should be used.
UEPICFN A START command was not being processed or a START was being processed but it was not function shipped. UEPICTRN Address of 4 bytes containing the name of the transaction to be run. UEPICRTR Address of 4 bytes containing the name of the terminal on which the transaction should run. UEPICCTR Address of 4 bytes containing, for START commands, the name of the current terminal if the command was transaction routed, or the name of the session if the command was function shipped.
run. It is important that your exit program supply a terminal netname if the TOR to which it directs the ATI request is a member of a VTAM generic resource. Return codes UERCTEUN Terminal unknown, reject request. UERCNETN Terminal known, netname returned in UEPICNTO. UERCSYSI Terminal known, sysid returned in UEPICSYO. UERCPURG Task purged during XPI call. XPI calls The following must not be used: v ADD_SUSPEND v DELETE_SUSPEND v v v v v DEQUEUE ENQUEUE RESUME SUSPEND WAIT_MVS.
DFHXTENF CSECT DFHVM XTENF ENTRY DFHXTENA DFHXTENA DS 0H STM R14,R12,12(R13) save registers BALR R11,0 set up base register USING *,R11 * USING DFHUEPAR,R1 DFHUEH parameter list * * Could check the terminal ID at this point. In this * program we assume it is valid. We also choose to accept * START requests and reject Transient Data trigger level * events.
Important The example in Figure 2 on page 231 is intended purely as a demonstration of some of the possibilities available, and would be impractical in a production environment. Related concepts “The terminal-not-known sample exit program” on page 25 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.
transaction specified on DTRTRAN is attached and CICS considers that the transaction has been found. Equated values are: UEATFND The transaction was found. UEATNFND The transaction was not found. UEPATTST The address of a 1 byte transaction definition state. Equated values for the definition state are: UEATENAB The transaction is enabled. UEATDISA The transaction is disabled. UEPATTTK The address of a doubleword containing a transaction token.
When the task being attached is for a task started by an immediate START command; that is, a START without an interval, the current task is the task that issues the START command, and the fields contain values associated with that task. 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.
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. UERCPURG Task purged during XPI call. XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM v WAIT_MVS Do not use any other calls.
Note: If you return UERCTDOK to suppress the first line of a multiline message, the rest of the message is not presented to XTDOUT, but is also suppressed. UERCPURG Task purged during XPI call. XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM v WAIT_MVS Do not use any other calls. 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.
Exit XTDEREQ When invoked Before CICS processes a transient data API request. Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 240. 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. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’.
Note: Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a transient data request from the XTDEREQ exit. Use of the recursion counter UEPRECUR is recommended. 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 240.
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 commands All can be used, except for: EXEC CICS SHUTDOWN EXEC CICS XCTL Note: Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a transient data request from the XTDEREQC exit.
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. You can also modify values of keywords specified on the request. (For example, you could change the sysid specified in the request.) End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list.
X'04' READQ X'06' DELETEQ. 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.
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.
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. You can treat such fields in the same way as output fields, and they are considered to be the same. Modifying the EID: It is not possible to modify the EID to make major changes to requests, such as changing a READQ request to a WRITEQ request.
You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. Transient data copies your values into the real EIB after the completion of XTDEREQC; or if you specify a return code of ‘ bypass’ in XTDEREQ. You must set valid transient data responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by CICS transient data to describe a valid completion.
When using XRCINIT and XRCINPT, you should bear in mind that the exits may be invoked before recovery of temporary storage and transient data resources is complete. For further guidance information about exits for unit of work backout, refer to the CICS Recovery and Restart Guide. Coding the exit programs CICS services can be used in exit programs invoked from these exits using the XPI or EXEC CICS commands.
name6 are the names of your user exit programs for XRCINIT, XRCINPT, XFCBFAIL, XFCLDEL, XFCBOVER, and XFCBOUT. v Enable the exits during the first stage of initialization using a PLTPI program. If you use the TBEXITS parameter to enable the exits, a global work area of 4 bytes is provided. If you use a PLTPI program, you can select the size of the global work area.
UEPUOWBO UOW backed out UEPUOWIF UOW was in-flight UEPUOWID UOW was in-doubt. UEPLGREC Address of the log record just read. The journal control record can be mapped using the information supplied in Chapter 27, “CICS logging and journaling,” on page 709. 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.
UEPTPNL Address of a 1-byte field containing the length of the TPN or DPN. UEPTRAN Address of the 4-byte transaction ID. Note: The exit program must not change the TRANSID of tasks started by automatic transaction initiation (ATI). (This is because CICS needs to match the TRANSID in its program control table with the TRANSID in the automatic initiate descriptor (AID) that was created in the AOR.) Return codes UERCNORM Continue processing. XPI calls All can be used.
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. However, fields TIOASAL and TIOASCA are not programming interfaces. Note: In certain circumstances—for example, when XZCOUT is invoked before the send of a NULL RU—UEPTIOA contains zeroes. Return codes UERCNORM Continue processing.
v The equivalent global user exit to control the number of queued requests for sessions on IP interconnectivity (IPIC) connections is XISQUE: see “XISQUE exit for managing IPIC intersystem queues” on page 258. v There are several methods that you can use to control the length of intersystem queues. For a description of the various methods, see Intersystem session queue management, in the CICS Intercommunication Guide. The XZIQUE exit enables you detect queuing problems (bottlenecks) early.
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. These are: UERCAQUE This return code indicates that CICS is to queue the allocate request.
v For specific modegroup allocate requests, use return code UERCAKLM. UERCAKLM also returns SYSIDERR to all application programs waiting on the purged allocate requests. CICS sets the UEPFLAG parameter to UEPRC12 on subsequent calls to your XZIQUE exit program to indicate that UERCAKLM was returned previously to purge the queue. Purging a queue that is causing congestion in the flow of tasks frees task slots that are needed to prevent the system becoming clogged.
Each time an XZIQUE global user exit program returns with a request to purge a queue, CICS increments a new field in either the system entry or mode entry connection statistics. These fields are: A14EQPCT The count of the number of times the queue has been purged for the connection as a whole. A20EQPCT The count of the number of times the mode group queue has been purged.
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). UEPMODST Address of the 84-byte modegroup statistics record for the modegroup specified in the relevant CICS profile. This field applies only to APPC connections for a specific allocate. For LU61, IRC, or non-specific APPC allocates, it contains zero. The statistics record can be mapped using DSECT DFHA20DS.
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). UEPSARC8 A half-word binary field containing the number of sessions freed since the queue was last purged as a result of a UEPCAKLL return code to CICS. Specific allocates data:The following three fields contain data relating to specific modegroup allocates.
UERCNORM Resume normal operation of the link or modegroup. UERCAPUR Reject the allocate request with SYSIDERR. XPI calls All can be used. Designing an XZIQUE global user exit program The functions of your XZIQUE exit should be designed: 1. To control of the number of tasks (and the amount of associated resource) that are waiting in a queue for a free intersystem session. Waiting tasks can degrade the performance of the local system. 2.
to control the existence and length of the queue of allocate requests. If you enable the exit, the parameters from the connection definition are passed to your XZIQUE global user exit program, which can change the way in which these parameters are used. The exit program also demonstrates how to control allocate requests for a particular modegroup, based on the same QUEUELIMIT and MAXQTIME parameters.
Extensions to the sample program: The sample exit program does not attempt to control the queue length, or detect poor response for a particular modegroup differently from the whole connection. This kind of enhancement is something you might want to add to your own exit program if your applications request specific modegroups via the allocate command (or via a transaction profile) and you think it would be useful to control the modegroups individually.
Exit-specific parameters UEPISDATA Address of the 78-byte area containing the information listed below. This area is mapped by the DSECT in copybook DFHXIQDS. Area addressed by UEPISDATA: UEPREQ A 2-byte origin-of-request code, which can have the following value: FS Function shipping (includes distributed program link.) UEPIPCNM The 8-byte name of the IPCONN. UEPREQTR The 4-byte identifier of the requesting transaction.
UERCAQUE Queue the allocate request. UERCAPUR Reject the allocate request with SYSIDERR. UERCAKLL Reject this allocate request with SYSIDERR. Purge all other queued allocate requests and send an information message to the operator console. CICS also returns SYSIDERR to all application programs waiting on the purged allocate requests. UERCPURG Task purged during XPI call.
number of allocates processed since the queue began, to determine the rate at which CICS is processing requests. The relevant fields are: UEPSAQTS and UEPSACNT. To determine whether CICS is allocating requests for sessions on this IPCONN at an acceptable rate, you can compare the calculated time with either of the following: 1. The value of the MAXQTIME option of the IPCONN resource definition, which is passed in the UEPEMXQT exit-specific parameter. 2. Some other preset time value.
ISR_XISQUE_ALLOC_REJECTS Each time an XISQUE global user exit program returns with a request to reject a request, CICS increments this field, which is provided to help you tune the queue limit. Normally, if the number of sessions and the queue limit specified on the IPCONN definition are correctly balanced, and there has been no abnormal congestion on the link, ISR_XISQUE_ALLOC_REJECTS should be zero. If the rejected allocates field is non-zero it indicates that action is probably needed.
the exit, the parameters from the IPCONN definition are passed to the XISQUE exit program, which can change the way in which these parameters are used. Overview of the sample exit program The program uses the exit-specific parameters passed by CICS to determine the state of the IPCONN, and to request the appropriate action, as follows: 1. The IPCONN is operating normally; a queue may exist, but is of short length.
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. XXRSTAT gives you the choice of allowing the system which has suffered the takeover to continue or to terminate. To avoid potential integrity exposures, CICS default action after a predatory takeover is to terminate without a dump.
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. Chapter 1.
266 Customization Guide
Chapter 2. Task-related user exit programs This chapter describes a special kind of user exit called a task-related user exit (TRUE). The chapter is divided into the following sections: 1. “Introduction to the task-related user exit mechanism (the adapter)” 2. “The stub program” on page 269 3. “Writing a task-related user exit program” on page 271 4. “Administering the adapter” on page 302.
Application program DFHRMCAL Stub Task-related user exit program Resource manager Non-CICS resource THE ADAPTER CICS SPI manager CICS syncpoint manager CICS task manager CICS termination manager CICS context management EDF 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.
The administration routines may also contain commands to retrieve information about one of the exit program’s work areas (the EXEC CICS EXTRACT EXIT command), and to resolve any inconsistency between CICS and a non-CICS resource manager after a system failure (the EXEC CICS RESYNC command). For programming information about the EXEC CICS ENABLE PROGRAM, DISABLE PROGRAM, EXTRACT EXIT, and RESYNC ENTRYNAME commands, refer to the CICS System Programming Reference manual.
The application can use a parameter to determine whether the resource manager was called. For example, if the application sets a parameter to zero and the resource manager sets it to nonzero, the parameter value on return indicates whether the resource manager was invoked. Note: The only operands of the DFHRMCAL macro intended for customer use are TO, RTNABND, and SUPPEDF (the latter two being described below). The other operands are for CICS internal use only.
Writing a task-related user exit program The main function of the task-related user exit program is to translate the calling program’s parameters into a form acceptable to your non-CICS resource manager, and then to pass control to the resource manager. You therefore need to be familiar with your resource manager’s syntax requirements. The calling program’s parameters are described in “Caller parameter lists” on page 279.
Threadsafe restrictions An open API TRUE must not treat the executing open TCB environment in such a way that it causes problems for: v Other open API TRUEs called by the same task v OPENAPI programs called by the same task v Application program logic that could run on the open TCB v Future tasks that might use the open TCB v CICS management code.
Application program call (API)—UERTAPPL For this call, CICS always invokes the TRUE on an L8 mode TCB CICS syncpoint manager call—UERTSYNC For this call, CICS always invokes the TRUE on an L8 mode TCB CICS task manager call—UERTTASK For this call, the TCB on which CICS invokes the TRUE is further determined by the type of task manager call: UERTSOTR—Start of task For this call the open API option is ignored for performance reasons, and CICS always invokes the TRUE on the QR TCB.
v v v v v The The The The The address address address address address of of of of of the kernel stack entry the APPC unit of work (UOW) identifier the user security block flag the user security block the resource manager qualifier name v The address of the resource manager’s “single-update” and “read-only” indicator byte v The address of the caller’s AMODE indicator byte v The address of the application’s DATALOC and TASKDATAKEY indicator byte v The address of the performance block token v The address
area, with the contents of registers 14 through 12 stored in the fourth and subsequent words. Its fifth word, representing the calling program's register 15, is cleared by CICS before the task-related user exit program is invoked, so that it can be used to convey response codes from the resource manager to the calling program. For this reason you cannot use register 15 to send data to the task-related user exit program. The seventh word of the save area contains the caller's register 1.
UEPRMQUA Address of an 8-byte field into which the task-related user exit can move the qualifier name of the resource manager on each API request. This is useful where the same exit program is used to connect to more than one instance of a resource manager; the qualifier identifies the instance of the resource manager to which the exit is currently connected.
exit is called on the QR TCB with the UEPTUTCB bit set. For all other calls, CICS abends the transaction without invoking the task-related user exit. The second and third bytes contain a value indicating the TCB mode of its caller. This is represented in DFHUEPAR as both a two-character code and a symbolic value, as follows: Table 13. TCB indicators in DFHUEPAR.
An exit program must make no assumptions about the contents of the Performance Block and must not attempt to modify it: if it does so, the results are unpredictable. UEPTRCE Address of a 1-byte trace flag indicating whether RMI tracing (the RI trace component) is active. 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.
Caller parameter lists In addition to the DSECTs DFHUEPAR and DFHUERTR, the inclusion of DFHUEXIT TYPE=RM in the task-related user exit program provides some field definitions that are specific to the caller of the task-related user exit. The calling program’s parameter list is normally addressed by R1 in the calling program’s RSA. This RSA is addressed by field UEPHMSA of DFHUEPAR. These parameters are described below.
messages for resource recovery. They are presented explicitly because, after a system failure, the task driving the exit is not the task that originally scheduled the recoverable work. These additional parameters describe the original task’s environment and are accessed directly. The full parameter list is as follows: Parameter 1 The address of operation byte 1, which contains the following flags: UERTPREP (X'80') Prepare to commit (that is, perform the first phase of a two-phase commit).
task. But note that, on many invocations of the exit program, parameters 2 through 9 do not contain values. See note 1. Parameter 3 Address of a 4-character field identifying the transaction that started the original task. See note 1. Parameter 4 Address of a 4-character field identifying the terminal from which the original task was initiated. See note 1. Parameter 5 Address of a 4-character field containing the identity of the terminal operator (OPID) who initiated the original task. See note 1.
1. Parameters 2 through 8 contain values only if the CICS syncpoint manager call is prompted by the issue of an EXEC CICS RESYNC command after a session or system failure, and operation byte 1 contains the bit settings UERTCOMM or UERTBACK. Otherwise, they are set to X'00' (hexadecimal zero).
UERTCABY (X'20') CICS abend, retry possible, TCBs dispatchable UERTCABN (X'10') CICS abend, retry not possible, TCBs dispatchable UERTOPCA (X'01') CICS abend, retry not possible, TCBs not dispatchable. For further information about shutdown TRUEs, see “Coding a program to be invoked at CICS termination” on page 298.
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. UEPEDFNO (X'01') EDF user has requested NOOP. UEPEDFFO The output flag byte. If the task-related user exit requires, it can set the UEPEDFFO flag byte to indicate to EDF what action the task-related user exit wants EDF to take. It can take the following values: UEPEDFDF (X'80') Take default CICS action.
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 Note: 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.
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 UEPTAA UEPTAL UEPEIB UEPURID UEPFLAGS
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. There is a unique schedule flag word for each association between a CICS task and the ENTRYNAME specified when a task-related user exit program is enabled.
flag word. When the calling application program subsequently issues a syncpoint command, or when end-of-task is reached, the CICS syncpoint manager calls the exit program. Note: CICS sets the syncpoint manager bit off after every call to the syncpoint manager. This is to avoid the CICS syncpoint manager invoking the task-related user exit program for a unit of recovery during which the exit program did no recoverable work.
The calling program’s registers The calling program’s registers are stored at the address specified by UEPHMSA of DFHUEPAR. Where the calling program is a CICS management program, for example the syncpoint manager, the only caller registers that have significance are registers 1 and 15. Register 1 addresses the calling program’s parameter list. CICS sets the calling program’s register 15 to zero before the task-related user exit program is invoked.
DFHRMCAL, the task-related user exit is invoked in AMODE 24. For this reason, task-related user exits which have been enabled without the LINKEDITMODE option must reside below the 16MB line. Exit programs and the CICS storage protection facility When you are running CICS with the storage protection facility, there are two points you need to consider for task-related user exits: 1. The execution key in which your task-related user exit programs run 2.
v Before passing control to a task-related user exit program, CICS inhibits: – The ability to purge tasks – The monitoring of runaway tasks v While control is in a task-related user exit program: – Purge requests are deferred until control is returned from the task-related user exit program. – Monitoring of runaway tasks is inactive. – Force purge requests are actioned.
v On each invocation of a task-related user exit program, a new EXEC environment is created, even when the program is being invoked from the same task. This means that CICS operations, such as browse of a resource definition table, cannot be continued from one invocation of the exit program to the next. Using channels and containers Task-related user exit programs cannot access channels and containers created by application programs.
The local work area A local work area is associated with a single task and lasts only for the duration of the task. It is for the use of a single task-related user exit program. It can be thought of as a logical extension to the transaction work area (TWA, TWACOBA) 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.
piece of recoverable work to ensure that the CICS syncpoint manager calls the exit program during syncpoint processing. (The identification of the current unit of recovery—or unit of work—is addressed by the 8-byte field UEPURID. This is available on all invocations of your exit program in which recoverable actions are possible, for example, application calls and subsequent syncpoint manager calls.
manager’s parameter list and the TRUE return codes. (The CICS syncpoint manager parameters are described in “CICS syncpoint manager parameters” on page 279.) Table 15.
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 /* Don’t know what happened */ put
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. If the resource manager is unable to get into this state, the exit program should return ‘UERFBACK’ in register 15, to request backout.
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. For example: v Do not update any CICS resources at all during a task-detach exit call, because the CICS syncpoint manager is not invoked again for that task. Note also that all resources (terminals, and so on) except task-storage have been released by end-of-task.
CICS abend, retry possible, TCBs dispatchable (UERTCABY) MVS has flagged the failure as being “eligible for retry”. Your exit program must follow the MVS rules for this type of failure, documented in the OS/390 MVS Authorized Assembler Services Guide. Subtasks in the region (that is, task control blocks (TCBs) in addition to the CICS job-step TCB) are still dispatchable, and your exit program can execute code under them. You must not use any CICS services.
JTRUE1A * * * * * * CONT JTRUE1B * * * * * EXIT 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 shu
DFHEISTG * * * RSA SA * RSACB RSACF RSAR14 RSAR15 RSAR0 RSAR1 RSAR2 RSAR3 RSAR4 RSAR5 RSAR6 RSAR7 RSAR8 RSAR9 RSAR10 RSAR11 RSAR12 DSECT Local working storage for CSECT JTRUE1B DS 18F DSECT DS F Register save area Register save area DSECT DS F +004 DS F +008 DS F +00C DS F +010 DS F +014 DS F +018 DS F DS F DS F DS F DS F DS F DS F DS F DS F DS F DS F DFHREGS DFHUEXIT TYPE=RM DFHEISTG DFHEIEND PRINT NOGEN PRINT GEN END Figure 10.
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 11.
operators. This section lists what you must do before you can use the adapter, and describes the commands used by the supervisor to administer task-related user exit programs. What you must do before using the adapter A task-related user exit program must be both enabled and started before it is available for execution. 1. Use the CEDA INSTALL PROGRAM command to define the task-related user exit program to the system. 2.
capable of waiting for in-doubt resolution. This applies to local resources such as files, and also other RMCs, such as LU6.1, LU6.2, or MRO connections to other systems. v An inbound RESYNC command from a resource manager that requests resynchronization for a UOW that CICS was in-doubt about, results in CICS invoking the task-related user exit with a forced decision. SHUTDOWN specifies that the exit program is to be invoked at CICS shutdown.
Chapter 3. The user exit programming interface (XPI) This chapter describes the user exit programming interface (XPI) of CICS Transaction Server for z/OS, Version 3 Release 2. It is divided into the following sections: v “Overview of the XPI” is an introduction to the XPI. v “Making an XPI call” on page 308 contains information that applies to all the XPI calls. v “Global user exit XPI examples, showing the use of storage” on page 313 contains two pieces of sample code.
– Release all storage held by the SEARCH_LDAP function—see “The FREE_SEARCH_RESULTS call” on page 324.
– Inquire about the attributes of a specified program—see “The INQUIRE_PROGRAM call” on page 366 – Inquire about the attributes of the program that is currently running—see “The INQUIRE_CURRENT_PROGRAM call” on page 373 – Set selected attributes in the definition of a specified program—see “The SET_PROGRAM call” on page 375 – Browse through program definitions, optionally starting at the definition of a specified program—see “The START_BROWSE_PROGRAM call” on page 379, “The GET_NEXT_PROGRAM call” on page 38
– Inquire about an attached transaction—see “The INQUIRE_TRANSACTION call” on page 414 – Change the task priority and transaction class of the current task—see “The SET_TRANSACTION call” on page 418. v Using the XPI user journaling function, you can: – Write a record to a CICS journal—see “The WRITE_JOURNAL_DATA call” on page 419. Important 1. You cannot use all of the XPI calls at every global user exit point.
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. v There must be no embedded blanks apart from the blank between the macro-name and the first keyword (usually CALL). v Entries on lines other than the final line must end with a comma. v Lines other than the final line must have a continuation character in column 72.
Note: Failure to clear the parameter list can cause unpredictable results, such as program checks or storage violations. If you are building the parameter list incrementally, specify CLEAR before specifying any parameters. If you are not building the parameter incrementally, specify CLEAR when the CALL is issued. IN tells CICS that any parameter following the IN option and preceding the OUT option is an input value. It must be specified when CALL is specified.
DFHxxyyX. You cannot assume that the arithmetic values of corresponding RESPONSE codes are the same for all macro calls. The meanings of the RESPONSE codes are as follows: OK The XPI request was completed successfully. EXCEPTION The function was not completed successfully for a reason which could be expected to happen, and which may be coded for by a program (for example, TRANSACTION_DUMP, EXCEPTION = SUPPRESSED_BY_DUMPTABLE). Any REASON value may provide more information.
If a DFHDSSRX SUSPEND or WAIT_MVS call does not specify an INTERVAL, and gets this RESPONSE with a REASON of ‘TASK_CANCELLED’ or ‘TIMED_OUT’, it indicates that the task has been purged by an operator or an application, or by the deadlock time-out facility. In this case, you must set a return code of ‘UERCPURG’ and return. You must not return the response code ‘UERCPURG’ to CICS for any other reason. If you attempt to do so, your program will have unpredictable results.
The XPI copy books There is a copy book for each XPI function, to provide the DSECTs associated with that function. These DSECTs allow you to map the parameters and the response and reason codes of an XPI call. You must include in your exit program a COPY statement for each XPI function that you are going to use. The copy book name is the same as the macro name, except that the final letter “X” becomes a letter “Y”.
in the first 4 bytes of the LIFO storage addressed by UEPXSTOR. In this example, the initialization of the parameter list (using the CLEAR option), the building of the parameter list, and the GETMAIN call occur in a single macro. For details of how to build the parameter list incrementally, and how to separate the CLEAR and the GETMAIN call, refer to “An example showing how to build a parameter list incrementally” on page 318.
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.
************************************************************************** * Before issuing an XPI function call, set up addressing to XPI * * parameter list.
************************************************************************* * 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.
* OUT -output values follow * * * * RESPONSE(*) -- put response at SMMC_RESPONSE in * * macro parameter list. * * REASON(*) -- put reason at SMMC_REASON in macro * * parameter list.
OUT, ADDRESS((R6)), RESPONSE(*), REASON(*) * * * Important You must set your parameters using only the XPI functions. XPI syntax The XPI functions use special syntax. The description of each function defines only the options that are specific to that call. Options that are applicable to all function calls are described in “Making an XPI call” on page 308. The following argument types are used: name1, name2,.... Each of these refers to the name of a field of the given size in bytes.
len The data length as {namel | (Rn) | expression}: namel The name of a location containing a binary fullword giving the data length in bytes (Rn) A register, the contents of which specify in fullword binary the 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 .
(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 . * A required parameter to indicate that the parameter list is to be used for the reserved fields. If this parameter is coded, then the required value must be taken from the _N component returned in the buffer-descriptor.
CACHE_SIZE(name4) a fullword that specifies the number of bytes available for caching LDAP search results. A value of zero indicates an unlimited cache size. If CACHE_SIZE is specified, CACHE_TIME_LIMIT must also be specified. If neither parameter is specified, results will not be cached. CACHE_TIME_LIMIT(name4) a fullword that specifies the amount of time (in seconds) that LDAP search results are cached. A value of zero indicates an unlimited cache time limit.
RESPONSE KERNERROR PURGED REASON None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The END_BROWSE_RESULTS call The END_BROWSE_RESULTS call allows you to end the browse session that was started by the START_BROWSE_RESULTS call. END_BROWSE_RESULTS DFHDDAPX [CALL], [CLEAR], [IN, FUNCTION(END_BROWSE_RESULTS), SEARCH_TOKEN(name4),] [OUT, [LDAP_RESPONSE(name4),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
[OUT, [LDAP_RESPONSE(name4),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. LDAP_RESPONSE(name4) specifies the return code that is sent by the LDAP API. LDAP_SESSION_TOKEN(name4) the name of the fullword token that was returned by the BIND_LDAP function.
RESPONSE INVALID KERNERROR PURGED REASON None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The GET_ATTRIBUTE_VALUE call The GET_ATTRIBUTE_VALUE call allows you to retrieve the value associated with an attribute returned by the SEARCH_LDAP call. An entry is an LDAP record, and an attribute is one element within an entry.
VALUE_ARRAY_POSITION(name4) specifies the position of the requested value, in the value array for the current attribute. This parameter is only required if multiple values are expected. Array indexing starts at position 1.
VALUE_COUNT(name4) a fullword containing the number of values returned for this attribute. There is usually one value returned. RESPONSE and REASON values for GET_NEXT_ATTRIBUTE: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None BROWSE_END INVALID_BUFFER_LENGTH INVALID_CALLING_SEQUENCE INVALID_TOKEN NOT_FOUND None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
SEARCH_TOKEN(name4) the name of the fullword token that is returned by the SEARCH_LDAP function. RESPONSE and REASON values for GET_NEXT_ENTRY: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None INVALID_TOKEN INVALID_BUFFER_LENGTH INVALID_CALLING_SEQUENCE BROWSE_END None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The SEARCH_LDAP call The SEARCH_LDAP call sends a search request to a specified LDAP server.
address of the data, and the second word contains the length in bytes of the data. For more information on block-descriptors, see “XPI syntax” on page 319. LDAP_RESPONSE(name4) specifies the return code that is sent by the LDAP API. LDAP_SESSION_TOKEN(name4) the name of the fullword token that was returned by the BIND_LDAP function. SEARCH_TIME_LIMIT(name4) specifies the time limit for the search (in seconds). If the search is not successful within this time limit, the search is abandoned.
[LDAP_RESPONSE(name4),] [ATTRIBUTE_COUNT(name4),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. DISTINGUISHED_NAME(buffer-descriptor) indicates the buffer where you want the distinguished name of the first, or only located result returned. A group of three fullwords are specified for the buffer-descriptor: v The address where the data is returned. v The length of the buffer in bytes, where the data is returned. v The maximum length in bytes of the data.
This command is threadsafe. LDAP_RESPONSE(name4) specifies the return code that is sent by the LDAP API. LDAP_SESSION_TOKEN(name4) the name of the fullword token that was returned by the BIND_LDAP function. RESPONSE and REASON values for UNBIND_LDAP: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None INVALID_TOKEN LDAP_INACTIVE None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
The normal synchronization protocol In the normal case, synchronization involves two tasks and three operations. In the following sample operations, the tasks are A (the task that requests a service) and B (the task that processes a request from task A). 1. Task A starts the request by: v Setting the parameters to be used by task B v Resuming task B v Issuing the SUSPEND call. 2.
Task A: Set parameters; Task B: Resume task B; Get parameters; Suspend-fail Process request; Resume-fail; Clean up both Because task-purging is effective only if performed between SUSPEND and RESUME, Suspend-fail precedes Resume-fail.
The ADD_SUSPEND call ADD_SUSPEND acquires a suspend token that can later be used to identify a SUSPEND/RESUME pair. 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 | *)] This command is threadsafe.
name4 The name of a 4-byte field where the token is stored (Rn) A register into which the token value is loaded. 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 “Making an XPI call” on page 308. The SUSPEND call SUSPEND suspends execution of a running task. The task can be resumed in one of two ways.
depends on the setting of the TIME_UNIT option. The INTERVAL value overrides any time-out (DTIMOUT) value specified for the transaction. name4 The name of a 4-byte area, which is interpreted as a binary fullword. (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 17.
name8 The name of the location where an 8-byte value is stored. string A string of characters without intervening blanks; if it is not 8 bytes long, it is extended with blanks or truncated as required. "string" A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string. If you want to document a name (label) in your program, use this form. Note: 1.
IO Waiting on an I/O operation or indeterminate I/O-related operation (locks, buffer, string, and so on). LOCK Waiting on a lock. MISC Waiting on an unidentified resource. 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.
attach) has expired. The token, however, remains suspended and must be the object of a RESUME before it can be the object of a DELETE_SUSPEND. The RESUME call RESUME restarts execution of a task that is suspended or timed out. There must be only one RESUME request for each SUSPEND. However, because this is an asynchronous interface, a SUSPEND can be received either before or after its corresponding RESUME.
2. ‘TASK_CANCELLED’ means that the task was canceled by operator action while it was suspended, and that the suspend token is available for use. The DELETE_SUSPEND call DELETE_SUSPEND releases a suspend token associated with this task. DELETE_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(DELETE_SUSPEND), SUSPEND_TOKEN(name4 | (Rn)),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
Note: ECBs used in WAIT_MVS requests must never be “hand posted”. They must be posted using the MVS POST macro. 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 | *)] This command is threadsafe.
Table 18. WAIT_MVS call - RESPONSE(PURGED) (continued) 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. If the user has set an INTERVAL, then this, too, overrides the PURGEABLE(NO) option.
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.
RESPONSE and REASON values for WAIT_MVS: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None None None None None TASK_CANCELLED TIMED_OUT Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. 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.
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 “Making an XPI call” on page 308. Dump control XPI functions There are two XPI dump control functions. These are the DFHDUDUX macro calls SYSTEM_DUMP and TRANSACTION_DUMP.
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 block-descriptor. DUMPID(name9 | *) returns the dump identifier. name9 The name of a 9-byte field to receive the assigned ID. SYSTEM_DUMPCODE(name8 | string | "string") specifies the code corresponding to the error that caused this system dump call.
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 SET TRANDUMPCODE, in the CICS System Programming Reference manual. Important There is a restriction in using the XPI early during initialization.
end of the list must be marked by a word containing X'FFFFFFFF'. SEGMENT 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.
Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. 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 XPI functions There are two XPI enqueue domain functions. These are the DFHNQEDX macro calls ENQUEUE and DEQUEUE.
rather than enqueue name, allowing the NQ domain to locate the enqueue control block directly, and hence more efficiently. MAX_LIFETIME(DISPATCHER_TASK) MAX_LIFETIME(DISPATCHER_TASK) is required and specifies that all XPI enqueues are owned by the requesting dispatcher task. If you use the ENQUEUE XPI call to ensure that your global user exit programs are threadsafe, you are recommended to free (dequeue) resources during the invocation of the global user exit program in which they were enqueued.
The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, and MAX_LIFETIME(DISPATCHER_TASK) parameters are the same as in the ENQUEUE function call. RESPONSE and REASON values for DEQUEUE RESPONSE OK EXCEPTION REASON None ENQUEUE_NOT_OWNED ENQUEUE_LOCKED Kernel domain XPI 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.
STOP_PURGE_PROTECTION DFHKEDSX [CALL,] [CLEAR,] [IN, FUNCTION(STOP_PURGE_PROTECTION),] [OUT, RESPONSE (name1 | *)] This command is threadsafe. There are no input or output parameters on this call, only a RESPONSE. RESPONSE values for STOP_PURGE_PROTECTION: RESPONSE OK DISASTER INVALID REASON None None None Nesting purge protection calls Note that the START_ and STOP_PURGE_PROTECTION functions can be nested.
The DEFINE_PROGRAM call DEFINE_PROGRAM allows you to define new programs to the loader domain, or to change the details of programs that have already been defined. The details that you provide are recorded on the local catalog, and become immediately available. They are used on all subsequent ACQUIRE requests for the named program. However, note that program definitions made in this way are not retained over an XRF takeover. Also, the CSD is not updated, only the loader domain definitions.
Table 19. Summary of attributes defining DSA eligibility (continued) EXECUTION_KEY option Reentrant Above or below 16MB line Dynamic storage area (DSA) CICS Yes Below RDSA CICS No Above ECDSA CICS Yes Above ERDSA USER No Below UDSA USER Yes Below RDSA USER No Above EUDSA 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.
PRIVATE The program is in the DFHRPL or dynamic LIBRARY concatenation. A PRIVATE program need not be reentrant, and is given only limited protection from unauthorized overwriting.
RESPONSE DISASTER INVALID KERNERROR PURGED REASON CATALOG_NOT_OPERATIONAL None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. 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.
name1 The name of a 1-byte location to receive the program attribute. (Rn) A register in which the low-order byte receives the program attribute and the other bytes are set to zero. It can have the values RELOAD, RESIDENT, REUSABLE, or TRANSIENT. RELOAD The program is not reusable, and therefore several copies of the program may be loaded. A copy is removed from storage when a RELEASE_PROGRAM call (for that copy) is issued.
RESPONSE and REASON values for ACQUIRE_PROGRAM: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None NO_STORAGE PROGRAM_NOT_DEFINED PROGRAM_NOT_FOUND None None None None Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. 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.
name8 The name of a location containing an 8-byte program name. string A string of characters naming the program. "string" A string in quotation marks. The string length is set to 8 by padding with blanks or truncating. PROGRAM_TOKEN(name4), specifies a token identifying the program to be released. name4 The name of a location containing an 4-byte token obtained by a previous DEFINE_PROGRAM or ACQUIRE_PROGRAM call.
string A string of characters naming the program. "string" A string in quotation marks. The string length is set to 8 by padding with blanks or truncating. RESPONSE and REASON values for DELETE_PROGRAM: RESPONSE OK EXCEPTION DISASTER INVALID KERNERROR PURGED REASON None PROGRAM_NOT_DEFINED None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. Log manager XPI functions There are two XPI log manager functions.
RESPONSE INVALID KERNERROR REASON None None The SET_PARAMETERS call SET_PARAMETERS allows you to set the activity keypoint frequency for the CICS region. SET_PARAMETERS DFHLGPAX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PARAMETERS), [KEYPOINT_FREQUENCY(name4 | (Rn) ),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. KEYPOINT_FREQUENCY(name4 | *) specifies the activity keypointing frequency of the CICS region. Permitted values are 0, or any integer between 200 and 65535 inclusive.
INQUIRE_MONITORING_DATA calls cannot be used in any exit program invoked from any global user exit point in DFHTCP or DFHZCP (that is, at any of the exit points named “XTCx...” or “XZCx...”). The MONITOR call The MONITOR XPI call is similar to the EXEC CICS MONITOR command. It enables you to invoke user event-monitoring points (EMPs) in your exit programs.
expression A valid assembler-language expression giving the fullword binary variable for this EMP. name4 The name of a 4-byte field containing the fullword binary variable for this EMP. (Ra) A register containing the fullword binary variable for this EMP. * The value of this option is already present in the parameter list, or the option is not specified for this EMP.
"string" A string, enclosed in quotation marks, and possibly containing blanks. This value is processed in the same way as the “string” above. Note: If, when defining the EMP in the MCT, you do not specify an entry name, the entry name defaults to ‘USER’. ENTRYNAME likewise defaults to ‘USER’ if not specified. POINT(expression | name2 | (Rn)) specifies the monitoring point identifier as defined in the MCT, and is in the range 0 through 255.
The DFHMNTDS DSECT that maps the data is of fixed format. Note that: v All the CICS system-defined fields in the performance records (including fields that you have specified for exclusion using the EXCLUDE option of the DFHMCT TYPE=RECORD macro) are listed. v No user-defined data fields are listed. INQUIRE_MONITORING_DATA DFHMNMNX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_MONITORING_DATA), DATA_BUFFER(buffer-descriptor),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
Program management XPI functions There are eight XPI program management functions. These are the DFHPGISX calls: INQUIRE_PROGRAM INQUIRE_CURRENT_PROGRAM SET_PROGRAM START_BROWSE_PROGRAM GET_NEXT_PROGRAM END_BROWSE_PROGRAM 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.
[PROGRAM_LENGTH(name4),] [PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY),] [PROGRAM_USAGE(APPLICATION|NUCLEUS),] [PROGRAM_USE_COUNT(name4),] [PROGRAM_USER_COUNT(name4),] [REMOTE_DEFINITION(LOCAL|REMOTE),] [REMOTE_PROGID(name8),] [REMOTE_SYSID(name4),] [REMOTE_TRANID(name4),] [SPECIFIED_AMODE(24|31|AMODE_ANY|AMODE_NOT_SPECIFIED),] [SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
| | | | THREADSAFE The program is defined as threadsafe, and is able to run under whichever TCB is in use by its user task when the program is given control. This could be either an open TCB or the CICS QR TCB. | | | Note: In the case of a Language Environment-conforming program, the concurrency as originally defined can be overridden when the program is subsequently loaded.
USER CICS gives control to the program in user key. The program is loaded into a user DSA, above or below the 16MB line; that is, the UDSA or EUDSA, depending on its residency mode (RMODE) attribute as defined to the linkage-editor. EXECUTION_SET(DPLSUBSET|FULLAPI|NOT_APPLIC) returns a value indicating whether CICS links to and runs the program as if it were running in a remote CICS region. DPLSUBSET CICS links to and runs the program with the API restrictions of a remote DPL program.
LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|LE370| NOT_APPLIC|NOT_DEFINED|PLI) returns the programming language specified on the resource definition. LIBRARY(name) returns the 8-character name of the LIBRARY resource from which this program was loaded. This is blank if the program has not been loaded, or if the LPASTATUS is LPA (indicating that the program has been loaded from the LPA). LIBRARYDSN(data-area) displays the 44-character name of the data set from which the program was loaded.
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. If PROGRAM_TOKEN is specified on the request, NEW_PROGRAM_TOKEN is set to the same value.
NOT_APPLIC Not applicable. The program is remote. PRIVATE The program is to be loaded from the DFHRPL or dynamic LIBRARY concatenation.. 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). SHARED The program is to be loaded from the link pack area (LPA).
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.
This command is threadsafe. Note: The options not described in the following list are identical to the equivalent options of the INQUIRE_PROGRAM call. 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.
| | where a global user exit program or task-related user exit program is involved, the options return information about the exit program. | | | | INVOKING_ENVIRONMENT (EXEC|GLUE|PLT|SYSTEM|TRUE|URM) returns the environment from which the current program was invoked; that is, the environment corresponding to the program named in INVOKING_PROGRAM_NAME. The values are as described for CURRENT_ENVIRONMENT.
SET_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PROGRAM), {PROGRAM_NAME(name8 | string | ’string’)| PROGRAM_TOKEN(name4)},] [AVAIL_STATUS(DISABLED|ENABLED),] [CEDF_STATUS(CEDF|NOCEDF),] [EXECUTION_KEY(CICS|USER),] [EXECUTION_SET(DPLSUBSET|FULLAPI),] [PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),] [PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),] [PROGRAM_USAGE(APPLICATION|NUCLEUS),] [REQUIRED_AMODE(24|31|AMODE_ANY),] [REQUIRED_RMODE(24|RMODE_ANY),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] Thi
FULLAPI CICS links to and runs the program without the API restrictions of a remote DPL program. The program can use the full CICS API. PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT) specifies the residency status of the program—that is, when its storage is to be released. RELOAD The program is not reusable, and therefore several copies may be loaded. A copy is removed from storage when a RELEASE_PROGRAM call (for that copy) is issued.
TYPE_ANY Either the copy in the DFHRPL or a dynamic LIBRARY concatenation, or the LPA copy of the program can be used, though preference is given to the LPA copy. PROGRAM_USAGE(APPLICATION|NUCLEUS) specifies whether the program is used as a CICS nucleus program or as a user application program. REQUIRED_AMODE(24|31|AMODE_ANY) specifies the addressing mode of the program. If, during subsequent processing, no copy of the program that meets the defined addressing requirement can be found, an exception occurs.
The START_BROWSE_PROGRAM call START_BROWSE_PROGRAM returns a token that enables you to begin browsing through program definitions, optionally starting at the definition of a specified program. START_BROWSE_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(START_BROWSE_PROGRAM), [PROGRAM_NAME(name8 | string | ’string’),]] [OUT, BROWSE_TOKEN(name4) RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
The GET_NEXT_PROGRAM call GET_NEXT_PROGRAM allows you to inquire on the next program definition during a browse sequence initiated by START_BROWSE_PROGRAM. The browsing sequence is alphabetical. The end of the alphabetic list of definitions is indicated by an 'END_LIST' exception response.
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.
The INQUIRE_AUTOINSTALL call INQUIRE_AUTOINSTALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets. INQUIRE_AUTOINSTALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_AUTOINSTALL),] [OUT, [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
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 | *)] This command is threadsafe. 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 XPI 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.
* The parameter list itself, in name APIQ_EIB, is used to hold the address. RSA(name4 | (Rn | * ) returns the address of the register save area for the current task. name4 The name of a fullword area that is to receive the address of the register save area. (Rn) A register that is to receive the address of the register save area. * The parameter list itself, name APIQ_RSA, is used to hold the address. SYSEIB(name4 | (Rn) | *) returns the address of the system EXEC interface block of the current task.
name4 The name of a 4-byte area that is to receive the length, in bytes, of the TWA. (Rn) A register that is to receive the length of the TWA. * The parameter list itself, name APIQ_TWASIZE, is used to hold the length of the TWA.
[TIMEOFDAY(name4| *),] [XRFSTATUS(NOXRF | PRIMARY | TAKEOVER),] RESPONSE (name1 | * ), REASON (name1 | * )] This command is threadsafe. CICSREL(name4 | *) returns the level number of the CICS code under which the CICS region is running. name4 The name of a 4-byte location that is to receive the level number characters as hexadecimal values. CICSSTATUS(ACTIVE|FINALQUIESE|FIRSTQUIESCE|INITIALIZING) returns the status of the CICS region. ACTIVE The CICS region is active and ready to receive work.
name4 The name of a 4-byte location that is to receive the date. DTRPRGRM(name8 | *) returns the name of the dynamic routing program. name8 The name of an 8-byte area that is to receive the name of the dynamic routing program. GMMLENGTH(name2 | *) returns the length in bytes of the “good morning” message. name2 The name of a 2-byte area that is to receive the length of the good morning message.
name2 The name of a 2-byte area that is to receive, as a half-word binary value, the level number of the MVS element of OS/390. For example, OS/390 Release 3 MVS is represented by 03. Note: This field is supported for compatibility purposes only. The information is derived from the last two numbers held in the MVS CVTPRODN field. For example, CVTPRODN holds SP5.2.2 for MVS/ESA SP Version 5 Release 2.2 (in which case OPREL returns 22), and SP6.0.3 for OS/390 Release 3.
NOTSHUTDOWN CICS is not in shutdown mode. SHUTDOWN CICS is performing an immediate shutdown. STARTUP(COLDSTART|EMERGENCY|WARMSTART) returns the type of startup the CICS region performed. COLDSTART CICS performed a cold start, either because this was explicitly specified on the system initialization parameter, or because CICS forced a cold start because of the state of the global catalog. EMERGENCY CICS performed an emergency restart because the previous run did not shut down normally with a warm keypoint.
RESPONSE INVALID EXCEPTION REASON INVALID_FUNCTION LENGTH_ERROR UNKNOWN_DATA INQ_FAILED None DISASTER PURGED The SET_SYSTEM call The SET_SYSTEM call allows you to set CICS system data values in the AP domain. 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 | * )] This command is threadsafe.
RESPONSE and REASON values for SET_SYSTEM: RESPONSE OK INVALID EXCEPTION DISASTER PURGED REASON None INVALID_FUNCTION AKP_SIZE_ERROR NO_KEYPOINT SET_FAILED None Storage control XPI 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.
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 | *)] This command is threadsafe. ADDRESS(name4 | (Rn) | *) returns the address of the storage obtained by the call.
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 20. Table 20.
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.
[OUT, ACCESS(CICS | READ_ONLY | USER), RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. 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. ELEMENT_LENGTH(name4 | (Rn) | *) specifies the length of the storage element, in bytes. A length of zero is treated as a length of one.
ELEMENT_ADDRESS(name4 | (Rn) | *) returns the start address of the element of task-lifetime storage referenced by the ADDRESS parameter. The start address returned does not include the leading check zone. ELEMENT_LENGTH(name4 | (Rn) | *) returns the length of the element of task-lifetime storage referenced by the ADDRESS parameter. The length returned does not include the leading or trailing check zones.
RESPONSE and REASON values for INQUIRE_SHORT_ON_STORAGE: RESPONSE OK DISASTER KERNERROR REASON None None None The INQUIRE_TASK_STORAGE call INQUIRE_TASK_STORAGE enables you to request details of all elements of task-lifetime storage belonging to a task. You can specify the transaction number of the task explicitly on the call, or let it default to the current task.
RESPONSE DISASTER INVALID KERNERROR PURGED REASON NO_TRANSACTION_ENVIRONMENT None None None None The SWITCH_SUBSPACE call SWITCH_SUBSPACE causes CICS to switch from a subspace to base space, if the task is not already executing in the base space. If the task is already in the base space, storage manager ignores the call. This function can be used by global user exit programs that receive control in subspace and for some reason need to switch into basespace.
The TRACE_PUT call TRACE_PUT writes a trace entry to the active trace destinations. You should only make a TRACE_PUT call when UEPTRON indicates that tracing is active for the function containing the exit program (see UEPTRON in DFHUEPAR). You may prefer to make “exception” trace entries, in case of serious errors, without testing UEPTRON.
expression A valid assembler-language expression that results in the address name4 The name of a fullword containing the address (Ra) A register containing the address. RESPONSE values for TRACE_PUT The RESPONSE field is never set for the TRACE_PUT function. This is for performance reasons. It is not considered that any useful purpose could be served by testing for this value. Note, however, that the syntax requires that RESPONSE is always specified as a parameter on the call.
name8 The name of an 8-byte location to receive the name of the bridge exit program. BRIDGE_TRANSACTION_ID(name4) returns the name of the bridge monitor transaction that issued a START BREXIT TRANSID command to start this transaction. If CONTEXT returns NORMAL, the contents of this field are meaningless. name4 The name of a 4-byte location to receive the name of the bridge monitor transaction. BRXA_TOKEN(name4) returns a token that contains the address of the bridge exit area (BRXA) used by this task.
The INQUIRE_DTRTRAN call INQUIRE_DTRTRAN returns the name of the dynamic transaction routing (DTR) transaction definition. 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.
MXT_QUEUED(name4 | (Rn) ), TCLASS_QUEUED(name4 | (Rn) ), RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe. CURRENT_ACTIVE(name4 | (Rn)) returns the current number of all active user tasks. name4 The name of a 4-byte location that is to receive the current number of active user tasks, expressed as a binary value. (Rn) A register to receive the current number of active user tasks, expressed as a binary value. MXT_LIMIT(name4 | (Rn)) returns the current number of the MXT parameter.
The INQUIRE_TCLASS call The INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Its purpose is to provide current information about the specified transaction class (TCLASS). INQUIRE_TCLASS DFHXMCLX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TCLASS), INQ_TCLASS_NAME(name8 | string | 'string'),] [OUT, [CURRENT_ACTIVE(name4 | (Rn)),] [CURRENT_QUEUED(name4 | (Rn)),] [MAX_ACTIVE(name4 | (Rn)),] [PURGE_THRESHOLD(name4 | (Rn)),] RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe.
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.
[SHUTDOWN(name1),] [SPURGE(name1),] [STATUS(name1),] [STORAGE_CLEAR(name1),] [STORAGE_FREEZE(name1),] [SYSTEM_ATTACH(name1),] [SYSTEM_RUNAWAY(name1),] [TASKDATAKEY(name1),] [TASKDATALOC(name1),] [TCLASS(name1),[TCLASS_NAME(name8),]] [TPURGE(name1),] [TRACE(name1),] [TRAN_PRIORITY(name4 | (Rn)),] [TRAN_ROUTING_PROFILE(name8),] [TRANSACTION_ID(name4),] [TWASIZE(name4 | (Rn)),] RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe.
XMXD_NO A transaction dump is not required. DYNAMIC(name1) returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined for dynamic transaction routing. XMXD_YES The transaction is to be dynamically routed to a remote CICS. XMXD_NO The transaction is not to be dynamically routed.
name4 The name of a 4-byte location that contains the name of the transaction identifier. string A string of characters, without intervening blanks, naming the transaction identifier. ‘string’ A string of characters, within quotation marks, naming the transaction identifier. The string length is set to 4 by padding with blanks within the quotation marks.
XMXD_OWN The reserved name OWN is specified for the partitionset, which means tasks running under this transaction definition perform their own partitionset management. PARTITIONSET_NAME(name8) returns the name of the partitionset defined on the transaction definition. name8 The name of an 8-byte location that is to receive the name of the partitionset. PROFILE_NAME(name8) returns the name of the profile definition that is associated with the transaction definition.
XMXD_NO The transaction cannot be restarted. XMXD_YES The transaction can be restarted. ROUTABLE_STATUS(ROUTABLE|NOT_ROUTABLE) returns a value indicating whether, if the transaction is the subject of an eligible EXEC CICS START command, it will be routed using the enhanced routing method. NOT_ROUTABLE If the transaction is the subject of a START command, it will be routed using the “traditional” method.
STORAGE_CLEAR(name1) returns, in a 1-byte location (name1), an equated 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. XMXD_NO Task-lifetime storage need not be cleared before it's freed. XMXD_YES Task-lifetime storage must be cleared before it's freed.
TCLASS(name1) returns, in a 1-byte location (name1), an equated value indicating whether the transaction belongs to a transaction class. XMXD_NO The transaction is not a member of a transaction class. XMXD_YES The transaction is a member of the transaction class named in the TCLASS_NAME parameter. 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.
name4 The name of a 4-byte location that contains the name of the transaction identifier. TWASIZE(name4 | (Rn)) returns the size of the transaction work area specified on the transaction definition. name4 The name of a 4-byte location to receive the size of the transaction work area, expressed as a binary value. (Rn) A register to receive the size of the transaction work area, expressed as a binary value.
[TASK_PRIORITY(name1),] [TCLASS(name1),[TCLASS_NAME(name8),]] [TERMINATE_PROTECTED(name1),] [TPURGE(name1),] [TRANNUM(name4 | string | 'string'),] [TRAN_PRIORITY(name1),] [TRAN_ROUTING_PROFILE(name8),] [TRANSACTION_ID(name4),] [USERID(name8),] RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe. The descriptions of the following parameters are the same as the corresponding parameters on the INQUIRE_TRANDEF function call.
XMIQ_TD The principal facility is a transient data queue. XMIQ_TERMINAL The principal facility is a terminal. NETNAME(name8) returns the network name of the principal facility associated with this task. name8 The name of an 8-byte location to receive the network name. 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.
START_CODE(name1) returns, in a 1-byte location (name1), an equated value indicating how the task was started: C A CICS internal attach. XMIQ_DF The start code isn't yet known—to be set later. XMIQ_QD A transient data trigger level attach. XMIQ_S A START command without any data. XMIQ_SD A START command with data. XMIQ_SZ A front end programming interface (FEPI) attach. XMIQ_T A terminal input attach. XMIQ_TT A permanent transaction terminal attach.
TRANNUM(name4) returns the task number of the transaction. name4 The name of a 4-byte location to receive the task number. TRANSACTION_TOKEN(name8) specifies the transaction token for the task being inquired upon. This parameter is optional, and if omitted, the current task is assumed. If you issue this call within an XXMATT global user exit program, the current task may be a CICS system task.
TASK_PRIORITY(name4) specifies the new task priority being set for the task identified by TRANSACTION_TOKEN. name4 The name of a 4-byte location that contains the new task priority number, expressed as a binary value. TCLASS_NAME(name8) specifies the new transaction class name that you want to associate this task with. To specify that the task is not to be in any transaction class, specify the special default system name DFHTCL00.
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 | *)] This command is threadsafe. Important There is a restriction in using the XPI early during initialization.
RESPONSE DISASTER INVALID KERNERROR PURGED REASON JOURNAL_NOT_OPEN LENGTH_ERROR STATUS_ERROR None None None None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. Chapter 3.
422 Customization Guide
Part 2. Customizing with initialization and shutdown programs © Copyright IBM Corp.
424 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. This information is divided into the following sections: 1. “Writing initialization programs” 2. “Writing shutdown programs” on page 428 3.
v First phase PLTPI programs must not enable any task-related user exit program with the TASKSTART option. v Because first-phase PLT programs run so early in CICS initialization, no resource definitions are available. This means that you cannot use installed PROGRAM definitions (or the program autoinstall user program) to define first-phase PLT programs to CICS, nor to define the user exit programs that first-phase PLT programs enable. Instead, default definitions are installed automatically by CICS.
Note: A pseudo-terminal: – Must be a surrogate TCTTE that exists only in an AOR – Can be used only in a transaction routing environment – Cannot exist with distributed program link (DPL) requests – Cannot exist with any type of function shipping request | | | | | | – Cannot exist in a distributed transaction. v PLTPI programs can request services that could suspend the issuing task, but note that this affects the time at which control is given to CICS.
Writing shutdown programs Any program that is to execute during CICS shutdown must be defined in a program list table (PLT), and the PLT must be named on the program list table shutdown (PLTSD) system initialization parameter. You can override the PLTSD value by providing a PLT name on the CEMT PERFORM SHUTDOWN command, or on the EXEC CICS PERFORM SHUTDOWN command. If a PLTSD program abends, syncpoint rollback occurs.
to be started, and they cannot communicate with terminals. Further, second phase PLT programs must not cause any resource security checking or DB2 calls to be performed. If a transaction abend occurs while the PLTSD program is running, CICS is left in a permanent wait state. To avoid this happening, ensure that your PLTSD program handles all abend conditions. The second quiesce stage is complete when all of the second phase PLT programs have been executed.
program causes the relevant unit of work to be shunted. The PLTPI program abends ASP1, and CICS runs the next program defined in the PLTPI table, if any. v PLTSD programs run under the transaction that issued the PERFORM SHUTDOWN command. The CEMT transaction is defined with WAIT(YES). Therefore, if shutdown is as the result of a CEMT PERFORM SHUTDOWN command, an in-doubt failure that occurs while running a PLTSD program causes the unit of work to be shunted.
| | | 1. Create a separate PROGRAM resource definition using the same JVMCLASS attribute value and specify EXECKEY(CICS). 2. Add the PROGRAM resource definition to the PLT. | | The original PROGRAM resource definition with EXECKEY(USER) can then be used subsequently.
432 Customization Guide
Part 3. Customizing with user-replaceable programs © Copyright IBM Corp.
434 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. The chapter is divided into the following sections: 1. “Rewriting user-replaceable programs” 2. “Assembling and link-editing user-replaceable programs” on page 436 3. “User-replaceable programs and the storage protection facility” on page 437.
Assembling and link-editing user-replaceable programs The source for the CICS-supplied user-replaceable programs is installed in the CICSTS32.CICS.SDFHSAMP library. If you intend changing any of these programs, take a copy of the CICSTS32.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.
2 The library into which the load module will be link-edited. 3 Optionally, the name of a library containing your local Assembler macros and copy members. 4 These options are required for DFHXCURM, and for the supplied sample versions of DFHTEP and DFHZNEP. 5 your_sourcelib is the name of the library containing your modified version of the program. 6 program_name is the source member name of the user-replaceable program being assembled. The source member for the supplied DFHTEP sample is DFHXTEP.
Data storage key for user-replaceable programs The storage key of storage used by user-replaceable programs depends on how the storage is obtained: v The communication area passed to the user-replaceable program by its caller is always in CICS key. v Any working storage obtained for the user-replaceable program is in the key set by the TASKDATAKEY of the transaction under which the program is invoked.
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 435 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.
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 value of PEP_COM_KEY is significant for abend codes ‘ASRA’ and ‘ASRB’ only.
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 ...
DFHPEP_COMMAREA DSECT * * Standard header section * PEP_COM_STANDARD DS 0F PEP_COM_FUNCTION DS CL1 Always ’1’ PEP_COM_COMPONENT DS CL2 Always ’PC’ PEP_COM_RESERVED DS C Reserved * * Abend codes and EIB * PEP_COM_CURRENT_ABEND_CODE DS CL4 Current abend code PEP_COM_ORIGINAL_ABEND_CODE DS CL4 Original abend code PEP_COM_USERS_EIB DS CL(EIBRLDBK-EIBTIME+L’EIBRLDBK) * EIB at last EXEC CICS command * * Debugging information (program, PSW, registers and execution key at * time of abend, hit storage indicator).
The sample program error programs Two source-level versions of the default program are provided: DFHPEP, coded in assembler language, and DFHPEPD, coded in C. Both are in the CICSTS32.CICS.SDFHSAMP library. There is an assembler-language macro, DFHPCOM, and a corresponding C copy book, DFHPCOMD, that you can use to define the communication area. These are found in the CICSTS32.CICS.SDFHMAC and CICSTS32.CICS.SDFHC370 libraries, respectively.
444 Customization Guide
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)).
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. v The transaction must be related to a principal facility. If these conditions are satisfied, CICS invokes the transaction restart program, which then decides whether or not to request that the transaction be restarted.
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 equated values for this parameter are: XMRS_SYNCPOINT_YES Means one or more syncpoints have been performed. XMRS_SYNCPOINT_NO Means no syncpoints have been performed.
v AFCW, indicating that the transaction abended due to a VSAM-detected deadlock (RLS only). The source of the CICS-supplied default transaction restart program, DFHREST, is supplied in assembler language only, in the CICSTS32.CICS.SDFHSAMP library. The assembler copybook for mapping the communications area is in the CICSTS32.CICS.SDFHMAC library.
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 435 apply to this chapter. This chapter contains information about the CICS terminal error program (TEP), which handles error conditions for devices that use the sequential access method. Note that node error programs, not terminal error programs, must be used for VTAM-supported devices.
version of the terminal error program (DFHTEP, either CICS-supplied or user-written), so that it can take the appropriate action. Terminal control program When the terminal from which the error was detected has been put out of service, the terminal control program creates a terminal abnormal condition line entry (TACLE), which is chained off the real entry, the terminal control table line entry (TCTLE) for the line on which the error occurred. The TACLE contains information about the error.
The communication area The communication area is the basic interface used by the sample DFHTEP, and should be used by a user-written DFHTEP to: v Address the TACLE v Indicate the course of action to be taken on return to DFHTACP. Before giving control to DFHTEP, DFHTACP establishes which default actions should be taken. This depends on the particular error condition that has been detected. The default actions are indicated by appropriate bit settings in the 1-byte communication area field TEPCAACT.
of as the number of error occurrences that are permitted for a given type of error on a given terminal before the sample DFHTEP accepts the DFHTACP default actions. Optionally, the number of occurrences can be controlled and accounted for over prescribed time intervals (for example, if more than three of a given type of error occur in an hour, the terminal is put out of service).
SYMBOLIC TERMINAL ID . . . ERROR STATUS ELEMENT . . . . . . COMMON ERROR BUCKET Figure 21. Terminal error block (TEB) An ESE records the occurrence of a particular type of error associated with the terminal. The contents of an error status element are described in the TEPCD DSECT (generated by the DFHTEPM TYPE=INITIAL macro) under the comment “ERROR STATUS ELEMENT FORMAT”. The number of ESEs per TEB remains constant for all TEBs. You specify the number when the TEP tables are generated.
Figure 22 on page 456 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. It obtains addressability to the communication area passed by DFHTACP by means of an EXEC CICS ADDRESS COMMAREA, and addressability to the EXEC interface block with an EXEC CICS ADDRESS EIB command.
General exit Control is passed to a general exit routine from each error processor. This routine determines whether the terminal is to remain in service. If the terminal is to be put out of service, the terminal error block and all error status elements for that terminal are deleted from the TEP error table unless the terminal was defined as a permanent entry. When the terminal is placed back in service, a new terminal error block is assigned if a subsequent error occurs.
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 22.
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 error text is one of the following: Unsupported error code, “xx” The error code presented to DFHTEP by DFHTACP is unknown to DFHTEP.
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]). See the TACLE DSECT described in “Writing your own terminal error program” on page 470.
macros are related and care must be taken to ensure compatibility. The parameters concerned are identified in the descriptions of the macros later in this chapter. If you use the sample terminal error program (DFHXTEP), you can generate the required program and transaction definitions by using the CEDA INSTALL GROUP(DFHSTAND) command.
DFHTEPM TYPE=INITIAL [,DSECTPR={YES|NO}] [,OPTIONS=([TD|(TD,destid)|NOTD] [,EXITS|,NOEXITS] [,TIME|,NOTIME] [,PRINT=([ERRORS|NOERRORS] [,TACPACTION|,NOTACPACTION] [,TEPACTION|,NOTEPACTION] [,TID|,NOTID] [,DECB|,NODECB] [,TACLE|,NOTACLE] [,ESE|,NOESE])] TYPE=INITIAL establishes the beginning of the generation of the sample DFHTEP module itself. DSECTPR={YES|NO} controls the printing of CICS DSECTs on the sample DFHTEP assembly listing. Its purpose is to reduce the size of the listing.
TIME This type of threshold testing is supported. NOTIME This type of threshold testing is not supported. PRINT=print-information specifies which types of information are to be logged to the transient data destination each time an error occurs. If NOTD is specified on the OPTIONS operand, all PRINT parameters default to NO. All PRINT parameters require the transient data output routine. The parentheses are required even when only one parameter is specified.
TACLE|NOTACLE specifies whether the TACLE prefix is to be recorded on the transient data destination. TACLE The 16-byte TACLE prefix as received from DFHTACP is logged. NOTACLE No TACLE prefix logging occurs. ESE|NOESE specifies whether the ESE associated with the error is to be recorded on the transient data destination. ESE The ESE, after being updated, and before being deleted (if the action puts the terminal out of service) is logged. NOESE No ESE logging occurs.
TYPE=ERRPROC indicates that a CICS-supplied error processor routine is to be replaced with the user-written error processor that immediately follows the macro. This macro is optional; if used, it must follow the DFHTEPM TYPE=INITIAL macro. One DFHTEPM TYPE=ERRPROC macro must precede each user-written error processor source routine. CODE=errcode is used to identify the error code assigned to the appropriate error condition. These codes are listed in Figure 26 on page 474.
* GENERATE USER STORAGE DFHTEPM USORFLD DS DFHTEPM TYPE=USTOR F TYPE=USTOREND * MODULE SPECIFICATIONS DFHTEPM TYPE=INITIAL, OPTIONS=((TD,TEPQ),NO3270,EXITS), PRINT=(NOTEPACTION,NOTACPACTION), DSECTPR=NO * * * * USER-SUPPLIED ERROR PROCESSORS DFHTEPM TEPCD81 DS B TYPE=ERRPROC,CODE=87 0H DFHTEPM TEPCD9C DS B TYPE=ERRPROC,CODE=9F 0H error processor "87" source statements TEPRET error processor "9F" source statements TEPRET * USER "EXIT" EXIT CODE DFHTEPM TYPE=EXIT TEPEXIT DS 0H Additional user sourc
DFHTEPT TYPE=INITIAL–establishing the control section The DFHTEPT TYPE=INITIAL macro necessary to establish the control section for the TEP tables is: DFHTEPT TYPE=INITIAL ,MAXTIDS=number [,MAXERRS={25|number}] [,OPTIONS={TIME|NOTIME}] TYPE=INITIAL establishes the beginning of the generation of the TEP tables. MAXTIDS=number specifies the total number of permanent and reusable terminal error blocks to be generated in the TEP error table.
TYPE=PERMTID defines permanently reserved terminal error blocks for specific terminals. Permanent TEBs are defined for terminals that are critical to system operation to ensure that error processors are always executed in the event of errors associated with that terminal. If no permanent TEBs are to be defined, this macro is not required. A separate macro must be issued for each permanently reserved TEB.
default actions to be taken. If the number of occurrences is less than the threshold, the error processor normally takes a logic path that overrides the DFHTACP default actions. The updating and testing of the current threshold counts are normally performed by a DFHTEP subroutine that sets a condition code that the error processor can test to determine whether the limit has been reached. If you specify 0 as the number in the COUNT operand, you are not told when the threshold is reached.
Table 23 illustrates the default thresholds of the sample terminal error program, referred to in the TYPE, COUNT, and TIME operands of the DFHTEPT TYPE=PERMCODE|ERRCODE macro. Table 23. Default thresholds of the sample TEP CODE= COUNT= TIME= 81 3 (7,MIN) 84 1 0 85 1 0 87 50 (Note 2) 0 88 1 0 8C 1 0 8D 1 0 8E 1 0 8F 1 0 90 0 0 91 0 0 94 7 (10,MIN) 95 (Note 1) 0 0 96 2 (1,MIN) 97 (Note 1) 0 0 99 1 0 9F (Note 1) 0 0 BUCKET 5 (5,MIN) Notes: 1.
DFHTEPT TYPE=FINAL–terminating DFHTEPT entries The DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEP tables. DFHTEPT TYPE=FINAL DFHTEPT–examples of how the macros are used 1. The following is an example of the minimum number of statements required to generate the TEP tables: DFHTEPT DFHTEPT END TYPE=INITIAL,MAXTIDS=10 TYPE=FINAL This example generates 10 reusable terminal error blocks, each capable of accounting for the maximum number of error types.
Writing your own terminal error program You can write your own terminal error program in any of the languages supported by CICS. However, CICS-supplied code is provided in assembler language only. The names of the supplied source files and macros, and the libraries in which they can be found, are listed in Table 24. Table 24. Supplied source files and macros Name Type Description Library DFHXTEP Source Sample terminal error program (assembler language) CICSTS32.CICS.
Addressing the contents of the communication area After your terminal error program receives control from DFHTACP, it should obtain the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command. You generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program. The layout of the communication area is shown in Figure 25.
ABORTWR (X'08') Abend write, free terminal storage RELTTIOA (X'04') Release TCAM incoming message. (TCAM is no longer supported.) SIGNOFF (X'02') Call sign-off program. On entry to DFHTEP, the above flags represent the default actions set by DFHTACP.
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.
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. The format of the TACLE DSECT is shown in Figure 26.
Displacement Dec Hex 0 0 Code Bytes Label Meaning 4 Storage accounting TCTLEPSA RESERVED 8 8 1 TCTLEPFL 81 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: no longer supported) 96 97 99 9F . . . .
(PCICNT) represents a user-defined field used to accumulate the count of recursive errors. It should be in the process control information (PCI) area of the TCTTE. SYSTEM COUNT (TCTTENI) represents the 6-byte field in the TCTTE that contains the terminal input and output counts (TCTTENI+TCTTENO). In the example, these two adjacent fields are considered as one 6-byte field.
*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 STATBAR EQU 4 Pointer to statistics DSECT TCTUABAR EQU 5 Pointer to TCTU
EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) Get statistics for this terminal using TERMID passed in Commarea * * * * * INCR 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. Increment the number of times this error has occurred (recursive count) Has the maximum recursive error limit been reached? NO ....
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 435 apply to this chapter. This chapter contains information about the node error program (NEP) of CICS Transaction Server for z/OS, Version 3 Release 2. Node error programs, not terminal error programs, must be used for terminals and logical units supported via the ACF/VTAM interface.
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.) In a few cases, exceptions signaled to CICS by VTAM are not treated as errors, and are not passed to the node error handler.
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. For example, if an error were signaled during the sending of a document to a printer, it might be able to restart from the beginning, or from a specific page. v Some devices, such as the 3650 Retail Store System, return application-type data in “User Sense Data” fields. This can only be retrieved in a NEP.
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 855.
other, reusable NEBs for general use. If you expect to accumulate error statistics about 10 LUs concurrently, you need 10–12 NEBs. Each NEB may contain multiple recording areas, one being used for each group of errors you want to distinguish. The error groups correspond to those in the NEP. That is, they are groups of error types requiring separate processing logic. Each recording area is known as an error status block (ESB).
will then locate the correct ESB within a selected NEB. The latter may be permanently dedicated to the LU in error (a named NEB), or may be one taken from the general pool. The initial code then invokes the appropriate user logic for that error group. The initial code also sets up pointers to the communication area, the NEB, and the ESB. For details, see “Generating the sample node error program” on page 499. The common routines in the NEP provide common services for your own logic.
The 3270 sample code is not intended to cover all error conditions. Note that the code is not suitable for SNA 3270s (LU session type 2). Error conditions arising from these result in different DFHZNAC error codes and may require different handling. You may find that the CICS-supplied code is not sufficient for other, application-related, reasons. Perhaps you want to try to reacquire lost sessions after a time interval.
You also have to provide the sub-NEPs for the various NEP transaction classes, including, of course, one for the default NEPCLASS(0). Each of these sub-NEPs needs a separate program definition. You have the same choice in coding each sub-NEP as you had when there was just one; you can code your own, or use the CICS sample macro DFHSNEP.
DFHZNAC assumes that system sense codes are available upon receipt of an exception response from the logical unit. Thus, analysis is performed to determine the reason for the response. Decisions, such as which action flags to set and which requests are needed, are made based upon the system sense codes received. If sense information is not available, default action flags are set, and DFHZEMW is scheduled to send a negative response, if a response is outstanding, with an error message to the terminal.
Header Error_being_processed User option bytes VTAM information Additional information for NEP Additional system parameters XRF parameters Figure 30. General structure of the communication area The significance of each section of the communication area is described below: Header A 4-byte header common to all user-replaceable programs. Error_being_processed Identifiers of the error code and the terminal associated with the error.
********************************************************************** ** 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 it ** ** These fields are READ ON
********************************************************************** ** 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 sense byte No 2 * TWASENSR DS 0F
********************************************************************** ** 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 for TCTTE TWACOMMA DS CL4 Address
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. Setting the TWAONQN flag causes the network qualified name to be printed after any message that contains the action flag. Similarly setting the TWAOTNA flag causes the TNADDR information to be printed. The flags are: TWAOAF (X'80') Print action flags. TWAORPL (X'40') Print VTAM RPL. TWAOTCTE (X'20') Print TCTTE. TWAOTIOA (X'10') Print TIOA.
“good morning” message transaction is initiated (the transaction specified by the system initialization parameter GMTRAN). The flags are: TWAOAS (X'80') Abandon any SEND for this terminal TWAOAR (X'40') Abandon any RECEIVE for this terminal TWAOAT (X'20') Abend any task attached to TCTTE TWAOCT (X'10') Cancel any task attached to TCTTE TWAOGMM (X'08') “good morning” message to be sent TWAOPBP (X'04') Purge any BMS pages for this session TWAOASM (X'02') SIMLOGON required. Note: 1.
TWAONCN (X'10') Normal CLSDST (no reset allowed) TWAOSCN (X'08') Normal CLSDST (reset allowed) TWAONEGR (X'04') Send negative response TWAOOS (X'02') Keep node out of service TWAOCN (X'01') CLSDST node. Do not set this flag when processing error codeX'49' (TCZCLSIN). TWAONINT forces TWAOCN. TWAONEGR forces TWAOAR and TWAOAT. TWAOOS forces TWAOCN. TWAOCN forces TWAOAR, TWAOAS, and TWAOAT. TWAOOS indicates that no further processing is to be done for this node. The node is logically out of service.
TWANLD of the communication area, and the length of the data in field TWANLDL. The data is logged to the CSNE transient data queue for future inspection. Note: No data in excess of 220 bytes is logged. You can also send user-written messages to the CSNE log using the transient data facility. To write your messages, you must code the EXEC CICS WRITEQ TD instruction directly into the node error program.
The sample node error program The sample node error program provides a general environment for the execution of error processing routines (error processors), each of which is specific to certain error codes generated by the node abnormal condition program. Sufficient optional error processors for normal operation of VTAM 3270 or interactive logical unit networks are provided; these can be easily supplemented or replaced by user-supplied error processors.
v Optional error processors for 3270 or interactive logical units. A node error program cannot be generated with both 3270 and interactive logical unit error processors. The components are described in the sections that follow. Entry section On entry, the sample NEP uses DFHEIENT to establish base registers and addressability to the EXEC interface. It uses an EXEC CICS LOAD PROGRAM command to establish addressability to the node error table (NET) and, if included, the common subroutine vector table (CSVT).
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 34. Format of node error table and node error block Optional common subroutines The common subroutines are addressed via the CSVT and provide error processors with the following functions: v Locate or assign NEBs and ESBs on the basis of node ID and error group index.
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 action flags in TWANPFW are manipulated to allow the failing SEND request to be retried.
DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL. The DFHSNEP TYPE=USTOREND macro has the following format: This macro indicates the end of user storage definitions. Its use is mandatory if DFHSNEP TYPE=USTOREND DFHSNEP TYPE=USTOR has been coded. If you use DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL.
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. DFHSNEP TYPE=DEFILU—including error processors for INTLUs The DFHSNEP TYPE=DEFILU macro has the following format: DFHSNEP TYPE=DEFILU TYPE=DEFILU specifies that the CICS-supplied error processor for interactive logical units is to be included in the node error program.
in the range X'01' through X'FF' (a leading zero can be omitted). The error processor name has the form NEPROCxx, where “xx” is the error group index. A CSECT statement of this name is generated, which causes the error processor code to be assembled at the end of the node error program module and to have its own addressability. If you intend to add your own error processors to the sample node error program, you should consider the following factors: v The layout of the communication area.
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. DFHSNET [NAME=DFHNET|name] [,COUNT=100|threshold] [,ESBS=1|(index,length,...)] [,NEBNAME=(name,...
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). This operand is optional, and the default is set to (7,MIN). DSECTs The following DSECTs are provided: Node Error Table Header: This contains the table name and common information relevant for all the node error blocks (NEBs) in the table.
CSVTESBL CSVTNEBD CSVTECUP DS DS DS A A A NEPESBL - ESB locate routine NEPNEBD - NEB delete routine NEPECUP - error count update routine Writing your own node error program You can write your own NEP in any of the CICS-supported languages. However, CICS-supplied NEP code is provided in assembler language only. The communication area parameter list is supplied in assembler-language and C versions.
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.
Before linking to the node error program, DFHZNAC inserts the primary and secondary printer netnames and terminal IDs into the communication area, indicating also whether either printer is eligible for a print request. DFHZNAC links to the node error program with no default actions set.
If used in this way, the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however, that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened. Refer to “Restrictions on the use of EXEC CICS commands” on page 505. Coding for specific VTAM sense codes Figure 35 shows how your NEP error processors could test for the presence of specific VTAM sense codes.
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.
Handling shutdown hung terminals in the node error program Error Code: X'6F' Symbolic Name: TCZSDAS Message Number: DFHZC2351 For error code X'6F', DFHZNAC passes the setting of TCSACTN and the DFHZC2351 reason code to DFHZNEP, and DFHZNEP can modify the force-close action for the current terminal. How DFHZNAC passes the setting of TCSACTN to DFHZNEP For error code X'6F', DFHZNAC passes the setting of the TCSACTN system initialization parameter to DFHZNEP by setting TWAOSCN.
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'. (For details of the recovery notification parameters passed to the NEP, see the listing of communication area fields in Figure 31 on page 489.) The node error program with persistent session support Persistent session support is described in the CICS Recovery and Restart Guide.
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. By default, for an XRF takeover, this is the following CICS-supplied message in BMS map DFHXRC1 of map set DFHXMSG: CICS/ESA has recovered after a system failure. Execute recovery procedures. For a persistent sessions recovery, BMS map DFHXRC3 is used; this map prefixes the above message with CICS/ESA message number DFHZC0199.
the others have all been shut down), the ISSUE PASS command does not fail with an INVREQ. Instead, the terminal is logged off and message DFHZC3490 is written to the CSNE log. You may want to code your node error program to deal with the situation when message DFHZC3490 (DFHZNAC error code X'C3') is issued. Chapter 9.
514 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 435 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).
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. v If you are using model terminal support (MTS), define the MTS tables to VTAM. v Use the default autoinstall control program for terminals (DFHZATDX), or write your own program, using the source-code of the default program and the customization examples in this information as a basis.
Coding entries for MTS You need to define model names (MDLTAB, MDLENT, and MDLPLU macros) and printer and associated printer names (ASLTAB, ASLENT, and ASLPLU macros) to VTAM. The autoinstall control program for terminals In addition to managing your resource definition, your autoinstall control program can perform any other processes that you want at this time. Its access to the command-level interface is that of a normal, nonterminal user task.
v Autoinstall processing has been completed to a point where information (a terminal identifier and autoinstall model name) from the control program is required to proceed. The communication area at INSTALL for terminals The layout of the communication area is shown in Figure 36.
The control program selects one model from this list, and CICS uses this model to build the TCTTE for the device. The default autoinstall control program, DFHZATDX, always selects the first model name in the list. If you are not using MTS but need a printer ID or NETNAME (or an alternative printer ID or NETNAME) associated with this terminal, then your control program can supply this in the area addressed by fullword 4.
model name into the model name list (Autinstmodelname_1), and also into the model name field (Modelname) in the selection list addressed by fullword 4 of the parameter list. If CICS is unable to find an MTS model name in the MTS Control Vector, or the named model does not exist or is invalid, it builds the list of autoinstall models by selecting from the complete list of terminal models those models that are compatible with the VTAM information describing the resource.
used to name a CONNECTION. It should therefore conform to the naming standards for a CONNECTION (rather than a TERMINAL) as defined in CONNECTION definition attributes, in the CICS Resource Definition Guide. The user program could identify an LU6.2 AUTOINSTALL request in one of the following ways: – Use a MODEL naming convention and examine the model name pointed to by fullword 3. – Test bytes 14 and 15 of the CINIT BIND which is pointed to by fullword 5 for X'0602' (LU6.2). v Set the return code to X'00'.
As a general rule, all the models in the list passed to your program match the VTAM data for the terminal. That is, a viable TCT entry usually results from the use of any of the models. (The exception to this rule involves the VTAM RUSIZE; if this value is incompatible, CICS issues an error message.) The default autoinstall control program merely picks the first model in the list. However, this model may not provide the attributes required in all cases.
However, you may be in a situation where you must continue to use unique and predictable TERMINAL names for your terminals. Your control program must be able to assign the right TERMINAL name to each terminal, every time the user logs on. Two possible approaches to this problem are: v Devise another algorithm to generate predictable TERMINAL names from NETNAMEs v Use a table or file to map TERMINAL names to NETNAMEs.
satisfactory, CICS schedules the new resource for OPNDST in order to complete the logon request. If the installation process fails, then the control program is driven again, as though a DELETE had occurred. (See the section “The autoinstall control program at DELETE” on page 525 for details.) This is necessary to allow the program to free any allocations (for example, terminal identifiers) made on the assumption that this INSTALL request would succeed.
The autoinstall control program at DELETE To provide symmetry of control over the autoinstall process, the autoinstall control program is also invoked when: v A session with a previously automatically-installed resource has been ended v An autoinstall request was accepted by the user program, but the subsequent INSTALL process failed for some reason. To make it easier for you to write your control program, these two events can be considered to be identical.
Table 27. Autoinstall control program’s parameter list at DELETE (continued) 1st byte Third fullword Next 15 bytes 2nd byte Length of netname to be deleted 3rd byte 4th byte First two bytes of netname Remainder of netname Note that the named resource has been deleted by the time the control program is invoked, and is not therefore found by any TC LOCATE type functions.
If CICS attempts to BIND, compare the device’s CINIT RU to the CICS BIND, and make corrections accordingly. It is very important that you ensure that the VTAM LOGMODE table entries for your terminals are correct, rather than defining new autoinstall models to fit incorrectly coded entries. Bear in mind, while you are testing, that CICS autoinstall does not work if a LOGMODE entry is incorrectly coded. Note that you cannot force device attributes by specifying them in the TYPETERM definition.
The default action of the sample program, on INSTALL, is to select the first model in the list, and derive the terminal identifier from the last four nonblank characters of the NETNAME, set the status byte, and return to CICS. If there are no models in the list, it returns with no action. The default action, on DELETE, is to address the passed parameter list, and return to CICS with no action. You can customize the sample program to carry out any processing that suits your installation.
* * * * * * * * * * * * * * * * * REGISTER CONVENTIONS = R0 used by DFHEICAL expansion R1 -------"-------"------"---R2 Base for Input parameters R3 Base for code addressability R4 Base for model name list R5 Base for output parameter list R6 Work register R7 -----"------R8 -----"------R9 free R10 Internal subroutine linkage return R11 Base for EIB R12 free R13 Base for dynamic storage R14 used by DFHEICAL expansion R15 -------"-------"------"---- * * * * * * * * * * * * * * * * * * * SELECT MODEL * LH R6
* 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 * * * * * VALIDM * VALIDM1 RETURN At this point th
. * * * * * * * * * * * * 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 01 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. . .
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); /* Screen alternate width in BIN
/* 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.
534 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 435 apply to this chapter. This chapter describes how to write a program to control the automatic installation of MVS console devices (including TSO consoles).
Note: 1. You can have only one active autoinstall control program to handle terminals, consoles, and APPC connections. You specify the name of the active program on the AIEXIT system initialization parameter. 2. Your autoinstall program must be able to recognise the console INSTALL and DELETE parameter lists and return a model name, termid and return code. v Enable the CICS AUTOINSTALL function for consoles.
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 44. Autoinstall control program’s communication area at INSTALL for consoles The parameter list contains the following information: 1. A standard header.
'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 45.
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.
CICS action on return from the control program When CICS receives control back from the autoinstall control program, it examines the return code field: v If the return code is zero, and the other required information supplied is satisfactory, CICS schedules the transaction specified on the MODIFY command to complete the request. If the installation process fails, the autoinstall control program is driven again, as though a DELETE function is being processed.
The sample autoinstall control programs for consoles 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 autoinstall control programs for terminals” on page 527. Chapter 11.
542 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 435 apply to this chapter. This chapter describes how to write a program to control the automatic installation of local APPC connections.
Like autoinstall for other resources, autoinstall for APPC connections requires model definitions. However, unlike the model definitions used to autoinstall terminals, those used to autoinstall APPC links do not need to be defined explicitly as models. Instead, CICS can use any previously-installed connection definition as a “template” for a new definition. In order for autoinstall to work, you must have a template for each kind of connection you want to be autoinstalled.
The autoinstall control program for APPC connections The purpose of the autoinstall control program is to provide CICS with any extra information it needs to complete an autoinstall request. For APPC connections, the control program selects the template to be used, and provides a name for the new connection.
*---------------------------------------------------------------------* * APPC Install parameter list - Functions 2, 3, and 4 * *---------------------------------------------------------------------* INSTALL_APPC_COMMAREA DSECT Install Parameter List * INSTALL_APPC_STANDARD DS F Standard field ORG INSTALL_APPC_STANDARD INSTALL_APPC_EXIT_FUNCTION DS XL1 Install request type INSTALL_APPC_PS_CINIT EQU X’F2’ Install PS via CINIT INSTALL_APPC_PS_BIND EQU X’F3’ Install PS via BIND INSTALL_APPC_SS_BIND EQU X’F4’ I
INSTALL_APPC_SS_BIND X'F4' represents an install request for an APPC single-session connection via a BIND. Note: The values X'F0' and X'F1' represent, respectively, install and delete requests for terminals (including APPC single-session devices). See Chapter 10, “Writing a program to control autoinstall of terminals,” on page 515. INSTALL_APPC_EXIT_COMPONENT A 2-byte component code, which is set to ‘ZC’.
Your control program can use the TEMPLATE_NETNAME field to specify the NETNAME of the template. For connections between generic resources, your program can accept the suggested template passed by CICS, or specify a different one—either in this field or by overwriting the suggested template with blanks and putting a value in the TEMPLATE_SYSID field. If the specified name is less than 8 bytes, it must be padded with trailing blanks.
The autoinstall control program at DELETE To provide symmetry of control over the autoinstall process, the autoinstall control program is also invoked when an autoinstalled APPC connection is deleted. Invoking the control program at DELETE enables you to reverse the processes carried out at the INSTALL event. For example, if the control program at INSTALL incremented a count of the total number of automatically installed resources, then the control program at DELETE would decrement that count.
Synclevel 1 connections installed via a BIND Synclevel 1-only APPC connections autoinstalled via a BIND request (except for limited resource connections installed on a CICS generic resource member—see next section) are implicitly deleted at the following times: v v v v When the connection is released If VTAM abends When the VTAM ACB is closed by CICS After the expiry of the AIRDELAY interval following a warm or emergency start (if the value of the AIRDELAY system initialization parameter is greater than ze
Note: This type of request cannot be received by CICS Transaction Server for z/OS, Version 3 Release 2. INSTALL_APPC_PS_BIND (X'F3') An incoming BIND for an APPC parallel-session connection. Specify a template. This is done in one of two ways: v For connections between two generic resources, by accepting the suggested template (the generic resource name connection) whose NETNAME is passed in TEMPLATE_NETNAME. If there is no generic resource name connection, set TEMPLATE_SYSID to 'CBPS'.
552 Customization Guide
Chapter 13. Writing a program to control autoinstall of IPIC connections Considerations common to all user-replaceable programs Note that the comments contained in Chapter 5, “General notes about user-replaceable programs,” on page 435 apply to this information. This section describes how to write a program to control the automatic installation of IPIC connections.
You can use any installed IPCONN definition as a template but, for performance reasons, your template must be an installed definition that is not in use. The definition is locked while CICS is copying it, and, if you have a large number of IPCONNs being autoinstalled at one time you might notice the delay. Requirements for autoinstall To activate IPCONN autoinstall: 1. The receiving region must have installed at least one TCPIPSERVICE that specifies PROTOCOL(IPIC). 2.
If the default user program is not adequate for your purposes, you can write a customized version of the default program or create your own program to provide enhanced function. CICS supplies the source code of the default program in several programming languages; see “The sample autoinstall user program for IPIC connections (IPCONN)” on page 557. Recovery and restart Autoinstalled IPCONNs are cataloged by CICS, for recovery at an emergency restart only. They are not recovered at a warm restart.
isaic_networkid (Input) An 8-character field containing the network ID of the system trying to connect, as sent on the connect flow. isaic_port (Input/Output) The call back port number for the client. -1 means that no call back is allowed. The autoinstall user program can modify this for the same reason that it can modify the host name, unless it is -1, in which case it cannot be changed. The autoinstall user program is also not allowed to change this value to -1.
isaic_function (Input) The function for which the user program has been invoked: X'F1' After deletion of an IPCONN. isaic_ipconn (Input) The name of the autoinstalled IPCONN. isaic_applid (Input) The applid (of the remote system) specified on the autoinstalled IPCONN. isaic_networkid (Input) The network ID (of the remote system) specified on the autoinstalled IPCONN. isaic_tcpipservice (Input) The name of the TCPIPSERVICE on which the connect flow arrived.
Default actions of the sample program The role of the autoinstall user program in installing IPCONNs is to choose the IPCONN template to be used and to supply the name of the new connection. Optionally, the program can modify the values of the APPLID, HOST, and PORT attributes of the new connection from those supplied on the connect flow. All other attributes of the new IPCONN are taken from the template or the CICS-supplied default values and cannot be modified by the user program.
Chapter 14. 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 435 apply to this chapter. This chapter describes how to write a program to control the installation of shipped terminals and connections.
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.
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. If your application programs record TERMIDs in this way, your autoinstall program may need to use a mapping file. Example Assume that you have two terminal-owning regions, TORA and TORB, and that they use the same set of terminal identifiers, T001 through T500.
autoinstall control program at INSTALL” on page 536. 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 545. The parameter list passed at INSTALL of Client virtual terminals is described in “The communications area at INSTALL for Client virtual terminals” on page 571. This section describes only INSTALL of shipped terminals and connections.
(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. N The name by which the terminal or connection is known in the TOR is not in use in the AOR to identify a remote terminal or connection. INSTALLED_SHIPPED_NETNAME_PTR A fullword pointer to an 8-character input field containing the netname of the terminal or connection to be installed.
installed, and stored within the definition. Thus, if the definition is shipped to another region, the value of the token is shipped too. The correlation ID is used by CICS during attach processing, to check whether existing shipped definitions in an AOR are up-to-date, or whether they need to be deleted and reshipped because the terminal has been re-installed in the TOR.
DELETE_SHIPPED_TERM (X'FA') A shipped terminal DELETE_SHIPPED_RSE (X'FB') A shipped connection (remote system entry). DELETE_SHIPPED_TERMID A 4-character field containing the identifier (TERMID) of the terminal or connection in the TOR. DELETE_SHIPPED_APPLID An 8-character field containing the netname (applid) of the TOR. DELETE_SHIPPED_LTERMID A 4-character field containing the name by which the terminal or connection is known in the AOR.
566 Customization Guide
Chapter 15. Writing a program to control autoinstall of virtual terminals Virtual terminals are used by the External Presentation Interface (EPI) and terminal emulator functions of the CICS Clients products, as well as the CICS Link3270 bridge. In a bridged environment, these virtual terminals replace the real 3270 that is the principal facility of a 3270 transaction. They are known as bridge facilities.
TERMIDs generated by CICS for Client terminals consist of a 1-character prefix and a 3-character suffix. The default prefix is '\', but you can specify a different prefix using the VTPREFIX system initialization parameter. The suffix can have the values 'AAA' through '999'. That is, each character in the suffix can have the value 'A' through 'Z' or '0' through '9'. The first suffix generated by CICS has the value 'AAA'. This is followed by 'AAB', 'AAC', ... 'AAZ', 'AA0', 'AA1', and so on, up to '999'.
same AOR. However, if you are using CICS-generated TERMIDs, your server programs must not rely on TERMIDs being allocated consistently to particular Client terminals. A Client terminal can be deleted by a Client sending a CICS_EpiDelTerminal request, by an end user shutting down a Client terminal emulator or the Client itself, or if a connection failure occurs. 3 When it is reinstalled, CICS does not necessarily generate the same TERMID as it had previously.
If a name clash occurs in an AOR, the autoinstall control program is invoked in the AOR. It can resolve the conflict by allocating an alias terminal identifier to the shipped definition. How bridge facility virtual terminals are autoinstalled Bridge facility virtual terminals are defined to CICS Transaction Server for z/OS, Version 3 Release 2 as LU2 devices.
v The USERID of the first transaction in a pseudoconversation can be obtained using EXEC CICS ASSIGN USERID. v The TRANSID of the first transaction in a pseudoconversation can be obtained from EIBTRNID. The autoinstall control program can use the USERID and TRANSID values to derive new TERMID and NETNAME values and return them in the communications area. Autoinstall of a Link3270 bridge facility Bridge facility name uniqueness Some applications use the termid to allocate a unique resource.
Note: The communications area for INSTALL of virtual terminals is the same as that for INSTALL of shipped terminals and connections—that is why the field names contain the word “SHIPPED”.
SELECTED_SHIPPED_TERMID A 4-character field used to specify the name by which the virtual terminal will be known to CICS. If the name is less than 4 characters long, it must be padded with trailing blanks. For a list of the characters you can use in terminal names, see Terminal definition attributes, in the CICS Resource Definition Guide.
----------------------------------------------------------------------* Install Bridge Facility - Function 15 & 17 *---------------------------------------------------------------------* INSTALL_BRFAC_COMMAREA DSECT Install Parameter List INSTALL_BRFAC_STANDARD DS F Standard field ORG INSTALL_BRFAC_STANDARD INSTALL_BRFAC_EXIT_FUNCTION DS XL1 Install type INSTALL_LINK_BRFAC EQU X’0F’ Install Link Brfacility INSTALL_START_BRFAC EQU X’11’ Install Start Brfacility INSTALL_BRFAC_EXIT_COMPONENT DS CL2 Component I
RETURN_OK (X'00') Install the virtual terminal. This is the default value. Your user program must return this value if the resource is to be autoinstalled. REJECT (X'01') Do not install the virtual terminal. SELECTED_BRFAC_NETNAME An 8-character field used to specify the netname of the bridge facility. If the name is less than 8 characters long, it must be padded with trailing blanks. You can copy the name in INSTALL_BRFAC_NETNAME_PTR, or set a new value.
DELETE_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being deleted. The equated value for Client virtual terminals is DELETE_SHIPPED_TERM (X'FC'). Note: A value of X'F1' represents the deletion of a local terminal, or an APPC single-session device that was autoinstalled via a CINIT request—see page “The autoinstall control program at DELETE” on page 525.
INSTALL_LINK_BRFAC (X'10') The autoinstall program was called during installation of a bridge facility to be used by the Link3270 bridge. INSTALL_START_BRFAC (X'12') The autoinstall program was called during installation of a bridge facility to be used by the START bridge. DELETE_BRFAC_EXIT COMPONENT A 2-byte component code, which is set to ‘BR’ DELETE_BRFAC_TERMID A 4-character field containing the bridge facility name.
578 Customization Guide
Chapter 16. 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 435 apply to this chapter. This chapter describes the user-replaceable program that controls the automatic installation of programs, mapsets, and partitionsets.
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 purpose of a model is to provide CICS with a definition that can be used for all programs with the same properties.
Note: This assumes that the autoinstall control program chooses not to install a definition. If no definition is installed because autoinstall fails, the dynamic routing program is not invoked. Autoinstall processing of mapsets Table 30 shows the differences in mapset processing between CICS regions with program autoinstall active and inactive. Table 30.
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 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. This is an input-only field, which your user-replaceable program must not alter.
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.
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. PGAC_REMOTE_SYSID allows you to specify, in a 4-byte field, the name of the remote system where the program is to execute.
shared resources it takes into account the possibility that other programs may be executing concurrently and attempting to modify the same resources. PGAC_JVM allows you to specify, in a 1-byte field, whether the program is to be run under a JVM. The equated values are: PGAC_JVM_YES The program is a Java bytecode program and must run under the control of a JVM. PGAC_JVM_NO The program does not require a JVM for its execution.
If you customize the supplied control program, or write your own version, you should note the following: v Input:The first two fields of the parameter list are input-only fields and should not be altered by your program. v Output:The remaining fields on the parameter list are input/output or output only fields, which you can use to specify attributes that override those of the model definition. v Some of the output fields in the parameter list are not applicable to mapsets or partitionsets.
group containing the definitions in your startup grouplist. If you specify an invalid name for the control program, CICS disables the program, thus disabling the program autoinstall function. The following program resource definitions are supplied by CICS for the autoinstall control program; the default is the assembler version, DFHPGADX. If these definitions are not suitable for your use, you can create your own, using RDO or the DFHCSDUP utility.
Chapter 17. 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 435 apply to this chapter. This chapter describes the CICS default dynamic routing program and tells you how to write your own version.
3. 4. 5. 6. 7. “Routing bridge requests dynamically” on page 603 “Routing by user ID” on page 607 “Parameters passed to the dynamic routing program” on page 607 “Naming your dynamic routing program” on page 621 “Testing your dynamic routing program” on page 621 8. “Dynamic transaction routing sample programs” on page 622. Routing transactions dynamically This section refers to the dynamic routing of transactions initiated from user terminals or by eligible terminal-related EXEC CICS START commands.
v After the routed transaction has completed, if the routing program has requested to be reinvoked at termination. v If the routed transaction abends, if the routing program has requested to be reinvoked at termination. Figure 57 shows the points at which the dynamic routing program is invoked. Route selection Notification Route selection error Transaction/link request termination Transaction abend Figure 57.
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.
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. You can test the DYRDTRXN field to check if the transaction passed to your routing program is defined by the DTRTRAN definition. Figure 58 contains skeleton code for routing transactions defined by DTRTRAN.
If the system is unavailable or unknown The dynamic routing program is invoked again if the remote system name that you specify on the route selection call is not known or is unavailable. When this happens, you have a choice of actions: v You can tell CICS not to continue trying to route the transaction, by issuing a return code of ‘8’ in DYRRETC. If the reason for the error is that the system is unavailable, CICS issues message ‘DFHAC2014’ or ‘DFHAC2029’ to the terminal user.
Modifying the initial terminal data The dynamic routing program should not perform an EXEC CICS RECEIVE or an EXEC CICS GDS RECEIVE command, because this prevents the routed-to transaction from obtaining the initial terminal data. The CICS relay program, DFHAPRT, places a copy of the user’s initial terminal input into a separate buffer. This information includes SNA presentation services headers for APPC mapped and unmapped conversations.
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. See also “Modifying the application’s containers” on page 607.
result of logic in the routed transaction. You should also consider carefully the effect of EXEC CICS SYNCPOINT and ABEND commands on APPC 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.
v Distributed Computing Environment (DCE) remote procedure calls (RPCs) v ONC/RPC calls. A program-link request received from outside CICS can be dynamically routed by: v Defining the program to CICS Transaction Server for z/OS as DYNAMIC(YES) v Coding your dynamic routing program to route the request.
Changing the target CICS region The communications area passed to the dynamic routing program initially contains the system identifier (sysid) and netname of the default CICS region to which the link request is to be routed. These are derived from the value of the REMOTESYSTEM option of the installed program definition. If REMOTESYSTEM is not specified, or there is no program definition, the sysid and netname passed are those of the local CICS region.
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. Changing the transaction ID A transaction identifier is always associated with each dynamic program-link request. CICS obtains the transaction ID using the following sequence: 1. From the TRANSID option on the LINK command 2. From the TRANSID option on the program definition 3. 'CSMI', the generic mirror transaction.
been set to ‘N’—the request is not to be queued—for this error to occur), issue a return code of ‘0’ in DYRRETC, and try to route the request again. v You can change the sysid, and issue a return code of ‘0’ in DYRRETC to try to route the request again. Note that if you change the sysid, you may also need to supply a different remote program name or transaction ID. A count of the times the routing program has been invoked for routing purposes for this request is passed in field DYRCOUNT.
For information about writing an XPCERES global user exit program, see The XPCERES global user exit. If a required resource is unavailable on the target region, but the XPCERES exit is unavailable or disabled (or is enabled but does not set the UERCRESU return code), the client program receives an error response.
v The dynamic routing program can be RMODE ANY but must be AMODE 31. Unit of work considerations The client program, the dynamic routing program, and possibly the server program constitute a single unit of work. Any recoverable resources owned by the dynamic routing program could therefore be affected by the syncpoint activity of the client program. This means that these resources may be committed or backed out inadvertently by the client program.
v If an error occurs in route selection, for example, if the target region returned by the routing program on its initial (route selection) call is unavailable. This allows the routing program to specify an alternate target. This process iterates until the routing program selects a target that is available, or sets a non-zero return code. v After the user transaction has completed, if the routing program has requested to be reinvoked at termination.
v If the SYSIDs are the same (or the returned SYSID is blank) CICS executes the link request locally. v If the two SYSIDs are not the same, CICS routes the request to the remote CICS region, using the returned transaction name. Changing the bridge request TRANSID The TRANSID of the target user transaction is passed to the dynamic routing program in DYRTRAN. You can change this by overwriting the DYRTRAN field in the communications area.
To use the XPCERES exit, both the routing region and the target region must support the “resource unavailable” condition (RESUNAVAIL). All the following support the “resource unavailable” condition: v CICS TS OS/390, Version 1.3, with APAR PQ73107 applied v CICS TS for z/OS, Version 2.2, with APAR PQ74920 applied v CICS TS for z/OS, Version 2.3 and later The exit is invoked, if enabled, on the target region before CICS processes a dynamically-routed Link3270 bridge request.
resources, because changes to those resources may be committed or backed out inadvertently as a result of logic in the routed program. v If you want to keep information about how link requests are routed, it must be done in the user routing program, perhaps by writing the information to a temporary storage queue. v The dynamic routing program can be RMODE ANY but must be AMODE 31.
Standard header Function code Component code Reserved Route selection error code Transaction termination option Queue-the-request indicator Reserved Return code Default/Selected sysid Version of the interface Type of routing request Reserved Default/Selected remote tranid Number of invocations count Address of input buffer Length of input buffer Pass priority to AOR? Reserved Dispatch priority passed to AOR Netname matching sysid Run this program if routed locally DTRTRAN indicator DTRTRAN reject? Reserved
under the DYRFUNC parameter the value X'5' is not listed because it is never passed to the dynamic routing program—it occurs only on a route initiate call to the distributed routing program. If you use the same program as both a dynamic routing program and a distributed routing program, for descriptions of the parameters and values that are significant on distributed routing calls refer to “Parameters passed to the distributed routing program” on page 645.
When your routing program is invoked because the routed transaction has abended (DYRFUNC=4), the information in the communications area, or in the DFHROUTE container, is not meaningful. Your routing program can alter the data in any application’s communications area, or DFHROUTE container, addressed by DYRACMAA.
DYRBRTK is the 8-byte bridge facility token associated with a Link3270 bridge request. This field is valid only when DYRTYPE=8. DYRCABP indicates whether or not you want CICS to continue standard abend processing. Note: This field applies only to dynamic transaction routing, not to the routing of program-link or Link3270 requests. (If a linked-to program abends on a remote region, the abend is mirrored in the local region—that is, it is passed to the program that issued the EXEC CICS LINK command.
N The transaction is not rejected. This indicator is always set to the reject condition when the dynamic routing program is invoked. To dynamically route a transaction defined by the DTRTRAN definition, you must change this to the accept condition. If you reject the transaction, message DFHAC2001—“Transaction ‘tranid’ is unrecognized”—is sent to the user’s terminal for dynamic transaction routing.
2 The selected system is in service, but no sessions are available. 3 An allocate request has been rejected, and SYSIDERR returned to the application program. This error occurs for one of the following reasons: 1. An XZIQUE global user exit program requested that the allocate be rejected, or 2. CICS rejected the allocate request automatically because the QUEUELIMIT value specified on the CONNECTION resource definition has been reached.
3 Invoked for notification of the destination of a statically-routed request. This applies in the following cases: ATI requests A transaction defined as DYNAMIC(YES) has been initiated by a terminal-related automatic transaction initiation (ATI) request—for example, by the expiry of an interval control start request—but the transaction is ineligible for dynamic routing.
Note: This mixed level of operation, in which different CICS regions in the same logical server are at different levels of CICS, is intended to be used only for rolling upgrades. It should not be used permanently, because it increases the risk of failure in some interoperability scenarios. The normal, recommended, mode of operation is that all the regions in a logical sever should be at the same level of CICS and Java.
N The dynamic routing program is not to be reinvoked. This is the default. Y The dynamic routing program is to be reinvoked. You can specify this option for transactions, link requests, or bridge requests that are routed to remote CICS regions and also for those that are executed locally. DYRPROCCMP is not used by the dynamic routing program. On invocation, it is set to nulls. DYRPROCID is not used by the dynamic routing program. On invocation, it is set to nulls.
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’. To make CICS terminate the transaction (issuing a message or abend), return a value of ‘8’.
client that the dynamic routing program has rejected the request, and a compcode that gives details of the reason the last attempt to route the request failed. You do not need to set a return code when the routing program is invoked for notification or at transaction termination. (Any code you set is ignored by CICS.
– If DYRERROR is set to ‘2’ (no session available) and you want CICS to retry routing, you must change DYRSYSID or change the value of DYRQUEUE to ‘Y’ (queue the request until a session is available). v When DYRFUNC is set to ‘2’ (termination of a routed request), DYRSYSID contains the name of the CICS region on which the completed transaction or link request executed.
2. If the original value was not obtained from the TRANSID option of an EXEC CICS LINK command. A value specified on the TRANSID option of a LINK command cannot be overridden by the routing program. DYRTYPE is the type of routing request for which the program is being invoked. For transaction routing, this field is meaningful only when DYRFUNC is set to ‘0’ (route selection) or ‘3’ (notify). The values that can be passed to the dynamic routing program are: 0 A transaction initiated from a terminal.
DYRUSERN is a 1024-byte user area. CICS initializes this user area to zeroes before invoking the dynamic routing program for a given task. This user area can be modified by the dynamic routing program; the modified area is passed to subsequent invocations of the dynamic routing program for the same request. DYRVER is the version number of the dynamic routing program interface. For CICS Transaction Server for z/OS, Version 3 Release 2, the number is “10”.
v The invocation of the dynamic routing program if the routed transaction abends (DYRFUNC=4), if you have specified DYROPTER=Y. If you want EDF to display the execution of your dynamic routing program only, either choose dual-terminal mode, or use one of the other methods described in Execution diagnostic facility (EDF), in the CICS Application Programming Guide. Dynamic transaction routing sample programs The CICS-supplied sample dynamic routing program is named DFHDYP.
Chapter 18. Writing a distributed routing program You can write your own distributed routing program or use the default program that is provided with CICS. You must be familiar with the principles of dynamic and distributed routing that are described in the CICS Intercommunication Guide, the CICS Business Transaction Services, and Java Applications in CICS .
6. 7. 8. 9. 10. “Routing by user ID” on page 644 “Dealing with an abend on the target region” on page 644 “Some processing considerations” on page 645 “Parameters passed to the distributed routing program” on page 645 “Naming your distributed routing program” on page 656 11.
3. The distributed routing program is invoked at more points than the dynamic routing program. Figure 60 on page 627 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. 4. Unlike the dynamic routing program, the distributed routing program cannot: 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).
“Daisy-chaining” is not supported. That is, once a BTS activity has been routed to a target region it cannot be re-routed from the target to a third region, even though its associated transaction is defined as DYNAMIC(YES). 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 routing region: 1. Either of the following: v For routing the activity.
Requesting/routing region Target region Route selection Transaction initiation Notification Transaction termination Route selection error Transaction abend Routing attempt complete Figure 60. When and where the distributed routing program is invoked 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.
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend. 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 distributed routing program is invoked again. When this happens, you have a choice of actions: 1.
Routing method requests for enterprise beans and CORBA stateless objects This section describes how to use a distributed routing program to dynamically route method requests for enterprise beans and CORBA stateless objects. It assumes that you have read the introduction to the distributed routing of such requests in Logical servers-enterprise beans in a sysplex, in the Java Applications in CICS manual.
1. Client connections can be balanced across the listener regions, using any of the following methods: v Connection optimization by means of dynamic Domain Name System (DNS) registration. v IP routing. v A combination of connection optimization and IP routing. 2. OTS transactions can be balanced across the AORs, using either of the following: v CICSPlex System Manager v A customized version of the CICS distributed routing program, DFHDSRP.
on the local EJB/CORBA server, that issues a request for another bean.
– Whether or not the target object implements CosTransactions::TransactionalObject. v Whether or not the client has an OTS transaction when it issues the method request; and, if so, whether it has issued a previous method request to the same target object within the scope of the same OTS transaction. The routing program is not invoked for route selection when the requested method of the target object is to run under an existing OTS transaction.
This invocation signals that (unless the routing region and the target region are one and the same) the routing region’s responsibility for this request has been discharged. On the target region: These invocations occur only if the target region is CICS TS for z/OS, Version 2.1 or later and the routing program on the routing region has specified that it should be reinvoked on the target region: 1. When the routed method starts on the target region.
When it is invoked for route selection, the distributed routing program can change the target region by changing the value in DYRSYSID. If the specified sysid is invalid, or cannot be found, SYSIDERR is returned to the distributed routing program—which may deal with the error by returning a different sysid—see “If an error occurs in route selection.
If the routing program sets DYROPTER to 'Y', it is re-invoked on the target region: 1. When the routed method starts on the target region. That is, when the CICS transaction specified on the REQUESTMODEL definition starts. 2. v If the routed method is part of an OTS transaction, if the OTS transaction ends successfully. v If the method executes outside an OTS transaction, if the method itself ends successfully. That is, if the CICS transaction specified on the REQUESTMODEL definition ends successfully. 3.
In general, you should follow the guidelines in Updating enterprise beans in a production region, in the Java Applications in CICS manual about how to organize beans, CorbaServers, and transaction IDs to facilitate maintenance. One way of dealing with a disabled CorbaServer is as follows: 1. If your AORs contain multiple CorbaServers, ensure that you assign different sets of transaction IDs to the objects supported by each CorbaServer. 2.
Performing a rolling upgrade of an EJB/CORBA server The DYRLEVEL field of the communications area is a migration aid, intended to help you perform a “rolling upgrade” of a multi-region logical server, whereby one region at a time is upgraded from one release of CICS to the next, without bringing down the server. Requests that require a specific level of CICS can be routed to an appropriate AOR. For details, see DYRLEVEL. Important Note: 1.
distributed routing program is invoked for notification only—it cannot route the request. Unless the SYSID option of the START command specifies a remote region explicitly, the START request is function-shipped to the target region named in the REMOTESYSTEM option; if REMOTESYSTEM is not specified, the START executes locally. “Daisy-chaining” is not supported.
Figure 63 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. Note that the “target region” is not necessarily remote—it could be the local (routing) region, if the routing program chooses to execute the START request locally. Requesting/routing region Target region Route selection Transaction initiation Notification Transaction termination Route selection error Transaction abend Routing attempt complete Figure 63.
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend. 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.
Invoking the distributed routing program on the target region The route selection, notification, route selection error, and routing complete invocations of the distributed routing program all occur on the routing region. If the routing program wants to be re-invoked on the target region, it must set the DYROPTER field in the communications area to 'Y'. It must do this on its initial (route selection or notification) invocation—and again, if it is reinvoked for a route selection error.
region, even though the transaction is defined as ROUTABLE(YES) and DYNAMIC(YES). The transaction may, however, be statically routed from the target region to a third region. When the distributed routing program is invoked For inbound Web service requests that are eligible for enhanced routing, CICS invokes the distributed routing program at the following points: On the routing region: 1. Either of the following: v For routing the request. v For notification of a statically-routed request.
Requesting/routing region Target region Route selection Transaction initiation Notification Transaction termination Route selection error Transaction abend Routing attempt complete Figure 64. When and where the distributed routing program is invoked Changing the target CICS region The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the request is to be routed.
If an error occurs in route selection If an error occurs in route selection—for example, if the sysid returned by the distributed routing program is unavailable or unknown—the routing program is invoked again. When this happens, you have a choice of actions: 1. 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. If this region too is unavailable, the routing program is again invoked for a route selection error.
The recommended way of dealing with an abend on the target region is as follows: 1. Code your routing program so that, on each route selection (and route selection error) call, it specifies that it is to be reinvoked (for transaction initiation, termination, and abend) on the target region—see “Invoking the distributed routing program on the target region” on page 634. 2.
DYRFUNC DYRCOMP DYRFILL1 DYRERROR DYROPTER DYRQUEUE DYRFILL2 DYRRETC DYRSYSID DYRVER DYRTYPE DYRFILL3 DYRTRAN DYRCOUNT DYRBPNTR DYRBLGTH DYRRTPRI DYRFILL4 DYRPRTY DYRNETNM DYRLPROG DYRDTRXN DYRDTRRJ DYRFILL5 DYRSRCTK DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS DS CL1 CL2 CL1 CL1 CL1 CL1 CL1 F CL4 H CL1 CL1 CL8 F F F CL1 CL1 H CL8 CL8 CL1 CL1 CL2 XL4 Function code Component code Reserved Route selection error code Transaction termination option Queue-the-request indicator Reser
under the DYRTYPE parameter the value X'4' is not listed because it is never passed to the distributed routing programit occurs only on a program-link-related call to the dynamic routing program. If you use the same program as both a distributed routing program and a dynamic routing program, for descriptions of the parameters and values that are significant on dynamic routing calls refer to “Parameters passed to the dynamic routing program” on page 607.
DYRACTID is the CICS-assigned, 52-character activity identifier of the BTS activity being routed. (When a process is being routed, DYRACTID returns the identifier of the root activity.) This field applies only to the routing of BTS processes and activities. DYRACTN is the name of the BTS activity being routed. (When a process is being routed, DYRACTN returns the name of the root activitythat is, DFHROOT.) This field applies only to the routing of BTS processes and activities.
This field is not used by the distributed routing program. On invocation, it is set to 'N'. DYRERROR has a value only when DYRFUNC is set to 1. It indicates the type of error that occurred during the last attempt at route selection. The possible values are: 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. 3 An allocate request has been rejected, and SYSIDERR returned to the application program.
resource is unavailable on the target region. This error code may be set for program-link, Link3270 bridge, and non-terminal-related START requests. DYRFUNC tells you the reason for this invocation of the distributed routing program. The possible values are: 0 Invoked for route selection. This invocation occurs on the routing region. 1 Invoked because an error occurred in route selection. This invocation occurs on the routing region.
6 Invoked because CICS has finished trying (successfully or unsuccessfully) to route the request to the target region. This invocation occurs on the routing region. It signals that (unless the routing region and the target region are one and the same) the routing regions responsibility for this transaction has been discharged. The routing program might, for example, use this invocation to release any resources that it has acquired on behalf of the transaction.
DYRNETNM is not used by the distributed routing program. On invocation, it is set to null characters. Note: To set the target region, the distributed routing program must use the DYRSYSID field. DYROPTER specifies whether the distributed routing program is to be reinvoked on the target region when the transaction associated with the routed request: 1. Is to be started on the target region 2. Terminates (successfully or unsuccessfully).
DYRPROCT is the process-type of the BTS process to which the process or activity being routed belongs. This field applies only to the routing of BTS processes and activities. DYRPRTY is not used by the distributed routing program. On invocation, it is set to zeroes. DYRQUEUE identifies whether or not the request is to be queued if no sessions are immediately available to the remote system identified by DYRSYSID. This field is not used by the distributed routing program. On invocation, it is set to 'Y'.
The distributed routing program can accept the value of DYRSYSID or change it before returning to CICS. If the sysid you return to CICS is the same as the local sysid, CICS executes the request on the local region. v When DYRFUNC is set to 1 (route selection error), DYRSYSID contains the CICS region name returned to CICS by the distributed routing program on its previous invocation. If you want CICS to retry routing, you must change DYRSYSID before returning to CICS.
Note that this is the name by which the transaction is known in the routing region. Unlike the dynamic routing program, the distributed routing program: 1. Is passed the local, not the remote, transaction name 2. Cannot specify an alternative remote transaction name, for forwarding to the target region. DYRTYPE is the type of routing request for which the program is being invoked. The values that can be passed to the distributed routing program are: 5 A BTS process or activity.
v For non-terminal-related START requests, DYRUSERID contains: – The userid specified on the USERID option of the EXEC CICS START command, or – If USERID is not specified, the userid under which the transaction that issued the START command is running. By examining this field when it is invoked for routing or because of a route-selection error (DYRFUNC=0 or 1, respectively), your routing program can route requests based on the userid associated with the request. DYRUSERN is a 1024-byte user area.
Note: A sample definition is provided for DFHDSRP, but you must install a new resource definition for a customized distributed routing program. Distributed transaction routing sample programs The CICS-supplied sample distributed routing program is named DFHDSRP. 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 CICSTS32.
658 Customization Guide
Chapter 19. 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 435 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.
DBUDISC (X'02') Disconnected. DBUREAS Reason for Disconnection. Contains flags: DBUMENU (X'01') Disconnected from menu DBUDBCC (X'02') Checkpoint Freeze input to DBCTL DBUDRAF (X'03') DRA Failure has taken place DBUDBCF (X'04') DBCTL Failure has taken place. DBUSUFF DRA startup table suffix. DBUDBCTL DBCTL identifier. The sample CICS–DBCTL interface status program The source-code of the supplied CICS–DBCTL interface status program, DFHDBUEX, is provided, in assembler language only, in the CICSTS32.CICS.
Chapter 20. 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 435 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.
662 Customization Guide
Chapter 21. 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 435 apply to this chapter. Incoming requests using the Internet Inter-ORB Protocol (IIOP) are processed by CICS under a default user ID, unless you provide an IIOP security exit program to assign a new user ID.
* 1–character reserved field pIIOPData contains the address of the first megabyte of the unconverted IIOP buffer. If the incoming request is fragmented, this field contains a pointer to: v the first megabyte of the first fragment, if the first fragment is greater than 32K v a 32K buffer containing data from the first fragments that fit in the buffer, if the first fragment is less than or equal to 32K. lIIOPData contains the length of the unconverted IIOP buffer.
sslClientUserid 1–byte field showing the derivation of the user ID if SSLTYPE CLIENTAUTH is specified in the TCPIPSERVICE definition, where: * 0 user ID set from DFLTUSER 1 user ID set from SSL CERTIFICATE 2–byte reserved field return_code contains the return code. reason_code contains the reason code. A user ID can be returned, but other fields are provided for information only.
If you write your own security exit program, it should return all fields other than userid and return_code unchanged, or unpredictable results will occur. DFHEBURM DFHEBURM is for use with the EJB Bank Account sample program. It alters the user ID under which the sample runs from the default CICS user ID to “SAMPLE”. For more information about DFHEBURM, see The EJB Bank Account sample application, in the Java Applications in CICS.
Chapter 22. Writing programs to customize JVMs This chapter describes how to write programs to customize a Java Virtual Machine (JVM). The normal way to customize JVMs is by specifying options in the JVM profile, and system properties in the JVM properties file. There are three additional ways to customize JVMs: v You can create Java classes that intercept the stdout and stderr output from a JVM, add time stamps and record headers, and redirect the output to the destination of your choice.
For a JVM to use an output redirection class that you have modified or written, the class must be present in a directory on an appropriate class path in the JVM profile or properties file. The directory containing the jar file for the sample output redirection class is automatically included on an appropriate class path, and you do not need to specify it explicitly in the JVM profile.
by one provided in a subclass. It does not implement a writeRecord method, and such a method must be provided by any subclass to control the output redirection process.You could imitate this in your own class structure. The initialization of output redirection can also be performed using a constructor, rather than the initRedirect method. Note: The inPS parameter contains either the JVM's original System.out PrintStream or the JVM's original System.err PrintStream.
the sample classes trap all errors in this way, this means that the calling programs do not need to handle any exceptions thrown by the output redirection class. You can use this method to avoid making changes to your calling programs. Be careful that you do not send the output redirection class into a loop by attempting to redirect the error message issued by the class to the destination which has failed.
CICS checks the length of the runtime options before passing them to Language Environment. If the length is greater than 255 bytes, CICS does not attempt to start the JVM. Error messages are written to CSMT in this case. Note that the values you specify are not checked by CICS before being passed to Language Environment. If you decide to modify DFHJVMRO, note the following: v Keep the size of the list of options to a minimum for quick processing, and because CICS adds some options to this list.
You cannot call DFHJVMAT for a continuous JVM, that is, with a JVM profile that specifies REUSE=YES (for example, the default CICS-supplied JVM profile, DFHJVMPR). If you specify INVOKE_DFHJVMAT=YES for this type of JVM, then INVOKE_DFHJVMAT=YES is ignored and DFHJVMAT is not called. The values specified in the JVM profile are available to DFHJVMAT as z/OS UNIX System Services environment variables, which you can modify before the JVM is created.
1. Except where explicitly stated as being for information only, you can reset the values of these variables. 2. All environment variables and values are case sensitive, and should be set as shown. 3. CICS ignores any values that it does not recognize as a valid option. 4. For the options beginning with X: v Some of these options are no longer documented in the CICS documentation. However, they are still valid options and available to DFHJVMAT.
Table 34.
Chapter 23. Writing a distinguished name program for clients of enterprise beans Considerations common to all user-replaceable programs Note that the comments contained in Chapter 5, “General notes about user-replaceable programs,” on page 435 apply to this chapter. Use the distinguished name user-replaceable program, DFHEJDNX, to supply the distinguished name of a client of an enterprise bean, when the client has not presented an X.509 certificate containing a name.
ejdn_common_name_ptr A pointer to the proposed common name of the client, derived from the username associated with the client’s userid in the external security manager’s database. ejdn_common_name_len A binary fullword containing the length of the client’s common name. ejdn_title_ptr A pointer to the proposed title of the client, derived from the title in the X.509 certificate associated with the CorbaServer. ejdn_title_len A binary fullword containing the length of the client’s title.
Sample programs and copy books The default distinguished name program is an assembler-language program named DFHEJDNX. The source of the default program is provided in assembler-language and C. The corresponding copy book that defines the communications area is provided in assembler-language, C, COBOL, and PL/I. The names of the supplied source programs and copy books, and the CICSTS32.CICS libraries in which they can be found, are summarized in Table 35. Table 35.
678 Customization Guide
Chapter 24. Writing an EJB event program You can write your own EJB event program or use the program provided with CICS, DFHEJEP. You must be familiar with the methods of defining CORBASERVER and DJAR resources and know how to deploy enterprise beans, as described in Java Applications in CICS.
The DFHEJEP communications area The DFHEJEP communications area is mapped by the EJEV_COMMAREA DSECT, which is supplied in the DFHEJEPH copybook. The information passed in the communications area is as follows: EJEV_BEANNAME The 240-byte name of the bean involved in this event. For some events (for example, the discard of a DJAR) there is no bean name, in which case this field is blank. EJEV_CORBASERVER The 4-byte name of the CorbaServer for which this event is relevant.
Event codes Table 36 shows the codes and meanings of all EJB events that may be passed to the EJB event program. Table 36. EJB event codes. The table shows the event type and meaning of each event code. The “Bean name” column indicates whether the EJEV_BEANNAME field in the DFHEJEP communications area contains the name of an enterprise bean. The “DJAR name” column indicates whether the EJEV_DJAR field in the DFHEJEP communications area contains the name of a DJAR resource.
Table 36. EJB event codes (continued). The table shows the event type and meaning of each event code. The “Bean name” column indicates whether the EJEV_BEANNAME field in the DFHEJEP communications area contains the name of an enterprise bean. The “DJAR name” column indicates whether the EJEV_DJAR field in the DFHEJEP communications area contains the name of a DJAR resource. Event code Event type Bean name? DJAR name? Description 020 I N N A scan of a CorbaServer’s “pickup” directory has ended.
Table 37. EJB event programs and copy books (continued) Language Copy books: v Assembler v C v COBOL v PL/I Member name v v v v DFHEJEPD DFHEJEPH DFHEJEPO DFHEJEPL Library v v v v SDFHMAC SDFHC370 SDFHCOB SDFHPL1 You can use the supplied program as the basis of your own EJB event program. Your program could, for example, use different criteria than the default program to filter the EJB events passed to it; or send the filtered events to a different destination.
684 Customization Guide
Chapter 25. Writing programs to customize Language Environment run-time options for XPLink programs Considerations common to all user-replaceable programs Note that the comments contained in Chapter 5, “General notes about user-replaceable programs,” on page 435 apply to this chapter. This chapter describes how to write a user-replaceable program that will be called by CICS during the initialization of the Language Environment enclave for a C or C++ program compiled with the XPLINK option.
686 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 26. 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. The XRF overseer program has two major functions: v To display the current status of active and alternate CICS regions v To restart failed CICS regions in place without operator intervention.
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 Display and Restart commands control the two major functions of the sample overseer program, which are described below.
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. An example of the status display is shown, for guidance purposes, in the CICS Operations and Utilities Guide. Note: An ‘X’ following any of these status values indicates that the associated job is currently executing.
active-alternate pairs are not to be automatically restarted in place, regardless of whether restart processing is enabled or disabled. This is described in “How to tell the overseer which actives and alternates to monitor” on page 693. The Restart command works like an ON/OFF switch. Restart in place is enabled when the sample program is initialized. When the Restart command is first entered, restart in place is disabled. If you issue the command again, restart is enabled again, and so on.
This problem arises only if the overseer is initialized before all the CAVM data sets have been formatted. If it occurs, the operator can use the Open command (see Open ) to retry the opening of those CAVM data sets on which the Open previously failed. The overseer retries an Open only if the previous attempt failed with the return code X'C'. (See “DFHWOSM FUNC=OPEN macro” on page 698.
The sample overseer program reads the DFHOSD records in key sequence and builds a table of entries. Each active-alternate pair is known by its generic applid on this data set. Every entry on the data set contains the following information: v A 12-byte key field, containing the 4-byte value ‘GNbb’ followed by the 8-byte generic applid of the active-alternate pair. v The ddnames of the control data set and the message data set associated with this generic applid. Each of these is an 8-byte value.
2 The last three entries are for three related MRO regions that are identified by the related system name of MROSYS. One of these is not allowed to restart in place and is indicated by the letter N. The DFHWOSM macros The DFHWOSM macros invoke the CICS module DFHWOS to provide services to the overseer program.
by the overseer program and passed back to DFHWOS as input to the OPEN, CLOSE, READ, QJJS, and TERM macros. DFHWOSM FUNC=BUILD macro The DFHWOSM FUNC=BUILD macro must be issued by the overseer program to initialize its communication with DFHWOS. No other macro can be issued by the overseer program until DFHWOS FUNC=BUILD has completed successfully.
DFHWOSM FUNC=DSECT macro The DFHWOSM FUNC=DSECT macro generates a number of DSECTs, including the DSECT of the DBLID definitions. DFHWOSM FUNC=DSECT DFHWOSM FUNC=JJC macro The DFHWOSM FUNC=JJC macro issues a JES cancel for a named job with a JES job identifier. DFHWOSM FUNC=JJC [,PARM={parm address|1}] [,TOKEN={token register|14}] Input The PARM value is a pointer to the addresses of the following: v An 8-byte job name v An 8-byte JES job ID v A 256-byte SSOB return area.
For FUNC=QJJS, the PARM value is a pointer to the addresses of the following: v An 8-byte job name v An 8-byte JES job ID v A 256-byte SSOB return area v A doubleword area to hold two ECBs. The FUNC=QJJS macro requires 2 ECBs: the first is posted when the JES call completes; the second is posted if a time-out occurs before JES returns. The TOKEN value is the BUILD token.
8 Access already initialized for this generic applid or for this ddname 9 Version numbers of the named CAVM data sets do not match C Data set open failure 10 SHOWCB failure. A register 15 return code value of ‘0’ through ‘5’ indicates that a DFHWOSM FUNC=READ macro can now be issued. A return code value of ‘6’ or above indicates that the OPEN has failed and that the overseer program will not be able to access the CAVM data sets.
Input The PARM value is a pointer to a parameter list that contains the addresses of the generic applid and the “dbllist”. The dbllist is a list of one or more doublewords. In the first two bytes of the second word of each of these doublewords you supply the DBLID of the information you require. Each piece of information that you can request is identified by a DBLID, and a list of these is provided in Figure 69 on page 701.
DBLIDs for the active: DBLID1 DBLID2 DBLID3 DBLID4 DBLID5 DBLID6 DBLID7 DBLID8 DBLID9 DBLID10 DBLID11 DBLID12 DBLID32 DBLID33 DBLID34 DBLID35 DBLID36 DBLID37 DBLID38 DBLID39 DBLID40 EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU EQU X’0001’ X’0002’ X’0003’ X’0004’ X’0005’ X’0006’ X’0007’ X’0008’ X’0009’ X’000A’ X’000B’ X’000C’ – X’001F’ X’0020’ X’0021’ X’0022’ X’0023’ X’0024’ X’0025’ X’0026’ X’0027’ X’0028’ JOB NAME JES JOB ID JOB SUBMISSION TIME (STIME) JOB STEP TASK ATT
0 Read successful, active and alternate signed on 1 Read successful, active signed on 2 Read successful, alternate signed on. 3 Read successful, nothing signed on 4 Same SMF MVS name; IPL time of active earlier than MVS IPL time 5 Same SMF MVS name; IPL time of alternate earlier than MVS IPL time 8 CAVM data set access not initialized 10C DBLID not known 1xx Read subtask problem.
DFHDXGHD GHDDXADB GHDDXRSE GHDDXCTM GHDDXDTM GHDDXJNM GHDDXJID GHDDXASD GHDDXIRT DXRHTSBY DXRDBDC DXRDBCTL GHDDXTYP DXMCNNCT DXMDISC DXMDRAF DXMABEND DXMERROR DXGHDLEN DSECT DS DS DS DS DS DS DS DS EQU EQU EQU DS EQU EQU EQU EQU EQU EQU ORG CL4 CL8 CL4 CL4 CL8 CL8 H X X’01’ X’02’ X’04’ X X’01’ X’02’ X’04’ X’08’ X’80’ *-DFHDXGHD , DBCTL SSID IMS RSE name IMS connect time IMS disconnect time JES Job name of old active IMS JES Job ID of old active IMS ASID of old active IMS IMS region type region type is ho
The associated DSECTs are provided in member DFH$XRDS of CICSTS32.CICS.SDFHSAMP. There are several ways in which you can change the supplied code to make the overseer program more suitable for your installation. Here are some customization suggestions: v If the supplied display of status information (DSECT DSPDS) is not suitable, you can change the layout for your installation. You may also want to change the content of the status display if you are using DBCTL.
user exit program to request a CICS abend, and thereby initiate a takeover, and for the overseer program to issue the PERFORM TAKEOVER command while acting on the same information. – At particular times of the day, perhaps when fewer operational staff are available than at other times, you may find it convenient to change the TAKEOVER setting for some, or all, of your regions.
link-edit job step requires the entry name DFHXRONA. If you change any of the DSECTs used by the sample overseer program, you should reassemble the four modules.
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 27. CICS logging and journaling This chapter is divided into the following sections: 1. “The CICS log manager” 2. “Log stream storage” 3. “Enabling, disabling, and reading journals” on page 711 4. “Structure and content of COMPAT41-format journal records” on page 729 5. “Format of journal records written to SMF” on page 737. The CICS log manager The CICS log manager provides facilities for the creation, control, and retrieval of journals during real-time CICS execution.
data sets managed by the storage management subsystem (SMS). Each log stream, identified by its log stream name (LSN), is written to its own log data sets. 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 71 and Figure 72 on page 711 show the types of storage used by the MVS system logger.
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 72. 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.
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.
System logs are always presented in CICS Transaction Server for z/OS 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. Each CICS journal record comprises a record header followed by caller data. Figure 73 gives a graphical overview of a general log, showing the format of a complete block, and the format of a complete journal record.
Fixed length 8 >DFHtrnn LGBH_GLOBAL_INFO 8 8 Start time (GMT) LGBH_START_GMT 8 Start time (Local) LGBH_START_LOCAL 8 Seq no. LGBH_BLOCK_NUMBER CICS applid LGBH_GENERIC_APPLID Where t = Log type r = reserved nn = block version number Figure 74. Format of a general log block header LGBH_GLOBAL_INFO 8-bytes containing '>DFHtrnn', where: t = log type r = reserved nn = block version number LGBH_GENERIC_APPLID 8-byte CICS applid. LGBH_START_GMT 8-byte start time (GMT).
Fixed length 4 4 4 Time (GMT) GLRH_GMT 8 8 Time (Local) GLRH_LOCAL Record data length GLRH_REC_ DATA_LEN 4 4 4 2 2 8 1 3 Journal name GLRH_REC_ JOURNAL Tran ID GLRH_TRAN_ID Task ID GLRH_TASK_ID Reserved Domain ID GLRH_REC_ COMPID Term ID GLRH_TERM_ID Header length GLRH_HEADER_LENGTH Record type GLRH_REC_TYPE X'0001' Start of run record X'0002' Any other record Record length GLRH_RECORD_LENGTH X'8n' equivalent to JCSPSOTK (start of task) X'4n' equivalent to JCSPLSTK (start of uow) Fig
Start of task indicator 1-byte which may contain: X’8n’ X’4n’ Equivalent to JCSPSOTK (start of task) Equivalent to JCSPLSTK (start of UOW) Reserved 3-byte reserved field. The caller data differs depending on the CICS component issuing the record, and on the function being journaled. 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.
Journal records can be written by any of the following CICS components: the logger, journal control (in the case of a request issued by a user), file control, the front end programming interface (FEPI), and terminal control. The field GLRH_REC_COMPID in the record header tells you which component has written the record: LG, UJ, FC, SZ, or TC respectively. File control adds information to the start of the actual journaled data, and this is described in “Caller data written by file control.
Some records have a third and fourth section which are of variable length. Table 38 outlines the sections in a journal record written by file control. Table 38.
FLJB_GENERAL_DATA 12-byte general data. FLJB_COMMON_DATA 16-byte common data. FLJB_CD_KEY Variable-length caller data key. FLJB_CD_DATA Variable-length caller data. The format of the FLJB_GENERAL_DATA section is shown in Figure 79.
FLJB_FILE_NAME 8-byte file name. Reserved 2-byte reserved field. The format of the FLJB_COMMON_DATA section is shown in Figure 80.
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).
Fixed length 4 2 2 1 3 Reserved Relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS or is extended ESDS) Flag byte FLJB_WDD_BITS X'80' UOW has been shunted at least once X'40' fixed length record FLJB_WDD_BASE_ESDS_RBA Base key length FLJB_WDD_BASE_KEY_LENGTH Path key length (0 if file does not refer to a path) FLJB_WDD_PATH_KEY_LENGTH Figure 82.
Fixed length 28 12 FLJB_GENERAL_DATA FILE_CLOSE_DATA Figure 83. Layout of record written for file-close record types FLJB_GENERAL_DATA 12-byte general data section. FLJB_CLOSE_DATA 28-byte close data section. See Figure 79 on page 719 for the format of the FLJB_GENERAL_DATA section. The format of the FLJB_CLOSE_DATA section is shown in Figure 84.
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. The format of such a record written for tie-up record types is shown in Figure 85. Fixed length 12 FLJB_GENERAL_DATA 136 TIE_UP_RECORD_DATA Figure 85. Layout of record written for tie-up record types FLJB_GENERAL_DATA 12-byte general data. TIE_UP_RECORD_DATA 136-byte tie-up record data.
Fixed length 4 4 4 2 11 CI size of base data set FLJB_TUR_BASE_CI_SIZE Record format FLJB_TUR_RECORD_FORMAT x 'E5' = Variable x 'C6' = Fixed Maximum record length FLJB_TUR_MAXIMUM_LRECL Data set type FLJB_TUR_DATASET_TYPE X'C5'=ESDS X'D2'=KSDS X'D7'=Path X'D9'=RRDS X'E5'=VRRDS X'E7'=XESDS Base key position in record FLJB_TUR_BASE_KEY_POS Base key length FLJB_TUR_BASE_KEY_LENGTH Fixed length 2 44 Base data set name FLJB_TUR_BASE_DSNAME Base data set name length FLJB_TUR_BASE_DSNAME_LENGTH Fixed
FLJB_TUR_MAXIMUM_LRECL 4-byte maximum record length. FLJB_TUR_BASE_KEY_POSITION 4-byte base key position in record. FLJB_TUR_BASE_KEY_LENGTH 2-byte base key length. FLJB_TUR_DATASET_TYPE 1-byte data set type: X’C5’ X’D2’ X’D7’ X’D9’ X’E5’ X’E7’ Standard ESDS KSDS Path RRDS VRRDS Extended ESDS FLJB_TUR_RECORD_FORMAT 1-byte record format: X’E5’ X’C6’ Variable Fixed FLJB_TUR_BASE_DSNAME_LENGTH 2-byte length of base data set name. FLJB_TUR_BASE_DSNAME 44-byte base data set name.
Fixed length 11 2 2 4 Function identifier JCAUPTID Terminal identifier (padded with blanks if unused) Module identifier InboundVTAM sequence number OutboundVTAM sequence number Figure 87. Format of the terminal control prefix area Function ID 1-byte function identifier. Module ID 1-byte module identifier. Inbound VTAM SN 2-byte inbound VTAM sequence number. Outbound VTAM SN 2-byte outbound VTAM sequence number. JCAUP TID 4-byte terminal identifier (padded with blanks if unused).
Fixed length 1111 2 8 8 8 4 Pool name UP_ FEPPL Reserved Escape character Target name UP_ FEPTG for keystroke UP_ FEPES Conversation identifier Data function UP_ FEPCV UP_ FEPDF Reserved Module identifier UP_ SVMID Module function UP_ MODFN Figure 88.
Structure and content of COMPAT41-format journal records SMF records The following description does not apply to journal records written to an SMF data set. These are described on page “Format of journal records written to SMF” on page 737. CICS allows you to format journal records so that they are presented in the format used at CICS/ESA 4.1. Use the COMPAT41 option on the SUBSYS=(LOGR...) step of your JCL. Within the data presented, certain fields are not presented at CICS Transaction Server for z/OS.
Fixed length 4 10 32 Label header Label prefix Length of block Not presented unless the caller is reading data blocks rather than records Figure 90. Format of journal control label header The label header part of the journal control label header is 10 bytes long, and its format is shown in Figure 91. Fixed length 2 2 Length of record JCRLL 2 2 2 Record number within block JCRLRN X‘0000' System-type ID JCRSTRID ‘0000' if user journal request.
JCRSTRID 2-byte system-type identifier. For a user journal request, this is X'0000'. Otherwise, it consists of a 1-byte function ID followed by a 1-byte module ID. JCRUTRID 2-byte user-type identifier. For a CICS journal request, this is X'0000'. Otherwise, it contains the code specified by the JTYPEID keyword of the user request. JCRLRN 2-byte record number within the block. The label prefix part of the journal control label header is 32 bytes long, and its format is shown in Figure 92.
Fixed length Variable length 10 System header System prefix User prefix Journal data Figure 93. Format of COMPAT41 journal record The system header is 10 bytes long. Its format is shown in Figure 94. Fixed length 2 2 2 Length of record JCRLL 2 2 Record number within block JCRLRN X'0000' System-type ID JCRSTRID '0000' if user journal request. Otherwise 1-byte function ID followed by 1-byte module ID User-type ID JCRUTRID '0000' if CICS journal request.
JCRUTRID 2-byte user-type identifier. For a CICS journal request, this is X'0000'. Otherwise, it contains the code specified by the JTYPEID keyword of the user request. JCRLRN 2-byte record number within the block. 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.
Reserved 2-byte reserved field. JCSPF1 1-byte flag field: X’01’ X’02’ X’04’ JCSPTASK 3-byte JCSPTIME 4-byte JCSPTRAN 4-byte JCSPTERM 4-byte User prefix present Physical start-of-task, JCSPSOTK Logical start-of-task, JCSPLSTK task number. time of request. transaction identifier. terminal identifier. For some CICS journal requests, additional data is included in the system prefix to identify more specifically the originator of the request.
JCRLL - (system header (10) bytes + JCSPLL + user prefix) Not all journal records contain journaled data. The CICS components that issue journaling requests are journal control, file control, FEPI, and terminal control. Chapter 27.
*********************************************************************** * * 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’ ...
*********************************************************************** * * M O D U L E I D E N T I F I E R S * * *********************************************************************** * * MODIDTC EQU X’10’ ...TERMINAL CONTROL MODIDFC EQU X’11’ ...FILE CONTROL MODIDJC EQU X’45’ ...JOURNAL CONTROL MODIDFEP EQU X’50’ ...FEPI * * *********************************************************************** Figure 98. Journal module identifiers Note: 1.
Log block SMF Block header Record header Log block CICS Product section Log block Log block CICS Data section LG Caller data Figure 99. Layout of a CICS log written to MVS SMF Journal records written to SMF can be read offline by user-written programs. Such programs can map journal records by including an INCLUDE DFHLGMSD statement. This generates the assembler version of the DSECT. The SMF block header This block describes the system creating the output.
Fixed length 2 2 1 1 4 4 4 4 Time record moved SMFH_TME (local) Record type SMFH_RTY Operating system indicator SMFH_FLG Segment descriptor X'0000' SMFH_SEG Record length SMFH_LEN 2 2 2 4 No.
SMFH_NPS 2-byte SMFH_ASS 4-byte SMFH_ASL 2-byte SMFH_ASN 2-byte number of CICS product section. offset to CICS data section. length of CICS data section. number of CICS data sections. Note: CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFH_LG). SMF sets the remainder of the byte according to the operating system level and other factors.
Fixed length 2 8 2 8 Product name (generic APPLID) SMFPS_PRN 54 Record maintenance indicator SMFPS_MFL X'0vrm' SMFPS_VRM Reserved Product name (specific APPLID) SMFPS_SPN v = version r = release m = modification set by DFHSYS Fixed length 8 Journal name SMFPS_JNM 8 Job name SMFPS_JBN 4 4 8 Job time SMFPS_RST (local) 8 User ID SMFPS_UIF Op.system product level SMFPS_PDN Job date SMFPS_RSD Figure 101.
SMFPS_JNM 8-byte SMFPS_JBN 8-byte SMFPS_RSD 4-byte SMFPS_RST 4-byte SMFPS_UIF 8-byte SMFPS_PDN 8-byte journal name. job name. job date. job time (local). user ID. operating system product-level. The CICS data section This section contains a variable number of CICS journal records. Each record comprises a general log record header, the format of which is shown in Figure 75 on page 715. This is followed by a user header, the format of which is shown in Figure 77 on page 717.
Chapter 28. CICS monitoring This section describes the monitoring facilities of CICS Transaction Server for z/OS, Version 3 Release 2, 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 section covers: 1. “Introduction to CICS monitoring” describes the classes of monitoring data, event-monitoring points, and the use of the monitoring control table. 2.
or when there is an immediate shutdown of CICS, the transaction resource records are not written to SMF and the data is lost. Exception records are passed directly to SMF when the exception condition completes. Each exception record describes one exception condition. You can link performance records with their associated exception records by matching the value of the TRANNUM field in each type of record; each contains the same transaction number.
invoked, displays a menu screen from which the user can choose a specific application. It is then possible to run all the elements of the application under the common menu transaction ID. This is very effective from the application users point of view, because they do not have to use a large number transaction IDs to run an application.
DFHEISTG DSECT EMPDATA1 DS F Data area for DATA1 address * * * Constants for DATA2 (null value) and ENTRYNAME * EMPDATA2 DC F’0’ APPLNAME DC CL8’DFHAPPL’ * LA Rn,tranid Set addr of tranid ST Rn,EMPDATA1 Store tranid for EMP EXEC CICS MONITOR POINT(1) ENTRYNAME(APPLNAME) DATA1(EMPDATA1) DATA2(EMPDATA2) NOHANDLE C Figure 102. EXEC CICS MONITOR commands for DFHAPPL EMPs (assembler) This example shows 4 bytes of user data, typically the transaction ID, being moved using the DFHAPPL.1 EMP.
IDENTIFICATION DIVISION. PROGRAM-ID. APPLNAME. ENVIRONMENT DIVISION. DATA DIVISION. WORKING-STORAGE SECTION. 77 APPLICATION-NAME-PTR POINTER. 77 MENU-APPLICATION-NAME PIC X(4) VALUE ’MENU’. 77 PAYROLL-APPLICATION-NAME PIC X(8) VALUE ’PAYROLL ’. 77 DFHAPPL-NAME PIC X(8) VALUE ’DFHAPPL ’. 77 DFHAPPL-DATA2 PIC S9(8) COMP VALUE +0. 77 BLANKS PIC X VALUE SPACE. * LINKAGE SECTION. 77 LS-APPLICATION-NAME PIC X(8). * PROCEDURE DIVISION.
DFHMCT TYPE=EMP There must be a DFHMCT TYPE=EMP macro definition for every user-coded EMP. The PERFORM operand of the DFHMCT TYPE=EMP macro tells CICS which user count fields, user clocks, and character values to expect at the identified user EMP, and what operations to perform on them. The DFHMCT TYPE=EMP macro has an ID operand, whose value must be made up of the ENTRYNAME and POINT values specified on the EXEC CICS MONITOR command.
Example 1: Starting a user clock Example 1 shows a user clock being started by an application that is identified as PROG3. This is the eleventh EMP in this application. To prevent confusion with the eleventh EMP in another application, this EMP is uniquely identified by the empid PROG3.11. The clock that is being started is the first clock in a string, and has the identifier CLOCKA. Table 40.
The DBCTL data recorded by these event monitoring points can be mapped using the IMS macro DFSDSTA DSECT=YES, which is available in the IMS genlibs. For more information about monitoring in DBCTL, see the CICS IMS Database Control Guide. CICS monitoring record formats This section describes the formats of CICS monitoring SMF type 110 records in detail. You need this information if you write your own program to analyze the monitoring data. CICS writes several types of SMF 110 record.
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 105 on page 752. Chapter 28.
* * MNSMFDS SMFMNLEN SMFMNSEG SMFMNFLG SMFMNRTY SMFMNTME SMFMNDTE SMFMNSID SMFMNSSI SMFMNSTY SMFMNTRN START OF THE SMF HEADER DSECT DS DS DS DC DS DS DS DS DS DS DS DS DS DS DS DS DS XL2 XL2 X X’6E’ XL4 XL4 CL4 CL4 XL2 XL2 XL2 XL4 XL2 XL2 XL4 XL2 XL2 RECORD LENGTH SEGMENT DESCRIPTOR OPERATING SYSTEM INDICATOR (see note 1) RECORD 110 FOR CICS TIME RECORD MOVED TO SMF DATE RECORD MOVED TO SMF SYSTEM IDENTIFICATION SUBSYSTEM IDENTIFICATION RECORD SUBTYPE - MONITORING USES TYPE 1 NUMBER OF TRIPLETS RESERVED
factors. For an explanation of the setting of the other bits, refer to the z/OS MVS System Management Facilities (SMF) manual. 2. Fields SMFMNDCA SMFMNDCL, and SMFMNDCN apply to performance class records only. 3. For dictionary class monitoring records (described in “Dictionary data sections” on page 754), the fields SMFMNDRA, SMFMNDRL, and SMFMNDRN in the SMF product section have the following meaning: SMFMNDRA Offset to the first dictionary entry. SMFMNDRL Length of a single dictionary entry.
CICS data section The CICS data section can be made up of a dictionary data section, a performance data section, an exception data section, or a transaction resource 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. If data compression has been used, the z/OS Data Compression and Expansion Services must be used to expand the data section before processing.
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.
756 C Byte-string P Packed decimal number S Clock T Time stamp Customization Guide
FIELD-NAME SIZE DFHTASK C001 4 DFHTERM C002 4 DFHCICS C089 8 DFHTASK C004 4 DFHCICS T005 8 DFHCICS T006 8 DFHTASK P031 4 DFHTASK A109 4 DFHTASK C166 8 DFHTERM C111 8 DFHPROG C071 8 DFHTASK C097 20 DFHTASK C098 8 DFHCICS C130 4 DFHCICS A131 4 DFHTASK T132 8 DFHCICS C167 8 DFHCICS C168 8 DFHTASK C163 4 DFHTASK A164 8 DFHTERM A165 4 DFHTERM C169 4 DFHTASK C124 4 DFHTASK C190 16 DFHCBTS C200 36 DFHCBTS C201 8 DFHCBTS C202 52 DFHCBTS C203 52 DFHCBTS C204 16 DFHSOCK C244 16 DFHTASK C082 28 DFHTERM C197 8 DFHTERM
FIELD-NAME DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHSTOR DFHFILE DFHFILE DFHFILE DFHFILE DFHFILE DFHFILE DFHFILE DFHDEST DFHDEST DFHDEST DFHDEST DFHTEMP DFHTEMP DFHTEMP DFHTEMP DFHMAPP DFHMAPP DFHMAPP DFHMAPP DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHPROG DFHJOUR DFHJOUR DFHTASK DFHTASK DFHTASK DFHTASK A106 A116 A119 A095 A107 A11
FIELD-NAME DFHTASK DFHTASK DFHSYNC DFHCICS DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHFEPI DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHCBTS DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHDOCH DFHDOCH DFHDOCH DFHDOCH DFHDOCH DFHDOCH DFHDOCH DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK A346 A347 A060 A025
FIELD-NAME DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHSOCK DFHDATA DFHDATA DFHDATA DFHTASK DFHTASK DFHEJBS DFHEJBS DFHEJBS DFHEJBS DFHEJBS DFHEJBS DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHWEBB DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHCHNL DFHSOCK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK A298
FIELD-NAME DFHTASK DFHTASK DFHTASK DFHCICS DFHTERM DFHFILE DFHJOUR DFHTEMP DFHTERM DFHDEST DFHPROG DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTERM DFHTERM DFHFEPI DFHTASK DFHTASK DFHSYNC DFHFILE DFHFILE DFHTASK DFHTASK DFHTASK DFHTASK DFHTASK DFHTEMP DFHFILE DFHSYNC DFHTASK DFHTASK DFHSYNC DFHSOCK DFHDATA DFHDATA DFHDATA DFHDATA DFHDATA DFHTASK DFHTASK DFHSOCK DFHTASK DFHTASK DFHSYNC DFHTASK DFHTASK DFHTASK DFHTASK DFHSOCK S281 S268 S247 S103 S009 S063 S010 S011 S100 S101 S115 S125 S126 S127 S129 S123 S133
performance records changes if you add user data at user event monitoring points (EMPs), or if you exclude any system-defined data from the monitoring process. All of the system-defined data fields in the performance records are described in Performance class data: listing of data fields , in the CICS Performance Guide. The format of the performance data section is shown in Figure 113.
Figure 114 illustrates the relationship between the dictionary record, the field connectors, and the performance records.
record type, and they do not change between CICS runs. There is more information about field identifiers in the CICS Resource Definition Guide. Field offsets in the performance record allow you to build a table for fast selection of required fields in your monitoring data processing programs. Exception data sections The exception data section contains a single exception record representing one exception condition.
MNEXCDS EXCMNTRN EXCMNTER EXCMNUSR EXCMNTST EXCMNSTA EXCMNSTO EXCMNTNO EXCMNTPR EXCMNLUN EXCMNEXN EXCMNRTY EXCMNRID EXCMNTYP EXCMNWT EXCMNBWT EXCMNSWT EXCMNTCN EXCMNSRV EXCMNRPT EXCMNNPX EXCMNNSX EXCMNTRF EXCMNFCN EXCMNCPN EXCMNBTR EXCMNURI EXCMNRIL EXCMNRIX EXCMNNID EXCMNRLU DSECT DS CL4 TRANSACTION IDENTIFICATION DS XL4 TERMINAL IDENTIFICATION DS CL8 USER IDENTIFICATION DS CL4 TRANSACTION START TYPE DS XL8 EXCEPTION START TIME DS XL8 EXCEPTION STOP TIME DS PL4 TRANSACTION NUMBER DS XL4 TRANSACTION PRIORI
queues for which resource data can be collected for any one transaction. For example, if you specify FILE=10 in the DFHMCT TYPE=INITIAL macro, the file resource data section can have up to 960 bytes of file resource data. All the system-defined data fields in the transaction resource monitoring records are described in http://winlnx0c.hursley.ibm.com:19000/help/index.jsp?topic=/ com.ibm.cics.ts.performance.doc/topics/dfht3_mon_tranmnr_fields.html#dfht35m , in the CICS Performance Guide.
DFHMNRDS DSECT MNR_LENGTH MNR_ID_EQUATE MNR_ID MNR_VERSION MNR_DSECT_VERS * MNR_HEADER MNR_HDRLEN , DS EQU DC EQU DS DS H 79 AL2(MNR_ID_EQUATE) X’02’ CL1 CL3 DS 0XL40 DS H DS XL2 DS XL8 MNR_TRN DS H DS XL2 MNR_ISO DS XL4 MNR_ISL DS XL2 MNR_ISN DS XL2 MNR_FSO DS XL4 MNR_FSL DS XL2 MNR_FSN DS XL2 MNR_TSO DS XL4 MNR_TSL DS XL2 MNR_TSN DS XL2 MNR_HDR_LENGTH EQU *-MNR_HEADER SPACE , MNR_ID_DATA DSECT MNR_ID_TRANID DS CL4 MNR_ID_TERMID DS CL4 MNR_ID_USERID DS CL8 MNR_ID_STYPE DS CL4 MNR_ID_START DS XL8 MNR_ID_
MNR_ID_ACMETH_TCAM EQU X’04’ MNR_ID_ACMETH_BGAM EQU X’06’ MNR_ID_ACMETH_CONSOLE EQU X’07’ MNR_ID_DEVCODE DS XL1 * MNR_ID_TERMCNNM DS CL4 MNR_ID_RES_FLAGS DS 0XL4 MNR_ID_RES_FLAG1 DS XL1 MNR_FILE_LIMIT_EXCEEDED EQU X’80’ MNR_TSQUEUE_LIMIT_EXCEEDED EQU X’40’ DS XL3 MNR_ID_ISIPCNNM DS XL8 DS XL8 DS XL8 MNR_ID_LENGTH EQU *-MNR_ID_DATA SPACE , MNR_FILE_ENTRY DSECT MNR_FILE_NAME DS CL8 MNR_FILE_GET DS XL8 MNR_FILE_PUT DS XL8 MNR_FILE_BRWSE DS XL8 MNR_FILE_ADD DS XL8 MNR_FILE_DEL DS XL8 MNR_FILE_TOTAL DS XL8 MNR
Chapter 29. Writing statistics collection and analysis programs This chapter describes how you can customize the collection and analysis of CICS statistics. It is divided into the following sections: 1. “Writing a program to collect CICS statistics” describes how user programs can use EXEC CICS commands to collect statistics and reset statistics counters. 2. “CICS statistics record format” on page 771 describes the format of CICS statistics SMF type 110 records.
Resetting statistics counters Statistics counters are reset in the following circumstances: v At CICS startup v When interval statistics are written (but not when an interval occurs and no statistics are written) v At end of day v When requested reset statistics are written. However, you can cause statistics counters to be reset without writing records to the SMF data set.
v v v v v v v v DFH0STGN DFH0STLK DFH0STPR DFH0STSY DFH0STTP DFH$STAS DFH$STCN DFH$STTB The sample programs produce a report showing critical system parameters from the CICS dispatcher, together with loader statistics and an analysis of the CICS storage manager. DFH$STAS, DFH$STCN, and DFH$STTB are provided in assembler language; the other eight programs are provided in COBOL.
* * STSMFDS SMFSTLEN SMFSTSEQ SMFSTFLG SMFSTRTY SMFSTTME SMFSTDTE SMFSTSID SMFSTSSI SMFSTSTY * SMFSTTRN 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 SMFSTAPS SMFSTLPS SMFSTNPS SMFSTASS SMFSTASL SMFSTASN * * * * * SMFSTRVN SMFSTPRN SMFSTSPN SMFSTMFL DS DS DS DS DS DS DS DS XL2 XL2 XL4 XL2 XL2 XL4 XL2 XL2 THIS CONCLUDES THE SMF HEADER RECORD LENGTH SEGMENT DESCRIPTOR OPERATING SYSTEM INDICATOR (see note 1) RECORD TYPE 110 FOR CICS TIME RECORD MOVED TO
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.
Figure 124 on page 775. For further guidance information about the fields within the statistics data records, see CICS statistics in DSECTs and DFHSTUP report, in the CICS Performance Guide. STIVERS takes the value ‘1’ for this release of CICS.
STID Symbolic name STID Value Copy book Type of record STISMD STISMT STIXMG STIXMR STIXMC STISMDSA STIFEPIP STIFEPIC STIFEPIT STIVT STIPAUTO STIAUTO STILDR STIDBUSS STILDG STITCR STILSRR STILSRFR STITDQR STITDQG STITSQ STICONSR STICONSS STIDS STIUSG STITM STIDST STIDSR STIST STIFCR STIMQG STICONMR STIM STIMNR STITDR STITDG STISDR STISDG STILGG STILGR STILGS STINQG STIRMG STIWBG STID2G STID2R STIWBR STIPIR STIPIW STISOG STISOR STIISR STIIIR STIDHD STIEJR STIEJB STISJG STISJR STIPGR 5 6 10 11 12 14 16 17
The TS data sharing statistics use no symbolic names, but relate to the STID values as follows: STID Symbolic name - STID Value Copy book Type of record 121 122 123 DFHXQS1D DFHXQS2D DFHXQS3D TS server list structure stats id TS buffer stats id TS storage stats id Figure 125.
Processing the output from CICS statistics There are several utilities to help you process statistics output: 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. Tivoli® Decision Support for z/OS This tool enables you to store CICS statistics and other data into a DB2 data set, and to present the data in a variety of forms.
778 Customization Guide
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 30. 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. 2. 3. 4. 5. 6.
The application uses a 3270 display screen terminal, and adjusts its formatting to suit the screen size. BMS is not required. The program is designed so that the installation can easily modify the functions supported to suit installation standards. Installing the program and transaction definitions Transaction and program definitions for the dynamic allocation sample program are provided in the sample utilities group DFH$UTIL on the CSD.
containing “?” is entered, no DYNALLOC SVC is issued. “?” is recognized only in the positions specified above; the rest of the command is ignored. The dynamic allocation program—values Values are classified as follows: Keyword value Keyword values must be specified for some keywords. For example, the STATUS keyword may have a keyword value of SHR, NEW, MOD, or OLD (which can be abbreviated). String of key letters The value can be a string of letters in any order.
The dynamic allocation sample program does not support negative numbers. It does not cross-check operand keywords; errors of this type usually cause DYNALLOC to return error codes of the form 03xx. Abbreviation rules for keywords Keywords can be abbreviated. A word in the command matches a keyword if: v The spelling is the same. v The first letter is the same, and the remaining letters in the word appear in the same order as they do in the keyword.
Following successful tokenizing, the main program calls DFH99FP to analyze the verb keyword. DFH99FP calls DFH99LK to look up the verb keyword in the table, DFH99T. DFH99LK calls DFH99MT if an abbreviation is possible. Upon finding the matching verb, DFH99FP puts the address of the operand section of the table into COMM, and puts the function code into the DYNALLOC request block. The main program now calls DFH99KO to process the operand keywords.
At the end of processing the command, the main program calls DFH99MP with no parameters, which causes it to send the output buffer to the terminal, and initialize it to empty.
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. Customization of password expiry templates for HTTP basic authentication, which is an element of CICS Web support, is covered in the CICS Internet Guide.
Chapter 31. Invoking an external security manager CICS provides an interface to an external security manager (ESM), which may be the Resource Access Control Facility (RACF), a vendor product, or user-written. 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.
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 router passes a parameter list (generated by the RACROUTE macro) to the exit routine. In addition, the exit receives the address of a 150-byte work area.
Table 44. 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. The MVS router translates this return code to a router return code of ‘0’ and returns control to the issuer of the RACROUTE macro (CICS), bypassing RACF processing. (See the next section.) CC The exit has completed successfully.
For non-RACF users — the ESM parameter list CICS (or another caller) passes information to your external security manager in the ESM parameter list, the address of which can be calculated using field SAFPRACP of the MVS router parameter list. When the caller is CICS, the “INSTLN” field of the ESM parameter list points to the installation data parameter list, which contains CICS-related information that can be used by ESM exit programs.
Table 46. Obtaining the address of the installation data parameter list (continued) RACROUTE REQUEST type EXTRACT RACF exit Not available Exit list mapping macro Parameter list field name Not available None Note: 1. The “xxxINSTL” field points to the installation parameter list only if you specify INSTLN on the ESMEXITS system initialization parameter. The default value of this parameter is NOINSTLN, which means that no installation data is passed. 2.
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.
LINK_COMMAND_CHECK (X'51') Command checking for link EDF_COMMAND_CHECK (X'52') Command checking for EDF USER_RESOURCE_CHECK (X'60') Resource checking for user LINK_RESOURCE_CHECK (X'61') Resource checking for link EDF_RESOURCE_CHECK (X'62') Resource checking for EDF USER_SURROGATE_CHECK (X'68') Surrogate checking for user LINK_SURROGATE_CHECK (X'69') Surrogate checking for link EDF_SURROGATE_CHECK (X'6A') Surrogate checking for EDF USER_QUERY_CHECK (X'70') Query checking for user LINK_QUERY_CHECK (X'71') Qu
UXPLUNAM Address of an area containing the VTAM LU name. The address may be zero if no terminal is associated with the request, or the area may be blank if the terminal is not a VTAM terminal. UXPTCTUA Address of the TCT user area. UXPTCTUL Address of a fullword containing the length of the TCTUA. UXPCOMM Address of a 2-word communication area. CICS security control points The following list summarizes the RACROUTE macros used by CICS to invoke the ESM, and the control points at which they are issued.
v When an invalid password, or a passticket is presented, or an EXEC CICS VERIFY PASSWORD command is issued. RACROUTE REQUEST=FASTAUTH Issued during resource checking, on behalf of a user who is identified by an ACEE.
CICS defers the creation of the accessor environment element until the RACROUTE REQUEST=VERIFY macro with the ENVIR=CREATE option is issued to perform the normal verification routine. The ENVIR=CREATE version of the macro is issued by the security manager domain running in supervisor state. CICS passes the following information on the ENVIR=VERIFY version of the RACROUTE REQUEST=VERIFY macro: USERID The userid of the user signing on to the CICS region.
Using CICS API commands in an early verification routine An early verification routine can use CICS application programming interface (API) commands, provided it obeys the following interface rules: v The routine must be written in assembler. v Entry to the routine must be via the DFHEIENT macro, which saves the caller’s registers and establishes a CICS early verification API environment.
800 Customization Guide
Chapter 32. 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. Note: 1.
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 TRANSID that invoked GNTRAN Pseud
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. GNTRAN_SCREEN_HEIGHT The height of the screen in use when the terminal timed out.
c. Writes the communication area, if any, to a temporary storage queue. d. Displays a screen asking the user to input his or her password, and sets the flag indicating that this has been done. e. Issues EXEC CICS RETURN with TRANSID GNIT and the COMMAREA option, to continue the timeout process as a pseudoconversation. 3. If this is not the first invocation for this timeout: a. Recovers the original communication area, if any, from the temporary storage queue. b.
LOGOFF The terminal is both signed off and logged off. v Specify the identifier (TRANSID) of your “good night” transaction on the GNTRAN system initialization parameter. If you have customized the sample program, DFH0GNIT, specify the supplied sample transaction definition, GNIT. If you have written your own “good night” program, named something other than DFH0GNIT, you must create and install a transaction definition that points to your program, and specify this definition on the GNTRAN SIT parameter.
806 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 33. Using the programmable interface to CEDA This chapter describes a programmable interface to the resource definition online (RDO) transaction, CEDA. The functions provided by RDO can be invoked from application programs, by a command such as: EXEC CICS LINK PROGRAM(’DFHEDAP’) COMMAREA(CEDAPARM) where DFHEDAP is the name of the entry point in the RDO program, and CEDAPARM is a user-defined name of a parameter list consisting of five 31-bit addresses (each contained in a fullword) as follows: 1.
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. (For example, spelling errors such as PRORGAM for PROGRAM are not corrected automatically when you use the programmable interface.) 3.
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. Do not attempt to use LINK DFHEDAP when more than a pair of DTP application programs are involved—that is, one front end and one back end.
812 Customization Guide
Chapter 34. 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. “Invoking a user program from DFHCSDUP” on page 814 describes the DFHCSDUP EXTRACT command, and tells you how to write a user program to be invoked from DFHCSDUP. 3.
v As a batch program. The next section refers to this method. v From a user program running either in batch mode or in a TSO environment. “Invoking DFHCSDUP from a user program” on page 821 describes this method. Invoking a user program from DFHCSDUP 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.
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. When the user program is invoked The user program can be invoked at nine different points during the processing of the EXTRACT command by DFHCSDUP.
8 10 12 14 16 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. Back translated command Ptr The address of a fullword that contains the address of a 75-byte area of storage that contains the EXTRACT command that is being processed.
Table 48. Sample EXTRACT user programs for the DFHCSDUP utility program (continued) Program names Languages Description DFH$FORA DFH0FORC DFH$FORP Assembler COBOL PL/I Formats the group or list of resource definitions you specify on the EXTRACT command into a form suitable for the DB2 table load utility. DFH0CBDC COBOL Writes the list or group of resource definitions you specify on the EXTRACT command in the form of DEFINE commands, suitable for use as a backup copy of the resources extracted.
The CSD cross-referencing program The CICS-supplied sample CSD cross-referencing program produces a cross-reference listing of objects and keywords on the CSD. The data gathered by the EXTRACT command is passed to the sample program, where it is saved in a cross-reference table. On the final call to this sample program, the contents of the table are printed in collating sequence.
v For distribution, in part or as a whole, to other CICS installations v To recreate or add resource definitions to any CSD using DFHCSDUP. The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) or: EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword.
An assembler-language version The sample job in Figure 129 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=CICSTS32.CICS.SDFHLOAD,DISP=SHR //SYSLMOD DD DSN=user.
//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=CICSTS32.CICS.CICS.SDFHLOAD,DISP=SHR //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLMOD DD DSN=user.
message number ‘DFH5618’ to the put-message exit (see “The put-message exit” on page 827), where this is available, and also to the default output file: AN ATTENTION INTERRUPT WAS REQUESTED DURING DFHCSDUP PROCESSING Your put-message exit routine can terminate DFHCSDUP, if desired. (Note that you must supply a put-message routine if you want your operators to regain control after an ATTENTION interrupt.) 2.
Note that if you specify both replacement ddnames and replacement DCBs, the alternative DCBs are used, but the alternative ddnames are disregarded. EXITS The addresses of a set of user exit routines to be invoked during processing of DFHCSDUP. The structure of the parameter list is shown in Figure 131.
first three subentries of the DDNAMES parameter. The fourth, fifth, and sixth subentries, if present, replace the ddnames of DFHCSD, SYSIN, and SYSPRINT, respectively. v In the DCBS functional data, each subentry consists of two fullwords. The first word is not used by CICS. The second word contains the address of an open DCB or ACB.
DFHUEXIT UEPEXN UEPGAA UEPGAL UEPCRCA UEPTCA UEPCSA UEPHMSA UEPSTACK UEPXSTOR UEPTRACE * UEPCMDA UEPCMDL * DSECT DS DS DS DS DS DS DS DS DS DS A A A A A A A A A A ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS ADDRESS DS DS A A ADDRESS OF UTILITY COMMAND ADDRESS OF LENGTH OF UTILITY COMMAND OF OF OF OF OF OF OF OF OF OF EXIT NUMBER GLOBAL AREA GLOBAL AREA LENGTH CURRENT RETURN-CODE TCA CSA SAVE AREA USED BY HOST KERNEL STACK ENTRY STORAGE OF XPI PARMS TRACE FLAG Explanation
UEPCMDA Pointer to the address of a command. UEPCMDL Address of a halfword containing the length of the command text. The maximum length that can be specified is 1536 bytes. Return codes UERCNORM (X'00') Continue processing. UERCDONE (X'04') No more commands to process. (This is equivalent to reaching end-of-file on the SYSIN file.) UERCERR Irrecoverable error. This causes DFHCSDUP to terminate with a return code of ‘8’. XPI calls Must not be used.
data is being extracted. This value is set on ‘group start’, ‘group end’, ‘object start’, ‘object end’, and ‘keyword’ calls. EXTRACT_CSD_OBJECT_TYPE_PTR Address of a 12-byte field that identifies the type of object (such as TRANSACTION, PROGRAM, and so on). This value is set only on ‘object start’, ‘object end’, and ‘keyword’ calls. EXTRACT_CSD_OBJECT_NAME_PTR Address of an 8-byte field containing the name of the object. This value is set only on ‘object start’, ‘object end’, and ‘keyword’ calls.
UEPMDOM Reserved UEPINSN Address of a 2-byte field containing the number of insert fields UEPINSA Address of the following message structure: INS_1_TEXT_PTR INS_1_LEN_PTR DS F DS A DS A DS F DS F INS_2_TEXT_PTR DS A INS_2_LEN_PTR DS A DS ...
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. The sample program, DFH$CUS1 The CICS-supplied sample program, DFH$CUS1, illustrates how DFHCSDUP can be invoked from a user program. It is written as a command processor (CP) for execution under the TSO/E operating system. Note that DFH$CUS1 uses different DCB and ACB names from those normally used by DFHCSDUP.
830 Customization Guide
Part 9. Appendixes © Copyright IBM Corp.
832 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 of the VTAM LOGON mode table” 2. “TYPETERM device types and pointers to related LOGON mode data” 3. “VTAM MODEENT macro operands” on page 835 4. “PSERVIC screen size values for LUTYPEx devices” on page 840 5. “Matching models and LOGON mode entries” on page 841 6.
Note that Table 49 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 (*). For details about coding TYPETERM definitions, and for a list of terminals that can be autoinstalled, see the CICS Resource Definition Guide. Table 49.
Table 49.
table, such as PSERVIC for some reference numbers, are not tested by CICS. Any bit settings that do not matter to CICS during bind analysis for autoinstalled terminals appear as periods (.). Note: Some fields in the PSERVIC data for LUTYPE0, LUTYPE2, and LUTYPE3 devices have values that depend on the ALTSCREEN and DEFSCREEN characteristics of the device.
Table 50. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 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.000 PSERVIC=B’00000001 ........ 00000000 9 FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=X’90’ COMPROT=B’0011.000 PSERVIC=B’00000001 ........ 00000000 Suitable supplied entries 01000.
Table 50. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 14 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 ........ 00000000 01010000’ FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=X’B0’ COMPROT=B’0111.000 PSERVIC=B’00000001 ........ 00000000 10000.00’ 00110001 00001100 0111000.
Table 50. LOGON mode table and ISTINCLM entries (continued) RN VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions 19 FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=B’10..0000’ COMPROT=B’0011.000 10000.00’ PSERVIC=B’00000011 10000000 00000000 00000000 00000000 00000000 aaaaaaaa bbbbbbbb cccccccc dddddddd eeeeeeee’ Suitable supplied entries BLK3790 DSC2K DSC4K D6328902 D6328904 See note 1 20 FMPROF=X’04’ TSPROF=X’03’ PRIPROT=X’31’ SECPROT=X’B0’ COMPROT=B’0111.
PSERVIC screen size values for LUTYPEx devices Table 51 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 51, 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 51.
Table 52.
ATI TTI AUTOCONNECT LOGONMSG ==> ==> ==> ==> YES YES NO YES BIND SENT BY CICS depends on PSERVIC value on LOGMODE definition above: EITHER : 01020271 40200000 00000080 00000000 00000000 00000002 00009300 00300000 OR : 01020271 40200000 00000080 00000000 00000018 502B507F 00009300 00300000 OR : 01020271 40200000 00000080 00000000 Real Model 2 00000018 5000007E 00009300 00300000 ****************************************************************** 2) LOCAL SNA 3277/78/79 (without special features) LUTYPE2 ***
TERMINAL definition ************************* AUTINSTNAME ==> M3770 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3770 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3770 GROUP ==> PDATD DEVICE ==> 3770 SESSIONTYPE ==> BATCHDI PAGESIZE ==> 12,80 DISCREQ ==> YES AUTOPAGE ==> YES RECEIVESIZE ==> 256 SENDSIZE ==> 256 IOAREALEN ==> 256,2048 BUILDCHAIN ==> YES BRACKET ==> YES ATI ==> YES TTI ==> YES AUTOCONNECT ==> NO HORIZFORM ==> YES VERTFORM ==> YES LDCLIST ==> LDC2 Needs
ATI TTI PAGESIZE AUTOPAGE LOGONMSG LDCLIST ==> ==> ==> ==> ==> ==> YES YES 50,80 YES NO LDC1 Needs LDC declaration in TCT : LDCS DFHTCT TYPE=LDC,LDC=SYSTEM LDC1 DFHTCT TYPE=LDC,LOCAL=INITIAL DFHTCT TYPE=LDC,DVC=(BLUCON,01),PROFILE=DEFAULT,LDC=PC, PGESIZE=(50,80),PGESTAT=AUTOPAGE DFHTCT TYPE=LDC,DVC=(BLUPRT,02),PROFILE=BASE,LDC=PP, PGESIZE=(50,80),PGESTAT=AUTOPAGE DFHTCT TYPE=LDC,DVC=(BLUPRT,08),PROFILE=BASE,LDC=P8, PGESIZE=(50,80),PGESTAT=AUTOPAGE DFHTCT TYPE=LDC,DVC=(BLUPRT,08),PROFILE=DEFAULT,LDC=DP, P
BRACKET IOAREALEN ATI TTI ==> ==> ==> ==> YES 256 YES YES BIND SENT BY CICS : 010404B1 B0708000 00858580 00000000 ****************************************************************** 6) 3790 BATCH DATA INTERCHANGE ****************************************************************** S3790B MODEENT LOGMODE=S3790B, 3790 BATCH TYPE=1, FMPROF=X’03’, TSPROF=X’04’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’7080’, RUSIZES=X’8585’, PSERVIC=X’013118400000920000E10050’ TERMINAL definition ************************* AUTI
AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3790C INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3790C GROUP ==> PDATD DEVICE ==> 3790 SESSIONTYPE ==> SCSPRT BRACKET ==> YES SENDSIZE ==> 256 RECEIVESIZE ==> 256 ATI ==> YES TTI ==> YES BIND SENT BY CICS : Note that CEDA changes DEVICE=3790, SESSIONTYPE=SCSPRT to DEVICE=SCSPRINT, SESSIONTYPE=blanks, PRINTERTYPE=3284.
TERMINAL definition ************************* AUTINSTNAME ==> M3650A AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3650A INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3650A GROUP ==> PDATD DEVICE ==> 3650 SESSIONTYPE ==> USERPROG ROUTEDMSGS ==> SPECIFIC FMHPARM ==> YES RELREQ ==> YES DISCREQ ==> YES BRACKET ==> YES RECEIVESIZE ==> 256 IOAREALEN ==> 256,256 ATI ==> YES TTI ==> YES AUTOCONNECT ==> NO BIND SENT BY CICS : 01040431 30600000 00000080 00000000 **************
TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’6000’ TERMINAL definition ************************* AUTINSTNAME ==> M3650B2 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3650B2 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3650B2 GROUP ==> PDATD DEVICE ==> 3650 SESSIONTYPE ==> 3653 RELREQ ==> YES DISCREQ ==> NO BRACKET ==> YES IOAREALEN ==> 256 RECEIVESIZE ==> 240 ROUTEDMSGS ==> NONE ATI ==> NO TTI ==> YES BIND SENT BY CICS : 010403B1 90600000 00000080 00000000
TSPROF=X’07’, PRIPROT=X’B0’, SECPROT=X’B0’, COMPROT=X’50B1’, PSNDPAC=X’00’, SRCVPAC=X’00’, SSNDPAC=X’00’, RUSIZES=X’8585’, PSERVIC=X’060200000000000000002C00’ TERMINAL definition ************************* AUTINSTNAME ==> MLU62 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> SINLU62 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> SINLU62 GROUP ==> PDATD DEVICE ==> APPC RECEIVESIZE ==> 2048 SENDSIZE ==> 2048 ATI ==> YES TTI ==> YES Note: There is no RDO keyword equivalent of th
USERAREALEN ATI TTI LOGONMSG ERRHILIGHT RECEIVESIZE ==> ==> ==> ==> ==> ==> 32 YES YES YES BLINK 1024 BIND SENT BY CICS : 010303B1 90308000 00878780 00028000 00000018 503EA07F 00000000 00000000 ****************************************************************** 15) 3601 WITH A 3604 ATTACHED ****************************************************************** S3600 MODEENT LOGMODE=S3600, 3601 TYPE=1, FMPROF=X’04’, TSPROF=X’04’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’7000’, RUSIZES=X’0000’ TERMINAL definit
DFHLU3 MODEENT LOGMODE=DFHLU3, LU TYPE 3 PRINTER.
DFHLU0M2 MODEENT LOGMODE=D4B32782, LU0 model 2 nonqueryable FMPROF=X’02’, TSPROF=X’02’, PRIPROT=X’71’, SECPROT=X’40’, COMPROT=X’2000’, RUSIZES=X’0000’, PSERVIC=X’000000000000185000007E00’ DFHLU0M3 MODEENT LOGMODE=D4B32783, LU0 model 3 nonqueryable FMPROF=X’02’, TSPROF=X’02’, PRIPROT=X’71’, SECPROT=X’40’, COMPROT=X’2000’, RUSIZES=X’0000’, PSERVIC=X’000000000000185020507F00’ DFHLU0M4 MODEENT LOGMODE=D4B32784, LU0 model 4 nonqueryable FMPROF=X’02’, TSPROF=X’02’, PRIPROT=X’71’, SECPROT=X’40’, COMPROT=X’2000’, R
DFHLU2M3 MODEENT LOGMODE=D4A32783, LU2 model 3 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, RUSIZES=X’87C7’, PSERVIC=X’020000000000185020507F00’ DFHLU2M4 MODEENT LOGMODE=D4A32784, LU2 model 4 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, RUSIZES=X’87C7’, PSERVIC=X’02000000000018502B507F00’ DFHLU2M5 MODEENT LOGMODE=D4A32785, LU2 model 5 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, R
854 Customization Guide
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.
Table 53.
Table 53.
Table 53.
Table 53.
Table 53.
Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code X'FF' Symbolic label Message Action flags set TCZPSPE DFHZC0149 7 Note: 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 54.
Table 54.
Table 54.
Table 54.
Table 54.
Table 54.
Table 55.
Table 55. Messages issued and flags set by DFHZNAC for specific sense codes (continued) Sense code Message Action flags set X'40FF' DFHZC3453 2, 3, 7, 9, 10, 11, 23, 24 X'8000' DFHZC3435 2, 3, 7, 9, 10, 11, 18, 24 X'8005' DFHZC3435 2, 3, 7, 9, 10, 11, 18, 24 X'80FF' DFHZC3435 2, 3, 7, 9, 10, 11, 18, 23, 24 X'FFFF' DFHZC2460 2, 3, 7, 9, 10, 11, 23, 24 Note: 1. The system sense code is in the form of an LUSTATUS command code. 2.
Table 56. Meanings of action flags set by DFHZNAC (continued) Flag Bit mask Hex bit setting 11 ..1. .... X'20' 12 ...1 .... X'10' 13 .... 1... X'08' 14 .... .1.. X'04' 15 .... ..1. X'02' 1... .... .1.. .... X'80' X'40' 20 ...1 .... X'10' 21 .... 1... X'08' 22 23 .... .1.. .... ..1. X'04' X'02' 24 .... ...
870 Customization Guide
Appendix C. Analyzing CICS restart information You can programmatically determine the type of CICS shutdown that occurred and whether it is safe to override the next restart type and perform a cold restart of the CICS system. DFHRMUTL provides the SET_AUTO_START keywords to allow a CICS system to be auto-restarted with a given override. This can include AUTOCOLD, to make CICS perform a cold start. Care should be taken when performing such a change.
872 Customization Guide
Appendix D. Using the 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.
874 Customization Guide
Appendix E. Uppercase translation This appendix describes how to translate lower- and mixed-case characters to uppercase. “Translating national characters to uppercase” describes how to translate national characters that CICS cannot handle by standard means. “Translating TS data sharing messages to uppercase” on page 876 describes how to translate operator messages produced by CICS temporary storage data sharing.
Note: If you are already using a customized TCT rather than DFHTCTDY (that is, something other than 'NO' or 'DY' is specified on the SIT TCT parameter), you must add your translation code to the TCT you are using. Figure 133 shows a suggested way to code the assembler source statements to translate your national characters. 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. .
Appendix F. 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.
* * * 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.
*---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries. Each entry * * can be mapped by the TABLE_ENTRY DSECT * *---------------------------------------------------------------------* TABLE_ENTRY DSECT ENTRY_NAME DS CL8 NEW_NAME DS CL8 NEW_SYSID DS CL4 ENTRY_ACTION DS XL1 FILLER DS CL3 * *---------------------------------------------------------------------* * The following definitions are for program working storage.
* 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_Request * * When(XTSEREQC) then call TS_Reque
*=====================================================================* * TS_REQUEST - Invoked at XTSEREQ exit point * * Determine the TS Queue Name and scan the TS_Routing_Table for * * a match. If an entry exists in the table, then check the action * * field and call the ROUTE_REQUEST or LOCAL_REQUEST routines.
*=====================================================================* TS_REQUEST DS 0H * Check for possible recursion L R1,UEPRECUR Address of recursive count LH R1,0(R1) Fetch count LTR R1,R1 Has exit been invoked recursively? BNZ ERROR2 ..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..
*=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point * * Free any shared storage that was acquired during previous * * invocation at XTSEREQ.
*=====================================================================* * LOCAL_REQUEST: Process Local TS Queues * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. If required, rename the TS Queue Name, but do not * * modify the SYSID.
*=====================================================================* * ROUTE_REQUEST: Ship request to remote system * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. The request is modified by adding a SYSID to the * * command and renaming the queue if required.
* 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 ..
* 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 L R12,0(R12) Fetch shared storage address
*=====================================================================* * 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(resp) * * If resp ¬= OK then * * Call Er
*=====================================================================* * FREEMAIN_SHARED - Free shared storage * * Free the shared storage associated with this command.
USING DFHTRPT_ARG,R1 TRACE_ENTRY DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ENTRY) B ISSUE_TRACE TRACE_EXIT DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_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 * *----------------------------------------
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 * *********************************************************************** DS 0D EYE_CATCHER DC CL16’XTSEREQ
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
Appendix G. Threadsafe XPI commands Most, but not all, XPI commands are threadsafe. Issuing any of the non-threadsafe commands causes CICS to use the QR TCB to ensure serialization. The XPI commands that are threadsafe are indicated in the command syntax diagrams in Chapter 3, “The user exit programming interface (XPI),” on page 305 with the statement: “This command is threadsafe”, and are listed here.
Non-threadsafe commands: v DFHDUDUX TRANSACTION_DUMP 894 Customization Guide
Bibliography The CICS Transaction Server for z/OS library The published information for CICS Transaction Server for z/OS is delivered in the following forms: The CICS Transaction Server for z/OS Information Center The CICS Transaction Server for z/OS Information Center is the primary source of user information for CICS Transaction Server. The Information Center contains: v Information for CICS Transaction Server in HTML format.
CICS Transaction Server for z/OS Migration from CICS TS Version 3.1, GC34-6858 CICS Transaction Server for z/OS Migration from CICS TS Version 1.3, GC34-6855 CICS Transaction Server for z/OS Migration from CICS TS Version 2.
CICSPlex SM Application Programming Guide, SC34-6848 CICSPlex SM Application Programming Reference, SC34-6849 Diagnosis CICSPlex SM Resource Tables Reference, SC34-6850 CICSPlex SM Messages and Codes, GC34-6851 CICSPlex SM Problem Determination, GC34-6852 CICS family books Communication CICS Family: Interproduct Communication, SC34-6853 CICS Family: Communicating from CICS on zSeries, SC34-6854 Licensed publications The following licensed publications are not included in the unlicensed version of the Info
Short Title Full Title Data Areas Volume 1 OS/390 MVS Data Areas, Vol 1 (ABEP-DALT), SY28-1164 Data Areas Volume 2 OS/390 MVS Data Areas, Vol 2 (DCCB-ITTCTE), SY28-1165 Data Areas Volume 3 OS/390 MVS Data Areas, Vol 3 (IVT-RCWK), SY28-1166 Data Areas Volume 4 OS/390 MVS Data Areas, Vol 4 (RD-SRRA), SY28-1167 Data Areas Volume 5 OS/390 MVS Data Areas, Vol 5 (SSAG-XTLST), SY28-1168 — System Management Facilities MVS/ESA Resource Measurement Facility (RMF), Version 5–Monitor I & II Reference and U
Updates to the softcopy are clearly marked by revision codes (usually a # character) to the left of the changes.
900 Customization Guide
Accessibility Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use software products successfully. You can perform most tasks required to set up, run, and maintain your CICS system in one of these ways: v using a 3270 emulator logged on to CICS v using a 3270 emulator logged on to TSO v using a 3270 emulator as an MVS system console IBM Personal Communications provides 3270 emulation with accessibility features for people with disabilities.
902 Customization Guide
Index Special characters “good night” transaction customizing the sample program 804 overview 801 sample program, DFH0GNIT 803 Numerics 3270 bridge bridge exit 661 bridge exit program 661 3270 information display system error processors (optional) 498 unavailable printer DFHZNEP 506 A abends transaction bit 472 abnormal conditions in terminal error programs 470 sample node error program 496 sample terminal error program 451 user-written node error programs 505 abort write bit 472 ACF/VTAM application rout
automatic installation of IPIC connections introduction 553 preliminary considerations 553 automatic installation of programs benefits of 581 control program parameter list at install 583 testing 588 installation of mapsets 581 introduction 579 model definitions 580 requirements for 582 supplied resource definitions 587 system autoinstall 581 the sample programs customizing 586 DFHPGADX 586 DFHPGAHX 586 DFHPGALX 586 DFHPGAOX 586 automatic installation of shipped terminals control program parameter list at d
communications area autoinstall control program APPC connections 545 programs 583 terminals 518 autoinstall user program IPCONNs 555 CICSDBCTL interface status program 659 distributed routing program 645 dynamic routing program 607 node error program 487 program error program 441 terminal error program 471 transaction restart program 446 consoles, automatic installation 535 COUNT operand DFHSNET macro 503 DFHTEPT TYPE=PERMCODE|ERRCODE 466 limits, default threshold for TEP 466 CS operand DFHSNEP TYPE=INITIAL
DFHCSDUP, system definition utility program (continued) sample programs (continued) DFH$CRFA 816 DFH$CRFP 816 DFH$FORA 817 DFH$FORP 817 DFH0CBDC 817 DFH0CRFC 816 DFH0FORC 817 DFHDBUEX, CICS–DBCTL interface status program communications area 659 introduction to 659 sample program 660 DFHDDAPX macro 321, 323, 324, 325, 326, 327, 328, 329, 330 DFHDSATX macro 331 DFHDSRP, distributed routing program changing the target region 627, 633, 639, 643 communications area 645 differences from dynamic routing program 62
DFHSAIQX macro 386, 391 DFHSMFDS, SMF header DSECT 750 DFHSMMCX macro 392 DFHSMSRX macro 397 DFHSNEP macro TYPE=DEF3270 500 TYPE=DEFILU 501 TYPE=ERRPROC 484, 501 TYPE=FINAL 501 TYPE=INITIAL 483, 500 TYPE=USTOR 499 TYPE=USTOREND 499 DFHSNEP, sample node error program 499 DFHSNET macro 503 COUNT operand 503 ESB structure 503 ESBS operand 503 NAME operand 503 NEBNAME operand 503 NEBS operand 503 TIME operand 503 DFHSTUP, statistics processing program 777 DFHTACP, terminal abnormal condition program 450 termina
distributed program link (DPL) (continued) dynamic routing of requests (continued) eligibility for routing 597 error handling 600 terminating a request 600 when the routing program is invoked 598 distributed routing of BTS activities changing the target region 627 eligibility for routing 625 error handling 628 running the activity locally 627 when the routing program is invoked 626 of inbound Web service requests changing the target region 643 eligibility for routing 641 error handling 644 running the trans
dynamic routing program (DFHDYP) (continued) changing bridge parameters 604 changing the program name 593, 599 changing the target region 592, 599 communications area 607 error handling 594, 600 information passed to 591 invoking on abend 594, 602 modifying application’s communications area 595, 602 modifying initial terminal data 595 overview 589 processing considerations 596, 602 receiving information from routed DPL request monitoring the output COMMAREA 602 receiving information from routed transaction
Functional list of GLUEs 32 G generic resources, VTAM 547 node error program 512 GET_ATTRIBUTE_VALUE function of the XPI 325 GET_NEXT_ATTRIBUTE function of the XPI 326 GET_NEXT_ENTRY function of the XPI 327 GET_NEXT_PROGRAM function of the XPI 380 GETMAIN function of the XPI 393 global user exits example programs 18 for EXEC interface exits 877 for mixing API and XPI calls 5, 877 for modifying TS requests 221, 877 for XFCREQ 94, 98 for XFCREQC 94, 98 for XICEREQ 161, 162 for XICEREQC 161, 162 for XPCREQ 1
global user exits (continued) sample programs (continued) DFH$WBX1 21 DFH$WBX2 22 DFH$XDRQ 19 DFH$XISQ 24 DFH$XNQE 19, 66 DFH$XZIQ 24 DFH$ZCAT 16 DFHXIS 140 DFHXTENF 230 summary of 15 trace table entries 6 with storage protection data storage key 11 execution key 11 GLUEs 3 GLUEs, alphabetical list 25 GLUEs, functional list 32 GMTRAN, system initialization parameter 493 GNTRAN, system initialization parameter 801, 805 GROUP operand DFHSNEP TYPE=ERRPROC 501 I IIOP DFHEBURM 665 DFHXOPUS 665 security exit pro
log manager functions of the XPI 360 logical units (LUs) node error program 486 LOGON mode table, VTAM 833 LU alias names 523 M MAXERRS operand DFHTEPT TYPE=INITIAL 465 MAXTIDS operand DFHTEPT TYPE=INITIAL 465 MCT (monitoring control table) entries for DBCTL 749 entries for EMPs 747 model definitions for autoinstall of APPC connections 543 for automatic installation of programs 580 model terminal support coding entries 517 MONITOR function of the XPI 362 monitoring control table (MCT) 747 data section form
NEP (node error program) (continued) sample (continued) DFHSNEP TYPE=INITIAL macro 500 DFHSNEP TYPE=USTOR macro 499 DFHSNEP TYPE=USTOREND macro 499 error processor vector table (EPVT) 497, 501 error processors for INTLU, DFHSNEP TYPE=DEFILU 501 error processors, DFHSNEP TYPE=DEF3270 500 error status information 497 generating by DFHSNEP 499 node error table 497 optional common subroutines 498 optional error processor for INTLU 499 optional error processors for 3270 498 routing mechanism (ACF/VTAM) 497 sessi
nonpurgeable task 472 notation, syntax xviii O OPTIONS operand DFHTEPM TYPE=INITIAL 460 DFHTEPT TYPE=INITIAL 465 overseer program customizing the sample program 703 including the CEBT command 704 loop or wait detection in the active 705 DFH$AXRO 693 DFHOSD data set 693 DFHWOSM macros 695 FUNC=BUILD 696 FUNC=CLOSE 696 FUNC=DSECT 697 FUNC=JJC 697 FUNC=JJS 697 FUNC=OPEN 698 FUNC=OSCMD 699 FUNC=QJJS 697 FUNC=READ 699 FUNC=TERM 703 display function 690 interface with CICS 693 module DFHWOS 693 opening CAVM data
S sample programs “good night” transaction (DFH0GNIT) 803 CICS–DBCTL interface status program (DFHDBUEX) 660 for automatic installation of APPC connections 550 for automatic installation of IPCONNs 557 for automatic installation of programs 586 for automatic installation of terminals 527 for distributed routing 657 for dynamic allocation (DYNALLOC) 781 for dynamic routing 622 for global user exits DFH$APAD, for the XAPADMG exit 18 DFH$BMXT, for the XBMIN and XBMOUT exits 18 DFH$DTAD, for the XDTAD exit 18 D
syntax notation xviii system autoinstall 581 system definition utility program (DFHCSDUP) as a batch program EXTRACT command 814 link-edit statements for user program 819 parameters passed from DFHCSDUP to the user program 815 when the user program is invoked 815 writing a program for EXTRACT processing 814 invocation from a user program entry parameters for DFHCSDUP 822 introduction 821 responsibilities of the user program 824 user exits in DFHCSDUP 824 overview 813 running under TSO 821 sample programs CS
task-related user exits (continued) UEPHMSA, address of register save area 275 UEPPBTOK, address of performance block token 277 UEPRMQUA, address of the resource manager qualifier name 276 UEPRMSTK, address of the kernel stack entry 275 UEPSECBLK, address of a fullword addressing the user security block 275 UEPSECFLG, address of the user security flag 275 UEPSYNCA, address of the single-update indication byte 276 UEPTAA, address of local work area 275 UEPTAL, length of local work area 275 UEPTIND, address o
terminal error program (TEP) (continued) replace error processors, DFHTEPM TYPE=ERRPROC 462 sample action flag names 457 common subroutines 455 components 451 DECB information 458 DECB operand 458 DFHTEPM TYPE=INITIAL 459 entry and initialization 454 error processing execution 454 error processor selection 454 error status element (ESE) 452 ESE information 458 exit 455 generate sample module 459 messages 456 overview 454 TACLE information 458 terminal error block (TEB) 452 terminal identification and error-
user-written node error programs 505 utility programs shutdown assist, DFHCESD 429 V virtual terminals, automatic installation of VTAM dynamic LU alias 523 567 W work areas in task-related user exits 292 WRITE JOURNAL DATA function of the XPI X XALCAID, global user exit 221 XALTENF, global user exit 226 XAPADMGR, global user exit 33 XBMIN, global user exit 35 XBMOUT, global user exit 35 XDLIPOST, global user exit 51 XDLIPRE, global user exit 49 XDSAWT, global user exit 48 XDSBWT, global user exit 47 XDT
XPCREQ, global user exit (continued) description 175 example of use 185 parameter list and return codes 177 UEPCLPS parameter 181 XPCREQC, global user exit command parameter structure 181 description 177 example of use 185 parameter list and return codes 179 UEPCLPS parameter 181 XPCTA, global user exit 190 XPI (exit programming interface) directory domain functions BIND_LDAP 321 END_BROWSE_RESULTS 323 FLUSH_LDAP_CACHE 323 FREE_SEARCH_RESULTS 324 GET_ATTRIBUTE_VALUE 325 GET_NEXT_ATTRIBUTE 326 GET_NEXT_ENTRY
XRMMI, global user exit 193 XRSINDI, global user exit 196 XSNEX, global user exit 201 XSNOFF, global user exit 200 XSNON, global user exit 199 XSRAB, global user exit 203 XSTERM, global user exit 206 XSTOUT, global user exit 202, 776 XSZARQ, global user exit 137 XSZBRQ, global user exit 137 XTCATT, global user exit 224 XTCIN, global user exit 223 XTCOUT, global user exit 223 XTDEREQ, global user exit command parameter structure 239 parameter list and return codes 237 UEPCLPS parameter 240 XTDEREQC, global u
922 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.
Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
926 Customization Guide
Readers’ Comments — We'd Like to Hear from You CICS Transaction Server for z/OS Customization Guide Version 3 Release 2 Publication No. SC34-6814-04 We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy, organization, subject matter, or completeness of this book. The comments you send should pertain to only the information in this manual or product and the way in which the information is presented.
SC34-6814-04 ___________________________________________________________________________________________________ Readers’ Comments — We'd Like to Hear from You Cut or Fold Along Line _ _ _ _ _ _ _Fold _ _ _and _ _ _Tape _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _ _ _ _ do _ _ not _ _ _staple _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold _ _ _and _ _ Tape ______ PLACE POSTAGE STAMP HERE IBM United Kingdom Limited User Technologies Department (MP095) Hursley Park Wi
Product Number: 5655-M15 SC34-6814-04
Spine information: CICS Transaction Server for z/OS Customization Guide Version 3 Release 2
