Reference

Top     Installation     Introduction     Samples     Tutorial     Reference     Release Notes

Debugging Rule Sets

Sometimes a rule set does not work as expected. The trace facility allows you to step through the rule engine's reasoning process to see exactly how the rules and data are being used.

The trace facility is also an excellent tool for learning exactly how a rule reasoning engine works.

Trace

To start the trace:

• Select a cell with an =RQuery() function call, and select ARulesXL | Trace Query from the menu
  or
• Right-click on a cell with an =RQuery() function call, and select Trace Query from the menu

The trace then starts with:

• A pop-up menu with the Trace controls, and
• A new workbook/worksheet that will contains the trace user interface.

(See the Tutorial for screen images.)

The buttons on the Trace menu are:

• Step - step into the reasoning process.
• Skip - skip the details for this reasoning step; and/or skip out of the current reasoning step.
• Run - run to the end of query. Note that you will have to hit End to see the final results.
• End - end the reasoning process, report on the status at the time of ending.
• Help - Displays this documentation.

Directions on how to use the trace appear at the top of the Trace worksheet.

The output on the worksheet is divided into three sections:

• Headers - contain the Trace title, a line of instructions on the options available, and the query being traced.
• Actions - the current active steps in the reasoning process.
• Knowns - the property values that have been derived at this point in the reasoning, and the source of those values.

The trace actions are organized in a number of layers of detail:

Find Found	Seeking the value of an property.
Try Succeed Fail Retry	Applying rules that will find the value of an property. The rule is echoed on the Trace worksheet.
Findall Foundall	Indicates the reasoning engine is entering or exiting a findall, which means it will be searching for all possible answers for goals within the Findall.
Known Data	Indicates a property value is already known, or was input as data in RCell() or RArray().
Test Match Yes No	Trying a test in the When clause of a rule (ex. .Quantity > 20). Match indicates a test which is really setting the value of a pattern-matching variable (ex. ?p = .part).
Try Succeed Fail Retry	For logic predicates. In these cases the value is the pattern of the left side of the logic predicate (ex. member(?H23, [ apple, pear, plum] ).

Pattern matching variables in a rule, such as ?x or ?part, do NOT get displayed in the trace with their original names. Instead they are displayed with an internal name, such as ?H234.

Certain functions that call back to Excel cannot be used during trace; these include EVALUATE(), ASK(), MSGBOX().

The Skip control button for the trace causes the trace to skip until a pair of trace outputs are matched. For example, a skip given at a Find will run until the corresponding Found. Similarly for Try and Findall.

Formatting the Trace Spreadsheet

You can change the location, size and format of the trace spreadsheet, for example, the you can widen the columns. Your changes will be used during the remainder of the trace. The format is also saved in a file named 'ARulesXL Trace.xls' in the same directory as your spreadsheet. That file will be used the next time you start a trace on any spreadsheet in that directory. This allows you to save your format changes across Excel sessions.

Trace Log File

The file 'arulesxl trace.txt' contains a full text transcript of the most recent trace. It is in the same directory as the workbook being traced. The format is semi-colon delimited with the fields corresponding to the columns of the Trace worksheet. You can open it into an Excel worksheet with the Open Trace Log File command.

You can use this to go over the full reasoning process, and also to send to technical support in case of difficulties.

Diagnostic Messages

Sometimes the simplest way to find a logic error in rules is to use the MSGBOX() function to generate diagnostic messages. For example, if the simple pricing rules were not working, maybe the problem was the input quantity. The rules could be modified to check this theory as follows:

price = 10 WHEN MSGBOX(quantity) AND quantity > 20
price = 15 WHEN MSGBOX(quantity) AND quantity <= 20

The special value, call_stack, can be used to get the value of the call stack as a string for display. For example, if quantity should never be negative, but somehow it is, this rule could be used to find out why.

price = 0 WHEN quantity < 0 AND MSGBOX( "Negative quantity at: "    & call_stack)

Common Errors

These errors commonly occur when building rule sets.

• Stack Overflow — This message occurs when the ARulesXL control stack overflows. In indicates the program has a very deep reasoning tree. Usually this is caused by circular reasoning in the rules, that is a rule that depends on another rule which depends on the first rule. If the error isn't obvious, the debugger can be used to trace execution. It will show the error. The easiest way is to simply tell the debugger to run. Since it is generating diagnostics, it might take a while, but when it is finished it will show you the control stack error and what it was trying to do before getting the error. You should see the circular logic.
  
  It is possible the application really requires a deeper stack. In that case, edit the arules.cfg file in your ...\Microsoft Office\...\Library\ directory. Remove the # in front of the 'control stack' parameter and put in a larger number. Restart Excel & ARulesXL.
  
  
• Parse Error — Parsing errors are due to syntax errors in rules. The error message gives a hint as to where the parser was confused, but the error could be earlier. Typical errors involve use of the wrong brackets, square or parentheses, or missing dots in front of properties, or non quoted text values with embedded spaces.

Copyright ©2005-7 Amzi! inc. All Rights Reserved. ARulesXL and Amzi! are trademarks or registered trademarks of Amzi! Microsoft and Excel are trademarks or registered trademarks of Microsoft Corporation.