REPLY utility

We covered the documentation for REPLY in the previous article. In this article we will look at the source code. As you will see, REPLY is mostly a fairly thin wrapper around the SYS_BRKTHRU service.

const UI =  'object Main:rectangle' + CR +
            '  top = 2' + CR +
            '  object label:label' + CR +
            '    text = "Text:"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object text:string' + CR +
            '    hint = "Message text"' + CR +
            '    top = $margin' + CR +
            '    left = label.width + $margin' + CR +
            '  end' + CR +
            '  object Options:rectangle' + CR +
            '    object all:boolean' + CR +
            '      text = "All terminals"' + CR +
            '      truehint = "Click to send message to all terminals"' + CR +
            '      falsehint = "Click to restrict which terminals receive the message"' + CR +
            '    end' + CR +
            '    object bell:boolean' + CR +
            '      text = "Sound bell on terminals receiving message"' + CR +
            '    end' + CR +
            '    object enable:list' + CR +
            '      hint = "Backspace handling"' + CR +
            '      list = "", "Cards", "Central", "Cluster", "Devices",  +
            '        "Disks", "License", "Network", "Oper1", "Oper2", "Oper3", ' +
            '        "Oper4", "Oper5", "Oper6", "Oper7", "Oper8", "Oper9", ' +
            '        "Oper10", "Oper11", "Oper12", "Printer", "Security", "Tapes"' + CR +
            '      text = ""' + CR +
            '      type = constrained' + CR +
            '      multiselect = true' + CR +
            '    end' + CR +
            '    object disable:list' + CR +
            '      hint = "Backspace handling"' + CR +
            '      list = "", "Cards", "Central", "Cluster", "Devices",' +
            '        "Disks", "License", "Network", "Oper1", "Oper2", "Oper3",' +
            '        "Oper4", "Oper5", "Oper6", "Oper7", "Oper8", "Oper9",' +
            '        "Oper10", "Oper11", "Oper12", "Printer", "Security", "Tapes"' + CR +
            '      text = ""' + CR +
            '      type = constrained' + CR +
            '      multiselect = true' + CR +
            '    end' + CR +
            '    object log:command' + CR +
            '      text = "Open log file"' + CR +
            '      hint = "Click to open a new log file"' + CR +
            '    end' + CR +
            '    object nolog:command' + CR +
            '      text = "Close log file"' + CR +
            '      hint = "Click to close the current log file"' + CR +
            '    end' + CR +
            '    object shutdown:boolean' + CR +
            '      text = "Send shutdown message"' + CR +
            '      truehint = "Click to send a shutdown message"' + CR +
            '      falsehint = "Click to not send a shutdown message" ' + CR +
            '    end' + CR +
            '    object terminallabel:label' + CR +
            '      text = "Terminal for message:"' + CR +
            '    end' + CR +
            '    object terminal:string' + CR +
            '      text = ""' + CR +
            '      hint = "Enter terminal to send message to"' + CR +
            '      left = terminallabel.left + $margin' + CR +
            '    end' + CR +
            '    object userlabel:label' + CR +
            '      text = "Username for message:"' + CR +
            '    end' + CR +
            '    object username:string' + CR +
            '      text = ""' + CR +
            '      hint = "Enter terminal to send message to"' + CR +
            '      left = userlabel.left + $margin' + CR +
            '    end' + CR +
            '    object urgent:boolean' + CR +
            '      text = "URgent"' + CR +
            '      truehint = "Click to ring two bells at receiving terminals"' + CR +
            '      falsehint = "Click to not send two bells to receiving termainals"' + CR +
            '    end' + CR +
            'end' ;

The UI definition for REPLY is similar to the ones we've looked at previously. There is one thing of note though. The nolog and log components use the "command" type. This is a new morphable UI component type. For a command-line interface, it operates as if it were of type boolean. For a GUI, it operates as if it were of type operation. This is needed solely to support the VMS specification. REPLY/LOG and REPLY/NOLOG do specific operations rather than altering the behavior of another operation. Therefore, they ought to be implemented as commands. For instance:
REPLY NOLOG

Of course, that would require the message operation to look something like:
REPLY MESSAGE messagetext

