Updated: 11 December 1998

OpenVMS Debugger Manual

Deactivates a tracepoint, which you can later activate.

Format

DEACTIVATE TRACE [address-expression[,...]]

Parameters

address-expression

Specifies a tracepoint to be deactivated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER.

Qualifiers

/ACTIVATING

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Deactivates a tracepoint established with a previous SET TRACE/ACTIVATING command.

/ALL

By default, deactivates all user-defined tracepoints. When used with /PREDEFINED, it deactivates all predefined tracepoints but no user-defined tracepoints. To deactivate all tracepoints, use /ALL/USER/PREDEFINED.

/BRANCH

Deactivates a tracepoint established with a previous SET TRACE/BRANCH command.

/CALL

Deactivates a tracepoint established with a previous SET TRACE/CALL command.

/EVENT=event-name

Deactivates a tracepoint established with a previous SET TRACE/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET TRACE/EVENT command.

To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.

/EXCEPTION

Deactivates a tracepoint established with a previous SET TRACE/EXCEPTION command.

/INSTRUCTION

Deactivates a tracepoint established with a previous SET TRACE/INSTRUCTION command.

/LINE

Deactivates a tracepoint established with a previous SET TRACE/LINE command.

/PREDEFINED

Deactivates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, it deactivates all predefined tracepoints.

/TERMINATING

Deactivates a tracepoint established with a previous SET TRACE/TERMINATING command.

/USER

Deactivates a specified user-defined tracepoint without affecting any predefined tracepoints. When used with /ALL, it deactivates all user-defined tracepoints. The /USER qualifier is the default unless you specify /PREDEFINED.

/VECTOR_INSTRUCTION

(VAX only) Deactivates a tracepoint established with a previous SET TRACE/VECTOR_INSTRUCTION command.

Description

User-defined tracepoints are activated when you set them with the SET TRACE command. Predefined tracepoints are activated by default. Use the DEACTIVATE TRACE command to deactivate one or more tracepoints.

If you deactivate a tracepoint, the debugger ignores the tracepoint during program execution. To activate a deactivated tracepoint, use the ACTIVATE TRACE command. You can activate and deactivate user-defined and predefined tracepoints separately. Activating and deactivating tracepoints enables you to run and rerun your program with or without tracepoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all tracepoints (activated or deactivated).

To check if a tracepoint is deactivated, use the SHOW TRACE command.

Related commands:

• CANCEL ALL
• RERUN
• (SET,SHOW) EVENT_FACILITY
• (SET,SHOW,CANCEL,ACTIVATE) TRACE

Examples

DBG> DEACTIVATE TRACE MAIN\LOOP+10
      

This command deactivates the user-defined tracepoint at the location MAIN\LOOP+10.

DBG> DEACTIVATE TRACE/ALL
      

This command deactivates all user-defined tracepoints.

Deactivates a watchpoint, which you can later activate.

Format

DEACTIVATE WATCH [address-expression[,...]]

Parameters

address-expression

Specifies a watchpoint to be deactivated. With high-level languages, this is typically the name of a variable. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression with /ALL.

Qualifiers

/ALL

Deactivates all watchpoints.

Description

Watchpoints are activated when you set them with the SET WATCH command. Use the DEACTIVATE WATCH command to deactivate one or more watchpoints.

If you deactivate a watchpoint, the debugger ignores the watchpoint during program execution. To activate a deactivated watchpoint, use the ACTIVATE WATCH command. Activating and deactivating watchpoints enables you to run and rerun your program with or without watchpoints without having to cancel and then reset them.

By default, the RERUN command saves the current state of all static watchpoints (activated or deactivated). The state of a particular nonstatic watchpoint might or might not be saved depending on the scope of the variable being watched relative to the main program unit (where execution restarts).

To check if a watchpoint is deactivated, use the SHOW WATCH command.

Related commands:

• CANCEL ALL
• RERUN
• (SET,SHOW,CANCEL,ACTIVATE) WATCH

Examples

DBG> DEACTIVATE WATCH SUB2\TOTAL
      

This command deactivates the watchpoint at variable TOTAL in module SUB2.

DBG> DEACTIVATE WATCH/ALL
      

This command deactivates all watchpoints you have set.

Declares a formal parameter within a command procedure. This enables you to pass an actual parameter to the procedure when entering an execute procedure (@) command.

Format

DECLARE p-name:p-kind [,p-name:p-kind[,...]]

Parameters

p-name

Specifies a formal parameter (a symbol) that is declared within the command procedure.

Do not specify a null parameter (represented either by two consecutive commas or by a comma at the end of the command).

p-kind

Specifies the parameter kind of a formal parameter. Valid keywords are as follows:

ADDRESS	Specifies that the actual parameter is interpreted as an address expression. Same effect as DEFINE/ADDRESS symbol-name = actual-parameter.
COMMAND	Specifies that the actual parameter is interpreted as a command. Same effect as DEFINE/COMMAND symbol-name = actual-parameter.
VALUE	Specifies that the actual parameter is interpreted as a value expression in the current language. Same effect as DEFINE/VALUE symbol-name = actual-parameter.

