Summaries Method (IPIValues2 interface)

             

 

The Summaries method computes several summary types over several intervals in a single call while the PIValues.Summary method only computes one summary type over one time interval. The Summaries method returns the results in a NamedValues collection. The format of the calculation result is described under Remarks below. IPIValues2.Summaries performs the same calculation as IPIData2.Summaries2 except that IPIValues2.Summaries computes the summaries off the local data in the PIValues collection from which it is called while IPIData2.Summaries2 relies on the PI server to compute the results based on its archive data. Because this method relies on the PIValues collection for its source data, for time weighted calculations it returns an error if the StartTime or the EndTime of the calculation is outside the PIValues collection time range.  

Syntax

object.Summaries StartTime, EndTime, CalculationDuration, SummaryType, CalculationBasis, AsyncStatus

The Summaries2 method syntax has these parts:

Part

Description

object

An object expression that evaluates to a IPIValues2 interface. This interface can be obtained from a PIValues 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.

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.  Currently not supported.  

Settings

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:


Remarks

Usage Notes

The PISDK computes time-weighted total by integrating the local data in the PIValues 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 to check the percentGood attribute to determine if the calculation result is suitable for the application's purposes.

When PISDK performs the integration for the time-weighted total, it does not have knowledge of the time unit of the data. Therefore, the time-weighted total is computed assuming the data has units of "per day". If the measured time component of the data source 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 data source 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.

Also, all time-weighted calculation on the PIValues summaries method are computed based on UTC time of the data, regardless of the data source. Therefore, it is possible that the time-weighted summaries result of a PIValues generated from a PI 2 tag does not match the result from a similar summary calculation on the PI2 server if the time range encompasses a DST transition. The time-weighted calculation on the PI2 server is local time based.

 

PIValues Collection

 

As noted above, for time weighted calculations it is essential that the PIValues collection that represents the data source extend over a range at least as wide as the desired calculation to avoid an error being returned (E_INVALIDARG). Note the requirement for the range also implies that there must be a minimum of two values in the PIValues collection (one at or before the start time and one at or after the end time).  Typically a method such as RecordedValues is used for this purpose.  When calling such a method, the user specifies a boundary type from the BoundaryTypesConstants enumeration.  If the same start and end time is used in the RecordedValues retrieval as is used in the calculation it is important that this boundary type ensure there are values at the end points.  This can be accomplished by specifying btOutside or btInterp.  Using btAuto for a boundary type, however, is a problem if the source tag has its Step flag set to 1 indicating it represents discrete values, not a continuous stream.  In this case, btAuto resolves to btInside which will typically result in a PIValues collection with a narrower range than the requested start and end times.

 

Event weighted calculations will be performed even if the PIValues collection is empty, returning CalcFailed for each calculation type requested. Only a single value is necessary for all but StdDev calculations with this CalculationBasis. 

 

An additional consideration is the CalculationBasis argument.  When specifying cbEventWeighted, you do not want to generate interpolated events at the end points of the time range because those artificial events would be used in the event weighted calculation. For cbTimeWeightedDiscrete and cbTimeWeightedContinuous (two options that allow the user to override the source point step attribute interpolation behavior), values should be retrieved specifying btoutside so that the local summaries can generate the needed interpolated data according to the user interpolation specification (discrete or continuous).

An additional consideration when using interpolation to generate values is integer roundoff. If the point is an integer type, interpolated values retrieved from the server could be subject to integer round-off (the server rounds the value before sending it to the client). When a  summary calculation is done on the server (IPIData2 Summaries), the calculation algorithm does the interpolation in double precision and no integer round off is involved. So if RecordedValues was called with btinterpolate and then used to perform a local summary, the result might be different than the same call against the server due to integer round-off.  Retrieving only recorded values (btOutside) avoids this discrepancy.
 

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 interval type. 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, 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
StartTime

Y

T

Y T
EndTime

T

Y

T Y
Duration

5h

5h

-5h -5h
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 NamesValues collection. Each requested summary type produce a corresponding NameValue item in the NamesValues collection. The name property of the NameValue 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 NamesValues collection with more than one item.

Summary Type Name in NamesValue 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 NameValue 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 NameValue 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 NameValue item of ErrDescription. 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 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.
PISDK_E_ERRCONVINPUT Problem converting input arguments.
PISDK_E_CALCFAILED Other calculation error
PISDK_E_ERRCONVOUTPUT Error converting calculation result to PISDK result format
E_INVALIDARG One or more of the arguments is incorrect.  For example the time range of the PIValues is narrower than the requested calculation span.

 

 

Enabling Operational Intelligence