OpenVMS User's Manual

For additional information on the commands described in this chapter, refer to the OpenVMS DCL Dictionary or online help.

13.2 About Logical Names

Logical names:

• Are equated to strings (called equivalence strings or equivalence names) or a list of equivalence strings (called search lists). When you use a logical name, the equivalence string is substituted for the logical name.
• Can be shorthand for long file specifications.
• Can be defined by you or by the system.
• Can be used to keep programs and command procedures independent of physical file specifications. For example, if a command procedure references the logical name ACCOUNTS, you can equate ACCOUNTS to any file on any disk before executing the command procedure.

In general, when a command accepts a system object, the command checks whether the name you provide is a logical name. If the name is a logical name, the system replaces the logical name with its actual value and executes the command.

13.2.1 Example

In the following example, the logical name COMS is created to represent the directory DISK7:[WALSH.COMMAND_PROC]:

$ TYPE COMS:PAYROLL.COM

Then COMS can be used in a DCL command line:

$ SET DEFAULT COMS

In command procedures, you can use logical names to perform input and output from files. When you open a file with the OPEN command, you also create a logical name for the file. The READ, WRITE, and CLOSE commands use the logical name and not the actual file specification to refer to the file.

13.2.3 Example

In the following example, when the CLOSE command closes the file, it deassigns the logical name INFILE:

$ OPEN INFILE DISK3:[WALSH]DATA.DAT 
$ READ INFILE RECORD 
$ CLOSE INFILE 

The system creates a set of systemwide logical names for you when you start the system and log in. These logical names allow you to refer to commonly used files or devices without using their physical device names.

Every time you log in, the system creates a group of logical names for your process and places these names in your process table.

13.3.1 Examples

• To list your operating system's programs, you do not need to know the name of the disk and directory where these programs are stored. Instead, you can use the logical name SYS$SYSTEM, as follows:

  $ DIRECTORY SYS$SYSTEM
  

• The logical name SYS$LOGIN refers to your default device and directory when you log in. If you have changed your current defaults by using the SET DEFAULT command, you can use the following command to display a file from your initial default directory:

  $ TYPE SYS$LOGIN:DAILY_NOTES.DAT
  

You can create logical names with either the ASSIGN command or the DEFINE command. Usually, you define logical names in a login command procedure (LOGIN.COM), so you can use the logical name each time you log in. You can also create logical names interactively. However, you can use these logical names only while your current process is active. Your system manager can create logical names for use by anyone logged in to the system.

13.4.1 Using the DEFINE Command

The format for defining a logical name with the DEFINE command is as follows:

DEFINE logical-name equivalence-string[,...] 

The same format can be used to create logical names for other system objects.

By default, the DEFINE command places logical names in your process logical name table, where the logical name is available only to your process and subprocesses. Section 13.5 describes logical name tables.

13.4.2 Examples

• In the following example, the following command creates the logical name WORKFILE and equates it the equivalence string DISK2:[WALSH.REPORTS]WORK_SUMMARY.DAT:

  $ DEFINE WORKFILE DISK2:[WALSH.REPORTS]WORK_SUMMARY.DAT
  

  
  After you define WORKFILE as a logical name, you can use the logical name interchangeably with the equivalence string.
• In the following example, the command creates the logical name MY_Q for the print queue BLDGC_LPS20_ANSI:

  $ DEFINE MY_Q BLDGC_LPS20_ANSI
  

  
  You could then use the following command to print the file FABLES.TXT to the BLDGC_LPS20_ANSI print queue:

  $ PRINT/QUEUE=MY_Q FABLES.TXT
  

Observe the following rules when you create a logical name with the DEFINE command:

• Limit the equivalence string and the logical name to no more than 255 characters each. A logical name can contain alphanumeric characters, the underscore (_), the dollar sign ($), and the hyphen (-).
• When you specify an equivalence string, include the punctuation marks (colons, brackets, periods) required by a file specification. For example, end a device name with a colon, enclose a directory specification in brackets, and precede a file type with a period.
• If a logical name represents only part of a file specification, separate the name from the rest of the file specification with a colon. When you use a logical name to represent a complete file specification, the terminating colon is not needed.
  In addition, be sure the logical name is the leftmost component of a file specification.
