GetHistoryData - method of the PmaEventGroup object

Description:

Obtains the data from event history that fit the specified filtering text.

Syntax:

Array GetHistoryData(String sColumns, String sFilter)

Parameters:

sColumns	(String) List of desired column (property) identificators of event items (separated by comma), for example "Desc,TimeOn,TimeOff,TimeAck". "TimeOn" - Activation time "GlobalId" - Identifier of the event item in the group "Priority" - Priority of the event item 0 - low 1 2 3 4 5 - medium 6 7 8 9 10 - high "Area" - Marking area of the event item "Source" - Marking source of the event item "Desc" - Event item description "Comment" - Event item comment "UserNote" - Event item user note
sFilter	(String) Filtering text that specifies which events are to be included into the desired output. Different filtration fields can be used simultaneously, the event then must comply with all of them (e.g. "desc:FIQ100;priority.ge:5;"). The filtering text xx must not be empty string (e.g. it is not possible to enter "desc:;"). Entries are in the KeyVal format, for example "desc:Test2;records:50;". The folowing types of filtration texts exist ("field" represents some of events column): "field:xx;" means that the corresponding event field must be equal to the value of xx. "field:#eq:xx;" means that the corresponding event field must be equal to the value of xx. If the corresponding event field is to be equal to one of several texts, then can be entered multiple texts separated by #or:. "field:#begin:xx;" means that the corresponding event field must begin with the text xx. If the corresponding event field is to begin with some of several texts, then can be entered multiple texts separated by #or:. "field:#in:xx;" means that the corresponding event field must contain the text xx. If the corresponding event field is to contain some of several texts, then can be entered multiple texts separated by #or:. "field:#le:xx;" means that the corresponding event field must be less then or equal to xx. "field:#ge:xx;" means that the corresponding event field must be greater or equal to xx. Note! If the field begins with the text s., then this is the setting hidden from the enduser in the event viewer and serves for setting the definite script filtration independently on end user settings. Both filtration type fields can be used for a single column simultaneously. In order to let the event pass the filter it must comly to both filtering fields. This can be handy for definite script filtrations (independent on enduser) and also for setting the initial state of user defined filtration (can be modified by the enduser). For example s.source:#begin:Boiler;source:Boiler1;. "area:#oper:xx;" (optional) - Displays events with area meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer. For example "area:BoilerPlant1;" or "area:#eq:BoilerPlant1;" or "area:#eq:BoilerPlant1#or:BoilerPlant2;" or "area:#begin:BoilerPlant;". "s.area:#oper:xx;" (optional) - Displays events with area meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer. For example "s.area:BoilerPlant1;" or "s.area:#eq:BoilerPlant1;" or "s.area:#eq:BoilerPlant1#or:BoilerPlant2;" or "s.area:#begin:BoilerPlant;". "source:#oper:xx;" (optional) - Displays events with source meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer. For example "source:Boiler;" or "source:#eq:Boiler;" or "source:#eq:Boiler1#or:Boiler2;" or "source:#begin:Boiler;". "s.source:#oper:xx;" (optional) - Displays events with source meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer. For example "s.source:Boiler;" or "s.source:#eq:Boiler;" or "s.source:#eq:Boiler1#or:Boiler2;" or "s.source:#begin:Boiler;". "desc:#oper:xx;" (optional) - Displays events with description (desc) meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer. For example "desc:FIQ101;" or "desc:#eq:FIQ101;" or "desc:#eq:FIQ101#or:FIQ102;" or "desc:#begin:FIQ;". "s.desc:#oper:xx;" (optional) - Displays events with description (desc) meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer. For example "s.desc:FIQ101;" or "s.desc:#eq:FIQ101;" or "s.desc:#eq:FIQ101#or:FIQ102;" or "s.desc:#begin:FIQ;". "comment:#oper:xx;" (optional) - Displays events with comment meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer. For example "comment:correction;" or "comment:#eq:correction;" or "comment:#eq:correction#or:test;" or "comment:#begin:correction;". "s.comment:#oper:xx;" (optional) - Displays events with comment meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer. For example "s.comment:correction;" or "s.comment:#eq:correction;" or "s.comment:#eq:correction#or:test;" or "s.comment:#begin:correction;". "s.usernote:#oper:xx;" (optional) - Displays events with usernote meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer. For example "s.usernote:correction;" or "s.usernote:#eq:correction;" or "s.usernote:#eq:correction#or:test;" or "s.usernote:#begin:correction;". "priority:#oper:xx;" (optional) - Displays events whose priority meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer. For example "priority:5;" or "priority:#eq:5;" or "priority:#le:5;" or "priority:#ge:5;". "from:xx;" (optional) - Displays the events with the creation time (timeon) greater or equal to time "xx". The time is entered in the form time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. "from:time(2025.07.28-14:30:00.000);". The Time-range allows to narrow down the searched event set (events outside the time-range are not tested). "to:xx;" (optional) - Displays the events with the creation time (timeon) less then or equal to time "xx". The time is entered in the form time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. "to:time(2025.07.28-15:00:00.000);". The to time can be entered also by the now keyword, which means the current time (at the moment of calling), e.g. to:now. The Time-range allows to narrow down the searched event set (events outside the time-range are not tested). "timerange:xx;" (optional) - Displays the events with the creation time (timeon) belonging to specified time-range For selecting the time span by timerange, the value of either from or to must be defined, where the timerange allows to compute the missing limit of the time-range. Thus the time-range can be defined by the following pairs: from - to, from - timerange or to - timerange. For example to:now;timerange:30m;. Time-range allows to reduce the portion of event items to be searched (events outside the time-range are not tested). The time-range can be entered as integer followed by time unit sign (without space). Valid time units are: w = week, d = day, h = hour, m = minute, s = second. For example timerange:12h; or timerange:90m;. "records:xx;" (optional) - It allows to set (reduce) the number of desired events, satisfying the filter criteria. The event search is terminated after the number of found items reaches the defined count. Together with the time span limitation the events can also be limited to a certain portion. Using the normal filter would make the search go through all the events including the backup records. It is therefore handy to limit the filters in order to search only the desired portion of the event history. "scanrecords:xx;" (optional) - It allows to set (reduce) the number of all tested (browsed) events, regardless of whether the events meet the filter criteria or not. After the number of tested events reaches the defined value the testing is terminated. This option allows to prevent the system from searching within too many events in history if the number of desired search results is not reached. "scanstart:xx;" (optional) - (history only) It allows to change the default direction of searching (where the search begins). It is defined in the form scanstart:from; or scanstart:to;. If the time-range is not defined or if to is defined (can be set together with from or with timerange), then the default search direction is from newer to older items. If only from is defined (can be set together with timerange), then the default search direction is from older to newer items. Using the scanstart is handy particulary if the time-range is defined by from and to and if it is necessary to change the search direction from older to newer items (scanstart:start;). "lang:xx;" (optional) - (only scripting methods) Specifies the language to be used for evaluated localized texts. Language is determined with a text identifier, e.g. "en", "de", "ru" etc. - see Fully supported languages in the PROMOTIC system. If not set, then the language currently used in the application will be used - therefore it is not necessary to define this option under normal circumstances. See the "Main language of runtime" configurator. "headers:xx;" (optional) - (only scripting methods) Specifies whether the output list will contain (on first and/or second row) also the column names (localized texts) while being viewed. title - The first/second row of the output list will contain the column names (localized texts) while being viewed. id - The first/second row of the output list will contain the system column names (identifiers) while being viewed.

