The ReplaceValue method is used to replace a specific PIValue. In some cases there may be more than one event at a given time. The UpdateValue method compares only timestamps when determining which event to modify. If there are several events with the same timestamp, they are considered identical. With ReplaceValue the caller can select between events with the same timestamp but different values.
object.ReplaceValue NewValue, OldValue, [AsyncStatus]
The ReplaceValue method syntax has these parts:
|object||An object expression that evaluates to an IPIData2 interface, obtained from a PIData object.|
|NewValue||A PIValue containing the new value to substitute for the OldValue.|
|OldValue||An existing value with the same timestamp as NewValue.|
|AsyncStatus||Optional PIAsynchStatus object that may be used to monitor the progress and status of the method.|
The possible values in the variant for TimeStamp input to a PIValue are:
The supported PIValue variant types that can be placed in the NewValues PIValues collection are listed below:
Timestamps for both the NewValue and OldValue PIValue objects must match, otherwise the caller will receive an error. ReplaceValue is only supported on PI server version 3.4 and greater; calls to previous versions of the PI server will receive a pseSERVERNOTIMPL error.
The variant types supported by the individual PIValue objects that are added to the PIValues collection follow the rules set forth in the documentation under the PIValues Collection, Add method. Note, not all variant types are supported for implicit conversion by the PI SDK. The caller of the ReplaceValue is responsible for coercing an unsupported variant type into one that the PI SDK and PI server can use.
Annotated values can be handled by this call. However, if there are are multiple events at the same time with same value, but some values are annotated while the others are not, only the annotated events can be targeted for replacement. A specific unannotated event amongst several others with the same timestamp and value cannot be targeted for replacement - they are all equivalent and therefore cannot be distinguished.
This method is only works against PI3 servers of version 3.4 and greater. All other servers will return pseSERVERNOTIMPL.
In addition to generic errors (such as Out of Memory), the following errors may occur:
|pseWRITEERROR||Failed to write one or more values to the server. The server error is appended to the error object's Description property.|
|pseVARIANTTOPIEVENT||Unable to convert the passed VARIANT to a server PIvalue. Not all VARIANT types are supported. Some types may contain data larger than a DOUBLE or LONG can hold.|
|pseBADPIVALUE||Passed VARIANT contains an unsupported VARIANT type (e.g. VT_EMPTY). Not all VARIANT types are supported.|
|pseOBJECTNOTPITIME||A VARIANT passed for a time argument containing an object (IDispatch pointer) did not contain a PITime object or one of its derivatives.|
|pseVARIANTTYPEASTIME||A VARIANT passed for a time argument did not contain a variant type that is supported.|
|tseTIMEINVALID||Invalid time value.|
|pseVARIANTTIMETODOUBLE||A VARIANT passed for a timestamp could not be converted to a positive number of seconds since 1970.|
|pseDATETOTIMESTAMP||A DATE passed for a timestamp could not be converted to a PI timestamp.|