[Digital logo]
[HR]

OpenVMS Debugger Manual


Previous | Contents

The QUIT command starts the debugger exit handlers to close log files, restores the screen and keypad states, and so on.

The EXIT command and Ctrl/Z function identically. They perform the same functions as the QUIT command, and additionally execute any exit handlers that are declared in your program.

1.9 Establishing a Multiprocess Debugging Configuration

You can start the debugger in either the default configuration or the multiprocess configuration to debug programs that run in either one or several processes, respectively. The configuration depends on the current definition of the logical name DBG$PROCESS. Before starting the debugger, enter the DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of DBG$PROCESS:

For more information about multiprocess debugging, see Chapter 14.

1.10 Debugging a Program on a Workstation Running DECwindows Motif

If you are at a workstation running DECwindows Motif, by default the debugger starts up in the DECwindows Motif interface, which is displayed on the workstation specified by the DECwindows Motif applicationwide logical name DECW$DISPLAY.

The logical name DBG$DECW$DISPLAY enables you to override the default to display the debugger's command interface in a DECterm window, along with any program input/output (I/O).

To display the debugger's command interface in a DECterm window:

  1. Enter the following definition in the DECterm window from which you plan to start the debugger:
    $ DEFINE/JOB DBG$DECW$DISPLAY " "
    

    You can specify one or more space characters between the quotation marks. It is recommended that you use a job definition for the logical name. If you use a process definition, it must not have the CONFINE attribute.
  2. Start the debugger in the usual way from that DECterm window (see Section 1.3.1). The debugger's command interface is displayed in the same window.

For example:

$ DEFINE/JOB DBG$DECW$DISPLAY " "
$ DEBUG/KEEP
           Debugger Banner and Version Number
DBG>

You can now bring your program under debugger control as explained in Section 1.3.1. For more information about the logical names DBG$DECW$DISPLAY and DECW$DISPLAY, see Section 9.7.3.

1.11 Debugging Detached Processes that Run with No CLI

The design and implementation of the debugger's DECwindows Motif interface requires that the process being debugged have a command line interpreter (CLI). To debug a detached process (such as a print symbiont) that does not have a CLI, you must use the character-cell (screen mode) interface to the debugger.

To do so, direct DBG$INPUT, DBG$OUTPUT and DBG$ERROR to a terminal port that is not logged in. This allows the image to be debugged with the standard character-cell interface on that terminal.

For example:

    $ DEFINE/TABLE=GROUP DBG$INPUT  TTA3: 
    $ DEFINE/TABLE=GROUP DBG$OUTPUT TTA3: 
    $ DEFINE/TABLE=GROUP DBG$ERROR  TTA3: 
    $ START/QUEUE SYS$PRINT /PROCESSOR=dev:[dir]test_program 
 
    [Debugger starts up on logged-out terminal TTA3:] 

1.12 Debugger Command Summary

The following sections list all the debugger commands and any related DCL commands in functional groupings, along with brief descriptions. During a debugging session, you can get online help on all debugger commands and their qualifiers by typing HELP at the debugger prompt (see Section 2.1).

1.12.1 Starting and Ending a Debugging Session

The following commands start the debugger, bring a program under debugger control, and interrupt and end a debugging session. Except where the DCL commands RUN and DEBUG are indicated specifically, all commands are debugger commands.
$DEBUG/KEEP (DCL) Starts the debugger.
$RUN SYS$SHARE:DEBUGSHR.EXE (DCL) Starts the debugger.
RUN filespec Brings a program under debugger control.
RERUN Reruns the program currently under debugger control.
$RUN program-image (DCL) If the specified image was linked using LINK/DEBUG, starts the debugger and also brings the image under debugger control. When you start the debugger in this manner, you cannot then use the debugger RUN or RERUN commands. You can use the /[NO]DEBUG qualifiers with the RUN command to control whether the debugger is started when the program is executed.
EXIT, Ctrl/Z Ends a debugging session, executing all exit handlers.
QUIT Ends a debugging session without executing any exit handlers declared in the program.
Ctrl/C Aborts program execution or a debugger command without interrupting the debugging session.
(SET,SHOW) ABORT_KEY (Assigns, identifies) the default Ctrl/C abort function to another Ctrl/key sequence, identifies the Ctrl/key sequence currently defined for the abort function.
Ctrl/Y
$DEBUG
(DCL) Interrupts a program that is running without debugger control and starts the debugger.
ATTACH Passes control of your terminal from the current process to another process.
SPAWN Creates a subprocess, which enables you to execute DCL commands without ending a debugging session or losing your debugging context.

