GetHistoryData - metoda objektu PmaEventGroup

Popis:

Získá data z historie eventů , které vyhovují zadanému filtračnímu textu.

Syntaxe:

Array GetHistoryData(String sColumns, String sFilter)

Parametry:

sColumns	(String) Seznam identifikátorů požadovaných sloupců (vlastností) event položek (oddělené čárkou), například "Desc,TimeOn,TimeOff,TimeAck". "TimeOn" - Čas aktivace "GlobalId" - Identifikátor event položky ve skupině "Priority" - Priorita event položky 0 - nízká 1 2 3 4 5 - střední 6 7 8 9 10 - vysoká "Area" - Označení oblasti event položky "Source" - Označení zdroje event položky "Desc" - Popis event položky "Comment" - Komentář event položky "UserNote" - Uživatelská poznámka event položky
sFilter	(String) Filtrační text určující, které eventy se mají zahrnovat do požadovaného výsledku. Různá filtrační pole mohou být použita i současně, event potom musí vyhovavat všem (např. "desc:FIQ100;priority.ge:5;"). Filtrační text xx nesmí být prázdný řetězec (např. nelze zadat "desc:;"). Údaje jsou zde ve formátu KeyVal, například "desc:Test2;records:50;". Existují následující druhy filtračních textů ("field" představuje některý sloupec eventů): "field:xx;" znamená, že příslušné pole eventu se musí rovnat hodnotě xx. "field:#eq:xx;" znamená, že příslušné pole eventu se musí rovnat hodnotě xx. Pokud příslušné pole eventu se má rovnat jednomu z několika textů, pak lze zadat více textů oddělených #or:. "field:#begin:xx;" znamená, že příslušné pole eventu musí začínat textem xx. Pokud příslušné pole eventu má začínat na některý z několika textů, pak lze zadat více textů oddělených #or:. "field:#in:xx;" znamená, že příslušné pole eventu musí uvnitř obsahovat text xx. Pokud příslušné pole eventu má obsahovat některý z několika textů, pak lze zadat více textů oddělených #or:. "field:#le:xx;" znamená, že příslušné pole eventu musí být menší nebo rovno číslu xx. "field:#ge:xx;" znamená, že příslušné pole eventu musí být větší nebo rovno číslu xx. Poznámka! Pokud pole začíná textem s., pak se jedná o volbu skrytou koncovému uživateli v prohlížeči historie eventů a slouží pro nastavení pevné filtrace skriptem nezávisle na nastavení uživatelské části filtru. Pro stejný sloupec lze použít oba typy filtračních polí současně. Aby event vyhověl, musí vyhovět oběma filtračním polím. Toho lze s výhodou využít pro nastavení pevné filtrace skriptem (neovlivnitelné koncovým uživatelem) a současně nastavit i počáteční stav uživatelské filtrace (měnitelnou koncovým uživatelem). Například s.source:#begin:Kotel;source:Kotel1;. "area:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž oblast (area) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů. Například "area:Kotelna1;" nebo "area:#eq:Kotelna1;" nebo "area:#eq:Kotelna1#or:Kotelna2;" nebo "area:#begin:Kotelna;". "s.area:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž oblast (area) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů. Například "s.area:Kotelna1;" nebo "s.area:#eq:Kotelna1;" nebo "s.area:#eq:Kotelna1#or:Kotelna2;" nebo "s.area:#begin:Kotelna;". "source:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž zdroj (source) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů. Například "source:Kotel;" nebo "source:#eq:Kotel;" nebo "source:#eq:Kotel1#or:Kotel2;" nebo "source:#begin:Kotel;". "s.source:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž zdroj (source) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů. Například "s.source:Kotel;" nebo "s.source:#eq:Kotel;" nebo "s.source:#eq:Kotel1#or:Kotel2;" nebo "s.source:#begin:Kotel;". "desc:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž popis (desc) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů. Například "desc:FIQ101;" nebo "desc:#eq:FIQ101;" nebo "desc:#eq:FIQ101#or:FIQ102;" nebo "desc:#begin:FIQ;". "s.desc:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž popis (desc) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů. Například "s.desc:FIQ101;" nebo "s.desc:#eq:FIQ101;" nebo "s.desc:#eq:FIQ101#or:FIQ102;" nebo "s.desc:#begin:FIQ;". "comment:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž komentář (comment) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů. Například "comment:oprava;" nebo "comment:#eq:oprava;" nebo "comment:#eq:oprava#or:test;" nebo "comment:#begin:oprava;". "s.comment:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž komentář (comment) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů. Například "s.comment:oprava;" nebo "s.comment:#eq:oprava;" nebo "s.comment:#eq:oprava#or:test;" nebo "s.comment:#begin:oprava;". "s.usernote:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž poznámka (usernote) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů. Například "s.usernote:oprava;" nebo "s.usernote:#eq:oprava;" nebo "s.usernote:#eq:oprava#or:test;" nebo "s.usernote:#begin:oprava;". "priority:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž priorita (priority) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů. Například "priority:5;" nebo "priority:#eq:5;" nebo "priority:#le:5;" nebo "priority:#ge:5;". "from:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) je větší nebo rovno času "xx". Čas se zadává v podobě time(YYYY.MM.DD-hh:mm:ss.mmm), např. "from:time(2023.07.28-14:30:00.000);". Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují). "to:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) je menší nebo rovno času "xx". Čas se zadává v podobě time(YYYY.MM.DD-hh:mm:ss.mmm), např. "to:time(2023.07.28-15:00:00.000);". Čas to lze zadat i pomocí klíčového slova now, které znamená do aktualního času (v okamžiku volání), např. to:now. Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují). "timerange:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) leží v zadaném časovém rozsahu. Pro určení časového rozpětí pomocí timerange, musí být zadané buď from nebo to, kde timerange umožňuje dopočítat druhou chybějící mez časového rozsahu. Časový rozsah lze tedy zadat pomocí následujících dvojic: from - to, from - timerange nebo to - timerange. Například to:now;timerange:30m;. Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují). Časový rozsah lze zadat jako celé číslo následované znakem časové jednotky (bez mezery). Časové jednotky jsou: w = týden, d = den, h = hodina, m = minuta, s = sekunda. Například timerange:12h; nebo timerange:90m;. "records:xx;" (nepovinné) - Umožňuje zadat (omezit) počet požadovaných eventů, splňujících filtrační kritéria. Po dosažení zadaného počtu nalezených eventů se prohledávání eventů ukončí. Spolu s určením časového rozpětí umožňuje omezovat prohledávaní eventů na omezenou část eventů. Normální filtr by totiž procházel všechny eventy ve všech zálohách. Z praktických důvodů je tedy vhodné filtraci omezit pouze na nutnou a užitečnou část historie eventů. "scanrecords:xx;" (nepovinné) - Umožňuje zadat (omezit) počet všech testovaných (procházených) eventů, bez ohledu na to, zda eventy splňují nebo nesplňují filtrační kritérium. Po dosažení zadaného počtu testovaných eventů se prohledávání ukončí. Tato volba zabrání, aby se při nenalezení požadovaného počtu eventů splňujích filtrační kritérium, neprohledávalo zbytečně mnoho eventů v historii. "scanstart:xx;" (nepovinné) - (pouze historie) Umožňuje změnit implicitní směr prohledávaní (odkud se začne s prohledávaním). Zadává se v podobě scanstart:from; nebo scanstart:to;. Pokud není časový rozsah vůbec určen nebo pokud je zadán to (může být i společně s from nebo s timerange), pak je implicitní směr prohledávaní od novějších ke starším. Pokud je zadán pouze from (může být i společně s timerange), pak je implicitní směr prohledávaní od starších k novějším. Používat scanstart má smysl zejména, pokud časový rozsah je zadán pomocí from a to a pokud je nutno změnit směr prohledávaní na od starších k mladším položkám (scanstart:start;). "lang:xx;" (nepovinné) - (pouze skriptovací metody) Určuje jazyk, pro který budou vyhodnocené lokalizované texty. Jazyk je určen textovým identifikátorem, např. "cs", "sk", "en" atd. - viz Jazyky s plnou podporou v systému PROMOTIC. Pokud není nastaveno, pak použije se právě používaný jazyk aplikace - normálně se tedy tato volba nemusí zadávat. Viz konfigurátor "Hlavní jazyk runtime". "headers:xx;" (nepovinné) - (pouze skriptovací metody) Určuje, zda výsledný seznam bude obsahovat (první a/nebo druhý řádek) i názvy sloupců (lokalizované texty) pro následné zobrazení. title - První/druhý řádek výsledného seznamu bude obsahovat názvy sloupců (lokalizované texty) pro následné zobrazení. id - První/druhý řádek výsledného seznamu bude obsahovat systémové názvy sloupců (identifikátory) pro následné zobrazení.

