 |
HP OpenVMS DCL Dictionary
DEFINE
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, refer
to 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, refer to the OpenVMS User's Manual. For
the use of logical names in applications, refer to the HP OpenVMS Programming Concepts Manual.
For managing clusterwide logical names, refer to 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
| #1 |
$ 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.
| #2 |
$ 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.
| #3 |
$ 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.
| #4 |
$ 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.
| #5 |
$ 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.
| #6 |
$ 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.
| #7 |
$ 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].
| #8 |
$ 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.
| #9 |
$ 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.
| #10 |
$ 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.
|
