ExDesc (extended descriptor)
- Last UpdatedNov 21, 2022
- 5 minute read
- PI System
- PI Interface for OPC HDA 1.6.2
- Interfaces
You can use the extended descriptor attribute for several purposes, such as indicating a point is a performance point, associating a trigger point with an input point, and specifying different ItemIDs for the timestamp and the point value. When using the field for multiple purposes, insert a comma between each definition.
Length
Depending on the version of the PI API and the Data Archive, this interface supports an ExDesc attribute whose length is at most 80 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and Data Archive versions.
|
PI API |
Data Archive |
Maximum Length |
|---|---|---|
|
1.6.0.2 or later |
3.4.370.x or later |
1023 |
|
1.6.0.2 or later |
Earlier than 3.4.370.x |
80 |
|
Earlier than 1.6.0.2 |
3.4.370.x or later |
80 |
|
Earlier than 1.6.0.2 |
Earlier than 3.4.370.x |
80 |
Performance points
For UniInt-based interfaces, the extended descriptor is checked for the string PERFORMANCE_POINT. If this character string is found, UniInt treats this point as a performance point.
Trigger based input points
For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by event or trig and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.
Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:
Event=‘trigger_tag_name’ event_condition
The trigger tag name must be in single quotes. For example,
Event=‘Sinusoid’ Anychange
will trigger on any event to the PI point sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.
The keywords in the following table can be used to specify trigger conditions.
|
Condition |
Description |
|---|---|
|
Anychange |
Trigger on any change as long as the value of the current event is different than the value of the previous event. System digital states also trigger events. For example, an event will be triggered on a value change from 0 to Bad Input, and an event will be triggered on a value change from Bad Input to 0. |
|
Increment |
Trigger on any increase in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. |
|
Decrement |
Trigger on any decrease in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. |
|
Nonzero |
Trigger on any non-zero value. Events are not triggered when a system digital state is written to the trigger point. For example, an event is triggered on a value change from Pt Created to 1, but an event is not triggered on a value change from 1 to Bad Input. |
Sending time stamp and output value to different ItemIDs
Specify the timestamp ItemID in ExDesc when you want to write the output value to one ItemID and the corresponding timestamp to a different ItemID. In this case, the ItemID specified in the InstrumentTag point attribute or in the ExDesc field as instr=ItemId will contain the value, and the ItemID specified in the ExDesc field will contain the timestamp that goes with that value. Again, the ItemID string must match exactly the ItemID on the OPC HDA Server.
There are two formats, depending on the data type of the ItemID that receives the timestamp:
|
Format |
Description |
|---|---|
|
Tim=ItemID |
The interface writes the time stamp as a string (VT_BSTR) formatted according to the /TF setting in the startup file. In this format, the time stamp matches the Data Archive times tamp, and is not adjusted for differences in time zone or daylight saving time settings. |
|
Dat=ItemID |
The interface writes the time stamp as a VT_DATE. In this format, the time stamp is in universal (UTC) format, and has no dependency on the time zone or daylight saving time setting. |
The time stamp written to the OPC HDA Server is the same time stamp seen on the PI machine when looking at the archive timestamp.
Time stamp strings
Time stamp format is specified using the command line parameter /TF. You can only specify one format string for an instance of the interface. If you must process more than one format of times tamp, then you must use more than instance of the interface. The interface will make a copy of the format string, and will then replace the tokens with the actual values, to create a string. To read a string, it will look for numbers that are in the same position as the tokens, and use those numbers as values. The tokens that the interface recognizes in the /TF command line parameter are:
|
Token |
Description |
|---|---|
|
cc |
2-digit century |
|
yy |
2-digit year |
|
mn |
2-digit month |
|
mon |
month as a 3-character abbreviation: one of the following: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec |
|
dd |
2-digit |
|
hh |
2-digit hour from 0 to 23 |
|
hr |
2-digit hour from 0 to 12 |
|
mm |
2-digit minute |
|
ss |
2-digit second |
|
0 |
3-digit milliseconds |
|
XM |
either AM or PM |
You can put the tokens together in any combination, with anything or nothing between them. What matters to the interface is where in the string the tokens are found. It reads from left to right, looking for a recognizable token. The following table shows some common format strings and example time stamps.
|
Format string |
Example time stamp |
|---|---|
|
ccyy/mn/dd hh:mm:ss.000 |
1998/11/29 15:32:19.391 |
|
dd mon, ccyy hr:mm:ss XM |
29 Nov, 1998 03:32:19 PM |
|
mn-dd-ccyy hh:mm:ss |
11-29-1998 15:32:19 |
|
hh:mm:ss.000 |
15:32:19.482 |
Dzero for scaled points
When the device returns values that must be scaled to fit the range of values the point stores (such as scaling from device voltage to temperature in degrees Celsius), store the device Zero (Dzero) in ExDesc. (The Convers point attribute is used to specify the device Span.) The format is for the device Zero is:
Dzero=nnnnn.nnn