SET NODE utility

In the previous article, we looked at the system configuration script. If the user specifies a node name, we use the SET NODE command to set the node name as specified. Before we go on though, I need to point out that this is not the mechanism used by VMS to set the node name. Instead, it puts the node name value in the MODPARAMS.DAT file, which is read on system startup by VMS. We will be doing things differently in UOS. We want to avoid having to reboot the system it at all possible. There is no good reason to have to reboot UOS in order to set, or change, the node name. Thus, we will create a new system call that will do this, and a utility (SET NODE) to make the system call.

Before we dive into the utility in question, we have to talk a little about the way that VMS maps DCL commands onto CUSPs. VMS uses a Command Definition utility to define what commands are allowed, what options (switches) they support, and what programs they run. As we've discussed in the past, we allow a program to automatically serve as a command if its name is typed into the shell. Thus, users don't have to create command definitions in UOS. The downside is that a command that has multiple words separated by spaces (such as "SET NODE") only works if the user includes quotes around the name - otherwise, the command is assumed to be "SET" followed by a parameter "NODE". For compatibility with VMS, we don't want to enforce that kind of non-intuitive restriction, although the user can use quotes if he wishes. So, we will implement this (and some future utilities) by creating a SET.exe CUSP in the system library. This program will then automatically redirect the user to the appropriate CUSP. So we will discuss that program first.

Of course, there are always many approaches to any problem and I've considered several options that I rejected in favor of the SET program that redirects to other programs. It would be tedious to go through all the possible options, but I think that examining one of the most obvious ones might be instructional. In this alternative approach, the SET program would handle all of the SET operations in a single program. Anything from SET NODE to SET TERMINAL could be handled by this program. However, this has several drawbacks. First, it would make the program huge. This would result in unnecessary use of system resources (such as memory) even for simple SET operations, and would be slower to load/run. Second, it would make the program more complex. I like the unix approach of making programs do only one thing, but have them do it well. A lack of focus in any program causes several problems, among which is the introduction of bugs. It can also be a security risk since many of the SET operations require one or more privileges. When dealing with elevated privileges, an increase in code complexity is just asking for trouble. Finally, it makes the SET command less flexible. With the approach we are taking, a system administrator could add additional SET commands, by placing new programs in sys$system. There is no such easy customization if we put everything into a single program.

function Run : int64 ;

var P : integer ;
    SRB, SRB1 : TSRB ;
    OS : POS_UOS ;
    Command, _Program, S, Switches : string ;

begin
    // Setup...
    OS := new( POS_UOS, Init ) ;
    Result := 0 ;
    Command := OS^.Command_Line ;

    // Get switches, if any...
    P := Parse_Position( '/', Command ) ;
    if( P = 0 ) then
    begin
        P := length( Command ) + 1 ;
    end ;
    Switches := copy( Command, P, length( Command ) ) ;
    Command := copy( Command, 1, P - 1 ) ;

As per the other CUSPs we've looked at, the SET program has a Run procedure which starts by initializing data and get the command line. Next, we extract the switches, if any, and save them for later.

    // Get parameter indicating which SET command...
    S := trim( Parse_Parameter( ' ', Command ) ) ;
    while( S = '' ) do
    begin
        S := trim( Get_Command_With_Timeout( '_What: ' ) ) ;
        P := Parse_Position( '/', S ) ;
        if( P = 0 ) then
        begin
            P := length( S ) + 1 ;
        end ;
        Switches := Switches + copy( Command, P, length( Command ) ) ;
        S := trim( copy( S, 1, P - 1 ) ) ;
    end ;

Next we parse the first word of the command line, preserving the rest of the line to pass on to the appropriate CUSP. If there was no word, we go into a loop to query the user for what they want to set. We allow the user to specify switches, which we add to the switches we extracted above, even if they only supply switches (in which case we keep looping and prompting until the user enters something - or cancels out).

    _Program := '' ;
    if( Directory_Exists( 'sys$system:set ' + S + '.exe' ) ) then
    begin
        _Program := 'sys$system:set ' + Left( S, 4 ) + '.exe' ;
    end else
    if( Directory_Exists( 'sys$system:set' + S + '.exe' ) ) then
    begin
        _Program := 'sys$system:set' + Left( S, 4 ) + '.exe'
    end else
    begin
        OS^.OutputLn( RH_SysError, '%SET-W-IVKEYW, unrecognized command - check validity and spelling' ) ;
        OS.Free ;
        SYS_EXIT( 0 ) ;
        exit ;
    end ;

