OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

REBOOT (Alpha Only)

When debugging Alpha operating system code with the OpenVMS Alpha System-Code Debugger, reboots the target machine running the Alpha operating system code and executes (or reexecutes) your system program.
The REBOOT command, in other words, is similar to the RUN or RERUN commands when you are within the OpenVMS Alpha System-Code Debugger environment. (The OpenVMS Alpha System-Code Debugger is a kernel debugger that is activated through the OpenVMS Debugger.)
Before you issue this command, you must have completed the instructions described in the Writing OpenVMS Alpha Device Drivers in C manual. These instructions include the creation of an Alpha device driver, the setup commands activating the OpenVMS Alpha System-Code Debugger, and the CONNECT command that allows you to debug.
You must also have started the OpenVMS Debugger with the DEBUG/KEEP command.

Format

REBOOT

Description

For complete information on using the OpenVMS Alpha System-Code Debugger, see the Writing OpenVMS Alpha Device Drivers in C manual.
Related commands:

CONNECT
DISCONNECT

Example


DBG> REBOOT

This command reboots the target machine where you will be debugging the OpenVMS Alpha operating system and reruns your program.

REPEAT

Executes a sequence of commands a specified number of times.

Format

REPEAT language-expression DO (command[;...])

Parameters

language-expression
Denotes any expression in the currently set language that evaluates to a positive integer.
command
Specifies a debugger command. If you specify more than one command, you must separate the commands with semicolons (;). At each execution, the debugger checks the syntax of any expressions in the commands and then evaluates them.

Description

The REPEAT command is a simple form of the FOR command. The REPEAT command executes a sequence of commands repetitively a specified number of times, without providing the options for establishing count parameters that the FOR command does.
Related commands:

EXITLOOP
FOR
WHILE

Example


DBG> REPEAT 10 DO (EXAMINE Y; STEP)

This command line sets up a loop that issues a sequence of two commands (EXAMINE Y, then STEP) 10 times.

RERUN

Reruns the program currently under debugger control.

Note
Requires that you started your debugging session with the DCL command DEBUG/KEEP and then executed the debugger RUN command. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RERUN command.

Format

RERUN

Qualifiers

