HELPLIB.HLB  —  Lexicals  F$TRNLNM
    Translates a logical name and returns the equivalence name string
    or the requested attributes of the logical name specified.

    Format

      F$TRNLNM(logical-name [,table] [,index] [,mode] [,case]

              [,item])

1  –  Return Value

    The equivalence name or attribute of the specified logical
    name. The return value can be a character string or an integer,
    depending on the arguments you specify with the F$TRNLNM
    function. If no match is found, a null string ("")  is returned.

2  –  Arguments

 logical-name

    Specifies a character string containing the logical name to be
    translated.

 table

    Specifies a character string containing the logical name table
    or tables that the F$TRNLNM function should search to translate
    the logical name. The table argument must be a logical name that
    translates to a logical name table or to a list of table names.

    A logical name for a logical name table must be defined in one of
    the following logical name tables:

    o  LNM$SYSTEM_DIRECTORY

    o  LNM$PROCESS_DIRECTORY

                                   NOTE

       If you subsequently create a table using the CREATE/NAME_
       TABLE command and want to make your private table accessible
       for F$TRNLNM, you must redefine one of the table logical
       names to include your private table. To see all the tables
       that are normally searched by F$TRNLNM, issue the following
       command:

       $ SHOW LOGICAL/STRUCTURE LNM$DCL_LOGICAL

       For more information, see the CREATE/NAME_TABLE amd SHOW
       LOGICAL commands.

    If you do not specify a table, the default value is LNM$DCL_
    LOGICAL. That is, the F$TRNLNM function searches the tables whose
    names are equated to the logical name LNM$DCL_LOGICAL. Unless
    LNM$DCL_LOGICAL has been redefined for your process, the F$TRNLNM
    function searches the process, job, group, and system logical
    name tables, in that order, and returns the equivalence name for
    the first match found.

 index

    Specifies the number of the equivalence name to be returned if
    the logical name has more than one translation. The index refers
    to the equivalence strings in the order the names were listed
    when the logical name was defined.

    The index begins with zero; that is, the first name in a list of
    equivalence names is referenced by the index zero.

    If you do not specify the index argument, the default is zero.

 mode

    Specifies a character string containing one of the following
    access modes for the translation: USER (default), SUPERVISOR,
    EXECUTIVE, or KERNEL.

    The F$TRNLNM function starts by searching for a logical name
    created with the access mode specified in the mode argument. If
    it does not find a match, the F$TRNLNM function searches for the
    name created with each inner access mode and returns the first
    match found. For example, two logical names can have the same
    name, but one name can be created with user access mode and the
    other name with executive access mode. If the mode argument is
    USER, the F$TRNLNM function returns the equivalence string for
    the user-mode, not the executive-mode, logical name.

 case

    Specifies the type of translation to be performed. The case
    argument controls both the case of the translation and whether
    the translation is to be interlocked or noninterlocked.

    You can specify the case argument as any combination of CASE_
    BLIND (default), CASE_SENSITIVE, NONINTERLOCKED (default), and
    INTERLOCKED.

    If the translation is case blind, the F$TRNLNM searches the
    logical name table for the first occurrence of the logical name,
    regardless of the case, and returns the translation. If no match
    is found for either case, the function returns a null string
    ("").

    If the translation is case sensitive, the F$TRNLNM function
    searches only for a logical name with characters of the same
    case as the logical-name argument. If no exact match is found,
    the F$TRNLNM function returns a null string ("").

    If the translation is interlocked, the F$TRNLNM function does
    not take effect until all clusterwide logical name modifications
    in progress complete. Then, if a match is found, the result of
    the translation is returned. If no match is found, the F$TRNLNM
    function returns a null string ("").

    If the translation is noninterlocked, the F$TRNLNM function
    takes effect immediately. If a match is found, the result of
    the translation is returned. If no match is found, the F$TRNLNM
    function returns a null string ("").

 item

    Specifies a character string containing the type of information
    that F$TRNLNM should return about the specified logical name.
    Specify one of the following items:

                Return
    Item        Type      Information Returned

    ACCESS_     String    One of the following access modes
    MODE                  associated with the logical name: USER,
                          SUPERVISOR, EXECUTIVE, KERNEL.

    CLUSTERWIDE String    TRUE or FALSE to indicate whether the
                          logical name is in a clusterwide name
                          table.

    CONCEALED   String    TRUE or FALSE to indicate whether the
                          CONCEALED attribute was specified with
                          the /TRANSLATION_ATTRIBUTES qualifier when
                          the logical name was created. The CONCEALED
                          attribute is used to create a concealed
                          logical name.

    CONFINE     String    TRUE or FALSE to indicate whether the
                          logical name is confined. If the logical
                          name is confined (TRUE), then the name is
                          not copied to subprocesses. If the logical
                          name is not confined (FALSE), then the name
                          is copied to subprocesses.

    CRELOG      String    TRUE or FALSE to indicate whether the
                          logical name was created with the $CRELOG
                          system service or with the $CRELNM system
                          service, using the CRELOG attribute.

                          If the logical name was created with the
                          $CRELOG system service or with the $CRELNM
                          system service, using the CRELOG attribute,
                          then TRUE is returned. Otherwise, FALSE is
                          returned.

    LENGTH      Integer   Length of the equivalence name associated
                          with the specified logical name. If the
                          logical name has more than one equivalence
                          name, the F$TRNLNM function returns the
                          length of the name specified by the index
                          argument.

    MAX_INDEX   Integer   The largest index defined for the logical
                          name. The index shows how many equivalence
                          names are associated with a logical name.
                          The index is zero based; that is, the index
                          zero refers to the first name in a list of
                          equivalence names.

    NO_ALIAS    String    TRUE or FALSE to indicate whether the
                          logical name has the NO_ALIAS attribute.
                          The NO_ALIAS attribute means that a logical
                          name must be unique within outer access
                          mode.

    TABLE       String    TRUE or FALSE to indicate whether the
                          logical name is the name of a logical name
                          table.

    TABLE_NAME  String    Name of the table where the logical name
                          was found.

    TERMINAL    String    TRUE or FALSE to indicate whether the
                          TERMINAL attribute was specified with the
                          /TRANSLATION_ATTRIBUTES qualifier when the
                          logical name was created. The TERMINAL
                          attribute indicates that the logical
                          name is not a candidate for iterative
                          translation.

    VALUE       String    Default. The equivalence name associated
                          with the specified logical name. If the
                          logical name has more than one equivalence
                          name, the F$TRNLNM function returns the
                          name specified by the index argument.

