Overview

This interface can be used by clients to browse the available properties (also referred to as attributes or parameters) associated with an ITEMID and to read the current values of these properties. In some respects the functionality is similar to that provided by BrowseServerAddressSpace, by EnumItemAttributes and by the SyncIO Read function. It differs from these interfaces in two important respects; (a) it is intended be much easier to use and (b) it is not optimized for efficient access to large amounts of data. Rather it is intended to allow an application to easily browse and read small amounts of additional information specific to a particular ITEMID.
The design of this interface is based upon the assumption is that many ITEMIDs are associated with other ITEMIDs which represent related values such as Engineering Units range or Description or perhaps Alarm Status. For example the system might be built internally of 'records' which represent complex objects (like PID Controllers, Timers, Counters, Analog Inputs, etc). These record items would have properties (like current value, setpoint, hi alarm limit, low alarm limit, description, etc).
As a result, this interface allows a flexible and convenient way to browse, locate and read this related information without imposing any particular design structure on the underlying system.
It also allows such information to be read without the need to create and manage OPCGroups.

In most cases, a system like the one above (i.e. one composed internally of 'records') would also expose a hierarchical address space to OPC in the form of A100 as a 'branch' and A100.CV, A100.SP, A100.OUT, A100.DESC as 'leafs'. In other words, the properties of an item which happens to be a record will generally map into lower level ITEMIDS. Another way to look at this is that things that have properties like A100 are going to be things that show up as 'Branch' Nodes in the OPC Browser and things that are properties are going to show up as 'Leaf' nodes in the OPC Browser.
Note that the A100 item could in fact be embedded in a higher level "Plant.Building.Line" hierarchy however for the moment we will ignore this as it is not relevant to this discussion.
So, the general intent of this interface is to provide a way, given an ITEMID of any one of a number of related its properties (like A100.CV or A100.DESC or even A100), to identify the other related properties.

Before we begin however it should be noted that the first 6 properties (the OPC Specific Property Set 1) are 'special cases' in that they represent data that would exist within the OPC Server if this item were added to an OPC Group and do not represent properties of the 'real' tag record in the underlying system. As a result, these particular property IDs will generally behave differently in the methods on this interface as described below.

An overview of the QueryAvailableProperties function:

The expected use of this is that you would pass it an ITEMID such as A100 which represents a 'record' object although you can also pass it a fully qualified ITEMID such as A100.CV or A100.SP. In any case you will get back a list of all of the other properties related to this item; typically, these are the other properties of the record object. Except for properties 1-6 it is not relevant whether the starting ITEMID reflects the record object or one of its property objects. Either way you will get back the same result - i.e. the list of properties in the containing 'record' object.
As noted above properties 1-6 have special behavior. They will refer to the OPC Item Data within the server for this particular item. If the passed ITEMID would not have made sense when passed to AddItem then the special 1-6 properties will not be available. For example if adding A100 (rather than A100.CV) would produce an error from AddItem then properties 1-6 are not available for A100.
Note that a server could chose to assign a 'default' value to an unqualified tag such that for example A100 becomes equivalent to A100.CV. Such a server might chose to return properties 1-6 when passed an unqualified ITEMID such as A100..

An overview of the GetItemProperties function:

The expected use is that you would pass the same ITEMID to this function as you passed to QueryAvailableProperties since, logically, the Property ID list returned by QueryAvailableProperties is valid only for exactly that ITEMID. Again note that except for properties 1-6 it does not matter whether the ITEMID is A100, A100.CV or A100.DESC, the properties will still return the appropriate properties of the container record.
Properties 1-6 have special behavior in that their behavior does vary based on the ITEMID. For example, property 2 (Current Value) would return the value of A100.CV if that were the passed ITEMID or the value or A100.SP if that were the passed ITEMID or might be invalid if the passed ITEMID were simply A100.

An overview of the LookupItemIDs function:

The expected use is that you would pass the same ITEMID to this function as you passed to QueryAvailableProperties since, logically, the Property ID list returned by QueryAvailableProperties is valid only for exactly that ITEMID. Again note that except in the case of properties 1-6 it does not matter whether the ITEMID is A100, A100.CV or A100.DESC, the returned ITEMIDs will still reflect the ITEMIDs of the appropriate properties of the container record.
Because properties 1-6 reflect data stored within the server and are not really related to properties of the item, there will never be any ITEMIDs returned for these properties and they should never be passed to this function. Doing so will generate an OPC_E_INVALID_PID error for the passed property.

Typical Use

