Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Programming a BEA Tuxedo Application Using C

• Coding Rules for a Multithreaded Client

• Initializing a Client to Multiple Contexts

• Getting Replies in a Multithreaded Environment

• Using Environment Variables in a Multithreaded and/or Multicontexted Environment

• Using Per-context Functions and Data Structures in a Multithreaded Client

• Using Per-process Functions and Data Structures in a Multithreaded Client

• Using Per-thread Functions and Data Structures in a Multithreaded Client

• Sample Code for a Multithreaded Client

  Note: The BEA Tuxedo system does not support multithreaded COBOL applications.

Coding Rules for a Multithreaded Client

Keep in mind the following rules for coding multithreaded clients:

• Once a conversation has been started, any thread in the same process can work on that conversation. Handles and call descriptors are portable within the same context in the same process, but not between contexts or processes. Handles and call descriptors can be used only in the application context in which they are originally assigned.

• Any thread operating in the same context within the same process can invoke tpgetrply() to receive a response to an earlier call to tpacall(), regardless of whether or not that thread originally called tpacall().

• A transaction can be committed or aborted by only one thread, which may or may not be the same thread that started it.

• All RPC calls and all conversations must be completed before an attempt is made to commit the transaction. If an application calls tpcommit() while RPC calls or conversations are outstanding, tpcommit() aborts the transaction, returns -1, and sets tperrno(5) to TPEABORT.

• Functions such as tpcall(), tpacall(), tpgetrply(), tpconnect(), tpsend(), tprecv(), and tpdiscon() should not be called in transaction mode unless you are sure that the transaction is not already committing or aborting.

• Two tpbegin() calls cannot be made simultaneously for the same context.

• tpbegin() cannot be issued for a context that is already in transaction mode.

• If you are using a client and you want to connect to more than one domain, you must manually change the value of TUXCONFIG or WSNADDR before calling tpinit(). You must synchronize the setting of the environment variable and the tpinit() call if multiple threads may be performing such an action. All application associations in a client must obey the following rules:

  • All associations must be made to the same release of the BEA Tuxedo system.

  • Either every application association in a particular client must be made as a native client, or every application association must be made as a workstation client.

• To join an application, a multithreaded workstation client must always call tpinit() with the TPMULTICONTEXTS flag set, even if the client is running in single-context mode.

Initializing a Client to Multiple Contexts

To have a client join more than one context, issue a call to the tpinit() function with the TPMULTICONTEXTS flag set in the flags element of the TPINIT data structure.

In any one process, either all calls to tpinit() must include the TPMULTICONTEXTS flag or no call to tpinit() may include this flag. The only exception to this rule is that if all of a client's application associations are terminated by successful calls to tpterm(), then the process is restored to a state in which the inclusion of the TPMULTICONTEXTS flag in the next call to tpinit() is optional.

When tpinit() is invoked with the TPMULTICONTEXTS flag set, a new application association is created and is designated the current association. The BEA Tuxedo domain to which the new association is made is determined by the value of the TUXCONFIG or WSENVFILE/WSNADDR environment variable.

When a client thread successfully executes tpinit() without the TPMULTICONTEXTS flag, all threads in the client are placed in the single-context state (TPSINGLECONTEXT).

On failure, tpinit() leaves the calling thread in its original context (that is, in the context state in which it was operating before the call to tpinit()).

Do not call tpterm() from a given context if any of the threads in that context are still working. See the table labeled Multicontext State Transitions for a description of the context states that result from calling tpterm() under these and other circumstances.

In a multicontext application, calls to various functions result in context state changes for the calling thread and any other threads that are active in the same context as the calling process. The following diagram illustrates the context state changes that result from calls to tpinit(), tpsetctxt(3c), and tpterm(). (The tpgetctxt(3c) function does not produce any context state changes.)

Multicontext State Transitions

Note: When tpterm() is called by a thread running in the multicontext state (TPMULTICONTEXTS), the calling thread is placed in the null context state (TPNULLCONTEXT). All other threads associated with the terminated context are switched to the invalid context state (TPINVALIDCONTEXT).

The following table lists all possible context state changes produced by calling tpinit(), tpsetctxt(3c), and tpterm().

Context State Changes for a Client Thread

When this function is executed . . .	Then a thread in this context state results in . . .
	Null Context	Single Context	Multicontext	Invalid Context
tpinit() without TPMULTICONTEXTS	Single context	Single context	Error	Error
tpinit() with TPMULTICONTEXTS	Multicontext	Error	Multicontext	Error
tpsetctxt(3c) to TPNULLCONTEXT	Null	Error	Null	Null
tpsetctxt(3c) to context 0	Error	Single context	Error	Error
tpsetctxt(3c) to context > 0	Multicontext	Error	Multicontext	Multicontext
Implicit tpinit()	Single context	N/A	N/A	Error
tpterm() in this thread	Null	Null	Null	Null
tpterm() in a different thread of this context	N/A	Null	Invalid	N/A

