[Digital logo]
[HR]

OpenVMS Debugger Manual

Previous | Contents

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

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:

Related commands:

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:

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:

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:

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:

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:

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.

SELECT

Selects a screen display as the current error, input, instruction, output, program, prompt, scrolling, or source display.

Note

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

Format

SELECT [display-name]

PARAMETERS

display-name

Specifies the display to be selected. You can specify any one of the following, with the restrictions noted in the qualifier descriptions:

If you omit this parameter and do not specify a qualifier, you "unselect" the current scrolling display (no display then has the scrolling attribute). If you omit this parameter but specify a qualifier (/INPUT, /SOURCE, and so on), you unselect the current display with that attribute (see the qualifier descriptions).

QUALIFIERS

/ERROR

Selects the specified display as the current error display. This causes all debugger diagnostic messages to go to that display. The display specified must be either an output display or the PROMPT display. If you do not specify a display, selects the PROMPT display current error display. By default, the PROMPT display has the error attribute.

/INPUT

Selects the specified display as the current input display. This causes that display to echo debugger input (which appears in the PROMPT display). The display specified must be an output display.

If you do not specify a display, the current input display is unselected and debugger input is not echoed to any display (debugger input appears only in the PROMPT display). By default, no display has the input attribute.

/INSTRUCTION

Selects the specified display as the current instruction display. This causes the output of all EXAMINE/INSTRUCTION commands to go to that display. The display specified must be an instruction display.

If you do not specify a display, the current instruction display is unselected and no display has the instruction attribute.

By default, for all languages except MACRO--32, no display has the instruction attribute. If the language is set to MACRO--32, the INST display has the instruction attribute by default.

/OUTPUT

Selects the specified display as the current output display). This causes debugger output that is not already directed to another display to go to that display. The display specified must be either an output display or the PROMPT display.

If you do not specify a display, the PROMPT display is selected as the current output display. By default, the OUT display has the output attribute.

/PROGRAM

Selects the specified display as the current program display. This causes the debugger to try to force program input and output to that display. Currently, only the PROMPT display can be specified.

If you do not specify a display, the current program display is unselected and program input and output are no longer forced to the specified display.

By default, the PROMPT display has the program attribute, except on workstations, where the program attribute is unselected.

/PROMPT

Selects the specified display as the current prompt display. This is where the debugger prompts for input. Currently, only the PROMPT display can be specified. Moreover, you cannot unselect the PROMPT display (the PROMPT display always has the prompt attribute).

/SCROLL

(Default.) Selects the specified display as the current scrolling display. This is the default display for the SCROLL, MOVE, and EXPAND commands. Although any display can have the scroll attribute, you can use only the MOVE and EXPAND commands (not the SCROLL command) with the PROMPT display.

If you do not specify a display, the current scrolling display is unselected and no display has the scroll attribute.

By default, for all languages except MACRO-32, the SRC display has the scroll attribute. If the language is set to MACRO-32, the INST display has the scroll attribute by default.

/SOURCE

Selects the specified display as the current source display. This causes the output of all TYPE and EXAMINE/SOURCE commands to go to that display. The display specified must be a source display.

If you do not specify a display, the current source display is unselected and no display has the source attribute.

By default, for all languages except MACRO--32, the SRC display has the source attribute. If the language is set to MACRO--32, no display has the source attribute by default.

/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

Attributes are used to select the current scrolling display and to direct various types of debugger output to particular displays. This gives you the option of mixing or isolating different types of information, such as debugger input, output, diagnostic messages, and so on in scrollable displays.

Use the SELECT command with one or more qualifiers (/ERROR, /SOURCE, and so on) to assign one or more corresponding attributes to a display. By default, if you do not specify a qualifier, /SCROLL is assumed.

If you use the SELECT command without specifying a display name, in general the attribute assignment indicated by the qualifier is canceled (unselected). To reassign display attributes, you must use another SELECT command. For more information, see the individual qualifier.

For a list of the key definitions associated with the SELECT command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.

Related commands:

Examples

#1 
DBG> SELECT/SOURCE/SCROLL SRC2

This command selects display SRC2 as the current source and scrolling display.

#2 
DBG> SELECT/INPUT/ERROR OUT

This command selects display OUT as the current input and error display. This causes debugger input, debugger output (assuming OUT is the current output display), and debugger diagnostic messages to be logged in the OUT display in the correct sequence.

#3 
DBG> SELECT/SOURCE

This command unselects (deletes the source attribute from) the currently selected source display. The output of a TYPE or EXAMINE/SOURCE command then goes to the currently selected output display.

SET ABORT_KEY

Assigns the debugger's abort function to another Ctrl-key sequence. By default, Ctrl/C does the abort function.

Note

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

Format

SET ABORT_KEY = CTRL_character

PARAMETERS

character

Specifies the key you press while holding down the Ctrl key. You can specify any alphabetic character.

DESCRIPTION

By default, the Ctrl/C sequence, when entered within a debugging session, aborts the execution of a debugger command and interrupts program execution. The SET ABORT_KEY command enables you to assign the abort function to another Ctrl-key sequence. This might be necessary if your program has a Ctrl/C AST service routine enabled.

Many Ctrl-key sequences have predefined functions, and the SET ABORT_KEY command enables you to override such definitions (see the OpenVMS User's Manual). Some of the Ctrl-key characters not used by the operating system are G, K, N, and P.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]

[HR] 

  4538P039.HTM
  OSSG Documentation
  22-NOV-1996 13:02:31.74

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal