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.

• 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. 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.

The Installation and Troubleshooting sections of this document describe how to install the application. The Application Interface section describes the use of the application

Read the EigenvectorTools Release Notes to learn what has been updated in each version.

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.
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. 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.

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

Solo_Predictor Will Not Launch

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. Since this file is required for Solo_Predictor to start, you must use the "settingsFile" property of the EigenvectorTools object to specify where the default.xml file is located. Also make sure the license code is correctly entered into the default.xml file as shown in the Solo_Predictor Configuration page.