Add Method (PIValues collection)



Given a timestamp, and a value as Variants, and a NamedValues or MTNVS collection of ValueAttributes, this method adds the data to the  PIValues collection and returns a reference to the added PIValue.


MTNVS is a thread-safe version of NamedValues. It implements all the NamedValues and INamedValues2 methods and properties as well as native versions (prefaced by "MT") of the same.


object .Add TimeStamp, Value, nvAttrs

The Add method syntax has these parts:

Part Description
object An object expression that evaluates to a PIValues collection.
TimeStamp A VARIANT containing the time at which the associated value occurred.  See settings below.
Value A VARIANT containing the value to be added to the PIValues collection.  See settings below.
nvAttrs A NamedValues or MTNVS collection containing one or more ValueAttributes describing the data value being added.  See settings below.


The possible values in the variant for TimeStamp are:


The possible values in the variant for NewValue are:


The possible NamedValue objects in the ValueAttributes NamedValues collection are either booleans or variants.  The recognized names are:
Setting Description
Annotations (VARIANT) The annotations that are associated with this value.
Questionable (BOOLEAN) There is some question as to the validity of the value.



Note, not all VARIANT types are supported for implicit conversion by the PI SDK.  The caller of the Add is responsible for coercing an unsupported VARIANT type into one that the PI SDK and PI server can use.


For ValueAttributes, if a NamedValue of Name "Questionable" is present, the Value of that NamedValue will establish the value of the flag.  If a NamedValue of Name "Annotations" is present, the Value of that NamedValue is used as the annotation.  In the event that is saved in the PI server, the "Annotated" flag will be set - an annotation is present.   Replacing a previous event that contains an annotation with a value that does not have an annotation will not remove the annotation from the value.  Removal of an annotation is done by replacing the server event with a PIValue of the same timestamp and an annotation with a blank (zero-length) string.  A blank string as an annotation will not create an annotation, but will always remove an annotation if present.  A blank annotation will do nothing, if there is no annotation previously present.  Note, the replacement of a server event with another event, even the same value with a blank annotation, will set the "Substituted" flag on the event, since the event has been altered.

Trappable Errors

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

Error Description
psePIVALADD Failed to add the value.  See the Description field of the error object for more information.
pseVARIANTNOTDATE The passed timestamp argument could not be converted to a valid date/time.
pseVARIANTTYPEASTIME The passed timestamp VARIANT was not recognized as a type that could be converted to a time.
pseOBJECTNOTPITIME The passed timestamp VARIANT contained an object but it was not a PITime.
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.
psePIVALUECREATE Unable to create a PIValue to return.  See the Description field of the error object for more information.
psePIVALUESTORE Unable to store the passed value in a PIValue object.  Possibly an unsupported type.
psePITIMECREATE Unable to create a PITime object for the PIValue.
psePIVALUESTOREPITIME Unable to store the PITime object into the PIValue.

Enabling Operational Intelligence