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 or toTime 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 given objectReference.

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