Click or drag to resize
OSIsoft, LLC

PIPointListSummaries Method (AFTimeRange, AFTimeSpan, AFSummaryTypes, AFCalculationBasis, AFTimestampCalculation, PIPagingConfiguration)

Returns several summaries over a time range for each interval within the range for each PIPoint in the list.

Namespace:  OSIsoft.AF.PI
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.8.440
Syntax
public IEnumerable<IDictionary<AFSummaryTypes, AFValues>> Summaries(
	AFTimeRange timeRange,
	AFTimeSpan summaryDuration,
	AFSummaryTypes summaryTypes,
	AFCalculationBasis calculationBasis,
	AFTimestampCalculation timeType,
	PIPagingConfiguration pagingConfig
)

Parameters

timeRange
Type: OSIsoft.AF.TimeAFTimeRange
The bounding time range over which the summary intervals are computed.
summaryDuration
Type: OSIsoft.AF.TimeAFTimeSpan

The duration of each summary interval. If specified in hours, minutes, seconds, or milliseconds, the summary durations will be evenly spaced UTC time intervals. Longer interval types are interpreted using wall clock rules and are time zone dependent. For example, an interval created with the string "24h" means using an evenly spaced 24 UTC hour interval between each event. On the other hand, an interval created with the string "1d" would return an interval shorter or longer than 24 hours if the interval encompasses a Daylight Savings Time change.

When a positive duration is specified, the summary calculation begins at the earliest bounding time in the timeRange and applies the duration repeatedly in time ascending direction to generate the summary intervals.

If a negative duration is specified, the summary calculation begins at the latest bounding time in the timeRange and applies the duration repeatedly in time descending direction to generate the summary intervals. Note that the order of values returned will still be reflected by the timeRange, regardless of the summary duration sign.

summaryTypes
Type: OSIsoft.AF.DataAFSummaryTypes
A flag which specifies one or more summaries to compute for each interval over the time range
calculationBasis
Type: OSIsoft.AF.DataAFCalculationBasis
Specifies the method of evaluating the data over the time range.
timeType
Type: OSIsoft.AF.DataAFTimestampCalculation
A flag indicating what how to calculate a timestamp for each interval.
pagingConfig
Type: OSIsoft.AF.PIPIPagingConfiguration
Contains the paging configuration parameters for the request.

Return Value

Type: IEnumerableIDictionaryAFSummaryTypes, AFValues

An enumerable of summaries results for each PIPoint in the list. The results are not guaranteed to match the order of the PIPointList, and duplicate points in the list will not produce a duplicate result. The results can be mapped back to the corresponding PI Point using the PIPoint property on each result.

The order of the results are predictable; however, if you need the results in the same order as the attribute list, then consider using a dictionary keyed by PI Point to construct a list in the same order.

The points in the list are broken up by their corresponding PI Data Archive. A bulk call is made against each PI Data Archive in parallel. The results are made available as they are returned from the PI Data Archive in the order that the bulk calls were made.

The following example shows a list of points including duplicates from three different PI Data Archives:

PI PointPI Data Archive
Lobby_Room_TemperatureContoso
Lobby_Room_TemperatureNorthwind
Lobby_Room_TemperatureContoso
Lobby_Room_TemperatureAdventureWorks
Kitchen_Room_TemperatureContoso

This table shows the order that the results would be returned:

PI PointPI Data Archive
Lobby_Room_TemperatureContoso
Kitchen_Room_TemperatureContoso
Lobby_Room_TemperatureNorthwind
Lobby_Room_TemperatureAdventureWorks

Since the first point is on the Contoso PI Data Archive, it is the first PI Data Archive to receive a bulk call; therefore, all Contoso point results will be returned first. Duplicate points do not produce a duplicate result, so the duplicate Contoso Lobby_Room_Temperature does not produce a second return value. After the Contoso results have been returned, the Northwind results are returned followed by the AdventureWorks results.

Exceptions
ExceptionCondition
ArgumentOutOfRangeException The summaryTypes cannot be None.
OperationCanceledExceptionWhen an error occurs that prevents the operation from proceeding. Check the Error property on the pagingConfig object for more specific error information.
ArgumentNullExceptionWhen pagingConfig is .
Remarks

The following table illustrates the interaction between timeRange and summaryDuration with the timestamp summary calculations and order of returned values for each summary type.

Time RangeSummary DurationSummaries returned in AFValues
Ascending (Y to T)Positive (5h)Y to Y+5h, Y+5h to Y+10h, Y+10h to y+15h, Y+15h to Y+20h
Descending (T to Y)Positive (5h)Y+15h to Y+20h, Y+10h to Y+15h, Y+10h, Y+5h to Y+10h, Y to Y+5h
Ascending (Y to T)Negative (-5h)T-20h to T-15h, T-15h to T-10h, T-10h to T-5h, T-5h to T
Descending (T to Y)Negative (-5h)T-5h to T, T-10h to T-5h, T-15h to T-10h, T-20 to T-15h

Time-weighted totals are computed 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. The use can use the PercentGood summary to determine if the calculation results are suitable for the application's purposes.

Note Notes to Callers
This method, property, or class is only available in the .NET 4 version of the SDK.

Important note Important
This method will use a single bulk Remote Procedure Call if the PI Data Archive supports it, otherwise it will issue individual RPCs in parallel. Results are available for enumeration as they returned from the PI Data Archive.

Important note Important
When individual RPCs are issued in parallel, each RPC is made using the caller's security context. When making these calls while impersonating, the thread or runtime must be configured to propagate the impersonation across these asynchronous points (see the SecurityContext documentation for details).

Important note Important
The returned enumerable collection can be enumerated one time. As the collection is enumerated, the internal data structures are disposed. Any attempt to reset or enumerate a second time will result in an exception.

Note Notes to Callers
This call might use a background task to complete some of its work. See the Threading Overview for some matters to consider when execution transitions to another thread.

Examples
// Holds the results keyed on the associated point
var resultsMap = new Dictionary<PIPoint, AFValues>();

// Results should be sent back for 100 tags in each page.
PIPagingConfiguration config = new PIPagingConfiguration(PIPageType.TagCount, 100);

try
{
    var listResults = pointList.Summaries(timeRange, timeSpan,
        AFSummaryTypes.Average, AFCalculationBasis.TimeWeighted,
        AFTimestampCalculation.Auto, config);

    foreach (IDictionary<AFSummaryTypes, AFValues> pointResults in listResults)
    {
        // Get average values from the result dictionary
        AFValues pointValues = pointResults[AFSummaryTypes.Average];
        PIPoint point = pointValues.PIPoint;

        // Map the results back to the point
        resultsMap[point] = pointValues;
    }
}
catch (OperationCanceledException)
{
    // Errors that occur during bulk calls get trapped here
    // The actual error is stored on the PIPagingConfiguration object
    Console.WriteLine(config.Error.Message);
}
catch (Exception otherEx)
{
    // Errors that occur in an iterative fallback method get trapped here
    Console.WriteLine(otherEx.Message);
}
Version Information

AFSDK

Supported in: 2.10.5, 2.10, 2.9.5, 2.9, 2.8.5, 2.8, 2.7.5, 2.7, 2.6
See Also