VMS Help  —  System Services, $BRKTHRU
    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 HP 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.
Close Help