The REPLY utility uses the BRKTHRU system service to send a message to all (or some) terminals. There used to be a BRDCST (broadcast) service in VMS which was superseded by BRKTHRU. The current VMS documentation doesn't even include the old service, other than a passing mention to it. Since we follow the documentation, we don't include the older service.

The following code has TODO comments in regard to carriage control and flags parameters passed to the service. In both cases, this has to do with how messages are displayed on terminals. This is handled by the display management facility, which (as mentioned in previous articles) which we will cover sometime in the future. For now, message text is just spit out without any formatting considerations. Also, we leave the cluster processing for a future set of articles. Finally of note, there is a reference to the SET BROADCAST utility, which we will address at some point in the future. Now, the documentation for BRKTHRU:

Sends a message to one or more terminals. BRKTHRU is asynchonous, BRKTHRUW is synchronous.

Value

Mnuemonic

Description

BRK_C_ALLTERMS

Message is sent to all terminals. Messages are not sent to terminals with AUTOBAUD that are not logged in. sendto is ignored.

BRK_C_ALLUSERS

Message is sent to all terminals at which a user are logged in.

BRK_C_DEVICE

Message is sent to the terminal specified in sendto.

BRK_C_USERNAME

Message is sent to all terminals at which the user specified by sendto are logged in.

Value

Mnuemonic

Description

0-31

Display 0 to 31 blank lines before the message is shown. Only applies if BRK_M_SCREEN is specified. Note that this is not a bit flag like the other flags, rather the lower 5 bits are treated as an integer indicating the number of lines.

BRK_M_NOREFRESH

Do not redisplay last line or a read operation that was interrupted by the message.

BRK_M_BOTTOM

If BRK_M_SCREEN is also specified, the message is shown at the bottom of the screen.

128

BRK_M_CLUSTER

Enable broadcast on other nodes in a cluster. Otherwise the message is sent only terminals on the current node.

256

BRK_M_SCREEN

Message is sent using display formatting. In the absence of other flags, the message is shown at the top of the display, assuming the display filter supports that operation.

Class Name

Description

BRK_C_GENERAL

Default value.

BRK_C_PHONE

Sent by the PHONE utility.

BRK_C_MAIL

Sent by the MAIL utility.

BRK_C_UCL

Sent for Control-T status.

BRK_C_QUEUE

Sent by the queue manager.

BRK_C_SHUTDOWN

Used by REPLY/ID=SHUTDOWN.

BRK_C_URGENT

Used by REPLY/ID=URGENT.

BRK_C_USER1 through BRK_C_USER16

Reserved for user programs.

