Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo C Function Reference

tpbegin() - routine for beginning a transaction

#include <atmi.h>
int tpbegin(unsigned long timeout, long flags)

A transaction in the BEA Tuxedo system is used to define a single logical unit of work that either wholly succeeds or has no effect whatsoever. A transaction allows work being performed in many processes, at possibly different sites, to be treated as an atomic unit of work. The initiator of a transaction uses tpbegin() and either tpcommit() or tpabort() to delineate the operations within a transaction. Once tpbegin() is called, communication with any other program can place the latter (of necessity, a server) in "transaction mode" (that is, the server's work becomes part of the transaction). Programs that join a transaction are called participants. A transaction always has one initiator and can have several participants. Only the initiator of a transaction can call tpcommit() or tpabort(). Participants can influence the outcome of a transaction by the return values (rvals) they use when they call tpreturn(). Once in transaction mode, any service requests made to servers are processed on behalf of the transaction (unless the requester explicitly specifies otherwise).

Note that if a program starts a transaction while it has any open connections that it initiated to conversational servers, these connections will not be upgraded to transaction mode. It is as if the TPNOTRAN flag had been specified on the tpconnect() call.

tpbegin()'s first argument, timeout, specifies that the transaction should be allowed at least timeout seconds before timing out. Once a transaction times out it must be marked abort-only. If timeout is 0, then the transaction is given the maximum number of seconds allowed by the system before timing out (that is, the timeout value equals the maximum value for an unsigned long as defined by the system).

Currently, tpbegin()'s second 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 tpbegin().

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

Upon failure, tpbegin() sets tperrno() to one of the following values.

[TPEINVAL]

flags is not equal to 0.

[TPETRAN]

The caller cannot be placed in transaction mode because an error occurred starting the transaction.

[TPEPROTO]

tpbegin() was called in an improper context (for example, the caller is already in transaction mode).

[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.

When using tpbegin(), tpcommit(), and tpabort() to delineate a BEA Tuxedo 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() 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 system transaction.

tpabort(3c), tpcommit(3c), tpgetlev(3c), tpscmt(3c)