HP OpenVMS Systems Documentation

OpenVMS User's Manual

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.

11.10.1 Creating 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).

A name in a directory table can contain 1 to 31 characters. Only uppercase alphanumeric characters, the dollar sign ($), and the underscore (_) are valid. If you specify a lowercase table name, it is automatically converted to uppercase.

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 allows you to specify the logical name table to display.

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

To have the system search the new table automatically during file lookup, you can redefine LNM$PROCESS, as shown in the following example:

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$PROCESS LNM$PROCESS_TABLE, 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

You can create a clusterwide logical name table in the same way that you create other shareable logical name tables. A clusterwide logical name table is a special type of shareable logical name table and is subject to the privilege and access requirements that apply to all shareable logical name tables (see Section 11.10.4).

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 new clusterwide logical name table, you define the new clusterwide logical name with the DEFINE command, specifying the new table's name with the /TABLE qualifier, as shown in the following example:

$ DEFINE/TABLE=new_clusterwide_logical_name_table
logical_name -
_$ equivalence_string

Users with privileges can create shareable logical name tables for special purposes. For example, an application can create one or more shareable logical name tables to communicate information such as file locations to the application users:

$ CREATE/NAME_TABLE APPX_FILE_LOCATOR /PARENT=LNM$SYSTEM_DIRECTORY -
_$ /PROTECTION = (S:RWD,O:RWD,G:R,W:R)

To create a shareable logical name table, you must have:

• CREATE (C) access to the parent table
• SYSPRV privilege or WRITE (W) access to LNM$SYSTEM_DIRECTORY

To delete a shareable logical name table, you must have:

• DELETE (D) access to the table
• SYSPRV privilege or WRITE (W) access to LNM$SYSTEM_DIRECTORY

The operating system provides default protection for the shareable logical name tables that it creates and that users create. The default protection is stored in security profiles that a system manager or table owner can modify. For more information, see the OpenVMS Guide to System Security.

You can modify the default protection of the tables that you create by:

• Using the /PROTECTION qualifier with the DCL CREATE/NAME_TABLE command. This command lets you set UIC-based protection.
• Applying ACL protection to a table already created with the ACL editor or with the SET SECURITY/ACL/OBJECT_TYPE=LOGICAL_NAME_TABLE command.

ACLs for shareable logical name tables are not saved between system boots. You must reestablish ACLs on these logical name tables every time the system is booted.

For more information about applying ACL protection to a shareable logical name table, refer to the SET SECURITY/ACL command in the OpenVMS DCL Dictionary.

11.10.6 Establishing Quotas for Logical Name Tables

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.

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.

Once you set the quota for a table, you cannot change it. If the table runs out of room, use the DEASSIGN command to delete old logical names. This frees space for your new logical names.

In the following example, the logical name table ABC is created and is given a quota of 500 bytes:

$ CREATE/NAME_TABLE/QUOTA=500 ABC

The job logical name table is a shareable table. The quota for a job logical name table is established when the table is created. The quota is determined by one or more of the following criteria:

• The JTQUOTA value established for the user in the system user authorization file SYSUAF.DAT (if the first image activated by the process was the system image LOGINOUT).
• The PQL$_JTQUOTA quota list value specified in the call to the Create Process ($CREPRC) system service.
• The /JOB_TABLE_QUOTA qualifier value on the RUN command used to create the detached process.
• The SYSGEN parameter PQL_DJTQUOTA (if none of the preceding conditions applies). The standard default value for this parameter is 1024 bytes; however, the system manager can change it. The System Generation utility (SYSGEN) can be used to display and set the values of the parameters PQL_DJTQUOTA (default job logical name table quota) and PQL_MJTQUOTA (minimum job logical name table quota).

A quota value of 0 for a job logical name table means there is no quota. For all practical purposes, the quota is unlimited.

11.11 Modifying the Order of Logical Name Translations

LNM$FILE_DEV defines both the logical name tables that will be searched and the search order for all logical name translations. Generally, you do not need to modify the default search order. However, you may want to add the name of a new, process-private logical name table to be searched first, before the tables specified by LNM$FILE_DEV. Similarly, system managers may want to add the names of one or more shareable logical name tables to be searched before the tables specified by LNM$FILE_DEV.

To create a process-private definition of LNM$FILE_DEV with a new table of logical names that the system will search first, do the following:

1. Create a file that contains the new logical names.
2. Convert this new file to a new logical name table.
3. Create a private definition of LNM$FILE_DEV by specifying the process logical name directory table as the parent table.
4. Add the new logical name table name to the beginning of the table name list in the private definition of LNM$FILE_DEV.

In the following example, a new logical name table, NEWTAB, is created, and a process-private definition of LNM$FILE_DEV is created with NEWTAB listed as the first table to be searched:

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

In the example above, the system searches the NEWTAB table first for the following reasons:

• The process-private definition of LNM$FILE_DEV is used instead of the default system version.
• Within LNM$FILE_DEV, NEWTAB is listed before the other logical name tables.

To add a new logical name table to the system definition of LNM$FILE_DEV, you must have SYSNAM or SYSPRV privileges.

The following example is similar to the previous one except NEWTAB is created as a shareable table rather than as a process-private table:

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

You can also remove logical names tables from the search list defined by LNM$FILE_DEV. In the following example, a process-private definition of LNM$FILE_DEV is created that contains only the process and system logical name tables. Because the process-private definition does not contain LNM$JOB and LNM$GROUP, subsequent commands that need to translate a logical name will not search the job or group tables.

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

To delete a logical name table, specify the table that contains it (the system or process directory logical name table) and the name of the table. All logical names in descendant tables (and the descendant tables themselves) are deleted when you delete a parent logical name table.

To delete a shareable logical name table, you must have DELETE access to the table or SYSPRV privilege.

In the following example, the command deletes the logical name WORKFILE:

$ DEASSIGN WORKFILE

In the following example, the command deletes the logical name table TAX from the process directory table:

$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY TAX

DCL creates process-permanent logical names when you log in. These names remain defined for the life of your process. You cannot deassign these logical names. You can redefine them (by specifying a different equivalence string in a DEFINE command), but if the redefined name is later deassigned, the process-permanent name is reestablished.

The following process-permanent logical names are available:

• SYS$INPUT
  Logical name that refers to the default input device or file
• SYS$OUTPUT
  Logical name that refers to the default output device or file
• SYS$ERROR
  Logical name that refers to the default device or file to which the system writes messages
• SYS$COMMAND
  Logical name that refers to the value of SYS$INPUT when you log in

When you use the system interactively, DCL equates SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND to your terminal. However, when you execute command procedures and submit batch jobs, DCL creates new equivalence strings for these logical names.

When you execute a command procedure interactively, the following occur:

• SYS$INPUT is equated to the command procedure. Therefore, DCL obtains data from the command procedure. This assignment is temporary. After the command procedure terminates, SYS$INPUT regains its original value.
• SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR remain equated to the terminal.

When you submit a batch job, the following occur:

• SYS$INPUT and SYS$COMMAND are equated to the batch job command procedure.
• SYS$OUTPUT and SYS$ERROR are equated to the batch job log file.

When you nest command procedures (that is, when you write a command procedure that executes other command procedures), the equivalence string for SYS$INPUT changes to point to the command procedure that is currently executing. However, the equivalence strings for SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND remain the same unless you explicitly change them.

In addition, when you enter a command that opens a file, DCL opens the file as a process-permanent file. For example, if you open a file with the OPEN command, this file is opened as a process-permanent file. The file remains open until you explicitly close the file or until you log out.

Process-permanent files are stored in a special area in memory. Note that if you keep a large number of files open at the same time, you can exhaust this area. If this occurs, close some of the files (or log out).

11.13.2 Redirecting File I/O Using Process-Permanent Logical Names

You can use process-permanent logical names to redirect file I/O. In command procedures, you can use these names to read data from the terminal and to display data (see Chapter 13 and Chapter 14). Note that DCL ignores new definitions for SYS$INPUT and SYS$COMMAND.

In OpenVMS Version 7.1, the DCL PIPE command was introduced. The PIPE command is an alternate way to redirect file I/O. For information about the PIPE command, refer to the OpenVMS DCL Dictionary: N--Z.

11.13.2.1 Redefining SYS$INPUT

You can redefine SYS$INPUT so that an image, invoked by a command procedure, reads input from the terminal or another file. Because DCL always obtains input from the default input stream, DCL ignores a redefinition of SYS$INPUT.

