Writing a task-related user exit program

The main function of the task-related user exit program is to translate the calling program’s parameters into a form acceptable to your non-CICS resource manager, and then to pass control to the resource manager. You therefore need to be familiar with your resource manager’s syntax requirements. The calling program’s parameters are described in Caller parameter lists.

This section describes the user exit parameter lists, the schedule flag word, which is used by the exit program to register its need to be invoked by CICS® management services, and register-handling in the task-related user exit program. This section also discusses the use of the CICS syncpoint manager and the CICS task manager. It also discusses some factors that you should consider if you plan to use TCBs provided by the CICS open transaction environment (OTE).

Obligations of OPENAPI task-related user exits

Open API task-related user exits (that is, exits enabled with the OPENAPI option) are invoked on an open L8 mode TCB instead of the main CICS QR TCB. If a TRUE wants to invoke an external resource manager without the benefit of the open API facility, it has to manage its own set of subtask TCBs. It can then use one of these private TCBs on which it can run the request to access the external resource manager. Typically, the subtask TCB is posted to access the external resource manager, while the CICS task running on the QR TCB in the TRUE is put into a CICS dispatcher wait until the subtask completes its work. The CICS dispatcher wait allows the CICS dispatcher to dispatch another CICS task on the QR TCB in the meantime. The reason for this architecture is that external resource managers cannot be invoked directly by a caller on the QR TCB, because any operating system wait issued by the external resource manager would halt the QR TCB, and thereby the whole of CICS.

An open API TRUE is invoked on an L8 mode TCB, which is dedicated for use by the calling CICS task, and is separate from the CICS QR TCB. Therefore, a TRUE can invoke its external resource manager on the allocated L8 TCB and avoid the need to manage its own set of subtask TCBs. An operating system wait issued by an external resource manager will halt the L8 TCB, but CICS continues processing on the QR TCB, and on other open TCBs.

An open API TRUE, although freed from the constraints imposed by the QR TCB, and from having to create subtask TCBs, nevertheless does have obligations both to the CICS system as a whole and to future users of the L8 TCB it is using. An L8 TCB is dedicated for use by the CICS task to which it is allocated, but once the CICS task has completed, the L8 TCB is returned to the dispatcher-managed pool of L8 mode TCBs, provided it is still in a "clean " state. (An unclean TCB in this context means that the task using the L8 mode TCB suffered an unhandled abend in an open API TRUE, and not that the TRUE has broken the threadsafe restrictions, which CICS would not detect.) Note that the L8 TCB is not dedicated for use by a particular open API TRUE, but is used by all open API TRUEs Start of changeand OPENAPI programsEnd of change invoked by the CICS task to which the L8 mode TCB is allocated. Also, if an application program invoking an open API TRUE is coded to threadsafe standards, and defined to CICS as threadsafe, it continues to execute on the L8 mode TCB on return from the TRUE. When considering whether to exploit CICS OTE support rather than manage your own subtask TCBs, consider the restrictions listed below. You can then decide whether to work within these restrictions or to use your own subtask TCB, which is dedicated for your own TRUE's use.

Threadsafe restrictions

An open API TRUE must not treat the executing open TCB environment in such a way that it causes problems for:

In particular:

Calling an OPENAPI task-related user exit

If a task-related user exit is enabled with the OPENAPI option, CICS uses the following rules, based on the type of call, to determine the TCB on which it should invoke the TRUE--on the QR TCB, on the caller's TCB, or an L8 mode TCB:

Application program call (API)--UERTAPPL
For this call, CICS always invokes the TRUE on an L8 mode TCB
CICS syncpoint manager call--UERTSYNC
For this call, CICS always invokes the TRUE on an L8 mode TCB
CICS task manager call--UERTTASK
For this call, the TCB on which CICS invokes the TRUE is further determined by the type of task manager call:
UERTSOTR--Start of task
For this call the open API option is ignored for performance reasons, and CICS always invokes the TRUE on the QR TCB.
UERTEOTR --End of task
For this call, CICS always invokes the TRUE on an L8 mode TCB.
EDF call--UERTFEDF
For this call, CICS always invokes the TRUE on an L8 mode TCB
CICS SPI call--UERTSPI
For this call, CICS always invokes the TRUE as a threadsafe TRUE on the TCB on which the task is currently running at the time of the call.

The SPI function, which is to satisfy EXEC CICS INQUIRE EXITPROGRAM commands on which the CONNECTST or QUALIFIER option are specified, is simple and does not require invocation on a specific TCB.

CICS termination call--UERTCTER
For this call the open API option is ignored and CICS always invokes the TRUE on the QR TCB.
Note:
Even for call types that are invoked on an L8 TCB, it is possible that the L8 TCB could suffer an aynschronous abend and therefore not be available for subsequent use, with the following result: The TCB mode on which the task-related user exit is being called is provided in the second and third bytes of a three-byte filed addressed by the UEPTIND parameter. See Table 13 for details.

User exit parameter lists

When a task-related user exit is invoked, the CICS management module that handles task-related user exits provides the exit with a parameter list. The address of this parameter list is passed in register 1. The list contains the following information:

To enable your exit program to access this parameter list, you must include in it the macro:

DFHUEXIT TYPE=RM

The DFHUEXIT TYPE=RM macro causes the assembler to create the storage definitions (DSECTs) DFHUEPAR and DFHUERTR. If you want your task-related user exit to be able to format screens for EDF, you must include in it the macro:

DFHUEXIT TYPE=RM,DSECT=EDF

This causes the assembler to create the UEPEDFRM DSECT, which is described in CICS EDF build parameters. All of the user exit parameter lists are summarized in Figure 7.

The format and the purpose of these definitions are described below.

DFHUEPAR

DFHUEPAR gives you the following symbolic names for address parameters:

UEPEXN
Address of the function definition, which tells the task-related user exit program why it is being called. See DFHUERTR (the function definition) for more details.
UEPGAA
Address of the global work area requested in the EXEC CICS ENABLE command. The global work area is described in topic The global work area. CICS initializes this work area to X'00' when the task-related user exit program is enabled.
UEPGAL
Address of a halfword containing the length (binary value) of the global work area.
UEPTCA
This field is retained for historical reasons. It should not be referenced by your exit program.
UEPCSA
This field is retained for historical reasons. It should not be referenced by your exit program.
UEPHMSA
Address of the register save area (RSA) of the caller. It is an 18-word save area, with the contents of registers 14 through 12 stored in the fourth and subsequent words. Its fifth word, representing the calling program’s register 15, is cleared by CICS before the task-related user exit program is invoked, so that it can be used to convey response codes from the resource manager to the calling program. For this reason you cannot use register 15 to send data to the task-related user exit program. The seventh word of the save area contains the caller’s register 1. Register 1 addresses the caller’s parameter list if the exit program is being invoked by the CICS task manager or the CICS syncpoint manager, by EDF, or at CICS termination. When the caller is an application program, the contents of register 1 are determined by the linkage conventions of the adapter’s language interface.
UEPTAA
Address of the local work area requested in the EXEC CICS ENABLE command. The local work area is described in topic The local work area. CICS initializes the work area to X'00' throughout on first acquiring the area; that is, when the task first invokes the task-related user exit program.
UEPTAL
Address of a halfword containing the binary length of the local work area.
UEPEIB
Address of the EXEC interface block (EIB) created by CICS for the task-related user exit program. The EIB exists only for the duration of the call and it allows the task-related user exit program to request CICS services through the command-level interface. This is not the same EIB that is available to the calling program, so you cannot access the calling program’s environment other than by UEPHMSA (see above), which provides the address of the calling program’s register save area (RSA).
UEPURID
Address of CICS unit of recovery identifier. This field contains the 8-byte date and time value that is generated by an STCK instruction, and it identifies the current unit of work.
UEPFLAGS
Address of the schedule flag word. This is a fullword that the task-related user exit program uses to register its need for CICS management programs’ services. For more information, see The schedule flag word.
UEPRMSTK
Address of the kernel stack entry.
UEPUOWDS
Address of the APPC unit of work (UOW) identifier.
UEPSECFLG
Address of the user security flag. The user security flag is a 1-byte field that can take the following values:
UEPNOSEC (X'80')
Security is not active for this CICS system.
UEPSEC (X'20')
Security is active for this CICS system. Only in this case is the address of the "user security block" set.
UEPSECBLK
Address of a fullword that addresses the "user security block"--that is, the ACEE.
UEPRMQUA
Address of an 8-byte field into which the task-related user exit can move the qualifier name of the resource manager on each API request. This is useful where the same exit program is used to connect to more than one instance of a resource manager; the qualifier identifies the instance of the resource manager to which the exit is currently connected.

Where different resource manager qualifiers are returned on the responses to various API requests within a UOW, it is the resource manager qualifier returned on the final API request immediately before a prepare or backout invocation that is used when recording any in-doubt information.

UEPCALAM
Address of caller’s AMODE indication byte.
X'80'
Indicates that the original caller was in AMODE 31. If the top bit is not set, then the caller was in AMODE 24.
UEPSYNCA
Address of the single-update and read-only indication byte. This field contains flags that your exit program can set to indicate that the resource manager "understands" the single-update protocol, and to record the status of the current unit of work (UOW). See Increasing efficiency - single-update and read-only protocols.
UEPSUPDR (X'80')
The resource manager understands the single-update protocol. That is, your exit program can instruct the resource manager to perform a single-phase commit, in appropriate circumstances.
UEPREADO (X'40')
The resource manager understands the read-only protocol, and has been in read-only mode for this UOW so far. (If this flag is not set, it means either that the UOW contains updates for this resource manager, or that the UOW may be read-only but the resource manager does not understand the read-only protocol.)
UEPTIND
Address of a 3-byte field containing indicators.

The first indicator byte can take one of three symbolic values, UEPTANY, UEPTCICS, and UEPTUTCB, which you can test to determine: whether data locations can be above or below 16MB; whether the application’s storage is in CICS-key or user-key storage; and whether the TRUE has been called by an unexpected TCB:

UEPTANY (X'80')
The application can accept addresses above 16MB. If the symbolic value is not UEPTANY, the application must be returned an address below 16MB.
UEPTCICS (X'40')
The application’s working storage and task life-time storage are in CICS-key storage (TASKDATAKEY=CICS). If the symbolic value is not UEPTCICS, the application’s working storage and the task’s life-time storage are in user-key storage (TASKDATAKEY=USER).
UEPTUTCB (X'20')
Indicates an unexpected TCB. Set on a syncpoint or end-of-task call only, this indicates a failure to switch to the TCB expected by the task-related user exit. In these two cases, the task-related user exit is called on the QR TCB with the UEPTUTCB bit set. For all other calls, CICS abends the transaction without invoking the task-related user exit.

The second and third bytes contain a value indicating the TCB mode of its caller. This is represented in DFHUEPAR as both a two-character code and a symbolic value, as follows:

Table 13. TCB indicators in DFHUEPAR Description
Symbolic value 2-byte code Description
UEPTQR QR The quasi-reentrant mode TCB
UEPTRO RO The resource-owning mode TCB
UEPTCO CO The concurrent mode TCB
UEPTSZ SZ The FEPI mode TCB
UEPTRP RP The ONC/RPC mode TCB
UEPTFO FO The file-owning mode TCB
UEPTSL SL The sockets listener mode TCB
UEPTSO SO The sockets mode TCB
UEPTS8 S8 The secure sockets layer mode TCB
UEPTD2 D2 The CICS-DB2 housekeeping mode TCB
UEPTJ8 J8 The J8 open TCB, used for JVMs that are in CICS key
UEPTJ9 J9 The J9 open TCB, used for JVMs that are in user key
UEPTJM JM The JM open TCB, used for the master JVM that initializes the shared class cache
UEPTL8 L8 Start of changeAn L8 open TCB, used for OPENAPI TRUEs, or OPENAPI programs that are in CICS keyEnd of change
Start of changeUEPTL9End of change Start of changeL9End of change Start of changeAn L9 open TCB, used for OPENAPI programs that are in user keyEnd of change
Start of changeUEPTX8End of change Start of changeX8End of change Start of changeAn X8 open TCB, used for C and C++ programs, compiled with the XPLINK option, that are in CICS keyEnd of change
Start of changeUEPTX9End of change Start of changeX9End of change Start of changeAn X9 open TCB, used for C and C++ programs, compiled with the XPLINK option, that are in user keyEnd of change
UEPPBTOK
Address of the performance block token used for workload management, to enable resource managers to relate their own performance blocks for the work request with the original CICS performance block. For example, DBCTL and DB2® need to correlate the work they do on behalf of CICS with the originating CICS task, so that MVS workload manager can measure the performance of the whole CICS task.
UEPTRCE
Address of a 1-byte trace flag indicating whether RMI tracing (the RI trace component) is active.
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 user exit could, for example, issue an EXEC CICS SET TRACETYPE command to reset the level of RMI tracing.

DFHUERTR (the function definition)

The function definition identifies the caller of the task-related user exit program. The DSECT contains two symbolic definitions (fields).

