Documente Academic
Documente Profesional
Documente Cultură
version 2.1.45.0
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
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
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
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
PIOPCTool.....................................................................................................................79
Revision History........................................................................................................... 95
15 December 2009 BV 1
Introduction
Configurations
The Preferred Configuration
Another Possibility
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.
15 December 2009 BV 7
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.
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.
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.
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.
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
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.
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).
Good Quality
Quality OPC Definition PI Status
11SSSSLL Non-specific Good
Except
110110LL Local Override _SUBStituted
Questionable
Quality OPC Definition PI Status
010110LL Sub-Normal Bad_Quality
010101LL Engineering Units Exceeded
QQSSSS01 Low Limited Under LCL
QQSSSS10 High Limited Over UCL
Otherwise Inp OutRange
010100LL Sensor Not Accurate
QQSSSS01 Low Limited Under Range
QQSSSS10 High Limited Over Range
Otherwise Out of calibration Invalid Data
010011LL Invalid Bad Input
010010LL Invalid Bad Input
010001LL Last Usable Value No_Sample
010000LL Non-specific Doubtful
Bad Quality
Quality OPC Definition PI Status
000111LL Out of Service DCS failed
000110LL Comm Failure Arc Off-line
000101LL Last Known Value Scan Timeout
000100LL Sensor Failure Equip Fail
000011LL Device Failure Unit Down
000010LL Not Connected AccessDenied
000001LL Configuration Error Configure
000000LL Non-specific Bad
Good Quality
Quality OPC Definition PI Status
11SSSSLL Non-specific Good
Except
110110LL Local Override _SUBStituted
Bad Quality
Quality OPC Definition PI Status
000111LL Out of Service Out of Service
000110LL Comm Failure Comm Failure
000101LL Last Known Value Scan Timeout
000100LL Sensor Failure Equip Fail
000011LL Device Failure Unit Down
000010LL Not Connected Not Connected
000001LL Configuration Error Configure
000000LL Non-specific Bad
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
15 December 2009 BV 21
PI Point Configuration
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.
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 = 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.
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.
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.
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.
15 December 2009 BV 29
Software Configuration
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.
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.
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.
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.
Parameter Description
/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.
Parameter Description
/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
Parameter Description
/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.
Parameter Description
/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 #.
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.
Parameter Description
/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
/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
15 December 2009 BV 47
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.
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)
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.
Scan Classes
Scan classes are defined in the opcint.bat file. Each /F= parameter defines a scan class,
which we number in order, so if your .bat file has
/F=2 /F=1:00 /F=1:30:00 /F=00:00:05
then you have defined these scan classes
Scan Class 1 has scan period 2 seconds
Scan Class 2 has scan period 60 seconds
Scan Class 3 has scan period 5400 seconds (90 minutes)
Scan Class 4 has scan period 5 seconds
Remember that the first scan class is reserved for Advise tags. All other scan classes
can have either advise tags or polled tags, and you can have as many classes for each
type of tag as you need (as long as your server supports that many groups).
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
15 December 2009 BV 51
Configuring Tags
Tag exdesc instrumenttag loc1 loc2 loc3 loc4 loc5 userint1 userint2
FiveSecond.PV ItemID1 1 0 0 4 0 0 0
OneMinute.PV ItemID2 1 0 0 2 0 0 0
NinetyMinute.PV ItemID3 1 0 0 3 0 0 0
AdvFiveSecs.PV ItemID1 1 0 1 8 0 0 0
AdvOneMin.PV ItemID2 1 0 1 6 0 0 0
AdvNinetyMins.PV ItemID3 1 0 1 7 0 0 0
For polled array tags, you would set Location3=0 for all the array tags, and set
Location4 to the scan class for the array.
Tag exdesc instrumenttag loc1 loc2 loc3 loc4 loc5 userint1 userint2
ArrayTag0001.PV Data.Array 1 0 0 4 0 1 0
ArrayTag0002.PV Data.Array 1 0 0 4 0 2 0
ArrayTag0002.PV Data.Array 1 0 0 4 0 3 0
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.
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
15 December 2009 BV 57
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 Directories
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.
15 December 2009 BV 59
Interface Installation
The dlls, their supporting files, and the documentation for their usage are all installed
into a subdirectory below the interface directory called Plug-Ins.
OPCEnum Directory
The OPCEnum tool is mentioned elsewhere in this document. The executable and the
files needed for using it on another machine are installed into a subdirectory below the
interface directory called OPCEnum.
Tools Directory
Various tools are included in the installation, most prominently the PIOPCTool itself.
These are installed into a subdirectory below the interface directory called Tools.
Security
If the home node is a PI 3 server, the PI Firewall Database and the PI Proxy Database
must be configured so that the interface is allowed to write data to the PI Data Archive.
See Modifying the Firewall Database and Modifying the Proxy Database in the PI
Data Archive Manual.
If the home node is a PI 3.3 server, or higher, then you will need to establish a trust
relationship for the interface. Again, see the PI archive manual for how to do that.
If the home node is a PI 2 server, the read/write permissions should be set appropriately
in the pisysdat:piserver.dat file on the PI 2 home node. For more information on
setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 2 or PI 3 server because it has insufficient
privileges, a 10401 error will be reported in the pipc.log file. See the section Error
and Informational Messages for additional information on error messaging.
Interface Checklist
The OPC interface comes with an installation application. Executing the application
will copy the necessary files to your hard disk and install the interface as a service.
However, you will still need to edit the startup parameters. Alternatively, you can
install and use the PI Interface Configuration Utility (PI-ICU) if you're using PI3
version 3.3 or higher, and we do recommend that you use the ICU if you can. It makes
configuration much simpler.
In the installation process, you are given the opportunity to specify where to install the
interface files. If you took the defaults, the directory is opcint. If you specified
another directory, everywhere that this manual says "opcint", you should insert the
name of the directory you specified. If your directory name has spaces embedded, as in
"OPC for PI", you'll have to enclose it with double quotation marks. In your
installation directory there will be a sample command file OPCInt.bat (there's your
first substitution, if you used another directory). For information on how to configure
this file, see Software Configuration: Command-line Parameters.
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
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.
15 December 2009 BV 67
Interface Installation
IOPCServer
This error indicates that you do not have the proxy stub registered. The
opcproxy.dll and opccomn_ps.dll files are included in this distribution. To register
them, open a Command Prompt window, change to the directory where the
interface was installed, and type the following commands. The system should pop
up a window after each line, telling you that the DLL was registered.
>regsvr32 opcproxy.dll
>regsvr32 opccomn_ps.dll
AddRef
This means the OPC server would not let the interface do the simplest function. If
you are able to read and write tags using PIOPCTool, but you get this error, you
almost certainly have some permissions problem. Recheck your DCOM settings,
check what user the interface is running as, try running the interface interactively
(see above on how to do this)
No ConnectionPoint for OPCShutdown
Shutdown Advise Failed
There are not fatal errors, it just means that the OPC server does not implement the
Shutdown interface, or doesn't implement it properly; if the server goes down, we'll
only know about it because it stops answering our calls. This will not prevent
proper operation of our interface.
Advise returns error: 80040202(Unable to open the access token of the current
thread)
If you believe you configured DCOM correctly, and you still keep getting this error
after connecting to the server successfully, it is possible that the wrong opcproxy.dll
is being loaded. If you have multiple copies of opcproxy.dll on your API node
(possibly because you have more than one OPC server on your machine), make
sure that they are the same version. It is safest to have only one version around on
your system (in \winnt\system32 directory, that being the latest version). If they are
from before June, 1999, they may contain an error which causes errors like above.
If the directories containing such versions are specified in the system path, that is
why you get the above error although you configured everything correctly.
Unable to advise group
Unable to advise output group
Unable to advise event group
Unable to create group
Unable to add to group
Unable to add to OPC group.
AddGroup failed for scanclass %d
QueryInterface:IID_IOPCAsyncIO2 failed for scanclass %d
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.
15 December 2009 BV 75
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.
15 December 2009 BV 77
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.
15 December 2009 BV 79
Appendix
Then run
C:>regsvr32 opccomn_ps.dll
The following dialog box should show up.
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 select Identity tab and select This user, and specify an account with
administrator privileges. OPCint service must also be configured in
ControlPanel/Services/Startup to log on as that account.
Do not use the Local System account to run programs that use DCOM. While the
Local System account has plenty of privileges locally, it has no authority outside its
own system.
Now, if you had to make any changes to the existing selections and/or entries so far,
click on Apply, and if not click Cancel to get back to the main Application tab.
Click on Default Properties tab and make sure the entries look like following
Click on Edit Default for Default Access Permissions. Make sure that at least all of the
following accounts are there.
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.
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.
15 December 2009 BV 87
Appendix
Instead, use the Manual Tag List button to list the items one level at a time.
15 December 2009 BV 89
Appendix
number.