UpdateValue Method (PIData object)

                    

 

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.

Syntax

object.UpdateValue NewValue, TimeStamp, [MergeType], [AsyncStatus]

The UpdateValue method syntax has these parts:

Part Description
object An object expression that evaluates to a PIData object.
NewValue 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.

TimeStamp

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.

MergeType

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

AsyncStatus

Not Implemented; if used, this parameter is ignored. Optional PIAsynchStatus object that may be used to monitor the progress and status of the method.

Settings

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.

Remarks

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. 

Trappable Errors

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:

Error Description
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.

Enabling Operational Intelligence