UERTFGP
A single byte that is set to X'00'. The zero setting shows that this is a task-related user exit invocation and that the parameter list therefore includes the fields UEPTAA, UEPTAL, UEPEIB, UEPURID, and UEPFLAGS.
UERTFID
A single-byte identifier that shows whether this call has been made by the CICS SPI, an application program, the CICS syncpoint manager, the CICS task manager, or EDF, or whether this is a CICS termination call. It can have one of the following six settings:
UERTSPI
(X'01') CICS SPI call.
UERTAPPL
(X'02') Application program call.
UERTSYNC
(X'04') CICS syncpoint manager call.
UERTTASK
(X'08') CICS task manager call.
UERTCTER
(X'0A') CICS termination call.
UERTFEDF
(X'0C') EDF call.

It is important to know which type of program has made the call because it affects how the calling program’s parameter list is interpreted by the task-related user exit program.

Caller parameter lists

In addition to the DSECTs DFHUEPAR and DFHUERTR, the inclusion of DFHUEXIT TYPE=RM in the task-related user exit program provides some field definitions that are specific to the caller of the task-related user exit. The calling program’s parameter list is normally addressed by R1 in the calling program’s RSA. This RSA is addressed by field UEPHMSA of DFHUEPAR. These parameters are described below.

CICS SPI parameters

If you enable your task-related exit program with the SPI option of the EXEC CICS ENABLE PROGRAM command (or the program itself "expresses interest" in SPI calls--see The schedule flag word), the exit program can be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM commands on which the CONNECTST or QUALIFIER option is specified. This allows applications to query whether the exit program is connected to its resource manager, and its entryname-qualifier. For information about the INQUIRE EXITPROGRAM command, see the CICS System Programming Reference manual.

The CICS SPI parameter list contains two entries:

Parameter 1
The address of a 1-byte output field, which your task-related exit program should use to indicate whether it is connected to its external resource manager. The equated return code values are:
UERTCONN
(X'80') The exit is connected to its resource manager.
UERTNCONN
(X'40') The exit is not connected to its resource manager.
Parameter 2
The address of an 8-character output field, in which your task-related exit program should return the qualifier of the external resource manager, if known. See the UEPRMQUA parameter in DFHUEPAR for more information on qualifier names.
Application program parameters

If the caller is an application program, the format and addressing of its parameter list are decided locally.

CICS syncpoint manager parameters

The CICS syncpoint manager’s parameter list contains ten entries, although on most invocations only parameters 1 and 10 contain values. The operation bytes pointed to by parameters 1 and 10 contain flags which, when combined, form an operation code that tells the TRUE why it has been invoked.

Parameters 2 through 9 contain values only when the syncpoint manager makes a "Commit Unconditionally" or "Backout" call to the TRUE, for resynchronization purposes after a session or system failure. These extra parameters point to fields that identify the task, the transaction that started the task, the terminal from which it was initiated, the identity of the terminal operator, the date and time of the failing syncpoint, and (if there are no further units of recovery associated with the task) the next transaction code. Typically, you would use these values to create meaningful messages for resource recovery. They are presented explicitly because, after a system failure, the task driving the exit is not the task that originally scheduled the recoverable work. These additional parameters describe the original task’s environment and are accessed directly.

The full parameter list is as follows:

Parameter 1
The address of operation byte 1, which contains the following flags:
UERTPREP
(X'80') Prepare to commit (that is, perform the first phase of a two-phase commit).
UERTCOMM
(X'40') Commit unconditionally (perform the second phase of a two-phase commit).
UERTBACK
(X'20') Backout.
UERTDGCS
(X'10') Unit of recovery has been lost because of an initial start of CICS.
UERTDGNK
(X'08') Resource manager should not be in doubt about this unit of recovery.
UERTWAIT
(X'04') Resource manager must wait for the outcome of this unit of recovery. This value is set at phase two of a two-phase commit, if CICS is in-doubt about the outcome of a UOW. It occurs only if the task-related user exit is enabled with the INDOUBTWAIT option (see Enabling for specific invocation-types).
UERTRSYN
(X'02') This syncpoint request was generated as the result of an EXEC CICS RESYNC command.
UERTLAST
(X'01') There are no further units of recovery associated with this task. Note that when this bit is not set, there may or may not be further units of recovery. For this reason, it is not recommended that you rely on this bit to signal end-of-task. You should instead schedule the CICS task manager to drive you at end-of-task by setting the task manager bit in the schedule flag word. If you do use UERTLAST to signal end-of-task, and if at that stage you can complete your clean-up process, you can set the task manager bit off in the schedule flag word when the clean-up process is finished, to avoid an unnecessary invocation by the CICS task manager.

The only valid bit combinations are those produced by combining one of UERTPREP, UERTCOMM, UERTBACK, UERTDGCS, and UERTDGNK with either UERTLAST or UERTRSYN, or both; or by combining UERTWAIT and UERTLAST.

Your exit program should examine the flags set both in this byte and in operation byte 2 (see parameter 10), to determine what action is expected of it.

Parameter 2
If not zero, the address of a 4-byte, packed-decimal field identifying the original task. But note that, on many invocations of the exit program, parameters 2 through 9 do not contain values. See note 1.
Parameter 3
Address of a 4-character field identifying the transaction that started the original task. See note 1.
Parameter 4
Address of a 4-character field identifying the terminal from which the original task was initiated. See note 1.
Parameter 5
Address of a 4-character field containing the identity of the terminal operator (OPID) who initiated the original task. See note 1.
Parameter 6
Address of a 4-byte, packed-decimal field containing the date of the failing syncpoint, in the format 0Cyyddds, where:

See note 1.

Parameter 7
Address of a 4-byte, packed-decimal field containing the time of the failing syncpoint, in the format 0hhmmss+. See note 1.
Parameter 8
Address of an 8-byte field containing the resource manager qualifier. See note 1.

To verify that this is a resync for this instance of the resource manager, your exit program should check that the qualifier passed is the one that is currently in use. If it is not, the exit program should ignore the resync and set a return code of UERFHOLD, to indicate that CICS should keep the disposition of the unit of work.

Parameter 9
Address of a 4-character field containing the next transaction code. If the transaction ended with an EXEC CICS RETURN without specifying the next transaction code, the addressed field is set to nulls; otherwise, it is set to the value specified by the application. See note 2.
Parameter 10
The address of operation byte 2, which contains the following flags:
UERTONLY
(X'80') Perform a single-phase commit. (No recoverable resources other than those owned by the resource manager being invoked have been updated during the current UOW.)
UERTELUW
(X'40') Perform a single-phase commit. (The resource manager was in read-only mode throughout the current UOW.)
Your exit program should examine the flags set both in this byte and in operation byte 1 (see parameter 1), to determine what action is expected of it.
Notes:
  1. Parameters 2 through 8 contain values only if the CICS syncpoint manager call is prompted by the issue of an EXEC CICS RESYNC command after a session or system failure, and operation byte 1 contains the bit settings UERTCOMM or UERTBACK. Otherwise, they are set to X'00' (hexadecimal zero). For programming information about the EXEC CICS RESYNC command and about the completion of the syncpointing procedure following a system failure, refer to the CICS System Programming Reference manual.

    Note that parameters 2 through 8 describe the environment of the original task (not of the task that is currently driving the TRUE).

  2. Unless the UERTLAST bit is set in operation byte 1, parameter 9 is a zero address. Although for a call prompted by an EXEC CICS RESYNC call, the UERTLAST bit will be set on, in this case the next transaction code does not apply and so Parameter 9 addresses a field set to nulls.
