The function queries DP attributes over a specified period of time.


dpGetPeriod(time t1, time t2, int count, stringdp1, <dyn_type1> &xa1, dyn_time &ta1 [,string dp2, <dyn_type2> &xa2, dyn_time &ta2);


Parameter Description
t1 start time
t2 end time
count number of the values before t1 and after t2 that also have to be read out.

data point attribute identifier


Do not use data points of different systems! The function dpGet only works for one system. If the dpGet is used for at least two systems, it does not work and the following error message is shown:

WCCOAui (1), 2006.09.26 14:11:19.266, PARAM,SEVERE, 175, this request cannot address more than one system, DP: dist_789:ExampleDP_Arg1.:_original.._value WCCOAui (1), 2006.09.26 14:11:19.266, CTRL, WARNING, 76, Invalid argument in function,
xa1 target variable
ta1 source times belonging to xa1

Return Value

The function dpGetPeriod() returns 0 and if it is unsuccessful, it returns -1.


The errors can be retrieved with getLastError(). This includes missing arguments or if the data point does not exist.

If a dpGetPeriod query returns more values than specified with [valarch] queryMaxValues, an error message is shown. The error can be retrieved with a subsequent call of the function getLastError(). See also Error Handling.


The function dpGetPeriod() reads the values of the data point attributes dp1, dp2, ... with source times in the interval of t1 and t2, and the count values before t1 and after t2 from the database and writes them in the field variables xa1, xa2, ... . The associated source times are stored in the fields ta1, ta2, ... .Values returned by dpGetPeriod() are always ordered according to the source time. Within the value archives the values with ident source times (also ident milliseconds) are ordered according to the arrival.

If an alias is used for query, this is passed as parameter to the external query function; Meaning function calls for dpQuery() and alertGetPeriod(). When querying historical values from a value archive (HDB), consider the notes in the chapter Swap out/backup archives.

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

  • With the help of dpGetPeriod() only attributes of the config "_original", "_online", "_offline" and "_corr" can be retrieved! t1 may not predate 1.1.1970 0:0 (UTC).
  • When using dyn_* variables the correct variable type must be used. dyn_anytype cannot be used.

If a definition for a config or attribute does not exist, the following defaults are used:

Function Default
dpSet*() _original.._value
dpGet() _online.._value
dpGetAsynch() _offline.._value
dpGetPeriod() _offline.._value
dpConnect() _online.._value
dpDisconnect() _online.._value

The configs "_original", "_online" and "_offline" have the same attributes. For the configs "_original" and "_online" only the values of the attributes "_value" and "_stime" may be different from one another. In exceptional cases the config "_online" adopts the configured correction value (attribute "_default.._value") of a data point element, whereas under normal circumstances the original value is also the online value. Correction values may be set by the user and if they have the same source time, replace the appropriate original (or correction values) as offline values. Otherwise, the config "_offline" adopts the attribute values of the config "_online".

The fields xa1, xa2, ..., ta1, ta2 are reinitialized on every call, i.e. they have the same length.

In the case of dpGetPeriod queries to the ValueArchive of the History DB with the parameter "count" > 0, the value entries generated by the archive itself (for example, on start of archival and change of archive) are also included. These values can be recognized by the set TIMEINVALID bit.
Anmerkung: With NGA, all values are archived with the time of the change of the value and not with the time of the activation or deactivation of the archive. Therefore, the TIMEINVALID bit is not set. The COUNT takes into account all archived values.

Query for saving

The time of the earliest database entry of an original, online or offline value of a data point element can be determined using the attributes of config start. The values of "<dpvariable>:_start.._original", "<dpvariable>:_start.._online" and "<dpvariable>:_start.._offline" are the times of the first occurrence of original, online and offline values of the data point element <dpvariable> in the database.

By setting correction values, offline values of a data point element can exist for a longer period of time than original and online values. If there are no values of the queried data point attribute in the database, the arrays (value and time) remain empty.

The config "_archive" must be added to a data point element!


The example returns the archived values of the data point "Reservoir_1_level.C1.AVG_WT0" between 08.09.03 and 09.09.03 and at least 1 value before and after this period. Note that you have to add an _archive config to the data point to archive values. See chapter Data point configs, basics

  dyn_float val;
  //Contains the values
  dyn_time t;
  //Contains the source times of the values
  int ant;
  //The function returns -1 in case of errors
  //from 08.09.2003 to 09.09.2003, at least 1 value before 08.09.03 and after 09.09.03
  ant = dpGetPeriod(makeTime(2003,9,8),makeTime(2003,9,9), 1,"Reservoir_1_level.C1.AVG_WT0:_offline.._value", val, t);
  if ((ant== -1) || (dynlen(val) == 0))
  // Is executed if a query error occurs or no values exist
    DebugN("dpGetPeriod caused an error or no values exist");
    int i;
  //loop variable
    DebugN("Result values:");


Data point function, waiting Control function