GetPoints Method (Server object)

                    

 

This method accepts a query string, and returns a PointList object that contains PIPoint objects which satisfy the query. The query string syntax is similar to a SQL "where" clause, but simplified.

By default, GetPoints returns a set of four PointAttributes for each PIPoint returned in the PointList collection. In order to return a larger set of PointAttributes to be used in an application use the GetPoints2 method. There are two advantages of the GetPoints2 method. It returns both attributes and PIPoint objects in one network call. Secondly, less client program memory is required to cache a smaller set of PointAttributes. The PointAttribute cache is smaller because retrieving a PointAttribute subsequently may return the entire set of PointAttributes for that PIPoint.

Syntax

object.GetPoints whereClause, [asynchStatus]

The GetPoints method syntax has these parts:

Part

Description

object

An object expression that evaluates to a Server object.

whereClause

A string containing a Boolean expression that defines the desired query. See below for query syntax.

AsynchStatus

An optional PIAsynchStatus object. To monitor the progress of the call asynchronously, the caller creates this object and passes it to the call. The caller may then use the PIAsynchStatus object's events to track the call's progress, and to cancel it if desired.

 

Query Syntax

The basic test syntax has these parts:

Part

Description

attribute-name

The name of a point attribute, such as descriptor or pointid. You may enclose the name in single or double quotes, but this is not necessary unless the name contains punctuation.

relational-op

<, <=, >, >=, =, or <>. No other relational operators are supported in this release.

value

A number, string, or date, as required.

Numbers may be in integer, floating-point, or scientific form; all numeric comparisons are done in double-precision, regardless of the attribute's data type.

Strings may be enclosed in single or double quotes. If a string is to contain a quote, you must enclose it in the other kind of quotes. If a string must contain both kinds of quotes, you may construct it from parts, using the SQL concatenate operator (||) to join the parts.

Dates may be time expressions or string-format dates. A string-format date is translated on the server, using standard PI date-time format (e.g. "1-dec-99" or "*-3h"). A time expression is translated on the client, using Microsoft date formats, and localized to the language defined on the client machine. In a time expression, you may translate a string to a date by using the CDate() function. For instance, CDate("3/1/98") is a time expression, and is translated on the client.

Note: at present, the only time expression supported is CDate(string). Time arithmetic, using time intervals, will be supported in a later release.

Remarks

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

Since the performance efficiency depends on implementation within the PI server, this method only works against a PI3 server.  Attempting GetPoints against a PI2 server will yield a result of pseSERVERNOTIMPL.

Currently GetPoints does not support queries that use the same attribute in multiple conditions (e.g. "span > 20 AND span < 50") and will return an error.  GetPointsSQL will process this correctly.

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

 

True asynchronous calling of this method is now invoked when a PIAsynchStatus object is passed as the asynchStatus argument.  This means the call will return quickly (generally with success unless local argument checks fail) but the returned PointList will be empty until the call completes. 

 

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 differ in some instances.

If no points are found by this method it returns an empty PointList collection.  The Server.GetPointsSQL returns an error of pseNoPointsFound in this case.

 

Trappable Errors

In addition to generic errors (such as Out of Memory), there are two potential sources of errors when calling GetPoints. When the call is made, the client-side PI-SDK code parses the expression in the whereClause argument using the PISDKParse.dll and changes the SQL-like syntax into the arguments necessary to place the RPC call to the server. If expression parsing fails, any of the errors exposed in the PISDKParse error enumeration, PISDKParse::ppeErrorConstants, could be returned. These errors are in the ranges
 

Error # Start

Error Constant

Error # End Error Constant

0x800404ed

PISDKParse::ppeNOSTRINGDELIM 0x800404ff PISDKParse::ppeTYPEMISMATCH

0x800405a1

PISDKParse::ppeNEEDEVALCONTEXT 0x800405a6 PISDKParse::ppeNOTARESOLVER
0x800405a9 PISDKParse::ppeNEGATIVEARG 0x800405aa PISDKParse::ppeARGERROR


The complete list of PISDKParse errors is viewable in a type library browser under the enumeration. If expression parsing succeeds, the call is made to the server which can also return errors. These can be the same errors you can get with any server call - disconnected, RPC off line, ... or they can be more specific to the server's evaluation of the GetPoints call as shown below.

Note this behavior is different than GetPointsSQL which just passes the expression directly to the server so client side parsing errors are never encountered.
 

Error

Description

pseSYNTAX

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

pseGETPOINTS

The call failed. This is usually a problem detected on the server. You will find more detailed information in Err.Description.

Enabling Operational Intelligence