NAME

watch - Run-time tracing of Soar

SYNOPSIS

watch [option*]

DESCRIPTION

The watch command controls run-time tracing of Soar. With no arguments, this command prints out the current watch status. The various options are used to modify the current watch settings. For example, watch -context on turns on the tracing of context slot decisions; watch -context off turns it off again. Individual watch parameters may be changed using this command as well as sets of parameters defined by watch levels. The learn command may also be used to alter certain watch settings.

OPTIONS

The following options are allowed (status must be given as either on or off):

-context status
controls whether context slot decisions are printed
-phases status
controls whether phase names are printed
-firings [ default | user | chunk | nonchunk | all ] status
controls which production firings and retractions are printed. The optional argument (which defaults to all) specifies which types of productions the status argument refers to.
-firings-wmes [ 0 | 1 | 2 ]
controls the level of detail given about the wmes matched by productions whose firings and retractions are being traced. Level 0 means no information about the wmes is printed. Level 1 means the wme timetags are printed. Level 2 means the whole wmes are printed.
-firings-preferences status
controls whether the preferences generated by the traced productions are printed when those productions fire or retract. When a production fires, all the preferences it generates are printed. When it retracts, only the ones being removed from preference memory are printed (i.e., the i-supported ones).
-wmes status
controls whether changes to working memory are printed
-chunk-names status
controls whether names of newly built chunks are printed
-justification-names status
ditto, only for justifications (internal chunks)
-chunks status
controls whether newly built chunks are printed
-justifications status
ditto, only for justifications
-backtracing status
controls whether backtracing information is printed

The options above allow complete control over individual watch settings. Some settings are often manipulated together and an aggregrate scheme has been generated to help make this process easier. Hence, a watch option can also be one of the following numeric arguments: -1, 0, 0.5, 1, 1.5, 2, 3. The table below gives the corresponding option parameter settings for each numeric argument:

            Watch Level:    -1    0  0.5    1  1.5    2    3
                           ---- ---- ---- ---- ---- ---- ----
  -context                 off   on   on   on   on   on   on
  -phases                  off  off   on   on   on   on   on
  -firings nonchunk        off  off   on   on   on   on   on
    -firings-wmes            0    0    0    1    2    2    2
    -firings-preferences   off  off  off  off  off  off   on
  -wmes                    off  off  off  off  off   on   on

watch task is also provided and is equivalent to watch -firings default off.

learn noprint/print/full-print and notrace/trace/full-trace also translate into keyword parameter settings, as shown in the tables below:

          Learn:   noprint  print  full-print
                   -------  -----  ----------
  -chunk-names        off     on          on
  -chunks             off    off          on

          Learn:   notrace  trace  full-trace
                   -------  -----  ----------
  -firings chunk      off     on          on
  -backtracing        off    off          on

EXAMPLES

The most common uses of watch are by using the numeric arguments which indicate watch levels:
watch 0

or

watch 3

Of course, individual options can be changed as well:

watch 1 -justifications off -chunks on

SEE ALSO

learn, ptrace