CICS task manager parameters

There are either one or two entries in the CICS task manager’s parameter list, depending on the reason for the call to the TRUE: on start-of-task calls, the parameter list contains one entry, while on end-of-task calls, it contains two. Each entry consists of an address, and the end of the parameter list is indicated by the top bit of the address being set.

The significance of the parameters is as follows:

Parameter 1
The address of a single byte with bit definitions indicating the reason for the call:
UERTSOTR
(X'40') Start of CICS task
UERTEOTR
(X'80') End of CICS task.
Parameter 2
This parameter is passed only on end-of-task calls. It is the address of a 4-character field which contains the next transaction code specified on the EXEC CICS RETURN command. If the transaction ends with an EXEC CICS RETURN without specifying a next transaction, this field is set to nulls.

The schedule flag word should be set during the start-of-task call if you want your task-related user exit program to be invoked unconditionally by the CICS syncpoint manager.

CICS termination manager parameters

All task-related user exit programs that have been enabled with the SHUTDOWN option of the EXEC CICS ENABLE command, and started, are invoked at CICS termination to allow them to do the clean-up processing that is appropriate to the type of termination. At CICS termination, the address of a one-byte termination code is passed to your exit program. The code may consist of any of the following bit settings:

UERTCORD
(X'80') CICS orderly shutdown
UERTCIMM
(X'40') CICS immediate shutdown
UERTCABY
(X'20') CICS abend, retry possible, TCBs dispatchable
UERTCABN
(X'10') CICS abend, retry not possible, TCBs dispatchable
UERTOPCA
(X'01') CICS abend, retry not possible, TCBs not dispatchable.

For further information about shutdown TRUEs, see Coding a program to be invoked at CICS termination.

CICS EDF build parameters

On EDF invocations, the address contained in register 1 of the calling program’s RSA points to the UEPEDFRM DSECT.
This contains the following fields:

UEPEDFR1
The address of the application’s R1 parameter list.
UEPEDFFI
The input flag byte. When a task-related user exit is invoked by EDF, UEPEDFFI can take one or more of the following bit settings:
UEPEDFRQ
(X'80') "About to Execute" invocation.
UEPEDFRS
(X'40') "Command Execution Complete" invocation.
UEPEDFRA
(X'20') About to display command to EDF.
UEPEDFRC
(X'10') Command has been displayed to EDF.
UEPEDFSC
(X'08') EDF user has changed the screen.
UEPEDFWS
(X'04') EDF user has changed working storage.
UEPEDFNO
(X'01') EDF user has requested NOOP.
UEPEDFFO
The output flag byte. If the task-related user exit requires, it can set the UEPEDFFO flag byte to indicate to EDF what action the task-related user exit wants EDF to take. It can take the following values:
UEPEDFDF
(X'80') Take default CICS action. (EDF screen contains the uninterpreted caller’s R1 parameter list.)
UEPEDFND
(X'40') Do not display command to EDF.
UEPEDFRD
(X'20') Redisplay command to EDF.
UEPEDFDL
EDF screen attributes. These are for information only: the task-related user exit program cannot change these fields.
UEPEDFPS (halfword binary)
Page size (number of lines).
UEPEDFLS (halfword binary)
Line size.
UEPEDFMP (halfword binary)
Maximum number of pages.
UEPEDFPA
The address of the EDF display data parameter list, supplied by the task-related user exit. The display data parameter list is composed of alternating pairs of attribute-byte addresses and data-field addresses. Attribute bytes refer to the line of display data pointed to by the data-field addresses. The data field must be the same size as the value specified in UEPEDFLS. The display data is in the format shown in Figure 6.

Notes:
  1. CICS provides a list of named standard attribute bytes that you may want to use. These standard attribute bytes are contained within DFHBMSCA, which must be copied into your program. For programming information, including a list of the attribute bytes and their meanings, refer to the CICS Application Programming Reference manual.
  2. The high-order bit must be set on in the last address, to indicate to EDF that this is the last address.

Summary of the task-related user exit parameter lists

Figure 7 shows, in diagrammatic form, the relationships between the parameter lists that are discussed in the preceding sections.

Figure 7. Task-related user exit parameter lists
 The picture shows, in diagrammatic form, the relationships between the parameter lists that are discussed in the preceding sections.

The schedule flag word

The schedule flag word is a fullword indicator that the task-related user exit program uses to control its own invocation. It is also used by CICS to schedule the first invocation of a task-related user exit program. The schedule flag word is accessed by the address parameter UEPFLAGS of DFHUEPAR. There is a unique schedule flag word for each association between a CICS task and the ENTRYNAME specified when a task-related user exit program is enabled.

The default setting of the schedule flag word is for application program requests (that is, the last two bytes are set to X'0004').

The format of the schedule flag word is shown in Table 14.

Table 14. Format of the schedule flag word
Byte Setting Comments
0 -- Reserved.
1 -- Reserved.
2
UEFDFEDF
UEFDTASK
 
UEFMFEDF (X'10')
UEFMTASK (X'01')
 
Bit mask for EDF invocation.
Bit mask for task manager.
3
UEFDSYNC
UEFDAPPL
UEFDSPI
 
UEFMSYNC (X'10')
UEFMAPPL (X'04')
UEFMSPI  (X'02')
 
Bit mask for syncpoint manager.
Bit mask for application prog.
Bit mask for SPI.

The bit settings of the schedule flag word show which programs invoke your task-related user exit program. For example, if an exit program is to be invoked by the CICS task manager, the CICS syncpoint manager, and an application program, then the last two bytes of the schedule flag word are set to X'0114'. If an exit program is to be called by the CICS task manager and an application program only, the last two bytes of the flag word are set to X'0104'. Before the exit program is first called by a task, CICS sets the API flag bit on.

Before returning from any call, the task-related user exit can change the bit settings of the flag word to register its need to be invoked by a different CICS management service, or to register lack of interest in a service by setting the relevant flag bit to zero.

For example, a task-related user exit may be called by an application program that needs to access a non-CICS recoverable resource. When the exit program is first called, the API bit is set on by CICS. If the calling program then issues a request to update a record, the exit program sets the syncpoint manager bit on in the schedule flag word. When the calling application program subsequently issues a syncpoint command, or when end-of-task is reached, the CICS syncpoint manager calls the exit program.

