Extend MODL Interface Professional Edition

Installation

The Extend MODL is used to add reasoning capabilities to Extend models. It consists of 6 files. The first 5 files are in the arulesxl\api\bin_redist directory. The last 2 files are in the arulesxl\api\modl directory.

• arulesrt.cfg — The ARulesXL engine configuration file.
• arulesrt.dll, ar_mysqlrt.lsx, ar_osutilsrt.lsx, arulesrt.xpl —The ARulesXL engine
• arulesmodl.dll — The interface DLL between MODL and ARulesXL.
• arules.h — The include file for the MODL interface that is included into a library.

To use the MODL interface, put all of the above files in the Extend\extensions directory.

API Additions & Changes

MODL uses the Extend DLL application programming interface (API). As a result, the API calls differ in these ways:

• InitRules() must be called once before any calls to OpenRules().
• Every function except OpenRules() takes an ARulesXL identifier as the first parameter. (OpenRules() returns that identifier.)
• All of the functions return an integer error code where 0 means no error and any other value describes the error.
• Parameters are not overloaded, so there is one function for each data type instead of a single function that accepts different data types as parameters. For example, instead of the AddObject() function, there are AddDoubleObject(), AddLongObject() and AddStringObject().

Error Codes

The most common error codes are:

• 205 Value is not a string
• 206 Value is not an integer/long
• 207 Value is not a floating point/double
• 211 Value is not a list

These error codes usually occur when calling QueryRulesTo___ and the result of the query does not match the type returned by the function. You can test your queries directly in Excel using RQuery(). Alternatively, you can enable tracing in the arulesrt.cfg file. To do this remove the pound sign (#) in front of these lines:

apitrace = on
logfile = c:\arulestrace.log   

If you look in the log file you will see the queries and the results returned.

AddObject

Description:

integer AddDoubleObject(long arxl, string ruleset, string objectname, double value)
integer AddLongObject(long arxl, string ruleset, string objectname, long value)
integer AddStringObject(long arxl, string ruleset, string objectname, string value)

Remarks:

See AddObject()

Return Value:

An error code, where 0 means success.

AddToTable

Description:

integer AddDoubleToTable(long arxl, string ruleset, string objectName, string rowname, string colname, double value)
integer AddLongToTable(long arxl, string ruleset, string objectName, string rowname, string colname, long value)
integer AddStringToTable(long arxl, string ruleset, string objectName, string rowname, string colname, string value)

Remarks:

See AddToTable()

Return Value:

An error code, where 0 means success.

AddToVector

Description:

integer AddDoubleToVector(long arxl, string ruleset, string objectname, string rowname, double value)
integer AddLongToVector(long arxl, string ruleset, string objectname, string rowname, long value)
integer AddStringToVector(long arxl, string ruleset, string objectname, string rowname, string value)

Remarks:

See AddToVector()

Return Value:

An error code, where 0 means success.

InitRules

Description:

InitRules()

Remarks:

InitRules() must be called before OpenRules(), and initializes the ARulesXL module by loading external code in DLLs.

Return Value:

None.

LoadVectorFromArray

Description:

integer LoadVectorFromDoubleArray(long arxl, string ruleset, string objectname, double values[])
integer LoadVectorFromLongArray(long arxl, string ruleset, string objectname, long values[])

arxl

The ARulesXL identifier from OpenRules

ruleset

The name of the ruleset where the table fact is defined

objectname

The name of the fact

values

A single-dimension array containing the data to add

Remarks:

Replaces all data in a new or existing vector (a one-dimensional table) with the values given.

Return Value:

An error code, where 0 means success.

Example:

double ar[3];
integer arxl;
integer rc;

InitRules();
arxl = OpenRules("c:\Extend6LT\pricing.axl", "C:\Extend6LT\Extensions\");
ar[0] = 1;
ar[1] = 2.345;
ar[2] = 0.345678e20;
rc = LoadVectorFromDoubleArray(arxl, "PriceRules", "ar", ar);

OpenRules

Description:

long OpenRules(string rulesetfile, string arulespath)

Remarks:

See OpenRules().

InitRules() must be called before OpenRules().

Return Value:

The ARulesXL identifier that is passed to all subsequent functions.

QueryRules

Description:

integer QueryRulesToDouble(long arxl, string ruleset, string query, double out[])
integer QueryRulesToLong(long arxl, string ruleset, string query, long out[])

Remarks:

See QueryRules().

Return Value:

An error code, where 0 means success. The last parameter is an array of length 1 where the result of the query is returned.

QueryRulesToVector

Description:

integer QueryRulesToDoubleVector(long arxl, string ruleset, string query, long count[], double out[])
integer QueryRulesToLongVector(long arxl, string ruleset, string query, long count[], long out[])

Remarks:

See QueryRules().

Returns a list of values from a query into a double or long array. Will return all the items in the list if the array is large enough to contain them, otherwise just fills the array.

Return Value:

An error code, where 0 means success. The count parameter is an array of length 1 where the number of items in the list is returned. The out parameter is an array where the values of the list are returned in order.

QueryMore

Description:

integer QueryMoreToDouble(long arxl, string ruleset, string query, double out[])
integer QueryMoreToLong(long arxl, string ruleset, string query, long out[])

Remarks:

See QueryMore().

Return Value:

An error code, where 0 means success. The last parameter is an array of length 1 where the result of the query is returned.

Sample

Building the Sample

Before running the sample, you need to create and copy files into the Extend program directories:

1. In the api\modl\samples\pricing directory, open 'PhoneCallPricing.xls' in Excel. Select ARulesXL | Export to create phonecallpricing.axl. Copy that file to your Extend\Extensions directory.
2. Copy 'ARulesXLDemo.lix' to your Extend\Libraries directory.

Running the Sample

To run the sample:

1. Open 'PhoneCallPricingDemo.mox' in Extend.
2. Right-click on the 'Call Price' block and select 'Open Dialog'. On the 'Paths' tab, make sure the pathname of the Extend\Extensions directory is entered correctly.
3. Play the model and watch the calls being priced.

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.