sColumns

(String) Seznam identifikátorů požadovaných sloupců (vlastností) event položek (oddělené čárkou), například "Desc,TimeOn,TimeOff,TimeAck".

"TimeOn" - Čas aktivace

"GlobalId" - Identifikátor event položky ve skupině

"Priority" - Priorita event položky

0 - nízká

5 - střední

10 - vysoká

"Area" - Označení oblasti event položky

"Source" - Označení zdroje event položky

"Desc" - Popis event položky

"Comment" - Komentář event položky

"UserNote" - Uživatelská poznámka event položky

sFilter

(String) Filtrační text určující, které eventy se mají zahrnovat do požadovaného výsledku.
Různá filtrační pole mohou být použita i současně, event potom musí vyhovavat všem (např. "desc:FIQ100;priority.ge:5;").
Filtrační text xx nesmí být prázdný řetězec (např. nelze zadat "desc:;").
Údaje jsou zde ve formátu KeyVal, například "desc:Test2;records:50;".

Existují následující druhy filtračních textů ("field" představuje některý sloupec eventů):

"field:xx;" znamená, že příslušné pole eventu se musí rovnat hodnotě xx.

"field:#eq:xx;" znamená, že příslušné pole eventu se musí rovnat hodnotě xx. Pokud příslušné pole eventu se má rovnat jednomu z několika textů, pak lze zadat více textů oddělených #or:.

