RemoveSpecifiedValues Method (IPIData2 interface)

                    

 

The RemoveSpecifiedValues method deletes a list of values. The values may uniquely indicate one of several values with the same timestamp. This unique selection of values is needed to supplement cases that the RemoveValues method cannot handle. A PIErrors collection containing any errors that occurred in removing values is returned by this method.

Syntax

object.RemoveSpecifiedValues ValueList, [AsyncStatus]

 

The RemoveSpecifiedValues method syntax has these parts:

Part Description
object An object expression that evaluates to an IPIData2 interface, obtained from a PIData object.
ValueList A PIValues collection containing the values remove.
AsyncStatus 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 supported PIValue variant types that can be placed in the NewValues PIValues collection are listed below:

Remarks

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 RemoveSpecifiedValues 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 RemoveSpecifiedValues, 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 RemoveSpecifiedValues 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 removal.  A specific unannotated event amongst several others with the same timestamp and value cannot be targeted for removal.

This method is only available against PI3 servers.  PI2 servers will return pseSERVERNOTIMPL.

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur: 

Error Description
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.
Enabling Operational Intelligence