/ARGUMENTS="arg-list"
Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips them when parsing the string. If you do not specify arguments, any arguments that were specified previously when running or rerunning that program are applied, by default.
/HEAP_ANALYZER
(Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see Chapter 12.
/SAVE (default)

/NOSAVE
Controls whether to save the current state (activated or deactivated) of all breakpoints, tracepoints, and static watchpoints for the next run of the program. The /SAVE qualifier specifies that their state is saved, and /NOSAVE specifies that their state is not saved. /SAVE might or might not save the state of a particular nonstatic watchpoint depending on the scope of the variable being watched relative to the main program unit (where execution restarts).

Description

If you invoked the debugger with the DCL command DEBUG/KEEP and subsequently used the debugger RUN command to begin debugging your program, you can then use the RERUN command to rerun the program currently under debugger control.
The RERUN command terminates the image you were debugging and then restarts that image under debugger control. Execution is paused at the start of the main program unit, as if you had used the debugger RUN command or the DCL command RUN/DEBUG.
The RERUN command uses the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command.
Related commands:

RUN (debugger command)
RUN (DCL command)
(ACTIVATE,DEACTIVATE) BREAK
(ACTIVATE,DEACTIVATE) TRACE
(ACTIVATE,DEACTIVATE) WATCH

Examples

#1
DBG> RERUN

This command reruns the current program. By default, the debugger saves the current state of all breakpoints, tracepoints, and static watchpoints (activated or deactivated).

#2
DBG> RERUN/NOSAVE

This command reruns the current program without saving the current state of breakpoints, tracepoints, and watchpoints---in effect, the same as using the RUN command and specifying the image name.

#3
DBG> RERUN/ARGUMENTS="fee fii foo fum"

This command reruns the current program with new arguments.

RUN

Brings a program under debugger control.

Note
Requires that you started your debugging session with the DCL command DEBUG/KEEP. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RUN command.

Format

RUN [program-image]

Parameters

program-image
Specifies the executable image of the program to be debugged. Do not specify an image if you use the /COMMAND=cmd-symbol qualifier.

Qualifiers

/ARGUMENTS="arg-list"
Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotes when parsing the string.
/COMMAND="cmd-symbol"
Specifies a DCL foreign command for running the program.
Do not use this qualifier if you specify a program-image parameter.
Do not specify a DCL command or any other command definition that was created with the SET COMMAND command.
/HEAP_ANALYZER
(Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see Chapter 12.

Description

If you invoked the debugger with the DCL command DEBUG/KEEP, you can use the debugger RUN command at any time during a debugging session to start a program under debugger control. If you are in the midst of debugging a program when you issue the RUN command, that program will first be terminated.
To run the same program again (that is, the same version of the program that is currently under debugger control), use the RERUN command. RERUN enables you to save the current state (activated or deactivated) of any breakpoints, tracepoints, and static watchpoints.
For a discussion of passing arguments when you use the RUN or RERUN command, see Chapter 1.
Note the following restrictions about the debugger RUN command:

You can use the RUN command only if you started the debugger with the DCL command DEBUG/KEEP.
You cannot use the RUN command to connect the debugger to a running program. See the description of Ctrl/Y.
You cannot run a program under debugger control over a DECnet link. Both the image to be debugged and the debugger must reside on the same node.

Related commands:

RERUN
RUN (DCL command)
Ctrl/Y--DEBUG (DCL command)
DEBUG (DCL command)

Examples

#1
DBG> RUN EIGHTQUEENS Language: C, Module: EIGHTQUEENS

This command brings the program EIGHTQUEENS under debugger control.

#2
$ RUNPROG == "$ DISK3:[SMITH]MYPROG.EXE" $ DEBUG/KEEP ... DBG> RUN/COMMAND="RUNPROG"/ARGUMENTS="X Y Z"

The first line of this example creates a command symbol RUNPROG (at DCL level) to run an image named MYPROG.EXE. The second line starts the debugger. The debugger RUN command then brings the image MYPROG.EXE under debugger control. The /COMMAND qualifier specifies the command symbol previously created (in this case RUNPROG), and the /ARGUMENTS qualifier passes the arguments X Y Z to the image.

#3
DBG> RUN/ARGUMENTS="X Y Z" MYPROG

This command brings the program MYPROG.EXE under debugger control and passes the arguments X Y Z.

SAVE

Preserves the contents of an existing screen display in a new display.

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

Format

SAVE old-display AS new-display [,...]

Parameters

old-display
Specifies the display whose contents are saved. You can specify any of the following entities:

A predefined display:

SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG

A display previously created with the DISPLAY command
A display built-in symbol:

%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE

new-display
Specifies the name of the new display to be created. This new display then receives the contents of the old-disp display.

Qualifiers

/SUFFIX[=process-identifier-type]
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.
The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.
Use any of the following process-identifier-type keywords:

PROCESS_NAME The display-name suffix is the process name.

PROCESS_NUMBER The display-name suffix is the process number (as shown in a SHOW PROCESS display).

PROCESS_PID The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).

Description

The SAVE command enables you to save a snapshot copy of an existing display in a new display for later reference. The new display is created with the same text contents as the existing display. In general, the new display is given all the attributes or characteristics of the old display except that it is removed from the screen and is never automatically updated. You can later recall the saved display to the terminal screen with the DISPLAY command.
When you use the SAVE command, only those lines that are currently stored in the display's memory buffer (as determined by the /SIZE qualifier on the DISPLAY command) are stored in the saved display. However, in the case of a saved source or instruction display, you can also see any other source lines associated with that module or any other instructions associated with that routine (by scrolling the saved display).
You cannot save the PROMPT display.
Related commands:

DISPLAY
EXITLOOP

Example


DBG> SAVE REG AS OLDREG

This command saves the contents of the display named REG into the newly created display named OLDREG.

SCROLL

Scrolls a screen display to make other parts of the text visible through the display window.

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

Format

SCROLL [display-name]

Parameters

display-name
Specifies a display to be scrolled. You can specify any of the following entities:

A predefined display:

SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG

A display previously created with the DISPLAY command
A display built-in symbol:

%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE

If you do not specify a display, the current scrolling display, as established by the SELECT command, is chosen.

Qualifiers

/BOTTOM
Scrolls down to the bottom of the display's text.
/DOWN:[n]
Scrolls down over the display's text by n lines to reveal text further down in the display. If you omit n, the display is scrolled by approximately 3/4 of its window height.
/LEFT:[n]
Scrolls left over the display's text by n columns to reveal text beyond the left window border. You cannot scroll past column 1. If you omit n, the display is scrolled left by 8 columns.
/RIGHT[:n]
Scrolls right over the display's text by n columns to reveal text beyond the right window border. You cannot scroll past column 255. If you omit n, the display is scrolled right by 8 columns.
/SUFFIX[=process-identifier-type]
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.
The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.
Use any of the following process-identifier-type keywords:

PROCESS_NAME The display-name suffix is the process name.

PROCESS_NUMBER The display-name suffix is the process number (as shown in a SHOW PROCESS display).

PROCESS_PID The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).
/TOP
Scrolls up to the top of the display's text.
/UP[:n]
Scrolls up over the display's text by n lines to reveal text further up in the display. If you omit n, the display is scrolled by approximately 3/4 of its window height.

