OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

2 Commands Disabled in the Debugger's DECwindows Motif Interface

The following commands are disabled in the debugger's DECwindows Motif interface. Many of them are relevant only to the command interface's screen mode.

ATTACH SELECT

CANCEL MODE (SET,SHOW) ABORT_KEY

CANCEL WINDOW (SET,SHOW) KEY

DEFINE/KEY (SET,SHOW) MARGINS

DELETE/KEY SET MODE [NO]KEYPAD

DISPLAY SET MODE [NO]SCREEN

EXAMINE/SOURCE SET MODE [NO]SCROLL

EXPAND SET OUTPUT [NO]TERMINAL

EXTRACT (SET,SHOW) TERMINAL

HELP ¹ (SET,SHOW) WINDOW

MOVE (SHOW,CANCEL) DISPLAY

SAVE SHOW SELECT

SCROLL SPAWN

¹Help on commands is available from the Help menu in a debugger window.

The debugger issues an error message if you try to enter any of these disabled commands at the command prompt or when the debugger executes a command procedure containing any of these commands.

The MONITOR command works only with the DECwindows Motif interface (because the command uses the Monitor View).

3 Commands Recognized Only on Workstations Running VWS

The following commands are recognized only when you are using the debugger at a workstation running VWS (not DECwindows Motif):

SET MODE [NO]SEPARATE
SET PROMPT/[NO]POP

4 Debugger Diagnostic Messages

The following example shows the elements of a debugger diagnostic message:

%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table (1) (2) (3) (4)

The facility name (DEBUG).
The severity level (W, in this example).
The message identifier (NOSYMBOL, in this example). The message identifier is an abbreviation of the message text.
The message text.

The identifier enables you to find the explanation for a diagnostic message from the debugger's online help (and the action you need to take, if any).

To get online help about a debugger message, use the following command format:

HELP MESSAGES message-identifier

The possible severity levels for diagnostic messages are as follows:

S (success)
I (informational)
W (warning)
E (error)
F (fatal, or severe error)

Success and informational messages inform you that the debugger has performed your request.

Warning messages indicate that the debugger might have performed some, but not all, of your request and that you should verify the result.

Error messages indicate that the debugger could not perform your request, but that the state of the debugging session was not changed. The only exceptions are if the message identifier was DBGERR or INTERR. These identifiers signify an internal debugger error, and you should contact your Digital support representative.

Fatal messages indicate that the debugger could not perform your request and that the debugging session is in an indeterminate state from which you cannot recover reliably. Typically, the error ends the debugging session.

5 Debugger Command Dictionary

The Debugger Command Dictionary describes each debugger command in detail. Commands are listed alphabetically. The following information is provided for each command: command description, format, parameters, qualifiers, and one or more examples. See the preface of this manual for documentation conventions.

@ (Execute Procedure)

Executes a debugger command procedure.

Format

@file-spec [parameter[,...]]

Parameters