"field:#begin:xx;" znamená, že příslušné pole eventu musí začínat textem xx. Pokud příslušné pole eventu má začínat na některý z několika textů, pak lze zadat více textů oddělených #or:.

"field:#in:xx;" znamená, že příslušné pole eventu musí uvnitř obsahovat text xx. Pokud příslušné pole eventu má obsahovat některý z několika textů, pak lze zadat více textů oddělených #or:.

"field:#le:xx;" znamená, že příslušné pole eventu musí být menší nebo rovno číslu xx.

"field:#ge:xx;" znamená, že příslušné pole eventu musí být větší nebo rovno číslu xx.

Poznámka! Pokud pole začíná textem s., pak se jedná o volbu skrytou koncovému uživateli v prohlížeči historie eventů a slouží pro nastavení pevné filtrace skriptem nezávisle na nastavení uživatelské části filtru. Pro stejný sloupec lze použít oba typy filtračních polí současně. Aby event vyhověl, musí vyhovět oběma filtračním polím. Toho lze s výhodou využít pro nastavení pevné filtrace skriptem (neovlivnitelné koncovým uživatelem) a současně nastavit i počáteční stav uživatelské filtrace (měnitelnou koncovým uživatelem). Například s.source:#begin:Kotel;source:Kotel1;.

"area:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž oblast (area) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů.
Například "area:Kotelna1;" nebo "area:#eq:Kotelna1;" nebo "area:#eq:Kotelna1#or:Kotelna2;" nebo "area:#begin:Kotelna;".

"s.area:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž oblast (area) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů.
Například "s.area:Kotelna1;" nebo "s.area:#eq:Kotelna1;" nebo "s.area:#eq:Kotelna1#or:Kotelna2;" nebo "s.area:#begin:Kotelna;".

"source:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž zdroj (source) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů.
Například "source:Kotel;" nebo "source:#eq:Kotel;" nebo "source:#eq:Kotel1#or:Kotel2;" nebo "source:#begin:Kotel;".

