ExpressionSummaries Method (IPICalculation interface)

              

 

This method creates a data stream from an arbitrary expression and calculate one or more summaries on the expression result. The method returns a NamedValues collection with the requested summaries as described below under Remarks. This method is currently not supported for PI2 servers.

 

Syntax

object.ExpressionSummaries StartTime, EndTime, SummaryDuration, Expression, SummaryType, CalculationBasis, stSampleType, SampleInterval, 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 ExpressionSummaries method syntax has these parts:

Part Description
object

An object expression that evaluates to an IPICalculation interface.

StartTime

A Variant containing the start time of the evaluation period. See the Settings section for allowable values. The StartTime, EndTime and SummaryDuration arguments together determine the number of calculation periods and the starting and ending times of each period. See the Remarks section for how the calculation periods are determined.

EndTime

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

SummaryDuration A Variant containing the length of summary period. See the Settings section for allowable values and the Remarks section for usage.

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.

SummaryType A value from the ArchiveSummariesTypeConstants enumeration specifying the kind(s) of summaries to calculate.  Note this argument is not a bit mask.  See the Settings section for allowable values.
CalculationBasis A value from the CalculationBasisConstants enumeration specifying the method of evaluating the event stream.  See the Settings section for allowable values. This argument is optional and the default value is cbTimeWeighted.

stSampleType

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. This argument is optional and the default value is stRecordedValues.

SampleInterval

A Variant containing the time interval at which the sampling is performed within the specified time range.  See the Settings section for allowable values. If SampleType 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 CalculationDuration are:

 

The settings for SummaryType are:


 

The settings for CalculationBasis are:


 

The possible values for stSampleType are:

 

The possible values for SampleInterval are:

 

 

Remarks

Usage Notes

The PI server computes time-weighted total by integrating the rate tag values over the requested time range. If some of the data are bad in the time range, the calculated total is divided by the fraction of the time period for which there are good values. Mathematically, this approach is equivalent to assuming that during the period of bad data, the tag takes on the average values for the entire calculation time range. It is important for the user of the data to check the percentGood attribute to determine if the calculation result is suitable for the application's purposes.

When the PI server performs the integration for the time-weighted total, it does not have knowledge of the time unit of the rate tag. Therefore, the server performs the time-weighted total using the same time unit for all the tags. The default time unit for all PI3 servers is "per day". If the measured time component of the rate tag is not based on a day, the user of the data has to convert the totalization result to the appropriate units. For example, if the rate tag has engineering units of "gallons/minute", the user needs to multiply the time-weighted total result by 1440 (minutes/day) to obtain the correct number of gallons for the period.

Specifying Calculation Intervals

Given the StartTime, EndTime and Duration, this function generates a number of contiguous calculation time periods where the computation results are returned according to the following rules:

1.  When the Duration 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, Duration 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 Duration of "1d", the calculation will be performed for nine one calendar day periods, 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 Duration is specified, the function starts at the earliest time (i.e. the smaller of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in ascending time direction to generate the calculation periods. 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 Duration, the function starts at the latest time (i.e. the larger of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in descending time direction to generate the calculation periods. 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.

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

 

  Time Ascending Time Descending Time Ascending with negative Duration Time Descending with negative Duration
StartTime

Y

T

Y T
EndTime

T

Y

T Y
Duration

5h

5h

-5h -5h
Period for PIValues(1) 12a.m. to 5a.m. 3p.m. to 8p.m. 4a.m. to 9a.m. 7p.m. to 12p.m.
Period for PIvalues(2) 5a.m. to 10a.m. 10a.m. to 3p.m. 9a.m. to 2p.m. 2p.m. to 7p.m.
Period for PIvalues(3) 10a.m. to 3p.m. 5a.m. to 10a.m. 2p.m. to 7p.m. 9a.m. to 2p.m.
Period for last PIvalue 3p.m. to 8p.m. 12a.m. to 5a.m. 7p.m. to 12p.m. 4a.m. to 9a.m.

 

 

Calculation Result Format

The summaries methods can compute multiple summary results over multiple calculation periods. The summaries methods return the result as a NamedValues collection. Each requested summary type produce a corresponding NameValue item in the NamedValues collection. The name property of the NameValue item contains the string representing the summary type. The following table shows the string corresponding to each summary type. SummariesType like asAll or asTotalAndAvg will result in NamedValues collection with more than one item.

Summary Type Name in NamedValue item
Total Total
Minimum Minimum
Maximum Maximum
Range Range
Average Average
Standard Deviation StdDev
Population Standard Deviation PStdDev
Count Count

 

The value property of the NameValue item contains a PIValues collection holding the result over multiple calculation periods for the corresponding summary type. Every calculation period has one corresponding PIValue object in the PIValues collection. The value field of the PIValue object holds the calculation result. The timestamp of each PIValue object is assigned to the start time of the calculation period. The start time of the calculation period is always the earliest time of the period even when the StartTime and the EndTime arguments are specified in reversed time order. If there is error in the calculation period, the value field of the PIValue object is set to VT_ERROR.

The ValueAttributes of each of the PIValue contains additional information about the calculation result in the period. The start time and the end time of the calculation period are stored as NameValue item EarliestTime and MostRecentTime. If there is problem when the server computes the result, the PIValue.value will contain a variant with VT_ERROR type and the full error description is put into the NameValue item of ErrDescription. The following table shows all the possible NameValue items in the ValueAttributes of a summary calculation result PIvalue:

Name Description Data Type Always Present
EarliestTime Start time of the calculation period PITime yes
MostRecentTime End time of the calculation period PITime yes
PercentGood Percent of data with good value during the calculation period. For timeweighted calculation, percentgood is based on time. For eventweighted, percentgood is based on event count. Double Precision Float yes except when the calculation result is VT_Error
TimeOfMaxVal Time of Maximum value in the period PITime only for type Maximum or range and no calculation error
TimeOfMinVal Time of Minimum value in the period PITime only for type Minimum or range

and no calculation error

ErrDescription Error message string String only when the calculation result is VT_Error

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_CALCFAILED Other calculation error from the PI Server
PISDK_E_ERRCONVOUTPUT Error converting PI Server result to PISDK result format

 

 

Enabling Operational Intelligence