HP OpenVMS Systems Documentation
HP OpenVMS Programming Concepts Manual
|System Service||Meaning||DCL Command||Meaning|
|SYS$CRELNM||Create Logical Name||ALLOCATE||Optionally associates a logical name with a device|
|ASSIGN||Creates a logical name and assigns an equivalence string to a specific logical name|
|DEFINE||Associates an equivalence name with a logical name|
|MOUNT||Allows the optional naming of a logical name for a disk or magnetic tape volume|
|SYS$CRELNT||Create Logical Name Table||CREATE/NAME_TABLE||Creates a new logical name table|
|SYS$DELLNM||Delete Logical Name||DEASSIGN||Cancels a logical name assignment|
|SYS$TRNLNM||Translate Logical Name||SHOW LOGICAL||Displays translations and the logical name table for a specified logical name|
|SHOW TRANSLATION||Displays the first translation found for the specified logical name|
The following sections describe various concepts you should be aware of
when you use the logical name system services. For further discussion
of logical names, see the OpenVMS User's Manual.
34.1.1 Logical Names, Equivalence Names, and Search Lists
A logical name is a user-specified character string that can represent a file specification, device name, logical name table name, application-specific information, or another logical name. Typically, for process-private purposes, you specify logical names that are easy to use and to remember. System managers and privileged users choose mnemonics for files, system devices, and search lists that are frequently accessed by all users.
An equivalence string, or an equivalence name, is a character string that denotes the actual file specification, device name, or character string. An equivalence name can also be a logical name. In this case, further translation is necessary to reveal the actual equivalence name.
A multivalued logical name, commonly called a search list, is a logical name that has more than one equivalence string. Each equivalence string in the search list is assigned an index number starting at zero. A logical name can have a maximum of 128 equivalence names.
Logical names and their equivalence strings are stored in logical name tables. Logical names can have a maximum length of 255 characters. Equivalence strings can have a maximum of 255 characters. You can establish logical name and equivalence string pairs as follows:
For example, you could use the symbolic name TERMINAL to refer to an output terminal in a program. For a particular run of the program, you could use the DEFINE command to establish the equivalence name TTA2.
To create a logical name in a program, you must define character-string
descriptors for the name strings and call the system service within
34.1.2 Logical Name Tables
A logical name table contains logical name and equivalence string pairs. Each table is an independent name space. When you translate a logical name, you specify the table containing the name. A logical name table is referred to by its name, which is itself a logical name, or by another logical name that translates into the table name.
Logical name tables can be created in process space or in system space. Tables created in process space are accessible only by that process. Tables created in system space are potentially shareable among many processes. OpenVMS creates a number of logical name tables with specific characteristics. These predefined logical name tables have names beginning with the prefix LNM$.
Logical name and equivalence name pairs are maintained in three types of logical name tables:
Because the names of logical name tables are logical names, table names must reside in logical name tables. Two special tables called directories exist for this purpose. Table names are translated from these logical name directory tables. Logical name and equivalence name pairs for logical name tables are maintained in the following two directory tables:
The process directory table contains the names of all process-private user-defined logical name tables created through the SYS$CRELNT system service. In addition, the process directory table contains system-assigned logical name table names and the name of the process logical name table LNM$PROCESS_TABLE.
The system directory table contains the names of potentially shareable logical name tables and system-assigned logical name table names. Typically, you must have the SYSPRV privilege to create a logical name in the system directory table. For a discussion of privileges, see Section 34.3.
Logical names other than logical name table names can exist within
these tables, but are strongly discouraged. The length of the logical
names and table names created in either of these tables must not exceed
31 characters. Logical table names and logical names created in the
directory tables must consist of uppercase alphanumeric characters,
dollar signs ($), and underscores (_). Equivalence strings must not
exceed 255 characters.
220.127.116.11 Process, Job, Group, System and Clusterwide Default Logical Name Tables
OpenVMS creates a number of logical name tables automatically, some at system initialization and some at process creation. Some of these tables are accessible to all processes, and some are accessible only to selected processes. These tables are called the default logical name tables.
Each default logical name table has a logical name associated with it in addition to its table name. The default logical name table names and the common logical names used to refer to them are as follows:
|Job||LNM$JOB_ xxxxxxxx 1||LNM$JOB|
|Group||LNM$GROUP_ gggggg 2||LNM$GROUP|
|Clusterwide system table||LNM$SYSCLUSTER_TABLE||LNM$SYSCLUSTER|
|Clusterwide parent table||LNM$CLUSTER_TABLE||LNM$CLUSTER|
The length of the logical names created in these tables cannot exceed
255 characters, with no restriction on the types of characters used.
Equivalence strings cannot exceed 255 characters. By convention, an
HP-created logical name begins with a facility-specific prefix,
followed by a dollar sign ($) and a name within that facility. You are
strongly encouraged to define logical names without the dollar sign ($)
to avoid inadvertent conflicts.
18.104.22.168.1 Process Logical Name Table
The process logical name table LNM$PROCESS_TABLE contains names used exclusively by the process. A process logical name table exists for each process in the system. Some entries in the process logical name table are made by system programs executing at more privileged access modes; these entries are qualified by the access mode from which the entry was made. The process logical name table contains the following process-permanent logical names:
|SYS$INPUT||Default input stream|
|SYS$OUTPUT||Default output stream|
|SYS$COMMAND||Original first-level (SYS$INPUT) input stream|
|SYS$ERROR||Default device to which the system writes error messages|
SYS$COMMAND is created only for processes that execute LOGINOUT.
Usually, you create logical names only in your process logical name table. Most entries in the process logical name table are made in user or supervisor mode.
Process logical names that are created in user mode are deleted whenever the creating process runs an image down. The following DCL commands illustrate this behavior with supervisor mode and /TABLE=LNM$PROCESS as the defaults (default mode and default table) for the DEFINE command:
$ DEFINE/USER ABC XYZ $ SHOW TRANSLATION ABC ABC = XYZ $ DIRECTORY . . . $ SHOW LOGICAL ABC ABC = (undefined)
The DCL command DIRECTORY performs image rundown when it is finished
operating. At that time, all user-mode process-private logical names
are deleted, including the logical name ABC.
22.214.171.124.2 Job Logical Name Table
The job logical name table is a shareable table that is accessible by all processes within the same job tree. Whenever a detached process is created, a job logical name table is created for this process and for all of its potential subprocesses. At the same time, the process-private logical name LNM$JOB is created in the process directory logical name table LNM$PROCESS_DIRECTORY. The logical name LNM$JOB translates to the name of the job logical name table.
Because the job logical name table already exists for the main process, only the process-private logical name LNM$JOB is created when a subprocess is created.
The job logical name table contains the following three process-permanent logical names for processes that execute LOGINOUT:
|SYS$LOGIN||Original default device and directory|
|SYS$LOGIN_DEVICE||Original default device|
|SYS$SCRATCH||Default device and directory to which temporary files are written|
Instead of creating these logical names within the process logical name table LNM$PROCESS_TABLE for every process within a job tree, LOGINOUT creates these logical names once when it is executed for the process at the root of the job tree.
Additionally, the job logical name table can contain the following logical names:
The group logical name table contains names that cooperating processes in the same group can use. You need the GRPNAM privilege to add or delete a logical name in the group logical name table. For a discussion of privileges, see Section 34.3.
A group logical name table is created when a top-level process with a
unique group code is created. The logical name LNM$GROUP exists in each
process's process directory LNM$PROCESS_DIRECTORY. This logical name
translates into the name of the group logical name table.
126.96.36.199.4 System Logical Name Table
The system logical name table LNM$SYSTEM_TABLE contains names that all processes in the system can access. This table includes the default names for all system-assigned logical names. You need the SYSNAM or SYSPRV privilege to add or delete a logical name in the system logical name table. For a discussion of privileges, see Section 34.3.
The system logical table contains system-assigned logical names accessible to all processes in the system. For example, the logical names SYS$LIBRARY and SYS$SYSTEM provide logical names that all users can access to use the device and directory that contain system files.
|Logical Name||Equivalence Name|
The Logical Names section of the OpenVMS User's Manual contains a list of
these system-assigned logical names.
188.8.131.52.5 Clusterwide Logical Name Table
The clusterwide system logical name table LNM$SYSCLUSTER_TABLE contains names that all processes in the cluster can access. This is the clusterwide table that contains system logical names. Because this table exists on all systems, the programs and command procedures that use clusterwide logical names are transportable to both clustered and nonclustered systems. The names in this table are available to anyone translating a logical name using SHOW LOGICAL/SYSTEM and specifying a table name of LNM$SYSTEM, or LNM$DCL_LOGICAL (DCL's default table search list), or LNM$FILE_DEV (system and RMS default).
LNM$SYSCLUSTER is the logical name for LNM$SYSCLUSTER_TABLE. It is provided for convenience in referencing LNM$SYSCLUSTER_TABLE and it is consistent in format with LNM$SYSTEM_TABLE and its logical name, LNM$SYSTEM.
You need either the SYSNAM or SYSPRV privilege or write access to the table to create or delete a name in this table.
The definition of LNM$SYSTEM has been expanded to include LNM$SYSCLUSTER. When a system logical name is translated, the search order is LNM$SYSTEM_TABLE, LNM$SYSCLUSTER.
The clusterwide logical name table LNM$CLUSTER_TABLE is the parent table for all logical names, including LNM$SYSCLUSTER_TABLE. When you create a new table using LNM$CLUSTER_TABLE as the parent table, the new table will be available clusterwide.
LNM$CLUSTER is the logical name for LNM$CLUSTER_TABLE. It is provided for convenience in referencing LNM$CLUSTER_TABLE.
You need either the SYSPRV privilege or write access to the table to create or delete a name in this table.
Logical names in these two tables and their descendant tables are clusterwide. Creation and deletion of cluster wide logical names are replicated on other nodes of the cluster. Creation and deletion of clusterwide logical name tables are replicated on other nodes of the cluster. When a node boots into a cluster, it receives the current set of clusterwide logical names.
LNM$SYSCLUSTER_TABLE and LNM$CLUSTER_TABLE are created on all systems,
regardless of whether they are cluster nodes. Their existence enables
OpenVMS to maintain a consistent application environment.
34.1.3 Logical Name Table Names and Search Lists
The process, job, group, and system tables are typically referred to indirectly. For example, the process table is usually specified as LNM$PROCESS. This indirect reference enables you to redefine LNM$PROCESS as multiple equivalence names and thus include one or more of your own tables in it.
The system table is specified as LNM$SYSTEM. The logical name LNM$SYSTEM is defined as LNM$SYSTEM_TABLE, LNM$SYSCLUSTER. Thus, it includes both systemwide names specific to the node and systemwide names common to all nodes in the cluster. When a system name is translated, the search order is LNM$SYSTEM_TABLE, LNM$SYSCLUSTER.
As described in the OpenVMS User's Manual, OpenVMS automatically defines a number of logical names, some of which are names of logical name tables. In addition to the table names in the table in Section 184.108.40.206, OpenVMS defines LNM$FILE_DEV and LNM$DCL_LOGICAL.
RMS and other system components specify the table LNM$FILE_DEV for file specification and device name translations. Its definition is LNM$PROCESS, LNM$JOB, LNM$GROUP, LNM$SYSTEM. Thus, the precedence order for resolving logical names using this search list is as follows:
The table name LNM$DCL_LOGICAL is used for the SHOW LOGICAL and SHOW
TRANSLATION DCL commands and for the logical name lexical functions.
Its definition is LNM$FILE_DEV.
34.1.4 Specifying the Logical Name Table Search List
Logical names exist as entries within logical name tables. When a logical name is to be created, deleted, or translated, you must specify or take the default name that designates the logical name table that contains the logical name. This name possesses one or more of the following characteristics:
As mentioned in Section 34.1.2, predefined logical names exist for certain logical name tables. These predefined names begin with the prefix LNM$. You can redefine these names to modify the search order or the tables used.
Instead of a fixed set of logical name tables and a rigidly defined order (process, job, group, system) for searching those tables, you can specify which tables are to be searched and the order in which they are to be searched. Logical names in the directory tables are used to specify this searching order. By convention, each class of logical name (for example, device or file specification) uses a particular predefined name for this purpose.
For example, LNM$FILE_DEV is the logical name that defines the list of logical name tables used whenever file specifications or device names are translated by OpenVMS RMS or the I/O services. LNM$FILE_DEV is the default for file specifications and device names. This name must translate to a list of one or more logical name table names that specify the tables to be searched when translating file specifications.
By default, LNM$FILE_DEV specifies that the process, job, group, and system tables are all searched, in that order, and that the first match found is returned.
Logical name table names are translated from two tables: the process logical name directory table LNM$PROCESS_DIRECTORY and the system logical name directory table LNM$SYSTEM_DIRECTORY. The LNM$FILE_DEV logical name table must be defined in one of these tables.
Thus, if identical logical names exist in the process and group tables, the process table entry is found first, and the job and group tables are not searched. When the process logical name table is searched, the entries are searched in order of access mode, with user-mode entries matched first, supervisor-mode entries second, and so on.