Getting Replies in a Multithreaded Environment

tpgetrply() receives responses only to requests made via tpacall(). Requests made with tpcall() are separate and cannot be retrieved with tpgetrply() regardless of the multithreading or multicontexting level.

tpgetrply() operates in only one context, which is the context in which it is called. Therefore, when you call tpgetrply() with the TPGETANY flag, only handles generated in the same context are considered. Similarly, a handle generated in one context may not be used in another context, but the handle may be used in any thread operating within the same context.

When tpgetrply() is called in a multithreaded environment, the following restrictions apply:

• If a thread calls tpgetrply() for a specific handle while another thread in the same context is already waiting in tpgetrply() for the same handle, tpgetrply() returns -1 and sets tperrno to TPEPROTO.

• If a thread calls tpgetrply() for a specific handle while another thread in the same context is already waiting in tpgetrply() with the TPGETANY flag, the call returns -1 and sets tperrno(5) to TPEPROTO.

  The same behavior occurs if a thread calls tpgetrply() with the TPGETANY flag while another thread in the same context is already waiting in tpgetrply() for a specific handle. These restrictions protect a thread that is waiting on a specific handle from having its reply taken by a thread waiting on any handle.

• At any given time, only one thread in a particular context can wait in tpgetrply() with the TPGETANY flag set. If a second thread in the same context invokes tpgetrply() with the TPGETANY flag while a similar call is outstanding, this second call returns -1 and sets tperrno(5) to TPEPROTO.

Using Environment Variables in a Multithreaded and/or Multicontexted Environment

When a BEA Tuxedo application is run in an environment that is multicontexted and/or multithreaded, the following considerations apply to the use of environment variables:

• A process initially inherits its environment from the operating system environment. On platforms that support environment variables, such variables make up a per-process entity. Therefore, applications that depend on per-context environment settings should use the tuxgetenv(3c) function instead of an OS function.

  Note: The environment is initially empty for those operating systems that do not recognize an operating system environment.

• Many environment variables are read by the BEA Tuxedo system only once per process or once per context and then cached within the BEA Tuxedo system. Changes to such variables once cached in the process have no effect.

  Caching is done on a . . .	For environment variables such as . . .
  Per-context basis	TUXCONFIG
  	FIELDTBLS and FIELDTBLS32
  	FLDTBLDIR and FLDTBLDIR32
  	ULOGPFX
  	VIEWDIR and VIEWDIR32
  	VIEWFILES and VIEWFILES32
  	WSNADDR
  	WSDEVICE
  	WSENV
  Per-process basis	TMTRACE
  	TUXDIR
  	ULOGDEBUG

• The tuxputenv(3c) function affects the environment for the entire process.

• When you call the tuxreadenv(3c) function, it reads a file containing environment variables and adds them to the environment for the entire process.

• The tuxgetenv(3c) function returns the current value of the requested environment variable in the current context. Initially, all contexts have the same environment, but the use of environment files specific to a particular context can cause different contexts to have different environment settings.

• If a client intends to initialize to more than one domain, the client must change the value of the TUXCONFIG, WSNADDR, or WSENVFILE environment variable to the proper value before each call to tpinit(). If such an application is multithreaded, a mutex or other application-defined concurrency control will probably be needed to ensure that:

  • The appropriate environment variable is reset.

  • The call to tpinit() is made without the environment variable being re-set by any other thread.

• When a client initializes to the system, the WSENVFILE and/or machine environment file is read and affects the environment in that context only. The previous environment for the process as a whole remains for that context to the extent that it is not overridden within the environment file(s).

Using Per-context Functions and Data Structures in a Multithreaded Client

The following ATMI functions affect only the application contexts in which they are called:

• tpabort()

• tpacall()

• tpadmcall(3c)

• tpbegin()

• tpbroadcast()

• tpcall()

• tpcancel()

• tpchkauth()

• tpchkunsol()

• tpclose(3c)

• tpcommit()

• tpconnect()

• tpdequeue(3c)

• tpdiscon()

• tpenqueue(3c)

• tpforward()

• tpgetlev()

• tpgetrply()

• tpinit()

• tpnotify()

• tpopen(3c)

• tppost()

• tprecv()

• tpresume()

• tpreturn()

• tpscmt(3c)

• tpsend()

• tpservice(3c)

• tpsetunsol()

• tpsubscribe()

• tpsuspend()

• tpterm()

• tpunsubscribe()

• tx_begin(3c)

• tx_close(3c)

• tx_commit(3c)

• tx_info(3c)

• tx_open(3c)

• tx_rollback(3c)

• tx_set_commit_return(3c)

• tx_set_transaction_control(3c)

• tx_set_transaction_timeout(3c)

