SYS_TRNLNM, Part 2

We introduced the TRNLNM system service back in article 68. In this article, we will flesh out the rest of its features. Here is the definition of the service:

TRNLNM returns information about a symbol name.

Format

TRNLNM flags table name acmod itemlst

Arguments
flags

Address of 64-bit flag to control the operation of TRNLNM. If this is 0, no flags are considered to be set. The following flags can be specified:

Flag Description

LNM_M_CASE_BLIND If set, TRNLNM doesn't distinguish between upper and lower case characters in the symbol name. By default, TRNLNM matches by case.

LNM_INTERLOCKED If set, TRNLNM will wait to complete until any current clusterwide symbols are complete.

table

The address of an SRB structure pointing to the name of a symbol table. If this is 0 or the symbol table name is null, the process, job, group, system, and cluster symbol tables are searched, in that order.

name

Address of an SRB structure that points to the symbol name to translate.

acmode

The address of the 64-bit access mode to be used in the translation. If this is 0, the access mode is assumed to the outermost mode (USER). When provided, all symbols with an access mode less privileged than this are ignored. The valid access modes are:

Mneumonic Description

PSL_C_KERNEL Kernel (executive) mode (ring 0)

PSL_C_DRIVER Driver mode (ring 1)

PSL_C_EXEC Synonymous with PSL_C_DRIVER

PSL_C_USER User mode (ring 3)

PSL_C_SUPER Supervisor mode (ring 2)

itemlst

A pointer to a descriptor list containing items defining what the service should return. A descriptor list is an array of descriptors with the following layout:

Byte offset Byte length Description

0 2 Must be -1.

2 2 Item code.

4 4 Must be -1.

8 8 Length of result buffer.

16 8 Address of result buffer.

24 8 Address where to write result length.

Codes

LNM_ACMODE Returns the access mode associated with the specified symbol.

LNM_ATTRIBUTES Returns the attributes of the specified symbol. The following mnuemonics can be used to compare with these attributes.

LNM_M_CONCEALED The matching symbol is a concealed logical.

LNM_M_CONFINE The symbol will not be copied to a spawned process.

LNM_M_CRELOG The symbol was created using the CRELOG system service.

LNM_M_EXISTS The symbol exists.

LNM_M_NO_ALIAS The symbol cannot be defined in the same table with an outer access mode.

LNM_M_TABLE The symbol is a symbol table name.

LNM_M_CLUSTERWIDE The symbol was found in a clusterwide table.

LNM_M_TERMINAL The symbol is not subject to recursive translation.

LNM_CHAIN This is ignored by UOS. It is provided for VMS compatibility.

LNM_INDEX Defines which equivalence value is to be returned for following descriptors. If not specified, index 0 is used. This can be used to return several equivalence values by alternating LNM_INDEX and LNM_STRING items, changing the index with each one.

LNM_LENGTH Returns the length of the equivalence value for the specified symbol.

LNM_MAX_INDEX The maximum index for equivalence values for the specified symbol.

LNM_NAME Returns the case-sensitive name of the symbol matching the one specified.

LNM_STRING Returns the equivalence name (value) for the specified symbol.

LNM_TABLE Returns the name of the table containing the symbol name being translated.

Description
The TRNLNM system service returns information about the given symbol name.

Condition Codes
SS_NORMAL SS_BADPARAM SS_BUFFEROVF SS_IVLOGTAB SS_NOLOGNAM

