Section 3c - C Functions

ATMI C Function Reference

tpsetctxt(3c)

Name

tpsetctxt()—Sets a context identifier for the current application association.

Synopsis

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

Description

tpsetctxt() defines the context in which the current thread operates. This function operates on a per-thread basis in a multithreaded environment, and on a per-process basis in a non-threaded environment.

Subsequent BEA Tuxedo ATMI calls made in this thread reference the application indicated by context. The context should have been provided by a previous call to tpgetctxt() in one of the threads of the same process. If the value of context is TPNULLCONTEXT, then the current thread is disassociated from any BEA Tuxedo ATMI context.

You can put an individual thread in a process operating in multicontext mode into the TPNULLCONTEXT state by issuing the following call:

tpsetctxt(TPNULLCONTEXT, 0)

TPINVALIDCONTEXT is not a valid input value for context.

A thread in the TPINVALIDCONTEXT state is prohibited from issuing calls to most ATMI functions. (For a complete list of the functions that may and may not be called, see Introduction to the C Language Application-to-Transaction Monitor Interface..) Therefore, you may sometimes need to move a thread out of the TPINVALIDCONTEXT state. To do so, call tpsetctxt() with context set to TPNULLCONTEXT or another valid context. (It is also allowable to call the tpterm() function to exit from the TPINVALIDCONTEXT state.)

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

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

Return Values

Upon successful completion, tpsetctxt() returns a non-negative value.

Upon failure, it leaves the calling process in its original context, returns a value of -1, and sets tperrno to indicate the error condition.

Errors

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

[TPEINVAL]

Invalid arguments have been given. For example, flags has been set to a value other than 0 or the context is TPINVALIDCONTEXT.

[TPENOENT]

The value of context is not a valid context.

[TPEPROTO]

tpsetctxt() has been called in an improper context. For example: (a) it has been called in a server-dispatched thread; (b) it has been called in a process that has not called tpinit(); (c) it has been called in a process that has called tpinit() without specifying the TPMULTICONTEXTS flag; or (d) it has been called from more than one thread in a process where the TMNOTHREADS environment variable has been turned on.

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