Storing Original Streamed Data

After you receive the tag key from the HistorianAccess.AddTag() call, you can start sending original streamed data to the historian using the HistorianAccess.AddStreamedValue() method.

This method adds a new VTQ (value, time, quality) triplet into the time-ordered original data stream for delivery to the historian server. If the caller violates the time order of the VTQs being added, the underlying infrastructure corrects the timestamps and indicates that the time correction was performed by setting a special QualityDetail value.

If the historian connection was created with the store-and-forward mode support, the caller of this method should not be concerned about whether a live physical connection to the historian is present. The underlying HCAL infrastructure transparently redirects the data flow either to the historian server or to the store-and-forward engine.

The following code snippet illustrates sending for storage 1,000,000 time-ordered VTQs for a 32-bit integer tag.

Example

HistorianAccessError error;
HistorianDataValue myVTQ = new HistorianDataValue();
myVTQ.TagKey        = tagKey;
myVTQ.DataValueType = myTag.TagDataType;
myVTQ.OpcQuality    = 192;


for (int i = 0; i < 1000000; i++)
{
    myVTQ.Value         = i;
    myVTQ.StartDateTime = DateTime.Now;
    if (!historian.AddStreamedValue(myVTQ, out error))
        Console.WriteLine("Failed to enqueue VTQ: {0}", error.ErrorDescription); 
}

The AddStreamedValue() method is asynchronous and it returns true if the VTQ was successfully queued for storage, or false if the queuing operation failed. When those values will reach the historian server and be physically stored depends on factors such as server availability and network bandwidth. Usually this latency does not exceed a couple of seconds in a local network and gets down to a fraction of a second for higher data rates, because the data packets get filled faster and sent more often.

The DataValueType property of the HistorianDataValue class allows you to specify the value type of that particular VTQ. If the value type does not match the tag type, the managed HCAL tries to make a proper conversion. The OpcQuality property should reflect the original quality of the VTQ and is set to 192 by default, which corresponds to good quality.

When the original streamed data is sent by the AddStreamedValue() method, the HCAL infrastructure internally applies the storage rules if any are specified in the tag properties. Storage rules in include delta, cyclic, time deadband, value deadband, rate deadband (swinging door), and so on. If configured properly, such storage rules could significantly reduce the needed storage space on the historian server and the consumed network bandwidth. It is recommended to know the historization requirements for your data and configure tag storage rules so the insignificant noise gets cut off by such storage rules.