Time Array Plug-In for OPC Data
General
To enhance the functionality of the OPC interface, specific additional tasks can be performed by an additional DLL.
This paper contains information about OPCPluginTimeArray.DLL. This DLL allows the transposition of an array of values into a series of successive values for a single tag. When a tag is configured as a Time Array tag, the interface will ask for the tag as an array of values; for instance, if the tag is a Float32 PI tag, the interface will ask the OPC server for an array of VT_R4 values. The interface does not specify how many values should be in the array, and it will pass the data on to the dll directly.
The TimeArray dll will accept the array and, if the quality of the data is good, it will store the array of values in PI as successive data values, incrementing the timestamp given with the array by a configured interval for each value, such that the first value has timestamp T, the second value has timestamp T + (1 * Interval), the third value has timestamp T + (2 * Interval), etc., where T is the timestamp that was sent with the array. All the values will have the same quality, since the quality is sent from the OPC server as the quality for the entire array. If the quality is not GOOD (see the OPC interface manual for more on quality), the dll will pass the array back to the interface, which will process it normally, and store one entry in PI with the appropriate digital state corresponding to the quality.
This paper extends the information contained in the manual "OPC Interface to the PI System" (opcint.doc) Please read that document for more on configuring PI tags and the OPC interface.
Point configuration
Two factors define a tag which will use the TimeArray plugin.
Location2
In general use of the OPC interface, Location2 specifies what special handling should be done with the data, such as asking for a different datatype than would normally be requested for a given tag type. For the TimeArray plugin, you should add 1024 to whatever value Location2 would already have. This allows most standard functionality of the interface to be maintained. Thus if your tag is a Float32, but your OPC server can only provide the data if you ask for it as a VT_R8 (64 bit floating point number), you would ordinarily set Location2 = 5. To do the same thing for a tag that will receive an array of time-series data, you would set Location2 = 5 + 1024 = 1029.
ExDesc
The interval between values, when the values are written to PI, must also be specified in the tag. We use ExDesc for this, and use a keyword of ARRAYINT. So, if the array of data coming from the OPC server contains values that should be stored 100 milliseconds apart, your tag should have
ARRAYINT=100
as part of the ExDesc. You can also have any of the other values you would otherwise have in the ExDesc, separating them with commas as usual.
Limits
· OPCINT Version 2.1.32 or greater is required.
· The TimeArray dll will not process string tags. All numeric or digital tags are allowed. String values from the OPC server will be accepted.
· The TimeArray dll will work with both v1.0a and v2.0 OPC servers.
Installation
The file OPCPluginTimeArray.dll has to be copied to the same machine where the OPC interface resides. The complete path and filename has to be entered in the interface startup bat file.
Example: /DLL=c:\pipc\interfaces\opcint\plug-ins\OPCPluginTimeArray.dll
If the path name contains spaces, the whole startup parameter has to be surrounded by double quotes.
Errors and logging
Error messages and informational output are written to PIPC.LOG. If the interface is run as a console application, output is sent to the application window, too.
Error messages
Messages from the dll with appear in the pipc.log file (and in the output window, if the interface is run interactively), with the prefix "Timearray: ". For all of the examples below, the numbers and tagnames used will vary. So if you're looking to see what an error message means, look for a message that matches what your logfile shows, but ignore difference in the tagnames or numbers given.
You will always see the version printed:
01-Nov-01 11:58:37
Timearray: Version 1.1.0
If you have defined a debug tag, you'll see that confirmed
01-Nov-01 11:58:37
Timearray: Debug tag TIMEARRAYDEBUG found
or if the tag was not found:
01-Nov-01 11:58:37
Timearray: Unable to find debug tag TIMEARRAYDEBUG, no debug tag set
If the value of the debug tag is greater than 0, or if you have specified a debug flag on the command line that is greater than 0, you'll see another message:
Timearray: DebugFlag 4
When data arrives from the OPC interface, the dll may print error messages if it is unable to process the data :
TimeArray: Invalid point type 12
Timearray: Invalid array type 12
Timearray: Array has dimension > 1, skipping ArrayTag
TimeArray: Array not one-dimensional
Any of those messages indicates a serious problem with the data received from the OPC server, and you'll probably need to talk to your server vendor. Call or email our Tech Support staff, so we can check the pipc.log file to make sure there's no indication of another problem.
If the timestamp we get from the OPC server doesn't make sense to us, you'll see :
TimeArray: Invalid timestamp for tag: ArrayTag, 100479844 and 0.27
The two numbers are the whole seconds of the PI timestamp, and the fractional part of a second.
TimeArray: ArrayTag : Can't translate date to seconds
This one indicates that we got a VT_DATE value from the OPC server, and we couldn't translate it into a number of seconds (this is one of the Location2 options for opcint). This would indicate a serious problem with the data.
TimeArray: Unrecoverable error, data type unknown 37
Okay, we got some data from the server, but we have no idea what it is or how to read it. We're completely baffled, and we're giving up on it.
For all of these "bad data" messages, what will happen is that that particular value will be dropped (or the entire array, if the timestamp itself is bad), but the interface and the dll will continue to collect data. So the effect is that we'll drop what we can't process, after logging the error message, and go on to take care of the data that we can process.
Problem in TimeArray.dll, HRESULT = 0x80040335
This error says that we got something from the server, but we can't read any of it. This is a bad error, and it probably means that there's really serious problem with either your server or the dll or both. Call us.
Timearray: Putsnap error state changed, was %d, now %d, tag: %s, pt: %d, index %d, cstat: %d
TimeArray: Putsnap no longer in error %d,tag: %s, pt: %d, cstat: %d
TimeArray: Putsnap system error %d
These errors indicate a problem in communicating with PI (system error), or an error in writing to PI (error state changed), or recovery from an error writing to PI (no longer in error). These are just like the same error messages seen with the OPC interface itself. Use pidiag.exe to see what an error number means when there's an error writing to PI (pidiag.exe -e -109, for example, to see what a -109 is). Remember that once a tag goes into error, you won't see any more messages until it goes out of error, or gets a different error, so once you get an error, you won't have data going to PI for that tag until you see another message that the error has cleared.
Debugging
The TimeArray dll also has the ability to use a debug tag, and to have the value of the debug flag set on the command line. To set the value of the debug flag on the command line, you would use
/dlldb=#
where # is the number corresponding to the debug messages you want to have printed (see the table below).
The preferred way to set the debug flag is to define an Int32 tag in PI, configure it as a simple input tag with Location2 = 1024 (so the dll will recognize it), and put any dummy value into the instrumenttag. Make sure that the Location1 property of the tag has the correct value for this interface. Then give the tagname in the command line :
/dlldebugtag=tagname
Before starting the interface, you should set the value of the debug tag. Then when you want to turn debugging on or off, or to change the level of debugging, you will need to first change the value of the tag, and then edit the tag. You must edit the tag in order to have the dll pick up the new value, because the dll doesn't process output values, so to have the dll notified that there is a value change, we rely on PI to notify us of the tag edit. When the dll gets the tag, it will go and read the value from the PI snapshot, and then it will refuse the tag, causing the interface to reject it. Thus, the debug tag has no impact on the OPC server.
In the pipc.log file, you will see the following messages to indicate that the debug tag has been found and read:
01-Nov-01 11:58:37
Timearray: Debug tag TIMEARRAYDEBUG found
01-Nov-01 11:58:41
OPCpi> 2> Removed Tag TimeArrayDebug
01-Nov-01 11:58:41
OPCpi> 2> Developer load structure failure, TimeArrayDebug, 1177
Every time you edit the debug tag (which you will do every time you need to change the value), you will see those last two messages in the pipc.log file.
Debugging Messages
The debug flag is a bitmask, so you can turn on more than one set of messages by adding the set numbers together and setting the debug flag to that value. So, to turn on messages for the array timestamps and for values that we would process but none passed the exception parameters, you would set debugging to 1 + 8 = 9 . The message sets are:
1
Messages showing that we got data, but none of it passed the exception parameters, so we didn't send anything to PI for this tag.
Timearray: No data to send, skipping ArrayTag
2
Messages showing values that we're not going to process. The OPC interface passes all data to us (after applying some minimal checks), we ignore values for tags that aren't ours and then validate the data. If the tag has been deleted, the interface will have set the dev struct to zero, so we'll skip that one. If the tag has been marked for deletion, we will just dump data, so we'll skip those too. And finally, if the quality sent with the array isn't GOOD, we'll skip the tag and let the OPC interface store one status value to the tag, showing the quality that the OPC server sent.
Timearray: No dev struct, skipping
Timearray: Tag waiting for deletion, skipping ArrayTag
Timearray: Bad quality, skipping ArrayTag
4
Messages showing values for tags we're not supposed to process,
Timearray: Not an array tag, skipping FloatTag
Timearray: Not our array tag, skipping OtherArray
8
Print the timestamp sent with the array. This is to verify what the OPC server is sending us.
Timearray: Tag ArrayTag time 1004551257.2541676
16
Print the index and timestamp for each value sent to PI. This can be a lot of output, so use it carefully.
Timearray: Tag ArrayTag index 67 time 0:57.254180908203125