file-spec
Specifies the command procedure to be executed. For any part of the full file specification not provided, the debugger uses the file specification established with the last SET ATSIGN command, if any. If the missing part of the file specification was not established by a SET ATSIGN command, the debugger assumes SYS$DISK:[]DEBUG.COM as the default file specification. You can specify a logical name.
parameter
Specifies a parameter that is passed to the command procedure. The parameter can be an address expression, a value expression in the current language, or a debugger command; the command must be enclosed within quotation marks ("). Unlike with DCL, you must separate parameters by commas. Also, you can pass as many parameters as there are formal parameter declarations within the command procedure. For more information about passing parameters to command procedures, see the DECLARE command.

Description

A debugger command procedure can contain any debugger commands, including another execute procedure (@) command. The debugger executes commands from the command procedure until it reaches an EXIT or QUIT command or reaches the end of the command procedure. At that point, the debugger returns control to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, a DO clause in a command such as SET BREAK, or a DO clause in a screen display definition.
By default, commands read from a command procedure are not echoed. If you enter the SET OUTPUT VERIFY command, all commands read from a command procedure are echoed on the current output device, as specified by DBG$OUTPUT (the default output device is SYS$OUTPUT).
For information about passing parameters to command procedures, see the DECLARE command.
Related commands:

DECLARE
(SET,SHOW) ATSIGN
SET OUTPUT [NO]VERIFY
SHOW OUTPUT

Example


DBG> SET ATSIGN USER:[JONES.DEBUG].DBG DBG> SET OUTPUT VERIFY DBG> @CHECKOUT %DEBUG-I-VERIFYICF, entering command procedure CHECKOUT SET MODULE/ALL SET BREAK SUB1 GO break at routine PROG5\SUB2 EXAMINE X PROG5\SUB2\X: 376 ... %DEBUG-I-VERIFYICF, exiting command procedure MAIN DBG>

DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SET OUTPUT VERIFY
DBG> @CHECKOUT
%DEBUG-I-VERIFYICF, entering command procedure CHECKOUT 
 SET MODULE/ALL 
 SET BREAK SUB1 
 GO 
break at routine PROG5\SUB2 
 EXAMINE X 
PROG5\SUB2\X:  376
    ...
%DEBUG-I-VERIFYICF, exiting command procedure MAIN
DBG>

In this example, the SET ATSIGN command establishes that debugger command procedures are, by default, in USER:[JONES.DEBUG] and have a file type of .DBG. The @CHECKOUT command executes the command procedure USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands in the command because of the SET OUTPUT VERIFY command.

ACTIVATE BREAK

Activates a breakpoint that you have previously set and then deactivated.

Format

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

Parameters

address-expression
Specifies a breakpoint to be activated. 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). Activates a breakpoint established by a previous SET BREAK/ACTIVATING command.
/ALL
By default, activates all user-defined breakpoints. When used with /PREDEFINED, activates all predefined breakpoints but no user-defined breakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a breakpoint established by a previous SET BREAK/BRANCH command.
/CALL
Activates a breakpoint established by a previous SET BREAK/CALL command.
/EVENT=event-name
Activates 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
Activates a breakpoint established by a previous SET BREAK/EXCEPTION command.
/HANDLER
Activates a breakpoint established by a previous SET BREAK/HANDLER command.
/INSTRUCTION
Activates a breakpoint established by a previous SET BREAK/INSTRUCTION command.
/LINE
Activates a breakpoint established by a previous SET BREAK/LINE command. Do not specify an address expression with this qualifier.
/PREDEFINED
Activates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, activates all predefined breakpoints.
/SYSEMULATE
(Alpha only) Activates a breakpoint established by a previous SET BREAK/SYSEMULATE command.
/TERMINATING
Activates a breakpoint established by a previous SET BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Activates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command.
/USER
Activates a specified user-defined breakpoint without affecting any predefined breakpoints. To activate all user-defined breakpoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates a breakpoint established by a previous SET BREAK/VECTOR_INSTRUCTION command.

Description

User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the ACTIVATE BREAK command to activate one or more breakpoints that you deactivated with DEACTIVATE BREAK.
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).
You can activate and deactivate user-defined breakpoints or predefined breakpoints or both. To check if a breakpoint is activated, use the SHOW BREAK command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY

Examples

#1
DBG> ACTIVATE BREAK MAIN\LOOP+10

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

#2
DBG> ACTIVATE BREAK/ALL

This command activates all user-defined breakpoints.

#3
DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED

This command activates all breakpoints, both user-defined and predefined.

ACTIVATE TRACE

Activates a tracepoint that you have previously set and then deactivated.

Format

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

Parameters

address-expression
Specifies a tracepoint to be activated. 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). Activates a tracepoint established with a previous SET TRACE/ACTIVATING command.
/ALL
By default, activates all user-defined tracepoints. When used with /PREDEFINED, activates all predefined tracepoints but no user-defined tracepoints. To activate all tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a tracepoint established with a previous SET TRACE/BRANCH command.
/CALL
Activates a tracepoint established with a previous SET TRACE/CALL command.
/EVENT=event-name
Activates 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
Activates a tracepoint established with a previous SET TRACE/EXCEPTION command.
/INSTRUCTION
Activates a tracepoint established with a previous SET TRACE/INSTRUCTION command.
/LINE
Activates a tracepoint established with a previous SET TRACE/LINE command.
/PREDEFINED
Activates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, activates all predefined tracepoints.
/TERMINATING
Activates a tracepoint established with a previous SET TRACE/TERMINATING command.
/USER
Activates a specified user-defined tracepoint without affecting any predefined tracepoints. To activate all user-defined tracepoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates 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 ACTIVATE TRACE command to activate one or more tracepoints that you deactivated with DEACTIVATE TRACE.
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).
You can activate and deactivate user-defined tracepoints or predefined tracepoints or both. To check if a tracepoint is activated, use the SHOW TRACE command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,DEACTIVATE) TRACE

