EigenvectorTools: Difference between revisions
imported>Jeremy |
imported>Jeremy |
||
Line 125: | Line 125: | ||
====Visual Basic==== | ====Visual Basic with ETV6==== | ||
The following is an example of instancing the EigenvectorToolsV6 interface in Visual Basic. This demonstrates how to make calls to Solo or Solo_Predictor through EigenvectorToolsV6 object. To learn more about the scripting format (the "tosend" string included below), see the [[Solo Predictor Script Commands Summary]] and [[Solo_Predictor_Script_Construction#Scripting_Examples|Scripting Examples]] pages. | The following is an example of instancing the EigenvectorToolsV6 interface in Visual Basic. This demonstrates how to make calls to Solo or Solo_Predictor through EigenvectorToolsV6 object. To learn more about the scripting format (the "tosend" string included below), see the [[Solo Predictor Script Commands Summary]] and [[Solo_Predictor_Script_Construction#Scripting_Examples|Scripting Examples]] pages. | ||
To instance the ETV6 object, you must add a reference to the EigenvectorToolsV6 object in your project in Visual Studio. | |||
<pre> | <pre> | ||
Dim | Dim solo As EigenvectorToolsV6.application | ||
Set | Set solo = New EigenvectorToolsV6.application | ||
Dim tosend As String 'string to hold message we're sending | Dim tosend As String 'string to hold message we're sending | ||
Line 137: | Line 139: | ||
Dim myresp As String 'string to hold response from server | Dim myresp As String 'string to hold response from server | ||
solo.automation = True 'turn on automation | |||
solo.socket = False 'turn OFF sockets | |||
If | If solo.startApp Then | ||
''' Could not start V6 server | ''' Could not start V6 server | ||
''' -- usually throw some error -- | ''' -- usually throw some error -- | ||
Line 149: | Line 151: | ||
tosend = ":plain; model = 'mymodel.mat'; data = 'mydata.txt'; pred = data|model; pred.prediction;" | tosend = ":plain; model = 'mymodel.mat'; data = 'mydata.txt'; pred = data|model; pred.prediction;" | ||
status = | status = solo.sendCommand(tosend) | ||
If status = 0 Then | If status = 0 Then | ||
' Command successful | ' Command successful | ||
myresp = | myresp = solo.lastResponse | ||
myval = Val(myresp) ''convert to double (assumes only one value in myresp) | myval = Val(myresp) ''convert to double (assumes only one value in myresp) | ||
Line 159: | Line 161: | ||
' Server returned error | ' Server returned error | ||
myresp = "error code: " + Str(status) + vbCrLf + | myresp = "error code: " + Str(status) + vbCrLf + solo.lastResponse | ||
End If | End If | ||
End If | End If | ||
</pre> | </pre> | ||
====Visual Basic with ET.NET==== | |||
The above code will work for the ET.NET interface with two minor changes. First, select to add a reference, then browse to locate the EigenvectorTools.dll. Next, change the manner in which the solo object is instanced by changing the first two lines of code shown above to read: | |||
<pre> | |||
Dim solo As Eigenvector.application | |||
Set solo = New Eigenvector.application | |||
</pre> | |||
After this, all other references to the "solo" object will be identical. | |||
==Troubleshooting== | ==Troubleshooting== |
Revision as of 16:10, 10 March 2011
The EigenvectorTools suite comprises a number of libraries which can be used on Windows to connect to Eigenvector Research's stand-alone software packages like Solo and Solo_Predictor. There are two versions of these tools:
- EigenvectorToolsV6 : A standard Version 6 ActiveX object (referred to as "ETV6" in this document) written for best compatibility with older applications and those not wishing to run with Microsoft's .NET Framework. See the note below regarding limitations when using ETV6 on 64-bit operating systems.
- EigenvectorTools : A .NET object (referred to as "ET.NET") recommended for any managed code applications built using Microsoft's .NET framework 1.1 or higher (Visual Studio 2003, 2005, or later). Although ET.NET was written with COMInterop (i.e. allowing the .NET object to be accessed like a standard ActiveX object from older, non-managed code) but ETV6 is still the recommended object for use with these older platforms.
ETV6 and ET.NET both implement nearly identical interfaces into the main Solo application. The details of this interface are given below. ET.NET also includes socket communication and XML parsing tools which may be useful for some applications. These tools are not available in the ETV6 application.
Notes for use on 64-bit systems: Although either ETV6 or ET.NET can be used with the 32-bit versions of our products, ETV6 cannot be used with the 64-bit versions. If you need to use the ETV6 interface on a 64-bit system (for use with an older application, for example), it can only be used with the 32-bit versions of Eigenvector's products. To use this interface with our 64-bit products, you must use the ET.NET version of the interface. A compatibility table is given below.
Solo/Solo_Predictor | Solo/Solo_Predictor | |
---|---|---|
32-bit | 64-bit | |
32-bit Windows | ETV6 or ET.NET | n/a |
64-bit Windows | ETV6 or ET.NET | ET.NET |
Installation
- Download the version of Solo, Solo_Predictor or other stand-alone application which will be controlled by EigenvectorTools from your account at [http://download.eigenvector.com]
- Run the stand-alone application installer downloaded in the previous step. NOTE: This installation will include the option to add the product to the Windows system path. This step must be completed for EigenvectorTools to function. If the option is not available or not selected, please see the troubleshooting section. If multiple Eigenvector applications are installed on the same system, only the first one on the system path will be accessible through the EigenvectorTools interface.
- Download the EigenvectorTools application from your account at [http://download.eigenvector.com]
- Unzip the EigenvectorTools ZIP file into a new folder. This folder can be located anywhere convenient on your system. A folder named C:/Program Files/EVRI/EigenvectorTools is a reasonable default location.
- Using an account with administrative privileges, complete one of the two following steps depending on the version of EigenvectorTools you are installing:
- EigenvectorToolsV6: In the folder containing the EigenvectorToolsV6 application, drag the EigenvectorToolsV6.dll to the regsvr32.exe application.
- EigenvectorTools: In the folder containing the EigenvectorTools application, drag the EigenvectorTools.dll to the regasm.exe application. Then copy the EigenvectorTools.dll into a folder on your system path (such as the Solo or Solo_Predictor folder on your path) or into the folder in which the 3rd party application resides. See the Troubleshooting section below.
The EigenvectorTools application should now be ready for use. It can be tested by running one of the test applications:
- CPPExample/socketTester.exe to test EigenvectorTools only (not EigenvectorToolsV6) - Before running, copy the EigenvectorTools.dll into the CppExample folder.
- VBExample/VBsocketTester.exe to test EigenvectorTools or EigenvectorToolsV6.
Please see Troubleshooting section for assistance with installation and testing errors.
Application Interface
The primary object in both versions of EigenvectorTools is an application object. The object's interface implements several start-up properties and several methods. For ETV6, the base object is instanced by creating a new EigenvectorToolsV6.application object. For ET.NET, the base object is instanced by creating a new Eigenvector.application object. Note that the ET.NET version also has two other objects (socketClient and numericParser) which can be instanced using the same namespace (Eigenvector.socketClient and Eigenvector.numericParser).
Methods
startApp() |
Start up the Solo application. This method should be called after setting any of the desired startup properties listed below and before issuing any sendCommand() calls. Once started, none of the startup properties can be changed.
RETURNS: 0 if start was successful or -1 if the start failed. Error messages from a failed start can be retrieved from the read-only property lastResponse. |
stopApp() |
Stop the Solo application. Note that once stopApp has been called, it cannot be restarted without unloading EigenvectorTools. In general it is recommended that this method be called only when the client application is performing final cleanup before exiting. Note that this method is also automatically called when the application object is destroyed, thus, directly calling this method is usually not needed. |
sendCommand(cmd) |
Send a string command "cmd" to the Solo application. This is the standard way of communicating with the application. The command may be any of the simple object-creation commands described in the Solo_Predictor_User_Guide documentation or a command making use of EVRIGUI_Objects. Any textural response from the application is stored in the read-only property lastResponse.
RETURNS: 0 if command was successful, -1 if the command failed due to low-level application error, or -2 if the command was invalid, there was a license error, or other high-level error. In either case, the textural response including any error can be found using the lastResponse property. |
Properties
lastResponse |
READ ONLY: Returns the string response returned by the server after the last sendCommand() call. |
Start-up Properties | |
automation |
Forces the application to open "silently" with no GUI to start. The application will then wait for commands passed through either the application interface or through the socket interface (unless the socket property is set to false - see below). |
allowedLength |
Maximum string length allowed to be returned in lastResponse |
socket |
Boolean flag indicating if socket connections should be enabled when automation mode is on (see automation property).
If false, only commands issued directly through application.sendCommand method will be allowed. If true, socket connections from other programs and optionally other computers will be allowed. |
gui |
Boolean flag indicating if any GUIs should be permitted. If false, application will exit after issuing any other command-line calls. |
clearSettings |
Boolean flag indicating if the settings file (default.xml or value in settingsFile property) should be re-read. If true, previously saved settings and preferences will be cleared before re-reading settings file. Solo_Predictor never retains settings from session to session. |
debug |
Boolean flag indicating if additional startup output should be given. Note this output is reported to the standard output device and may not viewable by applications which cannot capture standard output.
Note: In EigenvectorToolsV6, this property is named debugMode to avoid namespace conflicts. |
licensecode |
String indicating the activation / license code to use with the application. Any previous code will be erased before using this code. If this code is not valid for the given version and product, the application will fail to start. |
settingsFile |
String indicating an alternative settingsFile to load (instead of the default: default.xml). Contents of specified file will only be used when an existing setting is not currently specified. Use in conjunction with clearSettings property to assure these settings are used. |
dataFile |
String specifying a data file to read in upon initialization of application. This file will be read into the workspace unless a special importer is designated for the file (this is only the case for custom applications) |
addCmd |
String specifying any additional command-line options to pass into the application. |
Examples
Visual Basic with ETV6
The following is an example of instancing the EigenvectorToolsV6 interface in Visual Basic. This demonstrates how to make calls to Solo or Solo_Predictor through EigenvectorToolsV6 object. To learn more about the scripting format (the "tosend" string included below), see the Solo Predictor Script Commands Summary and Scripting Examples pages.
To instance the ETV6 object, you must add a reference to the EigenvectorToolsV6 object in your project in Visual Studio.
Dim solo As EigenvectorToolsV6.application Set solo = New EigenvectorToolsV6.application Dim tosend As String 'string to hold message we're sending Dim status As Long 'status integer returned Dim myresp As String 'string to hold response from server solo.automation = True 'turn on automation solo.socket = False 'turn OFF sockets If solo.startApp Then ''' Could not start V6 server ''' -- usually throw some error -- Else ''' Server started, send command tosend = ":plain; model = 'mymodel.mat'; data = 'mydata.txt'; pred = data|model; pred.prediction;" status = solo.sendCommand(tosend) If status = 0 Then ' Command successful myresp = solo.lastResponse myval = Val(myresp) ''convert to double (assumes only one value in myresp) Else ' Server returned error myresp = "error code: " + Str(status) + vbCrLf + solo.lastResponse End If End If
Visual Basic with ET.NET
The above code will work for the ET.NET interface with two minor changes. First, select to add a reference, then browse to locate the EigenvectorTools.dll. Next, change the manner in which the solo object is instanced by changing the first two lines of code shown above to read:
Dim solo As Eigenvector.application Set solo = New Eigenvector.application
After this, all other references to the "solo" object will be identical.
Troubleshooting
Dragging EigenvectorTools.dll to RegAsm doesn't register application
If dragging the EigenvectorTools.dll to the regasm application (to register the ET.NET object) doesn't make the application available, it is possible that the user with which you are trying to perform the action does not have sufficient permissions to register the application. Try using regasm from a command window (run: cmd). You will receive a message similar to:
- RegAsm : error RA0000 : An error occurred while writing the registration information to the registry.
- You must have administrative credentials to perform this task.
- Contact your system administrator for assistance
You must either use an explicit administrator, or use the "Run as Administrator" option to start a command window (cmd.exe), navigate to the folder which contains EigenvectorTools.dll and use the command:
regasm EigenvectorTools.dll
DllRegisterServer Failed. Return Code 0x80004005
If you receive the error:
- DllRegisterServer in EigenvectorToolsV6.dll Failed. Return Code was: 0x80004005
when trying to use regsvr32 to register the ETV6 ActiveX, the user you are logged in as does not have sufficient permissions to register the application. You must either use an explicit administrator, or use the "Run as Administrator" option to start a command window (cmd.exe), navigate to the folder which contains EigenvectorToolsV6.dll and use the command:
regsvr32 EigenvectorToolsV6.dll
Unhandled Exception: System.IO.FileNotFoundException
If you receive an error:
- Unhandled Exception: System.IO.FileNotFoundException: File or assembly name EigenvectorTools, or one of its dependencies, was not found.
- File name: "EigenvectorTools" at main()
the problem is most likely that the EigenvectorTools.dll is not in a folder on your system path or in the same folder as the 3rd party application.
It is often easiest to copy the EigenvectorTools.dll into the Solo or Solo_Predictor application folder. To locate this folder, open a DOS Command window and type the command path. Look in the displayed path for the folder relating to Solo, for example:
C:\Program Files\EVRI\Solo\application\app_bin\win32\
An alternative solution to this problem is to install EigenvectorTools.dll in the GAC (Global Assembly Cache). For more information, see Microsoft Global Assembly Cache page
Cannot Find "plstoolbox.dll" or "System.DllNotFoundException" when Starting Solo
If EigenvectorTools are found and the objects are instanced correctly, but when you attempt to start the application (Solo or Solo_Predictor) via the startApp call, you receive either a message that "plstoolbox.dll" could not be found (from ETV6) or "System.DllNotFoundException" (from ET.NET), the likely cause is that the Solo or Solo_Predictor application's binary directory is not on the system path.
The exact location of the binary directory depends on the location of installation. The easiest way to locate this path is to find any of the shortcuts created by the installer and retreive the properties of that shortcut. It will contain the full path to either a win32 or win64 directory. This is the folder which must be put onto the system path. Typical directories are:
C:\Program Files\EVRI\(product name)\application\app_bin\win32 C:\Program Files\EVRI\(product name)\application\runtime\win64
Solo_Predictor Throws: unknown error Error in => opentoolbox.m at 117
If you are attempting to use Solo_Predictor through the EigenvectorTools interface and it either refuses to start (returning an "unknown error Error in => opentoolbox.m at 117") or requests a license code via a dialog box, it is probable that the default.xml file cannot be found. When starting Solo_Predictor from another application, it is not always clear which folder the default.xml file should be located in so best practice is to use the "settingsFile" property of the EigenvectorTools object to specify where the default.xml file is located. The file can be a copy of the default.xml file usually located in the main Solo_Predictor program folder and can be stored in your own application's folder.
Also make sure the license code is correctly entered into the default.xml file as described in the Solo_Predictor Configuration page.