RuleWorks

RuleWorks

Debugging RuleWorks Programs

You can use the RuleWorks debugging commands to find errors in your program and to interact with it while it is running. If your program calls routines written in another language, you must use that language's debugger to find errors in those routines. That debugger sees the C code generated by the RuleWorks compiler, not your RuleWorks source code. DEBUG qualifier.

Note: that the RuleWorks debugger, unlike other debuggers, is subordinate -- it is called from your program. Other debuggers call your program. You control the appearance of the RuleWorks interpreter with the Debug compilation qualifier, DEBUG action, and the rul_debug RTL routine.

Using the RuleWorks Command Interpreter

The RuleWorks command interpreter lets you interactively control the execution of an entry block by entering RuleWorks commands. Table 9-1 lists these commands with their corresponding operations.

Table 9-1. Debugging Commands

CommandsOperation
@Execute contents of a command file
EBREAK
RBREAK
WBREAK
Use breakpoints
PPCLASSDisplay the inheritance hierarchy of an object class
PPWM
WMHISTORY
Display objects in working memory
MAKE
MODIFY
COPY
SPECIALIZE
REMOVE
REMOVE-EVERY
Change working memory
MATCHESDisplay match information
CS
NEXT
Display the contents of the conflict set
TRACEDisplay trace information

ADDSTATE
RESTORESTATE
SAVESTATE
Save and restore visible working memory and active conflict set
DISABLE
ENABLE
Change the state of program operation
AFTERSet the recognize-act counter for a catcher
RUNExecute recognize-act cycles

 

Entering RuleWorks Commands

The RuleWorks command interpreter displays the following prompt:

    RuleWorks>

To enter a RuleWorks command, type the command, with arguments if appropriate, and then press the Return key. To extend a command over more than one line, you can either enclose it in parentheses (which you can optionally use for single-line commands also) or use the continuation character (-).

An example of a single-line command entered, without parentheses, at the interpreter prompt is shown below:

    RuleWorks>CS

If you end a line with the continuation character, the command interpreter prompts you for the rest of the command each time you press the Return key. For example:

    RuleWorks>MAKE HD-30 ^IS-EXPANDED YES ^NAME HD-30 ^PART-NUMBER HD-30

    _RuleWorks>^PRINT-NAME |30 Megabyte Hard Disk Drive| ^PRICE 599.95

    _RuleWorks>^TAKES-SLOT YES

If you begin a command with a parenthesis, you must make sure you have the same number of left and right parentheses, because the interpreter matches each left parenthesis with a corresponding right parenthesis before it accepts the command. The MAKE command above can also be entered with parentheses but without a continuation character:

    RuleWorks>MAKE HD-30 ^IS-EXPANDED YES ^NAME HD-30 ^PART-NUMBER HD-30

    _RuleWorks>^PRINT-NAME |30 Megabyte Hard Disk Drive| ^PRICE 599.95

    _RuleWorks>^TAKES-SLOT YES

If you want to include an extra unmatched parenthesis in such a command, you must enclose it in quote characters, for example, ||. Otherwise the interpreter counts it as a parenthesis to be matched before it allows you to end the command.

Arguments, which can be optional or required, must follow the command name. If you do not specify a required argument, the run-time system displays an error message, shows the correct syntax and an example, and finally redisplays the command interpreter prompt. For example:

    RuleWorks>make

    %RUL-E-SYNTAXERR, Syntax error: MAKE command missing required parameters Usage: MAKE class-name [ {^attribute value}... ]

    Example: RuleWorks> make my-part ^number 801 ^color-list[3] yellow

    Note: The command interpreter does not evaluate arguments. Therefore, you cannot use variables as an argument to a RuleWorks command. Similarly, you cannot use a call to any function except COMPOUND.

Exiting the Command Interpreter

Use the EXIT command to exit the command interpreter. Depending on whether your RuleWorks code is set up as a main program or a callable routine, control returns either to the operating system or to the calling program.

    RuleWorks>exit

    $

Using RuleWorks Command Files

You can store a list of RuleWorks commands in a file and execute them later by using the RuleWorks @ command inside your ON-ENTRY statement or at the command interpreter. For example, you can have an @ file of MAKE commands to create objects when your program starts.

The following command opens the file ORDER.WM and causes the command interpreter to execute the commands stored in that file:

    RuleWorks>@ ORDER.WM

If the file you specify with the @ command contains information other than RuleWorks commands, the run-time system displays an error message. For example:

    RuleWorks>@ ORDER.DAT

    %RUL-E-SYNTAXERR, Syntax error: unknown command 'home-Kiwi'

Using Breakpoints

A breakpoint causes your program to pause under certain conditions: a specified rule is about to be executed or an object that matches a specified pattern has just been created, changed, or deleted. You can set, delete, and list breakpoints by using the EBREAK command for entry blocks; the RBREAK command for rules and rule groups; and the WBREAK command for WMOs.

