alertGetPeriod()

Reads the values of the specified alert attributes of the data point elements for which alerts were triggered.

Synopsis

int alertGetPeriod (time t1, time t2, dyn_time &times, dyn_int &counts, string alert1, dyn_string &dpa1, < dyn_type1 > &val1 [, string alert2, dyn_string &dpa2, < dyn_type2 > &val2 ...]);

Parameters

Parameter Meaning
t1, t2 Start and end time for reading alerts.
times Times of the alerts.
counts Counter for alerts of a specified alert attribute.
alert1, alert2, ... Alert handlig attributes such as _alert_hdl.._prior
dpa1, dpa2, ... A return value array containing the data points, including alert attributes for which alerts were returned.
val1, val2, ... Alert attribute values for the data points that triggered the alerts.

Return Value

Returns 0 and in case of an error -1.

Errors

Errors can be retrieved with getLastError(). The return value of getLastError() is the error code.

Description

The function reads values (val1, val2, ...) from alert attributes (alert1, alert2, ...) of the data point elements for which alerts were issued between times t1 and t2.

The names of the datapoint elements are written to the arrays dpa1, dpa2 etc. together with the alert handling attributes in the form:

"dpName.dpElem.[dpElem, ... ]:dpConfig.[dpDetail].dpAttr".

The corresponding alert times are written to the array times and the data point values to the arrays val1, val2.. Counters for alerts of the same data point attribute with the alert time are stored in the array counts.

The arrays times, counts, dpa1, val1 etc. have the same length. Elements with the same index belong to the same alert. The arrays are reinitialized at each call, that is, they always have the current length.

Use the alert handling attributes such as _alert_hdl.._prior (priority of an alert) or alert_hdl.._text (text of the alert state) for the parameters (alert1, alert2).

Note: Note that only alert handling attributes that can be used for an alertConnect can be used for alert1 and alert2 of an alertGetPeriod query. For the alert connect attributes, see the chapter alert_hdl().

Within a dpGetPeriod() call, either different alert handling attributes of multiple data points or different alert handling attributes of one data point can be queried.

  • Historical query of attributes of all data point elements of a data point is not supported.
  • When using alertGetPeriod() for RDB, DP names must be used, otherwise an error occurs.
  • When using dyn_* variables, the correct variable type must be used. A dyn_anytype cannot be used.

Example

In this example the alert priorities of all alerts for data points between January 18th, 2023 at 6 pm and January 19th, 2023 at 7 pm are assigned the array value_dp_prio and the alert texts into the array value_dp_text. The datapoints and the alert handling attributes of the datapoints will be saved in the arrays dp_prio and dp_text and the alert times in the array times.

main()
{
  time alertTime1, alertTime2;
  dyn_int count1, value_dp_prio;
  dyn_time times;
  dyn_string dp_prio, dp_text;
  dyn_string value_dp_text;
  int i;

  i = alertGetPeriod(setTime(alertTime1,2023,1,18, 12,00),setTime(alertTime2,2023,1,19, 18,00),times, count1,":_alert_hdl.._prior", dp_prio, value_dp_prio,":_alert_hdl.._text", dp_text, value_dp_text);
  DebugN(i," ", times," ", count1, " ", dp_prio," ", value_dp_prio, dp_text," ", value_dp_text);
  }

Assignment

Alert handling, waiting Control function

Availability

CTRL