SysWorks©

SysWorks
Command Reference Manual
Previous Contents Index

Use of /CHECK=IF_PRESENT is conjuntion with /LITERAL is useful for defining a logical name only if a file exists, but leaving the equivalence in its orignal unsearched form.

If the UTLTOOLS DEFINE/V1 command is used, however, the /LITERAL does stop checking. This is to ensure compatibility with the old DEFxxx commands.

This qualifier is incompatible with the /ROOT qualifier.

/LOG (default)

/NOLOG

Displays a message when a new logical name supersedes an existing name.

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

Specifies attributes for a logical name. By default, no attributes are set. Possible keywords are as follows:
CONFINE The logical name is not copied into a spawned subprocess. This qualifier is relevant only for logical names in a private table.

The logical name inherits the CONFINE attribute from the logical name table where it is entered; if the logical name table is "confined," then all names in the table are "confined."

NO_ALIAS A logical name cannot be duplicated in the specified table in a less privileged access mode; any previously created identical names in an outer (less privileged) access mode within the specified table are deleted.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.

/NODE

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

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

/ORIGINAL_TABLE=name

Specifies the logical name table in which the original equivalences are defined. This table is used in conjunction with the /INDEX qualifier to indicate that the logical name for the original equivalences exists in a different table to the new logical name.

This qualifier can only be used if /INDEX is also used.

/PROCESS (default)

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

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

/QUOTE (default)

/NOQUOTE

Specifies whether equivalence values written to DCL command procedures are enclosed in quotation marks.

By default, equivalence values are placed in quotation marks.

/ROOT

/NOROOT (default)

Specifies whether an equivalence should be converted into a root directory form. This is only useful when /CHECK=code is used, code is not NONE and /DIRECTORY is used or inferred.

If /ROOT is used and all other qualifier and search criteria are met, the equivalence(s) may be converted to an unconcealed equivalent, have any close and open square bracket pair removed (i.e. the leftover from pasring with an existing concealed logical) and have a period placed before the closing square bracket of the directory specification. If this is done, an effective /TRANSLATION_ATTRIBUTES=(CONCEALED,TERMINAL) is then applied to the equivalence.

Note that an equivalence which is a device or already a directory root logical name (i.e. looks like a device) is left as is.

This qualifier is incompatible with the /LITERAL qualifier.

/SEARCHLIST

/NOSEARCHLIST (default)

Specifies whether an equivalence based on a search list should have each item in the search list checked (/SEARCHLIST) or use the standard RMS parsing model which is to find the first match (/NOSEARCHLIST).

When /SEARCHLIST is used, the resultant logical name has an equivalence defined for each search list item match, and may therefore have more equivalences than there were parameter values.

By default, /NOSEARCHLIST is assumed.

/SEPARATE[={ALL|SOME}]

/NOSEPARATE (default)

Specifies whether equivalences with explicit or implied concealed translation attribute should be converted into additional logical names.

If /SEPARATE=SOME is used, the first such equivalence is not converted since it effectively uses the logical name being defined. Subsequent concealed equivalences are define using logical names based on the specified parameter with _1, _2 etc applied as a suffix. These additional logical names are then used as the actual equivalence of the logical name parameter. See the examples below to see the results of using this qualifier.

If /SEPARATE=ALL is used, all such equivalences are converted. This is useful when it is necessary to have the parsed form of a directory be different to the unparsed form. An example of this is when some operations should only be performed on the first entry in a search list (such as a wildcard directory operation leading to a write or delete action), while others (such as reading information) use the whole search list.

/SUPERVISOR_MODE (default)

Creates a supervisor-mode logical name in the specified table. The mode of the logical name must be the same as or less privileged than the mode of the table in which you are placing the name.

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

/SYSTEM

Requires write (W) access or SYSNAM (system logical name) privilege to place a name in the system logical name table.

Places the logical name in the system logical name table. All system users can access the logical name. The /SYSTEM qualifier is synonymous with the /TABLE=LNM$SYSTEM qualifier.

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

/TABLE=name

Requires write (W) access to the table to specify the name of a shareable logical name table.

Specifies the name of the logical name table in which the logical name is to be entered. You can use the /TABLE qualifier to specify a user-defined logical name table (created with the CREATE/NAME_TABLE command); to specify the process, job, group, or system logical name tables; or to specify the process or system logical name directory tables.

If you specify the table name using a logical name that has more than one translation, the logical name is placed in the first table found. For example, if you specify UTLTOOLS DEFINE/TABLE=LNM$FILE_ DEV and LNM$FILE_DEV is equated to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the logical name is placed in LNM$PROCESS.

The default is the /TABLE=LNM$PROCESS qualifier.

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

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

Equivalence-name qualifier.

