Click or drag to resize
OSIsoft, LLC

PIPointListRecordedValues Method

Returns a list of compressed values for the requested time range from PI.

Namespace:  OSIsoft.AF.PI
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.8.440
Syntax
public IEnumerable<AFValues> RecordedValues(
	AFTimeRange timeRange,
	AFBoundaryType boundaryType,
	string filterExpression,
	bool includeFilteredValues,
	PIPagingConfiguration pagingConfig,
	int maxCount = 0
)

Parameters

timeRange
Type: OSIsoft.AF.TimeAFTimeRange
The bounding time range for the recorded values request. If the StartTime is earlier than the EndTime, the resulting values will be in time-ascending order, otherwise they will be in time-descending order.
boundaryType
Type: OSIsoft.AF.DataAFBoundaryType
A value from the AFBoundaryType enumeration that determines how the times and values of the returned end points are determined.
filterExpression
Type: SystemString
A filter expression that follows the performance equation syntax.
includeFilteredValues
Type: SystemBoolean
Specify to indicate that values which fail the filter criteria are present in the returned data at the times where they occurred with a value set to a "Filtered" enumeration value with bad status. Repeated consecutive failures are omitted.
pagingConfig
Type: OSIsoft.AF.PIPIPagingConfiguration
Contains the paging configuration parameters for the request.
maxCount (Optional)
Type: SystemInt32
The maximum number of values to be returned. If zero, then all of the events within the requested time range will be returned.

Return Value

Type: IEnumerableAFValues

An enumerable of AFValues 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
ArgumentOutOfRangeExceptionmaxCount cannot be less than zero.
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

Returned times are affected by the specified boundaryType. If no values are found for the time range and conditions specified then the method will return success and an empty AFValues collection.

When specifying for the includeFilteredValues parameter, consecutive filtered events are not returned. The first value that would be filtered out is returned with its time and the enumeration value "Filtered". The next value in the collection will be the next compressed value in the specified direction that passes the filter criteria - if any.

When both boundaryType and a filterExpression are specified, the events returned for the boundary condition specified are passed through the filter. If the includeFilteredValues parameter is , the boundary values will be reported at the proper timestamps with the enumeration value "Filtered" when the filter conditions are not met at the boundary time. If the includeFilteredValues parameter is for this case, no event is returned for the boundary time.

Note Note

The PI Data Archive imposes a limit on the maximum number of events that can be returned with a single call. As of PI 3.4.380, the default is set at 1.5M. This behavior can be changed on the server by editing the server's PITimeout table and adding or editing the value associated with the parameter ArcMaxCollect.

When a PI Point is queried over a time range which includes the current source server time, where the latest known value is before the server current time, a manufactured event containing an Enumeration Value with the bad value NoData, will be placed in the results at a timestamp one second past the current server time for boundary types Interpolated and Outside. This is provided to assist the caller in further interpolation of the results. Specifying a boundary type of Inside indicates that no interpolation is desired and this manufactured value is not provided for that case. The NoData will be reflected into any dependent calculation based Data References.

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
Dictionary<PIPoint, AFValues> resultsMap = new Dictionary<PIPoint, AFValues>();

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

try
{
    IEnumerable<AFValues> listResults = pointList.RecordedValues(
        timeRange, AFBoundaryType.Inside, null, false, config);

    foreach (AFValues pointResults in listResults)
    {
        // Map the results back to the point
        resultsMap[pointResults.PIPoint] = pointResults;
    }
}
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
Enabling Operational Intelligence