InterpolatedValues2 Method (IPIData2 interface)

                    

The  method returns interpolated values from the archive over the specified time range as a PIValues collection. InterpolatedValues2 differs from PIData.InterpolatedValues only in the specification of the sampling interval. In PIData.InterpolatedValues, user specifies number of intervals and PISDK computes the interval length based on start time, end time and the number of intervals. The interval length is constant throughout the period. In InterpolatedValues2, user specifies the interval length as a variant in the SampleInterval argument. The interval length could change within the requested time period.

Syntax

object.InterpolatedValues2 StartTime, EndTime, SampleInterval, [FilterExp], [ShowFiltered], [AsynchStatus]

The InterpolatedValues2 method syntax has these parts:

Part Description
object An object expression that evaluates to a PIData object.
StartTime A Variant containing the desired start time. See the Settings section for allowable values.

EndTime A Variant containing the desired end time. See the Settings section for allowable values.
SampleInterval A Variant representing the sampling interval.  See the Settings section for allowable values.
FilterExp A string containing a filter expression [Optional]
ShowFiltered An value from the FilteredViewConstants enumeration that controls whether filtered events are returned with a filter status or not shown at all. [Optional] See the Settings section for allowable values. 
AsyncStatus A PIAsynchStatus object for launching an asynchronous call, determining the progress of, or cancelling a lengthy call. [Optional]

Settings

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


 

The possible values for SampleInterval are:

The possible values for ShowFiltered are:


Remarks

Specifying Archive Event Intervals with SampleType of stInterval

Given the StartTime, EndTime and SampleInterval, this function generates a series of time stamps according to the following rules. The archive events are then retrieved at each of these time stamps.

1.  When the SampleInterval argument is specified as a string, the way the archive interval is determined depends on the server type and the interval type.

Against a PI2.x server, wall clock rules based on client machine time zone are used to determine the interval length for all interval types.

Against a PI3.x server, intervals specified in "seconds", "minutes" and "hours" are interpreted as evenly spaced UTC time intervals. The rest of the interval types are interpreted using wall clock rules. Wall clock rules are time zone dependent. If the StartTime and EndTime arguments are specified as PITimeFormat objects, the wall clock rules of the PITimeZoneInfo of the passed PITimeFormat object are used to determine the calculation intervals. Otherwise, wall clock rules based on the client machine time zone are used. For example, against a PI 3 server, SampleInterval of "24h" means using an evenly spaced 24 UTC hour interval between each event. On the other hand, for a StartTime of April 1, 2003, EndTime of April 10, 2003 and SampleInterval of "1d", archive events are retrieved at ten time stamps, each one calendar day apart, with the sixth interval covering only 23 UTC hours because of Daylight Savings Time change. 

2.  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. Using the example in rule 1, reversing the StartTime and EndTime, the result PIValues collection will be generated in descending time order, starting with April 9 period and ending with the April 1 period.

3.  When positive SampleInterval is specified, the function starts at the earliest time (i.e. the smaller of the StartTime and the EndTime argument) and applies the SampleInterval as interval length repeatedly in ascending time direction to generate the calculation intervals. Therefore, if the StartTime is more recent than the EndTime, the function starts at the EndTime, otherwise, the function starts at the StartTime. The function stops at the closest interval to the latest time (i.e. the larger of the StartTime and the EndTime argument) but does not go beyond the it. 

4.  For negative SampleInterval, the function starts at the latest time (i.e. the larger of the StartTime and the EndTime argument) and applies the SampleInterval as interval length repeatedly in descending time direction to generate the calculation intervals. Therefore, if the StartTime is more recent than the EndTime, the function starts at the StartTime, otherwise, the function starts at the EndTime. The function stops at the closest interval to the earliest time (i.e. the smaller of the StartTime and the EndTime argument) but does not go beyond the it.

Note that the order of the PIValues still obeys rule 2 where the results index order reflects the start and end time specification regardless of the sign of the SampleInterval.

Rules 2, 3 and 4 apply to SampleInterval specified in string as well as numeric format. The determination of the calculation interval and results index order from the Start/End time and SampleInterval specifications are demonstrated in the following table:

 

  Time Ascending Time Descending Time Ascending with negative SampleInterval Time Descending with negative SampleInterval
StartTime

Y

T

Y T
EndTime

T

Y

T Y
SampleInterval

5h

5h

-5h -5h
time of PIValues(1) 12 a.m. 8 p.m. 4 a.m. 12 p.m.
time of PIvalues(2) 5 a.m. 3 p.m. 9 a.m. 7 p.m.
time of PIvalues(3) 10 a.m. 10 a.m. 2 p.m. 2 p.m.
time of PIvalues(4) 3 p.m. 5 a.m. 7 p.m. 9 a.m.
time of PIvalues(5) 8 p.m. 12 a.m. 12 p.m. 4 a.m.

 

Trappable Errors

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

Error Description
E_INVALIDARG Some of the function argument are not valid.
E_NOTIMPL This combination of the function arguments is not implemented at current PISDK version or not supported by this version of the PI Server.
PISDK_E_ERRCONVINPUT Problem converting input arguments to PI Server calling arguments.
E_ACCESSDENIED No read access to PI Server
PISDK_E_DATENOTONLINE Archive not online for specified time range
PISDK_E_EVENTSRETRIEVE Other calculation error from the PI Server
PISDK_E_ERRCONVOUTPUT Error converting PI Server result to PISDK result format
Enabling Operational Intelligence