Next we look for the program to pass control to. It must be an .exe file located in the sys$system folder. First we check for a program starting with "SET" and a space, then up to four characters of the first word of the command line following "SET". If that file isn't found, we check for a file with a name without the space. Thus, if the user types "SET NODE", we check first for "sys$system:set node.exe" and then for "sys$system:setnode.exe". If neither is found, we display an error and exit.

    if( Command <> '' ) then
    begin
        Command := ' ' + Command ;
    end ;
    Command := Command + Switches ;
    Set_String( _Program, SRB ) ;
    Set_String( Command, SRB1 ) ;
    OS.Free ;
    LIB_RUN( int64( @SRB ), int64( @SRB1 ), 0 ) ;

    SYS_EXIT( 0 ) ;
end ; // Run

Once we've found a matching program, we set up for a call to LIB_RUN and then run the program.

There is a standard way we are going to handle CUSPs in UOS. We've discussed a few ways in which this is done, such as the Run routine. However, there is much more related to the user-interface. LOGIN, LOGOUT, SET, SHOW, and a few other CUSPs handle the user-interface in a different way, which is why we haven't had to address the UI prior to this. We will describe a UI specification that the CUSPs will use, as we cover the various programs. The UI specification will be used for both command-line and GUI applications.

We will discuss the GUI interface in the future. For now, we will concentrate on the standards that we will use for the command-line interface. In most cases, when a CUSP is run in command-line mode, we will display an identifying line of information. This line will have the following layout:

<name> <version> at <date/time>

where the name is the program name, version is the program version, and date/time is the current date and time. The version for all UOS CUSPs is the UOS version number, plus edit and build number. For instance:

V1.1B-7

This indicates UOS version 1.1B, the 8th build (version) of the CUSP. The initial build of the CUSP includes no build number. Thus, a complete ID line would look something like this:

SETTERM V1.1C at 11:00:00 am on 23-Mar-2022

There are four circumstances under which the ID line isn't shown in command-line mode: 1) if the entire command is entered on a single line (meaning the program won't be prompting the user), 2) if there is no option to provide or only a single piece of information needed with no switches or other options (such as SET NODE, which only needs a node name), 3) if the program uses smart terminal commands to write on the screen (such as VT100 escape sequences), and 4) if an indirect command file is specified (which is a variant of circumstance 1). Thus, SET NODE won't display the ID line as per circumstance 2.

Here is the user documentation for SET NODE.

SET NODE

Sets the computer's node name.

Format

SET NODE name

Parameters

name
The name to use as the node name for the computer. The node name must begin with an alphabetic character and can contain alpha, numeric, dollar sign ($), and underscore (_) characters. The name should be unique on your network/cluster.

Description

The SET NODE utility sets the current node name of the computer. This happens immediately and might terminate existing network connections. You should be aware of requirements and restrictions of network identifiers used on your network.

Examples

$ SET NODE KAPPA

$ SET NODE WSU$ADMIN1

Privileges required

PHY_IO

function Run : int64 ;

var P : integer ;
    SRB : TSRB ;
    OS : POS_UOS ;
    Command : string ;
    UUI : TUUI ;

begin
    // Setup...
    OS := new( POS_UOS, Init ) ;
    Result := 0 ;
    UUI := TUUI.Create ;
    UUI.Definition := UI ;
    if( UUI.Execute ) then
    begin
        // Set the node name...
        Command := lowercase( UUI.Get_Component_By_Name( 'name' ).Text ) ;
        // Validate name...
        if( pos( Command[ 1 ], 'abcdefghijklmnopqrstuvwxyz' ) = 0 ) then
        begin
            OS^.OutputLn( RH_SysError, '%SETNODE-W-ILNAME, illegal name' ) ;
            OS.Free ;
            SYS_EXIT( 0 ) ;
            exit ;
        end ;
        for P := 2 to length( Command ) do
        begin
            if( pos( Command[ P ], 'abcdefghijklmnopqrstuvwxyz1234567890$_' ) = 0 ) then
            begin
                OS^.OutputLn( RH_SysError, '%SETNODE-W-ILNAME, illegal name' ) ;
                OS.Free ;
                SYS_EXIT( 0 ) ;
                exit ;
            end ;
        end ;

        Set_String( Command, SRB ) ;
        OS.Free ;
        SYS_SET_NODE_NAME( int64( @SRB ) ) ;
    end ;

    SYS_EXIT( 0 ) ;
