RefreshData

Description:	Used in combination with a VTSRead module to delivering data read from the I/O device
Returns:	Nothing
Usage:	Script Only.
Function Groups:
Related to:	NoData | AddRead | DelRead
Format:	CallBackObj\RefreshData(TimeStamp, NewData, Attribute, QueueObj, PropagateOnlyOnDataChange)
Parameters:

TimeStamp

Optional. If invalid, the system uses current time in UTC to timestamp the data. Otherwise, may be either of the following: A single timestamp value, expressed in number of seconds since January 1st 1970 UTC. This value will be applied to each element of NewDta. An array, having the same structure as NewData. Each data point will be assigned its corresponding timestamp from the timestamp array. For event driven reads, you may wish to process only the data from a single address, rather than from a full read block. You can achieve this by setting all the TimeStamp array elements to invalid except for the one matching the element of NewData which you want to process. Note that invalid timestamps in a timestamp array have special meaning. An invalid timestamp element indicates that the corresponding data has not changed. This enables drivers to pass back partial updates. This feature is independent of the PropagateOnlyOnDataChange option.

NewData

This is the value read from the I/O device. It may be either a simple array, or an array of arrays having the same size as the MemAddress array used in the VTSRead function. If a simple array, there will be one element for each address. The array of arrays option is generally used for returning historical data for a given address. Calling Refresh data with the NewData parameter specified as an array of arrays will work only with Analog Status, Digital Status and Pump Status. It will not work with Analog Input, Digital Input, and any tag not specifically coded to handle an array of results being passed into newData().

Attribute

Optional. No default. May be a single value, which will be applied to all elements of NewData if that is an array, or may be an array of attributes that gets assigned to the corresponding array of data. If an array, the size and arrangement of the array must be the same as NewData.

QueueObj

Obsolete. Should be set to Invalid.

PropagateOnlyOnDataChange

Flag that when set true, will prevent data from being propagated through RPC or to tag\NewData() unless the value of NewData or Attributes has changed since the last time RefreshData was called. Defaults to TRUE. Historical reads, whether by array or array-of-array, are expected to set PropagateOnlyOnDataChange to FALSE to disable the automatic filtering. One can interpret this option as 'automatically detect and ignore data which has not changed'.

Comments

The data type and structure can vary for the three parameters, NewData, TimeStamp and Attribute. If the driver will read blocks of history data, you will need to take additional steps.

Invalid data is accompanied by a valid timestamp:

TimeStamp[i] = Some Valid Time;
Data[i]             = Invalid;

Missing Data is indicated by an invalid timestamp:

TimeStamp[i]  =  Invalid;

Currently, for the entire array of data to be written to the Historian the History address must be used in the I/O tag.

Block history

When reading historical data, an array of arrays may optionally be used, where each element of the NewData array will contain another array which must be sized for the number of data points that are being returned for the matching MemAddress. This holds true even if there is only one value to return for each I/O address.

Note: the IO tag supports accepting arrays.

This a special mode used only for input tags that can support the different read result. These are, the I/O, AnalogStatus, DigitalStatus and the PumpStatus, all of which have a 'History Address' parameter. The reading of block history has little to do with VTSDriver itself since VTSDriver simply passes through whatever the driver provides. The contract that standard status tags expect is that a block of history will be passed to NewData() as an array, and that the Timestamp parameter will be a matching array with corresponding timestamps. If Attributes are present, then attributes for block history should be in an array corresponding to the Data/Timestamp arrays. It is important that drivers pass block history data in the form that VTScada status tags support.

If the block of history records is being passed in an array, then the oldest timestamp must be at index 0. The restriction that the block history be in a certain order is due to the Historian, which logs exactly what it is given without modification (by design). Having timestamps reversed means that out-of-order history is written, which will slow performance. If the driver’s protocol requires block history with the newest item first, then that driver should swap the order before passing it along.

Example 1:

Given MemAddress with two addresses, "Addr1" and "Addr2" and data for Addr1 = 1.23 and data for Addr2 = 2.34, you might do something like:

 { Make a data array }
Data = New(2);
 { Add first element }
Data[0] = New(1);
Data[0][0] = 1.23;
 { Add second element }
Data[1] = New(1);
Data[1][0] = 2.234;
 
{ Make it So }
CallBackObj\RefreshData( Invalid, Data, Invalid );

Example 2:

Multiple Data/Timestamp Value Pairs for each item in MemAddress, no Attributes

Given MemAddress with two addresses, "Addr1" and "Addr2" and data/timestamps for
Addr1 = 1.23/2009-08-01 11:23, 1.24/2009-08-01 11:24 and data for Addr2 = 2.34/2009-08-01 11:21, 2.35/2009-08-01 11:22
you might do something like:

{ Make a data array }
Data      = New(2);
TimeStamp = New(2);

{ Add first element}
TimeStamp[0]    = New(2);
Data[0]         = New(2);
Data[0][0]      = 1.23;
TimeStamp[0][0] = ConvertTimestamp(  
                    \ODBCManager\ConvertToVTSTimeStamp(
                       "2009-08-01 11:23"), 
                       "US Eastern Standard Time", 0, 
                       "GMT Standard Time" );
Data[0][1]      = 1.24;
TimeStamp[0][1] = ConvertTimestamp( 
                    \ODBCManager\ConvertToVTSTimeStamp( 
                       "2009-08-01 11:24"), 
                       "US Eastern Standard Time", 0, 
                       "GMT Standard Time" );

{ Add second element}
Data[1]      = New(2);
TimeStamp[1] = New(2);

Data[1][0]      = 2.34;
TimeStamp[1][0] = ConvertTimestamp( 
                    \ODBCManager\ConvertToVTSTimeStamp( 
                       "2009-08-01 11:21"), 
                       "US Eastern Standard Time", 0, 
                       "GMT Standard Time" );
Data[1][1]      = 2.35;
TimeStamp[1][1] = ConvertTimestamp( 
                    \ODBCManager\ConvertToVTSTimeStamp( 
                       "2009-08-01 11:22"), 
                       "US Eastern Standard Time", 0, 
                       "GMT Standard Time" );

{ Make it So }
CallBackObj\RefreshData( TimeStamp, Data, Invalid );