dpGetPeriodSplit()

Queries DP attributes over a certain period of time. Use the function when you query a large amount of data. The function reduces the system load and offers a considerable advantage when dealing with a large amount of data.

As of the first function call, the data is collected internally. This means that the archive manager sends all collected data to the DATA manager. The DATA manager sends the data further to the UI or the CTRL manager, which buffers the data. The UI or the CTRL manager buffers the data until the data is queried via the split functions (dpQuerySplit, dpGetPeriodSplit). Which manager buffers the data depends on the manager (UI or CTRL) that is used to query the data.

Depending on how fast the CTRL script queries the data blocks (depending on the amount of data and on the system load), less bigger or more smaller data blocks are returned.

Synopsis

int dpGetPeriodSplit ( int &reqId, int &progress, time t1, time t2, unsigned count, string dp1, <dyn_type1> &xa1, dyn_time &ta1 [, string dp2, <dyn_type2> &xa2, dyn_time &ta2);

Parameter

Parameter Description
reqId The request ID. The request ID must be set to 0 when calling the function for the first time. Thereafter the request ID is set by the function.
progress

The return parameter 'progress' shows how much of the function was executed. 100% means that the function was executed completely.

Note that for the split queries, you can use the debug flag "-dbg 10" for CTRL and UI managers in order to output the progress of a split query in the log viewer.
t1 Start time
t2 End time
count Number of the values before t1 (start time) and after t2 (end time) that are also queried.
dp1 Data point or the data point config (see example below).
xa1

Target variable for the queried values of the data point, for example, a dyn_float for ExampleDP_Arg*.

Note that the result variable is continuously filled. Therefore, the variable must be emptied or the new part used (see example further below).
ta1

Source times for the values ( xa1). This means the source times for the values that were queried.

Note that the result variable is continuously filled. Therefore, the variable must be emptied or the new part used (see example further below).

See chapter dpGetPeriod() for a detailed description of the function.

Note that if more values are returned for a dpGetPeriodSplit query than the limit specified via the config entry queryMaxValues in the [valarch] queryMaxValues as well as via the config entry "maxValueRequestCount" in the [data] maxValueRequestCount, an error message is shown. The error can be retrieved with a subsequent call of the function getLastError(). See also Error Handling.

dpQuerySplit and dpGetPeriodSplit return 1 after a redu switch! Furthermore, the parameter "progress" and the target variable as well as the source times are reset (meaning that the progress is set to 0 and the values of the target variable and the source times are deleted).

If the data point that is queried, is renamed simultaneously with a dpGetPeriodSplit query, the function dpGetPeriodSplit returns an error.

The message splitting reduces the system load in case of larger historical queries. The value archive splits the request message into several requests for each value archive file. To display the messages for a value archive, use the manager option for Value Archives "-snd 1" (debug output for outgoing messages).

Example

The example queries the archived values (_offline.._value) of the data point "ExampleDP_Arg1" between 28.07.15 and 29.07.15 and at least 1 value before and after this period.

main()
{
  dyn_float val; //Contains the individual values
  dyn_time t; //Contains the source times of the values
  int reqId = 0; //For the first call the Request ID must be set to 0.
  int progress = 0; //The return parameter progress shows how much of the function was executed.
  int err; //In case of errors the function returns -1.
  while ((progress < 100) && !err)
  {
    err = dpGetPeriodSplit(reqId, progress, makeTime(2015,7,28),
                                         makeTime(2015,7,29),1,"ExampleDP_Arg1.:_offline.._value", val, t);
    /* from 28.07.2015 to 29.07.2015, at least 1 value before 28.07.2015 and after 29.07.2015, data point element, results */
    if ((err != 0) ) /* In case of query errors */
    {
      DebugN("dpGetPeriodSplit caused an error");
    }
    else
    {
      int i; //loop variable
      DebugN("Request ID:", reqId, "Progress:", progress, "Result values:");
      for(i=1; i<=dynlen(val); i++)
        DebugN(val[i], t[i]);
      dynClear(val); //Empties the table
      dynClear(t); //Empties the table
    }
  }
}

Assignment

Data point function

Availability

CTRL, UI