PI OPCInt-nosdk 2.1.45.0

OPC
Interface to the PI System
version 2.1.45.0
OSI Software, Inc.

How to Contact Us
Phone (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax (510) 357-8136
E-mail techsupport@osisoft.com
World Wide Web http://www.osisoft.com
Mail OSIsoft OSI Software, Ltd
P.O. Box 727 P O Box 8256
San Leandro, CA 94577-0427 Symonds Street
USA Auckland 1035 New Zealand
OSI Software GmbH OSI Software, Asia Pte Ltd

Hauptstrae 30 152 Beach Road
D-63674 Altenstadt 1 #09-06 Gateway East
Deutschland Singapore, 189721
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statementPI 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_350023660.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
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...........................................................................50
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............................................................................................65
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................................................................93

Honeywell APP Node..................................................................................................93
DeltaV System............................................................................................................94
All Servers Built on the FactorySoft Toolkit.................................................................94
Revision History........................................................................................................... 95
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.
15 December 2009 BV 1
Introduction
Configurations
The Preferred Configuration
Another Possibility
2 OSI Software, Inc.

Supported Features
Feature Support
Part Number PI-IN-OS-OPC-NTI
Platforms NT-Intel, W2K, XP
PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 /
Digital / String
Subsecond Timestamps Yes
Subsecond Scan Classes Yes
Automatically Incorporates PI Point Attribute Yes
Changes
Exception Reporting Done by Interface / Done by DCS
Outputs from PI Yes
History Recovery No
*Failover Yes
Inputs to PI: Scan-based / Unsolicited / Event Scan-based / Unsolicited / Event Tags
Tags
Uniint-based Yes
Maximum Point Count Unlimited
SDK Yes
Vendor Software Required on PI API / PINet No
node
* Vendor Software Required on DCS System Yes
Vendor Hardware Required No
* Additional PI Software Included with Yes
Interface
*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 one-
time change to their tag configuration, and set their opcint.bat file accordingly. The
change comes in three steps; you can use SMT to update your tags, or use the piconfig
commands below.
For all tags with a value of 1 in Location1, set Location3=2.
The piconfig commands would be (Change pointsource=O to use your
pointsource!!):
>@tabl pipoint
>@pointclass classic
>@mode edit
>@modify Location3=2
>@select tag=*,pointsource=O,Location1=1
>@ends
Then edit your opcint.bat file to make sure that /ID= has a numeric value, such as
/ID=4.
Finally, set Location1 for all the OPC tags to be the same as your /ID=# parameter in
your opcint.bat file.
>@tabl pipoint

>@pointclass classic
>@mode edit
>@modify Location1=4
>@select tag=*,pointsource=O
>@ends
If you have no output tags (which were signified by Location1=1, and are now signified
by Location3=2), you can leave your current tag configuration in place as long as you
do not use a numeric value in the /ID= parameter. If /ID= does not specify a number,
or specifies 0, the interface will accept all tags with the correct pointsource, regardless
of the value in Location1 of the tag. If you specify a numeric value for /ID=, the
interface will only accept those tags that have the correct pointsource and that numeric
value in Location1.

Overview
Notes on OPC and COM

The general idea behind COM is that using a standard method for passing information
between programs allows us to ignore where a program runs: as long as we can connect
to that program and exchange information, we dont 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 dont 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 dont 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 theres a process device out there, it has some points on
it, the OPC server knows about those points, and its willing to let you touch those
points. This is all arranged by the client (thats us, the OPC interface) creating a Group
and adding points to it, or connecting to a Public Group thats 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
doesnt 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
cant 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, were providing a simple OPC client (PIOPCTool). It has an
internal help, but its really very basic: it looks to see what OPC servers are registered
on your machine and gives you a list to select from. You choose the one you want, and
then press the Connect button. If the server is on another machine, tell it the name of
that machine, and press Connect, and it will ask the other machine what OPC servers it
Overview
has, and add them to its list. (You will need to have OPCEnum installed on both
machines, that's covered later.)
If you cant connect using the PIOPCTool client, then there's no sense even trying the
interface until you've solved the problem. See the sections below on troubleshooting
connections before you go any further. You can also use PIOPCTool to read and write
data. Look at the help inside PIOPCTool for more instructions. If you can use
Refresh and Advise to get data into PIOPCTool, the interface will be able to get
data. Using SyncRead to get data only shows that the server responds to synchronous
calls, it does not show that you will be able to get data into the interface, as the
interface uses only asynchronous calls to get data.
Timestamps
The interface is designed to get timestamps from the OPC server along with the data.
The interface will then adjust those timestamps to match the time on the PI server. This
is done because PI cannot store data in the future, and the OPC interface and/or the
device may have a clock setting which is quite different from that of the PI server. The
adjustments to the timestamps will also correct for clock drift. The interface attempts
to get new timestamps from the PI server and the OPC server every 30 seconds.
If your OPC server does not provide timestamps, or does not provide timestamps for all
data, you may choose to use one of the command-line switches to adjust the behavior of
the interface.
The preferred setting is /TS=Y. This expects the OPC server to provide timestamps,
and will only adjust them to localize them to the PI server.
/TS=N is used if the OPC server cannot provide any timestamps. The interface will
timestamp each value as it receives it and adjust that to the local time of the PI server.
This is the default setting.
/TS=A is used if the OPC server will provide timestamps for Advise tags. Some
servers will return correct values for Advise items, but for polled reads they will return
the time that the value last changed, rather than the time of the read. This option allows
you to use the Advise timestamps, but have the interface provide timestamps for the
polled values, just as it would with /TS=N. This option is only valid for OPC
servers conforming to the OPC Data Access v1.0a standard. The v2.0 standard
does not allow the client to request data without timestamps.
/TS=U allows the user to live dangerously. Timestamps received from the OPC server
will be sent to PI directly, without any adjustment at all. If this results in PI receiving
timestamps that are in the future, the data will be dropped. Use this option with great
caution, and only if there's no other choice, and be sure you check the OPC server
machine's clock against the PI server machine's clock frequently. If you are seeing
error -11049 in your pipc.log file, check the clock on the PI server and on the interface
node; this error means the interface has sent a timestamp, which is outside of the range
for the PI archives.
Writing Timestamps to the Device

Timestamps may be written to or read from the device as data. To read and write
timestamps from a PI tag, where the timestamp is the value of the tag, see the section
below on Datatypes.

For the special case where you need to write the timestamp of an output value to one
ItemID, and the output value itself to another, you can specify the ItemID to get the
timestamp in the ExDesc field. You must also specify whether the ItemID is to be
written as a VT_DATE or as a VT_BSTR (string value). If it it to be written as a
string value, you must have /TF defined in your opcint.bat file, so the interface knows
what format to use to create the string. See the sections on ExDesc and on Command
Line Parameters for more on these settings.
Connections - Creating, Losing, and Recreating

The interface is designed to be very persistent about creating and maintaining a
connection with both the OPC server and the PI archive. If either or both of them are
not available on startup, it will log that fact to the pipc.log file and wait around,
retrying the connection periodically. If it loses the connection to the PI server, it
continue to gather data and try to send it to PI, while it tries to re-establish the
connection to PI. Use of the API buffering program (bufserv) is strongly recommended,
to avoid losing data if your PI system is unreachable. If the interface loses the
connection to the OPC server, it will keep trying to re-establish that connection (see the
section on Failover for alternative strategies).
If the connection to PI is lost, the only thing visible from the PI side is that no data is
coming in. But the interface accepts two command-line parameters that will let you use
PI tags to monitor the connection with the OPC server and watch how much data is
waiting to be passed over to PI. These are the /ST and /QT parameters. See
Software Configuration: The Interface File for more information on using them. The
interface will only write to these tags when the value has changed.
The interface also monitors the server status reported by the OPC server. On startup, it
will wait around for the OPC server to report that it is in RUNNING state, before
beginning the process of creating groups and adding items. To accommodate broken
servers that don't return the proper state code, you can use the /IS flag in the
opcint.bat file (see below for more on that).
The OPCEnum Utility

The OPC Foundation has provided a tool to allow clients to access servers on remote
nodes, without having to have information about those servers in the local registry.
That tool is OPCEnum. It will be installed with the interface, but you will need to set
the DCOM permissions (using dcomcnfg.exe) to allow it to communicate with
OPCEnums on other systems. The only thing that OPCEnum does is tell other
instances of OPCEnum what OPC servers are on the local system, and it can ask other
OPCEnums what OPC servers are on their systems. You should give Access and
Launch DCOM permissions to SYSTEM, NETWORK, INTERACTIVE, and at least
to the Userid which you expect to be using for the interface, although giving permission
to Everyone is quite safe.
While the interface and DCOM, and the PIOPCTool itself, only require NT4 with
Service Pack 3, OPCEnum requires at least SP4 and it requires that you have Internet
Explorer 4 or higher installed. See the help in the PIOPCTool for more information
about OPCEnum and how to use it.
If your OPC server is on a different system, and your OPC server does not install
OPCEnum, you can copy the contents of the OPCEnum directory (it's right below your

Overview
interface directory) to the OPC server system, and then run register.bat on that system.
You'll need to be logged into a userid on the server system that has administrative
privileges. Again, check DCOM permissions.
Plug-In Post-processing DLLs

The interface has the ability to use plug-in DLLs. These are libraries of routines that
do application-specific data processing before the data is sent to PI. The DLLs and
their accompanying files and documentation can be obtained separately from OSI, and
are installed into the Plug-Ins subdirectory under the interface directory. Please refer to
the "Plugins Readme.txt" file in the Plug-Ins directory for how to install the plug-in
packages. Each plug-in package contains the documentation for how to use that
specific package.
Polling, Advising and Event Tags

The OPC interface has three methods of getting data: advising, polling, and event reads
(also known as triggered reads). For Advise tags (called ReadOnChange in the OPC
standard), the OPC server sends data whenever a new value is read into the server's
cache. For polled points, the interface sends an asynchronous Refresh for the group.
For event reads, the PI server tells the interface when the trigger point has a new event
(not necessarily a change in value), and the interface sends an asynchronous Read for
the tags attached to that trigger. All three kinds of points are read asynchronously, and
the same data routines process all updates.
Polled tags are grouped by scan class; all tags in a scan class will be in the same group.
Since reads are done on a group level, it is best to not have too many tags in one group.
You can have multiple scan classes with the same scan rate; use the offset parameter to
ensure that the load on the interface is smooth, rather than having the interface attempt
to read all your tags at the same time. It is strongly recommended that you not mix
advise tags and polled tags in the same scan class.
Advise tags will be grouped by the interface, if they are in scan class 1. You specify a
scan class for advise tags, just as you do for polled tags, but for tags in scan class 1 the
interface will automatically limit the number of tags in an advise group to 800. Up to
800 tags will be put into a group, if they all have the same deadband. If there are more
than 800 tags with the same deadband in scan class 1, the interface will create as many
groups as are needed. If you would rather group your advise tags yourself, you can use
any scanclass. It is strongly recommended that you not mix advise tags and polled tags
in the same scan class.
Event tags (triggered reads) are usually used to gather a set of data points after a
particular event has occurred. The PI tag which triggers the read is named in the
ExDesc field. When a new event for a trigger tag is sent to the PI snapshot, the PI
system informs the interface of this and the interface then goes out to read the values
for all the associated event tags from the OPC server. For v1.0a servers, this is done
with an asynchronous read to the servers 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 isnt reasonable. That means that if you read a value as a
string, and want to put it into an Int32 tag, the string has to have a number in it. If you
read a value as VT_R8 (a 64-bit floating point value), and want it put into an Int16 tag,
the value read has to fit into an Int16 tag, even though a VT_R8 can hold a much larger
number than you can fit into an Int16.
Reading Digital, Integer, and Real Tags as Strings

Tags that are defined as Digital State tags in PI are generally read and written as
integer values, and those values correspond to specific strings in the Digital State table
specified in the tag's Digital Set property. Since some devices read and write the string
rather than the integer value, you can have Digital State tags which are read and written
as though they were String tags, by setting Location2 = 1. You must make sure that
the strings used by the OPC server are exactly identical to the strings in the Digital Set,
including case, punctuation, and spacing.
Other OPC servers cannot serve up certain numbers as numeric, they can only provide
the character strings. For these servers, you can also set Location2 = 1 for Int16,
Int32, Float32, and Float64 tags, and the interface will request the data as a string
(BSTR) and try to read the resulting data as a number.
Reading Tags as Booleans

Some servers appear to have been written to not only send boolean values as 0 and -1
when read as VT_BOOL (as specified by Microsoft's definition of a VARIANT of type
VT_BOOL), but also to send the same values when read as integers. This creates a

Overview
problem when you want to read that data into a PI Digital State tag, since "-1" is not
actually what you want stored. While most servers appear to handle this properly, to
handle the data from ill-behaved servers, the interface will take the absolute value of
any integer or real values read for digital state tags. Since digital state tag values are
actually offsets into the digital state table for the tag, and a negative offset has no
functional meaning, this should not cause problems for properly written servers. This
is in no way intended to validate or encourage such broken behavior on the part of
servers. It is simply to allow clients to use them even though they're broken.
You may also have the interface request the item as a boolean (VT_BOOL). This will
only work for items which truly only have two possible states, as any nonzero value
will be interpreted as a "1". To have tags read and written as though they were
booleans, set Location2 = 2.
Reading Tags as 4-byte Integers

If your OPC server doesn't want to send your data as a 2-byte integer (VT_I2), you can
set Location2 = 3 to have the interface request the data as a 4-byte integer
(VT_I4). Of course, this uses up more resource, so only use it if you have to.
Reading Tags as Float64 Values

Likewise, if your OPC server will only give you a particular value as an 8-byte floating
point number (VT_R8), you can set Location2 = 5 to have the interface request
VT_R8 even though you'll be storing it to, for instance, a 4-byte floating point tag.
There may be some loss of precision, and if the number is too large to fit inside your
tag, you will see a status of BAD stored to the tag.
Converting Timestamps into Seconds

Setting Location2 = 6 tells the interface that the OPC Item is a string
(VT_BSTR) that will have a timestring value in it such as "2000/11/02 15:34:29". The
format of the strings must be supplied in the command file (opcint.bat) with the /TF
switch. See the section below on Timestamp Strings for how to create that format.
If the PI tag is an integer tag, the interface will attempt to translate the timestamp into
whole seconds and store that in PI (remember that Int16 tags can only hold numbers up
to 32767, so for time spans longer than 9 hours you'll need Int32 tags). If the PI tag is
a Float tag, the timestamp will be translated into seconds and stored as a floating-point
number. The interface will not perform any adjustments on the timestamps received,
regardless of the timezone settings or /TS switch on the command line. However, if
you configure the tag to use scaling or transformation, that operation will happen after
the string has been translated into seconds, so you can actually handle a wide range of
values.
Reading Timestamps as VT_DATE Datatypes

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

Timestamp Strings
Only one format string may be specified for an instance of the interface, so if you need
to process more than one format of timestamp string, you will have to use more than
one copy of the interface. The interface will make a copy of your format string, and
will then replace the tokens with the actual values, to create a string. To read a string,
it will look for numbers that are in the same position as the tokens, and use those
numbers as values.
The tokens that the interface recognizes are:
cc 2-digit century
yy 2-digit year
mn 2-digit month
mon month as a 3-character abbreviation, one of the following:
Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
dd 2-digit day
hh 2-digit hour from 0 to 23
hr 2-digit hour from 0 to 12
mm 2-digit minute
ss 2-digit second
3-digit milliseconds
XM either AM or PM
You can put those tokens together in any way, with anything or nothing between them.
What matters to the interface is where in the string the tokens are found. It reads from
left to right, looking for a recognizable token. So, some common format strings and
example timestamps:
"ccyy/mn/dd hh:mm:ss.000" "1998/11/29 15:32:19.391"
"dd mon, ccyy hr:mm:ss XM" "29 Nov, 1998 03:32:19 PM"
"mn-dd-ccyy hh:mm:ss" "11-29-1998 15:32:19"
"hh:mm:ss.000" "15:32:19.482"
Not Specifying a Datatype

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

While OPC servers can perform their own transformations and scaling, some users
have found that the desired functions are not filled by their server. So, you can
configure your PI points so that the interface will perform transformations and scaling

Overview
for you. Note that transformation and scaling happens before the value is compared to
the exception parameters for the tag, so the exception parameters are applied to the
value that would be sent to PI, rather than to the raw value.
Scaling
Scaling is fairly complex, and is controlled by the TotalCode and SquareRoot
properties of the tag. Since we're limited in what information we can get about the tag,
the Convers property is used to carry the Span of the device, and the ExDesc does
further duty to carry the device Zero (DZero). Thus you can have the interface
translate a value from the scale of what the device can send to the scale of the actual
tag.
If TotalCode is zero, the only scaling that will be done is based on the value of
SquareRoot. If Square Root is a 1, the value read will be squared before sending it to
PI, and for an output value the square root will be taken before writing to the device. If
SquareRoot is a 2, the opposite happens: for values read from the device, the square
root of the value read will be sent to PI, while output values will be squared before
sending them to the device.
If TotalCode is non-zero, some other scaling may be done, either to transform the value
read into another scale of measurement or to apply an offset or conversion factor. Just
as the value stored in the tag ranges from (Zero) to (Zero + Span), so the values read
from or written to the device can range from (DZero) to (DZero + Convers). This
allows the value stored in PI to be a simple transformation from one scale to another.
The SquareRoot property can be used to specify that the square or square root of the
value should be used rather than the value itself. In other cases, the Convers value may
be added to or subtracted from the value, or may be used as a multiplier, or applied as a
bitmask. Again, the SquareRoot code may specify using the square or square root of
the value, rather than the raw value, as the input to the formula.
Scaling is only supported for numeric tags. You may have a tag defined in PI as a
number, yet the OPC server reads and writes the Item as a string, and those tags would
support scaling. But if the PI tag is defined as a string , any scaling will be ignored.
The table below covers all the scaling formulas currently used. Again, if SquareRoot is
a 1 or a 2, the square root or square of the value will be calculated first, and then the
formula will be applied.
Convers TotalCode SquareRoot DZero Operation:
0 0 0 Don't care Value = value
0 0 1 Don't care Input tags:
Value = (Value)2
Output tags:
Value = (Value)0.5
0 0 2 Don't care Input tags:
Value = (Value)0.5
Output tags:
Value = (Value)2

Not 0 1 0 Defined Input tags:
Value = [ (Value DZero) / Convers ] * Span +
Zero
Output tags:
Value = [ (Value - Zero) / Span] * Convers +
DZero
Value = [ ((Value)2 DZero) / Convers ] * Span
+ Zero
Output tags:
Value = [ ((Value)0.5 - Zero) / Span] * Convers +
DZero
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
Value = (Value)2 * Convers
Output tags:
Value = (Value)0.5 / Convers
Value = (Value)0.5 * Convers
Output tags:
Value = (Value)2 / Convers
Value = (Value / Convers) DZero
Output tags:
Value = (Value + DZero) * Convers
Value = ((Value)2 / Convers) DZero
Output tags:
Value = ((Value)0.5 + DZero) * Convers
Value = ((Value)0.5 / Convers) DZero
Output tags:
Value = ((Value)2 + DZero) * Convers
Value = (Value - DZero)/ Convers
Output tags:
Value = (Value * Convers) + DZero

Overview

Value = ((Value)2 - DZero)/ Convers
Output tags:
Value = ((Value)0.5 * Convers) + DZero
Value = ((Value)0.5 - DZero)/ Convers
Output tags:
Value = ((Value)2 * Convers) + DZero
Value = Value + Convers
Output tags:
Value = Value - Convers
Value = (Value)2 + Convers
Output tags:
Value = (Value)0.5 - Convers
Value = (Value)0.5 + Convers
Output tags:
Value = (Value)2 - Convers
Not 0 6 Don't care Don't care Input tags:
Value = Value AND Convers
Output tags:
Value = Value AND Convers
Value = Value OR Convers
Output tags:
Value = Value OR Convers
Value = Value XOR Convers
Output tags:
Value = Value XOR Convers
Quality Information
The OPC Data Access standard uses Fieldbus quality flags. The interface translates
those quality flags to the closest approximation within the PI System State table. The
low 8 bits of the Quality flags are currently defined in the form of three bit fields,
Quality, Substatus and Limit status. The 8 Quality bits are arranged as follows:
QQSSSSLL
The tables at the end of this section give the transformation to PI status. The second
table gives the status codes that will be used if the PI system is version 3.3 or newer.
That version of PI is the first that defines the states needed by the OPC interface, so
that the interface will not use the Archive Offline and other states which were causing
some confusion.

Questionable Qualities -- Store the Status or the Value?
Because the PI archive stores either the quality or the value, the interface will translate
the qualities in the questionable category to GOODSTAT, and set the questionable
value flag for the data value. Bad quality flags get the corresponding PI status
stored for the tag. If the quality is SUBSTITUTED_ST, the interface will currently
store the status rather than the value sent. You can change this behavior with the /SQ
flag in the opcint.bat file. Setting /SQ=Y flag will cause the interface to store the
quality (translated to a PI status) if the quality is anything but GOOD. Similarly, if
you set /SQ=I, the interface will ignore the "questionable" quality, and treat the value
as if it had good quality.
Quality no /SQ flag /SQ=Y /SQ=I

GOOD value value value
Questionable value, flag digital state value
BAD digital state digital state digital state
Storing Quality Information Directly

You also have the option of storing the quality in a separate PI tag, so you can keep
both the values reported and also the qualities that came with those values, with no loss
of granularity. Setting Location2=4 for a tag tells the interface that you want to
store the quality for the associated OPC Item, rather than the value. Since OPC
qualities are unsigned 16-bit integers, we expect to have an Int32 tag to receive them.
The values are stored in PI without any change, and their status is always GOOD. To
understand what those quality values represent, please go to
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 OPC Definition PI Status
11SSSSLL Non-specific Good
Except
110110LL Local Override _SUBStituted
Not used by OPC

10SSSSLL Invalid Bad Input

Overview
Questionable
010110LL Sub-Normal Bad_Quality
010101LL Engineering Units Exceeded
QQSSSS01 Low Limited Under LCL
QQSSSS10 High Limited Over UCL
Otherwise Inp OutRange
010100LL Sensor Not Accurate
QQSSSS01 Low Limited Under Range
QQSSSS10 High Limited Over Range
Otherwise Out of calibration Invalid Data
010011LL Invalid Bad Input
010001LL Last Usable Value No_Sample
010000LL Non-specific Doubtful
Bad Quality
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
11SSSSLL Non-specific Good
Except
110110LL Local Override _SUBStituted
Not Used by OPC

10SSSSLL Invalid Bad Input

Questionable
010110LL Sub-Normal Bad_Quality
010101LL Engineering Units Exceeded
QQSSSS01 Low Limited Under LCL
QQSSSS10 High Limited Over UCL
Otherwise Inp OutRange
010100LL Sensor Not Accurate
QQSSSS01 Low Limited Under Range
QQSSSS10 High Limited Over Range
Otherwise Out of calibration Invalid Data
010001LL Last Usable Value No_Sample
010000LL Non-specific Doubtful
Bad Quality
000111LL Out of Service Out of Service
000110LL Comm Failure Comm Failure
000101LL Last Known Value Scan Timeout
000100LL Sensor Failure Equip Fail
000011LL Device Failure Unit Down
000010LL Not Connected Not Connected
000001LL Configuration Error Configure
000000LL Non-specific Bad

PI Point Configuration
Point Attributes
The following information is necessary to define a PI tag for use with an OPC Server.
Failing to configure your tags will mean that the interface cannot communicate
properly with the OPC server. See the section on Error Messages for information on
how to recognize configuration problems. Also, see the Sample Configuration section
for examples.
PointType
The interface itself supports all PI point types except the BLOB, but not all OPC
servers will support all point types. Refer to the vendor-supplied documentation for
your OPC Server to determine what point types are supported by the specific server. If
the point type defined in PI does not match the canonical data type defined in the OPC
server, the interface will attempt to translate the data. If you have a question about
whether the point can be read as the type you want, use the PIOPCTool to try to read
the point directly from the OPC server. Also, see the Datatypes section for special
settings that may help you get around recalcitrant servers.
PointSource
All tags defined in the PI database and used by the OPC interface must share a
common point source. The point source is a one character variable, for example, G. On
a PI 2 system, the point source for the interface must be defined in PI before interface
operation or tag definition.
Several subsystems and applications that ship with PI 3 are associated with default
point source characters. The Totalizer subsystem uses the point source character T, the
Alarm subsystem uses G and @, and PI Performance Equations uses C. One should
either not use these point source characters or change the default point source
characters for these applications. Also, if one does not specify a point source character
when creating a PI point, the point is assigned a default point source character of L.
Hence, it would be confusing to use L as the point source character for an interface.
The following point source characters are reserved on PI 2 systems and cannot be used
as the point source character for an interface: C, ?, @, Q, T.
InstrumentTag
This field contains the ItemID for the tag. The format of this field depends on the
specific OPC server being used. Refer to the documentation for your server to
determine the proper format. This field must exactly match the point defined to your
OPC server. That means punctuation, spaces, uppercase vs. lowercase, everything.
This field must exactly match the point defined to your OPC server. For PI3 systems,
this field can be up to 1023 characters long. For PI2 systems, the limit is 32
characters. If your point identifier is longer than 32 characters, use the ExDesc field.
To verify an ItemID, use the PIOPCTool. If your server supports browsing, you can
use List Server's Tags to see a list of defined ItemIDs. Doubleclicking on an ItemID in
the tree will result in the full ItemID being displayed in the Item field. This is the
ItemID that you want to use in InstrumentTag.
ExDesc
The extended descriptor field is used for multiple purposes.
To indicate event-based data collection:
To define an event tag, this field will contain event=tagname, where tagname is
any valid PI tagname. When that tag has an exception event, the points for which it
is the event, or "trigger", will be read from the OPC server.
For long instrument tags:
If the instrument tag for this point is longer than 32 characters and you are using a
PI2 system, you can put the instrument tag here in the form instr=whatever.the-
opc/server*needs. Again, the instrument tag must exactly match the ItemID
defined to your OPC server. If the instrument tag contains a comma, enclose the
tagname with double quote characters (), such as:
Instr=whatever.you, or someone*needs*
To specify DZero for scaled tags:
For tags where the range of values which the device returns must be scaled to fit
the range of values the tag stores (such as scaling from device voltage to
temperature in degrees Celsius), you will use the Convers field to store the device
Span, and you must store the device Zero here in the ExDesc. The format is
DZero=nnnnn.nnn
To specify the ItemID to receive the timestamp for an output value
When you need an output value to go to one ItemID, and the timestamp that comes
with the output value to go to another ItemID, you can specify the timestamp
ItemID here. Thus, the ItemID specified in your instrumenttag field will get the
value, and the ItemID specified in the ExDesc field will get the timestamp that goes
with that value. The same restrictions apply to this ItemID as are stated above,
under "For long instrument tags". There are two formats, depending on the
datatype of the ItemID that is to receive the timestamp.
Tim=ItemID
Dat=ItemID
Both of these formats will write the date and time. The difference is that using
Tim= will tell the interface to write the timestamp as a string (VT_BSTR),
formatted according to your /TF setting in the opcint.bat file, while using Dat= will
tell the interface to write the timestamp as a VT_DATE. When written as a
VT_DATE, the timestamp is in universal (UTC) format, so there is no dependence
on timezone or daylight savings time setting. When written as a string, the
timestamp is that of the PI server, and is not adjusted for differences in timezone or
daylight savings time setting. The timestamp written to the OPC server is the same
timestamp you would see if you were on the PI machine and looked at the database
timestamp.
Please note that in error messages relating to this timestamp ItemID, the interface
will report a generated tagname of the form TS:xxxxxx, where xxxxxx will be the
PI tagname of the output tag.

If you use this field to specify more than one of the above items, put a comma between
the definitions.
This field can contain 80 characters for a PI2 system, or 1023 for a PI3 system.
A Note on Performance Points

Those familiar with other PI interfaces may have used "Performance Points" before.
These tags document how long it takes to complete a scan. Due to the architecture
of this interface, performance points are not valid -- the server's response is
asynchronous, so the time to "scan" bears no relation to the amount of time it may
take to get the data from the server.
SourceTag
To specify the source tag for an output point, this field will contain a valid PI tagname.
On an exception for that tag, the value in the source tag will be written to the OPC
point defined in the InstrumentTag (or in ExDesc) and also to the output tag. For an
output point with no SourceTag defined, when the output tag itself has an exception,
the value of the output tag will be written to the OPC point. For output points, the
timestamp of the trigger value must be greater than (not greater than or equal to) the
timestamp of the previous value.
Scan
This field is a flag to indicate whether the value for this point should be read. The
intention is to allow tags to be defined but inactive. A value of On in this field will
allow the point to be active; a value of Off will disable it. Disabled points will be
ignored, both for reading from the OPC server and writing to the OPC server.
Totalcode
This field holds the code used to indicate what scaling to apply to the value. The
SquareRoot, Convers, and ExDesc fields may also be needed. See the section on
Scaling for a complete description of how to use this field. Valid values are 0 through
5, with 0 the default.
SquareRoot
This field is used to indicate that the value stored in PI or written to the device should
be squared first, or the square root should be found. See the section on scaling for a
complete discussion of its use. Valid values for this field are 0, 1, and 2. The default is
0.
Convers
This field is used for scaled tags to hold the device span. Just as a PI tag has a zero
and a span, which together define the legal range of values, the device Item may have a
DZero and a DSpan, which define the actual span of values, which the device will send.
The interface can use those two ranges to translate from the units used by the device to
the units defined for the PI tag. The Convers field may also hold an offset or multiplier.
See the section on Scaling for how to use this functionality.

Location1
The first location field specifies the interface instance number. In the opcint.bat file,
there is a parameter for interface ID, /ID=#, where # is any number. The Location1
field for each tag must match that number, or the tag will be ignored. So if your
opcint.bat file has "/ID=4", and "/PS=O", the only tags with pointsource=O and
Location1=4 will be used by that copy of the interface. This lets you have multiple
interfaces use the same pointsource, each with their own ID. In the pipc.log file, the ID
shows up as the last identifier on each line, for example
26-Mar-00 23:24:50
OPCpi> 1> API version> 1.3.1.3
shows a 1 in the ID field, so that message was printed by the interface with ID=1 in its
opcint.bat file.
If /ID= does not specify a number, or specifies 0, the interface will accept all tags with
the correct pointsource, regardless of the value in Location1 of the tag. If you specify a
numeric value for /ID=, the interface will only accept those tags that have the correct
pointsource and that numeric value in Location1.
Location2
This field is used to indicate special handling. See the discussion on Datatypes for
more information.
Location2 = 0
Normal processing
Location2 = 1
If Location2 is a 1, the value in the OPC server will be read as a String, and written as
a String. For Digital tags, this will only work if the strings read from the OPC server
are an exact match for the strings in the Digital State Set used by the tag. See the Data
Archive Manual for a complete discussion of Digital State sets and Digital State tags.
For Integer and Real tags, setting Location2 = 1 will cause the interface to request a
string value, and then try to translate that string value into a number.
Location2 = 2
If Location2 is set to 2 for a Digital State tag, the value will be read as a Boolean.
Booleans can have only two values, zero and nonzero; you can only use Location2=2 if
your Digital State Set only has two values. Likewise, for numeric tags, any value but 0
will be True (-1), and a value of 0 will be False (0).
Location2 = 3
If Location2 is set to 3, the value will be read as a 4-byte integer. This setting is
included to accommodate servers, which cannot send the value as a 2-byte integer,
which is how Digital tags are normally read.
Location2 = 4
This setting will cause the interface to store the quality of the item rather than the
value. This allows us to store the value of the item in one tag and the quality in
another.

Location2 = 5
This setting is for floating point numbers. By default, the interface will request Real
tags as VT_R4 items (4 byte reals). If Location2 is set to 5, the interface will request
Real tags as VT_R8 items (8 byte reals). For Float32 tags, including all PI2 Real tags,
values that cannot be stored in a 32-bit floating point number will be dropped, and in
any case some of the precision of the R8 will be lost in translation. This setting is
included to enable the use of servers, which refuse to translate R8 data to R4 tags
themselves, or to allow the use of Float32 tags where the benefit of greater precision is
not worth the overhead of using Float64 tags.
Location2 = 6
This setting allows us to read timestamps from the OPC server as strings, and
transform those strings into a number of seconds. The PI tag may be an Int or a Float.
The format of the timestamp string is specified in the opcint.bat file with the /TF
switch, and the same format is used for all tags. For more information on this, see the
section above on Datatypes.
Location2 = 7
This setting allows us to read timestamps from the OPC server as VT_DATE variables.
These values can either be translated into timestamp strings or passed to PI as a
number of seconds, suitable for use in computations. If the value is translated into a
string, the timestamp format specified with the /TF switch will be used. For more
information on this, see the section above on Datatypes.
Location2 = 8
This setting will cause the interface to ask the server to give us whatever datatype it
would like to give us. The interface will try to transform the value into the proper
datatype for the PI tag. This may not be possible in all cases, so use this with caution,
and only when your server is broken and will not provide data if you specify a datatype.
It's always better to specify what type of data you want to get, unless the server will not
honor such a request.
Location2 > 1024

For passing array data directly to a dll, you can combine any of the above Location2
settings ( 0 through 7) with 1024, to indicate that both the indicated setting ( 0 - 7)
should be in effect, and that the tag is also a series array tag. For more information, see
the manual for the TimeArray plugin module.
Location3
This field is used to indicate whether this tag is to be polled, advised, or output. A
value of 0 indicates a normal polled tag or event tag, a value of 1 indicates an advise
tag, and a value of 2 indicates that the tag is an output tag. For an advised tag, the
OPC Interface will sign up for updates with the OPC Server, and the PI tag will be
updated every time the value in the point changes. To minimize noise, you can use
Location5 to indicate the desired deadband: if the change between the last value read
and the new value is less than the deadband, the new value is ignored. This deadband
processing is only valid for points which are defined in the OPC server as Analog.
Care should be used when defining points as advised, as a point without a deadband
can cause a great deal of data to be gathered very quickly. Deadband processing is

optional for servers under the OPC standard: be sure that your server supports
deadband processing before attempting to configure tags for advise.
Location4
Scan class number. Scan classes are defined in the interface startup file; each scan
class defines an update period. This location code defines which scan class period is
used to update the PI point.
The updates from the OPC server come in groups: at start-up, the interface defines a
group on the OPC server and adds all points within the given scan class to the group.
Up to 200 groups, and thus 200 scan classes, can be defined. The OPC server is
queried for all points within a group at the same time, therefore some consideration
should be given to the creation of scan classes. Having more than one scan class with
the same scan period is allowed, and using different offsets on those scan classes may
help performance. See the section on The Interface File, below, for more on offsets.
Event based points and output points do not use this location code, and its value for
those points must be zero.
Advise tags use this location to specify the Requested Update Rate for the group: the
OPC server will only check for new values as frequently as this, which allows you to
use a larger value for points which don't change often, to lighten the load on your
machine. By convention, the first scan class is reserved for advise tags. Other scan
classes can also be used for advise tags, but any tags which use the first scan class and
are not advised will not be polled. If there are more than 800 tags in the first scan
class, they will be broken up into multiple groups, with each group having no more
than 800 tags. If you need to have all the advise tags in the same group, you must use
another scan class.
While it is possible to have advise tags and polled tags in the same scan class, it can
cause odd problems, and the performance of the interface under those conditions is not
guaranteed. It is strongly advised that you do not have advise tags and polled tags in
the same scan class.
Location5
This field is used with Location3 for tags that are to be advised to define a deadband
value which will be used by the OPC server. This is separate from the Deadband in PI,
and proper use will result in fewer data points being sent to PI.
For this field to be valid, the corresponding point in the OPC server must be defined as
an Analog point, and the EuMin and EuMax fields in the OPC server point definition
will delimit the value range for the point (these correspond to the Zero and Span fields
in the PI point definition, but here were specifically referring to the point as defined in
the OPC server). The Location5 value is a percentage of that range, measured in
hundredths. Thus, if the OPC server point is defined as Analog with an EuMin of -10
and an EuMax of 10, and Location5 contains 2500 (meaning 25%), data will only be
sent to the PI tag when the difference between the new value and the old value is at least
5 (25% of 20 = 5).
Note: Deadband processing is optional behavior for OPC servers. If the server does
not support deadband processing, the PI tag will be updated for all value changes to
the point. If you are unsure of whether your server supports deadband processing,
use the PIOPCTool to check.

Userint1
This field is used to give the index number for a tag within an array. The OPC
standard supports reading data as an array of values; the array has one timestamp and
one quality, with multiple values attached to them. To map these values to PI tags, we
use the Userint1 field to give the one-based index into the array for each tag. Thus, the
first value in the array will correspond to the tag with Userint1=1, the second to the tag
with Userint1=2, and so on.
All the tags that belong to the same array must have exactly the same values in
InstrumentTag, ExDesc, and all Location fields. The tag names can be whatever you
like.
Note: All tags that are not part of an array must have a zero in Userint1.
Userint2
This field is used to designate an event group for an event tag. See the section on
Configuring Event Tags for more on this topic.
Note: All tags that are not event tags must have a zero in Userint2.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on
for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0
when the interface starts, SCAN OFF will be written to the PI point. If the scan
attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be
written to the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where Uniint
will write SCAN OFF to a PI point. If a point that is currently loaded by the interface
is edited so that the point is no longer valid for the interface, the point will be removed
from the interface, and SCAN OFF will be written to the point. For example, if the
PointSource of a PI point that is currently loaded by the interface is changed, the point
will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. See data archive
(DA) section 4.2.3 of PI System Manual I for information on configuring shutdown
events for PI 2.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the pishutev
subsystem is to write the SHUTDOWN digital state to all PI points when PI is started.
The timestamp that is used for the SHUTDOWN events is retrieved from a file that is
updated by the snapshot subsystem. The timestamp is usually updated every 15
minutes, which means that the timestamp for the SHUTDOWN events will be accurate to
within 15 minutes in the event of a power failure. For additional information on

shutdown events, the reader is referred to the PI Data Archive Manual for NT and
UNIX. Note that the SHUTDOWN events that are written by the pishutev subsystem are
independent of the SHUTDOWN events that are written by the interface when the
/opcstopstat command-line argument is specified.
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a
utility program that provides the capability to store and forward events to a PI server,
allowing continuous data collection when the server is down for maintenance, upgrades,
backups, and unexpected failures. That is, when PI is shutdown, Bufserv will continue
to collect data for the interface, making it undesirable to write SHUTDOWN events to
the PI points for this interface. Refer to the Bufserv manual for additional information.
One can disable SHUTDOWN events from being written to PI when PI is restarted by
setting the Shutdown attribute to 0 for each point. Alternatively, one can change the
default behavior of the pishutev subsystem to write SHUTDOWN events only for PI
points that have their Shutdown attribute set to 0. One can change the default behavior
by editing the \PI\dat\Shutdown.dat file, as discussed in the PI Data Archive Manual
for NT and UNIX.
Exception processing
The OPC interface handles exception processing a little differently from standard OSI
interfaces, in order to allow exception processing for Advise tags. The ExcMin,
ExcMax, and ExcDev parameters perform the usual functions, but unlike standard
interfaces, if you set ExcMax to 0, you can still use values in ExcMin and ExcDev.
The three parameters operate independently, and you must set all three to 0 to have the
interface send every value to PI. See your PI manual for more on exception processing.
ExcMax
The longest time period between values sent to PI. Note this also works for Advise
tags, so if we have not received a value after ExcMax seconds, and we've no indication
that communication with the server has failed (we do check the clock every 30
seconds), we'll assume that the value has remained the same and will send the last value
received to PI, with the timestamp set to the current time. For Polled tags, a value will
be sent to PI if we haven't sent one in the last ExcMax seconds, even if the new value
doesn't pass ExcDev tests.
ExcMin
The minimum time between values sent to PI.
ExcDev
The minimum change, from the last value sent to PI, which will cause a new value to be
seen as an event and sent to PI.

Software Configuration
In addition to PI Point definitions, the point source, digital states, and the I/O rate
counter need to be configured.
Point Source -- PI 2
The point source may be any alpha-numeric character not currently used by another
process or interface. The point source is defined by running the Point Src display on
the PI menu, choosing a blank field location from the point source list, and entering the
following location parameter limits:
Point Source Character (char)
Point Source Description OPC
Location 1 Location 2 Location 3 Location 4 Location 5
0 0 0 0 0
9999 5 2 200 10000
Point Source -- PI 3
Choose a single alpha-numeric character not currently used by another process or
interface. Enter this character into the pointsource attribute for each of the interface
tags.
Digital States -- PI 2
Digital states are defined by running the Digtl Stat display from the PI menu. The
states must be contiguous for each status type. The digital states need to be defined
prior to point configuration. For more information, see the DA manual.
Digital States -- PI 3
A digital state set is a group of digital states that are related. For instance, ON/OFF
may be a digital state set where the zero of the tag is ON and a value of one for the tag
denotes OFF. Each state set has a name, and that name must be in a tag's Digital State
Set field in order for that tag to use that state set. Tags may also use system state sets
for conditions such as "I/O Timeout" and to store quality information when the data
received from the OPC server indicates a problem with the quality of the value.
IO Rate Points
An IO Rate point can be configured to receive 10-minute averages of the total number
of exceptions per minute that are sent to PI by the interface. An exception is a value
that has passed the exception specifications for a given PI point. Since 10-minute
averages are taken, the first average is not written to PI until 10 minutes after the
interface has started. There are two configuration steps.
Step 1 PI Point configuration on the PI Server

For step 1 and 2, it is assumed that the name of the PI tag is OPCRate.
PI 3 Server Nodes
Create an IO Rate Tag with the following point attribute values.
Attribute Value
PointSource L
PointType float32
Compressing 1
ExcDev 0
The default settings can be used for the remaining PI Point attributes. However, one
may wish to adjust the compression specifications (CompDev, CompMin, CompMax,
and CompDevPercent) to control the amount of data that is archived owing to the IO
Rate point.
PI 2 Server Nodes
Create an IO Rate Tag using one of the existing IO Rate Tags as a template. A listing
of IO Rate Tags can be found on page DA-71 of PI System Manual I.
Step 2 Configuration on the Interface Node

For step 2, it is assumed that the name of the IO Rate point on the home node is
OPCRate.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME
directory is defined either by the PIPCSHARE entry or the PHOME entry in the
pipc.ini file, which is located in the \WinNT directory. If both are specified, the
PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C: \PIPC, the full name of the iorates.dat
file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
OPCRate, x
where OPCRate is the name of the IO Rate Tag and x corresponds to the first
instance of the /ec=x flag in the startup command file. x can be any number
between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an
event counter, x, that is not equal to 1 because 1 is the default event counter for
UniInt-based interfaces. Set the /ec=x flag on the startup command file of the
interface to match the event counter in the iorates.dat file.
2. The interface must be stopped and restarted in order for the IO Rate tag to take
effect. IORates will not be written to the tag until 10 minutes after the interface is
started.
3. The 10-minute rate averages (in events/minute) can be monitored with a client
application such as Processbook.

Command-line Parameters
Before the interface starts, a file containing the configuration parameters must be
created. The command line arguments will need to be modified for your site and
interface.
At startup, the interface interprets the command line arguments. The command line
arguments define the point source, scan frequency, and many options for how to
communicate with the OPC server and how to process the data received. All arguments
must begin with a /, have a space between them, and have no spaces within the
argument. The arguments are not case sensitive. A point source, scan class, and OPC
server must be defined for the interface to start.
This list groups the arguments by usage, to show what options are available. The
alphabetical listing that follows gives details about each argument and how it is used.
It is strongly suggested that if you can use the PI ICU (Interface Configuration Utility),
you should do so. This tool is freely available from our web site, and can make
configuring the interface much simpler. It is only available for interfaces that are
connecting to PI3 systems of version 3.3 or higher. You can do everything by editing
the batch file yourself, but the tool is provided to make configuration and support
easier.
Caution: It is common with Uniint-based interfaces to use the /STOPSTAT parameter.

You must not use this parameter with the OPC interface. Instead, you must use
/OPCSTOPSTAT. Using /STOPSTAT may cause invalid values to be stored to your PI
tags.
Starting and Finding Servers

/SERVER The name and location of the OPC server
/HOST The name and location of your PI server, and its port number
/STARTUP_DELAY If your interface hangs when the machine reboots, you may need to tell
it to wait a few seconds before connecting to the network layer.
/PISDKCONTIMEOUT Change the timeout value for PISDK calls.
/MAXSTOPTIME Set how many seconds the interface is allowed for shutting down
nicely.
Interface-level Failover
/CM Cluster Mode. Selects behavior for the backup interface.
/PR Primary or backup? /PR=1 is primary, /PR=2 is backup.
/RN Resource number. Identifies the apionline instance that goes with this
interface instance.
/SIN Secondary interface nodename. Both nodes must have the same value
for /SIN=nodename. Obsolete.
/FM Failover mode. /FM=1 is chilly, /FM=2 is cool, /FM=3 is warm
(and is the default mode),

/CN The string tag into which should be written the name of the currently
active interface node.
Server-Level Failover
/NI The number of interfaces running on this node.
/WD Watchdog tag specifications.
/BACKUP The name and location of the backup OPC server
/FT The number of seconds to try to connect, before switching to the
backup server.
/SW The number of seconds to wait for RUNNING status, before switching
to the backup server.
/CS The string tag into which should be written the name of the currently
active server.
/WQ Fail over if watchdog tag has bad quality or any error.
/WS Fail over if the server status leaves the RUNNING state.
Post-processing ("plug-in" dlls)

/DLL The dll name and path, i.e.
c:\pipc\interfaces\opcint\plug-ins\mydll.dll"
Controlling Data Collection

Commonly Used
/EC IORate tag identifier
/ER Update rate for event classes
/F Scan class specifier, sets scan period for the class, and update rate
unless overruled
/ID Interface instance identifier. This number shows which parts of
pipc.log were written by this interface. The Location1 parameter of all
tags must match this, unless /ID is zero or not numeric (in which case
all tags with the correct point source will be considered valid for this
instance of the interface). This is for running more than one instance
of the interface on the same machine.
/OPCSTOPSTAT Specifies digital state to be written to all tags when the interface is shut
down.
/PS The point source for the interface.
/SQ Store quality. If data has other than GOOD quality, store the quality
information rather than the value if SQ=Y. If SQ=I, treat
"questionable" quality as "good".
/ST Status tag. Tag to get the current state of the OPC server.

/TS Timestamps -- do we get them from the OPC server, or make them
ourselves? If we get them from the server, do we adjust for clock
differences between the OPC server clock and the PI clock ?
/VN Version number. We'll try to connect with v2.0 OPC Data Access, but
if that doesn't work we'll use v1.0a. This switch tells the interface to
skip trying v2.0. If your server only speaks v1.0a, use this.
Special Circumstances
/CR Connection Refresh. Causes the interface to call Refresh on all Advise
tags when the PI server comes back after having been unavailable.
Only useful if you are not using API buffering.
/CO ConnectionOutput. Causes the interface to send all output values
when the PI server comes back after having been unavailable. Only
useful if you are not using API buffering.
/ES Event source. Determines whether event tags are read from the OPC
server's CACHE or directly from the DEVICE, for v1.0a servers. For
v2.0 servers, it has no impact, because all event tag reads are from
DEVICE.
/QT Queue Tag. A tag to hold the number of values currently waiting to be
sent to PI. One way to measure the load on the interface. A high
number here indicates that we're getting more data than we can quickly
pass to PI. This switch is usually not needed if you have buffering
enabled.
/UR Update rate specifier, if different from the scan class rate
/HQ High queue limit. Don't set this unless we tell you to, it tells the
interface when to decide it is using too much memory, and it's time to
drop data instead of sending it to PI.
/LQ Low Queue limit. Don't touch this either. It tells the interface when to
resume sending data to PI.
/IT Integer Time. If you don't want or need the millisecond portion of the
timestamp, use this flag to drop it. Storing integer seconds speeds up
processing on the PI server.
/NT No Timeout. This flag directs the interface to never write IO Timeout.
Ever. Included for very special circumstances, be sure you want this
before you use it.
/SN Turns off exception reporting and sends all data to the snapshot.
Should not be used except for testing.
/TF Sets the format for timestamp strings read from or written to the OPC
server.
Handling Idiosyncracies for Various OPC Servers

/AF Advise groups immediately. This helps if your server does not return
initial data on advise. The symptom is that when you create an advise
tag for a value that doesn't change often, the interface does not write a
value to PI when it first starts up. You can tell if you have this

problem by using PIOPCTool to create a group, add tags, and then

Advise the group. If you do not get an immediate value for your tags,
but adding another tag to the group gets you a value for that tag, you
will need to use the /AF=Y switch.
/AR Ignore the AccessRights property. If you see "Invalid read/write mode
requested" in your pipc.log file, try this one.
/GL If you see "OnDataChange:Invalid group ID in your pipc.log file.
This means that your server is broken. Please, please email us at
techsupport@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, well wait this many seconds before trying to reconnect.
/TO Timestamp Offset. If your server installation is broken such that the
time on the server machine is incorrect (specifically, this is useful when
the server clock matches the wall clock but the server's timezone
information is required to be incorrect), this will tell the interface to
adjust all the timestamps by a specific amount.
Debugging
/DB Debug level
/DF The name of a PI tag that has the debug level. This should be an
integer tag, configured as an output tag for the interface. When you
change the value in the tag, the interface will capture the new debug
flag value. Nothing will be written to the OPC server for this tag.
/DT Debug tag for some levels. See the section on Debugging.

Alphabetical List of Parameters
Parameter Description
/AF The /AF argument is provided to help deal with broken servers which do
not return initial values for Advise tags. This argument must not be used
Optional in conjunction with NT Cluster Failover, as it causes OPC Groups to be
Default: /AF=N advised as soon as they are created.
/AR The /AR argument is used to tell the interface to ignore the access rights
property on items added to a group ( /AR=N). If your server does not use
Optional the access rights bitmask properly, setting /AR=N will tell the interface to
Default: /AR=Y ignore the server's access rights bitmask and attempt to use the item
anyway. The error from the interface is "Invalid read/write mode
requested"; if you get this message, try using
/AR=N.
/BACKUP The /BACKUP argument is used if failover option is used. This switch
specifies the name of the backup OPC server. The backup server name is
Optional specified after an equal sign with no spaces or quotes as follows:
Required for server-level /BACKUP=backuphostname::backupOPCservername
failover
Again, if the OPC server is on the local machine, the hostname:: must be
omitted:
/BACKUP= backupOPCservername
/CM Cluster Mode. When the interface is configured for interface-level failover,
running on a cluster, this argument specifies which mode to use. Mode 0 is
Optional the original mode, with a preferred primary. Mode 1 is a non-preferential
mode, where the whichever interface is active will stay active until the
cluster resource fails over, either through a failure or through human
intervention. The default is /CM=0.
/CM=1
For more on failover modes, please see the section below on Interface-level
Failover.
/CN When the interface is configured for interface-level failover, running on a
cluster, this argument can be used to specify a PI string tag which will
Optional receive the nodename of the interface which is currently gathering data.
This allows tracking of which cluster node was the active interface node.
As with the other tag specifiers, you specify the PI tag with
/CN=tagname
This tag should be configured to be a Lab tag, or otherwise not belong to a
point source which is in use.

/CO This argument is only useful when, for some reason, you are not using API
buffering. When the PI server becomes unreachable, the interface will still
Optional try to send the data, but it will fail. When an attempt to send data succeeds,
Default: 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
/CO=N interface will simply wait for the next new value to come before writing
anything to the OPC server. If you want the interface to send the current
values to the OPC server when the PI server comes back online, include this
argument in your opcint.bat file
/CO=Y
/CR This argument is only useful when, for some reason, you are not using API
buffering. When the PI server becomes unreachable, the interface will still
Optional try to send the data, but it will fail. When an attempt to send data succeeds,
Default: 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
/CR=N default, the interface will simply wait for the next value to come in. If you
want the interface to request the current values from the OPC server when
the PI server comes back online, include this argument in your opcint.bat
file
/CR=Y
/CS When the interface is configured for server-level failover, this argument can
be used to specify a PI string tag which will receive the name of the server
Optional which is currently providing data. This allows tracking of which server was
the active server across a period of time. As with the other tag specifiers,
you specify the PI tag with
/CS=tagname
This tag should be configured to be a Lab tag, or otherwise not belong to a
point source which is in use.
/DB This is included to allow some minimal debugging if you have difficulty
figuring out what you're getting from your server. See the section on
Optional Debugging for more information.
Default: none
/DF 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
Optional set its value to 0. Give the name of this tag with the /DF parameter:
Default: none /DF=OPC.Debug.Flag
and give it some dummy instrumenttag. When you change the value in the
PI tag, the interface will capture the new value and set its debug flag to that
value. Nothing will be written to the OPC server.
/DLL The interface now supports post-processing DLLs for specific OPC servers.
The format for telling the interface where to find your DLL is :
Optional
/DLL=c:\directory\to\the\file\yourdll.dll
Default: none
where you replace the directory path and filename with the appropriate one
for your DLL.

/DT The name of the tag to be used with /DB=64. If this tag is not specified, the
interface will use the first tag for which it receives a value.
Optional
Default: none
/EC 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:
Optional
Tagname1, 1
Default: none Tagname2, 2
where tagname1 and tagname2 can be any legal tag name. The number
after the tag name can be between 1 and 33 or between 51 and 200,
inclusive. Numbers 34 to 50 are reserved for future use. If /ec=2 is used on
the command line for the above iorates.dat file, then the rate (events per
minute) at which data is sent to the snapshot will be stored in Tagname2.
The rate that is sent to Tagname2 is a 10 minute average (i.e. the total
number of events collected by the interface divided by 10 minutes).
Therefore the IORate will appear to be zero for the first 10 minutes of
interface operation. IORates for individual tags cannot be measured at this
time.
The iorates.dat file must be created by hand. The file should be placed in
the \dat directory. The \dat directory is located in the directory designated
by the PIHOME entry in the pipc.ini file. Normally the PIHOME entry
points to the C:\ProgramFiles\PIPC\ directory so that the iorates.dat file will
reside in the C:\ProgramFiles\PIPC\dat\ directory.
Once the iorates.dat file is created, the interface must be stopped and
restarted before the interface begins measuring the IORate.
Although the interface will allow multiple instances of the /ec flag to be
specified on the command line, the rate will only be nonzero for the first
rate tag that is referenced.
/ER This parameter defines the requested update rate for the event class group.
All event-based points belong to one group, and the default update rate for
Optional the group is one second. If the OPC server's data cache for event-based tags
Default: does not need to be updated that frequently, use this parameter. For
example:
/ER=00:00:01
/ER=00:00:10
For v2.0 servers, all event reads are done from device, so this value should
be set quite large, /ER=24:00:00, unless there is some other reason to
update the cache.
/ES This parameter determines whether event tag reads for v1.0a servers will be
from CACHE or from DEVICE. DEVICE reads should be used with
Optional caution, as they can have a tremendously negative impact on the
Default: performance of the OPC server. Please read the section on Configuring
Event Tags before using this setting (/ES=DEVICE).
/ES=CACHE

/F This parameter defines the frequency scan class. It determines how
frequently the interface requests the data from the server. The format is
Required /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 theyre defined, with the first one being scan class 1, the next
scan class 2, etc.
The interface supports sub-second scan frequencies, but they should be used
with caution, as very fast scans place a high demand on the system. Sub-
second scan times have the format
/F=00:00:00.50
to indicate a frequency of one-half second.
Performance can be further improved by defining scan offsets as explained
in Polling and Advising section. You can configure the scan offsets by
specifying the scan class in the opcint.bat file as follows:
/F=00:01:00,00:00:30
The points belonging to this scan class will scan every minute offset by 30
seconds. That is, 30 seconds after the next minute, then 1 minute after that,
and so forth.
If you specify
/F=00:01:00
with no offset, the interface will start scanning whenever it gets around to
it.
If you specify
/F=00:01:00,00:00:00
the interface will start at the next minute.
/FM=# Failover mode. This controls the behavior of the backup interface when
using interface-level failover. The options are:
Default:
/FM=1 Chilly: do not create groups on the server
/FM=3
/FM=2 Cool: Create groups inactive, and add tags
/FM=3 Warm: Create groups active, do not advise groups
For more on failover modes, please see the section below on Interface-level
Failover

/FT The /FT argument is used in conjunction with /BACKUP argument to
specify the failover time. The interface will keep trying to connect to the
Optional
current server for this many seconds before it give up and tries to connect to
Default: /FT=60 the other server. The interface will stay on a given server, once connected,
until that server fails, or the watchdog tag(s) indicate that it is no longer the
active server.
This parameter also affects how often the interface will check the server
status. If the failover time (FT) specified is less than 30 seconds, the
interface will call GetStatus on the server every FT seconds. If FT is not
specified, or is more than 30 seconds, GetStatus will be called every 30
seconds. This serves as a watchdog to ensure that the server is still
reachable and responding, and also allows the interface to monitor clock
drift between the systems. Note that this parameter has a large impact on
systems using the /WS flag.
/GL Some early v1.0a servers did not format messages correctly, and the
interface included a work-around for them. This is now turned off by
Optional default. If you receive the error message "OnDataChange:Invalid group
Default: /GL=Y 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.
/GS The /GS argument is intended to allow the use of older, non-compliant
OPC servers which do not provide a valid GroupStatus on asynchronous
Optional
reads. If your log file contains an error like:
Default: /GS=Y
"OnDataChange: Header status :" followed by a hexadecimal number, and
you are not getting any data from the interface, you should try using
/GS=N to tell the interface to ignore the group status flags. If you are
getting some data, but are also getting this error on some reads, you should
contact the vendor for your OPC server and give them the error number, so
they can help you determine why your OPC server is returning this error
indication for the group in question.
/HQ The /HQ argument sets the upper limit for the internal queue of the
interface. The interface may take in data from the OPC server faster than it
Optional
can pass it to PI, or faster than PI will accept data. This data is queued in
Default: /HQ=100,000 memory until it can be passed to PI. If the internal queue grows too large,
it can take so much virtual memory that NT becomes unstable. This queue
limit is a safeguard against such behavior. If the internal queue exceeds the
HQ limit, the interface will log the fact that it is exceeding its limits, and it
will drop incoming data until the internal queue has dropped below the low
queue limit (LQ).
It is strongly recommended that this value not be changed unless you are
willing to lose incoming data. This parameter is intended for debugging
system performance problems.

/HOST /HOST=nodename:X defines the PI Server to which the interface will
connect. If this parameter is not used, the interface will attempt to find the
Optional PILOGIN.INI file and use the default server defined there. For example:
Default server defined in If the interface is installed on a PI3 home node:
PILOGIN.INI
/host=localhost:5450
If the interface is installed on a PI API node and talking to a PI2 server
located on CASABA:
/HOST=CASABA:545
If the intervace is installed on a PI API node and talking to a PI3 server located on
PEACH:
/HOST=PEACH:5450
/HS This flag makes the interface request a cache update rate of 1/2 of the scan
rate for the scan class. If your scan class is 2 seconds, the interface will ask
Optional the OPC server to read new values from the device every second, for all the
Default: /HS=N 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
OBSOLETE rate anyway. If the tags are advised, the scan rate is only used to define the
requested update rate for the group, so you'd do just as well to make the
scan rate the same as the requested update rate.
This parameter is obsolete -- use /UR instead.
/HWPS This flag tells the interface to check for Plantscape-specific error codes
when retreiving data values. It specifically checks for an Item error code of
Optional 0xE00483FD or 0xE00483FC, and if it finds either of them, it will attempt
to failover to the other OPC server.
/ID /ID=2 defines an identifier. The identifier precedes messages sent to the
log so that if more than one OPC interface is running on the same computer
Optional
the messages will be associated with the correct interface. The number
specified here will be matched with the Location1 parameter of all tags in
the interface's pointsource. Only tags with matching Location1 will be
recognized.
If /ID= does not specify a number, or specifies 0, the interface will accept
all tags with the correct pointsource, regardless of the value in Location1 of
the tag. If you specify a numeric value for /ID=, the interface will only
accept those tags that have the correct pointsource and that numeric value
in Location1.
/IF The /IF flag tells the interface to ignore the first value sent for each point.
This is to accommodate those servers that send a response when the
Optional interface connects to a point: some servers send a value back, regardless of
Default: /IF=N whether or not they have a valid value, and neglect to send a status that
would indicate that the value is invalid. This generally manifests as odd-
looking values showing up whenever the connection to the OPC server is
established or a point is edited. To get rid of the false values, set this flag to
/IF=Y.

/IS This flag tells the interface to ignore the server status returned by the OPC
server, as far as determining the appropriate actions to take. All servers
Optional should return
Default: /IS=N OPC_STATUS_RUNNING
when they're ready to add groups and items and return values, but some
broken servers do not do this. If your interface hangs on startup, and the
PI_OPCTool shows something in
Server current state =
that isn't "RUNNING", you should use this flag, and report the problem to
your OPC server vendor.
/IT For performance reasons, some users may wish to discard the subsecond
portion of the timestamps being passed to PI and only send whole integer
Optional seconds. This will mean that PI will require less space, and possibly less
Default: /IT=N CPU, to store the same amount of data. The fractional part of the second is
simply truncated. To use this, set /IT=Y.
/LQ The /LQ argument sets the lower limit for the internal queue of the
interface. If the internal queue has exceeded the HQ limit, the interface will
Optional
drop incoming data until the internal queue size has dropped below the low
Default : /LQ=80,000 queue limit.
It is strongly recommended that this value not be changed unless you are
willing to lose incoming data. This parameter is intended for debugging
system performance problems. The LQ cannot be set to less than (HQ -
100).
/MA By default, the interface will add one item at a time to its groups. This
guards against ill-behaved servers that will reject an entire group if one
Optional item is invalid. The Mass Add flag tells the interface to add all the items in
Default: /MA=N a class at the same time. If your OPC server allows it, you should use
/MA=Y. If this causes lots of tags to be rejected by the server, remove the
/MA flag at least until you determine which tag is the problem.
/MAXSTOPTIME The interface ordinarily gets 120 seconds to close its connections and exit
cleanly. If your server requires more time, use this parameter.
Optional
Default=120
/NI 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
Optional
specify how long the interface is to wait until it initiates a server-level
Used in conjunction with failover. This gives the multiple interfaces extra time to DCOM timeout in
/FT if multiple instances case a DCOM call made to the server doesnt return in time because the
of the interface are server is busy servicing requests from other interface.
running on the same
node.
/NT 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
Optional Timeout written to the tags at those times, but the ability to turn it off is
Default=N included for very special circumstances.

/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
Optional stopped. If you don't specify a digital state, the interface will use "IO
Timeout", but you can specify any state in the System State Set. Most sites
will probably find this useful.
/PISDKCONTIMEOUT Set the timeout for PISDK calls. The parameter is the number of seconds to
wait before timing out. The default is 15 seconds.
Optional
/PR 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
Optional. failover is needed and the interface is to be the primary interface set this
Required for interface argument to /PR=1. If this interface is to be the secondary interface set it
level failover to /PR=2.
Default: /PR=0
/PS The point source is defined by /PS=pointsourcechar where pointsourcechar
is the character used by the interface tags. For example:
Required
/PS=G
/QT 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,
Optional this number should be fairly low and fairly steady, but if PI is slowed down
Default: none by other processing or if the OPC server sends a large burst of data, you
may see it jump. The tag should be an integer tag (Int32 for PI3), set up for
manual input as though it was a lab tag.
/RD This specifies how many seconds to wait before trying to reconnect to the
server, if we get an error indicating that the RPC server is unavailable or
Optional busy (0x800706ba or 0800706bb).
Default: not active Note that this option causes the interface to abandon the connection without
cleaning up first. Thats a bad idea, in general, so dont use this option
unless you have no choice, and then only while you figure out why youre
losing the RPC server.
/RN The /RN argument specifies the resource number if there are to be multiple
instances of opcint running (with different service names) on the same
Optional machine in conjunction, each dependent on a uniquely-named resource,
Required for interface- apionline#. /rn=1 will indicate that the interface is to depend on apionline1
level failover when (i.e. will look for the service named apionline1), /rn=2 will indicate that the
multiples instances of interface is to depend on apionline2, and so forth. See Interface-Level
opcint are running on the Failover section for more detailed explanation. If interface-level failover is
same node. to be supported and this number is negative (/RN=-1), the cluster resource
name is assumed to be apionline without the suffix #.

/SERVER The OPC Server to be used is defined with this command line parameter.
Use the following format:
Required
/SERVER=FACT1NODE::MODBUSOPC
where FACT1NODE is the name of the computer where the OPC Server
will run, and MODBUSOPC is the name of the OPC Server as registered
on that machine. If the server will be running on the same machine as the
interface, the nodename must be omitted:
/SERVER=MODBUSOPC
If your server name has embedded spaces, you will need to enclose the name in
double quotes (see the beginning of this section, where it says that there can be no
spaces within any parameter):
/SERVER="Server name with spaces"
/SIN The /SIN argument specifies the name of the secondary interfaces node
when i/f failover is to be supported. You must specify the same secondary
Optional
interface node in the startup files for both the primary and secondary
OBSOLETE interfaces.
/SN 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.
Optional
/SQ 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
Optional
interface to store the quality rather than the value if the quality is anything
Default: /SQ=N except GOOD. Setting this flag to /SQ=I will cause the interface to ignore
the quality information, and treat questionable quality as GOOD. BAD
quality will still result in a digital state code being sent to the archive.
/ST This allows you to define a PI tag that will get the status of the OPC server.
This should be a digital state tag, set up for manual input as though it was a
Optional lab tag. The possible values are:
Default: none 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 0 th 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.

/SW 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
Optional enter RUNNING status, or drop the connection. You can use this switch to
Default: none limit the number of seconds that the interface will wait for the server to
enter RUNNING state. The parameter is the number of seconds which the
interface should wait.
/SW=5
/STARTUP_DELAY If your interface is installed for autostart, but it hangs when the machine
reboots, you may need to give the network layer time to get settled before
Optional trying to use it. This parameter will make the interface sleep for # seconds
before trying to actually do anything. The basic form is
/STARTUP_DELAY=#
where # is the number of seconds to wait.
/STARTUP_DELAY
will cause a 30-second delay.
/TF This argument allows you to specify the format of timestamp strings. The
setting will be used for tags with Location2 = 6 or 7, where the OPC Item is
Optional either a string that contains a timestamp, or a VT_DATE value, and also for
writing output timestamps using TIM= in the ExDesc field. See the
sections above on Location2 settings, Datatypes, and ExDesc for more
information. The Datatypes section gives example format strings.
Format: valid tokens are
cc yy mn mon dd hh hr mm ss 000 XM
/TO Timestamp Offset. This parameter allows you to apply an adjustment to the
timestamps, to deal with broken servers and broken installations, where the
Optional clock for the OPC server is set incorrectly (for example, the server requires
the clock to match the wallclock, but the Timezone must be GMT,
regardless of where the server is actually located). This should not be used
if you have a properly working server. The format is the same as that of the
scan period parameters (/F), but may be optionally preceeded by a negative
sign.
Format:
/TO=01:00:00
/TO=-03:00:00
/TO=00:45:00

/TS This flag determines whether the interface expects to get timestamps for the
data from the interface, or whether it will timestamp the data when it
Optional receives it. Some OPC servers are able to provide the timestamp for when
Default: /TS=N they read the data from the device, while others are not. If your server is
able to provide valid timestamps, use
/TS=Y
If your server can provide valid timestamps only for advised tags, use
/TS=A
If you need to store times without having them adjusted to the PI server clock, use
/TS=U
This setting can cause your data to be lost, if your clocks are set incorrectly.
Please see the section on Timestamps before using this setting.
/UR The /ur argument sets the requested update rate for the group. This
argument is positional, like the /f scan period argument. The update rate
Optional
will be applied to the scan period it follows. Thus, if you have
/f=00:00:02 /f=00:00:03 /ur=00:00:00.5
/f=00:00:01, you get scan class one with period=2 seconds, ur=2
seconds, class 2 with period=3 seconds, ur=0.5 seconds, and scan class 3
with period=1 second, ur=1 second.
/VN=1 The /VN argument is used to tell the interface that the OPC server uses
OPC v1.0a. If this argument is not used, the interface will try to
Optional
communicate using OPC v2.0, and will fall back to v1.0a if v2.0 does not
succeed.
/WS Once the interface connects to a server that enters the RUNNING state, it
will stay connected until the server disconnects, the watchdog tag(s)
Optional indicate that this is not the active server, or the interface is shut down. If
you want the interface to disconnect from the server if the server leaves the
RUNNING state, set this flag to
/WS=1
By default, the server status is checked every 30 seconds. You can adjust
this to be more frequent by using the /FT parameter to specify the failover
time.
/WD1 The /WD1 and /WD2 arguments can be used if the redundant OPC servers
return OPC_STATUS_RUNNING status when in backup mode as well as in
/WD2
primary mode. Please see the section on Watchdog Tags for more
Optional information.
Needed with some servers
for server-level failover.
/WQ=# This setting directs the interface to fail over to the other server if a
watchdog tag has anything but GOOD quality, or if there is an error on
Optional reading the item. Note that v1.0a servers do not return error codes for
Needed with some servers individual items, so for version 1.0a servers this flag only checks the quality
for server-level failover. of the value sent from the server.
/WQ=1

Interface Operation
OSI recommends that interfaces be installed on API nodes instead of directly on the PI
server node. An API node is an NT or UNIX node other than the PI Server node where
the PI Application Programming Interface (PI-API) has been installed (see the PI-API
Installation Instructions manual). The PI server should not need to compete with
interfaces for CPU time. The primary function of the PI server is to archive data and to
service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the API
node (once again, see the PI-API Installation Instructions manual). Bufserv is
distributed with the PI-API. It is a utility program that provides the capability to store
and forward events to a PI server, allowing continuous data collection when
communication to the PI server is lost. Communication will be lost when there are
network problems or when the PI server is shut down for maintenance, upgrades,
backups, or unexpected failures.
In most cases, interfaces on API nodes should be installed as automatic services, except
during the initial testing period where it is recommended to run the interface
interactively to simplify troubleshooting. Services keep running after the user logs off.
Automatic services automatically restart when the computer is restarted, which is
useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI server node. In this
case, the typical scenario is to install the PI server as an automatic service and
interfaces as manual services that are launched by site-specific command files when the
PI server is started. Interfaces that are started as manual services are also stopped in
conjunction with the PI server by site-specific command files. This typical scenario
assumes that Bufserv is not enabled on the PI server node. Bufserv can be enabled on
the PI Server node so that interfaces on the PI server node do not need to be started and
stopped in conjunction with PI, but it is not standard practice to enable buffering on the
PI server node.
No More Password File

With the introduction of PI version 3.3, you should begin using trust relationships to
secure your data. Rather than creating a password file, and a proxy for the interface
within PI, you will use the PI trust database. Please refer to the PI Data Server
manuals for how to set up a trust relationship for your interface.
For users who are not yet using PI 3.3, you can still run the interface interactively to set
the password to be used by the PI SDK. If you change the password on the account,
you will need to delete the opcint.pwd file, which will be in the interface directory, and
run the interface interactively again, to set the new password.
Installing the Interface as a Service

While the installation script will install the interface as a service, if you need to
uninstall it or change the installation, you can do this easily. Open a Command Prompt
window, and change to the directory that contains opcint.exe and opcint.bat. To
uninstall the service, type
Interface Operation
>opcint -remove
To install it as a service, type
>opcint -install
To install it as a service that will automatically start when the system starts, type
>opcint -install -auto
If (as is likely) the service needs to wait for one or more other services to be started
before it starts, you'll need to know the names of the services it should wait for. One
common one would be tcpip, another would be bufserv (the PI API buffer service for
API nodes). Another that some customers have needed to specify would be RpcSs, the
RPC service. To have the service wait for those three services before starting, type
>opcint -install -auto -depend "tcpip bufserv RpcSs"
You can specify that the interface is dependent on any service you choose, just put a
space between the names and enclose the entire set in double quote marks. Remember
that this only determines the order in which services are started when the system comes
up, it has no impact on what happens after that. So if your interface is dependent on
bufserv, and you've taken down both bufserv and the interface, starting the interface
through either the Control Panel or from the command line will not start bufserv.
Removing and reinstalling the service only changes registry entries, so if you are unsure
what dependencies you have set, it is generally safe to remove and reinstall the service.
Or, you can find the actual registry entry under
"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\opcint".
You can use the Control Panel/Services to change the auto-start setting, but you cannot
change the dependencies through the Control Panel.
Installing Debug Symbols

The install kit will automatically install the debug symbols to directory
%SystemRoot%\Symbols\exe
Service Control Manager can use the symbols contained in this file to match Dr.
Watson dumps with the extracted symbol information. This directory is usually created
by the PI 3.2 installation program. If it does not exist, however, the user should create
it. Our install program will copy this file to the appropriate directory if it exists, but if
it does not the user needs to create it. After it has been created, the debug symbol file
can be manually copied over to %SystemRoot%\Symbols\exe directory. Dr. Watson is
installed as the default debugger by typing drwtsn32 i at command prompt.
To test if the symbols are correctly installed, user can induce an application crash by
typing the following at command prompt in the directory where the interface is installed
opcint crash
after the interface is installed as service as explained in the previous section. In
%SystemRoot% directory (\winnt directory under winnt) there will be drwtsn32.log.
This file will contain a series of opc function calls made around the time of the crash.
Of course, we hope to never have to use this useful tool.
If this interface is being installed using the installation kit (available from version 2.08
or higher) the debug symbol file is automatically installed in the correct directory.
However, drwtsn32 still needs to be set by the user in order for drwtsn32 to act as the
default debugger.

Startup/Shutdown
The OPC Interface, if run as a service, can be started and stopped from the Service
manager in the Control Panel. It can also be started or stopped from a console window
by typing "opcint -start" or "opcint -stop" (if you're not in the opcint directory, you'll
need to specify the entire path to the file), or by using the standard service commands,
"net start opcint" and "net stop opcint" in a command window.
To run the interface interactively, you can just double-click on the opcint.bat file, or
open a Command Prompt window and type "opcint" (if you're in the same directory as
the opcint.bat and opcint.exe files), or type the complete path to the opcint.bat file, like
"c:\pipc\interfaces\opcint\opcint.bat".
Editing Tags While the Interface is Running

The interface will perform tags edits while it is running, so that you don't need to shut it
down to update the tag configuration information. However, as with most PI
interfaces, the interface will only process so many tag edits at a time. In general, the
interface will check for tag edits every 2 minutes. If it finds that at least 25 tags have
been edited, it will check again in 30 seconds, otherwise it will wait another 2 minutes
before checking again. Also, the edits are performed in the simplest way -- we delete
the tag from the interface and then add it in again. With some servers, that operation
can require quite a bit of time and resource.
Therefore, if you are editing very many tags, you will probably find it faster and more
efficient to restart the interface after all your tags have been edited.
Logging Messages
The OPC Interface will send the following information to the log file:
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.
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

Interface Operation
importantly, this action also provides positive feedback to the interface that the OPC
server is still up and running, even if all points are configured for advise and no data
has come in for some time.
If the OPC Server does go out of reach, the interface will periodically try to reestablish
the connection. Once the connection to the OPC Server is regained, the interface will
recreate its groups and items on the server and resume data collection.
Using PI-API Buffering

To use API buffering with the OPC interface, you must have version 1.3 or higher of
the PI API. This is because earlier versions of bufserv did not support extended API
calls, which the interface uses. If you are having problems getting the interface to work
with buffering, first make sure that it works without buffering installed, then try adding
the buffering function.
Configuring DCOM: The Basic Steps

Your server should have instructions on configuring DCOM, and if possible you should
just do what your server documentation says. But just in case that doesn't work, here's
the short version of how to get data moving. Press the Start button, then select Run,
type in "dcomcnfg" and press OK. This will bring up the DCOMCNFG window.
There are slightly different versions for different systems (NT, W2K, XP), and for
different SPs. The important things:
Check the box to enable DCOM.
Under "Default Properties", set the Default Authentication level to "Connect". Set the
Default Impersonation Level to "Identify".
Under "Default Security", edit the Default Access Permissions. Grant Access to
INTERACTIVE, SYSTEM, NETWORK, and to whatever user your interface will run
as. Edit the Default Launch Permissions, and grant Launch permissions to the same
users.
Under the Applications tab, find your OPC server and check its properties. Under the
Security tab, if it uses Custom Permissions, Edit those permissions to grant Access and
Launch permission to the same users as above, INTERACTIVE, SYSTEM,
NETWORK, and the interface account.
Under the Identity tab, check the user that the OPC server will run as, and make sure
*that* user has been given permission to Launch and Access DCOM applications on
the Default Security page. In general, running the server under the Interactive User
account seems to work well with NT4 SP3, and running under the Launching User
works well under NT4 SP4, but specifying a given account which has permissions
seems to work best. Running the server under the local system account will not work
for DCOM, as the local system account has no permissions outside the machine.
The main point is that services run under the INTERACTIVE account, or at least they
require that account to have permissions before they can connect using DCOM. After
changing DCOM permissions, you may need to restart your OPC server if it's running.
More detailed description can be found in "DCOM Configuration: The Details", below.

Configuring Tags
Scan Classes
Scan classes are defined in the opcint.bat file. Each /F= parameter defines a scan class,
which we number in order, so if your .bat file has
/F=2 /F=1:00 /F=1:30:00 /F=00:00:05
then you have defined these scan classes
Scan Class 1 has scan period 2 seconds
Scan Class 3 has scan period 5400 seconds (90 minutes)
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.
AdvFiveSecs.PV ItemID1 1 0 1 4 0 0 0
AdvOneMin.PV ItemID2 1 0 1 2 0 0 0
AdvNinetyMins. ItemID3 1 0 1 3 0 0 0
PV
Note that the same opcint.bat settings can be used for either polled or advised tags, but
if you wanted to use both of these sample configurations, you would need to add
another three scan periods, and use the first set for either advises or polls, and the
second set for the other tags. So you would have
Configuring Tags
/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
FiveSecond.PV ItemID1 1 0 0 4 0 0 0
OneMinute.PV ItemID2 1 0 0 2 0 0 0
NinetyMinute.PV ItemID3 1 0 0 3 0 0 0
AdvFiveSecs.PV ItemID1 1 0 1 8 0 0 0
AdvOneMin.PV ItemID2 1 0 1 6 0 0 0
AdvNinetyMins.PV ItemID3 1 0 1 7 0 0 0
Configuring Event Tags

Event tags are only read when the triggering event occurs. An event happens when the
PI snapshot receives a value for the trigger tag. It may have the same timestamp and
quality and value as the last event, and so the snapshot value for that trigger may seem
the same, but the act of receiving a value for the trigger tag causes the interface to
receive a notification that the trigger has been updated.
Many event tags can use the default configuration: set Location4=0, and set the name
of the trigger tag in the ExDesc field ("TRIG=triggertagname"). The default update
rate for event groups is 1 second, so the server will be asked to update its cache every
second for every event tag defined. That's probably faster than is necessary.
Especially if you have a server that uses the OPC v2.0 standard; in v2.0, all
asynchronous reads are done from the device, so updating the cache is essentially
wasted effort. If you have a v2.0 server, you should set the event rate (/ER in
opcint.bat) to something much higher, perhaps 8 hours. Even if you have a v1.0a
server, where asynchronous reads are from the cache, you probably don't need to have
the cache updated that often for all your event tags.
You use UserInt2 to specify in which event group an event tag belongs. The parameter
does nothing else, it is only an instruction to the interface as to which tags get read
together. All values for a single read must be returned at the same time, so grouping has
different effects on different servers. Also, a plug-in DLL that does post-processing of
data before the data is sent to PI may require that a set of data be processed as a
complete set, and so all the tags that make up that set must be in the same group.
For v1.0a servers, it is useful to separate event tags into groups based on the triggering
event. This is the most efficient mode.
For v2.0 servers, it's probably more important to separate event tags based on where
the data actually comes from. The v2.0 standard requires that all asynchronous reads
be read from the device, rather than from the server's cache, so you should set the cache
update rate very high, and most important, you should try not to have an event group
contain values that come from different devices.
Tag exdesc instrume loc1 loc2 loc3 loc4 loc5 userint1 userint2
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.
ArrayTag0001.PV Data.Array 1 0 1 3 0 1 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.

Configuring Tags
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 loc2 loc3 loc4 loc5 userint1 userint2
g
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

Weve already shown how to read the quality of a value rather than reading the value
itself, and weve also seen how to use transformations and scaling to adjust the value
read. You can combine these two options to end up with a PI tag that corresponds to
the quality of the item, translated into a simple digital set of Bad Value, Questionable
Value, Invalid Value, and Good Value. To do this, you need to create your digital tag,
and your digital state set with states Bad, Invalid, Questionable, and Good (in that
order), and set the tag to use that digital state set. Then set Location2 = 4, to tell the
interface to read the quality rather than the value of the item. Lastly, you need to set up
a transformation to mathematically translate the quality values into one of those three
values (0, 1, 2, or 3).
All you really need to do here is divide the quality number by a conversion factor, and
you will get the proper number, since the values are defined to be within ranges. If you
look at the possible values for the quality, youll 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
dont need to use an offset at all. Looking at the table of available conversions, we find
Value = (Value / Convers) DZero
Output tags:
Value = (Value + DZero) * Convers
So here we need to set our tag to have
Convers = 64 (decimal value for 0x40)
Totalcode = 3
SquareRoot = 0 (this is the default)
ExcDesc = DZero=0 (this can be combined with other options in the ExcDesc
field)

OPC Server Issues
The OPC specification allows a great deal of flexibility in how OPC servers are
designed, and in what features they will support. This is an outline of how that may
affect users of this interface.
Browsing
Point browsing is not a requirement of the OPC specification. If your OPC server does
not support browsing, you must have access to a list of the points which it will accept,
or the format of point names it will allow you to use. If browsing is allowed, you can
use PIOPCTool to see the points which your OPC server recognizes.
Timestamps
There has been much discussion of what the timestamp value should be, when the OPC
server sends one with the data. Some vendors send the timestamp for the last time the
data value and quality were read from the device (so the timestamp will change even if
the value does not). Others send the timestamp of the last read where the value or
quality changed, so if the data remains the same, the timestamp will not change no
matter how many times, or in what way, you read it. If your OPC server sends
timestamps for when the data last changed, you should use the /TS=N flag in the
startup command file.
Disconnecting
If your interface disconnects improperly from an OPC server (like if your network
connection goes down, or your NT system crashes), the server may not clean up the
connection on its side. The symptoms for this will probably be that the interface cannot
reconnect with the server. You can use the PIOPCTool to verify that this is occurring,
and the solution will probably be to shut down the OPC server. Refer to the
documentation which came with your server to see if they address this issue. If not, try
shutting down the server, or, if you understand NT and the programs youre running on
that machine quite well, use Task Manager to kill the thread. If in doubt, reboot the
machine. This is not a problem which can be resolved by a change in the interface:
once the connection is broken, we have no way to tell the server that it needs to clean
up its act.
False Values
Some OPC servers will return a value when a client connects to a point, even if the
server does not have a valid value for the point yet. When the server also sends a
proper status, this is not a problem, but some servers will send a false value and a
status of GOOD, which results in the false value being sent to the PI archive. You
would see those values in the archive at times which correspond with the interface
starting, or getting reconnected to the OPC server, or when a point was edited while the
interface was running. To prevent these values, you should use the /IF flag in the
OPC Server Issues
opcint.bat file. This will result in the interface dropping the first value received from
the OPC server for each point, each time the interface connects to the point.
Access Path
The Access Path is a suggestion for how the server might want to get to the data. It is
not part of the ItemID, and the server is not required to pay any attention to it.
However, the server is also not allowed to require it. If your server requires it, your
server is broken.
Some servers, such as RSLinx, require the information about how to access the data,
and look for this information either in the Access Path or as part of the ItemID. For
instance, RSLinx servers use the format
[accesspath]itemid
Other servers may use other formats. It's perfectly valid for servers to require path
information in order to access a value. It's just not legal for them to require that it be
sent in the Access Path field. If your server requires path information, and will only
accept it in the Access Path field, you need to contact your server vendor.

Interface Installation
Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface
executable is ifc.exe and that the startup command file is called ifc.bat. If the actual
name of the interface is Random, one should substitute Random for ifc in the
installation procedure below.
It is customary for the user to rename the executable and the startup command file
when multiple copies of the interface are run. For example, one would typically use
ifc1.exe and ifc1.bat for interface number 1, ifc2.exe and ifc2.bat for interface number
2, and so on. When an interface is run as a service, the executable and the command
file must have the same root name because the service looks for its command-line
arguments in a file that has the same root name as itself.
Interface Directories
The PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini
configuration file. This pipc.ini file is an ASCII text file, which is located in the
WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on
the C: drive. OSI recommends using \pipc as the root directory name. The PIHOME
directory does not need to be on the C: drive.
Interface Installation Directory

If multiple copies of the interface are to be installed, you will need a separate interface
directory for each copy of the interface. If the convention is followed, it is
recommended to place ifc1, ifc2, ifc3, etc., in the directories:
PIHOME\interfaces\ifc1\
and so on.
The installation kit will create the directories for you as well as renaming the opcint.exe
and opcint.bat files.
Plug-Ins Directory
There are plug-in dlls which do post-processing for specific applications. These
contain application logic which is not suitable for inclusion in the interface itself, as it
is specific to a given server and usage, but which is used by more than one customer.
The dlls, their supporting files, and the documentation for their usage are all installed
into a subdirectory below the interface directory called Plug-Ins.
OPCEnum Directory
The OPCEnum tool is mentioned elsewhere in this document. The executable and the
files needed for using it on another machine are installed into a subdirectory below the
interface directory called OPCEnum.
Tools Directory
Various tools are included in the installation, most prominently the PIOPCTool itself.
These are installed into a subdirectory below the interface directory called Tools.
Security
If the home node is a PI 3 server, the PI Firewall Database and the PI Proxy Database
must be configured so that the interface is allowed to write data to the PI Data Archive.
See Modifying the Firewall Database and Modifying the Proxy Database in the PI
Data Archive Manual.
If the home node is a PI 3.3 server, or higher, then you will need to establish a trust
relationship for the interface. Again, see the PI archive manual for how to do that.
If the home node is a PI 2 server, the read/write permissions should be set appropriately
in the pisysdat:piserver.dat file on the PI 2 home node. For more information on
setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 2 or PI 3 server because it has insufficient
privileges, a 10401 error will be reported in the pipc.log file. See the section Error
and Informational Messages for additional information on error messaging.
Interface Checklist
The OPC interface comes with an installation application. Executing the application
will copy the necessary files to your hard disk and install the interface as a service.
However, you will still need to edit the startup parameters. Alternatively, you can
install and use the PI Interface Configuration Utility (PI-ICU) if you're using PI3
version 3.3 or higher, and we do recommend that you use the ICU if you can. It makes
configuration much simpler.
In the installation process, you are given the opportunity to specify where to install the
interface files. If you took the defaults, the directory is opcint. If you specified
another directory, everywhere that this manual says "opcint", you should insert the
name of the directory you specified. If your directory name has spaces embedded, as in
"OPC for PI", you'll have to enclose it with double quotation marks. In your
installation directory there will be a sample command file OPCInt.bat (there's your
first substitution, if you used another directory). For information on how to configure
this file, see Software Configuration: Command-line Parameters.
To run the OPC Interface:

1. Define the Point Source (PI 2)

2. Create Digital States
3. Check the DCOM configuration, and add permissions as necessary.
4. Use PIOPCTool to verify connection to the OPC server and data collection for at
least one tag. Use Refresh to make sure we can read asynchronously.
5. Edit OPCInt.bat. Use the server name you used for PIOPCTool.
6. Create interface points
7. Add your PI server to the Connections table in PI-SDK, using AboutPI-SDK.exe.
8. Start the interface interactively
Once you have confirmed that the interface runs interactively, you should verify that it
works as a service. Check the Microsoft Windows NT services control panel to verify
that the service was added successfully. You can use the services control panel at any
time to change the interface from an automatic service to a manual service or vice
versa.
The service can be started from the services control panel or with the command:
opcint.exe -start
or with the command
net start opcint
A message will be echoed to the screen informing the user whether or not the interface
has been successfully started as a service. Even if the message indicates that the
service started successfully, you should make sure that the service is still running by
checking in the services control panel. There are several reasons that a service may
immediately terminate after startup. For one, the service may not be able to find the
command-line arguments in the associated .bat file. For this to succeed, the root name
of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must
be in the same directory. If the service terminates prematurely for whatever reason, no
error messages will be echoed to the screen. The user must consult the pipc.log file for
error messages. See the section Error Messages for additional information.
If the interface runs interactively but cannot connect to the server when run as a
service, it's almost always a DCOM permissions problem, recheck your dcomcnfg
settings.
The service can be stopped at any time from the services control panel or with the
command:
opcint.exe -stop
The service can be removed by
opcint.exe remove
Upgrading an Installation
If you already have an earlier version of the OPC Interface installed, and you're
upgrading to the newer version, you will need to uninstall the version you now have.
You can do that from Control Panel\ Add/Remove Programs. The interface installation
will not let you install a new version over the top of an existing installation. You can
install a new version into another directory, and you can have multiple installations on
one computer; the installation will use the directory name (the last portion) as the name
of the service. If you already have the interface installed into c:\pipc\interfaces\opcint,

you can install the new version into c:\pipc\interfaces\opcint2, and your Services list
will show both opcint and opcint2. You can then uninstall the opcint version when
you're ready to do so. If you are uncertain about upgrading, installing the new version
into a separate directory will make it easy for you to test out the new version before
moving all your data collection over to it. Don't forget to uninstall the old version when
you've got the new one working properly.
Common Problems
The vast majority of problems in getting the interface installed and collecting data are
in getting COM/DCOM set up. Don't even bother trying to run the interface until you
can use PIOPCTool to connect to your OPC server, create a group, add points, and
read values using either Refresh or Advise. If you can read values with SyncRead but
not with either of the other methods, you almost certainly have DCOM permissions,
probably on the machine on which the interface is running. Go back and check your
DCOM settings on that machine, and check the userid under which the OPC server is
running.
If you have trouble running the interface as a service, try running interactively: open a
Command window, change to the directory where you installed the interface, and run it
by typing "opcint.bat". Make sure you're logged in as the right user. If that doesn't
work, you should at least get some messages that will help you figure out what's wrong
(see the list of error messages below).
If you can run interactively but not as a service, check the Event Viewer (Start
button/Programs/Administrative Tools/Event Viewer) to see if there are messages about
DCOM; that would indicate a permission problem, or a registration problem. The
PIOPCTool program uses the same code as the interface itself, so if you can talk to
your OPC server with the tool you should be able to talk to it with the interface. Also,
check your DCOM permissions. Make sure you aren't trying to install the service to
use files that reside on a logical disk: if you have created a logical mapping of part of
your disk drive, for example if your C:\Program Files\pistuff directory is shared as
PISTUFF, and you map drive P:\ to PISTUFF, then install the interface on P:\, you're
likely to have problems. The same for your OPC server, you can't use logical drive
mappings when you register the server.
If you're getting "error -11049" in your pipc.log file, and you're not getting data, check
the timezone and Daylight Saving Time settings for your PI server and your interface
machine, and try setting them to the same values. If you're using /TS=U, check the
time reported by the OPC server machine -- it will also have to be in the same timezone
with the same DST settings.
If you're having difficulty with getting Digital State tags configured, look at the settings
for Location2. Use PIOPCTool to find the canonical data type for the item : connect to
the server, create a group, add the item to it, and do a synchronous read. If you do not
specify a datatype when you add the item to the group, the server will return the
datatype that it uses internally for the data. VT_I2 is what we use for Digitals by
default. If the server uses VT_I4 or VT_BOOL or VT_BSTR, you can use Location2
to change the datatype that the interface will use for the tag.
Problems with getting and maintaining a connection to the PI server can be due to the
PI SDK and your network. The SDK uses "reverse name lookup" to establish a secure
connection to PI. This means that your PI server needs to be able to find the interface
node's address from the name, just as the interface machine needs to be able to find the
PI machine's address. The SDK also needs to be able to connect to the Primary

Domain Controller (PDC) for your domain, if the interface machine is part of a
domain. If you don't have Domain Name System (DNS) service set up correctly, or if
your domain configuration is not correct, you may see problems connecting to PI, or
timeouts in trying to connect. Generally, if the interface has trouble connecting, but the
non-SDK version works fine, that's an indication that you have a configuration problem
with your routers, your PDC, or your DNS. Often with multihomed PCs, which have
more than one network card and are usually connected to both a factory network and an
office network, conflicting DNS information can cause intermittent connection failures.
Debugging
The debugging flag is included to assist in understanding problematic or unexplained
behavior, such as duplicate values or invalid timestamps. Use of the debugging flag
should be limited to short periods of time, as the flag will generally cause the creation
of large files (files larger than 200 Mb would not be unusual). The flag itself is
actually a bitmask, which means you can set more than one option at the same time. A
value of /DB=5 is the same as /DB=1 and /DB=4. Here are a few of the possible
settings and what they do:
/DB=1
This is for internal testing only, and is not useful to users.
/DB=2
Logging of startup, including instrumenttag and exdesc for each tag.
/DB=4
This setting causes a number of messages to be written to the pipc.log file when write
operations are performed. Since we only send one value at a time to be written (per
group), and wait for that write to be acknowledged before sending another one, we
throttle writes using the TransID. If a server fails to acknowledge a TransID, the
symptom is that after that write, no more writes are performed to that group. This flag
will cause the OPC interface to log every time it sends a write and every time it receives
an ack, as well as any time it stores a write into its "pending write" queue. The
TransID which is printed is not necessarily valid, as v1.0a servers give us a TransID
after we send the write. Version2 servers allow us to specify the TransID.
/DB=8
Log timestamps for when Refresh is called.
This setting will cause the interface to create three files: opcscan.log, opcrefresh.log,
and opcresponse.log. If the interface is running as a service, the files will be in your
winnt/system32 directory, otherwise they will be in the directory from which you ran
the interface. Every time our routine polls a group (by calling Refresh on the OPC
group), the interface will open the opcscan.log file, write the current time, the number
of the scanclass, and the current value of the scan flag, and close the file. The
timestamp is in UTC (that means Greenwich timezone, and no daylight savings time is
observed), and it is a FILETIME structure written as an I64X field. That means that
the lower and upper halves of the number are transposed, and the actual number is a
count of the interval since Jan 1, 1601, measured in 10E-7 seconds.

After logging the data, the interface will set the scan flag for the group. Then the COM
thread will take its turn: when we cycle around to perform the poll, the interface will
open the opcrefresh.log file, log the time, the scanclass, and the TransID used (note that
the TransID logged for v1.0a servers will be the TransID that was returned from the
last poll of the group, while for v2.0 servers it will be the actual TransID returned from
the server).
When we receive data from the OPC server, the interface will open the opcresponse.log
file, and log the time, the scanclass, and the TransID received. This is virtually the first
thing done upon receiving data, if this flag is set.
/DB=16
Log information for excmax processing.
/DB=32
This setting will log the timestamp with the data, the adjusted timestamp, the PItime,
the scanclass, and TransID for each data value that the interface receives. This is a
*lot* of data. It all goes into the opcresponse.log file. Do not leave this setting on for
more than a few minutes. See the section below for more information.
/DB=64
This setting will log the same items as /DB=32, but it will log them for only the tag
specified as the debug tag (/DT=tagname). If there is no tag specified, the first tag for
which a value is received will be declared the debug tag. See the section below for
more information.
/DB=128
Logging for clustering and failover.
/DB=256
Logging for event tags. This will also cause the interface to print the name of each tag
into the pipc.log file, as it receives data for the tag. This can create very large files very
quickly, so use it sparingly, but it can also verify that the interface is or is not receiving
data for some tags. Please note that if you are running the interface interactively, you
will not see these messages in the command window for the interface, they only appear
in the log file.
/DB=512
Logging for array tags.
/DB=1024
Logging for opclist pointers. This is internal and is not useful for users.
/DB=2048
This setting will cause the interface to ignore point edits after startup. This is not
normally useful to users.

Using the opcresponse.log, opcscan.log, and opcrefresh.log Files
The interface gets notified that it's time to scan, so it logs the time in opcscan.log, along
with the group number and the current value of the flag for the group, and then sets the
flag so the other thread will see it.
opcscan.log: flag: time group
0: 1BFD631E7C98AF0 2
The other thread sees there's a flag set, so it logs the time in opcrefresh.log, and makes
the call to the server, then clears the flag. The group number and transaction ID for the
call are also logged.
opcrefresh.log: time group TransID
1BFD631E8FE1350 2 1db8
It's important to note that the flag is not cleared until the call is completed.
When data comes in, it logs the time in opcresponse.log along with the group number
and the transaction ID.
opcresponse.log: time group TransID
1BFD63208D4DCE0 2 1db8
Now, these timestamps are logged just the way they are used in the program, so we
have three tiny programs that will translate those files (we don't translate the
timestamps before we write our log files because that would take time, and what we're
generally dealing with when we use the files is a problem in how long it takes to get
data). The three programs are installed into the tools subdirectory below the interface
directory:
opcscan.exe
opcrefresh.exe
opcresponse.exe
and they each want an input file and an output file specified. Opcrefresh.log also has
an option to squeeze out duplicates, but you generally don't want to use that, so say "n".
You can run these by double-clicking on them, and they'll pop up a window and ask for
the inputs, or you can run them from a command window:
>opcscan.exe opcscan.log scan.log
>opcrefresh c:\pipc\interfaces\opcint\opcrefresh.log c:\temp\refresh.log
>tools\opcresponse opcresponse.log response.log
So now you have one or more translated files. They will look like
scan.log:
0 126054824440170000 2000/06/14 18:54:04.017 2
refresh.log
126054824440370000 2000/06/14 18:54:04.037 2 1db8
response.log
126054824974540000 2000/06/14 18:54:57.454 2 1db8
If you're using /DB=64, you will have longer lines when you get data for the debug tag
(which is either specified on the command line or, if chosen by the interface, named in
pipc.log so you know which tag it is):
response.log

126054824424850000 2000/06/14 18:54:02.485 126054680424850000 2000/06/14

14:54:02.485 960994309.485001 2 1db8
This is all on one line, and shows the UTC timestamp that came with the data, both raw
and translated, then that timestamp translated into local time, both raw and translated,
then the PITime we sent to the PI server, then the group number and the TransID.
By looking at the logfiles, you can see when we decided to poll, when we made the call,
and when the data came in. A major clue is that the flag in opcscan.log should never be
anything but zero -- if it's not zero, then the last call we made to the server has not
returned by the time we decided it was time for another poll. This should never happen,
and so if you see a 1 in that flag, you'll need to talk to your server vendor, and have
them call us.
Another common use for these files is to show the timestamp we're getting from the
OPC server. Remember, this is UTC time, which we translate into local clock time and
then adjust for PI. UTC time is based in 1600, so if you see a date around 1600 you
can be sure the server is not sending valid timestamps, and you may want to use
/TS=N to have the interface create timestamps when it gets the data.

Error and Informational Messages
Here is a partial list of the error messages you may find in your pipc.log file, and what
they mean. They will generally either have a hex number after these phrases (like
0x80007005) or they'll have another message after the phrase, if the OPC server was so
kind as to give us an explanation for the error. Other error messages are produced by
the standard OSI interface routines, or by the API, and those error messages are not
documented here. If any error message has a point number as well as a tag name,
always use the point number to identify the problem tag, because often the tagname
field that is used is one that only has 12 characters, so the tagname printed in the logfile
will not be complete.
These error messages may not exactly match the error messages in the version you're
running. What's listed here is the general part of the message. It's a good idea to do a
Find in this document to look for words from the error message that you see.
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.
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

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

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.
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
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.
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.
The error #### is Win32 Error code. The attempt to open the Cluster service and/or
the Cluster resource failed. Since the interface did not get the handle to these
objects it cannot support the interface-failover facilitated by the cluster service. An
example of this error is
5007 The cluster resource could not be found.
Please verify resource name is correct.
There are also informational messages printed; on startup, the interface will
print the scan classes with the count of tags in each class, and the update rate for
the class. After the interface is started, if points are edited in PI, the interface will
log the changes in the log file.

PIOPCTool
PIOPCTool is included with the OPC interface to make it easier to install and
troubleshoot your OPC interface and OPC server(s). It consists of an executable file
PIOPCTool.exe which can be run by double-clicking on the filename in NT Explorer or
MyComputer, or you can create a shortcut for it. It is installed into a subdirectory
called Tools, below the interface directory.
Once the program starts, youll 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 Servers Tags button to get a list of the
points that this server recognizes. If its a hierarchical list, youll 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 Servers 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 cant have two groups named Temperature on the
same OPC server. Enter a scan rate in the Update Rate box, counting in
milliseconds, so 1000 would give a scan rate of one second. Press Create to create
the group.
6. Now you can add points to the group by either double-clicking on the point in the
browse box (if the server supports browsing), or by typing the name into the Point
box. You can also select the Data Type for the point, or you can leave it blank and
let the OPC server tell you what the data type is. Some servers may require that
you specify a Data Type. You also need to type in a name for the tag -- this can be
anything you like. If you plan on saving the configuration to create tags in your PI
PIOPCTool
server, use the tagname you intend to use in PI. Press Add to Group to add the
point.
7. Once youve 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 dont 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 doesnt work, look at the help. Ive tried to include both explanations
for what might be wrong as well as suggestions on how you can verify or fix the
problem.

OPC Interface Failover
This interface supports two types of failover, one which allows the interface to collect
data from either of two servers (server-level failover), and one which allows two copies
of the interface to run on the two machines of a Microsoft cluster, with only one of
those copies actually collecting data at any given time. The two modes are designed to
work together, so that you can have redundancy for both the server and the interface.
Details of configuring failover are documented in the OPC Interface Failover Manual.
DCOM Configuration Details
A note about using DCOM without an NT Primary Domain Controller
If you do not have a Primary Domain Controller, or if your OPC server and your OPC
client machines are not within the same NT domain, DCOM cannot use NT security to
determine who can talk to whom. Therefore, it will fall back on the most basic of
security models: the account(s) under which the client and server are running must be
valid and privileged on both machines. That means that the server must have a user
account defined that is the same as the user account on the client machine under
which the interface itself (and PIOPCTool) will run. The passwords for those two
accounts must also be identical. Otherwise, DCOM will not pass any communication
between the client and the server, although it may well launch the OPC server,
leading you to believe that you should be able to talk to the server from the client
machine. Note that this account must be a local account on each machine, not a
domain account.
Your server vendor may have provided you with instructions on how to configure
DCOM for your OPC server. If so, please try to run the interface with those settings
before you try to configure your system using the following instructions. Also, its 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. Thats 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.
Thats 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 dont have documentation for
your server, its 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 DLLs. 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.
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.

Then you will see the following. Check the information is correct.
Editing entries under Location tab can change this information.

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).

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.

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

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.

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.

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 Honeywells 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, thats 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, weve found that the APP node server wants to be fully up and running
before a client connects to it. This is true of some other servers as well. The
/STARTUP_DELAY switch will let you tell the interface to wait some number of
seconds before trying to connect to the server, which will give the server time to get
fully started. Note that the server may allow the connection, and say that it is in a
RUNNING state, but not yet be ready for a client to create groups and add tags and
read data. If you have trouble on startup, especially if you have trouble when the
system is rebooted and the interface is set to automatically start as a service, try setting
that flag to 30 or 60 seconds, or even 120.
A recent version of the APP node also included a DLL (dynamic link library) for
performance counters which caused some problems. The 1.1 version of the PI SDK
loaded all the performance counter DLLs and unloaded them, but unfortunately the
Honeywell DLL calls exit when it is unloaded, causing the program to exit. This is
Not Good. You can work around that by renaming the DLL, so that it will not be
loaded. The problem description and solution are given on the OSI web site, in Online
Support under the title SDK 1.1.0.142 exits with no errors reported. The DLL which
produced this problem was DSSCOUNTERS.DLL, found in \Program
Files\Honeywell\TPS\base.
DeltaV System
Do not use the List Servers 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.
Appendix
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 dont 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 theres a new value
to send. Servers built on the FactorySoft toolkit do not send that initial value, so if you
have a data item that only changes once a week, the interface could run for a week
before it receives any data for that item. This is Not Good.
FactorySoft is aware of the problem and will fix it in the next release of their toolkit.
They have also said that they will be providing an upgrade path for servers built upon
the old toolkit. Meanwhile, they say that if you contact them, they can provide a work-
around. If your server exhibits this behavior (simple to check with PIOPCTool, just
create the group and add the tags before you press the Advisev1.0a or Advisev2.0
button: if you get data when you press Advise, your server is fine), please contact your
server vendor and ask them to investigate a fix.

Revision History
Date Author Comments
May-97 LAC Rough Draft
Jun-97 LAC Updated to reflect server issues, added PIOPCTool
description.
Sept-97 LAC Added Event Rate argument, rewrote descriptive
sections.
Oct-97 LAC Updated to Uniint v2.25
May-98 LAC Release candidate
May-99 LAC Updated for v2.0
Jun-99 LAC Updated for v2.0.6
Oct-99 KL Added descriptions for failover support and DCOMCNFG
Feb-2000 LAC Added descriptions for arrays, DLLs, DCOM notes.
April-2000 LAC Version 2.1 information, appendices.
May-2000 LAC Additional options
Aug-2000 LAC More options, clarifications
Nov-2000 LAC Version 2.1.21, new options
Mar-2001 LAC Version 2.1.22, new options
Jun-2001 LAC Version 2.1.25, minor additions
Sept-2001 LAC Version 2.1.31, new options
02-Nov-01 CG Version 2.3.4; formatting, headers, footers
05-Nov-01 KL Minor wording changes to failover section
30-Nov-2001 LAC Version 2.1.35 new options
08-May-2002 BY Clarification on options
26-Jul-02 CG Added version 2.1.37; fixed some typos; fixed TCO; fixed
headers & footers
6-Aug-2002 LAC Added version 2.1.38
2-Oct-2002 LAC Enhancements for 2.1.39
22-Jan-2003 LAC Enhancements for 2.1.41
28-Apr-2003 LAC Added DCOM caution, minor clarifications, updated
version number.
24-Jun-2003 LAC Added /SQ=I option, updated version number
16-Jul-2003 KL Corrected DCOM Identity tab configuration instructions.
21-Jul-2003 LAC Corrected Basic DCOM Identity info, updated version
Appendix
number.

PI OPCInt-nosdk 2.1.45.0

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

PI OPCInt-nosdk 2.1.45.0

Transféré par

Droits d'auteur :

Formats disponibles

OPC

Interface to the PI System

OSI Software, Inc.

OSI Software GmbH OSI Software, Asia Pte Ltd

2000 - 2003 OSI Software, Inc. All rights reserved

OSI Software, Inc.

iv OSI Software, Inc.

OPC Server Issues.......................................................................................................61

Error and Informational Messages..............................................................................71

OPC Interface to the PI System v

OPC Interface Failover.................................................................................................81

DCOM Configuration Details.......................................................................................83

Appendix A: Notes on Some OPC Servers................................................................93

vi OSI Software, Inc.

2 OSI Software, Inc.

Vendor Software Required on DCS System

OPC Interface to the PI System 3

Additional PI Software Included with Interface

Requirements - PI2 and PI3 Servers

Upgrading from Version 1.x or 2.0 to 2.1 or Higher

4 OSI Software, Inc.

OPC Interface to the PI System 5

Notes on OPC and COM

Writing Timestamps to the Device

8 OSI Software, Inc.

Connections - Creating, Losing, and Recreating

The OPCEnum Utility

OPC Interface to the PI System 9

Plug-In Post-processing DLLs

Polling, Advising and Event Tags

10 OSI Software, Inc.

Reading Digital, Integer, and Real Tags as Strings

Reading Tags as Booleans

OPC Interface to the PI System 11

Reading Tags as 4-byte Integers

Reading Tags as Float64 Values

Converting Timestamps into Seconds

Reading Timestamps as VT_DATE Datatypes

12 OSI Software, Inc.

Not Specifying a Datatype

Transformations and Scaling

OPC Interface to the PI System 13

14 OSI Software, Inc.

OPC Interface to the PI System 15

Convers TotalCode SquareRoot DZero Operation:

16 OSI Software, Inc.

Quality no /SQ flag /SQ=Y /SQ=I

Storing Quality Information Directly

Quality States Used with PI Systems Earlier than PI 3.3

Not used by OPC

OPC Interface to the PI System 17

Quality States Used with PI Systems Version PI 3.3 and Later

Not Used by OPC

18 OSI Software, Inc.

OPC Interface to the PI System 19

22 OSI Software, Inc.

A Note on Performance Points

OPC Interface to the PI System 23

24 OSI Software, Inc.

Location2 > 1024

OPC Interface to the PI System 25

26 OSI Software, Inc.

OPC Interface to the PI System 27