dpGetPeriod()
The function queries DP attributes over a specified period of time.
Synopsis
dpGetPeriod(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 |
|---|---|
| t1 | start time in local time |
| t2 | end time in local time |
| count | number of the values before t1 and after t2 that also have to be read out. |
| dp1 |
data point attribute identifier Note:
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.
Errors
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.
Description
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 00:00:00 or "00:00:00 UTC on 1 January 1970" (UTC).
- When using dyn_* variables the correct variable type must be used. dyn_anytype cannot be used.
time parameters the local time must be used instead of UTC.
The necessary conversion is performed internally.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.
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!
Example
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
main()
{
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");
}
else
{
int i;
//loop variable
DebugN("Result values:");
for(i=1;i<=dynlen(val);i++)
DebugN(val[i],t[i]);
}
}Assignment
Data point function, waiting Control function
Availability
UI, CTRL
