Ibm SC33-1683-02 Manual de usuario

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