DELLNM system service

In the last article, our discussion of UCL's CLOSE command referenced the DELLNM system service. We will cover that in this article. Here is the user documentation:

DELLNM

Deletes a symbol or all symbols in a specific table. The symbols deleted are those at the specified access mode, or more outer.

Format

SYS_DELLNM tablename, symbolname, acmode

Arguments

tablename
This is a pointer to a TSRB structure that indicates the table name. This value cannot be null.

symbolname
This is a pointer to a TSRB structure that indicates the symbol name. If the table name is a symbol directory then this value indicates the table name within that directory. In that case, all symbols of the specified access mode, or more outer, in this table are deleted.

acmode
This is an address of an access mode. The symbols deleted are those with this access mode or a more outer one. Note that the access mode is set to the most outer value of either the user's current access mode and the specified access mode. However, if the process has the SYSNAM privilege, the specified access mode is used, regardless of the process' access mode. If the passed acmode is 0, the process' acmode is used.

Description

the DELLNM service deletes all symbols with the specified name at the specified access mode, or more outer access mode. It can also be used to delete all symbols in a table with the specified access mode.

Privileges

SYSNAM is needed to delete a symbol name at an access mode less than the process' access mode.
SYSNAM or SYSPRV is needed to delete a symbol from a system table.

Quotas

None.

Possible error codes

SS_NORMAL = Success
SS_ACCVIO = Service cannot access memory pointed to by parameters
SS_BADPARAM = Incorrect parameter
SS_IVLOGTAB = Table not found
SS_NOLOGTAB = Specified table not found
SS_NOPRIV = Process lacks sufficient privilege for operation

function DELLNM( Table, Symbol : string ; ACMode : integer = 4 ) : int64 ;

var S_Tabname, S_Symbol : TSRB ;

begin
    Set_String( Table, S_Tabname ) ;
    Set_String( Symbol, S_Symbol ) ;
    Result := SYS_DELLNM( int64( @S_Tabname ), int64( @Symbol ), ACMode ) ;
end ;

This routine is added to PasStarlet to provide a Pascal-friendly interface to the DELLNM service. It simply packages up the strings into TSRB structures and calls the service.

function SYS_DELLNM( Tabnam, Symbol, ACMode : int64 ) : int64 ;

var S_Tabnam, S_Symbol : PSRB ;
    SysRequest : TString2I1_Request ;

begin
    S_Tabnam := PSRB( pointer( Tabnam ) ) ;
    S_Symbol := PSRB( pointer( Symbol ) ) ;

    SysRequest.Request.Subsystem :=  UOS_Subsystem_SSC ;
    SysRequest.Request.Request := UOS_SSC_DELLNM ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( Sysrequest.Request ) ;
    SysRequest.Request.Status := 0 ;
    SysRequest.String1.Buffer := S_Tabnam.Buffer ;
    SysRequest.String2.Buffer := S_Symbol.Buffer ;
    SysRequest.String1.Length := S_Tabnam.Length ;
    SysRequest.String2.Length := S_Symbol.Length ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := SysRequest.Request.Status ;
end ;

This is a typical wrapper for the system call.

        UOS_SSC_DELLNM:
            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
                    PS2I1 := PString2I1_Request( Base ) ;
                    PS2I1.Request.Status := DELLNM( Kernel, PID, PS2I1.String1,
                        PS2I1.String2, PS2I1.Integer1 ) ;
                finally
                    Exit_System_Call( Base, PID, MMC, sizeof( TString3_Request ) ) ;
                end ;
            end ;

This code is added to the SSC component's API method, which is pretty typical for this method.

function TUOS_SSC.DELLNM( Kernel : TUOS_Kernel ; PID : TPID ;
    Tabnam, Symbol : TSRB ; ACMode : integer ) : int64 ;

var I : integer ;
    Tablenam, Symbol_Name : string ;
    Status : integer ;
    Table : TUOS_Symbol_Table ;
    US : TUOS_String ;

begin
    // Get parameters...
    US := Get_User_String( Kernel, PID, Tabnam, Status ) ;
    if( Status = UE_Error ) then
    begin
        Result := Status ;
        exit ;
    end ;
    Tablenam := trim( lowercase( US.Contents ) ) ;
    US.Detach ;

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

    if( AcMode = 0 ) then
    begin
        AcMode := USC.Access_Mode( PID ) ;
    end ;

This new method does the work of deleting symbol names. First we obtain the values for the table name, symbol name, and access mode from the caller's memory space - exiting with an error if a problem occurs.

    if( ( Tablenam = '' ) and ( Symbol_Name = '' ) ) then
    begin
        Result := SS_BADPARAM ;
        exit ;
    end ;

    // See if deleting a table
    if( Tablenam = 'lnm$process_directory' ) then
    begin
        if( PID = 0 ) then
        begin
            Result := SS_NOLOGTAB ;
            exit ;
        end ;
        Result := USC.Delete_Symbol_Table( PChar( Symbol_Name ), '', PID, AcMode ) ;
        exit ;
    end ;

Next we verify the parameters. Both table and symbol names cannot be null. Next we see if we are deleting everything in a table by checking the table name. If it is the process directory table, the symbol name must be a table name within the process directory table. If not, we exit with an error, otherwise we tell the USC to delete the specified table and exit.

    Table := nil ;
    if( Tablenam = 'lnm$system_directory' ) then
    begin
        if( ( PID <> 0 )
            and
            not USC.Validate_Protection( PID, FAB_V_UPD, 0, PROTECTION_SYSTEM_DELETE, 0 )
          ) then // TODO: Use table's protection rather than hardcode ^
        begin
            Result := SS_NOPRIV ;
            exit ;
        end ;
        I := Symbols.IndexOf( Symbol_Name ) ;
        if( I <> -1 ) then // Table exists
        begin
            Table := TUOS_Symbol_Table( Symbols.Objects[ I ] ) ; // Table to delete
        end else
        begin
            Result := SS_NOLOGTAB ;
            exit ;
        end ;
    end ;

Next we check to see if the table name is the system directory. If so, the symbol name is a table within the system directory. In such case, we validate permission and exit with an error if the process has insufficient privileges. Otherwise, we find the table in the directory. If not found, we exit with an error. Note that, for now, we have hard-coded the table's protection. We will adjust this in the future. If everything is okay, we drop down to the following code with Table set to the proper table.

    // Determine the table...
    if( Table = nil ) then
    begin
        if( Tablenam = '' ) then // Need to search for the symbol
        begin
            Table := Resolve_Table( Tablenam, PID, Symbol_Name, False, AcMode ) ;
        end else
        begin
            Table := Get_Symbol_Table( Tablenam ) ;
        end ;
    end ;
    if( Table = nil ) then
    begin
        Generate_Exception( UOSErr_Resource_Not_Found ) ;
        Result := SS_IVLOGTAB ;
        exit ;
    end ;

If Table wasn't set above and no table name was specified, we must find the table which contains the specified symbol. Either way, we either have the appropriate table or Table is nil - in which case, we exit with an error.

    // Delete the symbol(s)...
    if( Symbol_Name = '' ) then // Delete all symbols in table with Access Mode > AcMode
    begin
        Table.Delete_All( AcMode ) ;
    end else
    begin
        Table.Delete( PChar( Symbol_Name ), False, AcMode ) ; 
    end ;
end ; // TUOS_SSC.DELLNM

Finally, we do the deletion. If the symbol name is null, we are deleting all of the symbols with the appropriate access mode from the table and we call Delete_All (see below) to accomplish this. Otherwise, we call the table's Delete method.

procedure TSymbol_Table.Delete_All( AcMode : integer ) ;

var I, Index, Loop : integer ;
    Prefix : string ;
    S : string ;
    Symbols : TStringList ;
    This_Symbol : TSymbol ;

begin
    Prefix := chr( AcMode ) ;
    for Loop := 0 to List.Count - 1 do
    begin
        Symbols := TStringList( List.Objects[ Loop ] ) ;
        for I := 0 to Symbols.Count - 1 do
        begin
            This_Symbol := TSymbol( Symbols.Objects[ I ] ) ;
            for Index := This_Symbol.Values.Count - 1 downto 0 do
            begin
                S := This_Symbol.Values[ Index ] ;
                if( S[ 1 ] >= Prefix ) then
                begin
                    This_Symbol.Values.Delete( Index ) ;
                end ;
            end ;
        end ; // for I := 0 to Symbols.Count - 1
    end ; // for Loop := 0 to List.Count - 1
end ; // TSymbol_Table.Delete_All

The new symbol table method is used to delete all symbols in the table with a given access mode (or more outer). This is very similar code to what we covered when we first looked at the code for symbol tables, so I won't go into detail on it. But to recall a little: the function iterates through the symbol lists, with each one it iterates through the symbols, deleting those that have the appropriate access mode prefixes.

In the next article, we will wrap up DCL file I/O by examining the READ command.