GetSelectedAttributes Method (IPointAttributes interface)

                  

 

Given an attribute list, this method fetches and optionally returns the requested attributes for all the points in the owner (PointList) collection. These attributes are kept in local cache in order to make the subsequent attribute retrievals very efficient.

The method returns a PIErrors collection to indicate specific errors during execution, please view the remarks section below for more detailed information.

 

Syntax

object.GetSelectedAttributes nvRetrievalAttributes, [bReturnAttrCollection], [nvAttributes]

 

The GetSelectedAttributes method syntax has these parts:

Part

Description

object

An object expression that evaluates to a PointList object.

nvRetrievalAttributes

A list of point attributes that should be returned by this call. This is described under Remarks below.

bReturnAttrCollection

An optional boolean flag to indicate whether the method should return the retrieved attributes in a NamedValues collection (nvAttributes argument). Default value is false.

nvAttributes

An optional NamedValues collection for the returned attributes.

 

Remarks

This call provides a simple and efficient mechanism to fetch and/or update a set of point attributes for an arbitrary collection of points.

 

The GetSelectedAttributes method is very similar to GetPoints2 method in that they both return user defined attributes for a set of points. The main difference is that GetPoints2 returns a list of points based on a given criteria while GetSelectedAttributes operates on an existing PointList.

 

The call fetches all point attributes if the nvRetrievalAttributes list contains one (1) item named * (this is equivalent to SQL 'Select * from PIPoint' statement).

The attributes are returned in a nested NamedValues collection. The top level collection has an item (NamedValue) for each PIPoint that can be identified by a tag name. The value of the top level item is a NamedValues collection containing the attributes for this point.

 

Important notes

It is important to understand how to best access the results if the user chooses to use the PointAttributes collection of each PIPoint instead of the return attributes. The most efficient ways to accomplish this is to use either GetAttributes or GetSelectedAttributes methods of the PointAttributes class, enumerating the collection or accessing the Count property will cause a full attribute load and a call to the server.

Retrieving multiple attributes from multiple points from PI3 server may lead to unexpected results in cases when points with different point classes are selected. The returned attribute lists are sized according to "maximum found" and the value/type for missing attributes is set to empty (VT_EMPTY). The caller should always validate each individual attribute and discard invalid ones.

 

 

 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error

Description

pseGETPOINTS

The call failed. Consult the returned error collection and error description for more detailed server information on the cause of the failure. The name of the failed server is stored in the "Cause" property of each individual PIError.

Enabling Operational Intelligence