Assigns a symbolic name to an address expression, command, or
value.
Format
DEFINE symbol-name=parameter [,symbol-name=parameter[, . . . ]]
1 – Parameters
symbol-name
Specifies a symbolic name to be assigned to an address, command,
or value. The symbolic name can be composed of alphanumeric
characters and underscores. The debugger converts lowercase
alphabetic characters to uppercase. The first character must not
be a number. The symbolic name must be no more than 31 characters
long.
parameter
Depends on the qualifier specified.
2 – Qualifiers
2.1 /ADDRESS
(Default) Specifies that the defined symbol is an abbreviation
for an address expression. In this case, parameter is an address
expression.
2.2 /COMMAND
Specifies that the defined symbol is treated as a new debugger
command. In this case, parameter is a quoted character string.
This qualifier provides, in simple cases, essentially the same
capability as the following DCL command:
$ symbol := string
To define complex commands, you might need to use command
procedures with formal parameters. For more information about
declaring parameters to command procedures, see the DECLARE
command.
2.3 /LOCAL
Specifies that the definition is valid only in the command
procedure in which it is defined. The defined symbol is not
visible at debugger command level. By default, a symbol defined
within a command procedure is visible outside that procedure.
2.4 /VALUE
Specifies that the defined symbol is an abbreviation for a value.
In this case, parameter is a language expression in the current
language.
3 – Description
The DEFINE/ADDRESS command assigns a symbolic name to an
address expression in a program. You can define a symbol for a
nonsymbolic program location or for a symbolic program location
having a long path-name prefix. You can then refer to that
program location with the symbolic name. The /ADDRESS qualifier
is the default.
The DEFINE/COMMAND command enables you to define abbreviations
for debugger commands or even define new commands, either from
the debugger command level or from command procedures.
The DEFINE/VALUE command enables you to assign a symbolic name to
a value (or the result of evaluating a language expression).
The DEFINE/LOCAL command confines symbol definitions to command
procedures. By default, defined symbols are global (visible
outside the command procedure).
To enter several DEFINE commands with the same qualifier, first
use the SET DEFINE command to establish a new default qualifier
(for example, SET DEFINE COMMAND makes subsequent DEFINE commands
behave like DEFINE/COMMAND). You can override the current default
qualifier for a single DEFINE command by specifying another
qualifier.
In symbol translation, the debugger searches symbols you define
during the debugging session first. So if you define a symbol
that already exists in your program, the debugger translates the
symbol according to its defined definition, unless you specify a
path-name prefix.
If a symbol is redefined, the previous definition is canceled,
even if you used different qualifiers with the DEFINE command.
Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE
commands are available only when the image in whose context
they were created is the current image. If you use the SET IMAGE
command to establish a new current image, these definitions are
temporarily unavailable. However, definitions created with the
DEFINE/COMMAND and DEFINE/KEY commands are always available for
all images.
Use the SHOW SYMBOL/DEFINED command to determine the equivalence
value of a symbol.
Use the DELETE command to cancel a symbol definition.
Related commands:
DECLARE
DELETE
SET IMAGE
SHOW DEFINE
SHOW SYMBOL/DEFINED
4 – Examples
1.DBG> DEFINE/VALUE COUNTER=0
DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1)
In this example, the DEFINE/VALUE command assigns a value of
0 to the symbol COUNTER. The SET TRACE command causes the
debugger to increment the value of the symbol COUNTER by 1
whenever address R is encountered. In other words, this example
counts the number of calls to R.
2.DBG> DEFINE/COMMAND BRE = "SET BREAK"
This command assigns the symbol BRE to the debugger command SET
BREAK.
5 /KEY
Assigns a string to a function key.
NOTE
This command is not available in the VSI DECwindows Motif for
OpenVMS user interface to the debugger.
Format
DEFINE/KEY key-name "equivalence-string"
5.1 – Parameters
key-name
Specifies a function key to be assigned a string. Valid key names
are as follows:
Key LK201
Name Keyboard VT100-type VT52-type
PF1 PF1 PF1 Blue
PF2 PF2 PF2 Red
PF3 PF3 PF3 Black
PF4 PF4 PF4
KP0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9
PERIOD Keypad Keypad
period (.) period (.)
COMMA Keypad comma Keypad comma
(,) (,)
E1 Find
E2 Insert Here
E3 Remove
E4 Select
E5 Prev Screen
E6 Next Screen
HELP Help
DO Do
F6-F20 F6-F20
On LK201 keyboards:
o You cannot define keys F1 to F5 or the arrow keys (E7 to E10).
o You can define keys F6 to F14 only if you have first entered
the DCL command SET TERMINAL/NOLINE_EDITING. In that case, the
line-editing functions of the left and right arrow keys (E8
and E9) are disabled.
equivalence-string
Specifies the string to be processed when you press the specified
key. Typically, this is one or more debugger commands. If the
string includes any space or nonalphanumeric characters (for
example, a semicolon separating two commands), enclose the string
in quotation marks (").
5.2 – Qualifiers
5.2.1 /ECHO
/ECHO (default)
/NOECHO
Controls whether the command line is displayed after the key has
been pressed. Do not use /NOECHO with /NOTERMINATE.
5.2.2 /IF_STATE
/IF_STATE=(state-name[, . . . ])
/NOIF_STATE (default)
Specifies one or more states to which a key definition applies.
The /IF_STATE qualifier assigns the key definition to the
specified states. You can specify predefined states, such as
DEFAULT and GOLD, or user-defined states. A state name can be
any appropriate alphanumeric string. The /NOIF_STATE qualifier
assigns the key definition to the current state.
5.2.3 /LOCK_STATE
/LOCK_STATE
/NOLOCK_STATE (default)
Controls how long the state set by /SET_STATE remains in effect
after the specified key is pressed. The /LOCK_STATE qualifier
causes the state to remain in effect until it is changed
explicitly (for example, with a SET KEY/STATE command). The
/NOLOCK_STATE qualifier causes the state to remain in effect
only until the next terminator character is typed, or until the
next defined function key is pressed.
5.2.4 /LOG
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the key
definition has been successfully created. The /LOG qualifier
displays the message. The /NOLOG qualifier suppresses the
message.
5.2.5 /SET_STATE
/SET_STATE=state-name
/NOSET_STATE (default)
Controls whether pressing the key changes the current key state.
The /SET_STATE qualifier causes the current state to change to
the specified state when you press the key. The /NOSET_STATE
qualifier causes the current state to remain in effect.
5.2.6 /TERMINATE
/TERMINATE
/NOTERMINATE (default)
Controls whether the specified string is terminated (processed)
when the key is pressed. The /TERMINATE qualifier causes the
string to be terminated when the key is pressed. The /NOTERMINATE
qualifier enables you to press other keys before terminating the
string by pressing the Return key.
5.3 – Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use
this command. Keypad mode is enabled by default.
The DEFINE/KEY command enables you to assign a string to a
function key, overriding any predefined function that was bound
to that key. When you then press the key, the debugger enters
the currently associated string into your command line. The
DEFINE/KEY command is like the DCL command DEFINE/KEY.
For a list of the predefined key functions, see the Keypad_
Definitions_CI online help topic.
On VT52- and VT100-series terminals, the function keys you can
use include all of the numeric keypad keys. Newer terminals and
workstations have the LK201 keyboard. On LK201 keyboards, the
function keys you can use include all of the numeric keypad keys,
the nonarrow keys of the editing keypad (Find, Insert Here, and
so on), and keys F6 to F20 at the top of the keyboard.
A key definition remains in effect until you redefine the key,
enter the DELETE/KEY command for that key, or exit the debugger.
You can include key definitions in a command procedure, such as
your debugger initialization file.
The /IF_STATE qualifier enables you 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.
By default, the current key state is the DEFAULT state. The
current state can be changed with the SET KEY/STATE command,
or by pressing a key that causes a state change (a key that was
defined with DEFINE/KEY/LOCK_STATE/SET_STATE).
Related commands:
DELETE/KEY
(SET,SHOW) KEY
5.4 – Examples
1.DBG> SET KEY/STATE=GOLD
%DEBUG-I-SETKEY, keypad state has been set to GOLD
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX"
%DEBUG-I-DEFKEY, GOLD key KP9 has been defined
In this example, the SET KEY command establishes GOLD as
the current key state. The DEFINE/KEY command assigns the
SET RADIX/OVERRIDE HEX command to keypad key 9 (KP9) for the
current state (GOLD). The command is processed when you press
the key.
2.DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE "
%DEBUG-I-DEFKEY, BLUE key KP9 has been defined
This command assigns the unterminated command string "SET BREAK
%LINE" to keypad key 9 for the BLUE state. After pressing BLUE-
KP9, you can enter a line number and then press the Return key
to terminate and process the SET BREAK command.
3.DBG> SET KEY/STATE=DEFAULT
%DEBUG-I-SETKEY, keypad state has been set to DEFAULT
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 ""
%DEBUG-I-DEFKEY, DEFAULT key F12 has been defined
In this example, the SET KEY command establishes DEFAULT as
the current state. The DEFINE/KEY command makes the F12 key
(on an LK201 keyboard) a state key. Pressing F12 while in
the DEFAULT state causes the current state to become RED. The
key definition is not terminated and has no other effect (a
null string is assigned to F12). After pressing F12, you can
enter "RED" commands by pressing keys that have definitions
associated with the RED state.
6 /PROCESS_SET
Assigns a symbolic name to a list of process specifications.
Format
DEFINE/PROCESS_SET process-set-name =process-spec[, . . . ]
6.1 – Parameters
process-set-name
Specifies a symbolic name to be assigned to a list of process
specifications. The symbolic name can be composed of alphanumeric
characters and underscores. The debugger converts lowercase
alphabetic characters to uppercase. The first character must not
be a number. The symbolic name must be no more than 31 characters
long.
process-spec
Specifies a process currently under debugger control. Use any of
the following forms:
[%PROCESS_NAME] process- The process name, if that name does not
name contain spaces or lowercase characters.
The process name can include the
asterisk (*) wildcard character.
[%PROCESS_NAME] The process name, if that name contains
"process-name " spaces or lowercase characters. You
can also use apostrophes (') instead of
quotation marks (").
%PROCESS_PID process_id The process identifier (PID, a
hexadecimal number).
[%PROCESS_NUMBER] The number assigned to a process when
process-number it comes under debugger control. A
(or %PROC process- new number is assigned sequentially,
number) starting with 1, to each process. If
a process is terminated with the EXIT
or QUIT command, the number can be
assigned again during the debugging
session. Process numbers appear in a
SHOW PROCESS display. Processes are
ordered in a circular list so they can
be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name A symbol defined with the
DEFINE/PROCESS_SET command to represent
a group of processes.
%NEXT_PROCESS The next process after the visible
process in the debugger's circular
process list.
%PREVIOUS_PROCESS The process previous to the visible
process in the debugger's circular
process list.
%VISIBLE_PROCESS The process whose stack, register set,
and images are the current context for
looking up symbols, register values,
routine calls, breakpoints, and so on.
If you do not specify a process, the symbolic name is created but
contains no process entries.
6.2 – Description
The DEFINE/PROCESS_SET command assigns a symbol to a list of
process specifications. You can then use the symbol in any
command where a list of process specifications is allowed.
The DEFINE/PROCESS_SET command does not verify the existence of a
specified process. This enables you to specify processes that do
not yet exist.
To identify a symbol that was defined with the DEFINE/PROCESS_SET
command, use the SHOW SYMBOL/DEFINED command. To delete a symbol
that was defined with the DEFINE/PROCESS_SET command, use the
DELETE command.
Related commands:
DELETE
(SET,SHOW) DEFINE
SHOW SYMBOL/DEFINED
6.3 – Examples
1.all> DEFINE/PROCESS_SET SERVERS=FILE_SERVER,NETWORK_SERVER
all> SHOW PROCESS SERVERS
Number Name State Current PC
* 1 FILE_SERVER step FS_PROG\%LINE 37
2 NETWORK_SERVER break NET_PROG\%LINE 24
all>
This DEFINE/PROCESS_SET command assigns the symbolic name
SERVERS to the process set consisting of FILE_SERVER and
NETWORK_SERVER. The SHOW PROCESS SERVERS command displays
information about the processes that make up the set SERVERS.
2.all> DEFINE/PROCESS_SET G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS
all> SHOW SYMBOL/DEFINED G1
defined G1
bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS"
was defined /process_set
all> DELETE G1
This DEFINE/PROCESS_SET command assigns the symbolic name G1 to
the process set consisting of process 1 and the visible process
(process 3). The SHOW SYMBOL/DEFINED G1 command identifies the
defined symbol G1. The DELETE G1 command deletes the symbol
from the DEFINE symbol table.
3.all> DEFINE/PROCESS_SET A = B,C,D
all> DEFINE/PROCESS_SET B = E,F,G
all> DEFINE/PROCESS_SET E = I,J,A
%DEBUG-E-NORECSYM, recursive PROCESS_SET symbol definition
encountered at or near "A"
This series of DEFINE/PROCESS_SET commands illustrate valid and
invalid uses of the command.