When the run-time system encounters a breakpoint, the system finishes executing the current recognize-act cycle, displays an informational message, and then invokes the command interpreter, to allow you to enter debugging commands. The format of the message depends on your operating system. For example, on VMS systems:

    %RUL-I-EBREAK, EBREAK encountered; pausing after ON-ENTRY in MAIN

If a breakpoint is set for an entry block, the run-time system pauses for the breakpoint after executing the ON-ENTRY and ON-EXIT clauses (if any) of the entry block. If a breakpoint is set for a rule, the run-time system pauses for the breakpoint just before executing that rule. Setting a breakpoint on a rule group is equivalent to setting breakpoints on every rule in the group. If a breakpoint is set for an object pattern, the run-time system pauses for the breakpoint after executing the rule that created, changed, or deleted the object.

Setting Breakpoints

To set a breakpoint, specify the EBREAK, RBREAK, or WBREAK command with the keyword ON and the name of the entry block or rule, or a pattern matched by the WMO.

You can give more than one name with a break command. For example, the following command sets breakpoints on two rules:

    RuleWorks>rbreak on verify-configuration:need-memory choose-slots:place-memory

The WBREAK command accepts at most one object pattern. This pattern is similar to a CE but more limited: it must include an object class name and can also include attributes with predicates and values. It cannot include variables, function calls or other expressions.

For example, suppose a breakpoint is already set for objects of class FLOPPY. The following two commands set a new breakpoint for objects with class name DISK and ^PRICE identical to 299.95, and delete the old one on class FLOPPY:

    RuleWorks>wbreak on disk ^price 299.95

When you specify an object class that has inheriting subclasses, objects of those subclasses are also affected by the WBREAK commands. Thus, the command above affects objects of classes DISK, FLOPPY, FD-5, FD-35, HARD-DISK, HD-30, and HD-200. See Chapter 2 for an illustration of the class inheritance hierarchy of the sample program KIWI.

Listing Breakpoints

To see what breakpoints are set, use the EBREAK, RBREAK, or WBREAK command without any keyword or arguments. The following example shows that breakpoints are set for two rules:

    RuleWorks>rbreak

    RBREAKs set on:

    1 VERIFY-CONFIGURATION:NEED-MEMORY

    2 CHOOSE-SLOTS:PLACE-MEMORY

This example shows that breakpoints are set for certain objects of class DISK:

    RuleWorks>wbreak

    WBREAKs set on:

    1 (DISK ^PRICE <= 299.95)

 

Deleting Breakpoints

To delete a breakpoint, specify the EBREAK, RBREAK, or WBREAK command with the keyword OFF, and one of the following:

  • the name of the entry block or rule, or a pattern matched by a WMO, that has a breakpoint set
  • a number displayed by a break command when given no arguments (as shown above)
  • an asterisk (*)

Use an asterisk to delete all breakpoints. For example:

    RuleWorks>rbreak off

    RuleWorks>rbreak

    No RBREAKs set.

 

Displaying the Inheritance Hierarchy

Use the PPCLASS command with the name of an object class to display the inheritance hierarchy of that class. This command lists the ancestors of the class you specify, starting at the top-level user-defined class. All attributes declared for that class, including those it inherits, are shown after the class name. For example:

    RuleWorks>ppclass box

      PART

        BOX

          ^$ID instance-id of BOX

          ^$INSTANCE-OF symbol (default BOX)

          ^PARTNUMBER

          ^NAME

          ^PRICE

          ^IS-EXPANDED (default NO)

          ^CARD-IN-SLOT compound

          ^CARD-IN-SLOT-OBJ-ID compound

An attribute's default and fill values, if any, are shown inside parentheses after the attribute's name. Compound attributes are also identified as such.

To display which object classes are visible to the active entry block, use the PPCLASS command with no argument. This shows the name of the entry block (and declaration blocks, if any) and the top-level user-defined classes only. For example:

    RuleWorks>ppclass

      Entry block CONFIG

        LOCAL

      Declaration block KIWI_DECLS

        CONTROL-CONTEXT

        ERROR

        INPUT-THING

        PART

 

Displaying Working-Memory Objects

During a debugging session, you can examine the contents of working memory to make sure it contains correct information. Missing or erroneous objects can cause a rule to be executed at the wrong time. The WM, PPWM, and WMHISTORY commands display the contents of working memory:

Table 9-2. Working Memory Commands

CommandDescription
WMDisplays all objects or objects with specified INSTANCE-IDs.
PPWMDisplays all objects or objects that match a specified pattern.
WMHISTORYDisplays the revision history of the object with a specified INSTANCE-ID, or of a specified attribute of that object.

The WM and PPWM commands provide the following information about each object:

  • Its INSTANCE-ID
  • Its time-tag
  • The name of the rule that set the time-tag (that is, the rule that last modified the object)
  • Its object class name, its attributes, and the attributes' values