Note:
CICS sets the syncpoint manager bit off after every call to the syncpoint manager. This is to avoid the CICS syncpoint manager invoking the task-related user exit program for a unit of recovery during which the exit program did no recoverable work. The syncpoint manager bit must therefore be set on whenever the exit program performs any recoverable work.

If you set the task manager bit in the schedule flag word on, CICS invokes your task-related exit program at the end of this task. (Note that, if you want your exit program to be called at the start as well as at the end of a task, you must specify TASKSTART on the EXEC CICS ENABLE command for the TRUE. This causes the TRUE to be invoked at the start and end of every task.)

If the last two bytes of the schedule flag word are set to X'1000', this indicates that the task-related user exit is interested in being invoked by EDF to format requests for display. This schedule flag bit UEFDFEDF is set on either by the EXEC CICS ENABLE FORMATEDF command, or by the task-related user exit. Unlike other schedule flag bits, there are restrictions on when the task-related user exit can register a lack of interest in EDF (that is, restrictions on when UEFEDFDF can be set off). Once a task-related user exit has formatted the initial screen for EDF to display on "About to Execute" or "Command Execution Complete", CICS does not allow it to set the EDF bit UEFDFEDF off until the screen build cycle is complete.

Register handling in the task-related user exit program

In this section, two sets of registers are discussed:

  1. The registers belonging to the CICS management module that handles task-related user exits. These are referred to as the CICS registers.
  2. The registers belonging to the calling program and that are addressed by parameter UEPHMSA of DFHUEPAR. These are referred to as the calling program’s registers.
  3. Start of changeThe registers belonging to the called resource management interface (RMI). These are referred to as the RMI registers.End of change

Saving CICS registers

Your task-related user exit program should begin by saving the contents of the CICS registers. Register 13 addresses an 18-word area into whose 4th and subsequent words your exit program should store registers 14 through 12. Three of the saved values have significance, as follows:

Note:
As a general rule, if you fail to understand the origin or the purpose of a call, you should:
  1. Restore any registers that you have used to the state they were in on entry to your code
  2. Return to the address contained in CICS register 14.

The calling program’s registers

The calling program’s registers are stored at the address specified by UEPHMSA of DFHUEPAR. Where the calling program is a CICS management program, for example the syncpoint manager, the only caller registers that have significance are registers 1 and 15. Register 1 addresses the calling program’s parameter list. CICS sets the calling program’s register 15 to zero before the task-related user exit program is invoked. The calling program’s register 15 can sometimes be used to pass responses back to the calling program from the task-related user exit program, depending on the identity of the caller. If the calling program is a CICS management program, and the register is still zero on return, CICS assumes that its call was not understood. If the calling program is an application program, the significance of register settings on return are either described in your resource manager’s documentation, or defined locally.

Start of change

The RMI registers

CICS does not support 64-bit addressing execution, but TRUEs can invoke RMI programs that use storage at addresses which are only available when running on 64-bit architecture machines. The CICS dump formatter displays the contents of the 64-bit General Purpose Registers captured when an abend occurs.

End of change

Addressing-mode implications

The task-related user exit is invoked in the AMODE of the caller, unless the exit has been enabled with the LINKEDITMODE option of the EXEC CICS ENABLE command. This option enables the task-related user exit in its link-edit AMODE. Therefore, if the TRUE has been link-edited AMODE 31 and is enabled with the LINKEDITMODE option, it can be placed above the 16MB line. For programming information about the LINKEDITMODE option of the EXEC CICS ENABLE command, refer to the CICS System Programming Reference manual.

Important

You should avoid the use of the LINKEDITMODE option where the TRUE has been link-edited AMODE 24. This combination forces the TRUE always to run AMODE 24, which is unwise because:

It is recommended that TRUEs are:

If the task-related user exit has not been enabled with the LINKEDITMODE option of EXEC CICS ENABLE, it is invoked in the AMODE of the caller. For example, in the case of an application request, if the application is AMODE 24 at the time of the DFHRMCAL, the task-related user exit is invoked in AMODE 24. For this reason, task-related user exits which have been enabled without the LINKEDITMODE option must reside below the 16MB line.

Exit programs and the CICS storage protection facility

When you are running CICS with the storage protection facility, there are two points you need to consider for task-related user exits:

  1. The execution key in which your task-related user exit programs run
  2. The storage key of data storage obtained for your exit programs.

Execution key for task-related user exit programs

When you are running with storage protection active, CICS always invokes task-related user exit programs in CICS key. Even if you specify EXECKEY(USER) on the program resource definition, CICS forces CICS key when it passes control to the TRUE. However, if a task-related user exit program itself passes control to another program (via a link or transfer-control command), the program thus invoked executes according to the execution key (EXECKEY) defined in its program resource definition.

Important

You are strongly recommended to specify EXECKEY(CICS) when defining both task-related user exit programs, and programs to which an exit program passes control.

Data storage key for task-related user exit programs

The storage key of storage used by task-related user exit programs depends on how the storage is obtained:

Recursion within a task-related user exit program

The task-related user exit has the ability to invoke itself recursively. It can do this, for example, by issuing a DFHRMCAL call to its own entry name (as specified on the EXEC CICS ENABLE command). It can also be entered recursively if it performs an EXEC CICS SYNCPOINT when it is interested in SYNCPOINT invocations.

Purging tasks

The operation of task purging when control is within a task-related user exit depends on the PURGEABLE option on the EXEC CICS ENABLE PROGRAM command.

If the PURGEABLE option is not specified:

If the PURGEABLE option is specified, before passing control to a task-related user exit program CICS inhibits the monitoring of runaway tasks but not the ability to purge tasks. While control is in a task-related user exit program:

See Wait states in your task-related user exit program for a fuller explanation of the PURGEABLE option.

Using CICS services in your task-related user exit program

You might find some CICS services useful in your exit program. These can be invoked using EXEC CICS commands. However, you should take note of the following:

Start of change

Using channels and containers

Task-related user exit programs cannot access channels and containers created by application programs. They can, however, create their own channels and pass them to programs which they call.

For information about channels and containers, see the CICS Application Programming Guide.

End of changeStart of change

Assembler programs and LEASM

Assembler programs translated with the LEASM option cannot be used as task-related user exit programs.

LEASM is used to produce Language Environment conforming main programs in assembler. For information about the LEASM translator option, see the CICS Application Programming Guide.

End of change

Wait states in your task-related user exit program

