DELLNT

VMS doesn't have a DELLNT system service, but UOS has added one for the purposes of manually deleting a table. Note that the VMS DELLNM service can be used to delete a logical table and we will be covering that in a future article, but it seems orthogonal to me to have a corresponding system call to CRELNT. But even more important is the need to be able to atomically assign a new default table.

Note: Yes I meant "atomically" as opposed to "automatically". An atomic operation is one in which all substeps must happen without interruption. It is like a database transaction. The word comes from the Greek atomos which mean something which cannot be broken into smaller pieces (literally "uncuttable"), and in the early days of physics the word was applied to atoms because they were thought to be the smallest particles in existence. Since then, of course, we find that atoms are made up of subatomic particles, but the concept remains.

The reason we want this operation to be atomic is because once a table is deleted, if it is the default table, we need to have the default switched to a new table at the same time. If we only delete one and then have to do another operation to set the default, something could happen between those two discrete operations that might have unpredictable consequences (remember that UOS is a multi-tasking operating system).

Here's the documentation for DELLNT:

DELLNT

Deletes a symbol table.

Format
SYS_DELLNT( Tabnam, Parent, Default )

Arguments
Tabnam

Address of an SRB defining the name of the table to delete.

Parent

Address of an SRB defining the name of the parent table of the table to delete.

Default

Optional address of an SRB defining the name of the table to become the default table for the parent table. If not specified, and the deleted table was the default table, UOS chooses another table as the default.

Condition Codes

Code Meaning

SS_NORMAL Normal completion

SS_BADPARAM No table or parent name was provided.

SS_NOLOGTAB A specified table does not exist.

SS_NOPRIV Calling process doesn't have a required privilege.

function DELLNT( TabName, Parent, Default : string ) : cardinal ;

var S_Tabname, S_Parent, S_Default : TSRB ;

begin
    Set_String( TabName, S_Tabname ) ;
    Set_String( Parent, S_Parent ) ;
    Set_String( Default, S_Default ) ;
    Result := SYS_DELLNT( int64( @S_Tabname ), int64( @Parent ), int64( @S_Default ) ) ;
end ;

This addition to PasStarlet wraps the passed strings in TSRB structures and calls the SYS unit.

function SYS_DELLNT( Tabnam, Parent, Default : int64 ) : int64 ;

var S_Tabnam, S_Parent, S_Default : PSRB ;
    SysRequest : TString3_Request ;

begin
    S_Tabnam := PSRB( pointer( Tabnam ) ) ;
    S_Parent := PSRB( pointer( Parent ) ) ;
    S_Default := PSRB( pointer( Default ) ) ;

    SysRequest.Request.Subsystem :=  UOS_Subsystem_SSC ;
    SysRequest.Request.Request := UOS_SSC_DELLNT ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := 0 ;
    SysRequest.String1.Buffer := S_Tabnam.Buffer ;
    SysRequest.String2.Buffer := S_Parent.Buffer ;
    SysRequest.String3.Buffer := S_Default.Buffer ;
    SysRequest.String1.Length := S_Tabnam.Length ;
    SysRequest.String2.Length := S_Parent.Length ;
    SysRequest.String3.Length := S_Default.Length ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := SysRequest.Request.Status ;
end ; // SYS_DELLNT

This addition to the SYS unit constructs the appropriate system request structure and calls the executive.

        UOS_SSC_DELLNT:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC, 
                    sizeof( TString3_Request ) - sizeof( TSystem_Request ), Base ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;

                try
                    PS3 := PString3_Request( Base ) ;
                    PS3.Request.Status := DELLNT( Kernel, PID, PS3.String1, PS3.String2,
                        PS3.String3 ) ;
                finally
                    Exit_System_Call( Base, PID, MMC, sizeof( TString3_Request ) ) ;
                end ;
            end ;

This code is added to the SSC's API method.

function TUOS_SSC.DELLNT( Kernel : TUOS_Kernel ; PID : TPID ;
    Tabnam, Parent, Default : TSRB ) : int64 ;

var I, Status : integer ;
    Default_Name, Parent_Name, Table_Name : string ;
    Table : TUOS_Symbol_Table ;
    US : TUOS_String ;

begin
    if( Parent.Buffer = 0 ) then
    begin
        Result := SS_BADPARAM ;
        exit ;
    end ;
    US := Get_User_String( Kernel, PID, Parent, Status ) ;
    if( Status = UE_Error ) then
    begin
        Result := Status ;
        exit ;
    end ;
    Parent_Name := trim( lowercase( US.Contents ) ) ;
    US.Detach ;

    US := Get_User_String( Kernel, PID, Tabnam, Status ) ;
    if( Status = UE_Error ) then
    begin
        Result := Status ;
        exit ;
    end ;
    Table_Name := trim( lowercase( US.Contents ) ) ;
    if( length( Table_Name ) = 0 ) then
    begin
        Result := SS_BADPARAM ;
        exit ;
    end ;
    US.Detach ;

    US := Get_User_String( Kernel, PID, Default, Status ) ;
    if( Status = UE_Error ) then
    begin
        Result := Status ;
        exit ;
    end ;
    Default_Name := trim( lowercase( US.Contents ) ) ;
    US.Detach ;