function SYS_TRNLNM( attr : int64 ; tabnam, lognam : int64 ;
    acmode, itmlst : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TS2I3_Request ;
    STabName, SLogName : PSRB ;

begin
    Status := 0 ;
    if( Lognam = 0 ) then
    begin
        Result := SS_BADPARAM ;
        exit ;
    end ;
    STabName := PSRB( pointer( Tabnam ) ) ;
    SLogName := PSRB( pointer( Lognam ) ) ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_SSC ;
    SysRequest.Request.Request := UOS_SSC_TRNLNM ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.SRB1.Buffer := STabname.Buffer ;
    SysRequest.SRB1.Length := STabname.Length ;
    SysRequest.SRB2.Buffer := SLogName.Buffer ;
    SysRequest.SRB2.Length := SLogName.Length ;
    SysRequest.Integer1 := Attr ;
    SysRequest.Integer2 := AcMode ;
    SysRequest.Integer3 := ItmLst ;

    Call_To_Ring0( integer( @SysRequest ) ) ;

    Result := Status ;
end ; // SYS_TRNLNM

We've made one small change to this function: we check for a missing symbol name and return an error in that case. The TRNLNM system service also checks for this condition, but by doing it here, we avoid a call across rings for this error.

function TUOS_SSC.TRNLNM( Tabname, SymName : TUOS_string ;
    Attr, AcMode, ItemLst : int64 ) : int64 ;

var aName : PChar ;
    Buff : PAnsiChar ;
    CS : boolean ;
    Descriptor : TSYS_Descriptor ;
    L : longint ;
    Flags, I, Index, Indexes, Len, Mode : int64 ;
    Offset : int64 ;
    P : PChar ;
    PID : TPID ;
    Res : int64 ;
    Status : longint ;
    S, SName : string ;
    Table : TUOS_Symbol_Table ;
    Tname : string ;

begin
    // Setup...
    Result := SS_NORMAL ;
    PID := Kernel.PID ;
    if( ( SymName = nil ) or ( SymName.Contents = '' ) ) then
    begin
        Generate_Exception( UOSErr_Missing_Name ) ;
        Result := SS_BADPARAM ;
        exit ;
    end ;
    SName := SymName.Contents ;
    CS := ( Attr and LNM_M_CASE_BLIND ) <> 0 ;

We've made several changes to this routine since we last looked at it, so we'll cover almost the entire function. In the set up, we set the CS boolean based on the LNM_M_CASE_BLIND flag, and we pull the symbol name from the parameter.

    // Determine table...
    if( TabName = nil ) then
    begin
        TName := '' ;
    end else
    begin
        TName := TabName.Contents ;
    end ;
    if( TName = '' ) then
    begin
        Table := Resolve_Table( 0, PID, SName, CS, AcMode ) ;
    end else
    begin
        Table := Get_Symbol_Table( TName ) ;
    end ;
    if( Table = nil ) then
    begin
        Generate_Exception( UOSErr_Resource_Not_Found ) ;
        Result := SS_IVLOGTAB ;
        exit ;
    end ;

This code is largely the same, with the exception of returning the condition code, and the extra parameters for the symbol table functions.

    // Get value (in S), and other symbol information...
    Flags := 0 ;
    S := '' ;
    if( Table.Exists( PAnsiChar( SName ), CS, AcMode ) ) then
    begin
        P := Table.Info( PAnsiChar( SName ), L, CS, AcMode, Index, Flags, Mode, Indexes, aName ) ;
        Flags := Flags or LNM_M_EXISTS ;
        setlength( S, L ) ;
        move( P[ 0 ], PChar( S )[ 0 ], L ) ;
    end else
    begin
        Result := SS_NOLOGNAM ;
    end ; // if( Table.Exists( SName ) )

We obtain all the information about the symbol, or set the condition code if the symbol wasn't found. If found, we add the LNM_M_EXISTS flag to the symbol flags.

                    LNM_LENGTH:
                        begin
                            Res := length( S ) ;
                            if( Len > sizeof( int64 ) ) then
                            begin
                                Len := sizeof( int64 ) ;
                            end ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, Res ) ;
                            if( Status = 0 ) then
                            begin
                                Status := Write_User( Kernel, PID, Descriptor.Return_Length_Address, 
                                    sizeof( int64 ), Len ) ;
                            end ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

The iteration of descriptors hasn't changed, so we'll simply look at the items we've added to the processing.

