HP OpenVMS Systems Documentation

OpenVMS User's Manual

By using multiple DEFINE commands, you can create multiple logical names that refer to the same object. 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 delete a logical name, use the DEASSIGN command. When you define logical names in your process and job logical name tables, they are not deleted until your process terminates or they are explicitly deleted by user actions. However, if you specify the /USER_MODE qualifier to the DEFINE command, the logical name is defined in the process logical name table and deleted automatically after executing the next command image.

To delete a logical name ending with a colon, specify two colons. The DEASSIGN command, like the ASSIGN command, removes one colon before it searches the logical name table for a match.

11.5 Logical Name Translation

When the system reads a file specification or device name in a DCL command line, it examines the file specification or device name to see whether the leftmost component is a logical name. If the leftmost component ends with a colon, space, comma, or a line terminator (for example, Enter), the system attempts to translate it as a logical name. If the leftmost component ends with any other character, the system does not attempt to translate it as a logical name.

After you enter the command shown in the following example, the system checks to see whether PUP is a logical name because PUP is the leftmost component of the file specification. Because the leftmost component is terminated with Enter, the system attempts to translate PUP.

$ TYPE PUP [Enter]

After you enter the command shown in the next example, the system checks whether DISK is a logical name. The system attempts to translate DISK because it is the leftmost component and ends with a colon. The system does not check PUP:

$ TYPE DISK:PUP [Enter]

In the third example, the system does not try to translate [DRYSDALE]PUP because the leftmost component ends with a right square bracket (]):

$ TYPE [DRYSDALE]PUP [Enter]

Logical name translation can be iterative: after the system translates a logical name, it repeats the translation process for any logical names it finds contained within the first logical name.

The system limits the number of levels to which it performs logical name translation. The number of levels varies among system facilities but it is at least nine. If you define more than the system-determined number of levels or if you create a circular definition, an error occurs when the logical name is used.

In the following example, the first DEFINE command equates the logical name DISK to the device name DUA1. The second DEFINE command equates the logical name MEMO to the file specification DISK:[JEFF.MEMOS]COMPLAINT.TXT:

$ DEFINE DISK DUA1:
$ DEFINE MEMO DISK:[JEFF.MEMOS]COMPLAINT.TXT

When the system translates the logical name MEMO, it finds the equivalence string DISK:[JEFF.MEMOS]COMPLAINT.TXT. It then checks to see whether the leftmost component in this file specification ends in a colon, a space, a comma, or an end-of-line terminator. It finds a colon after DISK. The system translates that logical name also. The final translation of the file specification is:

DUA1:[JEFF.MEMOS]COMPLAINT.TXT

When the system translates a logical name, it fills in any missing fields in a file specification with the current default device, directory, and version number. When you use a logical name to specify the input file for a command, the command uses the logical name to assign a file specification to the output file as well.

If the equivalence string contains a file name and file type, the output file is given the same file name and file type. If the equivalence string does not contain a file type, a default file type is supplied. The file type supplied depends on the command you are using.

When you use logical names in a list of input files, the equivalence string of each logical name provides a temporary default.

In the following example, because a device name is not specified for the logical name HIG, the device name for MAL defines DBA1 as the temporary default device:

$ SET DEFAULT  DBA2:[CASEY]
$ DEFINE MAL DBA1:[MALCOLM]
$ DEFINE HIG [HIGGINS]
$ PRINT ALPHA,MAL:BETA,HIG:GAMMA

The PRINT command looks for the following files:

DBA2:[CASEY]ALPHA.LIS
DBA1:[MALCOLM]BETA.LIS
DBA1:[HIGGINS]GAMMA.LIS

Identical logical names can exist in more than one logical name table. When the system translates a logical name in a file specification, it searches a list of logical name tables until it finds a match. The system uses the first match it finds.

The list of logical name tables that are searched is specified in the definition of the logical name LNM$FILE_DEV. The default list consists of the process, job, group, system, and clusterwide system logical name tables. The search order is the same (process, job, group, system, and clusterwide system).

You can modify the search order, as described in Section 11.11.

11.6 Displaying Logical Names

Use the SHOW LOGICAL command to display logical names and their equivalence strings.

Sometimes the definition of a logical name includes another logical name. The SHOW LOGICAL command performs iterative translations. It then displays both the equivalence string and the level of translation. Level numbers are zero based; that is, 0 is the first level, 1 is the second, and so on. To display only the first translation found for a specified logical name, use the SHOW TRANSLATION command. (For more information, refer to the OpenVMS DCL Dictionary.)

If you use the SHOW LOGICAL command to determine the equivalence string for a process-permanent file (see Section 11.13), the command displays only the device portion of the string. For example:

$ SHOW LOGICAL SYS$INPUT
"SYS$INPUT" = "_TTB4:" (LNM$PROCESS_TABLE)

In the following example, the logical name MYDISK is displayed. Two translations are performed; the number 1 indicates the second level of translation:

$ SHOW LOGICAL MYDISK
  "MYDISK" = "WORK4" (LNM$PROCESS_TABLE)
1 "WORK4" = "$255$DUA17:" (LNM$SYSTEM_TABLE)

In the next example, the equivalence string for the logical name WORKFILE is displayed:

$ SHOW LOGICAL WORKFILE
"WORKFILE" = "DISK2:[WALSH.REPORTS]WORK_SUMMARY.DAT" (LNM$PROCESS_TABLE)

The system displays the logical name, its translation, and the name of the table that contains the logical name.

11.6.1 Specifying a Logical Name Table to Search

By default, the SHOW LOGICAL command searches your process, job, group, system, and clusterwide system tables and displays all matches. However, you can specify a particular logical name table to be searched using the /TABLE qualifier. You can also use the /GROUP, /SYSTEM, /JOB, and /PROCESS qualifiers to display the logical names in the group, system, job, and process logical name tables, respectively.

In the following example, the SHOW LOGICAL command, using the /TABLE qualifier, displays the logical names in the process logical name table (LNM$PROCESS):

$ SHOW LOGICAL/TABLE=LNM$PROCESS
(LNM$PROCESS_TABLE)
  "DECW$DISPLAY" = "_WSA30:"
  "SYS$COMMAND" = "_FIFI$VTA65:"
  "SYS$DISK" [super] = "WORK1:"
  "SYS$DISK" [exec] = "WORK1:"
  "SYS$ERROR" = "_FIFI$VTA65:"
  "SYS$INPUT" = "_FIFI$VTA65:"
  "SYS$OUTPUT" [super] = "_FIFI$VTA65:"
  "SYS$OUTPUT" [exec] = "_FIFI$VTA65:"
  "TT" = "_VTA65:"

To display translation attributes and access modes of logical names, use the SHOW LOGICAL/FULL command, as follows:

$ SHOW LOGICAL/FULL SYS$ERROR
  "SYS$ERROR" [exec] = "_PADRAIC$TDA824:" [terminal] (LNM$PROCESS_TABLE)

This example displays the logical name SYS$ERROR in executive mode and shows the translation attribute, terminal.

11.7 Creating and Using Search Lists

When a logical name is equated to several equivalence strings in a single DEFINE (or ASSIGN) command, a search list is created.

When you use a search list in a file specification, the search list is translated as follows:

• If the search list contains only a device, the original default directory is searched.
• If the search list contains a device and a directory, both are used to construct a complete file specification.

The system translates the logical name, in the order in which you specified the equivalence strings, until it finds a match.

The command affects only the first file found. At that point, the search ends. If a match is not found, the system reports an error only on the last file it attempts to find.

Note that a search list is not a wildcard; it is a list of places to look.

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