Description

The SCROLL command moves a display up, down, right, or left relative to its window so that various parts of the display text can be made visible through the window.
Use the SELECT/SCROLL command to select the target display for the SCROLL command (the current scrolling display).
For a list of the key definitions associated with the SCROLL command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.
Related command: SELECT.

Examples

#1
DBG> SCROLL/LEFT

This command scrolls the current scrolling display to the left by 8 columns.

#2
DBG> SCROLL/UP:4 ALPHA

This command scrolls display ALPHA 4 lines up.

SEARCH

Searches the source code for a specified string and displays source lines that contain an occurrence of the string.

Format

SEARCH [range] [string]

Parameters

range
Specifies a program region to be searched. Use any of the following formats:

mod-name Searches the specified module from line 0 to the end of the module.

mod-name\line-num Searches the specified module from the specified line number to the end of the module.

mod-name\line-num:line-num Searches the specified module from the line number specified on the left of the colon to the line number specified on the right.

line-num Uses the current scope to find a module and searches that module from the specified line number to the end of the module. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope.

line-num:line-num Uses the current scope to find a module and searches that module from the line number specified on the left of the colon to the line number specified on the right. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope.

null (no entry) Searches the same module as that from which a source line was most recently displayed (as a result of a TYPE, EXAMINE/SOURCE, or SEARCH command, for example), beginning at the first line following the line most recently displayed and continuing to the end of the module.

