OPC Interface to the PI System
OPC
Interface to the PI System
version 2.1.45.0
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P O Box 8256 |
| |San Leandro, CA 94577-0427 |Symonds Street |
| |USA |Auckland 1035 New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |Singapore, 189721 |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation. OPC and OPC Foundation are trademarks of the OPC Foundation.
PI_opcint.doc
( 2000 - 2003 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Configurations 2
Supported Features 2
Requirements - PI2 and PI3 Servers 4
Upgrading from Version 1.x or 2.0 to 2.1 or Higher 4
Overview 7
Notes on OPC and COM 7
Timestamps 8
Writing Timestamps to the Device 9
Connections - Creating, Losing, and Recreating 9
The OPCEnum Utility 9
Plug-In Post-processing DLLs 10
Polling, Advising and Event Tags 10
Datatypes 11
Transformations and Scaling 14
Quality Information 17
Questionable Qualities -- Store the Status or the Value? 17
Storing Quality Information Directly 18
PI Point Configuration 21
Point Attributes 21
PointType 21
PointSource 21
InstrumentTag 21
ExDesc 22
SourceTag 23
Scan 23
Totalcode 23
SquareRoot 23
Convers 24
Location1 24
Location2 24
Location3 26
Location4 26
Location5 27
Userint1 27
Userint2 27
Scan 27
Shutdown 28
Exception processing 28
Software Configuration 31
Point Source -- PI 2 31
Point Source -- PI 3 31
Digital States -- PI 2 31
Digital States -- PI 3 31
IO Rate Points 31
Step 1 – PI Point configuration on the PI Server 32
Step 2 – Configuration on the Interface Node 32
Command-line Parameters 33
Starting and Finding Servers 33
Interface-level Failover 33
Server-Level Failover 34
Post-processing ("plug-in" dlls) 34
Controlling Data Collection 34
Handling Idiosyncracies for Various OPC Servers 36
Debugging 37
Complete Alphabetical List of Parameters 37
Interface Operation 49
No More Password File 49
Installing the Interface as a Service 50
Installing Debug Symbols 50
Startup/Shutdown 51
Editing Tags While the Interface is Running 51
Logging Messages 51
Connecting to OPC Server 52
Using PI-API Buffering 52
Configuring DCOM: The Basic Steps 52
Configuring Tags 55
Scan Classes 55
Configuring Polled Tags 55
Configuring Advise Tags 55
Configuring Event Tags 56
Configuring Array Tags 57
Configuring Arrays as Event Tags 58
Reading Basic Quality as a Digital Tag 58
OPC Server Issues 61
Browsing 61
Timestamps 61
Disconnecting 61
False Values 61
Access Path 62
Interface Installation 63
Naming Conventions and Requirements 63
Interface Directories 63
The PIHOME Directory Tree 63
Interface Installation Directory 63
Plug-Ins Directory 63
OPCEnum Directory 64
Tools Directory 64
Security 64
Interface Checklist 64
Upgrading an Installation 65
Common Problems 66
Debugging 67
Using the opcresponse.log, opcscan.log, and opcrefresh.log Files 69
Error and Informational Messages 71
PIOPCTool 79
OPC Interface Failover 81
DCOM Configuration Details 83
Appendix A: Notes on Some OPC Servers 93
Honeywell APP Node 93
DeltaV System 94
All Servers Built on the FactorySoft Toolkit 94
Revision History 95
Introduction
OPC (OLE for Process Control) is a standard established by the OPC Foundation task force to allow applications to access process data from the plant floor in a consistent manner. Vendors of process devices provide OPC servers whose communications interfaces comply with the specifications laid out by the task force (the OPC Standard), and any client software that complies with that standard can communicate with any of those servers without regard to hardware releases or upgrades. The connection between the client and the OPC server is either through the Microsoft COM interface or through OLE Automation, and the client accesses data from the data cache maintained by the OPC server or requests that the server read the device directly. This is an OPC COM custom interface for the OSI Software Plant Information (PI) system. The interface may reside on a PI home node or a PI API node.
Each interface will connect with one and only one OPC server, which may be on the same or a different machine. More than one interface may be configured to connect to the same server.
This interface only runs on an Intel platform running Windows NT v4.0 or higher with Service Pack 3 or higher. It requires both the PI API and the PI SDK.
For interface-level failover, Microsoft Clustering is required. See Failover section for more.
Configurations
The Preferred Configuration
[pic]
Another Possibility
[pic]
Supported Features
|Feature |Support |
|Part Number |PI-IN-OS-OPC-NTI |
|Platforms |NT-Intel, W2K, XP |
|PI Point Types |Float16 / Float32 / Float64 / Int16 / Int32 / Digital |
| |/ String |
|Subsecond Timestamps |Yes |
|Subsecond Scan Classes |Yes |
|Automatically Incorporates PI Point Attribute Changes |Yes |
|Exception Reporting |Done by Interface / Done by DCS |
|Outputs from PI |Yes |
|History Recovery |No |
|*Failover |Yes |
|Inputs to PI: Scan-based / Unsolicited / Event Tags |Scan-based / Unsolicited / Event Tags |
|Uniint-based |Yes |
|Maximum Point Count |Unlimited |
|SDK |Yes |
|Vendor Software Required on PI API / PINet node |No |
|* Vendor Software Required on DCS System |Yes |
|Vendor Hardware Required |No |
|* Additional PI Software Included with Interface |Yes |
*See below for further explanation.
Source of Timestamps
The interface can accept timestamps from the OPC server or it can provide timestamps.
Failover
The interface supports server-level failover, where the interface will shift to a backup OPC server if the current server becomes unavailable, and also interface-level failover, where one copy of the interface sits dormant until the primary copy becomes unable to collect data. Interface-level failover requires NT clustering.
Vendor Software Required on DCS System
The OPC server may run on the same system as the interface itself, or it may run on another system. The interface does not come with an OSI-supplied OPC server.
Additional PI Software Included with Interface
The PIOPCTool is an OSI product that assists in installing, configuring, and troubleshooting the interface.
Requirements - PI2 and PI3 Servers
Beginning with version 2.1.0, the OPC interface requires the PI SDK as well as the PI API to be installed and configured on the machine. The interface will not run without the SDK.
We are currently also offering a version of the interface which does not use the PI SDK. This is intended to make it easier for those customers who are using PI 3.2 servers. With PI 3.3, the security of the system is configured using the PI Trust relationships in the PI server, so we no longer require a login password to be encrypted by the interface. Older versions of the interface required the user to run the interface interactively to set the password which would be used by the PI SDK, and sent to the PI 3.2 system to validate the security of the connection. The /Setlogin flag allowed the user to change the login ID and password. That is no longer supported, so we are providing a version of the interface which does not use the PI SDK to make support easier for sites which have not yet upgraded to PI 3.3.
Note that it is the PI SDK which gives us support for features such as long strings for ExDesc, and InstrumentTag, as well as enabling tools such as the ICU (Interface Configuration Utility) and APS (Auto Point Synchronization). You can only have those features if you use the full version of the interface.
Upgrading from Version 1.x or 2.0 to 2.1 or Higher
With version 2.1, the OPC interface has been brought into alignment with other OSI interfaces. Location1 is now used to indicate the interface instance number. This means that users who are upgrading from an earlier version will have to make a one-time change to their tag configuration, and set their opcint.bat file accordingly. The change comes in three steps; you can use SMT to update your tags, or use the piconfig commands below.
For all tags with a value of 1 in Location1, set Location3=2.
The piconfig commands would be (Change pointsource=O to use your pointsource!!):
>@tabl pipoint
>@pointclass classic
>@mode edit
>@modify Location3=2
>@select tag=*,pointsource=O,Location1=1
>@ends
Then edit your opcint.bat file to make sure that /ID= has a numeric value, such as /ID=4.
Finally, set Location1 for all the OPC tags to be the same as your /ID=# parameter in your opcint.bat file.
>@tabl pipoint
>@pointclass classic
>@mode edit
>@modify Location1=4
>@select tag=*,pointsource=O
>@ends
If you have no output tags (which were signified by Location1=1, and are now signified by Location3=2), you can leave your current tag configuration in place as long as you do not use a numeric value in the /ID= parameter. If /ID= does not specify a number, or specifies 0, the interface will accept all tags with the correct pointsource, regardless of the value in Location1 of the tag. If you specify a numeric value for /ID=, the interface will only accept those tags that have the correct pointsource and that numeric value in Location1.
Overview
Notes on OPC and COM
The general idea behind COM is that using a standard method for passing information between programs allows us to ignore where a program runs: as long as we can connect to that program and exchange information, we don’t care if the program is running on our local machine, a machine across the room, or a machine in another country. For that matter, we don’t care what kind of machine it is.
The parts that are necessary for this to work are:
• The actual program that has the information we need, or wants the information we have.
• A program that runs on our machine that knows how to talk to the other program.
The actual OPC server may run on the same node as the interface, or on another machine entirely. Frankly, we don’t care which (well, there are some performance considerations). The important thing is that your OPC server will, when you install it, put entries into the NT Registry which will allow the NT system to locate the OPC server when someone wants to talk to it. If your interface and your OPC server are running on different machines, you can use OPCEnum to locate those registry entries on the other machine. As long as a program has a way to find those registry entries, it can use them to ask NT to connect it to the OPC server.
The notion behind OPC is that there’s a process device out there, it has some points on it, the OPC server knows about those points, and it’s willing to let you touch those points. This is all arranged by the client (that’s us, the OPC interface) creating a Group and adding points to it, or connecting to a Public Group that’s already been defined. All reads and writes actually happen to Groups, not individual points, although the client program can choose what points within the group to read or write. The Interface doesn’t define points, only groups: we add points to our groups, but they must be points which the OPC server is willing to recognize as valid points.
Another detail is that the OPC server will have a data cache where it keeps the most recent data. A client can specify that data should be read out of the cache, which will be very fast, or read directly from the device, which can be slow and will block all other reads and writes until the device read is finished. Our interface does all reads from the cache, and all writes to the device. When we create our group, we specify how often the cache values for the points in that group should be updated; the requested update rate is the same as the scan rate for those points. This is a requested update rate: the OPC server may not actually agree to update the cache that often. If the server says it can’t update the cache as quickly as we want, that information will be noted in the log file. The defining characteristic of a group is its scan rate.
Along with the interface, we’re providing a simple OPC client (PIOPCTool). It has an internal help, but it’s really very basic: it looks to see what OPC servers are registered on your machine and gives you a list to select from. You choose the one you want, and then press the Connect button. If the server is on another machine, tell it the name of that machine, and press Connect, and it will ask the other machine what OPC servers it has, and add them to its list. (You will need to have OPCEnum installed on both machines, that's covered later.)
If you can’t connect using the PIOPCTool client, then there's no sense even trying the interface until you've solved the problem. See the sections below on troubleshooting connections before you go any further. You can also use PIOPCTool to read and write data. Look at the help inside PIOPCTool for more instructions. If you can use Refresh and Advise to get data into PIOPCTool, the interface will be able to get data. Using SyncRead to get data only shows that the server responds to synchronous calls, it does not show that you will be able to get data into the interface, as the interface uses only asynchronous calls to get data.
Timestamps
The interface is designed to get timestamps from the OPC server along with the data. The interface will then adjust those timestamps to match the time on the PI server. This is done because PI cannot store data in the future, and the OPC interface and/or the device may have a clock setting which is quite different from that of the PI server. The adjustments to the timestamps will also correct for clock drift. The interface attempts to get new timestamps from the PI server and the OPC server every 30 seconds.
If your OPC server does not provide timestamps, or does not provide timestamps for all data, you may choose to use one of the command-line switches to adjust the behavior of the interface.
The preferred setting is /TS=Y. This expects the OPC server to provide timestamps, and will only adjust them to localize them to the PI server.
/TS=N is used if the OPC server cannot provide any timestamps. The interface will timestamp each value as it receives it and adjust that to the local time of the PI server. This is the default setting.
/TS=A is used if the OPC server will provide timestamps for Advise tags. Some servers will return correct values for Advise items, but for polled reads they will return the time that the value last changed, rather than the time of the read. This option allows you to use the Advise timestamps, but have the interface provide timestamps for the polled values, just as it would with /TS=N. This option is only valid for OPC servers conforming to the OPC Data Access v1.0a standard. The v2.0 standard does not allow the client to request data without timestamps.
/TS=U allows the user to live dangerously. Timestamps received from the OPC server will be sent to PI directly, without any adjustment at all. If this results in PI receiving timestamps that are in the future, the data will be dropped. Use this option with great caution, and only if there's no other choice, and be sure you check the OPC server machine's clock against the PI server machine's clock frequently. If you are seeing error -11049 in your pipc.log file, check the clock on the PI server and on the interface node; this error means the interface has sent a timestamp, which is outside of the range for the PI archives.
Writing Timestamps to the Device
Timestamps may be written to or read from the device as data. To read and write timestamps from a PI tag, where the timestamp is the value of the tag, see the section below on Datatypes.
For the special case where you need to write the timestamp of an output value to one ItemID, and the output value itself to another, you can specify the ItemID to get the timestamp in the ExDesc field. You must also specify whether the ItemID is to be written as a VT_DATE or as a VT_BSTR (string value). If it it to be written as a string value, you must have /TF defined in your opcint.bat file, so the interface knows what format to use to create the string. See the sections on ExDesc and on Command Line Parameters for more on these settings.
Connections - Creating, Losing, and Recreating
The interface is designed to be very persistent about creating and maintaining a connection with both the OPC server and the PI archive. If either or both of them are not available on startup, it will log that fact to the pipc.log file and wait around, retrying the connection periodically. If it loses the connection to the PI server, it continue to gather data and try to send it to PI, while it tries to re-establish the connection to PI. Use of the API buffering program (bufserv) is strongly recommended, to avoid losing data if your PI system is unreachable. If the interface loses the connection to the OPC server, it will keep trying to re-establish that connection (see the section on Failover for alternative strategies).
If the connection to PI is lost, the only thing visible from the PI side is that no data is coming in. But the interface accepts two command-line parameters that will let you use PI tags to monitor the connection with the OPC server and watch how much data is waiting to be passed over to PI. These are the /ST and /QT parameters. See Software Configuration: The Interface File for more information on using them. The interface will only write to these tags when the value has changed.
The interface also monitors the server status reported by the OPC server. On startup, it will wait around for the OPC server to report that it is in RUNNING state, before beginning the process of creating groups and adding items. To accommodate broken servers that don't return the proper state code, you can use the /IS flag in the opcint.bat file (see below for more on that).
The OPCEnum Utility
The OPC Foundation has provided a tool to allow clients to access servers on remote nodes, without having to have information about those servers in the local registry. That tool is OPCEnum. It will be installed with the interface, but you will need to set the DCOM permissions (using dcomcnfg.exe) to allow it to communicate with OPCEnums on other systems. The only thing that OPCEnum does is tell other instances of OPCEnum what OPC servers are on the local system, and it can ask other OPCEnums what OPC servers are on their systems. You should give Access and Launch DCOM permissions to SYSTEM, NETWORK, INTERACTIVE, and at least to the Userid which you expect to be using for the interface, although giving permission to Everyone is quite safe.
While the interface and DCOM, and the PIOPCTool itself, only require NT4 with Service Pack 3, OPCEnum requires at least SP4 and it requires that you have Internet Explorer 4 or higher installed. See the help in the PIOPCTool for more information about OPCEnum and how to use it.
If your OPC server is on a different system, and your OPC server does not install OPCEnum, you can copy the contents of the OPCEnum directory (it's right below your interface directory) to the OPC server system, and then run register.bat on that system. You'll need to be logged into a userid on the server system that has administrative privileges. Again, check DCOM permissions.
Plug-In Post-processing DLLs
The interface has the ability to use plug-in DLLs. These are libraries of routines that do application-specific data processing before the data is sent to PI. The DLLs and their accompanying files and documentation can be obtained separately from OSI, and are installed into the Plug-Ins subdirectory under the interface directory. Please refer to the "Plugins Readme.txt" file in the Plug-Ins directory for how to install the plug-in packages. Each plug-in package contains the documentation for how to use that specific package.
Polling, Advising and Event Tags
The OPC interface has three methods of getting data: advising, polling, and event reads (also known as triggered reads). For Advise tags (called 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 for the group. For event reads, the PI server tells the interface when the trigger point has a new event (not necessarily a change in value), and the interface sends an asynchronous Read for the tags attached to that trigger. All three kinds of points are read asynchronously, and the same data routines process all updates.
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 to not have too many tags in one group. You can have multiple scan classes with the same scan rate; use the offset parameter to ensure that the load on the interface is smooth, rather than having the interface attempt to read all your tags at the same time. It is strongly recommended that you not mix advise tags and polled tags in the same scan class.
Advise tags will be grouped by the interface, if they are in scan class 1. You specify a scan class for advise tags, just as you do for polled tags, but for tags in scan class 1 the interface will automatically limit the number of tags in an advise group to 800. Up to 800 tags will be put into a group, if they all have the same deadband. 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. If you would rather group your advise tags yourself, you can use any scanclass. It is strongly recommended that you not mix advise tags and polled tags in the same scan class.
Event tags (triggered reads) are usually used to gather a set of data points after a particular event has occurred. The PI tag which 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, this is done with an asynchronous read to the server’s cache. For v2.0 servers, the async read from cache is not available, and the interface must do an async read from the device. Doing very many of these device reads could impact the performance of the OPC server. For any async 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 PI, 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, you must set the scan class to zero, but you will enter a group number 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 depends 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. See the section on Configuring Event Tags for more on this topic.
Datatypes
By default, the interface will request the following datatypes:
|Digital State tag |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 are some ways to change those defaults.
A Note on Versions
Prior to version 2.1.31 of the interface, the various settings for Location2 were only valid for certain PI datatypes: you could only use a value of 2 or 3 in Loc2 with a Digital State tag, and you could only use Loc2 = 5 with a Float32 tag. As of version 2.1.31, you are not restricted to specific tag types, but you will still not get valid data if you specify a translation that isn’t reasonable. That means that if you read a value as a string, and want to put it into an Int32 tag, the string has to have a number in it. If you read a value as VT_R8 (a 64-bit floating point value), and want it 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 you can fit into an Int16.
Reading Digital, Integer, and Real Tags as Strings
Tags that are defined as Digital State 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, you can have Digital State tags which are read and written as though they were String tags, by setting Location2 = 1. You must make sure that the strings used by the OPC server are exactly identical to the strings in the Digital Set, including case, punctuation, and spacing.
Other OPC servers cannot serve up certain numbers as numeric, they can only provide the character strings. For these servers, you can also 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 you want to read that data into a PI Digital State tag, since "-1" is not actually what you want 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 state tags. Since digital state tag values are actually offsets into the digital state table for the tag, and a negative offset has no functional meaning, this should not cause problems for properly written servers. This is in no way intended to validate or encourage such broken behavior on the part of servers. It is simply to allow clients to use them even though they're broken.
You may also have the interface 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 your OPC server doesn't want to send your data as a 2-byte integer (VT_I2), you can set Location2 = 3 to have the interface request the data as a 4-byte integer (VT_I4). Of course, this uses up more resource, so only use it if you have to.
Reading Tags as Float64 Values
Likewise, if your OPC server will only give you a particular value as an 8-byte floating point number (VT_R8), you can set Location2 = 5 to have the interface request VT_R8 even though you'll be storing it to, for instance, a 4-byte floating point tag. There may be some loss of precision, and if the number is too large to fit inside your tag, you will see a status of BAD stored to 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 timestring value in it such as "2000/11/02 15:34:29". The format of the strings must be supplied in the command file (opcint.bat) with the /TF switch. See the section below on Timestamp Strings for how to create that format.
If the PI tag is an integer tag, the interface will attempt to translate the timestamp into whole seconds and store that in PI (remember that Int16 tags can only hold numbers up to 32767, so for time spans longer than 9 hours you'll need Int32 tags). 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 timezone settings or /TS switch on the command line. However, if you configure the tag to use scaling or transformation, that operation will happen after the string has been translated into seconds, so you can actually handle a wide range of values.
Reading Timestamps as VT_DATE Datatypes
The OPC standard allows the use of VT_DATE as a datatype. This is an internal representation of a timestamp. Setting Location2 = 7 tells the interface to use the VT_DATE datatype for reading the value from the OPC server, or for writing the value, if it's 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 timezone settings or /TS switch on the command line. For string tags, the timestamp format specified with the /TF switch 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 you need to process more than one format of timestamp string, you will have to use more than one copy of the interface. The interface will make a copy of your 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 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
6. 3-digit milliseconds
XM either AM or PM
You can put those tokens together in any way, 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. So, 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 Datatype
To accomodate certain broken servers, which do not allow clients to specify a datatype even when the client asks for the very one that the server uses, you can set Location2 to be 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, you should always specify the datatype that matches your PI tag.
Transformations and Scaling
While OPC servers can perform their own transformations and scaling, some users have found that the desired functions are not filled by their server. So, you can configure your PI points so that the interface will perform transformations and scaling for you. Note that transformation and scaling happens before the value is compared to the exception parameters for the tag, so the exception parameters are applied to the value that would be sent to PI, rather than to the raw value.
Scaling
Scaling is fairly complex, and is controlled by the TotalCode and SquareRoot properties of the tag. Since we're limited in what information we can get about the tag, the Convers property is used to carry the Span of the device, and the ExDesc does further duty to carry the device Zero (DZero). Thus you can have the interface translate a value from the scale of what the device can send to the scale of the actual tag.
If TotalCode is zero, the only scaling that will be done is based on the value of SquareRoot. If Square Root is a 1, the value read will be squared before sending it to PI, and for an output value the square root will be taken before writing to the device. If SquareRoot is a 2, the opposite happens: for values read from the device, the square root of the value read will be sent to PI, while output values will be squared before sending them to the device.
If TotalCode is non-zero, some other scaling may be done, either to transform the value read into another scale of measurement or to apply an offset or conversion factor. Just as the value stored in the tag ranges from (Zero) to (Zero + Span), so the values read from or written to the device can range from (DZero) to (DZero + Convers). This allows the value stored in PI to be a simple transformation from one scale to another. The SquareRoot property can be used to specify that the square or square root of the value should be used rather than the value itself. In other cases, the Convers value may be added to or subtracted from the value, or may be used as a multiplier, or applied as a bitmask. Again, the SquareRoot code may specify using the square or square root of the value, rather than the raw value, as the input to the formula.
Scaling is only supported for numeric tags. You may have a tag defined in PI as a number, yet the OPC server reads and writes the Item as a string, and those tags would support scaling. But if the PI tag is defined as a string , any scaling will be ignored.
The table below covers all the scaling formulas currently used. Again, if SquareRoot is a 1 or a 2, the square root or square of the value will be calculated first, and then the formula will be applied.
|Convers |TotalCode |SquareRoot |DZero |Operation: |
|0 |0 |0 |Don't care |Value = value |
|0 |0 |1 |Don't care |Input tags: |
| | | | |Value = (Value)2 |
| | | | |Output tags: |
| | | | |Value = (Value)0.5 |
|0 |0 |2 |Don't care |Input tags: |
| | | | |Value = (Value)0.5 |
| | | | |Output tags: |
| | | | |Value = (Value)2 |
|Not 0 |1 |0 |Defined |Input tags: |
| | | | |Value = [ (Value – DZero) / Convers ] * Span + Zero |
| | | | |Output tags: |
| | | | |Value = [ (Value - Zero) / Span] * Convers + DZero |
|Not 0 |1 |1 |Defined |Input tags: |
| | | | |Value = [ ((Value)2 – DZero) / Convers ] * Span + Zero |
| | | | |Output tags: |
| | | | |Value = [ ((Value)0.5 - Zero) / Span] * Convers + DZero|
|Not 0 |1 |2 |Defined |Input tags: |
| | | | |Value = [ ((Value)0.5 – DZero) / Convers ] * Span + |
| | | | |Zero |
| | | | |Output tags: |
| | | | |Value = [ ((Value)2 - Zero) / Span] * Convers + DZero |
|Not 0 |2 |0 |Don't care |Input tags: |
| | | | |Value = Value * Convers |
| | | | |Output tags: |
| | | | |Value = Value / Convers |
|Not 0 |2 |1 |Don't care |Input tags: |
| | | | |Value = (Value)2 * Convers |
| | | | |Output tags: |
| | | | |Value = (Value)0.5 / Convers |
|Not 0 |2 |2 |Don't care |Input tags: |
| | | | |Value = (Value)0.5 * Convers |
| | | | |Output tags: |
| | | | |Value = (Value)2 / Convers |
|Not 0 |3 |0 |Defined |Input tags: |
| | | | |Value = (Value / Convers) – DZero |
| | | | |Output tags: |
| | | | |Value = (Value + DZero) * Convers |
|Not 0 |3 |1 |Defined |Input tags: |
| | | | |Value = ((Value)2 / Convers) – DZero |
| | | | |Output tags: |
| | | | |Value = ((Value)0.5 + DZero) * Convers |
|Not 0 |3 |2 |Defined |Input tags: |
| | | | |Value = ((Value)0.5 / Convers) – DZero |
| | | | |Output tags: |
| | | | |Value = ((Value)2 + DZero) * Convers |
|Not 0 |4 |0 |Defined |Input tags: |
| | | | |Value = (Value - DZero)/ Convers |
| | | | |Output tags: |
| | | | |Value = (Value * Convers) + DZero |
|Not 0 |4 |1 |Defined |Input tags: |
| | | | |Value = ((Value)2 - DZero)/ Convers |
| | | | |Output tags: |
| | | | |Value = ((Value)0.5 * Convers) + DZero |
|Not 0 |4 |2 |Defined |Input tags: |
| | | | |Value = ((Value)0.5 - DZero)/ Convers |
| | | | |Output tags: |
| | | | |Value = ((Value)2 * Convers) + DZero |
|Not 0 |5 |0 |Don't care |Input tags: |
| | | | |Value = Value + Convers |
| | | | |Output tags: |
| | | | |Value = Value - Convers |
|Not 0 |5 |1 |Don't care |Input tags: |
| | | | |Value = (Value)2 + Convers |
| | | | |Output tags: |
| | | | |Value = (Value)0.5 - Convers |
|Not 0 |5 |2 |Don't care |Input tags: |
| | | | |Value = (Value)0.5 + Convers |
| | | | |Output tags: |
| | | | |Value = (Value)2 - Convers |
|Not 0 |6 |Don't care |Don't care |Input tags: |
| | | | |Value = Value AND Convers |
| | | | |Output tags: |
| | | | |Value = Value AND Convers |
|Not 0 |7 |Don't care |Don't care |Input tags: |
| | | | |Value = Value OR Convers |
| | | | |Output tags: |
| | | | |Value = Value OR Convers |
|Not 0 |8 |Don't care |Don't care |Input tags: |
| | | | |Value = Value XOR Convers |
| | | | |Output tags: |
| | | | |Value = Value XOR Convers |
Quality Information
The OPC Data Access standard uses Fieldbus quality flags. The interface translates those quality flags to the closest approximation within the PI System State table. The low 8 bits of the Quality flags are currently defined in the form of three bit fields, Quality, Substatus and Limit status. The 8 Quality bits are arranged as follows:
QQSSSSLL
The tables at the end of this section give the transformation to PI status. The second table gives the status codes that will be used if the PI system is version 3.3 or newer. That version of PI is the first that defines the states needed by the OPC interface, so that the interface will not use the Archive Offline and other states which were causing some confusion.
Questionable Qualities -- Store the Status or the Value?
Because the PI archive stores either the quality or the value, the interface will translate the qualities in the “questionable” category to GOODSTAT, and set the “questionable value” flag for the data value. “Bad quality” flags get the corresponding PI status stored for the tag. If the quality is SUBSTITUTED_ST, the interface will currently store the status rather than the value sent. You can change this behavior with the /SQ flag in the opcint.bat file. Setting /SQ=Y flag will cause the interface to store the quality (translated to a PI status) if the quality is anything but GOOD. Similarly, if you set /SQ=I, the interface will ignore the "questionable" quality, and treat the value as if it had good quality.
|Quality |no /SQ flag |/SQ=Y |/SQ=I |
|GOOD |value |value |value |
|Questionable |value, flag |digital state |value |
|BAD |digital state |digital state |digital state |
Storing Quality Information Directly
You also have the option of storing the quality in a separate PI tag, so you can keep both the values reported and also the qualities that came with those values, with no loss of granularity. Setting Location2=4 for a tag tells the interface that you want to store the quality for the associated OPC Item, rather than the value. Since OPC qualities are unsigned 16-bit integers, we expect to have an Int32 tag to receive them. The values are stored in PI without any change, and their status is always GOOD. To understand what those quality values represent, please go to and download the OPC Data Access specifications, which contain a brief discussion of quality data.
Note: the column on the left is a bitmask. The first number, for instance, would correspond to a hexadecimal value between 0xC0 (11000000 bitmask) and 0xFF (11111111 bitmask).
Quality States Used with PI Systems Earlier than PI 3.3
Good Quality
|Quality |OPC Definition |PI Status |
|11SSSSLL |Non-specific |Good |
|Except | | |
|110110LL |Local Override |_SUBStituted |
Not used by OPC
|Quality |OPC Definition |PI Status |
|10SSSSLL |Invalid |Bad Input |
Questionable
|Quality |OPC Definition |PI Status |
|010110LL |Sub-Normal |Bad_Quality |
|010101LL |Engineering Units Exceeded | |
|QQSSSS01 |Low Limited |Under LCL |
|QQSSSS10 |High Limited |Over UCL |
|Otherwise | |Inp OutRange |
|010100LL |Sensor Not Accurate | |
|QQSSSS01 |Low Limited |Under Range |
|QQSSSS10 |High Limited |Over Range |
|Otherwise |Out of calibration |Invalid Data |
|010011LL |Invalid |Bad Input |
|010010LL |Invalid |Bad Input |
|010001LL |Last Usable Value |No_Sample |
|010000LL |Non-specific |Doubtful |
Bad Quality
|Quality |OPC Definition |PI Status |
|000111LL |Out of Service |DCS failed |
|000110LL |Comm Failure |Arc Off-line |
|000101LL |Last Known Value |Scan Timeout |
|000100LL |Sensor Failure |Equip Fail |
|000011LL |Device Failure |Unit Down |
|000010LL |Not Connected |AccessDenied |
|000001LL |Configuration Error |Configure |
|000000LL |Non-specific |Bad |
Quality States Used with PI Systems Version PI 3.3 and Later
Good Quality
|Quality |OPC Definition |PI Status |
|11SSSSLL |Non-specific |Good |
|Except | | |
|110110LL |Local Override |_SUBStituted |
Not Used by OPC
|Quality |OPC Definition |PI Status |
|10SSSSLL |Invalid |Bad Input |
Questionable
|Quality |OPC Definition |PI Status |
|010110LL |Sub-Normal |Bad_Quality |
|010101LL |Engineering Units Exceeded | |
|QQSSSS01 |Low Limited |Under LCL |
|QQSSSS10 |High Limited |Over UCL |
|Otherwise | |Inp OutRange |
|010100LL |Sensor Not Accurate | |
|QQSSSS01 |Low Limited |Under Range |
|QQSSSS10 |High Limited |Over Range |
|Otherwise |Out of calibration |Invalid Data |
|010011LL |Invalid |Bad Input |
|010010LL |Invalid |Bad Input |
|010001LL |Last Usable Value |No_Sample |
|010000LL |Non-specific |Doubtful |
Bad Quality
|Quality |OPC Definition |PI Status |
|000111LL |Out of Service |Out of Service |
|000110LL |Comm Failure |Comm Failure |
|000101LL |Last Known Value |Scan Timeout |
|000100LL |Sensor Failure |Equip Fail |
|000011LL |Device Failure |Unit Down |
|000010LL |Not Connected |Not Connected |
|000001LL |Configuration Error |Configure |
|000000LL |Non-specific |Bad |
PI Point Configuration
Point Attributes
The following information is necessary to define a PI tag for use with an OPC Server. Failing to configure your tags will mean that the interface cannot communicate properly with the OPC server. See the section on Error Messages for information on how to recognize configuration problems. Also, see the Sample Configuration section for examples.
PointType
The interface itself supports all PI point types except the BLOB, but not all OPC servers will support all point types. Refer to the vendor-supplied documentation for your OPC Server to determine what point types are supported by the specific server. If the point type defined in PI does not match the canonical data type defined in the OPC server, the interface will attempt to translate the data. If you have a question about whether the point can be read as the type you want, use the PIOPCTool to try to read the point directly from the OPC server. Also, see the Datatypes section for special settings that may help you get around recalcitrant servers.
PointSource
All tags defined in the PI database and used by the OPC interface must share a common point source. The point source is a one character variable, for example, G. On a PI 2 system, the point source for the interface must be defined in PI before interface operation or tag definition.
Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer subsystem uses the point source character T, the Alarm subsystem uses G and @, and PI Performance Equations uses C. One should either not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Hence, it would be confusing to use L as the point source character for an interface.
The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T.
InstrumentTag
This field contains the ItemID for the tag. The format of this field depends on the specific OPC server being used. Refer to the documentation for your server to determine the proper format. This field must exactly match the point defined to your OPC server. That means punctuation, spaces, uppercase vs. lowercase, everything. This field must exactly match the point defined to your OPC server. For PI3 systems, this field can be up to 1023 characters long. For PI2 systems, the limit is 32 characters. If your point identifier is longer than 32 characters, use the ExDesc field.
To verify an ItemID, use the PIOPCTool. If your server supports browsing, you can use List Server's Tags to see a list of defined ItemIDs. Doubleclicking on an ItemID in the tree will result in the full ItemID being displayed in the Item field. This is the ItemID that you want to use in InstrumentTag.
ExDesc
The extended descriptor field is used for multiple purposes.
• To indicate event-based data collection:
To define an event tag, this field will contain “event=tagname”, where “tagname” is any valid PI tagname. When that tag has an exception event, the points for which it is the event, or "trigger", will be read from the OPC server.
• For long instrument tags:
If the instrument tag for this point is longer than 32 characters and you are using a PI2 system, you can put the instrument tag here in the form “instr=whatever.the-opc/server*needs”. Again, the instrument tag must exactly match the ItemID defined to your OPC server. If the instrument tag contains a comma, enclose the tagname with double quote characters (“), such as:
Instr=”whatever.you, or someone*needs*”
• To specify DZero for scaled tags:
For tags where the range of values which the device returns must be scaled to fit the range of values the tag stores (such as scaling from device voltage to temperature in degrees Celsius), you will use the Convers field to store the device Span, and you must store the device Zero here in the ExDesc. The format is
DZero=nnnnn.nnn
• To specify the ItemID to receive the timestamp for an output value
When you need an output value to go to one ItemID, and the timestamp that comes with the output value to go to another ItemID, you can specify the timestamp ItemID here. Thus, the ItemID specified in your instrumenttag field will get the value, and the ItemID specified in the ExDesc field will get the timestamp that goes with that value. The same restrictions apply to this ItemID as are stated above, under "For long instrument tags". There are two formats, depending on the datatype of the ItemID that is to receive the timestamp.
Tim=ItemID
Dat=ItemID
Both of these formats will write the date and time. The difference is that using Tim= will tell the interface to write the timestamp as a string (VT_BSTR), formatted according to your /TF setting in the opcint.bat file, while using Dat= will tell the interface to write the timestamp as a VT_DATE. When written as a VT_DATE, the timestamp is in universal (UTC) format, so there is no dependence on timezone or daylight savings time setting. When written as a string, the timestamp is that of the PI server, and is not adjusted for differences in timezone or daylight savings time setting. The timestamp written to the OPC server is the same timestamp you would see if you were on the PI machine and looked at the database timestamp.
Please note that in error messages relating to this timestamp ItemID, the interface will report a generated tagname of the form TS:xxxxxx, where xxxxxx will be the PI tagname of the output tag.
If you use this field to specify more than one of the above items, put a comma between the definitions.
This field can contain 80 characters for a PI2 system, or 1023 for a PI3 system.
A Note on Performance Points
Those familiar with other PI interfaces may have used "Performance Points" before. These tags document how long it takes to complete a scan. Due to the architecture of this interface, performance points are not valid -- the server's response is asynchronous, so the time to "scan" bears no relation to the amount of time it may take to get the data from the server.
SourceTag
To specify the source tag for an output point, this field will contain a valid PI tagname. On an exception for that tag, the value in the source tag will be written to the OPC point defined in the InstrumentTag (or in ExDesc) and also to the output tag. For an output point with no SourceTag defined, when the output tag itself has an exception, the value of the output tag will be written to the OPC point. 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.
Scan
This field is a flag to indicate whether the value for this point should be read. The intention is to allow tags to be defined but inactive. A value of On in this field will allow the point to be active; a value of Off will disable it. Disabled points will be ignored, both for reading from the OPC server and writing to the OPC server.
Totalcode
This field holds the code used to indicate what scaling to apply to the value. The SquareRoot, Convers, and ExDesc fields may also be needed. See the section on Scaling for a complete description of how to use this field. Valid values are 0 through 5, with 0 the default.
SquareRoot
This field is used to indicate that the value stored in PI or written to the device should be squared first, or the square root should be found. See the section on scaling for a complete discussion of its use. Valid values for this field are 0, 1, and 2. The default is 0.
Convers
This field is used for scaled tags to hold the device span. Just as a PI tag has a zero and a span, which together define the legal range of values, the device Item may have a DZero and a DSpan, which define the actual span of values, which the device will send. The interface can use those two ranges to translate from the units used by the device to the units defined for the PI tag. The Convers field may also hold an offset or multiplier. See the section on Scaling for how to use this functionality.
Location1
The first location field specifies the interface instance number. In the opcint.bat file, there is a parameter for interface ID, /ID=#, where # is any number. The Location1 field for each tag must match that number, or the tag will be ignored. So if your opcint.bat file has "/ID=4", and "/PS=O", the only tags with pointsource=O and Location1=4 will be used by that copy of the interface. This lets you have multiple interfaces use the same pointsource, each with their own ID. In the pipc.log file, the ID shows up as the last identifier on each line, for example
26-Mar-00 23:24:50
OPCpi> 1> API version> 1.3.1.3
shows a 1 in the ID field, so that message was printed by the interface with ID=1 in its opcint.bat file.
If /ID= does not specify a number, or specifies 0, the interface will accept all tags with the correct pointsource, regardless of the value in Location1 of the tag. If you specify a numeric value for /ID=, the interface will only accept those tags that have the correct pointsource and that numeric value in Location1.
Location2
This field is used to indicate special handling. See the discussion on Datatypes for more information.
Location2 = 0
Normal processing
Location2 = 1
If Location2 is a 1, the value in the OPC server will be read as a String, and written as a String. For Digital tags, this will only work if the strings read from the OPC server are an exact match for the strings in the Digital State Set used by the tag. See the Data Archive Manual for a complete discussion of Digital State sets and Digital State tags.
For Integer and Real tags, setting Location2 = 1 will cause the interface to request a string value, and then try to translate that string value into a number.
Location2 = 2
If Location2 is set to 2 for a Digital State tag, the value will be read as a Boolean. Booleans can have only two values, zero and nonzero; you can only use Location2=2 if your Digital State Set only has two values. Likewise, for numeric tags, any value but 0 will be True (-1), and a value of 0 will be False (0).
Location2 = 3
If Location2 is set to 3, the value will be read as a 4-byte integer. This setting is included to accommodate servers, which cannot send the value as a 2-byte integer, which is how Digital tags are normally read.
Location2 = 4
This setting will cause the interface to store the quality of the item rather than the value. This allows us to store the value of the item in one tag and the quality in another.
Location2 = 5
This setting is for floating point numbers. By default, the interface will request Real tags as VT_R4 items (4 byte reals). If Location2 is set to 5, the interface will request Real tags as VT_R8 items (8 byte reals). For Float32 tags, including all PI2 Real tags, values that cannot be stored in a 32-bit floating point number will be dropped, and in any case some of the precision of the R8 will be lost in translation. This setting is included to enable the use of servers, which refuse to translate R8 data to R4 tags themselves, or to allow the use of Float32 tags where the benefit of greater precision is not worth the overhead of using Float64 tags.
Location2 = 6
This setting allows us to read timestamps from the OPC server as strings, and transform those strings into a number of seconds. The PI tag may be an Int or a Float. The format of the timestamp string is specified in the opcint.bat file with the /TF switch, and the same format is used for all tags. For more information on this, see the section above on Datatypes.
Location2 = 7
This setting allows us to read timestamps from the OPC server as VT_DATE variables. These values can either be translated into timestamp strings or passed to PI as a number of seconds, suitable for use in computations. If the value is translated into a string, the timestamp format specified with the /TF switch will be used. For more information on this, see the section above on Datatypes.
Location2 = 8
This setting will cause the interface to ask the server to give us whatever datatype it would like to give us. The interface will try to transform the value into the proper datatype for the PI tag. This may not be possible in all cases, so use this with caution, and only when your server is broken and will not provide data if you specify a datatype. It's always better to specify what type of data you want to get, unless the server will not honor such a request.
Location2 > 1024
For passing array data directly to a dll, you can combine any of the above Location2 settings ( 0 through 7) with 1024, to indicate that both the indicated setting ( 0 - 7) should be in effect, and that the tag is also a series array tag. For more information, see the manual for the TimeArray plugin module.
Location3
This field is used to indicate whether this tag is to be polled, advised, or output. A value of 0 indicates a normal polled tag or event tag, a value of 1 indicates an advise tag, and a value of 2 indicates that the tag is an output tag. For an advised tag, the OPC Interface will sign up for updates with the OPC Server, and the PI tag will be updated every time the value in the point changes. To minimize “noise”, you can use Location5 to indicate the desired “deadband”: if the change between the last value read and the new value is less than the deadband, the new value is ignored. This deadband processing is only valid for points which are defined in the OPC server as Analog. Care should be used when defining points as advised, as a point without a deadband can cause a great deal of data to be gathered very quickly. Deadband processing is optional for servers under the OPC standard: be sure that your server supports deadband processing before attempting to configure tags for advise.
Location4
Scan class number. Scan classes are defined in the interface startup file; each scan class defines an update period. This location code defines which scan class period is used to update the PI point.
The updates from the OPC server come in groups: at start-up, the interface defines a group on the OPC server and adds all points within the given scan class to the group. Up to 200 groups, and thus 200 scan classes, can be defined. The OPC server is queried for all points within a group at the same time, therefore some consideration should be given to the creation of scan classes. Having more than one scan class with the same scan period is allowed, and using different offsets on those scan classes may help performance. See the section on The Interface File, below, for more on offsets.
Event based points and output points do not use this location code, and its value for those points must be zero.
Advise tags use this location to specify the Requested Update Rate for the group: the OPC server will only check for new values as frequently as this, which allows you to use a larger value for points which don't change often, to lighten the load on your machine. By convention, the first scan class is reserved for advise tags. Other scan classes can also be used for advise tags, but any tags which use the first scan class and are not advised will not be polled. If there are more than 800 tags in the first scan class, they will be broken up into multiple groups, with each group having no more than 800 tags. If you need to have all the advise tags in the same group, you must use another scan class.
While it is possible to have advise tags and polled tags in the same scan class, it can cause odd problems, and the performance of the interface under those conditions is not guaranteed. It is strongly advised that you do not have advise tags and polled tags in the same scan class.
Location5
This field is used with Location3 for tags that are to be advised to define a deadband value which will be used by the OPC server. This is separate from the Deadband in PI, and proper use will result in fewer data points being sent to PI.
For this field to be valid, the corresponding point in the OPC server must be defined as an Analog point, and the EuMin and EuMax fields in the OPC server point definition will delimit the value range for the point (these correspond to the Zero and Span fields in the PI point definition, but here we’re specifically referring to the point as defined in the OPC server). The Location5 value is a percentage of that range, measured in hundredths. Thus, if the OPC server point is defined as Analog with an EuMin of -10 and an EuMax of 10, and Location5 contains 2500 (meaning 25%), data will only be sent to the PI tag when the difference between the new value and the old value is at least 5 (25% of 20 = 5).
Note: Deadband processing is optional behavior for OPC servers. If the server does not support deadband processing, the PI tag will be updated for all value changes to the point. If you are unsure of whether your server supports deadband processing, use the PIOPCTool to check.
Userint1
This field is used to give the index number for a tag within an array. The OPC standard supports reading data as an array of values; the array has one timestamp and one quality, with multiple values attached to them. To map these values to PI tags, we use the Userint1 field to give the one-based index into the array for each tag. Thus, the first value in the array will correspond to the tag with Userint1=1, the second to the tag with Userint1=2, and so on.
All the tags that belong to the same array must have exactly the same values in InstrumentTag, ExDesc, and all Location fields. The tag names can be whatever you like.
Note: All tags that are not part of an array must have a zero in Userint1.
Userint2
This field is used to designate an event group for an event tag. See the section on Configuring Event Tags for more on this topic.
Note: All tags that are not event tags must have a zero in Userint2.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where Uniint will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. See data archive (DA) section 4.2.3 of PI System Manual I for information on configuring shutdown events for PI 2.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the pishutev subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the snapshot subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, the reader is referred to the PI Data Archive Manual for NT and UNIX. Note that the SHUTDOWN events that are written by the pishutev subsystem are independent of the SHUTDOWN events that are written by the interface when the /opcstopstat command-line argument is specified.
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI server, allowing continuous data collection when the server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shutdown, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface. Refer to the Bufserv manual for additional information.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the pishutev subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. One can change the default behavior by editing the \PI\dat\Shutdown.dat file, as discussed in the PI Data Archive Manual for NT and UNIX.
Exception processing
The OPC interface handles exception processing a little differently from standard OSI interfaces, in order to allow exception processing for Advise tags. The ExcMin, ExcMax, and ExcDev parameters perform the usual functions, but unlike standard interfaces, if you set ExcMax to 0, you can still use values in ExcMin and ExcDev. The three parameters operate independently, and you must set all three to 0 to have the interface send every value to PI. See your PI manual for more on exception processing.
ExcMax
The longest time period between values sent to PI. Note this also works for Advise tags, so if we have not received a value after ExcMax seconds, and we've no indication that communication with the server has failed (we do check the clock every 30 seconds), we'll assume that the value has remained the same and will send the last value received to PI, with the timestamp set to the current time. For Polled tags, a value will be sent to PI if we haven't sent one in the last ExcMax seconds, even if the new value doesn't pass ExcDev tests.
ExcMin
The minimum time between values sent to PI.
ExcDev
The minimum change, from the last value sent to PI, which will cause a new value to be seen as an event and sent to PI.
Software Configuration
In addition to PI Point definitions, the point source, digital states, and the I/O rate counter need to be configured.
Point Source -- PI 2
The point source may be any alpha-numeric character not currently used by another process or interface. The point source is defined by running the Point Src display on the PI menu, choosing a blank field location from the point source list, and entering the following location parameter limits:
Point Source Character (char)
Point Source Description OPC
|Location 1 |Location 2 |Location 3 |Location 4 |Location 5 |
|0 |0 |0 |0 |0 |
|9999 |5 |2 |200 |10000 |
Point Source -- PI 3
Choose a single alpha-numeric character not currently used by another process or interface. Enter this character into the pointsource attribute for each of the interface tags.
Digital States -- PI 2
Digital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type. The digital states need to be defined prior to point configuration. For more information, see the DA manual.
Digital States -- PI 3
A digital state set is a group of digital states that are related. For instance, ON/OFF may be a digital state set where the zero of the tag is ON and a value of one for the tag denotes OFF. Each state set has a name, and that name must be in a tag's Digital State Set field in order for that tag to use that state set. Tags may also use system state sets for conditions such as "I/O Timeout" and to store quality information when the data received from the OPC server indicates a problem with the quality of the value.
IO Rate Points
An IO Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. There are two configuration steps.
Step 1 – PI Point configuration on the PI Server
For step 1 and 2, it is assumed that the name of the PI tag is OPCRate.
PI 3 Server Nodes
Create an IO Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |1 |
|ExcDev |0 |
The default settings can be used for the remaining PI Point attributes. However, one may wish to adjust the compression specifications (CompDev, CompMin, CompMax, and CompDevPercent) to control the amount of data that is archived owing to the IO Rate point.
PI 2 Server Nodes
Create an IO Rate Tag using one of the existing IO Rate Tags as a template. A listing of IO Rate Tags can be found on page DA-71 of PI System Manual I.
Step 2 – Configuration on the Interface Node
For step 2, it is assumed that the name of the IO Rate point on the home node is OPCRate.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PHOME entry in the pipc.ini file, which is located in the \WinNT directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C: \PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
OPCRate, x
where OPCRate is the name of the IO Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.
2. The interface must be stopped and restarted in order for the IO Rate tag to take effect. IORates will not be written to the tag until 10 minutes after the interface is started.
3. The 10-minute rate averages (in events/minute) can be monitored with a client application such as Processbook.
Command-line Parameters
Before the interface starts, a file containing the configuration parameters must be created. The command line arguments will need to be modified for your site and interface.
At startup, the interface interprets the command line arguments. The command line arguments define the point source, scan frequency, and many options for how to communicate with the OPC server and how to process the data received. All arguments must begin with a /, have a space between them, and have no spaces within the argument. The arguments are not case sensitive. A point source, scan class, and OPC server must be defined for the interface to start.
This list groups the arguments by usage, to show what options are available. The alphabetical listing that follows gives details about each argument and how it is used.
It is strongly suggested that if you can use the PI ICU (Interface Configuration Utility), you should do so. This tool is freely available from our web site, and can make configuring the interface much simpler. It is only available for interfaces that are connecting to PI3 systems of version 3.3 or higher. You can do everything by editing the batch file yourself, but the tool is provided to make configuration and support easier.
Caution: It is common with Uniint-based interfaces to use the /STOPSTAT parameter. You must not use this parameter with the OPC interface. Instead, you must use /OPCSTOPSTAT. Using /STOPSTAT may cause invalid values to be stored to your PI tags.
Starting and Finding Servers
/SERVER The name and location of the OPC server
/HOST The name and location of your PI server, and its port number
/STARTUP_DELAY If your interface hangs when the machine reboots, you may need to tell it to wait a few seconds before connecting to the network layer.
/PISDKCONTIMEOUT Change the timeout value for PISDK calls.
/MAXSTOPTIME Set how many seconds the interface is allowed for shutting down nicely.
Interface-level Failover
/CM Cluster Mode. Selects behavior for the backup interface.
/PR Primary or backup? /PR=1 is primary, /PR=2 is backup.
/RN Resource number. Identifies the apionline instance that goes with this interface instance.
/SIN Secondary interface nodename. Both nodes must have the same value for /SIN=nodename. Obsolete.
/FM Failover mode. /FM=1 is chilly, /FM=2 is cool, /FM=3 is warm (and is the default mode),
/CN The string tag into which should be written the name of the currently active interface node.
Server-Level Failover
/NI The number of interfaces running on this node.
/WD Watchdog tag specifications.
/BACKUP The name and location of the backup OPC server
/FT The number of seconds to try to connect, before switching to the backup server.
/SW The number of seconds to wait for RUNNING status, before switching to the backup server.
/CS The string tag into which should be written the name of the currently active server.
/WQ Fail over if watchdog tag has bad quality or any error.
/WS Fail over if the server status leaves the RUNNING state.
Post-processing ("plug-in" dlls)
/DLL The dll name and path, i.e.
c:\pipc\interfaces\opcint\plug-ins\mydll.dll"
Controlling Data Collection
Commonly Used
/EC IORate tag identifier
/ER Update rate for event classes
/F Scan class specifier, sets scan period for the class, and update rate unless overruled
/ID Interface instance identifier. This number shows which parts of pipc.log were written by this interface. The Location1 parameter of all tags must match this, unless /ID is zero or not numeric (in which case all tags with the correct point source will be considered valid for this instance of the interface). This is for running more than one instance of the interface on the same machine.
/OPCSTOPSTAT Specifies digital state to be written to all tags when the interface is shut down.
/PS The point source for the interface.
/SQ Store quality. If data has other than GOOD quality, store the quality information rather than the value if SQ=Y. If SQ=I, treat "questionable" quality as "good".
/ST Status tag. Tag to get the current state of the OPC server.
/TS Timestamps -- do we get them from the OPC server, or make them ourselves? If we get them from the server, do we adjust for clock differences between the OPC server clock and the PI clock ?
/VN Version number. We'll try to connect with v2.0 OPC Data Access, but if that doesn't work we'll use v1.0a. This switch tells the interface to skip trying v2.0. If your server only speaks v1.0a, use this.
Special Circumstances
/CR Connection Refresh. Causes the interface to call Refresh on all Advise tags when the PI server comes back after having been unavailable. Only useful if you are not using API buffering.
/CO ConnectionOutput. Causes the interface to send all output values when the PI server comes back after having been unavailable. Only useful if you are not using API buffering.
/ES Event source. Determines whether event tags are read from the OPC server's CACHE or directly from the DEVICE, for v1.0a servers. For v2.0 servers, it has no impact, because all event tag reads are from DEVICE.
/QT Queue Tag. A tag to hold the number of values currently waiting to be sent to PI. One way to measure the load on the interface. A high number here indicates that we're getting more data than we can quickly pass to PI. This switch is usually not needed if you have buffering enabled.
/UR Update rate specifier, if different from the scan class rate
/HQ High queue limit. Don't set this unless we tell you to, it tells the interface when to decide it is using too much memory, and it's time to drop data instead of sending it to PI.
/LQ Low Queue limit. Don't touch this either. It tells the interface when to resume sending data to PI.
/IT Integer Time. If you don't want or need the millisecond portion of the timestamp, use this flag to drop it. Storing integer seconds speeds up processing on the PI server.
/NT No Timeout. This flag directs the interface to never write IO Timeout. Ever. Included for very special circumstances, be sure you want this before you use it.
/SN Turns off exception reporting and sends all data to the snapshot. Should not be used except for testing.
/TF Sets the format for timestamp strings read from or written to the OPC server.
Handling Idiosyncracies for Various OPC Servers
/AF Advise groups immediately. This helps if your server does not return initial data on advise. The symptom is that when you create an advise tag for a value that doesn't change often, the interface does not write a value to PI when it first starts up. You can tell if you have this problem by using PIOPCTool to create a group, add tags, and then Advise the group. If you do not get an immediate value for your tags, but adding another tag to the group gets you a value for that tag, you will need to use the /AF=Y switch.
/AR Ignore the AccessRights property. If you see "Invalid read/write mode requested" in your pipc.log file, try this one.
/GL If you see “"OnDataChange:Invalid group ID” in your pipc.log file. This means that your server is broken. Please, please email us at techsupport@ and tell us what server it is so we can talk to the vendor.
/GS If you see "OnDataChange: Header status:" in your pipc.log file, the Group status sent by your server is invalid. Use this switch to tell the interface to ignore it.
/HWPS Honeywell Plantscape. Enable checking for error codes specific to the Honeywell Plantscape system, for server-level failover.
/IF Ignore First value. If your server sends data before it actually reads data, you may see zeros or erroneous values show up when the interface starts. This parameter will tell the interface to ignore the first value it receives for each tag.
/IS Ignore Status. The OPC server should go to RUNNING state when it's ready to send data. If it doesn't, you can tell the interface to try to talk to it anyway.
/MA Mass Adds. It's faster to add items to groups in bunches, instead of one by one. But some servers will reject the entire group if one tag is invalid, and it can take a lot of work to figure out which tag was the problem. So you can tell the interface to add tags one at a time. Use /MA=Y if you can, use /MA=N if you have to.
/RD ReconnectDelay. If the server goes away ungracefully, and we get an error code indicating the RPC server is unavailable or too busy to answer, we’ll wait this many seconds before trying to reconnect.
/TO Timestamp Offset. If your server installation is broken such that the time on the server machine is incorrect (specifically, this is useful when the server clock matches the wall clock but the server's timezone information is required to be incorrect), this will tell the interface to adjust all the timestamps by a specific amount.
Debugging
/DB Debug level
/DF The name of a PI tag that has the debug level. This should be an integer tag, configured as an output tag for the interface. When you change the value in the tag, the interface will capture the new debug flag value. Nothing will be written to the OPC server for this tag.
/DT Debug tag for some levels. See the section on Debugging.
Alphabetical List of Parameters
|Parameter |Description |
|/AF |The /AF argument is provided to help deal with broken servers which do not return initial |
|Optional |values for Advise tags. This argument must not be used in conjunction with NT Cluster |
|Default: /AF=N |Failover, as it causes OPC Groups to be advised as soon as they are created. |
|/AR |The /AR argument is used to tell the interface to ignore the access rights property on items |
|Optional |added to a group ( /AR=N). If your server does not use the access rights bitmask properly, |
|Default: /AR=Y |setting /AR=N will tell the interface to ignore the server's access rights bitmask and attempt|
| |to use the item anyway. The error from the interface is "Invalid read/write mode requested"; |
| |if you get this message, try using |
| |/AR=N. |
|/BACKUP |The /BACKUP argument is used if failover option is used. This switch specifies the name of the|
|Optional |backup OPC server. The backup server name is specified after an equal sign with no spaces or |
|Required for server-level failover|quotes as follows: |
| |/BACKUP=backuphostname::backupOPCservername |
| |Again, if the OPC server is on the local machine, the hostname:: must be omitted: |
| |/BACKUP= backupOPCservername |
|/CM |Cluster Mode. When the interface is configured for interface-level failover, running on a |
|Optional |cluster, this argument specifies which mode to use. Mode 0 is the original mode, with a |
| |preferred primary. Mode 1 is a non-preferential mode, where the whichever interface is active|
| |will stay active until the cluster resource fails over, either through a failure or through |
| |human intervention. The default is /CM=0. |
| |/CM=1 |
| |For more on failover modes, please see the section below on Interface-level Failover. |
|/CN |When the interface is configured for interface-level failover, running on a cluster, this |
|Optional |argument can be used to specify a PI string tag which will receive the nodename of the |
| |interface which is currently gathering data. This allows tracking of which cluster node was |
| |the active interface node. As with the other tag specifiers, you specify the PI tag with |
| |/CN=tagname |
| |This tag should be configured to be a Lab tag, or otherwise not belong to a point source which|
| |is in use. |
|/CO |This argument is only useful when, for some reason, you are not using API buffering. When the|
|Optional |PI server becomes unreachable, the interface will still try to send the data, but it will |
|Default: |fail. When an attempt to send data succeeds, then, the interface can send the current PI |
|/CO=N |value for all output tags to the device, just as it does when the interface first starts up. |
| |By default, the interface will simply wait for the next new value to come before writing |
| |anything to the OPC server. If you want the interface to send the current values to the OPC |
| |server when the PI server comes back online, include this argument in your opcint.bat file |
| |/CO=Y |
|/CR |This argument is only useful when, for some reason, you are not using API buffering. When the|
|Optional |PI server becomes unreachable, the interface will still try to send the data, but it will |
|Default: |fail. When an attempt to send data succeeds, then, the interface can call Refresh for all of |
|/CR=N |the Advise tags, to send their current value to PI, just as it does when the interface first |
| |starts up. By default, the interface will simply wait for the next value to come in. If you |
| |want the interface to request the current values from the OPC server when the PI server comes |
| |back online, include this argument in your opcint.bat file |
| |/CR=Y |
|/CS |When the interface is configured for server-level failover, this argument can be used to |
|Optional |specify a PI string tag which will receive the name of the server which is currently providing|
| |data. This allows tracking of which server was the active server across a period of time. As|
| |with the other tag specifiers, you specify the PI tag with |
| |/CS=tagname |
| |This tag should be configured to be a Lab tag, or otherwise not belong to a point source which|
| |is in use. |
|/DB |This is included to allow some minimal debugging if you have difficulty figuring out what |
|Optional |you're getting from your server. See the section on Debugging for more information. |
|Default: none | |
|/DF |This parameter allows you to change the value of the debug flag while the interface is |
|Optional |running. Configure an output tag for the interface, Int32, and set its value to 0. Give the |
|Default: none |name of this tag with the /DF parameter: |
| |/DF=OPC.Debug.Flag |
| |and give it some dummy instrumenttag. When you change the value in the PI tag, the interface |
| |will capture the new value and set its debug flag to that value. Nothing will be written to |
| |the OPC server. |
|/DLL |The interface now supports post-processing DLLs for specific OPC servers. The format for |
|Optional |telling the interface where to find your DLL is : |
|Default: none |/DLL=c:\directory\to\the\file\yourdll.dll |
| |where you replace the directory path and filename with the appropriate one for your DLL. |
|/DT |The name of the tag to be used with /DB=64. If this tag is not specified, the interface will |
|Optional |use the first tag for which it receives a value. |
|Default: none | |
|/EC |The /ec flag is used to specify an IORate tag from the iorates.dat file. Example entries from|
|Optional |an iorates.dat file are given below: |
|Default: none |Tagname1, 1 |
| |Tagname2, 2 |
| |where tagname1 and tagname2 can be any legal tag name. The number after the tag name can be |
| |between 1 and 33 or between 51 and 200, inclusive. Numbers 34 to 50 are reserved for future |
| |use. If /ec=2 is used on the command line for the above iorates.dat file, then the rate |
| |(events per minute) at which data is sent to the snapshot will be stored in Tagname2. The |
| |rate that is sent to Tagname2 is a 10 minute average (i.e. the total number of events |
| |collected by the interface divided by 10 minutes). Therefore the IORate will appear to be |
| |zero for the first 10 minutes of interface operation. IORates for individual tags cannot be |
| |measured at this time. |
| |The iorates.dat file must be created by hand. The file should be placed in the \dat |
| |directory. The \dat directory is located in the directory designated by the PIHOME entry in |
| |the pipc.ini file. Normally the PIHOME entry points to the C:\ProgramFiles\PIPC\ directory so|
| |that the iorates.dat file will reside in the C:\ProgramFiles\PIPC\dat\ directory. |
| |Once the iorates.dat file is created, the interface must be stopped and restarted before the |
| |interface begins measuring the IORate. |
| |Although the interface will allow multiple instances of the /ec flag to be specified on the |
| |command line, the rate will only be nonzero for the first rate tag that is referenced. |
|/ER |This parameter defines the requested update rate for the event class group. All event-based |
|Optional |points belong to one group, and the default update rate for the group is one second. If the |
|Default: |OPC server's data cache for event-based tags does not need to be updated that frequently, use |
|/ER=00:00:01 |this parameter. For example: |
| |/ER=00:00:10 |
| |For v2.0 servers, all event reads are done from device, so this value should be set quite |
| |large, /ER=24:00:00, unless there is some other reason to update the cache. |
|/ES |This parameter determines whether event tag reads for v1.0a servers will be from CACHE or from|
|Optional |DEVICE. DEVICE reads should be used with caution, as they can have a tremendously negative |
|Default: |impact on the performance of the OPC server. Please read the section on Configuring Event |
|/ES=CACHE |Tags before using this setting (/ES=DEVICE). |
|/F |This parameter defines the frequency scan class. It determines how frequently the interface |
|Required |requests the data from the server. The format is /F=hh:mm:ss.mmm For example: |
| |/F=00:00:01 |
| |will set the scan frequency at one second. |
| |The interface will support 200 scan classes. The scan classes are numbered in the order |
| |they’re defined, with the first one being scan class 1, the next scan class 2, etc. |
| |The interface supports sub-second scan frequencies, but they should be used with caution, as |
| |very fast scans place a high demand on the system. Sub-second scan times have the format |
| |/F=00:00:00.50 |
| |to indicate a frequency of one-half second. |
| |Performance can be further improved by defining scan offsets as explained in Polling and |
| |Advising section. You can configure the scan offsets by specifying the scan class in the |
| |opcint.bat file as follows: |
| |/F=00:01:00,00:00:30 |
| |The points belonging to this scan class will scan every minute offset by 30 seconds. That is, |
| |30 seconds after the next minute, then 1 minute after that, and so forth. |
| |If you specify |
| |/F=00:01:00 |
| |with no offset, the interface will start scanning whenever it gets around to it. |
| |If you specify |
| |/F=00:01:00,00:00:00 |
| |the interface will start at the next minute. |
|/FM=# |Failover mode. This controls the behavior of the backup interface when using interface-level |
|Default: |failover. The options are: |
|/FM=3 |/FM=1 Chilly: do not create groups on the server |
| |/FM=2 Cool: Create groups inactive, and add tags |
| |/FM=3 Warm: Create groups active, do not advise groups |
| |For more on failover modes, please see the section below on Interface-level Failover |
|/FT |The /FT argument is used in conjunction with /BACKUP argument to specify the failover time. |
|Optional |The interface will keep trying to connect to the current server for this many seconds before |
|Default: /FT=60 |it give up and tries to connect to the other server. The interface will stay on a given |
| |server, once connected, until that server fails, or the watchdog tag(s) indicate that it is no|
| |longer the active server. |
| |This parameter also affects how often the interface will check the server status. If the |
| |failover time (FT) specified is less than 30 seconds, the interface will call GetStatus on the|
| |server every FT seconds. If FT is not specified, or is more than 30 seconds, GetStatus will |
| |be called every 30 seconds. This serves as a watchdog to ensure that the server is still |
| |reachable and responding, and also allows the interface to monitor clock drift between the |
| |systems. Note that this parameter has a large impact on systems using the /WS flag. |
|/GL |Some early v1.0a servers did not format messages correctly, and the interface included a |
|Optional |work-around for them. This is now turned off by default. If you receive the error message |
|Default: /GL=Y |“"OnDataChange:Invalid group ID”, try setting /GL=N to see if that fixes it. If it does, |
| |please email us at techsupport@ to tell us what server you're using. If possible, |
| |email us the pipc.log file and that will tell us what we need to know. |
|/GS |The /GS argument is intended to allow the use of older, non-compliant OPC servers which do not|
|Optional |provide a valid GroupStatus on asynchronous reads. If your log file contains an error like: |
|Default: /GS=Y |"OnDataChange: Header status :" followed by a hexadecimal number, and you are not getting any |
| |data from the interface, you should try using /GS=N to tell the interface to ignore the group |
| |status flags. If you are getting some data, but are also getting this error on some reads, |
| |you should contact the vendor for your OPC server and give them the error number, so they can |
| |help you determine why your OPC server is returning this error indication for the group in |
| |question. |
|/HQ |The /HQ argument sets the upper limit for the internal queue of the interface. The interface |
|Optional |may take in data from the OPC server faster than it can pass it to PI, or faster than PI will |
|Default: /HQ=100,000 |accept data. This data is queued in memory until it can be passed to PI. If the internal |
| |queue grows too large, it can take so much virtual memory that NT becomes unstable. This |
| |queue limit is a safeguard against such behavior. If the internal queue exceeds the HQ limit,|
| |the interface will log the fact that it is exceeding its limits, and it will drop incoming |
| |data until the internal queue has dropped below the low queue limit (LQ). |
| |It is strongly recommended that this value not be changed unless you are willing to lose |
| |incoming data. This parameter is intended for debugging system performance problems. |
|/HOST |/HOST=nodename:X defines the PI Server to which the interface will connect. If this parameter|
|Optional |is not used, the interface will attempt to find the PILOGIN.INI file and use the default |
|Default server defined in |server defined there. For example: |
|PILOGIN.INI |If the interface is installed on a PI3 home node: |
| |/host=localhost:5450 |
| |If the interface is installed on a PI API node and talking to a PI2 server located on CASABA: |
| |/HOST=CASABA:545 |
| |If the intervace is installed on a PI API node and talking to a PI3 server located on PEACH: |
| |/HOST=PEACH:5450 |
|/HS |This flag makes the interface request a cache update rate of 1/2 of the scan rate for the scan|
|Optional |class. If your scan class is 2 seconds, the interface will ask the OPC server to read new |
|Default: /HS=N |values from the device every second, for all the tags in this scan class. This is mostly |
|OBSOLETE |included for debugging problems with servers, since we won't look at the cache any more often |
| |than the scan rate anyway. If the tags are advised, the scan rate is only used to define the |
| |requested update rate for the group, so you'd do just as well to make the scan rate the same |
| |as the requested update rate. |
| |This parameter is obsolete -- use /UR instead. |
|/HWPS |This flag tells the interface to check for Plantscape-specific error codes when retreiving |
|Optional |data values. It specifically checks for an Item error code of 0xE00483FD or 0xE00483FC, and |
| |if it finds either of them, it will attempt to failover to the other OPC server. |
|/ID |/ID=2 defines an identifier. The identifier precedes messages sent to the log so that if more |
|Optional |than one OPC interface is running on the same computer the messages will be associated with |
| |the correct interface. The number specified here will be matched with the Location1 parameter|
| |of all tags in the interface's pointsource. Only tags with matching Location1 will be |
| |recognized. |
| |If /ID= does not specify a number, or specifies 0, the interface will accept all tags with the|
| |correct pointsource, regardless of the value in Location1 of the tag. If you specify a |
| |numeric value for /ID=, the interface will only accept those tags that have the correct |
| |pointsource and that numeric value in Location1. |
|/IF |The /IF flag tells the interface to ignore the first value sent for each point. This is to |
|Optional |accommodate those servers that send a response when the interface connects to a point: some |
|Default: /IF=N |servers send a value back, regardless of whether or not they have a valid value, and neglect |
| |to send a status that would indicate that the value is invalid. This generally manifests as |
| |odd-looking values showing up whenever the connection to the OPC server is established or a |
| |point is edited. To get rid of the false values, set this flag to /IF=Y. |
|/IS |This flag tells the interface to ignore the server status returned by the OPC server, as far |
|Optional |as determining the appropriate actions to take. All servers should return |
|Default: /IS=N |OPC_STATUS_RUNNING |
| |when they're ready to add groups and items and return values, but some broken servers do not |
| |do this. If your interface hangs on startup, and the PI_OPCTool shows something in |
| |Server current state = |
| |that isn't "RUNNING", you should use this flag, and report the problem to your OPC server |
| |vendor. |
|/IT |For performance reasons, some users may wish to discard the subsecond portion of the |
|Optional |timestamps being passed to PI and only send whole integer seconds. This will mean that PI |
|Default: /IT=N |will require less space, and possibly less CPU, to store the same amount of data. The |
| |fractional part of the second is simply truncated. To use this, set /IT=Y. |
|/LQ |The /LQ argument sets the lower limit for the internal queue of the interface. If the internal|
|Optional |queue has exceeded the HQ limit, the interface will drop incoming data until the internal |
|Default : /LQ=80,000 |queue size has dropped below the low queue limit. |
| |It is strongly recommended that this value not be changed unless you are willing to lose |
| |incoming data. This parameter is intended for debugging system performance problems. The LQ |
| |cannot be set to less than (HQ - 100). |
|/MA |By default, the interface will add one item at a time to its groups. This guards against |
|Optional |ill-behaved servers that will reject an entire group if one item is invalid. The Mass Add |
|Default: /MA=N |flag tells the interface to add all the items in a class at the same time. If your OPC server|
| |allows it, you should use /MA=Y. If this causes lots of tags to be rejected by the server, |
| |remove the /MA flag at least until you determine which tag is the problem. |
|/MAXSTOPTIME |The interface ordinarily gets 120 seconds to close its connections and exit cleanly. If your |
|Optional |server requires more time, use this parameter. |
|Default=120 | |
|/NI |The /NI argument specifies the number of instances of the interface running on the node. This |
|Optional |switch is used in conjunction with /FT switch to specify how long the interface is to wait |
|Used in conjunction with /FT if |until it initiates a server-level failover. This gives the multiple interfaces extra time to |
|multiple instances of the |DCOM timeout in case a DCOM call made to the server doesn’t return in time because the server |
|interface are running on the same |is busy servicing requests from other interface. |
|node. | |
|/NT |The /NT=Y flag tells the interface to never write IO Timeout when it loses the connection to |
|Optional |the OPC server. You will almost always want to have IO Timeout written to the tags at those |
|Default=N |times, but the ability to turn it off is included for very special circumstances. |
|/OPCSTOPSTAT |This is where you can specify that a digital state should be written to each input tag when |
|Optional |the interface is shut down, so show that data collection was stopped. If you don't specify a |
| |digital state, the interface will use "IO Timeout", but you can specify any state in the |
| |System State Set. Most sites will probably find this useful. |
|/PISDKCONTIMEOUT |Set the timeout for PISDK calls. The parameter is the number of seconds to wait before timing|
|Optional |out. The default is 15 seconds. |
|/PR |The /PR argument specifies if interface-level failover is to be supported. If no |
|Optional. |interface-level failover is needed, this argument is not needed. If i/f failover is needed and|
|Required for interface level |the interface is to be the primary interface set this argument to /PR=1. If this interface is|
|failover |to be the secondary interface set it to /PR=2. |
|Default: /PR=0 | |
|/PS |The point source is defined by /PS=pointsourcechar where pointsourcechar is the character used|
|Required |by the interface tags. For example: |
| |/PS=G |
|/QT |This allows you to define a PI tag which will receive the count of how many items the |
|Optional |interface has queued up to go to PI. Under normal conditions, this number should be fairly |
|Default: none |low and fairly steady, but if PI is slowed down by other processing or if the OPC server sends|
| |a large burst of data, you may see it jump. The tag should be an integer tag (Int32 for PI3),|
| |set up for manual input as though it was a lab tag. |
|/RD |This specifies how many seconds to wait before trying to reconnect to the server, if we get an|
|Optional |error indicating that the RPC server is unavailable or busy (0x800706ba or 0800706bb). |
|Default: not active |Note that this option causes the interface to abandon the connection without cleaning up |
| |first. That’s a bad idea, in general, so don’t use this option unless you have no choice, and|
| |then only while you figure out why you’re losing the RPC server. |
|/RN |The /RN argument specifies the resource number if there are to be multiple instances of opcint|
|Optional |running (with different service names) on the same machine in conjunction, each dependent on a|
|Required for interface-level |uniquely-named resource, apionline#. /rn=1 will indicate that the interface is to depend on |
|failover when multiples instances |apionline1 (i.e. will look for the service named apionline1), /rn=2 will indicate that the |
|of opcint are running on the same |interface is to depend on apionline2, and so forth. See Interface-Level Failover section for |
|node. |more detailed explanation. If interface-level failover is to be supported and this number is |
| |negative (/RN=-1), the cluster resource name is assumed to be apionline without the suffix #. |
|/SERVER |The OPC Server to be used is defined with this command line parameter. Use the following |
|Required |format: |
| |/SERVER=FACT1NODE::MODBUSOPC |
| |where FACT1NODE is the name of the computer where the OPC Server will run, and MODBUSOPC is |
| |the name of the OPC Server as registered on that machine. If the server will be running on |
| |the same machine as the interface, the nodename must be omitted: |
| |/SERVER=MODBUSOPC |
| |If your server name has embedded spaces, you will need to enclose the name in double quotes |
| |(see the beginning of this section, where it says that there can be no spaces within any |
| |parameter): |
| |/SERVER="Server name with spaces" |
|/SIN |The /SIN argument specifies the name of the secondary interface’s node when i/f failover is to|
|Optional |be supported. You must specify the same secondary interface node in the startup files for |
|OBSOLETE |both the primary and secondary interfaces. |
|/SN |The /SN argument indicates that exception reporting is to be turned off and all data should be|
|Optional |sent to the snapshot. Use only for testing. |
|/SQ |For "uncertain" qualities, the interface will normally store the value, and only flag it as |
|Optional |"uncertain". Setting this flag to /SQ=Y will cause the interface to store the quality rather |
|Default: /SQ=N |than the value if the quality is anything except GOOD. Setting this flag to /SQ=I will cause |
| |the interface to ignore the quality information, and treat questionable quality as GOOD. BAD |
| |quality will still result in a digital state code being sent to the archive. |
|/ST |This allows you to define a PI tag that will get the status of the OPC server. This should be|
|Optional |a digital state tag, set up for manual input as though it was a lab tag. The possible values |
|Default: none |are: |
| |1 = OPC_STATUS_RUNNING |
| |2 = OPC_STATUS_FAILED |
| |3 = OPC_STATUS_NOCONFIG |
| |4 = OPC_STATUS_SUSPENDED |
| |5 = OPC_STATUS_TEST |
| |Note that if the server returns anything other than above, a 0 will be sent to PI, and if only|
| |above are defined as the states in the digital set, OPC_STATUS_RUNNING will be archived, since|
| |it will be the 0th state. Therefore user should define a state other than above as the 0th |
| |state in the digital set. |
| | |
| |To specify the PI tag that will be used to write the status to, the form is: |
| | |
| |/ST=PI_TAG |
| | |
| |Where PI_TAG is the name of the PI tag setup for the OPC server status. |
|/SW |Status wait. Even with server-level failover enabled, once the interface has successfully |
|Optional |connected to the server, it will wait forever for the server to enter RUNNING status, or drop |
|Default: none |the connection. You can use this switch to limit the number of seconds that the interface |
| |will wait for the server to enter RUNNING state. The parameter is the number of seconds which|
| |the interface should wait. |
| |/SW=5 |
|/STARTUP_DELAY |If your interface is installed for autostart, but it hangs when the machine reboots, you may |
|Optional |need to give the network layer time to get settled before trying to use it. This parameter |
| |will make the interface sleep for # seconds before trying to actually do anything. The basic |
| |form is |
| |/STARTUP_DELAY=# |
| |where # is the number of seconds to wait. |
| |/STARTUP_DELAY |
| |will cause a 30-second delay. |
|/TF |This argument allows you to specify the format of timestamp strings. The setting will be used|
|Optional |for tags with Location2 = 6 or 7, where the OPC Item is either a string that contains a |
| |timestamp, or a VT_DATE value, and also for writing output timestamps using TIM= in the ExDesc|
| |field. See the sections above on Location2 settings, Datatypes, and ExDesc for more |
| |information. The Datatypes section gives example format strings. |
| |Format: valid tokens are |
| |cc yy mn mon dd hh hr mm ss 000 XM |
|/TO |Timestamp Offset. This parameter allows you to apply an adjustment to the timestamps, to deal|
|Optional |with broken servers and broken installations, where the clock for the OPC server is set |
| |incorrectly (for example, the server requires the clock to match the wallclock, but the |
| |Timezone must be GMT, regardless of where the server is actually located). This should not be|
| |used if you have a properly working server. The format is the same as that of the scan period|
| |parameters (/F), but may be optionally preceeded by a negative sign. |
| |Format: |
| |/TO=01:00:00 |
| |/TO=-03:00:00 |
| |/TO=00:45:00 |
|/TS |This flag determines whether the interface expects to get timestamps for the data from the |
|Optional |interface, or whether it will timestamp the data when it receives it. Some OPC servers are |
|Default: /TS=N |able to provide the timestamp for when they read the data from the device, while others are |
| |not. If your server is able to provide valid timestamps, use |
| |/TS=Y |
| |If your server can provide valid timestamps only for advised tags, use |
| |/TS=A |
| |If you need to store times without having them adjusted to the PI server clock, use |
| |/TS=U |
| |This setting can cause your data to be lost, if your clocks are set incorrectly. Please see |
| |the section on Timestamps before using this setting. |
|/UR |The /ur argument sets the requested update rate for the group. This argument is positional, |
|Optional |like the /f scan period argument. The update rate will be applied to the scan period it |
| |follows. Thus, if you have /f=00:00:02 /f=00:00:03 /ur=00:00:00.5 /f=00:00:01, you get scan |
| |class one with period=2 seconds, ur=2 seconds, class 2 with period=3 seconds, ur=0.5 seconds, |
| |and scan class 3 with period=1 second, ur=1 second. |
|/VN=1 |The /VN argument is used to tell the interface that the OPC server uses OPC v1.0a. If this |
|Optional |argument is not used, the interface will try to communicate using OPC v2.0, and will fall back|
| |to v1.0a if v2.0 does not succeed. |
|/WS |Once the interface connects to a server that enters the RUNNING state, it will stay connected |
|Optional |until the server disconnects, the watchdog tag(s) indicate that this is not the active server,|
| |or the interface is shut down. If you want the interface to disconnect from the server if the|
| |server leaves the RUNNING state, set this flag to |
| |/WS=1 |
| |By default, the server status is checked every 30 seconds. You can adjust this to be more |
| |frequent by using the /FT parameter to specify the failover time. |
|/WD1 |The /WD1 and /WD2 arguments can be used if the redundant OPC servers return OPC_STATUS_RUNNING|
|/WD2 |status when in backup mode as well as in primary mode. Please see the section on Watchdog |
|Optional |Tags for more information. |
|Needed with some servers for | |
|server-level failover. | |
|/WQ=# |This setting directs the interface to fail over to the other server if a watchdog tag has |
|Optional |anything but GOOD quality, or if there is an error on reading the item. Note that v1.0a |
|Needed with some servers for |servers do not return error codes for individual items, so for version 1.0a servers this flag |
|server-level failover. |only checks the quality of the value sent from the server. |
| |/WQ=1 |
Interface Operation
OSI recommends that interfaces be installed on API nodes instead of directly on the PI server node. An API node is an NT or UNIX node other than the PI Server node where the PI Application Programming Interface (PI-API) has been installed (see the PI-API Installation Instructions manual). The PI server should not need to compete with interfaces for CPU time. The primary function of the PI server is to archive data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the API node (once again, see the PI-API Installation Instructions manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI server, allowing continuous data collection when communication to the PI server is lost. Communication will be lost when there are network problems or when the PI server is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on API nodes should be installed as automatic services, except during the initial testing period where it is recommended to run the interface interactively to simplify troubleshooting. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI server node. In this case, the typical scenario is to install the PI server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI server node.
No More Password File
With the introduction of PI version 3.3, you should begin using trust relationships to secure your data. Rather than creating a password file, and a proxy for the interface within PI, you will use the PI trust database. Please refer to the PI Data Server manuals for how to set up a trust relationship for your interface.
For users who are not yet using PI 3.3, you can still run the interface interactively to set the password to be used by the PI SDK. If you change the password on the account, you will need to delete the opcint.pwd file, which will be in the interface directory, and run the interface interactively again, to set the new password.
Installing the Interface as a Service
While the installation script will install the interface as a service, if you need to uninstall it or change the installation, you can do this easily. Open a Command Prompt window, and change to the directory that contains opcint.exe and opcint.bat. To uninstall the service, type
>opcint -remove
To install it as a service, type
>opcint -install
To install it as a service that will automatically start when the system starts, type
>opcint -install -auto
If (as is likely) the service needs to wait for one or more other services to be started before it starts, you'll need to know the names of the services it should wait for. One common one would be tcpip, another would be bufserv (the PI API buffer service for API nodes). Another that some customers have needed to specify would be RpcSs, the RPC service. To have the service wait for those three services before starting, type
>opcint -install -auto -depend "tcpip bufserv RpcSs"
You can specify that the interface is dependent on any service you choose, just put a space between the names and enclose the entire set in double quote marks. Remember that this only determines the order in which services are started when the system comes up, it has no impact on what happens after that. So if your interface is dependent on bufserv, and you've taken down both bufserv and the interface, starting the interface through either the Control Panel or from the command line will not start bufserv.
Removing and reinstalling the service only changes registry entries, so if you are unsure what dependencies you have set, it is generally safe to remove and reinstall the service. Or, you can find the actual registry entry under
"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\opcint".
You can use the Control Panel/Services to change the auto-start setting, but you cannot change the dependencies through the Control Panel.
Installing Debug Symbols
The install kit will automatically install the debug symbols to directory
%SystemRoot%\Symbols\exe
Service Control Manager can use the symbols contained in this file to match Dr. Watson dumps with the extracted symbol information. This directory is usually created by the PI 3.2 installation program. If it does not exist, however, the user should create it. Our install program will copy this file to the appropriate directory if it exists, but if it does not the user needs to create it. After it has been created, the debug symbol file can be manually copied over to %SystemRoot%\Symbols\exe directory. Dr. Watson is installed as the default debugger by typing drwtsn32 –i at command prompt.
To test if the symbols are correctly installed, user can induce an application crash by typing the following at command prompt in the directory where the interface is installed
opcint –crash
after the interface is installed as service as explained in the previous section. In %SystemRoot% directory (\winnt directory under winnt) there will be drwtsn32.log. This file will contain a series of opc function calls made around the time of the crash. Of course, we hope to never have to use this useful tool.
If this interface is being installed using the installation kit (available from version 2.08 or higher) the debug symbol file is automatically installed in the correct directory. However, drwtsn32 still needs to be set by the user in order for drwtsn32 to act as the default debugger.
Startup/Shutdown
The OPC Interface, if run as a service, can be started and stopped from the Service manager in the Control Panel. It can also be started or stopped from a console window by typing "opcint -start" or "opcint -stop" (if you're not in the opcint directory, you'll need to specify the entire path to the file), or by using the standard service commands, "net start opcint" and "net stop opcint" in a command window.
To run the interface interactively, you can just double-click on the opcint.bat file, or open a Command Prompt window and type "opcint" (if you're in the same directory as the opcint.bat and opcint.exe files), or type the complete path to the opcint.bat file, like "c:\pipc\interfaces\opcint\opcint.bat".
Editing Tags While the Interface is Running
The interface will perform tags edits while it is running, so that you don't need to shut it down to update the tag configuration information. However, as with most PI interfaces, the interface will only process so many tag edits at a time. In general, the interface will check for tag edits every 2 minutes. If it finds that at least 25 tags have been edited, it will check again in 30 seconds, otherwise it will wait another 2 minutes before checking again. Also, the edits are performed in the simplest way -- we delete the tag from the interface and then add it in again. With some servers, that operation can require quite a bit of time and resource.
Therefore, if you are editing very many tags, you will probably find it faster and more efficient to restart the interface after all your tags have been edited.
Logging Messages
The OPC Interface will send the following information to the log file:
1. Informational messages on startup and shutdown
2. The scan rate for each class, and the actual update rate provided by the OPC server. For polled tags, the scan rate is how often we ask the OPC server for the current values. The update rate is how often the OPC server will read the value from the device. The OPC server may provide an update rate which is different from the scan rate.
3. A count of the points in each scan class, a count of the output points, and a count of the advised tags and event tags.
4. Error messages for points rejected by the server, or error messages sent from the server
5. Notification for all connections and disconnections from the server (if the connection with the OPC server is lost, the interface will attempt to reconnect)
Connecting to OPC Server
The OPC Interface maintains its connection to the OPC server and to PI automatically. While connected, it periodically checks its clock against that of the OPC Server and against that of PI, to take care of slight differences in clock speeds. But more importantly, this action also provides positive feedback to the interface that the OPC server is still up and running, even if all points are configured for advise and no data has come in for some time.
If the OPC Server does go out of reach, the interface will periodically try to reestablish the connection. Once the connection to the OPC Server is regained, the interface will recreate its groups and items on the server and resume data collection.
Using PI-API Buffering
To use API buffering with the OPC interface, you must have version 1.3 or higher of the PI API. This is because earlier versions of bufserv did not support extended API calls, which the interface uses. If you are having problems getting the interface to work with buffering, first make sure that it works without buffering installed, then try adding the buffering function.
Configuring DCOM: The Basic Steps
Your server should have instructions on configuring DCOM, and if possible you should just do what your server documentation says. But just in case that doesn't work, here's the short version of how to get data moving. Press the Start button, then select Run, type in "dcomcnfg" and press OK. This will bring up the DCOMCNFG window. There are slightly different versions for different systems (NT, W2K, XP), and for different SPs. The important things:
Check the box to enable DCOM.
Under "Default Properties", set the Default Authentication level to "Connect". Set the Default Impersonation Level to "Identify".
Under "Default Security", edit the Default Access Permissions. Grant Access to INTERACTIVE, SYSTEM, NETWORK, and to whatever user your interface will run as. Edit the Default Launch Permissions, and grant Launch permissions to the same users.
Under the Applications tab, find your OPC server and check its properties. Under the Security tab, if it uses Custom Permissions, Edit those permissions to grant Access and Launch permission to the same users as above, INTERACTIVE, SYSTEM, NETWORK, and the interface account.
Under the Identity tab, check the user that the OPC server will run as, and make sure *that* user has been given permission to Launch and Access DCOM applications on the Default Security page. In general, running the server under the Interactive User account seems to work well with NT4 SP3, and running under the Launching User works well under NT4 SP4, but specifying a given account which has permissions seems to work best. Running the server under the local system account will not work for DCOM, as the local system account has no permissions outside the machine.
The main point is that services run under the INTERACTIVE account, or at least they require that account to have permissions before they can connect using DCOM. After changing DCOM permissions, you may need to restart your OPC server if it's running.
More detailed description can be found in "DCOM Configuration: The Details", below.
Configuring Tags
Scan Classes
Scan classes are defined in the opcint.bat file. Each /F= parameter defines a scan class, which we number in order, so if your .bat file has
/F=2 /F=1:00 /F=1:30:00 /F=00:00:05
then you have defined these scan classes
Scan Class 1 has scan period 2 seconds
Scan Class 2 has scan period 60 seconds
Scan Class 3 has scan period 5400 seconds (90 minutes)
Scan Class 4 has scan period 5 seconds
Remember that the first scan class is reserved for Advise tags. All other scan classes can have either advise tags or polled tags, and you can have as many classes for each type of tag as you need (as long as your server supports that many groups).
Configuring Polled Tags
Polled tags are read once every scan period. To set up a polled tag, you must set Location1 to match your /ID parameter, Location3=0, and Location4=scan class number.
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|FiveSec.PV | |ItemID1 |1 |0 |0 |4 |0 |0 |0 |
|OneMin.PV | |ItemID2 |1 |0 |0 |2 |0 |0 |0 |
|NinetyMin.PV | |ItemID3 |1 |0 |0 |3 |0 |0 |0 |
Configuring Advise Tags
For Advise tags, we just ask the OPC server to send us data when it changes, and we tell it how often it should read the device to see if there's a new value. The scan period or requested update rate (/UR) sets that time span.
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|AdvFiveSecs.PV | |ItemID1 |1 |0 |1 |4 |0 |0 |0 |
|AdvOneMin.PV | |ItemID2 |1 |0 |1 |2 |0 |0 |0 |
|AdvNinetyMins.PV | |ItemID3 |1 |0 |1 |3 |0 |0 |0 |
Note that the same opcint.bat settings can be used for either polled or advised tags, but if you wanted to use both of these sample configurations, you would need to add another three scan periods, and use the first set for either advises or polls, and the second set for the other tags. So you would have
/F=2 /F=1:00 /F=1:30:00 /F=00:00:05 /F=2 /F=1:00 /F=1:30:00 /F=00:00:05
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|FiveSecond.PV | |ItemID1 |1 |0 |0 |4 |0 |0 |0 |
|OneMinute.PV | |ItemID2 |1 |0 |0 |2 |0 |0 |0 |
|NinetyMinute.PV | |ItemID3 |1 |0 |0 |3 |0 |0 |0 |
|AdvFiveSecs.PV | |ItemID1 |1 |0 |1 |8 |0 |0 |0 |
|AdvOneMin.PV | |ItemID2 |1 |0 |1 |6 |0 |0 |0 |
|AdvNinetyMins.PV | |ItemID3 |1 |0 |1 |7 |0 |0 |0 |
Configuring Event Tags
Event tags are only read when the triggering event occurs. An event happens when the PI snapshot receives a value for the trigger tag. It may have the same timestamp and quality and value as the last event, and so the snapshot value for that trigger may seem the same, but the act of receiving a value for the trigger tag causes the interface to receive a notification that the trigger has been updated.
Many event tags can use the default configuration: set Location4=0, and set the name of the trigger tag in the ExDesc field ("TRIG=triggertagname"). The default update rate for event groups is 1 second, so the server will be asked to update its cache every second for every event tag defined. That's probably faster than is necessary. Especially if you have a server that uses the OPC v2.0 standard; in v2.0, all asynchronous reads are done from the device, so updating the cache is essentially wasted effort. If you have a v2.0 server, you should set the event rate (/ER in opcint.bat) to something much higher, perhaps 8 hours. Even if you have a v1.0a server, where asynchronous reads are from the cache, you probably don't need to have the cache updated that often for all your event tags.
You use UserInt2 to specify in which event group an event tag belongs. The parameter does nothing else, it is only an instruction to the interface as to which tags get read together. All values for a single read must be returned at the same time, so grouping has different effects on different servers. Also, a plug-in DLL that does post-processing of data before the data is sent to PI may require that a set of data be processed as a complete set, and so all the tags that make up that set must be in the same group.
For v1.0a servers, it is useful to separate event tags into groups based on the triggering event. This is the most efficient mode.
For v2.0 servers, it's probably more important to separate event tags based on where the data actually comes from. The v2.0 standard requires that all asynchronous reads be read from the device, rather than from the server's cache, so you should set the cache update rate very high, and most important, you should try not to have an event group contain values that come from different devices.
|Tag |exdesc |instrumentt|loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
| | |ag | | | | | | | |
|PM1_Temp.PV |TRIG=PM1_Trigger |ItemID1 |1 |0 |0 |0 |0 |0 |1 |
|PM1_Rate.PV |TRIG=PM1_Trigger |ItemID2 |1 |0 |0 |0 |0 |0 |1 |
|PM2_Temp.PV |TRIG=PM2_Trigger |ItemID3 |1 |0 |0 |0 |0 |0 |2 |
In this case, PM1_Trigger and PM2_Trigger are tags that are updated from somewhere, either by this interface or another or by manual entry. When PM1_Trigger gets a new event in the PI snapshot, the interface will send the OPC server one read command, which requests data for both PM1_Temp.PV and PM1_Rate.PV. Both values will be returned in a single call. Likewise, when PM2_Trigger gets an event in the snapshot, the interface will request a value for PM2_Temp.PV.
Configuring Array Tags
The interface can read data from an OPC server as an array, and store the data into separate PI tags. The array is a valid OPC datatype, but PI itself only knows about individual tags. So, to configure tags for an array, you must use the ItemID of the array item as the instrumenttag for all the array tags, and use UserInt1 to indicate the index number within the array for each tag. Thus, if your array item has 100 values in it, you would configure 100 tags, all with the same instrumenttag, and the tag with UserInt1=1 will get the first value in the array, the tag with UserInt1=2 will get the 2nd value in the array, etc. Only the tag with UserInt1=1 will actually cause the interface to do anything -- the others must belong to the same OPC group, and so they must have the correct pointsource and Location1 and Location4 (and UserInt2, if they are event tags), but they will be ignored in normal processing.
While you can have as many tags as you like that all point the the same ItemID or the same array member, you must not have more than one set of tags in a scan class that points to a given array. This is due to the way that the interface processes arrays. For a given ItemID, which represents the array, the interface expects to only find one tag for each member of the array. So if you need to read the same array item more than once, you will have to have each tag that points to that array item in a different scan class.
It's also important to not put more than one array in a scanclass or eventclass unless the arrays are quite small. If your array is large, say 300 or more tags, then you do not want to have two arrays sharing the same class, and you really don't want a lot of other tags in the class with the array. You can have up to 200 scan classes, and up to 32000 event classes, although your OPC server would probably be pretty unhappy with that many groups. Again, you can have many scan classes with the same scan period, and event classes are just a logical grouping of tags, so putting arrays into their own classes with just the other tags that need to be read with the array is efficient and makes it easy to keep track of what tags are read as a set.
For Advise tags, that is enough; you would set Location3=1 for all the array tags, and set Location4 to the same value for all the array tags.
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|ArrayTag0001.PV | |Data.Array |1 |0 |1 |3 |0 |1 |0 |
|ArrayTag0002.PV | |Data.Array |1 |0 |1 |3 |0 |2 |0 |
|ArrayTag0002.PV | |Data.Array |1 |0 |1 |3 |0 |3 |0 |
For polled array tags, you would set Location3=0 for all the array tags, and set Location4 to the scan class for the array.
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|ArrayTag0001.PV | |Data.Array |1 |0 |0 |4 |0 |1 |0 |
|ArrayTag0002.PV | |Data.Array |1 |0 |0 |4 |0 |2 |0 |
|ArrayTag0002.PV | |Data.Array |1 |0 |0 |4 |0 |3 |0 |
For event tags, it's a little more complicated.
Configuring Arrays as Event Tags
The most complicated configuration is to have arrays that are read as event tags. Since only the first array item (with UserInt1=1) actually causes a read, it's actually most efficient to create a dummy trigger tag to use with the rest of the array items. That tag should have a pointsource that is unused or which is used for manual entry tags (lab data usually is entered manually, so often "L" is used as the point source for manual entry tags). If we call the read trigger tag TriggerTag, and call the dummy trigger tag DummyTrigger, then our array tags might look like this:
|Tag |exdesc |instrumenttag |loc1 |loc2 |loc3 |loc4 |loc5 |userint1 |userint2 |
|Array0001.PV |TRIG=TriggerTag |Data.Array |1 |0 |0 |0 |0 |1 |1 |
|Array0002.PV |TRIG=DummyTrigger |Data.Array |1 |0 |0 |0 |0 |2 |1 |
|Array0003.PV |TRIG=DummyTrigger |Data.Array |1 |0 |0 |0 |0 |3 |1 |
Since all the tags within one array must belong to the same group, even if you have a v2.0 server and some part of the array data comes from a different device than the rest of the array data, you still must configure all the array tags to be in the same event group.
Reading Basic Quality as a Digital Tag
We’ve already shown how to read the quality of a value rather than reading the value itself, and we’ve also seen how to use transformations and scaling to adjust the value read. You can combine these two options to end up with a PI tag that corresponds to the quality of the item, translated into a simple digital set of Bad Value, Questionable Value, Invalid Value, and Good Value. To do this, you need to create your digital tag, and your digital state set with states Bad, Invalid, Questionable, and Good (in that order), and set the tag to use that digital state set. Then set Location2 = 4, to tell the interface to read the quality rather than the value of the item. Lastly, you need to set up a transformation to mathematically translate the quality values into one of those three values (0, 1, 2, or 3).
All you really need to do here is divide the quality number by a conversion factor, and you will get the proper number, since the values are defined to be within ranges. If you look at the possible values for the quality, you’ll see that the ranges are
Less than 0x40 Bad Value
At least 0x40 but less than 0x80 Questionable Value
At least 0x80 but less than 0xc0 not used by OPC
At least 0xc0 Good Value
and each range has a size of 0x40. So you use that as your conversion factor, and you don’t need to use an offset at all. Looking at the table of available conversions, we find
|Convers |TotalCode |SquareRoot |DZero |Operation: |
|Not 0 |3 |0 |Defined |Input tags: |
| | | | |Value = (Value / Convers) – DZero |
| | | | |Output tags: |
| | | | |Value = (Value + DZero) * Convers |
So here we need to set our tag to have
Convers = 64 (decimal value for 0x40)
Totalcode = 3
SquareRoot = 0 (this is the default)
ExcDesc = “DZero=0” (this can be combined with other options in the ExcDesc field)
OPC Server Issues
The OPC specification allows a great deal of flexibility in how OPC servers are designed, and in what features they will support. This is an outline of how that may affect users of this interface.
Browsing
Point browsing is not a requirement of the OPC specification. If your OPC server does not support browsing, you must have access to a list of the points which it will accept, or the format of point names it will allow you to use. If browsing is allowed, you can use PIOPCTool to see the points which your OPC server recognizes.
Timestamps
There has been much discussion of what the timestamp value should be, when the OPC server sends one with the data. Some vendors send the timestamp for the last time the data value and quality were read from the device (so the timestamp will change even if the value does not). Others send the timestamp of the last read where the value or quality changed, so if the data remains the same, the timestamp will not change no matter how many times, or in what way, you read it. If your OPC server sends timestamps for when the data last changed, you should use the /TS=N flag in the startup command file.
Disconnecting
If your interface disconnects improperly from an OPC server (like if your network connection goes down, or your NT system crashes), the server may not clean up the connection on its side. The symptoms for this will probably be that the interface cannot reconnect with the server. You can use the PIOPCTool to verify that this is occurring, and the solution will probably be to shut down the OPC server. Refer to the documentation which came with your server to see if they address this issue. If not, try shutting down the server, or, if you understand NT and the programs you’re running on that machine quite well, use Task Manager to kill the thread. If in doubt, reboot the machine. This is not a problem which can be resolved by a change in the interface: once the connection is broken, we have no way to tell the server that it needs to clean up its act.
False Values
Some OPC servers will return a value when a client connects to a point, even if the server does not have a valid value for the point yet. When the server also sends a proper status, this is not a problem, but some servers will send a false value and a status of GOOD, which results in the false value being sent to the PI archive. You would see those values in the archive at times which correspond with the interface starting, or getting reconnected to the OPC server, or when a point was edited while the interface was running. To prevent these values, you should use the /IF flag in the opcint.bat file. This will result in the interface dropping the first value received from the OPC server for each point, each time the interface connects to the point.
Access Path
The Access Path is a suggestion for how the server might want to get to the data. It is not part of the ItemID, and the server is not required to pay any attention to it. However, the server is also not allowed to require it. If your server requires it, your server is broken.
Some servers, such as RSLinx, require the information about how to access the data, and look for this information either in the Access Path or as part of the ItemID. For instance, RSLinx servers use the format
[accesspath]itemid
Other servers may use other formats. It's perfectly valid for servers to require path information in order to access a value. It's just not legal for them to require that it be sent in the Access Path field. If your server requires path information, and will only accept it in the Access Path field, you need to contact your server vendor.
Interface Installation
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is ifc.exe and that the startup command file is called ifc.bat. If the actual name of the interface is “Random,” one should substitute Random for ifc in the installation procedure below.
It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use ifc1.exe and ifc1.bat for interface number 1, ifc2.exe and ifc2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a file that has the same root name as itself.
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSI recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
If multiple copies of the interface are to be installed, you will need a separate interface directory for each copy of the interface. If the convention is followed, it is recommended to place ifc1, ifc2, ifc3, etc., in the directories:
PIHOME\interfaces\ifc1\
PIHOME\interfaces\ifc2\
PIHOME\interfaces\ifc3\
and so on.
The installation kit will create the directories for you as well as renaming the opcint.exe and opcint.bat files.
Plug-Ins Directory
There are plug-in dlls which do post-processing for specific applications. These contain application logic which is not suitable for inclusion in the interface itself, as it is specific to a given server and usage, but which is used by more than one customer. The dlls, their supporting files, and the documentation for their usage are all installed into a subdirectory below the interface directory called Plug-Ins.
OPCEnum Directory
The OPCEnum tool is mentioned elsewhere in this document. The executable and the files needed for using it on another machine are installed into a subdirectory below the interface directory called OPCEnum.
Tools Directory
Various tools are included in the installation, most prominently the PIOPCTool itself. These are installed into a subdirectory below the interface directory called Tools.
Security
If the home node is a PI 3 server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive Manual.
If the home node is a PI 3.3 server, or higher, then you will need to establish a trust relationship for the interface. Again, see the PI archive manual for how to do that.
If the home node is a PI 2 server, the read/write permissions should be set appropriately in the pisysdat:piserver.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 2 or PI 3 server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. See the section “Error and Informational Messages” for additional information on error messaging.
Interface Checklist
The OPC interface comes with an installation application. Executing the application will copy the necessary files to your hard disk and install the interface as a service. However, you will still need to edit the startup parameters. Alternatively, you can install and use the PI Interface Configuration Utility (PI-ICU) if you're using PI3 version 3.3 or higher, and we do recommend that you use the ICU if you can. It makes configuration much simpler.
In the installation process, you are given the opportunity to specify where to install the interface files. If you took the defaults, the directory is opcint. If you specified another directory, everywhere that this manual says "opcint", you should insert the name of the directory you specified. If your directory name has spaces embedded, as in "OPC for PI", you'll have to enclose it with double quotation marks. In your installation directory there will be a sample command file OPCInt.bat (there's your first substitution, if you used another directory). For information on how to configure this file, see Software Configuration: Command-line Parameters.
To run the OPC Interface:
1. Define the point source (PI 2)
2. Create Digital States
3. Check the DCOM configuration, and add permissions as necessary.
4. Use PIOPCTool to verify connection to the OPC server and data collection for at least one tag. Use Refresh to make sure we can read asynchronously.
5. Edit OPCInt.bat. Use the server name you used for PIOPCTool.
6. Create interface points
7. Add your PI server to the Connections table in PI-SDK, using AboutPI-SDK.exe.
8. Start the interface interactively
Once you have confirmed that the interface runs interactively, you should verify that it works as a service. Check the Microsoft Windows NT services control panel to verify that the service was added successfully. You can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
The service can be started from the services control panel or with the command:
opcint.exe -start
or with the command
net start opcint
A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, you should make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. For one, the service may not be able to find the command-line arguments in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section “Error Messages” for additional information.
If the interface runs interactively but cannot connect to the server when run as a service, it's almost always a DCOM permissions problem, recheck your dcomcnfg settings.
The service can be stopped at any time from the services control panel or with the command:
opcint.exe -stop
The service can be removed by
opcint.exe –remove
Upgrading an Installation
If you already have an earlier version of the OPC Interface installed, and you're upgrading to the newer version, you will need to uninstall the version you now have. You can do that from Control Panel\ Add/Remove Programs. The interface installation will not let you install a new version over the top of an existing installation. You can install a new version into another directory, and you can have multiple installations on one computer; the installation will use the directory name (the last portion) as the name of the service. If you already have the interface installed into c:\pipc\interfaces\opcint, you can install the new version into c:\pipc\interfaces\opcint2, and your Services list will show both opcint and opcint2. You can then uninstall the opcint version when you're ready to do so. If you are uncertain about upgrading, installing the new version into a separate directory will make it easy for you to test out the new version before moving all your data collection over to it. Don't forget to uninstall the old version when you've got the new one working properly.
Common Problems
The vast majority of problems in getting the interface installed and collecting data are in getting COM/DCOM set up. Don't even bother trying to run the interface until you can use PIOPCTool to connect to your OPC server, create a group, add points, and read values using either Refresh or Advise. If you can read values with SyncRead but not with either of the other methods, you almost certainly have DCOM permissions, probably on the machine on which the interface is running. Go back and check your DCOM settings on that machine, and check the userid under which the OPC server is running.
If you have trouble running the interface as a service, try running interactively: open a Command window, change to the directory where you installed the interface, and run it by typing "opcint.bat". Make sure you're logged in as the right user. If that doesn't work, you should at least get some messages that will help you figure out what's wrong (see the list of error messages below).
If you can run interactively but not as a service, check the Event Viewer (Start button/Programs/Administrative Tools/Event Viewer) to see if there are messages about DCOM; that would indicate a permission problem, or a registration problem. The PIOPCTool program uses the same code as the interface itself, so if you can talk to your OPC server with the tool you should be able to talk to it with the interface. Also, check your DCOM permissions. Make sure you aren't trying to install the service to use files that reside on a logical disk: if you have created a logical mapping of part of your disk drive, for example if your C:\Program Files\pistuff directory is shared as PISTUFF, and you map drive P:\ to PISTUFF, then install the interface on P:\, you're likely to have problems. The same for your OPC server, you can't use logical drive mappings when you register the server.
If you're getting "error -11049" in your pipc.log file, and you're not getting data, check the timezone and Daylight Saving Time settings for your PI server and your interface machine, and try setting them to the same values. If you're using /TS=U, check the time reported by the OPC server machine -- it will also have to be in the same timezone with the same DST settings.
If you're having difficulty with getting Digital State tags configured, look at the settings for Location2. Use PIOPCTool to find the canonical data type for the item : connect to the server, create a group, add the item to it, and do a synchronous read. If you do not specify a datatype when you add the item to the group, the server will return the datatype that it uses internally for the data. VT_I2 is what we use for Digitals by default. If the server uses VT_I4 or VT_BOOL or VT_BSTR, you can use Location2 to change the datatype that the interface will use for the tag.
Problems with getting and maintaining a connection to the PI server can be due to the PI SDK and your network. The SDK uses "reverse name lookup" to establish a secure connection to PI. This means that your PI server needs to be able to find the interface node's address from the name, just as the interface machine needs to be able to find the PI machine's address. The SDK also needs to be able to connect to the Primary Domain Controller (PDC) for your domain, if the interface machine is part of a domain. If you don't have Domain Name System (DNS) service set up correctly, or if your domain configuration is not correct, you may see problems connecting to PI, or timeouts in trying to connect. Generally, if the interface has trouble connecting, but the non-SDK version works fine, that's an indication that you have a configuration problem with your routers, your PDC, or your DNS. Often with multihomed PCs, which have more than one network card and are usually connected to both a factory network and an office network, conflicting DNS information can cause intermittent connection failures.
Debugging
The debugging flag is included to assist in understanding problematic or unexplained behavior, such as duplicate values or invalid timestamps. Use of the debugging flag should be limited to short periods of time, as the flag will generally cause the creation of large files (files larger than 200 Mb would not be unusual). The flag itself is actually a bitmask, which means you can set more than one option at the same time. A value of /DB=5 is the same as /DB=1 and /DB=4. Here are a few of the possible settings and what they do:
/DB=1
This is for internal testing only, and is not useful to users.
/DB=2
Logging of startup, including instrumenttag and exdesc for each tag.
/DB=4
This setting causes a number of messages to be written to the pipc.log file when write operations are performed. Since we only send one value at a time to be written (per group), and wait for that write to be acknowledged before sending another one, we throttle writes using the TransID. If a server fails to acknowledge a TransID, the symptom is that after that write, no more writes are performed to that group. This flag will cause the OPC interface to log every time it sends a write and every time it receives an ack, as well as any time it stores a write into its "pending write" queue. The TransID which is printed is not necessarily valid, as v1.0a servers give us a TransID after we send the write. Version2 servers allow us to specify the TransID.
/DB=8
Log timestamps for when Refresh is called.
This setting will cause the interface to create three files: opcscan.log, opcrefresh.log, and opcresponse.log. If the interface is running as a service, the files will be in your winnt/system32 directory, otherwise they will be in the directory from which you ran the interface. Every time our routine polls a group (by calling Refresh on the OPC group), the interface will open the opcscan.log file, write the current time, the number of the scanclass, and the current value of the scan flag, and close the file. The timestamp is in UTC (that means Greenwich timezone, and no daylight savings time is observed), and it is a FILETIME structure written as an I64X field. That means that the lower and upper halves of the number are transposed, and the actual number is a count of the interval since Jan 1, 1601, measured in 10E-7 seconds.
After logging the data, the interface will set the scan flag for the group. Then the COM thread will take its turn: when we cycle around to perform the poll, the interface will open the opcrefresh.log file, log the time, the scanclass, and the TransID used (note that the TransID logged for v1.0a servers will be the TransID that was returned from the last poll of the group, while for v2.0 servers it will be the actual TransID returned from the server).
When we receive data from the OPC server, the interface will open the opcresponse.log file, and log the time, the scanclass, and the TransID received. This is virtually the first thing done upon receiving data, if this flag is set.
/DB=16
Log information for excmax processing.
/DB=32
This setting will log the timestamp with the data, the adjusted timestamp, the PItime, the scanclass, and TransID for each data value that the interface receives. This is a *lot* of data. It all goes into the opcresponse.log file. Do not leave this setting on for more than a few minutes. See the section below for more information.
/DB=64
This setting will log the same items as /DB=32, but it will log them for only the tag specified as the debug tag (/DT=tagname). If there is no tag specified, the first tag for which a value is received will be declared the debug tag. See the section below for more information.
/DB=128
Logging for clustering and failover.
/DB=256
Logging for event tags. This will also cause the interface to print the name of each tag into the pipc.log file, as it receives data for the tag. This can create very large files very quickly, so use it sparingly, but it can also verify that the interface is or is not receiving data for some tags. Please note that if you are running the interface interactively, you will not see these messages in the command window for the interface, they only appear in the log file.
/DB=512
Logging for array tags.
/DB=1024
Logging for opclist pointers. This is internal and is not useful for users.
/DB=2048
This setting will cause the interface to ignore point edits after startup. This is not normally useful to users.
Using the opcresponse.log, opcscan.log, and opcrefresh.log Files
The interface gets notified that it's time to scan, so it logs the time in opcscan.log, along with the group number and the current value of the flag for the group, and then sets the flag so the other thread will see it.
opcscan.log: flag: time group
0: 1BFD631E7C98AF0 2
The other thread sees there's a flag set, so it logs the time in opcrefresh.log, and makes the call to the server, then clears the flag. The group number and transaction ID for the call are also logged.
opcrefresh.log: time group TransID
1BFD631E8FE1350 2 1db8
It's important to note that the flag is not cleared until the call is completed.
When data comes in, it logs the time in opcresponse.log along with the group number and the transaction ID.
opcresponse.log: time group TransID
1BFD63208D4DCE0 2 1db8
Now, these timestamps are logged just the way they are used in the program, so we have three tiny programs that will translate those files (we don't translate the timestamps before we write our log files because that would take time, and what we're generally dealing with when we use the files is a problem in how long it takes to get data). The three programs are installed into the tools subdirectory below the interface directory:
• opcscan.exe
• opcrefresh.exe
• opcresponse.exe
and they each want an input file and an output file specified. Opcrefresh.log also has an option to squeeze out duplicates, but you generally don't want to use that, so say "n". You can run these by double-clicking on them, and they'll pop up a window and ask for the inputs, or you can run them from a command window:
>opcscan.exe opcscan.log scan.log
>opcrefresh c:\pipc\interfaces\opcint\opcrefresh.log c:\temp\refresh.log
>tools\opcresponse opcresponse.log response.log
So now you have one or more translated files. They will look like
scan.log:
0 126054824440170000 2000/06/14 18:54:04.017 2
refresh.log
126054824440370000 2000/06/14 18:54:04.037 2 1db8
response.log
126054824974540000 2000/06/14 18:54:57.454 2 1db8
If you're using /DB=64, you will have longer lines when you get data for the debug tag (which is either specified on the command line or, if chosen by the interface, named in pipc.log so you know which tag it is):
response.log
126054824424850000 2000/06/14 18:54:02.485 126054680424850000 2000/06/14 14:54:02.485 960994309.485001 2 1db8
This is all on one line, and shows the UTC timestamp that came with the data, both raw and translated, then that timestamp translated into local time, both raw and translated, then the PITime we sent to the PI server, then the group number and the TransID.
By looking at the logfiles, you can see when we decided to poll, when we made the call, and when the data came in. A major clue is that the flag in opcscan.log should never be anything but zero -- if it's not zero, then the last call we made to the server has not returned by the time we decided it was time for another poll. This should never happen, and so if you see a 1 in that flag, you'll need to talk to your server vendor, and have them call us.
Another common use for these files is to show the timestamp we're getting from the OPC server. Remember, this is UTC time, which we translate into local clock time and then adjust for PI. UTC time is based in 1600, so if you see a date around 1600 you can be sure the server is not sending valid timestamps, and you may want to use /TS=N to have the interface create timestamps when it gets the data.
Error and Informational Messages
Here is a partial list of the error messages you may find in your pipc.log file, and what they mean. They will generally either have a hex number after these phrases (like 0x80007005) or they'll have another message after the phrase, if the OPC server was so kind as to give us an explanation for the error. Other error messages are produced by the standard OSI interface routines, or by the API, and those error messages are not documented here. If any error message has a point number as well as a tag name, always use the point number to identify the problem tag, because often the tagname field that is used is one that only has 12 characters, so the tagname printed in the logfile will not be complete.
These error messages may not exactly match the error messages in the version you're running. What's listed here is the general part of the message. It's a good idea to do a Find in this document to look for words from the error message that you see.
1. Out of memory:
2. Can't even allocate a list, dying
3. Unable to add tag
There are several formats for messages that mean the system has run out of resources. You can use the Task Manager to check the resources being used: press the Control, Shift, and Escape keys all together to get to the Task Manager, then select the Processes tab. From the menu, select View\Select Columns, than check the boxes for Memory Usage and Virtual Memory Size to see who's eating up all the memory. If it's opcint.exe, you may have a bottleneck between the interface and your PI system -- you should see other messages in the PIPC.LOG file (see below for "Running low on memory, dropping data").
4. Error from CoInitialize:
5. Error from CoInitializeSecurity:
You may not have COM properly installed on your system. This is a major problem.
6. CLSIDFromProgID
The Server's Registry entries are not valid. You'll need to check your server installation instructions.
7. CoCreateInstanceEx
This is almost always a problem with DCOMCNFG. See the section on Configuring DCOM.
8. IOPCServer
This error indicates that you do not have the proxy stub registered. The opcproxy.dll and opccomn_ps.dll files are included in this distribution. To register them, open a Command Prompt window, change to the directory where the interface was installed, and type the following commands. The system should pop up a window after each line, telling you that the DLL was registered.
>regsvr32 opcproxy.dll
>regsvr32 opccomn_ps.dll
9. AddRef
This means the OPC server would not let the interface do the simplest function. If you are able to read and write tags using PIOPCTool, but you get this error, you almost certainly have some permissions problem. Recheck your DCOM settings, check what user the interface is running as, try running the interface interactively (see above on how to do this)
10. No ConnectionPoint for OPCShutdown
11. Shutdown Advise Failed
There are not fatal errors, it just means that the OPC server does not implement the Shutdown interface, or doesn't implement it properly; if the server goes down, we'll only know about it because it stops answering our calls. This will not prevent proper operation of our interface.
12. Advise returns error: 80040202(Unable to open the access token of the current thread)
If you believe you configured DCOM correctly, and you still keep getting this error after connecting to the server successfully, it is possible that the wrong opcproxy.dll is being loaded. If you have multiple copies of opcproxy.dll on your API node (possibly because you have more than one OPC server on your machine), make sure that they are the same version. It is safest to have only one version around on your system (in \winnt\system32 directory, that being the latest version). If they are from before June, 1999, they may contain an error which causes errors like above. If the directories containing such versions are specified in the system path, that is why you get the above error although you configured everything correctly.
13. Unable to advise group
14. Unable to advise output group
15. Unable to advise event group
16. Unable to create group
17. Unable to add to group
18. Unable to add to OPC group.
19. AddGroup failed for scanclass %d
20. QueryInterface:IID_IOPCAsyncIO2 failed for scanclass %d
21. QueryInterface:IID_IDataObject failed for scanclass %d
22. Advise returns E_OUTOFMEMORY
23. Advise returns E_UNEXPECTED
24. Advise returns error
25. Advise Group failed for %s
26. No ConnectionPoint for scanclass %d
27. AddItems failed for tag %s
28. AddItem failed for %s
29. Write failed
30. Write error %X for tag
31. Read: (some string from server here, we hope)
32. Refresh: (some string from server here, we hope)
These are all fatal errors, indicating that the OPC server returned us a failure code for the indicated operation. Try to do the same operation using the PIOPCTool; if that works, try running the interface interactively to see if you have the same error. If you can use PIOPCTool, and the interface works interactively, check your DCOM configuration to make sure that you've given permissions to the INTERACTIVE account.
The failure code c0040007 returned from AddItem indicates that the server doesn't have any item with the name you've specified. The value in the InstrumentTag field of the PI tag must be the exact name that the OPC server uses for the item. Use PIOPCTool to try to add that Item to a group, or if your server supports browsing, browse to the item and double-click on it to see its full name appear in the Item field of PIOPCTool.
The requested data type cannot be returned for this item (c0040004) means that you asked for a datatype that the server can't use for that particular data (like asking for a number, but the Item is a string with a value of "Not Open"). You should use PIOPCTool to add that Item to a group without specifying any data type, and then the server will send you values using the data type that it uses internally for that item. See the section on Datatypes to find out how to configure your tags to ask for that data type.
33. Invalid read/write mode requested for tag %s
This is not fatal, but you'll need to set a command line switch to take are of it. The server is returning invalid information about read/write access. Most likely, it's just a buggy server (early servers show this problem), and you can use the /AR=N flag to tell the interface to ignore this information.
34. RemoveItem failed for tag %s
35. dev_remove_tag: Unable to DUnadvise %s
36. dev_remove_tag: Unable to remove group %s
This means the server wouldn't let us remove a tag from a group, or stop collecting data for a group. It's probably not a problem, if it's not accompanied by lots of other messages, which it probably is. If we can't remove the tag or the group, we'll still be getting data for it, but since we've taken it out of our local database, we'll just drop the data on the floor. Still, this indicates some problem with the OPC server. These messages mostly help to diagnose problems that are discovered by other means.
37. AddItems failed, server not in RUNNING state, will try later
This is informational. Some servers take a while to fully start. We'll wait around, and when the server enters RUNNING mode, we'll continue. You can use the PIOPCTool to see the state of the server (use the Get Status button). If the server doesn't enter the RUNNING mode, you should investigate the cause.
38. QueryInterface:IID_IConnectionPointContainer failed, using v1.0a protocol
This is informational -- we try to use the v2.0 COM interfaces, but if the server doesn't support them, we'll drop back to v1.0a. It just means that the server doesn't support OPC DA v2.0.
39. Write unable to get values:
40. Getsnapshotx error %d
This means we tried to read a value from PI to write to the OPC server, and were unable to read the value. Make sure PI is running -- try using apisnap (in the API directory). Check the tag configuration to make sure you aren't trying to write a string value into a numeric output.
41. No Item name - instrumenttag and exdesc both empty
42. Unable to get point type
43. Unable to get square root
44. Square root must be 0, 1 or 2
45. Unable to get total specs
46. Total must be 0,1,2,3,4, or 5
47. Nonzero Totalcode requires nonzero Convers
48. This Totalcode requires DZero to be specified.
49. Point cannot be write and Read On Change
50. Unable to get source point type.
51. Event Point has invalid scan class (!= 0)
52. Point has invalid scan class (== 0)
53. Point has invalid scan class
54. ROC Point has invalid scan class (== 0)
These are errors from PI, indicating a tag is improperly configured. Check your tag configuration.
55. GetStatus
This means the OPC server didn't respond to a status query. It may be down or disconnected.
56. Can't get PI server time
This is actually a major error, as we're actually asking the API for the timestamp. If you see this, you probably need to call for help, unless you've just installed your system. If you've just installed your system, try rebooting, then making sure you can connect to PI. Try pinging the PI machine (>ping machinename); make sure PI is running; try using APIsnap to connect to PI (look in the API directory for apisnap.exe).
57. GetStatus: Server has no current time.
This is a really broken server that refuses to even give us the time of day. Literally. The server is supposed to include current time when it sends us its status. This one sent trash. We're going to assume it's a very stupid server, and try to guess at what correct timestamps would be, but you should not assume that your timestamps are highly accurate.
58. Cleaning up connections
59. Cleaned up connections
The interface will print these messages when it's been told to exit. The first indicates that the interface is beginning the process of disconnecting from the OPC server. The second indicates that we're disconnected and will be dying shortly.
60. Interface failed to write some %s states
When the OPC server shuts down, we will send a shutdown status to each tag, if you tell us to (using the /OPCSTOPSTAT parameter on the command line). If we tried, but couldn't send some or all of them (because we can't talk to PI, and you aren't using bufserv), you'll get this message.
61. Server sent shutdown notice
This is printed when we receive a shutdown notification from the OPC server. It may be followed by a message from the server indicating why it was going down. The interface will wait forever, trying to reconnect to the server periodically, until it is told to shutdown or until it is able to reconnect.
62. OnDataChange:Invalid group ID < 0
63. OnDataChange:Invalid advise group ID:
64. OnDataChange:Invalid group ID > 999
65. OnDataChange: Header status:
66. OnDataChange has format not HGlobal
67. OnDataChange:Invalid group ID for write completion
68. Unknown access type for group %s
These are all messages that indicate that the server is sending us trash. The only one we can work around is "Header status" -- you can set a command switch (/GS=N) to tell the interface to ignore the header status field in incoming data.
The other messages indicate that we got *something*, but we have no way to figure out what it's supposed to be. Talk to your OPC server vendor. Try using PIOPCTool to create groups and do async reads and advises. Check to see if you're getting the data you should be getting -- the server may be sending junk, but it may not interfere with data collection.
69. Got %d and cleared it
70. ClearWrite: dwTransID mismatch, have %d, got %d
71. Stashing transid %d
72. Sending transid %d"
73. Writing transid %d
These are debug messages at debug level 4. It shows that the server acknowledged write #d, and so we're clear to send another write value.
74. OnDataChange: VariantCopy
This is a serious problem, it indicates that the OPC server sent us what looked like data, but it's junk. It may be a transmission error, or a server bug. Whatever it was, we've dumped the bad data, since we can't do anything with it, and written BADSTAT to the tag (the timestamp was good, after all).
75. OnDataChange: Bad Timestamp
We got an invalid timestamp from the OPC server. We grabbed a timestamp when the data came in, and we'll use that, but you need to check your server. PIOPCTool will show you timestamps.
76. Invalid timestamp for tag: %s, %d and %.36f
We received an invalid timestamp from the OPC server. Try using PIOPCTool to look at the same ItemID. Using Refresh or Advise or AsyncRead will show you a timestamp. This usually indicates a bug in the OPC server.
77. Putsnap system error %d, %d
78. Putsnap no longer in system error %d, %d
We have/had a problem sending data to PI. These are system errors.
79. Putsnap error state changed, was %d, now %d
80. Putsnap no longer in error %d,tag: %s
We have/had a problem sending data for this tag.
81. Putsnapsx not implemented %d
82. Getsnapshotx not implemented
You need to install a more recent version of the API. This one doesn't handle extended API calls, and we require those.
83. Unable to translate string
We have to speak Unicode to the OPC server, because it's required for COM. We tried to translate some string value from a PI tag from its ASCII to Unicode, and we failed. The particular value in that particular tag would be most interesting to look at, since if it's valid ASCII printable data, it should be translatable.
84. Unable to initialize server object
We can't run. I'll be surprised if anything is running on your machine. Or maybe you're trying to run under an account with no privileges at all.
85. No OPC server specified
You didn't put \SERVER=servername into the opcint.bat file. Or you ran the interface interactively rather than as a service, but you didn't edit the opcint.bat file to put everything on one line first.
86. Can't find status tag, ignoring
87. Can't find queue tag, ignoring
88. Status tag is not Digital tag, ignoring
89. Queue tag is not Integer tag, ignoring
You specified a status/queue tag, but either it doesn't exist or it's not the correct datatype tag, so we're ignoring it and going on.
90. Can't connect to OPC server, going into slow cycle wait
We tried to connect to the server, but couldn't. We'll keep trying. There should be another message before this one that gives more information about exactly what call failed. Look at that message, and fix whatever it says is wrong. Otherwise, the interface will sit here forever.
91. Unable to create clock drift timer
We aren't going to be able to keep track of clock drift, because we can't create a timer. You could be really out of resources, or your system could be completely hosed. Either way, we're really unhappy.
92. Running low on memory, dropping data
93. Memory load within acceptable limits, resuming data collection
If the PI system won't take data as fast as we want to send it, we'll buffer it in memory for a while. If the situation continues, we'll end up eating all the memory on this machine and it will eventually crash, so at some point we'll decide to cut our losses and start drop[ping new data coming in. When we've sent enough of the buffered data to PI that system memory isn't critical anymore, we'll start collecting data again. The parameters for when we start dropping data and when we resume can be tweaked with /HQ and /LQ, but you're trying to push too much data through too small a pipe. Consider giving the PI system more resources, changing the exception parameters of your tags, or changing the scan period of your tags.
94. Failed to open cluster: error ####. Intf-failover will not be supported.
95. Failed to open cluster resource: error ####. Intf-failover will not be supported.
The error #### is Win32 Error code. The attempt to open the Cluster service and/or the Cluster resource failed. Since the interface did not get the handle to these objects it cannot support the interface-failover facilitated by the cluster service. An example of this error is
5007 The cluster resource could not be found.
Please verify resource name is correct.
• There are also informational messages printed; on startup, the interface will print the scan classes with the count of tags in each class, and the update rate for the class. After the interface is started, if points are edited in PI, the interface will log the changes in the log file.
PIOPCTool
PIOPCTool is included with the OPC interface to make it easier to install and troubleshoot your OPC interface and OPC server(s). It consists of an executable file PIOPCTool.exe which can be run by double-clicking on the filename in NT Explorer or MyComputer, or you can create a shortcut for it. It is installed into a subdirectory called Tools, below the interface directory.
Once the program starts, you’ll see a dialog with boxes and buttons. The Menu bar includes a pulldown Help, or you can start the Help function by pressing F1. The help includes a short tutorial which walks the user through connecting to an OPC server, creating a group, adding points to the group, reading and writing points, and asking for Advise on a group. In brief, the steps are:
1. Click on the Servers listbox to get a list of the OPC servers registered on your system. If your server is running on another machine, you can type the machine name or IP address in the Node box, and then press Connect. That will cause the tool to try to find out what servers are available on that machine. If OPCEnum is not installed on the other machine, you can copy the files in the OPCEnum directory to the other machine, then run register.bat, and that will install OPCEnum on that machine. You will need to be logged in with administrator privileges in order to do this.
2. Select a server, then press the Connect button. If the OPC server actually runs on another machine, type the name or address of the machine in the Node Name box before pressing Connect.
3. Select the server from the list of Connected Servers.
4. If the server supports browsing through the list of points, the Browseable box will now be checked, and you can press the List Server’s Tags button to get a list of the points that this server recognizes. If it’s a hierarchical list, you’ll see a tree structure just like NT Explorer uses to show directories and files. If you only want to see points that are Read points (Input), or only Write points (Output), check the box for the kind of point you want before you press the List Server’s Tags button.
If you are using a DeltaV OPC server, do NOT use List Server's Tags. Use the Manual Server List button to get one level at a time. The DeltaV has thousands of OPC Items, and listing them all out can take hours, or cause the PIOPCTool to lock up or crash.
5. Type a group name in the Group box -- this can be anything, but must be unique on that server -- in other words, you can’t have two groups named Temperature on the same OPC server. Enter a scan rate in the Update Rate box, counting in milliseconds, so 1000 would give a scan rate of one second. Press Create to create the group.
6. Now you can add points to the group by either double-clicking on the point in the browse box (if the server supports browsing), or by typing the name into the Point box. You can also select the Data Type for the point, or you can leave it blank and let the OPC server tell you what the data type is. Some servers may require that you specify a Data Type. You also need to type in a name for the tag -- this can be anything you like. If you plan on saving the configuration to create tags in your PI server, use the tagname you intend to use in PI. Press Add to Group to add the point.
7. Once you’ve got one or more points defined, you can Read the values, you can select a point in your group and put a value in the Value box and Write the value to the point, and you can Advise on the group, so the server will send you updates on the group whenever the value of a point in the group changes.
8. There is only one button for SyncRead, because this is the same no matter what server you have. For Advises, Writes, Async Reads, and Refreshes, however, you have a choice. If your server supports OPC Data Access standard v2.0, the interface will use that, and you should use Refreshv2.0, AsyncRead2.0, and Advisev2.0 for your testing. If your server doesn't support v2.0, you'll get an error when you try to use those, and you'll need to use Refreshv1.0a, AsyncRead1.0a, and Advisev1.0a. You should also use the /VN=1 parameter in your opcint.bat file. The interface uses Refresh for polled tags, just as if you sat there and pushed the Refresh button over and over again. For Advise (also called ReadOnChange) tags, the interface uses Advise. AsyncRead is used for triggered tags. The SyncRead button is only there for testing, the interface does not do any synchronous reads at all. This means that while you may be able to connect to the OPC server and do SyncReads, if you cannot get data from an Advise or Refresh, the interface will not be able to collect data. If you can get data with SyncRead but not with Refresh, AsyncRead, or Advise, it's most likely a DCOM permission problem.
9. You don’t need to disconnect from one server to connect to another -- the tool allows you to connect to 5 servers at once, and for each server you can define up to 10 groups, and for each group you can add up to 200 points.
10. If something doesn’t work, look at the help. I’ve tried to include both explanations for what might be wrong as well as suggestions on how you can verify or fix the problem.
OPC Interface Failover
This interface supports two types of failover, one which allows the interface to collect data from either of two servers (server-level failover), and one which allows two copies of the interface to run on the two machines of a Microsoft cluster, with only one of those copies actually collecting data at any given time. The two modes are designed to work together, so that you can have redundancy for both the server and the interface. Details of configuring failover are documented in the OPC Interface Failover Manual.
DCOM Configuration Details
A note about using DCOM without an NT Primary Domain Controller
If you do not have a Primary Domain Controller, or if your OPC server and your OPC client machines are not within the same NT domain, DCOM cannot use NT security to determine who can talk to whom. Therefore, it will fall back on the most basic of security models: the account(s) under which the client and server are running must be valid and privileged on both machines. That means that the server must have a user account defined that is the same as the user account on the client machine under which the interface itself (and PIOPCTool) will run. The passwords for those two accounts must also be identical. Otherwise, DCOM will not pass any communication between the client and the server, although it may well launch the OPC server, leading you to believe that you should be able to talk to the server from the client machine. Note that this account must be a local account on each machine, not a domain account.
Your server vendor may have provided you with instructions on how to configure DCOM for your OPC server. If so, please try to run the interface with those settings before you try to configure your system using the following instructions. Also, it’s a good idea to write down what the old settings were, whenever you change something, so that you can change it back if you need to do so. That’s particularly important if you already have another OPC client that works with your current setup. If your interface is on a separate computer from your OPC server, use these instructions just for the interface machine first, and only change the settings on the OPC server machine if you are unable to collect data without changing them. If your server vendor gave you installation instructions for how to set up a client machine, try using those.
If you are using two machines, both machines have to be configured to allow access. That’s because the OPC server makes calls to the interface, and the interface makes calls to the server, and if your configuration is not set up to give them both permission to talk, the NT system will not allow communication.
First, if PIOPCTool does not list your server when you run the tool on the same machine as the OPC server, you need to register the OPC server using a Command window as follows
servername.exe –regserver (to unregister use –unregserver)
(This is not guaranteed to work for all servers, but if you don’t have documentation for your server, it’s certainly worth trying, it will work for many or most.)
Do a search on all hard drives for opcproxy.dll (this comes with the OPC server). Make sure there is only one version on your machine. If there are more than one, it should not be a problem if they are all same version, if not rename all but the latest one which you should keep in \winnt\system32.
Then register the following DLL’s. Make sure opcproxy.dll and opccomn_ps.dll exist in winnt\system32 directory. Run
C:>regsvr32 opcproxy.dll
The following dialog box should show up.
[pic]
Then run
C:>regsvr32 opccomn_ps.dll
The following dialog box should show up.
[pic]
Then invoke dcomcnfg by typing in Command window
C:\winnt\system32\dcomcnfg.exe
A window that looks more or less like the following will show up. What you see may be a little different, depending on what versions of what Microsoft (TM) products you have installed. Select your OPC server and click on Properties button.
[pic]
Then you will see the following. Check the information is correct.
[pic]
Editing entries under Location tab can change this information.
If you are running the OPC server on a different node than OPCint interface, specify the node name and check “Run application on this computer “. You can specify more than one. This step is not critical since this only applies to default setting. OPCint will launch the correct OPC server if it is registered (see the beginning of this section for registering the server) and has correct security settings (more on this later).
[pic]
Then click on Security tab and make sure it looks like this:
[pic]
Then select Identity tab and select “This user”, and specify an account with administrator privileges. OPCint service must also be configured in ControlPanel/Services/Startup to log on as that account.
Do not use the Local System account to run programs that use DCOM. While the Local System account has plenty of privileges locally, it has no authority outside its own system.
Now, if you had to make any changes to the existing selections and/or entries so far, click on Apply, and if not click Cancel to get back to the main Application tab.
Click on Default Properties tab and make sure the entries look like following
[pic]
Now click on Default Security tab. You will see
[pic]
Click on Edit Default for Default Access Permissions. Make sure that at least all of the following accounts are there.
[pic]
Add the account with which OPCint service is logged on as. Type of Access should be Allow Access. Click OK, and get back to the main Default Security screen.
Click on Edit Default Launch Permissions button and enter the same entries as above.
[pic]
Allow Launch should be the Type of Access.
Now you are ready to try connecting to the server by using PIOPCTool which should run on the same machine as your OPCint interface. You may need to reboot.
CAUTION: This DCOM configuration is given as a sample configuration. The "EVERYONE" account will give permission to anyone who can log onto the system. You will probably want to restrict access more than that, once you have established a connection and can see data flowing into PI.
Appendix A:
Notes on Some OPC Servers
This section is neither exhaustive nor any indication of whether an given OPC server has been tested with the interface, is currently running at a production site, or is troublesome or troublefree. It is solely to provide some information that may be of use.
Honeywell APP Node
For the APP node, you must purchase the APP Solutions Package to have an OPC server for your APP node. It is also useful to note that while Honeywell’s internal representation of Digital State tags is as a small integer (VT_I2), if you use the ItemID as shown, what is passed across the LCN is the string value: the integer is translated to a string, that’s passed to the OPC server, which passes it to the interface, which translates it back to an integer, and then sends it to PI. This is a major drain on the resources on the Honeywell side. You can append “.internal” to the ItemID, and the OPC server will receive and send integer values rather than strings. Try this with the PIOPCTool first. You should see a noticeable improvement in performance if you have any appreciable number of Digital State tags.
Also note that there appears to be a limit of about 800 values/second for any client on the LCN. You may wish to run multiple copies of the interface or server to increase throughput.
In general, we’ve found that the APP node server wants to be fully up and running before a client connects to it. This is true of some other servers as well. The /STARTUP_DELAY switch will let you tell the interface to wait some number of seconds before trying to connect to the server, which will give the server time to get fully started. Note that the server may allow the connection, and say that it is in a RUNNING state, but not yet be ready for a client to create groups and add tags and read data. If you have trouble on startup, especially if you have trouble when the system is rebooted and the interface is set to automatically start as a service, try setting that flag to 30 or 60 seconds, or even 120.
A recent version of the APP node also included a DLL (dynamic link library) for performance counters which caused some problems. The 1.1 version of the PI SDK loaded all the performance counter DLLs and unloaded them, but unfortunately the Honeywell DLL calls “exit” when it is unloaded, causing the program to exit. This is Not Good. You can work around that by renaming the DLL, so that it will not be loaded. The problem description and solution are given on the OSI web site, in Online Support under the title “SDK 1.1.0.142 exits with no errors reported”. The DLL which produced this problem was DSSCOUNTERS.DLL, found in \Program Files\Honeywell\TPS\base.
DeltaV System
Do not use the List Server’s Tags button in PIOPCTool with the DeltaV server. The DeltaV considers all data items to be ItemIDs, so there may be over 100,000 items to be listed, and the program may crash or hang or simply take an hour or several to respond.
Instead, use the Manual Tag List button to list the items one level at a time.
All Servers Built on the FactorySoft Toolkit
The current version of the toolkit includes a bug that makes using Advise tags unwise if the values in the tags don’t change often. The server is required to send an initial value when we advise the group, and then it will only send a value when there’s a new value to send. Servers built on the FactorySoft toolkit do not send that initial value, so if you have a data item that only changes once a week, the interface could run for a week before it receives any data for that item. This is Not Good.
FactorySoft is aware of the problem and will fix it in the next release of their toolkit. They have also said that they will be providing an upgrade path for servers built upon the old toolkit. Meanwhile, they say that if you contact them, they can provide a work-around. If your server exhibits this behavior (simple to check with PIOPCTool, just create the group and add the tags before you press the Advisev1.0a or Advisev2.0 button: if you get data when you press Advise, your server is fine), please contact your server vendor and ask them to investigate a fix.
Revision History
|Date |Author |Comments |
|May-97 |LAC |Rough Draft |
|Jun-97 |LAC |Updated to reflect server issues, added PIOPCTool description. |
|Sept-97 |LAC |Added Event Rate argument, rewrote descriptive sections. |
|Oct-97 |LAC |Updated to Uniint v2.25 |
|May-98 |LAC |Release candidate |
|May-99 |LAC |Updated for v2.0 |
|Jun-99 |LAC |Updated for v2.0.6 |
|Oct-99 |KL |Added descriptions for failover support and DCOMCNFG |
|Feb-2000 |LAC |Added descriptions for arrays, DLLs, DCOM notes. |
|April-2000 |LAC |Version 2.1 information, appendices. |
|May-2000 |LAC |Additional options |
|Aug-2000 |LAC |More options, clarifications |
|Nov-2000 |LAC |Version 2.1.21, new options |
|Mar-2001 |LAC |Version 2.1.22, new options |
|Jun-2001 |LAC |Version 2.1.25, minor additions |
|Sept-2001 |LAC |Version 2.1.31, new options |
|02-Nov-01 |CG |Version 2.3.4; formatting, headers, footers |
|05-Nov-01 |KL |Minor wording changes to failover section |
|30-Nov-2001 |LAC |Version 2.1.35 new options |
|08-May-2002 |BY |Clarification on options |
|26-Jul-02 |CG |Added version 2.1.37; fixed some typos; fixed TCO; fixed headers &|
| | |footers |
|6-Aug-2002 |LAC |Added version 2.1.38 |
|2-Oct-2002 |LAC |Enhancements for 2.1.39 |
|22-Jan-2003 |LAC |Enhancements for 2.1.41 |
|28-Apr-2003 |LAC |Added DCOM caution, minor clarifications, updated version number. |
|24-Jun-2003 |LAC |Added /SQ=I option, updated version number |
|16-Jul-2003 |KL |Corrected DCOM Identity tab configuration instructions. |
|21-Jul-2003 |LAC |Corrected Basic DCOM Identity info, updated version number. |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
- 1 usmc training and education command
- pleading wizard world review group
- dbq 10 causes of the civil war
- temperature charts
- opc interface to the pi system
- gis standard operating guideline template
- parent letter first map season
- guided notes declaration of independence
- m21 4 chapter 2 veterans affairs
- property outline nyu law