API Reference
Professional Edition
API Reference |
|
ARulesXL rulesets can be run in a variety of languages and tools outside of Microsoft Excel. They can be deployed in Web servers under JSP/Servlets or ASP.NET. They can also be embedded in applications written in C++, Java, Delphi, Visual Basic and C#.
In each language environment, there is an 'ARulesXL' class with associated methods. Most of the methods are common across all environments. However, for ease of programming, there are a handful of language-specific, higher-level classes to transfer data to and get answers from ARulesXL and higher-level language constructs (such as collections and string lists).
The methods are detailed below.
The default method for runtime licensing is for the ARulesXL runtime to silently register itself over the Internet. It will try to do this five times without any prompting of the user. If it fails, it will prompt the user five more times to connect to the Internet.
You can manually control this process by calling the RegisterRuntime API method.
Another method, which is not available in the public release, is a runtime that will only work with your rule sets. Contact us to license this method or for other distribution and private labelling options.
Starting/Stopping the ARulesXL Engine
Loading Data into Ruleset Facts, Vectors and Tables
Querying Rulesets
Miscellaneous
Description:
AddObject(STRING ruleset, STRING objectname, STRING/INTEGER value)
Remarks:
Adds or replaces a simple fact with a single value. The value can be an ARulesXL type including: date, time, era, number or string.
Return Value:
Throws an exception on failure.
Example:
arxl.AddObject("PriceRules", "quantity", "1")
Description:
AddToTable(STRING ruleset, STRING objectname, STRING/INTEGER rowname, STRING/INTEGER colname, STRING/INTEGER value)
Remarks:
Adds data to an existing or previously cleared table. You must call
CleaRArray()first.The row and column indices can be text or numeric, but they are always passed as a string. Similarly the value can be an ARulesXL type including: date, time, era, number or string. You can intermix types for the same indices.
Return Value:
Throws an exception on failure.
Example:
arxl.CleaRArray('CommonRules', 'raw_vaccination');
for i := 1 to VaccineList.RowCount-1 do
begin
s := VaccineList.Cells[0, i];
Str(i, idx);
arxl.AddToTable('CommonRules', 'raw_vaccination', idx, 'Vaccination', s);
s := VaccineList.Cells[1, i];
arxl.AddToTable('CommonRules', 'raw_vaccination', idx, 'Date', s);
end;
Description:
AddToVector(STRING ruleset, STRING objectname, STRING/INTEGER rowname, STRING/INTEGER value)
Remarks:
Adds data to an existing or previously cleared vector (a one-dimensional table). You must call ClearVector() first.
The row index can be text or numeric, but it is always passed as a string. Similarly the value can be an ARulesXL type including: date, time, era, number or string. The row index is any value you want to use as the index for the vector. So if the object name is .data and the index is '1', you can access the value with .data[1]. Similarly if the index is 'blue', you can access the value with .data[blue]. You can intermix types in the same vector.
Return Value:
Throws an exception on failure.
Example:
'Load the user inputs, first clear the .in vector, then load it up
arxl.ClearVector("ShaftRules", ".in")
arxl.AddToVector("ShaftRules", ".in", "Favor", Favor.SelectedValue)
arxl.AddToVector("ShaftRules", ".in", "Swing Speed", SwingSpeed.Text)
arxl.AddToVector("ShaftRules", ".in", "Club Type", ClubType.SelectedValue)
arxl.AddToVector("ShaftRules", ".in", "Ball Flight", BallFlight.SelectedValue)
After running the above code, the rules in "ShaftRules" can refer to the values .in[Favor], .in['Club Type'], etc.
Description:
CleaRArray(STRING ruleset, STRING objectname)
Remarks:
Clears the values in a table (generally loaded using
RArray()) so that new values can be loaded.
Return Value:
Throws an exception on failure.
Example:
arxl.CleaRArray('CommonRules', 'raw_vaccination');
for i := 1 to VaccineList.RowCount-1 do
begin
s := VaccineList.Cells[0, i];
Str(i, idx);
arxl.AddToTable('CommonRules', 'raw_vaccination', idx, 'Vaccination', s);
s := VaccineList.Cells[1, i];
arxl.AddToTable('CommonRules', 'raw_vaccination', idx, 'Date', s);
end;
Description:
ClearVector(STRING ruleset, STRING objectname)
Remarks:
Clears the values in a vector (generally loaded using
RArray()) so that new values can be loaded.
Return Value:
Throws an exception on failure.
Example:
'Load the user inputs, first clear the .in vector, then load it up
arxl.ClearVector("ShaftRules", "in")
arxl.AddToVector("ShaftRules", "in", "Favor", Favor.SelectedValue)
arxl.AddToVector("ShaftRules", "in", "Swing Speed", SwingSpeed.Text)
arxl.AddToVector("ShaftRules", "in", "Club Type", ClubType.SelectedValue)
arxl.AddToVector("ShaftRules", "in", "Ball Flight", BallFlight.SelectedValue)
Description:
CloseRules()
Remarks:
Closes and frees the ARulesXL engine. It is also called by the Dispose() method of the class (if there is one).
Return Value:
Throws an exception on failure.
Example:
arxl.CloseRules()
Description:
GetLS()
Remarks:
Returns the Amzi! Logic Server used internally in ARulesXL. This is for advanced users who want to make use of the full Amzi! Logic Server API to query and parse results in ARulesXL.
The Logic Server object is implemented in arules.dll (not amzi.dll as you may be accustomed to). It is identical to amzi.dll from the programming interface point of view. However, amzi.dll cannot be used to run ARulesXL rulesets due to internal differences between the two libraries.
Return Value:
A LogicServer object .
Example:
LogicServer ls = arxl.GetLS()
Description:
OpenRules(STRING rulesetfile, STRING arulespath)
Remarks:
Loads the ARulesXL engine from arulespath and the named rulesetfile.
For IIS, the rulesetfile must be located in the bin subdirectory of your IIS directory.
Return Value:
Throws an exception on failure.
Example:
'Determine where we are path = Request.PhysicalApplicationPath + "bin\" 'Load the ARulesXL engine and ruleset file arxl.OpenRules(path + RulesetFilename.Text, path)
Description:
STRING QueryRules(STRING ruleset, STRING query)
Remarks:
Queries the named ruleset and returns the result as a string.
Return Value:
The result of the query as a string.
Throws an exception on failure.
Example:
ans = arxl.QueryRules(Ruleset.Text, "FIND advice")
Description:
STRING QueryRules(STRING ruleset, STRING query)
Remarks:
Queries the named ruleset and returns the result as a string. This call differs from QueryRules() because any values that were found during prior queries are retained. This lets you query the same ruleset repeatedly gaining new information each time, instead of having to compute the values for all the objects each time.
Return Value:
The result of the query as a string.
Throws an exception on failure.
Example:
ans = arxl.QueryMore(Ruleset.Text, "FIND explanation")
Description:
INTEGER ARulesRegisterRuntime(DWORD Method, STRING ProxyNames, STRING RuntimeID)
Remarks:
Registers this copy of the ARulesXL runtime on www.arulesxl.com using HTTP.
Method is the access type for the Microsoft Windows SDK function, InternetOpen(). The values from wininet.h are:
INTERNET_OPEN_TYPE_DIRECT Resolves all host names locally. INTERNET_OPEN_TYPE_PRECONFIG Retrieves the proxy or direct configuration from the registry. INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY Retrieves the proxy or direct configuration from the registry and prevents the use of a startup Microsoft JScript or Internet Setup (INS) file. INTERNET_OPEN_TYPE_PROXY Passes requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function uses INTERNET_OPEN_TYPE_DIRECT. ProxyNames is a list of one or more proxy servers. The Microsoft documentation on 'Listing Proxy Servers' for InternetOpen() says:
"WinINet recognizes two types of proxies: CERN type proxies (HTTP only) and TIS FTP proxies (FTP only). If Internet Explorer is installed, WinINet also support SOCKS type proxies. InternetConnect assumes, by default, that the specified proxy is a CERN proxy. If the access type is set to INTERNET_OPEN_TYPE_DIRECT or INTERNET_OPEN_TYPE_PRECONFIG, the lpszProxyName parameter of InternetOpen should be set to NULL. Otherwise, the value passed to lpszProxyName must contain the proxies in a space-delimited string. The proxy listings can contain the port number that is used to access the proxy.
To list a proxy for a specific protocol, the string must follow the format ""<protocol><protocol>://<proxy_name>"". The valid protocols are HTTP, HTTPS, FTP, and Gopher. For example, to list an FTP proxy, a valid string would be ""ftp=ftp://ftp_proxy_name:21"", where ftp_proxy_name is the name of the FTP proxy and 21 is the port number that must be used to access the proxy. If the proxy uses the default port number for that protocol, the port number can be omitted. If a proxy name is listed by itself, it is used as the default proxy for any protocols that do not have a specific proxy specified. For example, ""http=http://http_proxy other"" would use http_proxy for any HTTP operations, while all other protocols would use other.
By default, the function assumes that the proxy specified by lpszProxyName is a CERN proxy. An application can specify more than one proxy, including different proxies for the different protocols. For example, if you specify ""ftp=ftp://ftp-gw gopher=http://jericho:99 proxy"", FTP requests are made through the ftp-gw proxy, which listens at port 21, and Gopher requests are made through a CERN proxy called jericho, which listens at port 99. All other requests (for example, HTTP requests) are made through the CERN proxy called proxy, which listens at port 80. Note that if the application is only using FTP, for example, it would not need to specify ""ftp=ftp://ftp-gw:21"". It could specify just ""ftp-gw"". An application is only required to specify the protocol names if it is using more than one protocol per handle returned by InternetOpen."
RuntimeID is a string that is recorded on the ARulesXL website to identify this particular user when you request a report of registered runtime licenses. It is limited to 1024 characters. If none is provided, the default is the 8-digit hardware fingerprint for the PC using the ARulesXL runtime.
This functions registers this PC's use of the ARulesXL runtime on the ARulesXL website. You can call this function anytime after the rule set has been opened with OpenRules(). It returns immediately if the registration has already been successfully completed.
If you do not call this function, the ARulesXL engine will attempt to register this instance via the first two methods silently the first five times OpenRules() is called. From the 6th through 10th times, the user will be informed that this software must connect to the Internet to continue working. After the 11th time, the ARulesXL engine will no longer operate.
Return Value:
0 for success.
-1 if unable to connect to the website and/or read any results back.
1 if your ARulesXL license key is not found in the database on the ARulesXL web server. Contact us to remedy this problem.
2 if you have exceeded your limit of runtime licenses. Contact us to purchase more runtime licenses for your current license key.
Example:
ecode = ARulesRegisterRuntime(INTERNET_OPEN_TYPE_PRECONFIG, "", authorid, "automatic");
if (ecode == 0) {
if (!silent)
MessageBox(NULL, X(2)->getStr(), aS("ARulesXL"), MB_OK);
return TRUE;
}
// Then the next method
ecode2 = ARulesRegisterRuntime(INTERNET_OPEN_TYPE_DIRECT, "", authorid, "automatic");
if (ecode2 == 0) {
if (!silent)
MessageBox(NULL, X(2)->getStr(), aS("ARulesXL"), MB_OK);
return TRUE;
}
|
Copyright ©2005-7 Amzi! inc. All Rights Reserved.
|