dpQuerySplit()

Retrieves attribute values with the help of SQL statements. 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 dpQuerySplit(int &reqId, int &progress, string query, dyn_dyn_anytype &tab);

Parameter


Parameter	Meaning
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 API_USR1" for CTRL and UI managers in order to output the progress of a split query in debug messages.
query	SQL statement. See the example at the end of this page as well as chapter Queries and SQL keywords.
tab	Two-dimensional results table. Note that the result table is continuously filled. Therefore, the table must be emptied or the new part used (see example below).

Description

For a detailed description of the function, see chapter dpQuery().

If using sorting in a query (e.g. SORT BY 1 ASC, SORT 1 BY DESC), the function dpQuerySplit() returns the result in one piece, not split.

Note that if more values are returned for a dpQuerySplit request than the limits specified via the config entries queryMaxValues in the [valarch] section and the config entry "maxValueRequestCount" in the "[data] section, 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 and the current query is discarded! The parameter "progress" and the results table are reset (meaning that the progress is set to 0 and the values of the results table are deleted). The query must be restarted on the active host and the data will be collected again.

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.

Example

The example returns the values of the data point(s) "ExampleDP_Arg* of type ExampleDP_Float.

main()
{
  int reqId = 0;
  int progress = 0;
  int err = 0;
  dyn_dyn_anytype tab;
  int count = 2;
  int startPos = 2; //Start position is 2 since the header is returned first and thereafter the values

  while ((progress < 100) && !err)
  {
    err = dpQuerySplit(reqId, progress, "SELECT '_offline.._value' FROM 'ExampleDP_Arg*' WHERE _DPT = \"ExampleDP_Float\"TIMERANGE(\"2023.08.01 14:16:00.000\", \"now\", 1, 1)", tab);
  //Queries the offline values of the data points ExampleDP_Arg*
  for(int i = startPos; i<= dynlen(tab); i++)
    dynlen(tab);
    DebugN(tab);
    dynClear(tab); //Empties the table
    startPos =1; //The start position is 1 since the header was already returned
  }
}

Assignment

Data point functions

Availability

CTRL, UI