function SYS_BRKTHRU( efn, msgbuf, sendto, sndtyp, iosb, carcon, flags, reqid,
    timout, astadr, astprm : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TS2I9_Request ;

begin
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_BRKTHRU ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB1 := PSRB( Msgbuf )^ ;
    SysRequest.SRB2 := PSRB( Sendto )^ ;
    SysRequest.Integer1 := EFN ;
    SysRequest.Integer2 := sndtyp ;
    SysRequest.Integer3 := IOSB ;
    SysRequest.Integer4 := carcon ;
    SysRequest.Integer5 := Flags ;
    SysRequest.Integer6 := ReqID ;
    SysRequest.Integer7 := timout ;
    SysRequest.Integer8 := astadr ;
    SysRequest.Integer9 := astprm ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
    Result := Status ;
end ;


function SYS_BRKTHRUW( efn, msgbuf, sendto, sndtyp, iosb, carcon, flags, reqid,
    timout, astadr, astprm : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TS2I9_Request ;

begin
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_BRKTHRUW ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB1 := PSRB( Msgbuf )^ ;
    SysRequest.SRB2 := PSRB( Sendto )^ ;
    SysRequest.Integer1 := EFN ;
    SysRequest.Integer2 := sndtyp ;
    SysRequest.Integer3 := IOSB ;
    SysRequest.Integer4 := carcon ;
    SysRequest.Integer5 := Flags ;
    SysRequest.Integer6 := ReqID ;
    SysRequest.Integer7 := timout ;
    SysRequest.Integer8 := astadr ;
    SysRequest.Integer9 := astprm ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
    Result := Status ;
end ;

        UOS_FIP_BRKTHRU, UOS_FIP_BRKTHRUW:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC,
                    sizeof( TS2I9_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    S2I9_Request := PS2I9_Request( Address ) ;

                    UE := Broadcast( S2I9_Request.Integer1, S2I9_Request.Integer2,
                        S2I9_Request.Integer3, S2I9_Request.Integer4,
                        S2I9_Request.Integer5, S2I9_Request.Integer6,
                        S2I9_Request.Integer7, S2I9_Request.Integer8,
                        S2I9_Request.Integer9, S2I9_Request.SRB1,
                        S2I9_Request.SRB2, SReq.Request = UOS_FIP_BRKTHRUW ) ;
                    Status := 0 ;
                    if( UE <> nil ) then
                    begin
                        Status := UE.Get_Error ;
                    end ;
                    Write_User_int64( Kernel, PID, S2I9_Request.Request.Status,
                        Status ) ;
                finally
                    Exit_System_Call( integer( S2I9_Request ), PID, MMC,
                        sizeof( TS2I9_Request ) - sizeof( SReq ) ) ;
                end ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
            end ;

function TUOS_FiP.Broadcast( efn, sendtyp, IOSB, carcon, Flags, Reqid, timout, astadr, 
    astprm : int64 ; Msg, Sendto : TSRB ; Wait : boolean ) : TUnified_Exception ;

var Chars, Chars2 : int64 ;
    Context : int64 ;
    Descriptors : array[ 0..7 ] of TDVI_Descriptor ;
    DevLen : int64 ;
    Devname : string ;
    Have_OPER : boolean ;
    I : integer ;
    _IOSB : TIOSB ;
    Mes : string ;
    PID : TPID ;
    Res : integer ;
    RetLen : int64 ;
    Send : string ;
    R, SRB : TSRB ;
    ReqID_Mask : int64 ;
    S : TUOS_String ;
    St : string ;
    Status : integer ;
    Tag : int64 ;
    TermPID : TPID ;
    UIC, UIC_of_Caller : int64 ;
    US : TUOS_String ;
    Caller_Username, Username : string ;

begin
    // Get and validate the parameters...
    Result := nil ;
    PID := Kernel.PID ;
    US := Get_User_String( Kernel, PID, Msg, Status ) ;
    Mes := '' ;
    if( ( US <> nil ) and ( Status = 0 ) ) then
    begin
        Mes := trim( US.Contents ) ;
    end ;
    US.Free ;
    if( Status <> 0 ) then
    begin
        exit ;
    end ;
    if( Mes = '' ) then
    begin
        exit ; // Null message - do nothing
    end ;
    US := Get_User_String( Kernel, PID, Sendto, Status ) ;
    Send := '' ;
    if( ( US <> nil ) and ( Status = 0 ) ) then
    begin
        Send := trim( US.Contents ) ;
    end ;
    US.Free ;
    if( Status <> 0 ) then
    begin
        exit ;
    end ;
    if( ( efn < 0 ) or ( efn > 128 ) ) then
    begin
        Result := Generate_Exception( UOSErr_Illegal_Event_Flag ) ;
        exit ;
    end ;
    if( ( sendtyp < BRK_C_ALLTERMS ) or ( sendtyp > BRK_C_USERNAME ) ) then
    begin
        Result := Generate_Exception( UOSErr_Bad_Parameter ) ;
        exit ;
    end ;
    if( ( Flags < 0 ) or ( Flags > 511 ) ) then
    begin
        Result := Generate_Exception( UOSErr_Bad_Parameter ) ;
        exit ;
    end ;
    if( ( Reqid < BRK_C_GENERAL ) or ( Reqid > BRK_C_USER16 ) ) then
    begin
        Result := Generate_Exception( UOSErr_Bad_Parameter ) ;
        exit ;
    end ;
    if( ( Sendtyp = BRK_C_DEVICE ) or ( Sendtyp = BRK_C_USERNAME ) ) then
    begin
        if( Send = '' ) then // sendto must be specified for these types
        begin
            Result := Generate_Exception( UOSErr_Bad_Parameter ) ;
            exit ;
        end ;
    end ;
    Have_OPER := ( USC.Get_Process_Info( PID, JPI_CURPRIV ) and OPER ) <> 0 ;
    UIC_of_Caller := Kernel.USC.Get_Process_Info( PID, JPI_UIC ) ;
    Caller_Username := lowercase( UIC_Name( UIC_of_Caller ) ) ;
    if( SendTyp = BRK_C_USERNAME ) then
    begin
        if( Caller_Username <> Send ) then
        begin
            if( not Have_OPER ) then
            begin
                Result := Generate_Exception( UOSErr_OPER_Required ) ;
                exit ;
            end ;
        end ;
    end ;
    if( ReqID > 0 ) then
    begin
        ReqID_Mask := 1 shl ( ReqID - 1 ) ;
    end ;
    //TODO: Handle Flags

    // Iterate through terminals...
    setlength( Devname, 256 ) ;
    Set_String( Devname, R ) ;
    fillchar( Descriptors, sizeof( Descriptors ), 0 ) ;
    Descriptors[ 0 ].Item_Code := DVI_DEVCHAR ;
    Descriptors[ 0 ].Buffer_Address := int64( @Chars ) ;
    Descriptors[ 0 ].Buffer_Length := sizeof( Chars ) ;
    Descriptors[ 1 ].Item_Code := DVI_PID ;
    Descriptors[ 1 ].Buffer_Address := int64( @TermPID ) ;
    Descriptors[ 1 ].Buffer_Length := sizeof( TermPID ) ;
    Descriptors[ 2 ].Item_Code := DVI_DEVNAM ;
    Descriptors[ 2 ].Buffer_Address := R.Buffer ;
    Descriptors[ 2 ].Buffer_Length := 256 ;
    Descriptors[ 3 ].Item_Code := DVI_OWNUIC ;
    Descriptors[ 3 ].Buffer_Address := int64( @UIC ) ;
    Descriptors[ 3 ].Buffer_Length := sizeof( UIC ) ;
    Descriptors[ 4 ].Item_Code := DVI_DEVNAMLEN ;
    Descriptors[ 4 ].Buffer_Address := int64( @DevLen ) ;
    Descriptors[ 4 ].Buffer_Length := sizeof( DevLen ) ;
    Descriptors[ 5 ].Item_Code := DVI_TAG ;
    Descriptors[ 5 ].Buffer_Address := int64( @Tag ) ;
    Descriptors[ 5 ].Buffer_Length := sizeof( Tag ) ;
    Descriptors[ 6 ].Item_Code := DVI_DEVDEPEND3 ;
    Descriptors[ 6 ].Buffer_Address := int64( @Chars2 ) ;
    Descriptors[ 6 ].Buffer_Length := sizeof( Chars2 ) ;
    Context := 0 ;
    UIC := 0 ;

    if( Sendtyp = BRK_C_DEVICE ) then // Send to specific terminal
    begin
        Send := lowercase( Send ) ;
        if( ( copy( Send, 1, 4 ) <> 'term' ) and ( copy( Send, 1, 5 ) <> '_term' ) ) then
        begin
            Result := Generate_Exception( UOSErr_Bad_Parameter ) ;
            exit ;
        end ;
        St := send ;
        I := pos( 'term', St ) ;
        St := copy( St, I + 4, length( St ) ) ;
        if( copy( St, length( St ), 1 ) = ':' ) then
        begin
            setlength( St, length( St ) - 1 ) ;
        end ;
        if( ( St = '' ) or ( not trystrtoint( St, I ) ) ) then
        begin
            result := Generate_Exception( UOSErr_Bad_Parameter ) ;
            exit ;
        end ;
        Send_Message( Send ) ;
        if( IOSB <> 0 ) then
        begin
            Status := Write_User( Kernel, PID, IOSB, sizeof( _IOSB ), _IOSB ) ;
            if( Status <> 0 ) then
            begin
                exit ;
            end ;
        end ;
        exit ;
    end ;

    S := Pascal_To_UOS_String( 'term*' ) ;
    RetLen := 0 ;
    while( Kernel.USC.Device_Scan_Context( PID, S, R.Buffer, int64( @RetLen ), 0,
      int64( @Context ), _IOSB ) = 0 ) do
    begin
        Send_Message( copy( UOS_Util.Get_String( R ), 1, RetLen ) ) ;
    end ; // while
    if( IOSB <> 0 ) then
    begin
        Status := Write_User( Kernel, PID, IOSB, sizeof( _IOSB ), _IOSB ) ;
        if( Status <> 0 ) then
        begin
            exit ;
        end ;
    end ;
end ; // TUOS_FiP.Broadcast

    procedure Send_Message( Term : string ) ;

    var F : int64 ;
        Handle : THandle ;
        MB : TMailbox ;
        SRB : TSRB ;
        Status : int64 ;

    begin
        if( Term[ length( Term ) ] <> ':' ) then
        begin
            Term := Term + ':' ;
        end ;
        Set_String( Term, SRB ) ;
        Get_Device_Info( 0, int64( @Descriptors ), High( Descriptors ) - 1, SRB ) ;

        // Check for conditions that prevent broadcast on this device...
        if( ( Chars and TT_M_NOBRDCST ) <> 0 ) then
        begin
            exit ; // Ignore terminals with nobroadcast set
        end ;

        if( not Have_OPER ) then // Check restrictions if no OPER privilege
        begin
            if( UIC <> UIC_Of_Caller ) then
            begin
                exit ; // Different user on this terminal
            end ;
        end ;
        if( TermPID <> 0 ) then // Terminal is logged in or otherwise assigned
        begin
            if( Username <> '' ) then // Filter by username
            begin
                if( lowercase( Username ) <> Caller_Username ) then
                begin
                    exit ; // Different user
                end ;
            end ;
        end else
        if( ( Chars and TT2_M_AUTOBAUD ) <> 0 ) then
        begin
            exit ; // Non-logged-in autobaud terminals are ignored
        end ;
        if( ReqID > 0 ) then
        begin
            if( ( Chars2 and ReqID_Mask ) <> 0 ) then
            begin
                exit ; // This class of message disabled for terminal
            end ;
        end ;

The second set of terminal characteristic flags has a bit for each message class in the low bits, which is why we use the ReqID_Mask value.

        // See if terminal has associated mailbox
        if( Tag <> 0 ) then
        begin
            MB := TMailbox( Tag ) ;
            Term := 'MAILB' + inttostr( Temporary_Mailboxes.Indexof( MB ) ) + ':' ;
        end ;

        // Assign a handle...
        Handle := 0 ;
        Assign_Handle( Term, Handle, 0, '', 0 ) ;
        if( Handle <> 0 ) then // Successfully assigned a handle
        begin
            F := IO_WRITEVBLK or IOM_BREAKTHRU or IOM_CANCTRLO or IOM_CLOSE ;
            if( ( Flags and BRK_M_NOREFRESH ) = 0 ) then
            begin
                F := F or IOM_REFRESH ;
            end ;
            if( timout <> 0 ) then
            begin
                F := F or IOM_TIMED ;
            end ;
            if( Wait ) then
            begin
                QIOW( efn, Handle, F, _IOSB, Astadr, Astprm, Msg.Buffer,
                    Msg.Length, timout, carcon, 0, 0 ) ;
            end else
            begin
                Status := QIO( efn, Handle, F, _IOSB, Astadr, Astprm, Msg.Buffer,
                    Msg.Length, timout, carcon, 0, 0 ) ;
            end ;
            if( Status <> 0 ) then
            begin
                Result := Generate_Exception( Status ) ;
            end ;
        end ;
    end ; // .Send_Message

In either case, we assign a handle to the device, create the flags for our QIO call, and then call either QIO or QIOW, depending upon the Wait parameter. If an error is returned, we exit with an error.

function UIC_Name( UIC : integer ) : string ; var IOSB : TIOSB ; Len : int64 ; SRB : TSRB ; begin setlength( Result, 256 ) ; Len := 0 ; Set_String( Result, SRB ) ; Kernel.USC.Get_UIC_Name( Kernel, PID, SRB, UIC, int64( @Len ), IOSB ) ; setlength( Result, Len ) ; end ;

There were are few other changes needed in various places to support this. The first being the addition of the following line to the TMailbox class to provide a link to the associated terminal (if one):

Terminal : TTerminal ;

We also added a Tag integer variable to the TTerminal class to keep track of the associated mailbox from that side. The next change was to add a set of secondary terminal characteristics to hold the broadcast-by-message-class disable bits. There weren't enough bits left over in the primary characteristics, hence the need for another set. Then we needed a way to obtain them and also the terminal's tag (ie associated mailbox).

                    DVI_DEVDEPEND3 : begin
                                         Res := 0 ;
                                         if( Device.Terminal <> nil ) then
                                         begin
                                             Res := Device.Terminal.Terminal_Flags2 ;
                                         end ;
                                         if( Write_Integer( Res ) = UE_Error ) then
                                         begin
                                             exit ;
                                         end ;
                                     end ;
                    DVI_DEVNAMLEN : begin
                                        Res := system.length( This_Device_Name ) ;
                                        if( Write_Integer( Res ) = UE_Error ) then
                                        begin
                                            exit ;
                                        end ;
                                    end ;
                    DVI_TAG : begin
                                  Res := 0 ;
                                  if( Device.Terminal <> nil ) then
                                  begin
                                      Res := Device.Terminal.Tag ;
                                  end ;
                                  if( Write_Integer( Res ) = UE_Error ) then
                                  begin
                                      exit ;
                                  end ;
                              end ;

end else if( ( Func and IO_Function_Mask ) = IO_WRITEVBLK ) then begin if( ( Mode and IOM_TIMED ) <> 0 ) then begin Timeout := p3 ; end ; Request := Create_Request( Handle, 1, p1, p2 ) ; Pending_IOs.Add( Request ) ; Result := int64( Request ) ; end ;