Object names that are plural indicate collections (PIPoints, Servers, PointAttributes). Each collection provides a standard set of methods and properties that can be used to find elements in the collection, and iterate through the collection. In particular, the Item property of the collection is passed a key to a contained object and returns a reference to the object. To retrieve a reference to a member of the Servers collection in Visual Basic you would use:
dim mysrv as Server
set mysrv = PISDK.Servers.Item("MyServer")
This returns a reference to a server object for the server named "MyServer."
In the PI-SDK library, the Item property is always defined as the default property of a collection so in Visual Basic you can drop the word Item.
set mysrv = PISDK.Servers("MyServer")
A COM library, like the PI-SDK, can define a single global object (app object) that in Visual Basic is created automatically. This object has global scope, so its name can be dropped when accessing its members. For the PI-SDK library, the global object is the top-level PISDK object. This means the code to access the server can be further reduced to:
If you are using other libraries in your application that also define a global named Servers you can avoid the ambiguity by using the full name PISDK.Servers.
Another useful method provided by collections allows iterating through the members of a collection. In Visual Basic, using the For Each statement you can easily traverse the members of a collection. For example:
Private Sub AddStatesToListBox(ssSateSet as StateSet)
Dim dsState as DigitalState
For Each dsState in ssStateSet
In C++ this functionality is accessed through the _NewEnum property of the collection, which is hidden in Visual Basic.
Referencing an object that is returned as a property of another object is simply a matter of using the dot operator on the object. Continuing from the above example, to access the PIPoints collection in Visual Basic you use:
dim myPIPoints as PIPoints
set myPIPoints = mysrv.PIPoints
The step-wise access shown above can be put together in a single line burrowing down the hierarchy, saving code, and making the access more readable as follows:
dim myPointAttributes as PointAttributes
set myPointAttributes = Servers("MyServer").PIPoints("sinusoid").PointAttributes
In this example, we have retrieved a reference to the PointAttributes collection for the point Sinusoid from the server MyServer in a single line.
While this coding style is more readable, it is not recommended for non-trivial applications. As the complex expression is evaluated, temporary objects are created and destroyed (often redundantly) which can create performance problems as well as scoping issues. Compact syntax like this is hard to debug and provides no added performance benefit. This recommendation applies not only to Visual Basic but allso C++ when using the #import wrappers and Microsoft .Net languages.
When accessing objects using languages other than Visual Basic (VBScript, VB.Net, C#, C++), the global application object and default properties and methods are typically not supported. The PISDK object must be created and all properties and methods referenced explicitly.
For example in Visual C++ you must first create the PISDK object using CoCreateInstance or a smart pointer constructor and use the returned object to access the Servers collection. When retrieving members of the collection you must call the Item property explicitly, as default properties and methods are not supported. See the C++ tutorial for examples.