Typical Client use of this interface would be to obtain an ITEMID either by obtaining a 'LEAF' via BrowseServerAddress or via direct input to an edit box by the user. That ITEMID would be passed to QueryAvailableProperties(). The resulting list would be presented to the user. He would select the properties he wanted to see from the list. The client would pass this set to GetItemProperties () to get a 'snapshot' of the data. Optionally the client could pass the set to LookupItemIDs and use the resulting set of ITEMIDs to create an OPCGroup to be used to repeatedly obtain the data.

Examples

This is just an example. It is not intended to impose any particular structure on any server implementation.
A typical OPC ITEMID might be FIC101.CV. This could represent the current value of a tag or function block called FIC101. This function block commonly has other properties associated with it such as Engineering Units, a loop description, etc. This function block could also have alarm limits and status, a setpoint, tuning parameters as well as documentation cross references, maintenance information, help screens, default operator displays and a limitless set of other properties. All of these properties are associated with each other by virtue of their common association with FIC101. This interface provides a convenient shortcut to accessing those related properties.
An MMI package for example might use this interface to allow the user to indicate that the Hi and Lo Engineering Units values should be used to scale a bargraph representation of the value.

Note that because these associations can be 'many to many' and can also be circular, a client application would not want to automatically investigate them all.
It is NOT intended that property browsing be hierarchical.
Another similar example could be a function block such as a TIMER or COUNTER in a high end PLC where various Properties are associated with each object.

How 'Properties' relate to ItemIDs.

In most cases it is expected (but not required) that such properties can also be accessed via ItemIDs such as FIC101.HI_EU, FIC101.DESC, FIC101.ALMSTAT, etc. These related ITEMIDs could be used in an OPCGroup. This interface provides a way to easily determine if such an alternate method of access can be used for the properties if large amounts of information need to be obtained more efficiently.

Property IDs

The server will need to assign DWORD ID codes to the properties. This allows the client to more easily manage the list of properties it wants to access. These properties are divided (somewhat arbitrarily) into 3 'sets'. The OPC 'Fixed' set contains properties that are identical to some of those returned by OPCITEMATTRIBUTES, the 'recommended' set is expected to be common to many servers, the 'vendor specific' set contains additional properties as appropriate. The assigned IDs for the first two sets are fixed. The vendor specific properties should use ID codes above 5000.

The OPC Property Sets

This is a set of property IDs that are common to many servers. Servers which provide the coresponding properties must do so using the ID codes from this list. Symbolic equates for these properties are provided in the OPCProps.H file. (See Appendix to this document).

ID Set 1 - OPC Specific Properties - This includes information directly related to the OPC Server for the system.

ID	DATATYPE of returned VARIANT	STANDARD DESCRIPTION
1	VT_I2	Item Canonical DataType (VARTYPE stored in an I2)
2	<varies>	"Item Value" (VARIANT) Note the type of value returned is as indicated by the "Item Canonical DataType above and depends on the item. This will behave like a read from DEVICE.
3	VT_I2	Item Quality (OPCQUALITY stored in an I2). This will behave like a read from DEVICE.
4	VT_DATE	Item Timestamp (will be converted from FILETIME). This will behave like a read from DEVICE.
5	VT_I4	Item Access Rights (OPCACCESSRIGHTS stored in an I4)
6	VT_R4	Server Scan Rate In Milliseconds. This represents the fastest rate at which the server could obtain data from the underlying data source. The nature of this source is not defined but is typically a DCS system, a SCADA system, a PLC via a COMM port or network, a Device Network, etc. This value generally represents the 'best case' fastest RequestedUpdateRate which could be used if this item were added to an OPCGroup. The accuracy of this value (the ability of the server to attain 'best case' performance) can be greatly affected by system load and other factors.
7-99		Reserved for future OPC use

 

ID Set 2 - Recommended Properties - This is additional information which is commonly associated with ITEMs. This includes additional ranges of values that are reserved for use by other future OPC specifications. For information about the newest field ID assignments, consult the other OPC Foundation specifications.
The position of the OPC Foundation is that if you have properties associated with an item which seem to fit the descriptions below then it is recommended that you use these specific descriptions and ID codes to expose those properties via this interface.
A server can provide any subset of these values (or none of them).

ID	DATATYPE of returned VARIANT	STANDARD DESCIPTION
		Properties related to the Item Value.
