ATMI C Function Reference
tpscmt()
—Routine for setting when tpcommit()
should return.
#include <atmi.h>
int tpscmt(long flags)
tpscmt()
sets the TP_COMMIT_CONTROL
characteristic to the value specified in flags
. The TP_COMMIT_CONTROL
characteristic affects the way tpcommit()
behaves with respect to returning control to its caller. A program can call tpscmt()
regardless of whether it is in transaction mode or not. Note that if the caller is participating in a transaction that another program must commit, then its call to tpscmt()
does not affect that transaction. Rather, it affects subsequent transactions that the caller will commit.
In most cases, a transaction is committed only when a BEA Tuxedo ATMI system thread of control calls tpcommit()
. There is one exception: when a service is dispatched in transaction mode because the AUTOTRAN
variable in the *SERVICES
section of the UBBCONFIG
file is enabled, then the transaction completes upon calling tpreturn()
. If tpforward()
is called, then the transaction will be completed by the server ultimately calling tpreturn()
. Thus, the setting of the TP_COMMIT_CONTROL
characteristic in the service that calls tpreturn()
determines when tpcommit()
returns control within a server. If tpcommit()
returns a heuristic error code, the server will write a message to a log file.
When a client joins a BEA Tuxedo ATMI system application, the initial setting for this characteristic comes from a configuration file. (See the CMTRET
variable in the RESOURCES
section of UBBCONFIG(5))
The following are the valid settings for flags
:
This flag indicates that tpcommit()
should return after the commit decision has been logged by the first phase of the two-phase commit protocol but before the second phase has completed. This setting allows for faster response to the caller of tpcommit()
although there is a risk that a transaction participant might decide to heuristically complete (that is, abort) its work due to timing delays waiting for the second phase to complete. If this occurs, there is no way to indicate this situation to the caller since tpcommit()
has already returned (although the BEA Tuxedo ATMI system writes a message to a log file when a resource manager takes a heuristic decision). Under normal conditions, participants that promise to commit during the first phase will do so during the second phase. Typically, problems caused by network or site failures are the sources for heuristic decisions being made during the second phase.
This flag indicates that tpcommit(3c)
should return after the two-phase commit protocol has finished completely. This setting allows for tpcommit()
to return an indication that a heuristic decision occurred during the second phase of commit.
In a multi-threaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpscmt()
.
Upon success, tpscmt()
returns the previous value of the TP_COMMIT_CONTROL
characteristic.
Upon failure, tpscmt()
returns -1 and sets tperrno
to indicate the error condition.
Upon failure, tpscmt()
sets tperrno
to one of the following values:
When using tpbegin()
, tpcommit()
and tpabort()
to delineate a BEA Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit()
or tpabort()
. See buildserver(1) for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of a BEA Tuxedo ATMI system transaction.