WATCH

Set a watchpoint

WTSupported in traditional Synergy on Windows

 

USupported on UNIX
VSupported on OpenVMS
WATCH variable [option]
WATCH variable  rel_operator  value
WATCH address [option]

Arguments

variable

Sets a watchpoint on the specified variable. See Specifying variables for more information about variable specifications. Variable can also be a ^M(struct_fld, handle) specification.

option

(optional) The type and size of the variable or address to watch. It must be one of the following:

/An = Alpha of size n

/In = Integer of size n

rel_operator

One of the following relational operators:

.GT. = Greater than

.LT. = Less than

.GE. = Greater than or equal to

.LE. = Less than or equal to

.EQ. = Equal to

.NE. = Not equal to

value

The numeric value to which variable will be compared.

address

Sets an i4 watchpoint at the specified address.

Discussion

The WATCH command sets a watchpoint on the specified variable or address. This means that when the contents of the variable have changed or the expression variable rel_operator value is true, the debugger is invoked and the contents are displayed. If you watch a variable that is longer than one line (80 characters), the variable’s contents are displayed on multiple lines. Any nonprinting characters are displayed as periods (.). The debugger breaks on the line that changes the variable.

The maximum number of watchpoints is 32.

Variable is a variable specification identical to data division variable specifications. Any variable or address being watched can be cast by the option qualifier. For example, you can watch the center three bytes of a d5 variable as alpha using the following command:

SET WATCH dvar(2:3)/a3

You can also watch two successive records by spanning across both. For example, given the following data division:

record a
    avar1       ,a10
    avar2       ,a10
record b
    bvar1       ,d10
    bvar2       ,d10

you could specify the following SET WATCH commands:

SET WATCH a/a40

or

SET WATCH a   and   SET WATCH b/d20

The relational operators below can be used to watch a variable in relation to another value or in relation to another variable. In the second case, the value of the second variable will be saved at the time the watchpoint is set, and the value of the first variable will be compared against that value. A relational watchpoint will be deleted after the watchpoint has triggered.

.GT. or >

.LT. or <

.GE. or >=

.LE. or <=

.EQ. or ==

.NE. or !=

For example, the following breaks when var1 becomes less than the value of var2 (that is, the value of var2 when the watchpoint was set):

WATCH var1 .LT. var2

Watching object handles

A simple, nonrelational watchpoint on a handle saves the current handle reference and breaks when that reference changes. For relational watchpoints on handles, only .EQ. and .NE. are permitted. These are interpreted as “Do these handles now reference the same object?” and “Do these handles now reference different objects?” respectively. Handles can be compared against each other or against the value ^NULL, which indicates that no object is referenced.

Note

Custom implementation of the op_Equality or op_Inequality operator methods will not be recognized by the debugger.

Watching string objects

Watchpoints on string objects behave the same as watchpoints on alpha variables, with the additional option of comparing the string handle to ^NULL using the .EQ. or .NE. operator.

Examples

The following example breaks when the first four characters of the variable ab have changed.

WATCH ab

The next example breaks when the contents of x are greater than or equal to 0.

WATCH x .ge. 0

The example below breaks when the contents of the alpha variable id equals “A327”.

WATCH id/A4 .eq. "A327"

The following example breaks when the contents of the class field myfld is less than 12.

WATCH myclass.myfld .lt. 12

The example below breaks when the object handle objhnd changes to reference a different object or changes to or from ^NULL.

WATCH objhnd

This example breaks when objhnd1 no longer references the same object as objhnd2.

WATCH objhnd1 .NE. objhnd2

This example breaks when the string handle becomes ^NULL.

WATCH stringvar .EQ. ^NULL

This example breaks when the content of the string variable exceeds “ABC”.

WATCH stringvar .GT. "ABC"