end ; // Run

This is the main routine for the SETNODE CUSP. It uses the Universal UI (UUI) feature to handle getting the command from the command line or from the user. This involves constructing a TUUI instance, defining the UI, "executing" the UI, and then processing the result. The node name is validated to make sure it is legal. If so, we call the SYS_SET_NODE_NAME service. Note that if UUI.Execute returns false, then the user either aborted the program or there was a command line processing error, in which case we simply exit without doing anything. Note: The Set_String function is just the same as used in LOGIN.

const UI =  'object Main:rectangle' + CR +
            '  object label:label' + CR +
            '    text = "Name:"' + CR +
            '    top = $margin' + CR +
            '    left = $margin' + CR +
            '  end' + CR +
            '  object name:string' + CR +
            '    hint = "Node name"' + CR +
            '    top = $margin' + CR +
            '    left = label.width + $margin' + CR +
            '    allownull = false' + CR +
            '  end' + CR +
            'end' ;

This is the code that sets up the UI definition which is passed to the TUUI instance. This is minimal since the program does very little. It merely sets up a container component called "Main", which contains two components: a label and a string. In a GUI, "Main" would be the application window, "label" would be some static text, and "name" would be an edit box (or equivalent). In the case of the command line, "Main" does nothing more than serve as a container for the other two components. "label" defines the prompt to use (in "text") if the user didn't supply a node name on the command line. "name" defines what is expected (a non-blank string of characters). If the node name is provided on the command line, the "name" object will be assigned that value. Otherwise the user will be prompted for the name and whatever they type in will be assigned to the text attribute of the "name" component. After Execute returns, the program can query the "name" component's Text attribute to get the node name. One thing to note: UUI doesn't validate the node name other than to make sure it isn't null. That validation must still be done by the program. The reason is simple: UUI cannot know all of the possible validations needed for every CUSP. We will see some common situations as we continue, but the program must still do some basic checks on the user-supplied input.

"top", "left", and "hint" attributes are only used in a GUI and are ignored in command line. Now, this may seem like a bunch of extra work to prompt for a simple name, but the actual line count of the program is smaller due to the TUUI code handling various conditions. Not to mention that the program will now work with a GUI. Besides, most CUSPs will have far more options that will make the use of UUI more obviously beneficial.

If you have a passing familiarity with VMS, you might ask: why use UUI when one could use the VMS CDU (Command Definition Utility)? The answer is that they are quite different despite the superficial similarities. First, CDU must be used by the user or system administrator to define commands ahead of time. Because any program can be given a UUI by the developer, no knowledge or effort is required on the part of the user or admin. And although standard CUSPs can be handled by some startup command files provided with UOS, that does nothing to help with custom CUSPs or third-party CUSPs that may be installed on the system. Second, all CDU does is validate the command line - the program must still parse the command line on VMS and handle errors. UUI, by comparison, does both validation and parsing of the command line (or user input). Further, it supports modal use of CUSPs, which we will discuss in the future. Third, CDU doesn't do anything to help with a GUI interface. Finally, it is better to combine as much as possible in one place (the program) than to have pieces of it in different places (such as a command definition in a script plus the program in a different file). Although it cannot always be avoided, when all the pieces needed to make a program work are scattered across different files and/or locations, it is much easier for something to go wrong. Long term, it is less problematic to bundle together as much as possible in a program. This is the guiding philosophy that also led to the incorporation of ancillary data streams in files, which we discussed in the past. Note: if there must be several pieces, it is best if they are segregated from other programs, together somewhere.

We will look at the UUI code at some point in the future, and we will cover additional features of it as needed as we go forward. In the next article, we will provide a formal introduction to UUI.

We'll finish this article with a description of the SYS_SET_NODE_NAME service.