sColumns

(String) List of desired column (property) identificators of event items (separated by comma), for example "Desc,TimeOn,TimeOff,TimeAck".

"TimeOn" - Activation time

"GlobalId" - Identifier of the event item in the group

"Priority" - Priority of the event item

0 - low

5 - medium

10 - high

"Area" - Marking area of the event item

"Source" - Marking source of the event item

"Desc" - Event item description

"Comment" - Event item comment

"UserNote" - Event item user note

sFilter

(String) Filtering text that specifies which events are to be included into the desired output.
Different filtration fields can be used simultaneously, the event then must comply with all of them (e.g. "desc:FIQ100;priority.ge:5;").
The filtering text xx must not be empty string (e.g. it is not possible to enter "desc:;").
Entries are in the KeyVal format, for example "desc:Test2;records:50;".

The folowing types of filtration texts exist ("field" represents some of events column):

"field:xx;" means that the corresponding event field must be equal to the value of xx.

"field:#eq:xx;" means that the corresponding event field must be equal to the value of xx. If the corresponding event field is to be equal to one of several texts, then can be entered multiple texts separated by #or:.

"field:#begin:xx;" means that the corresponding event field must begin with the text xx. If the corresponding event field is to begin with some of several texts, then can be entered multiple texts separated by #or:.

