HELP DEFINE — VMS 5.0
Creates a logical name entry and assigns an equivalence name string,
or a list of strings, to the specified logical name.
o Define a characteristic name for the system queues (see
/CHARACTERISTIC).
o Define a form name and number and the characteristics of the
physical paper stock for printer and terminal queues (see /FORM).
o Associate an equivalence string and a set of attributes with a
key on the terminal keyboard (see /KEY).
Format:
DEFINE logical-name equivalence-name[,...]
Additional information available:
ParametersCommand QualifiersExamples
Parameters
logical-name
Specifies the logical name string. The logical name string can
contain from 1 to 255 characters. (However, logical names entered
in one of the logical name directory tables, LNM$SYSTEM_DIRECTORY or
LNM$PROCESS_DIRECTORY, must be no more than 31 characters long, and
must not contain characters other than alphanumerics, the dollar
sign, or the underscore.) If you specify a colon at the end of a
logical name, the DEFINE command saves the colon as part of the
logical name. (This is in contrast to the ASSIGN command, which
removes the colon before placing the name in a logical name table.)
By default, the logical name is placed in the process logical name
table.
If the string contains any characters other than alphanumerics, the
dollar sign, or the underscore character, enclose the string in
quotation marks. If the logical name contains quotation marks,
enclose the name in quotation marks and use two sets of quotation
marks ("") in the places where you want a quotation mark (") to
occur. Note that if you enclose a name in quotation marks, the case
of alphabetic characters is preserved.
equivalence-name[,...]
Defines the equivalence names to be associated with the logical name
in the specified logical name table. An equivalence name string can
contain from 1 to 255 characters. If the string contains any
characters other than alphanumerics, the dollar sign, or the
underscore character, enclose the string in quotation marks. If the
equivalence name contains quotation marks, enclose the string in
quotation marks and use two sets of quotation marks ("") in the
places where you want a quotation mark (") to occur.
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 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 VMS DCL Concepts Manual for more
information on search lists.
Command Qualifiers
Additional information available:
/EXECUTIVE_MODE/GROUP/JOB/LOG/NAME_ATTRIBUTES
/PROCESS/SUPERVISOR_MODE/SYSTEM/TABLE/TRANSLATION_ATTRIBUTES
/USER_MODE
/EXECUTIVE_MODE
/EXECUTIVE_MODE Requires the user privilege SYSNAM 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, then the DEFINE command ignores the qualifier and creates a supervisor mode logical name.
/GROUP
/GROUP Requires the user privilege GRPNAM or SYSPRV 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 UICs (user identification codes) can access the logical name. The /GROUP qualifier is synonymous with /TABLE=LNM$GROUP.
/JOB
/JOB Places the logical name in the job-wide 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 /TABLE=LNM$JOB.
/LOG
/LOG (default) /NOLOG Controls whether a message is displayed when you define a logical name that supersedes an existing name.
/NAME_ATTRIBUTES
/NAME_ATTRIBUTES[=(keyword[,...])]
Specifies attributes for a logical name. By default, no attributes
are set. You can specify the following keywords for attributes:
CONFINE The name is not to be copied into a subprocess by the
SPAWN command. This keyword is meaningful only when you
create logical names in a private table. If you specify
this keyword for a logical name in a shareable table, it
is ignored.
The CONFINE attribute is also inherited from the logical
name table where the name is entered; if the logical
name table is "confined", then all names in the table
are "confined".
NO_ALIAS The logical name cannot be duplicated in this table with a
less privileged (outer) access mode. If another logical
name with the same name and an outer access mode already
exists in this table, the name is deleted.
If you specify only one keyword, you can omit the parentheses. Only
the attributes you specify are set.
/PROCESS
/PROCESS (default) Places the logical name in the process logical name table. The /PROCESS qualifier is synonymous with /TABLE=LNM$PROCESS.
/SUPERVISOR_MODE
/SUPERVISOR_MODE (default) Creates a supervisor mode logical name in the specified table.
/SYSTEM
/SYSTEM Requires the user privilege SYSNAM or SYSPRV 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 /TABLE=LNM$SYSTEM.
/TABLE
/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 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. If you do not explicitly specify the /TABLE qualifier, the default is /TABLE=LNM$PROCESS (or /PROCESS).
/TRANSLATION_ATTRIBUTES
/TRANSLATION_ATTRIBUTES[=(keyword[,...])]
Equivalence-name qualifier.
Specifies one or more attributes that modify an equivalence string
of the logical name. You can specify the following keywords for
translation attributes:
CONCEALED Indicates that the equivalence string is a concealed
device name. 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 Indicates that the equivalence string should not be
translated iteratively; logical name translation should
terminate with the current equivalence string.
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
/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 any DCL command or user program that executes an image completes execution).
Examples
1. $ DEFINE CHARLIE XXX1:[CHARLES]
$ PRINT CHARLIE:TEST.DAT
Job 274 entered on queue SYS$PRINT
The DEFINE command associates the logical name CHARLIE with the
directory name [CHARLES] on the disk XXX1. Subsequent references to
the logical name CHARLIE result in the correspondence between the
logical name CHARLIE and the disk and directory specified. The
PRINT command queues a copy of the file XXX1:[CHARLES]TEST.DAT to
the system printer.
2. $ DEFINE PROCESS_NAME LIBRA
$ RUN WAKE
The 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.
3. $ DEFINE TEMP: XXX1:
.
.
.
$ DEASSIGN TEMP::
The 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 stripped by the
DEASSIGN command. The other colon is kept as part of the logical
name.
4. $ DEFINE PORTLAND PRTLND::YYY0:[DECNET.DEMO.COM]
The DEFINE command places the logical name PORTLAND in the process
logical name table with an equivalence name of
PRTLND::YYY0:[DECNET.DEMO.COM].
5. $ DEFINE LOCAL "BOSTON""JOHN_SMITH JKS""::"
The 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, so that access control information will be enclosed in one
set of quotation marks in the equivalence name.
/CHARACTERISTIC
Defines a characteristic name and associated characteristic number
in the system characteristics table. If the characteristic name is
already defined, the request alters the definition of the
characteristic. The /CHARACTERISTIC qualifier is required.
Format:
DEFINE/CHARACTERISTIC characteristic-name characteristic-number
Additional information available:
Parameters
characteristic-name Assigns a name to the characteristic being defined. Characteristic names can have from 1 to 31 characters, including all upper and lower case letters, digits, the dollar sign, and the underscore. The name, however, must contain at least one non-numeric character. characteristic-number Assigns a number to the characteristic being defined. Numbers can range from 0 to 127.
/FORM
Defines a form name and number as well as the type of the physical
paper stock. If the form name is already defined, DEFINE/FORM
alters the definition of the form. Each form must have a unique
number. The /FORM qualifier is required.
Format:
DEFINE/FORM form-name form-number
Additional information available:
Parameters
form-name Assigns a name to the form being defined. Form names can have from 1 to 31 characters, including all upper and lowercase letters, digits, the dollar sign, and the underscore. The name, however, must contain at least one non-numeric character. form-number Assigns a number to the form being defined. Numbers can range from 0 to 999. The DEFAULT form, which is automatically defined when the system is bootstrapped is assigned number 0.
Command Qualifiers
Additional information available:
/DESCRIPTION/LENGTH/MARGIN/PAGE_SETUP/SETUP
/SHEET_FEED/STOCK/TRUNCATE/WRAP/WIDTH
/DESCRIPTION
/DESCRIPTION=string Specifies a string of up to 255 characters. The default string is the specified form name. The string can be used to define the form type more specifically. For example, if you have form names such as LETTER1, LETTER2, and LETTER3, the /DESCRIPTION qualifier could be used to let the users and operators know that LETTER1 refers to the standard corporate letterhead paper (8.5 x 11), LETTER2 refers to the smaller corporate letterhead paper (6 x 9), and LETTER3 refers to the president's personalized letterhead paper.
/LENGTH
/LENGTH=n Specifies the physical length of a form page in lines. The default page length is 66 lines, which assumes a standard page length of 11 inches with 6 lines of print per inch. The n parameter must be a positive integer greater than 0 and not more than 255. The print symbiont sets the page length of the device equal to the form length. This enables the driver to compute the number of line feeds for devices lacking mechanical form feed.
/MARGIN
/MARGIN=(option[,...])
Specifies one or more of the four margin options: BOTTOM, LEFT,
RIGHT, and TOP.
BOTTOM=n Specifies the number of blank lines to leave between
the end of the print image on a page and the end
of the physical page of paper. The n parameter
must be a positive integer that is less than the
/LENGTH parameter. The default value is 6, which
generally means a one-inch bottom margin.
LEFT=n Specifies the number of columns to be left blank
between the leftmost printing position and the
actual print image area. The n parameter must be a
positive integer that is between 0 and the value
of the /WIDTH parameter. The default value is 0,
which means that the print image area starts as
far to the left of the paper as the printer can
go.
RIGHT=n Specifies the number of columns to be left blank
between the /WIDTH setting and the actual print
image area. The n parameter must be a positive
integer that is between 0 and the value of the
/WIDTH parameter. When determining the /RIGHT
parameter, start at the /WIDTH value and count to
the left. The default value is 0, which means that
the print image extends as far to the right as the
/WIDTH value.
TOP=n Specifies the number of blank lines to leave between
the top of the physical page of paper and the
start of the print image. The n parameter must be
a positive integer between 0 and the /LENGTH
parameter. The default value is 0, which generally
means that there is no top margin.
/PAGE_SETUP
/PAGE_SETUP=(module[,...]) /NOPAGE_SETUP (default) Specifies one or more modules that set up the device before every page. The modules are located in the device control library. When a new page is detected, the system extracts the appropriate modules from the device control library and copies them to the printer before the page is printed.
/SETUP
/SETUP=(module[,...]) Specifies one or more modules that set up the device appropriately for the specified form. The modules are located in the device control library. When the form is mounted, the system extracts the appropriate modules from the device control library and copies them to the printer before the file is printed.
/SHEET_FEED
/SHEET_FEED /NOSHEET_FEED (default) Specifies that the output print symbiont pause at the end of every physical page so that a new piece of paper can be inserted.
/STOCK
/STOCK=string Enables you to specify a type of paper stock to be associated with the form you are defining. The default for string is the form name. This qualifier is useful when you have several forms that use the same paper stock, but differ in other ways, such as margin specifications, wrapping, or page dimension. The system will change from one form to another automatically if those forms have an identical /STOCK qualifier. If the /STOCK qualifiers are different, you need to stop the queue, change the form, and restart the queue to print on another stock. The string parameter with /STOCK can be from 1 to 31 characters, including all letters, all digits, the dollar sign, and the underscore. You can create any string that you want. However, when you are creating forms with the same stock, be sure that the /STOCK string is identical in all the DEFINE/FORM commands that refer to the same type of paper.
/TRUNCATE
/TRUNCATE (default) /NOTRUNCATE Determines how the printer will accommodate lines that exceed either the /WIDTH value or the /MARGIN=RIGHT value. If you specify /TRUNCATE, the default, the printer will discard any characters that exceed the line length that is currently in effect. If you specify /TRUNCATE, you cannot specify /WRAP. The /TRUNCATE qualifier forces /NOWRAP. If you specify both /NOTRUNCATE and /NOWRAP, the printer prints all characters on a line insofar as it is able. This combination of qualifiers is useful for some types of graphics output.
/WRAP
/WRAP /NOWRAP (default) Determines how the printer will accommodate lines that exceed either the /WIDTH value or the /MARGIN=RIGHT value. The /WRAP qualifier causes print lines that exceed the current line length to wrap onto the next line. If you specify /WRAP, you cannot specify /TRUNCATE. The /WRAP qualifier forces /NOTRUNCATE. If you specify both /NOWRAP and /NOTRUNCATE, the printer prints all characters on a line insofar as it is able. This combination of qualifiers is useful for some types of graphics output.
/WIDTH
/WIDTH=n Specifies the physical width of the paper in terms of columns or character positions. Any lines exceeding this value will be wrapped if /WRAP is in effect or truncated if /TRUNCATE is in effect. (If both /NOTRUNCATE and /NOWRAP are in effect, lines will be printed as far as is possible.) If the /MARGIN=RIGHT qualifier has been specified, its value overrides the /WIDTH value in determining when lines of text will be wrapped. The n parameter must be a positive integer greater than 0 and not more than 65535. The default value for n is 132.
/KEY
Associates an equivalence string and a set of attributes with a key
on the terminal keyboard. The /KEY qualifier is required.
Format:
DEFINE/KEY key-name equivalence-string
Additional information available:
ParametersCommand QualifiersExamples
Parameters
key-name
Specifies the name of the key that you are defining. The following
table lists the key names in column one. The remaining three
columns indicate the key designations on the keyboards for the three
different types of terminals that allow key definitions. All
definable keys on VT52 terminals are located on the numeric keypad.
On VT100-type terminals, you can define the LEFT and RIGHT arrow
keys as well as all the keys on the numeric keypad. There are three
types of keys that can be defined on terminals with LK201 keyboards:
(1) keys on the numeric keypad, (2) keys on the editing keypad
(except the UP and DOWN arrow keys), and (3) keys on the function
key row across the top of the terminal. (Note that you cannot
define function keys F1 through F5.)
Key-name LK201 VT100-type VT52
PF1 PF1 PF1 [blue]
PF2 PF2 PF2 [red]
PF3 PF3 PF3 [gray]
PF4 PF4 PF4 - -
KP0, KP1, ..., KP9 0, 1, ..., 9 0, 1, ..., 9
0, 1, ..., 9
PERIOD . . .
COMMA , , n/a
MINUS - - n/a
ENTER Enter ENTER ENTER
LEFT <-- <-- <--
RIGHT --> --> -->
Find (E1) Find - - - -
Insert Here (E2) Insert Here - - - -
Remove (E3) Remove - - - -
Select (E4) Select - - - -
Prev Screen (E5) Prev Screen - - - -
Next Screen (E6) Next Screen - - - -
HELP Help - - - -
DO Do - - - -
F6, F7, ..., F20 F6, F7, ..., F20 - - - -
Some defineable keys are enabled for definition all the time.
Others, including KP0 through KP9, PERIOD, COMMA, and MINUS, need to
be enabled for definition purposes. You must issue either the SET
TERMINAL/APPLICATION or SET TERMINAL/NONUMERIC command before using
these keys.
The LEFT and RIGHT arrow keys and the F6 through F14 VT200 keys are
reserved for command line editing. You must issue the SET
TERMINAL/NOLINE_EDITING command before defining these keys. You can
also press CTRL/V to enable keys F7 through F14. Note that CTRL/V
will not enable the F6 key.
equivalence-string
Specifies the string which is to be processed when you press the
key. If the string contains any spaces, enclose the equivalence
string in quotation marks.
Command Qualifiers
Additional information available:
/ECHO/ERASE/IF_STATE/LOCK_STATE/LOG/SET_STATE
/TERMINATE
/ECHO
/ECHO (default) /NOECHO Determines whether the equivalence string is displayed on your screen after the key has been pressed. You cannot use /NOECHO with the /NOTERMINATE qualifier.
/ERASE
/ERASE /NOERASE (default) Determines whether the current line is erased before the key translation is inserted.
/IF_STATE
/IF_STATE=(state-name,...) /NOIF_STATE Specifies a list of one or more states, one of which must be in effect for the key definition to be in effect. If you omit the /IF_STATE qualifier or use /NOIF_STATE, the current state is used. The state name is an alphanumeric string. States are established with the /SET_STATE qualifier or the SET KEY command. If you specify only one state name, you can omit the parentheses. By including several state names, you can define a key to have the same function in all the specified states.
/LOCK_STATE
/LOCK_STATE /NOLOCK_STATE (default) Specifies that the state set by the /SET_STATE qualifier remain in effect until explicitly changed. If you use the /NOLOCK_STATE qualifier, the state set by /SET_STATE is in effect only for the next defineable key that you press or for the next read terminating character that you type. The /LOCK_STATE qualifier can only be specified with the /SET_STATE qualifier.
/LOG
/LOG (default) /NOLOG Controls whether the system displays a message indicating that the key definition has been successfully created.
/SET_STATE
/SET_STATE=state-name /NOSET_STATE (default) Causes the specified state-name to be set when the key is pressed. The state name can be any alphanumeric string. If you omit the SET_STATE qualifier or use /NOSET_STATE, the current state that was locked remains in effect. If you have not included this qualifier with a key definition, you can use the SET KEY command to change the current state.
/TERMINATE
/TERMINATE /NOTERMINATE (default) Specifies whether the current equivalence string is to be terminated (that is, processed) when the key is pressed. Pressing RETURN has the same effect as using /TERMINATE. The /NOTERMINATE qualifier allows you to create key definitions that insert text into command lines, after prompts, or into other text that you are typing.
Examples
1. $ DEFINE/KEY PF3 "SHOW TIME" /TERMINATE
%DCL-I-DEFKEY, DEFAULT key PF3 has been defined
$ SHOW TIME
15-APR-1984 14:43:59
The DEFINE/KEY command defines the PF3 key on the keypad to perform
the SHOW TIME command. DEFAULT refers to the default state.
2. $ DEFINE/KEY PF1 "SHOW " /SET_STATE=GOLD/NOTERMINATE/ECHO
%DCL-I-DEFKEY, DEFAULT key PF1 has been defined
$ DEFINE/KEY PF1 " DEFAULT" /TERMINATE/IF_STATE=GOLD/ECHO
%DCL-I-DEFKEY, GOLD key PF1 has been defined
$ SHOW DEFAULT
DISK1:[JOHN.TEST]
The first DEFINE/KEY command defines the PF1 key to be the string
SHOW. The state is set to GOLD for the subsequent key. The
/NOTERMINATE qualifier instructs the system not to process the
string when the key is pressed. The second DEFINE/KEY command
defines the use of the PF1 key when the keypad is in the GOLD state.
When the keypad is in the GOLD state, pressing PF1 will cause the
current read to be terminated.
If you press the PF1 key twice, the system displays and processes
the SHOW DEFAULT command.
The word DEFAULT in the second line of the example refers to the
fact that the key PF1 has been defined in the default state. Note
the space before the word DEFAULT in the second DEFINE/KEY command.
If the space is omitted, the system fails to recognize DEFAULT as
the keyword for the SHOW command.
3. $ SET KEY/STATE=ONE
%DCL-I-SETKEY, keypad state has been set to ONE
$DEFINE/KEY PF1 "ONE"
%DCL-I-DEFKEY, ONE key PF1 has been defined
$DEFINE/KEY/IF_STATE=ONE PF1 "ONE"
%DCL-I-DEFKEY, ONE key PF1 has been defined
The above two examples both define the PF1 key to be "ONE" for state
ONE. However, the first method is somewhat error-prone, in that it
is possible to forget which state you are in and to define a key for
a state other than you intended. The second example eliminates this
possibility of error by specifying the state in the same command as
the key definition. This is the preferred method for defining keys.