PURPOSE

tpsetunsol - routine for setting method of handling unsolicited messages

SYNOPSIS


#include <atmi.h>
void (*tpsetunsol (void (*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 System/T libraries. Prior to the first call to tpsetunsol(), any unsolicited messages received by the System/T 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 can not be freed by application code. However, the system frees it and invalidates the data area following return.

Processing within the application unsolicited message handling routine is restricted to the following System/T calls: tpalloc(3) tpgetlev(3) tprealloc(3) tptypes(3) tpfree(3)

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); otherwise, it returns TPUNSOLERR and sets tperrno to indicate the error condition.

ERRORS

Under the following conditions, tpsetunsol() fails and sets tperrno to:

[TPEPROTO]: tpsetunsol() was called in an improper context (e.g., from within a server).
[TPESYSTEM]: A System/T error has occurred. The exact nature of the error is written to a log file.
[TPEOS]: An operating system error has occurred.

PORTABILITY