In the following example, the commands are part of a new command procedure file. The DEFINE command redefines SYS$INPUT to SYS$COMMAND. SYS$COMMAND refers to the terminal, the initial input stream when you logged in. With this new definition, the image invoked by the command procedure obtains input from the terminal rather than from the command procedure file (the default) but only for a certain period.

The /USER_MODE qualifier tells the command procedure that SYS$INPUT is redefined only for the duration of the next image. In this example, the next image is the editor. When the editor is finished, SYS$INPUT resumes its default value. In this case, the default value is the command procedure file.

$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND
$ EDIT/TPU MYFILE.DAT
   .
   .
   .

You can redefine SYS$OUTPUT to redirect output from your default device to another file. When you redefine SYS$OUTPUT, the system opens a file with the name you specify in the logical name assignment. When you define SYS$OUTPUT, all subsequent output is directed to the new file.

Remember to deassign SYS$OUTPUT. Otherwise, output will continue to be written to the file you specified. Note that you can redefine SYS$OUTPUT in user mode (with DEFINE/USER_MODE) to redirect output from an image. This definition is in effect only until the next command image is executed. Once the command image is executed (that is, the output is captured in a file), the logical name SYS$OUTPUT resumes its default value.

When you log in, the system creates two logical names called SYS$OUTPUT. One name is created in executive mode; the other name is created in supervisor mode. You can supersede the supervisor mode logical name by redefining SYS$OUTPUT. If you deassign the supervisor mode name, the system redefines SYS$OUTPUT in supervisor mode, using the executive mode equivalence string. You cannot deassign the executive mode name.

When you redefine SYS$OUTPUT to a file, the logical name contains only the device portion of the file specification even though the output is directed to the file you specify.

If the system cannot open the file you specify when you redefine SYS$OUTPUT, it displays an error message.

After you redefine SYS$OUTPUT, most commands direct output to the existing version of the file. However, certain commands create a new version of the file before they write output.

In the following example, SYS$OUTPUT is defined as MYFILE.LIS before the SHOW DEVICES command is entered. The display produced by SHOW DEVICES is directed to MYFILE.LIS in the current directory rather than to the terminal. You can manipulate the data as you would any other text file:

$ DEFINE SYS$OUTPUT MYFILE.LIS
$ SHOW DEVICES

In the following example, SYS$OUTPUT is redefined to the file TEMP.DAT. When SYS$OUTPUT is redefined, output from DCL and from images is directed to the file TEMP.DAT. The output from the SHOW LOGICAL command and from the SHOW TIME command is also sent to TEMP.DAT. When SYS$OUTPUT is deassigned, the system closes the file TEMP.DAT and redefines SYS$OUTPUT to the terminal. When the TYPE command is entered, the output collected in TEMP.DAT displays on the terminal.

$ DEFINE SYS$OUTPUT TEMP.DAT
$ SHOW LOGICAL SYS$OUTPUT
$ SHOW TIME
$ DEASSIGN SYS$OUTPUT
$ TYPE TEMP.DAT
   "SYS$OUTPUT" = "DISK1:" (LNM$PROCESS_TABLE)
  06-MAY-1996 13:26:53

When SYS$OUTPUT is redefined, the equivalence string contains the device name DISK1, not the full file specification.

11.13.2.3 Redefining SYS$ERROR

You can redefine SYS$ERROR to direct error messages to a specified file. However, if you redefine SYS$ERROR so it is different from SYS$OUTPUT (or if you redefine SYS$OUTPUT without also redefining SYS$ERROR), DCL commands send informational, warning, error, and severe error messages to both SYS$ERROR and SYS$OUTPUT. Therefore, you receive these messages twice---once in the file indicated by the definition of SYS$ERROR and once in the file indicated by SYS$OUTPUT. Success messages are sent only to the file indicated by SYS$OUTPUT.

DCL commands and images, which use standard error display mechanisms, send error messages to both SYS$ERROR and SYS$OUTPUT even when SYS$ERROR is different from SYS$OUTPUT. However, if you redefine SYS$ERROR, then run an image that references SYS$ERROR, the image sends error messages only to the file indicated by SYS$ERROR. This is true even if SYS$ERROR is different from SYS$OUTPUT.

11.13.2.4 Redefining SYS$COMMAND

Although you can redefine SYS$COMMAND, DCL ignores your definition. DCL always uses the default definition for your initial input stream. However, if you execute an image that references SYS$COMMAND, the image can use your new definition.