OpenVMS Debugger Manual


Previous Contents Index

1.6 Starting the Debugger by Running a Program

You can bring your program under control of the non-kept debugger in one step by entering the DCL command RUN filespec.

Note that when running the non-kept debugger, you cannot use the debugger RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4, respectively. To rerun the same program or run another program under debugger control, you must first exit the debugger and start it again.

To start the non-kept debugger by running a program:

  1. Verify that you have compiled and linked the program as explained in Section 1.2.1 and Section 1.2.2.
  2. Enter the DCL command RUN filespec to start the debugger.

For example:


$ RUN FORMS
           Debugger Banner and Version Number
%DEBUG-I-NOTATMAIN, Language: C, Module: FORMS
DBG>

Upon startup, the debugger displays its banner, executes any user-defined initialization file, sets the language-dependent parameters to the source language of the main program, suspends execution at the start of the main program, and prompts for commands.

For more information about startup conditions, see Section 1.2.3 and Section 1.3.1.

1.7 Starting the Debugger After Interrupting a Running Program

You can bring a program that is executing freely under debugger control. This is useful either if you suspect that the program might be in an infinite loop or if you see erroneous output.

To bring your program under debugger control:

  1. Verify that you have compiled and linked the program as explained in Section 1.2.
  2. Enter the DCL command RUN/NODEBUG filespec to execute the program without invoking the debugger.
  3. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL command interpreter.
  4. Enter the DCL command DEBUG. This invokes the non-kept debugger.

For example:


$ RUN/NODEBUG FORMS
   .
   .
   .
[Ctrl/Y]
Interrupt
$ DEBUG
           Debugger Banner and Version Number
%DEBUG-I-NOTATMAIN, Language: C, Module: FORMS
DBG> 

Upon startup, the debugger displays its banner, executes any user-defined initialization file, sets the language-dependent parameters to the source language of the module where execution is interrupted, and prompts for commands.

To know where the execution is interrupted, enter the SHOW CALLS command to determine where execution is paused and to display the sequence of routine calls on the call stack (the SHOW CALLS command is described in Section 2.3.3).

Note that when running the non-kept debugger, you cannot use the debugger RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4, respectively. To rerun the same program or run another program under debugger control, you must first exit the debugger and start it again.

For more information about startup conditions, see Section 1.2.3 and Section 1.3.1.

1.8 Ending a Debugging Session

To end a debugging session in an orderly manner and return to DCL level, enter EXIT or QUIT or press Ctrl/Z. For example:


DBG> EXIT
$

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 Debugging a Program on a Workstation Running DECwindows Motif

If you are at a workstation running HP DECwindows Motif for OpenVMS, by default the debugger starts up in the HP DECwindows Motif for OpenVMS user interface, which is displayed on the workstation specified by the HP DECwindows Motif for OpenVMS 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. You should 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.8.3.

On a workstation running HP DECwindows Motif for OpenVMS, you can also run the client/server configuration of the OpenVMS debugger. See Section 9.9 for details.

1.10 Debugging a Program from a PC Running the Debug Client

The OpenVMS Debugger Version 7.2 and later features a client/server interface that allows you to debug programs running on OpenVMS on Alpha from a PC debug client interface running:

Note

The client/server interface for OpenVMS Integrity server systems is planned for a future release.

The OpenVMS client/server configuration allows the following:

The client and server communicate using Distributed Computing Environment/Remote Procedure Calls (DCE/RPC) over one of the following transports:

To invoke the server on an OpenVMS node, enter the following command:


$ DEBUG/SERVER

The server displays its network binding strings. You must specify one of these strings when you connect a HP DECwindows Motif for OpenVMS or Microsoft Windows client to this server. For example:


$ DEBUG/SERVER 
 
%DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: YES 
%DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.138[1034] 
%DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001] 
%DEBUG-I-WATCH: Network Binding: ncadg_ip_udp:16.32.16.138[1045] 
%DEBUG-I-AWAIT: Ready for client connection... 

In the client's Server Connection dialog box, enter the type of network protocol (TCP/IP, DECnet, or UDP) and the corresponding network binding string (see Section 9.9.4).

Note

Messages and program output appear by default in the window in which you start the server. You can redirect program output to another window as required.

For more information about using the debug client interface, see Chapter 11.

1.11 Debugging Detached Processes That Run with No CLI

The design and implementation of the debugger's HP DECwindows Motif for OpenVMS user 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 Configuring Process Quotas for the Debugger

Each user needs a PRCLM quota sufficient to create an additional subprocess for the debugger, beyond the number of processes needed by the program.

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. You may need to increase these quotas to account for the debugger subprocess as follows:

1.13 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.13.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 kept debugger.
$RUN SYS$SHARE:DEBUGSHR.EXE (DCL) Starts the kept debugger.
$DEBUG/SERVER (DCL) Starts the debug server.
$DEBUG/CLIENT (DCL) Starts the debug client.
$RUN SYS$SHARE:DEBUGUISHR.EXE (DCL) Starts the debug client.
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.13.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.13.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 HP DECwindows Motif for OpenVMS user interface) Displays the current value of a variable or language expression in the monitor view of the HP DECwindows Motif for OpenVMS user interface

1.13.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.13.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.13.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.13.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.13.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


Previous Next Contents Index