• Optionally, end the logical name with a colon.
  Note that the ASSIGN command removes the colon before placing the logical name in a logical name table; the DEFINE command saves the colon as part of the logical name.
• If you equate a logical name to one equivalence string, then equate the same logical name to a different equivalence string, the second definition will supersede the first, unless you define them in different logical name tables or define them with different access modes.

The following commands display the file DISK1:[SALES_STAFF]PAYROLL.DAT:

$ DEFINE PAY DISK1:[SALES_STAFF]PAYROLL.DAT
$ TYPE PAY

$ DEFINE PAY_FILE DISK1:[SALES_STAFF]PAYROLL
$ TYPE PAY_FILE:*.DAT

$ DEFINE PAY_DIR DISK1:[SALES_STAFF]
$ TYPE PAY_DIR:PAYROLL.DAT 

$ DEFINE PAY_DISK DISK1:
$ TYPE PAY_DISK:[SALES_STAFF]PAYROLL.DAT 

You can use a logical node name in place of a network node name or in place of a node name and an access control string. Once you define a logical node name, you can use it to avoid typing (and displaying) your user name and password on the screen.

13.4.6 Rules for Creating Logical Node Names

To define a logical node name, observe the following rules:

• Do not begin the logical name with an underscore (_).
• End the equivalence string with a double colon (::) and enclose it in quotation marks (" ").
• Use two sets of quotation marks ("" "") where you want quotation marks to appear in the access control string.
• Specify a logical name that contains 1 to 255 characters.

Caution

Do not place a DEFINE command that includes a password in a file (your login command procedure, for example). If others read the file, they will see the password.

In the following example, the command equates the logical name BOS to the node name BOSTON and an access control string, where ADAMS is the user name and OLMEKIKA is the password:

$ DEFINE BOS "BOSTON""ADAMS OLMEKIKA""::"

A file specification can contain both a logical node name (which the system translates at the local node) and a logical device name (which the system translates at the remote node). If you use a logical name to represent a node name only, you must include a double colon (::) when you use the logical name in the node position of a file specification.

After the system translates a logical node name at the local node, it parses the rest of the file specification to determine whether the format is valid.

13.4.9 Example

In the following example, the system translates the logical node name NYC at the local node. It translates the device name (DOC:) at the remote node (NEWYRK):

$ DEFINE NYC NEWYRK::
$ TYPE NYC::DOC:[PERKINS]TERM_PAPER.DAT

To override the access control string in a logical node name, specify both the logical name and an access control string in the command line.

When the system translates a logical node name iteratively, the access control information in the logical node name that is translated first overrides following access control information.

13.4.11 Examples

• In the following example, the access control string "REVERE HTEBAZILE" overrides the access control string given in the equivalence string for BOS:

  $ DEFINE BOS "BOSTON""ADAMS OLMEKIKA""::"
  $ TYPE BOS"REVERE HTEBAZILE"::RIDE.DAT
  

• In the following example, the logical name TEST1 translates to TORONTO"TEST NAMWENLUAP"::DBA1: :

  $ DEFINE TORONTO "TRNTO""TEST EIZNEKCAM""::"
  $ DEFINE TEST1 "TORONTO""TEST NAMWENLUAP""::DBA1:"
  $ TYPE TEST1:PROC.DAT
  

  
  TORONTO is a logical node name, so iterative translation occurs. In other words, the operating system searches the logical name tables until all levels of logical names in a definition are found. However, the access control string in the DEFINE TEST1 logical name assignment overrides the access control string in the DEFINE TORONTO logical node name assignment. Therefore, the TYPE command displays the following file:

   TRNTO"TEST NAMWENLUAP"::DBA1:PROC.DAT
  

When you create a logical name, you can specify translation attributes that modify how the system interprets the equivalence string.

To apply translation attributes to an equivalence string, use the /TRANSLATION_ATTRIBUTES qualifier to the DEFINE command. This is a positional qualifier: depending on where you place it on a command line, it can apply translation attributes to all equivalence strings or only to certain ones.

13.4.13 Creating Concealed Logical Names

The CONCEALED attribute causes system messages to display the logical name rather than the physical name of a device. Typically, you use the CONCEALED attribute with logical names that represent physical devices. Using concealed devices lets you write programs, write command procedures, and perform other operations without being concerned about which physical device holds the disk or tape. It also lets you use names that are more meaningful than the physical device names.

