Gebruiksaanwijzing /service van het product SC34-6814-04 van de fabrikant IBM
Ga naar pagina of 953
CIC S T ransa ct i o n Serv er f o r z /OS C u st o miz ati o n G ui d e V ers ion 3 Re lea s e 2 SC34-6814-04 .
.
CIC S T ransa ct i o n Serv er f o r z /OS C u st o miza ti o n G ui d e V ers ion 3 Re lea s e 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 V ersion 3 Release 2 of CICS T ransaction Server for z/OS, program number 5655-M15, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions.
Contents Preface ........................... xvii What this book is about ..................... xvii Who this book is for ....................... xvii What you need to know to understand this book ............ xvii How to use this book ...............
File control EXEC interface API exits XFCREQ and XFCREQC ...... 8 5 File control EXEC interface SPI exits XFCAREQ and XFCAREQC ..... 9 8 File control file state program exits XFCSREQ and XFCSREQC ..... 1 1 1 File control open/close program exit XFCNREC .
Recursion within a task-related user exit program ........... 2 9 0 Purging tasks ........................ 2 9 0 Using CICS services in your task-related user exit program ....... 2 9 1 Using channels and containers ................. 2 9 2 Assembler programs and LEASM .
The DEFINE_PROGRAM call .................. 3 5 3 The ACQUIRE_PROGRAM call ................. 3 5 6 The RELEASE_PROGRAM call ................. 3 5 8 The DELETE_PROGRAM call .................. 3 5 9 Log manager XPI functions .................... 3 6 0 The INQUIRE_P ARAMETERS call .
Storage keys for PL T programs ................. 4 3 0 Part 3. Customizing with user-replaceable programs ............. 4 3 3 Chapter 5. General notes about user-replaceable programs ...... 4 3 5 Rewriting user-replaceable programs ................ 4 3 5 Assembling and link-editing user-replaceable programs .
Coding for specific VT AM sense codes .............. 5 0 8 Writing multiple NEPs ..................... 5 0 8 DFHZNEPI macros ...................... 5 0 8 Handling shutdown hung terminals in the node error program ...... 5 1 0 Using the node error program with XRF or persistent sessions .
The sample autoinstall control program for APPC connections ....... 5 5 0 Default actions of the sample program ............... 5 5 0 Resource definitions ..................... 5 5 1 Chapter 13. Writing a program to control autoinstall of IPIC connections 553 Autoinstalling IPIC connections: preliminary considerations .
Routing transactions dynamically .................. 5 9 0 Dynamic transactions ..................... 5 9 0 When the dynamic routing program is invoked ............ 5 9 0 Information passed to the dynamic routing program .......... 5 9 1 Changing the target CICS region .
When the distributed routing program is invoked ........... 6 3 2 Changing the target CICS region ................. 6 3 3 T elling CICS whether to route the method request .......... 6 3 4 If an error occurs in route selection ................ 6 3 4 Invoking the distributed routing program on the target region .
Event codes ......................... 6 8 1 The EJB event sample program .................. 6 8 2 Actions of the default program .................. 6 8 2 Writing your own EJB event program ............... 6 8 2 Chapter 25. Writing programs to customize Language Environment run-time options for XPLink programs .
Chapter 28. CICS monitoring .................. 7 4 3 Introduction to CICS monitoring .................. 7 4 3 How CICS monitoring data is passed to SMF ............ 7 4 3 Coding additional event-monitoring points ............. 7 4 4 Application naming event monitoring points .
Part 8. Examining and modifying resource attributes ............. 8 0 7 Chapter 33. Using the programmable interface to CEDA ........ 8 0 9 When to use the programmable interface ............... 8 1 0 Using DFHEDAP in a DTP environment ...............
Appendix F . The example program for the XTSEREQ global user exit, DFH$XTSE ......................... 8 7 7 Appendix G. Threadsafe XPI commands .............. 8 9 3 Bibliography ......................... 8 9 5 The CICS T ransaction Server for z/OS library .
xvi Customization Guide.
Preface What this book is about This book provides the information needed to extend and modify an IBM ® CICS ® T ransaction Server for z/OS ® system to match your requirements.
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.
Summary of changes This book is based on the CICS Customization Guide for CICS T ransaction Server for z/OS, V ersion 3 Release 1, SC34-6429-00. Changes from that edition are marked by vertical bars in the left margin.
Changes for CICS T ransaction Server for z/OS, V ersion 2 Release 3 The more significant changes for this edition were: v A new global user exit, XICERES, in the interval EXEC interface control progra.
Part 1. Customizing with user exit programs © Copyright IBM Corp. 1977, 201 1 1.
2 Customization Guide.
Chapter 1. Global user exit programs Y ou 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.
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.
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.
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 .
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.
* (ZERO = NO WORK AREA) UEPGAL DS A ADDRESS OF GLOBAL WORK AREA LENGTH UEPCRCA DS A ADDRESS OF CURRENT RETURN-CODE UEPTCA DS A RESERVED UEPCSA DS A RESERVED UEPEPSA DS A ADDRESS OF REGISTER SAVE AREA .
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.
T able 1. TCB indicators in DFHUEP AR (continued). Description Symbolic value 2-byte code Description UEPTX9 X9 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 .
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. Y ou are strongly advised not to let the return code default to the normal response as the result can be unpredictable.
storage. However , on an EXEC CICS GETMAIN command, the exit program can override the T ASKDA T AKEY option by specifying either CICSDA T AKEY or USERDA T AKEY .
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 LP A=YES is specified as a system initialization parameter , CICS scans the LP A for the program.
– 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 GW A between global user exit programs, thereby making the information it contains available to more than one program, and overcoming limitations on the size of GW As.
v Uses the ST ART option of the EXEC CICS ENABLE command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINKs and XCTLs. v Links to the dummy program, DFH$PCPL, in order to drive DFH$PCEX. v Uses the STOP option of the EXEC CICS DISABLE command to make DFH$PCEX unavailable for execution.
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$DTRD A sample global user exit program, designed to be invoked at the XDTRD exit. DFH$DT AD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data T ables Guide .
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.
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.
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 c.
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.
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.
XPCT A exit, to test whether the abend was caused by a storage protection exception condition. It is described on page “The sample XPCT A global user exit program, DFH$PCT A” on page 191.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic XDT AD Data tables management When a write request is issued to a data table. “Exit XDT AD” on page 43 XDTLC At the completion of loading of a data table.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic XFCBF AIL File control recovery control program When an error occurs during the backout of a UOW . “Exit XFCBF AIL, file control backout failure exit” on page 127 XFCBOUT When CICS is about to back out a file update.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic 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.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic XPCABND Program control program After a transaction abend and before a dump call is made.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic XSZARQ Front End Programming Interface After a FEPI request has completed. “Front End Programming Interface exits XSZARQ and XSZBRQ” on page 137 XSZBRQ Before a FEPI request is actioned.
T able 2. Alphabetical list of global user exit points (continued) Exit name Module or domain Where or when invoked T opic XWBAUTH Web domain 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.
Return codes UERCNORM Continue processing. XPI calls XPI must not be used. API and SPI calls The following commands are supported: v ADDRESS CW A v ADDRESS EIB v LINK (but only to local programs; distributed program links may not be used). v RETURN v WRITE JOURNALNAME.
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$AP AD CICS provides a sample global user exit program, DFH$AP AD, for use at the XAP ADMGR exit point.
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.
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. UEPBMT AB Address of the field element table.
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, BMXDA T A points into a work area which BMS has obtained for input mapping purposes.
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. BMXA TTR 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.
Exit-specific parameters UEPF AREQ Address of a 1-byte field that indicates why the exit has been called. Possible values are: UEPF AIN Initialization. UEPF A TU T idy-up. UEPF A TUT Address of a 1-byte field that indicates the type of tidy-up required.
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.
Note: For additional information about using these exits with CICS shared data table support, see the CICS Shared Data T ables Guide . Related concepts “The data tables sample exit programs” on pa.
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.
XPI calls All can be used. Exit XDT AD The XDT AD user exit is invoked when a write request is issued to a data table. v For a user-maintained data table and coupling facility data table, the user exit is invoked once—before the record is added to the data table.
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.
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.
UERCABDU Abend CICS with a dump. XPI calls TRANSACTION_DUMP must not be used. DBCTL tracking program exits XXDFB and XXDT O Exit XXDFB When invoked By the alternate CICS when it receives a message from the active CICS indicating that connection to DBCTL has failed.
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 T ake no action. UERCSWCH Switch to the alternate DBCTL. UERCABNO Abend CICS without a dump.
XPI calls Must not be used. Exit XDSA WT 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.
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.
UEP APLIST 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.
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.
The general format for PL/I is: plist address --> parm1 address --> parm1 (parmcount) parm2 address --> locator descriptor --> parm2 parm3 address --> locator descriptor --> parm3 .
Return codes UERCNORM Continue processing. UERCPURG T ask 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.
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.
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.
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 T ask purged during XPI call.
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.
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.
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.
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.
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.
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.
non-zero value. T o help you set values for EIBRCODE, EIBRESP , and EIBRESP2, the values used by the enqueue domain are specified in DSECT DFHNQUED. Note: T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when issuing an enqueue request from the XNQEREQC exit.
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. T o obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure.
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.
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.
– 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.
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.
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.
UERCPURG T ask 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 UEP ARG Address of the EXEC command parameter list.
XPI calls All can be used. Exit XEIOUT When invoked After the execution of any EXEC CICS API or SPI command. Exit-specific parameters UEP ARG Address of the EXEC command parameter list. UEPEXECB Address of the system EIB. UEPUSID Address of the 8-character userid.
Exit-specific parameters UEP ARG Address of the EXEC command parameter list. UEPEXECB Address of the system EIB. UEPUSID Address of the 8-character userid. UEPPGM Address of the 8-character application program name. UEPLOAD Address of the application program's load-point.
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.
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.
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.
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, ST ART 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.
UEP_FC_DUPLICA TE_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_DUPLICA TE KEY v UEP_FC_NO.
v UEP_FC_REASON_DUPLICA TE_RECORD v UEP_FC_REASON_DUPLICA TE_REQID v UEP_FC_REASON_END_OF_FILE v UEP_FC_REASON_FILE_DISABLED v UEP_FC_REASON_FILE_NOT_OPEN v UEP_FC_REASON_FILE_NOT_FOUND v UEP_FC_REASO.
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 T ask purged during XPI call. XPI calls All can be used. API and SPI calls None can be used.
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_KEY VSAM KSDS or AIX P A TH 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, ST ART BR, and RESET BR requests o.
UEP_FC_CR Consistent read integrity . UEP_FC_FCT_V ALUE 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 T OKEN.
UEP_FC_REASON Address of a 1-byte area containing, if the request completed with an EXCEPTION response, the reason. The possible reasons are: v UEP_FC_REASON_ABEND v UEP_FC_REASON_ACCMETH_REQUEST_ERRO.
v UEP_FC_REASON_NOT AUTH v UEP_FC_REASON_NOT_EXTENDED v UEP_FC_REASON_PREVIOUS_RLS_F AILURE v UEP_FC_REASON_RBA_ACCESS_TO_RLS_KSDS v UEP_FC_REASON_READ_NOT_AUTHORISED v UEP_FC_REASON_READPREV_IN_GENER.
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.
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.
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'04' MASSINSERT specified. X'02' RRN specified. X'01' SET (and not INT O) was specified. Note: Y our program must test for keywords at the bit level, because there may be more than one of these keywords present. FC_EIDOPT6 Indicates whether certain keywords that do not take values were specified on the request.
X'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).
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: Y ou must never modify an input field by altering the data that is pointed to by the command-level parameter list.
X'04' REPEA T ABLE specified. X'02' UPDA TE 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. Y ou should not modify the pointer to the EID: any attempt to do so is ignored by CICS.
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 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 INT O area.
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.
‘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).
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.
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.
Note: T ake 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.
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.
v FCIS_BITS4 v FCIS_BITS5 v FCIS_BITS6 v FCIS_BITS7 v 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.
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_ADDR1 1 is meaningful. X'10' Set if the request contains an argument for the DISPOSITION 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.
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 T ABLENAME keyword. X'01' Set if the request contains the UPDA TEMODEL keyword.
FCIS_ADDR15 is the address of a 4-byte area containing the CVDA from ENABLEST A TUS. FCIS_ADDR16 is the address of a 4-byte area containing the CVDA from RECOVST A TUS. FCIS_ADDR17 is the address of a 4-byte area containing the CVDA from ACCESSMETHOD.
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.
T able 5. INQUIRE FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Data T ype Input/Output Arg16 RECOVST A TUS BIN(31) Outp.
T able 6. SET FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Data T ype Input/Output Arg2 DSNAME CHAR(44) Input Arg3 FWDR.
Note: Y ou must never modify an input field by altering the data that is pointed to by the command-level parameter list. T o do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field.
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 W AIT 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.
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.
UEFJRU Journal read for update UEFJWU Journal write update UEFJW A 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 .
UEF ACBCP 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 .
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.
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 UEF ADDIM Add valid UEFDELIM Delete valid UEFBRZIM Browse valid.
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.
UEPFBCAS Data set marked unavailable. UEF ACBCP 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 UEF ACBCP is undefined.
UERCPURG T ask 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. T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when a file control request is issued from the XFCSREQC exit.
associated with the file, as described by fields UEFLNAME and UEDSNAME in the DFHUEFDS DSECT . 3. Issues a WRITE OPERA TOR 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.
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. T o provide a means of selecting which mismatches to accept and which to reject, three parameters are passed to the exit.
Exit XFCVSDS When invoked Invoked after VSAM RLS has informed CICS that processing is required as a result of a data set-related action occurring in the sysplex.
CICS is not to carry out the processing required for the VSAM RLS action, and is to cancel the action throughout the sysplex. A return code of UERCPURG is not allowed. XPI calls All can be used. API and SPI calls Y ou can use CICS API and SPI commands at this exit.
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.
File control recovery program exits XFCBF AIL, XFCBOUT , XFCBOVER, and XFCLDEL CICS provides four global user exits that you can use in connection with file control recovery operations. These are: XFCBF AIL Invoked when an error occurs during backout.
point; the TBEXITS parameter allows only one exit program at each exit point. PL TPI processing is described in Chapter 4, “Writing initialization and shutdown programs,” on page 425. Exit XFCBF AIL, file control backout failure exit XFCBF AIL 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.
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.
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.
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 .
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 T ransaction Server for z/OS, V ersion 3 Release 2).
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 .
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.
– 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.
UEPFLEN Address of a fullword containing the length of the data in the file control request. Return codes UERCF AIL 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.
– 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.
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).
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.
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.
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.
Note that this exit is invoked only if the request to be shipped is of type EXEC CICS ST ART NOCHECK. For EXEC CICS requests other than those with the NOCHECK option (which is only available on ST ART commands) the ‘SYSIDERR’ condition is raised in the application program.
UERCPURG T ask 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 .
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.
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 “‘T erminal not known’ condition exits XAL TENF and XICTENF” on page 224.
v For dynamically-routed transactions —only dynamically-routed (non-terminal-related) ST ART requests cause the exit to be invoked. Thus, a dynamically-routed transaction that was initiated by a terminal-related EXEC CICS ST ART command does not cause the exit to be invoked.
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.
EXEC CICS SHUTDOWN EXEC CICS XCTL Note: T ake care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when an interval control request is issued from the XICEREQ exit. Use of the recursion counter UEPRECUR is recommended.
UERCNORM Continue processing. UERCPURG T ask 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.
UEPDA TE Address of a fullword copy of the EIB date value, EIBDA TE. 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 command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a 9-byte area that describes the type of request and identifies each keyword specified with ADDR0 .
the request. The remaining addresses point to pieces of data associated with the request. For example, the second address points to the interval for ST ART requests. Y ou can examine the EID to determine the type of request and the keywords specified.
IC_GROUP X'10' This is an interval control request. X'4A' This is an ASKTIME or FORMA TTIME command. IC_FUNCT One byte that defines the type of request.
X'80' Set if the request specifies RTERMID, or if a FORMA TTIME request specifies DA TESEP . 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.
X'04' YEAR was specified on a FORMA TTIME command, or MINUTES was specified. X'02' TIME was specified on a FORMA TTIME command, or PROTECT was specified. X'01' TIMESEP was specified on a FORMA TTIME command, or NOCHECK was 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 DELA Y , POST or ST ART). v A halfword containing the value of LENGTH (if the request is RETRIEVE). W arning: For requests that specify INTO, do not change the value of LENGTH to a value greater than that specified by the application.
v A fullword containing the value of DA YCOUNT . 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 DA YOFWEEK. IC_ADDRC is the address of one of the following: v An area containing the value of MINUTES.
The following are always input fields: v INTERV AL v TIME v REQID v FROM v TERMID v SYSID v HOURS v MINUTES v SECONDS v USERID v CHANNEL The following are always output fields: v DA TE v DA TEFORM v D.
ABSTIME is an input field on a FORMA TTIME request, and an output field on an ASKTIME request. DA TESEP and TIMESEP can be input fields on a FORMA TTIME request.
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_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: Y our user exit program is prevented from making major changes to the EID.
1. Scan the global work area (GW A) to locate a suitable CICS region (for example, the region currently processing the least number of ST ART requests). 2. Having decided which system to route the request to, increment the use count for this system. 3.
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.
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. UEPENTR Y Address of a 4-byte field containing the address of the program’s entry point.
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 .
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.
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.
Note: T o 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.
Important Because of the danger of recursion, your XMEOUT exit program should not try to reroute: v Any DFHTDxxxx messages, produced by the transient data program. v User domain messages in the range DFHUS0002 - DFHUS0006, plus message DFHUS0150. v T ransaction manager messages DFHXM0212, DFHXM0213, DFHXM0304 and DFHXM0308.
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.
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.
DFH$SXP5 Reroute a TDQ message to another TDQ DFH$SXP6 Reroute a TDQ message to a console. Related concepts “The message domain sample exit programs” on page 23 Monitoring domain exit XMNOUT XMNOU.
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).
UERCNORM Continue processing. UERCBYP Suppress monitor record output. UERCPURG T ask purged during XPI call. XPI calls W AIT_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.
UEP AP ABN (X'40') The Web service provider application completed its processing successfully . UEP APSF A 1-byte field indicating if the Web service provider application set a SOAP fault. V alid values are as follows: UEP APSFY (X'80') The Web service provider application is returning a SOAP fault.
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.
2. Reinvoke the routing program, on the routing region, for route selection failure. 3. Return a RESUNA V AIL condition on the EXEC CICS LINK command executed by the mirror on the target region. (This condition is not returned to the application program.
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 T oken. An exit program can use this token to access information (such as the service class token, SERVCLS) in the WLM Performance Block.
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.
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 .
UERCPURG T ask purged during XPI call. XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.
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_AD.
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_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.
Bits in the EID should be modified in place. Y ou should not modify the pointer to the EID. (Any attempt to do so is ignored by CICS.) The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the program control request only .
1. Scan the global work area (GW A) to locate a suitable CICS region - for example, the region currently processing the least number of LINK requests. 2.
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.
address. Set the top bit to specify that the alternative program is to run AMODE (31). PCUE_REAL_ENTR Y From z/OS 1.7 onwards, this field provides the real entry point for Language Environment conforming programs.
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.
XPI calls All can be used. Exit XPCT A XPCT A is invoked immediately after a transaction abend, and before any processing that might modify the existing environment so that the task could not be resumed. Y ou can use it to: v Set a resume address, instead of letting CICS process the abend v Specify the subspace that control is passed in.
PCUE_LOGICAL_LEVEL Fullword containing the number of chained DFHRSADS blocks (that is, logical level). PCUE_BRANCH_ADDRESS Fullword. Y ou can use this field to supply a resume address. Set the top bit to specify that the resumed task is to run AMODE (31).
DFH$PCT A 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.
UERCBYP Suppress the dump call. UERCPURG T ask 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.
UERCNORM Continue processing. UERCPURG T ask 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.
Return codes UERCNORM Continue processing. UERCPURG T ask 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.
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.
UEIDDB2E A DB2 entry (DB2ENTRY) UEIDDB2T A DB2 transaction (DB2TRAN) UEIDDJAR A deployed JAR file (DJAR) UEIDDOCT A DOCTEMPLA TE UEIDFECO A FEPI connection UEIDFENO A FEPI node UEIDFEPO A FEPI pool UE.
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.
UERCPURG T ask purged during XPI call. XPI calls Y ou 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.
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: T able 8. Flags set in the UEPSNFLG field of XSNON Flag Equivalent Meaning UEPSNOK 0 Signon was successful.
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 T imeout sign-off. Return codes UERCNORM Continue processing. UERCPURG T ask purged during XPI call.
T o use this program, add an entry to the first section of your PL TPI table (that is, before the DFHDELIM statement). For example: DFHPLT TYPE=INITIAL,SUFFIX=SN DFHPLT TYPE=ENTRY,PROGRAM=DFH$SNPI DFH.
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. UEPSDA TE Address of a 6-byte character field containing the collection date (MMDDYY).
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_CICS_ERROR_REASON 4-character field containing the MVS abend reason code. It contains a value only if flag SRP_V ALID_REASON is set. SRP_CICS_ERROR_DA T A An area describing the last thing that CICS did, prior to the abend.
2. The format of SRP_ERROR_DA T A 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’.
XPI calls All other XPI calls except WRITE_JOURNAL_DA T A 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_DA T A_P Address of a fullword containing the address of the data. (Write and rewrite requests). UEP_TS_DA T A_L Address of a fullword containing the length of the data. (Write and rewrite requests).
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 .
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.
Return codes UERCNORM Normal. UERCPURG T ask purged during XPI call. XPI calls All can be used. API and SPI calls None can be used. Exit XTSPTOUT When invoked After execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or BMS queues).
v UEP_TS_RESPONSE_EXCEPTION v UEP_TS_RESPONSE_DISASTER v UEP_TS_RESPONSE_INV ALID Return codes UERCNORM Normal response. UERCPURG A purged response was received from an XPI 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.
Note: T ake care when issuing recursive commands. For example, you must avoid entering a loop when issuing a temporary storage request from the XTSEREQ exit.
UERCPURG T ask 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 Y ou can update the copies of EIBRSRCE, EIBRCODE, EIBRESP , and EIBRESP2 that you are given in the parameter list.
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: T able 9.
X'02' Set if the request contains an argument for the SYSID keyword. If set, TS_ADDR7 is meaningful. TS_BITS2 T wo bytes not used by temporary storage. TS_EIDOPT5 Indicates whether certain keywords were specified on the request. X'80' QNAME was specified (otherwise QUEUE).
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.
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.
T able 1 1. 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 SE.
1. Obtain storage for the argument to be added 2. Initialize the storage to the required value 3. Select and set up the appropriate pointer from the parameter list 4. Select and set up the appropriate argument existence bit in the EID 5. Modify the parameter list to reflect the new end of list indicator .
UEP ALLEN 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 ST ART request without a FROM option. v The AID is associated with a channel (in which case the field pointed to by UEP ALCHN will be set to a name other than blanks).
Note: The XAL TENF exit, used to handle the “terminal not known” condition, is also invoked from the terminal allocation program. XAL TENF is described on page “‘T erminal not known’ condition exits XAL TENF and XICTENF” on page 224.
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 XTCA TT When invoked Before task attach. Exit-specific parameters UEPTCTTE Address of the terminal control table terminal entry (TCTTE).
in the local system. If the requested terminal is remote, the terminal allocation program ships an A TI request to the remote system, which initiates transaction routing back to the local system. For guidance information about A TI, refer to the CICS Intercommunication Guide .
UERCNETN Netname of T OR returned UERCSYSI Sysid of T OR 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).
UEP AL TRN Address of 4 bytes containing the name of the transaction to be run. UEP ALRTR 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 T OR to which it directs the A TI request is a member of a VT AM generic resource. Return codes UERCTEUN T erminal unknown, reject request. UERCNETN T erminal known, netname returned in UEP ALNTO.
UEPICFN A ST ART command was not being processed or aS T A R T 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.
run. It is important that your exit program supply a terminal netname if the T OR to which it directs the A TI request is a member of a VT AM generic resource. Return codes UERCTEUN T erminal unknown, reject request. UERCNETN T erminal known, netname returned in UEPICNTO.
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.
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 T ransaction manager domain exit XXMA TT Exit XXMA TT When invoked During transaction attach.
transaction specified on DTRTRAN is attached and CICS considers that the transaction has been found. Equated values are: UEA TFND The transaction was found. UEA TNFND The transaction was not found. UEP A TTST The address of a 1 byte transaction definition state.
When the task being attached is for a task started by an immediate ST ART command; that is, a ST ART without an interval, the current task is the task that issues the ST ART command, and the fields contain values associated with that task. T ransient data program exits XTDREQ, XTDIN, and XTDOUT Exit XTDREQ When invoked Before request analysis.
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.
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 T ask purged during XPI call. XPI calls Y ou can use: v INQ_APPLICA TION_DA T A v INQUIRE_SYSTEM v W AIT_MVS Do not use any other calls .
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.
Note: T ake care when issuing recursive commands. For example, you must avoid entering a loop when issuing a transient data request from the XTDEREQ exit.
UERCNORM Continue processing. UERCPURG T ask purged during XPI call. XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.
Y ou can examine the EID to determine the type of request and the keywords specified. Y ou can examine the other parameters in the list to determine the values of the keywords. Y ou can also modify values of keywords specified on the request. (For example, you could change the sysid specified in the request.
X'04' READQ X'06' DELETEQ. TD_BITS1 Existence bits that define which arguments were specified. T o obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit.
TD_ADDR4 is the address of a value intended for CICS internal use only . It must not be used. TD_ADDR5 is the address of a value intended for CICS internal use only . It must not be used. TD_ADDR6 is the address of a value intended for CICS internal use only .
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. Y ou can treat such fields in the same way as output fields, and they are considered to be the same.
Y ou can update the copies of EIBRSRCE, EIBRCODE, EIBRESP , and EIBRESP2 that you are given in the parameter list. T ransient data copies your values into the real EIB after the completion of XTDEREQC; or if you specify a return code of ‘ bypass’ in XTDEREQ.
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 .
name6 are the names of your user exit programs for XRCINIT , XRCINPT , XFCBF AIL, XFCLDEL, XFCBOVER, and XFCBOUT . v Enable the exits during the first stage of initialization using a PL TPI program. If you use the TBEXITS parameter to enable the exits, a global work area of 4 bytes is provided.
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.
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 (A TI).
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). Y our exit program should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
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.
Using the information passed in the parameter list, your global user exit program can decide (based on queue length, for example) whether CICS is to queue the allocate request. Y our program communicates its decision to CICS by means of one of the return codes CICS provides.
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.
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.
UEPP AD A 1-byte padding field. UEPFSPL Address of the 10-byte function shipping parameter list. UEPCONST Address of the 158-byte system entry statistics 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.
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.
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 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.
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.
Exit-specific parameters UEPISDA T A Address of the 78-byte area containing the information listed below . This area is mapped by the DSECT in copybook DFHXIQDS. Area addressed by UEPISDA T A: UEPREQ A 2-byte origin-of-request code, which can have the following value: FS Function shipping (includes distributed program link.
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.
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 . T o 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.
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.
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.
v A predatory takeover . A “predatory takeover” can occur , if you are using VT AM Release 3.4.0 or above, and a VT AM application with the same APPLID as that of the executing CICS system assumes control of all the sessions of the executing CICS system.
v For XRF , in the event of a VT AM failure: CICS continues processing as if the exit program had not been invoked. v For VT AM persistent sessions, in the event of a predatory takeover: CICS abends without a dump. UERCCOIG Ignore. UERCABNO Abend CICS without a dump.
266 Customization Guide.
Chapter 2. T ask-related user exit programs This chapter describes a special kind of user exit called a task-related user exit (TRUE) . The chapter is divided into the following sections: 1. “Introduction to the task-related user exit mechanism (the adapter)” 2.
The task-related user exit program is provided with a parameter list (DFHUEP AR) by the CICS management module that handles task-related user exits. This parameter list gives the task-related user exit access to information such as the addresses and sizes of its own work areas.
The 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).
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.
W riting 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 .
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.
v The address of the kernel stack entry v The address of the APPC unit of work (UOW) identifier v The address of the user security block flag v The address of the user security block v The address of .
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.
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.
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 DFHUEP AR as both a two-character code and a symbolic value, as follows: T able 13.
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.
Caller parameter lists In addition to the DSECT s DFHUEP AR 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.
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 .
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.
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 UER TBACK. 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.
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 .
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 Application Syncpoint Task manager Termination manager call Context management call CICS EDF call call program call manager call call DFHUEPAR DFHUEPAR DFHUEPAR DFHUEPAR UEPEXN UEPEXN UEPEXN .
The schedule flag word The schedule flag word is a fullword indicator that the task-related user exit program uses to control its own invocation. It is also used by CICS to schedule the first invocation of a task-related user exit program. The schedule flag word is accessed by the address parameter UEPFLAGS of DFHUEP AR.
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 .
The calling program’ s registers The calling program’s registers are stored at the address specified by UEPHMSA of DFHUEP AR. 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.
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.
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.
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.
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 (TW A, TW ACOBA) that is exclusively for the exit program’s use.
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.
manager ’s parameter list and the TRUE return codes. (The CICS syncpoint manager parameters are described in “CICS syncpoint manager parameters” on page 279.
As described in “Increasing efficiency – single-update and read-only protocols” on page 294, if the UERT ONL Y bit is set (indicating that the resource manager is the only one to have updated resources) the exit program should cause the resource manager to perform a single-phase commit.
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.
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.
CICS abend, retry possible, TCBs dispatchable (UERTCABY) MVS has flagged the failure as being “eligible for retry”. Y our exit program must follow the MVS rules for this type of failure, documented in the OS/390 MVS Authorized Assembler Services Guide .
JTRUE1A CSECT TERMINATION TRUE ENTRYPOINT STM 14,12,12(13) Save registers USING JTRUE1A,R3 LR R3,R15 Use R3 as base register USING DFHUEPAR,R1 Address DFHUEPAR parameter list L R2,UEPEXN USING DFHUERT.
Using EDF with your task-related user exit program If your exit program sets the EDF bit in the schedule flag word and EDF is active, the exit program is invoked before and after each API request to format screens for EDF to display . Communication between the task-related user exit and EDF is controlled by the task-related user exit interface.
T able 16 describes each stage of the interface between the task-related user exit and EDF , relating the descriptions to the (T n ) and (E n ) expressions in Figure 1 1. T able 16. Description of each stage of the task-related user exit/EDF interface Invocation Description (T1) T ask-related user exit invoked to set up its EDF requirements.
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.
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.
Chapter 3. The user exit programming interface (XPI) This chapter describes the user exit programming interface (XPI) of CICS T ransaction Server for z/OS, V ersion 3 Release 2. It is divided into the following sections: v “Overview of the XPI” is an introduction to the XPI.
– Release all storage held by the SEARCH_LDAP function—see “The FREE_SEARCH_RESUL TS call” on page 324. v Using the XPI dispatcher functions, you can: – Obtain a suspend token for a task—s.
– 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_.
– 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.
mandout2(value), ... [optout1(value),] [optout2(value),] ... RESPONSE, REASON] XPI calls follow assembler-language coding conventions: v The “macro-name” must begin before column 16.
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.
DFHxxyyX. Y ou 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 .
If a DFHDSSRX SUSPEND or W AIT_MVS call does not specify an INTERV AL, and gets this RESPONSE with a REASON of ‘T ASK_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 .
The XPI copy books There is a copy book for each XPI function, to provide the DSECT s associated with that function. These DSECT s allow you to map the parameters and the response and reason codes of an XPI call. Y ou must include in your exit program a COPY statement for each XPI function that you are going to use.
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.
TITLE ’GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI’ ************************************************************************* * The first three instructions set up the global user exit * * environm.
************************************************************************** * 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.
An example showing how to build a parameter list incrementally In the following example, the parameter list is built incrementally . The initialization of the parameter list (using the CLEAR option), the building of the parameter list, and the GETMAIN call are separated into discrete steps.
OUT, * ADDRESS((R6)), * RESPONSE(*), * REASON(*) Important Y ou 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.
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 fullwor.
(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 .
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.
RESPONSE REASON KERNERROR None PURGED None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The END_BROWSE_RESUL TS call The END_BROWSE_RESUL TS call allows you to end the browse session that was started by the ST ART_BROWSE_RESUL TS call.
[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 REASON INV ALID None KERNERROR None PURGED None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The GET_A TTRIBUTE_V ALUE call The GET_A TTRIBUTE_V ALUE call allows you to retrieve the value associated with an attribute returned by the SEARCH_LDAP call.
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.
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_A TTRIBUTE: RESPONSE REASON OK N.
SEARCH_TOKEN(name4) the name of the fullword token that is returned by the SEARCH_LDAP function. RESPONSE and REASON values for GET_NEXT_ENTR Y : RESPONSE REASON OK None EXCEPTION INV ALID_TOKEN INV A.
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.
[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.
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.
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).
Because task-purging is effective only if performed between SUSPEND and RESUME, Suspend-fail precedes Resume-fail. This means that, with the same constraints on serialization as in the normal synchronization protocol, the task-purge protocol can be logically reduced to: The difference is that Set results and Get results are replaced by Clean up.
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(na.
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 REASON OK None EXCEPTION None DISA.
depends on the setting of the TIME_UNIT option. The INTERV AL 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.
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.
IO W aiting on an I/O operation or indeterminate I/O-related operation (locks, buffer , string, and so on). LOCK W aiting on a lock. MISC W aiting 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_W AIT_TYPE parameter .
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.
2. ‘T ASK_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.
Note: ECBs used in W AIT_MVS requests must never be “hand posted”. They must be posted using the MVS POST macro. W AIT_MVS DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(WAIT_MVS), {ECB_ADDRESS(name4 | (.
T able 18. WAIT_MVS call - RESPONSE(PURGED) (continued) CONDITION PURGE FORCEPURGE DTIMOUT INTERV AL PURGEABLE (NO) Canceled Proceeds normally Canceled Proceeds normally PURGEABLE (YES) Proceeds norma.
MILLI_SECOND The INTERV AL 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 .
RESPONSE and REASON values for W AIT_MVS: RESPONSE REASON OK None EXCEPTION None DISASTER None INV ALID None KERNERROR None PURGED T ASK_CANCELLED TIMED_OUT Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
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.
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.
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.
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.
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.
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(DISP A TCHER_T ASK) is required and specifies that all XPI enqueues are owned by the requesting dispatcher task.
The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, and MAX_LIFETIME(DISP A TCHER_T ASK) parameters are the same as in the ENQUEUE function call. RESPONSE and REASON values for DEQUEUE RESPONSE REASON OK.
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.
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.
T able 19. Summary of attributes defining DSA eligibility (continued) EXECUTION_KEY option Reentrant Above or below 16MB line Dynamic storage area (DSA) CICS Y es Below RDSA CICS No Above ECDSA CICS Y.
PRIV A TE The program is in the DFHRPL or dynamic LIBRARY concatenation. A PRIV A TE program need not be reentrant, and is given only limited protection from unauthorized overwriting.
RESPONSE REASON CA T ALOG_NOT_OPERA TIONAL DISASTER None INV ALID None KERNERROR None PURGED None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
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.
RESPONSE and REASON values for ACQUIRE_PROGRAM: RESPONSE REASON OK None EXCEPTION NO_STORAGE PROGRAM_NOT_DEFINED PROGRAM_NOT_FOUND DISASTER None INV ALID None KERNERROR None PURGED None Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
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.
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 REASON INV ALID None KERNERROR None The SET_P ARAMETERS call SET_P ARAMETERS allows you to set the activity keypoint frequency for the CICS region. SET_P ARAMETERS DFHLGPAX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PARAMETERS), [KEYPOINT_FREQUENCY(name4 | (Rn) ),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
INQUIRE_MONITORING_DA T A 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 MONIT OR call The MONITOR XPI call is similar to the EXEC CICS MONIT OR command.
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 .
"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’.
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.
Program management XPI functions There are eight XPI program management functions. These are the DFHPGISX calls: INQUIRE_PROGRAM INQUIRE_CURRENT_PROGRAM SET_PROGRAM ST ART_BROWSE_PROGRAM GET_NEXT_PROG.
[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|REM.
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.
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 .
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.
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.
NOT_APPLIC Not applicable. The program is remote. PRIV A TE The program is to be loaded from the DFHRPL or dynamic LIBRARY concatenation.. A PRIV A TE program need not be reentrant, and is given only limited protection against unauthorized overwriting.
RESPONSE and REASON values for INQUIRE_PROGRAM: RESPONSE REASON OK None EXCEPTION PROGRAM_NOT_DEFINED_TO_LD PROGRAM_NOT_DEFINED_TO_PG DISASTER ABEND LOCK_ERROR INV ALID INV ALID_PROGRAM_TOKEN KERNERRO.
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.
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.
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),] [E.
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.
TYPE_ANY Either the copy in the DFHRPL or a dynamic LIBRARY concatenation, or the LP A copy of the program can be used, though preference is given to the LP A copy . PROGRAM_USAGE(APPLICATION|NUCLEUS) specifies whether the program is used as a CICS nucleus program or as a user application program.
The ST ART_BROWSE_PROGRAM call ST ART_BROWSE_PROGRAM returns a token that enables you to begin browsing through program definitions, optionally starting at the definition of a specified program.
The GET_NEXT_PROGRAM call GET_NEXT_PROGRAM allows you to inquire on the next program definition during a browse sequence initiated by ST ART_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. Y ou can use it in the BROWSE_TOKEN field of your next GET_NEXT_PROGRAM call (or END_BROWSE_PROGRAM call, if you want to end the sequence). Y ou can also use it in the PROGRAM_TOKEN field of INQUIRE_PROGRAM and SET_PROGRAM calls.
The INQUIRE_AUTOINST ALL call INQUIRE_AUTOINST ALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets.
SET_AUTOINST ALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_AUTOINSTALL), [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] [LANGUAGES_AVAILABLE(NO|YES),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
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_APPLICA TION_DA T A call The INQ_APPLICA TION_DA T A call enables you to inquire on application system data in the AP domain.
* The parameter list itself, in name APIQ_EIB, is used to hold the address. RSA(name4 | (R n|*) 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.
name4 The name of a 4-byte area that is to receive the length, in bytes, of the TW A. (Rn) A register that is to receive the length of the TW A. * The parameter list itself, name APIQ_TW ASIZE, is used to hold the length of the TW A.
[TIMEOFDAY(name4| *),] [XRFSTATUS(NOXRF | PRIMARY | TAKEOVER),] RESPONSE (name 1|*) , REASON (name 1|*) ] 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.
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, 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.
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.
RESPONSE REASON INV ALID INV ALID_FUNCTION EXCEPTION LENGTH_ERROR UNKNOWN_DA T A DISASTER INQ_F AILED PURGED None The SET_SYSTEM call The SET_SYSTEM call allows you to set CICS system data values in the AP domain.
RESPONSE and REASON values for SET_SYSTEM: RESPONSE REASON OK None INV ALID INV ALID_FUNCTION EXCEPTION AKP_SIZE_ERROR NO_KEYPOINT DISASTER SET_F AILED PURGED None Storage control XPI functions There are seven XPI storage control functions.
GETMAIN DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION(GETMAIN), GET_LENGTH(name4 | (Rn) | expression), STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL), S.
STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL) specifies the class of the storage that is the subject of the call. The values you can assign to this option, and the type of storage each represents, are listed in T able 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.
[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_ONL Y Readonly storage USER User-key . ELEMENT_ADDRESS(name4 | (Rn) | *) specifies the address of the storage element.
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 .
RESPONSE and REASON values for INQUIRE_SHORT_ON_STORAGE: RESPONSE REASON OK None DISASTER None KERNERROR None The INQUIRE_T ASK_STORAGE call INQUIRE_T ASK_STORAGE enables you to request details of all elements of task-lifetime storage belonging to a task.
RESPONSE REASON NO_TRANSACTION_ENVIRONMENT DISASTER None INV ALID None KERNERROR None PURGED None The SWITCH_SUBSP ACE call SWITCH_SUBSP ACE 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.
The TRACE_PUT call TRACE_PUT writes a trace entry to the active trace destinations. Y ou should only make a TRACE_PUT call when UEPTRON indicates that tracing is active for the function containing the exit program (see UEPTRON in DFHUEP AR). Y ou 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.
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 ST ART BREXIT TRANSID command to start this transaction. If CONTEXT returns NORMAL, the contents of this field are meaningless.
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.
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.
The INQUIRE_TCLASS call The INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Its purpose is to provide current information about the specified transaction class (TCLASS).
name4 The name of a 4-byte location that is to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value. (Rn) A register to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value.
[SHUTDOWN(name1),] [SPURGE(name1),] [STATUS(name1),] [STORAGE_CLEAR(name1),] [STORAGE_FREEZE(name1),] [SYSTEM_ATTACH(name1),] [SYSTEM_RUNAWAY(name1),] [TASKDATAKEY(name1),] [TASKDATALOC(name1),] [TCLA.
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.
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 .
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.
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 ST ART command, it will be routed using the enhanced routing 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 T ask-lifetime storage need not 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 .
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.
[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.
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.
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 ST ART command without any data.
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.
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.
WRITE_JOURNAL DA T A DFHJCJCX [CALL,] [CLEAR,] [IN, FUNCTION(WRITE_JOURNAL_DATA), FROM(block-descriptor), JOURNALNAME(name8 | string | ’string’ ) | JOURNAL_RECORD_ID(name2 | string | ’string’), WAIT(YES|NO), [RECORD_PREFIX(block-descriptor),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
RESPONSE REASON JOURNAL_NOT_OPEN LENGTH_ERROR ST A TUS_ERROR DISASTER None INV ALID None KERNERROR None PURGED None Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308.
422 Customization Guide.
Part 2. Customizing with initialization and shutdown programs © Copyright IBM Corp. 1977, 201 1 423.
424 Customization Guide.
Chapter 4. W riting initialization and shutdown programs Y ou can write programs to run during the initialization and shutdown phases of CICS processing. Any program that is to run at these times must be defined to CICS in a program list table (PL T).
v First phase PL TPI programs must not enable any task-related user exit program with the T ASKST ART option. v Because first-phase PL T programs run so early in CICS initialization, no resource definitions are available.
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.
W riting shutdown programs Any program that is to execute during CICS shutdown must be defined in a program list table (PL T), and the PL T must be named on the program list table shutdown (PL TSD) system initialization parameter .
to be started, and they cannot communicate with terminals. Further , second phase PL T programs must not cause any resource security checking or DB2 calls to be performed. If a transaction abend occurs while the PL TSD program is running, CICS is left in a permanent wait state.
program causes the relevant unit of work to be shunted. The PL TPI program abends ASP1, and CICS runs the next program defined in the PL TPI table, if any . v PL TSD programs run under the transaction that issued the PERFORM SHUTDOWN command. The CEMT transaction is defined with WAIT(YES).
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 PL T . 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. 1977, 201 1 433.
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 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 .
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 .
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 .
Chapter 6. W riting 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 .
v The program status word (PSW) at the time of the (current) abend, at PEP_COM_PSW . The full contents of PEP_COM_PSW are significant for abend codes ‘ASRA ’, ‘ASRB’, and ‘ASRD’ only; the last four characters (the PSW address) apply also to code ‘AICA ’.
DFHEISTG DSECT , * * Insert your own storage definitions here * DFHPCOM TYPE=DSECT *********************************************************************** ***** PROGRAM ERROR ***** ***** PROGRAM *****.
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 code.
The sample program error programs T wo source-level versions of the default program are provided: DFHPEP , coded in assembler language, and DFHPEPD, coded in C. Both are in the 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.
444 Customization Guide.
Chapter 7. W riting 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.
v The transaction abend which caused the transaction to be terminating abnormally must have been detected before the commit point of the implicit syncpoint at the end of the transaction has been reached. v The transaction must be defined as restartable in its transaction definition.
The 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.
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 .
Chapter 8. W riting 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 .
version of the terminal error program (DFHTEP , either CICS-supplied or user-written), so that it can take the appropriate action. T erminal control program When the terminal from which the error was .
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 T ACLE v Indicate the course of action to be taken on return to DFHT ACP . Before giving control to DFHTEP , DFHT ACP establishes which default actions should be taken.
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 DFHT ACP default actions.
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 ST A TUS ELEMENT FORMA T”.
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.
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.
Sample terminal error program messages The messages logged to the transient data destination CSMT (or , optionally , to the destination specified in the OPTIONS operand of DFHTEPM TYPE=INITIAL) are of six types, each identified by a unique message prefix.
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.
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.
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 INST ALL GROUP(DFHST AND) command.
TYPE=INITIAL establishes the beginning of the generation of the sample DFHTEP module itself. DSECTPR={YES|NO} controls the printing of CICS DSECT s on the sample DFHTEP assembly listing. Its purpose is to reduce the size of the listing. The default is DSECTPR=YES.
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.
TACLE|NOTACLE specifies whether the T ACLE prefix is to be recorded on the transient data destination. TACLE The 16-byte T ACLE prefix as received from DFHT ACP is logged. NOTACLE No T ACLE prefix logging occurs. ESE|NOESE specifies whether the ESE associated with the error is to be recorded on the transient data destination.
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.
DFHTEPT–generating the sample DFHTEP tables The following macros are required to generate the terminal error program tables: v DFHTEPT TYPE=INITIAL—to establish the control section. v DFHTEPT TYPE=PERMTID—to define permanently reserved terminal error blocks (TEBs) for specific terminals.
DFHTEPT TYPE=INITIAL–establishing the control section The DFHTEPT TYPE=INITIAL macro necessary to establish the control section for the TEP tables is: TYPE=INITIAL establishes the beginning of the generation of the TEP tables.
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.
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 DFHT ACP default actions.
T able 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.
DFHTEPT TYPE=FINAL–terminating DFHTEPT entries The DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEP tables. DFHTEPT–examples of how the macros are used 1.
W riting your own terminal error program Y ou 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 T able 24.
Addressing the contents of the communication area After your terminal error program receives control from DFHT ACP , it should obtain the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command. Y ou generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program.
ABORTWR (X'08') Abend write, free terminal storage REL TTIOA (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 DFHT ACP .
and DFHT ACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message to CSMT ; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or , rarely , ‘AEXZ’. v Abend write has no effect if the TCTTE was associated with a READ request.
After you have carried out the required functions and, optionally , altered the default actions scheduled by DFHT ACP , the user-written DFHTEP must return control to DFHT ACP by issuing the EXEC CICS RETURN command. DFHT ACP then performs the actions specified in the T ACLE and causes the error processing task to terminate.
Example of a user-written terminal error program The “DFHTEP recursive retry routine” on page 476 is an example of the logic steps necessary to design a portion of the terminal error program. In Figure 28 on page 477, 10 retries are provided for each terminal; however , the logic could be used for any number of retries.
(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).
*ASM XOPTS(NOPROLOG NOEPILOG SP) ************************************************************************ * * * DFHTEP RECURSIVE RETRY ROUTINE * * * ***************************************************.
Note that the code in Figure 28 on page 477 is intended only as an illustration of a recursive error handling technique and of the steps necessary to establish addressability to the applicable control blocks.
Chapter 9. W riting 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 .
Background to CICS-VT AM error handling In general, errors detected by CICS-VT AM terminal control are queued for handling by a special task, the CICS node error handler (transid CSNE).
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.
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 .
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 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 dif ferent handling.
Y ou 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. Y ou 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.
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 .
********************************************************************** ** VTAM information - Any VTAM sense and RPL codes ** ** These fields are READ ONLY ** ******************************************.
The next sections describe fields in the parameter list that can be reset within DFHZNEP . See also “Coding for the 3270 ‘unavailable printer ’ condition” on page 506, which describes the use .
causes CICS to take a system dump when there is no task attached to the terminal at the time of error detection, if the flag TW AOA T in TWAOPT2 is also set on. Setting the TW AONQN flag causes the network qualified name to be printed after any message that contains the action flag.
“good morning” message transaction is initiated (the transaction specified by the system initialization parameter GMTRAN). The flags are: TW AOAS (X'80') Abandon any SEND for this termin.
TW AONCN (X'10') Normal CLSDST (no reset allowed) TW AOSCN (X'08') Normal CLSDST (reset allowed) TW AONEGR (X'04') Send negative response TW AOOS (X'02') Keep node out of service TW AOCN (X'01') CLSDST node.
TW ANLD of the communication area, and the length of the data in field TW ANLDL. The data is logged to the CSNE transient data queue for future inspection. Note: No data in excess of 220 bytes is logged. Y ou can also send user-written messages to the CSNE log using the transient data facility .
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.
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.
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. v T ime stamp an error , update an error count, and test an error count against numeric and time threshold values.
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.
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=USTOR has been coded.
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.
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.
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.
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).
CSVTESBL DS A NEPESBL - ESB locate routine CSVTNEBD DS A NEPNEBD - NEB delete routine CSVTECUP DS A NEPECUP - error count update routine W riting your own node error program Y ou can write your own NEP in any of the CICS-supported languages. However , CICS-supplied NEP code is provided in assembler language only .
v Updates to recoverable resources. If the resources are locked by another task, the CSNE unit of work could be suspended or shunted. Y ou should also note that you cannot use the NEP to suppress DFHZNAC messages.
Before linking to the node error program, DFHZNAC inserts the primary and secondary printer netnames and terminal IDs into the communication area, indicating also whether either printer is eligible for a print request. DFHZNAC links to the node error program with no default actions set.
If used in this way , the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however , that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened.
DFHZNEPI TYPE=INITIAL—specifying the default routine The DFHZNEPI TYPE=INITIAL macro specifies the name of the default transaction-class routine to be used for the DFNZNEPI module. 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.
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'.
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.
the others have all been shut down), the ISSUE P ASS command does not fail with an INVREQ. Instead, the terminal is logged off and message DFHZC3490 is written to the CSNE log. Y ou may want to code your node error program to deal with the situation when message DFHZC3490 (DFHZNAC error code X'C3') is issued.
514 Customization Guide.
Chapter 10. W riting 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 .
v Create some model TERMINAL definitions. v Define the terminals to VT AM, so that their definitions in VT AM match the model TERMINAL definitions in CICS.
Coding entries for MTS Y ou need to define model names (MDL T AB, MDLENT , and MDLPLU macros) and printer and associated printer names (ASL T AB, ASLENT , and ASLPLU macros) to VT AM.
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 INST ALL 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, DFHZA TDX, always selects the first model name in the list.
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.
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 .
As a general rule, all the models in the list passed to your program match the VT AM 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 VT AM RUSIZE; if this value is incompatible, CICS issues an error message.
However , you may be in a situation where you must continue to use unique and predictable TERMINAL names for your terminals. Y our control program must be able to assign the right TERMINAL name to each terminal, every time the user logs on.
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.
The autoinstall control program at DELETE T o provide symmetry of control over the autoinstall process, the autoinstall control program is also invoked when: v A session with a previously automaticall.
T able 27. Autoinstall control program’s parameter list at DELETE (continued) 1st byte 2nd byte 3rd byte 4th byte Third fullword Length of netname to be deleted First two bytes of netname Next 15 by.
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 VT AM LOGMODE table entries for your terminals are correct, rather than defining new autoinstall models to fit incorrectly coded entries.
The default action of the sample program, on INST ALL, 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.
* REGISTER CONVENTIONS = * * R0 used by DFHEICAL expansion * * R1 -------"-------"------"---- * * R2 Base for Input parameters * * R3 Base for code addressability * * R4 Base for model .
COBOL Figure 41 on page 531, in COBOL, redefines the NETNAME, so that the last four characters are used to select a more suitable model than that selected in the sample control program.
PL/I Figure 42 on page 532, in PL/I, extracts information from the VT AM CINIT RU, which carries the BIND image. Part of this information is the screen presentation services information, such as the default screen size and alternate screen size. The alternate screen size is used to determine the model of terminal that is requesting logon.
DCL 1 CINIT BASED(INSTALL_CINIT_PTR), 2 CINIT_LENG FIXED BIN(15), 2 CINIT_RU CHAR(256); DCL SAVE_CINIT CHAR(256); /* Temp save area for CINIT RU */ DCL 1 SCRNSZ BASED(ADDR(SAVE_CINIT)), 2 SPARE CHAR(3.
/* Now access the screen PS area in the portion of the BIND image presented in the CINIT RU */ /* using the screen alternate height as a guide to the model of terminal attempting logon.
534 Customization Guide.
Chapter 1 1. W riting 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 .
Note: 1. Y ou can have only one active autoinstall control program to handle terminals, consoles, and APPC connections. Y ou specify the name of the active program on the AIEXIT system initialization parameter .
The parameter list contains the following information: 1. A standard header . Byte 1 indicates the request type (this is hexadecimal character X'FD' for INST ALL), and bytes 2 to 3 contain the component code, which is always ZC for consoles.
How CICS builds the list of autoinstall models CICS builds the list of autoinstall models by selecting from its complete list of terminal models those models that define console devices.
If you want an INST ALL request to proceed, perform these steps in your autoinstall control program: v Return an autoinstall model name in the first 8 bytes of the area addressed by fullword 4 of the parameter list. v Supply a CICS terminal name (TERMID) in the next four bytes of the return area.
CICS action on return from the control program When CICS receives control back from the autoinstall control program, it examines the return code field: v If the return code is zero, and the other required information supplied is satisfactory , CICS schedules the transaction specified on the MODIFY command to complete the request.
The sample 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.
542 Customization Guide.
Chapter 12. W riting 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 .
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.
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.
INSTALL_APPC_STANDARD header A fullword input field comprising the following information: INST ALL_APPC_EXIT_FUNCTION A 1-byte field that defines the install request type. The equated values are: INST ALL_APPC_PS_CINIT X'F2' represents an install request for an APPC parallel-session connection from a secondary node via a CINIT request.
INST ALL_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).
Y our control program can use the TEMPLA TE_NETNAME field to specify the NETNAME of the template. For connections between generic resources, your program can accept the suggested template passed by CI.
The autoinstall control program at DELETE T o 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 INST ALL event.
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—.
Note: This type of request cannot be received by CICS T ransaction Server for z/OS, V ersion 3 Release 2. INST ALL_APPC_PS_BIND (X'F3') An incoming BIND for an APPC parallel-session connection.
552 Customization Guide.
Chapter 13. W riting 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.
Y ou 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 .
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.
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.
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.
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 .
Chapter 14. W riting 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 .
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.
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.
autoinstall control program at INST ALL” on page 536. The parameter list passed at INST ALL of local APPC connections initiated by BIND requests is described in “The communication area at INST ALL for APPC connections” on page 545.
(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 T OR is not in use in the AOR to identify a remote terminal or connection.
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, t.
DELETE_SHIPPED_TERM (X'F A') 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 T OR.
566 Customization Guide.
Chapter 15. W riting 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.
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 suf fix can have the values 'AAA' through '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.
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.
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.
Note: The communications area for INST ALL of virtual terminals is the same as that for INST ALL 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 T erminal definition attributes, in the CICS Resource Definition Guide .
INSTALL_BRFAC_STANDARD A fullword input field containing the following information: INST ALL_BRF AC_EXIT_FUNCTION A 1-byte field that indicates the type of resource being installed.
RETURN_OK (X'00') Install the virtual terminal. This is the default value. Y our user program must return this value if the resource is to be autoinstalled. REJECT (X'01') Do not install the virtual terminal. SELECTED_BRF AC_NETNAME An 8-character field used to specify the netname of the bridge facility .
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').
INST ALL_LINK_BRF AC (X'10') The autoinstall program was called during installation of a bridge facility to be used by the Link3270 bridge. INST ALL_ST ART_BRF AC (X'12') The autoinstall program was called during installation of a bridge facility to be used by the ST ART bridge.
578 Customization Guide.
Chapter 16. W riting 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 .
v CICS calls any user-replaceable program other than the program or terminal autoinstall program. v A program is named in the PL TPI or PL TSD list. Autoinstall model definitions Like autoinstall for .
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 T able 30 shows the differences in mapset processing between CICS regions with program autoinstall active and inactive.
Faster startup times W arm and emergency starts If you are using program autoinstall with cataloging , restart times are similar to those of restarting a CICS region that is not using program autoinstall. This is because, in both cases, resource definitions are reinstalled from the catalog during the restart.
The autoinstall control program at INST ALL On invocation, CICS passes a parameter list to the autoinstall control program by means of a communication area addressed by DFHEICAP . The communications area is mapped by a copybook that is supplied in each of the languages supported by CICS.
If you do not set this field, the autoinstall routine uses the language defined in the model, if one is specified. However , when control is passed to the program, CICS determines the language from the program itself, and overrides any specification provided.
PGAC_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.
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.
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.
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.
Chapter 17. W riting 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. “Routing bridge requests dynamically” on page 603 4. “Routing by user ID” on page 607 5. “Parameters passed to the dynamic routing program” on page 607 6. “Naming your dynamic routing program” on page 621 7. “T esting your dynamic routing program” on page 621 8.
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.
Sometimes, the dynamic routing program may be invoked for transactions that are routed statically . This happens if a transaction defined as DYNAMIC(YES) is initiated by automatic transaction initiation (A TI)—for example, by the expiry of an interval control start request—but the transaction is ineligible for dynamic routing.
Important T o route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is 'Y'). If you leave DYTDTRRJ set to 'Y', the transaction is rejected.
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.
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 .
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. Y ou should also consider carefully the effect of EXEC CICS SYNCPOINT and ABEND commands on APPC transaction routing.
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 T ransaction 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.
alternative program is to be linked. Y ou can specify a local or remote program, depending on the region to which the request is to be routed. Changing the transaction ID A transaction identifier is always associated with each dynamic program-link request.
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 Y ou can change the sysid, and issue a return code of ‘0’ in DYRRETC to try to route the request again.
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.
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 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.
T o use the XPCERES exit, both the routing region and the target region must support the “resource unavailable” condition (RESUNA V AIL). All the following support the “resource unavailable” condition: v CICS TS OS/390, V ersion 1.3, with AP AR PQ73107 applied v CICS TS for z/OS, V ersion 2.
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.
Important The same communications area is passed to both the dynamic routing program and the distributed routing program. Some parameters are meaningful to one routing program but not to the other . Some parameter-values may be passed to one routing program but never to the other .
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.
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. Y our 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.
N The transaction is not rejected. This indicator is always set to the reject condition when the dynamic routing program is invoked. T o dynamically route a transaction defined by the DTRTRAN definition, you must change this to the accept condition.
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.
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-r.
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.
N The dynamic routing program is not to be reinvoked. This is the default. Y The dynamic routing program is to be reinvoked. Y ou 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 .
8 T erminate the transaction with either a message or an abend. Whenever the routing program is invoked, DYRRETC is set to ‘0’. When it is invoked for route selection or because an error occurs in route selection, if you want CICS to continue processing the transaction, you must leave it set to ‘0’.
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. Y ou do not need to set a return code when the routing program is invoked for notification or at transaction termination.
– 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).
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.
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.
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 progra.
Chapter 18. W riting a distributed routing program Y ou can write your own distributed routing program or use the default program that is provided with CICS.
6. “Routing by user ID” on page 644 7. “Dealing with an abend on the target region” on page 644 8. “Some processing considerations” on page 645 9. “Parameters passed to the distributed routing program” on page 645 10. “Naming your distributed routing program” on page 656 1 1.
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.
“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).
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.
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.
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.
on the local EJB/CORBA server , that issues a request for another bean. What happens next depends on whether or not the target object belongs to the local EJB/CORBA server: v If the request is for an .
– Whether or not the target object implements CosT ransactions::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.
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, V ersion 2.
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 .
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 .
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.
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 .
distributed routing program is invoked for notification only—it cannot route the request. Unless the SYSID option of the ST ART command specifies a remote region explicitly , the ST ART request is function-shipped to the target region named in the REMOTESYSTEM option; if REMOTESYSTEM is not specified, the ST ART executes locally .
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 ST ART request locally .
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend.
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.
region, even though the transaction is defined as ROUT ABLE(YES) and DYNAMIC(YES). The transaction may , however , be statically routed from the target region to a third region.
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.
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.
Important The same communications area is passed to both the distributed routing program and the dynamic routing program. Some parameters are meaningful to one routing program but not to the other . Some parameter-values may be passed to one routing program but never to the other .
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.
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.
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.
resource is unavailable on the target region. This error code may be set for program-link, Link3270 bridge, and non-terminal-related ST ART requests. DYRFUNC tells you the reason for this invocation of the distributed routing program. The possible values are: 0 Invoked for route selection.
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.
DYRNETNM is not used by the distributed routing program. On invocation, it is set to null characters. Note: T o set the target region, the distributed routing program must use the DYRSYSID field.
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.
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.
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.
v For non-terminal-related ST ART requests , DYRUSERID contains: – The userid specified on the USERID option of the EXEC CICS ST ART command, or – If USERID is not specified, the userid under which the transaction that issued the ST ART command is running.
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 .
658 Customization Guide.
Chapter 19. W riting 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 .
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.
Chapter 20. W riting 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.
662 Customization Guide.
Chapter 21. W riting 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 .
* 1–character reserved field pIIOPData contains the address of the first megabyte of the unconverted IIOP buf fer . If the incoming request is fragmented, this field contains a pointer to: v the fir.
sslClientUserid 1–byte field showing the derivation of the user ID if SSL TYPE CLIENT AUTH is specified in the TCPIPSER VICE definition, where: 0 user ID set from DFL TUSER 1 user ID set from SSL CERTIFICA TE * 2–byte reserved field return_code contains the return code.
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”.
Chapter 22. W riting 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.
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.
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.Y ou 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.
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.
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.
Yo u cannot call DFHJVMA T 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_DFHJVMA T=YES for this type of JVM, then INVOKE_DFHJVMA T=YES is ignored and DFHJVMA T is not called.
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.
T able 34. JVM profile options available to DFHJVMA T (continued) Option Specifies Xrs Reduces the use of operating system signals by the JVM Xrun dllname Loads the specified dynamic link library (DLL.
Chapter 23. W riting 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 .
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.
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.
678 Customization Guide.
Chapter 24. W riting an EJB event program Y ou can write your own EJB event program or use the program provided with CICS, DFHEJEP . Y ou must be familiar with the methods of defining CORBASER VER 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.
Event codes T able 36 shows the codes and meanings of all EJB events that may be passed to the EJB event program. T able 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.
T able 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.
T able 37. EJB event programs and copy books (continued) Language Member name Library Copy books: v Assembler v C v COBOL v PL/I v DFHEJEPD v DFHEJEPH v DFHEJEPO v DFHEJEPL v SDFHMAC v SDFHC370 v SDFHCOB v SDFHPL1 Y ou can use the supplied program as the basis of your own EJB event program.
684 Customization Guide.
Chapter 25. W riting 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 .
686 Customization Guide.
Part 4. Customizing the XRF overseer program © Copyright IBM Corp. 1977, 201 1 687.
A general note about user-written programs: On return from any user-written program, CICS must always receive control in primary-space translation mode, with the original contents of all access registers restored, and with all general purpose registers restored (except for those which provide return codes or linkage information).
Chapter 26. The extended recovery facility overseer program The information in this chapter is of interest only to users of the extended recovery facility (XRF).
End to terminate the sample program Open to ask the overseer to try to open CICS availability manager (CA VM) data sets that it has previously failed to open.
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 .
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.
This problem arises only if the overseer is initialized before all the CA VM data sets have been formatted. If it occurs, the operator can use the Open command (see Open ) to retry the opening of those CA VM data sets on which the Open previously failed.
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.
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.
DFHWOSM FUNC=DSECT macro The DFHWOSM FUNC=DSECT macro generates a number of DSECT s, including the DSECT of the DBLID definitions. DFHWOSM FUNC=JJC macro The DFHWOSM FUNC=JJC macro issues a JES cancel for a named job with a JES job identifier .
For FUNC=QJJS, the P ARM 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.
8 Access already initialized for this generic applid or for this ddname 9 V ersion numbers of the named CA VM 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.
Input The P ARM 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.
Note: 1. The data structures of the status information pointed to by items X'0024' and X'0124' are provided in DSECT DFHXRHDS of CICSTS32.CICS.SDFHMAC. 2. The data structures of the status information pointed to by items X'0025' and X'0125' are provided in DSECT DFHXRGDS of CICSTS32.
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 acti.
DFHWOSM FUNC=TERM macro The DFHWOSM FUNC=TERM macro terminates communication between the overseer program and DFHWOS, and releases any associated storage. It must be issued before the overseer program completes to ensure an orderly termination. Input The T OKEN value is the BUILD token.
The associated DSECT s 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.
user exit program to request a CICS abend, and thereby initiate a takeover , and for the overseer program to issue the PERFORM T AKEOVER command while acting on the same information.
link-edit job step requires the entry name DFHXRONA. If you change any of the DSECT s used by the sample overseer program, you should reassemble the four modules.
Part 5. CICS journaling, monitoring, and statistics © Copyright IBM Corp. 1977, 201 1 707.
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 r.
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 71 1 4. “Structure and content of COMP A T41-format journal records” on page 729 5.
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. T ertiary storage—a form of archive storage, used as specified in your hierarchical storage manager (HSM) policy .
Enabling, disabling, and reading journals Journal records are written to a log stream either directly from a user application program, or from a CICS management program on behalf of a user application. Journal records can be written from a user application using the EXEC CICS WRITE JOURNALNAME command.
Reading journal records offline Access to journaled data in log streams is provided through an MVS subsystem interface (SSI), LOGR. Y our existing user programs can read the general log streams, providing you specify , in your batch job JCL, the SUBSYS parameter and supporting options on the DD for log streams.
System logs are always presented in CICS T ransaction 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.
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_ST ART_GMT 8-byte start time (GMT). LGBH_ST ART_LOCAL 8-byte start time (local). LGBH_BLOCK_NUMBER 8-byte sequence number .
GLRH_RECORD_LENGTH 4-byte record length. GLRH_HEADER_LENGTH 4-byte header length. GLRH_REC_DA T A_LEN 4-byte record data length. GLRH_GMT 8-byte time (GMT). GLRH_LOCAL 8-byte time (local). GLRH_TRAN_ID 4-byte transaction identifier . GLRH_T ASK_ID 4-byte task identifier .
Start of task indicator 1-byte which may contain: X’8n’ Equivalent to JCSPSOTK (start of task) X’4n’ 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.
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.
Some records have a third and fourth section which are of variable length. T able 38 outlines the sections in a journal record written by file control.
FLJB_GENERAL_DA T A 12-byte general data. FLJB_COMMON_DA T A 16-byte common data. FLJB_CD_KEY V ariable-length caller data key . FLJB_CD_DA T A V ariable-length caller data.
FLJB_FILE_NAME 8-byte file name. Reserved 2-byte reserved field. The format of the FLJB_COMMON_DA T A section is shown in Figure 80. FLJB_CD_BASE_ESDS_RBA 4-byte relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS, or if is an extended addressing ESDS).
Write-delete record types There are four sections in the journal records written for write-delete record types: v The FLJB_GENERAL_DA T A section, v The FLJB_WRITE_DELETE_DA T A section, and v The two.
FLJB_WDD_BASE_ESDS_RBA 4-byte relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS, or if it is an extended addressing ESDS). FLJB_WDD_BASE_KEY_LENGTH 2-byte base key length. (The key length is 4 for an RRDS, a VRRDS, or a standard ESDS; 8 for an extended addressing ESDS.
FLJB_GENERAL_DA T A 12-byte general data section. FLJB_CLOSE_DA T A 28-byte close data section. See Figure 79 on page 719 for the format of the FLJB_GENERAL_DA T A section. The format of the FLJB_CLOSE_DA T A section is shown in Figure 84. FLJB_FCD_FWDRECOVLOG_NAME 26-byte log stream name of the forward recovery log.
Tie-up record types There are two sections in the journal records written for tie-up record types: v The FLJB_GENERAL_DA T A section v The TIE_UP_RECORD_DA T A section. The format of such a record written for tie-up record types is shown in Figure 85.
FLJB_TUR_BASE_CI_SIZE 4-byte CI size of base data set. 44 4 2 1 1 26 24 4 44 2 FLJB_ TUR_ BITS Fixed length Fixed length Fixed length Fixed length Log stream name of forward recovery log FLJB_TUR_FWDR.
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.
Function ID 1-byte function identifier . Module ID 1-byte module identifier . Inbound VT AM SN 2-byte inbound VT AM sequence number . Outbound VT AM SN 2-byte outbound VT AM sequence number . JCAUP TID 4-byte terminal identifier (padded with blanks if unused).
UP_MODFN 1-byte module function UP_SVMID 1-byte module identifier UP_FEPDF 1-byte data function UP_FEPES 1-byte escape character for keystroke Reserved 2-byte reserved field UP_FEPPL 8-byte pool name .
Structure and content of COMP A T41-format journal records SMF records The following description does not apply to journal records written to an SMF data set. These are described on page “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.
The label header part of the journal control label header is 10 bytes long, and its format is shown in Figure 91. JCRLL 2-byte length of record. X'0000' 2-bytes containing X'0000'. 32 Fixed length Label prefix Label header 10 4 Length of block Not presented unless the caller is reading data blocks rather than recor ds Figure 90.
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'.
The system header is 10 bytes long. Its format is shown in Figure 94. JCRLL 2-byte length of record. X'0000' 2-bytes containing X'0000'. JCRSTRID 2-byte system-type identifier . For a user journal request, this is X'0000'.
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.
Reserved 2-byte reserved field. JCSPF1 1-byte flag field: X’01’ User prefix present X’02’ Physical start-of-task, JCSPSOTK X’04’ Logical start-of-task, JCSPLSTK JCSPT ASK 3-byte task number . JCSPTIME 4-byte time of request. JCSPTRAN 4-byte transaction identifier .
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.
*********************************************************************** ** FUNCTION IDENTIFIERS ** *********************************************************************** * * * X’20’ PLUS X’8-’ ...USE FOR AUTOMATIC JOURNALING * * X’40’ PLUS X’8-’ .
Note: 1. Records created by automatic journaling and automatic logging are identified by values of X'20' (FIDAJRN) and X'40' (FIDALOG) respectively , added to the “base” value of the function identifier .
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.
The format of the SMF block header is: SMFH_LENGTH 2-byte record length. SMFH_SEG 2-byte segment descriptor (X'0000'). SMFH_FLG 1-byte operating system indicator . SMFH_RTY 1-byte record type. SMFH_TME 4-byte (local) time record moved. SMFH_DTE 4-byte date record moved.
SMFH_NPS 2-byte number of CICS product section. SMFH_ASS 4-byte offset to CICS data section. SMFH_ASL 2-byte length of CICS data section. SMFH_ASN 2-byte 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).
The format of the CICS product section is: SMFPS_VRM 2-byte CICS version, release, and modification information, in the format X'0vrm'. SMFPS_PRN 8-byte product name (generic APPLID). SMFPS_SPN 8-byte product name (specific APPLID). SMFPS_MFL 2-byte record maintenance indicator .
SMFPS_JNM 8-byte journal name. SMFPS_JBN 8-byte job name. SMFPS_RSD 4-byte job date. SMFPS_RST 4-byte job time (local). SMFPS_UIF 8-byte user ID. SMFPS_PDN 8-byte operating system product-level. The CICS data section This section contains a variable number of CICS journal records.
Chapter 28. CICS monitoring This section describes the monitoring facilities of CICS T ransaction Server for z/OS, V ersion 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.
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.
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 ef fective from the application users point of view , because they do not have to use a large number transaction IDs to run an application.
This example shows 4 bytes of user data, typically the transaction ID, being moved using the DFHAPPL.1 EMP . The data starts at offset 0, and the data length defaults to the length specified in the application naming EMP in the MCT .
The monitoring control table (MCT) Y ou can use the monitoring control table (MCT): v T o tell CICS about the EMPs that are invoked by your application programs and about the data that is to be collected at these points. The DFHMCT TYPE=EMP macro can do this.
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.
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. T o prevent confusion with the eleventh EMP in another application, this EMP is uniquely identified by the empid PROG3.
The DBCTL data recorded by these event monitoring points can be mapped using the IMS macro DFSDST A DSECT=YES, which is available in the IMS genlibs. For more information about monitoring in DBCTL, see the CICS IMS Database Control Guide .
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.
Note: 1. CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFMNFLG). SMF sets the remainder of the byte according to the operating system level .
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 .
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. Y ou can identify which of these you are dealing with by looking at the value of field SMFMNCL in the SMF product section.
Whenever the monitoring of performance class data is switched on, whether at CICS initialization or while CICS is running, a dictionary data section is written. So, if the monitoring of performance class data is switched on and off three times during a single CICS run, there are three separate, but identical, dictionary data sections for that run.
C Byte-string P Packed decimal number S Clock T T ime stamp 756 Customization Guide.
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHTASK C001 4 X’0001’ X’0000’ TRAN DFHTERM C002 4 X’0002’ X’0004’ TERM DFHCICS C089 8 X’0003’ X’0008’ USERID DFHTASK C004 4 X’0004.
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHSTOR A106 4 X’004B’ X’0314’ SCUSRHWM DFHSTOR A116 4 X’004C’ X’0318’ SC24CHWM DFHSTOR A119 4 X’004D’ X’031C’ SC31CHWM DFHSTOR A095 8.
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHTASK A346 4 X’0086’ X’0410’ ICSTRCCT DFHTASK A347 4 X’0087’ X’0414’ ICSTRCDL DFHSYNC A060 4 X’0088’ X’0418’ SPSYNCCT DFHCICS A025 4.
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAME DFHSOCK A298 4 X’00C2’ X’0500’ SOTOTCT DFHSOCK A301 4 X’00C3’ X’0504’ SOMSGIN1 DFHSOCK A302 4 X’00C4’ X’0508’ SOCHRIN1 DFHSOCK A303 4 .
Performance data sections Each performance data section is made up of a string of field connectors, followed by one or more performance data records. All of the performance records produced by a single CICS run have the same format.
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 .
Figure 1 14 illustrates the relationship between the dictionary record, the field connectors, and the performance records. How the string of field connectors is constructed When CICS is initialized, a unique connector value is assigned to every dictionary entry .
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.
For further information about exception class data, see Exception class data, in the CICS Performance Guide , which lists all the system-defined data that can be produced by CICS monitoring. T ransaction resource data sections Each transaction resource data section is made up of one or more transaction resource data records.
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.
DFHMNRDS DSECT , Transaction resource monitoring record MNR_LENGTH DS H Length of resource data MNR_ID_EQUATE EQU 79 Monitoring domain id mask MNR_ID DC AL2(MNR_ID_EQUATE) Monitoring domain id MNR_VER.
MNR_ID_ACMETH_TCAM EQU X’04’ TCAM/DCB (supported for remote terminals only) MNR_ID_ACMETH_BGAM EQU X’06’ BGAM MNR_ID_ACMETH_CONSOLE EQU X’07’ CONSOLE MNR_ID_DEVCODE DS XL1 Device type code.
Chapter 29. W riting statistics collection and analysis programs This chapter describes how you can customize the collection and analysis of CICS statistics.
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.
v DFH0STGN v DFH0STLK v DFH0STPR v DFH0STSY v DFH0STTP v DFH$ST AS v DFH$STCN v 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 .
Note: 1. CICS sets only the subsystem-related bits of the operating system indicator flag byte in the SMF header (SMFSTFLG). SMF sets the remainder of the byte according to the operating system level and other factors. For an explanation of the setting of the other bits, refer to the z/OS MVS System Management Facilities (SMF) manual.
3. Fields SMFSTINT and SMFSTINO are only relevant if SMFSTRQT is ‘INT’. Otherwise both values should be ignored. 4. For TS data sharing, the record subtype is X'0003' and certain fields are not set or are used in a different way . SMFSTPRN and SMFSTSPN contain the server prefix (DFHXQ) and the pool name.
Figure 124 on page 775. For further guidance information about the fields within the statistics data records, see CICS statistics in DSECT s and DFHSTUP report, in the CICS Performance Guide .
STID STID Symbolic Value Copy book Type of record name STISMD 5 DFHSMDDS Storage mgr domain subpool id STISMT 6 DFHSMTDS Storage manager task subpool id STIXMG 10 DFHXMGDS Transaction manager (Globals.
The TS data sharing statistics use no symbolic names, but relate to the STID values as follows: The coupling facility data table server statistics use no symbolic names, but relate to the STID values .
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 .
778 Customization Guide.
Part 6. Customizing CICS compatibility interfaces © Copyright IBM Corp. 1977, 201 1 779.
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 alwa.
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.
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.
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 V alues are classified as follows: Keyword value Keyword values must be specified for some keywords.
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.
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 .
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. 1977, 201 1 787.
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 .
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.
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.
T able 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 .
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.
T able 46. Obtaining the address of the installation data parameter list (continued) RACROUTE REQUEST type RACF exit Exit list mapping macro Parameter list field name EXTRACT Not available Not available None Note: 1.
DEF AUL T_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_RESOUR.
UXPLUNAM Address of an area containing the VT AM 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 VT AM terminal. UXPTCTUA Address of the TCT user area. UXPTCTUL Address of a fullword containing the length of the TCTUA.
v When an invalid password, or a passticket is presented, or an EXEC CICS VERIFY P ASSWORD 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=CREA TE option is issued to perform the normal verification routine. The ENVIR=CREA TE version of the macro is issued by the security manager domain running in supervisor state.
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 .
800 Customization Guide.
Chapter 32. W riting a “good night” program Y ou can use the GNTRAN system initialization parameter to specify a “good night” transaction that you want CICS to invoke when a user ’s terminal-timeout period expires.
GNTRAN_START_TRANSID The identifier of the transaction that started the “good night” transaction. If it was started by CICS because of a terminal timeout, GNTRAN_ST ART_TRANSID is set to 'CEGN'.
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.
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.
LOGOFF The terminal is both signed off and logged of f. 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 .
806 Customization Guide.
Part 8. Examining and modifying resource attributes © Copyright IBM Corp. 1977, 201 1 807.
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 alwa.
Chapter 33. Using the programmable interface to CEDA This chapter describes a programmable interface to the resource definition online (RDO) transaction, CEDA.
request input from its associated terminal, whereas an automatically initiated transaction must first send data to the terminal. An attempt to start CEDA under CECI by an EXEC CICS ST ART command fails for similar reasons. 2. The RDO command passed in address 1 of the CEDAP ARM parameter list must be valid.
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.
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.
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. Y ou must supply a USERPROGRAM value.
8 Keyword detail call 10 Object end call 12 Group end call 14 List end call 16 Final call. Workarea Ptr This is the address of a field containing the address of a fullword to be used by the user application to store the address of any user-acquired work area.
T able 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 .
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.
v For distribution, in part or as a whole, to other CICS installations v T o recreate or add resource definitions to any CSD using DFHCSDUP . The program must be run against an EXTRACT command of the .
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. Notes for the assembler job: 1 Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXAI.
Notes for the Language Environment job: 1 Specify the entry name as DFHEXTRA, which is the entry name in the CICS-supplied stub, DFHEXLE (see 3). 2 The CICS-supplied stub, DFHEXLE, is generated with a link to the user program using a dummy CSECT name (EXITEP).
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 Y our put-message exit routine can terminate DFHCSDUP , if desired.
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.
DFHUEXIT DSECT UEPEXN DS A ADDRESS OF EXIT NUMBER UEPGAA DS A ADDRESS OF GLOBAL AREA UEPGAL DS A ADDRESS OF GLOBAL AREA LENGTH UEPCRCA DS A ADDRESS OF CURRENT RETURN-CODE UEPTCA DS A ADDRESS OF TCA UE.
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.
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).
UEPMDOM Reserved UEPINSN Address of a 2-byte field containing the number of insert fields UEPINSA Address of the following message structure: DS F Reserved INS_1_TEXT_PTR DS A Address of insert 1 INS_.
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.
830 Customization Guide.
Part 9. Appendixes © Copyright IBM Corp. 1977, 201 1 831.
832 Customization Guide.
Appendix A. Coding entries in the VT AM LOGON mode table This appendix shows you what to code in your VT AM LOGON mode table for a terminal to be automatically installed. It is divided into the following sections: 1. “Overview of the VT AM LOGON mode table” 2.
Note that T able 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 .
T able 49. TYPETERM device types, with cross-references to VT AM logmode entries (continued) TYPETERM device type Reference number in T able 50 on page 836 DEVICE(3650) SESSIONTYPE(PIPELN) * 21 DEVICE.
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 (.
T able 50. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 7 FMPROF=X’04’ TSPROF=X’04’ PRIPROT=X’B0’ SECPROT=X’30’ COMPROT=B’0100.
T able 50. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 14 FMPROF=X’03’ TSPROF=X’04’ PRIPROT=X’B1’ SECPROT=X’B0’ COMPROT=B’0111.
T able 50. LOGON mode table and ISTINCLM entries (continued) RN VT AM MODEENT macro entries that are needed for related CICS TYPETERM definitions Suitable supplied entries 19 FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=B’10..0000’ COMPROT=B’0011.
PSER VIC screen size values for LUTYPEx devices T able 51 is to help you decide what screen size values you should specify on the PSERVIC operand of the VT AM MODEENT macro, for LUTYPE0, LUTYPE2, and LUTYPE3 devices.
T able 52. Equivalent PSERVIC screen size values (continued) Bytes 20—24 of CICS model bind V alid screen size values on PSERVIC definition xxxx 0000 7E Plus, if xxxx=1850 0000 0000 00 xxxx 0000 7E .
ATI ==> YES TTI ==> YES AUTOCONNECT ==> NO LOGONMSG ==> YES BIND SENT BY CICS depends on PSERVIC value on LOGMODE definition above: EITHER : 01020271 40200000 00000080 00000000 00000000 00.
TERMINAL definition ************************* AUTINSTNAME ==> M3770 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3770 INSERVICE ==> YES TYPETERM definition **********************.
ATI ==> YES TTI ==> YES PAGESIZE ==> 50,80 AUTOPAGE ==> YES LOGONMSG ==> NO LDCLIST ==> LDC1 Needs LDC declaration in TCT : LDCS DFHTCT TYPE=LDC,LDC=SYSTEM LDC1 DFHTCT TYPE=LDC,LOCAL.
BRACKET ==> YES IOAREALEN ==> 256 ATI ==> YES TTI ==> YES BIND SENT BY CICS : 010404B1 B0708000 00858580 00000000 ****************************************************************** 6) 3790.
AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3790C INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3790C Note that CEDA changes DEVICE=3790, GROUP ==> PDATD SESSIONTYPE=SCSPRT to DEVICE=SCSPRINT, DEVICE ==> 3790 SESSIONTYPE=blanks, PRINTERTYPE=3284.
TERMINAL definition ************************* AUTINSTNAME ==> M3650A AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3650A INSERVICE ==> YES TYPETERM definition ********************.
TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’6000’ TERMINAL definition ************************* AUTINSTNAME ==> M3650B2 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETER.
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’ TERMI.
USERAREALEN ==> 32 ATI ==> YES TTI ==> YES LOGONMSG ==> YES ERRHILIGHT ==> BLINK RECEIVESIZE ==> 1024 BIND SENT BY CICS : 010303B1 90308000 00878780 00028000 00000018 503EA07F 000000.
DFHLU3 MODEENT LOGMODE=DFHLU3, LU TYPE 3 PRINTER. TYPE=1, FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’3080’, RUSIZES=X’8585’, PSERVIC=X’03800000000000.
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’000000000000.
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’020000000000.
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 VT AM.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'20' TCZVT AMI DFHZC2417 None X'21' TCZ.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'49' TCZCLSIN DFHZC3462 7 X'4A' TCZOP A.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'75' TCZSESE1 DFHZC2424 3791 01 11 52 4 X'76.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'A7' TCZBOEB DFHZC2449 2371 11 82 22 4 X'A8&.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'D3' TCZDMPD DFHZC2463 None X'D4' TCZCX.
T able 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message Action flags set X'FF' TCZPSPE DFHZC0149 7 Note: 1. See message DFHZC2497 or DFHZC3493, depending on the device type. 2.
T able 54. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC2410 TCZTXCU X'D1' 23791 01 12 4 DFHZC241 1 TCZDMSN X'E0' .
T able 54. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC2450 TCZSSXAR X'83' None DFHZC2451 TCZSRCCI X'CC' 2391 01 .
T able 54. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC3429 TCZSTRMM X'EC' 2 3 7 DFHZC3430 TCZSTON X'ED' 2 3 DFHZ.
T able 54. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC3489 TCZLUINH X'C8' 7 18 24 DFHZC3490 TCZCPF AL X'C3' 7 24.
T able 54. CICS messages associated with VT AM errors (continued) Message Symbolic label Error code Action flags set DFHZC4939 TCZLUPUN X'8C' 23572 4 DFHZC4940 TCZLUSKN X'8F' 23572.
T able 55. Messages issued and flags set by DFHZNAC for specific sense codes (continued) Sense code Message Action flags set X'081 1' DFHZC2464 9, 10, 1 1 X'0812' DFHZC2465 2, 3 X&.
T able 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, 1 1, 23, 24 X'8000' D.
T able 56. Meanings of action flags set by DFHZNAC (continued) Flag Field Bit mask Hex bit setting Action 1 1 ..1. .... X'20' Abend any task attached to TCTTE 12 ...1 .... X'10' Cancel any task attached to TCTTE 13 .... 1... X'08' Good Morning message to be sent 14 .
870 Customization Guide.
Appendix C. Analyzing CICS restart information Y ou 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_ST ART keywords to allow a CICS system to be auto-restarted with a given override.
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 . Y ou 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. “T ranslating national characters to uppercase” describes how to translate national characters that CICS cannot handle by standard means.
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.
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 i.
* * * It is not safe to use the following storage: * * Program storage (DFHEISTG) since this is freed as soon * * as the exit program returns control to CICS.
*---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries. Each entry * * can be mapped by the TABLE_ENTRY DSECT * *----------------.
* Registers: * * R1 = UEPAR plist (set on entry) * * = Work register * * R2 = UEPAR plist * * R3 = Program base register (set by DFHEIENT) * * R6 = Linkage register * * R11= EIB register * * R13= EIST.
*=====================================================================* * TS_REQUEST - Invoked at XTSEREQ exit point * * Determine the TS Queue Name and scan the TS_Routing_Table for * * a match. If an entry exists in the table, then check the action * * field and call the ROUTE_REQUEST or LOCAL_REQUEST routines.
*=====================================================================* TS_REQUEST DS 0H * Check for possible recursion L R1,UEPRECUR Address of recursive count LH R1,0(R1) Fetch count LTR R1,R1 Has exit been invoked recursively? BNZ ERROR2 .
*=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point * * Free any shared storage that was acquired during previous * * invocation at XTSEREQ.
*=====================================================================* * LOCAL_REQUEST: Process Local TS Queues * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. If required, rename the TS Queue Name, but do not * * modify the SYSID.
*=====================================================================* * ROUTE_REQUEST: Ship request to remote system * * An entry has been found in the TS_Routing Table for this TS * * Queue Name. The request is modified by adding a SYSID to the * * command and renaming the queue if required.
* Update the Sysid in CLPS ROUTE1 DS 0H MVC SHARED_SYSID,NEW_SYSID Copy SYSID into shared storage L R8,UEPCLPS Address the CLPS.. USING TS_ADDR_LIST,R8 .
* Logic: * * Entry_Not_Found: * * Call Getmain_Shared * * Copy default_sysid into shared storage * * Address the command plist * * Update ADDR7 to point to the address of the default SYSID * * Set the.
*=====================================================================* * GETMAIN_SHARED - Obtain Shared storage * * * * Registers: * * R0 = Used by EXEC CICS call * * R1 = Used by EXEC CICS call * * .
*=====================================================================* * FREEMAIN_SHARED - Free shared storage * * Free the shared storage associated with this command.
USING DFHTRPT_ARG,R1 TRACE_ENTRY DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT_ID(TR_ENTRY) B ISSUE_TRACE TRACE_EXIT DS 0H L R1,UEPXSTOR Prepare for XPI call DFHTRPTX CLEAR, X POINT.
ERROR4 DS 0H MVI TR_ERROR_N,4 B TRACE_ERROR ERROR5 DS 0H MVI TR_ERROR_N,5 B TRACE_ERROR ERROR6 DS 0H MVI TR_ERROR_N,6 B TRACE_ERROR ERROR7 DS 0H MVI TR_ERROR_N,7 B TRACE_ERROR ERROR8 DS 0H MVI TR_ERRO.
Before using the sample program in a production environment, you would need to customize it to suit your installation. TS_ROUTING_TABLE DS 0D ENTRY_NAME_1 DC CL8’AAAAAAAA’ Rename Queue AAAAAAAA as.
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.
Non-threadsafe commands: v DFHDUDUX TRANSACTION_DUMP 894 Customization Guide.
Bibliography The CICS T ransaction Server for z/OS library The published information for CICS T ransaction Server for z/OS is delivered in the following forms: The CICS Transaction Server for z/OS Information Center The CICS T ransaction Server for z/OS Information Center is the primary source of user information for CICS T ransaction Server .
CICS T ransaction Server for z/OS Migration from CICS TS V ersion 3.1 , GC34-6858 CICS T ransaction Server for z/OS Migration from CICS TS V ersion 1.3 , GC34-6855 CICS T ransaction Server for z/OS Migration from CICS TS V ersion 2.
CICSPlex SM Application Programming Guide , SC34-6848 CICSPlex SM Application Programming Reference , SC34-6849 Diagnosis CICSPlex SM Resource T ables Reference , SC34-6850 CICSPlex SM Messages and Co.
Short Title Full Title Data Areas Volume 1 OS/390 MVS Data Areas, Vol 1 (ABEP-DAL T) , SY28-1 164 Data Areas Volume 2 OS/390 MVS Data Areas, Vol 2 (DCCB-ITTCTE) , SY28-1 165 Data Areas Volume 3 OS/390.
Updates to the softcopy are clearly marked by revision codes (usually a # character) to the left of the changes. Bibliography 899.
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 .
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 inf.
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 .
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 .
DFHCSDUP , system definition utility program (continued) sample programs (continued) DFH$CRF A 816 DFH$CRFP 816 DFH$FORA 817 DFH$FORP 817 DFH0CBDC 817 DFH0CRFC 816 DFH0FORC 817 DFHDBUEX, CICS–DBCTL .
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 T.
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 dist.
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 infor.
Functional list of GLUEs 32 G generic resources, VT AM 547 node error program 512 GET_A TTRIBUTE_V ALUE function of the XPI 325 GET_NEXT_A TTRIBUTE function of the XPI 326 GET_NEXT_ENTRY function of t.
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$ZCA T 16 DFHXIS 140 DFHXTENF 230 summary of 15 trace table ent.
log manager functions of the XPI 360 logical units (LUs) node error program 486 LOGON mode table, VT AM 833 LU alias names 523 M MAXERRS operand DFHTEPT TYPE=INITIAL 465 MAXTIDS operand DFHTEPT TYPE=I.
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 p.
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.
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 IPCO.
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 DFHCSD.
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, a.
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 DFH.
user-written node error programs 505 utility programs shutdown assist, DFHCESD 429 V virtual terminals, automatic installation of 567 VT AM dynamic LU alias 523 W work areas in task-related user exits.
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 .
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.
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.
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.
T rademarks 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 .
926 Customization Guide.
Readers’ Comments — W e'd Like to Hear from Y ou CICS T ransaction Server for z/OS Customization Guide V ersion 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.
Readers’ Comments — We'd Like to Hear from Y ou SC34-6814-04 SC34-6814-04 Cut or Fold Along Line Cut or Fold Along Line Fold and T ape Please do not staple Fold and T ape Fold an.
.
Product Number: 5655-M15 SC34-6814-04.
Spine information: CI C S T ra nsa cti o n Se rv er f o r z/OS C u sto mizati o n Gui d e Ve r s i o n 3 Re lease 2.
Een belangrijk punt na aankoop van elk apparaat IBM SC34-6814-04 (of zelfs voordat je het koopt) is om de handleiding te lezen. Dit moeten wij doen vanwege een paar simpele redenen:
Als u nog geen IBM SC34-6814-04 heb gekocht dan nu is een goed moment om kennis te maken met de basisgegevens van het product. Eerst kijk dan naar de eerste pagina\'s van de handleiding, die je hierboven vindt. Je moet daar de belangrijkste technische gegevens IBM SC34-6814-04 vinden. Op dit manier kan je controleren of het apparaat aan jouw behoeften voldoet. Op de volgende pagina's van de handleiding IBM SC34-6814-04 leer je over alle kenmerken van het product en krijg je informatie over de werking. De informatie die je over IBM SC34-6814-04 krijgt, zal je zeker helpen om een besluit over de aankoop te nemen.
In een situatie waarin je al een beziter van IBM SC34-6814-04 bent, maar toch heb je de instructies niet gelezen, moet je het doen voor de hierboven beschreven redenen. Je zult dan weten of je goed de alle beschikbare functies heb gebruikt, en of je fouten heb gemaakt die het leven van de IBM SC34-6814-04 kunnen verkorten.
Maar de belangrijkste taak van de handleiding is om de gebruiker bij het oplossen van problemen te helpen met IBM SC34-6814-04 . Bijna altijd, zal je daar het vinden Troubleshooting met de meest voorkomende storingen en defecten #MANUAl# samen met de instructies over hun opplosinge. Zelfs als je zelf niet kan om het probleem op te lossen, zal de instructie je de weg wijzen naar verdere andere procedure, bijv. door contact met de klantenservice of het dichtstbijzijnde servicecentrum.