string
Specifies the source code characters for which to search. If you do not specify a string, the string specified in the last SEARCH command, if any, is used.
You must enclose the string in quotation marks (") or apostrophes (') under the following conditions:

The string has any leading or ending space or tab characters
The string contains an embedded semicolon
The range parameter is null

If the string is enclosed in quotation marks, use two consecutive quotation marks ("") to indicate an enclosed quotation mark. If the string is enclosed in apostrophes, use two consecutive apostrophes ('') to indicate an enclosed apostrophe.

Qualifiers

/ALL
Specifies that the debugger search for all occurrences of the string in the specified range and display every line containing an occurrence of the string.
/IDENTIFIER
Specifies that the debugger search for an occurrence of the string in the specified range but display the string only if it is not bounded on either side by a character that can be part of an identifier in the current language.
/NEXT
(Default) Specifies that the debugger search for the next occurrence of the string in the specified range and display only the line containing this occurrence.
/STRING
(Default) Specifies that the debugger search for and display the string as specified, and not interpret the context surrounding an occurrence of the string, as it does in the case of /IDENTIFIER.

Description

The SEARCH command displays the lines of source code that contain an occurrence of a specified string.
If you specify a module name with the SEARCH command, that module must be set. To determine whether a particular module is set, use the SHOW MODULE command, then use the SET MODULE command, if necessary.
Qualifiers for the SEARCH command determine whether the debugger: (1) searches for all occurrences (/ALL) of the string or only the next occurrence (/NEXT); and (2) displays any occurrence of the string (/STRING) or only those occurrences in which the string is not bounded on either side by a character that can be part of an identifier in the current language (/IDENTIFIER).
If you plan to enter several SEARCH commands with the same qualifier, you can first use the SET SEARCH command to establish a new default qualifier (for example, SET SEARCH ALL makes the SEARCH command behave like SEARCH/ALL). Then you do not have to use that qualifier with the SEARCH command. You can override the current default qualifiers for the duration of a single SEARCH command by specifying other qualifiers.
Related commands:

(SET,SHOW) LANGUAGE
(SET,SHOW) MODULE
(SET,SHOW) SCOPE
(SET,SHOW) SEARCH

Examples

#1
DBG> SEARCH/STRING/ALL 40:50 D module COBOLTEST 40: 02 D2N COMP-2 VALUE -234560000000. 41: 02 D COMP-2 VALUE 222222.33. 42: 02 DN COMP-2 VALUE -222222.333333. 47: 02 DR0 COMP-2 VALUE 0.1. 48: 02 DR5 COMP-2 VALUE 0.000001. 49: 02 DR10 COMP-2 VALUE 0.00000000001. 50: 02 DR15 COMP-2 VALUE 0.0000000000000001. DBG>

DBG> SEARCH/STRING/ALL 40:50 D
module COBOLTEST 
    40: 02      D2N     COMP-2 VALUE -234560000000. 
    41: 02      D       COMP-2 VALUE  222222.33. 
    42: 02      DN      COMP-2 VALUE -222222.333333. 
    47: 02      DR0     COMP-2 VALUE  0.1. 
    48: 02      DR5     COMP-2 VALUE  0.000001. 
    49: 02      DR10    COMP-2 VALUE  0.00000000001. 
    50: 02      DR15    COMP-2 VALUE  0.0000000000000001.
DBG>

This command searches for all occurrences of the letter D in lines 40 to 50 of the module COBOLTEST, the module that is in the current scope.

#2
DBG> SEARCH/IDENTIFIER/ALL 40:50 D module COBOLTEST 41: 02 D COMP-2 VALUE 222222.33. DBG>

This command searches for all occurrences of the letter D in lines 40 to 50 of the module COBOLTEST. The debugger displays the only line where the letter D (the search string) is not bounded on either side by a character that can be part of an identifier in the current language.

#3
DBG> SEARCH/NEXT 40:50 D module COBOLTEST 40: 02 D2N COMP-2 VALUE -234560000000. DBG>

This command searches for the next occurrence of the letter D in lines 40 to 50 of the module COBOLTEST.

#4
DBG> SEARCH/NEXT module COBOLTEST 41: 02 D COMP-2 VALUE 222222.33. DBG>

This command searches for the next occurrence of the letter D. The debugger assumes D to be the search string because D was the last one entered and no other search string was specified.

#5
DBG> SEARCH 43 D module COBOLTEST 47: 02 DR0 COMP-2 VALUE 0.1. DBG>

Previous Next Contents Index

privacy and legal statement

4538PRO_050.HTML

PROCESS_NAME	The display-name suffix is the process name.
PROCESS_NUMBER	The display-name suffix is the process number (as shown in a SHOW PROCESS display).
PROCESS_PID	The display-name suffix is the process identifier (PID).

mod-name	Searches the specified module from line 0 to the end of the module.
mod-name\line-num	Searches the specified module from the specified line number to the end of the module.
mod-name\line-num:line-num	Searches the specified module from the line number specified on the left of the colon to the line number specified on the right.
line-num	Uses the current scope to find a module and searches that module from the specified line number to the end of the module. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope.
line-num:line-num	Uses the current scope to find a module and searches that module from the line number specified on the left of the colon to the line number specified on the right. The current scope is established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command. If you specify a scope search list with the SET SCOPE command, the debugger searches only the module associated with the first named scope.
null (no entry)	Searches the same module as that from which a source line was most recently displayed (as a result of a TYPE, EXAMINE/SOURCE, or SEARCH command, for example), beginning at the first line following the line most recently displayed and continuing to the end of the module.