"s.source:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž zdroj (source) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů.
Například "s.source:Kotel;" nebo "s.source:#eq:Kotel;" nebo "s.source:#eq:Kotel1#or:Kotel2;" nebo "s.source:#begin:Kotel;".

"desc:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž popis (desc) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů.
Například "desc:FIQ101;" nebo "desc:#eq:FIQ101;" nebo "desc:#eq:FIQ101#or:FIQ102;" nebo "desc:#begin:FIQ;".

"s.desc:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž popis (desc) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů.
Například "s.desc:FIQ101;" nebo "s.desc:#eq:FIQ101;" nebo "s.desc:#eq:FIQ101#or:FIQ102;" nebo "s.desc:#begin:FIQ;".

"comment:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž komentář (comment) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů.
Například "comment:oprava;" nebo "comment:#eq:oprava;" nebo "comment:#eq:oprava#or:test;" nebo "comment:#begin:oprava;".

"s.comment:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž komentář (comment) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů.
Například "s.comment:oprava;" nebo "s.comment:#eq:oprava;" nebo "s.comment:#eq:oprava#or:test;" nebo "s.comment:#begin:oprava;".

"s.usernote:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž poznámka (usernote) splňuje danou operaci #oper:xx. Část filtru skrytá koncovému uživateli v prohlížeči historie eventů.
Například "s.usernote:oprava;" nebo "s.usernote:#eq:oprava;" nebo "s.usernote:#eq:oprava#or:test;" nebo "s.usernote:#begin:oprava;".

"priority:#oper:xx;" (nepovinné) - Zobrazí eventy, jejichž priorita (priority) splňuje danou operaci #oper:xx. Část filtru měnitelná koncovým uživatelem v prohlížeči historie eventů.
Například "priority:5;" nebo "priority:#eq:5;" nebo "priority:#le:5;" nebo "priority:#ge:5;".

"from:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) je větší nebo rovno času "xx". Čas se zadává v podobě time(YYYY.MM.DD-hh:mm:ss.mmm), např. "from:time(2023.07.28-14:30:00.000);". Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují).

"to:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) je menší nebo rovno času "xx". Čas se zadává v podobě time(YYYY.MM.DD-hh:mm:ss.mmm), např. "to:time(2023.07.28-15:00:00.000);".
Čas to lze zadat i pomocí klíčového slova now, které znamená do aktualního času (v okamžiku volání), např. to:now.
Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují).

"timerange:xx;" (nepovinné) - Zobrazí eventy, jejichž čas vzniku (timeon) leží v zadaném časovém rozsahu. Pro určení časového rozpětí pomocí timerange, musí být zadané buď from nebo to, kde timerange umožňuje dopočítat druhou chybějící mez časového rozsahu. Časový rozsah lze tedy zadat pomocí následujících dvojic: from - to, from - timerange nebo to - timerange. Například to:now;timerange:30m;. Časový rozsah umožňuje omezit prohledávanou část eventů (eventy mimo časový rozsah se netestují).
Časový rozsah lze zadat jako celé číslo následované znakem časové jednotky (bez mezery). Časové jednotky jsou: w = týden, d = den, h = hodina, m = minuta, s = sekunda. Například timerange:12h; nebo timerange:90m;.

"records:xx;" (nepovinné) - Umožňuje zadat (omezit) počet požadovaných eventů, splňujících filtrační kritéria. Po dosažení zadaného počtu nalezených eventů se prohledávání eventů ukončí.
Spolu s určením časového rozpětí umožňuje omezovat prohledávaní eventů na omezenou část eventů. Normální filtr by totiž procházel všechny eventy ve všech zálohách. Z praktických důvodů je tedy vhodné filtraci omezit pouze na nutnou a užitečnou část historie eventů.

"scanrecords:xx;" (nepovinné) - Umožňuje zadat (omezit) počet všech testovaných (procházených) eventů, bez ohledu na to, zda eventy splňují nebo nesplňují filtrační kritérium. Po dosažení zadaného počtu testovaných eventů se prohledávání ukončí. Tato volba zabrání, aby se při nenalezení požadovaného počtu eventů splňujích filtrační kritérium, neprohledávalo zbytečně mnoho eventů v historii.

