Click or drag to resize
OSIsoft, LLC

AFDataUpdateValues Method (AFValues, AFUpdateOption, AFBufferOption)

This method writes or replaces one or more values on the target system using the configured data reference.

Namespace:  OSIsoft.AF.Data
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.6.195
Syntax
public AFErrors<AFValue> UpdateValues(
	AFValues values,
	AFUpdateOption option,
	AFBufferOption bufferOption
)

Parameters

values
Type: OSIsoft.AF.AssetAFValues
The values to be written or replaced on the target system.
option
Type: OSIsoft.AF.DataAFUpdateOption
An enumeration value that specifies how to treat duplicate values. It can also be used to specify that an existing value should be removed.
bufferOption
Type: OSIsoft.AF.DataAFBufferOption
An enumeration value that specifies buffering option.

Return Value

Type: AFErrorsAFValue
If there are no errors, then is returned. Otherwise an AFErrorsTKey instance containing error information is returned.
Exceptions
ExceptionCondition
ArgumentNullException The values is .
ArgumentException The values must contain at least one AFValue.
InvalidOperationException The Attribute does not have a data reference configured.
NotSupportedException The data reference does not support this method.
Remarks

This method requires that the attributes being written, if configured with a data reference, must support the UpdateValues method. This is indicated by having the UpdateValues flag set in the SupportedDataMethods property. The PI Point Data Reference supports UpdateValues for simply configured PI Points.

For the case of attributes which are configuration items, this method (unlike AFAttribute.SetValue) does not require the corresponding AFElement to be checked out or checked in.

If AFBufferOption is set to Buffer, this method requires that the attribute has a configured data reference which supports buffering. This is indicated by having the Buffering flag set in the SupportedDataMethods property. The PI Point Data Reference supports buffering.

Note Notes to Callers
This method, property, or class is only available in the .NET 4 version of the SDK.

Security note Security Note
You must have WriteData security rights to write a data value.

Important note Important
This method is not supported for attributes that do not have a data reference. Consider using AFListData.UpdateValues.

Examples
// This example demonstrates how to update values to an attribute with PIPoint data reference.
// Note: For successful write through Buffer, PI Buffer Subsystem needs to be correctly pre-configured with PI Buffer Manager. 

// Get the Database and UOMs
PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems.DefaultPISystem;
AFDatabase myDB = myPISystem.Databases.DefaultDatabase;
UOM uomFoot = myPISystem.UOMDatabase.UOMs["foot"];
UOM uomYard = myPISystem.UOMDatabase.UOMs["yard"];

// Create an Attribute and its new values
AFAttribute myAttribute = null;
AFTime newStartTime = new AFTime("T-1d", CultureInfo.CurrentCulture);
AFValues newValues = new AFValues();
Random randomValues = new Random();

// Create Dynamic Attribute to a PIPoint to Update
PIServer piServer = PIServers.GetPIServers().DefaultPIServer;
int dataCount = 5; //Create 5 new values to update
AFTime newTime = newStartTime;
PIPoint point;
if (!PIPoint.TryFindPIPoint(piServer, "MyTestPoint#1", out point))
{
    point = piServer.CreatePIPoint("MyTestPoint#1");
}
myAttribute = new AFAttribute(String.Format(CultureInfo.InvariantCulture, @"\\{0}\{1}", piServer.Name, point.Name));
myAttribute.DefaultUOM = uomFoot;
myAttribute.ConfigString += ";ReadOnly=False";
for (int i = 0; i < dataCount; i++)
{
    AFValue newValue = new AFValue(myAttribute, randomValues.NextDouble(), newTime, uomYard);
    newValues.Add(newValue);
    newTime = newTime.LocalTime.AddMinutes(10);
}
AFTime newEndTime = newTime;

// Get the Recorded Values for the Attribute
AFValues recordedValues = myAttribute.Data.RecordedValues(new AFTimeRange(newStartTime, newEndTime), AFBoundaryType.Inside,
    myAttribute.DefaultUOM, null, false);
Console.WriteLine("Recorded Values:");
foreach (AFValue value in recordedValues)
{
    Console.WriteLine("  {0}: '{1} {2}' at '{3}'",
        value.Attribute, value.Value, value.UOM, value.Timestamp);
}

// Get the Buffer Option
// Note: If not specified in AFSDK.config, the buffer option is defaulted to "BufferIfPossible". 
Console.WriteLine("Current Buffer Option: {0}", AFData.BufferOption);

// Set the Buffer Option to "Buffer" if it is not already, which will be valid throughout this client instance.
if (AFData.BufferOption != AFBufferOption.Buffer)
{
    AFData.BufferOption = AFBufferOption.Buffer;
    Console.WriteLine("Current Buffer Option for this instance has been changed to: {0}", AFData.BufferOption);
}

//1. Update the Attribute Values and Display any Errors
AFErrors<AFValue> errorsWithBuffer =
    myAttribute.Data.UpdateValues(newValues, AFUpdateOption.InsertNoCompression); //Insert or InsertNoCompression
Thread.Sleep(1000);

if (errorsWithBuffer != null && errorsWithBuffer.HasErrors)
{
    Console.WriteLine("\nErrors returned from AFAttribute.Data.UpdateValues:");

    // Display Value errors
    if (errorsWithBuffer.Errors != null && errorsWithBuffer.Errors.Count > 0)
    {
        foreach (var item in errorsWithBuffer.Errors)
        {
            Console.WriteLine("  AFValue '{0}': {1}", item.Key, item.Value);
        }
    }

    // Display error from the PI Data Archive
    if (errorsWithBuffer.PIServerErrors != null && errorsWithBuffer.PIServerErrors.Count > 0)
    {
        foreach (var item in errorsWithBuffer.PIServerErrors)
        {
            Console.WriteLine("  AFValue '{0}': {1}", item.Key, item.Value);
        }
    }

    // Display PI System errors
    if (errorsWithBuffer.PISystemErrors != null && errorsWithBuffer.PISystemErrors.Count > 0)
    {
        foreach (var item in errorsWithBuffer.PISystemErrors)
        {
            Console.WriteLine("  AFValue '{0}': {1}", item.Key, item.Value);
        }
    }
}


//2. Alternatively, one can specify buffer option in the UpdateValues method
AFErrors<AFValue> errorsWithBufferIfPossible =
    myAttribute.Data.UpdateValues(newValues, AFUpdateOption.InsertNoCompression, AFBufferOption.BufferIfPossible);
Thread.Sleep(1000);

// Get the Updated Recorded Values for the Attributes
AFValues recordedValuesUpdated = myAttribute.Data.RecordedValues(new AFTimeRange(newStartTime, newEndTime), AFBoundaryType.Inside,
    myAttribute.DefaultUOM, null, false);
Console.WriteLine("\nUpdated Recorded Values:");
foreach (AFValue value in recordedValuesUpdated)
{
    Console.WriteLine("  {0}: '{1} {2}' at '{3}'",
        value.Attribute, value.Value, value.UOM, value.Timestamp);
}
Version Information

AFSDK

Supported in: 2.10.5, 2.10, 2.9.5, 2.9, 2.8.5, 2.8, 2.7.5, 2.7, 2.6
See Also
Enabling Operational Intelligence