OPC
Interface to the PI System
version 2.1.46.0
OSI Software, Inc.
How to Contact Us
Phone
Fax
E-mail
World Wide Web
Mail
(510) 297-5800 (main number)
(510) 297-5828 (technical support)
(510) 357-8136
techsupport@osisoft.com
http://www.osisoft.com
OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
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
OSI Software, Inc.
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
OPC Interface to the PI System
iii
Table of Contents
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 ........................................................................... 49
Installing Debug Symbols ....................................................................................... 50
Startup/Shutdown ...................................................................................................... 51
Editing Tags While the Interface is Running .............................................................. 51
iv
OSI Software, Inc.
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 ........................................................................................... 66
Common Problems .................................................................................................... 66
Debugging ................................................................................................................. 67
Using the opcresponse.log, opcscan.log, and opcrefresh.log Files ........................ 69
Error and Informational Messages............................................................................. 71
OPC Interface to the PI System
v
Table of Contents
PIOPCTool ................................................................................................................... 79
OPC Interface Failover ................................................................................................ 81
DCOM Configuration Details ...................................................................................... 83
Appendix A: Notes on Some OPC Servers ............................................................... 91
Honeywell APP Node ................................................................................................. 91
DeltaV System ........................................................................................................... 92
All Servers Built on the FactorySoft Toolkit ................................................................ 92
Revision History .......................................................................................................... 93
vi
OSI Software, Inc.
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.
OPC Interface to the PI System
1
Introduction
Configurations
The Preferred Configuration
Another Possibility
Supported Features
Feature
2
Support
OSI Software, Inc.
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.
OPC Interface to the PI System
3
Introduction
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 onetime 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.
4
OSI Software, Inc.
>@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.
OPC Interface to the PI System
5
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
OPC Interface to the PI System
7
Overview
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.
8
OSI Software, Inc.
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.
OPC Interface to the PI System
9
Overview
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
10
OSI Software, Inc.
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
OPC Interface to the PI System
11
Overview
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
12
OSI Software, Inc.
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

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"
OPC Interface to the PI System
"1998/11/29 15:32:19.391"
13
Overview
"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.
14
OSI Software, Inc.
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
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
OPC Interface to the PI System
DZero
Operation:
15
Overview
16
Convers
TotalCode
SquareRoot
DZero
Operation:
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
OSI Software, Inc.
Convers
TotalCode
SquareRoot
DZero
Operation:
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
OPC Interface to the PI System
no /SQ flag
/SQ=Y
/SQ=I
GOOD
value
value
value
Questionable
value, flag
digital state
value
BAD
digital state
digital state
digital state
17
Overview
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
http://www.opcfoundation.org 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
11SSSSLL
OPC Definition
PI Status
Non-specific
Good
Local Override
_SUBStituted
Except
110110LL
Not used by OPC
Quality
10SSSSLL
OPC Definition
Invalid
PI Status
Bad Input
Questionable
Quality
OPC Definition
010110LL
Sub-Normal
010101LL
Engineering Units Exceeded
QQSSSS01
Low Limited
Under LCL
QQSSSS10
High Limited
Over UCL
Otherwise
18
PI Status
Bad_Quality
Inp OutRange
010100LL
Sensor Not Accurate
QQSSSS01
Low Limited
Under Range
QQSSSS10
High Limited
Over Range
Otherwise
Out of calibration
Invalid Data
OSI Software, Inc.
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
11SSSSLL
OPC Definition
PI Status
Non-specific
Good
Local Override
_SUBStituted
Except
110110LL
Not Used by OPC
Quality
10SSSSLL
OPC Definition
Invalid
PI Status
Bad Input
Questionable
Quality
OPC Definition
PI Status
010110LL
Sub-Normal
010101LL
Engineering Units Exceeded
QQSSSS01
Low Limited
Under LCL
QQSSSS10
High Limited
Over UCL
Otherwise
Bad_Quality
Inp OutRange
010100LL
Sensor Not Accurate
QQSSSS01
Low Limited
Under Range
QQSSSS10
High Limited
Over Range
OPC Interface to the PI System
19
Overview
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
20
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
OSI Software, Inc.
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
OPC Interface to the PI System
21
PI Point Configuration
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.theopc/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
22
OSI Software, Inc.
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.
OPC Interface to the PI System
23
PI Point Configuration
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
24
OSI Software, Inc.
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.
OPC Interface to the PI System
25
PI Point Configuration
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
26
OSI Software, Inc.
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.
OPC Interface to the PI System
27
PI Point Configuration
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.
28
OSI Software, Inc.
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.
OPC Interface to the PI System
29
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
Point Source Description
Location 1
(char)
OPC
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
OPC Interface to the PI System
31
Software Configuration
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.
32
OSI Software, Inc.
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.
OPC Interface to the PI System
33
Software Configuration
/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
34
/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.
OSI Software, Inc.
/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.
OPC Interface to the PI System
35
Software Configuration
/TF
Sets the format for timestamp strings read from or written to the OPC
server.
Handling Idiosyncracies for Various OPC Servers
36
/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@osisoft.com 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.
OSI Software, Inc.
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
/AF
Optional
Default: /AF=N
/AR
Optional
Default: /AR=Y
Description
The /AF argument is provided to help deal with broken servers which do not
return initial values for Advise tags. This argument must not be used in
conjunction with NT Cluster Failover, as it causes OPC Groups to be
advised as soon as they are created.
The /AR argument is used to tell the interface to ignore the access rights
property on items added to a group ( /AR=N). If your server does not use
the access rights bitmask properly, 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
Optional
Required for server-level
failover
The /BACKUP argument is used if failover option is used. This switch
specifies the name of the backup OPC server. The backup server name is
specified after an equal sign with no spaces or quotes as follows:
/BACKUP=backuphostname::backupOPCservername
Again, if the OPC server is on the local machine, the hostname:: must be
omitted:
/BACKUP= backupOPCservername
/CM
Optional
Cluster Mode. When the interface is configured for interface-level failover,
running on a 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.
OPC Interface to the PI System
37
Software Configuration
Parameter
/CN
Optional
Description
When the interface is configured for interface-level failover, running on a
cluster, this 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
Optional
Default:
/CO=N
This argument is only useful when, for some reason, you are not using API
buffering. When the PI server becomes unreachable, the interface will still
try to send the data, but it will fail. When an attempt to send data succeeds,
then, the interface can send the current PI 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
Optional
Default:
/CR=N
This argument is only useful when, for some reason, you are not using API
buffering. When the PI server becomes unreachable, the interface will still
try to send the data, but it will fail. When an attempt to send data succeeds,
then, the interface can call Refresh for all of 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
Optional
When the interface is configured for server-level failover, this argument can
be used to 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
Optional
This is included to allow some minimal debugging if you have difficulty
figuring out what you're getting from your server. See the section on
Debugging for more information.
Default: none
/DF
Optional
Default: none
This parameter allows you to change the value of the debug flag while the
interface is running. Configure an output tag for the interface, Int32, and set
its value to 0. Give the 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.
38
OSI Software, Inc.
Parameter
/DLL
Optional
Default: none
Description
The interface now supports post-processing DLLs for specific OPC servers.
The format for telling the interface where to find your DLL is :
/DLL=c:\directory\to\the\file\yourdll.dll
where you replace the directory path and filename with the appropriate one
for your DLL.
/DT
Optional
The name of the tag to be used with /DB=64. If this tag is not specified, the
interface will use the first tag for which it receives a value.
Default: none
/EC
Optional
Default: none
The /ec flag is used to specify an IORate tag from the iorates.dat file.
Example entries from an iorates.dat file are given below:
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
Optional
Default:
/ER=00:00:01
This parameter defines the requested update rate for the event class group.
All event-based points belong to one group, and the default update rate for
the group is one second. If the OPC server's data cache for event-based tags
does not need to be updated that frequently, use 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.
OPC Interface to the PI System
39
Software Configuration
Parameter
/ES
Optional
Default:
/ES=CACHE
/F
Required
Description
This parameter determines whether event tag reads for v1.0a servers will be
from CACHE or from DEVICE. DEVICE reads should be used with
caution, as they can have a tremendously negative impact on the
performance of the OPC server. Please read the section on Configuring
Event Tags before using this setting (/ES=DEVICE).
This parameter defines the frequency scan class. It determines how
frequently the interface 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. Subsecond 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=#
Default:
/FM=3
Failover mode. This controls the behavior of the backup interface when
using interface-level failover. The options are:
/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
40
OSI Software, Inc.
Parameter
/FT
Optional
Default: /FT=60
Description
The /FT argument is used in conjunction with /BACKUP argument to
specify the failover time. The interface will keep trying to connect to the
current server for this many seconds before 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
Optional
Default: /GL=Y
/GS
Optional
Default: /GS=Y
/HQ
Optional
Default: /HQ=100,000
Some early v1.0a servers did not format messages correctly, and the
interface included a work-around for them. This is now turned off by
default. If you receive the error message “"OnDataChange:Invalid group
ID”, try setting /GL=N to see if that fixes it. If it does, please email us at
techsupport@osisoft.com 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.
The /GS argument is intended to allow the use of older, non-compliant OPC
servers which do not provide a valid GroupStatus on asynchronous reads. If
your log file contains an error like:
"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.
The /HQ argument sets the upper limit for the internal queue of the interface.
The interface may take in data from the OPC server faster than it can pass it
to PI, or faster than PI will 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.
OPC Interface to the PI System
41
Software Configuration
Parameter
/HOST
Optional
Default server defined in
PILOGIN.INI
Description
/HOST=nodename:X defines the PI Server to which the interface will
connect. If this parameter is not used, the interface will attempt to find the
PILOGIN.INI file and use the default server defined there. For example:
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
Optional
Default: /HS=N
OBSOLETE
This flag makes the interface request a cache update rate of 1/2 of the scan
rate for the scan class. If your scan class is 2 seconds, the interface will ask
the OPC server to read new values from the device every second, for all the
tags in this scan class. This is mostly 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
Optional
/ID
Optional
This flag tells the interface to check for Plantscape-specific error codes when
retreiving 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=2 defines an identifier. The identifier precedes messages sent to the log
so that if more 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
Optional
Default: /IF=N
42
The /IF flag tells the interface to ignore the first value sent for each point.
This is to accommodate those servers that send a response when the interface
connects to a point: some 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.
OSI Software, Inc.
Parameter
/IS
Optional
Default: /IS=N
Description
This flag tells the interface to ignore the server status returned by the OPC
server, as far as determining the appropriate actions to take. All servers
should return
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
Optional
Default: /IT=N
/LQ
Optional
Default : /LQ=80,000
For performance reasons, some users may wish to discard the subsecond
portion of the timestamps being passed to PI and only send whole integer
seconds. This will mean that PI 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.
The /LQ argument sets the lower limit for the internal queue of the interface.
If the internal queue has exceeded the HQ limit, the interface will drop
incoming data until the internal 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
Optional
Default: /MA=N
/MAXSTOPTIME
Optional
By default, the interface will add one item at a time to its groups. This
guards against ill-behaved servers that will reject an entire group if one item
is invalid. The Mass Add 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.
The interface ordinarily gets 120 seconds to close its connections and exit
cleanly. If your server requires more time, use this parameter.
Default=120
/NI
Optional
Used in conjunction with
/FT if multiple instances
of the interface are
running on the same node.
/NT
Optional
Default=N
OPC Interface to the PI System
The /NI argument specifies the number of instances of the interface running
on the node. This switch is used in conjunction with /FT switch to specify
how long the interface is to wait until it initiates a server-level failover. This
gives the multiple interfaces extra time to DCOM timeout in case a DCOM
call made to the server doesn’t return in time because the server is busy
servicing requests from other interface.
The /NT=Y flag tells the interface to never write IO Timeout when it loses
the connection to the OPC server. You will almost always want to have IO
Timeout written to the tags at those times, but the ability to turn it off is
included for very special circumstances.
43
Software Configuration
Parameter
/OPCSTOPSTAT
This is where you can specify that a digital state should be written to each
input tag when 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.
Optional
/PISDKCONTIMEOUT
Optional
/PR
Optional.
Required for
level failover
Description
interface
Set the timeout for PISDK calls. The parameter is the number of seconds to
wait before timing out. The default is 15 seconds.
The /PR argument specifies if interface-level failover is to be supported. If
no interface-level failover is needed, this argument is not needed. If i/f
failover is needed and the interface is to be the primary interface set this
argument to /PR=1. If this interface is to be the secondary interface set it to
/PR=2.
Default: /PR=0
/PS
Required
The point source is defined by /PS=pointsourcechar where pointsourcechar
is the character used by the interface tags. For example:
/PS=G
/QT
Optional
Default: none
/RD
Optional
Default: not active
/RN
Optional
Required for interfacelevel
failover
when
multiples instances of
opcint are running on the
same node.
44
This allows you to define a PI tag which will receive the count of how many
items the interface has queued up to go to PI. Under normal conditions, this
number should be fairly 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.
This specifies how many seconds to wait before trying to reconnect to the
server, if we get an error indicating that the RPC server is unavailable or
busy (0x800706ba or 0800706bb).
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.
The /RN argument specifies the resource number if there are to be multiple
instances of opcint running (with different service names) on the same
machine in conjunction, each dependent on a uniquely-named resource,
apionline#. /rn=1 will indicate that the interface is to depend on apionline1
(i.e. will look for the service named apionline1), /rn=2 will indicate that the
interface is to depend on apionline2, and so forth. See Interface-Level
Failover section for 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 #.
OSI Software, Inc.
Parameter
/SERVER
Required
Description
The OPC Server to be used is defined with this command line parameter.
Use the following 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
Optional
OBSOLETE
/SN
Optional
/SQ
Optional
Default: /SQ=N
/ST
Optional
Default: none
The /SIN argument specifies the name of the secondary interface’s node
when i/f failover is to be supported. You must specify the same secondary
interface node in the startup files for both the primary and secondary
interfaces.
The /SN argument indicates that exception reporting is to be turned off and
all data should be sent to the snapshot. Use only for testing.
For "uncertain" qualities, the interface will normally store the value, and
only flag it as "uncertain". Setting this flag to /SQ=Y will cause the
interface to store the quality rather 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.
This allows you to define a PI tag that will get the status of the OPC server.
This should be a digital state tag, set up for manual input as though it was a
lab tag. The possible values 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 0 th 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.
OPC Interface to the PI System
45
Software Configuration
Parameter
/SW
Optional
Default: none
/STARTUP_DELAY
Optional
Description
Status wait. Even with server-level failover enabled, once the interface has
successfully connected to the server, it will wait forever for the server to
enter RUNNING status, or drop 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
If your interface is installed for autostart, but it hangs when the machine
reboots, you may 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
Optional
This argument allows you to specify the format of timestamp strings. The
setting will be used 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
Optional
Timestamp Offset. This parameter allows you to apply an adjustment to the
timestamps, to deal 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
46
OSI Software, Inc.
Parameter
/TS
Optional
Default: /TS=N
Description
This flag determines whether the interface expects to get timestamps for the
data from the interface, or whether it will timestamp the data when it
receives it. Some OPC servers are 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
Optional
/VN=1
Optional
/WS
Optional
The /ur argument sets the requested update rate for the group. This
argument is positional, 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.
The /VN argument is used to tell the interface that the OPC server uses OPC
v1.0a. If this 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.
Once the interface connects to a server that enters the RUNNING state, it
will stay connected 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
/WD2
Optional
The /WD1 and /WD2 arguments can be used if the redundant OPC servers
return OPC_STATUS_RUNNING status when in backup mode as well as in
primary mode.
Please see the section on Watchdog Tags for more
information.
Needed with some servers
for server-level failover.
/WQ=#
Optional
Needed with some servers
for server-level failover.
This setting directs the interface to fail over to the other server if a watchdog
tag has anything but GOOD quality, or if there is an error on reading the
item. Note that v1.0a servers do not return error codes for individual items,
so for version 1.0a servers this flag only checks the quality of the value sent
from the server.
/WQ=1
OPC Interface to the PI System
47
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
OPC Interface to the PI System
49
Interface Operation
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
50
OSI Software, Inc.
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:

