Creates a new logical name table. The /NAME_TABLE qualifier is required.

Format

UTLTOOLS CREATE/NAME_TABLE

Description

The UTLTOOLS CREATE/NAME_TABLE command creates a new logical name table. The name of the table is contained within the LNM$PROCESS_ DIRECTORY directory table if the table is process-private, and within the LNM$SYSTEM_DIRECTORY directory table if the table is shareable.

Every new table has a parent table, which determines whether the new table is process-private or shareable. To create a process- private table, use the /PARENT_TABLE qualifier to specify the name of a process-private table (the process directory table). To create a shareable table, specify the parent as a shareable table.

If you do not explicitly provide a parent table, the UTLTOOLS CREATE/NAME_ TABLE command creates a process-private table whose parent is LNM$PROCESS_DIRECTORY; that is, the name of the table is entered in the process directory.

Every table has a size quota. The quota may either constrain the potential growth of the table or indicate that the table's size can be virtually unlimited. The description of the /QUOTA qualifier explains how to specify a quota.

To specify an access mode for the table you are creating, use the /USER_MODE, /SUPERVISOR_MODE, /EXECUTIVE_MODE or /KERNEL_MODE qualifier. If you specify more than one of these qualifiers, only the last one entered is accepted. If you do not specify an access mode, then a supervisor-mode table is created.

To delete a logical name table, use the DEASSIGN or UTLTOOLS DEASSIGN command, specify the name of the table you want to delete, and use the /TABLE qualifier to specify the directory table where the name of the table was entered.

Qualifiers

/ATTRIBUTES[=(keyword[,...])]

Specifies attributes for the logical name table. If you specify only one keyword, you can omit the parentheses. If you do not specify the /ATTRIBUTES qualifier, no attributes are set.

You can specify the following keywords for attributes:

CONFINE	Does not copy the table name or the logical names contained in the table into a spawned subprocess; used only when creating a private logical name table. If a table is created with the CONFINE attribute, all names subsequently entered into the table are also confined.
NO_ALIAS	No identical names (either logical names or names of logical name tables) may be created in an outer (less privileged) mode in the current directory. If you do not specify the NO_ALIAS attribute, then the table may be "aliased" by an identical name created in an outer access mode. Deletes any previously created identical table names in an outer access mode in the same logical name table directory.
SUPERSEDE	Creates a new table that supersedes any previous (existing) table that contains the name, access mode, and directory table that you specify. The new table is created regardless of whether the previous table exists. (If you do not specify the SUPERSEDE attribute, the new table is not created if the previous table exists.)

If you specify or accept the default for the qualifier /LOG, you receive a message indicating the result.

/CONTEXT=(keyword=value,,,)

Specifies the context in which the command should execute.

By default the current context is assumed.

See the UTLTOOLS FETCH SUBCONTEXT command for more details about the keywords and their values.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege.

Creates an executive-mode logical name table. If you specify executive mode, but do not have SYSNAM privilege, a supervisor- mode logical name table is created.

/KERNEL_MODE

Requires SYSNAM (system logical name) privilege.

Creates a kernellogical name table. If you specify kernel mode, but do not have SYSNAM privilege, a supervisor- mode logical name table is created.

/LOG (default)

/NOLOG

Controls whether an informational message about the table creatrion is generated. The default is the /LOG qualifier; that is, the informational message is displayed.

/PARENT_TABLE=table

Requires either create (C) access to the parent table and write (W) access to the system directory or the SYSNAM privilege.

Specifies the name of the parent table. The parent table determines whether a table is private or shareable; it also determines the size quota of the table. If you do not specify a parent table, the default table is LNM$PROCESS_DIRECTORY. A shareable table has LNM$SYSTEM_DIRECTORY as its parent table. The parent table must have the same access mode or a higher level access mode than the one you are creating.

/PROTECTION=(ownership[:access][,...])

Applies the specified protection to shareable name tables.

• Specify the ownership parameter as system (S), owner (O), group (G), or world (W).
• Specify the access parameter as read (R), write (W), create (C), or delete (D).

For more information on specifying protection codes, see the OpenVMS Guide to System Security.

The /PROTECTION qualifier affects only shareable logical name tables; it does not affect process-private logical name tables.

/QUOTA=number-of-bytes

Specifies the size limit of the logical name table. The size of each logical name entered in the new table is deducted from this size limit. The new table's quota is statically subtracted from the parent table's quota holder. The parent table's quota holder is the first logical name table encountered when working upward in the table hierarchy that has an explicit quota and is therefore its own quota holder. If the /QUOTA qualifier is not specified or the size limit is 0, the parent table's quota holder becomes the new table's quota holder and space is dynamically withdrawn from it whenever a logical name is entered in this new table. If you do not specify the /QUOTA qualifier, or if you specify /QUOTA=0, the table has unlimited quota.

/SUPERVISOR_MODE (default)

Creates a supervisor-mode logical name table. If you do not specify a mode, a supervisor-mode logical name table is created.

/USER_MODE

Creates a user-mode logical name table. If you do not explicitly specify a mode, a supervisor-mode logical name table is created.

Examples

$ UTLTOOLS CREATE/NAME_TABLE
$ SHOW LOGICAL LNM_JONES
     %SHOW-S-NOTRAN, no translation for logical name TEST_TAB 
$ SHOW LOGICAL/TABLE=LNM$PROCESS_DIRECTORY LNM_JONES
      

In this example, the UTLTOOLS CREATE/NAME_TABLE command creates a new table called LNM_JONES. By default, the name of the table is entered in the process directory. The first SHOW LOGICAL command does not find the name LNM_JONES because it does not, by default, search the process directory table. You must use the /TABLE qualifier to request that the process directory be searched.

$ UTLTOOLS CREATE/NAME_TABLE/ATTRIBUTES=CONFINE
$ DEFINE/TABLE=LNM_JONES MYDISK DISK4:
$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV -
_$ LNM_JONES, LNM$PROCESS, LNM$JOB, LNM$GROUP, LNM$SYSTEM
$ TYPE MYDISK:[JONES]EXAMPLE1.LIS
      

This example creates a new logical name table called LNM_JONES that is created with the CONFINE attribute. Therefore, the LNM_JONES table and the names it contains will not be copied to subprocesses.

Next, the logical name MYDISK is placed into the table LNM_JONES. To use the name MYDISK in file specifications, you must make sure that the table LNM_JONES is searched when RMS parses file specifications. To do this, you can define a process-private version of the logical name LNM$FILE_DEV to include the name LNM_JONES as one of its equivalence strings. (The system uses LNM$FILE_DEV to determine the tables to search during logical name translation for device or file specifications, and will use the process-private version of the logical name before using the default system version.) After you define LNM$FILE_ DEV, the system searches the following tables during logical name translation: LNM_JONES, your process table, your job table, your group table, and the system table. Now, you can use the name MYDISK in a file specification and the equivalence string DISK4 will be substituted.

Cancels a logical name assignment that was made with one of the following commands: ALLOCATE, ASSIGN, DEFINE, UTLTOOLS DEFINE or MOUNT. The UTLTOOLS DEASSIGN command also deletes a logical name table that was created with the CREATE/NAME_TABLE command.

Format

UTLTOOLS DEASSIGN logical-name

Parameters

logical-name

Specifies the logical name to be deassigned. Logical names can have from 1 to 255 characters. If the logical name contains any characters other than alphanumerics, dollar signs ($), or underscores (_), enclose it in quotation marks (" ").

Unlike the DCL DEASSIGN command, the UTLTOOLS DEASSIGN command doesn't ignore a trailing colon with the logical name.

To delete a logical name table, specify the table name as the logical-name parameter. You must also use the /TABLE qualifier to indicate the logical name directory table where the table name is entered.

Qualifiers

/CONTEXT

Indicates that the specified logical name is in the context logical name table. The /CONTEXT qualifier is synonymous with the /TABLE=LNM$CONTEXT qualifier.

Requires write (W) access to the context table to delete a name.

See CONTEXT for details about contexts.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege to deassign executive-mode logical names.

Deletes only entries that were created in the specified mode or an outer (less privileged) mode. If you do not have SYSPRV (system privilege) privilege for executive mode, a supervisor- mode operation is assumed.

/GROUP

Requires GRPNAM (group logical name) or SYSPRV privilege to delete entries from the group logical name table.

Indicates that the specified logical name is in the group logical name table. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.

/JOB

Indicates that the specified logical name is in the jobwide logical name table. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier. If you do not explicitly specify a logical name table, the default is the /PROCESS qualifier.

You should not deassign jobwide logical name entries that were made by the system at login time, for example, SYS$LOGIN, SYS$LOGIN_DEVICE, and SYS$SCRATCH. However, if you assign new equivalence names for these logical names (that is, create new logical names in outer access modes), you can deassign the names you explicitly created.

