Characteristics of Watches

You should know the following characteristics about watches before working with them:
  • Watches are monitored system-wide, with a maximum number of 256 watches that can be active simultaneously. This number includes watches set by the system.
    Depending on overall system use, you may be limited in the number of watch conditions you can set at a given time. If you try to set a watch condition while the maximum number of active watches across the system is exceeded, you receive an error message and the watch condition is not set.
    Note: If an expression or a variable crosses a page boundary, two watches are used internally to monitor the storage locations. Therefore, the maximum number of expressions or variables that can be watched simultaneously system-wide ranges from 128 to 256.
  • Watch conditions can only be set when a program is stopped under debug, and the expression or variable to be watched is in scope. If this is not the case, an error message is issued when a watch is requested, indicating that the corresponding call stack entry does not exist.
  • Once the watch condition is set, the address of a storage location watched does not change. Therefore, if a watch is set on a temporary location, it could result in spurious watch-condition notifications.

    An example of this is the automatic storage of an ILE RPG subprocedure, which can be re-used after the subprocedure ends.

    A watch condition may be registered although the watched variable is no longer in scope. You must not assume that a variable is in scope just because a watch condition has been reported.

  • Two watch locations in the same job must not overlap in any way. Two watch locations in different jobs must not start at the same storage address; otherwise, overlap is allowed. If these restrictions are violated, an error message is issued.
    Note: Changes made to a watched storage location are ignored if they are made by a job other than the one that set the watch condition.
  • After the command is successfully run, your application is stopped if a program in your session changes the contents of the watched storage location, and the Display Module Source display is shown.

    If the program has debug data, and a source text view is available, it will be shown. The source line of the statement that was about to be run when the content change at the storage-location was detected is highlighted. A message indicates which watch condition was satisfied.

    If the program cannot be debugged, the text area of the display will be blank.

  • Eligible programs are automatically added to the debug session if they cause the watch-stop condition.
  • When multiple watch conditions are hit on the same program statement, only the first one will be reported.
  • You can set watch conditions also when you are using service jobs for debugging, that is when you debug one job from another job.