Summary Method (PIData object)

                    

Summary 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.

 

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 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.
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 possible values in the variant for StartTime and EndTime are:


The settings for SummaryType are:


 

The settings for CalculationBasis are:


 

Remarks

AstCount is the only summary type that supports non-numeric tags (such as string tags or digital tags). Requesting for the any other summary types on non-numeric tags will result in an error of E_INVALIDARG.

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 and most PI2 systems 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.

Currently, against a PI2 server, only limited combinations of SummaryType and CalculationBasis are supported (those available through the PI-API function piar_summary). Specifically, with CalculationBasis set to cbTimeWeighted, all SummaryType settings except astCount are supported. With CalculationBasis set to cbEventWeighed, only SummaryType astAverage is supported. The rest of the CalculationBasis settings are not supported against PI2 servers.

 

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

 

 


Trappable Errors

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

Error Description

pseVARIANTTOTIMESTAMP

Failed to convert passed variant to a valid time.

pseUNSUPPORTEDRETRIEVALTYPE

Combination of arguments is not supported.

pseNOTIMPL

Combination of arguments is not currently implemented.

pseEVENTSRETRIEVE

Failed to retrieve summary value from server. Check the error description field for details.

pseCALCFAILED

Calculation failed on the server.  Check the error description field for details.

pseINVALIDARG

One or more of the passed arguments is invalid.  Possibly the values specified for SummaryType or CalculationBasis do not come from the enumeration.  Check the error description field for additional information. 

pseVARIANTNOTDATE

A variant containing a string passed for a timestamp could not be converted to a date.

pseVARIANTTIMETODOUBLE

A variant passed for a timestamp could not be converted to a positive number of seconds since 1970.

VARIANTTYPEASTIME

The passed variant was not of a type that could be converted to a time.

Enabling Operational Intelligence