HP OpenVMS Systems Documentation
OpenVMS Programming Concepts Manual
32.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 Chapter 20 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.
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:
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.
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.
To determine the equivalence string for the logical name TERMINAL in the preceding table, enter the following command:
The system returns the equivalence string TTA2:.
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.
To determine the equivalence string of the logical name TERMINAL defined in the preceding table, enter the following command:
The system returns the equivalence string VTA14: as the translation.
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.
To determine the equivalence string for the logical name TERMINAL in the preceding user-defined table, enter the following command:
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:
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.
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.
Generally, attributes specified through the logical name system services perform two functions: they affect the creation of logical names or govern how the system service operates, and they affect the translation of logical names and equivalence strings.
Attributes that affect the creation of the logical names are specified optionally in the attr argument of a system service call. The attr argument attributes that are available from the SYS$CRELNM system service are as follows:
The attr argument attributes that are available from the SYS$CRELNT system service are as follows:
The attr argument attributes that are available from the SYS$TRNLNM system service are as follows:
The translation attributes LNM$M_CONCEALED and LNM$M_TERMINAL associated with logical names and equivalence strings are specified optionally through the LNM$_ATTRIBUTES item code in the itmlst argument of the SYS$CRELNM system service call. The equivalence name attributes for SYS$CRELNM are as follows:
When the item code LNM$_ATTRIBUTES is specified through SYS$TRNLNM, the system returns the current attributes associated with the logical name and equivalence string at the current index value. Since a logical name can have more than one equivalence name, each equivalence name is identified by an index value. The item code LNM$_INDEX of SYS$TRNLNM searches for an equivalence name that has the specified index value.
The equivalence returned attributes for SYS$TRNLNM are as follows:
The attributes of multiple equivalence strings do not have to match.
For more information about attributes, refer to the appropriate system
service in the OpenVMS System Services Reference Manual.
A logical name table quota is the number of bytes allocated in memory for logical names contained in a logical name table. Logical name table quotas are established in the following instances:
Each logical name table has a quota associated with it that limits the number of bytes of memory (either process pool or system paged pool) that can be occupied by the names defined in the table. The quota for a table is established when the table is created.
If no quota is specified, the newly created table has unlimited quota.
Note that this table can expand to consume all available process or
system memory, and all users with write access to such a shareable
table can cause the unlimited consumption of system paged pool.
When the system is initialized, unlimited quota is automatically established for the system directory table LNM$SYSTEM_DIRECTORY.
When you log in to the system, unlimited quota is automatically
established for the process directory table LNM$PROCESS_DIRECTORY.
The process, group, system, clusterwide system, and clusterwide parent
logical name tables have unlimited quota.
Because the job logical name table is a shareable table, and because you do not need special privileges to create logical names within it, the quota allocated to this logical name table is constrained at the time the table is created. The following three mechanisms specify the quota for the job logical name table at the time of its creation:
32.7.4 User-Defined Logical Name Table Quotas
User-defined logical name tables can be created with either an explicit limited quota or no quota limit.
The presence of user-defined logical name table quotas eliminates the
need for a privilege (for example, SYSNAM or GRPNAM) to control
consumption of paged pool when you create logical names in a shareable
Although logical names typically represent device and file names, shareable logical names can also be used to pass information among cooperating processes. When a process creates a shareable logical name, it can store up to 255 bytes of information in each equivalence name. The processes can agree to any arbitrary form for the information. Cooperating processes can translate the shareable name to retrieve the data in its eqivalence names.
The operating system ensures one process cannot change a logical name at the same time another process is either translating the name or trying to change it. In other words, the synchronization provided by OpenVMS allows multiple concurrent readers or a single writer to access shared logical names that are not clusterwide.
Each instance of OpenVMS has its own shareable logical name database. When a process creates a new shareable logical name, that name can be translated immediately by any other process in the system with access to the containing table.
On an OpenVMS cluster, each node has its own shareable logical name database. In addition, the clusterwide tables and their names are replicated on each node of the cluster. Cluster communication and replication time can delay the time when a clusterwide logical name is visible on other cluster nodes. For increased performance, the default synchronization provided by OpenVMS for clusterwide logical names allows a single writer to access shared logical names, but it does not block concurrent readers.
Synchronization provided by OpenVMS may therefore be insufficient for a given application. In particular, the following circumstances require that an application provide additional synchronization:
If you have an application where a logical name translator must be certain of getting the most recent definition of a clusterwide logical name, you should specify in the application the LNM$M_INTERLOCKED attribute in the attr argument. Use of this attribute synchronizes the translation with any pending changes to clusterwide names and ensures that the translation retrieves the most recent definition of the name. Use of this attribute to translate a local name adds a small amount of overhead but is otherwise harmless.
No logical name service provides an atomic modify of a logical name, clusterwide or local; it is thus not possible in one system service call to read the information in a logical name's equivalence names and recreate it with updated information. This means that if you have an interprocess application in which multiple processes modify a logical name, you must provide additional synchronization to create a critical section containing the SYS$TRNLNM and SYS$CRELNM calls. For example, your application could take the following steps:
32.9 Using Logical Name and Equivalence Name Format Conventions
The operating system uses special conventions for assigning logical names to equivalence names and for translating logical names. These conventions are generally transparent to user programs; however, you should be aware of the programming considerations involved.
If a logical name string presented in I/O services is preceded by an underscore (_), the I/O services bypass logical name translation, drop the underscore, and treat the logical name as a physical device name.
When you log in, the system creates default logical name table entries for process-permanent files. The equivalence names for these entries (for example, SYS$INPUT and SYS$OUTPUT) are preceded by a 4-byte header that contains the following information:
This header is followed by the equivalence name string. If any of your program applications must translate system-assigned logical names, you must prepare the program both to check for the existence of this header and to use only the desired part of the equivalence string. The following program demonstrates how to do this: