PI AutoPointSync Connector
for the OPC HDA
Interface to the PI System
Version 1.0.1.0
Revision C
How to Contact Us
OSIsoft, Inc.
Worldwide Offices
777 Davis St., Suite 250
OSIsoft Australia
San Leandro, CA 94577 USA
Perth, Australia
Auckland, New Zealand
Telephone
(01) 510-297-5800 (main phone)
OSI Software GmbH
Altenstadt, Germany
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
OSI Software Asia Pte Ltd.
Singapore
[email protected]
OSIsoft Canada ULC
Montreal, Canada
Houston, TX
OSIsoft, Inc. Representative Office
Johnson City, TN
Shanghai, People’s Republic of China
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
OSIsoft Japan KK
Tokyo, Japan
Seattle, WA
OSIsoft Mexico S. De R.L. De C.V.
Yardley, PA
Mexico City, Mexico
Sales Outlets and Distributors

Brazil

South America/Caribbean

Middle East/North Africa

Southeast Asia

Republic of South Africa

South Korea

Russia/Central Asia

Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI
ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book
that are known to be trademarks or service marks have been appropriately capitalized. Any trademark
that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein
in no way indicates an endorsement, recommendation, or warranty of such party's products or any
affiliation with such party of any kind.
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
Unpublished -- rights reserved under the copyright laws of the United States.
© 2005 - 2006 OSIsoft, Inc.
PI_OPCHDAInt_APS.doc
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
ii
Table of Contents
Introduction ................................................................................................................... 1
Reference Manuals ..................................................................................................... 2
Summary of Features and Requirements .................................................................... 3
Supported PI Point Attributes....................................................................................... 4
Diagram of PI APS for the OPCHDAInt Interface ....................................................... 10
OPCHDAInt_APS Features and Limitations .............................................................. 11
Selecting OPC Items for New PI Points ................................................................. 11
Assignment of Actual OPC Attributes to Generic Attributes.................................... 14
Quality Points......................................................................................................... 19
Limitations ............................................................................................................. 20
Principles of Operation............................................................................................... 21
Point Class ................................................................................................................ 21
Point Source and Instance ID .................................................................................... 22
Key Attributes ............................................................................................................ 22
Creatable and Synchronizable Attributes ................................................................... 22
Available and Hidden Points ...................................................................................... 23
Tag Naming Conventions ...................................................................................... 25
Point Type ............................................................................................................. 25
Updated Attributes ..................................................................................................... 26
Installation, Upgrading, and Uninstallation Instructions.......................................... 27
Installation Instructions .............................................................................................. 27
Upgrading Instructions ............................................................................................... 27
Uninstallation Instructions .......................................................................................... 28
Registering an Interface Instance with PI APS ......................................................... 29
Register the Interface ................................................................................................ 30
Configure the Settings ............................................................................................... 34
Rules ..................................................................................................................... 35
Synchronization Schedule...................................................................................... 36
User-set Defaults ................................................................................................... 37
Connector-specific Options .................................................................................... 43
Enable Synchronization ............................................................................................. 44
Connector-specific Configuration Control ................................................................ 45
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
iii
Table of Contents
OPC Attributes Tab ................................................................................................... 47
Point Creation Tab..................................................................................................... 50
Attribute Formulas Tab .............................................................................................. 54
Appendix A: Error and Informational Messages ....................................................... 59
Installation Problems ................................................................................................. 59
Upgrade Problems..................................................................................................... 60
Operational Problems ................................................................................................ 60
Glossary ...................................................................................................................... 63
Revision History.......................................................................................................... 65
iv
Introduction
This manual describes the operation of the PI AutoPointSync (PI APS) Connector for the
PI OPC HDA Interface. HDA is an acronym for Historical Data Access that refers to
programming interface standards issued by the OPC Foundation. Both the PI OPC HDA
Interface and this PI APS Connector are OPC HDA client applications.
The informal name of the interface is PI OPCHDAInt and the informal name of this
PI APS Connector is OPCHDAInt_APS.
PI APS is a tool for synchronizing the PI points for interfaces with the points in the data
sources associated with the interfaces. PI APS is based on Microsoft’s Component Object
Model (COM) technology and consists of four types of modules:

The PI APS Configuration and Management Utility.
The PI APS Configuration Utility is the interactive interface that registers instances
of interfaces that have corresponding PI APS Connectors for automatic point
synchronization and configures PI APS options.

The PI APS Synchronization Engine (Sync Engine).
The PI APS Sync Engine schedules synchronization scans and performs point
attribute synchronization for all interface instances that are registered with PI APS.
This module is the foundation of PI APS and does most of the work. The PI APS
Sync Engine is installed as a Windows service that starts automatically and is the
only PI APS module that is always running.

PI APS Connector modules (Interface-specific Connectors).
PI APS Connectors are interface-specific modules that call the application
programming interface (API) for the same data source as the interface to determine
point attribute updates. During each synchronization scan, the PI APS Sync Engine
invokes the PI APS Connector for the interface instance to retrieve a list of current
point definitions in the data source. The PI APS Sync Engine then uses this
information for updating the PI point database.

PI APS Connector-specific Configuration Controls.
Each PI APS Connector-specific Configuration Control provides the user interface
for configuring the options of a specific PI APS Connector. If the PI APS Connector
for an interface instance has a connector-specific configuration control, the PI APS
Configuration Utility makes it available when the interface is selected for
configuration.
The modularized architecture of PI APS allows a single instance of the PI APS
Configuration Utility and PI APS Sync Engine to support multiple PI APS Connector
modules on one computer. Also, adding new PI APS Connector modules does not require
changes to the PI APS Configuration Utility or PI APS Sync Engine. The use of COM
allows individual components to be upgraded independently of the other components.
When synchronizing the PI points for an interface instance, the PI APS Sync Engine uses
an interface-specific PI APS Connector to obtain current point definitions from the data
source. For the PI OPCHDAInt Interface, the PI APS Sync Engine calls the
OPCHDAInt_APS Connector to retrieve a list of the current point definitions from the
OPC HDA server. This information is used for creating, updating, or deleting PI points
for the PI OPCHDAInt Interface instance registered with the OPCHDAInt_APS
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
1
Introduction
Connector. PI APS provides many options to tailor its operation for each registered
interface instance. Some options apply to the interface instance, such as the period
between synchronization scans or the changes that the PI APS Sync Engine is permitted
to make automatically. Other options apply to individual PI points, such as whether the
PI APS Sync Engine is allowed to synchronize the point as a whole and, if so, which
specific attributes are editable. The PI APS Sync Engine logs all automated actions and
changes for auditing by the administrator.
Terminology and Definitions
In this manual, OPC refers to OPC HDA unless specifically stated otherwise. For
example, OPC server in this manual means an OPC HDA server.
The points in an OPC server are referred to as Items. Each Item in an OPC server is
identified by a unique string known as its ItemID.
Reference Manuals
OSIsoft

PI AutoPointSync for Interfaces and PI COM Connectors (PI-APSUserManual.doc)

PI Interface Configuration Utility User Manual (PI-ICUUserManual.doc)

OPC HDA Interface to the PI System (PI_OPCHDAInt.doc)
OPC Foundation

2
OPC Historical Data Access Specification, Version 1.20
Summary of Features and Requirements
The following table summarizes the main features and requirements of the
OPCHDAInt_APS Connector. An asterisk (*) in the table indicates that additional
explanation follows the table.
Feature
Support
* Platforms
Windows (2000, XP, 2003)
PI Point Types
All
Interface Instance ID Attribute
Location1
Point Class
Classic (see the “Point Class” section)
Synchronizable PI Attributes
See the “Supported PI Point Attributes”
table
Must install on PI Server
No
Must install on OPC HDA server node
No
Must install on Interface node
No
Tag Selection Conditions
Yes
Tag Naming Rules
Yes
Attribute Formulas
Yes
Attribute Lookup
No
* Additional PI Software Required
Yes
Vendor Software Required on PI APS Node
No
* Vendor Software Required on Foreign
Device
Yes
Vendor Hardware Required
No
Additional PI Software Included with
PI APS Connector
No
* Data Source Point Types
All
Platforms
The PI APS Connector is supported on the following Microsoft Windows operating
systems:

Windows 2000

Windows XP

Windows 2003
Please contact OSIsoft Technical Support for more information.
Additional PI Software Required
PI APS obtains information about installed interface instances from the PI Interface
Configuration Utility (PI ICU) configuration data stored in the Module Database. Also,
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
3
Introduction
PI APS stores its configuration information in the Module Database. Therefore, PI APS
requires installation of the OSIsoft products in the following list. In general, these
additional OSIsoft products can be installed on separate computers. See the “Diagram of
PI APS for the OPCHDAInt Interface” section for restrictions that apply to the
OPCHDAInt_APS Connector.

PI Server version 3.3.361.43 or greater is required for Module Database support.

PI OPC HDA Interface.

PI ICU on the interface node because an interface instance must be managed by
PI ICU before it can be registered with PI APS.
Vendor Software Required on Foreign Device
The PI APS Connector for the PI OPC HDA Interface is an OPC Historical Data Access
client. The OPC HDA Standard requires an OPC server to implement a basic set of
functions. Using the minimal set of OPC HDA interfaces, the OPCHDAInt_APS
Connector supports synchronization of existing PI OPCHDAInt Interface points, deletion
of PI points that correspond to nonexistent OPC server points, and creation of PI points
for OPC server points that do not have corresponding PI points.
Data Source Point Types
The OPC HDA Standard contains more Item types than PI point types. The most
common Item types have equivalent PI point types, but some Item types do not. The
OPCHDAInt_APS Connector provides a configurable choice of PI point type for each
Item type. The default configuration settings associate a suitable PI point type with each
Item type.
Supported PI Point Attributes
The following table lists the PI point attributes that the OPCHDAInt_APS Connector
supports. An asterisk (*) in the table indicates that additional explanation follows the
table.
Generic Attribute Column
The OPC HDA Standard provides for Items to have attributes but does not specify the
actual attributes that an OPC server must implement. Since the OPCHDAInt_APS
Connector cannot make any assumptions regarding the actual OPC attributes that an
indeterminate OPC server supports, the OPCHDAInt_APS Connector implements a set
of generic attributes that serve as placeholders for the actual attributes from the specific
OPC server being used. Configuration settings select the actual OPC attributes that the
OPCHDAInt_APS Connector requests from the OPC server and assigns to each generic
attribute. The “Assignment of Actual OPC Attributes to Generic Attributes” section
contains additional discussion of this feature and the “OPC Attributes Tab” section
discusses configuration.
Synchronizable Column
The “Sync.” column indicates whether an attribute is used for point creation only or for
both point creation and synchronization of existing points.
4
“No” in this column indicates that the attribute cannot be synchronized. That is, the
PI APS Connector can provide a value for this attribute for point creation but the attribute
cannot be edited for an existing point. For example, the PI Server does not allow the
PointType attribute to be changed after a point is created.
“Yes” in this column indicates that the PI APS Connector is capable of obtaining new
values from the data source for editing the attribute. However, the per-point
synchronization settings govern whether the attribute will actually be edited for a specific
point.
Default Value Column
The “Default Value” column in the table shows the default values that will be assigned to
attributes for new points that PI APS creates. The notation “<APS Config>” in this
column indicates that the default value can be configured with the PI APS Configuration
Utility. The configurable default values can be viewed and changed on the Security &
Archive Settings tab in the User-set Defaults dialog box.
Description
PI Point Attribute
Generic Attribute
Sync.
Default Value
No
See “Tag
Naming
Conventions”
section
OPCPIPointtype
No
See “Point
Type” section
OPCItemID
No
ItemID
No
0 or 1
OPCLocation3
No
0
Location4
OPCLocation4
Yes
1
Location5
OPCLocation5
Yes
0
Point Description
Descriptor
OPCDescription
Yes
<blank>
Extended
Description
* ExDesc
OPCExDesc
varies
<blank>
Engineering Units
EngUnits
OPCEngUnits
Yes
<blank>
Point Zero
* Zero
OPCZero
Yes
0
Point Span
* Span
OPCSpan
Yes
100
Digital Set Name
* DigitalSet
OPCDigitalSetName
Yes
<no default>
States in Digital Set
* DigitalStateSet
OPCDigitalStates
Yes
<no default>
Stepped changes
Step
OPCStepped
Yes
Off
Collect point data
Scan
OPCArchiving
Yes
On
Compression
Minimum time
between events
CompMin
OPCCompMin
Yes
<APS Config>
Compression
Maximum time
between events
CompMax
OPCCompMax
Yes
<APS Config>
PI Tag Name
Tag
PI Point Type
PointType
OPC ItemID
InstrumentTag
Data/Quality
Location2
Input/Output
Location3
Scan class
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
5
Introduction
Description
PI Point Attribute
Generic Attribute
Sync.
Default Value
Compression
Deviation in
engineering units
* CompDev
OPCCompDev
Yes
<APS Config>
Compression
Deviation as a
percent of span
* CompDevPercent
OPCCompDevPercen
t
Yes
<APS Config>
Exception Minimum
time between events
ExcMin
OPCExcMin
Yes
<APS Config>
Exception
Maximum time
between events
ExcMax
OPCExcMax
Yes
<APS Config>
Exception Deviation
in engineering units
* ExcDev
OPCExcDev
Yes
<APS Config>
Exception Deviation
as a percent of span
* ExcDevPercent
OPCExcDevPercent
Yes
<APS Config>
Typical value for
point
TypicalValue
OPCTypicalValue
Yes
50
TotalCode
OPCTotalCode
Yes
0
SquareRoot
OPCSquareRoot
Yes
0
Convers
OPCConvers
Yes
1
UserInt1
OPCUserInt1
Yes
0
UserInt2
OPCUserInt2
Yes
0
ExDesc
The preferred method of configuring a PI OPCHDAInt Interface point is to set the
InstrumentTag attribute to the ItemID. When an interface point has a non-blank
InstrumentTag attribute (presumed to be the ItemID), the interface does not use the
ExDesc attribute. If a point has a non-blank InstrumentTag attribute and the
OPCHDAInt_APS Connector is configured to obtain a value for the ExDesc attribute,
this attribute is synchronizable.
If the InstrumentTag attribute is blank, the PI OPCHDAInt Interface expects to find the
ItemID encoded in the ExDesc attribute and the ExDesc attribute is not synchronizable.
Zero and Span
The OPCHDAInt_APS Connector contains logic to derive values for the OPCZero and
OPCSpan generic attributes if the OPC server provides lower and upper limit attributes.
The “Creatable and Synchronizable Attributes” section contains additional details.
DigitalSet
The OPCHDAInt_APS Connector provides two options for creating PI digital points.
First, the default PI point type for one or more Item types can be configured to digital PI
point type. When an Item type is configured to digital PI point type, the name of an
existing digital set is a required part of the configuration.
6
The second option for creating PI digital points is to use the Attribute Formulas feature
to override the default PI point type for selected Items. When an attribute formula sets the
OPCPIPointtype generic attribute to digital, an associated attribute formula must set the
OPCDigitalSetName generic attribute.
For an existing PI point, its actual point type is the default value for the OPCPIPointtype
generic attribute. Changing the OPCPIPointtype generic attribute with an attribute
formula has no effect on an existing PI point. However, an attribute formula can construct
an OPCDigitalSetName generic attribute value for an existing digital point.
Caution: Attribute formulas to construct digital set names must be designed to
evaluate to a small set of unique names. Otherwise, the maximum number of digital sets
supported by the PI Server can be consumed. Since the PI Server never deletes digital
sets, recovery usually requires restoring from a backup.
To avoid the possibility of reaching the limit on the number of digital sets, restrict
formulas for the OPCDigitalSetName generic attribute to literal names of existing
digital sets. In particular, do not include a generic attribute that can be different for every
Item (like OPCItemID) in an attribute formula for the OPCDigitalSetName generic
attribute.
DigitalStateSet
DigitalStateSet is an artificial attribute that PI APS uses internally; it is not an actual PI
attribute. The DigitalStateSet attribute only applies to digital points and is coupled with
the DigitalSet attribute. For a digital point, the value in the DigitalSet attribute contains
the name of the PI digital set for the point. If the DigitalStateSet attribute for the point is
not empty, its value is a list of the states expected in the digital set.
The OPCHDAInt_APS Connector does not provide a default value for the
OPCDigitalStates generic attribute. An attribute formula for the OPCDigitalStates
generic attribute is the primary means of assigning a list of states to the DigitalStateSet
attribute. As the remainder of this section explains, enabling synchronization for the
DigitalStateSet attribute has the potential to consume all digital sets in the PI Server and,
therefore, must be undertaken with great care.
When the PI APS Connector returns both a digital set name and a list of states in the set
to the PI APS Sync Engine, the PI APS Sync Engine checks whether a digital set already
exists in the PI Server with the name.
If the digital set does not exist, the PI APS Sync Engine creates a digital set with that
name and the states in the digital state list.
If the digital set does exist, the PI APS Sync Engine compares the state list for the digital
set in the PI Server with the state list provided by the PI APS Connector. If the state lists
agree, the PI APS Sync Engine edits the DigitalSet attribute of an existing point to the
digital set name from the PI APS Connector or sets the DigitalSet attribute of a point
being created to the digital set name from the PI APS Connector. However, if the state
list for a digital set in the PI Server disagrees with the state list provided by the PI APS
Connector for a point that the PI APS Sync Engine will automatically create or edit, the
PI APS Sync Engine creates a new digital set with a unique digital set name that
contains the states in the state list from the PI APS Connector. The PI APS Sync Engine
uses the new unique digital set name (not the original name provided by the PI APS
Connector) to edit an existing point or create a new point. Because the check for
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
7
Introduction
agreement between digital state lists occurs on a point-by-point basis, a digital set with a
new unique name will be created for each point when the digital set name exists and the
state lists disagree.
Caution: Disagreement between the state list for an existing digital set and the
state list from the data source can result in the creation of a large number of digital sets.
In extreme cases, the maximum number of digital sets supported by the PI Server can be
consumed. Since the PI Server never deletes digital sets, recovery usually requires
restoring the PI Server from an earlier backup.
Unless constraints on the data source and attribute formulas guarantee that the conditions
described above cannot occur, OSIsoft emphatically recommends disabling
synchronization of the DigitalStateSet attribute.
CompDev and CompDevPercent
The OPCHDAInt_APS Connector supports the CompDev and CompDevPercent
attributes. Depending on the OPC server and configured attribute formulas, this PI APS
Connector can send values for both, one, or none of these attributes to the PI APS Sync
Engine for a particular point. The CompDev and CompDevPercent attributes are
interrelated in the PI Server; setting or editing one affects the value of the other. If both
are sent to the PI Server in one operation, the PI Server gives precedence to the
CompDevPercent attribute and calculates the CompDev attribute from the
CompDevPercent and span attributes.
When the PI APS Sync Engine synchronizes an existing point, the individual attribute
options for the point control which attributes are edited. Since the CompDevPercent
attribute is expressed as a percent of span, the span attribute must be enabled for
synchronization when the CompDevPercent attribute is enabled.
If options for an existing point enable synchronization for one of the CompDev and
CompDevPercent attributes, the enabled attribute is edited.
If options for an existing point enable synchronization of both CompDev and
CompDevPercent attributes, the PI Server gives precedence to the CompDevPercent
attribute.
For new points, the general PI APS configuration for an interface instance provides an
option to set a default value for one of the CompDev or CompDevPercent attributes. If
the selected attribute for compression deviation default value does not have a value from
the PI APS Connector, the PI APS Sync Engine will merge the default compression
deviation attribute with the attributes from the PI APS Connector, which can contain the
other compression deviation attribute. If the PI APS Connector returns one compression
deviation attribute to the PI APS Sync Engine and the general PI APS configuration
supplies the other, both will be sent to the PI Server and the CompDevPercent attribute
will have precedence. To avoid unwanted interactions with the general PI APS
configuration when the PI APS Connector is supplying one of the compression deviation
attributes, configure the same compression deviation attribute in the general PI APS
options.
8
Excdev and ExcDevPercent
The OPCHDAInt_APS Connector supports the ExcDev and ExcDevPercent attributes.
Depending on the OPC server and configured attribute formulas, this PI APS Connector
can send values for both, one, or none of these attributes to the PI APS Sync Engine for a
particular point. The ExcDev and ExcDevPercent attributes are interrelated in the
PI Server; setting or editing one affects the value of the other. If both are sent to the
PI Server in one operation, the PI Server gives precedence to the ExcDevPercent
attribute and calculates the ExcDev attribute from the ExcDevPercent and span
attributes.
When the PI APS Sync Engine synchronizes an existing point, the individual attribute
options for the point control which attributes are edited. Since the ExcDevPercent
attribute is expressed as a percent of span, the span attribute must be enabled for
synchronization when the ExcDevPercent attribute is enabled.
If options for an existing point enable synchronization for one of the ExcDev and
ExcDevPercent attributes, the enabled attribute is edited.
If options for an existing point enable synchronization of both ExcDev and
ExcDevPercent attributes, the PI Server gives precedence to the ExcDevPercent
attribute.
For new points, the general PI APS configuration for an interface instance provides an
option to set a default value for one of the ExcDev or ExcDevPercent attributes. If the
selected attribute for exception deviation default value does not have a value from the
PI APS Connector, the PI APS Sync Engine will merge the default exception deviation
attribute with the attributes from the PI APS Connector, which can contain the other
exception deviation attribute. If the PI APS Connector returns one exception deviation
attribute to the PI APS Sync Engine and the general PI APS configuration supplies the
other, both will be sent to the PI Server and the ExcDevPercent attribute will have
precedence. To avoid unwanted interactions with the general PI APS configuration when
the PI APS Connector is supplying one of the exception deviation attributes, configure
the same exception deviation attribute in the general PI APS options.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
9
Introduction
Diagram of PI APS for the OPCHDAInt Interface
The architecture and implementation of PI APS requires installation of the PI APS Sync
Engine, PI APS Configuration Utility, and the PI APS Connector(s) on the same
computer (identified as PI APS Node in the diagram above). PI ICU must be installed on
the PI Interface node. In general, the PI APS components, PI Server, interface, and data
source can be distributed on four separate computers as depicted in the diagram. If the
PI Interface node or data source computer has low CPU usage, the PI APS components
can be installed on the same node as the PI Interface or data source.
10
OPCHDAInt_APS Features and Limitations
The OPC HDA Standard defines the programming interface that an OPC HDA client
uses to access an OPC server. From the perspective of the OPCHDAInt_APS Connector
as an OPC HDA client, significant aspects of OPC server behavior are not specified by
the OPC HDA Standard. As a result, two OPC servers that are technically compliant with
the OPC HDA Standard can be very different in details that are relevant to PI point
configuration and synchronization. The following sections describe features of the
OPCHDAInt_APS Connector that provide options for adapting to the differences
between OPC servers.
Selecting OPC Items for New PI Points
The OPCHDAInt_APS Connector provides several configurable options to filter the OPC
server points that are candidates for creating new PI points. The following discussion
provides background information which is necessary to understand the filtering options.
An OPC server contains a browser interface that allows an OPC client to discover the
Items in the OPC server. The browser interface presents a hierarchical, tree-structured
view composed of branches and leaves. Branches and leaves are collectively referred to
as nodes of the browser hierarchy. As a client descends through the branches of the
browser hierarchy, leaf nodes can appear in any branch, not just the deepest branches.
While leaf nodes always represent Items, each OPC server implementation determines
whether any of its branches are Items.
Usually, the browser for an OPC server returns node names that are not ItemIDs. The
distinction between the node names in the browser hierarchy and actual ItemIDs is
significant for the filtering features of the OPCHDAInt_APS Connector. To illustrate the
relation between node names in the browser and ItemIDs, consider the browser hierarchy
in the following figure from the OPC server for a PLC (Programmable Logic Controller)
system.
Figure 1. Example Browser Hierarchy for a PLC
In this tree view of the browser hierarchy, the presence of an expand or contract
button indicates a branch. In Figure 1, Channel_1, Device_1, _System, and _Hints
are branches, which are not Items in this OPC server. The remaining nodes indicate
leaves, which are Items. The OPC HDA Standard requires only that leaf and branch
names are unique within their parent branch, and this browser returns short leaf names
that are not ItemIDs. For this particular OPC server, the ItemID for the Tag_1 leaf is
Channel_1.Device_1.Tag_1.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
11
Introduction
The ItemIDs in the OPC server in Figure 1 are directly related to the path through the
browser hierarchy from the root to the leaf. However, the OPC HDA Standard does not
specify the actual organization of the browser hierarchy or structure of ItemIDs, and not
all OPC HDA servers follow this pattern.
Each OPC server defines a browser hierarchy appropriate for its underlying control
system or instrumentation. The browser hierarchy may even provide alternate views of
the same Items in different branches of the browser hierarchy. For example, consider the
browser hierarchy in the following figure from the OPC server for a Distributed Control
System (DCS).
Figure 2. Example Browser Hierarchy for a DCS
The browser hierarchy shown in Figure 2 is from a distributed control system that
provides multiple views of its Items. The Modules branch organizes the Items by plant
area and the IO branch (not expanded) organizes the Items by instrumentation units. In
this specific control system, low-level input and output Items appear under both branches
(not shown in the figure). Since the OPC HDA Standard allows a browser to show an
Item in more than one branch, the ItemID is not necessarily composed from the path
through the browser hierarchy to the Item. The following figure expands the AREA_A
branch from Figure 2.
Figure 3. Expanded AREA_A for DCS Browser
In Figure 3, the actual ItemID for the CV leaf in this OPC server is
BFO_TEST/AI1/ABNORM_ACTIVE.CV. Unlike the OPC server in Figure 1, all branches
in the path from root to leaf are not part of the ItemID. In this OPC server, the browser
12
hierarchy provides information that is not available from either the ItemID or other
attributes of the Item.
The OPCHDAInt_APS Connector provides three features for selecting the Items for
which new PI points will be created:

Browser Branch Selection

Browser Node Type

Tag Selection
The following descriptions of these features are brief outlines. The “Available and
Hidden Points” section contains additional details on the operation of these features. The
“Tag Selection” and “Point Creation Tab” sections discuss configuration of these
features.
Browser Branch Selection
The OPC HDA Standard does not specify the actual organization of the browser
hierarchy. Instead, each OPC server is allowed to organize its browser hierarchy in a
manner that helps a human user locate Items for points in the underlying control system
or instrumentation. In general, the OPCHDAInt_APS Connector must explore every
branch of the browser hierarchy to discover all Items in an OPC server. For OPC serverspecific or site-specific reasons, however, only the Items in a subset of the branches may
be applicable to an interface instance. Returning to the example OPC server in Figure 2,
an OPC server-specific reason to explore only certain branches is that the top-level
branches are alternate views of the same Items, so exploring all of the top-level branches
will discover each Item multiple times. For the OPC server in Figure 2, exploring the
Modules branch will reveal all Items, and exploring the other top-level branches is
unnecessary overhead.
In some OPC servers, the browser hierarchy provides information that is not available
from the individual Items. For example, in the browser hierarchy in Figure 2 and
Figure 3, the OPC server groups Items by plant areas. For site-specific reasons, each
plant area may require a separate interface instance. With this example OPC server, the
only practical way to select Items from specific plant areas is to limit the exploration of
the browser hierarchy to the branches that represent the plant areas of interest.
The OPCHDAInt_APS Connector configuration includes a branch selection tree that
corresponds to the browser hierarchy of the OPC server. When the OPCHDAInt_APS
Connector explores the browser hierarchy to discover Items for point creation, the branch
selection tree controls which branches in the browser hierarchy are actually explored.
The branch selection tree is not a literal image of the browser hierarchy. The main
difference is that the branch selection tree permits patterns as branch nodes in addition to
literal branch names. In contrast to the actual browser hierarchy, a pattern in the branch
selection tree can represent one or more branches in the actual browser hierarchy. Thus,
the branch selection tree may have fewer branches than the actual browser hierarchy.
Also, the branch selection tree is not required to extend to the lowest levels in the
browser hierarchy, only as deeply as necessary to reach the branches to be explored in
their entirety.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
13
Introduction
Browser Node Type
In a browser for an OPC server, leaf nodes are always Items. Depending on the OPC
server, branch nodes may or may not be Items. The default behavior of the
OPCHDAInt_APS Connector considers all leaf and branch nodes that the browser
identifies as Items as candidates for creating new PI points. The OPCHDAInt_APS
Connector provides options to consider only leaf nodes or only branch nodes that are
Items as candidates for creating new PI points.
The option to consider only leaf nodes effectively excludes any branch nodes that are
identified as Items. This option is applicable in two situations. First, a few OPC servers
identify branches as Items (by returning an ItemID) but subsequently return errors when
the ItemID is accessed. For an OPC server with this behavior, the leaf-only option
prevents the OPCHDAInt_APS Connector from processing the branch Items, which
prevents error messages from attempting to read attributes for an invalid ItemID.
The second situation for using the leaf-only option is when an OPC server identifies its
branches as Items and also has a leaf node for the same Item under the branch. The
leaf-only option eliminates duplicate processing of the branch when additional leaf nodes
under the branches need to be considered for point creation.
The option to consider only branch nodes effectively eliminates processing of all leaf
nodes. This option is useful for OPC servers that organize their browser hierarchy such
that the leaf nodes are attributes of the Item represented by the parent branch. For
example, an OPC server of this type may have a branch that is an Item for a process
variable like a voltage reading. The leaves of the branch may contain description,
engineering units, low limit, etc.
Tag Selection
The OPCHDAInt_APS Connector supports the general PI APS Tag Selection feature.
The Tag Selection feature accepts a configurable list of condition expressions. The
condition expressions can compare Item attributes to fixed values (less than, less than or
equal, etc.) or match a string-valued Item attribute (such as the ItemID) with a wildcard
pattern. As Items are discovered while exploring the browser hierarchy, the condition
expressions are evaluated for each Item. One of the condition expressions must be true
for the Item to be a candidate for creating a new PI point.
Assignment of Actual OPC Attributes to Generic Attributes
The OPC HDA Standard provides for Items to have attributes and recommends a basic
set of attributes. Since the OPC HDA Standard allows an OPC server to implement any
subset of the recommended attributes (including none of them) and to add
vendor-specific attributes, a general-purpose OPC client like the OPCHDAInt_APS
Connector must be able to adapt to the attribute set provided by the OPC server with
which it is being used. To satisfy this requirement, the OPCHDAInt_APS Connector
supports a generic (vendor-independent) set of attributes that act as placeholders for
actual OPC attributes. Generic attributes are defined for almost the entire set of PI
attributes for the Classic point class and configuration settings select the actual OPC
attribute(s) in the specific OPC server that are assigned to each generic attribute.
Additional discussion of this feature is in the “Creatable and Synchronizable Attributes”
and “OPC Attributes Tab” sections.
14
The generic attributes are the basis for the Tag Selection, Tag Naming, and Attribute
Formulas features, which are discussed in more detail in later sections of this document.
All of these features are based on user-specified condition expressions, which are written
in terms of the generic attributes.
The Tag Naming and Attribute Formulas features evaluate user-specified formulas for
constructing replacement tag names or attribute values, respectively. Like condition
expressions, formulas also are written in terms of the generic attributes. Most of the
defined generic attributes can be used as “variables” in condition expressions and
formulas.
An OPC server is not likely to provide actual OPC attributes that are suitable for all of
the generic attributes. The Attribute Formulas feature can be used to generate values for
generic attributes not provided by the OPC server or conditionally override actual OPC
server attribute values.
The OPC HDA Standard recommends a basic set of attributes for the Items in OPC
server implementations. The OPCHDAInt_APS Connector provides default assignments
for the attributes recommended in the OPC HDA Standard, which are listed in the
following table. Where more than one actual OPC attribute is listed for a generic
attribute, the actual OPC attributes are listed in order of precedence.
Generic Attribute
Default Actual OPC Attribute
OPCItemID
(Note 1)
OPCParentBranch
(Note 2)
OPCLeaf
(Note 2)
OPCDatatype
OPCHDA_DATA_TYPE
OPCPIPointtype
(Note 3)
OPCPITagname
(Note 4)
OPCDescription
OPCHDA_DESCRIPTION
OPCExDesc
OPCEngUnits
OPCHDA_ENG_UNITS
OPCMaxValue
OPCHDA_NORMAL_MAXIMUM
OPCHDA_HIGH_ENTRY_LIMIT
OPCMinValue
OPCHDA_NORMAL_MINIMUM
OPCHDA_LOW_ENTRY_LIMIT
OPCZero
(Note 5)
OPCSpan
(Note 5)
OPCStepped
OPCHDA_STEPPED
OPCDatatype
OPCHDA_DATA_TYPE
OPCDigitalSetName
OPCDigitalStates
OPCCompMin
OPCHDA_MIN_TIME_INT
OPCCompMax
OPCHDA_MAX_TIME_INT
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
15
Introduction
Generic Attribute
Default Actual OPC Attribute
OPCCompDev
OPCCompDevPercent
OPCExcMin
OPCExcMax
OPCExcDev
(Note 6)
OPCExcDevPercent
(Note 6)
OPCPollInterval
OPCArchiving
OPCHDA_ARCHIVING
OPCTypicalValue
OPCLocation2
OPCLocation3
OPCLocation4
OPCLocation5
OPCTotalCode
OPCSquareRoot
OPCConvers
OPCUserInt1
OPCUserInt2
Note 1:
The OPCItemID generic attribute contains the ItemID of the Item, which is the unique
string that identifies the Item in the OPC server. This generic attribute cannot be changed
by an attribute formula.
Note 2:
These generic attributes are only available in the Tag Selection and Tag Naming features
(not available in the Attribute Formulas feature). The OPCLeaf generic attribute is the
node name from the browser hierarchy for an Item (usually a leaf but possibly a branch
node). The OPCParentBranch generic attribute is the node name of the branch that
contains the Item. For the CV Item in Figure 3, the OPCLeaf generic attribute is set to CV
and the OPCParentBranch generic attribute is set to ABNORM_ACTIVE. The
OPCItemID generic attribute is set to the ItemID
BFO_TEST/AI1/ABNORM_ACTIVE.CV.
In the OPC server in Figure 3, the leaves in the browser hierarchy are related Items for a
higher-level object in the control system. In this OPC server, leaf items are available for
current value (CV) and three forms of status (ST, CST, and AWST). All leaf nodes in this
OPC server have one of these four names. With OPC servers like this one, the leaf node
names are not useful for filtering or other purposes. The OPCParentBranch or
OPCItemID generic attributes may be more appropriate for filtering purposes.
Recommendation: Use HDATool to familiarize yourself with the browser hierarchy on
your specific OPC server.
16
Note 3:
While exploring the browser hierarchy for new Items, the default value for the
OPCPIPointtype generic attribute is obtained from the configuration settings for the
native OPC data type. When synchronizing an existing PI point, the default value for the
OPCPIPointtype generic attribute is the actual PI point type for the point. The default
OPCPIPointtype generic attribute value is the integer code for the PI point type, not a
point type name. Therefore, when using the OPCPIPointtype generic attribute in a
condition expression, it must be compared with an integer point type code. The table in
the “OPCPIPointtype in Conditions and Formulas” section lists the PI point types by
name and integer code.
Note 4:
For an Item that is a candidate available point, the ItemID is the default value for the
OPCPITagname generic attribute. If a tag naming formula is evaluated, the result is
assigned to the OPCPITagname generic attribute. For attribute formulas, conditions that
contain the OPCPITagname generic attribute use the value after tag naming, and an
attribute formula can change the OPCPITagname generic attribute. The value of the
OPCPITagname generic attribute after attribute formulas is the tag name used for point
creation.
For an existing PI point, the PI tag name is the default value for the OPCPITagname
generic attribute. For attribute formulas, conditions that contain the OPCPITagname
generic attribute use the existing tag name. An attribute formula can change the
OPCPITagname generic attribute but will have no effect. That is, an existing PI point
will not be renamed.
Note 5:
The OPC HDA Standard defines two pairs of attributes that contain lower and upper
limits for an Item. The lower limit from either pair could be used as the source for the PI
zero attribute, but the OPC HDA Standard does not define any attribute that corresponds
to the PI span attribute. Since an OPC server is more likely to provide lower and upper
limit attributes than a span attribute, the OPCHDAInt_APS Connector contains logic to
derive the OPCZero and OPCSpan generic attributes from upper and lower limit
attributes, as described in the “Creatable and Synchronizable Attributes” section.
Note 6:
The OPC HDA Standard recommends the OPCHDA_EXCEPTION_DEV attribute whose
value can be an absolute value or a percentage of the Item’s span. The OPC HDA
Standard also recommends the OPCHDA_EXCEPTION_DEV_TYPE attribute as an indicator
of how to interpret the OPCHDA_EXCEPTION_DEV attribute. However, the OPC HDA
Standard does not specify the encoding of the OPCHDA_EXCEPTION_DEV_TYPE attribute.
Therefore, the OPCHDAInt_APS Connector cannot determine whether to use the
OPCHDA_EXCEPTION_DEV attribute as the source for the OPCExcDev or
OPCExcDevPercent generic attribute. If your OPC server provides an
OPCHDA_EXCEPTION_DEV attribute, you can configure it to be the actual OPC attribute
assigned to the appropriate generic attribute.
The OPCHDAInt_APS Connector contains a variable to hold the value for each generic
attribute. Since the type of an actual OPC attribute depends on the OPC server, the
generic attribute variables are designed to accept values of any type that an OPC server
can return. For example, the numeric attributes may be primarily integers in one OPC
server and floating-point numbers in another OPC server.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
17
Introduction
The generic attribute variables can also be set to a special state that indicates no value is
available and are initialized to the no-value state when the OPCHDAInt_APS Connector
begins to retrieve attributes for an ItemID.
Unless otherwise noted in the above table, a blank entry in the “Default Actual OPC
Attribute” column indicates that the default configuration does not assign an actual OPC
attribute to the corresponding generic attribute. That is, these generic attributes will be
treated by the PI APS Sync Engine as if the OPC server provided no value. You must
explicitly assign an actual OPC attribute to these generic attributes (or use an attribute
formula) for them to provide values to the PI APS Sync Engine.
18
Quality Points
An Item “value” is actually composed of three quantities: the actual value, a quality
value, and a timestamp. The PI OPC HDA Interface allows a PI point to obtain its value
from either the actual value or the quality value. A PI point whose source is the OPC
quality value is called a quality point. For the PI OPC HDA Interface, the location2
attribute selects whether a particular PI point is a normal data point (location2 set to 0) or
a quality point (location2 set to 1).
The OPCHDAInt_APS Connector synchronizes existing PI points (both data and quality
points) and provides an option to create quality points. If the option to create quality
points is enabled in the configuration, the OPCHDAInt_APS Connector expects each
ItemID in the OPC server to have both a data and quality point in PI. If either the data or
quality point does not exist in PI, the OPCHDAInt_APS Connector will treat the missing
point as a candidate point for creation. The Tag Selection feature allows the
OPCLocation2 generic attribute to be used in condition expressions, which can be used
to make independent filtering decisions for data and quality points.
The quality value for an Item is a 32-bit integer. Quality points must have a PI point type
suitable for this range of values; the OPCHDAInt_APS Connector default point type for
quality points is int32. Note that use of a raw OPC quality value as the source for a PI
digital point is not feasible due to the range of possible values (the digital set would have
232 entries).
Some actual OPC attributes are specific to the data value and, therefore, are not
meaningful or appropriate for the quality value. For example, an engineering units
attribute describes the data value, but the quality value is unitless. Therefore, the
OPCHDAInt_APS Connector will derive the following generic attributes for quality
points from the actual Item attributes or use a default value:

OPCLocation2 is set to 1 (quality point).

If OPCDescription is not an empty string, “ Quality” is appended.
If OPCDescription is an empty string, it is set to “ItemID Quality”.

If OPCExDesc is not an empty string, “ Quality” is appended.

OPCEngUnits is set to empty (as if the OPC server provided no value).

OPCZero is set to 0.

OPCSpan is set to 256.

OPCCompDev is set to 1 and OPCCompDevPercent is set to 100 divided by
OPCSpan.

OPCExcDev is set to 1 and OPCExcDevPercent is set to 100 divided by
OPCSpan.
The rationale for these default values for zero, span, compression deviation, and
exception deviation generic attributes is to ensure that all changes in the quality value are
historicized. The span value of 256 was chosen because most of the quality information is
in the low-order byte (eight bits) of the quality value. The PI zero and span attributes do
not limit the range of values that can be stored in the point, so the high-order bytes will
be historicized. If the high-order bytes are non-zero, however, the default scaling in
ProcessBook will require adjustment to display a wider range of quality values.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
19
Introduction
Limitations
Any PI points that the PI APS Sync Engine or Configuration Utility creates from
information provided by the OPCHDAInt_APS Connector will have the ItemID in the
InstrumentTag attribute. If the OPC server has ItemIDs that are longer than
32 characters and either the PI Server version is lower than 3.4.370.x or the PI API
version installed on the interface node is lower than 1.6.2, the PI OPC HDA Interface
must be started with the /pisdk=1 parameter to enable the PI SDK.
No output points are created by default. Using attribute formulas, the OPCHDAInt_APS
Connector can be configured to set the OPCLocation3 generic attribute to create output
points. Automatically creating output points is not recommended.
The objective of the OPCHDAInt_APS Connector is to work with any compliant OPC
server. Otherwise, specific PI APS connectors would have to be developed for each
different OPC server. The OPC HDA Standard defines an “attribute” as “An additional
qualifier that a particular item may have associated with it.” The OPCHDAInt_APS
Connector uses the OPC HDA Standard attribute functions to locate attributes that can be
used (directly or indirectly) as sources for PI point attributes.
Some OPC servers have chosen to not implement OPC attributes that are usable for PI
point attributes, but these OPC servers may have Items that contain values corresponding
to PI point attribute values. Because the OPC HDA Standard does not specify the syntax
for ItemIDs (that is, Item names) or browser hierarchy structure, an OPC client has no
way to determine the relationships between Items, if any, that exist in a “generic” OPC
server. Therefore, the OPCHDAInt_APS Connector can only obtain values for PI
attribute values from actual OPC attribute values.
Note: The OPCHDAInt_APS Connector cannot obtain attribute values for one Item from
another Item.
20
Principles of Operation
This section explains how the OPCHDAInt_APS Connector and PI APS Sync Engine
work together to synchronize PI points for an instance of the PI OPCHDAInt Interface.
The PI APS Sync Engine runs as a Windows Service. It appears in the Windows Task
Manager on the Processes tab as PIAPSEngine.exe. The PI APS Sync Engine
schedules synchronization scans and implements the synchronization tasks common to all
PI APS Connectors. The PI APS Sync Engine makes all PI SDK calls to obtain or change
PI point information. By itself, the PI APS Sync Engine is unable to communicate with
any data source.
The OPCHDAInt_APS Connector implements a specific set of functions required by the
PI APS Sync Engine. It is an in-process COM object that is implemented in a dynamic
link library (DLL) named OPCHDAInt_APS.dll. This object is registered during
installation of the OPCHDAInt_APS Connector. The PI APS Sync Engine dynamically
loads the OPCHDAInt_APS Connector. That is, the PI APS Connector “plugs into” the
PI APS Sync Engine.
During a synchronization scan for the PI OPCHDAInt Interface, the PI APS Sync Engine
calls functions in the OPCHDAInt_APS Connector that actually obtain point definitions
by calling the OPC HDA programming interface. The OPCHDAInt_APS Connector
returns point information from the data source to the PI APS Sync Engine. The
OPCHDAInt_APS Connector does not access or change the PI Point database.
The OPCHDAInt_APS Connector has two primary functions that are called by the
PI APS Sync Engine:

Acquire a list of available points in the data source, and

Obtain current data source attributes for existing interface points.
The PI APS Sync Engine uses information returned by the OPCHDAInt_APS Connector
to create new PI points for the PI OPCHDAInt Interface instance, synchronize existing
interface instance points in the PI Server, and remove PI points when corresponding data
source points are deleted.
Point Class
This PI APS Connector returns “classic” when the PI APS Sync Engine asks for the point
class to use when creating new PI points. PI APS will create only classic points for an
interface instance registered with this PI APS Connector. Existing classic points can be
edited or deleted.
If the interface instance has existing points in a point class other than classic and the
point class contains all of the attributes listed in the table in the “Supported PI Point
Attributes” section, the PI APS Sync Engine can obtain updated attributes and detect
deleted points for the non-classic points. However, if an existing point belongs to a class
that does not contain all attributes in the table, the point cannot be synchronized by the
PI APS Sync Engine because errors result when the PI APS Sync Engine requests the
current attribute values from PI for attributes that are not defined in the class. Therefore,
use the PI APS Configuration utility to disable synchronization for any point in a class
that does not contain all of the attributes supported by this PI APS Connector.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
21
Principles of Operation
Point Source and Instance ID
PI points are associated with a PI OPCHDAInt Interface instance by the PointSource
and Location1 attributes. PI APS obtains the PointSource and instance ID values for
an interface instance from its PI ICU configuration. PI APS uses these attributes and the
values from PI ICU to identify the existing points for an interface instance. If PI APS
creates a point for the interface instance, the values from PI ICU will be assigned to the
PointSource and Location1 attributes of the new points.
Key Attributes
The OPCHDAInt_APS Connector uses the following attributes to map PI points to data
source points:

InstrumentTag

ExDesc
The OPCHDAInt_APS Connector uses the same logic as the PI OPCHDAInt Interface
for finding the ItemID of the OPC point associated with a PI point. If the InstrumentTag
attribute is not an empty string, it must contain the ItemID. If the InstrumentTag
attribute is an empty string, the ItemID must be encoded in the ExDesc attribute. When
the ItemID is in the ExDesc attribute, the keyword instr= identifies the start of the
ItemID substring and the ItemID extends to the first comma or end of string. This is an
oversimplification of the syntax for encoding ItemID in the ExDesc attribute; see the
OPC HDA Interface to the PI System user manual for details.
Creatable and Synchronizable Attributes
The OPCHDAInt_APS Connector supports the PI point attributes listed in the table in the
“Supported PI Point Attributes” section. This section explains the process that transforms
actual OPC attributes into PI attributes.
For either point creation or synchronization of an existing point, the OPCHDAInt_APS
Connector starts with the ItemID for an Item. The ItemID is obtained from the browser
while exploring for new points or from the key attributes of an existing PI point.
The OPCHDAInt_APS Connector contains a variable to hold the value for each generic
attribute in the table in the “Assignment of Actual OPC Attributes to Generic Attributes”
section. Each generic attribute variable can be set to either a numeric value, a string
value, or a no-value state.
1. The generic attributes are initialized to the no-value state.
2. The OPCHDAInt_APS Connector calls the OPC server to obtain the actual OPC
attributes for the ItemID. All of the actual OPC attributes that are configured as
sources for generic attributes are requested in a single OPC call.
3. The actual attributes from the OPC server are assigned to the generic attributes
according to the configuration settings. Some generic attributes may not be assigned
and will retain the no-value state.
4. If the point is a quality point, the generic attributes that are not meaningful or
appropriate for a quality point are replaced as described in the “Quality Points”
section.
22
5. For candidate available points, tag selection conditions are evaluated. If the candidate
available point does not satisfy the selection condition, the point is abandoned (the
remaining steps in this list are unnecessary).
6. For candidate available points, tag naming rules are evaluated.
7. If any attribute formulas are configured, the conditions and formulas are evaluated.
Formula results are stored in temporary variables.
8. The results of any attribute formulas that were evaluated are assigned to the
applicable generic attributes.
9. The generic attributes are validated:
If OPCCompDev or OPCExcDev is less than zero, set it to zero.
If OPCCompDevPercent or OPCExcDevPercent is less than zero, set it to zero.
If OPCCompDevPercent or OPCExcDevPercent is greater than 100, set it to 100.
10. If OPCCompDev has no value but OPCExcDev does, set OPCCompDev to
2*OPCExcDev.
11. If OPCExcDev has no value but OPCCompDev does, set OPCExcDev to
½*OPCCompDev.
12. If OPCZero and OPCSpan have no values but OPCMinValue and OPCMaxValue
do and OPCMinValue is less than OPCMaxValue, set OPCZero to
OPCMinValue and set OPCSpan to the difference between OPCMaxValue and
OPCMinValue.
13. Assign generic attributes to corresponding PI attributes.
Available and Hidden Points
The PI APS Sync Engine initially categorizes data source points that the PI APS
Connector discovers without a corresponding point in the target PI Server as Available
Points. Using the PI APS Configuration Utility, available points can be selectively
changed into Hidden Points and hidden points can be changed back into available points.
Both available and hidden points correspond to data source points with no associated PI
points. The PI APS Sync Engine handles the two categories differently: available points
are available for creation in the PI Server, and hidden points are treated as if they do not
exist.
During each synchronization scan, the PI APS Sync Engine constructs a list containing
the key attributes of existing PI points and hidden points for the interface instance.
The PI APS Sync Engine passes the list of key attributes for existing and hidden points to
the OPCHDAInt_APS Connector in a call for available points.
The PI APS Connector explores the OPC HDA server for a list of its point definitions.
Using the key attributes, the OPCHDAInt_APS Connector matches the points in the list
of existing and hidden points from the PI APS Sync Engine with the points in the list
from the OPC HDA server. Points in the OPC HDA server that match a point in the list
of existing and hidden points are not available points.
Unmatched points in the OPC HDA server are returned to the PI APS Sync Engine as
available points for point creation.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
23
Principles of Operation
Exploring and Filtering the OPC Browser Hierarchy
The OPCHDAInt_APS Connector configuration includes a branch selection tree that
controls which branches in the browser hierarchy are explored. The branch selection tree
only applies to branch nodes, not leaf nodes. Any leaf nodes in an explored branch are
candidates for available points. Similarly, any leaf nodes in an unexplored branch are
ignored. Since the root branch is always explored, any leaf nodes in the root branch are
always candidate available points.
The OPCHDAInt_APS Connector explores the browser hierarchy by starting at the
topmost branch (or, root) of both the browser hierarchy and the branch selection tree.
If the option for selecting candidate Items by browser node type is configured for all
Items or only leaf Items, the OPCHDAInt_APS Connector calls the OPC server for a list
of all leaves in the branch being explored. Each leaf is then subjected to the processing
described in the “Item-level Selection” section below.
After processing the leaf nodes, the OPCHDAInt_APS Connector calls the OPC server
for a list of all sub-branch nodes. If the current branch selection node that corresponds to
the branch being explored has no child nodes, all sub-branches implicitly satisfy branch
selection criteria. Otherwise, each sub-branch node name is matched with the child
patterns of the current branch selection node. If a sub-branch does not satisfy the
selection criteria, the sub-branch is ignored. If a sub-branch satisfies the selection criteria,
the sub-branch itself is a candidate Item and the sub-branch is recursively explored.
If the option for selecting candidate Items by browser node type is configured for all
Items or only branch Items, the OPCHDAInt_APS Connector determines if the subbranch itself is also an OPC Item by calling the OPC server for the ItemID for the subbranch. If the OPC server returns an ItemID for the sub-branch (indicating that the subbranch is an Item), the sub-branch is subjected to the processing described in the “Itemlevel Selection” section below.
Finally, the OPCHDAInt_APS Connector recursively explores the sub-branch. That is,
the OPCHDAInt_APS Connector descends one level in both the browser hierarchy and
the branch selection tree: an OPC server call is made to descend into the sub-branch of
the browser hierarch, and the new position in the branch selection tree is the node that
matched the browser sub-branch. In this new context, the leaf and branch nodes are
processed as described above. Since the current position is changed in both the browser
hierarchy and the branch selection tree, a different set of branch selection patterns apply
to the branch nodes in the new current browser hierarchy position. After processing the
leaf and branch nodes, the OPCHDAInt_APS Connector ascends to the parent branch in
the browser hierarchy and to the parent node in the branch selection tree.
Item-level Selection
When the exploration process discovers a candidate Item, the OPCHDAInt_APS
Connector searches the list of existing and hidden points (from the PI APS Sync Engine)
for a data point (location2 attribute is 0) with the same ItemID as the candidate Item. If a
data point is not found, the OPCHDAInt_APS Connector sets four generic attributes:
OPCItemID, OPCLeaf, OPCParentBranch, and OPCLocation2. The OPCItemID
generic attribute is set to the ItemID for the Item. The OPCLeaf generic attribute is set to
the browser node name of the leaf or branch. The OPCParentBranch generic attribute is
set to the browser node name of the branch that contains the Item. The OPCLocation2
generic attribute is set to 0 (data point). The other generic attributes contain either no
value or a value from an actual OPC attribute. The tag selection conditions are evaluated.
24
If the Item satisfies one of the tag selection conditions, the Item is reported as an
available data point to create in PI.
For purposes of data point creation, the OPCHDAInt_APS Connector does not
differentiate between input and output data points in the list of existing and hidden points.
If the list contains either an input or output point (or both) with the same ItemID as the
candidate Item, no data point will be created for the Item. If a data point is available for
creation, the default configuration of the OPCHDAInt_APS Connector will set
OPCLocation3 generic attribute to 0, making the available data point an input point.
If the option to create quality points is selected, the OPCHDAInt_APS Connector
searches the list of existing and hidden points (from the PI APS Sync Engine) for a
quality point (location2 attribute is 1) with the same ItemID as the candidate Item. If a
quality point is not found, the OPCHDAInt_APS Connector sets the OPCItemID,
OPCLeaf, and OPCParentBranch generic attributes to the ItemID, browser node name
for the Item, and browser node name of the parent branch, respectively. The
OPCLocation2 generic attribute is set to 1 (quality point) and the remaining generic
attributes are set as described in the “Quality Points” section. The tag selection conditions
are evaluated. If the Item satisfies one of the tag selection conditions, the Item is reported
as an available quality point to create in PI.
Tag Naming Conventions
The following naming conventions are used when available points are found.
The table in the “Assignment of Actual OPC Attributes to Generic Attributes” section
lists the generic attributes supported by the OPCHDAInt_APS Connector. The generic
attributes are the data source attributes that can be used in the tag naming rules
(conditions and formulas) described in this section.
The OPCHDAInt_APS Connector constructs tag names according to user-configurable
rules. Each tag naming rule consists of a condition and a formula for constructing a tag
name. Data source attributes are used as variables in both conditions and formulas. If the
attributes for a point satisfy the condition in a rule, the PI APS Connector uses the
formula in the same rule to construct a tag name for the point. Configure the tag naming
rules on the Tag Naming tab in the User-set Defaults dialog box in the PI APS
Configuration Utility. For details on configuring tag naming rules, see the “Tag Naming
Tab” section in the PI AutoPointSync for Interfaces and PI COM Connectors user
manual. The PI APS Configuration Utility User-set Defaults dialog box and PI
AutoPointSync for Interfaces and PI COM Connectors user manual refer to the data
source attributes as “DCS attributes.”
If no Tag Naming rules are configured or the point does not satisfy the condition in any
rule, the OPC ItemID is the default tag name.
Point Type
Items in an OPC server can have any of the types supported by a Microsoft COM
VARIANT. The OPCHDAInt_APS Connector provides a configurable choice of the PI
point type to use for each VARIANT type and a built-in set of default settings. When an
Item is found that has no corresponding PI data point, the PI point type configured for the
VARIANT type of the Item is the default PI point type that is assigned to the
OPCPIPointtype generic attribute. For quality points, the default PI point type assigned
to the OPCPIPointtype generic attribute is int32. The Attribute Formula feature can
change the OPCPIPointtype attribute of points that match user-specified conditions.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
25
Principles of Operation
Updated Attributes
During each synchronization scan, the PI APS Sync Engine constructs a list containing
the key attributes of existing PI points for the interface instance that are enabled for
synchronization.
The PI APS Sync Engine passes the list of synchronizable existing points to the
OPCHDAInt_APS Connector in a call for updated attributes.
For each synchronizable existing point, the OPCHDAInt_APS Connector uses the key
attributes to query the OPC server for the current synchronizable attribute values of the
Item. The PI APS Connector assembles the results for each point into a list to return to
the PI APS Sync Engine.
If an existing point successfully maps to a data source point, the PI APS Connector adds
the current attribute values for the data source point to the list of information for return to
the PI APS Sync Engine.
When processing an existing data point (location2 attribute contains 0), the
OPCHDAInt_APS Connector does not consider whether the point is for input or output
(location3 attribute value is ignored). Unless there are attribute formulas that override
generic attributes based on the OPCLocation3 generic attribute value, the same current
generic attributes for the Item are used to synchronize either an input or output data point.
When processing an existing quality point (location2 attribute contains 1), the
OPCHDAInt_APS Connector overrides the generic attributes (like OPCEngUnits) that
are not appropriate for a quality point. The built-in attribute overrides for quality points
are discussed in the “Quality Points” section and are applied before evaluating attribute
formulas.
If an existing point does not map to a valid data source point, the PI APS Connector adds
an indication that the existing PI point has no point in the data source to the list for return
to the PI APS Sync Engine.
After the PI APS Connector processes all of the synchronizable existing PI points, the list
of results is returned to the PI APS Sync Engine. The PI APS Sync Engine uses the
information in the list to generate a list of updates and a list of points to be deleted.
26
Installation, Upgrading, and Uninstallation
Instructions
Installation Instructions
PI APS must be installed on the same machine as the OPCHDAInt_APS Connector.
The OPCHDAInt_APS Connector setup program uses the services of the Microsoft
Windows Installer. Windows Installer is a standard part of Windows 2000, Windows XP,
and Windows 2003. To install, run the OPCHDAInt_APS_x.x.x.x.exe installation kit.
Note: This installation package installs only the OPCHDAInt_APS Connector, not the
OPCHDAInt Interface or PI APS.
Installation Checklist
1. Log on as a user with Administrative privileges.
2. Install PI AutoPointSync, if it is not already installed. (The PI APS installation kit
also contains the PI SDK, PI API, and PI ICU. If necessary, the PI APS installation
kit will install or upgrade these components.)
Note: The PI APS installation kit upgrades the PI SDK, PI API, or PI ICU if the
PI APS installation kit contains a newer version than the version already installed on
the computer.
3. Run OPCHDAInt_APS_x.x.x.x.exe to install the OPCHDAInt_APS Connector.
Upgrading Instructions
For information on the current version of the OPCHDAInt_APS Connector, see the
following web site:
http://techsupport.osisoft.com/support_aps.aspx?sub=1
The same OPCHDAInt_APS_x.x.x.x.exe installation kit is used for either an initial
installation or upgrading an existing installation of the OPCHDAInt_APS Connector.
Upgrading Checklist
1. Log on as a user with Administrative privileges, preferably the same user who
originally installed the OPCHDAInt_APS Connector.
2. If the PI APS Configuration Utility is running, exit from the program.
3. Stop the PI APS Sync Engine. The most common ways of stopping the PI APS Sync
Engine are from the Services applet or from a command prompt. For convenience,
the Services applet or command window can be left open and used later to restart the
PI APS Sync Engine.
To open the Services applet, click Start ► Settings ► Control
Panel ►Administrative Tools ► Services. In the right pane, scroll to PI APS
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
27
Installation, Upgrading, and Uninstallation Instructions
Synchronization Engine and click on that item to select it. Then, either click ■ on
the toolbar or Stop on the Actions menu.
To stop the Sync Engine from a command prompt, enter:
net stop piapsengine
4. Run the OPCHDAInt_APS_x.x.x.x.exe installation kit.
5. Restart the PI APS Sync Engine.
If using the Services applet, either click ► on the toolbar or Start on the Actions
menu.
If using a command window, enter:
net start piapsengine
Uninstallation Instructions
To uninstall the OPCHDAInt_APS Connector:
1. Review the interface instances that are registered with PI APS. Unregister all
interface instances that are associated with the OPCHDAInt_APS Connector.
2. If the PI APS Configuration Utility is running, exit from the program.
3. Log on as a user with Administrative privileges, preferably the same user who
originally installed the OPCHDAInt_APS Connector.
4. Stop the PI APS Sync Engine. The most common ways of stopping the PI APS Sync
Engine are from the Services applet or from a command prompt. For convenience,
the Services applet or command window can be left open and used later to restart the
PI APS Sync Engine.
To open the Services applet, click Start ► Settings ► Control
Panel ►Administrative Tools ► Services. In the right pane, scroll to PI APS
Synchronization Engine and click on that item to select it. Then, either click ■ on
the toolbar or Stop on the Actions menu.
To stop the Sync Engine from a command prompt, enter:
net stop piapsengine
5. Click Start ► Settings ► Control Panel ► Add or Remove Programs to open the
Add or Remove Programs applet. The following program needs to be removed:

PI OPC HDA (OPCHDAInt) APS Connector
6. Restart the PI APS Sync Engine.
If using the Services applet, either click ► on the toolbar or Start on the Actions
menu.
If using a command window, enter:
net start piapsengine
28
Registering an Interface Instance with PI APS
PI AutoPointSync synchronizes the points for interface instances that are registered with
PI APS. When an interface has multiple instances, registering one instance with PI APS
synchronizes only the points for that specific instance. Each interface instance must be
registered with PI APS for its points to be automatically synchronized.
If you are not familiar with registering interface instances with PI APS, this section does
not provide the in-depth discussions of the configurable options that are essential for
successful configuration. Important concepts and detailed explanations of the
configurable options are presented in the PI AutoPointSync for Interfaces and PI COM
Connectors user manual, which you must read before proceeding with the steps in this
section. The “Connector-specific Configuration Control” section in this manual is also
prerequisite reading. The “Principles of Operation” section is strongly recommended.
Note: OSIsoft emphasizes the need to read both manuals before beginning to register
the first interface with PI APS.
If you are familiar with PI APS, the set of procedures in this section gives the main steps
for registering an interface instance. These procedures are presented in the order that you
must perform them.
1. Register the Interface
2. Configure the Settings
3. Enable Synchronization
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
29
Registering an Interface Instance with PI APS
Register the Interface
Only interface instances managed by the PI Interface Configuration Utility can be
registered with PI APS. If a new interface instance is being created or an existing
interface instance is not managed by PI ICU, run PI ICU and add the interface instance.
Refer to the PI Interface Configuration Utility User Manual and the OPC HDA Interface
to the PI System user manual for instructions.
Note: The default PI APS installation configures the PI APS Sync Engine service to log
on as the local system account. In two particular situations related to OPC, the local
system account may not be allowed to connect to the OPC server. In these cases, the
logon account for the PI APS Synchronization Engine service must be changed.
The local system account may not have adequate privileges to connect to the OPC server
in the following situations:

The OPC server is on a remote node. DCOM is used to connect to a remote OPC
server and the local system account of one computer is typically not permitted
DCOM access to remote computers.

The OPC server is local but has its own authentication requirements that do not
permit connections from the local system account.
If the local system account is not allowed to connect to the OPC server, change the logon
account for the PI APS Sync Engine service as described in step 6 below.
1. Run the PI APS Configuration and Management Utility and select Register New…
on the Interface menu.
30
The Configure Interface or COM Connector for PI-APS dialog box opens:
For details on using the Configure Interface or COM Connector dialog box, see
the “Configure an Interface or PI COM Connector Dialog” section in the PI
AutoPointSync for Interfaces and PI COM Connectors user manual.
2. Click the Select APS Connector arrow and select the OPCHDAInt_APS Connector
from the list:
3. Click the Select PI server host arrow and select the PI Server where points for the
interface instance either exist or will be created.
After making a selection in both boxes, the PI APS Configuration Utility loads the
Select an interface list with the interface instances that are not yet registered with
PI APS.
4. Click the Select an interface arrow and select a specific interface instance for
registration.
5. Click Add.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
31
Registering an Interface Instance with PI APS
6. If the OPC server is on a remote node or is a local OPC server that only allows access
by designated users, the PI APS Synchronization Engine service may need to be
reconfigured to log on as a user that is permitted to connect to the OPC server. To
change the logon account for the PI APS Synchronization Engine service, click
Start ► Settings ► Control Panel ► Administrative Tools ► Services to open
the Services applet. Scroll through the list of services in the right pane and locate the
PI APS Synchronization Engine service. Right-click on the PI APS
Synchronization Engine item and select Properties on the shortcut menu, which
opens the following dialog box.
If the Service status: line indicates that the service is “Started” (as shown), click the
Stop button.
32
Click the Log On tab to switch to the following options:
When PI APS is installed, the PI APS Synchronization Engine service is configured
to log on as the local system account. Click the This account: radio button. Enter the
account (user) name in the box and the account password in the Password: and
Confirm password: boxes. Click the OK button to put these changes into effect.
Restarting the PI APS Synchronization Engine service at this time is optional. The
Services applet is no longer needed and may be closed.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
33
Registering an Interface Instance with PI APS
Configure the Settings
Configure the PI APS options for the new interface instance using the commands on the
Settings menu in the PI APS Configuration Utility:
Review the options on the dialog boxes that are opened by Rules…, Sync Schedule…,
User-set Defaults…, and Connector-specific… on the Settings menu. It is likely that
the default settings need to be changed for your specific requirements.
Note: OSIsoft emphasizes the necessity to configure these options before enabling a
new interface instance. In particular, the User-set Defaults establish the default per-point
synchronization settings that are assigned to existing points only once on the first
synchronization scan. Therefore, these settings must be configured for your specific
needs prior to the first synchronization scan.
The settings dialog boxes are briefly described in these sections:

Rules

Synchronization Schedule

User-set Defaults

Connector-specific Options
The options on the dialog boxes opened by Sync Settings… and Debug… do not have to
be reviewed or configured during initial registration.
34
Rules
On the Settings menu, click Rules:
The Rules dialog box opens:
The options in this dialog box determine how the PI APS Sync Engine handles available
points, attributes of existing points that disagree with current values in the data source,
and points that no longer map to valid points in the data source.
Note: OSIsoft emphasizes that you should initially choose to store the synchronization
results and carefully review for expected behavior before selecting any options to
automatically update the PI Point database.
The PI APS Sync Engine detects PI points that no longer map to valid points in the data
source while scanning for attributes that need to be edited. Therefore, if the Skip search
for edits option is selected, PI points that are candidates for deletion are not detected.
When the Skip search for edits option is selected, the options in the PI Points That No
Longer Exist on the DCS area have no effect and PI APS Sync Engine behaves like the
Do Nothing option is selected.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
35
Registering an Interface Instance with PI APS
Synchronization Schedule
On the Settings menu, click Sync Schedule…:
The Synchronization Schedule dialog box opens:
The options in the Synchronization Schedule area choose between automatic
synchronization scans at periodic intervals or manual synchronization scans started by
clicking Sync Now on the PI APS Configuration Utility toolbar.
Note: If you select Synchronize automatically, the first synchronization starts
immediately when the interface is enabled.
The options in the Synchronization Trigger area are unavailable because they are under
development.
36
User-set Defaults
On the Settings menu, click User-set Defaults…:
For details on using the User-set Defaults dialog box, see the “User-set Defaults Dialog”
section in the PI AutoPointSync for Interfaces and PI COM Connectors user manual. The
User-set Defaults dialog box contains tabs that switch between four sets of options.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
37
Registering an Interface Instance with PI APS
Security & Archive Settings
On the User-set Defaults dialog box, click the Security & Archive Settings tab:
The settings on this tab provide default values for PI attributes that have no
corresponding attributes in most data sources. When the PI APS Sync Engine processes
an available point, the attribute default values from this tab are merged with the attributes
from the PI APS Connector. If the PI APS Connector provides a value from the data
source for any of these attributes, the value from the data source is used.
Depending on connector-specific settings, the OPCHDAInt_APS Connector can provide
none, one, or both of the CompDev and CompDevPercent attributes. If the
OPCHDAInt_APS Connector returns one compression deviation attribute to the PI APS
Sync Engine and the Compdev configuration on this dialog box selects the other, both
will be sent to the PI Server and the CompDevPercent attribute will have precedence. To
prevent the Compdev setting on this dialog box from overriding the compression
deviation attribute from the OPCHDAInt_APS Connector, select the Compdev option
that corresponds to the compression deviation attribute from the OPCHDAInt_APS
Connector.
The same issues and recommendations apply to the Excdev configuration on this dialog
box.
38
Initial Sync Masks
On the User-set Defaults dialog box, click the Initial Sync Masks tab:
When the PI APS Sync Engine encounters an existing point that does not have per-point
synchronization settings for the first time, the PI APS Sync Engine assigns the default
settings in the Existing PI Points area to the point. The settings in this area are only used
in two situations:

On the first synchronization scan for an interface that has existing points when
registered with PI APS.

When points are added to an interface by tools other than PI APS.
After synchronization settings are assigned to an existing point, changes made to the
settings in the Existing PI Points area will not affect the point during subsequent
synchronization scans.
The PI APS Sync Engine assigns the per-point synchronization settings in the
Available Points area to PI points that it creates automatically or the PI APS
Configuration Utility assigns these settings to PI points that it creates under user control.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
39
Registering an Interface Instance with PI APS
Both areas contain a list of the synchronizable attributes supported by the PI APS
Connector and two options under Tag is sync’d by APS. The Tag is sync’d by APS:
options select the master synchronization setting assigned to a point. When an interface is
registered, the initial Tag is sync’d by APS: selections default to No. These defaults
were chosen to ensure that the PI APS Sync Engine does not synchronize any points until
explicitly enabled. The master synchronization setting for a point must be Yes for the
PI APS Sync Engine to synchronize any attributes.
Note: The Tag is sync’d by APS options determine the master synchronization setting
for a point. The default setting is No, which prevents the PI APS Sync Engine from
synchronizing the point.
The check boxes in the lists select the individual synchronization setting for each
attribute. The initial settings for the individual attribute synchronization options are
obtained from the PI APS Connecter. The settings for individual attributes can be toggled
by clicking the check boxes in the list.
40
Tag Naming
On the User-set Defaults dialog box, click the Tag Naming tab:
Use the Tag Naming tab to configure tag naming rules for available points. Each tag
naming rule has a condition part and a tag formula part. Data source attributes are the
variables in both conditions and formulas. If the attributes for a data source point satisfy
one of the conditions, the tag formula associated with the condition is used to construct
the tag name for the available point. The tag naming rules are processed in the order
shown in the list. The tag name is constructed from the tag formula associated with the
first condition that is true.
The OPCHDAInt_APS Connector assigns the ItemID as the initial tag name before
evaluating the tag naming rules. Therefore, if no condition is satisfied, the ItemID will be
the tag name for the available point.
The “Assignment of Actual OPC Attributes to Generic Attributes” section of this manual
contains a table that lists the generic attributes supported by this PI APS Connector. All
of the generic attributes are allowed in condition expressions and tag formulas.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
41
Registering an Interface Instance with PI APS
Tag Selection
On the User-set Defaults dialog box, click the Tag Selection tab:
Use the Tag Selection tab to configure conditions that select a subset of new data source
points for available points. If the Use All Tags box is selected, the Tag Selection feature
is turned off and all data source points are candidate available points.
Clear the Use All Tags check box to enable tag selection. Tag selection is based on a list
of condition expressions that use data source attributes as variables. Select the
Use these tags option to use only points that match any condition in the list. Select the
Do not use these tags option to exclude points that match any condition in the list.
The “Assignment of Actual OPC Attributes to Generic Attributes” section of this manual
contains a table that lists the generic attributes supported by this PI APS Connector. All
of the generic attributes are allowed in condition expressions and tag formulas.
42
Connector-specific Options
The OPCHDAInt_APS connector has additional configuration options. On the Settings
menu, click Connector-specific…:
The PI-APS Connector Control dialog box opens:
The “Connector-specific Configuration Control” section in this document provides a
detailed discussion of the options on this dialog.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
43
Registering an Interface Instance with PI APS
Enable Synchronization
1. The PI APS Sync Engine is installed in disabled mode and must be enabled before
any interface instances can be synchronized. Click the Tools menu. If the
Enable Sync Engine command has a check mark next to it as shown in the following
screen image, then the PI APS Sync Engine is already enabled and no action is
required. Otherwise, click Enable Sync Engine to enable the PI APS Sync Engine.
2. When an interface instance is registered with PI APS, the interface instance is in
disabled mode and must be enabled before it can be synchronized.
Note: If an interface instance is configured for automatic scheduled synchronization,
the first synchronization scan starts immediately when the PI APS Connector is
enabled. Confirm that Rules for point creation/edit/delete, Sync Schedule, and
User-set Defaults are appropriate for your needs before enabling the Connector.
Click the Tools menu. If no check mark appears by the Enable Connector command
as shown in the following screen image, click Enable Connector to enable
synchronization for the interface instance.
44
Connector-specific Configuration Control
The OPCHDAInt_APS Connector includes a connector-specific configuration control.
This control configures options that affect operation of the OPCHDAInt_APS Connector.
Access the configuration control from the PI APS Configuration Utility. On the PI APS
Configuration Utility window, select the interface instance to configure. On the Settings
menu, click the Connector-specific… command to open a dialog box that contains the
connector-specific control.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
45
Connector-specific Configuration Control
The PI-APS Connector Control dialog box opens:
The OPC server connection string is shown at the top of this dialog box. When the
OPCHDAInt_APS Connector configuration control opens, it connects to the OPC server.
If the connection succeeds, the vendor information and version of the OPC server is
displayed above the tabs and the attributes supported by the OPC server are loaded into
the OPC Server’s Actual Attributes: list.
Opening the connector-specific control for OPCHDAInt_APS provides a basic
connection check for the OPC server. However, communication with the OPC server uses
COM/DCOM and, therefore, is subject to COM/DCOM security rules. Since the PI APS
Configuration Utility is running under the credentials of the logon user, the success of the
connection made by the connector-specific control only verifies that the logon user has
the necessary privileges to connect. Connection to the OPC server for synchronization
occurs in the PI APS Sync Engine. The default installation of PI APS configures the
PI APS Sync Engine service to log on as the local system user. Therefore, a successful
connection by the connector-specific control does not indicate that the OPCHDAInt_APS
Connector will be able to connect when called by the PI APS Sync Engine unless the
46
PI APS Sync Engine service has been reconfigured to log on as a user that can run the
PI APS Configuration Utility and successfully open the connector-specific control.
OPC Attributes Tab
The OPC Attributes tab configures the default PI point type to use for each Item type
and the assignment of actual OPC attributes to generic attributes.
Default OPC Data Type to PI PointType conversion
The Default OPC Data Type to PI PointType conversion list at the top of the OPC
Attributes tab configures the default PI point type to use for each OPC Data Type.
The cells in the PI Point Type column are editable. Click on a cell to expose the arrow
button and click on the arrow button to display the list of PI point types. Click a point
type in the list to change the default PI point type for the OPC Data Type on the same
row:
On a row with Digital PI point type, the cell in the Digital Set column is editable in a
similar manner. Click on a cell to expose the arrow button and click on the arrow button
to display the list of digital sets that are available in the PI Server. Click a digital set in
the list to change the default DigitalSet attribute for the OPC Data Type on the same row:
For cells in the Digital Set column, the list of choices is loaded from the PI Server when
this dialog box is opened. If a suitable digital set is not in the list, use PI SMT or another
PI administrative tool to create a new digital set. After creating the digital set, close and
re-open the connector-specific control to reload the list of digital sets.
OPC Attribute Sources
The DCS Attribute links to OPC Attributes: tree contains top-level nodes for each
generic attribute supported by the OPCHDAInt_APS Connector. The children of the
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
47
Connector-specific Configuration Control
generic attribute nodes are the actual OPC attributes that can be assigned to the parent
DCS attribute in order of precedence:
The attributes available in the OPC server are obtained from the OPC server and loaded
into the OPC Server’s Actual Attributes: list. To add an actual OPC attribute as the
source for a DCS (that is, generic) attribute, an item in the OPC Server’s Actual
Attributes: list can be dragged to a node in the DCS Attribute links to OPC
Attributes: tree. The new actual OPC attribute is added below the drop target node. The
order of the actual OPC attributes under a generic attribute is the precedence that the
OPCHDAInt_APS Connector uses to choose from multiple actual OPC attributes. In the
configuration shown above for OPCMaxValue, if the OPCHDA_NORMAL_MAXIMUM
attribute for an Item has a value, it is assigned to the OPCMaxValue generic attribute. If
and only if the OPCHDA_NORMAL_MAXIMUM attribute for an Item has no value, the
OPCHDA_HIGH_ENTRY_LIMIT attribute value is assigned. To change the position of an
actual OPC attribute in the precedence order, drag it to the node that it is to follow. Also,
a selected actual OPC attribute can be moved with the UP ARROW and DOWN
ARROW keys.
To add, re-order, or delete actual attribute child nodes, the DCS Attribute links to OPC
Attributes tree has a shortcut menu that opens in response to right-clicking on nodes in
the tree:
The choices on the shortcut menu depend on whether you right-click a generic attribute
node or actual OPC attribute node. For example, a Delete choice only is presented when
an actual OPC attribute node is selected. Before using any of the various “add” choices
48
on the shortcut menu, the specific actual OPC attribute to be added must be selected in
the OPC Server’s Actual Attribute list. Also, different forms of “add” choices depend
on context. For a generic attribute node, the choices are Add First and Add Last. For an
actual OPC attribute node, the choices are Add First, Add Last, Add Before, and Add
After. When an actual OPC attribute is selected, the Delete, Move Up, and Move Down
commands can be invoked by shortcut keys DEL, UP ARROW, and DOWN ARROW,
respectively.
OPCDigitalStates Caution
The OPCDigitalStates generic attribute provides the value for the PI APS artificial
DigitalStateSet attribute.
Note: Due to the way the PI APS Sync Engine handles the artificial DigitalStateSet
attribute, significant risks are associated with using it. See the “DigitalStateSet” section
for additional explanation.
If a value is assigned to the OPCDigitalStates generic attribute, the value must be a
comma-separated list of states for a digital set. For example, assigning Closed,Open to
OPCDigitalStates indicates a digital set with two states: Closed and Open.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
49
Connector-specific Configuration Control
Point Creation Tab
The Point Creation tab contains configuration settings related to available points:
OPC Branches to search for new items
The OPC Branches to search for new Items: tree selects a subtree of the branches in
the browser hierarchy to explore for available points. Only the browser hierarchy
branches represented by nodes in the branch selection tree are searched for Items to be
considered as candidate available points. The candidate Items found in these branches are
subsequently qualified by the tag selection settings (see the “Tag Selection” section)
before becoming available points. That is, the OPCHDAInt_APS Connector uses two
distinct types of filtering while it searches for available points. The settings in this tree
filter the branches and the tag selection settings filter the Items.
The hierarchy of the nodes in the branch selection tree is not a literal image of the
browser hierarchy. The main difference is that a node in the branch selection tree may be
either a literal branch name or a pattern that represents one or more branches in the
browser hierarchy. Also, the branch selection tree is not required to extend to the lowest
50
levels in the browser hierarchy, only as deeply as necessary to reach the branches to be
explored in their entirety. That is, a node in the branch selection tree that has no subnodes
implicitly includes all sub-branches of the corresponding branch(es) in the browser
hierarchy.
The root branch of the browser hierarchy is always considered to be in the subtree of
branches to explore (otherwise, no sub-branches would be reachable). Therefore, any leaf
Items in the root branch will always be candidate available points.
The patterns used in nodes of the branch selection tree are an extension of the familiar PI
wildcard matching patterns: most characters represent themselves literally, “*” matches
zero or more characters, and “?” matches exactly one character. Case-insensitive
matching is used for alphabetic characters.
The extension to the usual wildcard syntax is “!” as the first character in a pattern. When
“!” is the first character of a pattern, it can be thought of as an exclusion operator. That
is, a pattern that begins with “!” will exclude any branch that matches the remainder of
the pattern.
Normally, when a sub-branch from the browser hierarchy does not match any of the
patterns under its corresponding parent branch in the branch selection tree, the subbranch is excluded from the available points search. A special case is made when all
patterns under a common parent node in the branch selection tree are exclusionary. In this
special case, the browser hierarchy sub-branches that are not explicitly excluded by one
of the patterns will be explored for available points.
Referring to the example browser hierarchy in Figure 2 and the example branch selection
configuration shown above, the subnodes under OPC Server Root correspond to the
actual root-level branches in the browser hierarchy. In this example, Modules is the only
branch selection pattern at the root level. When the APS Connector explores the root
level of the browser hierarchy, it matches each branch with this pattern and only descends
into the matching branch(es). In this example, the Modules branch will be explored; the
IO and any other root-level branches will be ignored because they do not match the
Modules pattern in the branch selection tree.
When the APS Connector explores the Modules branch in the browser hierarchy, the
corresponding node in the branch selection tree has two subnodes: AREA* and NORTH.
Each sub-branch of Modules in the browser hierarchy is sequentially matched with these
patterns until one matches or the list is exhausted. If a sub-branch matches AREA*, the
sub-branch will be explored. Since the AREA* pattern has no subpatterns, all deeper level
branches below a sub-branch that matches AREA* will also be explored. For the browser
hierarchy in Figure 2, AREA_A, AREA_B, and AREA_TEST match this pattern and,
therefore, will be explored.
The Modules branch in the browser hierarchy in Figure 2 contains a NORTH sub-branch,
and it will be explored because it matches the NORTH pattern in the branch selection tree.
Since the NORTH pattern has a subpattern, the sub-branches of the NORTH branch in the
browser hierarchy will be matched with the pattern !TEST*. This pattern begins with the
exclusion operation “!”, so any sub-branch that matches TEST* will be excluded.
Because the one and only child pattern of the NORTH branch selection node is an
exclusion pattern, the special case for all exclusionary patterns applies. Thus, subbranches of NORTH in the browser hierarchy that match TEST* are excluded and all other
sub-branches are recursively explored. For the browser hierarchy shown in Figure 2, the
FS102 and VBD01 sub-branches will be recursively explored.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
51
Connector-specific Configuration Control
To add nodes to the branch selection tree, right-click on either the parent for the new
node or the sibling node for the new node. A shortcut menu will open that contains
several add command.
To edit, delete, or move a node in the branch selection tree, right-click the node to open a
shortcut menu that contains commands for these operations. Also, clicking a selected
node will switch it into edit mode. The shortcut keys DEL and CTRL+X will delete and
cut a node, respectively.
A sub-branch in the branch selection tree can be moved by dragging it to a new position
in the tree. If the CTRL key is held down while dragging, the sub-branch is copied at the
new location.
All Items, Only Leaf Items, Only Branch Items
Below the branch selection tree, the All Items, Only Leaf Items, and Only Branch
Items option buttons select the type(s) of browser hierarchy nodes that are considered for
available points. The All Items selection includes both leaf nodes (which are always
Items) and any branch nodes that the OPC server identifies as Items.
The Only Leaf Items option effectively excludes any branch nodes that are identified as
Items. This option is applicable in two situations. First, a few OPC servers identify
branches as Items (by returning an ItemID) but subsequently return errors when the
ItemID is accessed. For an OPC server with this behavior, the Only Leaf Items option
prevents the OPCHDAInt_APS Connector from processing the branch Items, which
prevents error messages from attempting to read attributes for an invalid ItemID.
The second situation for using the Only Leaf Items option is when an OPC server
identifies its branches as Items and also has a leaf node for the same Item under the
branch. The Only Leaf Items option eliminates duplicate processing of the branch when
other leaf nodes under the branches need to be considered for point creation.
The Only Branch Items option effectively eliminates processing of all leaf nodes. This
option is useful for OPC servers that organize their browser hierarchy such that the leaf
nodes are attributes of the Item represented by the parent branch. For example, an OPC
server of this type may have a branch for a process variable like a voltage reading. The
leaves of the branch may contain description, engineering units, low limit, etc.
52
Pause between groups
When the PI APS Sync Engine automatically synchronizes an interface, eventually all
available points will be created in PI and become existing points. Thereafter, available
points will be infrequent occurrences, but the PI APS Connector must continue to search
the OPC server for new points during every synchronization scan. The search for
available points can be a CPU-intensive activity. Even though the PI APS Sync Engine
operates at reduced priority relative to other processes on the same computer, the OPC
server calls made by the OPCHDAInt_APS Connector can have a negative impact on the
OPC server. Two configurable settings work together to decrease both the rate of OPC
calls and CPU usage by the OPCHDAInt_APS Connector. One setting is the Pause
between groups time on this dialog box. The other setting is the Maximum number of
Available points to retrieve at a time value on the APS Connector tab of the Options
dialog box (opened from the Tools menu). The Maximum number of Available points
to retrieve at a time is the number of items in a group that the OPCHDAInt_APS
Connector processes before suspending itself for the Pause between groups time. These
two settings control how often the OPCHDAInt_APS Connector pauses and how long
each pause lasts.
Browser returns fully-qualified ItemIDs
The Browser returns fully-qualified ItemIDs option tells the OPCHDAInt_APS
Connector whether browser hierarchy node names are short names or ItemIDs. In the
general case, an OPC client (like the OPCHDAInt_APS Connector) must assume that the
browser hierarchy node names are not ItemIDs and call the OPC server to obtain the
ItemID for each browser hierarchy node name. If the OPC server actually returns ItemIDs
as browser hierarchy node names, the OPC call to obtain the ItemID is redundant. When
the Browser returns fully-qualified ItemIDs option is selected, the OPCHDAInt_APS
Connector does not make the separate call to the OPC server for the ItemID.
Create Quality Points
If the Create Quality Points check box is selected, the OPCHDAInt_APS Connector
creates quality points (see the “Quality Points” section) for Items that pass selection
criteria. The boxes following this check box contain optional prefix and suffix,
respectively, to add to the final tag name after tag naming and attribute formulas to
construct the quality point tag name. Unless tag naming rules or attribute formulas for the
OPCPITagname generic attribute depend on the OPCLocation2 generic attribute (data
or quality flag), fill in one or both of the prefix and suffix boxes to ensure that quality
points have tag names that are different from the corresponding data points.
Illegal Tagname Character Mapping
The Illegal Tagname Character Mapping area provides options for replacing characters
that are illegal in PI tag names with other characters. The OPCHDAInt_APS Connector
begins with the ItemID as the default tag name for a PI point. The Tag Naming and
Attribute Formula features can replace the default tag name. Before an available point is
returned to the PI APS Sync Engine, the options in this area are applied to the tag name.
Each illegal character is individually selected by its check box. The replacement box for
each selected illegal character must contain a single, legal character.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
53
Connector-specific Configuration Control
Attribute Formulas Tab
This screen shot shows the tab for configuring Attribute Formulas:
The Attribute Formulas feature is similar to the Tag Naming feature. Where tag naming
is specific to constructing one specific attribute (tag), the control for attribute formulas
generalizes the same concepts for other generic attributes supported by the
OPCHDAInt_APS Connector.
The main control on this tab is a grid with two panes. The left pane contains a single
column of conditions. The right pane contains one column for each generic attribute. The
cells in the right pane contain formulas for replacement values for the generic attributes.
The conditions and formulas on the Attribute Formulas tab use the same syntax as the
conditions and formulas in the Tag Naming feature. OPC server attribute values are
represented in conditions and formulas by generic attribute names enclosed in square
brackets. The table in the “Assignment of Actual OPC Attributes to Generic Attributes”
section contains the complete list of generic attributes defined by the OPCHDAInt_APS
Connector.
54
When the OPCHDAInt_APS Connector processes attribute formulas for an Item, each
column in the right pane is processed from top to bottom. If a formula cell is not empty
and the condition for the row is false, the formula in the cell is not evaluated and
processing continue with the next row. If a formula cell is not empty and the condition
for the row is true, the formula in the cell is evaluated, the resulting value is stored for
later replacement of the generic attribute for the column, and processing ends for the
column.
When the OPCHDAInt_APS Connector evaluates an attribute formula for a generic
attribute, the generic attribute is not immediately updated. That is, all conditions and
attribute formulas are evaluated based on the original values assigned to generic attributes
from actual OPC attributes. Any attribute formulas that are evaluated do not affect
conditions in following rows or attribute formulas in following columns. After processing
the entire grid, the results of any evaluated attribute formulas are assigned to the
corresponding generic attributes.
If a row contains formulas for more than one generic attribute, the condition for the row
will not be evaluated more than once. The first time the condition result is needed while
evaluating attribute formula columns, the condition is evaluated and the result is saved. If
subsequent columns reach an attribute formula on the same row, the saved condition
result is accessed instead of re-evaluating the condition.
Conditions can be entered directly in the Condition box, or the Build button opens the
Condition Builder dialog box.
Existing conditions can be edited directly in the grid. Click in a condition cell to switch
the cell to edit mode. For a wider view of a condition expression, double click on the
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
55
Connector-specific Configuration Control
folder icon in the condition cell to open the Edit Condition dialog box:
The condition expression can be edited directly in the Condition box. Or, click Build to
open the Condition Builder dialog box.
Similarly, you can edit an attribute formula directly in the grid by clicking on an attribute
formula cell to switch it into edit mode. Or, double click the folder icon in an attribute
formula cell to open the Formula Builder dialog box:
An empty cell in an attribute formula column indicates that the generic attribute has no
formula for the condition on the same row. This interpretation of empty cells is
convenient for the typical case where only isolated cells contain attribute formulas. To
support the infrequent cases where an attribute formula is needed to actually replace a
generic attribute with a blank or empty value, two special attribute formulas are provided:
[BLANK] and [EMPTY]. The special formula [BLANK] sets an attribute to a zero-length
string. The special formula [EMPTY] sets an attribute to a special “empty” value. The
results of these two special formulas have different interpretations when used to either
create or update a PI point. The zero-length string result of the [BLANK] formula is a
non-empty value. A zero-length string value overrides the default attribute value for point
creation or replaces the current attribute value for an existing point. In comparison, when
the PI APS Sync Engine updates an existing point, an empty attribute value is treated like
no value was assigned from the OPC server. For updating a point, the current attribute
value in the PI point is not changed. These behaviors are summarized in the following
table.
56
Created Point
Updated Point
[BLANK]
String attribute: zero-length string
Numeric attribute: zero
String attribute: zero-length string
Numeric attribute: zero
[EMPTY]
String attribute: zero-length string
Numeric attribute: zero
unchanged
OPCPIPointtype in Conditions and Formulas
When attribute conditions and formulas are evaluated, the OPCPIPointtype generic
attribute contains the integer code for a PI point type. For a candidate available point, the
code in the OPCPIPointtype generic attribute is the default PI point type setting for the
OPC Item type. For an existing point, the code for the actual type of the PI point is
assigned to the OPCPIPointtype generic attribute. When used in a condition, the
OPCPIPointtype generic attribute must be compared to the integer point type codes in
the following table.
Int32
8
Int16
6
Float32
12
Float16
11
Float64
13
Digital
101
String
105
When the OPCPIPointtype generic attribute is used in a formula, the integer point type
code replaces the generic attribute, not the point type name.
The results of formulas for the OPCPIPointtype generic attribute can be either the string
names or the integer codes for PI point types in the table above. The PI point type names
are case insensitive.
OPCDigitalStates Caution
The OPCDigitalStates generic attribute provides the value for the PI APS artificial
DigitalStateSet attribute.
Note: Due to the way the PI APS Sync Engine handles the artificial DigitalStateSet
attribute, significant risks are associated with using it. See the “DigitalStateSet” section
for additional explanation.
If a value is assigned to the OPCDigitalStates generic attribute, the value must be a
comma-separated list of states for a digital set. For example, assigning Closed,Open to
OPCDigitalStates indicates a digital set with two states: Closed and Open.
Quality Point Considerations
If quality points are enabled for point creation or the interface instance has existing
quality points, additional care must be taken when using the Attribute Formulas feature.
The reason is that attribute values for a data point, which are usually the primary concern,
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
57
Connector-specific Configuration Control
may not be appropriate for the corresponding quality point. The “Quality Points” section
contains related information. In particular, the values for these generic attributes are
likely to be different for a pair of data and quality points:
OPCDescription
OPCExDesc
OPCEngUnits
OPCMaxValue
OPCMinValue
OPCZero
OPCSpan
OPCCompDev
OPCCompDevPercent
OPCExcDev
OPCExcDevPercent
When quality points are involved, attribute formulas for the generic attributes in the list
above probably need to depend on conditions that include the OPCLocation2 generic
attribute. For example, the value of a quality point does not have the same engineering
units as the corresponding data point. If attribute formulas are defined to assign the
OPCEngUnits generic attribute for data points, the conditions that enable these formulas
should be extended with AND [OPCLocation2] = ‘0’. The same care should be taken
in the conditions for any generic attribute in the above list when quality points exist or are
enabled for creation. Similarly, attribute formulas that are specifically for quality points
should contain AND [OPCLocation2] = ‘1’ in their conditions.
58
Appendix A:
Error and Informational Messages
This section discusses several specific errors that may be encounter with the PI APS
Connector for the PI OPCHDAInt Interface and general troubleshooting methods for
resolving other problems.
Installation Problems
Symptoms of installation problems are usually noticed when the PI APS Configuration
Utility is being used to register the first PI OPCHDAInt Interface instance. Installation
problems can also occur after the OPCHDAInt_APS Connector is upgraded; the
symptoms of post-upgrade installation problems are messages in various log files (see
“Log Files” below for information on the log files).
The following is a list of symptoms and error messages, their explanations, and steps for
resolving the circumstances that caused them.

OPCHDAInt_APS does not appear as an installed connector in the PI APS
Configuration Utility
The PI APS Connector must be visible as OPCHDAInt_APS in the Installed PI APS
Connectors dialog box (Tools ► Installed Connectors…) and in the Select APS
Connector: list in the Configure Interface or COM Connector for PI APS dialog
box (Interface ► Register New…). If OPCHDAInt_APS does not appear in these
places, OPCHDAInt_APS.dll is not registered.

Error when opening the Connector-specific Control
If a dialog similar to the following is displayed when a PI OPCHDAInt Interface is
selected and Connector-specific… is clicked on the Settings menu,
OPCHDAInt_APS_Cfg.dll is not registered.
To register OPCHDAInt_APS_Cfg.dll, open a command window and enter the
following commands:
cd path_to_PIPC\APS\Connectors\OPCHDAInt_APS
regsvr32 OPCHDAInt_APS_Cfg.dll

“Error from CoCreateInstanceEx” messages from the PI APS Sync Engine
Messages similar to the following appear in the synchronization logs or PIPC log
files:
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
59
Appendix A: Error and Informational Messages
PIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx.
-2147221164: A specified class is not registered in the
registration database. from call
ptrAPSC.CreateInstance(OPCHDAInt_APS.PIAPSConnector) (for
localhost,Sandbox%PIOPCHDAInt1) in
LoadAPSRegisteredConnectors - will log every 100 errors
PIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx.
-2146233054: from call
ptrAPSC.CreateInstance(OPCHDAInt_APS.PIAPSConnector) (for
localhost,Sandbox% PIOPCHDAInt1) in
LoadAPSRegisteredConnectors - will log every 100 errors
PIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx.
-2147024894: from call
ptrAPSC.CreateInstance(OPCHDAInt_APS.PIAPSConnector) (for
localhost,Sandbox% PIOPCHDAInt1) in
LoadAPSRegisteredConnectors – will log every 100 errors
Other error numbers are also possible. The significant aspect of these messages is
that the error was returned from a call to
CreateInstance(OPCHDAInt_APS.PIAPSConnector). These messages indicate
that OPCHDAInt_APS.dll is not registered.
To register OPCHDAInt_APS.dll, open a command window and enter the following
commands:
cd path_to_PIPC\APS\Connectors\OPCHDAInt_APS
regsvr32 OPCHDAInt_APS.dll
Upgrade Problems
Following an upgrade, if the logs indicate that the old version of the OPCHDAInt_APS
Connector is still being used, the PI APS Sync Engine needs to be stopped and restarted.
When the PI APS Sync Engine starts, it loads copies of the PI APS Connectors for all
registered interface instances into its virtual memory. After a PI APS Connector is
loaded, the PI APS Sync Engine uses the copy in its virtual memory until the PI APS
Sync Engine service is stopped. Thus, if a PI APS Connector is upgraded while the
PI APS Sync Engine is running, the new version will not be used until the PI APS Sync
Engine is restarted. Follow the steps in the “Upgrading Checklist” to restart the PI APS
Sync Engine.
Operational Problems
Log Files
When the PI APS Sync Engine performs a synchronization scan for an interface, it
creates a log file for that synchronization scan. If errors occur during the synchronization
scan, the PI APS Sync Engine writes error details to the PIPC.log file and usually also
writes an error indication into the log file for the synchronization scan. The log files
created by the synchronization scans must be routinely monitored. If indications of errors
are found, additional information may be available in PIPC.log. The PI APS
Configuration Utility provides simple access to these log files. On the Tools menu, click
Log Files… to open the Synchronization & Point Logs dialog box.
60
In normal operation, the OPCHDAInt_APS Connector rarely logs messages. When it
does log a message, it is written to the pipc.log file. When the OPCHDAInt_APS
Connector encounters an error that it cannot handle, it returns an error code and
description string to the PI APS Sync Engine, which the PI APS Sync Engine usually
writes to both the PIPC.log file and the log file for the synchronization scan.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
61
Glossary
Available Points
Available points are points that PI AutoPointSync has detected on the data source but that
do not exist in PI.
Hidden Points
Hidden points are points that PI AutoPointSync has detected on the data source that do
not exist in PI and that the user has marked to be hidden from view.
Existing Points or Existing PI Points
Existing Points or Existing PI Points refers to points that already exist in PI and belong to
the current interface.
APS Connector (APS Interface Connector)
The APS Connector or APS Interface Connector is responsible for attribute data
collection from the data source.
Key Attributes
A Key Attribute is a PI attribute that is required in order to identify what point in the data
source the PI point corresponds to.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
63
Revision History
Date
Author
Comments
24-Aug-2006
LDaley
Version 1.0.1.0 Rev A: first edition of the
OPCHDAInt_APS user manual.
Based on skeleton version 1.1.
7-Nov-2006
Janelle
Version 1.0.1.0 Rev B: updated hardware diagram,
added information in Summary of Features and
Requirements table; updated headers and footers.
15-Nov-2006
MKelly
Version 1.0.1.0, Rev C; updated tabs in headers and
footers to be within page margins, resized several
screenshots and tables to fit with page margins.
PI AutoPointSync Connector for the OPC HDA Interface to the PI System
65