function SYS_SET_NODE_NAME( Name : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TString_Request ;
    Sname : PSRB ;

begin
    Status := 0 ;
    if( Name = 0 ) then
    begin
        Result := SS_BADPARAM ;
        exit ;
    end ;
    SName := PSRB( Name ) ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_Kernel ;
    SysRequest.Request.Request := UOS_Kernel_SetNodeName ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB.Buffer := SName.Buffer ;
    SysRequest.SRB.Length := SName.Length ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := Status ;
end ;

This code is added to the Sys unit. This is standard fare, so I won't say anything more about it.

        UOS_Kernel_SetNodeName:
            begin
                Offset := MMC.Lock_Pages( PID, Value, sizeof( TString_Request ) ) ;
                Base := MMC.Map_Pages( PID, 0, Value, sizeof( TString_Request ), MAM_Read or MAM_Lock ) ;
                if( Base = 0 ) then // Couldn't map the memory
                begin
                    USC.Set_Process_Exception( PID, MMC.Last_Error ) ;
                    if( MMC.Last_Error = nil ) then
                    begin
                        Generate_Exception( UOSErr_Memory_Address_Error ) ;
                    end ;
                    exit ;
                end ;
                String_Request := PString_Request( Base + Offset ) ;
                try
                    Status64 := Set_Node_Name( String_Request.SRB ) ;
                    if( String_Request.Request.Status <> 0 ) then // Return status
                    begin
                        Write_User_int64( Kernel, PID, String_Request.Request.Status, Status64 ) ;
                    end ;
                finally
                    MMC.UnMap_Pages( 0, Value, sizeof( TString_Request ) ) ;
                    MMC.Unlock_Pages( PID, Value, sizeof( TString_Request ) ) ;
                end ;
                exit ;
            end ;

This code is added to the Kernel's API method. Again, this is standard fare.

function TKernel.Set_Node_Name( Name : TSRB ) : int64 ;

var P : integer ;
    Status : integer ;
    UString : TUOS_String ;
    Work : string ;

begin
    // Get new name...
    Result := 0 ;
    UString := Get_User_String( Kernel, PID, Name, Status ) ;
    if( Status <> 0 ) then
    begin
        Result := Status ;
        exit ;
    end ;
    Work := UString.Contents ;
    UString.Free ;

    // Verify that we have privileges...
    if( ( USC.Get_Process_Info( PID, JPI_CURPRIV ) and PHY_IO ) = 0 ) then
    begin
        Result := SS_NOPRIV ; // User doen't have privilege to do this...
        exit ;
    end ;

    // Validate the value...
    Work := trim( lowercase( Work ) ) ;
    if( pos( Work[ 1 ], 'abcdefghijklmnopqrstuvwxyz' ) = 0 ) then
    begin
        Result := UOSErr_Invalid_Node_Name ;
        exit ;
    end ;
    for P := 2 to length( Work ) do
    begin
        if( pos( Work[ P ], 'abcdefghijklmnopqrstuvwxyz1234567890$_' ) = 0 ) then
        begin
            Result := UOSErr_Invalid_Node_Name ;
            exit ;
        end ;
    end ;

    // Make the change...
    _Node_Name := Work ;
end ; // TKernel.Set_Node_Name

This new method of the Kernel obtains the node name from the user address space, and validates that the process has the PHY_IO privilege. If not, we exit with a protection violation. Then we validate the node name, which must be alphanumeric, starting with an alpha, with dollar signs and underscores also allowed. We exit with an error, if it doesn't match these criteria. Otherwise, we set the node name as requested.

Here is the documentation for the new system service:

SYS_SET_NODE_NAME

Sets the computer's node name.

Format

SYS_SET_NODE_NAME name

Parameters

name
Address of an SRB that points to the name to use as the node name for the computer. The node name must begin with an alphabetic character and can contain alpha, numeric, dollar sign ($), and underscore (_) characters. The name should be unique on the network/cluster.

Description

The SYS_SET_NODE_NAME service sets the current node name of the computer. This happens immediately and might terminate existing network connections.

ondition codes returned

SS_NORMAL
SS_NOPRIV

Privileges required

PHY_IO

In the next article, we will look at a formal definition of UUI - at least as much as we've used it thus far.