Summaries Method (PIData object)

                    

 

The Summaries method retrieves several summary types in a single call over the specified range, and for each interval within the range. The method returns a NamedValues collection which contains named summaries as PIValues. The format of the NamedValues and the PIValues collections is described under Remarks below. Summaries differs from IPIData2.summaries2 only in the specification of the summary calculation duration. In PIData.summaries, user specifies number of calculation 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 summaries2, user specifies the interval length as a variant in the CalculationDuration argument. The interval length could change within the requested time period.

 

Syntax

object.Summaries StartTime, EndTime, BoundaryType, SummaryType, nIntervals, CalculationBasis, AsyncStatus

The Summaries 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. 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
BoundaryType A value from the BoundaryTypeConstants enumeration. This argument is not being used.
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.
nIntervals A long integer specifying the number of summary calculation intervals
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.
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

AsCount is the only summary type that supports non-numeric tags (such as string tags or digital tags). Requesting for the any other summary types (including asAll) 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 asCount are supported. With CalculationBasis set to cbEventWeighed, only SummaryType asAverage is supported. The rest of the CalculationBasis settings are not supported against PI2 servers.

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 NamedValue item in the NamedValues collection. The name property of the NamedValue 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 NamedValue 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 NamedValue 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 NamedValue item of ErrDescription. The following table shows all the possible NamedValue 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_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