HP OpenVMS Debugger Manual

Contents

Index

Ctrl/Z

Ctrl/Z ends a debugging session (like EXIT).

Format

[Ctrl/Z]

Description

For more information about Ctrl/Z, see the EXIT command.

DEACTIVATE BREAK

Deactivates a breakpoint, which you can later activate.

Format

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

Parameters

address-expression
Specifies a breakpoint 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
Deactivates a breakpoint established by a previous SET BREAK/ACTIVATING command.
/ALL
By default, deactivates all user-defined breakpoints. When used with /PREDEFINED, deactivates all predefined breakpoints but no user-defined breakpoints. To deactivate all breakpoints, use /ALL/USER/PREDEFINED.
/BRANCH
Deactivates a breakpoint established by a previous SET BREAK/BRANCH command.
/CALL
Deactivates a breakpoint established by a previous SET BREAK/CALL command.
/EVENT=event-name
Deactivates a breakpoint established by a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command.
To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Deactivates a breakpoint established by a previous SET BREAK/EXCEPTION command.
/HANDLER
Deactivates a breakpoint established by a previous SET BREAK/HANDLER command.
/INSTRUCTION
Deactivates a breakpoint established by a previous SET BREAK/INSTRUCTION command.
/LINE
Deactivates a breakpoint established by a previous SET BREAK/LINE command.
/PREDEFINED
Deactivates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, deactivates all predefined breakpoints.
/SYSEMULATE
(Alpha only) Deactivates a breakpoint established by a previous SET BREAK/SYSEMULATE command.
/TERMINATING
Deactivates a breakpoint established by a previous SET BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Deactivates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command.
/USER
Deactivates a specified user-defined breakpoint. To deactivate all user-defined breakpoints, use the /ALL qualifier.

Description

User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the DEACTIVATE BREAK command to deactivate one or more breakpoints.
If you deactivate a breakpoint, the debugger ignores the breakpoint during program execution. To activate a deactivated breakpoint, use the ACTIVATE BREAK command. You can activate and deactivate user-defined and predefined breakpoints separately. Activating and deactivating breakpoints enables you to run and rerun your program with or without breakpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all breakpoints (activated or deactivated).
To check if a breakpoint is deactivated, use the SHOW BREAK command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,ACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY

Examples

#1
DBG> DEACTIVATE BREAK MAIN\LOOP+10

This command deactivates the user-defined breakpoint set at the address expression MAIN\LOOP+10.

#2
DBG> DEACTIVATE BREAK/ALL

This command deactivates all user-defined breakpoints.

DEACTIVATE TRACE

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

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

#1
DBG> DEACTIVATE TRACE MAIN\LOOP+10

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

#2
DBG> DEACTIVATE TRACE/ALL

This command deactivates all user-defined tracepoints.

DEACTIVATE WATCH

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

#1
DBG> DEACTIVATE WATCH SUB2\TOTAL

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

#2
DBG> DEACTIVATE WATCH/ALL

This command deactivates all watchpoints you have set.

DECLARE

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

#1
! *** 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>

! ***** 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).

#2
! *** 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.

#3
! *** 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>

! ***** 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.

DEFINE

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

#1
DBG> DEFINE CHK=MAIN\LOOP+10

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

#2
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.

#3
DBG> DEFINE/COMMAND BRE = "SET BREAK"

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

DEFINE/KEY

Assigns a string to a function key.

Note
This command is not available in the HP DECwindows Motif for OpenVMS user 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 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 (").

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

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.

Previous Next Contents Index

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.