Section 3c - C Functions

ATMI C Function Reference

tpscmt(3c)

Name

tpscmt()—Routine for setting when tpcommit() should return.

Synopsis

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

Description

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:

TP_CMT_LOGGED

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.

TP_CMT_COMPLETE

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

Return Values

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.

Errors

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

[TPEINVAL]

flags is not one of TP_CMT_LOGGED or TP_CMT_COMPLETE.

[TPEPROTO]

tpscmt() was called improperly.

[TPESYSTEM]

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

[TPEOS]

An operating system error has occurred.

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.