Opc interface to the pi system

Plug-in Post-processing DLLs

The PI OPC Interface has the ability to use plug-in DLLs. These are libraries of routines that execute application-specific data processing before the data is sent to the PI Server or OPC Server. The DLLs and their accompanying files and documentation are on the interface CD and are installed into the Plug-ins sub-directory under the interface directory. Each plug-in package contains the documentation for how to use that specific package.

Polling, Advising and Event Tags

The PI OPC Interface has three methods of getting data: Advising, Polling, and Event reads (also known as triggered reads). For Advise tags (referred to as ReadOnChange in the OPC Standard), the OPC Server sends data whenever a new value is read into the server’s cache. For Polled points, the interface sends an Asynchronous Refresh call (see Data Access Custom Interface Standard v2.05a from OPC Foundation for more details) for the Group. For Event reads, the PI Server informs the interface when the trigger point has a new event (not necessarily a change in value) and the interface sends an Asynchronous Read call for the event tags attached to that trigger. All three kinds of points are read asynchronously by the interface and the same data routines process all updates.

Note: It is strongly recommended that Advise tags and Polled tags not be mixed in the same Group (i.e. scan class).

Polled Tags

Polled tags are grouped by scan class; all tags in a scan class will be in the same Group. Since reads are done on a Group level, it is best not to have too many tags in one Group. Multiple scan classes with the same scan rate can be used; use the offset parameter to ensure that the load on the interface is smooth, rather than having the interface attempt to read all the tags at the same time. Note that the offset parameter may have no effect on the load on the OPC server; for more information, see the section on the /f parameter in Command-line Parameters.

Advise Tags

Advise tags will be grouped automatically by the interface if they are in scan class 1. A scan class is specified for Advise tags, the same as for Polled tags, but for tags in scan class 1 the interface will automatically limit the number of tags in the Advise Group to 800 by default. This means that up to 800 tags with the same deadband will be put into one Group. If there are more than 800 tags with the same deadband in scan class 1, the interface will create as many Groups as are needed. To change this limit to a different number, use the /AM parameter.

Event Tags

Event tags (triggered inputs) are usually used to read a set of data points after a particular event has occurred. The PI tag that triggers the read is named in the ExDesc field. When a new event for a trigger tag is sent to the PI snapshot, the PI system informs the interface of this and the interface then goes out to read the values for all the associated event tags from the OPC Server. For v1.0a servers, an Asynchronous read is sent to the server’s cache. For v2.0 servers, the Asynchronous read from cache is not available and the interface must do an Asynchronous read from the device. Doing very many of these device reads could impact the performance of the OPC Server. For any Asynchronous read, the server is required to return all of the values together, so it is possible that there could be a delay in getting the new values back to the PI Server, if the OPC Server has a delay in reading one or more of the values. Grouping those tags by the device where the data resides might be important for performance, in those cases.

For event tags, the scan class must be set to zero, but a Group number will be entered in UserInt2. The interface will create a Group for each unique UserInt2, and when an event happens, a read will be performed for each Group that contains one or more of the event tags that depend on the triggering event. The UserInt2 number creates a logical grouping of event tags, but the only effect of that grouping is in how the interface itself handles the data processing, and how it asks the server for the information. Thus, a large number of event tags that share the same trigger tag can be split up into logical groups, which will each be read independently of the other groups, so that delays in reading from a given device need not impact the rest of the data acquisition.

Data Types

By default, the interface will request the following OPC data types:

PI PointType	OPC Data Type
Digital	2-byte Integer (VT_I2)
Int16	2-byte Integer (VT_I2)
Int32	4-byte Integer (VT_I4)
Float32	4-byte Float (VT_R4)
Float64	8-byte Float (VT_R8)
String	String (VT_BSTR)

Below there are some ways to change those defaults.

The user is not restricted to specific point types, but it is not possible to get valid data if a specified translation is not reasonable. That means that if a value is read as a string and is to be to put into an Int32 PI tag, the string has to have a number in it. If a value is read as VT_R8 (a 64-bit floating point value), and it is to be put into an Int16 tag, the value read has to fit into an Int16 tag, even though a VT_R8 can hold a much larger number than will fit into an Int16.

Reading Digital, Integer, and Real Tags as Strings

Tags that are defined as Digital tags in PI are generally read and written as integer values and those values correspond to specific strings in the Digital State table specified in the tag's Digital Set property. Since some devices read and write the string rather than the integer value, Digital tags can be read and written as though they were String tags, by setting Location2=1. Make sure that the strings used by the OPC Server are exactly identical to the strings in the Digital Set, including punctuation, and spacing.

Other OPC Servers cannot serve certain numbers as numeric and they can only provide the character strings. For these servers, set Location2=1 for Int16, Int32, Float32, and Float64 tags, and the interface will request the data as a string (BSTR) and try to read the resulting data as a number.

Reading Tags as Booleans

Some servers appear to have been written to not only send Boolean values as 0 and -1 when read as VT_BOOL (as specified by Microsoft's definition of a VARIANT of type VT_BOOL), but also to send the same values when read as integers. This creates a problem when reading that data into a PI Digital tag, since "-1" is not actually what should be stored. While most servers appear to handle this properly, to handle the data from ill-behaved servers, the interface will take the absolute value of any integer or real values read for digital tags. Since digital tag values are actually offsets into the digital set for the tag, and a negative offset has no functional meaning, this should not cause problems for properly written servers.

The interface may also request the item as a Boolean (VT_BOOL). This will only work for items which truly only have two possible states, as any nonzero value will be interpreted as a 1. To have tags read and written as though they were Booleans, set Location2=2.

Reading Tags as 4-byte Integers

If the OPC Server does not send data as a 2-byte integer (VT_I2), set Location2=3 to have the interface request the data as a 4-byte integer (VT_I4). Note that this option uses more resource, so use it only if necessary.

Reading Tags as Float64 Values

Likewise, if your OPC Server will only give a particular value as an 8-byte floating-point number (VT_R8), set Location2=5 to have the interface request VT_R8 even though it will be storing it to a 4-byte floating-point tag. There may be some loss of precision, and if the number is too large to fit in the tag, a status of BAD INPUT will be stored for the tag.

Converting Timestamps into Seconds

Setting Location2=6 tells the interface that the OPC Item is a string (VT_BSTR) that will have a timestamp string value in it, such as 2000/11/02 15:34:29. The format of the strings must be supplied in the command file with the /TF parameter. See the section below on Timestamp Strings for how to create that format.

If the PI tag is an integer, the interface will attempt to translate the timestamp into whole seconds and store that in the PI Archive. (Remember that Int16 tags can only hold numbers up to 32767, so for time spans longer than 9 hours Int32 tags will be needed.) If the PI tag is a Float tag, the timestamp will be translated into seconds and stored as a floating-point number. The interface will not perform any adjustments on the timestamps received, regardless of the time zone settings or /TS parameter on the command line. However, if the tag is configured to use scaling or transformation that operation will happen after the string has been translated into seconds, which allows a wide range of values to be handled.

Reading Timestamps as VT_DATE Data Types

The OPC Standard allows the use of VT_DATE as a data type. This is an internal representation of a timestamp. Setting Location2=7 tells the interface to use the VT_DATE data type for reading the value from the OPC Server, or for writing the value, if it is an output tag. The interface will translate between VT_DATE and integer, float, or string tags. It will not perform any adjustments on the timestamps received, regardless of the time zone settings or /TS parameter on the command line. For string tags, the timestamp format specified with the /TF parameter will be used. See the following section for how to create that format.

Timestamp Strings

Only one format string may be specified for an instance of the interface, so if more than one format of timestamp needs to be processed then more than one copy of the interface will need to be used. 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 parameter are:

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 day

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

The tokens can be put 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 are some common format strings and example timestamps:

"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"

Not Specifying a Data Type

To accommodate certain servers, which do not allow clients to specify a data type even when the client asks for the very one that the server uses, set Location2=8. Be aware that using this can cause other problems; while the interface makes every attempt to translate the value received from the OPC Server into the proper type for the PI tag, it may not be possible. Where possible, always specify the data type that matches the PI tag.