Send one or more values (snapshot or archive) to the PI Server. The method returns a PIErrors collection containing any errors that occurred when writing values.
The UpdateValues 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.UpdateValues NewValues, [MergeType], [AsyncStatus]
The UpdateValues method syntax has these parts:
|object||An object expression that evaluates to a PIData object.|
A PIValues collection containing one or more values to add to the server for this PIData object.
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 supported PIValue variant types that can be placed in the NewValues PIValues collection are listed below:
The settings for MergeType from the DataMergeConstants enumeration are as shown in the table below.
Note: A single UpdateValues call may send some events for which one or more values exist with the same timestamp, and some events for which no values exist with the same timestamp. Therefore, depending on the events sent to the PI Server, the actions described in both of the columns below may apply for a single UpdateValues call, resulting in some successful updates, some client errors, and some PI message log errors.
|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 the 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 the 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.
Since COM does not allow the user to return a "warning" (return codes are either 0 and greater, a success, or less than 0, a failure, the user must check the PIErrors collection upon return of the UpdateValues function, even when a success code is returned. With multiple values involved, the PIErrors collection can contain more detailed information concerning the individual value returns than the single metric of the function return. S_OK may be returned by UpdateValues, even if one or more of the values involved in the call experiences an error condition.
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 UpdateValues is responsible for coercing an unsupported variant type into one that the PI SDK and PI server can use.
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 UpdateValues call relative to the use of UpdateValues 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 UpdateValues 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 be returned by either the function or in the PIErrors collection:
|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.|
|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 UpdateValues 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.|