História stránky

...

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 libraryThe External function object represents an exported function in a dynamically linked library (file). 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:

• Implementation of a function implementation within the dll a dynamically linked library,
• definition 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:

...

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

...

•  type.

Function Implementation

External functions for the D2000 system can be written in C ++ language and the D2ExtFunc library must be used for their implementation. Also included is an example of the external function library  (utils/d2extfunc/sample directory in the D2000 installation directory), which also provides the following example of an external function implementation.

int DemoRedim(SyncRoutedFunctionParams& params) {
	// Parameter check: the first parameter must be the structure, the second simple integer 
	if (params.getCount() != 2
		|| !params[0].isStructured()
		|| !params[1].isSimple() || params[1].getType() != Integer)
		return CallError; // Wrong number or types of parameters - generates runtime exception in ESL

	// If the parameter specifying the new dimension of the structure is valid, 
	if (params[1].isValid()) {
		// then it will change the structure dimension
		params[0].setRowsCount(params[1].getValueInteger());
		for (int i = 1; i < params[0].getRowsCount(); ++i) {
			// and copy the values from the first row into the other ones
			for (int j = 0; j < params[0].getColumnsCount(); ++j) {
				params[0].copyValue(params[0], 0, j, i, j);
			}
		}
	}
	// Calling of the external function was successful 
	return CallSuccess;
}

Errors and exceptions handling

Performing external functions takes place in the same environment as running the ESL scripts that call them. If the implementation of an external function ends with a catchable C ++ exception, this exception is caught and promoted as a runtime error to the ESL. However, some C ++ errors (e. g., NULL dereference, division 0) do not generate catchable exceptions and end up with the fallout of the library and the process used by the library (Event handler), so it is important to care thoroughly of handling errors when implementing external functions.

Example of calling an external function

BEGIN
  RECORD NOALIAS (SD.ExtFunc) _rec
  CALL %DemoRedim(_rec, 10)
END

...