Document revision date: 19 July 1999

When you use the F$TRNLNM function, you can omit optional arguments that can be used to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument that you specify.

You can use the F$TRNLNM function in command procedures to save the current equivalence of a logical name and later restore it. You can also use it to test whether logical names have been assigned.

Examples

$ 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.

$ 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.

$ 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.

$ 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.

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

This example specifies both case sensitive and interlocked translation.

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)

Return Value

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 Table DCLI-14.

Table DCLI-14 Context Symbol Types

Symbol Type	Lexical Creating Symbol
PROCESS_CONTEXT	F$PID or F$CONTEXT (with PROCESS context type)
CLUSTER_SYSTEM_CONTEXT	F$CSID

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.

Argument

symbol-name

Specifies the name of the symbol to be evaluated.

Examples

$ 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.

$ 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.

$ 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.

$ 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.

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()

Return Value

Arguments

None.

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.

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])

Return Value

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.

Description

The lexical function 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.

Using the F$VERIFY function in command procedures allows you to test the current procedure verification setting. For example, a command procedure can save the current procedure verification setting before changing it and then later restore the setting. In addition, you can construct a procedure that does not display (or print) commands, regardless of what the initial state of verification is.

When you use the F$VERIFY function, you can specify zero, one, or two arguments. If you do not specify any arguments, neither of the verification settings is changed. If you specify only the procedure-value argument, both procedure and image verification are turned on (if the value is 1) or off (if the value is 0).

If you specify both arguments, procedure and image verification are turned on or off independently. If you specify the image-value argument alone, only image verification is turned on or off. If you specify the image-value argument alone, you must precede the argument with a comma (,).

You can also use the F$ENVIRONMENT function with VERIFY_PROCEDURE or VERIFY_IMAGE as the argument. With the F$ENVIRONMENT function, you can determine either the procedure or image verification setting; the F$VERIFY function determines only the procedure verification setting.