11.7.1 Using Search Lists with Commands That Accept Wildcards

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.

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 complete (as shown by SYS$LOGIN 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

When you specify a search list as the first part of the parameter for the SET DEFAULT command, the system assigns the search list name, untranslated, to SYS$DISK. (SYS$DISK is a logical name that translates to your default disk.) Note that when you specify a search list as the first part of a parameter for the SET DEFAULT command, each equivalence string in the search list must contain a device name.

In the following example, both a device and a directory are specified; thus, both are used to construct the file specifications:

$ DEFINE FIFI DISK1:[FRED],DISK2:[GLADYS],DISK3:[MEATBALL.SUB]
$ DIRECTORY FIFI:MEMO.LIS

This command displays the following list of files:

DISK1:[FRED]MEMO.LIS
DISK2:[GLADYS]MEMO.LIS
DISK3:[MEATBALL.SUB]MEMO.LIS

In the following example, the SHOW DEFAULT command shows the default disk and directory as DISK2:[MEATBALL.SUB]. Next, the search list FIFI is defined. The SET DEFAULT command uses the search list as its parameter. The second use of the SHOW DEFAULT command shows that the default directory has not changed. However, the search list FIFI is displayed as the default device along with its equivalence strings. The SHOW DEFAULT command displays the search list in the order in which the search list is evaluated by the system:

$ SHOW DEFAULT
  DISK2:[MEATBALL.SUB]
$ DEFINE FIFI DISK1:[FRED], DISK2:[GLADYS], DISK3:
$ SET DEFAULT FIFI
$ SHOW DEFAULT
  FIFI:[MEATBALL.SUB]
=   DISK1:[FRED]
=   DISK2:[GLADYS]
=   DISK3:[MEATBALL.SUB]

When the RUN command is followed by a search list, the system forms file specifications as described previously. However, the system then checks to see whether any of the files in the list are installed images. The system runs the first file in the search list that is an installed image. Then, the RUN command terminates.

If none of the file specifications are installed images, the system repeats the process of forming file specifications. This time it looks for each file specification on the disk. It runs the first file it finds there. An error message is displayed if none of the specified files is found either in the known file list or on the disk.

11.7.4 Search Order for Multiple Search Lists

A file specification can contain more than one search list. When this occurs, each item in the file name search list is used, while the first device name is held constant. After all the items in the file name search list are combined with the first device name, they are then combined with the second device name. This process continues until each device has been searched.

You can also have iterative (nested) search lists when one name in a search list translates to another search list. If this occurs, the system uses each name in a sublist before continuing to the next upper-level name.

The following example shows a file specification that has a search list in the file name and in the device name:

$ DEFINE FILE CHAP1.RNO, CHAP2.RNO
$ DEFINE DISK WORK1:[ROSE], WORK2:[THORN]
$ SET DEFAULT DISK
$ DIRECTORY FILE

Directory WORK1:[ROSE]

CHAP1.RNO;2          CHAP2.RNO;1

Total of 2 files.

Directory WORK2:[THORN]

CHAP1.RNO;1          CHAP2.RNO;1

Total of 2 files.

Grand total of 2 directories, 4 files.

The directory listing for each file name is given, first for WORK1:[ROSE] and second for WORK2:[THORN].

The following example shows iterative search lists:

$ DEFINE NESTED FRED.DAT, NEW_LIST, RICKY.DAT
$ DEFINE NEW_LIST ETHEL.DAT, LUCY.DAT

The search order for the search list NESTED follows:

FRED.DAT
ETHEL.DAT
LUCY.DAT
RICKY.DAT

A logical name table has the following characteristics:

• Scope (whether it is shareable or process-private)
• Access mode
• Name
• Parent logical name table
• Access control (shareable logical name tables only)
• Quota (to limit the amount of pool occupied by its logical names)

During system initialization, several shareable logical name tables are created. When a new process is created, the system creates several other tables, shareable and process-private, for that process. All these tables are shown in Table 11-1.

The access mode of a logical name table can be specified when it is created. If not specified, the mode defaults to the access mode from which the table creation was requested, typically supervisor or user mode. A logical name table can contain logical names of its own access mode and of less privileged access modes. A logical name table can be the parent table to another table of the same or less privileged access mode.

A logical name table is identified by its name, which is itself a logical name. As a logical name, each name table name must be contained within a logical name table.

11.8.1 Logical Name Table Directories

Two special logical name tables called directories exist as containers for logical name table names:

• Process directory, LNM$PROCESS_DIRECTORY
  The process directory contains the names of all process-private tables for that process and its own table name. Each process has its own process-private directory.
• System directory, LNM$SYSTEM_DIRECTORY
  The system directory contains the names of all shareable tables and its own table name. There is only one LNM$SYSTEM_DIRECTORY per system.

These directories contain names that translate iteratively to table names. All logical name table names and any logical names that translate to tables are kept in these directories.

The parent table of a logical name table is not necessarily a directory table. That is, this hierarchical structure is distinct from the location of logical name table names.

11.8.2 Displaying the Structure of Directory Tables

To display the relationship of logical name directory tables to logical name tables, enter the SHOW LOGICAL/STRUCTURE command, as shown in the following example:

$ SHOW LOGICAL/STRUCTURE
(LNM$PROCESS_DIRECTORY)
    (LNM$PROCESS_TABLE)
(LNM$SYSTEM_DIRECTORY)
    (LNM$SYSTEM_TABLE)
    (LMF$LICENSE_TABLE)
    (LNM$CLUSTER_TABLE)
        (LNM$SYSCLUSTER_TABLE)
    (LNM$GROUP_000123)
    (LNM$JOB_824E98E0)
            .
            .
            .

This example shows the logical name table names that reside in each logical name table directory. It also shows the relationship between LNM$CLUSTER_TABLE and LNM$SYSCLUSTER_TABLE.

11.9 Default Logical Name Tables

The default tables created by the executive, including the system directory and process directory tables, are shown in Table 11-1.