Summary Method (PIValues collection)

               

 

The Summary method is used to retrieve a single summary type over the user specified time range. The method returns a PIValue whose Value property is the calculated summary, and whose TimeStamp property is the time at the end of the period. For minimum or maximum calculations, the time stamp is the time of the first minimum/maximum event.  The ValueAttributes property of the PIValue contains additional information about the summary result. See the Remarks section for more details. This call is not supported when the PIValues contains results retrieved from a PI2 server. 

 

Syntax

object.Summary StartTime, EndTime, SummaryType, CalculationBasis, AsyncStatus

The Summary method syntax has these parts:

Part

Description

object

An object expression that evaluates to a PIValues collection.

StartTiime

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.

SummaryType

The type of summary desired. This is a value from the ArchiveSummaryTypeConstants enumeration.  See settings below.

CalculationBasis

The method used to evaluate the stream of values.  This is a value from the CalculationBasisConstants enumeration. See settings below.

AsyncStatus

An optional PIAsynchStatus object. To monitor the progress of the call asynchronously, the caller creates this object and passes it to the call. The caller may then use the PIAsynchStatus object's events to track the call's progress, and to cancel it if desired.  Not currently supported.  

 

Settings

The settings for StartTime and EndTime are:

 

The settings for SummaryType are:


The settings for CalculationBasis are:


 

 

Remarks

Usage Notes

This call is not supported when the PIValues contains results retrieved from a PI2 server.  PI2 servers base their calculations on local time.  PIValues.Summary uses UTC time as the basis for its calculations.

The PI3 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.

 

Calculation Result Format

The value field of the PIValue object holds the calculation result. 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. 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. 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
TimeOfMaxVal Time of Maximum value in the period PITime only for type Maximum or range
TimeOfMinVal Time of Minimum value in the period PITime only for type Minimum or range

 

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
PISDK_E_CALCFAILED Calculation error like not enough good value to do calculation
PISDK_E_ERRCONVOUTPUT Error converting calculation result to PISDK result format

 

Enabling Operational Intelligence