EigenvectorTools

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:	32-bit	64-bit
32-bit Windows	ETV6 or ET.NET	n/a
64-bit Windows	ETV6 or ET.NET	ET.NET

Installation - describes installation of the application.

Troubleshooting - describes some common problems and solutions.

Application Interface - describes the use of the application.

EigenvectorTools Release Notes - describes what has been updated in each release.

Installation

1. 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]
2. 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.
3. Download the EigenvectorTools application from your account at [http://download.eigenvector.com]
4. 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.
5. 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 debugMode	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

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.

 Dim solov6 As EigenvectorToolsV6.application
 Set solov6 = 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
  
 solov6.automation = True   'turn on automation
 solov6.socket = False      'turn OFF sockets
    

 If solov6.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 = solov6.sendCommand(tosend)
    If status = 0 Then

       ' Command successful
       myresp = solov6.lastResponse
       myval  = Val(myresp)         ''convert to double (assumes only one value in myresp)

    Else

       ' Server returned error
       myresp = "error code: " + Str(status) + vbCrLf + solov6.lastResponse

    End If
 End If

Troubleshooting

Unhandled Exception: System.IO.FileNotFoundException

If you recieve 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.