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.