How to Use the DLL Server

Top  Previous  Next

_bm45DLL Server - Detail

This capability allows you to execute a trained NeuroShell 2 network from Visual Basic, Access Basic, Pascal, C, Excel, or other languages.  In other words, your networks can be used within programs written in these languages.

 

Once you train a neural network in NeuroShell 2, the DLL Server gives you the means of saving the network on a file so it can later be accessed via a Dynamic Link Library (DLL).

 

Execution of a trained network is just the process of feeding an array of inputs to the network and receiving back the appropriate array of outputs.  This is handled by the NS2-32.DLL that is part of NeuroShell 2.  You may distribute the NS2-32.DLL with any applications that you create, but you are not allowed to disclose the details of how it works, i.e., the functions OpenNet, FireNet, and CloseNet, etc.  NS2-32.DLL is installed in the Windows SYSTEM directory during NeuroShell 2 setup.

 

Before any trained network can be executed by the DLL, a .DEF file for that network must be created by the NeuroShell2 DLL Primer which is part of the Runtime facilities.

 

1.  Use the File Menu to select the configuration file for the NeuroShell 2 problem for which you want to create a .DEF file.  The default name for the .DEF file will be the problem name.  Use the File Menu to choose a different name.

 

2.  Select the Generate DLL Definition File option from the Generate Menu to create the .DEF file.

 

Once the .DEF file is created, three DLL functions are needed to execute it:

 

OpenNet - This reads the .DEF file and sets up the network.  It gives you back a network number which is your future reference to the network.  It also gives you the number of inputs the network expects and the number of outputs with which it will respond.  Normally, you will already know the number of inputs and outputs anyway.

 

FireNet - Once the network is opened with OpenNet, use FireNet to pass inputs to the network and receive back outputs, both in double precision floating point arrays which you designate in your program.  Missing data values are not automatically replaced when using FireNet as they are when you specify conditions in the Training and Stop Training Criteria module in NeuroShell 2.  This is because there is no way to designate that data is missing as opposed to being zero.

 

CloseNet - Execute this when you no longer need to execute the network.  It will release all space taken by the network.  The next time your program needs to execute the network it will have to do another OpenNet.

 

All three of the functions return an integer return code which is zero if there was no error.  If there was an error, the return code is a positive integer.  All functions also pass their parameters as far pointers.

 

If you call the OpenNet function from a program and receive any non-zero return, it is usually because OpenNet could not find the .DEF file for your problem, or there was an error reading it.  This might be because the string that you passed to OpenNet which contained the .DEF file path was invalid or not passed properly.  If you are using Delphi, be sure to use C strings and not Pascal strings.

 

If you call the FireNet function for either a PNN or GRNN net and you receive a return of 38, the error signifies that the smoothing factor is out of range.  This means that the pattern being sent to the net is quite different from any patterns included in the training data.  Therefore, the current pattern cannot be processed.  The solution is to retrain the net with more data in the training set similar to this pattern.

 

In order to code the DLL calling into your program, follow the conventions of the particular language product you are using with regard to calling DLLs.

 

In C, the process usually requires including a .LIB file for the NS2-32.DLL into your project.  You may use one of the NS2-32.LIB files supplied with NeuroShell 2.  You can find these files in NeuroShell 2\Examples\Runtime examples\VC6 directory for Microsoft Visual C 6.0 and in NeuroShell 2\Examples\Runtime examples\Bc4_5 directory for Borland C 4.5.  Then use the C prototypes below to call the functions.  These prototypes are also available in NSHELL2.H files in corresponding directories for both C compilers mentioned above.  There may be other methods available, however.

 

In Visual Basic you can simply call the functions like any other VB function if you load NSHELL2.BAS into your project.  NSHELL2.BAS has the VB function prototypes in it.  You can find this file in NeuroShell 2\Examples\Runtime examples\VB6  directory.

 


C Prototypes and Complete Descriptions of the DLL functions

 

OpenNet

 

int far PASCAL _export OpenNet (char far *defpath, int far *netnumber, int far *inputs, int far *outputs);

 

*defpath is a pointer to a character string containing the path to the .DEF file.  If the path contains only the file name, the file must be in the current directory.

 

*netnumber is a pointer to an integer in your program where OpenNet will place the network number you will use to reference the network in FireNet and CloseNet.

 

*inputs is a pointer to an integer in your program where OpenNet will place the number of inputs the network expects.

 

*outputs is a pointer to an integer in your program where OpenNet will place the number of outputs the network expects to produce.

 

If the return code is not zero from OpenNet it is usually because OpenNet could not find a valid .DEF file at the location described by defpath.

 

FireNet

 

int far PASCAL FireNet (int far *netnumber, double far *inarray, double far *outarray);

 

*netnumber is a pointer to an integer containing the network number given to your program when you opened the network with OpenNet.

 

*inarray is a pointer to series of consecutive double precision floating point numbers. This series must contain as many doubles as the network expects for inputs. The input values must be in this array. Do not scale the values because FireNet will do that for you.

 

*outarray is also a pointer to a series of consecutive double precision floating point numbers.  This series must contain as many doubles as the network expects for outputs.  The output values will be placed in this array by FireNet.  If you mistakenly supply less doubles than there are outputs then your program will probably crash when FireNet overwrites part of your program with the rest of the outputs.

 

CloseNet

 

int far PASCAL _export CloseNet (int far *netnumber);

 

*netnumber is a pointer to an integer containing the network number given to your program when you opened the network with OpenNet.

 

 


Visual Basic Prototypes and Complete Descriptions of the DLL functions

 

OpenNet

 

Declare Function OpenNet% Lib "NS2-32.DLL" (ByVal defpath$, netnumber%, inputs%, outputs%)

 

defpath$ is a string containing the path to the .DEF file. If the path contains only the file name, the file must be in the current directory.

 

netnumber% is an integer variable in your program where OpenNet will place the network number you will use to reference the network in FireNet and CloseNet.

 

inputs% is an integer variable in your program where OpenNet will place the number of inputs the network expects.

 

outputs% is an integer variable in your program where OpenNet will place the number of outputs the network expects to produce.

 

If the return code is not zero from OpenNet it is usually because OpenNet could not find a valid .DEF file at the location described by defpath$.

 

FireNet

 

