ATMI C Function Reference
|
 |
 |
|
 |
 |
tpsetunsol(3c)
Name
tpsetunsol()—Sets the method for handling unsolicited messages.
Synopsis
#include <atmi.h>
void (*tpsetunsol (void (_TMDLLENTRY *)(*disp) (char *data, long len, long flags))) (char *data, long len, long flags)
Description
tpsetunsol() allows a client to identify the routine that should be invoked when an unsolicited message is received by the BEA Tuxedo ATMI system libraries. Before the first call to tpsetunsol(), any unsolicited messages received by the BEA Tuxedo ATMI 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. The _TMDLLENTRY macro is required for Windows-based operating systems to obtain the proper calling conventions between the Tuxedo libaries and your code. On Unix systems, the _TMDLLENTRY macro is not required because it expands to the null string.
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 ATMI 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().
Return Values
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.
Errors
Upon failure, tpsetunsol() sets tperrno to one of the following values:
tpsetunsol()has been called in an improper context. For example, it has been called from within a server.
Portability
The interfaces described in tpnotify(3c) are supported on native site UNIX-based and Windows processors. In addition, the routines tpbroadcast() and tpchkunsol(), as well as the function tpsetunsol(), are supported on UNIX and MS-DOS workstation processors.