Examples

#1
DBG> ACTIVATE TRACE MAIN\LOOP+10

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

#2
DBG> ACTIVATE TRACE/ALL

This command activates all user-defined tracepoints.

ACTIVATE WATCH

Activates a watchpoint that you have previously set and then deactivated.

Format

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

Parameters

address-expression
Specifies a watchpoint to be activated. 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
Activates all watchpoints.

Description

Watchpoints are activated when you set them with the SET WATCH command. Use the ACTIVATE WATCH command to activate one or more watchpoints that you deactivated with DEACTIVATE WATCH.
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 activated, use the SHOW WATCH command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) WATCH

Examples

#1
DBG> ACTIVATE WATCH SUB2\TOTAL

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

#2
DBG> ACTIVATE WATCH/ALL

This command activates all watchpoints you have set and deactivated.

ATTACH

Passes control of your terminal from the current process to another process.

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

Format

ATTACH process-name

Parameters

process-name
Specifies the process to which your terminal is to be attached. The process must already exist before you try to attach to it. If the process name contains nonalphanumeric or space characters, you must enclose it in quotation marks (").

Description

The ATTACH command enables you to go back and forth between a debugging session and your command interpreter, or between two debugging sessions. To do so, you must first use the SPAWN command to create a subprocess. You can then attach to it whenever you want. To return to your original process with minimal system overhead, use another ATTACH command.
Related command:

SPAWN

Examples

#1
DBG> SPAWN $ ATTACH JONES %DEBUG-I-RETURNED, control returned to process JONES DBG> ATTACH JONES_1 $

In this example, the series of commands creates a subprocess named JONES_1 from the debugger (currently running in the process JONES) and then attaches to that subprocess.

#2
DBG> ATTACH "Alpha One" $

This example illustrates using quotation marks to enclose a process name that contains a space character.

CALL

Calls a routine that was linked with your program.

Format

CALL routine-name [(argument[,...])]

Parameters

routine-name
Specifies the name or the memory address of the routine to be called.
argument
Specifies an argument required by the routine. Arguments can be passed by address, by descriptor, by reference, and by value, as follows:
%ADDR
(Default, except for C and C++.) Passes the argument by address. The format is as follows:
CALL routine-name (%ADDR address-expression)

The debugger evaluates the address expression and passes that address to the routine specified. For simple variables (such as X), the address of X is passed into the routine. This passing mechanism is how Fortran implements ROUTINE(X). In other words, for named variables, using %ADDR corresponds to a call by reference in Fortran. For other expressions, however, you must use the %REF function to call by reference. For complex or composite variables (such as arrays, records, and access types), the address is passed when you specify %ADDR, but the called routine might not handle the passed data properly. Do not specify a literal value (a number or an expression composed of numbers) with %ADDR.
%DESCR
Passes the argument by descriptor. The format is as follows:
CALL routine-name (%DESCR language-expression)

The debugger evaluates the language expression and builds a standard descriptor to describe the value. The descriptor is then passed to the routine you named. You would use this technique to pass strings to a Fortran routine.
%REF
Passes the argument by reference. The format is as follows:
CALL routine-name (%REF language-expression)

The debugger evaluates the language expression and passes a pointer to the value, into the called routine. This passing mechanism corresponds to the way Fortran passes the result of an expression.
%VAL
(Default for C and C++.) Passes the argument by value. The format is as follows:
CALL routine-name (%VAL language-expression)

The debugger evaluates the language expression and passes the value directly to the called routine.

Qualifiers

/AST (default)

/NOAST
Controls whether the delivery of asynchronous system traps (ASTs) is enabled or disabled during the execution of the called routine. The /AST qualifier enables the delivery of ASTs in the called routine. The /NOAST qualifier disables the delivery of ASTs in the called routine. If you do not specify /AST or /NOAST with the CALL command, the delivery of ASTs is enabled unless you have previously entered the DISABLE AST command.
/SAVE_VECTOR_STATE

/NOSAVE_VECTOR_STATE (default)
Applies to VAX vectorized programs. Controls whether the current state of the vector processor is saved and then restored when a routine is called with the CALL command.
The state of the vector processor comprises the following:

The values of the vector registers (V0 to V15) and the vector control registers (VCR, VLR, and VMR)
Any vector exception (an exception caused by the execution of a vector instruction) that might be pending delivery

When you use the CALL command to execute a routine, execution of the routine might change the state of the vector processor as follows:

By changing the values of vector registers or vector control registers
By causing a vector exception
By causing the delivery of a vector exception that was pending when the CALL command was issued

The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has completed execution, the debugger restores the state of the vector processor that exists before the CALL command is issued. This ensures that, after the called routine has completed execution:

Any vector exception that was pending delivery before the CALL command was issued is still pending delivery
No vector exception that was triggered during the routine call is still pending delivery
The values of the vector registers are identical to their values before the CALL command was issued

The /NOSAVE_VECTOR_STATE qualifier (which is the default) specifies that the state of the vector processor that exists before the CALL command is issued is not restored by the debugger after the called routine has completed execution. In this case, the state of the vector processor after the routine call depends on the effect (if any) of the called routine.
The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the general registers. The values of these registers are always saved and restored when you execute a routine with the CALL command.

Description

The CALL command is one of the four debugger commands that can be used to execute your program (the others are GO, STEP, and EXIT). The CALL command enables you to execute a routine independently of the normal execution of your program. The CALL command executes a routine whether or not your program actually includes a call to that routine, as long as the routine was linked with your program.
When you enter a CALL command, the debugger takes the following actions. For more information, see the qualifier descriptions.

Saves the current values of the general registers.
Constructs an argument list.
Executes a call to the routine specified in the command and passes any arguments.
Executes the routine.
Displays the value returned by the routine in register R0. By convention, after a called routine has executed, register R0 contains the function return value (if the routine is a function) or the procedure completion status (if the routine is a procedure that returns a status value). If a called procedure does not return a status value or function value, the value in R0 might be meaningless, and the "value returned" message can be ignored.
Restores the values of the general registers to the values they had just before the CALL command was executed.
Issues the prompt.

Previous Next Contents Index

privacy and legal statement

4538PRO_039.HTML

ATTACH	SELECT
CANCEL MODE	(SET,SHOW) ABORT_KEY
CANCEL WINDOW	(SET,SHOW) KEY
DEFINE/KEY	(SET,SHOW) MARGINS
DELETE/KEY	SET MODE [NO]KEYPAD
DISPLAY	SET MODE [NO]SCREEN
EXAMINE/SOURCE	SET MODE [NO]SCROLL
EXPAND	SET OUTPUT [NO]TERMINAL
EXTRACT	(SET,SHOW) TERMINAL
HELP ¹	(SET,SHOW) WINDOW
MOVE	(SHOW,CANCEL) DISPLAY
SAVE	SHOW SELECT
SCROLL	SPAWN

%ADDR	(Default, except for C and C++.) Passes the argument by address. The format is as follows: CALL routine-name (%ADDR address-expression) The debugger evaluates the address expression and passes that address to the routine specified. For simple variables (such as X), the address of X is passed into the routine. This passing mechanism is how Fortran implements ROUTINE(X). In other words, for named variables, using %ADDR corresponds to a call by reference in Fortran. For other expressions, however, you must use the %REF function to call by reference. For complex or composite variables (such as arrays, records, and access types), the address is passed when you specify %ADDR, but the called routine might not handle the passed data properly. Do not specify a literal value (a number or an expression composed of numbers) with %ADDR.
%DESCR	Passes the argument by descriptor. The format is as follows: CALL routine-name (%DESCR language-expression) The debugger evaluates the language expression and builds a standard descriptor to describe the value. The descriptor is then passed to the routine you named. You would use this technique to pass strings to a Fortran routine.
%REF	Passes the argument by reference. The format is as follows: CALL routine-name (%REF language-expression) The debugger evaluates the language expression and passes a pointer to the value, into the called routine. This passing mechanism corresponds to the way Fortran passes the result of an expression.
%VAL	(Default for C and C++.) Passes the argument by value. The format is as follows: CALL routine-name (%VAL language-expression) The debugger evaluates the language expression and passes the value directly to the called routine.