EigenvectorTools

Introduction

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

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

General Properties
lastResponse	READ ONLY: Returns the string response returned by the server after the last startApp() or sendCommand() call.
allowedLength	Maximum string length allowed to be returned in lastResponse
Start-up Properties - All Products
debug debugMode	Boolean flag indicating if additional startup output should be given. Usually, this output will be written to a file named solo_debug.log in the user's temp directory. 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). Also allows specifying location of default.xml when it can't be found automatically by the application. Note: In Solo and Solo+MIA, the contents of specified file will only be used when an existing setting is not currently specified. Thus, this setting should be used in conjunction with clearSettings property to assure these settings are used.
addCmd	String specifying any additional command-line options to pass into the application.
Start-up Properties - Solo & Solo+MIA Only
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).
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.
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)

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 example will work on the ET.NET interface after two changes are made:

1. You must tell Visual Studio to reference the EigenvectorTools.dll (ET.NET) by selecting "add a reference" option in Visual Studio, then browsing to locate the EigenvectorTools.dll.
2. You must make a change in the name used to instance the "solo" object. The exact name change depends on the version of Visual Studio you are using.

Visual Studio 6: Change the first two lines of code shown above to read:

       Dim solo As EigenvectorTools.application
       Set solo = New EigenvectorTools.application

Visual Studio 2003 and later: Change 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 either that the Solo or Solo_Predictor application's binary directory is not on the system path or you are attempting to start the 64-bit version of Solo/Solo_Predictor using ETV6.

• Check the system path for the binary directory. 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 retrieve 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   (32-bit Solo 6.2 and earlier)
 C:\Program Files\EVRI\(product name)\application\runtime\win32   (32-bit Solo 6.3 and later)
 C:\Program Files\EVRI\(product name)\application\runtime\win64   (all 64-bit Versions)

• The second possible cause of this error is attempting to start a 64-bit version of Solo or Solo_Predictor from ETV6. Only ET.NET can be used to start the 64-bit version of Solo. For more information, see Introduction to Eigenvector Tools. Check which version of Solo you are using

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.