The run-time system displays this information in the following format:

    #INSTANCE-ID time-tage[rule-name] (class-name ^attr-1 value-1 ^attr-2 value-2 ...)

The WMHISTORY command provides the following information about an object

  • Its INSTANCE-ID
  • Its time-tag
  • The name of the rule that last modified it
  • Its object class name
  • The name of the rule that set the object class name (that is, the rule that originally created the object)
  • Its attributes, the attributes' current values, and the names of the rules that set the attributes' current values

The run-time system displays this information in the following format:

    #INSTANCE-ID time-tage[rule-name-n] (class-name [rule-name] {attr-1 value-1 [rule-name-1]} )

When you create or change an object with an action contained in an "ON-"statement, the name of that statement appears inside the brackets rather than a rule name. When you use a command, the atom RUL appears.

The run-time system does not print an empty attribute unless you have specified a DEFAULT value for it. Empty is defined as a NIL value for scalar attributes, (COMPOUND) for compound attributes. Attributes that have a DEFAULT declaration are always printed.

Displaying the Contents of Working Memory

To display the entire contents of working memory, use either the WM or PPWM command without an argument. For example:

    RuleWorks>wm

      #1 1 [ON-ENTRY] (CONTEXT ^NAME TASKS-TO-DO)

      #2 2 [TASKS-TO-DO:TASKS-TO-DO] (CONTEXT ^NAME OUTPUT-NEW-ORDER)

      #3 3 [TASKS-TO-DO:TASKS-TO-DO] (CONTEXT ^NAME MODIFY-SOFTWARE-MEDIA)

      #4 4 [TASKS-TO-DO:TASKS-TO-DO] (CONTEXT ^NAME CHOOSE-SLOTS)

Object #1 was made in the ON-ENTRY statement, so that name appears inside the brackets instead of the name of a rule.

Displaying Specific Working-Memory Objects

To display particular objects, specify their INSTANCE-IDs with the WM command. The following example displays the objects that have INSTANCE-IDs #23 and #24:

    RuleWorks>wm #23 #24

      #23 27 [VERIFY-CONFIGURATION:MOUSE-PORT] (ERROR ^SEVERITY WARNING ^MESSAGE |Missing mouse port|)

      #24 28 [VERIFY-CONFIGURATION:MOUSE-PORT] (KEYBOARD ^IS-EXPANDED NO ^IS-PLACED NO)

You can find out which INSTANCE-IDs are assigned to which objects by setting the run-time system's TRACE level to WM. For further information on trace levels, See the Displaying Trace Information section of this chapter.

Displaying the History of Specific Working-Memory Objects

To display the names of the rules that have created or modified a particular object, specify the INSTANCE-ID of that object with the WMHISTORY command. By default, the WMHISTORY command is disabled. You must enable it with the ENABLE command before running the rules that affect the objects you want to display. The following example shows the history of the object whose INSTANCE-ID is #36:

    RuleWorks>enable wmhistory

    RuleWorks>run 45

    RuleWorks>wmhistory 36

      #36 41 [EXPAND-PART-SKELETONS:FD-35] (FD-35 [VERIFY-CONFIGURATION:NEED-DISK] ^ TAKES-SLOT YES [EXPAND-PART-SKELETONS:FD-35] ^NAME FD-35 [EXPAND-PART-SKELETONS: FD-35] ^PART-NUMBER FD-35 [EXPAND-PART-SKELETONS:FD-35] ^PRINTNAME 3.5" Floppy Disk Drive [EXPAND-PART-SKELETONS:FD-35] ^PRICE 99.95 [EXPAND-PART-SKELETONS:FD- 35] ^IS-EXPANDED YES [EXPAND-PART-SKELETONS:FD-35])

In this example, the WMHISTORY command shows that the rule EXPAND-PART-SKELETONS:FD-35 most recently changed this object, because that is the rule shown after the time-tag. Another rule, VERIFY-CONFIGURATION:NEED-DISK, originally created the object, because that is the rule shown after the class name. The rule EXPAND-PART-SKELETONS:FD-35 set the values of all the attributes.

If you are interested in which rule set a particular attribute value, you can specify the attribute name with the WMHISTORY command:

    RuleWorks>wmhistory #36 ^price

      #36 41 [EXPAND-PART-SKELETONS:FD-35] (FD-35 [VERIFY-CONFIGURATION:NEED-DISK]

      ^ PRICE 99.95 [EXPAND-PART-SKELETONS:FD-35])

When you use a command rather than an action inside a rule to create or modify an object, the atom RUL rather than the name of a rule appears inside the brackets after the time-tag, class name, or attribute value. When you use an action inside an "ON-"statement, the name of that statement appears inside the brackets.

Displaying the Working-Memory Objects of an Object Class

