PURPOSE

tpnotify - routine for sending notification by client identifier

SYNOPSIS

#include <atmi.h>
int tpnotify(CLIENTID *clientid, char *data, long len, long flags)

DESCRIPTION

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(3c). 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.

Following is a list of valid flags.

TPACK

The request is sent and the caller blocks until an acknowledgement message is received from the target client.

TPNOBLOCK

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).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is reissued.

Unless the TPACK flag is set, tpnotify() does not wait for the message to be delivered to the client.

RETURN VALUES

tpnotify() returns -1 on failure and sets tperrno to indicate the error condition.

ERRORS

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

[TPEINVAL]

Invalid arguments were given (for example, invalid flags).

[TPENOENT]

The target client does not exist and the TPACK flag is set.

[TPETIME]

A blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified, or TPACK was set but no acknowledgement was received and TPNOTIME was not specified.

[TPEBLOCK]

A blocking condition was found on the call and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tpnotify() was called in an improper context.

[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.

[TPERELEASE]

When the TPACK is set and the target is a client from a prior release of TUXEDO that does not support the acknowledgement protocol.

SEE ALSO

intro(3c),
tpalloc(3c),
tpbroadcast(3c),
tpchkunsol(3c),
tpinit(3c),
tpsetunsol(3c),
tpterm(3c)