Click above to get retro games delivered to your door ever month!

Figure 16. The Watch and Variable Window

Windows that display variables come in several different varieties.  They
are:

 .  Locals
 .  File Variables
 .  Watches
 .  Variable

They are collectively called variable windows.  You use the same
interactions in all variable windows to display, modify and browse your
variables and data structures.  The only difference between these windows
are the variables that they display.  The values in each window are updated
as you trace through your program.  The windows display the following
information:

Locals
    Contains the list of variables which are local to the current routine.
     Choose Locals from the Data menu to open this window.

File Variables
    Contains a list of all variables which are defined at file scope in the
    current module.  This includes external and static symbols.  Choose File
    Variables from the Data menu to open this window.

Watches
    The Watches windows allows you to add and delete variables and
    expressions.  In other windows you can choose Watch from the pop-up
    menu.  This will open the watches window add the text which is selected
    in another window to the watches window.  You can use New from the
    pop-up menu to add any expression to the Watches window.  Once entered,
    you can choose Edit from the pop-up menu to edit the expressions or
    typecast the variables.

Variable
    This is another instance of a Watches window.  A variable window is
    created when you select a variable or expression in a window and use
    Inspect from the pop-up menu.

Each line of a variable window has three elements.  On the left is a button.
 The button changes depending on the type of the variable or expression.  it
changes based on the type of the item:

structs (classes) (unions)
    Structures may be opened and closed by clicking on the button at the
    left.  When you open a structure or class, one line is added to the
    window for each field of the structure.  These new lines are indented.
     If you click on the button again, the structure is closed and the
    window is returned to its original state.

arrays
    Like structs, arrays may be opened and closed.  When you open an array,
    one line is added to the window for each element of the array.  The
    debugger will display at most 1000 elements of an array.  If it contains
    more you can use Type/Array...  to open different ranges.  Multi
    dimensional arrays are treated like an array of arrays.  When you open
    the first dimension, the lines that are added will also be arrays which
    you can open.

pointers
    When the variable is a pointer, you can click on the button and the
    debugger will follow the pointer and change the line to represent the
    item which is the result of the pointer reference.  For example, if you
    have a pointer to an integer and click on the button, the integer value
    will be displayed.  The button then changes to indicate so that you can
    undo the operation by clicking on it again.

    In the case of pointers to pointers, clicking on the button will follow
    the pointers one level each time you click on the button until a
    non-pointer value is reached.  Clicking on the button at this point will
    undo take you back to the original state.  When the pointer points to a
    struct, the structure will automatically be opened when you click on the
    button.  If a pointer is really an array, you can use Type/Array...
     from the pop-up menu to open it as an array.

Next comes the name of the variable, field or array element being displayed.
 Finally, the value is displayed.  If the item being displayed is not a
scalar item, the value displayed is an indication that it is a complex data
type.  If the value changes when you run your program, it will be
highlighted.  If a variable goes out of scope, or a pointer value becomes
invalid, the value will be displayed as question marks.

You can modify a variable's value by double clicking on the value field, or
by cursoring to it and pressing enter.  Double clicking or pressing enter on
the name field is equivalent to clicking on the button.  Press the right
mouse button to access the following pop-up menu items:


Modify...
    Modify the value of the selected item.

Break
    Set a breakpoint so that execution stops when the selected item's value
    changes.  This is the same as setting a breakpoint on the object.  See
    Breakpoints.

--------


Inspect
    Open a new Variable window containing the selected item.  If the item is
    a compound object (array, class, or structure), it will be opened
    automatically.

Watch
    Add the selected item to the Watch window.

Show/Raw Memory
    Display raw memory at the address of this variable.  This lets you
    examine the actual binary representation of a variable.

Show/Pointer Memory
    Display the memory that the item points to.  This is useful when you
    have a pointer to a block of memory that does not have a type associated
    with it.

Show/Pointer Code
    Display the code that the variable points to.  If the item being
    displayed is a pointer to function, you can use this menu item to see
    the definition of that function.

Show/Type
    Display the type of the variable in an information message box.  Select
    "OK" to dismiss the information box and resume debugging.

--------


Edit
    Open a dialog box in which you can edit an expression in the Watch
    window.  This is useful for typecasting variables or evaluating
    expressions.  See Watcom Debugger Expression Handling.

New
    Add a new variable or expression to the window.  You will be prompted
    for the expression to add.

Delete
    Delete the selected item from the window.

--------


FieldOnTop
    Display the value of this member at the top of the structure/class.  You
    can selectively add or remove items from the list that is displayed "on
    top".  For example, say you have a struct Point displayed as:


         [-] point
           x      10
           y      30
           other  "asdf"

    If you toggle FieldOnTop for both x and y then point would be displayed
    like this:


         [-] point { 10, 30 }
           x      10
           y      30
           other  "asdf"

    Furthermore, if you closed the struct (or pointer to struct) then you
    would see:


         [+] point { 10, 30 }

    This carries to structs containing structs (and so on) as shown in the
    following struct containing two Point structures.


         [-] rect { { 10, 10 }, { 30, 30 } }
           top_left { 10, 10 }
           bot_right { 30, 30 }

    If you close it, then you will see:


         [+] rect { { 10, 10 }, { 30, 30 } }


Class/Show Functions
    Display function members of this object.  If this option is not
    selected, no functions are displayed.  This option works in conjunction
    with other Class selections to display "Inherited", "Generated",
    "Private" and "Protected" functions.

Class/Show Inherited
    Display inherited members of this object.  To see inherited functions,
    you must also select Class/Show Functions.

Class/Show Generated
    Display compiled-generated members of this object.  To see generated
    functions, you must also select Class/Show Functions.

Class/Show Private
    Display private members of this object.  To see private functions, you
    must also select Class/Show Functions.

Class/Show Protected
    Display protected members of this object.  To see protected functions,
    you must also select Class/Show Functions.

Class/Show Static
    Display static members of this object.

Type/Hex
    Change the value to be displayed in hexadecimal.

Type/Decimal
    Change the value to be displayed in decimal.

Type/Character
    Change the value to be displayed as a single character constant.  This
    useful when you have a one byte variable that really contains a
    character.  The debugger will often display it as an integer by default.


Type/String
    The debugger automatically detects pointers to strings in the variable
    windows and displays the string rather than the raw pointer value.  In
    the string is not null terminated, contains non-printable characters, or
    is not typed as a pointer to 'char', this mechanism will not work.
     Type/String overrides the automatic string detecting and displays the
    pointer as a string regardless of its type.

Type/Pointer
    This will undo the effects of Type/String or Type/Array.  It will also
    let you see the raw pointer value when the debugger has automatically
    displayed a pointer to char as a string.

Type/Array...
    Use this menu item to display a pointer as if it were an array, or to
    display ranges of an array's elements.  You will be prompted for the
    first and last element to display.

Options/Whole Expression
    Select this option to show the whole expression used to access fields
    and array elements instead of just the element number or field name
    itself.

Options/Expand 'this'
    Do not display members of the 'this' pointer as if they were local
    variables declared within the member function.