Bea Tuxedo Application-to-Transaction Monitor Interface (ATMI) In C/C++

TX Transactions

Transactions defined by the TX Interface are practically identical with those defined by the ATMI functions. An application developer may use either set of functions when writing clients and service routines, but should not intermingle one set of functions with the other within a single process (that is, a process cannot call tpbegin() and later call tx_commit()).

The TX Interface has two calls for opening and closing resource managers in a portable manner, tx_open() and tx_close(), respectively. Transactions are started with tx_begin() and completed with either tx_commit() or tx_rollback(). tx_info() is used to retrieve transaction information, and there are three calls to set options for transactions: tx_set_commit_return(), tx_set_transaction_control(), and tx_set_transaction_timeout(). The TX Interface has no equivalents to ATMI's tpsuspend() and tpresume().

In addition to the semantics and rules defined for ATMI transactions, the TX Interface has some additional semantics that are worth introducing here. First, service routine writers wanting to use the TX Interface must supply their own tpsvrinit() routine that calls tx_open(). The default BEA Tuxedo ATMI system-supplied tpsvrinit() calls tpopen(). The same rule applies for tpsvrdone(): if the TX Interface is being used, then service routine writers must supply their own tpsvrdone() that calls tx_close().

Second, the TX Interface has two additional semantics not found in ATMI. These are chained and unchained transactions, and transaction characteristics.

Chained and Unchained Transactions

The TX Interface supports chained and unchained modes of transaction execution. By default, clients and service routines execute in the unchained mode; when an active transaction is completed, a new transaction does not begin until tx_begin() is called.

In the chained mode, a new transaction starts implicitly when the current transaction completes. That is, when tx_commit() or tx_rollback() is called, the BEA Tuxedo ATMI system coordinates the completion of the current transaction and initiates a new transaction before returning control to the caller. (Certain failure conditions may prevent a new transaction from starting.)

Clients and service routines enable or disable the chained mode by calling tx_set_transaction_control(). Transitions between the chained and unchained mode affect the behavior of the next tx_commit() or tx_rollback() call. The call to tx_set_transaction_control() does not put the caller into or take it out of transaction mode.

Since tx_close() cannot be called when the caller is in transaction mode, a caller executing in chained mode must switch to unchained mode and complete the current transaction before calling tx_close().

Transaction Characteristics

A client or a service routine may call tx_info() to obtain the current values of their transaction characteristics and to determine whether they are executing in transaction mode.

The state of an application process includes several transaction characteristics. The caller specifies these by calling tx_set_*() functions. When a client or a service routine sets the value of a characteristic, it remains in effect until the caller specifies a different value. When the caller obtains the value of a characteristic via tx_info(), it does not change the value.

Error Handling

Most of the ATMI functions have one or more error returns. An error condition is indicated by an otherwise impossible returned value. This is usually -1 or error, or 0 for a bad field identifier (BADFLDID) or address. The error type is also made available in the external integer tperrno. tperrno is not cleared on successful calls, so it should be tested only after an error has been indicated.

The tpstrerror() function is provided to produce a message on the standard error output. It takes one argument, an integer (found in tperrno) and returns a pointer to the text of an error message in LIBTUX_CAT. The pointer can be used as an argument to userlog().

tperrordetail() can be used as the first step of a three step procedure to get additional detail about an error in the most recent BEA Tuxedo ATMI system call on the current thread. tperrordetail() returns an integer which is then used as an argument to tpstrerrordetail() to retrieve a pointer to a string that contains the error message. The pointer can then be used as an argument to userlog or to fprintf().

The error codes that can be produced by an ATMI function are described on each ATMI reference page. The F_error() and F_error32() functions are provided to produce a message on the standard error output for FML errors. They take one parameter, a string; print the argument string appended with a colon and a blank; and then print an error message followed by a newline character. The error message displayed is the one defined for the error number currently in Ferror() or Ferror32(), which is set when errors occur.

Fstrerror(), and its counterpart, Fstrerror32(), can be used to retrieve the text of an FML error message from a message catalog; it returns a pointer that can be used as an argument to userlog.

The error codes that can be produced by an FML function are described on each FML reference page.

Dynamic Service Advertisements

By default, a server's services are advertised when it is booted and unadvertised when it is shut down. If a server needs to control the set of services that it offers at run time, it can do so by calling tpadvertise() and tpunadvertise(). These routines affect only the services offered by the calling server unless that server belongs to a Multiple Server, Single Queue (MSSQ) set. Because all servers in an MSSQ set must offer the same set of services, these routines also affect the advertisements of all servers sharing the caller's MSSQ set.