AF SDK Reference

PIPointList.PlotValues Method

Save PDF

PIPointList.PlotValues Method

Save PDF

Last UpdatedNov 18, 2025
6 minute read

Retrieves values over the specified time range suitable for plotting over the number of intervals (typically represents pixels).

Namespace: OSIsoft.AF.PI
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

public IEnumerable<AFValues> PlotValues(
	AFTimeRange timeRange,
	int intervals,
	PIPagingConfiguration pagingConfig
)

Public Function PlotValues ( 
	timeRange As AFTimeRange,
	intervals As Integer,
	pagingConfig As PIPagingConfiguration
) As IEnumerable(Of AFValues)

Dim instance As PIPointList
Dim timeRange As AFTimeRange
Dim intervals As Integer
Dim pagingConfig As PIPagingConfiguration
Dim returnValue As IEnumerable(Of AFValues)

returnValue = instance.PlotValues(timeRange, 
	intervals, pagingConfig)

public:
IEnumerable<AFValues^>^ PlotValues(
	AFTimeRange timeRange, 
	int intervals, 
	PIPagingConfiguration^ pagingConfig
)

member PlotValues : 
        timeRange : AFTimeRange * 
        intervals : int * 
        pagingConfig : PIPagingConfiguration -> IEnumerable<AFValues>

Parameters

timeRange: Type: OSIsoft.AF.TimeAFTimeRange
The bounding time range for the plot values request.
intervals: Type: SystemInt32
The number of intervals to plot over. Typically, this would be the number of horizontal pixels in the trend.
pagingConfig: Type: OSIsoft.AF.PIPIPagingConfiguration
Contains the paging configuration parameters for the request.

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 Point	PI Data Archive
Lobby_Room_Temperature	Contoso
Lobby_Room_Temperature	Northwind
Lobby_Room_Temperature	Contoso
Lobby_Room_Temperature	AdventureWorks
Kitchen_Room_Temperature	Contoso

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

PI Point	PI Data Archive
Lobby_Room_Temperature	Contoso
Kitchen_Room_Temperature	Contoso
Lobby_Room_Temperature	Northwind
Lobby_Room_Temperature	AdventureWorks

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

Exception	Condition
ArgumentOutOfRangeException	The intervals must be greater than zero.
OperationCanceledException	When an error occurs that prevents the operation from proceeding. Check the Error property on the pagingConfig object for more specific error information.
ArgumentNullException	When pagingConfig is .

Remarks

For each interval, the data available is examined and significant values are returned. Each interval can produce up to 5 values if they are unique, the first value in the interval, the last value, the highest value, the lowest value and at most one exceptional point (bad status or digital state).

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.

Notes to Callers
This method, property, or class is not available in the legacy .NET 3.5 version of the SDK.

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
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
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.

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.PlotValues(timeRange, 1000, 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);
}

' Holds the results keyed on the associated point
Dim resultsMap As New Dictionary(Of PIPoint, AFValues)

' Results should be sent back for 100 tags in each page.
Dim config As New PIPagingConfiguration(PIPageType.TagCount, 100)

Try

    Dim listResults As IEnumerable(Of AFValues) =
        pointList.PlotValues(timeRange, 1000, config)

    For Each pointResults As AFValues In listResults
        ' Map the results back to the point
        resultsMap(pointResults.PIPoint) = pointResults
    Next

Catch canceledEx As 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 otherEx As Exception

    ' Errors that occur in an iterative fallback method get trapped here
    Console.WriteLine(otherEx.Message)
End Try

No code example is currently available or this language may not be supported.

Version Information

AFSDK

Supported in: 3.1.1, 3.1.0, 3.0.2, 3.0.1, 3.0.0, 2.10.11, 2.10.5, 2.10.0, 2.10, 2.9.5, 2.9, 2.8.5, 2.8, 2.7.5, 2.7, 2.6

AF SDK Reference