External functions

External function is an object of D2000 system, that allows to extend the standard set of functions that are comprised in the mathematical apparatus. One of the important features of External function is its implementation within of DLL library. When properly implemented, they allow to substitute (in some cases also simplify) system extensions implemented by the interfaces D2000 ObjApi or D2000 KomAPI.

Creation of an External function consists two steps:

• function implementation within the dll library,
• definition of an object of External function type.

Object configuration parameters:

Examples are to be enclosed in brackets.

External function represents an exported function in a "dll" file. Therefore, it is necessary to set within the object configuration:

• DLL file - name of the dll file, that exports the function (userFunctions.dll)
• Function name - name of the function, that is exported by the dll library and that will be called during the evaluation of the defined External function (MultiplyFnct)
• Types of parameters - string, where every character represents a function parameter, whereby is also given the number of parameters (RR).
• Object value type of External function type - determination of a type of a value the function gains by the evaluation (Re - Real).\
• Help - defines a help file (name.chm like application help, but the name is not an application name). It will occur after a user press F1 key (in ESL editor), when the cursor is placed over the name of some external function. If the parameter is not defined, the basic help of D2000 System opens.
• Help page - defines a page of the help (html\page_name.htm). The page opens after the user press F1 key (in ESL editor), when the cursor is placed over the name of some external function. If the parameter is not defined, the first page of the help opens.
• Forbidden evaluation - parameter labels a function as forbidden. This function is highlighted in color in ESL editor and when checking ESL script a warning will be generated.
• Deprecated function - parameter labels a function as deprecated but it could be still used. This function is highlighted in color in ESL editor and when checking ESL script a warning will be generated.

In the object definition, it is necessary to enter its name (Multiply). This name will be used when the function is called within the mathematical expression notation (ESL, Eval tags).
For example: 2*%Multiply(2,3).

Function execution and protection from incorrect functions:

As the evaluation of external function brings some risks (very long execution, generation of exceptions), the external function configuration contains the attribute Disabled evaluation. If the option is enabled, the function will never be evaluated and always acquires invalid value. After the detection of an incorrect function, the system automatically enables this attribute and thereby avoids the repeated calling of the incorrect external function.

During the execution of External function, a process (calc.exe, event.exe alebo event.dll) initializes the necessary dll file (userFunctions.dll - Win32Api: LoadLibrary) and searches for the exported function (NasobFnct - Win32Api - GetProcAddress) in it. If the function is located in it, process prepares and checks parameters (according a string from Parameter's types option) and calls it. The number of parameters is at most 15. When the function is evaluated, process uses its result value and completes the expression evaluation. The initialized dll file is not closed. The function activity must be as short as possible. If it is not, process avoids its execution (configuration attribute) and is terminated. By default, the time is usually 1000 ms, at most. Changing this value is enabled by creation and setting of a key value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Ipesoft\D2000V45]
"MaxExtFnctTimeMS"=dword:000003e8

a time is in milliseconds (0x3E8 is 1000 ms).

Implementation of the function MultiplyFnct:

// the function multiplies two real numbers
int WINAPI MultiplyFnct(double * retVal, double *param1, double *param2)
{
  if(param1 == NULL)		// if the parameter is invalid, value is NULL
    return 1;			// function result is Invalid value

  if(param2 == NULL)		// if the parameter is invalid, value is NULL
    return 1;			// function result is Invalid value

  *retVal = *param1* *param2;	// multiply and assign to the result value
  return 0; 			// the return value *retVal is valid
}

The example shows several rules, valid for an implementation:

1. Function return value:

0 - evaluation executed (result is valid).
1 - evaluation was not executed (result is invalid value).



2. All parameters (including a result value) are passed by reference to the required type. If any of parameters is NULL, then the value is invalid.
3. The first function parameter is the pointer to a value, that will be used during the expression evaluation (in perspective of a function in the expression, it is the ''return value''). Pointer is pre-allocated according to the configuration parameter: Value type of the object of External function type.

Possible value types and their representation in the configuration parameter Parameter's types:

struct TAbsTime {
  int year;
  int month;
  int day;
  int hour;
  int minute;
  int second;
  int ms;
};

Only sign w or W must follow the sign w or W, another sign is not allowed. Number of w W defines the maximal optional parameter count.

Example:
The parameter types of external function are described by the following string:

vvwww

The first two parameters are required and the others are optional. Maximum number of parameters is 5, minimum one is 2. All the parameters are of Variant type, i.e. they can be optional.

Handling exceptions:

It is necessary, that all the external functions handle all exceptions by own facilities.

int WINAPI DivZero(double * retVal)
{
  try {    
      int i;
      i = 0;
      //i = 2 / i;		// the exception DivByZero
      throw "My exception";	// own exception 
    }
    catch (...) {};		// empty error handle
    *retVal = 0;		// return value is always 0
    return 0;
}

Calling of external functions from ESL script

To call the external functions from ESL script, you must implement ADA_CALL_ROUTER function to dll library. This function provides an interface between ESL script and the functions written in C programming language. This function checks and sets the parameters that come to dll library first and then calls the required function. ADA_CALL_ROUTER has to be added to each dll library. To check and process the parameters, you can use the library ada_call_router_utils.