Updated: 11 December 1998 |
OpenVMS Debugger Manual
Previous | Contents | Index |
Online help is always available during a debugging session. Online help contains information about all debugger commands and additional selected topics.
During a debugging session, you can display the source code for program modules written in any of the languages supported by the OpenVMS Debugger.
In screen mode, you can capture and display various kinds of information in scrollable display units. You can move these display units around the screen and resize them as needed. Automatically updated source, instruction, and register displays units are available. You can selectively direct debugger input, output, and diagnostic messages to specific display units. You can also create display units to capture the output of specific command sequences.
The kept debugger enables you to run different program images or rerun the same image from the current debugging session without having to first exit and restart the debugger. When you rerun a program, you can choose to retain or cancel any previously set breakpoints, as well as most tracepoints and watchpoints.
The OpenVMS Debugger has an optional DECwindows Motif graphical user interface (GUI) that provides access to common debugger commands by means of pushbuttons, pulldown menus, and popup menus. The GUI is an optional enhancement to the debugger command line interface that is available on workstations running DECwindows Motif. When using the GUI, you have full command-line access to all debugger commands that are relevant within a DECwindows Motif environment.
The OpenVMS Debugger has an optional client/server configuration that allows you to access the debugger and its functions from a PC running Microsoft Windows 95 or Microsoft Windows NT. This debugger implementation has a debug server that runs on OpenVMS on a VAX or Alpha CPU, and a debug client interface that runs on Microsoft Windows NT and Microsoft Windows 95 on an Intel or Alpha CPU.
The client/server configuration allows you to debug programs that run on an OpenVMS node remotely from another OpenVMS node using the DECwindows Motif interface, or from a PC using the Microsoft Windows interface. Up to 31 debug clients can simultaneously access the same debug server, which allows many debugging options.
When you start the debugger, several predefined debugger command sequences are assigned to the keys of the numeric keypad of the VT52, VT100, and LK201 keyboards. You can also create your own key definitions.
As you find errors during a debugging session, you can use the EDIT command to use any editor available on your system. You can specify the editor with the SET EDITOR command. If you use the DEC Language-Sensitive Editor (LSE), the editing cursor is automatically positioned within the source file corresponding to the source code that appears in the screen-mode source display.
You can direct the debugger to execute a command procedure (a file of debugger commands) to re-create a debugging session, to continue a previous session, or to avoid typing the same debugger commands many times during a debugging session. In addition, you can pass parameters to command procedures.
You can create an initialization file that contains debugger commands to set default debugging modes, screen display definitions, keypad key definitions, symbol definitions, and so on. Upon startup, the OpenVMS Debugger automatically executes the initialization file to create the predefined debugging environment.
You can create a log file to contain a record of command input and debugger output. You can then use the log file to analyze the debugging session, or edit the file for use as a command procedure in subsequent debugging sessions.
You can define your own symbols to represent lengthy commands, address
expressions, or values in abbreviated form.
1.2 Preparing an Executable Image for Debugging
To take full advantage of symbolic debugging, you must first compile
and link the program's modules (compilation units) using the compiler
and linker /DEBUG qualifiers as explained in Section 1.2.1 and
Section 1.2.2.
1.2.1 Compiling a Program for Debugging
Example 1-1 shows how to compile (for debugging) a C program, FORMS.EXE, that consists of two source modules: FORMS.C and INVENTORY.C. FORMS.C is the main program module.
Example 1-1 Compiling a Program with the /DEBUG Qualifier |
---|
$ CC/DEBUG/NOOPTIMIZE INVENTORY,FORMS |
Note that the /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults for some languages. These qualifiers are used in the example for emphasis. (For information about compiling programs in a specific language, see the documentation for that language.)
The /DEBUG qualifier in the compiler command in Example 1-1 directs the compiler to include the symbol information associated with FORMS.C and INVENTORY.C in object modules FORMS.OBJ and INVENTORY.OBJ, respectively. This enables you to refer to the symbolic names of variables, routines, and other declared symbols while debugging the program. Only object files created with the /DEBUG qualifier contain symbol information. You can control whether to include all symbol information or only that required to trace program flow (see Section 5.1.1).
Some compilers optimize the object code to reduce the size of the
program or to make it run faster. In such cases the object code does
not always match the source code, which can make debugging more
difficult. To avoid this, compile the program with the /NOOPTIMIZE
command qualifier (or equivalent). After the nonoptimized program has
been debugged, you can recompile and test it again without the
/NOOPTIMIZE qualifier to take advantage of optimization. Section 14.1
describes some of the effects of optimization.
1.2.2 Linking a Program for Debugging
Example 1-2 shows how to link a C program, FORMS.EXE, that consists of two source modules: FORMS.C and INVENTORY.C. FORMS.C is the main program module. Both source modules were compiled with the /DEBUG qualifier (see Example 1-1).
Example 1-2 Linking a Program with the /DEBUG Qualifier |
---|
$ LINK/DEBUG FORMS,INVENTORY |
On VAX processors, explicitly identify linker options files (as necessary) in the LINK command. In Example 1-3, the /OPTIONS qualifier indicates that OPTIONS_FILE is a linker options file.
Example 1-3 Linking a Program with the /OPTIONS_FILE Qualifier (VAX Only) |
---|
$ LINK/DEBUG FORMS,INVENTORY,OPTIONS_FILE/OPTIONS |
In Examples 1-2 and 1-3, the /DEBUG qualifier in the LINK command directs the linker to include in the executable image all symbol information that is contained in the object modules being linked. Most languages require that you specify all included object modules in the LINK command. See Section 5.1.3 for more details on how to control symbol information with the LINK command.
On Alpha systems, you can now debug programs that have been linked with the /DSF qualifier (and therefore have a separate debug symbol file). The /DSF qualifer to the LINK command directs the linker to create a separate .DSF file to contain the symbol information. This allows more flexible debugging options. Debugging such a program requires the following:
For example:
$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM $ LINK/DSF=TESTDISK:[TESTDIR]TESTPROGRAM.DSF TESTPROGRAM $ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR] $ DEBUG/KEEP TESTPROGRAM |
See Section 5.1.5 for more information about debugging programs that
have separate symbol files. See the OpenVMS Linker Utility Manual for more information
about using the /DSF qualifier.
1.2.3 Controlling Debugger Activation with the LINK and RUN Commands
In addition to passing symbol information to the executable image, the
LINK/DEBUG command causes the image activator to start the debugger if
you execute the resulting image with the DCL command RUN. (See
Section 1.6.)
You can also run an image compiled and linked with the /DEBUG command qualifiers without invoking the debugger. To do so, use the /NODEBUG qualifier in the DCL command RUN. For example:
$ RUN/NODEBUG FORMS |
This is convenient for checking your program once you think it is error free. Note that the data required by the debugger occupies space within the executable image. When your program is correct, you can link your program again without the /DEBUG qualifier. This creates an image with only traceback data in the debug symbol table, which creates a smaller executable file.
Table 1-1 summarizes how to control debugger activation with the LINK and RUN command qualifiers. Note that the LINK command qualifiers /[NO]DEBUG and /[NO]TRACEBACK affect not only debugger activation but also the maximum level of symbol information provided when debugging.
LINK Command Qualifier | To Run Program without Debugger | To Run Program with Debugger | Maximum Symbol Information Available1 |
---|---|---|---|
/DEBUG | RUN/NODEBUG | RUN | Full |
None or
/TRACEBACK or /NODEBUG 2 |
RUN | RUN/DEBUG | Only traceback 3 |
/NOTRACEBACK | RUN | RUN/DEBUG 4 | None |
/DSF 5 | RUN | DEBUG/KEEP 6 | Full |
/DSF 5 | RUN | DEBUG/SERVER 6 | Full |
On OpenVMS Alpha systems, anything that uses system service
interception (SSI), such as the debugger or the Heap Analyzer, is
unable to intercept system service call images activated by shared
linkage. The image activator, therefore, avoids shared linkage for
images linked or run with /DEBUG, and instead activates private image
copies. This affects performance of user applications under debugger or
Heap Analyzer control, as images activated by shared linkage run faster.
1.3 Debugging a Program with the Kept Debugger
You can run the OpenVMS Debugger as the kept debugger, which allows you to rerun the same program again and again, or to run different programs, all without terminating the debugging session. This section explains how to:
This section explains how to start the kept debugger from DCL level ($) and bring your program under debugger control. Section 1.6 and Section 1.7 describe other ways to invoke the debugger.
Using the kept debugger enables you to use the debugger's RERUN and RUN features explained in Section 1.3.3 and Section 1.3.4, respectively.
To start the kept debugger and bring your program under debugger control:
$ DEBUG/KEEP |
DBG> RUN FORMS Language: C, Module: FORMS DBG> |
The message displayed indicates that this debugging session is initialized for a C program and that the name of the main program unit (the module containing the image transfer address) is FORMS. The initialization sets up language-dependent debugger parameters. These parameters control the way the debugger parses names and expressions, formats debugger output, and so on. See Section 4.1.9 for more information about language-dependent parameters.
The debugger suspends program execution (by setting a temporary breakpoint) at the start of the main program unit or, with certain programs, at the start of some initialization code, at which point the debugger displays the following message:
Type GO to reach main program |
With some of these programs (for example, Ada programs), the temporary breakpoint enables you to debug the initialization code using full symbolic information. See Section 14.3 for more information.
At this point, you can debug your program as explained in Chapter 2.
RUN and RERUN Command Options for Programs That Require Arguments
Some programs require arguments. This section explains how to use the RUN and RERUN commands with the /ARGUMENTS and /COMMAND qualifiers when debugging a program with the kept debugger.
After starting the kept debugger, you can specify the image to be debugged by entering the RUN command with an image name, or the RUN/COMMAND command with a DCL foreign command. Note that you can specify a DCL foreign command only with the /COMMAND qualifier to the RUN command.
You can specify a list of arguments with the /ARGUMENTS qualifier to the RUN and RERUN commands.
The different methods are shown in the following example of a debugger session. The program to be debugged is echoargs.c, a program that echoes the input arguments to the terminal:
#include <stdio.h> main(int argc, char *argv[]) { int i; for (i = 0; i < argc; i++) printf("%s\n", argv[i]); } |
Compile and link the program as follows:
$ cc/debug/noopt echoargs.c $ link/debug echoargs |
Define a DCL foreign command as follows:
$ ECHO == "$ sys$disk:[]echoargs.exe" |
Invoke the kept debugger. The debugger session in the example that follows shows three ways of passing arguments:
RUN with /COMMAND and /ARGUMENTS
This section of the debugger session shows the use of the debugger RUN command with the /COMMAND and /ARGUMENTS qualifiers. The /COMMAND qualifier specifies DCL foreign command echo. The /ARGUMENTS qualifier specifies arguments fa sol la mi. The first GO command executes the initialization code of echoargs.exe after which the debugger suspends program execution at the temporary breakpoint at the start of the program. The second GO command executes echoargs.exe, which correctly echoes the arguments to the screen.
$ debug/keep Debugger Banner and Version Number DBG> run /command="echo"/arguments="fa sol la mi" Language: C, Module: ECHOARGS Type GO to reach main program DBG> go break at routine ECHOARGS\main 265: { DBG> go _dsa1:[jones.test]echoargs.exe;2 fa sol la mi 'Normal successful completion' |
This section of the debugger session shows the use of the RERUN command with the /ARGUMENTS qualifier to run the same image again, with new arguments fee fii foo fum. (If you omit the /ARGUMENTS qualifier, the debugger reruns the program with the arguments used previously.)
The first GO command executes the initialization code of echoargs.exe after which the debugger suspends program execution at the temporary breakpoint at the start of the program. The second GO command executes echoargs.exe, which correctly echoes the arguments to the screen.
DBG> rerun/arg="fee fii foo fum" Language: C, Module: ECHOARGS Type GO to reach main program DBG> go break at routine ECHOARGS\main 265: { DBG> go _dsa1:[jones.test]echoargs.exe;2 fee fii foo fum 'Normal successful completion' |
RUN with /ARGUMENTS and Image Name
This section of the debugging session uses the RUN command to invoke a fresh image of echoargs, with the /ARGUMENTS qualifier to specify a new set of arguments a b c.
The first GO command executes the initialization code of echoargs.exe after which the debugger suspends program execution at the temporary breakpoint at the start of the program. The second GO command executes echoargs.exe, which correctly echoes the arguments to the screen.
DBG> run/arg="a b c" echoargs Language: C, Module: ECHOARGS Type GO to reach main program DBG> go break at routine ECHOARGS\main 265: { DBG> go _dsa1:[jones.test]echoargs.exe;2 a b c 'Normal successful completion' DBG> quit |
Note the following restrictions about the debugger RUN command:
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4538PRO_001.HTML
|