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

Figure 19. The Breakpoint Dialog

The breakpoint dialog appears when you select At Cursor from the Break menu
or New from the Break menu and whenever you attempt to modify a break point.
 It allows you to define the breakpoint and set all of its conditions.  A
description of the items in the dialog follows.

Address
    This edit field displays the address tag associated with the selected
    breakpoint.

    When you choose At Cursor this field already contains an address that
    describes the line of code that the cursor is on.  The format of the
    address tag is symbol+offset where symbol is the name of the nearest
    function and offset is distance in bytes past that symbol where the
    break point is defined.  It is normally best NOT to edit this field.  To
    change the line of source code, leave the dialog, move the cursor to
    where you want the breakpoint, and use the At Cursor command again.

    When you choose New, this field is empty.  You can type any valid
    address expression in this field.  It can be the name of a function,
    global variable.  Refer to the section entitled
    Watcom Debugger Expression Handling for more information about address
    expressions.  In the dialog, you can click the Symbols...  button as a
    shortcut.  You can type a partial symbol name like foo and the Symbol
    button will show you a list of symbols that start with foo.  You can
    then choose one of these symbols by clicking on it or hitting ENTER.
     Note that the first time you use the Symbols...  in a debugging
    session, it will take a while as the debugger sorts the symbol table for
    the program.

    Note:
        Be careful when using local (stack) variables for a break-on-write
        breakpoint.  As soon as execution leaves the scope of the variable,
        the memory will change at random since the variable does not really
        exist any more and the memory will be used for other variables.
         Also, if execution enters that variable's scope again, the variable
        may not have the same memory address.

Condition
    Use this field to enter a conditions that must be met before a
    breakpoint will trigger.  The condition can be an arbitrary debugger
    expression.  These include statements in the language you are debugging.
     A valid example for the C language is i == 1.

Break on Execute
    Check this field to create a break-on-execute breakpoints.  If you
    choose Execute, be sure that the address field contains a code address
    (function name or code line number) and not a variable address.
     Variable are never executed.  If the address field names a variable,
    the breakpoint will never trigger.

Break on 1 Byte/2 Bytes/4 Bytes...
    Check one of these fields to create break-on-write breakpoints.  If you
    choose one of these options, be sure that the Address field contains a
    variable address and not a code address.  A code address will never be
    written to, so the breakpoint will never trigger.  The size of the
    memory location is defined by the checkbox you use as follows:

    1 Byte
        The breakpoint will trigger only when the first byte of the memory
        address is written to.

    2 Bytes
        The breakpoint will trigger when either of the first two bytes at
        the memory address are written to.

    4 Bytes
        The breakpoint will trigger if any of the first four bytes of the
        memory address are written to.

    etc.
        The breakpoint will trigger if any of the first "n" bytes of the
        memory address are written to.

Countdown
    Use this field to enter the number of times an address must be hit
    before the breakpoint triggers.  Every time the breakpoint conditions
    are met, the countdown decreases by one.  The breakpoint will trigger
    only after the countdown is at zero.  Once the countdown reaches zero,
    the breakpoint will trigger each time the conditions are met.  If you
    have also set a condition, the countdown will only decrease by one when
    the condition is true.

Total Hits
    This field displays the total number of times an address has been hit.
     This includes the times the breakpoint does not trigger because a
    condition failed or the countdown has not yet hit zero.

Reset
    Click on this button to reset the Total Hits field to zero.

Execute when Hit
    Use this field to enter a debugger command.  When the breakpoint is
    triggered, the debugger will execute this command.  You can use this
    field to execute arbitrary C statements, change a variable or register,
    or even set other breakpoints.  For a more detailed description of
    commands that can be entered in this field, refer to the section called
    Debugger Commands.  If you want to use this field to execute a statement
    in the language you are debugging, you need to use a DO command in front
    of the statement.  For example, you could enter DO i = 10 to have the
    value of 10 assigned to i each time the breakpoint triggered.

Resume
    Check this field if you want the program to resume execution after the
    Execute when Hit command has been completed.  This capability can be
    used to patch your code.

Enabled
    This field displays the current status of the breakpoint.  If it is
    checked, the breakpoint is enabled.  If it is unchecked, the breakpoint
    is disabled.

Value
    For Break-on-Execute breakpoints this field displays the source line or
    the assembly line at which the break point is defined.  For
    Break-on-Write breakpoints, this field displays the memory contents.

Clear
    Click on the clear button to clear the breakpoint and close the dialog.