OPC DA Interface AutoPointSync Connector - OSIsoftcdn.osisoft.com/interfaces/1703/PI_OPCInt_APS_1.2.0.0.… · Web viewOPC DA Interface AutoPointSync Connector. ... (PI_OPCInt.docx)

OPC DA Interface AutoPointSync Connector

Version 1.2.0.0

OSIsoft, LLC 777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

OSIsoft Australia • Perth, AustraliaOSIsoft Europe GmbH • Frankfurt, GermanyOSIsoft Asia Pte Ltd. • Singapore OSIsoft Canada ULC • Montreal & Calgary, CanadaOSIsoft, LLC Representative Office • Shanghai, People’s Republic of ChinaOSIsoft Japan KK • Tokyo, JapanOSIsoft Mexico S. De R.L. De C.V. • Mexico City, MexicoOSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

OPC DA Interface AutoPointSync ConnectorCopyright: © 1997-2011 OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTSUse, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.

Published: 05/2011

ii

http://www.osisoft.com/

Table of Contents

Terminology ..................................................................................................................viiPI AutoPointSync Terms...................................................................................viiGeneral Terms.................................................................................................. ix

Chapter 1. Introduction...................................................................................................1OPC Terminology...............................................................................................2Reference Manuals............................................................................................2Summary of Features and Requirements..........................................................3Supported PI Point Attributes.............................................................................5Diagram of PI APS for the OPCInt Interface......................................................8OPCInt_APS Features and Limitations..............................................................9

ItemID Must Be In InstrumentTag............................................................9OPC Browsing Interface Required to Search for Available Points...........9OPC Properties Required for Attribute Values.........................................9Filtering in the OPCInt_APS Connector on Full ItemID..........................10Configurable PI PointType for Each OPC Data Type............................10Scan Class.............................................................................................11Cannot Construct Available Points from Hints.......................................11

Chapter 2. Principles of Operation..............................................................................13Point Class.......................................................................................................14Point Source and Instance ID..........................................................................14Key Attributes...................................................................................................15Creatable and Synchronizable Attributes.........................................................15Available and Hidden Points............................................................................15

Tag Naming Conventions......................................................................16Point Type..............................................................................................17

Updated Attributes...........................................................................................17Error Handling..................................................................................................17

Chapter 3. Installation, Upgrading, and Uninstallation Instructions........................19Installation Instructions.....................................................................................19Upgrading Instructions.....................................................................................20Uninstallation Instructions................................................................................21

Chapter 4. Registering an Interface Instance with APS.............................................23Register the Interface.......................................................................................24Configure the Settings......................................................................................30

Rules.....................................................................................................31Synchronization Schedule.....................................................................32User-set Defaults...................................................................................33

OPC DA Interface AutoPointSync Connector ii

Connector-specific Options....................................................................37Enable Synchronization...................................................................................38

Chapter 5. Connector-specific Configuration Control...............................................39Select OPC Data Type.....................................................................................40Tag Name Patterns..........................................................................................41Filtering............................................................................................................42Pause x milliseconds after every n OPC operations........................................48

Appendix A. Error and Informational Messages.......................................................49Installation Problems........................................................................................49Upgrade Problems...........................................................................................51Operational Problems......................................................................................52

Appendix B. Resolving Installation Problems...........................................................55Installing Assemblies into the GAC..................................................................55Registering Assemblies with COM...................................................................57

Appendix C. OPC Server Surveys..............................................................................59ABB.................................................................................................................. 59Ascolab GmbH.................................................................................................60Beckhoff...........................................................................................................60CimQuest Inc...................................................................................................60Citect................................................................................................................60Cogent Real-Time Systems, Inc.......................................................................61Cyberlogic........................................................................................................61Descartes Systems Sciences, Inc....................................................................61Elipse Software Ltda........................................................................................61Emerson Process Management.......................................................................62Fluke................................................................................................................63Foxboro............................................................................................................63GE Fanuc Automation Americas, Inc...............................................................64Gesytec GmbH................................................................................................64Honeywell........................................................................................................64ICONICS..........................................................................................................65InduSoft............................................................................................................65Intellution..........................................................................................................65Invensys...........................................................................................................66Kassl GmbH.....................................................................................................67KEPware..........................................................................................................68Kongsberg........................................................................................................68Krones..............................................................................................................68KW................................................................................................................... 69Matrikon Inc.....................................................................................................69Mitsubishi.........................................................................................................69MSIndustrie Software GmbH...........................................................................70Northern Dynamic Inc......................................................................................70OMRON...........................................................................................................70

OPC DA Interface AutoPointSync Connector iii

Phoenix Contact GmbH & Co. KG...................................................................71PiiGAB.............................................................................................................71Power Measurement........................................................................................71Pressco Technology, Inc..................................................................................71Progea srl.........................................................................................................72Rockwell Software............................................................................................72RoviSys Company............................................................................................72Siemens AG.....................................................................................................73SISCO, Inc.......................................................................................................74Smar................................................................................................................75Softing AG........................................................................................................75Software Toolbox.............................................................................................76Takebishi Electric.............................................................................................76Technosoftware AG.........................................................................................78Westinghouse..................................................................................................78Wonderware.....................................................................................................78Woodhead........................................................................................................79Yokogawa........................................................................................................79

Appendix D. Technical Support and Resources.......................................................81Before You Call or Write for Help...........................................................81Help Desk and Telephone Support........................................................81Search Support......................................................................................82Email-based Technical Support.............................................................82Online Technical Support.......................................................................82Remote Access......................................................................................83On-site Service......................................................................................83Knowledge Center.................................................................................83Upgrades...............................................................................................83OSIsoft Virtual Campus (vCampus).......................................................83

Appendix E. Revision History.....................................................................................85

OPC DA Interface AutoPointSync Connector iv

Terminology

In order to understand this manual, you must be familiar with the terminology used in this document. Specifically, you must have read the PI AutoPointSync for Interfaces and PI COMConnectors user manual that explains important PI AutoPointSync concepts and provides full definitions of PI AutoPointSync terminology.

PI AutoPointSync Terms

APSAn acronym for PI AutoPointSync.

APS Configuration UtilityThe interactive application that registers instances of interfaces for automatic point synchronization and configures APS options.

APS Connector An interface-specific module that communicates with the same data source as the interface to obtain current tag attribute values. Generally, an APS Connector is designed for a particular interface and its implementation is based on a specific programming interface for the data source. During each synchronization scan, the APS Synchronization Engine dynamically loads the APS Connector for the interface instance and calls it to retrieve information for updating the PI point database.

APS Connector-specific ControlA module that provides the user interface for configuring the options of a specific APS Connector. Most APS Connectors have companion APS Connector-specific Controls. The APS Configuration Utility dynamically loads the APS Connector-specific Control that is identified by the APS Connector for the selected interface instance.

APS Synchronization EngineThe core service of the AutoPointSync product that schedules and performs synchronization scans for registered interface instances. During a synchronization scan, it obtains current tags and their attributes from a data source by dynamically loading and calling “plug-ins” known as APS Connectors. The APS Synchronization Engine creates, edits, or deletes PI points as necessary to agree with current tag definitions in the data source.

APS Synchronization Trigger ServiceA service that monitors for events that are configured to trigger a synchronization scan for a registered interface instance.

Available PointsPI points that can be created for data source tags that are not associated with a PI point. Available points do not exist in the PI point database.

OPC DA Interface AutoPointSync Connector vi

Terminology

Existing Points or Existing PI PointsPI points that already exist and are assigned to an interface instance that is registered with APS.

Hidden PointsFormer available points that someone marked for APS to ignore. Hidden points do not exist in the PI point database. They are excluded from the display of available points and prevent creation of PI points for the associated data source tags.

Key AttributesThe PI point attributes that are required by the interface and APS to identify and access the data source tag for the PI point.

Known AttributesThe attributes for which an APS Connector can provide values when a PI point is created.

Master Synchronization SettingA per-point configuration option that controls whether a PI point is synchronized by APS. Synchronization is enabled or disabled individually for each existing PI point.

PI Point DeletesExisting PI points that no longer have a valid data source tag.

PI Point EditsAttributes of existing PI points that are not in agreement with the corresponding data source tag attributes.

Syncable AttributesAttributes for which an APS Connector can provide values to update an existing PI point.

Synchronization or Synchronization ScanThe process that compares PI points for an interface with data source tags and either changes the PI Server to resolve any differences or logs the differences.

vii

General Terms

AttributeA parameter that describes a PI point. Each PI point has an associated list of attributes. Some attributes are simply descriptive. Other attributes are configuration parameters for the PI Server, the interface instance that transfers data between the PI point and data source, or both.

COM ConnectorA COM object that allows the PI Server to access data from a foreign data historian and make it available to any PI client application in a seamless fashion. Some currently available COM Connectors include those for data historians from AspenTech and Honeywell as well as one for any data source with an OLEDB provider. COM Connectors are only available on Windows platforms.

DCSAn acronym for Distributed Control System. DCS was used in earlier versions of APS documentation as a generic term for any data source that provides data to a PI Server, including measurement and control systems or other historian systems, even other PI Servers.

ICUThe PI Interface Configuration Utility. The ICU is the primary application that you use to configure PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.

You can configure an interface by editing a startup command file. However, APS cannot access interface parameters from a startup command file. Therefore, configuring an interface instance with the ICU is a prerequisite to registering the interface instance with APS.

InterfaceA software program that collects data from some type of data source and sends the data to a PI Server. Some interfaces also have the ability to read data from a PI Server and write back to the data source.

Interface NodeA computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIA library of functions that PI client applications call to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

OPC DA Interface AutoPointSync Connector viii

Terminology

PI CollectiveTwo or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member seamlessly continues to collect and provide data access to your PI clients.

PIHOMEThe directory that is the common location for 32-bit PI client applications. OSIsoft installation kits create a system environment variable named PIHOME that is set to the path of the top-level directory for 32-bit PI clients.

A typical PIHOME on a 32-bit operating system is C:\Program Files\PIPC.

A typical PIHOME on a 64-bit operating system is C:\Program Files (x86)\PIPC.

PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME. Most APS files are in the APS directory under PIHOME.

pipc.logThe file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU and APS Configuration Utility provide easy access to the pipc.log. The pipc.log file is in the dat subdirectory of PIHOME.

PI SDKA library of functions that client applications call to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK. PI APS uses PI SDK to communicate with the PI Server.

PI Server NodeA computer on which PI Server programs are installed. The PI Server runs on the PI Server node.

PI SMTPI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server node or a PI Interface node.

PointThe basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.

A PI point does not necessarily correspond to a "point" on the data source. For example, a single "point" on the data source can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.

In APS documentation, point means a PI point and tag designates a “point” on the data source.

ix

ServiceA Windows program that runs without user interaction. A service has the ability to start up when the computer itself starts up. If started manually, it continues to run after you log off from Windows.

Tag (Input Tag and Output Tag)The name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms "tag" and "point" interchangeably.

In APS documentation, point means a PI point and tag designates a “point” on the data source.

Interfaces read values from a data source and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the data source.

UniInt (Universal Interface)A framework for interfaces to the PI Server. UniInt provides common features and generic functions required by most interfaces. Most interfaces developed by OSIsoft are based on the UniInt framework, which results in a consistent set of features in the OSIsoft interfaces to PI. For example, the UniInt framework supports special points that can be used to monitor the performance and health of an interface. The UniInt framework also supports a failover mechanism for interface redundancy. The UniInt Interface User Manual provides complete information about the features provided by UniInt.

OPC DA Interface AutoPointSync Connector x

Chapter 1. Introduction

This manual describes the operation of the PI AutoPointSync (APS) Connector for the OPC DA Interface. The informal name of the interface is OPCInt and the informal name of this PI APS Connector is OPCInt_APS.

APS is a tool for synchronizing the PI points for interface instances with the tag definitions in the data sources associated with the interface instances. APS is based on Microsoft’s Component Object Model (COM) technology and includes the following applications and modules:

The APS Configuration Utility.The APS Configuration Utility is the interactive application which registers instances of interfaces that have corresponding APS Connectors for automatic point synchronization and configures APS options.

The APS Synchronization Engine (Sync Engine).The APS Synchronization Engine schedules synchronization scans and performs point attribute synchronization for all interface instances that are registered with APS. This module is the foundation of APS and does most of the work. The APS Synchronization Engine is installed as a Windows service that starts automatically and runs continuously.

The APS Synchronization Trigger Service.The APS Synchronization Trigger service monitors for events that are configured to trigger a synchronization scan for a registered interface instance. The APS Synchronization Trigger service is installed as a Windows service that starts automatically and runs continuously.

APS Connector modules (Interface-specific Connectors).APS Connectors are interface-specific modules that communicate with the same data source as the interface to obtain current tag attribute values. During each synchronization scan, the APS Synchronization Engine calls the APS Connector for the interface instance to retrieve a list of current tag definitions in the data source. The APS Synchronization Engine uses this information for updating the PI point database.

APS Connector-specific Configuration Controls.Each APS Connector-specific Configuration Control provides the user interface for configuring the options of a specific APS Connector. If the APS Connector for an interface instance has a connector-specific configuration control, the APS Configuration Utility makes it available when the interface instance is selected for configuration.

The modularized architecture of APS allows a single instance of the APS Configuration Utility and APS Synchronization Engine to support multiple APS Connector modules on one computer. Also, adding new APS Connector modules does not require changes to the APS

OPC DA Interface AutoPointSync Connector 1

Configuration Utility or APS Synchronization 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 APS Synchronization Engine uses an interface-specific APS Connector to obtain current tag definitions from the data source. For the OPCInt Interface, the APS Synchronization Engine calls the OPCInt_APS Connector to retrieve a list of the current tag definitions from the OPC DA Server. This information is used for creating, updating, or deleting PI points for the OPCInt Interface instance registered with the OPCInt_APS Connector.

APS provides many options to configure its operation for each registered interface instance. Some options apply to the interface instance, such as the interval between synchronization scans or the changes that the APS Synchronization Engine is permitted to make automatically. Other options apply to individual PI points, such as whether the APS Synchronization Engine is allowed to synchronize the point as a whole and, if so, which specific attributes are editable. The APS Synchronization Engine logs all automated actions and changes for auditing by the administrator.

Note: When an interface instance is registered with APS, APS synchronization rules are preset to non-automatic selections and the default per-point synchronization settings are preset to disable synchronization on each point.

The preset options are designed to prevent APS from changing the PI point database until explicitly enabled. While the preset selections for default per-point synchronization settings are in effect, synchronization is disabled for points created or discovered by APS until you manually enable synchronization for those points.

OPC Terminology

Both the OPCInt Interface and the OPCInt_APS Connector use functions defined in the OPC Data Access (DA) standards to communicate with an OPC DA Server. The OPC Data Access standards use the term Item to refer to data values in an OPC DA Server. That is, an OPC Item is conceptually the same as a “point” in a traditional control system. Each OPC Item is identified by a unique ItemID, which corresponds to the “tag” or name for a point in a control system.

Reference Manuals

OSIsoft PI AutoPointSync for Interfaces and PI COM Connectors (PI APS User

Manual.pdf)

PI Interface Configuration Utility (PI Interface Configuration Utility.pdf)

OPC DA Interface (PI_OPCInt.docx)

OPC Foundation Data Access Automation Interface Standard, Version 2.02

Data Access Custom Interface Standard, Version 2.05A


Summary of Features and Requirements

The following table summarizes the main features and requirements of the OPCInt_APS Connector. An asterisk (*) in the table indicates that additional explanation follows the table.

Feature Support

Part Number PI-IN-OS-OPC-NTI

* Platforms:

Windows XP

32-bit OS Yes

64-bit OS Yes (Emulation Mode)

Windows 2003 Server

32-bit OS Yes


Windows Vista

32-bit OS Yes


Windows 2008

32-bit OS Yes

Windows 2008 R2


Windows 7

32-bit OS Yes


.NET Version Required 3.5

PI Point Types Int16, int32, float16, float32, float64, digital, string

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 Node No

Must Install on OPC DA Server Node No

Must Install on Interface Node No

Tag Selection Conditions No

Tag Naming Rules No (See the “Tag Name Patterns” section.)

Attribute Formulas No

Attribute Lookup No

* Additional PI Software Required Yes

Vendor Software Required on APS Node

No

Vendor Software Required on Foreign Device

No

Vendor Hardware Required No


Introduction

Feature Support

Additional PI Software Included with APS Connector

No

* Data Source Point Types VARIANT types:VT_BOOL booleanVT_BSTR stringVT_CY 64-bit fixed pointVT_DATE floating-point dateVT_EMPTY canonical datatypeVT_I1 8-bit integerVT_I2 16-bit integerVT_I4 32-bit integerVT_I8 64-bit integerVT_INT 32-bit integerVT_R4 32-bit floating pointVT_R8 64-bit floating pointVT_UI1 8-bit unsigned integerVT_UI2 16-bit unsigned integerVT_UI4 32-bit unsigned integerVT_UI8 64-bit unsigned integerVT_UINT 32-bit unsigned integerone-dimensional array of the above types

PlatformsThe OPCInt_APS Connector is designed to run on the above-mentioned Microsoft Windows operating systems and their associated service packs.

The OPCInt_APS Connector requires .NET 3.5 or later.

Please contact OSIsoft Technical Support for more information.

Additional PI Software RequiredAPS obtains information about installed interface instances from configuration data stored in the Module Database by the PI Interface Configuration Utility (ICU). Also, APS stores its configuration information in the Module Database. Therefore, 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 OPCInt Interface ” section for restrictions that apply to the OPCInt_APS Connector.

PI Server version 3.3.361.43 or later is required for Module Database support.

OPC DA Interface.

ICU is required because an interface instance must be managed by ICU before it can be registered with APS. An instance of a Windows interface must be managed by a copy of ICU that is installed on the same computer as the interface instance.

Data Source Point TypesThe OPCInt_APS Connector supports the VARIANT types recommended in the Data AccessCustom Interface Standard, the other numeric VARIANT types that the standard does not specifically recommend, and one-dimensional arrays of the supported VARIANT types. Configuration options associate a PI point type with each VARIANT type. See the “PI Point Type” section later in this document.

4

Supported PI Point Attributes

The following table lists the PI point attributes that the OPCInt_APS Connector supports. The OPCInt_APS Connector returns these attributes to the APS Synchronization Engine to use for editing existing PI points or creating new PI points. An asterisk (*) in the table indicates that additional explanation follows the table.

Attributes that are not in this table are not changed when APS (either the APS Synchronization Engine or APS Configuration Utility) synchronizes an existing point.

When APS creates a new PI point, default values are assigned to attributes that are not in the table. APS has configurable default values for some attributes that have no corresponding attributes in most data sources (see the “Security & Archive Settings” section). Other than these special attributes, the default values configured in the PI Server are assigned to attributes that are not in the table.

Note: When a PI point is created, attributes not in the table are set to default values by either APS (for the special cases) or the PI Server (for all others).

OPC DA Server Attribute ColumnThe “OPC DA Server Attribute” column contains the data source attribute that provides the value for each PI attribute.

The numeric Property IDs (see the “OPC Properties Required for Attribute Values” section for a discussion of OPC properties) in this column are built into the OPCInt_APS Connector. The quoted string following each Property ID is the standard description of the property from the Data Access Custom Interface Standard.

Many OPC DA Servers have been surveyed for the properties that they support and other aspects of their operation that are relevant to the OPCInt_APS Connector. The results of these surveys, which are predictions of expected results, are in the “OPC Server Surveys” appendix. That is, the results in the appendix are not verified by actually testing the OPCInt_APS Connector with each of the OPC DA Servers.

Sync ColumnThe “Sync.” column indicates whether an attribute is used for point creation only or for both point creation and synchronization of existing points.

“No” in this column indicates that the attribute cannot be synchronized. That is, the APS Connector provides a value for this attribute for new PI point creation but does not provide a value for editing an existing point. Generally, the key attributes for the APS Connector (and interface) are not synchronizable because changing a key attribute causes the PI point to reference a different data source tag. APS always uses the attribute value from the APS Connector for new PI point creation.

“Yes” in this column indicates that the APS Connector can provide a value for this attribute for both new PI point creation and editing the attribute of an existing point. The attribute value from the APS Connector is always used for new PI point creation. However, the per-point synchronization settings control whether APS can edit the attribute for a specific existing point.

Note: The per-point synchronization settings do not apply to new PI point creation.


Introduction

Default Value ColumnThe “Default Value” column in the table shows the default values that the APS Connector provides if the data source does not provide a value.

The notation “<blank>” in this column indicates that the default value is a zero-length string.

The notation “<no default>” in this column indicates that the APS Connector does not provide a default value for an attribute. In effect, when no value is available from the data source for a tag, the APS Connector does not include the attribute in the attribute values that are returned to the APS Synchronization Engine for a point. As a result, if the data source returns no attribute value for an existing PI point, APS does not change the PI point attribute. If the data source returns no attribute value for a new PI point that APS is creating, the attribute is set to a default value by the PI Server.

Description PI Point Attribute OPC DA Server Attribute

Sync. Default Value

PI point name Tag See “Tag Naming Conventions” section

No ItemID

PI point type PointType Property ID 1 “Item Canonical DataType”. See “Point Type” section

No

Data source tag name or address

InstrumentTag ItemID No

Special handling for data value

Location2 No Depends on OPC Item type

Polled, Advise, Event, Output

Location3 No 1

Scan class Location4 No 1

Point description Descriptor Property ID 101“Item Description”

Yes <blank>

Engineering units EngUnits Property ID 100“EU Units”

Yes <blank>

Point minimum value Zero Property ID 103“Low EU”

Yes 0

Point value range Span Property ID 102 – Property ID 103“High EU” – “Low EU”

Yes 100

Digital state set name

* DigitalSet No Depends on OPC Item type

States in digital state set

* DigitalStateSet No <no default>

Array Element Number

UserInt1 No 0

6

DigitalSetNothing in the Data Access Custom Interface Standard corresponds to a PI digital state set name. When configuring the OPCInt_APS Connector to create a digital PI point for a particular OPC data type (see the “Select OPC Data Type” section), the connector-specific configuration control only allows selection of a name of an existing digital state set. The OPCInt_APS Connector returns the selected digital set name as the value for the DigitalSet attribute of any available digital points.

Note: The DigitalSet attribute is not synchronizable by the OPCInt_APS Connector. Therefore, the DigitalSet attribute only applies to digital points that are available for creation.

When the OPCInt_APS Connector returns attributes for a digital point, the APS Synchronization Engine checks whether a digital state set already exists in the PI Server with the name in the DigitalSet attribute. Unless a digital state set is removed from the PI Server after configuring the OPCInt_APS Connector, the digital state name exists in the PI Server. However, if the digital state set name does not exist when APS creates a digital point, APS first creates a digital state set with this name and an empty list of states.

DigitalStateSetDigitalStateSet is an artificial attribute that APS uses internally; it is not an actual PI attribute. DigitalStateSet 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 state set for the point. If the DigitalStateSet attribute for the point is not empty, it contains a list of the states expected in the digital state set. Since the Data Access Custom Interface Standard does not specify a universal method for a client application to obtain a list of state names, the OPCInt_APS Connector always returns no value for the DigitalStateSet attribute.


Introduction

Diagram of PI APS for the OPCInt Interface

PI Server

OPC DA Server

PI Interface NodePI APS Node

OPC DA COM Objects

OSIsoft Libraries: PI API and PI SDK

PI APS Sync Engine

OPCInt_APS Connector OPCIntInterface

Tag Information Process Data

The implementation of APS requires installation of the APS Synchronization Engine, APS Configuration Utility, and the APS Connectors on the same computer (identified as “PI APS Node” in the diagram above). ICU must be installed on the PI Interface node. In general, the 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 APS components can be installed on the same node as the PI Interface or data source.

If the OPC DA Server runs on a Windows computer, the APS components can be installed on the same computer as the OPC DA Server. In this case, OPCInt_APS is local to the OPC DA Server, which eliminates the need for DCOM and the complexities of DCOM configuration.

To avoid competing with the PI Server for computer resources, OSIsoft recommends that APS not be installed on the PI Server computer, but this is not prohibited.

8

OPCInt_APS Features and Limitations

ItemID Must Be In InstrumentTag

The OPC DA Interface looks for the ItemID either in the InstrumentTag attribute (recommended) or in the ExDesc attribute. The OPCInt_APS Connector looks for ItemID only in the InstrumentTag attribute. The OPCInt_APS Connector does not support ItemID in the ExDesc attribute.

Note: Before registering an Interface instance with APS, ensure that all existing points are configured with ItemID in the InstrumentTag attribute.

OPC Browsing Interface Required to Search for Available Points

The OPCInt_APS Connector is an OPC Data Access client. The OPC Data Access standards require an OPC DA Server to implement a base set of COM interfaces. The remaining COM interfaces in the standards are optional. Using only the required OPC Data Access interfaces, the OPCInt_APS Connector supports synchronization of existing OPC DA Interface points and detection of deleted points. For the OPCInt_APS Connector to search for OPC Items for which PI points can be created, the OPC DA Server must implement the optional address space browsing interface.

Note: the OPC DA Server must provide the optional address space browsing interface for the OPCInt_APS Connector to find available points.

OPC Properties Required for Attribute Values

The objective of the OPCInt_APS Connector is to work with any compliant OPC DA Server. Otherwise, specific APS Connectors would have to be developed for each different OPC DA Server. The OPC Data Access Custom Interface Standard defines an “interface [that] can be used by clients to browse the available properties (also referred to as attributes or parameters) associated with an ITEMID and to read the current values of these properties.” The Data Access Custom Interface Standard proceeds to say that the “design of this interface is based upon the assumption is [sic] that many ITEMIDs are associated with other ITEMIDs which represent related values such as Engineering units range or Description… As a result, this interface allows a flexible and convenient way to browse, locate and read this related information without imposing any particular design structure on the underlying system.” That is, OPC Item properties correspond to PI point attributes. The Data Access Custom Interface Standard intends for additional Item information to be implemented as properties.

Because OPC properties are the only generic mechanism available, the OPCInt_APS Connector uses the OPC Data Access properties interface to read property values that can be used (directly or indirectly) as sources for PI point attributes. The Data Access Custom Interface Standard only recommends, but does not require, a set of common properties, which includes description, engineering units, and highest and lowest expected values. If the OPC DA Server provides the set of recommended properties, the OPCInt_APS Connector can obtain values to synchronize PI point Descriptor, EngUnits, Zero, and Span attributes. Unfortunately, most OPC DA Servers do not implement the set of recommended properties.


Introduction

That is, very few OPC DA Servers actually provide properties that the OPCInt_APS Connector can use to obtain attribute values for a PI point from the associated OPC Item. OSIsoft has analyzed the OPC properties that are available in many OPC DA Servers. The “OPC Server Surveys” appendix lists the OPC properties for the OPC DA Servers that were analyzed.

Although a particular OPC DA Server may not provide OPC properties that are usable for PI point attributes, the OPC DA Server may have Items that appear to be usable for PI point attributes. Because the naming system for Items is not standardized, the OPCInt_APS Connector cannot use these Items without 1) knowing the specific OPC DA Server with which it is communicating, and 2) having server-specific internal code for the particular naming system and Item relationship rules of the OPC DA Server.

Note: the OPC DA Server Connector cannot obtain PI point attribute values from Items unless the Items are linked to properties of the Item configured for the PI point.

Filtering in the OPCInt_APS Connector on Full ItemID

The Data Access Custom Interface Standard browsing interface has a method that returns the Items in a branch of the OPC DA Server address space. One of the parameters to this method is a filter criteria string. The filter criteria string is OPC DA Server-specific for several reasons:

The Data Access Custom Interface Standard does not require an OPC DA Server to provide any filtering.

The Data Access Custom Interface Standard does not specify the syntax of the filter criteria string.

To provide filtering that is independent of the OPC DA Server, the OPCInt_APS Connector implements Item filtering. That is, the OPCInt_APS Connector does not use the Item filtering in the OPC DA Server. The filtering capabilities in the OPCInt_APS Connector have several advantages over the filtering in most OPC DA Servers:

Multiple filter criteria are allowed.

The filter criteria are applied to the full ItemID.

Regular expressions are used for pattern matching.

The Item filtering feature is fully explained in the “Filtering” section.

Configurable PI PointType for Each OPC Data Type

The OPCInt_APS Connector contains a table with a row of configurable options for each OPC data type. PI point type is one of the options on each row. That is, each OPC data type has an individually-configured PI point type option. The PointType attribute for the available point for an Item is set from the PI point type option on the row for the OPC data type of the Item. The “Select OPC Data Type” section explains how to configure the options for OPC data types.

10

Scan Class

All available points returned by the OPCInt_APS Connector are configured as Advise points (Location3 set to 1) in scan class 1 (Location4 set to 1). Read the OPC DA Interface user manual for an explanation of Advise points and other methods that the OPC DA Interface can use to read values from the OPC DA Server.

Cannot Construct Available Points from Hints

The OPC Data Access Standard recommends that the browsing interface return actual Items. However, the standard permits an OPC DA Server to return a “hint” string instead of, or in addition to, Items. For example, the browsing interface in an OPC DA Server for a PLC with registers numbered from 0 to 32766 is allowed to return a hint like “R0-32766” instead of the 32767 actual items “R0”, “R1”, “R2”, and so forth. The OPCInt_APS Connector can detect that such “hints” are not valid Items. However, the structure (syntax) of “hint” strings is not standardized, so the OPCInt_APS Connector cannot use hints to generate actual ItemIDs.

Note: If an OPC DA Server returns only “hint” strings (that is, does not return individual Items), the OPCInt_APS Connector cannot identify available points.


Chapter 2. Principles of Operation

This section explains how the OPCInt_APS Connector and APS Synchronization Engine work together to synchronize PI points for an instance of the OPCInt Interface.

The APS Synchronization Engine runs as a Windows service. It appears in the Windows Task Manager on the Processes tab as PIAPSEngine.exe. The APS Synchronization Engine schedules synchronization scans and implements the synchronization tasks common to all APS Connectors. The APS Synchronization Engine makes all PI SDK calls to obtain or change attributes for existing PI points or to create new PI points. By itself, the APS Synchronization Engine is unable to communicate with any data source.

The OPCInt_APS Connector implements a specific set of functions required by the APS Synchronization Engine. It is an in-process COM object that is implemented in a dynamic-link library (DLL) named OSIsoft.OPCInt_APS.dll. This object is registered during installation of the OPCInt_APS Connector. The APS Synchronization Engine dynamically loads the OPCInt_APS Connector. That is, the OPCInt_APS Connector “plugs into” the APS Synchronization Engine.

During a synchronization scan for the OPCInt Interface, the APS Synchronization Engine calls functions in the OPCInt_APS Connector that actually obtain data source tag definitions by calling the programming interface for the OPC DA Server. The OPCInt_APS Connector returns tag information from the OPC DA Server to the APS Synchronization Engine. The OPCInt_APS Connector does not access or change the PI point database.

The OPCInt_APS Connector has two primary functions that the APS Synchronization Engine calls:

Acquire a list of available points in the OPC DA Server, and

Obtain current OPC DA Server attributes for existing interface points.

If APS is configured for automatic operation, the APS Synchronization Engine uses information returned by the OPCInt_APS Connector to synchronize existing OPCInt Interface instance points in the PI Server, create new PI points for the interface instance, and remove PI points when corresponding data source tags are deleted. Alternatively, the APS Synchronization Engine stores the results of the last synchronization scan in a database file. The APS Configuration Utility can read the results of the last synchronization scan from the database file and display the pending edits for existing points, existing points that can be deleted, and new points that can be created. Also, the APS Configuration Utility allows you to selectively apply pending edits, create new points, or delete points.


OPC DA DetailsThe OPC Foundation has issued two complementary Data Access standards: Data Access Custom Interface Standard and Data Access Automation Interface Standard. Both Data Access interfaces provide essentially the same functionality. The Custom Interface standard is primarily intended for use from C++. Since using the Custom Interface from other languages can be difficult or impossible, the OPC Foundation created the Data Access Automation Interface Standard to simplify or enable access to OPC DA Servers from “automation” languages. The Data Access Automation Interface Standard states that its fundamental design goal is “to work as a ‘wrapper’ for existing OPC Data Access Custom Interface Servers providing an automation friendly mechanism to [access] the functionality provided by the custom interface.” As an extension of the Custom standard, the Automation standard explicitly references the Data Access Custom Interface Standard for the detailed descriptions of major functions.

The OPCInt_APS Connector is an OPC Data Access Automation client. In contrast, the OPCInt Interface is an OPC Data Access Custom Interface client. Since both Data Access standards apply to an Automation client, this document refers to both standards.

The OPC Data Access Automation Interface can be implemented as a generic “wrapper” that translates Automation Interface calls into Custom Interface calls to an actual OPC DA Server. The wrapper approach has a second benefit when the client is implemented with .NET technology: the wrapper provides a bridge between the .NET Framework and COM. The OPCInt_APS Connector is implemented with .NET technology and is bound to the Data Access Automation wrapper that is distributed by OSIsoft with OPCInt_APS and other OSIsoft products.

Point Class

This APS Connector returns “Classic” when APS asks for the point class to use when creating new PI points. APS creates only Classic points for an interface instance registered with the OPCInt_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 APS Synchronization 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 because errors result when the APS Synchronization Engine requests the current attribute values for attributes that are not defined in the class. Therefore, use the APS Configuration Utility to disable synchronization for any point in a class that does not contain all of the attributes supported by the OPCInt_APS Connector.

Point Source and Instance ID

PI points are associated with an OPCInt Interface instance by the PointSource and Location1 attributes. APS obtains the PointSource and instance ID values for an interface instance from its ICU configuration. APS uses these attributes and the values from ICU to identify the existing points for an interface instance. If APS creates a point for the interface instance, the values from ICU are assigned to the PointSource and Location1 attributes of the new points.


Key Attributes

The OPCInt_APS Connector uses the following PI point attributes to identify and access the data source tag for a PI point:

InstrumentTag

UserInt1

The OPCInt Interface looks for the OPC ItemID either in the InstrumentTag attribute (recommended) or in the ExDesc attribute.

Note: The OPCInt_APS Connector does not look for ItemID in the ExDesc attribute.

Creatable and Synchronizable Attributes

The OPCInt_APS Connector supports the PI point attributes listed in the table in the “Supported PI Point Attributes” section. The “Sync” column indicates whether an attribute is used for point creation only or for both point creation and synchronization of existing points.

When the APS Synchronization Engine calls the APS Connector for available points, the APS Connector attempts to provide a value for every attribute in the table.

Note: Per-point synchronization settings do not apply when APS creates a PI point.

When the APS Synchronization Engine calls the APS Connector for current data source attribute values for existing PI points, the APS Connector attempts to provide a value only for the attributes with “Yes” in the “Sync” column. The APS Connector does not provide values for the attributes with “No” in the “Sync” column.

Available and Hidden Points

The APS Synchronization Engine initially categorizes data source tags that the APS Connector discovers without a corresponding point in the PI Server as available points. Using the 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 tags with no associated interface points. The APS Synchronization 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 APS Synchronization Engine constructs an array containing the key attributes of existing PI points and hidden points for the interface instance.

The APS Synchronization Engine passes the array of key attributes for existing and hidden points to the OPCInt_APS Connector in a call for available points.

The OPCInt_APS Connector queries the OPC DA Server for a list of its tag definitions. Using the key attributes, the OPCInt_APS Connector matches the points in the array of existing and hidden points from the APS Synchronization Engine with the tags in the list


Principles of Operation

from the OPC DA Server. Tags in the OPC DA Server that match a point in the array of existing and hidden points are not available points.

Unmatched tags in the OPC DA Server are candidates for available points. The OPCInt_APS Connector applies the configurable ItemID filter (see the “Filtering” section) to each candidate available point. Only the data source tags that satisfy the filter conditions are returned to the APS Synchronization Engine as available points for point creation.

Browsing the OPC DA Server Address SpaceThe OPCInt_APS Connector uses the optional OPC DA browsing interface to explore the OPC DA Server address space for Items. The OPC DA standards allow either a flat or hierarchical (that is, tree-structured) address space. In effect, a flat address space is a special case of a hierarchical address space where the root branch contains only leaves (that is, no subbranches).

The OPCInt_APS Connector starts at the topmost branch (or, root) of the tree. The OPCInt_APS Connector first calls the OPC DA Server browsing interface to return a list of any subbranches. If any subbranches are returned, each subbranch is recursively explored. After exploring all subbranches, the OPCInt_APS Connector calls the OPC DA Server browsing interface to return a list of all leaves in the branch being explored.

For every branch or leaf that the exploration process finds, the OPCInt_APS Connector calls the OPC DA Server for the full ItemID.

If a branch does not have an ItemID, the branch is simply a container for subbranches and leaves and is not an Item. That is, a branch without an ItemID is not a candidate available point.

If a leaf does not have an ItemID, the OPCInt_APS Connector assumes that the leaf is a “hint” and ignores the leaf.

The “Exploring the OPC DA Server Address Space” section contains an expanded discussion that explains how the OPCInt_APS Connector options for filtering are integrated into the exploration process.

Tag Naming Conventions

The following naming conventions are used when available points are found.

The default tag name for an available point is the OPC ItemID.

The configuration options for the OPCInt_APS Connector include a pattern for constructing the tag name. The OPCInt_APS Connector supports the following data source attributes in the tag naming pattern:

ItemID

Description

OPC Server Name

Short item name

More information is in the “Tag Name Patterns” section later in this document.

16

Point Type

The PI PointType attribute for an available point is determined from the OPC data type of the Item. The OPCInt_APS Connector contains a table with a row for each OPC data type. Each row contains individually-configured options for the corresponding OPC data type, and PI point type is one of the options. The PointType attribute for the available point for an Item is set from the PI point type option on the row for the OPC data type of the Item. The “Select OPC Data Type” section contains related information.

Updated Attributes

During each synchronization scan, the APS Synchronization Engine constructs an array containing the key attributes of existing PI points for the interface instance that are enabled for synchronization.

The APS Synchronization Engine passes the array of synchronizable existing points to the OPCInt_APS Connector in a call for updated attributes.

For each synchronizable existing point, the OPCInt_APS Connector uses the key attributes to read the current attribute values of the data source tag. The APS Connector assembles the results for each point into an array to return to the APS Synchronization Engine.

If the key attributes identify a valid data source tag, the APS Connector adds the current attribute values from the data source tag to the array of information for return to the APS Synchronization Engine.

If the key attributes do not identify a valid data source tag, the APS Connector adds an indication that the existing PI point has no tag in the data source to the array for return to the APS Synchronization Engine.

After the APS Connector processes all of the synchronizable existing PI points, the array of results is returned to the APS Synchronization Engine. The APS Synchronization Engine uses the information in the array to generate a list of PI points to update and a list of PI points to delete.

Error Handling

The OPCInt_APS Connector connects to the OPC DA Server on every call for available points and updated points. If the connection succeeds, the OPCInt_APS Connector handles errors from OPC calls as explained in this section and continues. That is, errors from the OPCDA Server after connection generally do not cause a synchronization scan to terminate abnormally. The OPCInt_APS Connector completes the call and closes the connection to the OPC DA Server before returning to the APS Synchronization Engine.

If the OPCInt_APS Connector cannot connect to the OPC DA Server, the error code from the connection call is logged and returned to the APS Synchronization Engine, which terminates the synchronization scan.

Available Points CallIn each branch of the OPC DA Server address space, the OPCInt_APS Connector calls for a list of subbranches. The OPCInt_APS Connector expects the list of subbranches to contain subbranch names that are valid parameters for calling the browsing interface to descend into a


Principles of Operation

subbranch. However, some OPC DA Servers return a subbranch list that contains names which are invalid subbranches. That is, the browsing interface returns an error when called to descend into a subbranch that the OPC DA Server returned in a subbranch list. If the browsing interface returns an error when called to descend into a subbranch, the OPCInt_APS Connector logs the error to the log file for the synchronization scan (see the “Log Files” section). The OPCInt_APS Connector continues browsing with the next subbranch in the list.

In general, the OPCInt_APS Connector continues browsing after any browsing interface call returns an error. This implementation choice allows the OPCInt_APS Connector to browse as much of the OPC address space as possible. Also, the OPCInt_APS Connector can find available points for some OPC DA Servers with questionable compliance to the OPC Data Access standards.

The disadvantage of the choice to log errors and continue is that the log file can be flooded with error messages.

Updated Attributes CallFor every existing point, the OPCInt_APS Connector calls the OPC DA Server for properties of the Item. If the OPC DA Server returns an error code, the OPCInt_APS Connector interprets the error in one of two ways:

The ItemID does not exist in the OPC DA Server. The OPCInt_APS Connector returns a “tag not found on data source” flag for the existing point, which causes the APS Synchronization Engine to apply the rule for deleted points.

Current attribute values cannot be obtained. The OPCInt_APS Connector returns a “no updates found” flag for the existing point, which causes the APS Synchronization Engine to bypass the existing point.

The OPCInt_APS Connector interprets two error codes from the Data Access Custom Interface Standard to mean that an ItemID does not exist in the OPC DA Server:

OPC_E_UNKNOWNITEMID, which the standard defines as “The item is no longer available in the server address space.”

OPC_E_INVALIDITEMID, which the standard defines as “The item definition doesn't conform to the server's syntax.”

Only these two error codes are positive indications that an ItemID does not exist in the OPC DA Server. The OPCInt_APS Connector interprets all other error codes to mean that current attribute values cannot be obtained.

18

Chapter 3. Installation, Upgrading, and Uninstallation Instructions

Installation Instructions

APS must be installed on the same computer as the OPCInt_APS Connector.

The OPCInt_APS Connector requires the Microsoft .NET 3.5 Framework or a later version. If not already installed on this computer, the Microsoft .NET 3.5 (or later) Framework is downloadable from either Microsoft or OSIsoft. Microsoft redistributables that support OSIsoft applications are available from OSIsoft in Prerequisite Kits. The Prerequisites Kits page on the OSIsoft Technical Support web site provides more information.

Attention: The default APS installation runs the APS Synchronization Engine under the local system account. In two particular situations related to OPC, the local system account may not be allowed to connect to the OPC DA Server. In these cases, the account that runs the APS Synchronization Engine must be changed as described in the “Configure Connection to OPC Server” section.

The local system account may not have adequate privileges to connect to the OPC DA Server in the following situations:

the OPC DA Server is on a remote node. DCOM is used to connect to a remote OPC DA Server and the local system account of one computer is typically not permitted DCOM access to remote computers.

the OPC DA Server is local but has its own authentication requirements for local users. For example, the DeltaV OPC DA Server has access controls that allow only designated users to connect and, therefore, may not permit connections from the local system account.

The OPCInt_APS Connector setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and later.

To install, run the OPCInt_APS_#.#.#.#.exe installation kit.

Note: This installation kit installs only the OPCInt_APS Connector, not the OPCInt Interface or APS.


http://techsupport.osisoft.com/Products/Prerequisite+Kits/Prerequisite+Kits+Overview.htm

Installation Checklist1. Log on as a user with Administrator privileges.

2. Install PI AutoPointSync, if it is not already installed. (The APS installation kit also contains the PI SDK, PI API, and PI ICU. If necessary, the APS installation kit will install or upgrade these components.)

Caution: Installing PI APS can upgrade PI API and PI SDK, which may stop operational interfaces on the computer. If installation stops any interfaces, the interfaces must be manually restarted.

3. Run OPCInt_APS_#.#.#.#.exe to install the OPCInt_APS Connector.

Upgrading Instructions

For information on the current version of the OPCInt_APS Connector, see the following techsupport.osisoft.com web page:

OPCInt Interface Details

The same OPCInt_APS_#.#.#.#.exe installation kit is used for either an initial installation or upgrading an existing installation of the OPCInt_APS Connector.

Upgrading Checklist1. Log on as a user with Administrator privileges, preferably the same user who

originally installed the OPCInt_APS Connector.

2. If the APS Configuration Utility is running, exit from the program.

3. Stop the APS Synchronization Engine. The most common ways of stopping the APS Synchronization Engine are from the Services utility or from a command window. For convenience, the Services utility or command window can be left open and used later to restart the APS Synchronization Engine.

If using the Services utility, scroll to PI APS Synchronization Engine in the right pane and click on that item to select it. Then, click Stop on the Actions menu or toolbar.

If using a command window, enter:net stop piapsengine

4. Run the installation kit.

5. Restart the APS Synchronization Engine.

If using the Services utility, click Start on the Actions menu or toolbar.

If using a command window, enter:net start piapsengine


http://techsupport.osisoft.com/TechSupport/NonTemplates/InterfaceDetails.aspx?ifname=OPC%20DA%20Interface&if_platform=NTI

Uninstallation Instructions

To uninstall the OPCInt_APS Connector:

1. Review the interface instances that are registered with APS. Unregister all interface instances that are associated with the OPCInt_APS Connector.

2. If the APS Configuration Utility is running, exit from the program.

3. Log on as a user with Administrator privileges, preferably the same user who originally installed the OPCInt_APS Connector.

4. Stop the APS Synchronization Engine. The most common ways of stopping the APS Synchronization Engine are from the Services utility or from a command window. For convenience, the Services utility or command window can be left open and used later to restart the APS Synchronization Engine.

If using the Services utility, scroll to PI APS Synchronization Engine in the right pane and click on that item to select it. Then, click Stop on the Actions menu or toolbar.

If using a command window, enter:net stop piapsengine

5. Depending on the version of Windows:Click Start > Settings > Control Panel > Add or Remove Programs to open the Add or Remove Programs utility.

—or—Click Start >Control Panel >Uninstall a program to open the Uninstall or change a program utility.

6. Remove the following program:

o PI OPC DA (OPCInt) APS Connector

7. Restart the APS Synchronization Engine.

If using the Services utility, click Start on the Actions menu or toolbar.

If using a command window, enter:net start piapsengine


Chapter 4. Registering an Interface Instance with APS

PI AutoPointSync synchronizes the points for interface instances that are registered with APS. When an interface has multiple instances, registering one instance with APS synchronizes only the points for that specific instance. Each interface instance must be registered with APS for its points to be synchronized.

If you are not familiar with registering interface instances with 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 chapter. The “Connector-specific Configuration Control” chapter in this manual is also prerequisite reading. The “Principles of Operation” chapter is strongly recommended reading.

Note: OSIsoft emphasizes the need to read both manuals before beginning to register the first interface with APS.

If you are familiar with APS, the procedures in this section give 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


Register the Interface

Only interface instances managed by the Interface Configuration Utility can be registered with APS. If a new interface instance is being created or an existing interface instance is not managed by ICU, run ICU and add the interface instance. Refer to the PI Interface Configuration Utility and the OPC DA Interface user manuals for instructions.

Recommendation: Assign a meaningful name to the interface instance instead of accepting the default generic name.

Most interface instances are configured with a single PointSource string. If an interface instance is configured with multiple PointSource strings, however, the first string in the ICU Point Source list is the default PointSource attribute value for points created by APS. Confirm that the first PointSource string in the ICU Point Source list is the appropriate default for points created by APS.

Configure Connection to OPC ServerIf the OPC DA Interface is not installed on this computer and the OPC DA Server is on a remote node, follow the instructions in the OPC DA Interface user manual for configuring DCOM on this computer as if it were an Interface node. DCOM settings on the OPC DA Server node may also require changes to permit this computer to connect. Copy OPCTool or OPCClient from an Interface node to this computer and use the utility to verify that this computer can connect to the remote OPC DA Server.

If the OPC DA Server is on a remote node or is a local server that only allows access by designated users, the PI APS Synchronization Engine service may need reconfiguration to run as a user that is permitted to connect to the OPC DA Server. To change the account that runs the APS Synchronization Engine:

Depending on version of Windows:Click Start > Settings > Control Panel > Administrative Tools > Services to open the Services administrative utility.

—or—Click Start >Control Panel > System and Security > Administrative Tools > Services to open the Services administrative utility.

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.

Click the Log On tab to switch to the following dialog box:


Registering an Interface Instance with APS

When APS is installed, the PI APS Synchronization Engine service is configured to log on as the Local System account. For APS to synchronize with a remote OPC DA Server, change this service to log on as an account with appropriate DCOM privileges. Click This account. Enter the account (user) name in the box and the account password in the Password: and Confirm password: boxes. Click OK to put these changes into effect. Restarting the PI APS Synchronization Engine service at this time is optional. The Services administrative utility is no longer needed and may be closed.

26

Configure PI SDK Connection to PI ServerIn order for APS to synchronize points on a PI Server, you must configure PI SDK to connect to the PI Server and configure the PI Server to allow the connections from APS programs to access securable objects.

1. Run the APS Configuration and Management Utility.

2. Click SDK Connections on the Interface menu. Confirm that the server list on the PI Connections Manager dialog box contains the PI Server with the interface points that you want to synchronize. If not, use the PI Connections Manager dialog box to add the PI Server.

3. Configure PI Trusts or PI Mappings on the PI Server that allow the APS Synchronization Engine and APS Synchronization Trigger service to automatically connect. Optionally, configure a PI Trust or PI Mapping for the APS Configuration Utility. See the section “Required PI Server Configuration” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual and the PI Server documentation for more information.

4. Optionally, configure APS to use only specific PI Servers in the PI SDK Known Servers Table. The Known Servers Table is a system-wide resource that is shared by all PI SDK applications on the computer where APS runs. The default APS configuration causes APS to poll all servers in the Known Servers Table for interface instances registered with APS. However, PI Servers in the Known Servers Table for other applications may not contain interface instances registered with APS on this computer. Polling these PI Servers is unnecessary overhead for both the PI Servers and APS. The “Loading Tab” section in the PI AutoPointSync for Interfaces and PI COM Connectors user manual explains the options for limiting the PI Servers that APS polls for interface instances to synchronize.



Register the OPCInt Interface1. In the APS Configuration Utility, click Register New… on the Interface menu. The

Configure Interface or COM Connector for PI APS dialog box opens:

For details on using the Configure Interface or COM Connector for PI APS dialog box, see the “Configure Interface or PI COM Connector for PI APS Dialog Box” section in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.

2. Click the Select APS Connector arrow and select the OPCInt_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 APS Configuration Utility loads the Select an interface list with the interface instances that are not yet registered with APS.

28

4. Click the Select an interface arrow and select a specific interface instance for registration.

5. Click Add.



Configure the Settings

Click the arrow in the Interface box and select the interface instance to configure.

Configure the APS options for the new interface instance on the dialog boxes that are opened by the following commands on the Settings menu:

Rules…

Sync Schedule…

User-set Defaults…

Connector-specific…

Review the settings on these dialog boxes because registration presets synchronization rules to non-automatic selections and the default per-point synchronization settings to disable synchronization of each point. The preset options are designed to prevent APS from changing the PI point database until explicitly enabled. Therefore, it is likely that the default settings need to be changed for individual interface instances.

Note: OSIsoft emphasizes the necessity to configure these options before enabling a new interface instance. In particular, options on the User-set Defaults dialog box 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 Configuration Control

During initial registration, you do not need to review or configure the options on the dialog boxes opened by the Sync Settings…, Debug…, Columns…, and Column Header Names… commands on the Settings menu.

30

Rules

On the Settings menu, click Rules. The Rules for interface dialog box opens:

The options on this dialog box determine how the APS Synchronization Engine handles available points, attributes of existing points that disagree with current values in the OPC DA Server, and existing points that are not configured for valid data source tags. For a full explanation of this dialog box, see section “Rules Dialog Box” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.

Note: OSIsoft emphasizes that you should initially choose the options to store the synchronization results. Carefully review the results of several synchronization scans for expected behavior before selecting any options to automatically update the PI point database.

The APS Synchronization Engine detects PI points that are not configured for valid data source tags 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 Data Source area have no effect and the APS Synchronization Engine behaves like the Do Nothing option is selected.

If the OPC DA Server does not support browsing, the OPCInt_APS Connector cannot obtain a list of OPC Items to compare with the existing points in PI. In this case, select the Skip search for new points option in the Points Not in PI area.



Synchronization Schedule

On the Settings menu, click Sync Schedule. The Synchronization Schedule for interface dialog box opens:

This dialog box configures:

Automatic scheduling of synchronization scans by the APS Synchronization Engine.

Events that automatically initiate a synchronization scan.

32

For a full explanation of this dialog box, see section “Synchronization Schedule Dialog Box” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.

Note: Even though this dialog box configures automatic synchronization scans, the handling of differences between PI points and data source tags is still subject to the settings on the Rules dialog box. The rules may not necessarily be automatic.

The Synchronization Schedule area configures whether the APS Synchronization Engine initiates synchronization scans for the interface instance on a periodic schedule. If Synchronize automatically using the following schedule is selected, the Period boxes specify how often the APS Synchronization Engine runs a synchronization scan for the interface instance.

Note: If you select Synchronize automatically, the first synchronization starts immediately when the interface instance is enabled.

The Do not synchronize automatically button prevents periodic scheduling of synchronization scans for the interface instance. When this button is selected, synchronization scans only occur when initiated by clicking Sync Now on the toolbar or by the APS Synchronization Trigger service.

The options in the Synchronization Trigger area configure and display the conditions that the APS Synchronization Trigger service monitors. When the condition for a trigger occurs, the APS Synchronization Trigger service notifies the APS Synchronization Engine that a synchronization scan is needed.

Note: Unless periodic scheduling or synchronization triggers are configured, you must click Sync Now on the APS Configuration Utility toolbar to start a synchronization scan.

User-set Defaults

On the Settings menu, click User-set Defaults. The User-set Defaults for interface dialog box opens. The User-set Defaults dialog box contains tabs that switch between two sets of options. The Tag Naming and Tag Selection tabs are unavailable because the OPCInt_APS Connector does not support these features.

For a full explanation of the User-set Defaults for interface dialog box, see section “User-set Defaults Dialog Box” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual.



Security & Archive SettingsOn the User-set Defaults for interface 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 APS creates a PI point for an available point, the attribute default values from this tab are merged with the attributes from the APS Connector. If the APS Connector provides a value from the data source for any of these attributes, the value from the data source is used.

The attribute default values from this tab are not used to synchronize existing points.

34



Initial Sync MasksOn the User-set Defaults for interface dialog box, click the Initial Sync Masks tab:

36

When APS encounters an existing point for the first time and the existing point does not have per-point synchronization settings, APS assigns the default settings in the Existing PI Points area to the point. The settings in this area are only used in the following situations:

On the first synchronization scan for an interface instance that has existing points when the interface instance is registered with APS.

If the APS Configuration Utility loads an existing point into the grid area of the main window and the existing point does not have per-point synchronization settings.

After points are added to an interface instance by tools other than APS.

After synchronization settings are assigned to an existing point, changes made to the settings in the Existing PI Points area do not affect the per-point synchronization settings that were originally assigned.

The APS Synchronization Engine assigns the per-point synchronization settings in the Available Points area to PI points that it creates automatically or the APS Configuration Utility assigns these settings to PI points that it creates under user control.

Note: The per-point synchronization settings assigned to created points control the attributes that can be edited on subsequent synchronization scans. All attributes from the APS Connector are used for point creation. That is, the per-point synchronization settings do not apply to point creation.

Both areas contain a list of the synchronizable attributes supported by the APS Connector and two options under Point is sync’d by APS. The Point is sync’d by APS: options select the master synchronization setting assigned to a point. When an interface is registered, the initial Point is sync’d by APS: selections default to No. These defaults were chosen to ensure that the APS Synchronization Engine does not synchronize any points until explicitly enabled. The master synchronization setting for a point must be Yes for the APS Synchronization Engine to synchronize any attributes.

Note: The Point is sync’d by APS options determine the master synchronization setting for a point. The default setting is No, which prevents the APS Synchronization 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 APS Connector. The settings for individual attributes can be toggled by clicking the check boxes in the list.



Connector-specific Options

The OPCInt_APS Connector has additional configuration options. On the Settings menu, click Connector-specific to open the PI APS Connector Control dialog box:

The “Connector-specific Configuration Control” chapter in this document provides a detailed discussion of the options on this dialog box.

38

Enable Synchronization

1. The APS Synchronization 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 figure, then the APS Synchronization Engine is enabled and no action is required. Otherwise, click Enable Sync Engine to enable the APS Synchronization Engine.

2. When an interface instance is registered with 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 APS Connector is enabled for the interface instance. Confirm that configurations of Rules, Sync Schedule, and User-set Defaults are appropriate for your needs before enabling the APS Connector.

Click the Tools menu. If no check mark appears by the Enable APS for Interface command as shown in the following figure, click Enable APS for Interface to enable synchronization for the interface instance.


Chapter 5. Connector-specific Configuration Control

The OPCInt_APS Connector includes a connector-specific configuration control. This control configures options that affect operation of the OPCInt_APS Connector.

Access the configuration control from the APS Configuration Utility. In the APS Configuration Utility, select the interface instance to configure. On the Settings menu, click Connector-specific… to open a dialog box that contains the connector-specific control.


Select OPC Data Type

Items in the OPC DA Server can have various data types, and each data type that is supported by OPC DA can be selected from the Select OPC Data Type: list. Boxes in this area configure attribute settings for available points that are returned for Items with the selected OPC data type. For Items with values that are arrays of the selected OPC data type, the number of array elements to return as available points can also be specified.

The attributes that can be specified are:

PI PointType

for digital points, DigitalState

Location2

Note: The options in this area are independent for each OPC data type. Configure these options for each OPC data type that may be the type of an Item which the OPCInt_APS Connector may return as an available point.

When the data type property is read for an Item, the OPC DA Server is permitted to return VT_EMPTY to indicate that the actual data type for the Item is not yet known. If the OPC DA Server returns VT_EMPTY for the Item data type property, reading the Item value is necessary to determine the actual canonical data type. Reading the Item value requires several OPC calls and may be expensive for both the OPCInt_APS Connector and the data source. Therefore, the OPCInt_APS Connector does not read the Item value. Instead, the OPCInt_APS Connector uses the options for the VT_EMPTY data type. For VT_EMPTY, the default PI point type option is Null. This default prevents APS from automatically creating a PI point for the available point (see the “PI Point Type” section). However, the available point is stored in the Available Points database and is recorded in the APS log files. If an administrator takes an action that causes the OPC DA Server to acquire the OPC data type (for example, by using a utility provided with the OPC DA Server or by reading the Item value with a general utility like OPCTool or OPCClient), the next synchronization scan will see the actual canonical data type and return a revised available point with a new PointType attribute value. Alternatively, an administrator can choose a PI point type for the available point and create a PI point with a point-creation utility other than APS.

If the PI point type option for VT_EMPTY is changed to any choice other than Null, all available points for Items with unknown actual OPC data type are returned with this PI point type. Therefore, the PI point type must be appropriate for any Item. For example, if all Items in the OPC DA Server are integer or floating-point types, changing the PI point type option to float32 for VT_EMPTY may be acceptable. However, float32 is not a workable default if any Items have non-numeric types (for example, string or date).

PI Point TypeThe PI Point Type: list specifies the PI PointType to assign to all available points that are returned for Items of the selected OPC data type.

If the PointType attribute is Null for an available point, the OPCInt_APS Connector flags the available point as “log only”. This flag causes the APS Synchronization Engine to temporarily change the rule for handling the available point to Store in Available Points database. As a result, the APS Synchronization Engine never creates a PI point for an available point with Null as the PointType attribute. The available point is stored in the Available Points database and is recorded in the APS log files.


Digital StateIf the PI Point Type is Digital, the Digital State: box selects the name of an existing digital state set to assign to all available points that are returned for Items with the selected data type. The Digital State: list is loaded from the PI Server when this dialog box is opened. If a suitable digital state set is not in the list, use other PI tools to create the digital set. Then, close and reopen this dialog box to reload the Digital State: list.

Location2The Location2: box specifies the value assigned to the Location2 attribute for available points that are returned for Items with the selected data type. The OPC DA Interface uses the Location2 attribute to select various forms of special handling for the data value; consult the OPC DA Interface user manual for information on selecting values for Location2.

Number of Array ElementsThe Number of Array Elements: box specifies the total number of available points that the OPCInt_APS Connector returns for an OPC Item that has an array value. For example, if the Number of Array Elements: box contains 10, then 10 available points, corresponding to the first 10 elements of the array value, are returned.

Tag Name Patterns

The tag name patterns are templates for constructing the tag name of the available point for an Item. The tag name can be constructed from any combination of OPC ItemID, OPC Short Item Name, OPC Item Description, OPC Server Name, or literal text.

Tag Name PatternThe Tag Name Pattern: box contains the basic tag name pattern that applies to all available points. The string in this box must contain one or more of the following placeholders that represent Item-specific data which is substituted into the tag name:

[i] OPC ItemID

[n] OPC Short Item Name

[d] OPC Item Description

[s] OPC Server Name

Literal text may be interspersed with these placeholders. For example, assume that the Tag Name Pattern: box contains [s]:[n]. This pattern consists of two placeholders separated by a literal colon. If the OPC Server name is “OSI.DA.1” and the short Item name is “sinusoid”, the resulting tag name for the Item would be “OSI.DA.1:sinusoid”.

If the Tag Name Pattern: box is empty, the default pattern is [i] (the ItemID).

An ItemID is the unique name for an Item in the OPC DA Server. While browsing the OPC address space, however, the name for an Item in a branch is a short name. The short name in a branch is only unique within that branch. The same short name may exist in other branches and the two short names may be different Items. To make an analogy with a computer file system, an ItemID is like a full path, which uniquely identifies a file in the file system. A short Item name is like the name of a file in a folder. A short file name is not necessarily unique in the file system because files with the same name can exist in different folders. The



“Exploring the OPC Server’s Address Space” section contains additional discussion of ItemIDs and short Item names.

The ► button following the Tag Mask Pattern: box opens a shortcut menu for inserting placeholders into the pattern. Clicking one of the commands on the shortcut menu inserts the corresponding placeholder into the pattern. If text in the Tag Mask Pattern: box is selected (that is, highlighted), the placeholder replaces the selection. Otherwise, the placeholder is inserted at the insertion point.

If the background of the Tag Mask Pattern: box is yellow, the pattern is incorrect in some way. Point to the Tag Mask Pattern: box and pause to display a ToolTip, which contains an error message.

Array Extension PatternThe Array Extension Pattern: only applies to Items that have array values. For each available point for an array-valued Item, the tag name is constructed by evaluating the Tag Name Pattern: to create a base tag name and appending the string that results from evaluating the Array Extension Pattern: for each array element.

Only one placeholder is available in the Array Extension Pattern:

[a] Array Element Index

If padding with zeros is required (for example, “0001” instead of “1”), then the minimum number of digits to pad is specified by extra “a”s inside the placeholder brackets. For example, if the placeholder is [aaaa], the array extension is “0001” for the first element in the array and “0010” for the tenth. The array index placeholder is always replaced by enough digits to represent the index. That is, [a] is replaced by more than one digit if the array index is greater than 9, [aa] is replaced by more than two digits if the array index is greater than 99, and so forth.

The Array Extension Pattern: may also contain literal text.

If no Array Extension Pattern: is specified, the default pattern is.[a] (a period followed by the array index placeholder).

The ► button following the Array Extension Pattern: box opens a shortcut menu for inserting placeholders into the pattern.

If the background of the Array Extension Pattern: box is yellow, the pattern is incorrect in some way. Point to the Array Extension Pattern: box and pause to display a ToolTip, which contains an error message.

Filtering

The OPCInt_APS Connector provides four types of filtering that restrict the Items which are accepted for available points:

Item Access

Data Type

ItemID

Branch Name

44

An Item must satisfy all of the filter criteria for the OPCInt_APS Connector to return an available point.

The Item Access: filter restricts the selection of Items by access rights. The Data Type: filter restricts the selection of Items by data type. The OPCInt_APS Connector delegates these two filters to the corresponding capabilities of the OPC DA Server browsing interface. That is, these two filters are browsing interface parameters that cause the OPC DA Server to expose only Items that satisfy the filter criteria.

The ItemID Filter: restricts the selection of Items by ItemID. For the OPCInt_APS Connector to return an available point for an Item, the ItemID must match the pattern in the ItemID Filter: box. If the box is empty, all ItemIDs satisfy this filter. The syntax of the pattern is explained later in this document.

The Branch Filter: restricts the branches that are explored. If a branch does not satisfy the filter criteria in the Branch Filter: box, the leaves and subbranches in the branch are ignored. If the box is empty, all branches satisfy this filter.

The browsing interface returns “short” names that may not be ItemIDs. ItemIDs are unique Item identifiers within the OPC DA Server. Short names are only unique in a branch. The same short name can occur in multiple branches and, depending on the OPC DA Server, may refer to different Items.

The distinction between short names and ItemIDs is significant because filtering in the OPC DA Server operates on short names. Filtering of branches is delegated to the OPC DA Server and, therefore, operates on short branch names. However, filtering of Items is done by the OPCInt_APS Connector and operates on the ItemIDs.

Consider the OPCTool view of one OPC DA Server address space hierarchy in the following figure:

Figure 1. Example OPC Address Space for a PLC

OPCTool represents a hierarchical address space as a tree similar to the way Windows Explorer represents a hierarchy of folders and files. Each line in the tree view is either a branch or a leaf. The presence of an expand or contract button indicates a branch. In the tree shown in Figure 1, Channel_1, Device_1, _System, and _Hints are branches. The remaining lines indicate leaves. Generally, leaves in the OPC DA address space are Items. Branches are containers for leaves and subbranches, and a branch also may be an Item.

Observe that the browsing interface is permitted to return short names, which are not ItemIDs. For the OPC DA Server in Figure 1, the ItemID for the Tag_1 leaf is Channel_1.Device_1.Tag_1. The ItemIDs in this OPC DA Server are directly related to



the path from the root to the leaf. However, this behavior is not required by the OPC Data Access Custom Interface Standard and not all OPC DA Servers follow this pattern.

The OPC address space shown in Figure 1 also illustrates that an OPC DA Server is permitted to return leaves that are “hints” (that is, not Items). This OPC DA Server chose to list its hints under the appropriately-named _Hints branch. In general, hints can appear under any branch in the address space and may be mixed with actual items in a common branch. The K0.0-K9999.0...K0.15-K9999.15 leaf (and the partially visible leaf below it) is a hint. This hint indicates that this particular OPC DA Server supports Items with short names K0.0, K0.1, …, K1.0, K1.1, …, K9999.15, but the Items are not individually listed by the browsing interface. As noted earlier in the “Cannot Construct Available Points from Hints” section, the structure (syntax) of hint strings is not standardized, making it impossible for the OPCInt_APS Connector to expand hints into a list of actual Item names.

For the purpose of illustrating the variety in OPC DA Servers, the following figure shows the OPCTool view of the address space from a second OPC DA Server implementation:

Figure 2. Example OPC Address Space for a DCS

From the browsing view of short names, the two OPC DA Servers appear quite similar. When the actual ItemIDs for leaves are examined, the differences become apparent. For example, the ItemID for the CV leaf in this OPC DA Server is BFO_TEST/AI1/ABNORM_ACTIVE.CV. Unlike the OPC DA Server in Figure 1, all branches in the path from root to leaf are not part of the ItemID. Another difference is the delimiters used between the branch names.

Exploring the OPC DA Server Address SpaceThe OPCInt_APS Connector explores the OPC DA Server address space by starting at the topmost branch (or, root) of the tree. The OPCInt_APS Connector first calls the OPC DA Server browsing interface to return a list of any subbranches. The string from the Branch Filter: box is passed to the browser interface in the filter criteria parameter of this call. the OPC DA Server returns only the names of the branches whose short names satisfy the Branch Filter: string.

The OPC Data Access Custom Interface Standard does not require an OPC DA Server to implement filtering or use any specific syntax for the filter string. However, the standard recommends that OPC DA Servers provide the * and ? wildcards with their customary meanings: * matches zero or more characters and ? matches any single character. Since the interpretation of the Branch Filter: string is defined by each OPC DA Server implementation, consult the documentation for the specific OPC DA Server to determine how to specify a filter for branches. However, the standard does specify that an empty Branch Filter: string causes the browsing interface to return all subbranches (that is, no filtering).

46

Note: The Branch Filter: box only supports a single filter string that is uniformly applied at all levels in the OPC address space hierarchy. Therefore, except in very limited cases, the Branch Filter: is unusable and the box should be empty (no branch filter).

If any subbranches are returned, each subbranch is recursively explored. Before exploring a subbranch, the OPCInt_APS Connector determines if the subbranch itself is also an OPC Item. If the subbranch is an Item, the subbranch ItemID must satisfy the ItemID Filter: as described below. Observe that the OPC DA browsing interface does not apply the Item Access: or Data Type: filters to branches. Therefore, a branch that is also an Item becomes a candidate available point even though the branch may not have the specified access rights or data type.

After exploring all subbranches, the OPCInt_APS Connector calls the OPC DA Server browsing interface to return a list of all leaves in the branch being explored. The Item Access: and Data Type: filters are parameters to this call to the OPC DA Server. Unlike the earlier request for subbranches, the OPCInt_APS Connector always sends an empty filter string when requesting leaves in the current branch. That is, the OPCInt_APS Connector expects the OPC DA Server to return all leaves in the current branch that satisfy the Item Access: and Data Type: filters. The OPCInt_APS Connector then implements its own filtering of the leaves.

For every branch or leaf that the exploration process finds, the OPCInt_APS Connector calls the OPC DA Server for the ItemID. If this call returns an error, the branch or leaf is not an Item, and the OPCInt_APS Connector continues exploring. Generally, a leaf is an Item unless the leaf name is a hint. The Data Access Custom Interface Standard allows each OPC DA Server to choose whether or not branches are Items in addition to being containers for subbranches and leaves.

The OPCInt_APS Connector applies the ItemID Filter: to the ItemID before accepting the Item as an available point. For the visible leaves in Figure 1, the ItemID filter is applied to ItemIDs “Channel_1.Device_1.Bool_1”, “Channel_1.Device_1.Tag_1”, “Channel_1.Device_1.Tag_2”, and “Channel_1.Device_1.Tag_3”. Since the ItemID is used for ItemID filtering, branch names that are part of the ItemID can be used in ItemID Filter: patterns. That is, an ItemID Filter: pattern that matches strings that contain “Device_1” matches all Items under the Device_1 branch.

Recommendation: Use OPCTool, OPCClient, or another OPC browsing utility to examine and understand the ItemID naming convention of the OPC DA Server.

When configuring ItemID Filter, be aware that ItemIDs from the OPC DA Server are matched with the filter expression.

ItemID Filter SyntaxThe syntax of the string in the ItemID Filter: box supports more complex pattern matching than simple wildcards. The ItemID Filter: box can be empty, which accepts all candidate ItemIDs as available points. A string in the ItemID Filter: box can contain either a single pattern or a comma-separated list of patterns. The OPCInt_APS Connector matches the ItemID of each candidate Item with the patterns in this list, from left to right. The first successful match accepts the Item as an available point. If the ItemID fails to match all of the patterns, the Item is rejected as an available point.



The individual ItemID Filter: patterns are regular expressions. Regular expressions are similar to the familiar Windows file name matching patterns composed of literal characters and the * and ? wildcard operators. However, regular expressions have many more operators, which make them much more flexible and powerful than simple wildcard patterns. The following characters are regular expression operators:

. * + ? \ ^ $ { [ ( ) |

The meanings of commonly-used operators are briefly discussed in this section. Awareness of the complete list of operator characters is necessary because the operator characters must be escaped to match the character literally. The escape operator is \ (backslash). Backslash followed by any other operator, including backslash itself, causes the character following backslash to be taken literally instead of as an operator. For example, the regular expression abc\+xyz matches any string that contains “abc+xyz”. Any of these strings match: “123abc+xyz”, “123abc+xyz456”, “abc+xyzzzzz”, and so forth. In contrast, the regular expression abc+xyz does not match any of these strings (because unescaped + is a regular expression operator, not a literal “+”).

Because individual patterns are separated by commas, a comma cannot be used as a literal character in any of the individual patterns. However, the character escape \x2C (where 2C is the hexadecimal character code for comma) in a regular expression matches comma in an ItemID.

If the background of the ItemID Filter: box is yellow, the filter string is invalid. Point to the ItemID Filter: box and pause to display a ToolTip, which contains an error message. The error message is directly from the .NET regular expression parser. Unfortunately, the error messages are frequently cryptic (that is, difficult to interpret).

Note: Because the wildcard characters * and ? are also regular expression operators, a wildcard pattern can successfully parse as a regular expression but does not match as intended.

The regular expression operators that are equivalent to wildcards are:

.* matches zero or more characters (like the * wildcard)

. matches any one character (like the ? wildcard)

\. matches a literal “.”

.+ matches one or more characters

The * operator matches zero or more of the preceding character (which differs from the common wildcard interpretation). Similarly, the + operator matches one or more of the preceding character. Thus, these operators are always part of a two-character sequence. For example, the regular expression A.*Z matches any string that contains an “A”, followed by zero or more characters, followed by “Z”. The regular expression abc+xyz matches “ab”, followed by one or more “c”s, followed by “xyz”.

Without explicit operators to anchor the regular expression to the beginning or end of the candidate string, a regular expression match succeeds if any substring of the candidate string matches the regular expression. Recall that the example regular expression abc\+xyz matches “123abc+xyz456”. That is, the default interpretation of a regular expression behaves as if .* were at the beginning and end of the regular expression. When used as the first character in a regular expression, the ^ operator overrides the implicit .* at the beginning of

48

the regular expression. Thus, matching is anchored to the beginning of the candidate string. For example, the regular expression ÂBC matches any string that begins with “ABC”.

When used as the last character in a regular expression, the $ operator overrides the implicit .* at the end of the regular expression. Thus, the regular expression is anchored to the end of the candidate string. For example, the regular expression XYZ$ matches any string that ends with “XYZ”.

The comparison of literal characters in a regular expression is case sensitive. Lower case characters in the regular expression do not match the corresponding upper case characters in a candidate string and vice versa. The case of ItemIDs in an OPC Server is usually known, and regular expressions can be written with the same case. If case-insensitive matching is needed, enclose the regular expression in the following operators:

(?i:regular expression)

For example, the regular expression (?i:abcXYZ) matches any string that contains “abcxyz”, “ABCXYZ”, “AbCxYz”, or any other permutation of case.

As noted earlier, a wildcard pattern can parse successfully as a regular expression. However, the pattern will not match as expected. For example, the wildcard pattern .Value* means: match strings that begin with “.Value” followed by anything. However, the same .Value* as a regular expression means: match strings that contain “Valu” preceded by at least one character and followed by zero or more “e”s.

Note: The patterns in the ItemID Filter box must be regular expressions.

The following table shows the regular expressions that are equivalent to many common wildcard patterns. The table also provides additional examples.

Equivalent Regular Expressions and Wildcard Patterns

Regular Expression Wildcard Pattern

Match strings containing “KLM”

KLM *KLM*

Match strings beginning with “ABC”

ÂBC ABC*

Match strings ending with “XYZ”

XYZ$ *XYZ

Match strings beginning with “ABC” and ending with “XYZ”

ÂBC.*XYZ$ ABC*XYZ

Match only “A2Z” Â2Z$ A2Z

Match strings beginning with “BASE.”, including literal dot

^BASE\. BASE.*

Match strings containing “BASE” followed by zero or more characters and a literal dot (not required to be at end of string)

BASE.*\. *BASE*.*

Match strings ending with “.EXT”

\.EXT$ *.EXT



Complete reference information on regular expressions can be found at http://msdn.microsoft.com by searching for the topic “Regular Expression Language Elements”. Include the double quotation marks in the search box.

Pause x milliseconds after every n OPC operations

The APS Synchronization Engine provides options that can be configured to reduce the rate of calls to the OPC DA Server while updating existing points. When searching for available points, however, the APS Synchronization Engine cannot provide a similar restraint on the rate of calls to the OPC DA Server. The reason is that the APS Synchronization Engine calls the OPCInt_APS Connector for a group of available points. The APS Connector does not return to the APS Synchronization Engine until a group of available points is collected. Normally, the existing points for an interface instance are mostly or entirely in synchronization with the Items in the OPC DA Server. Therefore, very few or no available points are found. In this case, the OPCInt_APS Connector browses the entire OPC DA Server address space before returning to the APS Synchronization Engine, and the APS Synchronization Engine has no opportunity to restrain the rate of calls to the OPC DA Server.

The OPCInt_APS Connector provides an option to pause periodically, which restrains the rate of calls to the OPC DA Server. The first box configures the number of milliseconds to pause. The second box configures the number of OPC operations between pauses. This option is primarily intended to restrain the rate of calls to the OPC DA Server while searching for available points. However, the OPCInt_APS Connector also applies this option while retrieving current attribute values for existing points.

50

http://msdn.microsoft.com/

Appendix A. Error and Informational Messages

This appendix discusses several specific errors that may be encountered with the OPCInt_APS Connector and general troubleshooting methods for resolving other problems.

Installation Problems

Symptoms of installation problems are usually noticed when the APS Configuration Utility registers the first OPCInt Interface instance. Installation problems can also occur after the OPCInt_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.

OPCInt_APS failed to register HRESULT = -2147024769

This message from the Windows Installer indicates that one or more prerequisite DLLs are missing. Confirm that the appropriate prerequisite kit for the Windows version is installed.

OPCInt_APS does not appear as an installed connector in the APS Configuration Utility

The APS Connector must appear as “OPCInt_APS” in the Installed PI APS Connectors dialog box (Installed Connectors… on the Tools menu) and in the Select APS Connector: list in the Configure Interface or COM Connector for PI APS dialog box (Register New… on the Interface menu). If “OPCInt_APS” does not appear in these dialog boxes, OSIsoft.OPCInt_APS.dll is not registered.

To register OSIsoft.OPCInt_APS.dll, follow the instructions in the “Registering Assemblies with COM” section.

Error when opening the Connector-specific Control

If a message similar to the following is displayed when an Interface is selected and Connector-specific… is clicked on the Settings menu, OSIsoft.OPCInt_APS_Config.dll is not registered.


To register OSIsoft.OPCInt_APS_Config.dll, follow the instructions in the “Registering Assemblies with COM” section.

“Error from CoCreateInstanceEx” messages from the APS Synchronization Engine

Messages similar to the following appear in the synchronization logs or pipc.log files:PIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx. -2147221164: A specified class is not registered in the registration database. from call ptrAPSC.CreateInstance(OPCInt_APS.PIAPSConnector) (for strider,Sandbox%OPCInt2) in LoadAPSRegisteredConnectors - will log every 100 errorsPIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx. -2146233054: from call ptrAPSC.CreateInstance(OPCInt_APS.PIAPSConnector) (for strider,Sandbox%OPCInt2) in LoadAPSRegisteredConnectors - will log every 100 errorsPIAPSEngine.exe>PI-APS> Error from CoCreateInstanceEx. -2147024894: from call ptrAPSC.CreateInstance(OPCInt_APS.PIAPSConnector) (for strider,Sandbox%OPCInt2) 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(OPCInt_APS.PIAPSConnector). These messages indicate that OSIsoft.OPCInt_APS.dll is not registered.

To register OSIsoft.OPCInt_APS.dll, follow the instructions in the “Registering Assemblies with COM” section.


Upgrade Problems

Following an upgrade, if the logs indicate that the old version of the OPCInt_APS Connector is still being used, the APS Synchronization Engine needs to be stopped and restarted. When the APS Synchronization Engine starts, it loads copies of the APS Connectors for all registered interface instances into its virtual memory. After an APS Connector is loaded, the APS Synchronization Engine uses the copy in its virtual memory until the APS Synchronization Engine service is stopped. Thus, if an APS Connector is upgraded while the APS Synchronization Engine is running, the new version will not be used until the APS Synchronization Engine is restarted. Follow the steps in the “Upgrading Checklist” section to restart the APS Synchronization Engine.

GetObject(OPCInt_APS.PIAPSConnector) error when opening the Installed PI APS Connectors dialog box in the APS Configuration Utility

A GetObject error indicates that the ProgID for the OPCInt_APS Connector is registered. However, the APS Configuration Utility could not load the OPCInt_APS Connector DLL. One possible cause of a GetObject error after upgrading from OPCInt_APS version 1.1.0.12 or earlier is that two configuration files were not removed by the upgrade. OPCInt_APS version 1.1.0.12 or earlier requires .NET 1.1 Framework. On a computer where multiple versions of the .NET Framework are installed, applications use the latest version of the .NET Framework by default. To override this default for the APS Configuration Utility and the APS Synchronization Engine, the OPCInt_APS 1.1.0.12 installation kit installed configuration files PIAPSConfig.exe.config and PIAPSEngine.exe.config in the %PIHOME%\APS folder. These configuration files cause the respective applications to specifically use the .NET 1.1 Framework, which is necessary to dynamically load OPCInt_APS 1.1.0.12 or earlier. Later versions of OPCInt_APS depend on .NET 3.5 or later. Consequently, the old configuration files prevent the APS Configuration Utility or Synchronization Engine from loading the .NET 3.5 or later Framework, which is required for later versions of OPCInt_APS. If the configuration files are present on a computer where OPCInt_APS 1.2.0.0 or later is installed, clicking Installed PI APS Connectors on the Tools menu in the APS Configuration Utility causes a GetObject error. The error number and exact message depend on the version of Windows.

On Windows XP, the error message is “GetObject(OPCInt_APS.PIAPSConnector) Error 0x80131700: Automation error”.

On Windows 7, the error message is “GetObject(OPCInt_APS.PIAPSConnector) Error 0x80070002: Automation error The system cannot find the file specified.”

If a GetObject error occurs when opening the Installed PI APS Connectors dialog box, look for files PIAPSConfig.exe.config and PIAPSEngine.exe.config in the %PIHOME%\APS folder. If either configuration file exists, delete, rename, or move the configuration file to another folder.

Operational Problems

Log FilesWhen the APS Synchronization Engine performs a synchronization scan for an interface, it creates a log file for that synchronization scan. If errors occur during the synchronization


Error and Informational Messages

scan, the APS Synchronization Engine writes error details to the pipc.log file and usually also writes an error message into the log file for the synchronization scan. The log files created for the synchronization scans must be routinely monitored. If indications of errors are found, additional information may be available in pipc.log or the PI message log (SDK log). The 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.

In normal operation, the OPCInt_APS Connector rarely logs messages. If APS version 1.2.4.0 or later is installed, the OPCInt_APS Connector writes all messages to the synchronization log. For significant errors, the message is also written to the PI message log.

When the OPCInt_APS Connector encounters an error that it cannot handle, it returns an error code and description string to the APS Synchronization Engine, which the APS Synchronization Engine usually writes to both the pipc.log file and the log file for the synchronization scan.

The APS Configuration Utility typically reports errors and unusual conditions in the status bar on the main window or a message area on a dialog box. The APS Configuration Utility also writes a message to the PI message log (not pipc.log) for error conditions.

Enable Debug LoggingThe OPCInt_APS Connector has additional logging capabilities that can assist in determining the cause of a problem. By default, the additional logging is disabled. The file where additional log messages are written depends on the version of the APS Synchronization Engine.

Beginning with APS Synchronization Engine version 1.2.4.0, the log file for the synchronization scan is opened with modes that permit the APS Connector to append messages to the synchronization log. If the APS Synchronization Engine is version 1.2.4.0 or later, the OPCInt_APS Connector writes additional log messages to the synchronization log.

If the APS Synchronization Engine is earlier than 1.2.4.0, a new debug log file is created by the OPCInt_APS Connector for each synchronization scan. The connector-specific log files are created in the interface instance folder %PIHOME%\APS\interfaceHost_shortIFname_PIserver and are named OPCInt_APS_timestamp.log where the timestamp in the file name is the same timestamp as in the synchronization log created by the APS Synchronization Engine. Unlike the synchronization log files, which the APS Synchronization Engine can be configured to periodically remove, nothing automatically deletes the debug log files created by the OPCInt_APS Connector.

Note: If additional logging for the OPCInt_APS Connector is enabled and the Synchronization Engine is earlier than version 1.2.4.0, the log files must be manually managed (that is, removed).

To enable additional logging in the OPCInt_APS Connector, run the APS Configuration Utility. Select the OPC DA Interface instance to enable for additional logging. Click Debug… on the Settings menu to open the following dialog box:

54

In the PI APS Connector Debug Setting area, enabling either Retrieving updated attributes (GetUpdatedAttributes) or Retrieving Available points (GetAvailablePoints) causes the OPCInt_APS Connector to write messages that trace significant operations, including codes and messages from any errors, to a log file. The two check boxes independently enable additional logging during the two phases of synchronization. The other check boxes in this area are not used by the OPCInt_APS Connector, but they are used by the Synchronization Engine itself.

Operational ErrorsFor operational errors that are common to all APS Connectors, see “Appendix A: Troubleshooting” in the PI AutoPointSync for Interfaces and PI COM Connectors user manual. The following list contains known error messages that are specific to the OPCInt_APS Connector, their explanations, and steps for resolving the circumstances that caused those messages to be displayed.

ItemID Filter Pattern Errors

Using wildcard pattern notation in the ItemID Filter: box in the connector-specific configuration control is a common configuration error. The “ItemID Filter Syntax” section discusses the patterns used in the ItemID Filter: box, which are regular expressions. The following message appeared in the synchronization log when the wildcard pattern “*.Value*” was mistakenly used as an ItemID Filter:ItemID Filters: "*.Value*" parsing "*.Value*" - Quantifier {x,y} following nothing.


Error and Informational Messages

This specific message is complaining about the leading * operator in regular expression *.Value* because the regular expression * operator (which is a “quantifier”) specifies zero or more matches of the preceding character and there is no preceding character.

Unfortunately, not all misuses of * and ? as wildcards are detected when a regular expression is parsed. For example, the trailing * in regular expression *.Value* does not result in an error because e* is a valid regular expression, which matches zero or more “e”s. If the intention of this pattern is to match any ItemID that contains “.Value”, the regular expression is incorrect in two other respects: 1) the “.” is an operator that matches any character instead of a literal dot, and 2) “e*” matches zero or more “e”s instead of “e” followed by zero or more of any characters.

If an error message contains the word “parsing” or any of the pattern strings from the ItemID Filter: box, check for errors in the regular expression. The table in the “ItemID Filter Syntax” section shows the regular expressions that are equivalent to several common wildcard patterns.

Error code -2147024894 in synchronization log

One cause of the following message is missing assemblies in the Global Assembly Cache (GAC), particularly OSIsoft.OSIDAAuto.OPCInt_APS> Error -2147024894: Unknown Error Code. (ptrAPSC->GetUpdatedAttributes in PerformASynchronization)

The “Installing Assemblies into the GAC” section explains how to check for the required assemblies in the GAC and installing missing assemblies.

56

Appendix B. Resolving Installation Problems

The installation of APS should install all prerequisite PI SDK and APS .NET assemblies into the Global Assembly Cache (GAC). The installation of the OPCInt_APS Connector should install and register the OPCInt_APS Connector with COM. If missing or unregistered assemblies are identified as the likely cause of a symptom in the “Installation Problems” section, the procedures in this appendix deal with the most common problems.

Installing Assemblies into the GAC

The OPCInt_APS Connector requires specific versions of eight prerequisite assemblies in the GAC. To verify that the prerequisite assemblies are installed in the GAC:

Open Windows Explorer.

Type %systemroot%\assembly in the address bar.

A view of the GAC opens:


Examine the list of global assemblies for the eight assemblies that are outlined in the figure above. Look for the eight assembly names and confirm that the exact versions shown in the figure are in the GAC. The Processor Architecture column must be blank or x86 (32-bit version).

The .NET Global Assembly Cache is designed to allow multiple versions of the same assembly to coexist. On a 64-bit version of Windows, 32-bit (x86 processor architecture) and 64-bit (AMD64 processor architecture) implementations of an assembly may exist with the same version. Other versions of these eight assemblies can be present with no adverse consequences. For example, version 1.3.0.0 (.NET 2 or later) and version 1.2.0.0 (.NET 1.1) of the OSIsoft.PISDK assembly can both be installed in the GAC. However, the OPCInt_APS Connector will not work if only OSIsoft.PISDK version 1.2.0.0 is in the GAC (wrong version) or if only OSIsoft.PISDK version 1.3.0.0 for AMD64 (wrong processor architecture) is in the GAC.

If the required version and processor architecture of any assembly is missing from the GAC, use the following instructions to install the missing assemblies.

Note: You must be logged in as an administrator to change the GAC.

To install a .NET Assembly into the GAC, open a second Windows Explorer window and navigate to the folder that contains a copy of the assembly. The required assemblies for the OPCInt_APS Connector are installed at the following paths:


%PIHOME%\PISDK\OSIsoft.PISDK.dll

%PIHOME%\PISDK\OSIsoft.PISDKCommon.dll

%PIHOME%\Library\OSIsoft.PITimeServer.dll

%PIHOME%\Library\OSIsoft.PISpt.dll

%PIHOME%\Library\OSIsoft.OSIDAAuto.dll

%PIHOME%\APS\OSIsoft.PIAPSConfig.dll

%PIHOME%\APS\OSIsoft.PIAPSCTR.dll

%PIHOME%\APS\OSIsoft.PIAPSEngine.dll

Drag the assembly from the folder and drop it in the %systemroot%\Assembly folder.

The eight prerequisite assemblies are interop assemblies, which enable a .NET application to access COM classes. In effect, an interop assembly is a link between a .NET application and one or more COM servers. Since an interop assembly is not a COM object, the interop assembly is not registered with COM. However, the COM servers that implement the type definitions in the interop assembly must be registered. Registering the underlying COM servers for the interop assemblies is beyond the scope of this document.

The GAC must also contain the OPCInt_APS Connector assemblies OSIsoft.OPCInt_APS and OSIsoft.OPCInt_APS_Config. Only one version of the OPCInt_APS Connector assemblies should be in the GAC. The file version (not the assembly version shown by the Windows explorer view of the GAC) of both assemblies should match the version of the installation kit. To see the file version of an assembly in the GAC, right-click on the assembly. Click Properties on the shortcut menu. The Version tab on the assembly Properties dialog box shows the file version.

Copies of the OPCInt_APS Connector assemblies are installed at: %PIHOME%\APS\Connectors\OPCInt_APS\OSIsoft.OPCInt_APS.dll

%PIHOME%\APS\Connectors\OPCInt_APS\OSIsoft.OPCInt_APS_Config.dll

Registering Assemblies with COM

In order for the OPCInt_APS Connector to work with the APS Configuration Utility and APS Synchronization Engine, the OPCInt_APS Connector assemblies must be registered with COM. If the Installed Connectors… dialog box in the APS Configuration Utility (Installed Connectors on the Tools menu) does not show “OPCInt_APS”, the OPCInt_APS Connector is not registered with COM.

First, confirm that the OSIsoft.OPCInt_APS assembly is in the GAC and determine its assembly version number. See the “Installing Assemblies into the GAC” section for instructions on viewing the assemblies and assembly versions in the GAC.

The OSIsoft.OPCInt_APS_Config assembly also must be in the GAC and have the same assembly version as OSIsoft.OPCInt_APS.

Normally, only one version of these two assemblies is in the GAC. If the GAC contains both assemblies and they have the same version number, continue with the following instructions to register the assemblies with COM.


Resolving Installation Problems

Note: You must be logged in as an administrator to register assemblies with COM.

Run cmd to open a command window. If the version of Windows has User Account Control (UAC, Vista or later versions of Windows), run cmd as administrator.

Enter the following command to change the working directory:cd %PIHOME%\APS\Connectors\OPCInt_APS

To register the assemblies for the OPCInt_APS Connector from the GAC, run the reg_OPCInt_APS script with the assembly version number from the GAC as a parameter, for example:reg_OPCInt_APS 1.2.0.0

Be careful to use the assembly version number from the GAC as the parameter to this script. The script will fail if assemblies with the same version as the script parameter are not in the GAC.

60

Appendix C. OPC Server Surveys

This appendix contains a list of OPC DA Servers that have been surveyed for OPC properties that the OPCInt_APS Connector uses as values for PI point attributes. The information in this appendix was gathered by running a utility that explores the capabilities of an OPC DA Server to assess its ability to work with the OPCInt_APS Connector. Based on the results from this utility, the tables in this appendix predict how the OPCInt_APSConnector will behave with the OPC DA Servers. In most cases, actual results of using the OPCInt_APS Connector with these OPC DA Servers are not known.

Attention: The information in this appendix is not a commitment that the OPCInt_APSConnector will behave as predicted.

The entries in this appendix are alphabetic by OPC DA Server vendor.

ABB

OPC DA Server for AC 800M

ProgID ABB.AC800MC_OpcDaServer.3

Version 4.0.0

Vendor Information ABB Automation Technology Products AB. OPC DA Server for AC 800M.

Sync-able Attributes none

Notes GetItemProperties call is slow (average 1 second per call)

OPC DA Server for MaestroNT

ProgID abbmaestront.opcserver.1

Version 3.3.1041

Vendor Information ABB Automation


Notes


Ascolab GmbH

ProgID ascolab.OpcDaServer.1

Version 0.9.207

Vendor Information OpcDemoServer


Notes

Beckhoff

Beckhoff TwinCAT OPC Server4

ProgID Beckhoff.TwinCATOpcServerDA

Version 4.1.60

Vendor Information Beckhoff TwinCAT OPC Server4

Sync-able Attributes DescriptorEngUnits

Notes ItemIDs can contain illegal characters for PI tag name.

CimQuest Inc.

OPC Server for Allen-Bradley Networks

ProgID CimQuestInc.IGOPCAB

Version 3.0.5

Vendor Information OPC Server For Allen-Bradley Networks

Sync-able Attributes Descriptor

Notes

Citect

ProgID Citect.OPCRemote

Version 6.10.183

Vendor Information Citect Pty Ltd


Notes


Cogent Real-Time Systems, Inc.

ProgID Cogent.OPCDataHub.1

Version 6.4.3

Vendor Information Cogent Real-Time Systems - OPC DataHub

Sync-able Attributes ZeroSpan

Notes

Cyberlogic

ProgID Cyberlogic.OPCServerDA.7

Version 7.0.5

Vendor Information Cyberlogic OPC Server

Sync-able Attributes DescriptorEngUnitsZeroSpan

Notes

Descartes Systems Sciences, Inc.

ProgID DSSI.OmniServer.2

Version 0.26.0

Vendor Information Descartes Systems Sciences, Inc.


Notes

Elipse Software Ltda.

Elipse Drivers OPC

ProgID Elipse.OPCDrivers.1

Version 1.1.19

Vendor Information Elipse Drivers OPC, 1.1.0 Build 19 Copyright © 2004-2005 Elipse Software Ltda.

Sync-able Attributes unknown

Notes Cannot find available points because browsing is not supported.


OPC Server Surveys

E3 OPC Server

ProgID Elipse.OPCSvr.1

Version 1.0.50

Vendor Information E3 OPC Server, 1.00.022 Build 50 (c) Elipse Software Ltda.


Notes

Elipse SCADA

ProgID ElipseScada.OPCSvr.1

Version 2.27.11

Vendor Information Elipse SCADA 2.27 (c) Elipse Software Ltda.


Notes

Emerson Process Management

DeltaV

ProgID opc.deltav.1

Version 9.3.5181

Vendor Information Fisher-Rosemount Systems Inc. DeltaV OPC Data Server


Notes ItemIDs can appear more than once in the browse tree resulting in duplicate available points.

PROVOX

ProgID OPC.Provox

Version 2.0.642

Vendor Information Emerson Process Management PROVOX OPC Data Server Version 2.2


Notes OPC datatype of Items does not match native PROVOX datatype for all items, which can result in unexpected PI pointtype for available points.Information for EngUnits, Zero, and Span is not present for all Items.

64

Westinghouse Ovation

ProgID WDPF.OPC.4

Version 2.0.1

Vendor Information WDPF OPC Server from Emerson Process Management


Notes

Fluke

ProgID Fluke.DAQ.OPC

Version 6.1.1012

Vendor Information Studio Scada OPC Server v6.10


Notes

Foxboro

AIM

ProgID AIM.OPC.1

Version 1.349.34321

Vendor Information The Foxboro Company

Sync-able Attributes Descriptor (opchst items only)EngUnits (opchst items only)Zero (non-opchst items only)Span (non-opchst items only)

Notes ItemIDs contain “\” which is illegal in PI tag names.ItemIDs can appear more than once in the browse tree resulting in duplicate available points.ItemIDs ending with “opchst” appear to be historized items and have information for Descriptor and EngUnits but not for Zero and Span. Items not ending with “opchst” appear to be current-value only and have information for Zero and Span but not Descriptor or EngUnits.


OPC Server Surveys

GE Fanuc Automation Americas, Inc.

Intellution iFIX

ProgID Intellution.OPCiFIX.1

Version 4.5.6491

Vendor Information GE Fanuc Automation Americas, Inc.


Notes

Gesytec GmbH

ProgID Gesytec.ElonOPC2

Version 2.30.22

Vendor Information OPC Server by Gesytec GmbH


Notes ItemIDs can contain square brackets that are illegal in PI tag names.

Honeywell

Total Plant Network

ProgID hci.tpnserver

Version 212.1.30700

Vendor Information Honeywell IAC.


Notes OPC Server has throughput limitations.Some OPC calls are very slow, resulting in synchronization requiring up to 30 seconds per point.Extreme care must be taken when using APS for OPC with this server.

Uniformance PHD OPC DA 3.00/HDA 1.2 Server

ProgID OPC.PHDServerDA.1

Version 210.0.0

Vendor Information Uniformance PHD OPC DA 3.00/HDA 1.2 Server


Notes

66

ICONICS

DataStore OPC-DA Server and DataStore OPC-AE Server

ProgID ICONICS.DataStoreOPCDA.3

Version 3.12.0

Vendor Information ICONICS DataStore OPC-DA Server and DataStore OPC-AE Server


Notes

ModbusEthernetDA and ModbusEthernetAE

ProgID ICONICS.ModbusEthernetDA.2

Version 3.12.0

Vendor Information ICONICS ModbusEthernetDA and ModbusEthernetAE


Notes Information for Zero and Span is not present for all Items.

ToolWorX OPC Server

ProgID ICONICS.OPCToolWorXDA.3

Version 3.12.0

Vendor Information ICONICS OPC ToolWorX OPC Server


Notes

InduSoft

ProgID studio.scada.opc

Version 6.1.1012

Vendor Information Studio Scada OPC Server v6.10


Notes

Intellution

See GE Fanuc Automation Americas, Inc.


OPC Server Surveys

Invensys

DasABCIP

ProgID archestrA.DASABCIP.4

Version 4.0.0

Vendor Information Invensys (DasABCIP0399_MaintBuild_0015)


Notes

DasABTCP

ProgID archestra.dasabtcp.1

Version 154.126.0

Vendor Information Wonderware


Notes

DasGESRTP

ProgID ArchestrA.DASGESRTP.1

Version 1.0.182



Notes

DASMBSerial

ProgID ArchestrA.DASMBSerial.2

Version 198.126.0



Notes

DASMBTCP

ProgID ArchestrA.DASMBTCP.1

Version 1.0.246

Vendor Information Invensys (MBTCP_MasterBuild_v0246)


Notes

68

DASMTEthernet

ProgID ArchestrA.DASMTEthernet.1

Version 1.0.1



Notes

DASOMFINSEnet

ProgID ArchestrA.DASOMFINSEnet.1

Version 1.0.1



Notes

FSGateway

ProgID ArchestrA.FSGateway.1

Version 1.0.1

Vendor Information FSGatewayServer Vendor Name


Notes

SIDirect

ProgID archestrA.DASSIDIRECT.1

Version 1.0.244

Vendor Information Invensys (SIDirect_MasterBuild_v0244)


Notes

Kassl GmbH

ProgID OPCSample.OpcDa20Server.1.Clone

Version 1.3.59

Vendor Information (C) 2004 Kassl GmbH (http://www.kassl.de)


Notes Information for Zero and Span is not present for all Items.Some ItemIDs contain illegal PI tagname characters “[” and “]”.


OPC Server Surveys

KEPware

ProgID KEPware.KEPServerEx.V4

Version 4.270.416

Vendor Information KEPware


Notes Scaling must be configured for an item to have properties for EngUnits, Zero, and Span.

Kongsberg

Maritime

ProgID KM.HS-OPC-DA.1

Version 2.1.0

Vendor Information Kongsberg Maritime


Notes Flat namespace

SIMRAD

ProgID KongsbergSimrad.Hs-Export.1

Version 2.1.0

Vendor Information Kongsberg Maritime


Notes

Krones

ProgID Krones.LDSOpcDaServer.1

Version 1.0.3

Vendor Information KRONES LDS OPC Data Access Server



70

KW

ProgID opc.out.pcos.21

Version 1.11.0

Vendor Information KW


Notes

Matrikon Inc.

Desktop Historian

ProgID matrikon.opc.desktophistorian.1

Version 1.3.0

Vendor Information Matrikon Inc. (780) 448-1010 http://www.matrikon.com


Notes

Universal

ProgID Matrikon.OPC.Universal

Version 1.1.307

Vendor Information Matrikon Inc (780) 448-1010 http://www.matrikonopc.com

Sync-able Attributes DescriptorZeroSpan

Notes Information for Descriptor, Zero, and Span is not present for all Items.

Mitsubishi

For Mitsubishi MELSEC, see Takebishi Electric.

MX OPC Server

ProgID Mitsubishi.MXOPC.6

Version 5..0.0

Vendor Information MITSUBISHI MXOPCServer


Notes


http://www.matrikonopc.com/

http://www.matrikon.com/

OPC Server Surveys

MSIndustrie Software GmbH

NICE OPC.NET Data Access Server

ProgID msi.msiopcserverw

Version 1.1.7

Vendor Information MSI-NICE OPC.NET Data Access Server


Notes

OPC Data Access Server

ProgID msi.msiopcserverw

Version 1.1.7

Vendor Information MSI-OPC Data Access Server


Notes

OPC Data Access Server (PMA)

ProgID msi.opcserverPMA

Version 1.1.7

Vendor Information MSI-OPC Data Access Server (PMA)


Notes

Northern Dynamic Inc.

ProgID ndi.vbsimplesvr.1

Version 4.12.149

Vendor Information Northern Dynamic Inc.


Notes

OMRON

For OMRON SYSMAC, see Takebishi Electric.

72

Phoenix Contact GmbH & Co. KG

ProgID PhoenixContact.Interbus.

Version 2.13.2

Vendor Information Phoenix Contact GmbH & Co. KG


Notes

PiiGAB

ProgID PiiGAB.Mbus.2

Version 1.0.1

Vendor Information PiiGAB



Power Measurement

ION

ProgID ION.OpcDaServer

Version 5.5.200

Vendor Information Power Measurement


Notes

Pressco Technology, Inc.

ProgID Pressco.Intellispec.OPC.1.DA

Version 1.0.1

Vendor Information Pressco Technology, Inc.




OPC Server Surveys

Progea srl

ProgID MovServer

Version 0.0.0

Vendor Information Progea srl Modena Italy, http://www.progea.com


Notes

Rockwell Software

FactoryTalk

ProgID factorytalk Gateway

Version 3.1.5000

Vendor Information FactoryTalk Gateway


Notes ItemIDs contain illegal PI tag name characters “[“ and “]”.

RnaDa Client Services

ProgID RSOPC Gateway

Version 0.1.0

Vendor Information Rockwell Software RnaDa Client Services



RSLinx OPC Server

ProgID RSLinx OPC Server

Version 2.42.18

Vendor Information Rockwell Software RSLinx OPC Server



RoviSys Company

ProgID rovisys.opc90server

Version 4.3.1

Vendor Information OPC90 Server by The RoviSys Company


Notes

74

Siemens AG

IndustrialDataBridge

ProgID OPC.IndustrialDataBridge.1

Version 2.1.221

Vendor Information Siemens AG


Notes

RMOS3_DA

ProgID OPC.RMOS3_DA.1

Version 3.4.531

Vendor Information Siemens AG


Notes

SIMATIC NET OPC-Server DataAccess-V1.0A/2.05/3.0

ProgID opc.simaticnet

Version 3.6.12501

Vendor Information SIMATIC NET OPC-Server DataAccess-V1.0A/2.05/3.0 DataExchange-V1.0 (C) SIEMENS AG 2007


Notes

Simatic® S7-200 PC Access© OPC-Server DataAccess-V1.0A/2.05/3.0

ProgID S7200.OPCServer

Version 3.1.60

Vendor Information Simatic® S7-200 PC Access© OPC-Server DataAccess-V1.0A/2.05/3.0

Sync-able Attributes DescriptorZeroSpan

Notes

SIMATIC WinCC flexible RT OPC-Server

ProgID OPC.SimaticHMI.HmiRTm

Version 3.7.11901

Vendor Information SIMATIC WinCC flexible RT OPC-Server V1.0 (C) Siemens AG (2003)


Notes


OPC Server Surveys

SIMATIC WinCC OPC-Server DataAccess V3.7

ProgID OPCServer.WinCC.1

Version 3.7.11801

Vendor Information SIMATIC WinCC OPC-Server DataAccess V3.7 Copyright (C) 2004-2008 SIEMENS AG; OPC DA 2.05A/3.00 Specification


Notes ItemIDs can appear more than once in the browse tree resulting in duplicate available points.

SIMATIC XML DA Wrapper OPC-Server

ProgID OPC.Siemens.XML

Version 3.7.11901

Vendor Information Siemens SIMATIC XML DA Wrapper OPC-Server


Notes ItemIDs may contain illegal PI tag name character “;”.

SISCO, Inc.

AX-S4 ICCP

ProgID SISCO.AXS4ICCP.3

Version 3.1.59

Vendor Information AX-S4 ICCP OPC Server by SISCO, Inc


Notes

AX-S4 MMS

ProgID sisco.axs4mms.5

Version 5.10.5

Vendor Information AX-S4 MMS OPC Server by SISCO, Inc


Notes

76

Smar

Smar OPC & Conf Server for HSE

ProgID Smar.hseoleserver.0

Version 5.0.5

Vendor Information Smar OPC & Conf Server for HSE


Notes

Smar SNMP OPC Server for DFI302

ProgID smar.snmpopcserver.0

Version 1.3.0

Vendor Information Smar SNMP OPC Server for DFI302


Notes

Softing AG

PROFIBUS OPC Server

ProgID Softing.OPC_PROFIBUS_DPV1.1

Version 2.7.210

Vendor Information Softing PROFIBUS OPC Server


Notes

softing.OPC.Bridge

ProgID softing.OPC.Bridge

Version 1.20.19

Vendor Information Softing AG



softing.OPC.Storage

ProgID softing.OPC.Storage

Version 1.10.14



Notes


OPC Server Surveys

softing.OPC.Tunnel

ProgID softing.OPC.Tunnel

Version 1.20.19



Notes

Software Toolbox

OmniServer

ProgID swtoolbox.omniserver

Version 2.5.3

Vendor Information Software Toolbox, Inc.


Notes Information for attributes is not present for all Items.

TOP Server

ProgID SWToolbox.TOPServer

Version 4.270.416

Vendor Information Software Toolbox



Takebishi Electric

DeviceXPlorer OPC Server

ProgID takebishi.dxp.1

Version 4.1.3

Vendor Information DeviceXPlorer OPC Server by TAKEBISHI Corporation


Notes Information for EngUnits, Zero, and Span is not present for all Items.

78

Mitsubishi MELSEC

ProgID Takebishi.Melsec.1

Version 3.10.2

Vendor Information Mitsubishi MELSEC OPC Server by Takebishi Electric



OMRON SYSMAC OPC Server

ProgID Takebishi.Sysmac.1

Version 3.10.2

Vendor Information OMRON SYSMAC OPC Server by Takebishi Electric



TOYOPUC OPC Server

ProgID Takebishi.Toyopuc.1

Version 3.10.2

Vendor Information TOYOPUC OPC Server by Takebishi Electric



Yokogawa FA-M3R OPC Server

ProgID Takebishi.FAM3.1

Version 3.10.2

Vendor Information Yokogawa FA-M3R OPC Server by Takebishi Electric




OPC Server Surveys

Technosoftware AG

opcswift.sample.30

ProgID opcswift.sample.30

Version 3.0.1

Vendor Information Technosoftware AG


Notes Some ItemIDs contain illegal PI tagname characters “[” and “]”.

tsopcnet.daserver.1

ProgID tsopcnet.daserver.1

Version 1.0.0

Vendor Information OPC Server Framework .NET Sample Data Access Server


Notes Some ItemIDs contain illegal PI tagname characters “[” and “]”.Information for Zero and Span is not present for all Items.

tsopcsource.datasample.40

ProgID tsopcsource.datasample.40

Version 4.0.2

Vendor Information Technosoftware AG


Notes Some ItemIDs contain illegal PI tagname characters “[” and “]”.Information for Zero and Span is not present for all Items.

Westinghouse

For Ovation, see Emerson Process Management.

Wonderware

For Wonderware, see Invensys.

80

Woodhead

DeviceNet OPC Server

ProgID Woodhead.DnOpcServer

Version 1.3.6

Vendor Information Woodhead DeviceNet OPC server v1.3.6


Notes

NetDoctor for DeviceNet OPC Server

ProgID molex.netdocdnopcserver.1

Version 1.4.0

Vendor Information NetDoctor for DeviceNet OPC Server v1.4.0


Notes

Profibus OPC Server

ProgID woodhead.pfbopcserver.1

Version 1.3.6

Vendor Information Woodhead Profibus OPC server v1.3.6


Notes

Yokogawa

Exaquantum

ProgID Yokogawa.ExaopcDAEXQ.1

Version 2.0.1

Vendor Information Yokogawa Electric Corporation



Yokogawa FA-M3R

For Yokogawa FA-M3R, see Takebishi Electric.


Appendix D. Technical Support and Resources

You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:

http://techsupport.osisoft.com (http://techsupport.osisoft.com)

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The log file(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.

Office Location Access Number Local Language OptionsSan Leandro, CA, USA 1 510 297 5828 English

Philadelphia, PA, USA 1 215 606 0705 English

Johnson City, TN, USA 1 423 610 3800 English

Montreal, QC, Canada 1 514 493 0663 English, French

Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese

Frankfurt, Germany 49 6047 989 333 English, German

Manama, Bahrain 973 1758 4429 English, Arabic

Singapore 65 6391 181186 021 2327 8686

English, MandarinMandarin

Perth, WA, Australia 61 8 9282 9220 English


http://techsupport.osisoft.com/

Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.

If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.

If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, point to Knowledge Center, and then click Search Support.

Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

[email protected]

When contacting OSIsoft Technical Support by email, it is helpful to send the following information:

Description of issue: Short description of issue, symptoms, informational or error messages, history of issue

Log files: See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, point to My Support, and then click My Calls.

Using OSIsoft’s Online Technical Support, you can:

Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)

View or edit existing OSIsoft calls that you entered

View any of the calls entered by your organization or site, if enabled

See your licensed software and dates of your Service Reliance Program agreements


mailto:[email protected]

Remote Access

From the OSIsoft Technical Support Web site, point to Contact Us, and then click Remote Support Options.

OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.

On-site Service

From the OSIsoft Technical Support Web site, point to Contact Us, and then click On-site Field Service Visit.

OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.

The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.

The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).

System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, point to Contact Us, and then click Obtaining Upgrades.

You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support (http://techsupport.osisoft.com / ) for assistance.

OSIsoft Virtual Campus (vCampus)

The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that focuses on PI System development and integration. The Web site's annual online subscriptions provide customers with software downloads, resources that include a personal development PI System, online library, technical webinars, online training, and community-oriented features such as blogs and discussion forums.


http://techsupport.osisoft.com/

Technical Support and Resources

OSIsoft vCampus is intended to facilitate and encourage communication around PI programming and integration between OSIsoft partners, customers and employees. See the OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or contact the OSIsoft vCampus team at [email protected] for more information.

86

http://vCampus.osisoft.com/

Appendix E. Revision History

Date Author Comments

28-Sep-2002 BYoung Initial Documentation

25-Nov-2002 BYoung Added Appendix A

09-Dec-2002 BYoung Updated Appendix A, added drawing of configuration.

17-Mar-2003 BYoung Updated version to 1.1.0.0

25-Mar-2003 BYoung Version 1.1.0.2. Added Tag Name Masking section.

22-Feb-2005 LDaley Revised the Installation Instructions and Configuration Instructions sections. Rewrote the section on the connector specific configuration control.

10-Aug-2005 Chrys Version 1.1.0.8 – 1.1.0.10: Changed title of document; fixed TOC; fixed headers and footers; applied a different template

02-Dec-2005 LDaley Version 1.1.0.11: Revised discussion of Tag Filter to describe new behavior of matching on full ItemID. Expanded the Troubleshooting section with new symptoms. Revised Appendix A.

21-Dec-2005 Janelle Version 1.1.0.11 Rev B: fixed headers and footers, formatting.

04-Jan-2006 LDaley Version 1.1.0.11 Rev C: Added Appendix B. Added NT-specific version of reg_OPCInt_APS to Appendix A.

09-Jan-2006 MKelly Version 1.1.0.11 Rev D: Made several changes. Changed title of document, copyright page.

12-Jan-2006 Chrys Version 1.1.0.11 Rev E: Formatting and grammar changes

18-Jan-2006 LDaley Version 1.1.0.12 Rev A: Changed title page version line. Corrected grammar and punctuation in body text.

6-Feb-2006 Janelle Version 1.1.0.12 Rev B: fixed page numbering in Table of Contents, fixed hyperlinks in document.

7-Feb-2006 LDaley Version 1.1.0.12 Rev C: Restored bookmark to correct location and refreshed the document.

08-Feb-2011 LDaley Version 1.2.0.0. Migrated content into skeleton version 1.5.2. Newer versions of Windows are supported and the .NET prerequisite changes from .NET 1.1 to .NET 3.5.


OPC DA Interface AutoPointSync Connector - OSIsoftcdn.osisoft.com/interfaces/1703/PI_OPCInt_APS_1.2.0.0.… · Web viewOPC DA Interface AutoPointSync Connector. ... (PI_OPCInt.docx)

Documents