História stránky

Externá funkcia je objekt v systéme D2000, ktorý umožňuje rozšíriť štandardnú množinu funkcií, ktoré ponúka matematický aparát. Dôležitá črta Externej funkcie je, že je implementovaná v rámci dll knižnice. Pri ich vhodnej implementácii umožnia nahradiť (v určitých prípadoch Objekt Externá funkcia reprezentuje exportovanú funkciu v dynamicky linkovanej knižnici (súbore). Vhodnou implementáciou externých funkcií je možné nahradiť (prípadne aj zjednodušiť) rozšírenia systému implementované rozhraniami D2000 ObjApi alebo D2000 KomAPI.

Vytvorenie Externej funkcie spočíva v dvoch krokoch:

• implementácia Implementácia funkcie v rámci dll dynamicky linkovanej knižnice.
• definovanie Definovanie objektu typu Externá funkcia

Konfiguračné parametre objektu:

V zátvorke budú uvádzané príklady.

Externá funkcia predstavuje (reprezentuje) exportovanú funkciu v dll súbore. Preto je, v rámci konfigurácie objektu, potrebné zadať:

• DLL súbor - meno dll súboru, ktorý exportuje funkciu (userFunctions.dll).
• Meno funkcie - ide o meno funkcie, ktorá je exportovaná dll knižnicou a ktorá bude volaná pri vyhodnocovaní definovanej Externej funkcie (NasobFnct).
• Typy parametrov - reťazec, v ktorom každý znak predstavuje typ parametra funkcie, čím je daný aj počet parametrov (RR).
• Typ hodnoty objektu typu Externá funkcia - určenie typu hodnoty, ktorú funkcia vyhodnotením nadobúda (Re - Real).
• Help - umožňuje definovať súbor nápovedy (názov.chm podobne ako aplikačná nápoveda, pričom názov nie je meno aplikácie), ktorý sa zobrazí po stlačení klávesy F1 (v ESL editore), keď je kurzor umiestnený v rámci mena externej funkcie. Ak parameter nie je definovaný, otvorí sa štandardná nápoveda k systému D2000.
• Help stránka - umožňuje definovať stránku nápovedy (html\meno_stránky.htm), ktorá sa má otvoriť po stlačení klávesy F1 (v ESL editore), keď je kurzor umiestnený v rámci mena externej funkcie. Ak parameter nie je definovaný, otvorí sa nápoveda s úvodnou stránkou.
• Zakázané vyhodnocovanie - parameter označí funkciu ako zakázanú. Takto označená funkcia je farebne zvýraznená v prostredí ESL editora a pri kontrole ESL skriptu je generované upozornenie.
• Zastaralá funkcia - parameter označí funkciu ako zastaralú. Z pohľadu jej vykonávania sa nič nemení. Takto označená funkcia je farebne zvýraznená v prostredí ESL editora a pri kontrole ESL skriptu je generované upozornenie.

Pri definícii objektu je potrebné zadať jeho meno (Nasob). Toto meno sa použije pri volaní funkcie v rámci zápisu matematického výrazu ((ESL, Počítané body).
Napríklad: 2*%Nasob(2,3).

Vyhodnotenie (Exekúcia) funkcie a ochrana pred nekorektnými funkciami:

Keďže vyhodnotenie externej funkcie so sebou prináša určité riziká (príliš dlhé vyhodnocovanie, generovanie výnimiek (exceptions)), konfigurácia externej funkcie obsahuje príznak Zakázané vyhodnocovanie. Ak je príznak zapnutý, funkcia nebude nikdy vyhodnotená a vždy nadobudne neplatnú hodnotu. Pri zistení nekorektnej funkcie systém autonómne aktivuje tento príznak a tým predíde opakovanému volaniu nekorektnej externej funkcie.

Pri exekúcii Externej funkcie, proces (calc.exe, event.exe alebo event.dll) zavedie potrebný dll súbor (userFunctions.dll - Win32Api: LoadLibrary) a vyhľadá v ňom exportovanú funkciu (NasobFnct - Win32Api - GetProcAddress). Ak sa tam nachádza, pripraví a skontroluje parametre (podľa reťazca Typy parametrov) a odovzdá jej riadenie (zavolá ju). Počet parametrov je maximálne 15. Po skončení funkcie s výslednou hodnotou dokončí výpočet výrazu. Zavedený dll súbor nezatvára. Funkcia musí svoju činnosť ukončiť v čo najkratšom čase. Ak sa jej to nepodarí, proces zakáže jej vyhodnocovanie (konfiguračný príznak) a ukončí svoju činnosť. Tento čas je štandardne maximálne 1000 ms. Zmeniť túto hodnotu je možné vytvorením a nastavením hodnoty kľúča:

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

kde sa uvedie čas v MS (0x3E8 je 1000 ms).

Implementácia funkcie NasobFnct:

// funkcia násobí dve reálne čísla
int WINAPI NasobFnct(double * retVal, double *param1, double *param2)
{
  if(param1 == NULL)	// ak je parameter invalid, je hodnota NULL
    return 1;		// výsledok funkcie je Invalid hodnota

  if(param2 == NULL) 	// ak je parameter invalid, je hodnota NULL
    return 1;		// výsledok funkcie je Invalid hodnota

  *retVal = *param1* *param2;// vynásobím a naplním výslednú hodnotu
  return 0; 		// návratová hodnota *retVal je platná
}

Príklad ukazuje niekoľko pravidiel, ktoré platia pri implementácii:

...

Možné typy hodnôt a ich reprezentácia v konfiguračnom parametri Typy parametrov:

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

Za znakom w alebo W nesmie nasledovať iný znak ako w alebo W. Počet znakov w W určuje maximálny počet nepovinných parametrov.

Príklad:
Externá funkcia má typy parametrov popísané nasledujúcim reťazcom:

vvwww

Prvé dva parametre sú povinné a ostatné sú nepovinné. Maximálny počet parametrov je 5 a minimálny počet parametrov je 2. Všetky parametre sú typu Variant, to znamená, že môžu byť ľubovoľného typu.

Ošetrenie výnimiek

Je nutné, aby všetky externé funkcie obsluhovali všetky výnimky (exceptions) vo vlastnej réžii.

int WINAPI DivZero(double * retVal)
{
  try {
    int i;
    i = 0;
    //i = 2 / i; 		// výnimka DivByZero
    throw "My exception"; 	// vlastná výnimka
  }
  catch (...) {}; 		// prázdna obsluha chyby
  *retVal = 0; 			// návratová hodnota je vždy 0
  return 0;
}

Volanie externých funkcií z ESL skriptu

...

• .

Implementácia funkcie

Externé funkcie pre systém D2000 je možné písať v jazyku C++ a pre ich implementáciu je potrebné použiť dodávanú knižnicu D2ExtFunc. Spolu s ňou je dodávaný aj príklad knižnice externých funkcií (adresár utils/d2extfunc/sample v inštalačnom adresári D2000), z ktorého pochádza aj nasledovný príklad implementácie externej funkcie.

int DemoRedim(SyncRoutedFunctionParams& params) {
	// Kontrola parametrov: prvý musí byť štruktúra, druhý jednoduché celé číslo
	if (params.getCount() != 2
		|| !params[0].isStructured()
		|| !params[1].isSimple() || params[1].getType() != Integer)
		return CallError; // Zlý počet alebo typy parametrov - generuje runtime výnimku v ESL

	// Ak je parameter udávajúci nový rozmer štruktúry platný,
	if (params[1].isValid()) {
		// tak zmení rozmer štruktúry
		params[0].setRowsCount(params[1].getValueInteger());
		for (int i = 1; i < params[0].getRowsCount(); ++i) {
			// a skopíruje hodnoty z prvého riadku do všetkých ostatných
			for (int j = 0; j < params[0].getColumnsCount(); ++j) {
				params[0].copyValue(params[0], 0, j, i, j);
			}
		}
	}
	// Volanie externej funkcie bolo úspešné
	return CallSuccess;
}

Ošetrenie chybových stavov a výnimiek

Vykonávanie externých funkcií prebieha v rovnakom prostredí ako bežia ESL skripty, ktoré ich volajú. Ak vykonávanie externej funkcie skončí odchytitelnou C++ výnimkou, je táto výnimka zachytená a do ESL propagovaná ako runtime chyba. Avšak niektoré chyby v C++ (napr. dereferencia NULL, delenie 0) negenerujú odchytitelné výnimky a končia pádom knižnice a procesu, ktorý knižnicu používa (Event handler), preto je pri implementácii externých funkcií potrebné dôsledne dbať na ošetrenie chybových stavov.

Príklad volania externej funkcie

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