By default, tasks that are active in a task-related user exit and have entered a CICS wait state cannot be purged--only force purge can be used. However, if a task-related user exit is enabled with the PURGEABLE option, a task can be successfully purged from a wait within the task-related user exit. If this option is to be used, the task-related user exit program must be written to process correctly a purged response from the wait. See the CICS System Programming Reference manual for more information.

Work areas

When you use the EXEC CICS ENABLE command to identify a task-related user exit program to CICS, you may specify that the program must have access to one local and one global work area. The EXEC CICS ENABLE command allows you to specify the size, in bytes, of the work areas to be acquired for your task-related user exit program. CICS acquires storage for the areas and initializes pointers to them. The user exit parameter list, DFHUEPAR, gives you access to the pointers. For more information, see the description of DFHUEPAR under User exit parameter lists.

The global work area

A global work area is associated with an exit program. Whenever the exit program is invoked, it has access to the area through the parameter UEPGAA of DFHUEPAR. The global work area may be shared by a number of exit programs. You must have specified the size of the global work area using the GALENGTH parameter or the GAENTRYNAME parameter of the EXEC CICS ENABLE command.

The global work area is located below the 16MB line.

The local work area

A local work area is associated with a single task and lasts only for the duration of the task. It is for the use of a single task-related user exit program. It can be thought of as a logical extension to the transaction work area (TWA, TWACOBA) that is exclusively for the exit program’s use. It is specified using the TALENGTH option of the EXEC CICS ENABLE command and is accessed using the UEPTAA parameter of DFHUEPAR.

If the TRUE is enabled with the LINKEDITMODE option of the EXEC CICS ENABLE command and link-edited AMODE 31, local work areas are located above the 16MB line; otherwise, they are below the line.

Coding a program to be invoked by the CICS SPI

If you enable your task-related exit program with the SPI option of the EXEC CICS ENABLE PROGRAM command (or your program "expresses interest" in SPI calls by setting the SPI bit-mask in the schedule flag word), your program is invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM commands that query whether the exit program is connected to its resource manager, and its entryname-qualifier. (For information about the INQUIRE EXITPROGRAM command, see the CICS System Programming Reference manual.)

When invoked for SPI calls, your exit program should:

Typically, both the above pieces of information are kept in the exit program’s global work area. The caller parameter list for SPI calls is described in CICS SPI parameters.

The RMI SPI call allows a task-related user exit to be called by long-running monitor tasks, even if it has been disabled and reenabled since it was last called by the task. (All other types of RMI call fail if this is the case.)

Note:
When invoked for an SPI call, your exit program should not rely on the contents of the task local work area. If the exit has been disabled and reenabled, a new version may have been loaded, which may have a different mapping of the task local work area. The long-running task, however, is running with the original task local work area allocated to it on its first call.

Coding a program to be invoked by the CICS syncpoint manager

All task-related user exit programs can be invoked by the CICS syncpoint manager. An exit program must "schedule" the syncpoint manager by setting the syncpoint manager bit-mask in the schedule flag word. The bit-mask must be set after every piece of recoverable work to ensure that the CICS syncpoint manager calls the exit program during syncpoint processing. (The identification of the current unit of recovery--or unit of work--is addressed by the 8-byte field UEPURID. This is available on all invocations of your exit program in which recoverable actions are possible, for example, application calls and subsequent syncpoint manager calls.)

Increasing efficiency - single-update and read-only protocols

If your resource manager is capable of performing a single-phase commit, you can increase the efficiency of your system by means of CICS single-update and read-only protocols.

Single-update protocol

Many CICS transactions use only one external resource manager. In this case, a single-phase commit is in order. The benefits of a single-phase commit are:

To take advantage of these benefits, your task-related user exit program must indicate to CICS that the resource manager understands the single-update protocol, and that it (the TRUE) can process a syncpoint call to perform a single-phase commit. It indicates this by setting the UEPSUPDR flag in the field pointed to by UEPSYNCA in the DFHUEPAR parameter list. It must do this every time it sets the syncpoint manager bit in the schedule flag word.

If the exit program has set the UEPSUPDR flag, then, when the syncpoint manager next invokes the TRUE, it informs it whether the resource manager is the only one to have updated resources in the current UOW. It does this by means of the UERTONLY bit (in operation byte 2 of the syncpoint manager’s parameter list); if this is set on, then the resource manager can be asked to perform a single-phase commit.

Read-only protocol

Similar gains in efficiency can be made if the resource manager is in read-only mode throughout the current UOW. Again, a single-phase commit is in order. To benefit, the resource manager must return to the TRUE a flag indicating whether the UOW is read-only or not. The flag may show either the "history" of the UOW so far (for example, so far it is read-only), or simply whether the current request is read-only. In turn, the TRUE must update the UEPREADO flag in the DFHUEPAR parameter list with the history of the UOW so far. That is, it must set UEPREADO initially, but unset it as soon as the UOW contains updates. (Once UEPREADO has been unset, CICS ignores any subsequent setting of the flag during the current UOW, and treats the UOW as containing updates.)

At the end of the UOW, if the UEPREADO flag is still set, the syncpoint manager invokes the TRUE with instructions to issue a single-phase commit to the resource manager (by setting the UERTELUW bit on).

Return codes

When a task-related user exit program is invoked by the CICS syncpoint manager, the return codes it is able to set depend on the reason for the invocation. Table 15 shows the relationship between the request flags in the syncpoint manager’s parameter list and the TRUE return codes. (The CICS syncpoint manager parameters are described in CICS syncpoint manager parameters.)

Table 15. Valid return codes for a TRUE invoked by the CICS syncpoint manager
Request-type Return codes Meaning
UERTPREP UERFPREP Phase 1 of 2-phase commit successful
UERTPREP UERFBACK Phase 1 of 2-phase commit unsuccessful
UERTWAIT None Not applicable
UERTCOMM UERFDONE Phase 2 of 2-phase commit successful
UERTCOMM UERFHOLD Phase 2 of 2-phase commit unsuccessful
UERTBACK UERFDONE Backout successful
UERTBACK UERFHOLD Backout unsuccessful
UERTONLY UERFOK Single-phase commit successful
UERTONLY UERFBOUT Single-phase commit failed and backed out
UERTELUW None Not applicable

What is expected of your resource manager

If every request from the syncpoint manager prompts a meaningful response from the resource manager, CICS ensures that changes to recoverable resources (such as databases) can be synchronized. That is, either all the changes take effect or all are backed out, even across system failures.

Limitations

Do not update a recoverable CICS resource during a syncpoint call because any changes will not be seen by the CICS syncpoint manager.

Sample code for a TRUE invoked by the CICS syncpoint manager

The pseudocode given in Figure 8 is only an example. It is not complete, and includes only some of the conditions that a task-related user exit invoked at a syncpoint might be required to check.

Figure 8. Sample pseudocode for a task-related user exit program to be invoked by the CICS syncpoint manager
if UERTFID = UERTSYNC then       /* Caller is CICS syncpoint manager */
  select;                        /* Type of syncpoint manager request */
    when (UERTONLY)                          /* ONLY resource manager */
        invoke RM for single-phase commit    /* Single-phase commit */
        if RM single-phase commit succeeded then
          give CICS syncpoint manager 'YES' vote (UERFOK)
        else                         /* Single-phase commit failed */
                                     /* If RM completed backout */
          if RM single-phase commit failed and backed out
            give CICS syncpoint manager 'NO' vote (UERFBOUT)
          else                       /* Don't know what happened */
            put out message and issue transaction abend
          endif
        endif
    when (UERTELUW)                  /* RM read-only for current UOW */
        invoke RM for single-phase commit    /* Single-phase commit */
    when (UERTPREP)       /* Not ONLY resource manager, nor read-only */
        invoke RM for PREPARE  /* Prepare - phase 1 of 2-phase commit */
        select (resource manager vote)
          when (YES)                 /* Phase 1 completed */
            give CICS syncpoint manager 'YES' vote (UERFPREP)
          otherwise
            give CICS syncpoint manager 'NO' vote (UERFBACK)
        endselect
    when (UERTCOMM)             /* Commit - phase 2 of 2-phase commit */
      invoke RM for commit phase 2
      if RM commit succeeded then
        tell CICS sync manager OK (UERFDONE)
      else
        tell CICS sync manager remember could not commit (UERFHOLD)
      endif
    when (UERTBACK)                  /* Backout request */
      invoke RM for backout
      if RM backout succeeded then
        tell CICS sync manager OK (UERFDONE)
      else
        tell CICS sync manager remember could not backout (UERFHOLD)
      endif
    when (UERTWAIT)                  /* CICS in-doubt about UOW */
      invoke RM to free thread
         (but maintain locks for UOW and record UOW is in-doubt)
  endselect
endif

As described in Increasing efficiency - single-update and read-only protocols, if the UERTONLY bit is set (indicating that the resource manager is the only one to have updated resources) the exit program should cause the resource manager to perform a single-phase commit. If the commit is successful, the exit program should return ‘UERFOK’ in register 15; if not, it should return ‘UERFBOUT’, meaning that the commit was unsuccessful and the resources were backed out. If the exit program is unsure about the outcome of a single-phase commit, it must abend the task, having saved or displayed any diagnostic information that it considers necessary.

Note that "register 15" in this section refers to the syncpoint manager’s register 15, the fifth word of the area addressed by UEPHMSA.

Similarly, when the UERTELUW bit is set (indicating that the resource manager was in read-only mode throughout this UOW), the exit program should cause the resource manager to perform a single-phase commit. There are no return codes for 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 request to perform the first phase of a two-phase commit, the resource manager is expected to get into a state where recoverable changes made since the last syncpoint can be either committed or backed out on demand, even if there is an intervening system failure. For example, buffer contents must be moved to nonvolatile storage. If the resource manager is unable to get into this state, the exit program should return ‘UERFBACK’ in register 15, to request backout. Normally, it should return ‘UERFPREP’, to indicate a successful phase 1 of a 2-phase commit.

On receiving a request to wait (indicating that CICS is in-doubt about the outcome of the UOW), the resource manager should free any task-related resources, such as the thread. However, it should maintain any locks held by the UOW, and record that the UOW is in-doubt. See Enabling for specific invocation-types.

On receiving a request to perform the second phase of a two-phase commit, or a request to back out, the resource manager should take the corresponding irreversible step, and have the exit program send the syncpoint manager a return code: either ‘UERFDONE’, meaning that the commit or abend process is complete; or ‘UERFHOLD’, meaning that the commit or abend must be resolved later. These return code constants are available to you when you code the macro DFHUEXIT TYPE=RM in your exit program.

If a resource manager cannot understand a call, it should not change the contents of the caller’s register 15 before returning to the caller, because it cannot anticipate how the caller will interpret the change.

Resynchronization

If a failure occurs between returning from the exit after performing phase 1 of a 2-phase commit and the subsequent phase 2 or back out call, the resource manager must be ready, on restart, to discover the state of the unit of recovery, and to act accordingly. For programming information about restart resynchronization using the EXEC CICS RESYNC command, see the CICS System Programming Reference manual.

If CICS is in-doubt about a unit of work, it sends the exit program a request to wait (UERTWAIT). When the status of the in-doubt UOW is resolved, CICS initiates a resynchronization task, to inform the exit program of the outcome of the unit of work.

Information about in-doubt units of work is retained across both warm and cold starts of CICS. CICS initialization and keypoint management routines recover from the system log all information associating resource managers with outstanding units of recovery, which are resolved automatically when CICS reconnects to the resource managers concerned.

Coding a program to be invoked by the CICS task manager

If your exit program sets the task manager bit in the schedule flag word, it is invoked at end-of-task. If you specify TASKSTART on the EXEC CICS ENABLE command for the TRUE, it is invoked at start-of-task, and (providing it does not unset the task manager bit), at end-of-task too. To determine whether a particular invocation is at start- or end-of-task, you can examine the CICS task manager parameters described in CICS task manager parameters. Typically, your program shows interest in task manager events if it needs to save task-related information, such as performance or accounting data, before the task ends.

Limitations

If your exit program is invoked at end-of-task, you must be alert to possible limitations on exit program activity at task-detach. For example:

Coding a program to be invoked at CICS termination

If you specify the SHUTDOWN option when enabling your task-related user exit program, it is invoked at system termination. The CICS system termination manager passes the exit program the address of a one-byte code that identifies the type of termination (see CICS termination manager parameters). You can use this invocation of your program to do processing appropriate to the type of termination. For example, at an orderly shutdown you could use it, rather than a PLT program, to shut down the adapter; at a CICS abend you could use it to take special actions, related to the seriousness of the abend.

Limitations

Note that, due to the nature of CICS abends and operator cancels, there is no guarantee that CICS will be able to invoke your exit program at system termination, even if you have specified SHUTDOWN; it may be too impaired to do so.

The limitations on what your program can do, if invoked, depend on the type of termination:

Orderly shutdown (UERTCORD)
Your exit program must follow the rules for programs that execute during the first quiesce stage of CICS shutdown--that is, all CICS services are available, but programs must not start any new tasks.
Immediate shutdown (UERTCIMM)
As for orderly shutdown, except that your exit program should do the minimum required and return control, so that shutdown can proceed.
CICS abend, retry possible, TCBs dispatchable (UERTCABY)
MVS has flagged the failure as being "eligible for retry". Your exit program must follow the MVS rules for this type of failure, documented in the OS/390 MVS Authorized Assembler Services Guide.

