RecordedValuesByCount Method (PIData object)

                    

 

This method returns Count compressed values beginning at the requested start time in the direction specified as a PIValues collection.

Syntax

object.RecordedValuesByCount StartTime, Count, Direction, BoundaryType, [FilterExp], [ShowFiltered], [AsyncStatus]

The RecordedValuesByCount 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.
Count

A long integer containing the number of compressed values to return

Direction A value from the DirectionConstants enumeration indicating the direction in time from the start time to proceed when returning successive values.  See the Settings section for allowable values.
BoundaryType A value from the BoundaryTypeConstants enumeration 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 are:

The possible values for Direction are:

The possible values for BoundaryType, used for determining how events at or near StartTime are returned, are:

The possible values for ShowFiltered are:

Remarks

To retrieve values within a time range use the RecordedValues method.

 

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 DigitalState "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. 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.

Trappable Errors

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

Error

Description

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

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.

psePIEVENTSTOSAFEARRAYS

Failed to convert native PI3 events into Automation compatible SafeArrays. More information is available in the error's description field.

pseDIRECTIONINVALID

An invalid direction constant was specified.

pseVARIANTTYPEASTIME A Variant passed for a time argument did not contain a variant type that is supported.
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