IBM SC34-6814-04 Customization Manual

Cics transaction server for z/os

page of 953

/ 953
Contents
Table of Contents
Bookmarks

Table of Contents

Quick Links

Download this manual

CICS Transaction Server for z/OS

Customization Guide

V ersion 3 Release 2

SC34-6814-04

Table of Contents

Chapters

Table of Contents

Summary of Contents for IBM SC34-6814-04

Page 1 CICS Transaction Server for z/OS Customization Guide V ersion 3 Release 2 SC34-6814-04...
Page 3 CICS Transaction Server for z/OS Customization Guide V ersion 3 Release 2 SC34-6814-04...
Page 4 Before using this information and the product it supports, be sure to read the general information under “Notices” on page 923. This edition applies to Version 3 Release 2 of CICS Transaction Server for z/OS, program number 5655-M15, and to all subsequent versions, releases, and modifications until otherwise indicated in new editions.
Page 5: Table Of Contents
Summary of changes ..... . xix Changes for CICS Transaction Server for z/OS, Version 3 Release 2 ..xix Changes for CICS Transaction Server for z/OS, Version 3 Release 1 .
Page 6 File control EXEC interface API exits XFCREQ and XFCREQC ..85 File control EXEC interface SPI exits XFCAREQ and XFCAREQC ..98 File control file state program exits XFCSREQ and XFCSREQC ..111 File control open/close program exit XFCNREC .
Page 7 Recursion within a task-related user exit program... 290 Purging tasks ......290 Using CICS services in your task-related user exit program .
Page 8 The DEFINE_PROGRAM call ....353 The ACQUIRE_PROGRAM call ....356 The RELEASE_PROGRAM call .
Page 9 Storage keys for PLT programs ....430 Part 3. Customizing with user-replaceable programs ... . . 433 Chapter 5.
Page 10 Coding for specific VTAM sense codes Writing multiple NEPs ..... 508 DFHZNEPI macros ..... . 508 Handling shutdown hung terminals in the node error program .
Page 11 The sample autoinstall control program for APPC connections ..550 Default actions of the sample program ....550 Resource definitions ..... 551 Chapter 13.
Page 12 Routing transactions dynamically ....590 Dynamic transactions ..... 590 When the dynamic routing program is invoked .
Page 13 Dealing with a disabled CorbaServer ....635 Performing a rolling upgrade of an EJB/CORBA server..637 Routing non-terminal-related START requests ... . . 637 Which requests can be dynamically routed?.
Page 14 Reading journal records offline Structure and content of CICS Transaction Server for z/OS format journal records ......712 Format of general log block header .
Page 15 Chapter 28. CICS monitoring Introduction to CICS monitoring ....743 How CICS monitoring data is passed to SMF ... . 743 Coding additional event-monitoring points Application naming event monitoring points .
Page 16 Part 8. Examining and modifying resource attributes ... . . 807 Chapter 33. Using the programmable interface to CEDA ..809 When to use the programmable interface ....810 Using DFHEDAP in a DTP environment .
Page 17 Bibliography ......895 The CICS Transaction Server for z/OS library ... . . 895 The entitlement set .
Page 18 Customization Guide...
Page 19: Preface
Programming Reference. Resource definition information is described in the CICS Resource Definition Guide. To use the following information, you must be familiar with the IBM ACF/VTAM telecommunications access method: v Chapter 9, “Writing a node error program,” on page 479 v Chapter 10, “Writing a program to control autoinstall of terminals,”...
Page 20: Syntax Notation And Conventions Used In This Book
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.
Page 21: Summary Of Changes
Summary of changes This book is based on the CICS Customization Guide for CICS Transaction Server for z/OS, Version 3 Release 1, SC34-6429-00. Changes from that edition are marked by vertical bars in the left margin. Changes for CICS Transaction Server for z/OS, Version 3 Release 2...
Page 22: Changes For Cics Transaction Server For Z/Os, Version 2 Release 3
Changes for CICS Transaction Server for z/OS, Version 2 Release 3 The more significant changes for this edition were: v A new global user exit, XICERES, in the interval EXEC interface control program, was described in The XICERES global user exit and “Using the XICERES exit to check the availability of resources on the target region”...
Page 24 Customization Guide...
Page 25: Chapter 1. Global User Exit Programs
Write-to-operator (WTO) commands use register 1. If your exit program uses WTO commands, you should save the address of DFHUEPAR first. © Copyright IBM Corp. 1977, 2011 concurrently by several tasks; it does not modify itself while running. A “quasireentrant” program is serially reusable by different tasks. When it receives control it must be in the same state as when it relinquished control.
Page 26: 31-Bit Addressing Implications
16MB line. Access register implications v The global user exit is invoked in primary-space translation mode. For information about translation modes, see the IBM ESA/370 Principles of Operation manual. v The contents of the access registers are unpredictable. For information about access registers, see the IBM ESA/370 Principles of Operation manual.
Page 27: Using Channels And Containers
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.
Page 28: Assembler Programs And Leasm
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.
Page 29: Parameters Passed To The Global User Exit Program
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.
Page 30 UEPGAL UEPCRCA DS UEPTCA UEPCSA UEPEPSA DS UEPHMSA DS UEPGIND DS UEPSTACK DS UEPXSTOR DS UEPTRACE DS UEPEXN points to a 1-byte binary field whose contents identify the global user exit point from which the exit program is being invoked. You need this information if your exit program can be invoked from more than one exit point.
Page 31 UEPTJ9 The J9 open TCB, used for JVMs that are in user key UEPTJM The JM open TCB, used with the IBM SDK for z/OS, V1.4.2 for the master JVM that initializes the shared class cache UEPTL8 An L8 open TCB, used for OPENAPI TRUEs, or OPENAPI...
Page 32: Returning Values To Cics
Table 1. TCB indicators in DFHUEPAR (continued). Description Symbolic value UEPTX9 UEPSTACK points to the kernel stack entry. This value must be moved to the exit program’s register 13 before invoking the XPI. For more information, refer to Chapter 3, “The user exit programming interface (XPI),”...
Page 33: Restrictions On The Use Of Fields As Programming Interfaces
If you supply a return code value that is not expected at a particular exit point, the default return code indicating a normal response (usually UERCNORM) is assumed, unless you set the return code UERCPURG. You are strongly advised not to let the return code default to the normal response as the result can be unpredictable.
Page 34: Errors In User Exit Programs
storage. However, on an EXEC CICS GETMAIN command, the exit program can override the TASKDATAKEY option by specifying either CICSDATAKEY or USERDATAKEY. v When an exit program obtains storage using an XPI GETMAIN call, the storage key depends on the value specified on the STORAGE_CLASS option, which is mandatory, and which overrides the value of TASKDATAKEY.
Page 35: Viewing Active Global User Exits
v Otherwise, use the EXEC CICS ENABLE command to enable the user exit program. If you enable a global user exit program before it has been installed and LPA=YES is specified as a system initialization parameter, CICS scans the LPA for the program.
Page 36: Invoking A Single Exit Program At More Than One Exit
– 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. –...
Page 37: Sample Global User Exit Programs
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. You should pay particular attention to exit programs used on the mainline CICS-DB2 path: exit programs written for the XRMIIN and XRMIOUT exit points need to be made threadsafe, as well as those invoked frequently, such as XEIIN and XEIOUT, which...
Page 38 v Share a GWA between global user exit programs, thereby making the information it contains available to more than one program, and overcoming limitations on the size of GWAs. v Access information held in a global user exit program’s GWA. The GWA sample programs and copy books are: DFH$PCEX A sample global user exit program, designed to be invoked at the...
Page 39 v Uses the START option of the EXEC CICS ENABLE command to make DFH$PCEX available for execution. This causes DFH$PCEX to be driven for all LINKs and XCTLs. v Links to the dummy program, DFH$PCPL, in order to drive DFH$PCEX. v Uses the STOP option of the EXEC CICS DISABLE command to make DFH$PCEX unavailable for execution.
Page 40: Sample Programs For Specific Exits
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.
Page 41 DFH$DTRD A sample global user exit program, designed to be invoked at the XDTRD exit. DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data Tables Guide. Related concepts: “Data tables management exits XDTRD, XDTAD, and XDTLC” on page 40 Data tables management exits apply to both CICS shared data tables and CICS coupling facility data tables.
Page 42 This program, whose purpose is to initialize the supplied Web-related global user exits, is specified in the PLTPI and is invoked during the CICS post-initialization phase. It is specified with the INITPARM system initialization parameter as follows: INITPARM=(DFH$WBPI=’PROXY=proxyurl,LDAPBIND=profilename,STS=sts-server-url’) where Customization Guide...
Page 43 The proxy name must be specified as: INITPARM=(DFH$WBPI=’PROXY=proxyurl’) where proxyurl is the URL if a proxy server. If you use a number of proxy servers or want to apply a security policy to different host names, you can load or build a table...
Page 44 Obtains the destination HTTP host from UEPHOST/UEPHOSTL and the destination HTTP path from UEPPATH/UEPPATHL, and uses them to construct the URL of the HTTP server for which the basic authentication credentials are required, as follows: http://hostname/pathname. v If a realm exists (that is, if UEPREALML is non-zero), DFH$WBX2 appends the...
Page 45 If the LINK was unsuccessful, or if a SOAP fault response is returned, DFH$WBX2 returns from the exit with return code UERCERR. The above implementation assumes that the STS server is configured to respond with an appropriate username token when presented with the URI formatted by DFH$WBX2 in the AppliesTo element of the STS issue request.
Page 46 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. These parameters are passed to the XZIQUE global user program, which can change the way in which these parameters are used: DFH$XZIQ...
Page 47: Alphabetical List Of Global User Exit Points
XPCTA exit, to test whether the abend was caused by a storage protection exception condition. It is described on page “The sample XPCTA global user exit program, DFH$PCTA” on page 191. Related concepts: “The sample XPCTA global user exit program, DFH$PCTA” on page 191 The terminal-not-known sample exit program You can use this sample global user exit program to handle terminal-not-known conditions arising from START and ATI requests:...
Page 48 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XDTAD Data tables management XDTLC XDTRD XDUCLSE Dump domain XDUOUT XDUREQ XDUREQC XEIIN EXEC interface program XEIOUT XEISPIN XEISPOUT XFAINTU 3270 bridge facility management program XFCAREQ File control EXEC interface program...
Page 49 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XFCBFAIL File control recovery control program XFCBOUT XFCBOVER XFCLDEL XFCFRIN File control domain XFCFROUT XFCNREC File control open/close program XFCQUIS File control quiesce send program XFCREQ File control EXEC interface program...
Page 50 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XICEREQ Interval control EXEC interface program XICEREQC XICERES XICEXP Interval control program XICREQ XICTENF XISCONA Intersystem communication program XISLCLQ XISQUE To control the number of queued requests for sessions on IPCONNs XLDELETE Loader domain...
Page 51 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XPCABND Program control program XPCERES XPCFTCH XPCHAIR XPCREQ XPCREQC XPCTA XRCINIT User log record recovery program XRCINPT XRMIIN Resource manager interface program XRMIOUT XRSINDI Resource management modules XSNEX Security manager...
Page 52 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XSZARQ Front End Programming Interface XSZBRQ XTCATT Terminal control program XTCIN XTCOUT XTDEREQ Transient data EXEC interface program XTDEREQC XTDIN Transient data program After receiving data from QSAM (extrapartition) or XTDOUT XTDREQ XTSEREQ...
Page 53 Table 2. Alphabetical list of global user exit points (continued) Exit name Module or domain XWBAUTH Web domain XWBOPEN XWBSNDO XWSPRROO Pipeline domain XXDFA DBCTL interface control program XXDFB DBCTL tracking program XXDTO XXMATT Transaction manager domain XXRSTAT XRF request processing program XZCATT VTAM terminal...
Page 54: Global User Exit Points By Functional Area
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.
Page 55: Application Associated Data Exit, Xapadmgr, In The Ap Domain
Return codes UERCNORM XPI calls XPI must not be used. API and SPI calls The following commands are supported: v ADDRESS CWA v ADDRESS EIB v LINK (but only to local programs; distributed program links may not be v RETURN v WRITE JOURNALNAME.
Page 56: Basic Mapping Support Exits Xbmin And Xbmout
UERCNORM XPI calls All can be used. API and SPI calls All can be used, except for: v EXEC CICS ABEND v EXEC CICS PERFORM SHUTDOWN Sample exit program, DFH$APAD CICS provides a sample global user exit program, DFH$APAD, for use at the XAPADMGR exit point.
Page 57 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.
Page 58 UEPBMTCT UEPEXECB UEPBMCNT UEPBMTAB Return codes UERCNORM UERCPURG XPI calls All can be used. The field element table structure The field element table contains one or more elements which provide information about each “field of interest” passed to the exit. A “field of interest” is a field which has been defined as VALIDN=USEREXIT in the map source file used to create the mapset referenced in the mapping operation.
Page 59 BMXACTLN is a halfword binary value which contains the actual length of the data received or transmitted in this field. BMXDATA is the address of the field data. In the XBMIN exit, BMXDATA points into a work area which BMS has obtained for input mapping purposes.
Page 60: Bridge Facility Exit Xfaintu
When modifying data in the XBMIN exit, the safest method is to use the length provided in BMXMAPLN, but to ensure that any pad characters added by BMS are preserved. BMXATTR must be ignored in the XBMIN exit; it always contains binary zeroes. Programming the XBMOUT exit This section contains some considerations specific to the XBMOUT exit.
Page 61 Exit-specific parameters UEPFAREQ Address of a 1-byte field that indicates why the exit has been called. Possible values are: UEPFAIN Initialization. UEPFATU Tidy-up. UEPFATUT Address of a 1-byte field that indicates the type of tidy-up required. Possible values are: UEPFANTU Normal tidy-up.
Page 62: Data Tables Management Exits Xdtrd, Xdtad, And Xdtlc
Return codes UERCNORM XPI calls All can be used, except those that use recoverable resources. API calls All can be used except those that invoke task-related user exits or use recoverable resources. Data tables management exits XDTRD, XDTAD, and XDTLC Data tables management exits apply to both CICS shared data tables and CICS coupling facility data tables.
Page 63 Note: For additional information about using these exits with CICS shared data table support, see the CICS Shared Data Tables Guide. Related concepts: “The data tables sample exit programs” on page 18 Exit XDTRD The XDTRD user exit is invoked just before CICS attempts to add to the data table a record that has been retrieved from the source data set.
Page 64 Return codes UERCDTAC UERCDTRJ UERCDTOP Customization Guide 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.
Page 65 XPI calls All can be used. Exit XDTAD The XDTAD user exit is invoked when a write request is issued to a data table. v For a user-maintained data table and coupling facility data table, the user exit is invoked once—before the record is added to the data table. v For a CICS-maintained data table, the user exit is invoked twice—before the record is added to the source data set and then again before the record is added to the data table.
Page 66 Return codes UERCDTAC UERCDTRJ XPI calls All can be used. Exit XDTLC The XDTLC user exit is invoked at the completion of data table loading—whether successful or not. The user exit is not invoked if the data table is closed for any reason before loading is complete.
Page 67: Dbctl Interface Control Program Exit Xxdfa
Return codes UERCDTOK UERCDTCL XPI calls All can be used. DBCTL interface control program exit XXDFA When invoked By an active CICS when its connection to DBCTL fails. Your exit program is invoked after the active CICS has informed the alternate CICS of the failure.
Page 68: Dbctl Tracking Program Exits Xxdfb And Xxdto
UERCABDU XPI calls TRANSACTION_DUMP must not be used. DBCTL tracking program exits XXDFB and XXDTO Exit XXDFB When invoked By the alternate CICS when it receives a message from the active CICS indicating that connection to DBCTL has failed. The alternate and active CICS systems are running in different MVS images, perhaps in different central processing complexes (CPCs).
Page 69: Dispatcher Domain Exits Xdsbwt And Xdsawt
Exit-specific parameters UEPDBXR Return codes UERCNOAC UERCSWCH UERCABNO UERCABDU The return code UERCNORM is not available for use at this exit point. XPI calls The following must not be used: v INQUIRE_MONITORING_DATA v MONITOR v TRANSACTION_DUMP v WRITE_JOURNAL_DATA. Dispatcher domain exits XDSBWT and XDSAWT The XDSBWT and XDSAWT exit points are located before and after the operating system wait.
Page 70: Dl/I Interface Program Exits Xdlipre And Xdlipost
XPI calls Must not be used. Exit XDSAWT When invoked After an operating system wait issued by the quasireentrant CICS TCB. Exit-specific parameters UEPSYSRC Return codes UERCNORM UERCNOSW XPI calls Must not be used. DL/I interface program exits XDLIPRE and XDLIPOST The XDLIPRE and XDLIPOST exit points are invoked following the issue of an EXEC DLI command or DL/I call.
Page 71 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 Programming: DL/I Calls manual. 2. For all EXEC DLI calls, the application’s parameter list is in assembler-language format (that is, the value of the program language byte pointed to by UEPLANG is always UEPASM, and the parameter list pointed to by UEPAPLIST is always in assembler-language format).
Page 72 UEPAPLIST UEPLANG UEPIOAX UEPIOA UEPPSBNX Customization Guide 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.
Page 73 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...
Page 74 UEPLANG UEPIOAX UEPIOA UEPUIBX UEPUIB Customization Guide The general format for PL/I is: plist address --> parm1 address --> parm1 (parmcount) parm2 address --> locator descriptor --> parm2 parm3 address --> locator descriptor --> parm3 up to a maximum of 18 parameters. When UEPCTYPE is not UEPCSHIP, your exit program can change any of the parameters in the application parameter list.
Page 75: Dump Domain Exits Xdureq, Xdureqc, Xduclse, And Xduout
Return codes UERCNORM UERCPURG XPI calls All can be used. Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUT There are four exits in the dump domain. Related concepts: “The dump domain sample exit program” on page 19 Exit XDUREQ When invoked Immediately before a system or transaction dump is taken.
Page 76 UEPXDSCP UEPXDTXN UEPXDSYS UEPXDTRM Customization Guide 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.
Page 77 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.
Page 78 Return codes UERCNORM UERCBYP UERCPURG XPI calls WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls. Related concepts: “The dump domain sample exit program” on page 19 Exit XDUREQC When invoked Immediately after a system or transaction dump has been taken (or has...
Page 79 UEPDUMPT Address of the 1-byte dump-type identifier, which contains one of the following values: UEPDTRAN A transaction dump was requested. UEPDSYST A system dump was requested. Note: The dump-type identifier indicates the type of dump request that was passed to the dump domain. It does not reflect any modification that may have been made to the original request by a user entry in the dump table.
Page 80 UEPXDMAX UEPDXDCNT UEPXDTST UEPXDDAE UEPDMPID UEPDRESP UEPDREAS Return codes UERCNORM XPI calls WAIT_MVS can be used only when a UEPDUMPT indicates that a transaction dump is being taken. Do not use any other calls. Customization Guide UEPXDNO The CICS system is not to shutdown. This field may be modified by the exit to update the dump table SHUTDOWN setting.
Page 81 Exit XDUCLSE When invoked Immediately after a transaction dump data set has been closed. Exit-specific parameters UEPTRANID Address of the 4-byte transaction ID. UEPUSER Address of the 8-byte user ID. UEPTERM Address of the 4-byte terminal ID. UEPPROG Address of the 8-byte application program name. UEPDMPDD Address of the 8-byte dump data set ddname.
Page 82: Enqueue Exec Interface Program Exits Xnqereq And Xnqereqc
UEPDMPBF UEPDMPLEN Return codes UERCNORM UERCBYP XPI calls WAIT_MVS can be used. Do not use any other calls. Enqueue EXEC interface program exits XNQEREQ and XNQEREQC The XNQEREQ exit allows you to intercept enqueue API requests before any action has been taken on the request. The XNQEREQC exit allows you to intercept the response after an enqueue API request has completed.
Page 83 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.
Page 84 UEPCLPS UEPNQTOK UEPRCODE UEPRESP UEPRESP2 UEPTSTOK UEPRECUR UEPSCOPE Return codes UERCNORM UERCPURG XPI calls All can be used. API and SPI commands All can be used, except for: You can update the copies of EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list.
Page 85 non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2, the values used by the enqueue domain are specified in DSECT DFHNQUED. Note: Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when issuing an enqueue request from the XNQEREQC exit.
Page 86 NQ_FUNCT NQ_BITS1 NQ_BITS2 NQ_EIDOPT5 NQ_EIDOPT6 NQ_EIDOPT7 NQ_EIDOPT8 NQ_ADDR1 is the address of an area containing the value from RESOURCE. NQ_ADDR2 is the address of the halfword value of LENGTH. NQ_ADDR3 is the address of the fullword value of MAXLIFETIME. Modifying fields in the command-level parameter structure: The fields that are passed to the enqueue domain are used as input to the request.
Page 87 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.
Page 88 1. CICS does not check changes to argument values, so any changes must 2. It is not advisable for XNQEREQC to modify input arguments. Adding user arguments: Global user exit programs can add arguments associated with the LENGTH and MAXLIFETIME keywords. You must ensure that the arguments you specify or modify in your exit programs are valid.
Page 89: Exec Interface Program Exits Xeiin, Xeiout, Xeispin, And Xeispout
Method C Related concepts: “The enqueue EXEC interface sample exit program” on page 19 Notes about the use of XNQEREQ to alter ENQ or DEQ scope.: 1. XNQEREQ enables you to allow existing applications to be converted to use sysplex enqueues without changing the application. Note: Use of either the ENQMODEL resource definition or the user exit allows 2.
Page 90 XEIOUT Invoked after the execution of any EXEC CICS API or SPI command. XEISPOUT Invoked after the execution of any EXEC CICS SPI command except those listed for XEISPIN. The sequence is: command Note: Asynchronous processing of these exits may occur if the transaction is suspended (for example, during file I/O wait).
Page 91 This particular example of the danger of tampering with argument 0 does not apply to COBOL or C application programs, but nevertheless you should not modify CICS commands for application programs written in any supported language. Bypassing commands An XEIIN or XEISPIN exit program can bypass execution of a command by setting the UERCBYP return code.
Page 92 UERCPURG XPI calls All can be used. Exit XEISPIN When invoked Before the execution of any EXEC CICS SPI command except: v EXEC CICS ENABLE v EXEC CICS DISABLE v EXEC CICS EXTRACT EXIT v EXEC CICS PERFORM DUMP v EXEC CICS RESYNC ENTRYNAME Exit-specific parameters UEPARG UEPEXECB...
Page 93 XPI calls All can be used. Exit XEIOUT When invoked After the execution of any EXEC CICS API or SPI command. Exit-specific parameters UEPARG Address of the EXEC command parameter list. UEPEXECB Address of the system EIB. UEPUSID Address of the 8-character userid. UEPPGM Address of the 8-character application program name.
Page 94: File Control Domain Exits, Xfcfrin And Xfcfrout
Exit-specific parameters UEPARG UEPEXECB UEPUSID UEPPGM UEPLOAD UEPRSA UEP_EI_PBTOK Return codes UERCNORM UERCPURG XPI calls All can be used. File control domain exits, XFCFRIN and XFCFROUT XFCFRIN If enabled, the XFCFRIN exit is invoked on entry to the main file control request gate, FCFR.
Page 95 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.
Page 96 Exit XFCFRIN When invoked Before the execution of a file control request. The request may have originated from: v The execution of an application request to process a user file v The receipt of a function-shipped request v An internal CICS request to process a system file. Exit-specific parameters UEPTRANID UEPUSER...
Page 97 UEP_FC_BUFFER_L Address of a fullword containing (for READ, READ NEXT, and READ PREV requests) the value of the LENGTH of the buffer into which the record is to be read. UEP_FC_RECORD_P Address of one of the following: v If the request is a READ, READ NEXT, or READ PREV with the SET option, a fullword in which is to be returned the address (output) of a buffer, into which the record will be placed.
Page 98 UEP_FC_RECORD_ID_TYPE UEP_FC_REQID UEP_FC_NUMREC UEP_FC_KEY_COMPARISON UEP_FC_GENERIC UEP_FC_MASS_INSERT Customization Guide 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. Address of a byte containing (for READ, WRITE, DELETE, START BR, READ NEXT, READ PREV, and RESET BR requests) the RIDFLD type.
Page 99 UEP_FC_SEQUENTIAL_WRITE Records are to be written in sequential mode. UEP_FC_DIRECT_WRITE Records are to be written in direct mode. UEP_FC_READ_INTEGRITY Address of a byte containing (for non-update READ, READ NEXT, and READ PREV requests) the read integrity setting. (In current versions of CICS, this setting applies only to VSAM RLS.) On input to the exit, this parameter will be set to one of: UEP_FC_CR Consistent read integrity is to be used.
Page 100 UEP_FC_DUPLICATE_KEY_CODE UEP_FC_ACCMETH_RETURN_CODE UEP_FC_RESPONSE UEP_FC_REASON Customization Guide Address of a 1-byte output area indicating whether the request found more than one record for the supplied key. The possible values are: v UEP_FC_DUPLICATE KEY v UEP_FC_NOT_DUPLICATE KEY Address of a 4-byte output area in which access-method- dependent information is to be returned when either of the responses UEP_FC_REASON_ACCMETH_REQUEST_ERROR or UEP_FC_REASON_IO_ERROR is returned.
Page 101 v UEP_FC_REASON_DUPLICATE_RECORD v UEP_FC_REASON_DUPLICATE_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_REASON_FULL_KEY_WRONG_LENGTH v UEP_FC_REASON_GENERIC_DELETE_NOT_KSDS v UEP_FC_REASON_GENERIC_KEY_TOO_LONG v UEP_FC_REASON_ILLEGAL_KEY_TYPE_CHANGE v UEP_FC_REASON_INSUFFICIENT_SPACE v UEP_FC_REASON_INVALID_UPDATE_TOKEN v UEP_FC_REASON_IO_ERROR v UEP_FC_REASON_KEY_LENGTH_NEGATIVE v UEP_FC_REASON_KSDS_AND_XRBA v UEP_FC_REASON_NO_VARIABLE_LENGTH v UEP_FC_REASON_NOTAUTH v UEP_FC_REASON_NOT_EXTENDED v UEP_FC_REASON_READPREV_IN_GENERIC_BROWSE v UEP_FC_REASON_RECORD_NOT_FOUND v UEP_FC_REASON_REWRITE_BEFORE_READ_UPDATE v UEP_FC_REASON_RIDFLD_KEY_NOT_RECORD_KEY v UEP_FC_REASON_UNKNOWN_REQID_ENDBR...
Page 102 UERCBYPL UERCPURG XPI calls All can be used. API and SPI calls None can be used. Exit XFCFROUT When invoked After the completion of a file control request. Exit-specific parameters UEPTRANID UEPUSER UEPTERM UEPPROG UEP_FC_FUNCTION UEPTSTOK UEP_FC_FILE_NAME Customization Guide Bypass CICS processing of this request. If the exit program has been invoked for a function-shipped request, the mirror transaction must not terminate.
Page 103 UEP_FC_BUFFER_P Address of a fullword containing the address of the buffer provided by the originator of the request, in which the record is returned on completion of a READ, READ NEXT, or READ PREV request with the INTO option. UEP_FC_BUFFER_L Address of a fullword containing (for READ, READ NEXT, and READ PREV requests) the value of the LENGTH of the buffer into which the record was read.
Page 104 UEP_FC_REQID UEP_FC_NUMREC UEP_FC_KEY_COMPARISON UEP_FC_GENERIC UEP_FC_MASS_INSERT UEP_FC_READ_INTEGRITY Customization Guide UEP_FC_KEY VSAM KSDS or AIX PATH access UEP_FC_RBA VSAM ESDS or KSDS via RBA access UEP_FC_RRN VSAM RRDS access UEP_FC_DEBKEY BDAM deblocking by key (READ, DELETE, START BR, and RESET BR requests only) UEP_FC_DEBREC BDAM deblocking by relative record (READ, DELETE, START BR, and RESET BR requests only)
Page 105 UEP_FC_CR Consistent read integrity. UEP_FC_FCT_VALUE Read integrity according to the setting in the FILE definition. UEP_FC_NRI No read integrity. UEP_FC_RR Repeatable read integrity. UEP_FC_TOKEN Address of a fullword containing the value of TOKEN. If the request is READ, READ NEXT, or READ PREV with update, and the address is not null, the area is an output field in which the token is returned.
Page 106 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_ERROR v UEP_FC_REASON_BDAM_DELETE v UEP_FC_REASON_BDAM_LENGTH_CHANGE v UEP_FC_REASON_BDAM_KEY_CONVERSION v UEP_FC_REASON_BDAM_READ_PREVIOUS v UEP_FC_REASON_BDAM_WRITE_MASS_INSERT v UEP_FC_REASON_BROWSE_UPD_NOT_RLS v UEP_FC_REASON_CACHE_FAILURE v UEP_FC_REASON_CFDT_CONNECT_ERROR v UEP_FC_REASON_CFDT_DISCONNECT_ERROR v UEP_FC_REASON_CFDT_INVALID_CONTINUATION v UEP_FC_REASON_CFDT_POOL_FULL...
Page 107: File Control Exec Interface Api Exits Xfcreq And Xfcreqc
UEP_FC_EXIT_TOKEN Return codes UERCNORM UERCPURG XPI calls All can be used. API and SPI calls None can be used. File control EXEC interface API exits XFCREQ and XFCREQC The XFCREQ exit allows you to intercept a file control application programming interface (API) request before any action has been taken on it by file control.
Page 108 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.
Page 109 v The address of a 16-byte area that is used if the request has been function shipped. The command-level parameter structure The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request.
Page 110 FC_GROUP FC_FUNCT FC_BITS1 FC_BITS2 FC_EIDOPT5 Customization Guide Always X'06', indicating that this is a file control request. One byte that defines the type of request: X'02' READ X'04' WRITE X'06' REWRITE X'08' DELETE X'0A' UNLOCK X'0C' STARTBR X'0E' READNEXT X'10' READPREV X'12' ENDBR...
Page 111 X'04' MASSINSERT specified. X'02' RRN specified. X'01' SET (and not INTO) was specified. Note: Your program must test for keywords at the bit level, because there may be more than one of these keywords present. FC_EIDOPT6 Indicates whether certain keywords that do not take values were specified on the request.
Page 112 FC_ADDR1 is the address of an 8-byte area containing the name specified on the FILE keyword. FC_ADDR2 is the address of one of the following: v A 4-byte address returned for SET (if the request is READ, READNEXT, or READPREV, and if FC_EIDOPT5 indicates that this is SET). v Data returned for INTO (if the request is READ, READNEXT, or READPREV, and if FC_EIDOPT5 indicates that this is not SET).
Page 113 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.
Page 114 Modifying input fields: The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data. Note: You must never modify an input field by altering the data that is pointed to by the command-level parameter list.
Page 115 X'04' REPEATABLE specified. X'02' UPDATE specified on READNEXT or READPREV. X'01' NOSUSPEND specified (on READ, READNEXT, READPREV, WRITE, DELETE, or REWRITE). Bits in the EID should be modified in place. You should not modify the pointer to the EID: any attempt to do so is ignored by CICS. The EID is reset to its original value before return to the application program.
Page 116 Use of the parameter UEPFSHIP UEPFSHIP contains the address of a 16-byte area. This area consists of 4 characters, followed by 3 fullwords. If the first byte contains 'Y', this request has been function shipped to this region. In this case, if your exit program wants to bypass file control (by setting a return code of UERCBYP), it must set the 3 fullwords as follows: Fullword 1...
Page 117 In XFCREQC: 1. Check ‘UEPRCODE’ to make sure that the file control request completed without error. 2. Use UEPFCTOK to find the address of the area. This area now holds the compressed data. 3. Decompress the data in place. 4. Copy the data from the new area to the user’s INTO area. Use the user-specified LENGTH (from the command-level parameter list) to ensure that the data fits and that the copy does not cause a storage violation.
Page 118 UEPFSHIP UEPRSRCE Return codes UERCNORM UERCBYP UERCPURG XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used, except for: Note: 1.
Page 119 ‘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).
Page 120: File Control Exec Interface Spi Exits Xfcareq And Xfcareqc
3. Exit programs that issue EXEC CICS commands, and that use the Example program CICS supplies, in CICSTS32.CICS.SDFHSAMP, an example program, DFH$XTSE, that shows how to modify fields in the command-level parameter structure passed to EXEC interface exits. DFH$XTSE is listed on page Appendix F, “The example program for the XTSEREQ global user exit, DFH$XTSE,”...
Page 121 4. XFCAREQC v For the INQUIRE FILE command, only the XFCAREQ and XFCAREQC exits are invoked: 1. XFCAREQ 2. XFCAREQC Exit XFCAREQ When invoked Before CICS processes a file control SPI request. Exit-specific parameters UEPCLPS Address of a copy of the SPI command parameter list. See “The command-level parameter structure”...
Page 122 Note: Take care when using recursive commands. For example, you must avoid entering a loop when issuing a file control SPI request from the XFCAREQ exit. Use of the recursion counter UEPRECUR is recommended. Exit XFCAREQC When invoked After a file control SPI request has completed, before return from the file control SPI EXEC interface program.
Page 123 values into the application program’s EXEC interface block (EIB) after the completion of XFCAREQC or if you specify a return code of UERCBYP in XFCAREQ. You must set valid file control responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by file control to describe a valid completion.
Page 124 v FCIS_BITS4 v FCIS_BITS5 v FCIS_BITS6 v FCIS_BITS7 v FCIS_BITS8 FCIS_GROUP FCIS_FUNCT FCIS_EIDOPT2 FCIS_EIDOPT3 FCIS_EIDOPT4 FCIS_BITS1 FCIS_BITS2 Customization Guide Always X'4C', indicating that this is a file control SPI request. One byte that defines the type of request: X'02' INQUIRE FILE X'04' SET FILE.
Page 125 X'40' Set if the request contains an argument for the ADD keyword. If set, FCIS_ADDR10 is meaningful. X'20' Set if the request contains an argument for the DELETE keyword. If set, FCIS_ADDR11 is meaningful. X'10' Set if the request contains an argument for the DISPOSITION keyword.
Page 126 FCIS_BITS5 FCIS_BITS6 FCIS_BITS7 Customization Guide 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.
Page 127 FCIS_BITS8 FCIS_ADDR1 is the address of an 8-byte area containing the name from FILE. FCIS_ADDR2 is the address of a 44-byte area containing the name from DSNAME. FCIS_ADDR3 is the address of a 4-byte area containing the CVDA from FWDRECOVSTATUS. FCIS_ADDR4 is the address of a 4-byte area containing the data from STRINGS.
Page 128 FCIS_ADDR15 is the address of a 4-byte area containing the CVDA from ENABLESTATUS. FCIS_ADDR16 is the address of a 4-byte area containing the CVDA from RECOVSTATUS. FCIS_ADDR17 is the address of a 4-byte area containing the CVDA from ACCESSMETHOD. FCIS_ADDR18 is the address of a 4-byte area containing the CVDA from TYPE.
Page 129 FCIS_ADDR37 to FCIS_ADDR51 are not used by file control. FCIS_ADDR52 is the address of a 4-byte area containing the data from JOURNALNUM. FCIS_ADDR53 is the address of a 4-byte area containing the data from LOADTYPE. FCIS_ADDR54 is the address of a 4-byte area containing the data from CFDTPOOL. FCIS_ADDR55 is the address of a 4-byte area containing the data from TABLENAME.
Page 130 Table 5. INQUIRE FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Arg16 Arg17 Arg18 Arg19 Arg20 Arg21 Arg22 Arg23 Arg24 Arg25 Arg26 Arg27 Arg28 Arg29 Arg30 Arg31 Arg32 Arg33 Arg34 Arg35 Arg36 Arg37 to Arg51 Arg52 Arg53...
Page 131 Table 6. SET FILE requests (continued). The relationship between arguments, keywords, data types, and input/output types. Argument Keyword Arg2 DSNAME Arg3 FWDRECSTATUS Arg4 STRINGS Arg5 Arg6 LSRPOOLID Arg7 READ Arg8 UPDATE Arg9 BROWSE Arg10 Arg11 DELETE Arg12 DISPOSITION Arg13 EMPTYSTATUS Arg14 OPENSTATUS Arg15...
Page 132 Note: You must never modify an input field by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field.
Page 133: File Control File State Program Exits Xfcsreq And Xfcsreqc
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. v For output and input/output arguments, your exit program can update the argument in place, because the area of storage is represented in the application by a variable that is expected to receive a value from CICS.
Page 134 For a CLOSE WAIT command, the exits are invoked as follows. XFCSREQ is invoked, the task requests a closure of the file and waits for the closure to happen. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that closed it.
Page 135 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.
Page 136 Customization Guide UEFJRU Journal read for update UEFJWU Journal write update UEFJWA Journal write add UEFJDSN Dsname has been journaled UEFJSYN Journal read synchronously UEFJASY Journal write asynchronously. UEFDSVJL One byte indicating a further automatic journaling option which applies to VSAM files only. The value is: UEFJWAC Write add complete.
Page 137 UEFACBCP This field is set to nulls in this exit. Note: Only the first seven fields of UEPFINFO are set for this exit. Of the remaining fields, URFFRCLG is set to blanks, and the others are set to nulls. UEPRECUR Address of a halfword recursion counter.
Page 138 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 UEPFILE UEPFINFO Customization Guide Address of a 2-byte field that indicates the type of file request. The first byte contains one of the following values: UEPFSOPN Open request...
Page 139 UEFLNAME The 8-character file name. UEDSNAME The 44-character dsname of the data set associated with the file. UEFSERV One byte indicating the SERVREQ settings for this file. The possible values are: UEFRDIM Read valid UEFUPDIM Update valid UEFADDIM Add valid UEFDELIM Delete valid UEFBRZIM...
Page 140 Customization Guide UEFVSAM VSAM file UEFBDAM BDAM file UEFDTBL Data table file UEFDTUM User data table file UEFCFDT Coupling facility data table UEFBCRV One byte indicating the recovery attributes of the data set associated with this file. The possible values are: UEFBCFR Forward recovery specified UEFBCLOG...
Page 141 Return codes UEPFBCAS Data set marked unavailable. UEFACBCP Address of a read-only copy of the ACB for a VSAM file, or the DCB for a BDAM file. Set only after completion of a successful open. If UEFDTBL and UEFDTUM have been set on, then the storage addressed by UEFACBCP is undefined.
Page 142 UERCPURG XPI calls All can be used. API and SPI calls All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. Note: 1. Take care when issuing recursive commands not to cause a loop. For 2. Exit programs that issue EXEC CICS commands must first address the 3.
Page 143: File Control Open/Close Program Exit Xfcnrec
associated with the file, as described by fields UEFLNAME and UEDSNAME in the DFHUEFDS DSECT. 3. Issues a WRITE OPERATOR command to write as much data as has been created in the 690 bytes of storage to the system console. 4.
Page 144: File Control Quiesce Receive Exit, Xfcvsds
XFCNREC. If the base cluster block is set as unrecoverable and a mismatch has been allowed, access may be allowed to the data set, via an unrecoverable file, before the data set is fully recovered. To provide a means of selecting which mismatches to accept and which to reject, three parameters are passed to the exit.
Page 145 Exit XFCVSDS When invoked Invoked after VSAM RLS has informed CICS that processing is required as a result of a data set-related action occurring in the sysplex. Exit-specific parameters UEPDSNAM Address of a 44-byte field containing the name of the data set to which the action applies UEPVSACT Address of a 1-byte field indicating the RLS action of which CICS...
Page 146: File Control Quiesce Send Exit Xfcquis
A return code of UERCPURG is not allowed. XPI calls All can be used. API and SPI calls You can use CICS API and SPI commands at this exit. In general all can be used, with the following restrictions: v You should avoid the use of commands that cause the issuing task to v You must not use EXEC CICS SHUTDOWN or EXEC CICS XCTL.
Page 147 Rejected—see UEPQCONF for the reason code. UEQUNKNO Failed because data set not known to DFSMS as a VSAM data set. UEQIOERR Failed because of RLS error or SMSVSAM server not available. UEQCANCL Failed because quiesce was canceled by user (UEQSD and UEIMQSD only).
Page 148: File Control Recovery Program Exits Xfcbfail, Xfcbout, Xfcbover, And Xfcldel
File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and XFCLDEL CICS provides four global user exits that you can use in connection with file control recovery operations. These are: XFCBFAIL Invoked when an error occurs during backout. XFCBOUT Invoked when CICS is about to back out a file update. XFCBOVER Invoked when CICS is about to skip unit-of-work (UOW) backout because a batch program has overridden RLS retained lock protection and opened a...
Page 149 point; the TBEXITS parameter allows only one exit program at each exit point. PLTPI processing is described in Chapter 4, “Writing initialization and shutdown programs,” on page 425. Exit XFCBFAIL, file control backout failure exit XFCBFAIL is invoked whenever there is a failure during backout of an update made to a file record.
Page 150 UENOSPAC Data set out of storage. UEOPENER Error opening the file. UERLSERR SMSVSAM RLS server failure. UERLSDIS RLS access is currently disabled. UERLSCON Attempt to continue a thread with a new instance of the SMSVSAM RLS server.
Page 151 UERCBYP Ignore the error (do not invoke CICS backout failure control) and continue. Setting this return code could be damaging to the integrity of your data. A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because the conditions under which this exit is invoked mean that a purged condition cannot be returned by any XPI or API calls.
Page 152 record on the data set with the “before-image” held in the log record addressed by UEPBLOGR. Use parameter UEPFCRSP to determine which error occurred. XBFEWR An error response has been returned from the file control file-request-handler program while processing a WRITE request. This request is issued by file control backout to add the “before-image”...
Page 153 Migration note: XFCBOUT replaces the function provided for file control, in releases before CICS Transaction Server for OS/390, Version 1 Release 1, by the XDBIN and XRCINPT exits. In earlier releases: v XDBIN was invoked when a dynamic log record was processed during dynamic backout.
Page 154 FBO entry is not supplied (there is no FBO table in CICS Transaction Server for z/OS, Version 3 Release 2). However, the file name is in the log record, so your exit program can use an EXEC CICS INQUIRE FILE command to get information about the file.
Page 155 VSAM RLS locks individual records within a data set, and these locks are converted to retained locks for those UOWs that are not completed because of backout or in-doubt failures, thus preserving data integrity. To avoid corruption of a data set by a non-RLS batch job, which is not aware of the retained record locks, a data set cannot normally be opened for update in non-RLS mode if it has any locked records.
Page 156 UERCNORM UERCBCKO A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this global user exit is invoked during syncpoint phase 2, and therefore cannot get a purged response from any calls that it makes.
Page 157 – 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.
Page 158 UEPFLEN Return codes UERCFAIL UERCLDEL A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because the conditions under which this exit is invoked should mean that “purged” cannot be returned by any XPI or API calls.
Page 159: Front End Programming Interface Exits Xszarq And Xszbrq
– An eye-catcher ‘DFH$FCLD ENTRY’ – The unmarked file control request data – The file control portion of the log record. v Issues an EXEC CICS INQUIRE FILE command to check the access method and type to confirm that the file is a VSAM ESDS or BDAM data set. The logical delete exit should have been invoked only if the file is one of these types.
Page 160: Good Morning Message Program Exit Xgmtext
Good morning message program exit XGMTEXT When invoked Before the good morning message is transmitted. Exit-specific parameters UEPTCTTE UEPTIOA Return codes UERCNORM UERCPURG XPI calls All can be used. HTTP client open and send exits: XWBAUTH, XWBOPEN and XWBSNDO Exits XWBAUTH, XWBOPEN, and XWBSNDO are invoked during processing of EXEC CICS WEB CONVERSE, EXEC CICS WEB OPEN, EXEC CICS INVOKE WEBSERVICE, and EXEC CICS WEB SEND commands.
Page 161 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.
Page 162 v Examine the type of request and the resource being accessed (which can be discovered by examining the request parameter list). The program could, for example, reject file read requests but queue file updates. Note: Because a failure of the exit program could affect system availability, it is There are some problems that XISCONA cannot solve.
Page 163 UEPEIPPL Address of the request parameter list. UEPCONTY A 1-byte field indicating the connection-type. Possible values are: UEPMRO (X'80') Request for an MRO connection UEPLU6 (X'40') Request for an LU6.1 connection UEPLUC (X'20') Request for an LU6.2 connection. UEPNETNM An 8-character field containing the NETNAME for the connection- that is, the identifier (applid) of the remote CICS region or system.
Page 164 Note that this exit is invoked only if the request to be shipped is of type EXEC CICS START NOCHECK. For EXEC CICS requests other than those with the NOCHECK option (which is only available on START commands) the ‘SYSIDERR’ condition is raised in the application program.
Page 165: Interval Control Program Exits Xicreq, Xicexp, And Xictenf
UERCPURG XPI calls All can be used. Important There is no ‘UERCNORM’ return code at this exit point, because the exit is invoked after a failure. The choice is whether to take the system default action or to handle the error in some other way. Interval control program exits XICREQ, XICEXP, and XICTENF You can use some XPI calls in exit programs invoked from the interval control program.
Page 166 Note: Return codes UERCNORM UERCPURG XPI calls The following must not be used: v ADD_SUSPEND v DELETE_SUSPEND v DEQUEUE v ENQUEUE v RESUME v SUSPEND v WAIT_MVS. Exit XICEXP When invoked After an interval control time interval has expired. Exit-specific parameters UEPICE Return codes UERCNORM...
Page 167: Interval Control Exec Interface Program Exits Xicereq, Xiceres, And Xicereqc
Exit XICTENF When invoked Exit XICTENF is also invoked from the interval control program. However, this exit relates to the ‘terminal not known’ condition and so is considered in detail in “‘Terminal not known’ condition exits XALTENF and XICTENF” on page 224.
Page 168 v For dynamically-routed transactions—only dynamically-routed (non-terminal-related) START requests cause the exit to be invoked. Thus, a dynamically-routed transaction that was initiated by a terminal-related EXEC CICS START command does not cause the exit to be invoked. v If it is disabled. v If an XICEREQ exit program chooses to bypass the request.
Page 169 Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 152. UEPICTOK Address of a 4-byte token to be passed to XICEREQC. This allows you, for example, to pass a work area to exit XICEREQC. UEPRCODE Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’.
Page 170 Note: Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when an interval control request is issued from the XICEREQ exit. Use of the recursion counter UEPRECUR is recommended. Exit XICERES When invoked By the interval control program, before processing of a non-terminal-related...
Page 171 UERCNORM Continue processing. UERCPURG Task purged during XPI call. UERCRESU A required resource is unavailable. Setting this value causes CICS to reject the routed request, and to return a value of 'F' (resource unavailable) in the DYRERROR field of the routing program's communications area.
Page 172 UEPDATE UEPTIME UEP_IC_REMOTE_SYSTEM UEP_IC_REMOTE_NAME Return codes UERCNORM UERCPURG XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, you are recommended to use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI commands All can be used, except for: Note: Take care when issuing recursive commands.
Page 173 X'10’ Interval control, except X'4A’ ASKTIME or FORMATTIME ADDR0 ..08 ..ADDR1 Interval|time|reqid|A(into)|set | abstime ADDR2 Reqid|length | yyddd ADDR3 Transid|set|into | yymmdd ADDR4 A(from) | yyddmm ADDR5 data length | ddmmyy ADDR6 Termid | mmddyy ADDR7 Sysid | date...
Page 174 the request. The remaining addresses point to pieces of data associated with the request. For example, the second address points to the interval for START requests. You can examine the EID to determine the type of request and the keywords specified.
Page 175 IC_GROUP X'10' This is an interval control request. X'4A' This is an ASKTIME or FORMATTIME command. IC_FUNCT One byte that defines the type of request. If IC_GROUP = X'10': X'02' ASKTIME X'04' DELAY X'06' POST X'08' START X'0A' RETRIEVE X'0C' CANCEL If IC_GROUP = X'4A': X'02'...
Page 176 IC_BITS3 IC_EIDOPT5 IC_EIDOPT6 Customization Guide X'80' Set if the request specifies RTERMID, or if a FORMATTIME request specifies DATESEP. If set, IC_ADDR9 is meaningful. X'40' Set if the request specifies QUEUE. If set, IC_ADDRA is meaningful. X'20' Set if the request specifies HOURS. If set, IC_ADDRB is meaningful.
Page 177 X'04' YEAR was specified on a FORMATTIME command, or MINUTES was specified. X'02' TIME was specified on a FORMATTIME command, or PROTECT was specified. X'01' TIMESEP was specified on a FORMATTIME command, or NOCHECK was specified. IC_EIDOPT7 Indicates whether certain functions or keywords were specified on the request.
Page 178 IC_ADDR2 is the address of one of the following: v An 8-byte area containing the value of REQID (if the request is DELAY, POST or START). v A halfword containing the value of LENGTH (if the request is RETRIEVE). Warning: For requests that specify INTO, do not change the value of LENGTH to a value greater than that specified by the application.
Page 179 v A fullword containing the value of DAYCOUNT. IC_ADDRB is the address of one of the following: v An area containing the value of HOURS. v A fullword containing the value of DAYOFWEEK. IC_ADDRC is the address of one of the following: v An area containing the value of MINUTES.
Page 180 The following are always input fields: v INTERVAL 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 DATE v DATEFORM v DAYCOUNT v DAYOFMONTH v DAYOFWEEK v DDMMYY...
Page 181 ABSTIME is an input field on a FORMATTIME request, and an output field on an ASKTIME request. DATESEP and TIMESEP can be input fields on a FORMATTIME request. Modifying input fields: The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data.
Page 182 X'40' X'20' X'10' X'08' IC_EIDOPT6 X'20' X'10' X'08' X'04' X'02' X'01' IC_EIDOPT7 Bits in IC_EIDOPT7 should only be modified within the same functional group - that is, only those existence bits defined as valid for a START request should be set on a START request. ASKTIME requests X'13' DELAY requests...
Page 183 IC_EIDOPT8 X'20' Unused by CICS. The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the interval control request only. Note: Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted.
Page 184: Loader Domain Exits Xldload And Xldelete
1. Scan the global work area (GWA) to locate a suitable CICS region (for 2. Having decided which system to route the request to, increment the use 3. Obtain a 4-byte area in which to store the SYSID for this request. This 4.
Page 185 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.
Page 186: Log Manager Domain Exit Xlgstrm
UEPPROGL UEPLDPT UEPENTRY UEPTRANID UEPUSER UEPTERM UEPPROG Return codes UERCNORM XPI calls Must not be used. API and SPI calls Must not be used. Log manager domain exit XLGSTRM There is one exit point, XLGSTRM, in the log manager domain. You can use XLGSTRM to modify a request to MVS to create a new log stream.
Page 187 If you do not provide a JOURNALMODEL resource definition for DFHLOG and DFHSHUNT, or if you use the CICS definitions supplied in group DFHLGMOD, the model log stream names default to &sysname.DFHLOG.MODEL and &sysname.DFHSHUNT.MODEL. For example, if a CICS region issues a request to create a log stream for its primary system log, and CICS is running in an MVS image with a sysid of MV10 and using the default JOURNALMODEL definition, the MVS system logger expects to find a model log stream named...
Page 188 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.
Page 189 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.
Page 190: Message Domain Exit Xmeout
Note: To run the sample program “as is”, you must first create a model log stream called 'CICSAD01.DEPT0001.MODEL100'. However, you will probably want to tailor the sample to suit your own environment. The code contains comments to help you do this. Related concepts: “The log manager domain sample exit program”...
Page 191 Important Because of the danger of recursion, your XMEOUT exit program should not try to reroute: v Any DFHTDxxxx messages, produced by the transient data program. v User domain messages in the range DFHUS0002 - DFHUS0006, plus message DFHUS0150. v Transaction manager messages DFHXM0212, DFHXM0213, DFHXM0304 and DFHXM0308.
Page 192 UEPTERM UEPPROG UEPMNUM UEPMDOM UEPMROU UEPMNRC UEPMTDQ UEPMNTD UEPINSN UEPINSA INSERT_FORMAT_P DS A Address of the 1-byte insert INSERT_P INSERT_LENGTH_P DS A Address of a fullword contain- INSERT_TYPE_P You can find the order of the inserts in the array from the entry for the particular message in the CICS Messages and Codes manual.
Page 193 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.
Page 194: Monitoring Domain Exit Xmnout
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 XMNOUT is invoked at the following event points: v Before an exception class monitoring record is passed to SMF v Before a performance class monitoring record is written to the performance record buffer v Before a transaction resource monitoring record is written to the transaction...
Page 195 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).
Page 196: Pipeline Domain Exits
XPI calls Pipeline domain exits Use the pipeline domain exits to customize the processing that occurs for inbound and outbound Web services in the pipeline. Exit XWSPRROO Use the XWSPRROO exit to access containers on the current channel after the Web services provider application issues the Web service response message and before CICS creates the body of the response message.
Page 197: Program Control Program Exits Xpcreq, Xpceres, Xpcreqc, Xpcftch, Xpchair, Xpcta, And Xpcabnd
If the request is a distributed program link, the XPCREQ exit is driven on both sides of the link; that is, in both the client and the server regions. The exit program is passed the address of the application’s parameter list (in UEPCLPS), and can modify this as required.
Page 198 Note: XPCERES XPCERES is invoked by the EXEC interface program before CICS processes either of the following kinds of dynamically-routed link request: v A distributed program link (DPL) call v A Link3270 bridge request Note that XPCERES is invoked: v After exit XPCREQ and before XPCREQC (if these exits are enabled). This means that: –...
Page 199 2. Reinvoke the routing program, on the routing region, for route selection failure. 3. Return a RESUNAVAIL condition on the EXEC CICS LINK command executed by the mirror on the target region. (This condition is not returned to the application program.) CICS ignores any changes made by the exit program to the values of any of the exit parameters.
Page 200 UEPRSRCE UEP_PC_PBTOK Return codes UERCBYP UERCNORM UERCPURG XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used, except for: Exit XPCERES: When invoked...
Page 201 UEPRECUR Address of a halfword recursion counter. Because the XPCERES exit can never be called recursively in the same transaction, the value of this field is always 0. UEPRESP Address of a 4-byte copy of EIBRESP. UEPRESP2 Address of a 4-byte copy of EIBRESP2. UEPTSTOK Address of a 4-byte token that is valid throughout the life of a task.
Page 202 UEPCLPS UEPPCTOK UEPRCODE UEPRECUR UEPRESP UEPRESP2 UEPTSTOK UEPRSRCE UEP_PC_REMOTE_SYSTEM UEP_PC_REMOTE_NAME UEP_PC_PBTOK Return codes UERCNORM Customization Guide Address of the command parameter list. Address of a 4-byte token passed from XPCREQ. This allows XPCREQ to, for example, pass a work area to XPCREQC. Address of a 6-byte hexadecimal copy of EIBRCODE.
Page 203 UERCPURG Task purged during XPI call. XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI calls All can be used, except for: EXEC CICS SHUTDOWN EXEC CICS XCTL...
Page 204 PC_ADDRA. It is defined in the DSECT PC_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHPCEDS. The command-level parameter list is made up as follows: PC_ADDR0 is the address of a 7-byte area called the EXEC interface descriptor (EID), which is made up as follows: v PC_GROUP v PC_FUNCT...
Page 205 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.
Page 206 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.
Page 207 Bits in the EID should be modified in place. You should not modify the pointer to the EID. (Any attempt to do so is ignored by CICS.) The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the program control request only.
Page 208 1. Scan the global work area (GWA) to locate a suitable CICS region - for example, the region currently processing the least number of LINK requests. 2. Having decided which system to route the request to, increment the use count for this system.
Page 209 terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCFTCH is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS v 1-byte flag field. A setting of PCUECBTE indicates that the transaction is linked to a terminal. v A setting of PCUENOTX (X'40') indicates that the program is not command level.
Page 210 Return codes UERCNORM UERCPURG UERCMEA XPI calls All can be used. The sample XPCFTCH global user exit program, DFH$PCEX Note that there is a CICS-supplied sample exit program, DFH$PCEX, that is designed to be driven by the XPCFTCH exit. For more information about DFH$PCEX, see “Sample global user exit programs”...
Page 211: Terminal-Related Information, And That Can Be Mapped Using The
BASSM 15,0 USING *,15 When invoked Before a HANDLE ABEND routine is given control. Exit-specific parameters UEPPCDS Address of a storage area that contains program- and terminal-related information, and that can be mapped using the DSECT DFHPCUE. When XPCHAIR is invoked, the following DFHPCUE fields are significant: PCUE_CONTROL_BITS 1-byte flag field.
Page 212 XPI calls All can be used. Exit XPCTA XPCTA is invoked immediately after a transaction abend, and before any processing that might modify the existing environment so that the task could not be resumed. You can use it to: v Set a resume address, instead of letting CICS process the abend v Specify the subspace that control is passed in.
Page 213 PCUE_LOGICAL_LEVEL Fullword containing the number of chained DFHRSADS blocks (that is, logical level). PCUE_BRANCH_ADDRESS Fullword. You can use this field to supply a resume address. Set the top bit to specify that the resumed task is to run AMODE (31). PCUE_BRANCH_EXECKEY If storage protection is active, you can use this 1-byte field to specify the execution key of the resumed task.
Page 214 DFH$PCTA can be extended for transaction isolation. Related concepts: “The transaction-abend sample exit program” on page 24 Exit XPCABND XPCABND is invoked after a transaction abend and before a transaction dump call: you can use it to suppress the dump. When invoked After a transaction abend and before a transaction dump call is made.
Page 215: Resource Manager Interface Program Exits Xrmiin And Xrmiout
UERCBYP UERCPURG XPI calls All can be used. Resource manager interface program exits XRMIIN and XRMIOUT Exit XRMIIN When invoked Before a task-related user exit program is invoked due to an application program issuing an RMI API request. Exit-specific parameters UEPTRUEN UEPTRUEP UEP_RM_PBTOK...
Page 216 UERCNORM UERCPURG XPI calls All can be used. API and SPI commands All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. However, CALLDLI, EXEC DLI, or EXEC SQL commands must not be used. Exit XRMIOUT When invoked After a task-related user exit program has returned from handling an RMI API request.
Page 217: Resource Management Install And Discard Exit Xrsindi
Return codes UERCNORM UERCPURG XPI calls All can be used. API and SPI commands All except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used. However, CALLDLI, EXEC DLI, or EXEC SQL commands must not be used. Note: It is not recommended that your exit program make calls to other external resource managers that use the RMI, because this causes recursion, and may result in a loop.
Page 218 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.
Page 219 UEIDDB2E A DB2 entry (DB2ENTRY) UEIDDB2T A DB2 transaction (DB2TRAN) UEIDDJAR A deployed JAR file (DJAR) UEIDDOCT A DOCTEMPLATE UEIDFECO A FEPI connection UEIDFENO A FEPI node UEIDFEPO A FEPI pool UEIDFEPS A FEPI propertyset UEIDFETA A FEPI target UEIDFILE A file UEIDIPCO An IPIC connection ( “IPCONN”)
Page 220 UEPIDLEN UEPIDNUM UEPIDNAM UEPIDREC Return codes UERCNORM Customization Guide 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...
Page 221: Signon And Signoff Exits Xsnon, Xsnoff, And Xsnex
When a 'CANCEL' command is entered to terminate a CRTE routing session v A timeout sign-off. XSNEX is a special-purpose global user point, which is intended to be used only with the IBM-supplied global user exit program, DFH$SNEX. Exit XSNON When invoked When a user signs on.
Page 222 UEPTRMID UEPTCTUA UEPTCTUL UEPTRMTY UEPSNFLG Table 8. Flags set in the UEPSNFLG field of XSNON Flag UEPSNOK UEPSNFL UEPSNPSS UEPSNPSF Return codes UERCNORM UERCPURG XPI calls All can be used. Exit XSNOFF When invoked When a user signs off. Exit-specific parameters UEPUSRID UEPUSRLN UEPGRPID...
Page 223 CICS SIGNOFF command. You are not intended to write your own global user exit program for this exit point. IBM provides DFH$SNEX, the sole purpose of which is to make CICS handle EXEC CICS SIGNON and SIGNOFF commands in the same way as in CICS TS 1.3 and earlier.
Page 224: Statistics Domain Exit Xstout
To use this program, add an entry to the first section of your PLTPI table (that is, before the DFHDELIM statement). For example: DFHPLT TYPE=INITIAL,SUFFIX=SN DFHPLT TYPE=ENTRY,PROGRAM=DFH$SNPI DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM DFHPLT TYPE=FINAL Statistics domain exit XSTOUT On invocation, XSTOUT is passed the address of a buffer containing one or more statistics records.
Page 225: System Recovery Program Exit Xsrab
UEPSTYPE UEPSDATE UEPSTIME UEPSIVAL UEPSIVN UEPSCLD Return codes UERCNORM UERCBYP XPI calls WAIT_MVS can be used. Note, however, that the wait cannot be purged using CEMT or SPI. Do not use any other calls. System recovery program exit XSRAB When invoked When the system recovery program (DFHSRP) finds a match in the SRT for an MVS abend code.
Page 226 Customization Guide SRP_ERROR_TYPE The 4-character error type—always ‘ASRB’. SRP_SYS_ABCODE 2 bytes containing the system abend code XXX in binary format (for example, D37). SRP_USER_ABCODE 2 bytes containing the user abend code NNNN in binary format (for example, 0999). SRP_ERROR_TRANID 4-character field containing the ID of the abending transaction.
Page 227 SRP_CICS_ERROR_REASON 4-character field containing the MVS abend reason code. It contains a value only if flag SRP_VALID_REASON is set. SRP_CICS_ERROR_DATA An area describing the last thing that CICS did, prior to the abend. It contains the following: SRP_CICS_EC_PSW 8-character field containing the extended control (EC) mode program status word (PSW) SRP_CICS_EC_INT 8-character field containing the interrupt code and...
Page 228: System Termination Program Exit Xsterm
Return codes UERCNOCA UERCCANC UERCCICS XPI calls Because CICS invokes the exit XSRAB in an error environment, you can only use a subset of the XPI calls. Only TRACE_PUT is available for general use. You can use WAIT_MVS, but only after the exit program has determined (from the SRP_CICS_CODE and SRP_USER_CODE fields) that the abend has occurred in user application code, and not in CICS code.
Page 229: Temporary Storage Domain Exits Xtsqrin, Xtsqrout, Xtsptin, And Xtsptout
XPI calls All other XPI calls except WRITE_JOURNAL_DATA can be used. However, their use is not recommended, because they could cause the task to lose control, thus allowing another task to write more monitoring data. Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT The temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT allow you to:...
Page 230 UEP_TS_QUEUE_NAME UEP_TS_DATA_P UEP_TS_DATA_L UEP_TS_ITEM_NUMBER UEP_TS_STORAGE_TYPE Return codes UERCNORM UERCPURG XPI calls All can be used. API and SPI calls None can be used. Exit XTSQROUT When invoked After execution of a user temporary storage interface request for a user TS queue (for example, a WRITEQ TS, or READQ TS request).
Page 231 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 UEP_TS_FUN_READ_INTO v UEP_TS_FUN_READ_SET v UEP_TS_FUN_READ_NEXT_INTO v UEP_TS_FUN_READ_NEXT_SET v UEP_TS_FUN_DELETE UEP_TS_QUEUE_NAME Address of a 16-byte field containing the queue name. UEP_TS_DATA_P Address of a fullword containing the address of the data.
Page 232 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 UEPUSER UEPTERM UEPPROG UEP_TS_FUNCTION UEP_TS_QUEUE_NAME UEP_TS_DATA_P UEP_TS_DATA_L UEP_TS_STORAGE_TYPE Customization Guide Address of the 4-byte transaction ID. Address of the 8-byte user ID.
Page 233 Return codes UERCNORM Normal. UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI calls None can be used. Exit XTSPTOUT When invoked After execution of a temporary storage interface request for a CICS internal queue (for example, for interval control or BMS queues).
Page 234: Temporary Storage Exec Interface Program Exits Xtsereq And Xtsereqc
Return codes UERCNORM UERCPURG XPI calls All can be used. API and SPI calls None can be used. Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC The XTSEREQ exit allows you to intercept temporary storage API requests before any action has been taken on the request. The XTSEREQC exit allows you to intercept the response after a temporary storage API request has completed.
Page 235 Exit XTSEREQ When invoked Before CICS processes a temporary storage API request. Exit-specific parameters UEPCLPS Address of a copy of the command parameter list. See “The command-level parameter structure” on page 215. UEPTQTOK Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary storage request.
Page 236 Note: Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a temporary storage request from the XTSEREQ exit. Use of the recursion counter UEPRECUR is recommended. Exit XTSEREQC When invoked After a temporary storage API request has completed, before return from the temporary storage EXEC interface program.
Page 237 UERCPURG Task purged during XPI call. XPI calls All can be used. API and SPI commands All can be used, except for: EXEC CICS SHUTDOWN EXEC CICS XCTL You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. If you update the values, temporary storage copies the new values into the application program’s EIB after the completion of XTSEREQC or if you specify a return code of UERCBYP in XTSEREQ.
Page 238 The command-level parameter list is made up as follows. Note: The relationship between arguments, keywords, data types, and input/output types is summarized for the temporary storage commands in the following tables: Table 9. The relationship between arguments, keywords, data types, and input/output types for the temporary storage commands Command WRITEQ TS...
Page 239 X'02' Set if the request contains an argument for the SYSID keyword. If set, TS_ADDR7 is meaningful. TS_BITS2 Two bytes not used by temporary storage. TS_EIDOPT5 Indicates whether certain keywords were specified on the request. X'80' QNAME was specified (otherwise QUEUE). You can modify this bit in your user exit if you wish.
Page 240 TS_ADDR7 is the address of an area containing the value of SYSID. Modifying fields in the command-level parameter structure: Some fields that are passed to temporary storage are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.
Page 241 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.
Page 242 Table 11. READQ TS: User arguments and associated keywords, data types, and input/output types Argument Arg1 Arg1 Arg2 Arg2 Arg3 Arg4 Arg5 Arg6 Arg7 Table 12. DELETEQ TS: User arguments and associated keywords, data types, and input/output types Argument Arg1 Arg1 Arg2 Arg3...
Page 243: Terminal Allocation Program Exit Xalcaid
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.
Page 244 UEPALLEN UEPALRQD UEPALQUE UEPALRTE UEPALRTA UEPALFMH UEPALSTC UEPALCHN Return codes UERCNORM XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM No other XPI calls should be used. API and SPI commands No EXEC CICS commands can be used. Customization Guide Address of a fullword binary field containing the length of the FROM data;...
Page 245: Terminal Control Program Exits Xtcin, Xtcout, And Xtcatt
Note: The XALTENF exit, used to handle the “terminal not known” condition, is also invoked from the terminal allocation program. XALTENF is described on page “‘Terminal not known’ condition exits XALTENF and XICTENF” on page 224. Terminal control program exits XTCIN, XTCOUT, and XTCATT Exit XTCIN When invoked After an input event for a sequential device.
Page 246: Terminal Not Known' Condition Exits Xaltenf And Xictenf
XPI calls All can be used. However, note that you cannot use a GETMAIN call to obtain terminal-class storage for use as a replacement TIOA. Exit XTCATT When invoked Before task attach. Exit-specific parameters UEPTCTTE UEPTIOA UEPTCTLE UEPTRAN Return codes UERCNORM XPI calls All can be used.
Page 247 in the local system. If the requested terminal is remote, the terminal allocation program ships an ATI request to the remote system, which initiates transaction routing back to the local system. For guidance information about ATI, refer to the CICS Intercommunication Guide.
Page 248 UERCNETN Netname of TOR returned UERCSYSI Sysid of TOR returned. For return codes UERCNETN and UERCSYSI, the exit program must place the netname or sysid of the terminal-owning region in fields UEPxxNTO or UEPxxSYO (where xx is AL or IC). If the terminal-owning region is a member of a VTAM generic resource, the exit program should place the netname of the terminal in field UEPxxNNO.
Page 249 UEPALTRN Address of 4 bytes containing the name of the transaction to be run. UEPALRTR Address of 4 bytes containing the name of the terminal on which the transaction should run. (If a transient data trigger level was reached and the transient data queue definition specified a system, then this would contain a system identifier.) UEPALCTR Address of 4 bytes containing, for START commands, the name of...
Page 250 Return codes UERCTEUN UERCNETN UERCSYSI XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM. No other XPI calls should be used. Exit XICTENF When invoked By the interval control program when the terminal that an EXEC CICS START command requires is unknown in this system. The exit program is expected to give a return code indicating whether the terminal exists on another connected CICS system and, if so, on which one.
Page 251 UEPICFN A START command was not being processed or a START was being processed but it was not function shipped. UEPICTRN Address of 4 bytes containing the name of the transaction to be run. UEPICRTR Address of 4 bytes containing the name of the terminal on which the transaction should run.
Page 252 Return codes UERCTEUN UERCNETN UERCSYSI UERCPURG XPI calls The following must not be used: v ADD_SUSPEND v DELETE_SUSPEND v DEQUEUE v ENQUEUE v RESUME v SUSPEND v WAIT_MVS. The sample program for the XALTENF and XICTENF exits, DFHXTENF One program can be used for both exits, or a separate program can be written for each.
Page 253 DFHXTENF CSECT DFHVM XTENF ENTRY DFHXTENA DFHXTENA DS R14,R12,12(R13) BALR R11,0 USING *,R11 USING DFHUEPAR,R1 Could check the terminal ID at this point. In this program we assume it is valid. We also choose to accept START requests and reject Transient Data trigger level events.
Page 254: Transaction Manager Domain Exit Xxmatt
Important The example in Figure 2 on page 231 is intended purely as a demonstration of some of the possibilities available, and would be impractical in a production environment. Related concepts: “The terminal-not-known sample exit program” on page 25 Transaction manager domain exit XXMATT Exit XXMATT When invoked During transaction attach.
Page 255 transaction specified on DTRTRAN is attached and CICS considers that the transaction has been found. Equated values are: UEATFND The transaction was found. UEATNFND The transaction was not found. UEPATTST The address of a 1 byte transaction definition state. Equated values for the definition state are: UEATENAB The transaction is enabled.
Page 256: Transient Data Program Exits Xtdreq, Xtdin, And Xtdout
Transient data program exits XTDREQ, XTDIN, and XTDOUT Exit XTDREQ When invoked Before request analysis. Exit-specific parameters UEPTDQUE UEPTDTYP Return codes UERCNORM UERCTDOK UERCTDNA UERCPURG XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM v WAIT_MVS Do not use any other calls. Exit XTDIN When invoked After receiving data from QSAM (for extrapartition) or VSAM (for...
Page 257 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.
Page 258: Transient Data Exec Interface Program Exits Xtdereq And Xtdereqc
UERCPURG XPI calls You can use: v INQ_APPLICATION_DATA v INQUIRE_SYSTEM v WAIT_MVS Do not use any other calls. Transient data EXEC interface program exits XTDEREQ and XTDEREQC The XTDEREQ exit allows you to intercept a transient data request before any action has been taken on it by transient data.
Page 259 Exit XTDEREQ When invoked Before CICS processes a transient data API request. Exit-specific parameters UEPCLPS Address of the command-level parameter structure. See “The UEPCLPS exit-specific parameter” on page 240. UEPTDTOK Address of the 4-byte token to be passed to XTDEREQC. This allows you, for example, to pass a work area to exit XTDEREQC.
Page 260 Note: Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a transient data request from the XTDEREQ exit. Use of the recursion counter UEPRECUR is recommended. Exit XTDEREQC When invoked After a transient data API request has completed, and before return from the transient data EXEC interface program.
Page 261 UERCNORM UERCPURG XPI calls All can be used. Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead. API and SPI commands All can be used, except for: Note: Take care when issuing recursive commands.
Page 262 You can examine the EID to determine the type of request and the keywords specified. You can examine the other parameters in the list to determine the values of the keywords. You can also modify values of keywords specified on the request. (For example, you could change the sysid specified in the request.) End of parameter list indicator The high-order bit is set on in the last address set in the parameter list to indicate...
Page 263 X'04' READQ X'06' DELETEQ. TD_BITS1 Existence bits that define which arguments were specified. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the argument was not specified in the request and the address should not be used.
Page 264 TD_ADDR4 is the address of a value intended for CICS internal use only. It must not be used. TD_ADDR5 is the address of a value intended for CICS internal use only. It must not be used. TD_ADDR6 is the address of a value intended for CICS internal use only. It must not be used.
Page 265 Modifying fields used for both input and output: An example of a field that is used for both input and output is LENGTH on a READQ request that specifies INTO. You can treat such fields in the same way as output fields, and they are considered to be the same.
Page 266: User Log Record Recovery Program Exits Xrcinit And Xrcinpt
You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. Transient data copies your values into the real EIB after the completion of XTDEREQC; or if you specify a return code of ‘ bypass’...
Page 267 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.
Page 268 name6 are the names of your user exit programs for XRCINIT, XRCINPT, XFCBFAIL, XFCLDEL, XFCBOVER, and XFCBOUT. v Enable the exits during the first stage of initialization using a PLTPI program. If you use the TBEXITS parameter to enable the exits, a global work area of 4 bytes is provided.
Page 269: Vtam Terminal Management Program Exit Xzcatt
UEPLGREC UEPLGLEN UEPTAID UEPTRID UEPTEID Note: The values of the fields addressed by UEPTAID, UEPTRID, and Return codes UERCNORM UERCBYP XPI calls All can be used. See page “User log record recovery program exits XRCINIT and XRCINPT” on page 244 for restrictions. VTAM terminal management program exit XZCATT Exit XZCATT When invoked...
Page 270: Vtam Working-Set Module Exits Xzcin, Xzcout, Xzcout1, And Xzique
UEPTPNL UEPTRAN Return codes UERCNORM XPI calls All can be used. VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, and XZIQUE Note: None of the exits in the VTAM working-set module is available for advanced program-to-program communication (APPC, or LUTYPE6.2) links. Exit XZCIN When invoked After an input event.
Page 271 UEPTCTTE Address of the terminal control table terminal entry (TCTTE). The TCTTE can be mapped using the DSECT DFHTCTTE. UEPTIOA Address of the terminal input/output area (TIOA). Your exit program should not change the address. The TIOA can be mapped using the DSECT DFHTIOA.
Page 272 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.
Page 273 Using the information passed in the parameter list, your global user exit program can decide (based on queue length, for example) whether CICS is to queue the allocate request. Your program communicates its decision to CICS by means of one of the return codes CICS provides.
Page 274 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.
Page 275 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.
Page 276 UEPPAD UEPFSPL UEPCONST UEPMODST UEPSTEX UEPEMXQT UEPMDGST Non-specific allocates data:The following three fields contain data relating to MRO, LU6.1, and non-specific APPC allocates: UEPSAQTS Customization Guide A 1-byte padding field. Address of the 10-byte function shipping parameter list. Address of the 158-byte system entry statistics record (this can be mapped using DSECT DFHA14DS).
Page 277 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.
Page 278 Sample exit program design: A sample XZIQUE exit program is provided with CICS Transaction Server for z/OS, Version 3 Release 2 as a base for you to design your own global user exit program. It is called DFH$XZIQ, and is supplied in the CICSTS32.CICS.SDFHSAMP library.
Page 279 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.
Page 280: Xisque Exit For Managing Ipic Intersystem Queues
Extensions to the sample program: The sample exit program does not attempt to control the queue length, or detect poor response for a particular modegroup differently from the whole connection. This kind of enhancement is something you might want to add to your own exit program if your applications request specific modegroups via the allocate command (or via a transaction profile) and you think it would be useful to control the modegroups individually.
Page 281 Exit-specific parameters UEPISDATA Address of the 78-byte area containing the information listed below. This area is mapped by the DSECT in copybook DFHXIQDS. Area addressed by UEPISDATA: UEPREQ A 2-byte origin-of-request code, which can have the following value: Function shipping (includes distributed program link.) UEPIPCNM The 8-byte name of the IPCONN.
Page 282 UERCAQUE UERCAPUR UERCAKLL UERCPURG In the case of a successful allocate following the use of UERCAKLL on a previous invocation of the exit, use one of the following: UERCNORM UERCAPUR XPI calls All can be used. Using an XISQUE global user exit program When the exit is enabled, your XISQUE global user exit program is able to check on the state of allocate queues for IPCONNs in the local system.
Page 283 number of allocates processed since the queue began, to determine the rate at which CICS is processing requests. The relevant fields are: UEPSAQTS and UEPSACNT. To determine whether CICS is allocating requests for sessions on this IPCONN at an acceptable rate, you can compare the calculated time with either of the following: 1.
Page 284 ISR_XISQUE_ALLOC_REJECTS Each time an XISQUE global user exit program returns with a request to reject a request, CICS increments this field, which is provided to help you tune the queue limit. Normally, if the number of sessions and the queue limit specified on the IPCONN definition are correctly balanced, and there has been no abnormal congestion on the link, ISR_XISQUE_ALLOC_REJECTS should be zero.
Page 285: Xrf Request-Processing Program Exit Xxrstat
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.
Page 286 v A predatory takeover. A “predatory takeover” can occur, if you are using VTAM Release 3.4.0 or above, and a VTAM application with the same APPLID as that of the executing CICS system assumes control of all the sessions of the executing CICS system.
Page 287 v For XRF, in the event of a VTAM failure: CICS continues processing as if the exit program had not been invoked. v For VTAM persistent sessions, in the event of a predatory takeover: CICS abends without a dump. UERCCOIG Ignore.
Page 288 Customization Guide...
Page 289: Chapter 2. Task-Related User Exit Programs
Responses from the resource manager are passed back to the calling program by the task-related user exit program. © Copyright IBM Corp. 1977, 2011...
Page 290 Application program DFHRMCAL Stub THE ADAPTER CICS SPI CICS manager syncpoint manager Figure 4. The adapter concept The task-related user exit program is provided with a parameter list (DFHUEPAR) by the CICS management module that handles task-related user exits. This parameter list gives the task-related user exit access to information such as the addresses and sizes of its own work areas.
Page 291: The Stub Program
The administration routines may also contain commands to retrieve information about one of the exit program’s work areas (the EXEC CICS EXTRACT EXIT command), and to resolve any inconsistency between CICS and a non-CICS resource manager after a system failure (the EXEC CICS RESYNC command). For programming information about the EXEC CICS ENABLE PROGRAM, DISABLE PROGRAM, EXTRACT EXIT, and RESYNC ENTRYNAME commands, refer to the CICS System Programming Reference manual.
Page 292: Returning Control To The Application Program
The application can use a parameter to determine whether the resource manager was called. For example, if the application sets a parameter to zero and the resource manager sets it to nonzero, the parameter value on return indicates whether the resource manager was invoked. Note: The only operands of the DFHRMCAL macro intended for customer use are TO, RTNABND, and SUPPEDF (the latter two being described below).
Page 293: Writing A Task-Related User Exit Program
Writing a task-related user exit program The main function of the task-related user exit program is to translate the calling program’s parameters into a form acceptable to your non-CICS resource manager, and then to pass control to the resource manager. You therefore need to be familiar with your resource manager’s syntax requirements.
Page 294 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.
Page 295: User Exit Parameter Lists
Application program call (API)—UERTAPPL For this call, CICS always invokes the TRUE on an L8 mode TCB CICS syncpoint manager call—UERTSYNC For this call, CICS always invokes the TRUE on an L8 mode TCB CICS task manager call—UERTTASK For this call, the TCB on which CICS invokes the TRUE is further determined by the type of task manager call: UERTSOTR—Start of task UERTEOTR —End of task...
Page 296 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 the resource manager qualifier name v The address of the resource manager’s “single-update”...
Page 297 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.
Page 298 UEPRMQUA Address of an 8-byte field into which the task-related user exit can move the qualifier name of the resource manager on each API request. This is useful where the same exit program is used to connect to more than one instance of a resource manager;...
Page 299 UEPTJ9 The J9 open TCB, used for JVMs that are in user key UEPTJM The JM open TCB, used with the IBM SDK for z/OS, V1.4.2 for the master JVM that initializes the shared class cache UEPTL8 An L8 open TCB, used for OPENAPI TRUEs, or OPENAPI...
Page 300 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.
Page 301 Caller parameter lists In addition to the DSECTs DFHUEPAR and DFHUERTR, the inclusion of DFHUEXIT TYPE=RM in the task-related user exit program provides some field definitions that are specific to the caller of the task-related user exit. The calling program’s parameter list is normally addressed by R1 in the calling program’s RSA. This RSA is addressed by field UEPHMSA of DFHUEPAR.
Page 302 messages for resource recovery. They are presented explicitly because, after a system failure, the task driving the exit is not the task that originally scheduled the recoverable work. These additional parameters describe the original task’s environment and are accessed directly. The full parameter list is as follows: Parameter 1 The address of operation byte 1, which contains the following flags:...
Page 303 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.
Page 304 1. Parameters 2 through 8 contain values only if the CICS syncpoint 2. Unless the UERTLAST bit is set in operation byte 1, parameter 9 is a CICS task manager parameters: There are either one or two entries in the CICS task manager’s parameter list, depending on the reason for the call to the TRUE: on start-of-task calls, the parameter list contains one entry, while on end-of-task calls, it contains two.
Page 305 UERTCABY (X'20') CICS abend, retry possible, TCBs dispatchable UERTCABN (X'10') CICS abend, retry not possible, TCBs dispatchable UERTOPCA (X'01') CICS abend, retry not possible, TCBs not dispatchable. For further information about shutdown TRUEs, see “Coding a program to be invoked at CICS termination” on page 298. CICS context management parameters: CICS context management parameters are those parameters that CICS passes when a task-related user exit signals that CICS should be called for CICS context...
Page 306 UEPEDFRA UEPEDFRC UEPEDFSC UEPEDFWS UEPEDFNO UEPEDFFO The output flag byte. If the task-related user exit requires, it can set the UEPEDFFO flag byte to indicate to EDF what action the task-related user exit wants EDF to take. It can take the following values: UEPEDFDF UEPEDFND UEPEDFRD...
Page 307 DISPLAY DATA UEPEDFPA Address of attribute byte Address of data field Address of attribute byte Address of attribute byte Address of data field Figure 6. Display data parameter list Note: Summary of the task-related user exit parameter lists Figure 7 on page 286 shows, in diagrammatic form, the relationships between the parameter lists that are discussed in the preceding sections.
Page 308 CICS SPI Application call program call DFHUEPAR DFHUEPAR UEPEXN UEPEXN UEPGAA UEPGAA UEPGAL UEPGAL UEPHMSA UEPHMSA UEPTAA UEPTAA UEPTAL UEPTAL UEPEIB UEPEIB UEPURID UEPURID UEPFLAGS UEPFLAGS UEPRMSTK UEPRMSTK UEPUOWDS UEPUOWDS UEPSECFLG UEPSECFLG UEPSECBLK UEPSECBLK UEPRMQUA UEPRMQUA UEPCALAM UEPCALAM UEPSYNCA UEPSYNCA UEPTIND UEPTIND UEPPBTOK...
Page 309: The Schedule Flag Word
The schedule flag word The schedule flag word is a fullword indicator that the task-related user exit program uses to control its own invocation. It is also used by CICS to schedule the first invocation of a task-related user exit program. The schedule flag word is accessed by the address parameter UEPFLAGS of DFHUEPAR.
Page 310: Register Handling In The Task-Related User Exit Program
flag word. When the calling application program subsequently issues a syncpoint command, or when end-of-task is reached, the CICS syncpoint manager calls the exit program. Note: CICS sets the syncpoint manager bit off after every call to the syncpoint manager. This is to avoid the CICS syncpoint manager invoking the task-related user exit program for a unit of recovery during which the exit program did no recoverable work.
Page 311: Addressing-Mode Implications
The calling program’s registers The calling program’s registers are stored at the address specified by UEPHMSA of DFHUEPAR. Where the calling program is a CICS management program, for example the syncpoint manager, the only caller registers that have significance are registers 1 and 15.
Page 312: Exit Programs And The Cics Storage Protection Facility
DFHRMCAL, the task-related user exit is invoked in AMODE 24. For this reason, task-related user exits which have been enabled without the LINKEDITMODE option must reside below the 16MB line. Exit programs and the CICS storage protection facility When you are running CICS with the storage protection facility, there are two points you need to consider for task-related user exits: 1.
Page 313: Using Cics Services In Your Task-Related User Exit Program
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.
Page 314: Using Channels And Containers
v On each invocation of a task-related user exit program, a new EXEC environment is created, even when the program is being invoked from the same task. This means that CICS operations, such as browse of a resource definition table, cannot be continued from one invocation of the exit program to the next. Using channels and containers Task-related user exit programs cannot access channels and containers created by application programs.
Page 315: Coding A Program To Be Invoked By The Cics Spi
The local work area A local work area is associated with a single task and lasts only for the duration of the task. It is for the use of a single task-related user exit program. It can be thought of as a logical extension to the transaction work area (TWA, TWACOBA) that is exclusively for the exit program’s use.
Page 316: Return Codes
piece of recoverable work to ensure that the CICS syncpoint manager calls the exit program during syncpoint processing. (The identification of the current unit of recovery—or unit of work—is addressed by the 8-byte field UEPURID. This is available on all invocations of your exit program in which recoverable actions are possible, for example, application calls and subsequent syncpoint manager calls.) Increasing efficiency –...
Page 317 manager’s parameter list and the TRUE return codes. (The CICS syncpoint manager parameters are described in “CICS syncpoint manager parameters” on page 279.) Table 15. Valid return codes for a TRUE invoked by the CICS syncpoint manager Request-type Return codes UERTPREP UERFPREP UERTPREP...
Page 318 if UERTFID = UERTSYNC then select; when (UERTONLY) invoke RM for single-phase commit if RM single-phase commit succeeded then give CICS syncpoint manager ’YES’ vote (UERFOK) else if RM single-phase commit failed and backed out give CICS syncpoint manager ’NO’ vote (UERFBOUT) else put out message and issue transaction abend endif...
Page 319: Coding A Program To Be Invoked By The Cics Task Manager
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.
Page 320: Coding A Program To Be Invoked At Cics Termination
Limitations If your exit program is invoked at end-of-task, you must be alert to possible limitations on exit program activity at task-detach. For example: v Do not update any CICS resources at all during a task-detach exit call, because the CICS syncpoint manager is not invoked again for that task. Note also that all resources (terminals, and so on) except task-storage have been released by end-of-task.
Page 321 CICS abend, retry possible, TCBs dispatchable (UERTCABY) MVS has flagged the failure as being “eligible for retry”. Your exit program must follow the MVS rules for this type of failure, documented in the OS/390 MVS Authorized Assembler Services Guide. Subtasks in the region (that is, task control blocks (TCBs) in addition to the CICS job-step TCB) are still dispatchable, and your exit program can execute code under them.
Page 322 JTRUE1A CSECT 14,12,12(13) USING JTRUE1A,R3 R3,R15 USING DFHUEPAR,R1 R2,UEPEXN USING DFHUERTR,R2 UERTFID,UERTCTER CONT R10,UEPHMSA USING SA,R10 R5,RSAR1 USING DFHCTERM,R5 R5,CTERML USING CTERMLIST,R5 CTERMTYPE,UERTCORD CONT CTERMTYPE,UERTCIMM CONT Insert code here for any processing when CICS is abending (No CICS services should be used) 14,12,12(13) 0,14 CONT...
Page 323: Using Edf With Your Task-Related User Exit Program
DFHEISTG DSECT Local working storage for CSECT JTRUE1B DSECT RSACB +004 RSACF +008 RSAR14 +00C RSAR15 +010 RSAR0 +014 RSAR1 +018 RSAR2 RSAR3 RSAR4 RSAR5 RSAR6 RSAR7 RSAR8 RSAR9 RSAR10 RSAR11 RSAR12 DFHREGS DFHUEXIT TYPE=RM DFHEISTG DFHEIEND PRINT NOGEN PRINT GEN Figure 10.
Page 324: Administering The Adapter
Task-related user exit interface Task-related user exit (T1) Prepare 'About to Execute' EDF screen EDF (E1) Task-related user exit (T2) Response EDF user Task-related user exit (T3) Access resource manager Task-related user exit (T4) Prepare 'Command Execution Complete' EDF screen EDF (E2) Task-related user exit (T5) Response EDF user...
Page 325: What You Must Do Before Using The Adapter
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.
Page 326: Tracing A Task-Related User Exit Program
v An inbound RESYNC command from a resource manager that requests SHUTDOWN specifies that the exit program is to be invoked at CICS shutdown. specifies that the exit program is to be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM calls that specify the CONNECTST or QUALIFIER options.
Page 327: Chapter 3. The User Exit Programming Interface (Xpi)
Chapter 3. The user exit programming interface (XPI) This chapter describes the user exit programming interface (XPI) of CICS Transaction Server for z/OS, Version 3 Release 2. It is divided into the following sections: v “Overview of the XPI” is an introduction to the XPI.
Page 328 – Release all storage held by the SEARCH_LDAP function—see “The FREE_SEARCH_RESULTS call” on page 324. v Using the XPI dispatcher functions, you can: – Obtain a suspend token for a task—see “The ADD_SUSPEND call” on page – Suspend execution of the issuing task—see “The SUSPEND call” on page –...
Page 329 – Inquire about the attributes of a specified program—see “The INQUIRE_PROGRAM call” on page 366 – Inquire about the attributes of the program that is currently running—see “The INQUIRE_CURRENT_PROGRAM call” on page 373 – Set selected attributes in the definition of a specified program—see “The SET_PROGRAM call”...
Page 330: Making An Xpi Call
– Inquire about an attached transaction—see “The INQUIRE_TRANSACTION call” on page 414 – Change the task priority and transaction class of the current task—see “The SET_TRANSACTION call” on page 418. v Using the XPI user journaling function, you can: – Write a record to a CICS journal—see “The WRITE_JOURNAL_DATA call” on page 419.
Page 331 mandout2(value), [optout1(value),] [optout2(value),] RESPONSE, REASON] XPI calls follow assembler-language coding conventions: v The “macro-name” must begin before column 16. v The continuation lines must begin in column 16. v There must be no embedded blanks apart from the blank between the macro-name and the first keyword (usually CALL).
Page 332 Note: Failure to clear the parameter list can cause unpredictable results, tells CICS that any parameter following the IN option and preceding the OUT option is an input value. It must be specified when CALL is specified. If you use the function without CALL to build a parameter list, you can specify IN and some parameter values to store values into your list.
Page 333 DFHxxyyX. You cannot assume that the arithmetic values of corresponding RESPONSE codes are the same for all macro calls. The meanings of the RESPONSE codes are as follows: The XPI request was completed successfully. EXCEPTION The function was not completed successfully for a reason which could be expected to happen, and which may be coded for by a program (for example, TRANSACTION_DUMP, EXCEPTION = SUPPRESSED_BY_DUMPTABLE).
Page 334: Setting Up The Xpi Environment
REASON This is a mandatory data area that you define in order to receive more information about the RESPONSE value. You can use (*) to indicate to CICS that the REASON value is to be placed in the parameter list. On most XPI calls, standardized reason names (EQU symbols) are provided only for RESPONSE values of ‘EXCEPTION’...
Page 335: The Xpi Copy Books
The XPI copy books There is a copy book for each XPI function, to provide the DSECTs associated with that function. These DSECTs allow you to map the parameters and the response and reason codes of an XPI call. You must include in your exit program a COPY statement for each XPI function that you are going to use.
Page 336 in the first 4 bytes of the LIFO storage addressed by UEPXSTOR. In this example, the initialization of the parameter list (using the CLEAR option), the building of the parameter list, and the GETMAIN call occur in a single macro. For details of how to build the parameter list incrementally, and how to separate the CLEAR and the GETMAIN call, refer to “An example showing how to build a parameter list incrementally”...
Page 337 TITLE ’GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI’ ************************************************************************* * The first three instructions set up the global user exit * environment, identify the user exit point, prepare for the use of * the exit programming interface, and copy in the definitions that * are to be used by the XPI function.
Page 338 ************************************************************************** * Before issuing an XPI function call, set up addressing to XPI * parameter list. ************************************************************************* R5,UEPXSTOR USING DFHSMMC_ARG,R5 ************************************************************************* * Before issuing an XPI function call, you must ensure that register * 13 addresses the kernel stack. ************************************************************************* R13,UEPSTACK ************************************************************************* * Issue the DFHSMMCX macro call, specifying:...
Page 339 ************************************************************************* * Test SMMC_RESPONSE -- if OK, then branch round error handling. ************************************************************************* SMMC_RESPONSE,SMMC_OK STOK error-handling routines ************************************************************************** * The next section maps TRANSTOR on the acquired storage. ************************************************************************** STOK USING TRANSTOR,R6 R6,0(R5) R5,4(R5) DROP R5 USING DFHxxyy_ARG,R5 rest of user exit program ************************************************************************* * When the rest of the exit program is completed, free the storage * and return.
Page 340: An Example Showing How To Build A Parameter List Incrementally
OUT -- output values follow RESPONSE(*) -- put response at SMMC_RESPONSE in macro parameter list. REASON(*) -- put reason at SMMC_REASON in macro parameter list. ************************************************************************* DFHSMMCX CALL, CLEAR, FUNCTION(FREEMAIN), ADDRESS((R6)), STORAGE_CLASS(USER), OUT, RESPONSE(*), REASON(*) ************************************************************************* * Test SMMC_RESPONSE -- if OK, then branch round error handling. ************************************************************************* SMMC_RESPONSE,SMMC_OK STEND...
Page 341: Xpi Syntax
Important You must set your parameters using only the XPI functions. XPI syntax The XPI functions use special syntax. The description of each function defines only the options that are specific to that call. Options that are applicable to all function calls are described in “Making an XPI call”...
Page 342 buffer-descriptor Represents a source of both the data address and the maximum data length fields. Parts of the buffer-descriptor are also reserved to act as receiving fields for output information. A buffer-descriptor can be either a single value or a multiple value. The following is the single-value form: OPTION(bufdname) bufdname The following is the multiple-value form:...
Page 343: Directory Domain Xpi Functions
The BIND_LDAP call The BIND_LDAP call establishes a session with an LDAP server. The server is identified by one of the following: v The LDAP URL and the distinguished name and password of the user authorized to extract the expected data.
Page 344 LDAP URL (in the format ldap://server:port) of the LDAP server being accessed. If the colon and port number are omitted, the port defaults to 389. The block-descriptor is two fullwords of data, in which the first word contains the address of the data, and the second word contains the length in bytes of the data.
Page 345: The End_Browse_Results Call
RESPONSE KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The END_BROWSE_RESULTS call The END_BROWSE_RESULTS call allows you to end the browse session that was started by the START_BROWSE_RESULTS call. END_BROWSE_RESULTS DFHDDAPX [CALL], [CLEAR],...
Page 346: The Free_Search_Results 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 and REASON values for FLUSH_LDAP_CACHE: RESPONSE EXCEPTION DISASTER...
Page 347: The Get_Attribute_Value Call
RESPONSE INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The GET_ATTRIBUTE_VALUE call The GET_ATTRIBUTE_VALUE call allows you to retrieve the value associated with an attribute returned by the SEARCH_LDAP call. An entry is an LDAP record, and an attribute is one element within an entry.
Page 348: The Get_Next_Attribute 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. Array indexing starts at position 1. RESPONSE and REASON values for GET_ATTRIBUTE_VALUE: RESPONSE EXCEPTION DISASTER INVALID KERNERROR...
Page 349: The Get_Next_Entry Call
VALUE_COUNT(name4) a fullword containing the number of values returned for this attribute. There is usually one value returned. RESPONSE and REASON values for GET_NEXT_ATTRIBUTE: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call”...
Page 350: The Search_Ldap Call
“Making an XPI call” on page 308. The SEARCH_LDAP call The SEARCH_LDAP call sends a search request to a specified LDAP server. The search specifies an LDAP distinguished name, that is the target of the search. The search returns a series of results (attributes or entries) that can be browsed or selected.
Page 351: The Start_Browse_Results Call
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.
Page 352: The Unbind_Ldap Call
KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The UNBIND_LDAP call The UNBIND_LDAP call terminates a session with an LDAP server. UNBIND_LDAP DFHDDAPX [CALL], [CLEAR], [IN,...
Page 353: Dispatcher Xpi Functions
This command is threadsafe. LDAP_RESPONSE(name4) specifies the return code that is sent by the LDAP API. LDAP_SESSION_TOKEN(name4) the name of the fullword token that was returned by the BIND_LDAP function. RESPONSE and REASON values for UNBIND_LDAP: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in...
Page 354 The normal synchronization protocol In the normal case, synchronization involves two tasks and three operations. In the following sample operations, the tasks are A (the task that requests a service) and B (the task that processes a request from task A). 1.
Page 355 Task A: Set parameters; Resume task B; Task B: Get parameters; 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: Set parameters;...
Page 356: The Add_Suspend Call
The ADD_SUSPEND call ADD_SUSPEND acquires a suspend token that can later be used to identify a SUSPEND/RESUME pair. ADD_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(ADD_SUSPEND), [RESOURCE_NAME(name16 | string | ’string’),] [RESOURCE_TYPE(name8 | string | ’string’),]] [OUT, SUSPEND_TOKEN(name4 | (Rn)), RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
Page 357: The Suspend Call
name4 (Rn) RESPONSE and REASON values for ADD_SUSPEND: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The SUSPEND call SUSPEND suspends execution of a running task. The task can be resumed in one of two ways.
Page 358 depends on the setting of the TIME_UNIT option. The INTERVAL value overrides any time-out (DTIMOUT) value specified for the transaction. name4 (Rn) PURGEABLE(YES|NO) specifies whether your code can cope with the request being abnormally terminated as a result of a purge. There are four types of purge, as shown in Table 17.
Page 359 name8 The name of the location where an 8-byte value is stored. string A string of characters without intervening blanks; if it is not 8 bytes long, it is extended with blanks or truncated as required. "string" A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string.
Page 360 IO Waiting on an I/O operation or indeterminate I/O-related operation (locks, buffer, string, and so on). LOCK Waiting on a lock. MISC Waiting on an unidentified resource. Note: This is the default reason given to the wait if you suspend a task and OTHER_PRODUCT Waiting on another product to complete its function;...
Page 361: The Resume Call
The RESUME call RESUME restarts execution of a task that is suspended or timed out. There must be only one RESUME request for each SUSPEND. However, because this is an asynchronous interface, a SUSPEND can be received either before or after its corresponding RESUME.
Page 362: The Delete_Suspend Call
2. ‘TASK_CANCELLED’ means that the task was canceled by operator The DELETE_SUSPEND call DELETE_SUSPEND releases a suspend token associated with this task. DELETE_SUSPEND DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(DELETE_SUSPEND), SUSPEND_TOKEN(name4 | (Rn)),] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. SUSPEND_TOKEN(name4 | (Rn) ) specifies a token assigned by the system to identify the SUSPEND/RESUME pair of operations used on the task.
Page 363 Note: ECBs used in WAIT_MVS requests must never be “hand posted”. They must be posted using the MVS POST macro. WAIT_MVS DFHDSSRX [CALL,] [CLEAR,] [IN, FUNCTION(WAIT_MVS), {ECB_ADDRESS(name4 | (Ra)) | ECB_LIST_ADDRESS(name4 | (Ra)),} PURGEABLE(YES|NO), [INTERVAL(name4 | (Rn)),] [RESOURCE_NAME(name16 | string | ’string’),] [RESOURCE_TYPE(name8 | string | ’string’),]] [TIME_UNIT(SECOND|MILLI_SECOND),] [WLM_WAIT_TYPE,]...
Page 364 Table 18. WAIT_MVS call - RESPONSE(PURGED) (continued) CONDITION PURGE PURGEABLE (NO) Canceled PURGEABLE (YES) Proceeds normally Note: A FORCEPURGE always assumes that the user wants the task to be RESOURCE_NAME(name16 | string | "string") specifies a 16-character string that can be used to document and trace the resource involved in suspend and resume processing.
Page 365 MILLI_SECOND The INTERVAL option specifies the number of milliseconds before timeout. WLM_WAIT_TYPE(name1) specifies, in a 1-byte location, the reason for suspending the task. This indicates the nature of the task’s wait state to the MVS workload manager. The equated values for the type of wait are as follows: CMDRESP Waiting on a command response.
Page 366: The Change_Priority Call
RESPONSE and REASON values for WAIT_MVS: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in 2. ‘TIMED_OUT’ is returned if the INTERVAL expires, or if a deadlock 3. ‘TASK_CANCELLED’ means that the task has been canceled by operator The CHANGE_PRIORITY call CHANGE_PRIORITY allows the issuing task to change its own priority.
Page 367: Dump Control Xpi Functions
literalconst RESPONSE and REASON values for CHANGE_PRIORITY: RESPONSE DISASTER INVALID KERNERROR Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. Dump control XPI functions There are two XPI dump control functions. These are the DFHDUDUX macro calls SYSTEM_DUMP and TRANSACTION_DUMP.
Page 368 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 SYSTEM_DUMPCODE(name8 | string | "string") specifies the code corresponding to the error that caused this system dump call.
Page 369: The Transaction_Dump Call
The TRANSACTION_DUMP call TRANSACTION_DUMP causes a transaction dump to be taken. If the transaction dump code that you supply on input is in the transaction dump code table, the dump may be suppressed and, optionally, a system dump may be taken. For information about the dump table and how it works, refer to the CICS Problem Determination Guide and SET TRANDUMPCODE, in the CICS System Programming Reference manual.
Page 370 end of the list must be marked by a word containing X'FFFFFFFF'. SEGMENT and SEGMENT_LIST are mutually exclusive. TCA(NO|YES) specifies whether the task control area (TCA) is to be included in the transaction dump. The default is NO. TERMINAL(NO|YES) specifies whether all terminal storage areas associated with the task are to be included in the transaction dump.
Page 371: Enqueue Domain Xpi Functions
Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in 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 4. ‘PARTIAL’ means that the transaction dump resulting from this request is Enqueue domain XPI functions There are two XPI enqueue domain functions.
Page 372: The Dequeue Function
rather than enqueue name, allowing the NQ domain to locate the enqueue control block directly, and hence more efficiently. MAX_LIFETIME(DISPATCHER_TASK) MAX_LIFETIME(DISPATCHER_TASK) is required and specifies that all XPI enqueues are owned by the requesting dispatcher task. If you use the ENQUEUE XPI call to ensure that your global user exit programs are threadsafe, you are recommended to free (dequeue) resources during the invocation of the global user exit program in which they were enqueued.
Page 373: Kernel Domain Xpi Functions
The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, and MAX_LIFETIME(DISPATCHER_TASK) parameters are the same as in the ENQUEUE function call. RESPONSE and REASON values for DEQUEUE RESPONSE EXCEPTION Kernel domain XPI functions The START_PURGE_PROTECTION function The START_PURGE_PROTECTION function is provided on the DFHKEDSX macro call.
Page 374: Nesting Purge Protection Calls
STOP_PURGE_PROTECTION DFHKEDSX [CALL,] [CLEAR,] [IN, FUNCTION(STOP_PURGE_PROTECTION),] [OUT, RESPONSE (name1 | *)] This command is threadsafe. There are no input or output parameters on this call, only a RESPONSE. RESPONSE values for STOP_PURGE_PROTECTION: RESPONSE DISASTER INVALID Nesting purge protection calls Note that the START_ and STOP_PURGE_PROTECTION functions can be nested. You should ensure that, if multiple START_PURGE_PROTECTION calls are issued for a task, that the correct number of STOP_PURGE_PROTECTION calls are issued to cancel the purge protection.
Page 375: The Define_Program Call
The DEFINE_PROGRAM call DEFINE_PROGRAM allows you to define new programs to the loader domain, or to change the details of programs that have already been defined. The details that you provide are recorded on the local catalog, and become immediately available. They are used on all subsequent ACQUIRE requests for the named program.
Page 376 Table 19. Summary of attributes defining DSA eligibility (continued) EXECUTION_KEY option CICS CICS CICS USER USER USER USER NEW_PROGRAM_TOKEN(name4) returns the token supplied for the newly-defined program. name4 PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT) specifies the residency status of the program. RELOAD RESIDENT REUSABLE TRANSIENT PROGRAM_NAME(name8 | string | "string") specifies the name of the program to be defined.
Page 377 PRIVATE The program is in the DFHRPL or dynamic LIBRARY concatenation. A PRIVATE program need not be reentrant, and is given only limited protection from unauthorized overwriting. The degree of protection depends on the type of dynamic storage area (DSA) into which the program is loaded (see the EXECUTION_KEY option): Protection from unauthorized overwriting CDSA Cannot be overwritten by USER tasks...
Page 378: The Acquire_Program Call
RESPONSE DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. The ACQUIRE_PROGRAM call ACQUIRE_PROGRAM returns the entry and load point addresses, the length, and a new program token for a usable copy of the named program, which can be identified by either its name or a program token.
Page 379 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.
Page 380: The Release_Program Call
RESPONSE and REASON values for ACQUIRE_PROGRAM: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in 2. A REASON of ‘NO_STORAGE’ with a RESPONSE of ‘EXCEPTION’ 3. A REASON of ‘PROGRAM_NOT_FOUND’ is returned if the program has The RELEASE_PROGRAM call RELEASE_PROGRAM decrements the use count of a currently loaded program by one.
Page 381: The Delete_Program Call
name8 string A string of characters naming the program. "string" PROGRAM_TOKEN(name4), specifies a token identifying the program to be released. name4 RESPONSE and REASON values for RELEASE_PROGRAM: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: 1. For more detail, refer to the explanation of RESPONSE and REASON in 2.
Page 382: Log Manager Xpi Functions
string A string of characters naming the program. "string" RESPONSE and REASON values for DELETE_PROGRAM: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. Log manager XPI functions There are two XPI log manager functions.
Page 383: The Set_Parameters Call
RESPONSE INVALID KERNERROR The SET_PARAMETERS call SET_PARAMETERS allows you to set the activity keypoint frequency for the CICS region. SET_PARAMETERS DFHLGPAX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PARAMETERS), [KEYPOINT_FREQUENCY(name4 | (Rn) ),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. KEYPOINT_FREQUENCY(name4 | *) specifies the activity keypointing frequency of the CICS region.
Page 384: The Monitor Call
INQUIRE_MONITORING_DATA calls cannot be used in any exit program invoked from any global user exit point in DFHTCP or DFHZCP (that is, at any of the exit points named “XTCx...” or “XZCx...”). The MONITOR call The MONITOR XPI call is similar to the EXEC CICS MONITOR command. It enables you to invoke user event-monitoring points (EMPs) in your exit programs.
Page 385 expression A valid assembler-language expression giving the fullword binary variable for this EMP. name4 The name of a 4-byte field containing the fullword binary variable for this EMP. (Ra) A register containing the fullword binary variable for this EMP. The value of this option is already present in the parameter list, or the option is not specified for this EMP.
Page 386: The Inquire_Monitoring_Data Call
POINT(expression | name2 | (Rn)) specifies the monitoring point identifier as defined in the MCT, and is in the range 0 through 255. Note, however, that point identifiers in the range 200 through 255 are reserved for use by IBM program products. expression name2...
Page 387 The DFHMNTDS DSECT that maps the data is of fixed format. Note that: v All the CICS system-defined fields in the performance records (including fields that you have specified for exclusion using the EXCLUDE option of the DFHMCT TYPE=RECORD macro) are listed. v No user-defined data fields are listed.
Page 388: Program Management Xpi Functions
Program management XPI functions There are eight XPI program management functions. These are the DFHPGISX calls: INQUIRE_PROGRAM INQUIRE_CURRENT_PROGRAM SET_PROGRAM START_BROWSE_PROGRAM GET_NEXT_PROGRAM END_BROWSE_PROGRAM and the DFHPGAQX calls: INQUIRE_AUTOINSTALL SET_AUTOINSTALL Used with the Loader functions DEFINE_PROGRAM, ACQUIRE_PROGRAM, RELEASE_PROGRAM, and DELETE_PROGRAM, these calls give you a comprehensive set of tools for manipulating programs.
Page 389 [PROGRAM_LENGTH(name4),] [PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY),] [PROGRAM_USAGE(APPLICATION|NUCLEUS),] [PROGRAM_USE_COUNT(name4),] [PROGRAM_USER_COUNT(name4),] [REMOTE_DEFINITION(LOCAL|REMOTE),] [REMOTE_PROGID(name8),] [REMOTE_SYSID(name4),] [REMOTE_TRANID(name4),] [SPECIFIED_AMODE(24|31|AMODE_ANY|AMODE_NOT_SPECIFIED),] [SPECIFIED_RMODE(24|RMODE_ANY|RMODE_NOT_SPECIFIED),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. ACCESS(CICS|NONE|READ_ONLY|USER) returns a value indicating the type of storage into which the program has been loaded. CICS NONE The program has not been loaded READ_ONLY USER User-key APIST(CICSAPI|OPENAPI)
Page 390 If the program is the subject of a program-link request, the dynamic routing program is not invoked. For a distributed program link (DPL) request, the server region on which the program is to execute must be specified explicitly on the REMOTESYSTEM option of the PROGRAM definition or on the SYSID option of the EXEC CICS LINK command;...
Page 391 USER CICS gives control to the program in user key. The program is loaded into a user DSA, above or below the 16MB line; that is, the UDSA or EUDSA, depending on its residency mode (RMODE) attribute as defined to the linkage-editor. EXECUTION_SET(DPLSUBSET|FULLAPI|NOT_APPLIC) returns a value indicating whether CICS links to and runs the program as if it were running in a remote CICS region.
Page 392 LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|LE370| NOT_APPLIC|NOT_DEFINED|PLI) returns the programming language specified on the resource definition. LIBRARY(name) returns the 8-character name of the LIBRARY resource from which this program was loaded. This is blank if the program has not been loaded, or if the LPASTATUS is LPA (indicating that the program has been loaded from the LPA).
Page 393 MODULE_TYPE(MAPSET|PARTITIONSET|PROGRAM) returns the kind of program resource. NEW_PROGRAM_TOKEN(name4) returns a token that can be used to identify the named program. name4 The name of a location to receive a 4-byte token that identifies this program. If PROGRAM_NAME is specified on the request, NEW_PROGRAM_TOKEN is set to a program token that can be used on subsequent requests for the same program.
Page 394 NOT_APPLIC PRIVATE SHARED TYPE_ANY PROGRAM_USAGE(APPLICATION|NUCLEUS) returns a value indicating whether the program is used as a CICS nucleus program or as a user application program. PROGRAM_USE_COUNT(name4) returns the number of different users that have invoked the program. PROGRAM_USER_COUNT(name4) returns the current number of users of the program. REMOTE_DEFINITION(LOCAL|REMOTE) returns a value indicating whether this program is a local or a remote resource.
Page 395: The Inquire_Current_Program Call
RESPONSE and REASON values for INQUIRE_PROGRAM: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED The INQUIRE_CURRENT_PROGRAM call INQUIRE_CURRENT_PROGRAM returns information about the attributes of the program that is currently running. If this call is issued from within a global user exit or task-related user exit, it returns the attributes of the global user exit program or task-related user exit program itself.
Page 396 This command is threadsafe. Note: The options not described in the following list are identical to the equivalent CURRENT_AMODE(24|31) returns the addressing mode which the running program is currently using. CURRENT_CEDF_STATUS(CEDF|NOCEDF) returns the EDF status of the current instance of the program. The value returned is the same as for CEDF_STATUS, which is the EDF status specified on the program definition.
Page 397: The Set_Program Call
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.
Page 398 SET_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(SET_PROGRAM), {PROGRAM_NAME(name8 | string | ’string’)| PROGRAM_TOKEN(name4)},] [AVAIL_STATUS(DISABLED|ENABLED),] [CEDF_STATUS(CEDF|NOCEDF),] [EXECUTION_KEY(CICS|USER),] [EXECUTION_SET(DPLSUBSET|FULLAPI),] [PROGRAM_ATTRIBUTE(RELOAD|RESIDENT|REUSABLE|TRANSIENT),] [PROGRAM_TYPE(PRIVATE|SHARED|TYPE_ANY),] [PROGRAM_USAGE(APPLICATION|NUCLEUS),] [REQUIRED_AMODE(24|31|AMODE_ANY),] [REQUIRED_RMODE(24|RMODE_ANY),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. AVAIL_STATUS(DISABLED|ENABLED) specifies whether the program can be used—that is, whether or not it is enabled.
Page 399 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.
Page 400 TYPE_ANY PROGRAM_USAGE(APPLICATION|NUCLEUS) specifies whether the program is used as a CICS nucleus program or as a user application program. REQUIRED_AMODE(24|31|AMODE_ANY) specifies the addressing mode of the program. If, during subsequent processing, no copy of the program that meets the defined addressing requirement can be found, an exception occurs.
Page 401: The Start_Browse_Program Call
The START_BROWSE_PROGRAM call START_BROWSE_PROGRAM returns a token that enables you to begin browsing through program definitions, optionally starting at the definition of a specified program. START_BROWSE_PROGRAM DFHPGISX [CALL,] [CLEAR,] [IN, FUNCTION(START_BROWSE_PROGRAM), [PROGRAM_NAME(name8 | string | ’string’),]] [OUT, BROWSE_TOKEN(name4) RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe.
Page 402: The Get_Next_Program Call
The GET_NEXT_PROGRAM call GET_NEXT_PROGRAM allows you to inquire on the next program definition during a browse sequence initiated by START_BROWSE_PROGRAM. The browsing sequence is alphabetical. The end of the alphabetic list of definitions is indicated by an 'END_LIST' exception response. GET_NEXT_PROGRAM DFHPGISX [CALL,] [CLEAR,]...
Page 403: The End_Browse_Program Call
NEW_PROGRAM_TOKEN(name4) returns a token that identifies the next definition in the browse sequence. You can use it in the BROWSE_TOKEN field of your next GET_NEXT_PROGRAM call (or END_BROWSE_PROGRAM call, if you want to end the sequence). You can also use it in the PROGRAM_TOKEN field of INQUIRE_PROGRAM and SET_PROGRAM calls.
Page 404: The Inquire_Autoinstall Call
The INQUIRE_AUTOINSTALL call INQUIRE_AUTOINSTALL returns information about the current settings of the autoinstall function for programs, mapsets, and partitionsets. INQUIRE_AUTOINSTALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_AUTOINSTALL),] [OUT, [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. AUTOINSTALL_CATALOG(ALL|MODIFY|NONE) returns the catalog status for autoinstalled program definitions.
Page 405 SET_AUTOINSTALL DFHPGAQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_AUTOINSTALL), [AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),] [AUTOINSTALL_EXIT_NAME(name8),] [AUTOINSTALL_STATE (ACTIVE|INACTIVE),] [LANGUAGES_AVAILABLE(NO|YES),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. AUTOINSTALL_CATALOG(ALL|MODIFY|NONE) specifies the catalog status for autoinstalled program definitions. All autoinstalled program, map, and partitionset definitions are to be cataloged.
Page 406: State Data Access Xpi Functions
State data access XPI functions The state data access functions allow you to inquire on and set certain system data in the AP domain. The INQ_APPLICATION_DATA call The INQ_APPLICATION_DATA call enables you to inquire on application system data in the AP domain. INQ_APPLICATION_DATA DFHAPIQX [CALL,] [CLEAR,]...
Page 407 The parameter list itself, in name APIQ_EIB, is used to hold the address. RSA(name4 | (Rn | * ) returns the address of the register save area for the current task. name4 The name of a fullword area that is to receive the address of the register save area.
Page 408: The Inquire_System Call
name4 (Rn) RESPONSE and REASON values for INQ_APPLICATION_DATA: RESPONSE EXCEPTION DISASTER INVALID KERNERROR PURGED The INQUIRE_SYSTEM call The INQUIRE_SYSTEM call gives you access to CICS system data in the AP domain. INQUIRE_SYSTEM DFHSAIQX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_SYSTEM), [GMMTEXT(name4),]] [OUT, [CICSREL(name4 | *),] [CICSSTATUS(ACTIVE | FINALQUIESCE | [CICSSYS(name1 | *),] [CICTSLEVEL(name6 | *),]...
Page 409 A value of “X” represents MVS/ESA. CICSTSLEVEL(name6 | *) returns the release of CICS Transaction Server under which CICS is running. name6 The name of a 6-byte area that is to receive the release characters as hexadecimal values.
Page 410 name4 DTRPRGRM(name8 | *) returns the name of the dynamic routing program. name8 GMMLENGTH(name2 | *) returns the length in bytes of the “good morning” message. name2 GMMTEXT(name4) specifies the address of an area of storage, at least 244 bytes in length and owned by the caller, into which CICS is to return the good morning message.
Page 411 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.
Page 412 NOTSHUTDOWN SHUTDOWN STARTUP(COLDSTART|EMERGENCY|WARMSTART) returns the type of startup the CICS region performed. COLDSTART EMERGENCY WARMSTART STARTUPDATE(name4 | *) returns the start-up-date of this CICS region, in packed decimal form (4-bytes 00yydddc where yy=years, ddd=days, c is the sign). name4 TERMURM(name8 | *) returns the name of the autoinstall user program for terminals.
Page 413: The Set_System Call
RESPONSE INVALID EXCEPTION DISASTER PURGED The SET_SYSTEM call The SET_SYSTEM call allows you to set CICS system data values in the AP domain. SET_SYSTEM DFHSAIQX [CALL,] [CLEAR,] [IN, FUNCTION(SET_SYSTEM), [DTRPRGRM(name8 | string | ’string’),] [GMMLENGTH(name2 | (Rn) | expression),] [GMMTEXT(name8 | (Rn)),]] [OUT, RESPONSE (name1 | * ), REASON (name1 | * )]...
Page 414: Storage Control Xpi Functions
RESPONSE and REASON values for SET_SYSTEM: RESPONSE INVALID EXCEPTION DISASTER PURGED Storage control XPI functions There are seven XPI storage control functions. These are the DFHSMMCX macro calls GETMAIN, FREEMAIN, INQUIRE_ELEMENT_LENGTH, and INQUIRE_TASK_STORAGE, and the DFHSMSRX calls INQUIRE_ACCESS, INQUIRE_SHORT_ON_STORAGE, and SWITCH_SUBSPACE. DFHSMMCX calls cannot be used in any exit program invoked from any global user exit point in the: v Dispatcher domain...
Page 415 GETMAIN DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION(GETMAIN), GET_LENGTH(name4 | (Rn) | expression), STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL), SUSPEND(NO|YES), [INITIAL_IMAGE(name1 | literalconst),] [TCTTE_ADDRESS(name4 | (Ra)),]] [OUT, ADDRESS(name4 | (Rn) | *), RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. ADDRESS(name4 | (Rn) | *) returns the address of the storage obtained by the call.
Page 416 STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL) specifies the class of the storage that is the subject of the call. The values you can assign to this option, and the type of storage each represents, are listed in Table 20. Table 20. CICS storage classes STORAGE_CLASS CICS CICS24...
Page 417: The Freemain Call
2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request was 3. ‘PURGED’ is returned if the GETMAIN request was specified with The FREEMAIN call FREEMAIN releases an area of storage that is currently allocated to your exit program. FREEMAIN DFHSMMCX [CALL,] [CLEAR,] [IN, FUNCTION(FREEMAIN),...
Page 418: The Inquire_Element_Length Call
[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 READ_ONLY USER User-key. ELEMENT_ADDRESS(name4 | (Rn) | *) specifies the address of the storage element. ELEMENT_LENGTH(name4 | (Rn) | *) specifies the length of the storage element, in bytes.
Page 419: The Inquire_Short_On_Storage Call
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.
Page 420: The Inquire_Task_Storage Call
RESPONSE and REASON values for INQUIRE_SHORT_ON_STORAGE: RESPONSE DISASTER KERNERROR The INQUIRE_TASK_STORAGE call INQUIRE_TASK_STORAGE enables you to request details of all elements of task-lifetime storage belonging to a task. You can specify the transaction number of the task explicitly on the call, or let it default to the current task. INQUIRE_TASK_STORAGE DFHSMMCX [CALL,] [CLEAR,]...
Page 421: The Switch_Subspace Call
RESPONSE DISASTER INVALID KERNERROR PURGED The SWITCH_SUBSPACE call SWITCH_SUBSPACE causes CICS to switch from a subspace to base space, if the task is not already executing in the base space. If the task is already in the base space, storage manager ignores the call. This function can be used by global user exit programs that receive control in subspace and for some reason need to switch into basespace.
Page 422: The Trace_Put Call
The TRACE_PUT call TRACE_PUT writes a trace entry to the active trace destinations. You should only make a TRACE_PUT call when UEPTRON indicates that tracing is active for the function containing the exit program (see UEPTRON in DFHUEPAR). You may prefer to make “exception”...
Page 423: Transaction Management Xpi Functions
expression name4 (Ra) RESPONSE values for TRACE_PUT The RESPONSE field is never set for the TRACE_PUT function. This is for performance reasons. It is not considered that any useful purpose could be served by testing for this value. Note, however, that the syntax requires that RESPONSE is always specified as a parameter on the call.
Page 424 name8 BRIDGE_TRANSACTION_ID(name4) returns the name of the bridge monitor transaction that issued a START BREXIT TRANSID command to start this transaction. If CONTEXT returns NORMAL, the contents of this field are meaningless. name4 BRXA_TOKEN(name4) returns a token that contains the address of the bridge exit area (BRXA) used by this task.
Page 425: The Inquire_Dtrtran Call
The INQUIRE_DTRTRAN call INQUIRE_DTRTRAN returns the name of the dynamic transaction routing (DTR) transaction definition. The DTR transaction definition provides common attributes for transactions that are to be dynamically routed and which do not have a specific transaction definition. It is specified on the DTRTRAN system initialization parameter;...
Page 426 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 (Rn) MXT_LIMIT(name4 | (Rn)) returns the current number of the MXT parameter. name4 (Rn) MXT_QUEUED(name4 | (Rn))
Page 427: The Inquire_Tclass Call
The INQUIRE_TCLASS call The INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Its purpose is to provide current information about the specified transaction class (TCLASS). INQUIRE_TCLASS DFHXMCLX [CALL,] [CLEAR,] [IN, FUNCTION(INQUIRE_TCLASS), INQ_TCLASS_NAME(name8 | string | 'string'),] [OUT, [CURRENT_ACTIVE(name4 | (Rn)),] [CURRENT_QUEUED(name4 | (Rn)),] [MAX_ACTIVE(name4 | (Rn)),] [PURGE_THRESHOLD(name4 | (Rn)),]...
Page 428: The Inquire_Trandef Call
name4 (Rn) PURGE_THRESHOLD(name4 | (Rn)) returns the purge threshold limit for this transaction class. name4 (Rn) RESPONSE and REASON values for INQUIRE_TCLASS: RESPONSE DISASTER INVALID EXCEPTION The INQUIRE_TRANDEF call The INQUIRE_TRANDEF function is provided on the DFHXMXDX macro call. Its purpose is to allow you to obtain information about the specified transaction definition.
Page 429 [SHUTDOWN(name1),] [SPURGE(name1),] [STATUS(name1),] [STORAGE_CLEAR(name1),] [STORAGE_FREEZE(name1),] [SYSTEM_ATTACH(name1),] [SYSTEM_RUNAWAY(name1),] [TASKDATAKEY(name1),] [TASKDATALOC(name1),] [TCLASS(name1),[TCLASS_NAME(name8),]] [TPURGE(name1),] [TRACE(name1),] [TRAN_PRIORITY(name4 | (Rn)),] [TRAN_ROUTING_PROFILE(name8),] [TRANSACTION_ID(name4),] [TWASIZE(name4 | (Rn)),] RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe. The following parameter descriptions explain briefly the possible values that can be returned on an INQUIRE_TRANDEF call.
Page 430 XMXD_NO DYNAMIC(name1) returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined for dynamic transaction routing. XMXD_YES XMXD_NO INDOUBT(name1) returns, in a 1-byte location (name1), an equated value indicating the action to be taken if the CICS region fails or loses connectivity with its coordinator while a unit of work is in the in-doubt period.
Page 431 name4 The name of a 4-byte location that contains the name of the transaction identifier. string A string of characters, without intervening blanks, naming the transaction identifier. ‘string’ A string of characters, within quotation marks, naming the transaction identifier. The string length is set to 4 by padding with blanks within the quotation marks.
Page 432 XMXD_OWN PARTITIONSET_NAME(name8) returns the name of the partitionset defined on the transaction definition. name8 PROFILE_NAME(name8) returns the name of the profile definition that is associated with the transaction definition. name8 REMOTE(name1) returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined as remote.
Page 433 XMXD_NO The transaction cannot be restarted. XMXD_YES The transaction can be restarted. ROUTABLE_STATUS(ROUTABLE|NOT_ROUTABLE) returns a value indicating whether, if the transaction is the subject of an eligible EXEC CICS START command, it will be routed using the enhanced routing method. NOT_ROUTABLE If the transaction is the subject of a START command, it will be routed using the “traditional”...
Page 434 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 XMXD_YES STORAGE_FREEZE(name1 | (Rn)) returns, in a 1-byte location (name1), an equated value indicating whether storage freeze is defined for the transaction by means of the STGFRZ option on the CICS-supplied field engineering transaction, CSFE.
Page 435 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.
Page 436: The Inquire_Transaction Call
name4 TWASIZE(name4 | (Rn)) returns the size of the transaction work area specified on the transaction definition. name4 (Rn) RESPONSE and REASON values for INQUIRE_TRANDEF: RESPONSE EXCEPTION INVALID DISASTER PURGED The INQUIRE_TRANSACTION call The INQUIRE_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to obtain information about a transaction that is attached (task).
Page 437 [TASK_PRIORITY(name1),] [TCLASS(name1),[TCLASS_NAME(name8),]] [TERMINATE_PROTECTED(name1),] [TRANNUM(name4 | string | 'string'),] [TRAN_PRIORITY(name1),] [TRAN_ROUTING_PROFILE(name8),] [TRANSACTION_ID(name4),] [USERID(name8),] RESPONSE (name1 | *), REASON (name1 | *)] This command is threadsafe. The descriptions of the following parameters are the same as the corresponding parameters on the INQUIRE_TRANDEF function call. DTIMEOUT DYNAMIC INITIAL_PROGRAM...
Page 438 XMIQ_TD XMIQ_TERMINAL NETNAME(name8) returns the network name of the principal facility associated with this task. name8 ORIGINAL_TRANSACTION_ID(name4) returns the transaction id that was used to attach the transaction. For example, if an alias was used at a terminal, this field returns the alias. name4 OUT_TRANSACTION_TOKEN(name8) returns the token that represents the task.
Page 439 START_CODE(name1) returns, in a 1-byte location (name1), an equated value indicating how the task was started: A CICS internal attach. XMIQ_DF The start code isn't yet known—to be set later. XMIQ_QD A transient data trigger level attach. XMIQ_S A START command without any data. XMIQ_SD A START command with data.
Page 440: The Set_Transaction Call
TRANNUM(name4) returns the task number of the transaction. name4 TRANSACTION_TOKEN(name8) specifies the transaction token for the task being inquired upon. This parameter is optional, and if omitted, the current task is assumed. If you issue this call within an XXMATT global user exit program, the current task may be a CICS system task.
Page 441: User Journaling Xpi Function
TASK_PRIORITY(name4) specifies the new task priority being set for the task identified by TRANSACTION_TOKEN. name4 TCLASS_NAME(name8) specifies the new transaction class name that you want to associate this task with. To specify that the task is not to be in any transaction class, specify the special default system name DFHTCL00.
Page 442 WRITE_JOURNAL DATA DFHJCJCX [CALL,] [CLEAR,] [IN, FUNCTION(WRITE_JOURNAL_DATA), FROM(block-descriptor), JOURNALNAME(name8 | string | ’string’ ) | JOURNAL_RECORD_ID(name2 | string | ’string’), WAIT(YES|NO), [RECORD_PREFIX(block-descriptor),]] [OUT, RESPONSE(name1 | *), REASON(name1 | *)] This command is threadsafe. Important There is a restriction in using the XPI early during initialization. Do not start exit programs that use the XPI functions TRANSACTION_DUMP, WRITE_JOURNAL_DATA, MONITOR, and INQUIRE_MONITOR_DATA until the second phase of the PLTPI.
Page 443 RESPONSE DISASTER INVALID KERNERROR PURGED Note: For more detail, refer to the explanation of RESPONSE and REASON in “Making an XPI call” on page 308. REASON JOURNAL_NOT_OPEN LENGTH_ERROR STATUS_ERROR None None None None Chapter 3. The user exit programming interface (XPI)
Page 444 Customization Guide...
Page 446 Customization Guide...
Page 447: Chapter 4. Writing Initialization And Shutdown Programs
If a first-phase PLTPI program enables an exit program that issues any of the XPI calls INQUIRE_MONITORING_DATA, MONITOR, TRANSACTION_DUMP, or WRITE_JOURNAL_DATA, it must not specify the START option on the EXEC CICS ENABLE COMMAND. © Copyright IBM Corp. 1977, 2011...
Page 448: Second Phase Plt Programs
v First phase PLTPI programs must not enable any task-related user exit program with the TASKSTART option. v Because first-phase PLT programs run so early in CICS initialization, no resource definitions are available. This means that you cannot use installed PROGRAM definitions (or the program autoinstall user program) to define first-phase PLT programs to CICS, nor to define the user exit programs that first-phase PLT programs enable.
Page 449: Effect Of Delayed Recovery On Pltpi Processing
Note: A pseudo-terminal: v PLTPI programs can request services that could suspend the issuing task, but note that this affects the time at which control is given to CICS. The SUSPEND must not require the decision to resume to be taken by another task. v Although PLTPI programs can issue interval control START commands, the requested transactions are not attached before the initialization stages have completed, unless the ATTACH option is specified.
Page 450: Writing Shutdown Programs
Writing shutdown programs Any program that is to execute during CICS shutdown must be defined in a program list table (PLT), and the PLT must be named on the program list table shutdown (PLTSD) system initialization parameter. You can override the PLTSD value by providing a PLT name on the CEMT PERFORM SHUTDOWN command, or on the EXEC CICS PERFORM SHUTDOWN command.
Page 451: The Shutdown Assist Utility Program, Dfhcesd
RETURN command. v PLT programs receive control in primary-space translation mode. For information about translation modes, see the IBM ESA/390 Principles of Operation manual. They must return control to CICS in the same mode, and must restore any general purpose registers or access registers that they use.
Page 452: Storage Keys For Plt Programs
program causes the relevant unit of work to be shunted. The PLTPI program abends ASP1, and CICS runs the next program defined in the PLTPI table, if any. v PLTSD programs run under the transaction that issued the PERFORM SHUTDOWN command. The CEMT transaction is defined with WAIT(YES). Therefore, if shutdown is as the result of a CEMT PERFORM SHUTDOWN command, an in-doubt failure that occurs while running a PLTSD program causes the unit of work to be shunted.
Page 453 1. Create a separate PROGRAM resource definition using the same JVMCLASS attribute value and specify EXECKEY(CICS). 2. Add the PROGRAM resource definition to the PLT. The original PROGRAM resource definition with EXECKEY(USER) can then be used subsequently. Data storage key for PLT programs The storage key of storage used by PLT programs depends on how the storage is obtained: v Any working storage requested by the PLT program is in the key set by the...
Page 454 Customization Guide...
Page 456 Customization Guide...
Page 457: Chapter 5. General Notes About User-Replaceable Programs
(except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. v User-replaceable programs, and any programs invoked by user-replaceable programs, can be RMODE ANY but must be AMODE 31.
Page 458: Assembling And Link-Editing User-Replaceable Programs
Assembling and link-editing user-replaceable programs The source for the CICS-supplied user-replaceable programs is installed in the CICSTS32.CICS.SDFHSAMP library. If you intend changing any of these programs, take a copy of the CICSTS32.CICS.SDFHSAMP library and update the copy only. If the original SDFHSAMP is serviced, and a user-replaceable program is modified, you may like to reflect the changes in your own version of the code.
Page 459: User-Replaceable Programs And The Storage Protection Facility
2 The library into which the load module will be link-edited. 3 Optionally, the name of a library containing your local Assembler macros and copy members. 4 These options are required for DFHXCURM, and for the supplied sample versions of DFHTEP and DFHZNEP. 5 your_sourcelib is the name of the library containing your modified version of the program.
Page 460: Data Storage Key For User-Replaceable Programs
Data storage key for user-replaceable programs The storage key of storage used by user-replaceable programs depends on how the storage is obtained: v The communication area passed to the user-replaceable program by its caller is always in CICS key. v Any working storage obtained for the user-replaceable program is in the key set by the TASKDATAKEY of the transaction under which the program is invoked.
Page 461: Chapter 6. Writing A Program Error Program
PEP_COM_ABPROGRAM. PEP_COM_ABPROGRAM identifies the program as follows: – If the abend occurred in a distributed program link (DPL) server program running in a remote system, it identifies the server program. – If the abend is a local ‘ASRA’, ‘ASRB’, or ‘ASRD’, it identifies the program in which the program check or operating system abend occurred.
Page 462 Note that information about the PSW, registers, execution key, and type of storage “hit” is meaningful only if the abend occurred in the local system; these fields are set to zeros if the abend occurred in a DPL server program running in a remote system.
Page 463 DFHEISTG DSECT , Insert your own storage definitions here DFHPCOM TYPE=DSECT *********************************************************************** * * * * * P R O G R A M * * * * * P R O G R A M *********************************************************************** DFHPEP CSECT DFHPEP RMODE ANY DFHREGS , R1,R1...
Page 464 PEP_COM_CURRENT_ABEND_CODE PEP_COM_ORIGINAL_ABEND_CODE PEP_COM_USERS_EIB * Debugging information (program, PSW, registers and execution key at * time of abend, hit storage indicator). If the abend occurred in a * DPL server program running remotely, only program is meaningful. PEP_COM_DEBUG PEP_COM_ABPROGRAM PEP_COM_PSW PEP_COM_REGISTERS...
Page 465: The Sample Program Error Programs
The sample program error programs Two source-level versions of the default program are provided: DFHPEP, coded in assembler language, and DFHPEPD, coded in C. Both are in the CICSTS32.CICS.SDFHSAMP library. There is an assembler-language macro, DFHPCOM, and a corresponding C copy book, DFHPCOMD, that you can use to define the communication area.
Page 466 Customization Guide...
Page 467: Chapter 7. Writing A Transaction Restart Program
A transaction must be terminating abnormally. © Copyright IBM Corp. 1977, 2011 new task is attached that invokes the initial program of the transaction. This is true even if the task abended in the second or subsequent UOW, and DFHREST requested a restart.
Page 468: The Dfhrest Communications Area
v The transaction abend which caused the transaction to be terminating abnormally must have been detected before the commit point of the implicit syncpoint at the end of the transaction has been reached. v The transaction must be defined as restartable in its transaction definition. v The transaction must be related to a principal facility.
Page 469: The Cics-Supplied Transaction Restart Program
The equated values for this parameter are: XMRS_WRITE_YES XMRS_WRITE_NO XMRS_SYNCPOINT Indicates, in a 1-byte field, whether the transaction has performed any syncpoints. The equated values for this parameter are: XMRS_SYNCPOINT_YES XMRS_SYNCPOINT_NO XMRS_RESTART_COUNT This indicates, as an unsigned, half-word binary value, the number of times the transaction has been restarted.
Page 470 v AFCW, indicating that the transaction abended due to a VSAM-detected deadlock (RLS only). The source of the CICS-supplied default transaction restart program, DFHREST, is supplied in assembler language only, in the CICSTS32.CICS.SDFHSAMP library. The assembler copybook for mapping the communications area is in the CICSTS32.CICS.SDFHMAC library.
Page 471: Chapter 8. Writing A Terminal Error Program
When an abnormal condition associated with a particular terminal or line occurs, the terminal control program puts the terminal out of service and passes control to the terminal abnormal condition program (DFHTACP) which, in turn, passes control to a © Copyright IBM Corp. 1977, 2011...
Page 472: Terminal Control Program
version of the terminal error program (DFHTEP, either CICS-supplied or user-written), so that it can take the appropriate action. Terminal control program When the terminal from which the error was detected has been put out of service, the terminal control program creates a terminal abnormal condition line entry (TACLE), which is chained off the real entry, the terminal control table line entry (TCTLE) for the line on which the error occurred.
Page 473: The Communication Area
The communication area The communication area is the basic interface used by the sample DFHTEP, and should be used by a user-written DFHTEP to: v Address the TACLE v Indicate the course of action to be taken on return to DFHTACP. Before giving control to DFHTEP, DFHTACP establishes which default actions should be taken.
Page 474 of as the number of error occurrences that are permitted for a given type of error on a given terminal before the sample DFHTEP accepts the DFHTACP default actions. Optionally, the number of occurrences can be controlled and accounted for over prescribed time intervals (for example, if more than three of a given type of error occur in an hour, the terminal is put out of service).
Page 475: Structure Of The Sample Terminal Error Program
SYMBOLIC TERMINAL ID ERROR STATUS ELEMENT COMMON ERROR BUCKET Figure 21. Terminal error block (TEB) An ESE records the occurrence of a particular type of error associated with the terminal. The contents of an error status element are described in the TEPCD DSECT (generated by the DFHTEPM TYPE=INITIAL macro) under the comment “ERROR STATUS ELEMENT FORMAT”.
Page 476 Figure 22 on page 456 gives an overview of the structure of the sample terminal error program. Entry and initialization On entry, the sample TEP uses DFHEIENT to establish base registers and addressability to EXEC Interface components. It obtains addressability to the communication area passed by DFHTACP by means of an EXEC CICS ADDRESS COMMAREA, and addressability to the EXEC interface block with an EXEC CICS ADDRESS EIB command.
Page 477 General exit Control is passed to a general exit routine from each error processor. This routine determines whether the terminal is to remain in service. If the terminal is to be put out of service, the terminal error block and all error status elements for that terminal are deleted from the TEP error table unless the terminal was defined as a permanent entry.
Page 478: Sample Terminal Error Program Messages
Error Error processor processor Figure 22. Overview of the sample terminal error program (DFHXTEP) 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.
Page 479 of each type of message by using the appropriate parameters specified on the PRINT operand of DFHTEPM TYPE=INITIAL. These messages are: DFHTEP, ERROR – error text During DFHTEP module generation, the PRINT parameter specified ERRORS. This message can be suppressed by using the NOERRORS option. The error text is one of the following: Unsupported error code, “xx”...
Page 480: Generating The Sample Terminal Error Program
This message contains the symbolic terminal ID of the device associated with the error. This message can be suppressed by using the NOTID option. DFHTEP, DECB - DECB information During the DFHTEP module generation, the PRINT parameter specified DECB. This two-line message contains the DECB (printed in hexadecimal format) of the terminal causing the error.
Page 481 macros are related and care must be taken to ensure compatibility. The parameters concerned are identified in the descriptions of the macros later in this chapter. If you use the sample terminal error program (DFHXTEP), you can generate the required program and transaction definitions by using the CEDA INSTALL GROUP(DFHSTAND) command.
Page 482 DFHTEPM TYPE=INITIAL [,DSECTPR={YES|NO}] [,OPTIONS=([TD|(TD,destid)|NOTD] [,EXITS|,NOEXITS] [,TIME|,NOTIME] [,PRINT=([ERRORS|NOERRORS] [,TACPACTION|,NOTACPACTION] [,TEPACTION|,NOTEPACTION] [,TID|,NOTID] [,DECB|,NODECB] [,TACLE|,NOTACLE] [,ESE|,NOESE])] TYPE=INITIAL establishes the beginning of the generation of the sample DFHTEP module itself. DSECTPR={YES|NO} controls the printing of CICS DSECTs on the sample DFHTEP assembly listing. Its purpose is to reduce the size of the listing. The default is DSECTPR=YES. Printing of the DSECTs is allowed.
Page 483 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.
Page 484 TACLE|NOTACLE specifies whether the TACLE prefix is to be recorded on the transient data destination. TACLE NOTACLE ESE|NOESE specifies whether the ESE associated with the error is to be recorded on the transient data destination. NOESE DFHTEPM TYPE=ENTRY and EXIT–for user entry and exit routines The sample DFHTEP provides guidance about how to prepare error processor routines, particularly with regard to register and subroutine linkage conventions.
Page 485 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.
Page 486 * GENERATE USER STORAGE DFHTEPM TYPE=USTOR USORFLD DS F DFHTEPM TYPE=USTOREND * MODULE SPECIFICATIONS DFHTEPM TYPE=INITIAL, OPTIONS=((TD,TEPQ),NO3270,EXITS), PRINT=(NOTEPACTION,NOTACPACTION), DSECTPR=NO * USER-SUPPLIED ERROR PROCESSORS DFHTEPM TYPE=ERRPROC,CODE=87 TEPCD81 DS 0H error processor "87" source statements TEPRET DFHTEPM TYPE=ERRPROC,CODE=9F TEPCD9C DS 0H error processor "9F" source statements TEPRET * USER "EXIT"...
Page 487 DFHTEPT TYPE=INITIAL–establishing the control section The DFHTEPT TYPE=INITIAL macro necessary to establish the control section for the TEP tables is: DFHTEPT TYPE=INITIAL ,MAXTIDS=number [,MAXERRS={25|number}] [,OPTIONS={TIME|NOTIME}] TYPE=INITIAL establishes the beginning of the generation of the TEP tables. MAXTIDS=number specifies the total number of permanent and reusable terminal error blocks to be generated in the TEP error table.
Page 488 TYPE=PERMTID defines permanently reserved terminal error blocks for specific terminals. Permanent TEBs are defined for terminals that are critical to system operation to ensure that error processors are always executed in the event of errors associated with that terminal. If no permanent TEBs are to be defined, this macro is not required.
Page 489 default actions to be taken. If the number of occurrences is less than the threshold, the error processor normally takes a logic path that overrides the DFHTACP default actions. The updating and testing of the current threshold counts are normally performed by a DFHTEP subroutine that sets a condition code that the error processor can test to determine whether the limit has been reached.
Page 490 Table 23 illustrates the default thresholds of the sample terminal error program, referred to in the TYPE, COUNT, and TIME operands of the DFHTEPT TYPE=PERMCODE|ERRCODE macro. Table 23. Default thresholds of the sample TEP 95 (Note 1) 97 (Note 1) 9F (Note 1) Notes: 1.
Page 491 DFHTEPT TYPE=FINAL–terminating DFHTEPT entries The DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEP tables. DFHTEPT TYPE=FINAL DFHTEPT–examples of how the macros are used 1. The following is an example of the minimum number of statements required to generate the TEP tables: DFHTEPT DFHTEPT This example generates 10 reusable terminal error blocks, each capable of...
Page 492: Writing Your Own Terminal Error Program
Writing your own terminal error program You can write your own terminal error program in any of the languages supported by CICS. However, CICS-supplied code is provided in assembler language only. The names of the supplied source files and macros, and the libraries in which they can be found, are listed in Table 24.
Page 493: Addressing The Contents Of The Communication Area
Addressing the contents of the communication area After your terminal error program receives control from DFHTACP, it should obtain the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command. You generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program.
Page 494 ABORTWR (X'08') RELTTIOA (X'04') SIGNOFF (X'02') On entry to DFHTEP, the above flags represent the default actions set by DFHTACP. The write-abend bit (communication area field ABORTWR) and the abend-task bit (communication area field ABENDT) are always set if the place-line-out-of-service bit (X'80') is set;...
Page 495: Addressing The Contents Of The Tacle
and DFHTACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message to CSMT; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or, rarely, ‘AEXZ’. v Abend write has no effect if the TCTTE was associated with a READ request. In this case the normal result is that, if the line and terminal remain in service, the read is retried.
Page 496 After you have carried out the required functions and, optionally, altered the default actions scheduled by DFHTACP, the user-written DFHTEP must return control to DFHTACP by issuing the EXEC CICS RETURN command. DFHTACP then performs the actions specified in the TACLE and causes the error processing task to terminate.
Page 497: Example Of A User-Written Terminal Error Program
Displacement Code Bytes Label TCTLEPSA RESERVED TCTLEPFL (All codes not listed are reserved and are not intended for use by DFHTEP) TCTLEPF2 TCTLEPTE TCTLEECB TCTLEOA Figure 27. Format description of the TACLE DSECT (part 2) Example of a user-written terminal error program The “DFHTEP recursive retry routine”...
Page 498 (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).
Page 499 *ASM XOPTS(NOPROLOG NOEPILOG SP) ************************************************************************ DFHTEP RECURSIVE RETRY ROUTINE ************************************************************************ DFHEISTG DFHEIEND DFHTEPCA TYPE=DSECT COPY DFHA06DS USING DFHA06DS,STATBAR PCIAREA DSECT PCISAVE DS PCICNT TCTLEAR EQU STATBAR EQU TCTUABAR EQU COMMABAR EQU EJECT DFHTEP CSECT *********************************************************************** Establish addressability *********************************************************************** DFHEIENT EXEC CICS ADDRESS EIB(11) EXEC CICS ADDRESS COMMAREA(COMMABAR) USING DFHTEPCA,COMMABAR TCTLEAR,TEPCATCA...
Page 500 EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) PCISAVE,A06TENI INCR PCICNT,=P’1’ PCICNT,=P’10’ RETRY PCICNT,=P’0’ EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) PCISAVE,A06TENI NORETRY CKCOUNT DS EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR) PCISAVE,A06TENI RESET INCR RETRY NORETRY DS LTORG , Figure 29. DFHTEP recursive retry routine (part 2) 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.
Page 501: Chapter 9. Writing A Node Error Program
435 apply to this chapter. This chapter contains information about the node error program (NEP) of CICS Transaction Server for z/OS, Version 3 Release 2. Node error programs, not terminal error programs, must be used for terminals and logical units supported via the ACF/VTAM interface.
Page 502: Background To Cics-Vtam Error Handling
Background to CICS-VTAM error handling In general, errors detected by CICS-VTAM terminal control are queued for handling by a special task, the CICS node error handler (transid CSNE). (Note that CICS finds it convenient to use the same technique for some housekeeping work, such as sending “good morning”...
Page 503: An Overview Of Writing A Nep
Program resource definitions for DFHZNAC and DFHZNEP themselves are provided in the IBM-supplied CSD group, DFHVTAM. The key features of the DFHZNAC-DFHZNEP interface are as follows: v DFHZNEP can be written in any of the CICS-supported languages.
Page 504: The Default Nep
The action flags can be set or reset within DFHZNEP. The action flags set by DFHZNAC for specific error codes and sense codes are listed in Appendix B, “Default actions of the node abnormal condition program,” on page 855. The default NEP The CICS-supplied default NEP, DFHZNEP, sets the “print TCTTE”...
Page 505 other, reusable NEBs for general use. If you expect to accumulate error statistics about 10 LUs concurrently, you need 10–12 NEBs. Each NEB may contain multiple recording areas, one being used for each group of errors you want to distinguish. The error groups correspond to those in the NEP. That is, they are groups of error types requiring separate processing logic.
Page 506 will then locate the correct ESB within a selected NEB. The latter may be permanently dedicated to the LU in error (a named NEB), or may be one taken from the general pool. The initial code then invokes the appropriate user logic for that error group. The initial code also sets up pointers to the communication area, the NEB, and the ESB.
Page 507: Multiple Neps
The 3270 sample code is not intended to cover all error conditions. Note that the code is not suitable for SNA 3270s (LU session type 2). Error conditions arising from these result in different DFHZNAC error codes and may require different handling.
Page 508: When An Abnormal Condition Occurs
You also have to provide the sub-NEPs for the various NEP transaction classes, including, of course, one for the default NEPCLASS(0). Each of these sub-NEPs needs a separate program definition. You have the same choice in coding each sub-NEP as you had when there was just one; you can code your own, or use the CICS sample macro DFHSNEP.
Page 509: The Communication Area
DFHZNAC assumes that system sense codes are available upon receipt of an exception response from the logical unit. Thus, analysis is performed to determine the reason for the response. Decisions, such as which action flags to set and which requests are needed, are made based upon the system sense codes received. If sense information is not available, default action flags are set, and DFHZEMW is scheduled to send a negative response, if a response is outstanding, with an error message to the terminal.
Page 510 Header Error_being_processed User option bytes VTAM information Additional information for NEP Additional system parameters XRF parameters Figure 30. General structure of the communication area The significance of each section of the communication area is described below: Header A 4-byte header common to all user-replaceable programs. Error_being_processed Identifiers of the error code and the terminal associated with the error.
Page 511 ********************************************************************** Header These fields are READ ONLY ********************************************************************** NEPCAHDR DS 0XL4 NEPCAFNC DS NEPCACMP DS ********************************************************************** Error_being_processed Identity of terminal and the error code associated with it These fields are READ ONLY ********************************************************************** TWAEC TWANID TWANETN DS ********************************************************************** User option bytes Initially set to the default actions.
Page 512 ********************************************************************** VTAM information - Any VTAM sense and RPL codes These fields are READ ONLY ********************************************************************** TWAVTAM DS 0XL12 TWARPLCD DS TWASENSS DS TWASS1 TWASS2 TWAUS1 TWAUS2 TWASENSR DS TWASR1 TWASR2 TWAUR1 TWAUR2 ********************************************************************** Additional information for the NEP **Except for TWANPFW, TWANLD, and TWANLDL these fields are READ ONLY** ********************************************************************** TWAADINF DS 0XL22...
Page 513 ********************************************************************** Additional system parameters **Except for TWAPNETN, TWAPNTID, TWAUPRRC these fields are READ ONLY** ********************************************************************** TWASYSPM DS 0XL68 TWATCTA DS TWARPL TWATIOAA DS TWATIOAL DS TWACOMML DS TWACOMMA DS TWATECIA DS TWATECIL DS TWAPPNTN DS TWAPPTID DS TWAPPELG DS TWAPPELY EQU X’01’...
Page 514 causes CICS to take a system dump when there is no task attached to the terminal at the time of error detection, if the flag TWAOAT in TWAOPT2 is also set on. Setting the TWAONQN flag causes the network qualified name to be printed after any message that contains the action flag.
Page 515 “good morning” message transaction is initiated (the transaction specified by the system initialization parameter GMTRAN). The flags are: TWAOAS (X'80') TWAOAR (X'40') TWAOAT (X'20') TWAOCT (X'10') TWAOGMM (X'08') TWAOPBP (X'04') TWAOASM (X'02') Note: TWAOPT3 User option byte 3. TWAOPT3 contains flags which are node-related. The flags are: TWAOINT (X'80') TWAONINT (X'40')
Page 516 TWAONCN (X'10') TWAOSCN (X'08') TWAONEGR (X'04') TWAOOS (X'02') TWAOCN (X'01') TWAONINT forces TWAOCN. TWAONEGR forces TWAOAR and TWAOAT. TWAOOS forces TWAOCN. TWAOCN forces TWAOAR, TWAOAS, and TWAOAT. TWAOOS indicates that no further processing is to be done for this node. The node is logically out of service.
Page 517 TWANLD of the communication area, and the length of the data in field TWANLDL. The data is logged to the CSNE transient data queue for future inspection. Note: No data in excess of 220 bytes is logged. You can also send user-written messages to the CSNE log using the transient data facility.
Page 518: The Sample Node Error Program
The sample node error program The sample node error program provides a general environment for the execution of error processing routines (error processors), each of which is specific to certain error codes generated by the node abnormal condition program. Sufficient optional error processors for normal operation of VTAM 3270 or interactive logical unit networks are provided;...
Page 519 v Optional error processors for 3270 or interactive logical units. A node error program cannot be generated with both 3270 and interactive logical unit error processors. The components are described in the sections that follow. Entry section On entry, the sample NEP uses DFHEIENT to establish base registers and addressability to the EXEC interface.
Page 520 Node Error Table NODE ERROR TABLE HEADER NODE ERROR BLOCK PERMANENTLY ASSIGNED NEBs DYNAMICALLY ASSIGNED NEBs Figure 34. Format of node error table and node error block Optional common subroutines The common subroutines are addressed via the CSVT and provide error processors with the following functions: v Locate or assign NEBs and ESBs on the basis of node ID and error group index.
Page 521: Generating The Sample Node Error Program
Optional error processor for interactive logical units Only one error processor is supplied for interactive LUs: group index 1, with error code X'DC'. This error code, in combination with a user sense value of X'081B', indicates a ‘receiver in transmit mode’ condition. The action flags in TWANPFW are manipulated to allow the failing SEND request to be retried.
Page 522 DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL. The DFHSNEP TYPE=USTOREND macro has the following format: This macro indicates the end of user storage definitions. Its use is mandatory if DFHSNEP TYPE=USTOREND DFHSNEP TYPE=USTOR has been coded.
Page 523 DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=(D9,DC,DD,F2) Sense/status error processor code. DFHSNEP TYPE=ERRPROC,GROUP=2,CODE=42 Unavailable printer error processor code. DFHSNEP TYPE=DEFILU—including error processors for INTLUs The DFHSNEP TYPE=DEFILU macro has the following format: DFHSNEP TYPE=DEFILU TYPE=DEFILU specifies that the CICS-supplied error processor for interactive logical units is to be included in the node error program.
Page 524 in the range X'01' through X'FF' (a leading zero can be omitted). The error processor name has the form NEPROCxx, where “xx” is the error group index. A CSECT statement of this name is generated, which causes the error processor code to be assembled at the end of the node error program module and to have its own addressability.
Page 525 4. Registers 4 through 9 can be saved by common subroutines in an area DFHSNET—generating the node error table The DFHSNET macro is used to generate a node error table. Each node error table that you generate must be defined to CICS. DFHSNET [NAME=DFHNET|name] [,COUNT=100|threshold] [,ESBS=1|(index,length,...)]...
Page 526 specified in the COUNT operand is not exceeded before this time interval elapses, the error count is reset to 0. Specify “units” as SEC, MIN, or HRS. The maximum values for “interval” are as follows: (86400,SEC), (1440,MIN), or (24,HRS). This operand is optional, and the default is set to (7,MIN). DSECTs The following DSECTs are provided: Node Error Table Header: This contains the table name and common information...
Page 527: Writing Your Own Node Error Program
CSVTESBL CSVTNEBD CSVTECUP Writing your own node error program You can write your own NEP in any of the CICS-supported languages. However, CICS-supplied NEP code is provided in assembler language only. The communication area parameter list is supplied in assembler-language and C versions.
Page 528: Entry And Addressability
v Updates to recoverable resources. If the resources are locked by another task, the CSNE unit of work could be suspended or shunted. You should also note that you cannot use the NEP to suppress DFHZNAC messages. Entry and addressability On entry, your NEP should issue the commands: EXEC CICS ADDRESS COMMAREA EXEC CICS ADDRESS EIB...
Page 529: Coding For Session Failures
Before linking to the node error program, DFHZNAC inserts the primary and secondary printer netnames and terminal IDs into the communication area, indicating also whether either printer is eligible for a print request. DFHZNAC links to the node error program with no default actions set. On return from the node error program, DFHZNAC checks the additional system parameter TWAUPRRC in the communication area (see Figure 31 on page 489) and, based on its contents, performs one of the following actions:...
Page 530: Coding For Specific Vtam Sense Codes
If used in this way, the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however, that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened. Refer to “Restrictions on the use of EXEC CICS commands”...
Page 531 DFHZNEPI TYPE=INITIAL—specifying the default routine The DFHZNEPI TYPE=INITIAL macro specifies the name of the default transaction-class routine to be used for the DFNZNEPI module. DFHZNEPI TYPE=INITIAL [,DEFAULT=name] DEFAULT=name specifies the name of the default transaction-class routine to be used. A link is made to this default routine if you specify for the transaction (using the CEDA DEFINE PROFILE, CEDA DEFINE SESSIONS, or CEDA DEFINE TYPETERM command) a NEPCLASS value of 0 (the default) or higher than 255, or if you...
Page 532: Handling Shutdown Hung Terminals In The Node Error Program
Using the node error program with XRF or persistent sessions This section contains guidance information about the NEP in an XRF or persistent sessions environment for CICS Transaction Server for z/OS, Version 3 Release 2. The node error program in an XRF environment The CICS extended recovery facility (XRF) is described in the CICS/ESA 3.3 XRF...
Page 533: The Node Error Program With Persistent Session Support
system-wide recovery notification options (whether terminal users are notified of a recovery, the recovery message, or the recovery transaction) for some terminals, you should write your own error processor to handle code X'3F'. (For details of the recovery notification parameters passed to the NEP, see the listing of communication area fields in Figure 31 on page 489.) The node error program with persistent session support Persistent session support is described in the CICS Recovery and Restart Guide.
Page 534: Changing The Recovery Message
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.
Page 535 the others have all been shut down), the ISSUE PASS command does not fail with an INVREQ. Instead, the terminal is logged off and message DFHZC3490 is written to the CSNE log. You may want to code your node error program to deal with the situation when message DFHZC3490 (DFHZNAC error code X'C3') is issued.
Page 536 Customization Guide...
Page 537: Chapter 10. Writing A Program To Control Autoinstall Of Terminals
CEDA commands that create the environment in which your control program can work. If you choose automatic installation for some or all of your terminals, you must: © Copyright IBM Corp. 1977, 2011...
Page 538: Coding Entries In The Vtam Logon Mode Table
MODEENT macro. Some of the examples in the appendix correspond exactly to entries in the IBM-supplied logon mode table called ISTINCLM. Where this is so, the table gives the name of the entry in ISTINCLM.
Page 539: The Autoinstall Control Program For Terminals
Coding entries for MTS You need to define model names (MDLTAB, MDLENT, and MDLPLU macros) and printer and associated printer names (ASLTAB, ASLENT, and ASLPLU macros) to VTAM. The autoinstall control program for terminals In addition to managing your resource definition, your autoinstall control program can perform any other processes that you want at this time.
Page 540: The Communication Area At Install For Terminals
v Autoinstall processing has been completed to a point where information (a terminal identifier and autoinstall model name) from the control program is required to proceed. The communication area at INSTALL for terminals The layout of the communication area is shown in Figure 36. Fullword 1 Standard Header Byte 1...
Page 541: How Cics Builds The List Of Autoinstall Models
The control program selects one model from this list, and CICS uses this model to build the TCTTE for the device. The default autoinstall control program, DFHZATDX, always selects the first model name in the list. If you are not using MTS but need a printer ID or NETNAME (or an alternative printer ID or NETNAME) associated with this terminal, then your control program can supply this in the area addressed by fullword 4.
Page 542: Returning Information To Cics
model name into the model name list (Autinstmodelname_1), and also into the model name field (Modelname) in the selection list addressed by fullword 4 of the parameter list. If CICS is unable to find an MTS model name in the MTS Control Vector, or the named model does not exist or is invalid, it builds the list of autoinstall models by selecting from the complete list of terminal models those models that are compatible with the VTAM information describing the resource.
Page 543 used to name a CONNECTION. It should therefore conform to the naming standards for a CONNECTION (rather than a TERMINAL) as defined in CONNECTION definition attributes, in the CICS Resource Definition Guide. The user program could identify an LU6.2 AUTOINSTALL request in one of the following ways: –...
Page 544 As a general rule, all the models in the list passed to your program match the VTAM data for the terminal. That is, a viable TCT entry usually results from the use of any of the models. (The exception to this rule involves the VTAM RUSIZE; if this value is incompatible, CICS issues an error message.) The default autoinstall control program merely picks the first model in the list.
Page 545: Cics Action On Return From The Control Program
However, you may be in a situation where you must continue to use unique and predictable TERMINAL names for your terminals. Your control program must be able to assign the right TERMINAL name to each terminal, every time the user logs on.
Page 546 satisfactory, CICS schedules the new resource for OPNDST in order to complete the logon request. If the installation process fails, then the control program is driven again, as though a DELETE had occurred. (See the section “The autoinstall control program at DELETE” on page 525 for details.) This is necessary to allow the program to free any allocations (for example, terminal identifiers) made on the assumption that this INSTALL request would succeed.
Page 547: The Autoinstall Control Program At Delete
The autoinstall control program at DELETE To provide symmetry of control over the autoinstall process, the autoinstall control program is also invoked when: v A session with a previously automatically-installed resource has been ended v An autoinstall request was accepted by the user program, but the subsequent INSTALL process failed for some reason.
Page 548: Naming, Testing, And Debugging Your Autoinstall Control Program
Table 27. Autoinstall control program’s parameter list at DELETE (continued) Third fullword Next 15 bytes Note that the named resource has been deleted by the time the control program is invoked, and is not therefore found by any TC LOCATE type functions. Naming, testing, and debugging your autoinstall control program Finding the name of an autoinstall control program The supplied, user-replaceable autoinstall control program for terminals and APPC...
Page 549: The Sample Autoinstall Control Programs For Terminals
If CICS attempts to BIND, compare the device’s CINIT RU to the CICS BIND, and make corrections accordingly. It is very important that you ensure that the VTAM LOGMODE table entries for your terminals are correct, rather than defining new autoinstall models to fit incorrectly coded entries.
Page 550: Customizing The Sample Program
The default action of the sample program, on INSTALL, is to select the first model in the list, and derive the terminal identifier from the last four nonblank characters of the NETNAME, set the status byte, and return to CICS. If there are no models in the list, it returns with no action.
Page 551 REGISTER CONVENTIONS = R0 used by DFHEICAL expansion R1 -------"-------"------"---- R2 Base for Input parameters R3 Base for code addressability R4 Base for model name list R5 Base for output parameter list R6 Work register R7 -----"------- R8 -----"------- R9 free R10 Internal subroutine linkage return R11 Base for EIB R12 free...
Page 552 VALIDT SELECTED_MODELNAME,C’ ’ VALIDM1 R6,MODELNAME_COUNT R6,R6 RETURN R8,MODELNAME LOOP2 8(8,R7),0(R8) VALIDM R8,L’MODELNAME(R8) R6,LOOP2 Now we know the required model name was not presented to this exit by CICS, a return rejects the logon RETURN At this point the model name was found in those presented It is given to CICS and the new termid is the netname VALIDM...
Page 553 * Redefine the netname so that the last 4 characters (of 7) * can be used to select the autoinstall model to be used. * The netnames to be supplied are known to be of the form: HVMXNNN * HVM is the prefix is the system name * NNN is the address of the terminal 01 NETNAME-BITS.
Page 554 DCL 1 CINIT 2 CINIT_LENG 2 CINIT_RU SAVE_CINIT DCL 1 SCRNSZ 2 SPARE /* Bypass first part of CINIT and reach */ 2 DHGT /* Screen default height in BIND PS area */ 2 DWID /* Screen default width in BIND PS area */ 2 AHGT /* Screen alternate height in BIND PS area */ 2 AWID...
Page 555 /* Now access the screen PS area in the portion of the BIND image presented in the CINIT RU */ /* using the screen alternate height as a guide to the model of terminal attempting logon. If this cannot be determined then default to the first model in the table */ SELECT (AHGT);...
Page 556 Customization Guide...
Page 557: Chapter 11. Writing A Program To Control Autoinstall Of Consoles
Specify AICONS=AUTO (or issue a CEMT (or EXEC CICS) SET AUTOINSTALL CONSOLES(FULLAUTO) command). v Create at least one model TERMINAL definition that references a TYPETERM definition specifying DEVICE(CONSOLE). You can use the IBM-supplied definition in group DFHTERMC if it suits your needs. v Install the model TERMINAL and TYPETERM definition.
Page 558: The Autoinstall Control Program At Install
Note: 1. You can have only one active autoinstall control program to handle 2. Your autoinstall program must be able to recognise the console v Enable the CICS AUTOINSTALL function for consoles. You can do this either by specifying AICONS=YES as a system initialization parameter, or by issuing a SET AUTOINSTALL CONSOLES(PROGAUTO) command.
Page 559 Fullword 1 Standard Header Byte 1 Function Code Bytes 2 - 3 Component Code Byte 4 Reserved Fullword 2 Pointer to CONSOLENAME_FIELD Fullword 3 Pointer to MODELNAME_LIST Fullword 4 Pointer to SELECTED_PARMS Fullword 5 Reserved Figure 44. Autoinstall control program’s communication area at INSTALL for consoles The parameter list contains the following information: 1.
Page 560: How Cics Builds The List Of Autoinstall Models
'FD' Fullword 2 Fullword 3 Fullword 4 Modelname Terminal ID Reserved Reserved Return code Reserved Reserved Reserved Delete Delay i/o i/o i/o i/o Note: designates an input/output field. The other fields in SELECTED_PARMS are output only. Figure 45. Autoinstall control program’s parameter list at INSTALL 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.
Page 561 If you want an INSTALL request to proceed, perform these steps in your autoinstall control program: v Return an autoinstall model name in the first 8 bytes of the area addressed by fullword 4 of the parameter list. v Supply a CICS terminal name (TERMID) in the next four bytes of the return area. DFHZATDX and DFHZATDY take the last four non-blank characters of the console name (addressed by fullword 2 of the parameter list) as the terminal name.
Page 562: Cics Action On Return From The Control Program
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.
Page 563: The Sample Autoinstall Control Programs For Consoles
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”...
Page 564 Customization Guide...
Page 565: Chapter 12. Writing A Program To Control Autoinstall Of Appc Connections
If autoinstall is enabled, and an incoming APPC BIND request is received for an APPC service manager (SNASVCMG) session (or for the only session of a single-session connection), and there is no matching CICS CONNECTION definition, a new connection is created and installed automatically. © Copyright IBM Corp. 1977, 2011...
Page 566: Autoinstall Templates For Appc Connections
Like autoinstall for other resources, autoinstall for APPC connections requires model definitions. However, unlike the model definitions used to autoinstall terminals, those used to autoinstall APPC links do not need to be defined explicitly as models. Instead, CICS can use any previously-installed connection definition as a “template” for a new definition.
Page 567: The Autoinstall Control Program For Appc Connections
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.
Page 568 X'F2' represents an install request for an APPC parallel-session connection from a secondary node via a CINIT request. Note: These requests cannot be received by CICS Transaction Server for z/OS, Version 3 Release 2. INSTALL_APPC_PS_BIND X'F3' represents an install request for an APPC parallel-session...
Page 569 A fullword pointer to an input field containing the incoming CINIT, if the incoming session is a secondary. Note: Not applicable to CICS Transaction Server for z/OS, Version 3 Release INSTALL_APPC_BIND_PTR A fullword pointer to a 2-byte length field, followed by an input field containing the incoming BIND.
Page 570 Your control program can use the TEMPLATE_NETNAME field to specify the NETNAME of the template. For connections between generic resources, your program can accept the suggested template passed by CICS, or specify a different one—either in this field or by overwriting the suggested template with blanks and putting a value in the TEMPLATE_SYSID field.
Page 571: The Autoinstall Control Program At Delete
The autoinstall control program at DELETE To provide symmetry of control over the autoinstall process, the autoinstall control program is also invoked when an autoinstalled APPC connection is deleted. Invoking the control program at DELETE enables you to reverse the processes carried out at the INSTALL event.
Page 572: The Sample Autoinstall Control Program For Appc Connections
Synclevel 1 connections installed via a BIND Synclevel 1-only APPC connections autoinstalled via a BIND request (except for limited resource connections installed on a CICS generic resource member—see next section) are implicitly deleted at the following times: v When the connection is released v If VTAM abends v When the VTAM ACB is closed by CICS v After the expiry of the AIRDELAY interval following a warm or emergency start (if...
Page 573: Resource Definitions
USAGE(NORMAL) DATALOCATION(ANY) Note: This type of request cannot be received by CICS Transaction Server for z/OS, Version 3 Release 2. An incoming BIND for an APPC parallel-session connection. Specify a template. This is done in one of two ways: v For connections between two generic resources, by accepting the suggested template (the generic resource name connection) whose NETNAME is passed in TEMPLATE_NETNAME.
Page 574 Customization Guide...
Page 575: Chapter 13. Writing A Program To Control Autoinstall Of Ipic Connections
The purpose of a template is to provide CICS with a definition that can be used for all connections with the same properties. You customize the supplied autoinstall user program to select an appropriate template for each new connection, depending on the information it receives from CICS. © Copyright IBM Corp. 1977, 2011...
Page 576 You can use any installed IPCONN definition as a template but, for performance reasons, your template must be an installed definition that is not in use. The definition is locked while CICS is copying it, and, if you have a large number of IPCONNs being autoinstalled at one time you might notice the delay.
Page 577: The Autoinstall User Program At Install
If the default user program is not adequate for your purposes, you can write a customized version of the default program or create your own program to provide enhanced function. CICS supplies the source code of the default program in several programming languages;...
Page 578: The Autoinstall User Program At Delete
isaic_networkid (Input) An 8-character field containing the network ID of the system trying to connect, as sent on the connect flow. isaic_port (Input/Output) The call back port number for the client. -1 means that no call back is allowed. The autoinstall user program can modify this for the same reason that it can modify the host name, unless it is -1, in which case it cannot be changed.
Page 579: When Autoinstalled Ipconns Are Deleted
isaic_function (Input) The function for which the user program has been invoked: X'F1' isaic_ipconn (Input) The name of the autoinstalled IPCONN. isaic_applid (Input) The applid (of the remote system) specified on the autoinstalled IPCONN. isaic_networkid (Input) The network ID (of the remote system) specified on the autoinstalled IPCONN. isaic_tcpipservice (Input) The name of the TCPIPSERVICE on which the connect flow arrived.
Page 580: Default Actions Of The Sample Program
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.
Page 581: Chapter 14. Writing A Program To Control Autoinstall Of Shipped Terminals
For more information about using aliases on remote definitions, see Local and remote names for terminals, in the CICS Intercommunication Guide. Note: The autoinstall control program is invoked for all shipped terminals and connections, including shipped definitions of the virtual terminals used by CICS Clients. © Copyright IBM Corp. 1977, 2011...
Page 582: Cics-Generated Aliases
CICS-generated aliases The autoinstall control program is invoked once for each shipped terminal or connection definition to be installed. If CICS detects that the name on a shipped definition clashes with the name of a remote terminal, local terminal, or connection already installed in the AOR, it generates an alias TERMID and passes it to the control program in field SELECTED_SHIPPED_TERMID of the communications area.
Page 583: The Autoinstall Control Program At Install
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.
Page 584: The Communications Area At Install For Shipped Terminals
autoinstall control program at INSTALL” on page 536. The parameter list passed at INSTALL of local APPC connections initiated by BIND requests is described in “The communication area at INSTALL for APPC connections” on page 545. The parameter list passed at INSTALL of Client virtual terminals is described in “The communications area at INSTALL for Client virtual terminals”...
Page 585 (the value of the TERMINAL or CONNECTION attribute on the shipped definition) is already in use in the AOR to identify an installed remote terminal or connection. The name by which the terminal or connection is known in the TOR is not in use in the AOR to identify a remote terminal or connection.
Page 586: The Autoinstall Control Program At Delete
Shipped terminal and connection definitions are deleted by the CICS Transaction Server for z/OS, Version 3 Release 2 timeout delete mechanism. For details of the timeout delete mechanism, see Efficient deletion of shipped terminal definitions, in the CICS Intercommunication Guide.
Page 587: Default Actions Of The Sample Programs
DELETE_SHIPPED_TERM (X'FA') DELETE_SHIPPED_RSE (X'FB') DELETE_SHIPPED_TERMID A 4-character field containing the identifier (TERMID) of the terminal or connection in the TOR. DELETE_SHIPPED_APPLID An 8-character field containing the netname (applid) of the TOR. DELETE_SHIPPED_LTERMID A 4-character field containing the name by which the terminal or connection is known in the AOR.
Page 588 Customization Guide...
Page 589: Chapter 15. Writing A Program To Control Autoinstall Of Virtual Terminals
3. “The autoinstall control program at DELETE” on page 575 4. “Default actions of the sample programs” on page 577. How Client virtual terminals are autoinstalled Client virtual terminals are defined to CICS Transaction Server for z/OS, Version 3 Release 2 as remote 3270 datastream devices. Autoinstall models...
Page 590: Why Override Termids
CICS)? You may not need to; it may depend on the way in which your server programs are written. By “server programs” we mean both the transaction programs started by Client EPI programs, and those started from the Client terminal emulator.
Page 591 Client workstations, as previously described.) 3. Definitions of Client virtual terminals are not deleted by the CICS Transaction Server for z/OS, Version 3 Release 2 timeout delete mechanism that operates on shipped terminal definitions. That is, the timeout delete mechanism does not operate on the (remote) definitions of Client terminals on the CICS Transaction Server for z/OS, Version 3 Release 2 system on which the install Client terminal transaction (CTIN) runs.
Page 592: How Bridge Facility Virtual Terminals Are Autoinstalled
How bridge facility virtual terminals are autoinstalled Bridge facility virtual terminals are defined to CICS Transaction Server for z/OS, Version 3 Release 2 as LU2 devices. They are created by the 3270 bridge mechanism to support the execution of a CICS 3270 application in a bridged environment, where all terminal interaction is intercepted and passed to the 3270 bridge mechanism.
Page 593: Bridge Facility Name Uniqueness
v The USERID of the first transaction in a pseudoconversation can be obtained using EXEC CICS ASSIGN USERID. v The TRANSID of the first transaction in a pseudoconversation can be obtained from EIBTRNID. The autoinstall control program can use the USERID and TRANSID values to derive new TERMID and NETNAME values and return them in the communications area.
Page 594 Note: The communications area for INSTALL of virtual terminals is the same as that for INSTALL of shipped terminals and connections—that is why the field names contain the word “SHIPPED”. *--------------------------------------------------------------------------* * Remote install parameter list - Client virtual terminal function *--------------------------------------------------------------------------* INSTALL_SHIPPED_COMMAREA INSTALL_SHIPPED_STANDARD...
Page 595: The Communications Area At Install For Bridge Facility Virtual Terminals
SELECTED_SHIPPED_TERMID SELECTED_SHIPPED_RETURN_CODE INSTALL_SHIPPED_TERMID_PTR A fullword pointer to a 4-character input field containing the TERMID passed to the CICS autoinstall function (that is, the supplied name). INSTALL_SHIPPED_APPLID_PTR A fullword pointer to an 8-character input field containing the netname (applid) of the Client workstation. INSTALL_SHIPPED_SYSID_PTR A fullword pointer to a 4-character input field containing the name (sysid) of the connection to the Client workstation.
Page 596 ----------------------------------------------------------------------- * Install Bridge Facility *---------------------------------------------------------------------* INSTALL_BRFAC_COMMAREA DSECT INSTALL_BRFAC_STANDARD DS F ORG INSTALL_BRFAC_STANDARD INSTALL_BRFAC_EXIT_FUNCTION DS XL1 INSTALL_LINK_BRFAC EQU X’0F’ Install Link Brfacility INSTALL_START_BRFAC EQU X’11’ Install Start Brfacility INSTALL_BRFAC_EXIT_COMPONENT DS CL2 DS CL1 ORG , INSTALL_BRFAC_NETNAME_PTR DS A INSTALL_BRFAC_SELECTED_PTR DS A INSTALL_BRFAC_TERMID_PTR DS A DS A...
Page 597: The Autoinstall Control Program At Delete
DELETE for bridge facility virtual terminals” on page 576. Shipped terminal and connection definitions are deleted by the CICS Transaction Server for z/OS, Version 3 Release 2 timeout delete mechanism. For details of the timeout delete mechanism, see Efficient deletion of shipped terminal definitions, in the CICS Intercommunication Guide.
Page 598: The Communications Area At Delete For Bridge Facility Virtual Terminals
DELETE_SHIPPED_EXIT_FUNCTION A 1-byte field that indicates the type of resource being deleted. The equated value for Client virtual terminals is DELETE_SHIPPED_TERM (X'FC'). Note: A value of X'F1' represents the deletion of a local terminal, or an APPC DELETE_SHIPPED_TERMID A 4-character field containing the name by which the virtual terminal is known to the Client.
Page 599: Default Actions Of The Sample Programs
INSTALL_LINK_BRFAC (X'10') INSTALL_START_BRFAC (X'12') DELETE_BRFAC_EXIT COMPONENT A 2-byte component code, which is set to ‘BR’ DELETE_BRFAC_TERMID A 4-character field containing the bridge facility name. DELETE_BRFAC_NETNAME An 8-character field containing the netname of the bridge facility. Default actions of the sample programs When DFHZATDX or DFHZATDY is invoked at INSTALL of a Client virtual terminal, 1.
Page 600 Customization Guide...
Page 601: Chapter 16. Writing A Program To Control Autoinstall Of Programs
– EXEC CICS SEND PARTNSET – EXEC CICS RECEIVE PARTN – A dynamic COBOL call v A program abend occurs, and CICS transfers control to the program named on an EXEC CICS HANDLE ABEND command. © Copyright IBM Corp. 1977, 2011...
Page 602: Autoinstall Model Definitions
A definition that specifies DYNAMIC(YES) No definition of the server program Customization Guide CICS runs the server program on the local region. CICS ships the LINK request to the remote region. CICS invokes the dynamic routing program to route the LINK request.
Page 603: Autoinstall Processing Of Mapsets
Note: This assumes that the autoinstall control program chooses not to Autoinstall processing of mapsets Table 30 shows the differences in mapset processing between CICS regions with program autoinstall active and inactive. Table 30. Differences in mapset processing between autoinstall and non-autoinstall Program autoinstall INACTIVE CSD definition is required.
Page 604: Faster Startup Times
Faster startup times Warm and emergency starts If you are using program autoinstall with cataloging, restart times are similar to those of restarting a CICS region that is not using program autoinstall. This is because, in both cases, resource definitions are reinstalled from the catalog during the restart.
Page 605: The Autoinstall Control Program At Install
The autoinstall control program at INSTALL On invocation, CICS passes a parameter list to the autoinstall control program by means of a communication area addressed by DFHEICAP. The communications area is mapped by a copybook that is supplied in each of the languages supported by CICS.
Page 606 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.
Page 607 If the program is the subject of a program-link request, the dynamic routing program is not invoked. For a distributed program link (DPL) request, the server region on which the program is to execute must be specified explicitly on the REMOTESYSTEM option of the PROGRAM definition or on the SYSID option of the EXEC CICS LINK command;...
Page 608: The Sample Autoinstall Control Program For Programs, Dfhpgadx
PGAC_JVM allows you to specify, in a 1-byte field, whether the program is to be run under a JVM. The equated values are: PGAC_JVM_YES PGAC_JVM_NO PGAC_JVM_CLASS_LEN allows you to specify, as a two-byte binary value, the length of the Java class name supplied in PGAC_JVM_CLASS_DATA.
Page 609: Resource Definition
If you customize the supplied control program, or write your own version, you should note the following: v Input:The first two fields of the parameter list are input-only fields and should not be altered by your program. v Output:The remaining fields on the parameter list are input/output or output only fields, which you can use to specify attributes that override those of the model definition.
Page 610: Testing And Debugging 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;...
Page 611: Chapter 17. Writing A Dynamic Routing Program
The rest of the chapter is divided into the following sections: 1. “Routing transactions dynamically” on page 590 2. “Routing DPL requests dynamically” on page 597 © Copyright IBM Corp. 1977, 2011 named on the DTRPGM system initialization parameter—to route: v CICS business transaction services activities and processes.
Page 612: Routing Transactions Dynamically
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. “Testing your dynamic routing program” on page 621 8.
Page 613: Information Passed To The Dynamic Routing Program
v After the routed transaction has completed, if the routing program has requested to be reinvoked at termination. v If the routed transaction abends, if the routing program has requested to be reinvoked at termination. Figure 57 shows the points at which the dynamic routing program is invoked. Route selection Notification Route selection error...
Page 614: Changing The Target Cics Region
Sometimes, the dynamic routing program may be invoked for transactions that are routed statically. This happens if a transaction defined as DYNAMIC(YES) is initiated by automatic transaction initiation (ATI)—for example, by the expiry of an interval control start request—but the transaction is ineligible for dynamic routing. In this case, the dynamic routing program is called only to notify it of where the transaction is going to run.
Page 615: Changing The Program Name
Important To route a transaction defined by the DTRTRAN definition, your dynamic routing program must set the DYRDTRRJ field of the communications area to 'N' (the default is 'Y'). If you leave DYTDTRRJ set to 'Y', the transaction is rejected. You can test the DYRDTRXN field to check if the transaction passed to your routing program is defined by the DTRTRAN definition.
Page 616: If The System Is Unavailable Or Unknown
If the system is unavailable or unknown The dynamic routing program is invoked again if the remote system name that you specify on the route selection call is not known or is unavailable. When this happens, you have a choice of actions: v You can tell CICS not to continue trying to route the transaction, by issuing a return code of ‘8’...
Page 617: Modifying The Initial Terminal Data
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.
Page 618: Receiving Information From A Routed Transaction
4. For information about the IBM CICS Interdependency Analyzer for z/OS, see the CICS Interdependency Analyzer for z/OS User's Guide and Reference.
Page 619: Unit Of Work Considerations
result of logic in the routed transaction. You should also consider carefully the effect of EXEC CICS SYNCPOINT and ABEND commands on APPC transaction routing. v If you want to keep information about how transactions are routed, it must be done in the user routing program, perhaps by writing the information to a temporary storage queue associated with this terminal.
Page 620: When The Dynamic Routing Program Is Invoked
ONC/RPC calls. A program-link request received from outside CICS can be dynamically routed by: v Defining the program to CICS Transaction Server for z/OS as DYNAMIC(YES) v Coding your dynamic routing program to route the request. When the dynamic routing program is invoked...
Page 621: Changing The Target Cics Region
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.
Page 622: Changing The Transaction Id
alternative program is to be linked. You can specify a local or remote program, depending on the region to which the request is to be routed. Changing the transaction ID A transaction identifier is always associated with each dynamic program-link request.
Page 623: Using The Xpceres Exit To Check The Availability Of Resources On The Target Region
been set to ‘N’—the request is not to be queued—for this error to occur), issue a return code of ‘0’ in DYRRETC, and try to route the request again. v You can change the sysid, and issue a return code of ‘0’ in DYRRETC to try to route the request again.
Page 624: Invoking The Dynamic Routing Program At End Of Routed Requests
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.
Page 625: Unit Of Work Considerations
If you want to avoid this, you have to define the routing program’s resources as non-recoverable. For information about the syncpoint activity of DPL client and server programs, see The server program, in the CICS Intercommunication Guide.
Page 626: Changing Bridge Request Parameters
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.
Page 627: Rejecting A Link3270 Bridge Request
v If the SYSIDs are the same (or the returned SYSID is blank) CICS executes the link request locally. v If the two SYSIDs are not the same, CICS routes the request to the remote CICS region, using the returned transaction name. Changing the bridge request TRANSID The TRANSID of the target user transaction is passed to the dynamic routing program in DYRTRAN.
Page 628: Re-Invoking The Dynamic Routing Program After Link3270 Bridge Requests
To use the XPCERES exit, both the routing region and the target region must support the “resource unavailable” condition (RESUNAVAIL). All the following support the “resource unavailable” condition: v CICS TS OS/390, Version 1.3, with APAR PQ73107 applied v CICS TS for z/OS, Version 2.2, with APAR PQ74920 applied v CICS TS for z/OS, Version 2.3 and later The exit is invoked, if enabled, on the target region before CICS processes a dynamically-routed Link3270 bridge request.
Page 629: Modifying The Application's Containers
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.
Page 630 OCL4 DYRFUNC DYRCOMP DYRFILL1 DYRERROR DYROPTER DYRQUEUE DYRFILL2 DYRRETC DYRSYSID DYRVER DYRTYPE DYRFILL3 DYRTRAN DYRCOUNT DYRBPNTR DYRBLGTH DYRRTPRI DYRFILL4 DYRPRTY DYRNETNM DYRLPROG DYRDTRXN DYRDTRRJ DYRFILL5 DYRSRCTK DYRABNLC DYRABCDE DYRCABP DYRLEVEL DYRFILL6 DYRACMAA DYRACMAL DYRUAPTR * THE FOLLOWING 7 FIELDS APPLY ONLY TO BTS TRANSACTIONS DYRCBTS 0CL176 DYRPROCN...
Page 631 under the DYRFUNC parameter the value X'5' is not listed because it is never passed to the dynamic routing program—it occurs only on a route initiate call to the distributed routing program. If you use the same program as both a dynamic routing program and a distributed routing program, for descriptions of the parameters and values that are significant on distributed routing calls refer to “Parameters passed to the distributed routing program”...
Page 632 When your routing program is invoked because the routed transaction has abended (DYRFUNC=4), the information in the communications area, or in the DFHROUTE container, is not meaningful. Your routing program can alter the data in any application’s communications area, or DFHROUTE container, addressed by DYRACMAA. DYRACMAL This field applies to the routing of: v Terminal-initiated transactions...
Page 633 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.
Page 634 This indicator is always set to the reject condition when the dynamic routing program is invoked. To dynamically route a transaction defined by the DTRTRAN definition, you must change this to the accept condition. If you reject the transaction, message DFHAC2001—“Transaction ‘tranid’ is unrecognized”—is sent to the user’s terminal for dynamic transaction routing.
Page 635 The selected system is in service, but no sessions are available. 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.
Page 636 CICS to the next, without bringing down the server. Requests that require a specific level of CICS can be routed to an appropriate AOR.
Page 637 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.
Page 638 You can specify this option for transactions, link requests, or bridge requests that are routed to remote CICS regions and also for those that are executed locally. DYRPROCCMP is not used by the dynamic routing program. On invocation, it is set to nulls. DYRPROCID is not used by the dynamic routing program.
Page 639 Terminate the transaction with either a message or an abend. Whenever the routing program is invoked, DYRRETC is set to ‘0’. When it is invoked for route selection or because an error occurs in route selection, if you want CICS to continue processing the transaction, you must leave it set to ‘0’.
Page 640 client that the dynamic routing program has rejected the request, and a compcode that gives details of the reason the last attempt to route the request failed. You do not need to set a return code when the routing program is invoked for notification or at transaction termination.
Page 641 – If DYRERROR is set to ‘2’ (no session available) and you want CICS to retry routing, you must change DYRSYSID or change the value of DYRQUEUE to ‘Y’ (queue the request until a session is available). v When DYRFUNC is set to ‘2’ (termination of a routed request), DYRSYSID contains the name of the CICS region on which the completed transaction or link request executed.
Page 642 To ensure that DYRVER is '7' or greater, you must apply the PTFs for the following APARs to any of your routing or target regions at that CICS release: CICS Transaction Server for z/OS Version 2 Release 3 In systems where DYRUAPTR is less than '7' the contents of DYRUAPTR are unpredictable.
Page 643: Naming Your Dynamic Routing Program
DYRVER is the version number of the dynamic routing program interface. For CICS Transaction Server for z/OS, Version 3 Release 2, the number is “10”. Naming your dynamic routing program The supplied, user-replaceable dynamic routing program is named DFHDYP. If you write your own version, you can name it differently.
Page 644: Dynamic Transaction Routing Sample Programs
v The invocation of the dynamic routing program if the routed transaction abends (DYRFUNC=4), if you have specified DYROPTER=Y. If you want EDF to display the execution of your dynamic routing program only, either choose dual-terminal mode, or use one of the other methods described in Execution diagnostic facility (EDF), in the CICS Application Programming Guide.
Page 645: Chapter 18. Writing A Distributed Routing Program
629 4. “Routing non-terminal-related START requests” on page 637 5. “Routing inbound Web service requests” on page 641 © Copyright IBM Corp. 1977, 2011 named on the DSRTPGM system initialization parameter—to route: v Transactions initiated from user terminals...
Page 646: Differences Between The Distributed And Dynamic Routing Interfaces
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 11.
Page 647: Routing Bts Activities
3. The distributed routing program is invoked at more points than the dynamic routing program. Figure 60 on page 627 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. 4. Unlike the dynamic routing program, the distributed routing program cannot: v Select a target region by supplying a netname (any value set in the DYRNETNM field of the communications area is ignored).
Page 648: When The Distributed Routing Program Is Invoked
“Daisy-chaining” is not supported. That is, once a BTS activity has been routed to a target region it cannot be re-routed from the target to a third region, even though its associated transaction is defined as DYNAMIC(YES). When the distributed routing program is invoked For BTS processes and activities started by RUN ASYNCHRONOUS commands, CICS invokes the distributed routing program at the following points: On the routing region:...
Page 649: Changing The Target Cics Region
Requesting/routing region Route selection Notification Route selection error Routing attempt complete Figure 60. When and where the distributed routing program is invoked Changing the target CICS region The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the process or activity is to be routed.
Page 650: If An Error Occurs In Route Selection
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend. If an error occurs in route selection If an error occurs in route selection—for example, if the sysid returned by the distributed routing program is unavailable or unknown—the distributed routing program is invoked again.
Page 651: Routing Method Requests For Enterprise Beans And Corba Stateless Objects
Dynamic Figure 61. A CICS logical EJB/CORBA server. The logical server consists of a set of cloned “listener” regions and a set of cloned AORs. In this example, connection optimization by means of dynamic DNS registration is used to balance client connections across the listener regions.
Page 652 For example, if a client starts an OTS transaction, does some work, and then calls a method on an enterprise bean, so far as the CICS EJB server is concerned this is a “new” OTS transaction, because the server has not been called within this transaction’s scope before.
Page 653: Which Requests Can Be Dynamically Routed
EJB/CORBA server: v If the request is for an object owned by the local EJB/CORBA server (that is, the CORBASERVER name on the REQUESTMODEL definition is the name of the local CorbaServer): –...
Page 654: When The Distributed Routing Program Is Invoked
There are two reasons for a method to be associated with an existing OTS transaction: 1. A client makes a second or subsequent method call to the same server object within the scope of the same client OTS transaction, and the called methods support an external transaction coordinator.
Page 655: Changing The Target Cics Region
This invocation signals that (unless the routing region and the target region are one and the same) the routing region’s responsibility for this request has been discharged. On the target region: These invocations occur only if the target region is CICS TS for z/OS, Version 2.1 or later and the routing program on the routing region has specified that it should be reinvoked on the target region: 1.
Page 656: Telling Cics Whether To Route The Method Request
When it is invoked for route selection, the distributed routing program can change the target region by changing the value in DYRSYSID. If the specified sysid is invalid, or cannot be found, SYSIDERR is returned to the distributed routing program—which may deal with the error by returning a different sysid—see “If an error occurs in route selection.”...
Page 657: Dealing With A Disabled Corbaserver
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. v If the routed method is part of an OTS transaction, if the OTS transaction ends successfully.
Page 658 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.
Page 659: Performing A Rolling Upgrade Of An Ejb/Corba Server
“rolling upgrade” of a multi-region logical server, whereby one region at a time is upgraded from one release of CICS to the next, without bringing down the server. Requests that require a specific level of CICS can be routed to an appropriate AOR. For details, see DYRLEVEL.
Page 660: When The Distributed Routing Program Is Invoked
“Daisy-chaining” is not supported. That is, once a non-terminal-related START request has been dynamically routed to a target region it cannot be dynamically routed from the target to a third region, even though the transaction is defined as ROUTABLE(YES) and DYNAMIC(YES). The transaction may, however, be statically routed from the target region to a third region.
Page 661: Changing The Target Cics Region
Figure 63 shows the points at which the distributed routing program is invoked, and the region on which each invocation occurs. Note that the “target region” is not necessarily remote—it could be the local (routing) region, if the routing program chooses to execute the START request locally.
Page 662: If An Error Occurs In Route Selection
Returning a value in DYRRETC has no effect when the routing program is invoked for notification, routing complete, transaction initiation, transaction termination, or abend. If an error occurs in route selection If an error occurs in route selection—for example, if the sysid returned by the distributed routing program is unavailable or unknown—the routing program is invoked again.
Page 663: Invoking The Distributed Routing Program On The Target Region
Invoking the distributed routing program on the target region The route selection, notification, route selection error, and routing complete invocations of the distributed routing program all occur on the routing region. If the routing program wants to be re-invoked on the target region, it must set the DYROPTER field in the communications area to 'Y'.
Page 664: When The Distributed Routing Program Is Invoked
region, even though the transaction is defined as ROUTABLE(YES) and DYNAMIC(YES). The transaction may, however, be statically routed from the target region to a third region. When the distributed routing program is invoked For inbound Web service requests that are eligible for enhanced routing, CICS invokes the distributed routing program at the following points: On the routing region: 1.
Page 665: Changing The Target Cics Region
Requesting/routing region Route selection Notification Route selection error Routing attempt complete Figure 64. When and where the distributed routing program is invoked Changing the target CICS region The DYRSYSID field of the communications area passed to the distributed routing program initially contains the system identifier (sysid) of the default target region to which the request is to be routed.
Page 666: If An Error Occurs In Route Selection
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.
Page 667: Some Processing Considerations
The recommended way of dealing with an abend on the target region is as follows: 1. Code your routing program so that, on each route selection (and route selection error) call, it specifies that it is to be reinvoked (for transaction initiation, termination, and abend) on the target region—see “Invoking the distributed routing program on the target region”...
Page 668 DYRFUNC DYRCOMP DYRFILL1 DYRERROR DYROPTER DYRQUEUE DYRFILL2 DYRRETC DYRSYSID DYRVER DYRTYPE DYRFILL3 DYRTRAN DYRCOUNT DYRBPNTR DYRBLGTH DYRRTPRI DYRFILL4 DYRPRTY DYRNETNM DYRLPROG DYRDTRXN DYRDTRRJ DYRFILL5 DYRSRCTK DYRABNLC DYRABCDE DYRCABP DYRLEVEL DYRFILL6 DYRACMAA DYRACMAL DYRUAPTR * THE FOLLOWING 8 LINES APPLY ONLY TO BTS TRANSACTIONS DYRCBTS 0CL176 DYRPROCN...
Page 669 under the DYRTYPE parameter the value X'4' is not listed because it is never passed to the distributed routing programit occurs only on a program-link-related call to the dynamic routing program. If you use the same program as both a distributed routing program and a dynamic routing program, for descriptions of the parameters and values that are significant on dynamic routing calls refer to “Parameters passed to the dynamic routing program”...
Page 670 DYRACTID is the CICS-assigned, 52-character activity identifier of the BTS activity being routed. (When a process is being routed, DYRACTID returns the identifier of the root activity.) This field applies only to the routing of BTS processes and activities. DYRACTN is the name of the BTS activity being routed.
Page 671 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: The selected sysid is unknown.
Page 672 DYRFUNC tells you the reason for this invocation of the distributed routing program. The possible values are: Customization Guide resource is unavailable on the target region. This error code may be set for program-link, Link3270 bridge, and non-terminal-related START requests. Invoked for route selection.
Page 673 CICS to the next, without bringing down the server. Requests that require a specific level of CICS can be routed to an appropriate AOR.
Page 674 DYRNETNM is not used by the distributed routing program. On invocation, it is set to null characters. Note: To set the target region, the distributed routing program must use the DYROPTER specifies whether the distributed routing program is to be reinvoked on the target region when the transaction associated with the routed request: 1.
Page 675 DYRPROCT is the process-type of the BTS process to which the process or activity being routed belongs. This field applies only to the routing of BTS processes and activities. DYRPRTY is not used by the distributed routing program. On invocation, it is set to zeroes. DYRQUEUE identifies whether or not the request is to be queued if no sessions are immediately available to the remote system identified by DYRSYSID.
Page 676 The distributed routing program can accept the value of DYRSYSID or change it before returning to CICS. If the sysid you return to CICS is the same as the local sysid, CICS executes the request on the local region. v When DYRFUNC is set to 1 (route selection error), DYRSYSID contains the CICS region name returned to CICS by the distributed routing program on its previous invocation.
Page 677 To ensure that DYRVER is '7' or greater, you must apply the PTFs for the following APARs to any of your routing or target regions at the specified CICS release: CICS Transaction Server for z/OS Version 2 Release 3 PQ81378 In systems where DYRUAPTR is less than '7' the contents of DYRUAPTR are unpredictable.
Page 678: Naming Your Distributed Routing Program
DYRVER is the version number of the dynamic routing interface. For CICS Transaction Server for z/OS, Version 3 Release 2, the number is 10. Naming your distributed routing program The supplied, sample distributed routing program is named DFHDSRP. If you write your own version, you can name it differently.
Page 679: Distributed Transaction Routing Sample Programs
Note: A sample definition is provided for DFHDSRP, but you must install a new resource definition for a customized distributed routing program. Distributed transaction routing sample programs The CICS-supplied sample distributed routing program is named DFHDSRP. The corresponding copy book that defines the communications area is DFHDYPDS. There are assembler-language, COBOL, PL/I, and C source-level samples and copy books.
Page 680 Customization Guide...
Page 681: Chapter 19. Writing A Cics-Dbctl Interface Status Program
DBUREQT Request Type. The function code has one of the following values: DBUCONN (X'01') 7. The interface that enables DBCTL databases to be accessed from CICS. © Copyright IBM Corp. 1977, 2011 Standard Header Function Code Component Code Always "DB"...
Page 682: The Sample Cics-Dbctl Interface Status Program
DBUDISC (X'02') DBUREAS Reason for Disconnection. Contains flags: DBUMENU (X'01') DBUDBCC (X'02') DBUDRAF (X'03') DBUDBCF (X'04') DBUSUFF DRA startup table suffix. DBUDBCTL DBCTL identifier. The sample CICS–DBCTL interface status program The source-code of the supplied CICS–DBCTL interface status program, DFHDBUEX, is provided, in assembler language only, in the CICSTS32.CICS.SDFHSAMP library.
Page 683: Chapter 20. Writing A 3270 Bridge Exit Program
For a detailed description of the 3270 bridge exit and its interfaces, see Bridging to 3270 transactions, in the CICS External Interfaces Guide. © Copyright IBM Corp. 1977, 2011 ® MQ commands in a bridge exit so that CICS can GET and...
Page 684 Customization Guide...
Page 685: Chapter 21. Writing A Security Exit Program For Iiop
(44) FULLWORD (48) FULLWORD (4C) FULLWORD (50) FULLWORD Where: standard_header contains a standard header with the following format: function domain © Copyright IBM Corp. 1977, 2011 Type Len Name 80 sXOPUS 4 standard_header 4 pIIOPData 4 lIIOPData 4 pRequestBody 4 lRequestBody...
Page 686 pIIOPData contains the address of the first megabyte of the unconverted IIOP buffer. If the incoming request is fragmented, this field contains a pointer to: v the first megabyte of the first fragment, if the first fragment is greater than v a 32K buffer containing data from the first fragments that fit in the buffer, if the first fragment is less than or equal to 32K.
Page 687: The Sample Programs
sslClientUserid return_code contains the return code. reason_code contains the reason code. A user ID can be returned, but other fields are provided for information only. For further information about the use of the IIOP security user-replaceable program, see Using the IIOP user-replaceable security program, in the Java Applications in CICS.
Page 688: Dfheburm
If you write your own security exit program, it should return all fields other than userid and return_code unchanged, or unpredictable results will occur. DFHEBURM DFHEBURM is for use with the EJB Bank Account sample program. It alters the user ID under which the sample runs from the default CICS user ID to “SAMPLE”. For more information about DFHEBURM, see The EJB Bank Account sample application, in the Java Applications in CICS.
Page 689: Chapter 22. Writing Programs To Customize Jvms
CICS supplies sample Java classes, com.ibm.cics.samples.SJMergedStream and com.ibm.cics.samples.SJTaskStream, that you can use for this purpose. Sample source is provided for both these classes, in the directory /usr/lpp/cicsts/ cicsts32/samples/useroutputclass.
Page 690: The Com.ibm.cics.server.outputredirectionplugin Interface
JVM. The CICS-supplied samples implement this interface. The sample classes themselves are made up of: v A superclass com.ibm.cics.samples.SJStream that implements this interface v The subclasses com.ibm.cics.samples.SJMergedStream and com.ibm.cics.samples.SJTaskStream, which are the classes that are actually named in the JVM profile.
Page 691: Possible Destinations For Output
by one provided in a subclass. It does not implement a writeRecord method, and such a method must be provided by any subclass to control the output redirection process.You could imitate this in your own class structure. The initialization of output redirection can also be performed using a constructor, rather than the initRedirect method.
Page 692: Using Dfhjvmro To Modify The Language Environment Enclave For A Jvm
Guide tells you how to use reports obtained using the RPTO and RPTS options to identify suitable storage heap values. v At the request of the IBM service team, set other options to obtain diagnosis information. Note that the initial heap size and the heap increment sizes defined by DFHJVMRO are for minimal values, and less than the minimum heap size for a typical JVM.
Page 693: Using Dfhjvmat To Modify Options In A Jvm Profile
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.
Page 694: Options In The Jvm Profile That Are Available To Dfhjvmat
Some of the options are no longer documented in the CICS documentation, and information about these can be found in the documentation for the IBM SDK for z/OS, Java 2 Technology Edition and other Java documentation.
Page 695 JAVA_DUMP_OPTS Set of Java dump options to obtain diagnostics for an abend in the JVM JAVA_HOME Path to IBM SDK for z/OS, Java 2 Technology Edition subdirectories and JAR files JVMPROPS Path and name of the JVM properties file LIBPATH_PREFIX,...
Page 696 Table 34. JVM profile options available to DFHJVMAT (continued) Option Xrundllname Xverify Two additional fields not found in a standard JVM profile are passed to DFHJVMAT, as follows: CICS_PROGRAM Specifies the name of the CICS program (1-8 characters) associated with the Java class to be run.
Page 697: Chapter 23. Writing A Distinguished Name Program For Clients Of Enterprise Beans
Before returning, DFHEJDNX must place in this field the length of the distinguished name it has built. ejdn_userid_ptr A pointer to the client’s userid. ejdn_userid_len A binary fullword containing the length of the client’s userid. © Copyright IBM Corp. 1977, 2011...
Page 698 ejdn_common_name_ptr A pointer to the proposed common name of the client, derived from the username associated with the client’s userid in the external security manager’s database. ejdn_common_name_len A binary fullword containing the length of the client’s common name. ejdn_title_ptr A pointer to the proposed title of the client, derived from the title in the X.509 certificate associated with the CorbaServer.
Page 699: Sample Programs And Copy Books
Sample programs and copy books The default distinguished name program is an assembler-language program named DFHEJDNX. The source of the default program is provided in assembler-language and C. The corresponding copy book that defines the communications area is provided in assembler-language, C, COBOL, and PL/I. The names of the supplied source programs and copy books, and the CICSTS32.CICS libraries in which they can be found, are summarized in Table 35.
Page 700 Customization Guide...
Page 701: Chapter 24. Writing An Ejb Event Program
“install failed”; the event may, for instance, indicate that there was a UNIX file problem. Your application developers can use the RM for enterprise beans to browse this detailed information. © Copyright IBM Corp. 1977, 2011...
Page 702: The Dfhejep Communications Area
The DFHEJEP communications area The DFHEJEP communications area is mapped by the EJEV_COMMAREA DSECT, which is supplied in the DFHEJEPH copybook. The information passed in the communications area is as follows: EJEV_BEANNAME The 240-byte name of the bean involved in this event. For some events (for example, the discard of a DJAR) there is no bean name, in which case this field is blank.
Page 703: Event Codes
Event codes Table 36 shows the codes and meanings of all EJB events that may be passed to the EJB event program. Table 36. EJB event codes. The table shows the event type and meaning of each event code. The “Bean name” column indicates whether the EJEV_BEANNAME field in the DFHEJEP communications area contains the name of an enterprise bean.
Page 704: The Ejb Event Sample Program
Table 36. EJB event codes (continued). The table shows the event type and meaning of each event code. The “Bean name” column indicates whether the EJEV_BEANNAME field in the DFHEJEP communications area contains the name of an enterprise bean. The “DJAR name”...
Page 705 Table 37. EJB event programs and copy books (continued) Language Copy books: v DFHEJEPD v Assembler v DFHEJEPH v DFHEJEPO v COBOL v DFHEJEPL v PL/I You can use the supplied program as the basis of your own EJB event program. Your program could, for example, use different criteria than the default program to filter the EJB events passed to it;...
Page 706 Customization Guide...
Page 707: Chapter 25. Writing Programs To Customize Language Environment Run-Time Options For Xplink Programs
A CICS-supplied DFHAPXPO module is provided, setting some run-time options. See the fully-commented module source for an example of how to set these options. CICS programs can include a CEEUOPTS CSECT to supply Language Environment run-time options to control the program's execution. © Copyright IBM Corp. 1977, 2011...
Page 708 Customization Guide...
Page 710 (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. Customization Guide...
Page 711: Chapter 26. The Extended Recovery Facility Overseer Program
Restart to enable or disable the restart-in-place function of the overseer program Snap to take a snap dump of the sample program © Copyright IBM Corp. 1977, 2011...
Page 712 to terminate the sample program Open to ask the overseer to try to open CICS availability manager (CAVM) data sets that it has previously failed to open. The full format of the operator command entered at the MVS console is: MODIFY overseer-jobname,command-identifier where “command-identifier”...
Page 713 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.
Page 714 active-alternate pairs are not to be automatically restarted in place, regardless of whether restart processing is enabled or disabled. This is described in “How to tell the overseer which actives and alternates to monitor” on page 693. The Restart command works like an ON/OFF switch. Restart in place is enabled when the sample program is initialized.
Page 715: How The Sample Overseer Program Interfaces With Cics
This problem arises only if the overseer is initialized before all the CAVM data sets have been formatted. If it occurs, the operator can use the Open command (see Open ) to retry the opening of those CAVM data sets on which the Open previously failed.
Page 716 The sample overseer program reads the DFHOSD records in key sequence and builds a table of entries. Each active-alternate pair is known by its generic applid on this data set. Every entry on the data set contains the following information: v A 12-byte key field, containing the 4-byte value ‘GNbb’...
Page 717: The Dfhwosm Macros
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.
Page 718: Dfhwosm Func=Build Macro
by the overseer program and passed back to DFHWOS as input to the OPEN, CLOSE, READ, QJJS, and TERM macros. DFHWOSM FUNC=BUILD macro The DFHWOSM FUNC=BUILD macro must be issued by the overseer program to initialize its communication with DFHWOS. No other macro can be issued by the overseer program until DFHWOS FUNC=BUILD has completed successfully.
Page 719: Dfhwosm Func=Dsect Macro
DFHWOSM FUNC=DSECT macro The DFHWOSM FUNC=DSECT macro generates a number of DSECTs, including the DSECT of the DBLID definitions. DFHWOSM FUNC=DSECT DFHWOSM FUNC=JJC macro The DFHWOSM FUNC=JJC macro issues a JES cancel for a named job with a JES job identifier. DFHWOSM FUNC=JJC [,PARM={parm address|1}] [,TOKEN={token register|14}]...
Page 720: Dfhwosm Func=Open Macro
For FUNC=QJJS, the PARM value is a pointer to the addresses of the following: v An 8-byte job name v An 8-byte JES job ID v A 256-byte SSOB return area v A doubleword area to hold two ECBs. The FUNC=QJJS macro requires 2 ECBs: the first is posted when the JES call completes;...
Page 721: Dfhwosm Func=Oscmd Macro
A register 15 return code value of ‘0’ through ‘5’ indicates that a DFHWOSM FUNC=READ macro can now be issued. A return code value of ‘6’ or above indicates that the OPEN has failed and that the overseer program will not be able to access the CAVM data sets.
Page 722 Input The PARM value is a pointer to a parameter list that contains the addresses of the generic applid and the “dbllist”. The dbllist is a list of one or more doublewords. In the first two bytes of the second word of each of these doublewords you supply the DBLID of the information you require.
Page 723 DBLIDs for the active: DBLID1 X’0001’ DBLID2 X’0002’ DBLID3 X’0003’ DBLID4 X’0004’ DBLID5 X’0005’ DBLID6 X’0006’ DBLID7 X’0007’ DBLID8 X’0008’ DBLID9 X’0009’ DBLID10 EQU X’000A’ DBLID11 EQU X’000B’ DBLID12 EQU X’000C’ – X’001F’ DBLID32 EQU X’0020’ DBLID33 EQU X’0021’ DBLID34 EQU X’0022’...
Page 724 If a completion code of ‘0’ through ‘5’ is returned to register 15, each doubleword of the DBLLIST contains the address (4 bytes) and the length (2 bytes) of the output from this read. A completion code of ‘8’, ‘10C’, or ‘1xx’ indicates a READ failure. Reading DBCTL status information from the CAVM data sets If you are using DBCTL and have active and alternate DBCTL subsystems, status information about the subsystem connected to the active CICS is written to the...
Page 725: Dfhwosm Func=Term Macro
DFHDXGHD DSECT GHDDXADB DS GHDDXRSE DS GHDDXCTM DS GHDDXDTM DS GHDDXJNM DS GHDDXJID DS GHDDXASD DS GHDDXIRT DS DXRHTSBY EQU X’01’ DXRDBDC EQU X’02’ DXRDBCTL EQU X’04’ GHDDXTYP DS DXMCNNCT EQU X’01’ DXMDISC EQU X’02’ DXMDRAF EQU X’04’ DXMABEND EQU X’08’...
Page 726 The associated DSECTs are provided in member DFH$XRDS of CICSTS32.CICS.SDFHSAMP. There are several ways in which you can change the supplied code to make the overseer program more suitable for your installation. Here are some customization suggestions: v If the supplied display of status information (DSECT DSPDS) is not suitable, you can change the layout for your installation.
Page 727: Loop Or Wait Detection
user exit program to request a CICS abend, and thereby initiate a takeover, and for the overseer program to issue the PERFORM TAKEOVER command while acting on the same information. – At particular times of the day, perhaps when fewer operational staff are available than at other times, you may find it convenient to change the TAKEOVER setting for some, or all, of your regions.
Page 728 link-edit job step requires the entry name DFHXRONA. If you change any of the DSECTs used by the sample overseer program, you should reassemble the four modules. Customization Guide...
Page 730 (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. Customization Guide...
Page 731: Chapter 27. Cics Logging And Journaling
2. Secondary storage—when the primary storage for a log stream becomes full, the older records automatically spill into secondary storage, which consists of © Copyright IBM Corp. 1977, 2011...
Page 732 data sets managed by the storage management subsystem (SMS). Each log stream, identified by its log stream name (LSN), is written to its own log data sets. 3. Tertiary storage—a form of archive storage, used as specified in your hierarchical storage manager (HSM) policy. Optionally, older records can be migrated to tertiary storage, which can be either DASD data sets or tape volumes.
Page 733: Enabling, Disabling, And Reading Journals
Primary storage MVS1 System Logger Data Space Staging Data Sets Figure 72. The types of storage used by the MVS system logger. This diagram shows a log stream that uses DASD-only logging. Primary storage consists of a data space in the same MVS image as the system logger, and a single staging data set.
Page 734: Reading Journal Records Offline
CICS system log records are only available in the CICS Transaction Server for z/OS format, so you must ensure that any utilities that handled system log records in releases prior to CICS Transaction Server for OS/390, Version 1 Release 1 are converted to handle this format.
Page 735: Format Of General Log Block Header
System logs are always presented in CICS Transaction Server for z/OS format.. Each general log comprises a stream of contiguous blocks of journaled data. Each block comprises a block header followed by a variable number of CICS journal records. Each CICS journal record comprises a record header followed by caller data.
Page 736: Format Of General Log Journal Record
>DFHtrnn LGBH_GLOBAL_INFO CICS applid LGBH_GENERIC_APPLID Where t = Log type r = reserved nn = block version number Figure 74. Format of a general log block header LGBH_GLOBAL_INFO 8-bytes containing '>DFHtrnn', where: t = log type r = reserved nn = block version number LGBH_GENERIC_APPLID 8-byte CICS applid.
Page 737 Time (GMT) GLRH_GMT Record data length GLRH_REC_ DATA_LEN Header length GLRH_HEADER_LENGTH Record length GLRH_RECORD_LENGTH Figure 75. Format of a general log record header GLRH_RECORD_LENGTH 4-byte record length. GLRH_HEADER_LENGTH 4-byte header length. GLRH_REC_DATA_LEN 4-byte record data length. GLRH_GMT 8-byte time (GMT). GLRH_LOCAL 8-byte time (local).
Page 738: Start-Of-Run Record
Start of task indicator 1-byte which may contain: X’8n’ X’4n’ Reserved 3-byte reserved field. The caller data differs depending on the CICS component issuing the record, and on the function being journaled. Start-of-run record When CICS connects to a general log, it writes a start-of-run record to it as the first record for this run of CICS.
Page 739 Journal records can be written by any of the following CICS components: the logger, journal control (in the case of a request issued by a user), file control, the front end programming interface (FEPI), and terminal control. The field GLRH_REC_COMPID in the record header tells you which component has written the record: LG, UJ, FC, SZ, or TC respectively.
Page 740 Some records have a third and fourth section which are of variable length. Table 38 outlines the sections in a journal record written by file control. Table 38. FLJB sections in journal records issued by file control Record type First section Read-only FLJB_GENERAL_ Read-update...
Page 741 FLJB_GENERAL_DATA 12-byte general data. FLJB_COMMON_DATA 16-byte common data. FLJB_CD_KEY Variable-length caller data key. FLJB_CD_DATA Variable-length caller data. The format of the FLJB_GENERAL_DATA section is shown in Figure 79. Record type Flag byte FLJB_RECORD_TYPE FLJB_BITS X'80' read-only X'80' file control autojournal record X'81' read-update X'40' forward recovery log record X'82' write-update...
Page 742 FLJB_FILE_NAME 8-byte file name. Reserved 2-byte reserved field. The format of the FLJB_COMMON_DATA section is shown in Figure 80. Relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS or is extended ESDS) FLJB_CD_BASE_ESDS_RBA Length of...
Page 743 Write-delete record types There are four sections in the journal records written for write-delete record types: v The FLJB_GENERAL_DATA section, v The FLJB_WRITE_DELETE_DATA section, and v The two caller data image sections, which consist of: – FLJB_WDD_BASE_KEY (the length of which is given by FLJB_WDD_BASE_KEY_LENGTH in FLJB_WRITE_DELETE_DATA) –...
Page 744 Relative byte address of record in base data set for ESDS (0 if file does not refer to ESDS or is extended ESDS) FLJB_WDD_BASE_ESDS_RBA Base key length FLJB_WDD_BASE_KEY_LENGTH Figure 82. Format of the FLJB_WRITE_DELETE_DATA section 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).
Page 745 FLJB_GENERAL_DATA Figure 83. Layout of record written for file-close record types FLJB_GENERAL_DATA 12-byte general data section. FLJB_CLOSE_DATA 28-byte close data section. See Figure 79 on page 719 for the format of the FLJB_GENERAL_DATA section. The format of the FLJB_CLOSE_DATA section is shown in Figure 84. Fixed length Log stream name of the forward recovery log FLJB_FCD_FWDRECOVLOG_NAME...
Page 746 Tie-up record types There are two sections in the journal records written for tie-up record types: v The FLJB_GENERAL_DATA section v The TIE_UP_RECORD_DATA section. The format of such a record written for tie-up record types is shown in Figure 85. FLJB_GENERAL_DATA Figure 85.
Page 747 CI size of base data set FLJB_TUR_BASE_CI_SIZE Maximum record length FLJB_TUR_MAXIMUM_LRECL Base key position in record FLJB_TUR_BASE_KEY_POS Base key length FLJB_TUR_BASE_KEY_LENGTH Base data set name length FLJB_TUR_BASE_DSNAME_LENGTH Path data set name length FLJB_TUR_PATH_DSNAME_LENGTH Fixed length Log stream name of forward recovery log FLJB_TUR_FWDRECOVLOG_NAME Figure 86.
Page 748 FLJB_TUR_MAXIMUM_LRECL 4-byte maximum record length. FLJB_TUR_BASE_KEY_POSITION 4-byte base key position in record. FLJB_TUR_BASE_KEY_LENGTH 2-byte base key length. FLJB_TUR_DATASET_TYPE 1-byte data set type: X’C5’ X’D2’ X’D7’ X’D9’ X’E5’ X’E7’ FLJB_TUR_RECORD_FORMAT 1-byte record format: X’E5’ X’C6’ FLJB_TUR_BASE_DSNAME_LENGTH 2-byte length of base data set name. FLJB_TUR_BASE_DSNAME 44-byte base data set name.
Page 749 Fixed length Function identifier Module identifier InboundVTAM sequence number Figure 87. Format of the terminal control prefix area Function ID 1-byte function identifier. Module ID 1-byte module identifier. Inbound VTAM SN 2-byte inbound VTAM sequence number. Outbound VTAM SN 2-byte outbound VTAM sequence number. JCAUP TID 4-byte terminal identifier (padded with blanks if unused).
Page 750 Fixed length Pool name Reserved UP_ FEPPL Escape character for keystroke UP_ FEPES Conversation identifier Data function UP_ FEPDF Module identifier UP_ SVMID Module function UP_ MODFN Figure 88. Format of the FEPI prefix area UP_MODFN 1-byte module function UP_SVMID 1-byte module identifier UP_FEPDF 1-byte data function...
Page 751: Structure And Content Of Compat41-Format Journal Records
CICS/ESA 4.1. Use the COMPAT41 option on the SUBSYS=(LOGR...) step of your JCL. Within the data presented, certain fields are not presented at CICS Transaction Server for z/OS. They appear as X'00' in the formatted output. These fields are: Table 39. Fields formatted as X'00' JCLRJFID...
Page 752 Label header Length of block Not presented unless the caller is reading data blocks rather than records Figure 90. Format of journal control label header The label header part of the journal control label header is 10 bytes long, and its format is shown in Figure 91.
Page 753: Format Of Journal Record
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 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.
Page 754 Fixed length System header Figure 93. Format of COMPAT41 journal record The system header is 10 bytes long. Its format is shown in Figure 94. Fixed length Length of record JCRLL X'0000' User-type ID JCRUTRID '0000' if CICS journal request. System-type ID Otherwise code specified in JTYPEID keyword of user request...
Page 755 JCRUTRID 2-byte user-type identifier. For a CICS journal request, this is X'0000'. Otherwise, it contains the code specified by the JTYPEID keyword of the user request. JCRLRN 2-byte record number within the block. The field JCRSTRID (the system-type ID) and the field JCRUTRID (the user-type ID) in the system header allow you to distinguish those journal records output by CICS (by such components as terminal control), from those issued by direct user requests.
Page 756 Reserved 2-byte reserved field. JCSPF1 1-byte flag field: X’01’ X’02’ X’04’ JCSPTASK 3-byte task number. JCSPTIME 4-byte time of request. JCSPTRAN 4-byte transaction identifier. JCSPTERM 4-byte terminal identifier. For some CICS journal requests, additional data is included in the system prefix to identify more specifically the originator of the request.
Page 757 JCRLL - (system header (10) bytes + JCSPLL + user prefix) Not all journal records contain journaled data. The CICS components that issue journaling requests are journal control, file control, FEPI, and terminal control. Chapter 27. CICS logging and journaling...
Page 758 *********************************************************************** F U N C T I O N I D E N T I F I E R S *********************************************************************** X’20’ PLUS X’8-’ ...USE FOR AUTOMATIC JOURNALING X’40’ PLUS X’8-’ ...USE FOR AUTOMATIC LOGGING *********************************************************************** JOURNAL CONTROL *********************************************************************** FIDJCLAB EQU X’80’...
Page 759: Identifying Records For The Start Of Tasks And Uows
*********************************************************************** M O D U L E I D E N T I F I E R S *********************************************************************** MODIDTC EQU X’10’ MODIDFC EQU X’11’ MODIDJC EQU X’45’ MODIDFEP EQU X’50’ *********************************************************************** Figure 98. Journal module identifiers Note: 1. Records created by automatic journaling and automatic logging are 2.
Page 760: The Smf Block Header
Log block Log block CICS CICS Block Product Data header section section Record Caller header data Figure 99. Layout of a CICS log written to MVS SMF Journal records written to SMF can be read offline by user-written programs. Such programs can map journal records by including an INCLUDE DFHLGMSD statement.
Page 761 Time record moved SMFH_TME (local) Record type SMFH_RTY Operating system indicator SMFH_FLG Segment descriptor X'0000' SMFH_SEG Record Date record length moved SMFH_LEN SMFH_DTE Figure 100. Format of the SMF block header The format of the SMF block header is: SMFH_LENGTH 2-byte record length.
Page 762: The Cics Product Section
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).
Page 763 Product name (generic APPLID) SMFPS_PRN X'0vrm' SMFPS_VRM v = version set by r = release DFHSYS m = modification Journal name Job name SMFPS_JNM SMFPS_JBN Figure 101. Format of the CICS product section The format of the CICS product section is: SMFPS_VRM 2-byte CICS version, release, and modification information, in the format X'0vrm'.
Page 764: The Cics Data Section
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. Each record comprises a general log record header, the format of which is shown in Figure 75 on page 715.
Page 765: Chapter 28. Cics Monitoring
Chapter 28. CICS monitoring This section describes the monitoring facilities of CICS Transaction Server for z/OS, Version 3 Release 2, and tells you how to: v Control the types of monitoring data collected by CICS. v Gather more performance data about specific transactions than is provided automatically by CICS.
Page 766: Coding Additional Event-Monitoring Points
The numbers 1 through 199 are available for EMPs in user applications, and the numbers 200 through 255 are for use in IBM program products. The numbers can be qualified with an entry name, so that you can use each number more than once.
Page 767 invoked, displays a menu screen from which the user can choose a specific application. It is then possible to run all the elements of the application under the common menu transaction ID. This is very effective from the application users point of view, because they do not have to use a large number transaction IDs to run an application.
Page 768 DFHEISTG DSECT EMPDATA1 DS * Constants for DATA2 (null value) and ENTRYNAME EMPDATA2 DC APPLNAME DC EXEC CICS MONITOR POINT(1) ENTRYNAME(APPLNAME) Figure 102. EXEC CICS MONITOR commands for DFHAPPL EMPs (assembler) This example shows 4 bytes of user data, typically the transaction ID, being moved using the DFHAPPL.1 EMP.
Page 769: The Monitoring Control Table (Mct)
IDENTIFICATION DIVISION. PROGRAM-ID. APPLNAME. ENVIRONMENT DIVISION. DATA DIVISION. WORKING-STORAGE SECTION. 77 APPLICATION-NAME-PTR 77 MENU-APPLICATION-NAME 77 PAYROLL-APPLICATION-NAME 77 DFHAPPL-NAME 77 DFHAPPL-DATA2 77 BLANKS LINKAGE SECTION. 77 LS-APPLICATION-NAME PROCEDURE DIVISION. Figure 103. EXEC CICS MONITOR commands for DFHAPPL EMPs (COBOL) The monitoring control table (MCT) You can use the monitoring control table (MCT): v To tell CICS about the EMPs that are invoked by your application programs and about the data that is to be collected at these points.
Page 770 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.
Page 771 Example 1: Starting a user clock Example 1 shows a user clock being started by an application that is identified as PROG3. This is the eleventh EMP in this application. To prevent confusion with the eleventh EMP in another application, this EMP is uniquely identified by the empid PROG3.11.
Page 772: Cics Monitoring Record Formats
CICS journaling X'0001' CICS monitoring X'0002' CICS statistics X'0003' Shared temporary storage queue server statistics X'0004' Coupling facility data table server statistics X'0005' Named counter sequence number server statistics For more information about SMF journaling records, refer to Chapter 27, “CICS logging and journaling,”...
Page 773 The label ‘MNSMFDS’ is the default DSECT name, and SMF is the default PREFIX value, so you could also generate the DSECT simply by coding: DFHMNSMF The MNSMFDS DSECT has the format shown in Figure 105 on page 752. Chapter 28. CICS monitoring...
Page 774 START OF THE SMF HEADER MNSMFDS DSECT SMFMNLEN DS RECORD LENGTH SMFMNSEG DS SEGMENT DESCRIPTOR SMFMNFLG DS OPERATING SYSTEM INDICATOR (see note 1) SMFMNRTY DC X’6E’ RECORD 110 FOR CICS SMFMNTME DS TIME RECORD MOVED TO SMF SMFMNDTE DS DATE RECORD MOVED TO SMF SMFMNSID DS SYSTEM IDENTIFICATION SMFMNSSI DS...
Page 775 SMF header and the SMF product sections of all six subtypes of SMF 110 records written by CICS journaling, CICS monitoring, CICS statistics, the TS data sharing server, the coupling facility data table (CFDT) server, and the named counter sequence number server.
Page 776: Cics Data Section
CICS data section The CICS data section can be made up of a dictionary data section, a performance data section, an exception data section, or a transaction resource data section. You can identify which of these you are dealing with by looking at the value of field SMFMNCL in the SMF product section.
Page 777 DFHMCTDR TYPE=(PREFIX,CMO) CMO is the default label prefix. CMODNAME DS NAME OF OWNER (entry name) CMODTYPE DS OBJECT TYPE ’S’ = STOPWATCH (CLOCK) ’A’ = ACCUMULATOR (COUNT) ’C’ = BYTE-STRING FIELD ’T’ = TIMESTAMP (STCK FORMAT) ’P’ = PACKED-DECIMAL FIELD CMODIDNT DS ID WITHIN TYPE CLOCK-, COUNT-, OR FIELD-NO.
Page 778 Byte-string Packed decimal number Clock Time stamp Customization Guide...
Page 779 FIELD-NAME SIZE CONNECTOR OFFSET DFHTASK C001 4 X’0001’ X’0000’ DFHTERM C002 4 X’0002’ X’0004’ DFHCICS C089 8 X’0003’ X’0008’ DFHTASK C004 4 X’0004’ X’0010’ DFHCICS T005 8 X’0005’ X’0014’ DFHCICS T006 8 X’0006’ X’001C’ DFHTASK P031 4 X’0007’ X’0024’ DFHTASK A109 4 X’0008’...
Page 780 FIELD-NAME SIZE CONNECTOR OFFSET DFHSTOR A106 4 X’004B’ X’0314’ DFHSTOR A116 4 X’004C’ X’0318’ DFHSTOR A119 4 X’004D’ X’031C’ DFHSTOR A095 8 X’004E’ X’0320’ DFHSTOR A107 8 X’004F’ X’0328’ DFHSTOR A118 8 X’0050’ X’0330’ DFHSTOR A121 8 X’0051’ X’0338’ DFHSTOR A144 4 X’0052’...
Page 781 FIELD-NAME SIZE CONNECTOR OFFSET DFHTASK A346 4 X’0086’ X’0410’ DFHTASK A347 4 X’0087’ X’0414’ DFHSYNC A060 4 X’0088’ X’0418’ DFHCICS A025 4 X’0089’ X’041C’ DFHFEPI A150 4 X’008A’ X’0420’ DFHFEPI A151 4 X’008B’ X’0424’ DFHFEPI A152 4 X’008C’ X’0428’ DFHFEPI A153 4 X’008D’...
Page 782 FIELD-NAME SIZE CONNECTOR OFFSET DFHSOCK A298 4 X’00C2’ X’0500’ DFHSOCK A301 4 X’00C3’ X’0504’ DFHSOCK A302 4 X’00C4’ X’0508’ DFHSOCK A303 4 X’00C5’ X’050C’ DFHSOCK A304 4 X’00C6’ X’0510’ DFHDATA A179 4 X’00C7’ X’0514’ DFHDATA A180 4 X’00C8’ X’0518’ DFHDATA A395 4 X’00C9’...
Page 783 FIELD-NAME SIZE CONNECTOR OFFSET DFHTASK S281 12 X’0100’ X’06C0’ DFHTASK S268 12 X’0101’ X’06CC’ DFHTASK S247 12 X’0102’ X’06D8’ DFHCICS S103 12 X’0103’ X’06E4’ DFHTERM S009 12 X’0104’ X’06F0’ DFHFILE S063 12 X’0105’ X’06FC’ DFHJOUR S010 12 X’0106’ X’0708’ DFHTEMP S011 12 X’0107’...
Page 784 performance records changes if you add user data at user event monitoring points (EMPs), or if you exclude any system-defined data from the monitoring process. All of the system-defined data fields in the performance records are described in Performance class data: listing of data fields , in the CICS Performance Guide. The format of the performance data section is shown in Figure 113.
Page 785 Figure 114 illustrates the relationship between the dictionary record, the field connectors, and the performance records. Dictionary Record Dictionary Dictionary Dictionary Dictionary Entry 1 Entry 2 Entry 3 Field Connectors Performance Data for Record 1 field 1 Performance Data for Record 2 field 1 Performance...
Page 786 record type, and they do not change between CICS runs. There is more information about field identifiers in the CICS Resource Definition Guide. Field offsets in the performance record allow you to build a table for fast selection of required fields in your monitoring data processing programs. Exception data sections The exception data section contains a single exception record representing one exception condition.
Page 787 MNEXCDS DSECT EXCMNTRN DS EXCMNTER DS EXCMNUSR DS EXCMNTST DS EXCMNSTA DS EXCMNSTO DS EXCMNTNO DS EXCMNTPR DS EXCMNLUN DS EXCMNEXN DS EXCMNRTY DS EXCMNRID DS EXCMNTYP DS EXCMNWT EQU X’0001’ EXCMNBWT EQU X’0002’ EXCMNSWT EQU X’0003’ EXCMNTCN DS EXCMNSRV DS EXCMNRPT DS EXCMNNPX DS CL20...
Page 788 FILE=10 in the DFHMCT TYPE=INITIAL macro, the file resource data section can have up to 960 bytes of file resource data. All the system-defined data fields in the transaction resource monitoring records are described in http://winlnx0c.hursley.ibm.com:19000/help/index.jsp?topic=/ com.ibm.cics.ts.performance.doc/topics/dfht3_mon_tranmnr_fields.html#dfht35m , in the CICS Performance Guide.
Page 789 DFHMNRDS DSECT , MNR_LENGTH DS H MNR_ID_EQUATE EQU 79 MNR_ID DC AL2(MNR_ID_EQUATE) Monitoring domain id MNR_VERSION EQU X’02’ MNR_DSECT_VERS DS CL1 DS CL3 MNR_HEADER DS 0XL40 MNR_HDRLEN DS H DS XL2 DS XL8 MNR_TRN DS H DS XL2 MNR_ISO DS XL4 MNR_ISL DS XL2 MNR_ISN...
Page 790 MNR_ID_ACMETH_TCAM MNR_ID_ACMETH_BGAM MNR_ID_ACMETH_CONSOLE MNR_ID_DEVCODE MNR_ID_TERMCNNM DS CL4 MNR_ID_RES_FLAGS DS 0XL4 MNR_ID_RES_FLAG1 DS XL1 MNR_FILE_LIMIT_EXCEEDED EQU X’80’ MNR_TSQUEUE_LIMIT_EXCEEDED EQU X’40’ MNR_ID_ISIPCNNM DS XL8 MNR_ID_LENGTH EQU *-MNR_ID_DATA SPACE , MNR_FILE_ENTRY DSECT MNR_FILE_NAME DS CL8 MNR_FILE_GET MNR_FILE_PUT MNR_FILE_BRWSE DS XL8 MNR_FILE_ADD MNR_FILE_DEL MNR_FILE_TOTAL DS XL8 MNR_FILE_AM_RQ DS XL4 MNR_FILE_IO_WT DS XL8 MNR_RLS_FILE_IO_WT DS XL8...
Page 791: Chapter 29. Writing Statistics Collection And Analysis Programs
The records are of SMF type 110, subtype 0002. Note: Monitoring records, and statistics records produced by the temporary storage shared-queue server, are also written to the SMF data set as type 110 records. (Some journaling type 110 records can be written there, too.) You...
Page 792: Resetting Statistics Counters
Resetting statistics counters Statistics counters are reset in the following circumstances: v At CICS startup v When interval statistics are written (but not when an interval occurs and no statistics are written) v At end of day v When requested reset statistics are written. However, you can cause statistics counters to be reset without writing records to the SMF data set.
Page 793: Cics Statistics Record Format
CICS statistics, is the CICS region, the TS data sharing server, the CFDT server, or the named counter sequence number server. Both the SMF header and...
Page 794 START THE SMF HEADER STSMFDS DSECT SMFSTLEN DS RECORD LENGTH SMFSTSEQ DS SEGMENT DESCRIPTOR SMFSTFLG DS OPERATING SYSTEM INDICATOR (see note 1) SMFSTRTY DC X’6E’ RECORD TYPE 110 FOR CICS SMFSTTME DS TIME RECORD MOVED TO SMF SMFSTDTE DS DATE RECORD MOVED TO SMF SMFSTSID DS SYSTEM IDENTIFICATION SMFSTSSI DS...
Page 795: Cics Statistics Data Section
(DFHXQ) and the pool name. X'0004' and certain fields are not set or are used in a different way. SMFSTPRN and SMFSTSPN contain the server prefix (DFHCF) and the coupling facility data table pool name. X'0005' and certain fields are not set or are used in a different way.
Page 796 Figure 124 on page 775. For further guidance information about the fields within the statistics data records, see CICS statistics in DSECTs and DFHSTUP report, in the CICS Performance Guide. STIVERS takes the value ‘1’ for this release of CICS. Customization Guide...
Page 797 TCP/IP (global) id TCPIP services (resource) id IPCONN (resource) id REQUESTMODEL (resource) id DOCTEMPLATE (resource) id CORBA Server (resource) id Bean stats (resource) id JVMPOOL stats (global) id JVMPROFILE stats (resource) id JVMPROGRAM stats (Resource) id Chapter 29. Writing statistics collection and analysis programs...
Page 798: Using An Xstout Global User Exit Program To Filter Statistics Records
Symbolic Value Copy book name DFHXQS1D DFHXQS2D DFHXQS3D Figure 125. TS data sharing statistics related to STID The coupling facility data table server statistics use no symbolic names, but relate to the STID values as follows: STID STID Symbolic Value Copy book name...
Page 799: Processing The Output From Cics Statistics
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.
Page 800 Customization Guide...
Page 802 (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. Customization Guide...
Page 803: Chapter 30. The Dynamic Allocation Sample Program
Have read the relevant sections of the MVS/ESA SPL: Application Development Guide and have that manual available for reference while using the sample program, in particular for looking up error and reason codes returned by DYNALLOC. © Copyright IBM Corp. 1977, 2011...
Page 804: Installing The Program And Transaction Definitions
The application uses a 3270 display screen terminal, and adjusts its formatting to suit the screen size. BMS is not required. The program is designed so that the installation can easily modify the functions supported to suit installation standards. Installing the program and transaction definitions Transaction and program definitions for the dynamic allocation sample program are provided in the sample utilities group DFH$UTIL on the CSD.
Page 805: The Dynamic Allocation Program-Values
containing “?” is entered, no DYNALLOC SVC is issued. “?” is recognized only in the positions specified above; the rest of the command is ignored. The dynamic allocation program—values Values are classified as follows: Keyword value Keyword values must be specified for some keywords. For example, the STATUS keyword may have a keyword value of SHR, NEW, MOD, or OLD (which can be abbreviated).
Page 806: Abbreviation Rules For 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. A word in the command matches a keyword if: v The spelling is the same.
Page 807 Following successful tokenizing, the main program calls DFH99FP to analyze the verb keyword. DFH99FP calls DFH99LK to look up the verb keyword in the table, DFH99T. DFH99LK calls DFH99MT if an abbreviation is possible. Upon finding the matching verb, DFH99FP puts the address of the operand section of the table into COMM, and puts the function code into the DYNALLOC request block.
Page 808 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. Customization Guide...
Page 810 (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. Customization Guide...
Page 811: Chapter 31. Invoking An External Security Manager
The MVS router exit The MVS router provides an optional installation exit that is invoked whether or not RACF is installed and active on the system. If your installation does not use RACF, © Copyright IBM Corp. 1977, 2011...
Page 812 The exit must be named ICHRTX00 and must be located in the link pack area (LPA). Note: During signon processing, CICS Transaction Server for z/OS, Version 3 Release 2 issues the RACROUTE REQUEST=VERIFY macro with the ENVIR=VERIFY option, in problem-program state. (For an explanation of why CICS does this, see “Using early verification processing”...
Page 813: Using Esm Exit Programs To Access Cics-Related Information
Table 44. MVS router exit return codes Code Other Passing control to a user-supplied ESM Normally, a caller (such as CICS) invokes the MVS router and passes it request type, requester, and subsystem parameters via the RACROUTE exit parameter list. Using these parameters, the MVS router calls the router exit which, on completing its processing, passes a return code to the router.
Page 814: For Non-Racf Users - The Esm Parameter List
For non-RACF users — the ESM parameter list CICS (or another caller) passes information to your external security manager in the ESM parameter list, the address of which can be calculated using field SAFPRACP of the MVS router parameter list. When the caller is CICS, the “INSTLN”...
Page 815: The Installation Data Parameter List
2. RLX2PRPA contains the address of the ICHRLX01 user exit parameter For full descriptions of the RACF exit parameter lists, see the OS/390 Security Server (RACF) Security Administrator's Guide manual. For more information about CICS security processing using RACF, see Introduction to CICS security with RACF, in the CICS RACF Security Guide.
Page 816 DEFAULT_SIGN_ON (X'01') PRESET_SIGN_ON (X'02') IRC_SIGN_ON (X'03') LU61_SIGN_ON (X'04') LU62_SIGN_ON (X'05') XRF_SIGN_ON (X'06') ATTACH_SIGN_ON (X'07') NON_TERMINAL_SIGN_ON (X'08') USER_SIGN_ON (X'10') PRESET_SIGN_OFF (X'22') LINK_SIGN_OFF (X'25') XRF_SIGN_OFF (X'26') ATTACH_SIGN_OFF (X'27') NON_TERMINAL_SIGN_OFF (X'28') USER_SIGN_OFF (X'30') TIMEOUT_SIGN_OFF (X'31') USRDELAY_SIGN_OFF (X'32') DEFERRED_SIGN_OFF (X'33') USER_ATTACH_CHECK (X'40') LINK_ATTACH_CHECK (X'41') EDF_ATTACH_CHECK (X'42') USER_COMMAND_CHECK (X'50') Customization Guide...
Page 817 LINK_COMMAND_CHECK (X'51') Command checking for link EDF_COMMAND_CHECK (X'52') Command checking for EDF USER_RESOURCE_CHECK (X'60') Resource checking for user LINK_RESOURCE_CHECK (X'61') Resource checking for link EDF_RESOURCE_CHECK (X'62') Resource checking for EDF USER_SURROGATE_CHECK (X'68') Surrogate checking for user LINK_SURROGATE_CHECK (X'69') Surrogate checking for link EDF_SURROGATE_CHECK (X'6A') Surrogate checking for EDF USER_QUERY_CHECK (X'70')
Page 818: Cics Security Control Points
UXPLUNAM Address of an area containing the VTAM LU name. The address may be zero if no terminal is associated with the request, or the area may be blank if the terminal is not a VTAM terminal. UXPTCTUA Address of the TCT user area. UXPTCTUL Address of a fullword containing the length of the TCTUA.
Page 819: Using Early Verification Processing
It is also issued (with the parameters SEGMENT=CICS,CLASS=USER) during signon, at all the control points listed under RACROUTE REQUEST=VERIFY. For a detailed description of these macros, see the OS/390 Security Server External Security Interface (RACROUTE) Macro Reference manual. Using early verification processing...
Page 820: Writing An Early Verification Routine
CICS defers the creation of the accessor environment element until the RACROUTE REQUEST=VERIFY macro with the ENVIR=CREATE option is issued to perform the normal verification routine. The ENVIR=CREATE version of the macro is issued by the security manager domain running in supervisor state. CICS passes the following information on the ENVIR=VERIFY version of the RACROUTE REQUEST=VERIFY macro: USERID...
Page 821: Using Cics Api Commands In An Early Verification Routine
Using CICS API commands in an early verification routine An early verification routine can use CICS application programming interface (API) commands, provided it obeys the following interface rules: v The routine must be written in assembler. v Entry to the routine must be via the DFHEIENT macro, which saves the caller’s registers and establishes a CICS early verification API environment.
Page 822 Customization Guide...
Page 823: Chapter 32. Writing A "Good Night" Program
Figure 128 on page 802 shows the communications area passed to the “good night” program. © Copyright IBM Corp. 1977, 2011 able to handle the type of communication area it is passed when terminal timeout occurs. The CICS sign-off transaction, CESF, can do this, but...
Page 824 DFHSNGS DFHSNGS_FIXED GNTRAN_START_TRANSID GNTRAN_PSEUDO_CONV_FLAG GNTRAN_SCREEN_TRUNCATED GNTRAN_TRANSLATE_TIOA GNTRAN_TIMEOUT_TIME GNTRAN_TIMEOUT_REASON GNTRAN_PSEUDO_CONV_TRANSID GNTRAN_SCREEN_LENGTH GNTRAN_CURSOR_POSITION GNTRAN_SCREEN_WIDTH GNTRAN_SCREEN_HEIGHT GNTRAN_USER_FIELD DFHSNGS_VARIABLE GNTRAN_SCREEN_BUFFER Figure 128. Communications area passed to the “good night” program (assembler) 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_START_TRANSID is set to 'CEGN'.
Page 825: The Sample "Good Night" Program, Dfh0Gnit
pseudoconversational sequence. (If the terminal did not time out during a pseudoconversational sequence, the value of this field is meaningless.) GNTRAN_SCREEN_LENGTH The length of the screen buffer. GNTRAN_CURSOR_POSITION The cursor position. GNTRAN_SCREEN_WIDTH The width of the screen in use when the terminal timed out. GNTRAN_SCREEN_HEIGHT The height of the screen in use when the terminal timed out.
Page 826: Customizing The Sample "Good Night" Program
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.
Page 827 LOGOFF The terminal is both signed off and logged off. v Specify the identifier (TRANSID) of your “good night” transaction on the GNTRAN system initialization parameter. If you have customized the sample program, DFH0GNIT, specify the supplied sample transaction definition, GNIT. If you have written your own “good night”...
Page 828 Customization Guide...
Page 830 (except for those which provide return codes or linkage information). For information about translation modes, refer to the IBM ESA/370 Principles of Operation manual. Customization Guide...
Page 831: Chapter 33. Using The Programmable Interface To Ceda
Note: 1. An attempt to start CEDA from an application program by an EXEC CICS © Copyright IBM Corp. 1977, 2011 COMMAREA(CEDAPARM) Display output at terminal instead of returning it to caller. Do not display output at terminal.
Page 832: When To Use The Programmable Interface
2. The RDO command passed in address 1 of the CEDAPARM parameter 3. You cannot use the programmable interface to change the values of 4. CEDA issues various syncpoints as part of its processing. Therefore, When to use the programmable interface Remember that you can use the offline utility program, DFHCSDUP, to examine and amend CSD files;...
Page 833 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.
Page 834 Customization Guide...
Page 835: Chapter 34. User Programs For The System Definition Utility Program (Dfhcsdup)
Process an APAR—that is, apply maintenance for a specific APAR to the CSD v Remove a single group from a list on the CSD file v Scan all IBM-supplied and user-defined groups for a resource v Service a CSD file when necessary...
Page 836: Invoking A User Program From Dfhcsdup
The user progrm must be linked RMODE(24). It receives control in 24-bit primary-space translation mode. (For information about translation modes, see the IBM ESA/370 Principles of Operation manual.) The contents of the access registers are unpredictable. The program must return control in 24-bit primary-space translation mode, and it must restore any access registers that it modifies (in addition to restoring the general purpose registers).
Page 837: When The User Program Is Invoked
2. If you specify the OBJECTS option, all the attributes of the resource definitions are also extracted. USERPROGRAM is the name of the user-written program that is to process the data retrieved by the EXTRACT command. You must supply a USERPROGRAM value. When the user program is invoked The user program can be invoked at nine different points during the processing of the EXTRACT command by DFHCSDUP.
Page 838: The Sample Extract Programs
Workarea Ptr This is the address of a field containing the address of a fullword to be used by the user application to store the address of any user-acquired work area. Back translated command Ptr The address of a fullword that contains the address of a 75-byte area of storage that contains the EXTRACT command that is being processed.
Page 839 If the compatibility option is specified, the output includes obsolete keywords from releases before CICS Transaction Server for z/OS, Version 3 Release 2; if the option is not specified, only keywords from CICS Transaction Server for z/OS, Version 3 Release 2 are output.
Page 840 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.
Page 841: Assembling And Link-Editing Extract Programs
v For distribution, in part or as a whole, to other CICS installations v To recreate or add resource definitions to any CSD using DFHCSDUP. The program must be run against an EXTRACT command of the form: EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name) EXTRACT LIST(list name) OBJECTS USERPROGRAM(program-name) Note that the sample program requires you to specify the OBJECTS keyword.
Page 842 An assembler-language version The sample job in Figure 129 shows the link-edit statements you need for an assembler-language version of a DFHCSDUP user program. //DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid //* . //* Assembler job step here //* . //LINK EXEC PGM=IEWL,PARM=’XREF,LIST,LET’ //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLIB...
Page 843: Invoking Dfhcsdup From A User Program
//DFHCRFA JOB (accounting information),CLASS=A,MSGCLASS=A,NOTIFY=userid //* . //* Compile job step here //* . //LINK EXEC PGM=IEWL,PARM=’XREF,LIST,LET’ //SYSLIB DD DSN=PP.ADLE370.OS39025.SCEELKED //CICSLIB DD DSN=CICSTS32.CICS.CICS.SDFHLOAD,DISP=SHR //OBJLIB DD DSN=object.module.library,DISP=SHR //SYSLMOD DD DSN=user.library,DISP=SHR //SYSUT1 DD UNIT=SYSDA,SPACE=(1024,(100,10)) //SYSPRINT DD SYSOUT=A //SYSLIN DD * ENTRY DFHEXTRA CHANGE EXITEP(prof-id) INCLUDE CICSLIB(DFHEXLE)
Page 844: Entry Parameters For Dfhcsdup
2. Suitably authorized TSO operators can use the CEDA INSTALL Entry parameters for DFHCSDUP When invoking DFHCSDUP, your program passes a parameter list addressed by register 1. It may pass up to five parameters, as described below: OPTIONS A list of character strings, separated by commas. (The information passed here is that which would otherwise be passed on the PARM keyword of the EXEC statement of JCL.) A maximum of four options can be specified: CSD({READWRITE|READONLY})
Page 845 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. General options Register 1...
Page 846: Responsibilities Of The User Program
first three subentries of the DDNAMES parameter. The fourth, fifth, and sixth subentries, if present, replace the ddnames of DFHCSD, SYSIN, and SYSPRINT, respectively. v In the DCBS functional data, each subentry consists of two fullwords. The first word is not used by CICS. The second word contains the address of an open DCB or ACB.
Page 847: The Initialization Exit
DFHUEXIT DSECT UEPEXN UEPGAA UEPGAL UEPCRCA DS UEPTCA UEPCSA UEPHMSA DS UEPSTACK DS UEPXSTOR DS UEPTRACE DS UEPCMDA DS UEPCMDL DS Explanations of the exit-specific parameters are included in the descriptions of the individual exits, which follow. The initialization exit The initialization exit is invoked once during DFHCSDUP initialization.
Page 848: The Extract Exit
UEPCMDA UEPCMDL Return codes UERCNORM (X'00') UERCDONE (X'04') UERCERR XPI calls Must not be used. The extract exit The extract exit is invoked at various points during processing of the EXTRACT command. The points are listed in “When the user program is invoked” on page 815.
Page 849: The Put-Message Exit
EXTRACT_CSD_OBJECT_TYPE_PTR EXTRACT_CSD_OBJECT_NAME_PTR EXTRACT_KEYWORD_NAME_PTR EXTRACT_KEYWORD_LENGTH_PTR EXTRACT_KEYWORD_VALUE_PTR Note that these parameters are similar to those passed when DFHCSDUP is invoked as a batch program. (See “Parameters passed from DFHCSDUP to the user program” on page 815.) However, when DFHCSDUP is invoked from a user program, the parameter list also includes the standard parameters mentioned under “Parameters passed to the user exit routines”...
Page 850: The Termination Exit
UEPMDOM UEPINSN UEPINSA INS_1_TEXT_PTR DS A INS_1_LEN_PTR INS_2_TEXT_PTR DS A INS_2_LEN_PTR INS_n_TEXT_PTR DS A INS_n_LEN_PTR The exit-specific parameters provide a message number and insert fields only, to enable you to provide messages in the language of your TSO operators. The structure pointed to by UEPINSA is repeated as many times as UEPINSN requires.
Page 851: The Sample Program, Dfh$Cus1
UERCNORM (X'00') UERCERR XPI calls Must not be used. The sample program, DFH$CUS1 The CICS-supplied sample program, DFH$CUS1, illustrates how DFHCSDUP can be invoked from a user program. It is written as a command processor (CP) for execution under the TSO/E operating system. Note that DFH$CUS1 uses different DCB and ACB names from those normally used by DFHCSDUP.
Page 852 Customization Guide...
Page 854 Customization Guide...
Page 855: Appendix A. Coding Entries In The Vtam Logon Mode Table
When you find the right one, use the number to its right to locate, in Table 50 on page 836, what has to be coded on the VTAM MODEENT macros. © Copyright IBM Corp. 1977, 2011...
Page 856 Note that Table 49 is a complete list of TYPETERM device types; not all of these can be used with autoinstall. Those that cannot are marked with an asterisk (*). For details about coding TYPETERM definitions, and for a list of terminals that can be autoinstalled, see the CICS Resource Definition Guide.
Page 857: Vtam Modeent Macro Operands
Table 49. TYPETERM device types, with cross-references to VTAM logmode entries (continued) TYPETERM device type DEVICE(3650) SESSIONTYPE(PIPELN) * DEVICE(3650) SESSIONTYPE(USERPROG) BRACKET(YES) DEVICE(3650) SESSIONTYPE(USERPROG) BRACKET(NO) DEVICE(3650) SESSIONTYPE(3270) DEVICE(3650) SESSIONTYPE(3270) BRACKET(NO) DEVICE(3650) SESSIONTYPE(3653) DEVICE(3650) SESSIONTYPE(3653) BRACKET(NO) DEVICE(3767) DEVICE(3767C) DEVICE(3767I) DEVICE(3770) DEVICE(3770) SESSIONTYPE(BATCHDI) DEVICE(3770) SESSIONTYPE(USERPROG) DEVICE(3770B) DEVICE(3770B) SESSIONTYPE(BATCHDI)
Page 858 table, such as PSERVIC for some reference numbers, are not tested by CICS. Any bit settings that do not matter to CICS during bind analysis for autoinstalled terminals appear as periods (.). Note: Some fields in the PSERVIC data for LUTYPE0, LUTYPE2, and LUTYPE3 devices have values that depend on the ALTSCREEN and DEFSCREEN characteristics of the device.
Page 859 Table 50. LOGON mode table and ISTINCLM entries (continued) VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions FMPROF=X’04’ TSPROF=X’04’ PRIPROT=X’B0’ SECPROT=X’30’ COMPROT=B’0100.000 00000.00’ FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=X’90’ COMPROT=B’0011.000 01000.00’ PSERVIC=B’00000001 00000000 00000000 0000000..00000000 00000000 00000000 00000000 ...
Page 860 Table 50. LOGON mode table and ISTINCLM entries (continued) VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions FMPROF=X’03’ TSPROF=X’04’ PRIPROT=X’B1’ SECPROT=X’B0’ COMPROT=B’0111.000 10000.00’ PSERVIC=B’00000001 00110001 00011000 0100000. FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=X’B0’ COMPROT=B’0111.000 10000.00’ PSERVIC=B’00000001 00110001 00001100 0111000. FMPROF=X’04’...
Page 861 Table 50. LOGON mode table and ISTINCLM entries (continued) VTAM MODEENT macro entries that are needed for related CICS TYPETERM definitions FMPROF=X’03’ TSPROF=X’03’ PRIPROT=X’B1’ SECPROT=B’10..0000’ COMPROT=B’0011.000 10000.00’ PSERVIC=B’00000011 10000000 00000000 00000000 00000000 00000000 aaaaaaaa bbbbbbbb cccccccc dddddddd eeeeeeee’ FMPROF=X’04’ TSPROF=X’03’ PRIPROT=X’31’...
Page 862: Pservic Screen Size Values For Lutypex Devices
PSERVIC screen size values for LUTYPEx devices Table 51 is to help you decide what screen size values you should specify on the PSERVIC operand of the VTAM MODEENT macro, for LUTYPE0, LUTYPE2, and LUTYPE3 devices. If, on your CICS TYPETERM definition, you code the values shown in columns 1 through 4 of Table 51, the screen size values in the CICS model bind image are as shown in column 5.
Page 863: Matching Models And Logon Mode Entries
Table 52. Equivalent PSERVIC screen size values (continued) Bytes 20—24 of CICS model bind xxxx 0000 7E xxxx indicates 2 bytes containing the default screen size, in hexadecimal yyyy indicates 2 bytes containing the alternate screen size, in hexadecimal Matching models and LOGON mode entries This section contains a set of VTAM LOGON mode table definitions, and their matching CICS autoinstall definitions.
Page 864 AUTOCONNECT LOGONMSG BIND SENT BY CICS depends on PSERVIC value on LOGMODE definition above: EITHER Real Model 2 ****************************************************************** 2) LOCAL SNA 3277/78/79 (without special features) LUTYPE2 ****************************************************************** S32782 MODEENT LOGMODE=S32782, TERMINAL definition ************************* AUTINSTNAME AUTINSTMODEL ==> ONLY GROUP TYPETERM INSERVICE TYPETERM definition *************************...
Page 865 TERMINAL definition ************************* AUTINSTNAME ==> M3770 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3770 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3770 GROUP ==> PDATD DEVICE ==> 3770 SESSIONTYPE ==> BATCHDI PAGESIZE ==> 12,80 DISCREQ ==> YES AUTOPAGE ==>...
Page 866 PAGESIZE AUTOPAGE LOGONMSG LDCLIST Needs LDC declaration in TCT : LDCS DFHTCT TYPE=LDC,LDC=SYSTEM LDC1 DFHTCT TYPE=LDC,LOCAL=INITIAL DFHTCT TYPE=LDC,DVC=(BLUCON,01),PROFILE=DEFAULT,LDC=PC, DFHTCT TYPE=LDC,DVC=(BLUPRT,02),PROFILE=BASE,LDC=PP, DFHTCT TYPE=LDC,DVC=(BLUPRT,08),PROFILE=BASE,LDC=P8, DFHTCT TYPE=LDC,DVC=(BLUPRT,08),PROFILE=DEFAULT,LDC=DP, DFHTCT TYPE=LDC,DVC=(BLUPCH,03),PROFILE=JOB,LDC=PM, DFHTCT TYPE=LDC,DVC=(BLUPCH,03),PROFILE=DEFAULT,LDC=DM, DFHTCT TYPE=LDC,DVC=(WPMED1,04),PROFILE=WPRAW,LDC=P1, DFHTCT TYPE=LDC,DVC=(WPMED1,04),PROFILE=DEFAULT,LDC=D1, DFHTCT TYPE=LDC,DVC=(WPMED2,05),PROFILE=OII1,LDC=P2, DFHTCT TYPE=LDC,DVC=(WPMED2,05),PROFILE=DEFAULT,LDC=D2, DFHTCT TYPE=LDC,DVC=(WPMED3,06),PROFILE=OII2,LDC=P3, DFHTCT TYPE=LDC,DVC=(WPMED4,07),PROFILE=OII3,LDC=P4, DFHTCT TYPE=LDC,LOCAL=FINAL BIND SENT BY CICS : ******************************************************************...
Page 867 BRACKET ==> YES IOAREALEN ==> 256 ==> YES ==> YES BIND SENT BY CICS : 010404B1 B0708000 00858580 00000000 ****************************************************************** 6) 3790 BATCH DATA INTERCHANGE ****************************************************************** S3790B MODEENT LOGMODE=S3790B, TYPE=1, FMPROF=X’03’, TSPROF=X’04’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’7080’, RUSIZES=X’8585’, PSERVIC=X’013118400000920000E10050’ TERMINAL definition ************************* AUTINSTNAME ==>...
Page 868 AUTINSTMODEL ==> ONLY GROUP TYPETERM INSERVICE TYPETERM definition ************************* TYPETERM GROUP DEVICE SESSIONTYPE BRACKET SENDSIZE RECEIVESIZE BIND SENT BY CICS : ****************************************************************** 8) 3767 INTERACTIVE (FLIP-FLOP) LU ****************************************************************** S3767 MODEENT LOGMODE=S3767, TERMINAL definition ************************* AUTINSTNAME AUTINSTMODEL ==> ONLY GROUP TERMPRIORITY ==> 60 TYPETERM INSERVICE TYPETERM definition...
Page 869 TERMINAL definition ************************* AUTINSTNAME ==> M3650A AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> T3650A INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> T3650A GROUP ==> PDATD DEVICE ==> 3650 SESSIONTYPE ==> USERPROG ROUTEDMSGS ==> SPECIFIC FMHPARM ==> YES RELREQ ==>...
Page 870 TERMINAL definition ************************* AUTINSTNAME AUTINSTMODEL ==> ONLY GROUP TYPETERM INSERVICE TYPETERM definition ************************* TYPETERM GROUP DEVICE SESSIONTYPE RELREQ DISCREQ BRACKET IOAREALEN RECEIVESIZE ROUTEDMSGS BIND SENT BY CICS : ****************************************************************** 12) 3650 HOST COMMAND PROCESSOR LU (SESTYPE = USERPROG BRACKET = NO) ****************************************************************** S3650C MODEENT LOGMODE=S3650C,...
Page 871 TSPROF=X’07’, PRIPROT=X’B0’, SECPROT=X’B0’, COMPROT=X’50B1’, PSNDPAC=X’00’, SRCVPAC=X’00’, SSNDPAC=X’00’, RUSIZES=X’8585’, PSERVIC=X’060200000000000000002C00’ TERMINAL definition ************************* AUTINSTNAME ==> MLU62 AUTINSTMODEL ==> ONLY GROUP ==> PDATD TYPETERM ==> SINLU62 INSERVICE ==> YES TYPETERM definition ************************* TYPETERM ==> SINLU62 GROUP ==> PDATD DEVICE ==> APPC RECEIVESIZE ==> 2048 SENDSIZE ==>...
Page 872: Logon Mode Definitions For Cics-Supplied Autoinstall Models
USERAREALEN LOGONMSG ERRHILIGHT RECEIVESIZE BIND SENT BY CICS : ****************************************************************** 15) 3601 WITH A 3604 ATTACHED ****************************************************************** S3600 MODEENT LOGMODE=S3600, TERMINAL definition ************************* AUTINSTNAME AUTINSTMODEL ==> ONLY GROUP TERMPRIORITY ==> 50 TYPETERM INSERVICE TYPETERM definition ************************* TYPETERM GROUP DEVICE AUTOPAGE PAGESIZE RELREQ DISCREQ...
Page 873 DFHLU3 MODEENT LOGMODE=DFHLU3, TYPE=1, FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’3080’, RUSIZES=X’8585’, PSERVIC=X’038000000000000000000200’ DFHSCSP MODEENT LOGMODE=DFHSCSP, LU TYPE 1 SCS PRINTER TYPE=1, FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’B0’, COMPROT=X’7080’, RUSIZES=X’8585’, PSERVIC=X’010000010000000000000000’ DFHLU62T MODEENT LOGMODE=DFHLU62T, APPC SINGLE-SESSION TYPE=0, FMPROF=X’13’, TSPROF=X’07’, PRIPROT=X’B0’, SECPROT=X’B0’, COMPROT=X’50B1’, RUSIZES=X’8888’, PSERVIC=X’060200000000000000002C00’ DFH3270 MODEENT LOGMODE=DFH3270, 3270 TYPE=1, FMPROF=X’02’,...
Page 874 DFHLU0M2 MODEENT LOGMODE=D4B32782, LU0 model 2 nonqueryable DFHLU0M3 MODEENT LOGMODE=D4B32783, LU0 model 3 nonqueryable DFHLU0M4 MODEENT LOGMODE=D4B32784, LU0 model 4 nonqueryable DFHLU0M5 MODEENT LOGMODE=D4B32785, LU0 model 5 nonqueryable DFHLU2E2 MODEENT LOGMODE=SNX32702, LU2 model 2 queryable DFHLU2E3 MODEENT LOGMODE=SNX32703, LU2 model 3 queryable DFHLU2E4 MODEENT LOGMODE=SNX32704, LU2 model 4 queryable DFHLU2M2 MODEENT LOGMODE=D4A32782, LU2 model 2 nonqueryable Customization Guide...
Page 875 DFHLU2M3 MODEENT LOGMODE=D4A32783, LU2 model 3 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, RUSIZES=X’87C7’, PSERVIC=X’020000000000185020507F00’ DFHLU2M4 MODEENT LOGMODE=D4A32784, LU2 model 4 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, RUSIZES=X’87C7’, PSERVIC=X’02000000000018502B507F00’ DFHLU2M5 MODEENT LOGMODE=D4A32785, LU2 model 5 nonqueryable FMPROF=X’03’, TSPROF=X’03’, PRIPROT=X’B1’, SECPROT=X’90’, COMPROT=X’3080’, RUSIZES=X’87C7’, PSERVIC=X’02000000000018501B847F00’...
Page 876 Customization Guide...
Page 877: Appendix B. Default Actions Of The Node Abnormal Condition Program
Table 53. Messages issued and flags set by DFHZNAC for specific error codes Error code X'10' X'11' X'13' X'14' X'15' X'16' X'18' X'19' X'1A' X'1D' X'1E' © Copyright IBM Corp. 1977, 2011 Symbolic label Message TCZSRCTU DFHZC2405 TCZSRCBF DFHZC2403 TCZSRCVH DFHZC2416 TCZLRCER DFHZC2404 TCZSRCPF DFHZC2407...
Page 878 Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code X'20' X'21' X'22' X'23' X'24' X'25' X'26' X'28' X'29' X'2A' X'2B' X'2C' X'2D' X'2E' X'2F' X'30' X'31' X'32' X'33' X'34' X'35' X'36' X'37' X'38' X'39' X'3A' X'3B'...
Page 879 Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message X'49' TCZCLSIN DFHZC3462 X'4A' TCZOPACB DFHZC3463 X'4B' TCZICPUT DFHZC2498 X'4C' TCZDSPCL DFHZC3481 X'4D' TCZSLSRL DFHZC3473 X'4E' TCZUNBFE DFHZC3479 X'4F' TCZCNOS0 None X'50' TCZSDRE3 DFHZC3417...
Page 880 Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code X'75' X'76' X'77' X'78' X'79' X'7A' X'7C' X'7D' X'80' X'81' X'82' X'83' X'84' X'85' X'88' X'89' X'8A' X'8B' X'8C' X'8D' X'8E' X'8F' X'90' X'91' X'92' X'93' X'94'...
Page 881 Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code Symbolic label Message X'A7' TCZBOEB DFHZC2449 X'A8' TCZFMHLE DFHZC2471 X'A9' TCZRACRF DFHZC2472 X'AA' TCZSDSE9 DFHZC2473 X'AB' TCZLUERR DFHZC3470 X'AC' TCZVRDAC DFHZC3474 X'AD' TCZNRLUF DFHZC3475 X'AE' TCZRCLUF DFHZC3476...
Page 882 Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code X'D3' X'D4' X'D5' X'D6' X'D7' X'D8' X'D9' X'DA' X'DB' X'DC' X'DD' X'DE' X'DF' X'E0' X'E1' X'E2' X'E3' X'E4' X'E6' X'E8' X'E9' X'EA' X'EB' X'EC' X'ED' X'EF' X'F1'...
Page 883: Cics Messages Associated With Vtam Errors
Table 53. Messages issued and flags set by DFHZNAC for specific error codes (continued) Error code X'FF' Note: 1. See message DFHZC2497 or DFHZC3493, depending on the device 2. “Good morning” message to be sent. 3. Cancel task, and close VTAM session owing to quick close or abend. CICS messages associated with VTAM errors Table 54.
Page 884 Table 54. CICS messages associated with VTAM errors (continued) Message DFHZC2410 DFHZC2411 DFHZC2412 DFHZC2413 DFHZC2414 DFHZC2416 DFHZC2417 DFHZC2417 DFHZC2418 DFHZC2419 DFHZC2420 DFHZC2421 DFHZC2422 DFHZC2423 DFHZC2424 DFHZC2425 DFHZC2426 DFHZC2427 DFHZC2428 DFHZC2429 DFHZC2430 DFHZC2431 DFHZC2432 DFHZC2433 DFHZC2434 DFHZC2435 DFHZC2436 DFHZC2437 DFHZC2438 DFHZC2439 DFHZC2440 DFHZC2441 DFHZC2442...
Page 885 Table 54. CICS messages associated with VTAM errors (continued) Message Symbolic label DFHZC2450 TCZSSXAR DFHZC2451 TCZSRCCI DFHZC2452 TCZCXE2 DFHZC2453 TCZCXRR DFHZC2454 TCZSRCCX DFHZC2455 TCZRACET DFHZC2456 TCZSRCDE DFHZC2457 TCZRNCH DFHZC2458 TCZPXE2 DFHZC2459 TCZSDSE7 DFHZC2463 TCZDMPD DFHZC2467 TCZLEXCI DFHZC2468 TCZLEXUS DFHZC2469 TCZYX43 DFHZC2469 TCZEXRVT DFHZC2470...
Page 886 Table 54. CICS messages associated with VTAM errors (continued) Message DFHZC3429 DFHZC3430 DFHZC3431 DFHZC3432 DFHZC3433 DFHZC3434 DFHZC3440 DFHZC3441 DFHZC3442 DFHZC3443 DFHZC3444 DFHZC3452 DFHZC3454 DFHZC3455 DFHZC3461 DFHZC3462 DFHZC3463 DFHZC3464 DFHZC3465 DFHZC3466 DFHZC3468 DFHZC3469 DFHZC3470 DFHZC3470 DFHZC3471 DFHZC3472 DFHZC3473 DFHZC3474 DFHZC3475 DFHZC3476 DFHZC3477 DFHZC3479 DFHZC3480...
Page 887 Table 54. CICS messages associated with VTAM errors (continued) Message Symbolic label DFHZC3489 TCZLUINH DFHZC3490 TCZCPFAL DFHZC3491 TCZEXRO DFHZC3492 TCZDMIT DFHZC3495 TCZNOTNA DFHZC3499 TCZDWEGF DFHZC4902 TCZLUCF1 DFHZC4903 TCZLUCF2 DFHZC4904 TCZFSMBE DFHZC4905 TCZFSMCS DFHZC4906 TCZFSMCR DFHZC4907 TCZSDLER DFHZC4909 TCZRVLER DFHZC4910 TCZRVLRB DFHZC4911 TCZRLPEX DFHZC4912...
Page 888: Dfhznac-Default Actions For System Sense Codes
Table 54. CICS messages associated with VTAM errors (continued) Message DFHZC4939 DFHZC4940 DFHZC4941 DFHZC4942 DFHZC4943 DFHZC4944 DFHZC4945 DFHZC4946 DFHZC4947 DFHZC4949 DFHZC6590 DFHZC6591 DFHZC6593 DFHZC6594 DFHZC6595 DFHZC6596 DFHZC6598 DFHZNAC—default actions for system sense codes Table 55 shows the message issued and action flags set by DFHZNAC for each inbound system sense code received.
Page 889 Table 55. Messages issued and flags set by DFHZNAC for specific sense codes (continued) Sense code Message X'0811' DFHZC2464 X'0812' DFHZC2465 X'081B' DFHZC2483 X'081C' DFHZC2466 X'0824' DFHZC2475 X'0825' DFHZC2484 X'0826' DFHZC3423 X'0827' DFHZC2480 X'0829' DFHZC3407 X'082A' None X'082B' DFHZC3408 X'082D' DFHZC3413 X'082E' DFHZC3412...
Page 890: Action Flag Settings And Meanings
Table 55. Messages issued and flags set by DFHZNAC for specific sense codes (continued) Sense code X'40FF' X'8000' X'8005' X'80FF' X'FFFF' Note: 1. The system sense code is in the form of an LUSTATUS command code. 2. No action flags are set if a task is attached or if outstanding operations 3.
Page 891 Table 56. Meanings of action flags set by DFHZNAC (continued) Flag Field Bit mask ..1..1 ..1..1..1. TWAOPT3 1..1..1 ..1..1..1..1 Appendix B. Default actions of the node abnormal condition program Hex bit Action setting...
Page 892 Customization Guide...
Page 893: Appendix C. Analyzing Cics Restart Information
You can use the DFHRMRED Assembler DSECT in a batch program to map the global catalog record. DFHRMRED is found in the CICSTS32.CICS.SDFHMAC library. For more information about the DFHRMUTL utility, see the CICS Operations and Utilities Guide. © Copyright IBM Corp. 1977, 2011...
Page 894 Customization Guide...
Page 895: Appendix D. Using The Transient Data Write-To-Terminal Program (Dfh$Tdwt)
DFH$UTIL. Add DFH$UTIL to your CICS startup group list. However, you must define the other resources. Add a terminal definition for the L86P terminal to the CSD, and install it in your CICS region. © Copyright IBM Corp. 1977, 2011...
Page 896 Customization Guide...
Page 897: Appendix E. Uppercase Translation
4. Use the CICS-supplied DFHAUPLE job to assemble, define to SMP/E, and linkedit the new table. 5. Specify the 2–character suffix of your new TCT on the SIT TCT parameter. 6. Restart CICS, so that the new TCT takes effect. © Copyright IBM Corp. 1977, 2011...
Page 898: Translating Ts Data Sharing Messages To Uppercase
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.
Page 899: Appendix F. The Example Program For The Xtsereq Global User Exit, Dfh$Xtse
4-byte token in the DFHUEPAR parameter list. b) Shared global work area storage. c) Storage obtained by using the LOAD HOLD option. d) TCTUA or CWA storage. Figure 134. Example exit program for the XTSEREQ exit (part 1) © Copyright IBM Corp. 1977, 2011...
Page 900 It is not safe to use the following storage: Program storage (DFHEISTG) since this is freed as soon as the exit program returns control to CICS. 2) When adding or removing a field in the command parameter list, * you must remember: a) To set/clear the field’s existence bit in the EID b) To set/clear the appropriate address in the Addr_List c) To set the hi-order bit in the LAST address in the...
Page 901 *---------------------------------------------------------------------* * The TS Routing table is made up of a set of entries. Each entry * can be mapped by the TABLE_ENTRY DSECT *---------------------------------------------------------------------* TABLE_ENTRY DSECT ENTRY_NAME DS CL8 NEW_NAME DS CL8 NEW_SYSID DS CL4 ENTRY_ACTION DS XL1 FILLER DS CL3 *---------------------------------------------------------------------* * The following definitions are for program working storage.
Page 902 * Registers: R1 = UEPAR plist (set on entry) = Work register R2 = UEPAR plist R3 = Program base register (set by DFHEIENT) R6 = Linkage register R11= EIB register R13= EISTG register (set by DFHEIENT) R15= Work register User Exit Return Code * Logic: DFH$XTSE:...
Page 903 *=====================================================================* * TS_REQUEST - Invoked at XTSEREQ exit point Determine the TS Queue Name and scan the TS_Routing_Table for a match. If an entry exists in the table, then check the action * field and call the ROUTE_REQUEST or LOCAL_REQUEST routines. The TS_Routing_Table is made up of entries with the following structure: TABLE_ENTRY:...
Page 904 *=====================================================================* TS_REQUEST DS 0H Check for possible recursion R1,UEPRECUR R1,0(R1) R1,R1 ERROR2 Extract pointer to the EID and TS queue name from CLPS R8,UEPCLPS USING TS_ADDR_LIST,R8 R1,TS_ADDR0 R7,TS_ADDR1 DROP R8 Check that the Command GROUP code corresponds to a TS request USING TS_EID,R1 TS_GROUP,TS_TEMPSTOR_GROUP Is this a TS request? ERROR3...
Page 905 *=====================================================================* * TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point Free any shared storage that was acquired during previous invocation at XTSEREQ. * Registers: R1 = Work register R6 = Linkage register R8 = Command Parameter List (CLPS) * Logic: TS_Request_Complete: If called recursively then call Error(Recursive_Call2) Else...
Page 906 *=====================================================================* * LOCAL_REQUEST: Process Local TS Queues An entry has been found in the TS_Routing Table for this TS Queue Name. If required, rename the TS Queue Name, but do not modify the SYSID. * Registers: R1 = Work register R6 = Link Register R7 = Address of current Queue name R8 = Command Parameter List (CLPS)
Page 907 *=====================================================================* * ROUTE_REQUEST: Ship request to remote system An entry has been found in the TS_Routing Table for this TS Queue Name. The request is modified by adding a SYSID to the command and renaming the queue if required. * Registers: R1 = Work register R6 = Link Register R7 = Address of current Queue name...
Page 908 Update the Sysid in CLPS ROUTE1 SHARED_SYSID,NEW_SYSID Copy SYSID into shared storage R8,UEPCLPS USING TS_ADDR_LIST,R8 R1,TS_ADDR0 USING TS_EID,R1 TS_BITS1,TS_SYSID_V Indicate SYSID now present in CLPS DROP R1 R1,SHARED_SYSID R1,TS_ADDR7 TS_ADDR7,X’80’ Clear hi-order bits in ARGs 1 to 5 TS_ADDR1,X’7F’ TS_ADDR2,X’7F’ TS_ADDR3,X’7F’...
Page 909 * Logic: Entry_Not_Found: Call Getmain_Shared Copy default_sysid into shared storage Address the command plist Update ADDR7 to point to the address of the default SYSID Set the SYSID existence bit in the EID Set the Hi-order bit in last address in CLPS Return *=====================================================================* ENTRY_NOT_FOUND DS 0H...
Page 910 *=====================================================================* * GETMAIN_SHARED - Obtain Shared storage * Registers: R0 = Used by EXEC CICS call R1 = Used by EXEC CICS call Work Register R6 = Link Register - Return Address R11= EIB register (set on entry) R12= Work register R14= Used by EXEC CICS call R15= Used by EXEC CICS call * Logic:...
Page 911 *=====================================================================* * FREEMAIN_SHARED - Free shared storage Free the shared storage associated with this command. * Registers: R0 = Used by EXEC CICS call R1 = Used by EXEC CICS call R6 = Link Register - Return Address R11= EIB register (set on entry) R12= Work register R14= Used by EXEC CICS call...
Page 912 USING DFHTRPT_ARG,R1 TRACE_ENTRY DS 0H R1,UEPXSTOR DFHTRPTX CLEAR, POINT_ID(TR_ENTRY) ISSUE_TRACE TRACE_EXIT DS 0H R1,UEPXSTOR DFHTRPTX CLEAR, POINT_ID(TR_EXIT) ISSUE_TRACE TRACE_ERROR DS 0H R1,UEPXSTOR DFHTRPTX CLEAR, POINT_ID(TR_ERROR), DATA1(TR_ERROR_N,1) R6,ISSUE_TRACE RETURN *---------------------------------------------------------------------* * Issue the Trace XPI call *---------------------------------------------------------------------* ISSUE_TRACE DS 0H R8,UEPTRACE 0(R8),UEPTRON NO_TRACE R12,R13...
Page 913 ERROR4 TR_ERROR_N,4 TRACE_ERROR ERROR5 TR_ERROR_N,5 TRACE_ERROR ERROR6 TR_ERROR_N,6 TRACE_ERROR ERROR7 TR_ERROR_N,7 TRACE_ERROR ERROR8 TR_ERROR_N,7 TRACE_ERROR ERROR9 TR_ERROR_N,7 TRACE_ERROR EJECT , DROP R2 DROP R11 LTORG , *********************************************************************** * CONSTANTS *********************************************************************** DS 0D EYE_CATCHER DC CL16’XTSEREQ Storage ’ DEFAULT_SYSID DC CL4’MQ1 ’ LOCAL EQU X’01’...
Page 914 TS_ROUTING_TABLE DS 0D ENTRY_NAME_1 DC CL8’AAAAAAAA’ NEW_NAME_1 DC CL8’BBBBBBBB’ QOR_SYSID_1 DC CL4’ ’ ACTION_1 DC XL1’01’ FILLER_1 DC CL3’ ’ ENTRY_NAME_2 DC CL8’A1 ’ NEW_NAME_2 DC CL8’B1 ’ QOR_SYSID_2 DC CL4’ ’ ACTION_2 DC XL1’01’ FILLER_2 DC CL3’ ’ ENTRY_NAME_3 DC CL8’A2 ’...
Page 915: Appendix G. Threadsafe Xpi Commands
DFHSMSRX INQUIRE_ACCESS v DFHSMSRX INQUIRE_SHORT_ON_STORAGE v DFHSMSRX SWITCH_SUBSPACE v DFHTRPTX TRACE_PUT v DFHBRIQX INQUIRE_CONTEXT v DFHXMSRX INQUIRE_DTRTRAN v DFHXMSRX INQUIRE_MXT v DFHXMCLX INQUIRE_TCLASS v DFHXMXDX INQUIRE_TRANDEF v DFHXMIQX INQUIRE_TRANSACTION v DFHXMIQX SET_TRANSACTION v DFHJCJCX WRITE_JOURNAL_DATA © Copyright IBM Corp. 1977, 2011...
Page 916 Non-threadsafe commands: v DFHDUDUX TRANSACTION_DUMP Customization Guide...
Page 917: Bibliography
Bibliography The CICS Transaction Server for z/OS library The published information for CICS Transaction Server for z/OS is delivered in the following forms: The CICS Transaction Server for z/OS Information Center The CICS Transaction Server for z/OS Information Center is the primary source of user information for CICS Transaction Server.
Page 918 General Administration and Management Programming Customization Guide CICS Transaction Server for z/OS Migration from CICS TS Version 3.1, GC34-6858 CICS Transaction Server for z/OS Migration from CICS TS Version 1.3, GC34-6855 CICS Transaction Server for z/OS Migration from CICS TS Version 2.2,...
Page 919: Other Cics Books
CICS Debugging Tools Interfaces Reference, GC34-6865 Other CICS books The following publications contain further information about CICS, but are not provided as part of CICS Transaction Server for z/OS, Version 3 Release 2. Designing and Programming CICS Applications CICS Application Migration Aid Guide...
Page 920: Vtam Books
SNA Sessions Between Logical Units, GC20-1868 Determining if a publication is current IBM regularly updates its publications with new and changed information. When first published, both hardcopy and BookManager usually in step. However, due to the time required to print and distribute hardcopy books, the BookManager version is more likely to have had last-minute changes made to it before publication.
Page 921 Updates to the softcopy are clearly marked by revision codes (usually a # character) to the left of the changes. Bibliography...
Page 922 Customization Guide...
Page 923: Accessibility
3270 emulator logged on to TSO v using a 3270 emulator as an MVS system console IBM Personal Communications provides 3270 emulation with accessibility features for people with disabilities. You can use this product to provide the accessibility features you need in your CICS system.
Page 924 Customization Guide...
Page 925: Index
ADYN, dynamic allocation transaction 782 AIEXIT, system initialization parameter 516, 544 AILDELAY, system initialization parameter 195 AIRDELAY, system initialization parameter 511 © Copyright IBM Corp. 1977, 2011 allocate queues controlling the length of using the XISCONA global user exit 138...
Page 926 automatic installation of IPIC connections introduction 553 preliminary considerations 553 automatic installation of programs benefits of 581 control program parameter list at install 583 testing 588 installation of mapsets 581 introduction 579 model definitions 580 requirements for 582 supplied resource definitions 587 system autoinstall 581 the sample programs customizing 586...
Page 927 communications area autoinstall control program APPC connections 545 programs 583 terminals 518 autoinstall user program IPCONNs 555 CICSDBCTL interface status program 659 distributed routing program 645 dynamic routing program 607 node error program 487 program error program 441 terminal error program 471 transaction restart program 446 consoles, automatic installation 535 COUNT operand...
Page 928 DFHCSDUP, system definition utility program (continued) sample programs (continued) DFH$CRFA 816 DFH$CRFP 816 DFH$FORA 817 DFH$FORP 817 DFH0CBDC 817 DFH0CRFC 816 DFH0FORC 817 DFHDBUEX, CICS–DBCTL interface status program communications area 659 introduction to 659 sample program 660 DFHDDAPX macro 321, 323, 324, 325, 326, 327, 328, 329, 330 DFHDSATX macro 331 DFHDSRP, distributed routing program...
Page 929 DFHSAIQX macro 386, 391 DFHSMFDS, SMF header DSECT 750 DFHSMMCX macro 392 DFHSMSRX macro 397 DFHSNEP macro TYPE=DEF3270 500 TYPE=DEFILU 501 TYPE=ERRPROC 484, 501 TYPE=FINAL 501 TYPE=INITIAL 483, 500 TYPE=USTOR 499 TYPE=USTOREND 499 DFHSNEP, sample node error program 499 DFHSNET macro 503 COUNT operand 503 ESB structure 503 ESBS operand 503...
Page 930 distributed program link (DPL) (continued) dynamic routing of requests (continued) eligibility for routing 597 error handling 600 terminating a request 600 when the routing program is invoked 598 distributed routing of BTS activities changing the target region 627 eligibility for routing 625 error handling 628 running the activity locally 627 when the routing program is invoked 626...
Page 931 dynamic routing program (DFHDYP) (continued) changing bridge parameters 604 changing the program name 593, 599 changing the target region 592, 599 communications area 607 error handling 594, 600 information passed to 591 invoking on abend 594, 602 modifying application’s communications area 595, modifying initial terminal data 595 overview 589 processing considerations 596, 602...
Page 932 Functional list of GLUEs 32 generic resources, VTAM 547 node error program 512 GET_ATTRIBUTE_VALUE function of the XPI 325 GET_NEXT_ATTRIBUTE function of the XPI 326 GET_NEXT_ENTRY function of the XPI 327 GET_NEXT_PROGRAM function of the XPI 380 GETMAIN function of the XPI 393 global user exits example programs 18 for EXEC interface exits 877...
Page 933 global user exits (continued) sample programs (continued) DFH$WBX1 21 DFH$WBX2 22 DFH$XDRQ 19 DFH$XISQ 24 DFH$XNQE 19, 66 DFH$XZIQ 24 DFH$ZCAT 16 DFHXIS 140 DFHXTENF 230 summary of 15 trace table entries 6 with storage protection data storage key 11 execution key 11 GLUEs 3 GLUEs, alphabetical list 25...
Page 934 log manager functions of the XPI 360 logical units (LUs) node error program 486 LOGON mode table, VTAM 833 LU alias names 523 MAXERRS operand DFHTEPT TYPE=INITIAL 465 MAXTIDS operand DFHTEPT TYPE=INITIAL 465 MCT (monitoring control table) entries for DBCTL 749 entries for EMPs 747 model definitions for autoinstall of APPC connections 543...
Page 935 NEP (node error program) (continued) sample (continued) DFHSNEP TYPE=INITIAL macro 500 DFHSNEP TYPE=USTOR macro 499 DFHSNEP TYPE=USTOREND macro 499 error processor vector table (EPVT) 497, 501 error processors for INTLU, DFHSNEP TYPE=DEFILU 501 error processors, DFHSNEP TYPE=DEF3270 500 error status information 497 generating by DFHSNEP 499 node error table 497 optional common subroutines 498...
Page 936 nonpurgeable task 472 notation, syntax xviii OPTIONS operand DFHTEPM TYPE=INITIAL 460 DFHTEPT TYPE=INITIAL 465 overseer program customizing the sample program 703 including the CEBT command 704 loop or wait detection in the active 705 DFH$AXRO 693 DFHOSD data set 693 DFHWOSM macros 695 FUNC=BUILD 696 FUNC=CLOSE 696...
Page 937 sample programs “good night” transaction (DFH0GNIT) 803 CICS–DBCTL interface status program (DFHDBUEX) 660 for automatic installation of APPC connections 550 for automatic installation of IPCONNs 557 for automatic installation of programs 586 for automatic installation of terminals 527 for distributed routing 657 for dynamic allocation (DYNALLOC) 781 for dynamic routing 622 for global user exits...
Page 938 syntax notation xviii system autoinstall 581 system definition utility program (DFHCSDUP) as a batch program EXTRACT command 814 link-edit statements for user program 819 parameters passed from DFHCSDUP to the user program 815 when the user program is invoked 815 writing a program for EXTRACT processing 814 invocation from a user program entry parameters for DFHCSDUP 822...
Page 939 task-related user exits (continued) UEPHMSA, address of register save area 275 UEPPBTOK, address of performance block token 277 UEPRMQUA, address of the resource manager qualifier name 276 UEPRMSTK, address of the kernel stack entry 275 UEPSECBLK, address of a fullword addressing the user security block 275 UEPSECFLG, address of the user security flag 275 UEPSYNCA, address of the single-update indication...
Page 940 terminal error program (TEP) (continued) replace error processors, DFHTEPM TYPE=ERRPROC 462 sample action flag names 457 common subroutines 455 components 451 DECB information 458 DECB operand 458 DFHTEPM TYPE=INITIAL 459 entry and initialization 454 error processing execution 454 error processor selection 454 error status element (ESE) 452 ESE information 458 exit 455...
Page 941 user-written node error programs 505 utility programs shutdown assist, DFHCESD 429 virtual terminals, automatic installation of 567 VTAM dynamic LU alias 523 work areas in task-related user exits 292 WRITE JOURNAL DATA function of the XPI 419 XALCAID, global user exit 221 XALTENF, global user exit 226 XAPADMGR, global user exit 33 XBMIN, global user exit 35...
Page 942 XPCREQ, global user exit (continued) description 175 example of use 185 parameter list and return codes 177 UEPCLPS parameter 181 XPCREQC, global user exit command parameter structure 181 description 177 example of use 185 parameter list and return codes 179 UEPCLPS parameter 181 XPCTA, global user exit 190 XPI (exit programming interface)
Page 943 XRMMI, global user exit 193 XRSINDI, global user exit 196 XSNEX, global user exit 201 XSNOFF, global user exit 200 XSNON, global user exit 199 XSRAB, global user exit 203 XSTERM, global user exit 206 XSTOUT, global user exit 202, 776 XSZARQ, global user exit 137 XSZBRQ, global user exit 137 XTCATT, global user exit 224...
Page 944 Customization Guide...
Page 945: Notices
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead.
Page 946 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. Customization Guide...
Page 947: Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
Page 948 Customization Guide...
Page 949 When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the personal information that you supply to contact you about the issues that you state on this form.
Page 950 _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ IBM United Kingdom Limited...
Page 952 Product Number: 5655-M15 SC34-6814-04...

IBM SC34-6814-04 Customization Manual

Table of Contents

Chapter 1. Global User Exit Programs

Table of Contents

Chapter 2. Task-Related User Exit Programs

Chapter 3. The User Exit Programming Interface (XPI)

Chapter 4. Writing Initialization and Shutdown Programs

Chapter 5. General Notes about User-Replaceable Programs

Chapter 6. Writing a Program Error Program

Chapter 7. Writing a Transaction Restart Program

Chapter 8. Writing a Terminal Error Program

Chapter 9. Writing a Node Error Program

Chapter 10. Writing a Program to Control Autoinstall of Terminals

Chapter 11. Writing a Program to Control Autoinstall of Consoles

Chapter 12. Writing a Program to Control Autoinstall of APPC Connections

Chapter 13. Writing a Program to Control Autoinstall of IPIC Connections

Chapter 14. Writing a Program to Control Autoinstall of Shipped Terminals

Chapter 15. Writing a Program to Control Autoinstall of Virtual Terminals

Chapter 16. Writing a Program to Control Autoinstall of Programs

Chapter 17. Writing a Dynamic Routing Program

Chapter 18. Writing a Distributed Routing Program

Chapter 19. Writing a CICS-DBCTL Interface Status Program

Chapter 20. Writing a 3270 Bridge Exit Program

Chapter 21. Writing a Security Exit Program for IIOP

Chapter 22. Writing Programs to Customize Jvms

Chapter 23. Writing a Distinguished Name Program for Clients of Enterprise Beans

Chapter 24. Writing an EJB Event Program

Chapter 25. Writing Programs to Customize Language Environment Run-Time Options for Xplink Programs

Chapter 26. The Extended Recovery Facility Overseer Program

Chapter 27. CICS Logging and Journaling

Chapter 28. CICS Monitoring

Chapter 29. Writing Statistics Collection and Analysis Programs

Chapter 30. The Dynamic Allocation Sample Program

Chapter 31. Invoking an External Security Manager

Chapter 32. Writing a "Good Night" Program

Chapter 33. Using the Programmable Interface to CEDA

Chapter 34. User Programs for the System Definition Utility Program (DFHCSDUP)

Appendix A. Coding Entries in the VTAM LOGON Mode Table

Appendix B. Default Actions of the Node Abnormal Condition Program

Appendix C. Analyzing CICS Restart Information

Appendix D. Using the Transient Data Write-To-Terminal Program (DFH$TDWT)

Appendix E. Uppercase Translation

Appendix F. the Example Program for the XTSEREQ Global User Exit, DFH$XTSE

Appendix G. Threadsafe XPI Commands

Quick Links

Chapters

Related Manuals for IBM SC34-6814-04

Summary of Contents for IBM SC34-6814-04