To display the objects of a particular object class, use the PPWM command with the name of that class. For example:

    RuleWorks>ppwm error

      #23 27 [VERIFY-CONFIGURATION:MOUSE-PORT] (ERROR ^SEVERITY WARNING ^MESSAGE | Missing mouse port|)

      #25 29 [VERIFY-CONFIGURATION:APPLICATION-NEEDS-KIWOS] (ERROR ^SEVERITY WARNIN G ^MESSAGE |Missing operating system|)

      #27 31 [VERIFY-CONFIGURATION:KIWOS-MEMORY] (ERROR ^SEVERITY WARNING ^MESSAGE |Missing memory|) )

If you specify the name of an object class that has inheriting subclasses, objects of those subclasses are also displayed. For example:

    RuleWorks>ppwm software-option

      #27 69 [MODIFY-SOFTWARE-MEDIA:35-CHEAPEST] (KIWICALC ^MEDIA-TYPE FD-35 ^NAME KIWICALC ^PART-NUMBER S-CA-9200 ^PRINTNAME KiwiCalc Spreadsheet Software ^PRI CE 29.95 ^IS-EXPANDED YES)

      #29 70 [MODIFY-SOFTWARE-MEDIA:35-CHEAPEST] (KIWINDOWS ^MEDIA-TYPE FD-35 ^NAM E KIWINDOWS ^PART-NUMBER S-WI-9200 ^PRINTNAME KiWindows Windows Software ^PRIC E 59.95 ^IS-EXPANDED YES)

      #39 71 [MODIFY-SOFTWARE-MEDIA:35-CHEAPEST] (KIWOS ^MEDIA-TYPE FD-35 ^NAME KI WOS ^PART-NUMBER S-OS-9200 ^PRINTNAME KIWOS Operating System ^PRICE 9.95 ^IS-E XPANDED YES)

(See Chapter 2 for an illustration of the class inheritance hierarchy of the sample program KIWI.RUL.)

Displaying Working-Memory Objects that Match a Pattern

To display the objects that match a specific object pattern, use the PPWM command with an object class name followed by the pattern you want to match. This pattern is similar to an attribute-value test but variables and function calls are not allowed, except COMPOUND.

The following example displays all parts that match the object pattern ^PRICE < 50.00. The ^PRICE attribute is first declared in the PART class. Therefore, to display all objects that have the ^PRICE attribute, the object class name PART is specified in the PPWM command. The objects that actually match the pattern are instances of classes KIWICALC and KIWOS:

    RuleWorks>ppwm part ^price < 50.00

      #27 69 [MODIFY-SOFTWARE-MEDIA:35-CHEAPEST] (KIWICALC ^MEDIA-TYPE FD-35 ^NAME KIWICALC ^PART-NUMBER S-CA-9200 ^PRINTNAME KiwiCalc Spreadsheet Software ^PRI CE 29.95 ^IS-EXPANDED YES)

      #39 71 [MODIFY-SOFTWARE-MEDIA:35-CHEAPEST] (KIWOS ^MEDIA-TYPE FD-35 ^NAME KI WOS ^PART-NUMBER S-OS-9200 ^PRINTNAME KIWOS Operating System ^PRICE 9.95 ^IS-EXPANDED YES)

 

Modifying Working Memory

If working memory contains incorrect information, the rules in a program might not execute as you anticipate. You can modify working memory by:

  • Creating objects
  • Copying objects
  • Deleting objects
  • Changing the values in existing objects

Creating Working-Memory Objects

You can create a new object by using the MAKE command with an object class name. You can optionally specify attributes with constant values or the COMPOUND function with constant arguments. The following command creates an object with the class name INPUT-THING and a value for its ^ITEM attribute.

    RuleWorks>make input-thing ^item keyboard

The object could be displayed as follows:

    #18 20 [RUL] (INPUT-THING ^ITEM KEYBOARD)

Because the object was created by a command, the atom RUL is used instead of the name of a rule that set the time-tag.

Copying Working-Memory Objects

You can make a new copy of an existing object by using the COPY command with an INSTANCE-ID. You can optionally specify attributes with values. The following command creates another object of class FD-35 with a different attribute value:

    RuleWorks>copy #36 ^price 119.95

    RuleWorks>ppwm fd-35 ^price 119.95

      #45 63 [RUL] (FD-35 [RUL] ^TAKES-SLOT YES ^NAME FD-35 ^PART-NUMBER FD-35 ^ PRINTNAME 3.5" Floppy Disk Drive ^PRICE 199.95 ^IS-EXPANDED YES )

RUL is placed in the fields that store the names of the rules that created the object and that last modified it. Note that both the INSTANCE-ID and the time-tag of the new object are different from the older object.

Changing the Class of Objects

You can change the class of an object from a parent class to a subclass with the SPECIALIZE command. For example:

    RuleWorks>ppwm #48

      #48 54 [RUL] (FLOPPY ^IS-EXPANDED NO ^IS-PLACED NO)

    RuleWorks>specialize #48 fd-5

    RuleWorks>ppwm #48

      #48 55 [RUL] (FD-5 ^IS-EXPANDED NO ^IS-PLACED NO)

    Note: The converted object's INSTANCE-ID does not change as a result of this action, but the time-tag does change. You can also change attribute values with this command.

Deleting Objects from Working Memory

The REMOVE command deletes objects from working memory. To delete specific objects, specify their INSTANCE-IDs. The following example deletes the objects whose identifiers are #20 and #63:

    RuleWorks>remove #20 #63

To delete all visible objects, specify the command with an asterisk (*). For example:

    RuleWorks>remove *

To delete all instances of an object class and its subclasses, use the REMOVE-EVERY command. For example:

    RuleWorks>remove-every input-thing

Changing the Values in Working-Memory Objects

To change one or more values in an object, use the MODIFY command with the INSTANCE-ID of the object whose atoms you want to change, and specify the attributes and their new values. Suppose, for example, working memory contains the following objects:

    RuleWorks>ppwm input-thing

      #16 17 [READ-LINE-ITEM:READ-AN-ITEM] (INPUT-THING ^ITEM HOME-KIWI)

      #17 19 [READ-LINE-ITEM:READ-AN-ITEM] (INPUT-THING ^ITEM MOUSE)

      #18 21 [READ-LINE-ITEM:READ-AN-ITEM] (INPUT-THING ^ITEM KIWINDOWS)

The following command changes the atom for the attribute ^ITEM of the object whose INSTANCE-ID is #16:

    RuleWorks>modify #16 ^item business-kiwi

The run-time system then changes that attribute and gives the object a new time-tag:

    RuleWorks>wm #16

      #16 22 [RUL] (INPUT-THING ^ITEM BUSINESS-KIWI)

Note that the INSTANCE-ID remains the same.

 

Displaying Match Information

By examining match information, you can detect whether condition elements are being matched correctly by WMOs. You can display match information for specific rules by using the MATCHES command.

Match information includes the INSTANCE-IDs and time-tags of objects that match CEs in the rules you specify. First, the command displays the name of the rule. Then the command lists the time-tags for the objects that match the first CE, the second CE, the first and second CEs, and so on. For example, consider the following rule:

    (rule choose-slots:place-memory

      (active-context ^name choose-slots)

      (box ^$ID <the-box> ^card-in-slot { [=] <len> [<] 6 })

      (memory ^$ID <the-mem> ^is-placed NIL ^takes-slot YES)

      -->

      (modify <the-box>

        ^card-in-slot [(<len> + 1)] memory

        ^card-in-slot-obj-id [(<len> + 1)] <the-mem>)

      (modify <the-mem> ^is-placed YES ^in-slot (<len> + 1)))

The following objects:

    RuleWorks>wm #27 #37 #38 #46

    #27 59 [EXPAND-PART-SKELETONS:BOX] (BOX ^NAME BOX ^PART-NUMBER KI-9200 ^PRINTNAME Kiwi-9200 CPU Base Unit ^PRICE 999.95 ^IS-EXPANDED YES)

    #37 54 [EXPAND-PART-SKELETONS:MEMORY] (MEMORY ^TAKES-SLOT YES ^NAME MEMORY-CARD ^PART-NUMBER MS-9200 ^PRINTNAME Kiwi-9200 Memory card ^PRICE 129.95 ^IS-EXPANDED YES)

    #38 53 [EXPAND-PART-SKELETONS:MEMORY] (MEMORY ^TAKES-SLOT YES ^NAME MEMORY-CARD ^PART-NUMBER MS-9200 ^PRINTNAME Kiwi-9200 Memory card ^PRICE 129.95 ^IS-EXPANDED YES

    #46 60 [MAKE-CONTEXT-ACTIVE] (ACTIVE-CONTEXT ^NAME CHOOSE-SLOTS))

And the following MATCHES command:

    RuleWorks>matches choose-slots:place-memory

      >>> CHOOSE-SLOTS:PLACE-MEMORY (<<<) *** matches for 1 ***

      #46

      *** matches for 2 ***

      #27

      *** matches for 1 2 ***

      #46 #27

      *** matches for 3 ***

      #38

      #37

      *** complete instantiations ***

      #46 #27 #37

      #46 #27 #38

The first five lines of output show that the object whose INSTANCE-ID is #46 matches the first CE in the rule and the object whose INSTANCE-ID is #27 matches the second CE. These are called intraelement matches because each CE is considered individually. The next two lines show that the combination of these two objects matches the combination of the first and second CEs. This is called an interelement match.

The MATCHES command then displays the intraelement matches for the third CE, the objects whose INSTANCE-IDs are #37 and #38. Note that each match is displayed on a separate line.

Finally, the command displays the instantiations of the rule. Because two objects match one of the CEs, there are two instantiations.

Instantiations removed from the active conflict set by refraction are not included in the MATCHES output.

Match Information for Negated CEs

Negated CEs are represented in the match information by headers just like the headers for positive CEs. For example, the rule VERIFY-CONFIGURATION:MOUSE-PORT has two positive CEs and one negated CE:

    (rule verify-configuration:mouse-port

      (active-context ^name verify-configuration)

      (mouse)

      - (keyboard)

      -->

      (make error ^severity warning ^message |Missing mouse port|)

      (write (crlf) |Caution: You want a mouse, but you don't have a|

        (crlf) | mouse controller port, which is part of the keyboard|

        (crlf) | Fixup: adding a keyboard to your order.|

        (crlf)

      (make keyboard))

The match information for this rule is shown below:

    RuleWorks>matches verify-configuration:mouse-port

      >>> VERIFY-CONFIGURATION:MOUSE-PORT (<<<)

      *** matches for 1 ***

      #43

      *** matches for 2 ***

      #31

      *** matches for 1 2 ***

      #43 #31

      *** matches for 3 ***

      *** complete instantiations ***

      #43 #31

There is a complete instantiation of this rule in the conflict set (because) there is no match for the negated third CE.

Match Information for Interelement Variables

Interelement variables are bound in one CE and then used again in another CE. In match information, interelement variables result in fewer than expected matches for combinations of CEs, compared to the number of matches for individual CEs.

For example, suppose working memory contains the following objects:

    #26 42 (BOX)

    #28 65 (BOX ^CARD-IN-SLOT-OBJ-ID (COMPOUND #31)

    #31 64 (MEMORY ^IN-SLOT 1 ^IS-PLACED YES)

    #35 66 (MEMORY ^IN-SLOT 1 ^IS-PLACED YES)

    #39 69 (MEMORY ^IN-SLOT 2 ^IS-PLACED YES)

And the program contains this rule

    (rule display-memory-cards

      (memory ^$ID <mem> ^is-placed yes)

      (box ^$ID <box> ^card-in-slot-obj-id [+] <mem>)

      -->

      (write (crlf) box <box> contains memory card <mem>))

The following command displays the matches for this rule:

    RuleWorks>matches display-memory-cards

      >>> DISPLAY-MEMORY-CARDS (<<<) *** matches for 1 ***

      #31

      #35

      #39 *** matches for 2 ***

      #26

      #28 *** complete instantiations ***

      #31 #28 )

There are three intraelement matches for the first CE and two for the second CE, so you might expect six matches for the entire LHS. However, the interelement variable <MEM> limits the interelement matches to the combination of MEMORY #31 with BOX #28.

 

Displaying Conflict Set Information

The instantiations in the conflict set indicate which rules can be executed. You can display the entire contents of the conflict set or the instantiation of the next rule to be executed. The run-time system displays instantiations in the following format:

    rule-name #INSTANCE-ID-1 time-tag-1 #INSTANCE-ID-2 time-tag-2 ...

Displaying the Contents of the Conflict Set

The CS command displays the entire contents of the conflict set. For example:

    RuleWorks>cs

    .

    .

    .

     

    VERIFY-CONFIGURATION:KIWINDOWS-NEEDS-2-MEMORY-CARDS-FOUND-NONE #32 36 #29 33

    VERIFY-CONFIGURATION:APPLICATION-NEEDS-KIWOS #32 36 #29 33

    VERIFY-CONFIGURATION:APPLICATION-NEEDS-KIWOS #32 36 #27 31

    VERIFY-CONFIGURATION:NEED-DISK #32 36

    VERIFY-CONFIGURATION:NEED-OUTPUT #32 36

    VERIFY-CONFIGURATION:NEED-MEMORY #32 36

To display the instantiation of the next rule the run-time system will execute, use the NEXT command. For example:

    RuleWorks>next

    VERIFY-CONFIGURATION:KIWINDOWS-NEEDS-2-MEMORY-CARDS-FOUND-NONE #32 36 #29 33

This shows that the next rule the run-time system will execute is VERIFY-CONFIGURATION:KIWINDOWS-NEEDS-2-MEMORY-CARDS-FOUND-NONE. The rule will be executed with its CEs matched by the objects whose INSTANCE-IDs are #32 and #29.

 

Displaying Trace Information

The RuleWorks run-time system displays trace information while executing a program. Trace information can be enabled for entry blocks (EB), rule groups (RG), rules, working memory (WM), and the conflict set (CS).

Setting the Trace Level

To set the trace level, specify the TRACE command with the keyword ON or OFF and the type of information you want traced or not. The following table shows the valid keywords for the TRACE command. The default setting is OFF *.

Table 9-3. Trace Keywords

NameTrace Information Affected
ENTRY-BLOCK
EB
Entry blocks entered and exited
RULE-GROUP
RG
Rule group containing rule that just fired
RULERule firing counts and name of rule that just fired
WMChanges to working memory
CSChanges to the conflict set
.All trace information

For example, if you want the system to display as much trace information as possible, you can list all the keywords or use the asterisk (*):

    RuleWorks>trace on eb rg rule wm cs

    or

    RuleWorks>trace *

Displaying the Current Trace Level

To display the current trace level, use the TRACE command without an argument. For example:

    RuleWorks>trace

      TRACE set on: ENTRY-BLOCK RULE-GROUP RULE WM C

Tracing Entry Blocks

The TRACE ON EB command causes trace messages to be generated upon entering an entry block (before any ON-ENTRY actions are executed) and upon exiting (after any ON-EMPTY or ON-EXIT actions are executed).

The trace output for entry blocks includes the name of the entry block. Trace output for entry blocks starts in column one. All other trace messages are indented. The following example shows sample trace output on entry blocks in italic type.

    Note: The output of the following four examples are taken from a telephone directory program that uses the similarity predicate to find names that sound alike.

Example 9-1. Tracing Information on Entry Blocks

    RuleWorks>trace on eb

    RuleWorks>run

    Name to look up: RuleWorks>stefan pelican

    -->Entry-Block: LOOKUP_PHONE_NUMBER

    Could not find any likely matches for stefan pelican.

    <--Entry-Block: LOOKUP_PHONE_NUMBER

     

    Name to look up: stefan polocave

    -->Entry-Block: LOOKUP_PHONE_NUMBER

    Found one potential match for stefan polocave.

    The number for Steve Polikoff is 555-5391.

    <--Entry-Block: LOOKUP_PHONE_NUMBER

Tracing Rule Groups

The TRACE RG command causes trace messages to be generated whenever the rule group that contains the firing rule is different from the rule group that contains the previously fired rule. The trace output for rule groups contains the name of the rule block or entry block that contains the rule group, as well as the name of the rule group itself. The system displays this information in the following format:

    RULE-GROUP: rule-group-name [in rule-block-name] in entry-block-name

Tracing Rules

The TRACE RULE command causes a trace message to be generated each time the system executes a rule. Trace output for rule firings contains the following information:

  • The global rule-firing count (total number of recognize-act cycles in the program)
  • The local rule-firing count (number of recognize-act cycles in this invocation of the active entry block)
  • The name of the rule executed
  • The INSTANCE-IDs and time-tags of the objects that matched the rule's CEs, in order

The run-time system displays this information in the following format:

    global(local): rule-name #instance-id-1 time-tag-1 #instance-id-2 time-tag-2 ...

In the following example trace information for rules is shown in italic print.

Example 9-2. Trace Output for Rules

    RuleWorks>trace on eb rule

    RuleWorks>run

    Name to look up: konny oiljars

    -->Entry-Block: LOOKUP_PHONE_NUMBER

    1 (1): INIT-PHONE-BOOK #41 41

    2 (2): LAST-RESORT:PRINT-ALL-SIMILAR #42 42 #41 41 #30 30

    Could not find a probable match for konny oiljars

    but found potential matches

    ---->Entry-Block: PRINT_SIMILAR_NAMES

    3 (1): PRINT-ALL-WITH-SIMILAR-LAST-NAME #65 65 #30 30

    Connie Olegarz

    <---Entry-Block: PRINT_SIMILAR_NAMES

    <---Entry-Block: LOOKUP_PHONE_NUMBER

Tracing Working Memory

When the trace level includes WM, the run-time system displays changes to working memory (that is, objects created, changed, or deleted). The system displays the following information for each object:

  • Its INSTANCE-ID
  • Its time-tag
  • The name of the rule that added, changed, or deleted it
  • Its attributes and their values

The system displays working memory trace information in the following format:

    #INSTANCE-ID time-tag [rule-name] (class-name attr-1 value-1 attr-2 value-2 ...)

Each line of a working memory trace output is preceded by a symbol that indicates the nature of the change as shown in the following table.

Table 9-4. Working Memory Trace Output Symbols

SymbolMeaning
=>WM:Object added to working memory
<=WM:Object deleted from working memory

When an object is modified or specialized, the system displays two lines of output: the first shows the old version being deleted, the second shows the new version being added. The INSTANCE-ID, of course, does not change.

In the case of a SPECIALIZE action, the attribute changed is ^$INSTANCE-OF.

In the following example, trace output for working memory changes is shown in italic print.

Example 9-3. Trace Ouput for Working Memory

    RuleWorks>trace on eb rule wm

    RuleWorks>run

      Name to look up: Jenny Baker

      -->Entry-Block: LOOKUP_PHONE_NUMBER

      =>WM: #65 65 [ON-ENTRY] (REQUEST ^FIRST-NAME |Jenny| ^LAST-NAME |Baker|)

      3 (1): LAST-RESORT:PRINT-ALL-SIMILAR #42 42 #65 65 #3 3

       

      Could not find a probable match for Jenny Baker but found potential matches --

      -->Entry-Block: PRINT_SIMILAR_NAMES

      =>WM: #66 66 [ON-ENTRY] (REQUEST ^LAST-NAME |Baker|)

      4 (1): PRINT-ALL-WITH-SIMILAR-LAST-NAME #66 66 #3 3

       

      Ginny Baccer

      <--Entry-Block: PRINT_SIMILAR_NAMES

      <=WM: #66 66 [ON-ENTRY] (REQUEST ^LAST-NAME |Baker|)

      <--Entry-Block: LOOKUP_PHONE_NUMBER

      <=WM: #65 65 [ON-ENTRY] (REQUEST ^FIRST-NAME |Jenny| ^LAST-NAME |Baker|)

When all visible objects are deleted (for example, in a RESTORESTATE or REMOVE * action), the system displays: <=WM: ** All Objects Removed **

Tracing the Conflict Set

When the trace level includes CS, the run-time system displays the instantiations added to and deleted from the conflict set. The system displays the following information for each instantiation:

  • The name of the rule for which it was added or deleted
  • The INSTANCE-IDs and time-tags of the objects that match the rule's LHS

The system displays conflict set trace information in the following format:

    rule-name #INSTANCE-ID-1 time-tag #INSTANCE-ID-2 time-tag-2

Each line of conflict set trace output is preceded by a symbol that indicates whether the instantiation was added to or deleted from the conflict set:

Table 9-5. Trace Output Symbols

SymbolMeaning
=>CS:Instantiation added to conflict set
<=CS:Instantiation deleted from conflict set

In the following example, trace output about the conflict set is shown in italic print.

Example 9-4. Trace Ouput for The Conflict Set

    RuleWorks>trace on eb rule wm cs

    RuleWorks>run

    Name to look up: RuleWorks>Anne Beauchant

    -->Entry-Block: LOOKUP_PHONE_NUMBER

    =>WM: #69 69 [ON-ENTRY] (REQUEST ^FIRST-NAME |Anne| ^LAST-NAME |Beauchant|

    =>CS: LAST-SIMILAR-AND-FIRST-SIMILAR #44 44 #69 69 #2 2

    =>CS: LAST-RESORT:PRINT-ALL-SIMILAR #42 42 #69 69 #2 2

    =>CS: LAST-RESORT:NO-MATCHES-AT-ALL #42 42 #69 69

    7 (1): LAST-SIMILAR-AND-FIRST-SIMILAR #44 44 #69 69 #2 2

    Found a possible match for Anne Beauchant

    . The number for Ann Bachant is 555-5619.

    <--Entry-Block: LOOKUP_PHONE_NUMBER

    <=WM: #69 69 [ON-ENTRY] (REQUEST ^FIRST-NAME |Anne| ^LAST-NAME |Beauchant|)

When all conflict set elements are deleted, the system displays:

    <=CS: ** All CS Entries Removed **

 

Saving and Restoring Program State

If you are debugging a RuleWorks program and you need to stop execution to do something else, you might want to save the state of working memory and the conflict set as it exists at that time. Or, you might want to save a certain state so that you can rerun from that point many times. By using RuleWorks commands you can save the state to a file and then restore it later.

SAVESTATE Command

You can copy the state of visible working memory and the active conflict set to a file by using the SAVESTATE command. The following command copies the state of working memory and the conflict set to the file MY_SAVE.DAT:

    RuleWorks>savestate my_save.dat

    Note: The state of user-defined external routines and open files is not saved by the SAVESTATE command and thus cannot be restored with the ADDSTATE or RESTORESTATE command.

RESTORESTATE Command

The RESTORESTATE command clears and restores visible working memory and the active conflict set to the state recorded in a file produced by the SAVESTATE command. Suppose you used the SAVESTATE command to copy the state of working memory and the conflict set to the file MY_SAVE.DAT. The following command restores working memory and the conflict set to the state recorded in the file MY_SAVE.DAT:

    RuleWorks>restorestate my_save.dat

The RESTORESTATE command:

  • Clears visible working memory
  • Clears the active conflict set
  • Restores working memory from the saved state Saved WMOs that are not visible to the active entry block are ignored.
  • Restores the conflict set from the saved state

    Saved conflict set information that does not pertain to the active entry block is ignored.

The RESTORESTATE command automatically performs ID translation on any INSTANCE-ID values stored in attributes of the saved WMOs. That is, if you use IDs as pointers the relationships among saved WMOs are maintained. (See the description of rul_start_id_translation in Chapter A for details on ID translation.)

ADDSTATE Command

    RuleWorks>addstate my_save.dat

The ADDSTATE command:

  • Adds the objects in the saved state to visible working memory Saved WMOs that are not visible to the active entry block are ignored.
  • Adds the instantiations arising from the objects it just made to the active conflict set

    Saved instantiations that do not pertain to the active entry block are ignored.

Unlike the RESTORESTATE command, the ADDSTATE command does not delete any existing WMOs before creating new ones from the saved file. Like the RESTORESTATE command, ADDSTATE automatically performs ID translation on the saved WMOs (see rul_start_id_translation in Chapter A for details).

© RuleWorks.co.uk | | Sitemap