"field:#in:xx;" means that the corresponding event field must contain the text xx. If the corresponding event field is to contain some of several texts, then can be entered multiple texts separated by #or:.

"field:#le:xx;" means that the corresponding event field must be less then or equal to xx.

"field:#ge:xx;" means that the corresponding event field must be greater or equal to xx.

Note! If the field begins with the text s., then this is the setting hidden from the enduser in the event viewer and serves for setting the definite script filtration independently on end user settings. Both filtration type fields can be used for a single column simultaneously. In order to let the event pass the filter it must comly to both filtering fields. This can be handy for definite script filtrations (independent on enduser) and also for setting the initial state of user defined filtration (can be modified by the enduser). For example s.source:#begin:Boiler;source:Boiler1;.

"area:#oper:xx;" (optional) - Displays events with area meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer.
For example "area:BoilerPlant1;" or "area:#eq:BoilerPlant1;" or "area:#eq:BoilerPlant1#or:BoilerPlant2;" or "area:#begin:BoilerPlant;".

"s.area:#oper:xx;" (optional) - Displays events with area meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer.
For example "s.area:BoilerPlant1;" or "s.area:#eq:BoilerPlant1;" or "s.area:#eq:BoilerPlant1#or:BoilerPlant2;" or "s.area:#begin:BoilerPlant;".

"source:#oper:xx;" (optional) - Displays events with source meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer.
For example "source:Boiler;" or "source:#eq:Boiler;" or "source:#eq:Boiler1#or:Boiler2;" or "source:#begin:Boiler;".

"s.source:#oper:xx;" (optional) - Displays events with source meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer.
For example "s.source:Boiler;" or "s.source:#eq:Boiler;" or "s.source:#eq:Boiler1#or:Boiler2;" or "s.source:#begin:Boiler;".

"desc:#oper:xx;" (optional) - Displays events with description (desc) meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer.
For example "desc:FIQ101;" or "desc:#eq:FIQ101;" or "desc:#eq:FIQ101#or:FIQ102;" or "desc:#begin:FIQ;".

"s.desc:#oper:xx;" (optional) - Displays events with description (desc) meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer.
For example "s.desc:FIQ101;" or "s.desc:#eq:FIQ101;" or "s.desc:#eq:FIQ101#or:FIQ102;" or "s.desc:#begin:FIQ;".

"comment:#oper:xx;" (optional) - Displays events with comment meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer.
For example "comment:correction;" or "comment:#eq:correction;" or "comment:#eq:correction#or:test;" or "comment:#begin:correction;".

"s.comment:#oper:xx;" (optional) - Displays events with comment meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer.
For example "s.comment:correction;" or "s.comment:#eq:correction;" or "s.comment:#eq:correction#or:test;" or "s.comment:#begin:correction;".

"s.usernote:#oper:xx;" (optional) - Displays events with usernote meets the defined operation #oper:xx. The part of the filter hidden from the user in the event viewer.
For example "s.usernote:correction;" or "s.usernote:#eq:correction;" or "s.usernote:#eq:correction#or:test;" or "s.usernote:#begin:correction;".

"priority:#oper:xx;" (optional) - Displays events whose priority meets the defined operation #oper:xx. The part of the filter dependent on user setting in the event viewer.
For example "priority:5;" or "priority:#eq:5;" or "priority:#le:5;" or "priority:#ge:5;".

"from:xx;" (optional) - Displays the events with the creation time (timeon) greater or equal to time "xx". The time is entered in the form time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. "from:time(2025.07.28-14:30:00.000);". The Time-range allows to narrow down the searched event set (events outside the time-range are not tested).