This item returns the length of the symbol value, writing it and it's length to the user memory and exiting if there was an error.

                    LNM_ACMODE:
                        begin
                            if( Len > sizeof( int64 ) ) then
                            begin
                                Len := sizeof( int64 ) ;
                            end ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, Mode ) ;
                            if( Status = 0 ) then
                            begin
                                Status := Write_User( Kernel, PID, Descriptor.Return_Length_Address, 
                                    sizeof( int64 ), Len ) ;
                            end ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

This item returns the access mode, writing it to the user memory and exiting on error.

                    LNM_CHAIN: ; // Ignore these
                    LNM_INDEX:
                        begin
                            Index := Get_User_Integer( Kernel, PID, Descriptor.Buffer_Address, Status ) ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

We simply skip past any LNM_CHAIN item, which does nothing in UOS. In the case of LNM_INDEX, we read the index from the user's memory.

                    LNM_MAX_INDEX:
                        begin
                            if( Len > sizeof( int64 ) ) then
                            begin
                                Len := sizeof( int64 ) ;
                            end ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, Indexes ) ;
                            if( Status = 0 ) then
                            begin
                                Status := Write_User( Kernel, PID, Descriptor.Return_Length_Address, 
                                    sizeof( int64 ), Len ) ;
                            end ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

This item returns the maximum index of the equivalence names for the symbol - writing it to the user memory and exiting if there is an error.

                    LNM_TABLE:
                        begin
                            S := ansistring( Table.Name ) ;
                            if( S = '$' + inttostr( PID ) ) then
                            begin
                                S := 'LNM$PROCESS' ;
                            end ;
                            if( Len > length( S ) ) then
                            begin
                                Len := length( S ) ;
                            end ;
                            if( Len < length( S ) ) then
                            begin
                                Result := SS_BUFFEROVF ;
                            end ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, 
                                PChar( S )[ 0 ] ) ;
                            if( Status = 0 ) then
                            begin
                                Status := Write_User( Kernel, PID, Descriptor.Return_Length_Address, 
                                    sizeof( int64 ), Len ) ;
                            end ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

This item returns the name of the table in which the symbol was found, and the length of that name. These are written to the user memory and we exit if either of those writes fail. We also set the buffer override condition code, if the length of the target buffer is less than the table name. Note that the table name is converted to "LNM$PROCESS" if it is the main process symbol table. The actual name of the main process symbol table is a dollar sign followed by the process ID.

                    LNM_TABLELENGTH:
                        begin
                            S := ansistring( Table.Name ) ;
                            if( S = '$' + inttostr( PID ) ) then
                            begin
                                S := 'LNM$PROCESS' ;
                            end ;
                            if( Len > sizeof( int64 ) ) then
                            begin
                                Len := sizeof( int64 ) ;
                            end ;
                            I := length( S ) ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, I ) ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

This is not an item supported by VMS. We add it to UOS because table names are not limited in length, as they are on VMS. We write the table name length to the user memory and exit if there is an error.

                    LNM_NAME:
                        begin
                            S := ansistring( aName ) ;
                            if( Len > length( S ) ) then
                            begin
                                Len := length( S ) ;
                            end ;
                            if( Len < length( S ) ) then
                            begin
                                Result := SS_BUFFEROVF ;
                            end ;
                            Status := Write_User( Kernel, PID, Descriptor.Buffer_Address, Len, 
                                PChar( S )[ 0 ] ) ;
                            if( Status = 0 ) then
                            begin
                                Status := Write_User( Kernel, PID, Descriptor.Return_Length_Address, 
                                    sizeof( int64 ), Len ) ;
                            end ;
                            if( Status = UE_Error ) then // Error reading user value
                            begin
                                exit ;
                            end ;
                        end ;

This item is also UOS-specific. This returns the case-sensitive name of the found symbol. This is useful if the symbol lookup was case-insensitive. We write the name and length to the user memory and exit if there was an error. If the result buffer is too small to hold the name, we set the overflow condition (but we don't exit).

In the next article, we will examine the next lexical function.