ATMI COBOL Function Reference
TPBROADCAST()
- broadcast notification by name
01
TPBCTDEF-REC
.
COPY TPBCTDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPBROADCAST" USINGTPBCTDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
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
, all in TPBCTDEF-REC
, are logical identifiers used to select the target client set. A SPACES
value for any logical identifiers constitutes a wildcard for that argument. A wildcard argument matches all client identifiers for that field. Each identifier must meet the size restrictions defined for the system to be considered valid, that is, each identifier must be between 0 and 30 characters in length.
The data portion of the request is identified by DATA-REC
and LEN
in TPTYPE-REC
specifies how much of DATA-REC
to send. Note that if DATA-REC
is a record of a type that does not require a length to be specified, then LEN
is ignored (and may be 0
). If REC-TYPE
in TPTYPE-REC
is SPACES
, in which case DATA-REC
and LEN
are ignored and a request is sent with no data portion.
The following is a list of valid settings in TPBCTDEF-REC
.
The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Either TPNOBLOCK
or TPBLOCK
must be set.
If a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK
or TPBLOCK
must be set.
This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME
or TPTIME
must be set.
This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME
or TPTIME
must be set.
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. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
Upon successful completion, TPBROADCAST()
sets TP-STATUS
to [TPOK
].
Under the following conditions, TPBROADCAST()
sends no broadcast messages to application clients and sets TP-STATUS
to:
Invalid arguments were given. 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 can occur only if both TPBLOCK
and TPTIME
are specified.)
The interfaces described in TPNOTIFY()
are supported on native site UNIX-based processors. In addition, the routines TPBROADCAST()
and TPCHKUNSOL()
as well as the routine 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 UBBCONFIG(5) description of the RESOURCES
NOTIFY
parameter 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 in the configuration file 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 TPINITIALIZE(3cbl)
for more information on notification method selection.
TPINITIALIZE(3cbl)
, TPNOTIFY(3cbl)
, TPTERM(3cbl)
, UBBCONFIG(5)