Informational messages on startup and shutdown

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.

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.
OPC Interface to the PI System
51
Interface Operation

Error messages for points rejected by the server, or error messages sent from the
server

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.
52
OSI Software, Inc.
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.
OPC Interface to the PI System
53
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
OPC Interface to the PI System
55
Configuring Tags
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
56
exdesc
instrume loc1
loc2
loc3
loc4
loc5
userint1
userint2
OSI Software, Inc.
nttag
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
OPC Interface to the PI System
instrumenttag
loc1
loc2
loc3
loc4
loc5
userint1
userint2
57
Configuring Tags
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
instrumentta loc1
g
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
58
OSI Software, Inc.
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
Not 0
TotalCode
3
SquareRoot
0
DZero
Defined
Operation:
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 Interface to the PI System
59
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
OPC Interface to the PI System
61
OPC Server Issues
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.
62
OSI Software, Inc.
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.
OPC Interface to the PI System
63
Interface Installation
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.
64
OSI Software, Inc.
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
OPC Interface to the PI System
65
Interface Installation
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,
66
OSI Software, Inc.
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
OPC Interface to the PI System
67
Interface Installation
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.
68
OSI Software, Inc.
/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
1BFD63208D4DCE0
2
TransID
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
OPC Interface to the PI System
69
Interface Installation
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
14:54:02.485
960994309.485001 2 1db8
126054680424850000
2000/06/14
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.
70
OSI Software, Inc.
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.
Out of memory:
Can't even allocate a list, dying
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").
Error from CoInitialize:
Error from CoInitializeSecurity:
You may not have COM properly installed on your system. This is a major
problem.
CLSIDFromProgID
The Server's Registry entries are not valid. You'll need to check your server
installation instructions.
CoCreateInstanceEx
This is almost always a problem with DCOMCNFG. See the section on
Configuring DCOM.
OPC Interface to the PI System
71
Interface Installation
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
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)
No ConnectionPoint for OPCShutdown
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.
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.
Unable to advise group
Unable to advise output group
Unable to advise event group
Unable to create group
Unable to add to group
Unable to add to OPC group.
AddGroup failed for scanclass %d
QueryInterface:IID_IOPCAsyncIO2 failed for scanclass %d
72
OSI Software, Inc.
QueryInterface:IID_IDataObject failed for scanclass %d
Advise returns E_OUTOFMEMORY
Advise returns E_UNEXPECTED
Advise returns error
Advise Group failed for %s
No ConnectionPoint for scanclass %d
AddItems failed for tag %s
AddItem failed for %s
Write failed
Write error %X for tag
Read: (some string from server here, we hope)
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.
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.
RemoveItem failed for tag %s
dev_remove_tag: Unable to DUnadvise %s
dev_remove_tag: Unable to remove group %s
OPC Interface to the PI System
73
Interface Installation
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.
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.
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.
Write unable to get values:
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.
No Item name - instrumenttag and exdesc both empty
Unable to get point type
Unable to get square root
Square root must be 0, 1 or 2
Unable to get total specs
Total must be 0,1,2,3,4, or 5
Nonzero Totalcode requires nonzero Convers
This Totalcode requires DZero to be specified.
Point cannot be write and Read On Change
Unable to get source point type.
Event Point has invalid scan class (!= 0)
Point has invalid scan class (== 0)
Point has invalid scan class
ROC Point has invalid scan class (== 0)
These are errors from PI, indicating a tag is improperly configured. Check your
tag configuration.
74
OSI Software, Inc.
GetStatus
This means the OPC server didn't respond to a status query. It may be down or
disconnected.
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).
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.
Cleaning up connections
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.
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.
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.
OnDataChange:Invalid group ID < 0
OnDataChange:Invalid advise group ID:
OnDataChange:Invalid group ID > 999
OnDataChange: Header status:
OnDataChange has format not HGlobal
OnDataChange:Invalid group ID for write completion
Unknown access type for group %s
OPC Interface to the PI System
75
Interface Installation
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.
Got %d and cleared it
ClearWrite: dwTransID mismatch, have %d, got %d
Stashing transid %d
Sending transid %d"
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.
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).
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.
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.
Putsnap system error %d, %d
Putsnap no longer in system error %d, %d
We have/had a problem sending data to PI. These are system errors.
Putsnap error state changed, was %d, now %d
Putsnap no longer in error %d,tag: %s
We have/had a problem sending data for this tag.
Putsnapsx not implemented %d
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.
76
OSI Software, Inc.
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.
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.
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.
Can't find status tag, ignoring
Can't find queue tag, ignoring
Status tag is not Digital tag, ignoring
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.
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.
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.
Running low on memory, dropping data
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.
Failed to open cluster: error ####. Intf-failover will not be supported.
Failed to open cluster resource: error ####. Intf-failover will not be supported.
OPC Interface to the PI System
77
Interface Installation
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.

78
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.
OSI Software, Inc.
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
OPC Interface to the PI System
79
PIOPCTool
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.
80
OSI Software, Inc.
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.
OPC Interface to the PI System
81
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.
OPC Interface to the PI System
83
Appendix
Then run
C:>regsvr32 opccomn_ps.dll
The following dialog box should show up.
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.
84
OSI Software, Inc.
Then you will see the following. Check the information is correct.
Editing entries under Location tab can change this information.
OPC Interface to the PI System
85
Appendix
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).
86
OSI Software, Inc.
Then click on Security tab and make sure it looks like this:
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.
OPC Interface to the PI System
87
Appendix
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
88
OSI Software, Inc.
Now click on Default Security tab. You will see
Click on Edit Default for Default Access Permissions. Make sure that at least all of
the following accounts are there.
OPC Interface to the PI System
89
Appendix
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.
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.
90
OSI Software, Inc.
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.
OPC Interface to the PI System
91
Appendix
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.
92
OSI Software, Inc.
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
OPC Interface to the PI System
93
Appendix
number.
94
OSI Software, Inc.