/KERNEL_MODE

Requires SYSNAM (system logical name) privilege to deassign kernel-mode logical names.

Deletes only entries that were created in the specified mode or an outer (less privileged) mode. If you do not have SYSPRV (system privilege) privilege for kernel mode, a supervisor- mode operation is assumed.

/PROCESS (default)

Indicates that the specified logical name is in the process logical name table. The /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.

You cannot deassign logical name table entries that were made by the command interpreter, for example, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR. However, if you assign new equivalence names for these logical names (that is, you create new logical names in outer access modes), you can deassign the names you explicitly created.

/SUPERVISOR_MODE (default)

Deletes entries in the specified logical name table that were created in supervisor mode. If you specify the /SUPERVISOR_MODE qualifier, the DEASSIGN command also deassigns user-mode entries with the same name.

/SYSTEM

Indicates that the specified logical name is in the system logical name table. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.

/TABLE=name

Specifies the table from which the logical name is to be deleted. Defaults to LNM$PROCESS. The table can be the process, group, job, or system table, one of the directory tables, or the name of a user-created table. (The process, job, group, and system logical name tables should be referred to by the logical names LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, respectively.)

The /TABLE qualifier also can be used to delete a logical name table. To delete a process-private table, enter the following command:

$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY table-name

To delete a shareable table, enter the following command:

$ DEASSIGN/TABLE=LNM$SYSTEM_DIRECTORY table-name

To delete a shareable logical name table, you must have delete (D) access to the table or write (W) access to the directory table in which the name of the shareable table is cataloged.

If you do not explicitly specify the /TABLE qualifier, the default is the /TABLE=LNM$PROCESS qualifier.

/USER_MODE

Deletes entries in the process logical name table that were created in user mode. If you specify the /USER_MODE qualifier, the DEASSIGN command can deassign only user-mode entries. Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

Examples

$ UTLTOOLS DEFINE/USER_MODE TM1 $DISK1:[ACCOUNTS.MEMOS]WATER.TXT
      

In this example, the UTLTOOLS DEFINE command defines TM1 as equivalent to a file specification. After the next image runs, the logical name TM1 is automatically deassigned.

$ UTLTOOLS DEFINE MEMO $DISK1:[ACCOUNTS.MEMO]
      

In this example, the UTLTOOLS DEFINE command defines the logical name MEMO as equivalent to the partial file specification $DISK1:[ACCOUNTS.MEMO].

$ UTLTOOLS DEFINE PROCESS_NAME  LIBRA
$ RUN WAKE
      

In this example, the UTLTOOLS DEFINE command places the logical name PROCESS_NAME in the process logical name table with an equivalence name of LIBRA. The logical name is created in supervisor mode. The program WAKE translates the logical name PROCESS_NAME to perform some special action on the process named LIBRA.

$ UTLTOOLS DEFINE TEMP:  XXX1: 
 . 
 . 
 .
$ DEASSIGN TEMP::
      

In this example, the UTLTOOLS DEFINE command creates an equivalence name for the logical name TEMP: and places the name in the process logical name table. The colon is retained as part of the logical name. The DEASSIGN command deletes the logical name. Note that two colons are required on the logical name in the DEASSIGN command. One colon is deleted by the DEASSIGN command. The other colon is kept as part of the logical name.

$ UTLTOOLS DEFINE PORTLAND PRTLND::YYY0:[DECNET.DEMO.COM]
      

In this example, the UTLTOOLS DEFINE command places the logical name PORTLAND in the process logical name table with an equivalence name of PRTLND::YYY0:[DECNET.DEMO.COM]. Subsequent references to the logical name PORTLAND result in the correspondence between the logical name PORTLAND and the node, disk, and subdirectory specified.

$ UTLTOOLS DEFINE LOCAL "BOSTON""JOHN_SMITH JKS""::"
      

In this example, the UTLTOOLS DEFINE command places the logical name LOCAL in the process logical name table with a remote node equivalence name of BOSTON"JOHN_SMITH JKS"::. To satisfy conventions for local DCL command string processing, you must use three sets of quotation marks. The quotation marks ensure that access control information is enclosed in one set of quotation marks in the equivalence name.

$ UTLTOOLS DEFINE MYDISK XXX0:[MYDIR], YYY0:[TESTDIR]
      

