HP OpenVMS Systems Documentation

Content starts here

OpenVMS Programming Concepts Manual


Previous Contents Index

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

34.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 application
  • 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

34.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 34-2.

Table 34-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.

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

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

34.6 Specifying Attributes

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:

Attribute Meaning
LNM$M_CONFINE Prevents this process-private logical name from being copied to subprocesses. Subprocesses are created by the DCL command SPAWN or by the run-time library LIB$SPAWN routine.
LNM$M_NO_ALIAS Prevents creation of a duplicate logical name in the specified logical name table at an outer access mode. If another logical name already exists in the table at an outer access mode, that name is deleted.

The attr argument attributes that are available from the SYS$CRELNT system service are as follows:

Attribute Meaning
LNM$M_CONFINE Prevents this process-private logical table from being copied to subprocesses. Subprocesses are created by the DCL command SPAWN or by the run-time library LIB$SPAWN routine.
LNM$M_CREATE_IF Prevents creation of a nonclusterwide logical name table if the specified table already exists at the specified access mode in the appropriate directory table. This attribute applies only to local tables.
LNM$M_NO_ALIAS Prevents creation of a logical name table at an outer access mode in a directory table if the table name already exists in the directory table.

The attr argument attributes that are available from the SYS$TRNLNM system service are as follows:

Attribute Meaning
LNM$M_CASE_BLIND Governs the translation process and causes SYS$TRNLNM to ignore uppercase and lowercase differences in letters when searching for logical names.
LNM$M_INTERLOCKED Ensures that any clusterwide logical name modifications in progress are completed before the name is translated.

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:

Attribute Meaning
LNM$M_CONCEALED Indicates that the equivalence string at the current index value for the logical name is an OpenVMS RMS concealed device name.
LNM$M_TERMINAL Indicates that the equivalence strings cannot be translated further.

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:

Attribute Meaning
LNM$M_CONCEALED Indicates that the equivalence string at the current index value for the logical name is an OpenVMS RMS concealed device name.
LNM$M_CONFINE Indicates that the logical name cannot be used by spawned subprocesses. Subprocesses are created by the DCL command SPAWN or by the run-time library LIB$SPAWN routine.
LNM$M_CRELOG Indicates that the logical name was created by the SYS$CRELOG system service.
LNM$M_EXISTS Indicates that the equivalence string at the specified index value exists.
LNM$M_NO_ALIAS Indicates that if the logical name already exists in the table, it cannot be created in that table at an outer access mode.
LNM$M_TABLE Indicates that the logical name is the name of a logical name table.
LNM$M_TERMINAL Indicates that the equivalence strings cannot be translated further.
LNM$V_CLUSTERWIDE Indicates that the logical name is clusterwide.

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.

34.7 Establishing Logical Name Table Quotas

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:

  • When the system is initialized
  • When a process is created
  • When logical name tables are created

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.

34.7.1 Directory Table Quotas

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.

34.7.2 Default Logical Name Table Quotas

The process, group, system, clusterwide system, and clusterwide parent logical name tables have unlimited quota.

34.7.3 Job Logical Name Table Quotas

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:

  • For all processes that activate LOGINOUT, the quota for the job logical name table is obtained from the system authorization file. This allows the quota for the job to be specified on a user-by-user basis. You can modify the job logical name table quota by specifying a value with the DCL command AUTHORIZE/JTQUOTA.
  • For all processes that do not activate LOGINOUT, the quota for the job logical name table can be specified as a quota list item (PQL$_JTQUOTA) in the call to the Create Process (SYS$CREPRC) system service. If a detached process is to be created by means of the DCL command RUN/DETACHED, then you can use the /JOB_TABLE_QUOTA qualifier to specify the SYS$CREPRC quota list item.
  • For all processes that do not activate LOGINOUT and do not specify a PQL$_JTQUOTA quota list item in their call to SYS$CREPRC, the quota for the job logical name table is taken from the dynamic System Generation utility (SYSGEN) parameter PQL$_DJTQUOTA. You can use SYSGEN to display both PQL$_DJTQUOTA and PQL$_MJTQUOTA, the default and minimum job logical name table quotas, respectively.


Previous Next Contents Index