Associates an equivalence name with a logical name.

Format

DEFINE logical-name equivalence-name[,...]

Parameters

logical-name

Specifies the logical name string, which is a character string containing from 1 to 255 characters. The following rules apply:

• If the logical name is to be entered into the process or system directory logical name tables (LNM$PROCESS_DIRECTORY, LNM$SYSTEM_DIRECTORY), then the name can only have from 1 to 31 alphanumeric characters, including the dollar sign ($) and underscore (_). If the logical name translates to a logical name table name, any alphabetic characters in the name should all be uppercase.
• If you specify a colon (:) at the end of a logical name, the DEFINE command saves the colon as part of the logical name. (This is in contrast to the ASSIGN command, which removes the colon before placing the name in a logical name table.) By default, the logical name is placed in the process logical name table.
• If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks (" "). Use two sets of quotation marks ("" "") to denote actual quotation marks. When you enclose a name in quotation marks, the case of alphabetic characters is preserved.

equivalence-name[,...]

Specifies a character string containing from 1 to 255 characters. The following rules apply:

• If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks. Use two sets of quotation marks to denote an actual quotation mark. Specifying more than one equivalence name for a logical name creates a search list. A logical name can have a maximum of 128 equivalence names.
• When you specify an equivalence name that will be used as a file specification, you must include the punctuation marks (colons, brackets, periods) that would be required if the equivalence name were used directly as a file specification. Therefore, if you specify a device name as an equivalence name, you must terminate the equivalence name with a colon.

The DEFINE command allows you to assign multiple equivalence names to a single logical name. For example, you can use the same logical name to access different directories on different disks or to access different files in different directories.

Description

The DEFINE command creates a logical name that represents one or more equivalence names. An equivalence name can be a device name, another logical name, a file specification, or any other string.

You can limit the use of a logical name to a process, a job, a group, an entire system, or an entire OpenVMS Cluster system. How you use a logical name depends on the table you created in it. You can specify a table with one of the following qualifiers: /PROCESS, /JOB, /GROUP, /SYSTEM, or /TABLE.

The first four qualifiers represent the process, job, group, or system logical name tables, respectively, whereas the /TABLE qualifier is used to specify any type of table. Furthermore, the /TABLE qualifier is the only one to use when specifying a clusterwide logical name table.

If you enter more than one of the qualifiers, only the last one entered is accepted. If you do not specify a table with one of the qualifiers, the logical name is added to your process logical name table.

To specify the access mode of the logical name you are creating, use the /USER_MODE, the /SUPERVISOR_MODE, or the /EXECUTIVE_MODE qualifier. If you enter more than one of these qualifiers, only the last one entered is accepted. If you do not specify an access mode, a supervisor-mode name is created. You can create a logical name in the same mode as the table in which you are placing the name, or in an outer mode. (User mode is the outermost mode; executive mode is the innermost mode.)

You can enter more than one logical name with the same name in the same table, as long as each name has a different access mode. (However, if an existing logical name within a table has the NO_ALIAS attribute, you cannot use the same name to create a logical name in an outer mode in this table.)

If you create a logical name with the same name, in the same table, and in the same mode as an existing name, the new logical name assignment replaces the existing assignment.

You can also use the ASSIGN command to create logical names. To delete a logical name from a table, use the DEASSIGN command.

Note Avoid assigning a logical name that matches the file name of an executable image in SYS$SYSTEM:. Such an assignment prohibits you from invoking that image.

To create a logical name with no equivalence name (and therefore no indices), use the $CRELNM system service.

If you want to specify an ODS-5 file name as an equivalence name, see the HP OpenVMS System Manager's Manual, Volume 1: Essentials.

For a complete description of logical names and logical name tables, except for their use in applications, see the OpenVMS User's Manual. For the use of logical names in applications, see the HP OpenVMS Programming Concepts Manual. For managing clusterwide logical names, see the HP OpenVMS Cluster Systems manual. In this manual, see also the description of the lexical function F$TRNLNM, which is used to translate logical names.

Qualifiers

/CLUSTER_SYSTEM

You must be signed in to the SYSTEM account or have SYSNAM (system logical name) or SYSPRV (system) privilege to use this qualifier.

