CICS® Transaction Server for OS/390®CICS Customization GuideRelease 3SC33-1683-02IBM
The INQUIRE_PARAMETERS call ...329The SET_PARAMETERS call ...329Monitoring functions...330The MONITOR
Exit XEIOUTWhen invokedAfter the execution of any EXEC CICS API or SPI command.Exit-specific parametersUEPARGAddress of the EXEC command parameter list
UEPRSAAddress of the application’s register save area. This contains thecontents of the registers at the point when the program issued theEXEC CICS co
File control EXEC interface API exits XFCREQ and XFCREQCThe XFCREQ exit allows you to intercept a file control application programminginterface (API) r
The command-level parameter structureThe command-level parameter structure consists of a series of addresses. The firstaddress points to the EXEC inter
FC_FUNCTOne byte that defines the type of request:X'02' READX'04' WRITEX'06' REWRITEX'08' DELETEX'0A'
X'01' SET (and not INTO) was specified.Note: Your program must test for keywords at the bit level, becausethere may be more than one of these
v A 4-byte address returned for SET (if the request is READ, READNEXT, orREADPREV, and if FC_EIDOPT5 indicates that this is SET).v Data returned for I
KEYLENGTHREQIDSYSIDThe following are always output fields:INTONUMRECSETWhether LENGTH and RIDFLD are input or output fields depends on the request,as sh
Modifying output fieldsThe technique described in “Modifying input fields” on page 75 is not suitable formodifying output fields. (The results would be r
X'01' NOSUSPEND specified (on READ, READNEXT, READPREV, WRITE,DELETE, or REWRITE).Bits in the EID should be modified in place. You should not
Rewriting user-replaceable programs ...401Assembling and link-editing user-replaceable programs...402User-replaceable programs and
been function shipped to this region. In this case, if your exit program wants tobypass file control (by setting a return code of UERCBYP), it must set
In XFCREQC:1. Check ‘UEPRCODE’ to make sure that the file control requestcompleted without error.2. Use UEPFCTOK to find the address of the area. This a
UEPFSHIPAddress of a 16 byte area. See “Use of the parameter UEPFSHIP”on page 77.UEPRSRCEAddress of an 8-character copy of the EIB resource value,EIBR
UEPRESPAddress of a 4-byte binary copy of the EIB response code‘EIBRESP’.Note: If the file that has just been accessed is remote, theaddressed field con
Example programCICS supplies, in CICSTS13.CICS.SDFHSAMP, an example program,DFH$XTSE, that shows how to modify fields in the command-level parameterstr
File control EXEC interface SPI exits XFCAREQ and XFCAREQCThe XFCAREQ exit allows you to intercept a file control system programminginterface (SPI) req
Exit XFCAREQWhen invokedBefore CICS processes a file control SPI request.Exit-specific parametersUEPCLPSAddress of a copy of the SPI command parameter l
Exit XFCAREQCWhen invokedAfter a file control SPI request has completed, before return from the filecontrol SPI EXEC interface program.Exit specific para
file control to describe a valid completion. CICS does not check the consistency ofthe values you set. If EIBRCODE is set to a non-zero value and EIBRE
FC_BITS8FC_GROUPAlways X'4C', indicating that this is a file control SPI request.FC_FUNCTOne byte that defines the type of request:X'02&a
The node error program in an XRF environment ...480The node error program with persistent session support ...481Changing the recovery not
X'02' Set if the request contains an argument for theENABLESTATUS keyword. If set, FC_ADDR15 is meaningful.X'01' Set if the reques
X'01' Not used by file control.FC_BITS5Existence bits which specify which arguments were specified. Thecomments below FC_BITS1 also apply to F
FC_ADDR1is the address of an 8-byte area containing the name from FILE.FC_ADDR2is the address of a 44-byte area containing the name from DSNAME.FC_ADD
FC_ADDR23is the address of a 4-byte area containing the CVDA from BLOCKFORMAT.FC_ADDR24is the address of a 4-byte area containing the CVDA from KEYLEN
Table 5. INQUIRE FILE requests. The relationship between arguments, keywords, datatypes, and input/output types.Argument Keyword Data Type Input/Outpu
Note: The file parameter on INQUIRE FILE commands is:v An input field if the request does not specify START, NEXT, or ENDv An output field if the request
Table 6. SET FILE requests (continued). The relationship between arguments, keywords,data types, and input/output types.Argument Keyword Data Type Inp
Note: If you modify the EID, you must be careful not to create inconsistentparameters. For example, if the original request specified SET FILE OPENand
File control file state program exits XFCSREQ and XFCSREQCTwo user exits are provided in the file control state program. You can useXFCSREQ, which is in
Exit XFCSREQWhen invokedBefore a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE isattempted.Exit-specific parametersUEPFSREQAddress of a 2-byte field
Installing shipped terminals and connections ...523CICS-generated aliases ...524Resetting the terminal identifier ...
UEFLNAMEThe 8-character file name.UEDSNAMEThe 44-character dsname of the data set associated withthe file, if this has been set before the file request w
UEFDSACCOne byte indicating the access method of the file. Thepossible values are:UEFVSAMVSAM fileUEFBDAMBDAM file.UEFBCRVSet to nulls for this exit.UEFF
UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI callsAll can be used.Notes:1. Take care when issuing recursive commands not t
UEPFSCPClose pendingUEPFSELMEnd of load mode closeUEPFSIMMImmediate closeUEPFSICPImmediate close pendingUEPFSQURLS quiesce close.UEPFILEAddress of the
UEFJDSNDsname has been journaledUEFJSYNJournal read synchronouslyUEFJASYJournal write asynchronously.UEFDSVJLOne byte indicating a further automatic j
VSAM sphere with which it is associated. It contains thedate when activity against the VSAM sphere was brought toan end (quiesced).UEFCTIMEA time (HHM
Return codesUERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI callsAll can be used.Notes:1. Take ca
File control open/close program exit XFCNRECYou can use XFCNREC to suppress the open failure that occurs when a mismatchis detected between the backou
Exit XFCNRECWhen invokedBefore file open when a mismatch is detected between the backoutrecovery setting for the file and its associated non-RLS data se
File control quiesce receive exit, XFCVSDSThe XFCVSDS exit is invoked when VSAM RLS notifies CICS that processing isrequired as a result of some data s
Changing the transaction ID...560Telling CICS whether to route or terminate a DPL request...560If an error occurs in route select
Exit XFCVSDSWhen invokedInvoked after VSAM RLS has informed CICS that processing is required asa result of a data set-related action occurring in the
CICS isnotto carry out the processing required for the VSAM RLSaction, and is to cancel the action throughout the sysplex.A return code of UERCPURG is
File control quiesce send exit XFCQUISThe XFCQUIS global user exit is invoked on completion of a VSAM RLS quiesce orunquiesce of a data set that was r
UEQTIMEDFailed because quiesce was canceled due to timeout(UEQSD and UEIMQSD only).UEQMIGRTFailed because the data set has been migrated.UEPQCONFAddre
File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER,and XFCLDELCICS provides four global user exits that you can use in connection with fil
If more than one file is associated with a single data set, only the first record inthe first of the files to fail backout within the UOW causes CICS to i
UEDLOCKDeadlock detected.UEDUPRECDuplicate key on unique alternate index.UEIOERORI/O error.UELCKFULRLS lock structure full.UENOLDELLogical delete not
API and SPI callsAlthough this exit is allowed to issue API and SPI calls, you should be verycareful about which commands you use because the exit is
request. This request is issued by file control backout to delete a newrecord added to a VSAM data set. Use parameter UEPFCRSP to determinewhich error
v Sets a response code of UERCNORM and takes the normal exit from theprogram. A return code of UERCNORM specifies that CICS backout failureprocessing i
DFHWOSM FUNC=CLOSE macro ...616DFHWOSM FUNC=DSECT macro ...616DFHWOSM FUNC=JJC macro...616DFHWOSM FUNC={JJS|Q
Exit-specific parametersUEPFLOGRThe address of the file control portion of the log record that is beingpresented for backout. This is mapped by the DSEC
Exit XFCBOVER, file control backout override exitXFCBOVER is part of the support CICS file control provides for “batch windows” ina VSAM RLS environment
When invokedWhenever CICS is about to ignore a UOW log record that is due to bebacked out, because the lock that protected the updated record could ha
DFH$FCBV sample global user exit programDFH$FCBV provides sample processing for the file control backout override globaluser exit, XFCBOVER. The exit p
Exit XFCLDEL, file control logical delete exitXFCLDEL is invoked whenever a WRITE to a VSAM ESDS, or to a BDAM data set,is being backed out. Because th
It is recommended that you restrict EXEC CICS commands to inquiries, andavoid commands that update CICS resources, because the resources maythemselves
v Normal exit from the program:– Makes a user trace entry if tracing is active for file control. This has tracepoint id X'01F1' and traces:-
Front End Programming Interface exits XSZARQ and XSZBRQExits XSZARQ and XSZBRQ are invoked from the CICS/ESA Front EndProgramming Interface (FEPI), if
“Good morning” message program exit XGMTEXTWhen invokedBefore the “good morning” message is transmitted.Exit-specific parametersUEPTCTTEAddress of the
Intersystem communication program exits XISCONA and XISLCLQThe two exits in the intersystem communication program allow you to control thelength of in
Part 6. Customizing CICS compatibility interfaces ...689Chapter 26. Using TCAM with CICS ...691CICS with TCAM SNA...
3. If it is invoked, your exit program must decide whether or not to queue therequest by analyzing the statistics provided through the user exit param
Exit-specific parametersUEPISPCAAddress of a parameter list containing the following fields. You canmap the parameter list using the DSECT DFHXISDS.UEPC
XPI callsAll can be used.ImportantThere is no ‘UERCNORM’ return code at this exit point, because the exit isinvoked after a failure. The choice is whe
Note: No DSECT is provided for the above parameter list. You have tocode your own DSECT to access the named fields.Return codesUERCSYSTake the system a
Interval control program exits XICREQ, XICEXP, and XICTENFYou can use some XPI calls in exit programs invoked from the interval controlprogram. Howeve
Return codesUERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsThe following must not be used:ADD_SUSPENDDELETE_SUSPENDDEQUEUEEN
Interval control EXEC interface program exits XICEREQ andXICEREQCXICEREQ is invoked on entry to the interval control program before CICSprocesses an i
UEPRESP2Address of a 4-byte binary copy of the EIB response code‘EIBRESP2’.UEPTSTOKAddress of a 4-byte token that is valid throughout the life of a ta
‘EIBRCODE’. For details of EIB return codes, refer to theCICSApplication Programming Referencemanual.UEPRESPAddress of a 4-byte binary copy of the EIB
The command-level parameter structureThe command-level parameter structure consists of a series of addresses. The firstaddress points to the EXEC inter
Chapter 29. Writing a “good night” program ...733The sample “good night” program, DFH0GNIT ...735What the sample program does ...
area that describes the type of request and identifies each keyword specified withthe request. The remaining addresses point to pieces of data associate
IC_EIDOPT7IC_EIDOPT8IC_GROUPAlways X'10', indicating that this is an interval control request.IC_FUNCTOne byte that defines the type of reque
X'20' Set if the request specifies HOURS. If set, IC_ADDRB ismeaningful.X'10' Set if the request specifies MINUTES. If set, IC_ADDRC
IC_ADDR1is the address of one of the following:v An 8-byte area containing the value of the INTERVAL keyword (or TIMEkeyword if IC_EIDOPT7 indicates t
IC_ADDREis the address of an area containing the value of USERID.Modifying fields in the command-level parameter structureSome fields that are passed to
An output field is modified by altering the data that is pointed to by thecommand-level parameter list. In the case of an output field, you can modify th
X'01' The existence bit for NOCHECK.IC_EIDOPT7Bits in IC_EIDOPT7 should only be modified within the same functional group -that is, only thos
Using the task token UEPTSTOKUEPTSTOK provides the address of a 4-byte area that you can use to passinformation between successive interval control re
6. Set the X'02' existence bit on in IC_BITS1 to indicate that a SYSID isspecified.7. Return to CICS.In XICEREQC:1. Scan the global work area
Loader domain exits XLDLOAD and XLDELETEThere are two global user exits in the loader domain. XLDLOAD is invoked when anew instance of a program is lo
Index ...823Sending your comments to IBM ...841xvi CICS TS for OS/390: CICS Customization Guide
XPI callsMust not be used.API and SPI callsMust not be used.Exit XLDELETEWhen invokedAfter an instance of a program is released by CICS, and before th
Log manager domain exit XLGSTRMThere is one exit point, XLGSTRM, in the log manager domain.You can use XLGSTRM to modify a request to MVS to create a
An XLGSTRM global user exit program can set explicit attributes for the log streamdefinition, and can also set a return code that causes the log stream
UERCBYPCICS does not attempt to define the log stream. The process thatwas attempting to use the log stream may fail (for example, a dataset open).XPI
Message domain exit XMEOUTThe XMEOUT exit allows you to suppress or reroute CICS messages that use themessage domain.Note that your exit program is su
ImportantBecause of the danger of recursion, your XMEOUT exit program should nottry to reroute:v Any DFHTDxxxx messages, produced by the transient dat
UEPMNUMAddress of a 4-byte field containing the message number.UEPMDOMAddress of a 2-byte field containing the domain identifier of theCICS message.UEPMR
UEPNRTEAddress of 1-character flag indicating whether or not the messagecan be rerouted by XMEOUT. The possible values are:C'0:' The message
Monitoring domain exit XMNOUTXMNOUT is invoked before an exception class monitoring record is passed to SMF,and before a performance class monitoring
UEPMRTYPAddress of the halfword monitoring record type. If the value is 3,the type is performance class. If the value is 4, the type isexception class
NoticesThis information was developed for products and services offered in the U.S.A. IBMmay not offer the products, services, or features discussed i
Program control program exits XPCREQ, XPCREQC, XPCFTCH,XPCHAIR, XPCTA, and XPCABNDThere are six user exit points in the program control program.XPCREQ
Return codesUERCBYPProgram control is to ignore the request.UERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.A
XPI callsAll 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 FREEM
PC_ADDR0is the address of a 7-byte area called the EXEC interface descriptor (EID),which is made up as follows:PC_GROUPPC_FUNCTPC_BITS1PC_BITS2PC_EIDO
PC_BITS2Two bytes not used by program control.PC_EIDOPT5Not used by program control.PC_EIDOPT6Indicates whether the request specifies the SYNCONRETURN
An output field is modified by altering the data that is pointed to by thecommand-level parameter list. In the case of an output field you can modify the
example, if you need to pass information between successive invocations of theXPCREQ exit, UEPTSTOK provides a means of doing this.The EIBCopies of EI
3. If a GETMAIN was issued in XPCREQ to obtain an area to hold the SYSID,issue a FREEMAIN for the address held in UEPPCTOK.4. Return to CICS.Exit XPCF
PCUE_LOAD_POINTThe program’s load point.PCUE_ENTRY_POINTThe program’s entry point.PCUE_PROGRAM_SIZEFullword containing the size of the program, in byt
Exit-specific parametersUEPPCDSAddress of a storage area that contains program- andterminal-related information, and that can be mapped using theDSECT
The licensed program described in this document and all licensed material availablefor it are provided by IBM under terms of the IBM Customer Agreemen
Exit XPCTAXPCTA is invoked immediately after a transaction abend, and before anyprocessing that might modify the existing environment so that the task
PCUE_BRANCH_CICSCICS key.If storage protection is active, and you do not specify avalue, the resumed task executes in User key.If storage protection i
Exit-specific parametersUEPPCDSAddress of a storage area that contains program-related andterminal-related information. The storage area is mapped by t
Resource manager interface program exits XRMIIN and XRMIOUTExit XRMIINWhen invokedBefore a task-related user exit program is invoked due to an applica
Exit XRMIOUTWhen invokedAfter a task-related user exit program has returned from handling an RMIAPI request.Exit-specific parametersUEPTRUENAddress of
Resource management install and discard exit XRSINDIThe XRSINDI global user exit is driven, if it is enabled, immediately after CICSsuccessfully insta
UEPTERMAddress of the 4-byte terminal ID.UEPPROGAddress of the 8-byte application program name.UEPIDREQAddress of the 1-byte install or discard identi
UEIDMODEA modegroupUEIDNQRNAn ENQMODELUEIDPARTA partnerUEIDPROFA profileUEIDPROGA programUEIDPRTYA BTS process-typeUEIDPSETA partitionsetUEIDRQMDA requ
UEIDKEEPThe resources are recoverable at a warm or emergencyrestart.UEIDLOSEThe resources are not recoverable.Note: The exit is not driven during a CI
Signon and signoff exits XSNON and XSNOFFExit XSNON is invoked after a terminal user signs on, and exit XSNOFF is invokedafter a terminal user signs o
TrademarksThe following terms are trademarks of International Business Machines Corporationin the United States, or other countries, or both:ACF/VTAM
UEPSNFLSignon failed.Return codesUERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.Exit XSNOFFWhen invokedWhen
UERCPURGTask purged during XPI call.XPI callsAll can be used.sign on and sign off exitsChapter 1. Global user exit programs 179
Statistics domain exit XSTOUTOn invocation, XSTOUT is passed the address of a buffer containing one or morestatistics records. The buffer can contain
UEPSDATEAddress of a 6-byte character field containing the collection date(MMDDYY).UEPSTIMEAddress of a 6-byte character field containing the collection
System recovery program exit XSRABExit XSRABWhen invokedWhen the system recovery program (DFHSRP) finds a match in the SRT foran MVS/ESA™ abend code. F
SRP_USER_CODEThe abend occurred while running user applicationcode.SRP_PPT_ENTRYThe abend occurred while runningSRP_ERROR_PPT_NAME. If this flag is not
SRP_ERROR_FP_REGSAn area describing the contents of the floating pointregisters at the time of the abend. It contains:SRP_FP_REG_0FP register 0SRP_FP_R
ImportantNotes:1. Take care when coding a program to run at the XSRAB exit point. If yourexit program causes the system recovery program to be reenter
System termination program exit XSTERMThe XSTERM exit could be used to output final statistics to your statistics SMF datasets, and to close them. (Not
Temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, andXTSPTOUTThe temporary storage domain exits XTSQRIN, XTSQROUT, XTSPTIN, andXTSPTOUT allow
xx CICS TS for OS/390: CICS Customization Guide
UEP_TS_DATA_PAddress of a fullword containing the address of the data. (Write andrewrite requests).UEP_TS_DATA_LAddress of a fullword containing the l
UEPPROGAddress of the 8-byte application program name.UEP_TS_FUNCTIONAddress of a byte containing the function:UEP_TS_FUN_WRITEUEP_TS_FUN_REWRITEUEP_T
Exit XTSPTINWhen invokedBefore execution of a temporary storage interface request for a CICSinternal queue (for example, for interval control or BMS q
UEP_TS_STORAGE_TYPE_AUX_RECOV_NOAuxiliary storage (non-recoverable).Return codesUERCNORMNormal.UERCPURGTask purged during XPI call.XPI callsAll can be
UEP_TS_RESPONSE_OKUEP_TS_RESPONSE_PURGEDUEP_TS_RESPONSE_EXCEPTIONUEP_TS_RESPONSE_DISASTERUEP_TS_RESPONSE_INVALIDReturn codesUERCNORMNormal response.UE
Temporary storage EXEC interface program exits XTSEREQ andXTSEREQCThe XTSEREQ exit allows you to intercept temporary storage API requests beforeany ac
Exit XTSEREQWhen invokedBefore CICS processes a temporary storage API request.Exit-specific parametersUEPCLPSAddress of a copy of the command parameter
Exit XTSEREQCWhen invokedAfter a temporary storage API request has completed, before return fromthe temporary storage EXEC interface program.Exit-spec
You must set valid temporary storage responses. You must set all three ofEIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as wouldb
TS_FUNCTTS_BITS1TS_BITS2TS_EIDOPT5TS_EIDOPT6TS_EIDOPT7TS_EIDOPT8TS_GROUPAlways X'0A', indicating that this is a temporary storage request.TS
PrefaceWhat this book is aboutThis book provides the information needed to extend and modify an IBM® CICS®Transaction Server for OS/390® system to mat
X'80' WRITEQ MAIN or READQ ITEM specified.X'04' WRITEQ REWRITE or READQ NUMITEMS specified.TS_EIDOPT8Indicates whether certain keywo
NUMITEMSSETLENGTH is an input field on a WRITEQ request, and an output field on a READQrequest that specifies SET. It is both an input and an output field
X'10' The existence bit for NOSUSPEND.X'08' The existence bit for MAIN.The EID is reset to its original value before return to the
Table 9. DELETEQ TS: User arguments and associated keywords, data types, andinput/output typesArgument Keyword Data type Input/output typeArg1 QUEUE C
Example programCICS supplies—in hardcopy only—an example program, DFH$XTSE, thatshows how temporary storage requests can be modified. See “Appendix E.T
Terminal allocation program exit XALCAIDXALCAID is driven when an AID with data is canceled in one of the following ways:v By means of the CEMT transa
contains FMHs, as specified by the FMH option on the associatedSTART command; or hexadecimal zeros otherwise.UEPALSTCAddress of a 2-byte field containin
Terminal control program exits XTCIN, XTCOUT, XTCATT, XTCTIN, andXTCTOUTExit XTCINWhen invokedAfter an input event for a sequential device.Exit-specifi
Exit XTCATTWhen invokedBefore task attach.Exit-specific parametersUEPTCTTEAddress of the terminal control table terminal entry (TCTTE). TheTCTTE can be
Exit XTCTOUTWhen invokedBefore a TCAM output event.Exit-specific parametersUEPTCTTEAddress of the terminal control table terminal entry (TCTTE). TheTCT
CICS Transaction Server for OS/390 Release 3 supports CICS applications writtenin:v Assembler languagev Cv COBOLv PL/I.In this book, the phrase “the l
‘Terminal not known’ condition exits XALTENF and XICTENFThe ‘terminal not known’ condition can occur when intercommunicating CICSregions use both SHIP
CICS drives the XICTENF exit when the ‘terminal not known’ condition occurs afterthe interval control program has been invoked by an EXEC CICS START c
Exit-specific parametersUEPALEVTAddress of 2 bytes containing the type of request. The equatedvalues of the types are:UEPALESDSTART command with dataUE
For START commands issued in this system by transaction routingto a task, the netname of the last system from which the task wasrouted.For other START
Exit XICTENFWhen invokedBy the interval control program when the terminal that an EXEC CICSSTART command requires is unknown in this system. The exit
UEPICNTIAddress of 8 bytes containing, for function-shipped STARTcommands, the netname of the last system from which the requestcame.For START command
DELETE_SUSPENDDEQUEUEENQUEUERESUMESUSPENDWAIT_MVS.The sample program for the XALTENF and XICTENF exits, DFHXTENFOne program can be used for both exits
*BLDNETNM DS 0H** Build a netname by taking the first character of the* terminal ID and appending it to the characters 'CICS'.*L R2,UEPICNTO
Transaction manager domain exit XXMATTExit XXMATTWhen invokedDuring transaction attach. This exit is able to change some of the attributesof the trans
UEPATTTKThe address of a doubleword containing a transaction token. Notethat some of the transaction manager XPI calls require this token toidentify t
BibliographyCICS Transaction Server for OS/390CICS Transaction Server for OS/390: Planning for InstallationGC33-1789CICS Transaction Server for OS/390
Transient data program exits XTDREQ, XTDIN, and XTDOUTExit XTDREQWhen invokedBefore request analysis.Exit-specific parametersUEPTDQUEAddress of 4-byte
Exit XTDINWhen invokedAfter receiving data from QSAM (for extrapartition) or VSAM (forintrapartition).Exit-specific parametersUEPTDQUEAddress of the 4-
Exit XTDOUTWhen invokedBefore passing the data to a QSAM (for extrapartition) or VSAM (forintrapartition) user-defined transient data queue.Exit-specifi
Transient data EXEC interface program exits XTDEREQ andXTDEREQCThe XTDEREQ exit allows you to intercept a transient data request before anyaction has
UEPRCODEAddress of a 6-byte hexadecimal copy of the EIB return code‘EIBRCODE’. For details of EIB return codes, refer to theCICSApplication Programmin
Exit XTDEREQCWhen invokedAfter a transient data API request has completed, and before return fromthe transient data EXEC interface program.Exit-specifi
The command-level parameter structureThe command-level parameter structure consists of a series of addresses. The firstaddress points to the EXEC inter
End of parameter list indicatorThe high-order bit is set on in the last address set in the parameter list toindicate that it is the last one in the li
TD_BITS1Existence bits that define which arguments were specified. To obtainthe argument associated with a keyword, you need to use theappropriate addre
TD_ADDR4is the address of a value intended for CICS internal use only. It must not beused.TD_ADDR5is the address of a value intended for CICS internal
CICSPlex SM books for CICS Transaction Server for OS/390GeneralCICSPlex SM Master IndexSC33-1812CICSPlex SM Concepts and PlanningGC33-0786CICSPlex SM
An output field is modified by altering the data that is pointed to by thecommand-level parameter list. In the case of an output field, you can modify th
The EIBCopies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to theexit, so that you can:v Modify or set completion and resource information
User log record recovery program exits XRCINIT and XRCINPTAt warm and emergency restart, updates made to recoverable CICS resources thatwere not commi
v There is a restriction on using the XPI early during initialization: do not invokeexit programs that use the XPI functions TRANSACTION_DUMP,WRITE_JO
programs” on page 393.Exit XRCINITWhen invokedAt warm and emergency restart:v Before the first user recovery record is delivered to XRCINPTv When all s
be mapped using the information supplied in “Chapter 23. CICSlogging and journaling” on page 629.UEPLGLENAddress of a fullword containing the length o
VTAM terminal management program exit XZCATTExit XZCATTWhen invokedBefore task attach for terminal tasks.Exit-specific parametersUEPTCTTEAddress of the
VTAM working-set module exits XZCIN, XZCOUT, XZCOUT1, andXZIQUENote: None of the exits in the VTAM working-set module is available for advancedprogram
XPI callsAll can be used. However, we do not recommend that you use a GETMAINcall to obtain terminal-class storage for use as a replacement TIOA. This
XZIQUE exit for managing intersystem queuesYou can use the XZIQUE exit to control the number of queued requests forsessions on intersystem links (allo
MVS booksShort Title Full TitleAssembler Programming Guide OS/390 MVS Assembler Services Guide,GC28-1762Authorized Assembler Programming Guide OS/390
modegroups, depending on the session request. Non-specific allocate requests arefor MRO, LU6.1, and APPC sessions that do not specify a modegroup.Using
If the queue limit has been reached but the performance of allocate processingagainst the queue is below the acceptable limits defined in your user exi
A14EALRJ:Each time an XZIQUE global user exit program returns with a requestto reject a request, CICS increments a new field in the system entry connec
UEPRC8The exit program returned control to CICS on the previousinvocation with return code 8.UEPRC12The exit program returned control to CICS on the p
Non-specific allocates data:The following three fields contain data relatingto MRO, LU6.1, and non-specific APPC allocates:UEPSAQTSA double-word binary fi
modegroup specified on this allocate request and send aninformation message to the operator console. Retry the modegroupafter an interval.UERCPURGTask
Sample exit program designA sample XZIQUE exit program is provided with CICS Transaction Server forOS/390 Release 3 as a base for you to design your o
CICS invokes the exit program to enable it to indicate that normal processingcan continue.In this case, the exit program returns with UERCNORM to indi
XRF request-processing program exit XXRSTATXXRSTAT enables you to decide whether to terminate CICS when either of thefollowing occurs:v CICS is notifie
Return codesUERCNORMTake the system action. The system action depends on the reasonwhy the exit was invoked:v For XRF, in the event of a VTAM failure:
Determining if a publication is currentIBM regularly updates its publications with new and changed information. When firstpublished, both hardcopy and
XRF request-processing program exit248CICS TS for OS/390: CICS Customization Guide
Chapter 2. Task-related user exit programsThis chapter describes a special kind of user exit called a task-related user exit.Atask-related user exit a
The task-related user exit program is provided with a parameter list (DFHUEPAR)by the CICS management module that handles task-related user exits. Thi
statnameis a label that can be referenced externally. It should conform to therequirements of an assembler-language ENTRY statement, and typicallyreso
If you do not specify RTNABND=YES and the task-related user exit is not available,the application program terminates abnormally with the abend code ‘A
User exit parameter listsWhen a task-related user exit is invoked, the CICS management module thathandles task-related user exits provides the exit wi
command. The global work area is described on page “The global workarea” on page 269. CICS initializes this work area to X'00' when thetask-
UEPUOWDSAddress of the APPC unit of work (UOW) identifier.UEPSECFLGAddress of the user security flag. The user security flag is a 1-byte field thatcan tak
data locations can be above or below 16MB; whether the application’sstorage is in CICS-key or user-key storage; and whether the TRUE hasbeen called by
UEPTRLV1 (X'80')RMI level 1 trace is active.UEPTRLV2 (X'40')RMI level 2 trace is active.Having tested this field, the task-related
Summary of changesThis book is based on theCustomization Guidefor CICS Transaction Server forOS/390 Release 2, SC33-1683-01. Changes from that edition
exit program can be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAMcommands on which the CONNECTST or QUALIFIER option is specified. Thisallows applic
UERTBACK(X'20') Backout.UERTDGCS(X'10') Unit of recovery has been lost because of an initial start ofCICS.UERTDGNK(X'08'
Parameter 6Address of a 4-byte, packed-decimal field containing the date of the failingsyncpoint, in the format 00yyddd+. See note 1.Parameter 7Address
The significance of the parameters is as follows:Parameter 1The address of a single byte with bit definitions indicating the reason for thecall:UERTSOTR
UEPEDFFIThe input flag byte. When a task-related user exit is invoked by EDF,UEPEDFFI can take the following bit settings:UEPEDFRQ(X'80') “Ab
Notes:1. CICS provides a list of named standard attribute bytes that you maywant to use. These standard attribute bytes are contained withinDFHBMSCA,
CICS SPI Application Syncpoint Task manager Termination CICS EDFcall program call manager call call manager call callDFHUEPAR DFHUEPAR DFHUEPAR DFHUEP
The schedule flag wordThe schedule flag word is a fullword indicator that the task-related user exitprogram uses to control its own invocation. It is al
program to be called at the start as well as at the end of a task, you must specifyTASKSTART on the EXEC CICS ENABLE command for the TRUE. This causes
significance of register settings on return are either described in your resourcemanager’s documentation, or defined locally.Addressing-mode implication
CICS® Transaction Server for OS/390®CICS Customization GuideRelease 3SC33-1683-02IBM
- XEISPOUT– In the file control recovery program:- XFCAREQ- XFCAREQC– In the 3270 bridge facility management program:- XFAINTUv The following new exit
another program (via a link or transfer-control command), the program thus invokedexecutes according to the execution key (EXECKEY) defined in its prog
v DFHEIENT and DFHEIRET must be in your program.But see the note about notusing DFHEIENT in abend invocations, on page 276.For further details of theD
that is exclusively for the exit program’s use. It is specified using the TALENGTHoption of the EXEC CICS ENABLE command and is accessed using the UEPT
Increasing efficiency – single-update and read-only protocolsIf your resource manager is capable of performing a single-phase commit, you canincrease
Table 12. Valid return codes for a TRUE invoked by the CICS syncpoint managerRequest-type Return codes MeaningUERTPREPUERFPREP Phase 1 of 2-phase comm
As described in “Increasing efficiency – single-update and read-only protocols” onpage 271 , if the UERTONLY bit is set (indicating that the resource
a UERTELUW call. Because no updates were made, data integrity is not at risk,and therefore no action is taken if the commit fails.On receiving a reque
invocation is at start- or end-of-task, you can examine the CICS task managerparameters described in “CICS task manager parameters” on page 260. Typic
The limitations on what your program can do, if invoked, depend on the type oftermination:Orderly shutdown (UERTCORD)Your exit program must follow the
JTRUE1A CSECT TERMINATION TRUE ENTRYPOINTSTM 14,12,12(13) Save registersUSING JTRUE1A,R3LR R3,R15 Use R3 as base registerUSING DFHUEPAR,R1 Address DFH
The following global user exits became obsolete:– XDBDERR– XDBFERR– XDBIN– XDBINIT– XJCWB– XJCWR– XKCREQ– XRCFCER– XRCOPER– XTSIN– XTSOUT– XTSREQv Cha
Using EDF with your task-related user exit programIf your exit program sets the EDF bit in the schedule flag word and EDF is active,the exit program is
Table 13 describes each stage of the interface between the task-related user exitand EDF, relating the descriptions to the (Tn) and (En) expressions i
ImportantThe E1/T2 and E2/T5 cycles can be used repeatedly. This may occur, forexample, if the EDF user changes the screen a number of times.Adapter a
user exit should invoke its resource manager to free any task-relatedresources, such as the thread. However, the resource manager shouldmaintain any l
Tracing a task-related user exit programCICS outputs a trace entry just before control is passed to the task-related user exitand just after returning
Chapter 3. The user exit programming interface (XPI)This chapter describes the user exit programming interface (XPI) of CICSTransaction Server for OS/
v Using the XPI dump control functions, you can:– Request a system dump—see “The SYSTEM_DUMP call” on page 314– Request a transaction dump—see “The TR
– Change the settings of the autoinstall function for programs, mapsets, andpartitionsets—see “The SET_AUTOINSTALL call” on page 350.v Using the XPI s
Note: Using the XPI feature table, you can register a CICS-supplied feature (suchas ONC/RPC) to CICS. After it has been registered, you can inquire on
The general format (omitting the assembler-language continuation character) of allXPI calls is:macro-name [CALL],[CLEAR],[IN,FUNCTION(call_name),mandi
– The descriptions of fields in CICS-produced monitoring records, previously in“Chapter 24. CICS monitoring” on page 657, were moved to theCICSPerforma
Note: If you build your parameter list incrementally, do not specify CLEARwhen you finally issue the call, because the CLEAR option sets theparameter l
the name of a field in which you want the RESPONSE value to be placed.You need not code the RESPONSE option if you are using the macrowithout CALL to b
Note that if an XPI call other than DFHDSSRX SUSPEND orWAIT_MVS gets this RESPONSE, your exit program should set thereturn code to ‘UERCPURG’ and retu
CICS to perform the XPI call processing. You must not use any of these fields: ifyou do so, your user exit program will have unpredictable results.The
to to obtain more than the extra 64 bytes provided, obtain it by either aDFHSMMCX FUNCTION (GETMAIN) macro, or an MVS GETMAIN request.Information to b
TITLE 'GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI'************************************************************************** The first three
************************************************************************** The next seven instructions form the normal start of a global user ** exit
************************************************************************** Issue the DFHSMMCX macro call, specifying: ** ** CALL -- the macro is to be
************************************************************************** Test SMMC_RESPONSE -- if OK, then branch round error handling. ************
An example showing how to build a parameter list incrementallyIn the following example, the parameter list is built incrementally. The initialization
Part 1. Customizing with user exit programs© Copyright IBM Corp. 1977, 1999 1
DFHSMMCX CLEAR...DFHSMMCX GET_LENGTH(100)...DFHSMMCX CALL, *IN, *FUNCTION(GETMAIN), *GET_LENGTH(*), *SUSPEND(NO), *INITIAL_IMAGE(X'00'), *ST
OPTION(addr,len)addr The data address as {namea | (Ra) | aliteral}:nameaThe name of a location containing the data address(Ra) A register containing t
maxlenThe maximum data length as {namel | (Rn) | expression}:namel The name of a location containing a binary fullword givingthe maximum data length i
v Issuing the SUSPEND call.2. Task B performs the action by:v Getting the parametersv Performing the actionv Setting the resultsv Terminating (or wait
The difference is that Set results and Get results are replaced by Clean up. It isvital that only these two sequences can happen; this means that both
ADD_SUSPENDDFHDSSRX [CALL,][CLEAR,][IN,FUNCTION(ADD_SUSPEND),[RESOURCE_NAME(name16 | string | 'string'),][RESOURCE_TYPE(name8 | string | &ap
RESPONSE and REASON values for ADD_SUSPEND:RESPONSE REASONOK NoneEXCEPTION NoneDISASTER NoneINVALID NoneKERNERROR NonePURGED NoneNote: For more detail
(Rn) A register containing the interval value, a binary fullword.PURGEABLE(YES|NO)specifies whether your code can cope with the request being abnormall
"string"A string of characters enclosed in quotation marks. Blanks are permittedin the enclosed string. If you want to document a name (labe
Note: This is the default reason given to the wait if you suspend a task anddo not specify the WLM_WAIT_TYPE parameter.OTHER_PRODUCTWaiting on another
2 CICS TS for OS/390: CICS Customization Guide
corresponding RESUME. You must ensure that you keep account of the SUSPENDand RESUME requests issued from your exit program.RESUMEDFHDSSRX [CALL,][CLE
DELETE_SUSPENDDFHDSSRX [CALL,][CLEAR,][IN,FUNCTION(DELETE_SUSPEND),SUSPEND_TOKEN(name4 | (Rn)),][OUT,RESPONSE(name1 | *),REASON(name1 | *)]SUSPEND_TOK
WAIT_MVSDFHDSSRX [CALL,][CLEAR,][IN,FUNCTION(WAIT_MVS),{ECB_ADDRESS(name4 | (Ra)) | ECB_LIST_ADDRESS(name4 | (Ra)),}PURGEABLE(YES|NO),[INTERVAL(name4
Table 15. WAIT_MVS call - RESPONSE(PURGED)REASON TASK_CANCELLED TIMED_OUTCONDITION PURGE FORCEPURGE DTIMOUT INTERVALPURGEABLE (NO) Canceled Proceeds n
MILLI_SECONDThe INTERVAL option specifies the number of milliseconds beforetimeout.WLM_WAIT_TYPE(name1)specifies, in a 1-byte location, the reason for s
RESPONSE and REASON values for WAIT_MVS:RESPONSE REASONOK NoneEXCEPTION NoneDISASTER NoneINVALID NoneKERNERROR NonePURGED TASK_CANCELLEDTIMED_OUTNotes
literalconstA number in the form of a literal, for example B'00000000', X'FF',X'FCF4', "0" or an equate symbol
CALLER(block-descriptor)specifies the source of a system dump request. The information that you supplyhere appears in the dump header, so you could use
The TRANSACTION_DUMP callTRANSACTION_DUMP causes a transaction dump to be taken. If the transactiondump code that you supply on input is in the transa
and SEGMENT_LIST are mutually exclusive.TCA(NO|YES)specifies whether the task control area (TCA) is to be included in thetransaction dump. The default
Chapter 1. Global user exit programsThis chapter describes the CICS global user exit points, and how you can usethem, in conjunction with programs of
Notes:1. For more detail, refer to the explanation of RESPONSE and REASON in“General form of an XPI call” on page 286.2. ‘NOT_OPEN’ means that the CIC
However, as no recovery services are provided for abending global user exits,CICS ensures that any outstanding XPI enqueues are dequeued automatically
Kernel domain functionsThe START_PURGE_PROTECTION functionThe START_PURGE_PROTECTION function is provided on the DFHKEDSX macrocall. It inhibits purge
Nesting purge protection callsNote that the START_ and STOP_PURGE_PROTECTION functions can be nested.You should ensure that, if multiple START_PURGE_P
DEFINE_PROGRAMDFHLDLDX [CALL,][CLEAR,][IN,FUNCTION(DEFINE_PROGRAM),PROGRAM_NAME(name8 | string | 'string' ),[EXECUTION_KEY(CICS|USER),][PROG
Table 16. Summary of attributes defining DSA eligibility (continued)EXECUTION_KEYoptionReentrant Above or below16MB lineDynamic storagearea (DSA)USER Y
ECDSACannot be overwritten by USER tasksERDSAComplete—cannot be overwritten by USER tasks or CICS tasksEUDSANoneRDSA Complete—cannot be overwritten by
The ACQUIRE_PROGRAM callACQUIRE_PROGRAM returns the entry and load point addresses, the length, anda new program token for a usable copy of the named
storage unless deleted. RESIDENT programs must be at leastquasireentrant. Any program of PROGRAM_TYPE SHAREDhas the RESIDENT attribute by default. The
2. A REASON of ‘NO_STORAGE’ with a RESPONSE of ‘EXCEPTION’ means thatthere was insufficient storage to satisfy this request, and SUSPEND(NO) wasspecifi
Each global user exit point has a unique identifier, and is located at a point in themodule or domain at which it could be useful to do some extra proc
RESPONSE REASONEXCEPTION PROGRAM_NOT_DEFINEDPROGRAM_NOT_IN_USEDISASTER NoneINVALID NoneKERNERROR NonePURGED NoneNotes:1. For more detail, refer to the
Log manager functionsThere are two XPI log manager functions. These are the DFHLGPAX calls:INQUIRE_PARAMETERSSET_PARAMETERSThese calls allow you to in
SET_PARAMETERSDFHLGPAX [CALL,][CLEAR,][IN,FUNCTION(SET_PARAMETERS),[KEYPOINT_FREQUENCY(name4 | (Rn) ),]][OUT,RESPONSE(name1 | *),REASON(name1 | *)]KEY
The user event-monitoring points must be defined in the usual way in themonitoring control table (MCT). For more information about CICS monitoring, rea
DATA2(expression | name4 | (Rn) | *)specifies a fullword binary variable whose contents depend on the type of userEMP being used:v If the MCT user EMP
expressionA valid assembler-language expression that can be expressed in 2bytes.name2The name of a 2-byte source of point data(Rn) A register containi
INQUIRE_MONITORING_DATADFHMNMNX [CALL,][CLEAR,][IN,FUNCTION(INQUIRE_MONITORING_DATA),DATA_BUFFER(buffer-descriptor),][OUT,RESPONSE(name1 | *),REASON(n
and the DFHPGAQX calls:INQUIRE_AUTOINSTALLSET_AUTOINSTALL.Used with the Loader functions DEFINE_PROGRAM, ACQUIRE_PROGRAM,RELEASE_PROGRAM, and DELETE_P
CICS CICS-keyNONE The program has not been loadedREAD_ONLYReadonlyUSER User-key.AVAIL_STATUS(DISABLED|ENABLED)returns a value indicating whether the p
ENTRY_POINT(name4)returns the program’s entry point address, as it would be returned by a Loaderdomain ACQUIRE_PROGRAM call.EXECUTION_KEY(CICS|NOT_APP
v Register 15 contains the entry address of the exit program.No other register values are guaranteed, and they should not be relied on. The exitprogra
MANUALThe program is a CICS internal module explicitly defined to theProgram Manager by another CICS component.RDO RDO commands.SYSAUTOSystem autoinsta
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
NOT_APPLICNot applicable. The program is remote.PRIVATEThe program is to be loaded from the relocatable program library (RPL).A PRIVATE program need n
RESPONSE and REASON values for INQUIRE_PROGRAM:RESPONSE REASONOK NoneEXCEPTION PROGRAM_NOT_DEFINED_TO_LDPROGRAM_NOT_DEFINED_TO_PGDISASTER ABENDLOCK_ER
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
RESPONSE and REASON values forINQUIRE_CURRENT_PROGRAM:RESPONSE REASONOK NoneEXCEPTION NO_CURRENT_PROGRAMDISASTER LOCK_ERRORABENDINVALID NoneKERNERROR
Note: If the program has been link-edited as reentrant withAMODE(31),RMODE(ANY), the EXECUTION_KEY option is ignored,and it is loaded into the extende
name4The name of a location containing a 4-byte token obtained from aprevious INQUIRE_PROGRAM, INQUIRE_CURRENT_PROGRAM,START_BROWSE_PROGRAM, or GET_NE
RESPONSE and REASON values for SET_PROGRAM:RESPONSE REASONOK NoneEXCEPTION CEDF_STATUS_NOT_FOR_MAPSETCEDF_STATUS_NOT_FOR_PTNSETCEDF_STATUS_NOT_FOR_REM
string A string of characters naming the program.'string'A string of characters in quotation marks. The string length is set to 8by padding
All exit programs that issue EXEC CICS commands, and that use the DFHEIENTmacro, should use the DFHEIRET macro to set a return code and return toCICS.
GET_NEXT_PROGRAMDFHPGISX [CALL,][CLEAR,][IN,FUNCTION(GET_NEXT_PROGRAM),BROWSE_TOKEN(name4),][OUT,PROGRAM_NAME(name8),[ACCESS(CICS|NONE|READ_ONLY|USER)
NEW_PROGRAM_TOKEN(name4)returns a token that identifies the next definition in the browse sequence. Youcan use it in the BROWSE_TOKEN field of your next
The INQUIRE_AUTOINSTALL callINQUIRE_AUTOINSTALL returns information about the current settings of theautoinstall function for programs, mapsets, and p
SET_AUTOINSTALLDFHPGAQX [CALL,][CLEAR,][IN,FUNCTION(SET_AUTOINSTALL),[AUTOINSTALL_CATALOG (ALL|MODIFY|NONE),][AUTOINSTALL_EXIT_NAME(name8),][AUTOINSTA
State data access functionsThe state data access functions allow you to inquire on and set certain system datain the AP domain.The INQ_APPLICATION_DAT
SYSEIB(name4 | (Rn) | *)returns the address of the system EXEC interface block of the current task.name4The name of a fullword area that is to receive
RESPONSE and REASON values for INQ_APPLICATION_DATA:RESPONSE REASONOK NoneEXCEPTION DPL_PROGRAMNO_TRANSACTION_ENVIRONMENTTRANSACTION_DOMAIN_ERRORDISAS
The INQUIRE_SYSTEM callThe INQUIRE_SYSTEM call gives you access to CICS system data in the APdomain.INQUIRE_SYSTEMDFHSAIQX [CALL,][CLEAR,][IN,FUNCTION
CICSSYS(name1 | *)returns the operating system for which the running CICS has been built.name1The name of a 1-byte area that is to receive the hexadec
GMMTRANID(name4 | *)returns the transaction identifier of the CICS good morning transaction.name4The name of a 4-byte area that is to receive the CICS
Application programs can communicate with user exit programs that use or sharethe same global work area. The application program uses the EXEC CICSEXT
name1The name of a 4-byte area that is to receive the version and releasenumber of OS/390 on which CICS is running. A value of “0240”represents OS/390
name4The name of a 4-byte location that is to receive the startup date of thisCICS system.TERMURM(name8 | *)returns the name of the autoinstall user p
SET_SYSTEMDFHSAIQX [CALL,][CLEAR,][IN,FUNCTION(SET_SYSTEM),[DTRPRGRM(name8 | string | 'string'),][GMMLENGTH(name2 | (Rn) | expression),][GMM
Storage control functionsThere are seven XPI storage control functions. These are the DFHSMMCX macrocalls GETMAIN, FREEMAIN, INQUIRE_ELEMENT_LENGTH, a
GETMAINDFHSMMCX [CALL,][CLEAR,][IN,FUNCTION(GETMAIN),GET_LENGTH(name4 | (Rn) | expression),STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24|SHARED_
STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24|SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL)specifies the class of the storage that is the subje
2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request was specifiedwith SUSPEND(NO), and there was not enough storage available to satisfy there
INQUIRE_ACCESSDFHSMSRX [CALL,][CLEAR,][IN,FUNCTION(INQUIRE_ACCESS),ELEMENT_ADDRESS(name4 | (Rn) | *),ELEMENT_LENGTH(name4 | (Rn) | *),][OUT,ACCESS(CIC
INQUIRE_ELEMENT_LENGTHDFHSMMCX [CALL,][CLEAR,][IN,FUNCTION (INQUIRE_ELEMENT_LENGTH),ADDRESS (name4 | (Rn) | *),][OUT,ELEMENT_ADDRESS(name4 | (Rn) | *)
INQUIRE_SHORT_ON_STORAGEDFHSMSRX [CALL,][CLEAR,][IN,FUNCTION(INQUIRE_SHORT_ON_STORAGE),][OUT,SOS_ABOVE_THE_LINE(NO|YES),SOS_BELOW_THE_LINE(NO|YES),RES
Note!Before using this information and the product it supports, be sure to read the general information under “Notices” onpage xvii.Third edition (Mar
If your exit program is to be invoked at every global user exit point, you can code:DFHUEXIT TYPE=EP,ID=ALLIf your user exit program is to be used bot
lengths of the elements of task-lifetime storage belonging to either the specifiedtask or, by default, the current task. The lengths returned do not in
Trace control functionThere is one XPI trace control function. This is the DFHTRPTX call TRACE_PUT.DFHTRPTX calls cannot be used in any exit program i
call within a calling domain should specify a unique POINT_ID. This enablesyou to locate the origin of a trace call when examining a formatted trace.
name8The name of an 8-byte location to receive the name of the bridge exitprogram.BRIDGE_FACILITY_TOKEN(name4)returns a token that contains the addres
The DTR transaction definition provides common attributes for transactions that areto be dynamically routed and which do not have a specific transaction
name4The name of a 4-byte location that is to receive the current number ofactive user tasks, expressed as a binary value.(Rn) A register to receive t
The INQUIRE_TCLASS callThe INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Itspurpose is to provide current information about the spec
name4The name of a 4-byte location that is to receive the current maximumnumber of active tasks currently allowed for this transaction class,expressed
INQUIRE_TRANDEFDFHXMXDX [CALL,][CLEAR,][IN,FUNCTION(INQUIRE_TRANDEF),INQ_TRANSACTION_ID(name4 | string | ‘string’),][OUT,[BREXIT(name8),][CMDSEC(name1
CMDSEC(name1)returns, in a 1-byte location (name1), a value indicating whether commandsecurity checking is required for the transaction.YES Command se
UEPTCApoints to fetch-protect storage. Use of this field results in an abend ASRD atexecution time.UEPCSApoints to fetch-protect storage. Use of this fi
YES The UOW is to wait, pending recovery from the failure, to determinewhether recoverable resources are to be backed out or committed.INDOUBT_WAIT_TI
PARTITIONSET(name1)returns, in a 1-byte location (name1), the partitionset specified on thetransaction definition.KEEP The reserved name KEEP is specifie
RESSEC(name1)returns, in a 1-byte location (name1), a value indicating whether resourcesecurity checking is required for the transaction.NO Resource s
DISABLEDThe transaction definition is disabled.ENABLEDThe transaction definition is enabled.STORAGE_CLEAR(name1)returns, in a 1-byte location (name1), a
TCLASS_NAME(name8)returns the name of the transaction class to which the transaction belongs.name8The name of an 8-byte location to receive transactio
(Rn) A register to receive the size of the transaction work area, expressed asa binary value.RESPONSE and REASON values for INQUIRE_TRANDEF:RESPONSE R
The descriptions of the following parameters are the same as the correspondingparameters on the INQUIRE_TRANDEF function call.DTIMEOUTDYNAMICINITIAL_P
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
T A terminal input attach.TT A permanent transaction terminal attach.SUSPEND_TIME(name4 | (Rn))returns the length of time that the task has been in it
RESPONSE and REASON values for INQUIRE_TRANSACTION:RESPONSE REASONOK NoneDISASTER ABENDLOOPINVALID NoneEXCEPTION NO_TRANSACTION_ENVIRONMENTBUFFER_TOO_
Table 1. TCB indicators in DFHUEPAR (continued). DescriptionSymbolicvalue2-bytecodeDescriptionUEPTRP RP The ONC/RPC mode TCBUEPTSZ SZ The FEPI mode TC
RESPONSE and REASON values for SET_TRANSACTION:RESPONSE REASONOK NoneEXCEPTION NO_TRANSACTION_ENVIRONMENTUNKNOWN_TCLASSINVALID_TRANSACTION_TOKENDISAST
WRITE_JOURNAL DATADFHJCJCX [CALL,][CLEAR,][IN,FUNCTION(WRITE_JOURNAL_DATA),FROM(block-descriptor),JOURNALNAME(name8 | string | 'string' ) |J
RESPONSE and REASON values for WRITE_JOURNAL_DATA:RESPONSE REASONOK NoneEXCEPTION IO_ERRORJOURNAL_NOT_FOUNDJOURNAL_NOT_OPENLENGTH_ERRORSTATUS_ERRORDIS
Part 2. Customizing with initialization and shutdown programs© Copyright IBM Corp. 1977, 1999 391
392 CICS TS for OS/390: CICS Customization Guide
Chapter 4. Writing initialization and shutdown programsYou can write programs to run during the initialization and shutdown phases ofCICS processing.
system initialization parameter. The autoinstall user program is not invoked toallow the definitions to be modified. The programs are defined with the fo
First phase PLT programsPrograms that are to execute during the first quiesce stage of CICS shutdown arespecified in the first half of the PLT (before th
v On an immediate shutdown, CICS does not allow running tasks to finish andbackout is not performed until emergency restart. This can cause anunaccepta
However, if a PLT-definedshutdownprogram itself passes control to anotherprogram (via a link or transfer-control command), the program thus invokedexec
as if the exit program had not been invoked, and it is a valid option at most globaluser exit points. The exceptions are shown in the list of return c
PLT programs—general398CICS TS for OS/390: CICS Customization Guide
Part 3. Customizing with user-replaceable programs© Copyright IBM Corp. 1977, 1999 399
400 CICS TS for OS/390: CICS Customization Guide
Chapter 5. General notes about user-replaceable programsThe comments in this chapter apply to all the user-replaceable programs describedin Part 3 of
Assembling and link-editing user-replaceable programsThe source for the CICS-supplied user-replaceable programs is installed in theCICSTS13.CICS.SDFHS
Notes:1 This job stream uses the CICS-supplied procedure DFHASMVS to assembleand link-edit user-replaceable programs. The DFHASMVS procedure refers
Link-edit statements for DFHPEP.ORDER DFHEAI this CSECT is in SDFHLOAD(DFHEAI)ORDER DFHPEP this CSECT is in USERTEXT(DFHPEP)ORDER DFHEAI0 this CSECT i
User-replaceable programs and the storage protection facilityWhen you are running CICS with the storage protection facility, there are two pointsyou n
program, the program thus invoked executes according to the execution key(EXECKEY) defined in its program resource definition.ImportantYou are strongly
Chapter 6. Writing a program error programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5. Genera
program (via a link or transfer-control command), the program thus invoked isexecuted according to the execution key (EXECKEY) defined in its programre
v The program status word (PSW) at the time of the (current) abend, atPEP_COM_PSW. The full contents of PEP_COM_PSW are significant for abendcodes ‘ASR
DFHEISTG DSECT ,** Insert your own storage definitions here*DFHPCOM TYPE=DSECT************************************************************************
The sample programs and copy booksTwo source-level versions of the default program are provided: DFHPEP, coded inassembler language, and DFHPEPD, code
Chapter 7. Writing a transaction restart programThe transaction restart user-replaceable program (DFHREST) enables you toparticipate in the decision a
All the following conditions must be true for CICS to invoke the transaction restartprogram:v A transaction must be terminating abnormally.v The trans
XMRS_WRITEIndicates, in a 1-byte field, whether the transaction has issued any terminalwrite requests.The equated values for this parameter are:XMRS_WR
The CICS-supplied transaction restart programThe CICS-supplied default transaction restart program requests that the transactionbe restarted if:1. The
Chapter 8. Writing a terminal error programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5. Gener
When an abnormal condition occursWhen an abnormal condition associated with a particular terminal or line occurs, theterminal control program puts the
DFHTEP module and tables by means of the DFHTEPM and DFHTEPT macros,respectively. You can select the appropriate options in this sample program, andyo
recursive command (such as a TS command at exit point XTSEREQ). The exitsmost likely to be affected provide a recursion count parameter, UEPRECUR, tha
the operating environment by selecting the appropriate generation options andvariables. Because each error condition is processed by a separate routin
You should assign permanent TEBs to terminals that are critical to the network. Forthe remainder of the network, you can generate a pool of reusable T
1. Entry and initialization2. Terminal identification and error code lookup3. Error processor selection4. Error processing execution5. General exit6. C
processor, are to be performed. The common error bucket is processed by thespecific error processor. However, the thresholds of the common error bucket
TEPPUTTDUsed to output character or hexadecimal data to a user-defined transient datadestination.TEPTMCHKUsed by TEPINCR to determine whether the time
Sample terminal error program messagesThe messages logged to the transient data destination CSMT (or, optionally, to thedestination specified in the OP
six types, each identified by a unique message prefix. You can control the selectionof each type of message by using the appropriate parameters specified
This message contains the symbolic terminal ID of the device associated withthe error. This message can be suppressed by using the NOTID option.DFHTEP
to generate a sample error program and tables that include your user-writtenroutines. Some of the parameters specified in the DFHTEPM and DFHTEPTmacros
This macro indicates the end of user storage definitions. Its use is mandatory ifDFHTEPM TYPE=USTOR has been coded. If you use DFHTEPM TYPE=USTOR todefi
The following rules apply to return codes if a second user exit program sets adifferent return code value from that selected by the previous program:–
NOEXITSNo branches are taken to user routines.TIME|NOTIMEspecifies whether threshold tests are to be controlled over prescribed timeintervals. An examp
TID|NOTIDspecifies whether the symbolic terminal ID of the terminal associated withan error is to be recorded on the transient data destination.TIDThe
The macro required for a user “ENTRY” routine is:This macro must be immediately followed by user “ENTRY” routine code, startingwith the label “TEPENTR
to be logged to the TEPQ transient data destination. The CICS DSECTs are notprinted on the sample DFHTEP assembler-language listing. There are two err
DFHTEPT–generating the sample DFHTEP tablesThe following macros are required to generate the terminal error program tables:v DFHTEPT TYPE=INITIAL—to e
NOTIMETime threshold space is not reserved.DFHTEPT TYPE=PERMTID–assigning permanent terminal errorblocksThe DFHTEPT TYPE=PERMTID macro to define perman
CODE={errcode|BUCKET}identifies the error code referred to by the TYPE=PERMCODE|ERRCODEparameter. These codes are listed in Figure 22 on page 443. CODE
numberThe interval in units of one hundredth of a second. Parentheses are notrequired if this method is used. The maximum number must be less than8 64
DFHTEPT TYPE=BUCKET–using the error bucket for specificerrorsThe DFHTEPT TYPE=BUCKET macro is used to ensure that specific errorconditions are always ac
This example generates 10 terminal error blocks, one of which is reserved forthe terminal whose symbolic ID is TM02, and the other nine are reusable.
Global work area (GWA) sample exit programsThis set of sample programs shows you how to:v Enable a global user exit program and allocate a global work
Table 21. Supplied source files and macros (continued)Name Type Description LibraryDFHTEPCA Macro Assembler-languagecommunication areaCICSTS13.CICS.SDF
You generate the communication area DSECT by coding DFHTEPCATYPE=DSECT in your program. The layout of the communication area is shown inFigure 21.The
SIGNOFF (X'02')Call sign-off program.On entry to DFHTEP, the above flags represent the default actions set byDFHTACP. The write-abend bit (co
and DFHTACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message toCSMT; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or,rarely
L TCTTEAR,TCTLEPTE POINT TO ERROR TCTTEUSING DFHTCTTE,TCTTEARDROP TCTLEARL TCTLEAR,TCTTELEA POINT TO TCTLEUSING DFHTCTLE,TCTLEARAfter you have carried
TERMINAL ABNORMAL CONDITION LINE ENTRYDec Hex4 BYTES00TCTLEPSASTORAGE ACCOUNTING AREA44RESERVED88TCTLEPFL TCTLEPF2NOT USEDERROR FLAGS SPECIAL IND12 CT
DisplacementDec Hex Code Bytes Label Meaning0 0 4 TCTLEPSA Storage accountingRESERVED8 8 1 TCTLEPFL Error flags81 Message too long84 TCT search error8
Example of a user-written terminal error programThe “DFHTEP recursive retry routine” on page 446 is an example of the logic stepsnecessary to design a
DFHTEP recursive retry routine*ASM XOPTS(NOPROLOG NOEPILOG SP)************************************************************************* ** DFHTEP RECU
EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR)* Get statistics for this terminal* using TERMID passed in Commarea*MVC PCISAVE,A06TENI Sa
Most of the above information is obtained using EXEC CICS API commandssuch as:– INQUIRE SYSTEM– ASSIGN– ADDRESS– ASKTIME– FORMATTIME.v Uses the START
448 CICS TS for OS/390: CICS Customization Guide
Chapter 9. Writing a node error programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5. General n
Background to CICS-VTAM error handlingIn general, errors detected by CICS-VTAM terminal control are queued for handlingby a special task, the CICS nod
v There could be application-related activity to be performed when a node erroroccurs. For example, if a message fails to be delivered to a terminal,
v Status changes (for example, of TCTTE)v Clean-up work (cancel any associated transaction, end the VTAM session).The action flags can be set or reset
The node error table must be defined as a RESIDENT program. This makes it easyfor the NEP to find it (using a CICS LOAD request), and ensures that any c
The initial code first tests the internal error code passed from DFHZNAC to see if itbelongs to a group that the NEP needs to handle. (The groups are i
The code for non-SNA 3270s can be generated by codingDFHSNEP TYPE=DEF3270where you would otherwise code a DFHSNEP TYPE=ERRPROC macro plus logicof your
The DFHZNEPI macros (see “DFHZNEPI macros” on page 478) generate aDFHZNEP module that is purely a routing module. This inspects the NEPCLASS ineffect
When an abnormal condition occursThe following CICS components are involved when an abnormal condition isdetected from a logical unit:v The terminal c
DFH$PCPI is designed to be run as a PLT program. If you write a similar program,you should define it in the second part of the PLTPI list (after thePRO
When control is returned from DFHZNEP, DFHZNAC performs the actions specifiedin field TWAOPTL (except when disconnecting logical units, as noted above),
************************************************************************ Header **** These fields are READ ONLY **************************************
************************************************************************ VTAM information - Any VTAM sense and RPL codes **** These fields are READ ON
The next sections describe fields in the parameter list that can be reset withinDFHZNEP. See also “Coding for the 3270 ‘unavailable printer’ condition”
aids. The first five flags cause DFHZNAC to write the desired information to theCSNE log if the appropriate bit is set. Setting the sixth flag (TWAODNTA)
TWAOGMM (X'08')“good morning” message to be sentTWAOPBP (X'04')Purge any BMS pages for this sessionTWAOASM (X'02')SIMLOG
TWAOOS indicates that no further processing is to be done for this node. Thenode is logically out of service.For an LU6.1 intersystem communication se
This notification results in an informative message being issued, and causesDFHZNAC to invoke your NEP, whether the CLSDST request has failed orsucceed
v A general environment within which your error processing programs can beaddedv The default node error program in a system that has several node erro
Routing mechanismThe routing mechanism invokes the appropriate error processor depending on theerror code provided by the node abnormal condition prog
ContentsNotices ...xviiProgramming interface information ...xviiiTrademarks...xixPreface
DFH$FCBVA sample exit program designed to be invoked at the XFCBOVER exit; itallows you to decide whether to allow an update to be backed out, followi
Note: If you write your own node error program, you must generate a NET, even ifit contains no entries because your error processors do not use it.Opt
with an IC PUT command. Otherwise the default actions are taken. (For moredetails, see the section “Coding for the 3270 ‘unavailable printer’ conditio
DFHSNEP TYPE=USTOR and USTOREND—defining user storageThe DFHSNEP TYPE=USTOR macro has the following format:This macro indicates the start of user stora
TYPE=DEF3270specifies that the CICS-supplied error processors for 3270 logical units are tobe included in the node error program. This macro causes the
GROUP=error-group-indexspecifies an error group index for the error processor. This index is used toname the error processor, locate its address from t
4. Registers 4 through 9 can be saved by common subroutines in an areareserved in EXEC interface storage at label NEPCSRS. They must be restoredbefore
TIME=(7,MIN)|(interval,units)specifies the time interval that is to be stored in the NET header for use by thecommon subroutines to maintain error coun
DFHNEPC DSECTDS F Load instructionDS F Branch instructionCSVTNEP DS A Node error program base addressCSVTESBL DS A NEPESBL - ESB locate routineCSVTNEB
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 no
Before linking to the node error program, DFHZNAC inserts the primary andsecondary printer netnames and terminal IDs into the communication area,indic
The terminal-not-known sample exit programYou can use this sample global user exit program to handle terminal-not-knownconditions arising from START a
If used in this way, the initiated transaction can write an appropriate signonmessage when the session has been acquired. Note, however, that ifLOGONM
DFHZNEPI TYPE=INITIAL—specifying the default routineThe DFHZNEPI TYPE=INITIAL macro specifies the name of the defaulttransaction-class routine to be us
Handling shutdown hung terminals in the node error programError Code: X'6F'Symbolic Name: TCZSDASMessage Number: DFHZC2351For error code X&a
One of the steps in the conversation-restart process is to link to the node errorprogram with error code X'3F'. If you want to be able to ch
notification that service has been restored. To achieve this, you could codeRECOVNOTIFY(MESSAGE) in the TYPETERM definition, and then use the nodeerror
specific TOR within the CICS generic resource group, you must specify LUNAMEas the member name—that is, the CICS APPLID, as in the first example.)Note t
484 CICS TS for OS/390: CICS Customization Guide
Chapter 10. Writing a program to control autoinstall ofterminalsConsiderations common to all user-replaceable programsNote that the comments contained
For an overview of autoinstall, see theCICS Resource Definition Guide. You shouldalso read the sections in the same manual that describe the CEDA comma
Using model terminal support (MTS)CICS Transaction Server for OS/390 supports the model terminal support (MTS)function of VTAM 3.3 and above.Using MTS
Table 2. Alphabetical list of global user exit points (continued)Exit name Module ordomainWhere or when invoked PageXDSAWT DispatcherdomainAfter an op
described in “The communications area at INSTALL for shipped terminals” onpage 526 . The parameter list passed at INSTALL of client virtual terminals
For example, if a 3270 printer attempts to autoinstall, the subset of matchingmodels includes all the types in VTAM category 2 that you have defined as
How CICS builds the list of autoinstall modelsIf CICS finds an MTS model name (and the model is defined to CICS and iscompatible with the VTAM informati
VTAM characteristics of the device attempting to log on. The number in theright-hand column of the figure indicates the selection of the subset from th
before returning to CICS. If you need information about the formats and acceptablecharacter ranges for any of the return values, refer to theCICS Reso
bisynchronous devices, which do not support QUERY, one approach is to make thedefinition as straightforward as possible, with no special features.If yo
Using a table has two disadvantages, each of which loses you some of thebenefits of autoinstall: it takes up storage and it must be maintained. You cou
A suggested course of action is as follows:1. Determine whether a model such as ‘mmmmmmmm’ is suitable. If there areseveral models that have identical
1. Standard Header. Byte 1 indicates the request type. For deletion of localterminals (including APPC single-session devices installed via CINIT reque
parameter list in your test program, upon which operations can be performed.Running your program on a terminal before you use it properly means that y
Table 2. Alphabetical list of global user exit points (continued)Exit name Module ordomainWhere or when invoked PageXFCBFAIL File controlrecovery cont
Table 25. Autoinstall programs and copy books (continued)Language Member name Alias LibraryCopy books:AssemblerCOBOLPL/IC/370DFHTCUDSDFHTCUDODFHTCUDPD
Customizing the sample programHere are three pieces of code that customize the sample program.Assembler languageFigure 31, in assembler language, limi
COBOLFigure 32 on page 501, in COBOL, redefines the NETNAME, so that the last fourcharacters are used to select a more suitable model than that selecte
PL/IFigure 33 on page 502, in PL/I, extracts information from the VTAM CINIT RU,which carries the BIND image. Part of this information is the screen p
DCL 1 CINIT BASED(INSTALL_CINIT_PTR),2 CINIT_LENG FIXED BIN(15),2 CINIT_RU CHAR(256);DCL SAVE_CINIT CHAR(256);/* Temp save area for CINIT RU */DCL 1 S
/* Now access the screen PS area in the portion of the BINDimage presented in the CINIT RU *//* using the screen alternate height as a guide to the mo
504 CICS TS for OS/390: CICS Customization Guide
Chapter 11. Writing a program to control autoinstall ofconsolesConsiderations common to all user-replaceable programsNote that the comments contained
Using an autoinstall control programIf you choose to have your autoinstall control program invoked for consoles, followthese steps:v Use the default a
The communication area at INSTALL for consolesThe layout of the communication area is shown in Figure 34.The parameter list contains the following inf
Table 2. Alphabetical list of global user exit points (continued)Exit name Module ordomainWhere or when invoked PageXISCONA Intersystemcommunicationpr
How CICS builds the list of autoinstall modelsCICS builds the list of autoinstall models by selecting from its complete list ofterminal models those m
If you want an INSTALL request to proceed, perform these steps in your autoinstallcontrol program:v Return an autoinstall model name in the first 8 byt
CICS action on return from the control programWhen CICS receives control back from the autoinstall control program, it examinesthe return code field:v
The sample programs and copy booksIBM supplies a default autoinstall control program, written in each of the supportedprogramming languages, all of wh
512 CICS TS for OS/390: CICS Customization Guide
Chapter 12. Writing a program to control autoinstall of APPCconnectionsConsiderations common to all user-replaceable programsNote that the comments co
Local APPC parallel-session and single-session connections initiatedby BINDIf autoinstall is enabled, and an incoming APPC BIND request is received fo
DFHZATDX, described in “Chapter 10. Writing a program to control autoinstall ofterminals” on page 485. Thus, you can use a customized version of DFHZA
described in “The communications area at INSTALL for shipped terminals” onpage 526 . The parameter list passed at INSTALL of Client virtual terminals
INSTALL_APPC_EXIT_FUNCTIONA 1-byte field that defines the install request type. The equated valuesare:INSTALL_APPC_PS_CINITX'F2' represents an
Table 2. Alphabetical list of global user exit points (continued)Exit name Module ordomainWhere or when invoked PageXRMIIN Resourcemanager interfacepr
X'0001'Synclevel 1X'0002'Synclevel 2.INSTALL_APPC_TEMPLATE_NETNAME_PTRA fullword pointer to an 8-byte input/output area (TEMPLATE_
partner. This field is set whenever the local CICS is registered as a genericresource. At all other times it has a value of 0.INSTALL_APPC_GR_TYPE_PTRA
When autoinstalled APPC connections are deletedAny autoinstalled APPC connection entry is deleted if the connection is discarded(using the CEMT DISCAR
The actions taken by the supplied version of the program are to:1. Examine the request type passed in the INSTALL_APPC_EXIT_FUNCTIONfield:X'F0&apo
DFHZATDY is defined as follows in DFHAI62:DEFINE PROGRAM(DFHZATDY)DESCRIPTION(Assembler definition for sessions autoinstall control program)GROUP(DFHAI
Chapter 13. Writing a program to control autoinstall ofshipped terminalsConsiderations common to all user-replaceable programsNote that the comments c
CICS-generated aliasesThe autoinstall control program is invoked once for each shipped terminal orconnection definition to be installed.If CICS detects
v Whether your application programs record TERMIDs for later use. For example,an application might issue an EXEC CICS START TERMID command, with atime
INSTALL of local terminals and APPC single-session connections initiated by CINITis described in “The communication area at INSTALL for terminals” on
INSTALL_SHIPPED_CLASHA 1-character input field that indicates whether the TERMID of the shippeddefinition is already in use in the AOR.Y The name by whi
Table 2. Alphabetical list of global user exit points (continued)Exit name Module ordomainWhere or when invoked PageXXDFB DBCTL trackingprogramIn the
INSTALL_SHIPPED_CORRID_PTRA fullword pointer to an 8-character input field containing the shipped definition’scorrelation identifier. A correlation ident
DELETE_SHIPPED_EXIT_FUNCTIONA 1-byte field that indicates the type of resource being deleted. The equatedvalues are:DELETE_SHIPPED_TERM (X'FA&apos
530 CICS TS for OS/390: CICS Customization Guide
Chapter 14. Writing a program to control autoinstall of Clientvirtual terminalsConsiderations common to all user-replaceable programsNote that the com
Terminal identifiersThe terminal identifier (TERMID) passed to the CICS autoinstall function at install ofa virtual terminal is determined using the fol
Why override TERMIDs?Why might you want to create an alias for the supplied TERMID (or, in the case ofa clash of names, to override the alias generate
Overriding Client-specified TERMIDsIf TERMIDs are always nominated, in a consistent way, by your Client EPIprograms, the problem of data mismatch due t
INSTALL_SHIPPED_STANDARDA fullword input field containing the following information:INSTALL_SHIPPED_EXIT_FUNCTIONA 1-byte field that indicates the type
long, it must be padded with trailing blanks. For a list of the charactersyou can use in terminal names, see theCICS Resource DefinitionGuide.On invoca
At DELETE, all fields in the communications area are input only. Fields not listedbelow are as described for INSTALL.DELETE_SHIPPED_EXIT_FUNCTIONA 1-by
Activity keypoint program exit XAKUSERThe XAKUSER exit is invoked during the activity keypointing process. You can usethis exit to record, on the syst
2. Permits the remote definition to be installed by leaving the return code field setto its default value of RETURN_OK, and returning.When DFHZATDX or D
Chapter 15. Writing a program to control autoinstall ofprogramsConsiderations common to all user-replaceable programsNote that the comments contained
v CICS calls any user-replaceable program other than the program or terminalautoinstall program.v A program is named in the PLTPI or PLTSD list.Autoin
Autoinstall processing of mapsetsTable 26 shows the differences in mapset processing between CICS regions withprogram autoinstall active and inactive.
Faster startup timesWarm and emergency startsIf you are using program autoinstallwith cataloging, restart times are similar tothose of restarting a CI
The autoinstall control program at INSTALLOn invocation, CICS passes a parameter list to the autoinstall control program bymeans of a communication ar
If you do not set this field, the autoinstall routine uses the language defined inthe model, if one is specified. However, when control is passed to the
PGAC_LPA_NOCICS is to load a private copy from its own DFHRPL libraryconcatenation.PGAC_EXECUTION_SETallows you to specify, in a 1-byte field, whether
named explicitly on the SYSID option of the EXEC CICS LINKcommand, the routing program can route the request to the region onwhich the program is to e
v You can discard definitions after they have been installed; they are reinstalledwhen next referenced.v You must ensure that the parameters you return
WRITE JOURNALNAME.ImportantOnly the listed EXEC CICS commands are allowed in the XAKUSER exit. Theexit should link only to other programs with the sam
v Autoinstall control program definition for DFHPGAOX. This defines theCICS-supplied COBOL version, and its status is set to DISABLED:GROUP(DFHPGAIP) PR
Chapter 16. Writing a dynamic routing programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5. Gen
4. “Naming your dynamic routing program” on page 5735. “Testing your dynamic routing program” on page 5736. “Dynamic transaction routing sample progra
v If the routed transaction abends, if the routing program has requested to bereinvoked at termination.Figure 43 shows the points at which the dynamic
Sometimes, the dynamic routing program may be invoked for transactions that arerouted statically. This happens if a transaction defined as DYNAMIC(YES)
which transactions are to be routed. For information about defining remotetransactions for dynamic transaction routing, see theCICS IntercommunicationG
If you want to terminate the transaction without issuing a message or abend, set areturn code of X'4'.Warning: Setting a return code of X&ap
Invoking the dynamic routing program on abendIf you have set DYROPTER to 'Y', and the routed transaction abends, the dynamicrouting program
may also need to change the input communications area passed to the routedapplication. Field DYRACMAA of the routing program’s communications areaenab
v If you want to keep information about how transactions are routed, it must bedone in the user routing program, perhaps by writing the information to
Basic Mapping Support exits XBMIN and XBMOUTThe XBMIN exit allows you to intercept a RECEIVE MAP request after BMS hassuccessfully processed the reque
– The CICS Gateway for Java™v Calls from external CICS interface (EXCI) client programsv External Call Interface (ECI) calls from any of the CICS Clie
v If an abend is detected after the link request has been shipped to the specifiedremote system, if reinvocation was requested by the routing program.F
When it is invoked for routing9(not for notification of a statically-routed request),your routing program can, by overwriting the DYRLPROG field, specif
If an error occurs in route selectionIf an error occurs in route selection—for example, if the SYSID returned by thedynamic routing program is unavail
this; it is a pointer to the application’s communications area (or null, if nocommunications area was specified on the LINK command).Monitoring the app
DS OCL4 Standard headerDYRFUNC DS CL1 Function codeDYRCOMP DS CL2 Component codeDYRFILL1 DS CL1 ReservedDYRERROR DS CL1 Route selection error codeDYRO
ImportantThe same communications area is passed to both the dynamic routingprogram and the distributed routing program. Some parameters aremeaningful
Your routing program can alter the data in the application’s communicationsarea.DYRACMALis the length of the routed-to application’s communications ar
There is no default value.DYRCOMPis the CICS component code. For calls to the dynamic routing program, it isalways set to 'RT'.DYRCOUNTis a
For an explanation of the DTRTRAN system initialization parameter, see theCICS System Definition Guide.DYRERRORhas a value only when DYRFUNC is set to
Exit XBMIN ...28Exit XBMOUT ...28The field element table structure ...29Programming the XBMIN
Sample program, DFH$BMXTCICS supplies a sample program, DFH$BMXT, that shows how mapped inputand output data can be modified with reference to the info
2 Invoked because a previously routed transaction or program-linkrequest has terminated successfully.3 Invoked for notification of the destination of a
You can change DYRLPROG on any call to the dynamic routing program, but itis effective only when DYRFUNC is ‘0’ or ‘1’.DYRNETNMis the netname of the C
Transaction routingThe possible values are:0 Continue processing the transaction.4 Terminate the transaction without message or abend.8 Terminate the
DYRSYSIDis the system identifier (sysid) of a CICS region. The exact meaning of thisparameter depends on the values of DYRFUNC and DYRTYPE:v When DYRFU
v When DYRFUNC is set to ‘4’ (abend), DYRSYSID contains the name of theCICS region on which the transaction abended.DYRTRANcontains the remote transac
Naming your dynamic routing programThe supplied, user-replaceable dynamic routing program is named DFHDYP. If youwrite your own version, you can name
Dynamic transaction routing sample programsThe CICS-supplied sample dynamic routing program is named DFHDYP. Thecorresponding copy book that defines th
Chapter 17. Writing a distributed routing programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5.
6. “Distributed transaction routing sample programs” on page 593.Differences from the dynamic routing interfaceThis section discusses some significant
v Select a target region by supplying a netname (any value set in theDYRNETNM field of the communications area is ignored). The target must bespecified
UERCPURGTask purged during XPI call.XPI callsAll can be used.The field element table structureThefield element tablecontains one or more elements which
When the distributed routing program is invokedFor BTS processes and activities started by RUN ASYNCHRONOUS commands,CICS invokes the distributed rout
Changing the target CICS regionThe DYRSYSID field of the communications area passed to the distributed routingprogram initially contains the system ide
2. You can tell CICS to treat the request as “unserviceable”, by issuing a non-zeroreturn code in DYRRETC.Sometimes, perhaps because of a transaction
Note that, because the routing program is distributed, all the CICS regions in thetransaction routing set must have access to the data set.v The distr
When the distributed routing program is invokedFor non-terminal-related START requests that are eligible for enhanced routing,CICS invokes the distrib
Changing the target CICS regionThe DYRSYSID field of the communications area passed to the distributed routingprogram initially contains the system ide
If an error occurs in route selectionIf an error occurs in route selection—for example, if the sysid returned by thedistributed routing program is una
v The distributed routing program can be RMODE ANY but must be AMODE 31.Parameters passed to the distributed routing programFigure 48 shows the commun
ImportantThe same communications area is passed to both the distributed routingprogram and the dynamic routing program. Some parameters are meaningful
This field applies only to the routing of BTS processes and activities,notto therouting of non-terminal-related START requests.DYRACTNis the name of th
control, the TIOA is disposed of in accordance with the disposition of theTERMINAL (the default), SET, or PAGING option specified on the SEND MAPreques
2. CICS rejected the allocate request automatically because theQUEUELIMIT value specified on the CONNECTION resourcedefinition has been reached.4 A queu
For detailed information about which non-terminal-related STARTrequests are eligible for dynamic routing, see theCICSIntercommunication Guide.4 Invoke
This field applies only to the routing of BTS processes and activities,notto therouting of non-terminal-related START requests. Its contents are signifi
DYRRTPRIindicates whether or not the dispatch priority of the transaction should bepassed to the application-owning region, if the connection between
v When DYRFUNC is set to ‘5’ (transaction initiation), DYRSYSID contains thename of the target region on which the routed request is to be executed.(T
DYRVERis the version number of the dynamic routing interface. For CICS TransactionServer for OS/390 Release 3, the number is “5”.Naming your distribut
If you want to route requests dynamically, you must customize DFHDSRP, orreplace it completely with your own routing program.sample distributed routin
Chapter 18. Writing a CICS–DBCTL interface status programConsiderations common to all user-replaceable programsNote that the comments contained in “Ch
The parameter list contains the following information:DBUREQTRequest Type. The function code has one of the following values:DBUCONN (X'01')
The sample contains an example, as part of a comment, of how to enable and howto disable a transaction. To use the program, it is necessary for transa
The actual data length (in BMXACTLN) may be less than the length defined in themap (in BMXMAPLN). This occurs due to the compression of trailing nullsp
598 CICS TS for OS/390: CICS Customization Guide
Chapter 19. Writing a 3270 bridge exit programConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter 5. Ge
600 CICS TS for OS/390: CICS Customization Guide
Chapter 20. Writing a security exit program for IIOPConsiderations common to all user-replaceable programsNote that the comments contained in “Chapter
602 CICS TS for OS/390: CICS Customization Guide
Chapter 21. Writing a program to tailor JVM executionenvironment variablesConsiderations common to all user-replaceable programsNote that the comments
CICS_PROGRAMContains the name of the CICS program (1-8 characters) associated with theJava class to be run. No value is set in SDFHENV. This name is e
MAXHEAPSIZESets the maximum heap size for the JVM, in bytes. A default value of 8000000bytes (8M) is set in SDFHENV. This is the recommended default f
606 CICS TS for OS/390: CICS Customization Guide
Part 4. Customizing the XRF overseer program© Copyright IBM Corp. 1977, 1999 607
Bridge facility exitWhen enabled, XFAINTU (Facility Initialization and Tidy Up) is called:v Just after a new bridge facility has been built.v Just bef
A general note about user-written programsOn return from any user-written program, CICS must always receive control inprimary-space translation mode,
Chapter 22. The extended recovery facility overseer programThe information in this chapter is of interest only to users of the extended recoveryfacili
Snapto take a snap dump of the sample programEndto terminate the sample programOpento ask the overseer to try to open CICS availability manager (CAVM)
which was in an intermediate state when the Display command wasprocessed. Reissuing the Display command causes UNKN to bereplaced by another status va
related regions to be taken over, because the new active region can continuecommunication with the other active regions. Takeover is therefore likely
Opening CAVM data sets dynamicallyWhen the overseer program is initialized, it is possible that some CAVM data setshave not yet been formatted by a CI
each active-alternate pair. You create this data set and initialize it with informationabout active-alternate pairs before you use the overseer for th
DFHWOSM FUNC=READRetrieve status information for a named generic applid from the CAVM datasetsDFHWOSM FUNC=TERMClose communication with DFHWOS.The mac
Register 15Contains one of the following completion codes:0 Communication successfully initialized between the overseerprogram and DFHWOS4 Incorrect T
v An 8-byte JES job IDv A 256-byte SSOB return area.The TOKEN value is the ENTRY token.OutputRegister 15Contains the following completion codes:0 JES
Data tables management exits XDTRD, XDTAD, and XDTLCThese exits apply to both:v CICS shared data tablesv CICS coupling facility data tables.XDTRD and
NonzeroReturn code from JES.DFHWOSM FUNC=OPEN macroThe DFHWOSM FUNC=OPEN macro initializes access to the CAVM data sets for anamed generic applid.Inpu
the required MVS command is provided as input to the macro, and the OSCMDservice issues an SVC 34 specifying this command text. In addition, the OSCMD
Parameter list pointerGeneric ApplidAddress Generic ApplidDBLLIST AddressOUTPUT INPUT OUTPUTItem 1 address DBLID 1 Item 1 lengthItem 2 address DBLID 2
Notes:1. The data structures of the status information pointed to by items X'0024' andX'0124' are provided in DSECT DFHXRHDS of CI
Reading DBCTL status information from the CAVM data setsIf you are using DBCTL and have active and alternate DBCTL subsystems, statusinformation about
OutputRegister 15Contains the following completion codes:0 Communication terminated successfullyNonzeroRequest failed.Customizing the sample overseer
v To extend the function of the overseer program, you can incorporate the CEBTcommand, which is normally issued by the console operator to control the
To include this LOOP WARNING code, set the variable &LOOPWARN to ‘1’ andreassemble the sample.Assembling and link-editing the overseer programThe
626 CICS TS for OS/390: CICS Customization Guide
Part 5. CICS journaling, monitoring, and statistics© Copyright IBM Corp. 1977, 1999 627
This normally occurs when the loading process retrieves a record during thesequential copying of the source data set. However, it can also occur when
A general note about user-written programsThe following comment applies to all user-written programs mentioned in Part5 of this book:v Upon return fro
Chapter 23. CICS logging and journalingThe CICS log manager provides facilities for the creation, control, and retrieval ofjournals during real-time C
3. Tertiary storage—a form of archive storage, used as specified in yourhierarchical storage manager (HSM) policy. Optionally, older records can bemigr
Enabling, disabling, and reading journalsJournal records are written to a log stream either directly from a user applicationprogram, or from a CICS ma
Reading journal records offlineAccess to journaled data in log streams is provided through an MVS subsysteminterface (SSI), LOGR. Your existing user p
Server for OS/390 Release 1. Each journal record in these logs, if presented in thenewer format, contains more information than in the equivalent jour
Format of general log block headerThe log block header contains information of a general system-wide nature such asthe CICS applid writing the journal
Format of general log journal recordThe journal record comprises a record header followed by caller data. The recordheader contains information that d
Start-of-run recordWhen CICS connects to a general log, it writes a start-of-run record to it as the firstrecord for this run of CICS. This record comp
Caller data written by file controlThe file log and journal block (FLJB) describes the caller data that file control writesas part of its journal records
UEPDTCFT(X'10')The exit has been invoked by coupling facility datatable support.UEPDTUMT (X'08')This is a user-maintained table. O
v The FLJB_COMMON_DATA section, andv The caller data image sections which consist of the FLJB_CD_KEY (the length ofwhich is given in FLJB_COMMON_DATA)
The format of the FLJB_COMMON_DATA section is shown in Figure 62 .11Fixed length82Record type Flag byteX'80' file control autojournal record
Write-delete record typesThere are four sections in the journal records written for write-delete record types:v The FLJB_GENERAL_DATA section,v The FL
File-close record typesThere are two sections in the journal records written for file-close record types:v The FLJB_GENERAL_DATA sectionv The FLJB_CLOS
Tie-up record typesThere are two sections in the journal records written for tie-up record types:v The FLJB_GENERAL_DATA sectionv The TIE_UP_RECORD_DA
44421126244442FLJB TUR BITSFixed lengthFixed lengthFixed lengthFixed lengthLog stream name of forward recovery logFLJB TUR FWDRECOVLOG NAMEFLJB TUR PA
Note: The format of caller data in journal records written by file control in RLSmode is identical to that in journal records written by file control in
See theCICS Front End Programming Interface User’s Guidefor more informationabout FEPI journaling.Structure and content of COMPAT41-format journal rec
A graphical overview of the format of a general log, showing the format of acomplete block, is shown in Figure 71.Format of COMPAT41 journal control l
The label prefix part of the journal control label header is 32 bytes long, and itsformat is shown in Figure 74.Record numberwithin blockJCRLRNLength o
Exit XDTADThe 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
Format of journal recordEach CICS journal record comprises a system header, system prefix, user prefix,and journaled data. The format of a journal recor
The field JCRSTRID (the system-type ID) and the field JCRUTRID (the user-typeID) in the system header allow you to distinguish those journal records out
command via the JTYPEID, PREFIX, and PFXLENG parameters. Its format isshown in Figure 78.Field JCSPUP is set in the system prefix area if a user prefix
************************************************************************* FUNCTION IDENTIFIERS *******************************************************
************************************************************************ TERMINAL CONTROL FUNCTION IDENTIFIERS ** *FIDTCML EQU X'F0' SYNCPOI
Identifying records for the start of tasks and UOWsYou can identify records written to mark the start of tasks by examining the value ofthe system pre
The SMF block headerThis block describes the system creating the output. Its format is shown inFigure 82.Note: CICS sets only the subsystem-related bi
The CICS data sectionThis section contains a variable number of CICS journal records. Each recordcomprises a general log record header, the format of
656 CICS TS for OS/390: CICS Customization Guide
Chapter 24. CICS monitoringThis chapter describes the monitoring facilities of CICS Transaction Server forOS/390, and tells you how to:v Control the t
UEPDTRLThe fullword length of the data record.UEPDTKAThe address of the data table key.UEPDTKLThe fullword length of the data table key.UEPDTDSLThe fu
You can choose which classes of monitoring data you want to be collected. How todo this is described in “Controlling CICS monitoring” on page 662.Perf
v To tell CICS that you want specific system-defined performance data not to berecorded during a particular CICS run. See “DFHMCT TYPE=RECORD”.Full deta
also has its own numeric identifier that is unique within the group identifier. Forexample, the transaction sequence number field in a performance record
Example 3:Example 3 shows 32 bytes of user data being updated in the character stringreserved for that purpose. The updated data starts at offset 0, a
v Wait for temporary storage data set extensionv Wait for shared temporary storagev Wait for shared temporary storage poolv Wait for file stringv Wait
When CICS is running, you can control the monitoring facility dynamically. Just asat CICS initialization, you can switch monitoring on or off, and you
The label ‘MNSMFDS’ is the default DSECT name, and SMF is the default PREFIXvalue, so you could also generate the DSECT simply by coding:DFHMNSMFThe M
Notes:1. CICS sets only the subsystem-related bits of the operating system indicator flagbyte in the SMF header (SMFMNFLG). SMF sets the remainder of t
CICS data sectionThe CICS data section can be made up of a dictionary data section, a performancedata section, or an exception data section. You can i
Whenever the monitoring of performance class data is switched on, whether atCICS initialization or while CICS is running, a dictionary data section is
Modifying user arguments ...95File control file state program exits XFCSREQ and XFCSREQC ...96Exit XFCSREQ ...97
UEPDTCMT (X'40')This is a CICS-maintained table. Only meaningful ifUEPDTSDT is on.UEPDTCFT(X'10')The exit has been invoked by coup
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAMEDFHTASK C001 4 X'0001' X'0000' TRANDFHTERM C002 4 X'0002' X'0004' TER
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAMEDFHSTOR A117 4 X'0033' X'01C4' SCCGETCTDFHSTOR A120 4 X'0034' X'01C8'
FIELD-NAME SIZE CONNECTOR OFFSET NICKNAMEDFHTASK A059 4 X'0066' X'02A0' ICPUINCTDFHTASK A066 4 X'0067' X'02A4'
Note: The “field types” in Figure 88 are:A CountC Byte-stringP Packed decimal numberS ClockT Time stamp.FIELD-NAME SIZE CONNECTOR OFFSET NICKNAMEDFHTAS
Performance data sectionsEach performance data section is made up of a string of field connectors, followedby one or more performance data records. All
How the string of field connectors is constructed:When CICS is initialized, aunique connector value is assigned to every dictionary entry. CICS then ex
Exception data sectionsThe format of an exception data record (including the SMF header and SMFproduct section) is shown in Figure 91. The exception d
For further information about exception class data, see theCICS PerformanceGuide, which lists all the system-defined data that can be produced by CICSm
676 CICS TS for OS/390: CICS Customization Guide
Chapter 25. CICS statisticsThis chapter is divided into the following sections:1. “Introduction to CICS statistics” describes the types of statistics
DBCTL interface control program exit XXDFAWhen invokedBy an active CICS when its connection to DBCTL fails. Your exit program isinvoked after the acti
orv The RECORDING option of the EXEC CICS SET STATISTICS command isset to ON.The TS data sharing server writes interval statistics if statistics recor
v EXEC CICS SET STATISTICS ON|OFF RECORDNOW.CICS writes requested statistics to SMF even if, on one of the following, youhave specified OFF:v The STATR
If an autoinstall terminal logs on again before the expiry of the delayinterval, then the accumulation of statistics continues until the nextinterval.
System dumpsWhenever a system dump table entry is deleted, CICS collects thestatistics covering the period since the last interval.TCP/IP servicesWhen
ImportantStatistics counters are reset in various ways. Specific counters may be resetto:v 0v 1v A new peak valuev Not resetv None of the above.For inf
SMF header and SMF product sectionThe SMF header describes the system creating the output. The SMF productsection identifies the subsystem to which the
Notes:1. CICS sets only the subsystem-related bits of the operating system indicator flagbyte in the SMF header (SMFSTFLG). SMF sets the remainder of t
3. Fields SMFSTINT and SMFSTINO are only relevant if SMFSTRQT is ‘INT’.Otherwise both values should be ignored.4. For TS data sharing, the record subt
on page 682. For further guidance information about the fields within thestatistics data records, see theCICS Performance Guide.STIVERStakes the value
The coupling facility data table server statistics use no symbolic names, but relateto the STID values as follows:The named sequence number server sta
DBCTL tracking program exits XXDFB and XXDTOExit XXDFBWhen invokedBy the alternate CICS when it receives a message from the active CICSindicating that
Processing the output from CICS statisticsThere are several utilities to help you process statistics output. You can use:The CICS-supplied DFHSTUP pro
Part 6. Customizing CICS compatibility interfaces© Copyright IBM Corp. 1977, 1999 689
A general note about user-written programsThe following comment applies to all user-written programs mentioned in Part6 of this book:v Upon return fro
Chapter 26. Using TCAM with CICSThis chapter describes the use of the telecommunications access method (TCAM)with CICS Transaction Server for OS/390 R
CICS with TCAM SNAThe CICS-TCAM interface has an enhanced data stream support that enables anappropriate TCAM message control program (MCP) to control
Transaction controlIn the transaction control method of protocol management, the transaction controlsthe protocol. The SNA session should be bound wit
Batch processingWhen running a batch logical unit, a point to consider is how to get the transactionidentification to CICS on the “begin data set” cond
each output queue from CICS. In CICS, there are corresponding terminal controltable line entries (TCTLEs) for each input queue, and for each output qu
The CICS terminal control table terminal entries (TCTTEs) define the terminalsassociated with a particular line entry (TCTLE). For each physical termin
For information about the DFHTCT macros, see theCICS Resource DefinitionGuide.Logic flowThe following is a generalized description of the sequence of ev
Exit XXDTOWhen invokedBy an alternate CICS when it performs takeover under the followingconditions:v The active and alternate CICS systems are in diff
OUTPUT STEPACTIONA You issue an EXEC CICS SEND request in your application program.B The TCP terminal scan recognizes the SEND request.C CICS checks w
Terminal error programThe CICS-TCAM interface implementation has resulted in the expansion of theCICS terminal error program (DFHTEP) error codes and
Table 32. DFHTEP error codes and conditions unique to TCAMError code Condition ActionX'87'(TCEMCUI) Unsolicited inputTerminal ‘receive only’
The possible values of TCTTETCM are:Value Message segmentX'00' NullX'40' Intermediate portion of messageX'F1' First port
locked until a TCTTE becomes available because the task has ended. The numberof TCTTEs in the pool influences the degree of multitasking.You should con
permanently locked.TCAM queuesBecause a queue is a sequential data set, the second message on the queuecannot be retrieved until the first message has
To allow processing of input to continue, DFHTEP may take either of the followingsteps:v If the input line is placed in service by DFHTEP, the CICS-TC
The terminal services parameters that do not set bits in the communication controlbyte are SEND, WAIT TERMINAL, and SAVE. Bits in the communication co
Device-dependent dataDependent on the device: 3270, or other. See the following sections on therelevant devices.FMH Function management header.SNA onl
TCAM user exitsThere are three TCAM global user exit points:1. XTCATT, invoked before issuing a transaction manager ATTACH for atransaction identificat
Dispatcher domain exits XDSBWT and XDSAWTThe XDSBWT and XDSAWT exit points are located before and after the operatingsystem wait. CICS services cannot
CICS-TCAM terminationCICS is terminated in the normal manner. No modifications to terminationprocedures are required to support the CICS-TCAM interface
CICS and TCAM: program interrelationshipFigure 104 illustrates the interrelationship between the TCAM message controlprogram (MCP) and the TCAM applic
TCAM message control program (non-SNA)This section gives an example of a non-SNA TCAM message control program. ThisMCP shows the relationship between
S75A TERMINAL QBY=T,DCB=PG3270,RLN=1,TERM=327R,QUEUES=MO, *ADDR=E2E240402D,NTBLKSZ=1856POLLST1 INVLIST ORDER=(TRM1+02)POLLST2 INVLIST ORDER=(TRM2+02)P
712 CICS TS for OS/390: CICS Customization Guide
Chapter 27. The dynamic allocation sample programThis chapter suggests ways in which you can customize the dynamic allocationsample application progra
v Have read the relevant sections of theMVS/ESA SPL: Application DevelopmentGuideand have that manual available for reference while using the samplepr
Help featureThe program includes a limited “help” feature, driven by the program’s keywordtable.In response to “?”, the verb keywords are displayed. I
Maximum and minimum lengthsFor character and numeric values, the maximum and minimum lengths of thevalue are checked by the program. For a fixed-length
The flow of control when a DYNALLOC request is issuedThe flow in a normal invocation is as follows. The main program, DFH99M, receivescontrol from CICS
still exceeds the count of SYSEVENT OKSWAPs.Further SYSEVENT OKSWAPs must be requestedbefore a SYSEVENT OKSWAP is issued by CICS.Return codesUERCNORMC
returned value corresponds to a keyword value, DFH99KR is called to look up thevalue in the description, and issue the message.Processing of the comma
Part 7. Customizing CICS security processing© Copyright IBM Corp. 1977, 1999 719
General notesThe following comments apply to the chapters in Part 7 of this book:v The only aspects of CICS security processing covered are:– Invoking
Chapter 28. Invoking a user-written external security managerCICS provides an interface to an external security manager (ESM), which may beuser-writte
The MVS router exitThe MVS router provides an optional installation exit that is invoked whether or notRACF is installed and active on the system. If
Router exit return codesYour exit routine must return a return code in register 15. The hexadecimal valuesof the return code are shown in Table 35.Tab
How ESM exit programs access CICS-related informationWhen CICS invokes the ESM, it passes information about the current CICSenvironment, for use by an
Table 37. Obtaining the address of the installation data parameter listRACROUTEREQUEST typeRACF exit Exit list mappingmacroParameter list fieldnameVERI
UXPBLKIDThe name of the block identifier (UXPARMS).UXPPHASEAddress of a 1-byte code that indicates the reason for the call to the ESM(that is, the secu
USER_RESOURCE_CHECK (X'60')Resource checking for userLINK_RESOURCE_CHECK (X'61')Resource checking for linkUSER_QUERY_CHECK (X&apos
DL/I interface program exits XDLIPRE and XDLIPOSTThe XDLIPRE and XDLIPOST exit points are invoked following the issue of anEXEC DLI command or DL/I ca
RACROUTE REQUEST=VERIFYIssued at operator signon (with the parameter ENVIR=CREATE), and at sign-off(with the parameter ENVIR=DELETE). This macro creat
v After a call to FASTAUTH indicates an access failure that requires logging.v When a QUERY SECURITY request with the RESCLASS option is used.This ind
APPLThe APPLID of the CICS region on which the user is signing on. Which APPLIDis passed depends on what is specified as system initialization paramete
INCLUDE SYSLIB(DFHXSEAI)INCLUDE SYSLIB(DFHEAI)ORDER DFHEAI,verify-program,DFHEAI0ENTRY verify-programThe DFHEIENT and DFHEIRET macros are inserted by
732 CICS TS for OS/390: CICS Customization Guide
Chapter 29. Writing a “good night” programYou can use the GNTRAN system initialization parameter to specify a “good night”transaction that you want CI
GNTRAN_START_TRANSIDThe identifier of the transaction that started the “good night” transaction. If itwas started by CICS because of a terminal timeout
GNTRAN_PSEUDO_CONV_TRANSIDThe identifier of the next transaction, if the terminal timed out during apseudoconversational sequence. (If the terminal did
What the sample program doesThe DFH0GNIT sample program:1. Checks that it has been invoked for a terminal timeout, by testing theGNTRAN_START_TRANSID
v Your program should always start, like the sample program, by testing theGNTRAN_START_TRANSID field of the communications area passed by CICS.If it fi
Exit XDLIPREWhen invokedOn entry to the DL/I interface program.Exit-specific parametersUEPCTYPEAddress of type-of-request byte. Values are:UEPCEXECThe
sample good night program738CICS TS for OS/390: CICS Customization Guide
Part 8. Examining and modifying resource attributes© Copyright IBM Corp. 1977, 1999 739
A general note about user-written programsThe following comment applies to all user-written programs mentioned in Part8 of this book:v Upon return fro
Chapter 30. User programs for the system definition utilityprogram (DFHCSDUP)This chapter tells you how to write programs for use with the CICS system
DFHCSDUP as a part of the resource definition process is described in theCICSResource Definition Guide. Guidance information about the execution JCL for
v The names of all the resource definitions within the specified groupv The names of all the groups within the specified list.2. If you specify the OBJEC
0 Initial call2 List start call4 Group start call6 Object start call8 Keyword detail call10 Object end call12 Group end call14 List end call16 Final c
Table 39. Sample EXTRACT user programs for the DFHCSDUP utility programProgramnamesLanguages DescriptionDFH$CRFADFH0CRFCDFH$CRFPAssemblerVS COBOL IIPL
The program must be run against an EXTRACT command of the form:EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name)or:EXTRACT LIST(list name) O
The program must be run against an EXTRACT command of the form:EXTRACT GROUP(group name) OBJECTS USERPROGRAM(program-name)or:EXTRACT LIST(list name) O
UEPIOAXAddress of I/O area existence flag byte:UEPIOA1I/O area exists.For UEPCSHIP requests, the I/O area existence flag isalways off.UEPIOAAddress of I
An assembler-language versionThe sample job in Figure 107 shows the link-edit statements you need for anassembler-language version of a DFHCSDUP user
A VS COBOL II versionThe sample job in Figure 108 shows the link-edit statements you need for a VSCOBOL II version of a DFHCSDUP user program.Notes fo
A PL/I versionThe sample job in Figure 109 shows the link-edit statements you need for a PL/Iversion of a DFHCSDUP user program.Notes for the PL/I job
A Language Environment versionThe sample job in Figure 110 shows the link-edit statements you need for aDFHCSDUP user program written in a Language En
Notes:1. In a TSO environment, it is normally possible for the terminal operator tointerrupt processing at any time by means of an ATTENTION interrupt
The length of the page number data (field ‘bb’ in Figure 111) must be 0 or 4.The page number, if supplied, must be four numeric EBCDIC characters. Thefi
v The parameters DCBS and EXITS are aligned on a fullword boundary, and thefirst four bytes ‘00bb’ contain the binary number of fullwords in the follow
The user exit points in DFHCSDUPThere are five user exit points in DFHCSDUP. By specifying the appropriate entryparameters, you can cause DFHCSDUP to p
The get-command exitThe purpose of the get-command exit is to read in command lines. If it is specified,no commands are read from SYSIN.On invocation,
The extract exitThe extract exit is invoked at various points during processing of the EXTRACTcommand. The points are listed on page 743.Notes:1. If y
Exit XDLIPOSTWhen invokedOn exit from the DL/I interface program.Exit-specific parametersUEPCTYPEAddress of type-of-request byte. Values are:UEPCEXECAn
to the user program” on page 743.) However, when DFHCSDUP is invokedfrom a user program, the parameter list also includes the standardparameters menti
The put-message exitThe put-message exit is invoked whenever a message is to be issued. If you arerunning under TSO, you could use this exit to termin
The termination exitThe purpose of the termination exit is to allow you to perform final housekeepingduties. It is invoked before a normal or an abnorm
Chapter 31. The programmable interface to the RDOtransaction, CEDAThis chapter describes a programmable interface to the resource definition online(RDO
Notes:1. An attempt to start CEDA from an application program by an EXEC CICSSTART command must fail. This is because CEDA’s first action is to request
from a back-end application program whose session is in SEND state (and whichhas never issued a SYNCPOINT), the session will be put into RECEIVE state
764 CICS TS for OS/390: CICS Customization Guide
Part 9. Appendixes© Copyright IBM Corp. 1977, 1999 765
766 CICS TS for OS/390: CICS Customization Guide
Appendix A. Coding entries in the VTAM LOGON mode tableThis appendix shows you what to code in your VTAM LOGON mode table for aterminal to be automati
Exit XSTOUT ...180System recovery program exit XSRAB ...182Exit XSRAB...182System termination
UEPIOAXAddress of I/O area existence flag byte:UEPIOA1I/O area exists.For UEPCSHIP requests, the I/O area existence flag isalways off.UEPIOAAddress of I
TYPETERM device types and pointers to related LOGON mode dataSearch Table 40 for the TYPETERM device type that corresponds to the terminalyou want to
Table 40. TYPETERM device types, with cross-references to VTAM logmodeentries (continued)TYPETERM device type Referencenumber inTable 41 onpage 770DEV
VTAM MODEENT macro operandsTable 41 VTAM LOGON mode table entry for each TYPETERM you might define.You should have reached this table by looking up the
Table 41. LOGON mode table and ISTINCLM entries (continued)RN VTAM MODEENT macro entries that are needed for relatedCICS TYPETERM definitionsSuitablesu
Table 41. LOGON mode table and ISTINCLM entries (continued)RN VTAM MODEENT macro entries that are needed for relatedCICS TYPETERM definitionsSuitablesu
Table 41. LOGON mode table and ISTINCLM entries (continued)RN VTAM MODEENT macro entries that are needed for relatedCICS TYPETERM definitionsSuitablesu
Table 41. LOGON mode table and ISTINCLM entries (continued)RN VTAM MODEENT macro entries that are needed for relatedCICS TYPETERM definitionsSuitablesu
PSERVIC screen size values for LUTYPEx devicesTable 42 is to help you decide what screen size values you should specify on thePSERVIC operand of the V
Table 43. Equivalent PSERVIC screen size valuesBytes 20—24 of CICS model bind Valid screen size values on PSERVICdefinition0000 0000 01 0000 0000 00000
AUTINSTMODEL ==> ONLYGROUP ==> PDATDTYPETERM ==> T3278INSERVICE ==> YESTYPETERM definition*************************TYPETERM ==> T3278GR
Dump domain exits XDUREQ, XDUREQC, XDUCLSE, and XDUOUTThere are four exits in the dump domain.Exit XDUREQWhen invokedImmediately before a system or tr
LOGONMSG ==> YESDISCREQ ==> YESRECEIVESIZE ==> 256BUILDCHAIN ==> YESBIND SENT BY CICS : 010303B1 B0308000 0085C780 0002800000000018 501850
TERMINAL definition*************************AUTINSTNAME ==> M6670AUTINSTMODEL ==> ONLYGROUP ==> PDATDTYPETERM ==> T6670INSERVICE ==> YE
PRIPROT=X'B1',SECPROT=X'B0',RUSIZES=X'8585',COMPROT=X'7080'TERMINAL definition*************************AUTINST
BIND SENT BY CICS : 010304B1 B0708000 00858580 0001311840000092 0000E100 50000000 00000000************************************************************
ATI ==> YESTTI ==> YESBRACKET ==> YESRECEIVESIZE ==> 256SENDSIZE ==> 256BIND SENT BY CICS : 010303B1 90308000 00000080 00010000********
SESSIONTYPE ==> 3270RELREQ ==> YESDISCREQ ==> YESIOAREALEN ==> 256BRACKET ==> YESRECEIVESIZE ==> 240ATI ==> NOTTI ==> YESBIND
DEVICE ==> 3650SESSIONTYPE ==> USERPROGBRACKET ==> NORELREQ ==> NODISCREQ ==> NORECEIVESIZE ==> 256IOAREALEN ==> 256ATI ==> YE
AUTINSTMODEL ==> ONLYGROUP ==> PDATDTYPETERM ==> T3290INSERVICE ==> YESTYPETERM definition*************************TYPETERM ==> T3290GR
LDC=(DS=1),DVC=3604,PGESIZE=(6,40),PGESTAT=PAGEDFHTCT TYPE=LDC,LDC=SYSTEMBIND SENT BY CICS : 010404B1 B0700000 00000080 00000000LOGON mode definitions
DFHLU2 MODEENT LOGMODE=DFHLU2, SNA LUTYPE2 3270TYPE=1,FMPROF=X'03',TSPROF=X'03',PRIPROT=X'B1',SECPROT=X'B0',CO
UEPXDSCPAddress of a 1-byte field indicating the current dump tableDUMPSCOPE setting. It contains one of the following values:UEPXDLOCA system dump wil
DFHLU2E3 MODEENT LOGMODE=SNX32703, LU2 model 3 queryableFMPROF=X'03',TSPROF=X'03',PRIPROT=X'B1',SECPROT=X'90',
Appendix B. Default actions of the node abnormal conditionprogramThis appendix describes the default actions of the node abnormal conditionprogram, DF
Table 44. Messages issued and flags set by DFHZNAC for specific error codes (continued)Error code Symbolic label Message Action flags setX'1E'
Table 44. Messages issued and flags set by DFHZNAC for specific error codes (continued)Error code Symbolic label Message Action flags setX'48'
Table 44. Messages issued and flags set by DFHZNAC for specific error codes (continued)Error code Symbolic label Message Action flags setX'74'
Table 44. Messages issued and flags set by DFHZNAC for specific error codes (continued)Error code Symbolic label Message Action flags setX'A7'
Table 44. Messages issued and flags set by DFHZNAC for specific error codes (continued)Error code Symbolic label Message Action flags setX'D3'
Notes:1. See message DFHZC2497 or DFHZC3493, depending on the device type.2. “Good morning” message to be sent.3. Cancel task, and close VTAM session
Table 45. CICS messages associated with VTAM errors (continued)Message Symbolic label Error code Action flags setDFHZC2418 TCZSEXUC X'BB' 239
Table 45. CICS messages associated with VTAM errors (continued)Message Symbolic label Error code Action flags setDFHZC2458 TCZPXE2 X'DD' None
MAXIMUM setting will not suppress this dump request. A returncode of UERCBYP may be used to suppress the current dumprequest.UEPDXDCNTAddress of a 4-b
Table 45. CICS messages associated with VTAM errors (continued)Message Symbolic label Error code Action flags setDFHZC3441 TCZVTAMO X'63' Non
Table 45. CICS messages associated with VTAM errors (continued)Message Symbolic label Error code Action flags setDFHZC4903 TCZLUCF2 X'22' 3 9
Table 45. CICS messages associated with VTAM errors (continued)Message Symbolic label Error code Action flags setDFHZC4946 TCZINVAT X'F9' 2 3
Table 46. Messages issued and flags set by DFHZNAC for specific sense codes (continued)Sense code Message Action flags setX'0829' DFHZC3407 1,
3. Action flags 2 and 3 are set for negative response received for a SEND thatrequested a definite response.4. Presentation space error.5. Presentation
Appendix C. Transient data write-to-terminal program(DFH$TDWT)DFH$TDWT is a sample program that sends transient data messages to a terminalor printer.
804 CICS TS for OS/390: CICS Customization Guide
Appendix D. Uppercase translationThis appendix describes how to translate lower- and mixed-case characters touppercase. “Uppercase translation of nati
If you use this method, you must reassemble your modified copy of DFHTCTDY,keeping the 'DY' suffix. The 'DY' suffix is necessary be
Appendix E. The example program for the XTSEREQ globaluser exit, DFH$XTSEThis appendix lists the example global user exit program, DFH$XTSE. The examp
Return codesUERCNORMContinue processing.UERCBYPSuppress dump.UERCPURGTask purged during XPI call.XPI callsWAIT_MVS can be used only when a UEPDUMPT in
* ** It is not safe to use the following storage: ** Program storage (DFHEISTG) since this is freed as soon ** as the exit program returns control to
*---------------------------------------------------------------------** The TS Routing table is made up of a set of entries. Each entry ** can be map
* Registers: ** R1 = UEPAR plist (set on entry) ** = Work register ** R2 = UEPAR plist ** R3 = Program base register (set by DFHEIENT) ** R6 = Linkage
*=====================================================================** TS_REQUEST - Invoked at XTSEREQ exit point ** Determine the TS Queue Name and
*=====================================================================*TS_REQUEST DS 0H* Check for possible recursionL R1,UEPRECUR Address of recursiv
*=====================================================================** TS_REQUEST_COMPLETE - Invoked at XTSEREQC exit point ** Free any shared stora
*=====================================================================** LOCAL_REQUEST: Process Local TS Queues ** An entry has been found in the TS_R
*=====================================================================** ROUTE_REQUEST: Ship request to remote system ** An entry has been found in th
* Update the Sysid in CLPSROUTE1 DS 0HMVC SHARED_SYSID,NEW_SYSID Copy SYSID into shared storageL R8,UEPCLPS Address the CLPS..USING TS_ADDR_LIST,R8 ..
* Logic: ** Entry_Not_Found: ** Call Getmain_Shared ** Copy default_sysid into shared storage ** Address the command plist ** Update ADDR7 to point to
UEPDUMPTAddress of the 1-byte dump-type identifier, which contains one ofthe following values:UEPDTRANA transaction dump was requested.UEPDSYSTA system
*=====================================================================** GETMAIN_SHARED - Obtain Shared storage ** ** Registers: ** R0 = Used by EXEC
*=====================================================================** FREEMAIN_SHARED - Free shared storage ** Free the shared storage associated w
USING DFHTRPT_ARG,R1TRACE_ENTRY DS 0HL R1,UEPXSTOR Prepare for XPI callDFHTRPTX CLEAR, XPOINT_ID(TR_ENTRY)B ISSUE_TRACETRACE_EXIT DS 0HL R1,UEPXSTOR P
ERROR4 DS 0HMVI TR_ERROR_N,4B TRACE_ERRORERROR5 DS 0HMVI TR_ERROR_N,5B TRACE_ERRORERROR6 DS 0HMVI TR_ERROR_N,6B TRACE_ERRORERROR7 DS 0HMVI TR_ERROR_N,
TS_ROUTING_TABLE DS 0DENTRY_NAME_1 DC CL8'AAAAAAAA' Rename Queue AAAAAAAA asNEW_NAME_1 DC CL8'BBBBBBBB' BBBBBBBBBQOR_SYSID_1 DC CL
IndexSpecial Characters“good night” transactioncustomizing the sample program 736overview 733sample program, DFH0GNIT 735Numerics3270 bridgebridge exi
automatic installation of terminalscontrol programaction at delete 495action at install 487action on return 494information returned to CICS 491link-ed
DBCTL (database control)(continued)DFHDBUEX 622DFHMCT TYPE=EMP entries 661in an XRF environment 623interface status 595DBLID values 620DD card correla
DFHPGADX, user-replaceable autoinstall program(continued)introduction to 546parameter list at install 543sample program 546supplied definition of 547us
DFHZNEP, user-replaceable node error program 449DFHZNEPI macrosTYPE=ENTRY 479TYPE=FINAL 479TYPE=INITIAL 479dictionary data section, CICS monitoring re
UEPXDYESThe CICS system is to shutdown.UEPXDNOThe CICS system is not to shutdown.This field may be modified by the exit to update the dump tableSHUTDOWN
dynamic routing program (DFHDYP)(continued)UOW considerations 553, 562when invoked 550, 558dynamic transactions 550EEDF (Execution Diagnostic Facility
global user exits(continued)in DBCTL interface control program 19in DBCTL tracking program 40in dispatcher domain 42in DL/I interface program 44in dum
INQUIRE_TRANDEF function of the XPI 375INQUIRE_TRANSACTION function of the XPI 383interactive logical unit error processor 469intersystem queuescontro
NNAME operandDFHSNEP TYPE=INITIAL 470DFHSNET macro 473national charactersuppercase translation 805NEB (node error block) 474NEBNAME operandDFHSNET mac
node error program (NEP)(continued)DFHZNAC logging facility 476DFHZNEP 450, 457DFHZNEPI interface module 478DFHZNEPI macros 478DFHZNEPI TYPE=INITIAL 4
PLTSD programs(continued)general considerations 395introduction 394second phase 395POOL feature, TCAM 701pool of common TCTTEs 696PRINT operandDFHTEPM
SETEOM macro 694shipped terminals, automatic installation of 523shutdown (PLTSD) programsconsiderations when writing 394shutdown assist program, DFHCE
task-related user exits 280(continued)schedule flag word 280SPI parameters 257stub program 249, 250ename 251statname 251syncpoint manager calls 270back
TEP (terminal error program)(continued)system count (TCTTENI) 416user field a (PCISAVE) 445user field b (PCICNT) 445DFHTEP tables 432DFHTEPM TYPE=ENTRY
termination, TCAM 708TIE_UP_RECORD_DATA section, journal records 642TIME operandDFHSNET macro 474of DFHTEPT TYPE=PERMCODE|ERRCODEmacro 434TPROCESS blo
XPI callsWAIT_MVS can be used only when a UEPDUMPT indicates that atransaction dump is being taken. Do not use any other calls.Exit XDUCLSEWhen invoke
XFCAREQC, global user exit(continued)parameter list and return codes 83XFCBFAIL, global user exit 112XFCBOUT, global user exit 117XFCBOVER, global use
XPI (exit programming interface)(continued)GETMAIN 302INQUIRE_ACCESS 364INQUIRE_ELEMENT_LENGTH 365INQUIRE_SHORT_ON_STORAGE 366INQUIRE_TASK_STORAGE 367
840 CICS TS for OS/390: CICS Customization Guide
Sending your comments to IBMIf you especially like or dislike anything about this book, please use one of themethods listed below to send your comment
IBMRProgram Number: 5655-147Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.SC33-1683-02
Spine information:IBM CICS TS for OS/390 CICS Customization Guide Release 3
UEPDMPREDump is about to restart after autoswitch.UEPDMPABAbnormal termination of dump.UEPDMPDYBuffer is about to be written, and the CICS dump data s
Enqueue EXEC interface program exits XNQEREQ and XNQEREQCThe XNQEREQ exit allows you to intercept enqueue API requests before any actionhas been taken
Introduction to the task-related user exit mechanism (the adapter)...249The stub program ...250Returning control to the applica
between successive enqueue requests within the same task (forexample, between successive invocations of the XNQEREQ exit).UEPRECURAddress of a halfwor
UEPTSTOKAddress of a 4-byte token which can be used to pass informationbetween successive enqueue requests within the same task (forexample, between s
End of parameter list indicatorThe high-order bit is set on in the last address set in the parameter list toindicate that it is the last one in the li
X'20' Set if the request contains an argument for the MAXLIFETIMEkeyword. If set, NQ_ADDR3 is meaningful.NQ_BITS2Two bytes not used by the e
X'04' The existence bit for NOSUSPEND.The EID is reset to its original value before return to the application program. Thatis, changes made
Removing user argumentsUser exit programs can remove arguments (for which the program is totallyresponsible) associated with the LENGTH and MAXLIFETIM
Notes about the use of XNQEREQ to alter ENQ or DEQ scope.1. XNQEREQ enables you to allow existing applications to be converted to usesysplex enqueues
EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUTThere are four global user exit points in the EXEC interface program:XEIIN Invoked be
The correspondence between command parameters (such as PROGRAM) and theirpositions and values in the parameter list (in this case, argument 1, ‘MYPROG
UEPRSAAddress of the application’s register save area. This contains thecontents of the registers at the point when the program issued theEXEC CICS co
Kommentare zu diesen Handbüchern