or the requested attributes of the logical name specified. Format F$TRNLNM(logical-name [,table] [,index] [,mode] [,case] [,item]) 3 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. 3 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. 2 F$TYPE Returns the data type of a symbol. The string INTEGER is returned if the symbol is equated to an integer, or if the symbol is equated to a string whose characters form a valid integer. The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer. If the symbol is undefined, a null string ("") is returned. Format F$TYPE(symbol-name) 3 Return_Value The string INTEGER is returned if the symbol is equated to an integer, or if the symbol is equated to a string whose characters form a valid integer. If the symbol has been produced by a call to the F$CONTEXT function with a context type of PROCESS or by a call to the F$PID function, the string returned is PROCESS_CONTEXT. A symbol retains this type until F$CONTEXT is called with the symbol and the CANCEL keyword, or until a null string ("") is returned by a call to F$PID. Similarly, the return value is the string CLUSTER_SYSTEM_CONTEXT for symbols created by the F$CSID function. If the symbol is a context symbol, then the return value will be one of the types shown in the following table. Symbol Type Lexical Creating Symbol PROCESS_CONTEXT F$PID or F$CONTEXT (with PROCESS context type) CLUSTER_SYSTEM_ F$CSID CONTEXT The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer or whose type is not a context. If the symbol is undefined, a null string is returned. 3 Argument symbol-name Specifies the name of the symbol to be evaluated. 3 Examples 1.$ NUM = "52" $ TYPE = F$TYPE(NUM) $ SHOW SYMBOL TYPE TYPE = "INTEGER" This example uses the F$TYPE function to determine the data type of the symbol NUM. NUM is equated to the character string "52". Because the characters in the string form a valid integer, the F$TYPE function returns the string INTEGER. 2.$ NUM = 52 $ TYPE = F$TYPE(NUM) $ SHOW SYMBOL TYPE TYPE = "INTEGER" In this example, the symbol NUM is equated to the integer 52. The F$TYPE function shows that the symbol has an integer data type. 3.$ CHAR = "FIVE" $ TYPE = F$TYPE(CHAR) $ SHOW SYMBOL TYPE TYPE = "STRING" In this example, the symbol CHAR is equated to the character string FIVE. Because the characters in this string do not form a valid integer, the F$TYPE function shows that the symbol has a string value. 4.$ x = F$CONTEXT("PROCESS",CTX,"USERNAME","SMITH") $ TYPE = F$TYPE(CTX) $ SHOW SYMBOL TYPE TYPE = "PROCESS_CONTEXT" $ x = F$CONTEXT("PROCESS",CTX,"CANCEL") $ TYPE = F$TYPE(CTX) $ SHOW SYMBOL TYPE TYPE = "" In this example, the F$TYPE function returns the string PROCESS_CONTEXT because the symbol has been produced by a call to the F$CONTEXT function with a context type of PROCESS. The symbol returns this type until F$CONTEXT is called with the symbol and the selection-item argument value CANCEL. 2 F$UNIQUE Valid on Alpha and Integrity server systems only. Generates a string that is suitable to be a file name and is guaranteed to be unique across the cluster. Unique file names can be useful when creating temporary files. The string returned is alphanumeric and may be used as a file name, logical name, or DCL symbol name or value with no reserved character issues. The F$UNIQUE function has no arguments, but must be followed by a blank pair of parentheses. Format F$UNIQUE() 3 Return_Value A character string containing the unique string. 3 Examples 1.$ WRITE SYS$OUTPUT F$UNIQUE() 414853555241159711D7DF797CCF573F $ $ WRITE SYS$OUTPUT F$UNIQUE() 414853555241509811D7DF797E3F2777 $ This example shows how a unique string is returned on subsequent WRITE commands. 2.$ OPEN/WRITE TEMP_FILE 'F$UNIQUE() $ DIRECTORY Directory WORK1:[TEST] 594B53554C421C9C11D75463D61F58B7.DAT;1 Total of 1 file. $ $ CLOSE/DISPOSITION=DELETE TEMP_FILE $ DIRECTORY %DIRECT-W-NOFILES, no files found $ The first command creates a temporary file and gives it a unique name, which is displayed by the subsequent DIRECTORY command. After the file is later closed and deleted, it no longer shows up in the directory. 2 F$USER Returns the current user identification code (UIC) in named format as a character string. The F$USER function has no arguments, but must be followed by parentheses. Format F$USER() 3 Return_Value A character string containing the current UIC, including brackets ([ ]). The UIC is returned in the format [group-identifier, member-identifier]. 3 Example $ UIC = F$USER() $ SHOW SYMBOL UIC UIC = "[GROUP6,JENNIFER]" In this example, the F$USER function returns the current user identification code and assigns it to the symbol UIC. 2 F$VERIFY Returns an integer value indicating whether the procedure verification setting is currently on or off. If used with arguments, the F$VERIFY function can turn the procedure and image verification settings on or off. You must include the parentheses after the F$VERIFY function whether or not you specify arguments. Format F$VERIFY([procedure-value] [,image-value]) 3 Return_Value The integer 0 if the procedure verification setting is off, or the integer 1 if the procedure verification setting is on. 3 Arguments procedure-value Specifies an integer expression with a value of 1 to turn procedure verification on, or a value of 0 to turn procedure verification off. When procedure verification is on, each DCL command line in the command procedure is displayed on the output device. Procedure verification allows you to verify that each command is executing correctly. If you use the procedure-value argument, the function first returns the current procedure verification setting. Then the command interpreter turns the procedure verification on or off, as specified by the argument. image-value Specifies an integer expression with a value of 1 to turn image verification on, or a value of 0 to turn image verification off. When image verification is on, data lines in the command procedure are displayed on the output device. 3 Examples 1.$ SAVE_PROC_VERIFY = F$ENVIRONMENT("VERIFY_PROCEDURE") $ SAVE_IMAGE_VERIFY = F$ENVIRONMENT("VERIFY_IMAGE") $ SET NOVERIFY . . . $ TEMP = F$VERIFY(SAVE_PROC_VERIFY, SAVE_IMAGE_VERIFY) This example shows an excerpt from a command procedure. The first assignment statement assigns the current procedure verification setting to the symbol SAVE_PROC_VERIFY. The second assignment statement assigns the current image verification setting to the symbol SAVE_IMAGE_VERIFY. Then, the SET NOVERIFY command disables procedure and image verification. Later, the F$VERIFY function resets the verification settings, using the original values (equated to the symbols SAVE_PROC_VERIFY and SAVE_IMAGE_VERIFY). The symbol TEMP contains the procedure verification before it is changed with the F$VERIFY function. (In this example, the value of TEMP is not used.) 2.$ VERIFY = F$VERIFY(0) . . . $ IF VERIFY .EQ. 1 THEN SET VERIFY This example shows an excerpt from a command procedure that uses the F$VERIFY function to save the current procedure verification setting and to turn both procedure and image verification off. At the end of the command procedure, if procedure verification was originally on, both the procedure and image verification are turned on.