"to:xx;" (optional) - Displays the events with the creation time (timeon) less then or equal to time "xx". The time is entered in the form time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. "to:time(2025.07.28-15:00:00.000);".
The to time can be entered also by the now keyword, which means the current time (at the moment of calling), e.g. to:now.
The Time-range allows to narrow down the searched event set (events outside the time-range are not tested).

"timerange:xx;" (optional) - Displays the events with the creation time (timeon) belonging to specified time-range For selecting the time span by timerange, the value of either from or to must be defined, where the timerange allows to compute the missing limit of the time-range. Thus the time-range can be defined by the following pairs: from - to, from - timerange or to - timerange. For example to:now;timerange:30m;. Time-range allows to reduce the portion of event items to be searched (events outside the time-range are not tested).
The time-range can be entered as integer followed by time unit sign (without space). Valid time units are: w = week, d = day, h = hour, m = minute, s = second. For example timerange:12h; or timerange:90m;.

"records:xx;" (optional) - It allows to set (reduce) the number of desired events, satisfying the filter criteria. The event search is terminated after the number of found items reaches the defined count.
Together with the time span limitation the events can also be limited to a certain portion. Using the normal filter would make the search go through all the events including the backup records. It is therefore handy to limit the filters in order to search only the desired portion of the event history.

"scanrecords:xx;" (optional) - It allows to set (reduce) the number of all tested (browsed) events, regardless of whether the events meet the filter criteria or not. After the number of tested events reaches the defined value the testing is terminated. This option allows to prevent the system from searching within too many events in history if the number of desired search results is not reached.

"scanstart:xx;" (optional) - (history only) It allows to change the default direction of searching (where the search begins). It is defined in the form scanstart:from; or scanstart:to;.
If the time-range is not defined or if to is defined (can be set together with from or with timerange), then the default search direction is from newer to older items.
If only from is defined (can be set together with timerange), then the default search direction is from older to newer items.
Using the scanstart is handy particulary if the time-range is defined by from and to and if it is necessary to change the search direction from older to newer items (scanstart:start;).

"lang:xx;" (optional) - (only scripting methods) Specifies the language to be used for evaluated localized texts. Language is determined with a text identifier, e.g. "en", "de", "ru" etc. - see Fully supported languages in the PROMOTIC system. If not set, then the language currently used in the application will be used - therefore it is not necessary to define this option under normal circumstances. See the "Main language of runtime" configurator.

"headers:xx;" (optional) - (only scripting methods) Specifies whether the output list will contain (on first and/or second row) also the column names (localized texts) while being viewed.

title - The first/second row of the output list will contain the column names (localized texts) while being viewed.

id - The first/second row of the output list will contain the system column names (identifiers) while being viewed.

Return value:

2-dimensional array of values (PmArray object for JavaScript or Array data type for VBScript).

Note:

The implementation of event items filters tends to search and test all event available in history.
In order to prevent searching all items, it is necessary to reduce the query (filter criteria) to a smaller portion of events. The reduction can be based on a time span, causing the search focuses only on items belonging to the defined time span. Another reduction possibility is to define the total number of event items to be found and also the total searched event items count can be defined. For the reduced portion of events to be searched also a search direction (scanstart) can be specified, athough the search result are sorted the same way. Changing the search direction is relevant only if complemented with reduction of searched items count (scanrecords) or found (records) items count. In such case the search direction is relevant because it specifies the side of time span that can be omited based on the item limitation.

Example1:

Obtains the last (newest) 50 events records:50;scanrecords:500; (the values of desired columns), satisfying the filter condition (desc:Test2;).

JavaScriptVBScriptSelect and copy to clipboard



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

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

Example2:

Obtains all events (values of desired columns), meeting the filtering criteria (desc:Test2;) in last 8 hours (timerange:8h;) with respect to the defined time (to:time(2025.07.20-06:00:00.000);) and with count limitation of maximum searched and returned sentences records:50;scanrecords:500;. Get also the english column names in the first row.

JavaScriptVBScriptSelect and copy to clipboard



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

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