Document revision date: 19 July 1999

This chapter explains how to:

• Start the debugger ( Section 9.1)
• Continue when your program completes execution ( Section 9.2)
• Rerun the same program from the current debugging session ( Section 9.3)
• Run another program from the current debugging session ( Section 9.4)
• Interrupt program execution and debugger operations ( Section 9.5)
• End a debugging session ( Section 9.6)
• Start the debugger in additional ways for specific purposes ( Section 9.7)

This section explains the most common way to start the debugger from DCL level ($) and bring your program under debugger control. Section 9.7 explains optional ways to start the debugger.

Starting the kept debugger as explained here enables you to use the Rerun (see Section 9.3) and Run (see Section 9.4) features.

To start the 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

   
   By default, the debugger starts up as shown in Figure 9-1. The main window remains empty until you bring a program under debugger control (Step 4). Upon startup, the debugger executes any user-defined initialization file (see Section 13.2).

   Figure 9-1 Debugger at Startup

   ---

   
4. Bring your program under debugger control using one of the following two techniques:
   • Run a specified image (this is the most common technique):
     1. Choose Run Image... from the File menu on the main window. The Run Image dialog lists the executable images in your current directory (see Figure 9-2).
     2. Click on the name of the image to be debugged. The Image: field displays the image name.
     3. If applicable, enter arguments to be passed to the program in the Arguments: field. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotation marks when parsing the string.
     4. Click on OK.

     Figure 9-2 Running a Program by Specifying an Image

     ---

     
   • Run an image by specifying a DCL command or a symbol for a foreign command:
     1. Choose Run Foreign Command... from the File menu on the main window. The Run Foreign Command dialog is displayed (see Figure 9-3).
     2. Enter the symbol in the Foreign Command: field (such a symbol can provide a shortcut around the directory and file selection process). The foreign command X1, shown in Figure 9-3, has been previously defined:

        $X1 :== RUN MYDISK:[MYDIR.MYSUBDIR]EIGHTQUEENS.EXE

     3. Enter any arguments to be passed with the command in the Arguments: field.
     4. Click on OK.

Figure 9-3 Running a Program by Specifying a Command Symbol

Once the debugger has control of the program, the debugger:

• Displays the program's source code in the main window, as shown in Figure 9-4.
• Suspends execution at the start of the main program. The current-location pointer to the left of the source code shows which line of code will be executed next.

Figure 9-4 Source Display at Startup

The message displayed in the command view indicates that this debugging session is initialized for a C program and that the name of the source module is EIGHTQUEENS.

With certain programs, the debugger sets a temporary breakpoint to suspend program execution at the start of some initialization code, before the main program, and displays the following message:

Type GO to reach MAIN program No source line for address: nnnnnnnn

With some of these programs (for example, Ada programs), the breakpoint enables you to debug the initialization code using full symbolic information. 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.

You can now debug your program as explained in Chapter 10.

Note the following restrictions about running a program under debugger control:

• You cannot use the procedure in this section to connect the debugger to a running program (see Section 9.7.2).
• 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.

If you try to run a program that does not exist, or misspell the name of a program that does exist, the following error messages are displayed in the DECterm window, rather than in the command view:

%DCL-W-ACTIMAGE, error activating image -CLI-E-IMAGEFNF, image file not found

To avoid this problem, make sure the Select an application to run field in the File Selection popup contains a valid file specification.

9.2 When Your Program Completes Execution

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 your program from the same debugging session (see Section 9.3).
• You can run another program from the same debugging session (see Section 9.4).
• You can end the debugging session (see Section 9.6).

When running the kept debugger (see Section 9.1), you can rerun the program currently under debugger control at any time during a debugging session.

To rerun the program:

1. Choose Rerun Same... from the File menu on the main window. The Rerun dialog is displayed (see Figure 9-5).
2. Enter any arguments to be passed to the program, if required, in the Arguments: field. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotation marks when parsing the string.
3. Choose whether or not to keep the current state of any breakpoints, tracepoints, or static watchpoints that you previously set, activated, or deactivated (see Section 10.4 and Section 10.5.5). Nonstatic watchpoints might or might not be saved, depending on the scope of the variable being watched relative to the main program unit (where execution restarts).
4. Click on OK.

Figure 9-5 Rerunning the Same Program

When you rerun a program, it is in the same initial state as a program that is brought under debugger control as explained in Section 9.1, except for any saved breakpoints, tracepoints, or static watchpoints. The source display and current location pointer are updated accordingly.

When you rerun a program, the debugger uses 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, choose Run Image... or Run Foreign Command.. from the File menu on the main window (see Section 9.1).

9.4 Running Another Program from the Current Debugging Session

You can bring another program under debugger control at any time during a debugging session, if you started the debugger as explained in Section 9.1. Follow the procedure in that section for bringing a program under debugger control (also note the restrictions about using that procedure).

9.5 Interrupting Program Execution and Aborting Debugger Operations

