![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
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.
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.
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 13.1 describes some of the effects of optimization.
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.
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 Available¹ |
|---|---|---|---|
| /DEBUG | RUN/NODEBUG | RUN | Full |
|
None or
/TRACEBACK or /NODEBUG² |
RUN | RUN/DEBUG | Only traceback³ |
| /NOTRACEBACK | RUN | RUN/DEBUG 4 | None |
| /DSF 5 | RUN | DEBUG/KEEP 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.
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.
Notes
The following problems or restrictions are specific to the kept debugger:
- If a previous debugger process has not completely stopped, you may see the following error at debugger startup:
%DEBUG-E-INTERR, internal debugger error in DBGMRPC\DBG$WAIT_FOR_EVENT got an ACK
To fix this problem, exit the debugger. Then use the DCL command SHOW PROCESS/SUBPROCESS to check whether any debugger subprocesses exist. If so, stop them by using the DCL command STOP and then restart the debugger.- Running a sequence of many large programs can cause the debugger to fail because it has run out of memory, global sections, or some other resource.
To fix this problem, exit the debugger and restart the debugging session.
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 13.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'
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:
When your program completes execution normally during a debugging session, the debugger issues the following message:
'Normal successful completion'
You then have the following options:
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 Language: C, Module: FORMS 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).
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 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.
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).
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:
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.
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:
For example:
$ RUN FORMS
Debugger Banner and Version Number
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.
You can bring a program that is executing freely under debugger control. This is useful 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:
For example:
$ RUN/NODEBUG FORMS
.
.
.
[Ctrl/Y]
Interrupt
$ DEBUG
Debugger Banner and Version Number
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 was interrupted, and prompts for commands.
Usually you will not know where execution was 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.
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 $
4538P001.HTM OSSG Documentation 22-NOV-1996 13:01:30.40
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.