In this example, the UTLTOOLS DEFINE command places the logical name MYDISK in the process logical name table with two equivalence names: XXX0:[MYDIR] and YYY0:[TESTDIR].

$ CREATE/NAME_TABLE TABLE1
$ UTLTOOLS DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV -
_$ TABLE1,LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM
$ UTLTOOLS DEFINE/TABLE=TABLE1 -
_$ /TRANSLATION_ATTRIBUTES=CONCEALED   WORK_DISK DBA1:
      

In this example, the CREATE/NAME_TABLE command creates the process private logical name table TABLE1.

The first UTLTOOLS DEFINE command ensures that TABLE1 is searched first in any logical name translation of a device or file specification (because TABLE1 is the first item in the equivalence string for the logical name LNM$FILE_DEV, which determines the default search sequence of logical name tables whenever a device or file specification is translated).

The second UTLTOOLS DEFINE command assigns the logical name WORK_DISK to the physical device DBA1 and places the name in TABLE1. The logical name has the concealed attribute. Therefore, the logical name WORK_DISK is displayed in system messages.

$ CREATE/NAME_TABLE SPECIAL
$ UTLTOOLS DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV -
_$ SPECIAL,LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM
$ UTLTOOLS DEFINE/TABLE=LNM$PROCESS_DIRECTORY TAB SPECIAL
$ UTLTOOLS DEFINE/TABLE=TAB REPORT [CHELSEA]STORES
$ SHOW LOGICAL/TABLE=SPECIAL REPORT 
  "REPORT" = "[CHELSEA]STORES" (SPECIAL)
      

In this example, the CREATE/NAME_TABLE command is used to create a new logical name table called SPECIAL. This table is defined in the process directory, LNM$PROCESS_DIRECTORY.

The first UTLTOOLS DEFINE command ensures that SPECIAL is searched first in any logical name translation of a device or file specification (because SPECIAL is the first item in the equivalence string for the logical name LNM$FILE_DEV, which determines the default search sequence of logical name tables whenever a device or file specification is translated). The logical name LNM$FILE_DEV is placed in the process directory, LNM$PROCESS_DIRECTORY.

With the next UTLTOOLS DEFINE command, a new logical name, TAB, is defined. TAB translates to the string SPECIAL, which identifies a logical name table. You must define TAB in the process directory because it translates iteratively to a logical name table.

Next, the logical name REPORT is placed into the logical name table TAB. Because TAB translates to the table SPECIAL, the name REPORT is entered into SPECIAL table. The SHOW LOGICAL command verifies that the name REPORT has been entered into the table SPECIAL.

Note that you can redefine TAB so it translates to a different table. Therefore, if you run different programs that use the name TAB as a table name, you can change the actual tables where the names are entered or referenced.

Associates an equivalence name with a logical name. If you specify an existing logical name, the new equivalence name replaces the existing equivalence name.

• Associate an equivalence string and a set of attributes with a key on the terminal keyboard (see /KEY).
• Define a logical name using the old DEFxxx command format (See /V1).
• Define a logical name using a SysWorks variable value (See /VARIABLE).

Format

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

Parameters

logical-name

Specifies the logical name string, which is a character string containing from 1 to 255 characters. The following rules apply:

• If you specify an existing logical name, the new equivalence names replace the existing equivalence name.
• If the logical name is to be entered into the process or system directory logical name tables (LNM$PROCESS_DIRECTORY, LNM$SYSTEM_DIRECTORY), then the name can only have from 1 to 31 alphanumeric characters, including the dollar sign ($) and underscore (_).
• If you specify a colon (:) at the end of a logical name, the UTLTOOLS DEFINE command saves the colon as part of the logical name. By default, the logical name is placed in the process logical name table.
• If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks (" "). Use two sets of quotation marks ("" "") to denote actual quotation marks. When you enclose a name in quotation marks, the case of alphabetic characters is preserved.

equivalence-name

Specifies a character string containing from 1 to 255 characters. The following rules apply:

• If the string contains any characters other than uppercase alphanumerics, the dollar sign, or the underscore character, enclose the string in quotation marks. Use two sets of quotation marks to denote an actual quotation mark. Specifying more than one equivalence name for a logical name creates a search list.
• When you specify an equivalence name that will be used as a file specification, you must include the punctuation marks (colons, brackets, periods) that would be required if the equivalence name were used directly as a file specification. Therefore, if you specify a device name as an equivalence name, you must terminate the equivalence name with a colon.

