Send a single value (snapshot or archive) to the PI Server. If events with the same timestamp exist in the archive, this method replaces one of the existing events.
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.UpdateValue NewValue, TimeStamp, [MergeType], [AsyncStatus]
The UpdateValue method syntax has these parts:
|object||An object expression that evaluates to a PIData object.|
The variant may contain an actual value (real, int, string), an
object containing a PIValue, a DigitalState object or another object.
If another object is passed, the default value of the object
(DISPID_VALUE) is used.
This works in conjunction with the passed date. If a non zero date is passed it is always used. If a zero date is passed but the NewValue is not a PIValue object then the current date/time on the destination server is used.
A variant containing a timestamp. 0 means current date/time on the server unless NewValue is a PIValue object in which case a 0 TimeStamp argument means use the time in the PIValue object. In that case, if the PIValue object’s timestamp is 0, then the current date/time on the server will be used.
An optional flag used to indicate how to treat duplicate values in the archive. The default value is dmReplaceDuplicates. Valid values for the flag are contained in the DataMergeConstants enumeration
Not Implemented; if used, this parameter is ignored. Optional PIAsynchStatus object that may be used to monitor the progress and status of the method.
The possible values in the variant for TimeStamp are:
The possible values in the variant for NewValue are:
The settings for MergeType from the DataMergeConstants enumeration are:
|Setting||Action when no value exists with the same timestamp||Action when one or more values exist with the same timestamp|
|dmReplaceDuplicates||Add the value to the archive.||Overwrite one of the existing values and set its Substituted flag to True.|
|dmInsertDuplicates||Add the value to the archive.||Add a new value with the same timestamp. Existing values are not overwritten.|
|dmErrorDuplicates||Add the value to the archive.||Return an error to the client. When PI SDK buffering is enabled, error reporting for this mode is the same as for silent modes.|
|dmReplaceOnlyDuplicates||Return an error to the client.||Overwrite one of the existing values and set its Substituted flag to True. When PI SDK buffering is enabled, error reporting for this mode is the same as for silent modes.|
|dmErrorDuplicatesSilent||Add the value to the archive.||The archive subsystem writes an error message to the PI message log on the PI Server, or PI SDK returns an error to the client.|
|dmReplaceOnlyDuplicatesSilent||The archive subsystem writes an error message to the PI message log on the PI Server, or PI SDK returns an error to the client.||Overwrite one of the existing values and set its Substituted flag to True.|
For additional details regarding the use of this method with PI SDK buffering, see “Buffering and the Behavior of PI SDK Calls” in PI SDK Help.
In addition to sending a value to PI, this method can be used to set attributes related to the value. This is accomplished by supplying these attributes in a NamedValues collection set into a PIValue object's ValueAttributes property. For details about supported attributes see the PIValue.ValueAttributes page referenced under See Also. This is how annotations are placed on data values. This is demonstrated in the referenced example.
The dmReplaceOnlyDuplicates and dmErrorDuplicates modes require an additional call to the PI server to verify the presence or absence of events at the passed time. Therefore, use of these modes may return errors from either the retrieval or placement of the value. Also, the additional server call may affect the performance of the UpdateValue call relative to the use of UpdateValue with other MergeType modes. The DataMergeConstants dmErrorDuplicatesSilent and dmReplaceOnlyDuplicatesSilent are provided to obtain the same behavior when events are posted to the server without the added cost of prior retrievals needed to provide an error return. These new options should be used when an error report is not required by the calling application.
On PI2 servers, insertion of duplicate timestamp events for timestamps earlier than the snapshot are not allowed; however, multiple events with the timestamp of the snapshot are allowed. These PI2 server behaviors affect the implementation of UpdateValues, the user should be aware that the results of the dmInsertDuplicate mode may vary based on the timestamp of the incoming event. Also, the dmErrorDuplicates mode is not supported against PI2 servers, users should exercise a combination of calls to UpdateValues using different modes: dmReplaceDuplicates mode for events at the timestamp and the dmInsertDuplicates mode for insertion of events in the past (i.e. before the snapshot) that are not to be overwritten.
With the introduction of PI-SDK buffering in version 1.4, when buffering is active for the target server, this call is directed to the pibufss subsystem, not the server itself. As a result, the errors that are returned reflect interaction with that subsystem and may differ from the callers expectation. For example, calling UpdateValue(s) using DataMergeConstants that claim to return an error, (dmErrorDuplicates and dmReplaceOnlyDuplicates) when buffering is active will not return errors to the caller based on values on the server. The communication between the buffering subsystem and the server is intentionally separated from the application which allows the application to proceed sending data without a connection to the server.
When pseBUFSSWRITE or pseBUFSSFAIL errors occur, PI SDK attempts to write data directly to PI Server if appropriate. For details, see "Buffering and the Behavior of PI SDK Calls" in the PI SDK Buffering Limitations topic.
For a system that is correctly configured and operating normally, pseBUFSSWRITE errors may indicate a temporary condition that may resolve itself, so the application can continue attempting to write data. If a configuration error occurred prior to the pseBUFSSWRITE error, then data writes will be unsuccessful until the configuration is corrected. In this case, you may see the following error appended to the Description property: [-11417], "Buffer Subsystem is not performing buffering due to configuration".
In contrast, pseBUFSSFAIL errors will not be resolved without intervention, and once this type of error occurs, further UpdateValue calls should be avoided until the condition causing the error has been corrected.
In addition to generic errors (such as Out of Memory), the following errors may occur:
|pseWRITEERROR||Failed to write the value 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.|
|pseBUFSSWRITE||Event passed to PI Buffer Subsystem cannot be written, but this condition is usually temporary and may resolve itself. If appropriate, PI SDK attempts to write data directly to PI Server.|
|pseBUFSSFAIL||Event passed to PI Buffer Subsystem cannot be written, and further UpdateValue calls should be avoided until the condition causing the error is corrected. If appropriate, PI SDK attempts to write data directly to PI Server.|
|pseDUPVALUEEXISTS||Event passed in dmErrorDuplicates mode cannot be written due to an event already at that timestamp.|
|pseNOVALUETOREPLACE||Event passed in dmReplaceOnlyDuplicates mode cannot be written since no previous events exists at that timestamp.|
|pseEVENTSRETRIEVE||Check for events at passed timestamp failed with server error. The server error is appended to the error object's Description property.|