13.4.14 Creating Terminal Logical Names

The TERMINAL attribute prevents iterative translation of a logical name (that is, the equivalence string is not examined to see if it is also a logical name). The translation is "terminal" (final or completed) after the first translation.

13.4.15 Example: Translation Attributes

In the following example, the device name DJA3: is concealed with the logical name DISK:

$ DEFINE/TRANSLATION_ATTRIBUTES=CONCEALED DISK DJA3:
$ SHOW DEFAULT
  DISK:[SAM.PUP]
$ SHOW LOGICAL DISK
  "DISK" = "DJA3" (LNM$PROCESS_TABLE)

The logical name DISK represents the physical device DJA3. Thus, the SHOW DEFAULT command displays the logical name DISK rather than the physical device name, DJA3. The SHOW LOGICAL command reveals the translation of DISK.

13.4.16 Equating Several Logical Names to One Equivalence String

You can equate more than one logical name to an equivalence string by entering more than one DEFINE command. For example, the following commands equate the logical names $TERMINAL and CONSOLE to the physical name of a terminal so that both logical names translate to the same device (LTA69):

$  DEFINE $TERMINAL LTA69
$  DEFINE CONSOLE LTA69

To create a search list, equate a logical name to more than one equivalence string in a single command.

When you use a search list, the system translates the logical name until it finds a match. The order in which you specify the equivalence strings determines the order in which the system translates the names. It uses each equivalence string listed in the definition until a match is found. Note that a search list is not a wildcard; it is a list of places to look. Once a file is found, the search ends.

13.4.18 Examples

• In the following example, the logical name GETTYSBURG is a search list:

  $ DEFINE GETTYSBURG [JONES.HISTORY],[JONES.WORKFILES]
  $ SHOW LOGICAL GETTYSBURG 
   
    "GETTYSBURG" = "[JONES.HISTORY]" (LNM$PROCESS_TABLE) 
         = "[JONES.WORKFILES]"
  

• In the following example, the TYPE command searches the equivalence string [JONES.HISTORY] before it searches [JONES.WORKFILES] (the order specified in the preceding logical name definition for GETTYSBURG):

  $ TYPE GETTYSBURG:SPEECH.TXT 
  DISK1:[JONES.HISTORY]SPEECH.TXT;2 
   
  Fourscore and seven years ago, our fathers brought 
  forth on this continent a new nation, conceived 
  in liberty, and dedicated to the proposition that 
  all men are created equal.
     .
     .
     .
  

  
  Once the TYPE command finds a file named SPEECH.TXT, it ends the search and displays the file.

You can use a search list with a command that accepts wildcards. When you use wildcards, the system forms file specifications by using each equivalence string in the search list. The command operates on each file specification that identifies an existing file.

13.4.20 Example

In the following example, the DIRECTORY command is specified with a wildcard character in the version field. It finds all versions of SPEECH.TXT in the search list defined by GETTYSBURG:

$ DIRECTORY GETTYSBURG:SPEECH.TXT;*
 
Directory DISK1:[JONES.HISTORY] 
 
SPEECH.TXT;2     SPEECH.TXT;1 
 
Total of 2 files. 
 
Directory DISK1:[JONES.WORKFILES] 
 
SPEECH.TXT;1 
 
Total of 1 file. 
 
Grand total of 2 directories, 3 files.

When you enter a search list (for example, using the DIRECTORY command), the operating system uses elements in one part of the list to supply parts of the file specification that are omitted from other parts of the list. If a file specification is not precise (as shown in the following example), command lines can produce multiple files and file-not-found conditions:

$ DIRECTORY SYS$MANAGER:LOGIN.COM,SYS$LOGIN

You can avoid producing multiple files and file-not-found conditions by placing a semicolon after the file specification, as shown:

$ DIRECTORY SYS$MANAGER:LOGIN.COM;,SYS$LOGIN

Identical logical names can exist in more than one logical name table (see Section 13.5). The logical name 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. The order in which the tables are listed is also the order in which they are searched.

By default, the precedence order defined by LNM$FILE_DEV is:

1. Process table
2. Job table
3. Group table
4. System table

So, for example, if a logical name exists in both the process and the group logical name tables, the logical name within the process table is used. See Section 13.5.9 for information about redefining LNM$FILE_DEV.