Subtasks in the region (that is, task control blocks (TCBs) in addition to the CICS job-step TCB) are still dispatchable, and your exit program can execute code under them.

You must not use any CICS services.

CICS abend, retry not possible, TCBs dispatchable (UERTCABN)
MVS has flagged the failure as "not eligible for retry". Your exit program must follow the MVS rules for this type of failure. Note that your exit program is invoked from code within the CICS extended subtask abend exit (ESTAE). MVS imposes more restrictions on ESTAE code than on non-ESTAE code.

Subtasks in the region are still dispatchable, and your exit program can execute code under them.

You must not use any CICS services.

CICS abend, retry not possible, TCBs not dispatchable (UERTOPCA)
As for UERTCABN, except that subtasks in the region are not dispatchable; your exit program must not try to execute code under any TCBs that it may have attached.
Important

In the abend invocations (UERTCABY through UERTOPCA), your exit program must not use any CICS services. This includes the DFHEIENT call, which performs a CICS GETMAIN. To prevent a DFHEIENT call being issued automatically on each invocation of your program, specify the NOPROLOG translator option; but include in the program source your own DFHEIENT call to be issued on non-abend invocations only. An example of how to code a task-related user exit program to be invoked at CICS termination is given in Figure 9. For further information about coding a DFHEIENT call, see the CICS Application Programming Reference manual.

Sample code for a TRUE invoked at CICS termination

Note that the sample in Figure 9 is a multipurpose program--that is, it is coded to be invoked at many task-related user exit points. However, to avoid the need to test for CICS abends in all of your multipurpose TRUEs, it is recommended that you use a separate program for termination invocations.

Figure 9. Sample code for a task-related user exit program to be invoked at CICS termination
JTRUE1A  CSECT                          TERMINATION TRUE ENTRYPOINT
         STM   14,12,12(13)             Save registers
         USING JTRUE1A,R3
         LR    R3,R15                   Use R3 as base register
         USING DFHUEPAR,R1              Address DFHUEPAR parameter list
         L     R2,UEPEXN
         USING DFHUERTR,R2
         CLI   UERTFID,UERTCTER         CICS Termination call?
         BNE   CONT                     No, so continue
         L     R10,UEPHMSA              Address Host register save area
         USING SA,R10
         L     R5,RSAR1                 Get Caller's R1
         USING DFHCTERM,R5
         L     R5,CTERML                Get termination type
         USING CTERMLIST,R5
         TM    CTERMTYPE,UERTCORD       CICS orderly shutdown?
         BO    CONT                     Yes, so can use CICS services
         TM    CTERMTYPE,UERTCIMM       CICS immediate shutdown?
         BO    CONT                     Yes, so can use CICS services
*        ...
*        ...
*        Insert code here for any processing when CICS is abending
*        (No CICS services should be used)
*        ...
*        ...
         LM    14,12,12(13)             Restore caller's registers
         BSM   0,14                     Return to caller
CONT     DS    0H                       Continue in new CSECT
         LM    14,12,12(13)             Restore callers's registers
         DROP  R3
         USING JTRUE1A,R15              Use R15 as temporary base register
         L     R15,=V(JTRUE1B)          Get address of new CSECT
         BR    R15                      Branch to new CSECT
         DROP  R15
         LTORG
JTRUE1B  CSECT                          POST TEST CSECT
         DFHEIENT
         LR    R4,R1                    Use R4 to address parm list
         USING DFHUEPAR,R4              Address parm list
         L     R5,UEPEXN
         USING DFHUERTR,R5
         MVC   DFHEIBP,UEPEIB
         MVC   DFHEICAP,=X'80000000'
*        .....
*        Insert code here for all types of call other than when CICS
*        is abending
*        (CICS services can be used)
*        .....
EXIT     DS    0H
         DFHEIRET
*
         LTORG
*
DFHCTERM DSECT
CTERML   DS    A
*
CTERMLIST DSECT
CTERMTYPE DS   CL1
*
DFHEISTG DSECT
*
*        Local working storage for CSECT JTRUE1B
*
RSA      DS    18F                      Register save area
SA       DSECT                          Register save area DSECT
         DS    F
*
RSACB    DS    F       +004
RSACF    DS    F       +008
RSAR14   DS    F       +00C
RSAR15   DS    F       +010
RSAR0    DS    F       +014
RSAR1    DS    F       +018
RSAR2    DS    F
RSAR3    DS    F
RSAR4    DS    F
RSAR5    DS    F
RSAR6    DS    F
RSAR7    DS    F
RSAR8    DS    F
RSAR9    DS    F
RSAR10   DS    F
RSAR11   DS    F
RSAR12   DS    F
         DFHREGS
         DFHUEXIT TYPE=RM
         DFHEISTG
         DFHEIEND
         PRINT NOGEN
         PRINT GEN
         END

Using EDF with your task-related user exit program

If your exit program sets the EDF bit in the schedule flag word and EDF is active, the exit program is invoked before and after each API request to format screens for EDF to display.

Communication between the task-related user exit and EDF is controlled by the task-related user exit interface. The command flow between this interface, EDF, and the task-related user exit is summarized in Figure 10.

Figure 10. Interface between the task-related user exit and EDF
 The picture shows, in diagrammatic form, the seven stages of the task-related user exit/EDF interface that are described in the text.

Table 16 describes each stage of the interface between the task-related user exit and EDF, relating the descriptions to the (Tn) and (En) expressions in Figure 10.

Table 16. Description of each stage of the task-related user exit/EDF interface
Invocation Description
(T1) Task-related user exit invoked to set up its EDF requirements. At this stage the task-related user exit prepares the "About to Execute" screen based on the application request.
(E1) Using information passed back from the task-related user exit at invocation T1, the task-related user exit interface invokes EDF to display the "About to Execute" screen. EDF sets up the EDF user response, for example, if the user has changed the screen.
(T2) Task-related user exit is invoked with the EDF user response to the "About to Execute" screen.
(T3) Task-related user exit invoked to access external resource manager for application request.
(T4) Task-related user exit invoked to prepare a "Command Execution Complete" screen, based on the result of the application request.
(E2) Using information passed back from the task-related user exit at invocation T4, the task-related user exit interface invokes EDF to display the "Command Execution Complete" screen. EDF sets up the EDF user response, for example, if the user has changed the screen.
(T5) Task-related user exit is invoked with the EDF user response to the "Command Execution Complete" screen.

Important

The E1/T2 and E2/T5 cycles can be used repeatedly. This may occur, for example, if the EDF user changes the screen a number of times.

Related concepts
Introduction to the task-related user exit mechanism (the adapter)
The stub program
Overview of the XPI
Related tasks
Administering the adapter
Making an XPI call
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]