ATMI C Function Reference
tpbroadcast()
—Routine to broadcast notification by name.
#include <atmi.h>
int tpbroadcast(char *lmid, char *usrname, char *cltname,
char *data, long len, long flags)
tpbroadcast()
allows a client or server to send unsolicited messages to registered clients within the system. The target client set consists of those clients matching identifiers passed to tpbroadcast()
. Wildcards can be used in specifying identifiers.
lmid
, usrname
, and cltname
are logical identifiers used to select the target client set. A NULL value for any argument constitutes a wildcard for that argument. A wildcard argument matches all client identifiers for that field. A 0-length string for any argument matches only 0-length client identifiers. Each identifier must meet the size restrictions defined for the system to be considered valid, that is, each identifier must be between 0 and MAXTIDENT
characters in length.
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. The buffer passes through the typed buffer switch routines just as any other outgoing or incoming message would; for example, encode/decode are performed automatically.
The following is a list of valid flags
:
The request is not sent if a blocking condition exists (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.
If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Upon successful return from tpbroadcast()
, the message has been delivered to the system for forwarding to the selected clients. tpbroadcast()
does not wait for the message to be delivered to each selected client.
In a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpbroadcast()
.
Upon failure, tpbroadcast()
returns -1 and sets tperrno
to indicate the error condition.
Upon failure, tpbroadcast()
sends no broadcast messages to application clients and sets tperrno
to one of the following values:
Invalid arguments were given (for example, identifiers too long or invalid flags). Note that use of an illegal LMID
will cause tpbroadcast()
to fail and return TPEINVAL
. However, non-existent user or client names will simply successfully broadcast to no one.
A blocking timeout occurred. (A blocking timeout cannot occur if TPNOBLOCK
and/or TPNOTIME
is specified.)
The interfaces described in tpnotify(3c)
are supported on native site UNIX-based processors. In addition, the routines tpbroadcast()
and tpchkunsol()
as well as the function tpsetunsol()
are supported on UNIX and MS-DOS workstation processors.
Clients that select signal-based notification may not be signal-able by the system due to signal restrictions. When this occurs, the system generates a log message that it is switching notification for the selected client to dip-in and the client is notified then and thereafter via dip-in notification. (See the description of the RESOURCES
NOTIFY
parameter in UBBCONFIG()
for a detailed discussion of notification methods.)
Because signaling of clients is always done by the system, the behavior of notification is always consistent, regardless of where the originating notification call is made. Therefore to use signal-based notification:
The ID for the application administrator is identified as part of the configuration for the application.
If signal-based notification is selected for a client, then certain ATMI calls can fail, returning TPGOTSIG
due to receipt of an unsolicited message if TPSIGRSTRT
is not specified. See UBBCONFIG(5) and tpinit(3c)
for more information on notification method selection.
tpalloc(3c)
, tpinit(3c)
, tpnotify(3c)
, tpterm(3c)
, UBBCONFIG(5)