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).
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 and OPENAPI programs
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.
An open API TRUE must not treat the executing open TCB environment in such a way that it causes problems for:
In particular:
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:
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.
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 gives you the following symbolic names for address parameters:
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.
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:
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:
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 | ![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
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.
The function definition identifies the caller of the task-related user exit program. The DSECT contains two symbolic definitions (fields).
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.
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.
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:
If the caller is an application program, the format and addressing of its parameter list are decided locally.
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:
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.
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.
Note that parameters 2 through 8 describe the environment of the original task (not of the task that is currently driving the TRUE).
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:
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.
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:
For further information about shutdown TRUEs, see Coding a program to be invoked at CICS termination.
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:
Figure 7 shows, in diagrammatic form, the relationships between the parameter lists that are discussed in the preceding sections.
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.
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.
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.
In this section, two sets of registers are discussed:
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:
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.
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.
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.
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.
When you are running CICS with the storage protection facility, there are two points you need to consider for task-related user exits:
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.
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.
The storage key of storage used by task-related user exit programs depends on how the storage is obtained:
The default storage key for storage obtained by EXEC CICS commands is set by the TASKDATAKEY of the transaction under which the exit program is invoked.
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.
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.
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:
TESTPROG DFHEIENT CODEREG=2,EIBREG=11,DATAREG=10
USING DFHUEPAR,1
MVC DFHEIBP,UEPEIB Get correct EIB address
L DFHEIBR,UEPEIB Reload EIB base register
MVC DFHEICAP,=X'80000000'
Note
that the entry point of a program does not have to be at the start of the
program and can be positioned after the DFHEIENT macro.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.
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.
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.
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.
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.
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.
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.)
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.)
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.
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.
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).
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.)
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 |
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.
Do not update a recoverable CICS resource during a syncpoint call because any changes will not be seen 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.
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.
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.
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.
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:
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.
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:
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.
Subtasks in the region are still dispatchable, and your exit program can execute code under them.
You must not use any CICS services.
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.
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.
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
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.
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.
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. |
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.