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
archIdentinOdkaz 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_RecoutOdkaz na stĺpec lokálnej premennej typu RECORD pre výsledné hodnoty.
locVarColFlagsIdent_RecoutNepovinný parameter. Odkaz na stĺpec lokálnej premennej typu RECORD pre archívne flagy (celočíselného typu).
timeFromItemIdent_TmAinIdentifikátor typu AbsTime - začiatok intervalu.
timeToItemIdent_TmAinIdentifikátor typu AbsTime - koniec intervalu.
stepIdentinIdentifikátor typu Int - časový krok pre prevzorkovanie hodnôt v archíve.
Detaily prevzorkovania - viď Poznámka o prevzorkovaní.
maxValsIdent_IntinMaximá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_IntoutÚspešnosť čítania.
archivInstance_IntinNepovinný 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žkyTyp položky
TextText
ValueReálne číslo
FlagsCeločí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 časPouž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

2 komentárov

  1. Anonymný

    Aká maximálna hodnota maxValsIdent_Int môže byť použitá?

  2. D2000 Dev Team

    Veľkosť lokálnych štruktúr nie je obmedzená. Resp. je obmedzená množstvom pamäte a výkonom CPU. Teoreticky je maximálny rozmer max 2^31.

Napíšte komentár