Akcia GETARCHARR

Funkcia

Čítanie archívnych hodnôt z časového intervalu.

Deklarácia

GETARCHARR archIdent, locVarColValueIdent_Rec, [locVarColFlagsIdent_Rec], timeFromIdent_TmA, timeToIdent_TmA, stepIdent_Int, maxValsIdent_Int, statusIdent_Int[, archivInstance_Int]

Parametre

archIdent	in	Odkaz na jednu archívnu hodnotu, odkaz na objekt alebo odkaz na položku objektu typu Štruktúrovaná premenná (poznámka: hodnoty objektu alebo položky sa musia archivovať). Upozornenie: Ak sa parameter odkazuje na objekt, ktorý je viacnásobne archivovaný, nie je určené, hodnoty ktorého archívneho objektu sa použijú pre akciu.
locVarColValueIdent_Rec	out	Odkaz na stĺpec lokálnej premennej typu RECORD pre výsledné hodnoty.
locVarColFlagsIdent_Rec	out	Nepovinný parameter. Odkaz na stĺpec lokálnej premennej typu RECORD pre archívne flagy (celočíselného typu).
timeFromItemIdent_TmA	in	Identifikátor typu AbsTime - začiatok intervalu.
timeToItemIdent_TmA	in	Identifikátor typu AbsTime - koniec intervalu.
stepIdent	in	Identifikátor typu Int - časový krok pre prevzorkovanie hodnôt v archíve. Detaily prevzorkovania - viď Poznámka o prevzorkovaní.
maxValsIdent_Int	in	Maximálny počet hodnôt. Ak je v žiadanom intervale väčší počet hodnôt, budú orezané a akcia vráti v identifikátore statusIdent_Int upozornenie _ERR_MORE_DATA.
statusIdent_Int	out	Úspešnosť čítania.
archivInstance_Int	in	Nepovinný identifikátor typu Int - identifikácia inštancie archívu. Ak nie je uvedený, nahradí sa hodnotou 0.

Popis

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. Pozri čítanie zaarchivovaných hodnôt.

Parameter stepIdent_Int určuje prevzorkovanie (v sekundách) čítaných hodnôt. Ak je jeho hodnota 0, čítanie sa neprevzorkováva.
Detaily prevzorkovania - viď Poznámka o prevzorkovaní.

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é.

Parameter locVarColValueIdent_Rec obsahuje odkaz na políčko v lokálnej premennej typu RECORD. Akcia po úspešnom načítaní hodnôt zmení veľkosť (interne akcia REDIM) poľa na potrebný počet riadkov a postupne (od 1...) naplní dané políčko v každom riadku hodnotou z archívu.
Takisto parameter locVarColFlagsIdent_Rec je odkaz na políčko v lokálnej premennej typu RECORD. Políčko musí byť typu Int. Podobne ako pri predchádzajúcom parametri, akcia zmení veľkosť poľa (veľkosti budú zhodné) a naplní dané políčko v každom riadku archívnymi príznakmi (pozri akciu GETARCHVAL). Parameter nie je povinný a môže sa vynechať. Položka pre dáta z archívu a položka pre archívne príznaky môžu byť z tej istej lokálnej premennej.

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.

Príklad

V príklade predpokladá existenciu objektu SD.ArchDemo typu Definícia štruktúry, ktorý obsahuje nasledovné položky:

Meno položky	Typ položky
Text	Text
Value	Reálne číslo
Flags	Celočíselný

Načítanie hodnôt z archívu. Hodnoty a archívne príznaky sú v dvoch rôznych poliach.

 TIME _timeFrom
 TIME _timeTo
 INT _maxVals
 INT _step
 INT _status
 
 RECORD (SD.ArchDemo) _locAValArr
 RECORD (SD.ArchDemo) _locAFlagsArr
 
 _timeTo := %StrToTime("10:00:00 31-12-1999")
 _timeFrom := %StrToTime("09:00:00 31-12-1999")
 _maxVals := 100
 _step := 0

 GETARCHARR H.ArchObj, _locAValArr^Value, _locAFlagsArr^Flags, _timeFrom, _timeTo, _step, _maxVals, _status
 IF (_status = _ERR_NO_ERROR) | (_status = _ERR_MORE_DATA) THEN
   ; dáta sú načítané
 ELSE
   ; nastala nejaká chyba
 ENDIF

