6.2.5 Setting a watchpoint (watch command)

The watch command sets a watchpoint. The abbreviation for the watch command is wa.

Numbers are assigned sequentially to the watchpoints as they are set, beginning with 1. Breakpoints that are set are numbered in the same sequence (that is, point number n could be a watchpoint or a breakpoint). The following shows the format of the watch command:

watch variable-name

You specify a variable name as the argument of the watch command. Whenever the value of the specified variable is updated, execution of the job definition script stops at the next command where execution can be stopped and watchpoint information is displayed.

The following describes the watch command's processing.

When the watch command argument is specified

The command sets a watchpoint at the specified variable. The command also displays information about the set watchpoint.

When the watch command argument is omitted

The command outputs an error message.

When execution of a job definition script is stopped by a watchpoint, the watch command displays as the watchpoint information the pre-update value, the post-update value, and the line number of the line that updated the variable. The following shows the display format:

Old value = pre-update-value
New value = post-update-value
Line = line-number

• pre-update-value: This is the watched variable's value before updating. If there is no value, <No value> is displayed.

• post-update-value: This is the watched variable's value after updating. If there is no value, <No value> is displayed.

• line-number: This is the line number of the line that updated the variable. If the trap command's action is running, <Trap action> is displayed. If the line is the end of the job definition script, <EOF> is displayed.

Notes:

• To specify an array for the variable name, you must specify an array element.

  Examples:

  Normal variable specification: aaa

  Array specification: aaa[1]

• A variable and its array 0 (example: aaa and aaa[0]) are the same. However, you can set a watchpoint for each of them.

• A variable name with a dollar sign ($) attached is not recognized as a variable name.

• The command does not check at the time the watch command is entered whether the specified variable actually exists.

• If the variable name specification violates a naming convention, the command outputs an error message.

• Execution stops at the watchpoint even if the new value assigned to the variable is the same as its pre-update value.

• When the typeset standard shell command is used to change the value of the variable from character string type to integer type, or vice versa, execution stops at the location as a watchpoint.

• Because the same naming conventions apply to both functions and variables, you can set a watchpoint by specifying a function name as the argument. However, execution of the job definition script will not stop unless the value of the variable whose name is the same as the specified function name is updated.

• If one line contains multiple commands and the value of a watched variable is updated, execution stops before the next command at which execution can be stopped even on the same line.

• The total number of breakpoints and watchpoints combined cannot exceed 999. If this limit has been reached and you want to set a new breakpoint or watchpoint, terminate and restart the debugger. Once the maximum value has been reached, no new breakpoint or watchpoint can be set even if you use the delete command to delete existing breakpoints or watchpoints.

• If the set command is used to change the value of a watched variable while the job definition script is stopped and then execution of the job definition script is restarted, execution will stop before the next command at which execution can be stopped.

• Only one watchpoint can be set for the same variable. Once a watchpoint is set for a variable, no more watchpoints can be set for that variable.

• Execution of a job definition script does not stop when the value of a watched variable is changed by any of the following commands:

  Commands executed in the background (& or |&)

  Commands joined by a pipe

  Group of commands enclosed in parentheses (())

  Commands that are executed as separate processes, such as external commands

  Example:

  1: a=1 &

  2: b=2

  3: c=3

  In the above example, if a watchpoint is set for variable a and then the job definition script is executed, execution of the job definition script does not stop because the assignment expression a=1 is executed in the background.

Example

In the following job definition script, specifying watch b will set a watchpoint for variable b:

1: echo "start"
2: a=1
3: b=5
4: c=10
5: echo "end"

When the job definition script is executed and then the assignment expression b=5 is executed, the watchpoint information will be displayed and execution will stop before execution of c=10 on line 4:

KNAX7023-I Watchpoint "1": variable="b"
Old value = <No value>
New value = 5
Line = 3
KNAX7032-I The script "test.ash" stopped running.
4: c=10
Current: c=10
(adshdb)

To Page Top