• userlog(3c)

  Note: For tpbroadcast(), the broadcast message is identified as having come from a particular application association. For tpnotify(3c), the notification is identified as having come from a particular application association. See "Using Per-process Functions and Data Structures in a Multithreaded Client" for notes about tpinit().

  If tpsetunsol() is called from a thread that is not associated with a context, a per-process default unsolicited message handler for all new tpinit() contexts created is established. A specific context may change the unsolicited message handler for that context by calling tpsetunsol() again when the context is active. The per-process default unsolicited message handler may be changed by again calling tpsetunsol() in a thread not currently associated with a context.

• The CLIENTID, client name, user name, transaction ID, and the contents of the TPSVCINFO data structure may differ from context to context within the same process.

• Asynchronous call handles and connection descriptors are valid in the contexts in which they are created. The unsolicited notification type is specific per-context. Although signal-based notification may not be used with multiple contexts, each context may choose one of three options:

  • Ignoring unsolicited messages

  • Using dip-in notification

  • Using dedicated thread notification

Using Per-process Functions and Data Structures in a Multithreaded Client

The following BEA Tuxedo functions affect the entire process in which they are called.

• tpadvertise()

• tpalloc()

• tpconvert(3c)-The requested structure is converted, although it is probably relevant to only a subset of the process.

• tpfree()

• tpinit()-to the extent that the per-process TPMULTICONTEXTS mode or single-context mode is established. See also Using Per-context Functions and Data Structures in a Multithreaded Client.

• tprealloc()

• tpsvrdone()

• tpsvrinit()

• tptypes()

• tpunadvertise()

• tuxgetenv(3c)-if the OS environment is per-process

• tuxputenv(3c)-if the OS environment is per-process

• tuxreadenv(3c)-if the OS environment is per-process

• Usignal(3c)

The determination of single-context mode, multicontext mode, or uninitialized mode affects an entire process. The buffer type switch, the view cache, and environment variable values are also per-process functions.

Only the calling thread is affected by the following:

• CATCH

• tperrordetail(3c)

• tpgetctxt(3c)

• tpgprio()

• tpsetctxt(3c)

• tpsprio()

• tpstrerror(3c)

• tpstrerrordetail(3c)

• TRY(3c)

• Uunix_err(3c)

The Ferror, Ferror32(5), tperrno(5), tpurcode(5), and Uunix_err variables are specific to each thread.

The identity of the current context is specific to each thread.

The following example shows a multithreaded client using ATMI calls. Threads functions differ from one operating system to another. In this example, POSIX functions are used.

Note: In order to simplify this example, error checking code has not been included.

#include <stdio.h>
#include <pthread.h>
#include <atmi.h>

TPINIT   *   tpinitbuf;
int          timeout=60;
pthread_t    withdrawalthreadid, stockthreadid;
TPCONTEXT_T  ctxt;
void * stackthread(void *);
void * withdrawalthread(void *);

main()
{
	tpinitbuf = tpalloc(TPINIT, NULL, TPINITNEED(0));
	/*
	 * This code will perform a transfer, using separate threads for the 
	 * withdrawal and deposit.   It will also get the current 
	 * price of BEA stock from a separate application, and calculate how
	 * many shares the transferred amount can buy.
	 */

	tpinitbuf->flags = TPMULTICONTEXTS;

	/* Fill in the rest of tpinitbuf.  */
	tpinit(tpinitbuf);

	tpgetctxt(&ctxt, 0);
	tpbegin(timeout, 0);
	pthread_create(&withdrawalthreadid, NULL, withdrawalthread, NULL);
	tpcall("DEPOSIT", ...);

	/* Wait for the withdrawal thread to complete. */
	pthread_join(withdrawalthreadid, NULL);

	tpcommit(0);
	tpterm();

	/* Wait for the stock thread to complete. */
	pthread_join(stockthreadid, NULL);

	/* Print the results. */
	printf("$%9.2f has been transferred \
	from your savings account to your checking account.\n", ...);

	printf("At the current BEA stock price of $%8.3f, \
	you could purchase %d shares.\n", ...);

	exit(0);
}



void *
stockthread(void *arg)
{

     /* The other threads have now called tpinit(), so resetting TUXCONFIG can
      * no longer adversely affect them.
     */

     tuxputenv("TUXCONFIG=/home/users/xyz/stockconf");
     tpinitbuf->flags = TPMULTICONTEXTS;
     /* Fill in the rest of tpinitbuf. */
     tpinit(tpinitbuf);
     tpcall("GETSTOCKPRICE", ...);
      /* Save the stock price in a variable that can also be accessed in main(). */
     tpterm();
     return(NULL);
}



void *
withdrawalthread(void *arg)
{
	/* Create a separate thread to get stock prices from a different
	 * application. 
	*/

     pthread_create(&stockthreadid, NULL, stockthread, NULL);
     tpsetctxt(ctxt, 0);
     tpcall("WITHDRAWAL", ...);
     return(NULL);
}

• How Multithreading and Multicontexting Work in a Client

• Preliminary Guidelines for Programming a Multithreaded/Multicontexted Application

• Writing Code to Enable Multicontexting in a Client