This new method starts by obtaining the table names from the user memory. If any of the specified table names cannot be obtained, we exit with an error. If either the table name or parent table name is not supplied, we exit with a SS_BADPARAM error. Since the default table name is optional, we don't exit with that error if it isn't provided.

    // Delete the table...
    if( Parent_Name = 'lnm$process_directory' ) then
    begin
        if( PID = 0 ) then
        begin
            Result := SS_NOLOGTAB ;
            exit ;
        end ;
        Result := USC.Delete_Symbol_Table( PChar( Table_Name ), PChar( Default_Name ), PID, 3 ) ;
    end else

If the parent table is the process directory, we check that we have a PID. If we don't, there is no process directory to deal with and we exit with an error. Otherwise we call the USC to delete the table. This is covered later in this article.

    if( Parent_Name = 'lnm$system_directory' ) then
    begin
        if( ( PID <> 0 )
            and
            not USC.Validate_Protection( PID, FAB_V_UPD, 0, 
                PROTECTION_SYSTEM_WRITE or PROTECTION_SYSTEM_DELETE, 0 )
          ) then 
        begin
            Result := SS_NOPRIV ;
            exit ;
        end ;
        I := Symbols.IndexOf( Table_Name ) ;
        if( I <> -1 ) then // Table exists
        begin
            Table := TUOS_Symbol_Table( Symbols.Objects[ I ] ) ;
            Symbols.Delete( I ) ;
            Table.Free ;
        end else
        begin
            Result := SS_NOLOGTAB ;
        end ;
    end else
    begin
        Result := SS_NOLOGTAB ;
    end ;
end ; // TUOS_SSC.DELLNT

If the system directory was specified, we check that the process has the privileges to delete the table (if the PID is 0, this is a request from the executive itself and that is always permitted). For now, we have hard-coded the table protection. Next we lookup the table in the system symbol table. If not found, we exit with an error. Otherwise, we delete the table from the list and delete the table. On the other hand, if the parent name isn't recognized we exit with an error.

function TUSC.Delete_Symbol_Table( Table_Name, Default_Name : PChar ;
    PID : TPID ; AcMode : int64 ) : int64 ;

var Process : TProcess ;
    I : integer ;
    D, T : string ;

begin
    Result := 0 ;
    Process := Get_Process( PID ) ;
    if( Process = nil ) then // Process doesn't exist
    begin
        Result := UOSErr_Nonexistent_Process ;
        exit ;
    end ;
    T := lowercase( trim( string( Table_Name ) ) ) ;
    if( T = '' ) then
    begin
        Result := SS_NOLOGTAB ;
        exit ;
    end ;
    D := lowercase( trim( string( Default_Name ) ) ) ;

This new method in the USC gets the specified PID. If the process isn't found, we exit with an error. Next we get the table names and convert them to lowercase. This is necessary since we save the table names in lowercase.

    if( T = 'lnm$process' ) then // Delete the current default process table
    begin
        T := Process._Symbols.Name ;
    end ;
    I := Process.Symbol_Table_Directory.Indexof( T ) ;
    if( I = -1 ) then
    begin
        Result := SS_NOLOGTAB ;
        exit ;
    end ;

As mentioned in the previous article, lnm$process refers to the default table, regardless of its name. But we need to know the actual table, so if lnm$process is specified, we get the default table's actual name. Note that this may be "lnm$process". But either way, we now have the name of the table to delete. So we look in the process table list for a table of that name. If not found, we exit with an error.

    if( Process._Symbols.Name = 'lnm$process' ) then
    begin
        TUOS_Symbol_Table( Process.Symbol_Table_Directory.Objects[ I ] ).Clear ;
        // Can't really delete this table - so just clear it
    end else
    begin
        if( Process.Symbol_Table_Directory.Objects[ I ] = Process._Symbols ) then
        begin
            Process._Symbols := nil ;
        end ;
        Process.Symbol_Table_Directory.Objects[ I ].Free ;
        Process.Symbol_Table_Directory.Delete( I ) ;
    end ;

If the table's name is "lnm$process", we cannot delete it because that table is permanent for the life of the process. That way, there will always be a symbol table for the process. But, we will delete the contents of the table. If it is a different table, we delete the table and remove it from the list. Before that, though, we set the default symbol table pointer to null if it had been pointing to the table that we are deleting.

    if( D <> '' ) then // New default specified
    begin
        I := Process.Symbol_Table_Directory.Indexof( D ) ;
        if( I = -1 ) then
        begin
            Result := SS_NOLOGTAB ;
        end else
        begin
            Process._Symbols := TUOS_Symbol_Table( Process.Symbol_Table_Directory.Objects[ I ] ) ;
        end ;
    end ;

If a default table was specified, we look up the table in the list. If not found, we set the result to an error, but we don't exit yet. Otherwise, we point the default pointer to the specified table.

    if( Process._Symbols = nil ) then
    begin
        I := Process.Symbol_Table_Directory.Indexof( 'lnm$process' ) ;
        Process._Symbols :=
            TUOS_Symbol_Table( Process.Symbol_Table_Directory.Objects[ I ] ) ;
    end ;
end ; // TUSC.Delete_Symbol_Table

Finally, if the default table pointer is nil (meaning that the old default has been deleted and no new default was specified or found), we set the pointer to the actual lnm$process table. This is why we didn't exit above if there was an error - we must have the pointer point to a valid table when we exit.

In the next article, we will look at the next UCL command.