"scanstart:xx;" (nepovinné) - (pouze historie) Umožňuje změnit implicitní směr prohledávaní (odkud se začne s prohledávaním). Zadává se v podobě scanstart:from; nebo scanstart:to;.
Pokud není časový rozsah vůbec určen nebo pokud je zadán to (může být i společně s from nebo s timerange), pak je implicitní směr prohledávaní od novějších ke starším.
Pokud je zadán pouze from (může být i společně s timerange), pak je implicitní směr prohledávaní od starších k novějším.
Používat scanstart má smysl zejména, pokud časový rozsah je zadán pomocí from a to a pokud je nutno změnit směr prohledávaní na od starších k mladším položkám (scanstart:start;).

"lang:xx;" (nepovinné) - (pouze skriptovací metody) Určuje jazyk, pro který budou vyhodnocené lokalizované texty. Jazyk je určen textovým identifikátorem, např. "cs", "sk", "en" atd. - viz Jazyky s plnou podporou v systému PROMOTIC. Pokud není nastaveno, pak použije se právě používaný jazyk aplikace - normálně se tedy tato volba nemusí zadávat. Viz konfigurátor "Hlavní jazyk runtime".

"headers:xx;" (nepovinné) - (pouze skriptovací metody) Určuje, zda výsledný seznam bude obsahovat (první a/nebo druhý řádek) i názvy sloupců (lokalizované texty) pro následné zobrazení.

title - První/druhý řádek výsledného seznamu bude obsahovat názvy sloupců (lokalizované texty) pro následné zobrazení.

id - První/druhý řádek výsledného seznamu bude obsahovat systémové názvy sloupců (identifikátory) pro následné zobrazení.

Vrácená hodnota:

objekt PmArray pro JavaScript nebo datový typ Array pro VBScript.

Poznámka:

Implementace filtrace event položek má tendenci prohledávat a testovat všechny dostupné eventy v historii.
Aby se s každým dotazem neprohlédavaly všechny položky, je nutno omezit dotaz (filtrační kritérium) na menší část eventů. Omezení lze dosáhnout jednak pomocí zadaného časového rozpětí, kdy se prohlédavají a testují pouze položky z tohoto časového rozpětí. Další omezení lze docílit pomocí zadání počtu požadovaných nalezených event položek a také pomocí maximálního počtu prohlédávaných event položek. U omezené části eventů, která se bude prohledávat, lze určit směr prohledávaní (scanstart), nicméně výsledek prohledávaní je vždy setříděný stejně. Změna směru prohledávaní má tedy smysl pouze pokud je navíc ještě doplněna omezením požadovaného počtu prohledávaných (scanrecords) nebo nalezených (records) položek. Potom má směr prohledávaní smysl, protože určuje, na které straně časového rozpětí mohou případně chybět eventy, díky aplikaci omezením položek.

Viz také:

- Systém alarmů a Eventů

- Otevření prohlížeče objektu PmaEventGroup

- Jak pracovat s polem hodnot v systému PROMOTIC

Příklad1:

Získá posledních (nejnovějších) 50 eventů records:50;scanrecords:500; (hodnoty požadovaných sloupců), splňujících filtrační kritérium (desc:Test2;).

JavaScriptVBScriptVyber a zkopíruj do schránky



var oEv = pMe.Pm("/Event");

var a = oEv.GetHistoryData("Desc,TimeOn,TimeOff,TimeAck", "desc:Test2;records:50;scanrecords:500;");

Příklad2:

Získá všechny eventy (hodnoty požadovaných sloupců), splňujících filtrační kritérium (desc:Test2;) za posledních 8 hodin (timerange:8h;) vzhledem k zadanému času (to:time(2023.07.20-06:00:00.000);) a s omezením na maximální počet prohledávaných a vrácených vět records:50;scanrecords:500;. Získat i anglické názvy sloupců v prvním řádku.

JavaScriptVBScriptVyber a zkopíruj do schránky



var oEv = pMe.Pm("/Event");

var a = oEv.GetHistoryData("Desc,TimeOn,TimeOff,TimeAck", "desc:Test2;to:time(2023.07.20-06:00:00.000);timerange:8h;records:50;scanrecords:500;lang:en;headers:title;");