Hromadné čítanie hodnôt z archívu.

Akcia prečíta archívne hodnoty z viacerých archívnych objektov. Tieto sú určené riadkom, ktorý predstavuje parameter archIdent. Akcia pre každé políčko v danom riadku interne generuje požiadavku na čítanie dát z archívu a taktiež čaká na príchod načítaných dát. Tým že sú generované všetky požiadavky na čítanie naraz (ďalšia požiadavka nečaká na ukončenie čítania predchádzajúcej požiadavky) akcia dosahuje 50% až 200% rýchlejšie načítanie rovnakého počtu hodnôt ako ich postupné čítanie prostredníctvom akcie GETARCHARR. Toto zrýchlenie závisí od zaťaženia systému a počtu stĺpcov v riadku. Všeobecne platí, že zrýchlenie je vyššie pri viac zaťaženom systéme a väčšom množstve políčok.

Požiadavka na čítanie dát z archívu obsahuje odkaz na dáta prostredníctvom:

1. Priamo archívneho objektu (alebo položky štruktúrovaného archívneho objektu) - v tomto prípade je jednoznačne určený archívny objekt z ktorého prebehne čítanie.
   
   
2. Iného objektu v systéme (meraný bod, užívateľská premenná, ...) alebo položky lokálnej premennej typu Record - v tomto prípade systém automaticky vyhľadá archívny objekt, ktorý archivuje objekt špecifikovaný v požiadavke (napríklad: Ak požiadavka obsahuje odkaz na meraný bod, ktorý je archivovaný, systém automaticky túto požiadavku konvertuje na požiadavku čítania z daného archívneho objektu). Ak takýto neexistuje, akcia je ukončená s chybou _ERR_ARCHIV_NOT_RUNNING.

Parameter archIdent môže byť zapísaný jedným z nasledujúcich spôsobov:

1. Riadok lokálnej premennej typu „typový ALIAS“
   Príklad:
   ALIAS (definícia štruktúry) _lAT
   SET _lAT AS SV.Struct
   GETARCHROW _lAT[4] , ...
   
   Jednotlivé požiadavky na čítanie budú VŽDY adresované na položky štruktúry SV.Struct v danom riadku (aj v prípade, že niektorá položka je typu Objekt).
   
   
2. Riadok objektu typu Štruktúrovaná premenná
   Príklad:
   GETARCHROW SV.Struct[4] , ...
   
   Adresovanie požiadavky prebieha podľa tých istých pravidiel ako v bode 1.
   
   
3. Riadok lokálnej premennej typu Record
   Príklad:
   RECORD (definícia štruktúry) _lRec
   REDIM _lRec[10]
   
   SET _lRec[4]^Item1 AS Sec
   SET _lRec[4]^Item2 AS SysTime
   SET _lRec[4]^Item3 AS M.MeranyBod
   .....
   
   GETARCHROW _lRec[4], ...
   
   Akcia vyžaduje, aby všetky stĺpce v použitej definícii štruktúry boli typu Objekt. Jednotlivé požiadavky na čítanie budú adresované na objekty, na ktoré smerujú položky v danom riadku.
   Ak niektoré políčko nebude smerované na objekt, akcia končí s chybou ERR_NO_ASSIGNED_ALIAS.
   
   
4. Riadok štruktúrovaného archívneho objektu
   Príklad:
   GETARCHROW H.Struct[4], ...
   
   Jednotlivé požiadavky na čítanie budú adresované postupne na všetky položky v danom riadku. H.Struct nemôže byť jedno-stĺpcový archívny objekt.
   

Výsledok čítania je uložený do lokálnej premennej _locRecDstIdent. Výsledkom každej požiadavky na čítanie je jedna hodnota alebo postupnosť hodnôt. Tieto sú usporiadané v čase vzostupne a sú ukladané po riadkoch do príslušného stĺpca lokálnej premennej _locRecDstIdent. Štruktúrované premenné archIdent a _locRecDstIdent musia mať rovnaký typ štruktúry (tým je zaručený rovnaký počet stĺpcov). Akcia automaticky redimenzuje premennú _locRecDstIdent na potrebný počet riadkov (je daný najväčším počtom hodnôt vo výsledku čítania archívu).

Parametre timeFromIdent_TmA a timeToIdent_TmA určujú časový interval, z ktorého sú čítané hodnoty.
Parameter stepIdent_Int určuje prevzorkovanie (v sekundách) čítaných hodnôt. Ak je jeho hodnota 0, čítanie sa neprevzorkováva. Preto ak je hodnota rôzna od 0, vo výslednej štruktúre budú mať všetky hodnoty v jednom riadku rovnaký čas vzniku a každý stĺpec bude obsahovať načítané hodnoty až po posledný riadok. Ak je hodnota 0, rozmer výslednej štruktúry je daný maximálnym počtom prečítaných hodnôt na jednu požiadavku. Preto nie všetky stĺpce budú obsahovať prečítané hodnoty z archívu až po posledný riadok.
Ak je parameter timeToIdent_TmA väčší ako aktuálny čas a zároveň parameter stepIdent_Int je rôzny od nuly, prevzorkované hodnoty s časom v budúcnosti budú neplatné.

Hodnota parametra archivInstance_Int udáva inštanciu archívu, ktorá realizuje požiadavku. Ak nie je uvedený (alebo má hodnotu 0) požiadavku realizuje aktívna inštancia archívu.

Úspešnosť čítania akcie obsahuje premenná statusIdent_Int. Ak premenná statusIdent_Int nadobudne hodnotu _ERR_NO_DATA(22), znamená, že všetky archívy, ktoré sa použili pri čítaní, neobsahujú dáta. Ak aspoň jeden obsahuje dáta, akcia vráti _ERR_NO_ERR(0).

Akcie GETARCH* - príklad