Calculate Method (IPICalculation interface)

              

 

This method returns a PIValues collection that contains the result of evaluating the passed expression over the passed time range.

Syntax

object.Calculate StartTime, EndTime, Expression, stSampling, SampleFrequency, asynchStatus

The object placeholder is an object that evaluates to a reference to an IPICalculation interface.  This interface can be obtained from the Server object.

 

The Calculate method syntax has these parts:

Part Description

object

An object expression that evaluates to a PIData object.

StartTime

A Variant containing the start time of the evaluation period. See the Settings section for allowable values.

EndTime

A Variant containing the end time of the evaluation period. See the Settings section for allowable values.

Expression

A string containing the expression to be evaluated.  The syntax for the expression follows the Performance Equation syntax as described in the server documentation.

stSampling

A value from the SampleTypeConstants enumeration describing what data values are retrieved within the specified time range for the expression evaluation.  See the Settings section for allowable values. The stRecordedValues option is not supported on a PI 2 server.

SampleInterval

A Variant containing the time interval at which the evaluation is performed within the specified time range.  See the Settings section for allowable values. If stSampling is not specified as stInterval, this argument is ignored. 

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 stSampling are:

 

The possible values for SampleInterval are:

Remarks

Specifying Calculation 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 expression is then evaluated at each of these time stamps.

1.  When the SampleInterval argument is specified as a string, the way the calculation 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 for each calculation. On the other hand, for a StartTime of April 1, 2003, EndTime of April 10, 2003 and SampleInterval of "1d", the calculation will be performed at ten time stamps, each one calendar day apart, with the sixth period 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.

Impact of Regional Settings

Because the expression passed to this method and eventually to the server for evaluation is a string, the string formatting of numeric values becomes an issue.  Evaluation of a PE syntax string on any PI server assumes that English settings are used - decimals are periods.  If an application builds an expression string on a machine set to use non-English regional settings, care must be taken to avoid generating strings that violate the server's assumption.  Code like the following:

    dim fltVal as double

    dim strExp as string

    ....

    strExp = strExp + CStr(fltVal)

will follow the regional settings and generate strings with commas for decimal separators on a machine with that setting.  However the server won't interpret such a string correctly.  

 

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_INVPEEXPR Invalid Expression Syntax
PISDK_E_PERUNTIMEERROR Expression evaluation runtime error
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