Specifies one or more attributes that modify an equivalence string of the logical name. Possible keywords are as follows:
CONCEALED Indicates that the equivalence string is the name of a concealed device. When a concealed device name is defined, the system displays the logical name, rather than the equivalence string, in messages that refer to the device.
TERMINAL Logical name translation should terminate with the current equivalence string; indicates that the equivalence string should not be translated iteratively.

If you specify only one keyword, you can omit the parentheses. Only the attributes you specify are set.

Note that different equivalence strings of a logical name can have different translation attributes.

/USER_MODE

Creates a user-mode logical name in the specified table.

User-mode logical names created within the process logical name tables are used for the execution of a single image; for example, you can create a user-mode logical name to allow an image executing in a command procedure to redefine SYS$INPUT. User-mode entries are deleted from the process logical name table when any image executing in the process exits (that is, after a DCL command or user program that executes an image completes execution). Also, user-mode logical names are automatically deleted when invoking and exiting a command procedure.

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

Examples

#1 

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

#2 

$ 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].

#3 

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

#4 

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

#5 

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

#6 

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

#7 

$ 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].

#8 

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

#9 

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

#10 

$ UTLTOOLS DEFINE/CHECK=REQUIRED/CONTEXT -
_$ FIN_DAT_DIR DISK_DEV:[FIN.DAT]
$ UTLTOOLS DEFINE/CHECK=REQUIRED/CONTEXT -
_$ FIN_DAT_1_DIR DISK_DEV:[FIN.DAT1]
$ UTLTOOLS DEFINE/CHECK=REQUIRED/CONTEXT/ROOT FIN_DAT_ROOT -
_$ DISK_DEV:[FIN.DAT],DISK_DEV:[FIN.DAT1]
$ SHOW LOGICAL FIN_DAT*/FULL/TABLE=LNM_FIN_DEV
    . 
    . 
    . 
  "FIN_DAT_1_DIR" [super] = "DISK_DEV3:[FIN.DAT1]" 
  "FIN_DAT_DIR" [super] = "DISK_DEV4:[FIN.DAT]" 
  "FIN_DAT_ROOT" [super] = "$1$DKA500:[DEV_3.FIN.DAT.]" [concealed,terminal] 
        = "$1$DKA700:[DEV_4.FIN.DAT1.]" [concealed,terminal]
$ UTLTOOLS DEFINE/CHECK=REQUIRED/CONTEXT/ROOT/SEPARATE=SOME FIN_DAT_ROOT -
_$ DISK_DEV:[FIN.DAT],DISK_DEV:[FIN.DAT1]
$ SHOW LOGICAL FIN_DAT*/FULL/TABLE=LNM_FIN_DEV
    . 
    . 
    . 
  "FIN_DAT_1_DIR" [super] = "DISK_DEV4:[FIN.DAT1]" 
  "FIN_DAT_DIR" [super] = "DISK_DEV3:[FIN.DAT]" 
  "FIN_DAT_ROOT" [super] = "$1$DKA500:[DEV_3.FIN.DAT.]" [concealed,terminal] 
        = "FIN_DAT_ROOT_1:" 
  "FIN_DAT_ROOT_1" [super] = "$1$DKA700:[DEV_4.FIN.DAT1.]" [concealed,terminal]
$ UTLTOOLS DEFINE/CHECK=REQUIRED/CONTEXT/ROOT/SEPARATE=ALL FIN_DAT_ROOT -
_$ DISK_DEV:[FIN.DAT],DISK_DEV:[FIN.DAT1]
$ SHOW LOGICAL FIN_DAT*/FULL/TABLE=LNM_FIN_DEV
    . 
    . 
    . 
  "FIN_DAT_1_DIR" [super] = "DISK_DEV4:[FIN.DAT1]" 
  "FIN_DAT_DIR" [super] = "DISK_DEV3:[FIN.DAT]" 
  "FIN_DAT_ROOT" [super] = "FIN_DAT_ROOT_0:" 
          = "FIN_DAT_ROOT_1:" 
  "FIN_DAT_ROOT_0" [super] = "$1$DKA500:[DEV_3.FIN.DAT.]" [concealed,terminal] 
  "FIN_DAT_ROOT_1" [super] = "$1$DKA700:[DEV_4.FIN.DAT1.]" [concealed,terminal]

This example shows the difference in behaviour when the /SEPARATE qualifier is used. Note that the first definition of FIN_DAT_ROOT has two concealed equivalences which results in a root logical name which makes its sub-directory and file structure appear as a single directory. The second definition results in a form which can distinguish between sub-directories with the same name but located in different root mush like the standard OpenVMS SYS$SYSROOT logical name.

UTLTOOLS DEFINE/KEY

Defines a key to execute a command. This enables you to press a key to enter a command instead of typing the command name.

Format

UTLTOOLS DEFINE/KEY key-name "string"

Parameters

key-name

Specifies the name of the key you are defining. Use the following key names when defining keys:

