Document revision date: 19 July 1999

Online Help

Online help is always available during a debugging session. Online help contains information about all debugger commands and additional selected topics.

Source Code Display

During a debugging session, you can display the source code for program modules written in any of the languages supported by the OpenVMS Debugger.

Screen Mode

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.

Kept Debugger

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.

DECwindows Motif Interface

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.

Microsoft Windows Interface

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.

Client/Server Configuration

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.

Keypad Mode

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.

Source Editing

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.

Command Procedures

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.

Initialization Files

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.

Log Files

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.

Symbol Definitions

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:

• The name of the .DSF file must match the name of the .EXE file being debugged.
• You must be running in a configuration in which DBG$PROCESS is defined as DEFAULT or MULTIPROCESS.
• You must define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF file.

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.

Table 1-1 Controlling Debugger Activation with the LINK and RUN Commands

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:

• Start the kept debugger and then bring a program under debugger control
• Rerun the same program from the current debugging session
• Run another program from the current debugging session
• Interrupt program execution and abort debugger commands
• Interrupt a debugging session and then return to the debugging session

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:

1. Verify that you have compiled and linked the program as explained in Section 1.2.
2. Verify that the debugging configuration (default or multiprocess) is appropriate for the kind of program you are going to debug (see Section 1.9). For a program that runs in only one process (the typical case), use the default configuration.
3. Enter the following command line:

   $ DEBUG/KEEP

   
   Upon startup, the debugger displays its banner, executes any user-defined initialization file (see Section 13.2), and displays its DBG> prompt to indicate that you can now enter debugger commands, as explained in Section 2.1.

4. Bring your program under debugger control with the debugger RUN command, specifying the executable image of your program as the parameter. For example:

   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
• RERUN with /ARGUMENTS
• RUN with /ARGUMENTS and image name

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'

RERUN with /ARGUMENTS

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

RUN Command Restrictions

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 Section 1.7).
• 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.

	privacy and legal statement
4538PRO_001.HTML