Akcia prečíta archívne hodnoty pre archívny objekt
archIdent z časového intervalu od
timeFromIdent_TmA
do
timeToIdent_TmA s krokom
stepIdent_Int (v sekundách). Maximálny počet hodnôt je daný hodnotou identifikátora
maxValsIdent_Int.
Prečítané archívne hodnoty usporadúva do tzv. stránok. Jednotlivé stránky umiestňuje do
dátového kontajnera, ktorý akcia interne vytvorí. Jeho identifikátor (celočíselnú hodnotu) poskytne prostredníctvom parametra
pageSize. Za zrušenie obsahu kontajnera je zodpovedný užívateľ.
Akcia kontajner vytvorí vždy, ak došlo k prečítaniu nenulového počtu hodnôt (hodnoty boli načítane aj keď parameter
statusIdent_Int nadobudol hodnotu
_ERR_MORE_DATA).
Dátový kontajner vytvorený akciou GETARCHARR_TO_CNT obsahuje hodnoty na jednotlivých stránkach v pamäťovo optimálnej štruktúre, preto pre prácu s väčším množstvom dát je táto akcia vhodnejšia.
Stránky sú v kontajnery identifikované celočíselnou hodnotou od 1. Počet stránok je možné zistiť volaním akcie CNT_GETNR. K jednotlivým stránkam pristupuje akcia CNT_FIND. Akcia ako výstupný parameter
_value musí použiť lokálnu štruktúrovanú premennú (akcia zmení rozmer podľa potreby).
Ak obsahuje jeden stĺpec, tento bude naplnený hodnotami (s časovou značkou).
Ak obsahuje dva stĺpce, prvý bude naplnený hodnotami (s časovou značkou), druhý
archívnymi príznakmi.
Ak obsahuje viac stĺpcov, tieto nebudú inicializované.
Kontajner vyprázdni akcia CNT_DESTROY.
Ostatné
CNT_* akcie nie sú pre takto vytvorený kontajner povolené a ich prípadné použitie vyvolá run-time error
_ERR_INVALID_HANDLE.
Parameter
stepIdent_Int určuje prevzorkovanie (v sekundách)
čítaných hodnôt. Ak je jeho hodnota 0, čítanie sa neprevzorkováva.
Ak parameter
archIdent obsahuje odkaz na objekt typu
Archivovaná hodnota, činnosť akcie je popísaná vyššie. Ak obsahuje odkaz na objekt, ktorý nie je archívny alebo položku štruktúrovanej premennej, ktorá nie
je typu
Objekt, systém sa snaží nájsť archívny objekt (objekt typu
Archivovaná hodnota),
ktorý danú hodnotu archivuje.
Ak je parameter
archIdent odkaz na položku štruktúrovanej premennej typu
Objekt, táto ukazuje na určitý objekt v
systéme. Ak je tento objekt archívny, dáta budú načítané z neho. Ak nie je, systém sa snaží nájsť archívny objekt, ktorý danú
hodnotu archivuje.
Návratový kód
statusIdent_Int
môže nadobúdať jednu z nasledujúcich hodnôt:
- _ERR_TRANS_ABORT
- _ERR_TRANS_ERROR
- _ERR_TRANS_IGNORED
- _ERR_NO_ERROR
- _ERR_NO_DATA - v danom intervale nie sú žiadne dáta
- _ERR_MORE_DATA - v danom intervale je viac hodnôt ako maxValsIdent_Int
- _ERR_OBJECT_IS_NOT_IN_ARCHIVE
Chyba
_ERR_MORE_DATA má len informatívny charakter a žiadaný počet dát je prístupných. Ak je hodnota identifikátora
stepIdent_Int=0, hodnoty z daného časového intervalu nebudú prevzorkované.
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.