trendDataReadSync and trendDataRead Functions
The following methods allow reading historical (trended) data of a specific system object in a given time frame.
Such functions can be run synchronously or asynchronously, and in the last case, it is necessary to provide a callback method that will be executed when the operation is completed.
In order to keep historical data, it is necessary to set the value log flag in the Object Configurator application for the property concerned.
Alternatively, it is possible to get historical data of Trend Log objects without having set the value flag log.
trendDataReadSync
The trendDataReadSync
function allows retrieving the historical values of a given object in a specific time frame.
trendDataRead
The trendDataRead
function allows retrieving asynchronously the historical values of a given object in a specific time frame. Then it calls the <callback>
with the operation result.
Syntax
(Synchronous read)
var result = trendDataReadSync(<objectReference>, <fromTime>, <toTime>)>, <propertyName>);
(Asynchronous read. The result is provided in the callback method.)
trendDataRead(<callback>, <objectReference>, <fromTime>, <toTime>), <propertyName>);
Parameters Usage
Parameter | Type | Default | Use | Annotation |
callback | Function | - | Mandatory for asynchronous calls | Object that identifies the callback function invoked to provide the historical values of a property. |
objectReference | String BrowserObject | - | Mandatory | CNS full path (reference to the system object location). |
fromTime | DateTime | - | Mandatory | Start date and time for the time frame concerned. |
toTime | DateTime | - | Mandatory | End date and time for the time frame concerned. |
propertyName | String | null | Optional | Name of the property from which to read historical values. If not provided, the trends of all the properties with historical values are retrieved. |
The callback is a function declared as follows:
function trendDataReadCallback(<trendDataReadResult>)
{
//... Do callback stuff here ...
}
Where <trendDataReadResult>
is a TrendDataReadResult
object.
Result
The trendDataReadSync
function returns a TrendDataReadResult
object.
Error Handling
Errors can occur in case:
- The callback is missing, invalid, null, or empty (for the asynchronous function only).
- The provided
objectReference
is null, empty, of invalid type, or non-existing. - The provided
fromTime
ortoTime
are null, empty, of invalid type, or represent an invalid time frame (fromTime greater or equal to toTime). - The provided
propertyName
is of invalid type or non-existing for the givenobjectReference
.
Examples of Use
How to get synchronously the historical values of the Operational Status of a macro in the last day
var yesterday = new Date((new Date()).valueOf() - 1000*60*60*24);
var now = new Date();
var result = trendDataReadSync("System1.ApplicationView:ApplicationView.Logics.MacroRoot.Macro1, yesterday, now, "OperationalStatus");
console(result);
How to get asynchronously the historical values of the Value property of the Analog1 Virtual Object in the last month, print them with time stamp, then calculate the average
var from = new Date();
from.setMonth(from.getMonth() - 1);
var to = new Date();
var designation = "System1.ApplicationView:ApplicationView.Logics.VirtualObjects.Analog1";
var property = "Value"
trendDataRead(callback, designation, from, to, property);
function callback(trendDataReadResult)
{
if (trendDataReadResult.error != null)
{
console(trendDataReadResult);
return;
}
var trends = trendDataReadResult.trends;
if (trends.length == 0)
{
console("No trended properties.");
return;
}
var values = trends[0].values;
if (values.length == 0)
{
console("No trended values.");
return;
}
var sum = 0;
for(var i = 0; i < values.length; i++)
{
sum += parseFloat(values[i].value);
console("{0} - {1}", values[i].timestamp, values[i].value)
}
console("Average = {0}", sum/values.length)
}
How to get the historical values of all the trended properties of the Combination1 Virtual Object in the last month
var from = new Date();
from.setFullYear(from.getFullYear() - 1);
var to = new Date();
var trendDataReadResult = trendDataReadSync("System1.ApplicationView:ApplicationView.Logics.VirtualObjects.Combination1", from, to);
var trends = trendDataReadResult.trends;
if (trends == null)
{
console(trendDataReadResult.error);
terminate();
}
for (var t = 0; t < trends.length; t++)
{
var valuesCount = trends[t].values.length;
var trendedProperty = trends[t].propertyName;
console("{0} historical values found for property {1}", valuesCount, trendedProperty);
}
If the specified object has more than one property with the value log flag set, the output looks like this:
15 historical values found for property BooleanValue
18 historical values found for property FloatValue
20 historical values found for property IntegerValue