Data browsers are often created automatically when a breakpoint is reached in a debuggable program, or can created explicitly with the Show->Data Browser menu item; see Section 6.7.6.

A browser can display individual variable values, whole dynamic objects, stacks, and individual stack frames. A data browser also can also set watch conditions that are evaluated periodically during execution and can cause your program to break when the condition is met; see Section 4.3.

The data browser window contains a display area in which it displays the current object; initially, only one object at a time is visible in a data browser. However, you can create multiple panes within the same data browser window, each pane showing a different object. You can also create multiple data browsers; a new one is created each time you choose Show->Data browser.

The browser's display area can be scrolled horizontally and vertically so that you can view large objects. The display area also gets larger when you increase the size of the data browser window, so that you can see more of a large object at once.

Each displayed object is assigned a number and a title, such as “Record of class C”. All displayed objects are remembered (unless deleted) and can be redisplayed in various ways. Displayed objects are updated whenever they are redisplayed (including each time the debugger gets control).

A “POINTER button” is drawn beside each non-Zero POINTER that is a component of a displayed object, e.g., a POINTER record field. You can click on a POINTER button to display the entity pointed to; the newly displayed object becomes the currently displayed object. This allows you to traverse a data structure quickly. A POINTER button is also displayed beside each non-Zero ADDRESS or CHARADR value; clicking on the button displays raw memory starting at the specified location.

Clicking on a POINTER button next to a PROCEDURE name in the stack object sets the debugger's command context to that invocation of the PROCEDURE.

In the object that is the list of watched expressions, an additional button (the “watch button”) appears beside each expression (farther to the left than the POINTER button, if the watched expression is a POINTER). By clicking on the watch button for an expression, you bring up a dialog box where you can see the context where the expression is defined, set any break conditions associated with the expression, or remove the expression from the list of watched expressions.

4.1. Navigation Controls

• A goTo button next to a text field for entering the number of a previously displayed object which is to be redisplayed. If you click the goTo button, the object corresponding to that number is redisplayed (possibly updated if any values have changed). An error is reported if there is no object corresponding to the number, or if the text field does not contain a valid number.

• A Create Pane button can be used to split the browser's display area into multiple panes, each of which can display a separate object, so that you can see and compare two or more objects in the browser window simultaneously. One of the panes (whose text area is outlined in bold) is always the current pane; that pane is the one affected by navigation operations. You can change the current pane by clicking within the text area. The Delete Pane button deletes the current pane, resizing other panes to fill the window.

• Buttons for navigating through displayed objects:
  • first: Display the first object (more precisely, the lowest numbered undeleted object).

  • last: Display the last object (more precisely, the highest numbered undeleted object).

  • prev: Display the previous object (more precisely, the undeleted object with the next lower number).

  • next: Display the next object (more precisely, the undeleted object with the next higher number).

  • parent: Display the parent object (if the current object was displayed due to clicking a POINTER button, display the object that contains the button; an object's parent is updated each time it is shown due to a POINTER button being clicked).

  • stack: Display the stack frames for a specified coroutine. If there is just one coroutine, its stack is displayed; otherwise, a list of coroutine names is shown from which you click on the one whose stack you want to display.

    A stack display shows all PROCEDURE frames on the stack. Each frame is shown as moduleName.procedureName.offset, where offset is the MODULE displacement indicated by the return address. If the PROCEDURE is debuggable, its local variables are displayed, and a POINTER box is drawn beside it. Clicking on this box causes that PROCEDURE invocation to become the debugger's current PROCEDURE. Thus, you can scroll up and down a stack and instruct the debugger to make any debuggable frame the current context.

  • watchedExprs: Display the list of watched expressions (see Section 4.3).

  • delete: Delete the display of the currently displayed object. Automatically displays the previous object if there is one, else the next object if there is one, else an empty window.

If the Display Local Variables option of the Show->Options command is set and the current PROCEDURE is compiled debuggable, the local variables for the current PROCEDURE context are shown in a data browser window as object number zero (so it can be quickly found using the first button). When the values are first shown, a new data browser window is created if one does not already exist; otherwise, the most recently created data browser window is used. This data browser window is then used for subsequent local variable displays, with a new local variable display updating the old one.

If the Display Interface and Outer Variables option of the Show->Options command is set, the interface and outer variables for the current debugger MODULE context are shown in a data browser window selected as described above for Display Local Variables.

If both Display Local Variables and Display Interface and Outer Variables are set, the local variable and interface and outer variable displays are shown together in the same data browser window as if they are values of a single object. Both options are set by default.

4.2. Display Object or Display Memory

• dspy obj attempts to interpret the argument as the ADDRESS of a dynamic object; if successful, it displays that object's contents.

• dspy mem displays arbitrary memory as characters and hexadecimal bytes starting at the specified ADDRESS. The scrollbar associated with a pane displaying arbitrary memory can be used to move to any part of memory; the pane functions as a complete memory dump. Data from inaccessible memory locations are displayed with question marks.

When you define a watch expression, it must be legal in the current context (unless you use a bracketed watch expression specifier, as described below). You usually define a watch expression after having set and reached a breakpoint that puts you in the context in which the expression is meaningful.

4.3.1. Break Conditions for Watch Expressions

Watch expression break conditions can cause the debugger to break when the expression becomes non-Zero (or TRUE) or Zero (or FALSE). They can also cause a break when the expression's value changes. This is especially useful if a variable or memory location is being set to an incorrect value, but you do not know where the value was set.

4.3.2. Controlling the Data Section or Coroutine in Which an Expression Is Watched

You can have control over the data section and coroutine in which an expression is watched by prefixing the expression with a bracketed watch expression specifier of the form:

[{coroutineName:}moduleName{.procedureName}]

where the parts in curly braces are optional. procedureName is required if the expression contains local variables.

For example, to watch the variable i mentioned above in all data sections of MYMOD and in all coroutines, use:

[myMod.proc]i

To watch i in all data sections of MYMOD but only in the coroutine CO2, use:

[co2:myMod.proc]i

(There is currently no way to watch a local variable in a particular data section but in all coroutines.)

To watch an outer variable ov of MYMOD in all data sections for MYMOD, use:

[myMod]ov

• watch expr: Watch the expression specified in the show/watch text field. All watched expressions are displayed in the Watched exprs display. Each watched expression has a watch button next to it. Clicking on this pointer brings up the Watch Expr window (see below), which allows break conditions to be associated with each watched expression.

• watch obj: For POINTER-valued expressions, this displays the contents of a MAINSAIL dynamic object instead of just the value of the POINTER to it. The contents of each object are assigned a separate display number by the browser.

4.4.1. The Watch Expr Window

Break conditions can be evaluated at each statement, or at each PROCEDURE entry (the default). All break conditions are evaluated at the same time; i.e., it is not possible to define some break conditions that are evaluated only at PROCEDURE entries and others that are evaluated at statements.

The Watch Expr window contains the following displays and controls:

• Context, Expr: A description of the context in which the watched expression is declared (and hence can be evaluated), and the watched expression itself. These descriptions cannot be altered.

• Break if:
  • Zero (FALSE): Break as soon as the watch expression evaluates to the Zero of its data type.

  • NonZero (TRUE): Break as soon as the watch expression does not evaluate to the Zero of its data type.

  • Changes Value: Break as soon as the watch expression acquires a value different from its current value.

    Note: If a break condition associated with a watch expression is not explicitly removed after it is reached, the debugger may break again because of the same condition. In the case of a Zero or NonZero condition, the debugger breaks on each statement (if watch expression break conditions are being evaluated at the statement level) or PROCEDURE entry (if watch expression break conditions are being evaluated at the PROCEDURE level) until the expression again becomes non-Zero or Zero, respectively. In the case of a Changes Value condition, the debugger breaks each time the expression acquires a value different from its last evaluated value.

• Break for Watch Exprs at Statements (Else at Proc Entry):
  • On: Evaluate all break conditions at each statement execution. This setting can cause a drastic slowdown in execution.

  • Off: Evaluate all break conditions at each PROCEDURE entry. This is more efficient, but may still be much slower than normal execution, depending on how frequently debuggable PROCEDUREs are entered.

    Note: This is a global option that controls all break conditions, not just the one whose definition is currently being shown. It is included in this window for convenience; it can also be set with the Show->Options command.

  You can click on the L button to interrupt program execution while a break condition is in effect. When you click on L, the debugger remembers that you did so. Each time the debugger prepares to evaluate break conditions (at each PROCEDURE entry or at each statement), it first checks to see if you have clicked on L. If so it breaks without evaluating break conditions, then forgets that you clicked on L. This is especially important when evaluating break conditions at statements since programs can run for a very long time and you can become curious as to how far execution has gotten.

  Suppose you really need to evaluate a break condition at statements, but this slows your program too much. An alternate approach is as follows:

  • Set the break condition, and choose evaluation at PROCEDURE entry. This does not slow program execution down as much.

  • When the break condition occurs, note the value of the debuggable PROCEDURE count (shown in the lower left of the main window; this value is incremented each time a debuggable PROCEDURE is entered). Let this value be n. You know that the condition first became non-Zero between the debuggable PROCEDURE count n - 1 and the current PROCEDURE.

  • Rerun the program, first setting a count break value of n - 1 with the Breaks->Set Count Break command; this gets you to the last debuggable PROCEDURE entry before the condition becomes non-Zero. This execution proceeds at full speed.

  • Now set the break condition, and choose evaluation at the statement level. Since the break condition occurs before entering another debuggable PROCEDURE, the slowdown of evaluating break conditions at each statement should not be too severe.

• Delete: Delete this watch expression (stop watching it). This also removes the break conditions associated with the watch expression.