Keďže počet hodnôt a archívnych príznakov je vždy zhodný, predchádzajúci príklad je možné implementovať s čítaním hodnôt aj príznakov do jedného poľa.

 TIME _timeFrom
 TIME _timeTo
 INT _maxVals
 INT _step
 INT _status
 
 RECORD (SD.ArchDemo) _locAValArr
 
 _timeTo := %StrToTime("10:00:00 31-12-1999")
 _timeFrom := %StrToTime("09:00:00 31-12-1999")
 _maxVals := 100
 _step := 0

GETARCHARR H.ArchObj, _locAValArr^Value, _locAValArr^Flags, _timeFrom, _timeTo, _step, _maxVals, _status
 IF (_status = _ERR_NO_ERROR) | (_status = _ERR_MORE_DATA) THEN
   ; dáta sú načítané
 ELSE
   ; nastala nejaká chyba
 ENDIF

Čítanie dát zo štruktúrovaného archívneho objektu.

 TIME _timeFrom
 TIME _timeTo
 INT _maxVals
 INT _step
 INT _status
 INT _row
 
 RECORD (SD.ArchDemo) _locAValArr
 
 _timeTo := %StrToTime("10:00:00 31-12-1999")
 _timeFrom := %StrToTime("09:00:00 31-12-1999")
 _maxVals := 100
 _step := 0
 _row := 4   ; 4-tý riadok
 
 GETARCHARR (H.StructArchObj\HBJ, _row, 5), _locAValArr^Value, _locAValArr^Value, _timeFrom, _timeTo, _step, _maxVals, _status
 IF (_status = _ERR_NO_ERROR) | (_status = _ERR_MORE_DATA) THEN
   ; dáta sú načítané
 ELSE
   ; nastala nejaká chyba
 ENDIF

Poznámka o prevzorkovaní

Ak je hodnota parametra stepIdent_Int nenulová, načítané dáta sú prevzorkované so špecifikovanou periódou (v sekundách). Prevzorkovanie môže byť aj s periódou väčšou ako 1 deň (86400 sekúnd), napr. 3 alebo 7 dní.

Pre periodické archívy (primárne periodické, vypočítané periodické, štatistické, skriptom plnené periodické) prevzorkovanie berie do úvahy prechod medzi letným a zimným časom v závislosti na nastavení "Použi monotónny čas" v konfigurácii čítaného archívu. Ak je napr. prevzorkovanie s periódou 86400 sekúnd a počiatočným časom "10:00:00 29-10-2021", tak budú časové značky pre stredoeurópsky (CET) čas (prechod z letného času na zimný je 31-10-2021 o 02:00) takéto:

Použi monotónny čas	Použi lokálny čas

Použi monotónny čas

Použi lokálny čas

10:00:00 29-10-2021

10:00:00 30-10-2021

09:00:00 31-10-2021

09:00:00 01-11-2021

10:00:00 29-10-2021

10:00:00 30-10-2021

10:00:00 31-10-2021

10:00:00 01-11-2021

Pri použití monotónneho času došlo prevzorkovaním k posuvu z 10:00 na 09:00, keďže 31-10-2021 o 02:00 bola vložená ďalšia hodina (takže deň 31-10-2021 mal 25 * 3600 sekúnd).
Pri použití lokálneho času sa zachováva offset v rámci dňa (10:00).

Pre neperiodické archívy (primárne zmenové, vypočítané zmenové, skriptom plnené zmenové) prevzorkovanie vždy berie do úvahy prechod medzi letným a zimným časom (tj. offset v rámci dňa sa zachová). Ak by bolo potrebné urobiť "monotónne" prevzorkovanie, je možné nakonfigurovať štatistický archív (štatistická funkcia Časový rez), ktorý je vypočítaný pri čítaní (takže nezaťažuje archívnu databázu) a má nastavené "Použi monotónny čas". Následne je potrebné čítať tento časový rez.

Rovnako je možné nakonfigurovať časový rez aj pre periodické archívy, pokiaľ je potrebné urobiť prevzorkovanie s opačným nastavením Monotónny/Lokálny čas, ako má periodický archív.

Súvisiace stránky:

Akcie v skriptoch
Akcia GETARCHARR_TO_CNT

GETARCHARR

Akcia GETARCHARR

.css-6cu6fo{box-sizing:border-box;-webkit-appearance:none;-moz-appearance:none;-ms-appearance:none;appearance:none;border:none;}Comments

Comments