The UTLTOOLS DEFINE command allows you to assign the same logical name to more than one equivalence name. For example, you can use the same logical name to access different directories on different disks or to access different files in different directories.

When you specify more than one equivalence name for a logical name, you create a search list. See the OpenVMS User's Manual for more information on search lists.

Qualifiers

/CHECK[=code]

Specifies what type of checking and conversion if any is performed on the equivalences before the logical name is defined. Possibles codes are as follows:

BEST_FIT
IF_PRESENT	The logical name is only defined if all the object(s) specified by the equivalence(s) exist. No messages are displayed if the logical name is not defined.
NONE	No checking or conversion is performed.
REQUIRED	The object(s) specified by the equivalence(s) must exist. An error message is displayed for any which are not found, and the logical name will not be defined.

/CONTEXT

Requires write (W) access to the context table to specify the name.

Places the logical name in the context logical name table. Other users who use the same context can access the logical name. Using /CONTEXT qualifier is similar to using the /TABLE=LNM$CONTEXT qualifier.

See CONTEXT for details about contexts.

This qualifier is incompatible with the /GROUP, /JOB, /PROCESS, /SYSTEM and /TABLE qualifiers.

/DEVICE

Specifies that the equivalence(s) are devices for the purpose of checking when /CHECK=code is used and code is not NONE.

This qualifier is incompatible with the /DIRECTORY, /FILE and /NODE qualifiers.

/DIRECTORY

Specifies that the equivalence(s) are directories for the purpose of checking when /CHECK=code is used and code is not NONE.

This qualifier is incompatible with the /DEVICE, /FILE and /NODE qualifiers.

/EXECUTIVE_MODE

Requires SYSNAM (system logical name) privilege to create an executive-mode logical name.

Creates an executive-mode logical name in the specified table.

If you specify the /EXECUTIVE_MODE qualifier and you do not have SYSNAM privilege, the UTLTOOLS DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.

This qualifier is incompatible with the /KERNEL_MODE, /SUPERVISOR_MODE and /USER_MODE qualifiers.

/FILE

Specifies that the equivalence(s) are files for the purpose of checking when /CHECK=code is used and code is not NONE.

This qualifier is incompatible with the /DEVICE, /DIRECTORY and /NODE qualifiers.

/GROUP

Requires GRPNAM (group logical name) or SYSNAM (system logical name) privilege to place a name in the group logical name table.

Places the logical name in the group logical name table. Other users who have the same group number in their user identification codes (UICs) can access the logical name. The /GROUP qualifier is synonymous with the /TABLE=LNM$GROUP qualifier.

This qualifier is incompatible with the /CONTEXT, /JOB, /PROCESS, /SYSTEM and /TABLE qualifiers.

/INDEX=number

/NOINDEX (default)

Specifies whether a logical name is completely redefined or only some equivalences should be changed.

By default, /NOINDEX is assumed which indicates that the logical name is defined with the equivalences specified.

If /INDEX=number is used, equivalnces starting with the specified index are replaced. If the index number is greater that the current number of equivalnces, the new equivalences are placed at the end of the list. Thus, use of this qualifier to define the initial value of a logical name always results in the same behaviour as if the /INDEX qualifier had not been used.

/JOB

Places the logical name in the jobwide logical name table. All processes in the same job tree as the process that created the logical name can access the logical name. The /JOB qualifier is synonymous with the /TABLE=LNM$JOB qualifier.

This qualifier is incompatible with the /CONTEXT, /GROUP, /PROCESS, /SYSTEM and /TABLE qualifiers.

/KERNEL_MODE

Requires SYSNAM (system logical name) privilege to create an kernel-mode logical name.

Creates an kernel-mode logical name in the specified table.

If you specify the /KERNEL_MODE qualifier and you do not have SYSNAM privilege, the UTLTOOLS DEFINE command ignores the qualifier and creates a supervisor-mode logical name. The mode of the logical name must be the same or less privileged than the mode of the table in which you are placing the name.

This qualifier is incompatible with the /EXECUTIVE_MODE, /SUPERVISOR_MODE and /USER_MODE qualifiers.

/LITERAL

Specifies that the equivalence values are defined as presented and not translated in any way. This does not affect the checking of the equivalence, its just stops the result of the checking being used as the equivalence value. To stop checking, use the /NOCHECK qualifier, which is the default behaviour.

---

Previous

Next

Contents

Index