External Functions
A remarkable feature of EES is that the user can add (and later remove) functions and procedures written in any compiled language. These external routines may have any number of arguments. Functions return a single value whereas procedures may return multiple values. The external functions and procedures are used in exactly the same manner as internal functions and internal procedures.
External functions are written as dynamic link libraries (DLL's) under the Windows operating system. External functions are identified with a .DLF or .DLF64 file name extension. When EES is started, it examines the files in the \USERLIB (or \USERLIB64 for the 64-bit license) subdirectory and subdirectories within these subdirectories. Any files having a .DLF or .DLF64 file name extension are assumed to be external functions and are loaded unless directed otherwise by the Library Manager. The function name used in the EES equations is the file name (without the extension). External functions can also be loaded using the $INCLUDE directive or the Load Library command.
External functions can be written in any compiled language that supports linked lists. The function statement header, however, must have a specific format. A skeleton listing of an external function in Delphi follows:
library XTRNFUNC;
{$N+}
type
charString = array[0..255] of char
ParamRecPtr = ^ParamRec;
ParamRec = record
Value: double
next: ParamRecPtr;
end;
function FuncName (var S: charString; var Mode: integer; Inputs: ParamRecPtr): double; export; stdCall;
begin
...
...
FuncName:=Value;
end;
exports FuncName;
begin
end.
The major concern is the function header. To be recognized by EES, the function name, called FuncName in the above example, must be the same as the filename. The function statement has three arguments.
S is a 255 character C string. The actual string length may be less than 255 characters. It is terminated with a chr(0), following the normal C string conventions. S can be used both to send text information from EES and to return text information from the external procedure. The text information sent from EES to the function appears within single quotes as the first argument in the procedure call statement, as in the following example.
g = FuncName('optional text', Arg1, Arg2)
The text information is optional. If it appears in the function call, as above, then S will be set to this text without the quotes. Otherwise, S will be set to a null string. Note that Array Range Notation (e.g., X[1..5] can be used as shorthand in the Call statement. The input variables and returned result for an external function are always real regardless of the setting for Complex Numbers.
Mode is an integer set by EES as an input to the external routine with the following purpose:
Mode=-1: EES is requesting that the external Procedure return in S an example of the EES call format.
Mode=-2: EES is requesting that the external Procedure return in S a string containing the units of each of the inputs, separated by a list separator (comma or semicolon).
Mode=-3: EES is requesting that the external Procedure return in S a string containing the units of each of the output, separated by a list separator (comma or semicolon).
Mode=>0 The procedure should calculate and return the output values.
Note that EES will provide unit checking if the external procedure provides the strings of inputs and outputs requested with Modes=-2 and -3. Otherwise it will skip unit checking for this equation.
Inputs is a pointer to the head of a linked list of input values supplied by EES. Each input consists of a value (double precision) and a pointer to the next input, as indicated by the ParamRec structure. The function may have one or more inputs. The next field of the last input will be a null pointer (nil). The function should count the inputs to be sure that the number supplied is as expected and issue an error message in S if this is not the case.
Under normal operation, S is returned from the function as the null string and the function should set Mode to 0. If an error is encountered in the external function, S should be set to an appropriate error message and Mode should be set to a positive integer. EES will then terminate calculations and display this error message. If it is desired to display a warning message (that will not terminate calculations), Mode should be set to a negative integer and the warning should appear in string S.
An example external function written in DELPHI called PWF is supplied with EES. The PWF source code is in this help file. The compiled function is in the PWF.DLF file. Also available is a simple example of an external function written in C++.
Information concerning external functions can be obtained in an identical manner to built-in functions with the Function Info command in the Options menu. When the user clicks the Function Info button, EES will look for a file with the name of the external function and a help file having a .CHM, .PDF, .TXT, or .HTM file name extension. The .HTM file should be HTML code readable by a browser. This text will be displayed if the file is found in the same folder as the external function.
A method to register external functions and procedures is implemented in EES versions 10.011 and newer. Before calling the function the first time, EES will call it with Mode=-1 and with the character string S set to '['+EESIDNo+']', e.g., [1234]. EESIDNo is the EES registration number that appears on the EES start-up screen. The external function can ignore this information or it can internally set to flag it if this EES license is not intended to use the external function.