The SCL Debugger

WATCH

Suspends program execution when the value of a specified variable has been modified

Abbreviation:

Syntax
Details
Examples
See Also

Syntax

WATCH <entry-name\> variable <AFTER count> <WHEN clause | DO list >

entry-name\: is the name of the entry that contains the variable to be watched. The debugger starts watching the variable at the first executable statement in the program in the specified entry. If the entry resides in the current catalog, then entry-name can be a one-level name. If the entry resides in a different catalog, then entry-name must be a four-level name, and the entry must already be loaded into the application's execution stack. A backslash must follow the entry name.
variable: is the name of the variable to watch.
AFTER count: specifies the number of times for the value of the variable to be changed before the debugger suspends program execution. Therefore, for an AFTER specification of 3, the program halts when the value of the watched variable is changed for the third time.
WHEN clause: specifies an expression that must be true in order for the command to be executed. Clause can contain SCL functions.
DO list: contains one or more debugger commands to execute. Use semicolons to separate multiple commands.

Details

The WATCH command monitors a variable and suspends program execution when the value of the variable is modified. A variable is called a watched entry parameter if it is defined as both a watched variable and as an ENTRY statement parameter. A program is not suspended when the value of a watched entry parameter is changed by a called program. However, a program is suspended when a changed value for a watched entry parameter is copied back to the calling program.

Each time the variable is modified, the debugger

suspends program execution
checks for any AFTER count and resumes program execution if the specified number of changes has not been reached
evaluates the WHEN condition and resumes execution if the WHEN condition is false
displays the entry name and line number at which execution has been suspended
displays the variable's old value
displays the variable's new value
executes any commands that are provided in a DO list
returns control to the developer and displays the DEBUG> prompt.

You can watch only variables that are in the current program.

Examples

Monitor the variable DIVISOR in TEST2 for value changes:

DEBUG> w divisor

The output to the MESSAGE window is

Stop at line 6 in MYLIB.MYCAT.TEST2.SCL
Watch variable DIVISOR has been modified
Old value=1
New value=99

Monitor all the elements in the array NUM for value changes:
```
DEBUG> w num
```
Monitor the variable DIVISOR in TEST1.SCL for value changes:
```
DEBUG> w test1\divisor
```
Monitor an object attribute for its value changes:
```
DEBUG> w object.attribute
```
Monitor the variable A[1] for value changes and suspend program execution after its value has been altered three times:
```
DEBUG> w a[1] after 3
```
Monitor A[1] for value changes and suspend program execution when neither X nor Y is 0:
```
DEBUG> w a[1] when (x^=0 and y^=0)
```
Monitor FIELD1 for value changes and suspend program execution after the third change in the value of FIELD1 when the variables DIVIDEND and DIVISOR both equal 0:
```
DEBUG> w field1 after 3 when (dividend=0
       and divisor=0)
```
Monitor X when it has the same value as item 1 in LIST.
```
DEBUG> w x when x=getitemc(list,1)
```