DCL performs the F$VERIFY function even if it appears after a comment character, if it is enclosed in single quotation marks (` '). This is the only processing that DCL performs within a comment.

Examples

$ 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.)

$ 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.

Invokes the Librarian utility, which creates, modifies, or describes an object, macro, help, text, or shareable image library.

For more information about the Librarian utility, refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual or online help.

Format

LIBRARY library-filespec [input-filespec[,...]]

Invokes the License Management utility, which manages software licenses on the OpenVMS operating system.

For more information about the License Management utility, refer to the OpenVMS License Management Utility Manual or online help.

Format

LICENSE subcommand parameter

Invokes the OpenVMS Linker, which links one or more object modules into a program image and defines execution characteristics of the image.

For more information about the linker, including more information about the LINK command, refer to the OpenVMS Linker Utility Manual or online help.

Format

LINK filespec[,...]

Initiates an interactive terminal session.

Format

[Ctrl/C]

[Ctrl/Y]

[Return]

Description

There is no LOGIN command. You signal your intention to access the system by pressing the Return Key, Ctrl/C, or Ctrl/Y, on a terminal not currently in use. The system prompts for your user name and your password (and your secondary password, if you have one) and then validates them.

Specify the optional qualifiers immediately after you type your user name; then press the Return key to get the password prompts.

The login procedure performs the following functions:

• Validates your right to access the system by checking your user name and passwords against the entries in the system's user authorization file (UAF).
• Establishes the default characteristics of your terminal session based on your user name entry in the UAF.
• Executes the command procedure file SYS$SYLOGIN.COM if one exists.
• Executes either the command procedure file named LOGIN.COM if one exists in your default directory, or the command file defined in the UAF, if any.

Some systems are set up with a retry facility for users who are accessing the system from remote or dialup locations. With these systems, when you make a mistake typing your user name or password, the system allows you to reenter the information. To reenter your login information, press the Return key. The system displays the user name prompt again. Now retype your user name and press the Return key to send the information to the system. The system displays the password prompt. (There is both a limit to the number of times you can retry to enter your login information and a time limit between tries.)

Qualifiers

/CLI=command-language-interpreter

Specifies the name of an alternate command language interpreter (CLI) to override the default CLI listed in the UAF. The CLI you specify must be located in SYS$SYSTEM and have the file type .EXE.

If you do not specify a command interpreter by using the /CLI qualifier and you do not have a default CLI listed in the UAF, the system supplies the qualifier /CLI=DCL by default.

/COMMAND[=filespec] (default)

/NOCOMMAND

Controls whether to execute your default login command procedure when you log in. Use the /COMMAND qualifier to specify the name of an alternate login command procedure. If you specify a file name without a file type, the default file type .COM is used. If you specify the /COMMAND qualifier and omit the file specification, your default login command procedure is executed.

Use the /NOCOMMAND qualifier if you do not want your default login command procedure to be executed.

/DISK=device-name[:]

Specifies the name of a disk device to be associated with the logical device SYS$DISK for the terminal session. This specification overrides the default SYS$DISK device established in the UAF.

/NEW_PASSWORD

Requires that you change the account password before logging in (as if the password had expired). Use this qualifier as a shortcut if you had intended to change your password after login, or if you suspect that your password has been detected.

/TABLES=(command-table[,...])

/TABLES=DCLTABLES (default)

Specifies the name of an alternate CLI table to override the default listed in the UAF. This table name is considered a file specification. The default device and directory is SYS$SHARE and the default file type is EXE.

If a logical name is used, the table name specification must be defined in the system logical name table.

If the /CLI qualifier is set to DCL or MCR, the /TABLES qualifier defaults to the correct value. If the /TABLES qualifier is specified without the /CLI qualifier, the CLI specified in the user's UAF will be used.

Examples

 [Ctrl/Y]
Username:  MACKRILL
Password:  <PASSWORD>
      

In this example, pressing Ctrl/Y allows you to access the operating system, which immediately prompts for a user name. After validating the user name, the system prompts for the password but does not echo it.

 [Return]                            
Username:  HIGGINS/DISK=USER$
Password: <PASSWORD>
Welcome to OpenVMS Alpha (TM) Operating System, Version 7.2 on node LSR
    Last interactive login on Tuesday, 18-DEC-1998 08:41
    Last non-interactive login on Monday, 19-DEC-1998 15:43
 
      

In this Alpha example, the /DISK qualifier requests that the default disk for the terminal session be USER$. The SHOW DEFAULT command shows that USER$ is the default disk.

 [Return]                            
Username:  HIGGINS/DISK=USER$
Password: <PASSWORD>
       Welcome to OpenVMS VAX Version 7.2 on node SATURN
       Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
       Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
$ SHOW DEFAULT
  USER$:[HIGGINS]
 
      

In this VAX example, the /DISK qualifier requests that the default disk for the terminal session be USER$. The SHOW DEFAULT command shows that USER$ is the default disk.

 [Ctrl/C]
Username: LIZA/CLI=MCR/COMMAND=ALTLOGIN.COM
Password: <PASSWORD>
       Welcome to OpenVMS VAX Version 7.2 on node SATURN
       Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
       Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
>
 
      

In this example, the /CLI qualifier requests the alternate MCR command interpreter. The /COMMAND qualifier indicates that the login command file ALTLOGIN.COM is to be executed instead of the default login command file.

The right angle-bracket prompt (>) indicates that MCR is active and expects an MCR command.

 [Return]
Username: XENAKIS
Password: <PASSWORD>
Password: <PASSWORD>
       Welcome to OpenVMS VAX Version 7.2 on node SATURN
       Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
       Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
$
 
      

In this example, the second password prompt indicates that the user has a secondary password, which must be entered to access the system.

 [Return]
Username: JONES
Password: <PASSWORD>
User authorization failure
 [Return]
Username: JONES
Password: <PASSWORD>
Welcome to OpenVMS Alpha (TM) Operating System, Version 7.2 on node LSR
        Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
        Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
        1 failure since last successful login.
$
 
      

This example shows the "User authorization failure" message, which indicates that the password has been entered incorrectly. After you successfully log in, a message is displayed showing the number of login failures since your last successful login. This message is displayed only if login failures have occurred.

 [Return]
Username: JOYCE
Password: <PASSWORD>
Welcome to OpenVMS Alpha (TM) Operating System, Version 7.2 on node LSR
       Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
       Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
       WARNING - Primary password has expired; update immediately.
$
 
      

This example shows the WARNING message, which indicates that your primary password has expired. You must use the SET PASSWORD command to change your password before logging out, or you will be unable to log in again.

For more information on changing your password, see the description of the SET PASSWORD command in this manual.

 [Return]
Username: MIHALY/NEW_PASSWORD
Password: <PASSWORD>
Password: <PASSWORD>
      Welcome  to OpenVMS VAX Version 7.2 on node SATURN
      Last interactive login on Tuesday, 15-DEC-1998 09:16:47.08
      Last non-interactive login on Monday, 14-DEC-1998 17:32:34.27
      Your password has expired; you must set a new password to log in.
          Old password: <PASSWORD>
          New password: <PASSWORD>
          Verification: <PASSWORD>
 
      

In this example, the user enters the /NEW_PASSWORD qualifer after the user name MIHALY. The system then forces the user to set a new password immediately after login. The prompts are the same as those provided when you enter the DCL command SET PASSWORD from the command line.

	privacy and legal statement
9996PRO_036.HTML