13.4.23 Using Different Logical Name Tables

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. For example:

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

This command creates the logical name REVIEWERS in the system table.

13.4.24 Access Modes

The OpenVMS operating system has four access modes, as follows:

• User mode (the outermost and least privileged mode)
• Supervisor mode
• Executive mode
• Kernel mode (the innermost and most privileged mode)

You can use the DCL commands DEFINE or ASSIGN to create logical names in the first three modes (user, supervisor, and executive). By specifying different access modes for each logical name definition, you can equate the same logical name to different equivalence strings in the same logical name table. Note that you must have SYSNAM or SYSPRV privileges to create logical names in executive mode in any logical name table.

When you use the DEFINE command without specifying a mode, DCL creates the logical name in supervisor mode.

13.4.25 Example

In the following example, the commands shown equate the logical name ACCOUNTS to two different equivalence strings in the process logical name table---one in supervisor mode and one in executive mode:

$ DEFINE ACCOUNTS DISK1:[ACCOUNTS]CURRENT.DAT
$ DEFINE/EXECUTIVE_MODE ACCOUNTS DISK1:[JANE.ACCOUNTS]OBSOLETE.DAT

Logical names created in user mode are temporary. Define a logical name in user mode when you want to use it only for the execution of the next command or image.

13.4.27 Example

In the following example, the logical name ADDRESSES is deleted automatically after the execution of the program PAYABLE:

$ DEFINE/USER_MODE ADDRESSES DISK1:[SAM.ACCOUNTS]OVERDUE.LIS 
$ RUN PAYABLE

In looking up logical names, all privileged images and utilities, such as LOGINOUT and Mail, bypass the user-mode and supervisor-mode portions of the system logical name table. Therefore, Digital recommends that you define all logical names for important system components (public disks and directories, for example) in executive mode. (Only the operating system and privileged programs can create logical names in kernel mode.)

13.5 Creating Logical Name Tables

The system stores logical names and their equivalence strings in process, job, group or system logical name tables. Some logical name tables are available only to your process; these tables are called process-private. Other tables are shareable; that is, they are available to other users on the system.

13.5.1 Process Table

The names in this table are available only to your process and any subsequent subprocesses. Every process on the system has a process logical name table. When you log in, the system creates logical names for your process and places them in your process table.

The name for your process table is LNM$PROCESS_TABLE. However, use the logical name LNM$PROCESS to refer to your process table.

13.5.2 Job Table

The names in this table are available to your process and to any of your subprocesses. All job tables are shareable so that all users can access them.

The name for your job table is LNM$JOB_xxx (xxx represents the Job Information Block address defined by the system for your job tree). However, use the logical name LNM$JOB to refer to your job table.

13.5.3 Group Table

The names in this table are available to all users in your group. The name for your group table is LNM$GROUP_xxx (xxx represents a group number.) However, use the logical name LNM$GROUP to refer to your group table.

13.5.4 System Table

The names in this table are available to all users on the system. The name for your system table is LNM$SYSTEM_TABLE. However, use the logical name LNM$SYSTEM to refer to the system table.

13.5.5 Creating Logical Names in Tables

In general, you create logical names in your process table. However, if you are a system manager or if your work requires you to add names to shareable tables (see Section 13.5.8), you must also work with the group and system tables. To create or delete a name in your group table, you need GRPNAM, GRPPRV, or SYSPRV privilege. To create or delete a name in the system table, you must have a UIC group number between 0 and 10 or SYSNAM or SYSPRV privilege.

The CREATE/NAME_TABLE command creates a logical name table and catalogs it in one of the directory logical name tables. Logical names that identify logical name tables or that translate iteratively to logical name tables must always be entered into one of the directory logical name tables.

13.5.6 Process Private Logical Name Tables

To create a logical name table that is private to your process, create the table in LNM$PROCESS_DIRECTORY (the default). If the table needs to be shareable, specify /PARENT_TABLE=LNM$SYSTEM_DIRECTORY with the CREATE/NAME_TABLE command.

A name in a directory table can contain 1 to 31 characters. Only alphanumeric characters, the dollar sign ($), and the underscore (_) are valid.

13.5.7 Example

