Externé funkcie (Matematické spracovanie údajov)

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 aj zjednodušiť) rozšírenia systému implementované rozhraniami D2000 ObjApi alebo D2000 KomAPI.

Vytvorenie Externej funkcie spočíva v dvoch krokoch:

• implementácia funkcie v rámci dll knižnice
• 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:

1. Návratová hodnota funkcie:

0 - výpočet prebehol (výsledok je platný)
1 - výpočet neprebehol (výsledok funkcie je neplatná hodnota)



2. Všetky parametre (aj výsledná hodnota) sú odovzdávané cez smerník na potrebný typ. Ak je niektorý parameter NULL, hodnota je neplatná (Invalid).
3. Prvý parameter funkcie je smerník na hodnotu, ktorá sa použije pri vyhodnocovaní výrazu (z pohľadu funkcie vo výraze ide o "návratovú hodnotu"). Smerník je predalokovaný podľa konfiguračného parametra: Typ hodnoty objektu typu Externá funkcia.

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

Ak chcete volať externé funkcie z ESL skriptu, je potrebné do dll knižnice implementovať funkciu ADA_CALL_ROUTER, ktorá poskytuje rozhranie medzi nimi. Táto funkcia má za úlohu skontrolovať a nastaviť do potrebného tvaru parametre prichádzajúce do dll knižnice a až potom zavolať želanú funkciu. Každá dll knižnica musí implementovať vlastnú ADA_CALL_ROUTER funkciu v závislosti od exportovaných funkcií. Pri jej implementácii je možné použiť na kontrolu a spracovanie parametrov do požadovaného tvaru knižnicu ada_call_router_utils.