[Digital logo]
[HR]

OpenVMS Debugger Manual

Previous | Contents

Once started, program execution continues until one of the following events occurs:

Whenever the debugger suspends execution of the program, the main window display is updated and the current-location pointer marks which line of code will execute next.

10.3.3 Executing Your Program One Source Line at a Time

To execute one source line of your program, click on the STEP button in the push button view or enter the STEP command in the command view. This debugging technique (called stepping) is one of the most commonly used.

After the line executes, the source view is updated and the current-location pointer marks which line of code will execute next.

Note the following points about source lines and the stepping behavior:

Keep in mind that if you optimized your code at compilation time, the source code displayed might not reflect the code that is actually executing (see Section 1.2).

10.3.4 Stepping into a Called Routine

When program execution is paused at a routine call statement, clicking on the STEP button typically executes the called routine in one step (depending on the coding style used), and the debugger suspends execution at the next source line in the calling routine (assuming no breakpoint was set within the called routine). This enables you to step through the code quickly without having to trace execution through any called routines (some of which might be system or library routines). This is called stepping over called routines.

To step into a called routine so that you can execute it one line at a time:

  1. Suspend execution at the routine call statement, for example, by setting a breakpoint (see Section 10.4) and then clicking on the Go button in the push button view.
  2. When execution is paused at the call statement, click on the S/in button in the push button view, or enter the STEP/INTO command at the DBG> prompt. This moves execution just past the start of the called routine.

Once execution is within the called routine, click on the STEP button to execute the routine line by line.

Clicking on the S/in button when execution is not paused at a routine call statement is the same as clicking on the STEP button.

10.3.5 Returning from a Called Routine

When execution is suspended within a called routine, you can execute your program directly to the end of that routine by clicking on the S/ret button in the push button view, or enter the STEP/RETURN command at the DBG> prompt.

The debugger suspends execution just before the routine's return instruction executes. At that point, the routine's call frame has not been deleted from the call stack, so you can still get the values of variables local to that routine, and so on.

You can also use the S/call button in the push button view (or enter the STEP/CALL command at the DBG> prompt) to execute the program directly to the next Return or Call instruction.

The S/ret button is particularly useful if you have inadvertently stepped into a system or library routine (see Section 10.1.3).

10.4 Suspending Execution by Setting Breakpoints

A breakpoint is a location in your program at which you want execution to stop so that you can check the current value of a variable, step into a routine, and so on.

When using the debugger's DECwindows Motif interface, you can set breakpoints on:

Note

If you are stopped at a breakpoint in a routine that has control of the mouse pointer by a PointerGrab or a KeyboardGrab, your workstation will hang.

To work around this problem, debug your program using two workstations. For more information, see Section 9.7.3.1.

The debugger provides two ways to qualify breakpoints:

You can set a breakpoint that is both a conditional and action breakpoint.

The following sections explain these breakpoint options.

10.4.1 Setting Breakpoints on Source Lines

You can set a breakpoint on any source line that has a button to its left in the source display. These are the lines for which the compiler has generated executable code (routine declarations, assignment statements, and so on).

To set a breakpoint on a source line:

  1. Find the source line on which you want to set a breakpoint (see Section 10.1).
  2. Click on the button to the left of that line. (The breakpoint is set when the button is filled in.) The breakpoint is set at the start of the source line---that is, on the first machine-code instruction associated with that line.

Figure 10-4 shows that a breakpoint has been set on the start of line 37.

Figure 10-4 Setting a Breakpoint on a Source Line

10.4.2 Setting Breakpoints on Routines with Source Browser

Setting a breakpoint on a routine enables you to move execution directly to the routine and inspect the local environment.

To set a breakpoint on a routine:

  1. Choose Browse Sources... from the File menu on the main window (see Figure 10-2). The Source Browser dialog box displays the name of your executable image, which is highlighted, and all the shareable images linked with it (for example, DEBUG and LIBRTL). The name of a linked image is dimmed if no symbolic information is available for that image.
  2. Double click on the name of the executable image. The names of the modules in that image are displayed (indented) under the image name.
  3. Double click on the name of the target module. The names of the routines in that module are displayed (indented) under the module name (see Figure 10-5).
  4. Double click on the name of the routine on which to set a breakpoint. The debugger echoes the results of your SET BREAKPOINT command on the command line in the command view.
    Alternatively, click once on the name of the routine, then click the Set Breakpoint button in the Source Browser view. The debugger echoes the results of your SET BREAKPOINT command on the command line in the command view.

Figure 10-5 Setting a Breakpoint on a Routine

10.4.3 Setting an Exception Breakpoint

An exception breakpoint suspends execution when an exception is signaled and before any exception handler declared by your program executes. This enables you to step into the exception handler (if one is available) to check the flow of control.

To set an exception breakpoint, choose On Exception from the Break menu on the main window or the optional views window. The exception breakpoint triggers whenever any exception is signaled.

10.4.4 Identifying the Currently Set Breakpoints

There are three ways to determine which breakpoints are currently set:

10.4.5 Deactivating, Activating, and Canceling Breakpoints

After a breakpoint is set, you can deactivate, activate, or delete it.

Deactivating a breakpoint causes the debugger to ignore the breakpoint during program execution. However, the debugger keeps the breakpoint listed in the breakpoint view so that you can activate it at a later time, for example, when you rerun the program (see Section 9.3). Note the following points:

Activating a breakpoint causes it to take effect during program execution:

When you cancel a breakpoint, it is no longer listed in the breakpoint view so that later you cannot activate it from that list. You have to reset the breakpoint as explained in Section 10.4.1 and Section 10.4.2. Note the following points:

10.4.6 Setting a Conditional Breakpoint

A conditional breakpoint suspends execution only when a specified expression is evaluated as true. For example, you can specify that a breakpoint take effect when the value of a variable in your program is 4. The breakpoint is ignored if the value is other than 4.

The debugger evaluates the conditional expression when the breakpoint triggers during execution of your program.

The following procedure sets a conditional breakpoint, whether or not a breakpoint was previously set at that location:

  1. Display the source line on which you want to set the conditional breakpoint (see Section 10.1).
  2. Do one of the following:
  3. Enter a relational expression in the Condition: field of the dialog box. The expression must be valid in the source language. For example, a[3] :=,= 0 is a valid relational expression in the C language.
  4. Click on OK. The conditional breakpoint is now set. The debugger indicates that a breakpoint is conditional by changing the shape of the breakpoint's button from a square to a diamond.

    Figure 10-6 Setting a Conditional Breakpoint

    The following procedure modifies a conditional breakpoint; that is, it can be used to change the location or condition associated with an existing conditional breakpoint, or to change an unqualified breakpoint into a conditional breakpoint:

    1. Choose Views... from the Options menu on the main window or optional views window. When the Views dialog box appears, click on Breakpoint View to display the breakpoint view.
    2. From the breakpoint view, do one of the following:
      • Press Ctrl/MB1 on the button to the left of the listed breakpoint.
      • Click on a breakpoint listed in the view, and choose the Set/Modify item from the Break menu.
    3. Follow steps 3 and 4 of the previous procedure, as appropriate.

      10.4.7 Setting an Action Breakpoint

      When an action breakpoint triggers, the debugger suspends execution and then executes a specified list of commands.

      To set an action breakpoint, whether or not a breakpoint was previously set at that location:

      1. Display the source line on which you want to set the action breakpoint (see Section 10.1).
      2. Do one of the following:
        • Press Ctrl/MB1 on the button to the left of the source line. This displays the Set/Modify Breakpoint dialog box, showing the source line you selected in the Location: field (see Figure 10-6).
        • Choose the Set or Set/Modify item from the Break menu. When the Set/Modify Breakpoint dialog box displays, enter the source line in the Location: field.
      3. Enter one or more debugger commands in the Action: field of the dialog box. For example: DEPOSIT x[j] = 3; STEP; EXAMINE a
      4. Click on OK. The action breakpoint is now set (see Figure 10-7.)

        Figure 10-7 Setting an Action Breakpoint

        The following procedure modifies an action breakpoint; that is, it can be used to change the location or command associated with an existing action breakpoint, or to change an unqualified breakpoint into an action breakpoint:

        1. Choose Views... from the Options menu on the main window or optional views window, then click on Breakpoint View when the Views dialog box appears.
        2. From the breakpoint view, do one of the following:
          • Press Ctrl/MB1 on the button to the left of the listed breakpoint.
          • Click on a breakpoint listed in the view, and choose the Set/Modify item in the Break menu.
        3. Follow steps 3 and 4 of the previous procedure, as appropriate.

          10.5 Examining and Manipulating Variables

          This section explains how to:

          • Select variable names from windows
          • Display the value of a variable
          • Monitor a variable
          • Watch a variable
          • Change the value of a variable

          See Section 10.6, which also applies to all operations on variables.

          10.5.1 Selecting Variable Names from Windows

          Use the following techniques to select variable names from windows for the operations described in the sections that follow (see Section 10.5.2 for examples).

          When selecting names, follow the syntax of the source programming language:

          • To specify a scalar (nonaggregate) variable, such as an integer, real, Boolean, or enumeration type, select the variable's name.
          • To specify an entire aggregate, such as array or structure (record), select the variable's name.
          • To specify a single element of an aggregate variable, select the entity using the language syntax. For example:
            • The string arr2[7] specifies element 7 of array arr2 in the C language.
            • The string employee.address specifies component address of record (structure) employee in the Pascal language.
          • To specify the object designated by a pointer variable, select the entity following the language syntax. For example, in the C language, the string *int_point specifies the object designated by pointer int_point.

          Select character strings from windows as follows:

          • In any window, to select a string delimited by blank spaces, use the standard DECwindows Motif word selection technique: position the pointer on that string and then double click MB1.
          • In any window, to select an arbitrary character string, use the standard DECwindows Motif text-selection technique: position the pointer on the first character, press and hold MB1 while dragging the pointer over the string and then release MB1.
          • In the debugger source display, you also have the option of using language-sensitive text selection. To select a string delimited by language-dependent identifier boundaries, position the pointer on that string and press
            Ctrl/MB1.
            For example, suppose the source display contains the character string arr2[m], then:
            • To select arr2, position the pointer on arr2 and press Ctrl/MB1.
            • To select m, position the pointer on m and press Ctrl/MB1.

            You can change the key sequence for language-sensitive text selection as explained in Section 10.10.4.2.

          10.5.2 Displaying the Current Value of a Variable

          To display the current value of a variable:

          1. Find and select the variable name in a window as explained in Section 10.5.1.
          2. Click on the EX button in the push button view. The debugger displays the variable and its current value in the command view. The debugger displays the value of a variable in the current scope, which might not be the same as the source location you were intending.

          Figure 10-8, Figure 10-9, and Figure 10-10 show how to display the value of an integer variable, array aggregate, and array element, respectively.

          Figure 10-8 Displaying the Value of an Integer Variable

          Figure 10-9 Displaying the Value of an Array Aggregate

          Figure 10-10 Displaying the Value of an Array Element

          To display the current value in a different type or radix, use the following alternative method:

          1. Find and select the variable name in a window as explained in Section 10.5.1.
          2. Choose Examine... in the Commands menu in the main window. The Examine dialog box appears with the name selected in the Variable/Expression field.
          3. Choose the default, int, long, quad, short, or char* item from the Typecast menu within the dialog box.
          4. Choose the default, hex, octal, decimal, or binary item from the Output Radix menu within the dialog box.
          5. Click on OK.

          The value, altered to your specification, appears in the command view.

          Figure 10-11 shows that the variable j has been typecast as long.

          Figure 10-11 Typecasting the Value of a Variable

          10.5.3 Changing the Current Value of a Variable

          To change the current value of a variable:

          • Find and select the variable name in a window as explained in Section 10.5.1.
          • Choose Deposit... from the Commands menu in the main window. The Deposit dialog box appears with the name selected in the Variable field.
          • Enter the new value in the Value field.
          • Choose the default, hex, octal, decimal, or binary item from the Input Radix menu within the dialog box.
          • Click on OK.

          The new value, altered to your specification, appears in the command view and is assigned to the variable.

          Figure 10-12 shows a new value for the variable safe.

          Figure 10-12 Changing the Value of a Variable

          10.5.4 Monitoring a Variable

          When you monitor a variable, the debugger displays the value in the monitor view and checks and updates the displayed value whenever the debugger regains control from your program (for example, after a step or at a breakpoint).

          Note

          You can monitor only a variable, including an aggregate such as an array or structure (record). You cannot monitor a composite expression or memory address.

          To monitor a variable (see Figure 10-13):

          1. Find and select the variable name in a window as explained in Section 10.5.1.
          2. Click on the MON button in the push button view. The debugger:
            • Displays the monitor view (if it is not displayed)
            • Puts the selected variable's name, along with its qualifying path name, in the Monitor Expression column
            • Puts the value of the variable in the Value/Deposit column
            • Puts a cleared button in the Watched column (see Section 10.5.5).

            You can typecast the output value when monitoring variables by choosing the Typecast item in the Monitor menu.

            You can change the output radix when monitoring variables as follows:

            • Choose Change Radix in the Monitor menu to change the output radix for a selected monitored element.
            • Choose the Change All Radix in the Monitor menu to change the output radix for all subsquently monitored elements.

            To remove a monitored element from the monitor view, choose Remove from the Monitor menu.

            Figure 10-13 Monitoring a Variable

            10.5.4.1 Monitoring an Aggregate (Array or Structure) Variable

            If you select the name of an aggregate variable, such as an array or structure (record) and click on the MON button, the debugger displays the word Aggregate in the Value/Deposit column of the monitor view. To display the values of all elements (components) of an aggregate variable, double click on the variable name in the Monitor Expression column (or choose Expand in the Monitor menu). The displayed element names are indented relative to the parent name (see Figure 10-14). If an element is also an aggregate, you can double click on its name to display its elements, and so on.

            Figure 10-14 Expanded Aggregate Variable (Array) in Monitor View

            To collapse an expanded display so that only the aggregate parent name is shown in the monitor view, double click on the name in the Monitor Expression column (or choose Collapse from the Monitor menu).

            If you have selected a component of an aggregate variable, and the component expression is itself a variable, the debugger monitors the component that was active when you made the selection. For example, if you select the array component arr[i] and the current value of i is 9, the debugger monitors arr[9] even if the value of i subsequently changes to 10.

            10.5.4.2 Monitoring a Pointer (Access) Variable

            If you select the name of a pointer (access) variable and click on the MON button, the debugger displays the address of the referenced object in the
            Value/Deposit column of the monitor view (see the top entry in Figure 10-15).

            To monitor the value of the referenced object (to dereference the pointer variable), double click on the pointer name in the Monitor Expression column. This adds an entry for the referenced object in the monitor view, indented under the pointer entry (see the bottom entry in Figure 10-15). If a referenced object is an aggregate, you can double click on its name to display its elements, and so on.

            Figure 10-15 Pointer Variable and Referenced Object in Monitor View

            10.5.5 Watching a Variable

            Whenever the program changes the value of a watched variable, the debugger suspends execution and displays the old and new values in the command view.

            To watch a variable (also known as setting a watchpoint on a variable):

            • Monitor the variable as explained in Section 10.5.4. The debugger puts a button in the Watched column of the monitor view whenever you monitor a variable. See Figure 10-16.
            • Click on the button in the Watched column. A filled-in button indicates that the watchpoint is set.

            Figure 10-16 Watched Variable in Monitor View

            To deactivate a watchpoint, clear its Watched button in the monitor view (by clicking on the button) or choose Toggle Watchpoint in the Monitor menu. To activate a watchpoint, fill in its Watched button or choose Toggle Watchpoint in the Monitor menu.

            Section 10.6.1 explains static and nonstatic (automatic) variables and how to access them. The debugger deactivates a nonstatic watchpoint when execution moves out of (returns from) the variable's defining routine. When a nonstatic variable is no longer active, its entry is dimmed in the monitor view and its Watched button is cleared.

            The debugger does not automatically reactivate nonstatic watchpoints if execution later returns to the variable's defining routine. You must reactivate nonstatic watchpoints explicitly.

            10.5.6 Changing the Value of a Monitored Scalar Variable

            To change the value of a scalar (nonaggregate) variable, such as an integer or Boolean type (see Figure 10-17):

            1. Monitor the variable as explained in Section 10.5.4.
            2. Click on the variable's value in the Value/Deposit column of the monitor view. A small dialog box is displayed over that value, which you can now edit.
            3. Enter the new value in the dialog box.
            4. Click on the check mark (OK) in the dialog box. The dialog box is removed and replaced by the new value, indicating that the variable now has that value. The debugger notifies you if you try to enter a value that is incompatible with the variable's type, range, and so on.

            Figure 10-17 Changing the Value of a Monitored Scalar Variable

            Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]

            [HR] 

              4538P016.HTM
  OSSG Documentation
  22-NOV-1996 13:01:54.50

            Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

            Legal