Latest Insert

In the following example, there is an analog tag with original data values A, B, and C, stored with timestamps t_A, t_B, and t_C accordingly:

The latest insert allows users to add a VTQ, which will be visible until the next VTQ, if the data gets retrieved with wwVersion = 'LATEST'. The latest insert will mask previously stored VTQs of the same timestamp. For example, if we perform a latest insert operation with a VTQ of value G with timestamp t_B on data presented in the following diagram, we will see the following retrieval result if we retrieve with wwVersion = 'LATEST': {A at t_A, G at t_B, C at t_C}. If we retrieve with wwVersion = 'ORIGINAL', we will still see the original data in its intact form: {A at t_A, B at t_B, C at t_C}.

If we perform another latest insert, the latest data stream will be merged during that operation and the final result will be retrieved with wwVersion = 'LATEST'. For example, if we now perform a latest insert with VTQ of value F and timestamp t_B, the retrieval operation of wwVersion = 'LATEST' will produce {A at  t_A, F at t_B, C at t_C}, while retrieval of wwVersion = 'ORIGINAL' will produce the same result as before.

Example

HistorianDataValueList myVTQs =
    historian.CreateHistorianDataValueList(HistorianDataCategory.RevisionInsertLatest);

HistorianDataValue myVTQ = new HistorianDataValue(tagKey, HistorianDataType.DoubleByteString);
myVTQ.StringValue   = "G";
myVTQ.StartDateTime = new DateTime(2012, 9, 1, 11, 00, 00);

if (!myVTQs.Add(myVTQ, out error));
    Console.WriteLine("Failed to add revision VTQs: {0}", error.ErrorDescription);            

while (!historian.SendValues(myVTQs, out error))
{
    if (error.ErrorType != HistorianAccessError.ErrorTypeValue.CustomError)
    {
        Console.WriteLine("Failed to store revision VTQs: {0}", error.ErrorDescription);           
        break;
    }    
    if (error.ErrorCode != HistorianAccessError.ErrorValue.PreemptedTransaction &&
        error.ErrorCode != HistorianAccessError.ErrorValue.ValidationFailed)
    {
        Console.WriteLine("Failed to store revision VTQs: {0}", error.ErrorDescription);            
        break;
    }
    Console.WriteLine("Retrying revision transaction...");
}

Sending revision data happens in several steps:

1. An empty revision VTQ collection of class HistorianDataValueList must be constructed with specified historian data category.

2. New VTQs should be added one by one to that collection by calling the Add() method of the HistorianDataValueList class.

3. The accumulated values must be sent to the historian server by calling the SendValues() method of the HistorianAccess class. The list is automatically cleared if the data is stored successfully.

4. Repeat step 3 until the revision data operation transaction succeeds.

The HistorianAccess.SendValues() is executed as a single transaction. It might happen that there are multiple clients on the server, all executing revision data operations, trying to modify the same sections of a data file on the server. The AVEVA Historian Revision Data Subsystem is based on the optimistic concurrency control scheme, which requires unsuccessful transactions to try again if the resources are unavailable.

The custom error codes HistorianAccessError.ErrorValue.PreemptedTransaction and HistorianAccessError.ErrorValue.ValidationFailed indicate such an error condition. In this case, the caller must try to execute the same transaction again by calling HistorianAccess.AddRevisionValues() for the same collection.

There is no hardcoded limit on the number of VTQs that can be sent within a single transaction. However, it is recommended to send no more than 2,000 VTQs per single revision transaction. If you have VTQs for multiple tags, per transaction, it is recommended to limit the number of different tags participating in the same transaction by 100. Not following this recommendation will increase the time needed to complete the SendValues() call. If you notice that the SendValues() call takes more than 10 seconds (which may depend from the load on the server and its hardware performance characteristics) you should consider reducing the size of a single transaction.