Item Property (StateSets collection)



This default property of the StateSets collection, when given a numeric or string index returns the corresponding StateSet collection.


object[.Item]( index)

The Item property syntax has these parts:




An object expression that evaluates to a StateSets collection.


An expression that specifies a member of the collection, as described in Settings.



The settings for index are:


Description (collections implementing setting)


Specifies a numeric identifier for the StateSet as returned by StateSet.StateSetID


Specifies a StateSet by name. 



The Item property is the default property of the collection, so these expressions have the same meaning:



PI on OpenVMS (PI2) servers physically only support a single state set called System. When used to provide states to digital tags, a subset of the System StateSet is associated with the tag. The tag is given a starting code and a number of codes as attributes to designate which states are to be used. To allow the PI-SDK to expose a digital point's StateSet under PI2 as a small collection of states rather than the entire system set, a convention is adopted where the PI-SDK refers to these state sets as System:m:n where m is the starting state in the System table and n is one less than the number of states for that logical set (the states are addressed in StateSet.Item with indexes 0 to n). For example a digital point on a PI2 system, when asked for its DigitalSet attribute returns the string "System:20:4". This means the tag will use system states 20 through 24 (5 states).


As these pseudo state sets do not actually exist on the server, when you query a PI2 server for its StateSet collections (For each StateSet in StateSets) you will only see one set, System. However if you ask the StateSets collection for the StateSet called System:20:4, (StateSets.Item("System:20:4")), you will be returned a StateSet object that contains the 5 states starting at offset 20 in the System table. This allows a program to easily display the allowable digital states for a particular digital tag in a uniform way regardless of the server type.


Trappable Errors

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




StateSet names cannot be empty or blank filled strings.


The desired StateSet was not found on this Server.


Unable to create a StateSet object to return.


The passed index was not numeric or a string.

Enabling Operational Intelligence