Defines a clusterwide logical name in the LNM$SYSCLUSTER table.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege to create an executive-mode logical name.

Creates an executive-mode logical name in the specified table.

If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM privilege, the DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.

/GROUP

Requires GRPNAM (group logical name) or SYSNAM (system logical name) privilege to place a name in the group logical name table.

Places the logical name in the group logical name table. Other users who have the same group number in their user identification codes (UICs) can access the logical name. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.

/JOB

Places the logical name in the jobwide logical name table. All processes in the same job tree as the process that created the logical name can access the logical name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier.

/LOG (default)

/NOLOG

Displays a message when a new logical name supersedes an existing name.

/NAME_ATTRIBUTES[=(keyword[,...])]

Specifies attributes for a logical name. By default, no attributes are set. Possible keywords are as follows:

CONFINE	The logical name is not copied into a spawned subprocess. This qualifier is relevant only for logical names in a private table. The logical name inherits the CONFINE attribute from the logical name table where it is entered; if the logical name table is "confined," then all names in the table are "confined."
NO_ALIAS	A logical name cannot be duplicated in the specified table in a less privileged access mode; any previously created identical names in an outer (less privileged) access mode within the specified table are deleted.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.

/PROCESS (default)

Places the logical name in the process logical name table. The /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.

/SUPERVISOR_MODE (default)

Creates a supervisor-mode logical name in the specified table. The mode of the logical name must be the same as or less privileged than the mode of the table in which you are placing the name.

/SYSTEM

Requires write (W) access or SYSNAM (system logical name) privilege to place a name in the system logical name table.

Places the logical name in the system logical name table. All system users can access the logical name. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.

/TABLE=name

Requires write (W) access to the table to specify the name of a shareable logical name table.

Specifies the name of the logical name table in which the logical name is to be entered. You can use the /TABLE qualifier to specify a user-defined logical name table (created with the CREATE/NAME_TABLE command); to specify the process, job, group, system, or clusterwide logical name tables; or to specify the process or system logical name directory tables.

If you specify the table name using a logical name that has more than one translation, the logical name is placed in the first table found. For example, if you specify DEFINE/TABLE=LNM$FILE_DEV and LNM$FILE_DEV is equated to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the logical name is placed in LNM$PROCESS.

The default is the /TABLE=LNM$PROCESS qualifier.

/TRANSLATION_ATTRIBUTES[=(keyword[,...])]

Equivalence-name qualifier.

Specifies one or more attributes that modify an equivalence string of the logical name. Possible keywords are as follows:

CONCEALED	Indicates that the equivalence string is the name of a concealed device. When a concealed device name is defined, the system displays the logical name, rather than the equivalence string, in messages that refer to the device.
TERMINAL	Logical name translation should terminate with the current equivalence string; indicates that the equivalence string should not be translated iteratively.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.

Note that different equivalence strings of a logical name can have different translation attributes.

/USER_MODE

Creates a user-mode logical name in the specified table.

User-mode logical names created within the process logical name tables are used for the execution of a single image; for example, you can create a user-mode logical name to allow an image executing in a command procedure to redefine SYS$INPUT. User-mode entries are deleted from the process logical name table when any image executing in the process exits (that is, after a DCL command or user program that executes an image completes execution). Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

Examples

$ DEFINE/USER_MODE TM1 $DISK1:[ACCOUNTS.MEMOS]WATER.TXT
      

In this example, the DEFINE command defines TM1 as equivalent to a file specification. After the next image runs, the logical name TM1 is automatically deassigned.

$ DEFINE CHARLIE XXX1:[CHARLES]
$ PRINT  CHARLIE:TEST.DAT
Job 274 entered on queue SYS$PRINT
      

In this example, the DEFINE command associates the logical name CHARLIE with the directory name [CHARLES] on the disk XXX1. The PRINT command queues a copy of the file XXX1:[CHARLES]TEST.DAT to the system printer.

$ DEFINE PROCESS_NAME  LIBRA
$ RUN WAKE
      

In this example, the DEFINE command places the logical name PROCESS_NAME in the process logical name table with an equivalence name of LIBRA. The logical name is created in supervisor mode. The program WAKE translates the logical name PROCESS_NAME to perform some special action on the process named LIBRA.

$ DEFINE TEMP:  XXX1:
   .
   .
   .
