ATMI C Function Reference
|
 |
 |
|
 |
 |
tpsuspend(3c)
Name
tpsuspend()—Suspends a global transaction.
Synopsis
#include <atmi.h>
int tpsuspend(TPTRANID *tranid, long flags)
Description
tpsuspend() is used to suspend the transaction active in the caller's process. A transaction begun with tpbegin() may be suspended with tpsuspend(). Either the suspending process or another process may use tpresume() to resume work on a suspended transaction. When tpsuspend() returns, the caller is no longer in transaction mode. However, while a transaction is suspended, all resources associated with that transaction (such as database locks) remain active. Like an active transaction, a suspended transaction is susceptible to the transaction timeout value that was assigned when the transaction first began.
For the transaction to be resumed in another process, the caller of tpsuspend() must have been the initiator of the transaction by explicitly calling tpbegin(). tpsuspend() may also be called by a process other than the originator of the transaction (for example, a server that receives a request in transaction mode). In the latter case, only the caller of tpsuspend() may call tpresume() to resume that transaction. This case is allowed so that a process can temporarily suspend a transaction to begin and do some work in another transaction before completing the original transaction (for example, to run a transaction to log a failure before rolling back the original transaction).
tpsuspend() returns in the space pointed to by tranid the transaction identifier being suspended. The caller is responsible for allocating the space to which tranid points. It is an error for tranid to be NULL.
To ensure success, the caller must have completed all outstanding transactional communication with servers before issuing tpsuspend(). That is, the caller must have received all replies for requests sent with tpacall() that were associated with the caller's transaction. Also, the caller must have closed all connections with conversational services associated with the caller's transaction (that is, tprecv() must have returned the TPEV_SVCSUCC event). If either rule is not followed, then tpsuspend() fails, the caller's current transaction is not suspended and all transactional communication descriptors remain valid. Communication descriptors not associated with the caller's transaction remain valid regardless of the outcome of tpsuspend().
Currently, flags are 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 tpsuspend().
Return Value
tpsuspend() returns -1 on error and sets tperrno to indicate the error condition.
Errors
Under the following conditions, tpsuspend() fails and sets tperrno to:
tranidis a NULL pointer orflagsis not 0. The caller's state with respect to the transaction is not changed.The caller's active transaction has been aborted. All communication descriptors associated with the transaction are no longer valid.
tpsuspend()was called in an improper context (for example, the caller is not in transaction mode). The caller's state with respect to the transaction is not changed.