However, since that isn't the way VMS did it, and we are largely following the documentation as our specification, we need to support doing the operation as a switch on the command line. However, in a GUI environment (not defined in VMS), we'd want these options to be buttons that perform the action when pressed, rather than checkboxes (or worse, both as checkboxes and buttons).

function Run : int64 ;

var C : string ;
    E : int64 ;
    OS : POS_UOS ;

begin
    OS := new( POS_UOS, Init ) ;
    C := Get_Symbol( 'reply$defaults' ) ;
    E := REPLY_SET( PChar( OS^.Command_Line ), PChar( C ), True ) ;
    if( E <> 0 ) then
    begin
        OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, E ) ) ;
    end ;
    OS.Free ;
    SYS_EXIT( 0 ) ;
end ;

The main entry point for the REPLY program is nearly identical to all other CUSPs we've covered.

function REPLY_SET( Command, Defaults : PChar ; Standalone : boolean ) : int64 ;

var All, Bell, Log, Nolog, Shutdown, Urgent : boolean ;
    Have_Enabled, Have_Disabled : boolean ;
    Message_Text : string ;
    IOSB : TIOSB ;
    S, Term : string ;
    Enabled, Disabled, Terminal, Username : string ;
    Msg : TSRB ;
    Priv : int64 ;
    SRB : TSRB ;
    sndtyp : integer ;
    UUI : TUUI ;

begin
    // Setup...
    Result := 0 ;
    UUI := TUUI.Create ;
    UUI.Definition := UI ;
    S := Get_JPI( JPI_CURPRIV ) ;
    Priv := 0 ;
    move( PChar( S )[ 0 ], Priv, length( S ) ) ;
    if( ( Priv and OPER ) = 0 ) then
    begin
        Result := REPLY_NOOPER ;
        exit ;
    end ;

The main routine for REPLY starts by setting up and then checking to see if the user has the OPER privilege. If the user doesn't have the privilege, the program ends with an error.

    // Processing...
    if( UUI.Execute( '', Standalone ) ) then
    begin
        All := UUI.Get_Component_By_Name( 'all' ).Selected ;
        Message_Text := UUI.Get_Component_By_Name( 'text' ).Text ;
        Bell := UUI.Get_Component_By_Name( 'bell' ).Selected ;
        Shutdown := UUI.Get_Component_By_Name( 'shutdown' ).Selected ;
        Terminal := UUI.Get_Component_By_Name( 'terminal' ).Text ;
        Username := UUI.Get_Component_By_Name( 'username' ).Text ;
        Log := UUI.Get_Component_By_Name( 'log' ).Selected ;
        Nolog := UUI.Get_Component_By_Name( 'nolog' ).Selected ;
        Urgent := UUI.Get_Component_By_Name( 'urgent' ).Selected ;
        Enabled := UUI.Get_Component_By_Name( 'enable' ).Text ;
        Disabled := UUI.Get_Component_By_Name( 'disable' ).Text ;
        Have_Enabled := UUI.Get_Component_By_Name( 'enable' ).UUI ;
        Have_Disabled := UUI.Get_Component_By_Name( 'disable' ).UUI ;

        // Process the specified options...
        if( ( Terminal <> '' ) and ( Username <> '' ) ) then
        begin
            Result := CUSP_CONFLICT ;
            exit ;
        end ;
        if(
            (
              All or Bell or Shutdown or Urgent or
              ( Terminal <> '' ) or ( Username <> '' ) or ( Enabled <> '' ) or
              ( Disabled <> '' )
            )
            and
            ( Message_Text = '' )
          ) then // Conflicting switches
        begin
            Result := REPLY_ABSENT ;
            exit ;
        end ;

        if( NoLog ) then
        begin
            Send_Message( 'Nolog' ) ;
        end ;
        if( Log ) then
        begin
            Send_Message( 'Log' ) ;
        end ;

Next we execute the UI and get the various values. If both a terminal and a username was specified, we exit with an error - only one or neither can be specified. Then if any of the terminal message switches were specified but no message text was specified, we also exit with an error.