$ DEASSIGN TEMP::
      

In this example, the DEFINE command creates an equivalence name for the logical name TEMP: and places the name in the process logical name table. The colon is retained as part of the logical name. The DEASSIGN command deletes the logical name. Note that two colons are required on the logical name in the DEASSIGN command. One colon is deleted by the DEASSIGN command. The other colon is kept as part of the logical name.

$ DEFINE PORTLAND PRTLND::YYY0:[DECNET.DEMO.COM]
      

In this example, the DEFINE command places the logical name PORTLAND in the process logical name table with an equivalence name of PRTLND::YYY0:[DECNET.DEMO.COM]. Subsequent references to the logical name PORTLAND result in the correspondence between the logical name PORTLAND and the node, disk, and subdirectory specified.

$ DEFINE LOCAL "BOSTON""JAY_SABLE JKS""::"
      

In this example, the DEFINE command places the logical name LOCAL in the process logical name table with a remote node equivalence name of BOSTON"JAY_SABLE JKS"::. To satisfy conventions for local DCL command string processing, you must use three sets of quotation marks. The quotation marks ensure that access control information is enclosed in one set of quotation marks in the equivalence name.

$ DEFINE MYDISK XXX0:[MYDIR], YYY0:[TESTDIR]
      

In this example, the DEFINE command places the logical name MYDISK in the process logical name table with two equivalence names: XXX0:[MYDIR] and YYY0:[TESTDIR].

$ DEFINE/TABLE=LNM$CLUSTER_TABLE FIRENZE FIRENZE::FIESOLE:[ETRUSCAN]
      

In this example, the DEFINE command equates FIRENZE to the directory specification FIRENZE::FIESOLE:[ETRUSCAN] and places both the new logical name (FIRENZE) and its equivalence string (FIRENZE::FIESOLE:[ETRUSCAN]) in the default clusterwide table. The new logical name is automatically propagated to all nodes in the cluster.

$  CREATE/NAME_TABLE TABLE1 
$  DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV - 
_$ TABLE1,LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM 
$  DEFINE/TABLE=TABLE1 - 
_$ /TRANSLATION_ATTRIBUTES=CONCEALED   WORK_DISK DKA1: 
      

In this example, the CREATE/NAME_TABLE command creates the process private logical name table TABLE1.

The first DEFINE command ensures that TABLE1 is searched first in any logical name translation of a device or file specification (because TABLE1 is the first item in the equivalence string for the logical name LNM$FILE_DEV, which determines the default search sequence of logical name tables whenever a device or file specification is translated).

The second DEFINE command assigns the logical name WORK_DISK to the physical device DKA1 and places the name in TABLE1. The logical name has the concealed attribute. Therefore, the logical name WORK_DISK is displayed in system messages.

$ CREATE/NAME_TABLE SPECIAL
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV -
_$ SPECIAL,LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY TAB SPECIAL
$ DEFINE/TABLE=TAB REPORT [CHELSEA]STORES
$ SHOW LOGICAL/TABLE=SPECIAL REPORT
  "REPORT" = "[CHELSEA]STORES" (SPECIAL)
 
      

In this example, the CREATE/NAME_TABLE command is used to create a new logical name table called SPECIAL. This table is defined in the process directory, LNM$PROCESS_DIRECTORY.

The first DEFINE command ensures that SPECIAL is searched first in any logical name translation of a device or file specification (because SPECIAL is the first item in the equivalence string for the logical name LNM$FILE_DEV, which determines the default search sequence of logical name tables whenever a device or file specification is translated). The logical name LNM$FILE_DEV is placed in the process directory, LNM$PROCESS_DIRECTORY.

With the next DEFINE command, a new logical name, TAB, is defined. TAB translates to the string SPECIAL, which identifies a logical name table. You must define TAB in the process directory because it translates iteratively to a logical name table.

Next, the logical name REPORT is placed into the logical name table TAB. Because TAB translates to the table SPECIAL, the name REPORT is entered into SPECIAL table. The SHOW LOGICAL command verifies that the name REPORT has been entered into the table SPECIAL.

Note that you can redefine TAB so it translates to a different table. Therefore, if you run different programs that use the name TAB as a table name, you can change the actual tables where the names are entered or referenced.