ATMI C Function Reference
tpnotify()
—Routine for sending notification by client identifier.
#include <atmi.h>
int tpnotify(CLIENTID *clientid, char *data, long len, long flags)
tpnotify()
allows a client or server to send an unsolicited message to an individual client.
clientid
is a pointer to a client identifier saved from the TPSVCINFO
structure of a previous or current service invocation, or passed to a client via some other communications mechanism (for example, retrieved via the administration interface).
The data portion of the request is pointed to by data
, a buffer previously allocated by tpalloc()
. len
specifies how much of data
to send. Note that if data
points to a buffer type that does not require a length to be specified, (for example, an FML
fielded buffer) then len
is ignored (and may be 0). Also, data
may be NULL in which case len
is ignored.
Upon successful return from tpnotify()
, the message has been delivered to the system for forwarding to the identified client. If the TPACK
flag was set, a successful return means the message has been received by the client. Furthermore, if the client has registered an unsolicited message handler, the handler will have been called.
The following is a list of valid flags
:
The request is sent and the caller blocks until an acknowledgement message is received from the target client.
The request is not sent if a blocking condition exists in sending the notification (for example, the internal buffers into which the message is transferred are full).
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
In a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpnotify()
.
Upon failure, tpnotify()
returns -1 and sets tperrno
to indicate the error condition. If a call fails with a particular tperrno
value, a subsequent call to tperrordetail()
, with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the tperrordetail(3c)
reference page for more information.
Upon failure, tpnotify()
sets tperrno
to one of the following values:
The target client does not exist or does not have an unsolicited handler set and the TPACK
flag is set.
A blocking timeout occurred and neither TPNOBLOCK
nor TPNOTIME
were specified, or TPACK
was set but no acknowledgment was received and TPNOTIME
was not specified. (A blocking timeout cannot occur if TPNOBLOCK
and/or TPNOTIME
is specified.)
Introduction to the C Language Application-to-Transaction Monitor Interface, tpalloc(3c)
, tpbroadcast(3c)
, tpchkunsol(3c)
, tperrordetail(3c)
, tpinit(3c)
, tpsetunsol(3c)
, tpstrerrordetail(3c)
, tpterm(3c)