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.
The Summaries method syntax has these parts:
|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.|
The possible values in the variant for StartTime and EndTime are:
The settings for SummaryType are:
The settings for CalculationBasis are:
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.
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|
|Population Standard Deviation||PStdDev|
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|
In addition to generic errors (such as Out of Memory), the following errors may occur:
|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|