Finally, we send a message to OPCOM if /LOG or /NOLOG was used. We will cover the Send_Message routine in a moment.

        Term := GET_JPI( JPI_TERMINAL ) ;

        Enabled := lowercase( Enabled ) ;
        Disabled := lowercase( Disabled ) ;
        Username := lowercase( Username ) ;

        if( pos( 'security', Enabled ) + pos( 'security', Disabled ) > 0 ) then
        begin
            if( ( Priv and SECURITY ) = 0 ) then
            begin
                Result := REPLY_NOSECURITY ;
                exit ;
            end ;
        end ;

        if( Have_Enabled ) then
        begin
            Send_Message( 'Enabled=' + Term + ':' + Enabled ) ;
        end ;

        if( Have_Disabled ) then
        begin
            Send_Message( 'Disabled=' + Term + ':' + Disabled ) ;
        end ;

Now we process the ENABLE and DISABLE options. First, we get the current terminal - which is the one to which the ENABLE and/or DISABLE apply. If either option refers to "security", we verify that the user has the SECURITY privilege and, if not, exit with an error. Finally, we send a message to OPCOM for any enabled and any disabled items. Note that if the same item is in both enabled and disabled, it will be disabled since we process the disabled items after the enabled. The messages to OPCOM have specific format, which we will discuss when we cover OPCOM in the future.

        if(
            All or Bell or Shutdown or Urgent or
            ( Terminal <> '' ) or ( Username <> '' )
          ) then
        begin
            if( Terminal <> '' ) then
            begin
                Set_String( Terminal, SRB ) ;
            end else
            if( Username <> '' ) then
            begin
                Set_String( Username, SRB ) ;
            end else
            begin
                fillchar( SRB, sizeof( SRB ), 0 ) ;
            end ;
            Set_String( Message_Text, Msg ) ;
            if( All ) then
            begin
                sndtyp := BRK_C_ALLTERMS ;
            end else
            if( Terminal <> '' ) then
            begin
                sndtyp := BRK_C_DEVICE ;
            end else
            begin
                sndtyp := BRK_C_USERNAME ;
            end ;
            Result := SYS_BRKTHRU( 0, int64( @Msg ), int64( @SRB ), sndtyp,
                int64( @IOSB ), 0, 0, BRK_C_GENERAL, 5, 0, 0 ) ;
        end ;
    end ; // if( UUI.Execute )
end ; // REPLY_SET

If any of the options related to sending a message are used, we then build the various parameters and pass them in the call to SYS_BRKTHRU. We will cover that service in a couple articles.

var Inited : boolean = False ;
    OPCOM : string = '' ;

procedure Send_Message( const S : string ) ;

var F : TCOM_UOS_File ;
    SRB : TSRB ;

begin
    if( not Inited ) then
    begin
        Inited := True ;
        OPCOM := Get_Symbol_Value( 'LNM$PERMANENT_MAILBOX', '_OPCOM$MAILBOX' ) ;
        if( OPCOM <> '' ) then
        begin
            Set_String( OPCOM, SRB ) ;
            F := Open_File( int64( @SRB ), FAB_V_PUT ) ;
            if( F = nil ) then
            begin
                OPCOM := '' ; // Could not open OPCOM mailbox
            end else
            begin
                F.Free ;
            end ;
        end ;
    end ;

This function is used to send a message to OPCOM. On the first call to this routine, Inited is false, so we enter the initialization code which sets Inited and obtains the value of the OPCOM$MAILBOX global symbol. If set, we set OPCOM to that value. If defined, this should be the mailbox that OPCOM created. To verify this, we attempt to open the mailbox. If that fails we clear OPCOM. This is because either the mailbox has been deleted, the symbol has incorrectly been set up, or some other issue exists. The purpose of this is to prevent us, once mailbox access has failed for any reason, from going through the initialization process over and over during this run of REPLY.

    if( OPCOM <> '' ) then
    begin
        Set_String( OPCOM, SRB ) ;
        F := Open_File( int64( @SRB ), FAB_V_PUT ) ;
        if( F <> nil ) then
        begin
            F.Writeln( PChar( S ) ) ;
            F.Free ;
        end ;
    end ;
end ; // Send_Message

When we get to this part of the code, if OPCOM is valid, we open the OPCOM mailbox and write the text to it. We will cover the valid commands for OPCOM when we cover OPCOM in a few articles from now.

In the next article, we will look at the implementation of mailboxes.