RecordedValues Method (PIData object)

                    

This method returns compressed values for the requested time range from the archive as a PIValues collection.

Syntax

object.RecordedValues StartTime, EndTime, BoundaryType, [FilterExp], [ShowFiltered], [AsyncStatus]

 

The RecordedValues method syntax has these parts:

Part Description
object An object expression that evaluates to a PIData object.
StartTime A Variant containing the time. See the Settings section for allowable values.
EndTime A Variant containing the time. See the Settings section for allowable values. When the specified StartTime is earlier than the EndTime, the resulting PIValues collection will be indexed in time ascending direction. If the StartTime is more recent than the EndTime, the resulting PIValues collection will be indexed in time descending direction.
BoundaryType A value from the BoundaryTypeConstants enumeration type that determines how the times and values of the returned end points are determined.
FilterExp A string containing a filter expression [Optional]
ShowFiltered

A value from the FilteredViewConstants enumeration that controls whether filtered events are returned with a filter status or not shown at all. [Optional]

AsyncStatus A PIAsynchStatus object for launching an asynchronous call, determining the progress of, or canceling a lengthy call. [Optional]

 

Settings

The possible values in the variant for StartTime and EndTime are:

The possible values for BoundaryType are:

The possible values for ShowFiltered are:

Remarks

Returned times are affected by the specified boundary constant.  If no values are found for the time range and conditions specified then the method will return success and an empty PIValues collection. 

When both BoundaryType and FilterExp are specified, the events returned for the boundary condition specified are passed through the filter.  If the ShowFiltered argument specifies fvShowFilteredState, the boundary values will be reported at the proper timestamps with the digital state "Filtered" if the filter conditions are not met at the boundary time.  If instead fvRemoveFiltered is specified for this case, no event is returned for the boundary time.

PI3 systems, when queried over a time range which includes the current server time and where the snapshot value for the PIPoint in question is before the current time, will return an event containing a DigitalState with the value "NO_DATA" one second past the current server time for boundary types btInterp and btOutside.  This event is manufactured by the server to indicate the time range over which the snapshot value is considered valid.  This is provided to assist the caller in further interpolation of the results.  Specifying btInside, indicates that no interpolation is desired and this manufactured value is not provided for that case. 

When specifying fvShowFilteredState for the ShowFiltered argument, consecutive filtered events are not returned from PI3 systems.  The first value that would be filtered out is returned with its time and the digital state "Filtered".  The next value in the collection will be the next compressed value in the specified direction that passes the filter criteria - if any. 

Note, when using a BoundaryType of btAuto for PI2 servers which have no native "step" attribute, step is manufactured based on the point's rescode property.  A rescode value of 4 is equated to a value of 1 for the step attribute.  All other rescodes result in a step attribute of 0.

PI3 servers impose a limit on the maximum number of events that can be returned with a single call.  By default this is set at 150,000 before version 3.4.380 and 1,500,000 events for later PI servers.  This behavior can be changed on the server by editing the server's PITimeout table and adding or editing the value associated with the parameter ArcMaxCollect.

 

When invoking this method asynchronously by passing a PIAsynchStatus object, the call will return quickly (generally with success unless local argument checks fail) but the returned PIValues collection will be empty until the call completes. 

 

 

Trappable Errors

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

Error Description
pseBOUNDARYTYPEUNRECOGNIZED An invalid boundary type was specified.
pseEVENTSRETRIEVE Failed to retrieve events from the server. More information is available in the error's description field.
pseVARIANTNOTDATE A variant passed for a StartTime or EndTime could not be interpreted as a date.
pseOBJECTNOTPITIME A Variant passed for a time argument containing an object (IDispatch pointer) did not contain a PITime object or one of its derivatives.
psePIVALUESCREATE Unable to create a PIValues collection
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