Updated: 11 December 1998

OpenVMS Programming Concepts Manual

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:

Logical Name	Meaning
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 logical name optionally specified and associated with a newly created temporary mailbox
• The logical name optionally specified and associated with a privately mounted volume

You do not need special privileges to modify the job logical name table. For a discussion of privileges, see Section 12.3.

12.1.2.2.3 Group Logical Name Table

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

12.1.2.2.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 12.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
SYS$LIBRARY	SYS$SYSROOT:[SYSLIB]
SYS$SYSTEM	SYS$SYSROOT:[SYSEXE]
...	...
...	...
...	...

The Logical Names section of the OpenVMS User's Manual contains a list of these system-assigned logical names.

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

12.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 12.1.2.2, 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:

process-->job-->group-->system-->clusterwide system

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.

12.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:

• It is the name of a logical name table.
• It is a logical name that iteratively translates in the process or system directory table to the name of a logical name table.
• It is a multivalued logical name (search list) that iteratively translates to the names of several logical name tables. The tables are used in the order in which they appear.

As mentioned in Section 12.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.

If you want to change the list of tables used for device and file specifications, you can redefine LNM$FILE_DEV in the process directory table LNM$PROCESS_DIRECTORY.

12.2 Creating User-Defined and Clusterwide Logical Name Tables

You can create process-private tables and shareable tables by calling the SYS$CRELNT system service in a program, or with the DCL command CREATE/NAME_TABLE. However, to create a shareable table you must have create (C) access to the parent table and either SYSPRV privilege or write (W) access to LNM$SYSTEM_DIRECTORY. If granted access, processes other than the creating process can use shareable tables. For a discussion of privileges, see Section 12.3. Processes other than the creating process cannot use logical names contained in process-private tables.

You can assign protection to these shareable tables through the promsk argument of the SYS$CRELNT system service. The promsk argument allows you to specify the type of access for system, owner, group, and world users, as follows:

• Read privileges allow access to names in the logical name table.
• Write privileges allow creation and deletion of names within the logical name table.
• Delete privileges allow deletion of the logical name table.
• Create privilege to a table allows creation of children tables.

You can apply the following types of ownership and access to a shareable logical name table:

• OWNERSHIP: SYSTEM(S), GROUP(G), or WORLD(W)
• ACCESS: READ(R), WRITE(W), CREATE(C), or DELETE(D)

If the promsk argument is omitted, complete access is granted to system and owner, and no access is granted to group and world.

When a shareable table is created, both the specified promsk argument and the current default security profile for tables are applied.

In addition, you can specify finer-grained access rights by modifying the access control list using either the DCL command SET SECURITY or the SYS$SET_SECURITY system service. For more information, see Chapter 25 and OpenVMS Guide to System Security.

The length of logical names created in user-defined logical name tables cannot exceed 255 characters. Equivalence strings cannot exceed 255 characters.

12.2.1 Creating Clusterwide Logical Name Tables

You might want to create additional clusterwide logical name tables for the following purposes:

• For use by a multiprocess clusterwide applications
• For sharing by members of a UIC group

You can create additional clusterwide logical name tables in the same way that you can create additional process, job, and group logical name tables---with the CREATE/NAME_TABLE command or with the $CRELNT system service. When creating a clusterwide logical name table, you must specify the /PARENT_TABLE qualifier and provide a value for the qualifier that is a clusterwide name. Any existing clusterwide table used as the parent table will make the new table clusterwide.

The following example shows how to create a clusterwide logical name table:

$ CREATE/NAME_TABLE/PARENT_TABLE=LNM$CLUSTER_TABLE - _$ new_clusterwide_logical_name_table

To create clusterwide logical names that will reside in the clusterwide logical name table you created, you define the new clusterwide logical name with the DEFINE command, specifying your new clusterwide table's name with the /TABLE qualifier, as shown in the following example:

$ DEFINE/TABLE=new_clusterwide_logical_name_table logical_name - _$ equivalence_string

12.3 Checking Access and Protection

When a user tries to access a logical name table, the operating system compares the security profile of the user with the security profile of the table. The operating system uses the following sequence:

1. Scans the table's access control list for an entry matching any of the user's rights identifiers.
2. Evaluates the table's protection mask against the user's UIC.
3. Looks for special privileges.

The system checks the privileges in the user authorization file (UAF) granted to you when your system manager sets up your account. Privileges allow you to perform the functions listed in Table 12-2.

Table 12-2 Summary of Privileges

Privilege	Function
GRPNAM	Creates or deletes a logical name in your group logical name table.
GRPPRV	Creates or deletes a logical name in your group logical name table.
SYSNAM	Creates executive-mode or kernel-mode logical names. Creates or deletes a logical name in the system logical name table. Deletes a logical name or table at an inner access mode.
SYSPRV	Creates or deletes a logical name in the system logical name table. Creates or deletes a shareable table.

The system also checks for read, write, and delete access.

For example, a user without SYSPRV privilege but with write access to LNM$SYSTEM_DIRECTORY can create or delete a shareable table.

All users can create, delete, and translate their own process-private logical names and process-private logical name tables.

12.4 Specifying Access Modes

