GetPoints2 Method (IGetPoints2 interface)

                  

 

Given a query string and return attribute list, this method returns a PointList collection that contains PIPoint objects which match the request. The query string is in the format of a simple SQL "Where clause" .

The method may also return a collection of user defined point attributes for each returned PIPoint. These attributes are kept in local cache in order to make the subsequent attribute retrievals very efficient.

Syntax

object.GetPoints2 WhereClause, nvRetrievalAttributes, callType, [asynchStatus], [nvExtraTableList], [Servers]

The GetPoints2 method syntax has these parts:

Part Description

object

An object expression that evaluates to a Server object.

WhereClause

A string containing an expression in simple SQL syntax that defines the desired selection criteria. The "where" keyword should be omitted from the string. The exact syntax depends on the call type, see the callType parameter.

nvRetrievalAttributes

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

callType

A GetPointsRetrievalTypes enumeration defining the subsystem and/or internal method to be used for the actual data retrieval. Currently supported modes are useGetPoints and useGetPointsSql.

AsynchStatus

An optional PIAsynchStatus object created by the caller and passed to the call allowing the method to be executed asynchronously, providing a means to cancel the call, and providing a means for the caller to be signaled as the call progresses and completes its tasks or to poll for results.

nvExtraTableList

An optional argument containing the names of tables other than PIpoint used in the whereClause argumen (see Server.GetPointSQL)

Servers

An optional NamedValues collection containing the names of the servers that should be accessed by this call. This is described under Remarks below.

 

Remarks

This call provides a powerful mechanism for finding specific points and point attributes on given servers based on a wide range of criteria. The call makes use of the underlying Server's GetPoints method and follows the SQL syntax described in the documentation of that method.

 

Because GetPoints2 is such a powerful call, care must be used in constructing reasonable queries.  Posting a complicated query that involves looking at every tag on a large PI system can take some time to execute and adversely affect other users as with any database system.  Adding a restriction based on tag name or point source is advisable for performance.

 

The method retrieves the most important attributes even if the nvRetrievalAttributes is not defined or is empty. These attributes are Tag, PointID, PointType and Descriptor for GetPoints call. There is no need to include these in the attributes collection because they will be inserted if not present.

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

Important note

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 (applies to GetPoints mode).

 

GetPoints vs. GetPointsSQL

GetPointsSQL can implement complex queries, including joins with other PI tables. GetPoints cannot do such complex queries, but it is faster, and can use custom point attributes, which GetPointsSQL cannot. To convert between equivalent GetPoints and GetPointsSQL queries, note that GetPointsSQL uses attribute names as defined by PI-ODBC, but GetPoints uses attribute names as defined internally in the PI Point Database. These names, and data types, differ in some instances so the system needs to convert the ODBC based attributes to match the Point Database. This process affects the following ODBC attributes:

    - DIGNUMBER, POINTTYPE, RECORDTYPE and RES are ignored

    - Following attributes are renamed:

        POINTNUMBER (pointid),  POINTID (recno),  POINTTYPEX (converted to pointtype), POINTCLASS (ptclassid)

        POINTACCESS (ptaccess), POINTGROUP (ptgroup), POINTOWNER (ptowner)

        DIGSTARTCODE (converted to digitalset)

 

Detailed information and examples for GetPoints2 is available on the "GetPoints Syntax" page.

 

The Servers argument is currently ignored.

 

If no points are found by the Server.GetPoints call it returns an empty PointList collection.

 

Trappable Errors

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

Error Description

pseNOPOINTSFOUND

The query returned no points.

pseSYNTAX

The query contained one or more syntax errors. You will find more detailed information in Err.Description.

pseGETPOINTS

The call failed. Consult the Err.Description for more detailed server information on the cause of the failure.

Enabling Operational Intelligence