3  –  Examples

    1.$ SAVE_DIR = F$TRNLNM("SYS$DISK")+F$DIRECTORY()
         .
         .
         .
      $ SET DEFAULT 'SAVE_DIR'

      The assignment statement concatenates the values returned
      by the F$DIRECTORY and F$TRNLNM functions, and assigns the
      resulting string to the symbol SAVE_DIR. The symbol SAVE_DIR
      consists of a full device and directory name string.

      The argument SYS$DISK is enclosed in quotation marks ("")
      because it is a character string. (The command interpreter
      treats all arguments that begin with alphabetic characters
      as symbols or lexical functions, unless the arguments are
      enclosed in quotation marks.) None of the optional arguments
      is specified, so the F$TRNLNM function uses the defaults.

      At the end of the command procedure, the original default
      directory is reset. When you reset the directory, you must
      place single quotation marks (` ')  around the symbol SAVE_DIR
      to force symbol substitution.

    2.$ DEFINE/TABLE=LNM$GROUP TERMINAL 'F$TRNLNM("SYS$OUTPUT")'

      This example shows a line from a command procedure that (1)
      uses the F$TRNLNM function to determine the name of the current
      output device and (2)  creates a group logical name table entry
      based on the equivalence string.

      You must enclose the argument SYS$OUTPUT in quotation marks
      because it is a character string.

      Also, in this example you must enclose the F$TRNLNM function
      in single quotation marks to force the lexical function to be
      evaluated; otherwise, the DEFINE command does not automatically
      evaluate the lexical function.

    3.$ RESULT= -
      _$ F$TRNLNM("INFILE","LNM$PROCESS",0,"SUPERVISOR",,"NO_ALIAS")
      $ SHOW SYMBOL RESULT
        RESULT = "FALSE"

      In this example, the F$TRNLNM function searches the process
      logical name table for the logical name INFILE. The function
      starts the search by looking for the logical name INFILE
      created in supervisor mode. If no match is found, the function
      looks for INFILE created in executive mode.

      When a match is found, the F$TRNLNM function determines whether
      the name INFILE was created with the NO_ALIAS attribute. In
      this case, the NO_ALIAS attribute is not specified.

    4.$ foo=f$trnlnm("FOO","LNM$SYSCLUSTER",,,"INTERLOCKED",)

      In this example, logical name FOO is translated in the
      LNM$SYSCLUSTER table in an interlocked manner; that is, all
      clusterwide logical name modifications in progress on this
      and other nodes are completed before the translation occurs.
      This ensures that the translation is based on the most recent
      definition of FOO.

      Because the case translation is not specified, the translation
      is by default CASE_BLIND.

    5.$ foo=f$trnlnm("FOO","LNM$SYSCLUSTER",,,"INTERLOCKED,CASE_SENSITIVE",)

      This example specifies both case sensitive and interlocked
      translation.
Close Help