|Document revision date: 15 July 2002|
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
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:
To delete a shareable logical name table, you must have:
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:
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:
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:
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:
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:
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:
When you submit a batch job, the following occur:
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.
220.127.116.11 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.
18.104.22.168 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.
22.214.171.124 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.
|privacy and legal statement|