1.12.2 Controlling and Monitoring Program Execution

The following commands control and monitor program execution:
GO Starts or resumes program execution.
STEP Executes the program up to the next line, instruction, or specified instruction.
(SET,SHOW) STEP (Establishes, displays) the default qualifiers for the STEP command.
(SET,SHOW,CANCEL) BREAK (Sets, displays, cancels) breakpoints.
(ACTIVATE,DEACTIVATE) BREAK (Activates, deactivates) previously set breakpoints.
(SET,SHOW,CANCEL) TRACE (Sets, displays, cancels) tracepoints.
(ACTIVATE,DEACTIVATE) TRACE (Activates, deactivates) previously set tracepoints.
(SET,SHOW,CANCEL) WATCH (Sets, displays, cancels) watchpoints.
(ACTIVATE,DEACTIVATE) WATCH (Activates, deactivates) previously set watchpoints.
SHOW CALLS Identifies the currently active routine calls.
SHOW STACK Gives additional information about the currently active routine calls.
CALL Calls a routine.

1.12.3 Examining and Manipulating Data

The following commands examine and manipulate data:
EXAMINE Displays the value of a variable or the contents of a program location.
SET MODE [NO]OPERANDS Controls whether the address and contents of the instruction operands are displayed when you examine an instruction.
DEPOSIT Changes the value of a variable or the contents of a program location.
DUMP Displays the contents of memory in a manner similar to the DCL command DUMP.
EVALUATE Evaluates a language or address expression.
MONITOR (Applies only to the debugger's DECwindows Motif interface.) Displays the current value of a variable or language expression in the monitor view of the DECwindows Motif interface.

1.12.4 Controlling Type Selection and Radix

The following commands control type selection and radix:
(SET,SHOW,CANCEL) RADIX (Establishes, displays, restores) the radix for data entry and display.
(SET,SHOW,CANCEL) TYPE (Establishes, displays, restores) the type for program locations that are not associated with a compiler-generated type.
SET MODE [NO]G_FLOAT Controls whether double-precision floating-point constants are interpreted as G_FLOAT or D_FLOAT.

1.12.5 Controlling Symbol Searches and Symbolization

The following commands control symbol searches and symbolization:
SHOW SYMBOL Displays symbols in your program.
(SET,SHOW,CANCEL) MODULE Sets a module by loading its symbol information into the debugger's symbol table, identifies, cancels a set module.
(SET,SHOW,CANCEL) IMAGE Sets a shareable image by loading data structures into the debugger's symbol table, identifies, cancels a set image.
SET MODE [NO]DYNAMIC Controls whether or not modules and shareable images are set automatically when the debugger interrupts execution.
(SET,SHOW,CANCEL) SCOPE (Establishes, displays, restores) the scope for symbol searches.
SYMBOLIZE Converts a memory address to a symbolic address expression.
SET MODE [NO]LINE Controls whether or not program locations are displayed in terms of line numbers or routine-name + byte offset.
SET MODE [NO]SYMBOLIC Controls whether or not program locations are displayed symbolically or in terms of numeric addresses.

1.12.6 Displaying Source Code

The following commands control the display of source code:
TYPE Displays lines of source code.
EXAMINE/SOURCE Displays the source code at the location specified by the address expression.
SEARCH Searches the source code for the specified string.
(SET,SHOW) SEARCH (Establishes, displays) the default qualifiers for the SEARCH command.
SET STEP [NO]SOURCE Enables/disables the display of source code after a STEP command has been executed or at a breakpoint, tracepoint, or watchpoint.
(SET,SHOW) MARGINS (Establishes, displays) the left and right margin settings for displaying source code.
(SET,SHOW,CANCEL) SOURCE (Creates, displays, cancels) a source directory search list.

1.12.7 Using Screen Mode

The following commands control screen mode and screen displays:
SET MODE [NO]SCREEN Enables/disables screen mode.
DISPLAY Creates or modifies a display.
SCROLL Scrolls a display.
EXPAND Expands or contracts a display.
MOVE Moves a display across the screen.
(SHOW,CANCEL) DISPLAY (Identifies, deletes) a display.
(SET,SHOW,CANCEL) WINDOW (Creates, identifies, deletes) a window definition.
SELECT Selects a display for a display attribute.
SHOW SELECT Identifies the displays selected for each of the display attributes.
SAVE Saves the current contents of a display into another display.
EXTRACT Saves a display or the current screen state into a file.
(SET,SHOW) TERMINAL (Establishes, displays) the terminal screen height and width that the debugger uses when it formats displays and other output.
SET MODE [NO]SCROLL Controls whether an output display is updated line by line or once per command.
Ctrl/W
DISPLAY/REFRESH
Refreshes the screen.

1.12.8 Editing Source Code

The following commands control source editing from a debugging session:
EDIT Starts an editor during a debugging session.
(SET,SHOW) EDITOR (Establishes, identifies) the editor started by the EDIT command.

1.12.9 Defining Symbols

The following commands define and delete symbols for addresses, commands, or values:
DEFINE Defines a symbol as an address, command, or value.
DELETE Deletes symbol definitions.
(SET,SHOW) DEFINE (Establishes, displays) the default qualifier for the DEFINE command.
SHOW SYMBOL/DEFINED Identifies symbols that have been defined with the DEFINE command.

1.12.10 Using Keypad Mode

The following commands control keypad mode and key definitions:
SET MODE [NO]KEYPAD Enables/disables keypad mode.
DEFINE/KEY Creates key definitions.
DELETE/KEY Deletes key definitions.
SET KEY Establishes the key definition state.
SHOW KEY Displays key definitions.

1.12.11 Using Command Procedures, Log Files, and Initialization Files

The following commands are used with command procedures and log files:
@ (execute procedure) Executes a command procedure.
(SET,SHOW) ATSIGN (Establishes, displays) the default file specification that the debugger uses to search for command procedures.
DECLARE Defines parameters to be passed to command procedures.
(SET,SHOW) LOG (Specifies, identifies) the debugger log file.
SET OUTPUT [NO]LOG Controls whether or not a debugging session is logged.
SET OUTPUT [NO]SCREEN_LOG Controls whether or not, in screen mode, the screen contents are logged as the screen is updated.
SET OUTPUT [NO]VERIFY Controls whether or not debugger commands are displayed as a command procedure is executed.
SHOW OUTPUT Identifies the current output options established by the SET OUTPUT command.

1.12.12 Using Control Structures

The following commands establish conditional and looping structures for debugger commands:
FOR Executes a list of commands while incrementing a variable.
IF Executes a list of commands conditionally.
REPEAT Executes a list of commands a specified number of times.
WHILE Executes a list of commands while a condition is true.
EXITLOOP Exits an enclosing WHILE, REPEAT, or FOR loop.

1.12.13 Debugging Multiprocess Programs

The following commands debug multiprocess programs. Note that these commands are specific to multiprocess programs. Many of the commands listed under other categories have qualifiers or parameters that are specific to multiprocess programs (for example, SET BREAK/ACTIVATING, EXIT process-spec, DISPLAY/PROCESS=).
CONNECT Brings a process under debugger control.
DEFINE/PROCESS_GROUP Assigns a symbolic name to a list of process specifications.
DO Executes commands in the context of one or more processes.
SET MODE [NO]INTERRUPT Controls whether execution is interrupted in other processes when it is paused in some process.
(SET,SHOW) PROCESS Modifies the multiprocess debugging environment, displays process information.

1.12.14 Additional Commands

The following commands are used for miscellaneous purposes:
HELP Displays online help on debugger commands and selected topics.
(DISABLE,ENABLE,SHOW) AST (Disables, enables) the delivery of ASTs in the program, identifies whether delivery is enabled or disabled.
(SET,SHOW) EVENT_FACILITY (Establishes, identifies) the current run-time facility for Ada, DECthreads, and SCAN events.
(SET,SHOW) LANGUAGE (Establishes, identifies) the current language.
SET MODE [NO]SEPARATE Controls whether the debugger, when used on a workstation running VWS, creates a separate window for debugger input and output.
SET OUTPUT [NO]TERMINAL Controls whether debugger output, except for diagnostic messages, is displayed or suppressed.
SET PROMPT Specifies the debugger prompt.
(SET,SHOW) TASK Modifies the tasking environment, displays task information.
(SET,SHOW) VECTOR_MODE (VAX only) Enables or disables a debugger vector mode option, identifies the current vector mode option (for vectorized programs).
SHOW EXIT_HANDLERS Identifies the exit handlers declared in the program.
SHOW MODE Identifies the current debugger modes established by the SET MODE command (for example, screen mode, step mode).
SHOW OUTPUT Identifies the current output options established by the SET OUTPUT command.
SYNCHRONIZE VECTOR_MODE (VAX only) Forces immediate synchronization between the scalar and vector processors (for vectorized programs).


+VAX specific


Part 2
Command Interface

This part describes the debugger's command interface.

For information about the debugger's DECwindows Motif interface, see Part 3.


Chapter 2
Getting Started with the Debugger

This chapter gives a tutorial introduction to the debugger's command interface.

The way you use the debugger depends on several factors: the kind of program you are working on, the kinds of errors you are looking for, and your own personal style and experience with the debugger. This chapter explains the following basic tasks that apply to most situations:

Several examples are language specific. However, the general concepts are readily adaptable to all supported languages.

The sample debugging session in Section 2.6 shows how to use some of this information to locate an error and correct it.

For information about starting and ending a debugging session, see Section 1.3.

2.1 Entering Debugger Commands and Accessing Online Help

After you start the debugger as explained in Section 1.3, you can enter debugger commands whenever the debugger prompt (DBG>) is displayed. To enter a command, type it at the keyboard and press Return. For example, the following command sets a watchpoint on the variable COUNT:

DBG> SET WATCH COUNT

Detailed reference information about debugger commands is available in Part 5 and through the debugger's online help:

Online help is also available on the following topics:

To display help about any of these topics, type HELP topic. For example, to display information about diagnostic messages, type HELP Messages.

When you start the debugger, a few commonly used command sequences are automatically assigned to the keys on the numeric keypad (to the right of the main keyboard). Thus, you can perform certain functions either by entering a command or by pressing a keypad key.

The predefined key functions are identified in Figure 2-1.

Figure 2-1 Keypad Key Functions Predefined by the Debugger---Command Interface



Most keypad keys have three predefined functions---DEFAULT, GOLD, and BLUE.

In Figure 2-1, the DEFAULT, GOLD, and BLUE functions are listed within each key's outline, from top to bottom, respectively. For example:

Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down, left, right, or up, respectively. By putting the keypad in the MOVE, EXPAND, or CONTRACT state, indicated in Figure 2-1, you can also use these keys to move, expand, or contract displays in four directions. Enter the command HELP Keypad_Definitions to display the keypad key definitions.

You can redefine keypad key functions with the DEFINE/KEY command.

2.2 Displaying Source Code

The debugger provides two modes for displaying information: noscreen mode and screen mode. By default, when you start the debugger, you are in noscreen mode, but you might find that it is easier to view source code in screen mode. The following sections briefly describe both modes.

2.2.1 Noscreen Mode

Noscreen mode is the default, line-oriented mode of displaying input and output. The interactive examples throughout this chapter, excluding Section 2.2.2, show noscreen mode.

In noscreen mode, use the TYPE command to display one or more source lines. For example, the following command displays line 7 of the module in which execution is currently paused:

DBG> TYPE 7
module SWAP_ROUTINES 
     7:        TEMP := A;
DBG>

The display of source lines is independent of program execution. To display source code from a module (compilation unit) other than the one in which execution is currently paused, use the TYPE command with a path name to specify the module. For example, the following command displays lines 16 to 21 of module TEST:

DBG> TYPE TEST\16:21

Path names are discussed in more detail in Section 2.3.2, in conjunction with the STEP command.

You can also use the EXAMINE/SOURCE command to display the source line for a routine or any other program location that is associated with an instruction.


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

[HR]

  4538P002.HTM
  OSSG Documentation
  22-NOV-1996 13:01:31.99

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal