ATMI C Function Reference
tpcommit()
—Routine for committing current transaction.
#include <atmi.h>
int tpcommit(long flags)
tpcommit()
signifies the end of a transaction, using a two-phase commit protocol to coordinate participants. tpcommit()
can be called only by the initiator of a transaction. If any of the participants cannot commit the transaction (for example, they call tpreturn()
with TPFAIL
), then the entire transaction is aborted and tpcommit()
fails. That is, all of the work involved in the transaction is undone. If all participants agree to commit their portion of the transaction, then this decision is logged to stable storage and all participants are asked to commit their work.
Depending on the setting of the TP_COMMIT_CONTROL
characteristic (see tpscmt(3c)
), tpcommit()
can return successfully either after the commit decision has been logged or after the two-phase commit protocol has completed. If tpcommit()
returns after the commit decision has been logged but before the second phase has completed (TP_CMT_LOGGED
), then all participants have agreed to commit the work they did on behalf of the transaction and should fulfill their promise to commit the transaction during the second phase. However, because tpcommit()
is returning before the second phase has completed, there is a hazard that one or more of the participants can heuristically complete their portion of the transaction (in a manner that is not consistent with the commit decision) even though the function has returned success.
If the TP_COMMIT_CONTROL
characteristic is set such that tpcommit()
returns after the two-phase commit protocol has completed (TP_CMT_COMPLETE
), then its return value reflects the exact status of the transaction (that is, whether the transaction heuristically completed or not).
Note that if only a single resource manager is involved in a transaction, then a one-phase commit is performed (that is, the resource manager is not asked whether or not it can commit; it is simply told to commit). In this case, the TP_COMMIT_CONTROL
characteristic has no bearing and tpcommit()
will return heuristic outcomes if present.
If tpcommit()
is called while call descriptors exist for outstanding replies, then upon return from the function, the transaction is aborted and those descriptors associated with the caller's transaction are no longer valid. Call descriptors not associated with the caller's transaction remain valid.
tpcommit()
must be called after all connections associated with the caller's transaction are closed (otherwise TPEABORT
is returned, the transaction is aborted and these connections are disconnected in a disorderly fashion with a TPEV_DISCONIMM
event). Connections opened before tpbegin()
or with the TPNOTRAN
flag (that is, connections not in transaction mode) are not affected by calls to tpcommit()
or tpabort()
.
Currently, tpcommit()
's sole argument, flags
, is reserved for future use and must be set to 0.
In a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpcommit()
.
Upon failure, tpcommit()
returns -1 and sets tperrno
to indicate the error condition.
Upon failure, tpcommit()
sets tperrno
to one of the following values:
The transaction could not commit because either the work performed by the initiator or by one or more of its participants could not commit. This error is also returned if tpcommit()
is called with outstanding replies or open conversational connections.
Due to some failure, the work done on behalf of the transaction could have been heuristically completed.
Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.
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.
tpabort(3c)
, tpbegin(3c)
, tpconnect(3c)
, tpgetlev(3c)
, tpreturn(3c)
, tpscmt(3c)