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 ("ETV6") 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. IMPORTANT: ETV6 has been removed in newer versions. ETV6 is only available for use in Solo_Predictor versions 3.6.2 and earlier. (32-bit versions only)

• 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: 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 older 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. Furthermore, a 32-bit and 64-bit version of ET.NET is provided in the distribution. In general, the version used should be matched to the user's calling application (a 64-bit application should use the 64-bit ET.NET; a 32-bit application should use the 32-bit ET.NET). 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*

* Either the 32-bit or 64-bit version of ET.NET can be used, but should be matched to the application instancing 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. The EigenvectorTools application will be installed along with the stand-alone application and will be found in a folder named "eigenvectortools" under the main application folder. The DLLs referred to below will be in the eigenvectortools/bin/x86 folder for 32-bit versions of ET and the eigenvectortools/bin/x64 folder for 64-bit versions of ET. Note that all types of ET tools are shipped with all products, whether or not the main product is the 32- or 64-bit version.
4. Using an account with administrative privileges, complete one of the two following steps depending on the version of EigenvectorTools you are installing:
   • 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 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 allowedLengthLong	Maximum string length allowed to be returned in lastResponse. In ET.NET: allowedLength property is a Long integer type and allowedLengthLong is not available. Both set the maximum length of string returned, but allowedLength property is typed as a Short Integer while the allowedLengthLong property is typed a Long Integer. In general, allowedLenghtLong should be used in ETV6 but allowedLength is supported to allow backwards compatibility. Maximum length of string when setting using the Short Integer version of this property is 65535 characters.
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. Note: for Solo_Predictor and other products that require a default.xml file, this property will not be used unless a valid default.xml has been found (see settingsFile property for a method to specify the location of this file). However, the default.xml file does not need to have a valid licensecode in it if this property is set. This is not the case for Solo or Solo+MIA which do not require a default.xml file.
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

Please see the example code in the supplied eigenvectortools\VBExample\source\frmTCPTest.frm

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.

MSVC++ with ET.NET

For applications using Microsoft's Visual C++ and using .NET, the previous example is almost identical to what would be used except for the following code changes:

Replace the line:

   EigenvectorToolsV6::application *solo = new EigenvectorToolsV6::application;

with

   Eigenvector::application *solo = new Eigenvector::application;

and the line

   solo->allowedLengthLong = &lngth;

with

   solo->allowedLength = &lngth;

See the example in the supplied eigenvectortools\CppExample\source\socketTester\socketTester.cpp, or

In addition, to instance the ET.NET object, you must add a reference to the EigenvectorTools object in your project in Visual Studio.

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\runtime\win32          (32-bit Solo on a 32-bit system)
 C:\Program Files (x86)\EVRI\(product name)\application\runtime\win32    (32-bit Solo on a 64-bit system)
 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 and confirm that you are using the compatible EigenvectorTools version (ETV6 or ET.NET).

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.

Setting Up Visual Studio 2019 for Examples

Assuming you have installed Solo_Predictor following its installation instructions, for example at: C:\Program Files\EVRI\Solo_Predictor\ (and have edited the default.xml configuration file to include your license code) then you can test communication with Solo_Predictor from .NET languages as shown in the eigenvectortools\CSharpExample\CSharpExample.sin Visual Studio example

C#

• Open the CSharpExample.sln file with Visual Studio and allow the "upgrade" to take place.
• In the References, remove the existing reference to EigenvectorTools.dll.
• Add a new reference to EigenvectorTools.dll in the SoloP folder (example - C:\Program Files\EVRI\Solo_Predictor\eigenvectortools\bin\x64\EigenvectorTools.dll).
• Run configuration as "Any CPU"

In the Visual Studio "Solutions Explorer" window open the "TestApp.cs" file by double-clicking. Ensure line 25 of this file is identifying your "default.xml" settings file location. Run this test program to see it create an application object then use the EigenvectorTools methods "startApp()" and "sendCommand()" to start Solo_Predictor and send a simple example command message to it. It this is successful it reads the response "solo.lastResponse", or reports any error. If all goes well you should see a console window open containing something like the following:

   Starting Application...
   Status: 0
   Error Code: 0
   0.814723686393 0.905791937076 0.126986816294 0.913375856139 0.632359246225
   
   Press Enter to end this program.

This is the response to the simple command included in the code as

   "string cmd = ":plain; x='[rand(1,5)]'; x";" 

but in practice you would send commands as described at: Script Construction See the example at: Retrieve Results. This example would be coded as a command as:

   string cmd = ":plain; data = 'C:/datacollector/datafolder/spectrum1.spc'; model = 'C:/modelfolder/mymodel.mat'; pred = data | model; pred.prediction;". 

For more complicated examples it can be simpler to use the ":include" command as described at Other Commands.

Release Notes

The following pages describe the release notes for the given version of the EigenvectorTools application:

• Version 2.3 - released Jan. 2014 / 2.3.1 Jul. 2014
• Version 2.2 - released Oct. 2011