100	VT_BSTR	"EU Units"e.g. "DEGC" or "GALLONS"
101	VT_BSTR	"Item Description" e.g. "Evaporator 6 Coolant Temp"
102	VT_R8	"High EU" Present only for 'analog' data. This represents the highest value likely to be obtained in normal operation and is intended for such use as automatically scaling a bargraph display. e.g. 1400.0
103	VT_R8	"Low EU" Present only for 'analog' data. This represents the lowest value likely to be obtained in normal operation and is intended for such use as automatically scaling a bargraph display. e.g. -200.0
104	VT_R8	"High Instrument Range" Present only for 'analog' data. This represents the highest value that can be returned by the instrument. e.g. 9999.9
105	VT_R8	"Low Instrument Range" Present only for 'analog' data. This represents the lowest value that can be returned by the instrument. e.g. -9999.9
106	VT_BSTR	"Contact Close Label" Present only for 'discrete' data. This represents a string to be associated with this contact when it is in the closed (non-zero) state e.g. "RUN", "CLOSE", "ENABLE", "SAFE" ,etc.
107	VT_BSTR	"Contact Open Label" Present only for 'discrete' data. This represents a string to be associated with this contact when it is in the open (zero) state e.g. "STOP", "OPEN", "DISABLE", "UNSAFE" ,etc.
108	VT_I4	"Item Timezone" The difference in minutes between the items UTC Timestamp and the local time in which the item value was obtained. See the OPCGroup TimeBias property. Also see the WIN32 TIME_ZONE_INFORMATION structure.
109-199		Reserved for future OPC use. Additional IDs may be added without revising the interface ID.
		Properties related operator displays
200	VT_BSTR	"Default Display" The name of an operator display associated with this ItemID
201	VT_I4	"Current Foreground Color" The COLORREF in which the item should be displayed
202	VT_I4	"Current Background Color" The COLORREF in which the item should be displayed
203	VT_BOOL	"Current Blink" Should a display of this item blink?
204	VT_BSTR	"BMP File" e.g. C:\MEDIA\FIC101.BMP
205	VT_BSTR	"Sound File" e.g. C:\MEDIA\FIC101.WAV, or .MID
206	VT_BSTR	"HTML File" e.g. http:\\mypage.com/FIC101.HML
207	VT_BSTR	"AVI File" e.g. C:\MEDIA\FIC101.AVI
207-299		Reserved for future OPC use. Additional IDs may be added without revising the interface ID.
		Properties Related to Alarm and Condition Values (preliminary)... IDs 300 to 399 are reserved for use by OPC Alarms and Events. See the OPC Alarm and Events specification for additional information.
300	VT_BSTR	"Condition Status" The current alarm or condition status associated with the Item e.g. "NORMAL", "ACTIVE", "HI ALARM", etc
301	VT_BSTR	"Alarm Quick Help" A short text string providing a brief set of instructions for the operator to follow when this alarm occurs.
302	VT_BSTR |VT_ARRAY	"Alarm Area List" An array of stings indicating the plant or alarm areas which include this ItemID.
303	VT_BSTR	"Primary Alarm Area" A string indicating the primary plant or alarm area including this ItemID
304	VT_BSTR	"Condition Logic" An arbitrary string describing the test being performed. e.g. "High Limit Exceeded" or "TAG.PV >= TAG.HILIM"
305	VT_BSTR	"Limit Exceeded" For multistate alarms, the condition exceeded e.g. HIHI, HI, LO, LOLO
306	VT_R8	"Deadband"
307	VT_R8	"HiHi Limit"
308	VT_R8	"Hi Limit"
309	VT_R8	"Lo Limit"
310	VT_R8	"LoLo Limit"
311	VT_R8	"Rate of Change Limit"
312	VT_R8	"Deviation Limit"
313-399		Reserved for future OPC Alarms and Events use. Additional IDs may be added without revising the interface ID.
400-4999		Reserved for future OPC use. Additional IDs may be added without revising the interface ID.

NOTE the OPC Foundation reserves the right to expand this list from time to time. Clients should be prepared to deal with this.

 

ID Set 3 - Vendor specific Properties

5000...	VT_xxx	Vendor Specific Properties. ID codes for these properties must have values of 5000 or greater. They do not need to be sequential. The datatypes must be compatable with the VARIANT.

The client should take care dealing with these vendor specific IDs - i.e. not make assumptions about them. Different vendors may not provide the same information for IDs of 5000 and above.
Note again that this interface is NOT intended to allow efficient access to large amounts of data.
The LocaleID of the server (as set by IOPCCommon::SetLocaleID) will be used by the server to localize any data items returned as strings. The item descriptions are not localized.