Section 3c - C Functions

ATMI C Function Reference

tpgetctxt(3c)

Name

tpgetctxt()—Retrieves a context identifier for the current application association.

Synopsis

#include <atmi.h>
int tpgetctxt(TPCONTEXT_T *context, long flags)

Description

tpgetctxt() retrieves an identifier that represents the current application context and places that identifier in context. This function operates on a per-thread basis in a multithreaded environment, and on a per-process basis in a non-threaded environment.

Typically, a thread:

Calls tpinit()

Calls tpgetctxt()

Handles the value of context as follows:

In a multithreaded application—passes the value of context to another thread in the same process so the other thread can call tpsetctxt().
In a single-threaded or multithreaded application—saves this context identifier for itself so it can switch back to the indicated context later.

The second argument, flags, is not currently used and must be set to 0.

tpgetctxt() may be called in single-context applications as well as in multicontext applications.

A thread in a multithreaded application may issue a call to tpgetctxt() while running in any context state, including TPINVALIDCONTEXT.

Return Values

Upon successful completion, tpgetctxt() returns a non-negative value. Context is set to the current context ID, which may be represented by any of the following:

A context ID greater than 0, indicating a context in a multicontexted application.
TPSINGLECONTEXT, indicating that the current thread has successfully executed tpinit() without the TPMULTICONTEXTS flag, or that the current thread was just created in a process that has successfully executed tpinit() without the TPMULTICONTEXTS flag. The value of TPSINGLECONTEXT is 0.
TPNULLCONTEXT, indicating that the current thread is not associated with a context.
TPINVALIDCONTEXT, indicating that the current thread is in the invalid context state. If a thread in a multicontexted client issues a call to tpterm() while other threads in the same context are still working, the working threads are placed in the TPINVALIDCONTEXT context. The value of TPINVALIDCONTEXT is -1.

A thread in the TPINVALIDCONTEXT state is prohibited from issuing calls to most ATMI functions. For a complete list of functions that may and may not be called, see the Introduction to the C Language Application-to-Transaction Monitor Interface.
For details about the TPINVALIDCONTEXT context state, see tpterm(3c).

Upon failure, tpgetctxt() returns a value of -1 and sets tperrno to indicate the error condition.

Errors

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

[TPEINVAL]

Invalid arguments have been given. For example, the value of context is NULL or the value of flags is not 0.

[TPESYSTEM]

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

[TPEOS]

An operating system error has occurred.