You can specify the access mode of a logical name when you define the logical name. If you do not specify an access mode, then the access mode defaults to that of the caller of the SYS$CRELNM system service. If you specify the acmode argument and the process has SYSNAM privilege, the logical name is created with the specified access mode. Otherwise, the access mode cannot have more privileges than the mode from which the service was requested. For information about access modes, see OpenVMS Programming Interfaces: Calling a System Routine and the discussion of SYS$CRELNM in the OpenVMS System Services Reference Manual.

A logical name table can contain multiple definitions of the same logical name with different access modes. If a request to translate such a logical name specifies the acmode argument, then the SYS$TRNLNM system service ignores all names defined at a less privileged mode. A request to delete a logical name includes the access mode of the logical name. Unless the process has the SYSNAM privilege, the mode specified can be no more privileged than the caller.

By default, the command interpreter places entries made from the command stream into the process-private logical name table; these are supervisor-mode entries and are not deleted at image exit (except for the logical names defined by the DCL commands ASSIGN/USER and DEFINE/USER). During certain system operations, such as the activation of an image installed with privilege, only executive-mode and kernel-mode logical names are used.

Logical names or logical name table names, which either an image running in user mode or the DCL commands ASSIGN/USER and DEFINE/USER have placed in a process-private logical name table, are automatically deleted at image exit. Shareable user-mode names, however, survive image exit and process deletion.

12.5 Translating Logical Names

Only one entry can exist for a particular logical name of a given access mode in a logical name table. However, a logical name table can contain entries for the same logical name at different access modes. Different logical name tables can contain entries for the same logical name.

Because identical logical names can exist in more than one logical name table, the translation that the system uses depends on the order in which it searches the logical name tables. For example, when the system attempts to translate a logical name to identify the location of a file, it uses the logical name LNM$FILE_DEV to provide the list of tables in which to look for the name.

If, for example, a logical name exists in both the process and the group logical name tables, the logical name within the process table is used.

By default, the DEFINE and DEASSIGN commands place names in, and delete names from, your process table. However, you can request a different table with the /TABLE qualifier, as shown in the following example:

$ DEFINE/TABLE=LNM$SYSTEM REVIEWERS DISK3:[PUBLIC]REVIEWERS.DIS

Any number of logical names can have the same equivalence name. Consider the following examples of the logical name TERMINAL defined in several tables. The logical name TERMINAL translates differently depending on the table specified.

Process Logical Name Table for Process A

The following process logical name table equates the logical name TERMINAL to the specific terminal TTA2. The INFILE and OUTFILE logical names are equated to disk specifications. The logical names were created from supervisor mode.

Logical Name	Equivalence Name	Access Mode
INFILE	DM1:[HIGGINS]TEST.DAT	Supervisor
OUTFILE	DM1:[HIGGINS]TEST.OUT	Supervisor
TERMINAL	TTA2:	Supervisor
...	...	...
...	...	...

To determine the equivalence string for the logical name TERMINAL in the preceding table, enter the following command:

$ SHOW LOGICAL TERMINAL

The system returns the equivalence string TTA2:.

Job Logical Name Table

The portion of the following job logical name table assigns the logical name TERMINAL to a virtual terminal VTA14. The logical name SYS$LOGIN is the device and directory for the process when you log in. The SYS$LOGIN logical name is defined in executive mode.

Logical Name	Equivalence Name	Access Mode
SYS$LOGIN	DBA9:[HIGGINS]	Executive
TERMINAL	VTA14:	User
...	...	...
...	...	...

To determine the equivalence string of the logical name TERMINAL defined in the preceding table, enter the following command:

$ SHOW LOGICAL/JOB TERMINAL

The system returns the equivalence string VTA14: as the translation.

User-Defined Logical Name Table

The following user-defined logical name table (called LOG_TBL for purposes of this discussion) contains a definition of TERMINAL as the mailbox device MBA407. The multivalued logical name (search list) XYZ has two translations: DISK1 and DISK3.

Logical Name	Equivalence Name	Access Mode
TERMINAL	MBA407:	Supervisor
XYZ	DISK1:,DISK3:	Supervisor
...	...	...
...	...	...

To determine the equivalence string for the logical name TERMINAL in the preceding user-defined table, enter the following command:

$ SHOW LOGICAL/TABLE=LOG_TBL TERMINAL

The system returns the equivalence string MBA407. In order to use this definition of TERMINAL as a device or file specification, you must redefine the logical name LNM$FILE_DEV to reference the user-defined table, as follows:

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV LOG_TBL, - _$ LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM

In this example, the DCL command DEFINE is used to redefine the default search list LNM$FILE_DEV. The /TABLE qualifier specifies the table LNM$PROCESS_DIRECTORY that is to contain the redefined search list. The system searches the tables defined by LNM$FILE_DEV in the following order: LOG_TBL, LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM.

Logical Name Supersession

If the logical name TERMINAL is equated to TTA2 in the process table, as shown in the previous examples, and the process subsequently equates the logical name TERMINAL to TTA3, the equivalence of TERMINAL TTA2 is replaced by the new equivalence name. The successful return status code SS$_SUPERSEDE indicates that a new entry replaced an old one.

The definitions of TERMINAL in the job table and in the user-defined table LOG_TBL are unaffected.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5841PRO_034.HTML