Key Name VT100 VT52 LK201
PF1 PF1 red key PF1
PF2 PF2 blue key PF2
PF3 PF3 black key PF3
PF4 PF4 - PF4
KP0, KP1-KP9 keypad 0-9 keypad 0-9 keypad 0-9
Period period key period key period key
Comma comma key comma key comma key
Minus minus key minus key minus key
Enter ENTER key ENTER key ENTER key
E1,E2 - - Find,Insert Here
E3,E4 - - Remove,Select
E5 - - Previous Screen
E6 - - Next Screen
Help,Do - - Help(15), Do(16)
F17-F20 - - Function Keys

Note
You cannot redefine the arrow keys or the function keys F1 to F14.

"string"

Specifies the string you want entered when you press the defined key. "String" can be a UTLTOOLS command, for example, DIRECTORY or SET FILE.

Qualifiers

/ECHO

/NOECHO

Specifies whether the command line is visible on the screen after you press the defined key. You cannot define a key specifying both the /NOECHO and /NOTERMINATE qualifiers. The default qualifier is /ECHO.

/IF_STATE=state_list

/NOIF_STATE

Specifies a list of states, any one of which must be set in order to enable the specified key definition. If you omit or negate this qualifier, the current state prevails.

States are used to increase the number of key definitions available on your terminal. The same key can be assigned any number of definitions as long as each definition is associated with a different state. State names can be any alphanumeric string.

/LOCK_STATE

/NOLOCK_STATE

Retains the state specified by the /SET_STATE qualifier until you use the /SET_STATE qualifier again to change it. The default qualifier is /NOLOCK_STATE.

States are used to increase the number of key definitions available on your terminal. The same key can be assigned any number of definitions as long as each definition is associated with a different state. State names can be any alphanumeric string.

/LOG

/NOLOG

Specifies whether informational messages are displayed. These messages signal successfully created key definitions. The default qualifier is /LOG.

/SET_STATE=state

/NOSET_STATE

Associates a state with the key you are defining. A state name can be any alphanumeric string. If you omit or negate this qualifier, the current state remains unchanged. You cannot define a key specifying both the /SET_STATE and /TERMINATE qualifiers.

States are used to increase the number of key definitions available on your terminal. The same key can be assigned any number of definitions as long as each definition is associated with a different state.

/TERMINATE

/NOTERMINATE (default)

Determines whether the specified command string executes when you press the key. When you use the /NOTERMINATE qualifier, you must press the Return key to execute the command string. You cannot define a key specifying both the /SET_STATE and /TERMINATE qualifiers.

Examples

#1 

UTLTOOLS> DEFINE/KEY PF1 "DIRECTORY"

This example shows how to define the keypad key PF1 as the DIRECTORY command. To enter the DIRECTORY command, press PF1 followed by the Return key.

#2 

UTLTOOLS> DEFINE/KEY KP6 "EDIT" /TERMINATE

This example shows how to define the keypad key 6 (KP6) as the EDIT command. The /TERMINATE qualifier causes the EDIT command to execute when you press KP6; you do not have to press the Return key.

#3 

UTLTOOLS> DEFINE/KEY PF2 "SET "/SET_STATE=ALTERED
UTLTOOLS> DEFINE/KEY PF3 "FILE" /IF_STATE=ALTERED /TERMINATE

In this example, the PF2 key is defined as the SET command, with the state name ALTERED. Then, the PF3 key is defined to output the string FILE when the state ALTERED is specified.

The /TERMINATE qualifier is used to end the command line. When you specify the /TERMINATE qualifier, you can avoid pressing the Return key to execute the command line. After you define PF2 and PF3, you can use them together. Press PF2 to produce the first half of the command line (SET) and press PF3 to finish the command line (FILE).

#4 

UTLTOOLS> DEFINE/KEY PF4 "SET " /SET_STATE=ALTERED
UTLTOOLS> DEFINE/KEY KP7 "FILE" /TERMINATE /IF_STATE=ALTERED
UTLTOOLS> DEFINE/KEY KP8 "FORWARD" /TERMINATE /IF_STATE=ALTERED
UTLTOOLS> DEFINE/KEY KP9 "WASTEBASKET" /TERMINATE /IF_STATE=ALTERED

This example shows how to define four different keys and associate them with a state named ALTERED:

  1. The first definition defines the key PF4 as the SET command and associates this key with a state named ALTERED.
  2. The second definition defines the keypad key 7 as "FILE" and makes it dependent on a state named ALTERED. When you press PF4 followed by keypad key 7, UTLTOOLS executes the SET FILE command.
  3. The third definition defines keypad key 8 as "FORWARD" and also makes it dependent on the ALTERED state. When you press PF4 followed by keypad key 8, UTLTOOLS executes the SET FORWARD command.
  4. The fourth definition defines keypad key 9 as "WASTEBASKET" and also makes it dependent on the ALTERED state. When you press PF4 followed by keypad key 9, UTLTOOLS executes the SET WASTEBASKET command.

Previous Next Contents Index