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   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo C Function Reference

tpsetunsol() - sets the method for handling unsolicited messages

#include <atmi.h>
void (*tpsetunsol (void (_TMDLLENTRY *)(*disp) (char *data, long len, long flags))) (char *data, long len, long flags)

tpsetunsol() allows a client to identify the routine that should be invoked when an unsolicited message is received by the BEA Tuxedo system libraries. Before the first call to tpsetunsol(), any unsolicited messages received by the BEA Tuxedo system libraries on behalf of the client are logged and ignored. A call to tpsetunsol() with a NULL function pointer has the same effect. The method used by the system for notification and detection is determined by the application default, which can be overridden on a per-client basis (see tpinit(3c)).

The function pointer passed on the call to tpsetunsol() must conform to the parameter definition given. data points to the typed buffer received and len is the length of the data. flags are currently unused. data can be NULL if no data accompanied the notification. data may be of a buffer type/subtype that is not known by the client, in which case the message data is unintelligible.

data cannot be freed by application code. However, the system frees it and invalidates the data area following return.

Processing within the application's unsolicited message handling routine is restricted to the following BEA Tuxedo functions: tpalloc(), tpfree(), tpgetctxt(), tpgetlev(), tprealloc(), and tptypes().

Note that in a multithreaded programming environment, it is possible for an unsolicited message handling routine to call tpgetctxt(), create another thread, have that thread call tpsetctxt() to the appropriate context, and have the new thread use the full set of ATMI functions that are available to clients.

If tpsetunsol() is called from a thread that is not currently associated with a context, this establishes a per-process default unsolicited message handler for all new tpinit() contexts created. It has no effect on contexts already associated with the system. A specific context may change this default unsolicited message handler 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.

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpsetunsol().

Upon success, tpsetunsol() returns the previous setting for the unsolicited message handling routine. (NULL is a successful return indicating that no message handling function had been set previously.)

Upon failure, it returns TPUNSOLERR and sets tperrno() to indicate the error condition.

Upon failure, tpsetunsol() sets tperrno() to one of the following values.

[TPEPROTO]

tpsetunsol() has been called in an improper context. For example, it has been called from within a server.

[TPESYSTEM]

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

[TPEOS]

An operating system error has occurred.

The interfaces described in tpnotify(3c) are supported on native site UNIX-based and Windows NT processors. In addition, the routines tpbroadcast() and tpchkunsol(), as well as the function tpsetunsol(), are supported on UNIX and MS-DOS workstation processors.

tpinit(3c), tpterm(3c)