ATMI C Function Reference
|
 |
 |
|
 |
 |
tpterm(3c)
Name
tpterm()—Leaves an application.
Synopsis
#include <atmi.h>
int tpterm(void)
Description
tpterm() removes a client from a BEA Tuxedo ATMI system application. If the client is in transaction mode, then the transaction is rolled back. When tpterm() returns successfully, the caller can no longer perform BEA Tuxedo ATMI client operations. Any outstanding conversations are immediately disconnected.
If tpterm() is called more than once (that is, if it is called after the caller has already left the application), no action is taken and success is returned.
Multithreading and Multicontexting Issues
In good programming practice, all threads but one should either exit or switch context before the single remaining thread issues a call to tpterm(). If this is not done, then the remaining threads are put in a TPINVALIDCONTEXT context. A description of the semantics of this context follows.
When invoked by one thread in a context with which multiple threads are associated, tpterm():
- Operates on all threads in a context, but not on all contexts in a process
- Executes immediately, even if other threads in the same process are still associated with that context
Any thread blocked in an ATMI call when another thread terminates its context will return from the ATMI call with a failure return; tperrno is set to TPESYSTEM. In addition, if tperrordetail() is invoked after such a failure return, it returns TPED_INVALIDCONTEXT.
In a single-context application, whenever a single thread calls tpterm(), the context state for all threads is set to TPNULLCONTEXT.
In a multicontexted application, however, when tpterm() is invoked by one thread, all other threads in the same context are placed in a state such that if they subsequently call most ATMI functions, those functions will, instead, return failure with tperrno set to TPEPROTO. Lists of the functions that are allowed and disallowed in such an invalid context state are provided in Introduction to the C Language Application-to-Transaction Monitor Interface. If a thread in the invalid context state (TPINVALIDCONTEXT) calls the tpgetctxt() function, tpgetctxt() sets the context parameter to TPINVALIDCONTEXT.
A thread may exit from the TPINVALIDCONTEXT state by calling one of the following:
It is forbidden to call tpsetctxt() with a context of TPINVALIDCONTEXT; doing so results in failure with tperrno set to TPEPROTO. When a thread invokes ATMI functions other than tpsetunsol()that do not require the caller to be associated with an application, these functions behave as if they were invoked in the NULL context. Client applications using unsolicited thread notification should explicitly call tpterm() to terminate the unsolicited notification thread.
After invoking tpterm(), a thread is placed in the TPNULLCONTEXT context. Most ATMI functions invoked by a thread in the TPNULLCONTEXT context perform an implicit tpinit(). Whether or not the call to tpinit() succeeds depends on the usual determining factors, unrelated to context-specific or thread-specific issues.
A thread in a multithreaded application may issue a call to tpterm() while running in any context state, including TPINVALIDCONTEXT.
Return Values
Upon success in a single-context application, all threads in the application's current context are placed in the TPNULLCONTEXT state.
Upon success in a multicontexted application, the calling thread is placed in the TPNULLCONTEXT state and all other threads in the same context as the calling thread are placed in the TPINVALIDCONTEXT state. The user may change the context state of the latter threads by running tpsetctxt() with the context argument set to TPNULLCONTEXT or another valid context.
Upon failure, tpterm() leaves the calling process in its original context state, returns -1, and sets tperrno to indicate the error condition.
Errors
Upon failure, tpterm() sets tperrno to one of the following values:
