Ibm SC34-6814-04 Manuel d'utilisateur

CICS Transaction Server fo r z/OSCustomization GuideVers ion 3 Re le ase 2SC34-6814-04

Coding for specific VTAM sense codes ...508Writing multiple NEPs ...508DFHZNEPI macros ...508Handling

UEP_FC_DUPLICATE_KEY_CODEAddress of a 1-byte output area indicating whether the requestfound more than one record for the supplied key. The possibleva

v UEP_FC_REASON_DUPLICATE_RECORDv UEP_FC_REASON_DUPLICATE_REQIDv UEP_FC_REASON_END_OF_FILEv UEP_FC_REASON_FILE_DISABLEDv UEP_FC_REASON_FILE_NOT_OPENv

UERCBYPLBypass CICS processing of this request. If the exit program hasbeen invoked for a function-shipped request, the mirror transactionmust not ter

UEP_FC_BUFFER_PAddress of a fullword containing the address of the buffer providedby the originator of the request, in which the record is returned on

UEP_FC_KEYVSAM KSDS or AIX PATH accessUEP_FC_RBAVSAM ESDS or KSDS via RBA accessUEP_FC_RRNVSAM RRDS accessUEP_FC_DEBKEYBDAM deblocking by key (READ, D

UEP_FC_CRConsistent read integrity.UEP_FC_FCT_VALUERead integrity according to the setting in the FILE definition.UEP_FC_NRINo read integrity.UEP_FC_R

UEP_FC_REASONAddress of a 1-byte area containing, if the request completed withan EXCEPTION response, the reason. The possible reasons are:v UEP_FC_RE

v UEP_FC_REASON_NOTAUTHv UEP_FC_REASON_NOT_EXTENDEDv UEP_FC_REASON_PREVIOUS_RLS_FAILUREv UEP_FC_REASON_RBA_ACCESS_TO_RLS_KSDSv UEP_FC_REASON_READ_NOT_

Note: For information about the XFCAREQ and XFCAREQC exits that are invokedfor file control SPI requests, see “File control EXEC interface SPI exitsXF

v The address of a 16-byte area that is used if the request has been functionshipped.The command-level parameter structureThe command-level parameter

The sample autoinstall control program for APPC connections ...550Default actions of the sample program ...550Resource definitions ...

FC_GROUPAlways X'06', indicating that this is a file control request.FC_FUNCTOne byte that defines the type of request:X'02' READX

X'04' MASSINSERT specified.X'02' RRN specified.X'01' SET (and not INTO) was specified.Note: Your program must test for k

X'08' XRBA specified. If the XRBA bit is on, FC_RIDFLD (describedin DSECT DFHFCEDS) points to an 8-byte extended relativebyte address (XRBA)

Modifying fields in the command-level parameter structureSome fields that are passed to file control are used as input to the request, someare used as

Modifying input fields: The correct method of modifying an input field is to createa new copy of it, and to change the address in the command-level pa

X'04' REPEATABLE specified.X'02' UPDATE specified on READNEXT or READPREV.X'01' NOSUSPEND specified (on READ, READNEXT,

Use of the parameter UEPFSHIPUEPFSHIP contains the address of a 16-byte area. This area consists of 4characters, followed by 3 fullwords. If the first

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

UEPFSHIPAddress of a 16 byte area. See “Use of the parameter UEPFSHIP”on page 94.UEPRSRCEAddress of an 8-character copy of the EIB resource value,EIBR

‘EIBRCODE’. For details of EIB return codes, refer to EIB fields, inthe CICS Application Programming Reference manual.UEPRESPAddress of a 4-byte binar

Routing transactions dynamically ...590Dynamic transactions ...590When the dynamic routing program is invoked ...

3. Exit programs that issue EXEC CICS commands, and that use theDFHEIENT macro, should use the DFHEIRET macro to set a return codeand return to CICS.

4. XFCAREQCv For the INQUIRE FILE command, only the XFCAREQ and XFCAREQC exits areinvoked:1. XFCAREQ2. XFCAREQCExit XFCAREQWhen invokedBefore CICS pro

Note: Take care when using recursive commands. For example, you must avoidentering a loop when issuing a file control SPI request from the XFCAREQexit

values into the application program’s EXEC interface block (EIB) after thecompletion of XFCAREQC or if you specify a return code of UERCBYP inXFCAREQ.

v FCIS_BITS4v FCIS_BITS5v FCIS_BITS6v FCIS_BITS7v FCIS_BITS8FCIS_GROUPAlways X'4C', indicating that this is a file control SPI request.FCIS_

X'40' Set if the request contains an argument for the ADD keyword. Ifset, FCIS_ADDR10 is meaningful.X'20' Set if the request conta

X'10' Set if the request contains an argument for the EXCLUSIVEkeyword. If set, FCIS_ADDR28 is meaningful.X'08' Set if the request

X'08' Set if the request contains the LOADTYPE keyword.X'04' Set if the request contains the POOL keyword.X'02' Set if t

FCIS_ADDR15is the address of a 4-byte area containing the CVDA from ENABLESTATUS.FCIS_ADDR16is the address of a 4-byte area containing the CVDA from R

FCIS_ADDR37 to FCIS_ADDR51are not used by file control.FCIS_ADDR52is the address of a 4-byte area containing the data from JOURNALNUM.FCIS_ADDR53is th

When the distributed routing program is invoked ...632Changing the target CICS region ...633Telling CICS whether to route the me

Table 5. INQUIRE FILE requests (continued). The relationship between arguments,keywords, data types, and input/output types.Argument Keyword Data Type

Table 6. SET FILE requests (continued). The relationship between arguments, keywords,data types, and input/output types.Argument Keyword Data Type Inp

Note: You must never modify an input field by altering the data that is pointed to bythe command-level parameter list. To do so would corrupt storage

Modifying user argumentsUser exit programs can modify user arguments as follows:v For input arguments, your exit program should obtain sufficient stor

For a CLOSE WAIT command, the exits are invoked as follows. XFCSREQ isinvoked, the task requests a closure of the file and waits for the closure to ha

UEPFSOFBOpen for backout.If the first byte indicates a close request (UEPFSCLS), the secondbyte shows the type of close:UEPFSNCNormal closeUEPFSCPClos

UEFJRUJournal read for updateUEFJWUJournal write updateUEFJWAJournal write addUEFJDSNDsname has been journaledUEFJSYNJournal read synchronouslyUEFJASY

UEFACBCPThis field is set to nulls in this exit.Note: Only the first seven fields of UEPFINFO are set for this exit.Of the remaining fields, URFFRCLG

Exit XFCSREQCWhen invokedAfter a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSEcommand has completed.Note: The exit is not invoked for function-sh

UEFLNAMEThe 8-character file name.UEDSNAMEThe 44-character dsname of the data set associated withthe file.UEFSERVOne byte indicating the SERVREQ setti

Event codes ...681The EJB event sample program ...682Actions of the default program ...682Writing

UEFVSAMVSAM fileUEFBDAMBDAM fileUEFDTBLData table fileUEFDTUMUser data table fileUEFCFDTCoupling facility data tableUEFBCRVOne byte indicating the rec

UEPFBCASData set marked unavailable.UEFACBCPAddress of a read-only copy of the ACB for a VSAM file, orthe DCB for a BDAM file. Set only after completi

UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI callsAll except EXEC CICS SHUTDOWN and EXEC CICS XCTL can be used.Note:1. Tak

associated with the file, as described by fields UEFLNAME andUEDSNAME in the DFHUEFDS DSECT.3. Issues a WRITE OPERATOR command to write as much data a

XFCNREC. If the base cluster block is set as unrecoverable and a mismatch hasbeen allowed, access may be allowed to the data set, via an unrecoverable

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 is not to carry out the processing required for the VSAM RLSaction, and is to cancel the action throughout the sysplex.A return code of UERCPURG

UEPQRCDEAddress of a 1-byte field indicating the result of the quiesce orunquiesce. Possible values are:UEQOKSuccessful.UEQREJECRejected—see UEPQCONF

File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER,and XFCLDELCICS provides four global user exits that you can use in connection with fi

point; the TBEXITS parameter allows only one exit program at each exit point.PLTPI processing is described in Chapter 4, “Writing initialization and s

Chapter 28. CICS monitoring ...743Introduction to CICS monitoring ...743How CICS monitoring data is passed to SMF ...

UEPFCRSPAddress of the file control response byte. This can have one of thefollowing values:UEAIXFULNo space in non-unique alternate index.UECACHERLS

UERCBYPIgnore the error (do not invoke CICS backout failure control) andcontinue. Setting this return code could be damaging to the integrityof your d

record on the data set with the “before-image” held in the log recordaddressed by UEPBLOGR. Use parameter UEPFCRSP to determine whicherror occurred.XB

The sample program takes this step to demonstrate the use of the UERCBYPreturn code. It is not recommended that you use UERCBYP with important dataset

Because the same backout code is executed following an emergency restart as atany other time, XFCBOUT replaces both XRCINPT and XDBIN for file data. T

VSAM RLS locks individual records within a data set, and these locks are convertedto retained locks for those UOWs that are not completed because of b

UERCNORMDo not perform the backout of this log record. Any updatesperformed by the batch run should take precedence.UERCBCKOPerform the backout. It is

– The data set name– The file control portion of the log record.v Checks the data set name to see if it is one of those for which it is known thatbatc

UEPFLENAddress of a fullword containing the length of the data in the filecontrol request.Return codesUERCFAILDo not perform the logical delete, and t

– An eye-catcher ‘DFH$FCLD ENTRY’– The unmarked file control request data– The file control portion of the log record.v Issues an EXEC CICS INQUIRE FI

Part 8. Examining and modifying resource attributes ...807Chapter 33. Using the programmable interface to CEDA ...809When to use the pr

Good morning message program exit XGMTEXTWhen invokedBefore the good morning message is transmitted.Exit-specific parametersUEPTCTTEAddress of the ter

If you already have an XISCONA exit program, you may be able to modify it for useat the XZIQUE exit point.The purpose of XISCONA is to help you preven

v Examine the type of request and the resource being accessed (which can bediscovered by examining the request parameter list). The program could, for

UEPEIPPLAddress of the request parameter list.UEPCONTYA 1-byte field indicating the connection-type. Possiblevalues are:UEPMRO (X'80')Reques

Note that this exit is invoked only if the request to be shipped is of type EXEC CICSSTART NOCHECK. For EXEC CICS requests other than those with the N

UERCPURGTask purged during XPI call.XPI callsAll can be used.ImportantThere is no ‘UERCNORM’ return code at this exit point, because the exit is invok

Note:1. The contents of the fields addressed by UEPICQID andUEPICTID are unpredictable if the associated data items werenot specified on the request.

Exit XICTENFWhen invokedExit XICTENF is also invoked from the interval control program. However,this exit relates to the ‘terminal not known’ conditio

v For dynamically-routed transactions—only dynamically-routed(non-terminal-related) START requests cause the exit to be invoked. Thus, adynamically-ro

Exit-specific parametersUEPCLPSAddress of the command-level parameter structure. See “TheUEPCLPS exit-specific parameter” on page 152.UEPICTOKAddress

Appendix F. The example program for the XTSEREQ global user exit,DFH$XTSE ...877Appendix G. Threadsafe XPI commands ...

EXEC CICS SHUTDOWNEXEC CICS XCTLNote: Take care when issuing recursive commands not to cause a loop. Forexample, it is your responsibility to avoid en

UERCNORMContinue processing.UERCPURGTask purged during XPI call.UERCRESUA required resource is unavailable. Setting this value causes CICSto reject th

UEPDATEAddress of a fullword copy of the EIB date value, EIBDATE.UEPTIMEAddress of a fullword copy of the EIB time value, EIBTIME.UEP_IC_REMOTE_SYSTEM

The command-level parameter structure consists of a series of addresses. The firstaddress points to the EXEC interface descriptor (EID), which consist

the request. The remaining addresses point to pieces of data associated with therequest. For example, the second address points to the interval for ST

IC_GROUPX'10' This is an interval control request.X'4A' This is an ASKTIME or FORMATTIME command.IC_FUNCTOne byte that defines the

X'80' Set if the request specifies RTERMID, or if a FORMATTIMErequest specifies DATESEP. If set, IC_ADDR9 is meaningful.X'40' Set

X'04' YEAR was specified on a FORMATTIME command, orMINUTES was specified.X'02' TIME was specified on a FORMATTIME command, orPROT

IC_ADDR2is the address of one of the following:v An 8-byte area containing the value of REQID (if the request is DELAY,POST or START).v A halfword con

v A fullword containing the value of DAYCOUNT.IC_ADDRBis the address of one of the following:v An area containing the value of HOURS.v A fullword cont

xvi Customization Guide

The following are always input fields:v INTERVALv TIMEv REQIDv FROMv TERMIDv SYSIDv HOURSv MINUTESv SECONDSv USERIDv CHANNELThe following are always o

ABSTIME is an input field on a FORMATTIME request, and an output field on anASKTIME request. DATESEP and TIMESEP can be input fields on a FORMATTIMEre

X'40' The existence bit for QUEUEX'20' The existence bit for HOURSX'10' The existence bit for MINUTESX'08' The

IC_EIDOPT8X'20' Unused by CICS.The EID is reset to its original value before return to the application program. Thatis, changes made to the

1. Scan the global work area (GWA) to locate a suitable CICS region (forexample, the region currently processing the least number of STARTrequests).2.

These are both information-only exits. Any changes made to the exit parameters bythe exit program are ignored by CICS, as is any return code which it

UEPPROGLAddress of a 4-byte field containing the length, in bytes, of theprogram that is being freed.UEPLDPTAddress of a 4-byte field containing the a

If you do not provide a JOURNALMODEL resource definition for DFHLOGand DFHSHUNT, or if you use the CICS definitions supplied in groupDFHLGMOD, the mod

For information about the IXGINVNT service, see the OS/390 MVS AuthorizedAssembler Services manual.An XLGSTRM global user exit program can set explici

UEPSYSLGThe log stream is for a CICS system log.UEPGENLGThe log stream is for a general log (a forward recovery log,a user journal, or auto-journal).R

PrefaceWhat this book is aboutThis book provides the information needed to extend and modify an IBM®CICS®Transaction Server for z/OS®system to match y

Note: To run the sample program “as is”, you must first create a model log streamcalled 'CICSAD01.DEPT0001.MODEL100'. However, you will prob

ImportantBecause of the danger of recursion, your XMEOUT exit program should not try toreroute:v Any DFHTDxxxx messages, produced by the transient dat

UEPTERMAddress of the 4-byte ID of the terminal under which the currenttransaction is running. If the current transaction is not associatedwith a term

DFHFC0531 date time applid Automatic journal journaljournalname, opened for file filename is not oftype MVS. Module module.The XMEOUT inserts are date

DFH$SXP5Reroute a TDQ message to another TDQDFH$SXP6Reroute a TDQ message to a console.Related concepts“The message domain sample exit programs” on pa

UEPDICTAddress of the dictionary. The sequence of dictionary entries ismapped by the DSECT generated from the macro DFHMCTDR.This field only has meani

UERCNORMContinue processing.UERCBYPSuppress monitor record output.UERCPURGTask purged during XPI call.XPI callsWAIT_MVS can be used. Do not use any ot

UEPAPABN (X'40')The Web service provider application completed its processingsuccessfully.UEPAPSFA 1-byte field indicating if the Web servic

Note:1. The attributes of the local PROGRAM definition are not passed to theexit program. If the exit program needs to know, for example, thevalue of

2. Reinvoke the routing program, on the routing region, for route selectionfailure.3. Return a RESUNAVAIL condition on the EXEC CICS LINK commandexecu

v Cv COBOLv PL/I.In this book, the phrase “the languages supported by CICS” refers to the abovelanguages.Syntax notation and conventions used in this

UEPRSRCEAddress of an 8-character copy of the EIB resource value,EIBRSRCE.UEP_PC_PBTOKAddress of a 4-byte field containing the z/OS Workload Manager(W

UEPRECURAddress of a halfword recursion counter. Because the XPCERESexit can never be called recursively in the same transaction, thevalue of this fie

UEPCLPSAddress of the command parameter list.UEPPCTOKAddress of a 4-byte token passed from XPCREQ. This allowsXPCREQ to, for example, pass a work area

UERCPURGTask purged during XPI call.XPI callsAll can be used.Although the exit permits the use of XPI GETMAIN and FREEMAIN calls,we recommend that you

PC_ADDRA. It is defined in the DSECT PC_ADDR_LIST, which you should copyinto your exit program by including the statement COPY DFHPCEDS.The command-le

PC_EXIST7 (X'02 ')Set if the request specifies the SYSID parameter. If set,PC_ADDR7 is meaningful.PC_EXIST8 (X'01 ')Set if the req

PC_ADDRAis the address of the 16-byte channel name, as specified on the CHANNELparameter.Modifying fields in the command parameter structure: Some fie

Bits in the EID should be modified in place. You should not modify the pointer to theEID. (Any attempt to do so is ignored by CICS.)The EID is reset t

1. Scan the global work area (GWA) to locate a suitable CICS region - forexample, the region currently processing the least number of LINK requests.2.

terminal-related information, and that can be mapped using theDSECT DFHPCUE. When XPCFTCH is invoked, the followingDFHPCUE fields are significant:PCUE

Summary of changesThis book is based on the CICS Customization Guide for CICS Transaction Serverfor z/OS, Version 3 Release 1, SC34-6429-00. Changes f

address. Set the top bit to specify that the alternativeprogram is to run AMODE (31).PCUE_REAL_ENTRYFrom z/OS 1.7 onwards, this field provides the rea

BASSM 15,0USING *,15When invokedBefore a HANDLE ABEND routine is given control.Exit-specific parametersUEPPCDSAddress of a storage area that contains

XPI callsAll can be used.Exit XPCTAXPCTA is invoked immediately after a transaction abend, and before anyprocessing that might modify the existing env

PCUE_LOGICAL_LEVELFullword containing the number of chained DFHRSADSblocks (that is, logical level).PCUE_BRANCH_ADDRESSFullword. You can use this fiel

DFH$PCTA can be extended for transaction isolation.Related concepts“The transaction-abend sample exit program” on page 24Exit XPCABNDXPCABND is invoke

UERCBYPSuppress the dump call.UERCPURGTask purged during XPI call.XPI callsAll can be used.Resource manager interface program exits XRMIIN and XRMIOUT

UERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI commandsAll except EXEC CICS SHUTDOWN and EXEC CI

Return codesUERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI commandsAll except EXEC CICS SHUTDOWN

connection is a concatenation of a FEPI node name and a FEPI target name, eachof which is 8 characters long (fixed length) with no separator.The exit

UEIDDB2EA DB2 entry (DB2ENTRY)UEIDDB2TA DB2 transaction (DB2TRAN)UEIDDJARA deployed JAR file (DJAR)UEIDDOCTA DOCTEMPLATEUEIDFECOA FEPI connectionUEIDF

Changes for CICS Transaction Server for z/OS, Version 2 Release 3The more significant changes for this edition were:v A new global user exit, XICERES,

UEIDPSETA partitionsetUEIDRQMDA request model (IIOP)UEIDSESSA sessionUEIDSTRMAn MVS log streamUEIDTCLSA transaction classUEIDTCPSA TCP/IP serviceUEIDT

UERCPURGTask purged during XPI call.XPI callsYou can use all XPI calls.ImportantAbends in a program enabled at the XRSINDI exit point may cause CICS t

UEPTRMIDAddress of the terminal id.UEPTCTUAAddress of the TCT user area.UEPTCTULAddress of the TCT user area length.UEPTRMTYAddress of the terminal-ty

UEPTRMTYAddress of the terminal-type byte.UEPSNFLGAddress of a 2-byte field containing flags:UEPSNOKSign-off was successfulUEPSNFLSign-off failedUEPSN

To use this program, add an entry to the first section of your PLTPI table (thatis, before the DFHDELIM statement). For example:DFHPLT TYPE=INITIAL,SU

UEPSTYPEAddress of the 3-byte character field statistics type. The values ofthe types are:INT Interval statisticsEOD End-of-day statisticsREQ Requeste

SRP_ERROR_TYPEThe 4-character error type—always ‘ASRB’.SRP_SYS_ABCODE2 bytes containing the system abend code XXX in binaryformat (for example, D37).S

SRP_CICS_ERROR_REASON4-character field containing the MVS abend reason code. Itcontains a value only if flag SRP_VALID_REASON is set.SRP_CICS_ERROR_DA

2. The format of SRP_ERROR_DATA is shown in the CICS DataAreas manual.Return codesUERCNOCAAbnormally terminate the task with abend code ‘ASRB’. Do not

XPI callsAll other XPI calls except WRITE_JOURNAL_DATA can be used. However,their use is not recommended, because they could cause the task to losecon

Part 1. Customizing with user exit programs© Copyright IBM Corp. 1977, 2011 1

UEP_TS_QUEUE_NAMEAddress of a 16-byte field containing the queue name.UEP_TS_DATA_PAddress of a fullword containing the address of the data. (Write an

UEPTERMAddress of the 4-byte terminal ID.UEPPROGAddress of the 8-byte application program name.UEP_TS_FUNCTIONAddress of a byte containing the functio

Exit XTSPTINWhen invokedBefore execution of a temporary storage interface request for a CICSinternal queue (for example, for interval control or BMS q

Return codesUERCNORMNormal.UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI callsNone can be used.Exit XTSPTOUTWhen invokedAft

v UEP_TS_RESPONSE_EXCEPTIONv UEP_TS_RESPONSE_DISASTERv UEP_TS_RESPONSE_INVALIDReturn codesUERCNORMNormal response.UERCPURGA purged response was receiv

Exit XTSEREQWhen invokedBefore CICS processes a temporary storage API request.Exit-specific parametersUEPCLPSAddress of a copy of the command paramete

Note: Take care when issuing recursive commands. For example, you must avoidentering a loop when issuing a temporary storage request from theXTSEREQ e

UERCPURGTask purged during XPI call.XPI callsAll can be used.API and SPI commandsAll can be used, except for:EXEC CICS SHUTDOWNEXEC CICS XCTLYou can u

The command-level parameter list is made up as follows.Note: The relationship between arguments, keywords, data types, and input/outputtypes is summar

X'02' Set if the request contains an argument for the SYSID keyword.If set, TS_ADDR7 is meaningful.TS_BITS2Two bytes not used by temporary s

2 Customization Guide

TS_ADDR7is the address of an area containing the value of SYSID.Modifying fields in the command-level parameter structure: Some fields thatare passed

However, you can make minor changes to requests, such as to turn on theexistence bit for SYSID so that the request can be changed into one that is shi

Table 11. READQ TS: User arguments and associated keywords, data types, andinput/output typesArgument Keyword Data type Input/output typeArg1 QUEUE CH

1. Obtain storage for the argument to be added2. Initialize the storage to the required value3. Select and set up the appropriate pointer from the par

UEPALLENAddress of a fullword binary field containing the length of the FROMdata; or hexadecimal zeros, in either of the following cases:v The AID was

Note: The XALTENF exit, used to handle the “terminal not known” condition, isalso invoked from the terminal allocation program. XALTENF is described o

XPI callsAll can be used. However, note that you cannot use a GETMAIN call toobtain terminal-class storage for use as a replacement TIOA.Exit XTCATTWh

in the local system. If the requested terminal is remote, the terminal allocationprogram ships an ATI request to the remote system, which initiates tr

UERCNETNNetname of TOR returnedUERCSYSISysid of TOR returned.For return codes UERCNETN and UERCSYSI, the exit program must place thenetname or sysid o

UEPALTRNAddress of 4 bytes containing the name of the transaction to berun.UEPALRTRAddress of 4 bytes containing the name of the terminal on whichthe

Chapter 1. Global user exit programsYou can use the CICS global user exit points, in conjunction with programs of aspecial type that you write yoursel

run. It is important that your exit program supply a terminalnetname if the TOR to which it directs the ATI request is a memberof a VTAM generic resou

UEPICFNA START command was not being processed or aSTARTwas being processed but it was not function shipped.UEPICTRNAddress of 4 bytes containing the

run. It is important that your exit program supply a terminalnetname if the TOR to which it directs the ATI request is a memberof a VTAM generic resou

DFHXTENF CSECTDFHVM XTENFENTRY DFHXTENADFHXTENA DS 0HSTM R14,R12,12(R13) save registersBALR R11,0 set up base registerUSING *,R11*USING DFHUEPAR,R1 DF

ImportantThe example in Figure 2 on page 231 is intended purely as a demonstration ofsome of the possibilities available, and would be impractical in

transaction specified on DTRTRAN is attached and CICS considersthat the transaction has been found.Equated values are:UEATFNDThe transaction was found

When the task being attached is for a task started by an immediateSTART command; that is, a START without an interval, the current taskis the task tha

UEPTDLUDAddress of the fullword length of the unmodified TD data.UEPTDAMDAddress of the TD data modified by the exit program.UEPTDLMDAddress of the fu

Note: If you return UERCTDOK to suppress the first line of amultiline message, the rest of the message is not presentedto XTDOUT, but is also suppress

Exit XTDEREQWhen invokedBefore CICS processes a transient data API request.Exit-specific parametersUEPCLPSAddress of the command-level parameter struc

v Register 13 contains the address of the standard register save area where yourexit program should store its own registers immediately after being in

Note: Take care when issuing recursive commands. For example, you must avoidentering a loop when issuing a transient data request from the XTDEREQexit

UERCNORMContinue processing.UERCPURGTask purged during XPI call.XPI callsAll can be used.Although the exit permits the use of XPI GETMAIN and FREEMAIN

You can examine the EID to determine the type of request and the keywordsspecified. You can examine the other parameters in the list to determine the

X'04' READQX'06' DELETEQ.TD_BITS1Existence bits that define which arguments were specified. To obtainthe argument associated with

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

Modifying fields used for both input and output: An example of a field that isused for both input and output is LENGTH on a READQ request that specifi

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2that you are given in the parameter list. Transient data copies your values into

When using XRCINIT and XRCINPT, you should bear in mind that the exits may beinvoked before recovery of temporary storage and transient data resources

name6 are the names of your user exit programs for XRCINIT, XRCINPT,XFCBFAIL, XFCLDEL, XFCBOVER, and XFCBOUT.v Enable the exits during the first stage

UEPUOWBOUOW backed outUEPUOWIFUOW was in-flightUEPUOWIDUOW was in-doubt.UEPLGRECAddress of the log record just read. The journal control record canbe

An exit program invoked at an exit that does not support the use of EXEC CICScommands must not call a task-related user exit program (TRUE). Calling a

UEPTPNLAddress of a 1-byte field containing the length of the TPN or DPN.UEPTRANAddress of the 4-byte transaction ID.Note: The exit program must not c

UEPTCTTEAddress of the terminal control table terminal entry (TCTTE). TheTCTTE can be mapped using the DSECT DFHTCTTE.UEPTIOAAddress of the terminal i

v The equivalent global user exit to control the number of queued requestsfor sessions on IP interconnectivity (IPIC) connections is XISQUE: see“XISQU

Using the information passed in the parameter list, your global user exit programcan decide (based on queue length, for example) whether CICS is to qu

v For specific modegroup allocate requests, use return code UERCAKLM.UERCAKLM also returns SYSIDERR to all application programs waiting onthe purged a

Each time an XZIQUE global user exit program returns with a request to purge aqueue, CICS increments a new field in either the system entry or mode en

UEPPADA 1-byte padding field.UEPFSPLAddress of the 10-byte function shipping parameter list.UEPCONSTAddress of the 158-byte system entry statistics re

UEPSACNTA half-word binary field containing the number of all non-specificallocates processed since the queue was started (see UEPSAQTSfor the start t

UERCNORMResume normal operation of the link or modegroup.UERCAPURReject the allocate request with SYSIDERR.XPI callsAll can be used.Designing an XZIQU

to control the existence and length of the queue of allocate requests. If you enablethe exit, the parameters from the connection definition are passed

Assembler programs and LEASMAssembler programs translated with the LEASM option cannot be used as globaluser exit programs.LEASM is used to produce La

Extensions to the sample program: The sample exit program does not attempt tocontrol the queue length, or detect poor response for a particular modegr

Exit-specific parametersUEPISDATAAddress of the 78-byte area containing the information listed below.This area is mapped by the DSECT in copybook DFHX

UERCAQUEQueue the allocate request.UERCAPURReject the allocate request with SYSIDERR.UERCAKLLReject this allocate request with SYSIDERR. Purge all oth

number of allocates processed since the queue began, to determine the rate atwhich CICS is processing requests. The relevant fields are: UEPSAQTS andU

ISR_XISQUE_ALLOC_REJECTSEach time an XISQUE global user exit program returns with a request to rejecta request, CICS increments this field, which is p

the exit, the parameters from the IPCONN definition are passed to the XISQUE exitprogram, which can change the way in which these parameters are used.

v A predatory takeover. A “predatory takeover” can occur, if you are using VTAMRelease 3.4.0 or above, and a VTAM application with the same APPLID as

v For XRF, in the event of a VTAM failure: CICS continuesprocessing as if the exit program had not been invoked.v For VTAM persistent sessions, in the

266 Customization Guide

Chapter 2. Task-related user exit programsThis chapter describes a special kind of user exit called a task-related user exit(TRUE). The chapter is div

v If your global user exit is in a domain, you can add extra trace calls to provideadditional diagnostic information by setting the AP option of EXEC

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

The administration routines may also contain commands to retrieve informationabout one of the exit program’s work areas (the EXEC CICS EXTRACT EXITcom

The application can use a parameter to determine whether the resource managerwas called. For example, if the application sets a parameter to zero and

Writing a task-related user exit programThe main function of the task-related user exit program is to translate the callingprogram’s parameters into a

Threadsafe restrictionsAn open API TRUE must not treat the executing open TCB environment in such away that it causes problems for:v Other open API TR

Application program call (API)—UERTAPPLFor this call, CICS always invokes the TRUE on an L8 mode TCBCICS syncpoint manager call—UERTSYNCFor this call,

v The address of the kernel stack entryv The address of the APPC unit of work (UOW) identifierv The address of the user security block flagv The addre

area, with the contents of registers 14 through 12 stored in the fourth andsubsequent words. Its fifth word, representing the calling program's r

UEPRMQUAAddress of an 8-byte field into which the task-related user exit can movethe qualifier name of the resource manager on each API request. This

exit is called on the QR TCB with the UEPTUTCB bit set. For allother calls, CICS abends the transaction without invoking thetask-related user exit.The

CICS Transaction Server fo r z/OSCustomization GuideVers ion 3 Re le ase 2SC34-6814-04

* (ZERO = NO WORK AREA)UEPGAL DS A ADDRESS OF GLOBAL WORK AREA LENGTHUEPCRCA DS A ADDRESS OF CURRENT RETURN-CODEUEPTCA DS A RESERVEDUEPCSA DS A RESERV

An exit program must make no assumptions about the contents of thePerformance Block and must not attempt to modify it: if it does so, theresults are u

Caller parameter listsIn addition to the DSECTs DFHUEPAR and DFHUERTR, the inclusion ofDFHUEXIT TYPE=RM in the task-related user exit program provides

messages for resource recovery. They are presented explicitly because, after asystem failure, the task driving the exit is not the task that originall

task. But note that, on many invocations of the exit program, parameters 2through 9 do not contain values. See note 1.Parameter 3Address of a 4-charac

1. Parameters 2 through 8 contain values only if the CICS syncpointmanager call is prompted by the issue of an EXEC CICS RESYNCcommand after a session

UERTCABY(X'20') CICS abend, retry possible, TCBs dispatchableUERTCABN(X'10') CICS abend, retry not possible, TCBs dispatchableUERT

UEPEDFRA(X'20') About to display command to EDF.UEPEDFRC(X'10') Command has been displayed to EDF.UEPEDFSC(X'08') EDF us

Note:1. CICS provides a list of named standard attribute bytes that youmay want to use. These standard attribute bytes are containedwithin DFHBMSCA, w

CICS SPI Application Syncpoint Task manager Terminationmanager callContextmanagementcallCICS EDFcallcall program call manager call callDFHUEPAR 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

Apart from register 15, which contains the return code value from the exitprogram, the values in this save area are used by CICS to reload the registe

flag word. When the calling application program subsequently issues a syncpointcommand, or when end-of-task is reached, the CICS syncpoint manager cal

The calling program’s registersThe calling program’s registers are stored at the address specified by UEPHMSA ofDFHUEPAR. Where the calling program is

DFHRMCAL, the task-related user exit is invoked in AMODE 24. For this reason,task-related user exits which have been enabled without the LINKEDITMODEo

v Before passing control to a task-related user exit program, CICS inhibits:– The ability to purge tasks– The monitoring of runaway tasksv While contr

v On each invocation of a task-related user exit program, a new EXECenvironment is created, even when the program is being invoked from the sametask.

The local work areaA local work area is associated with a single task and lasts only for the duration ofthe task. It is for the use of a single task-r

piece of recoverable work to ensure that the CICS syncpoint manager calls the exitprogram during syncpoint processing. (The identification of the curr

manager’s parameter list and the TRUE return codes. (The CICS syncpointmanager parameters are described in “CICS syncpoint manager parameters” onpage

As described in “Increasing efficiency – single-update and read-only protocols” onpage 294, if the UERTONLY bit is set (indicating that the resource m

On receiving a request to perform the first phase of a two-phase commit, theresource manager is expected to get into a state where recoverable changes

Table 1. TCB indicators in DFHUEPAR (continued). DescriptionSymbolicvalue2-bytecodeDescriptionUEPTX9 X9 An X9 open TCB, used for C and C++ programs, c

LimitationsIf your exit program is invoked at end-of-task, you must be alert to possiblelimitations on exit program activity at task-detach. For examp

CICS abend, retry possible, TCBs dispatchable (UERTCABY)MVS has flagged the failure as being “eligible for retry”. Your exit programmust follow the MV

JTRUE1A CSECT TERMINATION TRUE ENTRYPOINTSTM 14,12,12(13) Save registersUSING JTRUE1A,R3LR R3,R15 Use R3 as base registerUSING DFHUEPAR,R1 Address DFH

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 i

Table 16 describes each stage of the interface between the task-related user exitand EDF, relating the descriptions to the (Tn) and (En) expressions i

operators. This section lists what you must do before you can use the adapter, anddescribes the commands used by the supervisor to administer task-rel

capable of waiting for in-doubt resolution. This applies to local resourcessuch as files, and also other RMCs, such as LU6.1, LU6.2, or MROconnections

Chapter 3. The user exit programming interface (XPI)This chapter describes the user exit programming interface (XPI) of CICSTransaction Server for z/O

– Release all storage held by the SEARCH_LDAP function—see “TheFREE_SEARCH_RESULTS call” on page 324.v Using the XPI dispatcher functions, you can:– O

– Inquire about the attributes of a specified program—see “TheINQUIRE_PROGRAM call” on page 366– Inquire about the attributes of the program that is c

If you supply a return code value that is not expected at a particular exit point, thedefault return code indicating a normal response (usually UERCNO

– Inquire about an attached transaction—see “The INQUIRE_TRANSACTIONcall” on page 414– Change the task priority and transaction class of the current t

mandout2(value),...[optout1(value),][optout2(value),]...RESPONSE,REASON]XPI calls follow assembler-language coding conventions:v The “macro-name” must

Note: Failure to clear the parameter list can cause unpredictable results,such as program checks or storage violations. If you are building theparamet

DFHxxyyX. You cannot assume that the arithmetic values of correspondingRESPONSE codes are the same for all macro calls. The meanings of theRESPONSE co

If a DFHDSSRX SUSPEND or WAIT_MVS call does not specify anINTERVAL, and gets this RESPONSE with a REASON of‘TASK_CANCELLED’ or ‘TIMED_OUT’, it indicat

The XPI copy booksThere is a copy book for each XPI function, to provide the DSECTs associated withthat function. These DSECTs allow you to map the pa

in the first 4 bytes of the LIFO storage addressed by UEPXSTOR. In this example,the initialization of the parameter list (using the CLEAR option), the

TITLE ’GUEXPI - GLOBAL USER EXIT PROGRAM WITH XPI’************************************************************************** The first three instructi

*************************************************************************** Before issuing an XPI function call, set up addressing to XPI ** parameter

************************************************************************** Test SMMC_RESPONSE -- if OK, then branch round error handling. ************

storage. However, on an EXEC CICS GETMAIN command, the exit program canoverride the TASKDATAKEY option by specifying either CICSDATAKEY orUSERDATAKEY.

An example showing how to build a parameter list incrementallyIn the following example, the parameter list is built incrementally. The initialization

OUT, *ADDRESS((R6)), *RESPONSE(*), *REASON(*)ImportantYou must set your parameters using only the XPI functions.XPI syntaxThe XPI functions use specia

len The data length as {namel | (Rn) | expression}:namel The name of a location containing a binary fullword givingthe data length in bytes(Rn) A regi

(Rn) A register, the contents of which specify in fullword binarythe maximum number of bytes of dataexpressionA decimal integer, or any arithmetic exp

CACHE_SIZE(name4)a fullword that specifies the number of bytes available for caching LDAP searchresults. A value of zero indicates an unlimited cache

RESPONSE REASONKERNERROR NonePURGED NoneNote: For more detail, refer to the explanation of RESPONSE and REASON in“Making an XPI call” on page 308.The

[OUT,[LDAP_RESPONSE(name4),]RESPONSE(name1 | *),REASON(name1 | *)]This command is threadsafe.LDAP_RESPONSE(name4)specifies the return code that is sen

RESPONSE REASONINVALID NoneKERNERROR NonePURGED NoneNote: For more detail, refer to the explanation of RESPONSE and REASON in“Making an XPI call” on p

VALUE_ARRAY_POSITION(name4)specifies the position of the requested value, in the value array for the currentattribute. This parameter is only required

VALUE_COUNT(name4)a fullword containing the number of values returned for this attribute. There isusually one value returned.RESPONSE and REASON value

v Otherwise, use the EXEC CICS ENABLE command to enable the user exitprogram.If you enable a global user exit program before it has been installed and

SEARCH_TOKEN(name4)the name of the fullword token that is returned by the SEARCH_LDAP function.RESPONSE and REASON values for GET_NEXT_ENTRY:RESPONSE

address of the data, and the second word contains the length in bytes of thedata. For more information on block-descriptors, see “XPI syntax” on page

[LDAP_RESPONSE(name4),][ATTRIBUTE_COUNT(name4),]RESPONSE(name1 | *),REASON(name1 | *)]This command is threadsafe.DISTINGUISHED_NAME(buffer-descriptor)

This command is threadsafe.LDAP_RESPONSE(name4)specifies the return code that is sent by the LDAP API.LDAP_SESSION_TOKEN(name4)the name of the fullwor

The normal synchronization protocolIn the normal case, synchronization involves two tasks and three operations. In thefollowing sample operations, the

Because task-purging is effective only if performed between SUSPEND andRESUME, Suspend-fail precedes Resume-fail. This means that, with the sameconstr

The ADD_SUSPEND callADD_SUSPEND acquires a suspend token that can later be used to identify aSUSPEND/RESUME pair.ADD_SUSPENDDFHDSSRX [CALL,][CLEAR,][I

name4The name of a 4-byte field where the token is stored(Rn) A register into which the token value is loaded.RESPONSE and REASON values for ADD_SUSPE

depends on the setting of the TIME_UNIT option. The INTERVAL valueoverrides any time-out (DTIMOUT) value specified for the transaction.name4The name o

name8The name of the location where an 8-byte value is stored.string A string of characters without intervening blanks; if it is not 8 bytes long,it i

– If the new program supplies a different return code value from the currentvalue addressed by UEPCRCA, CICS ignores both values and resets the“curren

IO Waiting on an I/O operation or indeterminate I/O-related operation (locks,buffer, string, and so on).LOCKWaiting on a lock.MISCWaiting on an uniden

attach) has expired. The token, however, remains suspended and mustbe the object of a RESUME before it can be the object of aDELETE_SUSPEND.The RESUME

2. ‘TASK_CANCELLED’ means that the task was canceled by operatoraction while it was suspended, and that the suspend token is availablefor use.The DELE

Note: ECBs used in WAIT_MVS requests must never be “hand posted”. They mustbe posted using the MVS POST macro.WAIT_MVSDFHDSSRX [CALL,][CLEAR,][IN,FUNC

Table 18. WAIT_MVS call - RESPONSE(PURGED) (continued)CONDITION PURGE FORCEPURGE DTIMOUT INTERVALPURGEABLE (NO) Canceled Proceeds normally Canceled Pr

MILLI_SECONDThe INTERVAL option specifies the number of milliseconds beforetimeout.WLM_WAIT_TYPE(name1)specifies, in a 1-byte location, the reason for

RESPONSE and REASON values for WAIT_MVS:RESPONSE REASONOK NoneEXCEPTION NoneDISASTER NoneINVALID NoneKERNERROR NonePURGED TASK_CANCELLEDTIMED_OUTNote:

literalconstA number in the form of a literal, for example B'00000000', X'FF',X'FCF4', "0" or an equate symbol

here appears in the dump header, so you could use it to identify the exitprogram that initiated the system dump request. For a description of validblo

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

If a CICS DB2 application program has been written and defined as threadsafe toobtain the benefits of the CICS open transaction environment (OTE), the

end of the list must be marked by a word containing X'FFFFFFFF'. SEGMENTand SEGMENT_LIST are mutually exclusive.TCA(NO|YES)specifies whether

Note:1. For more detail, refer to the explanation of RESPONSE and REASON in“Making an XPI call” on page 308.2. ‘NOT_OPEN’ means that the CICS dump dat

rather than enqueue name, allowing the NQ domain to locate the enqueuecontrol block directly, and hence more efficiently.MAX_LIFETIME(DISPATCHER_TASK)

The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, andMAX_LIFETIME(DISPATCHER_TASK) parameters are the same as in theENQUEUE function call.RESPONSE and

STOP_PURGE_PROTECTIONDFHKEDSX [CALL,][CLEAR,][IN,FUNCTION(STOP_PURGE_PROTECTION),][OUT,RESPONSE (name1 | *)]This command is threadsafe.There are no in

The DEFINE_PROGRAM callDEFINE_PROGRAM allows you to define new programs to the loader domain, or tochange the details of programs that have already be

Table 19. Summary of attributes defining DSA eligibility (continued)EXECUTION_KEYoptionReentrant Above or below16MB lineDynamic storagearea (DSA)CICS

PRIVATEThe program is in the DFHRPL or dynamic LIBRARY concatenation. APRIVATE program need not be reentrant, and is given only limitedprotection from

RESPONSE REASONCATALOG_NOT_OPERATIONALDISASTER NoneINVALID NoneKERNERROR NonePURGED NoneNote: For more detail, refer to the explanation of RESPONSE an

name1The name of a 1-byte location to receive the program attribute.(Rn) A register in which the low-order byte receives the program attributeand the

v Share a GWA between global user exit programs, thereby making the informationit contains available to more than one program, and overcoming limitati

RESPONSE and REASON values for ACQUIRE_PROGRAM:RESPONSE REASONOK NoneEXCEPTION NO_STORAGEPROGRAM_NOT_DEFINEDPROGRAM_NOT_FOUNDDISASTER NoneINVALID None

name8The name of a location containing an 8-byte program name.string A string of characters naming the program."string"A string in quotation

string A string of characters naming the program."string"A string in quotation marks. The string length is set to 8 by padding withblanks or

RESPONSE REASONINVALID NoneKERNERROR NoneThe SET_PARAMETERS callSET_PARAMETERS allows you to set the activity keypoint frequency for the CICSregion.SE

INQUIRE_MONITORING_DATA calls cannot be used in any exit program invokedfrom any global user exit point in DFHTCP or DFHZCP (that is, at any of the ex

expressionA valid assembler-language expression giving the fullword binaryvariable for this EMP.name4The name of a 4-byte field containing the fullwor

"string"A string, enclosed in quotation marks, and possibly containing blanks.This value is processed in the same way as the “string” above.

The DFHMNTDS DSECT that maps the data is of fixed format. Note that:v All the CICS system-defined fields in the performance records (including fieldst

Program management XPI functionsThere are eight XPI program management functions. These are the DFHPGISXcalls:INQUIRE_PROGRAMINQUIRE_CURRENT_PROGRAMSE

[PROGRAM_LENGTH(name4),][PROGRAM_TYPE(NOT_APPLIC|PRIVATE|SHARED|TYPE_ANY),][PROGRAM_USAGE(APPLICATION|NUCLEUS),][PROGRAM_USE_COUNT(name4),][PROGRAM_US

v Uses the START option of the EXEC CICS ENABLE command to makeDFH$PCEX available for execution. This causes DFH$PCEX to be driven forall LINKs and XC

THREADSAFEThe program is defined as threadsafe, and is able to run underwhichever TCB is in use by its user task when the program is givencontrol. Thi

USER CICS gives control to the program in user key. The program is loadedinto a user DSA, above or below the 16MB line; that is, the UDSA orEUDSA, dep

LANGUAGE_DEFINED(ASSEMBLER|C370|COBOL|LE370| NOT_APPLIC|NOT_DEFINED|PLI)returns the programming language specified on the resource definition.LIBRARY(

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 DFHRPL or dynamic LIBRARYconcatenation.. A PRIVATE program

RESPONSE and REASON values for INQUIRE_PROGRAM:RESPONSE REASONOK NoneEXCEPTION PROGRAM_NOT_DEFINED_TO_LDPROGRAM_NOT_DEFINED_TO_PGDISASTER ABENDLOCK_ER

This command is threadsafe.Note: The options not described in the following list are identical to the equivalentoptions of the INQUIRE_PROGRAM call.CU

where a global user exit program or task-related user exit program is involved,the options return information about the exit program.INVOKING_ENVIRONM

SET_PROGRAMDFHPGISX [CALL,][CLEAR,][IN,FUNCTION(SET_PROGRAM),{PROGRAM_NAME(name8 | string | ’string’)|PROGRAM_TOKEN(name4)},][AVAIL_STATUS(DISABLED|EN

FULLAPICICS links to and runs the program without the API restrictionsof a remote DPL program. The program can use the full CICSAPI.PROGRAM_ATTRIBUTE(

Note!Before using this information and the product it supports, be sure to read the general information under “Notices” on page923.This edition applie

Example programAs well as the sample programs supplied in source code, there is an examplelisting, DFH$XTSE, that shows you how to:v Use EXEC CICS com

TYPE_ANYEither the copy in the DFHRPL or a dynamic LIBRARY concatenation,or the LPA copy of the program can be used, though preference isgiven to the

The START_BROWSE_PROGRAM callSTART_BROWSE_PROGRAM returns a token that enables you to begin browsingthrough program definitions, optionally starting a

The GET_NEXT_PROGRAM callGET_NEXT_PROGRAM allows you to inquire on the next program definition duringa browse sequence initiated by START_BROWSE_PROGR

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 ne

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 XPI functionsThe state data access functions allow you to inquire on and set certain system datain the AP domain.The INQ_APPLICATION

* The parameter list itself, in name APIQ_EIB, is used to hold theaddress.RSA(name4 | (Rn|*)returns the address of the register save area for the curr

name4The name of a 4-byte area that is to receive the length, in bytes, of theTWA.(Rn) A register that is to receive the length of the TWA.* The param

[TIMEOFDAY(name4| *),][XRFSTATUS(NOXRF | PRIMARY | TAKEOVER),]RESPONSE (name1|*),REASON (name1|*)]This command is threadsafe.CICSREL(name4 | *)returns

DFH$DTRDA sample global user exit program, designed to be invoked at the XDTRDexit.DFH$DTAD, DFH$DTLC, and DFH$DTRD are listed in the CICS Shared Data

name4The name of a 4-byte location that is to receive the date.DTRPRGRM(name8 | *)returns the name of the dynamic routing program.name8The name of an

name2The name of a 2-byte area that is to receive, as a half-word binaryvalue, the level number of the MVS element of OS/390. For example,OS/390 Relea

NOTSHUTDOWNCICS is not in shutdown mode.SHUTDOWNCICS is performing an immediate shutdown.STARTUP(COLDSTART|EMERGENCY|WARMSTART)returns the type of sta

RESPONSE REASONINVALID INVALID_FUNCTIONEXCEPTION LENGTH_ERRORUNKNOWN_DATADISASTER INQ_FAILEDPURGED NoneThe SET_SYSTEM callThe SET_SYSTEM call allows y

RESPONSE and REASON values for SET_SYSTEM:RESPONSE REASONOK NoneINVALID INVALID_FUNCTIONEXCEPTION AKP_SIZE_ERRORNO_KEYPOINTDISASTER SET_FAILEDPURGED N

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 subj

2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request wasspecified with SUSPEND(NO), and there was not enough storageavailable to satisfy the r

[OUT,ACCESS(CICS | READ_ONLY | USER),RESPONSE(name1 | *),REASON(name1 | *)]This command is threadsafe.ACCESS(CICS|READ_ONLY|USER)returns the access-ke

ELEMENT_ADDRESS(name4 | (Rn) | *)returns the start address of the element of task-lifetime storage referenced bythe ADDRESS parameter. The start addre

a batch update run that has overridden retained locks. See “DFH$FCBVsample global user exit program” on page 134.DFH$FCLDA sample exit program designe

RESPONSE and REASON values forINQUIRE_SHORT_ON_STORAGE:RESPONSE REASONOK NoneDISASTER NoneKERNERROR NoneThe INQUIRE_TASK_STORAGE callINQUIRE_TASK_STOR

RESPONSE REASONNO_TRANSACTION_ENVIRONMENTDISASTER NoneINVALID NoneKERNERROR NonePURGED NoneThe SWITCH_SUBSPACE callSWITCH_SUBSPACE causes CICS to swit

The TRACE_PUT callTRACE_PUT writes a trace entry to the active trace destinations. You should onlymake a TRACE_PUT call when UEPTRON indicates that tr

expressionA valid assembler-language expression that results in the addressname4The name of a fullword containing the address(Ra) A register containin

name8The name of an 8-byte location to receive the name of the bridge exitprogram.BRIDGE_TRANSACTION_ID(name4)returns the name of the bridge monitor t

The INQUIRE_DTRTRAN callINQUIRE_DTRTRAN returns the name of the dynamic transaction routing (DTR)transaction definition.The DTR transaction definition

MXT_QUEUED(name4 | (Rn) ),TCLASS_QUEUED(name4 | (Rn) ),RESPONSE (name1 | *),REASON (name1 | *)]This command is threadsafe.CURRENT_ACTIVE(name4 | (Rn))

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

[SHUTDOWN(name1),][SPURGE(name1),][STATUS(name1),][STORAGE_CLEAR(name1),][STORAGE_FREEZE(name1),][SYSTEM_ATTACH(name1),][SYSTEM_RUNAWAY(name1),][TASKD

PROXY=proxyurlThis optional keyword stores the URL (in the form http://proxyserver) of aproxy server into the Web global work area, then enables the s

XMXD_NOA transaction dump is not required.DYNAMIC(name1)returns, in a 1-byte location (name1), an equated value indicating whether thetransaction is d

name4The name of a 4-byte location that contains the name of the transactionidentifier.string A string of characters, without intervening blanks, nami

XMXD_OWNThe reserved name OWN is specified for the partitionset, which meanstasks running under this transaction definition perform their ownpartition

XMXD_NOThe transaction cannot be restarted.XMXD_YESThe transaction can be restarted.ROUTABLE_STATUS(ROUTABLE|NOT_ROUTABLE)returns a value indicating w

STORAGE_CLEAR(name1)returns, in a 1-byte location (name1), an equated value indicating whethertask-lifetime storage, of tasks associated with this tra

TCLASS(name1)returns, in a 1-byte location (name1), an equated value indicating whether thetransaction belongs to a transaction class.XMXD_NOThe trans

name4The name of a 4-byte location that contains the name of the transactionidentifier.TWASIZE(name4 | (Rn))returns the size of the transaction work a

[TASK_PRIORITY(name1),][TCLASS(name1),[TCLASS_NAME(name8),]][TERMINATE_PROTECTED(name1),] [TPURGE(name1),][TRANNUM(name4 | string | 'string'

XMIQ_TDThe principal facility is a transient data queue.XMIQ_TERMINALThe principal facility is a terminal.NETNAME(name8)returns the network name of th

START_CODE(name1)returns, in a 1-byte location (name1), an equated value indicating how the taskwas started:C A CICS internal attach.XMIQ_DFThe start

racfcid=uuuuuuuuis the current userid, obtained from UEPUSERibm-httprealm=rrrrrrrris the HTTP 401 realm, obtained from UEPREALM (if this exists)labele

TRANNUM(name4)returns the task number of the transaction.name4The name of a 4-byte location to receive the task number.TRANSACTION_TOKEN(name8)specifi

TASK_PRIORITY(name4)specifies the new task priority being set for the task identified byTRANSACTION_TOKEN.name4The name of a 4-byte location that cont

WRITE_JOURNAL DATADFHJCJCX [CALL,][CLEAR,][IN,FUNCTION(WRITE_JOURNAL_DATA),FROM(block-descriptor),JOURNALNAME(name8 | string | ’string’ ) |JOURNAL_REC

RESPONSE REASONJOURNAL_NOT_OPENLENGTH_ERRORSTATUS_ERRORDISASTER NoneINVALID NoneKERNERROR NonePURGED NoneNote: For more detail, refer to the explanati

422 Customization Guide

Part 2. Customizing with initialization and shutdown programs© Copyright IBM Corp. 1977, 2011 423

424 Customization Guide

Chapter 4. Writing initialization and shutdown programsYou can write programs to run during the initialization and shutdown phases ofCICS processing.

v First phase PLTPI programs must not enable any task-related user exit programwith the TASKSTART option.v Because first-phase PLT programs run so ear

Note: A pseudo-terminal:– Must be a surrogate TCTTE that exists only in an AOR– Can be used only in a transaction routing environment– Cannot exist wi

Note: It is not necessary to specify a pipeline in the DFHWS-PIPELINEcontainer. The pipeline is dynamically created by DFHPIRT whenCHANNEL(DFHWSTC-V1)

Writing shutdown programsAny program that is to execute during CICS shutdown must be defined in aprogram list table (PLT), and the PLT must be named o

to be started, and they cannot communicate with terminals. Further, second phasePLT programs must not cause any resource security checking or DB2 call

program causes the relevant unit of work to be shunted. The PLTPI programabends ASP1, and CICS runs the next program defined in the PLTPI table, if an

1. Create a separate PROGRAM resource definition using the same JVMCLASSattribute value and specify EXECKEY(CICS).2. Add the PROGRAM resource definiti

432 Customization Guide

Part 3. Customizing with user-replaceable programs© Copyright IBM Corp. 1977, 2011 433

434 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 theCICSTS32.CICS.SDFHS

2 The library into which the load module will be link-edited.3 Optionally, the name of a library containing your local Assembler macros andcopy member

Related concepts“The sample XMEOUT global user exit programs” on page 171The MRO and APPC session queue management sample exitprogramThis sample progr

Data storage key for user-replaceable programsThe storage key of storage used by user-replaceable programs depends on howthe storage is obtained:v The

Chapter 6. Writing a program error programConsiderations common to all user-replaceable programsNote that the comments contained in Chapter 5, “Genera

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 ‘AS

DFHEISTG DSECT ,** Insert your own storage definitions here*DFHPCOM TYPE=DSECT************************************************************************

DFHPEP_COMMAREA DSECT** Standard header section*PEP_COM_STANDARD DS 0FPEP_COM_FUNCTION DS CL1 Always ’1’PEP_COM_COMPONENT DS CL2 Always ’PC’PEP_COM_RE

The sample program error programsTwo source-level versions of the default program are provided: DFHPEP, coded inassembler language, and DFHPEPD, coded

444 Customization Guide

Chapter 7. Writing a transaction restart programThe transaction restart user-replaceable program (DFHREST) enables you toparticipate in the decision a

v The transaction abend which caused the transaction to be terminating abnormallymust have been detected before the commit point of the implicit syncp

The equated values for this parameter are:XMRS_WRITE_YESMeans a terminal write has been performed by the transaction.XMRS_WRITE_NOMeans a terminal wri

XPCTA exit, to test whether the abend was caused by a storage protectionexception condition. It is described on page “The sample XPCTA globaluser exit

v AFCW, indicating that the transaction abended due to a VSAM-detecteddeadlock (RLS only).The source of the CICS-supplied default transaction restart

Chapter 8. Writing a terminal error programConsiderations common to all user-replaceable programsNote that the comments contained in Chapter 5, “Gener

version of the terminal error program (DFHTEP, either CICS-supplied oruser-written), so that it can take the appropriate action.Terminal control progr

The communication areaThe communication area is the basic interface used by the sample DFHTEP, andshould be used by a user-written DFHTEP to:v Address

of as the number of error occurrences that are permitted for a given type of error ona given terminal before the sample DFHTEP accepts the DFHTACP def

An ESE records the occurrence of a particular type of error associated with theterminal. The contents of an error status element are described in the

Figure 22 on page 456 gives an overview of the structure of the sample terminalerror program.Entry and initializationOn entry, the sample TEP uses DFH

General exitControl is passed to a general exit routine from each error processor. This routinedetermines whether the terminal is to remain in service

Sample terminal error program messagesThe messages logged to the transient data destination CSMT (or, optionally, to thedestination specified in the O

of each type of message by using the appropriate parameters specified on thePRINT operand of DFHTEPM TYPE=INITIAL.These messages are:DFHTEP, ERROR – e

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXDTAD Data tablesmanagementWhen

This message contains the symbolic terminal ID of the device associated withthe error. This message can be suppressed by using the NOTID option.DFHTEP

macros are related and care must be taken to ensure compatibility. The parametersconcerned are identified in the descriptions of the macros later in t

TYPE=INITIALestablishes the beginning of the generation of the sample DFHTEP moduleitself.DSECTPR={YES|NO}controls the printing of CICS DSECTs on the

TIMEThis type of threshold testing is supported.NOTIMEThis type of threshold testing is not supported.PRINT=print-informationspecifies which types of

TACLE|NOTACLEspecifies whether the TACLE prefix is to be recorded on the transient datadestination.TACLEThe 16-byte TACLE prefix as received from DFHT

TYPE=ERRPROCindicates that a CICS-supplied error processor routine is to be replaced with theuser-written error processor that immediately follows the

DFHTEPT–generating the sample DFHTEP tablesThe following macros are required to generate the terminal error program tables:v DFHTEPT TYPE=INITIAL—to e

DFHTEPT TYPE=INITIAL–establishing the control sectionThe DFHTEPT TYPE=INITIAL macro necessary to establish the control section forthe TEP tables is:TY

TYPE=PERMTIDdefines permanently reserved terminal error blocks for specific terminals.Permanent TEBs are defined for terminals that are critical to sy

default actions to be taken. If the number of occurrences is less than thethreshold, the error processor normally takes a logic path that overrides th

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXFCBFAIL File control recoveryc

Table 23 illustrates the default thresholds of the sample terminal error program,referred to in the TYPE, COUNT, and TIME operands of the DFHTEPTTYPE=

DFHTEPT TYPE=FINAL–terminating DFHTEPT entriesThe DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEPtables.DFHTEPT–examples of how the m

Writing your own terminal error programYou can write your own terminal error program in any of the languages supportedby CICS. However, CICS-supplied

Addressing the contents of the communication areaAfter your terminal error program receives control from DFHTACP, it should obtainthe address of the c

ABORTWR (X'08')Abend write, free terminal storageRELTTIOA (X'04')Release TCAM incoming message. (TCAM is no longer supported.)SIGN

and DFHTACP writes the ‘DFHTC2522 INTERCEPT REQUIRED’ message toCSMT; if the task is not marked nonpurgeable, it is abended with code ‘AEXY’ or,rarely

After you have carried out the required functions and, optionally, altered the defaultactions scheduled by DFHTACP, the user-written DFHTEP must retur

Example of a user-written terminal error programThe “DFHTEP recursive retry routine” on page 476 is an example of the logic stepsnecessary to design a

(PCICNT)represents a user-defined field used to accumulate the count of recursiveerrors. It should be in the process control information (PCI) area of

*ASM XOPTS(NOPROLOG NOEPILOG SP)************************************************************************* ** DFHTEP RECURSIVE RETRY ROUTINE ** *******

ContentsPreface ...xviiWhat this book is about ...xviiWho this book is for ...xviiWhat y

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXICEREQ Interval control EXECin

Note that the code in Figure 28 on page 477 is intended only as an illustration of arecursive error handling technique and of the steps necessary to e

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

redirecting to another. With messages sent with exception-response only, CICSmay not have the data available to send it again, but the requesting appl

The action flags can be set or reset within DFHZNEP.The action flags set by DFHZNAC for specific error codes and sense codes arelisted in Appendix B,

other, reusable NEBs for general use. If you expect to accumulate error statisticsabout 10 LUs concurrently, you need 10–12 NEBs.Each NEB may contain

will then locate the correct ESB within a selected NEB. The latter may bepermanently dedicated to the LU in error (a named NEB), or may be one takenfr

The 3270 sample code is not intended to cover all error conditions. Note that thecode is not suitable for SNA 3270s (LU session type 2). Error conditi

You also have to provide the sub-NEPs for the various NEP transaction classes,including, of course, one for the default NEPCLASS(0). Each of these sub

DFHZNAC assumes that system sense codes are available upon receipt of anexception response from the logical unit. Thus, analysis is performed to deter

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXPCABND Program controlprogramA

The significance of each section of the communication area is described below:HeaderA 4-byte header common to all user-replaceable programs.Error_bein

************************************************************************ 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

causes CICS to take a system dump when there is no task attached to theterminal at the time of error detection, if the flag TWAOAT in TWAOPT2 is alsos

“good morning” message transaction is initiated (the transaction specified by thesystem initialization parameter GMTRAN).The flags are:TWAOAS (X'

TWAONCN (X'10')Normal CLSDST (no reset allowed)TWAOSCN (X'08')Normal CLSDST (reset allowed)TWAONEGR (X'04')Send negative

TWANLD of the communication area, and the length of the data in field TWANLDL.The data is logged to the CSNE transient data queue for future inspectio

The sample node error programThe sample node error program provides a general environment for the executionof error processing routines (error process

v Optional error processors for 3270 or interactive logical units. A node errorprogram cannot be generated with both 3270 and interactive logical unit

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXSZARQ Front EndProgramming Int

Optional common subroutinesThe common subroutines are addressed via the CSVT and provide error processorswith the following functions:v Locate or assi

Optional error processor for interactive logical unitsOnly one error processor is supplied for interactive LUs: group index 1, with errorcode X'D

DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEPTYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL.The DFHSNEP TYPE=USTOREND macro

DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=(D9,DC,DD,F2)Sense/status error processor code.DFHSNEP TYPE=ERRPROC,GROUP=2,CODE=42Unavailable printer error process

in the range X'01' through X'FF' (a leading zero can be omitted). The errorprocessor name has the form NEPROCxx, where “xx” is the

4. Registers 4 through 9 can be saved by common subroutines in an areareserved in EXEC interface storage at label NEPCSRS. They must berestored before

specified in the COUNT operand is not exceeded before this time intervalelapses, the error count is reset to 0. Specify “units” as SEC, MIN, or HRS. T

CSVTESBL DS A NEPESBL - ESB locate routineCSVTNEBD DS A NEPNEBD - NEB delete routineCSVTECUP DS A NEPECUP - error count updateroutineWriting your own

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

Table 2. Alphabetical list of global user exit points (continued)Exit name Module or domain Where or when invoked TopicXWBAUTH Web domain During proce

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 u

Handling shutdown hung terminals in the node error programError Code: X'6F'Symbolic Name: TCZSDASMessage Number: DFHZC2351For error code X&a

system-wide recovery notification options (whether terminal users are notified of arecovery, the recovery message, or the recovery transaction) for so

Changing the recovery messageIf you define a terminal with RECOVNOTIFY(MESSAGE) in its TYPETERMdefinition, a recovery message is sent to the terminal

the others have all been shut down), the ISSUE PASS command does not fail withan INVREQ. Instead, the terminal is logged off and message DFHZC3490 is

514 Customization Guide

Chapter 10. Writing a program to control autoinstall ofterminalsConsiderations common to all user-replaceable programsNote that the comments contained

v Create some model TERMINAL definitions.v Define the terminals to VTAM, so that their definitions in VTAM match the modelTERMINAL definitions in CICS

Coding entries for MTSYou need to define model names (MDLTAB, MDLENT, and MDLPLU macros) andprinter and associated printer names (ASLTAB, ASLENT, and

Global user exit points by functional areaThe exit points are grouped according to their functional relationships. This usuallymeans according to the

v Autoinstall processing has been completed to a point where information (aterminal identifier and autoinstall model name) from the control program is

The control program selects one model from this list, and CICS uses this model tobuild the TCTTE for the device. The default autoinstall control progr

model name into the model name list (Autinstmodelname_1), and also into themodel name field (Modelname) in the selection list addressed by fullword 4

used to name a CONNECTION. It should therefore conform to the namingstandards for a CONNECTION (rather than a TERMINAL) as defined inCONNECTION defini

As a general rule, all the models in the list passed to your program match theVTAM data for the terminal. That is, a viable TCT entry usually results

However, you may be in a situation where you must continue to use unique andpredictable TERMINAL names for your terminals. Your control program must b

satisfactory, CICS schedules the new resource for OPNDST in order to completethe logon request. If the installation process fails, then the control pr

The autoinstall control program at DELETETo provide symmetry of control over the autoinstall process, the autoinstall controlprogram is also invoked w

Table 27. Autoinstall control program’s parameter list at DELETE (continued)1st byte 2nd byte 3rd byte 4th byteThird fullword Length of netname to bed

If CICS attempts to BIND, compare the device’s CINIT RU to the CICS BIND, andmake corrections accordingly.It is very important that you ensure that th

Return codesUERCNORMContinue processing.XPI callsXPI must not be used.API and SPI callsThe following commands are supported:v ADDRESS CWAv ADDRESS EIB

The default action of the sample program, on INSTALL, is to select the first modelin the list, and derive the terminal identifier from the last four n

* REGISTER CONVENTIONS = ** R0 used by DFHEICAL expansion ** R1 -------"-------"------"---- ** R2 Base for Input parameters ** R3 Base

COBOLFigure 41 on page 531, in COBOL, redefines the NETNAME, so that the last fourcharacters are used to select a more suitable model than that select

PL/IFigure 42 on page 532, 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

534 Customization Guide

Chapter 11. Writing a program to control autoinstall ofconsolesConsiderations common to all user-replaceable programsNote that the comments contained

Note:1. You can have only one active autoinstall control program to handleterminals, consoles, and APPC connections. You specify the name ofthe active

The parameter list contains the following information:1. A standard header. Byte 1 indicates the request type (this is hexadecimalcharacter X'FD&

UERCNORMContinue processing.XPI callsAll can be used.API and SPI callsAll can be used, except for:v EXEC CICS ABENDv EXEC CICS PERFORM SHUTDOWNSample

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 by

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 autoinstall control programs for consolesIBM supplies a default autoinstall control program, written in each of the supportedprogramming la

542 Customization Guide

Chapter 12. Writing a program to control autoinstall of APPCconnectionsConsiderations common to all user-replaceable programsNote that the comments co

Like autoinstall for other resources, autoinstall for APPC connections requires modeldefinitions. However, unlike the model definitions used to autoin

The autoinstall control program for APPC connectionsThe purpose of the autoinstall control program is to provide CICS with any extrainformation it nee

INSTALL_APPC_STANDARD headerA fullword input field comprising the following information:INSTALL_APPC_EXIT_FUNCTIONA 1-byte field that defines the inst

INSTALL_APPC_SS_BINDX'F4' represents an install request for an APPC single-sessionconnection via a BIND.Note: The values X'F0' and

v Use the mapset name, map name, and field length defined in the map, and theactual length of field data placed in the outbound datastreamv Modify the

Your control program can use the TEMPLATE_NETNAME field to specify theNETNAME of the template. For connections between generic resources, yourprogram

The autoinstall control program at DELETETo provide symmetry of control over the autoinstall process, the autoinstall controlprogram is also invoked w

Synclevel 1 connections installed via a BINDSynclevel 1-only APPC connections autoinstalled via a BIND request (except forlimited resource connections

Note: This type of request cannot be received by CICS TransactionServer for z/OS, Version 3 Release 2.INSTALL_APPC_PS_BIND (X'F3')An incomin

552 Customization Guide

Chapter 13. Writing a program to control autoinstall of IPICconnectionsConsiderations common to all user-replaceable programsNote that the comments co

You can use any installed IPCONN definition as a template but, for performancereasons, your template must be an installed definition that is not in us

If the default user program is not adequate for your purposes, you can write acustomized version of the default program or create your own program to

isaic_networkid (Input)An 8-character field containing the network ID of the system trying to connect,as sent on the connect flow.isaic_port (Input/Ou

isaic_function (Input)The function for which the user program has been invoked:X'F1' After deletion of an IPCONN.isaic_ipconn (Input)The nam

UEPBMTCTAddress of the TCTTE associated with the mapping request.UEPEXECBAddress of the system EIB associated with the task.UEPBMCNTAddress of the hal

Default actions of the sample programThe role of the autoinstall user program in installing IPCONNs is to choose theIPCONN template to be used and to

Chapter 14. 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 detect

terminal. If, during the delay interval, the terminal definition is deleted, re-shipped,and re-installed with a different local TERMID, the started tr

autoinstall control program at INSTALL” on page 536. The parameter list passed atINSTALL of local APPC connections initiated by BIND requests is descr

(the value of the TERMINAL or CONNECTION attribute on the shippeddefinition) is already in use in the AOR to identify an installed remoteterminal or c

installed, and stored within the definition. Thus, if the definition is shipped toanother region, the value of the token is shipped too. The correlati

DELETE_SHIPPED_TERM (X'FA')A shipped terminalDELETE_SHIPPED_RSE (X'FB')A shipped connection (remote system entry).DELETE_SHIPPED_T

566 Customization Guide

Chapter 15. Writing a program to control autoinstall of virtualterminalsVirtual terminals are used by the External Presentation Interface (EPI) and te

BMXACTLNis a halfword binary value which contains the actual length of the data receivedor transmitted in this field.BMXDATAis the address of the fiel

TERMIDs generated by CICS for Client terminals consist of a 1-character prefixand a 3-character suffix. The default prefix is '\', but you c

same AOR. However, if you are using CICS-generated TERMIDs, your serverprograms must not rely on TERMIDs being allocated consistently to particular Cl

If a name clash occurs in an AOR, the autoinstall control program is invoked in theAOR. It can resolve the conflict by allocating an alias terminal id

v The USERID of the first transaction in a pseudoconversation can be obtainedusing EXEC CICS ASSIGN USERID.v The TRANSID of the first transaction in a

Note: The communications area for INSTALL of virtual terminals is the same asthat for INSTALL of shipped terminals and connections—that is why the fie

SELECTED_SHIPPED_TERMIDA 4-character field used to specify the name by which the virtualterminal will be known to CICS. If the name is less than 4 cha

INSTALL_BRFAC_STANDARDA fullword input field containing the following information:INSTALL_BRFAC_EXIT_FUNCTIONA 1-byte field that indicates the type of

RETURN_OK (X'00')Install the virtual terminal. This is the default value. Your userprogram must return this value if the resource is to beau

DELETE_SHIPPED_EXIT_FUNCTIONA 1-byte field that indicates the type of resource being deleted. The equatedvalue for Client virtual terminals is DELETE_

INSTALL_LINK_BRFAC (X'10')The autoinstall program was called during installation of a bridge facilityto be used by the Link3270 bridge.INSTA

File control EXEC interface API exits XFCREQ and XFCREQC ...85File control EXEC interface SPI exits XFCAREQ and XFCAREQC ...98File control file s

When modifying data in the XBMIN exit, the safest method is to use the lengthprovided in BMXMAPLN, but to ensure that any pad characters added by BMS

578 Customization Guide

Chapter 16. 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

Note: This assumes that the autoinstall control program chooses not toinstall a definition. If no definition is installed because autoinstallfails, th

Faster startup timesWarm and emergency startsIf you are using program autoinstall with cataloging, restart times are similar tothose of restarting a C

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 t

PGAC_EXECUTION_SETallows you to specify, in a 1-byte field, whether or not the program is restrictedto using the distributed program link (DPL) subset

shared resources it takes into account the possibility that otherprograms may be executing concurrently and attempting to modify thesame resources.PGA

If you customize the supplied control program, or write your own version, youshould note the following:v Input:The first two fields of the parameter l

Exit-specific parametersUEPFAREQAddress of a 1-byte field that indicates why the exit has beencalled. Possible values are:UEPFAINInitialization.UEPFAT

group containing the definitions in your startup grouplist. If you specify an invalidname for the control program, CICS disables the program, thus dis

Chapter 17. Writing a dynamic routing programConsiderations common to all user-replaceable programsNote that the comments contained in Chapter 5, “Gen

3. “Routing bridge requests dynamically” on page 6034. “Routing by user ID” on page 6075. “Parameters passed to the dynamic routing program” on page 6

v After the routed transaction has completed, if the routing program has requestedto be reinvoked at termination.v If the routed transaction abends, i

Sometimes, the dynamic routing program may be invoked for transactions that arerouted statically. This happens if a transaction defined as DYNAMIC(YES

ImportantTo route a transaction defined by the DTRTRAN definition, your dynamic routingprogram must set the DYRDTRRJ field of the communications area

If the system is unavailable or unknownThe dynamic routing program is invoked again if the remote system name that youspecify on the route selection c

Modifying the initial terminal dataThe dynamic routing program should not perform an EXEC CICS RECEIVE or anEXEC CICS GDS RECEIVE command, because thi

may also need to change the input communications area passed to the routedapplication. Field DYRACMAA of the routing program’s communications areaenab

result of logic in the routed transaction. You should also consider carefully theeffect of EXEC CICS SYNCPOINT and ABEND commands on APPC transactionr

Return codesUERCNORMContinue processing.XPI callsAll can be used, except those that use recoverable resources.API callsAll can be used except those th

v Distributed Computing Environment (DCE) remote procedure calls (RPCs)v ONC/RPC calls.A program-link request received from outside CICS can be dynami

Changing the target CICS regionThe communications area passed to the dynamic routing program initially containsthe system identifier (sysid) and netna

alternative program is to be linked. You can specify a local or remote program,depending on the region to which the request is to be routed.Changing t

been set to ‘N’—the request is not to be queued—for this error to occur), issue areturn code of ‘0’ in DYRRETC, and try to route the request again.v Y

For information about writing an XPCERES global user exit program, see TheXPCERES global user exit.If a required resource is unavailable on the target

v The dynamic routing program can be RMODE ANY but must be AMODE 31.Unit of work considerationsThe client program, the dynamic routing program, and po

v If an error occurs in route selection, for example, if the target region returned bythe routing program on its initial (route selection) call is una

v If the SYSIDs are the same (or the returned SYSID is blank) CICS executes thelink request locally.v If the two SYSIDs are not the same, CICS routes

To use the XPCERES exit, both the routing region and the target region mustsupport the “resource unavailable” condition (RESUNAVAIL). All the followin

resources, because changes to those resources may be committed or backedout inadvertently as a result of logic in the routed program.v If you want to

Note: For additional information about using these exits with CICS shared datatable support, see the CICS Shared Data Tables Guide.Related concepts“Th

ImportantThe same communications area is passed to both the dynamic routing program andthe distributed routing program. Some parameters are meaningful

under the DYRFUNC parameter the value X'5' is not listed because it is neverpassed to the dynamic routing program—it occurs only on a route