Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | 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 may or may 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

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

> #### /NEW

> Runs a new program under debugger control without terminating any programs already running.

### 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 unless you use the /NEW qualifier.

> 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 Compaq DECwindows Motif for OpenVMS user 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.

### 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 Compaq DECwindows Motif for OpenVMS user 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.

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

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

> This command searches for the next occurrence (by default) of the letter D, starting with line 43.

Previous | Next | Contents | Index

| privacy and legal statement |
4538PRO_049.HTML