The Summaries2 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. Summaries2 differs from PIData.summaries 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.
object.Summaries2 StartTime, EndTime, CalculationDuration, SummaryType, CalculationBasis, AsyncStatus
The Summaries2 method syntax has these parts:
|object||An object expression that evaluates to a IPIData2 interface. This interface can be obtained from a PIData object.|
|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.|
|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.|
|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 possible values for CalculationDuration 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.
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|
|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 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|