Section 3c - C Functions

ATMI C Function Reference

tpnotify(3c)

Name

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

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.

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

Return Values

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.

Errors

Upon failure, tpnotify() sets tperrno to one of the following values:

[TPEINVAL]

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

[TPENOENT]

The target client does not exist or does not have an unsolicited handler set and the TPACK flag is set.

[TPETIME]

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

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

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

[TPERELEASE]

When the TPACK is set and the target is a client from a prior release of BEA Tuxedo that does not support the acknowledgment protocol.