To interrupt program execution during a debugging session, click on the Stop button on the push button view (see Figure 8-3). This is useful if, for example, the program is in an infinite loop.

To abort a debugger operation in progress, click on Stop. This is useful if, for example, the debugger is displaying a long stream of data.

Clicking on Stop does not end the debugging session. Clicking on Stop has no effect when the program is not running or when the debugger is not executing a command.

9.6 Ending a Debugging Session

To end a debugging session and terminate the debugger, choose Exit Debugger from the File menu on the main window, or enter EXIT at the prompt (to avoid confirmation dialogue). This returns control to system level.

To rerun your program from the current debugging session, see Section 9.3.

To run another program from the current debugging session, see Section 9.4.

9.7 Additional Options for Starting the Debugger

In addition to the startup procedure described in Section 9.1, the following options are available for starting the debugger from DCL level ($):

• Start the debugger by running the program to be debugged with the DCL command RUN (see Section 9.7.1).
• Interrupt a running program by pressing Ctrl/Y and then start the debugger using the DCL command DEBUG (see Section 9.7.2).
• Establish a default or multiprocess debugging configuration to debug a program that runs in either one or several processes, respectively (see Chapter 17).
• Override the debugger's default (DECwindows Motif) interface (see Section 9.7.3) to achieve the following:
  • Display the DECwindows Motif interface on another workstation
  • Display the command interface in a DECterm window along with any program input/output (I/O)
  • Display the command interface and program I/O in separate DECterm windows

In all cases, before starting the debugger, verify that you have compiled and linked the modules of your program (as explained in Section 1.2) and established the proper debugging configuration (as explained in Section 1.9).

9.7.1 Starting the Debugger by Running a Program

You can start the debugger and also bring your program under debugger control in one step by entering the DCL command RUN filespec (assuming the program was compiled and linked with the /DEBUG qualifier).

However, you cannot then use the Rerun or Run features explained in Section 9.3 and Section 9.4, respectively. To rerun the same program or run a new program under debugger control, you must first exit the debugger and start it again.

To start the debugger by running a program, enter the DCL command RUN filespec to start the debugger. For example:

$ RUN EIGHTQUEENS

By default, the debugger starts up as shown in Figure 9-4, executing any user-defined initialization file and displaying the program's source code in the main window. The current-location pointer shows that execution is paused at the start of the main program. The debugger sets the language-dependent parameters to the source language of the main program unit.

For more information about debugger startup, see Section 9.1.

9.7.2 Starting the Debugger After Interrupting a Running Program

To bring your program under debugger control:

1. Enter the DCL command RUN/NODEBUG filespec to execute the program without debugger control.
2. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL command interpreter.
3. Enter the DCL command DEBUG to start the debugger.

For example:

$ RUN/NODEBUG EIGHTQUEENS . . . [Ctrl/Y] Interrupt $ DEBUG [starts debugger]

At startup, the debugger displays the main window and executes any user-defined initialization file, and sets the language-dependent parameters to the source language of the module in which execution was interrupted.

To help you determine where execution was interrupted:

1. Look at the main window.
2. Enter the SET MODULES/CALLS command at the command-entry prompt.
3. Display the Call Stack menu on that window to identify the sequence of routine calls on the call stack. The routine at level 0 is the routine in which execution is currently paused (see Section 10.3.1).

When you start the debugger in this manner, you cannot then use the Rerun or Run features explained in Section 9.3 and Section 9.4, respectively. To rerun the same program or run a new program under debugger control, you must first exit the debugger and start it again.

For more information about debugger startup, see Section 9.1.

9.7.3 Overriding the Debugger's Default Interface

By default, if your workstation is running DECwindows Motif, the debugger starts up in the DECwindows Motif interface, which is displayed on the workstation specified by the DECwindows Motif applicationwide logical name DECW$DISPLAY.

This section explains how to override the debugger's default DECwindows Motif interface to achieve the following:

• Display the debugger's DECwindows Motif interface on another workstation
• Display the debugger's command interface in a DECterm window along with any program I/O
• Display the debugger's command interface and program I/O in separate DECterm windows

The logical name DBG$DECW$DISPLAY enables you to override the default interface of the debugger. In most cases, there is no need to define DBG$DECW$DISPLAY because the default is appropriate.

Section 9.7.3.4 provides more information about the logical names DBG$DECW$DISPLAY and DECW$DISPLAY.

9.7.3.1 Displaying the Debugger's DECwindows Motif Interface on Another Workstation

If you are debugging a DECwindows Motif application that uses most of the screen (or if you are debugging pop-ups in a Motif application), you might find it useful to run the program on one workstation and display the debugger's DECwindows Motif interface on another. To do so:

1. Enter a logical definition with the following syntax in the DECterm window from which you plan to run the program:

   DEFINE/JOB DBG$DECW$DISPLAY workstation_pathname

   
   The path name for the workstation where the debugger's DECwindows Motif interface is to be displayed is workstation_pathname. See the description of the SET DISPLAY command in the OpenVMS DCL Dictionary for the syntax of this path name.
   It is recommended that you use a job definition. If you use a process definition, it must not have the CONFINE attribute.

2. Run the program from that DECterm window. The debugger's DECwindows Motif interface is now displayed on the workstation specified by DBG$DECW$DISPLAY. The application's windowing interface is displayed on the workstation where it is normally displayed.
3. Use client/server mode (see Section 9.8.2).

To display the debugger's command interface in a DECterm window, along with any program I/O:

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 spaces between the quotation marks. It is recommended that you 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 from that DECterm window (see Section 9.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 9.1.

9.7.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm Windows

• The program's input/output (I/O) is displayed in the window from which you start the debugger.
• The debugger's I/O, including any screen-mode display, is displayed in the separate window.

The effect is the same as entering the SET MODE SEPARATE command at the DBG> prompt on a workstation running VWS rather than DECwindows Motif. (The SET MODE SEPARATE command is not valid when used in a DECterm window.)

The following example shows how to display the debugger's command interface in a separate debugger window titled Debugger.

1. Create the command procedure SEPARATE_WINDOW.COM shown in Example 9-1.

   Example 9-1 Command Procedure SEPARATE_WINDOW.COM

   $ ! Simulates effect of SET MODE SEPARATE from a DECterm window $ ! $ CREATE/TERMINAL/NOPROCESS - /WINDOW_ATTRIBUTES=(TITLE="Debugger",- ICON_NAME="Debugger",ROWS=40)- /DEFINE_LOGICAL=(TABLE=LNM$JOB,DBG$INPUT,DBG$OUTPUT) $ ALLOCATE DBG$OUTPUT $ EXIT $ ! $ ! The command CREATE/TERMINAL/NOPROCESS creates a DECterm $ ! window without a process. $ ! $ ! The /WINDOW_ATTRIBUTES qualifier specifies the window's $ ! title (Debugger), icon name (Debugger), and the number $ ! of rows in the window (40). $ ! $ ! The /DEFINE_LOGICAL qualifier assigns the logical names $ ! DBG$INPUT and DBG$OUTPUT to the window, so that it becomes $ ! the debugger input and output device. $ ! $ ! The command ALLOCATE DBG$OUTPUT causes the separate window $ ! to remain open when you end the debugging session.

2. Execute the command procedure as follows:

   $ @SEPARATE_WINDOW %DCL-I-ALLOC, _MYNODE$TWA8: allocated

   
   A new DECterm window is created with the attributes specified in SEPARATE_WINDOW.COM.

3. Follow the steps in Section 9.7.3.2 to display the debugger's command interface. The interface is displayed in the new window.
4. You can now enter debugger commands in the debugger window. Program I/O is displayed in the DECterm window from which you started the debugger.
5. When you end the debugging session with the EXIT command, control returns to the DCL prompt in the program I/O window but the debugger window remains open.
6. To display the debugger's command interface in the same window as the program's I/O (as in Section 9.7.3.2), enter the following commands:

   $ DEASSIGN/JOB DBG$INPUT $ DEASSIGN/JOB DBG$OUTPUT

   
   The debugger window remains open until you close it explicitly.

By default, if your workstation is running DECwindows Motif, the debugger starts up in the DECwindows Motif interface, which is displayed on the workstation specified by the DECwindows Motif applicationwide logical name DECW$DISPLAY. DECW$DISPLAY is defined in the job table by FileView or DECterm and points to the display device for the workstation.

For information about DECW$DISPLAY, see the description of the DCL commands SET DISPLAY and SHOW DISPLAY in the OpenVMS DCL Dictionary.

The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent of DECW$DISPLAY. DBG$DECW$DISPLAY is similar to the debugger-specific logical names DBG$INPUT and DBG$OUTPUT. These logical names enable you to reassign SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on which debugger input and output are to appear.

The default user interface of the debugger results when DBG$DECW$DISPLAY is undefined or has the same translation as DECW$DISPLAY. By default, DBG$DECW$DISPLAY is undefined.

The algorithm that the debugger follows when using the logical definitions of DECW$DISPLAY and DBG$DECW$DISPLAY is as follows:

1. If the logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise, use the logical name DECW$DISPLAY.
2. Translate the logical name. If its value is not null (if the string contains characters other than spaces), the DECwindows Motif interface is displayed on the specified workstation. If the value is null (if the string consists only of spaces), the command interface is displayed in the DECterm window.

To enable the OpenVMS Debugger to start up in the DECwindows Motif interface, first enter one of the following DCL commands:

$DEFINE DBG$DECW$DISPLAY "WSNAME::0" $SET DISPLAY/CREATE/NODE=WSNAME

where WSNAME is the nodename of your workstation.

	privacy and legal statement
4538PRO_019.HTML