Sends a message to one or more terminals. The $BRKTHRU service
completes asynchronously; that is, it returns to the caller after
queuing the message request, without waiting for the message to
be written to the specified terminals.
For synchronous completion, use the Breakthrough and Wait
($BRKTHRUW) service. The $BRKTHRUW service is identical to the
$BRKTHRU service in every way except that $BRKTHRUW returns
to the caller after the message is written to the specified
terminals.
The $BRKTHRU service supersedes the Broadcast ($BRDCST) service.
When writing new programs, you should use $BRKTHRU instead of
$BRDCST. When updating old programs, you should change all uses
of $BRDCST to $BRKTHRU.
Format
SYS$BRKTHRU [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]
[,carcon] [,flags] [,reqid] [,timout] [,astadr]
[,astprm]
C Prototype
int sys$brkthru (unsigned int efn, void *msgbuf, void *sendto,
unsigned int sndtyp, struct _iosb *iosb,
unsigned int carcon, unsigned int flags,
unsigned int reqid, unsigned int timout, void
(*astadr)(__unknown_params), int astprm);
1 – Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when the message has been
written to the specified terminals. The efn argument is a
longword containing this number; however, $BRKTHRU uses only
the low-order byte.
When the message request is queued, $BRKTHRU clears the specified
event flag (or event flag 0 if efn is not specified). Then, after
the message is sent, $BRKTHRU sets the specified event flag (or
event flag 0).
msgbuf
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Message text to be sent to the specified terminals. The msgbuf
argument is the address of a descriptor pointing to this message
text.
The $BRKTHRU service allows the message text to be as long as
16,350 bytes; however, both the system parameter MAXBUF and the
caller's available process space can affect the maximum length of
the message text.
sendto
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of a single device (terminal) or single user name to which
the message is to be sent. The sendto argument is the address of
a descriptor pointing to this name.
The sendto argument is used in conjunction with the sndtyp
argument. When sndtyp specifies BRK$C_DEVICE or BRK$C_USERNAME,
the sendto argument is required.
If you do not specify sndtyp or if sndtyp does not specify BRK$C_
DEVICE or BRK$C_USERNAME, you should not specify sendto; if
sendto is specified, $BRKTHRU ignores it.
sndtyp
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Terminal type to which $BRKTHRU is to send the message. The
sndtyp argument is a longword value specifying the terminal type.
Each terminal type has a symbolic name, which is defined by the
$BRKDEF macro. The following table describes each terminal type:
Terminal Type Description
BRK$C_ When specified, $BRKTHRU sends the message to all
ALLTERMS terminals at which users are logged in and to all
other terminals that are connected to the system
except those with the AUTOBAUD characteristic
set.
BRK$C_ When specified, $BRKTHRU sends the message to all
ALLUSERS users who are currently logged in to the system.
BRK$C_DEVICE When specified, $BRKTHRU sends the message to a
single terminal; you must specify the name of the
terminal by using the sendto argument.
BRK$C_ When specified, $BRKTHRU sends the message to a
USERNAME user with a specified user name; you must specify
the user name by using the sendto argument.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb argument is the address of this quadword block.
When the iosb argument is specified, $BRKTHRU sets the quadword
to 0 when it queues the message request. Then, after the message
is sent to the specified terminals, $BRKTHRU returns four
informational items, one item per word, in the quadword I/O
status block.
These informational items indicate the status of the messages
sent only to terminals and mailboxes on the local node; these
items do not include the status of messages sent to terminals and
mailboxes on other nodes in an OpenVMS Cluster system.
The following table shows each word of the quadword block and the
informational item it contains:
Word Informational Item
1 A condition value describing the final completion status.
2 A decimal number indicating the number of terminals and
mailboxes to which $BRKTHRU successfully sent the message.
3 A decimal number indicating the number of terminals to which
$BRKTHRU failed to send the message because the write to the
terminals timed out.
4 A decimal number indicating the number of terminals to which
$BRKTHRU failed to send the message because the terminals
were set to the NOBROADCAST characteristic (by using the DCL
command SET TERMINAL/NOBROADCAST).
carcon
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Carriage control specifier indicating the carriage control
sequence to follow the message that $BRKTHRU sends to the
terminals. The carcon argument is a longword containing the
carriage control specifier.
For a list of the carriage control specifiers that you can use
in the carcon argument, see the VSI OpenVMS I/O User's Reference
Manual.
If you do not specify the carcon argument, $BRKTHRU uses a
default value of 32, which represents a space in the ASCII
character set. The message format resulting from this default
value is a line feed, the message text, and a carriage return.
The carcon argument has no effect on message formatting
specified by the BRK$M_SCREEN flag in the flags argument. See
the description of the flags argument.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag bit mask specifying options for the $BRKTHRU operation. The
flags argument is a longword value that is the logical OR of each
desired flag option.
Each flag option has a symbolic name. The $BRKDEF macro defines
the following symbolic names:
Symbolic Name Description
BRK$V_ERASE_ When specified with the BRK$M_SCREEN flag,
LINES BRK$V_ERASE_LINES causes a specified number of
lines to be cleared from the screen before the
message is displayed. When BRK$M_SCREEN is not
also specified, BRK$V_ERASE_LINES is ignored.
Unlike the other Boolean flags, BRK$V_ERASE_
LINES specifies a 1-byte integer in the range
0 to 24. It occupies the first byte in the
longword flag mask. In coding the call to
$BRKTHRU, specify the desired integer value in
the OR operation with any other desired flags.
BRK$M_SCREEN When specified, $BRKTHRU sends screen-formatted
messages as well as messages formatted through
the use of the carcon argument. $BRKTHRU sends
screen-formatted messages to terminals with
the DEC_CRT characteristic, and it sends
messages formatted by carcon to those without
the DEC_CRT characteristic. You set the DEC_CRT
characteristic for the terminal by using the DCL
command SET TERMINAL/DEC_CRT.
A screen-formatted message is displayed at the
top of the terminal screen, and the cursor is
repositioned at the point it was prior to the
broadcast message. However, the BRK$V_ERASE_
LINES and BRK$M_BOTTOM flags also affect the
display.
BRK$M_BOTTOM When BRK$M_BOTTOM is specified and BRK$M_SCREEN
is also specified, $BRKTHRU writes the message
to the bottom of the terminal screen instead of
the top. BRK$M_BOTTOM is ignored if the BRK$M_
SCREEN flag is not set.
BRK$M_ When BRK$M_NOREFRESH is specified, $BRKTHRU,
NOREFRESH after writing the message to the screen, does
not redisplay the last line of a read operation
that was interrupted by the broadcast message.
This flag is useful only when the BRK$M_SCREEN
flag is not specified, because BRK$M_NOREFRESH
is the default for screen-formatted messages.
BRK$M_CLUSTER Specifying BRK$M_CLUSTER enables $BRKTHRU to
send the message to terminals or mailboxes on
other nodes in an OpenVMS Cluster system. If
BRK$M_CLUSTER is not specified, $BRKTHRU sends
messages only to terminals or mailboxes on the
local node.
reqid
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Class requester identification, which identifies to $BRKTHRU
the application (or image) that is calling $BRKTHRU. The reqid
argument is this longword identification value.
The reqid argument is used by several images that send messages
to terminals and can be used by as many as 16 different user
images as well.
When such an image calls $BRKTHRU, specifying reqid, $BRKTHRU
notifies the terminal that this image wants to write to the
terminal. This makes it possible for you to allow the image to
write or prevent it from writing to the terminal.
To prevent a particular image from writing to your
terminal, you use the image's name in the DCL command SET
TERMINAL/NOBROADCAST=image-name. Note that image-name in this
DCL command is the same as the value of the reqid argument that
the image passed to $BRKTHRU.
For example, you can prevent the Mail utility (which is an image)
from writing to the terminal by entering the DCL command SET
BROADCAST=NOMAIL.
The $BRKDEF macro defines class names that are used by several
OpenVMS components. These components specify their class names by
using the reqid argument in calls to $BRKTHRU. The $BRKDEF macro
also defines 16 class names (BRK$C_USER1 through BRK$C_USER16)
for the use of user images that call $BRKTHRU. The class names
and the components to which they correspond are as follows:
Class Name Component
BRK$C_GENERAL This class name is used by the image invoked
by the DCL command REPLY and the callers of the
$BRKTHRU service. This is the default if the
reqid argument is not specified.
BRK$C_PHONE This class name is used by the OpenVMS Phone
utility.
BRK$C_MAIL This class name is used by the OpenVMS Mail
utility.
BRK$C_DCL This class name is used by the DIGITAL Command
Language (DCL) interpreter for the Ctrl/T
command, which displays the process status.
BRK$C_QUEUE This class name is used by the queue manager,
which manages print and batch jobs.
BRK$C_SHUTDOWN This class name is used by the system shutdown
image, which is invoked by the DCL command
REPLY/ID=SHUTDOWN.
BRK$C_URGENT This class name is used by the image invoked by
the DCL command REPLY/ID=URGENT.
BRK$C_USER1 These class names can be used by user-written
through BRK$C_ images.
USER16
timout
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Timeout value, which is the number of seconds that must elapse
before an attempted write by $BRKTHRU to a terminal is considered
to have failed. The timout argument is this longword value (in
seconds).
Because $BRKTHRU calls the $QIO service to perform write
operations to the terminal, the timeout value specifies the
number of seconds allotted to $QIO to perform a single write
operation to the terminal.
If you do not specify the timout argument, $BRKTHRU uses a
default value of 0 seconds, which specifies infinite time (no
timeout occurs).
The value specified by timout can be 0 or any number greater than
4; the numbers 1, 2, 3, and 4 are illegal.
When you press Ctrl/S or the No Scroll key, $BRKTHRU cannot send
a message to the terminal. In such a case, the value of timout is
usually exceeded and the attempted write to the terminal fails.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed after $BRKTHRU has sent the
message to the specified terminals. The astadr argument is the
address of this routine.
If you specify astadr, the AST routine executes at the same
access mode as the caller of $BRKTHRU.
astprm
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST routine specified by the
astadr argument. The astprm argument specifies this longword
parameter.