Declare Function FireNet% Lib "NS2-32.DLL" (netnumber%, inarray#, outarray#)

 

netnumber% is an integer containing the network number given to your program when you opened the network with OpenNet.

 

inarray# is the first of a series of consecutive double precision floating point numbers. This series must contain as many doubles as the network expects for inputs. This can be a one dimensional array (e.g. Array(1)) or a column of a 2 dimensional array (e.g. Array(1, J)).  The input values must be in this array. Do not scale the values because FireNet will do that for you.

 

outarray# is also the first of a series of consecutive double precision floating point numbers.  This series must contain as many doubles as the network expects for outputs.  The output values will be placed in this array by FireNet.  If you mistakenly supply less doubles than there are outputs then your program will probably crash when FireNet overwrites part of your program with the rest of the outputs.

 

CloseNet

 

Declare Function CloseNet% Lib "NS2-32.DLL" (netnumber%)

 

netnumber% is an integer containing the network number given to your program when you opened the network with OpenNet.

 

 


Firing from Delphi

OpenNet, FireNet, and CloseNet are easy to use from Delphi compilers, too.  In addition to making sure you pass parameters by pointer, make sure you pass the .DEF file path as a C string instead of a Pascal string.  Use the Delphi Strpcopy function to convert.  Also, make sure you use the compiler options smart callbacks and extended syntax.  See below for more information concerning the 32 bit Delphi compiler.

 

 


32-bit Compiler

Remember, when calling our 32-bit DLL (Ns2-32.DLL) from 32-bit compilers, any reference to integer means a 16-bit integer.  Many 32-bit compilers assume integers are 32-bit integers. When using Delphi 32-bit, use smallint, not shortint, and use the stdcall declaration on the DLL function prototypes.  Please refer to the subdirectory  Examples\Runtime examples\Delphi for an example.

 

 


Firing from TradeStation

If you want to call FireNet from the TradeStation Easy Language, you must use the TradeStation Add-on, which provides another form of the DLL that is easier for the Easy Language to access.  Please refer to TradeStation Help File for more information about this add-on.

 

 


Firing networks from Microsoft Excel 97 and below

Note: below description of the OpenNetX, FireNetX, CloseNetX, and Predict functions employs the Excel spreadsheet function CALL. The CALL function worked in Excel version 97 (excluding Excel 97 SR-2) and below. The CALL function in newer versions of Excel had been disabled from worksheets by Microsoft due to security reasons. For information on how to execute networks from newer versions of Excel, please scroll down and read section Firing networks from Microsoft Excel 97 SR-2 and higher at the end of this topic.

 

If you have Excel 5 or higher you can call OpenNet, FireNet, and CloseNet from a module using Visual Basic.  There are three functions equivalent to OpenNet, FireNet, and CloseNet which can be called from Microsoft Excel as functions without using Visual Basic.  They are OpenNetX, FireNetX, and CloseNetX.  There is also available another function, Predict, which combines the actions of OpenNetX and FireNetX into one function which is more appropriate for a spreadsheet. Most users will want to use Predict exclusively.  The functions OpenNetX, FireNetX, CloseNetX, and Predict require the spreadsheet to be saved in Excel 5 or higher .XLS format rather than NeuroShell 2's internal .WK1 file format.

 

Note: Users who have installed country specific versions of their operating system other than US may have to use a semicolon as a list separator instead of a comma in the call examples below. The exact character for a list separator can be found in the Windows Control Panel under Regional Settings.

 

OpenNetX

 

To execute OpenNetX you can place a call to it right in the worksheet as follows:

 

=CALL("NS2-32.DLL","OpenNetX","pp",def_path)

 

where def_path is a label showing the path to the def file you created from the Runtime DLL Primer. For example:

 

=CALL("NS2-32.DLL","OpenNetX","pp", "c:\NeuroShell 2\Examples\saddle.def")

 

Of course, def_path can also be given by reference:

 

=CALL("NS2-32.DLL","OpenNetX","pp",$A$1)

 

OpenNetX returns an integer, the network number to use in future FireNetX calls.  It does little harm to call OpenNetX multiple times (as in a recalculation) because only one copy of each network will be opened.

 

The "pp" cannot be changed in this or any other DLL call below because this tells EXCEL about the DLL inputs and outputs.

 

If OpenNetX cannot locate the .DEF file where you said it was, the result returned will be the familiar  #NAME?

 

FireNetX

 

FireNetX can also be placed in the worksheet:

 

=CALL("NS2-32.DLL","FireNetX","pppp",network_number,input_array,output_number)

 

where network_number is the number returned by OpenNetX, input_array is the array where the inputs are found, and output_number is the number from 1 to the number of outputs of this network which is the one you want placed in this cell.

 

In the following example, suppose cell B1 is where you placed the OpenNetX, and suppose that the two inputs to the network SADDLE are in A9:B9.  Then the following call will fire the SADDLE net and place the first output (in this case there is only one output) in the cell:

 

=CALL("NS2-32.DLL","FireNetX","pppp",$B$1,A9:B9,1)

 

We used the form $B$1 instead of B1 so that if the call is copied and pasted then the reference to the network number will stay the same. The output number may be by reference too. If the network has multiple outputs, place a call to FireNetX in multiple cells with different output numbers.

 

Error returns from FireNetX are:

 

#REF!   you did not supply enough inputs.

#NUM!   the network number was invalid or the net is not open.

#N/A  there was more than one input, but you did not pass an array to the DLL.

#VALUE!  there was a non-numeric input, e.g., a label.

#DIV/0!   the output sequence number was invalid for this network.

#NULL!   there was some type of internal or system problem executing the network.  If this occurs with a GRNN or PNN network, it is probably because the smoothing factor is out of range for the data.  Make sure you have data in the Training and Test Sets that is "close" to data you are applying the net to.

 

CloseNetX

 

Use this function to close a network and free its memory, or you can just close Excel when you are finished with the spreadsheet.

 

=CALL("NS2-32.DLL","CloseNetX","pp",network_number)

 

where network_number was placed by OpenNetX, e.g.:

 

=CALL("NS2-32.DLL","CloseNetX","pp",$B$1)

 

Predict

 

Predict combines the actions of OpenNetX and FireNetX to make life easier. This is the only function you will need, assuming you will close all networks by simply ending EXCEL when you are done with it.

 

=CALL("NS2-32.DLL","Predict","pppp", def_path, input_array, output)

 

In the following example, suppose you want the third output of the REALTY network.  The network's 6 inputs are located in cells A1:A6.

 

=CALL("NS2-32.DLL","Predict","pppp","c:\NeuroShell 2\Examples\realty.def",A1:A6,3)

 

Predict returns the same errors as OpenNetX and FireNetX.

 

Note: Function names in Excel calls are case sensitive, so you must make sure the upper and lower case letters match the following:  OpenNetX, FireNetX, CloseNetX, or Predict.

 

The inputs to the call of the Predict function must be in the same order as they appeared in the Define Inputs/Outputs module.  The cell range which defines the inputs for the Predict function must only contain values for variables that were designated as I, Input, in the Define Inputs/Outputs module.  The range of input values must be contiguous, i.e, it may not contain any unused columns that appeared in the spreadsheet used to train the net.

 

Note: If you put ! at the end of the pppp, then the CALL recalculates every time the spreadsheet recalculates.  Do this only if you put a new .DEF file in the computer and the spreadsheet won't recalculate.  Otherwise, the constant recalculations may drastically slow down spreadsheet operations, especially if there are a great deal of CALLS or the network is large.

 

Note: If your list separator is a character other than a comma, the other character should be substituted for the comma in the call to Predict.  The exact character for a list separator can be found in the Windows Control Panel under Regional Settings.

 


Firing networks from Microsoft Excel 97 SR-2 and higher

The following applies to Excel 97 SR-2, Excel 2000, Excel XP (aka Excel 2002), Excel 2003, and Excel 2007.

The CALL worksheet function no longer works in above mentioned versions of Excel. Microsoft has disabled the CALL function from worksheets due to security reasons.

A VBA macro function called Predict was built to work around this problem. The new Predict function is located in the PRED.XLA Add-In in your NeuroShell 2\Examples\Runtime Examples\Excel2000 directory. To be able to use it with newer versions of Excel you first need to properly install PRED.XLA on your machine.

To install, follow these steps:

Excel versions prior to Excel 2007:

1. Open up Microsoft Excel.

2. Click on the Tool -> Add-Ins menu. Click on the Browse button, browse to and select PRED.XLA from the NeuroShell 2\Examples\Runtime Examples\Excel2000 directory.

3. Click OK button.

Excel 2007:

1. Open up Microsoft Excel.

2. Click on the Office button (top left).

3. Click on the Excel Options button (bottom).

4. In the left pane, click on Add-Ins.

5. In the right pane, click on the Go button.

6. Click on the Browse button, browse to and select PRED.XLA from the NeuroShell 2\Examples\Runtime Examples\Excel2000 directory.

7. Click OK button.

Now the PRED.XLA is properly installed. The syntax of the Predict macro is as follows:

 

=Predict(definition_filename, input_range, network_output_number)

 

For example:

 

=Predict("C:\NeuroShell 2\Examples\lines.def", $A$10:$E$11, 1)

 

The Predict macro can only fire one pattern at a time. Therefore, the input_range parameter must represent a contiguous set of cells where number of cells must be equal to the number of inputs in your network definition file. If you need to fire the net with multiple patterns, create the Predict formula for each individual pattern.

The NeuroShell 2\Examples\Runtime Examples\Excel2000 folder also contains files Predict2000.xls and pred.xls. The Predict2000.xls example shows how to use new Predict macro in newer Excels. We also supply source of the Predict macro in pred.xls for those users, who feel comfortable to incorporate the macro directly into the workbook as a VBA module. This way you don’t need to use the Predict as an Add-In tool.

 

 


Recurrent Networks

You need to be careful when using the Predict function with recurrent networks.  The first time the Predict function is called from the spreadsheet, it will give the correct answers.  If the spreadsheet automatically recalculates any values, however, it will provide different answers.

 


Examples

Your NeuroShell 2 distribution CD contains five examples which call NeuroShell 2 networks from other programs.

 

In the first example, we have built a Visual Basic 5 program called RUNREAL to load and fire the Realty example.  RUNREAL is an interactive form which allows the user to put home characteristics on the form and classify the property via the network.  The Visual Basic source code is included for your reference in the subdirectory  Examples\Runtime examples\VB6.

 

In the second example, we have built a console application under Visual C 4.0 that also loads and fires the Realty example.  This example program asks the user to input home characteristics from console and classifies the property via the network.  The Visual C source code is included for your reference in the subdirectory  Examples\Runtime Examples\VC6.

 

In the third example, we have built a similar console application that loads and fires the Realty example under Borland C 4.5.  You can find the C source code and the Borland C project file in the subdirectory  Examples\Runtime Examples\Bc4_5.

 

In the fourth example, we have built an application that uses FireNet with a 32-bit Delphi compiler.  It uses Firenet to fire the NeuroShell 2 Saddle example using random inputs.  The sample code is included for your reference in the subdirectory  Examples\Runtime examples\Delphi.

 

In the last example, we have created an Excel 4 spreadsheet which executes the Lines example from the spreadsheet.  There are labels on the spreadsheet which explain where the inputs are placed and where the outputs are received.  The spreadsheet is called PREDICT.XLS and you can find it in the subdirectory  Examples\Runtime Examples\Excel.