WATCH

Supplies a condition that must be true for a particular breakpoint to take effect.

address

The address of the breakpoint that is to be conditional.

Supply as part of the command, or from the cursor position. If supplied by means of cursor position and a watchpoint condition is specified, the condition must be preceded by a semicolon. If the address is supplied by means of cursor position and the command is a query (no condition supplied) the semicolon need not be supplied.

comparator

The condition being checked. Must be:

  = EQ ¬= NE > GT < LT >= GE <= LE

If the comparator and following parameters are not supplied the WATCH command is a query. In this case, the existing watchpoint condition for the address is displayed, or a message indicates that no watchpoint is active at the address.

instruction

A System/370 comparison instruction. This must be one of the following:

CR: Compare register
CLR: Compare logical register
C: Compare
CL: Compare logical
CH: Compare halfword
CLM: Compare logical characters under mask
CLC: Compare logical characters

This instruction is coded using standard assembler syntax, with a few exceptions that are detailed below.

The operation of the watchpoint is that when the watchpoint is encountered, the instruction you specified on the WATCH command is executed. If the result of the comparison instruction matches the comparator you specified, the watchpoint condition is considered true and execution of the target program stops, otherwise the target program continues to execute as if there was no breakpoint at the specified address. When the breakpoint is taken, if there is a list of commands associated with the watchpoint, they are executed before control is returned to you. These commands are specified at the end of the WATCH command, separated from the comparator instruction and each other by vertical bars (|). If a command receives a non-zero return code, the remaining commands in the list are not executed.

For example, if you want to stop execution of the target program at the instruction labeled LOOP only when R15 is nonzero, you can issue the following WATCH command and then start the target program through the RUN command:

   watch loop; ne c r15,=f'0'

Departures from standard assembler syntax are:

When specifying a register, you must use the Rn or rn notation. If you only supply the number of the register it is not recognized.
Literal data is supported for the F, H, X, and C data types. The maximum length of literal data is 50 bytes. Only one literal value may be specified when using a CLC instruction. Comparing two literals is meaningless as a watchpoint condition.
When specifying a symbolic address, do not also specify a base register, since the result is to access the specified address in storage as indexed by that register.

command

A command that is issued when the breakpoint is taken.

While the condition is false, control passes through the watchpoint and the target program is not stopped. But when the condition is true and the target program is at the breakpoint address, the target program is stopped for inspection.

Watchpoints are cleared by issuing a BREAK command or a SET BREAK OFF command for the address in question.

When you issue a WATCH command that specifies a CLC instruction, the length actually used in the comparison is shown to the right of the watchpoint condition if you query the watchpoint.

If a WATCH command with a condition is issued for an address at which there is a breakpoint, that breakpoint is converted into a watchpoint. If commands were specified with the original breakpoint, they are associated with the watchpoint unless commands were specified with the WATCH command.

If a watchpoint whose condition is true is placed within the execution path of the subroutine to be skipped, execution stops at that watchpoint.

Examples

To set a conditional breakpoint at location X'20040', to be taken when the contents of R3 are equal to the word in ARRAY within CSECT TEST as indexed by R1:

watch x'20040' ; = c r3,(test)array(r1)

To set a conditional breakpoint at TEST, to be taken if R3 and R4 are not equal:

wat test;ne cr r3,r4

To set a watchpoint at LOOP, to be taken when the 5 characters pointed to by R1 are thing, any of the following could be used:

watc  loop; = clc 0(5,r1),=c'thingxxx'
watch loop ; eq clc =c'thing',0(r1)
wat   loop; = clc 0(r1),=c'thing'

Return codes

0: Operation successful
3: Keyword not recognized
1: No address specified
5: Syntax or other error in expression
6: Specified location does not contain a valid instruction, or breakpoint table full