The following example creates a process-private logical name table named TAX, places the definition for the logical name CREDIT in the table, and verifies the table's creation. The SHOW LOGICAL/TABLE command displays logical names in tables other than LNM$SYSTEM or LNM$PROCESS:

$ CREATE/NAME_TABLE TAX
$ DEFINE/TABLE=TAX CREDIT [ACCOUNTS.CURRENT]CREDIT.DAT
$ SHOW LOGICAL/TABLE=TAX CREDIT
 "CREDIT" = "[ACCOUNTS.CURRENT]CREDIT.DAT"  (TAX)

To create a shareable logical name table, use the /PARENT_TABLE qualifier and specify the name of a shareable table. For example:

$ CREATE/NAME_TABLE/PARENT_TABLE=LNM$SYSTEM_DIRECTORY NEWTAB

The following privilege and access requirements apply to the use of shareable logical name tables:

• To create a shareable logical name table, you must have SYSPRV privilege and EXECUTE (E) access to the parent table.
• To delete a shareable logical name table, you must have SYSPRV privilege or DELETE (D) access to the table.
• To place a name in or delete a name from a shareable logical name table, you must have WRITE (W) access to the table.
• To read (translate) a name in a shareable logical name table, you must have READ (R) access to the table.

Generally, you do not need to change the default logical name table definitions set up in the directory tables LNM$PROCESS_DIRECTORY and LNM$SYSTEM_DIRECTORY. Two reasons for changing the entries in the directory logical name tables are:

1. To create another logical name table
2. To change the order in which the system searches the logical name tables

To place a logical name in a specific table, use the DEFINE/TABLE command.

13.5.10 Example

In the following example, the logical name TESTDIR is placed in NEWTAB (a user-defined logical name table):

$ DEFINE/TABLE=NEWTAB TESTDIR [JONES.TESTFILES]

The next time TESTDIR is referred to in a file specification, the system looks for it in the process, job, group, and system logical name tables only. It does not look in the NEWTAB table. NEWTAB must be included in the list of logical name tables that the system searches.

13.5.11 Adding Logical Names to the Logical Name Directory

There are two ways to add logical names to the logical name directory:

• Create a private definition of LNM$FILE_DEV within the process logical name directory table.
• Redefine LNM$FILE_DEV within the system directory logical name table (requires SYSNAM or SYSPRV privilege).

To add a logical name table to the process logical name directory table, redefine the logical name LNM$FILE_DEV within the process logical name directory table.

If you have SYSNAM or SYSPRV privileges, you can add a logical name table to the system directory logical name table.

13.5.12 Examples

• In the following example, NEWTAB is added to the process logical name directory:

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

  
  This example specifies that the system search the NEWTAB table first for the following reasons:
  • The process-private version of LNM$FILE_DEV is used before the default system version.
  • Within LNM$FILE_DEV, NEWTAB is listed before the process, job, group, and system logical name tables.
• In the following example, the logical name NEWTAB is added to the system directory table by a user with SYSNAM or SYSPRV privileges:

  $ DEFINE/TABLE=LNM$SYSTEM_DIRECTORY LNM$FILE_DEV -
  _$ NEWTAB, LNM$PROCESS, LNM$JOB, LNM$GROUP, LNM$SYSTEM
  

There are two ways to define the protection of a logical name table:

• Use the /PROTECTION qualifier with the CREATE/NAME_TABLE command. This command lets you set UIC-based protection for a shareable logical name table.
• Apply ACL protection with the ACL editor or with the SET SECURITY/ACL/OBJECT_TYPE=LOGICAL_NAME_TABLE command. ACLs for system logical name tables are saved when the system reboots but ACLs for process logical name tables are not. You must reestablish ACLs on process logical name tables every time the system is booted. For more information, see the SET SECURITY/ACL command in the OpenVMS DCL Dictionary.

Quotas are used to limit the amount of system resources that a given logical name table can consume. The process, group, and system logical name tables have an infinite quota. By default, when you create a logical name table, it too has an unlimited quota.

13.5.15 Specifying Quotas

You can specify a quota to limit the size, in bytes, of a logical name table that you create. Before a logical name is created, the size of its data structure is checked against the quota remaining for the table. If there is insufficient quota available for the new entry, the system displays an error message.

  6489P021.HTM
  OSSG Documentation
  22-NOV-1996 13:17:07.26

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal