More on symbols

We introduced TRNLNM back in article 68. TRNLNM provides a means of querying the system symbol tables and the interface was fairly simple. VMS supports some additional capabilities for symbols and in this article we will discuss those features. Note that the default behavior will still match how things work now. Use of the new features is optional. Thus, all existing code will continue to work. When multiple symbol names exist with different cases but are otherwise the same, they are referred to as "aliases".

The first feature is that of case-sensitive symbol names. VMS allows this and so UOS will too. However, unless specifically requested, we will treat the names as uppercase. Thus, multiple versions (using different cases) of a symbol can exist.

The second feature is that a symbol can have multiple values, accessable via an index. Unless specifically requested, there will be a single value (always index 0).

The third feature is that symbols of the same name (even of the same case) can be defined for each ring (0-3). Ring 3 is the application ring and is the default ring for symbols. The ring associated with a symbol is sometimes referred to as the "access mode".

The final feature is the inclusion of flags with each symbol. These flags define various options, such as whether or not aliases are allowed for the symbol.

We will address these features in detail in future articles. But to prepare for this, we need to alter the symbol table implementation. We will briefly review these changes here. The basic idea is this: the symbol list in the table indicates the symbol names normalized to uppercase. This allows us to quickly find all aliases of a given symbol name. Each entry in the list has an associated list of symbols which defines all of the symbol alises, including the access mode (we prefix the case-sensitive name with the access mode). Each of those entries has an associated TSymbol instance which defines the flags for that symbol and contains a list of values. Here is an illustration of the overall data structure, including the path used to find the value for the symbol "MySymbol":

type TSymbol = class
                   public // constructors and destructors...
                       constructor Create( const _Value : string ;
                           _Flags : integer ) ;
                       destructor Destroy ; override ;

                   public // Instance data...
                       Flags : integer ; // LNM_* flags
                       Values : TStringList ; // Equivalence values...
               end ; // TSymbol

// constructors and destructors...

constructor TSymbol.Create( const _Value : string ; _Flags : integer ) ;

begin
    inherited Create ;

    Flags := _Flags ;
    Values := TStringList.Create ;
    Values.Add( _Value ) ;
end ;


destructor TSymbol.Destroy ;

begin
    FreeandNil( Values ) ;

    inherited Destroy ;
end ;

This is the new class to hold all the values of a given symbol. There is one of these instances for each alias, for each access mode defined. It simply wraps a TStringList and adds flags.

destructor TSymbol_Table.Destroy ;

var I, Loop : integer ;
    Symbols : TStringList ;

begin
    for Loop := 0 to List.Count - 1 do
    begin
        Symbols := TStringList( List.Objects[ Loop ] ) ;
        for I := 0 to Symbols.Count - 1 do
        begin
            TSymbol( Symbols.Objects[ I ] ).Free ;
        end ;
        Symbols.Free ;
        List.Objects[ Loop ] := nil ;
    end ;
    FreeandNil( List ) ;

    inherited Destroy ;
end ;

The destructor releases all of the memory held by the table. As before, List is a TStringlist containing the variable names. But instead of the associated object being a string object, it is now a TStringlist. That is, List is a stringlist of stringlists. The sub-stringlist contains all of the aliases of the symbol. That list's object is a TSymbol instance.

To free this structure, we iterate through all the symbols in the table, then iterate through the sub-list (aliases) for each symbol. We free the TSymbol instance, which frees up the list of values. When we are done iterating through the aliases, we free the alias stringlist. Finally, we free List.

procedure TSymbol_Table.Set_Value( Name, Value : PChar ; Len : longint ;
    Access : integer = 3 ) ;

var I : integer ;
    N, uN, V : Ansistring ;
    Prefix : char ;
    Symbol : TSymbol ;
    Symbol_List : TStringList ;

begin
    // Process parameters...
    N := Ansistring( Name ) ;
    uN := uppercase( N ) ;
    if( Len = -1 ) then
    begin
        V := Ansistring( Value ) ;
    end else
    begin
        setlength( V, Len ) ;
        move( Value[ 0 ], PChar( V )[ 0 ], Len ) ;
    end ;
    Prefix := char( Access ) ;

    // Set/create value...
    I := List.Indexof( uN ) ;
    if( I = -1 ) then // Not already defined
    begin
        Symbol_List := TStringList.Create ;
        Symbol_List.Sort ;
        List.AddObject( uN, Symbol_List ) ;
        Symbol_List.AddObject( Prefix + N, TSymbol.Create( V, 0 ) ) ;
        exit ;
    end ;
    Symbol_List := TStringList( List.Objects[ I ] ) ;
    I := Symbol_List.Indexof( Prefix + N ) ;
    if( I = -1 ) then // Doesn't exist yet
    begin
        Symbol_List.AddObject( Prefix + N, TSymbol.Create( V, 0 ) ) ;
        exit ;
    end ;
    Symbol := TSymbol( Symbol_List.Objects[ I ] ) ;
    Symbol.Values[ 0 ] := V ;
end ; // TSymbol_Table.Set_Value

We've added an access mode to the parameter list, which defaults to 3. We locate the uppercase (normalized) symbol name in List. Once we've found the symbol, we look for an alias with an exact case match and with the proper access mode. If not found, we create it. Otherwise we alter the value.

function TSymbol_Table.Exists( Name : Pchar ; CS : boolean = false ;
    Access : integer = 3 ) : boolean ;

begin
    Result := Indexof( Ansistring( Name ), CS, Access ) <> -1 ;
end ;

We've added CS and Access parameters (defaulting to False and 3, respectively). Then we call a new method, Indexof, to look up the symbol.

procedure TSymbol_Table.Delete( Name : Pchar ; CS : boolean = False ;
    Access : integer = 3 ) ;

var I, L : integer ;
    N, uN : Ansistring ;
    Prefix : char ;
    Symbols : TStringList ;

begin
    // Setup...
    N := Ansistring( Name ) ;
    uN := uppercase( N ) ;
    Prefix := char( Access ) ;

    // Look up the symbol...
    L := List.Indexof( uN ) ;
    if( L = -1 ) then // Not found at all
    begin
        exit ;
    end ;
    Symbols := TStringList( List.Objects[ L ] ) ;
    I := Symbols.Indexof( Prefix + N ) ;
    if( I = -1 ) then // Exact match not found
    begin
        if( not CS ) then
        begin
            for I := 0 to Symbols.Count - 1 do
            begin
                if( copy( Symbols[ I ], 1, 1 ) = Prefix ) then
                begin
                    TSymbol( Symbols.Objects[ I ] ).Free ;
                    Symbols.Delete( I ) ;
                    if( Symbols.Count = 0 ) then // All aliases deleted
                    begin
                        Symbols.Free ;
                        List.Delete( L ) ;
                    end ;
                    break ;
                end ;
            end ; // for I := 0 to Symbols.Count - 1
        end ; // if( not CS )
        exit ;
    end ; // if( I = -1 )

    // Delete the symbol...
    TSymbol( Symbols.Objects[ I ] ).Free ;
    Symbols.Delete( I ) ;
    if( Symbols.Count = 0 ) then // All aliases deleted
    begin
        Symbols.Free ;
        List.Delete( L ) ;
    end ;
end ; // TSymbol_Table.Delete

Again, we add defaulted CS and Access parameters. We look up the the normalized name, Then we look up the exact name/access mode in the alias list. If that isn't found, and CS is false (indicating case-insensitive), we iterate through the aliases and delete all that have the passed access mode. If the exact match is found, we delete only that alias. In either case, once we've finished any/all deletions, we check to see if the alias list is empty. If so, the symbol has been completely deleted and we remove the entry in the normalized list.

function TSymbol_Table.Info( Name : PChar ; var Len : longint ;
    CS : boolean ; Access, Index : integer ; var Flags, Mode, Indexes : int64 ;
    var aName : PChar ) : PChar ;

var I : integer ;
    N, uN, Prefix, S : Ansistring ;
    Symbols : TStringList ;
    Symbol : TSymbol ;

