Section 3c - C Functions

ATMI C Function Reference

tpcommit(3c)

Name

tpcommit()—Routine for committing current transaction.

Synopsis

#include <atmi.h> int tpcommit(long flags)

Description

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().

Return Values

Upon failure, tpcommit() returns -1 and sets tperrno to indicate the error condition.

Errors

Upon failure, tpcommit() sets tperrno to one of the following values:

[TPEABORT]

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.

[TPEHAZARD]

Due to some failure, the work done on behalf of the transaction could have been heuristically completed.

[TPEHEURISTIC]

Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.

[TPEINVAL]

flags is not equal to 0. The caller's transaction is not affected.

[TPEOS]

An operating system error has occurred.

[TPEPROTO]

tpcommit() was called in an improper context (for example, by a participant).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPETIME]

The transaction has timed out and its status is unknown: it may have been either committed or aborted. If a transaction has timed out and its status is known to be aborted, then TPEABORT is returned.

Notices

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.