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

In Example 1-2, 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 and Integrity server systems, you can now debug programs that have been linked with the /DSF qualifier (and therefore have a separate debug symbol file). The /DSF qualifier 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 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 1	RUN/NODEBUG	RUN	Full
None or /TRACEBACK or /NODEBUG 3	RUN	RUN/DEBUG	Only traceback 4
/NOTRACEBACK	RUN	RUN/DEBUG 5	None
/DSF 6	RUN	DEBUG/KEEP 7	Full
/DSF 6	RUN	DEBUG/SERVER 7	Full

1.3 Debugging a Program with the Kept Debugger

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

3. 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 %DEBUG-I-INITIAL,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:

%DEBUG-I-NOTATMAIN, 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" %DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS %DEBUG-I-NOTATMAIN,Type GO to reach main program DBG> GO break at routine ECHOARGS\main 1602: for (i = 0; i < argc; i++) DBG> GO _dsa1:[jones.test]echoargs.exe;2 fa sol la mi %DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, 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/ARGUMENTS="fee fii foo fum" %DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS %DEBUG-I-NOTATMAIN,Type GO to reach main program DBG> GO break at routine ECHOARGS\main 1602: for (i = 0; i < argc; i++) DBG> GO _dsa1:[jones.test]echoargs.exe;2 fee fii foo fum %DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, 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/ARGUMENTS="a b c" echoargs %DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS %DEBUG-I-NOTATMAIN,Type GO to reach main program DBG> GO break at routine ECHOARGS\main 1602: for (i = 0; i < argc; i++) DBG> GO _dsa1:[jones.test]echoargs.exe;2 a b c %DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, 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).
• Unless you are using the debugger client/server interface, you cannot run a program under debugger control over a network link. See Section 9.9 and Chapter 11 for more information about using the debugger client/server interface.

When your program completes execution normally during a debugging session, the debugger issues the following message:

%DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, Normal successful completion')

You then have the following options:

• You can rerun your program from the same debugging session (see Section 1.3.3).
• You can run another program from the same debugging session (see Section 1.3.4).
• You can end the debugging session (see Section 1.8).

You can rerun the program currently under debugger control at any time during a debugging session, provided you invoked the kept debugger as explained in Section 1.3.1. Use the RERUN command. For example:

DBG> RERUN %DEBUG-I-NOTATMAIN, Language: C, Module: ECHOARGS %DEBUG-I-NOTATMAIN, Type GO to reach main program DBG>

The RERUN command terminates the image you were debugging and brings a fresh copy of that image under debugger control, pausing at the start of the main source module as if you had used the RUN command (see Section 1.3.1).

When you use the RERUN command you can save the current state (activated or deactivated) of any breakpoints, tracepoints, and static watchpoints. Note that the state of a particular nonstatic watchpoint might not be saved, depending on the scope of the variable being watched relative to the main program unit (where execution restarts). RERUN/SAVE is the default. To clear all breakpoints tracepoints, and watchpoints, enter RERUN/NOSAVE.

The RERUN command invokes the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command. To rerun a program with new arguments, use the /ARGUMENTS qualifier (see RUN and RERUN Command Options for Programs That Require Arguments).

1.3.4 Running Another Program from the Kept Debugger

You can bring another program under debugger control at any time during a debugging session, provided you invoked the kept debugger as explained in Section 1.3.1. Use the debugger RUN command. For example:

DBG> RUN TOTALS %DEBUG-I-NOTATMAIN, Language: FORTRAN, Module: TOTALS DBG>

The debugger loads the program and pauses execution at the start of the main source module.

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

For information about all RUN command options, see the debugger RUN command description.

1.4 Interrupting Program Execution and Aborting Debugger Commands

If your program goes into an infinite loop during a debugging session so that the debugger prompt does not reappear, press Ctrl/C. This interrupts program execution and returns you to the debugger prompt (pressing Ctrl/C does not end the debugging session). For example:

DBG> GO . . . [Ctrl/C] DBG>

You can also press Ctrl/C to abort the execution of a debugger command. This is useful if, for example, the debugger is displaying a long stream of data.

Pressing Ctrl/C when the program is not running or when the debugger is not performing an operation has no effect.

If your program has a Ctrl/C AST (asynchronous system trap) service routine enabled, use the SET ABORT_KEY command to assign the debugger's abort function to another Ctrl/key sequence. To identify the abort key that is currently defined, enter the SHOW ABORT_KEY command.

Pressing Ctrl/Y from within a debugging session has the same effect as pressing Ctrl/Y during the execution of a program. Control is returned to the DCL command interpreter ($ prompt).

1.5 Pausing and Resuming a Debugging Session

The debugger SPAWN and ATTACH commands enable you to interrupt a debugging session from the debugger prompt, enter DCL commands, and return to the debugger prompt. These commands function essentially like the DCL commands SPAWN and ATTACH:

• Use the debugger SPAWN command to create a subprocess.
• Use the debugger ATTACH command to attach to an existing process or subprocess.

You can enter the SPAWN command with or without specifying a DCL command as a parameter. If you specify a DCL command, it is executed in a subprocess (if the DCL command invokes a utility, that utility is invoked in a subprocess). Control returns to the debugging session when the DCL command terminates (or when you exit the utility). The following example shows spawning the DCL command DIRECTORY:

DBG> SPAWN DIR [JONES.PROJECT2]*.FOR . . . Control returned to process JONES_1 DBG>

The next example shows spawning the DCL command MAIL, which invokes the Mail utility:

DBG> SPAWN MAIL MAIL> READ/NEW . . . MAIL> EXIT Control returned to process JONES_1 DBG>

If you enter the SPAWN command without specifying a parameter, a subprocess is created, and you can then enter DCL commands. Either logging out of the subprocess or attaching to the parent process (with the DCL command ATTACH) returns you to the debugging session. For example:

DBG> SPAWN $ RUN PROG2 . . . $ ATTACH JONES_1 Control returned to process JONES_1 DBG>

If you plan to go back and forth several times between your debugging session and a spawned subprocess (which might be another debugging session), use the debugger ATTACH command to attach to that subprocess. Use the DCL command ATTACH to return to the parent process. Because you do not create a new subprocess every time you leave the debugger, you use system resources more efficiently.

If you are running two debugging sessions simultaneously, you can define a new debugger prompt for one of the sessions with the SET PROMPT command. This helps you differentiate the sessions.