begin
    // Setup...
    Result := nil ;
    Len := 0 ;
    N := Ansistring( Name ) ;
    uN := uppercase( N ) ;

    // Find symbol...
    I := List.Indexof( N ) ;
    if( I = -1 ) then
    begin
        exit ;
    end ;
    Symbols := TStringList( List.Objects[ I ] ) ;
    while( true ) do
    begin
        Prefix := char( Access ) ;
        for I := 0 to Symbols.Count - 1 do
        begin
            S := Symbols[ I ] ;
            if( copy( S, 1, 1 ) = Prefix ) then
            begin
                if( CS ) then // Case-sensisitve
                begin
                    if( S <> Prefix + N ) then // Not exact match
                    begin
                        continue ;
                    end ;
                end ;
                Symbol := TSymbol( Symbols.Objects[ I ] ) ;
                Indexes := Symbol.Values.Count - 1 ;
                if( ( Index < 0 ) or ( Index > Indexes ) ) then
                begin
                    Index := 0 ; // Use index 0 if requested index is out of range
                end ;
                Result := PChar( Symbol.Values[ Index ] ) ;
                Len := length( Symbol.Values[ Index ] ) ;
                Mode := Access ;
                Flags := Symbol.Flags ;
                aName := PChar( S ) + 1 ;
                exit ;
            end ;
        end ; // for I := 0 to Symbols.Count - 1

        // Not found at specified access level, check next inner level...
        if( Access = 0 ) then
        begin
            exit ; // Exhausted the search with no matches
        end ;
        dec( Access ) ;
    end ; // while( true )
end ; // TSymbol_Table.Info

We loop through the aliases, looking for a match with the specified access mode (taking case-sensitivity into account, if necessary). If not found, we decrement the access mode and try again. This is because, we always look for the outermost access modes first, proceeding to innermore modes until the symbol is found. Obviously, we exit if a match isn't found on the innermost mode. Otherwise we return information about the symbol including it's value, actual name, flags, and access mode.

function TSymbol_Table.Value( Name : PChar ; var Len : longint ;
    CS : boolean ; Access : integer ) : PChar ;

var Flags, Mode : int64 ;
    aName : PChar ;

begin
    Result := Info( Name, Len, CS, Access, 0, Flags, Mode, aName ) ;
end ;

We've added CS and Access and changed this function to call the Info method, ignoring what it returns other than the symbol value.

function TSymbol_Table.Get_Index( Index : integer ; var Len : longint ;
    Access : integer = 3 ) : PChar ;

var I : integer ;
    Prefix : string ;
    Symbols : TStringList ;

begin
    // Setup...
    Result := nil ;
    if( ( Index < 0 ) or ( Index >= Count ) ) then
    begin
        exit ; // Out of range
    end ;
    Symbols := TStringList( List.Objects[ I ] ) ;

    // Search for match...
    while( true ) do
    begin
        Prefix := Char( Access ) ;
        for I := 0 to Symbols.Count - 1 do
        begin
            if( copy( Symbols[ I ], 1, 1 ) = Prefix ) then
            begin
                Result := PChar( TSymbol( Symbols.Objects[ I ] ).Values[ 0 ] ) ;
                Len := length( TSymbol( Symbols.Objects[ I ] ).Values[ 0 ] ) ;
                exit ;
            end ;
        end ; // for I := 0 to Symbols.Count - 1

        // Not found at specified access level, check next inner level...
        if( Access = 0 ) then
        begin
            exit ; // Exhausted the search with no matches
        end ;
        dec( Access ) ;
    end ; // while( true )
end ;

We've added Access to the parameters. Like the previous function, we search the alias table from the requested access mode to the innermost access mode.

function TSymbol_Table.IndexOf( Value : string ; CS : boolean = false ;
    Access : integer = 3 ) : integer ;

var I, L : integer ;
    Symbols : TStringList ;
    Prefix, S, UValue : string ;

begin
    // Setup...
    Result := -1 ; // Assume not found...
    UValue := uppercase( Value ) ;
    Prefix := char( Access ) ;

    // Look up the symbol...
    I := List.Indexof( UValue ) ;
    if( I = -1 ) then // Not found at all
    begin
        exit ;
    end ;
    Symbols := TStringList( List.Objects[ I ] ) ;

    // Match by case...
    for L := 0 to Symbols.Count - 1 do
    begin
        S := Symbols[ L ] ;
        if( Prefix >= copy( S, 1, 1 ) ) then
        begin
            if( not CS ) then
            begin
                Result := I ;
                exit ;
            end ;
            system.delete( S, 1, 1 ) ;
            if( S = Value ) then // Exact match
            begin
                Result := I ;
                exit ;
            end ;
        end ;
    end ; // while( List[ I ] = UValue )
end ; // TSymbol_Table.IndexOf

This is a new method for the symbol table class. It returns the index (in the normalized symbol name list) of the specified symbol, with the requested access mode and case-sensitivity. It returns -1 if the normalized name isn't found, or if a matching alias isn't found.

In the next article, we will examine the F$TRNLNM lexical function.