Name

TPCOMMIT() - commit current BEA Tuxedo ATMI transaction

Synopsis

01 TPTRXDEF-REC.
COPY TPTRXDEF.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPCOMMIT" USING TPTRXDEF-REC TPSTATUS-REC

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()), 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 routine 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 communication handles exist for outstanding replies, then upon return from TPCOMMIT(), the transaction is aborted and those handles associated with the caller's transaction are no longer valid. Communication handles 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 setting (that is, connections not in transaction mode) are not affected by calls to TPCOMMIT() or TPABORT().

Currently, TPCOMMIT()'s argument, TPTRXDEF-REC, is reserved for future use.

Return Values

Upon successful completion, TPCOMMIT() sets TP-STATUS to [TPOK].

Errors

Under the following conditions, TPCOMMT() fails and sets TP-STATUS to:

Notices

See Also