Description

The DECLARE command is valid only within a command procedure.

The DECLARE command binds one or more actual parameters, specified on the command line following the execute procedure (@) command, to formal parameters (symbols) declared within a command procedure.

Each p-name:p-kind pair specified by a DECLARE command binds one formal parameter to one actual parameter. Formal parameters are bound to actual parameters in the order in which the debugger processes the parameter declarations. If you specify several formal parameters on a single DECLARE command, the leftmost formal parameter is bound to the first actual parameter, the next formal parameter is bound to the second, and so on. If you use a DECLARE command in a loop, the formal parameter is bound to the first actual parameter on the first iteration of the loop; the same formal parameter is bound to the second actual parameter on the next iteration, and so on.

Each parameter declaration acts like a DEFINE command: it associates a formal parameter with an address expression, a command, or a value expression in the current language, according to the parameter kind specified. The formal parameters themselves are consistent with those accepted by the DEFINE command and can in fact be deleted from the symbol table with the DELETE command.

The %PARCNT built-in symbol, which can be used only within a command procedure, enables you to pass a variable number of parameters to a command procedure. The value of %PARCNT is the number of actual parameters passed to the command procedure.

Related commands:

• @ (Execute Procedure)
• DEFINE
• DELETE

Examples

! ***** Command Procedure EXAM.COM *****
SET OUTPUT VERIFY
DECLARE K:ADDRESS
EXAMINE K
 
DBG> @EXAM ARR4
%DEBUG-I-VERIFYIC, entering command procedure EXAM 
 DECLARE K:ADDRESS 
 EXAMINE K 
PROG_8\ARR4 
    (1):        18 
    (2):        1 
    (3):        0 
    (4):        1 
%DEBUG-I-VERIFYIC, exiting command procedure EXAM
DBG>
      

In this example, the DECLARE K:ADDRESS command declares the formal parameter K within command procedure EXAM.COM. When EXAM.COM is executed, the actual parameter passed to EXAM.COM is interpreted as an address expression, and the EXAMINE K command displays the value of that address expression. The SET OUTPUT VERIFY command causes the commands to echo when they are read by the debugger.

At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM, passing the actual parameter ARR4. Within EXAM.COM, ARR4 is interpreted as an address expression (an array variable, in this case).

! ***** Debugger Command Procedure EXAM_GO.COM *****
DECLARE L:ADDRESS, M:COMMAND
EXAMINE L; M
 
DBG> @EXAM_GO X "@DUMP"
      

In this example, the command procedure EXAM_GO.COM accepts two parameters, an address expression (L) and a command string (M). The address expression is then examined and the command is executed.

At the debugger prompt, the @EXAM_GO X "@DUMP" command executes EXAM_GO.COM, passing the address expression X and the command string @DUMP.

! ***** Debugger Command Procedure VAR.DBG *****
SET OUTPUT VERIFY 
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
DBG> @VAR.DBG 12,37,45
%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
 FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 
12 
37 
45 
%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
DBG>
      

In this example, the command procedure VAR.DBG accepts a variable number of parameters. That number is stored in the built-in symbol %PARCNT.

At the debugger prompt, the @VAR.DBG command executes VAR.DBG, passing the actual parameters 12, 37, and 45. Therefore, %PARCNT has the value 3, and the FOR loop is repeated 3 times. The FOR loop causes the DECLARE command to bind each of the three actual parameters (starting with 12) to a new declaration of X. Each actual parameter is interpreted as a value expression in the current language, and the EVALUATE X command displays that value.

Assigns a symbolic name to an address expression, command, or value.

Format

DEFINE symbol-name=parameter [,symbol-name=parameter[,...]]

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.

Qualifiers

/ADDRESS

(Default) Specifies that the defined symbol is an abbreviation for an address expression. In this case, parameter is an address expression.

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

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

/VALUE

Specifies that the defined symbol is an abbreviation for a value. In this case, parameter is a language expression in the current language.

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

Examples

DBG> DEFINE CHK=MAIN\LOOP+10
      

This command assigns the symbol CHK to the address MAIN\LOOP+10.

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.

DBG> DEFINE/COMMAND BRE = "SET BREAK"
      

This command assigns the symbol BRE to the debugger command SET BREAK.

Assigns a string to a function key.

Note This command is not available in the DECwindows Motif interface to the debugger.

Format

DEFINE/KEY key-name "equivalence-string"

Parameters

key-name

Specifies a function key to be assigned a string. Valid key names are as follows:

Key Name	LK201 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 period (.)	Keypad period (.)
COMMA	Keypad comma (,)	Keypad comma (,)
MINUS	Keypad minus (-)	Keypad minus (-)
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:

• You cannot define keys F1 to F5 or the arrow keys (E7 to E10).
• 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 the specified key is pressed. 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 (").

Qualifiers

/ECHO (default)

/NOECHO

Controls whether the command line is displayed after the key has been pressed. Do not use /NOECHO with /NOTERMINATE.

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

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

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

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

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

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

Examples

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.

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.

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_043.HTML